Harness架构：一个人九个月20万行代码的Agent工程实践

1. 先搞清楚这个20万行代码到底在说什么第一次看到一个人、九个月、20万行代码、每月40亿token这组数字我的第一反应不是震撼而是怀疑。九个月按270天算20万行代码意味着平均每天要产出740行有效代码还要同时消耗每月40亿token的模型调用量。这个量级放在任何团队里都算高强度一个人扛下来要么是天才要么是数字游戏。但仔细拆解之后我发现这组数字背后真正值得聊的不是卷而是一种全新的应用架构范式——Harness架构。它和传统意义上的写一个App完全是两回事。传统应用是你写逻辑、写界面、写数据流代码量直接对应功能复杂度。而Harness架构下你写的绝大部分代码是给Agent搭脚手架定义工具、定义约束、定义状态机、定义回滚策略、定义上下文注入规则。真正干活的是模型你写的是让模型能稳定干活的马具。这就是Harness这个词的来源。它不是框架不是SDK更像是一整套把大模型拴住、让它按轨道跑的工程体系。你给它套上缰绳、眼罩、鞍具它才能拉车而不是乱跑。20万行代码里可能只有不到两万行是业务逻辑剩下十八万行全是这套马具的零件。我之所以对这个标题感兴趣是因为过去一年我自己的项目也在往这个方向迁移。从最早的prompt拼字符串到后来的function calling再到现在的多Agent编排状态持久化工具沙箱每一步都在增加Harness的厚度。所以这篇我想把Harness架构拆开讲清楚它到底由哪些层组成、为什么一个人能撑起这么大的代码量、40亿token到底烧在哪里、以及如果你也想做类似的东西应该从哪一层开始下手。适合读这篇的人有三类一是正在做Agent应用、感觉代码越写越乱的开发者二是想理解为什么Agent项目代码量会爆炸的技术负责人三是对Claude Code、Obsidian这类工具链感兴趣、想自己搭一套个人知识Agent的进阶用户。不要求你会写Harness但至少要跑通过一次Agent调用否则后面很多细节会没有体感。2. Harness架构的六层结构为什么代码量会指数级膨胀2.1 从调API到养Agent的认知转变大多数人第一次接触Agent都是从一段几十行的脚本开始的拼一个system prompt塞几个工具定义循环调用模型直到它不再请求工具。这段代码跑通只要半小时但它离能用的产品差着十万八千里。差距在哪在于不确定性。模型每次输出都可能不一样工具调用可能失败上下文可能超长用户可能中途改需求网络可能抖动模型可能陷入死循环。传统应用里这些是异常分支写几个try-catch就完事。Agent应用里这些是常态你必须为每一种不确定性准备一套应对机制而这些机制本身就是代码。我自己的项目从最初800行脚本膨胀到后来的六万多行中间经历了三次重构。每一次重构都不是因为功能变多而是因为要让它在真实场景下稳定跑这件事本身太耗代码。这就是Harness架构代码量膨胀的根本原因你写的不是功能是容错。2.2 六层结构拆解把Harness架构拆开大致能分成六层。每一层都有它存在的理由也都能解释为什么代码量会往上翻。层级职责典型代码占比关键难点模型接入层多模型路由、重试、限流、成本统计8%不同厂商API差异、流式解析上下文管理层历史压缩、检索注入、token预算22%压缩策略、相关性排序工具执行层工具注册、沙箱、权限、超时25%安全隔离、并发控制状态与记忆层会话持久化、长期记忆、回滚18%一致性、快照粒度编排与调度层多Agent协作、任务分解、仲裁17%死锁、循环检测观测与评估层日志、追踪、自动评测、告警10%评测集构建、指标设计这张表是我自己项目跑下来统计的不一定适用于所有人但比例关系大体靠谱。可以看到上下文管理、工具执行、状态记忆这三层加起来占了65%而这三层恰恰是传统应用里几乎不存在的部分。2.3 上下文管理层最容易被低估的代码黑洞很多人以为上下文管理就是把历史消息拼起来发过去。真做起来你会发现光是什么时候该压缩历史这一个问题就能写出几千行代码。我踩过的第一个坑是早期我用的策略是超过阈值就摘要压缩。结果发现摘要本身会丢信息模型经常忘记用户三句话前提过的关键约束。后来改成分层压缩——最近N轮原文保留中间M轮做结构化摘要更早的做向量检索按需召回。这一改代码量直接翻了三倍因为你要处理摘要的粒度怎么定、结构化摘要的schema怎么设计、检索的query怎么生成、召回的内容怎么和当前上下文融合、融合后超长怎么办。再往后是token预算。40亿token一个月听起来夸张但如果你每个请求都塞满上下文一天几千次调用就能烧掉几千万。所以你必须做预算分配system prompt占多少、工具定义占多少、历史占多少、检索结果占多少、留给输出的空间占多少。这套预算逻辑要动态调整还要能根据任务类型切换策略。这部分代码不写成本就失控写了就是几千行的策略引擎。2.4 工具执行层安全与并发的双重绞杀工具执行层是Harness架构里最工程的部分。一个工具从注册到执行中间要过好几道关参数校验、权限检查、沙箱隔离、超时控制、结果截断、错误包装、重试决策。我印象最深的一次事故是一个文件写入工具没有做路径规范化模型传了个带../的路径差点把项目外的文件覆盖了。从那以后我加了一整套路径白名单规范化符号链接检查的逻辑光这一块就写了四百多行。你可能觉得夸张但真实场景下模型会传各种你想不到的参数防御性代码必须写足。并发控制也是大头。多个Agent同时调用同一个工具时怎么保证不冲突我的做法是给每个工具打上可并发/需串行/需独占的标签配一个调度器。调度器要处理优先级、超时、取消、死锁检测。这套东西写下来又是两三千行。2.5 状态与记忆层快照粒度决定回滚能力Agent执行到一半失败了怎么办传统应用里你重试就行Agent应用里重试可能意味着重复执行副作用操作。所以你需要状态快照能在失败时回滚到某个检查点。快照粒度是个权衡粒度太细存储爆炸粒度太粗回滚后要重做很多。我的方案是工具调用边界快照——每次工具调用前存一次状态调用后存一次结果。这样回滚时能精确到某一次调用。听起来简单但实现起来要处理状态怎么序列化、大对象怎么处理、快照怎么清理、跨会话怎么恢复。这部分代码量在1.5万行左右是我项目里第二大的模块。长期记忆更麻烦。用户上周说过偏好这周怎么让模型想起来你需要一套记忆的写入、索引、召回、衰减机制。写入时要判断这条信息值不值得记索引时要选embedding模型召回时要排序和去重衰减时要定期清理。每一环都是代码。2.6 编排层与观测层让多Agent不打架当你从单Agent走向多Agent编排层的复杂度会跳一个数量级。任务怎么分解、子任务怎么分配、Agent之间怎么通信、结果怎么合并、冲突怎么仲裁、循环怎么检测——每一个问题都能写出一篇论文。我自己的做法比较土用一个显式的任务图DAG来编排每个节点是一个Agent任务边是依赖关系。调度器按拓扑序执行遇到循环就报错。这套东西不优雅但可控。观测层则是把每一步的输入输出、耗时、token消耗、工具调用都记下来方便事后分析。没有观测层你根本不知道40亿token烧在哪。3. 40亿token的账钱到底花在哪几个环节3.1 拆解token消耗结构每月40亿token按主流模型的价格算成本是六位数人民币级别。这个数字吓人但拆开看其实有迹可循。我按自己的项目做了个估算模型消耗环节占比说明上下文重复发送45%每轮对话都要重发历史工具定义注入12%工具越多每轮注入越多检索结果注入15%RAG召回的内容模型实际推理18%真正思考的部分重试与失败重放10%失败后的重复调用最扎眼的是上下文重复发送占45%。这是Agent应用的结构性问题每一轮对话你都要把之前所有历史重新发一遍。对话越长浪费越大。一个20轮的对话第20轮发送的token里可能有90%是重复的。3.2 缓存是省钱的命门解决重复发送的核心手段是prompt caching。主流模型厂商都支持对system prompt和稳定前缀做缓存缓存命中的部分按折扣价计费。我实测下来把system prompt、工具定义、固定知识库这三块做成缓存前缀后整体成本降了约40%。但缓存有坑一是缓存有TTL过期就失效二是缓存前缀必须完全一致改一个字符就全部失效三是不同厂商的缓存策略不一样有的按前缀匹配有的要显式标记。我踩过的坑是把动态内容比如当前时间放进了system prompt导致缓存永远不命中。后来把动态内容全部挪到用户消息里缓存命中率才上去。3.3 上下文压缩的收益计算压缩历史是另一个省钱大头。我的策略是超过8轮的对话把第3轮到第N-4轮压缩成结构化摘要。摘要用便宜的小模型生成成本可以忽略。压缩后长对话的token消耗能降60%以上。但压缩有信息损失。我的经验是约束类信息不能压事实类信息可以压。比如用户要求输出必须是JSON这种约束压缩后模型经常忘而用户提到过三个文件名这种事实压缩成用户提到了若干文件问题不大。所以我的压缩器会先做信息分类约束类原样保留事实类才压缩。3.4 工具定义的瘦身工具定义注入占12%看起来不多但工具一多就很恐怖。我项目里有40多个工具每个工具的定义平均200token一轮就是8000token。如果对话20轮光工具定义就烧了16万token。瘦身办法有几个一是按需注入根据当前任务类型只注入相关工具二是定义精简把描述写短参数用简写三是工具分组把相关工具合并成一个带action参数的工具。我用的是第一种第三种组合工具定义注入量降了70%。3.5 重试成本的控制重试占10%这部分最冤。失败重放意味着同样的token再烧一遍。控制重试成本的关键是快速失败能在本地校验的错误不要发给模型能在工具层拦截的异常不要触发重试。我加了一层预检在调用模型前先做参数合法性、权限、配额检查不合格直接返回错误让模型重新生成而不是执行后再失败。这一层把重试率从15%降到了4%。4. 一个人怎么撑起20万行工程方法论4.1 模块化是唯一的出路一个人写20万行代码如果不做模块化三个月后自己都看不懂。我的做法是按Harness六层严格分模块每层内部再按职责分子模块模块之间只通过明确定义的接口通信。具体到目录结构大概是这样的harness/ model/ # 模型接入层 router.py providers/ streaming.py context/ # 上下文管理层 compressor.py retriever.py budget.py tools/ # 工具执行层 registry.py sandbox.py scheduler.py state/ # 状态与记忆层 snapshot.py memory.py orchestration/ # 编排层 dag.py arbiter.py observability/ # 观测层 tracer.py evaluator.py每个模块都有独立的测试模块内部可以随便重构只要接口不变就不影响其他部分。这套结构让我在九个月里重构了四次核心逻辑但每次都能控制影响范围。4.2 用Agent写Agent自举开发20万行代码一个人写纯手写不可能。我的核心方法是用Agent辅助开发。具体来说我把开发任务也做成了一套Harness定义好代码规范、测试要求、提交格式然后让Claude Code这类工具按规范生成代码我做review和集成。这里的关键是规范要写成机器可读的形式。我把代码风格、命名约定、错误处理模式、测试模板都写成了配置文件Agent生成代码时会读取这些配置。这样生成的代码一致性很高我review的成本大幅降低。实测下来这套自举开发能让我的产出效率提升3到4倍。20万行里大概有60%是Agent生成后我修改集成的40%是我手写的核心逻辑。核心逻辑必须手写因为那部分是Harness的灵魂Agent理解不了全局设计意图。4.3 测试策略Agent项目的测试和传统项目不一样传统项目测试是输入A期望输出B。Agent项目里模型输出是不确定的你没法断言精确输出。我的测试策略分三层第一层是工具层单测这部分是确定性的按传统方式写覆盖率要求80%以上。第二层是流程层集成测试用mock模型替换真实模型验证编排逻辑、状态流转、错误处理是否正确。这层测试跑得快每次提交都跑。第三层是端到端评测用真实模型跑一批标准任务用LLM-as-judge打分。这层跑得慢、成本高每天跑一次。评测集我维护了200多个任务覆盖常见场景和边界情况。4.4 版本管理与回滚Agent项目的版本管理有个特殊问题模型版本变了行为就变了。同一个prompt模型升级后可能输出格式就不一样了。所以我的做法是把模型版本也纳入版本管理每次模型升级都要跑一遍完整评测确认没有回归才切换。回滚策略上我保留了最近三个版本的完整快照包括代码、配置、prompt、评测结果。出问题时能快速定位是哪个版本引入的。5. 工具链选型Claude Code、Obsidian与Markdown的三角关系5.1 Claude Code在开发流中的定位Claude Code在我的工作流里扮演结对程序员的角色。它的优势是能直接读写文件、执行命令、理解项目结构。我用它做三件事生成样板代码、重构重复逻辑、写测试。但Claude Code有个坑它默认会热情过度你让它改一个函数它可能顺手把整个文件重构了。我的应对是在项目根目录放一个CLAUDE.md明确写清楚只改指定范围不要动其他代码。这个文件会被自动读取效果立竿见影。另一个经验是任务要拆小。让Claude Code一次做一件事做完review完再做下一件。一次给它一个大任务它容易跑偏而且出错后很难定位。5.2 Obsidian作为知识底座Obsidian在我的架构里是长期记忆的存储层。所有项目文档、决策记录、踩坑笔记都存在Obsidian库里用Markdown格式。这样做的好处是纯文本、可版本控制、可被Agent直接读取。我写了个小插件把Obsidian库的索引暴露给Harness的检索层。Agent需要背景知识时通过检索层从Obsidian库里召回相关笔记。这套东西替代了传统的向量数据库方案因为我的知识量不大几千篇笔记用文件系统关键词检索就够了还省了维护向量库的成本。Obsidian的双链特性在这里特别有用。笔记之间的关联关系本身就是一张知识图谱检索时可以顺着链接扩展召回质量比纯向量检索好。5.3 Markdown作为Agent的通用语整个Harness架构里Agent之间、Agent与人类之间的通信格式我统一用Markdown。原因有三一是模型对Markdown的理解最好生成质量最高二是人类可读调试方便三是结构化程度够用标题、列表、表格、代码块能表达大部分语义。但Markdown有个坑表格和代码块的解析。模型生成的Markdown经常有格式问题比如表格列数不匹配、代码块没闭合。我在Harness里加了一层Markdown规范化器专门修复这些常见问题。这层代码不复杂但省了很多下游解析的麻烦。5.4 工具链的协同这三者怎么协同我的流程是在Obsidian里记录需求和设计用Claude Code实现代码实现过程中的决策和踩坑再记回Obsidian。Harness运行时从Obsidian检索背景用Markdown格式和模型交互模型生成的代码通过Claude Code落地。这套流程跑顺之后我的思考-实现-记录形成了一个闭环知识不会丢代码有据可查。6. 踩过的坑与实测经验6.1 上下文超长的隐蔽陷阱最常见的坑是上下文悄悄超长。你以为自己控制了token但实际发送时超了模型要么报错要么截断。我踩过一次检索层召回的内容没做长度检查某次召回了一篇超长笔记直接把上下文撑爆模型返回了截断的输出我还以为是模型能力问题排查了两小时才发现。解决办法是在发送前做一次硬校验统计实际token数超了就按优先级裁剪。裁剪顺序是检索结果→历史→工具定义→system prompt。system prompt永远不裁。6.2 工具调用的死循环模型有时候会陷入工具调用死循环调用A→失败→重试A→失败→重试A……我遇到过最夸张的一次一个工具连续被调用了47次。后来加了调用频率限制同一个工具在同一个任务里连续失败3次就强制中断把错误返回给模型让它换策略。还有一个变种是A调B、B调A的循环。这个更隐蔽因为每次调用都成功了。我的检测方法是记录调用图如果出现环就告警。6.3 状态快照的存储爆炸快照粒度太细会导致存储爆炸。我一开始每次工具调用都存全量状态结果一天下来存了几十个G。后来改成增量快照只存变化的部分恢复时按顺序重放。存储量降了90%。但增量快照有个问题重放时间长。我的折中是定期全量中间增量比如每10次调用存一次全量中间存增量。恢复时从最近的全量开始重放。6.4 模型升级导致的回归模型升级是Agent项目最大的隐性风险。我遇到过三次一次是模型升级后工具调用格式变了一次是输出风格变了导致解析失败一次是模型变聪明了反而不再按我预设的步骤走。应对方法是锁定模型版本升级前跑全量评测。评测集要覆盖所有关键场景任何一项回归都不能升级。评测集本身也要定期更新把线上发现的新问题加进去。6.5 成本失控的预警机制40亿token不是一天烧出来的是慢慢涨上去的。如果没有预警等你发现时账单已经吓人了。我设了三道预警日消耗超阈值告警、单次调用超阈值告警、缓存命中率低于阈值告警。这三道预警帮我抓到了好几次异常消耗。7. 如果你也想做从哪一层开始7.1 最小可行Harness不要一上来就搭六层。我的建议是从工具执行层上下文管理层开始这两层是Harness的核心也是最能体现价值的部分。模型接入层可以用现成的SDK状态层可以先用文件系统凑合编排层单Agent阶段不需要观测层用日志先顶着。最小可行的Harness大概长这样一个工具注册器、一个上下文预算器、一个执行循环。代码量控制在2000行以内能跑通模型调用工具→工具返回结果→模型继续这个基本循环就行。7.2 逐步加厚跑通最小版本后按这个顺序加厚先加状态快照解决失败回滚再加检索解决长期记忆再加编排解决多任务最后加观测解决调优。每加一层都要确保前一层稳定不要同时加多层。7.3 不要重复造轮子有些东西不用自己写模型SDK用官方的、向量检索用现成的、日志用标准库。自己写的应该是和你的业务强相关的部分你的工具、你的上下文策略、你的编排逻辑。通用能力尽量用现成的。7.4 评测先行在写第一行Harness代码之前先建评测集。评测集是你的北极星没有它你不知道自己改的东西是变好还是变坏。评测集不用大20到50个任务就够起步但要覆盖你的核心场景。8. 这套架构的边界与后续演进Harness架构不是银弹。它的代价是复杂度高、开发慢、维护成本大。如果你的场景简单比如就是问答或者单轮生成完全不需要Harness直接调API就行。Harness的价值在复杂、长周期、多步骤、需要稳定性的场景。我自己的判断是当你的Agent任务需要超过5步、涉及超过3个工具、或者需要跨会话保持状态时Harness架构才开始划算。低于这个复杂度用简单的脚本prompt工程更高效。后续演进方向上我在关注几个点一是自适应Harness让架构能根据任务复杂度自动调整厚度二是跨模型可移植让Harness不绑定特定模型三是评测自动化减少人工维护评测集的成本。最后分享一个我自己的体会做Harness架构最难的从来不是写代码而是想清楚每一层该管什么、不该管什么。边界划清楚了代码自然就顺边界模糊写多少行都是乱的。我前三个月写的代码后来几乎全重构了就是因为边界没想清楚。如果你准备开始先花一周时间画架构图比急着写代码值。