1. 先搞清楚这个标题到底在说什么一个人、九个月、20 万行代码、每个月烧掉 40 亿 token——这串数字摆在一起第一反应是夸张第二反应是好奇一个人怎么可能在九个月内写出 20 万行代码每个月 40 亿 token 又是什么概念先算一笔账。40 亿 token 听起来很吓人但拆开来看如果按主流大模型 API 的计费方式输入和输出 token 是分开算的。假设平均每次请求消耗 8000 输入 token 2000 输出 token那 40 亿 token 大约对应 40 万次请求。九个月按 270 天算每天约 1480 次请求每小时约 62 次。对于一个重度依赖 AI 辅助编码的开发者来说这个频率并不离谱——尤其是当你把 Agent 的自动补全、代码审查、文档生成、测试用例生成全部算进去的时候。真正值得聊的不是这些数字本身而是**Harness 架构应用**这个核心概念。Harness 在这里不是指某个具体的 CI/CD 工具而是一种架构模式用一层挽具把大模型的原始能力约束、编排、引导成可预测、可复用、可测试的工程化输出。你可以把它理解成给一匹野马套上缰绳和马鞍——马还是那匹马但你能骑着它去你想去的地方而不是被它拖着乱跑。这个项目本质上是一个个人开发者用 AI Agent 作为主要生产力工具构建一个 Harness 架构应用的完整实践记录。它涉及的核心技术点包括Agent 编排、Markdown 作为中间表示层、Claude Code 作为编码 Agent、Obsidian 作为知识管理底座以及 DeepSeek Harness 这类工具链的集成。适合谁看适合那些已经在用 AI 辅助编码、但感觉效率提升不明显或者代码越写越乱的开发者也适合想了解 Agent 架构落地细节的技术管理者。2. 为什么是 Harness 架构而不是直接让 Agent 自由发挥2.1 裸用 Agent 的三个致命问题我刚开始用 Claude Code 的时候跟大多数人一样打开终端输入需求等它生成代码复制粘贴跑测试报错再让它修。前两周感觉很爽第三周开始不对劲了。第一个问题是上下文漂移。Agent 在多轮对话中会逐渐忘记最初的架构约束。你第一轮告诉它所有数据访问必须通过 Repository 层到第十轮它可能直接在 Controller 里写 SQL 查询了。这不是模型笨而是注意力机制在长上下文中的自然衰减。第二个问题是输出不可复现。同样的提示词今天生成的代码结构和明天生成的可能完全不同。对于个人项目还好但一旦涉及多人协作或者需要长期维护这种不确定性就是灾难。第三个问题是知识碎片化。Agent 生成的代码、你手动改的代码、Agent 写的文档、你记的笔记散落在不同的文件和工具里。三个月后回头看你自己都说不清某个设计决策是怎么来的。Harness 架构的核心思路就是解决这三个问题用结构化的中间表示Markdown固定上下文用模板化的 Agent 调用保证输出一致性用统一的知识库Obsidian沉淀所有决策记录。2.2 Harness 和 Agent 的本质区别很多人把 Harness 和 Agent 混为一谈其实它们的关系更像是马鞍和马。Agent 是执行者负责理解意图、生成内容、调用工具Harness 是约束层负责定义输入输出的格式、管理上下文窗口、编排多个 Agent 的协作流程、验证输出是否符合预期。举个具体的例子。你让 Agent帮我写一个用户登录接口。裸用 Agent 的话它可能给你生成一个包含路由、控制器、服务层、数据访问层的完整代码块也可能只给你一个函数签名。但如果你有一个 Harness它会先检查你的项目里有没有现成的认证模块、有没有统一的响应格式、有没有代码风格配置然后把这些约束作为上下文注入给 Agent最后按照预定义的模板输出代码文件、测试文件、API 文档三件套。提示Harness 架构的落地成本主要不在技术选型而在于你愿不愿意花时间把隐性知识显性化。如果你连自己项目的代码规范都说不清楚那 Harness 也帮不了你。2.3 20 万行代码是怎么来的回到那个数字。20 万行代码九个月一个人。如果纯手写按每天有效编码 4 小时、每小时 50 行有效代码算需要 1000 天。所以这 20 万行里绝大部分是 Agent 生成的人的角色是架构设计、提示词工程、代码审查和集成测试。具体拆解一下这 20 万行的构成大约 40% 是业务逻辑代码25% 是测试代码20% 是配置和基础设施代码15% 是文档和注释。Agent 最擅长的是测试代码和配置代码这两块基本可以做到 90% 自动生成。业务逻辑代码的自动生成比例大约在 60% 左右剩下的需要人工调整。文档和注释的自动生成比例最高接近 95%但需要人工审核准确性。这个比例分布很关键。它告诉你不要指望 Agent 帮你写核心算法但可以让它帮你写所有有固定模式的代码。Harness 架构的价值就在于它能把更多代码变成有固定模式的。3. Markdown 作为中间表示层的设计细节3.1 为什么选 Markdown 而不是 JSON 或 YAMLJSON 和 YAML 是机器友好的但人读起来累。Markdown 是人友好的但机器解析起来需要额外处理。在 Harness 架构里中间表示层需要同时满足两个条件人能快速理解和修改机器能稳定解析和生成。Markdown 的优势在于它的容错性。你少写一个闭合标签JSON 直接报错Markdown 只是渲染效果差一点。你多写一个空行YAML 可能解析出 nullMarkdown 完全不受影响。在 Agent 生成内容的场景下容错性比严格性更重要——因为 Agent 的输出本身就有不确定性。另一个关键因素是Obsidian 的原生支持。Obsidian 的底层就是 Markdown 文件它的双链语法[[文件名]]、标签系统#tag、元数据---都是 Markdown 的超集。这意味着你的 Harness 中间表示可以直接在 Obsidian 里编辑、预览、建立关联不需要额外的转换层。3.2 Markdown 换行和语法在 Harness 中的特殊处理Markdown 的换行是个经典坑。标准 Markdown 里单个换行符不会产生新段落需要两个空格加换行或者空行。但在 Harness 的提示词模板里换行符是重要的分隔标记。我的处理方式是在 Harness 层统一把单换行转换为双换行把连续三个以上换行压缩为两个。这样 Agent 生成的 Markdown 无论换行习惯如何最终输出都是规范的。具体实现可以用一个简单的预处理函数import re def normalize_markdown(text): # 将单换行转为双换行保留代码块内的换行 lines text.split(\n) result [] in_code_block False for i, line in enumerate(lines): if line.strip().startswith(): in_code_block not in_code_block if not in_code_block and line.strip() : result.append() elif not in_code_block and i 0 and lines[i-1].strip() ! and line.strip() ! : result.append() result.append(line) else: result.append(line) # 压缩连续空行 text \n.join(result) text re.sub(r\n{3,}, \n\n, text) return textMarkdown 表格在 Harness 里也有特殊处理。Agent 生成的表格经常列数对不齐或者分隔行|---|---|的横线数量不对。我的做法是在 Harness 的输出验证层加一个表格规范化步骤自动补齐缺失的列和对齐分隔行。3.3 GitHub Markdown Callout 的妙用GitHub 的 Callout 语法 [!NOTE]、 [!WARNING]、 [!TIP]在 Harness 架构里是一个被低估的工具。它不仅仅是渲染效果更是一种语义标记。我在 Harness 里定义了这样一套约定Agent 生成的代码中所有需要人工确认的地方用 [!WARNING]标记所有可以自动化的地方用 [!TIP]标记所有外部依赖用 [!NOTE]标记。这样在后续的代码审查环节我可以直接搜索这些标记来定位需要关注的部分而不是逐行阅读。 [!WARNING] 这段逻辑涉及金额计算Agent 生成后必须人工验证边界条件。 [!TIP] 这个工具函数已经在 utils/format.py 中存在可以直接复用。这套标记系统配合 Obsidian 的搜索功能效率提升非常明显。你可以在 Obsidian 里搜索[!WARNING]标签一次性看到所有需要人工介入的代码位置。4. Agent 编排从单 Agent 到多 Agent 协作4.1 Claude Code 在 Harness 中的角色定位Claude Code 在这个项目里不是写代码的工具而是Harness 的执行引擎。它的核心能力是理解自然语言指令、读写文件、执行命令、根据反馈迭代。Harness 要做的是把这些能力编排成可重复的工作流。我配置 Claude Code 的方式可能和大多数人不一样。我没有把它当成一个交互式的聊天窗口而是把它当成一个批处理工具。具体来说我写了一个 shell 脚本接收一个 Markdown 格式的任务描述文件调用 Claude Code 执行然后把结果输出到指定的目录。#!/bin/bash # harness-run.sh TASK_FILE$1 OUTPUT_DIR$2 # 提取任务描述 TASK_DESC$(cat $TASK_FILE) # 调用 Claude Code注入 Harness 上下文 claude-code --prompt $(cat harness-context.md) 任务描述 $TASK_DESC 请按照 harness-output-template.md 的格式输出结果。 \ --output-dir $OUTPUT_DIR \ --max-tokens 8000这个脚本的关键在于harness-context.md和harness-output-template.md这两个文件。前者定义了项目的架构约束、代码规范、可用工具列表后者定义了输出的文件结构、命名规则、必须包含的章节。每次调用 Agent 时这两个文件都会被注入到提示词里保证输出的一致性。4.2 多 Agent 分工的具体实现单 Agent 处理复杂任务时容易顾此失彼。我的做法是把开发流程拆成四个阶段每个阶段用一个专门的 Agent 处理Agent 角色职责输入输出架构 Agent分析需求设计模块划分和接口需求文档架构设计 Markdown编码 Agent根据架构设计生成代码架构设计 代码规范代码文件 单元测试审查 Agent检查代码质量、安全、性能代码文件 审查规则审查报告 Markdown文档 Agent生成 API 文档和用户手册代码文件 架构设计文档 Markdown这四个 Agent 之间通过 Markdown 文件传递信息而不是通过对话历史。这样做的好处是每个 Agent 的上下文都是干净的不会被其他阶段的无关信息干扰。架构 Agent 不需要知道编码 Agent 用了什么变量名编码 Agent 也不需要知道审查 Agent 发现了什么问题。编排逻辑用一个简单的状态机实现class HarnessPipeline: def __init__(self): self.stages [architect, coder, reviewer, documenter] self.state {} def run(self, requirement): self.state[requirement] requirement for stage in self.stages: agent self.load_agent(stage) context self.build_context(stage) result agent.execute(context) self.state[stage] result if stage reviewer and result.has_critical_issues(): # 审查不通过回退到编码阶段 self.state[coder] None return self.run_from(coder) return self.state4.3 如何扛住高并发下的 Agent 调用每个月 40 亿 token 意味着大量的并发调用。这里的并发不是指同时处理多个用户请求而是指同时运行多个 Agent 任务。比如你让编码 Agent 生成 10 个模块的代码这 10 个任务可以并行执行。但并发带来两个问题速率限制和成本控制。主流 API 都有 RPM每分钟请求数和 TPM每分钟 token 数限制。我的做法是在 Harness 层加一个令牌桶限流器import time from collections import deque class RateLimiter: def __init__(self, max_rpm, max_tpm): self.max_rpm max_rpm self.max_tpm max_tpm self.request_times deque() self.token_counts deque() def acquire(self, estimated_tokens): now time.time() # 清理一分钟前的记录 while self.request_times and now - self.request_times[0] 60: self.request_times.popleft() self.token_counts.popleft() # 检查是否超限 while len(self.request_times) self.max_rpm or sum(self.token_counts) estimated_tokens self.max_tpm: time.sleep(1) now time.time() while self.request_times and now - self.request_times[0] 60: self.request_times.popleft() self.token_counts.popleft() self.request_times.append(now) self.token_counts.append(estimated_tokens)成本控制方面我给每个 Agent 任务设置了 token 预算。编码 Agent 的单任务预算上限是 50 万 token审查 Agent 是 20 万 token文档 Agent 是 10 万 token。超过预算的任务会被自动终止并标记为需要人工介入。注意不要为了省钱而过度压缩上下文。我试过把架构约束从 5000 token 压缩到 1000 token结果 Agent 生成的代码质量明显下降返工成本远高于省下的 token 费用。5. Obsidian 作为知识底座的集成方案5.1 为什么是 Obsidian 而不是 Notion 或语雀Obsidian 的核心优势是本地文件 纯文本 双向链接。这三个特性在 Harness 架构里都是刚需。本地文件意味着你的知识库不依赖网络Agent 可以直接读写文件系统不需要通过 API 调用外部服务。纯文本意味着版本控制友好你可以用 Git 管理整个知识库每次 Agent 生成的内容都有完整的变更记录。双向链接意味着你可以从代码文件反向链接到设计文档从设计文档反向链接到需求描述形成一张可追溯的知识网络。Notion 和语雀的问题在于它们是封闭的云服务。你的数据在别人的服务器上Agent 要访问需要经过 API 鉴权、速率限制、格式转换。对于个人项目来说这些额外复杂度不值得。5.2 如何将 Zotero 笔记导入 Obsidian 并接入 HarnessZotero 是文献管理工具但它的笔记功能也可以用来管理技术文档。将 Zotero 笔记导入 Obsidian 的流程如下在 Zotero 中选中要导出的笔记右键选择导出笔记导出格式选择Markdown 附件将导出的文件夹放入 Obsidian 库的references/目录在 Obsidian 中安装Zotero Integration插件配置 Zotero 数据库路径使用插件的导入笔记功能自动建立双向链接导入后的笔记会自动带上 Zotero 的元数据作者、年份、标签这些元数据在 Harness 里可以作为引用来源注入给 Agent。比如你让 Agent 写一段关于分布式共识算法的代码Harness 会自动从references/目录里找到相关的论文笔记把摘要和关键结论作为上下文提供给 Agent。5.3 Obsidian 模板与 Harness 输出格式的对齐Obsidian 的模板功能Templater 插件可以和 Harness 的输出格式对齐。我定义了一套模板Agent 生成的内容直接套用这些模板保证格式统一。比如代码审查报告的模板--- type: code-review date: {{date}} module: {{module_name}} agent: reviewer status: {{status}} --- # 代码审查报告{{module_name}} ## 审查范围 {{review_scope}} ## 发现的问题 {{#each issues}} ### {{this.severity}}: {{this.title}} - 位置{{this.location}} - 描述{{this.description}} - 建议{{this.suggestion}} {{/each}} ## 总体评价 {{overall_assessment}}Agent 只需要输出结构化的数据Harness 负责套用模板生成最终的 Markdown 文件。这样既保证了格式一致性又降低了 Agent 的输出复杂度。6. 九个月踩过的坑和对应的解决方案6.1 上下文窗口溢出的处理策略Claude Code 的上下文窗口是有限的。当项目变大时Agent 需要读取的文件越来越多很容易超出窗口限制。我试过三种方案第一种是滑动窗口只保留最近 N 轮对话。问题是 Agent 会忘记早期的架构决策。第二种是摘要压缩让 Agent 自己总结之前的对话。问题是摘要本身会丢失细节。第三种是分层上下文把上下文分成永久层架构约束、代码规范和临时层当前任务相关文件永久层始终保留临时层按需加载。最终我采用的是第三种方案的变体永久层 任务层 引用层。永久层大约 3000 token包含项目结构、核心接口定义、代码风格规则。任务层大约 5000 token包含当前任务直接相关的文件内容。引用层按需加载只有当 Agent 明确需要某个文件时才注入。6.2 Agent 生成代码的幻觉依赖问题Agent 有时会引用不存在的库或函数。比如它生成from utils.helpers import format_date但你的项目里根本没有utils/helpers.py。这种幻觉依赖在大型项目里很常见。我的解决方案是在 Harness 的审查阶段加一个依赖验证器。它扫描 Agent 生成的所有 import 语句检查对应的模块是否存在。如果不存在要么自动创建桩代码要么标记为需要人工处理。import ast import os def validate_imports(file_path, project_root): with open(file_path, r) as f: tree ast.parse(f.read()) missing [] for node in ast.walk(tree): if isinstance(node, ast.Import): for alias in node.names: module_path alias.name.replace(., /) .py if not os.path.exists(os.path.join(project_root, module_path)): missing.append(alias.name) elif isinstance(node, ast.ImportFrom): if node.module: module_path node.module.replace(., /) .py if not os.path.exists(os.path.join(project_root, module_path)): missing.append(node.module) return missing6.3 Token 成本失控的预警机制40 亿 token 听起来多但如果没有监控很容易在不知不觉中翻倍。我设置了三层预警第一层是日预算预警。每天凌晨统计前一天的 token 消耗如果超过日均值的 150%发送提醒。第二层是单任务预警。任何单个 Agent 任务的 token 消耗超过预算的 80% 时暂停任务并请求确认。第三层是异常模式预警。如果某个 Agent 在短时间内反复调用同一个工具说明它可能陷入了循环自动终止并记录日志。这套机制帮我省下了至少 30% 的无效消耗。最典型的一次是编码 Agent 在生成一个复杂正则表达式时陷入了生成-测试-失败-重新生成的循环连续调用了 47 次才被预警机制终止。如果没有预警这个任务可能会烧掉上百万 token。6.4 Harness 插件加载失败的排查链路Harness 架构依赖多个插件Obsidian 插件、Claude Code 扩展、自定义脚本。插件加载失败是最常见的问题之一。我的排查链路是这样的第一步检查插件目录结构。Harness 的插件必须放在plugins/目录下每个插件一个子目录包含manifest.json和入口文件。目录结构不对是最常见的原因。第二步检查 manifest.json 的字段。id必须唯一version必须符合语义化版本规范main必须指向存在的文件。我遇到过因为main字段写成了main.js但实际文件是index.js导致加载失败的情况。第三步检查依赖冲突。两个插件依赖同一个库的不同版本时后加载的会覆盖先加载的。解决方案是在 manifest 里声明依赖版本范围Harness 在加载时做版本仲裁。第四步查看日志。Harness 的日志默认输出到logs/harness.log包含插件加载的详细过程。如果日志里出现failed to load plugins通常会在下一行说明具体原因。7. 从 20 万行代码里提炼出的可复用经验7.1 提示词模板的版本管理提示词是 Harness 架构的核心资产必须像代码一样管理。我的做法是把所有提示词模板放在prompts/目录下用 Git 管理每次修改都有 commit message 说明改了什么、为什么改。提示词模板的命名规则是{agent角色}-{任务类型}-v{版本号}.md。比如coder-generate-api-v3.md表示编码 Agent 生成 API 代码的第三版提示词。版本号只在做不兼容修改时递增小的调整直接修改当前版本。每个提示词模板的头部包含元数据--- agent: coder task: generate-api version: 3 last_updated: 2025-01-15 changelog: - v3: 增加对 GraphQL 接口的支持 - v2: 优化了错误处理的生成逻辑 - v1: 初始版本 ---这样做的好处是当 Agent 输出质量下降时你可以快速定位是不是最近修改了提示词导致的也可以随时回滚到之前的版本。7.2 代码审查 Agent 的规则配置审查 Agent 的规则不是越多越好。我一开始配置了 50 多条规则结果审查报告长得没人看。后来精简到 12 条核心规则分为三类必须修复阻断合并安全漏洞、空指针风险、资源泄漏。建议修复不阻断但记录命名不规范、注释缺失、重复代码。仅供参考仅记录性能优化建议、设计模式建议。规则的精简原则是每条规则都必须能对应到一个具体的、可操作的修改动作。如果一条规则只能给出这段代码可以更好这种模糊建议那它就不应该出现在审查规则里。7.3 知识库的定期清理和重构Obsidian 知识库用久了会变得混乱。我的做法是每个月做一次知识库体检第一检查孤立笔记。没有任何双向链接的笔记要么删除要么建立链接。第二检查重复内容。同一个概念在多个笔记里重复解释时合并到一个主笔记其他笔记改为链接。第三检查过时内容。标记为#deprecated的笔记在三个月后自动归档到archive/目录。这个清理过程本身也可以部分自动化。我写了一个脚本扫描所有 Markdown 文件统计每个文件的入链数和出链数生成一份知识库健康报告。入链数为 0 的文件会被标记为待处理出链数超过 50 的文件会被标记为可能需要拆分。7.4 个人开发者的时间分配建议九个月下来我在各个环节的时间分配大致是这样的架构设计和提示词工程占 30%Agent 任务编排和监控占 20%代码审查和集成测试占 25%知识库维护占 15%纯手写代码占 10%。这个分配比例和传统开发完全不同。传统开发里写代码占 60% 以上。但在 Harness 架构下写代码变成了最不重要的事情重要的是设计好约束条件、编排好 Agent 工作流、审查好生成结果。如果你打算走这条路我的建议是前三个月不要追求产出把时间花在搭建 Harness 基础设施上。提示词模板、审查规则、知识库结构、自动化脚本这些东西前期投入越大后期效率越高。我前三个月只写了不到 2 万行代码但后面六个月写了 18 万行而且质量更稳定。提示不要试图一次性设计出完美的 Harness。我的 Harness 架构迭代了 7 个版本每个版本都是被实际问题逼出来的。先跑起来再优化。8. 这套架构的边界在哪里Harness 架构不是银弹。它最适合的场景是有明确模式、需要大量重复、对一致性要求高的代码生成。比如 CRUD 接口、数据转换脚本、测试用例、配置文件、文档。这些场景下Harness 能把 Agent 的产出从能用提升到可维护。但它不适合需要深度领域知识、涉及复杂算法、或者需求本身模糊的场景。我试过让 Agent 写一个自定义的调度算法生成的代码逻辑上说得通但性能比手写版本差了 3 倍。后来我改成自己写核心算法让 Agent 写周边的测试和文档效率反而更高。另一个边界是团队协作。Harness 架构目前是为个人开发者设计的如果多人共用一套 Harness提示词模板的修改、审查规则的调整、知识库的更新都需要协调机制。我还没有在团队场景下验证过这套架构所以不敢说它一定能 scale。最后这套架构对开发者的架构能力要求很高。你必须能清晰地定义模块边界、接口契约、代码规范否则 Harness 就是在放大混乱。Agent 不会帮你做架构决策它只会执行你定义的架构。如果你自己都说不清楚想要什么Agent 给你的只会是一堆看起来像代码的文本。我在实际使用中发现Harness 架构最大的价值不是省了多少时间而是强迫你把隐性知识显性化。当你必须把我觉得这段代码应该这样写变成这段代码必须遵循以下 5 条规则时你对项目的理解会深刻得多。这可能是九个月里比 20 万行代码更重要的收获。