whale

README

Whale

简体中文 · English

Whale 是一个非官方的 DeepSeek CLI / DeepSeek 编程 Agent。
运行在终端里，支持读代码、改代码、运行命令、MCP 和 Skills。

90% live prefix-cache hit · ~30x cheaper per task vs Claude Code · terminal-first · open source

---

快速开始

curl -fsSL https://raw.githubusercontent.com/usewhale/whale/main/scripts/install.sh | sh
whale setup
whale

Whale 当前使用 DeepSeek API。运行前请先在 DeepSeek Platform 创建 API key。API 细节见 DeepSeek API docs。

也可以直接运行一次性任务：

whale exec "解释这个仓库是做什么的"
printf '总结当前目录\n' | whale exec

---

和其他工具有什么区别

	Whale	Claude Code	Codex CLI	Cursor	Aider
主要形态	终端 TUI/CLI	终端 Agent	终端 Agent	IDE	CLI
默认后端	DeepSeek	Anthropic	OpenAI	多模型	多模型
DeepSeek 优化	是	否	否	否	有限
Prefix-cache 友好	是	n/a	n/a	取决于模型	有限
本地读写代码	是	是	是	是	是
运行 shell / test	是	是	是	部分	是
/ask 只读模式	是	部分	部分	n/a	部分
/plan 规划模式	是	是	是	n/a	部分
MCP	是	是	取决于版本	部分	部分
Skills / 工作流复用	是	是	是	部分	有限
开源	是	否	是	否	是

Whale 的重点不是“支持最多模型”，而是把 DeepSeek API 变成一个更稳定、便宜、适合长时间打开的本地编程 Agent。

为什么 DeepSeek-only？

DeepSeek 的低价只是第一层优势。真正适合做长会话编程 Agent 的关键，是 prefix cache。

DeepSeek 的 prefix cache 对字节稳定很敏感。Whale 的工具循环围绕这个特点设计：尽量保持追加式 turn、稳定的上下文顺序和可恢复的会话记录，让长任务能持续吃到缓存收益。

这也是 Whale 不急着做通用 provider 抽象的原因。Claude、OpenAI、DeepSeek 的缓存机制、tool-call 形态和 reasoning 行为并不一样。强行套一层通用接口，通常会牺牲 DeepSeek 最有价值的部分。

Whale 针对 DeepSeek 做了这些适配：

通用 Agent 常见假设	DeepSeek 实际会发生	Whale 的处理
tool-call JSON 总是稳定	payload 可能 malformed、被转义或混进 reasoning	repair / scavenge 路径
深层 tool schema 能稳定保留	部分深层嵌套参数可能丢失	工具参数尽量扁平化
失败工具需要统一 replan	有些失败应该原样反馈给模型	更细的失败分类和 recovery 策略
用户取消就是普通工具失败	取消后不应该继续恢复或补计划	中断路径单独处理
reasoning 深度只靠 prompt	DeepSeek 暴露 reasoning_effort	runtime 里保留 effort 控制

Whale 的目标是让 DeepSeek 的价格优势、缓存优势和编码能力真正落到终端工作流里。

---

Whale 能做什么

• 理解代码库：读取文件、搜索代码、总结项目结构和关键模块。
• 修改代码：生成 patch、编辑文件、补测试、修 bug、重构局部模块。
• 运行命令：执行 shell 命令、测试、构建、诊断脚本，并把结果带回对话。
• 交互式工作流：在本地 TUI 里连续对话，支持会话保存和 whale resume 恢复。
• 只读提问：用 /ask 进入只读问答模式，适合先理解代码，不让 Agent 修改文件。
• 先规划再执行：用 /plan 先产出计划，再决定是否让 Agent 实施。
• 扩展工具能力：通过 MCP 接入外部工具，通过 Skills 复用固定工作流。
• 无头执行：用 whale exec 在脚本、CI 或一次性任务里运行单条 prompt。

常用命令

命令	作用
whale	启动交互式 TUI
whale setup	保存 DeepSeek API key
whale doctor	运行健康检查
whale exec "prompt"	非交互运行单条 prompt
whale resume [id]	恢复已保存会话
/ask [prompt]	只读提问模式
/plan [prompt]	先规划，再决定是否执行
/skills	查看本地 skills
/mcp	查看 MCP server 状态

MCP

Whale 支持从 MCP server 加载工具。MCP 工具会作为普通 Whale 工具注册，并继续走审批流程。

当前支持：

• stdio MCP server
• Streamable HTTP MCP server
• disabled_tools
• HTTP headers 和环境变量展开
• filesystem server allowed-directories 校验

配置说明见 docs/mcp.md。

Skills

Whale 支持本地 Agent Skills。一个 skill 是包含 SKILL.md 的指令目录，可用于沉淀固定工作流、团队规范或特定工具用法。

默认发现路径：

• .whale/skills
• .agents/skills
• ~/.whale/skills
• ~/.agents/skills

在 TUI 中可以这样触发：

$my-skill 帮我按这个工作流处理当前任务

更多说明见 docs/skills.md。

配置

Whale 会把本地状态存放在 ~/.whale/ 下。API key、偏好设置、会话记录和 MCP 配置都在本地管理。

更多说明见 docs/configuration.md。

---

Non-goals

• 不做通用多模型外壳。 Whale 当前就是 DeepSeek-only，优先把 DeepSeek 的缓存、工具调用和成本优势做好。
• 不做 IDE。 Whale 是 terminal-first，和你的 shell、git、测试命令一起工作，不替代 Cursor 这类 IDE。

项目状态

Whale 仍在快速迭代中，建议先用于个人项目、实验仓库或可回滚的开发流程。功能和交互可能会继续变化。

免责声明： 本项目与 DeepSeek Inc. 无关，系独立开源社区项目。

参与贡献

关于克隆、开发、测试、issues 和 pull requests，请查看 CONTRIBUTING.md。

安全

如果是安全相关问题，请查看 SECURITY.md。