Skip to content

Commit 5d6f727

Browse files
qorzjqorzj
committed
feat: add permission.md and update README.md
1 parent 50e18f1 commit 5d6f727

5 files changed

Lines changed: 215 additions & 0 deletions

File tree

‎README-en.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,10 @@ When the AI assistant completes a task, Deep Code can automatically execute a no
137137

138138
For detailed configuration instructions, see: [docs/notify_en.md](docs/notify_en.md)
139139

140+
### Does Deep Code only support YOLO mode?
141+
142+
No. Deep Code has a built-in fine-grained permission control mechanism that lets you confirm operations before the AI assistant executes shell commands, reads/writes files, accesses the network, and more. You can configure each permission scope's policy — always allow, always ask, or deny — via the `permissions` field in `settings.json`. See [docs/permission.md](docs/permission.md) for details.
143+
140144
## Contributing
141145

142146
Contributions are welcome! Here's how to get started:

‎README-zh_CN.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,10 @@ Deep Code 支持 MCP（Model Context Protocol），可以连接 GitHub、浏览
122122

123123
详细配置指南：[docs/notify.md](docs/notify.md)
124124

125+
### Deep Code 只支持 YOLO 模式吗？
126+
127+
不是。Deep Code 内置了细粒度的权限控制机制，支持在 AI 助手执行 Shell 命令、读写文件、访问网络等操作前进行确认。你可以通过 `settings.json` 中的 `permissions` 字段按需配置每种权限范围的策略：始终允许、始终询问、或直接拒绝。详见 [docs/permission.md](docs/permission.md)。
128+
125129
### 是否支持 Coding Plan？
126130

127131
支持。只要把 `~/.deepcode/settings.json` 的 `env.BASE_URL` 配置为 OpenAI 兼容的接口地址就行。以火山方舟的 Coding Plan 为例：
@@ -136,6 +140,7 @@ Deep Code 支持 MCP（Model Context Protocol），可以连接 GitHub、浏览
136140
"thinkingEnabled": true
137141
}
138142
```
143+
139144
## 贡献
140145

141146
欢迎贡献代码！以下是参与方式：

‎README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,10 @@ Deep Code 支持 MCP（Model Context Protocol），可以连接 GitHub、浏览
122122

123123
详细配置指南：[docs/notify.md](docs/notify.md)
124124

125+
### Deep Code 只支持 YOLO 模式吗？
126+
127+
不是。Deep Code 内置了细粒度的权限控制机制，支持在 AI 助手执行 Shell 命令、读写文件、访问网络等操作前进行确认。你可以通过 `settings.json` 中的 `permissions` 字段按需配置每种权限范围的策略：始终允许、始终询问、或直接拒绝。详见 [docs/permission.md](docs/permission.md)。
128+
125129
### 是否支持 Coding Plan？
126130

127131
支持。只要把 `~/.deepcode/settings.json` 的 `env.BASE_URL` 配置为 OpenAI 兼容的接口地址就行。以火山方舟的 Coding Plan 为例：
@@ -136,6 +140,7 @@ Deep Code 支持 MCP（Model Context Protocol），可以连接 GitHub、浏览
136140
"thinkingEnabled": true
137141
}
138142
```
143+
139144
## 贡献
140145

141146
欢迎贡献代码！以下是参与方式：

