企业官网建设流程全解析

1. 这个项目到底在做什么：先把“Harness 架构应用”翻译成人话

一个人，九个月，二十万行代码，每个月消耗四十多亿 token，最终交付的是一款基于 Harness 架构的应用。这组数字第一次看到的时候，我盯着屏幕愣了几秒——不是因为二十万行代码有多夸张，而是“一个人”和“四十亿 token”这两个量级放在一起，说明这个人几乎把整个开发流程都外包给了 AI Agent，自己只负责架构决策、方向把控和最后的验收。这已经不是传统意义上的“写代码”，而是“指挥一支 AI 工程队”。

先把 Harness 这个词说清楚。在 AI Agent 开发的语境里，Harness 指的是包裹在大模型外面的一整套运行时框架——它负责管理上下文、调度工具调用、维护会话状态、处理错误重试、控制 token 预算、协调多个 Agent 之间的协作。你可以把它理解成汽车的底盘和传动系统：大模型是发动机，Harness 是把发动机的动力真正传导到轮子上的那套机械结构。没有 Harness，模型再强也只是一台空转的引擎；有了 Harness，它才能稳定地跑起来、转弯、刹车、载货。

这个项目之所以值得拆解，是因为它踩中了当下 AI 应用开发最核心的几个命题：如何让 Agent 长时间稳定运行而不失控、如何在 token 成本和质量之间找到平衡、如何用 Markdown 这类轻量格式承载复杂的知识结构、如何把 Claude Code、Obsidian 这类工具串成一条完整的工作流。这些命题不是理论问题，是每一个真正在做 Agent 项目的人每天都要面对的。

适合读这篇内容的人有三类。第一类是想从零搭建 Agent 应用的开发者，你需要知道 Harness 层到底要处理哪些脏活累活。第二类是在用 Claude Code、Obsidian 做知识管理和自动化的人，你想知道怎么把这些工具的能力边界推到更远。第三类是纯粹好奇“一个人怎么用 AI 干出二十万行代码”的从业者，你想看清楚这套工作流的真实成本和真实瓶颈在哪里。不管你是哪一类，接下来的内容都会围绕一个核心问题展开：当 AI 成为主要生产力，人的角色到底变成了什么。

2. 为什么是 Harness 架构：方案选型背后的真实考量

2.1 不用现成 Agent 框架，自己搭 Harness 的理由

市面上现成的 Agent 框架不少，从早期的 LangChain 到后来的各种 Agent 编排工具，开箱即用的东西很多。但这个项目选择自己搭 Harness，背后有几个很实际的考量。

第一是控制粒度。现成框架为了通用性，往往把很多决策封装在内部，你只能通过配置项去影响它。但当一个项目跑到二十万行代码、每月四十亿 token 的规模时，任何一个被封装掉的细节都可能变成成本黑洞。比如上下文裁剪策略，通用框架可能默认保留最近 N 轮对话，但你的项目可能需要根据任务类型动态决定保留哪些历史、丢弃哪些历史。这种级别的控制，只有自己写 Harness 才能做到。

第二是错误恢复。Agent 长时间运行最怕的不是单次调用失败，而是失败之后状态错乱。自己搭 Harness 可以把状态机设计成可回滚的，每一步操作都有明确的检查点和恢复路径。现成框架的错误处理往往是“重试三次然后放弃”，这在生产环境里是不够的。

第三是token 预算管理。四十亿 token 一个月是什么概念？按主流模型的定价粗略估算，这是一笔相当可观的月度支出。自己搭 Harness 可以在调用层面做精细的预算控制——哪些任务用强模型、哪些任务用轻量模型、哪些任务可以缓存结果不重复调用。这些优化在通用框架里很难做到极致。

提示：自己搭 Harness 不是因为它更简单，恰恰是因为它更难但更可控。如果你只是做一个 demo，用现成框架完全够用。但如果你要跑一个长期项目，Harness 层的自主权会决定你的成本上限和质量下限。

2.2 Harness 架构的核心分层设计

一个能扛住长期运行的 Harness，通常需要分成几层来设计。这个项目的架构思路，我根据常见实践和热词里透露的信息，还原成下面这个分层模型。

这个分层不是拍脑袋想出来的，而是被实际需求逼出来的。比如记忆层单独拆出来，是因为 Agent 运行时间一长，上下文管理就成了最大的瓶颈。你不能把所有历史都塞进 prompt，那样 token 消耗会爆炸；你也不能完全丢弃历史，那样 Agent 会失忆。所以需要一个独立的记忆层，用 Markdown 文件作为长期存储，按需检索、按需注入。

