@tencent-ai/agent-sdk 0.3.169 → 0.3.171

package/cli/dist/web-ui/docs/cn/cli/permission-modes.md

@@ -0,0 +1,260 @@
+# 权限模式（Permission Mode）
+
+> 控制 CodeBuddy 在编辑文件、运行命令、发起网络请求前要不要先停下来询问。模式决定整段会话的节奏：保守模式逐次审批，宽松模式让 CodeBuddy 长时间不打断地推进、最后回报。敏感操作选严格、信任方向时选宽松。
+
+## 可用模式
+
+CodeBuddy Code 实际定义在 `src/node/settings/settings-protocol.ts::PermissionMode` 枚举里的所有模式如下。其中前 4 个是 CLI 直接面向用户的，后 4 个属于程序化/集成场景。
+
+### 用户可手动切换的模式
+
+| 模式                                                         | 不询问就能跑什么                                                                                              | 适用场景                                              |
+| :----------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------- |
+| `default`                                                    | 信任目录内的 Read 工具                                                                                        | 默认；适合敏感工作 / 上手期                            |
+| [`acceptEdits`](#auto-edits自动批准文件编辑)                  | 信任目录内的 Read + Edit 系列工具                                                                             | 边写边走 git diff 复核                                |
+| [`plan`](#plan探索后再改)                                     | 委托给"进入 plan 前"的那个模式（默认 = `default`）；额外允许写入会话计划文件                                  | 落手改动前先摸清代码再决定                            |
+| [`bypassPermissions`](#bypasspermissions跳过所有检查)         | 全部工具，无询问                                                                                              | 沙箱容器 / VM / 离线 dev container 才用               |
+| [`delegate`](#delegate多代理协调模式)                         | 仅协调类工具（如 Agent / TaskCreate / SendMessage / 团队管理），实现类工具被装配层屏蔽                         | 主代理只做拆派、把执行交给子代理                      |
+
+### 程序化 / 集成模式（不在 Shift+Tab 循环里）
+
+| 模式            | 何时出现                                                                                                                          |
+| :-------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
+| `fullAccess`    | ACP 客户端（IDE 集成）通过协议传入；语义上等价于 `bypassPermissions` 的全局放行（见 `sandbox-orchestrator.ts:946`）                 |
+| `work`          | ACP 客户端传入。Read 直接放行（不查信任目录），Edit 一律询问，Bash 仅安全命令直接放行，其他询问                                    |
+| `ignore`        | 仅在子代理（subagent / teammate）场景生效，表示"用主会话的模式，不要被子代理自己的 frontmatter 覆盖"；主会话用不到                  |
+
+## 切换权限模式
+
+模式不是用对话告诉 CodeBuddy 来切的，而是通过下面三个入口设置。
+
+### 会话中切换：Shift+Tab
+
+CLI 里按 `Shift+Tab` 在以下 5 个模式之间循环（顺序见 `input-hint-box.tsx:72`）：
+
+```
+default → bypassPermissions → acceptEdits → plan → delegate → default → ...
+```
+
+切换后会话状态栏左下角会显示当前模式：
+
+| 模式                 | 状态栏文案                              | 颜色                                |
+| :------------------- | :-------------------------------------- | :---------------------------------- |
+| `default`            | 不显示                                  | —                                   |
+| `bypassPermissions`  | `⏵⏵ bypass permissions on (shift+tab to cycle)` | warning（警示）              |
+| `acceptEdits`        | `⏵⏵ accept edits on (shift+tab to cycle)`       | info                          |
+| `plan`               | `⏸ plan mode on (shift+tab to cycle)`           | planMode                      |
+| `plan` + 前置        | `⏸ plan + accept edits (shift+tab to cycle)` 等  | planMode                      |
+| `delegate`           | `⇢ delegate mode on (shift+tab to cycle)`        | delegateMode                  |
+
+### 启动时指定：`--permission-mode`
+
+```bash
+codebuddy --permission-mode plan
+codebuddy --permission-mode acceptEdits
+codebuddy --permission-mode bypassPermissions
+codebuddy --permission-mode default
+```
+
+CLI 选项 `--permission-mode` 只接受这 4 个字面量（见 `cli-provider.ts:36`）。其他模式（`delegate` / `work` / `fullAccess` / `ignore`）不能在命令行传入。
+
+`-p`（[非交互模式](headless.md)）下同样有效：
+
+```bash
+codebuddy -p --permission-mode acceptEdits "重构 src/utils/foo.ts"
+```
+
+启动时还可以追加：
+
+- `-y` / `--dangerously-skip-permissions`：等价于 `--permission-mode bypassPermissions`，跳过全部权限检查（见 `cli-provider.ts:35`）
+
+### 持久化默认值：`defaultMode`
+
+写到 `~/.codebuddy/settings.json` 或仓库 `.codebuddy/settings.json`：
+
+```json
+{
+  "permissions": {
+    "defaultMode": "acceptEdits"
+  }
+}
+```
+
+启动时同时给 `--permission-mode` 时，CLI 参数优先（见 `stream-json-view.ts:525` 的 fallback 链：`session 当前值 → permissions.defaultMode → PermissionMode.Default`）。
+
+### 计划进入前的"前置模式"自动记忆
+
+进入 `plan` 时，CodeBuddy 会把当前模式保存到 `session.meta.prePlanPermissionMode`，离开 plan 时还原。这意味着：
+
+- 你在 `acceptEdits` 下按 `Shift+Tab` 进 `plan`，plan 期间 Read/Edit/Bash 的审批策略仍然按 `acceptEdits` 的规则做（计划文件除外，永不询问）
+- 离开 plan 时回到 `acceptEdits`，不会被强行掉到 `default`
+
+实现见 `tool-permission-strategy.ts:92` 的 `delegateToPrePlanStrategy`。
+
+## 各模式语义详解
+
+### default（默认）
+
+逐次审批模式，是初学者和处理敏感工作时的安全选项。
+
+| 工具类型 | 决定                                                                                                |
+| :------- | :-------------------------------------------------------------------------------------------------- |
+| Read     | 路径在信任目录内（cwd + `permissions.additionalDirectories` + 用户加的 `addDir`）→ 放行；否则询问  |
+| Edit     | 一律询问                                                                                            |
+| Bash     | 一律询问                                                                                            |
+| 其他     | 一律询问                                                                                            |
+
+### acceptEdits（自动批准文件编辑）
+
+适合"想边写边过 diff，不想被每个 Edit 弹窗打断"。
+
+| 工具类型 | 决定                                                                                                |
+| :------- | :-------------------------------------------------------------------------------------------------- |
+| Read     | 信任目录内 → 放行；否则询问                                                                        |
+| Edit     | **一律放行**                                                                                        |
+| Bash     | 一律询问                                                                                            |
+| 其他     | 一律询问                                                                                            |
+
+注意：
+
+- 仅自动批准 **`Edit` 类工具**（Edit / Write / NotebookEdit 等），不影响 Bash —— Bash 永远走单独的安全分级（`command-utils.ts::checkCommandSafety`）
+- "信任目录"以工作区根 + 用户配置的 `permissions.additionalDirectories` + 启动时 `--add-dir` 为准（见 `permission-utils.ts:561`）
+- 读写[受保护文件](#受保护的关键文件)仍照原模式询问，不走自动放行
+
+### plan（探索后再改）
+
+CodeBuddy 在 plan 模式下专心读代码、跑只读 Bash 命令探查，把方案写成计划再回来征求你的同意；不会落地修改你的源码。
+
+实现思路见 `tool-permission-strategy.ts:75` —— plan 模式不是独立的"全块只读"，而是**委托给前置模式**：
+
+- Read：把决定权交给前置模式（默认是 `default`）
+- Edit：先判断目标路径是否就是当前 session 的**计划文件**（`PlanStorageService.getPlanFilePath`）→ 是则放行；否则委托给前置模式
+- Bash：委托给前置模式
+- 进入 plan 通过 `Shift+Tab` 或工具 `EnterPlanMode`；退出通过再次 `Shift+Tab` 或 `ExitPlanMode`（见 `enter-planmode-tool.ts:94`、`exit-planmode-tool.ts:73`）
+
+启动时直接进 plan：
+
+```bash
+codebuddy --permission-mode plan
+```
+
+### bypassPermissions（跳过所有检查）
+
+字面意思：**全部跳过审批**。所有 Bash、Edit、网络、MCP 都立刻执行。仅在以下场景使用：
+
+- 隔离的容器 / VM / dev container
+- 没有外网的 sandbox
+- 你完全清楚后果的脚本化场景
+
+启动方式：
+
+```bash
+codebuddy --permission-mode bypassPermissions
+# 等价
+codebuddy -y
+codebuddy --dangerously-skip-permissions
+```
+
+#### 关闭通道（管理员）
+
+把 `permissions.disableBypassPermissionsMode: "disable"` 写到任一层 settings：
+
+```json
+{
+  "permissions": {
+    "disableBypassPermissionsMode": "disable"
+  }
+}
+```
+
+写入后即使会话切到 `bypassPermissions`，权限策略也会**降级回 `default` 的判定**（见 `tool-permission-strategy.ts:192`）；多层 settings 任一层关掉即生效（user / project / local / cli flagSettings 任一层为 `"disable"` 即生效，见 `tool-permission-service.ts:670`）。
+
+### delegate（多代理协调模式）
+
+主代理在 `delegate` 模式下**只能调度**：发任务、起子代理、跨成员通信，自己不动手编辑或跑命令。
+
+实现思路：
+
+- 装配层（tool-manager）会把"实现类工具"（Read/Write/Edit/Bash 等）从主代理的可用工具集里去掉
+- 进到 `delegate` 策略层（`tool-permission-strategy.ts:244`）的就只剩协调类工具（Agent / TaskCreate / SendMessage 等），全部自动放行
+
+适合的场景：你明确要做"主代理只规划、各专业子代理实施"的协作任务（[Agent Teams](agent-teams.md) / [子代理](sub-agents.md)）。
+
+按 `Shift+Tab` 循环到 `delegate` 即可进入。
+
+### work（IDE 集成）
+
+由 ACP 客户端（IDE 扩展）通过协议设置（见 `acp-agent.ts:3407`），CLI 用户不直接接触。语义：
+
+| 工具类型 | 决定                                                                                |
+| :------- | :---------------------------------------------------------------------------------- |
+| Read     | **直接放行**（不检查信任目录）                                                      |
+| Edit     | 一律询问                                                                            |
+| Bash     | 安全命令（`checkCommandSafety` 标记为 `isSafe && !requiresApproval`）放行；其他询问 |
+| 其他     | 放行                                                                                |
+
+### fullAccess（IDE 集成）
+
+仅 ACP 协议传入；与 `bypassPermissions` 同语义（沙箱编排器把它和 `BypassPermissions` 一起短路放行，见 `sandbox-orchestrator.ts:946`）。
+
+### ignore（子代理专用）
+
+仅子代理的 frontmatter / option 用到 —— 子代理把 `permissionMode: ignore` 写在自己的元信息里时，agent-task 装配会把它当作"不要覆盖父代理的模式"，沿用父会话当前模式（见 `agent-task.ts:1009`）。主会话不会出现这个值。
+
+## 受保护的关键文件
+
+下列路径的写入操作即使在 `acceptEdits` / `bypassPermissions` 也会保留特殊处理（与 cc 对齐）：
+
+- 仓库自身：`.git`、`.gitconfig`、`.gitmodules`
+- shell 配置：`.bashrc` / `.bash_profile` / `.zshrc` / `.zprofile` / `.envrc` 等
+- 包管理：`.npmrc` / `.yarnrc` / `.pnpmfile.cjs` / `bunfig.toml` 等
+- IDE / 工具：`.vscode` / `.idea` / `.husky` / `.devcontainer` / `.cargo` / `.yarn` / `.mvn`
+- CodeBuddy 自身：`.codebuddy`（除 `.codebuddy/worktrees`）
+- MCP / 配置：`.mcp.json` / `.codebuddy.json`
+
+具体清单与判定逻辑以 `tool-permission-service.ts` 为准。
+
+## 子代理的权限模式继承
+
+子代理（[Agent](sub-agents.md) 工具调用、[Agent Teams](agent-teams.md) 队员）默认继承主会话的权限模式。要在团队 / 项目层强制覆盖：
+
+```json
+{
+  "permissions": {
+    "subagentPermissionMode": "bypassPermissions"
+  }
+}
+```
+
+写入后所有子代理都会按 `bypassPermissions` 跑（实现见 `agent-task.ts:1009` 的优先级链）。注意：
+
+- Agent 工具调用时显式传 `mode` 参数 → **优先级最高**，覆盖此设置
+- 子代理 frontmatter 里写 `permissionMode: ignore` → 仍按主会话模式跑（不被本设置影响）
+
+## 与 Permissions 规则配合
+
+权限模式定义"基线"。在 `~/.codebuddy/settings.json` 或仓库 `.codebuddy/settings.json` 的 `permissions` 下还可以叠加规则：
+
+```json
+{
+  "permissions": {
+    "defaultMode": "default",
+    "allow": ["Bash(npm test)", "Read(/etc/hosts)"],
+    "ask": ["WebFetch"],
+    "deny": ["Bash(rm -rf *)", "Edit(.git/**)"]
+  }
+}
+```
+
+- `allow` / `ask` / `deny` 三层优先级高于 mode 的判定（除 `bypassPermissions` 整段跳过权限层）
+- 详细规则语法见 [Settings 配置](settings.md)、[安全](security.md) 与 [IAM](iam.md)
+
+## 相关资源
+
+- [Agent Teams：多代理协作](agent-teams.md)：在 `delegate` 模式下让主代理专注调度
+- [子代理（Sub-agents）](sub-agents.md)：子代理的工具与权限模式继承
+- [Hooks 钩子系统](hooks-guide.md)：用 `PreToolUse` 钩子做自定义放行 / 拦截
+- [Bash 沙箱化](bash-sandboxing.md)：在 Bash 命令层加文件系统 / 网络隔离
+- [Settings 配置](settings.md)：权限规则、信任目录、`disableBypassPermissionsMode` 等完整字段
+- [CLI 参考](cli-reference.md)：`--permission-mode` / `-y` / `--add-dir` 等启动参数
+- [非交互模式](headless.md)：`-p` 流程下使用权限模式

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

@@ -0,0 +1,380 @@
+# 权限规则（Permissions）
+
+> 用细粒度的 allow / ask / deny 规则、权限模式与多层 settings 精准约束 CodeBuddy Code 能做什么。规则可以提交到版本库与团队共享，也可以由开发者本地覆盖。
+
+## 权限系统概览
+
+CodeBuddy Code 用一套分层评估机制平衡能力与安全。它在主代理执行任何工具调用前都会过一次权限服务（`tool-permission-service.ts::checkToolPermission`），8 个 Phase 顺序判定：
+
+| Phase | 检查项 | 命中后行为 |
+| :---- | :---- | :--------- |
+| 1 | **Deny 规则** | 立刻拒绝，最高优先级 |
+| 2 | **可信 Allow 规则**（user / cli / flag / session / policy / 信任目录下的 project / `--allowedTools`） | 立刻放行，**可越过命令安全检查** |
+| 3 | **命令安全检查**（`checkCommandSafety`，仅交互式） | 高危/危险命令强制询问 |
+| 4 | **Ask 规则** | 强制询问 |
+| 5 | **Bypass 模式短路** | `bypassPermissions` 模式直接放行；`disableBypassPermissionsMode` 已禁用时降级 default |
+| 6 | **不可信 Allow 规则**（不在信任目录的 project / local，以及 command / sandbox 来源） | 放行，但**不能越过命令安全检查** |
+| 7 | **权限模式策略**（`tool-permission-strategy.ts`） | 按当前 [PermissionMode](permission-modes.md) 决定是否需要审批 |
+| 8 | dontAsk / async agent 兜底 | print / 异步代理场景把 `ask` 转成 `deny` 避免死锁 |
+
+> **要点**：deny 永远优先，且分"可信 / 不可信" allow 两层 —— 项目根目录被列入信任目录前，`.codebuddy/settings.json` 的 allow 规则**不能越过命令安全门**。这是与 cc 不一样的地方，目的是防止恶意仓库把自己的 settings 推到团队 PR 时绕过本地安全保护。
+
+读类工具（Read / Grep / Glob 等）默认在信任目录内不弹审批，编辑类与 Bash 一律走完整 Phase 链。具体在 `tool-permission-strategy.ts::ToolPermissionDefaultStrategy` 与 `permission-utils.ts::isArgsInTrustedDirectories`。
+
+## 规则的三种行为
+
+`permissions` 对象下三个数组对应三种行为：
+
+```json
+{
+  "permissions": {
+    "allow": ["Bash(npm test)", "Read(/tmp/data/**)"],
+    "ask":   ["WebFetch"],
+    "deny":  ["Bash(rm -rf *)", "Edit(.git/**)"]
+  }
+}
+```
+
+- **`allow`**：CodeBuddy 可使用且无需弹审批
+- **`ask`**：每次使用都弹审批
+- **`deny`**：绝不能使用
+
+## 在哪里管理规则
+
+### `/permissions` 命令
+
+会话里输入 `/permissions` 打开权限管理面板（命令实现见 `permissions-command-executor.ts`），可以查看当前所有 allow / ask / deny 规则、它们来自哪一层 settings，并临时增删（写到 user / project 或 project-local 任一作用域）。
+
+弹窗里勾选 **"Yes, don't ask again"** 时，CodeBuddy 会把当前命令对应的最稳前缀写入对应作用域 settings 的 `allow` 数组。
+
+### CLI 启动参数
+
+| 参数 | 作用 |
+| :--- | :--- |
+| `--allowedTools <tools...>` | 进程级临时 allow 规则。空格或逗号分隔。例：`--allowedTools "Bash(git:*) Edit"` |
+| `--disallowedTools <tools...>` | 进程级临时 deny 规则。同上 |
+| `--add-dir <path>` | 把额外目录加入信任目录范围（影响 Read 是否需要弹询问） |
+| `-y` / `--dangerously-skip-permissions` | 等价于 `--permission-mode bypassPermissions` |
+
+定义见 `cli-provider.ts:40-55`。
+
+### 配置文件
+
+详见 [Settings 配置](settings.md)。CodeBuddy 按这 4 个作用域合并：
+
+| 作用域 | 路径 |
+| :----- | :--- |
+| user | `~/.codebuddy/settings.json` |
+| project | `<repo>/.codebuddy/settings.json`（提交进 git） |
+| project-local | `<repo>/.codebuddy/settings.local.json`（不进 git，本地覆盖） |
+| cliArg / flagSettings / session / policySettings | 进程态，不落盘 |
+
+具体合并代码见 `tool-permission-service.ts:647-741`。
+
+## 规则语法
+
+规则形态：`Tool` 或 `Tool(specifier)`。
+
+### 整体匹配某个工具
+
+去掉括号匹配工具的所有调用：
+
+| 规则 | 含义 |
+| :--- | :--- |
+| `Bash` | 所有 Bash 命令 |
+| `WebFetch` | 所有 web 抓取 |
+| `Read` | 所有文件读 |
+| `Edit` | 所有文件编辑 |
+
+`*` 也可以单独作为规则（`permission-utils.ts:194` 把它当成全匹配通配）。
+
+### 加 specifier 做细粒度
+
+在括号里写参数：
+
+| 规则 | 匹配 |
+| :--- | :--- |
+| `Bash(npm run build)` | 精确匹配 `npm run build` |
+| `Bash(npm:*)` 或 `Bash(npm *)` | `npm` 开头的所有命令 |
+| `Read(./.env)` | 当前目录的 `.env` |
+| `Edit(/src/**/*.ts)` | 项目根下 `src/**/*.ts` |
+| `Read(~/.zshrc)` | 用户目录的 `.zshrc` |
+| `Read(//tmp/scratch.txt)` | 文件系统绝对路径 `/tmp/scratch.txt` |
+| `WebFetch(domain:example.com)` | 抓取 example.com |
+| `mcp__puppeteer__navigate` | MCP 工具 puppeteer 服务的 navigate |
+| `Agent(Explore)` | 子代理 Explore |
+
+## 工具特定规则
+
+### Bash
+
+Bash 规则支持三种语法（实现见 `permission-utils.ts::matchSingleCommandAgainstPattern`，`414-450 行`）：
+
+| 语法 | 含义 | 示例 |
+| :--- | :--- | :--- |
+| 精确匹配 | pattern 完全等于命令 | `Bash(npm run build)` 仅匹配 `npm run build` |
+| `:*` 前缀 | pattern 末尾 `:*` → 匹配命令第一个词 / 多词前缀 | `Bash(git:*)` 匹配 `git status` / `git push origin main` |
+| 通配符 | pattern 含 `*` 时走 picomatch bash 模式（**`*` 可跨 `/`**） | `Bash(npm run *)` 匹配 `npm run build`；`Bash(ls *)` 匹配 `ls -al /tmp/x` |
+
+> 与 minimatch 不同，cbc Bash 通配符模式刻意启用 `bash: true`，让 `*` 能跨越 `/` —— 否则 `ls *` 无法匹配 `ls -al /xxx`，这是用户最常踩的坑（见 `permission-utils.ts:441-446` 的注释）。
+
+#### 复合命令
+
+CodeBuddy 用 `CommandParserService`（优先级：tree-sitter > shell-quote > regex 兜底，见 `permission-utils.ts:357-378`）解析 shell 操作符 `&&` / `||` / `;` / `|`，对每个子命令独立判定：
+
+- **deny / ask 规则**：任一子命令命中即触发（`matchCommandRule`，`305-334 行`）
+- **allow 规则**：要求**所有子命令都命中**才放行（`isCommandAllowed`，`478-500 行`）。这是和 cc 不一样的取舍 —— 一个命中、一个不命中的复合命令仍会询问，避免攻击者把危险命令藏在被允许的命令旁边
+
+举例：
+
+```text
+allow: ["Bash(git:*)"]
+
+git status         → 允许
+git status && rm * → 询问（rm * 不在 allow 内,需所有子命令都命中)
+git status; rm *   → 询问（同上)
+```
+
+#### 重定向
+
+包含 `>` / `<` / `>>` / `<<` / `&>` 的命令在 allow 规则下要求**精确匹配**（`permission-utils.ts:482-485`），通配符规则不生效。
+
+### Read / Edit / Write
+
+文件类规则用 `minimatch` 做 glob 匹配，并做了三层路径归一（`permission-utils.ts::matchFileRule` 和 `normalizePath`，`241-268 行`）：
+
+| pattern | 解释 | 示例 |
+| :------ | :--- | :--- |
+| `//path` | 文件系统绝对路径 | `Read(//etc/hosts)` |
+| `~/path` | 用户目录起 | `Read(~/.zshrc)` |
+| `/path` | 项目根起 | `Edit(/src/**/*.ts)` |
+| `path` 或 `./path` | 当前工作目录起 | `Read(.env)` |
+
+匹配开关：`dot: true`（允许点开头）、`nocase: true`（不区分大小写）、`matchBase: true`（裸文件名可匹配任意深度）。
+
+注意：
+
+- `Edit(.git/**)` 之类的 deny 规则会阻挡所有走 Edit / Write / NotebookEdit 的尝试；但**不阻挡**通过 Bash 跑 `python -c 'open(".git/config", "w")...'` 这类间接路径 —— 操作系统级保护需要靠 [Bash 沙箱](bash-sandboxing.md)
+- Read 规则同样会被部分 Bash 文件读命令（`cat`、`head`、`tail` 等）拦截解析（见 `command-utils.ts::checkCommandSafety` 内部对这类命令的特殊识别）
+
+### WebFetch
+
+```text
+WebFetch                       # 任何 URL
+WebFetch(domain:example.com)   # 仅 example.com 及子域
+```
+
+匹配实现见 `permission-utils.ts::matchURLRule`（`515 行`），支持 `domain:` 前缀做主机名匹配。
+
+### MCP 工具
+
+MCP 工具命名格式：`mcp__<server>__<tool>`。规则三种粒度：
+
+| 规则 | 匹配 |
+| :--- | :--- |
+| `mcp__puppeteer` | 整个 puppeteer server 的所有工具 |
+| `mcp__puppeteer__*` | 同上（通配符写法） |
+| `mcp__puppeteer__navigate` | 仅 navigate 工具 |
+
+`tool-permission-service.ts:152` 起判定 `tool.name.startsWith('mcp__')`，进入 MCP 专用分支。
+
+### Agent（子代理）
+
+```json
+{
+  "permissions": {
+    "deny": ["Agent(Explore)", "Agent(Plan)"]
+  }
+}
+```
+
+也可用 CLI flag：
+
+```bash
+codebuddy --disallowedTools "Agent(Explore) Agent(Plan)"
+```
+
+被 deny 后主代理调起 Agent 工具时该 `subagent_type` 会被拒。
+
+### Skill
+
+```json
+{
+  "permissions": {
+    "deny": ["Skill(dangerous-skill-name)"]
+  }
+}
+```
+
+Skill 规则**必须**是精确匹配（`permission-utils.ts::matchSkillRule`，`458-464 行`），不支持通配符。
+
+## 信任目录
+
+CodeBuddy 默认认为只有**当前工作目录**是受信任的。Read 工具在受信目录内放行，受信外询问；Edit / Bash 永远走完整审批（除非有 allow 规则或处于宽松模式）。
+
+扩大信任范围的几种方式：
+
+| 方式 | 持久度 |
+| :--- | :--- |
+| `--add-dir <path>` 启动参数 | 进程级 |
+| 会话内 `/add-dir` 命令 | 会话级 |
+| `permissions.additionalDirectories` 配置项 | 持久化 |
+| `permissions.trustedDirectories` 配置项 | 持久化 |
+
+实现见 `permission-utils.ts:561-583`：信任目录列表 = `工作区根 + settings.trustedDirectories + session.options.addDir`。
+
+> `--add-dir` 和 `permissions.additionalDirectories` 都只授予**文件访问权**，**不会**让 CodeBuddy 加载这些目录里的 `.codebuddy/` 配置（agents / hooks / settings 等都仍以启动目录的为准）。这与 cc 行为一致。
+
+### 项目目录信任开关
+
+仓库目录是否被你"显式信任"还会影响 allow 规则的可信级别（`tool-permission-service.ts:182`）。当目录**未被信任**时：
+
+- `<repo>/.codebuddy/settings.json` 与 `.codebuddy/settings.local.json` 里的 `allow` 规则会被归到**不可信**层（Phase 6），**不能**越过命令安全检查
+- 用户在交互界面确认信任后（`directoryTrustService.isTrustDirectory`），项目级规则会被提升到 Phase 2 可信层
+
+这是 cbc 独有的安全模型，目的是缓解仓库被克隆后立即跑产生的横向风险。
+
+## 受保护文件 / 路径
+
+任意模式下，CodeBuddy 都会对一组关键路径加额外保护（与 [PermissionMode 文档](permission-modes.md#受保护的关键文件) 重合）：
+
+- 仓库自身：`.git`、`.gitconfig`、`.gitmodules`
+- shell 配置：`.bashrc` / `.zshrc` / `.envrc` 等
+- 包管理：`.npmrc` / `.yarnrc` / `bunfig.toml` 等
+- IDE 工具：`.vscode` / `.idea` / `.husky` / `.devcontainer`
+- CodeBuddy 自身：`.codebuddy`（除 `.codebuddy/worktrees`）
+- MCP / 配置：`.mcp.json` / `.codebuddy.json`
+
+`bypassPermissions` 模式仍然会让其中绝大部分通过，但 `rm -rf /` / `rm -rf ~` 这类"灾难性命令"会通过 `isDangerousCommand` 兜底强制询问（`tool-permission-service.ts:244`）。
+
+## 用 Hooks 扩展权限
+
+[Hooks 钩子系统](hooks-guide.md) 的 `PreToolUse` 钩子会在权限弹审批之前运行，可以编程式 allow / deny / 改写输入。
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [{ "type": "command", "command": "/path/to/bash-policy.sh" }]
+      }
+    ]
+  }
+}
+```
+
+钩子退出码语义：
+
+| 退出码 | 行为 |
+| :----- | :--- |
+| `0` + JSON 决策 | 按 JSON 里的 `permissionDecision`（allow / ask / deny）执行 |
+| `2` | 阻断（stderr 内容回填给模型） |
+| 其他非 0 | 非阻断错误（提示但放行） |
+
+注意：
+
+- **deny / ask 规则始终先于钩子生效**。钩子返回 `"allow"` 不能越过 settings 里的 deny —— 这条与 cc 行为一致
+- 但**阻断式钩子**（exit code 2）能在 Phase 1 之前 short-circuit allow 规则，所以可以"先放行 Bash 全部，但用钩子单独拦几条特定命令"
+
+## 与沙箱的协作
+
+权限规则与 [Bash 沙箱](bash-sandboxing.md) 是互补层：
+
+- **规则层**：约束 CodeBuddy "想不想用"某工具或访问某路径
+- **沙箱层**：约束 Bash 子进程在 OS 层"能不能真的访问"某资源
+
+防御纵深的典型组合：
+
+- `deny` 规则阻挡 CodeBuddy 主动尝试受限工具
+- 沙箱阻挡所有 Bash 子进程触达白名单外的文件 / 网络 —— 即使 prompt injection 让 CodeBuddy 想绕也做不到
+- WebFetch 的 `domain:` allow 规则与沙箱 `allowedDomains` 都生效，最终边界取交集
+
+## Settings 优先级
+
+权限规则继承通用 [Settings 优先级](settings.md)：
+
+```
+flagSettings / cliArg / session  > userSettings > policySettings >
+projectSettings > localSettings > command/sandbox 来源
+```
+
+但**评估顺序**比 settings 优先级更重要：
+
+- `deny` 数组从所有作用域合并（`PermissionUtils.mergeRulesFromAllSources`），**任一作用域 deny 即拒**
+- `allow` 数组按"可信 / 不可信"分两次合并：可信合并里 user/cli/flag/session/policy 永远在；project/local 仅在目录被信任时算可信
+- `disableBypassPermissionsMode` 在 `user / project / local / cliArg` 四层任一为 `"disable"` 即生效（见 `tool-permission-service.ts:670-673`）—— 比 cc 多了项目级硬关闭通道
+
+## 示例配置
+
+### 最小化信任：只允许 npm 测试 + 读项目内文件
+
+```json
+{
+  "permissions": {
+    "defaultMode": "default",
+    "allow": [
+      "Bash(npm test)",
+      "Bash(npm run lint)",
+      "Read(/src/**)",
+      "Read(/test/**)"
+    ],
+    "deny": [
+      "Bash(rm:*)",
+      "Bash(curl:*)",
+      "Bash(wget:*)",
+      "Edit(.git/**)",
+      "Edit(/.codebuddy/**)"
+    ]
+  }
+}
+```
+
+### CI / 流水线场景：跳过审批 + 强 deny
+
+```json
+{
+  "permissions": {
+    "defaultMode": "bypassPermissions",
+    "deny": [
+      "Bash(rm -rf /:*)",
+      "Bash(sudo:*)",
+      "Bash(curl * -o /etc/*)",
+      "WebFetch(domain:internal-corp.example)"
+    ]
+  }
+}
+```
+
+### 团队共享 + 个人放宽
+
+`<repo>/.codebuddy/settings.json`（提交进 git）：
+
+```json
+{
+  "permissions": {
+    "deny": ["Bash(rm:*)", "Edit(.git/**)"]
+  }
+}
+```
+
+`~/.codebuddy/settings.json`（用户级，私有）：
+
+```json
+{
+  "permissions": {
+    "defaultMode": "acceptEdits",
+    "allow": ["Bash(git:*)", "Bash(npm:*)"]
+  }
+}
+```
+
+## 相关资源
+
+- [权限模式（Permission Mode）](permission-modes.md)：default / acceptEdits / plan / bypassPermissions / delegate 等模式
+- [Settings 配置](settings.md)：完整配置字段、作用域与合并规则
+- [Hooks 钩子系统](hooks-guide.md)：用钩子做编程式权限决策
+- [Bash 沙箱化](bash-sandboxing.md)：Bash 命令的 OS 级隔离
+- [CLI 参考](cli-reference.md)：`--allowedTools` / `--disallowedTools` / `--add-dir` 等启动参数
+- [安全](security.md)：整体安全模型与最佳实践
+- [IAM 身份与访问](iam.md)：组织级身份认证与权限控制

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

@@ -17,6 +17,9 @@ Release Notes 记录了每个版本的用户可见变更，包括：
 
 <!-- 新版本自动添加到此处 -->
 
+- [v2.103.4](./v2.103.4.md) - 2026-06-08
+- [v2.103.3](./v2.103.3.md) - 2026-06-08
+- [v2.103.2](./v2.103.2.md) - 2026-06-07
 - [v2.103.1](./v2.103.1.md) - 2026-06-04
 - [v2.103.0](./v2.103.0.md) - 2026-06-04
 - [v2.102.0](./v2.102.0.md) - 2026-06-03

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

@@ -0,0 +1,21 @@
+# 🚀 CodeBuddy Code v2.103.2 发布
+
+## 📦 版本信息
+
+| 组件 | 版本 |
+|------|------|
+| CodeBuddy Code CLI | v2.103.2 |
+| Agent SDK JS | v0.3.167 |
+| Agent SDK Python | v0.3.166 |
+
+## 🔧 改进优化
+
+- **计划模式可见性收敛**：子代理仅在显式锁定 plan 模式时才可见退出工具，纯继承主会话 plan 模式的子代理不再误调用，避免污染主会话的审批弹窗
+- **嵌入式场景适配**：新增 `CODEBUDDY_DISABLE_PLAN_MODE` 环境变量，宿主可一键关闭 plan 模式，适配无审批弹窗渲染位的嵌入式场景
+- **Stats 模型展示名优化**：模型聚合统计展示用户配置的模型名称，覆盖 Web UI 与 TUI 的模型排行、Token 趋势图例等
+- **上下文压缩开关兼容**：优化压缩开关兼容逻辑，新开关显式关闭时不再被旧配置误启用
+
+## 🐛 问题修复
+
+- **上下文压缩恢复稳定性**：修复 `/compact` 与自动压缩在超长上下文、待审批和图片结果场景下的恢复稳定性，降低压缩失败后请求中断的概率
+- **监控 metrics 上报丢失**：修复因 OpenTelemetry API 多实例导致 MeterProvider 注册失败的问题，确保 metrics 数据正常上报