从上下文工程到 Harness Engineering

如果无法正常显示，请先停止浏览器的去广告插件。

2. 从上下文工程到 Harness Engineering 构建高效的 Agent 执行环境：上下文工程 & 工具链设计

3. About me 周晓 / zhoushaw 字节 Web Infra 成员 AI Coding / Harness Engineering Midscene.js / Module Federation 2.0

5. 为什么 AI 出现后，研发普遍觉得更累了？真正的瓶颈：编码提速并未打破系统性天花板，非编码工作量正在随着代码生成量的增加而指数级爆发。软件开发工作时间分配非编码工作占比高达 70% 30% 编码 (AI赋能环节) 40% 验证 / CI / 测试局部最优陷阱 20% 部署 / 发布 / 灰度 10% 排障 / 沟通 / Code Review 破局：Harness Engineering AI 目前只在开发环境里极速写代码，但并没有帮你解决测试、必须从"单行代码补全"跃升至让 Agent 执行跨越整个生命周验证和沟通等环节。价值上限被后续流程死死锁住。期的长时间闭环任务 (Long-term Tasks)。痛点爆发：代码生成得越快越多，你用于手动测试、验证排核心路径：通过专属工具链集成，解决上下文爆炸问题，让障和 Code Review 的工作量正在呈指数级上升。AI 接管测试与排障，彻底打破 70% 的非编码流程枷锁。

6. 范式转移：什么是 Harness Engineering？工程师角色转变Harness EngineeringAgent 可读性从“编写代码”转向“设计环境、明确意图”构建 Agent 专属工具链，实现受控执行北极星指标：代码库重塑为模型能“ 读懂”的环境 “不要只把大模型看作‘大脑’，必须为它打造专属的‘工作室’。”

7. PART 01 唯快不破 — 从 Transformer 原理到 Prompt Cache Transformer 自回归、KV Cache、Prompt Cache、ReAct 循环、上下文布局

8. Claude Code / Codex 在遵循哪些“物理限制”？你觉得产品“慢、笨、会幻觉”？其实每个行为都是一道工程选择题 SLOW / 慢DUMB / 笨HALLUCINATION / 幻觉并非产品 Bug并非模型能力弱并非故意欺骗自回归逐 Token 生成是物理铁律；上下文越长，Prefill 就越久，这是算力的基本开销。上下文塞得越多，注意力被稀释得越严重。在万行代码中，关键逻辑往往被掩埋。当上下文中缺少事实锚点，模型为维持概率连贯，只能进行“合理的猜测”。产品设计并非在对抗限制，而是在做 Harness Engineering：顺应物理限制，在约束中求解最优体验。 1.2–1.3 KV Cache & Prompt Cache1.4 ReAct 循环机制上下文布局与压缩解释了为什么 System Prompt 要保持极高稳定性 — — 只有稳定，缓存才能命中，响应才能加速解释了为什么 Agent 要"想→做→看"反复迭代 —— 利用外部反馈来对冲模型的概率波动解释了为什么会自动 Compact —— 在有限的注意力槽位内，塞入信噪比最高的信息理解这些约束 = 理解 Harness Engineering 的底层逻辑 NEXT: 以 Transformer 第一个 Token 为起点，逐层拆解 →

9. 1.1 为什么是一个 token 一个 token 吐？自回归分解PyTorch 朴素推理（无 KV Cache） LLM 本质是"下一个 token 预测器"for step in range(max_tokens): # 朴素实现：每步全量前向 out = model(input_ids) next = argmax(out.logits) # 拼接 → 序列越来越长 input_ids = cat([input_ids, next]) P(x1,...,xT) = ∏ P(xt | x1,...,xt-1) ▸ 流式渲染暴露了模型自回归的物理现实 ▸ 无 KV Cache 时，吐第 100 词 → 前 99 词全部重算 ▸ Coding Agent 塞入几万字 → Prefill 阶段极其昂贵结论：上下文越长 → Prefill 越重 → 首 Token 延迟越大 — 这就是 KV Cache 的动机

10. 1.2 KV Cache：为什么"追加"便宜？ Attention 的物理本质： Q：问题 | K：标签 | V：细节标准 Attention 公式 Attention(Q,K,V) = softmax(QKT/√d) V 长任务黄金定律：追加 (Append) 极度便宜老 KV 复用，新 token 只算一次中间修改极其昂贵推理两阶段：Prefill（全量算 KV）➤ Decode（复用 KV）修改点之后的所有 Cache 全部作废重算核心结论：一切上下文工程，本质上都是为了“尽量不破坏前缀” 追加 = 复用 KV，O(新 token) | 修改 = 从修改点起重算 KV，O(N)

