From 325aec396dd7ee442169617108de09c505b86224 Mon Sep 17 00:00:00 2001 From: Hunter Bown Date: Tue, 26 May 2026 06:40:12 -0500 Subject: [PATCH] =?UTF-8?q?docs:=20v0.8.45=20harness=20framing=20=E2=80=94?= =?UTF-8?q?=20READMEs,=20website,=20metadata,=20contributors?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README: new tagline, What Is It/Key Features → harness framing - README.zh-CN/ja-JP: matching Chinese/Japanese translations - web/app/page.tsx: updated hero, description, three-column grid, flywheel - web/app/layout.tsx: metadata title + description for harness framing - website/index.html + zh/: hero, feature grid, install command - README: updated contributor credits for v0.8.45 (idling11, gaord, h3c-hexin, cyq1017, reidliu41, wdw8276, zlh124) --- README.ja-JP.md | 47 +++++----- README.md | 141 ++++++++++++------------------ README.zh-CN.md | 50 +++++------ web/app/[locale]/docs/page.tsx | 56 +++++------- web/app/[locale]/faq/page.tsx | 22 +++-- web/app/[locale]/page.tsx | 57 ++++++------ web/app/[locale]/roadmap/page.tsx | 26 +++--- web/app/layout.tsx | 6 +- website/index.html | 38 ++++---- website/zh/index.html | 38 ++++---- 10 files changed, 220 insertions(+), 261 deletions(-) diff --git a/README.ja-JP.md b/README.ja-JP.md index dc21668d..9916ec32 100644 --- a/README.ja-JP.md +++ b/README.ja-JP.md @@ -1,6 +1,6 @@ # 🐳 CodeWhale -> **DeepSeek ファーストで、オープンソースおよびオープンウェイトのコーディングモデルに向けたターミナルネイティブのコーディングエージェントです。DeepSeek V4 の 100 万トークンのコンテキストウィンドウとプレフィックスキャッシュ機能を中心に構築されています。単一のバイナリとして配布され、Node.js や Python のランタイムは不要です。MCP クライアント、サンドボックス、永続的なタスクキューも標準で同梱されています。** +> **DeepSeek V4 のための最もエージェント的なハーネス。ルール、ツール、証拠、フィードバックループ——モデルがタスクを完了するまで働き続け、さらに改善し続けるための仕組みです。** [![CI](https://github.com/Hmbown/CodeWhale/actions/workflows/ci.yml/badge.svg)](https://github.com/Hmbown/CodeWhale/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/codewhale)](https://www.npmjs.com/package/codewhale) @@ -63,34 +63,35 @@ cargo install codewhale-tui --locked --force ## codewhale とは？ -codewhale は、ターミナル内で完結するコーディングエージェントです。DeepSeek のフロンティアモデルがあなたのワークスペースに直接アクセスできるようにし、ファイルの読み取り・編集、シェルコマンドの実行、Web 検索、Git 管理、サブエージェントの統制などを、すべて高速でキーボード駆動の TUI を通じて行えます。 +モデルは質問に答えます。エージェントはタスクを完了します。その差がハーネス——モデルを取り巻くルール、ツール、証拠、フィードバックループという動作環境です。 -**DeepSeek V4 向けに構築** (`deepseek-v4-pro` / `deepseek-v4-flash`)。100 万トークンのコンテキストウィンドウとネイティブの thinking-mode（思考連鎖）ストリーミングをサポートします。 +CodeWhale はそのハーネスであり、DeepSeek V4 Pro と Flash のために構築されました。メンテナがモデルがタスクの途中で方向を見失ったり、ユーザーの現在の要求より古い指示に従ったり、コマンドが失敗すると諦めたりすることにうんざりしたことから、個人ツールとして始まりました。そこから生まれたのが、モデルの方向性を保つシステムです：憲法的なプロンプト階層、構造化された信頼境界、並列サブエージェント、プレフィックスキャッシュ対応のコンテキスト管理、そしてモデルが自己修正するための十分なシグナルを提供する検証の鼓動。 -### 主な機能 +DeepSeek V4 はこのハーネスの一部を書くのを手伝いました。これは重要です——CodeWhale がすでに V4 を使う最も効果的な方法であり、V4 が改善するにつれてハーネスも改善することを意味します。各ターンがより良いプロンプト、より良いルール、より良いハンドオフを残します。次のターンはより強い位置から始まります。 -- **モデル自動ルーティング** — `--model auto` / `/model auto` がターンごとにモデルと推論強度を選択 -- **Fin の高速経路** — thinking off の低コストな `deepseek-v4-flash` がルーティング、RLM 子呼び出し、要約、調整作業を担当 -- **ネイティブ RLM** (`rlm_open`/`rlm_eval`) — 永続 REPL セッションでバッチ解析を行い、`peek`、`search`、`chunk`、`sub_query_batch` などの補助関数を利用 -- **Thinking-mode ストリーミング** — モデルがタスクに取り組む様子をリアルタイムで観察し、思考連鎖の展開を追える -- **完全なツールスイート** — ファイル操作、シェル実行、Git、Web 検索／ブラウズ、apply-patch、サブエージェント、MCP サーバー -- **100 万トークンコンテキスト** — コンテキスト追跡、手動または設定ベースのコンパクション、プレフィックスキャッシュのテレメトリ -- **3 つのモード** — Plan（読み取り専用の探索）、Agent（承認ありのインタラクティブ）、YOLO（自動承認） -- **推論努力ティア** — `Shift + Tab` で `off → high → max` を切り替え -- **セッション保存／再開** — 長時間実行のセッションをチェックポイント化して再開可能 -- **ワークスペースのロールバック** — リポジトリの `.git` には触れずに、サイド Git によるターン前後のスナップショットを `/restore` と `revert_turn` で扱える -- **永続的タスクキュー** — 再起動を超えて生き残るバックグラウンドタスク。スケジュール自動化や長時間レビューなどに -- **HTTP/SSE ランタイム API** — `codewhale serve --http` でヘッドレスエージェントワークフローを実現 -- **MCP プロトコル** — Model Context Protocol サーバーに接続して拡張ツールを利用可能。詳細は [docs/MCP.md](docs/MCP.md) を参照 -- **LSP 診断** — rust-analyzer、pyright、typescript-language-server、gopls、clangd により、編集ごとにエラー／警告をインライン表示 -- **ユーザーメモリ** — クロスセッションの嗜好をシステムプロンプトに注入できる、オプションの永続メモファイル -- **ローカライズ済み UI** — `en`、`ja`、`zh-Hans`、`pt-BR` を自動検出 -- **ライブコスト追跡** — ターンごと／セッションごとのトークン使用量とコスト見積もり、キャッシュヒット／ミスの内訳 -- **スキルシステム** — GitHub から取得できる命令パック。初回起動時に `skill-creator`、`mcp-builder`、`documents`、`presentations`、`spreadsheets`、`pdf`、`feishu` などのスターターセットを同梱 +### ハーネスの仕組み + +**憲法的階層。** システムプロンプトは法の抵触エンジンです。ユーザーの意図は古いメモリより上。ライブの証拠は仮定より上。検証は自信より上。各ターンは明確な権限チェーンを継承するので、モデルはどの指示に従うべきか推測する必要がありません。 + +**構造化された信頼。** ハードな境界を持つ3つのモード——Plan（読み取り専用）、Agent（承認ゲート付き）、YOLO（信頼済みワークスペースで自動承認）。OS レベルのサンドボックスが境界を支えます：macOS の Seatbelt、Linux の Landlock、Windows の Job Objects。危険なコマンドはモードに関係なく分類・ゲート制御されます。 + +**フィードバックの鼓動。** 失敗したコマンド、失敗したテスト、LSP 診断——これらは行き止まりではありません。モデルがチューニングできる信号です。非ゼロの終了コードは情報です。型エラーは修正ベクトルです。ハーネスは失敗を読み取り可能にし、ユーザーが常に舵を取り直さなくてもモデルが回復できるようにします。 + +**継続性。** メモリはセッションをまたいで持続します。ハンドオフはコンテキスト圧縮後も生存します。セッションは保存・再開・兄弟パスへのフォークが可能です。次の知性——人間であれ機械であれ——が、すでに学ばれたことを再発見する必要なく、前回の中断点から引き継ぎます。 + +**分散作業。** サブエージェントが並行実行、一度に最大 20。`agent_open` は即座に戻り、親は作業を続けます。結果は構造化された完了イベントとして到着し、境界付きハンドルで——完全なトランスクリプトで親コンテキストを埋める必要はありません。[docs/SUBAGENTS.md](docs/SUBAGENTS.md) を参照。 + +**適正な知性。** Fin——thinking off の安価な Flash——がモデル自動ルーティング、RLM 子呼び出し、要約、調整を処理します。Pro はアーキテクチャ、デバッグ、セキュリティレビューに使用。`--model auto` がターンごとにモデルと思考レベルを選択します。各問題に適切な量の知性を。 + +**長期注意の経済学。** 100 万トークンのコンテキストウィンドウとプレフィックスキャッシュテレメトリ。キャッシュヒットはミスより約 100 倍安価。`/statusline` チップがプレフィックス安定性をリアルタイムで表示し、変更がキャッシュ予算を破壊しようとしているのが見えます。 + +**回復付きの自由。** 毎ターンの side-git スナップショット（リポジトリの `.git` には触れません）。`/restore` と `revert_turn` でワークスペースを即座にロールバック。危険な操作は OS レベルでサンドボックス化。モデルに試させることができます。 + +その他の機能面：**RLM セッション**（`peek`、`search`、`chunk`、`sub_query_batch` ヘルパー付きのバッチ分析用永続 Python REPL）、**LSP 診断**（編集ごとの rust-analyzer、pyright、tsserver、gopls、clangd からのインラインエラー）、**MCP プロトコル**、**HTTP/SSE ランタイム API**、再起動を超えて存続する**永続タスクキュー**、Zed や他のエディタ向け **ACP アダプター**、**SWE-bench エクスポート**、**インストール可能なスキル**、**テーマピッカー**、**デスクトップ通知**、キャッシュヒット/ミス内訳付きの**ライブコスト追跡**。 --- -## 仕組み +## ハーネス `codewhale`（ディスパッチャー CLI）→ `codewhale-tui`（コンパニオンバイナリ）→ ratatui インターフェース ↔ 非同期エンジン ↔ OpenAI 互換のストリーミングクライアント。ツール呼び出しは型付きレジストリ（シェル、ファイル操作、Git、Web、サブエージェント、MCP、RLM）を経由してルーティングされ、結果はトランスクリプトへとストリーム返送されます。エンジンはセッション状態、ターン管理、永続タスクキューを管理し、LSP サブシステムは編集後の診断を次の推論ステップ前にモデルのコンテキストへ供給します。 diff --git a/README.md b/README.md index b5e27147..c3fd6722 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # CodeWhale -> DeepSeek-first agentic terminal for open source and open-weight coding 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 DeepSeek model and thinking level. +> The most agentic harness for DeepSeek V4. Rules, tools, evidence, and feedback loops that help the model keep working until the task is done — and keep getting better at it. [![CI](https://github.com/Hmbown/CodeWhale/actions/workflows/ci.yml/badge.svg)](https://github.com/Hmbown/CodeWhale/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/codewhale)](https://www.npmjs.com/package/codewhale) @@ -75,38 +75,35 @@ cargo install codewhale-tui --locked --force ## What Is It? -CodeWhale is a DeepSeek-first coding agent for open source and open-weight models that runs in your terminal. It can read and edit files, run shell commands, search the web, manage git, and coordinate sub-agents from a keyboard-driven TUI. +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. -It is built around DeepSeek V4 (`deepseek-v4-pro` / `deepseek-v4-flash`), including 1M-token context windows, streaming reasoning blocks, and prefix-cache-aware cost reporting. +CodeWhale is that harness, built around DeepSeek V4 Pro and Flash. It started as a personal tool because the maintainer got tired of models losing track mid-task, obeying stale instructions over the user's current request, or giving up when a command failed. What emerged was a system that keeps the model oriented: a constitutional prompt hierarchy, structured trust boundaries, parallel sub-agents, prefix-cache-aware context management, and verification beats that give the model enough signal to self-correct. -### Key Features +DeepSeek V4 helped write parts of this harness. That matters because it means CodeWhale is already the most effective way to use V4 — and as V4 improves, the harness improves with it. Each turn leaves behind better prompts, better rules, and better handoffs. The next turn starts from a stronger position. -- **Model auto-routing** — `--model auto` / `/model auto` chooses both the model and thinking level for each turn -- **Thinking-mode streaming** — see DeepSeek reasoning blocks as the model works -- **Full tool suite** — file ops, shell execution, git, web search/browse, apply-patch, sub-agents, MCP servers -- **1M-token context** — context tracking, manual or configured compaction, and prefix-cache telemetry -- **Prefix-cache stability tracking** — an optional `/statusline` footer chip surfaces how stable the cached prefix has been across recent turns so cost-busting edits are visible before they land -- **Three modes** — Plan (read-only explore), Agent (interactive with approval), YOLO (auto-approved) -- **Reasoning-effort tiers** — cycle through `off → high → max` with `Shift + Tab` -- **Session save/resume/fork** — checkpoint long-running sessions and fork saved conversations into sibling paths with parent lineage shown in the picker -- **Workspace rollback** — side-git pre/post-turn snapshots with `/restore` and `revert_turn`, without touching your repo's `.git` -- **Approval + platform sandbox controls** — Seatbelt on macOS and Landlock on Linux where available; Windows uses the same approval flow and terminal/runtime protections while OS-level filesystem isolation remains a tracked helper contract -- **Durable task queue** — background tasks can survive restarts -- **HTTP/SSE runtime API** — `codewhale serve --http` for headless agent workflows -- **MCP protocol** — connect to Model Context Protocol servers for extended tooling; please see [docs/MCP.md](docs/MCP.md) -- **Fin-powered seams** — cheap `deepseek-v4-flash` with thinking off handles routing, RLM child calls, summaries, and other fast coordination work -- **Native RLM** (`rlm_session_objects`/`rlm_open`/`rlm_eval`) — persistent REPL sessions for batched analysis with bounded helpers like `peek`, `search`, `chunk`, and `sub_query_batch`; active prompt/history objects are opened by symbolic refs instead of pasted into the parent transcript -- **LSP diagnostics** — inline error/warning surfacing after every edit via rust-analyzer, pyright, typescript-language-server, gopls, clangd -- **User memory** — optional persistent note file injected into the system prompt for cross-session preferences -- **Localized UI** — `en`, `ja`, `zh-Hans`, `pt-BR` with auto-detection -- **Live cost tracking** — per-turn and session-level token usage and cost estimates; cache hit/miss breakdown; CNY display when the session locale is `zh-Hans` -- **Skills system** — composable, installable instruction packs from GitHub; ships with a bundled starter set (`skill-creator`, `mcp-builder`, `plugin-creator`, `v4-best-practices`, `documents`, `presentations`, `spreadsheets`, `pdf`, `feishu`, `skill-installer`, `delegate`) so `/skills` is useful from first launch -- **Terminal-native notifications** — OSC 9 (iTerm2/WezTerm/Ghostty), OSC 99 (Kitty), OSC 777 (Ghostty), plus desktop notification fallback -- **Built-in theme picker** — Catppuccin, Tokyo Night, Dracula, Gruvbox alongside the original light/dark palettes; switch live with `/theme` +### How the harness works + +**Constitutional hierarchy.** The system prompt is a conflict-of-laws engine. User intent outranks stale memory. Live evidence outranks assumptions. Verification outranks confidence. Every turn inherits a clear chain of authority, so the model never has to guess which instruction to follow. + +**Structured trust.** Three modes with hard boundaries — Plan (read-only), Agent (approval-gated), YOLO (auto-approved in trusted workspaces). OS-level sandboxing backs the boundaries: Seatbelt on macOS, Landlock on Linux, Job Objects on Windows. Dangerous commands are classified and gated regardless of mode. + +**Feedback beats.** Failed commands, failing tests, LSP diagnostics — these are not dead ends. They are signals the model can tune against. A non-zero exit code is information. A type error is a correction vector. The harness makes failure legible so the model can recover without the user constantly re-steering. + +**Continuity.** Memory persists across sessions. Handoffs survive context compaction. Sessions can be saved, resumed, and forked into sibling paths. The next intelligence — human or machine — picks up where the last one left off without having to re-discover what was already learned. + +**Distributed work.** Sub-agents run concurrently, up to 20 at a time. `agent_open` returns immediately so the parent keeps working. Results arrive as structured completion events with bounded handles — no need to flood the parent context with full transcripts. See [docs/SUBAGENTS.md](docs/SUBAGENTS.md). + +**Right-size intelligence.** Fin — cheap Flash with thinking off — handles model auto-routing, RLM child calls, summaries, and coordination. Pro engages for architecture, debugging, and security review. `--model auto` selects both the model and thinking level per turn. The right amount of intelligence for each problem. + +**Long-horizon attention economics.** 1M-token context window with prefix-cache telemetry. Cache hits cost roughly 100× less than misses. A `/statusline` chip shows prefix stability in real time so you can see when a change is about to bust the cache budget. + +**Freedom with recovery.** Every turn records a side-git snapshot that doesn't touch your repo's `.git`. `/restore` and `revert_turn` roll back the workspace instantly. Dangerous operations are sandboxed at the OS level. You can let the model try things. + +The rest of the surface: **RLM sessions** (persistent Python REPL for batched analysis with `peek`, `search`, `chunk`, and `sub_query_batch` helpers), **LSP diagnostics** (inline errors from rust-analyzer, pyright, tsserver, gopls, clangd after every edit), **MCP protocol**, **HTTP/SSE runtime API**, **persistent task queue** that survives restarts, **ACP adapter** for Zed and other editors, **SWE-bench export**, **installable skills**, **theme picker**, **desktop notifications**, and **live cost tracking** with cache hit/miss breakdowns. --- -## How It's Wired +## The Harness `codewhale` (dispatcher CLI) → `codewhale-tui` (companion binary) → ratatui interface ↔ async engine ↔ OpenAI-compatible streaming client. Tool calls route through a typed registry (shell, file ops, git, web, sub-agents, MCP, RLM) and results stream back into the transcript. The engine manages session state, turn tracking, the durable task queue, and an LSP subsystem that feeds post-edit diagnostics into the model's context before the next reasoning step. @@ -210,37 +207,12 @@ codewhale --version Prebuilt binaries can also be downloaded from [GitHub Releases](https://github.com/Hmbown/CodeWhale/releases). Use `DEEPSEEK_TUI_RELEASE_BASE_URL` for mirrored release assets. -### Windows +### Windows (Scoop) -Windows x64 is a first-class release target. Use npm or direct GitHub release -downloads when you need the newest v0.8.45 binary; Cargo also works when Rust -1.88+ and the MSVC toolchain are installed. - -```powershell -npm install -g codewhale -codewhale --version - -cargo install codewhale-cli --locked --force -cargo install codewhale-tui --locked --force -``` - -Current Windows terminal behavior: - -- interactive sessions always use the TUI-owned alternate screen; the old - `--no-alt-screen` flag is accepted for script compatibility but no longer - disables the interactive alternate screen -- runtime logs stay out of the alternate-screen buffer when `RUST_LOG` or - `DEEPSEEK_LOG_LEVEL` is enabled -- mouse capture defaults on in Windows Terminal, ConEmu, and Cmder, but stays - off in legacy console hosts and JetBrains terminals; use `--mouse-capture` or - `--no-mouse-capture` to override -- mouse-wheel-as-arrow terminals keep composer history usable by routing empty - composer Up/Down to transcript scrolling where appropriate - -[Scoop](https://scoop.sh) is also supported. The `deepseek-tui` package is -listed in Scoop's main bucket, but that manifest updates independently and can -lag the GitHub/npm/Cargo release. Run `scoop update` first, then verify the -installed version with `codewhale --version`: +[Scoop](https://scoop.sh) is a Windows package manager. The `codewhale` package is listed +in Scoop's main bucket, but that manifest updates independently and can lag the +GitHub/npm/Cargo release. Run `scoop update` first, then verify the installed +version with `codewhale --version`: ```bash scoop update @@ -273,28 +245,17 @@ Both binaries are required. Cross-compilation and platform-specific notes: [docs -### Providers +### Other API Providers -CodeWhale v0.8.45 focuses on delivering the highest-quality experience on -DeepSeek first. The project's broader goal remains to become a strong harness -for open-source and open-weight coding models — additional first-class -provider paths are planned for v0.9.0. Backend provider infrastructure for -other OpenAI-compatible endpoints and self-hosted runtimes is available under -the same `--provider` flag for advanced users who need it today. +Official DeepSeek remains the default and first-class path. Other providers are +additive, with OpenRouter starting from DeepSeek Pro/Flash before broader +open-model catalogs are enabled. ```bash -# DeepSeek (default) -codewhale auth set --provider deepseek --api-key "YOUR_DEEPSEEK_API_KEY" -codewhale --provider deepseek --model deepseek-v4-pro - # NVIDIA NIM codewhale auth set --provider nvidia-nim --api-key "YOUR_NVIDIA_API_KEY" codewhale --provider nvidia-nim -# Generic OpenAI-compatible endpoint -codewhale auth set --provider openai --api-key "YOUR_OPENAI_COMPATIBLE_API_KEY" -OPENAI_BASE_URL="https://openai-compatible.example/v4" codewhale --provider openai --model deepseek-v4-pro - # AtlasCloud codewhale auth set --provider atlascloud --api-key "YOUR_ATLASCLOUD_API_KEY" codewhale --provider atlascloud @@ -315,6 +276,14 @@ codewhale --provider novita --model deepseek/deepseek-v4-pro codewhale auth set --provider fireworks --api-key "YOUR_FIREWORKS_API_KEY" codewhale --provider fireworks --model deepseek-v4-pro +# Moonshot/Kimi +codewhale auth set --provider moonshot --api-key "YOUR_MOONSHOT_OR_KIMI_API_KEY" +codewhale --provider moonshot --model kimi-k2.6 + +# Generic OpenAI-compatible endpoint +codewhale auth set --provider openai --api-key "YOUR_OPENAI_COMPATIBLE_API_KEY" +OPENAI_BASE_URL="https://openai-compatible.example/v4" codewhale --provider openai --model deepseek-v4-pro + # Self-hosted SGLang SGLANG_BASE_URL="http://localhost:30000/v1" codewhale --provider sglang --model deepseek-v4-flash @@ -489,23 +458,20 @@ Key environment variables: | Variable | Purpose | |---|---| -| `CODEWHALE_PROVIDER` | Active provider. Public alias for `DEEPSEEK_PROVIDER`; wins when both are set. | -| `CODEWHALE_MODEL` | Default model for the active provider. Public alias for `DEEPSEEK_MODEL`. | -| `CODEWHALE_BASE_URL` | Base URL for the active provider. Public alias for `DEEPSEEK_BASE_URL`. | | `DEEPSEEK_API_KEY` | API key | -| `DEEPSEEK_BASE_URL` | API base URL (legacy alias of `CODEWHALE_BASE_URL`) | +| `DEEPSEEK_BASE_URL` | API base URL | | `DEEPSEEK_HTTP_HEADERS` | Optional custom model request headers, e.g. `X-Model-Provider-Id=your-model-provider` | -| `DEEPSEEK_MODEL` | Default model (legacy alias of `CODEWHALE_MODEL`) | +| `DEEPSEEK_MODEL` | Default model | | `DEEPSEEK_STREAM_IDLE_TIMEOUT_SECS` | Stream idle timeout in seconds, default `300`, clamped to `1..=3600` | -| `DEEPSEEK_PROVIDER` | Legacy alias of `CODEWHALE_PROVIDER`. Accepts `deepseek` (default), `nvidia-nim`, `openai`, `atlascloud`, `wanjie-ark`, `openrouter`, `novita`, `fireworks`, `sglang`, `vllm`, `ollama`. | +| `DEEPSEEK_PROVIDER` | `codewhale` (default), `nvidia-nim`, `openai`, `atlascloud`, `wanjie-ark`, `openrouter`, `novita`, `fireworks`, `moonshot`, `sglang`, `vllm`, `ollama` | | `DEEPSEEK_PROFILE` | Config profile name | | `DEEPSEEK_MEMORY` | Set to `on` to enable user memory | | `DEEPSEEK_ALLOW_INSECURE_HTTP=1` | Allow non-local `http://` API base URLs on trusted networks | -| `NVIDIA_API_KEY` / `NVIDIA_NIM_API_KEY` / `OPENAI_API_KEY` / `ATLASCLOUD_API_KEY` / `WANJIE_ARK_API_KEY` / `WANJIE_API_KEY` / `WANJIE_MAAS_API_KEY` / `OPENROUTER_API_KEY` / `NOVITA_API_KEY` / `FIREWORKS_API_KEY` / `SGLANG_API_KEY` / `VLLM_API_KEY` / `OLLAMA_API_KEY` | Provider auth | -| `NVIDIA_NIM_BASE_URL` / `NIM_BASE_URL` / `NVIDIA_BASE_URL` | NVIDIA NIM endpoint override | +| `NVIDIA_API_KEY` / `OPENAI_API_KEY` / `ATLASCLOUD_API_KEY` / `WANJIE_ARK_API_KEY` / `OPENROUTER_API_KEY` / `NOVITA_API_KEY` / `FIREWORKS_API_KEY` / `MOONSHOT_API_KEY` / `KIMI_API_KEY` / `SGLANG_API_KEY` / `VLLM_API_KEY` / `OLLAMA_API_KEY` | Provider auth | | `OPENAI_BASE_URL` / `OPENAI_MODEL` | Generic OpenAI-compatible endpoint and model ID | | `ATLASCLOUD_BASE_URL` / `ATLASCLOUD_MODEL` | AtlasCloud endpoint and model override | -| `WANJIE_ARK_BASE_URL` / `WANJIE_BASE_URL` / `WANJIE_MAAS_BASE_URL` / `WANJIE_ARK_MODEL` / `WANJIE_MODEL` / `WANJIE_MAAS_MODEL` | Wanjie Ark endpoint and model override | +| `WANJIE_ARK_BASE_URL` / `WANJIE_ARK_MODEL` | Wanjie Ark endpoint and model override | +| `MOONSHOT_BASE_URL` / `KIMI_BASE_URL` / `MOONSHOT_MODEL` / `KIMI_MODEL` | Moonshot/Kimi endpoint and model override | | `OPENROUTER_BASE_URL` | OpenRouter endpoint override | | `NOVITA_BASE_URL` | Novita endpoint override | | `FIREWORKS_BASE_URL` | Fireworks endpoint override | @@ -635,8 +601,8 @@ This project ships with help from a growing community of contributors: - **[zichen0116](https://github.com/zichen0116)** — CODE_OF_CONDUCT.md (#686) - **[dfwqdyl-ui](https://github.com/dfwqdyl-ui)** — model ID case-sensitivity compatibility report (#729) - **[Oliver-ZPLiu](https://github.com/Oliver-ZPLiu)** — stale `working...` state bug report, Windows clipboard fallback, MCP Streamable HTTP session fixes, and Homebrew tap automation (#738, #850, #1643, #1631) -- **[reidliu41](https://github.com/reidliu41)** — resume hint, workspace trust persistence, Ollama provider support, thinking-block stream finalization, CI cache hardening, streaming wrap, DeepSeek model completions, help picker selection polish, and transcript user-message highlighting (#863, #870, #921, #1078, #1603, #1628, #1601, #1964, #1995) -- **[cyq1017](https://github.com/cyq1017)** — Unicode `git_status` paths, local/configured skill discovery, and mode-switch toast dedupe (#1953, #1956, #1957) +- **[reidliu41](https://github.com/reidliu41)** — resume hint, workspace trust persistence, Ollama provider support, thinking-block stream finalization, CI cache hardening, streaming wrap, DeepSeek model completions, help picker selection polish, transcript user-message highlighting, approval one-step confirmation flow, and model-picker Esc-selection fix (#863, #870, #921, #1078, #1603, #1628, #1601, #1964, #1995, #2143, #2056) +- **[cyq1017](https://github.com/cyq1017)** — Unicode `git_status` paths, local/configured skill discovery, mode-switch toast dedupe, sub-agent completion handoff compatibility, and goal-prompt actionability (#1953, #1956, #1957, #2057, #2120, #2097) - **[xieshutao](https://github.com/xieshutao)** — plain Markdown skill fallback (#869) - **[GK012](https://github.com/GK012)** — npm wrapper `--version` fallback (#885) - **[y0sif](https://github.com/y0sif)** — parent turn-loop wakeup after direct child sub-agent completion (#901) @@ -647,7 +613,7 @@ This project ships with help from a growing community of contributors: - **[chnjames](https://github.com/chnjames)** — cached @mention completions, config recovery polish, and Windows UTF-8 shell output (#849, #927, #982, #1018) - **[angziii](https://github.com/angziii)** — config safety, async cleanup, Docker hardening, and command-safety fixes (#822, #824, #827, #831, #833, #835, #837) - **[elowen53](https://github.com/elowen53)** — UTF-8 decoding and deterministic test coverage (#825, #840) -- **[wdw8276](https://github.com/wdw8276)** — `/rename` command for custom session titles (#836) +- **[wdw8276](https://github.com/wdw8276)** — `/rename` command for custom session titles and composer session-title display fix (#836, #2108) - **[banqii](https://github.com/banqii)** — `.cursor/skills` discovery path support (#817) - **[junskyeed](https://github.com/junskyeed)** — dynamic `max_tokens` calculation for API requests (#826) - **Hafeez Pizofreude** — SSRF protection in `fetch_url` and Star History chart @@ -668,11 +634,11 @@ This project ships with help from a growing community of contributors: - **[mdrkrg](https://github.com/mdrkrg)** — first-run onboarding crash fix when the API key is missing (#1598) - **[Aitensa](https://github.com/Aitensa)** — CJK wrapping propagation for diff and pager output (#1622) - **[qiyan233](https://github.com/qiyan233)** — legacy DeepSeek CN provider alias compatibility (#1645) -- **[zlh124](https://github.com/zlh124)** — WSL2/headless startup report, clipboard-init fix, and YAML block-scalar frontmatter parsing (#1772, #1773, #1908) +- **[zlh124](https://github.com/zlh124)** — WSL2/headless startup report, clipboard-init fix, and YAML block-scalar frontmatter parsing (#1772, #1773, #1908, #1907) - **[aboimpinto](https://github.com/aboimpinto)** — Windows alt-screen logging, Home/End composer, and runtime log follow-ups (#1774, #1776, #1748, #1749, #1782, #1783) - **[LeoLin990405](https://github.com/LeoLin990405)** — provider model passthrough, reasoning replay, thinking-only turn, and Windows quoting fixes (#1740, #1743, #1742, #1744) - **[nightt5879](https://github.com/nightt5879)** — Ctrl+C prompt restore fix (#1764) -- **[h3c-hexin](https://github.com/h3c-hexin)** — streaming batch tool-call preservation and CLI reasoning-effort passthrough (#1686, #1511) +- **[h3c-hexin](https://github.com/h3c-hexin)** — streaming batch tool-call preservation, CLI reasoning-effort passthrough, sub-agent completion handoff compatibility, and self-hosted context budgeting (#1686, #1511, #2057, #2120, #2060) - **[hxy91819](https://github.com/hxy91819)** — prefix-cache preservation during tool-result pruning (#1514) - **[JiarenWang](https://github.com/JiarenWang)** — Plan-mode read-only enforcement, approval-takeover clamping, Ctrl+H delete fix, and undo context sync (#1123, #962, #958, #1150) - **[Liu-Vince](https://github.com/Liu-Vince)** — MCP pagination, markdown indentation preservation, zh-Hans i18n polish, and env-var documentation (#1256, #1179, #1274, #1178) @@ -738,7 +704,8 @@ This project ships with help from a growing community of contributors: - **[xulongzhe](https://github.com/xulongzhe)** — issue-template and vision-boundary follow-ups (#1530, #1544) - **[YaYII](https://github.com/YaYII)** — trusted media path work (#1462) - **[47Cid](https://github.com/47Cid)** and **[Jafar Akhondali](https://github.com/JafarAkhondali)** — responsible security disclosures and hardening reports -- **[gaord](https://github.com/gaord)** — approval-remember live-turn sync fix (#2041) +- **[gaord](https://github.com/gaord)** — approval-remember live-turn sync fix and user-message transcript highlighting (#2041, #2047) +- **[idling11](https://github.com/idling11)** — readable `/restore` snapshot labels and sidebar hover tooltips (#2111, #2110) --- diff --git a/README.zh-CN.md b/README.zh-CN.md index 97fd11eb..2087f223 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,6 +1,6 @@ # CodeWhale -> **DeepSeek 优先、面向开源与开放权重编码模型的终端原生编程智能体：100 万 token 上下文、思考模式流式推理、前缀缓存感知。自包含 Rust 二进制发布——开箱即带 MCP 客户端、沙箱和持久化任务队列。** +> **DeepSeek V4 的最强智能体运行框架。规则、工具、证据和反馈循环——帮助模型持续工作直到任务完成，并且越用越好。** [![CI](https://github.com/Hmbown/CodeWhale/actions/workflows/ci.yml/badge.svg)](https://github.com/Hmbown/CodeWhale/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/codewhale)](https://www.npmjs.com/package/codewhale) @@ -70,37 +70,35 @@ cargo install codewhale-tui --locked --force ## 这是什么？ -codewhale 是一个完全运行在终端里的编程智能体。它让 DeepSeek 前沿模型直接访问你的工作区：读写文件、运行 shell 命令、搜索浏览网页、管理 git、调度子智能体——全部通过快速、键盘驱动的 TUI 完成。 +模型回答问题。智能体完成任务。区别在于运行框架——包围模型的规则、工具、证据和反馈循环。 -它面向 **DeepSeek V4**（`deepseek-v4-pro` / `deepseek-v4-flash`）构建，原生支持 100 万 token 上下文窗口和思考模式流式输出。 +CodeWhale 就是这套框架，围绕 DeepSeek V4 Pro 和 Flash 构建。它最初是一个个人工具，因为维护者受够了模型在任务中途迷失方向、服从过时指令而非用户当前请求、或者命令失败就放弃。结果诞生了一个让模型保持方向的系统：宪政提示层级、结构化信任边界、并行子智能体、前缀缓存感知的上下文管理、以及让模型有足够信号来自我校正的验证节拍。 -### 主要功能 +DeepSeek V4 参与了这套框架的部分编写。这很重要——它意味着 CodeWhale 已经是使用 V4 最有效的方式，并且随着 V4 的改进，框架也会随之改进。每一轮都留下更好的提示、更好的规则、更好的交接。下一轮从一个更强的位置开始。 -- **模型自动路由** —— `--model auto` / `/model auto` 每轮自动选择模型和推理强度 -- **Fin 快速通道** —— 使用关闭思考的低成本 `deepseek-v4-flash` 承担路由、RLM 子调用、摘要和协调工作 -- **原生 RLM**（`rlm_open`/`rlm_eval`）—— 持久化 REPL 会话用于批量分析；使用带界面的辅助函数（`peek`、`search`、`chunk`、`sub_query_batch`） -- **思考模式流式输出** —— 实时观察模型在解决问题时的思维链展开 -- **完整工具集** —— 文件操作、shell 执行、git、网页搜索/浏览、apply-patch、子智能体、MCP 服务器 -- **100 万 token 上下文** —— 上下文跟踪、手动或配置驱动的压缩，以及前缀缓存遥测 -- **前缀缓存稳定性跟踪** —— 可选 `/statusline` footer chip 显示最近轮次缓存前缀的稳定程度 -- **三种交互模式** —— Plan（只读探索）、Agent（带审批的默认交互）、YOLO（可信工作区自动批准） -- **推理强度档位** —— 用 `Shift+Tab` 在 `off → high → max` 之间切换 -- **会话保存和恢复** —— 长任务的断点续作 -- **工作区回滚** —— 通过 side-git 记录每轮前后快照，支持 `/restore` 和 `revert_turn`，不影响项目自己的 `.git` -- **持久化任务队列** —— 后台任务在重启后仍然存在，支持计划任务和长时间运行的操作 -- **HTTP/SSE 运行时 API** —— `codewhale serve --http` 用于无界面智能体流程 -- **MCP 协议** —— 连接 Model Context Protocol 服务器扩展工具，见 [docs/MCP.md](docs/MCP.md) -- **LSP 诊断** —— 每次编辑后通过 rust-analyzer、pyright、typescript-language-server、gopls、clangd 提供内联错误/警告 -- **用户记忆** —— 可选的持久化笔记文件注入系统提示，实现跨会话偏好保持 -- **多语言 UI** —— 支持 `en`、`ja`、`zh-Hans`、`pt-BR`，支持自动检测 -- **实时成本跟踪** —— 按轮次和会话统计 token 用量与成本估算，含缓存命中/未命中明细；简体中文 locale 下显示 CNY -- **技能系统** —— 可通过 GitHub 安装的组合式指令包；首次启动自带 `skill-creator`、`mcp-builder`、`documents`、`presentations`、`spreadsheets`、`pdf`、`feishu` 等 starter skills -- **终端原生通知** —— OSC 9、OSC 99、OSC 777，以及桌面通知兜底 -- **内置主题选择器** —— Catppuccin、Tokyo Night、Dracula、Gruvbox 和原有亮/暗色主题，可用 `/theme` 实时切换 +### 框架如何工作 + +**宪政层级。** 系统提示词是一个冲突法引擎。用户意图优先于陈旧记忆。实时证据优先于假设。验证优先于自信。每一轮继承清晰的权威链，模型永远不需要猜测该服从哪条指令。 + +**结构化信任。** 三种模式，硬边界——Plan（只读）、Agent（审批门控）、YOLO（可信工作区自动批准）。OS 级沙箱支撑边界：macOS 的 Seatbelt、Linux 的 Landlock、Windows 的 Job Objects。危险命令无论在哪种模式下都被分类和门控。 + +**反馈节拍。** 失败的命令、失败的测试、LSP 诊断——这些不是死胡同。它们是模型可以调谐的信号。非零退出码是信息。类型错误是修正向量。框架让失败变得可读，模型可以在用户不必不断重新掌舵的情况下恢复。 + +**连续性。** 记忆跨会话持久化。交接在上下文压缩后存活。会话可以保存、恢复和分叉到兄弟路径。下一位智能体——人或机器——从上一位置继续，无需重新发现已经学到的东西。 + +**分布式工作。** 子智能体并发运行，一次最多 20 个。`agent_open` 立即返回，父进程继续工作。结果以结构化完成事件形式到达，带有有界句柄——无需用完整对话记录淹没父上下文。详见 [docs/SUBAGENTS.md](docs/SUBAGENTS.md)。 + +**适度智能。** Fin——关闭思考的廉价 Flash——处理模型自动路由、RLM 子调用、摘要和协调。Pro 用于架构、调试和安全审查。`--model auto` 每轮选择模型和思考强度。每个问题匹配恰当的智能量。 + +**长程注意力经济学。** 100 万 token 上下文窗口，前缀缓存遥测。缓存命中比未命中便宜约 100 倍。`/statusline` 芯片实时显示前缀稳定性，让你能看到某次变更是否即将破坏缓存预算。 + +**自由与恢复。** 每轮记录 side-git 快照，不影响仓库 `.git`。`/restore` 和 `revert_turn` 即刻回滚工作区。危险操作在 OS 级沙箱化。你可以让模型放手尝试。 + +其余功能面：**RLM 会话**（持久化 Python REPL，配合 `peek`、`search`、`chunk`、`sub_query_batch` 辅助函数进行批量分析）、**LSP 诊断**（每次编辑后 rust-analyzer、pyright、tsserver、gopls、clangd 的内联错误）、**MCP 协议**、**HTTP/SSE 运行时 API**、重启后仍存活的**持久化任务队列**、Zed 等编辑器的 **ACP 适配器**、**SWE-bench 导出**、**可安装技能**、**主题选择器**、**桌面通知**、以及带缓存命中/未命中明细的**实时成本追踪**。 --- -## 架构说明 +## 运行框架 `codewhale`（调度器 CLI）→ `codewhale-tui`（伴随二进制）→ ratatui 界面 ↔ 异步引擎 ↔ OpenAI 兼容流式客户端。工具调用通过类型化注册表（shell、文件操作、git、web、子智能体、MCP、RLM）路由，结果流式返回对话记录。引擎管理会话状态、轮次追踪、持久化任务队列和 LSP 子系统——它在下一步推理前将编辑后诊断反馈到模型上下文中。 diff --git a/web/app/[locale]/docs/page.tsx b/web/app/[locale]/docs/page.tsx index 5a639add..cfe384b5 100644 --- a/web/app/[locale]/docs/page.tsx +++ b/web/app/[locale]/docs/page.tsx @@ -121,7 +121,7 @@ export default async function DocsPage({ params }: { params: Promise<{ locale: s { group: "Git / 诊断 / 测试", tools: "git_status · git_diff · diagnostics · run_tests" }, { group: "子 Agent", tools: "agent_open · agent_eval · agent_close —— 持久会话，并行执行，通过 var_handle 读取大结果" }, { group: "递归 LM (RLM)", tools: "rlm_open · rlm_eval · rlm_configure · rlm_close —— 沙箱 Python REPL，内置 peek/search/chunk/sub_query_batch 等辅助函数" }, - { group: "MCP", tools: "mcp__——从 ~/.deepseek/mcp.json 自动注册" }, + { group: "MCP", tools: "mcp__——从 ~/.codewhale/mcp.json 自动注册" }, ].map((row) => (
{row.group}
@@ -152,8 +152,8 @@ export default async function DocsPage({ params }: { params: Promise<{ locale: s ))}

