DeepSeek TUI (CodeWhale) 使用指南

版本：基于 codewhale v0.8.50 | 更新日期：2026-06-04

---

目录

1. 什么是 DeepSeek TUI
2. 安装与启动
3. 界面概览
4. 斜杠命令参考
5. 键盘快捷键
6. 工作模式
7. 对话管理
8. 配置管理
9. 上下文管理
10. 实用技巧
11. 常见问题

---

1. 什么是 DeepSeek TUI

DeepSeek TUI（终端用户界面）即 CodeWhale，是一个基于终端的 DeepSeek 大模型交互工具。它运行在命令行中，支持多行输入、对话管理、文件操作、代码执行等高级功能，是开发者与 DeepSeek 模型交互的主要方式。

核心特性

• 多模型支持：deepseek-v4-pro、deepseek-v4-flash 等
• Agent 模式：自主执行任务，可读写文件、运行命令
• 对话持久化：自动保存会话历史，支持导入导出
• 上下文管理：支持 compaction（压缩）以扩展对话长度
• 文件感知：自动加载工作区文件到上下文中
• 子代理系统：可并行启动多个子代理处理任务

---

2. 安装与启动

安装

# 通过 npm 安装（推荐）
npm install -g @deepseek/codewhale

# 或通过 cargo 安装
cargo install codewhale

启动

# 进入工作目录后启动
cd /path/to/your/project
codewhale

# 或指定工作目录
codewhale --workspace /path/to/project

# 使用 TUI 模式
codewhale-tui

认证

首次使用需要配置 API 密钥：

codewhale auth login

按照提示输入 DeepSeek API Key 完成认证。

---

3. 界面概览

TUI 界面分为以下几个区域：

┌─────────────────────────────────────────────────────┐
│  DeepSeek TUI (CodeWhale) v0.8.50                   │  ← 标题栏
├─────────────────────────────────────────────────────┤
│                                                     │
│  [User] 你的问题...                                  │  ← 对话区域
│                                                     │
│  [Assistant] 模型回复...                             │
│                                                     │
├─────────────────────────────────────────────────────┤
│  模式: Agent │ 模型: deepseek-v4-pro │ 上下文: 25K  │  ← 状态栏
├─────────────────────────────────────────────────────┤
│  > _                                                 │  ← 输入区域
└─────────────────────────────────────────────────────┘

状态栏信息

项目	说明
模式	当前工作模式（Agent / Plan / YOLO）
模型	当前使用的 DeepSeek 模型
上下文	已使用的 token 数 / 总上限
缓存命中率	提示词前缀缓存命中率（红色 < 40%，黄色 < 80%）

---

4. 斜杠命令参考

在输入框中以 / 开头输入以下命令：

4.1 对话控制

命令	说明	示例
/help	显示帮助信息	/help
/clear	清除当前对话	/clear
/compact 或 Ctrl+L	压缩对话历史以释放上下文	/compact
/reset	重置整个会话	/reset

4.2 模式切换

命令	说明	示例
/agent	切换到 Agent 模式（自主执行）	/agent
/plan	切换到 Plan 模式（仅规划）	/plan
/yolo	切换到 YOLO 模式（自动批准）	/yolo

4.3 模型与配置

命令	说明	示例
/model	切换模型	/model deepseek-v4-pro
/config	查看或修改配置	/config
/thinking	切换思考模式（显示推理过程）	/thinking on
/web	切换网络搜索	/web on

4.4 文件操作

命令	说明	示例
/file	添加文件到对话上下文	/file src/main.rs
/workspace	查看或切换工作区	/workspace
/editor	打开外部编辑器编写输入	/editor

4.5 会话管理

命令	说明	示例
/save	保存当前对话	/save my-session
/load	加载已保存的对话	/load my-session
/export	导出对话为 Markdown	/export conversation.md
/history	查看对话历史列表	/history
/search	搜索对话历史	/search keyword

4.6 实用工具

命令	说明	示例
/token	显示当前 token 用量详情	/token
/copy	复制最后一条回复	/copy
/status	显示会话状态	/status
/auth	查看认证状态	/auth status
/doctor	诊断环境问题	/doctor
/multiline	切换多行输入模式	/multiline
/paste	粘贴剪贴板内容	/paste
/cost	显示当前会话的 API 费用估算	/cost

