Whale

usewhaleMIT活跃维护

面向 DeepSeek 的终端优先编码 Agent，靠约 98% 的提示缓存命中率和 1M 上下文降低调用成本，支持 MCP 工具与动态工作流。

Whale — blazingly fast, terminal-first AI coding agent for DeepSeek. ~98% prompt cache hit rate, 1M context, MCP tools, dynamic workflows.

v0.1.66发布于 2026-08-11 00:03 UTC933star +2 / 7 天75fork同步于 2026-11-10 17:54 UTC

编码 Agent 终端工具提示缓存 MCP 工具 DeepSeek

对比 GitHub 官网 coding-agent deepseek deepseek-agent deepseek-cli deepseek-coding-agent

怎么上手

由 README 提炼，执行前请确认

原文

npm install -g @usewhale/whale
whale setup
whale

硬件要求按 README 说明

README 未说明显存或 GPU 要求；工具本身运行在终端，模型推理走 DeepSeek API，Windows 需 Windows 10 或 Windows Server 2016 及以上

下载：源码 zip·GitHub Releases（安装包）本站不镜像安装包

项目说明

由 README 自动翻译提炼

没人工点评？写下你的经验

面向 DeepSeek 的终端优先 AI 编码代理，靠高缓存命中率把长上下文编码成本压到很低

面向 DeepSeek 的终端优先编码 Agent，靠约 98% 的提示缓存命中率和 1M 上下文降低调用成本，支持 MCP 工具与动态工作流。

核心能力

以约 98% 的 prompt 缓存命中率复用上下文，降低单次会话成本
针对 DeepSeek 的 1M token 长上下文与工具调用做原生适配
用 JavaScript 脚本编排多 agent 的 Dynamic Workflows
接入 1000+ MCP 服务器扩展文件、shell、git、web 等工具
提供 TUI、单次 CLI 与 headless 三种运行接口

容易踩的坑

项目已停止维护，README 建议改用官方 DeepSeek Harness；Dynamic Workflows 默认关闭，需在 TUI 执行 /config 或改配置开启；使用前必须先用 whale setup 配置 DeepSeek API key

内容由模型根据 README 生成，可能不完整或不准确，以官方文档为准。看原文 README

最近发版

5 个版本v0.1.66

全部 release

v0.1.66最新正式版2026-08-11 · 2026-08-11 00:03 UTC
v0.1.66

Summary

This release sharpens the TUI and hardens the ACP/MCP runtime:
1. ACP session lifecycle — session/delete so Zed's Trash actually removes whale threads, plus permission options constrained to the ACP schema enum so approvals are never silently dropped.
2. Agent turn reliability — an "execute, don't narrate" system block plus wider premature-end recovery catches announce-then-stop turns across the ACP, terminal CLI, and subagents; abrupt turns recover with interrupt tracing.
3. MCP integration robustness — no more server spawn storms on every session/new, negative caching of failed servers, sanitized logs, concurrency-safe stderr capture, and restored tool promotion on resume.
4. TUI polish — wrap-around arrow navigation in every list picker, and Alt+P permission cycling that works even while a turn is running.
What's Changed