调度层用状态机驱动，是因为 Agent 执行任务时经常需要“暂停等待人工确认”或者“失败后从某个检查点恢复”。没有状态机，这些场景很难优雅处理。执行层的 token 预算控制，则是直接对应那每月四十亿的消耗——没有这层控制，成本会失控。

2.3 Markdown 作为核心数据格式的深层原因

热词里反复出现 Markdown 相关的搜索：markdown 换行、markdown 语法、markdown 表格转换 excel、markdown 表格复制、markdown 阅读器、markdown preview enhanced。这说明这个项目里 Markdown 不只是文档格式，而是核心的数据交换格式。

为什么选 Markdown？因为它是人和 AI 都能高效读写的最轻量格式。JSON 对机器友好但对人不够直观，富文本对友好但机器解析麻烦，Markdown 刚好在中间——结构清晰、纯文本、易于 diff、易于版本控制、易于被模型理解和生成。

在这个项目里，Markdown 承担了几个关键角色。第一是任务描述载体，每个任务用 Markdown 写清楚目标、输入、输出、约束条件。第二是知识存储格式，长期记忆以 Markdown 文件形式存在 Obsidian 库里，Agent 需要时读取相关文件。第三是结果输出格式，Agent 产出的内容以 Markdown 呈现，方便人工审阅和后续处理。

注意：Markdown 的换行和表格语法是高频踩坑点。不同解析器对换行的处理不一致，表格的列对齐和转义也有坑。在 Harness 里最好统一用一套解析库，并且在写入时做规范化处理，避免因为格式问题导致 Agent 读取失败。

3. 核心细节拆解：二十万行代码是怎么被“指挥”出来的

3.1 Claude Code 在流程中的真实定位

热词里 Claude Code 出现频率极高：claude code 安装、claude code 下载、claude code 使用、vscode 配置 claude code、vscode 安装 claude code、claude code desktop 国内下载。这说明 Claude Code 是这个项目的主力工具之一。

但 Claude Code 在这个项目里的定位，不是“自动写代码的机器人”，而是一个可以被 Harness 调度的执行单元。区别在于：如果你直接打开 Claude Code 让它写一个功能，它是被动的、一次性的；但如果你把 Claude Code 接入 Harness，让它接收结构化任务、返回结构化结果、失败时能被重试、成功时能被记录，它就变成了流水线上的一个工位。

具体怎么接入？常见做法是通过命令行调用或者 API 封装，把任务以 Markdown 格式传给 Claude Code，让它按照预设的模板输出代码和说明。Harness 负责在调用前后做上下文注入和结果校验。这样做的关键收益是可追溯——每一行代码是谁在什么上下文下生成的、经过了哪些校验、关联哪个任务，全部有记录。

这里有个实操心得：Claude Code 在长会话里容易“跑偏”，生成的内容越来越偏离初始目标。解决办法是在 Harness 里强制每次调用都重新注入核心约束，不要依赖会话历史来维持方向。宁可多花一点 token 做上下文重置，也不要让 Agent 在错误的方向上越走越远。

3.2 Obsidian 作为长期记忆库的用法

Obsidian 在这个项目里的角色是长期记忆的物理载体。热词里有 obsidian 教程、obsidian 下载、obsidian 安装、obsidian 插件推荐、obsidian 创建项目管理台账、obsidian 的 docxer 怎么用、codex obsidian、weknora 和 obsidian。这些搜索说明很多人在尝试把 Obsidian 接入 AI 工作流。

这个项目的做法，我推测是这样的：Obsidian 库里的每个 Markdown 文件代表一个知识单元，可能是项目文档、可能是历史决策记录、可能是代码片段库。Harness 的记忆层通过文件系统读取这些 Markdown，根据当前任务的相关性检索出需要的文件，注入到 Agent 的上下文里。

这样做的好处是记忆和推理分离。模型不需要把所有知识都记在参数里，它只需要在需要的时候读取相关文件。这大大降低了上下文压力，也让知识更新变得简单——改一个 Markdown 文件就行，不需要重新训练或微调。

实操中要注意的是检索策略。Obsidian 库文件一多，怎么快速找到相关文件就成了问题。常见做法是用文件名、标签、双向链接做索引，Harness 根据任务关键词匹配相关文件。更进阶的做法是用向量检索，把 Markdown 内容做 embedding，按语义相似度召回。但向量检索会增加复杂度和成本，项目早期用关键词匹配往往就够了。

提示：Obsidian 的双向链接功能在构建知识图谱时非常有用。在 Harness 里可以利用双向链接关系做上下文扩展——找到相关文件后，顺藤摸瓜把链接指向的文件也纳入上下文，往往能提供更完整的背景信息。

