5.4 工具调用中的权限检查

模型: claude-opus-4-6 (anthropic/claude-opus-4-6) 生成日期: 2025-02-17

---

5.4.1 ctx.ask() 的调用时机与流程

每个涉及敏感操作的工具都会在执行前调用 ctx.ask() 发起权限请求：

// edit.ts 中的权限检查
await ctx.ask({
  permission: "edit",
  patterns: [path.relative(Instance.worktree, filePath)],
  always: ["*"],
  metadata: {
    filepath: filePath,
    diff: diff,
    existed: existed,
  },
})

参数含义：

• permission：权限类别名称（如 "edit"、"bash"、"read"）

• patterns：匹配模式。对于文件操作，是相对路径；对于命令执行，是命令内容

• always：如果用户选择"总是允许"，记忆的匹配模式

• metadata：展示给用户的附加信息（如 diff 内容、文件路径）

5.4.2 权限请求的用户交互流程

当权限规则为 "ask" 时，整个系统会进入以下流程：

1. 工具调用 ctx.ask()
       │
2. PermissionNext 评估权限规则
       │
       ├── "allow" → 直接返回，工具继续执行
       ├── "deny"  → 抛出 RejectedError，工具中止
       └── "ask"   → 创建 Permission Request
              │
3. 通过 Bus 发布权限请求事件
       │
4. 前端（TUI/Web）接收事件，弹出确认对话框
       │
5. 用户做出选择：
       ├── "Allow"        → 本次允许
       ├── "Always Allow"  → 永久允许该模式
       └── "Deny"         → 拒绝
       │
6. 前端通过 API 提交用户决策
   POST /project/:id/session/:sid/permission/:pid
       │
7. ctx.ask() 的 Promise resolve/reject
       │
8. 工具继续执行或中止

各工具的权限粒度：

工具	权限名称	匹配模式	示例
bash	bash	命令文本/文件路径	"rm -rf dist"
edit	edit	相对文件路径	"src/index.ts"
write	write	相对文件路径	"new-file.ts"
read	read	相对文件路径	".env" (特殊保护)
task	task	Agent 名称	"explore"
external_directory	external_directory	目录路径	"/usr/local/..."

Bash 工具的特殊处理：

Bash 工具使用 Tree-sitter 解析器分析命令，提取涉及的文件路径。这样权限检查可以精确到文件级别，而不是笼统地允许/拒绝所有命令。BashArity（permission/arity.ts）实现了这种精细的权限粒度划分。

always 记忆机制：

当用户选择 "Always Allow" 时，该权限模式会被记住并存储。后续相同模式的请求会自动通过，不再弹出确认对话框。存储粒度由 always 字段控制——例如 ["*"] 表示对所有文件的编辑都自动允许，而 ["src/*.ts"] 表示只自动允许对 src/ 下 TypeScript 文件的编辑。

---

至此，Tool 系统的完整架构已经清晰：从抽象层设计、注册发现、20+ 个内置工具实现，到权限检查的完整流程。Tool 是 Agent 的"手脚"——下一章我们将分析 Agent 本身，即赋予这些工具"大脑"的系统。