★ FEATURED ARTICLE 一个人、九个月、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往一个文件夹里写MarkdownObsidian把这个文件夹当vault打开你就能用图谱视图看到Agent的知识结构。这个组合我用下来非常顺手。3. Claude Code和Agent开发的实战关系3.1 Claude Code不只是个命令行工具很多人把Claude Code当成终端里的AI助手这个理解太浅了。Claude Code本质上是一个已经封装好的Harness实现。它内置了工具调用、上下文管理、文件操作、命令执行这些能力你通过自然语言就能驱动它完成复杂任务。热词里有claude code安装vscode配置claude codeclaude 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是知识管理工具两者打通能形成读文献→整理笔记→建立关联的完整链路。大致步骤是这样的在Zotero里安装导出插件把笔记导出为Markdown格式导出时注意保留元数据作者、年份、标题这些会变成frontmatter把导出的文件夹放进Obsidian的vault目录用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砸的都是这个可靠性。如果你也想做类似的东西从最小版本开始把可靠性一点点堆上去比一开始就追求大而全要实在得多。
阅读完成 · 觉得有帮助？