3.3 Agent 执行流程的完整拆解

一个任务从进入到完成，在 Harness 里通常要经过这些环节。我用一个具体的例子来说明：假设任务是“给项目添加一个用户配置模块”。

第一步是任务解析。Harness 接收到 Markdown 格式的任务描述，解析出目标、约束、预期输出。这一步要做的关键判断是：这个任务需要哪些上下文？是全新功能还是修改现有代码？涉及哪些文件？

第二步是上下文组装。根据任务解析结果，从记忆层检索相关文件——可能是现有的配置模块代码、可能是项目的架构文档、可能是之前的类似任务记录。把这些内容组装成 Agent 能理解的 prompt。

第三步是Agent 调度。选择合适的执行单元。简单任务用轻量模型，复杂任务用强模型。Claude Code 适合需要写代码的任务，其他 Agent 可能适合文档生成或代码审查。

第四步是执行与监控。Agent 开始工作，Harness 实时监控 token 消耗、执行时长、是否触发错误。如果超出预算或超时，触发中断和重试。

第五步是结果校验。Agent 返回结果后，Harness 要做基本校验——格式是否正确、是否包含预期内容、是否有明显错误。校验不通过则触发重试或人工介入。

第六步是记忆更新。任务完成后，把关键信息写回记忆层——更新项目文档、记录决策理由、保存代码片段。这样下一个相关任务就能用到这次的经验。

这个流程看起来步骤多，但每一步都是被实际问题逼出来的。少了任何一步，长期运行都会出问题。比如少了结果校验，错误会累积；少了记忆更新，Agent 会重复犯同样的错。

3.4 Token 消耗的构成与优化空间

每月四十亿 token，这个数字需要拆开看才能理解钱花在哪里了。粗略估算，token 消耗主要来自几个部分。

上下文注入占大头，这符合直觉——Agent 每次执行都需要大量背景信息。优化空间也主要在这里：检索越精准，注入的无关内容越少，token 消耗越低。这也是为什么记忆层的设计如此关键。

代码生成部分的优化思路是任务拆分。不要让 Agent 一次生成几百行代码，而是拆成多个小任务，每个任务生成一个函数或一个模块。这样单次生成的 token 量可控，出错也容易定位。

重试部分的优化靠提高首次成功率。这需要好的 prompt 设计、清晰的约束条件、充分的上下文。首次成功率从 70% 提升到 90%，重试消耗就能减少三分之二。

4. 实操过程还原：从零到二十万行的关键节点

4.1 项目启动阶段的架构决策

任何长期项目，启动阶段的决策都会影响后续所有工作。这个项目在启动时，有几个关键决策值得参考。

第一个决策是确定 Harness 的边界。哪些事情由 Harness 做，哪些事情交给 Agent 做，哪些事情人工做。边界不清会导致职责混乱——要么 Harness 管太多变得臃肿，要么 Agent 承担太多容易失控。常见的划分是：Harness 管流程、管状态、管预算；Agent 管具体的内容生成；人工管方向决策和最终验收。

第二个决策是确定数据格式。前面说了 Markdown 是核心格式，但具体怎么组织需要提前定好。任务描述用什么模板、知识文件用什么结构、代码片段怎么标注，这些都要在启动阶段定下来。后期再改格式，迁移成本很高。

第三个决策是确定工具链。Claude Code 负责代码生成，Obsidian 负责知识管理，可能还有其他工具负责测试、部署、监控。工具之间的接口要提前设计好，避免后期集成时发现对不上。

注意：启动阶段最容易犯的错是“先跑起来再说”。对于短期项目这没问题，但对于要跑九个月的项目，前期多花一周做架构设计，后期能省下几个月填坑的时间。

4.2 中期迭代中的成本控制实战

项目跑到中期，代码量上来之后，token 成本会成为最敏感的问题。这个阶段的核心工作是持续优化 token 效率。

一个有效的做法是建立 token 消耗的监控看板。按任务类型、按 Agent、按时间段统计 token 消耗，找出异常高的部分。比如某个类型的任务突然消耗飙升，可能是上下文注入出了问题，检索到了不相关的大文件。

另一个做法是缓存重复结果。很多任务在本质上是一样的，比如“检查代码风格”“生成单元测试”。这些任务的结果可以缓存，相同输入直接返回缓存结果，不重复调用模型。缓存命中率哪怕只有 20%，也能省下可观的 token。

