1. 这个项目到底在做什么先把“Harness 架构应用”翻译成人话一个人九个月二十万行代码每个月消耗四十多亿 token最终交付的是一款基于 Harness 架构的应用。这组数字第一次看到的时候我盯着屏幕愣了几秒——不是因为二十万行代码有多夸张而是“一个人”和“四十亿 token”这两个量级放在一起说明这个人几乎把整个开发流程都外包给了 AI Agent自己只负责架构决策、方向把控和最后的验收。这已经不是传统意义上的“写代码”而是“指挥一支 AI 工程队”。先把 Harness 这个词说清楚。在 AI Agent 开发的语境里Harness 指的是包裹在大模型外面的一整套运行时框架——它负责管理上下文、调度工具调用、维护会话状态、处理错误重试、控制 token 预算、协调多个 Agent 之间的协作。你可以把它理解成汽车的底盘和传动系统大模型是发动机Harness 是把发动机的动力真正传导到轮子上的那套机械结构。没有 Harness模型再强也只是一台空转的引擎有了 Harness它才能稳定地跑起来、转弯、刹车、载货。这个项目之所以值得拆解是因为它踩中了当下 AI 应用开发最核心的几个命题如何让 Agent 长时间稳定运行而不失控、如何在 token 成本和质量之间找到平衡、如何用 Markdown 这类轻量格式承载复杂的知识结构、如何把 Claude Code、Obsidian 这类工具串成一条完整的工作流。这些命题不是理论问题是每一个真正在做 Agent 项目的人每天都要面对的。适合读这篇内容的人有三类。第一类是想从零搭建 Agent 应用的开发者你需要知道 Harness 层到底要处理哪些脏活累活。第二类是在用 Claude Code、Obsidian 做知识管理和自动化的人你想知道怎么把这些工具的能力边界推到更远。第三类是纯粹好奇“一个人怎么用 AI 干出二十万行代码”的从业者你想看清楚这套工作流的真实成本和真实瓶颈在哪里。不管你是哪一类接下来的内容都会围绕一个核心问题展开当 AI 成为主要生产力人的角色到底变成了什么。2. 为什么是 Harness 架构方案选型背后的真实考量2.1 不用现成 Agent 框架自己搭 Harness 的理由市面上现成的 Agent 框架不少从早期的 LangChain 到后来的各种 Agent 编排工具开箱即用的东西很多。但这个项目选择自己搭 Harness背后有几个很实际的考量。第一是控制粒度。现成框架为了通用性往往把很多决策封装在内部你只能通过配置项去影响它。但当一个项目跑到二十万行代码、每月四十亿 token 的规模时任何一个被封装掉的细节都可能变成成本黑洞。比如上下文裁剪策略通用框架可能默认保留最近 N 轮对话但你的项目可能需要根据任务类型动态决定保留哪些历史、丢弃哪些历史。这种级别的控制只有自己写 Harness 才能做到。第二是错误恢复。Agent 长时间运行最怕的不是单次调用失败而是失败之后状态错乱。自己搭 Harness 可以把状态机设计成可回滚的每一步操作都有明确的检查点和恢复路径。现成框架的错误处理往往是“重试三次然后放弃”这在生产环境里是不够的。第三是token 预算管理。四十亿 token 一个月是什么概念按主流模型的定价粗略估算这是一笔相当可观的月度支出。自己搭 Harness 可以在调用层面做精细的预算控制——哪些任务用强模型、哪些任务用轻量模型、哪些任务可以缓存结果不重复调用。这些优化在通用框架里很难做到极致。提示自己搭 Harness 不是因为它更简单恰恰是因为它更难但更可控。如果你只是做一个 demo用现成框架完全够用。但如果你要跑一个长期项目Harness 层的自主权会决定你的成本上限和质量下限。2.2 Harness 架构的核心分层设计一个能扛住长期运行的 Harness通常需要分成几层来设计。这个项目的架构思路我根据常见实践和热词里透露的信息还原成下面这个分层模型。层级职责关键设计点接入层接收任务、解析意图、路由到对应 Agent支持多种输入格式Markdown 是主要载体调度层管理 Agent 生命周期、任务队列、并发控制状态机驱动支持暂停/恢复/回滚执行层实际调用模型、执行工具、处理返回token 预算控制、重试策略、结果校验记忆层维护短期上下文和长期知识库与 Obsidian 等工具集成Markdown 存储观测层记录运行日志、token 消耗、错误统计可追溯、可分析、可优化这个分层不是拍脑袋想出来的而是被实际需求逼出来的。比如记忆层单独拆出来是因为 Agent 运行时间一长上下文管理就成了最大的瓶颈。你不能把所有历史都塞进 prompt那样 token 消耗会爆炸你也不能完全丢弃历史那样 Agent 会失忆。所以需要一个独立的记忆层用 Markdown 文件作为长期存储按需检索、按需注入。调度层用状态机驱动是因为 Agent 执行任务时经常需要“暂停等待人工确认”或者“失败后从某个检查点恢复”。没有状态机这些场景很难优雅处理。执行层的 token 预算控制则是直接对应那每月四十亿的消耗——没有这层控制成本会失控。2.3 Markdown 作为核心数据格式的深层原因热词里反复出现 Markdown 相关的搜索markdown 换行、markdown 语法、markdown 表格转换 excel、markdown 表格复制、markdown 阅读器、markdown preview enhanced。这说明这个项目里 Markdown 不只是文档格式而是核心的数据交换格式。为什么选 Markdown因为它是人和 AI 都能高效读写的最轻量格式。JSON 对机器友好但对人不够直观富文本对友好但机器解析麻烦Markdown 刚好在中间——结构清晰、纯文本、易于 diff、易于版本控制、易于被模型理解和生成。在这个项目里Markdown 承担了几个关键角色。第一是任务描述载体每个任务用 Markdown 写清楚目标、输入、输出、约束条件。第二是知识存储格式长期记忆以 Markdown 文件形式存在 Obsidian 库里Agent 需要时读取相关文件。第三是结果输出格式Agent 产出的内容以 Markdown 呈现方便人工审阅和后续处理。注意Markdown 的换行和表格语法是高频踩坑点。不同解析器对换行的处理不一致表格的列对齐和转义也有坑。在 Harness 里最好统一用一套解析库并且在写入时做规范化处理避免因为格式问题导致 Agent 读取失败。3. 核心细节拆解二十万行代码是怎么被“指挥”出来的3.1 Claude Code 在流程中的真实定位热词里 Claude Code 出现频率极高claude code 安装、claude code 下载、claude code 使用、vscode 配置 claude code、vscode 安装 claude code、claude code desktop 国内下载。这说明 Claude Code 是这个项目的主力工具之一。但 Claude Code 在这个项目里的定位不是“自动写代码的机器人”而是一个可以被 Harness 调度的执行单元。区别在于如果你直接打开 Claude Code 让它写一个功能它是被动的、一次性的但如果你把 Claude Code 接入 Harness让它接收结构化任务、返回结构化结果、失败时能被重试、成功时能被记录它就变成了流水线上的一个工位。具体怎么接入常见做法是通过命令行调用或者 API 封装把任务以 Markdown 格式传给 Claude Code让它按照预设的模板输出代码和说明。Harness 负责在调用前后做上下文注入和结果校验。这样做的关键收益是可追溯——每一行代码是谁在什么上下文下生成的、经过了哪些校验、关联哪个任务全部有记录。这里有个实操心得Claude Code 在长会话里容易“跑偏”生成的内容越来越偏离初始目标。解决办法是在 Harness 里强制每次调用都重新注入核心约束不要依赖会话历史来维持方向。宁可多花一点 token 做上下文重置也不要让 Agent 在错误的方向上越走越远。3.2 Obsidian 作为长期记忆库的用法Obsidian 在这个项目里的角色是长期记忆的物理载体。热词里有 obsidian 教程、obsidian 下载、obsidian 安装、obsidian 插件推荐、obsidian 创建项目管理台账、obsidian 的 docxer 怎么用、codex obsidian、weknora 和 obsidian。这些搜索说明很多人在尝试把 Obsidian 接入 AI 工作流。这个项目的做法我推测是这样的Obsidian 库里的每个 Markdown 文件代表一个知识单元可能是项目文档、可能是历史决策记录、可能是代码片段库。Harness 的记忆层通过文件系统读取这些 Markdown根据当前任务的相关性检索出需要的文件注入到 Agent 的上下文里。这样做的好处是记忆和推理分离。模型不需要把所有知识都记在参数里它只需要在需要的时候读取相关文件。这大大降低了上下文压力也让知识更新变得简单——改一个 Markdown 文件就行不需要重新训练或微调。实操中要注意的是检索策略。Obsidian 库文件一多怎么快速找到相关文件就成了问题。常见做法是用文件名、标签、双向链接做索引Harness 根据任务关键词匹配相关文件。更进阶的做法是用向量检索把 Markdown 内容做 embedding按语义相似度召回。但向量检索会增加复杂度和成本项目早期用关键词匹配往往就够了。提示Obsidian 的双向链接功能在构建知识图谱时非常有用。在 Harness 里可以利用双向链接关系做上下文扩展——找到相关文件后顺藤摸瓜把链接指向的文件也纳入上下文往往能提供更完整的背景信息。3.3 Agent 执行流程的完整拆解一个任务从进入到完成在 Harness 里通常要经过这些环节。我用一个具体的例子来说明假设任务是“给项目添加一个用户配置模块”。第一步是任务解析。Harness 接收到 Markdown 格式的任务描述解析出目标、约束、预期输出。这一步要做的关键判断是这个任务需要哪些上下文是全新功能还是修改现有代码涉及哪些文件第二步是上下文组装。根据任务解析结果从记忆层检索相关文件——可能是现有的配置模块代码、可能是项目的架构文档、可能是之前的类似任务记录。把这些内容组装成 Agent 能理解的 prompt。第三步是Agent 调度。选择合适的执行单元。简单任务用轻量模型复杂任务用强模型。Claude Code 适合需要写代码的任务其他 Agent 可能适合文档生成或代码审查。第四步是执行与监控。Agent 开始工作Harness 实时监控 token 消耗、执行时长、是否触发错误。如果超出预算或超时触发中断和重试。第五步是结果校验。Agent 返回结果后Harness 要做基本校验——格式是否正确、是否包含预期内容、是否有明显错误。校验不通过则触发重试或人工介入。第六步是记忆更新。任务完成后把关键信息写回记忆层——更新项目文档、记录决策理由、保存代码片段。这样下一个相关任务就能用到这次的经验。这个流程看起来步骤多但每一步都是被实际问题逼出来的。少了任何一步长期运行都会出问题。比如少了结果校验错误会累积少了记忆更新Agent 会重复犯同样的错。3.4 Token 消耗的构成与优化空间每月四十亿 token这个数字需要拆开看才能理解钱花在哪里了。粗略估算token 消耗主要来自几个部分。消耗来源占比估算优化方向上下文注入40%-50%精准检索避免注入无关内容代码生成20%-30%任务拆分减少单次生成量结果校验与重试10%-15%提高首次成功率减少重试记忆更新与索引5%-10%批量处理异步执行其他开销5%日志、监控等上下文注入占大头这符合直觉——Agent 每次执行都需要大量背景信息。优化空间也主要在这里检索越精准注入的无关内容越少token 消耗越低。这也是为什么记忆层的设计如此关键。代码生成部分的优化思路是任务拆分。不要让 Agent 一次生成几百行代码而是拆成多个小任务每个任务生成一个函数或一个模块。这样单次生成的 token 量可控出错也容易定位。重试部分的优化靠提高首次成功率。这需要好的 prompt 设计、清晰的约束条件、充分的上下文。首次成功率从 70% 提升到 90%重试消耗就能减少三分之二。4. 实操过程还原从零到二十万行的关键节点4.1 项目启动阶段的架构决策任何长期项目启动阶段的决策都会影响后续所有工作。这个项目在启动时有几个关键决策值得参考。第一个决策是确定 Harness 的边界。哪些事情由 Harness 做哪些事情交给 Agent 做哪些事情人工做。边界不清会导致职责混乱——要么 Harness 管太多变得臃肿要么 Agent 承担太多容易失控。常见的划分是Harness 管流程、管状态、管预算Agent 管具体的内容生成人工管方向决策和最终验收。第二个决策是确定数据格式。前面说了 Markdown 是核心格式但具体怎么组织需要提前定好。任务描述用什么模板、知识文件用什么结构、代码片段怎么标注这些都要在启动阶段定下来。后期再改格式迁移成本很高。第三个决策是确定工具链。Claude Code 负责代码生成Obsidian 负责知识管理可能还有其他工具负责测试、部署、监控。工具之间的接口要提前设计好避免后期集成时发现对不上。注意启动阶段最容易犯的错是“先跑起来再说”。对于短期项目这没问题但对于要跑九个月的项目前期多花一周做架构设计后期能省下几个月填坑的时间。4.2 中期迭代中的成本控制实战项目跑到中期代码量上来之后token 成本会成为最敏感的问题。这个阶段的核心工作是持续优化 token 效率。一个有效的做法是建立 token 消耗的监控看板。按任务类型、按 Agent、按时间段统计 token 消耗找出异常高的部分。比如某个类型的任务突然消耗飙升可能是上下文注入出了问题检索到了不相关的大文件。另一个做法是缓存重复结果。很多任务在本质上是一样的比如“检查代码风格”“生成单元测试”。这些任务的结果可以缓存相同输入直接返回缓存结果不重复调用模型。缓存命中率哪怕只有 20%也能省下可观的 token。还有一个做法是分级使用模型。不是所有任务都需要最强的模型。简单的格式转换、内容提取用轻量模型就够只有复杂的推理和生成才用强模型。Harness 里可以根据任务类型自动路由到不同模型。4.3 后期稳定性的保障措施项目跑到后期代码量大了Agent 之间的依赖多了稳定性就成了首要问题。这个阶段的重点是防止系统性崩溃。第一道防线是限流和熔断。当某个 Agent 连续失败或者 token 消耗异常自动暂停它的任务避免问题扩散。这就像电路里的保险丝烧断了保护整个系统。第二道防线是状态快照。定期保存 Harness 的完整状态包括任务队列、Agent 状态、记忆层索引。出问题时可以从快照恢复不用从头再来。第三道防线是人工检查点。关键决策点设置人工确认比如架构变更、大规模重构、删除文件。Agent 可以提议但最终执行需要人点头。这看起来降低了自动化程度但实际上避免了灾难性的自动错误。4.4 一个人如何管理二十万行代码这是最核心的问题一个人怎么管得过来二十万行代码答案是他不管代码他管流程。代码是 Agent 生成的人不需要逐行阅读。人需要做的是定义任务、设定约束、检查结果、调整方向。这更像是一个技术负责人的角色而不是一个程序员。具体来说每天的工作可能是这样的早上检查昨晚 Agent 的运行报告看有没有异常然后规划今天的任务把大目标拆成小任务写进 Harness中间抽查几个关键任务的输出质量晚上总结当天的进展更新项目文档。代码本身人只在出问题时才深入查看。这种工作方式对能力的要求变了。以前要求写得快、写得好现在要求想得清楚、说得明白、判断得准。你得能把模糊的需求翻译成精确的任务描述得能判断 Agent 的输出是对是错得能在多个方案之间做出取舍。写代码的能力依然重要但更重要的是架构能力和判断力。5. 常见问题与排查技巧实录5.1 Agent 执行中断与错误恢复热词里有 agent execution terminated due to error、codex 无法发送消息、显示更新 agent 沙盒、harness failed to load plugins。这些都是实际运行中高频出现的问题。Agent 执行中断的原因通常有几类。第一类是上下文超限注入的内容太多超出了模型的上下文窗口。解决办法是优化检索策略只注入最相关的内容。第二类是工具调用失败Agent 尝试调用某个工具但工具不可用或返回错误。解决办法是在 Harness 里做工具健康检查不可用的工具提前排除。第三类是模型返回格式异常Agent 的输出不符合预期格式解析失败。解决办法是在 prompt 里强化格式约束并在解析失败时做容错处理。错误恢复的关键是状态可回滚。每次 Agent 执行前保存状态快照失败后回滚到快照点而不是从中间某个不确定的状态继续。这要求 Harness 的状态管理设计得非常干净不能有隐藏的副作用。5.2 Markdown 格式相关的坑Markdown 看起来简单但在 Agent 工作流里坑不少。热词里 markdown 换行、markdown 语法、markdown 表格转换 excel、markdown 表格复制、markdown 数学符号都是高频问题。换行问题最常见。不同解析器对单个换行和双换行的处理不一样有的把单换行当空格有的当换行。在 Harness 里最好统一用双换行表示段落分隔单换行只在特定场景使用并且写入时做规范化。表格问题也很烦。Markdown 表格的列对齐依赖空格Agent 生成时经常对不齐导致解析失败。解决办法是在 Harness 里做表格规范化生成后自动对齐。表格转 Excel 的需求可以用脚本处理把 Markdown 表格解析成结构化数据再导出。数学符号的问题在于转义。Markdown 里某些字符有特殊含义数学公式里的符号需要转义。如果 Agent 生成的内容包含数学公式最好用专门的数学标记语法并在渲染时正确处理。提示在 Harness 里维护一个 Markdown 规范化模块所有 Agent 生成的内容都经过这个模块处理后再存储。这样能避免大量格式相关的低级错误。5.3 插件加载失败与依赖问题harness failed to load plugins 这个搜索词说明插件加载失败是常见问题。Harness 架构通常支持插件扩展但插件之间的依赖关系、版本兼容性、加载顺序都可能导致失败。排查思路是这样的先看错误日志确定是哪个插件加载失败然后检查这个插件的依赖是否满足版本是否兼容再看加载顺序是否正确有些插件必须在其他插件之前加载最后看权限和路径配置插件文件是否在正确的位置、是否有读取权限。预防措施是插件隔离。每个插件在独立的沙盒里运行一个插件失败不影响其他插件。Harness 启动时逐个加载插件失败的插件记录错误但继续启动而不是整个 Harness 崩溃。5.4 常见问题速查表问题现象可能原因排查方向解决思路Agent 执行中断上下文超限/工具失败/格式异常查看错误日志和状态快照优化检索/健康检查/格式约束插件加载失败依赖缺失/版本冲突/路径错误检查插件日志和依赖树隔离加载/版本锁定/路径修正token 消耗异常上下文注入过多/重试频繁分析 token 消耗看板精准检索/提高首次成功率Markdown 解析失败换行/表格/转义问题检查原始内容格式规范化处理/统一解析库结果质量下降上下文漂移/约束弱化对比近期输出与早期输出强制上下文重置/强化约束5.5 独家避坑经验第一个经验是不要相信 Agent 的自我报告。Agent 说“任务完成”不代表真的完成了必须做独立校验。校验可以是自动的格式检查、单元测试也可以是人工抽查。我见过太多 Agent 自信满满地返回错误结果的情况。第二个经验是上下文不是越多越好。刚开始做的时候总觉得给 Agent 越多背景信息越好结果 token 消耗爆炸而且 Agent 反而更容易被无关信息干扰。后来发现精准的少量上下文比模糊的大量上下文效果好得多。第三个经验是定期做“记忆清理”。长期运行后记忆层会积累大量过时或冗余的信息。定期清理这些信息不仅能省 token还能提高检索准确率。清理策略可以是按时间删除半年前的临时记录、按类型删除已完成的临时任务记录、按访问频率删除长期未访问的文件。第四个经验是保留人工否决权。无论 Agent 多智能总会有判断失误的时候。在关键决策点保留人工否决权能避免很多灾难。这不是对 Agent 不信任而是对系统复杂性的敬畏。6. 这套工作流的真实成本与适用边界6.1 成本结构的完整拆解每月四十亿 token 的直接成本按当前主流模型定价是一笔需要认真对待的支出。但完整成本不只是 token 费用还包括时间成本、工具成本和机会成本。时间成本是最容易被忽略的。一个人九个月意味着这九个月里这个人几乎全部精力都投入在这个项目上。如果按市场价折算人力成本这个数字可能比 token 费用还高。所以评估这套工作流是否划算不能只看 token 账单要看总投入和总产出。工具成本包括 Claude Code 的订阅、Obsidian 的插件、可能用到的其他服务。这些相对 token 费用是小头但也要纳入考虑。机会成本是这个人如果不做这个项目能做其他什么事情。这个很难量化但做决策时应该心里有数。6.2 什么规模的项目适合这套工作流这套工作流不是万能的。它适合规模大、周期长、需求相对稳定的项目。规模大意味着自动化收益能覆盖搭建成本周期长意味着 Harness 的投入能摊薄需求稳定意味着不需要频繁调整架构。不适合的场景也很明确。短期小项目不值得搭 Harness直接用现成工具更快。需求剧烈变化的项目Harness 的架构可能跟不上变化速度。对正确性要求极高的项目比如涉及资金安全、人身安全的系统Agent 生成的内容需要极其严格的校验可能人工写反而更可靠。6.3 人的角色转变与能力要求这套工作流最深刻的影响是改变了人的角色。从“写代码的人”变成“指挥 AI 写代码的人”听起来轻松了实际上对能力的要求更高了。你需要有架构能力能在脑子里装下整个系统的结构知道各个部分怎么配合。你需要有判断能力能快速判断 Agent 的输出是对是错、是好是坏。你需要有表达能力能把模糊的需求翻译成精确的任务描述。你需要有耐心能忍受 Agent 反复出错、反复调试的过程。写代码的能力依然重要但它的作用变了。以前你写代码是为了实现功能现在你写代码是为了给 Agent 做示范、做校验、做兜底。你写的代码可能只占最终代码量的很小一部分但这一部分的质量决定了整个系统的上限。6.4 后续可以扩展的方向这套工作流跑通之后有几个自然的扩展方向。第一是多 Agent 协作让不同专长的 Agent 分工合作比如一个写代码、一个写测试、一个做审查。第二是自动化程度提升把更多人工检查点变成自动检查减少人的介入频率。第三是知识沉淀把项目过程中积累的经验和模式整理成可复用的模板用于下一个项目。我个人在实际操作中的体会是这套工作流最大的价值不在于省了多少人力而在于它让一个人能做的事情的边界大大扩展了。以前一个人做不了二十万行代码的项目现在可以了。这种能力边界的扩展比单纯的效率提升更有意义。最后再分享一个小技巧在 Harness 里加一个“每日摘要”功能每天结束时自动生成当天的工作摘要包括完成了哪些任务、消耗了多少 token、遇到了哪些问题。这个摘要不仅是记录也是第二天工作的起点。坚持做这个项目跑到后期你会感谢自己。
