企业官网建设流程全解析

1. 先搞清楚这个标题到底在说什么

一个人，九个月，20 万行代码，每个月烧掉 40 亿+ token，最终交付的是一款 Harness 架构应用。这几个数字摆在一起，任何一个写过代码的人都会先愣一下：20 万行代码是什么概念？如果按一个熟练工程师每天有效产出 200 到 300 行可维护代码来算，20 万行差不多是两到三个人干一整年的量。而这里只有一个人，时间只有九个月，中间还夹着每月 40 亿 token 的模型调用量。这不是一个"我用 AI 写了个小工具"的故事，而是一个"我把 AI 当成一支工程团队来调度"的完整实践。

先把几个核心词拆开讲清楚，不然后面没法聊。Harness这个词在工程语境里本意是"线束、挽具"，引申到软件领域，指的是一套把底层能力（模型、工具、执行环境）包裹起来、统一调度、统一约束的外壳层。你可以把它理解成马具：马本身力气很大，但你不给它套上挽具、缰绳、轭，它拉不动车，也走不直。Harness 架构应用，就是给大模型这匹"烈马"套上一整套可控的工程外壳，让它能稳定地完成复杂任务，而不是每次对话都从零开始即兴发挥。

Agent在这里不是营销词，而是指具备"感知—规划—执行—反馈"闭环的自动化执行体。Claude Code是这类 Agent 在终端环境里的一个典型形态，它把文件读写、命令执行、代码检索这些能力封装成模型可以调用的工具。Obsidian则是本地知识库的代表，基于 Markdown 文件组织内容，天然适合做 Agent 的长期记忆载体和产出容器。Markdown在这里不只是排版语法，而是人和 Agent 之间最省事的交换格式——纯文本、结构清晰、diff 友好、任何工具都能读写。

所以这个项目的本质是：用一套 Harness 架构，把 Claude Code 这类 Agent 能力、Obsidian 这类本地知识库、Markdown 这类通用交换格式串成一条流水线，让一个人借助每月 40 亿 token 的模型算力，在九个月里产出 20 万行规模的可用代码。这篇文章要讲的，就是这套东西为什么能成立、架构怎么搭、钱花在哪、坑埋在哪，以及一个普通开发者想复现的话该从哪下手。

适合谁看？如果你已经在用 Claude Code 或者类似的终端 Agent，但总觉得"它能干活但干不长、干不稳"，那这篇对你有用。如果你还在纠结要不要入局 Agent 开发，这篇能帮你判断投入产出比。如果你只是想了解 Harness 架构到底是个啥，前面这段已经给了你答案，后面是给真要动手的人看的。

2. 为什么是 Harness 架构，而不是直接堆 Prompt

2.1 裸用大模型的三个死穴

大多数人用大模型的方式是：打开对话框，把需求描述一遍，等它输出，不满意就再补一句"再改改"。这种方式在单次、短任务上没问题，但一旦任务跨度拉长到几天、几周，三个问题会立刻暴露。

第一个死穴是上下文漂移。模型没有真正的长期记忆，你这次对话里建立的约定，下次开新会话就全丢了。你昨天让它"所有 API 返回统一用 Result 包装"，今天它照样给你返回裸对象。你不可能每次都把几百条约定重新贴一遍，token 成本先不说，模型注意力也会被稀释。

第二个死穴是执行不可控。模型说"我已经修改了文件"，但它可能只是"以为"自己改了，或者改错了地方。没有真实的文件系统反馈、没有命令执行结果回灌，模型就是在闭着眼睛开车。

第三个死穴是产出不可复现。同一个需求问两次，得到两套完全不同的实现。对于一次性脚本无所谓，对于要长期维护的 20 万行代码库，这是灾难。

Harness 架构存在的意义，就是把这三点逐个堵死。它不是让模型变聪明，而是让模型的行为变得可约束、可观测、可复现。

2.2 Harness 到底"套"住了什么

一套完整的 Harness，通常包含四层约束。我用一个实际项目里的结构来说明，你可以对照自己的场景调整。

这四层里，记忆层和校验层是大多数人会忽略、但决定项目能不能撑到 20 万行的关键。工具层和编排层决定了 Agent 能不能干活，记忆层和校验层决定了它干的活能不能攒起来。

