From 94c1959a235ccb3b038212fa5929b2bca9fc39f8 Mon Sep 17 00:00:00 2001
From: Shizuku <2163018547@qq.com>
Date: Tue, 25 Aug 2026 19:16:17 +0800
Subject: [PATCH 1/4] docs: fix doc inaccuracies found in zh_hans review
---
docs/AGENT_RUNTIME.md | 2 ++
docs/CHANGELOG_ARCHIVE.md | 2 +-
docs/CONFIGURATION.md | 2 +-
docs/FLEET.md | 2 ++
docs/GUIDE.md | 4 +++-
docs/HOOKS.md | 7 ++++---
docs/INSTALL.md | 2 ++
docs/KEYBINDINGS.md | 2 ++
docs/MCP.md | 2 ++
docs/MODES.md | 2 ++
docs/PROVIDERS.md | 8 +++++---
docs/SKILLS.md | 2 ++
docs/SUBAGENTS.md | 2 ++
docs/TELEMETRY.md | 2 ++
docs/TOOL_LIFECYCLE.md | 2 ++
15 files changed, 34 insertions(+), 9 deletions(-)
diff --git a/docs/AGENT_RUNTIME.md b/docs/AGENT_RUNTIME.md
index 79c421c536..27bf9320e6 100644
--- a/docs/AGENT_RUNTIME.md
+++ b/docs/AGENT_RUNTIME.md
@@ -1,5 +1,7 @@
# The CodeWhale Agent Runtime — one durable substrate, familiar launchers
+> 阅读简体中文版：[zh_hans/AGENT_RUNTIME.md](zh_hans/AGENT_RUNTIME.md)
+
This document explains how sub-agents, the headless `exec` path, Agent Fleet,
and Runtime relate. These concepts had drifted into *two* parallel "worker"
systems. The fix is to make the **Runtime worker run** the durable execution
diff --git a/docs/CHANGELOG_ARCHIVE.md b/docs/CHANGELOG_ARCHIVE.md
index a6b0b7d871..9e3c01827c 100644
--- a/docs/CHANGELOG_ARCHIVE.md
+++ b/docs/CHANGELOG_ARCHIVE.md
@@ -3431,7 +3431,7 @@ Welcome — and thank you.
unsupported platforms don't fail the whole `npm install`.
### Docs
-- New [`docs/INSTALL.md`](docs/INSTALL.md) — every supported platform,
+- New [`INSTALL.md`](INSTALL.md) — every supported platform,
prebuilt vs. `cargo install` vs. manual download, cross-compiling x64 → ARM64
Linux with `cross` or `gcc-aarch64-linux-gnu`, and a troubleshooting section
covering the common `Unsupported architecture`, `MISSING_COMPANION_BINARY`,
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index a492397343..944f8ebf57 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -1787,7 +1787,7 @@ If you are upgrading from older releases:
- `reasoning_stream_style` (string, optional provider-table key): override how streaming reasoning is separated from answer text for the active provider route. Use `separate_field` for `reasoning_content` / `reasoning` deltas, `inline_tags` for gateways that stream `...` inside `delta.content`, or `none` to render incoming content exactly as answer text.
- `[providers..auth]` (table, optional): provider-scoped auth source metadata. `source = "command"` stores a command argv plus optional `timeout_ms`; `source = "secret"` stores a `secret_id`. This slice lets provider readiness, `/provider`, and doctor JSON report the auth source class without exposing command argv output or secret values; executing commands and resolving external secret material is handled by the follow-up resolver work.
- `insecure_skip_tls_verify` (bool, optional provider-table key): legacy compatibility key, disabled by default. When true on the active provider table, provider clients reject the configuration instead of skipping TLS certificate verification. Use `SSL_CERT_FILE` for corporate or private CA bundles; `codewhale doctor` reports stale uses of this setting.
-- `default_text_model` (string, optional): defaults to `deepseek-v4-pro` for DeepSeek and `deepseek-anthropic`, `gpt-5.6` for OpenAI, `grok-4.6` for xAI, `deepseek-ai/deepseek-v4-pro` for NVIDIA NIM, `deepseek-ai/deepseek-v4-flash` for AtlasCloud, `deepseek-reasoner` for Wanjie Ark, `DeepSeek-V4-Pro` for Volcengine Ark, `deepseek/deepseek-v4-pro` for OpenRouter and Novita, `mimo-v2.5-pro` for Xiaomi MiMo, `accounts/fireworks/models/deepseek-v4-pro` for Fireworks, `deepseek-ai/DeepSeek-V4-Pro` for SiliconFlow and DeepInfra, `trinity-large-thinking` for Arcee AI, `kimi-k2.7-code` for Moonshot, `MiniMax-M3` for MiniMax, `GLM-5.3` for Z.ai, `step-3.7-flash` for StepFun, `ernie-4.0-turbo-8k` for Qianfan, `fugu` for Sakana AI, `deepseek-ai/DeepSeek-V4-Pro` for SGLang/vLLM, `deepseek-coder:1.3b` for local Ollama, and `gpt-oss:120b` for Ollama Cloud. Hugging Face and Together AI both default to `deepseek-ai/DeepSeek-V4-Pro`; `openai-codex` defaults to `gpt-5.6`; `anthropic` defaults to `claude-sonnet-4-6`; `openmodel` defaults to `deepseek-v4-flash`. Current public DeepSeek IDs are `deepseek-v4-pro` and `deepseek-v4-flash`, both with 1M context windows, 384K max output, and thinking mode enabled by default. DeepSeek's live pricing/model page now labels the Pro backend `DeepSeek-V4-Pro-0813`; the callable API ID remains `deepseek-v4-pro`, so Codewhale does not send the backend label or the Claude Code-specific `deepseek-v4-pro[1m]` selector. DeepSeek retires `deepseek-chat` and `deepseek-reasoner` on July 24, 2026; direct first-party routes migrate both to `deepseek-v4-flash`, with omitted reasoning settings preserving their former non-thinking (`off`) and thinking (`high`) intent. Explicit `reasoning_effort` wins, and provider-owned ids on Wanjie Ark, aggregators, self-hosted runtimes, and custom endpoints are not globally rewritten. SiliconFlow retains its own mapping: `deepseek-reasoner` and `deepseek-r1` select its Pro model while `deepseek-chat` and `deepseek-v3` select Flash. Provider-specific mappings translate `deepseek-v4-pro` / `deepseek-v4-flash` to each provider's model ID where supported. OpenRouter also recognizes recent large IDs such as `arcee-ai/trinity-large-thinking`, `minimax/minimax-m3`, `minimax/minimax-m2.7`, `xiaomi/mimo-v2.5-pro`, `qwen/qwen3.6-flash`, `qwen/qwen3.6-35b-a3b`, `qwen/qwen3.6-max-preview`, `qwen/qwen3.6-27b`, `qwen/qwen3.6-plus`, `qwen/qwen3.7-max`, `google/gemma-4-31b-it`, `moonshotai/kimi-k2.7-code`, `moonshotai/kimi-k2.6`, `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free`, and `nvidia/nemotron-3-ultra-550b-a55b`; direct Arcee uses bare IDs such as `trinity-large-thinking` and `trinity-large-preview`; direct Moonshot recognizes `kimi-k3`, `kimi-k2.7-code`, and `kimi-k2.6`. The exact Kimi Code endpoint recognizes bare `k3` for K3 and `kimi-for-coding` for K2.7; those membership IDs are distinct from the direct Moonshot IDs and are never rewritten across routes. Direct MiniMax recognizes `MiniMax-M3` and the documented M2.x chat model IDs; direct Z.ai recognizes `GLM-5.3` (the default), `GLM-5.2`, `GLM-5.1`, and `GLM-5-Turbo`, and OpenRouter recognizes the matching `z-ai/glm-5.1`, `z-ai/glm-5.2`, `z-ai/glm-5.3`, and `z-ai/glm-5-turbo` IDs — `GLM-5.3` has been live on the Z.ai Coding Plan since 2026-08-13; it inherits its catalog metadata from `GLM-5.2` until Z.ai publishes distinct 5.3 numbers and carries no price, and an explicit `GLM-5.2` selection keeps its own id; direct Sakana recognizes `fugu` and `fugu-ultra-20260615`; direct Xiaomi MiMo recognizes chat IDs `mimo-v2.5-pro`, `mimo-v2.5-pro-ultraspeed`, and `mimo-v2.5`, while TTS IDs are selected through `codewhale speech` / `tts`. Generic `openai`, `atlascloud`, `wanjie-ark`, `xiaomi-mimo`, `arcee`, `moonshot`, `minimax`, `openmodel`, `zai`, `stepfun`, `qianfan`, `sakana`, local Ollama, and Ollama Cloud model IDs are passed through unchanged after known aliases are normalized. OpenRouter and SiliconFlow provider configs with a custom `base_url` also preserve explicit model values, which lets OpenAI-compatible gateways accept bare model IDs. Use `/models` or `codewhale models` to discover live IDs from your configured endpoint. `CODEWHALE_MODEL` overrides this for a single process; `DEEPSEEK_MODEL` is the legacy alias.
+- `default_text_model` (string, optional): defaults to `deepseek-v4-pro` for DeepSeek and `deepseek-anthropic`, `gpt-5.6` for OpenAI, `grok-4.6` for xAI, `deepseek-ai/deepseek-v4-pro` for NVIDIA NIM, `deepseek-ai/deepseek-v4-flash` for AtlasCloud, `deepseek-reasoner` for Wanjie Ark, `DeepSeek-V4-Pro` for Volcengine Ark, `deepseek/deepseek-v4-pro` for OpenRouter and Novita, `mimo-v2.5-pro` for Xiaomi MiMo, `accounts/fireworks/models/deepseek-v4-pro` for Fireworks, `deepseek-ai/DeepSeek-V4-Pro` for SiliconFlow and DeepInfra, `trinity-large-thinking` for Arcee AI, `kimi-k2.7-code` for Moonshot, `MiniMax-M3` for MiniMax, `GLM-5.3` for Z.ai, `step-3.7-flash` for StepFun, `ernie-4.0-turbo-8k` for Qianfan, `fugu` for Sakana AI, `deepseek-ai/DeepSeek-V4-Pro` for SGLang/vLLM, `deepseek-v4-flash` for local Ollama, and `gpt-oss:120b` for Ollama Cloud. Hugging Face and Together AI both default to `deepseek-ai/DeepSeek-V4-Pro`; `openai-codex` defaults to `gpt-5.6`; `anthropic` defaults to `claude-sonnet-4-6`; `openmodel` defaults to `deepseek-v4-flash`. Current public DeepSeek IDs are `deepseek-v4-pro` and `deepseek-v4-flash`, both with 1M context windows, 384K max output, and thinking mode enabled by default. DeepSeek's live pricing/model page now labels the Pro backend `DeepSeek-V4-Pro-0813`; the callable API ID remains `deepseek-v4-pro`, so Codewhale does not send the backend label or the Claude Code-specific `deepseek-v4-pro[1m]` selector. DeepSeek retires `deepseek-chat` and `deepseek-reasoner` on July 24, 2026; direct first-party routes migrate both to `deepseek-v4-flash`, with omitted reasoning settings preserving their former non-thinking (`off`) and thinking (`high`) intent. Explicit `reasoning_effort` wins, and provider-owned ids on Wanjie Ark, aggregators, self-hosted runtimes, and custom endpoints are not globally rewritten. SiliconFlow retains its own mapping: `deepseek-reasoner` and `deepseek-r1` select its Pro model while `deepseek-chat` and `deepseek-v3` select Flash. Provider-specific mappings translate `deepseek-v4-pro` / `deepseek-v4-flash` to each provider's model ID where supported. OpenRouter also recognizes recent large IDs such as `arcee-ai/trinity-large-thinking`, `minimax/minimax-m3`, `minimax/minimax-m2.7`, `xiaomi/mimo-v2.5-pro`, `qwen/qwen3.6-flash`, `qwen/qwen3.6-35b-a3b`, `qwen/qwen3.6-max-preview`, `qwen/qwen3.6-27b`, `qwen/qwen3.6-plus`, `qwen/qwen3.7-max`, `google/gemma-4-31b-it`, `moonshotai/kimi-k2.7-code`, `moonshotai/kimi-k2.6`, `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free`, and `nvidia/nemotron-3-ultra-550b-a55b`; direct Arcee uses bare IDs such as `trinity-large-thinking` and `trinity-large-preview`; direct Moonshot recognizes `kimi-k3`, `kimi-k2.7-code`, and `kimi-k2.6`. The exact Kimi Code endpoint recognizes bare `k3` for K3 and `kimi-for-coding` for K2.7; those membership IDs are distinct from the direct Moonshot IDs and are never rewritten across routes. Direct MiniMax recognizes `MiniMax-M3` and the documented M2.x chat model IDs; direct Z.ai recognizes `GLM-5.3` (the default), `GLM-5.2`, `GLM-5.1`, and `GLM-5-Turbo`, and OpenRouter recognizes the matching `z-ai/glm-5.1`, `z-ai/glm-5.2`, `z-ai/glm-5.3`, and `z-ai/glm-5-turbo` IDs — `GLM-5.3` has been live on the Z.ai Coding Plan since 2026-08-13; it inherits its catalog metadata from `GLM-5.2` until Z.ai publishes distinct 5.3 numbers and carries no price, and an explicit `GLM-5.2` selection keeps its own id; direct Sakana recognizes `fugu` and `fugu-ultra-20260615`; direct Xiaomi MiMo recognizes chat IDs `mimo-v2.5-pro`, `mimo-v2.5-pro-ultraspeed`, and `mimo-v2.5`, while TTS IDs are selected through `codewhale speech` / `tts`. Generic `openai`, `atlascloud`, `wanjie-ark`, `xiaomi-mimo`, `arcee`, `moonshot`, `minimax`, `openmodel`, `zai`, `stepfun`, `qianfan`, `sakana`, local Ollama, and Ollama Cloud model IDs are passed through unchanged after known aliases are normalized. OpenRouter and SiliconFlow provider configs with a custom `base_url` also preserve explicit model values, which lets OpenAI-compatible gateways accept bare model IDs. Use `/models` or `codewhale models` to discover live IDs from your configured endpoint. `CODEWHALE_MODEL` overrides this for a single process; `DEEPSEEK_MODEL` is the legacy alias.
- TelecomJS uses `deepseek-v4-pro` only as a conservative pre-refresh fallback. Once its key-scoped `/models` catalog is available, the picker uses those live rows; Codewhale omits unsupported reasoning request fields on this route.
- `reasoning_effort` (string, optional): `off`, `low`, `medium`, `high`, `max`, `xhigh`, or `ultracode`; defaults to the configured UI tier. DeepSeek Platform receives top-level `thinking` / `reasoning_effort` fields. Ollama Cloud's OpenAI-compatible Chat Completions route preserves its documented `none` / `low` / `medium` / `high` / `max` ladder (`off` is sent as `none`; `xhigh` and `ultracode` normalize to `max`). Direct xAI `grok-4.6` on exact `https://api.x.ai/v1` receives top-level `reasoning_effort = "low" | "medium" | "high" | "xhigh"`; `off` normalizes to `high`, `max`/`ultracode` to `xhigh`, and `auto` leaves the field omitted so xAI's documented default `high` applies. A custom xAI-compatible `base_url` does not inherit that dialect. Direct Moonshot `kimi-k3` on exact `https://api.moonshot.ai/v1` is always-thinking and receives only top-level `reasoning_effort = "low" | "high" | "max"`; `off` normalizes to `low`, and `medium` to `high`. Kimi Code membership `k3` on exact `https://api.kimi.com/coding/v1` instead receives nested `thinking.effort`, and its `off` setting also normalizes to enabled `low`. Normal dispatched `auto` uses Codewhale's auto-reasoning selector and sends a concrete route-normalized tier; only an omitted reasoning setting leaves the provider default in control. Neighboring gateways and model/endpoint combinations retain the generic Moonshot contract. OpenAI Codex normalizes stale `off` to `low` and sends `max` / `ultracode` as Responses `xhigh`. Z.ai receives documented `thinking` controls and treats enabled thinking as the GLM coding high/max lane. NVIDIA NIM receives equivalent settings through `chat_template_kwargs`.
- `verbosity` (string, optional): `normal` or `concise`. `normal` keeps the
diff --git a/docs/FLEET.md b/docs/FLEET.md
index 243528e339..526f185ad2 100644
--- a/docs/FLEET.md
+++ b/docs/FLEET.md
@@ -1,5 +1,7 @@
# Agent Fleet
+> 阅读简体中文版：[zh_hans/FLEET.md](zh_hans/FLEET.md)
+
Agent Fleet is the local-first roster and member-selection layer for durable
multi-worker runs. It does not execute or authorize work. After Fleet resolves
who should participate, the delegated coordinator launches a headless
diff --git a/docs/GUIDE.md b/docs/GUIDE.md
index 2fd7e51fe1..64421d7155 100644
--- a/docs/GUIDE.md
+++ b/docs/GUIDE.md
@@ -46,7 +46,9 @@ runtime model.
## 2. First Launch
Install Codewhale with the path that fits your machine. Release installers
-provide the same runtime under the `codewhale` and `codew` command names.
+provide the same runtime under the `codewhale` and `codew` command names, and
+every supported install path ships the `codewhale` dispatcher with the
+`codewhale-tui` runtime built in.
```bash
# npm
diff --git a/docs/HOOKS.md b/docs/HOOKS.md
index 6d465e8e2d..91dfa9b04e 100644
--- a/docs/HOOKS.md
+++ b/docs/HOOKS.md
@@ -1,4 +1,5 @@
# Hooks
+> 阅读简体中文版：[zh_hans/HOOKS.md](zh_hans/HOOKS.md)
Hooks run a shell command when the Codewhale **TUI** reaches a lifecycle
point. They are plain processes: they receive context through environment
@@ -166,7 +167,7 @@ configured instead (the backend owns its base environment, and your
| `{ type = "all", conditions = [...] }` | every nested condition | every event |
| `{ type = "any", conditions = [...] }` | at least one nested condition | every event |
-Two rules keep conditions from lying:
+Three rules keep conditions from lying:
- **`exit_code` needs a real exit code.** It matches only when the event
actually observed a process exit code — `tool_call_after`, or `on_error` for
@@ -405,8 +406,8 @@ aborted".
Codewhale's ambient environment. Its environment is built as:
1. a sanitized fixed allowlist of parent variables — `PATH`, `HOME`, `USER`,
- `LANG` and the other `LC_*`/locale entries, `TERM`, `SHELL`, `TMPDIR`, the
- Windows system and MSVC toolchain entries — and nothing else. Variables
+ `LANG` and the other `LC_*`/locale entries, `TERM`, `SHELL`, `TMPDIR`,
+ proxy variables, color/terminal entries such as `NO_COLOR`, `CARGO_HOME`/`RUSTUP_HOME`/`RUSTUP_TOOLCHAIN`, the Windows system and MSVC toolchain entries, and other platform keys (the full list lives in `crates/tui/src/child_env.rs`) — and nothing else. Variables
outside that allowlist, including anything that looks like a secret, are
dropped;
2. then the `KEY=VALUE` pairs your `shell_env` hooks produced, applied on top.
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index e85073010c..c9b22c1789 100644
--- a/docs/INSTALL.md
+++ b/docs/INSTALL.md
@@ -1,5 +1,7 @@
# Installing Codewhale
+> 阅读简体中文版：[zh_hans/INSTALL.md](zh_hans/INSTALL.md)
+
This page covers every supported install path and the most common
"it didn't install" failures, including **Linux ARM64** and other less
common platforms.
diff --git a/docs/KEYBINDINGS.md b/docs/KEYBINDINGS.md
index e32bc75fca..098a2fd913 100644
--- a/docs/KEYBINDINGS.md
+++ b/docs/KEYBINDINGS.md
@@ -1,5 +1,7 @@
# Keybindings
+> 阅读简体中文版：[zh_hans/KEYBINDINGS.md](zh_hans/KEYBINDINGS.md)
+
This is the source-of-truth catalog of every keyboard shortcut the TUI recognizes. Bindings are grouped by **context** — the focus or modal state they fire in. A binding listed under "Composer" only takes effect when the composer is focused; one under "Transcript" only when the transcript has focus; and so on.
Global key chords are not yet user-configurable — tracked for a future release (#436, #437). Hotbar slot actions are configurable with `[[hotbar]]` and `/hotbar`; the Hotbar activation chord remains `Alt-1` through `Alt-8`.
diff --git a/docs/MCP.md b/docs/MCP.md
index 031e45109a..c1147c2acb 100644
--- a/docs/MCP.md
+++ b/docs/MCP.md
@@ -1,5 +1,7 @@
# MCP (External Tool Servers)
+> 阅读简体中文版：[zh_hans/MCP.md](zh_hans/MCP.md)
+
codewhale can load additional tools via MCP (Model Context Protocol). MCP servers can be local stdio processes that the TUI starts, or remote URL-based servers that speak Streamable HTTP with legacy SSE fallback.
Browsing note:
diff --git a/docs/MODES.md b/docs/MODES.md
index 0296b6b89a..95392f634d 100644
--- a/docs/MODES.md
+++ b/docs/MODES.md
@@ -1,5 +1,7 @@
# Modes and Permission Postures
+> 阅读简体中文版：[zh_hans/MODES.md](zh_hans/MODES.md)
+
Codewhale has three related concepts:
- **TUI mode**: what kind of visible interaction you're in (Plan/Work/Operate).
diff --git a/docs/PROVIDERS.md b/docs/PROVIDERS.md
index 24b7fc300f..4973b9cf3d 100644
--- a/docs/PROVIDERS.md
+++ b/docs/PROVIDERS.md
@@ -1,5 +1,7 @@
# Provider Registry
+> 阅读简体中文版：[zh_hans/PROVIDERS.md](zh_hans/PROVIDERS.md)
+
This registry describes provider behavior that is wired into the current
Codewhale codebase. It is intentionally conservative: shipped entries are
limited to provider IDs, config keys, auth paths, base URLs, model resolution,
@@ -324,7 +326,7 @@ table.
| Runner | Default base URL | Default model | Base URL override |
| --- | --- | --- | --- |
-| `ollama` | `http://localhost:11434/v1` | `deepseek-coder:1.3b` | `OLLAMA_BASE_URL` |
+| `ollama` | `http://localhost:11434/v1` | `deepseek-v4-flash` | `OLLAMA_BASE_URL` |
| `vllm` | `http://localhost:8000/v1` | `deepseek-ai/DeepSeek-V4-Pro` | `VLLM_BASE_URL` |
| `sglang` | `http://localhost:30000/v1` | `deepseek-ai/DeepSeek-V4-Pro` | `SGLANG_BASE_URL` |
@@ -585,7 +587,7 @@ overlay and lets DSH resolve its own keys.
| `minimax-anthropic` | `[providers.minimax_anthropic]` | `MINIMAX_API_KEY` | `MINIMAX_ANTHROPIC_BASE_URL`; default `https://api.minimax.io/anthropic`; China `https://api.minimaxi.com/anthropic` | `MiniMax-M3`, `MiniMax-M2.7` | MiniMax direct Anthropic-compatible Messages route. Keep the `/anthropic` suffix because Codewhale appends `/v1/messages`; the route uses `x-api-key`. M3 supports adaptive or disabled thinking. M2.7 always keeps thinking enabled. |
| `sglang` | `[providers.sglang]` | Optional `SGLANG_API_KEY` | `SGLANG_BASE_URL`; default `http://localhost:30000/v1` | `deepseek-ai/DeepSeek-V4-Pro`, `deepseek-ai/DeepSeek-V4-Flash` | Self-hosted OpenAI-compatible route. Localhost deployments commonly omit auth. `SGLANG_MODEL` is accepted. |
| `vllm` | `[providers.vllm]` | Optional `VLLM_API_KEY` | `VLLM_BASE_URL`; default `http://localhost:8000/v1` | `deepseek-ai/DeepSeek-V4-Pro`, `deepseek-ai/DeepSeek-V4-Flash` | Self-hosted vLLM OpenAI-compatible route. Localhost deployments commonly omit auth. `VLLM_MODEL` is accepted. |
-| `ollama` | `[providers.ollama]` | Local optional `OLLAMA_API_KEY` | `OLLAMA_BASE_URL`; default `http://localhost:11434/v1` | `deepseek-coder:1.3b`; provider-hinted custom tags pass through | Local Ollama is keyless by default. `OLLAMA_MODEL` is accepted. |
+| `ollama` | `[providers.ollama]` | Local optional `OLLAMA_API_KEY` | `OLLAMA_BASE_URL`; default `http://localhost:11434/v1` | `deepseek-v4-flash`; provider-hinted custom tags pass through | Local Ollama is keyless by default. `OLLAMA_MODEL` is accepted. |
| `ollama-cloud` | `[providers.ollama_cloud]` | `OLLAMA_CLOUD_API_KEY`, then `OLLAMA_API_KEY` | `OLLAMA_CLOUD_BASE_URL`; default `https://ollama.com/v1` | `gpt-oss:120b`; arbitrary provider-owned IDs pass through | Hosted OpenAI-compatible `/v1/chat/completions` route. Save credentials under `ollama-cloud`; the exact released `ollama` + Cloud URL tuple has bounded read-only in-memory compatibility with its legacy table and secret slot. `OLLAMA_CLOUD_MODEL` is accepted. |
| `huggingface` | `[providers.huggingface]` | `HUGGINGFACE_API_KEY`, `HF_TOKEN` | `HUGGINGFACE_BASE_URL`, `HF_BASE_URL`; default `https://router.huggingface.co/v1` | `deepseek-ai/DeepSeek-V4-Pro`, `deepseek-ai/DeepSeek-V4-Flash` | Hugging Face Inference Providers OpenAI-compatible router route. Accepted aliases: `huggingface`, `hugging-face`, `hugging_face`, `hf`. Org-prefixed model IDs pass through. `HUGGINGFACE_MODEL` and `HF_MODEL` are accepted. Hub browsing/export are separate future features. |
| `deepinfra` | `[providers.deepinfra]` | `DEEPINFRA_API_KEY`, `DEEPINFRA_TOKEN` | `DEEPINFRA_BASE_URL`; default `https://api.deepinfra.com/v1/openai` | `deepseek-ai/DeepSeek-V4-Pro`, `deepseek-ai/DeepSeek-V4-Flash` | DeepInfra OpenAI-compatible route. Drop-in replacement for OpenAI SDK. |
@@ -775,7 +777,7 @@ endpoint when the endpoint supports model listing.
| `minimax-anthropic` | `MiniMax-M3`, `MiniMax-M2.7` | yes | yes |
| `sglang` | `deepseek-ai/DeepSeek-V4-Pro`, `deepseek-ai/DeepSeek-V4-Flash` | yes | yes |
| `vllm` | `deepseek-ai/DeepSeek-V4-Pro`, `deepseek-ai/DeepSeek-V4-Flash` | yes | yes |
-| `ollama` | `deepseek-coder:1.3b`; custom tags pass through when provider hint is `ollama` | yes | no |
+| `ollama` | `deepseek-v4-flash`; custom tags pass through when provider hint is `ollama` | yes | no |
| `ollama-cloud` | `gpt-oss:120b`; arbitrary provider-owned model IDs pass through | yes | yes |
| `huggingface` | `deepseek-ai/DeepSeek-V4-Pro`, `deepseek-ai/DeepSeek-V4-Flash` | yes | no |
| `deepinfra` | `deepseek-ai/DeepSeek-V4-Pro`, `deepseek-ai/DeepSeek-V4-Flash` | yes | yes |
diff --git a/docs/SKILLS.md b/docs/SKILLS.md
index 501548255d..831a2d7518 100644
--- a/docs/SKILLS.md
+++ b/docs/SKILLS.md
@@ -1,5 +1,7 @@
# Skills Manager
+> 阅读简体中文版：[zh_hans/SKILLS.md](zh_hans/SKILLS.md)
+
Skills are reusable `SKILL.md` instruction packs. Codewhale discovers them from
several roots, but **only CodeWhale-owned directories are writable**. The unified
`/skills` manager is the interactive surface for audit and mutation; slash
diff --git a/docs/SUBAGENTS.md b/docs/SUBAGENTS.md
index fc7360e3c4..efaf749d8a 100644
--- a/docs/SUBAGENTS.md
+++ b/docs/SUBAGENTS.md
@@ -1,5 +1,7 @@
# Fleet Workers and Sub-Agent Compatibility
+> 阅读简体中文版：[zh_hans/SUBAGENTS.md](zh_hans/SUBAGENTS.md)
+
Fleet roles are the user-facing vocabulary for delegated work: a parent
launches a focused `worker`, `scout`, `planner`, `reviewer`, `builder`,
`verifier`, or `consultant` through `agent` and gets back an `agent_id` plus transcript handle
diff --git a/docs/TELEMETRY.md b/docs/TELEMETRY.md
index 791036a37e..f09e90897f 100644
--- a/docs/TELEMETRY.md
+++ b/docs/TELEMETRY.md
@@ -1,5 +1,7 @@
# Codewhale product telemetry
+> 阅读简体中文版：[zh_hans/TELEMETRY.md](zh_hans/TELEMETRY.md)
+
**Status for 0.9.11: anonymous usage counting is on by default and can be
disabled immediately.** The first interactive launch shows one localized,
nonblocking notice after the terminal is ready. It says what is never collected,
diff --git a/docs/TOOL_LIFECYCLE.md b/docs/TOOL_LIFECYCLE.md
index d00cd6eebe..0ee9adaa8e 100644
--- a/docs/TOOL_LIFECYCLE.md
+++ b/docs/TOOL_LIFECYCLE.md
@@ -1,5 +1,7 @@
# Historical Tool-Surface Lifecycle Policy (v0.8.53)
+> 阅读简体中文版：[zh_hans/TOOL_LIFECYCLE.md](zh_hans/TOOL_LIFECYCLE.md)
+
**Status:** Historical design record, not current runtime documentation. The
v0.9.1 canonical action surface and replay-only alias contract are documented in
[`RUNTIME_SIMPLIFICATION_DESIGN.md`](RUNTIME_SIMPLIFICATION_DESIGN.md) and
From 712e7bdab96ec9efea28d987663550d60c7f69b1 Mon Sep 17 00:00:00 2001
From: Shizuku <2163018547@qq.com>
Date: Tue, 25 Aug 2026 19:21:56 +0800
Subject: [PATCH 2/4] docs: add zh_hans translation for INSTALL
---
docs/zh_hans/INSTALL.md | 853 ++++++++++++++++++++++++++++++++++++++++
1 file changed, 853 insertions(+)
create mode 100644 docs/zh_hans/INSTALL.md
diff --git a/docs/zh_hans/INSTALL.md b/docs/zh_hans/INSTALL.md
new file mode 100644
index 0000000000..6a35df0fd5
--- /dev/null
+++ b/docs/zh_hans/INSTALL.md
@@ -0,0 +1,853 @@
+# 安装 Codewhale
+
+> 本文翻译自英文版 [INSTALL.md](../INSTALL.md)，与英文修订 `1563ce351`（2026-08-18）同步。
+
+本文涵盖所有受支持的安装方式，以及最常见的"没装上"失败场景，包括 **Linux ARM64** 和其他不太常见的平台。
+
+如果你只想看精简的版本，请看[主 README](../../README.md#install) 或[简体中文 README](../../README.zh-CN.md#安装)。
+
+本分支描述的是 **v0.9.11 源码候选版**。使用 `latest` 的安装命令会解析到最新已发布的包或 GitHub Release，这可能落后于源码候选版。候选版只有在对应的包、标签、校验和与发布资源齐备之后，才算正式发布的安装。
+
+在 macOS 和 Linux 上，网站安装器是最短的安装/更新路径：
+
+```bash
+curl -fsSL https://codewhale.net/install.sh | sh
+```
+
+它会下载匹配的 `codewhale` 和 `codew` 发布二进制，对照 `codewhale-artifacts-sha256.txt` 校验，默认安装到 `~/.local/bin`，并暴露 `codew` 便捷命令。
+
+---
+
+## 1. 支持平台
+
+已发布的 Codewhale 版本会为受支持的平台/架构组合提供配套的 `codewhale` 和 `codew` 预编译二进制。下表是 v0.9.11 候选版的预期矩阵；Android/Termux 为预览状态，等待真机 QA。Linux ARM64 自 v0.8.8 起可用。Linux RISC-V 预编译暂时暂停，因为锁定的 `rquickjs-sys` 依赖没有提供 `riscv64gc-unknown-linux-gnu` 绑定。
+
+| 平台 | 架构 | npm install | `cargo install` | GitHub 发布资源 |
+| ------------ | ------------ | :---------: | :-------------: | ----------------------------------------------------- |
+| Linux | x64 (x86_64) | ✅ | ✅ | `codewhale-linux-x64`, `codew-linux-x64` |
+| Linux | arm64 | ✅ | ✅ | `codewhale-linux-arm64`, `codew-linux-arm64` |
+| Android / Termux | arm64 (aarch64) | ⚠️⁴ 预览版 | ⚠️⁴ 预览版 | `codewhale-android-arm64.tar.gz` 发布时的预览压缩包 |
+| Linux | riscv64 | ❌¹ | ❌³ | 暂时不支持，待上游绑定落地 |
+| macOS | x64 | ✅ | ✅ | `codewhale-macos-x64`, `codew-macos-x64` |
+| macOS | arm64 (M 系列) | ✅ | ✅ | `codewhale-macos-arm64`, `codew-macos-arm64` |
+| Windows | x64 | ✅ | ✅ | `codewhale-windows-x64.exe`, `codew-windows-x64.exe` |
+| Windows | arm64 | ✅ | ✅ | `codewhale-windows-arm64.exe`, `codew-windows-arm64.exe` |
+| Linux x64 或 arm64 上的 musl（Alpine） | 原生架构 | ✅（静态） | ✅ | 匹配的静态 Linux 资源 |
+| 其他 Linux（其他架构上的 musl） | — | ❌¹ | ✅² | 从源码构建 |
+| FreeBSD 14+ / OpenBSD | x64, arm64 | ❌ | ✅² | `cargo install codewhale-cli --locked`（无预编译；见 § FreeBSD） |
+
+¹ npm 包会以明确错误退出，并引导你到这里。
+² 前提是你的工具链能编译较新的 Rust workspace；见下文[从源码构建](#7-从源码构建)。
+³ RISC-V 源码构建目前需要上游 `rquickjs-sys` 的 RISC-V 绑定，或启用 bindgen 的依赖构建。
+⁴ v0.9.11 源码候选版的 npm 包装器能识别 Android arm64，并解析匹配的 `codewhale` 和 `codew` Android 资源。npm 安装仅对 GitHub Release 已发布的、匹配的包版本有效。在 #4236 和 #4242 跟踪的真机编译、启动、审批、文件工具与更新检查完成之前，Android/Termux 路径仍为预览。
+
+Android / Termux 与 Linux arm64 不是同一个目标。不要在 Termux 里安装 Linux 的 `codewhale-linux-arm64` 压缩包；当某个发布版或候选版发布了 Termux 专用的 Android 压缩包时请使用它，或在 Termux 内从源码构建。
+
+Linux 的 **x64 和 arm64** v0.9.11 候选版资源是**静态 musl 构建**。x64 发布路径自 v0.8.65 起使用 musl；v0.9.6 将同样的构建与静态启动检查扩展到 arm64。这些二进制没有 glibc 依赖，可在匹配的架构上跨 Ubuntu、Debian、RHEL/CentOS 和 Alpine/musl 运行。SQLite 通过 `rusqlite` 内置，因此无需单独的 `libsqlite3` 运行时包。
+
+### Linux ARM64 可移植性
+
+v0.9.6 之前的 Linux arm64 资源是 GNU libc 构建，可能继承了 Ubuntu 24.04 构建主机的 `GLIBC_2.39` 最低要求。
+Ubuntu 22.04 自带 glibc 2.35，因此，那些较老的 arm64 二进制可能报错，例如：
+
+```text
+version `GLIBC_2.39' not found
+```
+
+npm 包装器、`codewhale update` 和 Unix 压缩包安装器对较旧版本仍保留 GNU 二进制预检查。v0.9.11 arm64 候选版改用 `aarch64-unknown-linux-musl`，因此没有 `GLIBC_*` 最低要求。如果你要在较旧的 arm64 发行版上安装早期版本，请使用：
+
+```bash
+cargo install codewhale-cli --locked # 安装 codewhale
+```
+
+> **Linux ARM64 说明（v0.8.7 及更早）。** v0.8.7 及更早版本**未发布** Linux ARM64 预编译；
+> 使用HarmonyOS 轻薄本、Asahi Linux、树莓派(Raspberry Pi)、AWS Graviton 等的用户会从 `npm i -g codewhale` 看到 `Unsupported architecture: arm64`。
+> v0.8.8 发布了 `codewhale-linux-arm64`，因此普通的 `npm i -g codewhale` 可在任何基于 glibc 的 ARM64 Linux 上工作。
+> 如果你还卡在 v0.8.7，直接跳到[从源码构建](#7-从源码构建)——`cargo install` 完全可用。
+> HarmonyOS PC 与 OpenHarmony 交叉构建设置，见 [HarmonyOS 与 OpenHarmony](../HarmonyOS.md)。
+
+### Android / Termux arm64
+
+Termux 运行在 Android 的 Bionic libc 上，并使用 `$PREFIX` 作为其 Unix 前缀，因此需要 Termux 专用的 Android arm64 压缩包。Linux arm64 发布资源面向标准 Linux（使用 musl），而 Android 使用不同的 Rust 目标。因此，不应在那里使用 Linux 资源。
+
+先安装最基本的压缩包/运行时工具：
+
+```bash
+pkg update
+pkg install -y ca-certificates curl tar gzip coreutils
+```
+
+当发布版包含 `codewhale-android-arm64.tar.gz` 时，用压缩包自带的安装器安装。传入 `PREFIX="$PREFIX"` 很重要：安装器默认安装到 `~/.local`，而 Termux 用户通常期望命令在 `$PREFIX/bin` 下。
+
+```bash
+cd "$HOME"
+curl -L -O https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-android-arm64.tar.gz
+curl -L -O https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-bundles-sha256.txt
+sha256sum -c codewhale-bundles-sha256.txt --ignore-missing
+
+tar xzf codewhale-android-arm64.tar.gz
+cd codewhale-android-arm64
+PREFIX="$PREFIX" ./install.sh
+hash -r
+```
+
+如果你要验证源码或在本地构建候选版，请在运行 Cargo 之前，先安装构建包：
+
+```bash
+pkg install -y rust clang pkg-config make git
+cargo install codewhale-cli --locked # 安装 codewhale
+```
+
+正确的首次运行设置流程已实现，但其 Android 交互仍属于上文提到的预览 QA 范围。
+临时凭证优先使用 provider 环境变量。
+`codewhale auth set` 可用，但 Termux 构建没有受支持的 OS 钥匙串集成（keyring integration），会退化为文件存储的密钥：写入 `~/.codewhale/config.toml`，并把密钥镜像到 `~/.codewhale/secrets/secrets.json`。两者都是纯文本文件，受 `0600` 权限保护，静态存储时未加密。
+
+```bash
+codewhale auth set --provider deepseek
+codewhale auth status
+codewhale doctor
+```
+
+维护者应对 Termux / Android arm64 候选版使用这套可重复的冒烟检查清单（smoke checklist）：
+
+```bash
+command -v codewhale codew
+test -x "$PREFIX/bin/codewhale"
+test -x "$PREFIX/bin/codew"
+
+codewhale --version
+codewhale doctor
+codewhale exec --auto "run pwd"
+```
+
+已知限制：
+
+- 命令会继承 Android 的每应用（per-app） UID、SELinux 和 seccomp 保护，以及授予 Termux 的任何权限。Codewhale 的可选 bubblewrap 子进程沙箱仅限 Linux，未在 Android 上构建，因此已批准的命令不会获得 Codewhale 特有的文件系统限制。
+- Termux 构建没有受支持的 Android Keystore 或桌面 Secret Service 集成。用 `codewhale auth status` 确认当前生效的来源；当文件型纯文本存储不可接受时，优先使用 provider 环境变量。
+- 终端渲染因 Android 终端应用而异。TUI 始终拥有备用屏幕（alternate screen）。如果某个终端应用无法渲染全屏 TUI，请改用 `codewhale exec` 来无头运行。
+
+---
+
+## 2. 下载安全与校验和
+
+官方发布二进制只从 `https://github.com/Hmbown/CodeWhale/releases` 和名为 `codewhale` 的 npm 包发布。除非你明确信任某个镜像，请勿从仿冒的仓库、压缩包和搜索结果镜像安装发布资源。
+
+每个 GitHub release 都包含校验和清单。使用 `codewhale-artifacts-sha256.txt` 校验裸二进制文件，使用 `codewhale-bundles-sha256.txt` 校验 `.tar.gz` / `.zip` 平台压缩包。如果您手动下载二进制文件，请在运行前进行验证：
+
+```bash
+# 在包含已下载的二进制的目录中运行。
+curl -L -O https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-artifacts-sha256.txt
+sha256sum -c codewhale-artifacts-sha256.txt --ignore-missing
+```
+
+在 macOS 上，用 `shasum -a 256 -c codewhale-artifacts-sha256.txt --ignore-missing` 来代替 `sha256sum`。
+
+如果杀毒软件标记了官方发布的二进制文件，请在找出确切的工件（Artifact）之前将其视为未解决的问题。请在 GitHub issue 中提供以下所有信息：
+
+- 发布标签，例如 `v0.8.36`
+- 确切的下载 URL
+- 文件名，例如 `codewhale-linux-x64`
+- 你机器上文件的 SHA-256
+- 杀毒软件产品名与检测名称
+
+这能让维护者区分官方工件的误报与来自仿冒仓库或镜像的下载。
+
+---
+
+## 3. 通过 npm 安装
+
+npm 是推荐的安装方式（Node 18+；包装器适用于 v0.8.56 及更高版本）。它安装的是 注册表（registry） 上最新发布的版本，而不是未发布的源码候选版。
+
+```bash
+npm install -g codewhale
+codewhale --version # 打印已安装的发布版本
+```
+
+`postinstall` 会下载匹配的 `codewhale` 和 `codew` 二进制，对照该来源的 SHA-256 清单校验，并把 `codewhale` 和 `codew` 添加到你的 `PATH` 中。
+
+在 **Linux x64**（包括 OpenHarmony x64）上，包装器**不会**等待缓慢的 GitHub 二进制下载或漫长的超时失败。
+除非你设置了显式的 release 基础 URL 或 `CODEWHALE_USE_CNB_MIRROR=1`，否则它会并发地从 GitHub Releases 和第一方 CNB release 获取对应精确包版本的小型 `codewhale-artifacts-sha256.txt` 清单，接受第一个对所需资源通过 HTTP 响应与清单校验的来源，取消另一个探测，并且只从该锁定来源下载二进制。
+CNB 只发布 Linux x64；其他目标保持仅 GitHub 路径。所选来源会打印在安装进度中，并写入下载文件旁的 `.source`。校验和（checksum）或来源不匹配时按失败处理。
+
+在 Windows 上，请从 **Windows Terminal** 运行这些命令，而不是 `cmd.exe`，这样字体和颜色才能匹配受支持的 TUI。GitHub Release 还会在裸 x64 exe 旁发布 `codewhale.bat`；该启动器优先使用 `wt.exe`，在没有 Windows Terminal 时回退为直接启动。
+
+有用的环境变量：
+
+| 变量 | 用途 |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| `CODEWHALE_RELEASE_BASE_URL` | 覆盖下载根目录。跳过 Linux x64 的 GitHub/CNB 竞争。 |
+| `CODEWHALE_USE_CNB_MIRROR=1` | 在 Linux x64 / OpenHarmony x64 上强制使用 CNB 第一方镜像。其他目标会失败。 |
+| `CODEWHALE_VERSION` | 固定包装器下载哪个 release（默认 `codewhaleBinaryVersion`）。 |
+| `CODEWHALE_GITHUB_REPO` | 让下载器指向某个 fork（`owner/repo`）。 |
+| `CODEWHALE_FORCE_DOWNLOAD=1` | 即使缓存的二进制标记匹配也重新下载。 |
+| `CODEWHALE_DISABLE_INSTALL=1` | 完全跳过 `postinstall` 下载（CI 冒烟、内置二进制）。 |
+| `CODEWHALE_OPTIONAL_INSTALL=1` | 遇到可重试的下载错误时不使 `npm install` 失败——在 CI 矩阵中有用。 |
+| `CODEWHALE_QUIET_INSTALL=1` | 禁止安装器进度消息，静默安装。 |
+| `CODEWHALE_DOWNLOAD_TIMEOUT_MS` | 覆盖总下载超时时间（毫秒）。 |
+| `CODEWHALE_DOWNLOAD_STALL_MS` | 覆盖无进度停滞超时时间（毫秒）。 |
+
+相应的 `DEEPSEEK_TUI_*` 和 `DEEPSEEK_*` 变量仍作为旧别名被接受，但规范的名称是 `CODEWHALE_*`。新的自动化与支持文档应只使用 `Codewhale` 名称。
+
+> **中国大陆 npm 下载慢？** 如果 `npm install` 本身很慢（不只是 postinstall 的二进制下载），使用 npm 注册表镜像：
+> ```bash
+> npm config set registry https://registry.npmmirror.com
+> npm install -g codewhale
+> ```
+> 如果你更想用 Cargo 而非 npm，参见[第 4 节](#4-通过-cargo-安装任何-tier-1-rust-目标)。
+
+---
+
+## 4. 通过 Cargo 安装（任何 Tier-1 Rust 目标）
+
+如果 GitHub releases 缓慢、受阻，或你正在使用不受支持的架构，可以直接从 crates.io 安装。
+只需要一个 Cargo 包：`codewhale-cli` 会安装 `codewhale` 命令。npm 与预编译发布版还会把 `codew` 作为同一编译运行时的便捷名称暴露出来；Cargo 不会创建该别名，所以如果你想要更短的名字，请自行定义 shell 别名。
+
+```bash
+# 需要 Rust 1.88+（https://rustup.rs）
+cargo install codewhale-cli --locked # 安装 codewhale
+codewhale --version
+```
+
+> **Linux：先安装构建时依赖。** `cargo install` 从源码编译，在 Linux 上 `codewhale-cli` crate 会链接 `libdbus-1`（D-Bus secret-service 后端用它存储凭据）。运行 `cargo install` 之前请先安装所需的系统包：
+>
+> ```bash
+> # Debian / Ubuntu
+> sudo apt-get install -y build-essential pkg-config libdbus-1-dev
+>
+> # Fedora / RHEL
+> sudo dnf install -y gcc make pkgconf-pkg-config dbus-devel
+> ```
+>
+> 如果你使用 npm 包装器或下载 GitHub Release 二进制，这些构建时包就**不需要**了——预编译二进制只需要运行时库（`libdbus-1`），而大多数桌面 Linux 安装里已经自带。
+
+### 中国/镜像友好安装
+
+从中国大陆安装时，请同时为 **rustup**（Rust 工具链安装器）和 **Cargo**（包注册表）配置镜像，以避免 TLS 超时和下载失败。
+
+**第 1 步：通过 rustup 镜像安装 Rust**
+
+```bash
+# PowerShell
+[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+(New-Object Net.WebClient).DownloadFile('https://win.rustup.rs/x86_64', 'rustup-init.exe')
+
+# git-bash / msys2
+export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup
+export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup
+./rustup-init.exe -y --default-toolchain stable
+
+# Linux / macOS
+export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup
+export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable
+```
+
+如果 TUNA 镜像在你的网络下很慢，`rsproxy.cn` 是 Linux/macOS 的另一个 rustup 镜像选择：
+
+```bash
+export RUSTUP_DIST_SERVER=https://rsproxy.cn
+export RUSTUP_UPDATE_ROOT=https://rsproxy.cn/rustup
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable
+```
+
+`RUSTUP_DIST_SERVER` 和 `RUSTUP_UPDATE_ROOT` 环境变量**必须**在运行 rustup-init **之前**设置；否则工具链下载会遇到与安装器相同的 TLS 握手问题。
+
+**第 2 步：配置 Cargo registry 镜像**
+
+```toml
+# ~/.cargo/config.toml
+[source.crates-io]
+replace-with = "tuna"
+
+[source.tuna]
+registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"
+```
+
+`rsproxy`、腾讯云 COS 和阿里云 OSS 镜像的工作方式相同；根据你的网络环境选择最快的即可。
+
+## 5. 通过 Nix 安装
+
+**试试看**
+
+如果你已经有支持 flake 的 Nix，运行：
+
+```sh
+nix run github:Hmbown/CodeWhale
+```
+
+Nix 会构建 `codewhale`（单个二进制），然后启动调度器。在 `--` 之后传参，例如：
+
+```sh
+nix run github:Hmbown/CodeWhale -- --help
+```
+
+### Flake
+
+在 `flake.nix` 中添加 inputs：
+
+```nix
+{
+ inputs = {
+ nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+
+ codewhale.url = "github:Hmbown/CodeWhale";
+ codewhale.inputs.nixpkgs.follows = "nixpkgs";
+ };
+}
+```
+
+安装到 NixOS 模块中：
+
+```nix
+{
+ outputs = { self, nixpkgs, codewhale }:
+ let
+ # 把 system "x86_64-linux" 替换成你的系统
+ system = "x86_64-linux";
+ in
+ {
+ # 把 `yourhostname` 改成你的真实主机名（Hostname）
+ nixosConfigurations.yourhostname = nixpkgs.lib.nixosSystem {
+ inherit system;
+ modules = [
+ # ...
+ {
+ environment.systemPackages = [ codewhale.packages.${system}.default ];
+ }
+ ];
+ };
+ };
+}
+```
+
+---
+
+## Omarchy / AUR
+
+在 Omarchy 上安装预构建的 AUR 包：
+
+```bash
+omarchy pkg aur add codewhale-bin
+codewhale --version
+```
+
+`codewhale-bin` 打包与其他二进制安装路径相同的、经校验和固定的 Linux 发布压缩包，并提供 `codewhale` 和 `codew` 两个命令。它不携带单独的 Codewhale 版本；现有的 `codewhale-tui` 兼容命令仍是同一运行时的别名。包更新通过 `omarchy update` 到达；应用内更新器会把 pacman 拥有的二进制留给 Omarchy。
+
+AUR 更新跟随匹配的 Codewhale 标签和发布资源，因此它可能在 GitHub 发布之后才出现——其生成的 `PKGBUILD` 和 `.SRCINFO` 需要先经过验证。发布维护者说明见 [`packaging/aur/README.md`](../../packaging/aur/README.md)。
+
+---
+
+## Homebrew
+
+formula 名为 `codewhale`。
+tap GitHub 仓库在改名之前仍是 `Hmbown/homebrew-deepseek-tui`；`brew tap Hmbown/deepseek-tui` 无论哪种情况都能继续工作。
+
+```bash
+brew tap Hmbown/deepseek-tui
+brew install codewhale
+```
+
+用 `brew upgrade codewhale` 更新。
+旧的 `deepseek-tui` formula 名下的 Cellar 安装，在一个重叠发布周期内，仍可运行 `brew upgrade deepseek-tui`；新安装应使用 `codewhale`。
+
+---
+
+## 6. 从 GitHub Releases 手动下载
+
+每个平台在 Releases 页面以**两种形式**出现（这是有意为之——见 #3208）：**裸二进制**（`codewhale-` 和 `codew-`，无扩展名）和 **`.tar.gz` / `.zip` 压缩包**（`codewhale-.tar.gz`），压缩包包含了同样的命令，还外加了 `install.sh`。
+npm 包装器和应用内 `codewhale update` 会下载匹配的运行时二进制；压缩包是最简单的手动安装方式（见[第 6 节](#6-从-github-releases-手动下载)）。下面的步骤直接使用裸二进制文件。
+
+从 [Releases 页面](https://github.com/Hmbown/CodeWhale/releases)抓取匹配你平台的命令组，并把它们并排放入 `PATH` 上的某个目录（例如 `~/.local/bin`）：
+
+```bash
+# Linux ARM64 示例
+mkdir -p ~/.local/bin
+curl -L -o ~/.local/bin/codewhale \
+ https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-linux-arm64
+curl -L -o ~/.local/bin/codew \
+ https://github.com/Hmbown/CodeWhale/releases/latest/download/codew-linux-arm64
+chmod +x ~/.local/bin/codewhale ~/.local/bin/codew
+codewhale --version
+```
+
+> **macOS Gatekeeper 说明。** 如果你用浏览器下载了二进制，macOS 可能会用"Apple 无法验证"警告拦截它们。清除两个二进制的隔离属性后重试：
+> ```bash
+> xattr -d com.apple.quarantine ~/.local/bin/codewhale ~/.local/bin/codew 2>/dev/null || true
+> ```
+
+根据每个版本的 SHA-256 清单验证完整性：
+
+```bash
+curl -L -o /tmp/codewhale-artifacts-sha256.txt \
+ https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-artifacts-sha256.txt
+( cd ~/.local/bin && sha256sum -c /tmp/codewhale-artifacts-sha256.txt --ignore-missing )
+```
+
+（在 macOS 上使用 `shasum -a 256 -c /tmp/codewhale-artifacts-sha256.txt --ignore-missing` 代替 `sha256sum -c`。）
+
+### 回滚到之前的版本
+
+如果某个新 release 在你的机器上出问题，请显式安装最后一个已知正常的版本。把 `X.Y.Z` 替换成你要恢复的版本。
+
+```bash
+# npm 包装器，仅对已发布到 npm 的版本有效
+npm install -g codewhale@X.Y.Z
+
+# Cargo 路径：一个包安装 codewhale
+cargo install codewhale-cli --version X.Y.Z --locked --force
+```
+
+手动安装时，请从确切的 release 标签下载匹配的二进制或平台压缩包，并从同一标签校验对应的校验和清单：
+
+```bash
+# 单独的二进制
+curl -L -o codewhale-artifacts-sha256.txt \
+ https://github.com/Hmbown/CodeWhale/releases/download/vX.Y.Z/codewhale-artifacts-sha256.txt
+
+# 平台压缩包
+curl -L -o codewhale-bundles-sha256.txt \
+ https://github.com/Hmbown/CodeWhale/releases/download/vX.Y.Z/codewhale-bundles-sha256.txt
+```
+
+在 Codewhale 工作区内，`/restore list [N]` 列出 side-git 文件快照，`/restore ` 从所选快照恢复文件。这种工作区回滚不会改变你已安装的二进制版本，也不会重写对话历史。
+
+### Windows Scoop
+
+`codewhale` 包列在 Scoop 的 main bucket 中：
+
+```powershell
+scoop update
+scoop install codewhale
+codewhale --version
+```
+
+Scoop 清单维护在本仓库的发布工作流之外，可能落后于 GitHub/npm/Cargo 发布。当你需要立即拿到最新版本时，请使用 npm 或手动在 GitHub release 下载。
+
+### Windows winget（v0.9.5+）
+
+CodeWhale 为 `Hmbown.CodeWhale` 发布 winget manifest（解决 #1561）。Winget 只安装 `codewhale` + `codew` 命令。GitHub Releases 保留字节完全一致的 `codewhale-tui-*` 文件名，仅用于旧版更新器兼容；它们不是第三个已安装命令。
+
+```powershell
+winget install Hmbown.CodeWhale
+codewhale --version
+```
+
+清单位于 [`packaging/winget/Hmbown.CodeWhale.yaml`](../../packaging/winget/Hmbown.CodeWhale.yaml)（也在 [`.winget/Hmbown.CodeWhale.yaml`](../../.winget/Hmbown.CodeWhale.yaml) 镜像了一份），列出 NSIS 安装器（`CodeWhaleSetup.exe`，每用户安装，把 `%LOCALAPPDATA%\Programs\CodeWhale\bin` 加入用户 PATH）和便携 ZIP 备选（`codewhale-windows-x64.zip` / `codewhale-windows-arm64.zip`）。
+winget 会自动选择匹配的架构；两者都安装单二进制文件（`codewhale.exe` + `codew.exe`）。ZIP 里还包含 `codewhale.bat`。请双击那个启动器（而不是原始 `.exe`），如此，首选窗口被设置为 Windows Terminal（如果已安装）。
+
+通过 `winget upgrade Hmbown.CodeWhale` 或 `codewhale update` 更新。winget 包维护在本仓库的发布工作流之外，可能会比 GitHub/npm/Cargo 发布滞后一个验证周期 —— 当您需要最新版本时，请使用 npm 或 GitHub Release 资源。
+如果 `winget install` 报告哈希不匹配，请校验同一标签的 `codewhale-artifacts-sha256.txt`，并通过 `packaging/winget/generate-winget-manifest.sh` 重新生成清单（见 [`packaging/winget/README.md`](../../packaging/winget/README.md)），然后重新提交到 [microsoft/winget-pkgs](https://github.com/microsoft/winget-pkgs)。
+
+> **Windows ARM64 说明。** NSIS 安装器目前只包含 x64 二进制。Windows ARM64 用户应通过 `winget install Hmbown.CodeWhale`（ARM64 ZIP）或原生 ARM64 Node.js 下的 `npm install -g codewhale` 安装，或直接下载 `codewhale-windows-arm64.zip`——所有路径都会安装原生 ARM64 二进制。
+
+### Windows NSIS 安装器
+
+从 v0.8.50 开始，为喜欢传统双击安装的 Windows 用户提供了独立的基于 NSIS 的安装器（无需 npm、Scoop 或 Cargo）。
+
+NSIS 安装器目前包含 Windows x64 二进制。Windows ARM64 用户应通过原生 ARM64 Node.js 下的 npm 安装，或从同一 release 下载 `codewhale-windows-arm64.zip`；两条路径都会使用原生 ARM64 二进制。
+
+**下载** 从 [Releases 页面](https://github.com/Hmbown/CodeWhale/releases/latest) 下载 `CodeWhaleSetup.exe`。
+
+**安装** 双击安装程序。安装器会：
+
+- 把 `codewhale.exe` 和 `codew.exe` 并排安装（单二进制，没有 `codewhale-tui.exe`）到 `%LOCALAPPDATA%\Programs\CodeWhale\bin`
+- 安装 `codewhale.bat`，它在 `PATH` 上存在 Windows Terminal（`wt.exe`）时优先使用，否则直接启动 exe
+- 创建当前用户的开始菜单快捷方式，指向该启动器，而非裸 `.exe`
+- 把安装目录加入**当前用户**的 `PATH`
+- 在 Windows **应用和功能（Apps & Features）** 中注册，便于卸载
+
+卸载会移除二进制、`codewhale.bat`、开始菜单快捷方式和用户 `PATH` 条目。
+
+**静默安装**（供 IT 管理员、SCCM、Intune 使用）：
+
+```powershell
+CodeWhaleSetup.exe /S
+```
+
+安装器是每用户安装，不会请求提权。请在目标用户的环境中运行静默安装，或使用能为每个需要 Codewhale 的用户配置文件运行安装器的部署工具。
+
+发布版安装器目前未签名，可能触发 Windows SmartScreen。部署前请用 `codewhale-artifacts-sha256.txt` 校验 SHA-256 校验和（checksum）；如果你的环境要求签名应用包，请在内部部署管道中对安装程序进行签名。
+
+**自行构建安装程序**（需要 [NSIS](https://nsis.sourceforge.io)）：
+
+```powershell
+cd scripts\installer
+# 把 codewhale.exe 和 codew.exe 放到这里（单二进制，没有 codewhale-tui.exe），然后：
+makensis /DVERSION= codewhale.nsi
+```
+
+**手动回退**——如果安装器被组策略阻止，参见 [CLASSROOM_INSTALL.md](../CLASSROOM_INSTALL.md) 指南中的分步 PowerShell 命令。
+
+> **要部署到教室或实验室？** 参见完整的[教室安装清单](../CLASSROOM_INSTALL.md)，涵盖静默安装、API key 供应、镜像说明与故障排查。
+
+---
+
+## 7. 从源码构建
+
+这是面向我们不提供二进制平台的兜底方案，包括 musl 非 x64、LoongArch、FreeBSD 以及 2024 年以前的 ARM64 发行版。Linux RISC-V 目前也需要上游 `rquickjs-sys` 的 RISC-V 绑定或启用 bindgen 的依赖构建，源码构建才能预期可用。
+
+### 前置条件
+
+- **Rust** 1.88 或更高版本——用 [rustup](https://rustup.rs) 安装。
+- **Linux 构建期依赖**（Debian/Ubuntu/openEuler/Kylin）：
+ ```bash
+ sudo apt-get install -y build-essential pkg-config libdbus-1-dev
+ # openEuler / RHEL 系列：
+ # sudo dnf install -y gcc make pkgconf-pkg-config dbus-devel
+ ```
+- 不需要 `cmake`。
+
+### 构建并安装
+
+```bash
+git clone https://github.com/Hmbown/CodeWhale.git
+cd CodeWhale
+
+cargo install --path crates/cli --locked # 安装 codewhale
+
+codewhale --version
+```
+
+命令默认安装到 `~/.cargo/bin/`；请确保该目录在你的 `PATH` 上。
+
+### FreeBSD 14+（解决 #1097）
+
+FreeBSD 没有预编译的 GitHub Release 资源——`npm install -g codewhale` 会故意失败，提示 `Unsupported platform: freebsd` 并指向 Cargo。从源码安装：
+
+```bash
+pkg install -y rust pkgconf git
+cargo install codewhale-cli --locked # 安装 codewhale
+codewhale --version
+codewhale doctor
+```
+
+`rquickjs` 的 FreeBSD 绑定在构建时通过 `bindgen` 生成（见 `1582ba965`/`5eb0385e8`）。
+目前还没有单独的 `pkg install codewhale` 端口——原生端口作为 #1097 的后续工作记录在 `packaging/freebsd/` 下（欢迎贡献）。请在 release 分支上用 `cargo check --target x86_64-unknown-freebsd -p codewhale-cli --locked` 验证；7×1 发布矩阵（Linux musl x64/arm64、Android arm64、macOS x64/arm64、Windows x64/arm64）仍是 7 个目标——FreeBSD 是源码构建目标，不是预编译资源。
+
+### 从 x64 交叉编译到 ARM64 Linux
+
+release 资源使用 `aarch64-unknown-linux-musl`，并在原生 ARM runner 上构建。如果你想在 x64 Linux 主机上构建 GNU 链接的 ARM64 Linux 二进制（例如用于 HarmonyOS / openEuler ARM64 轻薄本），请使用 [`cross`](https://github.com/cross-rs/cross)，它把官方的 Rust 交叉目标封装在 Docker 容器中：
+
+```bash
+# 一次性
+rustup target add aarch64-unknown-linux-gnu
+cargo install cross --locked
+
+# 每次构建
+cross build --release --target aarch64-unknown-linux-gnu -p codewhale-cli # 单二进制
+```
+
+生成的二进制位于 `target/aarch64-unknown-linux-gnu/release/codewhale`。把它复制到 ARM64 主机（例如通过 `scp`）并赋予可执行权限。这个本地 GNU 构建与可移植的 musl release 资源不同；两个可执行文件都可以复制到 `codew` 便捷名称下使用。
+
+如果你没有 Docker，直接安装交叉链接器，让 Cargo 完成工作：
+
+```bash
+sudo apt-get install -y gcc-aarch64-linux-gnu
+rustup target add aarch64-unknown-linux-gnu
+
+cat >> ~/.cargo/config.toml <<'EOF'
+[target.aarch64-unknown-linux-gnu]
+linker = "aarch64-linux-gnu-gcc"
+EOF
+
+cargo build --release --target aarch64-unknown-linux-gnu -p codewhale-cli # 单二进制
+```
+
+交叉编译时生成 `aarch64-unknown-linux-musl` 需要合适的 musl 交叉链接器。release 工作流通过在 GitHub 的原生 ARM runner 上构建并启动 musl 二进制来避免这个额外的活动部件。
+
+### Windows 源码构建
+
+在 Windows 上构建需要 [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022) 中的 **MSVC C 工具链**（免费的可选工作负载安装器，不是完整 IDE）。
+
+**前置条件（Windows）**
+
+1. 安装 Visual Studio 2022 Build Tools——选择 **"使用 C++ 的桌面开发（Desktop development with C++）"** 工作负载。
+2. 安装 [Rust](https://rustup.rs) 1.88+（如果从中国大陆下载，参见上文[中国/镜像友好安装](#中国镜像友好安装)）。
+3. 安装 [Git for Windows](https://git-scm.com/download/win)（提供 `git` 和 `git-bash` 终端）。
+
+**推荐的终端**：Windows Terminal、`git-bash` 或 PowerShell。`cmd.exe` 可用，但缓冲区较小且 PATH 行为有限。
+
+**设置 MSVC 环境**
+
+Visual Studio Build Tools 会把 `cl.exe` 安装到带版本号的目录，但**不会**把它全局加入 `PATH`。你必须手动设置环境，或使用开发者命令提示符。所需的变量是：
+
+```powershell
+# 调整版本号以匹配你的安装
+$msvc = "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.44.35207"
+$sdk = "C:\Program Files (x86)\Windows Kits\10"
+$sdkv = "10.0.26100.0"
+
+$env:INCLUDE = "$msvc\include;$msvc\atlmfc\include;$sdk\Include\$sdkv\ucrt;$sdk\Include\$sdkv\um;$sdk\Include\$sdkv\shared"
+$env:LIB = "$msvc\lib\x64;$msvc\atlmfc\lib\x64;$sdk\Lib\$sdkv\ucrt\x64;$sdk\Lib\$sdkv\um\x64"
+$env:LIBPATH = "$msvc\lib\x64;$msvc\atlmfc\lib\x64"
+$env:CC = "$msvc\bin\Hostx64\x64\cl.exe"
+$env:CXX = "$msvc\bin\Hostx64\x64\cl.exe"
+$env:PATH = "$msvc\bin\Hostx64\x64;$env:PATH"
+```
+
+或者，打开 **"VS 2022 开发者命令提示符（Developer Command Prompt for VS 2022）"**（安装 Build Tools 后可从开始菜单找到），它会运行 `vcvars64.bat` 自动配置上述所有内容。然后在该会话中把 `cargo` 加入 `PATH`，并从项目根目录运行 `cargo build`。
+
+**Cargo registry 镜像**——在 Windows 上，镜像配置放在 `%USERPROFILE%\.cargo\config.toml`。参见[上文第 2 步](#中国镜像友好安装)。
+
+**构建**
+
+```bash
+git clone https://github.com/Hmbown/CodeWhale.git
+cd CodeWhale
+set CARGO_HTTP_CHECK_REVOKE=false # 某些中国 ISP 后面可能需要
+cargo build --release
+```
+
+Cargo 构建的二进制出现在 `target\release\codewhale.exe`。发布打包会另外把同一可执行文件暴露为 `codew.exe`。
+
+> 不想构建？通过 npm、Cargo、GitHub Releases 或 CNB 镜像安装——参见上文各节。
+
+---
+
+## 8. Shell 补全
+
+Codewhale 生成自己的补全脚本。每个 shell 一条命令；每个脚本同时补全 **`codewhale`** 和 `codew` 缩写。
+
+```bash
+codewhale completion
+```
+
+`codewhale completions` 是同一命令的可用别名。
+
+脚本写到 stdout，因此安装它就是把输出重定向到你的 shell 加载补全的位置。
+
+**Bash** —— 需要你的 shell 已加载 `bash-completion` 包：
+
+```bash
+mkdir -p ~/.local/share/bash-completion/completions
+codewhale completion bash > ~/.local/share/bash-completion/completions/codewhale
+```
+
+仅当前 shell 生效：`source <(codewhale completion bash)`。
+
+**Zsh** —— 脚本的 `#compdef` 行已覆盖两个命令名：
+
+```bash
+mkdir -p ~/.zfunc
+codewhale completion zsh > ~/.zfunc/_codewhale
+```
+
+如果 `~/.zfunc` 不在 `fpath` 上，请把它加入 `~/.zshrc`：
+
+```zsh
+fpath=(~/.zfunc $fpath)
+autoload -Uz compinit && compinit
+```
+
+**Fish**：
+
+```fish
+mkdir -p ~/.config/fish/completions
+codewhale completion fish > ~/.config/fish/completions/codewhale.fish
+```
+
+**PowerShell** —— 追加到你的 profile，使其在每个会话中加载：
+
+```powershell
+New-Item -ItemType Directory -Force -Path (Split-Path -Parent $PROFILE)
+codewhale completion powershell >> $PROFILE
+```
+
+仅当前会话生效：
+
+```powershell
+codewhale completion powershell | Out-String | Invoke-Expression
+```
+
+**Elvish** —— 脚本注册两个命令名：
+
+```elvish
+codewhale completion elvish >> ~/.config/elvish/rc.elv
+```
+
+升级 Codewhale 后重新生成脚本——它是生成它的那个版本的命令面快照，不是实时查询。
+
+> 从 v0.9.10 或更早版本升级？那些版本生成的脚本注册的是内部 `codewhale-tui` 可执行文件，因此 `codewhale` 或 `codew` 没有任何补全（[#5526](https://github.com/Hmbown/CodeWhale/issues/5526)）。删除旧文件并用上面的命令重新生成。
+
+---
+
+## 9. 故障排查
+
+### `Unsupported architecture: arm64 on platform linux`
+
+你处于 v0.8.8 之前的版本，该版本不发布 Linux ARM64 二进制。要么升级（`npm i -g codewhale@latest`），要么按[第 4 节](#4-通过-cargo-安装任何-tier-1-rust-目标)使用 `cargo install`。
+
+### 升级旧安装后出现 `MISSING_COMPANION_BINARY`
+
+当前的单二进制在进程内运行 TUI，不需要配套可执行文件。该错误标识的是过时的 v0.9.5 之前调度器；请用当前的 npm 包或 Cargo 二进制替换该安装，而不是下载额外的运行时：
+
+```bash
+npm install -g codewhale
+# 或
+cargo install codewhale-cli --locked --force
+```
+
+### `codewhale update` 报告 `no asset found for platform codewhale-linux-aarch64`
+
+这是 v0.8.7 中的 [#503](https://github.com/Hmbown/CodeWhale/issues/503)——自更新器使用了 Rust 的 `aarch64`/`x86_64` 架构名，而不是发布工件的 `arm64`/`x64`。v0.8.8 之前的临时方案：
+
+```bash
+npm i -g codewhale@latest
+# 或
+cargo install codewhale-cli --locked
+```
+
+### 中国大陆 npm 下载慢或超时
+
+在 Linux x64 上，npm 包装器已经并行探测 GitHub Releases 和 CNB 第一方校验和清单，并且只从第一个通过校验的来源下载二进制。这条自动路径不需要 `CODEWHALE_USE_CNB_MIRROR=1`。
+
+如果两个第一方来源都失败，把 `CODEWHALE_RELEASE_BASE_URL` 设置为镜像的 release 资源目录（rsproxy、TUNA、腾讯云 COS、阿里云 OSS），或者完全跳过 npm，使用[第 4 节](#4-通过-cargo-安装任何-tier-1-rust-目标)的 Cargo 镜像设置。旧的 `DEEPSEEK_TUI_RELEASE_BASE_URL` 名称仍被接受。`CODEWHALE_USE_CNB_MIRROR=1` 仍只在 Linux x64 / OpenHarmony x64 上强制 CNB。
+
+### 中国大陆 无法从 GitHub 使用 `codewhale update`
+
+`codewhale update` 通常会联系 GitHub Releases 获取元数据和二进制资源。在 GitHub 被屏蔽或不稳定的网络上，改用 CNB 源镜像，并从 release 标签安装 `codewhale-cli` 包。Cargo 会安装 `codewhale` 命令：
+
+要查看最新 release 而不下载或替换二进制，运行 `codewhale update --check`。
+
+```bash
+cargo install --git https://cnb.cool/codewhale.net/codewhale --tag vX.Y.Z codewhale-cli --locked --force # 单二进制
+```
+
+如果你运营二进制资源镜像，`codewhale update` 可以直接使用它：
+
+```bash
+CODEWHALE_RELEASE_BASE_URL=https://your-mirror.example.com/CodeWhale/vX.Y.Z/ \
+CODEWHALE_VERSION=X.Y.Z \
+codewhale update
+```
+
+镜像目录必须包含 `codewhale-artifacts-sha256.txt` 和来自 GitHub release 的平台二进制。旧的 `DEEPSEEK_TUI_RELEASE_BASE_URL` 镜像变量仍作为别名受支持。
+
+### Debian/Ubuntu：`cargo install` 报 `feature edition2024 is required`
+
+一些 Debian/Ubuntu 发行版包自带较旧的 Cargo，无法解析 Rust 2024 crate。例如，Ubuntu 24.04 上的 Cargo 1.75.0 会在构建前失败，报错：
+
+```text
+feature `edition2024` is required
+The package requires the Cargo feature called `edition2024`, but that feature
+is not stabilized in this version of Cargo
+```
+
+通过 rustup 安装当前的 stable Rust，然后重新运行[第 4 节](#4-通过-cargo-安装任何-tier-1-rust-目标)中的那条 Cargo 包安装命令。它会安装 `codewhale`。对于中国大陆网络，以下基于 rsproxy 的序列已验证可用：
+
+```bash
+export RUSTUP_DIST_SERVER=https://rsproxy.cn
+export RUSTUP_UPDATE_ROOT=https://rsproxy.cn/rustup
+
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
+source "$HOME/.cargo/env"
+rustup default stable
+cargo install codewhale-cli --locked # 安装 codewhale
+```
+
+之后，`which cargo` 应指向 `~/.cargo/bin/cargo`，而不是 `/usr/bin/cargo`。
+
+### Debian/Ubuntu：构建时报 `error: linker 'cc' not found`
+
+安装 C 工具链：
+
+```bash
+sudo apt-get install -y build-essential pkg-config libdbus-1-dev
+```
+
+### WSL2 / Ubuntu：构建时找不到 `dbus-1` 或 `pkg-config`
+
+WSL2 与 Ubuntu 使用相同的 Linux 源码构建路径。如果 `cargo install codewhale-cli --locked` 在编译 keyring 或 D-Bus 密钥存储 crate 时失败，请在 WSL 发行版内安装 Linux 构建依赖，然后重新运行那条 Cargo 包安装命令。它会安装 `codewhale`：
+
+```bash
+sudo apt-get update
+sudo apt-get install -y build-essential pkg-config libdbus-1-dev
+cargo install codewhale-cli --locked # 安装 codewhale
+```
+
+预编译的 npm/GitHub 二进制不需要这些构建时包；它们只在 WSL2 从源码编译 Codewhale 时才需要。
+
+### 包装器装好了但找不到 `codewhale`
+
+`npm i -g` 安装到 `$(npm prefix -g)/bin`；请确保该目录在你的 shell `PATH` 上。使用 nvm 时：`nvm use --lts && hash -r`。
+
+### Windows：`rustup-init` 报 `TLS handshake eof` 或 `CRYPT_E_REVOCATION_OFFLINE`
+
+对 `static.rust-lang.org` 的 TLS 握手在 GFW 或某些中国 ISP 后面失败。在运行安装器**之前**设置 rustup 镜像环境变量：
+
+```bash
+# git-bash / msys2
+export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup
+export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup
+./rustup-init.exe -y --default-toolchain stable
+```
+
+如果 Rust 安装后 Cargo 报 `CRYPT_E_REVOCATION_OFFLINE`，请在 `cargo build` 期间同时设置 `CARGO_HTTP_CHECK_REVOKE=false`。
+
+### Windows：`cargo build` 期间找不到 MSVC 编译器（`cl.exe`）
+
+Visual Studio Build Tools 不会把 `cl.exe` 加入全局 `PATH`。二选一：
+
+1. 从开始菜单打开 **"VS 2022 开发者命令提示符"**，在该窗口中把 `%USERPROFILE%\.cargo\bin` 加入 `PATH`，并从那里运行 `cargo build`；或
+2. 手动设置 MSVC 环境变量——PowerShell 片段见[Windows 源码构建](#windows-源码构建)一节。
+
+验证编译器可用：`cl.exe /?` 应打印帮助文本。
+
+### Windows：Cargo 执行构建脚本时报 `拒绝访问 (os error 5)`
+
+第三方杀毒软件（火绒、360、卡巴斯基等）可能阻止 Cargo 执行刚编译的构建脚本二进制（例如 `libsqlite3-sys`、`aws-lc-sys`、`instability`）。该错误与路径无关——移动 `target-dir` 也无济于事。
+
+**症状**：`could not execute process ... build-script-build (never executed)`
+
+**临时方案**（任选其一）：
+
+1. **把项目的 `target/` 目录加入杀毒软件排除列表。**
+2. **在 `cargo build` 期间暂时关闭杀毒软件。**
+3. **改用 GitHub Release 安装器/压缩包**——发布资源提供预编译二进制，完全跳过 Cargo 构建（[第 6 节](#6-从-github-releases-手动下载)）。
+4. **使用 crates.io 的 `cargo install codewhale-cli --locked`**——这会改变二进制路径，某些杀毒软件对不同的路径处理方式不同。
+
+要验证构建脚本二进制本身是否有效（未损坏），在 `target/debug/build//build-script-build` 下找到它并手动运行：
+
+```bash
+target/debug/build/libsqlite3-sys-*/build-script-build
+# 如果它能运行但以 "NotPresent"（没有 C 编译器）panic，说明二进制没问题——
+# 是杀毒软件专门在阻止 Cargo 的进程派生路径。
+```
+
+### npm 二进制下载超时
+
+如果 `codewhale` 等待几秒后打印 `connect ETIMEDOUT` 或 `EAI_AGAIN`（从 `github.com` 拉取时），说明 npm 包装器安装成功，但预编译二进制下载在你的网络上被屏蔽或不稳定。该下载与 npm registry 包下载是分开的。在 Linux x64 上，包装器先竞争小型 GitHub 和 CNB 校验和清单，不会等到完整 GitHub 二进制超时才使用有效的 CNB 清单。
+
+使用以下路径之一：
+
+1. 设置代理并重试：
+
+ ```bash
+ export HTTPS_PROXY=http://your-proxy:port
+ codewhale
+ ```
+
+2. 在内部镜像 release 资源并设置 `CODEWHALE_RELEASE_BASE_URL`：
+
+ ```bash
+ export CODEWHALE_RELEASE_BASE_URL=https://your-mirror.example.com/CodeWhale/
+ codewhale
+ ```
+
+ 目录必须包含 `codewhale-artifacts-sha256.txt` 和来自 GitHub release 的平台二进制。
+
+3. 通过 Cargo 安装，它在本地构建，不下载 GitHub release 资源。参见[第 4 节](#4-通过-cargo-安装任何-tier-1-rust-目标)。
+
+4. 从 [Releases 页面](https://github.com/Hmbown/CodeWhale/releases) 下载匹配的 `codewhale` 和 `codew` 两个二进制，放入 `PATH` 上的目录并赋予可执行权限。参见[第 6 节](#6-从-github-releases-手动下载)。
+
+---
+
+## 10. 验证你的安装
+
+```bash
+codewhale --version
+codewhale doctor # 检查 API key、provider、运行时与 PATH 完整性
+codewhale doctor --json
+```
+
+如果 `doctor` 发现问题，会以非零状态退出并打印结构化的修复提示。需要帮助时，把 JSON 输出粘贴到 GitHub issue 中。
From 582915fb8f4164ae20fff56371eade1ed14a5fd3 Mon Sep 17 00:00:00 2001
From: Shizuku <2163018547@qq.com>
Date: Tue, 25 Aug 2026 19:21:57 +0800
Subject: [PATCH 3/4] docs: add zh_hans translation for KEYBINDINGS
---
docs/zh_hans/KEYBINDINGS.md | 215 ++++++++++++++++++++++++++++++++++++
1 file changed, 215 insertions(+)
create mode 100644 docs/zh_hans/KEYBINDINGS.md
diff --git a/docs/zh_hans/KEYBINDINGS.md b/docs/zh_hans/KEYBINDINGS.md
new file mode 100644
index 0000000000..0467ba9364
--- /dev/null
+++ b/docs/zh_hans/KEYBINDINGS.md
@@ -0,0 +1,215 @@
+# 按键绑定
+
+> 本文翻译自英文版 [KEYBINDINGS.md](../KEYBINDINGS.md)，与英文修订 `1a9600e7c`（2026-08-19）同步。
+
+这里是 TUI 所识别的每一个键盘快捷键的权威目录。
+快捷键绑定按**上下文**分组——即它们生效时所处的焦点或模态状态。列在“编辑器”下的快捷键仅在编辑器获得焦点时生效；“对话记录”下的快捷键仅在对话记录获得焦点时生效；依此类推。
+
+全局快捷键目前尚不支持用户自定义——此功能计划在未来的版本中实现（#436, #437）。热键栏位操作可通过 `[[hotbar]]` 和 `/hotbar` 进行配置；热键栏激活快捷键仍为 `Alt-1` 至 `Alt-8`。
+## 全局（任意上下文）
+
+| 按键 | 操作 |
+|------|------|
+| `F1` 或 `Ctrl-/` | 切换帮助浮层 |
+| `F2` | 切换键入式设置编辑器 |
+| `Ctrl-K` | 打开命令面板（斜杠命令查找器） |
+| `Ctrl-C` | 取消当前回合 / 关闭模态框 / 先武装再确认退出 |
+| `Ctrl-B` | 将受支持的前台 shell 等待移入 `/jobs`，使对话回合得以继续；可用 `/jobs` 或 `action: "wait"` 的 `Bash` 来查看它 |
+| `Ctrl-D` | 退出（仅当输入框为空时） |
+| `Tab` | 当输入框为空时，循环切换 TUI 模式：Plan → Work → Operate → Plan |
+| `Shift+Tab` | 循环切换权限姿态：Ask → Auto-Review → Full Access。无论输入框内容如何或回合是否在运行都即时生效（仅在打开 Config 以外的模态框时被抑制） |
+| `Ctrl-T` | 循环切换当前模型的推理力度。走与 `/model` 和 `/effort` 相同的阶梯（catalog 或已文档化的路由方言）。始终思考的模型省略 `off`;Grok 4.6 包含 `xhigh`。 |
+| `Ctrl-Shift-T` | 切换实时 transcript 浮层（粘性尾部自动滚动） |
+| `Ctrl-R` | 打开恢复会话选择器 |
+| `Ctrl-L` | 压缩对话上下文（状态行显示进度；压缩已在运行时为无操作） |
+| `Ctrl-O` | 打开所选或当前回合的推理详情，与输入框内容无关 |
+| `Ctrl-Alt-O` | 打开整回合的 Turn Inspector，与输入框内容无关 |
+| `Alt-V` / `Option-V`（macOS） | 为所选、可见或最近的工具/子代理卡片打开详情分页器；发出传统 Option-V 字符的终端也会被处理 |
+| `Ctrl-Shift-E` / `Cmd-Shift-E` | 切换文件树侧边栏 |
+| `Alt-G` / `Alt-Shift-G` |输入框为空时将 transcript 滚动到顶部 / 底部 |
+| `Alt-1`-`Alt-8` | 当没有模态框或内联选择器打开时分发 Hotbar 槽位 1-8 |
+| `Alt-!` / `Alt-@` / `Alt-#` / `Alt-$` | 选择工作栏面板：Tasks / Agents / Context / Pinned |
+| `Ctrl-Alt-0` | 关闭工作栏 / 恢复到顶部位置 |
+| `Alt-L` | 为最后一条消息打开分页器（输入框为空） |
+| `Alt-P` / `Alt-A` / `Alt-Y` | 跳到 Plan / Work，或请求 Full Access（`Alt-Y` 是旧的权限通道——Work + Full Access——不是独立模式；它遵循锁定的审批策略） |
+| `Ctrl-X`（活动侧边栏） | 取消所有正在运行的后台 shell 任务 |
+| `Esc` | 关闭最上层模态框 · 取消斜杠菜单 · 关闭 toast |
+
+## Composer（消息输入区）
+
+正在编辑你即将发送的消息。
+
+| 按键 | 操作 |
+|------|------|
+| `Enter` | 空闲时发送；忙碌时排队;composer 为空时，立即发送下一条已排队的后续消息 |
+| `Shift-Enter` / `Alt-Enter` / `Ctrl-J` | 插入换行而不发送（空闲或忙碌均可） |
+| `Ctrl-Enter` / `Cmd-Enter` | 引导当前回合；空闲时正常发送（在终端支持时） |
+| `Ctrl-U` | 清空整个草稿（可恢复——参见 `Ctrl-Z`） |
+| `Ctrl-Z` | 恢复已清空的草稿（仅当 composer 为空时） |
+| `Ctrl-W` / `Ctrl-Backspace` / `Alt-Backspace` | 删除前一个单词 |
+| `Ctrl-A` / `Home` | 移到输入开头 / 行首（readline 约定） |
+| `Ctrl-E` / `End` | 移到输入结尾 / 行尾 |
+| `Ctrl-←` / `Alt-←` | 向后移动一个单词 |
+| `Ctrl-→` / `Alt-→` | 向前移动一个单词 |
+| `Shift-←` / `Shift-→` | 每次扩展选区一个字素 |
+| `Ctrl-Shift-←/→` / `Alt-Shift-←/→` | 每次扩展选区一个单词 |
+| `Shift-Home` / `Shift-End` | 把选区扩展到行首 / 行尾 |
+| `Ctrl-Shift-Home` / `Ctrl-Shift-End` | 把选区扩展到草稿开头 / 结尾 |
+| `Ctrl-Shift-A` / `Cmd-A` | 选择整个草稿（参见下方说明） |
+| `Ctrl-Shift-U` | 从键盘运行 `/update install`：无需离开 TUI 即可检查并安装最新的 CodeWhale 版本。托管安装（Homebrew/npm/cargo）保留其包管理器门槛；已是最新版本时显示更新器的 "Already up to date." 结果，不做任何更改 |
+| 鼠标拖动 | 选择 composer 文本；点击移动光标 |
+| `Cmd-V` / `Ctrl-Shift-V` | 终端本地粘贴（在支持时以括号粘贴形式到达） |
+| `Ctrl-V` | 在本地或转发的图形会话中直接粘贴剪贴板 |
+| `Ctrl-Y` | 从 kill buffer 拉取（粘贴） |
+| `↑` / `↓` | 循环 composer 历史（也用于选择弹窗/附件条目） |
+| `Shift-↑` / `Shift-↓` | 浏览对话历史 |
+| `Ctrl-P` / `Ctrl-N` | 在斜杠命令菜单条目间导航；菜单为空时 `Ctrl-P` 打开文件选择器 |
+| `Ctrl-G` / `Ctrl-S` | 暂存当前草稿（`/stash pop` 恢复它）；从不发送或引导 |
+| `Alt-R` | 搜索提示历史（Alt-R 退出） |
+| `Tab` | 斜杠命令 / `@` 提及补全（感知弹窗） |
+| `Ctrl-Shift-O` / `F4` | 在 `$VISUAL` / `$EDITOR` 中打开 composer 草稿；当终端无法区分 Ctrl-Shift-O 与 Ctrl-O 时，F4 可用 |
+| `! command` | 通过常规的审批、sandbox 和输出界面运行 shell 命令 |
+
+设置 `composer_multiline_mode = true` 即可交换可移植的 `Enter` 与 `Shift-Enter` 行为：`Enter` 插入换行，`Shift-Enter` 发送。`Alt-Enter`、`Ctrl-J` 以及受支持的 `Ctrl-Enter` / `Cmd-Enter` 行为保持不变。
+
+### 选择语义
+
+输入、粘贴、`Backspace` 或 `Delete` 在存在活动选区时会替换或删除所选文本，与任何 GUI 编辑器一致。纯移动键（方向键、`Home`/`End`、单词移动）会折叠选区。当选区覆盖整个草稿时，删除或在上面输入会像 `Ctrl-U` 一样暂存即将离开的文本，因此 `Ctrl-Z`（在空 composer 上）或 `Alt-R` 草稿恢复可以把它找回来。
+
+光标移动和删除是字素感知的：一次 `←`/`→` 步进或一次 `Backspace` 覆盖完整的 emoji ZWJ 序列、旗帜对或组合标记簇——绝不会只删一半。CJK 文本按预期逐字符移动和删除。
+
+**为什么全选不是 `Ctrl-A`：** composer 遵循 readline 约定，其中 `Ctrl-A` 跳到输入开头（与 `Ctrl-E` 配对）。全选在每个平台上都是 `Ctrl-Shift-A`（与 `Ctrl-Shift-O` / `Ctrl-Shift-E` 一样，需要支持增强键盘协议的终端）。在转发 Command 键的 macOS 终端上（kitty、WezTerm、带 Command 重映射的 iTerm2），原生的 `Cmd-A` 也会全选;`Cmd-Shift-A` 在 macOS 上随处可用，因为 Cmd 会归一化为 Ctrl。
+
+### Hotbar
+
+Hotbar 触发语义刻意只限 `Alt-1` 到 `Alt-8`。在 macOS 键盘上，这是 Option/Alt 键加数字行。裸 `1`-`8` 是 composer 中的正常文本输入，并仍归选择器、引导、审批提示和模态视图所有。
+
+功能键和 `Cmd-1` 到 `Cmd-8` 不是 Hotbar 的主要组合。许多终端为标签页、窗口或操作系统快捷键保留了这些键，有些从不把它们转发给终端应用。如果终端配置为把 `Alt-1` 发送给某个自定义快捷键，Hotbar 也会收到同样可靠的组合。
+
+自 #3807 起，缺少 `hotbar` 键会渲染**无栏**——全新配置在配置 `[[hotbar]]` 槽位之前不显示 Hotbar（显式的 `hotbar = []` 也会禁用它）。配置后，栏看起来像：
+
+| 槽位 | 按键 | 默认操作 | 标签 |
+|------|------|----------|------|
+| 1 | `Alt-1` | `slash.workflow` | `wf` |
+| 2 | `Alt-2` | `slash.goal` | `goal` |
+| 3 | `Alt-3` | `slash.auto` | `auto` |
+| 4 | `Alt-4` | `mode.plan` | `plan` |
+| 5 | `Alt-5` | `mode.agent` | `agent` |
+| 6 | `Alt-6` | `mode.operate` | `operate` |
+| 7 | `Alt-7` | `palette.open` | `palette` |
+| 8 | `Alt-8` | `sidebar.toggle` | `side` |
+
+| 焦点状态 | Hotbar 行为 |
+|----------|-------------|
+| Composer 为空、有文本或空白 | `Alt-1`-`Alt-8` 分发配置的槽位 |
+| 侧边栏聚焦、隐藏或自动 | `Alt-1`-`Alt-8` 仍然分发配置的槽位 |
+| 斜杠菜单或历史搜索打开 | 被阻止；内联选择器拥有该按键事件 |
+| 命令面板、帮助、审批、文件选择器、会话选择器、Fleet 设置或任何模态栈 | 被阻止；模态框拥有该按键事件 |
+| Onboarding | 被阻止;Onboarding 拥有数字选择 |
+
+### `@` 提及
+
+输入 `@` 打开文件提及弹窗。`↑`/`↓` 循环条目，`Tab` 或 `Enter` 接受。`Esc` 隐藏弹窗。自 v0.8.10（#441）起，补全按提及频率重新排序——你经常且最近提到的文件会浮到顶部。
+
+两种提及解析为精选的 git 上下文而不是路径（v0.9.2，#4067）：
+
+| 提及 | 内联内容 | 字节预算 |
+|------|----------|----------|
+| `@git` | 工作区的 `git status --short --branch` | 8 KB |
+| `@diff` | 工作树 diff，已暂存和未暂存（`git diff HEAD`） | 32 KB |
+
+两者都出现在补全弹窗中路径的旁边，并且都显示在上下文检查器中，带有其解析后的大小；当 diff 超过其预算时，还会显示截断标记。当 git 缺失、工作区不是仓库或没有可显示的内容时，回合会携带显式的 `` 说明，而不是静默地什么都不贡献。仅以该 token 开头的路径（`@diff.txt`、`@git/config`）仍是文件提及。
+
+### `#` 快速添加（记忆）
+
+当 `[memory] enabled = true` 时，输入 `# foo` 并按 `Enter` 会把 `foo` 作为带时间戳的条目追加到你的记忆文件中，*而不会*发送回合。参见 `docs/MEMORY.md`。
+
+## Transcript（transcript 获得焦点时）
+
+| 按键 | 操作 |
+|------|------|
+| `↑` / `↓` / `j` / `k` | 滚动一行（v0.8.13+：composer 为空时裸方向键也可滚动） |
+| `Alt-↑` / `Alt-↓` | 滚动 transcript（替代方式） |
+| `PgUp` / `PgDn` | 滚动一页 |
+| `Home` / `g` | 跳到顶部 |
+| `End` / `G` | 跳到底部 |
+| `Ctrl-Home` / `Ctrl-End` | 跳到顶部 / 底部（也可从 composer 中工作） |
+| `Alt-[` / `Alt-]` | 在工具输出块之间跳转 |
+| `Esc Esc` | 回溯到上一条用户消息（`←`/`→` 步进，`Enter` 回退） |
+| `Esc` | 将焦点返回 composer |
+| 鼠标拖动 | 在 Codewhale 中选择 transcript 文本 |
+| `Ctrl-C` | 复制活动的 Codewhale 选区 |
+| `Cmd-click`（macOS）/ `Ctrl-click`（Linux/Windows） | 在支持的终端中打开 OSC 8 链接（归终端处理） |
+
+对于终端原生选择，按住 `Shift` 拖动（终端支持程度不一），然后使用终端自己的复制命令：通常是 macOS 上的 `Cmd-C` 或 Linux/Windows 上的 `Ctrl-Shift-C`。这些命令由本地终端处理，并刻意与 Codewhale 的 `Ctrl-C` 选择绑定分开。在 SSH 上，Codewhale 通过 OSC 52 发回复制请求，或在 tmux 内运行时通过 tmux 的 `load-buffer -w` 路径。
+
+## Work bar（`Alt-W` 获得焦点后）
+
+| 按键 | 操作 |
+|------|------|
+| `↑` / `↓` | 移动选择 |
+| `Home` / `End` | 跳到第一行 / 最后一行 |
+| `PageUp` / `PageDown` | 每次按视口移动选择 |
+| `Enter` | 打开所选行的 world（work inspector / agent details）；在已打开的行上则关闭它 |
+| `Esc` | 关闭已打开的详情，否则将焦点返回 composer |
+| 任意可打印键 | 将焦点返回 composer（输入总是胜出） |
+
+鼠标对等：点击任意工作栏行都执行 `Enter` 的操作，适用于每个面板和位置。`Alt-!`/`Alt-@`/`Alt-#`/`Alt-$` 切换面板。
+
+## 斜杠命令面板（按 `Ctrl-K` 或输入 `/` 后）
+
+| 按键 | 操作 |
+|------|------|
+| `↑` / `↓` / `Ctrl+P` / `Ctrl+N` | 移动选择 |
+| `Enter` / `Tab` | 运行 / 补全高亮的命令 |
+| `Esc` | 关闭面板 |
+
+## Session Picker（`Ctrl-R` 或 `/sessions`）
+
+| 按键 | 操作 |
+|------|------|
+| `↑` / `↓` / `j` / `k` | 在会话列表中移动选择 |
+| `1`-`9` | 在该列表槽位打开可见的会话历史 |
+| `PgUp` / `PgDn` | 翻历史面板的页 |
+| `Enter` | 恢复所选会话 |
+| `/` | 搜索会话 |
+| `s` | 循环排序方式 |
+| `a` | 切换当前工作区范围与所有工作区 |
+| `e` | 归档 / 恢复所选会话 |
+| `x` | 显示或隐藏已归档会话 |
+| `d` | 确认后删除所选会话 |
+| `Esc` / `q` | 关闭选择器 |
+
+归档（`e`）非破坏性且无需确认：会话仍留在磁盘上且仍可加载，它只是离开默认列表并停止作为自动恢复候选。再按一次 `e` 把它带回来。删除（`d`）是破坏性的，并保留其确认。
+
+## 审批模态框（当工具请求审批时）
+
+| 按键 | 操作 |
+|------|------|
+| `y` / `Y` | 批准一次 |
+| `a` / `A` | 全部批准（自动批准后续调用） |
+| `n` / `N` / `Esc` | 拒绝 |
+| `e` | 在运行前编辑已批准的输入 |
+
+## Onboarding（首次运行流程）
+
+| 按键 | 操作 |
+|------|------|
+| `Enter` | 前进到下一步（欢迎 → 语言 → API/信任门 → 设置检查点） |
+| `Esc` | 后退一屏 |
+| `1`–`9` | 选择语言（语言步骤） |
+| `0`–`9` | 选择 provider（Provider 步骤;SGLang、vLLM 和 Ollama 默认无密钥） |
+| `y` / `Y` | 信任工作区（信任步骤） |
+| `n` / `N` | 跳过信任提示 |
+
+## v0.8.29 审计说明
+
+- **`Shift+Enter` / `Alt+Enter` 换行现在在 Windows 上的 VSCode 中可用（#1359）。** crossterm 的 `PushKeyboardEnhancementFlags` 命令在 Windows 上无条件返回 `Unsupported`（`is_ansi_code_supported() == false`），因此 Kitty 键盘协议转义从未写入终端。没有它，VSCode 的 xterm.js 停留在传统模式，其中 `Shift+Enter` 与普通 `Enter` 无法区分，导致 composer 发送消息而不是插入换行。修复方案直接在 Windows 上写入 push/pop 转义（`\x1b[>1u` / `\x1b[<1u`），绕过 crossterm 的能力门。VSCode 集成终端和 Windows Terminal ≥1.17 都遵循 Kitty 键盘协议；不理解这些序列的终端会静默丢弃它们。
+
+## v0.8.13 审计说明
+
+- **Ctrl-S 是暂存，不是历史搜索。** 在此修订中修复——`Alt-R` 才是历史搜索。
+- **移除了幽灵 `Alt+Up`。** "Edit last queued message" 绑定曾列在 README 中，但从未存在于按键分发代码中。
+- **composer 为空时裸 Up/Down 方向键滚动 transcript（v0.8.13）。** 以前 `should_scroll_with_arrows` 门被硬编码为 false，意味着即使 composer 为空，裸方向键也总是导航 composer 历史。虚拟终端（Ghostty、Codex、Kitty 协议）中的用户尤其受影响，因为他们无法使用 Cmd+Up / Alt+Up 快捷键。
+- **可配置键位（#436）和 `tui.toml`（#437）仍然延期。** `TuiPrefs` 结构体和加载器存在于 `settings.rs` 中，但未在启动时接线。允许 `~/.codewhale/tui.toml` 覆盖单个条目的命名绑定注册表仍然待办。
+- **未发现其他损坏的绑定。** 上面列出的每个其他组合都解析为 `crates/tui/src/tui/ui.rs`（按键事件分发）或 `crates/tui/src/tui/app.rs`（模式 + 状态转换）中的实时处理器。
From 252e14a9c0b552f84fd404f762d413cb3f68086b Mon Sep 17 00:00:00 2001
From: Shizuku <2163018547@qq.com>
Date: Tue, 25 Aug 2026 19:21:57 +0800
Subject: [PATCH 4/4] docs: add zh_hans translation for GUIDE
---
docs/zh_hans/GUIDE.md | 472 ++++++++++++++++++++++++++++++++++++++++++
1 file changed, 472 insertions(+)
create mode 100644 docs/zh_hans/GUIDE.md
diff --git a/docs/zh_hans/GUIDE.md b/docs/zh_hans/GUIDE.md
new file mode 100644
index 0000000000..94fb9979d8
--- /dev/null
+++ b/docs/zh_hans/GUIDE.md
@@ -0,0 +1,472 @@
+# Codewhale 用户指南
+
+> 本文翻译自英文版 [GUIDE.md](../GUIDE.md)，与英文修订 `3c3630396`（2026-08-19）同步。
+
+本指南面向你使用 Codewhale 的第一个小时。它涵盖了主要工作流程、重要安全控制，以及当你需要完整参考时接下来该看什么。
+
+Codewhale 有更深入的参考文档，涵盖安装、配置、提供商（provider）、模式、快捷键、工具和运维。请将本页当作引导式走查，需要每个选项时再顺着"下一步"链接往下看。
+
+## 1. 欢迎使用 Codewhale
+
+Codewhale 是一个终端编码智能体（agent）。你从某个工作区运行它，交给它一个任务，它就能用结构化工具检查文件、运行命令、编辑代码，并带回证据汇报结果。
+
+与普通聊天模型的重要区别在于，Codewhale 是围绕 “驾驭框架”（harness） 构建的：
+
+- 它让活动工作区和会话保持可见。
+- 它把每一轮都路由到明确的模式与审批规则。
+- 它在对话记录中展示工具调用，而不是把工作藏起来。
+- 它可以保存会话、分叉对话，并在之后继续。
+- 它可以运行子智能体来执行专注的后台工作。
+
+你可以用 Codewhale 回答小问题：
+
+```text
+解释此仓库中的身份验证流程。
+```
+
+也可以用它做多步工作：
+
+```text
+找到失败的验证路径，提出修复方案，等我批准了再编辑文件。
+```
+
+对于新仓库，请从保守的方式开始。在要求 Codewhale 修改文件之前，先让它探索和规划。这样会为您提供可审查的路径，并更容易及早发现错误的假设。
+
+下一步：[ARCHITECTURE.md](../ARCHITECTURE.md) 讲解内部 harness 与运行时模型。
+
+## 2. 首次启动
+
+用适合你机器的路径安装 Codewhale。发布安装器在 `codewhale` 和 `codew` 两个命令名下提供同一运行时；每条受支持的安装路径都提供 `codewhale` 调度器，`codewhale-tui` 运行时已内置。
+
+```bash
+# npm
+npm install -g codewhale
+
+# Cargo
+cargo install codewhale-cli --locked
+# Cargo 安装后可选的短命令名：
+ln -s "$(command -v codewhale)" "$(dirname "$(command -v codewhale)")/codew"
+
+# Homebrew
+brew tap Hmbown/deepseek-tui
+brew install codewhale
+```
+
+当你想要隔离的运行时，也可以用 Docker：
+
+```bash
+docker volume create codewhale-home
+docker run --rm -it \
+ -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
+ -v codewhale-home:/home/codewhale/.codewhale \
+ -v "$PWD:/workspace" \
+ -w /workspace \
+ ghcr.io/hmbown/codewhale:latest
+```
+
+从你希望它工作的仓库或目录启动 Codewhale：
+
+```bash
+codewhale
+```
+
+首次启动时，Codewhale 只询问本次安装仍然需要的决定：无法推断语言时询问语言，未配置可用路由时询问提供商，文件夹需要决定时询问工作区信任。提供商步骤包含明确的离线路由。就绪界面随后打开真正的编辑器，保留命令行中提供的任务，或为当前文件夹建议第一个任务。
+
+此后所有可选内容都保持可用。用 `/setup` 打开渐进式设置与修复指南，用 `/settings` 打开完整键入式编辑器，想自定义内置工作约定时用 `/constitution`。本地化遥测选择只在工作区就绪后出现，不会阻塞编辑器。
+
+DeepSeek 是默认提供商。如果你想在首次启动之前或之后配置它的 key，最直接的设置路径是：
+
+```bash
+codewhale auth set --provider deepseek
+```
+
+你也可以通过环境变量提供 key：
+
+```bash
+export DEEPSEEK_API_KEY="your-key"
+codewhale
+```
+
+新的 Codewhale 配置存放在 `~/.codewhale/config.toml`。旧的 `~/.deepseek/config.toml` 文件仍受支持，供从旧名称迁移的用户使用。
+
+用 `/constitution` 查看或更改常驻指引。设置完成后，运行一次 doctor 检查：
+
+```bash
+codewhale doctor
+```
+
+当你需要机器可读的报告用于提交 issue 时，用 JSON 形式：
+
+```bash
+codewhale doctor --json
+```
+
+两种形式默认都是离线的。
+它们报告结构配置和字面上的未知/未探测凭证状态，不会加载工作区的 `.env` 凭据、打开 secret/OAuth 文件、探测密钥串、联系提供商或启动 MCP 服务器。只有有意需要该实时边界时，才使用 `--check-updates`、`--probe-api`、`--probe-local` 或 `--probe-mcp`。JSON 保持离线，不接受实时标志。
+
+JSON 把凭据的 `source`（来源）与字面的 `availability`（可用性）分开报告。配置的环境、外部认证、OAuth、consent 和 secret-store 来源仍为 `not_probed`；它们的声明本身并不会让 Setup 或 Fleet 就绪。只有结构上存在的字面配置值，或一条不需要凭据的路由，才能证明离线就绪。对于无法使用共享存储的路由上的旧版密钥存储哨兵（secret-store sentinel），会单独报告为 `secret_store_unavailable`/`unavailable`，而不是简单的"符合条件"或"未知"。
+
+`doctor` 和 `doctor --json` 都还包含一项会话恢复诊断，它把旧会话文件名与当前存储对比，不读取会话内容，并报告以下之一： `isolated`、`no_legacy_sessions`、`migration_pending`、`migration_incomplete`、`migration_complete` 或 `scan_failed` 。
+使用 `migration_pending` 或 `migration_incomplete` 作为提示，完成把会话从 `~/.deepseek` 迁移到 `~/.codewhale` 的工作——就是上面提到的旧路径迁移。显式设置 `CODEWHALE_HOME` 会抑制此环境检查。
+
+下一步：[INSTALL.md](INSTALL.md) 涵盖各平台的安装路径，[CONFIGURATION.md](CONFIGURATION.md) 涵盖配置解析，[PROVIDERS.md](PROVIDERS.md) 涵盖提供商 ID 与凭据。
+
+## 3. 你的第一个任务
+
+从一个真实工作区里的只读任务开始：
+
+```text
+映射仓库结构，并告诉我 CLI 入口点在哪里。
+```
+
+然后要一份有重点的计划：
+
+```text
+我想为空的配置值添加一个小型验证。
+检查相关代码，并在编辑任何内容之前提出最小的安全更改。
+```
+
+当你准备好做编辑时，把验收标准说具体：
+
+```text
+实施你提出的验证。
+将更改范围限制在配置解析内，添加或更新最窄的测试，并运行相关的检查。
+```
+
+好的首批提示词（prompt）包含四个要素：
+
+- 你想要的结果。
+- 你关心的文件、功能或行为。
+- 哪些不在范围内。
+- 什么算"验证通过"。
+
+例如：
+
+```text
+修复配置加载器中损坏的提供程序错误消息。
+不要更改提供程序注册表。添加回归测试，并且只运行 config 包的测试。
+```
+
+如果你不确定 bug 在哪，直说：
+
+```text
+调查为什么 `codewhale doctor` 报告了错误的提供程序。
+暂时不要编辑文件。返回可能的原因、证据和提议的补丁计划。
+```
+
+面对不熟悉的代码，让调查和实现分步进行时 Codewhale 表现最好。对于很小且充分理解的改动，一个单独的实现请求就够了。
+
+下一步：[MODES.md](MODES.md) 讲解何时使用 Plan、Act 和 Operate。
+
+## 4. 了解界面
+
+交互式 TUI 有几个稳定的区域：
+
+- 头部（Header）：当前会话、活动模型、模式和总体状态。
+- 转录区（对话记录，Transcript）：对话、工具调用、命令输出摘要和模型回复。
+- 输入区（Composer）：你在这里输入提示、斜杠命令和文件提及。
+- 工作栏（Work bar）：转录区上方的一条（或可选的侧栏），承载活动目标、待办列表和子智能体。行会保持整个会话——已完成的工作显示为"已完成"而不是消失——点击某一行（或对它按 `Enter`）会打开它的详情。
+- 状态与底部区域：实时活动、排队的后续动作和简短命令提示。
+
+底部状态行可配置。运行 `/statusline` 选择哪些底部的片区可见，或在 `config.toml` 里设置 `[tui].status_items` 同时控制选择和顺序。
+当前支持的键包括 `mode`、`model`、`cost`、`balance`（仅 DeepSeek / DeepSeekCN）、`status`、`agents`、`reasoning_replay`、`prefix_stability`、`cache`、`context_percent`、`git_branch`、`last_tool_elapsed`（保留）、`rate_limit`（保留）、`tokens` 和 `session_metrics`。
+省略 `status_items` 以保持内置默认顺序；把它设为 `[]` 以隐藏可配置的片区。
+
+`session_metrics`（默认开启）在阶段行上绘制会话指标条带：
+`4 turns · 108 steps │ LLM 11m46s · Tool call 1m52s │ TTFT avg 1.5s · 120 tok/s │ Cache hit 99% │ Input 9.3M`
+Turns 是用户回合；steps 是模型调用加工具调用；`LLM` 是模型调用墙钟时间的总和，`Tool call` 是工具墙钟时间的总和；`TTFT avg` 是到首个流式 token 的平均时间；`tok/s` 是提供商报告的输出 token 除以流式秒数；`Cache hit` 和 `Input` 是提供商报告的 token 类别。提供商或运行时证据尚未到达的单元格会被省略而不是估算，在窄行上，指标条会丢弃价值最低的组（先是 steps 和工具时间，然后是延迟、turns、LLM 时间），而不是截断某个数字。`/status` 打印未裁剪的完整行。
+
+转录区（对话记录）就是审计轨迹。当 Codewhale 读文件、跑命令或改代码时，动作会出现在那里。如果某条命令失败，把可见的失败输出作为你下一条指令的一部分，而不是从头再来。
+
+输入区接受普通提示和斜杠命令。输入 `/` 可以发现可用命令。想让模型专注于某个特定文件或目录而不是广泛搜索时，使用文件提及。
+
+当一个回合跨越多个步骤时，工作栏很有用。它让目标、待办列表和智能体状态保持可见，同时转录区继续增长——包括在工作落定之后，这样你仍然可以打开看看发生了什么。
+
+键盘快捷键因上下文、终端和平台而异。本指南不重复完整的快捷键目录，以免与 TUI 脱节。
+
+下一步：[KEYBINDINGS.md](KEYBINDINGS.md) 是完整的快捷键参考。
+
+## 5. 模式
+
+Codewhale 有三种可见的 TUI 模式：
+
+| 模式 | 用于 | 默认姿态 |
+| --- | --- | --- |
+| Plan | 改动前的探索、设计与审查 | 只读调查 |
+| Act | 常规的多步编码工作 | 带审批门禁的工具使用 |
+| Operate | 直接工作，外加并行或后台协调 | 工具遵循活动姿态；需要时委派 |
+
+从 TUI 里用模式选择器切换模式：
+
+```text
+/mode
+```
+
+或直接切换：
+
+```text
+/mode plan
+/mode act
+/mode operate
+```
+
+Plan 模式是在陌生仓库里开始的最安全位置。它用于检查和决策，不做文件编辑。对于非平凡的工作，Plan 模式的确认提示可以显示有依据的计划工件（PlanArtifact）：目标、上下文、使用的来源、关键文件、约束、方法、验证计划、风险和交接说明。
+当智能体（agent）使用富工件形态时，空章节也是可见的，所以你可以要求修订，而不是接受一份说明不足的计划。
+
+Act 模式是大多数贡献工作的默认模式。它允许 Codewhale 读文件、跑检查、编辑文件，同时把有风险的动作留在审批门禁之后。
+
+Operate 保持直接的工具面及其审批、沙箱、shell、ask 规则和仓库保护。它的区别在于编排重点：Codewhale 优先把独立、并行、后台或长时间运行的工作交给 Fleet worker，而小型或紧密耦合的工作可以留在父进程中。
+
+对于你信任的工作区，如果你确实希望动作不经审批提示就继续，可以用 `Shift+Tab` 选择 Full Access 权限姿态。不要在你不信任的仓库里使用 Full Access。
+
+模式与模型路由是分开的。输入区空闲时 `Tab` 循环切换可见模式，而 `/model auto` 控制回合的模型与思考选择。
+
+你也可以在 `/config` 里通过编辑审批模式来改变审批行为。只有当你理解它会如何改变工具执行时才使用它。
+
+下一步：[MODES.md](MODES.md) 有完整的模式、审批和信任模式参考。
+
+## 6. 斜杠命令
+
+斜杠命令在输入区里输入。当你想要直接改变 Codewhale 状态，而不是用自然语言让模型去做时，它们很有用。
+
+对首次用户常用的命令：
+
+| 命令 | 用途 |
+| --- | --- |
+| `/mode` | 打开模式选择器，或用 `/mode agent` 切换 |
+| `/model` | 选择模型，或用 `/model auto` |
+| `/provider` | 选择活动的 API 提供商|
+| `/fleet` | 配置 Fleet 角色或打开 worker 状态 |
+| `/goal` | 设置一个智能体跨回合持续追求的持久目标；裸 `/goal` 显示进度 |
+| `/workflow` | 把当前工作编排为 Workflow；`status`、`cancel`、`settings` 无需模型回合即可回答 |
+| `/workflows` | 打开实时 Workflow 运行仪表盘：该工作区日志记录的每一次运行，含阶段、子项、进度和主机侧取消 |
+| `/config` | 编辑运行时与提供商设置 |
+| `/statusline` | 选择哪些底部状态芯片可见 |
+| `/compact` | 压缩长上下文以回收 token 预算 |
+| `/review` | 请求结构化的审查工作流 |
+| `/memory` | 启用时检查或管理记忆 |
+| `/mcp` | 配置或检查 MCP 服务器集成 |
+| `/plugin` | 审查和管理默认禁用的本地插件包 |
+| `/rc` | 把此确切会话交给已登录的 Codewhale 网页应用 |
+
+工具箱命令直接输入即可搜索：`/models` 拉取实时端点 ID，`/modeldb` 打开内置模型参考，`/rlm` 把文件或一段文本加载进工作上下文，在会话剩余时间里保持可用。
+
+想切离默认的 DeepSeek 路由时用 `/provider`。Provider ID、环境变量、模型默认值和能力说明都保留在提供商注册表文档里。
+
+软自动多智能体工作：[AUTOMATIC_WORKFLOWS.md](../AUTOMATIC_WORKFLOWS.md)。
+
+面向持久多 worker 工作的下一步：[FLEET_WORKFLOW_TUTORIAL.md](../FLEET_WORKFLOW_TUTORIAL.md) 带你走一遍 Fleet 任务规格、监控和 Workflow 编写。
+
+想让 Codewhale 每回合自己选模型和思考级别时，用 `/model auto`。当 DeepSeek 路由模型可用时，Auto 可以在脱敏清单中选取任何可运行的 provider/模型组合。该分类会把最新请求（上限 4,000 字符）加上最多六条最近上下文行的有界摘要（每条 900 字符）发送到 `DeepSeek / deepseek-v4-flash`。凭据、端点和提供商错误文本不会包含在清单里。没有该路由器时，Auto 使用本地的、感知提供商的启发式方法，不发送任何路由请求。如果分类尝试未通过验证或出错，Auto 回退到该启发式方法，同时把尝试过的分类器数据路径保留在回合回执中。
+
+`/model` 选择器会说明哪条数据路径可用，并显示最后解析的路由。`Ctrl+O` 打开所选或当前回合的推理详情；`Ctrl+Alt+O`（或 `/turn inspect`）打开整回合的回合检查器（Turn Inspector），其模型路由区记录具体的 provider/模型、strong/fast 配对、所选层级、选择范围、路由原因，以及分类器是否收到了路由上下文。当你需要可重复的比较、严格的提供商边界或完全不要分类请求时，使用固定模型。
+
+会话变长、模型开始承载太多历史记录时，用 `/compact`。压缩会用简洁的工作摘要换取原始转录细节。
+
+本指南有意不列出每条命令。命令面比上手流程变化更频繁，你在会话里时，TUI 命令面板才是事实来源。
+
+下一步：[CONFIGURATION.md](CONFIGURATION.md) 涵盖运行时设置，[MCP.md](MCP.md) 涵盖模型上下文协议（MCP，Model Context Protocol）集成。[PLUGIN_BUNDLES.md](../PLUGIN_BUNDLES.md) 涵盖默认禁用的包清单、能力审查和带命名空间的 Skill/MCP 激活边界。
+
+## 7. 使用工具
+
+Codewhale 的工具是结构化操作。模型不只是产出文字，还能调用工具来检查和改变工作区。
+
+工具支撑的工作示例包括：
+
+- 解释文件之前先读它。
+- 提出重构之前先搜索调用点。
+- 运行一条有重点的测试命令。
+- 应用一个小补丁。
+- 为并行调查打开一个子智能体。
+
+工具使用由模式、审批和沙箱策略约束。确切行为取决于当前模式和配置，但基本规则很简单：只读探索用 Plan 开始，常规改动用 Act，Full Access 留给受信任的自动化。
+
+工作区边界很重要。Codewhale 应该在你启动它的目录或你配置的工作区里工作。当任务应该留在仓库内时要说清楚：
+
+```text
+就检查并编辑此仓库下的文件。别触父目录和全局配置。
+```
+
+当命令需要网络、在工作区外写入或有风险的 shell 操作时，除非你配置了更宽松的行为，否则期待一个审批提示。
+
+好的工具指令是具体的：
+
+```text
+运行覆盖此解析器更改的最窄测试。
+如果失败，报告失败并在扩大测试范围之前停止。
+```
+
+避免在专注修复期间要求广泛的清理。较小的工具范围使对话记录更易于审查，最终的差异更易于合并。
+
+下一步：[TOOL_SURFACE.md](../TOOL_SURFACE.md) 列出工具面，[SANDBOX.md](../SANDBOX.md) 讲解沙箱行为。
+
+## 8. 子智能体与并行工作
+
+子智能体是后台子代理。父会话给子代理一个专注的任务，收到一个 agent id，然后可以在子代理运行时继续工作。
+
+主要的编排工具是：
+
+- `agent`：带任务和角色启动一个专注的子代理。子代理在后台运行，返回一份紧凑回执加转录句柄。
+
+你通常不需要直接调用这些工具。用自然语言请求并行工作：
+
+```text
+为 config 包打开一个只读探索器，为 TUI 提供商选择器打开另一个。让两者在规划修复之前返回文件引用和风险。
+```
+
+有用的角色包括：
+
+| 角色 | 适合 |
+| --- | --- |
+| `general` | 多步任务；未指定角色时的默认值 |
+| `explore` | 只读代码梳理 |
+| `plan` | 设计与迁移规划 |
+| `review` | 对已有改动的 bug 聚焦审查 |
+| `implementer` | 规格明确的编辑 |
+| `verifier` | 运行检查并报告通过/失败证据 |
+
+子智能体在可以干净切分工作的时候最有用。不要为微小编辑使用它们，也不要让多个智能体同时写入相同文件。
+
+### 长时间工作如何保持连贯
+
+跨越多个回合的工作不依赖无限增长的聊天转录。这是普通 Agent 行为——不需要打开任何东西，也没有单独的工作流要学：
+
+- 工作上下文在整个会话中保持加载。大段源材料和持久转录作为数据保存，智能体可以搜索和切片，有用的变量与导入跨回合存活。
+- Workflow 组合独立的 `task(...)` 调用和并行扇出。
+- `agent` 消息与后续动作直接协调活动的子代理。
+- 目标（Goals）在工作期间保留持久目标。
+
+`/rlm ` 把工作上下文指向一个特定文件或一段文本。历史上一度存在的动作形态 `rlm` 工具仍然注册着，只为了让旧会话能回放，并且刻意不教给新的模型回合。
+
+Codewhale 还可以在 `.codewhale/harness/state.json` 维护一个小型项目级账本：有证据支撑的提示备注、可复用的子代理简报和 skill 路由提示。之后的回合会把它当作不受信任的补充指导接收，绝不是权威或可执行指令。读取它是自动的；添加或删除条目要走正常的审批回执。它和个人记忆是分开的，绝不能保存密钥、草稿转录或未经证实的说法。
+
+下一步：[SUBAGENTS.md](SUBAGENTS.md) 涵盖角色、生命周期、并发和输出契约。
+
+## 9. 技能（Skills）
+
+技能是可复用的指令包。一个技能通常是 `SKILL.md` 文件，教 Codewhale 如何执行某个重复工作流、使用某类工具，或遵循某项项目约定。
+
+当任务有可重复的流程时使用技能：
+
+- 审查某一类 PR。
+- 处理某种文档或电子表格格式。
+- 遵循团队发布检查清单。
+- 使用项目特定的记忆或 wiki 工作流。
+
+在 TUI 里，`/skill ` 在可用时激活技能，裸 `/skills` 打开技能管理器（仅限自有清单，无网络）。用 `/skills `、`/skills inspect`、`/skills --remote`、`/skills suggest ` 或 `/skills sync` 走文本/注册表路径。建议会对远程目录排序，但绝不安装或激活任何东西。命令面板也能把技能条目和普通斜杠命令一起展示。
+
+知识贵广，技能贵精。它们应该告诉模型遵循什么工作流、收集什么证据、避免什么。它们不应该隐藏凭据或取代正常的仓库文档。
+
+如果仓库有自己的指令，把请将其当作活动工作的一部分。编辑前先读本地指南，并让你的贡献保持在仓库约定之内。
+
+下一步：见 [SKILLS.md](SKILLS.md) 了解管理器、所有权和来源规则；[CLAUDE_PLUGIN_COMPAT.md](../CLAUDE_PLUGIN_COMPAT.md) 了解 Claude Code 技能/插件兼容性；[CONFIGURATION.md](CONFIGURATION.md) 了解配置路径与项目权威。
+
+## 10. 获取帮助
+
+从 doctor 输出开始：
+
+```bash
+codewhale doctor
+```
+
+提交详细 issue 时用 JSON：
+
+```bash
+codewhale doctor --json
+```
+
+对于认证问题，用结构化的来源状态确认声明了什么。Doctor 刻意不检查环境、secret-store、钥匙串或 OAuth token 的值。当实时检查合适时，用 `codewhale doctor --probe-api` 选择加入（本地端点用 `--probe-local`）。
+
+对于提供商问题，确认活动的提供商和模型：
+
+```text
+/provider
+/model
+```
+
+会话又长又乱时，用 `/compact` 减轻上下文压力，或在同一工作区开一个新会话并总结你需要的东西。
+
+报告 issue 时，请包含：
+
+- Codewhale 版本。
+- 安装方式。
+- 操作系统和终端。
+- 提供商和模型。
+- 确切的命令或提示。
+- 相关的 doctor 输出。
+- 问题是否在新工作区里也出现。
+
+不要把 API key、私有源码或密钥粘贴进公开 issue。
+
+下一步：[OPERATIONS_RUNBOOK.md](../OPERATIONS_RUNBOOK.md) 有运维分诊与恢复步骤。
+
+## 常见问题（FAQ）
+
+### Codewhale 只支持 DeepSeek 吗？
+
+DeepSeek 是默认且一等的路由，但 Codewhale 也支持其他托管和本地的 OpenAI 兼容供应商。用 `/provider` 或 `codewhale --provider ` 选择供应商。配置非默认路由时，请打开提供商注册表参考。
+
+### 我应该先用哪个模式？
+
+陌生代码用 Plan，常规实现用 Act，只有在你信任、可以接受自动执行的仓库里才用 Full Access。
+
+### 为什么 Codewhale 运行命令前要问我？
+
+审批是安全模型的一部分。Shell 命令、付费工具、写入以及预期工作区之外的动作都可能产生副作用。审批提示让你在让模型做有用工作的同时保持控制。
+
+### 我如何在 macOS 上运行一个 Python 文件？
+
+在包含该文件的文件夹里打开终端并运行：
+
+```bash
+python3 your_file.py
+```
+
+如果 macOS 提示 `python3` 缺失，从 [python.org](https://www.python.org/downloads/macos/) 或 Homebrew 安装 Python：
+
+```bash
+brew install python
+```
+
+在 Codewhale 里，让智能体检查文件并用 `python3 your_file.py` 运行它。如果脚本需要包，先在虚拟环境里安装：
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install -r requirements.txt
+python3 your_file.py
+```
+
+### 我的配置存放在哪里？
+
+新的 Codewhale 配置使用 `~/.codewhale/config.toml`。旧的 `~/.deepseek/config.toml` 为兼容性仍然受支持。当工作区配置存在时，项目覆盖也可能影响行为。
+
+### 如何让成本可预测？
+
+用 `/model auto` 做路由，需要严格配置时选择固定模型，并压缩长会话。对更大的任务，让 Codewhale 先规划再实现，这样你就不会把 token 花在错误的路线上。
+
+### 如何继续之前的工作？
+
+Codewhale 会保存会话。用 README 和模式指南里讲到的会话选择器或 resume/continue CLI 路径。对于有风险的实验，在改变方向前先分叉（fork）会话。
+
+`/sessions` 选择器以当前工作区为范围启动，这样恢复会保持挂在打开的项目上。在选择器里按 `a` 显示所有工作区的会话，或在恢复某个特定 id 之前运行 `codewhale sessions` 列出所有已保存会话及其最后更新时间。
+
+要从网页应用继续当前正在运行的会话，输入 `/rc` 或用 `codewhale rc` 启动。在系统浏览器里批准一次性代码。租赁期生效期间，浏览器拥有新的提示和审批，终端是可读的安全面。连接后，横幅和一条转录备注会显示实时会话链接（`https://app.codewhale.net/session?run=…`）；`/rc open` 在浏览器里打开它，`/rc link` 打印它。`/rc status` 显示归属，`/rc stop` 把它交回终端，interrupt 仍然可用。断开的连接会保持本地输入锁定，直到最后一个网页租赁过期，这样两个控制器永远不会竞争。从一个终端登记的每个文件夹共享同一个稳定的设备 id，因此网页应用每台机器列出一台电脑，而不是每个会话一台。
+
+### 模型糊涂了，我该怎么办？
+
+停下来，重新陈述目标、约束和当前证据。如果转录很长，用 `/compact`，或带简短交接开一个新会话。如果是运维问题，运行 `codewhale doctor` 并检查报告的配置与提供商状态。
+
+### 项目规则应该放在提示里还是文件里？
+
+持久性的项目规则用仓库文件，回合特定的意图用提示。如果某个工作流跨项目重复出现，考虑把它做成技能。
+
+### Codewhale 能编辑当前仓库之外的文件吗？
+
+这取决于工作区边界、沙箱设置、信任模式和审批策略。做贡献工作时，让指令保持在当前仓库范围内，除非你确实需要别的。
+
+### 学完本指南后我该去哪？
+
+读与你正在改动的东西相关的重点参考。对大多数用户，接下来的页面是安装、配置、提供商、模式、快捷键、工具和子智能体。
+
+下一步：[INSTALL.md](INSTALL.md)、[CONFIGURATION.md](CONFIGURATION.md)、[PROVIDERS.md](PROVIDERS.md)、[MODES.md](MODES.md) 和 [TOOL_SURFACE.md](../TOOL_SURFACE.md)。