codewhale/README.zh-CN.md

DeepSeek TUI

面向 DeepSeek V4 模型的终端原生编程智能体，支持 100 万 token 上下文、思考模式推理流和完整工具调用。单一二进制，无需 Node/Python 运行时——开箱即带 MCP 客户端、沙箱和持久化任务队列。

English README

npm i -g deepseek-tui

---

这是什么？

DeepSeek TUI 是一个完全运行在终端里的编程智能体。它让 DeepSeek 前沿模型直接访问你的工作区：读写文件、运行 shell 命令、搜索浏览网页、管理 git、调度子智能体——全部通过快速、键盘驱动的 TUI 完成。

它面向 DeepSeek V4（deepseek-v4-pro / deepseek-v4-flash）构建，原生支持 100 万 token 上下文窗口和思考模式流式输出。

主要功能

• 原生 RLM（rlm_query）—— 利用现有 API 客户端并行调度 1-16 个低成本 deepseek-v4-flash 子任务，用于批量分析和并行推理
• 思考模式流式输出 —— 实时观察模型在解决问题时的思维链展开
• 完整工具集 —— 文件操作、shell 执行、git、网页搜索/浏览、apply-patch、子智能体、MCP 服务器
• 100 万 token 上下文 —— 上下文接近上限时自动智能压缩，支持前缀缓存感知以降低成本
• 三种交互模式 —— Plan（只读探索）、Agent（带审批的默认交互）、YOLO（可信工作区自动批准）
• 推理强度档位 —— 用 Shift+Tab 在 off → high → max 之间切换
• 会话保存和恢复 —— 长任务的断点续作
• 工作区回滚 —— 通过 side-git 记录每轮前后快照，支持 /restore 和 revert_turn，不影响项目自己的 .git
• 持久化任务队列 —— 后台任务在重启后仍然存在，支持计划任务和长时间运行的操作
• HTTP/SSE 运行时 API —— deepseek serve --http 用于无界面智能体流程
• MCP 协议 —— 连接 Model Context Protocol 服务器扩展工具，见 docs/MCP.md
• LSP 诊断 —— 每次编辑后通过 rust-analyzer、pyright、typescript-language-server、gopls、clangd 提供内联错误/警告
• 用户记忆 —— 可选的持久化笔记文件注入系统提示，实现跨会话偏好保持
• 多语言 UI —— 支持 en、ja、zh-Hans、pt-BR，支持自动检测
• 实时成本跟踪 —— 按轮次和会话统计 token 用量与成本估算，含缓存命中/未命中明细
• 技能系统 —— 可通过 GitHub 安装的组合式指令包，无需后端服务

---

架构说明

deepseek（调度器 CLI）→ deepseek-tui（伴随二进制）→ ratatui 界面 ↔ 异步引擎 ↔ OpenAI 兼容流式客户端。工具调用通过类型化注册表（shell、文件操作、git、web、子智能体、MCP、RLM）路由，结果流式返回对话记录。引擎管理会话状态、轮次追踪、持久化任务队列和 LSP 子系统——它在下一步推理前将编辑后诊断反馈到模型上下文中。

详见 docs/ARCHITECTURE.md。

---

快速开始

npm install -g deepseek-tui
deepseek

预构建二进制覆盖 Linux x64、Linux ARM64（v0.8.8 起）、macOS x64、macOS ARM64 和 Windows x64。其他目标平台（musl、riscv64、FreeBSD 等）请见下方的从源码安装或 docs/INSTALL.md。

首次启动时会提示输入 DeepSeek API key。密钥保存到 ~/.deepseek/config.toml，在任意目录、IDE 终端和脚本中都能使用，不会触发系统密钥环弹窗。

也可以提前配置：

deepseek auth set --provider deepseek   # 保存到 ~/.deepseek/config.toml

export DEEPSEEK_API_KEY="YOUR_KEY"      # 环境变量方式；需要在非交互式 shell 中使用请放入 ~/.zshenv
deepseek

deepseek doctor                          # 验证安装

轮换或移除密钥：deepseek auth clear --provider deepseek。

Linux ARM64（HarmonyOS 轻薄本、openEuler、Kylin、树莓派、Graviton 等）

从 v0.8.8 起，npm i -g deepseek-tui 直接支持 glibc 系的 ARM64 Linux。你也可以从 Releases 页面 下载预编译二进制，放到 PATH 目录中。

中国大陆 / 镜像友好安装

如果在中国大陆访问 GitHub 或 npm 下载较慢，可以通过 Cargo 注册表镜像安装：

# ~/.cargo/config.toml
[source.crates-io]
replace-with = "tuna"

[source.tuna]
registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"

然后安装两个二进制（调度器在运行时会调用 TUI）：

cargo install deepseek-tui-cli --locked   # 提供推荐入口 `deepseek`
cargo install deepseek-tui     --locked   # 提供交互式 TUI 伴随二进制
deepseek --version

也可以直接从 GitHub Releases 下载预编译二进制。DEEPSEEK_TUI_RELEASE_BASE_URL 可用于镜像后的 release 资产。

