DeepSeek-TUI

DeepSeek TUI

一个以终端为本的编码助手，构建于 DeepSeek V4 的 100 万 token 上下文和前缀缓存之上。单个二进制文件，无需 Node/Python 运行时——开箱即提供 MCP 客户端、沙箱和持久化任务队列。

英文 README

npm i -g deepseek-tui

---

这是什么？

DeepSeek TUI 是一个完全运行在终端中的编码助手。它赋予 DeepSeek 前沿模型直接访问你工作区的权限——读取和编辑文件、运行 shell 命令、搜索网络、管理 git、编排子代理——全部通过一个快速、键盘驱动的 TUI 完成。

专为 DeepSeek V4（deepseek-v4-pro / deepseek-v4-flash）打造，支持 100 万 token 上下文窗口和原生思维模式（chain-of-thought，思维链）流式输出。在处理任务时，实时观察模型的推理过程。

核心特性

• 原生 RLM（rlm_query 工具）—— 并行派发 1–16 个廉价的 deepseek-v4-flash 子模型，利用现有 DeepSeek 客户端进行批量分析、分解或并行推理
• 思维模式流式输出 —— 显示 DeepSeek 在推理你代码时的思维链
• 完整工具套件 —— 文件操作、shell 执行、git、网络搜索/浏览、应用补丁、子代理、MCP 服务器
• 100 万 token 上下文 —— 上下文填满时自动智能压缩
• 三种交互模式 —— Plan（只读探索）、Agent（交互式且需审批）、YOLO（自动审批）。基于分解优先的系统提示，引导模型在行动前执行 checklist_write、update_plan 和生成子代理
• 推理强度等级 —— 通过 Shift+Tab 在 off → high → max 之间循环
• 会话保存/恢复 —— 对长时间会话设置检查点并恢复
• 工作区回滚 —— 侧置 git 在每个轮次前后生成快照，通过 /restore 和 revert_turn 回滚，不影响仓库的 .git
• HTTP/SSE 运行时 API —— deepseek serve --http 用于无头代理工作流
• MCP 协议 —— 连接 Model Context Protocol 服务器以扩展工具能力；详见 docs/MCP.md
• 实时成本追踪 —— 逐轮和会话级别的 token 使用量及费用估算
• 深色主题 —— DeepSeek 蓝色调色板

---

架构概览

DeepSeek TUI 的架构遵循 dispatcher（调度器）→ TUI → engine（引擎）→ tools（工具） 模式。 deepseek CLI 二进制文件是一个轻量级调度器，负责解析子命令并将交互式会话委托给 deepseek-tui 配套二进制文件。TUI 运行一个基于 ratatui 的界面，与执行代理循环的异步引擎通信：用户输入通过流式客户端（兼容 OpenAI Chat Completions）流向 LLM，从响应中提取工具调用并通过类型化的工具注册表（shell、文件操作、git、网络、子代理、MCP）进行分派，结果流式返回并写入对话记录。

在幕后，引擎管理会话状态、轮次追踪和一个持久化任务队列。LSP 子系统（crates/tui/src/lsp/）通过生成语言服务器（rust-analyzer、pyright 等）并在下一推理步骤之前将错误注入模型上下文，提供编辑后诊断。递归语言模型（RLM）子系统为代理提供了一个沙箱化的 Python REPL，用于批量分类和子 LLM 编排。详见 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 指南。

Linux ARM64（Raspberry Pi、Asahi、Graviton、鸿蒙 PC）

从 v0.8.8 开始，npm i -g deepseek-tui 可在基于 glibc 的 ARM64 Linux 上工作。如果你仍在使用 v0.8.7 或更早版本（会出现 Unsupported architecture: arm64 错误），请升级或使用 cargo install：

# 需要 Rust 1.85+ (https://rustup.rs)
cargo install deepseek-tui-cli --locked   # 提供 `deepseek`
cargo install deepseek-tui     --locked   # 提供 `deepseek-tui`

