| 1 | # 安装 Codewhale |
| 2 | |
| 3 | > 本文依据英文版 [INSTALL.md](../INSTALL.md)。GitHub 优先安装与更新说明于 2026-09-04 更新；其余平台说明沿用现有译文。 |
| 4 | |
| 5 | 本文涵盖所有受支持的安装方式，以及最常见的"没装上"失败场景，包括 **Linux ARM64** 和其他不太常见的平台。 |
| 6 | |
| 7 | 如果你只想看精简的版本，请看[主 README](../../README.md#install) 或[简体中文 README](../../README.zh-CN.md#安装)。 |
| 8 | |
| 9 | 本分支描述的是 **v0.9.12 源码候选版**。使用 `latest` 的安装命令会解析到最新已发布的包或 GitHub Release，这可能落后于源码候选版。候选版只有在对应的包、标签、校验和与发布资源齐备之后，才算正式发布的安装。 |
| 10 | |
| 11 | 推荐使用官方 GitHub Releases。在 macOS 和 Linux 上首次安装： |
| 12 | |
| 13 | ```bash |
| 14 | curl -fsSL https://codewhale.net/install.sh | sh |
| 15 | ``` |
| 16 | |
| 17 | 它会下载匹配的 `codewhale` 和 `codew` 发布二进制，对照 `codewhale-artifacts-sha256.txt` 校验，默认安装到 `~/.local/bin`，并暴露 `codew` 便捷命令。 |
| 18 | |
| 19 | 已有的直接安装使用 `codewhale update --check` 和 `codewhale update`。更新器先使用 |
| 20 | GitHub；受支持的 Linux x64 平台仅在 GitHub 校验清单失败或无法覆盖该平台后才尝试 CNB。 |
| 21 | 每次清单请求最多 10 秒、最多三次尝试。`CODEWHALE_VERSION` 指定镜像版本； |
| 22 | `DEEPSEEK_TUI_VERSION` 和 `DEEPSEEK_VERSION` 仍作为兼容别名。 |
| 23 | 镜像和显式版本也不能绕过版本检查：例如源码 v0.9.12 |
| 24 | 不会被已发布的 v0.9.11 覆盖。 |
| 25 | |
| 26 | npm 和 Cargo 是次要打包方式。安装器不使用自动 sudo，也不覆盖不同的已有文件或符号链接； |
| 27 | 包管理器继续管理自己的可执行文件。更新器会保留指向当前二进制的符号链接，并拒绝覆盖 |
| 28 | 内容不同的同目录命令。遇到旧版分离的 dispatcher/TUI 或多个安装时，选择新的空目录： |
| 29 | |
| 30 | ```bash |
| 31 | mkdir -p "$HOME/.local" |
| 32 | codewhale_install_dir="$(mktemp -d "$HOME/.local/codewhale-release.XXXXXX")" |
| 33 | curl -fsSL https://codewhale.net/install.sh | CODEWHALE_INSTALL_DIR="$codewhale_install_dir" sh |
| 34 | "$codewhale_install_dir/codewhale" --version |
| 35 | export PATH="$codewhale_install_dir:$PATH" |
| 36 | hash -r |
| 37 | command -v codewhale codew |
| 38 | ``` |
| 39 | |
| 40 | 验证路径和版本后，将所选目录放到 shell 配置的 PATH 最前面。今后使用该目录中 |
| 41 | `codewhale` 的完整路径运行 `update`。Windows 使用官方 GitHub Release 安装器或压缩包， |
| 42 | 并通过 `Get-Command codewhale, codew -All` 检查路径。完整迁移说明见 |
| 43 | [英文安装指南](../INSTALL.md#recommended-official-github-releases)。 |
| 44 | |
| 45 | --- |
| 46 | |
| 47 | ## 1. 支持平台 |
| 48 | |
| 49 | 2026-09-04 检查的[最新稳定版 v0.9.11](https://github.com/Hmbown/CodeWhale/releases/tag/v0.9.11) |
| 50 | 包含 Linux、macOS、Windows 的 x64/arm64 资源及 Android arm64 资源。 |
| 51 | 资源存在不等于真机验收；下表的包管理器支持和静态构建说明仍属于 v0.9.12 源码候选版。 |
| 52 | |
| 53 | 已发布的 Codewhale 版本会为受支持的平台/架构组合提供配套的 `codewhale` 和 `codew` 预编译二进制。下表是 v0.9.12 候选版的预期矩阵；Android/Termux 为预览状态，等待真机 QA。Linux ARM64 自 v0.8.8 起可用。Linux RISC-V 预编译暂时暂停，因为锁定的 `rquickjs-sys` 依赖没有提供 `riscv64gc-unknown-linux-gnu` 绑定。 |
| 54 | |
| 55 | | 平台 | 架构 | GitHub 发布资源 | npm install | `cargo install` | |
| 56 | | ------------ | ------------ | ----------------------------------------------------- | :---------: | :-------------: | |
| 57 | | Linux | x64 (x86_64) | `codewhale-linux-x64`, `codew-linux-x64` | ✅ | ✅ | |
| 58 | | Linux | arm64 | `codewhale-linux-arm64`, `codew-linux-arm64` | ✅ | ✅ | |
| 59 | | Android / Termux | arm64 (aarch64) | `codewhale-android-arm64.tar.gz`（v0.9.11 已发布；真机支持仍为预览） | ⚠️⁴ 预览版 | ⚠️⁴ 预览版 | |
| 60 | | Linux | riscv64 | 暂时不支持，待上游绑定落地 | ❌¹ | ❌³ | |
| 61 | | macOS | x64 | `codewhale-macos-x64`, `codew-macos-x64` | ✅ | ✅ | |
| 62 | | macOS | arm64 (M 系列) | `codewhale-macos-arm64`, `codew-macos-arm64` | ✅ | ✅ | |
| 63 | | Windows | x64 | `codewhale-windows-x64.exe`, `codew-windows-x64.exe` | ✅ | ✅ | |
| 64 | | Windows | arm64 | `codewhale-windows-arm64.exe`, `codew-windows-arm64.exe` | ✅ | ✅ | |
| 65 | | Linux x64 或 arm64 上的 musl（Alpine） | 原生架构 | 匹配的静态 Linux 资源 | ✅（静态） | ✅ | |
| 66 | | 其他 Linux（其他架构上的 musl） | — | 从源码构建 | ❌¹ | ✅² | |
| 67 | | FreeBSD 14+ / OpenBSD | x64, arm64 | `cargo install codewhale-cli --locked`（无预编译；见 § FreeBSD） | ❌ | ✅² | |
| 68 | |
| 69 | ¹ npm 包会以明确错误退出，并引导你到这里。 |
| 70 | ² 前提是你的工具链能编译较新的 Rust workspace；见下文[从源码构建](#7-从源码构建)。 |
| 71 | ³ RISC-V 源码构建目前需要上游 `rquickjs-sys` 的 RISC-V 绑定，或启用 bindgen 的依赖构建。 |
| 72 | ⁴ v0.9.12 源码候选版的 npm 包装器能识别 Android arm64，并解析匹配的 `codewhale` 和 `codew` Android 资源。npm 安装仅对 GitHub Release 已发布的、匹配的包版本有效。在 #4236 和 #4242 跟踪的真机编译、启动、审批、文件工具与更新检查完成之前，Android/Termux 路径仍为预览。 |
| 73 | |
| 74 | Android / Termux 与 Linux arm64 不是同一个目标。不要在 Termux 里安装 Linux 的 `codewhale-linux-arm64` 压缩包；当某个发布版或候选版发布了 Termux 专用的 Android 压缩包时请使用它，或在 Termux 内从源码构建。 |
| 75 | |
| 76 | Linux 的 **x64 和 arm64** v0.9.12 候选版资源是**静态 musl 构建**。x64 发布路径自 v0.8.65 起使用 musl；v0.9.6 将同样的构建与静态启动检查扩展到 arm64。这些二进制没有 glibc 依赖，可在匹配的架构上跨 Ubuntu、Debian、RHEL/CentOS 和 Alpine/musl 运行。SQLite 通过 `rusqlite` 内置，因此无需单独的 `libsqlite3` 运行时包。 |
| 77 | |
| 78 | ### Linux ARM64 可移植性 |
| 79 | |
| 80 | v0.9.6 之前的 Linux arm64 资源是 GNU libc 构建，可能继承了 Ubuntu 24.04 构建主机的 `GLIBC_2.39` 最低要求。 |
| 81 | Ubuntu 22.04 自带 glibc 2.35，因此，那些较老的 arm64 二进制可能报错，例如： |
| 82 | |
| 83 | ```text |
| 84 | version `GLIBC_2.39' not found |
| 85 | ``` |
| 86 | |
| 87 | npm 包装器、`codewhale update` 和 Unix 压缩包安装器对较旧版本仍保留 GNU 二进制预检查。v0.9.12 arm64 候选版改用 `aarch64-unknown-linux-musl`，因此没有 `GLIBC_*` 最低要求。如果你要在较旧的 arm64 发行版上安装早期版本，请使用： |
| 88 | |
| 89 | ```bash |
| 90 | cargo install codewhale-cli --locked # 安装 codewhale |
| 91 | ``` |
| 92 | |
| 93 | > **Linux ARM64 说明（v0.8.7 及更早）。** v0.8.7 及更早版本**未发布** Linux ARM64 预编译； |
| 94 | > 使用HarmonyOS 轻薄本、Asahi Linux、树莓派(Raspberry Pi)、AWS Graviton 等的用户会从 `npm i -g codewhale` 看到 `Unsupported architecture: arm64`。 |
| 95 | > v0.8.8 发布了 `codewhale-linux-arm64`，因此普通的 `npm i -g codewhale` 可在任何基于 glibc 的 ARM64 Linux 上工作。 |
| 96 | > 如果你还卡在 v0.8.7，直接跳到[从源码构建](#7-从源码构建)——`cargo install` 完全可用。 |
| 97 | > HarmonyOS PC 与 OpenHarmony 交叉构建设置，见 [HarmonyOS 与 OpenHarmony](../HarmonyOS.md)。 |
| 98 | |
| 99 | ### Android / Termux arm64 |
| 100 | |
| 101 | Termux 运行在 Android 的 Bionic libc 上，并使用 `$PREFIX` 作为其 Unix 前缀，因此需要 Termux 专用的 Android arm64 压缩包。Linux arm64 发布资源面向标准 Linux（使用 musl），而 Android 使用不同的 Rust 目标。因此，不应在那里使用 Linux 资源。 |
| 102 | |
| 103 | 先安装最基本的压缩包/运行时工具： |
| 104 | |
| 105 | ```bash |
| 106 | pkg update |
| 107 | pkg install -y ca-certificates curl tar gzip coreutils |
| 108 | ``` |
| 109 | |
| 110 | 当发布版包含 `codewhale-android-arm64.tar.gz` 时，用压缩包自带的安装器安装。传入 `PREFIX="$PREFIX"` 很重要：安装器默认安装到 `~/.local`，而 Termux 用户通常期望命令在 `$PREFIX/bin` 下。 |
| 111 | |
| 112 | ```bash |
| 113 | cd "$HOME" |
| 114 | curl -L -O https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-android-arm64.tar.gz |
| 115 | curl -L -O https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-bundles-sha256.txt |
| 116 | sha256sum -c codewhale-bundles-sha256.txt --ignore-missing |
| 117 | |
| 118 | tar xzf codewhale-android-arm64.tar.gz |
| 119 | cd codewhale-android-arm64 |
| 120 | PREFIX="$PREFIX" ./install.sh |
| 121 | hash -r |
| 122 | ``` |
| 123 | |
| 124 | 如果你要验证源码或在本地构建候选版，请在运行 Cargo 之前，先安装构建包： |
| 125 | |
| 126 | ```bash |
| 127 | pkg install -y rust clang pkg-config make git |
| 128 | cargo install codewhale-cli --locked # 安装 codewhale |
| 129 | ``` |
| 130 | |
| 131 | 正确的首次运行设置流程已实现，但其 Android 交互仍属于上文提到的预览 QA 范围。 |
| 132 | 临时凭证优先使用 provider 环境变量。 |
| 133 | `codewhale auth set` 可用，但 Termux 构建没有受支持的 OS 钥匙串集成（keyring integration），会退化为文件存储的密钥：写入 `~/.codewhale/config.toml`，并把密钥镜像到 `~/.codewhale/secrets/secrets.json`。两者都是纯文本文件，受 `0600` 权限保护，静态存储时未加密。 |
| 134 | |
| 135 | ```bash |
| 136 | codewhale auth set --provider deepseek |
| 137 | codewhale auth status |
| 138 | codewhale doctor |
| 139 | ``` |
| 140 | |
| 141 | 维护者应对 Termux / Android arm64 候选版使用这套可重复的冒烟检查清单（smoke checklist）： |
| 142 | |
| 143 | ```bash |
| 144 | command -v codewhale codew |
| 145 | test -x "$PREFIX/bin/codewhale" |
| 146 | test -x "$PREFIX/bin/codew" |
| 147 | |
| 148 | codewhale --version |
| 149 | codewhale doctor |
| 150 | codewhale exec --auto "run pwd" |
| 151 | ``` |
| 152 | |
| 153 | 已知限制： |
| 154 | |
| 155 | - 命令会继承 Android 的每应用（per-app） UID、SELinux 和 seccomp 保护，以及授予 Termux 的任何权限。Codewhale 的可选 bubblewrap 子进程沙箱仅限 Linux，未在 Android 上构建，因此已批准的命令不会获得 Codewhale 特有的文件系统限制。 |
| 156 | - Termux 构建没有受支持的 Android Keystore 或桌面 Secret Service 集成。用 `codewhale auth status` 确认当前生效的来源；当文件型纯文本存储不可接受时，优先使用 provider 环境变量。 |
| 157 | - 终端渲染因 Android 终端应用而异。TUI 始终拥有备用屏幕（alternate screen）。如果某个终端应用无法渲染全屏 TUI，请改用 `codewhale exec` 来无头运行。 |
| 158 | |
| 159 | --- |
| 160 | |
| 161 | ## 2. 下载安全与校验和 |
| 162 | |
| 163 | 官方发布二进制只从 `https://github.com/Hmbown/CodeWhale/releases` 和名为 `codewhale` 的 npm 包发布。除非你明确信任某个镜像，请勿从仿冒的仓库、压缩包和搜索结果镜像安装发布资源。 |
| 164 | |
| 165 | 每个 GitHub release 都包含校验和清单。使用 `codewhale-artifacts-sha256.txt` 校验裸二进制文件，使用 `codewhale-bundles-sha256.txt` 校验 `.tar.gz` / `.zip` 平台压缩包。如果您手动下载二进制文件，请在运行前进行验证： |
| 166 | |
| 167 | ```bash |
| 168 | # 在包含已下载的二进制的目录中运行。 |
| 169 | curl -L -O https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-artifacts-sha256.txt |
| 170 | sha256sum -c codewhale-artifacts-sha256.txt --ignore-missing |
| 171 | ``` |
| 172 | |
| 173 | 在 macOS 上，用 `shasum -a 256 -c codewhale-artifacts-sha256.txt --ignore-missing` 来代替 `sha256sum`。 |
| 174 | |
| 175 | 如果杀毒软件标记了官方发布的二进制文件，请在找出确切的工件（Artifact）之前将其视为未解决的问题。请在 GitHub issue 中提供以下所有信息： |
| 176 | |
| 177 | - 发布标签，例如 `v0.8.36` |
| 178 | - 确切的下载 URL |
| 179 | - 文件名，例如 `codewhale-linux-x64` |
| 180 | - 你机器上文件的 SHA-256 |
| 181 | - 杀毒软件产品名与检测名称 |
| 182 | |
| 183 | 这能让维护者区分官方工件的误报与来自仿冒仓库或镜像的下载。 |
| 184 | |
| 185 | --- |
| 186 | |
| 187 | ## 3. 通过 npm 安装 |
| 188 | |
| 189 | npm 是次要安装方式（Node 18+；包装器适用于 v0.8.56 及更高版本）。它安装的是 注册表（registry） 上最新发布的版本，而不是未发布的源码候选版。 |
| 190 | |
| 191 | ```bash |
| 192 | npm install -g codewhale |
| 193 | codewhale --version # 打印已安装的发布版本 |
| 194 | ``` |
| 195 | |
| 196 | `postinstall` 会下载匹配的 `codewhale` 和 `codew` 二进制，对照该来源的 SHA-256 清单校验，并把 `codewhale` 和 `codew` 添加到你的 `PATH` 中。 |
| 197 | |
| 198 | 在 **Linux x64**（包括 OpenHarmony x64）上，包装器**不会**等待缓慢的 GitHub 二进制下载或漫长的超时失败。 |
| 199 | 除非你设置了显式的 release 基础 URL 或 `CODEWHALE_USE_CNB_MIRROR=1`，否则它会并发地从 GitHub Releases 和第一方 CNB release 获取对应精确包版本的小型 `codewhale-artifacts-sha256.txt` 清单，接受第一个对所需资源通过 HTTP 响应与清单校验的来源，取消另一个探测，并且只从该锁定来源下载二进制。 |
| 200 | CNB 只发布 Linux x64；其他目标保持仅 GitHub 路径。所选来源会打印在安装进度中，并写入下载文件旁的 `<binary>.source`。校验和（checksum）或来源不匹配时按失败处理。 |
| 201 | |
| 202 | 在 Windows 上，请从 **Windows Terminal** 运行这些命令，而不是 `cmd.exe`，这样字体和颜色才能匹配受支持的 TUI。GitHub Release 还会在裸 x64 exe 旁发布 `codewhale.bat`；该启动器优先使用 `wt.exe`，在没有 Windows Terminal 时回退为直接启动。 |
| 203 | |
| 204 | 有用的环境变量： |
| 205 | |
| 206 | | 变量 | 用途 | |
| 207 | | ----------------------------------- | -------------------------------------------------------------------------------------- | |
| 208 | | `CODEWHALE_RELEASE_BASE_URL` | 覆盖下载根目录。跳过 Linux x64 的 GitHub/CNB 竞争。 | |
| 209 | | `CODEWHALE_USE_CNB_MIRROR=1` | 在 Linux x64 / OpenHarmony x64 上强制使用 CNB 第一方镜像。其他目标会失败。 | |
| 210 | | `CODEWHALE_VERSION` | 固定包装器下载哪个 release（默认 `codewhaleBinaryVersion`）。 | |
| 211 | | `CODEWHALE_GITHUB_REPO` | 让下载器指向某个 fork（`owner/repo`）。 | |
| 212 | | `CODEWHALE_FORCE_DOWNLOAD=1` | 即使缓存的二进制标记匹配也重新下载。 | |
| 213 | | `CODEWHALE_DISABLE_INSTALL=1` | 完全跳过 `postinstall` 下载（CI 冒烟、内置二进制）。 | |
| 214 | | `CODEWHALE_OPTIONAL_INSTALL=1` | 遇到可重试的下载错误时不使 `npm install` 失败——在 CI 矩阵中有用。 | |
| 215 | | `CODEWHALE_QUIET_INSTALL=1` | 禁止安装器进度消息，静默安装。 | |
| 216 | | `CODEWHALE_DOWNLOAD_TIMEOUT_MS` | 覆盖总下载超时时间（毫秒）。 | |
| 217 | | `CODEWHALE_DOWNLOAD_STALL_MS` | 覆盖无进度停滞超时时间（毫秒）。 | |
| 218 | |
| 219 | 相应的 `DEEPSEEK_TUI_*` 和 `DEEPSEEK_*` 变量仍作为旧别名被接受，但规范的名称是 `CODEWHALE_*`。新的自动化与支持文档应只使用 `Codewhale` 名称。 |
| 220 | |
| 221 | > **中国大陆 npm 下载慢？** 如果 `npm install` 本身很慢（不只是 postinstall 的二进制下载），使用 npm 注册表镜像： |
| 222 | > ```bash |
| 223 | > npm config set registry https://registry.npmmirror.com |
| 224 | > npm install -g codewhale |
| 225 | > ``` |
| 226 | > 如果你更想用 Cargo 而非 npm，参见[第 4 节](#4-通过-cargo-安装任何-tier-1-rust-目标)。 |
| 227 | |
| 228 | --- |
| 229 | |
| 230 | ## 4. 通过 Cargo 安装（任何 Tier-1 Rust 目标） |
| 231 | |
| 232 | 如果 GitHub releases 缓慢、受阻，或你正在使用不受支持的架构，可以直接从 crates.io 安装。 |
| 233 | 只需要一个 Cargo 包：`codewhale-cli` 会安装 `codewhale` 命令。npm 与预编译发布版还会把 `codew` 作为同一编译运行时的便捷名称暴露出来；Cargo 不会创建该别名，所以如果你想要更短的名字，请自行定义 shell 别名。 |
| 234 | |
| 235 | ```bash |
| 236 | # 需要 Rust 1.88+（https://rustup.rs） |
| 237 | cargo install codewhale-cli --locked # 安装 codewhale |
| 238 | codewhale --version |
| 239 | ``` |
| 240 | |
| 241 | > **Linux：先安装构建时依赖。** `cargo install` 从源码编译，在 Linux 上 `codewhale-cli` crate 会链接 `libdbus-1`（D-Bus secret-service 后端用它存储凭据）。运行 `cargo install` 之前请先安装所需的系统包： |
| 242 | > |
| 243 | > ```bash |
| 244 | > # Debian / Ubuntu |
| 245 | > sudo apt-get install -y build-essential pkg-config libdbus-1-dev |
| 246 | > |
| 247 | > # Fedora / RHEL |
| 248 | > sudo dnf install -y gcc make pkgconf-pkg-config dbus-devel |
| 249 | > ``` |
| 250 | > |
| 251 | > 如果你使用 npm 包装器或下载 GitHub Release 二进制，这些构建时包就**不需要**了——预编译二进制只需要运行时库（`libdbus-1`），而大多数桌面 Linux 安装里已经自带。 |
| 252 | |
| 253 | ### 中国/镜像友好安装 |
| 254 | |
| 255 | 从中国大陆安装时，请同时为 **rustup**（Rust 工具链安装器）和 **Cargo**（包注册表）配置镜像，以避免 TLS 超时和下载失败。 |
| 256 | |
| 257 | **第 1 步：通过 rustup 镜像安装 Rust** |
| 258 | |
| 259 | ```bash |
| 260 | # PowerShell |
| 261 | [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 |
| 262 | (New-Object Net.WebClient).DownloadFile('https://win.rustup.rs/x86_64', 'rustup-init.exe') |
| 263 | |
| 264 | # git-bash / msys2 |
| 265 | export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup |
| 266 | export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup |
| 267 | ./rustup-init.exe -y --default-toolchain stable |
| 268 | |
| 269 | # Linux / macOS |
| 270 | export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup |
| 271 | export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup |
| 272 | curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable |
| 273 | ``` |
| 274 | |
| 275 | 如果 TUNA 镜像在你的网络下很慢，`rsproxy.cn` 是 Linux/macOS 的另一个 rustup 镜像选择： |
| 276 | |
| 277 | ```bash |
| 278 | export RUSTUP_DIST_SERVER=https://rsproxy.cn |
| 279 | export RUSTUP_UPDATE_ROOT=https://rsproxy.cn/rustup |
| 280 | curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable |
| 281 | ``` |
| 282 | |
| 283 | `RUSTUP_DIST_SERVER` 和 `RUSTUP_UPDATE_ROOT` 环境变量**必须**在运行 rustup-init **之前**设置；否则工具链下载会遇到与安装器相同的 TLS 握手问题。 |
| 284 | |
| 285 | **第 2 步：配置 Cargo registry 镜像** |
| 286 | |
| 287 | ```toml |
| 288 | # ~/.cargo/config.toml |
| 289 | [source.crates-io] |
| 290 | replace-with = "tuna" |
| 291 | |
| 292 | [source.tuna] |
| 293 | registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/" |
| 294 | ``` |
| 295 | |
| 296 | `rsproxy`、腾讯云 COS 和阿里云 OSS 镜像的工作方式相同；根据你的网络环境选择最快的即可。 |
| 297 | |
| 298 | ## 5. 通过 Nix 安装 |
| 299 | |
| 300 | **试试看** |
| 301 | |
| 302 | 如果你已经有支持 flake 的 Nix，运行： |
| 303 | |
| 304 | ```sh |
| 305 | nix run github:Hmbown/CodeWhale |
| 306 | ``` |
| 307 | |
| 308 | Nix 会构建 `codewhale`（单个二进制），然后启动调度器。在 `--` 之后传参，例如： |
| 309 | |
| 310 | ```sh |
| 311 | nix run github:Hmbown/CodeWhale -- --help |
| 312 | ``` |
| 313 | |
| 314 | ### Flake |
| 315 | |
| 316 | 在 `flake.nix` 中添加 inputs： |
| 317 | |
| 318 | ```nix |
| 319 | { |
| 320 | inputs = { |
| 321 | nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; |
| 322 | |
| 323 | codewhale.url = "github:Hmbown/CodeWhale"; |
| 324 | codewhale.inputs.nixpkgs.follows = "nixpkgs"; |
| 325 | }; |
| 326 | } |
| 327 | ``` |
| 328 | |
| 329 | 安装到 NixOS 模块中： |
| 330 | |
| 331 | ```nix |
| 332 | { |
| 333 | outputs = { self, nixpkgs, codewhale }: |
| 334 | let |
| 335 | # 把 system "x86_64-linux" 替换成你的系统 |
| 336 | system = "x86_64-linux"; |
| 337 | in |
| 338 | { |
| 339 | # 把 `yourhostname` 改成你的真实主机名（Hostname） |
| 340 | nixosConfigurations.yourhostname = nixpkgs.lib.nixosSystem { |
| 341 | inherit system; |
| 342 | modules = [ |
| 343 | # ... |
| 344 | { |
| 345 | environment.systemPackages = [ codewhale.packages.${system}.default ]; |
| 346 | } |
| 347 | ]; |
| 348 | }; |
| 349 | }; |
| 350 | } |
| 351 | ``` |
| 352 | |
| 353 | --- |
| 354 | |
| 355 | ## Omarchy / AUR |
| 356 | |
| 357 | 在 Omarchy 上安装预构建的 AUR 包： |
| 358 | |
| 359 | ```bash |
| 360 | omarchy pkg aur add codewhale-bin |
| 361 | codewhale --version |
| 362 | ``` |
| 363 | |
| 364 | `codewhale-bin` 打包与其他二进制安装路径相同的、经校验和固定的 Linux 发布压缩包，并提供 `codewhale` 和 `codew` 两个命令。它不携带单独的 Codewhale 版本；现有的 `codewhale-tui` 兼容命令仍是同一运行时的别名。包更新通过 `omarchy update` 到达；应用内更新器会把 pacman 拥有的二进制留给 Omarchy。 |
| 365 | |
| 366 | AUR 更新跟随匹配的 Codewhale 标签和发布资源，因此它可能在 GitHub 发布之后才出现——其生成的 `PKGBUILD` 和 `.SRCINFO` 需要先经过验证。发布维护者说明见 [`packaging/aur/README.md`](../../packaging/aur/README.md)。 |
| 367 | |
| 368 | --- |
| 369 | |
| 370 | ## Homebrew |
| 371 | |
| 372 | formula 名为 `codewhale`。 |
| 373 | tap GitHub 仓库在改名之前仍是 `Hmbown/homebrew-deepseek-tui`；`brew tap Hmbown/deepseek-tui` 无论哪种情况都能继续工作。 |
| 374 | |
| 375 | ```bash |
| 376 | brew tap Hmbown/deepseek-tui |
| 377 | brew install codewhale |
| 378 | ``` |
| 379 | |
| 380 | 用 `brew upgrade codewhale` 更新。 |
| 381 | 旧的 `deepseek-tui` formula 名下的 Cellar 安装，在一个重叠发布周期内，仍可运行 `brew upgrade deepseek-tui`；新安装应使用 `codewhale`。 |
| 382 | |
| 383 | --- |
| 384 | |
| 385 | ## 6. 从 GitHub Releases 手动下载 |
| 386 | |
| 387 | 每个平台在 Releases 页面以**两种形式**出现（这是有意为之——见 #3208）：**裸二进制**（`codewhale-<platform>` 和 `codew-<platform>`，无扩展名）和 **`.tar.gz` / `.zip` 压缩包**（`codewhale-<platform>.tar.gz`），压缩包包含了同样的命令，还外加了 `install.sh`。 |
| 388 | npm 包装器和应用内 `codewhale update` 会下载匹配的运行时二进制；压缩包是最简单的手动安装方式（见[第 6 节](#6-从-github-releases-手动下载)）。下面的步骤直接使用裸二进制文件。 |
| 389 | |
| 390 | 从 [Releases 页面](https://github.com/Hmbown/CodeWhale/releases)抓取匹配你平台的命令组，并把它们并排放入 `PATH` 上的某个目录（例如 `~/.local/bin`）： |
| 391 | |
| 392 | ```bash |
| 393 | # Linux ARM64 示例 |
| 394 | mkdir -p ~/.local/bin |
| 395 | curl -L -o ~/.local/bin/codewhale \ |
| 396 | https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-linux-arm64 |
| 397 | curl -L -o ~/.local/bin/codew \ |
| 398 | https://github.com/Hmbown/CodeWhale/releases/latest/download/codew-linux-arm64 |
| 399 | chmod +x ~/.local/bin/codewhale ~/.local/bin/codew |
| 400 | codewhale --version |
| 401 | ``` |
| 402 | |
| 403 | > **macOS Gatekeeper 说明。** 如果你用浏览器下载了二进制，macOS 可能会用"Apple 无法验证"警告拦截它们。清除两个二进制的隔离属性后重试： |
| 404 | > ```bash |
| 405 | > xattr -d com.apple.quarantine ~/.local/bin/codewhale ~/.local/bin/codew 2>/dev/null || true |
| 406 | > ``` |
| 407 | |
| 408 | 根据每个版本的 SHA-256 清单验证完整性： |
| 409 | |
| 410 | ```bash |
| 411 | curl -L -o /tmp/codewhale-artifacts-sha256.txt \ |
| 412 | https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-artifacts-sha256.txt |
| 413 | ( cd ~/.local/bin && sha256sum -c /tmp/codewhale-artifacts-sha256.txt --ignore-missing ) |
| 414 | ``` |
| 415 | |
| 416 | （在 macOS 上使用 `shasum -a 256 -c /tmp/codewhale-artifacts-sha256.txt --ignore-missing` 代替 `sha256sum -c`。） |
| 417 | |
| 418 | ### 回滚到之前的版本 |
| 419 | |
| 420 | 如果某个新 release 在你的机器上出问题，请显式安装最后一个已知正常的版本。把 `X.Y.Z` 替换成你要恢复的版本。 |
| 421 | |
| 422 | ```bash |
| 423 | # npm 包装器，仅对已发布到 npm 的版本有效 |
| 424 | npm install -g codewhale@X.Y.Z |
| 425 | |
| 426 | # Cargo 路径：一个包安装 codewhale |
| 427 | cargo install codewhale-cli --version X.Y.Z --locked --force |
| 428 | ``` |
| 429 | |
| 430 | 手动安装时，请从确切的 release 标签下载匹配的二进制或平台压缩包，并从同一标签校验对应的校验和清单： |
| 431 | |
| 432 | ```bash |
| 433 | # 单独的二进制 |
| 434 | curl -L -o codewhale-artifacts-sha256.txt \ |
| 435 | https://github.com/Hmbown/CodeWhale/releases/download/vX.Y.Z/codewhale-artifacts-sha256.txt |
| 436 | |
| 437 | # 平台压缩包 |
| 438 | curl -L -o codewhale-bundles-sha256.txt \ |
| 439 | https://github.com/Hmbown/CodeWhale/releases/download/vX.Y.Z/codewhale-bundles-sha256.txt |
| 440 | ``` |
| 441 | |
| 442 | 在 Codewhale 工作区内，`/restore list [N]` 列出 side-git 文件快照，`/restore <N>` 从所选快照恢复文件。这种工作区回滚不会改变你已安装的二进制版本，也不会重写对话历史。 |
| 443 | |
| 444 | ### Windows Scoop |
| 445 | |
| 446 | `codewhale` 包列在 Scoop 的 main bucket 中： |
| 447 | |
| 448 | ```powershell |
| 449 | scoop update |
| 450 | scoop install codewhale |
| 451 | codewhale --version |
| 452 | ``` |
| 453 | |
| 454 | Scoop 清单维护在本仓库的发布工作流之外，可能落后于 GitHub/npm/Cargo 发布。当你需要立即拿到最新版本时，请使用 npm 或手动在 GitHub release 下载。 |
| 455 | |
| 456 | ### Windows winget（v0.9.5+） |
| 457 | |
| 458 | Codewhale 为 `Hmbown.CodeWhale` 发布 winget manifest（解决 #1561）。Winget 只安装 `codewhale` + `codew` 命令。GitHub Releases 保留字节完全一致的 `codewhale-tui-*` 文件名，仅用于旧版更新器兼容；它们不是第三个已安装命令。 |
| 459 | |
| 460 | ```powershell |
| 461 | winget install Hmbown.CodeWhale |
| 462 | codewhale --version |
| 463 | ``` |
| 464 | |
| 465 | 清单位于 [`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`）。 |
| 466 | winget 会自动选择匹配的架构；两者都安装单二进制文件（`codewhale.exe` + `codew.exe`）。ZIP 里还包含 `codewhale.bat`。请双击那个启动器（而不是原始 `.exe`），如此，首选窗口被设置为 Windows Terminal（如果已安装）。 |
| 467 | |
| 468 | 通过 `winget upgrade Hmbown.CodeWhale` 或 `codewhale update` 更新。winget 包维护在本仓库的发布工作流之外，可能会比 GitHub/npm/Cargo 发布滞后一个验证周期 —— 当您需要最新版本时，请使用 npm 或 GitHub Release 资源。 |
| 469 | 如果 `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)。 |
| 470 | |
| 471 | > **Windows ARM64 说明。** NSIS 安装器目前只包含 x64 二进制。Windows ARM64 用户应通过 `winget install Hmbown.CodeWhale`（ARM64 ZIP）或原生 ARM64 Node.js 下的 `npm install -g codewhale` 安装，或直接下载 `codewhale-windows-arm64.zip`——所有路径都会安装原生 ARM64 二进制。 |
| 472 | |
| 473 | ### Windows NSIS 安装器 |
| 474 | |
| 475 | 从 v0.8.50 开始，为喜欢传统双击安装的 Windows 用户提供了独立的基于 NSIS 的安装器（无需 npm、Scoop 或 Cargo）。 |
| 476 | |
| 477 | NSIS 安装器目前包含 Windows x64 二进制。Windows ARM64 用户应通过原生 ARM64 Node.js 下的 npm 安装，或从同一 release 下载 `codewhale-windows-arm64.zip`；两条路径都会使用原生 ARM64 二进制。 |
| 478 | |
| 479 | **下载** 从 [Releases 页面](https://github.com/Hmbown/CodeWhale/releases/latest) 下载 `CodeWhaleSetup.exe`。 |
| 480 | |
| 481 | **安装** 双击安装程序。安装器会： |
| 482 | |
| 483 | - 把 `codewhale.exe` 和 `codew.exe` 并排安装（单二进制，没有 `codewhale-tui.exe`）到 `%LOCALAPPDATA%\Programs\CodeWhale\bin` |
| 484 | - 安装 `codewhale.bat`，它在 `PATH` 上存在 Windows Terminal（`wt.exe`）时优先使用，否则直接启动 exe |
| 485 | - 创建当前用户的开始菜单快捷方式，指向该启动器，而非裸 `.exe` |
| 486 | - 把安装目录加入**当前用户**的 `PATH` |
| 487 | - 在 Windows **应用和功能（Apps & Features）** 中注册，便于卸载 |
| 488 | |
| 489 | 卸载会移除二进制、`codewhale.bat`、开始菜单快捷方式和用户 `PATH` 条目。 |
| 490 | |
| 491 | **静默安装**（供 IT 管理员、SCCM、Intune 使用）： |
| 492 | |
| 493 | ```powershell |
| 494 | CodeWhaleSetup.exe /S |
| 495 | ``` |
| 496 | |
| 497 | 安装器是每用户安装，不会请求提权。请在目标用户的环境中运行静默安装，或使用能为每个需要 Codewhale 的用户配置文件运行安装器的部署工具。 |
| 498 | |
| 499 | 发布版安装器目前未签名，可能触发 Windows SmartScreen。部署前请用 `codewhale-artifacts-sha256.txt` 校验 SHA-256 校验和（checksum）；如果你的环境要求签名应用包，请在内部部署管道中对安装程序进行签名。 |
| 500 | |
| 501 | **自行构建安装程序**（需要 [NSIS](https://nsis.sourceforge.io)）： |
| 502 | |
| 503 | ```powershell |
| 504 | cd scripts\installer |
| 505 | # 把 codewhale.exe 和 codew.exe 放到这里（单二进制，没有 codewhale-tui.exe），然后： |
| 506 | makensis /DVERSION=<version> codewhale.nsi |
| 507 | ``` |
| 508 | |
| 509 | **手动回退**——如果安装器被组策略阻止，参见 [CLASSROOM_INSTALL.md](../CLASSROOM_INSTALL.md) 指南中的分步 PowerShell 命令。 |
| 510 | |
| 511 | > **要部署到教室或实验室？** 参见完整的[教室安装清单](../CLASSROOM_INSTALL.md)，涵盖静默安装、API key 供应、镜像说明与故障排查。 |
| 512 | |
| 513 | --- |
| 514 | |
| 515 | ## 7. 从源码构建 |
| 516 | |
| 517 | 这是面向我们不提供二进制平台的兜底方案，包括 musl 非 x64、LoongArch、FreeBSD 以及 2024 年以前的 ARM64 发行版。Linux RISC-V 目前也需要上游 `rquickjs-sys` 的 RISC-V 绑定或启用 bindgen 的依赖构建，源码构建才能预期可用。 |
| 518 | |
| 519 | ### 前置条件 |
| 520 | |
| 521 | - **Rust** 1.88 或更高版本——用 [rustup](https://rustup.rs) 安装。 |
| 522 | - **Linux 构建期依赖**（Debian/Ubuntu/openEuler/Kylin）： |
| 523 | ```bash |
| 524 | sudo apt-get install -y build-essential pkg-config libdbus-1-dev |
| 525 | # openEuler / RHEL 系列： |
| 526 | # sudo dnf install -y gcc make pkgconf-pkg-config dbus-devel |
| 527 | ``` |
| 528 | - 不需要 `cmake`。 |
| 529 | |
| 530 | ### 构建并安装 |
| 531 | |
| 532 | ```bash |
| 533 | git clone https://github.com/Hmbown/CodeWhale.git |
| 534 | cd CodeWhale |
| 535 | |
| 536 | cargo install --path crates/cli --locked # 安装 codewhale |
| 537 | |
| 538 | codewhale --version |
| 539 | ``` |
| 540 | |
| 541 | 命令默认安装到 `~/.cargo/bin/`；请确保该目录在你的 `PATH` 上。 |
| 542 | |
| 543 | ### FreeBSD 14+ 源码构建替代方案（#1097） |
| 544 | |
| 545 | FreeBSD 没有预编译的 GitHub Release 资源——`npm install -g codewhale` 会故意失败，提示 `Unsupported platform: freebsd` 并指向 Cargo。从源码安装： |
| 546 | |
| 547 | ```bash |
| 548 | pkg install -y rust pkgconf git |
| 549 | cargo install codewhale-cli --locked # 安装 codewhale |
| 550 | codewhale --version |
| 551 | codewhale doctor |
| 552 | ``` |
| 553 | |
| 554 | `rquickjs` 的 FreeBSD 绑定在构建时通过 `bindgen` 生成（见 `1582ba965`/`5eb0385e8`）。 |
| 555 | 目前还没有单独的 `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 是源码构建目标，不是预编译资源。 |
| 556 | |
| 557 | ### 从 x64 交叉编译到 ARM64 Linux |
| 558 | |
| 559 | release 资源使用 `aarch64-unknown-linux-musl`，并在原生 ARM runner 上构建。如果你想在 x64 Linux 主机上构建 GNU 链接的 ARM64 Linux 二进制（例如用于 HarmonyOS / openEuler ARM64 轻薄本），请使用 [`cross`](https://github.com/cross-rs/cross)，它把官方的 Rust 交叉目标封装在 Docker 容器中： |
| 560 | |
| 561 | ```bash |
| 562 | # 一次性 |
| 563 | rustup target add aarch64-unknown-linux-gnu |
| 564 | cargo install cross --locked |
| 565 | |
| 566 | # 每次构建 |
| 567 | cross build --release --target aarch64-unknown-linux-gnu -p codewhale-cli # 单二进制 |
| 568 | ``` |
| 569 | |
| 570 | 生成的二进制位于 `target/aarch64-unknown-linux-gnu/release/codewhale`。把它复制到 ARM64 主机（例如通过 `scp`）并赋予可执行权限。这个本地 GNU 构建与可移植的 musl release 资源不同；两个可执行文件都可以复制到 `codew` 便捷名称下使用。 |
| 571 | |
| 572 | 如果你没有 Docker，直接安装交叉链接器，让 Cargo 完成工作： |
| 573 | |
| 574 | ```bash |
| 575 | sudo apt-get install -y gcc-aarch64-linux-gnu |
| 576 | rustup target add aarch64-unknown-linux-gnu |
| 577 | |
| 578 | cat >> ~/.cargo/config.toml <<'EOF' |
| 579 | [target.aarch64-unknown-linux-gnu] |
| 580 | linker = "aarch64-linux-gnu-gcc" |
| 581 | EOF |
| 582 | |
| 583 | cargo build --release --target aarch64-unknown-linux-gnu -p codewhale-cli # 单二进制 |
| 584 | ``` |
| 585 | |
| 586 | 交叉编译时生成 `aarch64-unknown-linux-musl` 需要合适的 musl 交叉链接器。release 工作流通过在 GitHub 的原生 ARM runner 上构建并启动 musl 二进制来避免这个额外的活动部件。 |
| 587 | |
| 588 | ### Windows 源码构建 |
| 589 | |
| 590 | 在 Windows 上构建需要 [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022) 中的 **MSVC C 工具链**（免费的可选工作负载安装器，不是完整 IDE）。 |
| 591 | |
| 592 | **前置条件（Windows）** |
| 593 | |
| 594 | 1. 安装 Visual Studio 2022 Build Tools——选择 **"使用 C++ 的桌面开发（Desktop development with C++）"** 工作负载。 |
| 595 | 2. 安装 [Rust](https://rustup.rs) 1.88+（如果从中国大陆下载，参见上文[中国/镜像友好安装](#中国镜像友好安装)）。 |
| 596 | 3. 安装 [Git for Windows](https://git-scm.com/download/win)（提供 `git` 和 `git-bash` 终端）。 |
| 597 | |
| 598 | **推荐的终端**：Windows Terminal、`git-bash` 或 PowerShell。`cmd.exe` 可用，但缓冲区较小且 PATH 行为有限。 |
| 599 | |
| 600 | **设置 MSVC 环境** |
| 601 | |
| 602 | Visual Studio Build Tools 会把 `cl.exe` 安装到带版本号的目录，但**不会**把它全局加入 `PATH`。你必须手动设置环境，或使用开发者命令提示符。所需的变量是： |
| 603 | |
| 604 | ```powershell |
| 605 | # 调整版本号以匹配你的安装 |
| 606 | $msvc = "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.44.35207" |
| 607 | $sdk = "C:\Program Files (x86)\Windows Kits\10" |
| 608 | $sdkv = "10.0.26100.0" |
| 609 | |
| 610 | $env:INCLUDE = "$msvc\include;$msvc\atlmfc\include;$sdk\Include\$sdkv\ucrt;$sdk\Include\$sdkv\um;$sdk\Include\$sdkv\shared" |
| 611 | $env:LIB = "$msvc\lib\x64;$msvc\atlmfc\lib\x64;$sdk\Lib\$sdkv\ucrt\x64;$sdk\Lib\$sdkv\um\x64" |
| 612 | $env:LIBPATH = "$msvc\lib\x64;$msvc\atlmfc\lib\x64" |
| 613 | $env:CC = "$msvc\bin\Hostx64\x64\cl.exe" |
| 614 | $env:CXX = "$msvc\bin\Hostx64\x64\cl.exe" |
| 615 | $env:PATH = "$msvc\bin\Hostx64\x64;$env:PATH" |
| 616 | ``` |
| 617 | |
| 618 | 或者，打开 **"VS 2022 开发者命令提示符（Developer Command Prompt for VS 2022）"**（安装 Build Tools 后可从开始菜单找到），它会运行 `vcvars64.bat` 自动配置上述所有内容。然后在该会话中把 `cargo` 加入 `PATH`，并从项目根目录运行 `cargo build`。 |
| 619 | |
| 620 | **Cargo registry 镜像**——在 Windows 上，镜像配置放在 `%USERPROFILE%\.cargo\config.toml`。参见[上文第 2 步](#中国镜像友好安装)。 |
| 621 | |
| 622 | **构建** |
| 623 | |
| 624 | ```bash |
| 625 | git clone https://github.com/Hmbown/CodeWhale.git |
| 626 | cd CodeWhale |
| 627 | set CARGO_HTTP_CHECK_REVOKE=false # 某些中国 ISP 后面可能需要 |
| 628 | cargo build --release |
| 629 | ``` |
| 630 | |
| 631 | Cargo 构建的二进制出现在 `target\release\codewhale.exe`。发布打包会另外把同一可执行文件暴露为 `codew.exe`。 |
| 632 | |
| 633 | > 不想构建？通过 npm、Cargo、GitHub Releases 或 CNB 镜像安装——参见上文各节。 |
| 634 | |
| 635 | --- |
| 636 | |
| 637 | ## 8. Shell 补全 |
| 638 | |
| 639 | Codewhale 生成自己的补全脚本。每个 shell 一条命令；每个脚本同时补全 **`codewhale`** 和 `codew` 缩写。 |
| 640 | |
| 641 | ```bash |
| 642 | codewhale completion <bash|zsh|fish|powershell|elvish> |
| 643 | ``` |
| 644 | |
| 645 | `codewhale completions` 是同一命令的可用别名。 |
| 646 | |
| 647 | 脚本写到 stdout，因此安装它就是把输出重定向到你的 shell 加载补全的位置。 |
| 648 | |
| 649 | **Bash** —— 需要你的 shell 已加载 `bash-completion` 包： |
| 650 | |
| 651 | ```bash |
| 652 | mkdir -p ~/.local/share/bash-completion/completions |
| 653 | codewhale completion bash > ~/.local/share/bash-completion/completions/codewhale |
| 654 | ``` |
| 655 | |
| 656 | 仅当前 shell 生效：`source <(codewhale completion bash)`。 |
| 657 | |
| 658 | **Zsh** —— 脚本的 `#compdef` 行已覆盖两个命令名： |
| 659 | |
| 660 | ```bash |
| 661 | mkdir -p ~/.zfunc |
| 662 | codewhale completion zsh > ~/.zfunc/_codewhale |
| 663 | ``` |
| 664 | |
| 665 | 如果 `~/.zfunc` 不在 `fpath` 上，请把它加入 `~/.zshrc`： |
| 666 | |
| 667 | ```zsh |
| 668 | fpath=(~/.zfunc $fpath) |
| 669 | autoload -Uz compinit && compinit |
| 670 | ``` |
| 671 | |
| 672 | **Fish**： |
| 673 | |
| 674 | ```fish |
| 675 | mkdir -p ~/.config/fish/completions |
| 676 | codewhale completion fish > ~/.config/fish/completions/codewhale.fish |
| 677 | ``` |
| 678 | |
| 679 | **PowerShell** —— 追加到你的 profile，使其在每个会话中加载： |
| 680 | |
| 681 | ```powershell |
| 682 | New-Item -ItemType Directory -Force -Path (Split-Path -Parent $PROFILE) |
| 683 | codewhale completion powershell >> $PROFILE |
| 684 | ``` |
| 685 | |
| 686 | 仅当前会话生效： |
| 687 | |
| 688 | ```powershell |
| 689 | codewhale completion powershell | Out-String | Invoke-Expression |
| 690 | ``` |
| 691 | |
| 692 | **Elvish** —— 脚本注册两个命令名： |
| 693 | |
| 694 | ```elvish |
| 695 | codewhale completion elvish >> ~/.config/elvish/rc.elv |
| 696 | ``` |
| 697 | |
| 698 | 升级 Codewhale 后重新生成脚本——它是生成它的那个版本的命令面快照，不是实时查询。 |
| 699 | |
| 700 | > 从 v0.9.10 或更早版本升级？那些版本生成的脚本注册的是内部 `codewhale-tui` 可执行文件，因此 `codewhale` 或 `codew` 没有任何补全（[#5526](https://github.com/Hmbown/CodeWhale/issues/5526)）。删除旧文件并用上面的命令重新生成。 |
| 701 | |
| 702 | --- |
| 703 | |
| 704 | ## 9. 故障排查 |
| 705 | |
| 706 | ### `Unsupported architecture: arm64 on platform linux` |
| 707 | |
| 708 | 你处于 v0.8.8 之前的版本，该版本不发布 Linux ARM64 二进制。请按本文开头的说明， |
| 709 | 使用官方 GitHub 安装器安装到新的空目录；没有兼容预编译资源时，可按 |
| 710 | [第 4 节](#4-通过-cargo-安装任何-tier-1-rust-目标)使用受支持的 Cargo 源码构建路径。 |
| 711 | |
| 712 | ### 升级旧安装后出现 `MISSING_COMPANION_BINARY` |
| 713 | |
| 714 | 当前的单二进制在进程内运行 TUI，不需要配套可执行文件。该错误标识的是过时的 |
| 715 | v0.9.5 之前调度器。请按本文开头的 GitHub 迁移说明安装到新的空目录，再验证选中的 |
| 716 | `codewhale` 和 `codew` 路径。无需下载另一个单独的运行时。 |
| 717 | |
| 718 | ### `codewhale update` 报告 `no asset found for platform codewhale-linux-aarch64` |
| 719 | |
| 720 | 旧版更新器使用的 Rust 架构名与发布资源名不一致。请按本文开头的说明，使用官方 |
| 721 | GitHub 安装器安装到新的空目录，再通过新安装命令的完整路径启动。 |
| 722 | |
| 723 | ### 中国大陆 npm 下载慢或超时 |
| 724 | |
| 725 | 在 Linux x64 上，npm 包装器已经并行探测 GitHub Releases 和 CNB 第一方校验和清单，并且只从第一个通过校验的来源下载二进制。这条自动路径不需要 `CODEWHALE_USE_CNB_MIRROR=1`。 |
| 726 | |
| 727 | 如果两个第一方来源都失败，把 `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。 |
| 728 | |
| 729 | ### 中国大陆 无法从 GitHub 使用 `codewhale update` |
| 730 | |
| 731 | `codewhale update` 优先使用 GitHub Releases。在受支持的 Linux x64 平台上， |
| 732 | GitHub 校验清单失败后可回退到配套的 CNB 清单和二进制。如果 GitHub 元数据也无法访问， |
| 733 | 请显式选择已发布的 CNB 版本 |
| 734 | （`CODEWHALE_USE_CNB_MIRROR=1 CODEWHALE_VERSION=X.Y.Z codewhale update`）， |
| 735 | 或使用下方的二进制镜像设置。已有的较新构建会被保留。 |
| 736 | |
| 737 | 通过 Cargo 从 CNB 源码镜像构建是次要选项，会安装由 Cargo 管理的 `codewhale` 命令： |
| 738 | |
| 739 | 要查看最新 release 而不下载或替换二进制，运行 `codewhale update --check`。 |
| 740 | |
| 741 | ```bash |
| 742 | cargo install --git https://cnb.cool/codewhale.net/codewhale --tag vX.Y.Z codewhale-cli --locked --force # 单二进制 |
| 743 | ``` |
| 744 | |
| 745 | 如果你运营二进制资源镜像，`codewhale update` 可以直接使用它： |
| 746 | |
| 747 | ```bash |
| 748 | CODEWHALE_RELEASE_BASE_URL=https://your-mirror.example.com/CodeWhale/vX.Y.Z/ \ |
| 749 | CODEWHALE_VERSION=X.Y.Z \ |
| 750 | codewhale update |
| 751 | ``` |
| 752 | |
| 753 | 镜像目录必须包含 `codewhale-artifacts-sha256.txt` 和来自 GitHub release 的平台二进制。旧的 `DEEPSEEK_TUI_RELEASE_BASE_URL` 镜像变量仍作为别名受支持。 |
| 754 | |
| 755 | ### Debian/Ubuntu：`cargo install` 报 `feature edition2024 is required` |
| 756 | |
| 757 | 一些 Debian/Ubuntu 发行版包自带较旧的 Cargo，无法解析 Rust 2024 crate。例如，Ubuntu 24.04 上的 Cargo 1.75.0 会在构建前失败，报错： |
| 758 | |
| 759 | ```text |
| 760 | feature `edition2024` is required |
| 761 | The package requires the Cargo feature called `edition2024`, but that feature |
| 762 | is not stabilized in this version of Cargo |
| 763 | ``` |
| 764 | |
| 765 | 通过 rustup 安装当前的 stable Rust，然后重新运行[第 4 节](#4-通过-cargo-安装任何-tier-1-rust-目标)中的那条 Cargo 包安装命令。它会安装 `codewhale`。对于中国大陆网络，以下基于 rsproxy 的序列已验证可用： |
| 766 | |
| 767 | ```bash |
| 768 | export RUSTUP_DIST_SERVER=https://rsproxy.cn |
| 769 | export RUSTUP_UPDATE_ROOT=https://rsproxy.cn/rustup |
| 770 | |
| 771 | curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y |
| 772 | source "$HOME/.cargo/env" |
| 773 | rustup default stable |
| 774 | cargo install codewhale-cli --locked # 安装 codewhale |
| 775 | ``` |
| 776 | |
| 777 | 之后，`which cargo` 应指向 `~/.cargo/bin/cargo`，而不是 `/usr/bin/cargo`。 |
| 778 | |
| 779 | ### Debian/Ubuntu：构建时报 `error: linker 'cc' not found` |
| 780 | |
| 781 | 安装 C 工具链： |
| 782 | |
| 783 | ```bash |
| 784 | sudo apt-get install -y build-essential pkg-config libdbus-1-dev |
| 785 | ``` |
| 786 | |
| 787 | ### WSL2 / Ubuntu：构建时找不到 `dbus-1` 或 `pkg-config` |
| 788 | |
| 789 | WSL2 与 Ubuntu 使用相同的 Linux 源码构建路径。如果 `cargo install codewhale-cli --locked` 在编译 keyring 或 D-Bus 密钥存储 crate 时失败，请在 WSL 发行版内安装 Linux 构建依赖，然后重新运行那条 Cargo 包安装命令。它会安装 `codewhale`： |
| 790 | |
| 791 | ```bash |
| 792 | sudo apt-get update |
| 793 | sudo apt-get install -y build-essential pkg-config libdbus-1-dev |
| 794 | cargo install codewhale-cli --locked # 安装 codewhale |
| 795 | ``` |
| 796 | |
| 797 | 预编译的 npm/GitHub 二进制不需要这些构建时包；它们只在 WSL2 从源码编译 Codewhale 时才需要。 |
| 798 | |
| 799 | ### 包装器装好了但找不到 `codewhale` |
| 800 | |
| 801 | `npm i -g` 安装到 `$(npm prefix -g)/bin`；请确保该目录在你的 shell `PATH` 上。使用 nvm 时：`nvm use --lts && hash -r`。 |
| 802 | |
| 803 | ### Windows：`rustup-init` 报 `TLS handshake eof` 或 `CRYPT_E_REVOCATION_OFFLINE` |
| 804 | |
| 805 | 对 `static.rust-lang.org` 的 TLS 握手在 GFW 或某些中国 ISP 后面失败。在运行安装器**之前**设置 rustup 镜像环境变量： |
| 806 | |
| 807 | ```bash |
| 808 | # git-bash / msys2 |
| 809 | export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup |
| 810 | export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup |
| 811 | ./rustup-init.exe -y --default-toolchain stable |
| 812 | ``` |
| 813 | |
| 814 | 如果 Rust 安装后 Cargo 报 `CRYPT_E_REVOCATION_OFFLINE`，请在 `cargo build` 期间同时设置 `CARGO_HTTP_CHECK_REVOKE=false`。 |
| 815 | |
| 816 | ### Windows：`cargo build` 期间找不到 MSVC 编译器（`cl.exe`） |
| 817 | |
| 818 | Visual Studio Build Tools 不会把 `cl.exe` 加入全局 `PATH`。二选一： |
| 819 | |
| 820 | 1. 从开始菜单打开 **"VS 2022 开发者命令提示符"**，在该窗口中把 `%USERPROFILE%\.cargo\bin` 加入 `PATH`，并从那里运行 `cargo build`；或 |
| 821 | 2. 手动设置 MSVC 环境变量——PowerShell 片段见[Windows 源码构建](#windows-源码构建)一节。 |
| 822 | |
| 823 | 验证编译器可用：`cl.exe /?` 应打印帮助文本。 |
| 824 | |
| 825 | ### Windows：Cargo 执行构建脚本时报 `拒绝访问 (os error 5)` |
| 826 | |
| 827 | 第三方杀毒软件（火绒、360、卡巴斯基等）可能阻止 Cargo 执行刚编译的构建脚本二进制（例如 `libsqlite3-sys`、`aws-lc-sys`、`instability`）。该错误与路径无关——移动 `target-dir` 也无济于事。 |
| 828 | |
| 829 | **症状**：`could not execute process ... build-script-build (never executed)` |
| 830 | |
| 831 | **临时方案**（任选其一）： |
| 832 | |
| 833 | 1. **把项目的 `target/` 目录加入杀毒软件排除列表。** |
| 834 | 2. **在 `cargo build` 期间暂时关闭杀毒软件。** |
| 835 | 3. **改用 GitHub Release 安装器/压缩包**——发布资源提供预编译二进制，完全跳过 Cargo 构建（[第 6 节](#6-从-github-releases-手动下载)）。 |
| 836 | 4. **使用 crates.io 的 `cargo install codewhale-cli --locked`**——这会改变二进制路径，某些杀毒软件对不同的路径处理方式不同。 |
| 837 | |
| 838 | 要验证构建脚本二进制本身是否有效（未损坏），在 `target/debug/build/<crate>/build-script-build` 下找到它并手动运行： |
| 839 | |
| 840 | ```bash |
| 841 | target/debug/build/libsqlite3-sys-*/build-script-build |
| 842 | # 如果它能运行但以 "NotPresent"（没有 C 编译器）panic，说明二进制没问题—— |
| 843 | # 是杀毒软件专门在阻止 Cargo 的进程派生路径。 |
| 844 | ``` |
| 845 | |
| 846 | ### npm 二进制下载超时 |
| 847 | |
| 848 | 如果 `codewhale` 等待几秒后打印 `connect ETIMEDOUT` 或 `EAI_AGAIN`（从 `github.com` 拉取时），说明 npm 包装器安装成功，但预编译二进制下载在你的网络上被屏蔽或不稳定。该下载与 npm registry 包下载是分开的。在 Linux x64 上，包装器先竞争小型 GitHub 和 CNB 校验和清单，不会等到完整 GitHub 二进制超时才使用有效的 CNB 清单。 |
| 849 | |
| 850 | 使用以下路径之一： |
| 851 | |
| 852 | 1. 设置代理并重试： |
| 853 | |
| 854 | ```bash |
| 855 | export HTTPS_PROXY=http://your-proxy:port |
| 856 | codewhale |
| 857 | ``` |
| 858 | |
| 859 | 2. 在内部镜像 release 资源并设置 `CODEWHALE_RELEASE_BASE_URL`： |
| 860 | |
| 861 | ```bash |
| 862 | export CODEWHALE_RELEASE_BASE_URL=https://your-mirror.example.com/CodeWhale/ |
| 863 | codewhale |
| 864 | ``` |
| 865 | |
| 866 | 目录必须包含 `codewhale-artifacts-sha256.txt` 和来自 GitHub release 的平台二进制。 |
| 867 | |
| 868 | 3. 通过 Cargo 安装，它在本地构建，不下载 GitHub release 资源。参见[第 4 节](#4-通过-cargo-安装任何-tier-1-rust-目标)。 |
| 869 | |
| 870 | 4. 从 [Releases 页面](https://github.com/Hmbown/CodeWhale/releases) 下载匹配的 `codewhale` 和 `codew` 两个二进制，放入 `PATH` 上的目录并赋予可执行权限。参见[第 6 节](#6-从-github-releases-手动下载)。 |
| 871 | |
| 872 | --- |
| 873 | |
| 874 | ## 10. 验证你的安装 |
| 875 | |
| 876 | ```bash |
| 877 | codewhale --version |
| 878 | codewhale doctor # 检查 API key、provider、运行时与 PATH 完整性 |
| 879 | codewhale doctor --json |
| 880 | ``` |
| 881 | |
| 882 | 如果 `doctor` 发现问题，会以非零状态退出并打印结构化的修复提示。需要帮助时，把 JSON 输出粘贴到 GitHub issue 中。 |
| 883 |