1. 一个人九个月二十万行代码背后的真实工程逻辑先把数字摊开来看。九个月按每月有效工作日22天算总共不到200个工作日。20万行代码平均每个工作日要产出1000行以上。这个数字放在传统软件工程里几乎不可能因为正常项目的代码量增长曲线是前期慢、中期快、后期收敛而且大量时间花在需求对齐、评审、联调、返工上。但如果是一个人加一个Agent系统的组合这个数字就变得可以理解了——因为真正的产出不是手写出来的而是Harness架构下的Agent流水线批量生成、校验、修正出来的。这里的关键词是Harness。很多人第一次看到这个词会以为是某个具体工具的名字其实它更接近一种架构范式把大模型当作一个需要被约束、驱动、校验的执行引擎而不是一个聊天对象。Harness的本意是马具、挽具引申到AI工程里就是给模型套上一套可控的执行框架——输入怎么组织、上下文怎么裁剪、工具怎么调用、输出怎么验证、失败怎么重试全部由外层框架决定模型只负责它最擅长的那部分推理和生成。这个项目标题里还有几个信息量极大的点每个月烧掉40亿 token。40亿token是什么概念按主流大模型API的定价区间粗略估算如果全部走中高端模型月成本在数万到数十万人民币量级即便大量使用缓存、批处理和便宜模型分流这也是一笔实打实的投入。这说明这个项目不是玩具而是高频、长上下文、多轮迭代的重度Agent应用。而支撑这种消耗的必然是Harness架构——因为只有Harness才能把token花在刀刃上而不是浪费在无意义的上下文堆砌和重复推理上。再看热搜词里的Claude Code、Obsidian、Markdown、Agent、deepseek harness、harness engineering这几个词基本勾勒出了这个项目的技术栈轮廓用Claude Code这类Agent编程工具做代码生成和文件操作用Obsidian做知识管理和项目台账用Markdown做中间格式和文档载体用Harness做整体调度和约束。这套组合不是随便凑的而是一个人对抗20万行代码复杂度的必然选择。我先把结论放在前面这个项目真正值得学的不是九个月20万行这个结果而是Harness架构如何把一个人的产能放大到一个小团队的水平。下面我会从架构设计、核心细节、实操流程、问题排查四个维度把这个项目的工程逻辑拆开讲清楚。适合谁看如果你正在做Agent应用、想用AI辅助大型项目、或者单纯好奇一个人怎么管20万行代码这篇内容应该能给你一些可以直接抄作业的东西。2. Harness架构的整体设计与选型考量2.1 为什么是Harness而不是普通Agent框架市面上Agent框架不少从早期的ReAct模式到后来的多Agent协作框架选择很多。但这个项目选了Harness核心原因在于控制粒度。普通Agent框架的典型问题是模型自主性太强导致行为不可预测、成本不可控、结果不可复现。你让它改一个bug它可能顺手重构了三个文件你让它生成一个模块它可能引入五个你没要求的依赖。在20万行代码的规模下这种自主性是灾难。Harness的思路正好相反把模型的自由度压缩到最小把框架的控制力放到最大。具体来说Harness架构通常包含这几层任务编排层决定下一步做什么而不是让模型自己决定。这一层用状态机或DAG来管理任务流每个节点是一个明确的原子操作。上下文管理层决定给模型看什么。这是Harness最核心的部分因为40亿token的消耗大头就在这里。上下文不是越多越好而是要精准裁剪——只给当前任务相关的代码片段、文档、历史记录。工具执行层决定模型能做什么。文件读写、命令执行、搜索、格式化全部封装成受控工具模型只能通过工具接口操作不能直接碰系统。输出校验层决定结果对不对。语法检查、类型检查、测试运行、格式校验全部自动化不通过就回退重试。成本控制层决定花多少。token预算、模型分流、缓存命中、失败熔断全部在这一层管理。这五层加起来就是Harness。它本质上是一个围绕大模型构建的操作系统模型是CPUHarness是内核。这个类比我觉得很准确因为内核的职责就是资源管理和进程调度而Harness的职责就是上下文管理和任务调度。2.2 技术栈选型的背后逻辑热搜词里出现的Claude Code、Obsidian、Markdown不是随意搭配而是各有明确分工。Claude Code在这个项目里承担的是代码生成与文件操作的主力。它的优势在于对代码库的理解能力和文件级操作能力能直接读写项目文件、执行命令、运行测试。相比纯API调用Claude Code这类工具把模型工具上下文打包好了省去了大量胶水代码。但要注意Claude Code本身也是一个Agent它的行为同样需要被Harness约束——比如限制它能改哪些目录、能执行哪些命令、单次任务的最大token预算。Obsidian的角色是知识管理和项目台账。20万行代码的项目文档量是巨大的。需求文档、设计文档、API文档、变更记录、问题追踪如果散落在各处一个人根本管不过来。Obsidian的双向链接和图谱视图能把零散笔记连成网络而它的本地Markdown存储又保证了数据可迁移、可版本控制。热搜词里的obsidian创建项目管理台账就是这个用法——用Obsidian做项目的第二大脑所有决策记录、架构图、待办清单都在里面Agent需要时可以直接读取。Markdown是中间格式和通用载体。为什么不用JSON或YAML做中间格式因为Markdown对人类友好对模型也友好。模型生成Markdown的准确率远高于生成复杂结构化数据而且Markdown可以直接被Obsidian渲染、被版本控制diff、被转换成其他格式。热搜词里的markdown表格转换excel、markdown转word工作流说明这个项目里Markdown承担了大量文档流转工作。但要注意Markdown的坑换行语法在不同渲染器下行为不一致表格在复杂内容下容易错位数学符号需要特定渲染器支持。这些细节在Harness里都要做规范化处理。deepseek harness这个热搜词值得单独说。DeepSeek系列模型在这个项目里很可能承担了成本敏感型任务——比如批量代码格式化、简单重构、文档生成、日志分析。这些任务不需要顶级模型的推理能力用便宜模型跑量把贵模型留给核心逻辑。这就是Harness的模型分流策略不同任务走不同模型成本能降一个数量级。2.3 一个人如何管理20万行代码的复杂度这是整个项目最核心的问题。传统答案是管不了但Harness架构给出了新答案把复杂度交给框架人只做决策。具体来说这个人每天的工作不是写代码而是定义任务把需求拆成Harness能理解的原子任务写清楚输入、输出、验收标准。审查结果Agent生成代码后人做code review但review的重点不是逐行看而是看测试是否通过、接口是否符合预期、有没有引入意外依赖。调整Harness当发现Agent反复犯同类错误时不是手动改代码而是改Harness的约束规则——比如加一条校验、改一段prompt、调整上下文裁剪策略。维护知识库把决策、踩坑、模式记录到Obsidian让Agent下次能读到。这个工作模式的关键在于杠杆率。人花1小时调整Harness规则可能让后续100个任务都受益。而如果人花1小时手动改代码只解决了1个任务。九个月20万行代码靠的就是这种杠杆率的累积。注意Harness架构不是让AI自动写代码而是让人用更高的抽象层级指挥AI写代码。人的角色从执行者变成规则制定者这个转变是项目成败的关键。3. 核心细节解析与实操要点3.1 上下文管理40亿token花在哪里40亿token的月消耗如果平均到每天大约是1.3亿token。这个量级下上下文管理就是成本管理的核心。我见过太多Agent项目token大部分浪费在三个地方重复读取整个代码库、把无关历史塞进上下文、生成冗长的中间推理。Harness架构下的上下文管理核心策略是分层裁剪按需加载全局层项目结构、核心接口定义、编码规范。这部分相对稳定可以缓存每次只注入摘要。模块层当前任务涉及的模块代码。按依赖关系动态加载不相关的模块不注入。任务层当前任务的具体需求、相关历史、验收标准。这部分每次不同但可以复用相似任务的模板。会话层当前对话的短期记忆。严格控制轮数超过阈值就摘要压缩。实测下来这套分层策略能把单任务的平均token消耗降低60%以上。具体做法是给每个代码文件生成一个语义摘要不是简单截断而是用便宜模型生成的功能描述存在索引里。Agent需要某个文件时先读摘要判断相关性相关才加载全文。这个摘要索引的维护成本很低但收益极大。另一个关键点是缓存。大模型API普遍支持prompt caching相同的前缀部分可以命中缓存成本大幅降低。Harness要把稳定的上下文如系统prompt、编码规范、项目结构放在prompt前部把变化的部分放在后部最大化缓存命中率。这个细节看起来小但在40亿token的规模下能省下的成本非常可观。3.2 任务编排状态机比自由对话可靠得多普通Agent用对话循环来推进任务模型输出一个动作执行把结果喂回去再输出下一个动作。这种方式灵活但不可控容易陷入循环、跑偏、或者提前结束。Harness用的是显式状态机。每个任务被定义为一个状态图节点是原子操作边是转移条件。比如实现一个API接口这个任务状态图可能是读取接口规范 → 2. 生成接口骨架 → 3. 生成实现逻辑 → 4. 生成单元测试 → 5. 运行测试 → 6. 测试通过则提交失败则回到3并附带错误信息。每个状态节点有明确的输入输出和验收标准。模型只在节点内部做推理节点之间的转移由框架控制。这样做的好处是可观测、可重试、可中断、可恢复。任务跑到一半失败了能从最后一个成功节点继续不用从头来。实操中要注意的是状态粒度。粒度太粗一个节点里模型要做太多事容易出错粒度太细节点数量爆炸编排成本高。我的经验是一个节点对应一个可独立验证的产出。比如生成函数实现是一个节点生成测试是另一个节点因为这两者的验收标准不同。3.3 输出校验自动化验收是规模化的前提一个人管20万行代码如果每个产出都要人工验收根本忙不过来。所以Harness必须把能自动化的验收全部自动化。这个项目里的校验层大概包含语法校验代码能不能解析这是最低门槛。类型校验类型系统能不能通过能抓出大量低级错误。Lint校验编码规范、命名约定、复杂度阈值。测试校验单元测试、集成测试是否通过。接口校验生成的接口是否符合预定义的schema。依赖校验有没有引入未授权的依赖有没有循环依赖。这些校验全部通过才进入人工review。人工review的重点是设计合理性和业务正确性而不是语法和格式。这样人的时间就花在了真正需要判断力的地方。提示校验规则要版本化和代码一起管理。每次发现Agent犯新错误就加一条校验规则这样错误不会重复出现。这是Harness越用越聪明的核心机制。3.4 模型分流不是所有任务都值得用最贵的模型40亿token如果全走顶级模型成本会高到不可持续。Harness的模型分流策略通常是任务类型推荐模型档位理由核心逻辑生成顶级模型需要强推理错误代价高代码重构中高端模型需要理解上下文但模式相对固定文档生成中端模型对推理要求低对语言流畅度要求高格式化/简单转换便宜模型规则明确几乎不需要推理摘要/索引便宜模型批量处理成本敏感校验/分类便宜模型或本地模型任务简单可离线这套分流策略的关键是任务分类器。Harness要先判断一个任务属于哪一类再决定用哪个模型。分类器本身可以用便宜模型或规则引擎实现。实测下来合理分流能把整体成本降低70%以上而质量损失很小。3.5 Markdown与Obsidian的工程化用法Markdown在这个项目里不只是文档格式而是Agent和知识库之间的接口。Agent读Obsidian笔记获取上下文写Obsidian笔记记录产出整个过程通过Markdown文件完成。这种设计的优势是解耦Agent不需要理解Obsidian的内部结构只需要读写Markdown文件Obsidian也不需要知道Agent的存在它只是一个文件目录。但Markdown有几个工程化的坑要处理换行不同渲染器对单换行和双换行的处理不同。Harness要统一规范比如强制双换行表示段落分隔。表格复杂表格在Markdown里容易错位尤其是包含代码或长文本的单元格。建议复杂数据用代码块或独立文件Markdown里只放简单表格。数学符号需要特定渲染器支持Obsidian要装对应插件。Agent生成数学内容时要检查渲染兼容性。链接Obsidian的双向链接语法[[...]]和标准Markdown链接[...](...)不同Harness要统一处理。Obsidian的插件生态在这里也很有用。比如Markdown Preview Enhanced提供更强的预览能力Docxer类插件支持导出Word项目管理台账类插件能把笔记变成看板。这些插件让Obsidian从一个笔记工具变成了轻量级项目管理平台一个人就能维护整个项目的知识体系。4. 实操过程与核心环节实现4.1 环境搭建从零到可运行的最小Harness假设你现在要从零搭一套类似的Harness最小可运行版本需要这些组件第一步确定Agent执行环境。如果用的是Claude Code这类工具安装和配置是基础。热搜词里的claude code安装、vscode配置claude code说明很多人卡在这一步。核心是装好工具配好API密钥确认能正常读写文件和执行命令。国内环境下要注意网络和账号问题这里不展开。第二步建立项目目录结构。推荐的结构是project/ src/ # 源代码 docs/ # 文档Markdown .harness/ # Harness配置 tasks/ # 任务定义 rules/ # 校验规则 prompts/ # 提示词模板 cache/ # 上下文缓存 obsidian/ # Obsidian库可软链到docs这个结构的关键是分离关注点代码、文档、Harness配置各归各的互不干扰。第三步定义任务模板。每个任务用Markdown或YAML定义包含任务ID、输入、输出、验收标准、使用的模型档位、最大token预算。比如id: impl-api-user-login input: spec: docs/api/user-login.md context: - src/models/user.py - src/utils/auth.py output: - src/api/user_login.py - tests/test_user_login.py acceptance: - syntax: pass - type: pass - test: pass - lint: pass model: tier-1 max_tokens: 50000这个模板就是Harness的任务契约Agent按契约执行框架按契约验收。第四步实现上下文加载器。这是Harness的核心组件。它根据任务定义从代码库和Obsidian里加载相关上下文做摘要和裁剪组装成prompt。实现要点用文件摘要索引做相关性判断用依赖图做传递闭包用token计数器做预算控制。第五步实现校验流水线。把语法、类型、Lint、测试等校验串成流水线每个校验是一个独立函数返回通过/失败和错误详情。失败时把错误详情附到下一次重试的上下文里。第六步实现成本追踪。每次模型调用记录token消耗、模型档位、任务ID汇总到日报。这样你能清楚看到钱花在哪里哪些任务可以优化。这套最小Harness大概几百行代码就能跑起来但它是后续所有规模化的基础。4.2 任务执行流程一次完整的Agent调用以一个具体任务为例给用户模块加一个登录接口。完整流程是任务入队Harness读取任务定义确认输入文件存在输出路径可写。上下文组装加载user-login.md规范加载user.py和auth.py的摘要和全文加载相关编码规范组装prompt。模型调用按任务定义的模型档位调用传入prompt设置max_tokens和temperature。产出解析模型返回的代码块被解析出来写入临时文件。校验流水线语法检查→类型检查→Lint→运行测试。假设测试失败错误信息被捕获。重试把错误信息附到上下文重新调用模型要求修复。最多重试3次。人工review校验通过后任务进入review队列。人看设计是否合理接口是否符合预期。合并提交review通过代码合并到主分支任务标记完成相关笔记更新到Obsidian。这个流程里第6步的重试机制是质量的关键。很多Agent项目失败是因为一次生成不对就放弃了或者无限重试不收敛。Harness的重试要满足每次重试都带上具体错误信息重试次数有上限超过上限就转人工。4.3 参数计算token预算怎么定token预算不是拍脑袋定的要基于任务类型和历史数据。我的做法是冷启动阶段给每个任务类型设一个宽松预算记录实际消耗。稳定阶段取历史消耗的P90作为预算超过就告警。优化阶段分析超预算任务看是上下文冗余还是模型选择不当针对性优化。以生成一个中等复杂度函数为例实测数据大概是输入上下文2000-5000 token输出500-1500 token加上重试平均1.5次单任务总消耗约5000-10000 token。如果一个月做4000个这样的任务就是2000万-4000万token。要凑到40亿说明任务量级和复杂度都远超这个例子——可能有大量长上下文任务如全模块重构和高频小任务如格式化、文档生成。注意token预算要留20%的缓冲因为模型输出长度有波动校验失败重试也会增加消耗。预算卡太死会导致任务频繁中断反而降低效率。4.4 Obsidian知识库的维护流程Obsidian在这个项目里不是顺便用用而是核心基础设施。维护流程大概是每日把当天的新决策、踩坑、模式记录到日记笔记打标签。每周整理日记把可复用的内容提炼到主题笔记更新双向链接。每月回顾知识图谱找出孤立笔记和过时内容清理或归档。任务前Harness自动从Obsidian加载相关笔记作为上下文。任务后Harness自动把任务产出摘要写回Obsidian。这个流程的关键是自动化。如果靠人手动维护很快就会荒废。Harness要能自动读写Obsidian的Markdown文件自动打标签自动建立链接。Obsidian的本地文件特性让这一切成为可能——它就是一个文件夹Agent可以直接操作。5. 常见问题与排查技巧实录5.1 Agent执行中断与错误处理热搜词里的agent execution terminated due to error和harness failed to load plugins是两类高频问题。执行中断的常见原因和排查思路现象可能原因排查方法解决任务跑到一半停token超预算查成本日志提高预算或优化上下文模型返回空上下文过长被截断查prompt长度裁剪上下文工具调用失败权限或路径问题查工具日志修正权限或路径校验反复失败任务定义不清查任务契约细化验收标准无限重试错误信息没传对查重试上下文确保错误详情完整传入插件加载失败通常发生在Harness启动阶段原因可能是依赖缺失、版本不兼容、配置错误。排查顺序是先看日志确认是哪个插件再检查该插件的依赖和配置最后考虑版本回退。5.2 上下文污染与模型跑偏这是Agent项目最隐蔽的问题。表现是模型生成的代码越来越偏离项目规范或者开始幻觉出不存在的接口和依赖。根本原因通常是上下文里混入了错误信息——比如之前失败任务的错误输出没清理干净或者Obsidian里有过时的笔记被加载了。排查技巧定期审计上下文。随机抽几个任务把实际传给模型的prompt打印出来人工检查有没有无关或错误内容。这个动作我建议每周做一次能发现很多隐藏问题。解决方法是上下文隔离不同任务类型的上下文分开管理失败任务的上下文不污染成功任务过时笔记打上归档标签不被加载。5.3 成本失控的预警与止损40亿token的规模下成本失控是最大风险。预警机制要包含日消耗告警超过日均预算120%就告警。单任务告警超过任务预算就中断转人工。模型档位审计定期检查有没有任务用错了模型档位。缓存命中率监控命中率低于阈值说明上下文组织有问题。止损手段熔断机制。当某个任务类型连续失败或超预算自动暂停该类任务等人工介入。这能防止一个bug导致整晚烧钱。5.4 代码质量与可维护性20万行代码如果质量差维护成本会指数级上升。Harness要强制保证统一的代码风格Lint规则要严格Agent生成后自动格式化。充分的测试覆盖每个生成的功能都要有对应测试测试不通过不合并。清晰的模块边界依赖校验要防止循环依赖和越界调用。完整的文档每个模块要有Markdown文档由Agent自动生成和维护。提示定期做代码考古——随机抽一个模块看它的历史变更和当前状态评估Agent生成代码的可维护性。如果发现某个模块越来越乱说明Harness的约束不够要针对性加强。5.5 一个人协作的节奏管理最后说一个非技术但极重要的问题节奏。一个人管这么大的项目最大的敌人不是技术难题而是疲劳和决策质量下降。我的经验是上午做决策定义任务、审查产出、调整Harness这些需要清醒头脑。下午做维护整理Obsidian、审计上下文、优化规则这些相对机械。晚上让Agent跑批把大批量、低风险的任务安排在夜间第二天看结果。每周留一天不碰代码只做回顾和规划避免陷入细节。这个节奏的核心是把人的精力花在最高杠杆的地方把重复劳动交给Agent。九个月20万行代码靠的不是每天工作16小时而是让每一小时的产出都被Agent放大。6. 从这套架构里能带走什么如果你只想记一件事那就是Harness的本质是把写代码变成写规则。这个人九个月做的不是写了20万行代码而是设计了一套能让Agent稳定产出20万行代码的规则体系。代码是结果规则才是资产。具体能带走的东西有三样。第一是分层上下文管理的思路——不管你做不做Agent把信息按稳定性和相关性分层都是提升效率的通用方法。第二是显式状态机编排——把模糊的任务拆成可验证的原子步骤这个思路在任何项目管理里都适用。第三是自动化校验优先——能自动检查的绝不靠人眼人的时间要留给判断力。至于Obsidian和Markdown它们是这套架构的胶水不是核心但少了它们知识管理会散架。如果你要复现建议先从最小Harness跑通一个任务开始别一上来就追求40亿token的规模。规模是结果不是目标。我自己在类似项目里踩过的最大的坑是过早追求自动化。一开始就想让Agent全自动跑结果错误累积、上下文污染、成本失控最后不得不推倒重来。后来改成半自动——Agent生成人审查逐步把稳定的环节自动化——反而走得更快。这个教训我觉得比任何技术细节都值钱。 
长河君 · 2026/9/30 13:42:45 · 阅读 1.2k Harness架构实战：一个人如何用Agent九个月产出20万行代码
1. 一个人九个月二十万行代码背后的真实工程逻辑先把数字摊开来看。九个月按每月有效工作日22天算总共不到200个工作日。20万行代码平均每个工作日要产出1000行以上。这个数字放在传统软件工程里几乎不可能因为正常项目的代码量增长曲线是前期慢、中期快、后期收敛而且大量时间花在需求对齐、评审、联调、返工上。但如果是一个人加一个Agent系统的组合这个数字就变得可以理解了——因为真正的产出不是手写出来的而是Harness架构下的Agent流水线批量生成、校验、修正出来的。这里的关键词是Harness。很多人第一次看到这个词会以为是某个具体工具的名字其实它更接近一种架构范式把大模型当作一个需要被约束、驱动、校验的执行引擎而不是一个聊天对象。Harness的本意是马具、挽具引申到AI工程里就是给模型套上一套可控的执行框架——输入怎么组织、上下文怎么裁剪、工具怎么调用、输出怎么验证、失败怎么重试全部由外层框架决定模型只负责它最擅长的那部分推理和生成。这个项目标题里还有几个信息量极大的点每个月烧掉40亿 token。40亿token是什么概念按主流大模型API的定价区间粗略估算如果全部走中高端模型月成本在数万到数十万人民币量级即便大量使用缓存、批处理和便宜模型分流这也是一笔实打实的投入。这说明这个项目不是玩具而是高频、长上下文、多轮迭代的重度Agent应用。而支撑这种消耗的必然是Harness架构——因为只有Harness才能把token花在刀刃上而不是浪费在无意义的上下文堆砌和重复推理上。再看热搜词里的Claude Code、Obsidian、Markdown、Agent、deepseek harness、harness engineering这几个词基本勾勒出了这个项目的技术栈轮廓用Claude Code这类Agent编程工具做代码生成和文件操作用Obsidian做知识管理和项目台账用Markdown做中间格式和文档载体用Harness做整体调度和约束。这套组合不是随便凑的而是一个人对抗20万行代码复杂度的必然选择。我先把结论放在前面这个项目真正值得学的不是九个月20万行这个结果而是Harness架构如何把一个人的产能放大到一个小团队的水平。下面我会从架构设计、核心细节、实操流程、问题排查四个维度把这个项目的工程逻辑拆开讲清楚。适合谁看如果你正在做Agent应用、想用AI辅助大型项目、或者单纯好奇一个人怎么管20万行代码这篇内容应该能给你一些可以直接抄作业的东西。2. Harness架构的整体设计与选型考量2.1 为什么是Harness而不是普通Agent框架市面上Agent框架不少从早期的ReAct模式到后来的多Agent协作框架选择很多。但这个项目选了Harness核心原因在于控制粒度。普通Agent框架的典型问题是模型自主性太强导致行为不可预测、成本不可控、结果不可复现。你让它改一个bug它可能顺手重构了三个文件你让它生成一个模块它可能引入五个你没要求的依赖。在20万行代码的规模下这种自主性是灾难。Harness的思路正好相反把模型的自由度压缩到最小把框架的控制力放到最大。具体来说Harness架构通常包含这几层任务编排层决定下一步做什么而不是让模型自己决定。这一层用状态机或DAG来管理任务流每个节点是一个明确的原子操作。上下文管理层决定给模型看什么。这是Harness最核心的部分因为40亿token的消耗大头就在这里。上下文不是越多越好而是要精准裁剪——只给当前任务相关的代码片段、文档、历史记录。工具执行层决定模型能做什么。文件读写、命令执行、搜索、格式化全部封装成受控工具模型只能通过工具接口操作不能直接碰系统。输出校验层决定结果对不对。语法检查、类型检查、测试运行、格式校验全部自动化不通过就回退重试。成本控制层决定花多少。token预算、模型分流、缓存命中、失败熔断全部在这一层管理。这五层加起来就是Harness。它本质上是一个围绕大模型构建的操作系统模型是CPUHarness是内核。这个类比我觉得很准确因为内核的职责就是资源管理和进程调度而Harness的职责就是上下文管理和任务调度。2.2 技术栈选型的背后逻辑热搜词里出现的Claude Code、Obsidian、Markdown不是随意搭配而是各有明确分工。Claude Code在这个项目里承担的是代码生成与文件操作的主力。它的优势在于对代码库的理解能力和文件级操作能力能直接读写项目文件、执行命令、运行测试。相比纯API调用Claude Code这类工具把模型工具上下文打包好了省去了大量胶水代码。但要注意Claude Code本身也是一个Agent它的行为同样需要被Harness约束——比如限制它能改哪些目录、能执行哪些命令、单次任务的最大token预算。Obsidian的角色是知识管理和项目台账。20万行代码的项目文档量是巨大的。需求文档、设计文档、API文档、变更记录、问题追踪如果散落在各处一个人根本管不过来。Obsidian的双向链接和图谱视图能把零散笔记连成网络而它的本地Markdown存储又保证了数据可迁移、可版本控制。热搜词里的obsidian创建项目管理台账就是这个用法——用Obsidian做项目的第二大脑所有决策记录、架构图、待办清单都在里面Agent需要时可以直接读取。Markdown是中间格式和通用载体。为什么不用JSON或YAML做中间格式因为Markdown对人类友好对模型也友好。模型生成Markdown的准确率远高于生成复杂结构化数据而且Markdown可以直接被Obsidian渲染、被版本控制diff、被转换成其他格式。热搜词里的markdown表格转换excel、markdown转word工作流说明这个项目里Markdown承担了大量文档流转工作。但要注意Markdown的坑换行语法在不同渲染器下行为不一致表格在复杂内容下容易错位数学符号需要特定渲染器支持。这些细节在Harness里都要做规范化处理。deepseek harness这个热搜词值得单独说。DeepSeek系列模型在这个项目里很可能承担了成本敏感型任务——比如批量代码格式化、简单重构、文档生成、日志分析。这些任务不需要顶级模型的推理能力用便宜模型跑量把贵模型留给核心逻辑。这就是Harness的模型分流策略不同任务走不同模型成本能降一个数量级。2.3 一个人如何管理20万行代码的复杂度这是整个项目最核心的问题。传统答案是管不了但Harness架构给出了新答案把复杂度交给框架人只做决策。具体来说这个人每天的工作不是写代码而是定义任务把需求拆成Harness能理解的原子任务写清楚输入、输出、验收标准。审查结果Agent生成代码后人做code review但review的重点不是逐行看而是看测试是否通过、接口是否符合预期、有没有引入意外依赖。调整Harness当发现Agent反复犯同类错误时不是手动改代码而是改Harness的约束规则——比如加一条校验、改一段prompt、调整上下文裁剪策略。维护知识库把决策、踩坑、模式记录到Obsidian让Agent下次能读到。这个工作模式的关键在于杠杆率。人花1小时调整Harness规则可能让后续100个任务都受益。而如果人花1小时手动改代码只解决了1个任务。九个月20万行代码靠的就是这种杠杆率的累积。注意Harness架构不是让AI自动写代码而是让人用更高的抽象层级指挥AI写代码。人的角色从执行者变成规则制定者这个转变是项目成败的关键。3. 核心细节解析与实操要点3.1 上下文管理40亿token花在哪里40亿token的月消耗如果平均到每天大约是1.3亿token。这个量级下上下文管理就是成本管理的核心。我见过太多Agent项目token大部分浪费在三个地方重复读取整个代码库、把无关历史塞进上下文、生成冗长的中间推理。Harness架构下的上下文管理核心策略是分层裁剪按需加载全局层项目结构、核心接口定义、编码规范。这部分相对稳定可以缓存每次只注入摘要。模块层当前任务涉及的模块代码。按依赖关系动态加载不相关的模块不注入。任务层当前任务的具体需求、相关历史、验收标准。这部分每次不同但可以复用相似任务的模板。会话层当前对话的短期记忆。严格控制轮数超过阈值就摘要压缩。实测下来这套分层策略能把单任务的平均token消耗降低60%以上。具体做法是给每个代码文件生成一个语义摘要不是简单截断而是用便宜模型生成的功能描述存在索引里。Agent需要某个文件时先读摘要判断相关性相关才加载全文。这个摘要索引的维护成本很低但收益极大。另一个关键点是缓存。大模型API普遍支持prompt caching相同的前缀部分可以命中缓存成本大幅降低。Harness要把稳定的上下文如系统prompt、编码规范、项目结构放在prompt前部把变化的部分放在后部最大化缓存命中率。这个细节看起来小但在40亿token的规模下能省下的成本非常可观。3.2 任务编排状态机比自由对话可靠得多普通Agent用对话循环来推进任务模型输出一个动作执行把结果喂回去再输出下一个动作。这种方式灵活但不可控容易陷入循环、跑偏、或者提前结束。Harness用的是显式状态机。每个任务被定义为一个状态图节点是原子操作边是转移条件。比如实现一个API接口这个任务状态图可能是读取接口规范 → 2. 生成接口骨架 → 3. 生成实现逻辑 → 4. 生成单元测试 → 5. 运行测试 → 6. 测试通过则提交失败则回到3并附带错误信息。每个状态节点有明确的输入输出和验收标准。模型只在节点内部做推理节点之间的转移由框架控制。这样做的好处是可观测、可重试、可中断、可恢复。任务跑到一半失败了能从最后一个成功节点继续不用从头来。实操中要注意的是状态粒度。粒度太粗一个节点里模型要做太多事容易出错粒度太细节点数量爆炸编排成本高。我的经验是一个节点对应一个可独立验证的产出。比如生成函数实现是一个节点生成测试是另一个节点因为这两者的验收标准不同。3.3 输出校验自动化验收是规模化的前提一个人管20万行代码如果每个产出都要人工验收根本忙不过来。所以Harness必须把能自动化的验收全部自动化。这个项目里的校验层大概包含语法校验代码能不能解析这是最低门槛。类型校验类型系统能不能通过能抓出大量低级错误。Lint校验编码规范、命名约定、复杂度阈值。测试校验单元测试、集成测试是否通过。接口校验生成的接口是否符合预定义的schema。依赖校验有没有引入未授权的依赖有没有循环依赖。这些校验全部通过才进入人工review。人工review的重点是设计合理性和业务正确性而不是语法和格式。这样人的时间就花在了真正需要判断力的地方。提示校验规则要版本化和代码一起管理。每次发现Agent犯新错误就加一条校验规则这样错误不会重复出现。这是Harness越用越聪明的核心机制。3.4 模型分流不是所有任务都值得用最贵的模型40亿token如果全走顶级模型成本会高到不可持续。Harness的模型分流策略通常是任务类型推荐模型档位理由核心逻辑生成顶级模型需要强推理错误代价高代码重构中高端模型需要理解上下文但模式相对固定文档生成中端模型对推理要求低对语言流畅度要求高格式化/简单转换便宜模型规则明确几乎不需要推理摘要/索引便宜模型批量处理成本敏感校验/分类便宜模型或本地模型任务简单可离线这套分流策略的关键是任务分类器。Harness要先判断一个任务属于哪一类再决定用哪个模型。分类器本身可以用便宜模型或规则引擎实现。实测下来合理分流能把整体成本降低70%以上而质量损失很小。3.5 Markdown与Obsidian的工程化用法Markdown在这个项目里不只是文档格式而是Agent和知识库之间的接口。Agent读Obsidian笔记获取上下文写Obsidian笔记记录产出整个过程通过Markdown文件完成。这种设计的优势是解耦Agent不需要理解Obsidian的内部结构只需要读写Markdown文件Obsidian也不需要知道Agent的存在它只是一个文件目录。但Markdown有几个工程化的坑要处理换行不同渲染器对单换行和双换行的处理不同。Harness要统一规范比如强制双换行表示段落分隔。表格复杂表格在Markdown里容易错位尤其是包含代码或长文本的单元格。建议复杂数据用代码块或独立文件Markdown里只放简单表格。数学符号需要特定渲染器支持Obsidian要装对应插件。Agent生成数学内容时要检查渲染兼容性。链接Obsidian的双向链接语法[[...]]和标准Markdown链接[...](...)不同Harness要统一处理。Obsidian的插件生态在这里也很有用。比如Markdown Preview Enhanced提供更强的预览能力Docxer类插件支持导出Word项目管理台账类插件能把笔记变成看板。这些插件让Obsidian从一个笔记工具变成了轻量级项目管理平台一个人就能维护整个项目的知识体系。4. 实操过程与核心环节实现4.1 环境搭建从零到可运行的最小Harness假设你现在要从零搭一套类似的Harness最小可运行版本需要这些组件第一步确定Agent执行环境。如果用的是Claude Code这类工具安装和配置是基础。热搜词里的claude code安装、vscode配置claude code说明很多人卡在这一步。核心是装好工具配好API密钥确认能正常读写文件和执行命令。国内环境下要注意网络和账号问题这里不展开。第二步建立项目目录结构。推荐的结构是project/ src/ # 源代码 docs/ # 文档Markdown .harness/ # Harness配置 tasks/ # 任务定义 rules/ # 校验规则 prompts/ # 提示词模板 cache/ # 上下文缓存 obsidian/ # Obsidian库可软链到docs这个结构的关键是分离关注点代码、文档、Harness配置各归各的互不干扰。第三步定义任务模板。每个任务用Markdown或YAML定义包含任务ID、输入、输出、验收标准、使用的模型档位、最大token预算。比如id: impl-api-user-login input: spec: docs/api/user-login.md context: - src/models/user.py - src/utils/auth.py output: - src/api/user_login.py - tests/test_user_login.py acceptance: - syntax: pass - type: pass - test: pass - lint: pass model: tier-1 max_tokens: 50000这个模板就是Harness的任务契约Agent按契约执行框架按契约验收。第四步实现上下文加载器。这是Harness的核心组件。它根据任务定义从代码库和Obsidian里加载相关上下文做摘要和裁剪组装成prompt。实现要点用文件摘要索引做相关性判断用依赖图做传递闭包用token计数器做预算控制。第五步实现校验流水线。把语法、类型、Lint、测试等校验串成流水线每个校验是一个独立函数返回通过/失败和错误详情。失败时把错误详情附到下一次重试的上下文里。第六步实现成本追踪。每次模型调用记录token消耗、模型档位、任务ID汇总到日报。这样你能清楚看到钱花在哪里哪些任务可以优化。这套最小Harness大概几百行代码就能跑起来但它是后续所有规模化的基础。4.2 任务执行流程一次完整的Agent调用以一个具体任务为例给用户模块加一个登录接口。完整流程是任务入队Harness读取任务定义确认输入文件存在输出路径可写。上下文组装加载user-login.md规范加载user.py和auth.py的摘要和全文加载相关编码规范组装prompt。模型调用按任务定义的模型档位调用传入prompt设置max_tokens和temperature。产出解析模型返回的代码块被解析出来写入临时文件。校验流水线语法检查→类型检查→Lint→运行测试。假设测试失败错误信息被捕获。重试把错误信息附到上下文重新调用模型要求修复。最多重试3次。人工review校验通过后任务进入review队列。人看设计是否合理接口是否符合预期。合并提交review通过代码合并到主分支任务标记完成相关笔记更新到Obsidian。这个流程里第6步的重试机制是质量的关键。很多Agent项目失败是因为一次生成不对就放弃了或者无限重试不收敛。Harness的重试要满足每次重试都带上具体错误信息重试次数有上限超过上限就转人工。4.3 参数计算token预算怎么定token预算不是拍脑袋定的要基于任务类型和历史数据。我的做法是冷启动阶段给每个任务类型设一个宽松预算记录实际消耗。稳定阶段取历史消耗的P90作为预算超过就告警。优化阶段分析超预算任务看是上下文冗余还是模型选择不当针对性优化。以生成一个中等复杂度函数为例实测数据大概是输入上下文2000-5000 token输出500-1500 token加上重试平均1.5次单任务总消耗约5000-10000 token。如果一个月做4000个这样的任务就是2000万-4000万token。要凑到40亿说明任务量级和复杂度都远超这个例子——可能有大量长上下文任务如全模块重构和高频小任务如格式化、文档生成。注意token预算要留20%的缓冲因为模型输出长度有波动校验失败重试也会增加消耗。预算卡太死会导致任务频繁中断反而降低效率。4.4 Obsidian知识库的维护流程Obsidian在这个项目里不是顺便用用而是核心基础设施。维护流程大概是每日把当天的新决策、踩坑、模式记录到日记笔记打标签。每周整理日记把可复用的内容提炼到主题笔记更新双向链接。每月回顾知识图谱找出孤立笔记和过时内容清理或归档。任务前Harness自动从Obsidian加载相关笔记作为上下文。任务后Harness自动把任务产出摘要写回Obsidian。这个流程的关键是自动化。如果靠人手动维护很快就会荒废。Harness要能自动读写Obsidian的Markdown文件自动打标签自动建立链接。Obsidian的本地文件特性让这一切成为可能——它就是一个文件夹Agent可以直接操作。5. 常见问题与排查技巧实录5.1 Agent执行中断与错误处理热搜词里的agent execution terminated due to error和harness failed to load plugins是两类高频问题。执行中断的常见原因和排查思路现象可能原因排查方法解决任务跑到一半停token超预算查成本日志提高预算或优化上下文模型返回空上下文过长被截断查prompt长度裁剪上下文工具调用失败权限或路径问题查工具日志修正权限或路径校验反复失败任务定义不清查任务契约细化验收标准无限重试错误信息没传对查重试上下文确保错误详情完整传入插件加载失败通常发生在Harness启动阶段原因可能是依赖缺失、版本不兼容、配置错误。排查顺序是先看日志确认是哪个插件再检查该插件的依赖和配置最后考虑版本回退。5.2 上下文污染与模型跑偏这是Agent项目最隐蔽的问题。表现是模型生成的代码越来越偏离项目规范或者开始幻觉出不存在的接口和依赖。根本原因通常是上下文里混入了错误信息——比如之前失败任务的错误输出没清理干净或者Obsidian里有过时的笔记被加载了。排查技巧定期审计上下文。随机抽几个任务把实际传给模型的prompt打印出来人工检查有没有无关或错误内容。这个动作我建议每周做一次能发现很多隐藏问题。解决方法是上下文隔离不同任务类型的上下文分开管理失败任务的上下文不污染成功任务过时笔记打上归档标签不被加载。5.3 成本失控的预警与止损40亿token的规模下成本失控是最大风险。预警机制要包含日消耗告警超过日均预算120%就告警。单任务告警超过任务预算就中断转人工。模型档位审计定期检查有没有任务用错了模型档位。缓存命中率监控命中率低于阈值说明上下文组织有问题。止损手段熔断机制。当某个任务类型连续失败或超预算自动暂停该类任务等人工介入。这能防止一个bug导致整晚烧钱。5.4 代码质量与可维护性20万行代码如果质量差维护成本会指数级上升。Harness要强制保证统一的代码风格Lint规则要严格Agent生成后自动格式化。充分的测试覆盖每个生成的功能都要有对应测试测试不通过不合并。清晰的模块边界依赖校验要防止循环依赖和越界调用。完整的文档每个模块要有Markdown文档由Agent自动生成和维护。提示定期做代码考古——随机抽一个模块看它的历史变更和当前状态评估Agent生成代码的可维护性。如果发现某个模块越来越乱说明Harness的约束不够要针对性加强。5.5 一个人协作的节奏管理最后说一个非技术但极重要的问题节奏。一个人管这么大的项目最大的敌人不是技术难题而是疲劳和决策质量下降。我的经验是上午做决策定义任务、审查产出、调整Harness这些需要清醒头脑。下午做维护整理Obsidian、审计上下文、优化规则这些相对机械。晚上让Agent跑批把大批量、低风险的任务安排在夜间第二天看结果。每周留一天不碰代码只做回顾和规划避免陷入细节。这个节奏的核心是把人的精力花在最高杠杆的地方把重复劳动交给Agent。九个月20万行代码靠的不是每天工作16小时而是让每一小时的产出都被Agent放大。6. 从这套架构里能带走什么如果你只想记一件事那就是Harness的本质是把写代码变成写规则。这个人九个月做的不是写了20万行代码而是设计了一套能让Agent稳定产出20万行代码的规则体系。代码是结果规则才是资产。具体能带走的东西有三样。第一是分层上下文管理的思路——不管你做不做Agent把信息按稳定性和相关性分层都是提升效率的通用方法。第二是显式状态机编排——把模糊的任务拆成可验证的原子步骤这个思路在任何项目管理里都适用。第三是自动化校验优先——能自动检查的绝不靠人眼人的时间要留给判断力。至于Obsidian和Markdown它们是这套架构的胶水不是核心但少了它们知识管理会散架。如果你要复现建议先从最小Harness跑通一个任务开始别一上来就追求40亿token的规模。规模是结果不是目标。我自己在类似项目里踩过的最大的坑是过早追求自动化。一开始就想让Agent全自动跑结果错误累积、上下文污染、成本失控最后不得不推倒重来。后来改成半自动——Agent生成人审查逐步把稳定的环节自动化——反而走得更快。这个教训我觉得比任何技术细节都值钱。