你也可以直接从 Releases 页面 下载 deepseek-linux-arm64 和 deepseek-tui-linux-arm64，然后将两者并排放置在 PATH 中的某个目录中。从 x64 交叉编译到 ARM64 的方法已在 docs/INSTALL.md 中记录。

中国 / 镜像友好安装

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

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

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

然后安装标准的 deepseek 调度器和配套的 TUI 二进制文件（两者都需要——调度器将工作委托给 TUI 运行时）：

cargo install deepseek-tui-cli --locked   # 提供 `deepseek`
cargo install deepseek-tui     --locked   # 提供 `deepseek-tui`
deepseek --version

当 GitHub 发布资产可访问时，你也可以直接从 GitHub Releases 页面下载预构建的二进制文件。当存在镜像发布资产目录时，TUNA、rsproxy、腾讯 COS 或阿里云 OSS 镜像也可以在 DEEPSEEK_TUI_RELEASE_BASE_URL 下使用。

首次启动时，系统会提示你输入 DeepSeek API 密钥。TUI 会将其保存到你的用户配置文件 ~/.deepseek/config.toml 中，这样无论在哪个文件夹中都能使用，无需操作系统凭据提示。

你也可以提前设置：

# 推荐——保存到 ~/.deepseek/config.toml；在任何地方都有效
# （交互式 shell、IDE 终端、脚本、cron）：
deepseek auth set --provider deepseek

# 环境变量替代方案——注意在 zsh 中，~/.zshrc 中的 export 只影响交互式 shell。
# 如果你想在所有上下文（登录 shell、IDE、脚本）中都生效，请将其放入 ~/.zshenv：
export DEEPSEEK_API_KEY="你的 DEEPSEEK API 密钥"
deepseek

# 验证二进制文件正在读取哪个源：
deepseek doctor

要轮换或删除已保存的密钥，请运行 deepseek auth clear --provider deepseek（或使用旧别名 deepseek logout）， 然后再次运行 deepseek auth set --provider deepseek。

使用 NVIDIA NIM

deepseek auth set --provider nvidia-nim --api-key "你的 NVIDIA API 密钥"
deepseek --provider nvidia-nim

# 或进程级别：
DEEPSEEK_PROVIDER=nvidia-nim NVIDIA_API_KEY="..." deepseek

其他 DeepSeek V4 提供商

deepseek auth set --provider fireworks --api-key "你的 FIREWORKS API 密钥"
deepseek --provider fireworks --model deepseek-v4-pro

# SGLang 是自托管的；本地部署时认证为可选。
SGLANG_BASE_URL="http://localhost:30000/v1" deepseek --provider sglang --model deepseek-v4-flash

从源码构建

适用于任何 Tier-1 Rust 目标——包括 Linux musl/riscv64、FreeBSD，以及早于我们预构建二进制文件的 ARM64 发行版。

# Linux 构建依赖（Debian/Ubuntu/openEuler/Kylin）：
#   sudo apt-get install -y build-essential pkg-config libdbus-1-dev
#   # RHEL 系列：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`

两个二进制文件都是必需的——deepseek 调度器在运行时委托给 deepseek-tui。交叉编译、镜像和平台特定说明详见 docs/INSTALL.md。

---

v0.8.8 更新内容

一个专注于稳定性的版本：在 v0.8.6 / v0.8.7 基础之上进行了大量 UX 优化，并修复了生产会话中暴露的一些粗糙边缘。没有模型或 API 更改；所有现有配置和会话都保持正常工作。

🪟 TUI 优化

