企业官网建设流程全解析

一个人、九个月、20万行代码、每月40亿token的消耗量，这几个数字摆在一起的时候，我第一反应不是"牛"，而是"这人到底在解决什么问题，值得用这么重的投入去砸"。Harness架构这个词最近被讨论得很多，但真正把它落到一个完整应用里的人并不多。我花了很长时间研究这类项目的构建思路，也自己动手搭过几个Agent驱动的工具链，踩过的坑不算少。这篇文章就把我从这个项目标题里拆出来的东西，结合Harness、Agent、Markdown、Claude Code、Obsidian这几个关键词，完整地聊一遍——它是什么、为什么这么设计、核心技术点在哪、普通人能不能复现、以及那些文档里不会写的坑。

如果你正在做AI Agent相关的开发，或者想用Claude Code这类工具搭一套自己的知识管理系统，又或者只是好奇"一个月烧40亿token到底在干什么"，这篇应该能给你一些实在的参考。

1. 先搞清楚Harness架构到底在解决什么

1.1 从"模型很聪明但干不了活"说起

大多数人用大模型的姿势是这样的：打开对话框，输入问题，拿到回答，复制走人。这个模式在问答场景下没问题，但一旦你想让它"持续地做一件事"，立刻就崩了。原因很简单——模型本身是无状态的，它不记得上一轮做了什么，不知道文件在哪，没法调用外部工具，更没法在出错的时候自己重试。

Harness这个词直译是"马具"或者"挽具"，放在AI语境里，它的核心含义是：给模型套上一套完整的执行框架，让它从"会说话"变成"会干活"。你可以把它理解成给一匹力气很大但没方向感的马，配上缰绳、鞍具和车道。模型是马，Harness是那整套装备。

一个完整的Harness架构通常包含这几个部分：

• 任务编排层：决定下一步做什么，把大目标拆成小步骤
• 工具调用层：让模型能读写文件、执行命令、访问网络、操作数据库
• 上下文管理层：决定哪些信息放进prompt，哪些丢掉，怎么压缩历史
• 状态持久层：把执行过程中的中间结果存下来，支持中断恢复
• 错误处理层：出错时怎么重试、怎么回退、怎么上报

这五层缺一层，系统就跑不稳。我见过太多人只做了工具调用层就以为大功告成，结果一跑长任务就各种断片。

1.2 为什么是"一个人九个月20万行"

20万行代码这个量级，如果是一个团队做，大概三到六个月能出来。但一个人做九个月，意味着这个人几乎是在全职、高强度地迭代。这里面有个很关键的判断：Harness架构的复杂度不在单点技术，而在系统集成。

单看每一层都不难——调个API、写个文件读写、做个简单的状态机，任何一个有经验的工程师几天就能搞定。难的是让这五层协同工作，并且在各种边界情况下都不崩。比如：

• 模型调用工具返回了超长结果，上下文塞不下了怎么办
• 工具执行到一半进程被杀，重启后怎么恢复
• 模型陷入死循环，反复调用同一个工具怎么办
• 多个子任务并行时，状态怎么同步

这些问题没有标准答案，只能一个个试、一个个改。20万行代码里，我估计至少有一半是在处理这些"边角料"。

1.3 每月40亿token是什么概念

40亿token，按Claude Sonnet的定价粗略估算，输入输出混算，一个月大概是几万到十几万美元的量级。这个数字说明两件事：一是这个应用确实在跑真实的长任务，不是demo；二是它的上下文管理策略一定做了大量优化，否则成本会失控。

我自己的经验是，一个Agent任务如果上下文管理做得粗糙，token消耗能差出五到十倍。比如同样是让Agent读一个代码库回答问题，全量塞进去和先做检索再塞，消耗完全不是一个量级。40亿token能撑住，说明这套Harness在上下文压缩、缓存复用、增量处理上下了功夫。

