企业官网建设流程全解析

1. 先搞清楚这个项目到底在做什么

一个人，九个月，二十万行代码，每个月消耗四十亿以上的 token，最终交付的是一款基于 Harness 架构的应用。这几个数字摆在一起，任何一个写过代码的人都会先愣一下——不是因为二十万行代码有多夸张，而是因为“一个人”和“九个月”这两个限定词。正常来说，二十万行代码的工程量，放在一个五人到八人的团队里，做一年半到两年是常态。一个人九个月干完，意味着这个人几乎把所有能自动化的环节全部自动化了，而四十亿 token 的月消耗量，恰恰说明自动化不是靠手写脚本堆出来的，是靠大模型驱动的 Agent 流水线跑出来的。

这里说的 Harness 架构，不是某个具体框架的名字，而是一种设计思路：把大模型当作一个需要被“约束”和“驱动”的执行引擎，外面套一层完整的控制层，负责上下文管理、工具调用、状态持久化、错误恢复和任务编排。你可以把它理解成给一匹野马套上缰绳和马鞍——模型本身能力很强，但如果没有 Harness，它就是一个聊天框；有了 Harness，它才是一个能持续干活的生产力工具。Claude Code 就是这种思路的一个典型代表，它把文件读写、命令执行、代码搜索这些能力封装成工具，让模型在一个受控的循环里反复调用，直到任务完成。

这个项目适合谁来参考？如果你是一个独立开发者，正在琢磨怎么用 Agent 的方式把自己的工作效率拉高一个数量级，那这篇内容对你有直接价值。如果你是一个小团队的负责人，想知道一个人怎么干出一个团队的产出，这里面的架构决策和踩坑记录同样值得看。哪怕你只是刚开始接触 Claude Code、Obsidian 这类工具，想搞清楚它们之间怎么串起来，下面的内容也能给你一条清晰的路径。

2. 为什么是 Harness 架构，而不是普通的脚本自动化

2.1 普通脚本自动化的天花板在哪里

大部分人第一次尝试自动化，都是从写脚本开始的。比如用 Python 写一个脚本，定时抓取某个数据源，处理完之后写到文件里。这种模式在任务固定、输入格式稳定的场景下非常好用，写起来快，跑起来也稳。但问题在于，一旦任务变得稍微复杂一点——比如需要根据中间结果动态决定下一步做什么，或者需要理解自然语言描述的指令——脚本就开始力不从心了。

我举个例子。假设你想让程序帮你整理一批 Markdown 笔记，把里面所有关于“Agent”的段落提取出来，按照主题重新归类，然后生成一份摘要。用传统脚本怎么做？你得先写正则表达式匹配“Agent”相关的关键词，然后写一套规则来判断段落属于哪个主题，再写一个模板来生成摘要。这套东西写出来，光是规则维护就能把人逼疯，而且换一批笔记，规则可能就全废了。

Harness 架构解决的就是这个问题。它不要求你预先定义所有规则，而是把“理解”和“决策”交给模型，你只需要定义好模型可以使用的工具，以及这些工具的调用规范。模型在每一步都会根据当前上下文决定调用哪个工具、传什么参数，然后根据返回结果决定下一步。这个循环就是 Agent 的核心执行逻辑。

2.2 Harness 架构的三个核心组件

一个完整的 Harness 架构，至少包含三个部分。第一个是上下文管理器，负责决定每一步往模型的输入里塞什么信息。这听起来简单，实际上是最难的部分。模型的上下文窗口是有限的，你不可能把所有历史记录都塞进去，必须做筛选和压缩。常见的做法是保留最近几轮对话的完整内容，对更早的历史做摘要，同时把当前任务相关的文件内容按需注入。

第二个是工具层。工具就是模型可以调用的函数，比如读文件、写文件、执行命令、搜索代码。每个工具都需要有清晰的描述，告诉模型这个工具是干什么的、参数是什么格式、什么情况下应该用。工具描述的质量直接决定了模型能不能正确使用它。我见过太多人抱怨模型“不听话”，结果一看工具描述写得含糊不清，模型根本不知道什么时候该调用。

第三个是状态机与错误恢复。Agent 在执行任务的过程中一定会出错——工具调用失败、模型输出格式不对、任务陷入死循环。Harness 需要有一套机制来检测这些异常，并决定是重试、跳过还是终止。这部分往往是最容易被忽略的，但恰恰是决定一个 Agent 能不能长时间稳定运行的关键。

2.3 为什么选择 Claude Code 作为执行引擎

在众多可选方案里，Claude Code 的优势在于它已经把工具层和上下文管理做得很成熟了。你不需要从零开始写一个 Agent 循环，只需要在它的基础上做扩展。它内置了文件读写、命令执行、代码搜索这些高频工具，而且工具调用的协议是稳定的。更重要的是，它对 Markdown 文件的支持非常自然——这对于以 Obsidian 作为知识库载体的项目来说，几乎是刚需。