---

5. 键盘快捷键

5.1 全局快捷键

快捷键	说明
Ctrl + C	中断当前模型回复生成
Ctrl + D	退出 TUI
Ctrl + L	清屏 / 触发对话压缩
Ctrl + R	搜索对话历史
Ctrl + S	暂停/恢复输出流
Ctrl + Z	挂起进程（Unix）

5.2 输入操作

快捷键	说明
Enter	发送消息
Shift + Enter	插入换行符（单行模式下）
Alt + Enter	发送但不记录到历史
Ctrl + Enter	强制发送（多行模式下）
Tab	自动补全（命令 / 文件路径）
Esc	取消当前输入 / 退出模式

5.3 导航

快捷键	说明
↑ / ↓	浏览历史输入
Ctrl + P / Ctrl + N	上一条 / 下一条历史
Page Up / Page Down	向上 / 向下翻页
Home / End	跳转到对话开头 / 末尾

5.4 文本编辑（输入框内）

快捷键	说明
Ctrl + A	跳到行首
Ctrl + E	跳到行尾
Ctrl + K	删除从光标到行尾的内容
Ctrl + U	删除整行
Ctrl + W	删除前一个单词
Alt + ← / Alt + →	按单词移动光标
Ctrl + ← / Ctrl + →	按单词移动光标（Windows）

5.5 Vim 模式（如果启用）

快捷键	说明
j / k	向下 / 向上滚动对话
Esc	进入 Normal 模式
i / a	进入输入模式
gg	跳到对话开头
G	跳到对话末尾
/pattern	搜索模式

---

6. 工作模式

DeepSeek TUI 提供三种工作模式，适用于不同场景：

6.1 Agent 模式（默认）

最常用的模式。模型可以自主使用工具完成任务：

• 读写文件
• 执行命令（需批准）
• 搜索代码
• 生成和修改代码
• 并行启动子代理

适用场景：日常开发、代码修改、调试、项目重构等。

批准策略：读操作自动执行，写操作需用户批准。

6.2 Plan 模式

模型仅进行规划和设计，不执行实际操作：

• 分析需求
• 制定计划
• 输出结构化方案
• 不会修改任何文件

适用场景：需求分析、架构设计、代码审查、学习理解代码库。

6.3 YOLO 模式

完全自主模式，所有操作自动批准：

• 无需人工确认
• 自动执行写入和命令
• 适合完全信任的自动化场景

⚠️ 警告：YOLO 模式会跳过所有确认步骤，请仅在完全受控的环境中使用。

切换模式

# 方式一：斜杠命令
/agent
/plan
/yolo

# 方式二：启动参数
codewhale --mode agent
codewhale --mode plan
codewhale --mode yolo

---

7. 对话管理

7.1 保存和加载对话

# 保存当前对话
/save 我的项目讨论

# 加载已保存的对话
/load 我的项目讨论

# 查看所有已保存的对话
/history

7.2 导出对话

# 导出为 Markdown
/export ./docs/conversation-2026-06-04.md

# 导出为 JSON（包含完整元数据）
/export ./backup/session.json --format json

7.3 对话压缩（Compaction）

当上下文使用超过 60% 时（约 600K tokens），建议压缩：

# 手动压缩
/compact

# 快捷键
Ctrl + L

压缩会将早期对话总结为结构化摘要，保留：

• 任务目标
• 已完成工作
• 进行中的工作
• 阻塞事项
• 关键决策

7.4 搜索历史

# 在当前对话中搜索
/search 数据库连接

# 搜索已保存的对话
/history --search "bug修复"

---

8. 配置管理

8.1 配置文件位置

配置文件位于 ~/.codewhale/config.toml：

# ~/.codewhale/config.toml 示例

[general]
model = "deepseek-v4-pro"
mode = "agent"

[search]
provider = "duckduckgo"   # duckduckgo / bing / tavily / bocha / metaso / baidu

[subagents]
max_concurrent = 10        # 最大并发子代理数（上限 20）

[approval]
auto_approve_reads = true  # 读操作自动批准

[context]
auto_compact = true        # 自动压缩
compact_threshold = 0.6    # 压缩阈值（60%）