‎docs/permission.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Deep Code 权限机制
2+
3+
Deep Code 内置了一套细粒度的权限控制机制，在 AI 助手执行工具调用（如执行 Shell 命令、读写文件、访问网络等）前，根据用户配置的策略决定是自动放行、直接拒绝、还是弹出交互式确认。
4+
5+
## 概述
6+
7+
每次 AI 助手调用工具时，系统会自动分析该操作涉及的**权限范围（Permission Scope）**，然后根据 `settings.json` 中的权限配置做出决策。对于需要用户确认的操作，会在终端中弹出交互式选择界面，用户可以选择：
8+
9+
- **Yes** — 仅本次放行
10+
- **Yes, and always allow** — 本次放行，并将该权限范围写入项目配置文件，后续同类操作不再询问
11+
- **No** — 拒绝本次操作
12+
13+
## 权限范围
14+
15+
Deep Code 定义了以下 10 种权限范围，覆盖了工具调用的各类风险场景：
16+
17+
| 权限范围 | 说明 |
18+
| -------- | ---- |
19+
| `read-in-cwd` | 读取当前工作区内的文件 |
20+
| `read-out-cwd` | 读取当前工作区外的文件 |
21+
| `write-in-cwd` | 在当前工作区内创建或覆写文件 |
22+
| `write-out-cwd` | 在当前工作区外创建或覆写文件 |
23+
| `delete-in-cwd` | 删除当前工作区内的文件 |
24+
| `delete-out-cwd` | 删除当前工作区外的文件 |
25+
| `query-git-log` | 查询 Git 历史（如 `git log`、`git show`、`git blame`） |
26+
| `mutate-git-log` | 修改 Git 历史（如 `git commit`、`git rebase`、`git tag`） |
27+
| `network` | 访问网络（如 `curl`、`npm install` 等联网操作） |
28+
| `mcp` | 调用 MCP 外部工具 |
29+
30+
此外还有一个特殊的 `unknown` 范围，当 LLM 无法准确分类命令的副作用时使用，**`unknown` 总是触发询问**。
31+
32+
## 权限配置
33+
34+
在 `~/.deepcode/settings.json`（用户级）或 `.deepcode/settings.json`（项目级）中通过 `permissions` 字段配置：
35+
36+
```json
37+
{
38+
"permissions": {
39+
"allow": [],
40+
"deny": [],
41+
"ask": [],
42+
"defaultMode": "allowAll"
43+
}
44+
}
45+
```
46+
47+
### 配置项说明
48+
49+
| 字段 | 类型 | 说明 |
50+
| ---- | ---- | ---- |
51+
| `allow` | `string[]` | 始终自动放行的权限范围列表 |
52+
| `deny` | `string[]` | 始终自动拒绝的权限范围列表 |
53+
| `ask` | `string[]` | 始终弹出询问的权限范围列表 |
54+
| `defaultMode` | `"allowAll"` \| `"askAll"` | 未在 `allow`/`deny`/`ask` 中明确列出的权限范围的默认处理方式。默认为 `"allowAll"` |
55+
56+
### 优先级规则
57+
58+
当一个工具调用涉及多个权限范围时，决策按以下优先级进行：
59+
60+
1. 若任一范围命中 `deny` → **拒绝**
61+
2. 若任一范围命中 `ask` → **询问**
62+
3. 若所有范围均在 `allow` 中 → **自动放行**
63+
4. 否则 → 按 `defaultMode` 处理
64+
65+
### 示例：宽松模式（默认）
66+
67+
```json
68+
{
69+
"permissions": {
70+
"defaultMode": "allowAll"
71+
}
72+
}
73+
```
74+
75+
默认行为：所有操作自动放行，无需确认。
76+
77+
### 示例：严格模式
78+
79+
```json
80+
{
81+
"permissions": {
82+
"allow": ["read-in-cwd", "write-in-cwd", "query-git-log"],
83+
"defaultMode": "askAll"
84+
}
85+
}
86+
```
87+
88+
此配置的效果：
89+
- 工作区内读写、Git 查询 → 自动放行
90+
- 其他操作都需要用户确认。
91+
92+
93+
## 持久化机制
94+
95+
当用户在权限提示中选择 "Yes, and always allow" 后，对应的权限范围会被写入当前项目的 `.deepcode/settings.json` 文件中：
96+
97+
- 新增范围会追加到 `permissions.allow` 列表
98+
- 如果该范围之前存在于 `deny` 或 `ask` 中，会被自动移除
99+
- 不会重复写入已存在的范围
100+
101+
这样后续同类操作就不再询问。