Obsidian 的笔记本身就是 Markdown 格式，Claude Code 可以直接读取和修改这些文件，不需要做任何格式转换。这意味着你可以让 Agent 直接在你的知识库里干活，比如自动整理笔记、生成索引、提取待办事项。这种无缝衔接是很多其他方案做不到的。

3. 二十万行代码是怎么堆出来的

3.1 代码量的构成分析

二十万行代码听起来很多，但如果拆开看，其实构成很清晰。根据我在类似项目中的经验，这类 Harness 应用的代码大致可以分为几个部分。核心的 Agent 循环和上下文管理大概占百分之十五到二十，工具层的实现占百分之二十五到三十，剩下的百分之五十以上都是业务逻辑和适配层。

业务逻辑为什么这么多？因为 Harness 架构本身只提供了执行框架，具体要做什么任务，需要大量的领域代码来支撑。比如你要处理 Markdown 笔记，就需要写 Markdown 解析、链接提取、标签管理、文件同步这些模块。每一个模块单独看都不复杂，但加起来量就上去了。

还有一个容易被低估的部分是配置和提示词工程。提示词本身不算代码，但围绕提示词的管理、版本控制、A/B 测试、效果评估，这些都需要代码来支撑。在一个成熟的 Harness 项目里，提示词相关的代码和配置能占到总代码量的百分之十左右。

3.2 九个月的时间线拆解

九个月听起来很长，但对于这个体量的项目来说，时间其实非常紧。我试着还原一下合理的时间分配。第一个月基本上是在做技术选型和原型验证，确定用 Claude Code 作为执行引擎，确定 Obsidian 作为知识库载体，跑通最基本的“读文件-处理-写文件”循环。

第二到第四个月是核心架构的搭建期。这段时间要完成上下文管理器的实现、工具层的封装、状态机的设计。同时还要解决一个关键问题：怎么让 Agent 在长时间运行中保持稳定。我试过不少方案，最后发现最有效的做法是给每个任务设置明确的完成条件，并且限制最大迭代次数，防止 Agent 在一个问题上无限循环。

第五到第七个月是业务逻辑的密集开发期。这段时间代码量增长最快，因为大量的 Markdown 处理逻辑、Obsidian 插件适配、数据同步机制都是在这个阶段完成的。也是在这个阶段，token 消耗量开始飙升，因为每次调试都需要让 Agent 实际跑一遍任务。

最后两个月是优化和打磨期。重点放在减少 token 消耗、提高任务成功率、完善错误恢复机制上。这个阶段代码量的增长放缓，但质量提升明显。

3.3 四十亿 token 到底花在哪里了

四十亿 token 一个月，平均下来每天一亿多。这个数字乍看很吓人，但拆开看就合理了。假设你每天让 Agent 处理一千个任务，每个任务平均消耗十万 token，那一天就是一亿。十万 token 是什么概念？大概相当于七万到八万个英文单词，或者五万个左右的中文汉字。对于一个需要读取多个文件、进行多轮推理、生成结构化输出的任务来说，这个消耗量是正常的。

消耗的大头在上下文注入。每次 Agent 执行任务，都需要把相关的文件内容、历史记录、工具描述塞进上下文。如果文件很大，或者历史记录很长，token 消耗就会急剧上升。我踩过的一个坑是，早期没有做上下文压缩，每次任务都把整个对话历史塞进去，结果 token 消耗是现在的三到四倍。后来引入了滑动窗口和摘要机制，消耗才降下来。

另一个消耗大户是错误重试。Agent 执行失败的时候，往往需要重新跑一遍，这就意味着同样的上下文要再消耗一次。减少错误重试的关键是提高工具描述的清晰度和任务拆分的粒度。任务拆得越细，单步出错的概率越低，重试的成本也越小。

4. 核心实操：从零搭建一个 Harness 应用的完整路径

4.1 环境准备与工具链配置

第一步是安装 Claude Code。这个过程本身不复杂，但有几个细节需要注意。安装完成后，你需要配置模型访问方式。如果你使用的是本地模型，比如通过 LM Studio 加载的模型，需要在 Claude Code 的配置里指定本地服务的地址和端口。这里的一个常见问题是模型名称的映射——Claude Code 默认使用特定的模型标识，你需要把它映射到你本地实际加载的模型名称上，否则会报“模型不存在”的错误。

Obsidian 的安装相对简单，但插件配置需要花点心思。我推荐至少安装以下几个插件：Dataview 用于查询笔记元数据，Templater 用于自动化模板生成，QuickAdd 用于快速捕获内容。这些插件本身不直接和 Agent 交互，但它们生成的 Markdown 文件结构会直接影响 Agent 的处理效率。比如，如果你用 Dataview 生成了结构化的查询结果，Agent 读取这些结果时就比读取纯文本要容易得多。

