| 1 | # Codewhale 用户指南 |
| 2 | |
| 3 | > 本文翻译自英文版 [GUIDE.md](../GUIDE.md)，与英文修订 `3c3630396`（2026-08-19）同步。 |
| 4 | |
| 5 | 本指南面向你使用 Codewhale 的第一个小时。它涵盖了主要工作流程、重要安全控制，以及当你需要完整参考时接下来该看什么。 |
| 6 | |
| 7 | Codewhale 有更深入的参考文档，涵盖安装、配置、提供商（provider）、模式、快捷键、工具和运维。请将本页当作引导式走查，需要每个选项时再顺着"下一步"链接往下看。 |
| 8 | |
| 9 | ## 1. 欢迎使用 Codewhale |
| 10 | |
| 11 | Codewhale 是一个终端编码智能体（agent）。你从某个工作区运行它，交给它一个任务，它就能用结构化工具检查文件、运行命令、编辑代码，并带回证据汇报结果。 |
| 12 | |
| 13 | 与普通聊天模型的重要区别在于，Codewhale 是围绕 “驾驭框架”（harness） 构建的： |
| 14 | |
| 15 | - 它让活动工作区和会话保持可见。 |
| 16 | - 它把每一轮都路由到明确的模式与审批规则。 |
| 17 | - 它在对话记录中展示工具调用，而不是把工作藏起来。 |
| 18 | - 它可以保存会话、分叉对话，并在之后继续。 |
| 19 | - 它可以运行子智能体来执行专注的后台工作。 |
| 20 | |
| 21 | 你可以用 Codewhale 回答小问题： |
| 22 | |
| 23 | ```text |
| 24 | 解释此仓库中的身份验证流程。 |
| 25 | ``` |
| 26 | |
| 27 | 也可以用它做多步工作： |
| 28 | |
| 29 | ```text |
| 30 | 找到失败的验证路径，提出修复方案，等我批准了再编辑文件。 |
| 31 | ``` |
| 32 | |
| 33 | 对于新仓库，请从保守的方式开始。在要求 Codewhale 修改文件之前，先让它探索和规划。这样会为您提供可审查的路径，并更容易及早发现错误的假设。 |
| 34 | |
| 35 | 下一步：[ARCHITECTURE.md](../ARCHITECTURE.md) 讲解内部 harness 与运行时模型。 |
| 36 | |
| 37 | ## 2. 首次启动 |
| 38 | |
| 39 | 在 macOS 或 Linux 上首次安装时，使用官方 GitHub Release。安装器会校验发布资源， |
| 40 | 并在 `codewhale` 和 `codew` 两个命令名下提供同一运行时： |
| 41 | |
| 42 | ```bash |
| 43 | curl -fsSL https://codewhale.net/install.sh | sh |
| 44 | ``` |
| 45 | |
| 46 | Windows 用户请选择 [GitHub Releases](https://github.com/Hmbown/CodeWhale/releases/latest) |
| 47 | 中的对应安装器或压缩包。已有的直接安装先运行 `codewhale update --check`，再运行 |
| 48 | `codewhale update`。npm 和 Cargo 是次要打包方式；没有兼容预编译资源的平台仍可使用 |
| 49 | 受支持的 Cargo 源码构建路径。目录已占用、包管理器安装及 PATH 配置请参阅 |
| 50 | [安装与迁移指南](INSTALL.md)。Android/Termux 使用专用的 |
| 51 | [预览压缩包或源码构建路径](INSTALL.md#android--termux-arm64)。 |
| 52 | |
| 53 | 当你想要隔离的运行时，也可以用 Docker： |
| 54 | |
| 55 | ```bash |
| 56 | docker volume create codewhale-home |
| 57 | docker run --rm -it \ |
| 58 | -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \ |
| 59 | -v codewhale-home:/home/codewhale/.codewhale \ |
| 60 | -v "$PWD:/workspace" \ |
| 61 | -w /workspace \ |
| 62 | ghcr.io/hmbown/codewhale:latest |
| 63 | ``` |
| 64 | |
| 65 | 把安装目录加入 PATH 后，从你希望它工作的仓库或目录启动 Codewhale： |
| 66 | |
| 67 | ```bash |
| 68 | codewhale |
| 69 | ``` |
| 70 | |
| 71 | 使用 GitHub 安装器的默认目录时，在把该目录加入 PATH 之前，可以通过 |
| 72 | `"$HOME/.local/bin/codewhale"` 启动。 |
| 73 | |
| 74 | 首次启动时，Codewhale 只询问本次安装仍然需要的决定：无法推断语言时询问语言，未配置可用路由时询问提供商，文件夹需要决定时询问工作区信任。提供商步骤包含明确的离线路由。就绪界面随后打开真正的编辑器，保留命令行中提供的任务，或为当前文件夹建议第一个任务。 |
| 75 | |
| 76 | 此后所有可选内容都保持可用。用 `/setup` 打开渐进式设置与修复指南，用 `/settings` 打开完整键入式编辑器，想自定义内置工作约定时用 `/constitution`。本地化遥测选择只在工作区就绪后出现，不会阻塞编辑器。 |
| 77 | |
| 78 | DeepSeek 是默认提供商。如果你想在首次启动之前或之后配置它的 key，最直接的设置路径是： |
| 79 | |
| 80 | ```bash |
| 81 | codewhale auth set --provider deepseek |
| 82 | ``` |
| 83 | |
| 84 | 你也可以通过环境变量提供 key： |
| 85 | |
| 86 | ```bash |
| 87 | export DEEPSEEK_API_KEY="your-key" |
| 88 | codewhale |
| 89 | ``` |
| 90 | |
| 91 | 新的 Codewhale 配置存放在 `~/.codewhale/config.toml`。旧的 `~/.deepseek/config.toml` 文件仍受支持，供从旧名称迁移的用户使用。 |
| 92 | |
| 93 | 用 `/constitution` 查看或更改常驻指引。设置完成后，运行一次 doctor 检查： |
| 94 | |
| 95 | ```bash |
| 96 | codewhale doctor |
| 97 | ``` |
| 98 | |
| 99 | 当你需要机器可读的报告用于提交 issue 时，用 JSON 形式： |
| 100 | |
| 101 | ```bash |
| 102 | codewhale doctor --json |
| 103 | ``` |
| 104 | |
| 105 | 两种形式默认都是离线的。 |
| 106 | 它们报告结构配置和字面上的未知/未探测凭证状态，不会加载工作区的 `.env` 凭据、打开 secret/OAuth 文件、探测密钥串、联系提供商或启动 MCP 服务器。只有有意需要该实时边界时，才使用 `--check-updates`、`--probe-api`、`--probe-local` 或 `--probe-mcp`。JSON 保持离线，不接受实时标志。 |
| 107 | |
| 108 | JSON 把凭据的 `source`（来源）与字面的 `availability`（可用性）分开报告。配置的环境、外部认证、OAuth、consent 和 secret-store 来源仍为 `not_probed`；它们的声明本身并不会让 Setup 或 fleet 就绪。只有结构上存在的字面配置值，或一条不需要凭据的路由，才能证明离线就绪。对于无法使用共享存储的路由上的旧版密钥存储哨兵（secret-store sentinel），会单独报告为 `secret_store_unavailable`/`unavailable`，而不是简单的"符合条件"或"未知"。 |
| 109 | |
| 110 | `doctor` 和 `doctor --json` 都还包含一项会话恢复诊断，它把旧会话文件名与当前存储对比，不读取会话内容，并报告以下之一： `isolated`、`no_legacy_sessions`、`migration_pending`、`migration_incomplete`、`migration_complete` 或 `scan_failed` 。 |
| 111 | 使用 `migration_pending` 或 `migration_incomplete` 作为提示，完成把会话从 `~/.deepseek` 迁移到 `~/.codewhale` 的工作——就是上面提到的旧路径迁移。显式设置 `CODEWHALE_HOME` 会抑制此环境检查。 |
| 112 | |
| 113 | 下一步：[INSTALL.md](INSTALL.md) 涵盖各平台的安装路径，[CONFIGURATION.md](CONFIGURATION.md) 涵盖配置解析，[PROVIDERS.md](PROVIDERS.md) 涵盖提供商 ID 与凭据。 |
| 114 | |
| 115 | ## 3. 你的第一个任务 |
| 116 | |
| 117 | 从一个真实工作区里的只读任务开始： |
| 118 | |
| 119 | ```text |
| 120 | 映射仓库结构，并告诉我 CLI 入口点在哪里。 |
| 121 | ``` |
| 122 | |
| 123 | 然后要一份有重点的计划： |
| 124 | |
| 125 | ```text |
| 126 | 我想为空的配置值添加一个小型验证。 |
| 127 | 检查相关代码，并在编辑任何内容之前提出最小的安全更改。 |
| 128 | ``` |
| 129 | |
| 130 | 当你准备好做编辑时，把验收标准说具体： |
| 131 | |
| 132 | ```text |
| 133 | 实施你提出的验证。 |
| 134 | 将更改范围限制在配置解析内，添加或更新最窄的测试，并运行相关的检查。 |
| 135 | ``` |
| 136 | |
| 137 | 好的首批提示词（prompt）包含四个要素： |
| 138 | |
| 139 | - 你想要的结果。 |
| 140 | - 你关心的文件、功能或行为。 |
| 141 | - 哪些不在范围内。 |
| 142 | - 什么算"验证通过"。 |
| 143 | |
| 144 | 例如： |
| 145 | |
| 146 | ```text |
| 147 | 修复配置加载器中损坏的提供程序错误消息。 |
| 148 | 不要更改提供程序注册表。添加回归测试，并且只运行 config 包的测试。 |
| 149 | ``` |
| 150 | |
| 151 | 如果你不确定 bug 在哪，直说： |
| 152 | |
| 153 | ```text |
| 154 | 调查为什么 `codewhale doctor` 报告了错误的提供程序。 |
| 155 | 暂时不要编辑文件。返回可能的原因、证据和提议的补丁计划。 |
| 156 | ``` |
| 157 | |
| 158 | 面对不熟悉的代码，让调查和实现分步进行时 Codewhale 表现最好。对于很小且充分理解的改动，一个单独的实现请求就够了。 |
| 159 | |
| 160 | 下一步：[MODES.md](MODES.md) 讲解何时使用 Plan、Act 和 Operate。 |
| 161 | |
| 162 | ## 4. 了解界面 |
| 163 | |
| 164 | 交互式 TUI 有几个稳定的区域： |
| 165 | |
| 166 | - 头部（Header）：当前会话、活动模型、模式和总体状态。 |
| 167 | - 转录区（对话记录，Transcript）：对话、工具调用、命令输出摘要和模型回复。 |
| 168 | - 输入区（Composer）：你在这里输入提示、斜杠命令和文件提及。 |
| 169 | - 工作栏（Work bar）：转录区上方的一条（或可选的侧栏），承载活动目标、待办列表和子智能体。行会保持整个会话——已完成的工作显示为"已完成"而不是消失——点击某一行（或对它按 `Enter`）会打开它的详情。 |
| 170 | - 状态与底部区域：实时活动、排队的后续动作和简短命令提示。 |
| 171 | |
| 172 | 底部区域可配置。运行 `/statusline` 选择哪些内容可见，或在 `config.toml` 里设置 `[tui].status_items`。每个键只对应屏幕上的一样东西：`mode` 是姿态栏的 plan/act/operate 片区，而 `model`、`context_percent`、`cost`、`balance`（仅限预付费提供商：DeepSeek、DeepSeekCN、OpenRouter、SiliconFlow）、`cache`、`tokens` 、`ttft`、`output_rate`、`workspace` 和 `git_branch` 是它下方指标行的片区。 |
| 173 | 省略 `status_items` 以保持内置默认；把它设为 `[]` 只保留帮助提示。 |
| 174 | |
| 175 | `workspace` 和 `git_branch` 默认关闭。工作区片区显示文件夹名称；链接工作树会包含父目录以区分同名文件夹。分支片区显示当前分支或游离 HEAD 的短 SHA，并用 `(wt)` 标记链接工作树。名称过长时，保留末尾并限制为 24 个显示列。Git 信息沿用每 15 秒的后台刷新机制，也可按需刷新；无法取得 Git 信息时省略分支片区。这些信息对应当前会话的工作区，完整路径仍可在 `/status` 查看。 |
| 176 | |
| 177 | `context_percent` 默认开启，并在任何占用率下都显示 `ctx NN%`——0.9.12 在 50% 以下保持沉默，使会话的大部分时间都没有上下文信号。该读数从 80% 起仍使用警示配色。 |
| 178 | |
| 179 | `status`、`agents`、`reasoning_replay`、`prefix_stability`、`last_tool_elapsed` 和 `rate_limit` 这些键在 0.9.13 中已退役：它们不驱动任何东西。旧的配置文件仍可加载——已退役的键会被忽略并在日志中给出警告。 |
| 180 | |
| 181 | `status_items` 负责组合这两行；另有两个尺寸预设决定每行绘制多少。`[tui].posture_bar` 和 `[tui].metrics_line` 各接受 `full`、`compact` 或 `hidden`。姿态栏默认使用 `full` 以保留操作提示；指标行默认使用 `compact`，减少常驻遥测信息，也可以在运行时用 `/config posture_bar compact` 设置。TOML 中的值必须使用小写；`/config` 命令不区分大小写。`compact` 是该行走完最初几级舍弃阶梯后的样子：姿态栏保留权限与模式片区——以及属于建议而非装饰的容量警示——并舍弃时钟、计数和提示；指标行保留路由、上下文读数、成本和余额，并在空间足够时保留已选的 TTFT 和输出速率，舍弃次要计数与帮助提示。`hidden` 把该行交还给转录区。狭小的 tmux 面板可以隐藏两行而不动 `/statusline` 的组合。 |
| 182 | |
| 183 | `session_metrics`（默认开启）在指标行上显示 `ttft 1.5s`（到首个流式 token 的平均时间）和 `120 平均 tok/s`（本次会话中提供商报告的输出 token 总数，除以同一批调用的实测请求总秒数）。速率包含连接建立、首 token 等待以及响应过程中的停顿，不包含工具执行和调用之间的空闲时间；它衡量请求的实际吞吐量，而非模型解码速度。流式和非流式调用使用相同规则；没有独立请求计时的回执，其 token 和时间都不计入。新请求进行时保留上次实测平均值。两项读数与 `/status` 共用累加器，缺少证据时省略而不估算。在窄行上，这一对会先于成本和上下文读数被舍弃。 |
| 184 | |
| 185 | 转录区（对话记录）就是审计轨迹。当 Codewhale 读文件、跑命令或改代码时，动作会出现在那里。如果某条命令失败，把可见的失败输出作为你下一条指令的一部分，而不是从头再来。 |
| 186 | |
| 187 | 输入区接受普通提示和斜杠命令。输入 `/` 可以发现可用命令。想让模型专注于某个特定文件或目录而不是广泛搜索时，使用文件提及。 |
| 188 | |
| 189 | 当一个回合跨越多个步骤时，工作栏很有用。它让目标、待办列表和智能体状态保持可见，同时转录区继续增长——包括在工作落定之后，这样你仍然可以打开看看发生了什么。 |
| 190 | |
| 191 | 键盘快捷键因上下文、终端和平台而异。本指南不重复完整的快捷键目录，以免与 TUI 脱节。 |
| 192 | |
| 193 | 下一步：[KEYBINDINGS.md](KEYBINDINGS.md) 是完整的快捷键参考。 |
| 194 | |
| 195 | ## 5. 模式 |
| 196 | |
| 197 | Codewhale 有三种可见的 TUI 模式： |
| 198 | |
| 199 | | 模式 | 用于 | 默认姿态 | |
| 200 | | --- | --- | --- | |
| 201 | | Plan | 改动前的探索、设计与审查 | 只读调查 | |
| 202 | | Act | 常规的多步编码工作 | 带审批门禁的工具使用 | |
| 203 | | Operate | 直接工作，外加并行或后台协调 | 工具遵循活动姿态；需要时委派 | |
| 204 | |
| 205 | 从 TUI 里用模式选择器切换模式： |
| 206 | |
| 207 | ```text |
| 208 | /mode |
| 209 | ``` |
| 210 | |
| 211 | 或直接切换： |
| 212 | |
| 213 | ```text |
| 214 | /mode plan |
| 215 | /mode act |
| 216 | /mode operate |
| 217 | ``` |
| 218 | |
| 219 | Plan 模式是在陌生仓库里开始的最安全位置。它用于检查和决策，不做文件编辑。对于非平凡的工作，Plan 模式的确认提示可以显示有依据的计划工件（PlanArtifact）：目标、上下文、使用的来源、关键文件、约束、方法、验证计划、风险和交接说明。 |
| 220 | 当智能体（agent）使用富工件形态时，空章节也是可见的，所以你可以要求修订，而不是接受一份说明不足的计划。 |
| 221 | |
| 222 | Act 模式是大多数贡献工作的默认模式。它允许 Codewhale 读文件、跑检查、编辑文件，同时把有风险的动作留在审批门禁之后。 |
| 223 | |
| 224 | Operate 保持直接的工具面及其审批、沙箱、shell、ask 规则和仓库保护。小型或紧密耦合的工作直接处理。多步骤委派使用简洁的 Workflow 计划，明确依赖关系、工作范围，并在步骤间传递完成证据。Fleet 配置和管理的就是这些子智能体及其角色。一个范围明确、可独立完成的任务可以直接交给子智能体；后续工作通过 `followup` 继续使用同一个子智能体。 |
| 225 | |
| 226 | 对于你信任的工作区，如果你确实希望动作不经审批提示就继续，可以用 `Shift+Tab` 选择 Full Access 权限姿态。不要在你不信任的仓库里使用 Full Access。 |
| 227 | |
| 228 | 模式与模型路由是分开的。输入区空闲时 `Tab` 循环切换可见模式，而 `/model auto` 控制回合的模型与思考选择。 |
| 229 | |
| 230 | 你也可以在 `/config` 里通过编辑审批模式来改变审批行为。只有当你理解它会如何改变工具执行时才使用它。 |
| 231 | |
| 232 | 下一步：[MODES.md](MODES.md) 有完整的模式、审批和信任模式参考。 |
| 233 | |
| 234 | ## 6. 斜杠命令 |
| 235 | |
| 236 | 斜杠命令在输入区里输入。当你想要直接改变 Codewhale 状态，而不是用自然语言让模型去做时，它们很有用。 |
| 237 | |
| 238 | 对首次用户常用的命令： |
| 239 | |
| 240 | | 命令 | 用途 | |
| 241 | | --- | --- | |
| 242 | | `/mode` | 打开模式选择器，或用 `/mode agent` 切换 | |
| 243 | | `/model` | 选择模型，或用 `/model auto` | |
| 244 | | `/provider` | 选择活动的 API 提供商| |
| 245 | | `/fleet` | 打开当前所选 fleet 的成员花名册 | |
| 246 | | `/fleet saved` | 选择或切换已命名保存的 fleet | |
| 247 | | `/goal` | 设置一个智能体跨回合持续追求的持久目标；裸 `/goal` 显示进度 | |
| 248 | | `/workflow` | 把当前工作编排为 Workflow；`status`、`cancel`、`settings` 无需模型回合即可回答 | |
| 249 | | `/workflows` | 打开实时 Workflow 运行仪表盘：该工作区日志记录的每一次运行，含阶段、子项、进度和主机侧取消 | |
| 250 | | `/config` | 编辑运行时与提供商设置 | |
| 251 | | `/statusline` | 选择哪些底部状态芯片可见 | |
| 252 | | `/compact` | 压缩长上下文以回收 token 预算 | |
| 253 | | `/review` | 请求结构化的审查工作流 | |
| 254 | | `/memory` | 启用时检查或管理记忆 | |
| 255 | | `/mcp` | 配置或检查 MCP 服务器集成 | |
| 256 | | `/plugin` | 审查和管理默认禁用的本地插件包 | |
| 257 | | `/rc` | 把此确切会话交给已登录的 Codewhale 网页应用 | |
| 258 | |
| 259 | 工具箱命令直接输入即可搜索：`/models` 拉取实时端点 ID，`/modeldb` 打开内置模型参考，`/rlm` 把文件或一段文本加载进工作上下文，在会话剩余时间里保持可用。 |
| 260 | |
| 261 | 想切离默认的 DeepSeek 路由时用 `/provider`。Provider ID、环境变量、模型默认值和能力说明都保留在提供商注册表文档里。 |
| 262 | |
| 263 | 软自动多智能体工作：[AUTOMATIC_WORKFLOWS.md](../AUTOMATIC_WORKFLOWS.md)。 |
| 264 | |
| 265 | 面向持久多 worker 工作的下一步：[FLEET_WORKFLOW_TUTORIAL.md](../FLEET_WORKFLOW_TUTORIAL.md) 带你走一遍 fleet 任务规格、监控和 Workflow 编写。 |
| 266 | |
| 267 | 想让 Codewhale 每回合自己选模型和思考级别时，用 `/model auto`。当 DeepSeek 路由模型可用时，Auto 可以在脱敏清单中选取任何可运行的 provider/模型组合。该分类会把最新请求（上限 4,000 字符）加上最多六条最近上下文行的有界摘要（每条 900 字符）发送到 `DeepSeek / deepseek-v4-flash`。凭据、端点和提供商错误文本不会包含在清单里。没有该路由器时，Auto 使用本地的、感知提供商的启发式方法，不发送任何路由请求。如果分类尝试未通过验证或出错，Auto 回退到该启发式方法，同时把尝试过的分类器数据路径保留在回合回执中。 |
| 268 | |
| 269 | `/model` 选择器会说明哪条数据路径可用，并显示最后解析的路由。`Ctrl+O` 打开所选或当前回合的推理详情；`Ctrl+Alt+O`（或 `/turn inspect`）打开整回合的回合检查器（Turn Inspector），其模型路由区记录具体的 provider/模型、strong/fast 配对、所选层级、选择范围、路由原因，以及分类器是否收到了路由上下文。当你需要可重复的比较、严格的提供商边界或完全不要分类请求时，使用固定模型。 |
| 270 | |
| 271 | 会话变长、模型开始承载太多历史记录时，用 `/compact`。压缩会用简洁的工作摘要换取原始转录细节。 |
| 272 | |
| 273 | 本指南有意不列出每条命令。命令面比上手流程变化更频繁，你在会话里时，TUI 命令面板才是事实来源。 |
| 274 | |
| 275 | 下一步：[CONFIGURATION.md](CONFIGURATION.md) 涵盖运行时设置，[MCP.md](MCP.md) 涵盖模型上下文协议（MCP，Model Context Protocol）集成。[PLUGIN_BUNDLES.md](../PLUGIN_BUNDLES.md) 涵盖默认禁用的包清单、能力审查和带命名空间的 Skill/MCP 激活边界。 |
| 276 | |
| 277 | ## 7. 使用工具 |
| 278 | |
| 279 | Codewhale 的工具是结构化操作。模型不只是产出文字，还能调用工具来检查和改变工作区。 |
| 280 | |
| 281 | 工具支撑的工作示例包括： |
| 282 | |
| 283 | - 解释文件之前先读它。 |
| 284 | - 提出重构之前先搜索调用点。 |
| 285 | - 运行一条有重点的测试命令。 |
| 286 | - 应用一个小补丁。 |
| 287 | - 为并行调查打开一个子智能体。 |
| 288 | |
| 289 | 工具使用由模式、审批和沙箱策略约束。确切行为取决于当前模式和配置，但基本规则很简单：只读探索用 Plan 开始，常规改动用 Act，Full Access 留给受信任的自动化。 |
| 290 | |
| 291 | 工作区边界很重要。Codewhale 应该在你启动它的目录或你配置的工作区里工作。当任务应该留在仓库内时要说清楚： |
| 292 | |
| 293 | ```text |
| 294 | 就检查并编辑此仓库下的文件。别触父目录和全局配置。 |
| 295 | ``` |
| 296 | |
| 297 | 当命令需要网络、在工作区外写入或有风险的 shell 操作时，除非你配置了更宽松的行为，否则期待一个审批提示。 |
| 298 | |
| 299 | 好的工具指令是具体的： |
| 300 | |
| 301 | ```text |
| 302 | 运行覆盖此解析器更改的最窄测试。 |
| 303 | 如果失败，报告失败并在扩大测试范围之前停止。 |
| 304 | ``` |
| 305 | |
| 306 | 避免在专注修复期间要求广泛的清理。较小的工具范围使对话记录更易于审查，最终的差异更易于合并。 |
| 307 | |
| 308 | 下一步：[TOOL_SURFACE.md](../TOOL_SURFACE.md) 列出工具面，[SANDBOX.md](../SANDBOX.md) 讲解沙箱行为。 |
| 309 | |
| 310 | ## 8. 子智能体与并行工作 |
| 311 | |
| 312 | 子智能体是后台子代理。父会话给子代理一个专注的任务，收到一个 agent id，然后可以在子代理运行时继续工作。 |
| 313 | |
| 314 | 主要的编排工具是： |
| 315 | |
| 316 | - `agent`：带任务和角色启动一个专注的子代理。子代理在后台运行，返回一份紧凑回执加转录句柄。 |
| 317 | |
| 318 | 你通常不需要直接调用这些工具。用自然语言请求并行工作： |
| 319 | |
| 320 | ```text |
| 321 | 为 config 包打开一个只读探索器，为 TUI 提供商选择器打开另一个。让两者在规划修复之前返回文件引用和风险。 |
| 322 | ``` |
| 323 | |
| 324 | 有用的角色包括： |
| 325 | |
| 326 | | 角色 | 适合 | |
| 327 | | --- | --- | |
| 328 | | `general` | 多步任务；未指定角色时的默认值 | |
| 329 | | `explore` | 只读代码梳理 | |
| 330 | | `plan` | 设计与迁移规划 | |
| 331 | | `review` | 对已有改动的 bug 聚焦审查 | |
| 332 | | `implementer` | 规格明确的编辑 | |
| 333 | | `verifier` | 运行检查并报告通过/失败证据 | |
| 334 | |
| 335 | 子智能体在可以干净切分工作的时候最有用。不要为微小编辑使用它们，也不要让多个智能体同时写入相同文件。 |
| 336 | |
| 337 | ### 长时间工作如何保持连贯 |
| 338 | |
| 339 | 跨越多个回合的工作不依赖无限增长的聊天转录。这是普通 Agent 行为——不需要打开任何东西，也没有单独的工作流要学： |
| 340 | |
| 341 | - 工作上下文在整个会话中保持加载。大段源材料和持久转录作为数据保存，智能体可以搜索和切片，有用的变量与导入跨回合存活。 |
| 342 | - Workflow 组合独立的 `task(...)` 调用和并行扇出。 |
| 343 | - `agent` 消息与后续动作直接协调活动的子代理。 |
| 344 | - 目标（Goals）在工作期间保留持久目标。 |
| 345 | |
| 346 | `/rlm <file-or-text>` 把工作上下文指向一个特定文件或一段文本。历史上一度存在的动作形态 `rlm` 工具仍然注册着，只为了让旧会话能回放，并且刻意不教给新的模型回合。 |
| 347 | |
| 348 | Codewhale 还可以在 `.codewhale/harness/state.json` 维护一个小型项目级账本：有证据支撑的提示备注、可复用的子代理简报和 skill 路由提示。之后的回合会把它当作不受信任的补充指导接收，绝不是权威或可执行指令。读取它是自动的；添加或删除条目要走正常的审批回执。它和个人记忆是分开的，绝不能保存密钥、草稿转录或未经证实的说法。 |
| 349 | |
| 350 | 下一步：[SUBAGENTS.md](SUBAGENTS.md) 涵盖角色、生命周期、并发和输出契约。 |
| 351 | |
| 352 | ## 9. 技能（Skills） |
| 353 | |
| 354 | 技能是可复用的指令包。一个技能通常是 `SKILL.md` 文件，教 Codewhale 如何执行某个重复工作流、使用某类工具，或遵循某项项目约定。 |
| 355 | |
| 356 | 当任务有可重复的流程时使用技能： |
| 357 | |
| 358 | - 审查某一类 PR。 |
| 359 | - 处理某种文档或电子表格格式。 |
| 360 | - 遵循团队发布检查清单。 |
| 361 | - 使用项目特定的记忆或 wiki 工作流。 |
| 362 | |
| 363 | 在 TUI 里，`/skill <name>` 在可用时激活技能，裸 `/skills` 打开技能管理器（仅限自有清单，无网络）。用 `/skills <prefix>`、`/skills inspect`、`/skills --remote`、`/skills suggest <task>` 或 `/skills sync` 走文本/注册表路径。建议会对远程目录排序，但绝不安装或激活任何东西。命令面板也能把技能条目和普通斜杠命令一起展示。 |
| 364 | |
| 365 | 知识贵广，技能贵精。它们应该告诉模型遵循什么工作流、收集什么证据、避免什么。它们不应该隐藏凭据或取代正常的仓库文档。 |
| 366 | |
| 367 | 如果仓库有自己的指令，把请将其当作活动工作的一部分。编辑前先读本地指南，并让你的贡献保持在仓库约定之内。 |
| 368 | |
| 369 | 下一步：见 [SKILLS.md](SKILLS.md) 了解管理器、所有权和来源规则；[CLAUDE_PLUGIN_COMPAT.md](../CLAUDE_PLUGIN_COMPAT.md) 了解 Claude Code 技能/插件兼容性；[CONFIGURATION.md](CONFIGURATION.md) 了解配置路径与项目权威。 |
| 370 | |
| 371 | ## 10. 获取帮助 |
| 372 | |
| 373 | 从 doctor 输出开始： |
| 374 | |
| 375 | ```bash |
| 376 | codewhale doctor |
| 377 | ``` |
| 378 | |
| 379 | 提交详细 issue 时用 JSON： |
| 380 | |
| 381 | ```bash |
| 382 | codewhale doctor --json |
| 383 | ``` |
| 384 | |
| 385 | 对于认证问题，用结构化的来源状态确认声明了什么。Doctor 刻意不检查环境、secret-store、钥匙串或 OAuth token 的值。当实时检查合适时，用 `codewhale doctor --probe-api` 选择加入（本地端点用 `--probe-local`）。 |
| 386 | |
| 387 | 对于提供商问题，确认活动的提供商和模型： |
| 388 | |
| 389 | ```text |
| 390 | /provider |
| 391 | /model |
| 392 | ``` |
| 393 | |
| 394 | 会话又长又乱时，用 `/compact` 减轻上下文压力，或在同一工作区开一个新会话并总结你需要的东西。 |
| 395 | |
| 396 | 报告 issue 时，请包含： |
| 397 | |
| 398 | - Codewhale 版本。 |
| 399 | - 安装方式。 |
| 400 | - 操作系统和终端。 |
| 401 | - 提供商和模型。 |
| 402 | - 确切的命令或提示。 |
| 403 | - 相关的 doctor 输出。 |
| 404 | - 问题是否在新工作区里也出现。 |
| 405 | |
| 406 | 不要把 API key、私有源码或密钥粘贴进公开 issue。 |
| 407 | |
| 408 | 下一步：[OPERATIONS_RUNBOOK.md](../OPERATIONS_RUNBOOK.md) 有运维分诊与恢复步骤。 |
| 409 | |
| 410 | ## 常见问题（FAQ） |
| 411 | |
| 412 | ### Codewhale 只支持 DeepSeek 吗？ |
| 413 | |
| 414 | DeepSeek 是默认且一等的路由，但 Codewhale 也支持其他托管和本地的 OpenAI 兼容供应商。用 `/provider` 或 `codewhale --provider <id>` 选择供应商。配置非默认路由时，请打开提供商注册表参考。 |
| 415 | |
| 416 | ### 我应该先用哪个模式？ |
| 417 | |
| 418 | 陌生代码用 Plan，常规实现用 Act，只有在你信任、可以接受自动执行的仓库里才用 Full Access。 |
| 419 | |
| 420 | ### 为什么 Codewhale 运行命令前要问我？ |
| 421 | |
| 422 | 审批是安全模型的一部分。Shell 命令、付费工具、写入以及预期工作区之外的动作都可能产生副作用。审批提示让你在让模型做有用工作的同时保持控制。 |
| 423 | |
| 424 | ### 我如何在 macOS 上运行一个 Python 文件？ |
| 425 | |
| 426 | 在包含该文件的文件夹里打开终端并运行： |
| 427 | |
| 428 | ```bash |
| 429 | python3 your_file.py |
| 430 | ``` |
| 431 | |
| 432 | 如果 macOS 提示 `python3` 缺失，从 [python.org](https://www.python.org/downloads/macos/) 或 Homebrew 安装 Python： |
| 433 | |
| 434 | ```bash |
| 435 | brew install python |
| 436 | ``` |
| 437 | |
| 438 | 在 Codewhale 里，让智能体检查文件并用 `python3 your_file.py` 运行它。如果脚本需要包，先在虚拟环境里安装： |
| 439 | |
| 440 | ```bash |
| 441 | python3 -m venv .venv |
| 442 | source .venv/bin/activate |
| 443 | python3 -m pip install -r requirements.txt |
| 444 | python3 your_file.py |
| 445 | ``` |
| 446 | |
| 447 | ### 我的配置存放在哪里？ |
| 448 | |
| 449 | 新的 Codewhale 配置使用 `~/.codewhale/config.toml`。旧的 `~/.deepseek/config.toml` 为兼容性仍然受支持。当工作区配置存在时，项目覆盖也可能影响行为。 |
| 450 | |
| 451 | ### 如何让成本可预测？ |
| 452 | |
| 453 | 用 `/model auto` 做路由，需要严格配置时选择固定模型，并压缩长会话。对更大的任务，让 Codewhale 先规划再实现，这样你就不会把 token 花在错误的路线上。 |
| 454 | |
| 455 | ### 如何继续之前的工作？ |
| 456 | |
| 457 | Codewhale 会保存会话。用 README 和模式指南里讲到的会话选择器或 resume/continue CLI 路径。对于有风险的实验，在改变方向前先分叉（fork）会话。 |
| 458 | |
| 459 | `/sessions` 选择器以当前工作区为范围启动，这样恢复会保持挂在打开的项目上。在选择器里按 `a` 显示所有工作区的会话，或在恢复某个特定 id 之前运行 `codewhale sessions` 列出所有已保存会话及其最后更新时间。 |
| 460 | |
| 461 | 要从网页应用继续当前正在运行的会话，输入 `/rc` 或用 `codewhale rc` 启动。在系统浏览器里批准一次性代码。租赁期生效期间，浏览器拥有新的提示和审批，终端是可读的安全面。连接后，横幅和一条转录备注会显示实时会话链接（`https://app.codewhale.net/session?run=…`）；`/rc open` 在浏览器里打开它，`/rc link` 打印它。`/rc status` 显示归属，`/rc stop` 把它交回终端，interrupt 仍然可用。断开的连接会保持本地输入锁定，直到最后一个网页租赁过期，这样两个控制器永远不会竞争。从一个终端登记的每个文件夹共享同一个稳定的设备 id，因此网页应用每台机器列出一台电脑，而不是每个会话一台。 |
| 462 | |
| 463 | > 注（2026-09-14）：根据 2026-09-14 的产品客户端决定，app.codewhale.net 的托管网页应用将分阶段下线；原生 GPUI 桌面应用（私有 codehwhale-gpui 仓库，阶段规划见 docs/TRANSITION.md）是承接界面。网页应用存续期间 `/rc` 继续可用。 |
| 464 | |
| 465 | ### 模型糊涂了，我该怎么办？ |
| 466 | |
| 467 | 停下来，重新陈述目标、约束和当前证据。如果转录很长，用 `/compact`，或带简短交接开一个新会话。如果是运维问题，运行 `codewhale doctor` 并检查报告的配置与提供商状态。 |
| 468 | |
| 469 | ### 项目规则应该放在提示里还是文件里？ |
| 470 | |
| 471 | 持久性的项目规则用仓库文件，回合特定的意图用提示。如果某个工作流跨项目重复出现，考虑把它做成技能。 |
| 472 | |
| 473 | ### Codewhale 能编辑当前仓库之外的文件吗？ |
| 474 | |
| 475 | 这取决于工作区边界、沙箱设置、信任模式和审批策略。做贡献工作时，让指令保持在当前仓库范围内，除非你确实需要别的。 |
| 476 | |
| 477 | ### 学完本指南后我该去哪？ |
| 478 | |
| 479 | 读与你正在改动的东西相关的重点参考。对大多数用户，接下来的页面是安装、配置、提供商、模式、快捷键、工具和子智能体。 |
| 480 | |
| 481 | 下一步：[INSTALL.md](INSTALL.md)、[CONFIGURATION.md](CONFIGURATION.md)、[PROVIDERS.md](PROVIDERS.md)、[MODES.md](MODES.md) 和 [TOOL_SURFACE.md](../TOOL_SURFACE.md)。 |
| 482 | |
| 483 | `/statusline` 可分别切换首 token 等待时间（`ttft`）和平均输出速率（`output_rate`）。Space 预览，Enter 保存，Esc 撤销。旧的 `session_metrics` 配置仍会启用两项读数。 |
| 484 |