提示：如果你也在做Agent应用，token成本一定要从第一天就开始监控。等到账单出来再优化，通常已经晚了。

2. Markdown为什么成了这套系统的"通用语言"

2.1 Agent和Markdown的天然契合

热词里Markdown出现频率极高，这不是偶然。在Harness架构里，Markdown扮演的角色远比"文档格式"重要得多。它其实是人和Agent之间的中间协议。

为什么是Markdown而不是JSON或者YAML？我的理解是三点：

第一，Markdown对模型友好。大模型在训练时见过海量Markdown文本，它对标题层级、列表、代码块的理解非常自然。你让模型输出结构化数据，用Markdown比用严格JSON的出错率低得多。

第二，Markdown对人友好。Agent执行完任务，输出一份Markdown报告，人可以直接读，不需要额外解析。这在调试阶段特别重要。

第三，Markdown足够灵活。它既能表达纯文本，又能嵌代码块、表格、数学公式，还能通过frontmatter携带元数据。一个格式覆盖了展示、存储、传输三种需求。

2.2 那些让人抓狂的Markdown细节

做Agent应用，Markdown的坑是真的多。我列几个最常遇到的：

换行问题。Markdown里单个换行默认不生效，要空一行才是新段落。但模型经常忘记这一点，输出一堆挤在一起的文字。解决办法是在prompt里明确要求，或者在渲染层做预处理。

表格转换。热词里有"markdown表格转换excel"，这个需求在Agent场景下很常见——Agent生成一个表格，用户想导出。但Markdown表格的对齐、合并单元格支持很弱，转换时经常丢信息。我的做法是让Agent直接输出CSV或者用HTML表格，需要展示时再转Markdown。

数学公式。行内公式用$...$，块级用$$...$$，但不同渲染器支持程度不一样。Obsidian需要装插件，有些阅读器干脆不支持。如果Agent要输出公式，最好在系统提示里约定好格式。

代码块语言标注。这个看似小事，但影响很大。没有语言标注的代码块，语法高亮失效，可读性直线下降。我在prompt里会强制要求Agent标注语言。

2.3 Markdown作为Agent的"记忆载体"

这一点是我觉得最值得说的。在Harness架构里，Agent的长期记忆通常就是用Markdown文件存的。为什么？

因为Markdown文件是纯文本、可版本控制、可人工编辑的。Agent写进去的东西，人可以随时打开看、随时改。这比存数据库或者二进制格式强太多——出问题的时候，你直接打开文件就能看到Agent到底记了什么、想干什么。

Obsidian在这套体系里就成了天然的"记忆浏览器"。Agent往一个文件夹里写Markdown，Obsidian把这个文件夹当vault打开，你就能用图谱视图看到Agent的知识结构。这个组合我用下来非常顺手。

3. Claude Code和Agent开发的实战关系

3.1 Claude Code不只是个命令行工具

很多人把Claude Code当成"终端里的AI助手"，这个理解太浅了。Claude Code本质上是一个已经封装好的Harness实现。它内置了工具调用、上下文管理、文件操作、命令执行这些能力，你通过自然语言就能驱动它完成复杂任务。

热词里有"claude code安装""vscode配置claude code""claude code使用"，说明很多人在入门阶段。我的建议是：先把Claude Code用熟，再去理解Harness架构。因为Claude Code就是一个活生生的Harness样本，你用它的过程，就是在体验Harness该有的样子。

安装本身不复杂，但有几个点容易卡住：

• Node环境版本要够新，老版本会报奇怪的错
• 认证配置要一次做对，否则每次都要重新登录
• 工作目录的选择很关键，Claude Code会以当前目录为根做文件操作

3.2 用Claude Code调用本地模型的思路

热词里有一条"claude code 调用lmstudio的本地模型"，这个需求我理解——有人想省钱，有人想数据不出本地。思路是配置一个兼容OpenAI接口的本地服务，然后把Claude Code的endpoint指过去。

