Skip to content

Commit 4fff1ed

Browse files
qorzjqorzj
committed
feat: add docs/configuration.md
1 parent 3d01605 commit 4fff1ed

1 file changed

Lines changed: 173 additions & 0 deletions

File tree

‎docs/configuration.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# Deep Code 配置
2+
3+
## 配置层级
4+
5+
配置按以下优先级顺序应用（数字较小的会被数字较大的覆盖）：
6+
7+
| 层级 | 配置来源 | 说明 |
8+
| ---- | ------------ | ------------------------------------------- |
9+
| 1 | 默认值 | 应用程序内硬编码的默认值 |
10+
| 2 | 用户设置文件 | 当前用户的全局设置 |
11+
| 3 | 项目设置文件 | 项目特定的设置 |
12+
| 4 | 环境变量 | 系统范围或会话特定的变量 |
13+
14+
## 设置文件
15+
16+
Deep Code 使用 `settings.json` 设置文件进行持久化配置，支持两个层级的存放位置：
17+
18+
| 文件类型 | 位置 | 作用范围 |
19+
| ------------ | ---------------------------------- | ---------------------------------------------------- |
20+
| 用户设置文件 | `~/.deepcode/settings.json` | 适用于当前用户的所有 Deep Code 会话。 |
21+
| 项目设置文件 | `项目根目录/.deepcode/settings.json` | 仅在该特定项目中运行 Deep Code 时生效。项目设置会覆盖用户设置。 |
22+
23+
### `settings.json` 中的可用设置
24+
25+
以下是 `settings.json` 支持的全部顶层字段，以及 `env` 内部支持的子字段：
26+
27+
| 字段 | 类型 | 说明 |
28+
| -------------------- | --------- | ------------------------------------------------------------------- |
29+
| `env` | object | 环境变量分组（见下方子字段表） |
30+
| `model` | string | 模型名称。优先级高于 `env.MODEL` |
31+
| `thinkingEnabled` | boolean | 是否启用思考模式（DeepSeek V4 系列默认启用） |
32+
| `reasoningEffort` | string | 推理强度，可选 `"high"` 或 `"max"`（默认 `"max"`） |
33+
| `debugLogEnabled` | boolean | 是否启用调试日志输出（默认 `false`） |
34+
| `notify` | string | 任务完成通知脚本的完整路径（如 Slack 通知脚本） |
35+
| `webSearchTool` | string | 自定义联网搜索脚本的完整路径 |
36+
| `mcpServers` | object | MCP 服务器配置（键为服务名，值为 McpServerConfig 对象） |
37+
38+
#### `env` 子字段
39+
40+
| 字段 | 类型 | 说明 |
41+
| ---------- | ------ | ------------------------------------------------------------------ |
42+
| `MODEL` | string | 模型名称。例如 `"deepseek-v4-pro"`、`"deepseek-v4-flash"` |
43+
| `BASE_URL` | string | API 请求的基础 URL。例如 `"https://api.deepseek.com"` |
44+
| `API_KEY` | string | API 密钥 |
45+
| `THINKING_ENABLED` | string | 是否启用思考模式 |
46+
| `REASONING_EFFORT` | string | 推理强度 |
47+
| `DEBUG_LOG_ENABLED` | string | 是否启用调试日志输出 |
48+
| `<其他任意KEY>` | string | 自定义环境变量 |
49+
50+
#### `thinkingEnabled` — 思考模式
51+
52+
是否启用 DeepSeek 思考模式。设置为 `true` 启用、`false` 禁用。
53+
54+
- 对于 `deepseek-v4-pro` 和 `deepseek-v4-flash`，思考模式**默认启用**。
55+
- 对于其他模型，思考模式**默认关闭**。
56+
57+
#### `reasoningEffort` — 推理强度
58+
59+
当思考模式启用时，控制模型思考的深度：
60+
61+
| 值 | 说明 |
62+
| ------ | --------------------------------- |
63+
| `max` | 最大推理深度（默认值） |
64+
| `high` | 较高推理深度，token消耗相对较小 |
65+
66+
#### `notify` — 任务完成通知
67+
68+
设置一个 Shell 脚本的完整路径。当 AI 助手完成一轮任务后，会自动执行该脚本，可用于发送通知（如 Slack 消息）。
69+
70+
```json
71+
{
72+
"notify": "/path/to/slack-notify.sh"
73+
}
74+
```
75+
76+
#### `webSearchTool` — 自定义联网搜索
77+
78+
Deep Code 内置免费可用的 Web Search 工具。如果需要自定义搜索逻辑，可将 `webSearchTool` 设为一个可执行脚本的完整路径：
79+
80+
```json
81+
{
82+
"webSearchTool": "/path/to/my-search-script.sh"
83+
}
84+
```
85+
86+
脚本接收一个搜索查询参数，输出 JSON 格式的结果供 AI 使用。
87+
88+
#### `mcpServers` — MCP 服务器
89+
90+
MCP（Model Context Protocol）服务器配置。值是键值对，键为服务名称，值为服务器配置对象。
91+
92+
```json
93+
{
94+
"mcpServers": {
95+
"<服务名>": {
96+
"command": "npx",
97+
"args": ["-y", "@modelcontextprotocol/server-github"],
98+
"env": {
99+
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
100+
}
101+
}
102+
}
103+
}
104+
```
105+
106+
| McpServerConfig 字段 | 类型 | 必填 | 说明 |
107+
| -------------------- | -------- | ---- | -------------------------------------------------------------------- |
108+
| `command` | string | 是 | 可执行文件路径或命令（如 `npx`、`node`、`python`） |
109+
| `args` | string[] | 否 | 传递给命令的参数列表 |
110+
| `env` | object | 否 | 传递给 MCP 服务器进程的环境变量 |
111+
112+
> 当 `command` 为 `npx` 时，Deep Code 会自动在参数前补充 `-y`。
113+
114+
详细 MCP 使用说明请参考 [docs/mcp.md](docs/mcp.md)。
115+
116+
117+
#### `debugLogEnabled` — 调试日志
118+
119+
设为 `true` 可让程序输出详细的调试日志（默认 `false`），用于排查 API 调用和工具执行的问题。
120+
121+
## 环境变量优先级
122+
123+
环境变量是配置应用程序的常用方式，尤其适用于敏感信息（如 api-key）或可能在不同环境之间更改的设置。
124+
125+
### 优先级原则
126+
127+
环境变量优先级遵循“越具体、越局部的配置，优先级越高”和“env文件默认保护现有环境，系统变量高于env文件”的覆盖逻辑。(settings.json的env对象可以认为是一种env文件)
128+
129+
优先级层级 (由低到高)
130+
1. settings.json 外层的 env：这是针对整个工具及其所有子进程的通用配置（全局变量）。可被外层环境变量覆盖，但环境变量KEY会移除`DEEPCODE_`前缀。
131+
2. settings.json mcpServers 内定义的 env：这是针对特定 MCP 服务的最具体配置（局部变量）。可被外层环境变量覆盖，但环境变量KEY会移除`MCP_`前缀。
132+
3. Shell 环境系统变量：操作系统层面的环境变量。
133+
134+
### 场景
135+
136+
#### 一、设置模型的api_key, base_url
137+
138+
按以下优先级顺序应用（数字较小的会被数字较大的覆盖）(以api_key为例)：
139+
140+
1. 硬编码默认值: `""`
141+
2. 用户级settings.json: `{"env": {"API_KEY": "abc123"}}`
142+
3. 项目级settings.json: `{"env": {"API_KEY": "abc123"}}`
143+
4. 系统环境变量: `DEEPCODE_API_KEY=abc123 deepcode`
144+
145+
#### 二、设置模型的model, thinkingEnabled, reasoningEffort
146+
147+
按以下优先级顺序应用（数字较小的会被数字较大的覆盖）(以thinkingEnabled为例)：
148+
149+
1. 硬编码默认值: `true`
150+
2. 用户级settings.json: `{"env": {"THINKING_ENABLED": "true"}}`
151+
3. 用户级settings.json: `{"thinkingEnabled": true}`
152+
4. 项目级settings.json: `{"env": {"THINKING_ENABLED": "true"}}`
153+
5. 项目级settings.json: `{"thinkingEnabled": true}`
154+
6. 系统环境变量: `DEEPCODE_THINKING_ENABLED=true deepcode`
155+
156+
#### 三、设置启动notify, webSearchTool等外挂脚本的环境变量
157+
158+
按以下优先级顺序应用（数字较小的会被数字较大的覆盖）(以notify为例)：
159+
160+
1. 硬编码默认值：`os.environ.get('WEBHOOK', '...') # notify脚本代码`
161+
2. 用户级settings.json: `{"env": {"WEBHOOK": "..."}}`
162+
3. 项目级settings.json: `{"env": {"WEBHOOK": "true"}}`
163+
4. 系统环境变量: `DEEPCODE_WEBHOOK=... deepcode`
164+
165+
#### 四、设置MCP Service的环境变量
166+
167+
按以下优先级顺序应用（数字较小的会被数字较大的覆盖）(以github MCP server为例)：
168+
169+
1. 用户级settings.json: `{"mcpServers":{"github":{"env":{"GITHUB_PERSONAL_ACCESS_TOKEN":"..."}}}}`
170+
2. 用户级settings.json: `{"env": {"MCP_GITHUB_PERSONAL_ACCESS_TOKEN": "..."}}`
171+
3. 项目级settings.json: `{"mcpServers":{"github":{"env":{"GITHUB_PERSONAL_ACCESS_TOKEN":"..."}}}}`
172+
4. 项目级settings.json: `{"env": {"MCP_GITHUB_PERSONAL_ACCESS_TOKEN": "..."}}`
173+
5. 系统环境变量: `DEEPCODE_MCP_GITHUB_PERSONAL_ACCESS_TOKEN=... deepcode`

0 commit comments

Comments
 (0)