+ 嵌套宪法 Constitution +
+
+ CodeWhale 先给 Agent 一个可追责的地址，再给上下文冲突一套法律。全局 Constitution 处理 truth、user agency、行动和验证；
+ 仓库可以通过 .codewhale/constitution.json 增加本地 law；
+ runtime policy 再把模式、审批、沙箱、成本和工具边界落到代码里。
+
{row.desc}
+
+ 普通项目说明仍放在 AGENTS.md；CodeWhale 专属的冲突解决和验证策略放在
+ .codewhale/constitution.json。详见
+ repo authority docs。
+
@@ -314,7 +346,8 @@ command = "~/.codewhale/hooks/pre.sh" # / message_submit / mode_change / Documentation 文档
- The short version of how it works. For the full architecture walk-through, see + The short version of how it works: identity first, nested authority next, then modes, tools, and providers. + For the full architecture walk-through, see docs/ARCHITECTURE.md in the repo.
@@ -339,6 +372,35 @@ command = "~/.codewhale/hooks/pre.sh" # / message_submit / mode_change /+ Nested Constitution 宪法 +
+
+ CodeWhale gives the agent an accountable address before it hands over the tool list. The global Constitution handles truth,
+ user agency, action, and verification. Repositories can add local law through
+ .codewhale/constitution.json. Runtime policy then turns modes, approvals,
+ sandboxing, cost limits, and tool boundaries into code.
+
{row.desc}
+
+ Put ordinary project instructions in AGENTS.md. Put CodeWhale-specific conflict
+ resolution and verification policy in .codewhale/constitution.json. See the
+ repo authority docs.
+
Modes 模式
diff --git a/web/app/[locale]/faq/page.tsx b/web/app/[locale]/faq/page.tsx
index 0e3d9167..6ed64751 100644
--- a/web/app/[locale]/faq/page.tsx
+++ b/web/app/[locale]/faq/page.tsx
@@ -23,7 +23,7 @@ const faqEn: FaqItem[] = [
q: "What is CodeWhale?",
a: (
<>
- CodeWhale is a terminal-native coding agent for open-source and open-weight models. It runs from the codewhale command, streams reasoning blocks, edits local workspaces with approval gates, and can auto-route each turn to the right model and thinking level. DeepSeek V4 is the first-class model path; OpenRouter is ready. Hugging Face, self-hosted, and other open-model surfaces are on the roadmap.
+ CodeWhale is a terminal-native coding agent for open-source and open-weight models. It runs from the codewhale command, streams reasoning blocks, edits local workspaces with approval gates, and can auto-route each turn to the right model and thinking level. DeepSeek V4 is the first-class model path; OpenRouter, Hugging Face, self-hosted runtimes, and other OpenAI-compatible routes are additive.
),
sources: ["README.md", "docs/ARCHITECTURE.md"],
@@ -113,8 +113,8 @@ codewhale doctor # full connectivity check`}
CodeWhale ships with these built-in providers:
- DeepSeek — first-class, native API. Reasoning streaming, cache metrics, thinking effort control. -
- OpenRouter — unified API for DeepSeek models and more. -
- OpenAI, NVIDIA NIM, Volcengine Ark, Xiaomi MiMo, SiliconFlow, Novita, Fireworks, sglang, vLLM, Ollama +
- OpenRouter — unified API for DeepSeek models and other open-model routes. +
- OpenAI-compatible, NVIDIA NIM, AtlasCloud, Wanjie Ark, Volcengine Ark, Xiaomi MiMo, Novita, Fireworks, SiliconFlow, SiliconFlow CN, Arcee AI, Moonshot/Kimi, Hugging Face, SGLang, vLLM, Ollama
Set the corresponding env var (e.g. OPENROUTER_API_KEY) and your provider in ~/.codewhale/config.toml.
@@ -157,7 +157,7 @@ default_text_model = "openrouter/deepseek/deepseek-v4-pro"`}
Yes. Use the vllm, sglang, or ollama providers with your local endpoint.
For OpenAI-compatible endpoints (llama.cpp server, text-generation-webui, Aphrodite, etc.), you can use the openai provider with a custom base_url.
CodeWhale also respects DEEPSEEK_ALLOW_INSECURE_HTTP=true for local HTTP endpoints.
- Full Hugging Face TGI/vLLM integration is on the roadmap.
+ Hugging Face Inference Providers are also available through the huggingface provider. Broader Hub discovery, model cards, datasets, and Jobs belong to Model Lab.
),
sources: ["#574", "#1303", "docs/CONFIGURATION.md"],
@@ -282,12 +282,12 @@ registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"`}
sources: ["#907", "#1545"],
},
{
- q: "What is Model Lab? When will Hugging Face integration be available?",
+ q: "What is Model Lab? What Hugging Face pieces are available?",
a: (
<>
- Model Lab is the planned open-model infrastructure layer: Hugging Face Hub API for model discovery, model cards, datasets, safetensors adapters, inference providers, and Jobs.
- It is NOT fully implemented. Track progress in #1977.
- Currently, you can use Hugging Face models through the OpenRouter provider or self-hosted endpoints.
+ The huggingface provider is the shipped OpenAI-compatible route for Hugging Face Inference Providers.
+ Model Lab is the planned open-model infrastructure layer for Hub discovery, model cards, datasets, safetensors adapters, and Jobs.
+ Track broader progress in #1977.
),
sources: ["#1977", "docs/MODEL_LAB.md"],
@@ -337,7 +337,7 @@ const faqZh: FaqItem[] = [
q: "CodeWhale 是什么？",
a: (
<>
- CodeWhale 是一个面向开源模型的终端原生编程智能体。通过 codewhale 命令启动，流式输出推理块，在有审批门槛的情况下编辑本地工作区，并可为每个回合自动选择最合适的模型和推理深度。DeepSeek V4 是一级模型路径；OpenRouter 已就绪。Hugging Face、自托管等开放模型接口已在路线图中。
+ CodeWhale 是一个面向开源模型的终端原生编程智能体。通过 codewhale 命令启动，流式输出推理块，在有审批门槛的情况下编辑本地工作区，并可为每个回合自动选择最合适的模型和推理深度。DeepSeek V4 是一级模型路径；OpenRouter、Hugging Face、自托管运行时和其他 OpenAI 兼容路由都是增量选择。
),
sources: ["README.md", "docs/ARCHITECTURE.md"],
@@ -426,8 +426,8 @@ codewhale doctor # 完整连接检查`}
CodeWhale 内建以下提供商：
- DeepSeek — 一级支持，原生 API。推理流、缓存指标、思考力度控制。 -
- OpenRouter — 统一 API，可访问 DeepSeek 等模型。 -
- OpenAI、NVIDIA NIM、Volcengine Ark、Xiaomi MiMo、SiliconFlow、Novita、Fireworks、sglang、vLLM、Ollama +
- OpenRouter — 统一 API，可访问 DeepSeek 和其他开放模型路由。 +
- OpenAI 兼容、NVIDIA NIM、AtlasCloud、Wanjie Ark、Volcengine Ark、Xiaomi MiMo、Novita、Fireworks、SiliconFlow、SiliconFlow CN、Arcee AI、Moonshot/Kimi、Hugging Face、SGLang、vLLM、Ollama
设置对应的环境变量（如 OPENROUTER_API_KEY）并在 ~/.codewhale/config.toml 中配置你的提供商。
@@ -470,7 +470,7 @@ default_text_model = "openrouter/deepseek/deepseek-v4-pro"`}
可以。使用 vllm、sglang 或 ollama 提供商连接本地端点。
对于 OpenAI 兼容端点（llama.cpp server、text-generation-webui 等），可以使用 openai 提供商并设置自定义 base_url。
CodeWhale 也支持 DEEPSEEK_ALLOW_INSECURE_HTTP=true 用于本地 HTTP 端点。
- 完整的 Hugging Face TGI/vLLM 集成正在路线图中。
+ Hugging Face Inference Providers 也可以通过 huggingface provider 使用。更完整的 Hub 发现、模型卡片、数据集和 Jobs 属于 Model Lab。
),
sources: ["#574", "#1303", "docs/CONFIGURATION.md"],
@@ -595,12 +595,12 @@ registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"`}
sources: ["#907", "#1545"],
},
{
- q: "Model Lab 是什么？Hugging Face 集成什么时候可用？",
+ q: "Model Lab 是什么？Hugging Face 哪些部分可用？",
a: (
<>
- Model Lab 是规划中的开放模型基础设施层：Hugging Face Hub API 用于模型发现、模型卡片、数据集、safetensors 适配器、推理提供商和 Jobs。
- 它尚未完全实现。关注 #1977 的进展。
- 目前，你可以通过 OpenRouter 提供商或自托管端点使用 Hugging Face 模型。
+ huggingface provider 是已经接入的 OpenAI 兼容 Hugging Face Inference Providers 路由。
+ Model Lab 是规划中的开放模型基础设施层：Hub 发现、模型卡片、数据集、safetensors 适配器和 Jobs。
+ 更完整的进展见 #1977。
),
sources: ["#1977", "docs/MODEL_LAB.md"],
diff --git a/web/app/[locale]/install/page.tsx b/web/app/[locale]/install/page.tsx
index ba7cc6b3..97beb087 100644
--- a/web/app/[locale]/install/page.tsx
+++ b/web/app/[locale]/install/page.tsx
@@ -9,8 +9,8 @@ export async function generateMetadata({ params }: { params: Promise<{ locale: s
return {
title: isZh ? "安装 · CodeWhale" : "Install · CodeWhale",
description: isZh
- ? "安装 CodeWhale 的 codewhale / codewhale-tui 二进制对。其他方式：npm、Homebrew、预编译二进制、Docker、国内镜像。"
- : "Install the matched codewhale / codewhale-tui binary pair. Other ways: npm, Homebrew, prebuilt binary, Docker, source.",
+ ? "安装 CodeWhale 的 codewhale / codewhale-tui 二进制对。v0.8.54 推荐 Cargo、GitHub Releases、CNB、Homebrew、预编译二进制、Docker、国内镜像。"
+ : "Install the matched codewhale / codewhale-tui binary pair. For v0.8.54 use Cargo, GitHub Releases, CNB, Homebrew, prebuilt binary, Docker, or source.",
};
}
@@ -25,8 +25,10 @@ const UPDATE = `codewhale update`;
const SET_KEY_BASH = `export DEEPSEEK_API_KEY=sk-...`;
const SET_KEY_AUTH = `codewhale auth set --provider deepseek --api-key sk-...`;
-const NPM_INSTALL = `npm install -g codewhale`;
-
+const RELEASE_DOWNLOAD = `# Download your platform archive:
+https://github.com/Hmbown/CodeWhale/releases/tag/v0.8.54`;
+const CNB_INSTALL = `cargo install --git https://cnb.cool/codewhale.net/codewhale --tag v0.8.54 codewhale-cli --locked --force
+cargo install --git https://cnb.cool/codewhale.net/codewhale --tag v0.8.54 codewhale-tui --locked --force`;
const TUNA_CONFIG = `# ~/.cargo/config.toml
[source.crates-io]
replace-with = "tuna"
@@ -35,8 +37,6 @@ replace-with = "tuna"
registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"`;
const TUNA_INSTALL = `cargo install codewhale-cli --locked
cargo install codewhale-tui --locked`;
-const NPMMIRROR = `npm config set registry https://registry.npmmirror.com
-npm install -g codewhale`;
const BREW = `brew tap Hmbown/deepseek-tui
brew install deepseek-tui`;
@@ -107,19 +107,15 @@ export default async function InstallPage({ params }: { params: Promise<{ locale
{isZh ? (
<>
- 编译并安装 codewhale 和 codewhale-tui 到 ~/.cargo/bin。
- 需要 Rust 1.88+——如未安装可访问{" "}
- rustup.rs。
- 下方「其他安装方式」列出了不用 Rust 工具链、国内镜像、Homebrew、预编译二进制等替代选项。
+ v0.8.54 推荐通过 Cargo 安装已发布的 crates。npm wrapper 暂缓发布，直到 release asset 发布路径加固完成。
+ 下方「其他安装方式」列出 GitHub Releases、CNB、国内镜像、Homebrew、预编译二进制等替代选项。
) : (
<>
- Compiles and installs codewhale and{" "}
- codewhale-tui to{" "}
- ~/.cargo/bin. Requires Rust 1.88+ — install via{" "}
- rustup.rs if you don't have it.
- See Other ways to install below for
- npm, Homebrew, prebuilt binaries, or mainland China mirrors.
+ For v0.8.54, install the published Cargo crates. The npm wrapper is deferred
+ while the release asset publication path is hardened. See{" "}
+ Other ways to install below for
+ GitHub Releases, CNB, Homebrew, prebuilt binaries, or mainland China mirrors.
)}
brew upgrade deepseek-tui or{" "}
- npm update -g codewhale. Cargo users can re-run both{" "}
+ installed via Homebrew, prefer the package manager instead:{" "}
+ brew upgrade deepseek-tui. Cargo users can re-run both{" "}
cargo install commands with --force.
)}
@@ -269,29 +264,41 @@ export default async function InstallPage({ params }: { params: Promise<{ locale
{isZh ? (
<>
- npm 包装器会从 GitHub Releases 下载对应平台的预编译二进制。需要 Node 18+。
- 安装后会同时提供 codewhale 和{" "}
- codewhale-tui 两个命令。
+ 编译并安装 codewhale 和 codewhale-tui 到 ~/.cargo/bin。
+ 需要 Rust 1.88+；如未安装可访问 rustup.rs。
) : (
<>
- The npm wrapper downloads the prebuilt binary from GitHub Releases for your
- platform. Requires Node 18+. Installs both codewhale{" "}
- and codewhale-tui on PATH.
+ Compiles and installs codewhale and{" "}
+ codewhale-tui to{" "}
+ ~/.cargo/bin. Requires Rust 1.88+; install via{" "}
+ rustup.rs if you don't have it.
)}
- {isZh ? "npm 经 npmmirror 镜像：" : "npm via npmmirror:"} -
-
{isZh ? (
<>
- npm 包装器仍会从{" "}
- github.com/Hmbown/CodeWhale/releases{" "}
- 下载二进制，国内可能较慢。Cargo + Tuna 完全绕开 GitHub。
+ v0.8.54 的 npm wrapper 暂缓发布。Cargo + Tuna 或 CNB 路径可以绕开 GitHub 下载瓶颈。
DeepSeek API（api.deepseek.com）在国内直连，无需代理。
) : (
<>
- The npm wrapper still downloads the binary from{" "}
- github.com/Hmbown/CodeWhale/releases, which can
- be slow over GFW. Cargo + Tuna routes around GitHub entirely. The DeepSeek API
- at api.deepseek.com is reachable from mainland
- China without a proxy.
+ The npm wrapper is deferred for v0.8.54. Cargo + Tuna or the CNB path routes
+ around GitHub download bottlenecks. The DeepSeek API at{" "}
+ api.deepseek.com is reachable from mainland China
+ without a proxy.
)}
{isZh - ? "DeepSeek V4 的最强智能体运行框架。" - : "The most agentic harness for DeepSeek V4."} + ? "先有自我，再有法律，永远留下证据。" + : "Ego first. Law next. Evidence always."}
CodeWhale {isZh - ? " 就是那个框架——围绕 DeepSeek V4 Pro 和 Flash 构建，用规则、工具、证据和反馈循环让模型持续工作并不断进步。DeepSeek V4 参与了编写。V4 越强，框架越强——每一轮对话留下更好的提示词和更清晰的交接，下一轮从更高起点出发。这个递归循环正是项目的核心使命：借助国际开源社区，构建一个让 V4 自主管理环境的自改进框架。" - : " is that harness — built around DeepSeek V4 Pro and Flash, with rules, tools, evidence, and feedback loops that help the model keep working and keep improving. DeepSeek V4 helped write it. As V4 improves, the harness improves with it. Each turn leaves behind better prompts and better handoffs — so the next turn starts stronger. That's the recursive loop at the heart of this project: an international open source community building a harness that lets V4 manage its own environment, turn after turn."} + ? " 是 DeepSeek V4 和开放模型的本地运行层。它给 Agent 一个可追责的自我、一套处理冲突的 law，以及把工具、审批、回滚、子 Agent 和交接都留在明面上的证据循环。" + : " is a local operating layer for DeepSeek V4 and open-model coding work. It gives an agent an accountable self, a conflict law for the workspace, and an evidence loop where tools, approvals, rollback, sub-agents, and handoffs stay visible."}
{/* MISSION CALLOUT */}- {isZh ? "核心思想" : "The ideas that make it what it is"} + {isZh ? "判断栈" : "The judgment stack"}
{isZh - ? "一个模型回答问题，一个智能体完成任务。区别在于框架——围绕模型构建的规则、工具、证据和反馈循环的运行环境。CodeWhale 围绕三条原则运作。" - : "A model answers a question. An agent finishes a task. The difference is the harness — the operating environment that surrounds the model with rules, tools, evidence, and feedback loops. CodeWhale operates on three principles."} + ? "模型会生成文本；Agent 会留下后果。CodeWhale 把后果需要的结构放在模型外面：自我、权威、证据、工具，各在其位。" + : "A model generates text; an agent leaves consequences. CodeWhale puts the structure for those consequences around the model: self, authority, evidence, and tools, each in its place."}
七层权威链，从不模糊
+责任要有地址
- 《宪法》第七条定义了九层权威层级——用户当前消息覆盖过时项目规则，实时工具输出覆盖假设，验证覆盖自信。模型不需要猜测该服从哪条指令。 + Agent 不是模型卡片，也不是排行榜数字。它是这个终端、这个工作区、这个会话里的实例。先有地址，责任才有落点。
DeepSeek V4 参与构建
+冲突时有法律
- V4 编写了框架的部分代码。每一轮对话的缓存前缀让《宪法》的实际成本接近免费。V4 越强，框架越强；框架越强，V4 在其中越高效——递归循环。 + 全局 Constitution、当前用户请求、运行时规则、仓库本地 law、实时证据、记忆、个性和旧交接各有顺位。冲突时不靠感觉。
国际社区，小补丁驱动
+证据留在本地
- 100:1 贡献模型——一个提示词、大量智能体小时、一个小补丁、一次维护者审查。无 CLA，无赞助商优先通道。每一条内容都被阅读。 + 文件、Shell、Git、Web、MCP、子 Agent、回滚和诊断都由 runtime 管理。模型不需要假装验证；它必须留下证据。
Seven tiers of authority, never ambiguous
+Responsibility needs an address
- Article VII of the Constitution ranks nine sources from the Articles themselves to prior-session handoffs. The user's current message outranks stale project rules. Live tool output outranks assumptions. Verification outranks confidence. The model never guesses which instruction to follow. + The agent is not a model card or leaderboard score. It is an instance in this terminal, this workspace, this session. Give it an address before you ask it to act.
DeepSeek V4 helped build it
+Conflict has law
- V4 wrote parts of this harness. DeepSeek's prefix caching makes the Constitution nearly free to reference every turn. As V4 improves, the harness improves with it. A more effective V4 makes the harness better — the recursive loop that defines this project. + Global Constitution, current user request, runtime statutes, repo-local law, live evidence, memory, personality, and old handoffs each have a rank. When they conflict, the agent has an order to follow.
International community, small patches
+Evidence stays local
- The 100-to-1 contribution model: one prompt, many agent-hours, one small patch, one maintainer review. No CLA. No sponsor lockouts. The maintainer reads everything personally, issues are triaged in the open, releases cut from main. + Files, shell, git, web, MCP, sub-agents, rollback, and diagnostics are runtime surfaces. The model does not claim verification as a mood; it has to leave evidence.
- {isZh ? "递归自我改进的开源智能体框架" : "A recursive harness, modelled at 100-to-1"} + {isZh ? "长任务要能被继承" : "Long work has to be inheritable"}
{isZh - ? "1948 年，Ralph Bown 用 100:1 的晶体管模型，把微小的结构讲清楚。CodeWhale 借用同样的形状：一个清晰提示词，把 DeepSeek V4 Pro 的缓存注意力、工具调用与子智能体凝结为一个可审查的小补丁。" - : "In 1948, Ralph Bown used a 100-to-1 model of the transistor to make a tiny structure legible. CodeWhale uses the same shape: one clear prompt turns DeepSeek V4 Pro's cached attention, tool use, and sub-agents into one small, reviewable patch."} + ? "难点不是让模型一次做更多事，而是让用户意图、权威顺序、证据和贡献者上下文足够清楚，让下一个维护者可以接住。" + : "The hard part is not making the model do more at once. It is keeping intent, authority, evidence, and contributor context clear enough for the next maintainer to inherit."}
{isZh - ? "100:1 不是性能基准，而是贡献形状：一个提示词、许多智能体小时、一个小补丁、一次维护者审查。" - : "100-to-1 is not a throughput benchmark. It is a contribution shape: one prompt, many agent-hours, one small patch, one maintainer review."} + ? "好的 Agent 工作不是一团活动记录，而是一条可以复核的线：请求、调查、补丁、验证、署名。" + : "Good agent work is not a pile of activity. It is a reviewable line: request, investigation, patch, verification, credit."}
{isZh - ? "框架承担了繁重工作：宪政提示、结构化信任、反馈循环和跨会话存活的交接。模型可以专注于任务本身。因为 DeepSeek V4 参与构建了这套框架，每一次改进都让 V4 在其中变得更有效——这让下一次改进变得更容易。" - : "The harness does the heavy lifting: constitutional prompts, structured trust, feedback loops, and handoffs that survive the session. The model is free to focus on the task. And because DeepSeek V4 helped build this harness, each improvement makes V4 more effective within it — which makes the next improvement easier."} + ? "框架承担了繁重工作：宪政提示、结构化信任、反馈循环、回滚和跨会话存活的交接。模型可以把注意力放在任务本身。" + : "The harness carries the heavy parts: constitutional prompts, structured trust, feedback loops, rollback, and handoffs that survive the session. The model can keep its attention on the task itself."}