1. 先搞清楚这个项目到底在做什么一个人九个月二十万行代码每个月消耗四十亿以上的 token最终交付的是一款基于 Harness 架构的应用。这几个数字放在一起任何一个写过代码的人都会先愣一下——不是因为二十万行代码有多夸张大厂里一个中型项目组一年产出可能比这还多但那是团队作战。一个人扛下这个量级而且是在九个月里完成的背后一定有一套极其特殊的开发范式在支撑。这个范式就是 Harness 架构配合 Agent 驱动的开发流程。我先把话说直白一点Harness 架构不是某种新出的编程语言也不是某个具体框架的名字它更像是一种“把 AI Agent 当作执行引擎来组织软件系统”的设计思路。传统的应用开发你写的是业务逻辑本身Harness 架构下你写的是“让 Agent 能够正确执行任务的约束、工具、上下文和反馈回路”。代码的主体从“实现功能”变成了“编排能力”。这个项目之所以值得拆解是因为它踩中了当下几个最热的关键词Agent 开发、Claude Code、DeepSeek Harness、Obsidian 知识管理、Markdown 作为中间格式。这些词单独拎出来每一个都有大量教程但把它们串成一条完整的生产链路并且用一个人九个月的时间跑通、跑稳、跑到每月四十亿 token 的消耗量级这件事本身就很有参考价值。适合谁来读这篇内容如果你正在做 Agent 相关的项目或者你是一个独立开发者想搞清楚“一个人怎么用 AI 把项目做到这个体量”又或者你在用 Obsidian 管理知识、用 Markdown 做内容流转、用 Claude Code 做日常开发那这篇拆解会对你有直接帮助。我不打算讲空泛的方法论而是把这个项目里最核心的几个环节——架构选型、Agent 编排、Markdown 作为数据层、token 消耗的工程化管理——一个一个拆开讲清楚。2. Harness 架构的核心设计思路拆解2.1 为什么是 Harness而不是传统 MVC 或微服务传统应用架构的核心问题是业务逻辑是硬编码的。你写一个函数它做一件事输入输出都是确定的。但 Agent 驱动的应用不一样Agent 的行为带有不确定性它需要上下文、需要工具、需要反馈而且同一个任务在不同情况下可能走不同的路径。Harness 架构解决的就是这个问题。它的核心思想是把 Agent 当作一个“被约束的执行者”你不需要精确控制它每一步做什么但你需要给它提供三样东西——清晰的工具接口、足够的上下文、以及可验证的反馈信号。我打个比方。传统开发像是你亲手组装一台机器每个齿轮都要自己拧上去。Harness 架构像是你训练一个工人你告诉他“这是工具箱这是操作手册这是质检标准”然后让他自己去组装。你的工作从“拧齿轮”变成了“设计工具箱和质检流程”。这个项目选择 Harness 架构我认为核心原因有三个第一任务复杂度高无法穷举所有分支。二十万行代码的项目如果每一处逻辑都手写九个月根本不可能完成。Harness 架构让 Agent 承担了大量“根据上下文决定怎么做”的工作人只需要定义边界和验收标准。第二需要持续迭代和自修复。Agent 在执行任务时会出错但 Harness 架构允许你把错误反馈重新注入上下文让 Agent 自己修正。这比人工排查效率高出一个量级。第三Markdown 作为中间层的天然适配。这个项目大量使用 Markdown 作为数据交换格式而 Markdown 的结构化程度刚好够 Agent 理解又足够灵活不会像 JSON Schema 那样把 Agent 限制死。2.2 Harness 架构的四个核心组件拆开来看这个项目的 Harness 架构大致包含四个核心组件我按重要性排序第一个是工具层Tool Layer。这是 Agent 能调用的所有能力的集合。在这个项目里工具层包括文件读写、Markdown 解析、Obsidian 库操作、代码执行、搜索等。关键点在于每个工具必须有清晰的输入输出定义而且错误信息要足够详细因为 Agent 是靠错误信息来学习的。第二个是上下文管理器Context Manager。这是整个架构里最容易被低估的部分。Agent 的上下文窗口是有限的但项目知识是无限的。上下文管理器负责决定“在当前这一步应该给 Agent 看哪些信息”。这个项目里上下文管理器会根据任务类型从 Obsidian 知识库中检索相关的 Markdown 笔记拼接成 prompt 注入给 Agent。第三个是执行循环Execution Loop。Agent 不是一次调用就完事的它需要多轮迭代。执行循环负责调用 Agent、解析输出、执行工具、收集结果、判断是否完成、如果没完成就把结果反馈回去继续下一轮。这个循环的设计直接决定了 token 消耗量。第四个是验证层Validation Layer。这是保证输出质量的关键。每次 Agent 产出结果后验证层会检查是否符合预期——比如 Markdown 格式是否正确、代码是否能跑通、链接是否有效。验证不通过就触发重试。2.3 为什么 Markdown 成了这个项目的“数据总线”这个项目里Markdown 不只是一个文档格式它是整个系统的数据总线。Agent 的输入是 Markdown输出也是 Markdown中间状态用 Markdown 存储Obsidian 知识库本身就是一堆 Markdown 文件。为什么选 Markdown我的理解是Markdown 是“对人类友好”和“对机器可解析”之间的最佳平衡点。JSON 对机器友好但对人几乎不可读纯文本对人友好但机器很难理解结构Markdown 刚好卡在中间——它有标题层级、有列表、有表格、有代码块这些结构 Agent 都能理解同时人打开也能直接读。而且 Markdown 的容错性极高。Agent 输出格式稍微有点偏差比如标题少了一个井号、列表缩进不对Markdown 渲染器通常还能正常显示不会像 JSON 那样直接报错崩溃。这在 Agent 开发里非常重要因为 Agent 的输出不可能每次都完美。提示如果你也在做 Agent 项目强烈建议把中间数据格式统一成 Markdown。我试过用 JSON 做中间层Agent 经常因为少一个逗号就整个流程挂掉换成 Markdown 之后稳定性提升非常明显。3. Agent 编排与 Claude Code 的深度使用3.1 Claude Code 在这个项目里扮演什么角色Claude Code 在这个项目里不是“辅助写代码的工具”而是“主要的代码生产者”。这个定位很关键。很多人用 Claude Code 的方式是自己写主体逻辑遇到不会的让 Claude Code 补一段。但这个项目的用法是反过来的人负责定义任务、设计架构、写验收标准Claude Code 负责产出绝大部分实现代码。这就解释了为什么九个月能写出二十万行代码。如果人写一半、AI 写一半效率提升可能只有两三倍。但如果人只写百分之十的“骨架和约束”AI 写百分之九十的“填充和实现”效率提升就是十倍量级。具体怎么操作的我根据常见实践还原一下流程第一步人在 Obsidian 里写一份 Markdown 格式的任务描述包括目标、输入输出示例、边界条件、验收标准。这份描述本身就是结构化的有标题、有列表、有代码块示例。第二步把这份 Markdown 作为上下文喂给 Claude Code让它生成实现代码。关键技巧是在 prompt 里明确要求“先输出你的实现计划等我确认后再写代码”。这一步能过滤掉大量方向性错误。第三步Claude Code 输出代码后人快速 review把问题以 Markdown 注释的形式写回任务描述里再次喂给 Claude Code 让它修正。这个循环可能跑三到五轮。第四步代码通过验证后把这次的任务描述、实现方案、踩过的坑整理成一份 Markdown 笔记存进 Obsidian 知识库。下次遇到类似任务这份笔记就是现成的上下文。3.2 Agent 执行循环的 token 消耗分析每月四十亿 token 是什么概念按一个月三十天算每天大约消耗一点三亿 token。如果按 Claude 的定价粗略估算这是一笔相当可观的成本。所以这个项目一定在 token 效率上做了大量优化。我分析下来token 消耗主要来自四个地方消耗来源占比估算优化手段上下文注入约40%按需检索只注入相关笔记不全量加载Agent 推理输出约30%限制输出格式减少冗余解释工具调用结果约20%结果摘要化长结果只保留关键部分重试与纠错约10%提高首次成功率减少无效循环最大的优化空间在上下文注入。如果每次调用都把整个知识库塞进去token 消耗会爆炸。这个项目的做法是用 Obsidian 的标签系统和双向链接做粗筛再用关键词匹配做精筛每次只注入三到五篇最相关的笔记。另一个关键优化是“结果摘要化”。Agent 调用工具后返回的结果可能很长比如一个文件的内容。如果原样塞回上下文下一轮 token 就爆了。所以需要一层摘要逻辑把长结果压缩成关键信息再注入。3.3 如何让 Agent 扛住并发热词里有一个“ai agent 怎么扛并发”这在这个项目里是个真实问题。九个月里很多任务是并行跑的——比如同时处理多个模块的代码生成、同时验证多个 Markdown 文件的格式。Agent 并发的难点不在技术层面而在状态管理。多个 Agent 同时读写 Obsidian 知识库很容易冲突。这个项目的解法是给每个 Agent 分配独立的临时工作区所有中间产物先写临时区等任务完成后再合并回主知识库。合并时做冲突检测有冲突就触发人工介入。另一个并发问题是 API 限流。四十亿 token 的消耗量不可能靠单个 API key 跑。项目里应该是用了多 key 轮换加请求队列的方式把并发请求平滑到限流阈值以下。注意多 key 轮换时一定要做好失败重试和降级逻辑。我踩过的坑是某个 key 突然失效整个队列卡死所有 Agent 都在等。后来加了健康检查和自动切换才稳定下来。4. Markdown 与 Obsidian 知识库的工程化实践4.1 Obsidian 作为 Agent 的“长期记忆”Obsidian 在这个项目里的角色是 Agent 的长期记忆库。Agent 的上下文窗口再大也是有限的但 Obsidian 知识库可以无限增长。每次任务完成后产出的笔记就沉淀下来成为后续任务的参考。这里有个关键设计笔记的结构必须统一。如果每篇笔记格式都不一样Agent 检索和理解的成本会很高。这个项目应该是定义了一套 Markdown 模板所有笔记都按模板来写。模板大致包括标题、标签、适用场景、核心步骤、注意事项、相关链接。标签系统是检索的关键。Obsidian 的标签用#开头可以嵌套比如#agent/context、#markdown/table。Agent 检索时先按标签缩小范围再按关键词排序取 top N 篇注入上下文。双向链接也很重要。Obsidian 的[[链接]]语法让笔记之间形成网络。Agent 在阅读一篇笔记时可以顺着链接找到相关笔记这比纯关键词搜索更精准。4.2 Markdown 表格与数学公式的处理热词里有“markdown表格转换excel”和“markdown数学公式插件”这两个在这个项目里都是实际会遇到的问题。Markdown 表格是 Agent 输出结构化数据的主要方式。但 Agent 生成的表格经常有格式问题列数不对齐、分隔符缺失、单元格里有换行符。这个项目需要一层表格校验和修复逻辑在 Agent 输出后自动检查并修正。数学公式方面Markdown 本身不支持公式需要 LaTeX 扩展。Obsidian 支持$...$和$$...$$语法。Agent 在生成技术笔记时如果涉及算法或公式需要用 LaTeX 格式输出。这里要注意的是Agent 经常把公式写错比如括号不匹配、符号用错需要验证层做语法检查。表格转 Excel 的需求通常出现在数据导出场景。这个项目里应该是用 Python 的pandas或openpyxl库把 Markdown 表格解析成 DataFrame 再导出。解析时要注意处理转义字符和空单元格。4.3 Markdown 换行与语法细节的坑“markdown换行”是个看似简单但实际很坑的问题。Markdown 里换行有两种方式行尾加两个空格或者空一行。但 Agent 生成的文本经常搞混导致渲染出来的格式和预期不符。这个项目里我推测他们定义了一套严格的 Markdown 书写规范并且在验证层做了检查。比如段落内换行必须用空行列表项内换行必须缩进两个空格代码块必须标注语言类型。还有一个坑是 Markdown 阅读器的兼容性。不同阅读器对同一份 Markdown 的渲染结果可能不同。Obsidian 的渲染和 GitHub 的渲染就有差异。这个项目既然以 Obsidian 为主就应该以 Obsidian 的渲染结果为准其他场景做适配。提示如果你也在用 Markdown 做 Agent 的中间格式建议在项目初期就定好一份“Markdown 风格指南”把所有细节规定死。后期笔记多了再统一格式成本会高很多。5. 实操流程与关键环节还原5.1 从零搭建这套系统的步骤假设你现在要从零开始复现这套系统我按优先级给出步骤第一步搭建 Obsidian 知识库骨架。先建好文件夹结构比如tasks/、notes/、templates/、archive/。定义好标签体系比如按领域分#code、#doc、#data按状态分#status/todo、#status/done。这一步看起来简单但决定了后续所有笔记的组织方式。第二步定义 Markdown 模板。至少要有三种模板任务描述模板、实现笔记模板、问题排查模板。模板里预置好标题层级和必填字段。Obsidian 的模板插件可以一键插入。第三步搭建 Agent 调用层。用 Python 或 Node.js 写一个封装负责调用 Claude Code 或其他 Agent 接口。核心功能包括读取任务 Markdown、检索相关笔记、拼接 prompt、调用 API、解析输出、写回结果。第四步实现工具层。至少要有文件读写、Markdown 解析、代码执行、搜索这四个工具。每个工具都要有清晰的错误处理。第五步加入验证层。对 Agent 输出做格式检查和内容检查。格式检查用正则或 Markdown 解析器内容检查用简单的规则引擎。第六步跑通第一个完整任务。选一个简单的任务比如“生成一个 Markdown 表格并导出 Excel”走完整个流程记录每一步的 token 消耗和耗时。第七步迭代优化。根据第一个任务的表现优化上下文检索策略、prompt 模板、验证规则。然后逐步增加任务复杂度。5.2 参数选择与计算过程token 消耗的优化需要量化。我给出一个简单的计算方法假设每次 Agent 调用注入上下文 5000 tokenAgent 输出 2000 token工具结果 3000 token一轮总计 10000 token。如果任务平均需要 5 轮单个任务消耗 50000 token。每月四十亿 token意味着每月处理约 80000 个任务轮次或者说约 16000 个完整任务。这个量级下任何一点浪费都会被放大。比如上下文里多注入一篇不相关的笔记假设 1000 token乘以 80000 轮次就是 8000 万 token 的浪费。所以上下文检索的精准度直接关系到成本。优化方向很明确提高检索精准度、压缩工具结果、减少重试次数。检索精准度靠标签和关键词的配合工具结果压缩靠摘要算法重试次数靠提高首次成功率。5.3 实操现场记录一次典型的 Agent 任务我还原一次典型任务的执行过程任务是在 Obsidian 里新建一篇关于“Markdown 表格转 Excel”的笔记。任务描述 Markdown 已经写好包含目标、输入示例、输出要求。系统首先检索相关笔记找到三篇一篇讲 Markdown 表格语法一篇讲 Python 操作 Excel一篇讲 Obsidian 模板使用。这三篇笔记的摘要被注入上下文。然后调用 Agentprompt 里包含任务描述和三篇笔记摘要。Agent 输出一份实现方案包括用pandas.read_table读取 Markdown 表格、用to_excel导出。验证层检查方案代码语法是否正确、是否覆盖了输入示例、是否有错误处理。检查通过后Agent 生成完整代码和笔记正文。笔记正文写入 Obsidian标签设为#markdown/table和#python/excel。同时更新双向链接把这篇笔记链接到之前检索到的三篇笔记。整个过程消耗约 45000 token耗时约三分钟。如果人工写这篇笔记可能需要半小时。效率提升是明显的但前提是知识库里有足够的相关笔记供检索。6. 常见问题与排查技巧实录6.1 Agent 执行中断与错误处理热词里有“agent execution terminated due to error”这是 Agent 开发中最常见的问题。Agent 执行到一半突然中断可能的原因有很多API 超时、输出格式错误、工具调用失败、上下文超长。排查思路是分层的现象可能原因排查方法解决方案执行突然停止API 超时或限流检查 API 返回码加重试和退避逻辑输出格式错乱prompt 不够明确检查 prompt 模板增加格式示例工具调用失败参数错误或权限问题检查工具日志增加参数校验上下文超长注入内容过多统计 token 数优化检索策略循环不终止完成条件不明确检查验证逻辑设置最大轮次我踩过最坑的一次是Agent 在生成 Markdown 表格时因为表格太长输出被截断导致验证层一直不通过Agent 就一直重试token 消耗飙升。后来加了“输出长度限制”和“分段生成”逻辑才解决。6.2 Harness 插件加载失败的处理热词里有“harness failed to load plugins”这说明 Harness 生态里插件加载是个常见问题。插件加载失败通常是因为版本不兼容、依赖缺失、配置错误。处理这类问题的通用思路是先看日志确定是哪个插件失败然后检查该插件的依赖是否满足最后检查配置文件是否有误。如果还不行就禁用该插件看系统是否能正常运行以此判断是否是插件本身的问题。在这个项目里因为大量使用 Obsidian 插件插件管理是个日常问题。建议的做法是把插件配置也纳入版本管理每次变更都记录出问题时可以快速回滚。6.3 Claude Code 使用中的典型问题“your organization has disabled claude subscription access for claude code”这个热词反映了一个常见情况组织层面的访问限制。如果遇到这种情况需要联系管理员确认权限或者使用其他可用的接口。“claude code 调用 lmstudio 的本地模型”是另一个常见需求。Claude Code 默认调用云端模型但如果想用本地模型需要配置接口地址和模型名称。本地模型的好处是成本低、数据不出本地缺点是能力可能不如云端模型。“vscode配置claude code”和“安装claude code”是入门问题。基本流程是安装 VS Code 插件、配置 API key、设置工作目录。注意工作目录的选择很重要因为 Claude Code 会读取目录下的文件作为上下文。6.4 独家避坑技巧汇总最后分享几个我在实际项目中总结的技巧技巧一给 Agent 的输出加“自检”环节。在 prompt 里要求 Agent 输出完成后自己检查一遍格式和逻辑发现问题就修正。这个简单的动作能显著降低验证层的失败率。技巧二用 Markdown 注释做“隐藏指令”。在任务描述里用!-- --写一些给 Agent 看的指令这些内容不会渲染出来但 Agent 能读到。适合放一些不希望人类读者看到的调试信息。技巧三定期清理知识库。Obsidian 知识库用久了会积累大量过时笔记这些笔记会干扰检索。建议每月做一次清理把过时笔记移到archive/文件夹检索时排除这个文件夹。技巧四token 消耗要按任务类型分开统计。不同类型的任务 token 消耗差异很大混在一起统计看不出问题。分开统计后能快速定位哪类任务消耗异常。技巧五Agent 的 prompt 要版本化。每次修改 prompt 都记录版本和效果这样能知道哪个版本的 prompt 效果最好。我试过用 Git 管理 prompt 文件效果不错。这套系统跑下来最大的体会是Agent 开发的核心不是“让 AI 更聪明”而是“让 AI 的工作环境更清晰”。工具定义清楚、上下文给准确、验证标准明确Agent 的表现就会稳定。反过来如果环境一团糟再强的模型也跑不出好结果。九个月二十万行代码靠的不是某个神奇的模型而是一整套让 Agent 能持续稳定输出的工程体系。