接入 DeepSeek-TUI

DeepSeek-TUI 是一款采用 Rust 编写的高性能开源终端 AI 编程助手，采用 Codex 风格的 13-crate 工作区架构，性能优异、资源占用极低，启动速度远超 Node.js 实现的同类工具。其原生对接 api.deepseek.com，无需额外协议适配即可完全发挥 DeepSeek-V4 系列模型的全部特性，支持全 100 万 token 上下文，并在 macOS（Seatbelt 沙箱）、Linux（Landlock 沙箱）和 Windows 上提供沙箱化的工具执行能力，工具运行在隔离沙箱中，不会对系统造成修改，安全性极高。同时支持 MCP 对接、自定义技能、子 Agent 调度、HTTP API 暴露等高级特性，是追求性能、安全、原生体验的开发者的首选终端AI工具。

本教程将指导你完成 DeepSeek-TUI 的安装与全功能配置，阅读完成后你将能够使用 DeepSeek 模型驱动的高性能终端编程助手，享受沙箱安全执行、高级Agent特性带来的效率提升。

• GitHub： https://github.com/Hmbown/DeepSeek-TUI

1. 安装 DeepSeek-TUI

操作目的：安装 DeepSeek-TUI 命令行工具，实现系统任意路径下的快速调用。你可以根据自己的环境与需求选择以下任意一种安装方式：

# npm（跨平台预编译二进制）
npm install -g deepseek-tui

适用场景：适合所有用户，无需 Rust 环境，直接下载预编译的二进制文件，安装速度快。国内用户可追加淘宝镜像参数：npm install -g deepseek-tui --registry=https://registry.npmmirror.com

# Cargo（从源码构建，需要 Rust 1.85+）
cargo install deepseek-tui-cli

适用场景：适合 Rust 开发者或想要体验最新开发版功能的用户，需要 Rust 1.85+ 编译环境。国内用户建议配置 crates.io 镜像提升依赖下载速度。

# 或从 GitHub Releases 下载预编译二进制：
#   https://github.com/Hmbown/DeepSeek-TUI/releases

适用场景：适合无法使用 npm 或 Cargo 的环境，下载对应平台的二进制文件后，添加到系统 PATH 目录即可使用。

前置环境说明：

• 若使用 Cargo 安装，需 Rust 1.85+ 版本，执行 rustc --version 确认版本符合要求，低版本会导致编译失败。可通过 rustup 安装最新版本的 Rust。
• 编译依赖：Linux 系统需提前安装 libssl-dev、pkg-config 等依赖；macOS 需安装 Xcode 命令行工具（执行 xcode-select --install）；Windows 需安装 Visual Studio 生成工具。

验证安装：

deepseek --version

预期结果：执行命令后正常输出版本号（如 v0.10.0）即表示安装成功。

2. 获取 DeepSeek API Key

操作目的：配置 DeepSeek API 身份凭证，支持交互式配置与环境变量两种方式，满足不同场景需求。

在 DeepSeek 开放平台 获取 API Key。首次运行时 deepseek auth 会引导你保存到 ~/.deepseek/config.toml，也可直接设置环境变量 DEEPSEEK_API_KEY。

配置说明：deepseek auth 为交互式配置命令，适合新手用户，按照提示输入 API Key 即可自动写入配置文件，无需手动编辑；环境变量方式适合自动化部署、容器运行等场景，优先级高于配置文件中的值。 安全提示：API Key 请勿泄露，不要将配置文件提交到公开代码仓库，避免被盗用产生费用。

3. 进入项目目录并启动

操作目的：进入目标项目目录，DeepSeek-TUI 会自动扫描项目代码、Git 记录、.deepseek 目录下的配置与技能，实现项目级上下文感知。

cd /path/to/my-project
deepseek

deepseek 是规范的入口命令。默认进入交互式 TUI，也可调用子命令，如 deepseek doctor（环境诊断）、deepseek mcp list（列出已安装的 MCP 服务器）、deepseek serve --http（启动 HTTP API 服务）、deepseek -p "一次性 prompt"（执行一次性命令）、deepseek --yolo（直接以 YOLO 模式启动）等。

DeepSeek-TUI 默认使用 DeepSeek-V4-Pro。按 Shift+Tab 切换推理强度（off → high → max）。按 Tab 切换模式：

推理强度说明：off 关闭推理，响应速度最快，适合简单问题；high 高推理强度，平衡速度与准确率，适合大多数日常编码场景；max 最高推理强度，推理最充分，适合复杂问题排查、架构设计等场景，响应时间最长。 测试方法：启动后输入测试指令（如「帮我分析当前项目的依赖情况，列出存在安全漏洞的依赖包」），若能正常返回结果且无报错，即表示配置成功。