8.2 常用配置命令

# 查看当前配置
/config

# 修改默认模型
/config set general.model deepseek-v4-flash

# 修改搜索引擎
/config set search.provider bing

# 重置配置
/config reset

---

9. 上下文管理

9.1 上下文窗口

DeepSeek V4 模型支持 1M token 上下文窗口。上下文使用情况在状态栏实时显示。

9.2 前缀缓存

DeepSeek 使用前缀缓存来降低 API 成本：

• 缓存粒度：128 tokens
• 缓存命中折扣：约 90%
• 共享前缀在多次请求间复用

最佳实践：

• 保持系统提示稳定，不要频繁修改
• 新内容追加而不重排已有内容
• 读取文件后引用路径和行号，而不是重新引用不同格式的内容

9.3 上下文使用建议

使用率	状态	建议
< 60%	正常	无需操作
60-80%	注意	考虑执行 /compact
> 80%	紧张	建议立即压缩或开启新会话

---

10. 实用技巧

10.1 高效使用子代理

对于多步骤任务，使用子代理并行处理：

# 在对话中发送（模型会自动决策）
"请同时检查 src/、tests/ 和 docs/ 三个目录下的所有文件"

模型会自动启动多个只读子代理并行检索，效率远高于顺序读取。

10.2 文件操作技巧

# 添加文件到上下文
/file src/main.rs

# 添加多个文件
/file src/lib.rs src/utils.rs tests/

# 添加整个目录（递归）
/file src/ --recursive

10.3 快捷键速记表

最常用的 6 个快捷键：

操作	快捷键
中断生成	Ctrl + C
清屏/压缩	Ctrl + L
搜索历史	Ctrl + R
换行输入	Shift + Enter
退出	Ctrl + D
浏览历史	↑ / ↓

10.4 命令速记表

最常用的 6 个命令：

操作	命令
查看帮助	/help
切换模式	/agent / /plan
压缩对话	/compact
查看用量	/token
打开文件	/file
保存对话	/save

---

11. 常见问题

Q: 如何修改 API Key？

codewhale auth login
# 按照提示输入新的 API Key

Q: 对话太长卡顿怎么办？

# 方法一：压缩对话
/compact

# 方法二：开启新会话
/reset

Q: 如何查看 API 调用费用？

/token    # 查看 token 用量
/cost     # 查看费用估算

Q: 如何启用/禁用思考模式？

/thinking on    # 启用（显示模型推理过程）
/thinking off   # 禁用

Q: 如何切换模型？

/model deepseek-v4-pro     # 切换到 V4 Pro（更强推理）
/model deepseek-v4-flash   # 切换到 V4 Flash（更快更便宜）

Q: 支持哪些搜索引擎？

# DuckDuckGo（默认）
/config set search.provider duckduckgo

# Bing
/config set search.provider bing

# 其他选项：tavily, bocha, metaso, baidu

Q: 如何更新到最新版本？

# npm 安装方式
npm update -g @deepseek/codewhale

# cargo 安装方式
cargo install codewhale --force

Q: 对话保存位置在哪里？

• Windows: %USERPROFILE%\.codewhale\sessions\
• macOS/Linux: ~/.codewhale/sessions/

Q: 如何在离线环境使用？

DeepSeek TUI 需要网络连接。如需离线使用，请考虑使用 Ollama 等本地部署方案。

---

附录

A. 命令行参数参考

codewhale [选项]

选项：
  --workspace <路径>        指定工作区目录
  --mode <模式>             工作模式：agent / plan / yolo
  --model <模型名>          指定模型
  --config <路径>           指定配置文件路径
  --version                 显示版本信息
  --help                    显示帮助

B. 环境变量

变量	说明
DEEPSEEK_API_KEY	API 密钥（优先级高于配置文件）
DEEPSEEK_BASE_URL	API 基础 URL（自定义端点）
CODEWHALE_CONFIG	配置文件路径

C. 相关资源

• 官方网站：https://deepseek.com
• API 文档：https://api-docs.deepseek.com
• GitHub：https://github.com/deepseek-ai
• 源码仓库：git clone https://github.com/Hmbown/DeepSeek-TUI.git