1. 一个人九个月二十万行代码这件事到底在说什么先把标题里的几个数字拆开看。一个人意味着没有团队分工没有前后端联调没有产品经理帮你写需求文档所有决策链路都压在一个人的脑子里。九个月大概是 270 天左右如果按每天有效编码 6 小时算总共约 1600 小时。20 万行代码平均下来每小时要产出 125 行有效代码而且这还没算调试、重构、写文档、排查线上问题的时间。每个月烧掉 40 亿 token这个量级说明整个开发过程高度依赖大模型辅助不是偶尔问几句而是把模型当成了日常生产工具在跑。这三个数字放在一起指向的是一种新的应用构建范式——Harness 架构应用。所谓 Harness在当下的语境里指的是一套把大模型能力、工具调用、上下文管理、任务编排串起来的运行骨架。你可以把它理解成一个驾驶舱模型是发动机Harness 是方向盘、仪表盘和传动系统负责把发动机的原始动力转化成可操控、可复用、可观测的实际行为。没有 Harness模型就是一个只会聊天的黑盒有了 Harness它才能稳定地读文件、写代码、调工具、记住上下文、按流程推进任务。这篇文章适合谁看如果你正在用 Claude Code、Obsidian、各类 Agent 框架折腾自己的工具链或者你心里一直有个我想一个人做出一款完整应用的念头那这篇内容就是写给你的。我会把这类项目背后的架构思路、核心模块、实操细节、踩坑经验全部摊开讲不藏私也不灌鸡汤。20 万行代码不是靠意志力硬堆出来的它背后有一套可复制的方法论和工具组合。需要先说明一点标题里的具体项目细节我无法逐一核实但这类单人 大模型 长周期的项目在最近一年里确实大量涌现它们的共性特征非常清晰。下面我基于这类项目的常见实践把整套东西拆解成可参考、可复现的模块来讲。2. Harness 架构的核心设计思路拆解2.1 为什么是 Harness 而不是普通 Agent很多人第一次接触 Agent 开发脑子里想的是我写个循环让模型不断调用工具直到任务完成。这个思路没错但它只是最粗糙的雏形。真正跑长周期项目时你会发现几个致命问题上下文会爆、工具调用会乱、任务状态会丢、错误会累积、成本会失控。Harness 架构要解决的就是这些工程化问题。它和普通 Agent 的区别类似于脚本和框架的区别。脚本能跑通一次演示框架能支撑九个月的持续迭代。具体来说Harness 至少包含这几层上下文管理层决定每一轮对话里塞什么、丢什么、压缩什么。40 亿 token 一个月如果不做精细的上下文裁剪成本会翻好几倍。工具注册与调度层把文件读写、命令执行、搜索、数据库操作等能力标准化成统一接口模型只需要声明意图Harness 负责路由。任务状态层记录当前做到哪一步、哪些子任务完成、哪些失败待重试。这是长周期项目不崩的关键。可观测层日志、token 消耗统计、调用链路追踪。没有这层你根本不知道钱花在哪、错出在哪。记忆与知识层把项目约定、历史决策、代码规范沉淀下来避免每次都要重新解释。我个人的判断是一个人能在九个月里推进 20 万行代码靠的不是手速而是 Harness 把大量重复性认知劳动自动化了。模型负责生成和推理Harness 负责约束和记忆人负责决策和验收。三者分工明确才能持续。2.2 为什么选 Markdown 作为核心载体热搜词里 Markdown 出现频率极高这不是偶然。在这类项目里Markdown 往往承担了人机共同语言的角色。原因很实在第一Markdown 是纯文本模型读写零障碍。你让模型直接操作数据库或者二进制格式出错概率高得多。Markdown 的语法简单模型生成时不容易跑偏。第二Markdown 天然适合做知识沉淀。Obsidian 这类工具就是围绕 Markdown 文件构建的你的项目笔记、任务清单、架构决策记录全都可以是 Markdown 文件模型可以直接读、直接改。第三Markdown 的表格、列表、代码块结构恰好对应了任务分解、参数说明、代码片段这些开发场景。你让模型输出一个任务计划它用 Markdown 列表表达最自然。实操中一个常见做法是把整个项目的记忆存在一个 Markdown 文件树里Harness 每轮根据当前任务检索相关文件注入上下文。这比把所有历史对话塞进 prompt 要高效得多。Obsidian 在这里的价值就体现出来了——它既是人的知识管理工具也是模型的上下文来源两边共用同一套文件。提示Markdown 换行在不同渲染器里行为不一致写 Harness 读取逻辑时要注意统一处理。行尾两个空格、空行、反斜杠这三种换行方式建议在项目规范里固定一种否则模型生成的文档在不同工具里显示效果会乱。2.3 工具链选型的取舍逻辑从热搜词能看出Claude Code、Obsidian、各类 Agent 框架是高频组合。我梳理一下这类项目常见的工具选型逻辑环节常见选择选择理由注意事项模型调用Claude Code 等命令行工具直接操作文件系统适合编码场景注意沙盒权限配置知识管理ObsidianMarkdown 原生插件生态丰富插件冲突要提前排查代码编辑VS Code 相关插件生态成熟调试方便配置项多建议版本化管理任务编排自研 Harness 或现成框架长周期项目通常需要定制别过度设计先跑通最小闭环版本控制Git标配无需多言提交粒度要细方便回滚选型的核心原则是能复用就不自研但核心编排逻辑必须自己掌控。因为长周期项目里你的需求和现成框架总有偏差如果核心逻辑在别人手里改起来会非常痛苦。工具可以换Harness 的核心调度逻辑最好自己写。3. 核心模块的实操要点与细节3.1 上下文管理40 亿 token 是怎么花出去的先算一笔账。假设一个月 40 亿 token按 30 天算每天约 1.33 亿 token。如果一天有效工作 8 小时每小时约 1660 万 token每分钟约 27 万 token。这个量级意味着几乎每一轮交互都在处理大量上下文而不是简单的问答。上下文管理的核心矛盾是信息要全但窗口有限成本要控。常见做法是分层常驻层项目规范、核心架构说明、当前任务目标。这部分每轮都带但要做精简控制在几千 token 以内。检索层根据当前任务从知识库里动态拉取相关文档和代码片段。这层是 token 消耗大头也是优化重点。历史层最近几轮对话保留原始内容更早的做摘要压缩。临时层当前正在处理的文件内容、命令输出用完即弃。我试过的一个有效技巧是给每个 Markdown 知识文件加一个摘要头Harness 检索时先读摘要判断相关性后再决定是否加载全文。这样能把无效上下文砍掉一大半。另一个技巧是定期做记忆整理把零散的对话结论合并成结构化的 Markdown 文档减少重复信息。注意上下文压缩不是越狠越好。压得太狠模型会丢失关键约束生成的东西不符合项目规范返工成本更高。建议保留决策类信息压缩过程类信息。3.2 任务状态管理让九个月的项目不迷路一个人做九个月最大的敌人不是技术难题而是忘记自己做到哪了。今天写完的模块三天后回来看可能连变量命名逻辑都想不起来。任务状态管理就是对抗这种遗忘的。我的做法是用 Markdown 维护一个任务台账结构大致如下## 当前迭代用户认证模块 ### 已完成 - [x] 数据库表设计 - [x] 注册接口 - [x] 登录接口 ### 进行中 - [ ] 密码重置流程 - 状态接口已写邮件发送未接 - 阻塞点邮件服务选型未定 ### 待办 - [ ] 权限校验中间件 - [ ] 登录日志这个台账由 Harness 在每轮任务开始时读取模型据此知道当前进度。任务完成后Harness 自动更新勾选状态。这样即使隔了一周回来打开台账就能立刻进入状态。Obsidian 在这里的优势是双向链接和标签系统。你可以给每个任务打标签比如#backend#urgentHarness 按标签检索比全文搜索精准得多。热搜里提到的obsidian创建项目管理台账说的就是这类用法。3.3 工具调用的标准化设计Harness 要让模型调工具接口设计必须统一。我见过太多项目每个工具一套参数格式模型经常调错。标准做法是定义一套统一的工具描述格式类似这样{ name: read_file, description: 读取指定路径的文件内容, parameters: { path: {type: string, description: 文件相对路径}, max_lines: {type: integer, description: 最大读取行数默认全部} } }所有工具都按这个格式注册Harness 统一解析模型的调用意图统一执行统一返回结果。这样做的好处是新增工具时模型不需要重新学习调用方式降低出错率。实操中要特别注意错误返回的设计。工具执行失败时返回给模型的信息要包含失败原因、可能的修复建议、相关上下文。比如文件不存在不要只返回error而要返回文件 X 不存在当前目录下有这些文件...。模型拿到这种信息才能自我纠正。3.4 记忆沉淀把经验变成可检索的知识九个月下来项目里会积累大量决策为什么选这个库、为什么这样设计表结构、某个 bug 是怎么修的。这些如果不沉淀下次遇到类似问题还要重新想一遍。我的做法是维护几类 Markdown 文档决策记录ADR每个重要技术决策一篇写清楚背景、选项、最终选择和理由。踩坑日志遇到 bug 和解决方案按时间倒序排列。代码规范命名、注释、目录结构等约定。接口文档对外接口的说明。这些文档放在 Obsidian 库里Harness 按需检索。时间长了这就成了项目的外脑。模型在生成代码前先检索相关决策记录生成的东西就会更符合项目一贯风格减少返工。4. 完整实操流程与关键环节实现4.1 从零搭建 Harness 的最小闭环不要一上来就追求完整架构。先跑通最小闭环读任务 → 调模型 → 执行工具 → 写回结果。这个闭环能跑后面都是在这个基础上加模块。第一步准备任务文件。在项目根目录建一个tasks.md写清楚当前要做什么。格式不用复杂自然语言描述即可模型能看懂。第二步写主循环。伪代码大致如下while True: task read_task(tasks.md) context build_context(task) # 检索相关知识 response call_model(context) actions parse_actions(response) # 解析工具调用 for action in actions: result execute_tool(action) log_result(result) update_task_status(task, response) if task_completed(response): break第三步接工具。先接最基础的几个读文件、写文件、执行命令。够用了再扩展。第四步加日志。每轮调用的输入输出、token 消耗、耗时都记下来。这是后续优化的依据。这个闭环我建议控制在 200 行代码以内。跑通之后你会发现瓶颈在哪再针对性优化。4.2 上下文检索的实现细节检索质量直接决定模型输出质量。最简单的实现是关键词匹配从任务描述里提取关键词去 Markdown 库里找包含这些词的文件。但关键词匹配召回率低容易漏。进阶做法是向量检索把知识库文档切块转成向量存起来任务来了先转向量再找最相似的块。这个方案召回率高但需要额外的向量存储和嵌入模型调用成本和复杂度都上去了。我的折中方案是混合检索先用关键词粗筛再用向量精排。粗筛能快速缩小范围精排保证相关性。实测下来这个组合在中小规模知识库几千个文档上效果很好成本也可控。提示文档切块大小很关键。切太小上下文不完整切太大噪声多。建议按语义切比如一个 Markdown 的二级标题下的内容作为一块通常几百到一千字比较合适。4.3 成本控制的具体手段40 亿 token 一个月成本不是小数目。控制手段主要有几个第一缓存。相同的上下文和问题结果缓存起来避免重复调用。项目里很多操作是重复的比如读同一个文件、查同一个接口文档缓存命中率能到 30% 以上。第二模型分级。简单任务用便宜的小模型复杂推理用大模型。比如格式化代码、提取信息这类小模型完全够用。Harness 里加一个路由逻辑按任务复杂度选模型。第三上下文裁剪。前面讲过的分层管理把无效信息砍掉。这一项通常能省 40% 以上的 token。第四批量处理。能合并的请求合并减少调用次数。比如一次读多个文件比多次单独读要省。第五监控告警。设置每日 token 消耗上限超了告警。避免某天逻辑出 bug 疯狂烧钱。4.4 与 Obsidian 的集成方式Obsidian 的库本质就是一个文件夹里面全是 Markdown 文件。Harness 直接读写这个文件夹就行不需要什么特殊接口。集成点主要有读Harness 检索知识库时直接遍历 Obsidian 库的文件夹读 Markdown 文件。写Harness 生成的决策记录、踩坑日志直接写成 Markdown 文件放进库里Obsidian 会自动索引。链接利用 Obsidian 的双向链接语法[[文件名]]让 Harness 生成的内容之间建立关联方便人后续浏览。热搜里提到的obsidian插件推荐如果要做这类集成建议装几个增强 Markdown 处理的插件比如表格编辑、代码块高亮之类的提升人的阅读体验。但注意插件别装太多容易冲突热搜里harness failed to load plugins这类问题很多时候就是插件冲突导致的。5. 常见问题与排查技巧实录5.1 模型输出格式不稳定怎么办这是最高频的问题。模型有时候返回 JSON有时候返回 Markdown有时候夹带解释文字解析起来很头疼。解决办法在 prompt 里明确格式要求并给一个示例。示例比描述有效得多。加格式校验和重试。解析失败时把错误信息返回给模型让它重新生成。用结构化输出能力。如果模型支持强制 JSON 输出优先用这个比靠 prompt 约束可靠。我踩过的坑是一开始只靠 prompt 约束模型十次里有两次跑偏导致流程中断。后来加了校验重试稳定性大幅提升。重试次数建议设 2 到 3 次再多就是浪费。5.2 工具调用陷入死循环模型可能反复调用同一个工具比如一直读同一个文件或者反复执行失败的命令。排查思路检查工具返回信息是否清晰。如果返回模糊模型不知道成功还是失败就会重试。加调用次数限制。同一个工具同一参数连续调用超过 N 次就强制中断返回提示。加状态检查。如果连续几轮任务状态没变化说明卡住了主动介入。注意死循环往往不是模型笨而是你的工具反馈设计有问题。模型拿不到有效信息只能瞎试。把反馈做清楚大部分死循环会自然消失。5.3 上下文超限的处理长任务跑久了上下文必然超限。处理方式情况处理方式说明接近上限压缩历史对话保留结论丢弃过程已超限强制摘要把当前状态总结成简短描述重开上下文频繁超限检查检索逻辑可能是检索注入了太多无关内容强制摘要这个操作要小心摘要质量差会丢关键信息。建议摘要后让模型确认一遍关键约束是否保留。5.4 成本突然飙升的排查某天发现 token 消耗是平时的好几倍排查顺序看日志找出消耗最大的几轮调用。检查这几轮的上下文大小是不是检索注入了异常大的文件。检查是否有死循环或重试风暴。检查模型路由是否失效简单任务被路由到了大模型。我遇到过一次是因为某个 Markdown 文件被误写成了几万行检索时整个注入单轮就烧掉大量 token。后来加了单文件注入大小限制问题解决。5.5 项目后期维护的注意事项九个月的项目后期维护比前期开发更考验人。几个建议文档要跟上。代码改了相关 Markdown 文档同步更新否则 Harness 检索到的是过时信息会误导模型。定期重构知识库。把零散笔记合并整理删除过时内容。版本化 Harness 配置。prompt 模板、工具定义这些用 Git 管理方便回滚。保留人工审核环节。关键代码和决策不要完全交给模型人要把关。最后分享一个我自己的习惯每周花半小时把这一周的决策和踩坑整理成 Markdown 存进 Obsidian。这半小时的投入在后续几个月里能省下大量重新思考的时间。一个人做长周期项目拼的不是爆发力是这套自我管理的系统能不能持续运转。Harness 是给模型用的骨架而 Obsidian 里的那些 Markdown是给你自己用的骨架。两套骨架都立住了20 万行代码才不是天方夜谭。