但这里有个现实问题：本地模型的能力和Claude差距还是明显的，尤其是在长上下文和工具调用的稳定性上。我的经验是，简单任务用本地模型没问题，复杂的长链任务还是得用能力强的模型。省钱可以，但别省到任务跑不通。

3.3 Agent开发中最容易忽略的三件事

做了几个Agent项目之后，我发现新手最容易在三个地方翻车：

第一，工具描述写得太随意。模型靠工具描述来决定调不调用、怎么调用。描述写得含糊，模型就会乱调。每个工具的名称、参数、返回值、适用场景都要写清楚，最好给例子。

第二，没有做超时和重试。网络会抖，API会限流，工具会卡住。没有超时机制，一个任务能挂死在那里。我的做法是每个工具调用都设超时，失败后按指数退避重试，重试几次还不行就上报。

第三，日志记太粗。Agent执行过程如果不记详细日志，出问题根本没法排查。我要求每次模型调用、每次工具执行、每次状态变更都记日志，包括输入输出和耗时。日志多了占空间，但排查问题时是真香。

4. Obsidian在Agent工作流里的位置

4.1 为什么是Obsidian而不是别的笔记软件

Obsidian的核心优势是本地Markdown文件 + 双向链接 + 插件生态。这三点恰好对上Agent工作流的需求：

• 本地文件意味着Agent可以直接读写，不需要走API
• 双向链接让知识之间产生关联，Agent可以利用这个图谱做检索
• 插件生态让Obsidian能扩展出各种能力，比如和外部工具集成

热词里"obsidian教程""obsidian插件推荐""obsidian下载""obsidian使用教程"出现很多次，说明这是个热门话题。我推荐几个和Agent配合特别好的插件方向：Dataview（用查询语言动态展示笔记）、Templater（模板自动化）、以及各种Markdown增强插件。

4.2 把Zotero笔记导入Obsidian的实操

热词里有"如何将zotero的笔记导入obsidian"，这个我实际操作过。Zotero是文献管理工具，Obsidian是知识管理工具，两者打通能形成"读文献→整理笔记→建立关联"的完整链路。

大致步骤是这样的：

1. 在Zotero里安装导出插件，把笔记导出为Markdown格式
2. 导出时注意保留元数据（作者、年份、标题），这些会变成frontmatter
3. 把导出的文件夹放进Obsidian的vault目录
4. 用Dataview插件建立索引，按标签或年份自动归类

坑点在于：Zotero导出的Markdown，图片路径经常是错的，需要批量修正。另外引用格式在不同插件下表现不一致，最好统一用一种。

4.3 Obsidian作为Agent输出的"展示层"

我自己的用法是：Agent负责生成和整理内容，Obsidian负责展示和关联。Agent往vault里写Markdown，我在Obsidian里读。这样有个好处——Agent的产出是可审阅、可修改的，不是黑盒。

比如我让Agent帮我整理一周的技术笔记，它会生成一个带标签和链接的Markdown文件。我打开Obsidian，能看到这篇笔记和之前的哪些笔记有关联，图谱视图里一目了然。如果Agent哪里整理得不对，我直接改文件就行，下次Agent读到的就是修正后的版本。

5. 复现这套架构的可行路径

5.1 从最小可用版本开始

如果你看完上面这些，想自己动手搭一套，我的建议是别一上来就追求完整。先做一个最小可用版本：

• 一个能调用模型的脚本
• 两三个基础工具（读文件、写文件、执行命令）
• 一个简单的循环：模型输出→解析→执行工具→把结果喂回模型
• 一个Markdown格式的日志文件

这四样东西加起来可能就两三百行代码，但已经能跑通"让Agent做一件小事"的完整链路。跑通之后再逐步加东西：加超时、加重试、加上下文压缩、加状态持久化。

5.2 上下文管理的几个实用策略

这是Harness架构里最影响成本和效果的部分。我总结几个实用策略：