2.3 为什么选 Markdown + Obsidian 做记忆载体

记忆层可以用数据库、可以用向量库，为什么这个项目选了 Markdown 文件加 Obsidian？理由很实在。

Markdown 是纯文本，意味着模型读写它几乎零摩擦。你让模型输出 JSON，它偶尔会多一个逗号导致解析失败；你让它输出 Markdown，它天然就擅长，而且格式错了也不影响人读。更重要的是，Markdown 的 diff 极其干净，你随时能看出 Agent 这次到底改了什么，这在排查"它为什么把上周的约定忘了"时是救命的。

Obsidian 的价值在于双链和本地索引。20 万行代码的项目，约定和决策文档轻松上千篇。Obsidian 的[[双向链接]]让这些文档形成网状结构，Agent 检索时可以先定位到核心节点，再顺着链接展开，比全文向量检索精准得多。而且 Obsidian 库就是一堆本地文件夹，Agent 用普通的文件读写工具就能操作，不需要额外起服务。

提示：如果你不用 Obsidian，任何支持纯文本 + 目录结构的编辑器都能替代，核心是"文件即记忆"，而不是"数据库即记忆"。数据库对模型不友好，对调试也不友好。

2.4 40 亿 token 一个月，钱到底花在哪

这是最容易被误读的数字。40 亿 token 不是"一个月写了 40 亿 token 的代码"，而是整个 Harness 循环里所有模型调用的输入输出总和。拆开看，大头在三处。

第一处是上下文重放。每次 Agent 执行一个任务，都要把相关的项目约定、文件内容、历史决策重新喂进去。一个中等复杂度的任务，输入轻松到几万 token。如果一天跑几百个任务，光输入就是几亿 token。

第二处是多轮校验循环。Agent 写完代码，跑测试，失败，读错误，改，再跑。这个循环平均要转三到五轮。每一轮都是一次完整的模型调用，token 消耗直接乘以轮数。

第三处是子 Agent 并行。为了提速，复杂任务会拆给多个子 Agent 并行处理，每个子 Agent 都有自己的上下文。并行度越高，总 token 消耗越大，但墙钟时间越短。

所以 40 亿 token 换来的不是 40 亿 token 的产出，而是九个月里持续不断的自动化执行。按主流模型的定价粗算，这笔账能不能算得过来，取决于你替代掉的人力成本。一个人九个月产出 20 万行，如果按外包或招聘来算，成本远高于 token 费用，这才是这套架构真正的经济性来源。

3. 九个月 20 万行，工程上是怎么组织的

3.1 代码库的分层与 Agent 的"势力范围"

20 万行代码如果让 Agent 随便写，三个月就会变成一团泥。这个项目能撑下来，靠的是严格的分层和明确的势力范围。每一层有独立的目录、独立的约定文档、独立的测试策略，Agent 在某一层工作时，只能看到这一层及其依赖的接口，看不到其他层的实现细节。

具体做法是：在 Obsidian 库里为每个模块建一篇"契约文档"，写清楚这个模块对外暴露什么、依赖什么、不允许做什么。Agent 接到任务时，Harness 先把契约文档喂给它，再给它这个模块目录的读写权限。这样它就不会"顺手"去改别的模块，也不会因为看不到全局而乱猜接口。

这套做法的直接收益是上下文可控。Agent 每次只需要加载当前模块的契约和代码，而不是整个 20 万行。token 消耗降下来了，模型注意力也集中了，出错率明显下降。

3.2 任务拆解的粒度：为什么"一个任务一次提交"

Agent 最容易翻车的地方是任务太大。你让它"实现用户模块"，它会给你一个能跑但处处是坑的半成品。这个项目采用的原则是：一个任务对应一次可独立验证的提交。

什么叫可独立验证？就是这个任务做完，能跑一个明确的命令，得到一个明确的通过或失败结果。比如"给 UserService 加一个按邮箱查用户的方法，并补上单元测试"，做完之后跑pytest tests/test_user_service.py，绿了就过，红了就打回。

粒度控制在"一个方法到一个小功能"之间。太细了，Agent 调度开销占比过高；太粗了，校验层没法给出明确反馈。实践中，一个任务对应的代码改动量在 50 到 300 行之间比较合适。

3.3 校验层：让 Agent 自己知道自己错了

