一、概述
注意：说明：
注意：默认情况下，工具是否走延迟加载由产品默认或 MCP 配置的 defer_loading 字段决定（详见 MCP 文档-延迟加载）。这些是全局生效的默认设置。本特性允许你在不改默认配置的前提下，针对单次会话或单个自定义代理临时调整行为。
二、1. 语法速览
在任何接受工具名的“工具列表”字段里，普通工具名前加修饰符：
| 写法 | 含义 |
| Read | 普通工具，按全局默认决定是否 defer |
| Defer(Glob) | 该会话/代理强制让 Glob 走延迟加载（不直接进入模型的工具列表，可通过 ToolSearch 发现） |
| NoDefer(Bash) | 该会话/代理强制让 Bash 不走延迟加载（直接进入模型的工具列表） |
| Defer(mcp__github__*) | 通配匹配，把整组 MCP 工具置为延迟加载 |
| Defer(*) | 把当前列表内的所有工具都置为延迟加载（极端裁剪） |
注意：说明：
注意：* 是唯一支持的通配字符，匹配任意字符序列。其他字符（?、[] 等）按字面量处理。
三、2. 可用渠道
修饰符可以写在以下三类“工具列表”字段中：
四、2.1 CLI –tools 参数
codebuddy –tools "Read,Defer(Glob),NoDefer(Bash)"
ACP 与 SDK 客户端的 tools 字段与 CLI 等价。
五、2.2 自定义代理 frontmatter
在 .codebuddy/agents/*.md 的 YAML frontmatter 里：
—name: code-readerdescription: 只读型代码探索代理tools: – Read – Grep – Defer(Glob) # 让 Glob 走延迟加载，需要时通过 ToolSearch 发现 – NoDefer(Bash) # 即便默认让 Bash 延迟加载，本代理也强制不延迟—
详见 子代理-配置字段。
六、3. 修饰符不能用在哪里
修饰符仅作用于“工具列表”字段。以下“权限规则”字段不接受修饰符：
·–allowed-tools / settings.permissions.allow
·–disallowed-tools / settings.permissions.deny
·hooks 配置中的 matcher
# ✖ 错误：会立即报错codebuddy –allowed-tools "Defer(Glob)"# Error: Defer(…) / NoDefer(…) modifiers belong in –tools, not in permission rule fields.# ✔ 正确：分开写codebuddy –tools "…,Defer(Glob)" –allowed-tools "Glob(src/**)"
理由：“暴露策略”（是否走延迟加载）与“行为约束”（参数过滤）是两件正交的事，分开表达更清晰。
七、4. 优先级与合并
最终决策按以下优先级（从高到低）：
| 优先级 | 来源 | 说明 |
| 0a | 任一层 NoDefer(X) 命中 | 强制非 defer（无论其他来源说什么） |
| 0b | 任一层 Defer(X) 命中 | 强制 defer |
| 1 | MCP 工具级 tools[name].defer_loading | MCP 静态配置 |
| 2 | MCP 服务器级 defer_loading | MCP 静态配置 |
| 3 | 环境变量 CODEBUDDY_DEFER_TOOL_LOADING | 全局开关 |
| 4 | 用户设置 settings.deferToolLoading | 全局开关 |
| 5 | 内置默认（CodeBuddy Code 出厂配置） | 兜底 |
八、关键规则
·NoDefer 永远胜过 Defer：即使自定义代理写了 Defer(X)，CLI –tools 写 NoDefer(X) 后，本次会话内 X 仍然不延迟加载——用户运行时表态优先。
·CLI 与代理配置平等参与：两个来源的修饰符按并集生效，不分先后；最终结果由“NoDefer 优先”这一条规则裁决。
·同名重复：同一字段中多次出现同一工具时，最后一次出现的修饰符胜出（与 –allowedTools 重复时的语义一致）。
九、5. 自动附加：ToolSearch 与 DeferExecuteTool
只要工具列表里出现了至少一条 Defer(…)，CodeBuddy Code 会自动把以下两个工具加进去（如果还没在列表里）：
| 工具 | 作用 |
| ToolSearch | 让模型能搜索发现被延迟加载的工具 |
| DeferExecuteTool | 让模型实际调用被延迟加载的工具 |
也就是说，你可以这样写：
# 等价于 codebuddy –tools "Bash,Read,Defer(Edit),ToolSearch,DeferExecuteTool"codebuddy –tools "Bash,Read,Defer(Edit)"
十、为什么自动附加
延迟加载的工具不直接进入模型的工具列表，模型必须通过 ToolSearch 发现并通过 DeferExecuteTool 调用。少了任意一个，Defer(…) 就成了"模型再也用不到这个工具"。自动附加让最常见的写法符合直觉。
十一、通配护栏：Defer(*) 不会卷走自身
写 Defer(*) 时，理论上"所有工具"都会被延迟加载——包括 ToolSearch 和 DeferExecuteTool 自身，从而让 defer 工作流失效。为避免这种"自我封死"，自动附加会同时给这两个工具加上 NoDefer 护栏：
codebuddy –tools "Defer(*)"# 行为等价于:# codebuddy –tools "*,ToolSearch,DeferExecuteTool" + NoDefer(ToolSearch),NoDefer(DeferExecuteTool)
模型仍能看到并使用 ToolSearch / DeferExecuteTool，从而能搜索并调用其他被延迟加载的工具。
十二、不会触发自动附加的情形
·工具列表里只有 NoDefer(…)、没有 Defer(…)：用户意图是把工具拉回直接调用，与 defer 工作流无关
·工具列表里没有任何修饰符：保持原有行为
·用户已显式列出 ToolSearch 或 DeferExecuteTool：幂等，不重复添加
十四、6.1 临时把工具收进延迟加载，省 token
# 知道这次只用 Read/Edit，把其他大型工具暂时收起来codebuddy –tools "Read,Edit,Defer(Bash),Defer(Glob),Defer(Grep)"
模型上下文里只看到 Read、Edit、ToolSearch，需要时再通过 ToolSearch 调出其他工具。
十五、6.2 临时强制让被 defer 的工具直接可用
# 假设 Bash 默认被配为延迟加载，但本次需要它直接可调用codebuddy –tools "default,NoDefer(Bash)"
注意：说明：
注意：default 表示“全部内置工具”，与修饰符可同时使用。
十六、6.3 自定义代理的精细化暴露策略
—name: explorerdescription: 大型仓库探索专用代理，把搜索类工具收起来减少干扰tools: – Read – Edit – ToolSearch – Defer(Glob) – Defer(Grep) – Defer(LSP)—
十七、6.4 整组 MCP 工具按需暴露
codebuddy –tools "default,Defer(mcp__github__*)"
把 GitHub MCP 服务器的所有工具收进延迟加载，需要时模型通过 ToolSearch 搜索 github pr、github issue 等关键词找到。
十九、7.1 写错语法
Error: Invalid –tools value: Invalid tool spec "Defer(Read(*.md))": Defer(…) only accepts a tool name or glob; permission filters like Read(*.md) belong in –allowed-tools, not –tools.
把参数过滤搬到 –allowed-tools：
codebuddy –tools "Defer(Read)" –allowed-tools "Read(*.md)"
20、7.2 修饰符写到了错误的字段
Error: Invalid permission rule "Defer(Glob)" in –allowed-tools / settings.permissions.allow: Defer(…) / NoDefer(…) modifiers belong in –tools, not in permission rule fields.
见 3. 修饰符不能用在哪里。
21、7.3 嵌套 / 空内容
·Defer(NoDefer(X))：嵌套修饰被拒，无意义语义
·Defer()：空内容被拒
·defer(Read)：小写不识别，按字面量“含括号的工具名”拒绝
22、7.4 在自定义代理里出现拼写错误
自定义代理 frontmatter 中的 tools 字段使用宽松校验：单条非法写法只会发出警告日志后被忽略，不会让 CodeBuddy Code 启动失败。从日志中查找形如下面的提示来定位：
[AgentToolSpec] my-agent: invalid-pattern — Invalid tool spec "Defer(Read(*.md))": …
CLI 与 ACP 客户端直接输入的 –tools 使用严格校验，遇到非法写法会立刻报错。
23、8. 与“权限规则”的协作
修饰符与 –allowed-tools 完全正交，可以同时使用：
codebuddy \\ –tools "Read,Write,Defer(Glob)" \\ –allowed-tools "Glob(src/**)"
含义：
·Glob 走延迟加载（不直接进入模型的工具列表）
·当模型通过 ToolSearch > DeferExecuteTool 调用 Glob 时，仍受 Glob(src/**) 权限约束
·调用 Glob(/etc/*) 会按权限规则被拒绝
24、9. 与 ToolSearch / DeferExecuteTool 的交互
修饰符直接影响这两个工具的行为：
| 修饰 | 对 ToolSearch 的影响 | 对 DeferExecuteTool 的影响 |
| Defer(X)（X 原本不延迟加载） | 首次访问时自动加入可被搜索的延迟工具集合 | 首次调用时自动注册并放行 |
| NoDefer(X)（X 原本延迟加载） | 不会出现在搜索结果中（X 已直接进入模型的工具列表，无需搜索） | 调用 X 时返回错误，引导直接调用 |
报错示例（NoDefer 路径）：
Error: Tool "Bash" is not deferred in this session (NoDefer modifier). Call it directly instead of via DeferExecuteTool.
25、10. 已知边界
·MCP 服务器整体名：暂不支持在 –tools 里直接以服务器名作为修饰目标，只能写工具名或通配（如 Defer(mcp__github__*)）
·通配反向枚举：Defer(mcp__*) 等通配条目无法反向枚举具体工具名，MCP 工具的懒索引仍依赖 mcp-server-manager 自身的异步驱动流程