Markdown 的语法细节也值得注意。比如换行，在标准 Markdown 里，行尾加两个空格表示换行，但很多编辑器对此处理不一致。Obsidian 默认使用严格的换行规则，而 Claude Code 在生成 Markdown 时可能不会自动加空格。这个差异会导致生成的笔记在 Obsidian 里显示异常。我的做法是在 Agent 的输出环节加一个后处理步骤，自动把需要换行的地方补上两个空格。

4.2 上下文管理器的实现要点

上下文管理器是整个 Harness 的核心，它的质量直接决定了 Agent 的表现。实现的时候，我建议采用分层策略。第一层是系统提示词，这部分内容固定不变，定义 Agent 的角色、能力边界和基本行为规范。第二层是任务描述，每次执行任务时动态生成，告诉 Agent 这次要做什么。第三层是相关文件内容，根据任务类型选择性地注入。第四层是历史对话摘要，对之前的交互做压缩后的记录。

分层的好处是每一层可以独立优化。比如系统提示词可以单独做 A/B 测试，文件注入策略可以按任务类型调整，历史摘要的压缩比例可以动态控制。我实测下来，分层之后 token 利用率大概提升了百分之四十左右。

还有一个关键点是文件注入的粒度。不要一次性把整个文件塞进去，而是先注入文件的结构信息（比如标题层级、段落数量），让 Agent 决定需要读取哪一部分，然后再按需注入具体内容。这个策略对于大文件特别有效，能把单次任务的 token 消耗降低一半以上。

4.3 工具层的设计与实现

工具层的设计原则是“少而精”。不要给 Agent 提供几十个工具，那样只会让它选择困难。我建议核心工具控制在十个以内，每个工具的功能要足够通用。比如“读文件”这个工具，应该支持读取整个文件、读取指定行范围、按关键词搜索等多种模式，而不是拆成三个独立的工具。

每个工具的描述要包含三个要素：功能说明、参数格式、使用场景。功能说明要一句话讲清楚这个工具是干什么的。参数格式要明确每个参数的类型、是否必填、取值范围。使用场景要告诉 Agent 什么情况下应该用这个工具，什么情况下不应该用。我见过很多工具描述只写了功能说明，结果 Agent 在不该用的时候也调用，白白浪费 token。

错误处理也是工具层的重要部分。每个工具都应该有明确的错误返回格式，告诉 Agent 是参数错了、权限不够还是资源不存在。Agent 根据错误类型决定是重试、换参数还是放弃。如果错误信息含糊不清，Agent 就只能瞎猜，重试几次之后可能就陷入死循环了。

4.4 与 Obsidian 知识库的集成方案

Obsidian 的知识库本质上就是一个文件夹，里面全是 Markdown 文件。Agent 要做的第一件事是建立索引，扫描整个知识库，提取每个文件的标题、标签、链接关系、修改时间这些元数据。这个索引可以存在内存里，也可以持久化到文件里。我建议持久化，因为知识库大的时候，每次重新扫描很浪费时间。

索引建好之后，Agent 就可以根据任务需求快速定位到相关文件。比如用户说“帮我整理一下关于 Agent 的笔记”，Agent 先查索引，找到所有标签或内容里包含“Agent”的文件，然后逐个读取处理。这个流程比让 Agent 自己遍历整个文件夹要高效得多。

还有一个实用技巧是利用 Obsidian 的双向链接。Obsidian 的[[链接]]语法天然形成了一张知识图谱。Agent 在处理一个文件的时候，可以顺着链接找到相关联的文件，这样就能在整理笔记的同时发现内容之间的隐含关系。我试过让 Agent 自动生成“相关笔记”推荐，效果比单纯的关键词匹配好很多。

5. 踩坑记录与常见问题排查

5.1 Agent 执行中断的典型原因

Agent 执行到一半突然中断，是最让人头疼的问题。常见原因有几个。第一个是上下文超限。当注入的内容超过模型的上下文窗口时，模型会直接报错退出。解决办法是在注入前做 token 估算，超过阈值就触发压缩或截断。我一般会把阈值设在模型上限的百分之八十，留出余量给模型的输出。

第二个是工具调用格式错误。模型有时候会生成不符合工具描述格式的调用请求，比如参数类型不对、缺少必填字段。这种情况下，Harness 需要捕获解析错误，并把错误信息返回给模型，让它重新生成。如果连续三次都失败，就应该终止任务并记录日志，而不是无限重试。

第三个是网络或服务不稳定。如果模型是通过网络访问的，网络抖动会导致请求失败。这种情况下，简单的重试机制就能解决。但要注意设置重试上限和退避策略，避免在服务不可用的时候疯狂重试。

5.2 Token 消耗异常的排查思路