快捷键

DeepSeek-TUI 提供了丰富的快捷键提升操作效率，各按键功能说明如下：

配置

~/.deepseek/config.toml 是主配置文件（仓库中的 config.example.toml 列出了全部可用项），你可以根据需求修改配置。常用环境变量如下，环境变量优先级高于配置文件，适合临时调整参数或自动化场景：

配置修改后无需重启程序，DeepSeek-TUI 会自动检测配置文件变化并生效。

MCP、Skills 与 Hooks

DeepSeek-TUI 提供了丰富的扩展能力，支持自定义功能与工作流集成：

• MCP 服务器 —— 在 ~/.deepseek/mcp.json 中配置，或使用 deepseek mcp add ... 命令快速添加。DeepSeek-TUI 同时是 MCP 客户端与 MCP 服务器（deepseek mcp serve）。你可以添加第三方 MCP 服务器扩展能力，如浏览器控制、数据库操作、云服务管理等，实现更多场景的自动化。
• Skills —— 将 SKILL.md 放入 ~/.deepseek/skills/<name>/（用户级，全局可用）或 ./.deepseek/skills/<name>/（项目级，仅当前项目可用）。与其他工具的技能类似，你可以将高频任务封装为技能，避免重复输入提示词，提升效率。
• Hooks —— 在 config.toml 的 [hooks] 中配置生命周期钩子（stdout / jsonl / webhook），可在任务开始、模型回复完成、任务结束等节点触发自定义脚本，实现通知、数据上报、CI/CD 触发等功能。
• 子 Agent —— 模型可以通过 agent_spawn 派生子 Agent，并使用完整的生命周期工具族（agent_wait、agent_result、agent_cancel 等）。适合大型复杂任务的拆解处理，父 Agent 负责整体调度，子 Agent 负责具体子任务的执行，大幅提升复杂项目的处理效率。
• RLM —— 内置递归 LM 工具，在沙箱化的 Python REPL 中处理超大输入，不会污染父级上下文。适合处理超大规模的日志、代码库、文档等超过单轮上下文窗口的输入。

HTTP 运行时 API

deepseek serve --http 暴露 /v1/* 运行时 API，便于将 DeepSeek-TUI 嵌入 IDE 与 Web UI（sessions、threads、turns、tasks、automations、MCP、skills）。该 API 兼容 OpenAI 格式，你可以将其作为后端接入 VSCode、JetBrains IDE、自定义 Web 界面等工具，共享 DeepSeek-TUI 的沙箱、技能、MCP 等能力，无需在每个工具中单独配置 DeepSeek。

完整接口契约见 docs/RUNTIME_API.md。

注意事项与避坑指南

1. 沙箱权限问题：默认沙箱仅允许访问当前工作区目录下的文件，若需要访问其他目录，可切换到 YOLO 模式解除限制；部分老旧系统不支持沙箱特性，DeepSeek-TUI 会自动降级到无沙箱模式，不影响基本功能使用，但会失去安全隔离能力。
2. 网络访问超时：国内用户建议将 DEEPSEEK_BASE_URL 设置为中国区端点 https://api.deepseeki.com，大幅降低网络延迟。
3. 子 Agent 配额消耗：子 Agent 功能会为每个子任务创建独立的上下文，会消耗更多的 token，使用时注意监控配额使用情况。
4. HTTP API 安全：deepseek serve --http 默认监听 127.0.0.1:8080，请勿暴露到公网，避免未授权访问；若需要公网访问，请配置身份认证与访问控制。

常见问题（FAQ）

1. 启动后提示沙箱初始化失败怎么办？

   • 排查步骤：确认系统版本满足要求：macOS ≥ 10.15，Linux ≥ Kernel 5.13，Windows ≥ 10；若系统不支持沙箱，DeepSeek-TUI 会自动降级到无沙箱模式，不影响基本功能使用。

2. MCP 服务器不生效怎么办？

   • 排查步骤：执行 deepseek mcp list 查看已安装的 MCP 服务器列表，确认配置的 MCP 存在且状态正常；检查 mcp.json 配置格式是否正确，无语法错误。

3. HTTP API 无法访问怎么办？

   • 排查步骤：确认端口未被占用，可通过 --port 参数指定其他端口（如 deepseek serve --http --port 8081）；检查防火墙是否允许访问对应端口，默认仅允许本地访问。

4. 对话历史丢失怎么办？

   • 对话历史自动保存在 ~/.deepseek/history 目录下，通过 /resume 命令即可恢复任意历史对话；你也可以手动备份该目录下的文件实现历史迁移。

参考资料

• awesome-deepseek-agent：可查看更多 DeepSeek 生态的 Agent 工具与最佳实践。