我的实际做法是组合使用：近期对话用滑动窗口，历史内容定期摘要，需要精确回忆的用检索。这样能在成本和效果之间找到平衡。

5.3 状态持久化怎么做才靠谱

Agent跑长任务，最怕的就是中途挂了要从头来。状态持久化的核心是把执行过程变成可恢复的。

我的做法是每一步都写checkpoint：当前任务是什么、已经完成了哪些子步骤、下一步该做什么、有哪些中间结果。checkpoint用JSON存，简单可靠。重启时读最后一个checkpoint，从那里继续。

这里有个细节：checkpoint不能太频繁，否则IO开销大；也不能太稀疏，否则恢复时丢太多进度。我的经验是每个"有意义的步骤"完成后写一次，比如一个工具调用成功、一个子任务完成。

6. 那些没人告诉你的坑

6.1 模型会"假装"完成了任务

这是最坑的一点。模型有时候会输出"我已经完成了XX任务"，但实际上它根本没调用工具，或者调用了但失败了。如果你不加验证就信了，任务就悄悄失败了。

解决办法是强制验证：每个任务完成后，用独立的逻辑检查结果是否真的存在。比如Agent说"我已经创建了文件"，你就去检查文件是否真的存在、内容是否合理。

6.2 工具调用的参数会"漂移"

同一个工具，模型这次传的参数格式和上次可能不一样。比如一个接受路径的工具，模型有时传绝对路径，有时传相对路径，有时还带引号。这会导致工具执行失败。

我的做法是在工具层做参数归一化：不管模型传什么格式，先统一处理成标准格式再执行。同时在工具描述里把参数格式写死，减少模型的自由发挥空间。

6.3 长任务会"跑偏"

Agent跑着跑着，可能就偏离了原始目标。比如你让它整理文档，它整理到一半开始自己写新内容了。这是因为长上下文里，早期目标被稀释了。

对策是定期重申目标。每隔几步，把原始任务描述重新塞进上下文，提醒模型"你要做的是这个"。这个技巧简单但有效。

6.4 成本会在你不注意时飙升

Agent陷入循环、反复调用同一个工具、或者上下文无限增长，都会让成本飙升。我建议设置硬性上限：单任务最大token数、最大工具调用次数、最大执行时间。超过就强制停止并上报。

注意：这些上限不是限制Agent能力，而是保护你的钱包。我见过有人一晚上跑掉几百美元的案例。

7. 这套架构能延伸到哪里

7.1 个人知识管理的自动化

最直接的应用就是个人知识管理。Agent可以帮你：自动整理笔记、建立笔记之间的关联、从大量文档里提取要点、定期生成知识摘要。配合Obsidian，这套流程能跑得很顺。

7.2 代码库的自动化维护

Agent可以读代码库、理解结构、执行重构、生成文档、跑测试。Claude Code本身就是这个方向的产物。如果你有自己的代码库，可以基于Harness架构做一个定制化的维护助手。

7.3 内容生产的流水线

从选题、调研、写作到排版，Agent可以串成一条流水线。Markdown作为中间格式，让每个环节的产出都能被下一个环节直接消费。这也是我自己在用的模式。

7.4 需要注意的边界

不是所有任务都适合交给Agent。需要精确判断、涉及重要决策、容错率低的任务，还是得人来把关。Agent适合的是那些重复性高、容错率相对高、有明确验证标准的任务。搞清楚这个边界，比盲目追求"全自动"重要得多。

我在实际使用中最大的体会是：Harness架构的价值不在于让AI"更聪明"，而在于让AI"更可靠"。模型能力是给定的，但通过好的架构设计，你能让同样的模型完成复杂得多的任务。20万行代码、40亿token，砸的都是这个"可靠性"。如果你也想做类似的东西，从最小版本开始，把可靠性一点点堆上去，比一开始就追求大而全要实在得多。