• 视觉重试 / 退避横幅 当上游限流或返回 5xx 时显示，带有每秒倒计时，使卡住的会话明显可见而非无声冻结（#499）。
• MCP 健康状态芯片 在页脚中——一个带颜色的 MCP n/n 字样反映了有多少已配置的服务器实际可达，当未配置服务器时隐藏（#502）。
• 工具输出溢出 将完整内容路由到 ~/.deepseek/tool_outputs/<id>.txt，单元格中可见前 32 KiB 的内容；现有的详情分页器追加完整输出，因此不会隐藏任何内容，只是分页（#500）。
• 多日时间段格式化 —— humanize_duration 按 s → m → h → d → w 递增，最多显示两个单位，因此长时间运行的会话显示为 2d 3h 而不是 188415s（#447）。
• 累积 已工作 Nh Mm 页脚芯片 当会话超过 60 秒时出现，在窄宽度下优先丢弃，以免将更重要的芯片挤出屏幕（#448）。
• OSC 8 超链接 —— 对话记录中的 URL 可在 iTerm2、Terminal.app、Ghostty、Kitty、WezTerm、Alacritty 以及现代 gnome-terminal/konsole 中通过 Cmd+点击打开；传统终端仅显示可见文本（#498）。
• 行内差异渲染 针对 edit_file 和 write_file —— 工具结果在正文开头输出统一差异格式，由差异感知渲染器处理，显示行号和带颜色的 +/- 边栏（#505）。
• Composer 草稿暂存 —— Ctrl+S 将当前草稿保存到 ~/.deepseek/composer_stash.jsonl，/stash list 显示暂存草稿，/stash pop 按后进先出恢复，/stash clear 清空文件。自我修复的 JSONL 解析器，200 条上限，多行草稿可保留（#440）。
• 斜杠菜单布局不再抖动 聊天区域不再因输入过程中匹配条目数量变化而闪烁——在 Windows 10 PowerShell + WSL 上报告过，由于每个单元格的写入开销使重绘明显滞后。Composer 现在在整个斜杠/提及会话期间保留其面板最大边框。

♿ 无障碍

• NO_ANIMATIONS=1 环境变量（也可使用 1 / true / yes / on）强制在启动时启用 low_motion = true 和 fancy_animations = false，无论保存的设置如何；新的 docs/ACCESSIBILITY.md 文档记录了所有运动/输出旋钮（#450）。
• 键盘增强标志 在所有关闭路径上弹出，包括 panic、Ctrl+Z 挂起和外部编辑器调用，因此崩溃的 TUI 永远不会将终端置于原始模式（#443/#444）。
• Kitty 键盘协议（DISAMBIGUATE_ESCAPE_CODES）在启动时推送，以便 kitty 协议终端报告 Option/Alt 修饰键的明确事件；传统终端不受影响（#442）。

🤖 代理 / 子代理

• 子代理上限从 5 提高到 10（可通过 [subagents].max_concurrent 配置，硬上限 20）。已完成的代理不再计入运行中上限（#509）。
• 多代理扇出 UI 冻结修复 —— SharedSubAgentManager 现在使用 Arc<RwLock<…>>；读取路径获取读锁，而不是在 Mutex 上争用（#510）。
• 子代理输出汇总 然后才合并到父上下文，因此子节点返回 100KB 证据不会破坏父窗口（#511）。
• Implementer + Verifier 子代理角色 已接入 agent_spawn / agent_assign 模式，因此模型可按名称引用它们（#404）。
• agent_list 默认显示当前会话视图 —— 除非 include_archived=true，否则过滤掉先前会话（#405）。
• 紧凑的 agent_spawn 渲染 在实时模式下折叠为单头行；对话回放保留完整块（#409）。
• agent_swarm / spawn_agents_on_csv / /swarm 已在 v0.8.5 中移除——确认在此版本中不再存在；多子扇出不再是模型可调用的工具。

🛠️ 工作流 / 可扩展性

