1. 这个项目到底在做什么先把概念掰开揉碎一个人九个月20 万行代码每个月消耗 40 亿以上的 token最终交付一款基于 Harness 架构的应用。这组数字第一次看到的时候我的反应和大多数人一样——先怀疑再好奇最后是那种这活儿到底怎么干下来的的困惑。因为单看任何一个数字都不算离谱但把它们叠在一起就变成了一个非常反常识的工程样本。先把 Harness 这个词说清楚。在 AI Agent 开发语境里Harness 不是某个具体产品而是一类架构思路它指的是包裹在模型外面的一整套挽具——负责把模型的原始输出转化成可执行、可校验、可回滚的动作。你可以把它理解成马和马车之间的关系模型是马力气大但方向感差Harness 就是那套缰绳、鞍具和车架决定这匹马拉什么、往哪拉、什么时候停。没有 Harness 的 Agent本质上就是一个会聊天的接口有了 Harness它才变成一个能真正干活的系统。这个项目的核心价值恰恰在于它把 Harness 从论文里的概念变成了跑在生产环境里的东西。它解决的不是模型能不能回答问题而是模型能不能稳定地、可预期地、在长周期任务里持续做对的事。适合谁来参考我认为有三类人一是正在做 Agent 项目、被模型一抽风整个流程就崩折磨的开发者二是想理解 Agent 工程化落地路径的技术负责人三是像我这样对一个人能不能扛起一个完整 AI 应用这件事既怀疑又向往的独立开发者。九个月、20 万行、每月 40 亿 token这三个数字背后其实对应着三件事时间投入的密度、代码组织的复杂度、以及模型调用的真实规模。40 亿 token 是什么概念按主流模型的计费方式粗算如果全部走中高价位模型一个月的成本足以让大多数个人项目直接放弃。所以这个项目能跑下来本身就说明它在 token 使用策略上做了大量优化——这也是我后面要重点拆的部分。2. 架构选型的底层逻辑为什么是 Harness而不是别的2.1 从提示词工程到挽具工程的思维转变大多数人做 Agent 的第一反应是堆提示词。写一个超长的 system prompt把各种规则、示例、边界条件全塞进去然后祈祷模型每次都听话。我早期也这么干过结果就是简单任务表现不错一旦任务链条拉长到十几步模型就开始忘记前面的约束输出格式飘忽工具调用参数错位整个流程像多米诺骨牌一样倒掉。Harness 架构的核心洞察是不要指望模型记住规则而要把规则变成模型无法绕过的结构。这就像管理一个新员工你不会指望他背下所有规章制度就永远不犯错而是设计一套流程——每一步都有检查点每个输出都有 schema 校验每次失败都有明确的回退路径。模型负责生成候选答案Harness 负责判断这个答案能不能进入下一步。这个思维转变带来的直接好处是可测试性。纯提示词方案里你很难写单元测试因为输出是自然语言边界模糊。而 Harness 把每个环节的输入输出都定义成结构化数据你就可以像测试普通函数一样测试 Agent 的每个节点。这个项目能堆到 20 万行代码很大程度上就是因为大量代码是在做校验、重试、状态管理和边界处理而不是在写提示词。2.2 为什么选择 Markdown 作为中间表示层热词里反复出现 Markdown、Obsidian、Claude Code这不是巧合。这个项目的一个关键设计决策是把Markdown 作为 Agent 内部和外部沟通的通用中间格式。为什么是 Markdown 而不是 JSON 或 YAML我的理解是这样JSON 适合机器读但对人极不友好一个复杂的 Agent 状态用 JSON 表示人根本没法快速审查。而 Markdown 是人和机器都能读的甜点区——它有结构标题、列表、表格、代码块但又不强制严格语法模型生成起来自然人审查起来轻松。更重要的是Markdown 天然适配 Obsidian 这类知识管理工具意味着 Agent 的产出可以直接沉淀成人类可用的笔记而不是一堆需要二次解析的数据。具体到实现上这个项目大概率是这样做的Agent 的每一步产出都写成 Markdown 片段用特定的标题层级和标记来承载元信息。比如用##表示任务阶段用列表表示待办项用代码块包裹需要执行的命令或代码。Harness 层再写解析器把这些 Markdown 结构还原成可执行的动作。这样做的好处是调试极其方便——出问题的时候你直接打开那个 Markdown 文件就能看到 Agent 当时脑子里在想什么。提示用 Markdown 做中间层有个坑就是换行和空格的语义在不同解析器里不一致。项目里一定要统一一套解析规则最好自己写解析器而不是依赖第三方库否则 markdown 换行这类小问题会在长流程里被无限放大。2.3 Claude Code 与本地模型的混合调用策略热词里既有 Claude Code又有claude code 调用 lmstudio 的本地模型这说明项目在模型选型上是混合策略而不是死磕一个模型。这是被 40 亿 token 逼出来的必然选择。我的经验是Agent 任务可以粗略分成两类需要强推理的决策节点和大量重复的格式化/转换节点。前者必须用强模型后者完全可以用本地小模型甚至规则引擎搞定。一个成熟的 Harness 架构应该能根据任务类型动态路由到不同的模型。比如分析这段代码的潜在 bug走强模型把这段输出转成指定格式走本地模型。这样能把 token 成本压下来一大截同时保持关键环节的质量。Claude Code 在这个项目里的角色我判断是作为开发辅助和部分 Agent 能力的载体。它的优势在于对代码和文件系统的操作能力强适合做需要读写文件、执行命令的任务。而本地模型通过 LM Studio 之类的方式调用则承担那些对延迟不敏感、但对成本敏感的批量任务。这种混合架构的难点在于统一的抽象层——你得设计一套接口让上层 Harness 不关心底层是哪个模型只关心输入输出。这个抽象层本身就是大量代码的来源。3. 20 万行代码都花在哪了拆解真实工作量3.1 状态管理与持久化被低估的吞代码大户很多人以为 Agent 项目的代码量主要在调用模型上实际上调用模型可能只占 5%。真正吃代码的是状态管理。一个长周期 Agent 任务可能持续几小时甚至几天中间涉及几十个步骤每步都有输入、输出、中间产物、错误记录。这些状态怎么存、怎么恢复、怎么在崩溃后接着跑是一整套工程问题。这个项目九个月堆出 20 万行我推测状态管理至少占了三分之一。具体包括任务状态的序列化和反序列化、检查点机制每隔几步存一次快照、断点续跑逻辑、并发任务的状态隔离、以及状态变更的审计日志。这些代码写起来枯燥但缺了任何一块Agent 就没法在真实场景里稳定运行。举个具体例子假设 Agent 正在处理一个需要调用外部工具的任务调用到一半进程崩了。如果没有持久化重启后一切从头开始前面烧的 token 全白费。有了检查点重启后能从最后一个成功步骤继续。这个从哪继续的判断逻辑涉及状态版本管理、幂等性保证、以及外部副作用的回滚每一块都是硬骨头。3.2 工具调用层把不确定性关进笼子Agent 和普通程序最大的区别是它的动作来自模型生成而不是硬编码。这意味着每个工具调用都可能是错的——参数类型不对、必填项缺失、调用了不存在的工具、或者参数值超出合理范围。Harness 架构的核心工作之一就是在模型和真实工具之间加一层严格的校验和转换。这层代码通常包括工具定义的 schema 描述、参数校验器、类型转换器、调用前的预检查、调用后的结果验证、以及失败时的重试和降级策略。我做过统计一个功能完整的工具调用层每个工具平均需要 200 到 500 行代码来包裹。如果项目里有几十个工具光这一块就是上万行。更麻烦的是工具之间的依赖和编排。有些任务需要按特定顺序调用多个工具前一个的输出是后一个的输入。这种编排逻辑如果用代码硬写会非常脆弱如果用声明式的方式描述又需要一套解析和执行引擎。这个项目大概率采用了后者因为声明式的编排更容易让模型参与生成和修改而这正是 Agent 的价值所在。3.3 输出解析与格式修复和模型的不听话长期斗争模型输出格式不对是 Agent 开发里最日常的痛点。你要求它输出 JSON它给你输出带解释文字的 JSON你要求它用特定分隔符它偶尔用中文标点你要求它输出 Markdown 表格它给你来个 markdown 表格转换 excel 都费劲的畸形结构。这些看似小问题在自动化流程里就是致命的。所以这个项目里必然有大量代码在做输出解析和格式修复。策略通常是分层的第一层用严格解析器能过就过第二层用宽松解析器容忍常见偏差第三层用模型自己修复把错误输出和格式要求一起丢回去让它重写第四层才报错并记录。这四层每一层都需要代码而且需要大量测试用例来覆盖各种畸形输出。实操心得格式修复的提示词里一定要给反例。只告诉模型要输出 JSON效果一般告诉它不要输出解释文字不要用 markdown 代码块包裹第一个字符必须是左花括号效果会好很多。这个技巧我在多个项目里验证过能显著降低修复层的触发率。3.4 测试与可观测性让黑盒变成灰盒Agent 系统最难的地方在于它是黑盒——你给它输入它给你输出中间发生了什么很难看清。20 万行代码里必然有相当一部分是在做可观测性日志、追踪、指标、以及回放能力。具体来说每一步模型调用都要记录完整的输入输出、耗时、token 消耗、使用的模型版本。每个工具调用要记录参数、结果、耗时、是否重试。整个任务链路要能串起来形成一个可回放的 trace。这样出问题的时候你能精确知道是哪一步、哪个模型、哪个参数导致的。没有这套东西调试 Agent 就是纯靠猜效率极低。测试方面除了常规的单元测试还需要回归测试集——收集历史上出过问题的案例每次改动后跑一遍确保没有退化。这个测试集本身就是宝贵资产随着项目推进不断积累。我估计这个项目的测试代码占比不会低于 20%因为 Agent 的行为太容易受各种因素影响没有测试兜底根本不敢改代码。4. 每月 40 亿 token 是怎么烧的又怎么省下来的4.1 token 消耗的真实构成40 亿 token 一个月平均每天 1.3 亿多。这个量级如果全部走强模型成本会非常吓人。所以要理解这个数字必须拆开看构成。我的经验是Agent 项目的 token 消耗大致分四块系统提示词、上下文历史、工具定义、以及实际任务内容。系统提示词和工具定义是固定开销每次调用都要带上。如果系统提示词写得很长Agent 项目常见几千 token工具定义又很多那每次调用的基础成本就很高。上下文历史是累积开销随着任务推进不断增长如果不做压缩很快就会撑爆上下文窗口。实际任务内容反而是最不可控的部分。这个项目能把成本控制在可承受范围我推测做了几件事系统提示词精简和缓存很多模型支持提示词缓存重复部分不计费或打折、上下文压缩定期把历史总结成摘要丢弃原始细节、工具定义按需加载不是所有任务都需要所有工具用到才加载、以及前面提到的模型分级路由。4.2 上下文压缩Agent 长任务的生死线上下文窗口是有限的但 Agent 任务可能很长。怎么在有限窗口里塞进足够的信息是 Harness 架构必须解决的问题。常见策略有三种滑动窗口只保留最近 N 轮、摘要压缩把旧内容总结成短摘要、以及检索增强把历史存到外部需要时检索相关片段。这个项目大概率是三者结合。滑动窗口保证最近的上下文完整摘要压缩处理中期历史检索增强应对需要回溯很久之前信息的情况。难点在于摘要的质量——摘要太粗会丢关键信息太细又省不了多少 token。我的做法是让模型在摘要时明确保留决策、结论、未完成事项、关键参数这几类信息其他细节可以丢。这个策略在实测中能把上下文压缩到原来的 20% 到 30%同时保持任务连续性。注意上下文压缩有个隐蔽的坑就是压缩后的摘要如果被反复压缩会像复印件的复印件一样越来越模糊。所以一定要保留原始记录摘要只是给模型看的原始数据要存好必要时能重新生成摘要。4.3 缓存与批处理把重复劳动的成本降到零Agent 任务里有很多重复模式。比如同一个系统提示词在成百上千次调用里反复出现同一批文档的处理逻辑完全一样只是数据不同。这些地方都是优化的空间。提示词缓存是最直接的省钱手段。主流模型厂商都支持对固定前缀做缓存命中缓存的部分按折扣计费。把系统提示词、工具定义这些固定内容放在前面任务相关内容放在后面就能最大化缓存命中率。这个优化做不做成本可能差好几倍。批处理则是另一个维度。如果任务不要求实时响应可以把多个请求打包一起发通常有折扣。这个项目每月 40 亿 token如果有相当比例能走批处理省下来的钱相当可观。当然批处理的代价是延迟所以要区分哪些任务能等、哪些不能等。4.4 失败重试的成本陷阱Agent 项目里有个容易被忽视的成本黑洞失败重试。模型输出格式不对要重试工具调用失败要重试校验不通过要重试。每次重试都是一次完整的模型调用token 照烧。如果重试率是 20%那实际成本比理论值高 25%。控制重试成本的关键是让重试更聪明。不要简单地把同样的输入再发一遍而是把失败原因、期望格式、以及上次的错误输出一起发回去让模型有针对性地修正。同时设置重试上限超过就降级或报错避免无限重试烧钱。我见过最夸张的案例是一个格式问题导致模型重试了十几次一次任务烧掉几十万 token就是因为没有重试上限。5. 一个人怎么扛下这个项目协作与工具链5.1 与 AI 结对把 Claude Code 用成第二双手一个人写 20 万行代码纯靠手敲九个月是绝对不可能的。这个项目的真实工作模式必然是人机结对——人负责架构决策、关键逻辑、以及质量把关AI 负责大量样板代码、测试用例、以及重复性实现。Claude Code 这类工具的价值就在这里它能理解项目上下文按你的意图生成符合风格的代码还能帮你重构和修 bug。但用 AI 写代码有个前提你得能判断它写得对不对。如果自己不懂AI 生成的代码就是定时炸弹。所以这个项目的作者本身必然是有深厚工程功底的AI 只是放大了他的产出效率而不是替代了他的判断。这一点很多人误解以为有了 AI 就能零基础做项目实际上 AI 放大的是能力不是填补空白。我的实操经验是把任务拆成AI 能独立完成的和必须自己把关的两类。前者比如写测试、写文档、写数据转换逻辑直接交给 AI自己抽查。后者比如核心状态机、并发控制、错误处理策略自己设计框架让 AI 填充细节。这样既保证了效率又守住了质量底线。5.2 Obsidian 作为项目大脑知识沉淀决定长期效率热词里 Obsidian 出现频率很高这不是偶然。九个月的项目涉及大量决策、踩坑、方案对比如果这些不沉淀下来很快就会忘记当初为什么这么设计。Obsidian 这类工具的价值就是把这些碎片化的知识组织成可检索、可关联的网络。我推测这个项目的 Obsidian 库里至少有这几类笔记架构决策记录每个重要选择的原因和备选方案、踩坑日志遇到的问题和解决方法、API 和工具的使用笔记、以及任务规划和进度追踪。这些笔记本身就是项目的外脑让作者在九个月里保持思路连贯不至于重复踩同一个坑。实操心得Obsidian 笔记一定要有统一的模板和标签体系否则记多了就变成垃圾堆。我的做法是每篇笔记开头用固定格式写背景、问题、方案、结论四段标签用领域/类型/状态三级结构。这样几个月后回看依然能快速定位。5.3 版本控制与实验管理让每次改动可追溯Agent 项目的特点是改动影响面大——改一个提示词可能影响所有任务的表现。所以版本控制和实验管理极其重要。每次改动都要能追溯每个版本的表现都要能对比。具体做法包括代码用 Git 管理提示词也纳入版本控制不要硬编码在代码里每次重要改动记录变更原因和预期影响建立评估集改动后跑一遍看指标变化。这套流程听起来繁琐但在长周期项目里是保命的。我见过太多项目因为改了一个提示词导致整体退化又找不到是哪个改动引起的最后只能回滚到很久之前。6. 常见问题与排查技巧实录6.1 Agent 跑着跑着就失忆了怎么办这是长任务最常见的症状前面明明确认过的信息后面模型又忘了导致重复询问或做出矛盾决策。根因通常是上下文被压缩或截断关键信息丢失。排查思路先看上下文压缩策略是不是把重要信息压没了再看摘要生成的质量是不是丢了关键结论最后看是否有信息被放在了会被截断的位置。解决方法是把必须记住的信息显式提取出来放在每轮调用的固定位置而不是依赖模型从历史里自己找。这个技巧叫状态外置效果立竿见影。6.2 工具调用参数总是差一点模型生成的工具参数经常出现类型不对、格式不对、或者值不合理的情况。比如要求整数给了字符串要求路径给了描述。这类问题的排查要看是提示词没说清还是校验太宽松。解决分三步第一工具定义里把参数类型、格式、示例写清楚越具体越好第二加严格的校验层不合格直接打回让模型重写第三对高频错误做针对性提示比如路径必须是绝对路径以斜杠开头。实测下来这三步能把参数错误率降到很低。6.3 成本突然飙升怎么定位token 成本突然涨了通常有几个原因重试率上升、上下文变长、或者某个任务进入了死循环。排查要先看监控数据定位是哪个任务、哪个环节消耗异常。常见速查方向我整理成表症状可能原因排查方法解决方向单任务 token 暴涨上下文未压缩看历史长度曲线加压缩策略整体成本上升重试率变高统计重试次数优化提示词和校验某类任务异常进入循环看调用序列加循环检测和上限缓存命中率下降提示词前缀变动对比提示词版本固定前缀内容6.4 模型升级后行为变了模型版本更新是常事但新版本可能在某些任务上表现不同甚至退化。这时候不能盲目升级要先跑评估集对比。我的做法是维护一个黄金测试集包含各类典型任务和边界案例。新模型上线前先跑一遍对比通过率和质量。如果关键指标退化就暂缓升级或者针对新模型调整提示词。这个流程能避免升级即翻车的尴尬。7. 这套架构能复用到哪些场景Harness 架构的价值不限于这一个项目。任何需要模型稳定执行长周期任务的场景都能借鉴这套思路。比如自动化数据处理流水线、智能客服的多轮任务处理、代码生成与审查、以及知识库的自动整理。核心都是把模型的生成能力和工程的确定性结合起来。我个人在实际操作中的体会是Harness 架构的投入产出比在任务越复杂、周期越长的时候越明显。简单任务用纯提示词就够了硬上 Harness 是过度设计。但一旦任务链条超过十步或者需要跨会话保持状态Harness 就是必需品。判断标准很简单如果你发现自己在反复处理模型又抽风了的问题那就是该上 Harness 的时候了。最后再分享一个小技巧Harness 的每个环节都要设计成可单独测试的。不要写一个巨大的函数从头跑到尾而是拆成小步骤每步有明确输入输出。这样出问题能精确定位改动能局部验证整个系统的可维护性会高一个数量级。这个原则我在多个项目里坚持长期看省下的调试时间远超拆分时多花的那点功夫。