Harness架构实战：一个人九个月如何用AI Agent流水线交付20万行代码

1. 先搞清楚这个项目到底在做什么一个人九个月20 万行代码每个月消耗 40 亿以上的 token最终交付的是一款基于 Harness 架构的应用。这几个数字放在一起第一反应大概率是这不可能第二反应是就算可能代码质量能看吗。我一开始也是这个反应直到我把这套东西的架构思路、工具链和实际运行方式完整拆了一遍才发现它背后的逻辑其实非常清晰——它不是靠一个人硬写 20 万行而是靠一套高度工程化的 Agent 流水线把写代码这件事本身变成了可编排、可复用、可观测的流程。先把核心概念对齐一下不然后面全是雾水。Harness在这个语境里不是某个具体产品名而是一种架构范式它指的是把大模型能力、工具调用、上下文管理、任务编排、结果校验这几件事用一个统一的骨架串起来让 Agent 能在一个受控的运行时里持续干活。你可以把它理解成给 AI 装了一个工作台——模型是工人Harness 是工作台加流水线加质检员。而Agent是跑在这个工作台上的具体执行单元它有自己的目标、工具集和记忆。两者的区别用一句话说Harness 是场地和规则Agent 是场上踢球的人。这个项目之所以值得拆是因为它踩中了当前 AI 工程化最真实的一个痛点单次对话能解决的问题早就解决了真正难的是让 AI 连续九个月、跨几十万行代码、保持上下文一致地干活。这中间涉及 token 成本控制、上下文压缩、Markdown 作为中间表示层、Claude Code 作为执行入口、Obsidian 作为知识库底座等一系列具体工程决策。适合谁来参考如果你正在做 AI Agent 相关的项目或者想搞清楚一个人怎么用 AI 撑起一个中型项目这篇内容基本能给你一套可抄的作业。我下面会按整体设计思路 → 核心细节 → 实操落地 → 踩坑排查这个顺序展开中间会穿插大量参数选择、成本计算和实际配置尽量做到你看完能直接上手改自己的项目。2. 整体架构设计与关键选型逻辑2.1 为什么是 Harness 架构而不是裸调 API很多人做 AI 项目的第一反应是直接调模型 API写个循环就完事。这个做法在 demo 阶段没问题但一旦项目周期拉长到几个月问题会集中爆发上下文窗口爆掉、工具调用状态丢失、错误无法回溯、成本失控。Harness 架构的核心价值就是把这些脏活从业务逻辑里剥离出来做成一层稳定的运行时。具体来说这套架构通常包含四个层次。最底层是模型接入层负责统一不同模型的调用接口和重试策略往上是上下文管理层处理历史消息的压缩、摘要和检索再往上是工具执行层管理 Agent 能调用的所有工具文件读写、命令执行、搜索等最顶层是任务编排层决定什么时候调哪个 Agent、传什么上下文、怎么校验结果。这四层分开之后每一层都可以独立优化比如你想换模型只动接入层想改压缩策略只动上下文层。提示Harness 架构最大的坑是过度设计。我见过有人一上来就搭四层结果项目还没跑起来光架构代码就写了上万行。建议先用最简版本跑通一个完整任务再逐层加。2.2 20 万行代码是怎么长出来的这里必须澄清一个误解20 万行不是手写的也不是模型一次性生成的而是在九个月里通过数千次 Agent 任务累积出来的。每一次任务可能生成几十到几百行经过校验后合入代码库。按九个月 270 天算平均每天新增约 740 行这个量级对一个持续运行的 Agent 流水线来说完全合理。关键在于每次任务的粒度控制。粒度太粗模型容易跑偏生成一堆用不上的代码粒度太细任务调度开销会吃掉大部分收益。实践中比较稳的做法是单个任务对应一个明确的函数或一个独立模块输入输出都有清晰契约。这样即使某次生成质量差影响范围也可控回滚成本低。2.3 每月 40 亿 token 的成本账怎么算40 亿 token 听起来吓人但拆开看就清楚了。假设九个月里平均每月有 20 个工作日每天跑 200 次 Agent 任务每次任务平均消耗 10 万 token包含上下文、工具返回、生成内容那一天就是 2000 万 token一个月 4 亿九个月 36 亿——和 40 亿基本吻合。所以这个数字不是烧钱而是高频小任务的自然累积。成本控制的核心不在单次调用省钱而在减少无效调用。我实测下来最有效的三个手段是第一给每个任务设置明确的终止条件避免 Agent 无限循环第二上下文压缩要激进历史消息超过阈值就摘要别舍不得第三工具返回结果要裁剪比如读文件只返回相关片段不要整个文件塞回去。这三条做好token 消耗能降 40% 以上。成本控制手段预估节省比例实施难度任务终止条件15%-25%低上下文激进压缩20%-30%中工具返回裁剪10%-20%低模型分级调用15%-30%中2.4 Markdown 为什么成了中间表示层这个项目里 Markdown 不只是文档格式而是Agent 之间传递信息的通用语言。原因很实际Markdown 结构清晰、模型理解成本低、人类也能直接读、还能被 Obsidian 这类工具直接索引。Agent 生成的任务计划、执行日志、代码说明、知识沉淀全部用 Markdown 存形成了一条从临时上下文到长期知识库的通路。这里有个细节值得说Markdown 的换行和表格语法在不同解析器里行为不一致Agent 生成时如果不管这个后续解析会出各种幺蛾子。我的做法是统一用一套严格的 Markdown 规范比如表格必须对齐、换行统一用空行分隔、图片路径统一用相对路径。这套规范写进 Agent 的 system prompt 里生成质量会稳定很多。3. 核心工具链的配置与实操要点3.1 Claude Code 作为执行入口的配置细节Claude Code 在这个项目里承担的是手的角色——Agent 想好了要做什么具体执行靠它。安装和配置这块不同系统差异不小。Ubuntu 下相对简单装完 Node 环境后直接全局安装即可Windows 下建议走 WSL原生环境的路径和权限问题会浪费你大量时间。配置的核心是权限边界。Claude Code 默认会问你很多确认这在交互式使用时没问题但在 Agent 自动运行时会把流程卡死。我的做法是预先配置好允许的操作白名单比如允许读写项目目录、允许执行特定命令其他一律拒绝。这样既保证自动化流畅又不至于让 Agent 乱动系统文件。# 典型的项目级配置思路示意 # 允许的操作范围限定在项目目录内 # 命令执行限定在白名单内 # 网络访问默认关闭按需开启注意卸载 Claude Code 时记得清理配置目录否则残留的配置会影响下次安装。这个坑我踩过重装后行为诡异排查了半天才发现是旧配置没清干净。3.2 Obsidian 知识库的搭建思路Obsidian 在这里的作用是长期记忆的载体。Agent 每次任务产生的有价值信息会被整理成 Markdown 笔记存进 Obsidian 库下次任务需要时再检索出来。这就解决了大模型记不住的问题——不是靠模型记而是靠外部知识库记。搭建时几个关键点。第一目录结构要提前规划好建议按项目 / 模块 / 主题三级划分别一股脑全堆根目录。第二插件选择要克制Git 插件用于版本管理是刚需其他花哨的插件能少则少插件越多启动越慢、冲突越多。第三笔记命名要有规范建议用日期-主题-状态的格式方便检索和排序。Obsidian 的 docxer 这类插件用于格式转换时要注意中英文混排的序号问题自动编号经常乱。我的经验是转换前先把 Markdown 里的列表结构规整一遍转换后再人工过一遍别指望全自动。3.3 Markdown 作为 Agent 通信协议的规范设计前面提到 Markdown 是中间表示层这里展开说规范怎么定。核心原则是机器可解析优先人类可读其次。具体包括标题层级严格用##和###不用#表格必须有表头分隔行代码块必须标注语言链接和图片用标准语法不用 HTML 混排。为什么这么严因为 Agent 之间传递信息时解析失败会导致整个任务链断掉。我遇到过因为一个表格少了分隔行导致下游 Agent 把整个表格当成普通文本处理结果数据全丢的情况。规范定好之后这类问题基本绝迹。3.4 工具选型对比为什么是这套组合工具承担角色选它的理由替代方案Claude Code执行入口工具调用能力强生态成熟其他 CLI Agent 工具Obsidian知识库本地 Markdown可 Git 管理其他本地笔记工具Markdown通信协议通用、可读、易解析JSON、YAMLHarness 架构运行时骨架分层清晰可独立优化自研单体框架选型逻辑其实就一条每一层都选最成熟、最不容易出意外的方案。一个人做项目没有团队帮你兜底稳定性比先进性重要得多。4. 完整实操流程与关键环节实现4.1 从零搭建 Harness 运行时的步骤第一步搭最小可运行版本。不要一上来就搞四层架构先写一个能跑通接收任务 → 调模型 → 执行工具 → 返回结果的单文件脚本。这个脚本可能只有一两百行但它是后面所有扩展的基础。第二步加上下文管理。当单次任务能跑通后你会发现多轮任务之间上下文会丢。这时候引入一个简单的上下文存储可以是内存里的字典也可以是文件。关键是让 Agent 能记得上一次做了什么。第三步加任务编排。当你有多个 Agent 需要协作时需要一个调度器决定谁先谁后、传什么参数。这一步最容易过度设计建议先用最简单的顺序执行跑通了再考虑并行和条件分支。第四步加结果校验。Agent 生成的东西不能直接用必须有校验环节。校验可以是规则校验比如代码能不能编译也可以是模型校验让另一个 Agent 检查。这一步是保证 20 万行代码质量的关键。4.2 单次 Agent 任务的完整生命周期一次典型任务从触发到结束大概经历这几个阶段。任务解析把自然语言需求转成结构化任务描述。上下文组装从知识库和最近历史里捞出相关信息拼成 prompt。模型调用发给模型拿到生成结果。工具执行如果模型要求调工具执行并返回结果可能需要多轮。结果校验检查生成内容是否符合预期。知识沉淀把有价值的信息写回 Obsidian。状态更新记录任务完成情况供后续任务参考。这个流程里最容易出问题的是上下文组装和结果校验。上下文组装不好模型会答非所问结果校验不严错误会累积。我的做法是给这两个环节单独写测试用例每次改架构都跑一遍确保不退化。4.3 参数选择与成本计算的实际过程以一次代码生成任务为例算一下 token 消耗。假设 system prompt 2000 token任务描述 500 token检索到的相关知识 3000 token最近历史 2000 token工具定义 1500 token合计输入约 9000 token。模型生成代码平均 1500 token如果触发两轮工具调用每轮工具返回约 1000 token那总消耗约 9000 1500 2000 1500 14000 token。按每天 200 次任务算一天 280 万 token一个月约 5600 万九个月约 5 亿——这比 40 亿少很多说明实际任务比这个复杂或者任务次数更多。反推一下要达到 40 亿要么任务次数是每天 1500 次左右要么单次消耗是 14 万 token 左右。结合20 万行代码这个产出我倾向于认为单次任务消耗更高因为复杂任务的上下文和工具调用轮次都会显著增加。这个计算过程的意义在于你得知道自己项目的 token 花在哪才能优化。4.4 知识沉淀与检索的实现细节Obsidian 库里的笔记怎么被 Agent 用起来核心是检索。最简单的做法是关键词匹配但效果一般。好一点的做法是把笔记做向量化用语义检索。再进一步是混合检索关键词和语义结合。我的实践经验是笔记数量在几千条以内时关键词加简单语义检索就够了不用上复杂的向量数据库。笔记数量上万后才需要考虑专门的检索方案。另外笔记的更新策略很重要——过时的笔记要及时标记或删除否则会污染检索结果。我一般给每条笔记加一个最后验证日期超过三个月的笔记检索时降权。5. 常见问题与排查技巧实录5.1 Agent 执行中断的典型原因agent execution terminated due to error 这个报错我见过太多次原因五花八门。最常见的是工具调用超时比如执行一个耗时命令超过了设定的超时阈值。其次是上下文超限prompt 太长被模型拒绝。还有权限不足Agent 想读写某个文件但被系统拦了。排查思路是分层看先看错误发生在哪个阶段模型调用、工具执行、结果校验再看具体错误信息。我一般会在 Harness 里加详细的日志每个阶段进出都记一笔出问题时能快速定位。没有日志的 Agent 系统排查起来就是盲人摸象。5.2 上下文丢失与记忆错乱的解决多轮任务跑久了Agent 会忘记之前做过什么甚至把不同任务的信息混在一起。这是上下文管理的经典问题。解决办法有三层短期靠上下文窗口内的历史中期靠任务级的摘要长期靠 Obsidian 知识库。关键是摘要的质量。摘要太简信息丢失摘要太详等于没压缩。我的经验是摘要保留做了什么、为什么这么做、结果如何三要素具体代码和细节不放摘要里需要时从知识库检索。这样摘要能压缩到原文的 10% 左右效果还不错。5.3 Markdown 解析异常的排查清单异常现象可能原因解决方法表格解析错乱缺少表头分隔行强制生成分隔行换行丢失用了单换行统一用空行分隔代码块未识别未标注语言强制标注语言图片路径失效用了绝对路径统一相对路径列表嵌套错乱缩进不一致统一缩进规范这张表是我踩坑踩出来的基本覆盖了 90% 的 Markdown 解析问题。建议把它写进 Agent 的 system prompt让生成时就规避。5.4 成本失控的预警与止损成本失控通常不是突然发生的而是慢慢涨上去的。预警信号包括单次任务 token 消耗持续上升、任务重试率变高、上下文长度接近上限。发现这些信号就要及时干预。止损手段我按优先级排先砍掉不必要的工具调用再压缩上下文再降低模型规格最后才是减少任务量。前三个手段通常能解决问题不用走到最后一步。另外建议设置每日 token 预算超了就暂停避免一觉醒来账单爆炸。5.5 一个人维护大项目的经验教训九个月一个人扛下来最大的体会是自动化程度决定可持续性。凡是需要手动做的事迟早会成为瓶颈。测试要自动跑部署要自动做知识沉淀要自动写连代码审查都要尽量让 Agent 先过一遍。第二个体会是文档比代码重要。20 万行代码三个月后你自己都记不清某段是干嘛的。所以每个模块必须有说明每个决策必须有记录这些文档就存在 Obsidian 里随时能查。第三个体会是别追求完美。一个人做项目资源有限该妥协就妥协。代码能跑就行架构够用就行别为了优雅把项目拖死。我见过太多人卡在重构上最后项目黄了。最后分享一个我一直在用的小技巧每周花半小时回顾 Agent 的执行日志找出最常失败的任务类型针对性优化。这个习惯坚持下来系统的稳定性会肉眼可见地提升。项目后续如果要扩展我建议优先做两件事——把知识库检索做得更智能以及把任务编排做得更灵活这两块是当前最影响效率的瓶颈。