@tencent-ai/codebuddy-code 2.95.0 → 2.95.1-next.bd7ff53.20260508

package/dist/web-ui/docs/cn/cli/bash-sandboxing.md

@@ -136,6 +136,17 @@ git push
 # 3. 在非 AcceptEdits 模式下的所有命令
 ```
 
+## Bypass 权限模式下的沙箱越权自动放行
+
+当命令尝试越过沙箱边界时（例如写入 `.git/refs/*.lock`、模型带 `dangerouslyDisableSandbox=true` 调用 Bash），沙箱会弹出"是否在沙箱外运行此命令"的二次审批。
+
+从 v2.90.x 起，在 `bypassPermissions` 权限模式下，此类沙箱越权审批会对**非高危命令**自动放行，避免 `cd X && yarn build` 这类日常组合命令反复触发审批：
+
+* ✅ **自动放行**：命令安全等级为 SAFE / LOW / MEDIUM 时，直接以 `allow_once` 继续执行
+* ⛔ **仍需确认**：命令安全等级为 HIGH / CRITICAL 时（如 `rm -rf /`、`chmod 777 /etc` 等），即使在 bypass 模式下也保留交互式审批
+
+该策略与 bypass 模式下对 Bash 危险命令的保护语义一致——`bypassPermissions` 不等于无脑放行，高危操作永远需要显式确认。
+
 ### 安全保障
 
 沙箱自动批准在保持安全的同时提升效率：

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

@@ -39,6 +39,8 @@ CodeBuddy Code 支持通过环境变量来控制其行为。这些变量可以
 | `BASH_DEFAULT_TIMEOUT_MS` | 长时间运行 bash 命令的默认超时（默认：120000） |
 | `BASH_MAX_OUTPUT_LENGTH` | bash 输出在内存中保留的最大字符数（默认：30000，上限：150000）。超出部分会被中间截断（保留 head 20% + tail 80%），完整输出会自动保存到磁盘 |
 | `BASH_MAX_TIMEOUT_MS` | 模型可为长时间运行的 bash 命令设置的最大超时（默认：600000） |
+| `CODEBUDDY_BASH_ASSISTANT_BUDGET_MS` | 主对话响应预算（毫秒，默认 `0`=关闭）。设为 `>0` 时，主会话的前台 Bash/PowerShell 命令超过该时长会自动转为后台任务让对话保持响应。sub-agent 不受此预算影响。对齐 Claude Code 的 `ASSISTANT_BLOCKING_BUDGET_MS`（CC 官方默认值 `15000`） |
+| `CODEBUDDY_BASH_AUTO_BACKGROUND_DISABLED` | 设为 `1` 关闭超时自动后台化,前台命令到 timeout 回到旧的 SIGTERM/kill 硬杀行为。仅用于调试或遇到回归时临时回滚；正常场景保持默认（未设置） |
 
 ## 工具输出外部化
 
@@ -58,6 +60,7 @@ CodeBuddy Code 支持通过环境变量来控制其行为。这些变量可以
 | `CODEBUDDY_PLUGIN_DIRS` | 冒号分隔的本地插件目录路径列表（等同于 `--plugin-dir`），插件的 `bin/` 目录会自动注入到 `PATH` |
 | `CODEBUDDY_IMAGE_GEN_ENABLED` | 设置为 `false` 或 `0` 禁用图片生成功能 |
 | `CODEBUDDY_IMAGE_EDIT_ENABLED` | 设置为 `false` 或 `0` 禁用图片编辑功能 |
+| `CODEBUDDY_COMPUTER_USE_ENABLED` | **实验功能**：设置为 `true` 或 `1` 启用 macOS 桌面控制工具（截图、鼠标、键盘）。仅 macOS 可用，默认关闭。首次调用键盘/鼠标动作需在系统设置 → 隐私与安全 → 辅助功能、屏幕录制中为终端授权 |
 | `CODEBUDDY_DEFER_TOOL_LOADING` | 设置为 `false` 或 `0` 禁用 MCP 工具延迟加载 |
 | `CODEBUDDY_SHOW_ALL_DEFERRED_TOOLS` | 设置为 `true` 或 `1` 显示所有延迟工具的完整描述 |
 | `CODEBUDDY_DISABLE_CRON` | 设置为 `1` 禁用计划任务 |
@@ -82,6 +85,7 @@ CodeBuddy Code 支持通过环境变量来控制其行为。这些变量可以
 | `MCP_TIMEOUT` | MCP 服务器连接的超时时间（毫秒） |
 | `MCP_TOOL_TIMEOUT` | MCP 工具执行的超时时间（毫秒） |
 | `MAX_MCP_OUTPUT_TOKENS` | MCP 工具响应中允许的最大 token 数（默认：20000） |
+| `CODEBUDDY_DISABLE_MCP_LARGE_OUTPUT_FILES` | 设为 `1` 时，MCP 超大响应不落盘（跳过 `~/.codebuddy/projects/.../tool-results/` 文件），始终走内容截断降级 |
 
 ## 性能和输出
 
@@ -162,6 +166,8 @@ CodeBuddy Code 支持通过环境变量来控制其行为。这些变量可以
 | `CODEBUDDY_CODE_MAX_TURNS` | 主 Agent 的最大执行轮次。优先级：CLI `--max-turns` > 此环境变量 > 默认值 (500) |
 | `CODEBUDDY_CODE_SUBAGENT_MAX_TURNS` | 子 Agent 的最大执行轮次。优先级：CLI `--max-turns` > 此环境变量 > 模型动态传入的 `max_turns` > 默认值 (500) |
 | `CODEBUDDY_SUBAGENT_PERMISSION_MODE` | 子 Agent/团队成员的默认权限模式（如 `bypassPermissions`、`acceptEdits`、`default`、`plan`）。优先级：Agent 工具 `mode` 参数 > CLI `--subagent-permission-mode` > 此环境变量 > Settings `permissions.subagentPermissionMode` > 映射表默认值 |
+| `CODEBUDDY_TEAM_IDLE_DETECTION_DISABLED` | 设为 `1` 关闭队员空闲感知（默认启用）。关闭后"等待队员空闲"类 API 立即返回 `true` 不阻塞，进度快照也不再记录 |
+| `CODEBUDDY_TEAM_SHUTDOWN_GRACEFUL_TIMEOUT_MS` | 团队成员优雅关停的兜底超时毫秒数，默认 `15000`。超过此时长仍未收到队员响应将强制终止进程。设为 `0` 禁用强制兜底（纯等待响应） |
 
 ## Gateway 和远程访问
 

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

@@ -800,6 +800,33 @@ MCP 工具遵循 `mcp__<server>__<tool>` 模式，例如：
 - 成功/失败状态
 - 输出或错误消息
 
+## Agent / Skill Frontmatter Hooks
+
+除了全局 `~/.codebuddy/settings.json` 配置的 hooks 外，还可以直接在自定义 agent 的 `.md` 文件或 skill 的 `SKILL.md` 的 YAML frontmatter 里声明 `hooks` 字段。这些 hooks 只在对应的 subagent 或 fork skill 的生命周期内生效，结束后自动清理。
+
+```yaml
+---
+name: my-reviewer
+description: Code reviewer with pre-tool-use guard
+hooks:
+  PreToolUse:
+    - matcher: Bash
+      hooks:
+        - type: command
+          command: ./guard.sh
+          once: true
+  SubagentStop:
+    - hooks:
+        - type: command
+          command: echo "reviewer finished"
+---
+```
+
+- **范围限定**：skill 仅 `context: fork` 时支持 frontmatter hooks（注入路径无清晰生命周期边界，不接入）。
+- **`Stop` 自动转 `SubagentStop`**：agent 里写的 `Stop` event 会被转为 `SubagentStop` 以对齐 subagent 语义。
+- **安全闸门（默认关闭）**：出于安全考虑，来自**非 product 内置**来源的 frontmatter hooks 默认不会被注册，包括用户本地 `.codebuddy/agents|skills/*.md` 以及插件市场分发的 agent/skill。启用需在 `~/.codebuddy/settings.json` 中设置 `"allowUntrustedFrontmatterHooks": true`。只有 product 内置 agent/skill 自动放行。
+- **格式容错**：非法的 hook 定义会被静默丢弃，完全破损的 YAML 会在日志中输出 `Malformed YAML frontmatter in '<path>'` 诊断信息。
+
 ---
 
 通过本文档，你可以了解 CodeBuddy Code 中的 Hook 机制及其配置方式。若需快速实践示例，请继续阅读 [Hook 入门指南](./hooks-guide.md)。

package/dist/web-ui/docs/cn/cli/interactive-mode.md

@@ -17,7 +17,7 @@
 | `Ctrl+L`                                   | 清除终端屏幕                                                                             | 保留对话历史                                               | ✅ 支持        |
 | `Ctrl+O`                                   | 切换详细输出                                                                             | 显示详细的工具使用和执行信息                               | ✅ 支持        |
 | `Ctrl+R`                                   | 反向搜索命令历史                                                                         | 交互式搜索之前的命令                                       | ✅ 支持        |
-| `Ctrl+V` (macOS/Linux) 或 `Alt+V` (Windows) | 从剪贴板粘贴图片                                                                         | 粘贴图片或图片文件路径                                     | ✅ 支持        |
+| `Ctrl+V` (macOS/Linux) 或 `Alt+V` (Windows) | 从剪贴板粘贴文本或图片；Windows 上推荐用 `Alt+V` 获得更稳定的大段文本粘贴体验             | 粘贴文本、图片或图片文件路径                               | ✅ 支持        |
 | `Up/Down 方向键`                           | 导航命令历史                                                                             | 调用之前的输入                                             | ✅ 支持        |
 | `Esc` + `Esc`                              | 回退代码/对话                                                                            | 将代码和/或对话恢复到之前的状态 (需在输入框为空时连续按两次)                            | ✅ 支持      |
 | `Tab`                                      | 切换思考模式      | 在思考开启和思考关闭之间切换                               | ✅ 支持    |

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

@@ -732,6 +732,19 @@ codebuddy mcp add --scope user chrome-devtools -- npx -y chrome-devtools-mcp@lat
 codebuddy mcp add --scope user iwiki -- npx -y mcp-remote@latest https://prod.mcp.it.woa.com/app_iwiki_mcp/mcp3
 ```
 
+## 超大响应处理
+
+当 MCP 工具返回的内容超过 `MAX_MCP_OUTPUT_TOKENS`（默认 20000 tokens，约 80KB 字符数）时，CodeBuddy 会自动处理以避免占用过多上下文：
+
+- **默认行为（落盘）**：把完整响应保存到当前会话的 `~/.codebuddy/projects/<project-hash>/<session-id>/tool-results/mcp-<server>-<tool>-<timestamp>-<rand>.txt`，返回给模型一段读取指引（包含文件路径、格式说明、分段读取要求）。模型可以通过 Read 工具按 `offset` / `limit` 参数分段读取完整内容，或用 `jq` 对 JSON 结构做结构化查询。
+- **截断降级**：以下场景会直接截断内容到 `MAX_MCP_OUTPUT_TOKENS * 4` 字符上限，而不落盘：
+  - 响应包含图片块（避免 base64 payload 写入 `.txt` 文件丢失图片渲染）
+  - 当前无会话上下文（避免产生孤儿文件）
+  - 落盘失败（目录不可写、磁盘满等）
+  - 设置了环境变量 `CODEBUDDY_DISABLE_MCP_LARGE_OUTPUT_FILES=1`
+
+截断时会在内容尾部追加 `[OUTPUT TRUNCATED - exceeded N token limit]` 标记，并告知模型哪些类型的块被丢弃（例如 `[Dropped 2 audio blocks due to size limit]`），方便模型改用分页或过滤参数重试。
+
 ## 相关链接
 
 - [MCP 官方文档](https://modelcontextprotocol.io/)

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

@@ -230,7 +230,7 @@ LSP 集成提供:
 
 ## 三、插件清单架构（plugin.json）
 
-`.codebuddy-plugin/plugin.json`（或 `.claude-plugin/plugin.json`）文件定义插件的元数据和配置。本节记录所有支持的字段和选项。
+`.codebuddy-plugin/plugin.json`（或 `.workbuddy-plugin/plugin.json`、`.claude-plugin/plugin.json`）文件定义插件的元数据和配置。本节记录所有支持的字段和选项。
 
 清单是可选的。如果省略，CodeBuddy 会自动发现[默认位置](#文件位置参考)中的组件，并从目录名派生插件名称。当需要提供元数据或自定义组件路径时使用清单。
 
@@ -506,7 +506,7 @@ enterprise-plugin/
 └── CHANGELOG.md              # 版本历史
 ```
 
-> **重要**: `.codebuddy-plugin/` 目录包含 `plugin.json` 文件。所有其他目录（`commands/`、`agents/`、`skills/`、`output-styles/`、`hooks/`）必须位于插件根目录，而不是 `.codebuddy-plugin/` 内部。同时兼容 `.claude-plugin/` 目录。
+> **重要**: `.codebuddy-plugin/` 目录包含 `plugin.json` 文件。所有其他目录（`commands/`、`agents/`、`skills/`、`output-styles/`、`hooks/`）必须位于插件根目录，而不是 `.codebuddy-plugin/` 内部。同时兼容 `.workbuddy-plugin/` 与 `.claude-plugin/` 目录。
 
 ### 文件位置参考
 
@@ -811,7 +811,7 @@ CodeBuddy 插件系统在设计上兼容 Claude Code 插件规范，但存在以
 
 | 概念 | Claude Code | CodeBuddy |
 |------|-------------|-----------|
-| 元数据目录 | `.claude-plugin/` | `.codebuddy-plugin/`（优先）或 `.claude-plugin/`（兼容） |
+| 元数据目录 | `.claude-plugin/` | `.codebuddy-plugin/`（优先）、`.workbuddy-plugin/` 或 `.claude-plugin/`（兼容） |
 | 环境变量 | `${CLAUDE_PLUGIN_ROOT}` | `${CODEBUDDY_PLUGIN_ROOT}`（优先）或 `${CLAUDE_PLUGIN_ROOT}`（兼容） |
 | 数据目录变量 | `${CLAUDE_PLUGIN_DATA}` | `${CODEBUDDY_PLUGIN_DATA}`（优先）或 `${CLAUDE_PLUGIN_DATA}`（兼容） |
 

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

@@ -17,6 +17,12 @@ Release Notes 记录了每个版本的用户可见变更，包括：
 
 <!-- 新版本自动添加到此处 -->
 
+- [v2.95.0](./v2.95.0.md) - 2026-05-01
+- [v2.94.4](./v2.94.4.md) - 2026-05-01
+- [v2.94.3](./v2.94.3.md) - 2026-04-29
+- [v2.94.2](./v2.94.2.md) - 2026-04-28
+- [v2.94.1](./v2.94.1.md) - 2026-04-28
+- [v2.94.0](./v2.94.0.md) - 2026-04-28
 - [v2.93.7](./v2.93.7.md) - 2026-04-26
 - [v2.93.6](./v2.93.6.md) - 2026-04-25
 - [v2.93.5](./v2.93.5.md) - 2026-04-23

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

@@ -0,0 +1,22 @@
+# 🚀 CodeBuddy Code v2.93.7 发布
+
+## 🔧 改进优化
+
+- **主 agent 工具精简**：默认 agent 工具链聚焦到 Read / Write / Edit / Bash / PowerShell 等核心工具,删除不再默认挂载的冗余工具;用户在 settings 中自定义工具列表不受影响
+- **内建 `/commit` 与 `/commit-push-pr` 命令**：主 agent 内部委派使用,用于统一 Git 提交与 PR 打开流程;用户在 `/` 菜单中不可见
+- **Bash / Agent / Skill 工具说明精炼**:模型侧系统提示的工具描述整体瘦身,同时补充子代理提示写法与前后台选择指导
+- **长对话自动恢复**:增强上下文超限后的自动恢复稳定性,减少错误重试时的上下文处理异常;优化长会话下的预处理压缩兜底,避免压缩失败时当前输入被意外中断
+- **Cost 口径对齐**:`/cost` 展示采用业界一致的语义——`input / cacheRead / cacheWrite` 三者互不相交、相加等于总 input,避免重复计数
+- **Token 数值统一为 1000 进制**:`/cost`、`/context` 等面板中的 token 数字采用 1000 进制(k / M),与模型厂商文档保持一致
+- **跨轮 Memory 去重**:会话内已注入过的 memory 在后续轮次不再重复进入上下文,把"相关记忆"预算留给新的候选
+- **自定义 agent 的模型字段仅按 id 精确匹配**:`.codebuddy/agents/*.md` frontmatter 中 `model:` 字段若不是有效模型 id,将回落到主 agent 的当前模型,避免字面量撞名误选到用户自定义模型
+
+## 🐛 问题修复
+
+- **模型请求 502 稳定性**:改善偶发的 `502 socket hang up` 问题。为无代理场景下的 HTTPS 请求启用 TCP keep-alive,对抗中间网关 idle/NAT 超时;响应头返回前的连接级失败(ECONNRESET / socket hang up)自动透明重试一次,重试严格限制在上游尚未开始推理阶段,不会导致 token 重复计费
+
+## 📝 文档更新
+
+- **第三方模型对接示例**:`env-vars.md` / `models.md` 新增完整的端点 + 密钥 + 主/小/子代理模型配置示例,支持通过 `settings.json` 的 `env` 字段做团队统一配置
+- **`relatedModels` 字段说明**:`models.md` 补充 `relatedModels` 字段文档,介绍如何在 `lite`/`reasoning`/`vision`/`longContext`/`subagent` 等场景下关联不同模型 id
+- **权限字段边界澄清**:`iam.md` / `settings.md` 补充说明 `trustAll` / `trustedDirectories` 只影响目录信任授权提示,不会跳过工具执行权限审批,与 `permissions.defaultMode` 相互独立

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

@@ -0,0 +1,23 @@
+# 🚀 CodeBuddy Code v2.94.0 发布
+
+## ✨ 新功能
+
+### ComputerUse 工具（实验功能）
+
+新增 macOS 桌面控制能力，让 CodeBuddy Code 可以直接"看"屏幕、"点"界面：
+
+- 支持 14 种动作：截图、鼠标点击/双击/右键、拖拽、滚动、键盘输入、组合键、等待窗口出现等
+- 截图以图片形式直接返回给模型，无需再单独读取文件
+- 默认关闭，使用前需设置环境变量 `CODEBUDDY_COMPUTER_USE_ENABLED=1`
+- 首次使用键鼠动作需在系统设置 → 隐私与安全性中为终端授予"辅助功能"与"屏幕录制"权限
+
+## 🔧 改进优化
+
+- **企业微信群机器人语音转文字**：企微群 Bot 的语音消息现可自动读取服务端下发的转写文本并交给模型理解，用户不需要再手动复述；无转写文本时会给出明确提示引导用户改发文字
+- **企业微信群机器人图文同发支持**：用户在企微群里同时发图片和文字时，消息不再被静默丢弃，即便消息结构异常也会以占位符兜底，保证能进入对话
+- **AskUserQuestion 多问题场景修复**：模型在询问多个问题时，选项显示和选择稳定性大幅提升，不再出现"少了一个问题"或选项串到别的问题上的情况
+
+## 🐛 问题修复
+
+- **Hook 脚本调用服务代理**：修复 Hook 脚本通过 curl 等工具调用本地服务代理接口时，因缺少自定义请求头被拒绝的问题
+- **企业微信自建应用并发消息**：修复图文同发场景下两条消息并发到达时互相覆盖、CLI 端感知不到消息的问题

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

@@ -0,0 +1,6 @@
+# 🚀 CodeBuddy Code v2.94.1 发布
+
+## 🐛 问题修复
+
+- **DeepSeek V4+ 思考模式兼容**：修复使用 DeepSeek V4+ 模型开启思考模式时，历史对话继续发送请求会报 `invalid_request_error` 的问题，现已自动兼容处理
+- **自定义模型认证**：修复自定义模型认证问题

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

@@ -0,0 +1,5 @@
+# 🚀 CodeBuddy Code v2.94.2 发布
+
+## 🐛 问题修复
+
+- **私有化部署检测**：移除通过企业端点配置推断 Self-Hosted 部署类型的逻辑，避免在配置了企业端点但实际为云托管场景时错误地将部署类型标记为 Self-Hosted

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

@@ -0,0 +1,10 @@
+# 🚀 CodeBuddy Code v2.94.3 发布
+
+## 🔧 改进优化
+
+- **模型兼容适配增强**：模型兼容适配器新增"分段边界子串"匹配兜底规则，更好地支持 `org/xxx-model` 这类带命名空间前缀的自定义模型 ID，同时保留精确/前缀匹配优先级，避免短标识误伤
+
+## 🐛 问题修复
+
+- **DeepSeek V4+ 思考模式兼容**：修复自定义 DeepSeek V4 模型（如 `deepseek-v4-flash`）在多轮对话中报 `The reasoning_content in the thinking mode must be passed back to the API` 400 错误的问题，现在即使当前轮未显式启用思考模式，也会根据历史消息正确补齐推理字段
+- **上游错误信息可读性**：兼容 OpenAI 格式（`{error: {message, code, type}}`）的上游错误响应，使自定义模型返回的具体报错可在界面中展示，不再被统一替换为 "Server error" 占位文案

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

@@ -0,0 +1,5 @@
+# 🚀 CodeBuddy Code v2.94.4 发布
+
+## 🐛 问题修复
+
+- **自定义模型兼容性**：修复自定义模型（如 `custom-local:xxx`）在通过第三方 OpenAI 兼容接口调用时，请求体中残留的 Anthropic 风格字段（`verbosity`、`reasoning_summary`、`reasoning_effort`）导致接口返回 400 错误的问题，确保自定义模型能够正常工作

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

@@ -0,0 +1,43 @@
+# 🚀 CodeBuddy Code v2.95.0 发布
+
+## ✨ 新功能
+
+### Agent Team 能力对齐
+
+团队协作能力大幅增强，让多 agent 协作更稳定可控：
+
+- **队员空闲感知**：团队 lead 现在能精确查询每个队员的实时状态，等待指定队员空闲（支持超时和 abort signal），或注册"一旦空闲就回调"的钩子。UI 展示、任务调度、优雅关停等场景无需再订阅复杂的 stream，一个 API 调用即可获知队员状态
+- **Plan 审批用户体验对齐**：队员在 Plan 模式下结束 plan 时，审批弹窗自动显示在 lead 侧终端，带队员颜色徽章，选项为"通过 / 继续规划 / 退出 Plan 模式"三档（和常规工具审批的"通过 / 永久通过 / 拒绝"语义明确区分）
+- **优雅关停握手 + 超时兜底**：`TeamDelete` / 手动关停队员时，lead 会发送关停请求等待队员响应；若队员在默认 15 秒内无响应，自动强制终止进程，避免队员卡死导致清理流程永挂
+- **队员进度快照**：实时追踪每个队员跑了多少轮工具调用、累计生成多少文本，以及最近 10 次工具活动摘要，为 TUI/Web UI 展示"队员正在做什么"打好基础
+
+### 新增环境变量
+
+- `CODEBUDDY_TEAM_IDLE_DETECTION_DISABLED`：关闭队员空闲感知
+- `CODEBUDDY_TEAM_SHUTDOWN_GRACEFUL_TIMEOUT_MS`：关停兜底超时毫秒数（默认 15000，设为 0 禁用）
+- `CODEBUDDY_BASH_ASSISTANT_BUDGET_MS`：主对话响应预算（Bash/PowerShell 共享）
+- `CODEBUDDY_BASH_AUTO_BACKGROUND_DISABLED`：关闭超时自动后台化
+
+## 🔧 改进优化
+
+### Bash 工具
+
+- **超时自动后台化**：前台命令到 `timeout` 时不再直接杀子进程，而是自动转为后台任务继续跑，返回 `task_id` 供你用 TaskOutput（兼容旧名 BashOutput）拉取后续进度/结果。`yarn install` / `docker build` / `cargo build` / `make` 等冷跑远超默认 timeout 的长命令不再被工具层冤杀
+- **长命令引导更新**：描述模板引导你对长命令显式传 `run_in_background: true`，并说明超时不再是"kill"而是"auto-background"的新语义
+
+### PowerShell 工具
+
+- **超时自动后台化**：对齐 Bash 工具，`Invoke-WebRequest` 大文件下载、长 `Copy-Item -Recurse`、经由 PowerShell 调用的构建等冷跑超时不再被工具层冤杀
+- **后台任务状态查询**：显式传 `run_in_background: true` 的后台命令现在完整支持 TaskOutput 查询，可以和 Bash 一样拉取 stdout/stderr/status
+- **Ctrl+B 转后台**：从"未实现"占位符升级为真实功能
+- **主对话响应预算**：和 Bash 共享 `CODEBUDDY_BASH_ASSISTANT_BUDGET_MS`，超过预算自动转后台保持对话响应
+
+### 会话中断语义
+
+- Bash 与 PowerShell 工具均区分"用户主动取消"和"内部流程切换"两种中断信号；内部流程切换时不再杀掉正在跑的命令，改为尝试转为后台继续跑，避免并发调用或 turn 切换冤杀长命令
+
+## 🐛 问题修复
+
+- **PowerShell 后台任务状态更新**：转后台后任务状态现在会根据真实退出码更新为 `completed`/`failed`（之前永远停留在 `running`，TaskOutput 查询看不到最终状态）
+- **PowerShell 后台任务异常回灌**：转后台后若命令晚些时候异常终止，不再冒泡为 Node unhandledRejection 警告，错误详情会回灌到任务的 stderr 输出供 TaskOutput 查询展示
+- **PowerShell 后台文案语义准确**：返回文案准确区分超时 / 主对话预算 / Ctrl+B / 显式后台 / 内部中断五种来源，不再复用相近文案造成语义污染

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

@@ -62,6 +62,7 @@ CodeBuddy Code 使用分层配置系统，让您能够在不同级别进行个
 | `permissions` | 权限配置，见下表 | |
 | `hooks` | 配置在工具执行前后运行的自定义命令。见 [hooks 文档](hooks.md) | `{"PreToolUse": {"Bash": "echo 'Running command...'"}}` |
 | `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"` |
 | `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"}` |
@@ -80,6 +81,8 @@ CodeBuddy Code 使用分层配置系统，让您能够在不同级别进行个
 | `memory` | [Experimental] 记忆功能配置，见[记忆功能配置](#记忆功能配置experimental) | `{"enabled": true}` |
 | `trustedDirectories` | 已经信任过的工作目录列表。命中的目录启动时不会再弹"是否信任此目录"的授权提示。通常由首次启动时的弹窗自动写入，也可手动编辑 | `["~/workspace/myproj"]` |
 | `trustAll` | 信任所有工作目录，启动时不再弹"是否信任此目录"的授权提示。**仅免除目录信任授权，不会跳过工具执行权限**——是否弹工具审批仍由 `permissions.defaultMode` / `bypassPermissions` 模式决定，与本字段相互独立 | `true` |
+| `gateway` | Remote Gateway 配置，见 [Gateway 配置](#gateway-配置) | `{"runTimeoutMs": 1800000}` |
+| `disableUEAutoExclude` | 禁用 Unreal Engine 项目自动排除。默认 `false`：当 cwd 顶层存在 `*.uproject` 文件时，Grep/Glob 工具会自动在 ripgrep 搜索中排除 `Intermediate/ DerivedDataCache/ Saved/ Binaries/ Build/ .vs/` 六个 UE 编译产物和 IDE 缓存目录。设为 `true` 可关闭该行为，让搜索覆盖这些目录 | `true` |
 
 ### 权限设置
 
@@ -233,6 +236,50 @@ CodeBuddy Code 使用分层配置系统，让您能够在不同级别进行个
 
 匹配这些模式的文件将对 CodeBuddy Code 完全不可见，防止任何敏感数据的意外泄露。
 
+## Gateway 配置
+
+`gateway` 字段配置 Remote Gateway（`--serve` 模式下 HTTP/SSE 对外暴露 `/api/v1/runs` 等端点）的行为。
+
+```json
+{
+  "gateway": {
+    "auth": "none",
+    "maxConnections": 5,
+    "tokenTtlMs": 86400000,
+    "runTimeoutMs": 1800000
+  }
+}
+```
+
+| 字段 | 描述 | 默认 |
+|:-----|:-----|:-----|
+| `auth` | 认证模式。`"password"` 要求客户端携带密码，`"none"` 不做认证（仅建议 loopback 使用） | `"none"` |
+| `password` | `auth: "password"` 时的密码。为空首次启动会自动生成并打印到日志 | 自动生成 |
+| `corsOrigins` | 允许跨域访问 Gateway 的额外 Origin 列表（无需包含 loopback，loopback 自动放行） | `[]` |
+| `maxConnections` | ACP 协议最大并发连接数。环境变量 `CODEBUDDY_ACP_MAX_CONNECTIONS` 优先级更高 | `5` |
+| `tokenTtlMs` | ACP session token 有效期（毫秒）。环境变量 `CODEBUDDY_ACP_TOKEN_TTL_MS` 优先级更高 | `86400000`（24 小时）|
+| `runTimeoutMs` | `/api/v1/runs` 任务执行超时（毫秒）。超时返回 `{code:'EXECUTION_ERROR', message:'Task timed out after Xmin'}` | `1800000`（30 分钟）|
+
+### `runTimeoutMs` 覆盖优先级
+
+长任务（如复杂 agent 多轮搜索、大文件处理）可能超过默认 30 分钟，支持两种覆盖方式：
+
+1. **HTTP 请求头 `X-Codebuddy-Run-Timeout`**（毫秒数）— **针对单次请求覆盖**，优先级最高
+2. **`settings.json` 里 `gateway.runTimeoutMs`** — 进程级默认值
+3. **内置默认值** — 30 分钟
+
+示例：
+
+```bash
+# 单次请求给 60 分钟
+curl -X POST http://127.0.0.1:7890/api/v1/runs \
+  -H "Content-Type: application/json" \
+  -H "X-Codebuddy-Run-Timeout: 3600000" \
+  -d '{"id":"run-1","type":"message","payload":{"text":"..."}}'
+```
+
+设为 `0` 或负数关闭超时保护（不建议，长任务未结束会一直占用 SSE 长连接）。
+
 ## 子代理配置
 
 CodeBuddy Code 支持可在用户和项目级别配置的自定义 AI 子代理。这些子代理存储为带有 YAML frontmatter 的 Markdown 文件：

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

@@ -80,6 +80,33 @@ Skill 文件使用 Markdown 格式，支持 YAML Frontmatter 定义元数据：
 | `context` | 否 | 设置为 `fork` 时，Skill 在独立的 subagent 上下文中执行 | `fork` |
 | `agent` | 否 | 指定 subagent 类型，仅在 `context: fork` 时有效 | `Explore` |
 
+## 变量占位符
+
+SKILL.md 内容支持以下占位符，加载或执行时自动替换。同样的占位符也适用于自定义斜杠命令和 subagent 定义。
+
+| 占位符 | 替换为 | 适用来源 |
+|------|------|------|
+| `${CODEBUDDY_PLUGIN_ROOT}` | 插件安装根目录 | 仅插件来源的 skill |
+| `${CODEBUDDY_SKILL_DIR}` | 当前 SKILL.md 所在目录的绝对路径 | 所有来源 |
+| `${CODEBUDDY_SESSION_ID}` | 当前会话 ID（运行时注入） | 所有来源 |
+| `${MY_ENV_VAR}` 等大写环境变量 | `process.env.MY_ENV_VAR` 的值 | 所有来源 |
+| `${MY_ENV_VAR:-默认值}` | 环境变量，缺失时使用默认值 | 所有来源 |
+
+为与 Claude Code 保持兼容，`${CLAUDE_PLUGIN_ROOT}`、`${CLAUDE_SKILL_DIR}`、`${CLAUDE_SESSION_ID}` 也被识别为等价的别名。
+
+未设置的环境变量占位符会原样保留，不会被替换为空字符串；用户或项目来源的 skill 中 `${CODEBUDDY_PLUGIN_ROOT}` 会保留字面量（该变量仅适用于插件来源）。
+
+**示例**：
+
+```markdown
+---
+description: 带占位符的 skill 示例
+---
+
+读取脚本 @${CODEBUDDY_SKILL_DIR}/scripts/analyze.py 并使用密钥 ${MY_API_TOKEN:-dev-fallback} 执行。
+当前会话标识：${CODEBUDDY_SESSION_ID}
+```
+
 ## 执行 Shell 命令
 
 与[斜杠命令](slash-commands.md)一样，Skills 也支持在 SKILL.md 中使用 `!`command`` 语法内联执行 Shell 命令。当 Skill 被触发时（无论是 AI 自动调用还是用户通过 `/skill-name` 手动触发），这些命令会被执行，输出结果会替换到 Skill 内容中，供 AI 后续分析。

package/dist/web-ui/docs/en/cli/bash-sandboxing.md

@@ -136,6 +136,17 @@ git push
 # 3. All commands in non-AcceptEdits mode
 ```
 
+## Sandbox Bypass Auto-Approval in Bypass Permission Mode
+
+When a command attempts to cross sandbox boundaries (for example, writing to `.git/refs/*.lock`, or the model invokes Bash with `dangerouslyDisableSandbox=true`), the sandbox triggers a secondary "run this command outside the sandbox?" approval prompt.
+
+Starting from v2.90.x, in `bypassPermissions` permission mode, such sandbox bypass approvals are automatically granted for **non-high-risk commands**, avoiding repeated approval prompts for routine combined commands like `cd X && yarn build`:
+
+* ✅ **Auto-approved**: When the command's safety level is SAFE / LOW / MEDIUM, it directly continues execution as `allow_once`
+* ⛔ **Still requires confirmation**: When the command's safety level is HIGH / CRITICAL (such as `rm -rf /`, `chmod 777 /etc`, etc.), interactive approval is preserved even in bypass mode
+
+This policy is consistent with the protection semantics for dangerous Bash commands in bypass mode—`bypassPermissions` does not mean blind approval; high-risk operations always require explicit confirmation.
+
 ### Security Guarantees
 
 Sandbox auto-approval improves efficiency while maintaining security:

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

@@ -39,6 +39,8 @@ CodeBuddy Code supports environment variables to control its behavior. These var
 | `BASH_DEFAULT_TIMEOUT_MS` | Default timeout for long-running bash commands (default: 120000) |
 | `BASH_MAX_OUTPUT_LENGTH` | Maximum characters of bash output retained in memory (default: 30000, max: 150000). Content exceeding the limit is mid-truncated (keeping head 20% + tail 80%), and the full output is automatically saved to disk |
 | `BASH_MAX_TIMEOUT_MS` | Maximum timeout the model can set for long-running bash commands (default: 600000) |
+| `CODEBUDDY_BASH_ASSISTANT_BUDGET_MS` | Main conversation response budget (milliseconds, default `0`=off). When set to `>0`, foreground Bash/PowerShell commands in the main session that exceed this duration are automatically converted into background tasks to keep the conversation responsive. Sub-agents are not affected by this budget. Aligns with Claude Code's `ASSISTANT_BLOCKING_BUDGET_MS` (CC's official default value `15000`) |
+| `CODEBUDDY_BASH_AUTO_BACKGROUND_DISABLED` | Set to `1` to disable timeout auto-backgrounding; foreground commands fall back to the old SIGTERM/kill hard-kill behavior on timeout. Only used for debugging or temporary rollback when encountering regressions; keep the default (unset) in normal scenarios |
 
 ## Tool Output Externalization
 
@@ -58,6 +60,7 @@ CodeBuddy Code supports environment variables to control its behavior. These var
 | `CODEBUDDY_PLUGIN_DIRS` | Colon-separated list of local plugin directory paths (equivalent to `--plugin-dir`). The `bin/` directory of each plugin is automatically injected into `PATH` |
 | `CODEBUDDY_IMAGE_GEN_ENABLED` | Set to `false` or `0` to disable image generation |
 | `CODEBUDDY_IMAGE_EDIT_ENABLED` | Set to `false` or `0` to disable image editing |
+| `CODEBUDDY_COMPUTER_USE_ENABLED` | **Experimental**: Set to `true` or `1` to enable the macOS desktop control tool (screenshot, mouse, keyboard). Available only on macOS, disabled by default. The first invocation of keyboard/mouse actions requires authorizing the terminal in System Settings → Privacy & Security → Accessibility and Screen Recording |
 | `CODEBUDDY_DEFER_TOOL_LOADING` | Set to `false` or `0` to disable MCP tool deferred loading |
 | `CODEBUDDY_SHOW_ALL_DEFERRED_TOOLS` | Set to `true` or `1` to show full descriptions for all deferred tools |
 | `CODEBUDDY_DISABLE_CRON` | Set to `1` to disable scheduled tasks |
@@ -82,6 +85,7 @@ CodeBuddy Code supports environment variables to control its behavior. These var
 | `MCP_TIMEOUT` | Timeout for MCP server connections (milliseconds) |
 | `MCP_TOOL_TIMEOUT` | Timeout for MCP tool execution (milliseconds) |
 | `MAX_MCP_OUTPUT_TOKENS` | Maximum tokens allowed in MCP tool responses (default: 20000) |
+| `CODEBUDDY_DISABLE_MCP_LARGE_OUTPUT_FILES` | When set to `1`, MCP oversized responses are not persisted to disk (skipping the `~/.codebuddy/projects/.../tool-results/` files), always falling back to content truncation |
 
 ## Performance and Output
 
@@ -162,6 +166,8 @@ CodeBuddy Code supports environment variables to control its behavior. These var
 | `CODEBUDDY_CODE_MAX_TURNS` | Maximum execution turns for the main Agent. Priority: CLI `--max-turns` > this environment variable > default (500) |
 | `CODEBUDDY_CODE_SUBAGENT_MAX_TURNS` | Maximum execution turns for sub-Agents. Priority: CLI `--max-turns` > this environment variable > model dynamically passed `max_turns` > default (500) |
 | `CODEBUDDY_SUBAGENT_PERMISSION_MODE` | Default permission mode for sub-agents/team members (e.g., `bypassPermissions`, `acceptEdits`, `default`, `plan`). Priority: Agent tool `mode` parameter > CLI `--subagent-permission-mode` > this environment variable > Settings `permissions.subagentPermissionMode` > mapping table default |
+| `CODEBUDDY_TEAM_IDLE_DETECTION_DISABLED` | Set to `1` to disable teammate idle awareness (enabled by default). When disabled, "wait for teammate idle"-type APIs return `true` immediately without blocking, and progress snapshots are no longer recorded |
+| `CODEBUDDY_TEAM_SHUTDOWN_GRACEFUL_TIMEOUT_MS` | Fallback timeout (in milliseconds) for graceful team member shutdown, default `15000`. After this duration without a response from the teammate, the process is forcibly terminated. Set to `0` to disable the forced fallback (pure wait for response) |
 
 ## Gateway and Remote Access
 

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

@@ -796,6 +796,33 @@ Progress messages appear in transcript mode (Ctrl+R), showing:
 - Success/failure status
 - Output or error messages
 
+## Agent / Skill Frontmatter Hooks
+
+In addition to hooks configured via the global `~/.codebuddy/settings.json`, you can declare a `hooks` field directly in the YAML frontmatter of a custom agent `.md` file or a skill's `SKILL.md`. These hooks only take effect during the lifecycle of the corresponding subagent or forked skill, and are automatically cleaned up when it ends.
+
+```yaml
+---
+name: my-reviewer
+description: Code reviewer with pre-tool-use guard
+hooks:
+  PreToolUse:
+    - matcher: Bash
+      hooks:
+        - type: command
+          command: ./guard.sh
+          once: true
+  SubagentStop:
+    - hooks:
+        - type: command
+          command: echo "reviewer finished"
+---
+```
+
+- **Scoping**: Frontmatter hooks are only supported on skills when `context: fork` (the injection path lacks a clear lifecycle boundary and is not wired in).
+- **`Stop` auto-converted to `SubagentStop`**: `Stop` events written in an agent are converted to `SubagentStop` to align with subagent semantics.
+- **Safety gate (disabled by default)**: For security reasons, frontmatter hooks from **non-product-builtin** sources are not registered by default. This includes user-local `.codebuddy/agents|skills/*.md` as well as agents/skills distributed via the plugin marketplace. To enable them, set `"allowUntrustedFrontmatterHooks": true` in `~/.codebuddy/settings.json`. Only product-builtin agents/skills are automatically allowed.
+- **Format tolerance**: Invalid hook definitions are silently dropped. Completely broken YAML produces a `Malformed YAML frontmatter in '<path>'` diagnostic in the logs.
+
 ---
 
 With this guide you should have a complete understanding of how hooks work inside CodeBuddy Code and how to configure them safely. For a hands-on walkthrough, continue with the [Hooks Getting Started Guide](./hooks-guide.md).

package/dist/web-ui/docs/en/cli/interactive-mode.md

@@ -17,7 +17,7 @@
 | `Ctrl+L`                                   | Clear terminal screen                                                                    | Preserves conversation history                             | ✅ Supported      |
 | `Ctrl+O`                                   | Toggle verbose output                                                                    | Display detailed tool usage and execution information      | ✅ Supported      |
 | `Ctrl+R`                                   | Reverse search command history                                                           | Interactive search of previous commands                    | ✅ Supported      |
-| `Ctrl+V` (macOS/Linux) or `Alt+V` (Windows) | Paste image from clipboard                                                             | Paste image or image file path                             | ✅ Supported      |
+| `Ctrl+V` (macOS/Linux) or `Alt+V` (Windows) | Paste text or image from clipboard; on Windows, `Alt+V` is recommended for a more reliable experience when pasting large blocks of text | Paste text, image, or image file path                      | ✅ Supported      |
 | `Up/Down Arrow Keys`                       | Navigate command history                                                                 | Recall previous inputs                                     | ✅ Supported      |
 | `Esc` + `Esc`                              | Rewind code/conversation                                                                 | Restore code and/or conversation to previous state (requires pressing ESC twice consecutively when the input box is empty) | ✅ Supported      |
 | `Tab`                                      | Toggle thinking mode                                                                     | Switch between thinking on and thinking off                | ✅ Supported      |

package/dist/web-ui/docs/en/cli/mcp.md

@@ -732,6 +732,19 @@ codebuddy mcp add --scope user chrome-devtools -- npx -y chrome-devtools-mcp@lat
 codebuddy mcp add --scope user iwiki -- npx -y mcp-remote@latest https://prod.mcp.it.woa.com/app_iwiki_mcp/mcp3
 ```
 
+## Handling Oversized Responses
+
+When the content returned by an MCP tool exceeds `MAX_MCP_OUTPUT_TOKENS` (default 20,000 tokens, approximately 80KB of characters), CodeBuddy automatically handles it to avoid consuming excessive context:
+
+- **Default behavior (write to disk)**: The full response is saved to the current session's `~/.codebuddy/projects/<project-hash>/<session-id>/tool-results/mcp-<server>-<tool>-<timestamp>-<rand>.txt`, and the model receives a read instruction (including the file path, format description, and chunk-reading requirements). The model can read the full content in chunks via the Read tool using `offset` / `limit` parameters, or perform structured queries on JSON content using `jq`.
+- **Truncation fallback**: In the following scenarios, the content is truncated directly to `MAX_MCP_OUTPUT_TOKENS * 4` characters without writing to disk:
+  - The response contains image blocks (to avoid losing image rendering when base64 payloads are written into a `.txt` file)
+  - There is no current session context (to avoid creating orphan files)
+  - Writing to disk fails (directory not writable, disk full, etc.)
+  - The environment variable `CODEBUDDY_DISABLE_MCP_LARGE_OUTPUT_FILES=1` is set
+
+When truncation occurs, `[OUTPUT TRUNCATED - exceeded N token limit]` is appended to the end of the content, and the model is informed which types of blocks were dropped (e.g. `[Dropped 2 audio blocks due to size limit]`), making it easier for the model to retry with paging or filter parameters.
+
 ## Related Links
 
 - [MCP Official Documentation](https://modelcontextprotocol.io/)