1. 先搞清楚一个人九个月20万行到底意味着什么先把数字摊开看。九个月按每月22个工作日算大概198个工作日。20万行代码平摊下来每天要产出1000行左右的有效代码。这个量级如果靠手敲别说质量光是打字速度都撑不住。所以这个项目的核心根本不是勤奋而是把AI当成主力生产力人只做架构决策和验收。再看每月烧掉40亿 token。这个数字乍一听很吓人但换算一下就很清楚40亿token如果按主流大模型API的输入输出混合计价成本大概在几千到上万人民币区间浮动取决于缓存命中率和模型档位。真正贵的不是钱是上下文管理——40亿token意味着海量的对话轮次、文件读写、工具调用如果没有一套稳定的上下文压缩和检索机制模型早就失忆了。这个项目本质上是一个Harness架构应用。所谓Harness直译是马具、挽具在AI工程语境里它指的是套在模型外面的一层执行框架负责把用户意图拆解成任务、调度工具、管理记忆、控制上下文、校验输出。模型是马Harness是缰绳和车架。没有Harness模型只能聊天有了Harness它才能持续干活。关键词里出现的Agent、Claude Code、Obsidian、Markdown这几个词基本勾勒出了这个项目的技术底座用Claude Code这类终端Agent作为执行引擎用Obsidian作为知识库和记忆载体用Markdown作为人机之间的通用交换格式最终封装成一个能长期运行的Harness应用。这篇文章适合三类人看一是想独立做AI应用但不知道从哪下手的开发者二是已经在用Agent工具但总在上下文爆炸和任务跑飞之间反复横跳的实践者三是想理解Harness架构到底解决什么问题、值不值得投入的技术决策者。我会把架构思路、踩过的坑、以及那些文档里不会写的经验尽量讲透。2. Harness架构到底在解决什么问题2.1 裸模型和Harness应用的本质差距很多人第一次用大模型做项目思路是我把需求写清楚模型就能给我结果。做demo可以做产品必崩。原因很简单模型没有状态、没有记忆、没有工具、没有自我校验能力。它每次调用都是失忆的你上一轮告诉它的约束这一轮它可能就忘了。Harness要补的就是这四块状态管理当前任务进行到哪一步、哪些子任务完成了、哪些失败了。记忆系统长期知识项目规范、历史决策和短期上下文当前对话、临时文件分开存。工具调度读写文件、执行命令、调用API、检索知识库这些动作由Harness统一编排。输出校验模型产出的代码/文档要经过格式检查、语法检查、甚至单元测试不合格就打回重做。打个比方裸模型像一个很聪明但只有七秒记忆的实习生你每次都得从头交代Harness应用像一个有工位、有笔记本、有工具箱、还有质检流程的正式员工能连续干几个月的活。2.2 为什么是Markdown作为核心交换格式这个项目里Markdown不是顺便用用而是人机协作的协议层。原因有三第一Markdown是纯文本模型读写成本极低不像JSON那样对格式容错差也不像二进制那样不可读。第二Markdown天然支持结构化标题、列表、表格、代码块既能表达任务清单又能嵌入代码和配置。第三Obsidian、VS Code、各种阅读器都原生支持人看起来舒服机器解析也方便。实际项目里我见过太多人用JSON做Agent的任务描述结果模型稍微多输出一个逗号就整个解析失败。Markdown的容错性在这里是巨大优势——就算格式有点乱人也能看懂模型也能靠语义理解补全。2.3 Obsidian在架构里扮演的角色Obsidian在这个项目里不是笔记软件这么简单它是长期记忆的物理载体。Harness应用需要记住的东西太多了项目规范、历史bug、决策记录、用户偏好、领域知识。这些东西塞进模型的上下文窗口是不现实的必须外置。Obsidian的vault本质上就是一个Markdown文件夹每个文件是一个知识单元文件之间的双链[[链接]]构成了知识图谱。Harness可以通过文件系统直接读写这些Markdown用关键词检索或者向量检索找到相关片段再注入到当前上下文里。这就实现了按需加载记忆而不是把所有东西一股脑塞给模型。关键词里出现的obsidian创建项目管理台账obsidian插件推荐weknora和obsidian这些搜索词说明很多人已经在探索用Obsidian做项目管理和知识沉淀。这个方向是对的但要注意Obsidian是记忆层不是执行层。别指望它自己会干活它只是给Harness提供一个稳定的、可检索的知识底座。3. 从零搭一个Harness应用的骨架3.1 目录结构设计让模型一眼看懂项目九个月20万行代码如果没有清晰的目录结构模型每次都要花大量token去找文件。我的做法是把项目根目录设计成自解释的project/ ├── harness/ # Harness核心逻辑 │ ├── orchestrator/ # 任务编排 │ ├── memory/ # 记忆读写 │ ├── tools/ # 工具封装 │ └── validators/ # 输出校验 ├── vault/ # Obsidian知识库 │ ├── specs/ # 项目规范 │ ├── decisions/ # 决策记录 │ └── knowledge/ # 领域知识 ├── tasks/ # 任务清单Markdown ├── src/ # 实际业务代码 └── logs/ # 执行日志关键点每个目录下放一个README.md用一两句话说明这个目录是干什么的、里面文件的命名规范是什么。模型在探索项目时读README的成本远低于逐个打开文件。这个习惯能省下大量token也能减少模型迷路的概率。3.2 任务描述用Markdown模板固定下来Agent跑飞最常见的原因就是任务描述太模糊。我的做法是定义一个任务模板每次派活都按这个格式写# 任务实现用户登录接口 ## 目标 在 src/auth/ 下实现 POST /login 接口 ## 约束 - 使用项目现有的 JWT 工具见 vault/specs/auth.md - 错误码遵循 vault/specs/error-codes.md - 必须写单元测试覆盖率 80% ## 验收标准 - [ ] 接口能正常返回 token - [ ] 密码错误返回 401 - [ ] 单元测试全部通过 ## 相关文件 - src/auth/jwt.ts - vault/specs/auth.md这个模板的价值在于目标、约束、验收标准、相关文件四要素齐全。模型不需要猜人验收也有依据。实测下来用模板派活的任务一次通过率比自由描述高出一大截。3.3 上下文预算40亿token是怎么烧掉的很多人好奇40亿token到底花在哪。拆开看主要三块消耗项占比估算说明文件读写约40%每次任务都要读相关文件、写产出工具调用往返约30%执行命令、检索、校验的对话轮次上下文重放约30%每轮对话都要带上历史上下文最容易被忽视的是第三项。如果不管控每轮对话都把全部历史塞进去token消耗是指数级增长的。我的做法是分层上下文当前任务的相关文件全文注入历史对话只保留摘要长期知识按需检索。这样能把单次调用的token量压到可控范围。提示上下文压缩不是简单截断而是让模型自己总结到目前为止做了什么、还剩什么没做。这个摘要要写回vault下次任务可以直接复用。4. 那些文档里不会写的踩坑经验4.1 模型假装完成是最大的坑Agent最危险的行为不是报错而是声称完成了但实际没做。比如让它改一个文件它回复已修改完成但实际上文件根本没动。这种情况在长任务里特别常见因为模型会脑补自己完成了。我的应对方案是强制验证任何写操作之后Harness必须重新读取文件对比内容是否真的变了。代码任务还要跑一遍语法检查或测试。验证不通过就打回把错误信息喂回给模型重做。这个机制加上之后假装完成的比例大幅下降。4.2 Markdown换行和表格的坑关键词里markdown换行markdown表格转换excelmarkdown表格复制这些搜索词说明很多人在实际使用中被Markdown的细节坑过。在Harness应用里这些细节会直接影响解析结果。比如Markdown里单个换行默认不换行要换行得用两个空格加换行或者空一行。如果Harness靠换行来分割任务项模型输出时漏了空格解析就乱了。我的做法是不依赖Markdown的视觉换行而是用明确的分隔符比如每个任务项用- [ ]开头解析时按这个模式匹配稳得多。表格也是重灾区。模型生成的表格经常列数对不齐或者单元格里有|符号导致解析错位。如果要把Markdown表格转成Excel或结构化数据一定要先做列数校验对不齐就报错让模型重生成别硬解析。4.3 工具调用的幂等性设计Agent会重复调用工具这是常态。比如它可能连续两次执行同一个文件写入或者重复检索同一个知识。如果工具不是幂等的就会出问题——比如重复追加日志、重复创建文件。我的原则是所有写操作工具必须幂等。写文件用覆盖而不是追加除非明确要追加创建资源前先检查是否存在删除操作要能容忍已经不存在。这样即使Agent抽风重复调用也不会造成破坏。4.4 长任务的断点续跑九个月的项目不可能一次跑完中间必然有中断——模型超时、网络抖动、人工干预。如果每次中断都从头开始那40亿token根本不够烧。解决方案是任务状态持久化。每个任务执行到哪一步、产出了什么、下一步该干什么全部写进vault里的任务文件。中断后重新启动Harness先读任务文件从断点继续。这个机制让长任务变得可靠也让token消耗可控。5. 让Harness真正跑起来的几个关键机制5.1 记忆检索别把整个知识库塞进上下文Obsidian vault可能有几百上千个文件全塞进上下文是不可能的。必须做检索。我的方案是两级检索第一级用文件名和标题做关键词匹配快速缩小范围。第二级对候选文件做语义相似度排序取Top-N注入上下文。关键词匹配用简单的字符串包含就行语义检索可以用轻量级的向量模型不一定非要上大模型。实测下来两级检索能把相关文件的召回率做到很高同时注入的token量控制在合理范围。关键是检索结果要带来源标注让模型知道这段知识来自哪个文件方便它引用和追溯。5.2 输出校验代码要过测试文档要过格式Harness应用和聊天机器人的分水岭就在校验。聊天机器人输出什么都行Harness应用的输出必须符合规范。代码类输出语法检查 → 类型检查 → 单元测试 → 集成测试逐层过滤。文档类输出格式检查标题层级、必填字段→ 链接检查引用的文件是否存在→ 内容检查是否覆盖了任务要求的所有点。校验失败不是终点而是反馈循环的起点。把失败原因结构化地喂回给模型让它针对性修复。通常一到两轮就能通过比人工改快得多。5.3 成本控制缓存、批处理、模型分级40亿token/月的成本要压下来靠的是三招缓存相同的上下文前缀比如项目规范、常用工具定义缓存起来命中缓存的部分计费大幅降低。这个在主流API里都支持一定要用。批处理非实时任务攒一批一起处理比逐个调用便宜。模型分级简单任务格式转换、文件读写用便宜的小模型复杂任务架构设计、bug定位才用大模型。Harness里要有一个路由层根据任务复杂度自动选模型。这三招组合下来成本能压到原来的三分之一甚至更低而效果几乎不受影响。6. 一个人做这种项目的真实体会先说结论一个人九个月做20万行代码技术上完全可行但前提是你把AI当同事而不是当工具。当工具用你还是在写代码当同事用你是在做架构、定规范、验收成果代码是它写的。最难的不是技术是心态转变。你得接受模型会犯错、会偷懒、会假装完成然后设计一套机制去兜住这些。这套机制就是Harness。Harness做得好模型的能力能被放大十倍Harness做得差模型就是个昂贵的玩具。另一个体会是规范比代码重要。项目里最有价值的不是那20万行代码而是vault里那些规范文档、决策记录、任务模板。代码可以重写规范是复利的。每次踩坑之后把教训写进vault下次模型就能避开这才是长期效率的来源。最后说个具体的别追求一次做对。Harness架构本身也是迭代出来的我最初的版本只有任务派发和文件读写校验、记忆检索、成本控制都是后来加的。先跑起来再优化比一开始就设计完美架构要实际得多。40亿token里有相当一部分是学费但每一分都花在了让系统更稳上。
