CodeWhale（原 DeepSeek-TUI）项目介绍

CodeWhale（原 DeepSeek-TUI）项目介绍

项目定位

CodeWhale 是一个终端原生的 AI 编程 Agent Harness，围绕 DeepSeek V4 模型构建。

一句话定义：它不是”又一个 AI 编程工具”，而是一个Harness——一套规则、证据与反馈系统，让模型在复杂任务中保持方向感而非迷失。

解决什么问题：Agentic 模型在面对冲突信息时（用户意图、项目规则、系统默认值、工具输出、过期记忆）会失去方向感。CodeWhale 通过九级权限体系（Constitution）为模型提供明确的决策依据，让每次交互都有清晰的权威链。

核心能力

• Constitution 九级权限体系：从宪法条文到先例共九个层级，用户当前消息 > 过期指令，实时工具输出 > 假设，验证 > 自信
• Auto 模式智能路由：每轮通过一次廉价的 Flash 预调用自动选择模型和推理级别，短任务用 Flash，复杂任务升级到 Pro + 高推理
• 子 Agent 并发执行：支持 6 种角色的后台子 Agent（general/explore/plan/review/implementer/verifier），最多 20 个并发，完成后自动注入摘要到父会话
• RLM（递归语言模型）：持久化 Python REPL，用于处理超出上下文窗口的长文本，支持 chunk/batch/sequence 四种处理模式
• LSP 实时诊断注入：每次文件编辑后自动运行语言服务器，将诊断结果注入下一轮上下文
• 侧 Git 快照：每轮编辑在工作区外独立 Git 快照，支持 /restore 回滚，不影响用户的 .git
• 多协议服务：MCP stdio、HTTP/SSE 运行时 API、ACP 编辑器适配器三种服务模式
• 多提供商支持：15+ 模型提供商，包括 DeepSeek、NVIDIA NIM、OpenRouter、Ollama、SiliconFlow 等

技术栈

维度	技术选型
语言	Rust 1.88+（使用 2024 Edition）
TUI 框架	ratatui
异步运行时	Tokio（full feature）
HTTP 客户端	reqwest（rustls 后端）
Web 框架	axum（运行时 API）
持久化存储	SQLite（rusqlite）
配置格式	TOML
构建系统	Cargo workspace（15 个 crate）
部署方式	npm 包装器 + Cargo + Homebrew + Docker + 直接下载
平台支持	Linux x64/ARM64、macOS x64/ARM64、Windows x64

架构概览

双二进制架构

CodeWhale 采用匹配的双二进制设计：

• codewhale：调度器 CLI，负责参数解析、配置加载、入口路由
• codewhale-tui：TUI 运行时，包含完整引擎、工具系统、子 Agent 管理器和运行时 API

两个二进制文件必须版本匹配，npm/Homebrew/Docker 安装会自动配对。

快速体验

# 最简安装（需要 Node.js）
npm install -g codewhale

# 或使用 Cargo（需要 Rust 1.88+）
cargo install codewhale-cli --locked
cargo install codewhale-tui --locked

# 启动
export DEEPSEEK_API_KEY="your-key"
codewhale --model auto

教程导读

本教程分为两个部分：

AI 应用通用知识（6 章）

从 CodeWhale 的源码出发，抽象行业通用知识：

• Constitution 系统提示：九级权限体系的设计原理与缓存边界
• Agent Harness 架构：Harness 概念、与 Agent 框架的差异
• 子 Agent 角色分类：6 种角色、并发控制、上下文 Fork 策略
• 上下文压缩策略：Token 阈值、前缀缓存感知、手动 vs 自动
• 用户记忆系统：跨会话持久化记忆、三种注入方式、隐私边界
• Auto 模型路由：轻量预调用选择模型与推理级别的策略

每个知识点与 src/content/docs/common/ 中的通用教程对照，首次覆盖的知识点将创建新的通用知识教程。

编程核心技术（6 章）

聚焦 CodeWhale 的具体工程实践：

• Rust Workspace 架构：15 个 crate 的职责划分与依赖关系
• 流式 TUI 渲染：ratatui 流式渲染、键盘快捷键、状态机
• 侧 Git 快照系统：工作区回滚的设计决策与实现
• 工具审批策略引擎：YOLO 模式、审批缓存、策略配置
• RLM 子系统：持久化 REPL 设计、辅助函数体系、子查询分发
• 多协议服务架构：MCP/HTTP-SSE/ACP 三模式的复用与隔离