ai-agent-book

为 Agent 建立或改进评估体系时使用——设计评估指标（Pass@k/Pass^k/成本）、搭建可重复运行的评估环境、选择确定性验证器或 LLM-as-a-Judge 及各自适用边界、编写 Rubric、做失败归因与回归任务、评估驱动的模型选型、判断统计显著性、建设可观测性与内部评估基础设施（消融、AB 测试、特性开关、提示词回归）、从 Benchmark 报告走到系统改进。

让 Agent 从运行经验中持续学习、构建自进化闭环时使用——涵盖从运行轨迹提取学习信号（三层轨迹验证）、四种进化方式（经验知识库、Prompt/Skill、程序/Harness、模型参数）的适用边界与选择依据、Prompt 自动优化、轨迹编译为程序、Agent 自我修改与安全门禁、睡眠学习与长期分层评估。触发词：持续进化、自进化、经验学习、轨迹验证器、自我修改、进化闭环。

Agent 陷入无限循环、数不清工具调用次数、遗忘 TODO 或目标偏离、长任务中思考 token 持续膨胀时使用——Agent 状态栏机制、作为 user 消息注入末尾的 KV Cache 理由、每轮替换与持久追加两种实现及成本模型、五种状态栏技术（时间戳、工具计数器、TODO、详细错误、系统状态）与维护铁律。

中文文案去「AI 味」检查清单，由用户纠正反馈持续提炼而来

构建异步/事件驱动 Agent，或让 Agent 响应外部事件（新邮件、webhook 回调、IM 消息、定时器、系统告警）、 处理工具执行期间的用户打断与多任务并发时使用。覆盖事件循环与安全点、三类事件触发工具、用户沟通与多渠道召回、 虚拟身份与隔离执行环境、队列式/取消式/并行式三种事件处理策略及紧急度判定，以及模型原生异步与同步接口兼容两条路线。 触发词：异步 Agent、事件驱动、event-driven、webhook、定时器、心跳、任务句柄、打断、steering、并行工具执行。

把生产 bad case / 失败轨迹转成训练数据时使用——从失败归因、轨迹前缀截取、DPO 偏好对构造、LoRA 训练到边界集与保留集双集验证的完整链路；也用于判断某类问题该走 SFT、DPO、RL 还是先修 Harness/工具/tokenizer，以及如何从运行轨迹中提取带证据的结构化学习信号。触发词：bad case、失败归因、DPO、偏好对、轨迹前缀、拒绝采样、过度矫正、边界集、保留集、过早结束、reward hacking、LoRA 微调、训练评估隔离。

编写并运行 Python 代码，验证脚本逻辑和输出。

搭建 Coding Agent 或设计 Agent 护栏时使用——当你要构建能自主读写代码、跑测试、自我纠错的编码 Agent，或为已有 Agent 系统补约束/验证/纠正机制、设计执行边界与验收基线、判断某类任务是否适合交给 Agent、优化 Harness 提示词与工具集时使用。覆盖 Harness 四组件、任务四象限、四条设计原则与业界实践。

构建 GUI 自动化 Agent、让 Agent 像人一样看屏幕并用鼠标键盘操作桌面或浏览器软件时使用。 覆盖感知-思考-行动循环、动作空间（GUI/bash/文件编辑）、视觉定位 Grounding 三条路线 （结构化元素索引、Set-of-Mark、纯坐标预测）、分辨率坐标缩放、关键帧观察接口、世界模型与移动端生态壁垒。 触发词：Computer Use、GUI 自动化、截图、Grounding、browser-use、Set-of-Mark、视觉定位、坐标缩放、OSWorld。

上下文膨胀、工具结果撑爆窗口、Agent 决策质量随轮次下降时使用——上下文压缩的三个动机（长度成本、思考质量、上下文焦虑）、压缩即检索的机制、六种压缩策略实测数据、生产级五层分层压缩、四条设计原则，以及用子 Agent 隔离代替压缩。

设计 Agent 系统提示词、上下文结构或按需加载的 Skill 时使用——覆盖 API 消息角色与「静态前缀 + 轨迹」结构、系统提示词写法（结构化、SOP、业务规则细化、few-shot）、Agent Skills 渐进式披露与 SKILL.md 编写、提示注入的上下文层防御，以及注意力位置偏好等布局原则。

基于已确认数据执行可审计的数学计算和描述统计。

排查或加固 Agent 故障恢复机制时使用——当 Agent 陷入无限循环、流式响应中途断开、上下文溢出、模型服务限流过载、需要跨厂商接管跑到一半的轨迹、设计重试与熔断策略、防止错误处理路径自身引发连锁故障时使用。覆盖四层故障分类、检测方法、分级恢复策略、熔断上限与流式中断恢复。

设计 Agent 评估数据集或单条评估任务时使用——解剖评估任务的四个组成部分、设计验证器与验收标准（含防敷衍性修复）、划分任务难度与陷阱任务、防范训练/评估数据泄漏（参数化实例、canary）、建设评估集的质量控制与长期维护、选择公开基准/自建业务集/生产轨迹回流三个来源。覆盖 τ²-bench、SWE-bench、AndroidWorld、OSWorld、Terminal-Bench、GAIA 的可迁移设计手法。

组织与检索超越扁平文本块的知识时使用——涵盖 RAPTOR/GraphRAG 结构化索引选型、OpenViking 文件系统范式与 L0/L1/L2 按需加载、增量更新 PR 审核流与定期整理、Agentic RAG 与安全边界、上下文感知检索、结构化数据知识发现，以及双层记忆架构。

优化 Agent 推理延迟与成本、诊断首 token 变慢或缓存命中率下降时使用——KV Cache 前缀不变性原则、三条铁律、五种破坏缓存的错误上下文管理模式、Chat Template 与历史思维链回传策略、缓存作为架构约束（缓存边界、子 Agent 字节级对齐、替换字符串冻结）。

构建或修复 Agent 迭代循环时使用——解决 Agent 过早宣称完成、活干到一半就停、假成功、循环停不下来等问题，设计验证器与终止条件，实现提议者-审核者（Proposer-Reviewer）双 Agent 循环。覆盖过早终止三种形态、验证器是循环瓶颈的原则、LoopX 持久控制面、LongHorizon-Harness 的 MEA 循环、提议者-审核者最小不变量（审核者读独立证据、退回给可定位修复条件）。

为 Agent 接入第三方能力时使用——决定走 MCP 协议还是 Skill Hub 分发、搭建或选用 MCP 服务器、设计工具/资源/提示三类原语、评估引入第三方能力的 token 成本与安全风险、审查工具描述投毒与同名工具遮蔽、锁定服务器版本与配置最小权限凭证时查阅。含 MCP 客户端-服务器架构、传输层选型与供应链缓解清单。

为 Agent 设计、实现或评估用户记忆系统时使用——涵盖记忆能力三层次评估框架、轨迹与长期记忆分层、Simple Notes 到 Advanced JSON Cards 及可执行代码的存储格式选型、Mem0/Memobase 框架取舍、记忆压缩整理与隐私脱敏，以及何时该用记忆而非 RAG 的判断。

设计或评审多 Agent 系统、判断该用单 Agent 还是多 Agent 时使用——选择对等/管理者/去中心化协作拓扑、决定上下文是否共享、设计 Agent 间通信与共享文件系统、诊断多 Agent 失败模式（并发冲突、错误级联、同质趋同、互相扯皮、循环失控）。覆盖协作架构选择依据、多 Agent 优于单 Agent 的新信息判据、控制平面四原语与虚拟文件系统四类区域的设计检查表。