Hmbown/CodeWhale
GitHub: Hmbown/CodeWhale
CodeWhale是一款基于终端的深度学习编码代理工具。
Stars: 38658 | Forks: 3324
# CodeWhale
## 安装
`codewhale` 以一对自包含的 Rust 发布二进制文件的形式安装：
`codewhale` 分派命令和它启动的用于交互会话的兄弟 `codewhale-tui` 运行时。npm 和 Docker 会为你安装这两个二进制文件；Cargo 和手动安装必须将这两个二进制文件放在同一目录中（通常是 `PATH` 上的目录）。npm 软件包只是那些发布二进制文件的安装程序/包装器；代理不在 Node 上运行。
```
# 1. npm — easiest if you already use Node. The package downloads the
# matching prebuilt Rust binaries from GitHub Releases.
npm install -g codewhale
# 2. Cargo — no Node needed. Requires Rust 1.88+ (the crates use the
# 2024 edition; older toolchains fail with "feature `edition2024` is
# required"). Run `rustup update` first, or use a non-Cargo path below.
cargo install codewhale-cli --locked # `codewhale` (entry point)
cargo install codewhale-tui --locked # `codewhale-tui` (TUI binary)
# 3. Homebrew — legacy compatibility only.
# The tap/formula still uses the old deepseek-tui name. Prefer npm, Cargo,
# Docker, or direct downloads for new installs until the formula is renamed.
brew tap Hmbown/deepseek-tui
brew install deepseek-tui
# 4. Direct download — platform archive from GitHub Releases.
# https://github.com/Hmbown/CodeWhale/releases
# Archives include both codewhale and codewhale-tui plus an install script.
# Individual binaries are also attached for scripts; keep the pair together.
# 5. Docker — prebuilt release image.
docker volume create codewhale-home
docker run --rm -it \
-e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
-v codewhale-home:/home/codewhale/.codewhale \
-v "$PWD:/workspace" \
-w /workspace \
ghcr.io/hmbown/codewhale:latest
```
已经安装？使用与安装路径匹配的更新程序：
```
codewhale update # release-binary updater
npm install -g codewhale@latest # npm wrapper
brew update && brew upgrade deepseek-tui # legacy Homebrew installs only
cargo install codewhale-cli --locked --force
cargo install codewhale-tui --locked --force
```
## Harness 的工作原理
# 自托管 SGLang
SGLANG_BASE_URL="http://localhost:30000/v1" codewhale --provider sglang --model deepseek-v4-flash
# 自托管 vLLM
VLLM_BASE_URL="http://localhost:8000/v1" codewhale --provider vllm --model deepseek-v4-flash
# 可信局域网 vLLM 通过 HTTP
DEEPSEEK_ALLOW_INSECURE_HTTP=1 VLLM_BASE_URL="http://192.168.0.110:8000/v1" codewhale --provider vllm --model deepseek-v4-flash
# 自托管 Ollama
ollama pull codewhale-coder:1.3b
codewhale --provider ollama --model codewhale-coder:1.3b
```
Inside the TUI, `/provider` opens the provider picker and `/model` opens the
local model/thinking picker. `/provider openrouter` and `/model ` switch
directly, while `/models` explicitly fetches and lists live API models when the
active provider supports model listing.
---
## Release Notes
Release-specific changes live in [CHANGELOG.md](CHANGELOG.md). This README
stays focused on current install paths, core workflows, provider setup, runtime
interfaces, and extension points.
---
## Usage
```bash
codewhale # interactive TUI
codewhale "explain this function" # one-shot prompt
codewhale exec --auto --output-format stream-json "fix this bug" # NDJSON backend stream
codewhale exec --resume "follow up" # continue a non-interactive session
codewhale --model deepseek-v4-flash "summarize" # model override
codewhale --model auto "fix this bug" # auto-select model + thinking
codewhale --yolo # auto-approve tools
codewhale auth set --provider deepseek # save API key
codewhale doctor # check setup & connectivity
codewhale doctor --json # machine-readable diagnostics
codewhale setup --status # read-only setup status
codewhale setup --tools --plugins # scaffold tool/plugin dirs
codewhale models # list live API models
codewhale sessions # list saved sessions with timestamps
codewhale resume --last # resume the most recent session in this workspace
codewhale resume # resume a specific session by UUID
codewhale fork # fork a saved session into a sibling path
codewhale serve --http # HTTP/SSE API server
codewhale serve --mobile # LAN mobile control page; token-gated by default
codewhale serve --acp # ACP stdio adapter for Zed/custom agents
codewhale run pr # fetch PR and pre-seed review prompt
codewhale mcp list # list configured MCP servers
codewhale mcp validate # validate MCP config/connectivity
codewhale mcp-server # run dispatcher MCP stdio server
codewhale update # check for and apply binary updates
```
在交互式 TUI 编曲器中，在行前加上 `!` 以通过正常的批准、沙盒和输出界面运行 shell 命令，例如 `! cargo test -p codewhale-tui sidebar`。
### 分支对话
已保存的会话故意是可分支的。`codewhale fork ` 将现有已保存会话复制到一个新的兄弟会话中，记录父会话 ID 在元数据中，并打开该分支以便您可以探索一个替代方向，而不会污染原始路径。会话选择器和 `codewhale sessions` 用父 ID 标记分支会话。
`codewhale sessions` 列出跨工作区保存的会话，包括最后更新的时间戳。`codewhale resume --last` 和 `codewhale --continue` 选择当前工作区的最新会话；从另一个目录恢复工作时要传递显式的会话 ID。
在 TUI 中，Esc-Esc 回退可以将活动转写回先前的用户提示并将在编曲器中编辑该提示。`/restore` 和 `revert_turn` 是独立的 workspace 回滚工具：它们从 side-git 快照中恢复文件，但不会重写对话历史。
Docker 镜像发布到 GHCR 以进行发布构建：
```
docker volume create codewhale-home
docker run --rm -it \
-e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
-v codewhale-home:/home/codewhale/.codewhale \
-v "$PWD:/workspace" \
-w /workspace \
ghcr.io/hmbown/codewhale:latest
```
有关固定标签、本地镜像构建、卷所有权说明和非交互式管道使用，请参阅 [docs/DOCKER.md](docs/DOCKER.md）。
### Zed / ACP
DeepSeek 可以作为为通过 stdio 启动本地 ACP 代理的编辑器运行的自定义 Agent Client Protocol 服务器。在 Zed 中添加自定义代理服务器：
```
{
"agent_servers": {
"DeepSeek": {
"type": "custom",
"command": "codewhale",
"args": ["serve", "--acp"],
"env": {}
}
}
}
```
第一个 ACP 切片支持通过您现有的 DeepSeek 配置/API 密钥创建新会话和提示响应。工具支持的编辑和检查点回放尚未通过 ACP 暴露。
社区维护的适配器：[acp-codewhale-adapter](https://github.com/rockeverm3m/acp-codewhale-adapter）
将 `codewhale exec --auto` 连接到 `cc-connect`，为需要工具支持的 ACP 工作流但不在内置 Zed 切片中使用的用户提供桥梁。
### 键盘快捷键
| 键 | 操作 |
|---|---|
| `Tab` | 完成 `/` 或 `@` 条目；运行时，将草稿排队为后续操作；否则循环模式 |
| `Shift+Tab` | 循环推理努力：关闭 → 高 → 最大 |
| `F1` | 可搜索的帮助覆盖层 |
| `Esc` | 返回 / 取消 |
| `Ctrl+K` | 命令调色板 |
| `Ctrl+R` | 恢复早期会话 |
| `Alt+R` | 搜索提示历史记录并恢复已清除的草稿 |
| `Ctrl+S` | 保存当前草稿（`/stash list`，`/stash pop` 恢复） |
| `@path` | 在编曲器中附加文件/目录上下文 |
| `↑`（在编曲器开始时） | 选择要删除的附件行 |
完整快捷键目录：[docs/KEYBINDINGS.md](docs/KEYBINDINGS.md)。
## 模式
| 模式 | 行为 |
| --- | --- |
| **计划** 🔍 | 只读调查 — 模型在做出更改之前探索并提出计划；多步调查使用 `checklist_write` |
| **代理** 🤖 | 默认交互模式 — 多步工具使用带有批准门；大量工作使用 `checklist_write` 跟踪 |
| **YOLO** ⚡ | 在受信任的工作区自动批准所有工具；多步工作仍然保持可见的清单 |
## 配置
用户配置：`~/.codewhale/config.toml`（备用 `~/.deepseek/config.toml`）。项目覆盖：`/.codewhale/config.toml`（备用 `/.deepseek/config.toml`）（拒绝：`api_key`，`base_url`，`provider`，`mcp_config_path`）。[config.example.toml](config.example.toml) 包含每个选项。
TUI 页脚可以使用 `/statusline` 或通过在配置中设置 `[tui].status_items` 来修剪。当前页脚自定义从内置芯片中选择，例如 `mode`，`model`，`status`，`git_branch`，`tokens` 和 `cache`；芯片顺序由 `config.toml` 中 `status_items` 中键的顺序控制。交互式选择器写入规范顺序。多行布局、自定义颜色和外部命令小部件不是当前状态行界面的部分。
通常不需要为兼容 DeepSeek 的端点创建新的提供程序。保持 `provider = "deepseek"` 并设置 `[providers.deepseek].base_url` / `model`，或使用 `provider = "openai"` 为通用的 OpenAI 兼容网关。在用户配置或环境变量中保持 `provider`，`api_key` 和 `base_url`；项目覆盖不能设置它们。
关键环境变量：
| 变量 | 目的 |
|---|---|
| `DEEPSEEK_API_KEY` | API 密钥 |
| `DEEPSEEK_BASE_URL` | API 基础 URL |
| `DEEPSEEK_HTTP_HEADERS` | 可选的自定义模型请求头，例如 `X-Model-Provider-Id=your-model-provider` |
| `DEEPSEEK_MODEL` | 默认模型 |
| `DEEPSEEK_STREAM_IDLE_TIMEOUT_SECS` | 流空闲超时（秒），默认 `300`，夹在 `1..=3600` 之间 |
| `CODEWHALE_PROVIDER` / `DEEPSEEK_PROVIDER` | `deepseek`（默认），`nvidia-nim`，`openai`，`atlascloud`，`wanjie-ark`，`volcengine`，`openrouter`，`xiaomi-mimo`，`novita`，`fireworks`，`siliconflow`，`siliconflow-CN`，`arcee`，`moonshot`，`sglang`，`vllm`，`ollama`，`huggingface` |
| `DEEPSEEK_PROFILE` | 配置配置文件名称 |
| `DEEPSEEK_MEMORY` | 设置为 `on` 以启用用户内存 |
| `DEEPSEEK_ALLOW_INSECURE_HTTP=1` | 在受信任网络上允许非本地的 `http://` API 基础 URL |
| `NVIDIA_API_KEY` / `OPENAI_API_KEY` / `ATLASCLOUD_API_KEY` / `WANJIE_ARK_API_KEY` / `VOLCENGINE_API_KEY` / `VOLCENGINE_ARK_API_KEY` / `ARK_API_KEY` / `OPENROUTER_API_KEY` / `XIAOMI_MIMO_API_KEY` / `XIAOMI_API_KEY` / `MIMO_API_KEY` / `NOVITA_API_KEY` / `FIREWORKS_API_KEY` / `SILICONFLOW_API_KEY` / `ARCEE_API_KEY` / `MOONSHOT_API_KEY` / `KIMI_API_KEY` / `SGLANG_API_KEY` / `VLLM_API_KEY` / `OLLAMA_API_KEY` / `HUGGINGFACE_API_KEY` / `HF_TOKEN` | 提供程序身份验证 |
| `OPENAI_BASE_URL` / `OPENAI_MODEL` | 通用 OpenAI 兼容端点和模型 ID |
| `ATLASCLOUD_BASE_URL` / `ATLASCLOUD_MODEL` | AtlasCloud 端点和模型覆盖 |
| `WANJIE_ARK_BASE_URL` / `WANJIE_ARK_MODEL` | Wanjie Ark 端点和模型覆盖 |
| `VOLCENGINE_BASE_URL` / `VOLCENGINE_ARK_BASE_URL` / `ARK_BASE_URL` / `VOLCENGINE_MODEL` / `VOLCENGINE_ARK_MODEL` | Volcengine Ark 端点和模型覆盖 |
| `OPENROUTER_BASE_URL` | OpenRouter 端点覆盖 |
| `XIAOMI_MIMO_BASE_URL` / `MIMO_BASE_URL` / `XIAOMI_MIMO_MODEL` / `MIMO_MODEL` | Xiaomi MiMo 端点和模型覆盖；Token Plan 默认为 `https://token-plan-sgp.xiaomimimo.com/v1` |
| `NOVITA_BASE_URL` | Novita 端点覆盖 |
| `FIREWORKS_BASE_URL` | Fireworks 端点覆盖 |
| `SILICONFLOW_BASE_URL` / `SILICONFLOW_MODEL` | SiliconFlow 端点和模型覆盖 |
| `ARCEE_BASE_URL` / `ARCEE_MODEL` | Arcee AI 端点和模型覆盖 |
| `SGLANG_BASE_URL` | 自托管 SGLang 端点 |
| `SGLANG_MODEL` | 自托管 SGLang 模型 ID |
| `VLLM_BASE_URL` | 自托管 vLLM 端点 |
| `VLLM_MODEL` | 自托管 vLLM 模型 ID |
| `OLLAMA_BASE_URL` | 自托管 Ollama 端点 |
| `OLLAMA_MODEL` | 自托管 Ollama 模型标签 |
| `HUGGINGFACE_API_KEY` / `HF_TOKEN` / `HUGGINGFACE_BASE_URL` / `HUGGINGFACE_MODEL` | Hugging Face 端点和模型覆盖 |
| `NO_ANIMATIONS=1` | 启动时强制启用无动画模式 |
| `SSL_CERT_FILE` | 用于企业代理的定制 CA 套件 |
在 `settings.toml` 中设置 `locale`，使用 `/config locale zh-Hans` 或依赖 `LC_ALL`/`LANG` 来选择 UI 颜色和发送到 V4 模型的备用语言。最新的用户消息仍然在自然语言推理和回复中获胜，因此即使是在英文系统区域设置中，中文用户仍然保持中文。请参阅 [docs/CONFIGURATION.md](docs/CONFIGURATION.md) 和 [docs/MCP.md](docs/MCP.md)。
## 模型与定价
| 模型 | 上下文 | 输入（缓存命中） | 输入（缓存未命中） | 输出 |
|---|---|---|---|---|
| `deepseek-v4-pro` | 1M | $0.003625 / 1M | $0.435 / 1M | $0.87 / 1M |
| `deepseek-v4-flash` | 1M | $0.0028 / 1M | $0.14 / 1M | $0.28 / 1M |
DeepSeek 平台默认为 `https://api.deepseek.com/beta`，因此可以测试受 beta 门控的 API 功能而无需额外设置。将 `base_url = "https://api.deepseek.com"` 设置为退出。
旧别名 `deepseek-chat` / `deepseek-reasoner` 映射到 `deepseek-v4-flash` 并于 2026 年 7 月 24 日后退役。NVIDIA NIM 变体使用您的 NVIDIA 账户条款。
## 发布您的技能
codewhale 从工作区目录（`.agents/skills` → `skills` → `.opencode/skills` → `.claude/skills` → `.cursor/skills`）和全局目录（`~/.agents/skills` → `~/.claude/skills` → `~/.codewhale/skills` → `~/.deepseek/skills`）中查找技能。每个技能都是一个包含 `SKILL.md` 文件的目录：
```
~/.agents/skills/my-skill/
└── SKILL.md
```
必需的前置内容：
```
---
name: my-skill
description: Use this when DeepSeek should follow my custom workflow.
---
# My Skill
Instructions for the agent go here.
```
命令：`/skills`（列出），`/skill `（激活），`/skill new`（脚手架），`/skill install github:/`（社区），`/skill update` / `uninstall` / `trust`。社区安装从 GitHub 开始不需要后端服务。安装的技能出现在模型可见的会话上下文中；代理可以在任务与它们的描述匹配时自动选择相关技能，通过 `load_skill` 工具。
首次启动还会安装用于常见工作流程的捆绑系统技能skill-creator`，`delegate`，`v4-best-practices`，`plugin-creator`，
`skill-installer`，`mcp-builder`，`documents`，`presentations`，
`spreadsheets`，`pdf` 和 `feishu`。这些位于 `~/.codewhale/skills`（或备用 `~/.deepseek/skills`）中，并进行了版本控制，因此新捆绑包在升级时添加，而无需重新创建用户故意删除的技能。
## 文档
| 文档 | 主题 |
|---|---|
| [GUIDE.md](docs/GUIDE.md) | 首次运行用户指南 |
| [ARCHITECTURE.md](docs/ARCHITECTURE.md) |
标签：可视化界面, 请求拦截, 通知系统, 靶机