还有一个做法是分级使用模型。不是所有任务都需要最强的模型。简单的格式转换、内容提取用轻量模型就够，只有复杂的推理和生成才用强模型。Harness 里可以根据任务类型自动路由到不同模型。

4.3 后期稳定性的保障措施

项目跑到后期，代码量大了，Agent 之间的依赖多了，稳定性就成了首要问题。这个阶段的重点是防止系统性崩溃。

第一道防线是限流和熔断。当某个 Agent 连续失败，或者 token 消耗异常，自动暂停它的任务，避免问题扩散。这就像电路里的保险丝，烧断了保护整个系统。

第二道防线是状态快照。定期保存 Harness 的完整状态，包括任务队列、Agent 状态、记忆层索引。出问题时可以从快照恢复，不用从头再来。

第三道防线是人工检查点。关键决策点设置人工确认，比如架构变更、大规模重构、删除文件。Agent 可以提议，但最终执行需要人点头。这看起来降低了自动化程度，但实际上避免了灾难性的自动错误。

4.4 一个人如何管理二十万行代码

这是最核心的问题：一个人怎么管得过来二十万行代码？答案是他不管代码，他管流程。

代码是 Agent 生成的，人不需要逐行阅读。人需要做的是：定义任务、设定约束、检查结果、调整方向。这更像是一个技术负责人的角色，而不是一个程序员。

具体来说，每天的工作可能是这样的：早上检查昨晚 Agent 的运行报告，看有没有异常；然后规划今天的任务，把大目标拆成小任务写进 Harness；中间抽查几个关键任务的输出质量；晚上总结当天的进展，更新项目文档。代码本身，人只在出问题时才深入查看。

这种工作方式对能力的要求变了。以前要求写得快、写得好，现在要求想得清楚、说得明白、判断得准。你得能把模糊的需求翻译成精确的任务描述，得能判断 Agent 的输出是对是错，得能在多个方案之间做出取舍。写代码的能力依然重要，但更重要的是架构能力和判断力。

5. 常见问题与排查技巧实录

5.1 Agent 执行中断与错误恢复

热词里有 agent execution terminated due to error、codex 无法发送消息、显示更新 agent 沙盒、harness failed to load plugins。这些都是实际运行中高频出现的问题。

Agent 执行中断的原因通常有几类。第一类是上下文超限，注入的内容太多，超出了模型的上下文窗口。解决办法是优化检索策略，只注入最相关的内容。第二类是工具调用失败，Agent 尝试调用某个工具但工具不可用或返回错误。解决办法是在 Harness 里做工具健康检查，不可用的工具提前排除。第三类是模型返回格式异常，Agent 的输出不符合预期格式，解析失败。解决办法是在 prompt 里强化格式约束，并在解析失败时做容错处理。

错误恢复的关键是状态可回滚。每次 Agent 执行前保存状态快照，失败后回滚到快照点，而不是从中间某个不确定的状态继续。这要求 Harness 的状态管理设计得非常干净，不能有隐藏的副作用。

5.2 Markdown 格式相关的坑

Markdown 看起来简单，但在 Agent 工作流里坑不少。热词里 markdown 换行、markdown 语法、markdown 表格转换 excel、markdown 表格复制、markdown 数学符号，都是高频问题。

换行问题最常见。不同解析器对单个换行和双换行的处理不一样，有的把单换行当空格，有的当换行。在 Harness 里最好统一用双换行表示段落分隔，单换行只在特定场景使用，并且写入时做规范化。

表格问题也很烦。Markdown 表格的列对齐依赖空格，Agent 生成时经常对不齐，导致解析失败。解决办法是在 Harness 里做表格规范化，生成后自动对齐。表格转 Excel 的需求可以用脚本处理，把 Markdown 表格解析成结构化数据再导出。

数学符号的问题在于转义。Markdown 里某些字符有特殊含义，数学公式里的符号需要转义。如果 Agent 生成的内容包含数学公式，最好用专门的数学标记语法，并在渲染时正确处理。

提示：在 Harness 里维护一个 Markdown 规范化模块，所有 Agent 生成的内容都经过这个模块处理后再存储。这样能避免大量格式相关的低级错误。

5.3 插件加载失败与依赖问题

harness failed to load plugins 这个搜索词说明插件加载失败是常见问题。Harness 架构通常支持插件扩展，但插件之间的依赖关系、版本兼容性、加载顺序都可能导致失败。

排查思路是这样的：先看错误日志，确定是哪个插件加载失败；然后检查这个插件的依赖是否满足，版本是否兼容；再看加载顺序是否正确，有些插件必须在其他插件之前加载；最后看权限和路径配置，插件文件是否在正确的位置、是否有读取权限。