‎docs/permission_en.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Deep Code Permission Mechanism
2+
3+
Deep Code includes a fine-grained permission control mechanism. Before the AI assistant executes a tool call (such as running a shell command, reading/writing files, accessing the network, etc.), the system determines whether to auto-allow, auto-deny, or prompt for interactive confirmation based on your configured policy.
4+
5+
## Overview
6+
7+
Each time the AI assistant invokes a tool, the system automatically analyzes the **permission scopes** involved and makes a decision based on the permission configuration in `settings.json`. For operations requiring user confirmation, an interactive prompt appears in the terminal with the following choices:
8+
9+
- **Yes** — Allow this one time only
10+
- **Yes, and always allow** — Allow this time and persistently save the scope to the project configuration so future calls skip the prompt
11+
- **No** — Deny this operation
12+
13+
## Permission Scopes
14+
15+
Deep Code defines the following 10 permission scopes, covering various risk scenarios for tool calls:
16+
17+
| Permission Scope | Description |
18+
| ---------------- | ----------- |
19+
| `read-in-cwd` | Read files inside the current workspace |
20+
| `read-out-cwd` | Read files outside the current workspace |
21+
| `write-in-cwd` | Create or overwrite files inside the current workspace |
22+
| `write-out-cwd` | Create or overwrite files outside the current workspace |
23+
| `delete-in-cwd` | Delete files inside the current workspace |
24+
| `delete-out-cwd` | Delete files outside the current workspace |
25+
| `query-git-log` | Query Git history (e.g., `git log`, `git show`, `git blame`) |
26+
| `mutate-git-log` | Mutate Git history (e.g., `git commit`, `git rebase`, `git tag`) |
27+
| `network` | Access the network (e.g., `curl`, `npm install`) |
28+
| `mcp` | Invoke MCP external tools |
29+
30+
There is also a special `unknown` scope used when the LLM cannot classify a command's side effects — **`unknown` always triggers a prompt**.
31+
32+
## Permission Configuration
33+
34+
Configure permissions in `~/.deepcode/settings.json` (user-level) or `.deepcode/settings.json` (project-level) via the `permissions` field:
35+
36+
```json
37+
{
38+
"permissions": {
39+
"allow": [],
40+
"deny": [],
41+
"ask": [],
42+
"defaultMode": "allowAll"
43+
}
44+
}
45+
```
46+
47+
### Configuration Fields
48+
49+
| Field | Type | Description |
50+
| ----- | ---- | ----------- |
51+
| `allow` | `string[]` | Permission scopes that are always auto-allowed |
52+
| `deny` | `string[]` | Permission scopes that are always auto-denied |
53+
| `ask` | `string[]` | Permission scopes that always trigger a confirmation prompt |
54+
| `defaultMode` | `"allowAll"` \| `"askAll"` | Default behavior for scopes not explicitly listed in `allow`/`deny`/`ask`. Defaults to `"allowAll"` |
55+
56+
### Priority Rules
57+
58+
When a tool call involves multiple permission scopes, the decision follows this priority:
59+
60+
1. If any scope matches `deny` → **Deny**
61+
2. If any scope matches `ask` → **Prompt**
62+
3. If all scopes are in `allow` → **Auto-allow**
63+
4. Otherwise → use `defaultMode`
64+
65+
### Example: Relaxed Mode (default)
66+
67+
```json
68+
{
69+
"permissions": {
70+
"defaultMode": "allowAll"
71+
}
72+
}
73+
```
74+
75+
Default behavior: all operations are auto-allowed with no confirmation required.
76+
77+
### Example: Strict Mode
78+
79+
```json
80+
{
81+
"permissions": {
82+
"allow": ["read-in-cwd", "write-in-cwd", "query-git-log"],
83+
"defaultMode": "askAll"
84+
}
85+
}
86+
```
87+
88+
With this configuration:
89+
- Reading/writing inside the workspace and querying Git history → auto-allowed
90+
- All other operations → require user confirmation
91+
92+
## Persistence
93+
94+
When you select "Yes, and always allow" in a permission prompt, the corresponding scope is written to the project's `.deepcode/settings.json`:
95+
96+
- The scope is appended to the `permissions.allow` list
97+
- If the scope was previously in `deny` or `ask`, it is automatically removed
98+
- Duplicate scopes are not written again
99+
100+
This means subsequent calls involving the same scope will no longer prompt for confirmation.

0 commit comments

Comments
 (0)