Skip to content

permission.md

Latest commit

 

History

History
101 lines (74 loc) · 3.43 KB

permission.md

File metadata and controls

101 lines (74 loc) · 3.43 KB

Deep Code 权限机制

Deep Code 内置了一套细粒度的权限控制机制，在 AI 助手执行工具调用（如执行 Shell 命令、读写文件、访问网络等）前，根据用户配置的策略决定是自动放行、直接拒绝、还是弹出交互式确认。

概述

每次 AI 助手调用工具时，系统会自动分析该操作涉及的权限范围（Permission Scope），然后根据 settings.json 中的权限配置做出决策。对于需要用户确认的操作，会在终端中弹出交互式选择界面，用户可以选择：

  • Yes — 仅本次放行
  • Yes, and always allow — 本次放行，并将该权限范围写入项目配置文件，后续同类操作不再询问
  • No — 拒绝本次操作

权限范围

Deep Code 定义了以下 10 种权限范围，覆盖了工具调用的各类风险场景：

权限范围 说明
read-in-cwd 读取当前工作区内的文件
read-out-cwd 读取当前工作区外的文件
write-in-cwd 在当前工作区内创建或覆写文件
write-out-cwd 在当前工作区外创建或覆写文件
delete-in-cwd 删除当前工作区内的文件
delete-out-cwd 删除当前工作区外的文件
query-git-log 查询 Git 历史（如 git log、git show、git blame）
mutate-git-log 修改 Git 历史（如 git commit、git rebase、git tag）
network 访问网络（如 curl、npm install 等联网操作）
mcp 调用 MCP 外部工具

此外还有一个特殊的 unknown 范围，当 LLM 无法准确分类命令的副作用时使用，unknown 总是触发询问。

权限配置

在 ~/.deepcode/settings.json（用户级）或 .deepcode/settings.json（项目级）中通过 permissions 字段配置：

{
  "permissions": {
    "allow": [],
    "deny": [],
    "ask": [],
    "defaultMode": "allowAll"
  }
}

配置项说明

字段 类型 说明
allow string[] 始终自动放行的权限范围列表
deny string[] 始终自动拒绝的权限范围列表
ask string[] 始终弹出询问的权限范围列表
defaultMode "allowAll" | "askAll" 未在 allow/deny/ask 中明确列出的权限范围的默认处理方式。默认为 "allowAll"

优先级规则

当一个工具调用涉及多个权限范围时，决策按以下优先级进行：

  1. 若任一范围命中 deny → 拒绝
  2. 若任一范围命中 ask → 询问
  3. 若所有范围均在 allow 中 → 自动放行
  4. 否则 → 按 defaultMode 处理

示例：宽松模式（默认）

{
  "permissions": {
    "defaultMode": "allowAll"
  }
}

默认行为：所有操作自动放行，无需确认。

示例：严格模式

{
  "permissions": {
    "allow": ["read-in-cwd", "write-in-cwd", "query-git-log"],
    "defaultMode": "askAll"
  }
}

此配置的效果：

  • 工作区内读写、Git 查询 → 自动放行
  • 其他操作都需要用户确认。

持久化机制

当用户在权限提示中选择 "Yes, and always allow" 后，对应的权限范围会被写入当前项目的 .deepcode/settings.json 文件中：

  • 新增范围会追加到 permissions.allow 列表
  • 如果该范围之前存在于 deny 或 ask 中，会被自动移除
  • 不会重复写入已存在的范围

这样后续同类操作就不再询问。