校验层是整个 Harness 里最值得投入的部分。它的职责不是"帮 Agent 改代码"，而是"告诉 Agent 哪里错了"。这个项目里校验层分三级。

第一级是静态检查，包括类型检查、lint、格式检查。这一级最快，几秒钟出结果，能挡掉大量低级错误。

第二级是单元测试。每个模块的契约文档里都规定了必须覆盖的场景，Agent 写完代码必须补测试，测试不过直接打回。

第三级是集成验证。这一级最慢，通常只在关键节点跑，验证多个模块拼起来能不能正常工作。

三级校验的反馈会原样回灌给 Agent，让它自己修。这里有个关键细节：错误信息要原样回灌，不要人工总结。你总结成"测试失败了"，Agent 不知道哪失败；你把完整的报错栈贴回去，它往往能自己定位。这个项目里，Agent 一次修复成功率在 70% 以上，靠的就是完整反馈。

3.4 记忆的写入时机：什么时候该记，什么时候不该记

记忆层不是记得越多越好。记太多，检索时噪音大；记太少，约定丢失。这个项目的规则是：只有被验证过的决策才写入长期记忆。

具体来说，Agent 在任务过程中产生的临时想法、试错过程，不写入。只有当某个决策通过了校验、并且被证明在后续任务中可复用，才由 Harness 自动提炼成一篇 Markdown 文档，写入 Obsidian 库，并在相关模块的契约文档里加一条链接。

这条规则的价值在于记忆的质量。20 万行代码的项目，如果每一条临时想法都记下来，记忆库会膨胀到无法检索。只记验证过的，记忆库始终保持在"高信噪比"状态，Agent 检索时命中率才高。

4. 每月 40 亿 token 的调度细节与成本控制

4.1 上下文预算：给每个任务划一条线

40 亿 token 听起来多，但如果不控制，一个任务就能烧掉几百万。这个项目给每个任务设了上下文预算，超过预算就强制截断或拆分。

预算的分配逻辑是这样的：契约文档占 20%，相关代码占 50%，历史决策占 20%，剩余 10% 留给模型输出。这个比例不是拍脑袋定的，是实测调出来的。契约文档给太少，Agent 会违反约定；给太多，挤占代码空间。代码给太少，Agent 看不到足够上下文；给太多，模型注意力分散。

注意：上下文预算不是硬性截断，而是优先级排序。当预算不够时，先砍历史决策，再砍非核心代码，契约文档永远保留。因为契约是底线，违反了契约的代码再漂亮也是废的。

4.2 缓存与复用：哪些调用可以省

token 成本的大头在输入，而输入里有大量重复内容。这个项目用了两层缓存来省钱。

第一层是前缀缓存。很多模型服务支持对相同前缀的输入做缓存，命中后输入成本大幅下降。Harness 在组织上下文时，会把不变的部分（契约文档、项目全局约定）放在最前面，变化的部分（当前任务、相关代码）放在后面。这样前缀缓存命中率能到 60% 以上。

第二层是结果复用。某些查询类任务，比如"这个函数在哪里被调用"，结果在一段时间内是稳定的。Harness 会把这类结果缓存起来，短时间内重复查询直接返回缓存，不再调模型。

这两层加起来，实测能把 token 成本压掉三到四成。对于每月 40 亿 token 的规模，这是实打实的钱。

4.3 失败重试的代价：为什么"重试"要设上限

Agent 失败重试是常态，但重试是有代价的。每一次重试都是一次完整的模型调用，而且往往带着更长的上下文（因为要包含上次失败的信息）。如果不设上限，一个卡住的任务能烧掉几十万 token 还出不来。

这个项目给每个任务设了重试上限：三次。三次还不过，任务标记为"需要人工介入"，从队列里摘出来，不再自动重试。人工介入时，人只需要看一眼失败原因，往往几秒钟就能判断是任务描述有问题还是代码库有问题，改一下再放回队列。

这条规则救过很多次命。有一次一个任务因为契约文档里一个笔误，Agent 怎么改都过不了校验，自动重试三次后停下，人工一看就发现了笔误，改完一次通过。如果让它无限重试，可能烧掉上百万 token 还在原地打转。

4.4 子 Agent 并行的收益与风险

并行是提速的关键，但并行度不是越高越好。这个项目的经验是：并行度控制在 3 到 5 之间。

