1. 一个人九个月二十万行代码这件事到底在说什么先把标题里的数字拆开看。一个人意味着没有团队分工没有前后端联调没有产品经理帮你砍需求也没有测试帮你兜底。九个月大约是 270 天如果按每周工作六天算实际投入大概在 230 个工作日上下。20 万行代码平均到每个工作日接近 870 行。这个数字放在常规业务开发里不算离谱但放在一个人独立完成、还要兼顾架构设计、调试、文档和迭代的场景下就相当夸张了。更关键的是最后那个数字每个月烧掉 40 亿以上的 token。这说明这个项目不是传统意义上的手写业务系统而是一个深度依赖大模型能力、把 Agent 当作核心执行单元的 Harness 架构应用。所谓 Harness 架构简单理解就是“脚手架 编排 约束”三件事的组合。它不是让模型自由发挥而是给模型套上一套可预测、可回滚、可观测的执行框架。你可以把它想象成给一个能力很强但容易跑偏的实习生配了一套标准作业流程什么阶段读什么文件、什么条件下调用什么工具、输出必须符合什么格式、失败之后怎么重试、重试几次之后升级为人工介入。这套东西听起来不复杂但真正落到代码里就是大量的状态机、解析器、校验器、重试策略和日志埋点。20 万行代码里真正跟模型对话的部分可能只占很小一块剩下的大部分都在处理“模型不听话”这件事。这个项目适合谁来参考如果你正在做 AI Agent 相关的产品尤其是那种需要长时间运行、多步骤协作、还要保证输出稳定性的场景那这篇内容会对你有直接帮助。如果你只是刚接触 Agent 开发想了解一个真实项目在工程上要面对什么也可以把它当作一张地图先看清楚坑在哪里再决定自己要不要跳。如果你已经在用 Claude Code、Obsidian 这类工具做个人知识管理或自动化工作流那里面关于 Markdown 处理、插件机制、执行沙盒的部分你会有很强的既视感。我先把结论放在前面这个项目的核心难点从来不是“让模型写出代码”而是“让模型在九个月里持续写出能跑的代码并且每次跑出来的结果都差不多”。前者靠提示词就能糊弄过去后者必须靠 Harness 架构一层一层兜住。下面我会从整体设计、核心细节、实操过程、问题排查四个方向把这个项目拆开讲清楚。2. 整体架构设计与技术选型背后的真实考量2.1 为什么是 Harness 而不是普通 Agent 框架市面上常见的 Agent 框架大多围绕“感知—决策—执行”这个循环来做文章。你给它一个目标它自己拆解步骤自己调用工具自己判断是否完成。这种模式在演示场景里非常好看但一旦放到真实项目里问题会立刻暴露出来模型今天心情好可能三步就做完了明天状态差可能绕了二十步还在原地打转。更麻烦的是你很难知道它到底卡在哪一步因为整个执行过程是一个黑盒。Harness 架构的思路正好相反。它不追求让模型“自由发挥”而是把整个任务拆成一条固定的流水线。每个阶段做什么、输入是什么、输出必须满足什么条件、不满足怎么处理全部由代码写死。模型只负责在某个具体阶段里完成一件具体的事比如“把这段自然语言转成结构化 JSON”或者“根据这份 diff 判断是否引入回归风险”。这样做的好处是执行路径是可枚举的失败点是可以定位的重试策略是可以按阶段定制的。我选择 Harness 而不是通用 Agent 框架根本原因在于这个项目要处理的任务有很强的顺序依赖。比如先生成代码再跑静态检查再跑单元测试再根据失败信息决定是回滚还是修复。这些步骤之间不是简单的“做完一个做下一个”而是后面每一步都可能反过来影响前面的决策。通用 Agent 框架很难表达这种复杂的回退逻辑而 Harness 可以用状态机的方式把每个状态和转移条件都写清楚。2.2 20 万行代码到底花在哪里很多人听到 20 万行代码第一反应是“是不是写了很多重复逻辑”。实际上如果按模块拆开看代码分布大致是这样的模块占比主要职责任务编排与状态机18%定义阶段、转移条件、回滚策略输入输出解析与校验22%解析模型输出、格式校验、错误分类工具调用与沙盒执行15%文件读写、命令执行、资源隔离上下文管理与压缩14%历史裁剪、摘要生成、关键信息保留日志与可观测性12%结构化日志、指标采集、链路追踪提示词模板与版本管理9%模板渲染、变量注入、版本对比配置与插件系统6%外部扩展、热加载、权限控制其他辅助逻辑4%工具函数、类型定义、测试桩从这个分布能看出来真正跟“智能”相关的部分其实不多大部分代码都在做工程上的脏活累活。比如输入输出解析这一块之所以占到 22%是因为模型输出的格式稳定性远没有想象中那么高。你让它输出 JSON它可能给你带一段解释文字你让它只输出代码它可能给你加个 Markdown 代码块标记。这些情况都要在解析层处理掉否则后面所有环节都会被污染。2.3 每月 40 亿 token 是怎么烧掉的40 亿 token 听起来很多但如果拆到每个任务上其实并不夸张。假设一个中等复杂度的任务需要 20 轮模型交互每轮平均消耗 8000 token 的输入和 2000 token 的输出那就是 20 万 token。如果每天跑 200 个这样的任务一天就是 4000 万 token一个月按 30 天算就是 12 亿。再加上重试、上下文压缩、多模型对比这些额外开销40 亿是一个很合理的数字。这里有一个关键设计上下文压缩策略直接决定了 token 消耗量。如果每一轮都把完整历史塞进去token 消耗会指数级增长。我的做法是分层保留最近三轮保留完整内容三到十轮保留摘要十轮以上只保留关键决策点和当前状态。摘要不是简单截断而是用一个小模型专门做信息抽取把“已经确认的事实”和“待解决的问题”分开存储。这样既控制了 token 量又不会丢失关键信息。提示上下文压缩最容易犯的错误是把“模型说过的话”当成“已经确认的事实”。模型在某一轮说“我认为这个函数没有问题”并不代表它真的验证过。只有经过工具验证、测试通过、或者人工确认的信息才能进入“已确认事实”层。3. 核心细节解析与实操要点3.1 Markdown 在 Harness 架构里扮演什么角色这个项目里Markdown 不只是文档格式它同时承担了三个职责任务描述载体、中间产物格式、以及人机交互界面。任务描述用 Markdown 写是因为它既能表达结构化信息表格、列表、代码块又能保留自然语言的灵活性。中间产物用 Markdown是因为模型对 Markdown 的生成质量远高于纯 JSON 或 XML解析成本也更低。人机交互界面用 Markdown是因为最终用户可以直接在 Obsidian 这类工具里查看和编辑。但 Markdown 有一个很麻烦的问题它的语法太宽松了。同样一个表格模型可能给你生成三种不同的写法。同样一个代码块可能带语言标记也可能不带。更麻烦的是换行处理Markdown 里一个换行和两个换行语义完全不同而模型经常在这上面犯错。我的做法是在 Harness 里加一层 Markdown 规范化处理器所有模型输出的 Markdown 先经过这层处理统一换行、统一表格对齐、统一代码块标记然后再进入后续环节。def normalize_markdown(text: str) - str: # 统一换行符 text text.replace(\r\n, \n) # 压缩连续空行 text re.sub(r\n{3,}, \n\n, text) # 规范化代码块标记 text re.sub(r(\w*)\n, lambda m: f{m.group(1) or text}\n, text) # 规范化表格分隔行 text re.sub(r\|[\s-]\|, | --- |, text) return text.strip()这段代码看起来简单但它解决的是最频繁出现的解析失败问题。在没有这层处理之前光是表格解析失败导致的流程中断每天就要发生几十次。3.2 Agent 执行沙盒的设计与边界控制Agent 要执行代码、读写文件、调用外部命令这些操作必须放在沙盒里。沙盒的设计目标不是“完全隔离”而是“可控可观测”。完全隔离意味着 Agent 什么都做不了可控可观测意味着它能在限定范围内自由行动但每一步都有记录、有边界、有回滚方案。我的沙盒实现基于三个原则。第一文件系统访问必须经过路径白名单任何试图访问白名单之外路径的操作都会被拦截并记录。第二命令执行必须经过命令白名单只允许运行预定义的安全命令比如测试框架、静态检查工具、格式化工具。第三所有操作必须产生结构化日志包括操作类型、输入参数、执行结果、耗时、退出码。这些日志不仅是排查问题的依据也是后续优化提示词的素材。注意沙盒的边界控制最容易出的问题是“白名单太宽”。比如你允许执行python命令那 Agent 就可以通过python -c执行任意代码。正确的做法是只允许执行具体的脚本文件并且脚本文件本身也要经过审查。3.3 提示词模板的版本管理与灰度发布提示词是这个项目里最容易被低估的部分。很多人觉得提示词就是一段文字改了就改了。但在一个每天跑几千个任务、每月烧几十亿 token 的系统里提示词的任何改动都可能带来巨大的行为变化。我见过一次因为把“请仔细检查”改成“请务必仔细检查”导致模型过度谨慎任务完成率直接掉了 15%。所以提示词必须像代码一样管理。每个提示词模板都有版本号每次修改都要记录变更原因和预期影响。新版本上线之前先在 5% 的流量上做灰度对比关键指标任务完成率、平均交互轮数、token 消耗量、人工介入率。只有这些指标都不劣化才全量发布。如果出现劣化立刻回滚到上一个版本。指标灰度前灰度后判定任务完成率87.3%86.1%劣化回滚平均交互轮数12.414.7劣化回滚token 消耗/任务18.2 万21.5 万劣化回滚人工介入率6.8%9.2%劣化回滚这张表是一次真实回滚的记录。改动内容只是把提示词里的“检查”改成了“逐项检查”结果模型开始对每个细节都反复确认交互轮数暴涨。这件事让我彻底放弃了“提示词随便改改就行”的想法。4. 实操过程与核心环节实现4.1 从零搭建 Harness 的最小可行路径如果你现在想自己搭一个类似的 Harness 架构我建议不要一上来就追求完整功能。先做一个最小可行版本能跑通“输入任务—模型处理—输出结果”这个基本循环就行。具体步骤是这样的。第一步定义任务的数据结构。一个任务至少包含这些字段任务 ID、任务类型、输入内容、当前状态、历史记录、输出结果、错误信息。用 Python 的 dataclass 或者 TypeScript 的 interface 都可以关键是字段要固定不能随意增减。第二步实现状态机。状态机不需要很复杂一开始只需要三个状态待处理、处理中、已完成。每个状态之间的转移条件写清楚比如“处理中”转到“已完成”的条件是模型输出通过格式校验。第三步接入模型调用。这里要注意的是模型调用必须封装成一个独立模块输入是提示词和上下文输出是结构化结果。不要在业务逻辑里直接调模型 API否则后面换模型或者加缓存会非常痛苦。第四步加日志。日志要记录每个状态的进入时间、离开时间、输入输出摘要。一开始不需要很精细但必须有。没有日志的 Harness 就是一个黑盒出了问题只能靠猜。第五步加一个最简单的重试机制。模型调用失败或者输出格式不对就重试一次。重试两次还不行就标记为失败等待人工处理。这五步做完一个最小可用的 Harness 就跑起来了。后面所有的优化都是在这个基础上叠加。4.2 上下文压缩的具体实现与参数选择上下文压缩是控制 token 消耗的核心手段。我的实现方案是三层结构完整层、摘要层、事实层。完整层保留最近 N 轮对话的完整内容。N 的选择很关键太小会导致模型丢失近期上下文太大会导致 token 消耗过高。我实测下来N3 是一个比较平衡的值。如果任务复杂度很高可以调到 N5但 token 消耗会增加 40% 左右。摘要层保留第 N1 轮到第 M 轮的摘要。M 的选择取决于任务的平均长度。我的项目里大部分任务在 20 轮以内完成所以 M10 就够了。摘要生成用一个小模型提示词是“请用不超过 200 字总结这段对话的关键决策和待解决问题”。摘要质量直接影响后续轮次的准确性所以这个提示词也经过了多次迭代。事实层存储所有经过验证的结论。比如“函数 X 的输入参数是 Y”“测试用例 Z 已经通过”“配置文件 W 的路径是 V”。这些事实用键值对存储每轮对话开始时注入到提示词里。事实层的更新条件是只有经过工具验证或者人工确认的信息才能写入。class ContextManager: def __init__(self, full_window3, summary_window10): self.full_window full_window self.summary_window summary_window self.full_history [] self.summaries [] self.facts {} def add_turn(self, role, content): self.full_history.append({role: role, content: content}) if len(self.full_history) self.full_window: old_turn self.full_history.pop(0) self._maybe_summarize(old_turn) def build_prompt_context(self): parts [] parts.append(已确认事实\n format_facts(self.facts)) parts.append(历史摘要\n \n.join(self.summaries[-3:])) parts.append(最近对话\n format_turns(self.full_history)) return \n\n.join(parts)这段代码的核心逻辑是每次新增一轮对话就把超出完整窗口的最旧一轮拿出来判断是否需要生成摘要。摘要不是每轮都生成而是累积到一定量之后批量生成这样可以减少模型调用次数。4.3 工具调用的错误处理与重试策略工具调用是 Harness 里最容易出问题的环节。文件可能不存在命令可能超时网络可能抖动权限可能不足。每一种错误都需要不同的处理策略。我的做法是把错误分成三类可重试错误、可降级错误、致命错误。可重试错误包括网络超时、临时文件锁、资源暂时不可用这类错误直接重试最多重试三次每次间隔指数退避。可降级错误包括某个工具不可用但可以用替代方案比如格式化工具挂了可以用另一个格式化工具代替。致命错误包括权限不足、磁盘满、配置文件损坏这类错误直接终止任务并报警。错误类型示例处理策略重试次数可重试网络超时指数退避重试3可降级格式化工具不可用切换备用工具1致命权限不足终止并报警0提示重试策略最容易犯的错误是“所有错误都重试”。有些错误重试一百次也不会成功比如权限不足。无脑重试只会浪费 token 和时间还会掩盖真正的问题。4.4 与 Obsidian 的集成方式这个项目的最终输出是 Markdown 文件而 Obsidian 是一个非常适合管理和浏览 Markdown 的工具。集成方式有两种一种是直接写入 Obsidian 的 vault 目录另一种是通过 Obsidian 插件机制做深度集成。直接写入 vault 目录最简单只要文件路径和命名规则符合 Obsidian 的要求就行。但这种方式的问题是Obsidian 不会自动感知文件变化需要手动刷新或者重启。而且如果文件正在被 Obsidian 编辑直接写入可能会导致冲突。深度集成需要开发 Obsidian 插件。插件可以监听文件变化、调用 Harness 的 API、在 Obsidian 界面里展示任务状态。这种方式体验更好但开发成本也更高。我的选择是先做直接写入等核心流程稳定之后再做插件。插件开发中最麻烦的部分是处理 Obsidian 的异步文件系统它的 API 和 Node.js 的 fs 模块不完全一样需要额外封装一层。5. 常见问题与排查技巧实录5.1 模型输出格式不稳定怎么办这是最常见的问题没有之一。模型输出格式不稳定的表现有很多种JSON 里带注释、代码块标记不完整、表格列数对不上、列表缩进混乱。排查思路是先从解析层入手看解析失败的具体原因是什么。如果是因为模型多说了几句话就在提示词里加“只输出结果不要解释”。如果是因为模型对格式理解有偏差就在提示词里给一个完整的示例。但提示词只能解决一部分问题剩下的必须靠解析层的容错能力。我的解析器会尝试多种解析策略先按标准格式解析失败就尝试提取代码块再失败就尝试用正则匹配关键字段最后失败才报错。这种多层容错的设计把格式问题导致的流程中断率从 12% 降到了 1.5% 以下。5.2 任务执行到一半卡住不动了卡住的原因通常有三种模型调用超时但没有设置超时时间、工具调用死锁、状态机进入了一个没有出口的状态。排查方法是先看日志确认最后一个成功执行的动作是什么。如果日志显示模型调用发出去了但没有返回那就是超时问题需要给模型调用加超时和重试。如果日志显示工具调用开始了但没有结束那就是工具本身的问题需要检查工具的超时设置和资源占用。如果日志显示状态机停在了某个状态那就是状态转移条件写错了需要检查那个状态的所有出边条件。我遇到过一次很隐蔽的卡住问题状态机在“等待人工确认”状态但人工确认的入口因为一个前端 bug 没有显示出来。任务就一直等在那里既不超时也不报错。后来加了一个全局超时机制任何状态停留超过 30 分钟就自动标记为异常并报警。5.3 token 消耗突然暴涨怎么排查token 消耗暴涨通常有四个原因上下文压缩失效、重试次数过多、提示词变长、模型切换到了更贵的版本。排查顺序是从上到下先看上下文压缩的日志确认摘要层和事实层是否正常工作。再看重试日志确认是否有某个环节在疯狂重试。然后对比提示词版本看最近有没有改动。最后检查模型配置确认没有意外切换到更贵的模型。我遇到过一次 token 暴涨原因是摘要生成失败后没有降级策略导致每一轮都把完整历史塞进去。修复方法是在摘要生成失败时直接截断历史而不是保留完整历史。虽然截断会丢失一些信息但总比 token 爆炸好。5.4 常见问题速查表问题现象可能原因排查方法解决方案格式解析失败模型输出不规范查看原始输出加解析容错层任务卡住超时未设置查看最后日志加全局超时token 暴涨上下文未压缩查看压缩日志修复压缩逻辑工具调用失败权限或路径问题查看工具日志检查白名单结果不一致提示词版本混乱对比版本号灰度发布插件加载失败依赖缺失查看插件日志补全依赖5.5 几个踩过坑之后才明白的道理第一个道理不要相信模型的“自我检查”。模型说“我已经检查过了没有问题”这句话本身没有任何保证。真正的检查必须由外部工具完成比如静态检查、单元测试、类型检查。模型的自检只能作为辅助不能作为依据。第二个道理日志比调试器好用。在分布式、多阶段、长时间运行的系统里调试器基本用不上。你不可能在一个跑了三个小时的任务上挂调试器。唯一可靠的手段是结构化日志把每个关键节点的输入输出都记下来出问题的时候按时间线回放。第三个道理重试不是万能的。有些错误重试有用有些错误重试只会让情况更糟。区分这两类错误比设计一个复杂的重试策略更重要。第四个道理提示词改动必须灰度。我吃过一次亏改了一个看起来无关紧要的词结果任务完成率掉了 15%。从那以后任何提示词改动都先跑 5% 流量确认指标不劣化再全量。第五个道理沙盒边界要定期审查。随着项目迭代沙盒白名单会越来越长因为每次遇到“这个操作被拦截了”就加一条。时间长了白名单就形同虚设。我的做法是每个月审查一次白名单把不再需要的条目删掉把可以合并的条目合并。6. 一些关于工具链和扩展方向的个人经验Claude Code 在这个项目里主要用来做代码生成和重构。它的优势是对长上下文的理解比较稳定适合处理跨文件的修改。但它的输出格式有时候会带一些额外的解释文字需要在 Harness 里做一层清洗。另外 Claude Code 的桌面版和命令行版行为不完全一致如果要做自动化建议统一用命令行版。Obsidian 在这个项目里主要用来做知识管理和结果浏览。它的插件生态很丰富但插件质量参差不齐。我建议只装必要的插件比如 Markdown 预览增强、表格编辑、任务管理这几类。插件装多了会拖慢启动速度而且插件之间的冲突很难排查。如果遇到插件加载失败先检查 Obsidian 版本和插件版本的兼容性再看插件依赖是否完整。Markdown 表格转 Excel 这个需求我试过几种方案。最简单的是用 Python 的 pandas 直接读 Markdown 表格但 pandas 对表格格式要求比较严格模型生成的表格经常不满足。后来改用自己写的解析器先规范化表格格式再转成 CSV最后用 openpyxl 写入 Excel。这个方案虽然多了一步但稳定性高很多。关于 Agent 框架的选择我的建议是不要盲目追新。每个框架都有自己的设计假设和适用场景。通用 Agent 框架适合做探索性任务Harness 架构适合做生产级任务。如果你的任务需要高稳定性、高可观测性、高可控性那就老老实实搭 Harness。如果你的任务只是偶尔跑一次、结果不要求完全一致那用通用框架更省事。最后分享一个关于 token 成本控制的小技巧把模型调用分成“关键路径”和“非关键路径”。关键路径上的调用用能力最强的模型非关键路径上的调用用便宜的小模型。比如摘要生成、格式校验、日志分析这些完全可以用小模型来做成本能降 60% 以上效果差异在可接受范围内。这个策略的前提是你要能清楚区分哪些调用是关键的哪些不是。区分错了要么成本降不下来要么关键环节出问题。