11.

12. 1.4 ReAct：Agent 的操作系统不是"一问一答"，而是 Thought → Action → Observation 的循环 Thought (思考) 一个真实的 ReAct 过程 User: 给 user-service 加 /healthz 接口 "需要查看 index.ts 的错误信息" 模型在上下文里"自言自语" Reason: 先找路由注册方式…… Act: search / read_file Action (行动) Observe: 返回文件内容 Reason: 原来是 FastAPI，该这样写…… read_file() / write_file() / bash() 调用工具，影响物理世界 Act: write_file + bash pytest Observation (观察) 返回文件内容、终端输出、报错信息结果追加到上下文 → 触发下一轮 Turn 1 Turn 5 Turn 20 上下文随迭代爆炸 → 第一原则：保护前缀稳定性 → 接下来：怎么做？

13. 思考一下你的 Agent 工具，平均每轮往上下文里塞多少 token？如果超过 5,000 token，你的 Cache 命中率可能已经崩了接下来：从原理走向实战 — 上下文工程的具体策略

14. PART 02 上下文工程实战 Prompt 布局、缓存优化与上下文膨胀的应对策略

15. 一次 Agent 任务背后：Prompt 的五层结构不是"把你的话丢给模型"，而是构造了一整坨 Prompt 1 System 模型服务商系统提示 + Agent 身份定义 + 工具能力声明 2 AGENTS.md技术栈、代码风格、安全边界、团队工作流 3 项目快照当前工作目录、选中文本、项目结构 4 会话历史对话记录 + 工具调用与返回 + snapshot / 总结 5 工具定义MCP 工具清单：名称 + 说明 + JSON Schema 核心结论：上下文不是"越多越好"，而是要"把最重要的东西放到最该放的位置" 所有这些一起拼成 Prompt → 位置和占比决定了模型的注意力分配

16.

17. 抵抗膨胀：将上下文外包给"知识记录系统" 不在代码仓库里的隐形知识，对 Agent 来说就是不存在的 ReAct 长对话主动 Compaction 膨胀的中间过程将当前分析结果试错日志、调试输出、工具调用结果...浓缩成结构化快照清空对话历史结构化文件 docs/state/migration.md 下次 read_file 即可恢复隐形知识的陷阱业务决策如果只在聊天记录里，对 Agent 就是不存在的。正确姿势：执行完一个阶段 → 将探讨结论写成 Markdown 快照 → 清空对话历史 → 下次 read_file 恢复核心结论：记忆外包给文件系统 — 但上下文治理只是一半，工具设计同样关键 →

18. PART 01-02 CHECKPOINT 到这里，你需要带走的 3 条核心结论 ❶ 自回归 → 上下文越长，重复计算越多每生成一个 token 都要重算所有历史 — 这是模型的物理现实，无法绕过 ❷ KV Cache → 追加便宜，修改昂贵保护前缀稳定性 = 复用缓存 = 省钱 + 提速，中间插入 = 缓存作废 ❸ 上下文是最贵的资源 — 治理它，而不是堆砌它三段式布局 + 主动 Compaction + 记忆外包给文件系统一句话：所有后续策略的根基 — 保护前缀稳定性

19. PART 03 工具设计与 Agent 可读性 Agent 可读性、好工具标准、MCP / Skill / Sub Agent、闭环校验

20. 核心范式转移：提升 Agent 可读性从"对人友好"转向"对 Agent 可读" — 环境降维成结构化语义过去的 Infra 陷阱酷炫 GUI / 海量终端日志直接把给人类看的界面、十几页火焰图扔给 Agent → Token 瞬间爆炸，上下文被垃圾填满面向鼠标点击的交互 Agent 无法操作 GUI 按钮和拖拽界面 → 人机交互范式完全不适用范式转移：一切为了 Agent 可读 → → 视觉冗余图表图形化仪表盘对 Agent 完全不可读 → 缺乏语义，无法提取结构化信息 → 结构化语义 (JSON / API) 精确、唯一的术语定义 Agent 直接解析，零歧义面向自然语言指令用文字描述操作意图，取代鼠标点击 Agent 原生理解，自主执行高信噪比的诊断摘要极致精简，层级分明的上下文导航秒级反馈 + 100% 稳定结构化输出 Harness Engineering 的核心：给模型好的上下文、好的工具、可读的环境 — 这就是“为 Agent 打造专属工作室”的全部

