1. 先搞清楚这个项目到底在做什么一个人九个月20 万行代码每个月消耗 40 亿以上的 token最终交付的是一款基于 Harness 架构的应用。这几个数字摆在一起任何一个写过代码的人都会先愣一下。20 万行代码是什么概念一个中等规模的商业项目五到十人的团队做一年大概也就是这个量级。而这里是一个人九个月还附带每月 40 亿 token 的模型调用量。我第一次看到这组数据的时候第一反应不是厉害而是这到底是怎么组织起来的。先把核心概念说清楚。Harness在这个语境下指的是一种以 AI Agent 为执行核心的应用架构范式。它不是一个具体的框架名字而是一种设计思路把大模型当作一个可以持续调用工具、读写文件、执行命令、自我纠错的执行引擎而应用本身则是一层挽具harness 的本意就是马具、挽具负责给这个引擎套上约束、提供上下文、管理状态、控制流程。你可以把它理解成模型是马harness 是缰绳、鞍具和车厢三者合起来才能拉货上路。这个项目之所以值得拆解是因为它踩中了当下 AI 应用开发最核心的几个痛点上下文怎么管、工具怎么调、状态怎么存、错误怎么恢复、成本怎么控。20 万行代码里真正调用模型 API 的部分可能不到 2000 行剩下的 99% 全都在处理模型之外的事情——文件读写、Markdown 解析、Agent 循环控制、插件加载、错误重试、日志追踪、成本统计。这才是 Harness 架构的真实工作量分布。适合读这篇内容的人有三类。第一类是正在做 AI Agent 应用开发、被上下文和状态管理折磨得够呛的工程师第二类是用过 Claude Code、Obsidian 这类工具想搞清楚它们底层是怎么跑起来的进阶用户第三类是对一个人能不能扛起一个大项目这件事感兴趣、想看看真实工程组织方式的独立开发者。不管你是哪一类接下来的内容都会围绕真实可复现的架构决策和实操细节展开不讲空话。2. Harness 架构的整体设计与思路拆解2.1 为什么是 Harness而不是传统的 MVC 或微服务传统应用架构的核心假设是逻辑是确定的。你写一个 if-else它就一定走 if 或 else。但 AI 应用的核心假设恰恰相反逻辑是不确定的。同一个输入模型这次给你返回一段 JSON下次可能返回一段带解释的 JSON再下次可能直接给你一段自然语言。这种不确定性用 MVC 那套 Controller 分发、Model 处理、View 渲染的模式根本兜不住。Harness 架构的本质是在不确定的模型输出和确定的系统行为之间架一层确定性的外壳。这层外壳要做四件事约束输出格式通过 prompt 模板、schema 校验、重试机制把模型的自由输出收敛成系统能处理的结构化数据。管理执行循环Agent 不是调用一次就完事而是要思考—行动—观察—再思考循环往复。这个循环的终止条件、最大轮次、超时控制全在 harness 里。维护状态与上下文模型本身没有记忆每一轮对话都是全新的。harness 要负责把历史对话、文件内容、工具返回结果按优先级和 token 预算裁剪后塞进上下文窗口。提供工具接口模型要读写文件、执行命令、搜索网络这些能力都得由 harness 以工具tool的形式暴露出去并处理调用结果。我试过用纯 MVC 的思路去套一个 Agent 项目结果就是 Controller 里塞满了 prompt 拼接和 JSON 解析Model 层根本不知道该存什么View 层更是无从谈起。换成 Harness 思路之后整个项目被切成三层执行层Agent Loop、能力层Tools、状态层Context Storage每一层的职责边界非常清晰。2.2 20 万行代码到底花在哪了很多人看到 20 万行这个数字第一反应是是不是注水了。我拆过类似规模的项目可以负责任地说这个量级在 Harness 架构下是合理的。大致分布是这样的模块预估代码量占比核心职责Agent 循环与调度8%主循环、终止条件、并发控制、超时重试工具系统22%文件读写、命令执行、搜索、Markdown 解析上下文管理18%token 预算、历史裁剪、优先级排序、摘要压缩状态与持久化15%会话存储、检查点、恢复、版本管理插件与扩展12%插件加载、沙箱隔离、生命周期管理错误处理与日志10%异常捕获、重试策略、追踪、成本统计UI 与交互10%命令行界面、进度展示、Markdown 渲染配置与初始化5%环境检测、依赖校验、参数解析注意工具系统占了 22%这是最容易被低估的部分。一个能读写 Markdown 文件的工具听起来简单但你要处理编码问题、换行符差异Windows 的 CRLF 和 Unix 的 LF、大文件分块读取、并发写入冲突、路径穿越安全校验。光是一个 Markdown 表格的解析和转换就够写上千行。2.3 每月 40 亿 token 背后的成本逻辑40 亿 token 一个月平均每天 1.3 亿如果按 8 小时工作算每小时 1600 万 token。这个量级说明 Agent 在持续不断地读写上下文。token 消耗的大头从来不是用户输入而是上下文重放。每一轮 Agent 循环都要把之前的历史重新塞进去历史越长消耗越大而且是平方级增长。所以 Harness 架构里最值钱的设计就是上下文压缩策略。我实测下来一个设计良好的压缩策略能把 token 消耗降低 60% 到 80%。具体做法包括对历史对话做滚动摘要、对文件内容做增量读取而非全量重放、对工具返回结果做截断和结构化提取。这些策略的实现正是那 18% 上下文管理代码的核心价值。提示不要等到 token 账单爆炸了才想起来优化上下文。在项目第一天就把 token 预算和压缩策略设计进去后期改造成本极高。3. 核心细节解析与实操要点3.1 Agent 主循环终止条件比循环本身更重要Agent 主循环的伪代码看起来很简单while not done: response model.chat(context) if response.has_tool_call: result execute_tool(response.tool_call) context.append(result) else: done True但真正难的是done这个条件怎么判断。我踩过的坑包括模型陷入无限循环、反复调用同一个工具、输出了看似完成实则半成品的答案。一个健壮的终止条件至少要包含四重判断显式完成信号模型明确输出任务完成或返回最终答案。最大轮次限制硬性上限比如 50 轮超过就强制终止并返回当前最佳结果。重复检测连续三轮调用相同工具且参数相同判定为死循环中断。超时控制单次任务总时长超过阈值比如 10 分钟强制终止。这四重判断缺一不可。我见过只做最大轮次限制的项目结果模型在第 49 轮还在原地打转白白烧掉几十万 token。3.2 工具系统的设计接口要窄实现要厚工具系统的设计原则是接口窄、实现厚。所谓接口窄是指暴露给模型的工具描述要尽可能简单明确参数越少越好。所谓实现厚是指工具内部的容错、校验、日志要做得非常充分。以文件读取工具为例暴露给模型的接口可能只有两个参数{ name: read_file, parameters: { path: string, max_lines: integer, optional } }但内部实现要处理路径合法性校验防止读取系统敏感文件、文件不存在时的友好提示、超大文件的分块策略、编码自动检测、二进制文件的识别与拒绝。这些逻辑加起来一个 read_file 工具写 500 行代码很正常。注意工具的错误返回信息要写给模型看不是写给人看。返回 File not found 模型可能不知道怎么处理返回 File not found at /path/to/file. Available files in directory: a.md, b.md 模型就能自己纠正路径。3.3 上下文管理token 预算的分配艺术上下文窗口是有限资源怎么分配是门学问。我的做法是给不同来源的内容设定优先级和预算上限内容类型优先级预算占比压缩策略系统提示词最高5%不压缩当前任务描述最高10%不压缩最近 3 轮对话高30%不压缩历史对话摘要中20%滚动摘要文件内容中25%增量读取工具返回结果低10%截断结构化这个分配不是拍脑袋定的是根据实际运行数据调出来的。核心思路是越近的、越相关的、越不可再生的内容优先级越高。历史对话可以摘要文件内容可以重新读但当前任务描述丢了整个任务就废了。3.4 Markdown 处理被低估的工程难点这个项目里 Markdown 是核心数据格式因为 Agent 的输入输出、笔记存储、文档生成全都围绕 Markdown 展开。但 Markdown 的处理远比想象中复杂。换行就是第一个坑Markdown 规范里单个换行不产生新段落要两个换行才行但很多用户习惯单换行分段。表格是第二个坑Markdown 表格转换成 Excel 或 CSV 时单元格内的竖线和换行需要转义处理不当就串行。我处理 Markdown 的经验是解析用成熟库生成自己写。解析方面Python 的 markdown-it-py、JavaScript 的 markdown-it 都很成熟不要自己造轮子。但生成方面因为要控制格式、处理特殊字符、保证幂等性自己写反而更可控。特别是数学公式行内公式用$...$块级公式用$$...$$生成时要确保转义正确否则渲染出来就是一堆乱码。4. 实操过程与核心环节实现4.1 环境搭建与依赖管理项目起步阶段环境搭建的稳定性直接决定后续开发效率。我的建议是用容器化环境不要裸装。原因很简单Agent 项目依赖多、版本敏感裸装环境一旦污染排查成本极高。基础环境清单运行时Python 3.11 或 Node.js 20选你熟悉的但一定要锁定小版本。模型接入通过统一的 API 网关层接入不要在各个模块里直接调模型 SDK。存储本地用 SQLite 存会话状态文件用普通文件系统不要一上来就上数据库集群。日志结构化日志JSON 格式方便后续做成本分析和问题追踪。依赖管理用 lock 文件锁定版本这一点在 Agent 项目里尤其重要因为模型 SDK 更新频繁一个小版本升级可能就改了 API 签名。4.2 Agent 循环的完整实现我把 Agent 循环拆成五个阶段每个阶段都有明确的输入输出阶段一上下文组装。从状态层读取历史按预算裁剪拼装成模型能接受的格式。这一步的关键是幂等性同样的状态必须组装出同样的上下文否则调试时根本无法复现问题。阶段二模型调用。带上工具定义发起请求。这里要处理超时、限流、重试。重试策略用指数退避但要注意不是所有错误都值得重试。网络超时可以重试参数错误重试多少次都没用。阶段三响应解析。判断模型是返回了工具调用还是最终答案。工具调用的参数要做 schema 校验校验失败就把错误信息塞回上下文让模型重新生成。阶段四工具执行。在沙箱里执行工具捕获所有异常把结果结构化后返回。执行要有超时防止某个工具卡死整个循环。阶段五状态更新。把本轮对话、工具结果写入状态层更新 token 消耗统计判断是否满足终止条件。这五个阶段循环执行直到终止条件触发。整个循环的代码量不大但每个阶段的边界处理代码量很大这就是为什么 Agent 循环本身只占 8% 代码量但周边支撑代码占了绝大部分。4.3 插件系统的加载与隔离Harness 架构的一大优势是可扩展而扩展靠的就是插件系统。但插件系统也是故障高发区常见的 harness failed to load plugins 错误八成是插件依赖冲突或加载顺序问题。我的插件系统设计遵循三条规则插件声明式注册插件通过配置文件声明自己提供哪些工具、依赖哪些能力而不是靠代码里的隐式导入。加载失败不影响主流程某个插件加载失败记录日志后跳过主程序照常运行。沙箱隔离插件运行在受限环境里不能随意访问文件系统和网络需要的能力通过宿主提供的接口申请。插件加载的顺序也很关键。我遇到过插件 A 依赖插件 B 提供的工具但加载顺序反了导致 A 初始化失败。解决办法是拓扑排序根据插件声明的依赖关系算出加载顺序有环就报错。4.4 成本统计与 token 追踪每月 40 亿 token如果不做精细统计根本不知道钱花在哪了。我在项目里做了一个 token 追踪模块记录每一次模型调用的输入 token 数、输出 token 数、调用时间、所属任务、所属阶段。这些数据写入本地数据库可以按天、按任务、按阶段聚合分析。实测下来这个模块帮我发现了几个成本黑洞某个工具返回结果没有截断单次返回 5 万 token某个任务的上下文压缩策略失效历史无限增长某个重试逻辑没有上限失败任务反复重试烧钱。没有追踪数据这些问题根本发现不了。提示token 追踪要记录到调用级别不要只记录任务级别。任务级别的统计粒度太粗定位不到具体问题。5. 常见问题与排查技巧实录5.1 插件加载失败怎么排查harness failed to load plugins 是最常见的报错之一。排查顺序建议这样走看日志插件加载器通常会打印失败原因先看是找不到文件、依赖缺失还是初始化异常。单独加载把可疑插件单独拿出来加载排除相互干扰。检查依赖插件的依赖版本是否和主程序冲突特别是共享库的版本。检查权限插件目录的读写权限、执行权限是否正常。检查配置插件的配置文件格式是否正确路径是否写对。我遇到过一次诡异的问题插件在开发机上正常部署到服务器就加载失败。最后发现是服务器上文件系统大小写敏感而插件配置里路径大小写写错了。这种问题只能靠仔细核对。5.2 Agent 执行中断的常见原因agent execution terminated due to error 这个报错背后可能有很多原因我整理了一张速查表现象可能原因排查方法循环突然停止达到最大轮次限制查看轮次计数日志报工具调用错误工具参数 schema 不匹配打印模型原始输出对比 schema报上下文超限token 预算计算错误检查上下文组装逻辑报网络错误API 限流或超时查看重试日志和响应码无任何输出模型返回空响应检查模型服务状态和请求参数结果不完整终止条件误判检查完成信号识别逻辑排查这类问题的核心思路是先定位是模型的问题还是 harness 的问题。方法很简单把模型的原始响应打印出来。如果原始响应就是错的那是模型或 prompt 的问题如果原始响应正常但后续处理出错那是 harness 的问题。5.3 上下文超限的应急处理上下文超限是 Agent 项目的经典问题。应急处理方案是立即截断最老的历史保证当前任务能继续。但这是治标不治本根本解决要靠压缩策略。我的压缩策略分三级一级压缩对超过 5 轮的历史对话做摘要保留关键决策和结论丢弃中间过程。二级压缩对文件内容做增量读取只保留当前任务相关的片段。三级压缩对工具返回结果做结构化提取只保留模型需要的关键字段。三级压缩全开的情况下上下文能压缩到原始大小的 20% 左右而且任务完成质量基本不受影响。5.4 实操心得几个反直觉的经验第一个反直觉的经验模型不是越强越好。强模型贵、慢而且在小任务上未必比弱模型好。我的做法是任务分级简单任务用便宜模型复杂任务才上强模型。实测成本能降一半以上。第二个反直觉的经验prompt 不是越长越好。我早期喜欢把各种规则、示例、约束全塞进系统提示词结果模型反而抓不住重点。后来精简到只保留最核心的规则效果反而更好。系统提示词控制在 500 token 以内是我试出来的甜点区。第三个反直觉的经验错误处理不是越多越好。过度防御会让代码臃肿而且很多错误处理逻辑本身就有 bug。我的原则是能重试的重试不能重试的快速失败失败信息要清晰。不要试图处理所有可能的错误那是不可能的。6. 工具选型与生态整合6.1 Claude Code 与本地模型的接入Claude Code 是很多人接触 Agent 开发的入口它的设计思路对 Harness 架构很有参考价值。但实际使用中很多人会遇到订阅访问受限的问题这时候可以考虑接入本地模型。接入本地模型的关键是统一接口层不管后端是云端模型还是本地模型对上层暴露的接口要一致。本地模型的优势是成本可控、数据不出本地劣势是能力上限低、推理速度慢。我的做法是混合调度简单任务走本地模型复杂任务走云端模型通过一个路由层自动分发。路由规则可以基于任务类型、上下文长度、历史成功率来动态调整。6.2 Obsidian 作为知识库的整合Obsidian 是 Markdown 笔记工具里的标杆它的插件生态和本地文件存储方式非常适合作为 Agent 的知识库。整合的关键是双向同步Agent 生成的笔记要能写入 Obsidian 库Obsidian 里修改的笔记要能被 Agent 读取。实现上直接操作 Obsidian 库的 Markdown 文件即可不需要依赖 Obsidian 的 API。但要注意几点Obsidian 的链接语法[[...]]要正确处理frontmatter 的 YAML 格式要保留附件目录的路径要维护。我踩过的坑是 Agent 写入笔记时覆盖了用户手动添加的 frontmatter后来改成合并写入才解决。6.3 Markdown 工具链的选型Markdown 处理工具链的选型我建议按用途分开解析markdown-itJS或 markdown-it-pyPython成熟稳定。渲染markdown preview enhanced 这类工具适合预览但程序化渲染建议用库。转换Markdown 转 Excel 或 CSV用 pandoc 或自己写解析器注意表格转义。数学公式KaTeX 或 MathJax前者快后者全按需选择。选型的核心原则是解析和渲染分离不要用渲染器做解析。很多工具既能解析又能渲染但它们的解析结果往往带有渲染相关的信息不适合做数据处理。7. 一个人扛大项目的工程组织方式7.1 模块化与接口先行一个人做 20 万行代码的项目最大的敌人是复杂度失控。我的应对方式是接口先行每个模块先定义接口接口稳定后再实现。这样即使实现改了只要接口不变其他模块就不受影响。接口定义要写文档但不要写那种大而全的文档写最小可用文档这个模块做什么、输入什么、输出什么、有什么副作用。三句话能说清就别写三页。7.2 测试策略重点覆盖核心路径一个人没时间写全量测试我的策略是重点覆盖核心路径。Agent 循环、上下文组装、工具执行这三个核心路径必须有测试其他模块靠集成测试兜底。测试用例不用多但每个都要能复现真实场景。我特别推荐录制回放测试把真实的模型响应录下来测试时回放这样测试不依赖模型服务速度快、结果稳定。模型升级后重新录制一遍即可。7.3 版本管理与发布节奏九个月 20 万行代码版本管理必须严格。我的做法是小步快跑每个功能独立分支完成后合并主干每周打一个版本。版本号用语义化版本破坏性变更必须升大版本。发布节奏上我建议先内部用再小范围试用最后才对外。Agent 应用的不确定性高直接对外发布容易翻车。内部用一个月把明显的问题都暴露出来再考虑对外。7.4 持续迭代的心法最后分享一个心法不要追求一次做对追求快速迭代。Agent 应用的效果高度依赖 prompt 和上下文策略这些东西没法一次设计到位只能靠不断试错。我的做法是建立一个实验框架每次调整策略都跑一遍标准测试集对比效果。这样迭代有数据支撑不会凭感觉瞎改。九个月下来我改了上百次 prompt重构了三次上下文管理工具系统推倒重来过一次。这些迭代如果靠拍脑袋早就迷失方向了。有实验框架每次改动都有明确的收益或损失方向自然就清晰了。这个项目后续还可以这样扩展把工具系统做成插件市场让社区贡献工具把上下文压缩策略做成可配置的适配不同场景把成本追踪做成可视化面板实时监控 token 消耗。这些都是我一个人做不完但很有价值的方向。