- 沙箱：{facts.sandboxBackends.join("、")}。Windows 当前不宣称 OS 级文件系统沙箱，但保留同样的审批、工作区边界和终端运行时保护。 - /trust 可解除工作区边界限制。 + 沙箱：{facts.sandboxBackends.join("、")}。工作区边界默认为 --workspace。 + /trust 可解除边界限制。

@@ -163,7 +163,7 @@ export default async function DocsPage({ params }: { params: Promise<{ locale: s 配置 Configuration 
-{`# ~/.deepseek/config.toml
+{`# ~/.codewhale/config.toml
 api_key = "sk-..."
 base_url = "https://api.deepseek.com"
 default_text_model = "${facts.defaultModel ?? "deepseek-v4-pro"}"  # 默认模型；deepseek-v4-flash 用于快速 / 子智能体
@@ -179,7 +179,7 @@ default_timeout_secs = 30
 
 [[hooks.hooks]]
 event = "session_start"                     # 也支持: tool_call_before / tool_call_after
-command = "~/.deepseek/hooks/pre.sh"         # / message_submit / mode_change / on_error / shell_env`}
+command = "~/.codewhale/hooks/pre.sh"        # / message_submit / mode_change / on_error / shell_env`}

完整参考：config.example.toml。 @@ -193,7 +193,7 @@ command = "~/.deepseek/hooks/pre.sh" # / message_submit / mode_change /

codewhale 双向支持模型上下文协议（Model Context Protocol）：作为客户端从 - ~/.deepseek/mcp.json 加载服务器，同时也可作为服务器暴露工具 + ~/.codewhale/mcp.json 加载服务器，同时也可作为服务器暴露工具 （codewhale mcp）。工具以 mcp_<server>_<tool> 形式呈现。 

@@ -218,7 +218,7 @@ command = "~/.deepseek/hooks/pre.sh"         # / message_submit / mode_change /
                   技能 Skills
                 
                 

-                  技能是 ~/.deepseek/skills/<name>/ 下的一个文件夹，
+                  技能是 ~/.codewhale/skills/<name>/ 下的一个文件夹，
                   根目录包含 SKILL.md。Agent 启动时加载技能名称和描述，
                   在需要时通过 Skill 工具拉取完整内容。
                 

@@ -253,7 +253,7 @@ command = "~/.deepseek/hooks/pre.sh"         # / message_submit / mode_change /
                 

                   使用 codewhale auth set --provider <id> 切换。下表为
                   crates/tui/src/config.rs 中 ApiProvider 枚举的实时投影
-                  ，v0.8.45 当前共 {facts.providers.length} 个。
+                  ，目前共 {facts.providers.length} 个。
                 

                 

                   {facts.providers.map((p) => (
@@ -265,13 +265,9 @@ command = "~/.deepseek/hooks/pre.sh"         # / message_submit / mode_change /
                   ))}
                 

                 

-                  开放模型平台方向：CodeWhale 保持 DeepSeek 优先，同时内置 Moonshot/Kimi、OpenRouter、NVIDIA NIM、
-                  AtlasCloud、Wanjie Ark、Novita、Fireworks 和自托管 SGLang/vLLM/Ollama 路径。
-                  Kimi Code 会员 API Key 使用 providers.moonshot.base_url
-                  指向 https://api.kimi.com/coding/v1，模型为
-                  kimi-for-coding；Kimi/Moonshot 平台 API Key 继续使用
-                  https://api.moonshot.ai/v1 和
-                  kimi-k2.6。
+                  开放模型平台方向：CodeWhale 正在扩展对
+                   OpenRouter、 Hugging Face 和 自托管 模型的支持，
+                  为您提供完全自主的模型选择——从云端 API 到本地部署均可覆盖。
                 

               
 
@@ -377,7 +373,7 @@ command = "~/.deepseek/hooks/pre.sh"         # / message_submit / mode_change /
                     { group: "Git / diag / test", tools: "git_status · git_diff · diagnostics · run_tests" },
                     { group: "Sub-agents", tools: "agent_open · agent_eval · agent_close — persistent sessions, parallel execution, bounded result retrieval via var_handle" },
                     { group: "Recursive LM (RLM)", tools: "rlm_open · rlm_eval · rlm_configure · rlm_close — sandboxed Python REPL with peek/search/chunk/sub_query_batch helpers" },
-                    { group: "MCP", tools: "mcp__ — auto-registered from ~/.deepseek/mcp.json" },
+                    { group: "MCP", tools: "mcp__ — auto-registered from ~/.codewhale/mcp.json" },
                   ].map((row) => (
                     

                       
{row.group}

@@ -407,9 +403,8 @@ command = "~/.deepseek/hooks/pre.sh"         # / message_submit / mode_change /
                   ))}
                 

                 

-                  Sandbox: {facts.sandboxBackends.join(", ")}. On Windows, CodeWhale does not advertise
-                  OS-level filesystem isolation yet, but keeps the same approvals, workspace boundary,
-                  and terminal runtime protections. /trust lifts the workspace boundary.
+                  Sandbox: {facts.sandboxBackends.join(", ")}. Workspace boundary defaults to{" "}
+                  --workspace. /trust lifts the boundary.
                 

               
 
@@ -418,7 +413,7 @@ command = "~/.deepseek/hooks/pre.sh"         # / message_submit / mode_change /
                   Configuration 配置
                 
                 
-{`# ~/.deepseek/config.toml
+{`# ~/.codewhale/config.toml
 api_key = "sk-..."
 base_url = "https://api.deepseek.com"
 default_text_model = "${facts.defaultModel ?? "deepseek-v4-pro"}"  # default; deepseek-v4-flash is the fast / sub-agent option
@@ -434,7 +429,7 @@ default_timeout_secs = 30
 
 [[hooks.hooks]]
 event = "session_start"                     # or: tool_call_before / tool_call_after
-command = "~/.deepseek/hooks/pre.sh"         # / message_submit / mode_change / on_error / shell_env`}
+command = "~/.codewhale/hooks/pre.sh"        # / message_submit / mode_change / on_error / shell_env`}
                 

                 

                   Full reference: config.example.toml.
@@ -447,7 +442,7 @@ command = "~/.deepseek/hooks/pre.sh"         # / message_submit / mode_change /
                 
                 

                   codewhale speaks the Model Context Protocol both ways: as a client (loads
-                  servers from ~/.deepseek/mcp.json) and as a server
+                  servers from ~/.codewhale/mcp.json) and as a server
                   (codewhale mcp). Tools surface as mcp_<server>_<tool>.
                 

                 
@@ -471,7 +466,7 @@ command = "~/.deepseek/hooks/pre.sh"         # / message_submit / mode_change /
                   Skills 技能
                 
                 

-                  A skill is a folder under ~/.deepseek/skills/<name>/
+                  A skill is a folder under ~/.codewhale/skills/<name>/
                   with a SKILL.md at the root. The agent loads skill names + descriptions on
                   startup and can pull in the full body via the Skill tool when relevant.
                 

@@ -505,7 +500,7 @@ command = "~/.deepseek/hooks/pre.sh"         # / message_submit / mode_change /
                 

                   Switch with codewhale auth set --provider <id>. The
                   table below is a live projection of the ApiProvider enum
-                  in crates/tui/src/config.rs — v0.8.45 currently has {facts.providers.length} providers.
+                  in crates/tui/src/config.rs — currently {facts.providers.length} providers.
                 

                 

                   {facts.providers.map((p) => (
@@ -517,14 +512,9 @@ command = "~/.deepseek/hooks/pre.sh"         # / message_submit / mode_change /
                   ))}
                 

                 

-                  Open-model platform direction: CodeWhale stays DeepSeek-first while shipping Moonshot/Kimi,
-                  OpenRouter, NVIDIA NIM, AtlasCloud, Wanjie Ark, Novita, Fireworks, and self-hosted
-                  SGLang/vLLM/Ollama paths.
-                  Kimi Code membership API keys use providers.moonshot.base_url
-                  set to https://api.kimi.com/coding/v1 with
-                  kimi-for-coding; Kimi/Moonshot Platform API keys use
-                  https://api.moonshot.ai/v1 with
-                  kimi-k2.6.
+                  Open-model platform direction: CodeWhale is expanding support for
+                   OpenRouter,  Hugging Face, and  self-hosted models,
+                  giving you full sovereignty over model choice — from cloud APIs to local deployments.
                 

               
 
@@ -557,4 +547,4 @@ command = "~/.deepseek/hooks/pre.sh"         # / message_submit / mode_change /
       )}
     
   );
