Agent 工具数量变多、上下文被工具定义占满时使用——设计工具发现与渐进式披露机制、实现 discover_tools 元工具与两层语义路由、选择索引式/检索式/主动发现/Skills 方案、处理动态加载破坏 KV Cache 的问题、评估 token 成本与工具选择准确率时查阅。含渐进式加载五步流程、工具数量阈值与关键实验数据。
インストールする前に、エージェントに与えられる指示の中身を確認できます。
| 工具规模 | 推荐方案 |
|---|---|
| 十几个 | 全量注入，无需额外机制 |
| 几十个 | 只暴露索引，按需查定义 |
| 上百个 | 检索式预筛选（top-k 后注入） |
| 上百至上千 | 主动工具发现（元工具 + 两层语义路由）或 Skills 渐进式披露 |
| 上千 | Skills / Skill Hub；专用工具须另建索引层 |
层次化组织按信息源性质分类，并在系统提示词中显式说明，帮助 LLM 快速定位工具组：搜索工具（主动查找：网络/知识库/文件搜索）、读取工具（从已知位置提取：网页阅读、文档读取、DB 查询）、解析工具（处理非结构化数据：OCR、视频分析、音频转录）、查询工具（访问结构化数据源：天气、股票、公开数据库 API）。
name + description（数百 token），不注入完整 schema。<tool_request>server: GitHub for repository operations; tool: search repositories by keyword</tool_request>。系统提示词中只保留少数基础工具（web_search、code_interpreter）加一个 discover_tools 元工具。两层匹配候选相似度都低于阈值时，明确返回"未找到"，让 Agent 改写需求重试、用基础工具手工实现，或创造新工具。
| 策略 | 注入内容 | 适用 |
|---|---|---|
| 全量注入（all-tools） | 全部 N 个 schema，token 随目录规模线性增长 | 工具少的基线 |
| 检索预筛选（retrieval） | 按初始查询语义 top-k | 工具上百、需求可预估 |
| 主动发现（active） | Agent 迭代声明需求，上下文按需增长 | 工具上千、多步骤跨领域任务 |
实测（top-k=5）：全量注入 35 个工具 3,857 token，且 400 个工具时涨到 40,258 token；retrieval 恒为约 540-550 token 且 recall 保持 100%——按需选择把"选哪个工具"变成"查哪条资料"，且成本不随生态规模膨胀。
tool_search + defer_loading（要求后续请求保持 tool_search_output 项的原位置，同一工具无需重复加载）；Anthropic tool_reference（在会话历史原位置内联展开 block，官方文档明确后续每轮保持缓存命中）；Codex CLI 默认开启 tool_search。不需要嵌入索引、检索元工具、tool_search/tool_reference 这类基础设施。Agent 启动时只看到一份薄目录（每个 skill 的 name + description），当前上下文真的需要某种能力时，才读取对应 sub-skill，并顺着引用再往下读具体脚本或子文档。类比：没人会把工具书从第一页读到最后一页，而是顺着索引按需查词条。专用工具要达到同样的渐进式披露，必须在工具之外另建一层基础设施——这正是那些机制存在的理由。
实验 4-1 的做法（Qwen3-4B 面对 120+ 工具）：
web_search、code_interpreter、discover_tools；discover_tools 收自然语言需求，经嵌入相似度返回 3-5 个候选及完整 schema；新定义追加到对话历史，状态栏更新工具名列表；提示词引导模型在遇到能力缺口时主动调用 discover_tools。chapter4/active-tool-discovery/ — 在 126 个跨领域工具上对比全量注入 / 检索预筛选 / 主动发现；python demo.py --offline 跑通机制，run_exact_experiment.py 是正式实验入口。chapter4/active-tool-selection/ — MCP-Zero 风格教学实现：<tool_request> 结构化请求、服务器级→工具级两层语义路由、demo_comparison.py --offline 输出 recall/token/规模曲线。book/chapter4.md「工具太多怎么办：层次化组织与主动工具发现」まだレビューはありません。使ってみた感想をお寄せください。
概要と使いどころ
为 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 微调、训练评估隔离。
日本語の概要は準備中です。原文の説明を表示しています。