低于 3，提速不明显；高于 5，收益递减，而且风险上升。风险主要有两个：一是资源竞争，多个子 Agent 同时读写同一批文件，容易冲突；二是上下文不一致，多个子 Agent 各自基于不同的上下文做决策，合并时可能矛盾。

控制风险的办法是任务隔离。并行的子 Agent 必须操作互不重叠的文件集合，如果两个任务可能碰到同一个文件，就串行执行。Harness 在调度时会做依赖分析，自动判断哪些任务可以并行。

5. 从零复现这套架构的实操路径

5.1 环境准备：最小可用组合

想复现这套东西，不需要一上来就搞全套。最小可用组合是：一个终端 Agent（Claude Code 或同类）、一个本地 Markdown 库（Obsidian 或任意文件夹）、一套校验脚本（测试 + lint）。

安装 Claude Code 的流程这里不展开，官方文档写得很清楚。重点说两个容易忽略的配置。

第一个是工作目录的隔离。不要让 Agent 在你的主目录或者整个项目根目录下工作，给它一个专门的子目录，通过配置限制它的读写范围。这样即使它犯错，影响面也可控。

第二个是工具权限的白名单。Agent 能调用的命令要明确列出，尤其是删除、覆盖、网络请求这类危险操作，默认关闭，需要时手动开。这个项目里，Agent 默认只能读文件、写指定目录、跑测试命令，其他一律禁止。

5.2 契约文档的写法：给 Agent 看的文档和给人看的不一样

给 Agent 写契约文档，最大的误区是写成给人看的 API 文档。人看文档会脑补，Agent 不会。所以契约文档要显式、无歧义、带反例。

一个好的契约文档长这样：先写这个模块的职责一句话，再写对外接口的完整签名，然后写三条"必须遵守"和三条"绝对禁止"，最后附两个正例和两个反例。反例特别重要，Agent 对"不要做什么"的理解远不如对"要做什么"的理解，给反例能显著降低违规率。

文档用 Markdown 写，放在 Obsidian 库里，用双链关联到相关模块。每次 Agent 接任务，Harness 自动把对应契约文档注入上下文。

5.3 校验脚本的搭建：先有反馈，再谈智能

很多人搭 Harness 时先折腾编排和记忆，忽略了校验。结果 Agent 干了一堆活，没人知道对不对，最后全靠人工 review，自动化程度上不去。

正确的顺序是先搭校验，再搭编排。校验脚本不需要复杂，一个跑测试的脚本、一个跑 lint 的脚本、一个跑类型检查的脚本，三个加起来几十行。关键是它们要能输出结构化的、Agent 能读懂的错误信息。

测试框架选你熟悉的就行，重点是测试用例要覆盖契约文档里规定的场景。lint 和类型检查用社区标准配置，不要自己造轮子。这三个脚本跑通之后，Harness 的校验层就有了，Agent 的产出立刻变得可判断。

5.4 编排逻辑：状态机比工作流更适合 Agent

编排层有两种常见做法：工作流（workflow）和状态机（state machine）。这个项目选了状态机，理由是Agent 的执行路径是不确定的，工作流那种"步骤 A 完了走步骤 B"的线性结构，遇到 Agent 需要回退、重试、分支时就很难表达。

状态机的核心是定义几个状态：待处理、执行中、校验中、待修复、已完成、需人工。每个状态之间的转移条件写清楚，比如"校验通过 → 已完成"、"校验失败且重试次数小于三 → 待修复"、"重试次数达到三 → 需人工"。

状态机的好处是可观测。你随时能查当前有多少任务在哪个状态，卡在哪里，一目了然。工作流跑到一半卡住，你往往要翻日志才知道发生了什么。

5.5 从单任务到批量：什么时候该扩规模

不要一上来就批量跑。先用单任务模式跑通十个任务，确认校验层能正确判断、记忆层能正确写入、成本在可接受范围，再考虑批量。

扩规模的信号是：单任务模式下，你发现自己在重复做同样的调度动作，比如"手动把契约文档贴进去""手动跑校验脚本""手动判断要不要重试"。这些动作一旦重复超过五次，就该自动化了。