-}
+}
\ No newline at end of file
diff --git a/web/app/[locale]/faq/page.tsx b/web/app/[locale]/faq/page.tsx
index 2d9db748..f216552a 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; v0.8.45 also ships Moonshot/Kimi, OpenRouter, NVIDIA NIM, OpenAI-compatible, AtlasCloud, Wanjie Ark, Novita, Fireworks, SGLang, vLLM, and Ollama paths.
+        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.
       
     ),
     sources: ["README.md", "docs/ARCHITECTURE.md"],
@@ -112,13 +112,12 @@ codewhale doctor         # full connectivity check`}
         
CodeWhale ships with these built-in providers:

         
    
           
  • DeepSeek — first-class, native API. Reasoning streaming, cache metrics, thinking effort control.
    • 
-          
  • Moonshot/Kimi — Kimi Code and Kimi/Moonshot Platform API-key modes.
    • 
           
  • OpenRouter — unified API for DeepSeek models and more.
    • 
-          
  • OpenAI-compatible, NVIDIA NIM, AtlasCloud, Wanjie Ark, Novita, Fireworks, SGLang, vLLM, Ollama
    • 
+          
  • OpenAI, NVIDIA NIM, Novita, Fireworks, sglang, vLLM, Ollama
    • 
         

         

           Set the corresponding env var (e.g. OPENROUTER_API_KEY) and your provider in ~/.deepseek/config.toml.
