返回 DeepSeek-TUI-2026
README.zh-CN.md
根目录 / README.zh-CN.md
1 # DeepSeek TUI
2
3 > **面向 [DeepSeek V4](https://platform.deepseek.com) 的终端原生编程智能体：100 万 token 上下文、思考模式流式推理、前缀缓存感知。自包含 Rust 二进制发布——开箱即带 MCP 客户端、沙箱和持久化任务队列。**
4
5 [English README](README.md)
6
7 ## 安装
8
9 `deepseek` 是自包含 Rust 二进制——**运行时不依赖 Node.js 或 Python**。
10 下面几种方式装出来的是同一套二进制，按你已有的工具链选一个即可：
11
12 ```bash
13 # 1. npm —— 已装 Node 的最方便方式。npm 包只是一个下载器，
14 # 会从 GitHub Releases 拉取对应平台的预编译二进制，
15 # 并不会让 deepseek 本身依赖 Node 运行时。
16 npm install -g deepseek-tui
17
18 # 2. Cargo —— 无需 Node。
19 cargo install deepseek-tui-cli --locked # `deepseek` 入口
20 cargo install deepseek-tui --locked # `deepseek-tui` TUI 二进制
21
22 # 3. Homebrew —— macOS 包管理器。
23 brew tap Hmbown/deepseek-tui
24 brew install deepseek-tui
25
26 # 4. 直接下载 —— 无需任何工具链。
27 # https://github.com/Hmbown/DeepSeek-TUI/releases
28 # 覆盖 Linux x64/ARM64、macOS x64/ARM64、Windows x64
29 ```
30
31 > 中国大陆访问较慢时，npm 可加 `--registry=https://registry.npmmirror.com`，
32 > 或使用下方的 [Cargo 镜像](#中国大陆--镜像友好安装)。
33
34 [![CI](https://github.com/Hmbown/DeepSeek-TUI/actions/workflows/ci.yml/badge.svg)](https://github.com/Hmbown/DeepSeek-TUI/actions/workflows/ci.yml)
35 [![npm](https://img.shields.io/npm/v/deepseek-tui)](https://www.npmjs.com/package/deepseek-tui)
36 [![crates.io](https://img.shields.io/crates/v/deepseek-tui-cli?label=crates.io)](https://crates.io/crates/deepseek-tui-cli)
37
38 ![DeepSeek TUI 截图](assets/screenshot.png)
39
40 ---
41
42 ## 这是什么？
43
44 DeepSeek TUI 是一个完全运行在终端里的编程智能体。它让 DeepSeek 前沿模型直接访问你的工作区：读写文件、运行 shell 命令、搜索浏览网页、管理 git、调度子智能体——全部通过快速、键盘驱动的 TUI 完成。
45
46 它面向 **DeepSeek V4**（`deepseek-v4-pro` / `deepseek-v4-flash`）构建，原生支持 100 万 token 上下文窗口和思考模式流式输出。
47
48 ### 主要功能
49
50 - **原生 RLM**（`rlm_query`）—— 利用现有 API 客户端并行调度 1-16 个低成本 `deepseek-v4-flash` 子任务，用于批量分析和并行推理
51 - **思考模式流式输出** —— 实时观察模型在解决问题时的思维链展开
52 - **完整工具集** —— 文件操作、shell 执行、git、网页搜索/浏览、apply-patch、子智能体、MCP 服务器
53 - **100 万 token 上下文** —— 上下文接近上限时自动智能压缩，支持前缀缓存感知以降低成本
54 - **三种交互模式** —— Plan（只读探索）、Agent（带审批的默认交互）、YOLO（可信工作区自动批准）
55 - **推理强度档位** —— 用 `Shift+Tab` 在 `off → high → max` 之间切换
56 - **会话保存和恢复** —— 长任务的断点续作
57 - **工作区回滚** —— 通过 side-git 记录每轮前后快照，支持 `/restore` 和 `revert_turn`，不影响项目自己的 `.git`
58 - **持久化任务队列** —— 后台任务在重启后仍然存在，支持计划任务和长时间运行的操作
59 - **HTTP/SSE 运行时 API** —— `deepseek serve --http` 用于无界面智能体流程
60 - **MCP 协议** —— 连接 Model Context Protocol 服务器扩展工具，见 [docs/MCP.md](docs/MCP.md)
61 - **LSP 诊断** —— 每次编辑后通过 rust-analyzer、pyright、typescript-language-server、gopls、clangd 提供内联错误/警告
62 - **用户记忆** —— 可选的持久化笔记文件注入系统提示，实现跨会话偏好保持
63 - **多语言 UI** —— 支持 `en`、`ja`、`zh-Hans`、`pt-BR`，支持自动检测
64 - **实时成本跟踪** —— 按轮次和会话统计 token 用量与成本估算，含缓存命中/未命中明细
65 - **技能系统** —— 可通过 GitHub 安装的组合式指令包，无需后端服务
66
67 ---
68
69 ## 架构说明
70
71 `deepseek`（调度器 CLI）→ `deepseek-tui`（伴随二进制）→ ratatui 界面 ↔ 异步引擎 ↔ OpenAI 兼容流式客户端。工具调用通过类型化注册表（shell、文件操作、git、web、子智能体、MCP、RLM）路由，结果流式返回对话记录。引擎管理会话状态、轮次追踪、持久化任务队列和 LSP 子系统——它在下一步推理前将编辑后诊断反馈到模型上下文中。
72
73 详见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
74
75 ---
76
77 ## 快速开始
78
79 ```bash
80 npm install -g deepseek-tui
81 deepseek --version
82 deepseek
83 ```
84
85 预构建二进制覆盖 **Linux x64**、**Linux ARM64**（v0.8.8 起）、**macOS x64**、**macOS ARM64** 和 **Windows x64**。其他目标平台（musl、riscv64、FreeBSD 等）请见下方的[从源码安装](#从源码安装)或 [docs/INSTALL.md](docs/INSTALL.md)。
86
87 首次启动时会提示输入 [DeepSeek API key](https://platform.deepseek.com/api_keys)。密钥保存到 `~/.deepseek/config.toml`，在任意目录、IDE 终端和脚本中都能使用，不会触发系统密钥环弹窗。
88
89 也可以提前配置：
90
91 ```bash
92 deepseek auth set --provider deepseek # 保存到 ~/.deepseek/config.toml
93
94 export DEEPSEEK_API_KEY="YOUR_KEY" # 环境变量方式；需要在非交互式 shell 中使用请放入 ~/.zshenv
95 deepseek
96
97 deepseek doctor # 验证安装
98 ```
99
100 > 轮换或移除密钥：`deepseek auth clear --provider deepseek`。
101
102 ### Linux ARM64（HarmonyOS 轻薄本、openEuler、Kylin、树莓派、Graviton 等）
103
104 从 v0.8.8 起，`npm i -g deepseek-tui` 直接支持 glibc 系的 ARM64 Linux。你也可以从 [Releases 页面](https://github.com/Hmbown/DeepSeek-TUI/releases) 下载预编译二进制，放到 `PATH` 目录中。
105
106 ### 中国大陆 / 镜像友好安装
107
108 如果在中国大陆访问 GitHub 或 npm 下载较慢，可以通过 Cargo 注册表镜像安装：
109
110 ```toml
111 # ~/.cargo/config.toml
112 [source.crates-io]
113 replace-with = "tuna"
114
115 [source.tuna]
116 registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"
117 ```
118
119 然后安装两个二进制（调度器在运行时会调用 TUI）：
120
121 ```bash
122 cargo install deepseek-tui-cli --locked # 提供推荐入口 `deepseek`
123 cargo install deepseek-tui --locked # 提供交互式 TUI 伴随二进制
124 deepseek --version
125 ```
126
127 也可以直接从 [GitHub Releases](https://github.com/Hmbown/DeepSeek-TUI/releases) 下载预编译二进制。`DEEPSEEK_TUI_RELEASE_BASE_URL` 可用于镜像后的 release 资产。
128
129 ### Windows (Scoop)
130
131 [Scoop](https://scoop.sh) 是一个 Windows 软件包管理器。安装好 Scoop 后，运行：
132
133 ```bash
134 scoop install deepseek-tui
135 ```
136
137
138 <details id="install-from-source">
139 <summary>从源码安装</summary>
140
141 适用于任何 Tier-1 Rust 目标，包括 musl、riscv64、FreeBSD 以及尚无预编译包的 ARM64 发行版。
142
143 ```bash
144 # Linux 构建依赖（Debian/Ubuntu/RHEL）：
145 # sudo apt-get install -y build-essential pkg-config libdbus-1-dev
146 # sudo dnf install -y gcc make pkgconf-pkg-config dbus-devel
147
148 git clone https://github.com/Hmbown/DeepSeek-TUI.git
149 cd DeepSeek-TUI
150
151 cargo install --path crates/cli --locked # 需要 Rust 1.88+；提供 `deepseek`
152 cargo install --path crates/tui --locked # 提供 `deepseek-tui`
153 ```
154
155 两个二进制都需要安装。交叉编译和平台特定说明见 [docs/INSTALL.md](docs/INSTALL.md)。
156
157 </details>
158
159 ### 其他模型提供方
160
161 ```bash
162 # NVIDIA NIM
163 deepseek auth set --provider nvidia-nim --api-key "YOUR_NVIDIA_API_KEY"
164 deepseek --provider nvidia-nim
165
166 # Fireworks
167 deepseek auth set --provider fireworks --api-key "YOUR_FIREWORKS_API_KEY"
168 deepseek --provider fireworks --model deepseek-v4-pro
169
170 # 自托管 SGLang
171 SGLANG_BASE_URL="http://localhost:30000/v1" deepseek --provider sglang --model deepseek-v4-flash
172
173 # 自托管 vLLM
174 VLLM_BASE_URL="http://localhost:8000/v1" deepseek --provider vllm --model deepseek-v4-flash
175 ```
176
177 ---
178
179 ## v0.8.13 新功能
180
181 稳定性发布：聚焦 DeepSeek V4 运行时可靠性、工具调用恢复和 TUI 状态准确性。[完整更新日志](CHANGELOG.md)。
182
183 - **无需 LLM 的压缩预剪枝** —— 付费摘要前先机械压缩旧的大型工具结果；重复读取只保留最新完整内容
184 - **重复工具调用防循环** —— 同一轮内第三次完全相同的 `(tool, args)` 会变成纠正性工具结果，而不是继续卡住重试
185 - **V4 缓存命中率状态栏** —— 状态栏现在识别 `usage.prompt_tokens_details.cached_tokens`
186 - **工具调用恢复** —— 无效 JSON 参数、幻觉工具名和严格 schema 问题会在分发前修复或清理
187 - **区分大小写的模型 ID** —— 第三方 provider 的模型名保留用户输入大小写，同时继续规范化紧凑 DeepSeek 别名
188 - **忙碌状态修复** —— 如果 turn 开始前分发失败，会清除 `working...`，避免后续输入一直进入 pending
189 - **不会弹出 Keychain 的 doctor 密钥检查** —— 诊断流程不再读取 OS keyring
190 - **macOS Terminal 颜色兼容** —— `xterm-256color` 会使用 256 色索引，避免鲸蓝主题被渲染成绿色/青色块
191
192 ---
193
194 ## 使用方式
195
196 ```bash
197 deepseek # 交互式 TUI
198 deepseek "explain this function" # 一次性提示
199 deepseek --model deepseek-v4-flash "summarize" # 指定模型
200 deepseek --yolo # 自动批准工具
201 deepseek auth set --provider deepseek # 保存 API key
202 deepseek doctor # 检查配置和连接
203 deepseek doctor --json # 机器可读诊断
204 deepseek setup --status # 只读安装状态
205 deepseek setup --tools --plugins # 创建本地工具和插件目录
206 deepseek models # 列出可用 API 模型
207 deepseek sessions # 列出已保存会话
208 deepseek resume --last # 恢复最近会话
209 deepseek resume <SESSION_ID> # 按 UUID 恢复指定会话
210 deepseek fork <SESSION_ID> # 在指定轮次分叉会话
211 deepseek serve --http # HTTP/SSE API 服务
212 deepseek pr <N> # 获取 PR 并预填审查提示
213 deepseek mcp list # 列出已配置 MCP 服务器
214 deepseek mcp validate # 校验 MCP 配置和连接
215 deepseek mcp-server # 启动 dispatcher MCP stdio 服务器
216 deepseek update # 检查并应用二进制更新
217 ```
218
219 ### 常用快捷键
220
221 | 按键 | 功能 |
222 |---|---|
223 | `Tab` | 补全 `/` 或 `@`；运行中则把草稿排队；否则切换模式 |
224 | `Shift+Tab` | 切换推理强度：off → high → max |
225 | `F1` | 可搜索帮助面板 |
226 | `Esc` | 返回 / 关闭 |
227 | `Ctrl+K` | 命令面板 |
228 | `Ctrl+R` | 恢复旧会话 |
229 | `Alt+R` | 搜索提示历史和恢复草稿 |
230 | `Ctrl+S` | 暂存当前草稿（`/stash list`、`/stash pop` 恢复） |
231 | `@path` | 在输入框中附加文件或目录上下文 |
232 | `↑`（在输入框开头） | 选择附件行进行移除 |
233
234 完整快捷键目录：[docs/KEYBINDINGS.md](docs/KEYBINDINGS.md)。
235
236 ---
237
238 ## 模式
239
240 | 模式 | 行为 |
241 |---|---|
242 | **Plan** 🔍 | 只读调查；模型先探索并提出计划（`update_plan` + `checklist_write`），然后再做更改 |
243 | **Agent** 🤖 | 默认交互模式；多步工具调用带审批门禁 |
244 | **YOLO** ⚡ | 在可信工作区自动批准工具；仍会维护计划和清单以保持可见性 |
245
246 ---
247
248 ## 配置
249
250 用户配置：`~/.deepseek/config.toml`。项目覆盖：`<workspace>/.deepseek/config.toml`（以下密钥被拒绝：`api_key`、`base_url`、`provider`、`mcp_config_path`）。完整选项见 [config.example.toml](config.example.toml)。
251
252 常用环境变量：
253
254 | 变量 | 用途 |
255 |---|---|
256 | `DEEPSEEK_API_KEY` | DeepSeek API key |
257 | `DEEPSEEK_BASE_URL` | API base URL |
258 | `DEEPSEEK_MODEL` | 默认模型 |
259 | `DEEPSEEK_PROVIDER` | `deepseek`（默认）、`nvidia-nim`、`fireworks`、`sglang`、`vllm` |
260 | `DEEPSEEK_PROFILE` | 配置 profile 名称 |
261 | `DEEPSEEK_MEMORY` | 设为 `on` 启用用户记忆 |
262 | `NVIDIA_API_KEY` / `FIREWORKS_API_KEY` / `SGLANG_API_KEY` / `VLLM_API_KEY` | 提供商认证 |
263 | `SGLANG_BASE_URL` | 自托管 SGLang 端点 |
264 | `VLLM_BASE_URL` | 自托管 vLLM 端点 |
265 | `NO_ANIMATIONS=1` | 启动时强制无障碍模式 |
266 | `SSL_CERT_FILE` | 企业代理的自定义 CA 包 |
267
268 UI 语言与模型输出语言相互独立——在 `config.toml` 中设置 `locale`、使用 `/config locale zh-Hans`、或依赖 `LC_ALL`/`LANG`。详见 [docs/LOCALIZATION.md](docs/LOCALIZATION.md) 和 [docs/CONFIGURATION.md](docs/CONFIGURATION.md)。
269
270 ### 切换为中文界面
271
272 如果界面是其他语言，可以在 TUI 内一键切换为简体中文：
273
274 1. 在 Composer 里输入 `/config`，按 Tab 或 Enter 打开配置面板。
275 2. 选择 **Edit locale**，在 `New:` 字段输入 `zh-Hans`，按 Enter 应用。
276
277 可选语言：`auto` | `en` | `ja` | `zh-Hans` | `pt-BR`。
278
279 也可以在 `~/.deepseek/config.toml` 里直接设置 `locale = "zh-Hans"`，或通过 `LC_ALL` / `LANG` 环境变量自动选择：
280
281 ```toml
282 # ~/.deepseek/config.toml
283 [tui]
284 locale = "zh-Hans"
285 ```
286
287 或者通过环境变量（中文系统通常已自动生效）：
288
289 ```bash
290 LANG=zh_CN.UTF-8 deepseek run
291 ```
292
293 ---
294
295 ## 模型和价格
296
297 | 模型 | 上下文 | 输入（缓存命中） | 输入（缓存未命中） | 输出 |
298 |---|---|---|---|---|
299 | `deepseek-v4-pro` | 1M | $0.003625 / 1M* | $0.435 / 1M* | $0.87 / 1M* |
300 | `deepseek-v4-flash` | 1M | $0.0028 / 1M | $0.14 / 1M | $0.28 / 1M |
301
302 旧别名 `deepseek-chat` / `deepseek-reasoner` 映射到 `deepseek-v4-flash`。NVIDIA NIM 变体使用你的 NVIDIA 账号条款。
303
304 *DeepSeek Pro 价格是限时 75% 折扣，有效期到 2026-05-31 15:59 UTC；该时间之后 TUI 成本估算会回退到 Pro 基础价格。*
305
306 > [!Note]
307 > 关于 DeepSeek-V4-Pro 的最新定价信息，请参阅官方 [DeepSeek 定价页面](https://api-docs.deepseek.com/zh-cn/quick_start/pricing)，请注意目前可享受 75% 的折扣，该优惠有效期至 **2026 年 5 月 31 日 23:59（北京时间）**。此外，README 文档中所列出的所有价格，均与官方发布的数值保持一致。
308
309 ---
310
311 ## 创建和安装技能
312
313 DeepSeek TUI 从工作区目录（`.agents/skills` → `skills` → `.opencode/skills` → `.claude/skills`）和全局 `~/.deepseek/skills` 发现技能。每个技能是一个包含 `SKILL.md` 的目录：
314
315 ```text
316 ~/.deepseek/skills/my-skill/
317 └── SKILL.md
318 ```
319
320 需要 YAML frontmatter：
321
322 ```markdown
323 ---
324 name: my-skill
325 description: 当 DeepSeek 需要遵循我的自定义工作流时使用这个技能。
326 ---
327
328 # My Skill
329 这里写给智能体的指令。
330 ```
331
332 常用命令：`/skills`（列出）、`/skill <name>`（激活）、`/skill new`（创建）、`/skill install github:<owner>/<repo>`（社区）、`/skill update` / `uninstall` / `trust`。社区技能直接从 GitHub 安装，无需后端服务。已安装技能在模型可见的会话上下文里列出；当任务匹配技能描述时，智能体可通过 `load_skill` 工具自动读取对应的 `SKILL.md`。
333
334 ---
335
336 ## 文档
337
338 | 文档 | 主题 |
339 |---|---|
340 | [ARCHITECTURE.md](docs/ARCHITECTURE.md) | 代码库内部结构 |
341 | [CONFIGURATION.md](docs/CONFIGURATION.md) | 完整配置参考 |
342 | [MODES.md](docs/MODES.md) | Plan / Agent / YOLO 模式 |
343 | [MCP.md](docs/MCP.md) | Model Context Protocol 集成 |
344 | [RUNTIME_API.md](docs/RUNTIME_API.md) | HTTP/SSE API 服务 |
345 | [INSTALL.md](docs/INSTALL.md) | 各平台安装指南 |
346 | [MEMORY.md](docs/MEMORY.md) | 用户记忆功能指南 |
347 | [SUBAGENTS.md](docs/SUBAGENTS.md) | 子智能体角色分类与生命周期 |
348 | [KEYBINDINGS.md](docs/KEYBINDINGS.md) | 完整快捷键目录 |
349 | [RELEASE_RUNBOOK.md](docs/RELEASE_RUNBOOK.md) | 发布流程 |
350 | [LOCALIZATION.md](docs/LOCALIZATION.md) | UI 语言矩阵与切换 |
351 | [OPERATIONS_RUNBOOK.md](docs/OPERATIONS_RUNBOOK.md) | 运维和恢复 |
352
353 完整更新历史：[CHANGELOG.md](CHANGELOG.md)。
354
355 ---
356
357 ## 致谢
358
359 本项目由不断壮大的贡献者社区共同打造：
360
361 - **[merchloubna70-dot](https://github.com/merchloubna70-dot)** — 28 个 PR，涵盖功能、修复和 VS Code 扩展基础架构 (#645–#681)
362 - **[WyxBUPT-22](https://github.com/WyxBUPT-22)** — Markdown 表格、粗体/斜体和水平线渲染 (#579)
363 - **[loongmiaow-pixel](https://github.com/loongmiaow-pixel)** — Windows + 中国安装文档 (#578)
364 - **[20bytes](https://github.com/20bytes)** — 用户记忆文档和帮助优化 (#569)
365 - **[staryxchen](https://github.com/staryxchen)** — glibc 兼容性预检 (#556)
366 - **[Vishnu1837](https://github.com/Vishnu1837)** — glibc 兼容性改进 (#565)
367 - **[shentoumengxin](https://github.com/shentoumengxin)** — Shell `cwd` 边界验证 (#524)
368 - **[toi500](https://github.com/toi500)** — Windows 粘贴修复报告
369 - **[xsstomy](https://github.com/xsstomy)** — 终端启动重绘报告
370 - **[melody0709](https://github.com/melody0709)** — 斜杠前缀回车激活报告
371 - **[lloydzhou](https://github.com/lloydzhou)** 和 **[jeoor](https://github.com/jeoor)** — 压缩成本报告
372 - **[Agent-Skill-007](https://github.com/Agent-Skill-007)** — README 清晰化改进 (#685)
373 - **[woyxiang](https://github.com/woyxiang)** — Windows Scoop 安装文档 (#696)
374 - **[wangfeng](mailto:wangfengcsu@qq.com)** — 价格/折扣信息更新 (#692)
375 - **[zichen0116](https://github.com/zichen0116)** — CODE_OF_CONDUCT.md (#686)
376 - **[dfwqdyl-ui](https://github.com/dfwqdyl-ui)** — 模型 ID 大小写兼容性报告 (#729)
377 - **[Oliver-ZPLiu](https://github.com/Oliver-ZPLiu)** — `working...` 卡死状态 Bug 报告，含详细复现步骤和修复建议 (#738)
378 - **Hafeez Pizofreude** — `fetch_url` 的 SSRF 保护和 Star History 图表
379 - **Unic (YuniqueUnic)** — 基于 schema 的配置 UI（TUI + web）
380 - **Jason** — SSRF 安全加固
381
382 ---
383
384 ## 贡献
385
386 欢迎提交 pull request——请先查看 [CONTRIBUTING.md](CONTRIBUTING.md) 并留意[开放 issue](https://github.com/Hmbown/DeepSeek-TUI/issues) 中的好入门任务。
387
388 *本项目与 DeepSeek Inc. 无隶属关系。*
389
390 ## 许可证
391
392 [MIT](LICENSE)
393
394 ## Star 历史
395
396 [![Star History Chart](https://api.star-history.com/chart?repos=Hmbown/DeepSeek-TUI&type=date&legend=top-left)](https://www.star-history.com/?repos=Hmbown%2FDeepSeek-TUI&type=date&logscale=&legend=top-left)
397
397 lines MARKDOWN