• load_skill 模型可调用工具 —— 接收 skill id，在一个调用中返回 SKILL.md 正文及同级配套文件列表。可在 Plan 和 Agent / Yolo 模式下使用（#434）。
• 跨工具技能发现 —— skills 目录和 load_skill 会遍历 .agents/skills、skills、.opencode/skills、.claude/skills 和 ~/.deepseek/skills，按首次命中优先级（#432）。
• /hooks 只读生命周期钩子列表 按事件分组显示已配置的钩子，包含名称/命令预览/超时/条件。注明全局 [hooks].enabled 状态。/hooks events 列出所有支持的 HookEvent 值（#460）。
• 每个 HookEvent 现在都有实时生产者 —— tool_call_before / tool_call_after / message_submit / on_error 在运行时触发，除了现有的会话生命周期和模式变化事件。在 v0.8.8 中钩子仍为只读观察者（#455）。
• instructions = [...] 配置数组 允许你叠加额外的系统提示文件；每个文件路径上限 100 KiB，项目数组完全替换用户数组（#454）。
• deepseek pr <N> 子命令 通过 gh 获取 PR 的标题/正文/差异，并以审查提示启动 TUI 并预填入 composer。代码点安全的差异上限为 200 KiB；可选的 --repo / --checkout（#451）。
• 用户记忆 MVP（可选）—— ~/.deepseek/memory.md 作为 <user_memory> 块注入系统提示；在 composer 中键入 # foo 会追加带时间戳的要点而不触发轮次；/memory [show|path|clear|edit] 供检查。默认关闭；通过 [memory] enabled = true 或 DEEPSEEK_MEMORY=on 启用（#489–#493）。

🔒 安全性

• 项目配置密钥在工作区范围被拒绝 —— 恶意的 ./.deepseek/config.toml 不再能覆盖 api_key、base_url、provider 或 mcp_config_path。最宽松的值（approval_policy = "auto"、sandbox_mode = "danger-full-access"）也在项目范围被拒绝（#417）。
• SSL_CERT_FILE 被尊重 在 HTTPS 客户端中，因此企业 CA / MITM 代理用户可以连接——支持 PEM 包和 DER 回退；失败时记录警告并继续（#418）。
• Execpolicy heredoc 解析 —— normalize_command 在 shlex 分词前剥离 heredoc 主体，因此 auto_allow = ["cat > file.txt"] 能匹配 heredoc 形式 cat <<EOF > file.txt\nbody\nEOF。识别 <<DELIM / <<-DELIM / <<'DELIM' / <<"DELIM"；保留 <<<（here-string）不变（#419）。
• 不要自动批准 git -C ... 运行时修复已在 v0.8.7 主分支上发布（#416）——此处包含以保持完整性。

📦 打包

• Linux ARM64 预构建 已添加到发布矩阵；npm 包装器在 aarch64-linux 上自动选择正确的二进制文件。新的 docs/INSTALL.md 涵盖所有安装路径（npm、cargo、预构建、源码）。
• deepseek update 已修复 —— v0.8.7 的自更新器使用了 Rust ARCH 常量（aarch64/x86_64）而非发布资产命名（arm64/x64），导致该命令在所有平台上失败。现已正确映射，并拒绝将 .sha256 兄弟文件作为主二进制文件（#503）。
• CI 工作流清理 —— 修剪了三个重复/死亡的工作流；release.yml build 任务现在允许在手动 workflow_dispatch 时跳过 parity 门控（#507）。

🐛 Bug 修复

• Composer Option+Backspace 现在按词删除（#488）。
• 离线 composer 队列为会话限定范围 —— 旧的无范围队列在失败时关闭，而不是将内容泄漏到无关聊天中（#487）。
• display_path 测试竞态 + Windows 分隔符 —— 测试不再修改 $HOME；home 相对后缀与 MAIN_SEPARATOR_STR 连接，因此 Windows 显示 ~\projects\foo（#506）。
• 页脚从 app.ui_theme 读取状态行颜色（#449）。

🔑 认证与入门