-          SGLang, vLLM, and Ollama can also run against self-hosted OpenAI-compatible endpoints.
+          Hugging Face, ZenMux, and self-hosted OpenAI-compatible endpoints are on the roadmap.
         

       
     ),
@@ -157,7 +156,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.
-        Direct Hugging Face TGI discovery remains roadmap work.
+        Full Hugging Face TGI/vLLM integration is on the roadmap.
       
     ),
     sources: ["#574", "#1303", "docs/CONFIGURATION.md"],
@@ -212,7 +211,7 @@ default_text_model = "openrouter/deepseek/deepseek-v4-pro"`}
     a: (
       <>
         CodeWhale runs entirely on your machine. No telemetry, no cloud processing of your code.
-        Sandbox backends: seatbelt (macOS), landlock (Linux). Windows keeps the same approval and terminal runtime protections, but does not advertise OS-level filesystem isolation yet.
+        Sandbox backends: seatbelt (macOS), landlock (Linux), restricted tokens (Windows).
         Workspace boundaries default to --workspace. /trust lifts them.
         Approval mode is configurable per session. All credential/approval/elevation events are written to ~/.deepseek/audit.log.
       
@@ -337,7 +336,7 @@ const faqZh: FaqItem[] = [
     q: "CodeWhale 是什么？",
     a: (
       <>
-        CodeWhale 是一个面向开源模型的终端原生编程智能体。通过 codewhale 命令启动，流式输出推理块，在有审批门槛的情况下编辑本地工作区，并可为每个回合自动选择最合适的模型和推理深度。DeepSeek V4 是一级模型路径；v0.8.45 也内置 Moonshot/Kimi、OpenRouter、NVIDIA NIM、OpenAI 兼容、AtlasCloud、Wanjie Ark、Novita、Fireworks、SGLang、vLLM 和 Ollama 路径。
+        CodeWhale 是一个面向开源模型的终端原生编程智能体。通过 codewhale 命令启动，流式输出推理块，在有审批门槛的情况下编辑本地工作区，并可为每个回合自动选择最合适的模型和推理深度。DeepSeek V4 是一级模型路径；OpenRouter 已就绪。Hugging Face、自托管等开放模型接口已在路线图中。
       
     ),
     sources: ["README.md", "docs/ARCHITECTURE.md"],
@@ -425,13 +424,12 @@ codewhale doctor         # 完整连接检查`}
         