预防措施是插件隔离。每个插件在独立的沙盒里运行，一个插件失败不影响其他插件。Harness 启动时逐个加载插件，失败的插件记录错误但继续启动，而不是整个 Harness 崩溃。

5.4 常见问题速查表

5.5 独家避坑经验

第一个经验是不要相信 Agent 的自我报告。Agent 说“任务完成”不代表真的完成了，必须做独立校验。校验可以是自动的（格式检查、单元测试），也可以是人工抽查。我见过太多 Agent 自信满满地返回错误结果的情况。

第二个经验是上下文不是越多越好。刚开始做的时候，总觉得给 Agent 越多背景信息越好，结果 token 消耗爆炸，而且 Agent 反而更容易被无关信息干扰。后来发现，精准的少量上下文比模糊的大量上下文效果好得多。

第三个经验是定期做“记忆清理”。长期运行后，记忆层会积累大量过时或冗余的信息。定期清理这些信息，不仅能省 token，还能提高检索准确率。清理策略可以是按时间（删除半年前的临时记录）、按类型（删除已完成的临时任务记录）、按访问频率（删除长期未访问的文件）。

第四个经验是保留人工否决权。无论 Agent 多智能，总会有判断失误的时候。在关键决策点保留人工否决权，能避免很多灾难。这不是对 Agent 不信任，而是对系统复杂性的敬畏。

6. 这套工作流的真实成本与适用边界

6.1 成本结构的完整拆解

每月四十亿 token 的直接成本，按当前主流模型定价，是一笔需要认真对待的支出。但完整成本不只是 token 费用，还包括时间成本、工具成本和机会成本。

时间成本是最容易被忽略的。一个人九个月，意味着这九个月里这个人几乎全部精力都投入在这个项目上。如果按市场价折算人力成本，这个数字可能比 token 费用还高。所以评估这套工作流是否划算，不能只看 token 账单，要看总投入和总产出。

工具成本包括 Claude Code 的订阅、Obsidian 的插件、可能用到的其他服务。这些相对 token 费用是小头，但也要纳入考虑。

机会成本是这个人如果不做这个项目，能做其他什么事情。这个很难量化，但做决策时应该心里有数。

6.2 什么规模的项目适合这套工作流

这套工作流不是万能的。它适合规模大、周期长、需求相对稳定的项目。规模大意味着自动化收益能覆盖搭建成本；周期长意味着 Harness 的投入能摊薄；需求稳定意味着不需要频繁调整架构。

不适合的场景也很明确。短期小项目不值得搭 Harness，直接用现成工具更快。需求剧烈变化的项目，Harness 的架构可能跟不上变化速度。对正确性要求极高的项目，比如涉及资金安全、人身安全的系统，Agent 生成的内容需要极其严格的校验，可能人工写反而更可靠。

6.3 人的角色转变与能力要求

这套工作流最深刻的影响，是改变了人的角色。从“写代码的人”变成“指挥 AI 写代码的人”，听起来轻松了，实际上对能力的要求更高了。

你需要有架构能力，能在脑子里装下整个系统的结构，知道各个部分怎么配合。你需要有判断能力，能快速判断 Agent 的输出是对是错、是好是坏。你需要有表达能力，能把模糊的需求翻译成精确的任务描述。你需要有耐心，能忍受 Agent 反复出错、反复调试的过程。

写代码的能力依然重要，但它的作用变了。以前你写代码是为了实现功能，现在你写代码是为了给 Agent 做示范、做校验、做兜底。你写的代码可能只占最终代码量的很小一部分，但这一部分的质量决定了整个系统的上限。

6.4 后续可以扩展的方向

这套工作流跑通之后，有几个自然的扩展方向。第一是多 Agent 协作，让不同专长的 Agent 分工合作，比如一个写代码、一个写测试、一个做审查。第二是自动化程度提升，把更多人工检查点变成自动检查，减少人的介入频率。第三是知识沉淀，把项目过程中积累的经验和模式整理成可复用的模板，用于下一个项目。

我个人在实际操作中的体会是，这套工作流最大的价值不在于省了多少人力，而在于它让一个人能做的事情的边界大大扩展了。以前一个人做不了二十万行代码的项目，现在可以了。这种能力边界的扩展，比单纯的效率提升更有意义。

最后再分享一个小技巧：在 Harness 里加一个“每日摘要”功能，每天结束时自动生成当天的工作摘要，包括完成了哪些任务、消耗了多少 token、遇到了哪些问题。这个摘要不仅是记录，也是第二天工作的起点。坚持做这个，项目跑到后期你会感谢自己。