1. 先搞清楚这个标题到底在说什么一个人、九个月、20万行代码、每月40亿 token——这几个数字摆在一起任何一个写过代码的人都会先愣一下。20万行代码如果按一个成熟工程师每天有效产出200行来算需要1000个工作日也就是将近三年。而这里只有九个月还是一个人。更离谱的是每月40亿 token的消耗量这个量级意味着背后有一个持续运转的Agent系统在不停地读写、推理、调用工具而不是简单的代码补全。这个项目的核心是围绕Harness架构构建一款应用。Harness这个词在AI Agent开发圈子里最近被反复提及它本质上是一套让Agent能够稳定、可控、可观测地执行复杂任务的工程框架。你可以把它理解成给大模型套上一副马具——模型是马力气大但方向感差Harness就是缰绳、鞍具和路标的集合体让这匹马能拉着车走完一条完整的路而不是跑两步就冲进沟里。关键词里出现的Claude Code、Obsidian、Markdown、Agent、deepseek harness这些词基本勾勒出了这个项目的技术栈轮廓用Claude Code作为主要的编码Agent工具用Obsidian作为知识管理和项目管理的载体Markdown作为贯穿始终的文档格式而Harness则是把这些东西串起来的架构骨架。热搜词里还有harness failed to load pluginsagent execution terminated due to error这类报错信息说明在实际使用中插件加载失败和Agent执行中断是高频问题这也是本文要重点拆解的部分。这篇文章适合谁看如果你正在尝试用Agent工具做独立开发或者你在团队里负责搭建AI辅助的工程流水线又或者你只是好奇一个人怎么可能九个月写出20万行代码那接下来的内容应该能给你一些真实的参考。我不会只讲概念会把架构设计的取舍、token消耗的构成、插件系统的坑、以及Obsidian和Claude Code怎么配合这些实操层面的东西都摊开来说。2. Harness架构到底解决了什么问题2.1 裸奔的Agent为什么走不远大多数人第一次用Claude Code或者类似的Agent工具时体验路径都差不多装好打开终端输入一句帮我写一个XXX功能然后看着它开始噼里啪啦输出。前五分钟很惊艳十分钟后开始不对劲——它可能改了一个不该改的文件或者在一个循环里反复调用同一个工具又或者把之前已经确认过的需求忘得一干二净。这不是模型不够聪明而是缺少执行框架。一个裸奔的Agent面临三个核心问题状态管理、工具调用的边界控制、长任务的上下文保持。状态管理指的是Agent需要知道我现在做到哪一步了而不是每次对话都从零开始。工具调用的边界控制指的是Agent不能无限制地调用文件写入、命令执行这些高危操作需要有审批和回滚机制。长任务的上下文保持则更棘手一个跨越几小时甚至几天的开发任务上下文窗口根本装不下必须有一套外部的记忆和检索系统。Harness架构就是冲着这三个问题去的。它的核心思路是把Agent的执行过程拆成可编排的步骤每一步都有明确的输入、输出和状态标记步骤之间通过一个执行引擎来调度而不是让模型自由发挥。这听起来有点像传统的CI/CD流水线但区别在于Harness里的每一步本身可能又是一个小型的Agent调用具备一定的自主决策能力。2.2 Harness的四个核心组件从我实际搭建和使用的经验来看一个能跑起来的Harness架构至少包含四个部分执行引擎Execution Engine负责接收任务、拆解步骤、按顺序或按依赖关系调度执行。它需要处理超时、重试、失败回滚这些基础逻辑。热搜词里那个agent execution terminated due to error报错十有八九就是执行引擎在某个步骤失败后没有正确捕获异常导致整个链路断掉。工具注册表Tool Registry所有Agent可以调用的工具——读文件、写文件、执行命令、搜索网页、调用API——都在这里注册。每个工具需要定义清晰的参数schema、权限级别和副作用说明。这样做的好处是当Agent试图调用一个未注册的工具时引擎可以直接拦截并报错而不是让它执行一个未知操作。状态存储State Store通常是一个本地的SQLite或者JSON文件记录当前任务的执行状态、已完成的步骤、中间产物。Obsidian在这里可以扮演一个很自然的角色——把状态以Markdown文件的形式存进Vault里既方便人查看也方便Agent通过文件系统读取。上下文管理器Context Manager负责在每一步执行前从状态存储和历史记录中检索出最相关的上下文拼装成Prompt发给模型。这一步直接决定了token消耗的效率。如果上下文管理做得粗糙每次都把全部历史塞进去token消耗会爆炸式增长如果做得精细只检索相关片段就能把每月40亿token控制在合理范围内。2.3 为什么选择Markdown作为贯穿格式这个项目里Markdown不只是一个文档格式它是Agent和人类之间的接口协议。Agent读Markdown来理解任务写Markdown来汇报进度人类通过Obsidian查看和编辑这些Markdown文件来干预任务。这种设计的巧妙之处在于Markdown既是结构化的有标题、列表、表格又是人类可读的而且几乎所有工具都支持。热搜词里markdown表格转换excelmarkdown转word工作流这些需求说明在实际工作中Markdown经常需要和其他格式互转。在Harness架构里我通常会在工具注册表里加一个格式转换工具让Agent在需要输出Excel或Word时自动调用而不是手动处理。注意Markdown的换行和表格语法在不同解析器下行为不一致Agent生成的内容如果直接喂给另一个工具很容易出现格式错乱。建议在Harness里统一使用一种Markdown方言比如CommonMark并在工具层做一次规范化处理。3. 20万行代码是怎么堆出来的3.1 代码构成拆解20万行听起来吓人但拆开来看就没那么夸张了。根据我类似项目的经验这个量级的代码大概是这样分布的代码类型占比说明业务逻辑25%核心功能实现真正手写的部分工具适配层20%各种API、SDK的封装和适配配置与Schema15%工具定义、参数校验、流程配置测试代码20%单元测试、集成测试、回归测试文档与注释10%Markdown文档、代码注释生成代码10%由Agent自动生成的重复性代码真正需要人从头写的核心逻辑可能只有5万行左右剩下的15万行里有相当一部分是Agent在Harness框架下自动生成和迭代的。这就是为什么一个人能在九个月内完成这个量级——Agent负责产出人负责架构和审核。3.2 每月40亿token花在哪了40亿token一个月按30天算每天约1.33亿token。这个数字需要拆解才能理解代码生成与修改每次Agent写代码或改代码输入输出加起来大概5000-20000 token。如果一天有2000次这样的操作就是1000万-4000万token。上下文检索与拼装每次执行前检索相关文件和历史记录这部分是纯输入消耗。如果上下文管理不够精细一次检索可能吃掉几万token。测试与验证Agent跑测试、读报错、修复问题这个循环非常消耗token。一个复杂的bug可能需要几十轮对话才能修好。文档生成与同步Markdown文档的生成、更新、格式转换虽然单次消耗不大但频率高。实操心得token消耗的大头往往不是代码生成本身而是无效的上下文重复。我试过在Harness里加一个上下文去重层把每次请求里重复的文件内容做哈希比对只发送变化部分token消耗直接降了35%。3.3 九个月的时间线复盘如果把这个项目按九个月拆成三个阶段大概是这样的第一阶段1-3月架构搭建与工具链跑通。这个阶段代码量增长慢但token消耗不低因为大量时间花在调试Harness本身——插件加载失败、Agent执行中断、状态不同步这些问题会反复出现。热搜词里harness failed to load plugins和deepseek harness安装这些基本就是这个阶段的日常。第二阶段4-6月核心功能开发与Agent流水线优化。代码量开始指数增长因为Harness跑通后Agent可以批量生成和修改代码。这个阶段的关键是建立代码审核机制不能让Agent随便往主分支写东西。第三阶段7-9月测试、重构与文档补齐。代码量增长放缓但token消耗依然很高因为测试和重构需要大量的上下文理解和推理。这个阶段也是Obsidian发挥最大作用的时候——所有文档、决策记录、问题追踪都在Vault里Agent可以直接读取。4. Claude Code与Obsidian的配合方式4.1 为什么是这两个工具Claude Code在终端里运行能直接操作文件系统、执行命令、读写代码是一个天然的执行者。Obsidian则是一个本地的Markdown知识库所有文件都是纯文本Agent可以无障碍读取和写入。这两个工具的组合本质上构建了一个双向通道Claude Code负责干活Obsidian负责记录和展示Agent在两者之间同步信息。热搜词里vscode配置claude codeclaude code安装claude code使用这些说明很多人还在配置阶段就卡住了。我的建议是先把Claude Code在终端里跑通确认能正常读写文件和执行命令再去考虑和Obsidian的集成。顺序反了会浪费很多时间。4.2 具体的集成方式集成方式其实很简单核心就是让Claude Code把Obsidian Vault当作工作目录的一部分。具体操作在Obsidian里创建一个专门的文件夹比如/AgentWorkspace用来存放Agent生成的任务文档、进度记录和决策日志。在Claude Code的配置里把这个文件夹加入可访问路径。在Harness的工具注册表里注册几个针对Obsidian Vault的操作工具读取指定笔记、追加内容到日记、创建新笔记、搜索Vault内容。每次Agent执行完一个步骤自动在Vault里更新对应的Markdown文件。这样做的好处是你随时打开Obsidian就能看到Agent在干什么、干到哪了、遇到了什么问题。热搜词里obsidian创建项目管理台账这个需求在这个架构下就是自然而然的事情——Agent自己就在维护一本项目台账。4.3 插件冲突与加载失败的处理热搜词里harness failed to load plugins和obsidian插件推荐同时出现说明插件管理是个高频痛点。Obsidian的插件生态很丰富但并不是所有插件都适合和Agent配合使用。我的经验是避免使用会修改文件格式的插件。有些插件会在保存时自动调整Markdown语法这会导致Agent读取到的内容和写入的不一致。禁用自动同步类插件。Agent高频读写文件时同步插件可能触发冲突或锁文件。保持插件数量精简。每多一个插件就多一个潜在的加载失败点。如果Harness启动时报插件加载失败先禁用所有第三方插件逐个启用来定位问题。提示如果遇到harness failed to load plugins先检查插件目录的权限设置再确认插件版本和Harness版本是否匹配。很多时候问题出在版本不兼容而不是插件本身有问题。5. Agent执行中断与错误处理5.1 常见的执行中断原因agent execution terminated due to error这个报错在热搜里出现说明它是很多人的噩梦。Agent跑到一半突然停了前面的工作可能白做状态也可能不一致。根据我的排查经验中断原因主要有这几类工具调用超时Agent调用了一个外部API对方响应太慢执行引擎等不及就掐断了。解决办法是在工具注册表里给每个工具设置合理的超时时间并且实现重试逻辑。上下文超限Prompt太长超过了模型的上下文窗口API直接返回错误。这种情况在长任务中很常见需要在上下文管理器里做截断或摘要。状态不一致Agent认为某个文件已经写入了但实际上写入失败下一步读取时发现文件不存在直接崩溃。解决办法是在每一步执行后做状态校验确认副作用已经生效。权限问题Agent试图写入一个没有权限的目录或者执行一个被禁止的命令。Harness的权限系统应该提前拦截这类操作而不是等到系统层面报错。5.2 构建可恢复的执行链路一个健壮的Harness应该做到任何一步失败都不会导致整个任务丢失。具体做法每一步执行前把当前状态写入状态存储标记为进行中。执行成功后更新状态为已完成并记录输出。执行失败时记录错误信息状态标记为失败但保留已完成步骤的结果。提供恢复命令可以从最后一个失败步骤重新开始而不是从头再来。这套机制听起来简单但在实际实现中最难的是副作用的幂等性。比如Agent写了一个文件失败后重试又写了一遍如果写入操作不是幂等的就可能产生重复内容。我的做法是在写入前先检查目标内容是否已经存在如果存在就跳过。5.3 错误日志的分析方法Agent执行中断后日志是你最好的朋友。但Agent的日志往往又长又乱怎么快速定位问题我通常按这个顺序看先看最后一条错误信息确定是哪个工具或哪个步骤出的问题。往前翻看这个步骤的输入是什么是不是输入本身就有问题。再往前看这个步骤之前的状态是否正常有没有未处理的警告。如果错误信息模糊直接搜索关键词比如timeoutpermission deniedcontext length。实操心得在Harness里加一个日志分级机制把Agent的思考过程、工具调用、执行结果分成不同级别。排查问题时只看ERROR和WARN级别能省很多时间。6. 独立开发者的token成本控制6.1 40亿token的成本构成每月40亿token如果按主流API的定价来算成本不是小数目。但这里有个关键点不是所有token都需要用最贵的模型。在Harness架构里不同任务对模型能力的要求差异很大架构决策、复杂bug修复需要最强模型token单价高但用量少。代码生成、文档撰写中等模型就能胜任性价比最高。格式转换、简单检索可以用最便宜的模型甚至本地模型。我的做法是在Harness里配置一个模型路由层根据任务类型自动选择模型。这样能把整体成本压下来40%-60%。6.2 上下文压缩的几种手段上下文是token消耗的大头压缩上下文是最有效的省钱方式。我试过这几种手段摘要压缩把长对话历史用一个小模型做摘要只保留关键决策和当前状态。缺点是摘要可能丢失细节适合对精度要求不高的场景。向量检索把历史记录存入向量数据库每次只检索最相关的片段。这是目前最主流的方式效果和成本比较平衡。文件差分对于代码文件只发送变化的部分而不是整个文件。这需要Harness能追踪文件的版本变化。缓存复用对于重复出现的系统提示和工具定义利用API的缓存机制避免重复计费。6.3 什么时候该停下来独立开发最容易犯的错误是让Agent无限循环。一个bug修不好Agent会反复尝试每次尝试都消耗token但可能越修越乱。我的经验是设置一个硬性上限同一个问题Agent尝试超过5次还没有解决就强制停止转由人工介入。这个上限可以根据问题复杂度调整但必须有。7. 从热搜词看实际使用中的高频问题7.1 安装与配置类问题热搜里claude code安装claude code下载deepseek harness安装harness下载这些词集中出现说明很多人在第一步就卡住了。这类问题的共性原因是环境依赖不满足。我的建议是先确认Node.js或Python版本符合要求版本不对是最常见的坑。检查网络环境是否能正常访问所需的包管理源。安装完成后先用一个最简单的任务测试确认基础功能正常再去配置复杂的Harness。7.2 Markdown格式类问题markdown换行markdown语法markdown表格复制markdown表格转换excelmarkdown数学符号这些词说明Markdown虽然简单但在实际使用中细节问题很多。在Harness架构里我建议统一使用一种Markdown解析器避免不同工具解析结果不一致。表格转换用专门的工具处理不要依赖Agent手动转换。数学符号用LaTeX语法并确保渲染端支持。7.3 Agent框架类问题agent框架agent开发ai agentpi agenthermes agent这些词反映出大家都在探索Agent框架的选型。我的观点是没有最好的框架只有最适合当前任务的框架。Harness架构的好处是它不绑定特定的Agent框架你可以在执行引擎里同时接入多个框架根据任务类型切换。8. 这套架构还能怎么扩展8.1 多Agent协作目前的架构是单Agent执行但Harness天然支持多Agent。你可以让一个Agent负责写代码另一个负责审核第三个负责写测试。执行引擎负责协调它们之间的依赖关系。这样做的好处是每个Agent的上下文更聚焦token效率更高。8.2 与CI/CD流水线集成Harness的执行引擎可以和现有的CI/CD工具对接让Agent生成的代码自动进入构建和测试流程。这样就把AI辅助开发嵌入了标准的工程实践而不是一个孤立的工具。8.3 知识库的持续积累Obsidian Vault里的内容会随着项目推进越来越丰富这些内容本身就是宝贵的训练和检索资源。你可以定期把Vault里的决策记录、问题解决方案整理成结构化的知识库供后续项目复用。我在实际使用中发现这套架构最大的价值不是省了多少时间而是让一个人的产出能够接近一个小团队的规模。当然前提是你愿意花时间把Harness搭好把工具链跑通把错误处理做扎实。前期投入可能占整个项目30%的时间但后面70%的效率提升都靠它。如果你也在做类似的事情建议先从最小的Harness跑通开始别一上来就追求大而全迭代比规划重要得多。