codewhale/README.zh-CN.md

CodeWhale

面向 DeepSeek V4 和开放模型的本地 Agent 运行框架：自我、权威、证据闭环。

English README · 日本語 README · Tiếng Việt README

核心想法

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

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

然后它需要法律。真实工作区是一组冲突来源：用户当前意图、仓库规则、Shell 输出、旧记忆、上一次交接、安全策略和未完成改动都会挤在同一轮里。CodeWhale 用 Constitution 给这些来源排出顺序：当前用户请求高于旧上下文；实时证据高于假设；验证高于自信；个性只影响语气，不决定行为。

CodeWhale 的产品本质是模型外面的排序层：谁在行动、听谁的 law、有什么证据，以及下一个人或 Agent 如何继续。

已经具备的能力

• 本地优先的终端 TUI；
• 文件、Shell、Git、Web、MCP、RLM、子 Agent 等带 schema 的工具；
• 审批门、沙箱、side-git 快照和 /restore 回滚；
• 编辑后的语言服务器诊断反馈；
• 并发子 Agent、持久会话、fork、relay 交接和运行时 API；
• DeepSeek V4 一等支持，同时保留 OpenRouter、Xiaomi MiMo、NVIDIA NIM、Arcee、SiliconFlow、Fireworks、Novita、自托管 SGLang/vLLM、Ollama 等显式 provider 路由。

DeepSeek 是一等路径，不是唯一边界。provider、model、base URL 和凭据是分开的选择。

安装

cargo install codewhale-cli --locked
cargo install codewhale-tui --locked
codewhale --version
codewhale --model auto

其他路径：

# GitHub Releases 提供平台归档包：
# https://github.com/Hmbown/CodeWhale/releases

# 如果 GitHub 访问不稳定，可以使用 CNB 镜像：
cargo install --git https://cnb.cool/codewhale.net/codewhale --tag v0.8.58 codewhale-cli --locked --force
cargo install --git https://cnb.cool/codewhale.net/codewhale --tag v0.8.58 codewhale-tui --locked --force

# 旧 Homebrew 兼容路径，formula 仍使用 deepseek-tui 名称
brew tap Hmbown/deepseek-tui
brew install deepseek-tui

codewhale npm wrapper 也可通过 npm install -g codewhale 安装。

Docker、直接下载、中国大陆镜像、Windows/Scoop、Nix、校验和和故障排查见 docs/INSTALL.md。

第一次运行

codewhale auth set --provider deepseek
codewhale auth status
codewhale doctor
codewhale

常用入口：/provider、/model、/config、/statusline、/skills、/restore。在输入框前加 ! 可以通过正常审批和沙箱路径运行 Shell 命令。

更多文档

README 只保留概念和最快路径。细节放在文档和 codewhale.net：

• 用户指南
• 安装指南
• 配置和仓库 constitution
• Provider 注册表
• 子 Agent
• Runtime API
• Model Lab
• 架构
• v0.9.0 发布验收

v0.9.0 轨道

v0.9.0 仍是集成轨道，只有在 tag、GitHub Release、npm、Cargo 和发布产物都真实切出并验证后才算发布。当前重点包括 relay/交接、转录降噪、命令和 provider 架构、VS Code/GUI runtime API、HarnessProfile、WhaleFlow，以及贡献者 credit hygiene。

致谢

• DeepSeek — 感谢 DeepSeek 提供模型与支持，让每一次交互成为可能。
• DataWhale — 感谢 DataWhale 的支持，并欢迎我们加入“鲸兄弟”大家庭。
• OpenWarp — 感谢 OpenWarp 优先支持 codewhale，并一起打磨更好的终端智能体体验。
• Open Design — 感谢 Open Design 对面向设计的智能体工作流提供支持与协作。

本项目由不断壮大的贡献者社区共同打造：

v0.8.48 合并或吸收的贡献者包括：@cy2311、@LING71671、@axobase001、@dzyuan、@mvanhorn、@malsony、@gaord、@yuanchenglu、@idling11、@h3c-hexin、@AdityaVG13、@Sskift、@cyq1017、@HUQIANTAO、@New2Niu、@AiurArtanis、@Lee-take、@nightt5879、@AresNing、@AccMoment、@reidliu41、@aboimpinto、@zhuangbiaowei、@donglovejava、@hongqitai、@zlh124、@encyc、@Implementist、@lihuan215、@LeoAlex0、@jimmyzhuu、@rockyzhang、@mo-vic、@hufanexplore、@hoclaptrinh33 、@BryonGo、@gordonlu 和 @hongchen1993。

同样感谢提供报告、复现和验证的 @buko、@yyyCode、@gaslebinh-glitch、@Dr3259、@lpeng1711694086-lang、@VerrPower、@yan-zay、@jretz、@Neo-millunnium、@caeserchen、@T-Phuong-Nguyen、@zhyuzhyu、@0gl20shk0sbt36、@hatakes、@goodvecn-dev、@bevis-wong、@PurplePulse 和 @nbiish。

