返回 CodeWhale
ENVIRONMENTS.md
根目录 / docs / zh_hans / ENVIRONMENTS.md
1 # 特定环境的注意事项
2
3 > 英文原文：[ENVIRONMENTS.md](../ENVIRONMENTS.md)。
4 > 最后与英文同步日期（last synced with English revision）：2026-09-29。
5
6 标准的构建/测试/运行命令放在 `AGENTS.md` 和 `CONTRIBUTING.md`。本文件只记录
7 特定环境里那些不明显的怪癖，免得在永远碰不到它们的机器上占用上下文。
8
9 ## Cursor Cloud 虚拟机
10
11 - **系统构建依赖：** 构建需要 `libdbus-1-dev`（由 `crates/secrets` 为 OS
12 密钥环引入）。它由启动更新脚本安装；如果 `cargo build` 报 `dbus`/`pkg-config`
13 错误，就是缺这个依赖。
14 - **必须设置 `rustup default`：** 有些测试和运行时（runtime）路径会在本检出
15 目录*之外*的临时目录里拉起 shell（例如 `run_verifiers_background_*`、
16 子智能体（subagent）工作树）。这些被拉起的 shell 只有在 `/workspace` 内部
17 才能看到仓库的 `rust-toolchain.toml` 覆盖设置，所以没有全局默认值时，
18 它们会以“rustup could not choose a version of rustc to run”失败。
19 更新脚本会运行 `rustup default stable` 来修复这一点。
20 - **`/workspace` 上已知的环境相关测试失败（不是代码缺陷）：** 因为检出目录
21 直接位于 `/` 之下，有两个 `codewhale-tui` 子智能体测试会在这里失败——
22 `git_repo_root_reports_attempted_paths_when_no_repo_found`（无法在不可写的
23 父目录 `/` 里创建临时目录）和
24 `create_isolated_worktree_reports_friendly_error_when_no_repo_found`
25 （向上遍历到 `/` 时会把 `/workspace` 本身当成仓库）。当仓库检出到一个正常
26 可写的父目录下时，这两个测试都会通过。
27
28 ## 在没有提供商 API key 的情况下运行智能体
29
30 通过免密钥的 `vllm`/`ollama`/`sglang` 提供商（provider），把 Codewhale
31 指向任意本地 OpenAI 兼容端点：
32
33 ```sh
34 CODEWHALE_PROVIDER=vllm VLLM_BASE_URL=http://127.0.0.1:8000/v1 VLLM_MODEL=<id> \
35 codewhale exec --auto "..."
36 ```
37
38 `codewhale exec`（加上 `--auto` 可启用工具调用）是跑通完整智能体循环的非交互路径。
39
40 ## 在回合期间让主机保持唤醒
41
42 交互式 TUI 回合（turn）进行中时，Codewhale 会持有平台的空闲休眠断言，
43 这样无人值守的机器不会在回合中途空闲入睡而丢掉工作：
44
45 - macOS：`caffeinate -i`
46 - Linux：`systemd-inhibit --what=idle --why="Codewhale turn in flight" --mode=block cat`，
47 其中 `cat` 读取的管道由 Codewhale 在回合期间持有
48
49 断言在回合结束的那一刻释放——在 Linux 上通过关闭那条管道实现，于是 `cat`
50 退出、`systemd-inhibit` 随之结束，不会留下残留进程——而且它只覆盖*空闲*休眠：
51 显式执行 `sleep` / `pmset sleepnow`、合上盖子或电量过低仍会让机器挂起。
52 无头主机——`exec`、app-server、CI——从不持有它，所以共享 runner 的电源策略
53 不受影响。Windows 未实现：`SetThreadExecutionState` 是线程亲和的，需要一个
54 固定线程的持有者，所以这个缺口是有意为之，而不是被悄悄忽略。
55
56 如果回合还是被挂起了，引擎会在唤醒时察觉——墙上时钟耗时与单调时钟耗时之差
57 超过挂起阈值——上报 `System sleep detected; connection lost — retrying request`，
58 并重新发起请求，而不是让回合失败（#2990）。
59
60 ## Windows PowerShell 执行策略
61
62 shell 工具以 `-ExecutionPolicy Bypass` 运行 PowerShell。它只设置所启动子进程
63 自己的策略：不会持久化，不需要管理员权限，你自己打开的 PowerShell 窗口仍保持
64 原有策略。没有它时，本地策略为 `Restricted`（Windows 客户端的默认值）或
65 `AllSigned` 的机器，会拒绝运行 Codewhale 为多行命令写入的临时 `.ps1` 脚本
66 （#6745）。
67
68 由组策略设置的策略（`Get-ExecutionPolicy -List` 中 `MachinePolicy` 或
69 `UserPolicy` 行）优先级高于进程范围。在这样的机器上，多行命令仍会被拒绝，
70 PowerShell 的拒绝信息会作为该命令的错误返回；Codewhale 不会绕过管理员强制的
71 策略。单行命令通过 `-Command` 运行，不受执行策略约束。命令自身调用的脚本也在
72 同一进程范围内运行；决定什么可以运行的是 shell 工具的审批与沙箱设置，而不是
73 执行策略。
74
75 若希望改由机器或用户策略生效，请在启动 Codewhale 之前设置
76 `CODEWHALE_POWERSHELL_EXECUTION_POLICY=inherit`：此时 shell 工具会完全省略
77 `-ExecutionPolicy`，因此策略为 `Restricted` 或 `AllSigned` 时，需要临时 `.ps1`
78 脚本的多行命令会被拒绝。未设置、设置为 `bypass` 或任何其他值时，仍保持默认的
79 `Bypass`。
80
81 ## 统一的运行时命令
82
83 当前的 `codewhale` 二进制在进程内运行 TUI。发布安装器会把同样的字节复制到
84 可选的 `codew` 短命令；不需要另外的 `codewhale-tui` 可执行文件。
85 `DEEPSEEK_TUI_BIN` 仍是遗留的回放/迁移设置，不是当前安装所必需的。
86
86 lines MARKDOWN