@tencent-ai/codebuddy-code 2.125.4-next.41bad82.202607231203 → 2.126.0

package/dist/web-ui/docs/cn/cli/agent-teams.md

@@ -116,6 +116,12 @@ CodeBuddy 会根据任务自动决定生成多少成员，也可以明确指定
 创建一个 4 人团队并行重构这些模块，每个成员使用 lite 模型。
 ```
 
+团队成员与普通子代理使用相同的模型解析规则，并按 `subagent_type` 匹配持久化配置：
+
+- 提示词中明确指定的模型属于本次调用设置，仍可被 `CODEBUDDY_CODE_SUBAGENT_MODEL` 统一覆盖。
+- 未明确指定模型时，系统依次考虑项目级和用户全局的按子代理设置、内置声明，最后继承团队领导的主模型。
+- 使用 `/agents` 管理按子代理设置，使用 `/model` 管理 `lite` / `reasoning` 对应的具体模型。
+
 ### 要求成员在实施前提交计划
 
 对于复杂或高风险的任务，可以要求成员在实施前先提交计划：

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

@@ -43,6 +43,7 @@
 | `--tools`                        | 限制可用的内置工具集（白名单）。空字符串 `""` 禁用所有内置工具，`"default"` 使用全部工具，或指定逗号分隔的工具名。支持 `Defer(X)` / `NoDefer(X)` 修饰符按需调整工具的延迟加载状态，详见 [工具延迟加载覆盖](tool-defer-overlay.md) | `codebuddy --tools "Bash,Read,Defer(Glob)"`                                                        |
 | `--mcp-config <fileOrString>`    | 从 JSON 文件或 JSON 字符串加载 MCP 服务器配置                                                                                     | `codebuddy --mcp-config ./mcp.json`                                                                 |
 | `--strict-mcp-config`            | 仅使用 `--mcp-config` 或 SDK `mcpServers` 提供的 MCP 服务器，忽略用户、项目和本地 `.mcp.json` 等文件型配置；未显式传入时，交互模式、`--serve` 和 ACP 会继续加载这些文件型配置 | `codebuddy --serve --strict-mcp-config`                                                             |
+| `--no-session-persistence`       | 仅在内存中保留会话上下文，不创建或更新本地 transcript；仍可以只读加载已有会话                                      | `codebuddy --serve --no-session-persistence`                                                       |
 | `--print`, `-p`                  | 打印响应后退出,不进入交互模式                             | `codebuddy -p "查询"`                                                                              |
 | `--settings`                     | 从 JSON 文件或 JSON 字符串加载额外的设置配置                                                                                       | `codebuddy --settings '{"model":"gpt-5"}' "查询"`                                                  |
 | `--setting-sources`              | 指定要加载的设置源,逗号分隔（可选值: `user`, `project`, `local`）。默认: `user,project,local`                                      | `codebuddy --setting-sources project,local "查询"`                                                 |
@@ -92,7 +93,7 @@
 | `prompt`          | 是   | 指导子代理行为的系统提示词                                                     |
 | `tools`           | 否   | 子代理可以使用的特定工具数组（如 `["Read", "Edit", "Bash"]`)。省略则继承所有工具 |
 | `disallowedTools` | 否   | 子代理禁止使用的工具数组（黑名单），与 session 级 `--disallowedTools` 取并集生效 |
-| `model`           | 否   | 要使用的模型别名: `sonnet`、`opus` 或 `haiku`。省略则使用默认子代理模型        |
+| `model`           | 否   | 模型 ID、名称或别名、场景变体 `lite` / `reasoning`，或 `inherit` / `default`。省略或设为 `inherit` / `default` 时，继续通过正常的子代理解析链选择模型 |
 
 示例：
 
@@ -102,7 +103,7 @@ codebuddy --agents '{
     "description": "专业代码审查员。代码更改后主动使用。",
     "prompt": "你是高级代码审查员。专注于代码质量、安全性和最佳实践。",
     "tools": ["Read", "Grep", "Glob", "Bash"],
-    "model": "sonnet"
+    "model": "lite"
   },
   "debugger": {
     "description": "错误和测试失败的调试专家。",

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

@@ -80,13 +80,13 @@ CodeBuddy Code 每次交互都会消耗 Token。成本因代码库大小、查
 
 ### 自动模型选择
 
-CodeBuddy Code 会根据任务类型自动选择合适的场景模型。当子代理执行时，系统会根据用户当前选择的主模型，自动解析出对应的场景模型。
+CodeBuddy Code 会根据任务类型解析合适的场景模型。例如，`Explore` 的内置声明是 `lite`，可以把代码搜索交给更快、更经济的模型；规划类任务则可使用 `reasoning`。
 
-例如，`contentAnalyzer` 等轻量级子代理会自动使用 `lite` 模型，在保证功能的同时降低成本、提升速度。
+在 `/model` 的 **Scenario Models** 区域将 `lite` 和 `reasoning` 映射到具体模型；如需单独配置某个内置子代理，可通过 `/agents` 选择具体模型或场景变体。项目设置只覆盖同名子代理或场景键，不会删除其他全局映射。
 
 Agent 工具支持通过 `model` 参数指定场景类型：
 
-* `default`：继承父模型，适用于一般任务
+* `default`：继续使用由按子代理设置、内置声明和主模型组成的默认编排
 * `lite`：快速且低成本，适用于简单搜索、快速文件操作
 * `reasoning`：增强推理能力，适用于复杂分析、架构决策
 
@@ -124,11 +124,11 @@ When you are using compact, please focus on test output and code changes.
 
 ### 选择合适的模型
 
-根据任务复杂度选择模型。使用 `/model` 在会话中切换模型，或在 `/config` 中设置默认值。
+根据任务复杂度选择模型。使用 `/model` 切换主模型，或在 **Scenario Models** 区域配置 `lite` / `reasoning`；使用 `/agents` 为特定内置子代理选择场景变体或具体模型。
 
-* **简单任务使用 lite**：文件搜索、快速查询、代码格式化
-* **复杂任务使用 reasoning**：架构设计、性能优化、复杂调试
-* **一般任务使用 default**：日常编码、功能实现
+* **简单任务使用 `lite`**：文件搜索、快速查询、代码格式化
+* **复杂任务使用 `reasoning`**：架构设计、性能优化、复杂调试
+* **一般任务使用 `default`**：日常编码、功能实现
 
 ### 减少 MCP 服务器开销
 

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

@@ -259,12 +259,18 @@ codebuddy daemon start --port 8080
 # CI 启动
 codebuddy daemon start --port 9090
 
-# 其他 CI 步骤调用
+# 其他 CI 步骤调用（body 为 Gateway Protocol 格式，须含 id/type）
 curl -X POST http://127.0.0.1:9090/api/v1/runs \
   -H "Content-Type: application/json" \
-  -d '{"prompt": "审查这个 PR 的代码变更"}'
+  -H "X-CodeBuddy-Request: 1" \
+  -d '{"id": "run-1", "type": "message", "payload": {"text": "审查这个 PR 的代码变更"}}'
+# 响应: {"data": {"runId": "uuid-xxx", "status": "accepted"}}
 ```
 
