Permission System 专题¶

重要性：⭐⭐⭐⭐（权限核心——5 mode + bash classifier + 规则匹配 + 提示流程） 真实位置：src/utils/permissions/（25+ 文件）+ src/tools/BashTool/bashPermissions.ts 角色：决定每个工具调用是 allow / deny / ask —— 5 mode 切换 + bash classifier + 规则关联：topics/deep-dive-bash-permissions.md、topics/deep-dive-bash-security.md

1. Permission System 是什么¶

Permission System = 工具调用的"决策中心" - 输入：工具名 + 参数 - 输出：allow / deny / ask - 中间：5 mode + 规则匹配 + classifier

核心位置：utils/permissions/permissions.ts（推测）+ tools/BashTool/bashPermissions.ts。

2. 5 种 Permission Mode¶

const PERMISSION_MODES = ['acceptEdits', 'bypassPermissions', 'default', 'plan', 'auto']

5 种 mode： - default —— 正常（按规则） - acceptEdits —— 自动接受 Edit/Write - bypassPermissions —— 全部允许（危险） - plan —— 只读模式 - auto —— 自动模式（classifier 决策）

5 mode 切换通过 --permission-mode。

2.1 `getNextPermissionMode`¶

// utils/permissions/getNextPermissionMode.ts
function getNextPermissionMode(current: PermissionMode): PermissionMode { ... }

循环切换 —— Tab 键。

2.2 `PermissionMode` enum¶

// utils/permissions/PermissionMode.ts

模式定义。

3. 5 类工具¶

Bash, Edit, Read, Write, Agent, AskUserQuestion, WebFetch, ...

100+ 工具 —— 每个有自己的权限处理。

典型权限： - Bash → bashClassifier + rules - Edit → 文件 in/out + diff - Read → 文件 in - Agent → 子 agent 启动 - WebFetch → URL allow/deny

4. 权限规则（3 种）¶

4.1 Allow 规则¶

{ "allow": ["Bash(git:*)", "Read"] }

白名单 —— 总是允许。

4.2 Deny 规则¶

{ "deny": ["Bash(rm -rf:*)"] }

黑名单 —— 总是拒绝。

4.3 Ask 规则¶

{ "ask": ["Bash(sudo:*)"] }

总是问 —— 即便白名单。

5. 5 步决策流程¶

工具调用
  ↓
检查 mode (default/acceptEdits/bypass/plan/auto)
  ↓
匹配 allow 规则
  ↓
匹配 deny 规则
  ↓
特定工具检查 (bash classifier / path validation)
  ↓
返回 allow/deny/ask

5 步。

5.1 Mode 检查¶

if (mode === 'bypassPermissions') return { allow: true }
if (mode === 'plan' && tool !== 'Read') return { ask: true }

Mode 优先。

5.2 规则匹配¶

// bash: 模糊匹配 (Bash(git:*) 匹配 `git status`)
// 其它: 精确 / 前缀

多种匹配方式。

5.3 工具特定检查¶

// Bash: bashClassifier + bashSecurity
// Edit: path validation
// WebFetch: URL allow/deny

工具特定。

6. Bash 权限详解¶

详见 deep-dive-bash-permissions.md。

6 层决策： 1. exact match 2. wildcard 3. sandbox auto-allow 4. early deny 5. semantic deny 6. classifier (LLM)

7. 25+ Permission 文件¶

utils/permissions/
├── permissions.ts                    ← 核心
├── PermissionMode.ts
├── PermissionResult.ts
├── PermissionRule.ts
├── PermissionUpdate.ts
├── PermissionUpdateSchema.ts         ← zod schema
├── permissionsLoader.ts              ← 从 settings 加载
├── permissionSetup.ts                ← 初始化
├── permissionRuleParser.ts           ← 规则解析
├── permissionExplainer.ts            ← 解释器
├── permissionPromptToolResultSchema.ts
├── getNextPermissionMode.ts          ← Tab 循环
├── shellRuleMatching.ts              ← bash 规则匹配
├── shadowedRuleDetection.ts          ← 规则被遮蔽检测
├── filesystem.ts                     ← 文件系统权限
├── pathValidation.ts                 ← 路径校验
├── dangerousPatterns.ts              ← 危险模式
├── denialTracking.ts                 ← 拒绝追踪
├── bashClassifier.ts                 ← bash classifier
├── yoloClassifier.ts                 ← YOLO 模式 classifier
├── autoModeState.ts                  ← auto mode 状态
├── classifierDecision.ts             ← classifier 决策
├── classifierShared.ts               ← 共享
└── bypassPermissionsKillswitch.ts    ← 紧急 kill switch