批量模式的核心是队列 + 调度器。任务进队列，调度器按依赖关系和并行度取任务，分配给 Agent 执行，执行结果回写队列。这个项目里，队列用最简单的文件队列实现，每个任务一个 Markdown 文件，状态写在文件头，调度器就是一段轮询脚本。简单，但够用。

6. 踩过的坑和实测有效的经验

6.1 记忆库膨胀：从 200 篇到 2000 篇的失控

项目进行到第四个月时，Obsidian 库里的文档从 200 篇涨到了 2000 篇。Agent 检索时开始频繁命中无关文档，上下文里塞满了噪音，任务成功率明显下降。

排查后发现，问题出在记忆写入没有门槛。早期为了"不丢信息"，Agent 产生的任何决策都写入记忆库，结果大量临时性、一次性的决策也进去了。这些文档单独看没问题，但放在一起就稀释了核心约定的权重。

修复方案是加了一道记忆准入规则：只有满足"被校验通过"且"在后续任务中被引用过至少一次"两个条件的决策，才允许写入长期记忆。其余的一律丢弃。加了这个规则后，记忆库稳定在 800 篇左右，检索命中率回升。

6.2 契约漂移：Agent 悄悄改了约定

有一次发现 Agent 在实现新功能时，悄悄改了一个已有接口的返回格式。测试没覆盖到这个接口，所以校验通过了。等到下游模块调用时才发现不兼容。

根因是契约文档和代码没有强绑定。契约文档写在 Obsidian 里，代码在另一个目录，Agent 改代码时不会自动检查契约。

修复方案是给契约文档加接口签名校验。Harness 在任务完成后，除了跑测试，还会跑一个脚本，提取代码里的接口签名，和契约文档里写的签名做比对，不一致就报错。这个脚本用正则加 AST 解析实现，不到一百行，但挡住了后续所有类似的漂移。

6.3 上下文截断导致的"失忆"

有一次一个复杂任务，Agent 执行到一半突然开始违反早期约定。排查发现是上下文预算不够，Harness 自动截断时把契约文档砍掉了。

这个问题暴露了截断策略的缺陷。早期策略是"按 token 数从后往前砍"，结果把最重要的契约文档砍了。

修复方案是分级截断。上下文分成三级：核心级（契约文档、全局约定）永不截断；重要级（相关代码、近期决策）优先保留；辅助级（历史决策、参考文档）优先截断。截断时从辅助级开始砍，砍完还不够才动重要级，核心级永远不动。

6.4 并行冲突：两个 Agent 改了同一个文件

并行提速的代价是冲突。有一次两个子 Agent 同时修改了一个工具类文件，合并时发现改动互相覆盖，丢了一部分逻辑。

根因是依赖分析不够细。早期的依赖分析只看模块级，两个任务属于不同模块就判定可并行，但它们可能都依赖同一个工具类。

修复方案是文件级依赖分析。Harness 在调度前，先扫描每个任务可能涉及的文件集合，有交集就串行。这个扫描基于任务描述和契约文档里的依赖声明，不需要精确到行，文件级就够了。加了这层之后，并行冲突基本消失。

6.5 成本监控：没有度量就没有控制

项目前两个月，token 消耗是笔糊涂账，只知道总数，不知道花在哪。第三个月开始做成本归因，给每个任务记录 token 消耗，按模块、按任务类型、按时间段汇总。

归因之后发现，80% 的 token 花在 20% 的任务上，而这些任务大多是"任务描述不清导致反复重试"的。于是针对性优化任务描述模板，强制要求写清楚验收标准，这部分任务的 token 消耗降了一半。

提示：成本监控不需要复杂工具，一个记录每次调用 token 数的日志文件，加一个汇总脚本就够了。关键是要记，不记就永远不知道钱花在哪。

6.6 人工介入的时机：什么时候该放手，什么时候该接管

全自动不等于最优。这个项目的经验是：明确划分自动区和人工区。

自动区是那些"验收标准明确、失败可自动判断"的任务，比如加一个方法、补一个测试、修一个 lint 错误。这些任务全自动跑，人不管。

人工区是那些"验收标准模糊、需要判断"的任务，比如架构调整、接口设计、性能优化。这些任务 Agent 可以出方案，但最终决策由人做。

划分清楚之后，人的精力集中在真正需要判断的地方，Agent 的算力集中在真正能自动化的地方，整体效率最高。试图让 Agent 做所有事，结果往往是人在后面擦屁股，比自己做还累。