• merchloubna70-dot — 28 个 PR，涵盖功能、修复和 VS Code 扩展基础架构 (#645–#681)
• WyxBUPT-22 — Markdown 表格、粗体/斜体和水平线渲染 (#579)
• loongmiaow-pixel — Windows + 中国安装文档 (#578)
• 20bytes — 用户记忆文档和帮助优化 (#569)
• staryxchen — glibc 兼容性预检 (#556)
• Vishnu1837 — glibc 兼容性改进 (#565)
• shentoumengxin — Shell cwd 边界验证 (#524)
• toi500 — Windows 粘贴修复报告
• xsstomy — 终端启动重绘报告
• melody0709 — 斜杠前缀回车激活报告
• lloydzhou 和 jeoor — 压缩成本报告；lloydzhou 还贡献了确定性的环境上下文注入 (#813, #922) 和 KV 前缀缓存稳定化 (#1080)
• Agent-Skill-007 — README 清晰化改进 (#685)
• woyxiang — Windows 安装文档 (#696)
• wangfeng — 价格/折扣信息更新 (#692)
• zichen0116 — CODE_OF_CONDUCT.md (#686)
• dfwqdyl-ui — 模型 ID 大小写兼容性报告 (#729)
• Oliver-ZPLiu — working... 卡死状态 Bug 报告和 Windows 剪贴板兜底修复 (#738, #850)
• reidliu41 — 退出后的恢复提示、工作区信任持久化、Ollama provider 支持，以及思考块流式终结修复 (#863, #870, #921, #1078)
• xieshutao — 纯 Markdown skill 兜底解析 (#869)
• GK012 — npm wrapper 的 --version 兜底 (#885)
• y0sif — 直接子智能体完成后唤醒父级 turn loop (#901)
• mac119 和 leo119 — codewhale update 命令文档 (#838, #917)
• dumbjack / 浩淼的mac — shell 命令空字节安全加固 (#706, #918)
• macworkers — fork 完成后显示新 session id (#600, #919)
• zero 和 zerx-lab — 通知条件配置和更完整的 OSC 9 通知正文 (#820, #920)
• chnjames — @mention 补全缓存、配置恢复优化，以及 Windows UTF-8 shell 输出修复 (#849, #927, #982, #1018)
• angziii — 配置安全、异步清理、Docker 加固和命令安全修复 (#822, #824, #827, #831, #833, #835, #837)
• elowen53 — UTF-8 解码和确定性测试覆盖 (#825, #840)
• wdw8276 — 用于自定义 session 标题的 /rename 命令 (#836)
• banqii — .cursor/skills 发现路径支持 (#817)
• junskyeed — API 请求动态 max_tokens 计算 (#826)
• Hafeez Pizofreude — fetch_url 的 SSRF 保护和 Star History 图表
• Unic (YuniqueUnic) — 基于 schema 的配置 UI（TUI + web）
• Jason — SSRF 安全加固
• axobase001 — 快照孤儿文件清理、npm 安装守卫、会话遥测修复、模型作用域缓存清理、符号链接技能支持，以及 npm 镜像逃生路径指引 (#975, #1032, #1047, #1049, #1052, #1019, #1051, #1056)
• MengZ-super — /theme 命令基础和 SSE gzip/brotli 解压支持 (#1057, #1061)
• DI-HUO-MING-YI — Plan 模式只读沙箱安全修复 (#1077)
• bevis-wong — 粘贴-回车自动提交问题的精确复现 (#1073)
• Duducoco 和 AlphaGogoo — 技能斜杠菜单和 /skills 覆盖范围修复 (#1068, #1083)
• ArronAI007 — macOS Terminal.app 和 ConHost 窗口大小调整残留修复 (#993)
• THINKER-ONLY — OpenRouter 和自定义端点模型 ID 保留 (#1066)
• Jefsky — deepseek-cn 官方端点默认值 (#1079, #1084)
• wlon — NVIDIA NIM provider API key 优先级诊断 (#1081)
• donglovejava — paste @file 整合、CJK panic 修复、用户反馈、RLM 路由、edit_file 重试 (#2154–#2168)
• encyc — session token 分解显示和 /status (#2152)
• saieswar237 — 审查流程文档 (#2178)
• sximelon — paste Enter 抑制、键盘处理提取 (#2174, #2042)
• nanookclaw — search provider 显示在 doctor (#2135)
• Sskift — CLI 默认环境变量覆盖防止 (#2119)
• xin1104 — Homebrew codewhale 二进制安装 (#2105)
• mrluanma — Metaso 搜索提供商 (#2059)
• Lellansin — 主目录下跳过配置合并 (#2055)
• zhuangbiaowei — 更新发布渠道 (#2145)

---

贡献

欢迎提交 pull request——请先查看 CONTRIBUTING.md 并留意开放 issue 中的好入门任务。

本项目与 DeepSeek Inc. 无隶属关系。

许可证

MIT

Star 历史