当前位置：首页 > 技术分享 > 正文内容

CodeWhale 开源终端 AI 编程助手：DeepSeek V4 原生驱动，37k Star 的终端 Agent

CodeWhale — 本地优先的终端 AI 编程 Agent 框架

2026年，终端 AI 编程助手赛道迎来了一位重磅选手——CodeWhale（仓库名 Hmbown/CodeWhale）。这个基于 Rust 构建的开源项目在 GitHub 上狂揽超过 37,000 颗星星，成为 DeepSeek V4 生态中最受关注的终端 Agent 框架之一。

它不是又一个"套壳"的终端 AI 工具。CodeWhale 的核心理念是：Agent 改代码前，先要有一个身份。这个终端、这个用户、这个分支、这个会话——这就是它的 ego 层。在这之上，它用一套 Constitution（宪法）体系来管理真实工作区中各种冲突的优先级。

一、项目背景

CodeWhale 由 Hmbown 团队开发，代码以 MIT 协议开源。项目定位为"面向 DeepSeek V4 和开放模型的本地 Agent 运行框架"，强调本地优先、安全可控、可扩展。

属性	信息
项目名称	CodeWhale
GitHub	github.com/Hmbown/CodeWhale
Stars	37,940+
编程语言	Rust
许可证	MIT
核心模型	DeepSeek V4（同时支持小米 MiMo、OpenRouter 等）
安装方式	Cargo / npm / Homebrew / Docker / 直接下载
数据结构	CLI + TUI 双模式

二、核心设计理念

2.1 Ego 层：你是谁

多数编程 Agent 从"更强"开始——更多工具、更长上下文、更多自动化。CodeWhale 从责任开始。

Agent 修改仓库之前，先要有一个地址：这个终端、这个用户、这个分支、这个会话。这就是 ego 层——不是为了炫耀，而是为了连续性；不只是人格面具，而是责任的落点。

2.2 Constitution：谁说了算

真实工作区是一组冲突来源：用户当前意图、仓库规则、Shell 输出、旧记忆、历史交接、安全策略和未完成改动，全都在同一轮里竞争。CodeWhale 用 Constitution 给这些来源排出优先级：

用户意图至上：当前请求高于旧 repo 规则、记忆和历史交接
证据高于猜测：工具输出 > 模型猜测，失败的命令如实报告
验证内建：验证是任务的一部分，不是可选项
本地法律可配：仓库可以添加 .codewhale/constitution.json 定义持久规则
运行时策略强制：模式、审批门、沙箱、回滚都是代码，不是模型要记住的建议

2.3 产品本质

CodeWhale 的产品本质是模型外面的排序层：谁在行动、听谁的规则、有什么证据、下一个人或 Agent 如何继续。这套排序层让 AI 助手不再是"黑盒给答案"，而是"结构化协作"。它是真正的 Agent 操作系统级抽象——不仅有工具，还有安全门、身份层和持久化状态机。

三、功能特性

3.1 多模态工具系统

CodeWhale 内置了丰富的工具支持：

文件操作：读写、搜索、替换，带审批门和沙箱
Shell 执行：命令执行，带权限控制和沙箱隔离
Git 操作：Commit、Branch、Diff，side-git 快照回滚
Web 抓取：在线搜索和信息提取
MCP 协议：支持 Model Context Protocol 标准工具集成
RLM：远程语言模型路由
子 Agent：并发子智能体并行工作

3.2 Provider 路由

DeepSeek V4 是一等路径，但不是唯一边界。CodeWhale 同时支持：

DeepSeek V4（原生一等支持）
Xiaomi MiMo（小米大模型）
OpenRouter（多模型聚合网关）
NVIDIA NIM
SiliconFlow / Fireworks / Novita
Arcee / Ollama / SGLang / vLLM
自托管和 OpenAI 兼容网关

3.3 安全机制

审批门：敏感操作需用户批准
沙箱：危险操作在沙箱中执行
side-git 快照：每次操作前自动保存快照，/restore 一键回滚
诊断反馈：编辑后自动进行语言服务器诊断

3.4 会话和工作流

并发子 Agent：多 Agent 并行调查和实现
持久会话：Session 跨终端持久化
Fork / Relay：分支和交接机制
Runtime API：HTTP/SSE 接口，支持 VS Code 和 GUI 集成
Skills：可复用工作流，从 ~/.codewhale/skills/ 加载
WhaleFlow：分支/叶子工作流编排

四、快速安装

CodeWhale 支持多种安装方式，选择最适合你的：

# Rust 用户（推荐）
cargo install codewhale-cli --locked
cargo install codewhale-tui --locked

# npm 用户
npm install -g codewhale

# macOS Homebrew
brew tap Hmbown/deepseek-tui
brew install deepseek-tui

# 中国大陆镜像（如果 GitHub 不稳定）
cargo install --git https://cnb.cool/codewhale.net/codewhale \
  --tag v0.8.57 codewhale-cli --locked --force

首次启动会自动提示配置 DeepSeek API Key：

codewhale auth set --provider deepseek
codewhale doctor  # 检查环境
codewhale         # 启动

五、与同类工具对比

特性	CodeWhale	Cursor	Claude Code
开源	✅ MIT	❌	❌
Langue	Rust	TypeScript	TypeScript
模式	终端 TUI	IDE 插件	终端 CLI
本地优先	✅	部分	✅
多模型	10+ 提供商	3+	仅 Claude
MCP 协议	✅	✅	✅
回滚机制	side-git 快照	文件恢复	有限
Constitution	✅ 完整	❌	CLAUDE.md

六、总结

CodeWhale 的出现标志着终端 AI 编程助手进入了一个新阶段。它不再只是"帮你写代码的命令行工具"，而是一个完整的 Agent 运行框架——有身份层、规则层、工具层和安全层。在 DeepSeek V4 的强大模型能力驱动下，CodeWhale 同时保持了对小米 MiMo 等其他主流模型的开放支持。

对于开发者来说，CodeWhale 最大的价值在于三点：本地优先确保隐私安全、Rust 底层带来极致性能、Constitution 体系让 AI 协作变得可控可预测。

如果你在用 DeepSeek V4 或其他开放模型写代码，不妨试试 CodeWhale——它可能是你终端里最后一个 AI 编程助手。

参见：GitHub - Hmbown/CodeWhale · codewhale.net