CodeWhale 内建以下提供商：

         
    
           
  • DeepSeek — 一级支持，原生 API。推理流、缓存指标、思考力度控制。
    • 
-          
  • Moonshot/Kimi — Kimi Code 与 Kimi/Moonshot 平台 API key 模式。
    • 
           
  • OpenRouter — 统一 API，可访问 DeepSeek 等模型。
    • 
-          
  • OpenAI 兼容、NVIDIA NIM、AtlasCloud、Wanjie Ark、Novita、Fireworks、SGLang、vLLM、Ollama
    • 
+          
  • OpenAI、NVIDIA NIM、Novita、Fireworks、sglang、vLLM、Ollama
    • 
         

         

           设置对应的环境变量（如 OPENROUTER_API_KEY）并在 ~/.deepseek/config.toml 中配置你的提供商。
-          SGLang、vLLM 和 Ollama 也可以连接自托管 OpenAI 兼容端点。
+          Hugging Face、ZenMux 和自托管 OpenAI 兼容端点正在路线图中。
         

       
     ),
@@ -470,7 +468,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 的直接发现仍在路线图中。
+        完整的 Hugging Face TGI/vLLM 集成正在路线图中。
       
     ),
     sources: ["#574", "#1303", "docs/CONFIGURATION.md"],