+> 说明：`/api/v1/runs` 请求必须携带 `X-CodeBuddy-Request` 头，body 使用
+> [Gateway Protocol](./http-api.md) 格式（`id`、`type` 为必填，prompt 文本放
+> 在 `payload.text`）。字段详情见 [HTTP API 文档](./http-api.md)。
+
 ### 多人共享 Agent
 
 一台开发机上启动 daemon 绑定局域网地址，团队成员通过 Web UI 共同使用同一个 Agent 环境。

package/dist/web-ui/docs/cn/cli/env-vars.md

@@ -32,10 +32,15 @@ CodeBuddy Code 支持通过环境变量来控制其行为。这些变量可以
 | `CODEBUDDY_CODE_SUBAGENT_MODEL` | **一刀切**覆盖所有内置子代理的模型（优先级最高，压过 `subagents` 设置项）。仅需按子代理独立配置时，改用 `/agents` 面板或 `settings.json` 的 `subagents.agents.<子代理名>.model` |
 | `MAX_THINKING_TOKENS` | 启用扩展思考并设置思考过程的 token 预算。默认禁用 |
 
-> **env 与 settings 的关系**：模型相关环境变量是**运维/CI 级的最高优先级覆盖**。
-> - `CODEBUDDY_CODE_SUBAGENT_MODEL` 对**所有**子代理一刀切；若要**按子代理**分别指定，用 `settings.json` 的 `subagents.agents.<子代理名>.model`（支持全局 + 项目双 scope，可在 `/agents` 面板编辑），详见 [子代理文档](sub-agents.md)。
-> - `CODEBUDDY_SMALL_FAST_MODEL` / `CODEBUDDY_BIG_SLOW_MODEL` 是**按变体**独立设置的（前者只影响 `lite`、后者只影响 `reasoning`）；对应的可持久化设置项是 `variantModels`（可在 `/model` 面板的「场景变体区」编辑），详见 [设置文档](settings.md)。
-> - 优先级：env（最高）> `settings`（项目 > 全局）> 内置默认。取消 env 后 settings 恢复生效。
+> **env 与 settings 的关系**：模型相关环境变量用于运维或 CI 级覆盖。
+>
+> - 内置子代理：`CODEBUDDY_CODE_SUBAGENT_MODEL` > 本次 Agent 工具调用的 `model` 入参 > 项目级 `subagents` > 用户全局 `subagents` > 产品内置声明 > 主模型。
+> - 场景变体：对应的变体环境变量 > 项目级 `variantModels` > 用户全局 `variantModels` > 主模型的 `relatedModels` > 适用的产品内置默认 > 主模型。
+>
+> - `CODEBUDDY_CODE_SUBAGENT_MODEL` 统一覆盖所有子代理。若要分别指定，使用 `/agents` 或 `subagents.agents.<子代理名>.model`，详见 [子代理文档](sub-agents.md)。
+> - `CODEBUDDY_SMALL_FAST_MODEL` 只影响 `lite`，`CODEBUDDY_BIG_SLOW_MODEL` 只影响 `reasoning`。对应的持久化设置可通过 `/model` 或 `variantModels` 管理，详见 [设置文档](settings.md)。
+>
+> 取消环境变量后会恢复低优先级配置，不一定直接回退到主模型。
 
 ## Bash 工具配置
 
@@ -67,6 +72,7 @@ CodeBuddy Code 支持通过环境变量来控制其行为。这些变量可以
 | `CODEBUDDY_PLUGIN_DIRS` | 冒号分隔的本地插件目录路径列表（等同于 `--plugin-dir`），插件的 `bin/` 目录会自动注入到 `PATH` |
 | `CODEBUDDY_IMAGE_GEN_ENABLED` | 设置为 `false` 或 `0` 禁用图片生成功能 |
 | `CODEBUDDY_IMAGE_EDIT_ENABLED` | 设置为 `false` 或 `0` 禁用图片编辑功能 |
+| `CODEBUDDY_SHARE_LINK_ENABLED` | 设置为 `false` 或 `0` 禁用 ShareLink 工具（将本地单个 HTML 文件上传并返回可分享的公网链接）。默认开启。该环境变量优先级最高，未设置时回落到云端 `productFeatures.ShareLink` 开关（缺省 `true`） |
 | `CODEBUDDY_COMPUTER_USE_ENABLED` | **实验功能**：设置为 `true` 或 `1` 启用 macOS 桌面控制工具（截图、鼠标、键盘）。仅 macOS 可用，默认关闭。首次调用键盘/鼠标动作需在系统设置 → 隐私与安全 → 辅助功能、屏幕录制中为终端授权 |
 | `CODEBUDDY_WAIT_FOR_MCP_SERVERS_ENABLED` | 设置为 `0` 或 `false` 禁用 WaitForMcpServers 工具。默认开启。交互模式下不阻塞等待 MCP 连接，当 LLM 需要尚未就绪的 MCP 工具时可主动调用此工具按需等待。WorkBuddy 场景设置为 `0` 禁用 |
 | `CODEBUDDY_DEFERRED_TOOLS_MCP_READY_WAIT_MS` | 渲染延迟工具描述前等待 MCP 服务器就绪的最长毫秒数，默认 `2500`。设为 `0` 完全跳过等待，连接较慢则会立即把"仍在连接"提示烘焙进描述；调大可让远端 MCP 服务器有更多时间在首次提示前完成握手。一旦服务器就绪即立即继续，超时仅作为上限 |
