| 1 | # 安装 Codewhale |
| 2 | |
| 3 | > 英文原文：[INSTALL.md](../INSTALL.md)。 |
| 4 | > 最后与英文同步日期（last synced with English revision）：2026-09-29。本文按英文版当前结构（v0.10.0 安装实测版）整体重译；附录部分与英文一样，沿用上一版内容，未在 v0.10.0 上重测。 |
| 5 | |
| 6 | Codewhale 是一个在终端里运行的开源编码智能体（coding agent）。你交给它一个任务（"修复失败的测试"、"加一个 CLI 参数"），它会读取你的仓库、编辑文件并运行命令。在默认的 **Ask**（询问）权限级别下，它会立即应用工作区内的文件编辑（并给你看 diff），但运行 shell 命令之前会先询问，所以请先提交或暂存你在意的改动。它支持多家模型提供商，默认是 **DeepSeek**。 |
| 7 | |
| 8 | 命令是 `codewhale`。`codew` 是同一个程序的较短别名。 |
| 9 | |
| 10 | 本指南是在一台全新的 **Ubuntu 24.04 x86_64** 机器上安装 **v0.10.0**（2026-09-22 发布）时写成的，这里描述的每条路径都实际走过。文中每条命令都运行过，输出也核对过（见[安装回执](https://github.com/codewhale-hq/Codewhale/blob/37ecdfcc49bc68a9b0d058b97c3946e62c34bd31/docs/install-report/v0.10.0-2026-09-23/RECEIPTS.md)）。在那台机器上无法运行的步骤标注为 **（该虚拟机上未测试：原因）**。macOS、Windows 和 Android 不在测试范围内，只有少量说明。第二轮在 **macOS 26.1（Apple silicon）** 上重新运行了安装器、手动下载、压缩包和 npm 路径、无密钥检查以及 zsh 补全，见 [macOS 说明](#macos-说明)。需要调用模型的步骤没有在 macOS 上重跑。 |
| 11 | |
| 12 | 使用 `latest` 的安装命令会解析到最新**已发布**的 GitHub Release 或包。两次发布之间，`main` 可能已经在描述下一个版本（例如 2026-09-28 之前的 v0.10.1 源码候选版）。候选版在其标签、校验和与发布资源齐备之前，都不能安装。 |
| 13 | |
| 14 | --- |
| 15 | |
| 16 | ## 60 秒快速上手（Linux 或 macOS） |
| 17 | |
| 18 | ```bash |
| 19 | # 1. Install. Downloads two checksum-verified binaries into ~/.local/bin (no sudo). |
| 20 | curl -fsSL https://codewhale.net/install.sh | sh |
| 21 | |
| 22 | # 2. Make sure ~/.local/bin is on your PATH, now and in future terminals. |
| 23 | echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc # zsh: use ~/.zshrc |
| 24 | export PATH="$HOME/.local/bin:$PATH" |
| 25 | codewhale --version # -> codewhale 0.10.0 (1be1a703b975) |
| 26 | |
| 27 | # 3. Give it a DeepSeek API key (from https://platform.deepseek.com/api_keys). |
| 28 | codewhale auth set --provider deepseek # prompts for the key; nothing is echoed |
| 29 | codewhale auth status --provider deepseek # "active source: secret store" |
| 30 | |
| 31 | # 4. Run your first task inside a git repository. |
| 32 | cd ~/your-project |
| 33 | codewhale |
| 34 | ``` |
| 35 | |
| 36 | 在 TUI 里输入一句具体的话： |
| 37 | |
| 38 | ```text |
| 39 | create a Python file primes.py that prints the first 10 primes, run it, and show me the output |
| 40 | ``` |
| 41 | |
| 42 | Codewhale 会写出文件、给你看 diff，然后询问 **APPROVAL: bash python3 primes.py – Do you want to proceed?**。按 `y` 允许本次执行。它会运行该命令并报告输出。（输入框为空时）按 `Ctrl-D` 退出，它会打印出之后恢复该会话的命令。 |
| 43 | |
| 44 | > **如果发送第一条消息后没有任何反应，** 说明你还没有配置密钥。v0.10.0 在这种情况下不会给出警告。按 **F3**。如果 DeepSeek 显示 `missing key`，按 Enter，粘贴密钥，然后选择模型并确认。 |
| 45 | |
| 46 | --- |
| 47 | |
| 48 | ## 目录 |
| 49 | |
| 50 | 1. [开始之前](#1-开始之前) |
| 51 | 2. [安装：推荐的安装器](#2-推荐的安装器curl--sh) |
| 52 | 3. [安装：从 GitHub Releases 手动下载](#3-从-github-releases-手动下载) |
| 53 | 4. [安装：npm](#4-npm) |
| 54 | 5. [安装：Cargo / 从源码构建](#5-cargo-与从源码构建) |
| 55 | 6. [安装：Homebrew（Linux）与 Nix](#6-linux-上的-homebrew-与-nix) |
| 56 | 7. [更新与回滚](#7-更新与回滚) |
| 57 | 8. [API 密钥与提供商](#8-api-密钥与提供商) |
| 58 | 9. [Shell 补全](#9-shell-补全) |
| 59 | 10. [运行：TUI、无头模式、恢复会话](#10-运行) |
| 60 | 11. [终端说明（Ghostty 及其他）](#11-终端说明) |
| 61 | 12. [卸载，以及 Codewhale 留下了什么](#12-卸载) |
| 62 | 13. [故障排查](#13-故障排查) |
| 63 | 14. [附录：其他平台（本版未重测）](#附录其他平台本版未重测) |
| 64 | |
| 65 | --- |
| 66 | |
| 67 | ## 1. 开始之前 |
| 68 | |
| 69 | | 你需要 | 原因 | |
| 70 | |---|---| |
| 71 | | Linux x86_64 或 arm64，或 macOS | 这些平台有预编译二进制。Linux 二进制是**静态**链接的（musl），没有 glibc 或 libdbus 依赖，可在任何发行版上运行。 | |
| 72 | | `curl`（或 `wget`）和 `sha256sum`（或 `shasum`） | 安装器用它们下载并校验。 | |
| 73 | | 一个模型提供商的密钥，例如 [DeepSeek](https://platform.deepseek.com/api_keys) | 没有模型，Codewhale 什么用都没有。 | |
| 74 | | `git`（推荐） | Codewhale 在 git 仓库里效果最好。 | |
| 75 | | 可选：Python 3、Node.js 20+ | 如果存在，Codewhale 会启用它的 Python 和 JS 执行工具（`codewhale doctor` 会列出它们）。 | |
| 76 | |
| 77 | **该选哪条安装路径？** |
| 78 | |
| 79 | * **大多数人：** [推荐的安装器](#2-推荐的安装器curl--sh)。它最快（在测试机上约 6 秒），会校验校验和，并支持 `codewhale update`。 |
| 80 | * **隔离网络（air-gapped）或需要安全审查的机器：** [手动下载](#3-从-github-releases-手动下载)。 |
| 81 | * **你已经用 npm 管理命令行工具：** [npm](#4-npm)。 |
| 82 | * **你的平台没有预编译二进制，或者想自己构建：** [Cargo](#5-cargo-与从源码构建)。 |
| 83 | |
| 84 | **只选一种。** 同一台机器上装了多份，最后会在 PATH 上互相打架（见[故障排查](#13-故障排查)）。 |
| 85 | |
| 86 | **隐私说明：** Codewhale **默认**会发送聚合的使用次数统计（PostHog）。要永久关闭：运行 `codewhale config set telemetry false`，或者导出 `CODEWHALE_TELEMETRY=0`（它始终优先）。TUI 启动时还会检查 GitHub 上是否有更新（`~/.codewhale/config.toml` 中的 `[update] check_for_updates`）。 |
| 87 | |
| 88 | --- |
| 89 | |
| 90 | <a id="recommended-official-github-releases"></a> |
| 91 | |
| 92 | ## 2. 推荐的安装器（`curl | sh`） |
| 93 | |
| 94 | **前置条件：** curl、`sha256sum`（Linux）或 macOS 自带的 `shasum`，以及一个可写的主目录。不需要 sudo、Node 或 Rust。 |
| 95 | |
| 96 | ```bash |
| 97 | curl -fsSL https://codewhale.net/install.sh | sh |
| 98 | ``` |
| 99 | |
| 100 | 它做了什么（已验证）： |
| 101 | |
| 102 | * 检测你的平台（`linux-x64`、`linux-arm64`、`macos-x64`、`macos-arm64`）。对 Android/Termux 和 riscv64，它会给出明确提示并拒绝安装。 |
| 103 | * 从最新的 GitHub Release 下载 `codewhale-<platform>`、`codew-<platform>` 和 `codewhale-artifacts-sha256.txt`，并对照清单校验两个二进制。只要有一个不匹配，就会在安装任何东西之前停止（`codewhale install: checksum mismatch for …`）。 |
| 104 | * 安装 `~/.local/bin/codewhale` 和 `~/.local/bin/codew`：两个内容相同的 78 MB 文件。 |
| 105 | * **从不使用 sudo，也从不修改你的 shell 配置文件。** 它拒绝安装到系统或包管理器目录（`/usr/bin`、`~/.cargo/bin`、Homebrew、`node_modules`、`/nix/store` 等），也拒绝覆盖一个*不同的*已有 `codewhale`。 |
| 106 | |
| 107 | 预期输出： |
| 108 | |
| 109 | ``` |
| 110 | Installing Codewhale for linux-x64 |
| 111 | Release assets: https://github.com/codewhale-hq/CodeWhale/releases/latest/download |
| 112 | Install dir: /home/you/.local/bin |
| 113 | Checksums verified |
| 114 | Installed checksummed release commands: |
| 115 | /home/you/.local/bin/codewhale |
| 116 | /home/you/.local/bin/codew |
| 117 | … |
| 118 | PATH selects no codewhale command; this install is /home/you/.local/bin/codewhale |
| 119 | … |
| 120 | Put /home/you/.local/bin first on PATH in future shells (run once; this installer does not edit shell profiles): |
| 121 | echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc |
| 122 | Then run: . ~/.bashrc (or open a new terminal) |
| 123 | … |
| 124 | ``` |
| 125 | |
| 126 | ### macOS 说明 |
| 127 | |
| 128 | 在 macOS 26.1、Apple silicon（`macos-arm64`）上，用全新的 `HOME` 重新检查过： |
| 129 | |
| 130 | * 安装器打印了 `Installing Codewhale for macos-arm64`，用系统自带工具校验了校验和，并在 4.3 秒内装好了 `codewhale` 和 `codew`（各 64 MiB，Mach-O arm64）。两者都报告 `codewhale 0.10.0 (1be1a703b975)`。运行时没有弹出 Gatekeeper 提示。 |
| 131 | * 当 `PATH` 上没有 Node 时，它还会打印 `Computer Use is included and needs Node.js 20 or newer on PATH.`。核心 TUI 没有 Node 也能用，但在 `PATH` 上有 Node 之前，Computer Use 和 JavaScript 执行工具（`js_execution`）不可用。 |
| 132 | * `codewhale doctor` 的行为与 Linux 相同（退出码 0；没有密钥时输出 `All checks complete!`；文件型密钥存储位于 `~/.codewhale/secrets/`），只是它会报告 `✓ sandbox available: macos-seatbelt`。 |
| 133 | |
| 134 | ### 把它加入 PATH |
| 135 | |
| 136 | 如果安装器提示 `PATH selects no codewhale command`，说明 `~/.local/bin` **在当前 shell 里**不在 PATH 上。此时 `codewhale.net/install.sh` 安装器会根据你的 `$SHELL`（zsh、bash、fish 或 POSIX `sh`），打印下面这个代码块里对应的那一行；对于其他 shell，或者目录名含有引号、`$`、反引号或反斜杠的情况，它会让你自己添加该目录。它自己从不修改 shell 配置文件。发布压缩包内的 `install.sh` 只会打印针对当前 shell 的 `export` 行。在 Ubuntu 和 Debian 上，`~/.profile` 会加入 `~/.local/bin`，但前提是该目录在你*登录*时已经存在。所以： |
| 137 | |
| 138 | * 新开的 SSH 会话或登录 shell 会自动生效； |
| 139 | * 桌面上新开的终端**窗口**（GNOME Terminal、Ghostty 等）通常不会，要等到你注销再登录。我刚装完就在 Ghostty 里遇到了 `bash: codewhale: command not found`。 |
| 140 | |
| 141 | 一次性修复： |
| 142 | |
| 143 | ```bash |
| 144 | echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc # bash (macOS login bash: ~/.bash_profile, or ~/.profile if only that exists) |
| 145 | # echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc # zsh |
| 146 | # fish_add_path ~/.local/bin # fish (untested on this VM) |
| 147 | export PATH="$HOME/.local/bin:$PATH"; hash -r |
| 148 | command -v codewhale codew |
| 149 | ``` |
| 150 | |
| 151 | ### 选项 |
| 152 | |
| 153 | ```bash |
| 154 | # Choose the directory (must be absolute; created if missing) |
| 155 | curl -fsSL https://codewhale.net/install.sh | CODEWHALE_INSTALL_DIR="$HOME/.local/codewhale/bin" sh |
| 156 | # Install a specific release |
| 157 | curl -fsSL https://codewhale.net/install.sh | CODEWHALE_VERSION=v0.9.13 sh |
| 158 | # Show help |
| 159 | curl -fsSL https://codewhale.net/install.sh | sh -s -- --help |
| 160 | ``` |
| 161 | |
| 162 | （注释含义：选择目录，必须是绝对路径，不存在则创建；安装指定版本；显示帮助。） |
| 163 | |
| 164 | ### 验证 |
| 165 | |
| 166 | ```bash |
| 167 | codewhale --version # codewhale 0.10.0 (1be1a703b975) |
| 168 | codew --version # same |
| 169 | codewhale doctor # diagnostics; see the note in §8 about what it does NOT check |
| 170 | ``` |
| 171 | |
| 172 | ### 重新运行安装器 |
| 173 | |
| 174 | * 已安装的就是同一版本：无害。它会打印 `Already installed: …` 并以 0 退出。 |
| 175 | * 已安装的是不同版本：它会**拒绝**（`codewhale install: refusing to replace existing …/codewhale`），以 1 退出，并且不改动任何东西。拒绝之前它已经下载了约 160 MB。请改用 [`codewhale update`](#7-更新与回滚)。 |
| 176 | |
| 177 | ### 升级 / 卸载 |
| 178 | |
| 179 | * 升级：`codewhale update`（见 §7）。 |
| 180 | * 卸载：`rm ~/.local/bin/codewhale ~/.local/bin/codew`，数据的清理见 §12。 |
| 181 | |
| 182 | --- |
| 183 | |
| 184 | ## 3. 从 GitHub Releases 手动下载 |
| 185 | |
| 186 | 当你想亲自查看并校验每一个字节时使用。发布页：<https://github.com/codewhale-hq/CodeWhale/releases>。每个平台都有**裸二进制**（`codewhale-linux-x64`、`codew-linux-x64` 等）和一个**压缩包**（`codewhale-linux-x64.tar.gz`），压缩包里是同样的两个二进制外加一个 `install.sh`。 |
| 187 | |
| 188 | ### 3a. 裸二进制 |
| 189 | |
| 190 | ```bash |
| 191 | mkdir -p ~/codewhale-dl && cd ~/codewhale-dl |
| 192 | base=https://github.com/codewhale-hq/CodeWhale/releases/latest/download |
| 193 | curl -fsSLO "$base/codewhale-linux-x64" # use linux-arm64 on ARM |
| 194 | curl -fsSLO "$base/codew-linux-x64" |
| 195 | curl -fsSLO "$base/codewhale-artifacts-sha256.txt" |
| 196 | sha256sum -c codewhale-artifacts-sha256.txt --ignore-missing |
| 197 | # codew-linux-x64: OK |
| 198 | # codewhale-linux-x64: OK |
| 199 | mkdir -p ~/.local/bin |
| 200 | install -m 755 codewhale-linux-x64 ~/.local/bin/codewhale |
| 201 | install -m 755 codew-linux-x64 ~/.local/bin/codew |
| 202 | ``` |
| 203 | |
| 204 | 然后[把 `~/.local/bin` 加入 PATH](#把它加入-path)并运行 `codewhale --version`。在 macOS 上，资源名是 `codewhale-macos-arm64` 和 `codew-macos-arm64`（Intel 上是 `-macos-x64`），可以用系统自带的 `shasum` 校验（已在 macOS 26.1、Apple silicon 上测试）： |
| 205 | |
| 206 | ```bash |
| 207 | /usr/bin/shasum -a 256 -c codewhale-artifacts-sha256.txt --ignore-missing |
| 208 | # codew-macos-arm64: OK |
| 209 | # codewhale-macos-arm64: OK |
| 210 | ``` |
| 211 | |
| 212 | `codewhale-macos-arm64.tar.gz` 压缩包同样可以对照 `codewhale-bundles-sha256.txt` 校验，其中的 `./install.sh` 会安装到 `~/.local/bin`（已测试）。 |
| 213 | |
| 214 | 要固定某个版本，把 `latest/download` 换成 `download/vX.Y.Z`，并从同一个标签下取校验清单。 |
| 215 | |
| 216 | ### 3b. 压缩包 |
| 217 | |
| 218 | ```bash |
| 219 | cd "$(mktemp -d)" |
| 220 | base=https://github.com/codewhale-hq/CodeWhale/releases/latest/download |
| 221 | curl -fsSLO "$base/codewhale-linux-x64.tar.gz" |
| 222 | curl -fsSLO "$base/codewhale-bundles-sha256.txt" # note: *bundles*, not *artifacts* |
| 223 | sha256sum -c codewhale-bundles-sha256.txt --ignore-missing |
| 224 | # codewhale-linux-x64.tar.gz: OK |
| 225 | tar -xzf codewhale-linux-x64.tar.gz |
| 226 | cd codewhale-linux-x64 && ./install.sh # -> ~/.local/bin; PREFIX=/some/dir ./install.sh -> /some/dir/bin |
| 227 | ``` |
| 228 | |
| 229 | （注意：校验清单是 *bundles*，不是 *artifacts*。） |
| 230 | |
| 231 | 压缩包里的 `install.sh` 与网站上的安装器行为一致：不用 sudo，不动内容不同的已有文件，并打印同样的 PATH 提示。 |
| 232 | |
| 233 | **升级：** `codewhale update` 对 3a 和 3b 都适用，因为它们都属于"直接二进制"安装。**卸载：** 删除那两个文件（见 §12）。 |
| 234 | |
| 235 | --- |
| 236 | |
| 237 | ## 4. npm |
| 238 | |
| 239 | **前置条件：** Node.js 18+ 和 npm，并且有一个**你能写入的全局 prefix**。npm 安装的是注册表上最新已发布的版本，绝不会是未发布的源码候选版。 |
| 240 | |
| 241 | ```bash |
| 242 | npm install -g codewhale |
| 243 | codewhale --version |
| 244 | ``` |
| 245 | |
| 246 | 这个包是一个很小的包装器。它的 `postinstall` 步骤会下载同样的 `codewhale`/`codew` 发布二进制，对照该发布的 SHA-256 清单校验，并把 `codewhale` 和 `codew` 链接到 npm 的全局 `bin`。整个过程在测试机上用了 6 秒。 |
| 247 | |
| 248 | ### 如果遇到 `EACCES: permission denied` |
| 249 | |
| 250 | 这说明 Node 是系统级安装的（apt、`/usr/local`、`/opt`），而你的用户无权写入它的全局 prefix： |
| 251 | |
| 252 | ``` |
| 253 | npm error code EACCES |
| 254 | npm error Error: EACCES: permission denied, mkdir '/opt/node22/lib/node_modules/codewhale' |
| 255 | ``` |
| 256 | |
| 257 | **不要用 `sudo npm`。** 要么使用每用户的 Node（nvm、fnm、volta），要么把 npm 指向一个你自己拥有的目录。我测试了第二种方式： |
| 258 | |
| 259 | ```bash |
| 260 | npm config set prefix "$HOME/.npm-global" |
| 261 | echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc |
| 262 | export PATH="$HOME/.npm-global/bin:$PATH" |
| 263 | npm install -g codewhale |
| 264 | command -v codewhale codew # ~/.npm-global/bin/codewhale, ~/.npm-global/bin/codew |
| 265 | ``` |
| 266 | |
| 267 | ### 说明 |
| 268 | |
| 269 | * npm 会隐藏下载进度。加上 `--foreground-scripts` 可以看到（`codewhale: selected GitHub Releases for v0.10.0 … done.`）。所选来源也会写入 `$(npm prefix -g)/lib/node_modules/codewhale/bin/downloads/codewhale.source`。 |
| 270 | * 该包在磁盘上占用 157 MB。 |
| 271 | * 在 macOS 26.1（Apple silicon，Homebrew 的 Node 25）上，安装到用户自有的 prefix（`npm install -g --prefix <dir> codewhale`）用了 3 秒，并链接了 `codewhale` 和 `codew`，两者都是 `codewhale 0.10.0 (1be1a703b975)`。 |
| 272 | * **升级：** `npm install -g codewhale@latest`。`codewhale update` 会拒绝处理 npm 安装：它打印迁移说明，并以 1 退出，输出 `error: The package-managed executable was not changed.`。 |
| 273 | * **指定版本：** `npm install -g codewhale@0.9.13`。 |
| 274 | * **卸载：** `npm uninstall -g codewhale`。它只删除程序本身，不删除你的数据（见 §12）。 |
| 275 | |
| 276 | --- |
| 277 | |
| 278 | <a id="4-install-via-cargo-any-tier-1-rust-target"></a><a id="7-build-from-source"></a><a id="4-通过-cargo-安装任何-tier-1-rust-目标"></a><a id="7-从源码构建"></a> |
| 279 | |
| 280 | ## 5. Cargo 与从源码构建 |
| 281 | |
| 282 | 如果你的平台没有预编译二进制，或者你想自己编译，就用这条路径。只需要一个 Cargo 包：`codewhale-cli` 会安装 `codewhale` 命令。npm 和预编译发布版还会把 `codew` 作为同一个已编译运行时的便捷名称提供；Cargo 不会创建这个别名，所以如果想用短名字，请在 shell 的 rc 文件里加上 `alias codew=codewhale`。 |
| 283 | |
| 284 | ### 前置条件（Debian/Ubuntu） |
| 285 | |
| 286 | ```bash |
| 287 | sudo apt-get install -y build-essential pkg-config libdbus-1-dev git |
| 288 | # Rust via rustup (the distro's cargo is too old for this edition-2024 workspace) |
| 289 | curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y |
| 290 | source "$HOME/.cargo/env" |
| 291 | rustc --version # the workspace declares rust-version = 1.89 |
| 292 | ``` |
| 293 | |
| 294 | （注释含义：发行版自带的 cargo 太旧，无法构建这个 edition-2024 的 workspace；workspace 声明的 rust-version 为 1.89。） |
| 295 | |
| 296 | `libdbus-1-dev` **是必需的**。没有它，构建会在大约一分钟后失败： |
| 297 | |
| 298 | ``` |
| 299 | error: failed to run custom build command for `libdbus-sys v0.2.7` |
| 300 | The system library `dbus-1` required by crate `libdbus-sys` was not found. |
| 301 | ``` |
| 302 | |
| 303 | Fedora/RHEL：`sudo dnf install -y gcc make pkgconf-pkg-config dbus-devel` **（该虚拟机上未测试：只有 Ubuntu）**。 |
| 304 | |
| 305 | ### 5a. 从 crates.io 安装 |
| 306 | |
| 307 | ```bash |
| 308 | cargo install codewhale-cli --locked |
| 309 | codewhale --version |
| 310 | ``` |
| 311 | |
| 312 | 测试结果：用当前 stable Rust（1.98.1）**可行**。 |
| 313 | * 在 4 vCPU、15 GB 内存的机器上用了 **25 分 31 秒**，向 `~/.cargo/registry` 拉取了约 470 MB。 |
| 314 | * 它安装一个 122 MB 的文件 `~/.cargo/bin/codewhale`。这是普通的 glibc 链接二进制，运行时需要 `libdbus-1`。 |
| 315 | * `codewhale --version` 打印 `codewhale 0.10.0`，不带 commit 哈希。 |
| 316 | * 无头模式和 TUI 冒烟测试通过。 |
| 317 | |
| 318 | > **v0.10.0 声明的"Rust 1.88+"是错的，工作区现在声明 1.89（CI 的 MSRV 任务所构建的版本）。** 用 1.88.0 时，安装会在几秒内失败： |
| 319 | > `rustc 1.88.0 is not supported by the following package: serde-saphyr@1.3.0 requires rustc 1.89`。 |
| 320 | > 请使用当前 stable（`rustup update stable`）。 |
| 321 | |
| 322 | ### 5b. 从 git 检出构建 |
| 323 | |
| 324 | ```bash |
| 325 | git clone --depth 1 --branch v0.10.0 https://github.com/codewhale-hq/CodeWhale.git |
| 326 | cd CodeWhale |
| 327 | cargo install --path crates/cli --locked # installs ~/.cargo/bin/codewhale |
| 328 | ``` |
| 329 | |
| 330 | 需要知道的事（实际观察到的）： |
| 331 | |
| 332 | * 仓库里有 `rust-toolchain.toml`（`channel = "stable"`）。在检出目录里运行的第一条 `cargo` 命令，无论你的默认工具链是什么，都会**悄悄下载最新的 stable 工具链**（约 250 MB）。 |
| 333 | * workspace 把所有编译器警告都当作错误。用 Rust 1.89 时，构建会在大约 11 分钟后**失败**，在 `codewhale-tui` 中出现 8 个 `error: this lint expectation is unfulfilled`。请使用仓库选定的 stable 工具链，不要传入更旧的 `+toolchain`。 |
| 334 | * workspace 的 release profile 使用 thin LTO。在 4 vCPU / 15 GB 的虚拟机上，仅 `codewhale-tui` 这一个 crate 就编译了一个多小时，内存峰值 6–8 GB。请准备 16 GB 或更多内存，并预期这是迄今最慢的安装路径。`target/` 增长超过了 1.2 GB。 |
| 335 | |
| 336 | 测试结果：用仓库选定的 stable Rust（1.98.1）**可行**。 |
| 337 | * `Finished release profile … in 83m 12s`。其间大部分时间有一个 Nix 构建在争抢 CPU 和内存，所以请把它当作上限。 |
| 338 | * `target/` 最终达到 **3.1 GB**。之后用 `cargo clean` 删除。 |
| 339 | * 该二进制报告 `codewhale 0.10.0 (dev)`，`exec` 可用。 |
| 340 | * Cargo 会打印 `warning: default toolchain implicitly overridden with stable-x86_64-unknown-linux-gnu by rustup toolchain file`，这是无害的。 |
| 341 | * **Cargo 构建不提供 `codew`。** |
| 342 | |
| 343 | **升级：** 重新运行同样的 `cargo install … --force`（对 crates.io 可以加 `--version X.Y.Z`）。`codewhale update` 会拒绝处理 Cargo 安装。**卸载：** `cargo uninstall codewhale-cli`，然后见 §12。 |
| 344 | |
| 345 | --- |
| 346 | |
| 347 | ## 6. Linux 上的 Homebrew 与 Nix |
| 348 | |
| 349 | ### Linux 上的 Homebrew：可行，但不是旧文档给的那条命令 |
| 350 | |
| 351 | 前置条件：Homebrew 本身。它的安装器需要**一次** sudo，用来创建 `/home/linuxbrew/.linuxbrew`。没有 sudo 权限时，它会停在 `Insufficient permissions to install Homebrew to "/home/linuxbrew/.linuxbrew"`。请管理员运行 `sudo mkdir -p /home/linuxbrew/.linuxbrew && sudo chown $USER /home/linuxbrew/.linuxbrew`，然后重新运行安装器。之后，按它的 "Next steps" 提示，把 `eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv bash)"` 加入 `~/.bashrc`。 |
| 352 | |
| 353 | ```bash |
| 354 | brew install Hmbown/deepseek-tui/codewhale # full name: taps and trusts in one step |
| 355 | ``` |
| 356 | |
| 357 | （注释含义：使用完整名称，一步完成 tap 和信任。） |
| 358 | |
| 359 | 两步写法（先 `brew tap Hmbown/deepseek-tui`，再 `brew install codewhale`）在 **Homebrew 7.x 上会失败**： |
| 360 | |
| 361 | ``` |
| 362 | Error: Refusing to load formula hmbown/deepseek-tui/codewhale from untrusted tap hmbown/deepseek-tui. |
| 363 | Run `brew trust --formula hmbown/deepseek-tui/codewhale` or `brew trust hmbown/deepseek-tui` to trust it. |
| 364 | ``` |
| 365 | |
| 366 | 先运行 `brew trust hmbown/deepseek-tui`，或者使用上面的完整名称。 |
| 367 | |
| 368 | 用 Homebrew 7.0.6 对照 v0.10.0 的 tap formula 测试过：安装用了 73 秒。tap formula 跟踪最新发布并下载官方发布二进制，所以不需要编译。它**同时**提供 `codewhale` 和 `codew`。`Hmbown/deepseek-tui` 这个 tap 的 formula 还依赖 `node`，在 Linux 上拉了 31 个 bottle（约 560 MB）。这个 `node` 依赖只属于该 tap formula。核心 TUI 没有 Node 也能运行；Computer Use 和 JS 执行工具在 PATH 上有 Node 时会使用它。 |
| 369 | |
| 370 | * **升级：** `brew upgrade codewhale`。（`codewhale update` 会拒绝，并建议迁移。） |
| 371 | * **卸载：** `brew uninstall codewhale && brew untap Hmbown/deepseek-tui`。这也会自动移除该 tap 的 node 依赖以及它拉进来的其他东西。Homebrew 的下载缓存（`~/.cache/Homebrew`，约 330 MB）会保留，直到运行 `brew cleanup --prune=all`。 |
| 372 | |
| 373 | ### Nix：部分测试 |
| 374 | |
| 375 | ```bash |
| 376 | # flakes are still experimental; the tested setup enabled them once: |
| 377 | mkdir -p ~/.config/nix |
| 378 | echo 'experimental-features = nix-command flakes' >> ~/.config/nix/nix.conf |
| 379 | nix run github:codewhale-hq/CodeWhale -- --version |
| 380 | # one-off alternative (untested on this VM): nix --extra-experimental-features 'nix-command flakes' run github:codewhale-hq/CodeWhale -- --version |
| 381 | ``` |
| 382 | |
| 383 | （注释含义：flakes 仍是实验特性，测试环境一次性启用了它；一次性替代写法在该虚拟机上未测试。） |
| 384 | |
| 385 | Nix 2.35 安装正常；单用户模式需要先由 root 创建一次 `/nix`。flakes 解析成功。我在停止之前了解到： |
| 386 | |
| 387 | * **没有二进制缓存**，所以这是对 **main 分支**的完整源码构建，而不是 v0.10.0 发布版。该二进制报告 `codewhale 0.10.0 (dev)`。 |
| 388 | * 构建步骤在 4 核上用了 30 分钟。之后这个包会运行它的**测试套件**（`doCheck`），以测试模式重新编译 workspace。这花了超过 70 分钟，单个 rustc 进程占用超过 8 GB 内存，我在 105 分钟时停止了。因此 `nix run` 跑完、`nix build` 以及 `nix profile install/remove` 都**（该虚拟机上未测试：构建没能在时间预算内完成；该虚拟机的代理还需要 `--override-input fenix …` 这个变通办法）**。 |
| 389 | * Nix 只提供 `codewhale`，没有 `codew`（它只构建 `codewhale-cli` 包）。 |
| 390 | |
| 391 | 除非你本来就用 Nix，否则请改用 §2。 |
| 392 | |
| 393 | --- |
| 394 | |
| 395 | ## 7. 更新与回滚 |
| 396 | |
| 397 | 这些适用于通过 §2 和 §3 安装的（直接二进制）。由包管理器安装的（npm、Cargo、Homebrew）必须用各自的工具更新。 |
| 398 | |
| 399 | ```bash |
| 400 | codewhale update --check |
| 401 | # Current binary: /home/you/.local/bin/codewhale |
| 402 | # Current version: v0.9.13 |
| 403 | # Latest stable release: v0.10.0 |
| 404 | # Update available. Run `/home/you/.local/bin/codewhale update` to install v0.10.0. |
| 405 | codewhale update |
| 406 | # Downloading codewhale-linux-x64... |
| 407 | # SHA256 checksum verified against codewhale-artifacts-sha256.txt from GitHub Releases. |
| 408 | # ✅ Successfully updated to v0.10.0! |
| 409 | # Updated binaries: |
| 410 | # - /home/you/.local/bin/codewhale (codewhale-linux-x64) |
| 411 | # - /home/you/.local/bin/codew (codewhale-linux-x64) |
| 412 | ``` |
| 413 | |
| 414 | 它会把 `codewhale` **和** `codew` 一起更新，在测试机上用了 10 秒。再运行一次会得到 `Already up to date; no download needed.`。其他选项：`--beta` 和 `--proxy <URL>`。 |
| 415 | |
| 416 | <a id="roll-back-to-a-previous-release"></a> |
| 417 | |
| 418 | ### 回滚（例如回到 v0.9.13） |
| 419 | |
| 420 | `codewhale update` 从不降级，`CODEWHALE_VERSION=0.9.13 codewhale update` 也只会说 "Already up to date"。要回滚，请替换文件： |
| 421 | |
| 422 | ```bash |
| 423 | dir="$(dirname "$(command -v codewhale)")" # the install PATH actually selects |
| 424 | rm "$dir/codewhale" "$dir/codew" |
| 425 | curl -fsSL https://codewhale.net/install.sh | CODEWHALE_VERSION=v0.9.13 CODEWHALE_INSTALL_DIR="$dir" sh |
| 426 | hash -r; codewhale --version # codewhale 0.9.13 (a0b81f619b66) |
| 427 | ``` |
| 428 | |
| 429 | （注释含义：`dir` 是 PATH 实际选中的安装目录。） |
| 430 | |
| 431 | 默认的 `~/.local/bin` 和自定义的 `CODEWHALE_INSTALL_DIR` 都测试过。只对通过安装器、手动下载或压缩包安装的使用它。绝不要把它指向 npm、Cargo 或 Homebrew 的目录。 |
| 432 | |
| 433 | 或者让两个版本并存，把旧版本放在 PATH 最前面： |
| 434 | |
| 435 | ```bash |
| 436 | curl -fsSL https://codewhale.net/install.sh | CODEWHALE_VERSION=v0.9.13 CODEWHALE_INSTALL_DIR="$HOME/.local/codewhale-0.9.13" sh |
| 437 | export PATH="$HOME/.local/codewhale-0.9.13:$PATH"; hash -r |
| 438 | ``` |
| 439 | |
| 440 | 原地回滚之后要回到最新版，运行 `codewhale update`。（已测试：0.9.13 → 0.10.0。） |
| 441 | |
| 442 | npm：`npm install -g codewhale@0.9.13`。Cargo：`cargo install codewhale-cli --version 0.9.13 --locked --force` **（该虚拟机上未测试：只构建过 0.10.0）**。 |
| 443 | |
| 444 | --- |
| 445 | |
| 446 | ## 8. API 密钥与提供商 |
| 447 | |
| 448 | ### Codewhale 到哪里找密钥（先匹配到的优先） |
| 449 | |
| 450 | 1. 命令行上的 `--api-key <KEY>` |
| 451 | 2. `~/.codewhale/config.toml` 中的 `api_key` |
| 452 | 3. `codewhale auth set` 写入的密钥存储 |
| 453 | 4. 环境变量（DeepSeek 用 `DEEPSEEK_API_KEY`） |
| 454 | |
| 455 | 这个顺序很重要。**配置文件或密钥存储里的密钥，优先于 `DEEPSEEK_API_KEY`。** 如果你靠导出新的环境变量来轮换密钥，之前存下的旧密钥仍然会被继续使用。我测试过：`config.toml` 里是错误的密钥，环境变量里是正确的密钥，结果是 `Authentication Fails … ****beef is invalid`。 |
| 456 | |
| 457 | ### 设置 DeepSeek 密钥的方式（都已测试） |
| 458 | |
| 459 | **环境变量。** 适合试用和 CI： |
| 460 | ```bash |
| 461 | export DEEPSEEK_API_KEY=sk-... # add to ~/.bashrc / ~/.zshenv to persist |
| 462 | ``` |
| 463 | |
| 464 | **`auth set`。** 为所有目录保存密钥： |
| 465 | ```bash |
| 466 | codewhale auth set --provider deepseek # prompts: "Enter API key for deepseek:" |
| 467 | printf '%s\n' "$KEY" | codewhale auth set --provider deepseek --api-key-stdin # scripted |
| 468 | # -> saved API key for deepseek to file-based ("/home/you/.codewhale/secrets/secrets.json") (config contains metadata only) |
| 469 | ``` |
| 470 | 文件型存储的这条消息会打印解析出的密钥存储路径；显式设置 `CODEWHALE_HOME` 会改变这个位置。 |
| 471 | |
| 472 | 在 Linux 上，密钥以**明文**存放在 `~/.codewhale/secrets/secrets.json` 中，权限为 0600，不在操作系统的钥匙串（keyring）里。请注意，在 v0.10.0 中，`auth set` 还会往你的配置里写入 `default_text_model = "deepseek-v4-pro"`，把你从默认的 `deepseek-flash` 切换到更贵的 Pro 模型。可以在 TUI 里用 `/model` 改回去，或者编辑 `~/.codewhale/config.toml`。 |
| 473 | |
| 474 | **在 TUI 里。** 按 **F3**（或输入 `/provider`），选择 DeepSeek，按 Enter，粘贴密钥（会被遮蔽），选择模型并确认。这同样会写入密钥存储，并保持使用 `deepseek-flash`。 |
| 475 | |
| 476 | **配置文件。** `~/.codewhale/config.toml`： |
| 477 | ```toml |
| 478 | [providers.deepseek] |
| 479 | api_key = "sk-..." |
| 480 | ``` |
| 481 | |
| 482 | ### 查看当前生效的是哪个密钥 |
| 483 | |
| 484 | ```bash |
| 485 | codewhale auth status --provider deepseek |
| 486 | # active source: env (last4: ...xxxx) # or: secret store / config / missing |
| 487 | # lookup order: config -> secret store -> env |
| 488 | codewhale doctor --probe-api |
| 489 | # · Testing connection... ✓ API connection successful |
| 490 | ``` |
| 491 | |
| 492 | 请用 `auth status`。单独运行 `codewhale doctor` **不会**告诉你：即使密钥已设置，它也会打印 `deepseek: env_source=not inspected`；即使找不到密钥，它也以 0 退出。 |
| 493 | |
| 494 | ### 删除已保存的密钥 |
| 495 | |
| 496 | ```bash |
| 497 | codewhale auth clear --provider deepseek |
| 498 | # cleared API key for deepseek from config and secret store |
| 499 | ``` |
| 500 | |
| 501 | 它不会取消你 shell 里的 `DEEPSEEK_API_KEY`，也会保留 `auth set` 添加的那行 `default_text_model`。 |
| 502 | |
| 503 | ### 其他提供商 |
| 504 | |
| 505 | `codewhale auth list` 会列出约 50 个提供商（OpenRouter、Anthropic、OpenAI、Moonshot、Ollama 等）。用法相同：`codewhale auth set --provider <name>`，或者使用该提供商对应的环境变量。本地模型（Ollama、vLLM、SGLang）不需要密钥。这里只测试了 DeepSeek。 |
| 506 | |
| 507 | --- |
| 508 | |
| 509 | <a id="8-shell-completions"></a> |
| 510 | |
| 511 | ## 9. Shell 补全 |
| 512 | |
| 513 | ```bash |
| 514 | # bash (needs the bash-completion package) |
| 515 | mkdir -p ~/.local/share/bash-completion/completions |
| 516 | codewhale completion bash > ~/.local/share/bash-completion/completions/codewhale |
| 517 | |
| 518 | # zsh |
| 519 | mkdir -p ~/.zfunc |
| 520 | codewhale completion zsh > ~/.zfunc/_codewhale |
| 521 | # in ~/.zshrc, if not already there: |
| 522 | # fpath=(~/.zfunc $fpath) |
| 523 | # autoload -Uz compinit && compinit |
| 524 | |
| 525 | # fish |
| 526 | mkdir -p ~/.config/fish/completions |
| 527 | codewhale completion fish > ~/.config/fish/completions/codewhale.fish |
| 528 | ``` |
| 529 | |
| 530 | 每个脚本都同时注册 `codewhale` 和 `codew`。`codewhale completions` 是别名。之后请打开一个新的 shell。升级后请重新生成。 |
| 531 | |
| 532 | v0.10.0 中它们的表现（交互式测试）： |
| 533 | |
| 534 | * **bash：** 完全可用（`codewhale comp<Tab>`、`codew auth <Tab><Tab>`）。 |
| 535 | * **fish：** 子命令能补全并带说明，但 `codewhale completion <Tab>` 提供的是文件，而不是 shell 名称。 |
| 536 | * **zsh：** 只有第一个词能补全。在子命令之后（`codewhale auth <Tab>`），zsh 会错误地再次列出顶层命令（macOS 的 zsh 5.9 上同样如此，会给出全部 126 个顶层条目）。 |
| 537 | |
| 538 | PowerShell 和 Elvish 的脚本也会生成，**（该虚拟机上未测试：未安装这些 shell）**。 |
| 539 | |
| 540 | --- |
| 541 | |
| 542 | ## 10. 运行 |
| 543 | |
| 544 | ### TUI |
| 545 | |
| 546 | ```bash |
| 547 | cd your-git-repo |
| 548 | codewhale |
| 549 | ``` |
| 550 | |
| 551 | * 输入框（composer）在底部。页脚显示权限级别（`ask`）、模式（`work`）和模型（`DeepSeek · deepseek-flash`）。 |
| 552 | * **Shift+Tab** 循环切换权限级别：Ask → Auto-Review（自动审核）→ Full Access（完全访问）。（输入框为空时）**Tab** 循环切换模式：Plan → Work → Operate。 |
| 553 | * 在 **Ask** 下，工作区内的文件编辑会被直接应用并以 diff 显示。shell 命令会停在 **APPROVAL** 提示：`y` 允许本次，`a` 在本次会话中允许，`n` 拒绝，`Esc` 中止当前回合。 |
| 554 | * 常用按键：**F1** 帮助（或 `/help`），**Ctrl-K** 命令面板，**F3** 提供商/模型选择器，**Ctrl-R** 恢复过去的会话，**Ctrl-U** 清空输入（**Ctrl-Z** 可恢复），**Ctrl-C** 取消或退出，**Ctrl-D** 在输入为空时退出。完整列表见 [KEYBINDINGS.md](./KEYBINDINGS.md)。 |
| 555 | * 退出时它会打印 `To resume this session, run codewhale resume <id>`。 |
| 556 | |
| 557 | Codewhale 会在你的仓库里创建一个 `.codewhale/` 目录。请忽略它的内容，但保留可提交的 `constitution.json`（这些规则与 `/init` 写入的相同）： |
| 558 | |
| 559 | ```gitignore |
| 560 | **/.codewhale/* |
| 561 | !**/.codewhale/constitution.json |
| 562 | ``` |
| 563 | |
| 564 | ### 无头模式（脚本、CI） |
| 565 | |
| 566 | ```bash |
| 567 | codewhale exec "Reply with exactly: pong" # one-shot answer, no tools |
| 568 | codewhale exec --auto "create primes.py that prints the first 10 primes and run it" # tools, auto-approved |
| 569 | codewhale exec --json "…" # summary JSON (provider, model, usage, output) |
| 570 | codewhale exec --auto --output-format stream-json "…" # one JSON event per line |
| 571 | ``` |
| 572 | |
| 573 | （注释含义：单次回答，无工具；启用工具并自动批准；汇总 JSON（提供商、模型、用量、输出）；每行一个 JSON 事件。） |
| 574 | |
| 575 | `--auto` 会自动批准 shell 命令，所以只在你信任的仓库或沙箱里使用。 |
| 576 | |
| 577 | 普通的 `exec` 不给模型提供任何工具。只有 `--auto`、`--yolo`、`--allowed-tools` 或恢复某个会话才会打开工具面；`--max-turns`、`--disallowed-tools`、`--sandbox` 和输出格式这类限制项从不会增加工具（仅对工具有效的参数会打印警告）。如果提供商在输出上限处截断了回复，会要求模型继续，最终打印出的答案是完整的回复。普通运行最多进行 8 个模型步骤，除非用 `--max-turns` 另设上限；在该上限处仍被截断的回复会使这次运行失败。 |
| 578 | |
| 579 | ### 恢复会话 |
| 580 | |
| 581 | ```bash |
| 582 | codewhale resume <session-id> # or a unique prefix, e.g. e2525dfb |
| 583 | codewhale -c # continue the most recent session in this folder |
| 584 | codewhale sessions # list saved sessions |
| 585 | codewhale exec --continue "…" # headless follow-up to the latest session |
| 586 | codewhale exec --resume <id> "…" |
| 587 | ``` |
| 588 | |
| 589 | （注释含义：会话 ID 或其唯一前缀；继续此目录中最近的会话；列出已保存的会话；对最近会话进行无头跟进。） |
| 590 | |
| 591 | 在 v0.10.0 中，只有 **TUI 会话**和 **`--output-format stream-json`** 的 exec 运行会被保存。普通的 `codewhale exec`/`exec --auto` 运行*不会*被保存，所以紧接着的 `exec --continue` 会失败，报 `No saved sessions found for workspace`。 |
| 592 | |
| 593 | --- |
| 594 | |
| 595 | ## 11. 终端说明 |
| 596 | |
| 597 | ### Ghostty（已测试：Linux/X11 上的 Ghostty 1.3.1） |
| 598 | |
| 599 | 我检查的所有项目在 Ghostty 默认配置下（`TERM=xterm-ghostty`、`COLORTERM=truecolor`）都能正常工作。截图与[安装回执](https://github.com/codewhale-hq/Codewhale/tree/37ecdfcc49bc68a9b0d058b97c3946e62c34bd31/docs/install-report/v0.10.0-2026-09-23/screenshots)保存在一起。 |
| 600 | |
| 601 | | 检查项 | 结果 | |
| 602 | |---|---| |
| 603 | | 颜色 / truecolor 渐变、制表符绘图、Unicode（✓ é 日本語） | ✅ | |
| 604 | | 调整窗口大小（1504×886 → 800×500 → 还原）时重排干净 | ✅ | |
| 605 | | 鼠标滚轮滚动对话记录，并带有"跳到底部"按钮 | ✅ | |
| 606 | | 粘贴（`Ctrl+Shift+V`），多行：会被插入，不会被发送 | ✅ | |
| 607 | | F1、F3、Ctrl-K、Ctrl-R、Tab、Shift+Tab、Ctrl-U/Ctrl-Z、Ctrl-C、Ctrl-D | ✅ | |
| 608 | | 窗口标题显示状态（`waiting on you…`、`✓ done`） | ✅ | |
| 609 | | 退出后终端恢复正常（回到普通屏幕、光标正常、没有鼠标上报的乱码） | ✅ | |
| 610 | |
| 611 | Linux 上的 Ghostty 启动的是**非登录** shell，所以它读取 `~/.bashrc` 而不是 `~/.profile`。这就是为什么 PATH 那一行需要写进 `~/.bashrc`（§2）。 |
| 612 | |
| 613 | 你可能会注意到，一个回合结束后，一些小圆点和淡淡的标签（例如 `other · drift`）在空白区域飘动。那是 Codewhale 装饰性的"环境生命（ambient life）"小鲸鱼，不是渲染故障。 |
| 614 | |
| 615 | ### 其他终端 |
| 616 | |
| 617 | tmux 会吃掉 **F1**，所以在 tmux 里请用 `/help`。有些组合键（Ctrl-Shift-…、Ctrl-Tab）需要支持增强键盘协议的终端；[KEYBINDINGS.md](./KEYBINDINGS.md) 列出了可移植的替代按键。Windows 用户请使用 Windows Terminal **（该虚拟机上未测试）**。 |
| 618 | |
| 619 | --- |
| 620 | |
| 621 | ## 12. 卸载 |
| 622 | |
| 623 | ### 第 1 步：忘掉已保存的密钥（如果你用过 `auth set` 或 F3） |
| 624 | |
| 625 | ```bash |
| 626 | codewhale auth clear --provider deepseek |
| 627 | ``` |
| 628 | |
| 629 | ### 第 2 步：删除程序 |
| 630 | |
| 631 | | 安装方式 | 删除方法 | |
| 632 | |---|---| |
| 633 | | 安装器（§2）或手动下载（§3） | `rm ~/.local/bin/codewhale ~/.local/bin/codew`（或你的 `CODEWHALE_INSTALL_DIR`） | |
| 634 | | npm | `npm uninstall -g codewhale` | |
| 635 | | Cargo | `cargo uninstall codewhale-cli` | |
| 636 | | Homebrew | `brew uninstall codewhale && brew untap Hmbown/deepseek-tui`（同时会移除它的 node 依赖） | |
| 637 | |
| 638 | ### 第 3 步：删除数据。没有任何卸载器会替你做这件事。 |
| 639 | |
| 640 | | 路径 | 内容 | 所见大小 | |
| 641 | |---|---|---| |
| 642 | | `~/.codewhale/` | config.toml、**secrets/secrets.json（明文密钥）**、sessions/、logs/、catalog/（模型列表，约 5 MB）、skills/、builtin-plugins/、tasks/、automations/、crashes/、audit.log、输入框历史 | 6–7 MB | |
| 643 | | `~/.deepseek/snapshots/` | v0.10.0 把每个回合的**工作区副本**存在这里（一个旧路径）。里面包含你运行过它的每个仓库的内容。 | 这里为 0.2–0.6 MB；随仓库大小增长 | |
| 644 | | `<你用过的每个仓库>/.codewhale/` | 每个工作区的状态/锁目录 | 很小 | |
| 645 | | 补全文件 | `~/.local/share/bash-completion/completions/codewhale`、`~/.zfunc/_codewhale`、`~/.config/fish/completions/codewhale.fish` | – | |
| 646 | | 你添加的 PATH 行 | `~/.bashrc`、`~/.zshrc`、`~/.profile` | – | |
| 647 | |
| 648 | ```bash |
| 649 | rm -rf ~/.codewhale ~/.deepseek/snapshots |
| 650 | rmdir ~/.deepseek 2>/dev/null # removes the parent only if it is now empty |
| 651 | # per-repo dirs, e.g.: |
| 652 | find ~ -type d -name .codewhale -prune -print # review, then delete the ones you want |
| 653 | ``` |
| 654 | |
| 655 | （注释含义：仅当父目录已为空时才会删除它；逐个仓库的目录，先查看再删除想删的。） |
| 656 | |
| 657 | Codewhale 没有在 `$HOME` 和它被使用过的仓库之外写入任何东西：没有系统文件、服务或 cron 任务。（我检查了测试用户在其主目录之外拥有的每一个文件。）上面的命令只删除 `~/.deepseek/snapshots`。如果你仍在使用较早的 DeepSeek-TUI，`~/.deepseek` 里的其余部分（它的配置和会话）不会被动。 |
| 658 | |
| 659 | --- |
| 660 | |
| 661 | ## 13. 故障排查 |
| 662 | |
| 663 | 下面每一个错误，都是编写本指南时实际遇到的。 |
| 664 | |
| 665 | **装完后立刻出现 `bash: codewhale: command not found`。** |
| 666 | `~/.local/bin` 在这个终端里不在 PATH 上。见[把它加入 PATH](#把它加入-path)。 |
| 667 | |
| 668 | **`npm error code EACCES … permission denied, mkdir '…/lib/node_modules/codewhale'`。** |
| 669 | 你的 Node 是系统级安装的。见 [§4](#如果遇到-eacces-permission-denied)。不要用 sudo。 |
| 670 | |
| 671 | **`error: DeepSeek API key not found.`（来自 `codewhale exec`）** |
| 672 | 哪里都没有密钥。按打印出的步骤操作，或见 §8。 |
| 673 | |
| 674 | **TUI 显示了你的消息，却始终不回答。** |
| 675 | 没有密钥（v0.10.0 不会提示）。按 F3 → DeepSeek → Enter → 粘贴密钥。 |
| 676 | |
| 677 | **`error: Responses API request failed … Authentication Fails, Your api key: ****dead is invalid`。** |
| 678 | 密钥错误或已被吊销。运行 `codewhale auth status --provider deepseek` 查看*究竟*用的是哪个来源。请记住，配置文件和密钥存储优先于环境变量。用 `codewhale auth set --provider deepseek` 修复，或者用 `codewhale auth clear --provider deepseek` 回退到环境变量。在 TUI 里，无效的密钥会把你带到"Choose your model provider"界面，并把 DeepSeek 标为 `last check failed (authentication)`。 |
| 679 | |
| 680 | **`error: Network error: SSE stream request failed after HTTP/1.1 fallback: Responses API request failed. … on Windows or proxy networks, try CODEWHALE_FORCE_HTTP1=1 …`。** |
| 681 | 尽管措辞如此，在 Linux 上这通常只意味着**无法连接到 `api.deepseek.com`**。用 `curl -sI https://api.deepseek.com` 检查（返回 `401` 是正常的，说明主机可达）。如果你在代理后面，请确认已导出 `HTTPS_PROXY`。`codewhale doctor --probe-api` 对错误的密钥和网络问题都只会说 `✗ API connection failed`。 |
| 682 | |
| 683 | **`codewhale install: refusing to replace existing ~/.local/bin/codewhale`。** |
| 684 | 那里已经装了不同版本。运行 `codewhale update`，或者先删除那两个文件（见 §7 回滚），或者安装到一个全新的 `CODEWHALE_INSTALL_DIR`。 |
| 685 | |
| 686 | **`codewhale install: checksum mismatch for codew-linux-x64`。** |
| 687 | 下载被损坏或被篡改。什么都没有安装。重试；如果反复出现，就不要使用镜像。 |
| 688 | |
| 689 | **`error: The package-managed executable was not changed.`（来自 `codewhale update`）** |
| 690 | 你是用 npm、Cargo 或 Homebrew 安装的。请改用对应的工具更新。 |
| 691 | |
| 692 | **`error: failed to run custom build command for libdbus-sys`（Cargo）。** |
| 693 | 运行 `sudo apt-get install -y libdbus-1-dev pkg-config`。 |
| 694 | |
| 695 | **`error: No saved sessions found for workspace …`（来自 `exec --continue`）。** |
| 696 | 上一次运行是纯文本的 `exec`，它不会被保存。请使用 TUI，或者 `--output-format stream-json`。 |
| 697 | |
| 698 | **zsh 补全在第一个词之后给出错误的建议。** |
| 699 | v0.10.0 的已知 bug。bash 和 fish 没问题。 |
| 700 | |
| 701 | **获取帮助：** `codewhale doctor --json` 会生成一个不含密钥的诊断包。 |
| 702 | |
| 703 | --- |
| 704 | |
| 705 | ## 附录：其他平台（本版未重测） |
| 706 | |
| 707 | 下面各节原样沿用自本页的上一版。它们**没有**在上文的 v0.10.0 安装测试中重新运行（不在范围内：Windows、macOS、Android/Termux、FreeBSD、中国大陆镜像），仅 [macOS 说明](#macos-说明)中提到的 macOS 路径除外。通过检查已发布的 v0.10.0 资源，发现下列内容与之矛盾（[详情](https://github.com/codewhale-hq/Codewhale/blob/37ecdfcc49bc68a9b0d058b97c3946e62c34bd31/docs/install-report/v0.10.0-2026-09-23/DOC_DEFECTS.md)，D15 和 D16）： |
| 708 | |
| 709 | * `packaging/winget/` 里的 winget 清单仍停留在 0.9.6。 |
| 710 | * v0.10.0 同时发布了 `codewhale-windows-x64.zip`（附带一个把文件复制到 `%USERPROFILE%\bin` 的 `install.bat`）和 `codewhale-windows-x64-portable.zip`；下面各节只提到了前者。 |
| 711 | * 独立的 `codewhale.bat` 启动器只能在 x64 exe 旁边工作。 |
| 712 | |
| 713 | ### 支持平台与发布资源 |
| 714 | |
| 715 | [最新稳定版](https://github.com/codewhale-hq/CodeWhale/releases/latest)发布了 Linux x64/arm64、macOS x64/arm64、Windows x64/arm64 和 Android arm64 的资源。资源存在不等于平台已通过验收。下表描述的是当前源码树的平台与次要打包支持；`latest` 安装仍然选择已发布的版本。Android/Termux 为预览状态，等待真机 QA。Linux ARM64 自 v0.8.8 起可用。Linux RISC-V 预编译暂时暂停，因为锁定的 `rquickjs-sys` 依赖没有提供 `riscv64gc-unknown-linux-gnu` 绑定。 |
| 716 | |
| 717 | | 平台 | 架构 | GitHub 发布资源 | npm install | `cargo install` | |
| 718 | | ------------ | ------------ | ----------------------------------------------------- | :---------: | :-------------: | |
| 719 | | Linux | x64 (x86_64) | `codewhale-linux-x64`, `codew-linux-x64` | ✅ | ✅ | |
| 720 | | Linux | arm64 | `codewhale-linux-arm64`, `codew-linux-arm64` | ✅ | ✅ | |
| 721 | | Android / Termux | arm64 (aarch64) | `codewhale-android-arm64.tar.gz`（v0.9.12 已发布；真机支持仍为预览） | ⚠️⁴ 预览版 | ⚠️⁴ 预览版 | |
| 722 | | Linux | riscv64 | 暂时不支持，待上游绑定落地 | ❌¹ | ❌³ | |
| 723 | | macOS | x64 | `codewhale-macos-x64`, `codew-macos-x64` | ✅ | ✅ | |
| 724 | | macOS | arm64 (M 系列) | `codewhale-macos-arm64`, `codew-macos-arm64` | ✅ | ✅ | |
| 725 | | Windows | x64 | `codewhale-windows-x64.exe`, `codew-windows-x64.exe` | ✅ | ✅ | |
| 726 | | Windows | arm64 | `codewhale-windows-arm64.exe`, `codew-windows-arm64.exe` | ✅ | ✅ | |
| 727 | | Linux x64 或 arm64 上的 musl（Alpine） | 原生架构 | 匹配的静态 Linux 资源 | ✅（静态） | ✅ | |
| 728 | | 其他 Linux（其他架构上的 musl） | — | 从源码构建 | ❌¹ | ✅² | |
| 729 | | FreeBSD 14+ / OpenBSD | x64, arm64 | `cargo install codewhale-cli --locked`（无预编译；见 § FreeBSD） | ❌ | ✅² | |
| 730 | |
| 731 | ¹ npm 包会以明确的错误退出，并引导你到这里。 |
| 732 | ² 前提是你的工具链能编译较新的 Rust workspace；见下文[从源码构建](#5-cargo-与从源码构建)。 |
| 733 | ³ RISC-V 源码构建目前需要上游 `rquickjs-sys` 的 RISC-V 绑定，或启用 bindgen 的依赖构建。 |
| 734 | ⁴ 当前的 npm 包装器能识别 Android arm64，并解析匹配的 `codewhale` 和 `codew` Android 资源。npm 安装仅对 GitHub Release 已发布了这些匹配资源的包版本有效。在 #4236 和 #4242 跟踪的真机编译、启动、审批、文件工具与更新检查完成之前，Android/Termux 路径仍为预览。 |
| 735 | |
| 736 | Android / Termux 与 Linux arm64 不是同一个目标。不要在 Termux 里安装 Linux 的 `codewhale-linux-arm64` 压缩包；当某个发布版或候选版发布了 Termux 专用的 Android 压缩包时请使用它，或在 Termux 内从源码构建。 |
| 737 | |
| 738 | 当前 Linux 的 **x64 和 arm64** 资源都是**静态 musl 构建**。x64 发布路径自 v0.8.65 起使用 musl；v0.9.6 把同样的构建与静态启动检查扩展到了 arm64。这些二进制没有 glibc 依赖，可在匹配的架构上跨 Ubuntu、Debian、RHEL/CentOS 和 Alpine/musl 运行。SQLite 通过 `rusqlite` 内置，因此无需单独的 `libsqlite3` 运行时包。 |
| 739 | |
| 740 | #### Linux ARM64 可移植性 |
| 741 | |
| 742 | v0.9.6 之前的 Linux arm64 资源是 GNU libc 构建，可能继承了 Ubuntu 24.04 构建主机的 `GLIBC_2.39` 最低要求。Ubuntu 22.04 自带 glibc 2.35，因此那些较老的 arm64 二进制可能报错，例如： |
| 743 | |
| 744 | ```text |
| 745 | version `GLIBC_2.39' not found |
| 746 | ``` |
| 747 | |
| 748 | npm 包装器、`codewhale update` 和 Unix 压缩包安装器对较旧版本仍保留 GNU 二进制预检查。当前的 arm64 构建改用 `aarch64-unknown-linux-musl`，因此没有 `GLIBC_*` 最低要求。如果你要在较旧的 arm64 发行版上安装早期版本，请使用： |
| 749 | |
| 750 | ```bash |
| 751 | cargo install codewhale-cli --locked # installs `codewhale` |
| 752 | ``` |
| 753 | |
| 754 | > **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，请跳到[从源码构建](#5-cargo-与从源码构建)——`cargo install` 完全可用。HarmonyOS PC 与 OpenHarmony 交叉构建设置，见 [HarmonyOS 与 OpenHarmony](./HarmonyOS.md)。 |
| 755 | |
| 756 | <a id="migrating-from-npm-cargo-or-another-installation"></a> |
| 757 | |
| 758 | ### 从 npm、Cargo 或其他安装迁移 |
| 759 | |
| 760 | 包管理器继续拥有自己的文件。对于 npm、Cargo、Homebrew 和 Omarchy，`codewhale update` 会给出迁移说明，而不是覆盖它们。已知的系统/包目录也受到保护。`CODEWHALE_INSTALL_METHOD=binary` 覆盖项无法绕过已识别的受管路径。 |
| 761 | |
| 762 | 当 `~/.local/bin` 已被占用，或者同级命令的内容不同，就创建一个全新的目标目录。这样每个已有的安装都原样保留： |
| 763 | |
| 764 | ```bash |
| 765 | mkdir -p "$HOME/.local" |
| 766 | codewhale_install_dir="$(mktemp -d "$HOME/.local/codewhale-release.XXXXXX")" |
| 767 | curl -fsSL https://codewhale.net/install.sh | CODEWHALE_INSTALL_DIR="$codewhale_install_dir" sh |
| 768 | "$codewhale_install_dir/codewhale" --version |
| 769 | export PATH="$codewhale_install_dir:$PATH" |
| 770 | hash -r |
| 771 | command -v codewhale codew |
| 772 | "$codewhale_install_dir/codewhale" update --check |
| 773 | ``` |
| 774 | |
| 775 | 确认版本和命令路径之后，把该目录放在 shell 配置里 PATH 的最前面。在 PowerShell 里，用 `Get-Command codewhale, codew -All` 检查解析结果；运行所选可执行文件时使用它的完整路径。一次成功的更新只会改动它自己所在的安装目录，所以 PATH 上更靠前的其他条目仍可能启动旧副本。 |
| 776 | |
| 777 | 现代的、成对匹配的 `codewhale`、`codew` 以及兼容性副本，都从同一份已校验的字节更新。指向正在运行的二进制的符号链接会被保留。内容不同或不相关的同级文件会在错误里被点名并原样保留；不会仅仅为了猜测其归属而执行任何同级文件。对于带有独立 dispatcher/TUI 二进制的旧安装，请使用上面的新目录迁移方式。 |
| 778 | |
| 779 | 如果要保留一份由包管理器管理的次要安装，请用它自己的管理器： |
| 780 | |
| 781 | ```bash |
| 782 | npm install -g codewhale@latest |
| 783 | # or |
| 784 | cargo install codewhale-cli --locked --force |
| 785 | ``` |
| 786 | |
| 787 | Homebrew 用 `brew upgrade codewhale`；Omarchy 用 `omarchy update`。这些命令只更新它们各自的副本，所以之后请再次核对 PATH。 |
| 788 | |
| 789 | <a id="android--termux-arm64"></a> |
| 790 | |
| 791 | ### Android / Termux arm64（预览） |
| 792 | |
| 793 | Termux 运行在 Android 的 Bionic libc 上，并使用 `$PREFIX` 作为它的 Unix 前缀，因此需要 Termux 专用的 Android arm64 压缩包。Linux arm64 发布资源面向使用 musl 的标准 Linux；Android 使用不同的 Rust 目标，所以不应在那里使用 Linux 资源。 |
| 794 | |
| 795 | 先安装最基本的压缩包/运行时工具： |
| 796 | |
| 797 | ```bash |
| 798 | pkg update |
| 799 | pkg install -y ca-certificates curl tar gzip coreutils |
| 800 | ``` |
| 801 | |
| 802 | 当发布版包含 `codewhale-android-arm64.tar.gz` 时，用压缩包自带的安装器安装。传入 `PREFIX="$PREFIX"` 很重要：安装器默认安装到 `~/.local`，而 Termux 用户通常期望命令在 `$PREFIX/bin` 下。 |
| 803 | |
| 804 | ```bash |
| 805 | cd "$HOME" |
| 806 | curl -L -O https://github.com/codewhale-hq/CodeWhale/releases/latest/download/codewhale-android-arm64.tar.gz |
| 807 | curl -L -O https://github.com/codewhale-hq/CodeWhale/releases/latest/download/codewhale-bundles-sha256.txt |
| 808 | sha256sum -c codewhale-bundles-sha256.txt --ignore-missing |
| 809 | |
| 810 | tar xzf codewhale-android-arm64.tar.gz |
| 811 | cd codewhale-android-arm64 |
| 812 | PREFIX="$PREFIX" ./install.sh |
| 813 | hash -r |
| 814 | ``` |
| 815 | |
| 816 | 如果你要从源码验证，或在本地构建候选版，请在运行 Cargo 之前先安装构建包： |
| 817 | |
| 818 | ```bash |
| 819 | pkg install -y rust clang pkg-config make git |
| 820 | cargo install codewhale-cli --locked # installs `codewhale` |
| 821 | ``` |
| 822 | |
| 823 | 常规的首次运行设置流程已经实现，但它在 Android 上的交互仍属于上文提到的预览 QA 范围。临时凭据优先使用提供商的环境变量。`codewhale auth set` 可用，但 Termux 构建没有受支持的操作系统钥匙串（keyring）集成，会退化为文件型密钥：写入 `~/.codewhale/config.toml`，并把密钥镜像到 `~/.codewhale/secrets/secrets.json`。两者都是受 `0600` 权限保护的明文文件，静态存储时未加密。 |
| 824 | |
| 825 | ```bash |
| 826 | codewhale auth set --provider deepseek |
| 827 | codewhale auth status |
| 828 | codewhale doctor |
| 829 | ``` |
| 830 | |
| 831 | 维护者应对 Termux / Android arm64 候选版使用这份可重复的冒烟检查清单： |
| 832 | |
| 833 | ```bash |
| 834 | command -v codewhale codew |
| 835 | test -x "$PREFIX/bin/codewhale" |
| 836 | test -x "$PREFIX/bin/codew" |
| 837 | |
| 838 | codewhale --version |
| 839 | codewhale doctor |
| 840 | codewhale exec --auto "run pwd" |
| 841 | ``` |
| 842 | |
| 843 | 已知限制： |
| 844 | |
| 845 | - 命令会继承 Android 的每应用 UID、SELinux 和 seccomp 保护，以及授予 Termux 的任何权限。Codewhale 可选的 bubblewrap 子进程沙箱仅限 Linux，没有在 Android 上构建，因此已批准的命令不会获得 Codewhale 特有的文件系统限制。 |
| 846 | - Termux 构建没有受支持的 Android Keystore 或桌面 Secret Service 集成。用 `codewhale auth status` 确认当前生效的来源；当文件型明文存储不可接受时，优先使用提供商的环境变量。 |
| 847 | - 终端渲染因 Android 终端应用而异。TUI 始终独占备用屏幕（alternate screen）。如果某个终端应用无法渲染全屏 TUI，请改用 `codewhale exec` 进行无头运行。 |
| 848 | |
| 849 | ### 中国大陆/镜像友好安装 |
| 850 | |
| 851 | 从中国大陆安装时，请同时为 **rustup**（Rust 工具链安装器）和 **Cargo**（包注册表）配置镜像，以避免 TLS 超时和下载失败。 |
| 852 | |
| 853 | **第 1 步：通过 rustup 镜像安装 Rust** |
| 854 | |
| 855 | ```bash |
| 856 | # PowerShell |
| 857 | [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 |
| 858 | (New-Object Net.WebClient).DownloadFile('https://win.rustup.rs/x86_64', 'rustup-init.exe') |
| 859 | |
| 860 | # git-bash / msys2 |
| 861 | export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup |
| 862 | export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup |
| 863 | ./rustup-init.exe -y --default-toolchain stable |
| 864 | |
| 865 | # Linux / macOS |
| 866 | export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup |
| 867 | export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup |
| 868 | curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable |
| 869 | ``` |
| 870 | |
| 871 | 如果 TUNA 镜像在你的网络下很慢，`rsproxy.cn` 是 Linux/macOS 的另一个 rustup 镜像选择： |
| 872 | |
| 873 | ```bash |
| 874 | export RUSTUP_DIST_SERVER=https://rsproxy.cn |
| 875 | export RUSTUP_UPDATE_ROOT=https://rsproxy.cn/rustup |
| 876 | curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable |
| 877 | ``` |
| 878 | |
| 879 | `RUSTUP_DIST_SERVER` 和 `RUSTUP_UPDATE_ROOT` 环境变量**必须**在运行 rustup-init **之前**设置；否则工具链下载会遇到与安装器相同的 TLS 握手问题。 |
| 880 | |
| 881 | **第 2 步：配置 Cargo 注册表镜像** |
| 882 | |
| 883 | ```toml |
| 884 | # ~/.cargo/config.toml |
| 885 | [source.crates-io] |
| 886 | replace-with = "tuna" |
| 887 | |
| 888 | [source.tuna] |
| 889 | registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/" |
| 890 | ``` |
| 891 | |
| 892 | `rsproxy`、腾讯云 COS 和阿里云 OSS 镜像的用法相同；选你的网络下最快的即可。 |
| 893 | |
| 894 | ### Omarchy / AUR |
| 895 | |
| 896 | 在 Omarchy 上，安装预构建的 AUR 包： |
| 897 | |
| 898 | ```bash |
| 899 | omarchy pkg aur add codewhale-bin |
| 900 | codewhale --version |
| 901 | ``` |
| 902 | |
| 903 | `codewhale-bin` 打包的是与其他二进制安装路径相同的、校验和已固定的 Linux 发布压缩包，并同时提供 `codewhale` 和 `codew`。它不携带单独的 Codewhale 版本；现有的 `codewhale-tui` 兼容命令仍是同一运行时的别名。包更新通过 `omarchy update` 到达；应用内更新器会把 pacman 拥有的二进制留给 Omarchy 处理。 |
| 904 | |
| 905 | AUR 更新跟随对应的 Codewhale 标签和发布资源，所以它可能在 GitHub 发布之后才出现，因为其生成的 `PKGBUILD` 和 `.SRCINFO` 需要先经过验证。发布维护者说明见 [`packaging/aur/README.md`](../../packaging/aur/README.md)。 |
| 906 | |
| 907 | --- |
| 908 | |
| 909 | ### Windows |
| 910 | |
| 911 | #### Windows Scoop |
| 912 | |
| 913 | `codewhale` 包列在 Scoop 的 main bucket 中： |
| 914 | |
| 915 | ```powershell |
| 916 | scoop update |
| 917 | scoop install codewhale |
| 918 | codewhale --version |
| 919 | ``` |
| 920 | |
| 921 | Scoop 清单维护在本仓库的发布工作流之外，可能落后于 GitHub/npm/Cargo 的发布。当你需要立即拿到最新版本时，请使用 npm 或从 GitHub 手动下载发布资源。 |
| 922 | |
| 923 | #### Windows winget |
| 924 | |
| 925 | 已发布的 winget 包是 **`HunterBown.CodeWhale`**（2026-10-04 在 |
| 926 | [microsoft/winget-pkgs](https://github.com/microsoft/winget-pkgs/tree/master/manifests/h/HunterBown/CodeWhale) |
| 927 | 核实；最新发布版本为 0.10.0）。它是便携式 x64 包：winget 下载 |
| 928 | `codewhale-tui-windows-x64.exe`，将其安装为 `codewhale` 命令，并安装 Microsoft Visual C++ 2015+ x64 运行库。 |
| 929 | |
| 930 | ```powershell |
| 931 | winget install HunterBown.CodeWhale |
| 932 | codewhale --version |
| 933 | ``` |
| 934 | |
| 935 | 使用 `winget upgrade HunterBown.CodeWhale` 或 `codewhale update` 更新。每个版本在 GitHub Release 之后都要经过 winget-pkgs 审核，因此 winget 可能落后于 GitHub/npm/Cargo；需要立即获得最新版本时，请使用 npm 或 GitHub Release 资源。 |
| 936 | |
| 937 | winget 方式的已知限制： |
| 938 | |
| 939 | * **仅 x64。** 已发布的清单没有 ARM64 安装包。在 Windows ARM64 上，请在原生 ARM64 Node.js 下运行 `npm install -g codewhale`，或从 GitHub Releases 下载 `codewhale-windows-arm64.zip`。 |
| 940 | * **仅安装 `codewhale`。** winget 不安装简短别名 `codew`；请使用 `codewhale`。 |
| 941 | * 本仓库中的清单（`packaging/winget/`）不是 winget 实际提供的清单；见 [`packaging/winget/README.md`](../../packaging/winget/README.md)。 |
| 942 | |
| 943 | #### Windows NSIS 安装器 |
| 944 | |
| 945 | 从 v0.8.50 起，为喜欢传统双击安装的 Windows 用户提供了独立的、基于 NSIS 的安装器（无需 npm、Scoop 或 Cargo）。 |
| 946 | |
| 947 | NSIS 安装器目前包含 Windows x64 二进制。Windows ARM64 用户应通过在原生 ARM64 Node.js 下运行的 npm 安装，或从同一个发布下载 `codewhale-windows-arm64.zip`；这两条路径使用的都是原生 ARM64 二进制。 |
| 948 | |
| 949 | 从[发布页](https://github.com/codewhale-hq/CodeWhale/releases/latest)**下载** `CodeWhaleSetup.exe`。 |
| 950 | |
| 951 | 双击安装程序即可**安装**。安装器会： |
| 952 | |
| 953 | - 把 `codewhale.exe` 和 `codew.exe` 并排安装（单二进制，没有 `codewhale-tui.exe`）到 `%LOCALAPPDATA%\Programs\CodeWhale\bin` |
| 954 | - 安装 `codewhale.bat`：`PATH` 上有 Windows Terminal（`wt.exe`）时优先使用它，否则直接启动 exe |
| 955 | - 创建当前用户的开始菜单快捷方式，指向该启动器，而不是原始的 `.exe` |
| 956 | - 把安装目录加入**当前用户**的 `PATH` |
| 957 | - 注册到 Windows 的**应用和功能（Apps & Features）**，便于卸载 |
| 958 | |
| 959 | 卸载会移除二进制、`codewhale.bat`、开始菜单快捷方式和用户 `PATH` 条目。 |
| 960 | |
| 961 | **静默安装**（供 IT 管理员、SCCM、Intune 使用）： |
| 962 | |
| 963 | ```powershell |
| 964 | CodeWhaleSetup.exe /S |
| 965 | ``` |
| 966 | |
| 967 | 该安装器是每用户安装，不会请求提权。请在目标用户的环境中运行静默安装，或使用能为每个需要 Codewhale 的用户配置文件运行安装器的部署工具。 |
| 968 | |
| 969 | 发布版构建的安装器目前未签名，可能触发 Windows SmartScreen。部署前请用 `codewhale-artifacts-sha256.txt` 校验 SHA-256 校验和；如果你的环境要求已签名的应用包，请在内部部署流水线中对安装程序签名。 |
| 970 | |
| 971 | **自行构建安装器**（需要 [NSIS](https://nsis.sourceforge.io)）： |
| 972 | |
| 973 | ```powershell |
| 974 | cd scripts\installer |
| 975 | # Place codewhale.exe and codew.exe here (single binary, no codewhale-tui.exe), then: |
| 976 | makensis /DVERSION=<version> codewhale.nsi |
| 977 | ``` |
| 978 | |
| 979 | （注释含义：把 codewhale.exe 和 codew.exe 放到这里，单二进制，没有 codewhale-tui.exe，然后运行 makensis。） |
| 980 | |
| 981 | **手动回退**——如果安装器被组策略阻止，请参见 [CLASSROOM_INSTALL.md](../CLASSROOM_INSTALL.md) 指南中的分步 PowerShell 命令。 |
| 982 | |
| 983 | > **要部署到教室或实验室？** 请参见完整的[教室安装清单](../CLASSROOM_INSTALL.md)，其中涵盖静默安装、API 密钥配发、系统镜像（imaging）说明和故障排查。 |
| 984 | |
| 985 | <a id="freebsd"></a> |
| 986 | |
| 987 | ### FreeBSD、交叉编译、Windows 源码构建 |
| 988 | |
| 989 | #### FreeBSD 14+ 源码构建替代方案（#1097） |
| 990 | |
| 991 | FreeBSD 没有预编译的 GitHub Release 资源——`npm install -g codewhale` 会有意失败，提示 `Unsupported platform: freebsd` 并指向 Cargo。请从源码安装： |
| 992 | |
| 993 | ```bash |
| 994 | pkg install -y rust pkgconf git |
| 995 | cargo install codewhale-cli --locked # installs `codewhale` |
| 996 | codewhale --version |
| 997 | codewhale doctor |
| 998 | ``` |
| 999 | |
| 1000 | `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 是源码构建目标，不是预编译资源。 |
| 1001 | |
| 1002 | #### 从 x64 交叉编译到 ARM64 Linux |
| 1003 | |
| 1004 | 发布资源使用 `aarch64-unknown-linux-musl`，并在原生 ARM runner 上构建。如果你想在 x64 Linux 主机上构建一个 GNU 链接的 ARM64 Linux 二进制（例如给 HarmonyOS / openEuler ARM64 轻薄本用），请使用 [`cross`](https://github.com/cross-rs/cross)，它把官方的 Rust 交叉目标封装在 Docker 容器里： |
| 1005 | |
| 1006 | ```bash |
| 1007 | # Once |
| 1008 | rustup target add aarch64-unknown-linux-gnu |
| 1009 | cargo install cross --locked |
| 1010 | |
| 1011 | # Per build |
| 1012 | cross build --release --target aarch64-unknown-linux-gnu -p codewhale-cli # single binary |
| 1013 | ``` |
| 1014 | |
| 1015 | 生成的二进制位于 `target/aarch64-unknown-linux-gnu/release/codewhale`。把它复制到 ARM64 主机（例如通过 `scp`）并赋予可执行权限。这个本地 GNU 构建不同于可移植的 musl 发布资源；两种可执行文件都可以以 `codew` 这个便捷名称复制使用。 |
| 1016 | |
| 1017 | 如果你没有 Docker，可以直接安装交叉链接器，让 Cargo 来完成工作： |
| 1018 | |
| 1019 | ```bash |
| 1020 | sudo apt-get install -y gcc-aarch64-linux-gnu |
| 1021 | rustup target add aarch64-unknown-linux-gnu |
| 1022 | |
| 1023 | cat >> ~/.cargo/config.toml <<'EOF' |
| 1024 | [target.aarch64-unknown-linux-gnu] |
| 1025 | linker = "aarch64-linux-gnu-gcc" |
| 1026 | EOF |
| 1027 | |
| 1028 | cargo build --release --target aarch64-unknown-linux-gnu -p codewhale-cli # single binary |
| 1029 | ``` |
| 1030 | |
| 1031 | 交叉编译时生成 `aarch64-unknown-linux-musl` 需要合适的 musl 交叉链接器。发布工作流通过在 GitHub 的原生 ARM runner 上构建并启动 musl 二进制，避免了这个额外的麻烦环节。 |
| 1032 | |
| 1033 | #### Windows 源码构建 |
| 1034 | |
| 1035 | 在 Windows 上构建需要 [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022) 中的 **MSVC C 工具链**（免费的、可按工作负载选择的安装器，不是完整的 IDE）。 |
| 1036 | |
| 1037 | **前置条件（Windows）** |
| 1038 | |
| 1039 | 1. 安装 Visual Studio 2022 Build Tools——选择 **"使用 C++ 的桌面开发（Desktop development with C++）"** 工作负载。 |
| 1040 | 2. 安装 [Rust](https://rustup.rs) 1.89+（如果从中国大陆下载，参见上文[中国大陆/镜像友好安装](#中国大陆镜像友好安装)）。 |
| 1041 | 3. 安装 [Git for Windows](https://git-scm.com/download/win)（提供 `git` 和 `git-bash` 终端）。 |
| 1042 | |
| 1043 | **推荐的终端**：Windows Terminal、`git-bash` 或 PowerShell。`cmd.exe` 可用，但缓冲区较小，PATH 行为也有限。 |
| 1044 | |
| 1045 | **设置 MSVC 环境** |
| 1046 | |
| 1047 | Visual Studio Build Tools 会把 `cl.exe` 安装到带版本号的目录，但**不会**把它全局加入 `PATH`。你必须手动设置环境，或使用开发者命令提示符。所需的变量是： |
| 1048 | |
| 1049 | ```powershell |
| 1050 | # Adjust version numbers to match your installation |
| 1051 | $msvc = "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.44.35207" |
| 1052 | $sdk = "C:\Program Files (x86)\Windows Kits\10" |
| 1053 | $sdkv = "10.0.26100.0" |
| 1054 | |
| 1055 | $env:INCLUDE = "$msvc\include;$msvc\atlmfc\include;$sdk\Include\$sdkv\ucrt;$sdk\Include\$sdkv\um;$sdk\Include\$sdkv\shared" |
| 1056 | $env:LIB = "$msvc\lib\x64;$msvc\atlmfc\lib\x64;$sdk\Lib\$sdkv\ucrt\x64;$sdk\Lib\$sdkv\um\x64" |
| 1057 | $env:LIBPATH = "$msvc\lib\x64;$msvc\atlmfc\lib\x64" |
| 1058 | $env:CC = "$msvc\bin\Hostx64\x64\cl.exe" |
| 1059 | $env:CXX = "$msvc\bin\Hostx64\x64\cl.exe" |
| 1060 | $env:PATH = "$msvc\bin\Hostx64\x64;$env:PATH" |
| 1061 | ``` |
| 1062 | |
| 1063 | （第一行注释含义：请调整版本号以匹配你的安装。） |
| 1064 | |
| 1065 | 或者，打开 **"VS 2022 开发者命令提示符（Developer Command Prompt for VS 2022）"**（安装 Build Tools 后可在开始菜单找到），它会运行 `vcvars64.bat` 自动配置上述所有内容。然后在该会话里把 `cargo` 加入 `PATH`，并从项目根目录运行 `cargo build`。 |
| 1066 | |
| 1067 | **Cargo 注册表镜像**——在 Windows 上，镜像配置放在 `%USERPROFILE%\.cargo\config.toml`。参见[上文第 2 步](#中国大陆镜像友好安装)。 |
| 1068 | |
| 1069 | **构建** |
| 1070 | |
| 1071 | ```bash |
| 1072 | git clone https://github.com/codewhale-hq/CodeWhale.git |
| 1073 | cd CodeWhale |
| 1074 | set CARGO_HTTP_CHECK_REVOKE=false # may be needed behind some Chinese ISPs |
| 1075 | cargo build --release |
| 1076 | ``` |
| 1077 | |
| 1078 | （注释含义：在某些中国 ISP 之后可能需要。） |
| 1079 | |
| 1080 | Cargo 构建出的二进制位于 `target\release\codewhale.exe`。发布打包会另外把同一个可执行文件作为 `codew.exe` 提供。 |
| 1081 | |
| 1082 | > 不想构建？通过 npm、Cargo、GitHub Releases 或 CNB 镜像安装——见上面各节。 |
| 1083 | |
| 1084 | ### 旧版本与地区性故障排查 |
| 1085 | |
| 1086 | #### `Unsupported architecture: arm64 on platform linux` |
| 1087 | |
| 1088 | 你使用的是早于 v0.8.8 的版本，它不发布 Linux ARM64 二进制。请按上文所述，使用 GitHub 安装器安装到一个全新的目录，或者按[第 5 节](#5-cargo-与从源码构建)使用 `cargo install`。 |
| 1089 | |
| 1090 | #### 升级旧安装后出现 `MISSING_COMPANION_BINARY` |
| 1091 | |
| 1092 | 当前的单二进制在进程内运行 TUI，不需要配套的可执行文件。这个错误说明存在一个过时的、早于 v0.9.5 的 dispatcher。请使用上文的新目录 GitHub 迁移方式，然后核对所选的 `codewhale` 和 `codew` 路径。不要再下载另一个单独的运行时。 |
| 1093 | |
| 1094 | #### `codewhale update` 报告 `no asset found for platform codewhale-linux-aarch64` |
| 1095 | |
| 1096 | 旧版更新器使用的 Rust 架构名与发布资源名不一致。请按上文所述，用官方安装器安装到一个全新的目录，然后通过完整路径运行新安装的命令。 |
| 1097 | |
| 1098 | #### 中国大陆 npm 下载慢或超时 |
| 1099 | |
| 1100 | 在 Linux x64 上，npm 包装器已经并行探测 GitHub Releases 和 CNB 第一方校验和清单，并且只从第一个通过校验的来源下载二进制。这条自动路径不需要 `CODEWHALE_USE_CNB_MIRROR=1`。 |
| 1101 | |
| 1102 | 如果两个第一方来源都失败，请把 `CODEWHALE_RELEASE_BASE_URL` 设置为镜像的发布资源目录（rsproxy、TUNA、腾讯云 COS、阿里云 OSS），或者完全跳过 npm，使用[第 5 节](#5-cargo-与从源码构建)里的 Cargo 镜像设置。旧的 `DEEPSEEK_TUI_RELEASE_BASE_URL` 名称仍被接受。`CODEWHALE_USE_CNB_MIRROR=1` 仍然只在 Linux x64 / OpenHarmony x64 上强制使用 CNB。 |
| 1103 | |
| 1104 | #### 中国大陆无法从 GitHub 使用 `codewhale update` |
| 1105 | |
| 1106 | `codewhale update` 优先使用 GitHub Releases。在受支持的 Linux x64 目标上，GitHub 清单请求失败时，允许回退到对应的 CNB 清单和二进制。如果 GitHub 元数据也无法访问，请显式选择一个已知已发布的 CNB 版本（`CODEWHALE_USE_CNB_MIRROR=1 CODEWHALE_VERSION=X.Y.Z codewhale update`），或使用下面的二进制镜像。已有的较新构建会被保留。 |
| 1107 | |
| 1108 | 用 Cargo 从 CNB 源码镜像构建是次要选项。Cargo 会安装它自己管理的 `codewhale` 命令： |
| 1109 | |
| 1110 | 要在不下载、不替换二进制的情况下检查最新发布，运行 `codewhale update --check`。 |
| 1111 | |
| 1112 | ```bash |
| 1113 | cargo install --git https://cnb.cool/codewhale.net/codewhale --tag vX.Y.Z codewhale-cli --locked --force # single binary |
| 1114 | ``` |
| 1115 | |
| 1116 | 如果你运营一个二进制资源镜像，`codewhale update` 可以直接使用它： |
| 1117 | |
| 1118 | ```bash |
| 1119 | CODEWHALE_RELEASE_BASE_URL=https://your-mirror.example.com/CodeWhale/vX.Y.Z/ \ |
| 1120 | CODEWHALE_VERSION=X.Y.Z \ |
| 1121 | codewhale update |
| 1122 | ``` |
| 1123 | |
| 1124 | 镜像目录必须包含 `codewhale-artifacts-sha256.txt` 以及来自 GitHub 发布的各平台二进制。旧的 `DEEPSEEK_TUI_RELEASE_BASE_URL` 镜像变量仍作为别名受支持。 |
| 1125 | |
| 1126 | ### Windows 与 npm 下载故障排查 |
| 1127 | |
| 1128 | #### Windows：`rustup-init` 报 `TLS handshake eof` 或 `CRYPT_E_REVOCATION_OFFLINE` |
| 1129 | |
| 1130 | 在防火长城（GFW）或某些中国 ISP 之后，到 `static.rust-lang.org` 的 TLS 握手会失败。请在运行安装器**之前**设置 rustup 镜像环境变量： |
| 1131 | |
| 1132 | ```bash |
| 1133 | # git-bash / msys2 |
| 1134 | export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup |
| 1135 | export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup |
| 1136 | ./rustup-init.exe -y --default-toolchain stable |
| 1137 | ``` |
| 1138 | |
| 1139 | 如果 Rust 装好之后 Cargo 报 `CRYPT_E_REVOCATION_OFFLINE`，请在 `cargo build` 期间同时设置 `CARGO_HTTP_CHECK_REVOKE=false`。 |
| 1140 | |
| 1141 | #### Windows：`cargo build` 期间找不到 MSVC 编译器（`cl.exe`） |
| 1142 | |
| 1143 | Visual Studio Build Tools 不会把 `cl.exe` 加入全局 `PATH`。二选一： |
| 1144 | |
| 1145 | 1. 从开始菜单打开 **"VS 2022 开发者命令提示符"**，在该窗口里把 `%USERPROFILE%\.cargo\bin` 加入 `PATH`，并从那里运行 `cargo build`；或 |
| 1146 | 2. 手动设置 MSVC 环境变量——PowerShell 片段见 [Windows 源码构建](#windows-源码构建)一节。 |
| 1147 | |
| 1148 | 验证编译器可用：`cl.exe /?` 应该会打印帮助文本。 |
| 1149 | |
| 1150 | #### Windows：Cargo 执行构建脚本时报 `拒绝访问 (os error 5)` |
| 1151 | |
| 1152 | 第三方杀毒软件（火绒、360、卡巴斯基等）可能会阻止 Cargo 执行刚编译出来的构建脚本二进制（例如 `libsqlite3-sys`、`aws-lc-sys`、`instability`）。这个错误与路径无关——移动 `target-dir` 也没有帮助。 |
| 1153 | |
| 1154 | **症状**：`could not execute process ... build-script-build (never executed)` |
| 1155 | |
| 1156 | **变通办法**（任选其一）： |
| 1157 | |
| 1158 | 1. **把项目的 `target/` 目录加入杀毒软件的排除列表。** |
| 1159 | 2. **在 `cargo build` 期间暂时关闭杀毒软件。** |
| 1160 | 3. **改用 GitHub Release 安装器/压缩包**——发布资源提供预编译二进制，完全跳过 Cargo 构建（[第 3 节](#3-从-github-releases-手动下载)）。 |
| 1161 | 4. **使用 crates.io 的 `cargo install codewhale-cli --locked`**——这会改变二进制路径，某些杀毒软件对不同路径的处理方式不同。 |
| 1162 | |
| 1163 | 要验证构建脚本二进制本身是否有效（没有损坏），在 `target/debug/build/<crate>/build-script-build` 下找到它并手动运行： |
| 1164 | |
| 1165 | ```bash |
| 1166 | target/debug/build/libsqlite3-sys-*/build-script-build |
| 1167 | # If this runs but panics with "NotPresent" (no C compiler), the binary is |
| 1168 | # fine — the AV is blocking Cargo's process-spawning path specifically. |
| 1169 | ``` |
| 1170 | |
| 1171 | （注释含义：如果它能运行，但以 "NotPresent"（没有 C 编译器）panic，说明这个二进制没问题——是杀毒软件专门在阻止 Cargo 的进程派生路径。） |
| 1172 | |
| 1173 | #### npm 二进制下载超时 |
| 1174 | |
| 1175 | 如果 `codewhale` 等待几秒后，在从 `github.com` 拉取时打印 `connect ETIMEDOUT` 或 `EAI_AGAIN`，说明 npm 包装器安装成功了，但预编译二进制的下载在你的网络上被屏蔽或不稳定。这次下载与 npm 注册表的包下载是分开的。在 Linux x64 上，包装器会先并行探测体积很小的 GitHub 和 CNB 校验清单，不会等到完整的 GitHub 二进制超时，才去使用有效的 CNB 清单。 |
| 1176 | |
| 1177 | 请使用以下路径之一： |
| 1178 | |
| 1179 | 1. 设置代理并重试： |
| 1180 | |
| 1181 | ```bash |
| 1182 | export HTTPS_PROXY=http://your-proxy:port |
| 1183 | codewhale |
| 1184 | ``` |
| 1185 | |
| 1186 | 2. 在内部镜像发布资源，并设置 `CODEWHALE_RELEASE_BASE_URL`： |
| 1187 | |
| 1188 | ```bash |
| 1189 | export CODEWHALE_RELEASE_BASE_URL=https://your-mirror.example.com/CodeWhale/ |
| 1190 | codewhale |
| 1191 | ``` |
| 1192 | |
| 1193 | 该目录必须包含 `codewhale-artifacts-sha256.txt` 以及来自 GitHub 发布的各平台二进制。 |
| 1194 | |
| 1195 | 3. 通过 Cargo 安装，它在本地构建，不下载 GitHub 发布资源。见[第 5 节](#5-cargo-与从源码构建)。 |
| 1196 | |
| 1197 | 4. 从[发布页](https://github.com/codewhale-hq/CodeWhale/releases)下载匹配的 `codewhale` 和 `codew` 两个二进制，放到 `PATH` 上的某个目录并赋予可执行权限。见[第 3 节](#3-从-github-releases-手动下载)。 |
| 1198 |