21. 好工具的标准 Agent 的工具质量直接决定 Harness 工程的成败贴近物理上限结构化输出痛觉反馈秒级冷启动与响应，防止 Agent 注意力涣散。禁止 PDF/网页截图。必须输出 JSON/Markdown。错误信息是闭环的起点，需精确到行号与类型。核心原则：工具不是给人用的 UI — 是给 Agent 用的 API。快、准、结构化，缺一不可。

22. 大脑分工：MCP、Skill 与 Sub Agent 当任务足够复杂，光靠原子工具是不够的 — 我们需要给大脑分工 MCP 原子动作 · 常驻上下文 Skill 可见的 SOP · 按需激活 Sub Agent 黑盒外包 · 并行大脑一次性挂在上下文里，提供基础的"原子动作" GitHub · Slack · Database · K8s · Internal APIs 把成熟打法（CI Debug、审查清单）固化成可执行文件夹，在主会话里按步骤跑 skill.md + run.sh + examples/ 完全独立的会话，上下文隔离 — 适合超长任务拆解例：Explore 模式 — 起 3 个并行子 Agent 探索不同微服务，最后汇总 Summary 核心思路：用架构隔离，对抗长任务的熵增 — 原子动作 → 固化打法 → 并行外包

23. 闭环校验与编辑：机器人的 LSP 自动化的 "Lint → Fix → Verify" 闭环 1. 静态分析2. 增量重构3. 动态验证 AST 检测Agent 自动应用运行测试用例提前发现冲突最小差异真实反馈为什么需要闭环？ Agent 每一次编辑都可能引入新错误。没有 Lint → Fix → Test 的自动闭环，Agent 就会在错误上堆叠错误，直到上下文爆炸。核心结论：LSP 不是可选项 — 它是 Agent 编码质量的最低保障线。

24. PART 04 多智能体协作与受控执行 Agents Team、人机协作、Spec/Plan — 从单兵到团队作战

25. Spec Kit 与 Plan 模式：谋定而后动先写规格，再写代码 — 减少无目的的试错循环 Spec Kit (规格说明书) Plan 模式 (执行计划) 定义"做成什么样"：定义"怎么做"： • 输入/输出 Schema• 多步任务拆解 • 副作用边界 (Side Effects)• 关键检查点 (Checkpoints) • 验证通过标准 (Success Criteria)• 失败回退策略 (Rollback) 核心结论：Spec 答 What，Plan 答 How — 不确定时在第 1 轮就向人求助，而非猜错后浪费 20 轮

26. 人机协作：Agent 何时该自主，何时该求助 Harness 不是让 Agent 完全取代人 — 而是让人机各司其职受控闭环 Agent 自主执行向人求助 (AskUser) • Spec 明确 + 有闭环验证• 意图模糊 / 多条路径 • 工具能力覆盖完整 • 失败可自动回退• 环境信息不足 • 涉及不可逆操作 → 放手让 Agent 跑→ 第 1 轮就问，不猜 Harness 的边界：好的工具链让 Agent 知道自己能做什么、不能做什么 — 这本身就是 Harness

27. 突破智能上限：Agents Team 与结构化通信单 Agent 天花板 = 模型基础智商 → 用多智能体协作来突破单 Agent Agents Team 膨胀的上下文窗口 Orchestrator syst em_prompt + tools + history... ↓ react _turn 1...5...10...20... 分发子任务 tool_results + debug + errors... more accumulated noise...Worker AWorker BWorker C even_more_garbage_context...独立上下文独立上下文独立上下文干净沙盒干净沙盒干净沙盒 Agent ↑ 返回摘要仅通过结构化摘要通信上下文膨胀 → 注意力稀释物理隔离噪音 · 独立上下文智商被锁死在模型基础水平交叉验证 · 突破智能上限核心理念：用"结构化通信"代替"无脑堆砌"— Agent 在独立沙盒工作，只交换摘要

28. 回想一下上次让 Agent 跑一个超过 20 轮的任务，它在第几轮开始"变笨"？接下来看看我们的工程化解法 — 如何让 Agent 稳定跑完全程

29. PART 05 释放人类注意力 & 构建 AI native 工具 AI 降维 · 全链路流水线标准化基建

30. 基于 Agent 的 CLI 自迭代端到端闭环需求：将 CLI 的 skill 列表和 command 列表合并为统一的 / 触发下拉菜单（对齐 Claude Code 交互）。

31. 从 Review 代码到 Review 交互和测试

32. 端到端闭环交付，Aiden CLI 需求：将 CLI 的 skill 列表和 command 列表合并为统一的 / 触发下拉菜单（对齐 Claude Code 交互）。

33.

34.

35.