## 项目概述

CodeWhale 是一个开源的、社区驱动的终端编码智能体（coding agent）工具，使用 Rust 编写，采用 MIT 许可证。它最初为 DeepSeek 模型提供原生体验，现已发展为一个支持多种模型和提供商的通用编码工具。CodeWhale 允许用户自带模型（BYOM），支持托管或本地模型，并强调开源模型优先，不偏向任何特定提供商。它运行在用户自己的机器上，提供交互式 TUI 和命令行执行模式。

## 核心功能

- **多模型、多提供商支持**：支持 DeepSeek、Claude、GPT、Kimi、GLM 等 30+ 提供商，以及本地 vLLM、SGLang、Ollama 等，无需 API 密钥。
- **角色化模型编排（Fleet）**：用户可以为不同角色（如规划者、执行者、审查者）指定不同的模型和提供商，实现混合模型工作流。
- **可定制的智能体框架**：角色定义、宪法（constitution）等均为可编辑文件，用户可自定义智能体行为。
- **安全与权限控制**：提供 Plan/Act/Operate 模式，支持审批策略、沙箱（macOS Seatbelt、Linux bubblewrap）、仓库法律（repo law）等安全机制。
- **持久化与恢复**：支持会话快照、任务队列、Fleet 账本（ledger），可恢复中断的工作。
- **丰富的工具集**：内置 shell、文件操作、Git、GitHub、MCP、技能（skills）、钩子（hooks）等工具。
- **TUI 与 CLI**：提供交互式终端界面和 `codewhale exec` 命令行模式，支持脚本和 CI 集成。
- **可访问性**：提供低动态、ASCII 安全模式等辅助功能。

## 适用与不适用场景

**适用场景：**

- 需要在终端中进行代码编写、修改、测试等开发任务的开发者。
- 希望使用多种 LLM 提供商（包括本地模型）的用户。
- 需要自动化编码任务、CI/CD 集成的团队。
- 需要可定制、可审计的智能体行为的用户。

**不适用场景：**

- 需要图形化 IDE 完整体验的用户（CodeWhale 是终端工具）。
- 需要托管云服务的用户（CodeWhale 是本地优先）。
- 需要非编码类任务（如文档撰写）的用户（虽然可通过覆盖基础提示词扩展，但主要面向编码）。
- 需要 Windows 沙箱完整支持的用户（Windows 沙箱支持有限）。

## 技术架构与依赖

- **语言**：Rust（edition 2024）
- **许可证**：MIT
- **主要依赖**：
  - `ratatui`：TUI 渲染
  - `clap`：命令行参数解析
  - `tokio`：异步运行时
  - `serde`：序列化
  - `sqlite`：状态持久化
  - `quickjs`：Workflow 脚本引擎
  - `portable-pty`：PTY 支持
  - `ratatui`、`crossterm` 等
- **架构**：Cargo workspace，包含多个 crate，如 `tui`、`cli`、`core`、`config`、`state`、`tools`、`mcp`、`hooks`、`execpolicy`、`agent` 等。

## 安装与快速开始

**安装方式：**

- **npm**：`npm install -g codewhale`
- **Cargo**：`cargo install codewhale-cli codewhale-tui`（需要 Rust 工具链）
- **Docker**：`docker pull ghcr.io/hmbown/codewhale:latest`
- **预编译二进制**：从 GitHub Releases 下载
- **其他**：Nix、Scoop、Android/Termux 等，详见官方文档。

**快速开始：**

```bash
# 设置提供商（例如 DeepSeek）
codewhale auth set --provider deepseek

# 启动 TUI
codewhale

# 无头模式执行任务
codewhale exec "修复失败的测试"

# 启动本地 Web 客户端
codewhale web
```

## 典型使用方法

**TUI 交互：**

- `/model`：切换提供商和模型
- `/fleet`：构建和运行团队（角色化模型编排）
- `/undo`：撤销上一轮操作
- `/restore <N>`：回滚工作区到之前的快照
- `Tab`：在 Plan/Act/Operate 模式间切换（空输入时）或补全命令（有输入时）
- `Shift+Tab`：切换权限姿态（Ask/Auto-Review/Full Access）
- `!`：通过审批路径运行 shell 命令

**CLI 示例：**

```bash
# 运行任务并输出 JSON 事件流
codewhale exec --output-format stream-json "分析代码库"

# 使用 Fleet 运行多任务
codewhale fleet run tasks.json --max-workers 4

# 查看 Fleet 状态
codewhale fleet status
```

**配置示例：**

```toml
# ~/.codewhale/config.toml
provider = "deepseek"
default_text_model = "deepseek-v4-pro"

[providers.deepseek]
api_key = "YOUR_API_KEY"
```

## 配置与部署要点

- **配置文件**：`~/.codewhale/config.toml`（主配置）、`~/.codewhale/settings.toml`（UI 偏好）、`~/.codewhale/mcp.json`（MCP 服务器）、`~/.codewhale/constitution.json`（用户宪法）等。
- **环境变量**：支持 `CODEWHALE_*` 和 `DEEPSEEK_*` 系列变量，如 `CODEWHALE_PROVIDER`、`CODEWHALE_MODEL`、`CODEWHALE_API_KEY` 等。
- **项目覆盖**：`<workspace>/.codewhale/config.toml` 可覆盖部分配置，但只能收紧安全策略。
- **部署**：支持 Docker、Kubernetes（通过 Docker 镜像）、CI/CD 集成（`codewhale exec`）。
- **安全**：支持审批策略、沙箱、仓库法律、权限规则（`permissions.toml`）等。
- **更新**：支持自动更新检查，可通过 `codewhale update` 更新。

## 限制、风险与许可证

- **许可证**：MIT，独立社区项目，与任何模型提供商无关。
- **限制**：
  - Windows 沙箱支持有限（无 OS 级命令沙箱）。
  - 部分功能（如 Workflow）仍处于预览阶段。
  - 依赖第三方模型提供商的服务可用性。
- **风险**：
  - 使用 API 密钥需注意安全，避免泄露。
  - 沙箱并非绝对安全，用户需谨慎授权。
  - 项目仍在快速发展，API 可能变化。

## 官方链接

- **GitHub 仓库**：https://github.com/Hmbown/CodeWhale
- **官方文档**：https://codewhale.net/
- **Discord 社区**：https://discord.gg/37gfS3ksug
- **最新版本**：v0.9.5（2026-08-08 发布）

## 信息来源和分析时间

- **信息来源**：GitHub 仓库 README、文档（docs/ 目录）、CONTRIBUTING.md 等。
- **分析时间**：2026-08-08（基于最新发布版本 v0.9.5）。