deepseeker-code 1.0.0 → 1.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -21
- package/README.md +267 -267
- package/dist/builtin/tdd/SKILL.md +35 -35
- package/dist/cli.mjs +87 -91
- package/package.json +56 -56
package/LICENSE
CHANGED
|
@@ -1,21 +1,21 @@
|
|
|
1
|
-
MIT License
|
|
2
|
-
|
|
3
|
-
Copyright (c) 2025 DeepSeeker-Code
|
|
4
|
-
|
|
5
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
-
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
-
in the Software without restriction, including without limitation the rights
|
|
8
|
-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
-
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
-
furnished to do so, subject to the following conditions:
|
|
11
|
-
|
|
12
|
-
The above copyright notice and this permission notice shall be included in all
|
|
13
|
-
copies or substantial portions of the Software.
|
|
14
|
-
|
|
15
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
-
SOFTWARE.
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 DeepSeeker-Code
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,267 +1,267 @@
|
|
|
1
|
-
# DeepSeeker-Code
|
|
2
|
-
|
|
3
|
-
> DeepSeek 驱动的终端级 AI
|
|
4
|
-
|
|
5
|
-
```bash
|
|
6
|
-
npm i -g deepseeker-code
|
|
7
|
-
export DEEP_SEEK_API_KEY=sk-你的key
|
|
8
|
-
cd 你的项目
|
|
9
|
-
deepseeker-code
|
|
10
|
-
```
|
|
11
|
-
|
|
12
|
-
DeepSeeker-Code 在你的终端里跑一个自主 agent：流式逐字输出、可折叠思考过程、工具调用卡、审批模态、两阶段计划模式、会话恢复。**in-process 直驱引擎**——不走 HTTP/端口，工具审批走 Ink 原生模态。
|
|
13
|
-
|
|
14
|
-
> 另有 **VS Code 插件**版本（同名 `deepseeker-code`），与终端版同源共享 core 引擎和 `~/.deepseeker-code/` 数据目录，同一项目下会话可互续。
|
|
15
|
-
|
|
16
|
-
---
|
|
17
|
-
|
|
18
|
-
## 前置要求
|
|
19
|
-
|
|
20
|
-
- **Node.js ≥ 20**（esbuild target node20）
|
|
21
|
-
- **DeepSeek API Key**：通过 `~/.deepseeker-code/config.json` 的 `apiKey` 字段**或**环境变量 `DEEP_SEEK_API_KEY` 提供（**无交互式输入、无 `--model` 参数**）；两者都缺会直接退出并提示。
|
|
22
|
-
- **真实终端（TTY）**：UI 基于 React Ink，依赖 TTY；不要在 `npm run` / 管道 / 非交互 shell 里跑。
|
|
23
|
-
|
|
24
|
-
---
|
|
25
|
-
|
|
26
|
-
## 快速开始
|
|
27
|
-
|
|
28
|
-
```bash
|
|
29
|
-
# 1. 全局安装
|
|
30
|
-
npm install -g deepseeker-code
|
|
31
|
-
|
|
32
|
-
# 2. 配置 API Key（二选一）
|
|
33
|
-
# 方式 A（推荐，免环境变量）：写入 ~/.deepseeker-code/config.json
|
|
34
|
-
mkdir -p ~/.deepseeker-code && echo '{ "apiKey": "sk-你的key" }' > ~/.deepseeker-code/config.json
|
|
35
|
-
# 方式 B：环境变量（写入 shell 配置持久化，如 ~/.bashrc / ~/.zshrc / PowerShell $PROFILE）
|
|
36
|
-
export DEEP_SEEK_API_KEY=sk-你的key # Windows PowerShell: $env:DEEP_SEEK_API_KEY="sk-..."
|
|
37
|
-
|
|
38
|
-
# 3. 进入项目目录运行（agent 的工作区 = 当前目录）
|
|
39
|
-
cd ~/projects/my-app
|
|
40
|
-
deepseeker-code
|
|
41
|
-
|
|
42
|
-
# 可选：进入即计划模式
|
|
43
|
-
deepseeker-code --plan
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
---
|
|
47
|
-
|
|
48
|
-
## 命令行参数
|
|
49
|
-
|
|
50
|
-
| 参数 | 短写 | 作用 |
|
|
51
|
-
| --- | --- | --- |
|
|
52
|
-
| `--resume <会话id>` | `-r` | 续接指定会话 |
|
|
53
|
-
| `--continue` | `-c` | 自动续接本工作区最近一次会话 |
|
|
54
|
-
| `--plan` | `-p` | 初始进入计划模式（只读调研 → 方案 → 实现） |
|
|
55
|
-
| `--auto` | `-a` | 初始进入自动模式（按权限规则自动执行，少打断） |
|
|
56
|
-
|
|
57
|
-
> 没有 `--model` / `--print` / `--output-style` / `--session` 等参数。模型经 `DEEP_SEEK_MODEL` 环境变量设；输出风格经运行时 `/output-style <名称>` 切换。
|
|
58
|
-
|
|
59
|
-
## 聊天内命令
|
|
60
|
-
|
|
61
|
-
输入框以 `/` 开头（输入 `/` 会弹出补全菜单）：
|
|
62
|
-
|
|
63
|
-
| 命令 | 作用 |
|
|
64
|
-
| --- | --- |
|
|
65
|
-
| `/help` | 帮助 |
|
|
66
|
-
| `/plan` | 切换计划模式 |
|
|
67
|
-
| `/auto` | 切换自动模式 |
|
|
68
|
-
| `/model <名称>` | 切换模型 |
|
|
69
|
-
| `/thinking <off\|high\|max>` | 切换思考强度 |
|
|
70
|
-
| `/lang <zh\|en>` | 切换语言 |
|
|
71
|
-
| `/output-style <名称>` | 切换输出风格（人格） |
|
|
72
|
-
| `/sessions` | 列出并续接历史会话 |
|
|
73
|
-
| `/clear` | 新会话 |
|
|
74
|
-
| `/status` / `/usage` / `/context` | 查看状态 / 用量 / 上下文 |
|
|
75
|
-
| `/permissions` / `/mcp` / `/hooks` | 查看已加载的权限规则 / MCP / Hooks |
|
|
76
|
-
| `/debug` | 调试信息 |
|
|
77
|
-
| `/exit` / `/quit` | 退出 |
|
|
78
|
-
|
|
79
|
-
**快捷键**：`Ctrl+C` 退出 · `Esc` 中止/清输入 · `Ctrl+G` 中止当前轮 · `Ctrl+T` 展开/收起思考 · 模态/菜单 `↑↓ Enter`。
|
|
80
|
-
|
|
81
|
-
---
|
|
82
|
-
|
|
83
|
-
## 配置
|
|
84
|
-
|
|
85
|
-
DeepSeeker-Code 支持三种配置来源，优先级 **环境变量 > config.json（CLI）/ 设置项（VSCode）> 内置默认**。环境变量始终最高，作为临时覆盖/CI 的逃生通道。
|
|
86
|
-
|
|
87
|
-
### 配置文件 config.json（CLI 推荐）
|
|
88
|
-
|
|
89
|
-
不必再到处设环境变量——把连接/模型/运行时配置写进 `~/.deepseeker-code/config.json`（全局；位于 `DEEPSEEKER_CODE_DATA_DIR` 指向的目录），CLI 启动时自动读取并回填，**仅当对应环境变量未设时才采用 config.json 的值**。
|
|
90
|
-
|
|
91
|
-
```jsonc
|
|
92
|
-
// ~/.deepseeker-code/config.json
|
|
93
|
-
{
|
|
94
|
-
"apiKey": "sk-你的key", // 不必再 export DEEP_SEEK_API_KEY
|
|
95
|
-
"model": "deepseek-v4-flash",
|
|
96
|
-
"auxModel": "deepseek-v4-flash",
|
|
97
|
-
"apiUrl": "https://api.deepseek.com",
|
|
98
|
-
"reasoningEffort": "high", // high | max
|
|
99
|
-
"thinking": true, // 默认开；false 关闭深度思考
|
|
100
|
-
"parallelSafeTools": true, // 默认开；false 回退同轮工具完全串行
|
|
101
|
-
"workflowConcurrency": 4,
|
|
102
|
-
"workflowMaxSteps": 8,
|
|
103
|
-
"streamIdleTimeoutMs": 120000
|
|
104
|
-
}
|
|
105
|
-
```
|
|
106
|
-
|
|
107
|
-
| 字段 | 类型 | 默认 | 对应环境变量 |
|
|
108
|
-
| --- | --- | --- | --- |
|
|
109
|
-
| `apiKey` | string | — | `DEEP_SEEK_API_KEY` |
|
|
110
|
-
| `apiUrl` | string | `https://api.deepseek.com` | `DEEP_SEEK_API_URL` |
|
|
111
|
-
| `model` | string | `deepseek-v4-flash` | `DEEP_SEEK_MODEL` |
|
|
112
|
-
| `auxModel` | string | `deepseek-v4-flash` | `DEEP_SEEK_AUX_MODEL` |
|
|
113
|
-
| `reasoningEffort` | `high`\|`max` | `high` | `DEEP_SEEK_REASONING_EFFORT` |
|
|
114
|
-
| `thinking` | boolean | `true` | `DEEP_SEEK_THINKING`（false→`0`） |
|
|
115
|
-
| `parallelSafeTools` | boolean | `true` | `DEEP_SEEK_PARALLEL_SAFE_TOOLS`（false→`0`） |
|
|
116
|
-
| `streamIdleTimeoutMs` | number | `120000` | `DEEP_SEEK_STREAM_IDLE_TIMEOUT_MS` |
|
|
117
|
-
| `workflowConcurrency` | number | `4` | `DEEP_SEEK_WORKFLOW_CONCURRENCY` |
|
|
118
|
-
| `workflowMaxSteps` | number | `8` | `DEEP_SEEK_WORKFLOW_MAX_STEPS` |
|
|
119
|
-
|
|
120
|
-
> - **VSCode 插件不读 config.json**——在设置界面（`deepseekerCode.*`）配置，字段语义与上表一致。
|
|
121
|
-
> - 文件缺失或字段留空都安全（回退环境变量/默认）；JSON 解析失败会打 stderr 警告并忽略整个文件，不阻断启动。
|
|
122
|
-
> - `DEEPSEEKER_CODE_DATA_DIR` 仍只能用环境变量设（它决定 config.json 的位置，鸡生蛋）。
|
|
123
|
-
> - config.json 明文存放 `apiKey`（与环境变量同等明文），建议加文件权限（`chmod 600`）。
|
|
124
|
-
|
|
125
|
-
### 环境变量
|
|
126
|
-
|
|
127
|
-
#### 模型 / API（`DEEP_SEEK_*` — 指向 DeepSeek 厂商）
|
|
128
|
-
|
|
129
|
-
| 变量 | 作用 | 默认 |
|
|
130
|
-
| --- | --- | --- |
|
|
131
|
-
| `DEEP_SEEK_API_KEY` | DeepSeek API Key（**必填**） | — |
|
|
132
|
-
| `DEEP_SEEK_API_URL` | API 基址（兼容 OpenAI 协议的代理可改此项） | `https://api.deepseek.com` |
|
|
133
|
-
| `DEEP_SEEK_MODEL` | 主模型 | `deepseek-v4-flash` |
|
|
134
|
-
| `DEEP_SEEK_AUX_MODEL` | 辅助模型（摘要 / 风险分类） | `deepseek-v4-flash` |
|
|
135
|
-
| `DEEP_SEEK_REASONING_EFFORT` | 推理强度，仅 `high` / `max` | `high` |
|
|
136
|
-
| `DEEP_SEEK_THINKING` | 深度思考开关，设 `0` 关闭 | 开 |
|
|
137
|
-
| `DEEP_SEEK_STREAM_IDLE_TIMEOUT_MS` | 流式 idle 超时（ms） | `120000` |
|
|
138
|
-
|
|
139
|
-
#### 产品行为
|
|
140
|
-
|
|
141
|
-
| 变量 | 作用 | 默认 |
|
|
142
|
-
| --- | --- | --- |
|
|
143
|
-
| `DEEPSEEKER_CODE_DATA_DIR` | 用户数据目录（会话/skills/hooks/mcp 全在此） | `~/.deepseeker-code` |
|
|
144
|
-
| `DEEP_SEEK_PARALLEL_SAFE_TOOLS` | 设 `0` 关闭同轮只读工具并发（默认开） | 开（并发） |
|
|
145
|
-
| `DEEP_SEEK_WORKFLOW_CONCURRENCY` | run_workflow 子 agent 并发上限 | `4` |
|
|
146
|
-
| `DEEP_SEEK_WORKFLOW_MAX_STEPS` | run_workflow 单次步数上限 | `8` |
|
|
147
|
-
| `SEARCH_PROVIDER` | 搜索后端 `tavily` / `bing` / `ddg` | 自动（有 Tavily key 用 Tavily，否则 Bing） |
|
|
148
|
-
| `TAVILY_API_KEY` | Tavily 搜索密钥 | — |
|
|
149
|
-
| `WEB_FETCH_ALLOW_PRIVATE` | 设 `1` 放行 web_fetch 访问内网/回环（云元数据端点仍硬拦） | 关（SSRF 安全） |
|
|
150
|
-
| `MCP_CONFIG` | MCP 配置文件路径 | `<数据目录>/mcp.json` |
|
|
151
|
-
|
|
152
|
-
> CLI 经 Ink 独占 stdout；core 的 console 日志启动期被静默（调试时注释 `main.tsx` 里的重定向即可恢复）。
|
|
153
|
-
|
|
154
|
-
### 引擎偏好（`settings.json` 的 `engine` 段）
|
|
155
|
-
|
|
156
|
-
少数用户偏好类参数可在 settings.json 里调（与 VS Code 插件共享）。在数据目录下编辑 `settings.json`：
|
|
157
|
-
|
|
158
|
-
```jsonc
|
|
159
|
-
// ~/.deepseeker-code/settings.json （或 DEEPSEEKER_CODE_DATA_DIR 指向的目录）
|
|
160
|
-
{
|
|
161
|
-
"engine": {
|
|
162
|
-
"undoEnabled": true, // Undo 总开关：false 跳过所有写前备份（紧急降级）
|
|
163
|
-
"undoBackupSensitive": "skip", // 敏感文件(.env/私钥)备份策略：skip|deny|allow
|
|
164
|
-
"undoRetentionDays": 7, // Undo 备份保留天数
|
|
165
|
-
"traceRetentionDays": 7, // trace 诊断日志保留天数
|
|
166
|
-
"MAX_TOOL_RESULT_CHARS": 16000 // 单次工具结果截断长度（读大日志可放宽）
|
|
167
|
-
}
|
|
168
|
-
}
|
|
169
|
-
```
|
|
170
|
-
|
|
171
|
-
项目级 `<项目>/.deepseeker-code/settings.json` 的 `engine` 段会**覆盖**全局；非法值会被忽略并告警。
|
|
172
|
-
|
|
173
|
-
> ⚠️ **不可调**：上下文窗口（`MAX_HISTORY_TOKENS`）、压缩阈值（`COMPACT_RATIO`）、推理轮数等是针对 DeepSeek-V4 精调过的引擎参数，刻意不开放——调高反而越过精度甜点区。如确需改，改源码重编。
|
|
174
|
-
|
|
175
|
-
### 声明式配置（Hooks / 权限 / 状态栏 / MCP / Skills）
|
|
176
|
-
|
|
177
|
-
均从 `~/.deepseeker-code/`（全局）+ `<项目>/.deepseeker-code/`（项目，**首次进入该目录会交互式确认信任**）读取。CLI 与 VS Code 插件**完全一致**：
|
|
178
|
-
|
|
179
|
-
| 配置 | 位置 | 作用 |
|
|
180
|
-
| --- | --- | --- |
|
|
181
|
-
| **Hooks** | `settings.json` 的 `hooks` 段 | 生命周期事件（PreToolUse/PostToolUse/UserPromptSubmit/Stop 等）触发命令/http/注入/子 agent |
|
|
182
|
-
| **权限规则** | `settings.json` 的 `permissions` 段 | `allow`/`deny`/`ask` 细粒度工具放行（如 `run_command(npm:*)`） |
|
|
183
|
-
| **状态栏** | `settings.json` 的 `statusLine` 段 | 自定义底部状态栏命令（stdin 收 JSON 上下文，stdout 首行作状态栏） |
|
|
184
|
-
| **MCP** | `mcp.json`（独立文件，**非** settings.json） | 接入外部 MCP server 工具 |
|
|
185
|
-
| **Skills** | `skills/<name>/SKILL.md` | 可被 agent 按需加载的技能包 |
|
|
186
|
-
| **子 Agent** | `agents/<name>.agent.md` | 声明式子 agent 角色 |
|
|
187
|
-
| **斜杠命令** | `commands/<name>.md` | 自定义 `/命令` |
|
|
188
|
-
| **输出风格** | `output-styles/<name>.md` | 自定义回复人格（`/output-style <name>` 选用） |
|
|
189
|
-
|
|
190
|
-
settings.json 完整示例（代码真正消费的字段）：
|
|
191
|
-
|
|
192
|
-
```jsonc
|
|
193
|
-
{
|
|
194
|
-
"engine": { /* 见上 */ },
|
|
195
|
-
"hooks": {
|
|
196
|
-
"PreToolUse": [
|
|
197
|
-
{ "matcher": "run_command", "command": "./audit.sh", "denyOnNonZero": true }
|
|
198
|
-
],
|
|
199
|
-
"UserPromptSubmit": [
|
|
200
|
-
{ "type": "prompt", "text": "涉及数据库时先确认备份策略。" }
|
|
201
|
-
]
|
|
202
|
-
},
|
|
203
|
-
"permissions": {
|
|
204
|
-
"allow": ["run_command(npm:*)", "read_file(src/*)"],
|
|
205
|
-
"deny": ["read_file(.env)", "run_command(rm:*)"],
|
|
206
|
-
"ask": ["web_fetch(*)"]
|
|
207
|
-
},
|
|
208
|
-
"statusLine": { "command": "~/.deepseeker-code/statusline.sh", "padding": 0 }
|
|
209
|
-
}
|
|
210
|
-
```
|
|
211
|
-
|
|
212
|
-
MCP 配置（`mcp.json`，独立文件）：
|
|
213
|
-
|
|
214
|
-
```jsonc
|
|
215
|
-
{
|
|
216
|
-
"mcpServers": {
|
|
217
|
-
"local": { "command": "npx", "args": ["-y", "@xxx/server"], "env": { "KEY": "..." } },
|
|
218
|
-
"remote": { "type": "http", "url": "https://.../mcp", "headers": { "Authorization": "Bearer ..." } },
|
|
219
|
-
"stream": { "type": "sse", "url": "https://.../sse" }
|
|
220
|
-
}
|
|
221
|
-
}
|
|
222
|
-
```
|
|
223
|
-
|
|
224
|
-
---
|
|
225
|
-
|
|
226
|
-
## 数据目录
|
|
227
|
-
|
|
228
|
-
默认 `~/.deepseeker-code/`（可用 `DEEPSEEKER_CODE_DATA_DIR` 改位置）。布局：
|
|
229
|
-
|
|
230
|
-
```text
|
|
231
|
-
~/.deepseeker-code/
|
|
232
|
-
├── config.json # 连接/模型/运行时配置（CLI 读取，见「配置」段）
|
|
233
|
-
├── settings.json # 声明式配置（engine/hooks/permissions/statusLine）
|
|
234
|
-
├── mcp.json # MCP server 配置（独立文件）
|
|
235
|
-
├── prefs.json # UI 偏好（语言等）
|
|
236
|
-
├── skills/ # 全局 skills
|
|
237
|
-
├── agents/ # 全局子 agent
|
|
238
|
-
├── commands/ # 全局斜杠命令
|
|
239
|
-
├── output-styles/ # 全局输出风格
|
|
240
|
-
└── <工作区key>/ # 按工作区隔离的会话 transcript / trace / undo 备份
|
|
241
|
-
```
|
|
242
|
-
|
|
243
|
-
> 工作区 key 由项目绝对路径的 sha256 短哈希派生，故**同一项目无论从 CLI 还是 VS Code 打开，都命中同一份会话历史**。首次进入一个新项目目录时，CLI 会交互式询问是否信任（信任后才会加载该项目级 hooks/permissions/skills，防恶意仓库）。
|
|
244
|
-
|
|
245
|
-
---
|
|
246
|
-
|
|
247
|
-
## 从源码构建（开发者）
|
|
248
|
-
|
|
249
|
-
```bash
|
|
250
|
-
cd src/cli
|
|
251
|
-
pnpm install
|
|
252
|
-
pnpm build # esbuild 产出 dist/cli.mjs（内联 cli + core 源码，外部化 node_modules 依赖）
|
|
253
|
-
pnpm start # 运行打包产物
|
|
254
|
-
pnpm dev # 开发态（tsx 直跑）
|
|
255
|
-
|
|
256
|
-
# 全局安装本地构建：
|
|
257
|
-
pnpm build && npm i -g .
|
|
258
|
-
```
|
|
259
|
-
|
|
260
|
-
- **打包约定（与 VS Code 插件不同）**：CLI 用 `packages: "external"`，所有 node_modules 外部化，运行时从全局 `node_modules` 解析（ink/react/openai 等都是真运行时依赖，故留在 `dependencies`）。发布只发 `dist/cli.mjs` 单文件（`files` 字段）。
|
|
261
|
-
- **发布到 npm**：在 `src/cli/` 下 `npm publish`（`prepublishOnly` 自动构建）。安装方 `npm i -g deepseeker-code`。
|
|
262
|
-
|
|
263
|
-
---
|
|
264
|
-
|
|
265
|
-
## License
|
|
266
|
-
|
|
267
|
-
MIT
|
|
1
|
+
# DeepSeeker-Code
|
|
2
|
+
|
|
3
|
+
> DeepSeek 驱动的终端级 AI 编程助手（自研 agentic 架构）：agent 主循环 + 工具系统 + MCP + Hooks + Skills + 计划模式 + Undo 回退。本包是 **React Ink 终端客户端**。
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npm i -g deepseeker-code
|
|
7
|
+
export DEEP_SEEK_API_KEY=sk-你的key
|
|
8
|
+
cd 你的项目
|
|
9
|
+
deepseeker-code
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
DeepSeeker-Code 在你的终端里跑一个自主 agent：流式逐字输出、可折叠思考过程、工具调用卡、审批模态、两阶段计划模式、会话恢复。**in-process 直驱引擎**——不走 HTTP/端口，工具审批走 Ink 原生模态。
|
|
13
|
+
|
|
14
|
+
> 另有 **VS Code 插件**版本（同名 `deepseeker-code`），与终端版同源共享 core 引擎和 `~/.deepseeker-code/` 数据目录，同一项目下会话可互续。
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## 前置要求
|
|
19
|
+
|
|
20
|
+
- **Node.js ≥ 20**（esbuild target node20）
|
|
21
|
+
- **DeepSeek API Key**：通过 `~/.deepseeker-code/config.json` 的 `apiKey` 字段**或**环境变量 `DEEP_SEEK_API_KEY` 提供（**无交互式输入、无 `--model` 参数**）；两者都缺会直接退出并提示。
|
|
22
|
+
- **真实终端（TTY）**：UI 基于 React Ink，依赖 TTY；不要在 `npm run` / 管道 / 非交互 shell 里跑。
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## 快速开始
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
# 1. 全局安装
|
|
30
|
+
npm install -g deepseeker-code
|
|
31
|
+
|
|
32
|
+
# 2. 配置 API Key（二选一）
|
|
33
|
+
# 方式 A（推荐，免环境变量）：写入 ~/.deepseeker-code/config.json
|
|
34
|
+
mkdir -p ~/.deepseeker-code && echo '{ "apiKey": "sk-你的key" }' > ~/.deepseeker-code/config.json
|
|
35
|
+
# 方式 B：环境变量（写入 shell 配置持久化，如 ~/.bashrc / ~/.zshrc / PowerShell $PROFILE）
|
|
36
|
+
export DEEP_SEEK_API_KEY=sk-你的key # Windows PowerShell: $env:DEEP_SEEK_API_KEY="sk-..."
|
|
37
|
+
|
|
38
|
+
# 3. 进入项目目录运行（agent 的工作区 = 当前目录）
|
|
39
|
+
cd ~/projects/my-app
|
|
40
|
+
deepseeker-code
|
|
41
|
+
|
|
42
|
+
# 可选：进入即计划模式
|
|
43
|
+
deepseeker-code --plan
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
---
|
|
47
|
+
|
|
48
|
+
## 命令行参数
|
|
49
|
+
|
|
50
|
+
| 参数 | 短写 | 作用 |
|
|
51
|
+
| --- | --- | --- |
|
|
52
|
+
| `--resume <会话id>` | `-r` | 续接指定会话 |
|
|
53
|
+
| `--continue` | `-c` | 自动续接本工作区最近一次会话 |
|
|
54
|
+
| `--plan` | `-p` | 初始进入计划模式（只读调研 → 方案 → 实现） |
|
|
55
|
+
| `--auto` | `-a` | 初始进入自动模式（按权限规则自动执行，少打断） |
|
|
56
|
+
|
|
57
|
+
> 没有 `--model` / `--print` / `--output-style` / `--session` 等参数。模型经 `DEEP_SEEK_MODEL` 环境变量设；输出风格经运行时 `/output-style <名称>` 切换。
|
|
58
|
+
|
|
59
|
+
## 聊天内命令
|
|
60
|
+
|
|
61
|
+
输入框以 `/` 开头（输入 `/` 会弹出补全菜单）：
|
|
62
|
+
|
|
63
|
+
| 命令 | 作用 |
|
|
64
|
+
| --- | --- |
|
|
65
|
+
| `/help` | 帮助 |
|
|
66
|
+
| `/plan` | 切换计划模式 |
|
|
67
|
+
| `/auto` | 切换自动模式 |
|
|
68
|
+
| `/model <名称>` | 切换模型 |
|
|
69
|
+
| `/thinking <off\|high\|max>` | 切换思考强度 |
|
|
70
|
+
| `/lang <zh\|en>` | 切换语言 |
|
|
71
|
+
| `/output-style <名称>` | 切换输出风格（人格） |
|
|
72
|
+
| `/sessions` | 列出并续接历史会话 |
|
|
73
|
+
| `/clear` | 新会话 |
|
|
74
|
+
| `/status` / `/usage` / `/context` | 查看状态 / 用量 / 上下文 |
|
|
75
|
+
| `/permissions` / `/mcp` / `/hooks` | 查看已加载的权限规则 / MCP / Hooks |
|
|
76
|
+
| `/debug` | 调试信息 |
|
|
77
|
+
| `/exit` / `/quit` | 退出 |
|
|
78
|
+
|
|
79
|
+
**快捷键**：`Ctrl+C` 退出 · `Esc` 中止/清输入 · `Ctrl+G` 中止当前轮 · `Ctrl+T` 展开/收起思考 · 模态/菜单 `↑↓ Enter`。
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## 配置
|
|
84
|
+
|
|
85
|
+
DeepSeeker-Code 支持三种配置来源，优先级 **环境变量 > config.json（CLI）/ 设置项（VSCode）> 内置默认**。环境变量始终最高，作为临时覆盖/CI 的逃生通道。
|
|
86
|
+
|
|
87
|
+
### 配置文件 config.json（CLI 推荐）
|
|
88
|
+
|
|
89
|
+
不必再到处设环境变量——把连接/模型/运行时配置写进 `~/.deepseeker-code/config.json`（全局；位于 `DEEPSEEKER_CODE_DATA_DIR` 指向的目录），CLI 启动时自动读取并回填，**仅当对应环境变量未设时才采用 config.json 的值**。
|
|
90
|
+
|
|
91
|
+
```jsonc
|
|
92
|
+
// ~/.deepseeker-code/config.json
|
|
93
|
+
{
|
|
94
|
+
"apiKey": "sk-你的key", // 不必再 export DEEP_SEEK_API_KEY
|
|
95
|
+
"model": "deepseek-v4-flash",
|
|
96
|
+
"auxModel": "deepseek-v4-flash",
|
|
97
|
+
"apiUrl": "https://api.deepseek.com",
|
|
98
|
+
"reasoningEffort": "high", // high | max
|
|
99
|
+
"thinking": true, // 默认开；false 关闭深度思考
|
|
100
|
+
"parallelSafeTools": true, // 默认开；false 回退同轮工具完全串行
|
|
101
|
+
"workflowConcurrency": 4,
|
|
102
|
+
"workflowMaxSteps": 8,
|
|
103
|
+
"streamIdleTimeoutMs": 120000
|
|
104
|
+
}
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
| 字段 | 类型 | 默认 | 对应环境变量 |
|
|
108
|
+
| --- | --- | --- | --- |
|
|
109
|
+
| `apiKey` | string | — | `DEEP_SEEK_API_KEY` |
|
|
110
|
+
| `apiUrl` | string | `https://api.deepseek.com` | `DEEP_SEEK_API_URL` |
|
|
111
|
+
| `model` | string | `deepseek-v4-flash` | `DEEP_SEEK_MODEL` |
|
|
112
|
+
| `auxModel` | string | `deepseek-v4-flash` | `DEEP_SEEK_AUX_MODEL` |
|
|
113
|
+
| `reasoningEffort` | `high`\|`max` | `high` | `DEEP_SEEK_REASONING_EFFORT` |
|
|
114
|
+
| `thinking` | boolean | `true` | `DEEP_SEEK_THINKING`（false→`0`） |
|
|
115
|
+
| `parallelSafeTools` | boolean | `true` | `DEEP_SEEK_PARALLEL_SAFE_TOOLS`（false→`0`） |
|
|
116
|
+
| `streamIdleTimeoutMs` | number | `120000` | `DEEP_SEEK_STREAM_IDLE_TIMEOUT_MS` |
|
|
117
|
+
| `workflowConcurrency` | number | `4` | `DEEP_SEEK_WORKFLOW_CONCURRENCY` |
|
|
118
|
+
| `workflowMaxSteps` | number | `8` | `DEEP_SEEK_WORKFLOW_MAX_STEPS` |
|
|
119
|
+
|
|
120
|
+
> - **VSCode 插件不读 config.json**——在设置界面（`deepseekerCode.*`）配置，字段语义与上表一致。
|
|
121
|
+
> - 文件缺失或字段留空都安全（回退环境变量/默认）；JSON 解析失败会打 stderr 警告并忽略整个文件，不阻断启动。
|
|
122
|
+
> - `DEEPSEEKER_CODE_DATA_DIR` 仍只能用环境变量设（它决定 config.json 的位置，鸡生蛋）。
|
|
123
|
+
> - config.json 明文存放 `apiKey`（与环境变量同等明文），建议加文件权限（`chmod 600`）。
|
|
124
|
+
|
|
125
|
+
### 环境变量
|
|
126
|
+
|
|
127
|
+
#### 模型 / API（`DEEP_SEEK_*` — 指向 DeepSeek 厂商）
|
|
128
|
+
|
|
129
|
+
| 变量 | 作用 | 默认 |
|
|
130
|
+
| --- | --- | --- |
|
|
131
|
+
| `DEEP_SEEK_API_KEY` | DeepSeek API Key（**必填**） | — |
|
|
132
|
+
| `DEEP_SEEK_API_URL` | API 基址（兼容 OpenAI 协议的代理可改此项） | `https://api.deepseek.com` |
|
|
133
|
+
| `DEEP_SEEK_MODEL` | 主模型 | `deepseek-v4-flash` |
|
|
134
|
+
| `DEEP_SEEK_AUX_MODEL` | 辅助模型（摘要 / 风险分类） | `deepseek-v4-flash` |
|
|
135
|
+
| `DEEP_SEEK_REASONING_EFFORT` | 推理强度，仅 `high` / `max` | `high` |
|
|
136
|
+
| `DEEP_SEEK_THINKING` | 深度思考开关，设 `0` 关闭 | 开 |
|
|
137
|
+
| `DEEP_SEEK_STREAM_IDLE_TIMEOUT_MS` | 流式 idle 超时（ms） | `120000` |
|
|
138
|
+
|
|
139
|
+
#### 产品行为
|
|
140
|
+
|
|
141
|
+
| 变量 | 作用 | 默认 |
|
|
142
|
+
| --- | --- | --- |
|
|
143
|
+
| `DEEPSEEKER_CODE_DATA_DIR` | 用户数据目录（会话/skills/hooks/mcp 全在此） | `~/.deepseeker-code` |
|
|
144
|
+
| `DEEP_SEEK_PARALLEL_SAFE_TOOLS` | 设 `0` 关闭同轮只读工具并发（默认开） | 开（并发） |
|
|
145
|
+
| `DEEP_SEEK_WORKFLOW_CONCURRENCY` | run_workflow 子 agent 并发上限 | `4` |
|
|
146
|
+
| `DEEP_SEEK_WORKFLOW_MAX_STEPS` | run_workflow 单次步数上限 | `8` |
|
|
147
|
+
| `SEARCH_PROVIDER` | 搜索后端 `tavily` / `bing` / `ddg` | 自动（有 Tavily key 用 Tavily，否则 Bing） |
|
|
148
|
+
| `TAVILY_API_KEY` | Tavily 搜索密钥 | — |
|
|
149
|
+
| `WEB_FETCH_ALLOW_PRIVATE` | 设 `1` 放行 web_fetch 访问内网/回环（云元数据端点仍硬拦） | 关（SSRF 安全） |
|
|
150
|
+
| `MCP_CONFIG` | MCP 配置文件路径 | `<数据目录>/mcp.json` |
|
|
151
|
+
|
|
152
|
+
> CLI 经 Ink 独占 stdout；core 的 console 日志启动期被静默（调试时注释 `main.tsx` 里的重定向即可恢复）。
|
|
153
|
+
|
|
154
|
+
### 引擎偏好（`settings.json` 的 `engine` 段）
|
|
155
|
+
|
|
156
|
+
少数用户偏好类参数可在 settings.json 里调（与 VS Code 插件共享）。在数据目录下编辑 `settings.json`：
|
|
157
|
+
|
|
158
|
+
```jsonc
|
|
159
|
+
// ~/.deepseeker-code/settings.json （或 DEEPSEEKER_CODE_DATA_DIR 指向的目录）
|
|
160
|
+
{
|
|
161
|
+
"engine": {
|
|
162
|
+
"undoEnabled": true, // Undo 总开关：false 跳过所有写前备份（紧急降级）
|
|
163
|
+
"undoBackupSensitive": "skip", // 敏感文件(.env/私钥)备份策略：skip|deny|allow
|
|
164
|
+
"undoRetentionDays": 7, // Undo 备份保留天数
|
|
165
|
+
"traceRetentionDays": 7, // trace 诊断日志保留天数
|
|
166
|
+
"MAX_TOOL_RESULT_CHARS": 16000 // 单次工具结果截断长度（读大日志可放宽）
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
项目级 `<项目>/.deepseeker-code/settings.json` 的 `engine` 段会**覆盖**全局；非法值会被忽略并告警。
|
|
172
|
+
|
|
173
|
+
> ⚠️ **不可调**：上下文窗口（`MAX_HISTORY_TOKENS`）、压缩阈值（`COMPACT_RATIO`）、推理轮数等是针对 DeepSeek-V4 精调过的引擎参数，刻意不开放——调高反而越过精度甜点区。如确需改，改源码重编。
|
|
174
|
+
|
|
175
|
+
### 声明式配置（Hooks / 权限 / 状态栏 / MCP / Skills）
|
|
176
|
+
|
|
177
|
+
均从 `~/.deepseeker-code/`（全局）+ `<项目>/.deepseeker-code/`（项目，**首次进入该目录会交互式确认信任**）读取。CLI 与 VS Code 插件**完全一致**：
|
|
178
|
+
|
|
179
|
+
| 配置 | 位置 | 作用 |
|
|
180
|
+
| --- | --- | --- |
|
|
181
|
+
| **Hooks** | `settings.json` 的 `hooks` 段 | 生命周期事件（PreToolUse/PostToolUse/UserPromptSubmit/Stop 等）触发命令/http/注入/子 agent |
|
|
182
|
+
| **权限规则** | `settings.json` 的 `permissions` 段 | `allow`/`deny`/`ask` 细粒度工具放行（如 `run_command(npm:*)`） |
|
|
183
|
+
| **状态栏** | `settings.json` 的 `statusLine` 段 | 自定义底部状态栏命令（stdin 收 JSON 上下文，stdout 首行作状态栏） |
|
|
184
|
+
| **MCP** | `mcp.json`（独立文件，**非** settings.json） | 接入外部 MCP server 工具 |
|
|
185
|
+
| **Skills** | `skills/<name>/SKILL.md` | 可被 agent 按需加载的技能包 |
|
|
186
|
+
| **子 Agent** | `agents/<name>.agent.md` | 声明式子 agent 角色 |
|
|
187
|
+
| **斜杠命令** | `commands/<name>.md` | 自定义 `/命令` |
|
|
188
|
+
| **输出风格** | `output-styles/<name>.md` | 自定义回复人格（`/output-style <name>` 选用） |
|
|
189
|
+
|
|
190
|
+
settings.json 完整示例（代码真正消费的字段）：
|
|
191
|
+
|
|
192
|
+
```jsonc
|
|
193
|
+
{
|
|
194
|
+
"engine": { /* 见上 */ },
|
|
195
|
+
"hooks": {
|
|
196
|
+
"PreToolUse": [
|
|
197
|
+
{ "matcher": "run_command", "command": "./audit.sh", "denyOnNonZero": true }
|
|
198
|
+
],
|
|
199
|
+
"UserPromptSubmit": [
|
|
200
|
+
{ "type": "prompt", "text": "涉及数据库时先确认备份策略。" }
|
|
201
|
+
]
|
|
202
|
+
},
|
|
203
|
+
"permissions": {
|
|
204
|
+
"allow": ["run_command(npm:*)", "read_file(src/*)"],
|
|
205
|
+
"deny": ["read_file(.env)", "run_command(rm:*)"],
|
|
206
|
+
"ask": ["web_fetch(*)"]
|
|
207
|
+
},
|
|
208
|
+
"statusLine": { "command": "~/.deepseeker-code/statusline.sh", "padding": 0 }
|
|
209
|
+
}
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
MCP 配置（`mcp.json`，独立文件）：
|
|
213
|
+
|
|
214
|
+
```jsonc
|
|
215
|
+
{
|
|
216
|
+
"mcpServers": {
|
|
217
|
+
"local": { "command": "npx", "args": ["-y", "@xxx/server"], "env": { "KEY": "..." } },
|
|
218
|
+
"remote": { "type": "http", "url": "https://.../mcp", "headers": { "Authorization": "Bearer ..." } },
|
|
219
|
+
"stream": { "type": "sse", "url": "https://.../sse" }
|
|
220
|
+
}
|
|
221
|
+
}
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
---
|
|
225
|
+
|
|
226
|
+
## 数据目录
|
|
227
|
+
|
|
228
|
+
默认 `~/.deepseeker-code/`（可用 `DEEPSEEKER_CODE_DATA_DIR` 改位置）。布局：
|
|
229
|
+
|
|
230
|
+
```text
|
|
231
|
+
~/.deepseeker-code/
|
|
232
|
+
├── config.json # 连接/模型/运行时配置（CLI 读取，见「配置」段）
|
|
233
|
+
├── settings.json # 声明式配置（engine/hooks/permissions/statusLine）
|
|
234
|
+
├── mcp.json # MCP server 配置（独立文件）
|
|
235
|
+
├── prefs.json # UI 偏好（语言等）
|
|
236
|
+
├── skills/ # 全局 skills
|
|
237
|
+
├── agents/ # 全局子 agent
|
|
238
|
+
├── commands/ # 全局斜杠命令
|
|
239
|
+
├── output-styles/ # 全局输出风格
|
|
240
|
+
└── <工作区key>/ # 按工作区隔离的会话 transcript / trace / undo 备份
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
> 工作区 key 由项目绝对路径的 sha256 短哈希派生，故**同一项目无论从 CLI 还是 VS Code 打开，都命中同一份会话历史**。首次进入一个新项目目录时，CLI 会交互式询问是否信任（信任后才会加载该项目级 hooks/permissions/skills，防恶意仓库）。
|
|
244
|
+
|
|
245
|
+
---
|
|
246
|
+
|
|
247
|
+
## 从源码构建（开发者）
|
|
248
|
+
|
|
249
|
+
```bash
|
|
250
|
+
cd src/cli
|
|
251
|
+
pnpm install
|
|
252
|
+
pnpm build # esbuild 产出 dist/cli.mjs（内联 cli + core 源码，外部化 node_modules 依赖）
|
|
253
|
+
pnpm start # 运行打包产物
|
|
254
|
+
pnpm dev # 开发态（tsx 直跑）
|
|
255
|
+
|
|
256
|
+
# 全局安装本地构建：
|
|
257
|
+
pnpm build && npm i -g .
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
- **打包约定（与 VS Code 插件不同）**：CLI 用 `packages: "external"`，所有 node_modules 外部化，运行时从全局 `node_modules` 解析（ink/react/openai 等都是真运行时依赖，故留在 `dependencies`）。发布只发 `dist/cli.mjs` 单文件（`files` 字段）。
|
|
261
|
+
- **发布到 npm**：在 `src/cli/` 下 `npm publish`（`prepublishOnly` 自动构建）。安装方 `npm i -g deepseeker-code`。
|
|
262
|
+
|
|
263
|
+
---
|
|
264
|
+
|
|
265
|
+
## License
|
|
266
|
+
|
|
267
|
+
MIT
|