从源码安装

适用于任何 Tier-1 Rust 目标，包括 musl、riscv64、FreeBSD 以及尚无预编译包的 ARM64 发行版。

# Linux 构建依赖（Debian/Ubuntu/RHEL）：
#   sudo apt-get install -y build-essential pkg-config libdbus-1-dev
#   sudo dnf install -y gcc make pkgconf-pkg-config dbus-devel

git clone https://github.com/Hmbown/DeepSeek-TUI.git
cd DeepSeek-TUI

cargo install --path crates/cli --locked   # 需要 Rust 1.85+；提供 `deepseek`
cargo install --path crates/tui --locked   # 提供 `deepseek-tui`

两个二进制都需要安装。交叉编译和平台特定说明见 docs/INSTALL.md。

其他模型提供方

# NVIDIA NIM
deepseek auth set --provider nvidia-nim --api-key "YOUR_NVIDIA_API_KEY"
deepseek --provider nvidia-nim

# Fireworks
deepseek auth set --provider fireworks --api-key "YOUR_FIREWORKS_API_KEY"
deepseek --provider fireworks --model deepseek-v4-pro

# 自托管 SGLang
SGLANG_BASE_URL="http://localhost:30000/v1" deepseek --provider sglang --model deepseek-v4-flash

---

v0.8.10 新功能

补丁发布：热修复、UX 打磨和 whalescale 桌面集成的运行时 API 扩展。无破坏性变更。完整更新日志。

• 堆叠式 Toast 通知 —— 状态提示可以排队并叠放显示，不再互相覆盖
• 文件 @-提及频率排序 —— 文件提及建议学习近期选择（~/.deepseek/file-frecency.jsonl）
• 运行时 API 扩展 —— CORS 来源配置、完整线程编辑（PATCH /v1/threads/{id}）、archived_only 查询过滤、用量聚合端点（GET /v1/usage?group_by=day|model|provider|thread）
• 首次运行语言选择器 —— 新的引导步骤在输入 API 密钥前选择界面语言
• OPENCODE shell.env 钩子 —— 生命周期钩子可以向启动的命令注入 shell 环境
• 缓存感知压缩 —— 压缩调用复用缓存提示前缀，大幅降低 /compact 成本
• glibc 2.28 基础线 —— 预编译包现在针对 glibc 2.28（通过 cargo zigbuild），覆盖更老的发行版；npm postinstall 在不兼容时给出明确的源码构建提示
• 改进的 Markdown 渲染 —— 对话记录现在支持表格、粗体/斜体和水平线；不再有无穷循环问题
• MCP 关闭时发送 SIGTERM —— stdio 服务器收到 SIGTERM 并有 2 秒优雅退出时间，而非 SIGKILL
• Linux shell 子进程 PDEATHSIG —— 父进程退出时子进程自动收到 SIGTERM，消除泄漏窗口
• Windows Terminal 粘贴修复 —— 引导过程中 Ctrl/Cmd+V 现在正常工作
• 终端启动重绘 —— 首帧上方不再残留过时的默认背景行
• 斜杠前缀回车激活 —— 输入 /mo 后按回车自动激活第一个匹配项
• Shell cwd 边界验证 —— 超出工作区的 cwd 路径返回 PathEscape，与文件工具一致