@@ -74,6 +80,7 @@ CodeBuddy Code 支持通过环境变量来控制其行为。这些变量可以
 | `CODEBUDDY_SHOW_ALL_DEFERRED_TOOLS` | 设置为 `true` 或 `1` 显示所有延迟工具的完整描述 |
 | `CODEBUDDY_DISABLE_CRON` | 设置为 `1` 禁用计划任务 |
 | `CODEBUDDY_DISABLE_FORK_SUBAGENT` | 设置为 `1` 禁用 Agent 工具的 Fork 子代理模式（`subagent_type="fork"`）。启用后 Agent 工具描述会自动隐藏 fork-mode 段落，模型不会看到该功能；若模型仍然传 `subagent_type="fork"`，运行时会回落到名为 `fork` 的自定义代理（如用户在 `.codebuddy/agents/fork.md` 定义），否则改写为 `general-purpose` 普通子代理。适用于需要避免 fork 递归派生导致请求量放大的宿主场景 |
+| `CODEBUDDY_CODE_DISABLE_BACKGROUND_TASKS` | 设置为 `1` / `true` 禁用 Agent、Bash、PowerShell 工具的后台任务（`run_in_background=true`）。启用后这些工具 schema 中的 `run_in_background` 参数会被隐藏，模型不会看到该字段；即使历史/缓存 tool call 或直接调用方传入该参数，运行时也会兜底回退到同步（Agent）/前台（Bash、PowerShell）执行路径。适用于请求-响应式 SDK / 一次性任务场景——这类场景主进程在主 turn 结束后立即退出，任何后台代理/后台命令的结果都无法回流到最终答复中。对齐 Claude Code 的 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`（同样统管 Agent + Bash + PowerShell）。默认未设置（后台任务保持可用）。与 print-mode 守卫（`-p` 下始终阻断后台执行）相互独立 |
 | `CODEBUDDY_REHYDRATE_IMAGE_BLOB_REFS` | 设置为 `true` 在 `-p` 模式流式输出中将图片 blob 引用还原为完整 base64 数据。适用于需要直接获取图片数据的下游集成场景 |
 
 ## 上下文和内存
@@ -207,7 +214,7 @@ CodeBuddy Code 支持把内部 traces 通过 OTLP 协议上报到用户自有的
 | `CODEBUDDY_GATEWAY_PASSWORD` | Gateway 访问密码 |
 | `CODEBUDDY_GATEWAY_FORCE_TUNNEL` | 设置为 `1` 强制使用 tunnel 模式 |
 | `CODEBUDDY_DISABLE_REQUEST_VALIDATION` | 设置为 `1` 关闭 Gateway 自定义请求头校验（`X-CodeBuddy-Request`）。详见 [HTTP API 安全](./http-api.md#安全) |
-| `CODEBUDDY_CODE_CORS_ORIGINS` | 额外的 CORS 允许来源（逗号分隔）。支持精确 origin、`*.domain` 子域通配和 `*` 全开。如 `https://*.example.com,https://specific.com` |
+| `CODEBUDDY_CODE_CORS_ORIGINS` | 额外的 CORS 允许来源（逗号分隔）。支持精确 origin、`*.domain` 子域通配和 `*` 全开。如 `https://*.example.com,https://specific.com`。未设置时，若服务绑定 `0.0.0.0`（`--host 0.0.0.0`）则自动允许所有来源 |
 | `SERVER__HOST` | `--serve` 模式监听地址（默认：`127.0.0.1`） |
 | `SERVER__PORT` | `--serve` 模式监听端口 |
 
@@ -246,6 +253,8 @@ CodeBuddy Code 支持把内部 traces 通过 OTLP 协议上报到用户自有的
 | `CODEBUDDY_DEBUG_SDK` | 设置为 `1`/`true`/`yes`/`on` 启用 SDK 调试 |
 | `CODEBUDDY_DEBUG_REQUEST` | 设置为 `1` 启用请求调试 |
 | `CODEBUDDY_STARTUP_PROFILE` | 设置为 `1` 启用启动性能分析 |