• 无自动操作系统凭据提示 —— 启动、doctor、doctor --json 和普通调度器设置现在使用 CLI 标志 → ~/.deepseek/config.toml → 环境变量。
• 一个设置命令随处可用 —— deepseek auth set --provider deepseek 和 TUI 内入门屏幕都写入共享的用户配置文件，因此密钥可从任何文件夹使用，无需依赖 ~/.zshrc 传播。
• 入门屏幕措辞重写 —— "步骤 1：打开 https://platform.deepseek.com/api_keys" / "步骤 2：粘贴到下方并按 Enter"，并附有显式说明显示密钥保存位置。
• 缺少密钥的错误现在可操作 —— DeepSeek API key not found 退出消息首先列出基于配置的 CLI 命令，然后列出环境变量替代方案，并附带 ~/.zshrc vs ~/.zshenv 说明，因为 zsh 用户的环境变量仅影响交互式 shell。
• 调度器提供商/认证一致性 —— 标准 deepseek 入口点现在接受 TUI 广告的相同 DeepSeek V4 提供商（包括 fireworks、sglang），并且旧的 deepseek login --api-key / deepseek logout 现在共享相同的基于配置的路径。

完整变更日志：CHANGELOG.md。

---

v0.8.7 更新内容

基于 v0.8.6 的快速补丁，以解除复制/选择的阻塞。

✂️ 选择功能现在覆盖整个对话记录

v0.8.6 中引入的选择收紧将复制/选择限制在用户和助手消息正文，导致无法复制系统笔记、思维块或工具输出中的文本。v0.8.7 移除了该限制，因此渲染的对话记录块再次可从头到尾选择。

v0.8.7 已知问题（已在 v0.8.8 中修复）：

• deepseek update 失败，提示 no asset found for platform …，因为自更新器中的平台字符串映射使用了 aarch64/x86_64 而非发布工件的 arm64/x64 （#503）。
• npm i -g deepseek-tui 在 ARM64 Linux 上退出并提示 Unsupported architecture: arm64 on platform linux，因为 v0.8.7 未发布 deepseek-linux-arm64 资产。

在 v0.8.8 发布之前，请通过以下方式安装：

# x64 Linux / macOS / Windows
npm i -g deepseek-tui

# ARM64 Linux（鸿蒙、openEuler、Asahi、Raspberry Pi、Graviton 等）——
# 使用 Cargo 从源码构建（Rust 1.85+）：
cargo install deepseek-tui-cli --locked   # 提供 `deepseek`
cargo install deepseek-tui     --locked   # 提供 `deepseek-tui`

完整变更日志：CHANGELOG.md。

v0.8.6 更新内容

📝 AGENTS.md 引导（/init）

/init 遍历工作区，自动检测项目类型（Cargo.toml、package.json、pyproject.toml 等），并写入一个初始的 AGENTS.md，包含构建/测试命令、工作区布局以及从 git log 推断的约定。重新运行会显示建议更新的差异，同时不覆盖已有更改。

🔍 行内 LSP 诊断

每次 apply_patch/edit_file/write_file 之后，引擎向 LSP 服务器发送 textDocument/didChange，并将错误/警告显示在工具结果中。可通过 /lsp on|off 和 [lsp] 配置节进行配置。目前支持 rust-analyzer、pyright、typescript-language-server、gopls 和 clangd。

🔄 自更新（deepseek update）

deepseek update 获取最新的 GitHub 发布版，下载平台正确的二进制文件并经过 SHA256 验证，然后原子替换正在运行的二进制文件。无需再记住 cargo install 或 npm install -g。

🌐 会话共享（/share）

/share 将当前会话导出为静态 HTML 页面，并通过 gh CLI 上传到 GitHub Gist，生成一个可点击的 URL，你可以粘贴到任意位置。

📖 文档刷新

README 英雄区更新了意图声明和架构总结。ARCHITECTURE.md 针对 v0.8.6 进行了清理（移除了 swarm 工具表面，更新了 crate 映射）。CONTRIBUTING.md 现在包含"PR 形态"一节。

完整变更日志：CHANGELOG.md。

---

v0.8.5 更新内容

🛡️ fetch_url 的 SSRF 保护

fetch_url 现在在连接前验证目标主机名和 IP —— 对回环地址仅允许 localhost 的 HTTP，对远程主机进行 DNS 固定，并拦截内部 IP 范围。由 Hafeez Pizofreude（#261）和 Jason 贡献。

