从Harness架构到Token经济学的探索

从Harness架构到Token经济学的探索本文基于真实工程实践结合 Harness Engineering 领域的学术论文分享 AI 辅助编程的架构思考、工程落地与 Token 成本优化。01 Part 1 ·什么是 Harness它从哪儿来1.1 一个让所有人都很沮丧的问题你有没有遇到过这种情况——花半小时纠正 AI 的一个错误在 Prompt 里写清楚「不要这样做」第二天开了新会话AI 毫不犹豫地……又犯了同样的错换了个更贵的模型效果并没有你期望的那么好同一套代码别人的 AI 跑得很顺你接进来却各种翻车2025 年LangChain 发布了一组实验数据给同一个大语言模型换上一套更精巧的 Harness 架构它在 TerminalBench 2.0AI 编程能力权威榜单的通过率从 52.8% 直接拉升到 66.5%。底层模型权重一个字节没改单靠换壳排名从 30 名开外飙进前 5。这说明一件事很多时候卡住你的不是模型是模型外面那层「壳」。1.2 Harness 是什么Harness直译「挽具/线束」是包裹在大模型外面的那套代码它决定三件事模型能看到什么存什么、取什么、怎么呈现「The model contains the intelligence and the harness is the system that makes that intelligence useful.」 —— LangChain,The Anatomy of an Agent Harness, 2026.03一个公式Agent Model Harness1.3 Harness Engineering 的诞生史这个概念并不是一夜冒出来的而是被一个个真实 Bug 逼出来的。时间里程碑核心贡献2022ReAct 论文Yao et al., ICLR 2023提出 Thought-Action-Observation 循环推理与行动交错2023Reflexion 论文Shinn et al., NeurIPS 2023失败→反思报告→写入长期记忆实现「语言强化学习」2023Tree of ThoughtsYao et al., NeurIPS 2023推理从「链」扩展为「树」支持 BFS/DFS 多路径搜索回溯2025.11Anthropic: Effective Harnesses for Long-Running Agents双 Agent 架构 进度追踪文件解决长任务跨窗口失忆2026.02Mitchell Hashimoto 命名 Harness Engineering「每次发现 Agent 犯错就设计一个让它永远不再犯的方案」2026.02OpenAI: Harness EngineeringCodex3 人 5 月100 万行代码1500 PR零行人工编写代码2026.03LangChain: Anatomy of an Agent Harness将 Cybernetics控制论引入 Harness 框架2026.04Thoughtworksmartinfowler.com前馈控制 vs 反馈控制的系统化分类2026Meta-HarnessStanford/MIT/KRAFTONAI 自动搜索最优 Harness 代码同一模型性能差距最高 6 倍1.4 支撑 Harness 的核心数学与算法Harness 不是玄学它有扎实的理论基础。① 反馈控制论Cybernetics— Wiener, 1948Harness 的本质可以用控制论的「双环控制」来描述┌──────────────────────────────────────────────────────────────────┐数学基础负反馈系统的稳定性定理Nyquist, 1932——只要反馈增益 1系统趋于稳定。Hooks 的 deny 机制本质上是一个「增益截断器」。② ReAct 循环Thought-Action-Observation论文ReAct: Synergizing Reasoning and Acting in Language ModelsYao et al., ICLR 2023ReAct 的本质是一个推理与行动交替的循环Thought思考→ Action工具调用→ Observation观察结果→ Thought下一轮...每一次工具调用就是 ReAct 的一次迭代。而在项目的 Harness 中这个循环的三阶段分别被 Rules 和 Hooks 接管ReAct 阶段Harness 对应层.codebuddy 配置ThoughtAI 思考该怎么做Rules约束推理方向project-rules.md规定了技术栈和目录结构让 AI 不会想错方向ActionAI 决定调用工具PreToolUse Hooks拦截settings.json中配置了guard-commands.sh、protect-files.sh等在行动前检查安全性Observation工具返回结果PostToolUse Hooks反馈impact-analysis.sh检测到改了公共组件后自动 grep 全仓库引用方把影响面报告追加到 Observation以settings.json中的 Hook 配置为例// .codebuddy/settings.json — PreToolUse 阶段ReAct Harness 的关键洞察没有 Harness 的 ReAct 就像没有刹车的车——它能跑但不知道什么时候该停。Hooks 就是在 Action 阶段加的「刹车系统」。③ Reflexion — 反思记忆机制论文Reflexion: Language Agents with Verbal Reinforcement LearningShinn et al., NeurIPS 2023Reflexion 的核心是从失败中提取反思写入长期记忆供下次任务召回。 把流程从「AI 自动生成」变成了「工程师手工沉淀 自动注入」的工程化版本。Reflexion 在 项目中的三层实现第一层反思提取 →ai-coding-defense.md原始论文中AI 在任务失败后自动生成反思报告。我们从真实 Bug 中手工提炼规则!-- .codebuddy/rules/ai-coding-defense.mdalwaysApply --每一条都对应一个或一组真实踩过的坑。这就是 Reflexion 中「失败 → 反思」的人工版。第二层记忆持久化 →.codebuddy/memory/# .codebuddy/memory/ 目录结构memory 是 CodeBuddy 的内部记忆——单个 memory 文件本身不会被注入上下文、不消耗 token它只是 AI 跨会话持续学习的存储介质。archive-old-memories.sh负责把过期记录归档保持目录整洁。第三层记忆召回 →alwaysApply: trueSessionStartHook// .codebuddy/settings.json/compact会清空上下文导致 AI「失忆」。SessionStartHook 在 compact 触发后自动重新注入关键约定这是 Reflexion 中「episodic memory 持久化」的工程实现。对比总结Reflexion 论文项目工程化配置文件AI 自动生成反思报告工程师从 Bug 中提炼规则ai-coding-defense.md写入 episodic memory写入 memory/ 目录memory/*.md记忆老化未覆盖30 天自动归档archive-old-memories.sh下次任务自动召回alwaysApply SessionStart Hooksettings.jsonSessionStart④ 蒙特卡洛树搜索MCTS相关论文CodeTree (Li et al., 2023)、RethinkMCTS (Zhang et al., 2024)MCTS 的核心是「不一条路走到黑」生成多个候选方案 → 模拟评估 → 选择最优 → 必要时回溯。这在 Harness 工程中有三层映射。映射一dev 阶段2 MCTS 的「展开 选择」!-- .codebuddy/skills/项目-dev/SKILL.md 阶段2 节选 --这和 MCTS 的 Expansion Selection 完全对应不是直接写代码而是先出方案树评估后再选。映射二Rules 分级体系 MCTS 的「剪枝」!-- .codebuddy/rules/ 分级设计 --Rules 分级本质上是对 AI 搜索空间的剪枝——L1 永久剪掉明显错误的分支L2 按需剪掉不需要的路径。映射三suggest-compact 阈值调优 MCTS 的「模拟评估参数调优」// .codebuddy/hooks/suggest-compact.jsMCTS 中模拟次数rollout count决定了评估的准确度。suggest-compact的阈值从 50→35就是根据实际观察AI 在 35 次后质量明显下降对「何时该回溯compact」这个参数的调优。映射四impact-analysis.sh MCTS 的「节点评估函数」# .codebuddy/hooks/impact-analysis.sh一句话总结MCTS 教我们的不是「让 AI 更聪明」而是「给 AI 设计一个能试错的机制」——出方案 → 评估 → 选最优 → compact 后重来。⑤ 信息熵压缩无 Harness 的搜索空间02 Part 2 · .codebuddy 的 Harness 实践以下所有内容均来自.codebuddy/的真实配置不是理想状态是我们现在正在用的东西。2.1 架构全景.codebuddy/由四层能力组成┌─────────────────────────────────────────────────────────────────┐四层的职责分工层定位触发方式Token 消耗Commands流程入口/review-commit、/deploy-test用户手动执行极低轻量指令Skills领域能力包项目-dev、quick-iterate 等用户 Prompt 触发2K ~ 11KRules约束层始终激活 or 按需加载alwaysApply 或关键词匹配0 ~ 5.8KHooks自动化兜底AI 生命周期钩子工具调用自动触发0脚本执行2.2 Hooks 体系——反馈控制的工程实现Hooks 是 Harness「反馈控制」层最具体的落地也是我们花时间最多的部分。所有 Hook 都在 AI 生命周期的三个时机自动触发用户发出指令每个 Hook 解决的真实问题Hook解决什么问题对应的 AI 常见错误commit-quality.sh拦截裸 console、调试残留、非规范 commit msgAI 忘记清理调试代码就提交search-gate.js首次写入业务目录时提醒先搜索AI 重复造轮子不知道项目已有实现suggest-compact.js调用 35 次后建议/compact上下文膨胀导致 AI 质量下降impact-analysis.sh改公共组件时自动分析引用方AI 改了 BlockUploader 却不知道影响了多少页面stop-format-typecheck.js每次停止前批量格式化AI 改完不跑 lint留下格式问题config-protection.sh修改构建配置时询问AI 随意动 nuxt.config / eslint.configlarge-file-blocker.sh写入 400 行文件时提醒拆分AI 把所有逻辑堆在一个文件SessionStart compactcompact 后重新注入 7 条关键约定compact 后 AI「忘记」项目规范2.3 Rules 体系——前馈控制的工程实现Rules 对应控制论的「前馈控制」在 AI 行动之前就把约束注入到上下文中。分级体系避免把所有规则都 alwaysApply级别加载方式文件作用L1 核心always每次对话自动注入project-rules.md~3.5K tokens技术栈、目录、接口规范、8 条 DO NOTL1 核心always每次对话自动注入ai-coding-defense.md~1.5K tokens8 条编码红线历史 Bug 提炼L1 核心always每次对话自动注入plan-cleanup.mdc~800 tokensPlan 文件管理规范L2 场景按需关键词触发atomic-step-commit.mdc多步骤任务原子化提交工作流L2 场景按需写入业务目录时search-first.md编码前先搜索复用L2 场景按需调试/commit 场景debug-residue.md调试残留统一标记格式ai-coding-defense.md的 8 条编码红线全来自项目真实 Bug方案切换必须清理残留— 切换方案后全文搜索旧关键词防止两套方案并存通用控件保护— 改公共组件前先评估所有引用方影响面改动完整性— template/script/style 同步ref()vs 普通变量导出与引用同步场景全覆盖— 多端PC/Mobile、多调用方、多层守卫、tab 缓存避免策略反复— 先了解全部约束再定方案确定后不轻易切换异步操作所有路径必须有终态— 所有退出路径成功/失败/提前 return都必须重置 loadingVue 响应式纯净性—computed/Pinia getter 禁止副作用调试硬编码必须打标记并清理— 统一格式[xxx-debug]、__DEBUG_*__、TODO(debug-only):这 8 条规则的特殊之处不是「建议」是「工具会拦」。commit-quality.sh在 git commit 前自动扫描[xxx-debug]__DEBUG_*__TODO(debug-only)标记命中即拒绝提交。这就是 Reflexion 论文的工程版历史 Bug → 提炼反思 → 写入「记忆」→ 每次对话注入 → AI 不再犯同类错误。2.4 Skills 体系——领域知识封装最新disable-model-invocationSkills 是领域能力包把「怎么在项目里做一件事」的完整工作流封装起来。Skills 决策树用户说了什么Skill触发场景Token 消耗核心价值dev完整新功能、多文件联动、含设计稿~11K完整的 5 阶段工作流需求理解→设计→编码→验证→沉淀quick-iterate样式微调、文案修改、小交互变更~2K精准定位改动范围避免过度推断figma-to-codeFigma 链接设计稿还原~5KFigma API 项目组件规范的结合proto-syncProto 文件更新~3K类型生成→接口封装→调用方更新的固定流程git-commit-push提交代码~2Kconventional commits TAPD 关联dev 的 5 阶段工作流对应 ReAct 的 Plan→Execute→Verify 循环阶段 1需求理解 Plan 创建2.5 原子化提交工作流这是atomic-step-commit.mdc的核心设计也是我们避免「大 PR 噩梦」的关键。核心原则每步 最小可独立验证单元错误做法反模式三种 Review 模式根据任务风险选择模式场景AI 行为A. 自行 review低风险日常开发每步 lint/type-check 后自动 commit直接继续不打断用户B. 用户 review高风险改动每步完成后停下等用户确认确认才继续C. 传统模式改动关联性强统一修改所有步骤中间不 commit最后一起 review03 Part 3 · 模型选型与配额策略3.1 可用模型一览模型定位适合场景上下文窗口Claude复杂推理、大上下文、指令遵循最强多文件联动、架构设计、代码审查、新功能开发大100KDeepSeek代码理解强、性价比高、速度快日常开发主力单文件 bug fix、样式调整、proto 同步中等32KGLM轻量省 token、长时自主任务批量操作、文案文档、零碎问答中等32KHy3 preview内部新模型日常开发能力好DeepSeek 的替代方案可尝鲜日常开发中等3.2 按开发场景选型决策树任务有多复杂3.3 每日配额分配建议Claude~25% → 关键任务新功能开发、代码审查、架构设计、上线前 review3.4 注意事项小窗口模型 dev SkillSkill ~11K Rules ~15K ≈ 26K32K 窗口只剩 ~6K →建议拆分任务每次只执行 1 阶段或改用 Claude长文件 300 行建议用 Claude小窗口模型可能截断多轮对话超过 5 轮深度建议切 Claude小模型容易丢失早期上下文流程型 Skillproto-sync / git-commit-push已设disable-model-invocation: true可用 DeepSeek/GLM 执行不浪费大模型配额04 Part 4 · Token 经济学成本从哪里来、怎么省4.1 每次对话的固定开销从哪里来先搞清楚一次对话的「账单」每次对话基础开销分解项目优化后Transformer 的 KV Cache 机制理解成本的关键要真正理解 Token 成本必须先理解 KV Cache。什么是 KV CacheTransformer 的自注意力机制中每个 token 在处理时需要与序列中所有之前的 token 计算注意力。对于序列中第i个 token注意力计算为Attention(Q, K, V) softmax(QK^T / √d_k) · VKV Cache 在工程中的三层意义┌─────────────────────────────────────────────────────────────────┐Harness 调度层的 KV 管理职责智能体多轮工具调用、长代码库上下文极度依赖高性能 KV Cache。4.3 优化前后对比-36% 的从何而来指标优化前优化后降幅alwaysApply Rules~11K~5.8K-47%workspace_rules~12.5K~5K-60%每对话基础开销~23.5K~15K-36%项目-dev Skill~15K~11K-27%32K 窗口剩余空间~8.5K~17K100%对于流程型 Skillproto-sync、git-commit-push新增了disable-model-invocation: true标记——这类 Skill 是纯脚本执行流程加载后 AI 按步骤执行即可不需要再次调用大模型推理直接节省每步骤的推理 token。根因分析三类问题原始问题~23.5K 基础开销中有 ~8.5K 是「重复注入」或「不必要的 alwaysApply」Rules 分级最终状态级别文件alwaysApply每对话消耗L1 核心project-rules.md是~3.5KL1 核心ai-coding-defense.md是~1.5KL1 核心plan-cleanup.mdc是~800L2 场景atomic-step-commit.mdc否0按需L2 场景search-first.md否0按需L2 场景debug-residue.md否0按需L2 场景my-rule.mdc占位否04.4 四层配置成本控制策略层核心原则具体做法Rules只有「每次都必须遵守」的才 alwaysApply3 条 L1 核心 3 条 L2 按需Skills按场景精准选择流程型 Skill 设 disable-model-invocation简单改动用 quick-iterate~2K不用项目-dev~11KMemory只存核心结论30 天以上自动归档控制在 ~500 字以内archive-old-memories.sh定期执行Plans不自动注入0 固定消耗保留作参考不删除4.5 用户习惯对 Token 的影响低效做法高效做法Token 差距「帮我看看 Editor 有什么问题」Editor.vue:63 insertBlock 无 catch~3K「优化一下这个页面」Banner.vue 按钮圆角改 12px~5K「帮我加个功能」需求投票按钮 文件ActivityCard.vue useVoteStore~8K一次说 5 个需求每个需求独立对话~15K长对话一直跑35 次工具调用后/compact~5-10KToken 估算公式快速心算Token 数 ≈ 中文字符数 ÷ 1.5 英文字符数 ÷ 405 Part 5 · 马上就能用上的实战 Tips5.1 Prompt 模板速查场景推荐格式示例Bug 修复文件:行号 现象X 预期YEditor.vue:63 点击按钮没反应预期弹出侧栏样式调整文件 把 A 改成 B附截图Banner.vue 圆角改成 12px附设计稿截图新功能需求X 涉及文件A,B 注意Y需求加投票按钮 涉及ActivityCard.vue useVoteStore 注意SSR 兼容代码审查/review-commit 关注X/review-commit 关注类型安全和 SSR 兼容设计稿还原按 Figma 还原 {链接}按 Figma 还原 https://www.figma.com/design/ABC?node-id123proto 同步/proto-sync触发 proto-sync Skilldisable-model-invocation省配额提交代码/git-commit-push触发 git-commit-push Skill自动关联 TAPD5.2 对话管理策略推荐做法效果每个主题开新对话上下文干净AI 不混淆改完一个模块就/review-commit及时发现问题任务切换时执行/compact清理 5-10K 过期上下文SessionStart Hook 会自动重新注入项目约定用文件:行号精确指定位置减少 2-3 轮搜索流程型任务用对应 Skillproto-sync/git-commit-push 设了 disable-model-invocation省大模型配额避免做法问题一个对话混杂多个不相关任务上下文膨胀质量下降遇到报错在同一对话反复重试应贴报错 compact 精准重试说「帮我优化一下」但不给方向AI 会过度重构遇到 Hook 拦截就绕过Hook 拦截意味着有风险要读原因5.3 7 条黄金法则先搜后写— 动手写代码前先搜索项目中是否已有可复用实现search-gate.js会自动提醒精准定位— 用文件:行号而不是模糊描述单一职责— 每次对话只做一件事选对 Skill— 简单修改不加载 Skill流程型任务用 disable-model-invocation Skill及时 compact— 35 次工具调用后考虑/compactcompact 后 SessionStart Hook 自动重注入约定信任 Hooks— Hook 拦截意味着有风险不要绕过沉淀经验— 重要决策写 plan核心结论存 memory30天自动归档5.4 常见误区纠正误区 1「换更好的模型就能解决问题」LangChain 实验证明仅改 Harness 可提升 13 个百分点。先检查 Harness再换模型。误区 2「Rules 越多越好」Rules 有成本。只有「每次对话都必须遵守」的才值得 alwaysApply其余一律按需加载。误区 3「Hook 很烦直接--no-verify绕过」Hook 拦截说明有潜在风险。先读拦截原因修正后再提交。--no-verify在 Code Review 时可见。误区 4「Memory 越详细越好」Memory 每次都注入。只存核心结论定期运行archive-old-memories.sh归档老记录。误区 5「compact 之后项目规范就丢了」不会了。SessionStart Hook会在 compact 触发后自动重新注入 7 条关键约定。误区 6「所有 Skill 都需要 AI 推理」流程型 Skillproto-sync/git-commit-push设了disable-model-invocation: true加载后按固定步骤执行不触发额外推理可以用更省配额的模型跑。5.5 快速审计你自己的 .codebuddy# 查看所有 alwaysApply Rules 的大小判断标准alwaysApply Rules 总字符数控制在20K 以内约 10K tokens超出就要做一次规则降级或精简memory 文件超过30 天的运行archive-old-memories.sh归档流程型 Skill固定步骤执行建议设disable-model-invocation: true参考资料学术论文论文作者/机构发表核心贡献ReAct: Synergizing Reasoning and Acting in Language ModelsYao et al.ICLR 2023Thought-Action-Observation 循环Reflexion: Language Agents with Verbal Reinforcement LearningShinn et al.NeurIPS 2023语言形式反思记忆Tree of Thoughts: Deliberate Problem Solving with Large Language ModelsYao et al.NeurIPS 2023多路径推理树 BFS/DFSEfficient Memory Management for Large Language Model Serving with PagedAttentionKwon et al.SOSP 2023KV Cache 页式内存管理GQA: Training Generalized Multi-Query Transformer Models from Multi-Head CheckpointsAinslie et al.EMNLP 2023分组查询注意力KV 显存减少 70%Meta-Harness: End-to-End Optimization of Model HarnessesLee et al.arXiv 2026自动搜索最优 Harness 代码Dive into Claude Code: The Design Space of AI Agent SystemsVILA-LabarXiv 2026.041.6% AI 逻辑 98.4% 基础设施SWE-bench: Can Language Models Resolve Real-world Github Issues?—ICLR 2024AI 编程能力评测基准工程文章文章机构时间Effective Harnesses for Long-Running AgentsAnthropic2025.11My AI Adoption Journey命名 Harness EngineeringMitchell Hashimoto2026.02Harness Engineering: Leveraging Codex in an Agent-First WorldOpenAI2026.02The Anatomy of an Agent HarnessLangChain2026.03Harness Design for Long-Running Application DevelopmentAnthropic2026.03Harness Engineering for Coding Agent UsersThoughtworksmartinfowler.com2026.04项目文件.codebuddy/README.md— AI 编程辅助体系总览ai-infra-analysis.md— Token 消耗深度分析含优化前后对比rules/ai-coding-defense.md— 8 条编码红线rules/atomic-step-commit.mdc— 原子化提交工作流hooks/README.md— Hooks 体系完整文档scripts/archive-old-memories.sh— memory 归档脚本scripts/impact-analysis.sh— 影响面分析脚本