{"owner":"bojieli","repo":"ai-agent-book","hasSkills":true,"totalSkillsCount":36,"totalTokensCount":53800,"categories":["anthropic-skill","plugin-manifest"],"hasMcp":true,"mcpConfig":{"mcpServers":{"ai-agent-book":{"command":"npx","args":["-y","@modelcontextprotocol/server-ai-agent-book"]}}},"found":["skills/agent-state-bar/SKILL.md","skills/bad-case-to-dpo/SKILL.md","skills/coding-agent-harness/SKILL.md","chapter8/curly-quote-sft/SKILL.md","skills/context-compression/SKILL.md","skills/async-event-agent/SKILL.md","skills/agent-evaluation/SKILL.md","skills/agent-evolution/SKILL.md","skills/computer-use/SKILL.md","skills/context-engineering/SKILL.md","skills/eval-dataset-design/SKILL.md","skills/error-recovery/SKILL.md","skills/knowledge-org/SKILL.md","skills/kv-cache-design/SKILL.md","skills/loop-engineering/SKILL.md","skills/mcp-skill-hub/SKILL.md","skills/memory-system/SKILL.md","skills/multi-agent-design/SKILL.md","skills/post-training-strategy/SKILL.md","skills/rag-pipeline/SKILL.md","skills/reward-design/SKILL.md","skills/tool-design/SKILL.md","skills/tool-discovery/SKILL.md","chapter9/ai-style-skill/skill/SKILL.md","chapter10/multi-role-transfer/skills/coding/SKILL.md","chapter10/multi-role-transfer/skills/data_analysis/SKILL.md","chapter10/multi-role-transfer/skills/research/SKILL.md","chapter10/multi-role-transfer/skills/triage/SKILL.md","chapter10/multi-role-transfer/skills/writing/SKILL.md","chapter2/agent-skills-ppt/skills/pptx/SKILL.md","skills/README.md","chapter4/collaboration-tools/README.md","chapter4/execution-tools/README.md","chapter4/perception-tools/README.md","chapter9/self-evolving-tools/README.md","chapter2/agent-skills-ppt/skills/pptx/reference.md"],"skills":{"skills/agent-state-bar/SKILL.md":"---\nname: agent-state-bar\ndescription: Agent 陷入无限循环、数不清工具调用次数、遗忘 TODO 或目标偏离、长任务中思考 token 持续膨胀时使用——Agent 状态栏机制、作为 user 消息注入末尾的 KV Cache 理由、每轮替换与持久追加两种实现及成本模型、五种状态栏技术（时间戳、工具计数器、TODO、详细错误、系统状态）与维护铁律。\n---\n\n# Agent 状态栏：通过元信息增强 Agent 轨迹管理\n\n提示工程给的是静态指令，而 Agent 执行中还需要动态感知自身状态与任务进展。**Agent 状态栏**把任务进度、环境变化、工具调用计数等运行时状态整理成结构化摘要，由框架在上下文末尾持续注入。类比手机屏幕顶部始终显示时间、电量、信号——模型每次生成新回复时都能「瞥一眼」，据此做出更准确的决策。\n\n## 何时使用\n\n- Agent 反复执行相同工具调用、陷入无限循环（如超过次数限制仍在拨打）\n- 模型数不清「已经调用了几次」「还剩几项 TODO」，违反显式约束\n- 长任务中每次迭代的思考 token 量随上下文变长而持续增长\n- Agent 过分关注局部子任务，忘记用户原始诉求和核心约束\n- 小模型需要接近前沿模型的任务遵循能力\n- 设计状态消息的注入方式与更新策略\n\n## 核心原则\n\n- **状态栏不是对话主体内容**：它不属于用户消息、模型输出或工具结果，而是框架自动生成的状态摘要，注入在上下文**最末尾**，紧邻模型即将生成的新 token。\n- **理论基础是「上下文学习是检索而非推理」**：模型擅长查找，不擅长在一次前向传播中主动归纳统计。「已经打了几次电话」这类知识以原始记录形式分散在上下文里，模型每次决策都要花额外思考 token 扫描重算，效率极低且错误率高。\n- **本质是把隐式状态提炼为显式知识**：原始轨迹高度冗余，大量 token 中只含少量关键状态信息；状态栏以极低的额外 token 成本，呈现原本需要扫描数千 token 才能获得的信息。\n- **显式操纵注意力分配**：长上下文中早期目标和关键约束容易被后续工具结果淹没；结构化元信息放在末尾，空间上更接近新 token，获得更高注意力权重——一种「强制性的注意力引导」。\n- **实测收益**：提供提前算好的状态栏后，较小开源模型的准确率可以接近前沿大模型；每次迭代的思考 token 量、延迟和花费均降低约一个数量级。不带状态栏时思考量随上下文变长**持续增长**，带上后**基本恒定**。\n- **状态栏是上下文压缩技术之一**：它用代码确定性地维护「关于轨迹的结论」，与 LLM 驱动的压缩互补。\n- **无侵入性**：所有元信息以人类可读形式出现在上下文里，开发者随时可检查；不需要微调，直接在任何语言模型上起效。\n\n## 实践模式\n\n### 1. 注入位置：一条 user 角色的消息，放在最末尾\n\n```text\nmessages: [\n  { role: \"system\",    content: \"You are a customer service assistant...\" }  ← 固定，KV Cache 已缓存\n  { role: \"user\",      content: \"Help me cancel my Xfinity plan\" }\n  { role: \"assistant\", content: null, tool_calls: [...] }   ← 第 1 轮决策\n  { role: \"tool\",      content: \"Call log...\" }\n  { role: \"assistant\", content: null, tool_calls: [...] }   ← 第 2 轮决策\n  { role: \"tool\",      content: \"Call log...\" },\n  { role: \"user\",      content: \"Can you call them again to follow up?\" },\n  { role: \"user\",      content: \"<agent_status>\n      Current State:\n      - phone_call invoked 3 times (Xfinity: 3/3 max)\n      - Current time: 2025-09-14 10:30:45\n      - TODO: [1] Cancel plan (in_progress)\n    </agent_status>\" }                                        ← 框架注入的状态栏\n]\n```\n\n- **为什么是 user 角色而不是改 system**：修改 system 消息会破坏整个前缀的缓存。这里的 user 角色只是 API 协议层面的技术选择，**不等同于「来自终端用户的输入」**——Harness 借用这个消息槽位，挂载框架自动生成的系统状态信息。\n- 用 `<agent_status>` 标签包裹，便于模型识别其特殊性质。\n- 因为是追加而非修改，前面所有已缓存内容都不受影响。\n\n### 2. 状态栏的三类构成\n\n- **任务规划**：TODO 列表把复杂多步骤任务分解为清晰步骤，放在轨迹末尾，不断提醒模型当前进展和后续目标，确保行动与总体规划一致（防止只关注局部子任务）。\n- **事件的侧信道信息（Side-channel）**：为每个事件附加元数据——精确时间、地理位置、距上次 Agent 回复的时间间隔。通常随对应事件一起追加。\n- **环境当前状态的观察摘要**：系统时间、工作目录、异常操作提醒（「该工具已被重复调用 N 次」）、以及从隐式状态到显式观察的转换。随任务推进不断更新。\n\n### 3. 状态更新的两种实现与缓存代价\n\n**实现一：每轮替换**——每次 API 调用前移除上一轮状态消息，在末尾追加最新状态。保证永远只有一份最新状态，但移除旧状态会使其位置之后的所有缓存失效（与「动态时间戳」同一失效机制，区别仅在于状态消息位于末尾，失效范围只覆盖上次注入后新增的消息，通常是一轮，整个前缀仍可复用）。\n\n**实现二：持久追加**——状态消息一旦注入就永久留在轨迹中，每轮只在末尾追加新状态。Claude Code 的 `<system-reminder>` 即此方式，历史状态保留在 transcript 中从不删改。对缓存完全友好（只追加不修改，前缀始终稳定），代价是陈旧状态累积，既占 token 又要求模型自己关注最新一条。\n\n**选择规则**：\n\n- 状态很小、两次更新间产生的消息很多、会话长度受控 → **选实现二**（保留旧状态通常比反复重算长后缀便宜）\n- 状态较大、更新频繁或轨迹很长 → **选实现一**（只使上次注入后的短后缀失效，同时避免陈旧状态持续累积）\n\n**粗略成本模型**：设每条状态 S token，两次更新间新增后缀 R token，预计更新 N 次，缓存输入单价为普通输入的 α 倍：\n\n```\nC_替换 ≈ (N-1) * (1-α) * R\nC_追加 ≈ α * S * N * (N-1) / 2\n→ 当 α*S*N/2 < (1-α)*R 时倾向实现二，否则倾向实现一\n```\n\n该估算未计上下文占用和陈旧状态带来的歧义，实际选择还应结合服务商缓存计费与实测命中率。\n\n### 4. 五种状态栏技术（实验 2-9）\n\n- **时间戳跟踪**：以 `[2025-09-14 10:30:45]` 格式作为前缀添加到用户消息和工具响应中（**不是放在系统提示词里**，否则破坏 KV Cache）。让 Agent 理解时序关系，也为调试和审计提供信息；配合时间模拟可理解「昨天的文件」和「今天的修改」。\n- **工具调用计数器**：维护全局字典记录每个工具被调用次数，响应中标注 `Tool call #3 for 'read_file'`。显式计数触发模型的模式识别：第一次失败后检查路径，第二次失败后列出目录，第三次主动放弃并找替代方案。深层价值是隐式的成本感知。\n- **TODO 列表管理**：提供 `rewrite_todo_list` 和 `update_todo_status` 两个工具，每项含唯一标识符、内容、状态（pending / in_progress / completed / cancelled）和时间戳。借鉴 Manus「通过复述操纵注意力」理念。实验数据：启用 TODO 的 Agent 平均 **15 次**迭代完成任务，禁用时需 **21 次**且经常遗漏子任务。\n- **详细错误信息**：四层内容——错误类型和描述、完整参数的 JSON、调用栈信息、针对性修复建议（如 FileNotFoundError 时建议验证路径、检查工作目录、使用绝对路径）。启用后 Agent 在错误场景找到替代方案的成功率从 **60% 提升到 95%**，从盲目重试转变为有针对性地分析。\n- **系统状态感知**：注入当前时间、工作目录、操作系统类型、Shell 环境和 Python 版本。工作目录跟踪尤其关键——Agent 执行 `cd` 后自动更新；OS 信息让 Agent 做平台相关决策（Linux 用 `apt`、macOS 用 `brew`）。\n\n这些技术单独使用效果有限，**组合起来会产生涌现效应**：时间戳 + 工具计数器让 Agent 理解操作的频率和时间分布；TODO + 系统状态让 Agent 根据环境调整策略；详细错误 + 工具计数器让 Agent 多次失败后不仅改变策略，还理解失败原因。\n\n## 常见陷阱\n\n- **把时间戳写进 system prompt**：直接破坏 KV Cache 前缀，必须作为消息前缀或末尾状态注入。\n- **让 LLM 一次性批量统计状态**：模型几乎无条件地相信状态栏——你写「打了 3 次电话」，它就当真是 3 次，不会自己重算；而 LLM 做数量统计本来就容易出错。**状态栏尽量用代码维护，实在要用 LLM，也要逐条抽取、再由代码汇总。**\n- **忽视状态栏投毒风险**：状态栏信息被模型高度信任，一旦摘要内容来自可被外部污染的数据源（如把外部网页片段直接写进状态栏），这种信任会被反向利用。\n- **状态栏够用就整段删掉原始记录**：状态栏是对原始上下文的**有损投影**，只提前算了「你预想会被问到」的维度。计数、状态跟踪这类任务可以只保留状态栏以节省大量 token；但只要有一个问题涉及状态栏未计算的维度，仅保留状态栏就会导致准确率**断崖式下降**。删除前确认没有未覆盖的查询维度。\n- **状态消息无限累积从不清理**：实现二的代价，陈旧状态既占 token 又制造歧义，会话长度失控时应切换到实现一。\n- **用状态栏替代真正的任务规划**：TODO 列表需要配套工具支持状态流转，只在提示词里写「请跟踪进度」不够。\n\n## 配套代码\n\n- `chapter2/system-hint/` — 实验 2-9（agent-status-bar 框架）：实现时间戳、工具计数器、TODO 列表、详细错误、系统状态五种状态栏技术，可独立开关；`python main.py --mode preview` 无需 API key 即可对比有无状态栏时模型看到的上下文差异；`python run_experiment_2_8.py` 跑冻结的对照实验。\n\n## 深度阅读\n\n- `book/chapter2.md`「Agent 状态栏：通过元信息增强 Agent 轨迹管理」\n","skills/bad-case-to-dpo/SKILL.md":"---\nname: bad-case-to-dpo\ndescription: 把生产 bad case / 失败轨迹转成训练数据时使用——从失败归因、轨迹前缀截取、DPO 偏好对构造、LoRA 训练到边界集与保留集双集验证的完整链路；也用于判断某类问题该走 SFT、DPO、RL 还是先修 Harness/工具/tokenizer，以及如何从运行轨迹中提取带证据的结构化学习信号。触发词：bad case、失败归因、DPO、偏好对、轨迹前缀、拒绝采样、过度矫正、边界集、保留集、过早结束、reward hacking、LoRA 微调、训练评估隔离。\n---\n\n# 从问题案例到训练数据\n\n## 何时使用\n\n- 生产出现 bad case：用户纠正、点踩、事后审计发现失败轨迹，想把它变成后训练输入\n- 判断某类失败该修 Harness/工具/tokenizer，还是值得投入训练\n- 构造 DPO 偏好对、轨迹前缀回归任务、决策边界示范\n- 决定一个失败案例该进 SFT 数据、DPO 偏好对、PRM 负标签还是 RLVP 惩罚规则\n- 训练后验证修复效果，担心\"修好一个、弄坏一片\"\n- 从运行轨迹中提取可学习信号，而不是只存一个总分\n\n## 核心原则\n\n- **归因到首个错误步骤，不是整条轨迹。** 以 Coding Agent \"过早结束\"为例：读代码、改代码可能都没错，错的是\"在缺乏证据时下结论\"那一个决策边界。归因记录必须落到这一步，训练数据才能对着它构造。\n- **失败轨迹不应直接当作正确的 SFT 示范。** 它的正确用法是：构造偏好对、发现任务覆盖缺口，或补上诊断与修复后再加入训练。\n- **判定必须靠模型写不了的机制。** \"是否完成\"要由隐藏测试、状态断言或外部终止钩子给出；测试必须读取真实文件或环境状态，不能只检查模型是否说了\"已完成\"，否则模型会学会口头承诺验证而不真正验证。\n- **边界集与保留集缺一不可。** 边界集（任务未完成）看模型是否选择继续验证而非宣称完成；保留集（任务已完成）看模型是否仍能正常收尾。只盯边界集会把模型训练成永远不敢结束的**过度矫正**状态：每个任务都无限验证下去，延迟与成本崩溃。这是\"改动不能破坏既有行为\"在参数层面的版本。\n- **训练与评估严格隔离。** 训练集与评估集必须是不同的任务、不同的参数、不同的模板组合；参考解法、隐藏测试和验证器反馈不能泄露给模型。隔离规则应由单元测试强制检查，而不是靠人记得。\n- **先排除非模型原因。** 沿\"文件原始字节 → 工具返回 → Harness 序列化 → 模型上下文 → 模型 token 输出 → 解码字符串 → JSON/tool-call 解析 → 工具匹配\"逐层对比。只有模型收到的上下文与原始字符串完全一致、而**模型输出是链路上首个出现差异的位置**，才能标为模型能力问题。否则修工具/Harness/tokenizer，修完再看还剩多少。\n- **小数据 DPO 必须混入通用任务数据。** 案例数量少时，按小配比混入通用任务做 LoRA 微调，避免把\"逢收尾必验证\"学成新的过拟合，也降低灾难性遗忘风险。\n- **学习信号必须带证据。** 单一总分无法指出该改哪里。可供学习的评价至少包含：任务成功/部分成功/失败、每个维度各自的结论、每条结论对应的证据位置（哪一轮对话、哪一次工具调用）、失败的类型标签。验证器还应被允许在证据不足时**拒绝评分**——低置信度案例应排除在学习集之外，而不是当作事实固化。\n\n## 实践模式\n\n### 完整链路：失败归因 → 双集验证\n\n**① 采集与归因。** 从用户纠正、点踩、事后审计三类生产信号收集失败轨迹，按错误分类定位**首个错误步骤**并记录错误类别。轨迹前缀回归任务就是从这个决策边界截取的。\n\n**② 分流：该不该训练。** 先问 prompt、工具、代码约束、上下文管理能否解决；再沿字节链路排除工具/Harness/tokenizer 问题。都不要动权重时就不训练。\n\n**③ 选训练形态。** 按第七章评估数据集的类型映射到第八章用法：\n\n| 你手上的材料 | 训练用法 |\n|---|---|\n| 端到端回归任务（含验证器） | RL rollout 任务与可验证奖励（RLVR）；拒绝采样（RFT）的采样池 |\n| 轨迹前缀回归任务 | DPO 偏好对、决策边界的 SFT 示范、On-Policy Distillation 的教师状态 |\n| 失败归因记录（首个错误步骤与错误类别） | 过程监督的负标签（PRM）、RLVP 路径惩罚的规则来源 |\n| Rubric 多维评分与人工金标集 | 向量奖励的各维度、生成式奖励模型（GRM）的训练与校准数据 |\n\n**④ 截取轨迹前缀，构造偏好对。** 在决策边界上截出\"准备宣称完成\"的轨迹前缀：rejected 是过早结束的错误行为，chosen 是\"先运行测试、逐条核对验收条件，再下结论\"的期望行为。chosen 由教师模型生成，再经规则验证器过滤（拒绝采样）。案例太少时用数据扩充（换任务类型、换缺失的验证项、换完成措辞）形成数百条偏好对。失败原因、适用条件和验证器应随样本保存，方便追溯和复查。\n\n**⑤ LoRA DPO 训练。** 小配比混入通用任务数据防过拟合。参考配置：Qwen2.5-7B-Instruct + bf16 LoRA、4 epochs、学习率 3e-5、单卡约 24GB 显存。训练回执记录配置、数据哈希与时间戳。\n\n**⑥ 双集验证。** 对未完成任务集和已完成任务保留集分别让模型给出\"下一步动作\"，判定属于\"宣称完成\"还是\"继续验证\"：\n\n- **未完成任务集的过早结束率** —— 训练后应下降\n- **已完成任务保留集的正常收尾率** —— 训练后应保持\n- **过度矫正率 = 1 − 正常收尾率** —— 应维持在低位\n\n优先采用**格式固定、与训练提示一致的候选比较**（固定两个候选动作，比较模型更偏好哪一个，直接测量决策边界），而不是开放式自由生成。同时抽查通用能力，确认 LoRA 补丁没有破坏其他能力。\n\n**⑦ 记录与追溯。** 训练数据与评估集分开保存；数据构造有确定性模板和教师模型两条路径时，两条都留证据回执。\n\n### 案例参照：Coding Agent 过早结束（实验 8-17）\n\n配套数据：24 条轨迹前缀 bad case，覆盖四类过早结束——未跑测试就宣称完成、多目标只完成一部分、声称完成但验收条件未满足、遇错放弃宣称不可能（含删除失败测试/skip 等 reward hacking 变体）；与训练数据严格隔离的留出评估集为 boundary 12 条 + retention 8 条。\n\n实测结果：基座在固定候选比较的未完成任务集上选对 **3/12（25.0%）**，已完成任务保留集 **8/8（100%）**；LoRA DPO 后分别为 **11/12（91.7%）** 和 **8/8（100%）**。自由生成是补充诊断：过早结束 1/12→0/12，但正常收尾 6/8→0/8——**说明小数据 DPO 会让模型在开放式回答里过于谨慎**，因此主要结论只采用候选比较口径，不能外推成线上总体成功率提升。\n\n同一个问题还有 RL 分支：把\"宣称完成前必须跑通验收测试\"写成可验证奖励，测试对模型不可见，模型宣称完成时才运行，通过 +1、不通过 −1。\n\n### 另外两类常见案例的处理差异\n\n- **规则类反馈（如\"中文直引号应统一为弯引号\"）**：期望描述不是可直接训练的规则，同一个引号在中文自然语言、英文原文、Markdown 行内代码、代码块、注释、JSON、路径中角色完全不同。正确做法是**作用域敏感的最小编辑**：先把规则写成可审计的 Skill（正例覆盖需转换的中文段落与中文注释，反例覆盖英文原文、字符串字面量、JSON、路径、行内代码），它同时作为合成数据的标签依据、训练后的回归规范和规则变更时的重训输入。\n- **byte-exact 复制类（如 `edit_file` 的 `old_string` 匹配失败）**：把复制任务抽象成三个可验证任务——直接逐字复述、在相似且等长的多个字符串中选择完全相同的目标、把指定字符串完整抄写到 `old_string` 工具参数。样本特意包含真实编辑最容易损坏的空格、换行、反斜杠、Unicode 组合字符。训练后要用独立 tokenizer 审计排除词元化造成的假象：若 round-trip 上限本身就是 80.1%，模型测到 80.1% 就不能算作纯能力提升。\n\n### 从运行轨迹中提取学习信号（三层验证）\n\n评价一条轨迹实质是依次回答三个问题：**事情是否办成了、是否以允许的方式办成、是否让用户舒服。**\n\n- **底层结果验证器**——读测试结果、数据库状态、工具返回。这类信号来自环境真实状态，比模型对自己行为的描述可靠，是三层中最应优先建立的一层。\n- **中间过程验证器**——检查业务规则、权限和动作序列，区分\"结果已达成\"与\"结果以允许的路径达成\"。删除失败测试用例也能让测试通过；口头承诺也能得到暂时满意。政策库、权限表与动作轨迹均可精确表达，因此这层同样可以由代码判定。\n- **上层质量验证器**——是否耐心、是否提供合规变通、文本是否自然简洁。用 LLM-as-a-Judge 加预定义 Rubric，要求逐项给分并引用轨迹证据。\n\n输出形态决定它能否成为学习信号：单一总分只能反映一次运行的优劣。四项内容（成败判定、每维度结论、证据位置、失败类型标签）齐备，后续才能判断该更新知识、提示词、程序还是模型参数。\n\n## 常见陷阱\n\n- **把失败轨迹直接当正确示范训练**，把错误行为固化进参数。\n- **只优化边界集，不看保留集**，把模型训成永远不敢收尾的过度矫正状态。\n- **训练集与评估集共享任务或参数**，评估失去独立性；隔离规则要由测试强制，不靠人记得。\n- **用模型自述当完成判定**，模型很快学会\"口头声称去验证\"而不真的验证。\n- **把系统层损坏误报为后训练收益**：直接复述探针正确但工具调用仍失败时，该修的是 Harness 或工具协议。\n- **把 tokenizer/序列化损坏误判为模型复制能力不足**，训练前先做独立 tokenizer round-trip 审计。\n- **案例太少又不做扩充**，几条偏好对撑不起一个决策边界；或扩充时只换措辞不换任务类型与缺失验证项。\n- **小数据 DPO 不混通用数据**，学出\"逢 X 必 Y\"的新过拟合并带来灾难性遗忘。\n- **低置信度结论进入学习集**，错误经验和提示注入被固化并在后续任务持续放大。\n- **把开放式自由生成当主要验收口径**——小数据 DPO 下自由生成会过度保守，格式固定的候选比较才与训练提示一致。\n\n## 配套代码\n\n- `chapter8/premature-completion-dpo/` — 全书唯一从生产 bad case 出发的训练实验：24 条 bad case、boundary 12 + retention 8 留出评估集、隐藏测试；`python demo.py` 离线端到端演示，`python -m pytest -q test_pipeline.py` 机制单元测试，`python build_preference_data.py` 生成偏好对（`--teacher` 走教师模型拒绝采样路径），`python train_dpo.py --smoke` 数据/tokenizer 前向检查，`python train_dpo.py` 单卡 LoRA DPO，`python evaluate.py --decision-score` 双集候选比较评估，`python train_grpo_optional.py` 同一问题的可选 RL 分支。\n- `chapter8/curly-quote-sft/` — 规则类反馈的另一种监督目标：先写 `SKILL.md` 规范，再结构化合成数据做作用域敏感 SFT。\n- `chapter8/exact-copy-sft/` — byte-exact 复制 SFT，含 `tokenizer_audit.py` 排除词元化假象。\n- `chapter8/cot-distillation/` — \"生成候选—验证过滤—只留正确轨迹\"的拒绝采样流水线范例。\n\n## 深度阅读\n\n- `book/chapter8.md`「从问题案例到后训练」\n- `book/chapter8.md`「SFT 数据合成：从示范到可训练轨迹」\n- `book/chapter8.md`「奖励设计：如何把任务目标变成学习信号」\n- `book/chapter9.md`「从运行轨迹中获得学习信号」\n","skills/coding-agent-harness/SKILL.md":"---\nname: coding-agent-harness\ndescription: 搭建 Coding Agent 或设计 Agent 护栏时使用——当你要构建能自主读写代码、跑测试、自我纠错的编码 Agent，或为已有 Agent 系统补约束/验证/纠正机制、设计执行边界与验收基线、判断某类任务是否适合交给 Agent、优化 Harness 提示词与工具集时使用。覆盖 Harness 四组件、任务四象限、四条设计原则与业界实践。\n---\n\n# Coding Agent 与 Harness 工程\n\n## 何时使用\n- 从零搭建 Coding Agent（选工具集、定工作流、接测试反馈）\n- 为已有 Agent 补可靠性：加护栏、验收基线、执行边界、回退手段\n- 评估一个任务是否适合交给 Agent 自主执行（四象限判断）\n- Agent \"能跑但不可靠\"：跑偏、走破坏性捷径、过早宣布完成\n- 优化 Harness 本身（提示词、工具中间件、自验证循环）而不是换模型\n\n## 核心原则\n\n**Agent = Model + Harness，Harness = 上下文管理 + 工具接口 + 约束 + 验证 + 纠正。**\nHarness 是\"Agent 边界内、模型之外\"的运行与治理层：工具定义、调用适配器、沙箱权限属于 Harness；沙箱内的文件进程、外部数据库、用户属于 Environment。模型能力趋同后，竞争力在 Harness。\n\n**Coding Agent 场景的 Harness 四组件**（把抽象机制落地成工程件）：\n\n| 组件 | 回答的问题 | 落地形态 |\n| --- | --- | --- |\n| 验收基线 | 什么算做完了 | 测试套件、CI 管道、代码审查标准 |\n| 执行边界 | 能碰什么不能碰什么 | 模块边界、依赖规则、权限控制 |\n| 反馈信号 | 自动化的对错判断 | Linter 输出、测试结果、类型检查错误 |\n| 回退手段 | 出了问题怎么恢复 | Git 版本控制、沙盒隔离、快照回滚 |\n\n**任务四象限（目标清晰度 × 验证自动化程度）**——Harness 的目标是把任务推向\"目标明确 + 可自动验证\"：\n\n- 目标明确 + 可自动验证 = **最佳区域**（修复有测试用例的 bug）\n- 目标明确 + 需人工验证 = **吞吐量受限**，天花板是人的审查速度\n- 目标模糊 + 可自动验证 = **高效地跑偏**（如拿 linter 分数优化\"代码质量\"）\n- 目标模糊 + 需人工验证 = **难以启动**（如\"让 UI 更好看\"）\n\n代码编写天然处于象限核心：测试套件给验收标准，Linter/类型检查给即时验证，Git 给版本控制与回退。Coding Agent 成熟度最高不是因为代码模型最强，而是软件工程几十年积累的基础设施天然就是一套 Harness。\n\n**四条可迁移的设计原则**：\n\n1. **约束优先于指导**——能用代码强制的规则不要用文档建议。Linter 规则、类型约束、CI 检查是\"做不了\"，系统提示词里\"请遵循...\"只是\"建议别做\"。\n2. **验证要自动化**——人工审查是不可扩展的瓶颈，测试/检查/监控的投入回报率远高于加人力。\n3. **反馈越快越好、越结构化越好**——错误信息越详细、越接近出错时刻，Agent 纠正效率越高。\n4. **回退要可靠**——有安全网 Agent 才敢试错；Git 分支、沙盒、快照确保任何错误可逆。\n\n**约束管动作，不只是管结果。** 验收基线管结果对不对，执行边界管过程：删库重建\"修复\"了故障但数据没了，删光重写让编译通过但实现没了。这类破坏性捷径 Agent 总能绕开指标找到（reward hacking 的日常形态），因此 `rm -rf`、删生产数据、覆盖未读文件要设专门检查与审批。\n\n**并行调用的故障边界控制**：一个工具失败时，故障只在同一批并行调用内传播（级联中止依赖它的调用），不取消独立调用，不上升到父级操作、不让整个任务中止。每个工具声明是否支持并发（默认否，失败安全）。\n\n**业界经验**：\n- 大规模代码迁移成功靠三件事：知识必须存在于代码库本身（Agent 看不到的等于不存在）、约束编码进 Linter/CI 而非文档、验证与纠正全链路自动化。\n- LangChain 只优化 Harness（提示词、工具中间件、自验证循环）就把 Terminal Bench 2.0 从 52.8% 提到 66.5%，并用 Agent 分析失败轨迹反哺 Harness，让 Harness 工程从经验驱动变数据驱动。\n- Anthropic 拆两个角色：初始化 Agent 分解任务清单，执行 Agent 逐步推进并留下清晰的交接产物，解决\"一次想做太多\"和\"过早声称完成\"。\n\n## 实践模式\n\n**建一个 Coding Agent 的最小清单**：\n\n1. **工具集**：文件读写（read/write/edit）、目录浏览（glob/ls）、内容搜索（grep）、命令执行（bash）七件套；每个工具命名直观、参数带例子、边界有说明（防呆设计）。\n2. **工作流**：先理解项目（读文档、建认知框架）→ 设计 → 实现 → **立即写测试并跑** → 失败则分析-定位-修复循环，直到测试全绿。把\"测试通过\"而非\"代码写完\"定义为完成标准——跳过测试直接报完成是 Coding Agent 最常见的偷懒方式。\n3. **验收基线**：接入现成的测试套件、Linter、类型检查、CI；没有就先补最小可跑的。\n4. **执行边界**：默认权限最小化（故障安全默认值，能力默认关闭、显式开放）；危险命令走审批。\n5. **回退手段**：每次任务前开 Git 分支或快照；沙盒内执行不可逆操作。\n6. **反馈回路**：把 Linter/测试/编译错误结构化地喂回上下文（附行号、文件路径、错误类型）。\n7. **持续改进**：收集失败轨迹，让 Agent 分析轨迹反哺 Harness 修改。\n\n**上下文与环境注入**（Harness 的上下文层）：大文件按行号范围读取并给每行加行号前缀；长命令输出只保留头部（错误上下文）与尾部（错误总结）并说明完整输出已落盘；每次推理前以状态栏形式动态注入当前工作目录、git 分支、最近提交、未暂存变更（动态追加，别硬编码进系统提示词以免破坏 KV Cache）；维护持久化终端会话保留 cd/环境变量状态。\n\n## 常见陷阱\n- 把指导写进提示词而不落成代码约束——模型会忽略\"请遵循...\"式建议\n- 没有验收基线就放权：Agent 高效地往错误方向跑，或走破坏性捷径（删库重建、删光重写）\n- 写完代码不跑测试就报告\"任务完成\"\n- 把整个代码库一股脑塞进上下文，既不经济也没必要\n- 一个工具失败就中止整批并行调用甚至整个任务\n- 只换模型不修 Harness：基准提升往往来自 Harness 而非模型\n- 环境信息硬编码在静态系统提示词里\n\n## 配套代码\n- `chapter5/coding-agent/` — 纯 Python 实现的生产级 Coding Agent：16 个工具、patch 应用、测试/lint 验收反馈与失败路径\n- `chapter1/context/` — 上下文感知 Agent 与消融实验：量化 history/reasoning/工具调用/工具结果各自的作用\n- `chapter1/web-search-agent/` — 基于 Kimi Formula API 的自主 ReAct 搜索 Agent，展示\"模型即 Agent\"的最小闭环\n- `chapter1/search-codegen/` — Responses API 深度研究 Agent：托管 web_search + code_interpreter 的编排\n- `chapter1/learning-from-experience/` — LLM 上下文学习 vs 传统 RL 对照，理解 Agent 经验从哪来\n- `chapter1/image-gen-workflow/` — 工作流路线 vs 原生生成路线对照：何时该用固定 Harness、何时该交给模型自主\n\n## 深度阅读\n- `book/chapter5.md`「Coding Agent」→「Harness 工程在 Coding Agent 中的实践」\n- `book/chapter1.md`「Harness 工程：模型之外的竞争力」\n","chapter8/curly-quote-sft/SKILL.md":"# 中文技术文档符号与引用规范\n\n## 何时加载\n\n- 编辑或生成同时包含中文、英文、Markdown 和代码的技术文档。\n- 用户反馈引号、反引号或代码边界格式错误时。\n\n## 符号定义\n\n- ASCII 直引号：`\"`、`'`；常用于英文标点和代码字符串。\n- 中文弯引号：`“”`、`‘’`；用于中文自然语言引用。\n- Markdown 反引号：`` ` ``；用于行内代码和字面量。\n\n## 决策优先级\n\n1. 先保护可执行代码、JSON/schema、URL、路径和用户要求原样保留的引用文本。\n2. 识别 Markdown 代码围栏、行内代码和代码注释边界。\n3. 在中文自然语言作用域中，把成对的直引号改为弯引号，并正确处理嵌套引用。\n4. 英文原文保持原文标点；英文标识符是否使用反引号由其是否为代码字面量决定，而不是由语言决定。\n5. 无法判断作用域时保留原文并请求澄清，不做全局替换。\n\n## 正反例约束\n\n- 正例：`# 中文注释：显示 \"状态\"` → `# 中文注释：显示 “状态”`；同一代码块中的 `name = \"status\"`、`const name = \"status\"`、SQL 标识符和 JSON 键值保持 ASCII 语法。\n- 反例：不能把代码字符串、JSON、URL、路径、英文原句或 Markdown 行内代码中的 `\"`/`'` 改成弯引号；不能因为文件是中文就全局替换。\n- 每种编程语言至少提供“该改的中文注释”和“该留的可执行字面量”成对样本，并在留出/边界集更换体裁、变量名和代码结构。\n\n## 数据质量门禁\n\n- 合成数据先按文章体裁、作用域类型和编程语言分层，再切分 train/eval/boundary，禁止 ID 和模板组合重叠。\n- 机器门禁检查未解析变量、代码围栏、非注释代码行漂移和保护区；人工抽查每个分层的首条样本，记录在 `validation/manual_audit.md`。\n- 任何语言类别的保护区或语法门禁失败，都应回到 Skill/数据蓝图修订后重训，不能只增加 epoch 或汇报总体平均分。\n\n## 验证\n\n- 修改必须是最小编辑，正文事实和代码内容不变。\n- Markdown、JSON 和代码语法检查必须通过。\n- 英文原文、代码和保护区域做字节级回归。\n- 记录来源 Bad Case、适用范围、例外和验证结果。\n","skills/context-compression/SKILL.md":"---\nname: context-compression\ndescription: 上下文膨胀、工具结果撑爆窗口、Agent 决策质量随轮次下降时使用——上下文压缩的三个动机（长度成本、思考质量、上下文焦虑）、压缩即检索的机制、六种压缩策略实测数据、生产级五层分层压缩、四条设计原则，以及用子 Agent 隔离代替压缩。\n---\n\n# 上下文压缩策略\n\n压缩解决的是相反方向的问题：**如何为上下文做减法**——什么时候压缩、怎么压缩、为什么即使上下文没满也应该压缩。核心认知：**上下文学习本质上是检索而非推理**，压缩就是把需要思考才能得到的结论，变成可以直接检索的知识。\n\n## 何时使用\n\n- 工具调用结果动辄数万字符，几轮交互就撑满 128K 窗口\n- Agent 在长任务中「明明窗口没满，却找不到关键信息」或反复纠结已解决的问题\n- 模型在任务尚未完成前提前收尾、草率下结论\n- 设计压缩策略（何时触发、压缩什么、保留什么）或排查压缩副作用\n- 评估「把大任务委派给子 Agent」与「主 Agent 自己做完再压缩」的取舍\n\n## 核心原则\n\n- **三个动机，层次不同**：① 长度与成本约束（窗口有限、token 越贵、延迟越高）；② 提升思考质量——总结后的知识比原始形式更利于模型使用，十几轮搜索的原始结果散落各处，模型每次决策都要在数万 token 中反复检索；③ 缓解**上下文焦虑（Context Anxiety）**——模型认为窗口即将耗尽时可能在任务完成前提前收尾，在未接近耗尽时就提前压缩可能提升决策质量。\n- **上下文窗口是一台只有一半的检索引擎**：检索这一半极强（相当于每次前向传播都内置了 RAG），但缺「提炼层」——上下文里的东西从来不会被自动数一遍、建索引或就地总结。任何「关于这些内容的结论」都要从原始记录现算一遍，代价随内容量 N 上涨。\n- **压缩与状态栏是同一枚硬币的两面**：状态栏把算好的结论**加**进上下文（由代码确定性维护），压缩把臃肿的原始记录**换**成算好的结论（多用一次 LLM 调用蒸馏）。\n- **上下文腐化（Context Rot）≠ 溢出**：溢出是「装不下了」，腐化是「装得下但找不到了」——后者更隐蔽，Agent 表面正常工作，决策质量悄然下降。注意力权重被分散到更多 token 上，无关内容一旦占大头，决策质量明显下滑。\n- **主动显式提炼，不要期望模型自动学习**：与其让模型被动在海量信息中检索，不如主动提供经过提炼的高密度结构化知识。\n- **压缩最容易丢失**：早期的架构决策、约束背后的理由、失败的路径。因此 Agent 需要定期把进展记录到文档，而不是把所有信息零散堆在执行历史里。\n- **隔离优于压缩**：压缩是信息已进入上下文后的事后有损补救；隔离让大体积中间信息根本不进入主上下文。\n\n## 实践模式\n\n### 1. 六种压缩策略实测对比（实验 2-10）\n\n任务：识别并追踪 OpenAI 联合创始人的职业状态；Kimi K3（原生约 1M 窗口，实验刻意限制在 128K 预算以触发压缩）。\n\n| 策略 | 做法 | 迭代 | Token | 压缩率 | 问题 |\n| --- | --- | --- | --- | --- | --- |\n| 无压缩 | 完整保留原始结果 | 5 次即溢出失败 | ~165,000 | — | 7 次搜索累计约 367,000 字符（平均 52,000/次），数次搜索即耗尽 128K |\n| 个体摘要 | 每个结果独立生成 2-3 段摘要 | 12 | 276,608 | 10.9% | 信息碎片化，多页重复描述同一事件 |\n| 组合摘要 | 所有结果合并后一份综合摘要 | 10 | 93,449 | 4.3% | 输入超长必须截断，可能丢失末尾信息 |\n| **上下文感知** | 压缩提示中带入查询意图与已积累信息 | 7 | 40,157 | ~3.0% | 最优平衡点 |\n| 带引用的上下文感知 | 智能压缩 + 每条事实附带来源 URL | 7 | — | — | 内容有损、索引无损，可回溯原文 |\n| 自适应窗口化 | 阈值触发 + 批量压缩 + 防重复 | — | 174,601 | — | 初期保留完整原始信息，灵活性最大 |\n\n> 压缩率定义为「压缩后体积 / 原文体积」，数值越小表示压得越狠。上下文感知压缩将 token 使用量减少 75% 以上。\n\n**上下文感知的提示词写法**：在压缩提示中指定 `Given the search query: {query}` 和 `Current context: {context}`，引导模型生成针对性摘要。实测把约 150K 字符压到 2K 字符时，仍保留创始人姓名与职位变动等后续任务需要的关键信息。\n\n### 2. 自适应窗口化三机制（推荐默认）\n\n- **阈值触发**：持续监控上下文使用率，prompt token 超过窗口 80% 时才激活压缩（如 102,400 / 128K）。\n- **批量压缩**：触发时一次性压缩所有未标记的工具结果，而不是每轮零碎压。\n- **防重复保护**：添加 `[COMPRESSED]` 标记，确保已压缩内容永不被重复处理。\n\n### 3. 压缩与 KV Cache 的共存\n\n压缩不是在单次 API 调用中修改上下文，而是在**两次 API 调用之间**由框架预处理消息列表：\n\n1. **System Prompt 和 Tool Definitions 永远不动**——静态前缀持续缓存。\n2. **压缩对象是对话历史中的 tool results**——替换位置之后的缓存失效，之前的仍有效。\n3. **有意识的权衡**：不压缩则溢出失败；压缩损失部分缓存但长度可控、信息密度更高。**压缩频次需要权衡——频繁压缩频繁破坏缓存，最好在接近阈值时批量压缩，而不是每轮都压。**\n\n### 4. 生产级五层分层压缩（Claude Code 参照）\n\n不同信息有不同保质期，压缩策略应与预期生命周期匹配，按代价从低到高排列：\n\n1. **工具结果预算控制**：大体积输出存磁盘，模型只看摘要预览；替换决策一旦做出就冻结，保证缓存一致性。\n2. **噪声直接删除**：低价值内容（如大量搜索结果中只被用了几行的部分）直接移除，不做摘要——对噪声做摘要只是浪费 token。\n3. **API 层微压缩**：通过上下文编辑能力指示服务端从前缀移除指定工具结果，本地消息不变；零本地实现成本，但移除点之后缓存同样失效，产生一次缓存重建——适合上下文即将溢出、反正要付这次代价时用，不要频繁触发。\n4. **归档式摘要**：逐轮结构化摘要，像 git log 保留每轮独立记录，而非 git squash 合并成一条，保留对话逻辑脉络。\n5. **全量压缩**：LLM 驱动的完整压缩，作为最后手段；分两阶段（先压会话记忆，不行再全量），并配**连续失败熔断器**——生产数据显示大量会话被困在反复压缩失败的循环中，熔断器避免持续烧钱。\n\n### 5. 四条压缩设计原则\n\n- **信息价值的非均匀分布**：关键决策点（如人员名单）> 支撑性证据（如新闻细节）> 冗余噪声（网页导航栏、页脚广告）。\n- **语义完整性**：`Sutskever 于 2024 年 5 月离开 OpenAI` 不能压成 `Sutskever 离开`——时间和公司名是不可丢失的关键信息。\n- **任务相关性**：同样内容在「查找创始人名单」和「了解个人背景」两个任务下应产生不同压缩结果。检索类任务保广度，分析类任务保深度，创作类任务保灵感触发点；理想的 Agent 应按任务类型自适应选择压缩策略。\n- **压缩即理解**：有效压缩需要深层语义理解，负责压缩的模块本身要接近主模型能力，形成「模型调用模型」的递归架构；好处是显式压缩的结果可审查、可跨会话复用。\n\n### 6. 必须保留的四类信息\n\n无论哪种策略，压缩时都要显式 preserve：**decisions（决策）、constraints（约束）、failures（失败路径）、citations（来源引用）**。\n\n### 7. 隔离优于压缩：子 Agent 上下文隔离\n\n对比同一个任务「在代码库中找到处理支付回调的函数」：\n\n- **主 Agent 亲自搜索**：可能把十几个文件数万 token 原始代码纳入主上下文，找到目标后绝大部分沦为永久噪声，还得靠后续压缩清理。\n- **委派给搜索子 Agent**：主上下文只增加两条消息——一条任务描述，一条结论（「函数位于 `src/payment/callbacks.py` 的 `handle_callback`，另有两处调用点」）；中间过程的数万 token 随子 Agent 上下文一起丢弃。\n\n代价是子 Agent 看不到主 Agent 完整上下文，**任务描述必须自包含、目标明确**。Claude Code 的 Task 工具、各类 Deep Research 的检索子 Agent 都是这一模式的生产实现。\n\n## 常见陷阱\n\n- **每轮都压缩**：频繁破坏 KV Cache 前缀，应阈值触发 + 批量压缩。\n- **对噪声做摘要**：把只用了几行的搜索结果压成摘要，纯浪费 token，应直接删除。\n- **压缩时丢掉时间和主体**：语义不完整比不压缩更糟——模型会基于错误事实继续推理。\n- **用远弱于主模型的模块做压缩**：压缩即理解，能力差距大会丢关键信息。\n- **把压缩当成长度问题的唯一解**：即使窗口够大，压缩仍能提升思考质量、缓解上下文焦虑。\n- **让模型自己数数和统计**：查找是注意力强项，统计要遍历全部记录并维护计数状态；应提前把结论写进上下文。\n- **把所有进展只留在执行历史里**：早期架构决策、约束理由、失败路径最容易在压缩中丢失，必须定期落到文档。\n- **给子 Agent 派发含糊任务**：子 Agent 上下文隔离的代价就是任务描述必须自包含，否则结论质量无法保证。\n\n## 配套代码\n\n- `chapter2/context-compression/` — 实验 2-10：实现并对比 6 种压缩策略（`no_compression` / `individual` / `combined` / `context_aware` / `citations` / `windowed`），输出成功率、耗时、token、压缩率、溢出次数对比表；用 `python experiment.py -s context_aware` 单跑，`-m moonshot-v1-128k` 配合 `CONTEXT_WINDOW_SIZE=128K` 复现溢出。\n\n## 深度阅读\n\n- `book/chapter2.md`「上下文压缩策略」\n","skills/async-event-agent/SKILL.md":"---\nname: async-event-agent\ndescription: >-\n  构建异步/事件驱动 Agent，或让 Agent 响应外部事件（新邮件、webhook 回调、IM 消息、定时器、系统告警）、\n  处理工具执行期间的用户打断与多任务并发时使用。覆盖事件循环与安全点、三类事件触发工具、用户沟通与多渠道召回、\n  虚拟身份与隔离执行环境、队列式/取消式/并行式三种事件处理策略及紧急度判定，以及模型原生异步与同步接口兼容两条路线。\n  触发词：异步 Agent、事件驱动、event-driven、webhook、定时器、心跳、任务句柄、打断、steering、并行工具执行。\n---\n\n# 异步与事件驱动 Agent\n\n## 何时使用\n\n- 要让 Agent 在**没有用户输入时也行动**：定时生成报告、周期性检查服务器、跟进未回复的邮件、到工作时间再拨打电话。\n- 要接入**外部事件源**：新邮件到达、API 回调、IM/短信消息、GitHub PR 变更、支付失败告警。\n- 要支持**执行期间被打断**：长任务运行中用户说\"停\"\"改一下预算\"\"先帮我查个天气\"。\n- 要**同时管理多个并发任务**：并行跑几个脚本、先完成的先看结果、未达进度就取消。\n- 要从回合制 ReAct 循环升级为长期运行的**事件循环 Agent**。\n- 要评估某个模型/接口是否支持原生异步，或为不支持的接口设计兼容层。\n- 任务需要在\"发起\"与\"收尾\"之间跨越多个回合（如代打电话、长时审批流）。\n- Agent 需要以\"活人感\"与用户异步沟通（发消息、图片、文件、按紧急度推送提醒），而非必须打开指定会话。\n\n## 核心原则\n\n- **回合制是交互约定，不是环境性质。** 世界不会等模型反应完才变化；任务常在\"发起\"与\"收尾\"之间跨越多个回合。\n- **架构是事件循环，不是轮询。** Agent 是一个长期运行的循环：每轮从输入队列取若干事件 → 追加到轨迹 → 调一次 LLM → 执行它决定的工具 → 回到开头等下一批。不要用\"反复问有没有新消息\"的轮询。\n- **\"主动服务\"的前提是事件能推给 Agent。** Hooks（框架内生命周期事件）、Cron（定时调度）、Heartbeat（每隔 N 分钟唤醒）三种机制里只有后两种让 Agent 自己动起来，且都是**时间驱动**的；对内置渠道之外的第三方事件源（新邮件、外部回调）必须建实时推送通道，否则只能等下一个周期才察觉——这个延迟在验证码等待、三方通话等场景里不可接受。\n- **安全点决定一切。** 同步接口中事件只能在循环边界（一段推理结束、一次工具返回）被消费；紧急事件的取消式处理本质是\"主动提前制造一个安全点\"。取消点必须是工具或推理能安全收尾的位置。\n- **取消 ≠ 撤销。** 发送取消信号只是让执行器停止；已经发生的动作不会回滚。未完成的工具结果用显式占位符表示，不能伪造成功。\n- **三种处理策略按紧急度选择**：\n  - **取消式**（紧急事件：`user.interrupt`、`supervisor.instruction`、`agent.interrupt`、紧急告警）：停当前操作 → 清空队列 → 所有事件连同紧急事件一次性追加到轨迹 → 立即重新调 LLM。\n  - **队列式**（常规事件：`user.input`、`tool.result`、`timer.trigger`）：放入队尾不打断，等本轮到达安全点后**批量**追加，减少往返。\n  - **并行式**（独立、轻量、需快响的查询，如\"今天天气怎么样\"）：在独立推理会话中执行，结果追加进主轨迹并**明确标记为并行**，避免 LLM 混淆。\n  - 硬编码规则有局限；建议用轻量分类 LLM 做事件路由器。\n- **所有输入统一建模为结构化事件**：来源（谁）、渠道（方式）、内容（什么/紧急度）、上下文（与哪个任务相关）。这是防止把工具结果误当用户指令、以及提示注入的前提。异构触发器（webhook、定时器、邮件、数据库变更、文件监听）统一建模后，Agent 才能用一致方式处理不同来源的刺激。\n- **异步语义要写进工具接口**：把\"启动\"和\"完成\"解耦——`initiate_phone_call` 立即返回任务 ID 和初始状态，进展通过 `phone_call_connected` / `phone_call_ended` 等事件通知。工具名和描述本身就要传达异步语义（\"任务发起后立即返回 ID，你可以继续处理其他事项，结束后会收到单独通知\"）。\n- **三条路线按模型能力选择**：原生异步（工具挂起、模型继续、回合中途 steering）> 同步接口兼容（占位符 + 队列 + 重新请求）> 退化回纯串行。用了 `asyncio` 不等于模型具备异步能力，仍需应用层管理事件来源、工具生命周期与结果归属。\n- **可靠处理比能接收更难**：至少要检查——延迟结果能否归入正确任务且缺席时不编造；处理新要求后能否恢复原任务并区分\"修改计划\"与\"停止执行\"；多条更新能否同时遵守而不是只记住最后一条。\n- **事件优先级要动态判断，不是静态排序**：Agent 应像秘书按紧急程度决定先处理哪个、做到一半能否暂停切换，而不是固定先后。长任务异步执行不应阻塞用户交互，被打断的任务要能自然恢复。\n- **占位符只在打断时引入**：常态下 LLM 看到的就是标准同步轨迹；只有出现打断才插入\"工具正在后台执行\"的占位 tool result 修复配对格式，后台真实结果到达后再以带来源和任务 ID 的事件送回。\n\n## 实践模式\n\n1. **搭骨架**：inbox 队列 → 分发器（按紧急度路由）→ 单线程事件循环 → 轨迹存储。参考 `chapter6/async-agent/` 的 `runtime.py::AgentRuntime`（`_dispatcher` 路由紧急度、`_handle_interrupt` 在安全点取消、`run_llm_turn` 推进轨迹）。\n2. **接事件源**：三类事件触发工具——定时器（一次性 + 循环，循环定时器兼容只能主动查询的外部服务）、后台任务监控（监控新增输出或关键词，别让 Agent 反复盯命令行浪费 token）、外部事件通道（实时推送）。每个触发源都要定义过滤规则和足够上下文的 payload，避免无关事件烧算力。\n3. **定义紧急度分类器**：先列事件类型清单和默认策略，再用轻量 LLM 兜住语义边界（\"马上停下来\"→取消式，\"报告用中文发我\"→队列式，\"天气如何\"→并行式）。\n4. **同步兼容层五规则**：assistant 消息与工具调用项立即落轨迹；只有工具真正返回才记 tool result；执行中被打断则生成占位 tool result 后再追加新事件并重新请求；无 steering 时取消未完成生成、只保留已确认消息；非打断事件一律入队批处理。\n5. **多条更新的综合**：给每个未处理事件加显式标记（`[未处理事件 2/4] ...`），末尾附汇总，提示模型必须回应全部，防止只记住最后一条。\n6. **并发任务的状态可观测**：每个异步工具调用都要有任务 ID，支持按 ID 查询进度和取消；完成事件注入主轨迹时带真实结果（退出码、产出哈希），不要只报\"已完成\"。\n6. **触达用户**：用户沟通工具支持异步消息、已读/未读、多渠道（IM/短信/邮件/电话/推送），按紧急程度、用户状态、内容性质、用户偏好选择渠道——通知机制同时是召回机制，用于长任务完成与周期性任务的习惯养成。\n7. **身份与环境**：给 Agent 独立虚拟身份（专属账号、存储、计算环境）跑在隔离的 VM/容器或虚拟手机里；通过共享卷（如 `/workspace/shared`）以**文件路径**而非内容传数据，避免占满上下文；必须登录用户真实账号时走 Human-in-the-Loop（VNC/RDP 让用户亲自登录，会话令牌有效期内复用）。\n8. **验收三层**：事件能否及时到达 → 系统是否按策略执行（取消真的终止了子进程、批量是否齐全）→ 模型是否正确使用了这批更新（结果归属、未完成时不编造、恢复原任务）。可加状态检查点做中断后恢复验证。\n\n## 常见陷阱\n\n- **把\"任务已启动\"当成\"任务已完成\"**：占位符让模型误以为结果已到，在真实结果返回前做出依赖它的判断。必须用明确的任务状态和结果校验，并在评估中检查是否编造了未到达的数据。\n- **注意力分散**：批量事件只回应最后一条，前面的要求被静默丢弃。\n- **轮询冒充异步**：让 Agent 每隔几秒查一次状态，既慢又烧 token；要么用推送通道，要么用循环定时器 + 增量监控。\n- **明文拼接不可见推理**：服务端管理的 reasoning 状态要按提供商续接协议保留，不要自行拼出\"半截思考\"回灌。\n- **取消只发信号不检查**：执行器若不响应取消（类似不检查 `ctx.Done()`），\"停止\"消息发出去任务还在跑。\n- **给所有事件同一优先级**：紧急告警和常规输入走同一条队列，要么该停的停不下来，要么鸡毛蒜皮打断主任务。\n- **直接托管用户个人账号**：Agent 出错或被攻破即暴露全部数字身份；独立身份 + 隔离环境更安全也更可审计。\n- **忽略反机器人机制**：数据中心 IP 的虚拟环境容易被识别，需住宅代理；平台侧还可能有生态级封禁。\n- **用一次失败反推训练原因**：未公开的训练过程不可证，先查系统层的任务状态、事件来源和执行反馈。\n- **忘记维护多个对话线程的关联**：第三方消息如何影响用户情绪、用户在不同线程扮演什么角色、何时综合多线程信息给建议——纯事件路由处理不了这类上下文。\n\n## 配套代码\n\n- `chapter6/async-agent/` — 实验 6-2：事件驱动异步 Agent 框架（Flux），并行工具、打断取消、检查点持久化，含零依赖离线 demo。\n- `chapter6/agent-with-event-trigger/` — 实验 6-1：FastAPI 事件驱动 Agent + 42 个 MCP 工具，演示\"事件到达 → Agent 处理 → 结果输出\"最小闭环。\n- `chapter6/async-agent/` 同时给出离线验收 demo（并行 vs 串行墙钟时间、打断取消后恢复、检查点持久化与还原）与 LLM 场景复现两条路径，适合先跑离线 demo 验证运行时再上真实模型。\n- `chapter6/astra-async-steering/` — 实验 6-3：GPT-6 Astra 原生异步工具调用与回合中途引导，含 `sync` / `async` / `steer_reasoning` / `async_steer` / `unsupported_steer` 五组对照与真实 API 运行记录。\n- 语音相关（时间尺度更细的\"可打断\"场景）：`chapter6/end-to-end-speech/`、`chapter6/streaming-speech/`、`chapter6/controllable-tts/`、`chapter6/live-audio/`、`chapter6/phone-agent/`。\n- 机器人相关（毫秒级连续观察与动作分块）：`chapter6/gemini-xlerobot-navigation/`、`chapter6/rgb-sim2real-grasping/`、`chapter6/xlerobot-teleoperation/`。\n\n## 深度阅读\n\n- `book/chapter6.md`「模态与触发时机的扩展」\n- `book/chapter6.md`「异步与事件驱动：当世界主动找上门」\n- 相关设计文档：`chapter6/async-agent/agent_framework_design.md`（Flux 框架的运行时设计）\n","skills/agent-evaluation/SKILL.md":"---\nname: agent-evaluation\ndescription: 为 Agent 建立或改进评估体系时使用——设计评估指标（Pass@k/Pass^k/成本）、搭建可重复运行的评估环境、选择确定性验证器或 LLM-as-a-Judge 及各自适用边界、编写 Rubric、做失败归因与回归任务、评估驱动的模型选型、判断统计显著性、建设可观测性与内部评估基础设施（消融、AB 测试、特性开关、提示词回归）、从 Benchmark 报告走到系统改进。\n---\n\n# Agent 评估体系\n\n## 何时使用\n- 为 Agent 系统建立第一套评估，或审查现有评估是否可信\n- 选模型、换模型前需要数据依据（新模型公开分高，不代表在你的任务上更好，甚至可能回退）\n- 评估分数下降，要判断是 Agent 退化还是评测系统本身出了问题\n- 需要把\"成功率下降\"这类笼统结论拆成可着手修复的具体问题\n- 为生产 Agent 建设内部评估基础设施：消融实验、AB 测试、特性开关、提示词回归\n- 设计可观测性与生产轨迹回流，让评估集随产品持续演化\n\n## 核心原则\n- **评估的对象是\"模型 + Harness\"组合体，不是模型本身。** 同一模型在不同 Harness 下表现悬殊；表现不佳时先怀疑 Harness，再怀疑模型。\n- **用模型替换实验（model swap）区分两类问题**：固定 Harness 只换模型，分数不涨 → 瓶颈在 Harness；分数随模型能力大幅波动 → 瓶颈在模型能力。消融实验则是关闭 Harness 组件、定位内部哪个部件重要，两者互补，别混用。\n- **先检查评测系统，再动 Agent。** 分数下降先排查：运行环境资源不足导致的随机失败、验证器 bug 把对的判错、用例与生产脱节——这些在数字上与模型退化一模一样，只有回放完整轨迹能区分。\n- **指标口径由业务场景决定。** 同一个 0.8，对退款客服意味着每五名用户一人拿不到退款，对漏洞挖掘已属可观。报告必须写清 k 的口径：同一任务的 k 次独立采样，还是生产流水线连续 k 个任务。\n- **凡是能写成程序化断言的检查就用断言**，LLM 评判只用于确实无法机械判定的维度。确定性验证更便宜、更可复现，适合长期进 CI。\n- **分差要超过噪声、在配对分析中成立、并且能够复现，才值得据此切换模型或发布改动。**\n- **一轮证据只支持与它规模相称的下一步。** 子集 4/4 不能写成系统整体 100%，完整复测通过前不部署。\n\n## 实践模式\n\n### 1. 指标设计：Pass@k / Best@k / Pass^k\n- **Pass@k**（k 次至少一次通过）与 **Best@k**（连续得分取最好）衡量能力上限，适合科研发现、漏洞挖掘、开放式创作——人类会从 k 条候选轨迹里挑出最好的那条。\n- **Pass^k**（连续 k 次全部通过，且不触发安全、合规、幻觉等一票否决项）衡量业务可靠性，适合支付、退款、权限变更、生产部署。两者关系：Pass@k = 1-(1-p)^k，Pass^k = p^k。\n- p=0.6、k=5 时：Pass@5 ≈ 99%，Pass^5 ≈ 7.8%——前一个数字回答\"能不能偶尔创造奇迹\"，后一个才回答\"能否稳定交付\"。\n- 会产生副作用的操作不能\"重试直到成功\"：应在沙盒或可回滚环境中采样，每一次失败都记入可靠性指标。\n\n### 2. 评估环境五要素\n- **数据集**：初始状态、给 Agent 的输入、给模拟器的行为规范与验收标准，打包为一条记录即一个用例。\n- **环境状态**：必须可重置（`initialization_actions` 即重置脚本）；真实性（变化符合业务逻辑）与可控性（每次回到同一起点）兼得。\n- **工具接口**：两侧工具均为原子操作；抽象层次过高（如一个\"解决用户问题\"工具）会使评估退化为对单次函数调用的考察，规划与推理被工具本身吸收。\n- **评分标准**：分层检查项 + 明确的聚合规则（如 `reward_basis`）。\n- **执行协议**：终止信号、轮数上限、模拟用户耐心耗尽主动结束（沟通效率过低本身即计为失败）。\n- 按任务形态选环境类型：单轮问答用无状态单轮环境；搜索+综合用多轮工具环境；改数据库验状态用有状态环境；跑代码查输出用沙盒环境。并行采样与轨迹缓存是标配；工具失败应返回清晰错误信息而非单一失败标志，让 Agent 能据此调整策略。\n\n### 3. 验证方式谱系与自动化评估\n- 横轴是**可机械验证程度**：确定性断言 → 检查项清单 → Rubric + LLM-as-a-Judge → 配对比较。向右移动不意味着放弃左侧。\n- 确定性验证只能判对错、不给原因；生产系统最需要的恰恰是\"错在哪、下一步改什么\"。开放式任务（报告、投诉、创意）无唯一终态、人工评估不可规模化，才上 LLM 评判。\n- **Rubric 四准则**：基于专家指导（捕捉核心事实与推理步骤，而非语言流畅度）；全面覆盖（事实、逻辑、完整性、安全性，且明确 Pitfall）；按重要性加权（必要/重要/可选/陷阱，支持一票否决，如幻觉出现总分归零）；评价标准自包含（禁\"展示深刻理解\"，改为\"引用了至少两个权威理论并准确解释\"）。\n- 每个维度给客观可验证的评分档次、具体示例与边界案例；显式防范奖励作弊（幻觉、讨好用户、关键词堆砌、回避棘手问题）。\n- **长度偏差**防范：Rubric 显式惩罚冗长、规定同类任务长度上限；配对比较前把候选长度控制到相近；定期审计评分与长度的相关性——高分几乎总伴随长回答即已被带偏。\n- **同源模型问题**：Agent 与评判模型同家族时，Agent 会学会利用评判模型的偏好与盲点（古德哈特定律：度量成为优化目标后就不再是好度量）。换不同家族模型评判，并让 Rubric 随分歧持续迭代。\n\n### 4. 失败归因：把 0 分变成可修复的问题\n- 归因对象是轨迹中**首个**导致任务偏离的错误；后续错误多是连锁反应，不能把最后一条报错当根因。\n- 问题案例三来源：用户明确纠正、用户点踩/负面反馈、事后状态检查/规则验证器/LLM 评审发现 Agent 做了不该做的事。\n- **静默失败**（无任何工具报错、Agent 自行宣布完成）的两把定位工具：事实锚点比对（把 Agent 陈述与工具返回值逐步对齐，取首次背离）；轨迹前缀二分（截到第 k 步交人接手，能救回说明错误在 k 之后）。不能用搜报错关键字代替。\n- 归因记录结构化（JSON/YAML）：含任务名、首错步号、错误类别、责任方、原文证据、置信度，区分主因与后果（三次重试是后果，不是三个根因）；多类别并存时按\"最早且能解释后续失败\"选主因。\n- **规则先筛、LLM 再定位**比全量喂 LLM 更便宜也更准：完成声明与实际执行命令的交叉核对、diff 是否触及测试断言与 skip 标记、diff 是否改公开 API/schema 而无迁移，这三类可先用规则筛出嫌疑轨迹。\n- 警惕\"做对了但说错了\"：工具调用和环境状态全对，告知用户的信息却错。只检查终态的评估会整体掩盖它（τ²-bench 基线中约三分之一失败属此类）。根因归属要判到层：观察通道缺失不是\"模型不会 OCR\"。\n- 保存归因记录时，连同任务目标、环境状态、Agent 版本、工具集版本和完整轨迹一起存，供回归测试使用。\n\n### 5. 两层回归任务\n- **端到端回归**：从初始状态跑到终态，验最终状态、必要输出、安全条件。最接近生产结果，但难以定位失败步骤。\n- **轨迹前缀回归**：冻结首错之前的上下文、对话、工具返回与环境状态，只要求下一步或下几步可观察动作。成本低、能隔离单个策略问题；对高可靠生产 Agent，其重要性往往超过端到端口径。\n- 前缀回归答案定义为**可接受动作集合**（\"先读仓库规则\"\"先询问用户\"\"拒绝危险操作\"）+ 禁止动作，而不是唯一标准答案。\n- 按错误类别生成回归任务：流程缺失 → 带计划文档与测试验收条件的端到端任务；工具调用错误 → 截断出错前缀编辑成边界任务；信息反馈类 → 对答复内容本身设断言，而非只查环境状态。\n\n### 6. 评估驱动的模型选型\n- 延迟分两阶段：Prefill 决定首字延迟（TTFT = 排队 + 预填充），Decode 决定出字速度与思考时长（50 tokens/s 生成 2000 思考 token 要 40 秒）。看 p95 尾部延迟而非均值。\n- 在自己工作负载上实测各模型的思考 token 用量与对应收益，不凭公开榜单推断。\n- 成本算**每个任务的平均成本**与成本-性能比：便宜但成功率低的模型因频繁重试可能更贵；输入/输出/缓存 token 分开计价。\n- 指标按场景取：日常 Pass@1，关键操作 Pass^k，探索性任务 Pass@k / Best@k。\n- **预算—能力曲线**：除成功率，报告性能随墙钟时间、token、工具调用次数或算力预算变化的曲线；短预算领先不能外推长时运行能力（RE-Bench：2 小时预算最佳 Agent 约为人类专家 4 倍，8 小时人类反超）。\n- **行为策略也是选型维度**：同一中性 Harness 下测\"行动阈值\"（首次修改前的工具调用数与阅读文件数）。换模型行为改变、同模型跨 Harness 保持倾向 → 支持模型效应，反之支持 Harness 效应；工具步数、并行调用、模型延迟必须分开看。工具步数不是质量分。\n- 异构模型组合（轻量模型管简单、强模型管复杂）必须用评估验证整体效益超过所增复杂度，并检查特定场景是否回退。\n- 成本优化（KV Cache 稳定前缀、上下文压缩、分层选模型）每项独立开关，且**合用时在完整任务中一起实测**——各自节省比例不能相加（28.3% 与 17.5% 合用只有 30%）。\n- 建实时成本监控：按任务类型/模型/用户维度追踪 token 与费用，设单任务成本上限，Agent 陷入循环时自动终止。\n\n### 7. 统计显著性\n- 标准误 SE(p) ≈ √(p(1-p)/n)：100 个用例、成功率 70% 时 95% 置信区间约 ±9 个百分点，\"新模型 73% 对旧模型 70%\"不足以支持切换。\n- 同一批任务比较两个配置用**配对分析**：逐题记录谁胜出，McNemar 检验或配对 bootstrap，不要相减两个独立成功率。\n- 每个配置跑 3–5 个随机种子，报告均值与波动范围；单次运行只能用来筛选方向。\n- 预期收益只有 2–3 个百分点而评估集只有几十题：先扩大样本，标准误按 1/√n 缩小。\n- 并行验证多个假设时考虑**多重比较**：收紧显著性阈值，或对正向结果做独立复跑。\n\n### 8. 可观测性\n- 数据基础是 **trace/span 树**：一次任务执行一条 trace，每个 LLM 调用、工具调用、检索是一个 span（记录输入输出、起止时间、token 消耗、错误），父子关系构成执行树。\n- 采用标准协议（OpenTelemetry + OpenInference 等语义约定）保持采集与分析解耦，避免被单一平台锁定；采集异步批量进行，不拖累响应延迟。\n- 追踪的四大价值：问题诊断（回放而非猜测）、持续优化（定位低成功率工具与空结果检索）、成本管理（识别异常高成本案例）、后训练数据基础。\n- 最有价值的去向是**回流**：生产轨迹筛失败与可疑案例 → 脱敏（去隐私、密钥）→ 沉淀为评估集新用例与回归测试。评估集是随产品演化的活资产，不是一次性静态集合。\n\n### 9. 内部评估基础设施（生产级）\n- **消融**：每个主要特性可独立关闭，定期（如每次大版本发布前）跑消融，发现\"特性债务\"——曾经有效但随模型进化已不再必要的特性。消融开关要在启动路径极早期注入，事后加装不了。\n- **AB 测试**：多臂而非二元（揭示剂量-效应关系，找到最优点）；**区分机制指标与目标指标**（缩短计划文件长度是机制，降低会话级成本才是目标，别把机制当目标，计划过短可能引发更多编辑-检查循环反而更贵）；设护栏指标（满意度、操作次数、错误率不能变差）；记录基线统计（样本量、百分位数、相关性），否则无法判断显著性。\n- **双层特性开关**：编译时开关（代码物理移除，本身即干净的消融机制）+ 运行时开关（服务端下发、本地缓存、宁可稍旧也不能阻塞启动；每个特性曝光事件每会话最多记一次）。特性开关是一等架构组件，服务实验、渐进发布与紧急熔断。\n- **提示词敏感性**：系统提示要能确定性渲染（相同配置输入永远产出相同文本）；建立版本化快照；每次提示词变更在评估集上跑回归，像代码过 CI 一样。\n- **隐私感知分析**：分析接口只接受特殊类型包装的值，类型名即审计线索；隐私约束从第一天设计进去。分析系统无法安全收集数据，评估就无从谈起。\n\n### 10. 从 Benchmark 报告到系统改进的闭环节奏\n- 读报告先找失败集中在哪些任务与能力上，再回放轨迹分清问题出在**看、想、做、验**哪一环；别只盯总分（88% 总分很容易埋掉一个集中的失败簇）。\n- 每轮只改一个变量，形成假设链：加提示词无效 → 换输入通道有效但太贵 → 精简输入保住成功率且降成本。提示写得再详细也补不回 Agent 没看到的信息；输入也不是越多越好。\n- 小范围通过只获得扩大测试的资格：标准环境、全任务 × 多种子，同时查成功率不降、token 不超阈值、延迟不超上限，才能讨论部署。\n\n## 常见陷阱\n- 看到分数下降就改 Agent 代码，不先排查评测系统（资源不足、验证器 bug、用例脱节都会伪装成模型退化）。\n- 用公开基准分数直接做产品决策——GAIA 上提升两个百分点与退款成功率没有必然关系。\n- 把最后一条报错当根因；或把根因归错层（观察通道缺失被记成\"模型不会 OCR\"，于是去换模型、做 OCR 训练）。\n- 只检查环境终态，漏掉\"做对了但说错了\"。\n- Rubric 写\"展示深刻理解\"这类不可验证的抽象标准；没有一票否决项，被关键词堆砌式奖励作弊刷分。\n- 评分从未审计长度相关性，评判已被长度偏差带偏而不自知。\n- 同源模型既当运动员又当裁判，Goodhart 之后评分虚高。\n- 把多项上下文优化的节省比例直接相加；或凭单次运行的结果做选型决策。\n- 配对比较不交换候选顺序，位置偏差让先出现者系统性占优。\n- 子集小样本通过后直接当整体水平汇报，结论超出证据规模。\n\n## 配套代码\n- `chapter7/tau2-bench-eval/` — τ²-bench telecom 五任务双控环境评估：环境 reset、轨迹保存、二元奖励与失败任务（错选线路漏做充值）分析\n- `chapter7/android-world/` — T3A 运行记录、失败归因笔记，以及 diagnose→hypothesize→experiment→decide→iterate 的五阶段改进闭环\n- `chapter7/public-health-reporting-eval/` — 合成数据上的确定性六点评分：工具选择、参数、答案、证据行、无依据声明处罚\n- `chapter7/agent-cost-analysis/` — 八轮退款任务全链路成本拆解，KV-cache 友好与上下文压缩的 2×2 A/B 量化\n- `chapter7/model-benchmark/` — 多维度模型基准 campaign：吞吐/TTFT/尾延迟、168 小时可用性、限流爬坡、同模型不同供应商对照\n- `chapter7/model-action-threshold/` — 固定 Coding Harness 下测量不同模型的行动阈值（首次修改前的工具调用与文件阅读）\n- `chapter7/elo-leaderboard/` — 从 Chatbot Arena 真实投票实现 Elo/Bradley-Terry 配对排名与历史快照\n\n## 深度阅读\n- `book/chapter7.md`「评估指标：成功的定义」\n- `book/chapter7.md`「评估环境」\n- `book/chapter7.md`「自动化评估方法」\n- `book/chapter7.md`「评估驱动的模型选型」\n- `book/chapter7.md`「评估结果的统计显著性」\n- `book/chapter7.md`「Agent 的可观测性」\n- `book/chapter7.md`「从 Benchmark 报告到系统改进」\n- `book/chapter7.md`「从外部评估到内部评估：生产级 Agent 的评估基础设施」\n","skills/agent-evolution/SKILL.md":"---\nname: agent-evolution\ndescription: 让 Agent 从运行经验中持续学习、构建自进化闭环时使用——涵盖从运行轨迹提取学习信号（三层轨迹验证）、四种进化方式（经验知识库、Prompt/Skill、程序/Harness、模型参数）的适用边界与选择依据、Prompt 自动优化、轨迹编译为程序、Agent 自我修改与安全门禁、睡眠学习与长期分层评估。触发词：持续进化、自进化、经验学习、轨迹验证器、自我修改、进化闭环。\n---\n\n# Agent 持续进化\n\n## 何时使用\n\n- 部署后的 Agent 反复犯同类错误，需要把运行经验转化为持久能力\n- 需要为运行轨迹构建验证器 / 评价器，判断\"哪里错、为什么错、证据在哪里\"\n- 面对一个待修复缺陷，需要决定经验应写进知识库、Prompt/Skill、程序还是模型参数\n- 要做 Prompt 自动优化、失败轨迹规则提炼、浏览器轨迹转工作流等单点进化\n- 设计 Agent 自我修改流程（改自身 Harness、工具、重试策略），需要验证与发布门槛\n- 搭建\"在线执行 + 离线进化\"双循环，或设计记忆/Skill 的整理、淘汰与回滚机制\n- 评估系统是否真的在进化（而非只保存或只追加反馈）\n\n## 核心原则\n\n- **保存经历 ≠ 从经历中学习**。学习发生在系统主动完成\"评价、对照、归纳、验证\"之后，而非日志写入磁盘的那一刻。一百条轨迹放进向量库只是可检索案例，不自动完成跨案例比较。\n- **先评价再更新**。不知道任务是否完成、哪一步导致成败，模型的反思只是猜测。评价一条轨迹依次回答三问：事情是否办成（结果）、是否以允许的方式办成（过程）、是否让用户舒服（质量）。\n- **三层验证，底层优先**。结果验证器读环境真值（测试、数据库、工具返回），最应优先建立且比模型自述可靠；过程验证器用政策库/权限表/动作序列做代码判定；质量层才用 LLM Rubric。结果正确不代表过程正确（删掉失败用例也能让测试通过）。\n- **学习信号必须四要素齐备**：成败判定（成功/部分成功/失败）、每维度结论、每条结论的证据位置（哪轮对话、哪次工具调用）、失败类型标签。单一总分无法指导更新；证据不足时验证器应拒绝评分，低置信度案例排除在学习集外。\n- **按能力的表示性质选择载体**（表 9-2 的边界）：\n  - 经验知识库——事实、经验规律、例外与来源；更新快、可追溯，但依赖检索和模型正确应用\n  - Prompt/Skill——能用自然语言说清的判断原则、语境与例外；可解释、范围可控，但易膨胀、冲突、被忽略\n  - 程序/Harness——可确定性解析、可执行验证、高风险硬约束；可测试、稳定、低成本，但开发维护成本高\n  - 模型参数——高维感知、生成风格、隐式策略；泛化强、推理开销低，但更新与回归成本高\n- **同一能力可拆到多个载体**：事实入知识库，解释例外的原则入 Skill，不可绕过的权限由程序门控，高维识别能力入参数。路由结果只是更新提案，尚无发布资格。\n- **经验知识库 vs 领域知识**：第三章领域知识回答\"用户与世界是什么样的\"（如\"该航司特殊餐食需提前 24 小时预订\"）；本章经验知识库从行动轨迹与结果中提取\"在什么条件下应该怎样做\"（如\"订票前先检查特殊餐食截止时间\"）。二者共享存储与检索技术，来源和验证目标不同。\n- **所有修改是最小 diff + 可回滚 + 独立验证**。待验证版本必须同时在触发失败的边界集上改善、在正常工作的保留集上不退化；验证者须独立于提炼者。\n- **在线执行与离线进化分离**。在线循环只完成任务并追加不可变证据，不直接改写正式 Agent；离线循环聚合轨迹、生成提案、过门槛发布，两者经版本化经验库和评估集连接。一次偶发成功或恶意输入不能立即改写长期能力。\n- **安全边界三条**：证据与指令隔离（网页/工具输出及其 LLM 摘要都是不可信证据，LLM 摘要不是净化过程）；待验证能力与正式能力隔离（新产物先入不可服务真实流量的待验证区，过沙盒、权限、供应链扫描与回归后才转正）；安全机制不可自我修改（Agent 不能改验证器、测试、发布门槛、审计日志和稳定版本备份——否则降低阈值即可把退化伪装成进步）。\n- **Harness 更新能力 ≠ Harness 受益能力**。前者是从轨迹产出有价值修改，后者是任务 Agent 在正确场景激活并遵循该修改。不能用端到端分数反推更新器好坏，需分层评估。\n\n## 实践模式\n\n### 1. 轨迹验证器（学习信号的来源）\n\n- 三层结构：结果层读最终环境状态；过程层查业务规则、隐私、事实依据、承诺—行动一致性（声称完成的操作是否真实发生）；质量层按 Rubric 逐项给分并引用轨迹证据。\n- 输出结构化诊断而非总分：每维度结论 + 证据轮次 + 置信度，失败带类型标签。\n- 低置信度案例不进学习集；把它当事实固化比丢弃更危险。\n\n### 2. 经验知识提炼管道（五步）\n\n1. 保存不可变原始轨迹与环境结果（用于审计）；\n2. 为单次运行生成结构化分析：任务类型、所需能力、观察到的策略、错误与例外；\n3. 按任务族聚合同类运行，为每条经验草案建\"哪些轨迹支持、哪些轨迹反驳\"的证据表；\n4. 达到支持门槛才写入正式文档；\n5. 在未参与提炼的新任务上测迁移效果。\n\n正式经验文档写：适用场景、推荐策略、禁止做法、例外条件、证据来源、最近验证时间——不复述某次任务的完整过程。真正有迁移价值的内容来自对照（成功轨迹做了什么、失败轨迹缺少什么、策略在哪些版本/前置条件下失效），Reflexion 式自然语言反思可参与生成草案，但反思本身不是证据。\n\n### 3. 经验写成 Prompt/Skill（指令更新）\n\n- 触发条件：多条相似轨迹反复暴露同一种策略错误，且错误能用语言清楚描述。\n- 形式：带来源的最小 diff（`old_str → new_str`），不让模型每轮重写整份 Prompt——重写会丢细节、把相互制约的条件合并成过度抽象的原则。可参考 ACE：上下文维护成带稳定标识符的条目集合，增量更新 + 确定性合并去重。\n- 发布门槛：补丁非空、来源可追溯、保留集不退化、边界集确有改善；通过才灰度（`release_to_canary`），否则拒绝。待验证补丁写入 working 文件，不覆盖正式 Prompt。\n- Skill 与 Harness 边界：Skill 负责理解语境、提问、整理 Spec；Harness 负责缺少确认时否决高风险写入。否决器不替模型决定方案。\n- 提炼输入决定归纳质量：给失败摘要+报错文本，模型只归纳出教训；补充 Agent/用户各自的工具清单，才能归纳出职责归属。\n\n### 4. 经验写成程序（程序化经验）\n\n- 浏览器工作流六步生命周期：捕获轨迹（保存动作参数、URL、元素定位证据——定位信息只能用于再找元素，不能证明任务完成）→ 参数化（字面量换模板变量）→ 定义状态检查（动作前/后检查 + 最终状态检查，最终检查必须读真实页面或后端状态）→ 独立回放验证（沙盒/测试站点重置到独立初始状态后完整回放，全部谓词通过才发布）→ 匹配与回放（能力库按意图检索，直接执行，无需逐步调 LLM）→ 失效与重学（谓词失败、Schema 变化即回退完整 Agent 模式）。\n- 自我修改走软件发布流程，而非运行中进程覆盖自身：从稳定版本切隔离 worktree → Coding Agent 生成最小补丁 → 静态检查、单测、安全扫描、失败轨迹重放、旧任务回归 → 可灰度新版本。每次修改请求是一份可证伪的变更契约：失败证据、推断根因、归属组件、修改提案、预期修复的行为、可能受损的行为、分别验证两者的用例。\n- 提案生成器的输入不只有失败案例，还必须有成功约束（不能破坏的性质）和此前被拒记录（避免换说法重复提交），共同构成有边界的方案空间。\n\n### 5. 经验写入参数\n\n- 判断依据不是\"任务是否长期稳定\"，而是能力的表示性质：能否被外部符号较完整表达。域偏移用 LoRA/持续微调，快速变化的风格用周期性偏好训练。\n- 数据来源：经评价的生产轨迹——高质量示范进 SFT，明确偏好形成成对数据，有可靠环境奖励的交互用于 RL。\n\n### 6. 双循环与睡眠学习\n\n- 离线整合五步：触发（时间/轨迹量/容量/错误频率门槛，且无高优先级在线任务）→ 定向（读正式知识、Skill 目录及版本，了解不可修改边界）→ 采集与整合（合并重复、标记冲突与适用条件，优先生成局部补丁）→ 验证与审批（迁移集/保留集/安全集，高风险等人工批准）→ 修剪与索引（长期不用或被推翻的标记过期、归档，保留来源与回滚版本）。\n- 定期对抗上下文腐化：合并重复经验、把局部规则从全局 Prompt 移入领域 Skill、重验长期未用的工具、删除被推翻的知识、从原始基座重训 LoRA。\n\n### 7. 进化效果的分层评估\n\n- 指标（表 9-3）：更新提案有效率（独立验证中的接受率与增益）、产物激活率（是否正确场景加载）、遵循成功率（动作序列与过程验证器）、保留任务集增益（未参与进化任务的成功率/质量/成本）。\n- 长期评价至少五类：回退（新旧经验冲突）、泛化（测试集外场景）、Token 效率、安全性（规则/隐私/拒绝边界是否漂移）、长期工程质量（维护复杂度、向后兼容、调试负担）。\n- 开放式任务（科研、战略）反馈慢且答案不唯一，需改变证据结构：结论与证据分离（每类声明链接可审计来源）、保留负面结果与停止原因、维护搜索多样性（不全押当前最高分）、让人类在更高层介入（定义问题、审查评价标准、决定何时停止）。\n\n## 常见陷阱\n\n- 把用户满意度或单一总分当学习信号：满意度上升可能伴随规则违规率上升，需护栏指标。\n- 把低置信度结论当事实固化，或把 LLM 摘要当无害化后的指令直接纳入 Skill。\n- **模型会把观察到的行为当作应然的行为**：轨迹中最频繁出现的是转人工，模型就可能把\"三次失败即转接\"写成规则——而该环境下转接必然失败，等于把失败写进规范。提炼产物必须经与提炼者独立的验证。\n- 让模型每轮重写整份 Prompt/记忆，导致重要细节在多轮改写中消失。\n- 把\"动作执行过\"当\"任务完成\"：没有最终状态检查的回放，只是把错误更快地重复。\n- 待验证版本直接发布，或发布门槛可被提案自身修改（安全门不能由修改者自证）。\n- 只修当前失败案例，不顾保留集回退、泛化、Token 成本和长期工程质量。\n- 只追加不淘汰：知识无限增长引发检索错误、知识冲突、灾难性遗忘，抵消学习收益。\n- 用端到端分数判断更新器好坏，忽略激活率与遵循失败。\n- 提案被接受 ≠ 下游能力提升：一次提案通过只证明更新流程成立，仍需在相同任务和模型下做开关消融。\n\n## 配套代码\n\n- `chapter9/trajectory-verifier/` — 实验 9-1：三层轨迹验证器，对比单一总分与带证据的多维诊断\n- `chapter9/tau2-escalation-experience/` — 实验 9-2：从 τ²-bench telecom 失败轨迹提炼转人工与工具使用规则，三臂对照\n- `chapter9/prompt-auto-optimization/` — 实验 9-3：航空客服失败轨迹 → 三维诊断 → 最小 Prompt diff → 发布门槛\n- `chapter9/ai-style-skill/` — 补充案例：用户\"AI 味\"before/after 纠正持续提炼为写作 Skill，LLM judge + 金标校准\n- `chapter9/browser-use-rpa/` — 实验 9-5：浏览器轨迹编译为带状态谓词的待验证工作流，独立回放后才入能力库\n- `chapter9/self-modifying-agent/` — 实验 9-6：由失败轨迹触发重试/熔断代码自我修改，Docker 沙箱验证提案\n- `chapter9/harness-safety-gate/` — 实验 9-7：用户反馈触发高风险操作确认门禁，AST 扫描 + 隔离回放\n- `chapter9/hermes-self-evolution/` — 实验 9-8：Hermes 读本书后自主选题、修改自身并接受独立 Reviewer 审查\n- `chapter9/self-evolution-eval/` — 实验 9-9：四阶段纵向评估（学习/迁移/规则变化/保持），区分保存、追加与可淘汰记忆\n- `chapter9/self-evolving-tools/` — Alita 式补充案例：Agent 从零搜索、沙盒测试并封装新工具入库复用\n\n## 深度阅读\n\n- `book/chapter9.md`「从运行轨迹中获得学习信号」— 三层验证结构与学习信号四要素\n- `book/chapter9.md`「Agent 持续进化的四种方法」— 知识、指令、程序、参数的适用边界与各自流程\n- `book/chapter9.md`「构建可长期运行的持续进化闭环」— 双循环、睡眠学习、分层评估与安全边界\n","skills/computer-use/SKILL.md":"---\nname: computer-use\ndescription: >-\n  构建 GUI 自动化 Agent、让 Agent 像人一样看屏幕并用鼠标键盘操作桌面或浏览器软件时使用。\n  覆盖感知-思考-行动循环、动作空间（GUI/bash/文件编辑）、视觉定位 Grounding 三条路线\n  （结构化元素索引、Set-of-Mark、纯坐标预测）、分辨率坐标缩放、关键帧观察接口、世界模型与移动端生态壁垒。\n  触发词：Computer Use、GUI 自动化、截图、Grounding、browser-use、Set-of-Mark、视觉定位、坐标缩放、OSWorld。\n---\n\n# Computer Use：GUI 自动化 Agent\n\n## 何时使用\n\n- 要让 Agent 操作没有 API 的软件：填表、改系统设置、在网页上完成多步流程。\n- 要评估或实现\"截图 → 决策 → 执行动作\"的闭环，选模型、选 grounding 方案、选框架。\n- 定位不准、坐标偏移、点击错元素，需要排查 grounding 与坐标缩放链路。\n- Agent 每 3–5 秒才看一眼屏幕，错过通知、视频、弹窗等\"两帧之间发生的事\"。\n- 要把 Computer Use 扩展到移动端（Android 无障碍服务）或评估平台封禁风险。\n- 设计不可逆操作（删除、购买、提交）前的确认与安全边界。\n- 要减少操作步数与等待时间，让 Agent 达到\"实用\"而不只是\"答对\"（对照 OSWorld-Human 的人类基线）。\n- 没有编程 API 可用、Selenium 之类脚本化方案难以维护页面的场景。\n- 要在容器化虚拟桌面中跑 Agent，并隔离不可逆操作对真实环境的影响。\n\n## 核心原则\n\n- **核心是感知-思考-行动循环**：截图 → 多模态模型输出思考 + 一个动作 → 执行层真实执行（移动鼠标、点击、输入）→ 等界面响应再截图进入下一轮。\n- **区分\"看懂界面\"和\"完成任务\"**：前者可用一次截图问答测量（多模态理解）；后者要求把理解和动作放进闭环，处理页面加载、状态变化、误操作和不可逆后果。每执行一步都要**重新确认现实是否仍符合计划**。\n- **动作空间分三类**：GUI 操作（鼠标移动/点击/拖拽/滚动、键盘输入/组合键/长按、截图与等待）、持久 bash 会话（跨调用保持环境状态，用哨兵字符串判命令是否执行完）、字符串匹配的文件编辑（比整文件覆盖更精确，可撤销）。\n- **动作空间不是供应商私有协议**：只要 Harness 能把同样的截图、动作约束和执行结果转换成目标模型支持的消息与结构化输出，Claude、开放权重视觉模型和自托管端点都能驱动同一个循环。\n- **Grounding 优先把定位变成选择题**：先给元素编号，模型只报 ID，系统换算中心坐标。选择题比填空题容易答对——模型说\"点击 [123]\"而不是\"点击 (350, 464)\"。三条路线按界面性质选：\n  - **结构化元素索引**（DOM / Accessibility Tree，browser-use 路线）：结构化信息可得时首选，最精确稳定，无分割模型的漏检误检。\n  - **Set-of-Mark 视觉标注**：用分割模型切候选区域叠加编号，不需要 DOM，原生桌面软件、游戏、Canvas/WebGL 界面适用。\n  - **纯坐标预测**（SeeClick、Claude computer use）：直接在 GUI 截图-坐标配对上训练的模型更直接，省去标注步骤，但小元素和密集界面精度差。\n- **坐标预测必须做分辨率管理**：模型对坐标的理解依赖训练分辨率，不匹配就系统性偏移。按**宽高比**选最接近的目标分辨率做双向缩放（如 2560×1440 的 16:9 屏幕选 FWXGA 1366×768，模型返回 (683,384) 反推真实坐标约 (1280,720)）。切忌非等比拉伸把画面压扁。\n- **\"屏幕是静止的\"是危险假设**：该重新设计的是观察接口而不是动作接口——用关键帧截图（小模型判断是否有意义的变化，变化频繁时约 1 秒一次）、音量门控的语音转写、把截图压成一句持久文字描述来压缩多模态历史。\n- **世界模型带来\"推测执行\"**：行动前预测候选动作造成的状态差异，一致就沿计划继续，偏离才停下重规划。要预测的是**可检查的状态差异**（窗口、焦点、滚动位置、输入框内容、加载状态、权限、网络返回），不是生成逼真未来截图。\n- **生态壁垒是结构性问题**：Agent 直达目标会绕过广告与推荐变现链路，平台有动机封禁；这不只是 CAPTCHA 的技术对抗，短期难以调和。\n- **循环节奏与尺度**：Computer Use 的时间尺度是亚秒到秒——屏幕在两帧之间持续变化，因此\"动作后重新确认现实\"不是可选项而是循环的必要组成部分。这与语音（10ms–1s，可被打断）和机器人（毫秒级，动作分块可抢占）是不同的时机问题。\n- **结构化索引不省 token 但省错误**：把所有可交互元素及其属性发给模型成本高，但换来定位准确稳定，且免去分割模型的漏检误检——这是值得的交换。\n- **browser-use 式四步流程**：CDP 取 DOM 与无障碍信息 → 检测可交互元素 → 标注唯一 ID 并在截图绘边界框 → 同步生成\"ID → 元素描述\"文本列表；模型只输出 ID，系统用中心坐标执行。\n\n## 实践模式\n\n1. **搭循环**：Harness 负责截图、把动作约束转换成目标模型支持的消息与结构化输出、执行结果回传。同一套循环可换驱动模型（Claude、开放权重 VLM、自托管 vLLM/SGLang 端点），并保留实际端点与模型 ID 以便区分实验组。\n2. **选 grounding 路线**：先问\"这个界面有没有结构化信息可得\"——Web 走 DOM/a11y 索引（CDP 取 DOM → 检测可交互元素 → 标注唯一 ID 并在截图绘边界框 → 同步生成 ID 到元素的文本列表）；原生桌面软件、Canvas/WebGL、游戏走视觉标注或坐标预测；模型做过 GUI 定位训练才优先坐标预测。\n3. **实现坐标缩放层**：枚举目标模型支持的分辨率档位，按宽高比匹配；截图时等比缩放送入，动作坐标按比例反算回真实屏幕。\n4. **每步只做一个动作**：保留每步截图与动作轨迹，便于回放和验收；页面加载用 `wait`，不要盲点。\n5. **安全边界**：默认只读；不点击验证码、不登录、不提交、不购买、不改外部数据；不可逆操作先在隔离虚拟桌面预测是否出现确认框，必要时请求用户确认。凭证不落盘，最终截图要能佐证结论。\n6. **恢复策略要预置**：遇到验证码、权限弹窗、页面 404 时按只读恢复指令改走可达路径（如改用公开 JSON 接口取数据），而不是反复重试或点击挑战。\n6. **增强观察接口**：关键帧 + 音量门控 ASR + 文字描述三件套，让 Agent 对弹窗、视频、会议人声有感知，并让被清理出上下文的原图仍留下文字痕迹。\n7. **移动端适配**：动作空间从\"鼠标坐标 + 键盘\"换成无障碍服务 API（如 Android AccessibilityService）读写元素、下发点击与输入；坐标语义变为手势类型（单击/长按/滑动起点）的边界。\n8. **验收要测量效率**：准确率达到人类水平不等于实用——对照人类操作步数与等待时间，把\"步骤数、总时长\"纳入验收指标，并记录真实运行证据（截图哈希、动作轨迹）。\n\n## 常见陷阱\n\n- **把截图答对当成任务完成**：没有闭环、不重新确认现实，页面早已跳转还在点原来的坐标。\n- **非等比缩放**：把 16:9 硬塞进 4:3，画面横向压扁，坐标判断整体偏移。\n- **分辨率不匹配不换算**：直接把模型在训练分辨率下输出的坐标当真实屏幕坐标用。\n- **密集界面/小元素上裸报坐标**：三条路线在此都容易出错，优先编号选择题方案。\n- **分割模型漏检误检**：视觉标注路线里候选区域切错，模型只能从错的选项里选。\n- **每步多个动作**：中间页面变化无法回放定位，错误无法归因。\n- **假设屏幕静止**：两帧之间的通知、视频、声音全部丢失，任务在错误的世界观上推进。\n- **忽视平台封禁与验证码**：消费级场景中账号可能被直接限制，比技术问题更难解。\n- **只关注准确率不看效率**：步骤数和等待时间远超人类，成功也不可用。\n- **把不同模型的运行混为一组**：供应商与开放权重是不同实验组，必须分别记录端点、模型 ID 与证据。\n\n## 配套代码\n\n- `chapter6/claude-computer-use-native/` — 实验 6-8（Anthropic 原生路径）：容器化 Ubuntu 桌面中的官方 Computer Use Demo，`computer` / `bash` / 编辑器三类原生工具的真实运行与确定性验收记录。\n- `chapter6/computer-use-open-model/` — 实验 6-8/6-9（开放模型路径）：同一\"截图 → 结构化动作 → 浏览器执行\"循环，默认 Qwen3-VL 32B Instruct 驱动 browser-use，可接 OpenRouter 或自托管 vLLM/SGLang；含端点合格性契约（收截图、产出 Browser Use 动作 schema、每步一个动作、不静默替换模型）。\n- 两个 companion 都保留了真实运行证据（截图哈希、动作轨迹、确定性验收），可作为自己实现时的证据门禁模板；其中原生路径还记录了一次撞上 Google reCAPTCHA 后按只读恢复指令改走公开天气 JSON 接口、全程未点击挑战的完整轨迹。\n- 语音相关（同为\"时机\"扩展，可作对照）：`chapter6/end-to-end-speech/`、`chapter6/streaming-speech/`、`chapter6/controllable-tts/`、`chapter6/live-audio/`、`chapter6/phone-agent/`。\n- 机器人相关（从屏幕像素到物理传感器）：`chapter6/gemini-xlerobot-navigation/`、`chapter6/rgb-sim2real-grasping/`、`chapter6/xlerobot-teleoperation/`。\n- 移动端基准与评测可参考第七章 AndroidWorld 一节；本章 `chapter6/phone-agent/` 给出真实手机上的 Agent 驱动样例。\n\n## 深度阅读\n\n- `book/chapter6.md`「模态与触发时机的扩展」\n- `book/chapter6.md`「Computer Use：GUI 自动化 Agent」\n- 实验记录与证据门禁模板见 `chapter6/computer-use-open-model/` 与 `chapter6/claude-computer-use-native/` 的 README 与 `validation/` 目录。\n","skills/context-engineering/SKILL.md":"---\nname: context-engineering\ndescription: 设计 Agent 系统提示词、上下文结构或按需加载的 Skill 时使用——覆盖 API 消息角色与「静态前缀 + 轨迹」结构、系统提示词写法（结构化、SOP、业务规则细化、few-shot）、Agent Skills 渐进式披露与 SKILL.md 编写、提示注入的上下文层防御，以及注意力位置偏好等布局原则。\n---\n\n# 上下文工程总纲\n\n上下文是 Agent 在每个决策点实际「看到」的全部信息：系统提示词、工具定义、用户消息、模型回复、工具执行结果。上下文工程就是系统性设计、组织、供给这些信息——模型智力只是基础，**上下文质量才是 Agent 能力的真正关键**。一个中等能力的模型配上精心组织的上下文，往往胜过一个顶级模型在信息匮乏下的盲目摸索。\n\n## 何时使用\n\n- 设计或重构 Agent 的系统提示词、工具定义、消息列表结构\n- 编写 / 审查一份 `SKILL.md`（元数据、路由描述、正文分层）\n- 排查「Agent 行为不稳定、违反业务规则、重复犯错、忘记约束」\n- 决定哪些知识该进系统提示词、哪些该做成按需加载的 Skill\n- 评估外部内容（网页、文档、邮件）进入上下文后的安全风险\n\n## 核心原则\n\n- **API 无状态，上下文由框架每轮重建。** 模型不会「记住」上一轮，Agent 框架必须每次都把完整消息历史送回去。\n- **上下文 = 四种消息角色 + `tools` 字段。** `system`（开发者规则，通常只有一条且在最前）、`user`（终端用户输入）、`assistant`（模型回复含 `tool_calls`）、`tool`（框架执行结果，靠 `tool_call_id` 与调用关联）；工具定义走请求顶层 `tools` 字段，不是消息角色。\n- **静态前缀 + 动态轨迹。** system prompt 与 tool definitions 全程不变，对话历史（trajectory）随交互持续增长。所有后续技术都在优化这个列表的内容与结构。\n- **模型决策、框架执行。** 模型只发出工具调用请求，真正执行工具的是 Agent 框架；循环「请求 → tool_calls → 执行 → 送回结果 → 再请求」就是 ReAct 循环的 API 实现。\n- **最低信息需求三件套**：代码信息（结构、职责、规范）、流程规范（分支、提交、评审、CI/CD）、环境信息（配置、数据库、密钥管理）。缺哪一类，Agent 就在哪一类上出错。\n- **新员工检验法**：如果一个聪明的新员工读完你的系统提示词还不知道该怎么做，Agent 也一样不知道。\n- **上下文学习是检索而非推理**：模型擅长从已有内容中查找，不擅长在前向传播中归纳统计。位置偏好（Lost in the Middle）意味着开头和结尾注意力最高，中部易被忽视——关键信息放两端。\n- **与模型厂商的训练方法保持一致**：选择 Agent 交互模式时优先采用厂商专门训练过的模式（Skills、tool_search 等），同生态内表现最佳。\n\n## 实践模式\n\n### 1. 系统提示词四维度\n\n- **语气与风格**：用明确指令而非请求，如 `You MUST answer concisely with fewer than 4 lines`；无法完成任务时 `keep your response to 1-2 sentences` 且不要解释为什么不能做。大写（`NEVER do X`）比 `Please avoid doing X` 更能引起注意，但过度使用会稀释效果，只留给真正关键的约束。\n- **结构化**：Markdown 标题（`#`、`##`）提供人可读的层次，XML 标签提供机器可解析的精确语义（`<file_operation>`、`<network_request>`），标签名本身携带语义。双层配合：Markdown 管组织逻辑，XML 管语义边界。\n- **流程驱动而非规则堆砌**：写成带分支的 SOP（Step 1 Validation → Step 2 Classification → ... → Step 5 Verification），让模型任何时刻都知道自己在哪个阶段、异常时按阶段处理，而不是遍历上百条零散规则找匹配项。\n- **业务规则细化到可执行**：把模糊规则（「根据任务情况选择合适的计费类型」）改写成布尔判断，例如 `NEVER use percentage_based_one_time for refunds and service cancellations. Use fixed_fee instead.`；成功率阈值直接映射到行为（>60% 可退款、<30% 拒绝任务）；计费粒度写死（每分钟 $0.05，汇总四舍五入到整数美元），并明确「节省」只基于现有账单计算。**提示词由产品经理基于线上数据设计，工程师负责准确编码，不擅自决定业务逻辑。**\n\n### 2. few-shot 示例的两个决策点\n\n- **位置**：放系统提示词 = 成为静态前缀对所有请求生效；或伪造一组 user/assistant 消息放在首轮对话中，适合按会话类型选用不同示例集。\n- **稳定性**：无论放哪，示例都处于上下文靠前区域，一旦确定必须字节级稳定——按请求动态检索「最相关」的示例等于每轮改写前缀，缓存会持续失效。为每类任务准备固定示例集。\n- **数量**：两三个精心挑选、覆盖边界情况的示例，胜过十个大同小异的示例——后者既占上下文，又稀释对规则本身的注意力。\n\n### 3. Agent Skills：渐进式披露三层\n\n- **第一层 元数据**：`SKILL.md` 顶部 YAML frontmatter 的 `name` + `description`，在正文加载前对 Agent 可见，用于路由判断。`description` 要写得像路由条件而非功能介绍：明确「何时使用」「何时不使用」的边界，给几条典型反例。写 `help with backend` 这种宽泛描述等于任何后端工作都能触发，路由必然失准。\n- **第二层 核心流程**：模型判断需要该 Skill 时才加载完整 `SKILL.md`（斜杠命令由客户端本地拦截展开；模型自主触发则多一次 ReAct 往返，正文作为 user message 追加）。\n- **第三层 细则**：通过文件引用深入到子文档（如 `html2pptx.md`、`reference.md`），Agent 按需选择性深入。\n- **上下文成本**：所有 Harness 都遵循「少量目录常驻、完整正文按需加载」。Skill 正文在调用位置追加到轨迹末尾，不改写已建立的前缀，因此对 KV Cache 友好。\n- **SKILL.md 四部分**（宝玉《图解 Skill》）：角色与读者；核心原则只留 3–5 条并配正反例；禁止清单记录高频错误、越权动作并写清合法例外；参考资料放术语表、模板、范文。规则写成「作用域 + 动作 + 例外 + 验证方式」，不要堆成越来越长的禁用词表。\n- Skill 还可捆绑可执行代码工具和模板文件，自包含、可独立版本控制。\n\n### 4. 上下文布局决策骨架\n\n```python\nstable_prefix = system_message            # 定了就不改\nstable_tools  = core_tool_schemas         # 固定顺序\ntrajectory    = load_message_history(session)\nstatus_message = make_status_message(derive_current_state(trajectory))\n\nif estimated_tokens(stable_prefix, trajectory, status_message) > budget:\n    trajectory = compress_old_evidence(\n        trajectory, preserve=[decisions, constraints, failures, citations]\n    )\n\nrequest.messages = [stable_prefix] + trajectory + [status_message]\nrequest.tools = stable_tools\n```\n\n### 5. 提示注入的上下文层防御\n\n第一道防线是帮模型分清「指令」与「数据」：\n\n- **来源标记**：外部内容注入前用 `<external_content source=\"webpage\">...</external_content>` 包裹并标注来源。\n- **结构化角色**：严格用 system/user/assistant/tool 角色体系传递信息，绝不把工具结果混入 user 消息——那等于亲手抹掉模型辨别来源的依据。\n- **输入清洗**：过滤「忽略之前的指令」等常见注入短语，只能作辅助，易被措辞变体绕过。\n- **把 Skill 和状态栏也当注入面**：Skill 本质是「把外部内容当作指令加载」的制度化形式，安装来源不明的 Skill 前必须审查内容；状态栏信息被模型高度信任，若摘要来自可被外部污染的数据源，信任会被反向利用。\n\n## 常见陷阱\n\n- **把时间戳、用户余额等动态信息写进 system prompt**——每轮改写前缀，缓存全失效（详见 `kv-cache-design`）。\n- **规则堆砌而无组织结构**：实验 2-4 显示，保留全部规则内容但打乱组织、去掉标题层次，任务成功率下降超过 30%，Agent 经常违反关键业务规则。\n- **清空工具描述**：保留函数签名但移除描述性文本，工具调用错误率增加 45%。\n- **盲目追求语气风格**：风格显著改变表达方式，但对任务完成率影响相对有限，不必在此过度投入。\n- **示例逐请求动态检索**：缓存持续失效，且不同示例集导致行为不可复现。\n- **所有场景塞进一个系统提示词**：既浪费 token（大部分与当前任务无关），又稀释注意力——应拆成按需加载的 Skill。\n- **让模型在业务规则上自由裁量**：模型优势在于遵循复杂指令和从长上下文提取信息，模糊规则会让同一任务在不同时间得到不同分类。\n- **把上下文层防御当作万无一失**：它只能降低攻击成功率，权限控制、沙盒隔离、高风险操作独立审查是另一层。\n\n## 配套代码\n\n- `chapter1/context/` — 多 provider 上下文感知 Agent，消融实验 1-1 对比 full / no history / no reasoning / no tool calls / no tool results 五种上下文模式。\n- `chapter2/prompt-engineering/` — 实验 2-4：基于 Tau-Bench 的提示工程消融框架，量化语气风格、指令组织、工具描述三个维度对任务完成率的影响。\n\n## 深度阅读\n\n- `book/chapter2.md`「上下文：决定 Agent 能力上限的关键」\n- `book/chapter2.md`「Agent 如何调用大模型：理解 API 的上下文结构」\n- `book/chapter2.md`「提示工程：优化系统提示词」\n- `book/chapter2.md`「动态提示词与 Agent Skills」\n","skills/eval-dataset-design/SKILL.md":"---\nname: eval-dataset-design\ndescription: 设计 Agent 评估数据集或单条评估任务时使用——解剖评估任务的四个组成部分、设计验证器与验收标准（含防敷衍性修复）、划分任务难度与陷阱任务、防范训练/评估数据泄漏（参数化实例、canary）、建设评估集的质量控制与长期维护、选择公开基准/自建业务集/生产轨迹回流三个来源。覆盖 τ²-bench、SWE-bench、AndroidWorld、OSWorld、Terminal-Bench、GAIA 的可迁移设计手法。\n---\n\n# 评估数据集设计\n\n## 何时使用\n- 从零设计评估集，或评审现有任务定义是否站得住\n- 为 Agent 编写单条评估任务：工单、用户模拟规范、初始状态、验收标准\n- 设计验证器：该断言终态、断言动作，还是检查必须告知用户的信息\n- 评估任务被模型\"猜答案\"蒙过，需要提高信噪比\n- 怀疑评估集已被污染/泄漏进训练数据，需要防泄漏与检测手段\n- 决定自建评估集的任务从哪来：公开基准、业务集、还是生产失败回流\n- 评估集上线后需要长期维护：修补环境、描述、验证逻辑与初始状态问题\n\n## 核心原则\n- **一条评估任务 = 四个部分**：给 Agent 的工单、给模拟器的行为规范、两侧状态的初始重置、成功判定标准。缺任何一部分，任务都无法重复运行。\n- **把用户的认知边界建模为独立字段，而非靠提示词约束。** 用户不知晓的信息 Agent 无从推测，只能通过提问与引导获得——渐进式信息透露不是一句\"不要一次说完\"，而是 `known_info` 与 `task_instructions` 的拆分。\n- **没有事实锚定的用户模拟器会让评估退化为两个模型相互确认。** 模拟用户关于环境状态的任何回答都必须以工具返回为依据，不许编造工具结果；否则 Agent 稍加引导，用户就确认\"问题已解决\"。\n- **验证器必须核实机器可独立复核的事实，不能采信 Agent 的自我陈述。** Agent 很容易写一篇\"任务已全部完成\"的报告而实际什么都没做。\n- **训练集与评估集严格隔离。** 答案不可从互联网直接检索、任务实例参数化生成、嵌入 canary 使泄漏可检测——三招至少用一招。\n- **验收口径要有可核实的边界，防\"敷衍性修复\"。** \"网络已恢复\"不可核实；\"测速评级 excellent 才算解决，poor/fair/good 均不接受\"才堵得住压制症状、不除根因的糊弄。\n- **高质量的评估集是修出来的，不是写出来的。** 主流基准的现行形态都是初版暴露问题后逐轮修补的结果；发布前人工淘汰、发布后持续修两类问题都要预算。\n- **每道题亲手做一遍。** 做完问两个问题：描述是否有多种合理解释，验证器认可哪一种？蒙混过关的最低成本路径是什么，验证器拦得住吗？\n- **难度分层让评估集不过时**，且每层失败指向不同改进方向：基础层失败指向工具使用，中间层指向多步规划，最高层指向长序列思考。\n\n## 实践模式\n\n### 1. 任务解剖：四件套字段清单\n以 τ²-bench telecom 一条真实任务为范本，逐项对照自建任务：\n- **ticket（给 Agent 的工单）**：只含用户会主动说出的部分。真实用户的初始表述往往只是\"我上不了网\"，把需求澄清到可执行的程度本身就是 Agent 必须具备的能力。\n- **user_scenario（给模拟器的行为规范）**：`known_info` 界定用户知悉范围（姓名、号码、所在国），故障原因不在其中；`task_instructions` 规定透露方式，并包含三类约束——情绪设定（首次修复失败后表现不满）、验收口径（仅 excellent 算解决）、事实锚定（设备状态回答必须基于工具结果）。\n- **initial_state（初始重置）**：`initialization_actions` 把两侧状态重置到同一起点，包括用户侧（飞行模式、漫游开关）与 Agent 侧（运营商侧配置）。\n- **evaluation_criteria（成功判定）**：四个可检查维度按需组合，外加聚合规则。\n\n### 2. 四维校验与聚合规则\n- `env_assertions` 验**终态**：移动数据可用、测速达 200 Mbps 且评级 excellent。\n- `actions` 验**关键动作是否发生**（哪些工具被哪一侧调用）。\n- `communicate_info` / `nl_assertions` 验**必要信息是否已告知用户**——别只查环境状态。\n- `reward_basis` 是聚合规则。二元奖励（只看终态）以过程颗粒度换取跨模型可比的单一数字：满分轨迹里违反\"一次只做一个工具调用\"的政策也不会被捕获。生产评估系统需要更多：不仅判对错，还要指出问题出在哪。\n\n### 3. 验证器设计的三种模式\n- **双命题验证**（SWE-bench Verified）：FAIL_TO_PASS（修复前失败、修复后通过，证明问题确已解决）+ PASS_TO_PASS（修复前后均通过，证明未引入新缺陷）。只验前者，Agent 可以删改妨碍通过的断言蒙混；只验后者等于未检验。另需排除自身不稳定的 flaky test。\n- **深状态核查**（OSWorld 式）：134 个独立评估函数，拥有完整系统访问权限，查文件系统结构、进程状态、网络连接与应用内部状态；数据库任务连库核实 SQL 是否真执行，浏览器任务分析 DOM、cookie 与 localStorage 并向后端发验证请求——能抓住\"表面完成、实质错误\"。\n- **不可伪造执行**（Terminal-Bench 式）：成功标准是真实构建并运行（如从源码构建内核并在 QEMU 启动日志出现自定义 printk），Agent 无法伪造输出，只能真做完全流程。\n\n### 4. 难度划分与陷阱任务\n- 分层标注并用于诊断：GAIA 466 题分三级——Level 1 只需一至两个工具（人类 93.9%，早期模型 30.3%），Level 2 多步思考，Level 3 复杂组合。Level 1 失败指向基础工具使用，Level 2 指向多步规划与信息整合，Level 3 指向长序列思考与复杂性管理，改进方向各不相同。\n- **陷阱任务**检验压力与误导下的判断力：用户声称\"客服已批准取消\"，实际并不符合政策，看 Agent 是否维持正确判断。\n- 任务集覆盖从易到难的全谱，模型能力提升时评估集不会快速过时。\n\n### 5. 数据泄漏防范\n- **组合多源 + 专有附件 + 精确匹配**（GAIA 式）：答案必须组合多个信息源才能得出，单一网页无法直接给出；部分任务配互联网上不存在的 PDF/音频/图片附件；用精确字符串匹配判定。\n- **参数化模板实例化**（AndroidWorld 式）：任务是\"将联系人 X 的电话改为 Y\"这类模板，每次评估随机生成参数。三收益：回放固定操作序列失效；单模板可生成近乎无限实例；固定部分参数、只改其余，可精确测量特定因素的影响。\n- **金丝雀标识符**（Terminal-Bench 式）：题面嵌入 canary GUID，模型能输出含该 GUID 的内容即说明基准已进训练集。它不阻止泄漏，但使泄漏可被检测。\n\n### 6. 质量控制与长期维护\n- **发布前人工淘汰**：SWE-bench Verified 从 2294 个原始任务抽 1699 个，93 名精通 Python 的开发者逐条检查（描述是否清晰、测试是否覆盖边界、是否稳定、参考 patch 是否引入新错误、难度是否合理），仅 500 个通过——淘汰 71% 换来更高信噪比，评估成本下降约 80%。复杂 Agent 任务动辄数分钟至数小时，前沿模型跑完一个评估集往往需要数千美元 token，控本就是控迭代速度。\n- **发布后持续修补**：OSWorld 发布 15 个月暴露出 300 余个问题，分四类——环境问题（反爬、CAPTCHA、动态内容，靠锁定版本与离线备份）、任务描述歧义（改写消除）、验证逻辑过严或过松（人工建立正确基线再调条件）、初始状态不完整（增加完整性校验）。修补方式可整体借鉴。\n- **从初版到成熟版的五处典型重设计**（τ-bench → τ²-bench）：任务指令过于笼统导致可猜 → 拆分 known_info/task_instructions；成功条件不精确 → 改为可核实边界；模拟用户过于机械 → 补情绪、耐心上限与事实锚定；只有 Agent 能改变环境 → 引入用户侧工具的双控机制；静态任务 → 参数化批量生成实例（同时改善覆盖率与抗泄漏）。\n\n### 7. 评估集的三个来源与演进\n- **公开基准**：用于粗筛模型与借鉴设计手法（验证深度、参数化生成、防泄漏、质量维护），一般不用于产品决策——其任务分布与业务分布不一致。\n- **自建业务集**：覆盖真实任务分布，作为模型选型与 Harness 设计决策的依据。可拿成熟基准当骨架，替换领域数据与工具集。\n- **生产轨迹回流**：用户明确纠正、点踩、事后规则/LLM 审计发现的失败案例，经失败归因后沉淀为回归用例。成本最高、准确性最高，直接来自用户实际遇到的问题。\n- 演进节奏：起步只有公开基准 + 少量手写业务集；上线运行一段时间后，回流用例成为主体。今天线上暴露的失败模式，明天就是守住底线的回归用例。\n\n## 常见陷阱\n- 任务指令写得宽泛，模型无需澄清需求、凭常识猜一套流程也能通过。\n- 成功条件是\"网络已恢复\"这类无边界描述，被压制症状的敷衍性修复蒙过。\n- 只验 FAIL_TO_PASS 不验 PASS_TO_PASS，Agent 靠删断言作弊；或不排除 flaky test，结果不可复现。\n- 用户模拟器没有事实锚定，评估退化为 Agent 与模拟用户相互确认；没有耐心上限，沟通效率低下不被计失败。\n- 静态题面被模型记忆，且无 canary，泄漏发生了都不知道。\n- 验证器过严（把正确答案判失败）或过松（放走表面完成实质错误）；初始状态配置不完整，每次运行起点不同。\n- `reward_basis` 只看终态，过程违规（策略违背、信息未告知）不被捕获，且不另建过程检查。\n- 任务描述存在多种合理解释而验证器只认一种，开发者与人肉执行者的判断不一致。\n- 评估集建成后不再维护，上线后仍是手写那几十条，与真实用户分布脱节。\n\n## 配套代码\n- `chapter7/tau2-bench-eval/` — τ²-bench telecom 任务定义四部分（ticket / user_scenario / initial_state / evaluation_criteria）的完整解剖与双控环境运行记录\n- `chapter7/public-health-reporting-eval/` — 五个确定性任务的六点结构化评分示范验证器设计：工具选择、参数、答案（含数值容差）、证据行精确集合、无依据声明处罚\n- `chapter7/android-world/` — T3A 失败轨迹与归因笔记，演示参数化任务实例、验证器终态判定，以及从失败轨迹回流生成轨迹前缀回归任务\n\n## 深度阅读\n- `book/chapter7.md`「一条评估任务的解剖：τ²-bench 的 telecom 领域」\n- `book/chapter7.md`「评估数据集的设计」\n","skills/error-recovery/SKILL.md":"---\nname: error-recovery\ndescription: 排查或加固 Agent 故障恢复机制时使用——当 Agent 陷入无限循环、流式响应中途断开、上下文溢出、模型服务限流过载、需要跨厂商接管跑到一半的轨迹、设计重试与熔断策略、防止错误处理路径自身引发连锁故障时使用。覆盖四层故障分类、检测方法、分级恢复策略、熔断上限与流式中断恢复。\n---\n\n# 故障与错误恢复\n\n## 何时使用\n- Agent 反复调用同一工具毫无进展、陷入死循环或死亡螺旋\n- 流式响应在思考/正文/工具调用参数中途断开，需要续写\n- 模型 API 限流、过载、超时、输出触顶，需要重试或降级\n- 上下文窗口溢出、压缩失败、轨迹结构损坏（工具调用缺配对结果）\n- 主模型持续不可用，要把轨迹交给另一家模型接着跑\n- 设计重试策略、熔断阈值、错误暴露边界\n- 工具调用幻觉/参数畸形，需要让模型自我纠正\n\n## 核心原则\n\n**故障分类学：四层。** 先分类再处理，不同层的故障走完全不同的恢复路径：\n\n- **API 层**：限流（429）、过载、请求超时、连接中断、输出触顶被截断。与任务内容无关，是基础设施噪声——可重试。\n- **工具层**：幻觉调用（调用不存在的工具）、参数畸形、执行抛异常，以及最危险的一种：工具反复返回同一错误，模型不加改变地反复重试。\n- **上下文层**：窗口溢出、压缩失败、轨迹结构损坏。\n- **控制流层**：死循环（相同操作无进展）与死亡螺旋（恢复逻辑自身又调 LLM、再次出错、连锁反应）。\n\n**检测：先分类，再计数。** 第一个判断不是\"要不要重试\"而是\"值不值得重试\"：可重试错误（限流、过载、网络抖动）重试才有意义；不可重试错误（参数不合法、权限不足、工具不存在）原样重试一万次结果相同，必须改变输入或策略。生产级 Harness 维护一张\"错误 → 恢复策略\"的映射表，而不是笼统地\"出错就重试\"。单次错误之外还要检测**模式**：对\"工具名 + 参数\"计算指纹，相同指纹反复出现就是无进展循环的明确信号；每条恢复路径维护独立的连续失败计数，为熔断提供依据。\n\n**活性与完整性监控。** 流式连接最危险的失败不是断开（会立即报错），而是**静默卡死**——连接建立但数据流停止。SDK 超时往往只覆盖初始连接而非传输过程，需要独立的空闲看门狗（超过设定时间无新输出即判定卡死，主动杀死挂起的流并重试）。可推广为：**每个长连接都需要活性信号，而非仅依赖连接超时**。完整性监控针对轨迹结构：发现工具调用缺少配对结果消息时，在注入上下文前自动修复配对，而不是把结构异常抛给模型或用户。产品模式可用占位符宽容修补，训练数据收集模式则拒绝修复——合成占位符会污染训练数据。\n\n**恢复：分级升级，逐级透明。** 能用低级别解决就不升级：\n\n1. **静默重试**——可重试错误的默认动作。指数退避叠加随机抖动（避免客户端同步重试造成二次拥塞，尊重服务端的等待时长提示）；区分前台与后台调用：主循环失败要重试，标题生成、输入建议这类辅助性后台调用失败直接放弃，否则后台重试挤占主链路配额，形成\"重试放大\"。\n2. **降级与接续**——重试无效时改变请求本身。输出触顶：先静默提升输出上限重发，仍不够再在消息末尾追加元指令让模型从断点接续；主模型过载时降级到备用模型（先剥离旧模型私有格式块，否则新模型解析不了历史）；高成本模式被限流时暂时回落到标准模式。\n3. **暴露给用户**——所有自动手段用尽后才呈现错误，并附上已尝试过的恢复动作。\n\n**工具层错误走另一条路：不终止会话，把错误变成模型的输入。** 幻觉调用收到\"工具不存在\"的结构化错误结果；参数校验失败收到附带输入约束提示的错误；畸形参数（该是对象却输出字符串）在执行前先程序化修复。错误以普通工具结果身份进入上下文，由模型下一轮自行纠正——喂回的错误越具体，自我纠正成功率越高。\n\n**错误处理的边界不是单次请求，而是整个恢复循环。** 在确认无法恢复之前，中间错误不暴露给消费者（用户或订阅事件的下游系统）：恢复期间扣留错误消息，恢复成功则消费者毫无感知，所有手段均失败后才统一呈现。\n\n**跨厂商接管：带走文字，带不走凭证。** 换一家模型把轨迹接着跑完，真正的障碍不是接口地址，而是轨迹里有只属于原厂商的东西。工具调用与结果各家结构不同但语义一致，重新渲染即可；难办的是思考——它由可读文字和厂商凭证（证明这段思考出自它自己）构成，文字换一家仍读得懂，凭证换一家就失效。且凭证未必附在思考上，也可能附在工具调用上（如 Google 的 thoughtSignature），所以\"把思考删干净就安全\"反而会在严格校验的厂商处失败。接管方案按最严格的一端设计：把历史工具调用改写成文字叙述，模型不再当作真正调用过，但至少能接着跑。由此得到设计原则：**轨迹按中立格式存储**——思考拆成可移植文字与不可移植凭证两个槽位，工具调用只记名称与参数，标识符渲染成具体请求时按目标厂商重新生成；切换时凭证一律丢弃，文字以普通内容身份带入。中立轨迹还服务于评估重放、训练样本构造、经验提取。\n\n**终止：每条恢复路径都要有上限。** 恢复机制本身也可能失效：上下文压缩连续失败若干次就放弃压缩，权限分类连续失败就回退人工询问，输出接续最多固定轮数。阈值来自生产数据而非拍脑袋——Claude Code 的\"连续 3 次\"压缩熔断阈值来自真实会话统计（曾有会话连续失败三千余次，仅此一类无效重试每天全球浪费约 25 万次 API 调用；3 次是\"绝大多数故障此前已恢复\"与\"继续重试基本无望\"之间的经验拐点）。\n\n**死亡螺旋防护。** 错误处理路径中的逻辑本身又调用 LLM，再次出错引发连锁。真实案例：上下文溢出触发\"结束时自动提交代码\"钩子，钩子调 LLM 生成 commit message 再次溢出，又一次触发钩子。防护两条：错误路径上禁用一切会再次调用模型的副作用逻辑（宁可丢掉自动记忆提取之类的辅助功能），以及用递归深度计数器检测并打断残余连锁。最后叠加全局终止条件：最大迭代轮数、会话预算上限、连续失败超阈值升级人工。\n\n**流式中断的三个断点、三种恢复方式。** 断点可能出现在：思考中途、正文中途、工具调用参数中途。恢复方式：① 丢弃半截内容整轮重发（最贵但最稳）；② 把半截内容作为末尾 assistant 消息要求模型接着写（部分厂商原生支持，其余需显式标注待续写消息，没有该接口则退回下一种）；③ 追加一条元指令说明从断点继续。注意：半截的工具调用无法以原生结构回传，需先转成文字再让模型补完，拼接后重新解析校验；若半截输出里已有工具因流式提前执行，续写前按调用指纹去重，避免重复副作用；拼接处容易多出空白或重复字符——参数合法不等于语义正确。\n\n## 实践模式\n\n**建一张错误 → 策略映射表**（比\"出错就重试\"的根本改进）：\n\n1. 捕获异常 → 归入 API/工具/上下文/控制流四层之一\n2. 可重试？→ 指数退避 + 抖动静默重试（前台重试、后台放弃）\n3. 改变请求可救？→ 提升输出上限 / 追加接续元指令 / 降级备用模型 / 回落标准模式\n4. 工具层错误 → 结构化错误结果喂回上下文，让模型下轮自我纠正\n5. 持续失败 → 查恢复路径的连续失败计数器，超阈值熔断（阈值从生产日志统计得出）\n6. 全部失败 → 统一向用户暴露，附已尝试的恢复动作清单\n\n**流式恢复实现清单**：记录断点类型（思考/正文/参数）；半截工具调用转文字 + 指纹去重；拼接后重新解析校验参数；对比三种方式的 token 成本与恢复成功率，选默认路径。\n\n**接管实现清单**：轨迹存中立格式（文字/凭证分离）；渲染层按目标厂商重组；凭证一律丢弃；遇强制凭证校验的厂商，历史调用改写为文字叙述；切换后监控重复调用指纹。\n\n## 常见陷阱\n- 笼统\"出错就重试\"：不可重试的错误（参数不合法、权限不足）重试多少次都一样\n- 只依赖连接超时：静默卡死（连接通但无数据）检测不到，必须配空闲看门狗\n- 后台辅助调用也重试：重试放大挤占主链路配额\n- 恢复期间把中间错误暴露给用户或下游事件订阅者\n- 没有熔断上限：一条恢复路径连续失败三千次，白白烧掉海量 API 调用\n- 错误处理路径自身调用 LLM：死亡螺旋，连锁故障\n- 以为删掉思考就安全跨厂商接管：凭证可能挂在工具调用上\n- 续写半截输出不按调用指纹去重：已执行的工具产生重复副作用\n- 训练数据收集模式用占位符修补缺失消息：污染训练数据\n\n## 配套代码\n- `chapter5/provider-failover/` — 实验 5-1/5-2：中立轨迹格式实现跨厂商接管（直传/剥离/中立三臂对照）与流式三断点接续\n- `chapter5/log-diagnosis/` — 诊断 Agent 读轨迹定位根因、生成回归测试、真实重放验证并建 Issue 的完整闭环\n- `chapter5/adaptive-log-parser/` — 自愈循环示范：解析失败不报错，而是把失败样本交给 Agent 生成代码、测试、热更新\n\n## 深度阅读\n- `book/chapter5.md`「故障与错误恢复」\n- `book/chapter5.md`「Coding Agent」→「实现技巧」（并行工具调用、流式执行与级联中止）\n- `book/chapter1.md`「Harness 工程：模型之外的竞争力」（纠正机制与\"不暴露中间态\"原则）\n","skills/knowledge-org/SKILL.md":"# knowledge-org\n\nPath: `skills/knowledge-org/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/knowledge-org/SKILL.md)","skills/kv-cache-design/SKILL.md":"# kv-cache-design\n\nPath: `skills/kv-cache-design/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/kv-cache-design/SKILL.md)","skills/loop-engineering/SKILL.md":"# loop-engineering\n\nPath: `skills/loop-engineering/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/loop-engineering/SKILL.md)","skills/mcp-skill-hub/SKILL.md":"# mcp-skill-hub\n\nPath: `skills/mcp-skill-hub/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/mcp-skill-hub/SKILL.md)","skills/memory-system/SKILL.md":"# memory-system\n\nPath: `skills/memory-system/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/memory-system/SKILL.md)","skills/multi-agent-design/SKILL.md":"# multi-agent-design\n\nPath: `skills/multi-agent-design/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/multi-agent-design/SKILL.md)","skills/post-training-strategy/SKILL.md":"# post-training-strategy\n\nPath: `skills/post-training-strategy/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/post-training-strategy/SKILL.md)","skills/rag-pipeline/SKILL.md":"# rag-pipeline\n\nPath: `skills/rag-pipeline/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/rag-pipeline/SKILL.md)","skills/reward-design/SKILL.md":"# reward-design\n\nPath: `skills/reward-design/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/reward-design/SKILL.md)","skills/tool-design/SKILL.md":"# tool-design\n\nPath: `skills/tool-design/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/tool-design/SKILL.md)","skills/tool-discovery/SKILL.md":"# tool-discovery\n\nPath: `skills/tool-discovery/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/tool-discovery/SKILL.md)","chapter9/ai-style-skill/skill/SKILL.md":"# skill\n\nPath: `chapter9/ai-style-skill/skill/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter9/ai-style-skill/skill/SKILL.md)","chapter10/multi-role-transfer/skills/coding/SKILL.md":"# coding\n\nPath: `chapter10/multi-role-transfer/skills/coding/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter10/multi-role-transfer/skills/coding/SKILL.md)","chapter10/multi-role-transfer/skills/data_analysis/SKILL.md":"# data_analysis\n\nPath: `chapter10/multi-role-transfer/skills/data_analysis/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter10/multi-role-transfer/skills/data_analysis/SKILL.md)","chapter10/multi-role-transfer/skills/research/SKILL.md":"# research\n\nPath: `chapter10/multi-role-transfer/skills/research/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter10/multi-role-transfer/skills/research/SKILL.md)","chapter10/multi-role-transfer/skills/triage/SKILL.md":"# triage\n\nPath: `chapter10/multi-role-transfer/skills/triage/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter10/multi-role-transfer/skills/triage/SKILL.md)","chapter10/multi-role-transfer/skills/writing/SKILL.md":"# writing\n\nPath: `chapter10/multi-role-transfer/skills/writing/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter10/multi-role-transfer/skills/writing/SKILL.md)","chapter2/agent-skills-ppt/skills/pptx/SKILL.md":"# pptx\n\nPath: `chapter2/agent-skills-ppt/skills/pptx/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter2/agent-skills-ppt/skills/pptx/SKILL.md)","skills/README.md":"# Skills Skill\n\nPath: `skills/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/README.md)","chapter4/collaboration-tools/README.md":"# collaboration-tools Documentation\n\nPath: `chapter4/collaboration-tools/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter4/collaboration-tools/README.md)","chapter4/execution-tools/README.md":"# execution-tools Documentation\n\nPath: `chapter4/execution-tools/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter4/execution-tools/README.md)","chapter4/perception-tools/README.md":"# perception-tools Documentation\n\nPath: `chapter4/perception-tools/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter4/perception-tools/README.md)","chapter9/self-evolving-tools/README.md":"# self-evolving-tools Documentation\n\nPath: `chapter9/self-evolving-tools/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter9/self-evolving-tools/README.md)","chapter2/agent-skills-ppt/skills/pptx/reference.md":"# Pptx Skill\n\nPath: `chapter2/agent-skills-ppt/skills/pptx/reference.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter2/agent-skills-ppt/skills/pptx/reference.md)"},"files":{"skills/agent-state-bar/SKILL.md":"---\nname: agent-state-bar\ndescription: Agent 陷入无限循环、数不清工具调用次数、遗忘 TODO 或目标偏离、长任务中思考 token 持续膨胀时使用——Agent 状态栏机制、作为 user 消息注入末尾的 KV Cache 理由、每轮替换与持久追加两种实现及成本模型、五种状态栏技术（时间戳、工具计数器、TODO、详细错误、系统状态）与维护铁律。\n---\n\n# Agent 状态栏：通过元信息增强 Agent 轨迹管理\n\n提示工程给的是静态指令，而 Agent 执行中还需要动态感知自身状态与任务进展。**Agent 状态栏**把任务进度、环境变化、工具调用计数等运行时状态整理成结构化摘要，由框架在上下文末尾持续注入。类比手机屏幕顶部始终显示时间、电量、信号——模型每次生成新回复时都能「瞥一眼」，据此做出更准确的决策。\n\n## 何时使用\n\n- Agent 反复执行相同工具调用、陷入无限循环（如超过次数限制仍在拨打）\n- 模型数不清「已经调用了几次」「还剩几项 TODO」，违反显式约束\n- 长任务中每次迭代的思考 token 量随上下文变长而持续增长\n- Agent 过分关注局部子任务，忘记用户原始诉求和核心约束\n- 小模型需要接近前沿模型的任务遵循能力\n- 设计状态消息的注入方式与更新策略\n\n## 核心原则\n\n- **状态栏不是对话主体内容**：它不属于用户消息、模型输出或工具结果，而是框架自动生成的状态摘要，注入在上下文**最末尾**，紧邻模型即将生成的新 token。\n- **理论基础是「上下文学习是检索而非推理」**：模型擅长查找，不擅长在一次前向传播中主动归纳统计。「已经打了几次电话」这类知识以原始记录形式分散在上下文里，模型每次决策都要花额外思考 token 扫描重算，效率极低且错误率高。\n- **本质是把隐式状态提炼为显式知识**：原始轨迹高度冗余，大量 token 中只含少量关键状态信息；状态栏以极低的额外 token 成本，呈现原本需要扫描数千 token 才能获得的信息。\n- **显式操纵注意力分配**：长上下文中早期目标和关键约束容易被后续工具结果淹没；结构化元信息放在末尾，空间上更接近新 token，获得更高注意力权重——一种「强制性的注意力引导」。\n- **实测收益**：提供提前算好的状态栏后，较小开源模型的准确率可以接近前沿大模型；每次迭代的思考 token 量、延迟和花费均降低约一个数量级。不带状态栏时思考量随上下文变长**持续增长**，带上后**基本恒定**。\n- **状态栏是上下文压缩技术之一**：它用代码确定性地维护「关于轨迹的结论」，与 LLM 驱动的压缩互补。\n- **无侵入性**：所有元信息以人类可读形式出现在上下文里，开发者随时可检查；不需要微调，直接在任何语言模型上起效。\n\n## 实践模式\n\n### 1. 注入位置：一条 user 角色的消息，放在最末尾\n\n```text\nmessages: [\n  { role: \"system\",    content: \"You are a customer service assistant...\" }  ← 固定，KV Cache 已缓存\n  { role: \"user\",      content: \"Help me cancel my Xfinity plan\" }\n  { role: \"assistant\", content: null, tool_calls: [...] }   ← 第 1 轮决策\n  { role: \"tool\",      content: \"Call log...\" }\n  { role: \"assistant\", content: null, tool_calls: [...] }   ← 第 2 轮决策\n  { role: \"tool\",      content: \"Call log...\" },\n  { role: \"user\",      content: \"Can you call them again to follow up?\" },\n  { role: \"user\",      content: \"<agent_status>\n      Current State:\n      - phone_call invoked 3 times (Xfinity: 3/3 max)\n      - Current time: 2025-09-14 10:30:45\n      - TODO: [1] Cancel plan (in_progress)\n    </agent_status>\" }                                        ← 框架注入的状态栏\n]\n```\n\n- **为什么是 user 角色而不是改 system**：修改 system 消息会破坏整个前缀的缓存。这里的 user 角色只是 API 协议层面的技术选择，**不等同于「来自终端用户的输入」**——Harness 借用这个消息槽位，挂载框架自动生成的系统状态信息。\n- 用 `<agent_status>` 标签包裹，便于模型识别其特殊性质。\n- 因为是追加而非修改，前面所有已缓存内容都不受影响。\n\n### 2. 状态栏的三类构成\n\n- **任务规划**：TODO 列表把复杂多步骤任务分解为清晰步骤，放在轨迹末尾，不断提醒模型当前进展和后续目标，确保行动与总体规划一致（防止只关注局部子任务）。\n- **事件的侧信道信息（Side-channel）**：为每个事件附加元数据——精确时间、地理位置、距上次 Agent 回复的时间间隔。通常随对应事件一起追加。\n- **环境当前状态的观察摘要**：系统时间、工作目录、异常操作提醒（「该工具已被重复调用 N 次」）、以及从隐式状态到显式观察的转换。随任务推进不断更新。\n\n### 3. 状态更新的两种实现与缓存代价\n\n**实现一：每轮替换**——每次 API 调用前移除上一轮状态消息，在末尾追加最新状态。保证永远只有一份最新状态，但移除旧状态会使其位置之后的所有缓存失效（与「动态时间戳」同一失效机制，区别仅在于状态消息位于末尾，失效范围只覆盖上次注入后新增的消息，通常是一轮，整个前缀仍可复用）。\n\n**实现二：持久追加**——状态消息一旦注入就永久留在轨迹中，每轮只在末尾追加新状态。Claude Code 的 `<system-reminder>` 即此方式，历史状态保留在 transcript 中从不删改。对缓存完全友好（只追加不修改，前缀始终稳定），代价是陈旧状态累积，既占 token 又要求模型自己关注最新一条。\n\n**选择规则**：\n\n- 状态很小、两次更新间产生的消息很多、会话长度受控 → **选实现二**（保留旧状态通常比反复重算长后缀便宜）\n- 状态较大、更新频繁或轨迹很长 → **选实现一**（只使上次注入后的短后缀失效，同时避免陈旧状态持续累积）\n\n**粗略成本模型**：设每条状态 S token，两次更新间新增后缀 R token，预计更新 N 次，缓存输入单价为普通输入的 α 倍：\n\n```\nC_替换 ≈ (N-1) * (1-α) * R\nC_追加 ≈ α * S * N * (N-1) / 2\n→ 当 α*S*N/2 < (1-α)*R 时倾向实现二，否则倾向实现一\n```\n\n该估算未计上下文占用和陈旧状态带来的歧义，实际选择还应结合服务商缓存计费与实测命中率。\n\n### 4. 五种状态栏技术（实验 2-9）\n\n- **时间戳跟踪**：以 `[2025-09-14 10:30:45]` 格式作为前缀添加到用户消息和工具响应中（**不是放在系统提示词里**，否则破坏 KV Cache）。让 Agent 理解时序关系，也为调试和审计提供信息；配合时间模拟可理解「昨天的文件」和「今天的修改」。\n- **工具调用计数器**：维护全局字典记录每个工具被调用次数，响应中标注 `Tool call #3 for 'read_file'`。显式计数触发模型的模式识别：第一次失败后检查路径，第二次失败后列出目录，第三次主动放弃并找替代方案。深层价值是隐式的成本感知。\n- **TODO 列表管理**：提供 `rewrite_todo_list` 和 `update_todo_status` 两个工具，每项含唯一标识符、内容、状态（pending / in_progress / completed / cancelled）和时间戳。借鉴 Manus「通过复述操纵注意力」理念。实验数据：启用 TODO 的 Agent 平均 **15 次**迭代完成任务，禁用时需 **21 次**且经常遗漏子任务。\n- **详细错误信息**：四层内容——错误类型和描述、完整参数的 JSON、调用栈信息、针对性修复建议（如 FileNotFoundError 时建议验证路径、检查工作目录、使用绝对路径）。启用后 Agent 在错误场景找到替代方案的成功率从 **60% 提升到 95%**，从盲目重试转变为有针对性地分析。\n- **系统状态感知**：注入当前时间、工作目录、操作系统类型、Shell 环境和 Python 版本。工作目录跟踪尤其关键——Agent 执行 `cd` 后自动更新；OS 信息让 Agent 做平台相关决策（Linux 用 `apt`、macOS 用 `brew`）。\n\n这些技术单独使用效果有限，**组合起来会产生涌现效应**：时间戳 + 工具计数器让 Agent 理解操作的频率和时间分布；TODO + 系统状态让 Agent 根据环境调整策略；详细错误 + 工具计数器让 Agent 多次失败后不仅改变策略，还理解失败原因。\n\n## 常见陷阱\n\n- **把时间戳写进 system prompt**：直接破坏 KV Cache 前缀，必须作为消息前缀或末尾状态注入。\n- **让 LLM 一次性批量统计状态**：模型几乎无条件地相信状态栏——你写「打了 3 次电话」，它就当真是 3 次，不会自己重算；而 LLM 做数量统计本来就容易出错。**状态栏尽量用代码维护，实在要用 LLM，也要逐条抽取、再由代码汇总。**\n- **忽视状态栏投毒风险**：状态栏信息被模型高度信任，一旦摘要内容来自可被外部污染的数据源（如把外部网页片段直接写进状态栏），这种信任会被反向利用。\n- **状态栏够用就整段删掉原始记录**：状态栏是对原始上下文的**有损投影**，只提前算了「你预想会被问到」的维度。计数、状态跟踪这类任务可以只保留状态栏以节省大量 token；但只要有一个问题涉及状态栏未计算的维度，仅保留状态栏就会导致准确率**断崖式下降**。删除前确认没有未覆盖的查询维度。\n- **状态消息无限累积从不清理**：实现二的代价，陈旧状态既占 token 又制造歧义，会话长度失控时应切换到实现一。\n- **用状态栏替代真正的任务规划**：TODO 列表需要配套工具支持状态流转，只在提示词里写「请跟踪进度」不够。\n\n## 配套代码\n\n- `chapter2/system-hint/` — 实验 2-9（agent-status-bar 框架）：实现时间戳、工具计数器、TODO 列表、详细错误、系统状态五种状态栏技术，可独立开关；`python main.py --mode preview` 无需 API key 即可对比有无状态栏时模型看到的上下文差异；`python run_experiment_2_8.py` 跑冻结的对照实验。\n\n## 深度阅读\n\n- `book/chapter2.md`「Agent 状态栏：通过元信息增强 Agent 轨迹管理」\n","skills/bad-case-to-dpo/SKILL.md":"---\nname: bad-case-to-dpo\ndescription: 把生产 bad case / 失败轨迹转成训练数据时使用——从失败归因、轨迹前缀截取、DPO 偏好对构造、LoRA 训练到边界集与保留集双集验证的完整链路；也用于判断某类问题该走 SFT、DPO、RL 还是先修 Harness/工具/tokenizer，以及如何从运行轨迹中提取带证据的结构化学习信号。触发词：bad case、失败归因、DPO、偏好对、轨迹前缀、拒绝采样、过度矫正、边界集、保留集、过早结束、reward hacking、LoRA 微调、训练评估隔离。\n---\n\n# 从问题案例到训练数据\n\n## 何时使用\n\n- 生产出现 bad case：用户纠正、点踩、事后审计发现失败轨迹，想把它变成后训练输入\n- 判断某类失败该修 Harness/工具/tokenizer，还是值得投入训练\n- 构造 DPO 偏好对、轨迹前缀回归任务、决策边界示范\n- 决定一个失败案例该进 SFT 数据、DPO 偏好对、PRM 负标签还是 RLVP 惩罚规则\n- 训练后验证修复效果，担心\"修好一个、弄坏一片\"\n- 从运行轨迹中提取可学习信号，而不是只存一个总分\n\n## 核心原则\n\n- **归因到首个错误步骤，不是整条轨迹。** 以 Coding Agent \"过早结束\"为例：读代码、改代码可能都没错，错的是\"在缺乏证据时下结论\"那一个决策边界。归因记录必须落到这一步，训练数据才能对着它构造。\n- **失败轨迹不应直接当作正确的 SFT 示范。** 它的正确用法是：构造偏好对、发现任务覆盖缺口，或补上诊断与修复后再加入训练。\n- **判定必须靠模型写不了的机制。** \"是否完成\"要由隐藏测试、状态断言或外部终止钩子给出；测试必须读取真实文件或环境状态，不能只检查模型是否说了\"已完成\"，否则模型会学会口头承诺验证而不真正验证。\n- **边界集与保留集缺一不可。** 边界集（任务未完成）看模型是否选择继续验证而非宣称完成；保留集（任务已完成）看模型是否仍能正常收尾。只盯边界集会把模型训练成永远不敢结束的**过度矫正**状态：每个任务都无限验证下去，延迟与成本崩溃。这是\"改动不能破坏既有行为\"在参数层面的版本。\n- **训练与评估严格隔离。** 训练集与评估集必须是不同的任务、不同的参数、不同的模板组合；参考解法、隐藏测试和验证器反馈不能泄露给模型。隔离规则应由单元测试强制检查，而不是靠人记得。\n- **先排除非模型原因。** 沿\"文件原始字节 → 工具返回 → Harness 序列化 → 模型上下文 → 模型 token 输出 → 解码字符串 → JSON/tool-call 解析 → 工具匹配\"逐层对比。只有模型收到的上下文与原始字符串完全一致、而**模型输出是链路上首个出现差异的位置**，才能标为模型能力问题。否则修工具/Harness/tokenizer，修完再看还剩多少。\n- **小数据 DPO 必须混入通用任务数据。** 案例数量少时，按小配比混入通用任务做 LoRA 微调，避免把\"逢收尾必验证\"学成新的过拟合，也降低灾难性遗忘风险。\n- **学习信号必须带证据。** 单一总分无法指出该改哪里。可供学习的评价至少包含：任务成功/部分成功/失败、每个维度各自的结论、每条结论对应的证据位置（哪一轮对话、哪一次工具调用）、失败的类型标签。验证器还应被允许在证据不足时**拒绝评分**——低置信度案例应排除在学习集之外，而不是当作事实固化。\n\n## 实践模式\n\n### 完整链路：失败归因 → 双集验证\n\n**① 采集与归因。** 从用户纠正、点踩、事后审计三类生产信号收集失败轨迹，按错误分类定位**首个错误步骤**并记录错误类别。轨迹前缀回归任务就是从这个决策边界截取的。\n\n**② 分流：该不该训练。** 先问 prompt、工具、代码约束、上下文管理能否解决；再沿字节链路排除工具/Harness/tokenizer 问题。都不要动权重时就不训练。\n\n**③ 选训练形态。** 按第七章评估数据集的类型映射到第八章用法：\n\n| 你手上的材料 | 训练用法 |\n|---|---|\n| 端到端回归任务（含验证器） | RL rollout 任务与可验证奖励（RLVR）；拒绝采样（RFT）的采样池 |\n| 轨迹前缀回归任务 | DPO 偏好对、决策边界的 SFT 示范、On-Policy Distillation 的教师状态 |\n| 失败归因记录（首个错误步骤与错误类别） | 过程监督的负标签（PRM）、RLVP 路径惩罚的规则来源 |\n| Rubric 多维评分与人工金标集 | 向量奖励的各维度、生成式奖励模型（GRM）的训练与校准数据 |\n\n**④ 截取轨迹前缀，构造偏好对。** 在决策边界上截出\"准备宣称完成\"的轨迹前缀：rejected 是过早结束的错误行为，chosen 是\"先运行测试、逐条核对验收条件，再下结论\"的期望行为。chosen 由教师模型生成，再经规则验证器过滤（拒绝采样）。案例太少时用数据扩充（换任务类型、换缺失的验证项、换完成措辞）形成数百条偏好对。失败原因、适用条件和验证器应随样本保存，方便追溯和复查。\n\n**⑤ LoRA DPO 训练。** 小配比混入通用任务数据防过拟合。参考配置：Qwen2.5-7B-Instruct + bf16 LoRA、4 epochs、学习率 3e-5、单卡约 24GB 显存。训练回执记录配置、数据哈希与时间戳。\n\n**⑥ 双集验证。** 对未完成任务集和已完成任务保留集分别让模型给出\"下一步动作\"，判定属于\"宣称完成\"还是\"继续验证\"：\n\n- **未完成任务集的过早结束率** —— 训练后应下降\n- **已完成任务保留集的正常收尾率** —— 训练后应保持\n- **过度矫正率 = 1 − 正常收尾率** —— 应维持在低位\n\n优先采用**格式固定、与训练提示一致的候选比较**（固定两个候选动作，比较模型更偏好哪一个，直接测量决策边界），而不是开放式自由生成。同时抽查通用能力，确认 LoRA 补丁没有破坏其他能力。\n\n**⑦ 记录与追溯。** 训练数据与评估集分开保存；数据构造有确定性模板和教师模型两条路径时，两条都留证据回执。\n\n### 案例参照：Coding Agent 过早结束（实验 8-17）\n\n配套数据：24 条轨迹前缀 bad case，覆盖四类过早结束——未跑测试就宣称完成、多目标只完成一部分、声称完成但验收条件未满足、遇错放弃宣称不可能（含删除失败测试/skip 等 reward hacking 变体）；与训练数据严格隔离的留出评估集为 boundary 12 条 + retention 8 条。\n\n实测结果：基座在固定候选比较的未完成任务集上选对 **3/12（25.0%）**，已完成任务保留集 **8/8（100%）**；LoRA DPO 后分别为 **11/12（91.7%）** 和 **8/8（100%）**。自由生成是补充诊断：过早结束 1/12→0/12，但正常收尾 6/8→0/8——**说明小数据 DPO 会让模型在开放式回答里过于谨慎**，因此主要结论只采用候选比较口径，不能外推成线上总体成功率提升。\n\n同一个问题还有 RL 分支：把\"宣称完成前必须跑通验收测试\"写成可验证奖励，测试对模型不可见，模型宣称完成时才运行，通过 +1、不通过 −1。\n\n### 另外两类常见案例的处理差异\n\n- **规则类反馈（如\"中文直引号应统一为弯引号\"）**：期望描述不是可直接训练的规则，同一个引号在中文自然语言、英文原文、Markdown 行内代码、代码块、注释、JSON、路径中角色完全不同。正确做法是**作用域敏感的最小编辑**：先把规则写成可审计的 Skill（正例覆盖需转换的中文段落与中文注释，反例覆盖英文原文、字符串字面量、JSON、路径、行内代码），它同时作为合成数据的标签依据、训练后的回归规范和规则变更时的重训输入。\n- **byte-exact 复制类（如 `edit_file` 的 `old_string` 匹配失败）**：把复制任务抽象成三个可验证任务——直接逐字复述、在相似且等长的多个字符串中选择完全相同的目标、把指定字符串完整抄写到 `old_string` 工具参数。样本特意包含真实编辑最容易损坏的空格、换行、反斜杠、Unicode 组合字符。训练后要用独立 tokenizer 审计排除词元化造成的假象：若 round-trip 上限本身就是 80.1%，模型测到 80.1% 就不能算作纯能力提升。\n\n### 从运行轨迹中提取学习信号（三层验证）\n\n评价一条轨迹实质是依次回答三个问题：**事情是否办成了、是否以允许的方式办成、是否让用户舒服。**\n\n- **底层结果验证器**——读测试结果、数据库状态、工具返回。这类信号来自环境真实状态，比模型对自己行为的描述可靠，是三层中最应优先建立的一层。\n- **中间过程验证器**——检查业务规则、权限和动作序列，区分\"结果已达成\"与\"结果以允许的路径达成\"。删除失败测试用例也能让测试通过；口头承诺也能得到暂时满意。政策库、权限表与动作轨迹均可精确表达，因此这层同样可以由代码判定。\n- **上层质量验证器**——是否耐心、是否提供合规变通、文本是否自然简洁。用 LLM-as-a-Judge 加预定义 Rubric，要求逐项给分并引用轨迹证据。\n\n输出形态决定它能否成为学习信号：单一总分只能反映一次运行的优劣。四项内容（成败判定、每维度结论、证据位置、失败类型标签）齐备，后续才能判断该更新知识、提示词、程序还是模型参数。\n\n## 常见陷阱\n\n- **把失败轨迹直接当正确示范训练**，把错误行为固化进参数。\n- **只优化边界集，不看保留集**，把模型训成永远不敢收尾的过度矫正状态。\n- **训练集与评估集共享任务或参数**，评估失去独立性；隔离规则要由测试强制，不靠人记得。\n- **用模型自述当完成判定**，模型很快学会\"口头声称去验证\"而不真的验证。\n- **把系统层损坏误报为后训练收益**：直接复述探针正确但工具调用仍失败时，该修的是 Harness 或工具协议。\n- **把 tokenizer/序列化损坏误判为模型复制能力不足**，训练前先做独立 tokenizer round-trip 审计。\n- **案例太少又不做扩充**，几条偏好对撑不起一个决策边界；或扩充时只换措辞不换任务类型与缺失验证项。\n- **小数据 DPO 不混通用数据**，学出\"逢 X 必 Y\"的新过拟合并带来灾难性遗忘。\n- **低置信度结论进入学习集**，错误经验和提示注入被固化并在后续任务持续放大。\n- **把开放式自由生成当主要验收口径**——小数据 DPO 下自由生成会过度保守，格式固定的候选比较才与训练提示一致。\n\n## 配套代码\n\n- `chapter8/premature-completion-dpo/` — 全书唯一从生产 bad case 出发的训练实验：24 条 bad case、boundary 12 + retention 8 留出评估集、隐藏测试；`python demo.py` 离线端到端演示，`python -m pytest -q test_pipeline.py` 机制单元测试，`python build_preference_data.py` 生成偏好对（`--teacher` 走教师模型拒绝采样路径），`python train_dpo.py --smoke` 数据/tokenizer 前向检查，`python train_dpo.py` 单卡 LoRA DPO，`python evaluate.py --decision-score` 双集候选比较评估，`python train_grpo_optional.py` 同一问题的可选 RL 分支。\n- `chapter8/curly-quote-sft/` — 规则类反馈的另一种监督目标：先写 `SKILL.md` 规范，再结构化合成数据做作用域敏感 SFT。\n- `chapter8/exact-copy-sft/` — byte-exact 复制 SFT，含 `tokenizer_audit.py` 排除词元化假象。\n- `chapter8/cot-distillation/` — \"生成候选—验证过滤—只留正确轨迹\"的拒绝采样流水线范例。\n\n## 深度阅读\n\n- `book/chapter8.md`「从问题案例到后训练」\n- `book/chapter8.md`「SFT 数据合成：从示范到可训练轨迹」\n- `book/chapter8.md`「奖励设计：如何把任务目标变成学习信号」\n- `book/chapter9.md`「从运行轨迹中获得学习信号」\n","skills/coding-agent-harness/SKILL.md":"---\nname: coding-agent-harness\ndescription: 搭建 Coding Agent 或设计 Agent 护栏时使用——当你要构建能自主读写代码、跑测试、自我纠错的编码 Agent，或为已有 Agent 系统补约束/验证/纠正机制、设计执行边界与验收基线、判断某类任务是否适合交给 Agent、优化 Harness 提示词与工具集时使用。覆盖 Harness 四组件、任务四象限、四条设计原则与业界实践。\n---\n\n# Coding Agent 与 Harness 工程\n\n## 何时使用\n- 从零搭建 Coding Agent（选工具集、定工作流、接测试反馈）\n- 为已有 Agent 补可靠性：加护栏、验收基线、执行边界、回退手段\n- 评估一个任务是否适合交给 Agent 自主执行（四象限判断）\n- Agent \"能跑但不可靠\"：跑偏、走破坏性捷径、过早宣布完成\n- 优化 Harness 本身（提示词、工具中间件、自验证循环）而不是换模型\n\n## 核心原则\n\n**Agent = Model + Harness，Harness = 上下文管理 + 工具接口 + 约束 + 验证 + 纠正。**\nHarness 是\"Agent 边界内、模型之外\"的运行与治理层：工具定义、调用适配器、沙箱权限属于 Harness；沙箱内的文件进程、外部数据库、用户属于 Environment。模型能力趋同后，竞争力在 Harness。\n\n**Coding Agent 场景的 Harness 四组件**（把抽象机制落地成工程件）：\n\n| 组件 | 回答的问题 | 落地形态 |\n| --- | --- | --- |\n| 验收基线 | 什么算做完了 | 测试套件、CI 管道、代码审查标准 |\n| 执行边界 | 能碰什么不能碰什么 | 模块边界、依赖规则、权限控制 |\n| 反馈信号 | 自动化的对错判断 | Linter 输出、测试结果、类型检查错误 |\n| 回退手段 | 出了问题怎么恢复 | Git 版本控制、沙盒隔离、快照回滚 |\n\n**任务四象限（目标清晰度 × 验证自动化程度）**——Harness 的目标是把任务推向\"目标明确 + 可自动验证\"：\n\n- 目标明确 + 可自动验证 = **最佳区域**（修复有测试用例的 bug）\n- 目标明确 + 需人工验证 = **吞吐量受限**，天花板是人的审查速度\n- 目标模糊 + 可自动验证 = **高效地跑偏**（如拿 linter 分数优化\"代码质量\"）\n- 目标模糊 + 需人工验证 = **难以启动**（如\"让 UI 更好看\"）\n\n代码编写天然处于象限核心：测试套件给验收标准，Linter/类型检查给即时验证，Git 给版本控制与回退。Coding Agent 成熟度最高不是因为代码模型最强，而是软件工程几十年积累的基础设施天然就是一套 Harness。\n\n**四条可迁移的设计原则**：\n\n1. **约束优先于指导**——能用代码强制的规则不要用文档建议。Linter 规则、类型约束、CI 检查是\"做不了\"，系统提示词里\"请遵循...\"只是\"建议别做\"。\n2. **验证要自动化**——人工审查是不可扩展的瓶颈，测试/检查/监控的投入回报率远高于加人力。\n3. **反馈越快越好、越结构化越好**——错误信息越详细、越接近出错时刻，Agent 纠正效率越高。\n4. **回退要可靠**——有安全网 Agent 才敢试错；Git 分支、沙盒、快照确保任何错误可逆。\n\n**约束管动作，不只是管结果。** 验收基线管结果对不对，执行边界管过程：删库重建\"修复\"了故障但数据没了，删光重写让编译通过但实现没了。这类破坏性捷径 Agent 总能绕开指标找到（reward hacking 的日常形态），因此 `rm -rf`、删生产数据、覆盖未读文件要设专门检查与审批。\n\n**并行调用的故障边界控制**：一个工具失败时，故障只在同一批并行调用内传播（级联中止依赖它的调用），不取消独立调用，不上升到父级操作、不让整个任务中止。每个工具声明是否支持并发（默认否，失败安全）。\n\n**业界经验**：\n- 大规模代码迁移成功靠三件事：知识必须存在于代码库本身（Agent 看不到的等于不存在）、约束编码进 Linter/CI 而非文档、验证与纠正全链路自动化。\n- LangChain 只优化 Harness（提示词、工具中间件、自验证循环）就把 Terminal Bench 2.0 从 52.8% 提到 66.5%，并用 Agent 分析失败轨迹反哺 Harness，让 Harness 工程从经验驱动变数据驱动。\n- Anthropic 拆两个角色：初始化 Agent 分解任务清单，执行 Agent 逐步推进并留下清晰的交接产物，解决\"一次想做太多\"和\"过早声称完成\"。\n\n## 实践模式\n\n**建一个 Coding Agent 的最小清单**：\n\n1. **工具集**：文件读写（read/write/edit）、目录浏览（glob/ls）、内容搜索（grep）、命令执行（bash）七件套；每个工具命名直观、参数带例子、边界有说明（防呆设计）。\n2. **工作流**：先理解项目（读文档、建认知框架）→ 设计 → 实现 → **立即写测试并跑** → 失败则分析-定位-修复循环，直到测试全绿。把\"测试通过\"而非\"代码写完\"定义为完成标准——跳过测试直接报完成是 Coding Agent 最常见的偷懒方式。\n3. **验收基线**：接入现成的测试套件、Linter、类型检查、CI；没有就先补最小可跑的。\n4. **执行边界**：默认权限最小化（故障安全默认值，能力默认关闭、显式开放）；危险命令走审批。\n5. **回退手段**：每次任务前开 Git 分支或快照；沙盒内执行不可逆操作。\n6. **反馈回路**：把 Linter/测试/编译错误结构化地喂回上下文（附行号、文件路径、错误类型）。\n7. **持续改进**：收集失败轨迹，让 Agent 分析轨迹反哺 Harness 修改。\n\n**上下文与环境注入**（Harness 的上下文层）：大文件按行号范围读取并给每行加行号前缀；长命令输出只保留头部（错误上下文）与尾部（错误总结）并说明完整输出已落盘；每次推理前以状态栏形式动态注入当前工作目录、git 分支、最近提交、未暂存变更（动态追加，别硬编码进系统提示词以免破坏 KV Cache）；维护持久化终端会话保留 cd/环境变量状态。\n\n## 常见陷阱\n- 把指导写进提示词而不落成代码约束——模型会忽略\"请遵循...\"式建议\n- 没有验收基线就放权：Agent 高效地往错误方向跑，或走破坏性捷径（删库重建、删光重写）\n- 写完代码不跑测试就报告\"任务完成\"\n- 把整个代码库一股脑塞进上下文，既不经济也没必要\n- 一个工具失败就中止整批并行调用甚至整个任务\n- 只换模型不修 Harness：基准提升往往来自 Harness 而非模型\n- 环境信息硬编码在静态系统提示词里\n\n## 配套代码\n- `chapter5/coding-agent/` — 纯 Python 实现的生产级 Coding Agent：16 个工具、patch 应用、测试/lint 验收反馈与失败路径\n- `chapter1/context/` — 上下文感知 Agent 与消融实验：量化 history/reasoning/工具调用/工具结果各自的作用\n- `chapter1/web-search-agent/` — 基于 Kimi Formula API 的自主 ReAct 搜索 Agent，展示\"模型即 Agent\"的最小闭环\n- `chapter1/search-codegen/` — Responses API 深度研究 Agent：托管 web_search + code_interpreter 的编排\n- `chapter1/learning-from-experience/` — LLM 上下文学习 vs 传统 RL 对照，理解 Agent 经验从哪来\n- `chapter1/image-gen-workflow/` — 工作流路线 vs 原生生成路线对照：何时该用固定 Harness、何时该交给模型自主\n\n## 深度阅读\n- `book/chapter5.md`「Coding Agent」→「Harness 工程在 Coding Agent 中的实践」\n- `book/chapter1.md`「Harness 工程：模型之外的竞争力」\n","chapter8/curly-quote-sft/SKILL.md":"# 中文技术文档符号与引用规范\n\n## 何时加载\n\n- 编辑或生成同时包含中文、英文、Markdown 和代码的技术文档。\n- 用户反馈引号、反引号或代码边界格式错误时。\n\n## 符号定义\n\n- ASCII 直引号：`\"`、`'`；常用于英文标点和代码字符串。\n- 中文弯引号：`“”`、`‘’`；用于中文自然语言引用。\n- Markdown 反引号：`` ` ``；用于行内代码和字面量。\n\n## 决策优先级\n\n1. 先保护可执行代码、JSON/schema、URL、路径和用户要求原样保留的引用文本。\n2. 识别 Markdown 代码围栏、行内代码和代码注释边界。\n3. 在中文自然语言作用域中，把成对的直引号改为弯引号，并正确处理嵌套引用。\n4. 英文原文保持原文标点；英文标识符是否使用反引号由其是否为代码字面量决定，而不是由语言决定。\n5. 无法判断作用域时保留原文并请求澄清，不做全局替换。\n\n## 正反例约束\n\n- 正例：`# 中文注释：显示 \"状态\"` → `# 中文注释：显示 “状态”`；同一代码块中的 `name = \"status\"`、`const name = \"status\"`、SQL 标识符和 JSON 键值保持 ASCII 语法。\n- 反例：不能把代码字符串、JSON、URL、路径、英文原句或 Markdown 行内代码中的 `\"`/`'` 改成弯引号；不能因为文件是中文就全局替换。\n- 每种编程语言至少提供“该改的中文注释”和“该留的可执行字面量”成对样本，并在留出/边界集更换体裁、变量名和代码结构。\n\n## 数据质量门禁\n\n- 合成数据先按文章体裁、作用域类型和编程语言分层，再切分 train/eval/boundary，禁止 ID 和模板组合重叠。\n- 机器门禁检查未解析变量、代码围栏、非注释代码行漂移和保护区；人工抽查每个分层的首条样本，记录在 `validation/manual_audit.md`。\n- 任何语言类别的保护区或语法门禁失败，都应回到 Skill/数据蓝图修订后重训，不能只增加 epoch 或汇报总体平均分。\n\n## 验证\n\n- 修改必须是最小编辑，正文事实和代码内容不变。\n- Markdown、JSON 和代码语法检查必须通过。\n- 英文原文、代码和保护区域做字节级回归。\n- 记录来源 Bad Case、适用范围、例外和验证结果。\n","skills/context-compression/SKILL.md":"---\nname: context-compression\ndescription: 上下文膨胀、工具结果撑爆窗口、Agent 决策质量随轮次下降时使用——上下文压缩的三个动机（长度成本、思考质量、上下文焦虑）、压缩即检索的机制、六种压缩策略实测数据、生产级五层分层压缩、四条设计原则，以及用子 Agent 隔离代替压缩。\n---\n\n# 上下文压缩策略\n\n压缩解决的是相反方向的问题：**如何为上下文做减法**——什么时候压缩、怎么压缩、为什么即使上下文没满也应该压缩。核心认知：**上下文学习本质上是检索而非推理**，压缩就是把需要思考才能得到的结论，变成可以直接检索的知识。\n\n## 何时使用\n\n- 工具调用结果动辄数万字符，几轮交互就撑满 128K 窗口\n- Agent 在长任务中「明明窗口没满，却找不到关键信息」或反复纠结已解决的问题\n- 模型在任务尚未完成前提前收尾、草率下结论\n- 设计压缩策略（何时触发、压缩什么、保留什么）或排查压缩副作用\n- 评估「把大任务委派给子 Agent」与「主 Agent 自己做完再压缩」的取舍\n\n## 核心原则\n\n- **三个动机，层次不同**：① 长度与成本约束（窗口有限、token 越贵、延迟越高）；② 提升思考质量——总结后的知识比原始形式更利于模型使用，十几轮搜索的原始结果散落各处，模型每次决策都要在数万 token 中反复检索；③ 缓解**上下文焦虑（Context Anxiety）**——模型认为窗口即将耗尽时可能在任务完成前提前收尾，在未接近耗尽时就提前压缩可能提升决策质量。\n- **上下文窗口是一台只有一半的检索引擎**：检索这一半极强（相当于每次前向传播都内置了 RAG），但缺「提炼层」——上下文里的东西从来不会被自动数一遍、建索引或就地总结。任何「关于这些内容的结论」都要从原始记录现算一遍，代价随内容量 N 上涨。\n- **压缩与状态栏是同一枚硬币的两面**：状态栏把算好的结论**加**进上下文（由代码确定性维护），压缩把臃肿的原始记录**换**成算好的结论（多用一次 LLM 调用蒸馏）。\n- **上下文腐化（Context Rot）≠ 溢出**：溢出是「装不下了」，腐化是「装得下但找不到了」——后者更隐蔽，Agent 表面正常工作，决策质量悄然下降。注意力权重被分散到更多 token 上，无关内容一旦占大头，决策质量明显下滑。\n- **主动显式提炼，不要期望模型自动学习**：与其让模型被动在海量信息中检索，不如主动提供经过提炼的高密度结构化知识。\n- **压缩最容易丢失**：早期的架构决策、约束背后的理由、失败的路径。因此 Agent 需要定期把进展记录到文档，而不是把所有信息零散堆在执行历史里。\n- **隔离优于压缩**：压缩是信息已进入上下文后的事后有损补救；隔离让大体积中间信息根本不进入主上下文。\n\n## 实践模式\n\n### 1. 六种压缩策略实测对比（实验 2-10）\n\n任务：识别并追踪 OpenAI 联合创始人的职业状态；Kimi K3（原生约 1M 窗口，实验刻意限制在 128K 预算以触发压缩）。\n\n| 策略 | 做法 | 迭代 | Token | 压缩率 | 问题 |\n| --- | --- | --- | --- | --- | --- |\n| 无压缩 | 完整保留原始结果 | 5 次即溢出失败 | ~165,000 | — | 7 次搜索累计约 367,000 字符（平均 52,000/次），数次搜索即耗尽 128K |\n| 个体摘要 | 每个结果独立生成 2-3 段摘要 | 12 | 276,608 | 10.9% | 信息碎片化，多页重复描述同一事件 |\n| 组合摘要 | 所有结果合并后一份综合摘要 | 10 | 93,449 | 4.3% | 输入超长必须截断，可能丢失末尾信息 |\n| **上下文感知** | 压缩提示中带入查询意图与已积累信息 | 7 | 40,157 | ~3.0% | 最优平衡点 |\n| 带引用的上下文感知 | 智能压缩 + 每条事实附带来源 URL | 7 | — | — | 内容有损、索引无损，可回溯原文 |\n| 自适应窗口化 | 阈值触发 + 批量压缩 + 防重复 | — | 174,601 | — | 初期保留完整原始信息，灵活性最大 |\n\n> 压缩率定义为「压缩后体积 / 原文体积」，数值越小表示压得越狠。上下文感知压缩将 token 使用量减少 75% 以上。\n\n**上下文感知的提示词写法**：在压缩提示中指定 `Given the search query: {query}` 和 `Current context: {context}`，引导模型生成针对性摘要。实测把约 150K 字符压到 2K 字符时，仍保留创始人姓名与职位变动等后续任务需要的关键信息。\n\n### 2. 自适应窗口化三机制（推荐默认）\n\n- **阈值触发**：持续监控上下文使用率，prompt token 超过窗口 80% 时才激活压缩（如 102,400 / 128K）。\n- **批量压缩**：触发时一次性压缩所有未标记的工具结果，而不是每轮零碎压。\n- **防重复保护**：添加 `[COMPRESSED]` 标记，确保已压缩内容永不被重复处理。\n\n### 3. 压缩与 KV Cache 的共存\n\n压缩不是在单次 API 调用中修改上下文，而是在**两次 API 调用之间**由框架预处理消息列表：\n\n1. **System Prompt 和 Tool Definitions 永远不动**——静态前缀持续缓存。\n2. **压缩对象是对话历史中的 tool results**——替换位置之后的缓存失效，之前的仍有效。\n3. **有意识的权衡**：不压缩则溢出失败；压缩损失部分缓存但长度可控、信息密度更高。**压缩频次需要权衡——频繁压缩频繁破坏缓存，最好在接近阈值时批量压缩，而不是每轮都压。**\n\n### 4. 生产级五层分层压缩（Claude Code 参照）\n\n不同信息有不同保质期，压缩策略应与预期生命周期匹配，按代价从低到高排列：\n\n1. **工具结果预算控制**：大体积输出存磁盘，模型只看摘要预览；替换决策一旦做出就冻结，保证缓存一致性。\n2. **噪声直接删除**：低价值内容（如大量搜索结果中只被用了几行的部分）直接移除，不做摘要——对噪声做摘要只是浪费 token。\n3. **API 层微压缩**：通过上下文编辑能力指示服务端从前缀移除指定工具结果，本地消息不变；零本地实现成本，但移除点之后缓存同样失效，产生一次缓存重建——适合上下文即将溢出、反正要付这次代价时用，不要频繁触发。\n4. **归档式摘要**：逐轮结构化摘要，像 git log 保留每轮独立记录，而非 git squash 合并成一条，保留对话逻辑脉络。\n5. **全量压缩**：LLM 驱动的完整压缩，作为最后手段；分两阶段（先压会话记忆，不行再全量），并配**连续失败熔断器**——生产数据显示大量会话被困在反复压缩失败的循环中，熔断器避免持续烧钱。\n\n### 5. 四条压缩设计原则\n\n- **信息价值的非均匀分布**：关键决策点（如人员名单）> 支撑性证据（如新闻细节）> 冗余噪声（网页导航栏、页脚广告）。\n- **语义完整性**：`Sutskever 于 2024 年 5 月离开 OpenAI` 不能压成 `Sutskever 离开`——时间和公司名是不可丢失的关键信息。\n- **任务相关性**：同样内容在「查找创始人名单」和「了解个人背景」两个任务下应产生不同压缩结果。检索类任务保广度，分析类任务保深度，创作类任务保灵感触发点；理想的 Agent 应按任务类型自适应选择压缩策略。\n- **压缩即理解**：有效压缩需要深层语义理解，负责压缩的模块本身要接近主模型能力，形成「模型调用模型」的递归架构；好处是显式压缩的结果可审查、可跨会话复用。\n\n### 6. 必须保留的四类信息\n\n无论哪种策略，压缩时都要显式 preserve：**decisions（决策）、constraints（约束）、failures（失败路径）、citations（来源引用）**。\n\n### 7. 隔离优于压缩：子 Agent 上下文隔离\n\n对比同一个任务「在代码库中找到处理支付回调的函数」：\n\n- **主 Agent 亲自搜索**：可能把十几个文件数万 token 原始代码纳入主上下文，找到目标后绝大部分沦为永久噪声，还得靠后续压缩清理。\n- **委派给搜索子 Agent**：主上下文只增加两条消息——一条任务描述，一条结论（「函数位于 `src/payment/callbacks.py` 的 `handle_callback`，另有两处调用点」）；中间过程的数万 token 随子 Agent 上下文一起丢弃。\n\n代价是子 Agent 看不到主 Agent 完整上下文，**任务描述必须自包含、目标明确**。Claude Code 的 Task 工具、各类 Deep Research 的检索子 Agent 都是这一模式的生产实现。\n\n## 常见陷阱\n\n- **每轮都压缩**：频繁破坏 KV Cache 前缀，应阈值触发 + 批量压缩。\n- **对噪声做摘要**：把只用了几行的搜索结果压成摘要，纯浪费 token，应直接删除。\n- **压缩时丢掉时间和主体**：语义不完整比不压缩更糟——模型会基于错误事实继续推理。\n- **用远弱于主模型的模块做压缩**：压缩即理解，能力差距大会丢关键信息。\n- **把压缩当成长度问题的唯一解**：即使窗口够大，压缩仍能提升思考质量、缓解上下文焦虑。\n- **让模型自己数数和统计**：查找是注意力强项，统计要遍历全部记录并维护计数状态；应提前把结论写进上下文。\n- **把所有进展只留在执行历史里**：早期架构决策、约束理由、失败路径最容易在压缩中丢失，必须定期落到文档。\n- **给子 Agent 派发含糊任务**：子 Agent 上下文隔离的代价就是任务描述必须自包含，否则结论质量无法保证。\n\n## 配套代码\n\n- `chapter2/context-compression/` — 实验 2-10：实现并对比 6 种压缩策略（`no_compression` / `individual` / `combined` / `context_aware` / `citations` / `windowed`），输出成功率、耗时、token、压缩率、溢出次数对比表；用 `python experiment.py -s context_aware` 单跑，`-m moonshot-v1-128k` 配合 `CONTEXT_WINDOW_SIZE=128K` 复现溢出。\n\n## 深度阅读\n\n- `book/chapter2.md`「上下文压缩策略」\n","skills/async-event-agent/SKILL.md":"---\nname: async-event-agent\ndescription: >-\n  构建异步/事件驱动 Agent，或让 Agent 响应外部事件（新邮件、webhook 回调、IM 消息、定时器、系统告警）、\n  处理工具执行期间的用户打断与多任务并发时使用。覆盖事件循环与安全点、三类事件触发工具、用户沟通与多渠道召回、\n  虚拟身份与隔离执行环境、队列式/取消式/并行式三种事件处理策略及紧急度判定，以及模型原生异步与同步接口兼容两条路线。\n  触发词：异步 Agent、事件驱动、event-driven、webhook、定时器、心跳、任务句柄、打断、steering、并行工具执行。\n---\n\n# 异步与事件驱动 Agent\n\n## 何时使用\n\n- 要让 Agent 在**没有用户输入时也行动**：定时生成报告、周期性检查服务器、跟进未回复的邮件、到工作时间再拨打电话。\n- 要接入**外部事件源**：新邮件到达、API 回调、IM/短信消息、GitHub PR 变更、支付失败告警。\n- 要支持**执行期间被打断**：长任务运行中用户说\"停\"\"改一下预算\"\"先帮我查个天气\"。\n- 要**同时管理多个并发任务**：并行跑几个脚本、先完成的先看结果、未达进度就取消。\n- 要从回合制 ReAct 循环升级为长期运行的**事件循环 Agent**。\n- 要评估某个模型/接口是否支持原生异步，或为不支持的接口设计兼容层。\n- 任务需要在\"发起\"与\"收尾\"之间跨越多个回合（如代打电话、长时审批流）。\n- Agent 需要以\"活人感\"与用户异步沟通（发消息、图片、文件、按紧急度推送提醒），而非必须打开指定会话。\n\n## 核心原则\n\n- **回合制是交互约定，不是环境性质。** 世界不会等模型反应完才变化；任务常在\"发起\"与\"收尾\"之间跨越多个回合。\n- **架构是事件循环，不是轮询。** Agent 是一个长期运行的循环：每轮从输入队列取若干事件 → 追加到轨迹 → 调一次 LLM → 执行它决定的工具 → 回到开头等下一批。不要用\"反复问有没有新消息\"的轮询。\n- **\"主动服务\"的前提是事件能推给 Agent。** Hooks（框架内生命周期事件）、Cron（定时调度）、Heartbeat（每隔 N 分钟唤醒）三种机制里只有后两种让 Agent 自己动起来，且都是**时间驱动**的；对内置渠道之外的第三方事件源（新邮件、外部回调）必须建实时推送通道，否则只能等下一个周期才察觉——这个延迟在验证码等待、三方通话等场景里不可接受。\n- **安全点决定一切。** 同步接口中事件只能在循环边界（一段推理结束、一次工具返回）被消费；紧急事件的取消式处理本质是\"主动提前制造一个安全点\"。取消点必须是工具或推理能安全收尾的位置。\n- **取消 ≠ 撤销。** 发送取消信号只是让执行器停止；已经发生的动作不会回滚。未完成的工具结果用显式占位符表示，不能伪造成功。\n- **三种处理策略按紧急度选择**：\n  - **取消式**（紧急事件：`user.interrupt`、`supervisor.instruction`、`agent.interrupt`、紧急告警）：停当前操作 → 清空队列 → 所有事件连同紧急事件一次性追加到轨迹 → 立即重新调 LLM。\n  - **队列式**（常规事件：`user.input`、`tool.result`、`timer.trigger`）：放入队尾不打断，等本轮到达安全点后**批量**追加，减少往返。\n  - **并行式**（独立、轻量、需快响的查询，如\"今天天气怎么样\"）：在独立推理会话中执行，结果追加进主轨迹并**明确标记为并行**，避免 LLM 混淆。\n  - 硬编码规则有局限；建议用轻量分类 LLM 做事件路由器。\n- **所有输入统一建模为结构化事件**：来源（谁）、渠道（方式）、内容（什么/紧急度）、上下文（与哪个任务相关）。这是防止把工具结果误当用户指令、以及提示注入的前提。异构触发器（webhook、定时器、邮件、数据库变更、文件监听）统一建模后，Agent 才能用一致方式处理不同来源的刺激。\n- **异步语义要写进工具接口**：把\"启动\"和\"完成\"解耦——`initiate_phone_call` 立即返回任务 ID 和初始状态，进展通过 `phone_call_connected` / `phone_call_ended` 等事件通知。工具名和描述本身就要传达异步语义（\"任务发起后立即返回 ID，你可以继续处理其他事项，结束后会收到单独通知\"）。\n- **三条路线按模型能力选择**：原生异步（工具挂起、模型继续、回合中途 steering）> 同步接口兼容（占位符 + 队列 + 重新请求）> 退化回纯串行。用了 `asyncio` 不等于模型具备异步能力，仍需应用层管理事件来源、工具生命周期与结果归属。\n- **可靠处理比能接收更难**：至少要检查——延迟结果能否归入正确任务且缺席时不编造；处理新要求后能否恢复原任务并区分\"修改计划\"与\"停止执行\"；多条更新能否同时遵守而不是只记住最后一条。\n- **事件优先级要动态判断，不是静态排序**：Agent 应像秘书按紧急程度决定先处理哪个、做到一半能否暂停切换，而不是固定先后。长任务异步执行不应阻塞用户交互，被打断的任务要能自然恢复。\n- **占位符只在打断时引入**：常态下 LLM 看到的就是标准同步轨迹；只有出现打断才插入\"工具正在后台执行\"的占位 tool result 修复配对格式，后台真实结果到达后再以带来源和任务 ID 的事件送回。\n\n## 实践模式\n\n1. **搭骨架**：inbox 队列 → 分发器（按紧急度路由）→ 单线程事件循环 → 轨迹存储。参考 `chapter6/async-agent/` 的 `runtime.py::AgentRuntime`（`_dispatcher` 路由紧急度、`_handle_interrupt` 在安全点取消、`run_llm_turn` 推进轨迹）。\n2. **接事件源**：三类事件触发工具——定时器（一次性 + 循环，循环定时器兼容只能主动查询的外部服务）、后台任务监控（监控新增输出或关键词，别让 Agent 反复盯命令行浪费 token）、外部事件通道（实时推送）。每个触发源都要定义过滤规则和足够上下文的 payload，避免无关事件烧算力。\n3. **定义紧急度分类器**：先列事件类型清单和默认策略，再用轻量 LLM 兜住语义边界（\"马上停下来\"→取消式，\"报告用中文发我\"→队列式，\"天气如何\"→并行式）。\n4. **同步兼容层五规则**：assistant 消息与工具调用项立即落轨迹；只有工具真正返回才记 tool result；执行中被打断则生成占位 tool result 后再追加新事件并重新请求；无 steering 时取消未完成生成、只保留已确认消息；非打断事件一律入队批处理。\n5. **多条更新的综合**：给每个未处理事件加显式标记（`[未处理事件 2/4] ...`），末尾附汇总，提示模型必须回应全部，防止只记住最后一条。\n6. **并发任务的状态可观测**：每个异步工具调用都要有任务 ID，支持按 ID 查询进度和取消；完成事件注入主轨迹时带真实结果（退出码、产出哈希），不要只报\"已完成\"。\n6. **触达用户**：用户沟通工具支持异步消息、已读/未读、多渠道（IM/短信/邮件/电话/推送），按紧急程度、用户状态、内容性质、用户偏好选择渠道——通知机制同时是召回机制，用于长任务完成与周期性任务的习惯养成。\n7. **身份与环境**：给 Agent 独立虚拟身份（专属账号、存储、计算环境）跑在隔离的 VM/容器或虚拟手机里；通过共享卷（如 `/workspace/shared`）以**文件路径**而非内容传数据，避免占满上下文；必须登录用户真实账号时走 Human-in-the-Loop（VNC/RDP 让用户亲自登录，会话令牌有效期内复用）。\n8. **验收三层**：事件能否及时到达 → 系统是否按策略执行（取消真的终止了子进程、批量是否齐全）→ 模型是否正确使用了这批更新（结果归属、未完成时不编造、恢复原任务）。可加状态检查点做中断后恢复验证。\n\n## 常见陷阱\n\n- **把\"任务已启动\"当成\"任务已完成\"**：占位符让模型误以为结果已到，在真实结果返回前做出依赖它的判断。必须用明确的任务状态和结果校验，并在评估中检查是否编造了未到达的数据。\n- **注意力分散**：批量事件只回应最后一条，前面的要求被静默丢弃。\n- **轮询冒充异步**：让 Agent 每隔几秒查一次状态，既慢又烧 token；要么用推送通道，要么用循环定时器 + 增量监控。\n- **明文拼接不可见推理**：服务端管理的 reasoning 状态要按提供商续接协议保留，不要自行拼出\"半截思考\"回灌。\n- **取消只发信号不检查**：执行器若不响应取消（类似不检查 `ctx.Done()`），\"停止\"消息发出去任务还在跑。\n- **给所有事件同一优先级**：紧急告警和常规输入走同一条队列，要么该停的停不下来，要么鸡毛蒜皮打断主任务。\n- **直接托管用户个人账号**：Agent 出错或被攻破即暴露全部数字身份；独立身份 + 隔离环境更安全也更可审计。\n- **忽略反机器人机制**：数据中心 IP 的虚拟环境容易被识别，需住宅代理；平台侧还可能有生态级封禁。\n- **用一次失败反推训练原因**：未公开的训练过程不可证，先查系统层的任务状态、事件来源和执行反馈。\n- **忘记维护多个对话线程的关联**：第三方消息如何影响用户情绪、用户在不同线程扮演什么角色、何时综合多线程信息给建议——纯事件路由处理不了这类上下文。\n\n## 配套代码\n\n- `chapter6/async-agent/` — 实验 6-2：事件驱动异步 Agent 框架（Flux），并行工具、打断取消、检查点持久化，含零依赖离线 demo。\n- `chapter6/agent-with-event-trigger/` — 实验 6-1：FastAPI 事件驱动 Agent + 42 个 MCP 工具，演示\"事件到达 → Agent 处理 → 结果输出\"最小闭环。\n- `chapter6/async-agent/` 同时给出离线验收 demo（并行 vs 串行墙钟时间、打断取消后恢复、检查点持久化与还原）与 LLM 场景复现两条路径，适合先跑离线 demo 验证运行时再上真实模型。\n- `chapter6/astra-async-steering/` — 实验 6-3：GPT-6 Astra 原生异步工具调用与回合中途引导，含 `sync` / `async` / `steer_reasoning` / `async_steer` / `unsupported_steer` 五组对照与真实 API 运行记录。\n- 语音相关（时间尺度更细的\"可打断\"场景）：`chapter6/end-to-end-speech/`、`chapter6/streaming-speech/`、`chapter6/controllable-tts/`、`chapter6/live-audio/`、`chapter6/phone-agent/`。\n- 机器人相关（毫秒级连续观察与动作分块）：`chapter6/gemini-xlerobot-navigation/`、`chapter6/rgb-sim2real-grasping/`、`chapter6/xlerobot-teleoperation/`。\n\n## 深度阅读\n\n- `book/chapter6.md`「模态与触发时机的扩展」\n- `book/chapter6.md`「异步与事件驱动：当世界主动找上门」\n- 相关设计文档：`chapter6/async-agent/agent_framework_design.md`（Flux 框架的运行时设计）\n","skills/agent-evaluation/SKILL.md":"---\nname: agent-evaluation\ndescription: 为 Agent 建立或改进评估体系时使用——设计评估指标（Pass@k/Pass^k/成本）、搭建可重复运行的评估环境、选择确定性验证器或 LLM-as-a-Judge 及各自适用边界、编写 Rubric、做失败归因与回归任务、评估驱动的模型选型、判断统计显著性、建设可观测性与内部评估基础设施（消融、AB 测试、特性开关、提示词回归）、从 Benchmark 报告走到系统改进。\n---\n\n# Agent 评估体系\n\n## 何时使用\n- 为 Agent 系统建立第一套评估，或审查现有评估是否可信\n- 选模型、换模型前需要数据依据（新模型公开分高，不代表在你的任务上更好，甚至可能回退）\n- 评估分数下降，要判断是 Agent 退化还是评测系统本身出了问题\n- 需要把\"成功率下降\"这类笼统结论拆成可着手修复的具体问题\n- 为生产 Agent 建设内部评估基础设施：消融实验、AB 测试、特性开关、提示词回归\n- 设计可观测性与生产轨迹回流，让评估集随产品持续演化\n\n## 核心原则\n- **评估的对象是\"模型 + Harness\"组合体，不是模型本身。** 同一模型在不同 Harness 下表现悬殊；表现不佳时先怀疑 Harness，再怀疑模型。\n- **用模型替换实验（model swap）区分两类问题**：固定 Harness 只换模型，分数不涨 → 瓶颈在 Harness；分数随模型能力大幅波动 → 瓶颈在模型能力。消融实验则是关闭 Harness 组件、定位内部哪个部件重要，两者互补，别混用。\n- **先检查评测系统，再动 Agent。** 分数下降先排查：运行环境资源不足导致的随机失败、验证器 bug 把对的判错、用例与生产脱节——这些在数字上与模型退化一模一样，只有回放完整轨迹能区分。\n- **指标口径由业务场景决定。** 同一个 0.8，对退款客服意味着每五名用户一人拿不到退款，对漏洞挖掘已属可观。报告必须写清 k 的口径：同一任务的 k 次独立采样，还是生产流水线连续 k 个任务。\n- **凡是能写成程序化断言的检查就用断言**，LLM 评判只用于确实无法机械判定的维度。确定性验证更便宜、更可复现，适合长期进 CI。\n- **分差要超过噪声、在配对分析中成立、并且能够复现，才值得据此切换模型或发布改动。**\n- **一轮证据只支持与它规模相称的下一步。** 子集 4/4 不能写成系统整体 100%，完整复测通过前不部署。\n\n## 实践模式\n\n### 1. 指标设计：Pass@k / Best@k / Pass^k\n- **Pass@k**（k 次至少一次通过）与 **Best@k**（连续得分取最好）衡量能力上限，适合科研发现、漏洞挖掘、开放式创作——人类会从 k 条候选轨迹里挑出最好的那条。\n- **Pass^k**（连续 k 次全部通过，且不触发安全、合规、幻觉等一票否决项）衡量业务可靠性，适合支付、退款、权限变更、生产部署。两者关系：Pass@k = 1-(1-p)^k，Pass^k = p^k。\n- p=0.6、k=5 时：Pass@5 ≈ 99%，Pass^5 ≈ 7.8%——前一个数字回答\"能不能偶尔创造奇迹\"，后一个才回答\"能否稳定交付\"。\n- 会产生副作用的操作不能\"重试直到成功\"：应在沙盒或可回滚环境中采样，每一次失败都记入可靠性指标。\n\n### 2. 评估环境五要素\n- **数据集**：初始状态、给 Agent 的输入、给模拟器的行为规范与验收标准，打包为一条记录即一个用例。\n- **环境状态**：必须可重置（`initialization_actions` 即重置脚本）；真实性（变化符合业务逻辑）与可控性（每次回到同一起点）兼得。\n- **工具接口**：两侧工具均为原子操作；抽象层次过高（如一个\"解决用户问题\"工具）会使评估退化为对单次函数调用的考察，规划与推理被工具本身吸收。\n- **评分标准**：分层检查项 + 明确的聚合规则（如 `reward_basis`）。\n- **执行协议**：终止信号、轮数上限、模拟用户耐心耗尽主动结束（沟通效率过低本身即计为失败）。\n- 按任务形态选环境类型：单轮问答用无状态单轮环境；搜索+综合用多轮工具环境；改数据库验状态用有状态环境；跑代码查输出用沙盒环境。并行采样与轨迹缓存是标配；工具失败应返回清晰错误信息而非单一失败标志，让 Agent 能据此调整策略。\n\n### 3. 验证方式谱系与自动化评估\n- 横轴是**可机械验证程度**：确定性断言 → 检查项清单 → Rubric + LLM-as-a-Judge → 配对比较。向右移动不意味着放弃左侧。\n- 确定性验证只能判对错、不给原因；生产系统最需要的恰恰是\"错在哪、下一步改什么\"。开放式任务（报告、投诉、创意）无唯一终态、人工评估不可规模化，才上 LLM 评判。\n- **Rubric 四准则**：基于专家指导（捕捉核心事实与推理步骤，而非语言流畅度）；全面覆盖（事实、逻辑、完整性、安全性，且明确 Pitfall）；按重要性加权（必要/重要/可选/陷阱，支持一票否决，如幻觉出现总分归零）；评价标准自包含（禁\"展示深刻理解\"，改为\"引用了至少两个权威理论并准确解释\"）。\n- 每个维度给客观可验证的评分档次、具体示例与边界案例；显式防范奖励作弊（幻觉、讨好用户、关键词堆砌、回避棘手问题）。\n- **长度偏差**防范：Rubric 显式惩罚冗长、规定同类任务长度上限；配对比较前把候选长度控制到相近；定期审计评分与长度的相关性——高分几乎总伴随长回答即已被带偏。\n- **同源模型问题**：Agent 与评判模型同家族时，Agent 会学会利用评判模型的偏好与盲点（古德哈特定律：度量成为优化目标后就不再是好度量）。换不同家族模型评判，并让 Rubric 随分歧持续迭代。\n\n### 4. 失败归因：把 0 分变成可修复的问题\n- 归因对象是轨迹中**首个**导致任务偏离的错误；后续错误多是连锁反应，不能把最后一条报错当根因。\n- 问题案例三来源：用户明确纠正、用户点踩/负面反馈、事后状态检查/规则验证器/LLM 评审发现 Agent 做了不该做的事。\n- **静默失败**（无任何工具报错、Agent 自行宣布完成）的两把定位工具：事实锚点比对（把 Agent 陈述与工具返回值逐步对齐，取首次背离）；轨迹前缀二分（截到第 k 步交人接手，能救回说明错误在 k 之后）。不能用搜报错关键字代替。\n- 归因记录结构化（JSON/YAML）：含任务名、首错步号、错误类别、责任方、原文证据、置信度，区分主因与后果（三次重试是后果，不是三个根因）；多类别并存时按\"最早且能解释后续失败\"选主因。\n- **规则先筛、LLM 再定位**比全量喂 LLM 更便宜也更准：完成声明与实际执行命令的交叉核对、diff 是否触及测试断言与 skip 标记、diff 是否改公开 API/schema 而无迁移，这三类可先用规则筛出嫌疑轨迹。\n- 警惕\"做对了但说错了\"：工具调用和环境状态全对，告知用户的信息却错。只检查终态的评估会整体掩盖它（τ²-bench 基线中约三分之一失败属此类）。根因归属要判到层：观察通道缺失不是\"模型不会 OCR\"。\n- 保存归因记录时，连同任务目标、环境状态、Agent 版本、工具集版本和完整轨迹一起存，供回归测试使用。\n\n### 5. 两层回归任务\n- **端到端回归**：从初始状态跑到终态，验最终状态、必要输出、安全条件。最接近生产结果，但难以定位失败步骤。\n- **轨迹前缀回归**：冻结首错之前的上下文、对话、工具返回与环境状态，只要求下一步或下几步可观察动作。成本低、能隔离单个策略问题；对高可靠生产 Agent，其重要性往往超过端到端口径。\n- 前缀回归答案定义为**可接受动作集合**（\"先读仓库规则\"\"先询问用户\"\"拒绝危险操作\"）+ 禁止动作，而不是唯一标准答案。\n- 按错误类别生成回归任务：流程缺失 → 带计划文档与测试验收条件的端到端任务；工具调用错误 → 截断出错前缀编辑成边界任务；信息反馈类 → 对答复内容本身设断言，而非只查环境状态。\n\n### 6. 评估驱动的模型选型\n- 延迟分两阶段：Prefill 决定首字延迟（TTFT = 排队 + 预填充），Decode 决定出字速度与思考时长（50 tokens/s 生成 2000 思考 token 要 40 秒）。看 p95 尾部延迟而非均值。\n- 在自己工作负载上实测各模型的思考 token 用量与对应收益，不凭公开榜单推断。\n- 成本算**每个任务的平均成本**与成本-性能比：便宜但成功率低的模型因频繁重试可能更贵；输入/输出/缓存 token 分开计价。\n- 指标按场景取：日常 Pass@1，关键操作 Pass^k，探索性任务 Pass@k / Best@k。\n- **预算—能力曲线**：除成功率，报告性能随墙钟时间、token、工具调用次数或算力预算变化的曲线；短预算领先不能外推长时运行能力（RE-Bench：2 小时预算最佳 Agent 约为人类专家 4 倍，8 小时人类反超）。\n- **行为策略也是选型维度**：同一中性 Harness 下测\"行动阈值\"（首次修改前的工具调用数与阅读文件数）。换模型行为改变、同模型跨 Harness 保持倾向 → 支持模型效应，反之支持 Harness 效应；工具步数、并行调用、模型延迟必须分开看。工具步数不是质量分。\n- 异构模型组合（轻量模型管简单、强模型管复杂）必须用评估验证整体效益超过所增复杂度，并检查特定场景是否回退。\n- 成本优化（KV Cache 稳定前缀、上下文压缩、分层选模型）每项独立开关，且**合用时在完整任务中一起实测**——各自节省比例不能相加（28.3% 与 17.5% 合用只有 30%）。\n- 建实时成本监控：按任务类型/模型/用户维度追踪 token 与费用，设单任务成本上限，Agent 陷入循环时自动终止。\n\n### 7. 统计显著性\n- 标准误 SE(p) ≈ √(p(1-p)/n)：100 个用例、成功率 70% 时 95% 置信区间约 ±9 个百分点，\"新模型 73% 对旧模型 70%\"不足以支持切换。\n- 同一批任务比较两个配置用**配对分析**：逐题记录谁胜出，McNemar 检验或配对 bootstrap，不要相减两个独立成功率。\n- 每个配置跑 3–5 个随机种子，报告均值与波动范围；单次运行只能用来筛选方向。\n- 预期收益只有 2–3 个百分点而评估集只有几十题：先扩大样本，标准误按 1/√n 缩小。\n- 并行验证多个假设时考虑**多重比较**：收紧显著性阈值，或对正向结果做独立复跑。\n\n### 8. 可观测性\n- 数据基础是 **trace/span 树**：一次任务执行一条 trace，每个 LLM 调用、工具调用、检索是一个 span（记录输入输出、起止时间、token 消耗、错误），父子关系构成执行树。\n- 采用标准协议（OpenTelemetry + OpenInference 等语义约定）保持采集与分析解耦，避免被单一平台锁定；采集异步批量进行，不拖累响应延迟。\n- 追踪的四大价值：问题诊断（回放而非猜测）、持续优化（定位低成功率工具与空结果检索）、成本管理（识别异常高成本案例）、后训练数据基础。\n- 最有价值的去向是**回流**：生产轨迹筛失败与可疑案例 → 脱敏（去隐私、密钥）→ 沉淀为评估集新用例与回归测试。评估集是随产品演化的活资产，不是一次性静态集合。\n\n### 9. 内部评估基础设施（生产级）\n- **消融**：每个主要特性可独立关闭，定期（如每次大版本发布前）跑消融，发现\"特性债务\"——曾经有效但随模型进化已不再必要的特性。消融开关要在启动路径极早期注入，事后加装不了。\n- **AB 测试**：多臂而非二元（揭示剂量-效应关系，找到最优点）；**区分机制指标与目标指标**（缩短计划文件长度是机制，降低会话级成本才是目标，别把机制当目标，计划过短可能引发更多编辑-检查循环反而更贵）；设护栏指标（满意度、操作次数、错误率不能变差）；记录基线统计（样本量、百分位数、相关性），否则无法判断显著性。\n- **双层特性开关**：编译时开关（代码物理移除，本身即干净的消融机制）+ 运行时开关（服务端下发、本地缓存、宁可稍旧也不能阻塞启动；每个特性曝光事件每会话最多记一次）。特性开关是一等架构组件，服务实验、渐进发布与紧急熔断。\n- **提示词敏感性**：系统提示要能确定性渲染（相同配置输入永远产出相同文本）；建立版本化快照；每次提示词变更在评估集上跑回归，像代码过 CI 一样。\n- **隐私感知分析**：分析接口只接受特殊类型包装的值，类型名即审计线索；隐私约束从第一天设计进去。分析系统无法安全收集数据，评估就无从谈起。\n\n### 10. 从 Benchmark 报告到系统改进的闭环节奏\n- 读报告先找失败集中在哪些任务与能力上，再回放轨迹分清问题出在**看、想、做、验**哪一环；别只盯总分（88% 总分很容易埋掉一个集中的失败簇）。\n- 每轮只改一个变量，形成假设链：加提示词无效 → 换输入通道有效但太贵 → 精简输入保住成功率且降成本。提示写得再详细也补不回 Agent 没看到的信息；输入也不是越多越好。\n- 小范围通过只获得扩大测试的资格：标准环境、全任务 × 多种子，同时查成功率不降、token 不超阈值、延迟不超上限，才能讨论部署。\n\n## 常见陷阱\n- 看到分数下降就改 Agent 代码，不先排查评测系统（资源不足、验证器 bug、用例脱节都会伪装成模型退化）。\n- 用公开基准分数直接做产品决策——GAIA 上提升两个百分点与退款成功率没有必然关系。\n- 把最后一条报错当根因；或把根因归错层（观察通道缺失被记成\"模型不会 OCR\"，于是去换模型、做 OCR 训练）。\n- 只检查环境终态，漏掉\"做对了但说错了\"。\n- Rubric 写\"展示深刻理解\"这类不可验证的抽象标准；没有一票否决项，被关键词堆砌式奖励作弊刷分。\n- 评分从未审计长度相关性，评判已被长度偏差带偏而不自知。\n- 同源模型既当运动员又当裁判，Goodhart 之后评分虚高。\n- 把多项上下文优化的节省比例直接相加；或凭单次运行的结果做选型决策。\n- 配对比较不交换候选顺序，位置偏差让先出现者系统性占优。\n- 子集小样本通过后直接当整体水平汇报，结论超出证据规模。\n\n## 配套代码\n- `chapter7/tau2-bench-eval/` — τ²-bench telecom 五任务双控环境评估：环境 reset、轨迹保存、二元奖励与失败任务（错选线路漏做充值）分析\n- `chapter7/android-world/` — T3A 运行记录、失败归因笔记，以及 diagnose→hypothesize→experiment→decide→iterate 的五阶段改进闭环\n- `chapter7/public-health-reporting-eval/` — 合成数据上的确定性六点评分：工具选择、参数、答案、证据行、无依据声明处罚\n- `chapter7/agent-cost-analysis/` — 八轮退款任务全链路成本拆解，KV-cache 友好与上下文压缩的 2×2 A/B 量化\n- `chapter7/model-benchmark/` — 多维度模型基准 campaign：吞吐/TTFT/尾延迟、168 小时可用性、限流爬坡、同模型不同供应商对照\n- `chapter7/model-action-threshold/` — 固定 Coding Harness 下测量不同模型的行动阈值（首次修改前的工具调用与文件阅读）\n- `chapter7/elo-leaderboard/` — 从 Chatbot Arena 真实投票实现 Elo/Bradley-Terry 配对排名与历史快照\n\n## 深度阅读\n- `book/chapter7.md`「评估指标：成功的定义」\n- `book/chapter7.md`「评估环境」\n- `book/chapter7.md`「自动化评估方法」\n- `book/chapter7.md`「评估驱动的模型选型」\n- `book/chapter7.md`「评估结果的统计显著性」\n- `book/chapter7.md`「Agent 的可观测性」\n- `book/chapter7.md`「从 Benchmark 报告到系统改进」\n- `book/chapter7.md`「从外部评估到内部评估：生产级 Agent 的评估基础设施」\n","skills/agent-evolution/SKILL.md":"---\nname: agent-evolution\ndescription: 让 Agent 从运行经验中持续学习、构建自进化闭环时使用——涵盖从运行轨迹提取学习信号（三层轨迹验证）、四种进化方式（经验知识库、Prompt/Skill、程序/Harness、模型参数）的适用边界与选择依据、Prompt 自动优化、轨迹编译为程序、Agent 自我修改与安全门禁、睡眠学习与长期分层评估。触发词：持续进化、自进化、经验学习、轨迹验证器、自我修改、进化闭环。\n---\n\n# Agent 持续进化\n\n## 何时使用\n\n- 部署后的 Agent 反复犯同类错误，需要把运行经验转化为持久能力\n- 需要为运行轨迹构建验证器 / 评价器，判断\"哪里错、为什么错、证据在哪里\"\n- 面对一个待修复缺陷，需要决定经验应写进知识库、Prompt/Skill、程序还是模型参数\n- 要做 Prompt 自动优化、失败轨迹规则提炼、浏览器轨迹转工作流等单点进化\n- 设计 Agent 自我修改流程（改自身 Harness、工具、重试策略），需要验证与发布门槛\n- 搭建\"在线执行 + 离线进化\"双循环，或设计记忆/Skill 的整理、淘汰与回滚机制\n- 评估系统是否真的在进化（而非只保存或只追加反馈）\n\n## 核心原则\n\n- **保存经历 ≠ 从经历中学习**。学习发生在系统主动完成\"评价、对照、归纳、验证\"之后，而非日志写入磁盘的那一刻。一百条轨迹放进向量库只是可检索案例，不自动完成跨案例比较。\n- **先评价再更新**。不知道任务是否完成、哪一步导致成败，模型的反思只是猜测。评价一条轨迹依次回答三问：事情是否办成（结果）、是否以允许的方式办成（过程）、是否让用户舒服（质量）。\n- **三层验证，底层优先**。结果验证器读环境真值（测试、数据库、工具返回），最应优先建立且比模型自述可靠；过程验证器用政策库/权限表/动作序列做代码判定；质量层才用 LLM Rubric。结果正确不代表过程正确（删掉失败用例也能让测试通过）。\n- **学习信号必须四要素齐备**：成败判定（成功/部分成功/失败）、每维度结论、每条结论的证据位置（哪轮对话、哪次工具调用）、失败类型标签。单一总分无法指导更新；证据不足时验证器应拒绝评分，低置信度案例排除在学习集外。\n- **按能力的表示性质选择载体**（表 9-2 的边界）：\n  - 经验知识库——事实、经验规律、例外与来源；更新快、可追溯，但依赖检索和模型正确应用\n  - Prompt/Skill——能用自然语言说清的判断原则、语境与例外；可解释、范围可控，但易膨胀、冲突、被忽略\n  - 程序/Harness——可确定性解析、可执行验证、高风险硬约束；可测试、稳定、低成本，但开发维护成本高\n  - 模型参数——高维感知、生成风格、隐式策略；泛化强、推理开销低，但更新与回归成本高\n- **同一能力可拆到多个载体**：事实入知识库，解释例外的原则入 Skill，不可绕过的权限由程序门控，高维识别能力入参数。路由结果只是更新提案，尚无发布资格。\n- **经验知识库 vs 领域知识**：第三章领域知识回答\"用户与世界是什么样的\"（如\"该航司特殊餐食需提前 24 小时预订\"）；本章经验知识库从行动轨迹与结果中提取\"在什么条件下应该怎样做\"（如\"订票前先检查特殊餐食截止时间\"）。二者共享存储与检索技术，来源和验证目标不同。\n- **所有修改是最小 diff + 可回滚 + 独立验证**。待验证版本必须同时在触发失败的边界集上改善、在正常工作的保留集上不退化；验证者须独立于提炼者。\n- **在线执行与离线进化分离**。在线循环只完成任务并追加不可变证据，不直接改写正式 Agent；离线循环聚合轨迹、生成提案、过门槛发布，两者经版本化经验库和评估集连接。一次偶发成功或恶意输入不能立即改写长期能力。\n- **安全边界三条**：证据与指令隔离（网页/工具输出及其 LLM 摘要都是不可信证据，LLM 摘要不是净化过程）；待验证能力与正式能力隔离（新产物先入不可服务真实流量的待验证区，过沙盒、权限、供应链扫描与回归后才转正）；安全机制不可自我修改（Agent 不能改验证器、测试、发布门槛、审计日志和稳定版本备份——否则降低阈值即可把退化伪装成进步）。\n- **Harness 更新能力 ≠ Harness 受益能力**。前者是从轨迹产出有价值修改，后者是任务 Agent 在正确场景激活并遵循该修改。不能用端到端分数反推更新器好坏，需分层评估。\n\n## 实践模式\n\n### 1. 轨迹验证器（学习信号的来源）\n\n- 三层结构：结果层读最终环境状态；过程层查业务规则、隐私、事实依据、承诺—行动一致性（声称完成的操作是否真实发生）；质量层按 Rubric 逐项给分并引用轨迹证据。\n- 输出结构化诊断而非总分：每维度结论 + 证据轮次 + 置信度，失败带类型标签。\n- 低置信度案例不进学习集；把它当事实固化比丢弃更危险。\n\n### 2. 经验知识提炼管道（五步）\n\n1. 保存不可变原始轨迹与环境结果（用于审计）；\n2. 为单次运行生成结构化分析：任务类型、所需能力、观察到的策略、错误与例外；\n3. 按任务族聚合同类运行，为每条经验草案建\"哪些轨迹支持、哪些轨迹反驳\"的证据表；\n4. 达到支持门槛才写入正式文档；\n5. 在未参与提炼的新任务上测迁移效果。\n\n正式经验文档写：适用场景、推荐策略、禁止做法、例外条件、证据来源、最近验证时间——不复述某次任务的完整过程。真正有迁移价值的内容来自对照（成功轨迹做了什么、失败轨迹缺少什么、策略在哪些版本/前置条件下失效），Reflexion 式自然语言反思可参与生成草案，但反思本身不是证据。\n\n### 3. 经验写成 Prompt/Skill（指令更新）\n\n- 触发条件：多条相似轨迹反复暴露同一种策略错误，且错误能用语言清楚描述。\n- 形式：带来源的最小 diff（`old_str → new_str`），不让模型每轮重写整份 Prompt——重写会丢细节、把相互制约的条件合并成过度抽象的原则。可参考 ACE：上下文维护成带稳定标识符的条目集合，增量更新 + 确定性合并去重。\n- 发布门槛：补丁非空、来源可追溯、保留集不退化、边界集确有改善；通过才灰度（`release_to_canary`），否则拒绝。待验证补丁写入 working 文件，不覆盖正式 Prompt。\n- Skill 与 Harness 边界：Skill 负责理解语境、提问、整理 Spec；Harness 负责缺少确认时否决高风险写入。否决器不替模型决定方案。\n- 提炼输入决定归纳质量：给失败摘要+报错文本，模型只归纳出教训；补充 Agent/用户各自的工具清单，才能归纳出职责归属。\n\n### 4. 经验写成程序（程序化经验）\n\n- 浏览器工作流六步生命周期：捕获轨迹（保存动作参数、URL、元素定位证据——定位信息只能用于再找元素，不能证明任务完成）→ 参数化（字面量换模板变量）→ 定义状态检查（动作前/后检查 + 最终状态检查，最终检查必须读真实页面或后端状态）→ 独立回放验证（沙盒/测试站点重置到独立初始状态后完整回放，全部谓词通过才发布）→ 匹配与回放（能力库按意图检索，直接执行，无需逐步调 LLM）→ 失效与重学（谓词失败、Schema 变化即回退完整 Agent 模式）。\n- 自我修改走软件发布流程，而非运行中进程覆盖自身：从稳定版本切隔离 worktree → Coding Agent 生成最小补丁 → 静态检查、单测、安全扫描、失败轨迹重放、旧任务回归 → 可灰度新版本。每次修改请求是一份可证伪的变更契约：失败证据、推断根因、归属组件、修改提案、预期修复的行为、可能受损的行为、分别验证两者的用例。\n- 提案生成器的输入不只有失败案例，还必须有成功约束（不能破坏的性质）和此前被拒记录（避免换说法重复提交），共同构成有边界的方案空间。\n\n### 5. 经验写入参数\n\n- 判断依据不是\"任务是否长期稳定\"，而是能力的表示性质：能否被外部符号较完整表达。域偏移用 LoRA/持续微调，快速变化的风格用周期性偏好训练。\n- 数据来源：经评价的生产轨迹——高质量示范进 SFT，明确偏好形成成对数据，有可靠环境奖励的交互用于 RL。\n\n### 6. 双循环与睡眠学习\n\n- 离线整合五步：触发（时间/轨迹量/容量/错误频率门槛，且无高优先级在线任务）→ 定向（读正式知识、Skill 目录及版本，了解不可修改边界）→ 采集与整合（合并重复、标记冲突与适用条件，优先生成局部补丁）→ 验证与审批（迁移集/保留集/安全集，高风险等人工批准）→ 修剪与索引（长期不用或被推翻的标记过期、归档，保留来源与回滚版本）。\n- 定期对抗上下文腐化：合并重复经验、把局部规则从全局 Prompt 移入领域 Skill、重验长期未用的工具、删除被推翻的知识、从原始基座重训 LoRA。\n\n### 7. 进化效果的分层评估\n\n- 指标（表 9-3）：更新提案有效率（独立验证中的接受率与增益）、产物激活率（是否正确场景加载）、遵循成功率（动作序列与过程验证器）、保留任务集增益（未参与进化任务的成功率/质量/成本）。\n- 长期评价至少五类：回退（新旧经验冲突）、泛化（测试集外场景）、Token 效率、安全性（规则/隐私/拒绝边界是否漂移）、长期工程质量（维护复杂度、向后兼容、调试负担）。\n- 开放式任务（科研、战略）反馈慢且答案不唯一，需改变证据结构：结论与证据分离（每类声明链接可审计来源）、保留负面结果与停止原因、维护搜索多样性（不全押当前最高分）、让人类在更高层介入（定义问题、审查评价标准、决定何时停止）。\n\n## 常见陷阱\n\n- 把用户满意度或单一总分当学习信号：满意度上升可能伴随规则违规率上升，需护栏指标。\n- 把低置信度结论当事实固化，或把 LLM 摘要当无害化后的指令直接纳入 Skill。\n- **模型会把观察到的行为当作应然的行为**：轨迹中最频繁出现的是转人工，模型就可能把\"三次失败即转接\"写成规则——而该环境下转接必然失败，等于把失败写进规范。提炼产物必须经与提炼者独立的验证。\n- 让模型每轮重写整份 Prompt/记忆，导致重要细节在多轮改写中消失。\n- 把\"动作执行过\"当\"任务完成\"：没有最终状态检查的回放，只是把错误更快地重复。\n- 待验证版本直接发布，或发布门槛可被提案自身修改（安全门不能由修改者自证）。\n- 只修当前失败案例，不顾保留集回退、泛化、Token 成本和长期工程质量。\n- 只追加不淘汰：知识无限增长引发检索错误、知识冲突、灾难性遗忘，抵消学习收益。\n- 用端到端分数判断更新器好坏，忽略激活率与遵循失败。\n- 提案被接受 ≠ 下游能力提升：一次提案通过只证明更新流程成立，仍需在相同任务和模型下做开关消融。\n\n## 配套代码\n\n- `chapter9/trajectory-verifier/` — 实验 9-1：三层轨迹验证器，对比单一总分与带证据的多维诊断\n- `chapter9/tau2-escalation-experience/` — 实验 9-2：从 τ²-bench telecom 失败轨迹提炼转人工与工具使用规则，三臂对照\n- `chapter9/prompt-auto-optimization/` — 实验 9-3：航空客服失败轨迹 → 三维诊断 → 最小 Prompt diff → 发布门槛\n- `chapter9/ai-style-skill/` — 补充案例：用户\"AI 味\"before/after 纠正持续提炼为写作 Skill，LLM judge + 金标校准\n- `chapter9/browser-use-rpa/` — 实验 9-5：浏览器轨迹编译为带状态谓词的待验证工作流，独立回放后才入能力库\n- `chapter9/self-modifying-agent/` — 实验 9-6：由失败轨迹触发重试/熔断代码自我修改，Docker 沙箱验证提案\n- `chapter9/harness-safety-gate/` — 实验 9-7：用户反馈触发高风险操作确认门禁，AST 扫描 + 隔离回放\n- `chapter9/hermes-self-evolution/` — 实验 9-8：Hermes 读本书后自主选题、修改自身并接受独立 Reviewer 审查\n- `chapter9/self-evolution-eval/` — 实验 9-9：四阶段纵向评估（学习/迁移/规则变化/保持），区分保存、追加与可淘汰记忆\n- `chapter9/self-evolving-tools/` — Alita 式补充案例：Agent 从零搜索、沙盒测试并封装新工具入库复用\n\n## 深度阅读\n\n- `book/chapter9.md`「从运行轨迹中获得学习信号」— 三层验证结构与学习信号四要素\n- `book/chapter9.md`「Agent 持续进化的四种方法」— 知识、指令、程序、参数的适用边界与各自流程\n- `book/chapter9.md`「构建可长期运行的持续进化闭环」— 双循环、睡眠学习、分层评估与安全边界\n","skills/computer-use/SKILL.md":"---\nname: computer-use\ndescription: >-\n  构建 GUI 自动化 Agent、让 Agent 像人一样看屏幕并用鼠标键盘操作桌面或浏览器软件时使用。\n  覆盖感知-思考-行动循环、动作空间（GUI/bash/文件编辑）、视觉定位 Grounding 三条路线\n  （结构化元素索引、Set-of-Mark、纯坐标预测）、分辨率坐标缩放、关键帧观察接口、世界模型与移动端生态壁垒。\n  触发词：Computer Use、GUI 自动化、截图、Grounding、browser-use、Set-of-Mark、视觉定位、坐标缩放、OSWorld。\n---\n\n# Computer Use：GUI 自动化 Agent\n\n## 何时使用\n\n- 要让 Agent 操作没有 API 的软件：填表、改系统设置、在网页上完成多步流程。\n- 要评估或实现\"截图 → 决策 → 执行动作\"的闭环，选模型、选 grounding 方案、选框架。\n- 定位不准、坐标偏移、点击错元素，需要排查 grounding 与坐标缩放链路。\n- Agent 每 3–5 秒才看一眼屏幕，错过通知、视频、弹窗等\"两帧之间发生的事\"。\n- 要把 Computer Use 扩展到移动端（Android 无障碍服务）或评估平台封禁风险。\n- 设计不可逆操作（删除、购买、提交）前的确认与安全边界。\n- 要减少操作步数与等待时间，让 Agent 达到\"实用\"而不只是\"答对\"（对照 OSWorld-Human 的人类基线）。\n- 没有编程 API 可用、Selenium 之类脚本化方案难以维护页面的场景。\n- 要在容器化虚拟桌面中跑 Agent，并隔离不可逆操作对真实环境的影响。\n\n## 核心原则\n\n- **核心是感知-思考-行动循环**：截图 → 多模态模型输出思考 + 一个动作 → 执行层真实执行（移动鼠标、点击、输入）→ 等界面响应再截图进入下一轮。\n- **区分\"看懂界面\"和\"完成任务\"**：前者可用一次截图问答测量（多模态理解）；后者要求把理解和动作放进闭环，处理页面加载、状态变化、误操作和不可逆后果。每执行一步都要**重新确认现实是否仍符合计划**。\n- **动作空间分三类**：GUI 操作（鼠标移动/点击/拖拽/滚动、键盘输入/组合键/长按、截图与等待）、持久 bash 会话（跨调用保持环境状态，用哨兵字符串判命令是否执行完）、字符串匹配的文件编辑（比整文件覆盖更精确，可撤销）。\n- **动作空间不是供应商私有协议**：只要 Harness 能把同样的截图、动作约束和执行结果转换成目标模型支持的消息与结构化输出，Claude、开放权重视觉模型和自托管端点都能驱动同一个循环。\n- **Grounding 优先把定位变成选择题**：先给元素编号，模型只报 ID，系统换算中心坐标。选择题比填空题容易答对——模型说\"点击 [123]\"而不是\"点击 (350, 464)\"。三条路线按界面性质选：\n  - **结构化元素索引**（DOM / Accessibility Tree，browser-use 路线）：结构化信息可得时首选，最精确稳定，无分割模型的漏检误检。\n  - **Set-of-Mark 视觉标注**：用分割模型切候选区域叠加编号，不需要 DOM，原生桌面软件、游戏、Canvas/WebGL 界面适用。\n  - **纯坐标预测**（SeeClick、Claude computer use）：直接在 GUI 截图-坐标配对上训练的模型更直接，省去标注步骤，但小元素和密集界面精度差。\n- **坐标预测必须做分辨率管理**：模型对坐标的理解依赖训练分辨率，不匹配就系统性偏移。按**宽高比**选最接近的目标分辨率做双向缩放（如 2560×1440 的 16:9 屏幕选 FWXGA 1366×768，模型返回 (683,384) 反推真实坐标约 (1280,720)）。切忌非等比拉伸把画面压扁。\n- **\"屏幕是静止的\"是危险假设**：该重新设计的是观察接口而不是动作接口——用关键帧截图（小模型判断是否有意义的变化，变化频繁时约 1 秒一次）、音量门控的语音转写、把截图压成一句持久文字描述来压缩多模态历史。\n- **世界模型带来\"推测执行\"**：行动前预测候选动作造成的状态差异，一致就沿计划继续，偏离才停下重规划。要预测的是**可检查的状态差异**（窗口、焦点、滚动位置、输入框内容、加载状态、权限、网络返回），不是生成逼真未来截图。\n- **生态壁垒是结构性问题**：Agent 直达目标会绕过广告与推荐变现链路，平台有动机封禁；这不只是 CAPTCHA 的技术对抗，短期难以调和。\n- **循环节奏与尺度**：Computer Use 的时间尺度是亚秒到秒——屏幕在两帧之间持续变化，因此\"动作后重新确认现实\"不是可选项而是循环的必要组成部分。这与语音（10ms–1s，可被打断）和机器人（毫秒级，动作分块可抢占）是不同的时机问题。\n- **结构化索引不省 token 但省错误**：把所有可交互元素及其属性发给模型成本高，但换来定位准确稳定，且免去分割模型的漏检误检——这是值得的交换。\n- **browser-use 式四步流程**：CDP 取 DOM 与无障碍信息 → 检测可交互元素 → 标注唯一 ID 并在截图绘边界框 → 同步生成\"ID → 元素描述\"文本列表；模型只输出 ID，系统用中心坐标执行。\n\n## 实践模式\n\n1. **搭循环**：Harness 负责截图、把动作约束转换成目标模型支持的消息与结构化输出、执行结果回传。同一套循环可换驱动模型（Claude、开放权重 VLM、自托管 vLLM/SGLang 端点），并保留实际端点与模型 ID 以便区分实验组。\n2. **选 grounding 路线**：先问\"这个界面有没有结构化信息可得\"——Web 走 DOM/a11y 索引（CDP 取 DOM → 检测可交互元素 → 标注唯一 ID 并在截图绘边界框 → 同步生成 ID 到元素的文本列表）；原生桌面软件、Canvas/WebGL、游戏走视觉标注或坐标预测；模型做过 GUI 定位训练才优先坐标预测。\n3. **实现坐标缩放层**：枚举目标模型支持的分辨率档位，按宽高比匹配；截图时等比缩放送入，动作坐标按比例反算回真实屏幕。\n4. **每步只做一个动作**：保留每步截图与动作轨迹，便于回放和验收；页面加载用 `wait`，不要盲点。\n5. **安全边界**：默认只读；不点击验证码、不登录、不提交、不购买、不改外部数据；不可逆操作先在隔离虚拟桌面预测是否出现确认框，必要时请求用户确认。凭证不落盘，最终截图要能佐证结论。\n6. **恢复策略要预置**：遇到验证码、权限弹窗、页面 404 时按只读恢复指令改走可达路径（如改用公开 JSON 接口取数据），而不是反复重试或点击挑战。\n6. **增强观察接口**：关键帧 + 音量门控 ASR + 文字描述三件套，让 Agent 对弹窗、视频、会议人声有感知，并让被清理出上下文的原图仍留下文字痕迹。\n7. **移动端适配**：动作空间从\"鼠标坐标 + 键盘\"换成无障碍服务 API（如 Android AccessibilityService）读写元素、下发点击与输入；坐标语义变为手势类型（单击/长按/滑动起点）的边界。\n8. **验收要测量效率**：准确率达到人类水平不等于实用——对照人类操作步数与等待时间，把\"步骤数、总时长\"纳入验收指标，并记录真实运行证据（截图哈希、动作轨迹）。\n\n## 常见陷阱\n\n- **把截图答对当成任务完成**：没有闭环、不重新确认现实，页面早已跳转还在点原来的坐标。\n- **非等比缩放**：把 16:9 硬塞进 4:3，画面横向压扁，坐标判断整体偏移。\n- **分辨率不匹配不换算**：直接把模型在训练分辨率下输出的坐标当真实屏幕坐标用。\n- **密集界面/小元素上裸报坐标**：三条路线在此都容易出错，优先编号选择题方案。\n- **分割模型漏检误检**：视觉标注路线里候选区域切错，模型只能从错的选项里选。\n- **每步多个动作**：中间页面变化无法回放定位，错误无法归因。\n- **假设屏幕静止**：两帧之间的通知、视频、声音全部丢失，任务在错误的世界观上推进。\n- **忽视平台封禁与验证码**：消费级场景中账号可能被直接限制，比技术问题更难解。\n- **只关注准确率不看效率**：步骤数和等待时间远超人类，成功也不可用。\n- **把不同模型的运行混为一组**：供应商与开放权重是不同实验组，必须分别记录端点、模型 ID 与证据。\n\n## 配套代码\n\n- `chapter6/claude-computer-use-native/` — 实验 6-8（Anthropic 原生路径）：容器化 Ubuntu 桌面中的官方 Computer Use Demo，`computer` / `bash` / 编辑器三类原生工具的真实运行与确定性验收记录。\n- `chapter6/computer-use-open-model/` — 实验 6-8/6-9（开放模型路径）：同一\"截图 → 结构化动作 → 浏览器执行\"循环，默认 Qwen3-VL 32B Instruct 驱动 browser-use，可接 OpenRouter 或自托管 vLLM/SGLang；含端点合格性契约（收截图、产出 Browser Use 动作 schema、每步一个动作、不静默替换模型）。\n- 两个 companion 都保留了真实运行证据（截图哈希、动作轨迹、确定性验收），可作为自己实现时的证据门禁模板；其中原生路径还记录了一次撞上 Google reCAPTCHA 后按只读恢复指令改走公开天气 JSON 接口、全程未点击挑战的完整轨迹。\n- 语音相关（同为\"时机\"扩展，可作对照）：`chapter6/end-to-end-speech/`、`chapter6/streaming-speech/`、`chapter6/controllable-tts/`、`chapter6/live-audio/`、`chapter6/phone-agent/`。\n- 机器人相关（从屏幕像素到物理传感器）：`chapter6/gemini-xlerobot-navigation/`、`chapter6/rgb-sim2real-grasping/`、`chapter6/xlerobot-teleoperation/`。\n- 移动端基准与评测可参考第七章 AndroidWorld 一节；本章 `chapter6/phone-agent/` 给出真实手机上的 Agent 驱动样例。\n\n## 深度阅读\n\n- `book/chapter6.md`「模态与触发时机的扩展」\n- `book/chapter6.md`「Computer Use：GUI 自动化 Agent」\n- 实验记录与证据门禁模板见 `chapter6/computer-use-open-model/` 与 `chapter6/claude-computer-use-native/` 的 README 与 `validation/` 目录。\n","skills/context-engineering/SKILL.md":"---\nname: context-engineering\ndescription: 设计 Agent 系统提示词、上下文结构或按需加载的 Skill 时使用——覆盖 API 消息角色与「静态前缀 + 轨迹」结构、系统提示词写法（结构化、SOP、业务规则细化、few-shot）、Agent Skills 渐进式披露与 SKILL.md 编写、提示注入的上下文层防御，以及注意力位置偏好等布局原则。\n---\n\n# 上下文工程总纲\n\n上下文是 Agent 在每个决策点实际「看到」的全部信息：系统提示词、工具定义、用户消息、模型回复、工具执行结果。上下文工程就是系统性设计、组织、供给这些信息——模型智力只是基础，**上下文质量才是 Agent 能力的真正关键**。一个中等能力的模型配上精心组织的上下文，往往胜过一个顶级模型在信息匮乏下的盲目摸索。\n\n## 何时使用\n\n- 设计或重构 Agent 的系统提示词、工具定义、消息列表结构\n- 编写 / 审查一份 `SKILL.md`（元数据、路由描述、正文分层）\n- 排查「Agent 行为不稳定、违反业务规则、重复犯错、忘记约束」\n- 决定哪些知识该进系统提示词、哪些该做成按需加载的 Skill\n- 评估外部内容（网页、文档、邮件）进入上下文后的安全风险\n\n## 核心原则\n\n- **API 无状态，上下文由框架每轮重建。** 模型不会「记住」上一轮，Agent 框架必须每次都把完整消息历史送回去。\n- **上下文 = 四种消息角色 + `tools` 字段。** `system`（开发者规则，通常只有一条且在最前）、`user`（终端用户输入）、`assistant`（模型回复含 `tool_calls`）、`tool`（框架执行结果，靠 `tool_call_id` 与调用关联）；工具定义走请求顶层 `tools` 字段，不是消息角色。\n- **静态前缀 + 动态轨迹。** system prompt 与 tool definitions 全程不变，对话历史（trajectory）随交互持续增长。所有后续技术都在优化这个列表的内容与结构。\n- **模型决策、框架执行。** 模型只发出工具调用请求，真正执行工具的是 Agent 框架；循环「请求 → tool_calls → 执行 → 送回结果 → 再请求」就是 ReAct 循环的 API 实现。\n- **最低信息需求三件套**：代码信息（结构、职责、规范）、流程规范（分支、提交、评审、CI/CD）、环境信息（配置、数据库、密钥管理）。缺哪一类，Agent 就在哪一类上出错。\n- **新员工检验法**：如果一个聪明的新员工读完你的系统提示词还不知道该怎么做，Agent 也一样不知道。\n- **上下文学习是检索而非推理**：模型擅长从已有内容中查找，不擅长在前向传播中归纳统计。位置偏好（Lost in the Middle）意味着开头和结尾注意力最高，中部易被忽视——关键信息放两端。\n- **与模型厂商的训练方法保持一致**：选择 Agent 交互模式时优先采用厂商专门训练过的模式（Skills、tool_search 等），同生态内表现最佳。\n\n## 实践模式\n\n### 1. 系统提示词四维度\n\n- **语气与风格**：用明确指令而非请求，如 `You MUST answer concisely with fewer than 4 lines`；无法完成任务时 `keep your response to 1-2 sentences` 且不要解释为什么不能做。大写（`NEVER do X`）比 `Please avoid doing X` 更能引起注意，但过度使用会稀释效果，只留给真正关键的约束。\n- **结构化**：Markdown 标题（`#`、`##`）提供人可读的层次，XML 标签提供机器可解析的精确语义（`<file_operation>`、`<network_request>`），标签名本身携带语义。双层配合：Markdown 管组织逻辑，XML 管语义边界。\n- **流程驱动而非规则堆砌**：写成带分支的 SOP（Step 1 Validation → Step 2 Classification → ... → Step 5 Verification），让模型任何时刻都知道自己在哪个阶段、异常时按阶段处理，而不是遍历上百条零散规则找匹配项。\n- **业务规则细化到可执行**：把模糊规则（「根据任务情况选择合适的计费类型」）改写成布尔判断，例如 `NEVER use percentage_based_one_time for refunds and service cancellations. Use fixed_fee instead.`；成功率阈值直接映射到行为（>60% 可退款、<30% 拒绝任务）；计费粒度写死（每分钟 $0.05，汇总四舍五入到整数美元），并明确「节省」只基于现有账单计算。**提示词由产品经理基于线上数据设计，工程师负责准确编码，不擅自决定业务逻辑。**\n\n### 2. few-shot 示例的两个决策点\n\n- **位置**：放系统提示词 = 成为静态前缀对所有请求生效；或伪造一组 user/assistant 消息放在首轮对话中，适合按会话类型选用不同示例集。\n- **稳定性**：无论放哪，示例都处于上下文靠前区域，一旦确定必须字节级稳定——按请求动态检索「最相关」的示例等于每轮改写前缀，缓存会持续失效。为每类任务准备固定示例集。\n- **数量**：两三个精心挑选、覆盖边界情况的示例，胜过十个大同小异的示例——后者既占上下文，又稀释对规则本身的注意力。\n\n### 3. Agent Skills：渐进式披露三层\n\n- **第一层 元数据**：`SKILL.md` 顶部 YAML frontmatter 的 `name` + `description`，在正文加载前对 Agent 可见，用于路由判断。`description` 要写得像路由条件而非功能介绍：明确「何时使用」「何时不使用」的边界，给几条典型反例。写 `help with backend` 这种宽泛描述等于任何后端工作都能触发，路由必然失准。\n- **第二层 核心流程**：模型判断需要该 Skill 时才加载完整 `SKILL.md`（斜杠命令由客户端本地拦截展开；模型自主触发则多一次 ReAct 往返，正文作为 user message 追加）。\n- **第三层 细则**：通过文件引用深入到子文档（如 `html2pptx.md`、`reference.md`），Agent 按需选择性深入。\n- **上下文成本**：所有 Harness 都遵循「少量目录常驻、完整正文按需加载」。Skill 正文在调用位置追加到轨迹末尾，不改写已建立的前缀，因此对 KV Cache 友好。\n- **SKILL.md 四部分**（宝玉《图解 Skill》）：角色与读者；核心原则只留 3–5 条并配正反例；禁止清单记录高频错误、越权动作并写清合法例外；参考资料放术语表、模板、范文。规则写成「作用域 + 动作 + 例外 + 验证方式」，不要堆成越来越长的禁用词表。\n- Skill 还可捆绑可执行代码工具和模板文件，自包含、可独立版本控制。\n\n### 4. 上下文布局决策骨架\n\n```python\nstable_prefix = system_message            # 定了就不改\nstable_tools  = core_tool_schemas         # 固定顺序\ntrajectory    = load_message_history(session)\nstatus_message = make_status_message(derive_current_state(trajectory))\n\nif estimated_tokens(stable_prefix, trajectory, status_message) > budget:\n    trajectory = compress_old_evidence(\n        trajectory, preserve=[decisions, constraints, failures, citations]\n    )\n\nrequest.messages = [stable_prefix] + trajectory + [status_message]\nrequest.tools = stable_tools\n```\n\n### 5. 提示注入的上下文层防御\n\n第一道防线是帮模型分清「指令」与「数据」：\n\n- **来源标记**：外部内容注入前用 `<external_content source=\"webpage\">...</external_content>` 包裹并标注来源。\n- **结构化角色**：严格用 system/user/assistant/tool 角色体系传递信息，绝不把工具结果混入 user 消息——那等于亲手抹掉模型辨别来源的依据。\n- **输入清洗**：过滤「忽略之前的指令」等常见注入短语，只能作辅助，易被措辞变体绕过。\n- **把 Skill 和状态栏也当注入面**：Skill 本质是「把外部内容当作指令加载」的制度化形式，安装来源不明的 Skill 前必须审查内容；状态栏信息被模型高度信任，若摘要来自可被外部污染的数据源，信任会被反向利用。\n\n## 常见陷阱\n\n- **把时间戳、用户余额等动态信息写进 system prompt**——每轮改写前缀，缓存全失效（详见 `kv-cache-design`）。\n- **规则堆砌而无组织结构**：实验 2-4 显示，保留全部规则内容但打乱组织、去掉标题层次，任务成功率下降超过 30%，Agent 经常违反关键业务规则。\n- **清空工具描述**：保留函数签名但移除描述性文本，工具调用错误率增加 45%。\n- **盲目追求语气风格**：风格显著改变表达方式，但对任务完成率影响相对有限，不必在此过度投入。\n- **示例逐请求动态检索**：缓存持续失效，且不同示例集导致行为不可复现。\n- **所有场景塞进一个系统提示词**：既浪费 token（大部分与当前任务无关），又稀释注意力——应拆成按需加载的 Skill。\n- **让模型在业务规则上自由裁量**：模型优势在于遵循复杂指令和从长上下文提取信息，模糊规则会让同一任务在不同时间得到不同分类。\n- **把上下文层防御当作万无一失**：它只能降低攻击成功率，权限控制、沙盒隔离、高风险操作独立审查是另一层。\n\n## 配套代码\n\n- `chapter1/context/` — 多 provider 上下文感知 Agent，消融实验 1-1 对比 full / no history / no reasoning / no tool calls / no tool results 五种上下文模式。\n- `chapter2/prompt-engineering/` — 实验 2-4：基于 Tau-Bench 的提示工程消融框架，量化语气风格、指令组织、工具描述三个维度对任务完成率的影响。\n\n## 深度阅读\n\n- `book/chapter2.md`「上下文：决定 Agent 能力上限的关键」\n- `book/chapter2.md`「Agent 如何调用大模型：理解 API 的上下文结构」\n- `book/chapter2.md`「提示工程：优化系统提示词」\n- `book/chapter2.md`「动态提示词与 Agent Skills」\n","skills/eval-dataset-design/SKILL.md":"---\nname: eval-dataset-design\ndescription: 设计 Agent 评估数据集或单条评估任务时使用——解剖评估任务的四个组成部分、设计验证器与验收标准（含防敷衍性修复）、划分任务难度与陷阱任务、防范训练/评估数据泄漏（参数化实例、canary）、建设评估集的质量控制与长期维护、选择公开基准/自建业务集/生产轨迹回流三个来源。覆盖 τ²-bench、SWE-bench、AndroidWorld、OSWorld、Terminal-Bench、GAIA 的可迁移设计手法。\n---\n\n# 评估数据集设计\n\n## 何时使用\n- 从零设计评估集，或评审现有任务定义是否站得住\n- 为 Agent 编写单条评估任务：工单、用户模拟规范、初始状态、验收标准\n- 设计验证器：该断言终态、断言动作，还是检查必须告知用户的信息\n- 评估任务被模型\"猜答案\"蒙过，需要提高信噪比\n- 怀疑评估集已被污染/泄漏进训练数据，需要防泄漏与检测手段\n- 决定自建评估集的任务从哪来：公开基准、业务集、还是生产失败回流\n- 评估集上线后需要长期维护：修补环境、描述、验证逻辑与初始状态问题\n\n## 核心原则\n- **一条评估任务 = 四个部分**：给 Agent 的工单、给模拟器的行为规范、两侧状态的初始重置、成功判定标准。缺任何一部分，任务都无法重复运行。\n- **把用户的认知边界建模为独立字段，而非靠提示词约束。** 用户不知晓的信息 Agent 无从推测，只能通过提问与引导获得——渐进式信息透露不是一句\"不要一次说完\"，而是 `known_info` 与 `task_instructions` 的拆分。\n- **没有事实锚定的用户模拟器会让评估退化为两个模型相互确认。** 模拟用户关于环境状态的任何回答都必须以工具返回为依据，不许编造工具结果；否则 Agent 稍加引导，用户就确认\"问题已解决\"。\n- **验证器必须核实机器可独立复核的事实，不能采信 Agent 的自我陈述。** Agent 很容易写一篇\"任务已全部完成\"的报告而实际什么都没做。\n- **训练集与评估集严格隔离。** 答案不可从互联网直接检索、任务实例参数化生成、嵌入 canary 使泄漏可检测——三招至少用一招。\n- **验收口径要有可核实的边界，防\"敷衍性修复\"。** \"网络已恢复\"不可核实；\"测速评级 excellent 才算解决，poor/fair/good 均不接受\"才堵得住压制症状、不除根因的糊弄。\n- **高质量的评估集是修出来的，不是写出来的。** 主流基准的现行形态都是初版暴露问题后逐轮修补的结果；发布前人工淘汰、发布后持续修两类问题都要预算。\n- **每道题亲手做一遍。** 做完问两个问题：描述是否有多种合理解释，验证器认可哪一种？蒙混过关的最低成本路径是什么，验证器拦得住吗？\n- **难度分层让评估集不过时**，且每层失败指向不同改进方向：基础层失败指向工具使用，中间层指向多步规划，最高层指向长序列思考。\n\n## 实践模式\n\n### 1. 任务解剖：四件套字段清单\n以 τ²-bench telecom 一条真实任务为范本，逐项对照自建任务：\n- **ticket（给 Agent 的工单）**：只含用户会主动说出的部分。真实用户的初始表述往往只是\"我上不了网\"，把需求澄清到可执行的程度本身就是 Agent 必须具备的能力。\n- **user_scenario（给模拟器的行为规范）**：`known_info` 界定用户知悉范围（姓名、号码、所在国），故障原因不在其中；`task_instructions` 规定透露方式，并包含三类约束——情绪设定（首次修复失败后表现不满）、验收口径（仅 excellent 算解决）、事实锚定（设备状态回答必须基于工具结果）。\n- **initial_state（初始重置）**：`initialization_actions` 把两侧状态重置到同一起点，包括用户侧（飞行模式、漫游开关）与 Agent 侧（运营商侧配置）。\n- **evaluation_criteria（成功判定）**：四个可检查维度按需组合，外加聚合规则。\n\n### 2. 四维校验与聚合规则\n- `env_assertions` 验**终态**：移动数据可用、测速达 200 Mbps 且评级 excellent。\n- `actions` 验**关键动作是否发生**（哪些工具被哪一侧调用）。\n- `communicate_info` / `nl_assertions` 验**必要信息是否已告知用户**——别只查环境状态。\n- `reward_basis` 是聚合规则。二元奖励（只看终态）以过程颗粒度换取跨模型可比的单一数字：满分轨迹里违反\"一次只做一个工具调用\"的政策也不会被捕获。生产评估系统需要更多：不仅判对错，还要指出问题出在哪。\n\n### 3. 验证器设计的三种模式\n- **双命题验证**（SWE-bench Verified）：FAIL_TO_PASS（修复前失败、修复后通过，证明问题确已解决）+ PASS_TO_PASS（修复前后均通过，证明未引入新缺陷）。只验前者，Agent 可以删改妨碍通过的断言蒙混；只验后者等于未检验。另需排除自身不稳定的 flaky test。\n- **深状态核查**（OSWorld 式）：134 个独立评估函数，拥有完整系统访问权限，查文件系统结构、进程状态、网络连接与应用内部状态；数据库任务连库核实 SQL 是否真执行，浏览器任务分析 DOM、cookie 与 localStorage 并向后端发验证请求——能抓住\"表面完成、实质错误\"。\n- **不可伪造执行**（Terminal-Bench 式）：成功标准是真实构建并运行（如从源码构建内核并在 QEMU 启动日志出现自定义 printk），Agent 无法伪造输出，只能真做完全流程。\n\n### 4. 难度划分与陷阱任务\n- 分层标注并用于诊断：GAIA 466 题分三级——Level 1 只需一至两个工具（人类 93.9%，早期模型 30.3%），Level 2 多步思考，Level 3 复杂组合。Level 1 失败指向基础工具使用，Level 2 指向多步规划与信息整合，Level 3 指向长序列思考与复杂性管理，改进方向各不相同。\n- **陷阱任务**检验压力与误导下的判断力：用户声称\"客服已批准取消\"，实际并不符合政策，看 Agent 是否维持正确判断。\n- 任务集覆盖从易到难的全谱，模型能力提升时评估集不会快速过时。\n\n### 5. 数据泄漏防范\n- **组合多源 + 专有附件 + 精确匹配**（GAIA 式）：答案必须组合多个信息源才能得出，单一网页无法直接给出；部分任务配互联网上不存在的 PDF/音频/图片附件；用精确字符串匹配判定。\n- **参数化模板实例化**（AndroidWorld 式）：任务是\"将联系人 X 的电话改为 Y\"这类模板，每次评估随机生成参数。三收益：回放固定操作序列失效；单模板可生成近乎无限实例；固定部分参数、只改其余，可精确测量特定因素的影响。\n- **金丝雀标识符**（Terminal-Bench 式）：题面嵌入 canary GUID，模型能输出含该 GUID 的内容即说明基准已进训练集。它不阻止泄漏，但使泄漏可被检测。\n\n### 6. 质量控制与长期维护\n- **发布前人工淘汰**：SWE-bench Verified 从 2294 个原始任务抽 1699 个，93 名精通 Python 的开发者逐条检查（描述是否清晰、测试是否覆盖边界、是否稳定、参考 patch 是否引入新错误、难度是否合理），仅 500 个通过——淘汰 71% 换来更高信噪比，评估成本下降约 80%。复杂 Agent 任务动辄数分钟至数小时，前沿模型跑完一个评估集往往需要数千美元 token，控本就是控迭代速度。\n- **发布后持续修补**：OSWorld 发布 15 个月暴露出 300 余个问题，分四类——环境问题（反爬、CAPTCHA、动态内容，靠锁定版本与离线备份）、任务描述歧义（改写消除）、验证逻辑过严或过松（人工建立正确基线再调条件）、初始状态不完整（增加完整性校验）。修补方式可整体借鉴。\n- **从初版到成熟版的五处典型重设计**（τ-bench → τ²-bench）：任务指令过于笼统导致可猜 → 拆分 known_info/task_instructions；成功条件不精确 → 改为可核实边界；模拟用户过于机械 → 补情绪、耐心上限与事实锚定；只有 Agent 能改变环境 → 引入用户侧工具的双控机制；静态任务 → 参数化批量生成实例（同时改善覆盖率与抗泄漏）。\n\n### 7. 评估集的三个来源与演进\n- **公开基准**：用于粗筛模型与借鉴设计手法（验证深度、参数化生成、防泄漏、质量维护），一般不用于产品决策——其任务分布与业务分布不一致。\n- **自建业务集**：覆盖真实任务分布，作为模型选型与 Harness 设计决策的依据。可拿成熟基准当骨架，替换领域数据与工具集。\n- **生产轨迹回流**：用户明确纠正、点踩、事后规则/LLM 审计发现的失败案例，经失败归因后沉淀为回归用例。成本最高、准确性最高，直接来自用户实际遇到的问题。\n- 演进节奏：起步只有公开基准 + 少量手写业务集；上线运行一段时间后，回流用例成为主体。今天线上暴露的失败模式，明天就是守住底线的回归用例。\n\n## 常见陷阱\n- 任务指令写得宽泛，模型无需澄清需求、凭常识猜一套流程也能通过。\n- 成功条件是\"网络已恢复\"这类无边界描述，被压制症状的敷衍性修复蒙过。\n- 只验 FAIL_TO_PASS 不验 PASS_TO_PASS，Agent 靠删断言作弊；或不排除 flaky test，结果不可复现。\n- 用户模拟器没有事实锚定，评估退化为 Agent 与模拟用户相互确认；没有耐心上限，沟通效率低下不被计失败。\n- 静态题面被模型记忆，且无 canary，泄漏发生了都不知道。\n- 验证器过严（把正确答案判失败）或过松（放走表面完成实质错误）；初始状态配置不完整，每次运行起点不同。\n- `reward_basis` 只看终态，过程违规（策略违背、信息未告知）不被捕获，且不另建过程检查。\n- 任务描述存在多种合理解释而验证器只认一种，开发者与人肉执行者的判断不一致。\n- 评估集建成后不再维护，上线后仍是手写那几十条，与真实用户分布脱节。\n\n## 配套代码\n- `chapter7/tau2-bench-eval/` — τ²-bench telecom 任务定义四部分（ticket / user_scenario / initial_state / evaluation_criteria）的完整解剖与双控环境运行记录\n- `chapter7/public-health-reporting-eval/` — 五个确定性任务的六点结构化评分示范验证器设计：工具选择、参数、答案（含数值容差）、证据行精确集合、无依据声明处罚\n- `chapter7/android-world/` — T3A 失败轨迹与归因笔记，演示参数化任务实例、验证器终态判定，以及从失败轨迹回流生成轨迹前缀回归任务\n\n## 深度阅读\n- `book/chapter7.md`「一条评估任务的解剖：τ²-bench 的 telecom 领域」\n- `book/chapter7.md`「评估数据集的设计」\n","skills/error-recovery/SKILL.md":"---\nname: error-recovery\ndescription: 排查或加固 Agent 故障恢复机制时使用——当 Agent 陷入无限循环、流式响应中途断开、上下文溢出、模型服务限流过载、需要跨厂商接管跑到一半的轨迹、设计重试与熔断策略、防止错误处理路径自身引发连锁故障时使用。覆盖四层故障分类、检测方法、分级恢复策略、熔断上限与流式中断恢复。\n---\n\n# 故障与错误恢复\n\n## 何时使用\n- Agent 反复调用同一工具毫无进展、陷入死循环或死亡螺旋\n- 流式响应在思考/正文/工具调用参数中途断开，需要续写\n- 模型 API 限流、过载、超时、输出触顶，需要重试或降级\n- 上下文窗口溢出、压缩失败、轨迹结构损坏（工具调用缺配对结果）\n- 主模型持续不可用，要把轨迹交给另一家模型接着跑\n- 设计重试策略、熔断阈值、错误暴露边界\n- 工具调用幻觉/参数畸形，需要让模型自我纠正\n\n## 核心原则\n\n**故障分类学：四层。** 先分类再处理，不同层的故障走完全不同的恢复路径：\n\n- **API 层**：限流（429）、过载、请求超时、连接中断、输出触顶被截断。与任务内容无关，是基础设施噪声——可重试。\n- **工具层**：幻觉调用（调用不存在的工具）、参数畸形、执行抛异常，以及最危险的一种：工具反复返回同一错误，模型不加改变地反复重试。\n- **上下文层**：窗口溢出、压缩失败、轨迹结构损坏。\n- **控制流层**：死循环（相同操作无进展）与死亡螺旋（恢复逻辑自身又调 LLM、再次出错、连锁反应）。\n\n**检测：先分类，再计数。** 第一个判断不是\"要不要重试\"而是\"值不值得重试\"：可重试错误（限流、过载、网络抖动）重试才有意义；不可重试错误（参数不合法、权限不足、工具不存在）原样重试一万次结果相同，必须改变输入或策略。生产级 Harness 维护一张\"错误 → 恢复策略\"的映射表，而不是笼统地\"出错就重试\"。单次错误之外还要检测**模式**：对\"工具名 + 参数\"计算指纹，相同指纹反复出现就是无进展循环的明确信号；每条恢复路径维护独立的连续失败计数，为熔断提供依据。\n\n**活性与完整性监控。** 流式连接最危险的失败不是断开（会立即报错），而是**静默卡死**——连接建立但数据流停止。SDK 超时往往只覆盖初始连接而非传输过程，需要独立的空闲看门狗（超过设定时间无新输出即判定卡死，主动杀死挂起的流并重试）。可推广为：**每个长连接都需要活性信号，而非仅依赖连接超时**。完整性监控针对轨迹结构：发现工具调用缺少配对结果消息时，在注入上下文前自动修复配对，而不是把结构异常抛给模型或用户。产品模式可用占位符宽容修补，训练数据收集模式则拒绝修复——合成占位符会污染训练数据。\n\n**恢复：分级升级，逐级透明。** 能用低级别解决就不升级：\n\n1. **静默重试**——可重试错误的默认动作。指数退避叠加随机抖动（避免客户端同步重试造成二次拥塞，尊重服务端的等待时长提示）；区分前台与后台调用：主循环失败要重试，标题生成、输入建议这类辅助性后台调用失败直接放弃，否则后台重试挤占主链路配额，形成\"重试放大\"。\n2. **降级与接续**——重试无效时改变请求本身。输出触顶：先静默提升输出上限重发，仍不够再在消息末尾追加元指令让模型从断点接续；主模型过载时降级到备用模型（先剥离旧模型私有格式块，否则新模型解析不了历史）；高成本模式被限流时暂时回落到标准模式。\n3. **暴露给用户**——所有自动手段用尽后才呈现错误，并附上已尝试过的恢复动作。\n\n**工具层错误走另一条路：不终止会话，把错误变成模型的输入。** 幻觉调用收到\"工具不存在\"的结构化错误结果；参数校验失败收到附带输入约束提示的错误；畸形参数（该是对象却输出字符串）在执行前先程序化修复。错误以普通工具结果身份进入上下文，由模型下一轮自行纠正——喂回的错误越具体，自我纠正成功率越高。\n\n**错误处理的边界不是单次请求，而是整个恢复循环。** 在确认无法恢复之前，中间错误不暴露给消费者（用户或订阅事件的下游系统）：恢复期间扣留错误消息，恢复成功则消费者毫无感知，所有手段均失败后才统一呈现。\n\n**跨厂商接管：带走文字，带不走凭证。** 换一家模型把轨迹接着跑完，真正的障碍不是接口地址，而是轨迹里有只属于原厂商的东西。工具调用与结果各家结构不同但语义一致，重新渲染即可；难办的是思考——它由可读文字和厂商凭证（证明这段思考出自它自己）构成，文字换一家仍读得懂，凭证换一家就失效。且凭证未必附在思考上，也可能附在工具调用上（如 Google 的 thoughtSignature），所以\"把思考删干净就安全\"反而会在严格校验的厂商处失败。接管方案按最严格的一端设计：把历史工具调用改写成文字叙述，模型不再当作真正调用过，但至少能接着跑。由此得到设计原则：**轨迹按中立格式存储**——思考拆成可移植文字与不可移植凭证两个槽位，工具调用只记名称与参数，标识符渲染成具体请求时按目标厂商重新生成；切换时凭证一律丢弃，文字以普通内容身份带入。中立轨迹还服务于评估重放、训练样本构造、经验提取。\n\n**终止：每条恢复路径都要有上限。** 恢复机制本身也可能失效：上下文压缩连续失败若干次就放弃压缩，权限分类连续失败就回退人工询问，输出接续最多固定轮数。阈值来自生产数据而非拍脑袋——Claude Code 的\"连续 3 次\"压缩熔断阈值来自真实会话统计（曾有会话连续失败三千余次，仅此一类无效重试每天全球浪费约 25 万次 API 调用；3 次是\"绝大多数故障此前已恢复\"与\"继续重试基本无望\"之间的经验拐点）。\n\n**死亡螺旋防护。** 错误处理路径中的逻辑本身又调用 LLM，再次出错引发连锁。真实案例：上下文溢出触发\"结束时自动提交代码\"钩子，钩子调 LLM 生成 commit message 再次溢出，又一次触发钩子。防护两条：错误路径上禁用一切会再次调用模型的副作用逻辑（宁可丢掉自动记忆提取之类的辅助功能），以及用递归深度计数器检测并打断残余连锁。最后叠加全局终止条件：最大迭代轮数、会话预算上限、连续失败超阈值升级人工。\n\n**流式中断的三个断点、三种恢复方式。** 断点可能出现在：思考中途、正文中途、工具调用参数中途。恢复方式：① 丢弃半截内容整轮重发（最贵但最稳）；② 把半截内容作为末尾 assistant 消息要求模型接着写（部分厂商原生支持，其余需显式标注待续写消息，没有该接口则退回下一种）；③ 追加一条元指令说明从断点继续。注意：半截的工具调用无法以原生结构回传，需先转成文字再让模型补完，拼接后重新解析校验；若半截输出里已有工具因流式提前执行，续写前按调用指纹去重，避免重复副作用；拼接处容易多出空白或重复字符——参数合法不等于语义正确。\n\n## 实践模式\n\n**建一张错误 → 策略映射表**（比\"出错就重试\"的根本改进）：\n\n1. 捕获异常 → 归入 API/工具/上下文/控制流四层之一\n2. 可重试？→ 指数退避 + 抖动静默重试（前台重试、后台放弃）\n3. 改变请求可救？→ 提升输出上限 / 追加接续元指令 / 降级备用模型 / 回落标准模式\n4. 工具层错误 → 结构化错误结果喂回上下文，让模型下轮自我纠正\n5. 持续失败 → 查恢复路径的连续失败计数器，超阈值熔断（阈值从生产日志统计得出）\n6. 全部失败 → 统一向用户暴露，附已尝试的恢复动作清单\n\n**流式恢复实现清单**：记录断点类型（思考/正文/参数）；半截工具调用转文字 + 指纹去重；拼接后重新解析校验参数；对比三种方式的 token 成本与恢复成功率，选默认路径。\n\n**接管实现清单**：轨迹存中立格式（文字/凭证分离）；渲染层按目标厂商重组；凭证一律丢弃；遇强制凭证校验的厂商，历史调用改写为文字叙述；切换后监控重复调用指纹。\n\n## 常见陷阱\n- 笼统\"出错就重试\"：不可重试的错误（参数不合法、权限不足）重试多少次都一样\n- 只依赖连接超时：静默卡死（连接通但无数据）检测不到，必须配空闲看门狗\n- 后台辅助调用也重试：重试放大挤占主链路配额\n- 恢复期间把中间错误暴露给用户或下游事件订阅者\n- 没有熔断上限：一条恢复路径连续失败三千次，白白烧掉海量 API 调用\n- 错误处理路径自身调用 LLM：死亡螺旋，连锁故障\n- 以为删掉思考就安全跨厂商接管：凭证可能挂在工具调用上\n- 续写半截输出不按调用指纹去重：已执行的工具产生重复副作用\n- 训练数据收集模式用占位符修补缺失消息：污染训练数据\n\n## 配套代码\n- `chapter5/provider-failover/` — 实验 5-1/5-2：中立轨迹格式实现跨厂商接管（直传/剥离/中立三臂对照）与流式三断点接续\n- `chapter5/log-diagnosis/` — 诊断 Agent 读轨迹定位根因、生成回归测试、真实重放验证并建 Issue 的完整闭环\n- `chapter5/adaptive-log-parser/` — 自愈循环示范：解析失败不报错，而是把失败样本交给 Agent 生成代码、测试、热更新\n\n## 深度阅读\n- `book/chapter5.md`「故障与错误恢复」\n- `book/chapter5.md`「Coding Agent」→「实现技巧」（并行工具调用、流式执行与级联中止）\n- `book/chapter1.md`「Harness 工程：模型之外的竞争力」（纠正机制与\"不暴露中间态\"原则）\n","skills/knowledge-org/SKILL.md":"# knowledge-org\n\nPath: `skills/knowledge-org/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/knowledge-org/SKILL.md)","skills/kv-cache-design/SKILL.md":"# kv-cache-design\n\nPath: `skills/kv-cache-design/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/kv-cache-design/SKILL.md)","skills/loop-engineering/SKILL.md":"# loop-engineering\n\nPath: `skills/loop-engineering/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/loop-engineering/SKILL.md)","skills/mcp-skill-hub/SKILL.md":"# mcp-skill-hub\n\nPath: `skills/mcp-skill-hub/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/mcp-skill-hub/SKILL.md)","skills/memory-system/SKILL.md":"# memory-system\n\nPath: `skills/memory-system/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/memory-system/SKILL.md)","skills/multi-agent-design/SKILL.md":"# multi-agent-design\n\nPath: `skills/multi-agent-design/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/multi-agent-design/SKILL.md)","skills/post-training-strategy/SKILL.md":"# post-training-strategy\n\nPath: `skills/post-training-strategy/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/post-training-strategy/SKILL.md)","skills/rag-pipeline/SKILL.md":"# rag-pipeline\n\nPath: `skills/rag-pipeline/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/rag-pipeline/SKILL.md)","skills/reward-design/SKILL.md":"# reward-design\n\nPath: `skills/reward-design/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/reward-design/SKILL.md)","skills/tool-design/SKILL.md":"# tool-design\n\nPath: `skills/tool-design/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/tool-design/SKILL.md)","skills/tool-discovery/SKILL.md":"# tool-discovery\n\nPath: `skills/tool-discovery/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/tool-discovery/SKILL.md)","chapter9/ai-style-skill/skill/SKILL.md":"# skill\n\nPath: `chapter9/ai-style-skill/skill/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter9/ai-style-skill/skill/SKILL.md)","chapter10/multi-role-transfer/skills/coding/SKILL.md":"# coding\n\nPath: `chapter10/multi-role-transfer/skills/coding/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter10/multi-role-transfer/skills/coding/SKILL.md)","chapter10/multi-role-transfer/skills/data_analysis/SKILL.md":"# data_analysis\n\nPath: `chapter10/multi-role-transfer/skills/data_analysis/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter10/multi-role-transfer/skills/data_analysis/SKILL.md)","chapter10/multi-role-transfer/skills/research/SKILL.md":"# research\n\nPath: `chapter10/multi-role-transfer/skills/research/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter10/multi-role-transfer/skills/research/SKILL.md)","chapter10/multi-role-transfer/skills/triage/SKILL.md":"# triage\n\nPath: `chapter10/multi-role-transfer/skills/triage/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter10/multi-role-transfer/skills/triage/SKILL.md)","chapter10/multi-role-transfer/skills/writing/SKILL.md":"# writing\n\nPath: `chapter10/multi-role-transfer/skills/writing/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter10/multi-role-transfer/skills/writing/SKILL.md)","chapter2/agent-skills-ppt/skills/pptx/SKILL.md":"# pptx\n\nPath: `chapter2/agent-skills-ppt/skills/pptx/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter2/agent-skills-ppt/skills/pptx/SKILL.md)","skills/README.md":"# Skills Skill\n\nPath: `skills/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/README.md)","chapter4/collaboration-tools/README.md":"# collaboration-tools Documentation\n\nPath: `chapter4/collaboration-tools/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter4/collaboration-tools/README.md)","chapter4/execution-tools/README.md":"# execution-tools Documentation\n\nPath: `chapter4/execution-tools/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter4/execution-tools/README.md)","chapter4/perception-tools/README.md":"# perception-tools Documentation\n\nPath: `chapter4/perception-tools/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter4/perception-tools/README.md)","chapter9/self-evolving-tools/README.md":"# self-evolving-tools Documentation\n\nPath: `chapter9/self-evolving-tools/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter9/self-evolving-tools/README.md)","chapter2/agent-skills-ppt/skills/pptx/reference.md":"# Pptx Skill\n\nPath: `chapter2/agent-skills-ppt/skills/pptx/reference.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter2/agent-skills-ppt/skills/pptx/reference.md)"},"items":[{"name":"SKILL.md","path":"chapter10/multi-role-transfer/skills/coding/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter10/multi-role-transfer/skills/coding/SKILL.md","title":"coding","category":"anthropic-skill","format":"markdown","content":"# coding\n\nPath: `chapter10/multi-role-transfer/skills/coding/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter10/multi-role-transfer/skills/coding/SKILL.md)","tokens":300,"sizeBytes":215},{"name":"SKILL.md","path":"chapter10/multi-role-transfer/skills/data_analysis/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter10/multi-role-transfer/skills/data_analysis/SKILL.md","title":"data_analysis","category":"anthropic-skill","format":"markdown","content":"# data_analysis\n\nPath: `chapter10/multi-role-transfer/skills/data_analysis/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter10/multi-role-transfer/skills/data_analysis/SKILL.md)","tokens":300,"sizeBytes":236},{"name":"SKILL.md","path":"chapter10/multi-role-transfer/skills/research/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter10/multi-role-transfer/skills/research/SKILL.md","title":"research","category":"anthropic-skill","format":"markdown","content":"# research\n\nPath: `chapter10/multi-role-transfer/skills/research/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter10/multi-role-transfer/skills/research/SKILL.md)","tokens":300,"sizeBytes":221},{"name":"SKILL.md","path":"chapter10/multi-role-transfer/skills/triage/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter10/multi-role-transfer/skills/triage/SKILL.md","title":"triage","category":"anthropic-skill","format":"markdown","content":"# triage\n\nPath: `chapter10/multi-role-transfer/skills/triage/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter10/multi-role-transfer/skills/triage/SKILL.md)","tokens":300,"sizeBytes":215},{"name":"SKILL.md","path":"chapter10/multi-role-transfer/skills/writing/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter10/multi-role-transfer/skills/writing/SKILL.md","title":"writing","category":"anthropic-skill","format":"markdown","content":"# writing\n\nPath: `chapter10/multi-role-transfer/skills/writing/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter10/multi-role-transfer/skills/writing/SKILL.md)","tokens":300,"sizeBytes":218},{"name":"reference.md","path":"chapter2/agent-skills-ppt/skills/pptx/reference.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter2/agent-skills-ppt/skills/pptx/reference.md","title":"Pptx Skill","category":"anthropic-skill","format":"markdown","content":"# Pptx Skill\n\nPath: `chapter2/agent-skills-ppt/skills/pptx/reference.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter2/agent-skills-ppt/skills/pptx/reference.md)","tokens":300,"sizeBytes":215},{"name":"SKILL.md","path":"chapter2/agent-skills-ppt/skills/pptx/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter2/agent-skills-ppt/skills/pptx/SKILL.md","title":"pptx","category":"anthropic-skill","format":"markdown","content":"# pptx\n\nPath: `chapter2/agent-skills-ppt/skills/pptx/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter2/agent-skills-ppt/skills/pptx/SKILL.md)","tokens":300,"sizeBytes":201},{"name":"SKILL.md","path":"chapter8/curly-quote-sft/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter8/curly-quote-sft/SKILL.md","title":"curly-quote-sft","category":"anthropic-skill","format":"markdown","content":"# 中文技术文档符号与引用规范\n\n## 何时加载\n\n- 编辑或生成同时包含中文、英文、Markdown 和代码的技术文档。\n- 用户反馈引号、反引号或代码边界格式错误时。\n\n## 符号定义\n\n- ASCII 直引号：`\"`、`'`；常用于英文标点和代码字符串。\n- 中文弯引号：`“”`、`‘’`；用于中文自然语言引用。\n- Markdown 反引号：`` ` ``；用于行内代码和字面量。\n\n## 决策优先级\n\n1. 先保护可执行代码、JSON/schema、URL、路径和用户要求原样保留的引用文本。\n2. 识别 Markdown 代码围栏、行内代码和代码注释边界。\n3. 在中文自然语言作用域中，把成对的直引号改为弯引号，并正确处理嵌套引用。\n4. 英文原文保持原文标点；英文标识符是否使用反引号由其是否为代码字面量决定，而不是由语言决定。\n5. 无法判断作用域时保留原文并请求澄清，不做全局替换。\n\n## 正反例约束\n\n- 正例：`# 中文注释：显示 \"状态\"` → `# 中文注释：显示 “状态”`；同一代码块中的 `name = \"status\"`、`const name = \"status\"`、SQL 标识符和 JSON 键值保持 ASCII 语法。\n- 反例：不能把代码字符串、JSON、URL、路径、英文原句或 Markdown 行内代码中的 `\"`/`'` 改成弯引号；不能因为文件是中文就全局替换。\n- 每种编程语言至少提供“该改的中文注释”和“该留的可执行字面量”成对样本，并在留出/边界集更换体裁、变量名和代码结构。\n\n## 数据质量门禁\n\n- 合成数据先按文章体裁、作用域类型和编程语言分层，再切分 train/eval/boundary，禁止 ID 和模板组合重叠。\n- 机器门禁检查未解析变量、代码围栏、非注释代码行漂移和保护区；人工抽查每个分层的首条样本，记录在 `validation/manual_audit.md`。\n- 任何语言类别的保护区或语法门禁失败，都应回到 Skill/数据蓝图修订后重训，不能只增加 epoch 或汇报总体平均分。\n\n## 验证\n\n- 修改必须是最小编辑，正文事实和代码内容不变。\n- Markdown、JSON 和代码语法检查必须通过。\n- 英文原文、代码和保护区域做字节级回归。\n- 记录来源 Bad Case、适用范围、例外和验证结果。\n","isInternal":false,"tokens":795,"sizeBytes":2307},{"name":"SKILL.md","path":"chapter9/ai-style-skill/skill/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter9/ai-style-skill/skill/SKILL.md","title":"skill","category":"anthropic-skill","format":"markdown","content":"# skill\n\nPath: `chapter9/ai-style-skill/skill/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter9/ai-style-skill/skill/SKILL.md)","tokens":300,"sizeBytes":186},{"name":"SKILL.md","path":"skills/agent-evaluation/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/agent-evaluation/SKILL.md","title":"agent-evaluation","category":"anthropic-skill","format":"markdown","content":"---\nname: agent-evaluation\ndescription: 为 Agent 建立或改进评估体系时使用——设计评估指标（Pass@k/Pass^k/成本）、搭建可重复运行的评估环境、选择确定性验证器或 LLM-as-a-Judge 及各自适用边界、编写 Rubric、做失败归因与回归任务、评估驱动的模型选型、判断统计显著性、建设可观测性与内部评估基础设施（消融、AB 测试、特性开关、提示词回归）、从 Benchmark 报告走到系统改进。\n---\n\n# Agent 评估体系\n\n## 何时使用\n- 为 Agent 系统建立第一套评估，或审查现有评估是否可信\n- 选模型、换模型前需要数据依据（新模型公开分高，不代表在你的任务上更好，甚至可能回退）\n- 评估分数下降，要判断是 Agent 退化还是评测系统本身出了问题\n- 需要把\"成功率下降\"这类笼统结论拆成可着手修复的具体问题\n- 为生产 Agent 建设内部评估基础设施：消融实验、AB 测试、特性开关、提示词回归\n- 设计可观测性与生产轨迹回流，让评估集随产品持续演化\n\n## 核心原则\n- **评估的对象是\"模型 + Harness\"组合体，不是模型本身。** 同一模型在不同 Harness 下表现悬殊；表现不佳时先怀疑 Harness，再怀疑模型。\n- **用模型替换实验（model swap）区分两类问题**：固定 Harness 只换模型，分数不涨 → 瓶颈在 Harness；分数随模型能力大幅波动 → 瓶颈在模型能力。消融实验则是关闭 Harness 组件、定位内部哪个部件重要，两者互补，别混用。\n- **先检查评测系统，再动 Agent。** 分数下降先排查：运行环境资源不足导致的随机失败、验证器 bug 把对的判错、用例与生产脱节——这些在数字上与模型退化一模一样，只有回放完整轨迹能区分。\n- **指标口径由业务场景决定。** 同一个 0.8，对退款客服意味着每五名用户一人拿不到退款，对漏洞挖掘已属可观。报告必须写清 k 的口径：同一任务的 k 次独立采样，还是生产流水线连续 k 个任务。\n- **凡是能写成程序化断言的检查就用断言**，LLM 评判只用于确实无法机械判定的维度。确定性验证更便宜、更可复现，适合长期进 CI。\n- **分差要超过噪声、在配对分析中成立、并且能够复现，才值得据此切换模型或发布改动。**\n- **一轮证据只支持与它规模相称的下一步。** 子集 4/4 不能写成系统整体 100%，完整复测通过前不部署。\n\n## 实践模式\n\n### 1. 指标设计：Pass@k / Best@k / Pass^k\n- **Pass@k**（k 次至少一次通过）与 **Best@k**（连续得分取最好）衡量能力上限，适合科研发现、漏洞挖掘、开放式创作——人类会从 k 条候选轨迹里挑出最好的那条。\n- **Pass^k**（连续 k 次全部通过，且不触发安全、合规、幻觉等一票否决项）衡量业务可靠性，适合支付、退款、权限变更、生产部署。两者关系：Pass@k = 1-(1-p)^k，Pass^k = p^k。\n- p=0.6、k=5 时：Pass@5 ≈ 99%，Pass^5 ≈ 7.8%——前一个数字回答\"能不能偶尔创造奇迹\"，后一个才回答\"能否稳定交付\"。\n- 会产生副作用的操作不能\"重试直到成功\"：应在沙盒或可回滚环境中采样，每一次失败都记入可靠性指标。\n\n### 2. 评估环境五要素\n- **数据集**：初始状态、给 Agent 的输入、给模拟器的行为规范与验收标准，打包为一条记录即一个用例。\n- **环境状态**：必须可重置（`initialization_actions` 即重置脚本）；真实性（变化符合业务逻辑）与可控性（每次回到同一起点）兼得。\n- **工具接口**：两侧工具均为原子操作；抽象层次过高（如一个\"解决用户问题\"工具）会使评估退化为对单次函数调用的考察，规划与推理被工具本身吸收。\n- **评分标准**：分层检查项 + 明确的聚合规则（如 `reward_basis`）。\n- **执行协议**：终止信号、轮数上限、模拟用户耐心耗尽主动结束（沟通效率过低本身即计为失败）。\n- 按任务形态选环境类型：单轮问答用无状态单轮环境；搜索+综合用多轮工具环境；改数据库验状态用有状态环境；跑代码查输出用沙盒环境。并行采样与轨迹缓存是标配；工具失败应返回清晰错误信息而非单一失败标志，让 Agent 能据此调整策略。\n\n### 3. 验证方式谱系与自动化评估\n- 横轴是**可机械验证程度**：确定性断言 → 检查项清单 → Rubric + LLM-as-a-Judge → 配对比较。向右移动不意味着放弃左侧。\n- 确定性验证只能判对错、不给原因；生产系统最需要的恰恰是\"错在哪、下一步改什么\"。开放式任务（报告、投诉、创意）无唯一终态、人工评估不可规模化，才上 LLM 评判。\n- **Rubric 四准则**：基于专家指导（捕捉核心事实与推理步骤，而非语言流畅度）；全面覆盖（事实、逻辑、完整性、安全性，且明确 Pitfall）；按重要性加权（必要/重要/可选/陷阱，支持一票否决，如幻觉出现总分归零）；评价标准自包含（禁\"展示深刻理解\"，改为\"引用了至少两个权威理论并准确解释\"）。\n- 每个维度给客观可验证的评分档次、具体示例与边界案例；显式防范奖励作弊（幻觉、讨好用户、关键词堆砌、回避棘手问题）。\n- **长度偏差**防范：Rubric 显式惩罚冗长、规定同类任务长度上限；配对比较前把候选长度控制到相近；定期审计评分与长度的相关性——高分几乎总伴随长回答即已被带偏。\n- **同源模型问题**：Agent 与评判模型同家族时，Agent 会学会利用评判模型的偏好与盲点（古德哈特定律：度量成为优化目标后就不再是好度量）。换不同家族模型评判，并让 Rubric 随分歧持续迭代。\n\n### 4. 失败归因：把 0 分变成可修复的问题\n- 归因对象是轨迹中**首个**导致任务偏离的错误；后续错误多是连锁反应，不能把最后一条报错当根因。\n- 问题案例三来源：用户明确纠正、用户点踩/负面反馈、事后状态检查/规则验证器/LLM 评审发现 Agent 做了不该做的事。\n- **静默失败**（无任何工具报错、Agent 自行宣布完成）的两把定位工具：事实锚点比对（把 Agent 陈述与工具返回值逐步对齐，取首次背离）；轨迹前缀二分（截到第 k 步交人接手，能救回说明错误在 k 之后）。不能用搜报错关键字代替。\n- 归因记录结构化（JSON/YAML）：含任务名、首错步号、错误类别、责任方、原文证据、置信度，区分主因与后果（三次重试是后果，不是三个根因）；多类别并存时按\"最早且能解释后续失败\"选主因。\n- **规则先筛、LLM 再定位**比全量喂 LLM 更便宜也更准：完成声明与实际执行命令的交叉核对、diff 是否触及测试断言与 skip 标记、diff 是否改公开 API/schema 而无迁移，这三类可先用规则筛出嫌疑轨迹。\n- 警惕\"做对了但说错了\"：工具调用和环境状态全对，告知用户的信息却错。只检查终态的评估会整体掩盖它（τ²-bench 基线中约三分之一失败属此类）。根因归属要判到层：观察通道缺失不是\"模型不会 OCR\"。\n- 保存归因记录时，连同任务目标、环境状态、Agent 版本、工具集版本和完整轨迹一起存，供回归测试使用。\n\n### 5. 两层回归任务\n- **端到端回归**：从初始状态跑到终态，验最终状态、必要输出、安全条件。最接近生产结果，但难以定位失败步骤。\n- **轨迹前缀回归**：冻结首错之前的上下文、对话、工具返回与环境状态，只要求下一步或下几步可观察动作。成本低、能隔离单个策略问题；对高可靠生产 Agent，其重要性往往超过端到端口径。\n- 前缀回归答案定义为**可接受动作集合**（\"先读仓库规则\"\"先询问用户\"\"拒绝危险操作\"）+ 禁止动作，而不是唯一标准答案。\n- 按错误类别生成回归任务：流程缺失 → 带计划文档与测试验收条件的端到端任务；工具调用错误 → 截断出错前缀编辑成边界任务；信息反馈类 → 对答复内容本身设断言，而非只查环境状态。\n\n### 6. 评估驱动的模型选型\n- 延迟分两阶段：Prefill 决定首字延迟（TTFT = 排队 + 预填充），Decode 决定出字速度与思考时长（50 tokens/s 生成 2000 思考 token 要 40 秒）。看 p95 尾部延迟而非均值。\n- 在自己工作负载上实测各模型的思考 token 用量与对应收益，不凭公开榜单推断。\n- 成本算**每个任务的平均成本**与成本-性能比：便宜但成功率低的模型因频繁重试可能更贵；输入/输出/缓存 token 分开计价。\n- 指标按场景取：日常 Pass@1，关键操作 Pass^k，探索性任务 Pass@k / Best@k。\n- **预算—能力曲线**：除成功率，报告性能随墙钟时间、token、工具调用次数或算力预算变化的曲线；短预算领先不能外推长时运行能力（RE-Bench：2 小时预算最佳 Agent 约为人类专家 4 倍，8 小时人类反超）。\n- **行为策略也是选型维度**：同一中性 Harness 下测\"行动阈值\"（首次修改前的工具调用数与阅读文件数）。换模型行为改变、同模型跨 Harness 保持倾向 → 支持模型效应，反之支持 Harness 效应；工具步数、并行调用、模型延迟必须分开看。工具步数不是质量分。\n- 异构模型组合（轻量模型管简单、强模型管复杂）必须用评估验证整体效益超过所增复杂度，并检查特定场景是否回退。\n- 成本优化（KV Cache 稳定前缀、上下文压缩、分层选模型）每项独立开关，且**合用时在完整任务中一起实测**——各自节省比例不能相加（28.3% 与 17.5% 合用只有 30%）。\n- 建实时成本监控：按任务类型/模型/用户维度追踪 token 与费用，设单任务成本上限，Agent 陷入循环时自动终止。\n\n### 7. 统计显著性\n- 标准误 SE(p) ≈ √(p(1-p)/n)：100 个用例、成功率 70% 时 95% 置信区间约 ±9 个百分点，\"新模型 73% 对旧模型 70%\"不足以支持切换。\n- 同一批任务比较两个配置用**配对分析**：逐题记录谁胜出，McNemar 检验或配对 bootstrap，不要相减两个独立成功率。\n- 每个配置跑 3–5 个随机种子，报告均值与波动范围；单次运行只能用来筛选方向。\n- 预期收益只有 2–3 个百分点而评估集只有几十题：先扩大样本，标准误按 1/√n 缩小。\n- 并行验证多个假设时考虑**多重比较**：收紧显著性阈值，或对正向结果做独立复跑。\n\n### 8. 可观测性\n- 数据基础是 **trace/span 树**：一次任务执行一条 trace，每个 LLM 调用、工具调用、检索是一个 span（记录输入输出、起止时间、token 消耗、错误），父子关系构成执行树。\n- 采用标准协议（OpenTelemetry + OpenInference 等语义约定）保持采集与分析解耦，避免被单一平台锁定；采集异步批量进行，不拖累响应延迟。\n- 追踪的四大价值：问题诊断（回放而非猜测）、持续优化（定位低成功率工具与空结果检索）、成本管理（识别异常高成本案例）、后训练数据基础。\n- 最有价值的去向是**回流**：生产轨迹筛失败与可疑案例 → 脱敏（去隐私、密钥）→ 沉淀为评估集新用例与回归测试。评估集是随产品演化的活资产，不是一次性静态集合。\n\n### 9. 内部评估基础设施（生产级）\n- **消融**：每个主要特性可独立关闭，定期（如每次大版本发布前）跑消融，发现\"特性债务\"——曾经有效但随模型进化已不再必要的特性。消融开关要在启动路径极早期注入，事后加装不了。\n- **AB 测试**：多臂而非二元（揭示剂量-效应关系，找到最优点）；**区分机制指标与目标指标**（缩短计划文件长度是机制，降低会话级成本才是目标，别把机制当目标，计划过短可能引发更多编辑-检查循环反而更贵）；设护栏指标（满意度、操作次数、错误率不能变差）；记录基线统计（样本量、百分位数、相关性），否则无法判断显著性。\n- **双层特性开关**：编译时开关（代码物理移除，本身即干净的消融机制）+ 运行时开关（服务端下发、本地缓存、宁可稍旧也不能阻塞启动；每个特性曝光事件每会话最多记一次）。特性开关是一等架构组件，服务实验、渐进发布与紧急熔断。\n- **提示词敏感性**：系统提示要能确定性渲染（相同配置输入永远产出相同文本）；建立版本化快照；每次提示词变更在评估集上跑回归，像代码过 CI 一样。\n- **隐私感知分析**：分析接口只接受特殊类型包装的值，类型名即审计线索；隐私约束从第一天设计进去。分析系统无法安全收集数据，评估就无从谈起。\n\n### 10. 从 Benchmark 报告到系统改进的闭环节奏\n- 读报告先找失败集中在哪些任务与能力上，再回放轨迹分清问题出在**看、想、做、验**哪一环；别只盯总分（88% 总分很容易埋掉一个集中的失败簇）。\n- 每轮只改一个变量，形成假设链：加提示词无效 → 换输入通道有效但太贵 → 精简输入保住成功率且降成本。提示写得再详细也补不回 Agent 没看到的信息；输入也不是越多越好。\n- 小范围通过只获得扩大测试的资格：标准环境、全任务 × 多种子，同时查成功率不降、token 不超阈值、延迟不超上限，才能讨论部署。\n\n## 常见陷阱\n- 看到分数下降就改 Agent 代码，不先排查评测系统（资源不足、验证器 bug、用例脱节都会伪装成模型退化）。\n- 用公开基准分数直接做产品决策——GAIA 上提升两个百分点与退款成功率没有必然关系。\n- 把最后一条报错当根因；或把根因归错层（观察通道缺失被记成\"模型不会 OCR\"，于是去换模型、做 OCR 训练）。\n- 只检查环境终态，漏掉\"做对了但说错了\"。\n- Rubric 写\"展示深刻理解\"这类不可验证的抽象标准；没有一票否决项，被关键词堆砌式奖励作弊刷分。\n- 评分从未审计长度相关性，评判已被长度偏差带偏而不自知。\n- 同源模型既当运动员又当裁判，Goodhart 之后评分虚高。\n- 把多项上下文优化的节省比例直接相加；或凭单次运行的结果做选型决策。\n- 配对比较不交换候选顺序，位置偏差让先出现者系统性占优。\n- 子集小样本通过后直接当整体水平汇报，结论超出证据规模。\n\n## 配套代码\n- `chapter7/tau2-bench-eval/` — τ²-bench telecom 五任务双控环境评估：环境 reset、轨迹保存、二元奖励与失败任务（错选线路漏做充值）分析\n- `chapter7/android-world/` — T3A 运行记录、失败归因笔记，以及 diagnose→hypothesize→experiment→decide→iterate 的五阶段改进闭环\n- `chapter7/public-health-reporting-eval/` — 合成数据上的确定性六点评分：工具选择、参数、答案、证据行、无依据声明处罚\n- `chapter7/agent-cost-analysis/` — 八轮退款任务全链路成本拆解，KV-cache 友好与上下文压缩的 2×2 A/B 量化\n- `chapter7/model-benchmark/` — 多维度模型基准 campaign：吞吐/TTFT/尾延迟、168 小时可用性、限流爬坡、同模型不同供应商对照\n- `chapter7/model-action-threshold/` — 固定 Coding Harness 下测量不同模型的行动阈值（首次修改前的工具调用与文件阅读）\n- `chapter7/elo-leaderboard/` — 从 Chatbot Arena 真实投票实现 Elo/Bradley-Terry 配对排名与历史快照\n\n## 深度阅读\n- `book/chapter7.md`「评估指标：成功的定义」\n- `book/chapter7.md`「评估环境」\n- `book/chapter7.md`「自动化评估方法」\n- `book/chapter7.md`「评估驱动的模型选型」\n- `book/chapter7.md`「评估结果的统计显著性」\n- `book/chapter7.md`「Agent 的可观测性」\n- `book/chapter7.md`「从 Benchmark 报告到系统改进」\n- `book/chapter7.md`「从外部评估到内部评估：生产级 Agent 的评估基础设施」\n","frontmatter":{"name":"agent-evaluation","description":"为 Agent 建立或改进评估体系时使用——设计评估指标（Pass@k/Pass^k/成本）、搭建可重复运行的评估环境、选择确定性验证器或 LLM-as-a-Judge 及各自适用边界、编写 Rubric、做失败归因与回归任务、评估驱动的模型选型、判断统计显著性、建设可观测性与内部评估基础设施（消融、AB 测试、特性开关、提示词回归）、从 Benchmark 报告走到系统改进。"},"isInternal":false,"tokens":6318,"sizeBytes":16568},{"name":"SKILL.md","path":"skills/agent-evolution/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/agent-evolution/SKILL.md","title":"agent-evolution","category":"anthropic-skill","format":"markdown","content":"---\nname: agent-evolution\ndescription: 让 Agent 从运行经验中持续学习、构建自进化闭环时使用——涵盖从运行轨迹提取学习信号（三层轨迹验证）、四种进化方式（经验知识库、Prompt/Skill、程序/Harness、模型参数）的适用边界与选择依据、Prompt 自动优化、轨迹编译为程序、Agent 自我修改与安全门禁、睡眠学习与长期分层评估。触发词：持续进化、自进化、经验学习、轨迹验证器、自我修改、进化闭环。\n---\n\n# Agent 持续进化\n\n## 何时使用\n\n- 部署后的 Agent 反复犯同类错误，需要把运行经验转化为持久能力\n- 需要为运行轨迹构建验证器 / 评价器，判断\"哪里错、为什么错、证据在哪里\"\n- 面对一个待修复缺陷，需要决定经验应写进知识库、Prompt/Skill、程序还是模型参数\n- 要做 Prompt 自动优化、失败轨迹规则提炼、浏览器轨迹转工作流等单点进化\n- 设计 Agent 自我修改流程（改自身 Harness、工具、重试策略），需要验证与发布门槛\n- 搭建\"在线执行 + 离线进化\"双循环，或设计记忆/Skill 的整理、淘汰与回滚机制\n- 评估系统是否真的在进化（而非只保存或只追加反馈）\n\n## 核心原则\n\n- **保存经历 ≠ 从经历中学习**。学习发生在系统主动完成\"评价、对照、归纳、验证\"之后，而非日志写入磁盘的那一刻。一百条轨迹放进向量库只是可检索案例，不自动完成跨案例比较。\n- **先评价再更新**。不知道任务是否完成、哪一步导致成败，模型的反思只是猜测。评价一条轨迹依次回答三问：事情是否办成（结果）、是否以允许的方式办成（过程）、是否让用户舒服（质量）。\n- **三层验证，底层优先**。结果验证器读环境真值（测试、数据库、工具返回），最应优先建立且比模型自述可靠；过程验证器用政策库/权限表/动作序列做代码判定；质量层才用 LLM Rubric。结果正确不代表过程正确（删掉失败用例也能让测试通过）。\n- **学习信号必须四要素齐备**：成败判定（成功/部分成功/失败）、每维度结论、每条结论的证据位置（哪轮对话、哪次工具调用）、失败类型标签。单一总分无法指导更新；证据不足时验证器应拒绝评分，低置信度案例排除在学习集外。\n- **按能力的表示性质选择载体**（表 9-2 的边界）：\n  - 经验知识库——事实、经验规律、例外与来源；更新快、可追溯，但依赖检索和模型正确应用\n  - Prompt/Skill——能用自然语言说清的判断原则、语境与例外；可解释、范围可控，但易膨胀、冲突、被忽略\n  - 程序/Harness——可确定性解析、可执行验证、高风险硬约束；可测试、稳定、低成本，但开发维护成本高\n  - 模型参数——高维感知、生成风格、隐式策略；泛化强、推理开销低，但更新与回归成本高\n- **同一能力可拆到多个载体**：事实入知识库，解释例外的原则入 Skill，不可绕过的权限由程序门控，高维识别能力入参数。路由结果只是更新提案，尚无发布资格。\n- **经验知识库 vs 领域知识**：第三章领域知识回答\"用户与世界是什么样的\"（如\"该航司特殊餐食需提前 24 小时预订\"）；本章经验知识库从行动轨迹与结果中提取\"在什么条件下应该怎样做\"（如\"订票前先检查特殊餐食截止时间\"）。二者共享存储与检索技术，来源和验证目标不同。\n- **所有修改是最小 diff + 可回滚 + 独立验证**。待验证版本必须同时在触发失败的边界集上改善、在正常工作的保留集上不退化；验证者须独立于提炼者。\n- **在线执行与离线进化分离**。在线循环只完成任务并追加不可变证据，不直接改写正式 Agent；离线循环聚合轨迹、生成提案、过门槛发布，两者经版本化经验库和评估集连接。一次偶发成功或恶意输入不能立即改写长期能力。\n- **安全边界三条**：证据与指令隔离（网页/工具输出及其 LLM 摘要都是不可信证据，LLM 摘要不是净化过程）；待验证能力与正式能力隔离（新产物先入不可服务真实流量的待验证区，过沙盒、权限、供应链扫描与回归后才转正）；安全机制不可自我修改（Agent 不能改验证器、测试、发布门槛、审计日志和稳定版本备份——否则降低阈值即可把退化伪装成进步）。\n- **Harness 更新能力 ≠ Harness 受益能力**。前者是从轨迹产出有价值修改，后者是任务 Agent 在正确场景激活并遵循该修改。不能用端到端分数反推更新器好坏，需分层评估。\n\n## 实践模式\n\n### 1. 轨迹验证器（学习信号的来源）\n\n- 三层结构：结果层读最终环境状态；过程层查业务规则、隐私、事实依据、承诺—行动一致性（声称完成的操作是否真实发生）；质量层按 Rubric 逐项给分并引用轨迹证据。\n- 输出结构化诊断而非总分：每维度结论 + 证据轮次 + 置信度，失败带类型标签。\n- 低置信度案例不进学习集；把它当事实固化比丢弃更危险。\n\n### 2. 经验知识提炼管道（五步）\n\n1. 保存不可变原始轨迹与环境结果（用于审计）；\n2. 为单次运行生成结构化分析：任务类型、所需能力、观察到的策略、错误与例外；\n3. 按任务族聚合同类运行，为每条经验草案建\"哪些轨迹支持、哪些轨迹反驳\"的证据表；\n4. 达到支持门槛才写入正式文档；\n5. 在未参与提炼的新任务上测迁移效果。\n\n正式经验文档写：适用场景、推荐策略、禁止做法、例外条件、证据来源、最近验证时间——不复述某次任务的完整过程。真正有迁移价值的内容来自对照（成功轨迹做了什么、失败轨迹缺少什么、策略在哪些版本/前置条件下失效），Reflexion 式自然语言反思可参与生成草案，但反思本身不是证据。\n\n### 3. 经验写成 Prompt/Skill（指令更新）\n\n- 触发条件：多条相似轨迹反复暴露同一种策略错误，且错误能用语言清楚描述。\n- 形式：带来源的最小 diff（`old_str → new_str`），不让模型每轮重写整份 Prompt——重写会丢细节、把相互制约的条件合并成过度抽象的原则。可参考 ACE：上下文维护成带稳定标识符的条目集合，增量更新 + 确定性合并去重。\n- 发布门槛：补丁非空、来源可追溯、保留集不退化、边界集确有改善；通过才灰度（`release_to_canary`），否则拒绝。待验证补丁写入 working 文件，不覆盖正式 Prompt。\n- Skill 与 Harness 边界：Skill 负责理解语境、提问、整理 Spec；Harness 负责缺少确认时否决高风险写入。否决器不替模型决定方案。\n- 提炼输入决定归纳质量：给失败摘要+报错文本，模型只归纳出教训；补充 Agent/用户各自的工具清单，才能归纳出职责归属。\n\n### 4. 经验写成程序（程序化经验）\n\n- 浏览器工作流六步生命周期：捕获轨迹（保存动作参数、URL、元素定位证据——定位信息只能用于再找元素，不能证明任务完成）→ 参数化（字面量换模板变量）→ 定义状态检查（动作前/后检查 + 最终状态检查，最终检查必须读真实页面或后端状态）→ 独立回放验证（沙盒/测试站点重置到独立初始状态后完整回放，全部谓词通过才发布）→ 匹配与回放（能力库按意图检索，直接执行，无需逐步调 LLM）→ 失效与重学（谓词失败、Schema 变化即回退完整 Agent 模式）。\n- 自我修改走软件发布流程，而非运行中进程覆盖自身：从稳定版本切隔离 worktree → Coding Agent 生成最小补丁 → 静态检查、单测、安全扫描、失败轨迹重放、旧任务回归 → 可灰度新版本。每次修改请求是一份可证伪的变更契约：失败证据、推断根因、归属组件、修改提案、预期修复的行为、可能受损的行为、分别验证两者的用例。\n- 提案生成器的输入不只有失败案例，还必须有成功约束（不能破坏的性质）和此前被拒记录（避免换说法重复提交），共同构成有边界的方案空间。\n\n### 5. 经验写入参数\n\n- 判断依据不是\"任务是否长期稳定\"，而是能力的表示性质：能否被外部符号较完整表达。域偏移用 LoRA/持续微调，快速变化的风格用周期性偏好训练。\n- 数据来源：经评价的生产轨迹——高质量示范进 SFT，明确偏好形成成对数据，有可靠环境奖励的交互用于 RL。\n\n### 6. 双循环与睡眠学习\n\n- 离线整合五步：触发（时间/轨迹量/容量/错误频率门槛，且无高优先级在线任务）→ 定向（读正式知识、Skill 目录及版本，了解不可修改边界）→ 采集与整合（合并重复、标记冲突与适用条件，优先生成局部补丁）→ 验证与审批（迁移集/保留集/安全集，高风险等人工批准）→ 修剪与索引（长期不用或被推翻的标记过期、归档，保留来源与回滚版本）。\n- 定期对抗上下文腐化：合并重复经验、把局部规则从全局 Prompt 移入领域 Skill、重验长期未用的工具、删除被推翻的知识、从原始基座重训 LoRA。\n\n### 7. 进化效果的分层评估\n\n- 指标（表 9-3）：更新提案有效率（独立验证中的接受率与增益）、产物激活率（是否正确场景加载）、遵循成功率（动作序列与过程验证器）、保留任务集增益（未参与进化任务的成功率/质量/成本）。\n- 长期评价至少五类：回退（新旧经验冲突）、泛化（测试集外场景）、Token 效率、安全性（规则/隐私/拒绝边界是否漂移）、长期工程质量（维护复杂度、向后兼容、调试负担）。\n- 开放式任务（科研、战略）反馈慢且答案不唯一，需改变证据结构：结论与证据分离（每类声明链接可审计来源）、保留负面结果与停止原因、维护搜索多样性（不全押当前最高分）、让人类在更高层介入（定义问题、审查评价标准、决定何时停止）。\n\n## 常见陷阱\n\n- 把用户满意度或单一总分当学习信号：满意度上升可能伴随规则违规率上升，需护栏指标。\n- 把低置信度结论当事实固化，或把 LLM 摘要当无害化后的指令直接纳入 Skill。\n- **模型会把观察到的行为当作应然的行为**：轨迹中最频繁出现的是转人工，模型就可能把\"三次失败即转接\"写成规则——而该环境下转接必然失败，等于把失败写进规范。提炼产物必须经与提炼者独立的验证。\n- 让模型每轮重写整份 Prompt/记忆，导致重要细节在多轮改写中消失。\n- 把\"动作执行过\"当\"任务完成\"：没有最终状态检查的回放，只是把错误更快地重复。\n- 待验证版本直接发布，或发布门槛可被提案自身修改（安全门不能由修改者自证）。\n- 只修当前失败案例，不顾保留集回退、泛化、Token 成本和长期工程质量。\n- 只追加不淘汰：知识无限增长引发检索错误、知识冲突、灾难性遗忘，抵消学习收益。\n- 用端到端分数判断更新器好坏，忽略激活率与遵循失败。\n- 提案被接受 ≠ 下游能力提升：一次提案通过只证明更新流程成立，仍需在相同任务和模型下做开关消融。\n\n## 配套代码\n\n- `chapter9/trajectory-verifier/` — 实验 9-1：三层轨迹验证器，对比单一总分与带证据的多维诊断\n- `chapter9/tau2-escalation-experience/` — 实验 9-2：从 τ²-bench telecom 失败轨迹提炼转人工与工具使用规则，三臂对照\n- `chapter9/prompt-auto-optimization/` — 实验 9-3：航空客服失败轨迹 → 三维诊断 → 最小 Prompt diff → 发布门槛\n- `chapter9/ai-style-skill/` — 补充案例：用户\"AI 味\"before/after 纠正持续提炼为写作 Skill，LLM judge + 金标校准\n- `chapter9/browser-use-rpa/` — 实验 9-5：浏览器轨迹编译为带状态谓词的待验证工作流，独立回放后才入能力库\n- `chapter9/self-modifying-agent/` — 实验 9-6：由失败轨迹触发重试/熔断代码自我修改，Docker 沙箱验证提案\n- `chapter9/harness-safety-gate/` — 实验 9-7：用户反馈触发高风险操作确认门禁，AST 扫描 + 隔离回放\n- `chapter9/hermes-self-evolution/` — 实验 9-8：Hermes 读本书后自主选题、修改自身并接受独立 Reviewer 审查\n- `chapter9/self-evolution-eval/` — 实验 9-9：四阶段纵向评估（学习/迁移/规则变化/保持），区分保存、追加与可淘汰记忆\n- `chapter9/self-evolving-tools/` — Alita 式补充案例：Agent 从零搜索、沙盒测试并封装新工具入库复用\n\n## 深度阅读\n\n- `book/chapter9.md`「从运行轨迹中获得学习信号」— 三层验证结构与学习信号四要素\n- `book/chapter9.md`「Agent 持续进化的四种方法」— 知识、指令、程序、参数的适用边界与各自流程\n- `book/chapter9.md`「构建可长期运行的持续进化闭环」— 双循环、睡眠学习、分层评估与安全边界\n","frontmatter":{"name":"agent-evolution","description":"让 Agent 从运行经验中持续学习、构建自进化闭环时使用——涵盖从运行轨迹提取学习信号（三层轨迹验证）、四种进化方式（经验知识库、Prompt/Skill、程序/Harness、模型参数）的适用边界与选择依据、Prompt 自动优化、轨迹编译为程序、Agent 自我修改与安全门禁、睡眠学习与长期分层评估。触发词：持续进化、自进化、经验学习、轨迹验证器、自我修改、进化闭环。"},"isInternal":false,"tokens":5049,"sizeBytes":13492},{"name":"SKILL.md","path":"skills/agent-state-bar/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/agent-state-bar/SKILL.md","title":"agent-state-bar","category":"anthropic-skill","format":"markdown","content":"---\nname: agent-state-bar\ndescription: Agent 陷入无限循环、数不清工具调用次数、遗忘 TODO 或目标偏离、长任务中思考 token 持续膨胀时使用——Agent 状态栏机制、作为 user 消息注入末尾的 KV Cache 理由、每轮替换与持久追加两种实现及成本模型、五种状态栏技术（时间戳、工具计数器、TODO、详细错误、系统状态）与维护铁律。\n---\n\n# Agent 状态栏：通过元信息增强 Agent 轨迹管理\n\n提示工程给的是静态指令，而 Agent 执行中还需要动态感知自身状态与任务进展。**Agent 状态栏**把任务进度、环境变化、工具调用计数等运行时状态整理成结构化摘要，由框架在上下文末尾持续注入。类比手机屏幕顶部始终显示时间、电量、信号——模型每次生成新回复时都能「瞥一眼」，据此做出更准确的决策。\n\n## 何时使用\n\n- Agent 反复执行相同工具调用、陷入无限循环（如超过次数限制仍在拨打）\n- 模型数不清「已经调用了几次」「还剩几项 TODO」，违反显式约束\n- 长任务中每次迭代的思考 token 量随上下文变长而持续增长\n- Agent 过分关注局部子任务，忘记用户原始诉求和核心约束\n- 小模型需要接近前沿模型的任务遵循能力\n- 设计状态消息的注入方式与更新策略\n\n## 核心原则\n\n- **状态栏不是对话主体内容**：它不属于用户消息、模型输出或工具结果，而是框架自动生成的状态摘要，注入在上下文**最末尾**，紧邻模型即将生成的新 token。\n- **理论基础是「上下文学习是检索而非推理」**：模型擅长查找，不擅长在一次前向传播中主动归纳统计。「已经打了几次电话」这类知识以原始记录形式分散在上下文里，模型每次决策都要花额外思考 token 扫描重算，效率极低且错误率高。\n- **本质是把隐式状态提炼为显式知识**：原始轨迹高度冗余，大量 token 中只含少量关键状态信息；状态栏以极低的额外 token 成本，呈现原本需要扫描数千 token 才能获得的信息。\n- **显式操纵注意力分配**：长上下文中早期目标和关键约束容易被后续工具结果淹没；结构化元信息放在末尾，空间上更接近新 token，获得更高注意力权重——一种「强制性的注意力引导」。\n- **实测收益**：提供提前算好的状态栏后，较小开源模型的准确率可以接近前沿大模型；每次迭代的思考 token 量、延迟和花费均降低约一个数量级。不带状态栏时思考量随上下文变长**持续增长**，带上后**基本恒定**。\n- **状态栏是上下文压缩技术之一**：它用代码确定性地维护「关于轨迹的结论」，与 LLM 驱动的压缩互补。\n- **无侵入性**：所有元信息以人类可读形式出现在上下文里，开发者随时可检查；不需要微调，直接在任何语言模型上起效。\n\n## 实践模式\n\n### 1. 注入位置：一条 user 角色的消息，放在最末尾\n\n```text\nmessages: [\n  { role: \"system\",    content: \"You are a customer service assistant...\" }  ← 固定，KV Cache 已缓存\n  { role: \"user\",      content: \"Help me cancel my Xfinity plan\" }\n  { role: \"assistant\", content: null, tool_calls: [...] }   ← 第 1 轮决策\n  { role: \"tool\",      content: \"Call log...\" }\n  { role: \"assistant\", content: null, tool_calls: [...] }   ← 第 2 轮决策\n  { role: \"tool\",      content: \"Call log...\" },\n  { role: \"user\",      content: \"Can you call them again to follow up?\" },\n  { role: \"user\",      content: \"<agent_status>\n      Current State:\n      - phone_call invoked 3 times (Xfinity: 3/3 max)\n      - Current time: 2025-09-14 10:30:45\n      - TODO: [1] Cancel plan (in_progress)\n    </agent_status>\" }                                        ← 框架注入的状态栏\n]\n```\n\n- **为什么是 user 角色而不是改 system**：修改 system 消息会破坏整个前缀的缓存。这里的 user 角色只是 API 协议层面的技术选择，**不等同于「来自终端用户的输入」**——Harness 借用这个消息槽位，挂载框架自动生成的系统状态信息。\n- 用 `<agent_status>` 标签包裹，便于模型识别其特殊性质。\n- 因为是追加而非修改，前面所有已缓存内容都不受影响。\n\n### 2. 状态栏的三类构成\n\n- **任务规划**：TODO 列表把复杂多步骤任务分解为清晰步骤，放在轨迹末尾，不断提醒模型当前进展和后续目标，确保行动与总体规划一致（防止只关注局部子任务）。\n- **事件的侧信道信息（Side-channel）**：为每个事件附加元数据——精确时间、地理位置、距上次 Agent 回复的时间间隔。通常随对应事件一起追加。\n- **环境当前状态的观察摘要**：系统时间、工作目录、异常操作提醒（「该工具已被重复调用 N 次」）、以及从隐式状态到显式观察的转换。随任务推进不断更新。\n\n### 3. 状态更新的两种实现与缓存代价\n\n**实现一：每轮替换**——每次 API 调用前移除上一轮状态消息，在末尾追加最新状态。保证永远只有一份最新状态，但移除旧状态会使其位置之后的所有缓存失效（与「动态时间戳」同一失效机制，区别仅在于状态消息位于末尾，失效范围只覆盖上次注入后新增的消息，通常是一轮，整个前缀仍可复用）。\n\n**实现二：持久追加**——状态消息一旦注入就永久留在轨迹中，每轮只在末尾追加新状态。Claude Code 的 `<system-reminder>` 即此方式，历史状态保留在 transcript 中从不删改。对缓存完全友好（只追加不修改，前缀始终稳定），代价是陈旧状态累积，既占 token 又要求模型自己关注最新一条。\n\n**选择规则**：\n\n- 状态很小、两次更新间产生的消息很多、会话长度受控 → **选实现二**（保留旧状态通常比反复重算长后缀便宜）\n- 状态较大、更新频繁或轨迹很长 → **选实现一**（只使上次注入后的短后缀失效，同时避免陈旧状态持续累积）\n\n**粗略成本模型**：设每条状态 S token，两次更新间新增后缀 R token，预计更新 N 次，缓存输入单价为普通输入的 α 倍：\n\n```\nC_替换 ≈ (N-1) * (1-α) * R\nC_追加 ≈ α * S * N * (N-1) / 2\n→ 当 α*S*N/2 < (1-α)*R 时倾向实现二，否则倾向实现一\n```\n\n该估算未计上下文占用和陈旧状态带来的歧义，实际选择还应结合服务商缓存计费与实测命中率。\n\n### 4. 五种状态栏技术（实验 2-9）\n\n- **时间戳跟踪**：以 `[2025-09-14 10:30:45]` 格式作为前缀添加到用户消息和工具响应中（**不是放在系统提示词里**，否则破坏 KV Cache）。让 Agent 理解时序关系，也为调试和审计提供信息；配合时间模拟可理解「昨天的文件」和「今天的修改」。\n- **工具调用计数器**：维护全局字典记录每个工具被调用次数，响应中标注 `Tool call #3 for 'read_file'`。显式计数触发模型的模式识别：第一次失败后检查路径，第二次失败后列出目录，第三次主动放弃并找替代方案。深层价值是隐式的成本感知。\n- **TODO 列表管理**：提供 `rewrite_todo_list` 和 `update_todo_status` 两个工具，每项含唯一标识符、内容、状态（pending / in_progress / completed / cancelled）和时间戳。借鉴 Manus「通过复述操纵注意力」理念。实验数据：启用 TODO 的 Agent 平均 **15 次**迭代完成任务，禁用时需 **21 次**且经常遗漏子任务。\n- **详细错误信息**：四层内容——错误类型和描述、完整参数的 JSON、调用栈信息、针对性修复建议（如 FileNotFoundError 时建议验证路径、检查工作目录、使用绝对路径）。启用后 Agent 在错误场景找到替代方案的成功率从 **60% 提升到 95%**，从盲目重试转变为有针对性地分析。\n- **系统状态感知**：注入当前时间、工作目录、操作系统类型、Shell 环境和 Python 版本。工作目录跟踪尤其关键——Agent 执行 `cd` 后自动更新；OS 信息让 Agent 做平台相关决策（Linux 用 `apt`、macOS 用 `brew`）。\n\n这些技术单独使用效果有限，**组合起来会产生涌现效应**：时间戳 + 工具计数器让 Agent 理解操作的频率和时间分布；TODO + 系统状态让 Agent 根据环境调整策略；详细错误 + 工具计数器让 Agent 多次失败后不仅改变策略，还理解失败原因。\n\n## 常见陷阱\n\n- **把时间戳写进 system prompt**：直接破坏 KV Cache 前缀，必须作为消息前缀或末尾状态注入。\n- **让 LLM 一次性批量统计状态**：模型几乎无条件地相信状态栏——你写「打了 3 次电话」，它就当真是 3 次，不会自己重算；而 LLM 做数量统计本来就容易出错。**状态栏尽量用代码维护，实在要用 LLM，也要逐条抽取、再由代码汇总。**\n- **忽视状态栏投毒风险**：状态栏信息被模型高度信任，一旦摘要内容来自可被外部污染的数据源（如把外部网页片段直接写进状态栏），这种信任会被反向利用。\n- **状态栏够用就整段删掉原始记录**：状态栏是对原始上下文的**有损投影**，只提前算了「你预想会被问到」的维度。计数、状态跟踪这类任务可以只保留状态栏以节省大量 token；但只要有一个问题涉及状态栏未计算的维度，仅保留状态栏就会导致准确率**断崖式下降**。删除前确认没有未覆盖的查询维度。\n- **状态消息无限累积从不清理**：实现二的代价，陈旧状态既占 token 又制造歧义，会话长度失控时应切换到实现一。\n- **用状态栏替代真正的任务规划**：TODO 列表需要配套工具支持状态流转，只在提示词里写「请跟踪进度」不够。\n\n## 配套代码\n\n- `chapter2/system-hint/` — 实验 2-9（agent-status-bar 框架）：实现时间戳、工具计数器、TODO 列表、详细错误、系统状态五种状态栏技术，可独立开关；`python main.py --mode preview` 无需 API key 即可对比有无状态栏时模型看到的上下文差异；`python run_experiment_2_8.py` 跑冻结的对照实验。\n\n## 深度阅读\n\n- `book/chapter2.md`「Agent 状态栏：通过元信息增强 Agent 轨迹管理」\n","frontmatter":{"name":"agent-state-bar","description":"Agent 陷入无限循环、数不清工具调用次数、遗忘 TODO 或目标偏离、长任务中思考 token 持续膨胀时使用——Agent 状态栏机制、作为 user 消息注入末尾的 KV Cache 理由、每轮替换与持久追加两种实现及成本模型、五种状态栏技术（时间戳、工具计数器、TODO、详细错误、系统状态）与维护铁律。"},"isInternal":false,"tokens":3796,"sizeBytes":10541},{"name":"SKILL.md","path":"skills/async-event-agent/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/async-event-agent/SKILL.md","title":"async-event-agent","category":"anthropic-skill","format":"markdown","content":"---\nname: async-event-agent\ndescription: >-\n  构建异步/事件驱动 Agent，或让 Agent 响应外部事件（新邮件、webhook 回调、IM 消息、定时器、系统告警）、\n  处理工具执行期间的用户打断与多任务并发时使用。覆盖事件循环与安全点、三类事件触发工具、用户沟通与多渠道召回、\n  虚拟身份与隔离执行环境、队列式/取消式/并行式三种事件处理策略及紧急度判定，以及模型原生异步与同步接口兼容两条路线。\n  触发词：异步 Agent、事件驱动、event-driven、webhook、定时器、心跳、任务句柄、打断、steering、并行工具执行。\n---\n\n# 异步与事件驱动 Agent\n\n## 何时使用\n\n- 要让 Agent 在**没有用户输入时也行动**：定时生成报告、周期性检查服务器、跟进未回复的邮件、到工作时间再拨打电话。\n- 要接入**外部事件源**：新邮件到达、API 回调、IM/短信消息、GitHub PR 变更、支付失败告警。\n- 要支持**执行期间被打断**：长任务运行中用户说\"停\"\"改一下预算\"\"先帮我查个天气\"。\n- 要**同时管理多个并发任务**：并行跑几个脚本、先完成的先看结果、未达进度就取消。\n- 要从回合制 ReAct 循环升级为长期运行的**事件循环 Agent**。\n- 要评估某个模型/接口是否支持原生异步，或为不支持的接口设计兼容层。\n- 任务需要在\"发起\"与\"收尾\"之间跨越多个回合（如代打电话、长时审批流）。\n- Agent 需要以\"活人感\"与用户异步沟通（发消息、图片、文件、按紧急度推送提醒），而非必须打开指定会话。\n\n## 核心原则\n\n- **回合制是交互约定，不是环境性质。** 世界不会等模型反应完才变化；任务常在\"发起\"与\"收尾\"之间跨越多个回合。\n- **架构是事件循环，不是轮询。** Agent 是一个长期运行的循环：每轮从输入队列取若干事件 → 追加到轨迹 → 调一次 LLM → 执行它决定的工具 → 回到开头等下一批。不要用\"反复问有没有新消息\"的轮询。\n- **\"主动服务\"的前提是事件能推给 Agent。** Hooks（框架内生命周期事件）、Cron（定时调度）、Heartbeat（每隔 N 分钟唤醒）三种机制里只有后两种让 Agent 自己动起来，且都是**时间驱动**的；对内置渠道之外的第三方事件源（新邮件、外部回调）必须建实时推送通道，否则只能等下一个周期才察觉——这个延迟在验证码等待、三方通话等场景里不可接受。\n- **安全点决定一切。** 同步接口中事件只能在循环边界（一段推理结束、一次工具返回）被消费；紧急事件的取消式处理本质是\"主动提前制造一个安全点\"。取消点必须是工具或推理能安全收尾的位置。\n- **取消 ≠ 撤销。** 发送取消信号只是让执行器停止；已经发生的动作不会回滚。未完成的工具结果用显式占位符表示，不能伪造成功。\n- **三种处理策略按紧急度选择**：\n  - **取消式**（紧急事件：`user.interrupt`、`supervisor.instruction`、`agent.interrupt`、紧急告警）：停当前操作 → 清空队列 → 所有事件连同紧急事件一次性追加到轨迹 → 立即重新调 LLM。\n  - **队列式**（常规事件：`user.input`、`tool.result`、`timer.trigger`）：放入队尾不打断，等本轮到达安全点后**批量**追加，减少往返。\n  - **并行式**（独立、轻量、需快响的查询，如\"今天天气怎么样\"）：在独立推理会话中执行，结果追加进主轨迹并**明确标记为并行**，避免 LLM 混淆。\n  - 硬编码规则有局限；建议用轻量分类 LLM 做事件路由器。\n- **所有输入统一建模为结构化事件**：来源（谁）、渠道（方式）、内容（什么/紧急度）、上下文（与哪个任务相关）。这是防止把工具结果误当用户指令、以及提示注入的前提。异构触发器（webhook、定时器、邮件、数据库变更、文件监听）统一建模后，Agent 才能用一致方式处理不同来源的刺激。\n- **异步语义要写进工具接口**：把\"启动\"和\"完成\"解耦——`initiate_phone_call` 立即返回任务 ID 和初始状态，进展通过 `phone_call_connected` / `phone_call_ended` 等事件通知。工具名和描述本身就要传达异步语义（\"任务发起后立即返回 ID，你可以继续处理其他事项，结束后会收到单独通知\"）。\n- **三条路线按模型能力选择**：原生异步（工具挂起、模型继续、回合中途 steering）> 同步接口兼容（占位符 + 队列 + 重新请求）> 退化回纯串行。用了 `asyncio` 不等于模型具备异步能力，仍需应用层管理事件来源、工具生命周期与结果归属。\n- **可靠处理比能接收更难**：至少要检查——延迟结果能否归入正确任务且缺席时不编造；处理新要求后能否恢复原任务并区分\"修改计划\"与\"停止执行\"；多条更新能否同时遵守而不是只记住最后一条。\n- **事件优先级要动态判断，不是静态排序**：Agent 应像秘书按紧急程度决定先处理哪个、做到一半能否暂停切换，而不是固定先后。长任务异步执行不应阻塞用户交互，被打断的任务要能自然恢复。\n- **占位符只在打断时引入**：常态下 LLM 看到的就是标准同步轨迹；只有出现打断才插入\"工具正在后台执行\"的占位 tool result 修复配对格式，后台真实结果到达后再以带来源和任务 ID 的事件送回。\n\n## 实践模式\n\n1. **搭骨架**：inbox 队列 → 分发器（按紧急度路由）→ 单线程事件循环 → 轨迹存储。参考 `chapter6/async-agent/` 的 `runtime.py::AgentRuntime`（`_dispatcher` 路由紧急度、`_handle_interrupt` 在安全点取消、`run_llm_turn` 推进轨迹）。\n2. **接事件源**：三类事件触发工具——定时器（一次性 + 循环，循环定时器兼容只能主动查询的外部服务）、后台任务监控（监控新增输出或关键词，别让 Agent 反复盯命令行浪费 token）、外部事件通道（实时推送）。每个触发源都要定义过滤规则和足够上下文的 payload，避免无关事件烧算力。\n3. **定义紧急度分类器**：先列事件类型清单和默认策略，再用轻量 LLM 兜住语义边界（\"马上停下来\"→取消式，\"报告用中文发我\"→队列式，\"天气如何\"→并行式）。\n4. **同步兼容层五规则**：assistant 消息与工具调用项立即落轨迹；只有工具真正返回才记 tool result；执行中被打断则生成占位 tool result 后再追加新事件并重新请求；无 steering 时取消未完成生成、只保留已确认消息；非打断事件一律入队批处理。\n5. **多条更新的综合**：给每个未处理事件加显式标记（`[未处理事件 2/4] ...`），末尾附汇总，提示模型必须回应全部，防止只记住最后一条。\n6. **并发任务的状态可观测**：每个异步工具调用都要有任务 ID，支持按 ID 查询进度和取消；完成事件注入主轨迹时带真实结果（退出码、产出哈希），不要只报\"已完成\"。\n6. **触达用户**：用户沟通工具支持异步消息、已读/未读、多渠道（IM/短信/邮件/电话/推送），按紧急程度、用户状态、内容性质、用户偏好选择渠道——通知机制同时是召回机制，用于长任务完成与周期性任务的习惯养成。\n7. **身份与环境**：给 Agent 独立虚拟身份（专属账号、存储、计算环境）跑在隔离的 VM/容器或虚拟手机里；通过共享卷（如 `/workspace/shared`）以**文件路径**而非内容传数据，避免占满上下文；必须登录用户真实账号时走 Human-in-the-Loop（VNC/RDP 让用户亲自登录，会话令牌有效期内复用）。\n8. **验收三层**：事件能否及时到达 → 系统是否按策略执行（取消真的终止了子进程、批量是否齐全）→ 模型是否正确使用了这批更新（结果归属、未完成时不编造、恢复原任务）。可加状态检查点做中断后恢复验证。\n\n## 常见陷阱\n\n- **把\"任务已启动\"当成\"任务已完成\"**：占位符让模型误以为结果已到，在真实结果返回前做出依赖它的判断。必须用明确的任务状态和结果校验，并在评估中检查是否编造了未到达的数据。\n- **注意力分散**：批量事件只回应最后一条，前面的要求被静默丢弃。\n- **轮询冒充异步**：让 Agent 每隔几秒查一次状态，既慢又烧 token；要么用推送通道，要么用循环定时器 + 增量监控。\n- **明文拼接不可见推理**：服务端管理的 reasoning 状态要按提供商续接协议保留，不要自行拼出\"半截思考\"回灌。\n- **取消只发信号不检查**：执行器若不响应取消（类似不检查 `ctx.Done()`），\"停止\"消息发出去任务还在跑。\n- **给所有事件同一优先级**：紧急告警和常规输入走同一条队列，要么该停的停不下来，要么鸡毛蒜皮打断主任务。\n- **直接托管用户个人账号**：Agent 出错或被攻破即暴露全部数字身份；独立身份 + 隔离环境更安全也更可审计。\n- **忽略反机器人机制**：数据中心 IP 的虚拟环境容易被识别，需住宅代理；平台侧还可能有生态级封禁。\n- **用一次失败反推训练原因**：未公开的训练过程不可证，先查系统层的任务状态、事件来源和执行反馈。\n- **忘记维护多个对话线程的关联**：第三方消息如何影响用户情绪、用户在不同线程扮演什么角色、何时综合多线程信息给建议——纯事件路由处理不了这类上下文。\n\n## 配套代码\n\n- `chapter6/async-agent/` — 实验 6-2：事件驱动异步 Agent 框架（Flux），并行工具、打断取消、检查点持久化，含零依赖离线 demo。\n- `chapter6/agent-with-event-trigger/` — 实验 6-1：FastAPI 事件驱动 Agent + 42 个 MCP 工具，演示\"事件到达 → Agent 处理 → 结果输出\"最小闭环。\n- `chapter6/async-agent/` 同时给出离线验收 demo（并行 vs 串行墙钟时间、打断取消后恢复、检查点持久化与还原）与 LLM 场景复现两条路径，适合先跑离线 demo 验证运行时再上真实模型。\n- `chapter6/astra-async-steering/` — 实验 6-3：GPT-6 Astra 原生异步工具调用与回合中途引导，含 `sync` / `async` / `steer_reasoning` / `async_steer` / `unsupported_steer` 五组对照与真实 API 运行记录。\n- 语音相关（时间尺度更细的\"可打断\"场景）：`chapter6/end-to-end-speech/`、`chapter6/streaming-speech/`、`chapter6/controllable-tts/`、`chapter6/live-audio/`、`chapter6/phone-agent/`。\n- 机器人相关（毫秒级连续观察与动作分块）：`chapter6/gemini-xlerobot-navigation/`、`chapter6/rgb-sim2real-grasping/`、`chapter6/xlerobot-teleoperation/`。\n\n## 深度阅读\n\n- `book/chapter6.md`「模态与触发时机的扩展」\n- `book/chapter6.md`「异步与事件驱动：当世界主动找上门」\n- 相关设计文档：`chapter6/async-agent/agent_framework_design.md`（Flux 框架的运行时设计）\n","frontmatter":{"name":"async-event-agent","description":"构建异步/事件驱动 Agent，或让 Agent 响应外部事件（新邮件、webhook 回调、IM 消息、定时器、系统告警）、 处理工具执行期间的用户打断与多任务并发时使用。覆盖事件循环与安全点、三类事件触发工具、用户沟通与多渠道召回、 虚拟身份与隔离执行环境、队列式/取消式/并行式三种事件处理策略及紧急度判定，以及模型原生异步与同步接口兼容两条路线。 触发词：异步 Agent、事件驱动、event-driven、webhook、定时器、心跳、任务句柄、打断、steering、并行工具执行。"},"isInternal":false,"tokens":4033,"sizeBytes":11341},{"name":"SKILL.md","path":"skills/bad-case-to-dpo/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/bad-case-to-dpo/SKILL.md","title":"bad-case-to-dpo","category":"anthropic-skill","format":"markdown","content":"---\nname: bad-case-to-dpo\ndescription: 把生产 bad case / 失败轨迹转成训练数据时使用——从失败归因、轨迹前缀截取、DPO 偏好对构造、LoRA 训练到边界集与保留集双集验证的完整链路；也用于判断某类问题该走 SFT、DPO、RL 还是先修 Harness/工具/tokenizer，以及如何从运行轨迹中提取带证据的结构化学习信号。触发词：bad case、失败归因、DPO、偏好对、轨迹前缀、拒绝采样、过度矫正、边界集、保留集、过早结束、reward hacking、LoRA 微调、训练评估隔离。\n---\n\n# 从问题案例到训练数据\n\n## 何时使用\n\n- 生产出现 bad case：用户纠正、点踩、事后审计发现失败轨迹，想把它变成后训练输入\n- 判断某类失败该修 Harness/工具/tokenizer，还是值得投入训练\n- 构造 DPO 偏好对、轨迹前缀回归任务、决策边界示范\n- 决定一个失败案例该进 SFT 数据、DPO 偏好对、PRM 负标签还是 RLVP 惩罚规则\n- 训练后验证修复效果，担心\"修好一个、弄坏一片\"\n- 从运行轨迹中提取可学习信号，而不是只存一个总分\n\n## 核心原则\n\n- **归因到首个错误步骤，不是整条轨迹。** 以 Coding Agent \"过早结束\"为例：读代码、改代码可能都没错，错的是\"在缺乏证据时下结论\"那一个决策边界。归因记录必须落到这一步，训练数据才能对着它构造。\n- **失败轨迹不应直接当作正确的 SFT 示范。** 它的正确用法是：构造偏好对、发现任务覆盖缺口，或补上诊断与修复后再加入训练。\n- **判定必须靠模型写不了的机制。** \"是否完成\"要由隐藏测试、状态断言或外部终止钩子给出；测试必须读取真实文件或环境状态，不能只检查模型是否说了\"已完成\"，否则模型会学会口头承诺验证而不真正验证。\n- **边界集与保留集缺一不可。** 边界集（任务未完成）看模型是否选择继续验证而非宣称完成；保留集（任务已完成）看模型是否仍能正常收尾。只盯边界集会把模型训练成永远不敢结束的**过度矫正**状态：每个任务都无限验证下去，延迟与成本崩溃。这是\"改动不能破坏既有行为\"在参数层面的版本。\n- **训练与评估严格隔离。** 训练集与评估集必须是不同的任务、不同的参数、不同的模板组合；参考解法、隐藏测试和验证器反馈不能泄露给模型。隔离规则应由单元测试强制检查，而不是靠人记得。\n- **先排除非模型原因。** 沿\"文件原始字节 → 工具返回 → Harness 序列化 → 模型上下文 → 模型 token 输出 → 解码字符串 → JSON/tool-call 解析 → 工具匹配\"逐层对比。只有模型收到的上下文与原始字符串完全一致、而**模型输出是链路上首个出现差异的位置**，才能标为模型能力问题。否则修工具/Harness/tokenizer，修完再看还剩多少。\n- **小数据 DPO 必须混入通用任务数据。** 案例数量少时，按小配比混入通用任务做 LoRA 微调，避免把\"逢收尾必验证\"学成新的过拟合，也降低灾难性遗忘风险。\n- **学习信号必须带证据。** 单一总分无法指出该改哪里。可供学习的评价至少包含：任务成功/部分成功/失败、每个维度各自的结论、每条结论对应的证据位置（哪一轮对话、哪一次工具调用）、失败的类型标签。验证器还应被允许在证据不足时**拒绝评分**——低置信度案例应排除在学习集之外，而不是当作事实固化。\n\n## 实践模式\n\n### 完整链路：失败归因 → 双集验证\n\n**① 采集与归因。** 从用户纠正、点踩、事后审计三类生产信号收集失败轨迹，按错误分类定位**首个错误步骤**并记录错误类别。轨迹前缀回归任务就是从这个决策边界截取的。\n\n**② 分流：该不该训练。** 先问 prompt、工具、代码约束、上下文管理能否解决；再沿字节链路排除工具/Harness/tokenizer 问题。都不要动权重时就不训练。\n\n**③ 选训练形态。** 按第七章评估数据集的类型映射到第八章用法：\n\n| 你手上的材料 | 训练用法 |\n|---|---|\n| 端到端回归任务（含验证器） | RL rollout 任务与可验证奖励（RLVR）；拒绝采样（RFT）的采样池 |\n| 轨迹前缀回归任务 | DPO 偏好对、决策边界的 SFT 示范、On-Policy Distillation 的教师状态 |\n| 失败归因记录（首个错误步骤与错误类别） | 过程监督的负标签（PRM）、RLVP 路径惩罚的规则来源 |\n| Rubric 多维评分与人工金标集 | 向量奖励的各维度、生成式奖励模型（GRM）的训练与校准数据 |\n\n**④ 截取轨迹前缀，构造偏好对。** 在决策边界上截出\"准备宣称完成\"的轨迹前缀：rejected 是过早结束的错误行为，chosen 是\"先运行测试、逐条核对验收条件，再下结论\"的期望行为。chosen 由教师模型生成，再经规则验证器过滤（拒绝采样）。案例太少时用数据扩充（换任务类型、换缺失的验证项、换完成措辞）形成数百条偏好对。失败原因、适用条件和验证器应随样本保存，方便追溯和复查。\n\n**⑤ LoRA DPO 训练。** 小配比混入通用任务数据防过拟合。参考配置：Qwen2.5-7B-Instruct + bf16 LoRA、4 epochs、学习率 3e-5、单卡约 24GB 显存。训练回执记录配置、数据哈希与时间戳。\n\n**⑥ 双集验证。** 对未完成任务集和已完成任务保留集分别让模型给出\"下一步动作\"，判定属于\"宣称完成\"还是\"继续验证\"：\n\n- **未完成任务集的过早结束率** —— 训练后应下降\n- **已完成任务保留集的正常收尾率** —— 训练后应保持\n- **过度矫正率 = 1 − 正常收尾率** —— 应维持在低位\n\n优先采用**格式固定、与训练提示一致的候选比较**（固定两个候选动作，比较模型更偏好哪一个，直接测量决策边界），而不是开放式自由生成。同时抽查通用能力，确认 LoRA 补丁没有破坏其他能力。\n\n**⑦ 记录与追溯。** 训练数据与评估集分开保存；数据构造有确定性模板和教师模型两条路径时，两条都留证据回执。\n\n### 案例参照：Coding Agent 过早结束（实验 8-17）\n\n配套数据：24 条轨迹前缀 bad case，覆盖四类过早结束——未跑测试就宣称完成、多目标只完成一部分、声称完成但验收条件未满足、遇错放弃宣称不可能（含删除失败测试/skip 等 reward hacking 变体）；与训练数据严格隔离的留出评估集为 boundary 12 条 + retention 8 条。\n\n实测结果：基座在固定候选比较的未完成任务集上选对 **3/12（25.0%）**，已完成任务保留集 **8/8（100%）**；LoRA DPO 后分别为 **11/12（91.7%）** 和 **8/8（100%）**。自由生成是补充诊断：过早结束 1/12→0/12，但正常收尾 6/8→0/8——**说明小数据 DPO 会让模型在开放式回答里过于谨慎**，因此主要结论只采用候选比较口径，不能外推成线上总体成功率提升。\n\n同一个问题还有 RL 分支：把\"宣称完成前必须跑通验收测试\"写成可验证奖励，测试对模型不可见，模型宣称完成时才运行，通过 +1、不通过 −1。\n\n### 另外两类常见案例的处理差异\n\n- **规则类反馈（如\"中文直引号应统一为弯引号\"）**：期望描述不是可直接训练的规则，同一个引号在中文自然语言、英文原文、Markdown 行内代码、代码块、注释、JSON、路径中角色完全不同。正确做法是**作用域敏感的最小编辑**：先把规则写成可审计的 Skill（正例覆盖需转换的中文段落与中文注释，反例覆盖英文原文、字符串字面量、JSON、路径、行内代码），它同时作为合成数据的标签依据、训练后的回归规范和规则变更时的重训输入。\n- **byte-exact 复制类（如 `edit_file` 的 `old_string` 匹配失败）**：把复制任务抽象成三个可验证任务——直接逐字复述、在相似且等长的多个字符串中选择完全相同的目标、把指定字符串完整抄写到 `old_string` 工具参数。样本特意包含真实编辑最容易损坏的空格、换行、反斜杠、Unicode 组合字符。训练后要用独立 tokenizer 审计排除词元化造成的假象：若 round-trip 上限本身就是 80.1%，模型测到 80.1% 就不能算作纯能力提升。\n\n### 从运行轨迹中提取学习信号（三层验证）\n\n评价一条轨迹实质是依次回答三个问题：**事情是否办成了、是否以允许的方式办成、是否让用户舒服。**\n\n- **底层结果验证器**——读测试结果、数据库状态、工具返回。这类信号来自环境真实状态，比模型对自己行为的描述可靠，是三层中最应优先建立的一层。\n- **中间过程验证器**——检查业务规则、权限和动作序列，区分\"结果已达成\"与\"结果以允许的路径达成\"。删除失败测试用例也能让测试通过；口头承诺也能得到暂时满意。政策库、权限表与动作轨迹均可精确表达，因此这层同样可以由代码判定。\n- **上层质量验证器**——是否耐心、是否提供合规变通、文本是否自然简洁。用 LLM-as-a-Judge 加预定义 Rubric，要求逐项给分并引用轨迹证据。\n\n输出形态决定它能否成为学习信号：单一总分只能反映一次运行的优劣。四项内容（成败判定、每维度结论、证据位置、失败类型标签）齐备，后续才能判断该更新知识、提示词、程序还是模型参数。\n\n## 常见陷阱\n\n- **把失败轨迹直接当正确示范训练**，把错误行为固化进参数。\n- **只优化边界集，不看保留集**，把模型训成永远不敢收尾的过度矫正状态。\n- **训练集与评估集共享任务或参数**，评估失去独立性；隔离规则要由测试强制，不靠人记得。\n- **用模型自述当完成判定**，模型很快学会\"口头声称去验证\"而不真的验证。\n- **把系统层损坏误报为后训练收益**：直接复述探针正确但工具调用仍失败时，该修的是 Harness 或工具协议。\n- **把 tokenizer/序列化损坏误判为模型复制能力不足**，训练前先做独立 tokenizer round-trip 审计。\n- **案例太少又不做扩充**，几条偏好对撑不起一个决策边界；或扩充时只换措辞不换任务类型与缺失验证项。\n- **小数据 DPO 不混通用数据**，学出\"逢 X 必 Y\"的新过拟合并带来灾难性遗忘。\n- **低置信度结论进入学习集**，错误经验和提示注入被固化并在后续任务持续放大。\n- **把开放式自由生成当主要验收口径**——小数据 DPO 下自由生成会过度保守，格式固定的候选比较才与训练提示一致。\n\n## 配套代码\n\n- `chapter8/premature-completion-dpo/` — 全书唯一从生产 bad case 出发的训练实验：24 条 bad case、boundary 12 + retention 8 留出评估集、隐藏测试；`python demo.py` 离线端到端演示，`python -m pytest -q test_pipeline.py` 机制单元测试，`python build_preference_data.py` 生成偏好对（`--teacher` 走教师模型拒绝采样路径），`python train_dpo.py --smoke` 数据/tokenizer 前向检查，`python train_dpo.py` 单卡 LoRA DPO，`python evaluate.py --decision-score` 双集候选比较评估，`python train_grpo_optional.py` 同一问题的可选 RL 分支。\n- `chapter8/curly-quote-sft/` — 规则类反馈的另一种监督目标：先写 `SKILL.md` 规范，再结构化合成数据做作用域敏感 SFT。\n- `chapter8/exact-copy-sft/` — byte-exact 复制 SFT，含 `tokenizer_audit.py` 排除词元化假象。\n- `chapter8/cot-distillation/` — \"生成候选—验证过滤—只留正确轨迹\"的拒绝采样流水线范例。\n\n## 深度阅读\n\n- `book/chapter8.md`「从问题案例到后训练」\n- `book/chapter8.md`「SFT 数据合成：从示范到可训练轨迹」\n- `book/chapter8.md`「奖励设计：如何把任务目标变成学习信号」\n- `book/chapter9.md`「从运行轨迹中获得学习信号」\n","frontmatter":{"name":"bad-case-to-dpo","description":"把生产 bad case / 失败轨迹转成训练数据时使用——从失败归因、轨迹前缀截取、DPO 偏好对构造、LoRA 训练到边界集与保留集双集验证的完整链路；也用于判断某类问题该走 SFT、DPO、RL 还是先修 Harness/工具/tokenizer，以及如何从运行轨迹中提取带证据的结构化学习信号。触发词：bad case、失败归因、DPO、偏好对、轨迹前缀、拒绝采样、过度矫正、边界集、保留集、过早结束、reward hacking、LoRA 微调、训练评估隔离。"},"isInternal":false,"tokens":4575,"sizeBytes":12302},{"name":"SKILL.md","path":"skills/coding-agent-harness/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/coding-agent-harness/SKILL.md","title":"coding-agent-harness","category":"anthropic-skill","format":"markdown","content":"---\nname: coding-agent-harness\ndescription: 搭建 Coding Agent 或设计 Agent 护栏时使用——当你要构建能自主读写代码、跑测试、自我纠错的编码 Agent，或为已有 Agent 系统补约束/验证/纠正机制、设计执行边界与验收基线、判断某类任务是否适合交给 Agent、优化 Harness 提示词与工具集时使用。覆盖 Harness 四组件、任务四象限、四条设计原则与业界实践。\n---\n\n# Coding Agent 与 Harness 工程\n\n## 何时使用\n- 从零搭建 Coding Agent（选工具集、定工作流、接测试反馈）\n- 为已有 Agent 补可靠性：加护栏、验收基线、执行边界、回退手段\n- 评估一个任务是否适合交给 Agent 自主执行（四象限判断）\n- Agent \"能跑但不可靠\"：跑偏、走破坏性捷径、过早宣布完成\n- 优化 Harness 本身（提示词、工具中间件、自验证循环）而不是换模型\n\n## 核心原则\n\n**Agent = Model + Harness，Harness = 上下文管理 + 工具接口 + 约束 + 验证 + 纠正。**\nHarness 是\"Agent 边界内、模型之外\"的运行与治理层：工具定义、调用适配器、沙箱权限属于 Harness；沙箱内的文件进程、外部数据库、用户属于 Environment。模型能力趋同后，竞争力在 Harness。\n\n**Coding Agent 场景的 Harness 四组件**（把抽象机制落地成工程件）：\n\n| 组件 | 回答的问题 | 落地形态 |\n| --- | --- | --- |\n| 验收基线 | 什么算做完了 | 测试套件、CI 管道、代码审查标准 |\n| 执行边界 | 能碰什么不能碰什么 | 模块边界、依赖规则、权限控制 |\n| 反馈信号 | 自动化的对错判断 | Linter 输出、测试结果、类型检查错误 |\n| 回退手段 | 出了问题怎么恢复 | Git 版本控制、沙盒隔离、快照回滚 |\n\n**任务四象限（目标清晰度 × 验证自动化程度）**——Harness 的目标是把任务推向\"目标明确 + 可自动验证\"：\n\n- 目标明确 + 可自动验证 = **最佳区域**（修复有测试用例的 bug）\n- 目标明确 + 需人工验证 = **吞吐量受限**，天花板是人的审查速度\n- 目标模糊 + 可自动验证 = **高效地跑偏**（如拿 linter 分数优化\"代码质量\"）\n- 目标模糊 + 需人工验证 = **难以启动**（如\"让 UI 更好看\"）\n\n代码编写天然处于象限核心：测试套件给验收标准，Linter/类型检查给即时验证，Git 给版本控制与回退。Coding Agent 成熟度最高不是因为代码模型最强，而是软件工程几十年积累的基础设施天然就是一套 Harness。\n\n**四条可迁移的设计原则**：\n\n1. **约束优先于指导**——能用代码强制的规则不要用文档建议。Linter 规则、类型约束、CI 检查是\"做不了\"，系统提示词里\"请遵循...\"只是\"建议别做\"。\n2. **验证要自动化**——人工审查是不可扩展的瓶颈，测试/检查/监控的投入回报率远高于加人力。\n3. **反馈越快越好、越结构化越好**——错误信息越详细、越接近出错时刻，Agent 纠正效率越高。\n4. **回退要可靠**——有安全网 Agent 才敢试错；Git 分支、沙盒、快照确保任何错误可逆。\n\n**约束管动作，不只是管结果。** 验收基线管结果对不对，执行边界管过程：删库重建\"修复\"了故障但数据没了，删光重写让编译通过但实现没了。这类破坏性捷径 Agent 总能绕开指标找到（reward hacking 的日常形态），因此 `rm -rf`、删生产数据、覆盖未读文件要设专门检查与审批。\n\n**并行调用的故障边界控制**：一个工具失败时，故障只在同一批并行调用内传播（级联中止依赖它的调用），不取消独立调用，不上升到父级操作、不让整个任务中止。每个工具声明是否支持并发（默认否，失败安全）。\n\n**业界经验**：\n- 大规模代码迁移成功靠三件事：知识必须存在于代码库本身（Agent 看不到的等于不存在）、约束编码进 Linter/CI 而非文档、验证与纠正全链路自动化。\n- LangChain 只优化 Harness（提示词、工具中间件、自验证循环）就把 Terminal Bench 2.0 从 52.8% 提到 66.5%，并用 Agent 分析失败轨迹反哺 Harness，让 Harness 工程从经验驱动变数据驱动。\n- Anthropic 拆两个角色：初始化 Agent 分解任务清单，执行 Agent 逐步推进并留下清晰的交接产物，解决\"一次想做太多\"和\"过早声称完成\"。\n\n## 实践模式\n\n**建一个 Coding Agent 的最小清单**：\n\n1. **工具集**：文件读写（read/write/edit）、目录浏览（glob/ls）、内容搜索（grep）、命令执行（bash）七件套；每个工具命名直观、参数带例子、边界有说明（防呆设计）。\n2. **工作流**：先理解项目（读文档、建认知框架）→ 设计 → 实现 → **立即写测试并跑** → 失败则分析-定位-修复循环，直到测试全绿。把\"测试通过\"而非\"代码写完\"定义为完成标准——跳过测试直接报完成是 Coding Agent 最常见的偷懒方式。\n3. **验收基线**：接入现成的测试套件、Linter、类型检查、CI；没有就先补最小可跑的。\n4. **执行边界**：默认权限最小化（故障安全默认值，能力默认关闭、显式开放）；危险命令走审批。\n5. **回退手段**：每次任务前开 Git 分支或快照；沙盒内执行不可逆操作。\n6. **反馈回路**：把 Linter/测试/编译错误结构化地喂回上下文（附行号、文件路径、错误类型）。\n7. **持续改进**：收集失败轨迹，让 Agent 分析轨迹反哺 Harness 修改。\n\n**上下文与环境注入**（Harness 的上下文层）：大文件按行号范围读取并给每行加行号前缀；长命令输出只保留头部（错误上下文）与尾部（错误总结）并说明完整输出已落盘；每次推理前以状态栏形式动态注入当前工作目录、git 分支、最近提交、未暂存变更（动态追加，别硬编码进系统提示词以免破坏 KV Cache）；维护持久化终端会话保留 cd/环境变量状态。\n\n## 常见陷阱\n- 把指导写进提示词而不落成代码约束——模型会忽略\"请遵循...\"式建议\n- 没有验收基线就放权：Agent 高效地往错误方向跑，或走破坏性捷径（删库重建、删光重写）\n- 写完代码不跑测试就报告\"任务完成\"\n- 把整个代码库一股脑塞进上下文，既不经济也没必要\n- 一个工具失败就中止整批并行调用甚至整个任务\n- 只换模型不修 Harness：基准提升往往来自 Harness 而非模型\n- 环境信息硬编码在静态系统提示词里\n\n## 配套代码\n- `chapter5/coding-agent/` — 纯 Python 实现的生产级 Coding Agent：16 个工具、patch 应用、测试/lint 验收反馈与失败路径\n- `chapter1/context/` — 上下文感知 Agent 与消融实验：量化 history/reasoning/工具调用/工具结果各自的作用\n- `chapter1/web-search-agent/` — 基于 Kimi Formula API 的自主 ReAct 搜索 Agent，展示\"模型即 Agent\"的最小闭环\n- `chapter1/search-codegen/` — Responses API 深度研究 Agent：托管 web_search + code_interpreter 的编排\n- `chapter1/learning-from-experience/` — LLM 上下文学习 vs 传统 RL 对照，理解 Agent 经验从哪来\n- `chapter1/image-gen-workflow/` — 工作流路线 vs 原生生成路线对照：何时该用固定 Harness、何时该交给模型自主\n\n## 深度阅读\n- `book/chapter5.md`「Coding Agent」→「Harness 工程在 Coding Agent 中的实践」\n- `book/chapter1.md`「Harness 工程：模型之外的竞争力」\n","frontmatter":{"name":"coding-agent-harness","description":"搭建 Coding Agent 或设计 Agent 护栏时使用——当你要构建能自主读写代码、跑测试、自我纠错的编码 Agent，或为已有 Agent 系统补约束/验证/纠正机制、设计执行边界与验收基线、判断某类任务是否适合交给 Agent、优化 Harness 提示词与工具集时使用。覆盖 Harness 四组件、任务四象限、四条设计原则与业界实践。"},"isInternal":false,"tokens":2732,"sizeBytes":7662},{"name":"SKILL.md","path":"skills/computer-use/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/computer-use/SKILL.md","title":"computer-use","category":"anthropic-skill","format":"markdown","content":"---\nname: computer-use\ndescription: >-\n  构建 GUI 自动化 Agent、让 Agent 像人一样看屏幕并用鼠标键盘操作桌面或浏览器软件时使用。\n  覆盖感知-思考-行动循环、动作空间（GUI/bash/文件编辑）、视觉定位 Grounding 三条路线\n  （结构化元素索引、Set-of-Mark、纯坐标预测）、分辨率坐标缩放、关键帧观察接口、世界模型与移动端生态壁垒。\n  触发词：Computer Use、GUI 自动化、截图、Grounding、browser-use、Set-of-Mark、视觉定位、坐标缩放、OSWorld。\n---\n\n# Computer Use：GUI 自动化 Agent\n\n## 何时使用\n\n- 要让 Agent 操作没有 API 的软件：填表、改系统设置、在网页上完成多步流程。\n- 要评估或实现\"截图 → 决策 → 执行动作\"的闭环，选模型、选 grounding 方案、选框架。\n- 定位不准、坐标偏移、点击错元素，需要排查 grounding 与坐标缩放链路。\n- Agent 每 3–5 秒才看一眼屏幕，错过通知、视频、弹窗等\"两帧之间发生的事\"。\n- 要把 Computer Use 扩展到移动端（Android 无障碍服务）或评估平台封禁风险。\n- 设计不可逆操作（删除、购买、提交）前的确认与安全边界。\n- 要减少操作步数与等待时间，让 Agent 达到\"实用\"而不只是\"答对\"（对照 OSWorld-Human 的人类基线）。\n- 没有编程 API 可用、Selenium 之类脚本化方案难以维护页面的场景。\n- 要在容器化虚拟桌面中跑 Agent，并隔离不可逆操作对真实环境的影响。\n\n## 核心原则\n\n- **核心是感知-思考-行动循环**：截图 → 多模态模型输出思考 + 一个动作 → 执行层真实执行（移动鼠标、点击、输入）→ 等界面响应再截图进入下一轮。\n- **区分\"看懂界面\"和\"完成任务\"**：前者可用一次截图问答测量（多模态理解）；后者要求把理解和动作放进闭环，处理页面加载、状态变化、误操作和不可逆后果。每执行一步都要**重新确认现实是否仍符合计划**。\n- **动作空间分三类**：GUI 操作（鼠标移动/点击/拖拽/滚动、键盘输入/组合键/长按、截图与等待）、持久 bash 会话（跨调用保持环境状态，用哨兵字符串判命令是否执行完）、字符串匹配的文件编辑（比整文件覆盖更精确，可撤销）。\n- **动作空间不是供应商私有协议**：只要 Harness 能把同样的截图、动作约束和执行结果转换成目标模型支持的消息与结构化输出，Claude、开放权重视觉模型和自托管端点都能驱动同一个循环。\n- **Grounding 优先把定位变成选择题**：先给元素编号，模型只报 ID，系统换算中心坐标。选择题比填空题容易答对——模型说\"点击 [123]\"而不是\"点击 (350, 464)\"。三条路线按界面性质选：\n  - **结构化元素索引**（DOM / Accessibility Tree，browser-use 路线）：结构化信息可得时首选，最精确稳定，无分割模型的漏检误检。\n  - **Set-of-Mark 视觉标注**：用分割模型切候选区域叠加编号，不需要 DOM，原生桌面软件、游戏、Canvas/WebGL 界面适用。\n  - **纯坐标预测**（SeeClick、Claude computer use）：直接在 GUI 截图-坐标配对上训练的模型更直接，省去标注步骤，但小元素和密集界面精度差。\n- **坐标预测必须做分辨率管理**：模型对坐标的理解依赖训练分辨率，不匹配就系统性偏移。按**宽高比**选最接近的目标分辨率做双向缩放（如 2560×1440 的 16:9 屏幕选 FWXGA 1366×768，模型返回 (683,384) 反推真实坐标约 (1280,720)）。切忌非等比拉伸把画面压扁。\n- **\"屏幕是静止的\"是危险假设**：该重新设计的是观察接口而不是动作接口——用关键帧截图（小模型判断是否有意义的变化，变化频繁时约 1 秒一次）、音量门控的语音转写、把截图压成一句持久文字描述来压缩多模态历史。\n- **世界模型带来\"推测执行\"**：行动前预测候选动作造成的状态差异，一致就沿计划继续，偏离才停下重规划。要预测的是**可检查的状态差异**（窗口、焦点、滚动位置、输入框内容、加载状态、权限、网络返回），不是生成逼真未来截图。\n- **生态壁垒是结构性问题**：Agent 直达目标会绕过广告与推荐变现链路，平台有动机封禁；这不只是 CAPTCHA 的技术对抗，短期难以调和。\n- **循环节奏与尺度**：Computer Use 的时间尺度是亚秒到秒——屏幕在两帧之间持续变化，因此\"动作后重新确认现实\"不是可选项而是循环的必要组成部分。这与语音（10ms–1s，可被打断）和机器人（毫秒级，动作分块可抢占）是不同的时机问题。\n- **结构化索引不省 token 但省错误**：把所有可交互元素及其属性发给模型成本高，但换来定位准确稳定，且免去分割模型的漏检误检——这是值得的交换。\n- **browser-use 式四步流程**：CDP 取 DOM 与无障碍信息 → 检测可交互元素 → 标注唯一 ID 并在截图绘边界框 → 同步生成\"ID → 元素描述\"文本列表；模型只输出 ID，系统用中心坐标执行。\n\n## 实践模式\n\n1. **搭循环**：Harness 负责截图、把动作约束转换成目标模型支持的消息与结构化输出、执行结果回传。同一套循环可换驱动模型（Claude、开放权重 VLM、自托管 vLLM/SGLang 端点），并保留实际端点与模型 ID 以便区分实验组。\n2. **选 grounding 路线**：先问\"这个界面有没有结构化信息可得\"——Web 走 DOM/a11y 索引（CDP 取 DOM → 检测可交互元素 → 标注唯一 ID 并在截图绘边界框 → 同步生成 ID 到元素的文本列表）；原生桌面软件、Canvas/WebGL、游戏走视觉标注或坐标预测；模型做过 GUI 定位训练才优先坐标预测。\n3. **实现坐标缩放层**：枚举目标模型支持的分辨率档位，按宽高比匹配；截图时等比缩放送入，动作坐标按比例反算回真实屏幕。\n4. **每步只做一个动作**：保留每步截图与动作轨迹，便于回放和验收；页面加载用 `wait`，不要盲点。\n5. **安全边界**：默认只读；不点击验证码、不登录、不提交、不购买、不改外部数据；不可逆操作先在隔离虚拟桌面预测是否出现确认框，必要时请求用户确认。凭证不落盘，最终截图要能佐证结论。\n6. **恢复策略要预置**：遇到验证码、权限弹窗、页面 404 时按只读恢复指令改走可达路径（如改用公开 JSON 接口取数据），而不是反复重试或点击挑战。\n6. **增强观察接口**：关键帧 + 音量门控 ASR + 文字描述三件套，让 Agent 对弹窗、视频、会议人声有感知，并让被清理出上下文的原图仍留下文字痕迹。\n7. **移动端适配**：动作空间从\"鼠标坐标 + 键盘\"换成无障碍服务 API（如 Android AccessibilityService）读写元素、下发点击与输入；坐标语义变为手势类型（单击/长按/滑动起点）的边界。\n8. **验收要测量效率**：准确率达到人类水平不等于实用——对照人类操作步数与等待时间，把\"步骤数、总时长\"纳入验收指标，并记录真实运行证据（截图哈希、动作轨迹）。\n\n## 常见陷阱\n\n- **把截图答对当成任务完成**：没有闭环、不重新确认现实，页面早已跳转还在点原来的坐标。\n- **非等比缩放**：把 16:9 硬塞进 4:3，画面横向压扁，坐标判断整体偏移。\n- **分辨率不匹配不换算**：直接把模型在训练分辨率下输出的坐标当真实屏幕坐标用。\n- **密集界面/小元素上裸报坐标**：三条路线在此都容易出错，优先编号选择题方案。\n- **分割模型漏检误检**：视觉标注路线里候选区域切错，模型只能从错的选项里选。\n- **每步多个动作**：中间页面变化无法回放定位，错误无法归因。\n- **假设屏幕静止**：两帧之间的通知、视频、声音全部丢失，任务在错误的世界观上推进。\n- **忽视平台封禁与验证码**：消费级场景中账号可能被直接限制，比技术问题更难解。\n- **只关注准确率不看效率**：步骤数和等待时间远超人类，成功也不可用。\n- **把不同模型的运行混为一组**：供应商与开放权重是不同实验组，必须分别记录端点、模型 ID 与证据。\n\n## 配套代码\n\n- `chapter6/claude-computer-use-native/` — 实验 6-8（Anthropic 原生路径）：容器化 Ubuntu 桌面中的官方 Computer Use Demo，`computer` / `bash` / 编辑器三类原生工具的真实运行与确定性验收记录。\n- `chapter6/computer-use-open-model/` — 实验 6-8/6-9（开放模型路径）：同一\"截图 → 结构化动作 → 浏览器执行\"循环，默认 Qwen3-VL 32B Instruct 驱动 browser-use，可接 OpenRouter 或自托管 vLLM/SGLang；含端点合格性契约（收截图、产出 Browser Use 动作 schema、每步一个动作、不静默替换模型）。\n- 两个 companion 都保留了真实运行证据（截图哈希、动作轨迹、确定性验收），可作为自己实现时的证据门禁模板；其中原生路径还记录了一次撞上 Google reCAPTCHA 后按只读恢复指令改走公开天气 JSON 接口、全程未点击挑战的完整轨迹。\n- 语音相关（同为\"时机\"扩展，可作对照）：`chapter6/end-to-end-speech/`、`chapter6/streaming-speech/`、`chapter6/controllable-tts/`、`chapter6/live-audio/`、`chapter6/phone-agent/`。\n- 机器人相关（从屏幕像素到物理传感器）：`chapter6/gemini-xlerobot-navigation/`、`chapter6/rgb-sim2real-grasping/`、`chapter6/xlerobot-teleoperation/`。\n- 移动端基准与评测可参考第七章 AndroidWorld 一节；本章 `chapter6/phone-agent/` 给出真实手机上的 Agent 驱动样例。\n\n## 深度阅读\n\n- `book/chapter6.md`「模态与触发时机的扩展」\n- `book/chapter6.md`「Computer Use：GUI 自动化 Agent」\n- 实验记录与证据门禁模板见 `chapter6/computer-use-open-model/` 与 `chapter6/claude-computer-use-native/` 的 README 与 `validation/` 目录。\n","frontmatter":{"name":"computer-use","description":"构建 GUI 自动化 Agent、让 Agent 像人一样看屏幕并用鼠标键盘操作桌面或浏览器软件时使用。 覆盖感知-思考-行动循环、动作空间（GUI/bash/文件编辑）、视觉定位 Grounding 三条路线 （结构化元素索引、Set-of-Mark、纯坐标预测）、分辨率坐标缩放、关键帧观察接口、世界模型与移动端生态壁垒。 触发词：Computer Use、GUI 自动化、截图、Grounding、browser-use、Set-of-Mark、视觉定位、坐标缩放、OSWorld。"},"isInternal":false,"tokens":3813,"sizeBytes":10299},{"name":"SKILL.md","path":"skills/context-compression/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/context-compression/SKILL.md","title":"context-compression","category":"anthropic-skill","format":"markdown","content":"---\nname: context-compression\ndescription: 上下文膨胀、工具结果撑爆窗口、Agent 决策质量随轮次下降时使用——上下文压缩的三个动机（长度成本、思考质量、上下文焦虑）、压缩即检索的机制、六种压缩策略实测数据、生产级五层分层压缩、四条设计原则，以及用子 Agent 隔离代替压缩。\n---\n\n# 上下文压缩策略\n\n压缩解决的是相反方向的问题：**如何为上下文做减法**——什么时候压缩、怎么压缩、为什么即使上下文没满也应该压缩。核心认知：**上下文学习本质上是检索而非推理**，压缩就是把需要思考才能得到的结论，变成可以直接检索的知识。\n\n## 何时使用\n\n- 工具调用结果动辄数万字符，几轮交互就撑满 128K 窗口\n- Agent 在长任务中「明明窗口没满，却找不到关键信息」或反复纠结已解决的问题\n- 模型在任务尚未完成前提前收尾、草率下结论\n- 设计压缩策略（何时触发、压缩什么、保留什么）或排查压缩副作用\n- 评估「把大任务委派给子 Agent」与「主 Agent 自己做完再压缩」的取舍\n\n## 核心原则\n\n- **三个动机，层次不同**：① 长度与成本约束（窗口有限、token 越贵、延迟越高）；② 提升思考质量——总结后的知识比原始形式更利于模型使用，十几轮搜索的原始结果散落各处，模型每次决策都要在数万 token 中反复检索；③ 缓解**上下文焦虑（Context Anxiety）**——模型认为窗口即将耗尽时可能在任务完成前提前收尾，在未接近耗尽时就提前压缩可能提升决策质量。\n- **上下文窗口是一台只有一半的检索引擎**：检索这一半极强（相当于每次前向传播都内置了 RAG），但缺「提炼层」——上下文里的东西从来不会被自动数一遍、建索引或就地总结。任何「关于这些内容的结论」都要从原始记录现算一遍，代价随内容量 N 上涨。\n- **压缩与状态栏是同一枚硬币的两面**：状态栏把算好的结论**加**进上下文（由代码确定性维护），压缩把臃肿的原始记录**换**成算好的结论（多用一次 LLM 调用蒸馏）。\n- **上下文腐化（Context Rot）≠ 溢出**：溢出是「装不下了」，腐化是「装得下但找不到了」——后者更隐蔽，Agent 表面正常工作，决策质量悄然下降。注意力权重被分散到更多 token 上，无关内容一旦占大头，决策质量明显下滑。\n- **主动显式提炼，不要期望模型自动学习**：与其让模型被动在海量信息中检索，不如主动提供经过提炼的高密度结构化知识。\n- **压缩最容易丢失**：早期的架构决策、约束背后的理由、失败的路径。因此 Agent 需要定期把进展记录到文档，而不是把所有信息零散堆在执行历史里。\n- **隔离优于压缩**：压缩是信息已进入上下文后的事后有损补救；隔离让大体积中间信息根本不进入主上下文。\n\n## 实践模式\n\n### 1. 六种压缩策略实测对比（实验 2-10）\n\n任务：识别并追踪 OpenAI 联合创始人的职业状态；Kimi K3（原生约 1M 窗口，实验刻意限制在 128K 预算以触发压缩）。\n\n| 策略 | 做法 | 迭代 | Token | 压缩率 | 问题 |\n| --- | --- | --- | --- | --- | --- |\n| 无压缩 | 完整保留原始结果 | 5 次即溢出失败 | ~165,000 | — | 7 次搜索累计约 367,000 字符（平均 52,000/次），数次搜索即耗尽 128K |\n| 个体摘要 | 每个结果独立生成 2-3 段摘要 | 12 | 276,608 | 10.9% | 信息碎片化，多页重复描述同一事件 |\n| 组合摘要 | 所有结果合并后一份综合摘要 | 10 | 93,449 | 4.3% | 输入超长必须截断，可能丢失末尾信息 |\n| **上下文感知** | 压缩提示中带入查询意图与已积累信息 | 7 | 40,157 | ~3.0% | 最优平衡点 |\n| 带引用的上下文感知 | 智能压缩 + 每条事实附带来源 URL | 7 | — | — | 内容有损、索引无损，可回溯原文 |\n| 自适应窗口化 | 阈值触发 + 批量压缩 + 防重复 | — | 174,601 | — | 初期保留完整原始信息，灵活性最大 |\n\n> 压缩率定义为「压缩后体积 / 原文体积」，数值越小表示压得越狠。上下文感知压缩将 token 使用量减少 75% 以上。\n\n**上下文感知的提示词写法**：在压缩提示中指定 `Given the search query: {query}` 和 `Current context: {context}`，引导模型生成针对性摘要。实测把约 150K 字符压到 2K 字符时，仍保留创始人姓名与职位变动等后续任务需要的关键信息。\n\n### 2. 自适应窗口化三机制（推荐默认）\n\n- **阈值触发**：持续监控上下文使用率，prompt token 超过窗口 80% 时才激活压缩（如 102,400 / 128K）。\n- **批量压缩**：触发时一次性压缩所有未标记的工具结果，而不是每轮零碎压。\n- **防重复保护**：添加 `[COMPRESSED]` 标记，确保已压缩内容永不被重复处理。\n\n### 3. 压缩与 KV Cache 的共存\n\n压缩不是在单次 API 调用中修改上下文，而是在**两次 API 调用之间**由框架预处理消息列表：\n\n1. **System Prompt 和 Tool Definitions 永远不动**——静态前缀持续缓存。\n2. **压缩对象是对话历史中的 tool results**——替换位置之后的缓存失效，之前的仍有效。\n3. **有意识的权衡**：不压缩则溢出失败；压缩损失部分缓存但长度可控、信息密度更高。**压缩频次需要权衡——频繁压缩频繁破坏缓存，最好在接近阈值时批量压缩，而不是每轮都压。**\n\n### 4. 生产级五层分层压缩（Claude Code 参照）\n\n不同信息有不同保质期，压缩策略应与预期生命周期匹配，按代价从低到高排列：\n\n1. **工具结果预算控制**：大体积输出存磁盘，模型只看摘要预览；替换决策一旦做出就冻结，保证缓存一致性。\n2. **噪声直接删除**：低价值内容（如大量搜索结果中只被用了几行的部分）直接移除，不做摘要——对噪声做摘要只是浪费 token。\n3. **API 层微压缩**：通过上下文编辑能力指示服务端从前缀移除指定工具结果，本地消息不变；零本地实现成本，但移除点之后缓存同样失效，产生一次缓存重建——适合上下文即将溢出、反正要付这次代价时用，不要频繁触发。\n4. **归档式摘要**：逐轮结构化摘要，像 git log 保留每轮独立记录，而非 git squash 合并成一条，保留对话逻辑脉络。\n5. **全量压缩**：LLM 驱动的完整压缩，作为最后手段；分两阶段（先压会话记忆，不行再全量），并配**连续失败熔断器**——生产数据显示大量会话被困在反复压缩失败的循环中，熔断器避免持续烧钱。\n\n### 5. 四条压缩设计原则\n\n- **信息价值的非均匀分布**：关键决策点（如人员名单）> 支撑性证据（如新闻细节）> 冗余噪声（网页导航栏、页脚广告）。\n- **语义完整性**：`Sutskever 于 2024 年 5 月离开 OpenAI` 不能压成 `Sutskever 离开`——时间和公司名是不可丢失的关键信息。\n- **任务相关性**：同样内容在「查找创始人名单」和「了解个人背景」两个任务下应产生不同压缩结果。检索类任务保广度，分析类任务保深度，创作类任务保灵感触发点；理想的 Agent 应按任务类型自适应选择压缩策略。\n- **压缩即理解**：有效压缩需要深层语义理解，负责压缩的模块本身要接近主模型能力，形成「模型调用模型」的递归架构；好处是显式压缩的结果可审查、可跨会话复用。\n\n### 6. 必须保留的四类信息\n\n无论哪种策略，压缩时都要显式 preserve：**decisions（决策）、constraints（约束）、failures（失败路径）、citations（来源引用）**。\n\n### 7. 隔离优于压缩：子 Agent 上下文隔离\n\n对比同一个任务「在代码库中找到处理支付回调的函数」：\n\n- **主 Agent 亲自搜索**：可能把十几个文件数万 token 原始代码纳入主上下文，找到目标后绝大部分沦为永久噪声，还得靠后续压缩清理。\n- **委派给搜索子 Agent**：主上下文只增加两条消息——一条任务描述，一条结论（「函数位于 `src/payment/callbacks.py` 的 `handle_callback`，另有两处调用点」）；中间过程的数万 token 随子 Agent 上下文一起丢弃。\n\n代价是子 Agent 看不到主 Agent 完整上下文，**任务描述必须自包含、目标明确**。Claude Code 的 Task 工具、各类 Deep Research 的检索子 Agent 都是这一模式的生产实现。\n\n## 常见陷阱\n\n- **每轮都压缩**：频繁破坏 KV Cache 前缀，应阈值触发 + 批量压缩。\n- **对噪声做摘要**：把只用了几行的搜索结果压成摘要，纯浪费 token，应直接删除。\n- **压缩时丢掉时间和主体**：语义不完整比不压缩更糟——模型会基于错误事实继续推理。\n- **用远弱于主模型的模块做压缩**：压缩即理解，能力差距大会丢关键信息。\n- **把压缩当成长度问题的唯一解**：即使窗口够大，压缩仍能提升思考质量、缓解上下文焦虑。\n- **让模型自己数数和统计**：查找是注意力强项，统计要遍历全部记录并维护计数状态；应提前把结论写进上下文。\n- **把所有进展只留在执行历史里**：早期架构决策、约束理由、失败路径最容易在压缩中丢失，必须定期落到文档。\n- **给子 Agent 派发含糊任务**：子 Agent 上下文隔离的代价就是任务描述必须自包含，否则结论质量无法保证。\n\n## 配套代码\n\n- `chapter2/context-compression/` — 实验 2-10：实现并对比 6 种压缩策略（`no_compression` / `individual` / `combined` / `context_aware` / `citations` / `windowed`），输出成功率、耗时、token、压缩率、溢出次数对比表；用 `python experiment.py -s context_aware` 单跑，`-m moonshot-v1-128k` 配合 `CONTEXT_WINDOW_SIZE=128K` 复现溢出。\n\n## 深度阅读\n\n- `book/chapter2.md`「上下文压缩策略」\n","frontmatter":{"name":"context-compression","description":"上下文膨胀、工具结果撑爆窗口、Agent 决策质量随轮次下降时使用——上下文压缩的三个动机（长度成本、思考质量、上下文焦虑）、压缩即检索的机制、六种压缩策略实测数据、生产级五层分层压缩、四条设计原则，以及用子 Agent 隔离代替压缩。"},"isInternal":false,"tokens":4027,"sizeBytes":10278},{"name":"SKILL.md","path":"skills/context-engineering/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/context-engineering/SKILL.md","title":"context-engineering","category":"anthropic-skill","format":"markdown","content":"---\nname: context-engineering\ndescription: 设计 Agent 系统提示词、上下文结构或按需加载的 Skill 时使用——覆盖 API 消息角色与「静态前缀 + 轨迹」结构、系统提示词写法（结构化、SOP、业务规则细化、few-shot）、Agent Skills 渐进式披露与 SKILL.md 编写、提示注入的上下文层防御，以及注意力位置偏好等布局原则。\n---\n\n# 上下文工程总纲\n\n上下文是 Agent 在每个决策点实际「看到」的全部信息：系统提示词、工具定义、用户消息、模型回复、工具执行结果。上下文工程就是系统性设计、组织、供给这些信息——模型智力只是基础，**上下文质量才是 Agent 能力的真正关键**。一个中等能力的模型配上精心组织的上下文，往往胜过一个顶级模型在信息匮乏下的盲目摸索。\n\n## 何时使用\n\n- 设计或重构 Agent 的系统提示词、工具定义、消息列表结构\n- 编写 / 审查一份 `SKILL.md`（元数据、路由描述、正文分层）\n- 排查「Agent 行为不稳定、违反业务规则、重复犯错、忘记约束」\n- 决定哪些知识该进系统提示词、哪些该做成按需加载的 Skill\n- 评估外部内容（网页、文档、邮件）进入上下文后的安全风险\n\n## 核心原则\n\n- **API 无状态，上下文由框架每轮重建。** 模型不会「记住」上一轮，Agent 框架必须每次都把完整消息历史送回去。\n- **上下文 = 四种消息角色 + `tools` 字段。** `system`（开发者规则，通常只有一条且在最前）、`user`（终端用户输入）、`assistant`（模型回复含 `tool_calls`）、`tool`（框架执行结果，靠 `tool_call_id` 与调用关联）；工具定义走请求顶层 `tools` 字段，不是消息角色。\n- **静态前缀 + 动态轨迹。** system prompt 与 tool definitions 全程不变，对话历史（trajectory）随交互持续增长。所有后续技术都在优化这个列表的内容与结构。\n- **模型决策、框架执行。** 模型只发出工具调用请求，真正执行工具的是 Agent 框架；循环「请求 → tool_calls → 执行 → 送回结果 → 再请求」就是 ReAct 循环的 API 实现。\n- **最低信息需求三件套**：代码信息（结构、职责、规范）、流程规范（分支、提交、评审、CI/CD）、环境信息（配置、数据库、密钥管理）。缺哪一类，Agent 就在哪一类上出错。\n- **新员工检验法**：如果一个聪明的新员工读完你的系统提示词还不知道该怎么做，Agent 也一样不知道。\n- **上下文学习是检索而非推理**：模型擅长从已有内容中查找，不擅长在前向传播中归纳统计。位置偏好（Lost in the Middle）意味着开头和结尾注意力最高，中部易被忽视——关键信息放两端。\n- **与模型厂商的训练方法保持一致**：选择 Agent 交互模式时优先采用厂商专门训练过的模式（Skills、tool_search 等），同生态内表现最佳。\n\n## 实践模式\n\n### 1. 系统提示词四维度\n\n- **语气与风格**：用明确指令而非请求，如 `You MUST answer concisely with fewer than 4 lines`；无法完成任务时 `keep your response to 1-2 sentences` 且不要解释为什么不能做。大写（`NEVER do X`）比 `Please avoid doing X` 更能引起注意，但过度使用会稀释效果，只留给真正关键的约束。\n- **结构化**：Markdown 标题（`#`、`##`）提供人可读的层次，XML 标签提供机器可解析的精确语义（`<file_operation>`、`<network_request>`），标签名本身携带语义。双层配合：Markdown 管组织逻辑，XML 管语义边界。\n- **流程驱动而非规则堆砌**：写成带分支的 SOP（Step 1 Validation → Step 2 Classification → ... → Step 5 Verification），让模型任何时刻都知道自己在哪个阶段、异常时按阶段处理，而不是遍历上百条零散规则找匹配项。\n- **业务规则细化到可执行**：把模糊规则（「根据任务情况选择合适的计费类型」）改写成布尔判断，例如 `NEVER use percentage_based_one_time for refunds and service cancellations. Use fixed_fee instead.`；成功率阈值直接映射到行为（>60% 可退款、<30% 拒绝任务）；计费粒度写死（每分钟 $0.05，汇总四舍五入到整数美元），并明确「节省」只基于现有账单计算。**提示词由产品经理基于线上数据设计，工程师负责准确编码，不擅自决定业务逻辑。**\n\n### 2. few-shot 示例的两个决策点\n\n- **位置**：放系统提示词 = 成为静态前缀对所有请求生效；或伪造一组 user/assistant 消息放在首轮对话中，适合按会话类型选用不同示例集。\n- **稳定性**：无论放哪，示例都处于上下文靠前区域，一旦确定必须字节级稳定——按请求动态检索「最相关」的示例等于每轮改写前缀，缓存会持续失效。为每类任务准备固定示例集。\n- **数量**：两三个精心挑选、覆盖边界情况的示例，胜过十个大同小异的示例——后者既占上下文，又稀释对规则本身的注意力。\n\n### 3. Agent Skills：渐进式披露三层\n\n- **第一层 元数据**：`SKILL.md` 顶部 YAML frontmatter 的 `name` + `description`，在正文加载前对 Agent 可见，用于路由判断。`description` 要写得像路由条件而非功能介绍：明确「何时使用」「何时不使用」的边界，给几条典型反例。写 `help with backend` 这种宽泛描述等于任何后端工作都能触发，路由必然失准。\n- **第二层 核心流程**：模型判断需要该 Skill 时才加载完整 `SKILL.md`（斜杠命令由客户端本地拦截展开；模型自主触发则多一次 ReAct 往返，正文作为 user message 追加）。\n- **第三层 细则**：通过文件引用深入到子文档（如 `html2pptx.md`、`reference.md`），Agent 按需选择性深入。\n- **上下文成本**：所有 Harness 都遵循「少量目录常驻、完整正文按需加载」。Skill 正文在调用位置追加到轨迹末尾，不改写已建立的前缀，因此对 KV Cache 友好。\n- **SKILL.md 四部分**（宝玉《图解 Skill》）：角色与读者；核心原则只留 3–5 条并配正反例；禁止清单记录高频错误、越权动作并写清合法例外；参考资料放术语表、模板、范文。规则写成「作用域 + 动作 + 例外 + 验证方式」，不要堆成越来越长的禁用词表。\n- Skill 还可捆绑可执行代码工具和模板文件，自包含、可独立版本控制。\n\n### 4. 上下文布局决策骨架\n\n```python\nstable_prefix = system_message            # 定了就不改\nstable_tools  = core_tool_schemas         # 固定顺序\ntrajectory    = load_message_history(session)\nstatus_message = make_status_message(derive_current_state(trajectory))\n\nif estimated_tokens(stable_prefix, trajectory, status_message) > budget:\n    trajectory = compress_old_evidence(\n        trajectory, preserve=[decisions, constraints, failures, citations]\n    )\n\nrequest.messages = [stable_prefix] + trajectory + [status_message]\nrequest.tools = stable_tools\n```\n\n### 5. 提示注入的上下文层防御\n\n第一道防线是帮模型分清「指令」与「数据」：\n\n- **来源标记**：外部内容注入前用 `<external_content source=\"webpage\">...</external_content>` 包裹并标注来源。\n- **结构化角色**：严格用 system/user/assistant/tool 角色体系传递信息，绝不把工具结果混入 user 消息——那等于亲手抹掉模型辨别来源的依据。\n- **输入清洗**：过滤「忽略之前的指令」等常见注入短语，只能作辅助，易被措辞变体绕过。\n- **把 Skill 和状态栏也当注入面**：Skill 本质是「把外部内容当作指令加载」的制度化形式，安装来源不明的 Skill 前必须审查内容；状态栏信息被模型高度信任，若摘要来自可被外部污染的数据源，信任会被反向利用。\n\n## 常见陷阱\n\n- **把时间戳、用户余额等动态信息写进 system prompt**——每轮改写前缀，缓存全失效（详见 `kv-cache-design`）。\n- **规则堆砌而无组织结构**：实验 2-4 显示，保留全部规则内容但打乱组织、去掉标题层次，任务成功率下降超过 30%，Agent 经常违反关键业务规则。\n- **清空工具描述**：保留函数签名但移除描述性文本，工具调用错误率增加 45%。\n- **盲目追求语气风格**：风格显著改变表达方式，但对任务完成率影响相对有限，不必在此过度投入。\n- **示例逐请求动态检索**：缓存持续失效，且不同示例集导致行为不可复现。\n- **所有场景塞进一个系统提示词**：既浪费 token（大部分与当前任务无关），又稀释注意力——应拆成按需加载的 Skill。\n- **让模型在业务规则上自由裁量**：模型优势在于遵循复杂指令和从长上下文提取信息，模糊规则会让同一任务在不同时间得到不同分类。\n- **把上下文层防御当作万无一失**：它只能降低攻击成功率，权限控制、沙盒隔离、高风险操作独立审查是另一层。\n\n## 配套代码\n\n- `chapter1/context/` — 多 provider 上下文感知 Agent，消融实验 1-1 对比 full / no history / no reasoning / no tool calls / no tool results 五种上下文模式。\n- `chapter2/prompt-engineering/` — 实验 2-4：基于 Tau-Bench 的提示工程消融框架，量化语气风格、指令组织、工具描述三个维度对任务完成率的影响。\n\n## 深度阅读\n\n- `book/chapter2.md`「上下文：决定 Agent 能力上限的关键」\n- `book/chapter2.md`「Agent 如何调用大模型：理解 API 的上下文结构」\n- `book/chapter2.md`「提示工程：优化系统提示词」\n- `book/chapter2.md`「动态提示词与 Agent Skills」\n","frontmatter":{"name":"context-engineering","description":"设计 Agent 系统提示词、上下文结构或按需加载的 Skill 时使用——覆盖 API 消息角色与「静态前缀 + 轨迹」结构、系统提示词写法（结构化、SOP、业务规则细化、few-shot）、Agent Skills 渐进式披露与 SKILL.md 编写、提示注入的上下文层防御，以及注意力位置偏好等布局原则。"},"isInternal":false,"tokens":3453,"sizeBytes":9948},{"name":"SKILL.md","path":"skills/error-recovery/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/error-recovery/SKILL.md","title":"error-recovery","category":"anthropic-skill","format":"markdown","content":"---\nname: error-recovery\ndescription: 排查或加固 Agent 故障恢复机制时使用——当 Agent 陷入无限循环、流式响应中途断开、上下文溢出、模型服务限流过载、需要跨厂商接管跑到一半的轨迹、设计重试与熔断策略、防止错误处理路径自身引发连锁故障时使用。覆盖四层故障分类、检测方法、分级恢复策略、熔断上限与流式中断恢复。\n---\n\n# 故障与错误恢复\n\n## 何时使用\n- Agent 反复调用同一工具毫无进展、陷入死循环或死亡螺旋\n- 流式响应在思考/正文/工具调用参数中途断开，需要续写\n- 模型 API 限流、过载、超时、输出触顶，需要重试或降级\n- 上下文窗口溢出、压缩失败、轨迹结构损坏（工具调用缺配对结果）\n- 主模型持续不可用，要把轨迹交给另一家模型接着跑\n- 设计重试策略、熔断阈值、错误暴露边界\n- 工具调用幻觉/参数畸形，需要让模型自我纠正\n\n## 核心原则\n\n**故障分类学：四层。** 先分类再处理，不同层的故障走完全不同的恢复路径：\n\n- **API 层**：限流（429）、过载、请求超时、连接中断、输出触顶被截断。与任务内容无关，是基础设施噪声——可重试。\n- **工具层**：幻觉调用（调用不存在的工具）、参数畸形、执行抛异常，以及最危险的一种：工具反复返回同一错误，模型不加改变地反复重试。\n- **上下文层**：窗口溢出、压缩失败、轨迹结构损坏。\n- **控制流层**：死循环（相同操作无进展）与死亡螺旋（恢复逻辑自身又调 LLM、再次出错、连锁反应）。\n\n**检测：先分类，再计数。** 第一个判断不是\"要不要重试\"而是\"值不值得重试\"：可重试错误（限流、过载、网络抖动）重试才有意义；不可重试错误（参数不合法、权限不足、工具不存在）原样重试一万次结果相同，必须改变输入或策略。生产级 Harness 维护一张\"错误 → 恢复策略\"的映射表，而不是笼统地\"出错就重试\"。单次错误之外还要检测**模式**：对\"工具名 + 参数\"计算指纹，相同指纹反复出现就是无进展循环的明确信号；每条恢复路径维护独立的连续失败计数，为熔断提供依据。\n\n**活性与完整性监控。** 流式连接最危险的失败不是断开（会立即报错），而是**静默卡死**——连接建立但数据流停止。SDK 超时往往只覆盖初始连接而非传输过程，需要独立的空闲看门狗（超过设定时间无新输出即判定卡死，主动杀死挂起的流并重试）。可推广为：**每个长连接都需要活性信号，而非仅依赖连接超时**。完整性监控针对轨迹结构：发现工具调用缺少配对结果消息时，在注入上下文前自动修复配对，而不是把结构异常抛给模型或用户。产品模式可用占位符宽容修补，训练数据收集模式则拒绝修复——合成占位符会污染训练数据。\n\n**恢复：分级升级，逐级透明。** 能用低级别解决就不升级：\n\n1. **静默重试**——可重试错误的默认动作。指数退避叠加随机抖动（避免客户端同步重试造成二次拥塞，尊重服务端的等待时长提示）；区分前台与后台调用：主循环失败要重试，标题生成、输入建议这类辅助性后台调用失败直接放弃，否则后台重试挤占主链路配额，形成\"重试放大\"。\n2. **降级与接续**——重试无效时改变请求本身。输出触顶：先静默提升输出上限重发，仍不够再在消息末尾追加元指令让模型从断点接续；主模型过载时降级到备用模型（先剥离旧模型私有格式块，否则新模型解析不了历史）；高成本模式被限流时暂时回落到标准模式。\n3. **暴露给用户**——所有自动手段用尽后才呈现错误，并附上已尝试过的恢复动作。\n\n**工具层错误走另一条路：不终止会话，把错误变成模型的输入。** 幻觉调用收到\"工具不存在\"的结构化错误结果；参数校验失败收到附带输入约束提示的错误；畸形参数（该是对象却输出字符串）在执行前先程序化修复。错误以普通工具结果身份进入上下文，由模型下一轮自行纠正——喂回的错误越具体，自我纠正成功率越高。\n\n**错误处理的边界不是单次请求，而是整个恢复循环。** 在确认无法恢复之前，中间错误不暴露给消费者（用户或订阅事件的下游系统）：恢复期间扣留错误消息，恢复成功则消费者毫无感知，所有手段均失败后才统一呈现。\n\n**跨厂商接管：带走文字，带不走凭证。** 换一家模型把轨迹接着跑完，真正的障碍不是接口地址，而是轨迹里有只属于原厂商的东西。工具调用与结果各家结构不同但语义一致，重新渲染即可；难办的是思考——它由可读文字和厂商凭证（证明这段思考出自它自己）构成，文字换一家仍读得懂，凭证换一家就失效。且凭证未必附在思考上，也可能附在工具调用上（如 Google 的 thoughtSignature），所以\"把思考删干净就安全\"反而会在严格校验的厂商处失败。接管方案按最严格的一端设计：把历史工具调用改写成文字叙述，模型不再当作真正调用过，但至少能接着跑。由此得到设计原则：**轨迹按中立格式存储**——思考拆成可移植文字与不可移植凭证两个槽位，工具调用只记名称与参数，标识符渲染成具体请求时按目标厂商重新生成；切换时凭证一律丢弃，文字以普通内容身份带入。中立轨迹还服务于评估重放、训练样本构造、经验提取。\n\n**终止：每条恢复路径都要有上限。** 恢复机制本身也可能失效：上下文压缩连续失败若干次就放弃压缩，权限分类连续失败就回退人工询问，输出接续最多固定轮数。阈值来自生产数据而非拍脑袋——Claude Code 的\"连续 3 次\"压缩熔断阈值来自真实会话统计（曾有会话连续失败三千余次，仅此一类无效重试每天全球浪费约 25 万次 API 调用；3 次是\"绝大多数故障此前已恢复\"与\"继续重试基本无望\"之间的经验拐点）。\n\n**死亡螺旋防护。** 错误处理路径中的逻辑本身又调用 LLM，再次出错引发连锁。真实案例：上下文溢出触发\"结束时自动提交代码\"钩子，钩子调 LLM 生成 commit message 再次溢出，又一次触发钩子。防护两条：错误路径上禁用一切会再次调用模型的副作用逻辑（宁可丢掉自动记忆提取之类的辅助功能），以及用递归深度计数器检测并打断残余连锁。最后叠加全局终止条件：最大迭代轮数、会话预算上限、连续失败超阈值升级人工。\n\n**流式中断的三个断点、三种恢复方式。** 断点可能出现在：思考中途、正文中途、工具调用参数中途。恢复方式：① 丢弃半截内容整轮重发（最贵但最稳）；② 把半截内容作为末尾 assistant 消息要求模型接着写（部分厂商原生支持，其余需显式标注待续写消息，没有该接口则退回下一种）；③ 追加一条元指令说明从断点继续。注意：半截的工具调用无法以原生结构回传，需先转成文字再让模型补完，拼接后重新解析校验；若半截输出里已有工具因流式提前执行，续写前按调用指纹去重，避免重复副作用；拼接处容易多出空白或重复字符——参数合法不等于语义正确。\n\n## 实践模式\n\n**建一张错误 → 策略映射表**（比\"出错就重试\"的根本改进）：\n\n1. 捕获异常 → 归入 API/工具/上下文/控制流四层之一\n2. 可重试？→ 指数退避 + 抖动静默重试（前台重试、后台放弃）\n3. 改变请求可救？→ 提升输出上限 / 追加接续元指令 / 降级备用模型 / 回落标准模式\n4. 工具层错误 → 结构化错误结果喂回上下文，让模型下轮自我纠正\n5. 持续失败 → 查恢复路径的连续失败计数器，超阈值熔断（阈值从生产日志统计得出）\n6. 全部失败 → 统一向用户暴露，附已尝试的恢复动作清单\n\n**流式恢复实现清单**：记录断点类型（思考/正文/参数）；半截工具调用转文字 + 指纹去重；拼接后重新解析校验参数；对比三种方式的 token 成本与恢复成功率，选默认路径。\n\n**接管实现清单**：轨迹存中立格式（文字/凭证分离）；渲染层按目标厂商重组；凭证一律丢弃；遇强制凭证校验的厂商，历史调用改写为文字叙述；切换后监控重复调用指纹。\n\n## 常见陷阱\n- 笼统\"出错就重试\"：不可重试的错误（参数不合法、权限不足）重试多少次都一样\n- 只依赖连接超时：静默卡死（连接通但无数据）检测不到，必须配空闲看门狗\n- 后台辅助调用也重试：重试放大挤占主链路配额\n- 恢复期间把中间错误暴露给用户或下游事件订阅者\n- 没有熔断上限：一条恢复路径连续失败三千次，白白烧掉海量 API 调用\n- 错误处理路径自身调用 LLM：死亡螺旋，连锁故障\n- 以为删掉思考就安全跨厂商接管：凭证可能挂在工具调用上\n- 续写半截输出不按调用指纹去重：已执行的工具产生重复副作用\n- 训练数据收集模式用占位符修补缺失消息：污染训练数据\n\n## 配套代码\n- `chapter5/provider-failover/` — 实验 5-1/5-2：中立轨迹格式实现跨厂商接管（直传/剥离/中立三臂对照）与流式三断点接续\n- `chapter5/log-diagnosis/` — 诊断 Agent 读轨迹定位根因、生成回归测试、真实重放验证并建 Issue 的完整闭环\n- `chapter5/adaptive-log-parser/` — 自愈循环示范：解析失败不报错，而是把失败样本交给 Agent 生成代码、测试、热更新\n\n## 深度阅读\n- `book/chapter5.md`「故障与错误恢复」\n- `book/chapter5.md`「Coding Agent」→「实现技巧」（并行工具调用、流式执行与级联中止）\n- `book/chapter1.md`「Harness 工程：模型之外的竞争力」（纠正机制与\"不暴露中间态\"原则）\n","frontmatter":{"name":"error-recovery","description":"排查或加固 Agent 故障恢复机制时使用——当 Agent 陷入无限循环、流式响应中途断开、上下文溢出、模型服务限流过载、需要跨厂商接管跑到一半的轨迹、设计重试与熔断策略、防止错误处理路径自身引发连锁故障时使用。覆盖四层故障分类、检测方法、分级恢复策略、熔断上限与流式中断恢复。"},"isInternal":false,"tokens":3953,"sizeBytes":10382},{"name":"SKILL.md","path":"skills/eval-dataset-design/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/eval-dataset-design/SKILL.md","title":"eval-dataset-design","category":"anthropic-skill","format":"markdown","content":"---\nname: eval-dataset-design\ndescription: 设计 Agent 评估数据集或单条评估任务时使用——解剖评估任务的四个组成部分、设计验证器与验收标准（含防敷衍性修复）、划分任务难度与陷阱任务、防范训练/评估数据泄漏（参数化实例、canary）、建设评估集的质量控制与长期维护、选择公开基准/自建业务集/生产轨迹回流三个来源。覆盖 τ²-bench、SWE-bench、AndroidWorld、OSWorld、Terminal-Bench、GAIA 的可迁移设计手法。\n---\n\n# 评估数据集设计\n\n## 何时使用\n- 从零设计评估集，或评审现有任务定义是否站得住\n- 为 Agent 编写单条评估任务：工单、用户模拟规范、初始状态、验收标准\n- 设计验证器：该断言终态、断言动作，还是检查必须告知用户的信息\n- 评估任务被模型\"猜答案\"蒙过，需要提高信噪比\n- 怀疑评估集已被污染/泄漏进训练数据，需要防泄漏与检测手段\n- 决定自建评估集的任务从哪来：公开基准、业务集、还是生产失败回流\n- 评估集上线后需要长期维护：修补环境、描述、验证逻辑与初始状态问题\n\n## 核心原则\n- **一条评估任务 = 四个部分**：给 Agent 的工单、给模拟器的行为规范、两侧状态的初始重置、成功判定标准。缺任何一部分，任务都无法重复运行。\n- **把用户的认知边界建模为独立字段，而非靠提示词约束。** 用户不知晓的信息 Agent 无从推测，只能通过提问与引导获得——渐进式信息透露不是一句\"不要一次说完\"，而是 `known_info` 与 `task_instructions` 的拆分。\n- **没有事实锚定的用户模拟器会让评估退化为两个模型相互确认。** 模拟用户关于环境状态的任何回答都必须以工具返回为依据，不许编造工具结果；否则 Agent 稍加引导，用户就确认\"问题已解决\"。\n- **验证器必须核实机器可独立复核的事实，不能采信 Agent 的自我陈述。** Agent 很容易写一篇\"任务已全部完成\"的报告而实际什么都没做。\n- **训练集与评估集严格隔离。** 答案不可从互联网直接检索、任务实例参数化生成、嵌入 canary 使泄漏可检测——三招至少用一招。\n- **验收口径要有可核实的边界，防\"敷衍性修复\"。** \"网络已恢复\"不可核实；\"测速评级 excellent 才算解决，poor/fair/good 均不接受\"才堵得住压制症状、不除根因的糊弄。\n- **高质量的评估集是修出来的，不是写出来的。** 主流基准的现行形态都是初版暴露问题后逐轮修补的结果；发布前人工淘汰、发布后持续修两类问题都要预算。\n- **每道题亲手做一遍。** 做完问两个问题：描述是否有多种合理解释，验证器认可哪一种？蒙混过关的最低成本路径是什么，验证器拦得住吗？\n- **难度分层让评估集不过时**，且每层失败指向不同改进方向：基础层失败指向工具使用，中间层指向多步规划，最高层指向长序列思考。\n\n## 实践模式\n\n### 1. 任务解剖：四件套字段清单\n以 τ²-bench telecom 一条真实任务为范本，逐项对照自建任务：\n- **ticket（给 Agent 的工单）**：只含用户会主动说出的部分。真实用户的初始表述往往只是\"我上不了网\"，把需求澄清到可执行的程度本身就是 Agent 必须具备的能力。\n- **user_scenario（给模拟器的行为规范）**：`known_info` 界定用户知悉范围（姓名、号码、所在国），故障原因不在其中；`task_instructions` 规定透露方式，并包含三类约束——情绪设定（首次修复失败后表现不满）、验收口径（仅 excellent 算解决）、事实锚定（设备状态回答必须基于工具结果）。\n- **initial_state（初始重置）**：`initialization_actions` 把两侧状态重置到同一起点，包括用户侧（飞行模式、漫游开关）与 Agent 侧（运营商侧配置）。\n- **evaluation_criteria（成功判定）**：四个可检查维度按需组合，外加聚合规则。\n\n### 2. 四维校验与聚合规则\n- `env_assertions` 验**终态**：移动数据可用、测速达 200 Mbps 且评级 excellent。\n- `actions` 验**关键动作是否发生**（哪些工具被哪一侧调用）。\n- `communicate_info` / `nl_assertions` 验**必要信息是否已告知用户**——别只查环境状态。\n- `reward_basis` 是聚合规则。二元奖励（只看终态）以过程颗粒度换取跨模型可比的单一数字：满分轨迹里违反\"一次只做一个工具调用\"的政策也不会被捕获。生产评估系统需要更多：不仅判对错，还要指出问题出在哪。\n\n### 3. 验证器设计的三种模式\n- **双命题验证**（SWE-bench Verified）：FAIL_TO_PASS（修复前失败、修复后通过，证明问题确已解决）+ PASS_TO_PASS（修复前后均通过，证明未引入新缺陷）。只验前者，Agent 可以删改妨碍通过的断言蒙混；只验后者等于未检验。另需排除自身不稳定的 flaky test。\n- **深状态核查**（OSWorld 式）：134 个独立评估函数，拥有完整系统访问权限，查文件系统结构、进程状态、网络连接与应用内部状态；数据库任务连库核实 SQL 是否真执行，浏览器任务分析 DOM、cookie 与 localStorage 并向后端发验证请求——能抓住\"表面完成、实质错误\"。\n- **不可伪造执行**（Terminal-Bench 式）：成功标准是真实构建并运行（如从源码构建内核并在 QEMU 启动日志出现自定义 printk），Agent 无法伪造输出，只能真做完全流程。\n\n### 4. 难度划分与陷阱任务\n- 分层标注并用于诊断：GAIA 466 题分三级——Level 1 只需一至两个工具（人类 93.9%，早期模型 30.3%），Level 2 多步思考，Level 3 复杂组合。Level 1 失败指向基础工具使用，Level 2 指向多步规划与信息整合，Level 3 指向长序列思考与复杂性管理，改进方向各不相同。\n- **陷阱任务**检验压力与误导下的判断力：用户声称\"客服已批准取消\"，实际并不符合政策，看 Agent 是否维持正确判断。\n- 任务集覆盖从易到难的全谱，模型能力提升时评估集不会快速过时。\n\n### 5. 数据泄漏防范\n- **组合多源 + 专有附件 + 精确匹配**（GAIA 式）：答案必须组合多个信息源才能得出，单一网页无法直接给出；部分任务配互联网上不存在的 PDF/音频/图片附件；用精确字符串匹配判定。\n- **参数化模板实例化**（AndroidWorld 式）：任务是\"将联系人 X 的电话改为 Y\"这类模板，每次评估随机生成参数。三收益：回放固定操作序列失效；单模板可生成近乎无限实例；固定部分参数、只改其余，可精确测量特定因素的影响。\n- **金丝雀标识符**（Terminal-Bench 式）：题面嵌入 canary GUID，模型能输出含该 GUID 的内容即说明基准已进训练集。它不阻止泄漏，但使泄漏可被检测。\n\n### 6. 质量控制与长期维护\n- **发布前人工淘汰**：SWE-bench Verified 从 2294 个原始任务抽 1699 个，93 名精通 Python 的开发者逐条检查（描述是否清晰、测试是否覆盖边界、是否稳定、参考 patch 是否引入新错误、难度是否合理），仅 500 个通过——淘汰 71% 换来更高信噪比，评估成本下降约 80%。复杂 Agent 任务动辄数分钟至数小时，前沿模型跑完一个评估集往往需要数千美元 token，控本就是控迭代速度。\n- **发布后持续修补**：OSWorld 发布 15 个月暴露出 300 余个问题，分四类——环境问题（反爬、CAPTCHA、动态内容，靠锁定版本与离线备份）、任务描述歧义（改写消除）、验证逻辑过严或过松（人工建立正确基线再调条件）、初始状态不完整（增加完整性校验）。修补方式可整体借鉴。\n- **从初版到成熟版的五处典型重设计**（τ-bench → τ²-bench）：任务指令过于笼统导致可猜 → 拆分 known_info/task_instructions；成功条件不精确 → 改为可核实边界；模拟用户过于机械 → 补情绪、耐心上限与事实锚定；只有 Agent 能改变环境 → 引入用户侧工具的双控机制；静态任务 → 参数化批量生成实例（同时改善覆盖率与抗泄漏）。\n\n### 7. 评估集的三个来源与演进\n- **公开基准**：用于粗筛模型与借鉴设计手法（验证深度、参数化生成、防泄漏、质量维护），一般不用于产品决策——其任务分布与业务分布不一致。\n- **自建业务集**：覆盖真实任务分布，作为模型选型与 Harness 设计决策的依据。可拿成熟基准当骨架，替换领域数据与工具集。\n- **生产轨迹回流**：用户明确纠正、点踩、事后规则/LLM 审计发现的失败案例，经失败归因后沉淀为回归用例。成本最高、准确性最高，直接来自用户实际遇到的问题。\n- 演进节奏：起步只有公开基准 + 少量手写业务集；上线运行一段时间后，回流用例成为主体。今天线上暴露的失败模式，明天就是守住底线的回归用例。\n\n## 常见陷阱\n- 任务指令写得宽泛，模型无需澄清需求、凭常识猜一套流程也能通过。\n- 成功条件是\"网络已恢复\"这类无边界描述，被压制症状的敷衍性修复蒙过。\n- 只验 FAIL_TO_PASS 不验 PASS_TO_PASS，Agent 靠删断言作弊；或不排除 flaky test，结果不可复现。\n- 用户模拟器没有事实锚定，评估退化为 Agent 与模拟用户相互确认；没有耐心上限，沟通效率低下不被计失败。\n- 静态题面被模型记忆，且无 canary，泄漏发生了都不知道。\n- 验证器过严（把正确答案判失败）或过松（放走表面完成实质错误）；初始状态配置不完整，每次运行起点不同。\n- `reward_basis` 只看终态，过程违规（策略违背、信息未告知）不被捕获，且不另建过程检查。\n- 任务描述存在多种合理解释而验证器只认一种，开发者与人肉执行者的判断不一致。\n- 评估集建成后不再维护，上线后仍是手写那几十条，与真实用户分布脱节。\n\n## 配套代码\n- `chapter7/tau2-bench-eval/` — τ²-bench telecom 任务定义四部分（ticket / user_scenario / initial_state / evaluation_criteria）的完整解剖与双控环境运行记录\n- `chapter7/public-health-reporting-eval/` — 五个确定性任务的六点结构化评分示范验证器设计：工具选择、参数、答案（含数值容差）、证据行精确集合、无依据声明处罚\n- `chapter7/android-world/` — T3A 失败轨迹与归因笔记，演示参数化任务实例、验证器终态判定，以及从失败轨迹回流生成轨迹前缀回归任务\n\n## 深度阅读\n- `book/chapter7.md`「一条评估任务的解剖：τ²-bench 的 telecom 领域」\n- `book/chapter7.md`「评估数据集的设计」\n","frontmatter":{"name":"eval-dataset-design","description":"设计 Agent 评估数据集或单条评估任务时使用——解剖评估任务的四个组成部分、设计验证器与验收标准（含防敷衍性修复）、划分任务难度与陷阱任务、防范训练/评估数据泄漏（参数化实例、canary）、建设评估集的质量控制与长期维护、选择公开基准/自建业务集/生产轨迹回流三个来源。覆盖 τ²-bench、SWE-bench、AndroidWorld、OSWorld、Terminal-Bench、GAIA 的可迁移设计手法。"},"isInternal":false,"tokens":4056,"sizeBytes":11102},{"name":"SKILL.md","path":"skills/knowledge-org/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/knowledge-org/SKILL.md","title":"knowledge-org","category":"anthropic-skill","format":"markdown","content":"# knowledge-org\n\nPath: `skills/knowledge-org/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/knowledge-org/SKILL.md)","tokens":300,"sizeBytes":176},{"name":"SKILL.md","path":"skills/kv-cache-design/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/kv-cache-design/SKILL.md","title":"kv-cache-design","category":"anthropic-skill","format":"markdown","content":"# kv-cache-design\n\nPath: `skills/kv-cache-design/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/kv-cache-design/SKILL.md)","tokens":300,"sizeBytes":182},{"name":"SKILL.md","path":"skills/loop-engineering/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/loop-engineering/SKILL.md","title":"loop-engineering","category":"anthropic-skill","format":"markdown","content":"# loop-engineering\n\nPath: `skills/loop-engineering/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/loop-engineering/SKILL.md)","tokens":300,"sizeBytes":185},{"name":"SKILL.md","path":"skills/mcp-skill-hub/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/mcp-skill-hub/SKILL.md","title":"mcp-skill-hub","category":"anthropic-skill","format":"markdown","content":"# mcp-skill-hub\n\nPath: `skills/mcp-skill-hub/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/mcp-skill-hub/SKILL.md)","tokens":300,"sizeBytes":176},{"name":"SKILL.md","path":"skills/memory-system/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/memory-system/SKILL.md","title":"memory-system","category":"anthropic-skill","format":"markdown","content":"# memory-system\n\nPath: `skills/memory-system/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/memory-system/SKILL.md)","tokens":300,"sizeBytes":176},{"name":"SKILL.md","path":"skills/multi-agent-design/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/multi-agent-design/SKILL.md","title":"multi-agent-design","category":"anthropic-skill","format":"markdown","content":"# multi-agent-design\n\nPath: `skills/multi-agent-design/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/multi-agent-design/SKILL.md)","tokens":300,"sizeBytes":191},{"name":"SKILL.md","path":"skills/post-training-strategy/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/post-training-strategy/SKILL.md","title":"post-training-strategy","category":"anthropic-skill","format":"markdown","content":"# post-training-strategy\n\nPath: `skills/post-training-strategy/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/post-training-strategy/SKILL.md)","tokens":300,"sizeBytes":203},{"name":"SKILL.md","path":"skills/rag-pipeline/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/rag-pipeline/SKILL.md","title":"rag-pipeline","category":"anthropic-skill","format":"markdown","content":"# rag-pipeline\n\nPath: `skills/rag-pipeline/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/rag-pipeline/SKILL.md)","tokens":300,"sizeBytes":173},{"name":"README.md","path":"skills/README.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/README.md","title":"Skills Skill","category":"anthropic-skill","format":"markdown","content":"# Skills Skill\n\nPath: `skills/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/README.md)","tokens":300,"sizeBytes":149},{"name":"SKILL.md","path":"skills/reward-design/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/reward-design/SKILL.md","title":"reward-design","category":"anthropic-skill","format":"markdown","content":"# reward-design\n\nPath: `skills/reward-design/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/reward-design/SKILL.md)","tokens":300,"sizeBytes":176},{"name":"SKILL.md","path":"skills/tool-design/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/tool-design/SKILL.md","title":"tool-design","category":"anthropic-skill","format":"markdown","content":"# tool-design\n\nPath: `skills/tool-design/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/tool-design/SKILL.md)","tokens":300,"sizeBytes":170},{"name":"SKILL.md","path":"skills/tool-discovery/SKILL.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/tool-discovery/SKILL.md","title":"tool-discovery","category":"anthropic-skill","format":"markdown","content":"# tool-discovery\n\nPath: `skills/tool-discovery/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/tool-discovery/SKILL.md)","tokens":300,"sizeBytes":179},{"name":"README.md","path":"chapter4/collaboration-tools/README.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter4/collaboration-tools/README.md","title":"collaboration-tools Documentation","category":"plugin-manifest","format":"markdown","content":"# collaboration-tools Documentation\n\nPath: `chapter4/collaboration-tools/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter4/collaboration-tools/README.md)","tokens":300,"sizeBytes":214},{"name":"README.md","path":"chapter4/execution-tools/README.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter4/execution-tools/README.md","title":"execution-tools Documentation","category":"plugin-manifest","format":"markdown","content":"# execution-tools Documentation\n\nPath: `chapter4/execution-tools/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter4/execution-tools/README.md)","tokens":300,"sizeBytes":202},{"name":"README.md","path":"chapter4/perception-tools/README.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter4/perception-tools/README.md","title":"perception-tools Documentation","category":"plugin-manifest","format":"markdown","content":"# perception-tools Documentation\n\nPath: `chapter4/perception-tools/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter4/perception-tools/README.md)","tokens":300,"sizeBytes":205},{"name":"README.md","path":"chapter9/self-evolving-tools/README.md","rawUrl":"https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter9/self-evolving-tools/README.md","title":"self-evolving-tools Documentation","category":"plugin-manifest","format":"markdown","content":"# self-evolving-tools Documentation\n\nPath: `chapter9/self-evolving-tools/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter9/self-evolving-tools/README.md)","tokens":300,"sizeBytes":214}],"systemPromptSnippet":"<yakaai_skills repo=\"bojieli/ai-agent-book\">\n<!-- File: chapter10/multi-role-transfer/skills/coding/SKILL.md (Tokens: ~300 | Category: anthropic-skill) -->\n# coding\n\nPath: `chapter10/multi-role-transfer/skills/coding/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter10/multi-role-transfer/skills/coding/SKILL.md)\n\n<!-- File: chapter10/multi-role-transfer/skills/data_analysis/SKILL.md (Tokens: ~300 | Category: anthropic-skill) -->\n# data_analysis\n\nPath: `chapter10/multi-role-transfer/skills/data_analysis/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter10/multi-role-transfer/skills/data_analysis/SKILL.md)\n\n<!-- File: chapter10/multi-role-transfer/skills/research/SKILL.md (Tokens: ~300 | Category: anthropic-skill) -->\n# research\n\nPath: `chapter10/multi-role-transfer/skills/research/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter10/multi-role-transfer/skills/research/SKILL.md)\n\n<!-- File: chapter10/multi-role-transfer/skills/triage/SKILL.md (Tokens: ~300 | Category: anthropic-skill) -->\n# triage\n\nPath: `chapter10/multi-role-transfer/skills/triage/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter10/multi-role-transfer/skills/triage/SKILL.md)\n\n<!-- File: chapter10/multi-role-transfer/skills/writing/SKILL.md (Tokens: ~300 | Category: anthropic-skill) -->\n# writing\n\nPath: `chapter10/multi-role-transfer/skills/writing/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter10/multi-role-transfer/skills/writing/SKILL.md)\n\n<!-- File: chapter2/agent-skills-ppt/skills/pptx/reference.md (Tokens: ~300 | Category: anthropic-skill) -->\n# Pptx Skill\n\nPath: `chapter2/agent-skills-ppt/skills/pptx/reference.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter2/agent-skills-ppt/skills/pptx/reference.md)\n\n<!-- File: chapter2/agent-skills-ppt/skills/pptx/SKILL.md (Tokens: ~300 | Category: anthropic-skill) -->\n# pptx\n\nPath: `chapter2/agent-skills-ppt/skills/pptx/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter2/agent-skills-ppt/skills/pptx/SKILL.md)\n\n<!-- File: chapter8/curly-quote-sft/SKILL.md (Tokens: ~795 | Category: anthropic-skill) -->\n# 中文技术文档符号与引用规范\n\n## 何时加载\n\n- 编辑或生成同时包含中文、英文、Markdown 和代码的技术文档。\n- 用户反馈引号、反引号或代码边界格式错误时。\n\n## 符号定义\n\n- ASCII 直引号：`\"`、`'`；常用于英文标点和代码字符串。\n- 中文弯引号：`“”`、`‘’`；用于中文自然语言引用。\n- Markdown 反引号：`` ` ``；用于行内代码和字面量。\n\n## 决策优先级\n\n1. 先保护可执行代码、JSON/schema、URL、路径和用户要求原样保留的引用文本。\n2. 识别 Markdown 代码围栏、行内代码和代码注释边界。\n3. 在中文自然语言作用域中，把成对的直引号改为弯引号，并正确处理嵌套引用。\n4. 英文原文保持原文标点；英文标识符是否使用反引号由其是否为代码字面量决定，而不是由语言决定。\n5. 无法判断作用域时保留原文并请求澄清，不做全局替换。\n\n## 正反例约束\n\n- 正例：`# 中文注释：显示 \"状态\"` → `# 中文注释：显示 “状态”`；同一代码块中的 `name = \"status\"`、`const name = \"status\"`、SQL 标识符和 JSON 键值保持 ASCII 语法。\n- 反例：不能把代码字符串、JSON、URL、路径、英文原句或 Markdown 行内代码中的 `\"`/`'` 改成弯引号；不能因为文件是中文就全局替换。\n- 每种编程语言至少提供“该改的中文注释”和“该留的可执行字面量”成对样本，并在留出/边界集更换体裁、变量名和代码结构。\n\n## 数据质量门禁\n\n- 合成数据先按文章体裁、作用域类型和编程语言分层，再切分 train/eval/boundary，禁止 ID 和模板组合重叠。\n- 机器门禁检查未解析变量、代码围栏、非注释代码行漂移和保护区；人工抽查每个分层的首条样本，记录在 `validation/manual_audit.md`。\n- 任何语言类别的保护区或语法门禁失败，都应回到 Skill/数据蓝图修订后重训，不能只增加 epoch 或汇报总体平均分。\n\n## 验证\n\n- 修改必须是最小编辑，正文事实和代码内容不变。\n- Markdown、JSON 和代码语法检查必须通过。\n- 英文原文、代码和保护区域做字节级回归。\n- 记录来源 Bad Case、适用范围、例外和验证结果。\n\n<!-- File: chapter9/ai-style-skill/skill/SKILL.md (Tokens: ~300 | Category: anthropic-skill) -->\n# skill\n\nPath: `chapter9/ai-style-skill/skill/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/chapter9/ai-style-skill/skill/SKILL.md)\n\n<!-- File: skills/agent-evaluation/SKILL.md (Tokens: ~6318 | Category: anthropic-skill) -->\n---\nname: agent-evaluation\ndescription: 为 Agent 建立或改进评估体系时使用——设计评估指标（Pass@k/Pass^k/成本）、搭建可重复运行的评估环境、选择确定性验证器或 LLM-as-a-Judge 及各自适用边界、编写 Rubric、做失败归因与回归任务、评估驱动的模型选型、判断统计显著性、建设可观测性与内部评估基础设施（消融、AB 测试、特性开关、提示词回归）、从 Benchmark 报告走到系统改进。\n---\n\n# Agent 评估体系\n\n## 何时使用\n- 为 Agent 系统建立第一套评估，或审查现有评估是否可信\n- 选模型、换模型前需要数据依据（新模型公开分高，不代表在你的任务上更好，甚至可能回退）\n- 评估分数下降，要判断是 Agent 退化还是评测系统本身出了问题\n- 需要把\"成功率下降\"这类笼统结论拆成可着手修复的具体问题\n- 为生产 Agent 建设内部评估基础设施：消融实验、AB 测试、特性开关、提示词回归\n- 设计可观测性与生产轨迹回流，让评估集随产品持续演化\n\n## 核心原则\n- **评估的对象是\"模型 + Harness\"组合体，不是模型本身。** 同一模型在不同 Harness 下表现悬殊；表现不佳时先怀疑 Harness，再怀疑模型。\n- **用模型替换实验（model swap）区分两类问题**：固定 Harness 只换模型，分数不涨 → 瓶颈在 Harness；分数随模型能力大幅波动 → 瓶颈在模型能力。消融实验则是关闭 Harness 组件、定位内部哪个部件重要，两者互补，别混用。\n- **先检查评测系统，再动 Agent。** 分数下降先排查：运行环境资源不足导致的随机失败、验证器 bug 把对的判错、用例与生产脱节——这些在数字上与模型退化一模一样，只有回放完整轨迹能区分。\n- **指标口径由业务场景决定。** 同一个 0.8，对退款客服意味着每五名用户一人拿不到退款，对漏洞挖掘已属可观。报告必须写清 k 的口径：同一任务的 k 次独立采样，还是生产流水线连续 k 个任务。\n- **凡是能写成程序化断言的检查就用断言**，LLM 评判只用于确实无法机械判定的维度。确定性验证更便宜、更可复现，适合长期进 CI。\n- **分差要超过噪声、在配对分析中成立、并且能够复现，才值得据此切换模型或发布改动。**\n- **一轮证据只支持与它规模相称的下一步。** 子集 4/4 不能写成系统整体 100%，完整复测通过前不部署。\n\n## 实践模式\n\n### 1. 指标设计：Pass@k / Best@k / Pass^k\n- **Pass@k**（k 次至少一次通过）与 **Best@k**（连续得分取最好）衡量能力上限，适合科研发现、漏洞挖掘、开放式创作——人类会从 k 条候选轨迹里挑出最好的那条。\n- **Pass^k**（连续 k 次全部通过，且不触发安全、合规、幻觉等一票否决项）衡量业务可靠性，适合支付、退款、权限变更、生产部署。两者关系：Pass@k = 1-(1-p)^k，Pass^k = p^k。\n- p=0.6、k=5 时：Pass@5 ≈ 99%，Pass^5 ≈ 7.8%——前一个数字回答\"能不能偶尔创造奇迹\"，后一个才回答\"能否稳定交付\"。\n- 会产生副作用的操作不能\"重试直到成功\"：应在沙盒或可回滚环境中采样，每一次失败都记入可靠性指标。\n\n### 2. 评估环境五要素\n- **数据集**：初始状态、给 Agent 的输入、给模拟器的行为规范与验收标准，打包为一条记录即一个用例。\n- **环境状态**：必须可重置（`initialization_actions` 即重置脚本）；真实性（变化符合业务逻辑）与可控性（每次回到同一起点）兼得。\n- **工具接口**：两侧工具均为原子操作；抽象层次过高（如一个\"解决用户问题\"工具）会使评估退化为对单次函数调用的考察，规划与推理被工具本身吸收。\n- **评分标准**：分层检查项 + 明确的聚合规则（如 `reward_basis`）。\n- **执行协议**：终止信号、轮数上限、模拟用户耐心耗尽主动结束（沟通效率过低本身即计为失败）。\n- 按任务形态选环境类型：单轮问答用无状态单轮环境；搜索+综合用多轮工具环境；改数据库验状态用有状态环境；跑代码查输出用沙盒环境。并行采样与轨迹缓存是标配；工具失败应返回清晰错误信息而非单一失败标志，让 Agent 能据此调整策略。\n\n### 3. 验证方式谱系与自动化评估\n- 横轴是**可机械验证程度**：确定性断言 → 检查项清单 → Rubric + LLM-as-a-Judge → 配对比较。向右移动不意味着放弃左侧。\n- 确定性验证只能判对错、不给原因；生产系统最需要的恰恰是\"错在哪、下一步改什么\"。开放式任务（报告、投诉、创意）无唯一终态、人工评估不可规模化，才上 LLM 评判。\n- **Rubric 四准则**：基于专家指导（捕捉核心事实与推理步骤，而非语言流畅度）；全面覆盖（事实、逻辑、完整性、安全性，且明确 Pitfall）；按重要性加权（必要/重要/可选/陷阱，支持一票否决，如幻觉出现总分归零）；评价标准自包含（禁\"展示深刻理解\"，改为\"引用了至少两个权威理论并准确解释\"）。\n- 每个维度给客观可验证的评分档次、具体示例与边界案例；显式防范奖励作弊（幻觉、讨好用户、关键词堆砌、回避棘手问题）。\n- **长度偏差**防范：Rubric 显式惩罚冗长、规定同类任务长度上限；配对比较前把候选长度控制到相近；定期审计评分与长度的相关性——高分几乎总伴随长回答即已被带偏。\n- **同源模型问题**：Agent 与评判模型同家族时，Agent 会学会利用评判模型的偏好与盲点（古德哈特定律：度量成为优化目标后就不再是好度量）。换不同家族模型评判，并让 Rubric 随分歧持续迭代。\n\n### 4. 失败归因：把 0 分变成可修复的问题\n- 归因对象是轨迹中**首个**导致任务偏离的错误；后续错误多是连锁反应，不能把最后一条报错当根因。\n- 问题案例三来源：用户明确纠正、用户点踩/负面反馈、事后状态检查/规则验证器/LLM 评审发现 Agent 做了不该做的事。\n- **静默失败**（无任何工具报错、Agent 自行宣布完成）的两把定位工具：事实锚点比对（把 Agent 陈述与工具返回值逐步对齐，取首次背离）；轨迹前缀二分（截到第 k 步交人接手，能救回说明错误在 k 之后）。不能用搜报错关键字代替。\n- 归因记录结构化（JSON/YAML）：含任务名、首错步号、错误类别、责任方、原文证据、置信度，区分主因与后果（三次重试是后果，不是三个根因）；多类别并存时按\"最早且能解释后续失败\"选主因。\n- **规则先筛、LLM 再定位**比全量喂 LLM 更便宜也更准：完成声明与实际执行命令的交叉核对、diff 是否触及测试断言与 skip 标记、diff 是否改公开 API/schema 而无迁移，这三类可先用规则筛出嫌疑轨迹。\n- 警惕\"做对了但说错了\"：工具调用和环境状态全对，告知用户的信息却错。只检查终态的评估会整体掩盖它（τ²-bench 基线中约三分之一失败属此类）。根因归属要判到层：观察通道缺失不是\"模型不会 OCR\"。\n- 保存归因记录时，连同任务目标、环境状态、Agent 版本、工具集版本和完整轨迹一起存，供回归测试使用。\n\n### 5. 两层回归任务\n- **端到端回归**：从初始状态跑到终态，验最终状态、必要输出、安全条件。最接近生产结果，但难以定位失败步骤。\n- **轨迹前缀回归**：冻结首错之前的上下文、对话、工具返回与环境状态，只要求下一步或下几步可观察动作。成本低、能隔离单个策略问题；对高可靠生产 Agent，其重要性往往超过端到端口径。\n- 前缀回归答案定义为**可接受动作集合**（\"先读仓库规则\"\"先询问用户\"\"拒绝危险操作\"）+ 禁止动作，而不是唯一标准答案。\n- 按错误类别生成回归任务：流程缺失 → 带计划文档与测试验收条件的端到端任务；工具调用错误 → 截断出错前缀编辑成边界任务；信息反馈类 → 对答复内容本身设断言，而非只查环境状态。\n\n### 6. 评估驱动的模型选型\n- 延迟分两阶段：Prefill 决定首字延迟（TTFT = 排队 + 预填充），Decode 决定出字速度与思考时长（50 tokens/s 生成 2000 思考 token 要 40 秒）。看 p95 尾部延迟而非均值。\n- 在自己工作负载上实测各模型的思考 token 用量与对应收益，不凭公开榜单推断。\n- 成本算**每个任务的平均成本**与成本-性能比：便宜但成功率低的模型因频繁重试可能更贵；输入/输出/缓存 token 分开计价。\n- 指标按场景取：日常 Pass@1，关键操作 Pass^k，探索性任务 Pass@k / Best@k。\n- **预算—能力曲线**：除成功率，报告性能随墙钟时间、token、工具调用次数或算力预算变化的曲线；短预算领先不能外推长时运行能力（RE-Bench：2 小时预算最佳 Agent 约为人类专家 4 倍，8 小时人类反超）。\n- **行为策略也是选型维度**：同一中性 Harness 下测\"行动阈值\"（首次修改前的工具调用数与阅读文件数）。换模型行为改变、同模型跨 Harness 保持倾向 → 支持模型效应，反之支持 Harness 效应；工具步数、并行调用、模型延迟必须分开看。工具步数不是质量分。\n- 异构模型组合（轻量模型管简单、强模型管复杂）必须用评估验证整体效益超过所增复杂度，并检查特定场景是否回退。\n- 成本优化（KV Cache 稳定前缀、上下文压缩、分层选模型）每项独立开关，且**合用时在完整任务中一起实测**——各自节省比例不能相加（28.3% 与 17.5% 合用只有 30%）。\n- 建实时成本监控：按任务类型/模型/用户维度追踪 token 与费用，设单任务成本上限，Agent 陷入循环时自动终止。\n\n### 7. 统计显著性\n- 标准误 SE(p) ≈ √(p(1-p)/n)：100 个用例、成功率 70% 时 95% 置信区间约 ±9 个百分点，\"新模型 73% 对旧模型 70%\"不足以支持切换。\n- 同一批任务比较两个配置用**配对分析**：逐题记录谁胜出，McNemar 检验或配对 bootstrap，不要相减两个独立成功率。\n- 每个配置跑 3–5 个随机种子，报告均值与波动范围；单次运行只能用来筛选方向。\n- 预期收益只有 2–3 个百分点而评估集只有几十题：先扩大样本，标准误按 1/√n 缩小。\n- 并行验证多个假设时考虑**多重比较**：收紧显著性阈值，或对正向结果做独立复跑。\n\n### 8. 可观测性\n- 数据基础是 **trace/span 树**：一次任务执行一条 trace，每个 LLM 调用、工具调用、检索是一个 span（记录输入输出、起止时间、token 消耗、错误），父子关系构成执行树。\n- 采用标准协议（OpenTelemetry + OpenInference 等语义约定）保持采集与分析解耦，避免被单一平台锁定；采集异步批量进行，不拖累响应延迟。\n- 追踪的四大价值：问题诊断（回放而非猜测）、持续优化（定位低成功率工具与空结果检索）、成本管理（识别异常高成本案例）、后训练数据基础。\n- 最有价值的去向是**回流**：生产轨迹筛失败与可疑案例 → 脱敏（去隐私、密钥）→ 沉淀为评估集新用例与回归测试。评估集是随产品演化的活资产，不是一次性静态集合。\n\n### 9. 内部评估基础设施（生产级）\n- **消融**：每个主要特性可独立关闭，定期（如每次大版本发布前）跑消融，发现\"特性债务\"——曾经有效但随模型进化已不再必要的特性。消融开关要在启动路径极早期注入，事后加装不了。\n- **AB 测试**：多臂而非二元（揭示剂量-效应关系，找到最优点）；**区分机制指标与目标指标**（缩短计划文件长度是机制，降低会话级成本才是目标，别把机制当目标，计划过短可能引发更多编辑-检查循环反而更贵）；设护栏指标（满意度、操作次数、错误率不能变差）；记录基线统计（样本量、百分位数、相关性），否则无法判断显著性。\n- **双层特性开关**：编译时开关（代码物理移除，本身即干净的消融机制）+ 运行时开关（服务端下发、本地缓存、宁可稍旧也不能阻塞启动；每个特性曝光事件每会话最多记一次）。特性开关是一等架构组件，服务实验、渐进发布与紧急熔断。\n- **提示词敏感性**：系统提示要能确定性渲染（相同配置输入永远产出相同文本）；建立版本化快照；每次提示词变更在评估集上跑回归，像代码过 CI 一样。\n- **隐私感知分析**：分析接口只接受特殊类型包装的值，类型名即审计线索；隐私约束从第一天设计进去。分析系统无法安全收集数据，评估就无从谈起。\n\n### 10. 从 Benchmark 报告到系统改进的闭环节奏\n- 读报告先找失败集中在哪些任务与能力上，再回放轨迹分清问题出在**看、想、做、验**哪一环；别只盯总分（88% 总分很容易埋掉一个集中的失败簇）。\n- 每轮只改一个变量，形成假设链：加提示词无效 → 换输入通道有效但太贵 → 精简输入保住成功率且降成本。提示写得再详细也补不回 Agent 没看到的信息；输入也不是越多越好。\n- 小范围通过只获得扩大测试的资格：标准环境、全任务 × 多种子，同时查成功率不降、token 不超阈值、延迟不超上限，才能讨论部署。\n\n## 常见陷阱\n- 看到分数下降就改 Agent 代码，不先排查评测系统（资源不足、验证器 bug、用例脱节都会伪装成模型退化）。\n- 用公开基准分数直接做产品决策——GAIA 上提升两个百分点与退款成功率没有必然关系。\n- 把最后一条报错当根因；或把根因归错层（观察通道缺失被记成\"模型不会 OCR\"，于是去换模型、做 OCR 训练）。\n- 只检查环境终态，漏掉\"做对了但说错了\"。\n- Rubric 写\"展示深刻理解\"这类不可验证的抽象标准；没有一票否决项，被关键词堆砌式奖励作弊刷分。\n- 评分从未审计长度相关性，评判已被长度偏差带偏而不自知。\n- 同源模型既当运动员又当裁判，Goodhart 之后评分虚高。\n- 把多项上下文优化的节省比例直接相加；或凭单次运行的结果做选型决策。\n- 配对比较不交换候选顺序，位置偏差让先出现者系统性占优。\n- 子集小样本通过后直接当整体水平汇报，结论超出证据规模。\n\n## 配套代码\n- `chapter7/tau2-bench-eval/` — τ²-bench telecom 五任务双控环境评估：环境 reset、轨迹保存、二元奖励与失败任务（错选线路漏做充值）分析\n- `chapter7/android-world/` — T3A 运行记录、失败归因笔记，以及 diagnose→hypothesize→experiment→decide→iterate 的五阶段改进闭环\n- `chapter7/public-health-reporting-eval/` — 合成数据上的确定性六点评分：工具选择、参数、答案、证据行、无依据声明处罚\n- `chapter7/agent-cost-analysis/` — 八轮退款任务全链路成本拆解，KV-cache 友好与上下文压缩的 2×2 A/B 量化\n- `chapter7/model-benchmark/` — 多维度模型基准 campaign：吞吐/TTFT/尾延迟、168 小时可用性、限流爬坡、同模型不同供应商对照\n- `chapter7/model-action-threshold/` — 固定 Coding Harness 下测量不同模型的行动阈值（首次修改前的工具调用与文件阅读）\n- `chapter7/elo-leaderboard/` — 从 Chatbot Arena 真实投票实现 Elo/Bradley-Terry 配对排名与历史快照\n\n## 深度阅读\n- `book/chapter7.md`「评估指标：成功的定义」\n- `book/chapter7.md`「评估环境」\n- `book/chapter7.md`「自动化评估方法」\n- `book/chapter7.md`「评估驱动的模型选型」\n- `book/chapter7.md`「评估结果的统计显著性」\n- `book/chapter7.md`「Agent 的可观测性」\n- `book/chapter7.md`「从 Benchmark 报告到系统改进」\n- `book/chapter7.md`「从外部评估到内部评估：生产级 Agent 的评估基础设施」\n\n<!-- File: skills/agent-evolution/SKILL.md (Tokens: ~5049 | Category: anthropic-skill) -->\n---\nname: agent-evolution\ndescription: 让 Agent 从运行经验中持续学习、构建自进化闭环时使用——涵盖从运行轨迹提取学习信号（三层轨迹验证）、四种进化方式（经验知识库、Prompt/Skill、程序/Harness、模型参数）的适用边界与选择依据、Prompt 自动优化、轨迹编译为程序、Agent 自我修改与安全门禁、睡眠学习与长期分层评估。触发词：持续进化、自进化、经验学习、轨迹验证器、自我修改、进化闭环。\n---\n\n# Agent 持续进化\n\n## 何时使用\n\n- 部署后的 Agent 反复犯同类错误，需要把运行经验转化为持久能力\n- 需要为运行轨迹构建验证器 / 评价器，判断\"哪里错、为什么错、证据在哪里\"\n- 面对一个待修复缺陷，需要决定经验应写进知识库、Prompt/Skill、程序还是模型参数\n- 要做 Prompt 自动优化、失败轨迹规则提炼、浏览器轨迹转工作流等单点进化\n- 设计 Agent 自我修改流程（改自身 Harness、工具、重试策略），需要验证与发布门槛\n- 搭建\"在线执行 + 离线进化\"双循环，或设计记忆/Skill 的整理、淘汰与回滚机制\n- 评估系统是否真的在进化（而非只保存或只追加反馈）\n\n## 核心原则\n\n- **保存经历 ≠ 从经历中学习**。学习发生在系统主动完成\"评价、对照、归纳、验证\"之后，而非日志写入磁盘的那一刻。一百条轨迹放进向量库只是可检索案例，不自动完成跨案例比较。\n- **先评价再更新**。不知道任务是否完成、哪一步导致成败，模型的反思只是猜测。评价一条轨迹依次回答三问：事情是否办成（结果）、是否以允许的方式办成（过程）、是否让用户舒服（质量）。\n- **三层验证，底层优先**。结果验证器读环境真值（测试、数据库、工具返回），最应优先建立且比模型自述可靠；过程验证器用政策库/权限表/动作序列做代码判定；质量层才用 LLM Rubric。结果正确不代表过程正确（删掉失败用例也能让测试通过）。\n- **学习信号必须四要素齐备**：成败判定（成功/部分成功/失败）、每维度结论、每条结论的证据位置（哪轮对话、哪次工具调用）、失败类型标签。单一总分无法指导更新；证据不足时验证器应拒绝评分，低置信度案例排除在学习集外。\n- **按能力的表示性质选择载体**（表 9-2 的边界）：\n  - 经验知识库——事实、经验规律、例外与来源；更新快、可追溯，但依赖检索和模型正确应用\n  - Prompt/Skill——能用自然语言说清的判断原则、语境与例外；可解释、范围可控，但易膨胀、冲突、被忽略\n  - 程序/Harness——可确定性解析、可执行验证、高风险硬约束；可测试、稳定、低成本，但开发维护成本高\n  - 模型参数——高维感知、生成风格、隐式策略；泛化强、推理开销低，但更新与回归成本高\n- **同一能力可拆到多个载体**：事实入知识库，解释例外的原则入 Skill，不可绕过的权限由程序门控，高维识别能力入参数。路由结果只是更新提案，尚无发布资格。\n- **经验知识库 vs 领域知识**：第三章领域知识回答\"用户与世界是什么样的\"（如\"该航司特殊餐食需提前 24 小时预订\"）；本章经验知识库从行动轨迹与结果中提取\"在什么条件下应该怎样做\"（如\"订票前先检查特殊餐食截止时间\"）。二者共享存储与检索技术，来源和验证目标不同。\n- **所有修改是最小 diff + 可回滚 + 独立验证**。待验证版本必须同时在触发失败的边界集上改善、在正常工作的保留集上不退化；验证者须独立于提炼者。\n- **在线执行与离线进化分离**。在线循环只完成任务并追加不可变证据，不直接改写正式 Agent；离线循环聚合轨迹、生成提案、过门槛发布，两者经版本化经验库和评估集连接。一次偶发成功或恶意输入不能立即改写长期能力。\n- **安全边界三条**：证据与指令隔离（网页/工具输出及其 LLM 摘要都是不可信证据，LLM 摘要不是净化过程）；待验证能力与正式能力隔离（新产物先入不可服务真实流量的待验证区，过沙盒、权限、供应链扫描与回归后才转正）；安全机制不可自我修改（Agent 不能改验证器、测试、发布门槛、审计日志和稳定版本备份——否则降低阈值即可把退化伪装成进步）。\n- **Harness 更新能力 ≠ Harness 受益能力**。前者是从轨迹产出有价值修改，后者是任务 Agent 在正确场景激活并遵循该修改。不能用端到端分数反推更新器好坏，需分层评估。\n\n## 实践模式\n\n### 1. 轨迹验证器（学习信号的来源）\n\n- 三层结构：结果层读最终环境状态；过程层查业务规则、隐私、事实依据、承诺—行动一致性（声称完成的操作是否真实发生）；质量层按 Rubric 逐项给分并引用轨迹证据。\n- 输出结构化诊断而非总分：每维度结论 + 证据轮次 + 置信度，失败带类型标签。\n- 低置信度案例不进学习集；把它当事实固化比丢弃更危险。\n\n### 2. 经验知识提炼管道（五步）\n\n1. 保存不可变原始轨迹与环境结果（用于审计）；\n2. 为单次运行生成结构化分析：任务类型、所需能力、观察到的策略、错误与例外；\n3. 按任务族聚合同类运行，为每条经验草案建\"哪些轨迹支持、哪些轨迹反驳\"的证据表；\n4. 达到支持门槛才写入正式文档；\n5. 在未参与提炼的新任务上测迁移效果。\n\n正式经验文档写：适用场景、推荐策略、禁止做法、例外条件、证据来源、最近验证时间——不复述某次任务的完整过程。真正有迁移价值的内容来自对照（成功轨迹做了什么、失败轨迹缺少什么、策略在哪些版本/前置条件下失效），Reflexion 式自然语言反思可参与生成草案，但反思本身不是证据。\n\n### 3. 经验写成 Prompt/Skill（指令更新）\n\n- 触发条件：多条相似轨迹反复暴露同一种策略错误，且错误能用语言清楚描述。\n- 形式：带来源的最小 diff（`old_str → new_str`），不让模型每轮重写整份 Prompt——重写会丢细节、把相互制约的条件合并成过度抽象的原则。可参考 ACE：上下文维护成带稳定标识符的条目集合，增量更新 + 确定性合并去重。\n- 发布门槛：补丁非空、来源可追溯、保留集不退化、边界集确有改善；通过才灰度（`release_to_canary`），否则拒绝。待验证补丁写入 working 文件，不覆盖正式 Prompt。\n- Skill 与 Harness 边界：Skill 负责理解语境、提问、整理 Spec；Harness 负责缺少确认时否决高风险写入。否决器不替模型决定方案。\n- 提炼输入决定归纳质量：给失败摘要+报错文本，模型只归纳出教训；补充 Agent/用户各自的工具清单，才能归纳出职责归属。\n\n### 4. 经验写成程序（程序化经验）\n\n- 浏览器工作流六步生命周期：捕获轨迹（保存动作参数、URL、元素定位证据——定位信息只能用于再找元素，不能证明任务完成）→ 参数化（字面量换模板变量）→ 定义状态检查（动作前/后检查 + 最终状态检查，最终检查必须读真实页面或后端状态）→ 独立回放验证（沙盒/测试站点重置到独立初始状态后完整回放，全部谓词通过才发布）→ 匹配与回放（能力库按意图检索，直接执行，无需逐步调 LLM）→ 失效与重学（谓词失败、Schema 变化即回退完整 Agent 模式）。\n- 自我修改走软件发布流程，而非运行中进程覆盖自身：从稳定版本切隔离 worktree → Coding Agent 生成最小补丁 → 静态检查、单测、安全扫描、失败轨迹重放、旧任务回归 → 可灰度新版本。每次修改请求是一份可证伪的变更契约：失败证据、推断根因、归属组件、修改提案、预期修复的行为、可能受损的行为、分别验证两者的用例。\n- 提案生成器的输入不只有失败案例，还必须有成功约束（不能破坏的性质）和此前被拒记录（避免换说法重复提交），共同构成有边界的方案空间。\n\n### 5. 经验写入参数\n\n- 判断依据不是\"任务是否长期稳定\"，而是能力的表示性质：能否被外部符号较完整表达。域偏移用 LoRA/持续微调，快速变化的风格用周期性偏好训练。\n- 数据来源：经评价的生产轨迹——高质量示范进 SFT，明确偏好形成成对数据，有可靠环境奖励的交互用于 RL。\n\n### 6. 双循环与睡眠学习\n\n- 离线整合五步：触发（时间/轨迹量/容量/错误频率门槛，且无高优先级在线任务）→ 定向（读正式知识、Skill 目录及版本，了解不可修改边界）→ 采集与整合（合并重复、标记冲突与适用条件，优先生成局部补丁）→ 验证与审批（迁移集/保留集/安全集，高风险等人工批准）→ 修剪与索引（长期不用或被推翻的标记过期、归档，保留来源与回滚版本）。\n- 定期对抗上下文腐化：合并重复经验、把局部规则从全局 Prompt 移入领域 Skill、重验长期未用的工具、删除被推翻的知识、从原始基座重训 LoRA。\n\n### 7. 进化效果的分层评估\n\n- 指标（表 9-3）：更新提案有效率（独立验证中的接受率与增益）、产物激活率（是否正确场景加载）、遵循成功率（动作序列与过程验证器）、保留任务集增益（未参与进化任务的成功率/质量/成本）。\n- 长期评价至少五类：回退（新旧经验冲突）、泛化（测试集外场景）、Token 效率、安全性（规则/隐私/拒绝边界是否漂移）、长期工程质量（维护复杂度、向后兼容、调试负担）。\n- 开放式任务（科研、战略）反馈慢且答案不唯一，需改变证据结构：结论与证据分离（每类声明链接可审计来源）、保留负面结果与停止原因、维护搜索多样性（不全押当前最高分）、让人类在更高层介入（定义问题、审查评价标准、决定何时停止）。\n\n## 常见陷阱\n\n- 把用户满意度或单一总分当学习信号：满意度上升可能伴随规则违规率上升，需护栏指标。\n- 把低置信度结论当事实固化，或把 LLM 摘要当无害化后的指令直接纳入 Skill。\n- **模型会把观察到的行为当作应然的行为**：轨迹中最频繁出现的是转人工，模型就可能把\"三次失败即转接\"写成规则——而该环境下转接必然失败，等于把失败写进规范。提炼产物必须经与提炼者独立的验证。\n- 让模型每轮重写整份 Prompt/记忆，导致重要细节在多轮改写中消失。\n- 把\"动作执行过\"当\"任务完成\"：没有最终状态检查的回放，只是把错误更快地重复。\n- 待验证版本直接发布，或发布门槛可被提案自身修改（安全门不能由修改者自证）。\n- 只修当前失败案例，不顾保留集回退、泛化、Token 成本和长期工程质量。\n- 只追加不淘汰：知识无限增长引发检索错误、知识冲突、灾难性遗忘，抵消学习收益。\n- 用端到端分数判断更新器好坏，忽略激活率与遵循失败。\n- 提案被接受 ≠ 下游能力提升：一次提案通过只证明更新流程成立，仍需在相同任务和模型下做开关消融。\n\n## 配套代码\n\n- `chapter9/trajectory-verifier/` — 实验 9-1：三层轨迹验证器，对比单一总分与带证据的多维诊断\n- `chapter9/tau2-escalation-experience/` — 实验 9-2：从 τ²-bench telecom 失败轨迹提炼转人工与工具使用规则，三臂对照\n- `chapter9/prompt-auto-optimization/` — 实验 9-3：航空客服失败轨迹 → 三维诊断 → 最小 Prompt diff → 发布门槛\n- `chapter9/ai-style-skill/` — 补充案例：用户\"AI 味\"before/after 纠正持续提炼为写作 Skill，LLM judge + 金标校准\n- `chapter9/browser-use-rpa/` — 实验 9-5：浏览器轨迹编译为带状态谓词的待验证工作流，独立回放后才入能力库\n- `chapter9/self-modifying-agent/` — 实验 9-6：由失败轨迹触发重试/熔断代码自我修改，Docker 沙箱验证提案\n- `chapter9/harness-safety-gate/` — 实验 9-7：用户反馈触发高风险操作确认门禁，AST 扫描 + 隔离回放\n- `chapter9/hermes-self-evolution/` — 实验 9-8：Hermes 读本书后自主选题、修改自身并接受独立 Reviewer 审查\n- `chapter9/self-evolution-eval/` — 实验 9-9：四阶段纵向评估（学习/迁移/规则变化/保持），区分保存、追加与可淘汰记忆\n- `chapter9/self-evolving-tools/` — Alita 式补充案例：Agent 从零搜索、沙盒测试并封装新工具入库复用\n\n## 深度阅读\n\n- `book/chapter9.md`「从运行轨迹中获得学习信号」— 三层验证结构与学习信号四要素\n- `book/chapter9.md`「Agent 持续进化的四种方法」— 知识、指令、程序、参数的适用边界与各自流程\n- `book/chapter9.md`「构建可长期运行的持续进化闭环」— 双循环、睡眠学习、分层评估与安全边界\n\n<!-- File: skills/agent-state-bar/SKILL.md (Tokens: ~3796 | Category: anthropic-skill) -->\n---\nname: agent-state-bar\ndescription: Agent 陷入无限循环、数不清工具调用次数、遗忘 TODO 或目标偏离、长任务中思考 token 持续膨胀时使用——Agent 状态栏机制、作为 user 消息注入末尾的 KV Cache 理由、每轮替换与持久追加两种实现及成本模型、五种状态栏技术（时间戳、工具计数器、TODO、详细错误、系统状态）与维护铁律。\n---\n\n# Agent 状态栏：通过元信息增强 Agent 轨迹管理\n\n提示工程给的是静态指令，而 Agent 执行中还需要动态感知自身状态与任务进展。**Agent 状态栏**把任务进度、环境变化、工具调用计数等运行时状态整理成结构化摘要，由框架在上下文末尾持续注入。类比手机屏幕顶部始终显示时间、电量、信号——模型每次生成新回复时都能「瞥一眼」，据此做出更准确的决策。\n\n## 何时使用\n\n- Agent 反复执行相同工具调用、陷入无限循环（如超过次数限制仍在拨打）\n- 模型数不清「已经调用了几次」「还剩几项 TODO」，违反显式约束\n- 长任务中每次迭代的思考 token 量随上下文变长而持续增长\n- Agent 过分关注局部子任务，忘记用户原始诉求和核心约束\n- 小模型需要接近前沿模型的任务遵循能力\n- 设计状态消息的注入方式与更新策略\n\n## 核心原则\n\n- **状态栏不是对话主体内容**：它不属于用户消息、模型输出或工具结果，而是框架自动生成的状态摘要，注入在上下文**最末尾**，紧邻模型即将生成的新 token。\n- **理论基础是「上下文学习是检索而非推理」**：模型擅长查找，不擅长在一次前向传播中主动归纳统计。「已经打了几次电话」这类知识以原始记录形式分散在上下文里，模型每次决策都要花额外思考 token 扫描重算，效率极低且错误率高。\n- **本质是把隐式状态提炼为显式知识**：原始轨迹高度冗余，大量 token 中只含少量关键状态信息；状态栏以极低的额外 token 成本，呈现原本需要扫描数千 token 才能获得的信息。\n- **显式操纵注意力分配**：长上下文中早期目标和关键约束容易被后续工具结果淹没；结构化元信息放在末尾，空间上更接近新 token，获得更高注意力权重——一种「强制性的注意力引导」。\n- **实测收益**：提供提前算好的状态栏后，较小开源模型的准确率可以接近前沿大模型；每次迭代的思考 token 量、延迟和花费均降低约一个数量级。不带状态栏时思考量随上下文变长**持续增长**，带上后**基本恒定**。\n- **状态栏是上下文压缩技术之一**：它用代码确定性地维护「关于轨迹的结论」，与 LLM 驱动的压缩互补。\n- **无侵入性**：所有元信息以人类可读形式出现在上下文里，开发者随时可检查；不需要微调，直接在任何语言模型上起效。\n\n## 实践模式\n\n### 1. 注入位置：一条 user 角色的消息，放在最末尾\n\n```text\nmessages: [\n  { role: \"system\",    content: \"You are a customer service assistant...\" }  ← 固定，KV Cache 已缓存\n  { role: \"user\",      content: \"Help me cancel my Xfinity plan\" }\n  { role: \"assistant\", content: null, tool_calls: [...] }   ← 第 1 轮决策\n  { role: \"tool\",      content: \"Call log...\" }\n  { role: \"assistant\", content: null, tool_calls: [...] }   ← 第 2 轮决策\n  { role: \"tool\",      content: \"Call log...\" },\n  { role: \"user\",      content: \"Can you call them again to follow up?\" },\n  { role: \"user\",      content: \"<agent_status>\n      Current State:\n      - phone_call invoked 3 times (Xfinity: 3/3 max)\n      - Current time: 2025-09-14 10:30:45\n      - TODO: [1] Cancel plan (in_progress)\n    </agent_status>\" }                                        ← 框架注入的状态栏\n]\n```\n\n- **为什么是 user 角色而不是改 system**：修改 system 消息会破坏整个前缀的缓存。这里的 user 角色只是 API 协议层面的技术选择，**不等同于「来自终端用户的输入」**——Harness 借用这个消息槽位，挂载框架自动生成的系统状态信息。\n- 用 `<agent_status>` 标签包裹，便于模型识别其特殊性质。\n- 因为是追加而非修改，前面所有已缓存内容都不受影响。\n\n### 2. 状态栏的三类构成\n\n- **任务规划**：TODO 列表把复杂多步骤任务分解为清晰步骤，放在轨迹末尾，不断提醒模型当前进展和后续目标，确保行动与总体规划一致（防止只关注局部子任务）。\n- **事件的侧信道信息（Side-channel）**：为每个事件附加元数据——精确时间、地理位置、距上次 Agent 回复的时间间隔。通常随对应事件一起追加。\n- **环境当前状态的观察摘要**：系统时间、工作目录、异常操作提醒（「该工具已被重复调用 N 次」）、以及从隐式状态到显式观察的转换。随任务推进不断更新。\n\n### 3. 状态更新的两种实现与缓存代价\n\n**实现一：每轮替换**——每次 API 调用前移除上一轮状态消息，在末尾追加最新状态。保证永远只有一份最新状态，但移除旧状态会使其位置之后的所有缓存失效（与「动态时间戳」同一失效机制，区别仅在于状态消息位于末尾，失效范围只覆盖上次注入后新增的消息，通常是一轮，整个前缀仍可复用）。\n\n**实现二：持久追加**——状态消息一旦注入就永久留在轨迹中，每轮只在末尾追加新状态。Claude Code 的 `<system-reminder>` 即此方式，历史状态保留在 transcript 中从不删改。对缓存完全友好（只追加不修改，前缀始终稳定），代价是陈旧状态累积，既占 token 又要求模型自己关注最新一条。\n\n**选择规则**：\n\n- 状态很小、两次更新间产生的消息很多、会话长度受控 → **选实现二**（保留旧状态通常比反复重算长后缀便宜）\n- 状态较大、更新频繁或轨迹很长 → **选实现一**（只使上次注入后的短后缀失效，同时避免陈旧状态持续累积）\n\n**粗略成本模型**：设每条状态 S token，两次更新间新增后缀 R token，预计更新 N 次，缓存输入单价为普通输入的 α 倍：\n\n```\nC_替换 ≈ (N-1) * (1-α) * R\nC_追加 ≈ α * S * N * (N-1) / 2\n→ 当 α*S*N/2 < (1-α)*R 时倾向实现二，否则倾向实现一\n```\n\n该估算未计上下文占用和陈旧状态带来的歧义，实际选择还应结合服务商缓存计费与实测命中率。\n\n### 4. 五种状态栏技术（实验 2-9）\n\n- **时间戳跟踪**：以 `[2025-09-14 10:30:45]` 格式作为前缀添加到用户消息和工具响应中（**不是放在系统提示词里**，否则破坏 KV Cache）。让 Agent 理解时序关系，也为调试和审计提供信息；配合时间模拟可理解「昨天的文件」和「今天的修改」。\n- **工具调用计数器**：维护全局字典记录每个工具被调用次数，响应中标注 `Tool call #3 for 'read_file'`。显式计数触发模型的模式识别：第一次失败后检查路径，第二次失败后列出目录，第三次主动放弃并找替代方案。深层价值是隐式的成本感知。\n- **TODO 列表管理**：提供 `rewrite_todo_list` 和 `update_todo_status` 两个工具，每项含唯一标识符、内容、状态（pending / in_progress / completed / cancelled）和时间戳。借鉴 Manus「通过复述操纵注意力」理念。实验数据：启用 TODO 的 Agent 平均 **15 次**迭代完成任务，禁用时需 **21 次**且经常遗漏子任务。\n- **详细错误信息**：四层内容——错误类型和描述、完整参数的 JSON、调用栈信息、针对性修复建议（如 FileNotFoundError 时建议验证路径、检查工作目录、使用绝对路径）。启用后 Agent 在错误场景找到替代方案的成功率从 **60% 提升到 95%**，从盲目重试转变为有针对性地分析。\n- **系统状态感知**：注入当前时间、工作目录、操作系统类型、Shell 环境和 Python 版本。工作目录跟踪尤其关键——Agent 执行 `cd` 后自动更新；OS 信息让 Agent 做平台相关决策（Linux 用 `apt`、macOS 用 `brew`）。\n\n这些技术单独使用效果有限，**组合起来会产生涌现效应**：时间戳 + 工具计数器让 Agent 理解操作的频率和时间分布；TODO + 系统状态让 Agent 根据环境调整策略；详细错误 + 工具计数器让 Agent 多次失败后不仅改变策略，还理解失败原因。\n\n## 常见陷阱\n\n- **把时间戳写进 system prompt**：直接破坏 KV Cache 前缀，必须作为消息前缀或末尾状态注入。\n- **让 LLM 一次性批量统计状态**：模型几乎无条件地相信状态栏——你写「打了 3 次电话」，它就当真是 3 次，不会自己重算；而 LLM 做数量统计本来就容易出错。**状态栏尽量用代码维护，实在要用 LLM，也要逐条抽取、再由代码汇总。**\n- **忽视状态栏投毒风险**：状态栏信息被模型高度信任，一旦摘要内容来自可被外部污染的数据源（如把外部网页片段直接写进状态栏），这种信任会被反向利用。\n- **状态栏够用就整段删掉原始记录**：状态栏是对原始上下文的**有损投影**，只提前算了「你预想会被问到」的维度。计数、状态跟踪这类任务可以只保留状态栏以节省大量 token；但只要有一个问题涉及状态栏未计算的维度，仅保留状态栏就会导致准确率**断崖式下降**。删除前确认没有未覆盖的查询维度。\n- **状态消息无限累积从不清理**：实现二的代价，陈旧状态既占 token 又制造歧义，会话长度失控时应切换到实现一。\n- **用状态栏替代真正的任务规划**：TODO 列表需要配套工具支持状态流转，只在提示词里写「请跟踪进度」不够。\n\n## 配套代码\n\n- `chapter2/system-hint/` — 实验 2-9（agent-status-bar 框架）：实现时间戳、工具计数器、TODO 列表、详细错误、系统状态五种状态栏技术，可独立开关；`python main.py --mode preview` 无需 API key 即可对比有无状态栏时模型看到的上下文差异；`python run_experiment_2_8.py` 跑冻结的对照实验。\n\n## 深度阅读\n\n- `book/chapter2.md`「Agent 状态栏：通过元信息增强 Agent 轨迹管理」\n\n<!-- File: skills/async-event-agent/SKILL.md (Tokens: ~4033 | Category: anthropic-skill) -->\n---\nname: async-event-agent\ndescription: >-\n  构建异步/事件驱动 Agent，或让 Agent 响应外部事件（新邮件、webhook 回调、IM 消息、定时器、系统告警）、\n  处理工具执行期间的用户打断与多任务并发时使用。覆盖事件循环与安全点、三类事件触发工具、用户沟通与多渠道召回、\n  虚拟身份与隔离执行环境、队列式/取消式/并行式三种事件处理策略及紧急度判定，以及模型原生异步与同步接口兼容两条路线。\n  触发词：异步 Agent、事件驱动、event-driven、webhook、定时器、心跳、任务句柄、打断、steering、并行工具执行。\n---\n\n# 异步与事件驱动 Agent\n\n## 何时使用\n\n- 要让 Agent 在**没有用户输入时也行动**：定时生成报告、周期性检查服务器、跟进未回复的邮件、到工作时间再拨打电话。\n- 要接入**外部事件源**：新邮件到达、API 回调、IM/短信消息、GitHub PR 变更、支付失败告警。\n- 要支持**执行期间被打断**：长任务运行中用户说\"停\"\"改一下预算\"\"先帮我查个天气\"。\n- 要**同时管理多个并发任务**：并行跑几个脚本、先完成的先看结果、未达进度就取消。\n- 要从回合制 ReAct 循环升级为长期运行的**事件循环 Agent**。\n- 要评估某个模型/接口是否支持原生异步，或为不支持的接口设计兼容层。\n- 任务需要在\"发起\"与\"收尾\"之间跨越多个回合（如代打电话、长时审批流）。\n- Agent 需要以\"活人感\"与用户异步沟通（发消息、图片、文件、按紧急度推送提醒），而非必须打开指定会话。\n\n## 核心原则\n\n- **回合制是交互约定，不是环境性质。** 世界不会等模型反应完才变化；任务常在\"发起\"与\"收尾\"之间跨越多个回合。\n- **架构是事件循环，不是轮询。** Agent 是一个长期运行的循环：每轮从输入队列取若干事件 → 追加到轨迹 → 调一次 LLM → 执行它决定的工具 → 回到开头等下一批。不要用\"反复问有没有新消息\"的轮询。\n- **\"主动服务\"的前提是事件能推给 Agent。** Hooks（框架内生命周期事件）、Cron（定时调度）、Heartbeat（每隔 N 分钟唤醒）三种机制里只有后两种让 Agent 自己动起来，且都是**时间驱动**的；对内置渠道之外的第三方事件源（新邮件、外部回调）必须建实时推送通道，否则只能等下一个周期才察觉——这个延迟在验证码等待、三方通话等场景里不可接受。\n- **安全点决定一切。** 同步接口中事件只能在循环边界（一段推理结束、一次工具返回）被消费；紧急事件的取消式处理本质是\"主动提前制造一个安全点\"。取消点必须是工具或推理能安全收尾的位置。\n- **取消 ≠ 撤销。** 发送取消信号只是让执行器停止；已经发生的动作不会回滚。未完成的工具结果用显式占位符表示，不能伪造成功。\n- **三种处理策略按紧急度选择**：\n  - **取消式**（紧急事件：`user.interrupt`、`supervisor.instruction`、`agent.interrupt`、紧急告警）：停当前操作 → 清空队列 → 所有事件连同紧急事件一次性追加到轨迹 → 立即重新调 LLM。\n  - **队列式**（常规事件：`user.input`、`tool.result`、`timer.trigger`）：放入队尾不打断，等本轮到达安全点后**批量**追加，减少往返。\n  - **并行式**（独立、轻量、需快响的查询，如\"今天天气怎么样\"）：在独立推理会话中执行，结果追加进主轨迹并**明确标记为并行**，避免 LLM 混淆。\n  - 硬编码规则有局限；建议用轻量分类 LLM 做事件路由器。\n- **所有输入统一建模为结构化事件**：来源（谁）、渠道（方式）、内容（什么/紧急度）、上下文（与哪个任务相关）。这是防止把工具结果误当用户指令、以及提示注入的前提。异构触发器（webhook、定时器、邮件、数据库变更、文件监听）统一建模后，Agent 才能用一致方式处理不同来源的刺激。\n- **异步语义要写进工具接口**：把\"启动\"和\"完成\"解耦——`initiate_phone_call` 立即返回任务 ID 和初始状态，进展通过 `phone_call_connected` / `phone_call_ended` 等事件通知。工具名和描述本身就要传达异步语义（\"任务发起后立即返回 ID，你可以继续处理其他事项，结束后会收到单独通知\"）。\n- **三条路线按模型能力选择**：原生异步（工具挂起、模型继续、回合中途 steering）> 同步接口兼容（占位符 + 队列 + 重新请求）> 退化回纯串行。用了 `asyncio` 不等于模型具备异步能力，仍需应用层管理事件来源、工具生命周期与结果归属。\n- **可靠处理比能接收更难**：至少要检查——延迟结果能否归入正确任务且缺席时不编造；处理新要求后能否恢复原任务并区分\"修改计划\"与\"停止执行\"；多条更新能否同时遵守而不是只记住最后一条。\n- **事件优先级要动态判断，不是静态排序**：Agent 应像秘书按紧急程度决定先处理哪个、做到一半能否暂停切换，而不是固定先后。长任务异步执行不应阻塞用户交互，被打断的任务要能自然恢复。\n- **占位符只在打断时引入**：常态下 LLM 看到的就是标准同步轨迹；只有出现打断才插入\"工具正在后台执行\"的占位 tool result 修复配对格式，后台真实结果到达后再以带来源和任务 ID 的事件送回。\n\n## 实践模式\n\n1. **搭骨架**：inbox 队列 → 分发器（按紧急度路由）→ 单线程事件循环 → 轨迹存储。参考 `chapter6/async-agent/` 的 `runtime.py::AgentRuntime`（`_dispatcher` 路由紧急度、`_handle_interrupt` 在安全点取消、`run_llm_turn` 推进轨迹）。\n2. **接事件源**：三类事件触发工具——定时器（一次性 + 循环，循环定时器兼容只能主动查询的外部服务）、后台任务监控（监控新增输出或关键词，别让 Agent 反复盯命令行浪费 token）、外部事件通道（实时推送）。每个触发源都要定义过滤规则和足够上下文的 payload，避免无关事件烧算力。\n3. **定义紧急度分类器**：先列事件类型清单和默认策略，再用轻量 LLM 兜住语义边界（\"马上停下来\"→取消式，\"报告用中文发我\"→队列式，\"天气如何\"→并行式）。\n4. **同步兼容层五规则**：assistant 消息与工具调用项立即落轨迹；只有工具真正返回才记 tool result；执行中被打断则生成占位 tool result 后再追加新事件并重新请求；无 steering 时取消未完成生成、只保留已确认消息；非打断事件一律入队批处理。\n5. **多条更新的综合**：给每个未处理事件加显式标记（`[未处理事件 2/4] ...`），末尾附汇总，提示模型必须回应全部，防止只记住最后一条。\n6. **并发任务的状态可观测**：每个异步工具调用都要有任务 ID，支持按 ID 查询进度和取消；完成事件注入主轨迹时带真实结果（退出码、产出哈希），不要只报\"已完成\"。\n6. **触达用户**：用户沟通工具支持异步消息、已读/未读、多渠道（IM/短信/邮件/电话/推送），按紧急程度、用户状态、内容性质、用户偏好选择渠道——通知机制同时是召回机制，用于长任务完成与周期性任务的习惯养成。\n7. **身份与环境**：给 Agent 独立虚拟身份（专属账号、存储、计算环境）跑在隔离的 VM/容器或虚拟手机里；通过共享卷（如 `/workspace/shared`）以**文件路径**而非内容传数据，避免占满上下文；必须登录用户真实账号时走 Human-in-the-Loop（VNC/RDP 让用户亲自登录，会话令牌有效期内复用）。\n8. **验收三层**：事件能否及时到达 → 系统是否按策略执行（取消真的终止了子进程、批量是否齐全）→ 模型是否正确使用了这批更新（结果归属、未完成时不编造、恢复原任务）。可加状态检查点做中断后恢复验证。\n\n## 常见陷阱\n\n- **把\"任务已启动\"当成\"任务已完成\"**：占位符让模型误以为结果已到，在真实结果返回前做出依赖它的判断。必须用明确的任务状态和结果校验，并在评估中检查是否编造了未到达的数据。\n- **注意力分散**：批量事件只回应最后一条，前面的要求被静默丢弃。\n- **轮询冒充异步**：让 Agent 每隔几秒查一次状态，既慢又烧 token；要么用推送通道，要么用循环定时器 + 增量监控。\n- **明文拼接不可见推理**：服务端管理的 reasoning 状态要按提供商续接协议保留，不要自行拼出\"半截思考\"回灌。\n- **取消只发信号不检查**：执行器若不响应取消（类似不检查 `ctx.Done()`），\"停止\"消息发出去任务还在跑。\n- **给所有事件同一优先级**：紧急告警和常规输入走同一条队列，要么该停的停不下来，要么鸡毛蒜皮打断主任务。\n- **直接托管用户个人账号**：Agent 出错或被攻破即暴露全部数字身份；独立身份 + 隔离环境更安全也更可审计。\n- **忽略反机器人机制**：数据中心 IP 的虚拟环境容易被识别，需住宅代理；平台侧还可能有生态级封禁。\n- **用一次失败反推训练原因**：未公开的训练过程不可证，先查系统层的任务状态、事件来源和执行反馈。\n- **忘记维护多个对话线程的关联**：第三方消息如何影响用户情绪、用户在不同线程扮演什么角色、何时综合多线程信息给建议——纯事件路由处理不了这类上下文。\n\n## 配套代码\n\n- `chapter6/async-agent/` — 实验 6-2：事件驱动异步 Agent 框架（Flux），并行工具、打断取消、检查点持久化，含零依赖离线 demo。\n- `chapter6/agent-with-event-trigger/` — 实验 6-1：FastAPI 事件驱动 Agent + 42 个 MCP 工具，演示\"事件到达 → Agent 处理 → 结果输出\"最小闭环。\n- `chapter6/async-agent/` 同时给出离线验收 demo（并行 vs 串行墙钟时间、打断取消后恢复、检查点持久化与还原）与 LLM 场景复现两条路径，适合先跑离线 demo 验证运行时再上真实模型。\n- `chapter6/astra-async-steering/` — 实验 6-3：GPT-6 Astra 原生异步工具调用与回合中途引导，含 `sync` / `async` / `steer_reasoning` / `async_steer` / `unsupported_steer` 五组对照与真实 API 运行记录。\n- 语音相关（时间尺度更细的\"可打断\"场景）：`chapter6/end-to-end-speech/`、`chapter6/streaming-speech/`、`chapter6/controllable-tts/`、`chapter6/live-audio/`、`chapter6/phone-agent/`。\n- 机器人相关（毫秒级连续观察与动作分块）：`chapter6/gemini-xlerobot-navigation/`、`chapter6/rgb-sim2real-grasping/`、`chapter6/xlerobot-teleoperation/`。\n\n## 深度阅读\n\n- `book/chapter6.md`「模态与触发时机的扩展」\n- `book/chapter6.md`「异步与事件驱动：当世界主动找上门」\n- 相关设计文档：`chapter6/async-agent/agent_framework_design.md`（Flux 框架的运行时设计）\n\n<!-- File: skills/bad-case-to-dpo/SKILL.md (Tokens: ~4575 | Category: anthropic-skill) -->\n---\nname: bad-case-to-dpo\ndescription: 把生产 bad case / 失败轨迹转成训练数据时使用——从失败归因、轨迹前缀截取、DPO 偏好对构造、LoRA 训练到边界集与保留集双集验证的完整链路；也用于判断某类问题该走 SFT、DPO、RL 还是先修 Harness/工具/tokenizer，以及如何从运行轨迹中提取带证据的结构化学习信号。触发词：bad case、失败归因、DPO、偏好对、轨迹前缀、拒绝采样、过度矫正、边界集、保留集、过早结束、reward hacking、LoRA 微调、训练评估隔离。\n---\n\n# 从问题案例到训练数据\n\n## 何时使用\n\n- 生产出现 bad case：用户纠正、点踩、事后审计发现失败轨迹，想把它变成后训练输入\n- 判断某类失败该修 Harness/工具/tokenizer，还是值得投入训练\n- 构造 DPO 偏好对、轨迹前缀回归任务、决策边界示范\n- 决定一个失败案例该进 SFT 数据、DPO 偏好对、PRM 负标签还是 RLVP 惩罚规则\n- 训练后验证修复效果，担心\"修好一个、弄坏一片\"\n- 从运行轨迹中提取可学习信号，而不是只存一个总分\n\n## 核心原则\n\n- **归因到首个错误步骤，不是整条轨迹。** 以 Coding Agent \"过早结束\"为例：读代码、改代码可能都没错，错的是\"在缺乏证据时下结论\"那一个决策边界。归因记录必须落到这一步，训练数据才能对着它构造。\n- **失败轨迹不应直接当作正确的 SFT 示范。** 它的正确用法是：构造偏好对、发现任务覆盖缺口，或补上诊断与修复后再加入训练。\n- **判定必须靠模型写不了的机制。** \"是否完成\"要由隐藏测试、状态断言或外部终止钩子给出；测试必须读取真实文件或环境状态，不能只检查模型是否说了\"已完成\"，否则模型会学会口头承诺验证而不真正验证。\n- **边界集与保留集缺一不可。** 边界集（任务未完成）看模型是否选择继续验证而非宣称完成；保留集（任务已完成）看模型是否仍能正常收尾。只盯边界集会把模型训练成永远不敢结束的**过度矫正**状态：每个任务都无限验证下去，延迟与成本崩溃。这是\"改动不能破坏既有行为\"在参数层面的版本。\n- **训练与评估严格隔离。** 训练集与评估集必须是不同的任务、不同的参数、不同的模板组合；参考解法、隐藏测试和验证器反馈不能泄露给模型。隔离规则应由单元测试强制检查，而不是靠人记得。\n- **先排除非模型原因。** 沿\"文件原始字节 → 工具返回 → Harness 序列化 → 模型上下文 → 模型 token 输出 → 解码字符串 → JSON/tool-call 解析 → 工具匹配\"逐层对比。只有模型收到的上下文与原始字符串完全一致、而**模型输出是链路上首个出现差异的位置**，才能标为模型能力问题。否则修工具/Harness/tokenizer，修完再看还剩多少。\n- **小数据 DPO 必须混入通用任务数据。** 案例数量少时，按小配比混入通用任务做 LoRA 微调，避免把\"逢收尾必验证\"学成新的过拟合，也降低灾难性遗忘风险。\n- **学习信号必须带证据。** 单一总分无法指出该改哪里。可供学习的评价至少包含：任务成功/部分成功/失败、每个维度各自的结论、每条结论对应的证据位置（哪一轮对话、哪一次工具调用）、失败的类型标签。验证器还应被允许在证据不足时**拒绝评分**——低置信度案例应排除在学习集之外，而不是当作事实固化。\n\n## 实践模式\n\n### 完整链路：失败归因 → 双集验证\n\n**① 采集与归因。** 从用户纠正、点踩、事后审计三类生产信号收集失败轨迹，按错误分类定位**首个错误步骤**并记录错误类别。轨迹前缀回归任务就是从这个决策边界截取的。\n\n**② 分流：该不该训练。** 先问 prompt、工具、代码约束、上下文管理能否解决；再沿字节链路排除工具/Harness/tokenizer 问题。都不要动权重时就不训练。\n\n**③ 选训练形态。** 按第七章评估数据集的类型映射到第八章用法：\n\n| 你手上的材料 | 训练用法 |\n|---|---|\n| 端到端回归任务（含验证器） | RL rollout 任务与可验证奖励（RLVR）；拒绝采样（RFT）的采样池 |\n| 轨迹前缀回归任务 | DPO 偏好对、决策边界的 SFT 示范、On-Policy Distillation 的教师状态 |\n| 失败归因记录（首个错误步骤与错误类别） | 过程监督的负标签（PRM）、RLVP 路径惩罚的规则来源 |\n| Rubric 多维评分与人工金标集 | 向量奖励的各维度、生成式奖励模型（GRM）的训练与校准数据 |\n\n**④ 截取轨迹前缀，构造偏好对。** 在决策边界上截出\"准备宣称完成\"的轨迹前缀：rejected 是过早结束的错误行为，chosen 是\"先运行测试、逐条核对验收条件，再下结论\"的期望行为。chosen 由教师模型生成，再经规则验证器过滤（拒绝采样）。案例太少时用数据扩充（换任务类型、换缺失的验证项、换完成措辞）形成数百条偏好对。失败原因、适用条件和验证器应随样本保存，方便追溯和复查。\n\n**⑤ LoRA DPO 训练。** 小配比混入通用任务数据防过拟合。参考配置：Qwen2.5-7B-Instruct + bf16 LoRA、4 epochs、学习率 3e-5、单卡约 24GB 显存。训练回执记录配置、数据哈希与时间戳。\n\n**⑥ 双集验证。** 对未完成任务集和已完成任务保留集分别让模型给出\"下一步动作\"，判定属于\"宣称完成\"还是\"继续验证\"：\n\n- **未完成任务集的过早结束率** —— 训练后应下降\n- **已完成任务保留集的正常收尾率** —— 训练后应保持\n- **过度矫正率 = 1 − 正常收尾率** —— 应维持在低位\n\n优先采用**格式固定、与训练提示一致的候选比较**（固定两个候选动作，比较模型更偏好哪一个，直接测量决策边界），而不是开放式自由生成。同时抽查通用能力，确认 LoRA 补丁没有破坏其他能力。\n\n**⑦ 记录与追溯。** 训练数据与评估集分开保存；数据构造有确定性模板和教师模型两条路径时，两条都留证据回执。\n\n### 案例参照：Coding Agent 过早结束（实验 8-17）\n\n配套数据：24 条轨迹前缀 bad case，覆盖四类过早结束——未跑测试就宣称完成、多目标只完成一部分、声称完成但验收条件未满足、遇错放弃宣称不可能（含删除失败测试/skip 等 reward hacking 变体）；与训练数据严格隔离的留出评估集为 boundary 12 条 + retention 8 条。\n\n实测结果：基座在固定候选比较的未完成任务集上选对 **3/12（25.0%）**，已完成任务保留集 **8/8（100%）**；LoRA DPO 后分别为 **11/12（91.7%）** 和 **8/8（100%）**。自由生成是补充诊断：过早结束 1/12→0/12，但正常收尾 6/8→0/8——**说明小数据 DPO 会让模型在开放式回答里过于谨慎**，因此主要结论只采用候选比较口径，不能外推成线上总体成功率提升。\n\n同一个问题还有 RL 分支：把\"宣称完成前必须跑通验收测试\"写成可验证奖励，测试对模型不可见，模型宣称完成时才运行，通过 +1、不通过 −1。\n\n### 另外两类常见案例的处理差异\n\n- **规则类反馈（如\"中文直引号应统一为弯引号\"）**：期望描述不是可直接训练的规则，同一个引号在中文自然语言、英文原文、Markdown 行内代码、代码块、注释、JSON、路径中角色完全不同。正确做法是**作用域敏感的最小编辑**：先把规则写成可审计的 Skill（正例覆盖需转换的中文段落与中文注释，反例覆盖英文原文、字符串字面量、JSON、路径、行内代码），它同时作为合成数据的标签依据、训练后的回归规范和规则变更时的重训输入。\n- **byte-exact 复制类（如 `edit_file` 的 `old_string` 匹配失败）**：把复制任务抽象成三个可验证任务——直接逐字复述、在相似且等长的多个字符串中选择完全相同的目标、把指定字符串完整抄写到 `old_string` 工具参数。样本特意包含真实编辑最容易损坏的空格、换行、反斜杠、Unicode 组合字符。训练后要用独立 tokenizer 审计排除词元化造成的假象：若 round-trip 上限本身就是 80.1%，模型测到 80.1% 就不能算作纯能力提升。\n\n### 从运行轨迹中提取学习信号（三层验证）\n\n评价一条轨迹实质是依次回答三个问题：**事情是否办成了、是否以允许的方式办成、是否让用户舒服。**\n\n- **底层结果验证器**——读测试结果、数据库状态、工具返回。这类信号来自环境真实状态，比模型对自己行为的描述可靠，是三层中最应优先建立的一层。\n- **中间过程验证器**——检查业务规则、权限和动作序列，区分\"结果已达成\"与\"结果以允许的路径达成\"。删除失败测试用例也能让测试通过；口头承诺也能得到暂时满意。政策库、权限表与动作轨迹均可精确表达，因此这层同样可以由代码判定。\n- **上层质量验证器**——是否耐心、是否提供合规变通、文本是否自然简洁。用 LLM-as-a-Judge 加预定义 Rubric，要求逐项给分并引用轨迹证据。\n\n输出形态决定它能否成为学习信号：单一总分只能反映一次运行的优劣。四项内容（成败判定、每维度结论、证据位置、失败类型标签）齐备，后续才能判断该更新知识、提示词、程序还是模型参数。\n\n## 常见陷阱\n\n- **把失败轨迹直接当正确示范训练**，把错误行为固化进参数。\n- **只优化边界集，不看保留集**，把模型训成永远不敢收尾的过度矫正状态。\n- **训练集与评估集共享任务或参数**，评估失去独立性；隔离规则要由测试强制，不靠人记得。\n- **用模型自述当完成判定**，模型很快学会\"口头声称去验证\"而不真的验证。\n- **把系统层损坏误报为后训练收益**：直接复述探针正确但工具调用仍失败时，该修的是 Harness 或工具协议。\n- **把 tokenizer/序列化损坏误判为模型复制能力不足**，训练前先做独立 tokenizer round-trip 审计。\n- **案例太少又不做扩充**，几条偏好对撑不起一个决策边界；或扩充时只换措辞不换任务类型与缺失验证项。\n- **小数据 DPO 不混通用数据**，学出\"逢 X 必 Y\"的新过拟合并带来灾难性遗忘。\n- **低置信度结论进入学习集**，错误经验和提示注入被固化并在后续任务持续放大。\n- **把开放式自由生成当主要验收口径**——小数据 DPO 下自由生成会过度保守，格式固定的候选比较才与训练提示一致。\n\n## 配套代码\n\n- `chapter8/premature-completion-dpo/` — 全书唯一从生产 bad case 出发的训练实验：24 条 bad case、boundary 12 + retention 8 留出评估集、隐藏测试；`python demo.py` 离线端到端演示，`python -m pytest -q test_pipeline.py` 机制单元测试，`python build_preference_data.py` 生成偏好对（`--teacher` 走教师模型拒绝采样路径），`python train_dpo.py --smoke` 数据/tokenizer 前向检查，`python train_dpo.py` 单卡 LoRA DPO，`python evaluate.py --decision-score` 双集候选比较评估，`python train_grpo_optional.py` 同一问题的可选 RL 分支。\n- `chapter8/curly-quote-sft/` — 规则类反馈的另一种监督目标：先写 `SKILL.md` 规范，再结构化合成数据做作用域敏感 SFT。\n- `chapter8/exact-copy-sft/` — byte-exact 复制 SFT，含 `tokenizer_audit.py` 排除词元化假象。\n- `chapter8/cot-distillation/` — \"生成候选—验证过滤—只留正确轨迹\"的拒绝采样流水线范例。\n\n## 深度阅读\n\n- `book/chapter8.md`「从问题案例到后训练」\n- `book/chapter8.md`「SFT 数据合成：从示范到可训练轨迹」\n- `book/chapter8.md`「奖励设计：如何把任务目标变成学习信号」\n- `book/chapter9.md`「从运行轨迹中获得学习信号」\n\n<!-- File: skills/coding-agent-harness/SKILL.md (Tokens: ~2732 | Category: anthropic-skill) -->\n---\nname: coding-agent-harness\ndescription: 搭建 Coding Agent 或设计 Agent 护栏时使用——当你要构建能自主读写代码、跑测试、自我纠错的编码 Agent，或为已有 Agent 系统补约束/验证/纠正机制、设计执行边界与验收基线、判断某类任务是否适合交给 Agent、优化 Harness 提示词与工具集时使用。覆盖 Harness 四组件、任务四象限、四条设计原则与业界实践。\n---\n\n# Coding Agent 与 Harness 工程\n\n## 何时使用\n- 从零搭建 Coding Agent（选工具集、定工作流、接测试反馈）\n- 为已有 Agent 补可靠性：加护栏、验收基线、执行边界、回退手段\n- 评估一个任务是否适合交给 Agent 自主执行（四象限判断）\n- Agent \"能跑但不可靠\"：跑偏、走破坏性捷径、过早宣布完成\n- 优化 Harness 本身（提示词、工具中间件、自验证循环）而不是换模型\n\n## 核心原则\n\n**Agent = Model + Harness，Harness = 上下文管理 + 工具接口 + 约束 + 验证 + 纠正。**\nHarness 是\"Agent 边界内、模型之外\"的运行与治理层：工具定义、调用适配器、沙箱权限属于 Harness；沙箱内的文件进程、外部数据库、用户属于 Environment。模型能力趋同后，竞争力在 Harness。\n\n**Coding Agent 场景的 Harness 四组件**（把抽象机制落地成工程件）：\n\n| 组件 | 回答的问题 | 落地形态 |\n| --- | --- | --- |\n| 验收基线 | 什么算做完了 | 测试套件、CI 管道、代码审查标准 |\n| 执行边界 | 能碰什么不能碰什么 | 模块边界、依赖规则、权限控制 |\n| 反馈信号 | 自动化的对错判断 | Linter 输出、测试结果、类型检查错误 |\n| 回退手段 | 出了问题怎么恢复 | Git 版本控制、沙盒隔离、快照回滚 |\n\n**任务四象限（目标清晰度 × 验证自动化程度）**——Harness 的目标是把任务推向\"目标明确 + 可自动验证\"：\n\n- 目标明确 + 可自动验证 = **最佳区域**（修复有测试用例的 bug）\n- 目标明确 + 需人工验证 = **吞吐量受限**，天花板是人的审查速度\n- 目标模糊 + 可自动验证 = **高效地跑偏**（如拿 linter 分数优化\"代码质量\"）\n- 目标模糊 + 需人工验证 = **难以启动**（如\"让 UI 更好看\"）\n\n代码编写天然处于象限核心：测试套件给验收标准，Linter/类型检查给即时验证，Git 给版本控制与回退。Coding Agent 成熟度最高不是因为代码模型最强，而是软件工程几十年积累的基础设施天然就是一套 Harness。\n\n**四条可迁移的设计原则**：\n\n1. **约束优先于指导**——能用代码强制的规则不要用文档建议。Linter 规则、类型约束、CI 检查是\"做不了\"，系统提示词里\"请遵循...\"只是\"建议别做\"。\n2. **验证要自动化**——人工审查是不可扩展的瓶颈，测试/检查/监控的投入回报率远高于加人力。\n3. **反馈越快越好、越结构化越好**——错误信息越详细、越接近出错时刻，Agent 纠正效率越高。\n4. **回退要可靠**——有安全网 Agent 才敢试错；Git 分支、沙盒、快照确保任何错误可逆。\n\n**约束管动作，不只是管结果。** 验收基线管结果对不对，执行边界管过程：删库重建\"修复\"了故障但数据没了，删光重写让编译通过但实现没了。这类破坏性捷径 Agent 总能绕开指标找到（reward hacking 的日常形态），因此 `rm -rf`、删生产数据、覆盖未读文件要设专门检查与审批。\n\n**并行调用的故障边界控制**：一个工具失败时，故障只在同一批并行调用内传播（级联中止依赖它的调用），不取消独立调用，不上升到父级操作、不让整个任务中止。每个工具声明是否支持并发（默认否，失败安全）。\n\n**业界经验**：\n- 大规模代码迁移成功靠三件事：知识必须存在于代码库本身（Agent 看不到的等于不存在）、约束编码进 Linter/CI 而非文档、验证与纠正全链路自动化。\n- LangChain 只优化 Harness（提示词、工具中间件、自验证循环）就把 Terminal Bench 2.0 从 52.8% 提到 66.5%，并用 Agent 分析失败轨迹反哺 Harness，让 Harness 工程从经验驱动变数据驱动。\n- Anthropic 拆两个角色：初始化 Agent 分解任务清单，执行 Agent 逐步推进并留下清晰的交接产物，解决\"一次想做太多\"和\"过早声称完成\"。\n\n## 实践模式\n\n**建一个 Coding Agent 的最小清单**：\n\n1. **工具集**：文件读写（read/write/edit）、目录浏览（glob/ls）、内容搜索（grep）、命令执行（bash）七件套；每个工具命名直观、参数带例子、边界有说明（防呆设计）。\n2. **工作流**：先理解项目（读文档、建认知框架）→ 设计 → 实现 → **立即写测试并跑** → 失败则分析-定位-修复循环，直到测试全绿。把\"测试通过\"而非\"代码写完\"定义为完成标准——跳过测试直接报完成是 Coding Agent 最常见的偷懒方式。\n3. **验收基线**：接入现成的测试套件、Linter、类型检查、CI；没有就先补最小可跑的。\n4. **执行边界**：默认权限最小化（故障安全默认值，能力默认关闭、显式开放）；危险命令走审批。\n5. **回退手段**：每次任务前开 Git 分支或快照；沙盒内执行不可逆操作。\n6. **反馈回路**：把 Linter/测试/编译错误结构化地喂回上下文（附行号、文件路径、错误类型）。\n7. **持续改进**：收集失败轨迹，让 Agent 分析轨迹反哺 Harness 修改。\n\n**上下文与环境注入**（Harness 的上下文层）：大文件按行号范围读取并给每行加行号前缀；长命令输出只保留头部（错误上下文）与尾部（错误总结）并说明完整输出已落盘；每次推理前以状态栏形式动态注入当前工作目录、git 分支、最近提交、未暂存变更（动态追加，别硬编码进系统提示词以免破坏 KV Cache）；维护持久化终端会话保留 cd/环境变量状态。\n\n## 常见陷阱\n- 把指导写进提示词而不落成代码约束——模型会忽略\"请遵循...\"式建议\n- 没有验收基线就放权：Agent 高效地往错误方向跑，或走破坏性捷径（删库重建、删光重写）\n- 写完代码不跑测试就报告\"任务完成\"\n- 把整个代码库一股脑塞进上下文，既不经济也没必要\n- 一个工具失败就中止整批并行调用甚至整个任务\n- 只换模型不修 Harness：基准提升往往来自 Harness 而非模型\n- 环境信息硬编码在静态系统提示词里\n\n## 配套代码\n- `chapter5/coding-agent/` — 纯 Python 实现的生产级 Coding Agent：16 个工具、patch 应用、测试/lint 验收反馈与失败路径\n- `chapter1/context/` — 上下文感知 Agent 与消融实验：量化 history/reasoning/工具调用/工具结果各自的作用\n- `chapter1/web-search-agent/` — 基于 Kimi Formula API 的自主 ReAct 搜索 Agent，展示\"模型即 Agent\"的最小闭环\n- `chapter1/search-codegen/` — Responses API 深度研究 Agent：托管 web_search + code_interpreter 的编排\n- `chapter1/learning-from-experience/` — LLM 上下文学习 vs 传统 RL 对照，理解 Agent 经验从哪来\n- `chapter1/image-gen-workflow/` — 工作流路线 vs 原生生成路线对照：何时该用固定 Harness、何时该交给模型自主\n\n## 深度阅读\n- `book/chapter5.md`「Coding Agent」→「Harness 工程在 Coding Agent 中的实践」\n- `book/chapter1.md`「Harness 工程：模型之外的竞争力」\n\n<!-- File: skills/computer-use/SKILL.md (Tokens: ~3813 | Category: anthropic-skill) -->\n---\nname: computer-use\ndescription: >-\n  构建 GUI 自动化 Agent、让 Agent 像人一样看屏幕并用鼠标键盘操作桌面或浏览器软件时使用。\n  覆盖感知-思考-行动循环、动作空间（GUI/bash/文件编辑）、视觉定位 Grounding 三条路线\n  （结构化元素索引、Set-of-Mark、纯坐标预测）、分辨率坐标缩放、关键帧观察接口、世界模型与移动端生态壁垒。\n  触发词：Computer Use、GUI 自动化、截图、Grounding、browser-use、Set-of-Mark、视觉定位、坐标缩放、OSWorld。\n---\n\n# Computer Use：GUI 自动化 Agent\n\n## 何时使用\n\n- 要让 Agent 操作没有 API 的软件：填表、改系统设置、在网页上完成多步流程。\n- 要评估或实现\"截图 → 决策 → 执行动作\"的闭环，选模型、选 grounding 方案、选框架。\n- 定位不准、坐标偏移、点击错元素，需要排查 grounding 与坐标缩放链路。\n- Agent 每 3–5 秒才看一眼屏幕，错过通知、视频、弹窗等\"两帧之间发生的事\"。\n- 要把 Computer Use 扩展到移动端（Android 无障碍服务）或评估平台封禁风险。\n- 设计不可逆操作（删除、购买、提交）前的确认与安全边界。\n- 要减少操作步数与等待时间，让 Agent 达到\"实用\"而不只是\"答对\"（对照 OSWorld-Human 的人类基线）。\n- 没有编程 API 可用、Selenium 之类脚本化方案难以维护页面的场景。\n- 要在容器化虚拟桌面中跑 Agent，并隔离不可逆操作对真实环境的影响。\n\n## 核心原则\n\n- **核心是感知-思考-行动循环**：截图 → 多模态模型输出思考 + 一个动作 → 执行层真实执行（移动鼠标、点击、输入）→ 等界面响应再截图进入下一轮。\n- **区分\"看懂界面\"和\"完成任务\"**：前者可用一次截图问答测量（多模态理解）；后者要求把理解和动作放进闭环，处理页面加载、状态变化、误操作和不可逆后果。每执行一步都要**重新确认现实是否仍符合计划**。\n- **动作空间分三类**：GUI 操作（鼠标移动/点击/拖拽/滚动、键盘输入/组合键/长按、截图与等待）、持久 bash 会话（跨调用保持环境状态，用哨兵字符串判命令是否执行完）、字符串匹配的文件编辑（比整文件覆盖更精确，可撤销）。\n- **动作空间不是供应商私有协议**：只要 Harness 能把同样的截图、动作约束和执行结果转换成目标模型支持的消息与结构化输出，Claude、开放权重视觉模型和自托管端点都能驱动同一个循环。\n- **Grounding 优先把定位变成选择题**：先给元素编号，模型只报 ID，系统换算中心坐标。选择题比填空题容易答对——模型说\"点击 [123]\"而不是\"点击 (350, 464)\"。三条路线按界面性质选：\n  - **结构化元素索引**（DOM / Accessibility Tree，browser-use 路线）：结构化信息可得时首选，最精确稳定，无分割模型的漏检误检。\n  - **Set-of-Mark 视觉标注**：用分割模型切候选区域叠加编号，不需要 DOM，原生桌面软件、游戏、Canvas/WebGL 界面适用。\n  - **纯坐标预测**（SeeClick、Claude computer use）：直接在 GUI 截图-坐标配对上训练的模型更直接，省去标注步骤，但小元素和密集界面精度差。\n- **坐标预测必须做分辨率管理**：模型对坐标的理解依赖训练分辨率，不匹配就系统性偏移。按**宽高比**选最接近的目标分辨率做双向缩放（如 2560×1440 的 16:9 屏幕选 FWXGA 1366×768，模型返回 (683,384) 反推真实坐标约 (1280,720)）。切忌非等比拉伸把画面压扁。\n- **\"屏幕是静止的\"是危险假设**：该重新设计的是观察接口而不是动作接口——用关键帧截图（小模型判断是否有意义的变化，变化频繁时约 1 秒一次）、音量门控的语音转写、把截图压成一句持久文字描述来压缩多模态历史。\n- **世界模型带来\"推测执行\"**：行动前预测候选动作造成的状态差异，一致就沿计划继续，偏离才停下重规划。要预测的是**可检查的状态差异**（窗口、焦点、滚动位置、输入框内容、加载状态、权限、网络返回），不是生成逼真未来截图。\n- **生态壁垒是结构性问题**：Agent 直达目标会绕过广告与推荐变现链路，平台有动机封禁；这不只是 CAPTCHA 的技术对抗，短期难以调和。\n- **循环节奏与尺度**：Computer Use 的时间尺度是亚秒到秒——屏幕在两帧之间持续变化，因此\"动作后重新确认现实\"不是可选项而是循环的必要组成部分。这与语音（10ms–1s，可被打断）和机器人（毫秒级，动作分块可抢占）是不同的时机问题。\n- **结构化索引不省 token 但省错误**：把所有可交互元素及其属性发给模型成本高，但换来定位准确稳定，且免去分割模型的漏检误检——这是值得的交换。\n- **browser-use 式四步流程**：CDP 取 DOM 与无障碍信息 → 检测可交互元素 → 标注唯一 ID 并在截图绘边界框 → 同步生成\"ID → 元素描述\"文本列表；模型只输出 ID，系统用中心坐标执行。\n\n## 实践模式\n\n1. **搭循环**：Harness 负责截图、把动作约束转换成目标模型支持的消息与结构化输出、执行结果回传。同一套循环可换驱动模型（Claude、开放权重 VLM、自托管 vLLM/SGLang 端点），并保留实际端点与模型 ID 以便区分实验组。\n2. **选 grounding 路线**：先问\"这个界面有没有结构化信息可得\"——Web 走 DOM/a11y 索引（CDP 取 DOM → 检测可交互元素 → 标注唯一 ID 并在截图绘边界框 → 同步生成 ID 到元素的文本列表）；原生桌面软件、Canvas/WebGL、游戏走视觉标注或坐标预测；模型做过 GUI 定位训练才优先坐标预测。\n3. **实现坐标缩放层**：枚举目标模型支持的分辨率档位，按宽高比匹配；截图时等比缩放送入，动作坐标按比例反算回真实屏幕。\n4. **每步只做一个动作**：保留每步截图与动作轨迹，便于回放和验收；页面加载用 `wait`，不要盲点。\n5. **安全边界**：默认只读；不点击验证码、不登录、不提交、不购买、不改外部数据；不可逆操作先在隔离虚拟桌面预测是否出现确认框，必要时请求用户确认。凭证不落盘，最终截图要能佐证结论。\n6. **恢复策略要预置**：遇到验证码、权限弹窗、页面 404 时按只读恢复指令改走可达路径（如改用公开 JSON 接口取数据），而不是反复重试或点击挑战。\n6. **增强观察接口**：关键帧 + 音量门控 ASR + 文字描述三件套，让 Agent 对弹窗、视频、会议人声有感知，并让被清理出上下文的原图仍留下文字痕迹。\n7. **移动端适配**：动作空间从\"鼠标坐标 + 键盘\"换成无障碍服务 API（如 Android AccessibilityService）读写元素、下发点击与输入；坐标语义变为手势类型（单击/长按/滑动起点）的边界。\n8. **验收要测量效率**：准确率达到人类水平不等于实用——对照人类操作步数与等待时间，把\"步骤数、总时长\"纳入验收指标，并记录真实运行证据（截图哈希、动作轨迹）。\n\n## 常见陷阱\n\n- **把截图答对当成任务完成**：没有闭环、不重新确认现实，页面早已跳转还在点原来的坐标。\n- **非等比缩放**：把 16:9 硬塞进 4:3，画面横向压扁，坐标判断整体偏移。\n- **分辨率不匹配不换算**：直接把模型在训练分辨率下输出的坐标当真实屏幕坐标用。\n- **密集界面/小元素上裸报坐标**：三条路线在此都容易出错，优先编号选择题方案。\n- **分割模型漏检误检**：视觉标注路线里候选区域切错，模型只能从错的选项里选。\n- **每步多个动作**：中间页面变化无法回放定位，错误无法归因。\n- **假设屏幕静止**：两帧之间的通知、视频、声音全部丢失，任务在错误的世界观上推进。\n- **忽视平台封禁与验证码**：消费级场景中账号可能被直接限制，比技术问题更难解。\n- **只关注准确率不看效率**：步骤数和等待时间远超人类，成功也不可用。\n- **把不同模型的运行混为一组**：供应商与开放权重是不同实验组，必须分别记录端点、模型 ID 与证据。\n\n## 配套代码\n\n- `chapter6/claude-computer-use-native/` — 实验 6-8（Anthropic 原生路径）：容器化 Ubuntu 桌面中的官方 Computer Use Demo，`computer` / `bash` / 编辑器三类原生工具的真实运行与确定性验收记录。\n- `chapter6/computer-use-open-model/` — 实验 6-8/6-9（开放模型路径）：同一\"截图 → 结构化动作 → 浏览器执行\"循环，默认 Qwen3-VL 32B Instruct 驱动 browser-use，可接 OpenRouter 或自托管 vLLM/SGLang；含端点合格性契约（收截图、产出 Browser Use 动作 schema、每步一个动作、不静默替换模型）。\n- 两个 companion 都保留了真实运行证据（截图哈希、动作轨迹、确定性验收），可作为自己实现时的证据门禁模板；其中原生路径还记录了一次撞上 Google reCAPTCHA 后按只读恢复指令改走公开天气 JSON 接口、全程未点击挑战的完整轨迹。\n- 语音相关（同为\"时机\"扩展，可作对照）：`chapter6/end-to-end-speech/`、`chapter6/streaming-speech/`、`chapter6/controllable-tts/`、`chapter6/live-audio/`、`chapter6/phone-agent/`。\n- 机器人相关（从屏幕像素到物理传感器）：`chapter6/gemini-xlerobot-navigation/`、`chapter6/rgb-sim2real-grasping/`、`chapter6/xlerobot-teleoperation/`。\n- 移动端基准与评测可参考第七章 AndroidWorld 一节；本章 `chapter6/phone-agent/` 给出真实手机上的 Agent 驱动样例。\n\n## 深度阅读\n\n- `book/chapter6.md`「模态与触发时机的扩展」\n- `book/chapter6.md`「Computer Use：GUI 自动化 Agent」\n- 实验记录与证据门禁模板见 `chapter6/computer-use-open-model/` 与 `chapter6/claude-computer-use-native/` 的 README 与 `validation/` 目录。\n\n<!-- File: skills/context-compression/SKILL.md (Tokens: ~4027 | Category: anthropic-skill) -->\n---\nname: context-compression\ndescription: 上下文膨胀、工具结果撑爆窗口、Agent 决策质量随轮次下降时使用——上下文压缩的三个动机（长度成本、思考质量、上下文焦虑）、压缩即检索的机制、六种压缩策略实测数据、生产级五层分层压缩、四条设计原则，以及用子 Agent 隔离代替压缩。\n---\n\n# 上下文压缩策略\n\n压缩解决的是相反方向的问题：**如何为上下文做减法**——什么时候压缩、怎么压缩、为什么即使上下文没满也应该压缩。核心认知：**上下文学习本质上是检索而非推理**，压缩就是把需要思考才能得到的结论，变成可以直接检索的知识。\n\n## 何时使用\n\n- 工具调用结果动辄数万字符，几轮交互就撑满 128K 窗口\n- Agent 在长任务中「明明窗口没满，却找不到关键信息」或反复纠结已解决的问题\n- 模型在任务尚未完成前提前收尾、草率下结论\n- 设计压缩策略（何时触发、压缩什么、保留什么）或排查压缩副作用\n- 评估「把大任务委派给子 Agent」与「主 Agent 自己做完再压缩」的取舍\n\n## 核心原则\n\n- **三个动机，层次不同**：① 长度与成本约束（窗口有限、token 越贵、延迟越高）；② 提升思考质量——总结后的知识比原始形式更利于模型使用，十几轮搜索的原始结果散落各处，模型每次决策都要在数万 token 中反复检索；③ 缓解**上下文焦虑（Context Anxiety）**——模型认为窗口即将耗尽时可能在任务完成前提前收尾，在未接近耗尽时就提前压缩可能提升决策质量。\n- **上下文窗口是一台只有一半的检索引擎**：检索这一半极强（相当于每次前向传播都内置了 RAG），但缺「提炼层」——上下文里的东西从来不会被自动数一遍、建索引或就地总结。任何「关于这些内容的结论」都要从原始记录现算一遍，代价随内容量 N 上涨。\n- **压缩与状态栏是同一枚硬币的两面**：状态栏把算好的结论**加**进上下文（由代码确定性维护），压缩把臃肿的原始记录**换**成算好的结论（多用一次 LLM 调用蒸馏）。\n- **上下文腐化（Context Rot）≠ 溢出**：溢出是「装不下了」，腐化是「装得下但找不到了」——后者更隐蔽，Agent 表面正常工作，决策质量悄然下降。注意力权重被分散到更多 token 上，无关内容一旦占大头，决策质量明显下滑。\n- **主动显式提炼，不要期望模型自动学习**：与其让模型被动在海量信息中检索，不如主动提供经过提炼的高密度结构化知识。\n- **压缩最容易丢失**：早期的架构决策、约束背后的理由、失败的路径。因此 Agent 需要定期把进展记录到文档，而不是把所有信息零散堆在执行历史里。\n- **隔离优于压缩**：压缩是信息已进入上下文后的事后有损补救；隔离让大体积中间信息根本不进入主上下文。\n\n## 实践模式\n\n### 1. 六种压缩策略实测对比（实验 2-10）\n\n任务：识别并追踪 OpenAI 联合创始人的职业状态；Kimi K3（原生约 1M 窗口，实验刻意限制在 128K 预算以触发压缩）。\n\n| 策略 | 做法 | 迭代 | Token | 压缩率 | 问题 |\n| --- | --- | --- | --- | --- | --- |\n| 无压缩 | 完整保留原始结果 | 5 次即溢出失败 | ~165,000 | — | 7 次搜索累计约 367,000 字符（平均 52,000/次），数次搜索即耗尽 128K |\n| 个体摘要 | 每个结果独立生成 2-3 段摘要 | 12 | 276,608 | 10.9% | 信息碎片化，多页重复描述同一事件 |\n| 组合摘要 | 所有结果合并后一份综合摘要 | 10 | 93,449 | 4.3% | 输入超长必须截断，可能丢失末尾信息 |\n| **上下文感知** | 压缩提示中带入查询意图与已积累信息 | 7 | 40,157 | ~3.0% | 最优平衡点 |\n| 带引用的上下文感知 | 智能压缩 + 每条事实附带来源 URL | 7 | — | — | 内容有损、索引无损，可回溯原文 |\n| 自适应窗口化 | 阈值触发 + 批量压缩 + 防重复 | — | 174,601 | — | 初期保留完整原始信息，灵活性最大 |\n\n> 压缩率定义为「压缩后体积 / 原文体积」，数值越小表示压得越狠。上下文感知压缩将 token 使用量减少 75% 以上。\n\n**上下文感知的提示词写法**：在压缩提示中指定 `Given the search query: {query}` 和 `Current context: {context}`，引导模型生成针对性摘要。实测把约 150K 字符压到 2K 字符时，仍保留创始人姓名与职位变动等后续任务需要的关键信息。\n\n### 2. 自适应窗口化三机制（推荐默认）\n\n- **阈值触发**：持续监控上下文使用率，prompt token 超过窗口 80% 时才激活压缩（如 102,400 / 128K）。\n- **批量压缩**：触发时一次性压缩所有未标记的工具结果，而不是每轮零碎压。\n- **防重复保护**：添加 `[COMPRESSED]` 标记，确保已压缩内容永不被重复处理。\n\n### 3. 压缩与 KV Cache 的共存\n\n压缩不是在单次 API 调用中修改上下文，而是在**两次 API 调用之间**由框架预处理消息列表：\n\n1. **System Prompt 和 Tool Definitions 永远不动**——静态前缀持续缓存。\n2. **压缩对象是对话历史中的 tool results**——替换位置之后的缓存失效，之前的仍有效。\n3. **有意识的权衡**：不压缩则溢出失败；压缩损失部分缓存但长度可控、信息密度更高。**压缩频次需要权衡——频繁压缩频繁破坏缓存，最好在接近阈值时批量压缩，而不是每轮都压。**\n\n### 4. 生产级五层分层压缩（Claude Code 参照）\n\n不同信息有不同保质期，压缩策略应与预期生命周期匹配，按代价从低到高排列：\n\n1. **工具结果预算控制**：大体积输出存磁盘，模型只看摘要预览；替换决策一旦做出就冻结，保证缓存一致性。\n2. **噪声直接删除**：低价值内容（如大量搜索结果中只被用了几行的部分）直接移除，不做摘要——对噪声做摘要只是浪费 token。\n3. **API 层微压缩**：通过上下文编辑能力指示服务端从前缀移除指定工具结果，本地消息不变；零本地实现成本，但移除点之后缓存同样失效，产生一次缓存重建——适合上下文即将溢出、反正要付这次代价时用，不要频繁触发。\n4. **归档式摘要**：逐轮结构化摘要，像 git log 保留每轮独立记录，而非 git squash 合并成一条，保留对话逻辑脉络。\n5. **全量压缩**：LLM 驱动的完整压缩，作为最后手段；分两阶段（先压会话记忆，不行再全量），并配**连续失败熔断器**——生产数据显示大量会话被困在反复压缩失败的循环中，熔断器避免持续烧钱。\n\n### 5. 四条压缩设计原则\n\n- **信息价值的非均匀分布**：关键决策点（如人员名单）> 支撑性证据（如新闻细节）> 冗余噪声（网页导航栏、页脚广告）。\n- **语义完整性**：`Sutskever 于 2024 年 5 月离开 OpenAI` 不能压成 `Sutskever 离开`——时间和公司名是不可丢失的关键信息。\n- **任务相关性**：同样内容在「查找创始人名单」和「了解个人背景」两个任务下应产生不同压缩结果。检索类任务保广度，分析类任务保深度，创作类任务保灵感触发点；理想的 Agent 应按任务类型自适应选择压缩策略。\n- **压缩即理解**：有效压缩需要深层语义理解，负责压缩的模块本身要接近主模型能力，形成「模型调用模型」的递归架构；好处是显式压缩的结果可审查、可跨会话复用。\n\n### 6. 必须保留的四类信息\n\n无论哪种策略，压缩时都要显式 preserve：**decisions（决策）、constraints（约束）、failures（失败路径）、citations（来源引用）**。\n\n### 7. 隔离优于压缩：子 Agent 上下文隔离\n\n对比同一个任务「在代码库中找到处理支付回调的函数」：\n\n- **主 Agent 亲自搜索**：可能把十几个文件数万 token 原始代码纳入主上下文，找到目标后绝大部分沦为永久噪声，还得靠后续压缩清理。\n- **委派给搜索子 Agent**：主上下文只增加两条消息——一条任务描述，一条结论（「函数位于 `src/payment/callbacks.py` 的 `handle_callback`，另有两处调用点」）；中间过程的数万 token 随子 Agent 上下文一起丢弃。\n\n代价是子 Agent 看不到主 Agent 完整上下文，**任务描述必须自包含、目标明确**。Claude Code 的 Task 工具、各类 Deep Research 的检索子 Agent 都是这一模式的生产实现。\n\n## 常见陷阱\n\n- **每轮都压缩**：频繁破坏 KV Cache 前缀，应阈值触发 + 批量压缩。\n- **对噪声做摘要**：把只用了几行的搜索结果压成摘要，纯浪费 token，应直接删除。\n- **压缩时丢掉时间和主体**：语义不完整比不压缩更糟——模型会基于错误事实继续推理。\n- **用远弱于主模型的模块做压缩**：压缩即理解，能力差距大会丢关键信息。\n- **把压缩当成长度问题的唯一解**：即使窗口够大，压缩仍能提升思考质量、缓解上下文焦虑。\n- **让模型自己数数和统计**：查找是注意力强项，统计要遍历全部记录并维护计数状态；应提前把结论写进上下文。\n- **把所有进展只留在执行历史里**：早期架构决策、约束理由、失败路径最容易在压缩中丢失，必须定期落到文档。\n- **给子 Agent 派发含糊任务**：子 Agent 上下文隔离的代价就是任务描述必须自包含，否则结论质量无法保证。\n\n## 配套代码\n\n- `chapter2/context-compression/` — 实验 2-10：实现并对比 6 种压缩策略（`no_compression` / `individual` / `combined` / `context_aware` / `citations` / `windowed`），输出成功率、耗时、token、压缩率、溢出次数对比表；用 `python experiment.py -s context_aware` 单跑，`-m moonshot-v1-128k` 配合 `CONTEXT_WINDOW_SIZE=128K` 复现溢出。\n\n## 深度阅读\n\n- `book/chapter2.md`「上下文压缩策略」\n\n<!-- File: skills/context-engineering/SKILL.md (Tokens: ~3453 | Category: anthropic-skill) -->\n---\nname: context-engineering\ndescription: 设计 Agent 系统提示词、上下文结构或按需加载的 Skill 时使用——覆盖 API 消息角色与「静态前缀 + 轨迹」结构、系统提示词写法（结构化、SOP、业务规则细化、few-shot）、Agent Skills 渐进式披露与 SKILL.md 编写、提示注入的上下文层防御，以及注意力位置偏好等布局原则。\n---\n\n# 上下文工程总纲\n\n上下文是 Agent 在每个决策点实际「看到」的全部信息：系统提示词、工具定义、用户消息、模型回复、工具执行结果。上下文工程就是系统性设计、组织、供给这些信息——模型智力只是基础，**上下文质量才是 Agent 能力的真正关键**。一个中等能力的模型配上精心组织的上下文，往往胜过一个顶级模型在信息匮乏下的盲目摸索。\n\n## 何时使用\n\n- 设计或重构 Agent 的系统提示词、工具定义、消息列表结构\n- 编写 / 审查一份 `SKILL.md`（元数据、路由描述、正文分层）\n- 排查「Agent 行为不稳定、违反业务规则、重复犯错、忘记约束」\n- 决定哪些知识该进系统提示词、哪些该做成按需加载的 Skill\n- 评估外部内容（网页、文档、邮件）进入上下文后的安全风险\n\n## 核心原则\n\n- **API 无状态，上下文由框架每轮重建。** 模型不会「记住」上一轮，Agent 框架必须每次都把完整消息历史送回去。\n- **上下文 = 四种消息角色 + `tools` 字段。** `system`（开发者规则，通常只有一条且在最前）、`user`（终端用户输入）、`assistant`（模型回复含 `tool_calls`）、`tool`（框架执行结果，靠 `tool_call_id` 与调用关联）；工具定义走请求顶层 `tools` 字段，不是消息角色。\n- **静态前缀 + 动态轨迹。** system prompt 与 tool definitions 全程不变，对话历史（trajectory）随交互持续增长。所有后续技术都在优化这个列表的内容与结构。\n- **模型决策、框架执行。** 模型只发出工具调用请求，真正执行工具的是 Agent 框架；循环「请求 → tool_calls → 执行 → 送回结果 → 再请求」就是 ReAct 循环的 API 实现。\n- **最低信息需求三件套**：代码信息（结构、职责、规范）、流程规范（分支、提交、评审、CI/CD）、环境信息（配置、数据库、密钥管理）。缺哪一类，Agent 就在哪一类上出错。\n- **新员工检验法**：如果一个聪明的新员工读完你的系统提示词还不知道该怎么做，Agent 也一样不知道。\n- **上下文学习是检索而非推理**：模型擅长从已有内容中查找，不擅长在前向传播中归纳统计。位置偏好（Lost in the Middle）意味着开头和结尾注意力最高，中部易被忽视——关键信息放两端。\n- **与模型厂商的训练方法保持一致**：选择 Agent 交互模式时优先采用厂商专门训练过的模式（Skills、tool_search 等），同生态内表现最佳。\n\n## 实践模式\n\n### 1. 系统提示词四维度\n\n- **语气与风格**：用明确指令而非请求，如 `You MUST answer concisely with fewer than 4 lines`；无法完成任务时 `keep your response to 1-2 sentences` 且不要解释为什么不能做。大写（`NEVER do X`）比 `Please avoid doing X` 更能引起注意，但过度使用会稀释效果，只留给真正关键的约束。\n- **结构化**：Markdown 标题（`#`、`##`）提供人可读的层次，XML 标签提供机器可解析的精确语义（`<file_operation>`、`<network_request>`），标签名本身携带语义。双层配合：Markdown 管组织逻辑，XML 管语义边界。\n- **流程驱动而非规则堆砌**：写成带分支的 SOP（Step 1 Validation → Step 2 Classification → ... → Step 5 Verification），让模型任何时刻都知道自己在哪个阶段、异常时按阶段处理，而不是遍历上百条零散规则找匹配项。\n- **业务规则细化到可执行**：把模糊规则（「根据任务情况选择合适的计费类型」）改写成布尔判断，例如 `NEVER use percentage_based_one_time for refunds and service cancellations. Use fixed_fee instead.`；成功率阈值直接映射到行为（>60% 可退款、<30% 拒绝任务）；计费粒度写死（每分钟 $0.05，汇总四舍五入到整数美元），并明确「节省」只基于现有账单计算。**提示词由产品经理基于线上数据设计，工程师负责准确编码，不擅自决定业务逻辑。**\n\n### 2. few-shot 示例的两个决策点\n\n- **位置**：放系统提示词 = 成为静态前缀对所有请求生效；或伪造一组 user/assistant 消息放在首轮对话中，适合按会话类型选用不同示例集。\n- **稳定性**：无论放哪，示例都处于上下文靠前区域，一旦确定必须字节级稳定——按请求动态检索「最相关」的示例等于每轮改写前缀，缓存会持续失效。为每类任务准备固定示例集。\n- **数量**：两三个精心挑选、覆盖边界情况的示例，胜过十个大同小异的示例——后者既占上下文，又稀释对规则本身的注意力。\n\n### 3. Agent Skills：渐进式披露三层\n\n- **第一层 元数据**：`SKILL.md` 顶部 YAML frontmatter 的 `name` + `description`，在正文加载前对 Agent 可见，用于路由判断。`description` 要写得像路由条件而非功能介绍：明确「何时使用」「何时不使用」的边界，给几条典型反例。写 `help with backend` 这种宽泛描述等于任何后端工作都能触发，路由必然失准。\n- **第二层 核心流程**：模型判断需要该 Skill 时才加载完整 `SKILL.md`（斜杠命令由客户端本地拦截展开；模型自主触发则多一次 ReAct 往返，正文作为 user message 追加）。\n- **第三层 细则**：通过文件引用深入到子文档（如 `html2pptx.md`、`reference.md`），Agent 按需选择性深入。\n- **上下文成本**：所有 Harness 都遵循「少量目录常驻、完整正文按需加载」。Skill 正文在调用位置追加到轨迹末尾，不改写已建立的前缀，因此对 KV Cache 友好。\n- **SKILL.md 四部分**（宝玉《图解 Skill》）：角色与读者；核心原则只留 3–5 条并配正反例；禁止清单记录高频错误、越权动作并写清合法例外；参考资料放术语表、模板、范文。规则写成「作用域 + 动作 + 例外 + 验证方式」，不要堆成越来越长的禁用词表。\n- Skill 还可捆绑可执行代码工具和模板文件，自包含、可独立版本控制。\n\n### 4. 上下文布局决策骨架\n\n```python\nstable_prefix = system_message            # 定了就不改\nstable_tools  = core_tool_schemas         # 固定顺序\ntrajectory    = load_message_history(session)\nstatus_message = make_status_message(derive_current_state(trajectory))\n\nif estimated_tokens(stable_prefix, trajectory, status_message) > budget:\n    trajectory = compress_old_evidence(\n        trajectory, preserve=[decisions, constraints, failures, citations]\n    )\n\nrequest.messages = [stable_prefix] + trajectory + [status_message]\nrequest.tools = stable_tools\n```\n\n### 5. 提示注入的上下文层防御\n\n第一道防线是帮模型分清「指令」与「数据」：\n\n- **来源标记**：外部内容注入前用 `<external_content source=\"webpage\">...</external_content>` 包裹并标注来源。\n- **结构化角色**：严格用 system/user/assistant/tool 角色体系传递信息，绝不把工具结果混入 user 消息——那等于亲手抹掉模型辨别来源的依据。\n- **输入清洗**：过滤「忽略之前的指令」等常见注入短语，只能作辅助，易被措辞变体绕过。\n- **把 Skill 和状态栏也当注入面**：Skill 本质是「把外部内容当作指令加载」的制度化形式，安装来源不明的 Skill 前必须审查内容；状态栏信息被模型高度信任，若摘要来自可被外部污染的数据源，信任会被反向利用。\n\n## 常见陷阱\n\n- **把时间戳、用户余额等动态信息写进 system prompt**——每轮改写前缀，缓存全失效（详见 `kv-cache-design`）。\n- **规则堆砌而无组织结构**：实验 2-4 显示，保留全部规则内容但打乱组织、去掉标题层次，任务成功率下降超过 30%，Agent 经常违反关键业务规则。\n- **清空工具描述**：保留函数签名但移除描述性文本，工具调用错误率增加 45%。\n- **盲目追求语气风格**：风格显著改变表达方式，但对任务完成率影响相对有限，不必在此过度投入。\n- **示例逐请求动态检索**：缓存持续失效，且不同示例集导致行为不可复现。\n- **所有场景塞进一个系统提示词**：既浪费 token（大部分与当前任务无关），又稀释注意力——应拆成按需加载的 Skill。\n- **让模型在业务规则上自由裁量**：模型优势在于遵循复杂指令和从长上下文提取信息，模糊规则会让同一任务在不同时间得到不同分类。\n- **把上下文层防御当作万无一失**：它只能降低攻击成功率，权限控制、沙盒隔离、高风险操作独立审查是另一层。\n\n## 配套代码\n\n- `chapter1/context/` — 多 provider 上下文感知 Agent，消融实验 1-1 对比 full / no history / no reasoning / no tool calls / no tool results 五种上下文模式。\n- `chapter2/prompt-engineering/` — 实验 2-4：基于 Tau-Bench 的提示工程消融框架，量化语气风格、指令组织、工具描述三个维度对任务完成率的影响。\n\n## 深度阅读\n\n- `book/chapter2.md`「上下文：决定 Agent 能力上限的关键」\n- `book/chapter2.md`「Agent 如何调用大模型：理解 API 的上下文结构」\n- `book/chapter2.md`「提示工程：优化系统提示词」\n- `book/chapter2.md`「动态提示词与 Agent Skills」\n\n<!-- File: skills/error-recovery/SKILL.md (Tokens: ~3953 | Category: anthropic-skill) -->\n---\nname: error-recovery\ndescription: 排查或加固 Agent 故障恢复机制时使用——当 Agent 陷入无限循环、流式响应中途断开、上下文溢出、模型服务限流过载、需要跨厂商接管跑到一半的轨迹、设计重试与熔断策略、防止错误处理路径自身引发连锁故障时使用。覆盖四层故障分类、检测方法、分级恢复策略、熔断上限与流式中断恢复。\n---\n\n# 故障与错误恢复\n\n## 何时使用\n- Agent 反复调用同一工具毫无进展、陷入死循环或死亡螺旋\n- 流式响应在思考/正文/工具调用参数中途断开，需要续写\n- 模型 API 限流、过载、超时、输出触顶，需要重试或降级\n- 上下文窗口溢出、压缩失败、轨迹结构损坏（工具调用缺配对结果）\n- 主模型持续不可用，要把轨迹交给另一家模型接着跑\n- 设计重试策略、熔断阈值、错误暴露边界\n- 工具调用幻觉/参数畸形，需要让模型自我纠正\n\n## 核心原则\n\n**故障分类学：四层。** 先分类再处理，不同层的故障走完全不同的恢复路径：\n\n- **API 层**：限流（429）、过载、请求超时、连接中断、输出触顶被截断。与任务内容无关，是基础设施噪声——可重试。\n- **工具层**：幻觉调用（调用不存在的工具）、参数畸形、执行抛异常，以及最危险的一种：工具反复返回同一错误，模型不加改变地反复重试。\n- **上下文层**：窗口溢出、压缩失败、轨迹结构损坏。\n- **控制流层**：死循环（相同操作无进展）与死亡螺旋（恢复逻辑自身又调 LLM、再次出错、连锁反应）。\n\n**检测：先分类，再计数。** 第一个判断不是\"要不要重试\"而是\"值不值得重试\"：可重试错误（限流、过载、网络抖动）重试才有意义；不可重试错误（参数不合法、权限不足、工具不存在）原样重试一万次结果相同，必须改变输入或策略。生产级 Harness 维护一张\"错误 → 恢复策略\"的映射表，而不是笼统地\"出错就重试\"。单次错误之外还要检测**模式**：对\"工具名 + 参数\"计算指纹，相同指纹反复出现就是无进展循环的明确信号；每条恢复路径维护独立的连续失败计数，为熔断提供依据。\n\n**活性与完整性监控。** 流式连接最危险的失败不是断开（会立即报错），而是**静默卡死**——连接建立但数据流停止。SDK 超时往往只覆盖初始连接而非传输过程，需要独立的空闲看门狗（超过设定时间无新输出即判定卡死，主动杀死挂起的流并重试）。可推广为：**每个长连接都需要活性信号，而非仅依赖连接超时**。完整性监控针对轨迹结构：发现工具调用缺少配对结果消息时，在注入上下文前自动修复配对，而不是把结构异常抛给模型或用户。产品模式可用占位符宽容修补，训练数据收集模式则拒绝修复——合成占位符会污染训练数据。\n\n**恢复：分级升级，逐级透明。** 能用低级别解决就不升级：\n\n1. **静默重试**——可重试错误的默认动作。指数退避叠加随机抖动（避免客户端同步重试造成二次拥塞，尊重服务端的等待时长提示）；区分前台与后台调用：主循环失败要重试，标题生成、输入建议这类辅助性后台调用失败直接放弃，否则后台重试挤占主链路配额，形成\"重试放大\"。\n2. **降级与接续**——重试无效时改变请求本身。输出触顶：先静默提升输出上限重发，仍不够再在消息末尾追加元指令让模型从断点接续；主模型过载时降级到备用模型（先剥离旧模型私有格式块，否则新模型解析不了历史）；高成本模式被限流时暂时回落到标准模式。\n3. **暴露给用户**——所有自动手段用尽后才呈现错误，并附上已尝试过的恢复动作。\n\n**工具层错误走另一条路：不终止会话，把错误变成模型的输入。** 幻觉调用收到\"工具不存在\"的结构化错误结果；参数校验失败收到附带输入约束提示的错误；畸形参数（该是对象却输出字符串）在执行前先程序化修复。错误以普通工具结果身份进入上下文，由模型下一轮自行纠正——喂回的错误越具体，自我纠正成功率越高。\n\n**错误处理的边界不是单次请求，而是整个恢复循环。** 在确认无法恢复之前，中间错误不暴露给消费者（用户或订阅事件的下游系统）：恢复期间扣留错误消息，恢复成功则消费者毫无感知，所有手段均失败后才统一呈现。\n\n**跨厂商接管：带走文字，带不走凭证。** 换一家模型把轨迹接着跑完，真正的障碍不是接口地址，而是轨迹里有只属于原厂商的东西。工具调用与结果各家结构不同但语义一致，重新渲染即可；难办的是思考——它由可读文字和厂商凭证（证明这段思考出自它自己）构成，文字换一家仍读得懂，凭证换一家就失效。且凭证未必附在思考上，也可能附在工具调用上（如 Google 的 thoughtSignature），所以\"把思考删干净就安全\"反而会在严格校验的厂商处失败。接管方案按最严格的一端设计：把历史工具调用改写成文字叙述，模型不再当作真正调用过，但至少能接着跑。由此得到设计原则：**轨迹按中立格式存储**——思考拆成可移植文字与不可移植凭证两个槽位，工具调用只记名称与参数，标识符渲染成具体请求时按目标厂商重新生成；切换时凭证一律丢弃，文字以普通内容身份带入。中立轨迹还服务于评估重放、训练样本构造、经验提取。\n\n**终止：每条恢复路径都要有上限。** 恢复机制本身也可能失效：上下文压缩连续失败若干次就放弃压缩，权限分类连续失败就回退人工询问，输出接续最多固定轮数。阈值来自生产数据而非拍脑袋——Claude Code 的\"连续 3 次\"压缩熔断阈值来自真实会话统计（曾有会话连续失败三千余次，仅此一类无效重试每天全球浪费约 25 万次 API 调用；3 次是\"绝大多数故障此前已恢复\"与\"继续重试基本无望\"之间的经验拐点）。\n\n**死亡螺旋防护。** 错误处理路径中的逻辑本身又调用 LLM，再次出错引发连锁。真实案例：上下文溢出触发\"结束时自动提交代码\"钩子，钩子调 LLM 生成 commit message 再次溢出，又一次触发钩子。防护两条：错误路径上禁用一切会再次调用模型的副作用逻辑（宁可丢掉自动记忆提取之类的辅助功能），以及用递归深度计数器检测并打断残余连锁。最后叠加全局终止条件：最大迭代轮数、会话预算上限、连续失败超阈值升级人工。\n\n**流式中断的三个断点、三种恢复方式。** 断点可能出现在：思考中途、正文中途、工具调用参数中途。恢复方式：① 丢弃半截内容整轮重发（最贵但最稳）；② 把半截内容作为末尾 assistant 消息要求模型接着写（部分厂商原生支持，其余需显式标注待续写消息，没有该接口则退回下一种）；③ 追加一条元指令说明从断点继续。注意：半截的工具调用无法以原生结构回传，需先转成文字再让模型补完，拼接后重新解析校验；若半截输出里已有工具因流式提前执行，续写前按调用指纹去重，避免重复副作用；拼接处容易多出空白或重复字符——参数合法不等于语义正确。\n\n## 实践模式\n\n**建一张错误 → 策略映射表**（比\"出错就重试\"的根本改进）：\n\n1. 捕获异常 → 归入 API/工具/上下文/控制流四层之一\n2. 可重试？→ 指数退避 + 抖动静默重试（前台重试、后台放弃）\n3. 改变请求可救？→ 提升输出上限 / 追加接续元指令 / 降级备用模型 / 回落标准模式\n4. 工具层错误 → 结构化错误结果喂回上下文，让模型下轮自我纠正\n5. 持续失败 → 查恢复路径的连续失败计数器，超阈值熔断（阈值从生产日志统计得出）\n6. 全部失败 → 统一向用户暴露，附已尝试的恢复动作清单\n\n**流式恢复实现清单**：记录断点类型（思考/正文/参数）；半截工具调用转文字 + 指纹去重；拼接后重新解析校验参数；对比三种方式的 token 成本与恢复成功率，选默认路径。\n\n**接管实现清单**：轨迹存中立格式（文字/凭证分离）；渲染层按目标厂商重组；凭证一律丢弃；遇强制凭证校验的厂商，历史调用改写为文字叙述；切换后监控重复调用指纹。\n\n## 常见陷阱\n- 笼统\"出错就重试\"：不可重试的错误（参数不合法、权限不足）重试多少次都一样\n- 只依赖连接超时：静默卡死（连接通但无数据）检测不到，必须配空闲看门狗\n- 后台辅助调用也重试：重试放大挤占主链路配额\n- 恢复期间把中间错误暴露给用户或下游事件订阅者\n- 没有熔断上限：一条恢复路径连续失败三千次，白白烧掉海量 API 调用\n- 错误处理路径自身调用 LLM：死亡螺旋，连锁故障\n- 以为删掉思考就安全跨厂商接管：凭证可能挂在工具调用上\n- 续写半截输出不按调用指纹去重：已执行的工具产生重复副作用\n- 训练数据收集模式用占位符修补缺失消息：污染训练数据\n\n## 配套代码\n- `chapter5/provider-failover/` — 实验 5-1/5-2：中立轨迹格式实现跨厂商接管（直传/剥离/中立三臂对照）与流式三断点接续\n- `chapter5/log-diagnosis/` — 诊断 Agent 读轨迹定位根因、生成回归测试、真实重放验证并建 Issue 的完整闭环\n- `chapter5/adaptive-log-parser/` — 自愈循环示范：解析失败不报错，而是把失败样本交给 Agent 生成代码、测试、热更新\n\n## 深度阅读\n- `book/chapter5.md`「故障与错误恢复」\n- `book/chapter5.md`「Coding Agent」→「实现技巧」（并行工具调用、流式执行与级联中止）\n- `book/chapter1.md`「Harness 工程：模型之外的竞争力」（纠正机制与\"不暴露中间态\"原则）\n\n<!-- File: skills/eval-dataset-design/SKILL.md (Tokens: ~4056 | Category: anthropic-skill) -->\n---\nname: eval-dataset-design\ndescription: 设计 Agent 评估数据集或单条评估任务时使用——解剖评估任务的四个组成部分、设计验证器与验收标准（含防敷衍性修复）、划分任务难度与陷阱任务、防范训练/评估数据泄漏（参数化实例、canary）、建设评估集的质量控制与长期维护、选择公开基准/自建业务集/生产轨迹回流三个来源。覆盖 τ²-bench、SWE-bench、AndroidWorld、OSWorld、Terminal-Bench、GAIA 的可迁移设计手法。\n---\n\n# 评估数据集设计\n\n## 何时使用\n- 从零设计评估集，或评审现有任务定义是否站得住\n- 为 Agent 编写单条评估任务：工单、用户模拟规范、初始状态、验收标准\n- 设计验证器：该断言终态、断言动作，还是检查必须告知用户的信息\n- 评估任务被模型\"猜答案\"蒙过，需要提高信噪比\n- 怀疑评估集已被污染/泄漏进训练数据，需要防泄漏与检测手段\n- 决定自建评估集的任务从哪来：公开基准、业务集、还是生产失败回流\n- 评估集上线后需要长期维护：修补环境、描述、验证逻辑与初始状态问题\n\n## 核心原则\n- **一条评估任务 = 四个部分**：给 Agent 的工单、给模拟器的行为规范、两侧状态的初始重置、成功判定标准。缺任何一部分，任务都无法重复运行。\n- **把用户的认知边界建模为独立字段，而非靠提示词约束。** 用户不知晓的信息 Agent 无从推测，只能通过提问与引导获得——渐进式信息透露不是一句\"不要一次说完\"，而是 `known_info` 与 `task_instructions` 的拆分。\n- **没有事实锚定的用户模拟器会让评估退化为两个模型相互确认。** 模拟用户关于环境状态的任何回答都必须以工具返回为依据，不许编造工具结果；否则 Agent 稍加引导，用户就确认\"问题已解决\"。\n- **验证器必须核实机器可独立复核的事实，不能采信 Agent 的自我陈述。** Agent 很容易写一篇\"任务已全部完成\"的报告而实际什么都没做。\n- **训练集与评估集严格隔离。** 答案不可从互联网直接检索、任务实例参数化生成、嵌入 canary 使泄漏可检测——三招至少用一招。\n- **验收口径要有可核实的边界，防\"敷衍性修复\"。** \"网络已恢复\"不可核实；\"测速评级 excellent 才算解决，poor/fair/good 均不接受\"才堵得住压制症状、不除根因的糊弄。\n- **高质量的评估集是修出来的，不是写出来的。** 主流基准的现行形态都是初版暴露问题后逐轮修补的结果；发布前人工淘汰、发布后持续修两类问题都要预算。\n- **每道题亲手做一遍。** 做完问两个问题：描述是否有多种合理解释，验证器认可哪一种？蒙混过关的最低成本路径是什么，验证器拦得住吗？\n- **难度分层让评估集不过时**，且每层失败指向不同改进方向：基础层失败指向工具使用，中间层指向多步规划，最高层指向长序列思考。\n\n## 实践模式\n\n### 1. 任务解剖：四件套字段清单\n以 τ²-bench telecom 一条真实任务为范本，逐项对照自建任务：\n- **ticket（给 Agent 的工单）**：只含用户会主动说出的部分。真实用户的初始表述往往只是\"我上不了网\"，把需求澄清到可执行的程度本身就是 Agent 必须具备的能力。\n- **user_scenario（给模拟器的行为规范）**：`known_info` 界定用户知悉范围（姓名、号码、所在国），故障原因不在其中；`task_instructions` 规定透露方式，并包含三类约束——情绪设定（首次修复失败后表现不满）、验收口径（仅 excellent 算解决）、事实锚定（设备状态回答必须基于工具结果）。\n- **initial_state（初始重置）**：`initialization_actions` 把两侧状态重置到同一起点，包括用户侧（飞行模式、漫游开关）与 Agent 侧（运营商侧配置）。\n- **evaluation_criteria（成功判定）**：四个可检查维度按需组合，外加聚合规则。\n\n### 2. 四维校验与聚合规则\n- `env_assertions` 验**终态**：移动数据可用、测速达 200 Mbps 且评级 excellent。\n- `actions` 验**关键动作是否发生**（哪些工具被哪一侧调用）。\n- `communicate_info` / `nl_assertions` 验**必要信息是否已告知用户**——别只查环境状态。\n- `reward_basis` 是聚合规则。二元奖励（只看终态）以过程颗粒度换取跨模型可比的单一数字：满分轨迹里违反\"一次只做一个工具调用\"的政策也不会被捕获。生产评估系统需要更多：不仅判对错，还要指出问题出在哪。\n\n### 3. 验证器设计的三种模式\n- **双命题验证**（SWE-bench Verified）：FAIL_TO_PASS（修复前失败、修复后通过，证明问题确已解决）+ PASS_TO_PASS（修复前后均通过，证明未引入新缺陷）。只验前者，Agent 可以删改妨碍通过的断言蒙混；只验后者等于未检验。另需排除自身不稳定的 flaky test。\n- **深状态核查**（OSWorld 式）：134 个独立评估函数，拥有完整系统访问权限，查文件系统结构、进程状态、网络连接与应用内部状态；数据库任务连库核实 SQL 是否真执行，浏览器任务分析 DOM、cookie 与 localStorage 并向后端发验证请求——能抓住\"表面完成、实质错误\"。\n- **不可伪造执行**（Terminal-Bench 式）：成功标准是真实构建并运行（如从源码构建内核并在 QEMU 启动日志出现自定义 printk），Agent 无法伪造输出，只能真做完全流程。\n\n### 4. 难度划分与陷阱任务\n- 分层标注并用于诊断：GAIA 466 题分三级——Level 1 只需一至两个工具（人类 93.9%，早期模型 30.3%），Level 2 多步思考，Level 3 复杂组合。Level 1 失败指向基础工具使用，Level 2 指向多步规划与信息整合，Level 3 指向长序列思考与复杂性管理，改进方向各不相同。\n- **陷阱任务**检验压力与误导下的判断力：用户声称\"客服已批准取消\"，实际并不符合政策，看 Agent 是否维持正确判断。\n- 任务集覆盖从易到难的全谱，模型能力提升时评估集不会快速过时。\n\n### 5. 数据泄漏防范\n- **组合多源 + 专有附件 + 精确匹配**（GAIA 式）：答案必须组合多个信息源才能得出，单一网页无法直接给出；部分任务配互联网上不存在的 PDF/音频/图片附件；用精确字符串匹配判定。\n- **参数化模板实例化**（AndroidWorld 式）：任务是\"将联系人 X 的电话改为 Y\"这类模板，每次评估随机生成参数。三收益：回放固定操作序列失效；单模板可生成近乎无限实例；固定部分参数、只改其余，可精确测量特定因素的影响。\n- **金丝雀标识符**（Terminal-Bench 式）：题面嵌入 canary GUID，模型能输出含该 GUID 的内容即说明基准已进训练集。它不阻止泄漏，但使泄漏可被检测。\n\n### 6. 质量控制与长期维护\n- **发布前人工淘汰**：SWE-bench Verified 从 2294 个原始任务抽 1699 个，93 名精通 Python 的开发者逐条检查（描述是否清晰、测试是否覆盖边界、是否稳定、参考 patch 是否引入新错误、难度是否合理），仅 500 个通过——淘汰 71% 换来更高信噪比，评估成本下降约 80%。复杂 Agent 任务动辄数分钟至数小时，前沿模型跑完一个评估集往往需要数千美元 token，控本就是控迭代速度。\n- **发布后持续修补**：OSWorld 发布 15 个月暴露出 300 余个问题，分四类——环境问题（反爬、CAPTCHA、动态内容，靠锁定版本与离线备份）、任务描述歧义（改写消除）、验证逻辑过严或过松（人工建立正确基线再调条件）、初始状态不完整（增加完整性校验）。修补方式可整体借鉴。\n- **从初版到成熟版的五处典型重设计**（τ-bench → τ²-bench）：任务指令过于笼统导致可猜 → 拆分 known_info/task_instructions；成功条件不精确 → 改为可核实边界；模拟用户过于机械 → 补情绪、耐心上限与事实锚定；只有 Agent 能改变环境 → 引入用户侧工具的双控机制；静态任务 → 参数化批量生成实例（同时改善覆盖率与抗泄漏）。\n\n### 7. 评估集的三个来源与演进\n- **公开基准**：用于粗筛模型与借鉴设计手法（验证深度、参数化生成、防泄漏、质量维护），一般不用于产品决策——其任务分布与业务分布不一致。\n- **自建业务集**：覆盖真实任务分布，作为模型选型与 Harness 设计决策的依据。可拿成熟基准当骨架，替换领域数据与工具集。\n- **生产轨迹回流**：用户明确纠正、点踩、事后规则/LLM 审计发现的失败案例，经失败归因后沉淀为回归用例。成本最高、准确性最高，直接来自用户实际遇到的问题。\n- 演进节奏：起步只有公开基准 + 少量手写业务集；上线运行一段时间后，回流用例成为主体。今天线上暴露的失败模式，明天就是守住底线的回归用例。\n\n## 常见陷阱\n- 任务指令写得宽泛，模型无需澄清需求、凭常识猜一套流程也能通过。\n- 成功条件是\"网络已恢复\"这类无边界描述，被压制症状的敷衍性修复蒙过。\n- 只验 FAIL_TO_PASS 不验 PASS_TO_PASS，Agent 靠删断言作弊；或不排除 flaky test，结果不可复现。\n- 用户模拟器没有事实锚定，评估退化为 Agent 与模拟用户相互确认；没有耐心上限，沟通效率低下不被计失败。\n- 静态题面被模型记忆，且无 canary，泄漏发生了都不知道。\n- 验证器过严（把正确答案判失败）或过松（放走表面完成实质错误）；初始状态配置不完整，每次运行起点不同。\n- `reward_basis` 只看终态，过程违规（策略违背、信息未告知）不被捕获，且不另建过程检查。\n- 任务描述存在多种合理解释而验证器只认一种，开发者与人肉执行者的判断不一致。\n- 评估集建成后不再维护，上线后仍是手写那几十条，与真实用户分布脱节。\n\n## 配套代码\n- `chapter7/tau2-bench-eval/` — τ²-bench telecom 任务定义四部分（ticket / user_scenario / initial_state / evaluation_criteria）的完整解剖与双控环境运行记录\n- `chapter7/public-health-reporting-eval/` — 五个确定性任务的六点结构化评分示范验证器设计：工具选择、参数、答案（含数值容差）、证据行精确集合、无依据声明处罚\n- `chapter7/android-world/` — T3A 失败轨迹与归因笔记，演示参数化任务实例、验证器终态判定，以及从失败轨迹回流生成轨迹前缀回归任务\n\n## 深度阅读\n- `book/chapter7.md`「一条评估任务的解剖：τ²-bench 的 telecom 领域」\n- `book/chapter7.md`「评估数据集的设计」\n\n<!-- File: skills/knowledge-org/SKILL.md (Tokens: ~300 | Category: anthropic-skill) -->\n# knowledge-org\n\nPath: `skills/knowledge-org/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/knowledge-org/SKILL.md)\n\n<!-- File: skills/kv-cache-design/SKILL.md (Tokens: ~300 | Category: anthropic-skill) -->\n# kv-cache-design\n\nPath: `skills/kv-cache-design/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/kv-cache-design/SKILL.md)\n\n<!-- File: skills/loop-engineering/SKILL.md (Tokens: ~300 | Category: anthropic-skill) -->\n# loop-engineering\n\nPath: `skills/loop-engineering/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/loop-engineering/SKILL.md)\n\n<!-- File: skills/mcp-skill-hub/SKILL.md (Tokens: ~300 | Category: anthropic-skill) -->\n# mcp-skill-hub\n\nPath: `skills/mcp-skill-hub/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/mcp-skill-hub/SKILL.md)\n\n<!-- File: skills/memory-system/SKILL.md (Tokens: ~300 | Category: anthropic-skill) -->\n# memory-system\n\nPath: `skills/memory-system/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/memory-system/SKILL.md)\n\n<!-- File: skills/multi-agent-design/SKILL.md (Tokens: ~300 | Category: anthropic-skill) -->\n# multi-agent-design\n\nPath: `skills/multi-agent-design/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/multi-agent-design/SKILL.md)\n\n<!-- File: skills/post-training-strategy/SKILL.md (Tokens: ~300 | Category: anthropic-skill) -->\n# post-training-strategy\n\nPath: `skills/post-training-strategy/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/post-training-strategy/SKILL.md)\n\n<!-- File: skills/rag-pipeline/SKILL.md (Tokens: ~300 | Category: anthropic-skill) -->\n# rag-pipeline\n\nPath: `skills/rag-pipeline/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/rag-pipeline/SKILL.md)\n\n<!-- File: skills/README.md (Tokens: ~300 | Category: anthropic-skill) -->\n# Skills Skill\n\nPath: `skills/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/README.md)\n\n<!-- File: skills/reward-design/SKILL.md (Tokens: ~300 | Category: anthropic-skill) -->\n# reward-design\n\nPath: `skills/reward-design/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/bojieli/ai-agent-book/HEAD/skills/reward-design/SKILL.md)\n\n<!-- ... +6 more modular skills available via /api/skills/bojieli/ai-agent-book?path={path} -->\n</yakaai_skills>"}