@tencent-ai/agent-sdk 0.3.210 → 0.3.212

package/cli/dist/web-ui/docs/cn/cli/settings.md

@@ -65,6 +65,8 @@ CodeBuddy Code 使用分层配置系统，让您能够在不同级别进行个
 | `disableAllHooks` | 禁用所有 [hooks](hooks.md) | `true` |
 | `allowUntrustedFrontmatterHooks` | 是否允许执行来自**非 product 内置**来源的 agent/skill 的 frontmatter `hooks` 字段（包括用户本地 `.codebuddy/agents\|skills/*.md` 和插件市场）。默认 `false`，防止不可信的 md 文件静默启动 shell 命令；只有 product 内置 agent/skill 不受影响。 | `true` |
 | `model` | 覆盖 CodeBuddy Code 使用的默认模型 | `"gpt-5"` |
+| `subagents` | 按内置子代理粒度指定模型。结构为 `{"agents": {"<子代理名>": {"model": "..."}}}`（`agents` 的 key = 子代理名，如 `Explore`；`model` = 模型 ID / 别名 / 变体 `lite`\|`reasoning` / `inherit`）。各子代理互不影响，支持全局 + 项目双 scope。可在 `/agents` 面板可视化编辑。优先级：env `CODEBUDDY_CODE_SUBAGENT_MODEL`（一刀切）> 项目 > 全局 > 内置默认 > 继承主模型。详见 [子代理文档](sub-agents.md) | `{"agents": {"Explore": {"model": "gpt-5.1-codex"}, "general-purpose": {"model": "claude-opus-4"}}}` |
+| `variantModels` | 通用场景变体 → 模型 的映射（key = `lite`\|`reasoning`；value = 模型 ID / 别名）。影响所有走该变体的逻辑（如 `Explore` 等声明 `lite` 的子代理）。可在 `/model` 面板的「场景变体区」编辑。优先级：env（`CODEBUDDY_SMALL_FAST_MODEL` / `CODEBUDDY_BIG_SLOW_MODEL`，按变体）> 项目 > 全局 > 模型级 `relatedModels` > 主模型兜底 | `{"lite": "gpt-5.1-codex-lite", "reasoning": "gpt-5.5"}` |
 | `agent` | 覆盖主线程使用的 agent 名称（内置或自定义 agent），应用该 agent 的 system prompt、工具限制和模型配置。优先级：`product.json default` → `plugin agent` → `settings.json agent` → `CLI --agent` | `"my-reviewer"` |
 | `statusLine` | 配置自定义状态行以显示上下文。见 [statusLine 文档](#状态行配置） | `{"type": "command", "command": "~/.codebuddy/statusline.sh"}` |
 | `enableAllProjectMcpServers` | 自动批准项目 `.mcp.json` 文件中定义的所有 MCP 服务器 | `false` |

package/cli/dist/web-ui/docs/cn/cli/sub-agents.md

@@ -175,6 +175,44 @@ codebuddy --agents '{
 * 查看存在重复项时哪些子代理处于活动状态
 * **管理工具权限**，包含所有可用工具的完整列表
 
+### 为内置子代理配置模型（per-Agent 模型）
+
+内置子代理（如 `Explore`、`general-purpose`、`Plan`）也可以**按子代理粒度独立指定模型**，各子代理互不影响、可自由组合。这解决了以往「只能通过环境变量一刀切、无法区分」的痛点。
+
+**在 `/agents` 面板可视化配置**：
+
+1. 运行 `/agents`，用 `↑/↓` 选中一个内置子代理，按 `Enter` 进入其动作菜单。
+2. 选 **Edit Model**，进入模型选择器：
+   * 首项 **Inherit / Default** —— 清除该子代理的配置，回落默认编排。
+   * 通用场景变体 `lite` / `reasoning`。
+   * 全部可用模型（与 `/model` 一致）。
+3. 用 `Tab` 在 **Global（全局）** 与 **Project（项目）** 两个保存范围间切换，`Enter` 确认。
+4. 列表即时刷新为「生效模型 + 来源」。
+
+面板的 **SOURCE** 列展示每个子代理当前生效模型的来源，让默认编排透明化：
+
+| 来源标签 | 含义 |
+|---|---|
+| `env-global` | 环境变量 `CODEBUDDY_CODE_SUBAGENT_MODEL` 一刀切接管（见下方优先级） |
+| `settings-project` | 项目级配置（`.codebuddy/settings.json`） |
+| `settings-user` | 全局级配置（`~/.codebuddy/settings.json`） |
+| `product-default` | 内置默认声明（如 `Explore` = `lite`） |
+| `inherit` | 无任何声明，继承主对话模型 |
+| `fallback-main` | 配置的模型被禁用/本地未知，降级回主对话模型 |
+
+**配置存储**：写入 settings 的 `subagents.agents.<子代理名>.model` 字段（`agents` 的 key = 子代理名，`model` = 模型 ID / 别名 / 变体 / `inherit`）。也可手动编辑 `settings.json`，详见 [设置文档](settings.md)。
+
+**优先级（从高到低）**：
+
+1. 环境变量 `CODEBUDDY_CODE_SUBAGENT_MODEL`（**一刀切**，对所有子代理统一生效，最高）
+2. 本次调用的工具入参（`default` / `lite` / `reasoning`，单次生效）
+3. **项目级** `subagents.agents.<子代理名>.model`
+4. **全局级** `subagents.agents.<子代理名>.model`
+5. 内置默认声明（`product.json` 的 `agents[].models[0]`，如 `Explore` = `lite`）
+6. 继承主对话模型（兜底）
+
+> **说明**：设置了 `CODEBUDDY_CODE_SUBAGENT_MODEL` 时，面板仍允许保存 per-Agent 配置（不报错），但会显示「被环境变量统一覆盖」的提示；取消该环境变量后 per-Agent 配置恢复生效。
+
 ### 直接文件管理
 
 您也可以通过直接处理子代理的文件来管理它们：