@@ -525,7 +523,7 @@ default_text_model = "openrouter/deepseek/deepseek-v4-pro"`}
     a: (
       <>
         CodeWhale 完全在你的机器上运行。无遥测，不会将你的代码上传到云端处理。
-        沙箱后端：seatbelt（macOS）、landlock（Linux）。Windows 保留同样的审批与终端运行时保护，但当前不宣称 OS 级文件系统沙箱。
+        沙箱后端：seatbelt（macOS）、landlock（Linux）、受限令牌（Windows）。
         工作区边界默认为 --workspace。/trust 可解除边界。
         审批模式可按会话配置。所有凭证/审批/提权事件写入 ~/.deepseek/audit.log。
       
diff --git a/web/app/[locale]/page.tsx b/web/app/[locale]/page.tsx
index 2c999f39..3a7672ac 100644
--- a/web/app/[locale]/page.tsx
+++ b/web/app/[locale]/page.tsx
@@ -15,7 +15,7 @@ const FALLBACK_STATS: RepoStats = {
   forks: 0,
   openIssues: 0,
   openPulls: 0,
-  contributors: 99,
+  contributors: 98,
   fetchedAt: new Date().toISOString(),
 };
 
@@ -87,15 +87,15 @@ export default async function HomePage({ params }: { params: Promise<{ locale: s
 
             

               {isZh
-                ? "面向开源模型的终端编程智能体。"
-                : "The terminal coding agent for open models."}
+                ? "DeepSeek V4 的最强智能体运行框架。"
+                : "The most agentic harness for DeepSeek V4."}
             

 
             

               CodeWhale
               {isZh
-                ? " 是面向 DeepSeek V4 及其他开放权重模型的终端原生编程智能体。它读改文件、跑测试、调用 MCP 服务器，并通过审批、工作区边界和平台沙箱控制风险。"
-                : " is a terminal-native coding agent for DeepSeek V4 and other open-weight models. It reads and edits files, runs tests, calls MCP servers, and controls risk through approvals, workspace boundaries, and platform sandboxes."}
+                ? " 是围绕 DeepSeek V4 Pro 和 Flash 构建的运行框架。规则、工具、证据和反馈循环——帮助模型持续工作，并且不断进步。DeepSeek V4 参与了部分编写。更好的框架让 V4 更有效，更有效的 V4 又让框架变得更好——这是个正向循环。"
+                : " is a harness built around DeepSeek V4 Pro and Flash. Rules, tools, evidence, and feedback loops that help the model keep working — and keep improving. DeepSeek V4 helped write parts of it. A better harness makes V4 more effective, and a more effective V4 makes the harness better — it loops."}
             

 
             

@@ -155,7 +155,7 @@ export default async function HomePage({ params }: { params: Promise<{ locale: s
                 )}
               

               

-                {isZh ? "Linux / macOS / Windows x64" : "Linux / macOS / Windows x64"}
+                {isZh ? "需要 Node 或 Rust 1.88+" : "needs Node or Rust 1.88+"}
                 {isZh ? "其他方式 →" : "other ways →"}
               

             
@@ -178,48 +178,48 @@ export default async function HomePage({ params }: { params: Promise<{ locale: s
           {isZh ? (
             <>
               

-                
01 · 终端智能体

-                
编程智能体，不是聊天框

+                
01 · 宪政层级

+                
用户意图高于一切

                 

-                  与 Claude Code、Codex CLI 相同的循环：读、改、跑测试、回报。键盘驱动，住在终端里。
+                  实时证据高于假设。验证高于自信。清晰的权威链让模型无需猜测该服从哪条指令。
                 

               

               

-                
02 · 开源模型优先

-                
DeepSeek V4 深度集成

+                
02 · 反馈驱动

+                
失败是信号，不是终点

                 

-                  原生 DeepSeek API：推理流、缓存指标、思考力度控制。Moonshot/Kimi、OpenRouter、NVIDIA NIM、vLLM、SGLang 等同时可选。
+                  失败的命令、失败的测试、LSP 错误。框架让失败可读。每一次节拍都是模型可以调谐的信息，逐轮迭代。
                 

               

               

-                
03 · 沙箱边界

-                
Plan、Agent、YOLO

+                
03 · 自我修正

+                
恢复内建于环境

                 

-                  Plan 只读；Agent 风险操作前确认；YOLO 全自动。macOS 使用 seatbelt，Linux 使用 landlock；Windows 保留同样的审批与终端保护。
+                  子智能体、回滚、会话分叉、交接。模型不需要一次就全对。恢复机制从底层支持试错。
                 

               

             
           ) : (
             <>
               

-                
01 · terminal agent

-                
A coding agent, not a chat box

+                
01 · constitutional

+                
User intent above everything

                 

-                  Same loop as Claude Code or Codex CLI: reads, edits, runs tests, reports back. Keyboard-driven, lives in your terminal.
+                  Live evidence above assumptions. Verification above confidence. A clear chain of authority so the model never guesses which instruction to follow.
                 

               

               

-                
02 · open models first

-                
DeepSeek V4, deeply integrated

+                
02 · feedback-driven

+                
Failure is signal, not a dead end

                 

-                  Native DeepSeek API: reasoning streaming, cache metrics, thinking-effort control. Moonshot/Kimi, OpenRouter, NVIDIA NIM, vLLM, and SGLang are also supported.
+                  Failed commands, failing tests, LSP errors. The harness makes failure legible. Each beat is information the model can tune against, turn after turn.
                 

               

               

-                
03 · controlled

-                
Plan, Agent, YOLO

+                
03 · self-correcting

+                
Recovery built into the environment

                 

-                  Plan reads only. Agent asks before risky ops. YOLO auto-approves. macOS uses seatbelt, Linux uses landlock; Windows keeps the same approval and terminal protections.
+                  Sub-agents, rollback, session forks, handoffs. The model doesn't have to get everything right the first time. Recovery is built into the environment.
                 

               

             
@@ -260,6 +260,11 @@ export default async function HomePage({ params }: { params: Promise<{ locale: s
                   ? "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."}
               

+              

+                {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."}
+              

               

                 
                   {isZh ? "运行提示词 →" : "Run the prompt →"}
@@ -325,7 +330,7 @@ export default async function HomePage({ params }: { params: Promise<{ locale: s
     B -->|tool call| T["read_file · edit_file · grep
apply_patch · exec_shell
mcp_<server>_<tool>"]
     T -->|approval Y/N| P["审批对话框
approval dialog"]
     P --> B
-    T -->|exec| S["平台控制
seatbelt · landlock · approvals"]
+    T -->|exec| S["沙箱
seatbelt · landlock · win32"]
     classDef accent fill:#e9eefe,stroke:#0e0e10,stroke-width:1px;
     classDef api fill:#0e0e10,stroke:#0e0e10,color:#ffffff;
     class C api;
@@ -337,7 +342,7 @@ export default async function HomePage({ params }: { params: Promise<{ locale: s
     B -->|tool call| T["read_file · edit_file · grep
apply_patch · exec_shell
mcp_<server>_<tool>"]
     T -->|approval Y/N| P["Approval
dialog"]
     P --> B
-    T -->|exec| S["Platform controls
seatbelt · landlock · approvals"]
+    T -->|exec| S["Sandbox
seatbelt · landlock · win32"]
     classDef accent fill:#e9eefe,stroke:#0e0e10,stroke-width:1px;
     classDef api fill:#0e0e10,stroke:#0e0e10,color:#ffffff;
     class C api;
diff --git a/web/app/[locale]/roadmap/page.tsx b/web/app/[locale]/roadmap/page.tsx
index 3bcc5a46..17e382bb 100644
--- a/web/app/[locale]/roadmap/page.tsx
+++ b/web/app/[locale]/roadmap/page.tsx
@@ -26,12 +26,12 @@ const tracksEn = [
       { title: "Sub-agent parallel execution", note: "agent_open / agent_eval / agent_close; up to 10 concurrent sessions with bounded result handles" },
       { title: "RLM batched processing", note: "Persistent sandboxed Python REPL with 1–16 cheap parallel children for long-input analysis" },
       { title: "Three operating modes", note: "Plan (read-only), Agent (default), YOLO (auto-approved); orthogonal suggest / auto / never approval" },
-      { title: "Per-platform controls", note: "seatbelt (macOS), landlock (Linux); Windows keeps approvals and terminal/runtime protections while OS sandbox work remains tracked" },
+      { title: "Per-platform sandbox", note: "seatbelt (macOS), landlock (Linux); Windows containment via restricted tokens (limited)" },
       { title: "Durable sessions + tasks", note: "Save, resume, rollback; background task queue with replayable timelines under ~/.deepseek/tasks/" },
-      { title: "Bidirectional MCP", note: "Consume tools from external servers; expose as server via `codewhale mcp`; ~/.deepseek/mcp.json" },
+      { title: "Bidirectional MCP", note: "Consume tools from external servers; expose as server via `deepseek mcp`; ~/.deepseek/mcp.json" },
       { title: "Skills + unified slash palette", note: "~/.deepseek/skills/ auto-loading; /help, /mode, /status, /config, /trust, /feedback" },
-      { title: "v0.8.45 provider surface", note: "DeepSeek, NVIDIA NIM, OpenAI-compatible, AtlasCloud, Wanjie Ark, OpenRouter, Novita, Fireworks, Moonshot/Kimi, SGLang, vLLM, and Ollama" },
-      { title: "Moonshot/Kimi API-key setup", note: "Kimi Code plan and Kimi/Moonshot Platform API-key paths for Moonshot/Kimi sessions" },
+      { title: "OpenRouter provider", note: "First-class OpenRouter integration with 300+ models across dozens of providers" },
+      { title: "Multi-provider support", note: "Hot-swap between providers (DeepSeek, OpenAI, Anthropic, OpenRouter) per session" },
     ],
   },
   {
@@ -43,8 +43,8 @@ const tracksEn = [
       { title: "Memory typed store", note: "SQLite + FTS5 backend with graph-structured agent memory and multi-signal recall (#534–#536)" },
       { title: "Feishu / Lark bot", note: "Chat-platform frontend over the existing runtime API (#757)" },
       { title: "Chinese-market & i18n", note: "Locale-aware UI, platform refinements, region-specific search backends (#755)" },
-      { title: "Model Lab", note: "Curated model discovery and benchmarking for open-weight and self-hosted workflows" },
-      { title: "Provider billing and catalogs", note: "/balance capability layer plus richer live model catalogs for providers that expose listing endpoints" },
+      { title: "Hugging Face model discovery + Model Lab", note: "Browse, download, and manage models from Hugging Face Hub directly in the TUI" },
+      { title: "ZenMux / OpenAI-compatible providers", note: "Bring any OpenAI-compatible endpoint (vLLM, LiteLLM, Ollama, local) as a first-class provider" },
     ],
   },
   {
@@ -92,12 +92,12 @@ const tracksZh = [
       { title: "子 Agent 并行执行", note: "agent_open / agent_eval / agent_close；最多 10 个并发会话，通过 var_handle 有界读取结果" },
       { title: "RLM 批量处理", note: "持久沙箱 Python REPL，支持 1–16 路廉价并行子调用，处理长文本分析" },
       { title: "三种运行模式", note: "Plan（只读）、Agent（默认）、YOLO（自动批准）；审批模式正交（建议/自动/拒绝）" },
-      { title: "跨平台控制", note: "seatbelt（macOS）、landlock（Linux）；Windows 保留审批与终端运行时保护，OS 沙箱仍在跟踪中" },
+      { title: "跨平台沙箱", note: "seatbelt（macOS）、landlock（Linux）；Windows 通过受限令牌实现基础隔离（功能有限）" },
       { title: "持久化会话 + 后台任务", note: "保存、恢复、回滚；后台任务队列，可回放时间线，位于 ~/.deepseek/tasks/" },
-      { title: "双向 MCP 协议", note: "消费外部服务器工具；通过 `codewhale mcp` 暴露为服务器；~/.deepseek/mcp.json" },
+      { title: "双向 MCP 协议", note: "消费外部服务器工具；通过 `deepseek mcp` 暴露为服务器；~/.deepseek/mcp.json" },
       { title: "技能 + 统一命令面板", note: "~/.deepseek/skills/ 自动加载；/help、/mode、/status、/config、/trust、/feedback" },
-      { title: "v0.8.45 提供商表面", note: "DeepSeek、NVIDIA NIM、OpenAI 兼容、AtlasCloud、Wanjie Ark、OpenRouter、Novita、Fireworks、Moonshot/Kimi、SGLang、vLLM、Ollama" },
-      { title: "Moonshot/Kimi API-key 设置", note: "Kimi Code 会员与 Kimi/Moonshot 平台 API key 路径" },
+      { title: "OpenRouter 提供商", note: "原生集成 OpenRouter，支持 300+ 模型，覆盖数十个提供商" },
+      { title: "多提供商支持", note: "按会话动态切换提供商（DeepSeek、OpenAI、Anthropic、OpenRouter）" },
     ],
   },
   {
@@ -109,8 +109,8 @@ const tracksZh = [
       { title: "记忆类型化存储", note: "SQLite + FTS5 后端，图结构 Agent 记忆，多信号召回（#534–#536）" },
       { title: "飞书 / Lark 机器人", note: "基于现有 runtime API 的聊天平台前端（#757）" },
       { title: "中国市场与国际化改进", note: "本地化 UI、平台优化、区域搜索引擎（#755）" },
-      { title: "模型实验室", note: "面向开放权重和自托管工作流的模型发现与基准测试" },
-      { title: "提供商账单与目录", note: "/balance 能力层，以及对支持列表接口的提供商提供更完整的实时模型目录" },
+      { title: "Hugging Face 模型发现 + 模型实验室", note: "在 TUI 中直接浏览、下载和管理 Hugging Face Hub 上的模型" },
+      { title: "ZenMux / OpenAI 兼容提供商", note: "将任意 OpenAI 兼容端点（vLLM、LiteLLM、Ollama、本地模型）作为一级提供商接入" },
     ],
   },
   {
@@ -339,4 +339,4 @@ export default async function RoadmapPage({ params }: { params: Promise<{ locale
       )}
     
   );
-}
+}
\ No newline at end of file
diff --git a/web/app/layout.tsx b/web/app/layout.tsx
index 9dfc2ab7..214aceef 100644
--- a/web/app/layout.tsx
+++ b/web/app/layout.tsx
@@ -33,13 +33,13 @@ const cjk = Noto_Serif_SC({
 });
 
 export const metadata: Metadata = {
-  title: "CodeWhale · 深度求索 终端",
+  title: "CodeWhale · DeepSeek V4 智能体运行框架",
   description:
-    "Terminal-native coding agent for open-source and open-weight models across providers. DeepSeek V4 is first-class. Community site for installation, docs, roadmap, and live activity.",
+    "The most agentic harness for DeepSeek V4. Constitutional hierarchy, structured trust, verification, and recovery — rules, tools, and feedback loops that help the model keep working.",
   metadataBase: new URL("https://codewhale.net"),
   openGraph: {
     title: "CodeWhale",
-    description: "Terminal-native coding agent for open-source and open-weight models across providers.",
+    description: "The most agentic harness for DeepSeek V4. Constitutional hierarchy, structured trust, verification, and recovery.",
     url: "https://codewhale.net",
     siteName: "CodeWhale",
     type: "website",
diff --git a/website/index.html b/website/index.html
index 39351284..8cbf59cb 100644
--- a/website/index.html
+++ b/website/index.html
@@ -3,7 +3,7 @@
 
   
   
-  DeepSeek TUI — Terminal-native coding agent
+  CodeWhale — The most agentic harness for DeepSeek V4