6 位首次贡献者： @staryxchen (#556)、@shentoumengxin (#524)、@Vishnu1837 (#565)、@20bytes (#569)、@loongmiaow-pixel (#578)、@WyxBUPT-22 (#579)。 同时感谢 @lloydzhou、@jeoor、@toi500、@xsstomy 和 @melody0709 的错误报告。

---

使用方式

deepseek                                       # 交互式 TUI
deepseek "explain this function"              # 一次性提示
deepseek --model deepseek-v4-flash "summarize" # 指定模型
deepseek --yolo                                # 自动批准工具
deepseek auth set --provider deepseek         # 保存 API key
deepseek doctor                                # 检查配置和连接
deepseek doctor --json                         # 机器可读诊断
deepseek setup --status                        # 只读安装状态
deepseek setup --tools --plugins               # 创建本地工具和插件目录
deepseek models                                # 列出可用 API 模型
deepseek sessions                              # 列出已保存会话
deepseek resume --last                         # 恢复最近会话
deepseek serve --http                          # HTTP/SSE API 服务
deepseek pr <N>                                # 获取 PR 并预填审查提示
deepseek mcp list                              # 列出已配置 MCP 服务器
deepseek mcp validate                          # 校验 MCP 配置和连接
deepseek mcp-server                            # 启动 dispatcher MCP stdio 服务器

常用快捷键

按键	功能
Tab	补全 / 或 @；运行中则把草稿排队；否则切换模式
Shift+Tab	切换推理强度：off → high → max
F1	可搜索帮助面板
Esc	返回 / 关闭
Ctrl+K	命令面板
Ctrl+R	恢复旧会话
Alt+R	搜索提示历史和恢复草稿
Ctrl+S	暂存当前草稿（/stash list、/stash pop 恢复）
@path	在输入框中附加文件或目录上下文
↑（在输入框开头）	选择附件行进行移除
Alt+↑	编辑最后一条排队消息

完整快捷键目录：docs/KEYBINDINGS.md。

---

模式

模式	行为
Plan 🔍	只读调查；模型先探索并提出计划（update_plan + checklist_write），然后再做更改
Agent 🤖	默认交互模式；多步工具调用带审批门禁
YOLO ⚡	在可信工作区自动批准工具；仍会维护计划和清单以保持可见性

---

配置

用户配置：~/.deepseek/config.toml。项目覆盖：<workspace>/.deepseek/config.toml（以下密钥被拒绝：api_key、base_url、provider、mcp_config_path）。完整选项见 config.example.toml。

常用环境变量：

变量	用途
DEEPSEEK_API_KEY	DeepSeek API key
DEEPSEEK_BASE_URL	API base URL
DEEPSEEK_MODEL	默认模型
DEEPSEEK_PROVIDER	deepseek（默认）、nvidia-nim、fireworks、sglang
DEEPSEEK_PROFILE	配置 profile 名称
DEEPSEEK_MEMORY	设为 on 启用用户记忆
NVIDIA_API_KEY / FIREWORKS_API_KEY / SGLANG_API_KEY	提供商认证
SGLANG_BASE_URL	自托管 SGLang 端点
NO_ANIMATIONS=1	启动时强制无障碍模式
SSL_CERT_FILE	企业代理的自定义 CA 包

UI 语言与模型输出语言相互独立——在 settings.toml 中设置 locale、使用 /config locale zh-Hans、或依赖 LC_ALL/LANG。详见 docs/CONFIGURATION.md 和 docs/MCP.md。

切换为中文界面

如果界面是其他语言，可以在 TUI 内一键切换为简体中文：

1. 在 Composer 里输入 /config，按 Tab 或 Enter 打开配置面板。
2. 选择 Edit locale，在 New: 字段输入 zh-Hans，按 Enter 应用。

可选语言：auto | en | ja | zh-Hans | pt-BR。

也可以在 ~/.deepseek/settings.toml 里直接设置 locale = "zh-Hans"，或通过 LC_ALL / LANG 环境变量自动选择。

---

模型和价格

模型	上下文	输入（缓存命中）	输入（缓存未命中）	输出
deepseek-v4-pro	1M	$0.003625 / 1M*	$0.435 / 1M*	$0.87 / 1M*
deepseek-v4-flash	1M	$0.0028 / 1M	$0.14 / 1M	$0.28 / 1M

旧别名 deepseek-chat / deepseek-reasoner 映射到 deepseek-v4-flash。NVIDIA NIM 变体使用你的 NVIDIA 账号条款。

DeepSeek Pro 价格是限时 75% 折扣，有效期到 2026-05-05 15:59 UTC；该时间之后 TUI 成本估算会回退到 Pro 基础价格。

---

创建和安装技能

DeepSeek TUI 从工作区目录（.agents/skills → skills → .opencode/skills → .claude/skills）和全局 ~/.deepseek/skills 发现技能。每个技能是一个包含 SKILL.md 的目录：

~/.deepseek/skills/my-skill/
└── SKILL.md

需要 YAML frontmatter：

---
name: my-skill
description: 当 DeepSeek 需要遵循我的自定义工作流时使用这个技能。
---

# My Skill
这里写给智能体的指令。

常用命令：/skills（列出）、/skill <name>（激活）、/skill new（创建）、/skill install github:<owner>/<repo>（社区）、/skill update / uninstall / trust。社区技能直接从 GitHub 安装，无需后端服务。已安装技能在模型可见的会话上下文里列出；当任务匹配技能描述时，智能体可通过 load_skill 工具自动读取对应的 SKILL.md。

---

文档

文档	主题
ARCHITECTURE.md	代码库内部结构
CONFIGURATION.md	完整配置参考
MODES.md	Plan / Agent / YOLO 模式
MCP.md	Model Context Protocol 集成
RUNTIME_API.md	HTTP/SSE API 服务
INSTALL.md	各平台安装指南
MEMORY.md	用户记忆功能指南
SUBAGENTS.md	子智能体角色分类与生命周期
KEYBINDINGS.md	完整快捷键目录
RELEASE_RUNBOOK.md	发布流程
OPERATIONS_RUNBOOK.md	运维和恢复

完整更新历史：CHANGELOG.md。

---

致谢

此前版本得到以下贡献者的帮助：

• Hafeez Pizofreude — fetch_url 的 SSRF 保护和 Star History 图表
• Unic (YuniqueUnic) — 基于 schema 的配置 UI（TUI + web）
• Jason — SSRF 安全加固

---

贡献

欢迎提交 pull request——请先查看 CONTRIBUTING.md 并留意开放 issue 中的好入门任务。

本项目与 DeepSeek Inc. 无隶属关系。

许可证

MIT

Star 历史