7. 这套架构的边界与后续可扩展的方向

7.1 它擅长什么，不擅长什么

这套 Harness 架构在有明确验收标准、可自动校验的任务上表现极好。写 CRUD、补测试、重构、修 bug、写文档，这些任务 Agent 能独立完成，人只需要在最后 review 一下。

它在需要跨领域判断、验收标准模糊的任务上表现一般。比如"这个功能该不该做""这个架构选型合不合理"，Agent 能给出看起来合理的方案，但缺乏真正的判断力，容易在细节上翻车。

认清这个边界很重要。把 Agent 用在它擅长的地方，它是十倍效率工具；用在它不擅长的地方，它是十倍返工制造机。

7.2 从个人项目到团队协作的扩展点

这套架构目前是单人使用，扩展到团队需要解决三个问题。

第一是记忆库的共享与隔离。团队共享的约定放公共库，个人偏好放私有库，Harness 检索时合并。Obsidian 的库可以嵌套，天然支持这种结构。

第二是任务队列的并发控制。多人同时往队列里放任务，需要加锁和优先级。最简单的做法是每个任务一个文件，用文件锁控制写入，优先级写在文件头。

第三是成本的分摊与监控。团队使用后 token 消耗会上升，需要按人、按项目归因，避免有人滥用。这个在单人模式下不重要，团队模式下是刚需。

7.3 模型迭代带来的架构调整

模型能力在快速变化，Harness 架构需要跟着调整。这个项目九个月里换过两次底层模型，每次都要重新调上下文预算和校验策略。

经验是：把模型相关的配置集中管理。上下文预算、重试次数、并行度这些参数，不要散落在代码各处，集中在一个配置文件里。换模型时只改这个文件，不用翻遍整个项目。

另外，模型变强之后，某些校验层可以简化。比如早期模型经常写出类型错误，类型检查是必须的；新模型类型错误率大幅下降，类型检查可以从"每次必跑"改成"抽样跑"。这种调整能省下可观的 token。

7.4 一个值得尝试的扩展：让 Agent 参与架构决策

目前架构决策还是人在做，Agent 只负责执行。但有一个值得尝试的方向：让 Agent 在架构决策阶段提供方案对比和风险评估。

具体做法是，人提出架构问题，Harness 调度多个子 Agent 各自出一个方案，每个方案附带优缺点分析和风险点，然后人来做最终选择。这样人不用从零思考，只需要在几个成型方案里挑，决策效率会高很多。

这个方向还在试验中，初步效果是方案质量参差不齐，但偶尔能给出人没想到的角度。作为辅助工具是合格的，作为决策主体还差得远。

8. 最后分享几个实操中的小技巧

第一个技巧是给 Agent 写"任务模板"。每次派任务时，不要自由发挥，用固定模板：任务目标、验收标准、涉及文件、禁止事项。模板化之后，任务描述质量稳定，Agent 的理解偏差大幅减少。这个项目里，任务模板的引入让一次通过率从 50% 提到了 70% 以上。

第二个技巧是定期"体检"记忆库。每个月花半小时，扫一遍 Obsidian 库，把过时的、矛盾的、重复的文档清理掉。记忆库和人一样，不定期清理就会积累垃圾，检索效率越来越低。

第三个技巧是保留人工 review 的环节，但只 review 关键产出。不是每个任务都要人看，但涉及核心接口、数据模型、安全相关的改动，必须人过一眼。这个项目里，人工 review 的比例控制在 10% 左右，既保证了质量，又没有成为瓶颈。

第四个技巧是把失败案例存下来。每次 Agent 失败并且人工介入修复后，把失败原因和修复方法写成一篇短文档，存进记忆库。这些失败案例是后续任务的宝贵参考，Agent 遇到类似场景时能提前避开。这个项目里，失败案例库积累了三百多篇，是记忆库里最有价值的部分之一。

这套东西说到底，核心不是模型多强，而是工程约束做得多细。模型是马，Harness 是挽具，20 万行代码是车。马再壮，挽具不行，车也拉不动。反过来，挽具做好了，普通的马也能拉重车。九个月、一个人、20 万行，靠的不是奇迹，是把每一个约束都落到实处。