25+ 文件 —— 完整权限系统。

8. PermissionResult¶

type PermissionResult = {
  decision: 'allow' | 'deny' | 'ask'
  reason?: string
  rule?: PermissionRule
  // ...
}

3 种决策 + 原因 + 命中的规则。

9. PermissionRule 4 种操作¶

type PermissionUpdate = 
  | { type: 'addRules', rules: PermissionRule[], ... }
  | { type: 'removeRules', ... }
  | { type: 'setMode', mode: PermissionMode }
  | { type: 'addDirectories', ... }
  // ...

4 种操作 —— 增删规则 / 切换 mode / 加目录。

10. Settings 集成¶

// settings.json
{
  "permissions": {
    "allow": ["Bash(git:*)", "Read"],
    "deny": ["Bash(rm -rf:*)", "WebFetch"],
    "ask": ["Bash(sudo:*)"],
    "defaultMode": "default"
  }
}

4 字段 —— allow / deny / ask / defaultMode。

11. permissionsLoader¶

async function loadPermissionsFromSettings(): Promise<...> { ... }

从 settings 加载 —— 多源合并。

12. shadowedRuleDetection¶

function detectShadowedRules(rules): ... { ... }

规则遮蔽检测 —— 后面的规则可能 shadow 前面的。

13. permissionExplainer¶

function explainRule(rule): string { ... }

解释器 —— 把规则转成可读文本。

14. yoloClassifier¶

// utils/permissions/yoloClassifier.ts

YOLO mode —— "高风险自动放行" classifier（推测）。

15. autoModeState¶

// utils/permissions/autoModeState.ts

auto mode 状态 —— auto mode 启用时记录。

16. bypassPermissionsKillswitch¶

// utils/permissions/bypassPermissionsKillswitch.ts

Kill switch —— 紧急关闭 bypassPermissions（安全）。

17. 关键设计模式¶

17.1 5 mode¶

default / acceptEdits / bypass / plan / auto —— 5 种策略。

17.2 3 种规则¶

allow / deny / ask —— 3 种白/黑名单。

17.3 工具特定¶

Bash / Edit / Read / WebFetch 各有特定检查。

17.4 LLM classifier¶

auto mode + bash classifier —— AI 辅助决策。

17.5 settings 多源¶

4 级合并 —— 灵活。

17.6 Rule 解释器¶

UI 友好 —— 用户理解。

17.7 Kill switch¶

紧急 bypass —— 安全。

17.8 Shadowed 检测¶

规则覆盖警告。

18. 关键洞察¶

18.1 5 mode 是核心¶

default / acceptEdits / bypass / plan / auto —— 5 种策略。

18.2 25+ 文件是复杂度¶

权限系统不简单。

18.3 LLM classifier 是现代¶

auto mode 用 AI 决策。

18.4 settings 多源¶

4 级合并 —— 灵活。

18.5 Kill switch 必要¶

bypass 风险 → 紧急关闭。

18.6 Shadowed 检测¶

规则顺序重要。

18.7 工具特定检查¶

不是"一刀切"。

18.8 解释器友好¶

UI 友好。

18.9 3 决策清晰¶

allow / deny / ask。

18.10 4 操作完整¶

增删规则 / 切 mode / 加目录。

19. 改进方向¶

19.1 LLM classifier 优化¶

更准的 AI 决策。

19.2 规则调试 UI¶

可视化规则冲突。

19.3 测试覆盖¶

所有规则组合的测试。

19.4 权限模板¶

常见场景预设。

20. 阅读建议¶

看 permissions.ts —— 核心
看 PermissionMode.ts —— 5 mode
看 bashClassifier.ts + yoloClassifier.ts —— AI 决策
看 shellRuleMatching.ts —— 规则匹配
看 shadowedRuleDetection.ts —— 规则顺序

21. 与其他专题的关系¶

文件	关系
`deep-dive-bash-permissions.md`	bash 权限
`deep-dive-bash-security.md`	bash 安全
`authentication.md`	鉴权
`cache-strategies.md`	classifier 缓存