Token 消耗突然飙升，通常有几个信号。第一个信号是单任务消耗量翻倍。这往往意味着上下文注入策略出了问题，比如某个文件的注入没有做截断，或者历史摘要没有生效。排查方法是打印每次任务的 token 消耗明细，看看是哪一部分涨了。

第二个信号是重试率上升。如果 Agent 频繁重试，token 消耗自然就上去了。重试率上升的原因可能是工具描述变得模糊了，或者任务拆分的粒度变粗了。我遇到过一次，是因为修改了系统提示词，导致 Agent 对某个工具的理解出现了偏差，频繁调用一个不该调用的工具。

第三个信号是输出长度异常。模型有时候会生成特别长的输出，比如把一个简单的确认信息写成了一篇小作文。这种情况下，需要在系统提示词里明确限制输出长度，或者在 Harness 层面对输出做截断。

5.3 Markdown 处理中的常见坑

Markdown 看起来简单，但在 Agent 处理场景下有不少坑。第一个坑是表格转换。Markdown 表格的语法对对齐要求很严格，Agent 生成的表格经常因为列宽不一致而显示错乱。我的做法是在输出后加一个格式化步骤，自动调整表格的对齐。

第二个坑是数学公式。Markdown 本身不支持数学公式，需要依赖 LaTeX 扩展。如果 Agent 生成的公式没有用正确的定界符包裹，Obsidian 就无法渲染。我建议在系统提示词里明确要求所有数学公式必须用$或$$包裹，并且在输出后做一次校验。

第三个坑是链接和图片路径。Obsidian 使用相对路径引用附件，如果 Agent 生成的路径是绝对路径或者格式不对，链接就会失效。解决办法是在工具层封装一个路径规范化函数，所有涉及路径的操作都走这个函数。

5.4 常见问题速查表

6. 一些实操心得和后续扩展方向

6.1 关于提示词工程的几点体会

提示词不是越长越好。我早期写过几千字的系统提示词，结果发现模型反而更容易迷失重点。后来精简到几百字，只保留最核心的行为规范，效果反而更好。关键是要把提示词当成代码来管理，每次修改都要有明确的假设和验证方法。

另一个体会是示例比描述更有效。与其花大段文字描述“你应该怎么输出”，不如给一两个具体的输入输出示例。模型对示例的模仿能力很强，一个好的示例能顶十句描述。我在工具描述里都会附上一个调用示例，Agent 使用工具的准确率明显提升。

6.2 关于成本控制的实战经验

四十亿 token 一个月，成本确实不低。但通过一些策略，可以在不影响效果的前提下把消耗降下来。第一个策略是缓存。对于重复性高的任务，比如每天整理同一批笔记，可以把上次的处理结果缓存起来，只处理有变化的部分。第二个策略是分级处理。简单的任务用轻量模型，复杂的任务才用大模型。第三个策略是批量合并。把多个小任务合并成一个大任务，减少上下文重复注入的开销。

我实测下来，这三个策略叠加使用，能把 token 消耗降低百分之五十到六十，而任务成功率基本不受影响。

6.3 这个项目还能怎么扩展

Harness 架构的扩展性很强，因为它本质上是一个通用的执行框架。除了 Markdown 笔记处理，还可以用来做很多其他事情。比如接入代码仓库，让 Agent 自动做代码审查和重构建议。或者接入邮件系统，让 Agent 自动分类和回复邮件。甚至可以把多个 Agent 串联起来，形成一个流水线，每个 Agent 负责一个环节，前一个的输出作为后一个的输入。

我个人比较看好的方向是多 Agent 协作。单个 Agent 的能力有上限，但如果把任务拆开，让多个 Agent 并行处理，整体吞吐量能提升很多。当然，多 Agent 带来的协调成本也不低，需要一套完善的任务分发和结果汇总机制。这个方向我还在摸索，等有成熟经验了再单独写一篇来聊。

6.4 给刚入门的同行的建议

如果你刚开始接触 Harness 架构和 Agent 开发，我的建议是先跑通一个最小闭环。不要一上来就想着做多复杂的功能，先让 Agent 能读一个文件、处理一下、写回去。这个闭环跑通了，再逐步增加工具和任务类型。我见过太多人卡在环境配置和工具调试上，还没开始做业务逻辑就放弃了。

另外，日志一定要做全。Agent 的每一步决策、每一次工具调用、每一个错误，都要有详细的日志记录。这些日志是你排查问题的唯一依据。我早期没重视日志，结果出了问题只能靠猜，浪费了大量时间。后来把日志做完善了，排查效率至少提升三倍。

最后，不要追求一次做对。Agent 的行为有很大的不确定性，同样的输入可能产生不同的输出。接受这种不确定性，把重点放在提高成功率和降低失败成本上，而不是试图消除所有错误。这个心态调整过来之后，整个开发过程会顺畅很多。