+| `CODEBUDDY_CODE_HEAP_SNAPSHOT_NEAR_LIMIT_PCT` | **OOM 取证**（默认关闭）。开启后当进程堆越过 V8 堆上限高水位时，自动写一份 heap snapshot 到 `~/.codebuddy/diagnostics/<date>/oom-nearlimit-<pid>-<ts>.heapsnapshot`（进程内只写一次）。取值：`on`/`true`/`1` 按默认 85% 水位；`0.9` 或 `90` 自定义水位；未设 / `0` / `off` / `false` 关闭。⚠️ 快照文件≈当时 heapUsed 的 1.5 倍（GB 级堆会写出数 GB 文件），仅排查 OOM 时开启。详见[故障排查 · OOM](troubleshooting.md#内存溢出-oom-排查) |
+| `CBC_HEAP_SNAPSHOT_ON_WORKFLOW_END` | 设置为 `1` 时，每个 workflow（`ultracode` 等）跑完后写一份 heap snapshot 到 `~/.codebuddy/diagnostics/<date>/`。默认关闭（会占磁盘），仅排查 workflow 残留内存时开启 |
 
 ## E2E 测试 (Record/Replay)
 
@@ -316,7 +325,8 @@ export CODEBUDDY_BIG_SLOW_MODEL="deepseek-v4-pro"
 # 后台/轻量任务使用的小模型
 export CODEBUDDY_SMALL_FAST_MODEL="deepseek-v4-flash"
 
-# 子代理使用的模型（不设置则继承主 Agent）
+# 运维级统一覆盖所有子代理。
+# 不设置时会继续使用单次调用、按子代理设置和产品内置编排。
 export CODEBUDDY_CODE_SUBAGENT_MODEL="deepseek-v4-flash"
 
 # 启动时可通过 --model 显式指定主模型

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

@@ -324,7 +324,7 @@ LLM 必须使用包含以下内容的 JSON 响应：
 | 事件 | 触发时机 | matcher 字段 | 典型场景 |
 | --- | --- | --- | --- |
 | `PreToolUse` | 工具执行前 | 支持（工具名） | 校验命令、二次审批、日志记录 |
-| `PostToolUse` | 工具成功执行后 | 支持 | 自动格式化、补充上下文 |
+| `PostToolUse` | 工具成功执行后 | 支持 | 自动格式化、补充上下文、压缩/替换工具结果 |
 | `Notification` | 权限请求或 60 秒无输入提醒 | 部分支持 | 桌面提示、IM 通知 |
 | `UserPromptSubmit` | 用户提交消息时<br/>**注：不包括内部命令** | 不支持 | 内容审查、上下文注入 |
 | `Stop` | 主代理响应结束时 | 不支持 | 要求继续执行、追加提醒 |
@@ -593,7 +593,7 @@ Hooks 通过退出代码、stdout 和 stderr 传达状态：
 | Hook 事件 | 行为 |
 |------------|----------|
 | PreToolUse | 阻止工具调用，向 CodeBuddy 显示消息 |
-| PostToolUse | 向 CodeBuddy 显示消息（工具已运行，用于补充上下文） |
+| PostToolUse | 向 CodeBuddy 显示消息（工具已运行，用于补充上下文）；可用 `updatedToolOutput` 替换工具结果 |
 | Notification | N/A，仅向用户显示消息 |
 | UserPromptSubmit | 阻止提示词处理，清除提示词，仅向用户显示消息 |
 | Stop | 阻止停止，向 CodeBuddy 显示消息并继续对话 |
@@ -647,9 +647,14 @@ PreToolUse hooks 可以控制工具调用是否继续。
 - `"ask"` 要求用户在 UI 中确认工具调用，`permissionDecisionReason` 会显示在确认对话框中
 - `modifiedInput` 允许你在执行前修改工具的输入参数（部分字段覆盖）
 
-#### PostToolUse 上下文注入
+#### PostToolUse 上下文注入与结果替换
 
-PostToolUse 在工具执行**完成后**触发，无法阻止已执行的操作，但可以向 Agent 注入额外上下文信息。
+PostToolUse 在工具执行**完成后**触发，无法阻止已执行的操作，但可以：
+
+1. 向 Agent **追加**额外上下文（`additionalContext`）；
+2. **替换**将要发送给 Agent 的工具结果（`updatedToolOutput`）。
+
+**追加上下文**（原始工具结果保留，在其后追加一段提示）：
 
 ```jsonc
 {
@@ -660,6 +665,23 @@ PostToolUse 在工具执行**完成后**触发，无法阻止已执行的操作
 }
 ```
 
+**替换工具结果**（用返回值整个替换原始工具输出后再发给 Agent）：
+
+```jsonc
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUse",
+    "updatedToolOutput": "精简后的工具输出"
+  }
+}
+```
+
+- `updatedToolOutput` 对**所有工具**生效（内置工具与 MCP 工具均可）。
+- 典型用途：压缩冗长的工具输出（如超大命令日志、超长文件内容）以节省上下文 token —— 这类"压缩型" hook 依赖的正是替换能力。
+- 与 `additionalContext` 的区别：`additionalContext` 是**追加**（结果只会变长），`updatedToolOutput` 是**替换**（结果可以变短）。
+- 两者可同时返回：先用 `updatedToolOutput` 替换，再把 `additionalContext` 追加到替换后的内容上。
+- 对 MCP 工具，返回的 `updatedToolOutput` 若为数组则原样作为 MCP content 数组，否则包装为单个文本块。
+
 > **注意**：`decision: "block"` 字段已废弃。由于工具已执行完成，此时无法真正"阻止"操作。
 
 #### UserPromptSubmit 决策控制

package/dist/web-ui/docs/cn/cli/http-api.md

@@ -69,6 +69,17 @@ X-CodeBuddy-Request: 1
 
 可通过环境变量 `CODEBUDDY_DISABLE_REQUEST_VALIDATION=1` 关闭此校验。
 
+### CORS 白名单
+
+跨域请求的 `Origin` 会与服务端 CORS 白名单匹配，不在白名单中的来源会被拒绝（预检返回无 CORS 头的 204，实际请求返回 403 `Origin not allowed`）。白名单来源：
+
+- 本地端点及其回环变体（`localhost` / `127.0.0.1` / `[::1]`）
+- Tunnel URL（如启用）
+- 配置项 `gateway.corsOrigins`
+- 环境变量 `CODEBUDDY_CODE_CORS_ORIGINS`（逗号分隔，支持精确 origin、`*.domain` 子域通配和 `*` 全开）
+
+绑定 `0.0.0.0` 时（如 `--host 0.0.0.0`，常见于云虚拟机 / 局域网暴露场景），若未显式设置 `CODEBUDDY_CODE_CORS_ORIGINS`，服务端会**自动允许所有来源**（等价于配置 `*`），无需额外配置即可通过任意 IP 或域名访问 Web UI；显式设置该环境变量时以用户配置为准。
+
 ### 认证
 
 支持两种模式（环境变量 `CODEBUDDY_GATEWAY_AUTH` 控制）：
@@ -286,10 +297,12 @@ CBC 增强：
 | POST | `/api/v1/plugins/enable` | 启用插件 |
 | POST | `/api/v1/plugins/disable` | 禁用插件 |
 | POST | `/api/v1/plugins/uninstall` | 卸载插件 |
+| POST | `/api/v1/plugins/update` | 更新插件到最新版本 |
 | GET | `/api/v1/plugins/marketplaces` | 列出已配置的插件市场 |
-| POST | `/api/v1/plugins/marketplaces` | 添加插件市场 |
+| POST | `/api/v1/plugins/marketplaces` | 添加插件市场（可选 `autoUpdate` 添加时即开启自动更新） |
 | POST | `/api/v1/plugins/marketplaces/browse` | 浏览市场中的可用插件 |
 | POST | `/api/v1/plugins/marketplaces/update` | 更新市场（同步远端仓库内容） |
+| POST | `/api/v1/plugins/marketplaces/auto-update` | 开启/关闭市场自动更新 |
 | DELETE | `/api/v1/plugins/marketplaces/:name` | 删除插件市场 |
 
 ### 配置管理
@@ -302,6 +315,15 @@ CBC 增强：
 | POST | `/api/v1/settings/:key/items` | 向数组类配置追加值 |
 | POST | `/api/v1/settings/:key/remove` | 从数组类配置移除值 |
 
+### 工作目录
+
+| 方法 | 端点 | 说明 |
+|------|------|------|
+| GET | `/api/v1/workspace-dirs` | 列出当前附加工作目录 |
+| POST | `/api/v1/workspace-dirs` | 添加单个工作目录 |
+| DELETE | `/api/v1/workspace-dirs?path=` | 移除单个工作目录 |
+| PUT | `/api/v1/workspace-dirs/sync` | 全量同步工作目录列表 |
+
 ### 任务模板
 
 | 方法 | 端点 | 说明 |
@@ -352,17 +374,46 @@ curl http://127.0.0.1:8080/api/v1/health
 ### 发起 Agent 执行
 
 ```bash
-# 发送消息
+# 发送消息（body 为 Gateway Protocol 格式，id/type 必填）
 curl -X POST http://127.0.0.1:8080/api/v1/runs \
   -H "Content-Type: application/json" \
-  -d '{"text": "帮我分析代码性能", "sender": {"id": "dev", "name": "Developer"}}'
+  -H "X-CodeBuddy-Request: 1" \
+  -d '{
+    "id": "run-1",
+    "type": "message",
+    "source": {"platform": "generic", "sender": {"id": "dev", "name": "Developer"}, "conversation": {"id": "run-1", "type": "direct"}},
+    "payload": {"text": "帮我分析代码性能"}
+  }'
 
 # 响应: {"data": {"runId": "uuid-xxx", "status": "accepted"}}
 
-# 通过 SSE 流获取结果
-curl http://127.0.0.1:8080/api/v1/runs/uuid-xxx/stream
+# 通过 SSE 流获取结果（同样需携带 X-CodeBuddy-Request 头）
+curl -H "X-CodeBuddy-Request: 1" http://127.0.0.1:8080/api/v1/runs/uuid-xxx/stream
 ```
 
+#### 请求体字段（Gateway Protocol）
+
+`POST /api/v1/runs` 的请求体为 Gateway Protocol 入站消息格式：
+
+| 字段 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `id` | ✅ | string | 消息唯一 ID，由调用方生成，用于去重与追踪 |
+| `type` | ✅ | `"message"` \| `"action"` | 消息类型。`message` 发起对话，`action` 发送控制指令 |
+| `payload.text` | — | string | prompt 文本（也兼容顶层 `text` / `prompt`） |
+| `payload.attachments` | — | array | 附件列表，元素含 `type`（`image`/`voice`/`video`/`file`）、`url`、`urlType`（`local-path`/`url`）等 |
+| `version` | — | string | 协议版本，默认 `"1.0"` |
+| `source.platform` | — | string | 来源平台，默认 `"generic"` |
+| `source.sender.id` | — | string | 发送者 ID，用于限流；缺省为 `"unknown"` |
+| `source.sender.name` | — | string | 发送者名称 |
+| `source.conversation.id` | — | string | 会话 ID，缺省取 `id` |
+| `source.conversation.type` | — | `"direct"` \| `"group"` | 会话类型，默认 `"direct"` |
+| `action` | — | `"cancel"` \| `"status"` | 仅 `type="action"` 时使用的控制动作 |
+| `callback.url` | — | string | 异步回传结果的回调地址（模式 B） |
+| `callback.headers` | — | object | 回调请求附加的自定义头 |
+| `timeoutMs` | — | number | 单次执行超时（毫秒），优先级高于 `settings.gateway.runTimeoutMs`；也可用请求头 `X-Codebuddy-Run-Timeout`。设为 0 或负数关闭超时保护 |
+
+> 权威定义见源码 `src/node/remote-gateway/gateway-protocol.ts` 的 `GatewayInboundMessage`。
+
 ### PTY 终端管理
 
 ```bash
@@ -541,6 +592,11 @@ curl -X POST http://127.0.0.1:8080/api/v1/plugins/uninstall \
   -H "Content-Type: application/json" \
   -d '{"plugin": "my-plugin@my-marketplace"}'
 
+# 更新插件到最新版本（传 waitForApply=true 可等待重建生效后再返回）
+curl -X POST http://127.0.0.1:8080/api/v1/plugins/update \
+  -H "Content-Type: application/json" \
+  -d '{"plugin": "my-plugin@my-marketplace"}'
+
 # 列出插件市场
 curl http://127.0.0.1:8080/api/v1/plugins/marketplaces
 
@@ -549,6 +605,11 @@ curl -X POST http://127.0.0.1:8080/api/v1/plugins/marketplaces \
   -H "Content-Type: application/json" \
   -d '{"source": "https://example.com/marketplace", "name": "my-marketplace"}'
 
+# 添加插件市场并默认开启自动更新（等价于添加后再调一次 marketplaces/auto-update）
+curl -X POST http://127.0.0.1:8080/api/v1/plugins/marketplaces \
+  -H "Content-Type: application/json" \
+  -d '{"source": "https://example.com/marketplace", "name": "my-marketplace", "autoUpdate": true}'
+
 # 浏览市场中的插件
 curl -X POST http://127.0.0.1:8080/api/v1/plugins/marketplaces/browse \
   -H "Content-Type: application/json" \
@@ -559,6 +620,11 @@ curl -X POST http://127.0.0.1:8080/api/v1/plugins/marketplaces/update \
   -H "Content-Type: application/json" \
   -d '{"marketplace": "my-marketplace"}'
 
+# 开启/关闭市场自动更新（开启后后台周期性同步并升级已安装插件）
+curl -X POST http://127.0.0.1:8080/api/v1/plugins/marketplaces/auto-update \
+  -H "Content-Type: application/json" \
+  -d '{"marketplace": "my-marketplace", "autoUpdate": true}'
+
 # 删除插件市场
 curl -X DELETE http://127.0.0.1:8080/api/v1/plugins/marketplaces/my-marketplace
 ```
@@ -591,6 +657,33 @@ curl -X POST http://127.0.0.1:8080/api/v1/settings/permissions/remove \
   -d '{"values": ["Allow: Read(**)"]}'
 ```
 
+### 工作目录
+
+管理附加工作目录，使权限系统放行这些目录下的文件操作（与 `/add-dir` 命令效果一致）。
+
+```bash
+# 列出当前附加工作目录
+curl http://127.0.0.1:8080/api/v1/workspace-dirs
+
+# 添加工作目录
+curl -X POST http://127.0.0.1:8080/api/v1/workspace-dirs \
+  -H "Content-Type: application/json" \
+  -d '{"path": "/Users/me/other-project"}'
+
+# 移除工作目录
+curl -X DELETE "http://127.0.0.1:8080/api/v1/workspace-dirs?path=/Users/me/other-project"
+
+# 全量同步（页面刷新恢复后调用）
+curl -X PUT http://127.0.0.1:8080/api/v1/workspace-dirs/sync \
+  -H "Content-Type: application/json" \
+  -d '{"dirs": ["/Users/me/project-a", "/Users/me/project-b"]}'
+```
+
+**说明**：
+- 添加的目录存储在 CLI scope（进程内存），实例关闭后失效
+- 前端通过 Web UI 的 workspace storage 持久化，页面刷新后自动同步到后端
+- 添加后，Agent 工具（Read/Write/Glob/Grep/Bash）可免询问访问这些目录
+
 ### 使用统计
 
 ```bash

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

@@ -494,7 +494,7 @@ echo $CODEBUDDY_INTERNET_ENVIRONMENT
 
 | 版本 | `CODEBUDDY_INTERNET_ENVIRONMENT` |
 |:----|:--------------------------------|
-| 海外版 | 不设置或 `public` |
+| 海外版 | 不设置 |
 | 中国版 | `internal` |
 | iOA 版 | `ioa` |
 

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

@@ -338,7 +338,7 @@ CodeBuddy Code 在一次会话中会根据场景切换模型，避免用大模
 |------|------|---------|
 | `lite` | 轻量快速模型，用于后台提取、摘要等低价值请求；也是 Agent 工具 `model: "lite"` 参数对应的模型 | **已生效** |
 | `reasoning` | 推理增强模型，用于需要深度思考的复杂推理；Agent 工具 `model: "reasoning"` 参数对应的模型 | **已生效** |
-| `subagent` | 子 Agent / 团队成员默认使用的模型 | **预留未启用**——当前子代理模型通过 `CODEBUDDY_CODE_SUBAGENT_MODEL` 环境变量或 agent 配置的 `models[0]` 决定，不读取本字段 |
+| `subagent` | 子代理和团队成员默认使用的模型 | **预留未启用**——子代理使用独立的 `subagents` 解析链，不读取本字段 |
 | `vision` | 视觉理解模型，用于需要处理图片的请求 | **预留未启用**——类型已定义，尚无调用点消费此 variant |
 | `longContext` | 长上下文模型，用于上下文超长的请求 | **预留未启用**——类型已定义，尚无调用点消费此 variant |
 
@@ -347,7 +347,7 @@ CodeBuddy Code 在一次会话中会根据场景切换模型，避免用大模
 **关键规则（自定义模型必读）：**
 
 > 通过 `models.json` 添加的自定义模型**不会继承**产品内置的 `defaultRelatedModels`。
-> 如果没有在自身条目里显式声明 `relatedModels`，所有场景都会回退到主模型自己——也就是说子代理、lite、reasoning 全部用同一个大模型跑，成本和速度都不划算。
+> 如果自定义主模型没有声明 `relatedModels`，且没有环境变量或 `variantModels` 覆盖，`lite` 和 `reasoning` 会回退到主模型。子代理不读取 `relatedModels.subagent`，但配置为 `lite` 或 `reasoning` 的子代理仍会走这条场景变体解析链。
 
 **配置示例（DeepSeek 主模型 + flash 作为 lite / reasoning）：**
 
@@ -386,21 +386,51 @@ CodeBuddy Code 在一次会话中会根据场景切换模型，避免用大模
 }
 ```
 
-**解析优先级（从高到低，当前仅 `lite` / `reasoning` 会走到这个解析链）：**
+**场景变体解析优先级（从高到低，当前仅 `lite` / `reasoning` 会走这个解析链）：**
 
-1. 环境变量显式指定（`CODEBUDDY_SMALL_FAST_MODEL` 对应 `lite`、`CODEBUDDY_BIG_SLOW_MODEL` 对应 `reasoning`）
-2. 当前主模型条目里的 `relatedModels[variant]`
-3. 产品内置的 `defaultRelatedModels[variant]`（**仅对内置模型生效，自定义模型跳过这步**）
-4. 回落到主模型自身
+1. 对应的环境变量（`CODEBUDDY_SMALL_FAST_MODEL` 对应 `lite`、`CODEBUDDY_BIG_SLOW_MODEL` 对应 `reasoning`）
+2. 项目级 `variantModels[variant]`
+3. 用户全局 `variantModels[variant]`
+4. 当前主模型条目里的 `relatedModels[variant]`
+5. 产品内置的 `defaultRelatedModels[variant]`（仅对内置模型生效，自定义模型跳过这步）
+6. 回落到主模型自身
 
-> **子代理模型的取值规则不走 `relatedModels.subagent`**，而是独立的链路：Agent 工具 `model` 参数 > `CODEBUDDY_CODE_SUBAGENT_MODEL` 环境变量 > agent 配置的 `models[0]` > 主模型。
+`variantModels` 保存在 `settings.json` 中，也可通过 `/model` 面板的 **Scenario Models** 区域编辑。它适合在用户或项目范围内将 `lite` / `reasoning` 固定映射到具体模型；`relatedModels` 则适合让映射跟随当前主模型。
 
-**与环境变量方式的取舍：**
+**内置子代理解析优先级（从高到低）：**
 
-- 想让某主模型在 `lite` / `reasoning` 场景自动切到另一个同厂小模型：在主模型条目里声明 `relatedModels` 最直观，绑定关系跟着模型走。
-- 想让子代理用小模型：目前必须走环境变量 `CODEBUDDY_CODE_SUBAGENT_MODEL`，或在 agent 配置里把小模型写到 `models[0]`——**不是** `relatedModels.subagent`。
-- 想在不同项目里用不同的大小模型组合：用环境变量（`CODEBUDDY_MODEL` / `CODEBUDDY_BIG_SLOW_MODEL` / `CODEBUDDY_SMALL_FAST_MODEL` / `CODEBUDDY_CODE_SUBAGENT_MODEL`），配合项目级 `.env` 切换。
-- 两种方式同时生效时，环境变量优先。
+1. `CODEBUDDY_CODE_SUBAGENT_MODEL`，统一覆盖所有子代理
+2. 本次 Agent 工具调用的 `model` 入参
+3. 项目级 `subagents.agents.<子代理名>.model`
+4. 用户全局 `subagents.agents.<子代理名>.model`
+5. 产品内置声明，如 `Explore` 使用 `lite`
+6. 继承主对话模型
+
+子代理模型不读取 `relatedModels.subagent`。当子代理配置为 `lite` 或 `reasoning` 时，会继续通过上面的场景变体解析链得到具体模型。
+
+以下配置应写入用户级或项目级 `settings.json`：
+
+```json
+{
+  "subagents": {
+    "agents": {
+      "Explore": { "model": "lite" },
+      "Plan": { "model": "reasoning" }
+    }
+  },
+  "variantModels": {
+    "lite": "<fast-model-id>",
+    "reasoning": "<reasoning-model-id>"
+  }
+}
+```
+
+**不同配置方式的适用场景：**
+
+- 使用 `relatedModels`，让场景映射跟随主模型。
+- 使用 `variantModels` 或 `/model`，在用户或项目范围内固定 `lite` / `reasoning` 的具体模型。
+- 使用 `subagents.agents.<子代理名>.model` 或 `/agents`，为内置子代理分别选择模型或场景变体。
+- 使用模型环境变量进行运维或 CI 级覆盖。环境变量优先于持久化设置；取消后，低优先级设置会恢复生效。
 
 ### 完整示例
 

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

@@ -235,10 +235,11 @@ CodeBuddy 默认认为只有**当前工作目录**是受信任的。Read 工具
 | :--- | :--- |
 | `--add-dir <path>` 启动参数 | 进程级 |
 | 会话内 `/add-dir` 命令 | 会话级 |
+| Web UI 添加目录（`/api/v1/workspace-dirs`） | 进程级（前端持久化） |
 | `permissions.additionalDirectories` 配置项 | 持久化 |
 | `permissions.trustedDirectories` 配置项 | 持久化 |
 
-最终生效的信任目录 = 工作区根 + `settings.trustedDirectories` + 启动时 `--add-dir` / 会话内 `/add-dir` 添加的目录。
+最终生效的信任目录 = 工作区根 + `settings.trustedDirectories` + 启动时 `--add-dir` / 会话内 `/add-dir` / Web UI 添加的目录。
 
 > `--add-dir` 和 `permissions.additionalDirectories` 都只授予**文件访问权**，**不会**让 CodeBuddy 加载这些目录里的 `.codebuddy/` 配置（agents / hooks / settings 等都仍以启动目录的为准）。
 

package/dist/web-ui/docs/cn/cli/plugins-reference.md

@@ -913,6 +913,8 @@ CodeBuddy 按以下优先级计算缓存键：
 
 没有显式版本的 Git 插件以 12 位 commit SHA 为缓存目录名。通过版本约束解析 tag 时，缓存目录额外包含 12 位 commit SHA 后缀；约束校验使用单独记录的 `resolvedVersion`，不依赖可能过期的 manifest 版本。
 
+旧版本已经记录为 `unknown` 的 Git marketplace 插件会在启动时自动迁移：CodeBuddy 从当前 marketplace checkout 解析 commit SHA，将源码物化到对应的 SHA 缓存目录，再原子更新 `installed_plugins.json`。旧的 `unknown` 目录只会被标记为 orphan；至少保留 14 天，并且仍有活动会话的 `.in_use` 标记时不会删除。非 Git 来源且没有显式版本的插件继续使用 `unknown`。
+
 ---
 
 ## 九、与 Claude Code 的兼容性

package/dist/web-ui/docs/cn/cli/release-notes/README.md

@@ -17,6 +17,21 @@ Release Notes 记录了每个版本的用户可见变更，包括：
 
 <!-- 新版本自动添加到此处 -->
 
+- [v2.125.4](./v2.125.4.md) - 2026-07-23
+- [v2.125.3](./v2.125.3.md) - 2026-07-23
+- [v2.125.2](./v2.125.2.md) - 2026-07-22
+- [v2.125.1](./v2.125.1.md) - 2026-07-22
+- [v2.125.0](./v2.125.0.md) - 2026-07-21
+- [v2.124.1](./v2.124.1.md) - 2026-07-19
+- [v2.124.0](./v2.124.0.md) - 2026-07-17
+- [v2.123.1](./v2.123.1.md) - 2026-07-16
+- [v2.123.0](./v2.123.0.md) - 2026-07-16
+- [v2.122.0](./v2.122.0.md) - 2026-07-15
+- [v2.121.3](./v2.121.3.md) - 2026-07-15
+- [v2.121.2](./v2.121.2.md) - 2026-07-14
+- [v2.121.1](./v2.121.1.md) - 2026-07-14
+- [v2.121.0](./v2.121.0.md) - 2026-07-14
+- [v2.120.0](./v2.120.0.md) - 2026-07-13
 - [v2.119.4](./v2.119.4.md) - 2026-07-12
 - [v2.119.3](./v2.119.3.md) - 2026-07-12
 - [v2.119.2](./v2.119.2.md) - 2026-07-12

package/dist/web-ui/docs/cn/cli/release-notes/v2.120.0.md

@@ -0,0 +1,31 @@
+# 🚀 CodeBuddy Code v2.120.0 发布
+
+## 📦 版本信息
+
+| 组件 | 版本 |
+|------|------|
+| CodeBuddy Code CLI | v2.120.0 |
+| Agent SDK JS | v0.3.212 |
+| Agent SDK Python | v0.3.211 |
+
+## ✨ 新功能
+
+### 子 Agent 模型灵活配置
+
+现在可以按内置子 Agent（Explore / general-purpose / Plan 等）的粒度**独立指定模型**，各子 Agent 互不影响、可自由组合，不再只能通过环境变量一刀切。
+
+- 新增 `subagents` 配置项（`subagents.agents.<子Agent名>.model`），支持全局与项目两个 scope；
+- 在 `/agents` 面板可直接查看每个子 Agent 的「实际生效模型 + 来源」并可视化编辑；
+- 环境变量 `CODEBUDDY_CODE_SUBAGENT_MODEL` 仍为最高优先级、对所有子 Agent 统一生效。
+
+### 场景变体模型配置
+
+新增 `variantModels` 配置项，可在 `/model` 面板查看并修改 `lite`（轻量快速）与 `reasoning`（推理增强）两个通用场景槽位当前映射的模型，支持全局与项目两个 scope；对应环境变量 `CODEBUDDY_SMALL_FAST_MODEL` / `CODEBUDDY_BIG_SLOW_MODEL` 仍按变体独立、最高优先级生效。
+
+> 向后兼容：未做任何配置时，行为与升级前完全一致。
+
+## 🐛 问题修复
+
+- **沙箱 Bash 环境变量**：修复 Bash 沙箱执行时腾讯文档等 MCP 配置无法透传，导致相关工具不可用的问题。
+- **沙箱降级更稳健**：修复沙箱启动失败并降级到本地执行时，出现多余的 `unhandledRejection` 诊断告警的问题。
+- **Skill 加载优先级**：修复项目内 Skill 与全局 Skill 同名时，项目 Skill 未按就近优先级生效的问题。

package/dist/web-ui/docs/cn/cli/release-notes/v2.121.0.md

@@ -0,0 +1,42 @@
+# 🚀 CodeBuddy Code v2.121.0 发布
+
+## 📦 版本信息
+
+| 组件 | 版本 |
+|------|------|
+| CodeBuddy Code CLI | v2.121.0 |
+| Agent SDK JS | v0.3.213 |
+| Agent SDK Python | v0.3.212 |
+
+## ✨ 新功能
+
+### 工作目录管理
+
+新增 `/api/v1/workspace-dirs` REST API，支持列出、添加、移除和全量同步附加工作目录。Web UI 输入框工具栏新增工作目录堆叠图标，可视化添加/移除附加工作目录；附加工作目录信息会自动注入到 Agent 系统提示词中，让模型感知完整的工作范围。
+
+### 插件更新与市场自动更新
+
+- **插件更新公开接口**：新增 `POST /api/v1/plugins/update`，在公开 HTTP API 上提供「将已安装插件更新到最新版本」能力，支持指定插件、作用域与是否等待生效，为客户端「套件自动更新」提供前置能力。
+- **市场自动更新开关**：新增 `POST /api/v1/plugins/marketplaces/auto-update`，可开启/关闭市场自动更新；开启后由后台周期性同步市场并把已安装插件升级到最新。
+
+### 权限模式扩展
+
+ACP 新增 Full Access 和 Delegate 权限模式，提供更灵活的权限控制选项。
+
+## 🔧 改进优化
+
+- **Hooks 输出替换**：PostToolUse 支持通过 `updatedToolOutput` 替换所有工具的输出，便于压缩冗长结果并降低上下文占用。
+- **后台任务开关**：新增环境变量 `CODEBUDDY_CODE_DISABLE_BACKGROUND_TASKS`，宿主开启后隐藏 Agent、Bash、PowerShell 的后台执行参数，并兜底回退到同步/前台执行，保证结果一定回流到主答复，避免请求-响应式 SDK 场景下结果丢失。
+- **PTY 稳定性**：升级 PTY 底层依赖，纳入 macOS PTY 退出后的文件描述符回收修复，提升终端稳定性。
+- **输入框工具栏**：Mode/Model 选择器尺寸优化，更紧凑。
+- **文件树加载体验**：目录展开增加延迟显示 loading，避免快速加载时的闪烁。
+
+## 🐛 问题修复
+
+- **空模型响应处理**：修复模型正常结束但未返回有效内容时对话被静默取消、界面只显示占位符的问题；现在会作为可重试错误处理，仍为空时明确提示，避免会话被钉死无法继续。
+- **--print stream-json 结果误报**：修复该模式下工具未找到错误被自动恢复后，最终 result 仍误报 `is_error=true` 的问题，行为与交互式会话保持一致。
+- **延迟加载工具参数稳定性**：在重试轮补充目标工具的参数结构提示，降低数组等复杂字段被误生成的概率。
+- **AskUserQuestion 参数校验**：参数不合规时不再静默返回空结果，新增前置校验返回可读报错，并为问题卡片加渲染兜底。
+- **ACP 消息时间语义**：恢复每条消息独立记录时间戳的语义，避免完成耗时被首个流式分片时间截断。
+- **日志刷屏**：将 MCP 延迟工具索引的诊断日志降为 debug 级并删除逐工具热路径行，避免长会话下日志文件被撑到 GB 级。
+- **Linux Sandbox**：在 WorkBuddy Linux 中启用 sandbox-cli 后端，并使用 pipe 模式执行命令。

package/dist/web-ui/docs/cn/cli/release-notes/v2.121.1.md

@@ -0,0 +1,20 @@
+# 🚀 CodeBuddy Code v2.121.1 发布
+
+## 📦 版本信息
+
+| 组件 | 版本 |
+|------|------|
+| CodeBuddy Code CLI | v2.121.1 |
+| Agent SDK JS | v0.3.214 |
+| Agent SDK Python | v0.3.213 |
+
+## 🐛 问题修复
+
+- **子 Agent 卡在 preparing / ESC 崩溃**：修复本地 CLI 下主 Agent 调用 Agent 工具起子 Agent 后，子 Agent 长时间卡在 preparing 阶段不执行、且按 ESC 中断时进程崩溃的问题。子 Agent 在未启用 sandbox 时不再等待一个永不就绪的会话；准备阶段被中断时不再产生未处理异常；并为 MCP 工具列表查询补充请求超时，避免慢/无响应的 MCP 服务阻塞子 Agent 启动。
+- **工具调用流式解析**：修复部分模型将工具调用的 id 和 name 拆分到不同流式分片时，客户端无法识别导致工具调用失败、会话报错的问题。现已放宽首个分片的识别条件，允许后续分片补发工具名，兼容协议允许的字段拆分场景。
+- **Web UI 崩溃**：修复 chat 页面因循环依赖导致浏览器崩溃的问题。
+- **会话恢复列表**：过滤掉没有真实用户输入的空壳会话（如新建后立刻切走、仅留下命令记账消息的会话），避免标题回退显示成命令名。
+
+## 📝 文档更新
+
+- **HTTP API / Daemon 文档**：补充 `/api/v1/runs` 的请求头与请求体说明，示例统一为 Gateway Protocol 格式，并新增请求体字段表。