🖥️ 模式驱动配置编辑器

/config tui 打开一个由 schemaui 驱动的表单风格配置编辑器。仅 /config 打开旧的原生模态框；/config web 启动浏览器界面（需要 web 特性）。由 Unic（YuniqueUnic）通过 #365 贡献。

🏷️ DeepseekCN 提供商

ApiProvider::DeepseekCN 针对中国用户使用 api.deepseeki.com。首次运行时当系统区域设置为 zh-* 时自动检测。

🔐 原子文件写入

所有写入 ~/.deepseek/ 的操作现在都通过 write_atomic（临时文件 + fsync + 重命名）进行，防止写入中途崩溃导致的数据损坏。

🧵 Panic 安全基础

spawn_supervised 捕获并记录任务 panic 并附带崩溃转储，而不是静默丢弃任务。

⌨️ /config <key> <value> 绑定

/config model deepseek-v4-flash、/config locale zh-Hans 等命令可在会话中实时更改设置，无需打开编辑器。

完整变更日志：CHANGELOG.md。

---

感谢

v0.8.5 在以下贡献者的帮助下发布：

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

---

v0.8.0 更新内容

⚡ Shell 稳定性和发送后响应性

已完成后台 shell 任务在观测到完成时会立即释放其活动进程和管道句柄，同时保持作业记录可供检查。这防止了长时间运行的会话达到 Too many open files (os error 24)，该错误曾导致检查点保存失败，并使 shell 生成、消息发送、关闭和 Esc/取消路径出现延迟或失败。

🪟 Windows REPL 运行时 CI 加固

Windows 为 REPL 运行时测试设置了更长的 Python 引导就绪超时，以匹配 GitHub 运行器启动时的争用，同时不削弱其他平台的引导失败检测。

🌏 Cargo 镜像安装文档

README 现在包含 TUNA Cargo 镜像设置和直接发布资产指南，适用于 GitHub/npm 访问缓慢的用户。

🧪 测试加固

新的回归覆盖率证明，已完成后台 shell 作业在 exec_shell_wait 后会放弃其活动进程句柄。

完整变更日志：CHANGELOG.md。

---

v0.7.8 更新内容

⚡ Shell 控制：前台到后台分离 + exec_shell_cancel

现在可以将正在运行的前台命令移至后台交互式会话——在命令执行时按下 Ctrl+B 可打开 shell 控制，然后可以分离它（它继续运行，并可通过 exec_shell_wait 查询）或取消当前轮次。

新工具：exec_shell_cancel —— 按 task_id 取消特定的后台 shell 任务，或使用 all: true 取消所有正在运行的后台任务。

支持取消的 exec_shell_wait —— 当 exec_shell_wait 阻塞时取消轮次，会停止等待但保留后台任务继续运行。

🐛 Unicode glob 搜索修复

包含多字节字符的文件名（例如 dialogue_line__冰糖.mp3）不再使 matches_glob 函数 panic——字节索引切片已替换为基于 char_indices() 的边界安全迭代。

🔄 扇出 UI 协调

扇出卡不再预填充零状态的工作器，消除了"0 完成 · 0 运行中 · 0 失败 · N 等待"与侧边栏"N 运行中"之间的矛盾。侧边栏现在在来自旧式扇出调用的第一个进度事件到达前显示"正在调度 N"。

完整变更日志：CHANGELOG.md。

---

v0.7.6 更新内容

🌐 UI 本地化

DeepSeek TUI 现在支持你的语言。新的 locale 设置位于 settings.toml 中，控制 UI 界面——composer、历史搜索、/config、帮助覆盖层和状态提示——而不影响模型输出语言。

设置	显示
locale = \"auto\"	检查 LC_ALL → LC_MESSAGES → LANG（默认）
locale = \"ja\"	日语
locale = \"zh-Hans\"	简体中文
locale = \"pt-BR\"	葡萄牙语（巴西）
locale = \"en\"	英语回退