ACP: session/delete so Zed Trash removes whale sessions (#355) — @reneleonhardt
- initialize now advertises sessionCapabilities {list:{}, delete:{}}, so Zed's agent-panel Trash works instead of being a cosmetic no-op (zed-industries/zed#51912).
- session/delete validates sessionId before touching disk, refuses in-flight prompts, removes the session .jsonl (fatal on failure) plus sidecar artifacts (best-effort), and is idempotent for unknown ids.
- Prompt registration re-resolves the session under lock, closing a lookup→register gap that could resurrect deleted .jsonl files.
Agent: "execute, don't narrate" system block (#357) — @reneleonhardt
- New static system-prompt block instructing the agent to execute rather than narrate, wired into the shared turn loop so it covers the ACP, terminal CLI, and subagents.
- Premature-end recovery widened to catch announce-then-stop patterns such as trailing colons and gerund lead-ins ("Fixing:", "Running tests:").
ACP: permission options constrained to the schema enum (#358) — @reneleonhardt
- PermissionOption.Kind is now a typed PermissionOptionKind with constants and validation; invalid kinds fail loudly on the send path instead of being silently rejected by strict clients.
TUI: wrap-around arrow navigation (#359) — @shayne-snap
- ↑ on the first list item cycles to the last and ↓ on the last cycles to the first, via a shared wrapSelection helper applied across menus, pickers, and panels — fzf/vim-style navigation.
TUI: Alt+P permission cycle while busy (#360) — @shayne-snap
- Alt+P now cycles ask → auto-review → auto-accept → ask even mid-turn; changes apply immediately to subsequent tool calls without emitting a spurious EventTurnDone.
Agent: recover abrupt turns and trace interrupts (#361) — @shayne-snap
- Recovery now catches additional premature end-turn lead-ins (e.g. Chinese "最后是"/"立即" and English "finally") so users no longer need to type 继续.
- Esc / Ctrl+C / exit-requested sources are preserved through the runtime protocol and persisted in turn markers, making unrelated interruptions diagnosable.
MCP: integration robustness (#362) — @reneleonhardt
- Each session/new no longer re-spawns MCP servers (including failed ones); failed servers are negatively cached to stop spawn storms and log spam.
- Log sanitization removes the raw client-supplied names/errors log-injection vector; stderr capture is concurrency-safe; sessionID race conditions fixed; tool promotion ordering restored on resume.
PRs
v0.1.652026-08-06 · 2026-08-06 11:14 UTC
查看更新说明
v0.1.65

Summary

This release hardens the ACP (Agent Client Protocol) runtime and the agent turn loop:
1. ACP reliability overhaul — proper model resolution and API transport selection for whale-acp, automatic session compaction at a safe threshold, a raised tool-iteration cap, session/list support so Zed shows previous sessions, and no more mid-prompt eviction of sessions with in-flight requests.
2. Agent turn recovery & correctness — the agent now recovers turns that end prematurely before a promised tool call, preserves cancellation causes so service shutdown is not mistaken for a user interrupt, and keeps DeepSeek conversation history ordered for thinking mode.
What's Changed

ACP: model resolution, API transport, auto-compaction & tool cap (#354) — @reneleonhardt
- Model resolution: WHALE_MODEL is validated against supported models at startup (invalid values fail fast) with fallback to deepseek-v4-flash; names are lowercase-canonicalized so a single name feeds both the provider and context-window derivation. The retired deepseek-chat alias is now rejected.
- API transport: new deepseek.API setting (auto | responses | chat_completions) exposed via WHALE_API (env > config > heuristic); web_search=server implies Responses, and chat_completions + server-side search degrades search to local with a warning instead of refusing to start. Wired through all runtime construction sites, including the web_fetch extractor.
- Auto-compaction: ACP now compacts at an explicit 0.85 threshold with the model-derived context window (1M for V4) — earlier than the agent default 0.90 to avoid the overflow trap.
- Tool iteration cap: DefaultMaxToolIters raised to 300 (from 100), configurable via WHALE_MAX_TOOL_ITERS; 0/negative values rejected.
- Env knobs: WHALE_MODEL, WHALE_API, WHALE_COMPACT_THRESHOLD, WHALE_CONTEXT_WINDOW, WHALE_MAX_TOOL_ITERS read once at startup.
- Hardening: rejects NaN/±Inf thresholds, honors web_search=local on the Responses transport, normalizes whitespace/case in WHALE_API, retries 429s in the web_fetch extractor, and drops a context-compacted event type that could panic the ACP event translator.
ACP: session/list so Zed shows previous sessions (#352) — @reneleonhardt
- initialize now advertises sessionCapabilities {list:{}}, so Zed's agent panel can show whale session history.
- session/list lists persisted sessions from the same store session/load uses: sessionId, cwd, title (first visible user message), updatedAt (last message activity, mtime fallback).
- Excludes subagent IDs, approval/tool-input event sidecars, and rewrite artifacts; supports the optional cwd filter; orders by recency with deterministic tie-breaks. session/delete remains future work.
ACP: never evict sessions with in-flight prompts (#350) — @reneleonhardt
- LRU eviction now skips active sessions — the cap may be exceeded briefly rather than tearing down MCP servers mid-prompt (fixes a race that broke mcp__ calls).
- Evicted runtimes close off the session/new critical path, and CloseSessions shuts down runtimes in parallel (MCP stdio close can take ~5s).
DeepSeek: preserve Responses history ordering (#353) — @shayne-snap
- Keeps the latest user message as the final Responses input instead of appending stale server-side search calls after it; drops failed reasoning-only turns and avoids replaying plain private reasoning.
- Binds each web search call to the assistant response that produced it, satisfying DeepSeek thinking mode's reasoning → search → function-call → tool-result ordering (previously caused HTTP 400s and stale search content polluting unrelated prompts).
Agent: recover premature end turns (#356) — @shayne-snap
- When the model announces an immediate next action (e.g. "reading file…") but ends the turn without issuing the tool call, Whale now inserts a bounded hidden recovery nudge, clears th
v0.1.642026-08-05 · 2026-08-05 02:38 UTC
查看更新说明
v0.1.64

Summary

This release brings two significant improvements:
1. whale exec session resume & explicit mode control — resume existing sessions, override the execution mode (agent/ask/plan), and get strict, machine-parseable session validation with unified JSON error output. Built for automation workflows (CI, SWE-bench) with zero side effects on failed pre-checks.
2. TUI Alt+P permission cycle shortcut — cycle the permission mode directly from the chat view (ask → auto-review → auto-accept → ask) and always see the current permission state in the footer.
What's Changed

exec: session resume, mode control & strict session gate (#344) — @ehwjh2010
- exec --session <id>: resume an existing session; the next round appends to the same JSONL and reads the full first-round history. Worktree sessions are re-entered automatically (chdir to the recorded workspace, including subdirectories inside the worktree).
- exec --mode agent|ask|plan: explicit, case-insensitive mode override. On resume, the mode is persisted during the commit phase and carried to the next round; new sessions default to Agent.
- Strict session contract (ResolveStrictSession): blank/unsanitized IDs, nonexistent/unrecoverable sessions, subagent sessions, and cross-workspace sessions are rejected before any model call — zero provider requests, zero state writes.
- ValidateResumeTarget pre-validation matrix: session+worktree consistency, missing-worktree fallback, and explicit worktree takeover rejection all raised as identifiable error types.
- Unified JSON error output: with --json, session/mode/security/execution errors emit exactly one machine-readable ExecResult{status:error} and return a non-zero exit code — no double emission, no usage-text pollution.
- exec --help documentation: session/mode relationship docs; the SWE-bench script migrated to exec-local flag positions.
- Internal refactor: ResolveResumeWorktreeDecision split into a read-only decision + commit cleanup, with TargetWorkspace as a single fill point shared by TUI and exec; mode persistence converges on CommitStartState.
- Compatible with existing behavior: whale resume, TUI, app-server, and ACP unchanged (regression tests).
TUI: Alt+P permission mode cycle (#346) — @shayne-snap
- Alt+P cycles the permission mode in chat view: ask → auto-review → auto-accept → ask — no need to open /permissions to check or change the approval level.
- The footer now always shows the current permission state and the cycle hint (e.g. permission: ask (Alt+P to cycle)).
- Cycling is blocked while a turn is busy or suggestion panels are open, keeping the TUI in sync with the running turn.
- New model_permission_cycle_test.go covering cycle order, busy/suggestion-panel blocks, and the footer indicator.
PRs
- #344 feat: exec session resume, mode control, and strict session gate
- #346 feat(tui): add Alt+P permission mode cycle shortcut
Thanks

Thanks to @ehwjh2010 for building the exec session resume and mode control system, and to @shayne-snap for the Alt+P permission shortcut and for reviewing and merging the exec work. 🐋
v0.1.632026-07-18 · 2026-07-18 07:36 UTC
查看更新说明
v0.1.63 — 2026-07-16

🚀 Major Features
- Language Server Protocol (LSP) (#342) — Add full LSP support with 9 code intelligence tools: diagnostics, hover, go-to-definition, find-references, workspace symbols, document symbols, and more. Supports clangd, gopls, pyright, and rust-analyzer out of the box. Includes a /lsp toggle command, async server startup with ready-channel notification, mtime-based open-document cache, and cross-platform CI coverage. Huge thanks to @OliverZou for this incredible contribution — and welcome to Whale! 🎉
- Agent Client Protocol (ACP) (#338) — Add ACP support for external editor integration, starting with Zed. Whale can now serve as a background agent for your editor, with proper data-race fixes, pending-cancel handling, and config reordering.
🧹 Chores
- Remove stale .arts and .workbuddy artifacts
- Mark creack/pty as a direct dependency
- Add build_whale.bat and bin/ to .gitignore
- Ignore opencode.json
📦 New Contributors
- @OliverZou — First contribution! Delivered the entire LSP subsystem (#342) 🎉
Full Changelog: https://github.com/usewhale/whale/compare/v0.1.62...v0.1.63
v0.1.62v0.1.62 (2026-07-02)2026-07-01 · 2026-07-01 09:40 UTC
查看更新说明
v0.1.62 — 2026-07-02

🆕 Features
- feat(tui): show detailed user input answers in timeline (#335) — Full user input answers are now visible in the timeline, including multi-line responses. Removed 💬 emoji from the "Other" picker row for a cleaner look.
🧠 Agent
- agent: add anti-duplication guardrails to delegation policy (#336) — Prevents the model from delegating the same sub-task multiple times when it receives the same result back.
🐛 Fixes
- fix(tui): only title reasoning-only status cards, not all status cards — Prevents non-reasoning status cards from incorrectly showing a "Reasoning" label.
📦 What else
- Built with Go, distributed as static binaries for macOS, Linux, and Windows (amd64 + arm64).
- Published on npm as @usewhale/whale with platform-specific packages.

用户点评

登录用户的真实使用记录，可按版本和硬件筛选

共 0 条

还没有人点评。第一个说出真实体验的人最有价值。

README 原文

未翻译

在 GitHub 打开

[!IMPORTANT] This repository is no longer maintained. If needed, please use the official harness: DeepSeek Harness.

Building wirebox.sh — The identity and communication layer for AI agents.

Whale

🚀 Quick Start

Any platform:

npm install -g @usewhale/whale

macOS:

brew install usewhale/tap/whale

Linux:

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

Windows PowerShell:

Requires Windows 10 or Windows Server 2016 or later.

irm https://raw.githubusercontent.com/usewhale/Whale/main/scripts/install.ps1 | iex

Windows CMD:

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/usewhale/Whale/main/scripts/install.ps1 | iex"

# Set your DeepSeek API key
whale setup

# Launch the interactive TUI
whale

That's it. Type your question and Whale starts working — reading files, running commands, editing code, searching the web.

Need a different model provider, proxy, or custom config? See Configuration.

✨ At a Glance

What	Why it matters
💰 ~98% prompt cache hit	Whale reuses cached context aggressively — most prompts hit cache, slashing costs to pennies per session. DeepSeek pricing × Whale caching = AI-assisted coding at scale.
🐋 DeepSeek-native	Built for DeepSeek's long context (1M tokens), tool calling, and cost efficiency — no generic multi-model wrapper
🔁 Dynamic Workflows	Write JavaScript scripts that orchestrate multiple agents — fan-out research, multi-perspective review, pipelines. Claude Code compatible.
🔌 MCP	Plug in 1,000+ MCP servers for extended tooling — file ops, shell, git, web, and more
🧩 Skills + Plugins	Install community skills (code review, git workflows, etc.) or write your own

🔁 Dynamic Workflows

Whale's Dynamic Workflows let you script multi-agent orchestration in JavaScript:

// .whale/workflows/research.js
const results = await parallel([
  () => agent("Search for best practices in Go error handling"),
  () => agent("Find common Go error handling mistakes"),
]);
return agent("Synthesize both findings into a concise guide");

Fan-out research · Multi-perspective review · Pipeline processing · Adversarial validation

✅ Claude Code compatible — workflow scripts written for Claude Code work as-is in Whale.

⚠️ Disabled by default — run /config in the TUI and enable Dynamic workflows, or add [workflows] enabled = true to .whale/config.local.toml.

Learn more: Workflow Overview · Custom Workflow Guide

🧰 MCP, Skills & Plugins

Extension	What it does	Get started
MCP Servers	Connect to 1,000+ tools (databases, APIs, browser automation)	docs/mcp.en.md
Skills	Load domain expertise — code review, git-worktree, and more	docs/skills.en.md
Subagents	Define focused child-agent roles such as reviewers or researchers	docs/agents.en.md
Plugins	Extend Whale's runtime with custom logic	docs/plugins.en.md
Hooks	Run scripts on lifecycle events	docs/hooks.en.md

📸 How It Works

Whale currently offers three interfaces — with more environments on the way:

Interface	When to use
`whale` (TUI)	Interactive coding sessions — chat, review, iterate with full context
`whale ask "..."` (CLI)	One-shot questions, quick code reviews, single commands
`whale --headless`	CI/CD, automated PR reviews, scheduled tasks

🎯 Non-goals

Multi-model shell. Whale is DeepSeek-first — optimized for DeepSeek's caching, tools, and pricing.
IDE replacement. Whale is not an IDE — it's an agent that meets you wherever you code: terminal, desktop, or CI.

📦 Project Status

⚠️ No longer maintained. This project has been discontinued. If needed, please use the official DeepSeek Harness.

Disclaimer: This project is not affiliated with DeepSeek Inc. It was an independent open-source community project.

🤝 Contributing

See CONTRIBUTING.md for local development, testing, issues, and PRs.

Current direction and available tasks: ROADMAP.md.

Security issues: SECURITY.md.

Star History

🙏 Credits

Whale stands on the shoulders of giants:

Charmbracelet — Bubble Tea, Lip Gloss, Glamour, and the entire TUI ecosystem
fastschema/qjs — QuickJS Go bindings for workflow scripting
spf13/cobra — CLI framework
alecthomas/chroma — Syntax highlighting
yuin/goldmark — Markdown parsing
modelcontextprotocol/go-sdk — MCP protocol support
tetratelabs/wazero — Pure-Go WebAssembly runtime

And the many open-source libraries we depend on — thank you.

怎么上手

项目说明

核心能力

容易踩的坑

最近发版

v0.1.66

Summary

What's Changed

ACP: session/delete so Zed Trash removes whale sessions (#355) — @reneleonhardt

Agent: "execute, don't narrate" system block (#357) — @reneleonhardt

ACP: permission options constrained to the schema enum (#358) — @reneleonhardt

TUI: wrap-around arrow navigation (#359) — @shayne-snap

TUI: Alt+P permission cycle while busy (#360) — @shayne-snap

Agent: recover abrupt turns and trace interrupts (#361) — @shayne-snap

MCP: integration robustness (#362) — @reneleonhardt

PRs

v0.1.65

Summary

What's Changed

ACP: model resolution, API transport, auto-compaction & tool cap (#354) — @reneleonhardt

ACP: session/list so Zed shows previous sessions (#352) — @reneleonhardt

ACP: never evict sessions with in-flight prompts (#350) — @reneleonhardt

DeepSeek: preserve Responses history ordering (#353) — @shayne-snap

Agent: recover premature end turns (#356) — @shayne-snap

v0.1.64

Summary

What's Changed

exec: session resume, mode control & strict session gate (#344) — @ehwjh2010

TUI: Alt+P permission mode cycle (#346) — @shayne-snap

PRs

Thanks

v0.1.63 — 2026-07-16

🚀 Major Features

🧹 Chores

📦 New Contributors

v0.1.62 — 2026-07-02

🆕 Features

🧠 Agent

🐛 Fixes

📦 What else

用户点评

README 原文

Whale

🚀 Quick Start

✨ At a Glance

🔁 Dynamic Workflows

🧰 MCP, Skills & Plugins

📸 How It Works

🎯 Non-goals

📦 Project Status

🤝 Contributing

Star History

🙏 Credits

相关项目

ACP: `session/delete` so Zed Trash removes whale sessions (#355) — @reneleonhardt

ACP: `session/list` so Zed shows previous sessions (#352) — @reneleonhardt