| 1 | { |
| 2 | "chrome": { |
| 3 | "navDocs": "文档", |
| 4 | "navStart": "指引", |
| 5 | "navInstall": "安装", |
| 6 | "navFaq": "常见问题", |
| 7 | "navCommunity": "社区", |
| 8 | "navContribute": "贡献", |
| 9 | "navProduct": "产品", |
| 10 | "navModels": "模型", |
| 11 | "navPlugins": "插件", |
| 12 | "skipToContent": "跳转到主要内容", |
| 13 | "navPrimaryAria": "主导航", |
| 14 | "navHomeAria": "Codewhale 首页", |
| 15 | "installCta": "安装 →", |
| 16 | "authSignIn": "登录", |
| 17 | "dateLocale": "zh-CN", |
| 18 | "menuOpen": "打开菜单", |
| 19 | "menuClose": "关闭菜单", |
| 20 | "themeAuto": "自动", |
| 21 | "themeLight": "浅色", |
| 22 | "themeDark": "深色", |
| 23 | "themeAria": "主题：{mode}（点击切换）", |
| 24 | "themeTitle": "主题 · 自动 / 浅色 / 深色", |
| 25 | "footerTagline": "用你选择的模型编辑代码、运行测试并审查变更。", |
| 26 | "footerProduct": "产品", |
| 27 | "footerProject": "项目", |
| 28 | "footerDocs": "文档", |
| 29 | "footerGuide": "新手指引", |
| 30 | "footerInstall": "安装", |
| 31 | "footerModels": "模型", |
| 32 | "footerRuntime": "运行时", |
| 33 | "footerFaq": "常见问题", |
| 34 | "footerIssues": "议题", |
| 35 | "footerContribute": "参与贡献", |
| 36 | "footerLicense": "MIT 许可证", |
| 37 | "footerTerms": "服务条款", |
| 38 | "footerPrivacy": "隐私政策", |
| 39 | "footerChangelog": "更新日志", |
| 40 | "footerCanonicalSource": "官方源码：", |
| 41 | "footerReleases": " · 发布：", |
| 42 | "footerReleasesLink": "GitHub 发布页", |
| 43 | "footerSecurity": "安全", |
| 44 | "switcherLabel": "语言", |
| 45 | "switcherSwitchTo": "切换到 {label}", |
| 46 | "partialBadge": "(部分)" |
| 47 | }, |
| 48 | "home": { |
| 49 | "metaTitle": "Codewhale：适用于任意模型的开源编程智能体", |
| 50 | "metaDescription": "Codewhale 是一个在终端中运行的开源编程智能体。它使用你选择的云端或本地模型，读取项目、编辑文件并运行测试。", |
| 51 | "heroTitle": "适用于任意模型的开源编程智能体", |
| 52 | "heroIntro": "{brand} 在终端中读取你的项目、编辑文件并运行测试。连接云端或本地模型，并决定哪些操作需要你批准。", |
| 53 | "getCodewhale": "安装 Codewhale", |
| 54 | "heroInstallAria": "安装命令", |
| 55 | "exploreProduct": "了解工作方式", |
| 56 | "shotPreview": "终端预览", |
| 57 | "shotBuild": "v{version} 预发布版本", |
| 58 | "screenshotAlt": "Codewhale v{version} 预发布版本：鲸鱼标志、新会话、消息输入区、Ask 权限、Work 模式和模型状态。由隔离终端会话的实际画面渲染。", |
| 59 | "latestRelease": "最新发布 {tag}", |
| 60 | "releaseUnavailable": "发布状态暂不可用", |
| 61 | "currentSource": "源码", |
| 62 | "sourceCandidate": "未发布", |
| 63 | "publishedRelease": "已发布", |
| 64 | "figcaptionSourceCandidate": "未发布", |
| 65 | "chapterTerminal": "你的终端", |
| 66 | "chapterTerminalTitle": "实时查看每一次编辑和命令", |
| 67 | "gainHeading": "交出任务，保留控制权", |
| 68 | "gainLede": "直接说出想要的结果：修复错误、解释某个模块，或自动完成重复任务。先用一个智能体，任务变大时再增加。", |
| 69 | "gain": [ |
| 70 | [ |
| 71 | "修改代码并验证", |
| 72 | "智能体查看你的项目、编辑文件并运行测试。你可以在它工作时查看每一次编辑和命令结果。" |
| 73 | ], |
| 74 | [ |
| 75 | "自动完成重复工作", |
| 76 | "在脚本和 CI 中运行 codewhale exec。使用 Fleet 把大型任务分给多个智能体。" |
| 77 | ], |
| 78 | [ |
| 79 | "掌握执行过程", |
| 80 | "开始前设定权限，回应审批请求，随时停止任务。运行 /receipts 可列出会话中的每个文件、命令和审批。" |
| 81 | ] |
| 82 | ], |
| 83 | "chapterModels": "你的模型", |
| 84 | "modelsHeading": "为每项任务选择模型", |
| 85 | "modelsBody": "为每个会话选择内置提供商、任意 OpenAI 兼容端点或本地模型。你的模型连接与 Codewhale 账户相互独立。", |
| 86 | "modelsFacts": [ |
| 87 | [ |
| 88 | "托管", |
| 89 | "你自己的 API 密钥，用 codewhale auth set --provider <id> 保存" |
| 90 | ], |
| 91 | [ |
| 92 | "网关", |
| 93 | "一个端点接多个模型；提供商仍由你选择" |
| 94 | ], |
| 95 | [ |
| 96 | "本地", |
| 97 | "localhost 上的 vLLM、SGLang 或 Ollama，通常无需密钥" |
| 98 | ] |
| 99 | ], |
| 100 | "modelsLink": "浏览模型与提供商", |
| 101 | "startHeading": "安装、连接模型、运行任务", |
| 102 | "startLede": "在项目文件夹中用三个步骤运行第一项任务。如果工作需要多个智能体，之后再添加 Fleet。", |
| 103 | "startGuideLink": "按照新手指引操作", |
| 104 | "startVocabularyLink": "查名词", |
| 105 | "chapterAvailability": "在哪里运行", |
| 106 | "availabilityHeading": "现在就在终端中使用", |
| 107 | "availabilityLede": "终端、本地浏览器客户端和社区维护的 CodeWhale GUI 现已可用。桌面应用和重建中的托管网页应用正在开发，两者共用同一会话模型。", |
| 108 | "availability": [ |
| 109 | [ |
| 110 | "终端与本地浏览器", |
| 111 | "已发布", |
| 112 | "在 Linux、macOS 或 Windows 上安装，然后运行 codewhale，或运行 codewhale web 打开本地浏览器客户端。也可以用 npm 或 Cargo 安装；Android 上的 Termux 版本为预览版。" |
| 113 | ], |
| 114 | [ |
| 115 | "CodeWhale GUI（VS Code）", |
| 116 | "可用", |
| 117 | "由社区维护的独立项目：在 VS Code 侧边栏中连接同一个 Codewhale Runtime，进行对话、管理线程并查看文件变更。可从 VS Code Marketplace 安装。", |
| 118 | "https://marketplace.visualstudio.com/items?itemName=HengQuWorld.brotherwhale-vscode" |
| 119 | ], |
| 120 | [ |
| 121 | "托管网页应用", |
| 122 | "开发预览", |
| 123 | "正在重建，以与桌面应用保持一致。目前你可以登录，然后在正在运行的终端会话中输入 /rc，在网页上继续该会话；托管任务执行仍在验证中。" |
| 124 | ], |
| 125 | [ |
| 126 | "桌面端", |
| 127 | "开发版本", |
| 128 | "正在成为 Codewhale 主要客户端的原生应用：文件夹、对话和模型连接集中在一个窗口中。暂无公开下载。" |
| 129 | ], |
| 130 | [ |
| 131 | "云端计算机", |
| 132 | "开发中", |
| 133 | "为你运行任务的托管计算机。" |
| 134 | ] |
| 135 | ], |
| 136 | "availabilityNote": "终端、本地浏览器和 GUI 无需 Codewhale 账户。托管网页和桌面端使用账户，但账户不能代替模型连接；使用你自己的密钥产生的用量由提供商计费。", |
| 137 | "accountLink": "创建账户", |
| 138 | "surfacesHeading": "扩展智能体能接触的范围", |
| 139 | "surfaces": [ |
| 140 | [ |
| 141 | "文件与命令", |
| 142 | "在你设定的权限内读取项目、编辑文件、运行测试并查看输出。" |
| 143 | ], |
| 144 | [ |
| 145 | "插件与 MCP", |
| 146 | "连接更多工具和服务。每个插件在你审核并启用之前都保持关闭。" |
| 147 | ], |
| 148 | [ |
| 149 | "Computer Use · 预览", |
| 150 | "让智能体查看并操作其他应用的插件。由你启用它，并授予它请求的系统权限。" |
| 151 | ], |
| 152 | [ |
| 153 | "保存的会话", |
| 154 | "将对话和工具结果保存在一起，可以接着之前的工作继续，无需从头开始。本地浏览器会打开你电脑上的同一个会话。" |
| 155 | ], |
| 156 | [ |
| 157 | "Fleet", |
| 158 | "把任务的各部分分配给使用不同模型和角色的智能体，然后跟踪它们的进度。" |
| 159 | ] |
| 160 | ], |
| 161 | "runtimeLink": "查看全部集成", |
| 162 | "installBandHeading": "在 macOS 或 Linux 上安装", |
| 163 | "copy": "复制", |
| 164 | "copied": "已复制 ✓", |
| 165 | "binaries": "预编译包", |
| 166 | "chinaMirrors": "中国镜像", |
| 167 | "installGuideLink": "阅读安装指南", |
| 168 | "communityHeading": "和我们一起构建 Codewhale", |
| 169 | "communityBody": "在 GitHub 上报告 bug、提出功能建议，或提交你的第一个 pull request。欢迎小而经过测试的修复。", |
| 170 | "communityLinksAria": "社区链接", |
| 171 | "contribute": "提交 pull request" |
| 172 | }, |
| 173 | "docs-guide": { |
| 174 | "metaTitle": "开始第一个任务 · Codewhale 文档", |
| 175 | "metaDescription": "安装 Codewhale，连接模型，然后在你的项目里交给它一项任务。之后如果需要多个模型和角色，再配置 Fleet。", |
| 176 | "bodyClassName": "text-ink-soft leading-[1.9] tracking-wide", |
| 177 | "overviewTitle": "开始第一个任务", |
| 178 | "overviewLead": "从什么都没装到完成第一个任务，只需四步。每一步都链接到详细说明页；配置 Fleet 这一步是可选的。", |
| 179 | "sessionTitle": "看一次真实会话", |
| 180 | "sessionLead": "查看一项任务从首次请求到完成的全过程。", |
| 181 | "nextTitle": "下一步", |
| 182 | "sourceNote": "来源文档：docs/GUIDE.md、docs/INSTALL.md、docs/KEYBINDINGS.md · 修改时同步更新 docs-map.ts。" |
| 183 | }, |
| 184 | "docs-shell": { |
| 185 | "metaTitle": "文档 · Codewhale", |
| 186 | "metaDescription": "安装 Codewhale，连接模型提供商，然后把事情做完：模式与审批、查看改动、工作流、子智能体、MCP 工具、钩子、Runtime API 以及问题排查。", |
| 187 | "portalMark": "Codewhale 文档", |
| 188 | "heroTitle": "用 Codewhale 把事情做完。", |
| 189 | "heroLead": "从你想做的事开始。每一页都会说明你需要准备什么，给出今天就能运行的命令，并指向下一步。", |
| 190 | "installCta": "安装 Codewhale", |
| 191 | "releaseLabel": "版本", |
| 192 | "releasePublished": "最新发布 {tag} · {date}", |
| 193 | "releaseCandidate": "本站文档描述的是尚未发布的 {version} 源码候选版。", |
| 194 | "releaseMatches": "本站文档描述的是已发布的 {tag}。", |
| 195 | "releaseChangelog": "更新日志 →", |
| 196 | "searchLabel": "搜索文档", |
| 197 | "searchPlaceholder": "按任务或主题搜索…（按 / 快速聚焦）", |
| 198 | "searchClear": "清除", |
| 199 | "searchMatches": "{matched} / {total} 条匹配 “{query}”", |
| 200 | "searchNoMatches": "没有条目匹配 “{query}”", |
| 201 | "tasksHeading": "按任务", |
| 202 | "tasksLead": "从你想完成的事情开始。", |
| 203 | "topicsHeading": "按主题", |
| 204 | "webGuideTag": "网页指南", |
| 205 | "sourceDocTag": "源文档", |
| 206 | "sourceDetails": "详情", |
| 207 | "emptyTitle": "没有匹配的条目", |
| 208 | "emptyBody": "换一个关键词试试——中英文都可以搜索——或浏览 GitHub 上的完整文档目录。", |
| 209 | "emptyCta": "GitHub 文档目录 ↗", |
| 210 | "indexNote": "“网页指南”条目在 codewhale.net 上打开；“源文档”条目会打开 GitHub 仓库中的完整参考资料。", |
| 211 | "sidebarHeading": "文档目录", |
| 212 | "sidebarAria": "文档目录", |
| 213 | "breadcrumbAria": "面包屑导航", |
| 214 | "breadcrumbHome": "首页", |
| 215 | "breadcrumbDocs": "文档", |
| 216 | "helpTitle": "这一页还不够？", |
| 217 | "helpLead": "每份指南都对照仓库中的一份文档核实过。如果它写错了或缺了什么，请在维护者能看到的地方告诉我们。", |
| 218 | "helpSource": "来源：{name}", |
| 219 | "helpTroubleshooting": "排查问题", |
| 220 | "helpFaq": "常见问题", |
| 221 | "helpDiscord": "到 Discord 提问 ↗", |
| 222 | "helpIssue": "报告文档问题 ↗", |
| 223 | "nextHeading": "下一步", |
| 224 | "noteLabel": "注意：", |
| 225 | "onThisPage": "本页内容", |
| 226 | "mediaPendingNote": "还没有录像。录好之后会放在这里，附字幕、文字稿和可选的 GIF 下载。", |
| 227 | "mediaPlanLink": "录制计划与验收清单 ↗", |
| 228 | "mediaGifFallback": "GIF 下载回退（无视频环境）", |
| 229 | "mediaTranscript": "文字稿 ↗" |
| 230 | }, |
| 231 | "docs-hooks": { |
| 232 | "metaTitle": "在事件发生时运行命令 · Codewhale 文档", |
| 233 | "metaDescription": "在会话开始、工具调用之前、回合结束或 Codewhale 等你回应时运行你自己的脚本——用来补充上下文、执行规则或接收通知。", |
| 234 | "bodyClassName": "text-ink-soft leading-[1.9] tracking-wide", |
| 235 | "title": "在事件发生时运行命令", |
| 236 | "lede": "钩子会在 Codewhale 会话的特定时刻运行你指定的命令。可以用它拦下危险的命令、给消息补充上下文、记录发生了什么，或者在 Codewhale 等你回应时提醒你。", |
| 237 | "sections": [ |
| 238 | { |
| 239 | "id": "first-hook", |
| 240 | "title": "添加第一个钩子", |
| 241 | "blocks": [ |
| 242 | { |
| 243 | "p": "钩子写在 `~/.codewhale/config.toml` 中。下面这个钩子会在每次会话开始时打印一行文字：" |
| 244 | }, |
| 245 | { |
| 246 | "code": "[hooks]\nenabled = true\n\n[[hooks.hooks]]\nname = \"announce\"\nevent = \"session_start\"\ncommand = \"echo 'Codewhale session started'\"", |
| 247 | "lang": "config.toml" |
| 248 | }, |
| 249 | { |
| 250 | "p": "启动一个会话，运行 `/hooks`，就能看到所有已配置的钩子、钩子总开关是否打开，以及被拒绝加载的条目。`/hooks events` 会列出所有事件名称。" |
| 251 | } |
| 252 | ] |
| 253 | }, |
| 254 | { |
| 255 | "id": "gate", |
| 256 | "title": "在命令执行前拦下它", |
| 257 | "blocks": [ |
| 258 | { |
| 259 | "p": "`tool_call_before` 钩子会在每次工具调用执行之前看到它，并可以放行、拒绝，或强制弹出审批提示。下面这个钩子会拒绝强制推送。保存脚本并赋予可执行权限：" |
| 260 | }, |
| 261 | { |
| 262 | "code": "#!/bin/sh\n# ~/.codewhale/hooks/no-force-push.sh\ncase \"$DEEPSEEK_TOOL_ARGS\" in\n *\"push --force\"*|*\"push -f\"*)\n echo '{\"decision\": \"deny\", \"reason\": \"Force-push is blocked by a hook.\"}' ;;\nesac\nexit 0", |
| 263 | "lang": "no-force-push.sh" |
| 264 | }, |
| 265 | { |
| 266 | "code": "[[hooks.hooks]]\nname = \"no-force-push\"\nevent = \"tool_call_before\"\ncommand = \"~/.codewhale/hooks/no-force-push.sh\"\ncondition = { type = \"tool_name\", name = \"bash\" }", |
| 267 | "lang": "config.toml" |
| 268 | }, |
| 269 | { |
| 270 | "p": "钩子从环境变量中读取这次调用，并在标准输出上用 JSON 作答：`allow`、`deny` 或 `ask`，还可以附带 `reason`、改写后的输入（`updatedInput`）或给模型的补充上下文（`additionalContext`）。退出码 2 一律表示拒绝。多个钩子同时作答时，拒绝优先于询问，询问优先于放行。" |
| 271 | }, |
| 272 | { |
| 273 | "note": "在 Ask 和 Auto-Review 下，`ask` 会强制弹出提示。Full Access 从不显示审批提示，因此在那里 `ask` 不会新增提示。" |
| 274 | } |
| 275 | ] |
| 276 | }, |
| 277 | { |
| 278 | "id": "events", |
| 279 | "title": "选择触发时机", |
| 280 | "blocks": [ |
| 281 | { |
| 282 | "p": "有三个事件能改变接下来发生的事，其余事件只做观察：它们的输出会被忽略，失败也只会产生警告。" |
| 283 | }, |
| 284 | { |
| 285 | "rows": [ |
| 286 | [ |
| 287 | "message_submit", |
| 288 | "在你的消息发给模型之前。可以替换文本，或阻止发送。" |
| 289 | ], |
| 290 | [ |
| 291 | "tool_call_before", |
| 292 | "在每次工具调用之前。可以放行、拒绝、询问、改写输入或补充上下文。" |
| 293 | ], |
| 294 | [ |
| 295 | "shell_env", |
| 296 | "在每条 shell 命令运行之前。可以添加环境变量。" |
| 297 | ], |
| 298 | [ |
| 299 | "session_start / session_end", |
| 300 | "会话打开时，或正常关闭时。" |
| 301 | ], |
| 302 | [ |
| 303 | "turn_end", |
| 304 | "回合结束后，附带状态、耗时和 token 用量。" |
| 305 | ], |
| 306 | [ |
| 307 | "tool_call_after", |
| 308 | "每个工具结果返回之后，有退出码时会附带退出码。" |
| 309 | ], |
| 310 | [ |
| 311 | "waiting_for_user", |
| 312 | "Codewhale 开始等待你的审批、回答或暂停中的目标时。" |
| 313 | ], |
| 314 | [ |
| 315 | "session_idle / session_busy", |
| 316 | "会话闲下来，或重新开始工作时。" |
| 317 | ], |
| 318 | [ |
| 319 | "session_error / on_error", |
| 320 | "回合最终失败时，或发生任何错误、工具失败时。" |
| 321 | ], |
| 322 | [ |
| 323 | "mode_change", |
| 324 | "在 Plan、Work、Operate 之间切换时。" |
| 325 | ], |
| 326 | [ |
| 327 | "subagent_spawn / subagent_complete", |
| 328 | "子智能体启动或结束时。" |
| 329 | ] |
| 330 | ], |
| 331 | "codeTerms": true |
| 332 | }, |
| 333 | { |
| 334 | "p": "`condition` 可以缩小钩子的触发范围：按工具名（支持 `*` 通配）、工具类别、模式或退出码，也可以用 `all` 和 `any` 组合。永远不可能与所属事件匹配的条件，会在加载配置时直接被拒绝——这样你以为已经生效的拦截规则，不会悄无声息地失效。" |
| 335 | } |
| 336 | ] |
| 337 | }, |
| 338 | { |
| 339 | "id": "options", |
| 340 | "title": "设置超时与失败行为", |
| 341 | "blocks": [ |
| 342 | { |
| 343 | "rows": [ |
| 344 | [ |
| 345 | "timeout_secs", |
| 346 | "钩子最长可运行多久。默认 30 秒。" |
| 347 | ], |
| 348 | [ |
| 349 | "continue_on_error", |
| 350 | "`true`（默认）：钩子失败只发出警告。`false`：失败即阻止。" |
| 351 | ], |
| 352 | [ |
| 353 | "background", |
| 354 | "`true` 表示只作为观察者运行，不能阻止或改写。" |
| 355 | ], |
| 356 | [ |
| 357 | "working_dir", |
| 358 | "写在 `[hooks]` 下：钩子的运行目录。默认是会话的工作区。" |
| 359 | ] |
| 360 | ], |
| 361 | "codeTerms": true |
| 362 | }, |
| 363 | { |
| 364 | "note": "`[hooks] default_timeout_secs` 会替换每个钩子自己的 `timeout_secs`，而不只是补上未设置的那些。如果想让各钩子使用各自的超时，请不要设置它。" |
| 365 | } |
| 366 | ] |
| 367 | }, |
| 368 | { |
| 369 | "id": "project", |
| 370 | "title": "使用仓库自带的钩子", |
| 371 | "blocks": [ |
| 372 | { |
| 373 | "p": "仓库可以在 `.codewhale/hooks.toml` 中附带钩子。由于它们会在你的机器上运行命令，只有在你信任该工作区，并且批准了这份文件的确切内容之后，才会加载：" |
| 374 | }, |
| 375 | { |
| 376 | "code": "/hooks review\n/hooks approve <digest>\n/hooks revoke", |
| 377 | "lang": "Codewhale" |
| 378 | }, |
| 379 | { |
| 380 | "p": "`/hooks review` 会显示其中的命令以及文件摘要；批准该摘要后，从下一次会话起启用这份确切的内容。文件有任何改动都需要重新批准。命令调用的脚本也请一并审阅。" |
| 381 | } |
| 382 | ] |
| 383 | }, |
| 384 | { |
| 385 | "id": "headless", |
| 386 | "title": "在脚本和 CI 中使用钩子", |
| 387 | "blocks": [ |
| 388 | { |
| 389 | "p": "钩子在交互式会话中运行。`codewhale exec` 默认不触发任何钩子；加上 `--hooks` 后会触发 `tool_call_before` 和 `shell_env`。由于没有人可以回应，`ask` 会被当作拒绝。" |
| 390 | }, |
| 391 | { |
| 392 | "code": "codewhale exec --auto --hooks \"run the test suite and fix the first failure\"", |
| 393 | "lang": "终端" |
| 394 | } |
| 395 | ] |
| 396 | } |
| 397 | ], |
| 398 | "next": [ |
| 399 | { |
| 400 | "href": "/docs/modes", |
| 401 | "label": "设置模式与审批", |
| 402 | "note": "钩子的决定如何与 Ask、Auto-Review 和 Full Access 共同起作用。" |
| 403 | }, |
| 404 | { |
| 405 | "href": "/docs/mcp", |
| 406 | "label": "用 MCP 连接工具", |
| 407 | "note": "用同样的 `tool_call_before` 钩子管控 MCP 工具。" |
| 408 | }, |
| 409 | { |
| 410 | "href": "/docs/configuration", |
| 411 | "label": "修改设置", |
| 412 | "note": "`config.toml` 在哪里，以及项目可以覆盖哪些设置。" |
| 413 | } |
| 414 | ], |
| 415 | "sourceNote": "来源文档：docs/HOOKS.md（权威）、docs/CONFIGURATION.md · 修改时同步更新 docs-map.ts。" |
| 416 | }, |
| 417 | "docs-troubleshooting": { |
| 418 | "metaTitle": "排查问题 · Codewhale 文档", |
| 419 | "metaDescription": "用一条命令诊断 Codewhale，再逐一解决常见问题：找不到命令、没有回复、密钥被拒、网络错误、回合卡住、会话无法恢复，以及 MCP 服务器问题。", |
| 420 | "bodyClassName": "text-ink-soft leading-[1.9] tracking-wide", |
| 421 | "title": "排查问题", |
| 422 | "lede": "先运行一条诊断命令，再在下面找到你遇到的症状。每条解决办法都写明了你会看到的确切报错。", |
| 423 | "sections": [ |
| 424 | { |
| 425 | "id": "diagnose", |
| 426 | "title": "运行诊断", |
| 427 | "blocks": [ |
| 428 | { |
| 429 | "code": "codewhale --version\ncodewhale doctor\ncodewhale doctor --probe-api # one real test call to your provider\ncodewhale auth status --provider deepseek # which key is in use", |
| 430 | "lang": "终端" |
| 431 | }, |
| 432 | { |
| 433 | "p": "`codewhale doctor --json` 会生成一份不含任何密钥的诊断包，可以直接附到 issue 上。单独运行 `doctor` 不会告诉你当前用的是哪把密钥，即使没有密钥也会正常退出；查密钥请用 `auth status`。" |
| 434 | } |
| 435 | ] |
| 436 | }, |
| 437 | { |
| 438 | "id": "install", |
| 439 | "title": "安装与更新", |
| 440 | "blocks": [ |
| 441 | { |
| 442 | "rows": [ |
| 443 | [ |
| 444 | "`codewhale: command not found`", |
| 445 | "当前终端的 PATH 中没有 `~/.local/bin`。把 `export PATH=\"$HOME/.local/bin:$PATH\"` 加入 shell 配置文件，然后打开一个新终端。" |
| 446 | ], |
| 447 | [ |
| 448 | "`npm error code EACCES`", |
| 449 | "你的 Node 由系统管理。不要用 sudo：用 `npm config set prefix \"$HOME/.npm-global\"` 让 npm 安装到你自己的目录，把其中的 `bin` 加入 PATH，再重新安装。" |
| 450 | ], |
| 451 | [ |
| 452 | "`refusing to replace existing ~/.local/bin/codewhale`", |
| 453 | "那里已经装了另一个版本。运行 `codewhale update`，或者先删除旧的二进制文件。" |
| 454 | ], |
| 455 | [ |
| 456 | "`checksum mismatch`", |
| 457 | "下载的文件损坏或被篡改，因此没有安装任何东西。请重试；如果一再出现，不要使用镜像源。" |
| 458 | ], |
| 459 | [ |
| 460 | "`The package-managed executable was not changed.`", |
| 461 | "你是通过 npm、Cargo 或 Homebrew 安装的，请用对应的工具更新，例如 `npm install -g codewhale`。" |
| 462 | ] |
| 463 | ] |
| 464 | } |
| 465 | ] |
| 466 | }, |
| 467 | { |
| 468 | "id": "model", |
| 469 | "title": "没有回复，或密钥被拒", |
| 470 | "blocks": [ |
| 471 | { |
| 472 | "rows": [ |
| 473 | [ |
| 474 | "消息发出后一直没有回复", |
| 475 | "没有配置密钥，而 v0.10.0 不会提示你。按 F3，选择你的提供商，粘贴密钥。" |
| 476 | ], |
| 477 | [ |
| 478 | "`API key not found`", |
| 479 | "哪里都找不到密钥。用 `codewhale auth set --provider <name>` 保存一把。" |
| 480 | ], |
| 481 | [ |
| 482 | "`Authentication Fails … is invalid`", |
| 483 | "密钥错误或已被吊销。运行 `auth status` 查看用的是哪个来源——已保存的密钥优先于环境变量——然后保存正确的密钥，或运行 `codewhale auth clear --provider <name>`。" |
| 484 | ], |
| 485 | [ |
| 486 | "`Network error: SSE stream request failed …`", |
| 487 | "通常是连不上提供商。用 `curl -sI https://api.deepseek.com` 检查（返回 401 说明能连通）。在代理后面时请导出 `HTTPS_PROXY`；在 Windows 或限制严格的代理环境下，可以试试 `CODEWHALE_FORCE_HTTP1=1`。" |
| 488 | ] |
| 489 | ] |
| 490 | } |
| 491 | ] |
| 492 | }, |
| 493 | { |
| 494 | "id": "turn", |
| 495 | "title": "回合卡住了", |
| 496 | "blocks": [ |
| 497 | { |
| 498 | "list": [ |
| 499 | "按 Esc 取消当前回合。Esc 会先关闭已打开的菜单，所以如果开着菜单，需要再按一次。", |
| 500 | "如果是一条耗时很长的 shell 命令拖住了回合，按 Ctrl-B 把它移到后台。回合会继续进行，`/jobs` 中可以看到这条命令。", |
| 501 | "`/retry` 会重新发送上一次请求。" |
| 502 | ] |
| 503 | }, |
| 504 | { |
| 505 | "p": "需要详细记录时，用 `RUST_LOG=codewhale_tui=debug` 启动 Codewhale（排查连接重试用 `RUST_LOG=codewhale_tui::client=debug`）。日志写在 `~/.codewhale/logs/` 下。" |
| 506 | } |
| 507 | ] |
| 508 | }, |
| 509 | { |
| 510 | "id": "sessions", |
| 511 | "title": "恢复会话", |
| 512 | "blocks": [ |
| 513 | { |
| 514 | "code": "codewhale sessions # list saved sessions\ncodewhale resume <id> # an id or a unique prefix\ncodewhale -c # the latest session in this folder", |
| 515 | "lang": "终端" |
| 516 | }, |
| 517 | { |
| 518 | "p": "在 Codewhale 中按 Ctrl-R 可以打开会话选择器。如果 `codewhale exec --continue` 报出 `No saved sessions found for workspace`，说明之前那次是普通的 `exec` 运行，它不会被保存；想接着运行的任务请使用 `--output-format stream-json`。" |
| 519 | }, |
| 520 | { |
| 521 | "p": "离线时发送的消息会随会话一起保存在队列中，`/queue list` 可以查看。网络恢复后，用 `/queue edit <n>` 打开其中一条，按 Enter 发送。" |
| 522 | } |
| 523 | ] |
| 524 | }, |
| 525 | { |
| 526 | "id": "mcp", |
| 527 | "title": "MCP 工具不见了", |
| 528 | "blocks": [ |
| 529 | { |
| 530 | "list": [ |
| 531 | "修改 `mcp.json` 或服务器凭据后，运行 `/mcp reload`。`/mcp validate` 只会刷新界面上显示的内容。", |
| 532 | "在 shell 中亲自运行一遍服务器命令，确认它能启动。", |
| 533 | "如果配置文件丢失或损坏，`codewhale mcp init --force` 会重新生成一份。" |
| 534 | ] |
| 535 | } |
| 536 | ] |
| 537 | }, |
| 538 | { |
| 539 | "id": "docker", |
| 540 | "title": "在 Docker 中运行", |
| 541 | "blocks": [ |
| 542 | { |
| 543 | "code": "docker volume create codewhale-home\ndocker run --rm -it \\\n -e DEEPSEEK_API_KEY=\"$DEEPSEEK_API_KEY\" \\\n -v codewhale-home:/home/codewhale/.codewhale \\\n -v \"$PWD:/workspace\" -w /workspace \\\n ghcr.io/codewhale-hq/codewhale:latest", |
| 544 | "lang": "终端" |
| 545 | }, |
| 546 | { |
| 547 | "p": "镜像以非 root 用户运行，把你的设置和会话保存在命名卷里。想要可重复的环境，请固定某个发布标签而不是 `latest`；每个项目使用单独的卷；永远不要把密钥打包进镜像。" |
| 548 | } |
| 549 | ] |
| 550 | } |
| 551 | ], |
| 552 | "next": [ |
| 553 | { |
| 554 | "href": "/docs/auth", |
| 555 | "label": "连接模型提供商", |
| 556 | "note": "保存密钥、查看当前使用的是哪一把，或改用本地模型。" |
| 557 | }, |
| 558 | { |
| 559 | "href": "/install", |
| 560 | "label": "安装 Codewhale", |
| 561 | "note": "所有安装方式，以及每一步应有的输出。" |
| 562 | }, |
| 563 | { |
| 564 | "href": "/docs/review", |
| 565 | "label": "查看改动", |
| 566 | "note": "把文件回滚到出问题之前那个回合的快照。" |
| 567 | } |
| 568 | ], |
| 569 | "sourceNote": "来源文档：docs/INSTALL.md §13、docs/OPERATIONS_RUNBOOK.md、docs/DOCKER.md · 修改时同步更新 docs-map.ts。" |
| 570 | }, |
| 571 | "docs-configuration": { |
| 572 | "metaTitle": "修改设置 · Codewhale 文档", |
| 573 | "metaDescription": "找到 Codewhale 的配置文件，在会话或 shell 中修改设置，只对单次运行试用某个设置，并了解仓库可以覆盖哪些设置。", |
| 574 | "bodyClassName": "text-ink-soft leading-[1.9] tracking-wide", |
| 575 | "title": "修改设置", |
| 576 | "lede": "大多数设置无需打开文件就能修改：在会话中用 `/config`，在 shell 中用 `codewhale config`。这一页介绍设置保存在哪里、如何修改，以及仓库能替你改什么、不能改什么。", |
| 577 | "sections": [ |
| 578 | { |
| 579 | "id": "file", |
| 580 | "title": "找到配置文件", |
| 581 | "blocks": [ |
| 582 | { |
| 583 | "p": "你的设置保存在 `~/.codewhale/config.toml`。可以打印确切路径，或直接用编辑器打开：" |
| 584 | }, |
| 585 | { |
| 586 | "code": "codewhale config path\ncodewhale config edit", |
| 587 | "lang": "终端" |
| 588 | }, |
| 589 | { |
| 590 | "p": "想使用别的文件，传入 `--config <path>` 或设置 `CODEWHALE_CONFIG_PATH`；两者同时存在时以命令行参数为准。Codewhale 曾名为 DeepSeek-TUI：如果只有旧的 `~/.deepseek/` 文件夹，仍会读取它，而新设置一律写入 `~/.codewhale/`。" |
| 591 | } |
| 592 | ] |
| 593 | }, |
| 594 | { |
| 595 | "id": "change", |
| 596 | "title": "修改设置", |
| 597 | "blocks": [ |
| 598 | { |
| 599 | "p": "在会话中，`/config` 打开设置编辑器，`/settings` 打开设置界面。`/config audit` 会列出哪些设置可以在本次会话中修改、哪些可以保存、哪些要重启后才生效——手动编辑之前先看一下。" |
| 600 | }, |
| 601 | { |
| 602 | "p": "在 shell 中：" |
| 603 | }, |
| 604 | { |
| 605 | "code": "codewhale config get tools\ncodewhale config set telemetry false\ncodewhale config unset telemetry\ncodewhale config dump # the settings in effect, secrets redacted\ncodewhale config doctor # unknown keys, empty secrets, malformed URLs", |
| 606 | "lang": "终端" |
| 607 | }, |
| 608 | { |
| 609 | "p": "`config set` 只处理它认识的配置项；遇到其他配置项时，它会告诉你应该去编辑哪个 TOML 表，而不会自作主张。" |
| 610 | } |
| 611 | ] |
| 612 | }, |
| 613 | { |
| 614 | "id": "one-run", |
| 615 | "title": "只对一次运行试用设置", |
| 616 | "blocks": [ |
| 617 | { |
| 618 | "p": "`--set KEY=VALUE` 只在这一次启动中修改设置，不保存任何内容。它支持 `provider`、`model`、`verbosity`、`approval_policy`、`sandbox_mode` 和 `telemetry`，可以重复使用。" |
| 619 | }, |
| 620 | { |
| 621 | "code": "codewhale --set model=deepseek-v4-pro --set sandbox_mode=read-only", |
| 622 | "lang": "终端" |
| 623 | } |
| 624 | ] |
| 625 | }, |
| 626 | { |
| 627 | "id": "project", |
| 628 | "title": "与仓库共享设置", |
| 629 | "blocks": [ |
| 630 | { |
| 631 | "p": "仓库可以附带 `.codewhale/config.toml`，为所有在其中工作的人建议一些设置。只有少数配置项会生效，而且安全相关的设置只能更严格：" |
| 632 | }, |
| 633 | { |
| 634 | "rows": [ |
| 635 | [ |
| 636 | "model", |
| 637 | "这个仓库的默认模型。" |
| 638 | ], |
| 639 | [ |
| 640 | "reasoning_effort", |
| 641 | "例如为复杂的代码库设置 `\"high\"`。" |
| 642 | ], |
| 643 | [ |
| 644 | "approval_policy, sandbox_mode", |
| 645 | "只接受比你自己的设置更严格的值。" |
| 646 | ], |
| 647 | [ |
| 648 | "allow_shell", |
| 649 | "`false` 会关闭 shell 命令；`true` 会被忽略。" |
| 650 | ], |
| 651 | [ |
| 652 | "max_subagents", |
| 653 | "减少并行子智能体的数量，范围 1 到 128。" |
| 654 | ], |
| 655 | [ |
| 656 | "notes_path", |
| 657 | "把笔记保存在仓库里。" |
| 658 | ] |
| 659 | ], |
| 660 | "codeTerms": true |
| 661 | }, |
| 662 | { |
| 663 | "p": "密钥、服务端点、提供商选择、MCP 服务器、钩子、技能和额外的说明文件，始终来自你自己的配置，因此克隆下来的仓库无法让 Codewhale 指向它自己的服务器或文件。启动时加上 `--no-project-config`，可以在这一次运行中忽略仓库的配置文件。" |
| 664 | }, |
| 665 | { |
| 666 | "p": "项目说明——智能体在这个仓库里应该如何工作——请写在 `AGENTS.md` 中。运行 `/init` 即可生成一份。" |
| 667 | } |
| 668 | ] |
| 669 | } |
| 670 | ], |
| 671 | "next": [ |
| 672 | { |
| 673 | "href": "/docs/auth", |
| 674 | "label": "连接模型提供商", |
| 675 | "note": "保存密钥，并查看 Codewhale 当前使用的是哪一把。" |
| 676 | }, |
| 677 | { |
| 678 | "href": "/docs/modes", |
| 679 | "label": "设置模式与审批", |
| 680 | "note": "大多数人最先修改的设置。" |
| 681 | }, |
| 682 | { |
| 683 | "href": "/docs/hooks", |
| 684 | "label": "在事件发生时运行命令", |
| 685 | "note": "把你自己的脚本加入 `[hooks]` 表。" |
| 686 | } |
| 687 | ], |
| 688 | "sourceNote": "来源文档：docs/CONFIGURATION.md、docs/LEGACY_PATHS.md · 修改时同步更新 docs-map.ts。" |
| 689 | }, |
| 690 | "docs-fleet": { |
| 691 | "metaTitle": "运行工作流 · Codewhale 文档", |
| 692 | "metaDescription": "在 Fleet 中保存角色和模型，编写可重复的工作流，把它作为可查看、可停止的 Lane 运行，并用持久的智能体批量执行任务。", |
| 693 | "bodyClassName": "text-ink-soft leading-[1.9] tracking-wide", |
| 694 | "title": "运行工作流", |
| 695 | "lede": "大多数多步骤工作，直接提出来就行：在 Operate 模式下，Codewhale 会自己规划步骤，并把彼此独立的步骤并行执行。如果你希望每次都按同一套有序计划来做——分阶段、并行分支、最后汇总——并且每次运行都留有记录，就写一个工作流。", |
| 696 | "sections": [ |
| 697 | { |
| 698 | "id": "fleet", |
| 699 | "title": "在 Fleet 中保存角色", |
| 700 | "blocks": [ |
| 701 | { |
| 702 | "p": "Fleet 是 Codewhale 可以分派工作的角色列表，以及每个角色使用的模型。在会话中配置一次即可：" |
| 703 | }, |
| 704 | { |
| 705 | "code": "/fleet setup\n/fleet\n/fleet saved", |
| 706 | "lang": "Codewhale" |
| 707 | }, |
| 708 | { |
| 709 | "p": "`/fleet setup` 会带你选定一个角色、它使用的模型（或“沿用会话的模型”），以及保存位置：当前项目，或者对所有仓库都生效的个人配置。写入之前你会看到完整的文件内容。`/fleet` 显示当前所选 Fleet 的成员，`/fleet saved` 用于在已命名的 Fleet 之间切换。" |
| 710 | }, |
| 711 | { |
| 712 | "p": "Fleet 只决定由谁来做。一个智能体能读、能写、能运行什么，仍然取决于你的工作区信任、[审批设置](/docs/modes)和沙箱。" |
| 713 | } |
| 714 | ] |
| 715 | }, |
| 716 | { |
| 717 | "id": "write", |
| 718 | "title": "编写工作流", |
| 719 | "blocks": [ |
| 720 | { |
| 721 | "p": "工作流是放在仓库 `workflows/` 文件夹中的一个 JavaScript 文件。它只描述步骤，本身不干活。下面这个例子先并行审查两个部分，再汇总结论。把它保存为 `workflows/docs_readiness.workflow.js`：" |
| 722 | }, |
| 723 | { |
| 724 | "code": "export default workflow({\n \"id\": \"docs-readiness\",\n \"goal\": \"Review the docs and code for gaps, then summarize the next edit\",\n \"nodes\": [\n {\n \"branch\": {\n \"id\": \"parallel-review\",\n \"parallel\": true,\n \"children\": [\n { \"agent\": { \"id\": \"code-review\", \"prompt\": \"Inspect src/ for undocumented behavior.\",\n \"agent_type\": \"review\", \"mode\": \"read_only\", \"file_scope\": [\"src\"] } },\n { \"agent\": { \"id\": \"docs-review\", \"prompt\": \"Inspect docs/ for stale or missing steps.\",\n \"agent_type\": \"review\", \"mode\": \"read_only\", \"file_scope\": [\"docs\"] } }\n ]\n }\n },\n {\n \"reduce\": {\n \"id\": \"summary\",\n \"inputs\": [\"code-review\", \"docs-review\"],\n \"prompt\": \"Combine the findings into the safest next edit.\"\n }\n }\n ]\n});", |
| 725 | "lang": "workflows/docs_readiness.workflow.js" |
| 726 | }, |
| 727 | { |
| 728 | "p": "可用的步骤类型有 `agent`、`branch`、`sequence`、`reduce`、`loop_until`、`cond`、`expand` 和 `teacher_review`。工作流文件本身不能访问文件、shell 或网络，`import`、`fetch`、`eval` 和 `async` 都会被拒绝。真正干活的是它启动的智能体，它们按你平常的权限运行。" |
| 729 | }, |
| 730 | { |
| 731 | "note": "一次运行最多可启动 1,000 个智能体，同时工作的最多 16 个，其余排队等待。循环必须声明 `max_iterations`。" |
| 732 | } |
| 733 | ] |
| 734 | }, |
| 735 | { |
| 736 | "id": "run", |
| 737 | "title": "运行", |
| 738 | "blocks": [ |
| 739 | { |
| 740 | "code": "codewhale workflow run docs-readiness --runtime inline\ncodewhale workflow run docs-readiness --goal \"prepare the 1.2 release\" --verify", |
| 741 | "lang": "终端" |
| 742 | }, |
| 743 | { |
| 744 | "p": "Codewhale 会根据名字找到 `workflows/docs_readiness.workflow.js`，检查后启动。`--runtime inline` 在当前终端中运行；默认的 `tmux` 则在一个独立的 tmux 会话中运行，关闭终端后也会继续。`--verify` 会在成功完成后运行验证关卡，`--fleet <name>` 则使用指定的 Fleet 而不是内置角色。" |
| 745 | }, |
| 746 | { |
| 747 | "p": "如果不想动到当前的工作副本，加上 `--worktree-repo . --branch <name>`：这次运行会拥有自己的 git 工作树和分支。" |
| 748 | }, |
| 749 | { |
| 750 | "p": "在会话中，`/workflow` 用于启动工作流，`/workflows` 用于列出或取消本会话中的运行。" |
| 751 | } |
| 752 | ] |
| 753 | }, |
| 754 | { |
| 755 | "id": "watch", |
| 756 | "title": "查看和停止运行", |
| 757 | "blocks": [ |
| 758 | { |
| 759 | "p": "每次运行都是一个 Lane。Lane 会保存到磁盘上，所以你可以在任何终端里查看：" |
| 760 | }, |
| 761 | { |
| 762 | "code": "codewhale lane list\ncodewhale lane status <lane-id>\ncodewhale lane logs <lane-id>\ncodewhale lane attach <lane-id>\ncodewhale lane interrupt <lane-id>", |
| 763 | "lang": "终端" |
| 764 | }, |
| 765 | { |
| 766 | "p": "`lane list`、`lane status` 和 `lane interrupt` 都支持 `--json`，会输出一份机器可读的回执。在会话中，`/lane` 提供同样的操作，结果也完全一致。" |
| 767 | } |
| 768 | ] |
| 769 | }, |
| 770 | { |
| 771 | "id": "batch", |
| 772 | "title": "批量运行任务", |
| 773 | "blocks": [ |
| 774 | { |
| 775 | "p": "如果你手上是一串彼此独立的任务，而不是一套计划，就把它们写成任务文件，作为一次 Fleet 运行来执行。每个任务写明目标、角色和允许写入的路径。完整的 `tasks.json` 示例见[教程](https://github.com/codewhale-hq/CodeWhale/blob/main/docs/FLEET_WORKFLOW_TUTORIAL.md)。" |
| 776 | }, |
| 777 | { |
| 778 | "code": "codewhale fleet init\ncodewhale fleet run tasks.json --max-workers 4\ncodewhale fleet status\ncodewhale fleet logs <worker-id>\ncodewhale fleet resume <run-id>\ncodewhale fleet stop --all", |
| 779 | "lang": "终端" |
| 780 | }, |
| 781 | { |
| 782 | "p": "`fleet status` 会根据当前工作区的运行记录，统计排队中、运行中、已完成和失败的工作。笔记本休眠或管理进程退出后，`fleet resume` 能接着原来的运行继续，而不会新开一次。如果只想看挂在当前会话上的智能体，用 `/fleet workers`（或 `/subagents`）。" |
| 783 | } |
| 784 | ] |
| 785 | } |
| 786 | ], |
| 787 | "next": [ |
| 788 | { |
| 789 | "href": "/docs/subagents", |
| 790 | "label": "并行运行智能体", |
| 791 | "note": "不写工作流，也能把一个任务中彼此独立的部分交给子智能体。" |
| 792 | }, |
| 793 | { |
| 794 | "href": "/docs/review", |
| 795 | "label": "查看改动", |
| 796 | "note": "检查一次运行产生的 diff，并在推送前做一次审查。" |
| 797 | }, |
| 798 | { |
| 799 | "href": "/docs/vocabulary", |
| 800 | "label": "产品名词", |
| 801 | "note": "用一句话分别说明 Fleet、Workflow、Lane 和 Runtime。" |
| 802 | } |
| 803 | ], |
| 804 | "sourceNote": "来源文档：docs/FLEET.md、docs/FLEET_WORKFLOW_TUTORIAL.md、docs/WORKFLOW_AUTHORING.md · 修改时同步更新 docs-map.ts。" |
| 805 | }, |
| 806 | "docs-mcp": { |
| 807 | "metaTitle": "用 MCP 连接工具 · Codewhale 文档", |
| 808 | "metaDescription": "添加 Model Context Protocol 服务器让 Codewhale 使用更多工具，登录远程服务器，把 Codewhale 本身作为 MCP 服务器运行，并试用代码模式。", |
| 809 | "bodyClassName": "text-ink-soft leading-[1.9] tracking-wide", |
| 810 | "title": "用 MCP 连接工具", |
| 811 | "lede": "MCP 服务器能为 Codewhale 带来更多工具——数据库、问题跟踪系统、浏览器等。你可以添加一个由 Codewhale 替你启动的本地服务器，也可以通过 URL 添加远程服务器。这些工具与内置工具走同一套审批流程。", |
| 812 | "sections": [ |
| 813 | { |
| 814 | "id": "add", |
| 815 | "title": "添加服务器", |
| 816 | "blocks": [ |
| 817 | { |
| 818 | "code": "codewhale mcp add git --command \"uvx\" --arg \"mcp-server-git\"\ncodewhale mcp add docs --url \"https://example.com/mcp\"\ncodewhale mcp list\ncodewhale mcp validate", |
| 819 | "lang": "终端" |
| 820 | }, |
| 821 | { |
| 822 | "p": "`--command` 通过 stdio 启动本地服务器，每个参数用一个 `--arg`。`--url` 通过 Streamable HTTP 连接远程服务器，必要时回退到旧版 SSE。`mcp validate` 会检查配置文件以及你标记为必需的服务器。" |
| 823 | }, |
| 824 | { |
| 825 | "p": "在会话中，`/mcp` 会打开 MCP 管理器：显示每个服务器的状态、传输方式、超时设置、错误信息和已发现的工具。同样的操作在那里也能完成，例如 `/mcp add stdio <name> <command>` 和 `/mcp add http <name> <url>`。" |
| 826 | }, |
| 827 | { |
| 828 | "note": "MCP 服务器以你的权限运行。只添加你信任的服务器，就像只安装你信任的程序一样。" |
| 829 | } |
| 830 | ] |
| 831 | }, |
| 832 | { |
| 833 | "id": "remote-auth", |
| 834 | "title": "登录远程服务器", |
| 835 | "blocks": [ |
| 836 | { |
| 837 | "p": "使用 OAuth 的服务器，先用 URL 添加再登录。使用 bearer token 的服务器，把令牌放在环境变量里，而不是写进配置文件：" |
| 838 | }, |
| 839 | { |
| 840 | "code": "codewhale mcp login docs\ncodewhale mcp add tracker --url \"https://example.com/mcp\" --bearer-token-env-var TRACKER_TOKEN", |
| 841 | "lang": "终端" |
| 842 | }, |
| 843 | { |
| 844 | "p": "显式设置的 Authorization 请求头始终优先：先应用配置中的请求头，其次是 bearer token 环境变量，最后才是已保存的 OAuth 登录。`codewhale mcp logout <name>` 会删除本机保存的登录信息；提供商那边的授权可能仍然有效，需要到提供商处撤销。" |
| 845 | } |
| 846 | ] |
| 847 | }, |
| 848 | { |
| 849 | "id": "config", |
| 850 | "title": "编辑配置文件", |
| 851 | "blocks": [ |
| 852 | { |
| 853 | "p": "服务器配置保存在 `~/.codewhale/mcp.json`，`codewhale mcp init` 会生成一个初始文件。其他客户端使用的 `mcpServers` 键同样可用，现成的配置可以直接粘贴进来。" |
| 854 | }, |
| 855 | { |
| 856 | "code": "{\n \"servers\": {\n \"example\": {\n \"command\": \"node\",\n \"args\": [\"./path/to/your-mcp-server.js\"],\n \"env\": {},\n \"disabled\": false\n }\n }\n}", |
| 857 | "lang": "mcp.json" |
| 858 | }, |
| 859 | { |
| 860 | "p": "修改文件后，在会话中运行 `/mcp reload` 即可，无需重启。服务器只在某个回合需要它的工具时才启动；如果希望它在启动时就连接，把它标记为 `\"required\": true`。" |
| 861 | } |
| 862 | ] |
| 863 | }, |
| 864 | { |
| 865 | "id": "tool-names", |
| 866 | "title": "找到这些工具", |
| 867 | "blocks": [ |
| 868 | { |
| 869 | "p": "每个工具在模型眼中的名字是 `mcp_<server>_<tool>`：名为 `git` 的服务器提供的 `status` 工具，就叫 `mcp_git_status`。`codewhale mcp tools <server>` 会列出某个服务器提供的工具。连接失败或已禁用的服务器，其工具永远不会显示为可用。" |
| 870 | }, |
| 871 | { |
| 872 | "p": "MCP 工具遵循你的[审批设置](/docs/modes)：在策略允许时，列出和读取服务器的资源与提示词无需确认；有副作用的工具会先征求你的同意。Full Access 也不会绕过仓库规则或托管策略。" |
| 873 | } |
| 874 | ] |
| 875 | }, |
| 876 | { |
| 877 | "id": "serve", |
| 878 | "title": "把 Codewhale 作为 MCP 服务器运行", |
| 879 | "blocks": [ |
| 880 | { |
| 881 | "p": "其他 MCP 客户端——包括另一个 Codewhale 会话——都可以使用 Codewhale 的工具。只需注册一次：" |
| 882 | }, |
| 883 | { |
| 884 | "code": "codewhale mcp add-self\ncodewhale mcp tools codewhale", |
| 885 | "lang": "终端" |
| 886 | }, |
| 887 | { |
| 888 | "p": "`add-self` 会写入一条通过 stdio 运行 `codewhale serve --mcp` 的配置。每个客户端各自启动一个进程，不会打开任何网络端口。`codewhale serve --http` 则是另一回事——它是供应用使用的 [Runtime API](/docs/runtime-api)。" |
| 889 | } |
| 890 | ] |
| 891 | }, |
| 892 | { |
| 893 | "id": "code-mode", |
| 894 | "title": "用代码模式组合工具调用（实验性）", |
| 895 | "blocks": [ |
| 896 | { |
| 897 | "p": "代码模式让模型写一段简短的 JavaScript 程序，在其中调用多个工具、循环和筛选结果，而不必把每次调用都作为单独的一步。只有程序的最终结果会返回给模型，长时间的查找因此更紧凑。它默认关闭。可以只在一次会话中试用，也可以在配置中开启：" |
| 898 | }, |
| 899 | { |
| 900 | "code": "codewhale --enable code_mode\n\n# ~/.codewhale/config.toml\n[features]\ncode_mode = true", |
| 901 | "lang": "终端 / config.toml" |
| 902 | }, |
| 903 | { |
| 904 | "list": [ |
| 905 | "程序中只能调用无需审批的只读工具。任何写入、运行 shell 命令或需要征求你同意的调用，都会让程序停止，并报告被拒绝的是哪一次调用。", |
| 906 | "程序中暂时还不能调用 MCP 工具，请把它们作为普通工具调用来使用。", |
| 907 | "每个程序的上限：50 次工具调用、同时最多 4 次、30 秒、返回 16 KiB。", |
| 908 | "Plan 模式下不能使用代码模式。" |
| 909 | ] |
| 910 | } |
| 911 | ] |
| 912 | } |
| 913 | ], |
| 914 | "next": [ |
| 915 | { |
| 916 | "href": "/docs/hooks", |
| 917 | "label": "在事件发生时运行命令", |
| 918 | "note": "在工具调用执行前检查或改写它，MCP 工具也不例外。" |
| 919 | }, |
| 920 | { |
| 921 | "href": "/docs/modes", |
| 922 | "label": "设置模式与审批", |
| 923 | "note": "决定哪些 MCP 调用需要你批准。" |
| 924 | }, |
| 925 | { |
| 926 | "href": "/docs/runtime-api", |
| 927 | "label": "用 Runtime API 自动化", |
| 928 | "note": "通过 HTTP 从你自己的应用或脚本驱动 Codewhale。" |
| 929 | } |
| 930 | ], |
| 931 | "sourceNote": "来源文档：docs/MCP.md、crates/tui/src/tools/codemode.rs · 修改时同步更新 docs-map.ts。" |
| 932 | }, |
| 933 | "docs-modes": { |
| 934 | "metaTitle": "设置模式与审批 · Codewhale 文档", |
| 935 | "metaDescription": "用 Plan、Work、Operate 选择工作类型，用 Ask、Auto-Review、Full Access 决定 Codewhale 多久停下来问你一次。", |
| 936 | "bodyClassName": "text-ink-soft leading-[1.9] tracking-wide", |
| 937 | "title": "设置模式与审批", |
| 938 | "lede": "有两个相互独立的开关决定 Codewhale 能自己做什么。模式决定工作类型——只看、动手改，还是统筹协调；审批设置决定它什么时候停下来问你。两者都可以在回合之间随时用键盘切换。", |
| 939 | "sections": [ |
| 940 | { |
| 941 | "id": "modes", |
| 942 | "title": "选择模式", |
| 943 | "blocks": [ |
| 944 | { |
| 945 | "rows": [ |
| 946 | [ |
| 947 | "Plan", |
| 948 | "只看、只规划。Codewhale 可以阅读工作区、查资料，但不能修改文件，也不能运行 shell 命令。适合先弄懂代码库，或先商定做法。" |
| 949 | ], |
| 950 | [ |
| 951 | "Work", |
| 952 | "日常编码。Codewhale 会阅读、修改文件并运行命令，范围受你选择的审批设置约束。这是默认模式。" |
| 953 | ], |
| 954 | [ |
| 955 | "Operate", |
| 956 | "面向更大的目标。权限与 Work 相同，但 Codewhale 会先拆出有名字的步骤，把彼此独立的步骤并行交给子智能体，并在汇报完成之前逐一核对结果。" |
| 957 | ] |
| 958 | ] |
| 959 | }, |
| 960 | { |
| 961 | "p": "输入框为空时按 Tab，可以按 Plan → Work → Operate 的顺序切换；也可以输入 `/mode` 打开选择器，或者直接切换：" |
| 962 | }, |
| 963 | { |
| 964 | "code": "/mode plan\n/mode work\n/mode operate", |
| 965 | "lang": "Codewhale" |
| 966 | }, |
| 967 | { |
| 968 | "p": "你选中的模式也会成为下次启动会话时的模式。回合进行中 Codewhale 不接受切换模式，请先按 Esc 停止当前回合。" |
| 969 | } |
| 970 | ] |
| 971 | }, |
| 972 | { |
| 973 | "id": "approvals", |
| 974 | "title": "决定它什么时候问你", |
| 975 | "blocks": [ |
| 976 | { |
| 977 | "p": "按 Shift+Tab 可以按 Ask → Auto-Review → Full Access 的顺序切换。无论这里选什么，Plan 模式始终是只读的。" |
| 978 | }, |
| 979 | { |
| 980 | "rows": [ |
| 981 | [ |
| 982 | "Ask", |
| 983 | "默认设置。工作区内的文件修改会直接写入，并以 diff 的形式展示给你；shell 命令和其他有实际影响的工具会停下来等你批准。" |
| 984 | ], |
| 985 | [ |
| 986 | "Auto-Review", |
| 987 | "从不停下来问你。能确证安全的调用直接执行；发布类操作和破坏性的后台操作一律拦截；其余调用交给一次独立的模型审查。高风险调用和审查失败的调用会被拒绝，而不是执行。" |
| 988 | ], |
| 989 | [ |
| 990 | "Full Access", |
| 991 | "不弹出审批提示。仓库规则和托管策略该拦的照样会拦。只在你信任的工作区里使用。" |
| 992 | ] |
| 993 | ] |
| 994 | }, |
| 995 | { |
| 996 | "note": "Ask 模式下，工作区内的文件修改不会事先询问。开始之前请先提交或暂存重要的改动，并通过[查看改动](/docs/review)检查或回滚修改。" |
| 997 | } |
| 998 | ] |
| 999 | }, |
| 1000 | { |
| 1001 | "id": "prompt", |
| 1002 | "title": "回应审批提示", |
| 1003 | "blocks": [ |
| 1004 | { |
| 1005 | "p": "Codewhale 停在审批提示时，会显示将要执行的完整命令。按一个键作答：" |
| 1006 | }, |
| 1007 | { |
| 1008 | "rows": [ |
| 1009 | [ |
| 1010 | "y", |
| 1011 | "只允许这一次调用。" |
| 1012 | ], |
| 1013 | [ |
| 1014 | "a", |
| 1015 | "在本次会话剩余时间内都允许。" |
| 1016 | ], |
| 1017 | [ |
| 1018 | "n", |
| 1019 | "拒绝。Codewhale 会得知这次调用被拒绝了。" |
| 1020 | ], |
| 1021 | [ |
| 1022 | "Esc", |
| 1023 | "停止整个回合。" |
| 1024 | ] |
| 1025 | ], |
| 1026 | "codeTerms": true |
| 1027 | }, |
| 1028 | { |
| 1029 | "p": "新提示默认选中的是“拒绝”，所以没看清就按 Enter 会拒绝这次调用。如果想改变这一点，或者让等待过久的提示自动拒绝，可以在 `~/.codewhale/config.toml` 中设置：" |
| 1030 | }, |
| 1031 | { |
| 1032 | "code": "[approval]\ndefault_selection = \"allow_once\" # default: \"deny\"\ntimeout_seconds = 300 # default: wait indefinitely", |
| 1033 | "lang": "config.toml" |
| 1034 | } |
| 1035 | ] |
| 1036 | } |
| 1037 | ], |
| 1038 | "next": [ |
| 1039 | { |
| 1040 | "href": "/docs/review", |
| 1041 | "label": "查看改动", |
| 1042 | "note": "查看本次会话的 diff，把文件回滚到之前某个回合。" |
| 1043 | }, |
| 1044 | { |
| 1045 | "href": "/docs/sandbox", |
| 1046 | "label": "限制命令的访问范围", |
| 1047 | "note": "批准不等于沙箱。了解各平台上操作系统实际限制了什么。" |
| 1048 | }, |
| 1049 | { |
| 1050 | "href": "/docs/subagents", |
| 1051 | "label": "并行运行智能体", |
| 1052 | "note": "Operate 如何处理彼此独立的步骤，以及怎样查看进度。" |
| 1053 | } |
| 1054 | ], |
| 1055 | "sourceNote": "来源文档：docs/MODES.md、docs/INSTALL.md §10、docs/CONFIGURATION.md · 修改时同步更新 docs-map.ts。" |
| 1056 | }, |
| 1057 | "docs-runtime-api": { |
| 1058 | "metaTitle": "用 Runtime API 自动化 · Codewhale 文档", |
| 1059 | "metaDescription": "用你自己的脚本和应用驱动 Codewhale：在 CI 中运行一次性任务，或启动本地 HTTP API 来发送回合、接收事件流并回应审批。", |
| 1060 | "bodyClassName": "text-ink-soft leading-[1.9] tracking-wide", |
| 1061 | "title": "用 Runtime API 自动化", |
| 1062 | "lede": "脚本和应用可以驱动你在终端里使用的同一个引擎。单个任务用 `codewhale exec`；需要会话线程、实时事件和审批的应用，则运行本地的 Runtime API。一切都在你的机器上运行，没有托管中转。", |
| 1063 | "sections": [ |
| 1064 | { |
| 1065 | "id": "exec", |
| 1066 | "title": "在脚本中运行单个任务", |
| 1067 | "blocks": [ |
| 1068 | { |
| 1069 | "code": "codewhale exec \"Reply with exactly: pong\"\ncodewhale exec --auto \"fix the failing test and run it again\"\ncodewhale exec --auto --output-format stream-json \"update the changelog\"", |
| 1070 | "lang": "终端" |
| 1071 | }, |
| 1072 | { |
| 1073 | "p": "普通的 `exec` 只回答一次，不使用工具。`--auto` 允许它使用工具并自动批准，所以只在你信任的仓库或容器中使用；它绝不会放宽[沙箱](/docs/sandbox)。`--output-format stream-json` 每行输出一个 JSON 事件，并保存会话，以便之后用 `--continue` 接着运行。`--max-turns` 和 `--allowed-tools` 可以为一次运行设定限制。" |
| 1074 | } |
| 1075 | ] |
| 1076 | }, |
| 1077 | { |
| 1078 | "id": "start", |
| 1079 | "title": "启动 Runtime API", |
| 1080 | "blocks": [ |
| 1081 | { |
| 1082 | "code": "export CODEWHALE_RUNTIME_TOKEN=\"$(openssl rand -hex 32)\"\ncodewhale app-server --http # http://127.0.0.1:7878", |
| 1083 | "lang": "终端" |
| 1084 | }, |
| 1085 | { |
| 1086 | "p": "请在启动前自己设置令牌；如果不设置，Codewhale 会为该进程生成一个令牌，但不会打印出来。每个 `/v1/*` 请求都必须以 `Authorization: Bearer <token>` 的形式携带它。`--port` 可以更改端口。" |
| 1087 | } |
| 1088 | ] |
| 1089 | }, |
| 1090 | { |
| 1091 | "id": "turn", |
| 1092 | "title": "发送一个回合并观察它", |
| 1093 | "blocks": [ |
| 1094 | { |
| 1095 | "code": "API=http://127.0.0.1:7878\nAUTH=\"Authorization: Bearer $CODEWHALE_RUNTIME_TOKEN\"\n\nTHREAD=$(curl -s -X POST \"$API/v1/threads\" -H \"$AUTH\" \\\n -H \"Content-Type: application/json\" -d '{}' | jq -r .id)\n\ncurl -s -X POST \"$API/v1/threads/$THREAD/turns\" -H \"$AUTH\" \\\n -H \"Content-Type: application/json\" -d '{\"prompt\": \"Summarize README.md\"}'\n\ncurl -N \"$API/v1/threads/$THREAD/events?since_seq=0\" -H \"$AUTH\"", |
| 1096 | "lang": "终端" |
| 1097 | }, |
| 1098 | { |
| 1099 | "p": "线程就是一段对话；回合是一次请求，以及 Codewhale 为它所做的一切。事件流会从你给出的序号开始回放，然后保持连接等待新事件，因此重新连接的客户端不会漏掉任何内容。" |
| 1100 | }, |
| 1101 | { |
| 1102 | "rows": [ |
| 1103 | [ |
| 1104 | "停止回合", |
| 1105 | "`POST /v1/threads/{id}/turns/{turn_id}/interrupt`" |
| 1106 | ], |
| 1107 | [ |
| 1108 | "回应审批", |
| 1109 | "`POST /v1/approvals/{approval_id}`" |
| 1110 | ], |
| 1111 | [ |
| 1112 | "引导正在运行的回合", |
| 1113 | "`POST /v1/threads/{id}/turns/{turn_id}/steer`" |
| 1114 | ], |
| 1115 | [ |
| 1116 | "列出已保存的会话", |
| 1117 | "`GET /v1/sessions`" |
| 1118 | ] |
| 1119 | ] |
| 1120 | }, |
| 1121 | { |
| 1122 | "p": "[docs/RUNTIME_API.md](https://github.com/codewhale-hq/CodeWhale/blob/main/docs/RUNTIME_API.md) 列出了所有路由、请求体和事件。" |
| 1123 | } |
| 1124 | ] |
| 1125 | }, |
| 1126 | { |
| 1127 | "id": "other", |
| 1128 | "title": "选择其他连接方式", |
| 1129 | "blocks": [ |
| 1130 | { |
| 1131 | "rows": [ |
| 1132 | [ |
| 1133 | "codewhale app-server --stdio", |
| 1134 | "通过标准输入输出传输 JSON-RPC，不监听网络。适合 SDK 或本地探测。" |
| 1135 | ], |
| 1136 | [ |
| 1137 | "codewhale serve --acp", |
| 1138 | "面向 Zed 等编辑器的 Agent Client Protocol。" |
| 1139 | ], |
| 1140 | [ |
| 1141 | "codewhale serve --mcp", |
| 1142 | "把 Codewhale 的工具提供给其他 MCP 客户端。见[用 MCP 连接工具](/docs/mcp)。" |
| 1143 | ], |
| 1144 | [ |
| 1145 | "codewhale web", |
| 1146 | "内置的[浏览器客户端](/docs/web)，基于同一个 API。" |
| 1147 | ], |
| 1148 | [ |
| 1149 | "codewhale doctor --json", |
| 1150 | "以 JSON 输出健康状况和能力信息，不含任何密钥。" |
| 1151 | ] |
| 1152 | ], |
| 1153 | "codeTerms": true |
| 1154 | } |
| 1155 | ] |
| 1156 | }, |
| 1157 | { |
| 1158 | "id": "security", |
| 1159 | "title": "保持私密", |
| 1160 | "blocks": [ |
| 1161 | { |
| 1162 | "list": [ |
| 1163 | "服务默认只监听 `127.0.0.1`。令牌只是本地防护，不能替代 TLS 或 VPN；不要把端口暴露到网络上。", |
| 1164 | "`--insecure-no-auth` 只在回环地址上被接受。", |
| 1165 | "API 从不返回你的提供商密钥。健康和能力报告只包含元数据——没有密钥、文件内容或消息。" |
| 1166 | ] |
| 1167 | } |
| 1168 | ] |
| 1169 | } |
| 1170 | ], |
| 1171 | "next": [ |
| 1172 | { |
| 1173 | "href": "/docs/web", |
| 1174 | "label": "打开浏览器客户端", |
| 1175 | "note": "基于同一个 API 的现成客户端。" |
| 1176 | }, |
| 1177 | { |
| 1178 | "href": "/docs/hooks", |
| 1179 | "label": "在事件发生时运行命令", |
| 1180 | "note": "不写客户端，也能响应会话事件。" |
| 1181 | }, |
| 1182 | { |
| 1183 | "href": "/docs/fleet", |
| 1184 | "label": "运行工作流", |
| 1185 | "note": "可在任何终端查看的持久多步骤运行。" |
| 1186 | } |
| 1187 | ], |
| 1188 | "sourceNote": "来源文档：docs/RUNTIME_API.md · 修改时同步更新 docs-map.ts。" |
| 1189 | }, |
| 1190 | "docs-sandbox": { |
| 1191 | "metaTitle": "限制命令的访问范围 · Codewhale 文档", |
| 1192 | "metaDescription": "了解 macOS、Linux 和 Windows 上用哪种操作系统沙箱包裹 shell 命令，在可选的平台上开启它，并决定命令能写到哪里。", |
| 1193 | "bodyClassName": "text-ink-soft leading-[1.9] tracking-wide", |
| 1194 | "title": "限制命令的访问范围", |
| 1195 | "lede": "批准一条命令，决定的是它能不能运行；沙箱决定的是它运行之后能碰到什么。只要操作系统提供沙箱，Codewhale 就会使用它；没有沙箱时，也会如实告诉你。", |
| 1196 | "sections": [ |
| 1197 | { |
| 1198 | "id": "platforms", |
| 1199 | "title": "查看你的平台提供了什么", |
| 1200 | "blocks": [ |
| 1201 | { |
| 1202 | "rows": [ |
| 1203 | [ |
| 1204 | "macOS", |
| 1205 | "Seatbelt，启动检查通过后自动启用。命令可以广泛读取，写入范围由沙箱模式限定，只有模式允许时才能联网。" |
| 1206 | ], |
| 1207 | [ |
| 1208 | "Linux", |
| 1209 | "bubblewrap，但需要你手动开启（见下文）。不开启时，命令在没有操作系统沙箱的情况下运行。" |
| 1210 | ], |
| 1211 | [ |
| 1212 | "Windows", |
| 1213 | "目前没有操作系统沙箱。你的审批设置和 Windows 自身的权限仍然有效。" |
| 1214 | ], |
| 1215 | [ |
| 1216 | "外部服务", |
| 1217 | "设置 `sandbox_backend = \"opensandbox\"` 后，shell 命令会在你配置的 OpenSandbox 兼容服务上运行；隔离效果由该服务负责保证。" |
| 1218 | ] |
| 1219 | ] |
| 1220 | }, |
| 1221 | { |
| 1222 | "p": "问问 Codewhale 它找到了哪一种：" |
| 1223 | }, |
| 1224 | { |
| 1225 | "code": "codewhale doctor\ncodewhale setup --status", |
| 1226 | "lang": "终端" |
| 1227 | }, |
| 1228 | { |
| 1229 | "p": "两条命令报告的都是应用你的设置之后实际可用的沙箱。仓库里存在但没有接入执行路径的代码，Codewhale 从不把它算作沙箱。" |
| 1230 | } |
| 1231 | ] |
| 1232 | }, |
| 1233 | { |
| 1234 | "id": "linux", |
| 1235 | "title": "开启 Linux 沙箱", |
| 1236 | "blocks": [ |
| 1237 | { |
| 1238 | "p": "先安装 bubblewrap，再在 `~/.codewhale/config.toml` 中加一行来启用：" |
| 1239 | }, |
| 1240 | { |
| 1241 | "code": "sudo apt install bubblewrap # Fedora: dnf install bubblewrap · Arch: pacman -S bubblewrap\n\n# ~/.codewhale/config.toml\nprefer_bwrap = true", |
| 1242 | "lang": "终端 / config.toml" |
| 1243 | }, |
| 1244 | { |
| 1245 | "p": "只有当 `/usr/bin/bwrap` 存在且可执行时，Codewhale 才会使用它。此后，命令看到的是只读的系统视图，只能写入沙箱模式允许的位置，除非模式允许，否则无法联网。" |
| 1246 | } |
| 1247 | ] |
| 1248 | }, |
| 1249 | { |
| 1250 | "id": "mode", |
| 1251 | "title": "决定命令能写到哪里", |
| 1252 | "blocks": [ |
| 1253 | { |
| 1254 | "code": "sandbox_mode = \"workspace-write\"", |
| 1255 | "lang": "config.toml" |
| 1256 | }, |
| 1257 | { |
| 1258 | "rows": [ |
| 1259 | [ |
| 1260 | "read-only", |
| 1261 | "命令只能读，不能写。" |
| 1262 | ], |
| 1263 | [ |
| 1264 | "workspace-write", |
| 1265 | "命令只能写入工作区和临时文件夹，其他地方都不行。" |
| 1266 | ], |
| 1267 | [ |
| 1268 | "danger-full-access", |
| 1269 | "不使用操作系统沙箱。只在你不怕损坏的机器或容器里使用。" |
| 1270 | ], |
| 1271 | [ |
| 1272 | "external-sandbox", |
| 1273 | "你已经运行在隔离环境里，Codewhale 不再额外加一层。" |
| 1274 | ] |
| 1275 | ], |
| 1276 | "codeTerms": true |
| 1277 | }, |
| 1278 | { |
| 1279 | "p": "前两种模式只有在沙箱可用时才会真正生效——在没有 bubblewrap 的 Linux 上，以及在 Windows 上，它们只是设置，背后没有操作系统沙箱。仓库自带的配置只能让模式更严格，不能更宽松。对单次无界面运行，可以给 `codewhale exec` 传 `--sandbox <mode>`；`--auto` 只会自动批准工具，绝不会放宽沙箱。" |
| 1280 | } |
| 1281 | ] |
| 1282 | }, |
| 1283 | { |
| 1284 | "id": "limits", |
| 1285 | "title": "了解局限", |
| 1286 | "blocks": [ |
| 1287 | { |
| 1288 | "list": [ |
| 1289 | "命令启动前会检查沙箱是否可用，但受主机策略或容器限制影响，沙箱仍可能在启动时失败。", |
| 1290 | "命令报出“Permission denied”并不能证明是沙箱拦下了它。只有沙箱自己报告的拒绝，Codewhale 才会标记为沙箱拒绝。", |
| 1291 | "任何沙箱都无法防御内核漏洞，也无法防住所有类型的资源耗尽。" |
| 1292 | ] |
| 1293 | } |
| 1294 | ] |
| 1295 | } |
| 1296 | ], |
| 1297 | "next": [ |
| 1298 | { |
| 1299 | "href": "/docs/modes", |
| 1300 | "label": "设置模式与审批", |
| 1301 | "note": "决定哪些命令需要停下来等你批准。" |
| 1302 | }, |
| 1303 | { |
| 1304 | "href": "/docs/trust", |
| 1305 | "label": "了解哪些数据会离开本机", |
| 1306 | "note": "提供商会收到什么、哪些留在本地，以及遥测会发送什么。" |
| 1307 | }, |
| 1308 | { |
| 1309 | "href": "/docs/configuration", |
| 1310 | "label": "修改设置", |
| 1311 | "note": "这些配置项写在哪里，以及仓库可以覆盖哪些。" |
| 1312 | } |
| 1313 | ], |
| 1314 | "sourceNote": "来源文档：docs/SANDBOX.md、docs/CONFIGURATION.md · 修改时同步更新 docs-map.ts。" |
| 1315 | }, |
| 1316 | "docs-subagents": { |
| 1317 | "metaTitle": "并行运行智能体 · Codewhale 文档", |
| 1318 | "metaDescription": "让 Codewhale 把任务中彼此独立的部分交给子智能体，为它们选择角色，把它们的修改放在各自的工作树里，并随时查看进度。", |
| 1319 | "bodyClassName": "text-ink-soft leading-[1.9] tracking-wide", |
| 1320 | "title": "并行运行智能体", |
| 1321 | "lede": "Codewhale 可以把一块聚焦的工作交给子智能体，自己继续往下做。当一个任务能拆成彼此独立的几部分——梳理代码库、审查改动、跑测试——时，用这种方式让它们同时进行。", |
| 1322 | "sections": [ |
| 1323 | { |
| 1324 | "id": "ask", |
| 1325 | "title": "直接提出来", |
| 1326 | "blocks": [ |
| 1327 | { |
| 1328 | "p": "启动子智能体不需要命令，用平常的话提出来就行。在 Operate 模式下，Codewhale 会自己把独立的步骤分派出去；在 Work 模式下，说清楚你想怎么拆分：" |
| 1329 | }, |
| 1330 | { |
| 1331 | "code": "Use three explore agents in parallel: one maps the auth code,\none maps the billing code, one lists the tests that cover both.\nThen summarize what would break if we changed the session format.", |
| 1332 | "lang": "提示词" |
| 1333 | }, |
| 1334 | { |
| 1335 | "p": "每个子智能体都在后台启动，完成后回报结果。你的输入框始终可用，主回合会接着处理这些结果。" |
| 1336 | } |
| 1337 | ] |
| 1338 | }, |
| 1339 | { |
| 1340 | "id": "roles", |
| 1341 | "title": "选择角色", |
| 1342 | "blocks": [ |
| 1343 | { |
| 1344 | "p": "角色决定了子智能体如何做事。你可以在请求里点名，也可以让 Codewhale 自己选。子智能体拿到的权限永远不会超过你当前会话的权限。" |
| 1345 | }, |
| 1346 | { |
| 1347 | "rows": [ |
| 1348 | [ |
| 1349 | "general", |
| 1350 | "按任务说明做事，可以修改文件、运行命令。默认角色。" |
| 1351 | ], |
| 1352 | [ |
| 1353 | "explore", |
| 1354 | "只读。快速梳理相关代码——比如“找出这个函数的所有调用方”。" |
| 1355 | ], |
| 1356 | [ |
| 1357 | "planner", |
| 1358 | "设计方案，不做任何改动。" |
| 1359 | ], |
| 1360 | [ |
| 1361 | "reviewer", |
| 1362 | "阅读并评估一处改动，为每个发现标注严重程度。" |
| 1363 | ], |
| 1364 | [ |
| 1365 | "implement", |
| 1366 | "用最小的修改落实一项具体改动。" |
| 1367 | ], |
| 1368 | [ |
| 1369 | "test", |
| 1370 | "运行测试和检查，报告通过或失败。不修改代码。" |
| 1371 | ], |
| 1372 | [ |
| 1373 | "advisor", |
| 1374 | "针对需要判断的问题，给出简短而审慎的第二意见。不运行命令。" |
| 1375 | ], |
| 1376 | [ |
| 1377 | "custom", |
| 1378 | "只能使用你列出的工具，适合权限需要严格收紧的任务。" |
| 1379 | ] |
| 1380 | ], |
| 1381 | "codeTerms": true |
| 1382 | }, |
| 1383 | { |
| 1384 | "p": "想让某个角色固定使用某个模型，用 `/fleet setup` 保存——见[运行工作流](/docs/fleet)。" |
| 1385 | } |
| 1386 | ] |
| 1387 | }, |
| 1388 | { |
| 1389 | "id": "worktrees", |
| 1390 | "title": "让并行修改互不干扰", |
| 1391 | "blocks": [ |
| 1392 | { |
| 1393 | "p": "如果两个子智能体会修改同一个仓库，请让它们各自在自己的工作树里工作。Codewhale 会在你的仓库旁边的 `.codewhale-worktrees/` 下，为该智能体创建新的 git 工作树和分支；在你合并之前，你的工作副本保持干净。" |
| 1394 | }, |
| 1395 | { |
| 1396 | "p": "工作树只是隔离，不代表授权：需要写入的智能体仍然要有可写的角色，以及允许修改的路径。两个智能体如果声明要改同一批文件，会在任何一方动手之前就被拦下。" |
| 1397 | } |
| 1398 | ] |
| 1399 | }, |
| 1400 | { |
| 1401 | "id": "watch", |
| 1402 | "title": "查看进度并回应它们", |
| 1403 | "blocks": [ |
| 1404 | { |
| 1405 | "code": "/subagents", |
| 1406 | "lang": "Codewhale" |
| 1407 | }, |
| 1408 | { |
| 1409 | "p": "`/subagents`（与 `/fleet workers` 是同一个视图）会列出挂在本次会话上的智能体，以及每个智能体正在做什么。选中一个即可阅读它的对话记录。" |
| 1410 | }, |
| 1411 | { |
| 1412 | "p": "子智能体遵循你的[审批设置](/docs/modes)。在 Ask 下，需要审批的调用会像普通提示一样出现在你的会话里，智能体则在一旁等待；在 Auto-Review 下，每个被拦下的调用都会经过同样的独立审查，不会打扰你。凡是不是由你亲自做出的决定，都会写进该智能体的对话记录。" |
| 1413 | } |
| 1414 | ] |
| 1415 | }, |
| 1416 | { |
| 1417 | "id": "limits", |
| 1418 | "title": "了解上限", |
| 1419 | "blocks": [ |
| 1420 | { |
| 1421 | "rows": [ |
| 1422 | [ |
| 1423 | "同时运行", |
| 1424 | "默认 64 个。可在 `~/.codewhale/config.toml` 中设置 `max_subagents`（最多 128）。" |
| 1425 | ], |
| 1426 | [ |
| 1427 | "排队加运行", |
| 1428 | "最多 1,024 个；超出的启动请求会排队等待。" |
| 1429 | ], |
| 1430 | [ |
| 1431 | "嵌套", |
| 1432 | "子智能体也可以再启动子智能体，默认最多三层，绝不超过八层。" |
| 1433 | ] |
| 1434 | ] |
| 1435 | }, |
| 1436 | { |
| 1437 | "p": "这些只是上限，不是目标。少量边界清晰的智能体加一份清楚的汇总，胜过一大堆彼此重叠的智能体。如果工作需要在重启或笔记本休眠后继续，请改用 [Fleet 运行](/docs/fleet)。" |
| 1438 | } |
| 1439 | ] |
| 1440 | } |
| 1441 | ], |
| 1442 | "next": [ |
| 1443 | { |
| 1444 | "href": "/docs/fleet", |
| 1445 | "label": "运行工作流", |
| 1446 | "note": "把反复使用的计划写成工作流，分阶段执行，每次运行都有记录。" |
| 1447 | }, |
| 1448 | { |
| 1449 | "href": "/docs/work", |
| 1450 | "label": "跟踪进度", |
| 1451 | "note": "To-do 列表如何显示已完成、进行中和剩余的工作。" |
| 1452 | }, |
| 1453 | { |
| 1454 | "href": "/docs/review", |
| 1455 | "label": "查看改动", |
| 1456 | "note": "在保留之前，先检查这些智能体改了什么。" |
| 1457 | } |
| 1458 | ], |
| 1459 | "sourceNote": "来源文档：docs/SUBAGENTS.md、docs/FLEET.md、docs/MODES.md · 修改时同步更新 docs-map.ts。" |
| 1460 | }, |
| 1461 | "docs-web": { |
| 1462 | "metaTitle": "打开浏览器客户端 · Codewhale 文档", |
| 1463 | "metaDescription": "在你自己机器上的浏览器标签页里使用 Codewhale，或者用 /rc 在 Codewhale 网页应用中接着使用正在终端里运行的会话。", |
| 1464 | "bodyClassName": "text-ink-soft leading-[1.9] tracking-wide", |
| 1465 | "title": "打开浏览器客户端", |
| 1466 | "lede": "比起终端，更喜欢浏览器窗口？Codewhale 可以在你的机器上提供自己的客户端。它只是同一个本地会话的另一种视图——审批相同、沙箱相同，也不需要账户。", |
| 1467 | "sections": [ |
| 1468 | { |
| 1469 | "id": "start", |
| 1470 | "title": "启动", |
| 1471 | "blocks": [ |
| 1472 | { |
| 1473 | "p": "在你希望 Codewhale 工作的文件夹中运行：" |
| 1474 | }, |
| 1475 | { |
| 1476 | "code": "codewhale web\ncodewhale web --port 8788 # if 7878 is taken", |
| 1477 | "lang": "终端" |
| 1478 | }, |
| 1479 | { |
| 1480 | "p": "Codewhale 会在 `http://127.0.0.1:7878` 启动本地服务，打印一个一次性链接，并在默认浏览器中打开它。如果浏览器没有打开，请在十分钟内使用打印出来的链接。在终端按 Ctrl+C 即可停止，浏览器会话也随之结束。" |
| 1481 | } |
| 1482 | ] |
| 1483 | }, |
| 1484 | { |
| 1485 | "id": "use", |
| 1486 | "title": "在浏览器中工作", |
| 1487 | "blocks": [ |
| 1488 | { |
| 1489 | "p": "浏览器客户端可以列出和搜索你的会话线程，显示对话记录及每个工具的结果，并提供输入框。你可以开始、引导或中断一个回合，回应审批，给线程改名或归档。你的提供商密钥始终留在 Codewhale 中，不会被复制到浏览器存储里。" |
| 1490 | } |
| 1491 | ] |
| 1492 | }, |
| 1493 | { |
| 1494 | "id": "local", |
| 1495 | "title": "只在本机使用", |
| 1496 | "blocks": [ |
| 1497 | { |
| 1498 | "list": [ |
| 1499 | "服务只监听 `127.0.0.1`。没有任何选项能把它开放到你的网络，也无法在不认证的情况下运行。", |
| 1500 | "链接中携带的是一次性代码，而不是你的访问令牌。打开链接时，这个代码会换成一个绑定到当前进程的 cookie，随即失效。", |
| 1501 | "不要通过路由器、公共代理或隧道转发这个端口。如果要在手机或另一台机器上使用，请参阅 [Runtime API](/docs/runtime-api)，并先读一读它的认证规则。" |
| 1502 | ] |
| 1503 | } |
| 1504 | ] |
| 1505 | }, |
| 1506 | { |
| 1507 | "id": "remote", |
| 1508 | "title": "在网页应用中接着使用会话", |
| 1509 | "blocks": [ |
| 1510 | { |
| 1511 | "p": "这是另一回事：它把已经在终端里运行的会话交给已登录的 Codewhale 网页应用，让你可以换一台设备继续。这需要一个 [Codewhale 账户](/docs/auth#account)。" |
| 1512 | }, |
| 1513 | { |
| 1514 | "code": "/rc # in the running session; approve the one-time code in your browser\n/rc status # who controls the session now\n/rc link # print the session link\n/rc stop # hand control back to the terminal", |
| 1515 | "lang": "Codewhale" |
| 1516 | }, |
| 1517 | { |
| 1518 | "p": "网页应用接管会话期间，新的提示和审批都来自浏览器，终端仍可查看内容。任何一方都可以中断。你也可以用 `codewhale rc` 直接以这种方式启动会话。" |
| 1519 | } |
| 1520 | ] |
| 1521 | }, |
| 1522 | { |
| 1523 | "id": "fix", |
| 1524 | "title": "遇到问题时", |
| 1525 | "blocks": [ |
| 1526 | { |
| 1527 | "rows": [ |
| 1528 | [ |
| 1529 | "端口被占用", |
| 1530 | "用 `--port` 指定一个空闲端口。" |
| 1531 | ], |
| 1532 | [ |
| 1533 | "浏览器没有打开", |
| 1534 | "在十分钟内，把打印出来的链接复制到同一台机器上的浏览器中打开。" |
| 1535 | ], |
| 1536 | [ |
| 1537 | "链接已过期或已被使用", |
| 1538 | "这是预期行为。重新运行 `codewhale web` 获取新链接。" |
| 1539 | ], |
| 1540 | [ |
| 1541 | "模型没有回复", |
| 1542 | "web 命令不负责配置提供商。请检查 `codewhale doctor` 和 `/provider`。" |
| 1543 | ] |
| 1544 | ] |
| 1545 | } |
| 1546 | ] |
| 1547 | } |
| 1548 | ], |
| 1549 | "next": [ |
| 1550 | { |
| 1551 | "href": "/docs/runtime-api", |
| 1552 | "label": "用 Runtime API 自动化", |
| 1553 | "note": "浏览器客户端所基于的本地 API。" |
| 1554 | }, |
| 1555 | { |
| 1556 | "href": "/docs/auth", |
| 1557 | "label": "连接模型提供商", |
| 1558 | "note": "为浏览器客户端接上一个模型。" |
| 1559 | }, |
| 1560 | { |
| 1561 | "href": "/docs/modes", |
| 1562 | "label": "设置模式与审批", |
| 1563 | "note": "浏览器中同样适用这些审批设置。" |
| 1564 | } |
| 1565 | ], |
| 1566 | "sourceNote": "来源文档：docs/WEB.md · 修改时同步更新 docs-map.ts。" |
| 1567 | }, |
| 1568 | "docs-computers": { |
| 1569 | "metaTitle": "把任务发送到云端 · Codewhale 文档", |
| 1570 | "metaDescription": "把编码任务交给 Codewhale 云端智能体，由它在一个分支上完成工作并提交拉取请求——先提议，只有你确认后才会开始。", |
| 1571 | "bodyClassName": "text-ink-soft leading-[1.9] tracking-wide", |
| 1572 | "title": "把任务发送到云端", |
| 1573 | "lede": "云端智能体会把任务从你的机器上接走：它在一个全新的云端沙箱中工作，推送一个分支并提交拉取请求，你则可以继续在本地工作。在你确认之前，不会启动任何东西、不会产生费用，也不会推送代码。", |
| 1574 | "sections": [ |
| 1575 | { |
| 1576 | "id": "status", |
| 1577 | "title": "了解目前的完成度", |
| 1578 | "blocks": [ |
| 1579 | { |
| 1580 | "note": "云端智能体目前是预览版。完整流程已有离线测试覆盖，但真实链路——真实的沙箱，以及在各个代码托管平台上真实提交的拉取请求——尚未经过端到端验证。暂不支持私有仓库。" |
| 1581 | } |
| 1582 | ] |
| 1583 | }, |
| 1584 | { |
| 1585 | "id": "before", |
| 1586 | "title": "开始之前", |
| 1587 | "blocks": [ |
| 1588 | { |
| 1589 | "list": [ |
| 1590 | "用 `codewhale login` 登录你的 Codewhale 账户。未登录时，任务只能提议，无法确认。", |
| 1591 | "把账户 API 密钥设为 `CODEWHALE_API_KEY`，让沙箱中的智能体以你的账户身份运行。缺少它时，确认会在产生任何费用之前被拒绝。", |
| 1592 | "如果使用 GitHub，请先登录 `gh` 命令行工具；Codewhale 会用这个登录来提交拉取请求。" |
| 1593 | ] |
| 1594 | }, |
| 1595 | { |
| 1596 | "code": "codewhale dispatch --status", |
| 1597 | "lang": "终端" |
| 1598 | }, |
| 1599 | { |
| 1600 | "p": "`--status` 会显示从你的 git 远程仓库中识别出的代码托管平台，以及所需的凭据是否齐全。它从不打印任何密钥。" |
| 1601 | } |
| 1602 | ] |
| 1603 | }, |
| 1604 | { |
| 1605 | "id": "send", |
| 1606 | "title": "先提议，再确认", |
| 1607 | "blocks": [ |
| 1608 | { |
| 1609 | "code": "codewhale dispatch \"fix the flaky login test and open a PR\" --remote github\ncodewhale dispatch --confirm cloud_<id>", |
| 1610 | "lang": "终端" |
| 1611 | }, |
| 1612 | { |
| 1613 | "p": "第一条命令只写入一份提议并打印其 id；第二条命令才真正启动。Codewhale 可以自己提议云端任务，但从不自行确认。在会话中，使用 `/dispatch <task>` 和 `/dispatch confirm <id>`。" |
| 1614 | }, |
| 1615 | { |
| 1616 | "p": "确认之后，智能体会把仓库克隆到一个新沙箱中完成工作，推送一个新分支（绝不强制推送），并提交拉取请求。任务完成、失败或被取消时，沙箱都会被删除。" |
| 1617 | } |
| 1618 | ] |
| 1619 | }, |
| 1620 | { |
| 1621 | "id": "track", |
| 1622 | "title": "跟踪或取消任务", |
| 1623 | "blocks": [ |
| 1624 | { |
| 1625 | "code": "codewhale dispatch --list\ncodewhale dispatch --show cloud_<id>\ncodewhale dispatch --cancel cloud_<id>", |
| 1626 | "lang": "终端" |
| 1627 | }, |
| 1628 | { |
| 1629 | "p": "云端任务也会出现在 `/jobs` 中。每个任务会显示进度、分支、拉取请求链接（有了之后），以及运行了多少分钟——这是运行时长，不是账单。取消会立即拆除沙箱。" |
| 1630 | } |
| 1631 | ] |
| 1632 | }, |
| 1633 | { |
| 1634 | "id": "forge", |
| 1635 | "title": "选择拉取请求提交到哪里", |
| 1636 | "blocks": [ |
| 1637 | { |
| 1638 | "p": "Codewhale 支持 GitHub、CNB 和 Gitee，且从不假定 `origin` 就是 GitHub。名为 `github`、`cnb` 或 `gitee` 的远程仓库即对应该平台；其他远程仓库按其主机名识别。如果仓库关联了多个平台，请传入 `--remote`。" |
| 1639 | }, |
| 1640 | { |
| 1641 | "p": "如果拉取请求无法提交——例如缺少代码托管平台的令牌——任务会在推送之后被标记为失败，并说明没有提交拉取请求。它绝不会报告一个并不存在的链接。" |
| 1642 | } |
| 1643 | ] |
| 1644 | } |
| 1645 | ], |
| 1646 | "next": [ |
| 1647 | { |
| 1648 | "href": "/docs/auth", |
| 1649 | "label": "连接模型提供商", |
| 1650 | "note": "登录 Codewhale 账户并管理密钥。" |
| 1651 | }, |
| 1652 | { |
| 1653 | "href": "/docs/review", |
| 1654 | "label": "查看改动", |
| 1655 | "note": "合并之前，先审查智能体提交的拉取请求。" |
| 1656 | }, |
| 1657 | { |
| 1658 | "href": "/docs/fleet", |
| 1659 | "label": "运行工作流", |
| 1660 | "note": "改为在你自己的机器上运行更长的多步骤工作。" |
| 1661 | } |
| 1662 | ], |
| 1663 | "sourceNote": "来源文档：docs/DAYTONA_CLOUD_DISPATCH.md、docs/CODEWHALE_AGENT.md · 修改时同步更新 docs-map.ts。" |
| 1664 | }, |
| 1665 | "docs-auth": { |
| 1666 | "metaTitle": "连接模型提供商 · Codewhale 文档", |
| 1667 | "metaDescription": "为 Codewhale 接上模型：保存提供商密钥、查看当前使用的是哪把密钥，或者不用密钥直接运行本地模型。Codewhale 账户是可选的。", |
| 1668 | "bodyClassName": "text-ink-soft leading-[1.9] tracking-wide", |
| 1669 | "title": "连接模型提供商", |
| 1670 | "lede": "Codewhale 需要一个模型来回答问题。你可以为云端提供商保存一把密钥，也可以让它连接你本机运行的模型。费用由你直接付给提供商，不经过 Codewhale 账户。", |
| 1671 | "sections": [ |
| 1672 | { |
| 1673 | "id": "save-key", |
| 1674 | "title": "保存提供商密钥", |
| 1675 | "blocks": [ |
| 1676 | { |
| 1677 | "p": "先在提供商那里申请 API 密钥，然后保存。Codewhale 会提示你输入密钥，输入内容不会回显。DeepSeek 是默认提供商，下面以它为例。" |
| 1678 | }, |
| 1679 | { |
| 1680 | "code": "codewhale auth set --provider deepseek\ncodewhale auth status --provider deepseek", |
| 1681 | "lang": "终端" |
| 1682 | }, |
| 1683 | { |
| 1684 | "p": "`auth status` 会说明当前密钥来自哪里——配置文件、密钥存储还是环境变量——并且只显示最后四位。在脚本里可以用 `--api-key-stdin` 通过管道传入密钥，不必手动输入。" |
| 1685 | }, |
| 1686 | { |
| 1687 | "p": "也可以在 Codewhale 里连接：按 F3（或输入 `/provider`），选择提供商，粘贴密钥，再选一个模型。" |
| 1688 | }, |
| 1689 | { |
| 1690 | "note": "在 v0.10.0 中，`auth set --provider deepseek` 还会把默认模型切换为 DeepSeek Pro。想换回更快、更便宜的模型，运行 `/model` 即可。通过 F3 连接则会保留你当前的模型。" |
| 1691 | } |
| 1692 | ] |
| 1693 | }, |
| 1694 | { |
| 1695 | "id": "which-key", |
| 1696 | "title": "弄清用的是哪把密钥", |
| 1697 | "blocks": [ |
| 1698 | { |
| 1699 | "p": "同一个提供商的密钥如果设在多处，按下面的顺序取第一个找到的：" |
| 1700 | }, |
| 1701 | { |
| 1702 | "steps": [ |
| 1703 | "命令行上的 `--api-key`，只对这一次运行生效。", |
| 1704 | "`~/.codewhale/config.toml` 中的 `api_key`。", |
| 1705 | "`codewhale auth set` 写入的密钥存储。", |
| 1706 | "提供商自己的环境变量，例如 `DEEPSEEK_API_KEY`。" |
| 1707 | ] |
| 1708 | }, |
| 1709 | { |
| 1710 | "p": "因此，导出一个新的环境变量并不会替换你之前保存的密钥。如果换过的密钥一直报错，先用 `auth status` 看看生效的是哪个来源，再保存新密钥，或清除已存的旧密钥：" |
| 1711 | }, |
| 1712 | { |
| 1713 | "code": "codewhale auth clear --provider deepseek", |
| 1714 | "lang": "终端" |
| 1715 | }, |
| 1716 | { |
| 1717 | "p": "在 Linux 上，密钥存储是 `~/.codewhale/secrets/` 下的一个私有文件（权限 0600），而不是系统钥匙串。`codewhale doctor --probe-api` 会发起一次测试调用，确认密钥和网络都正常。" |
| 1718 | } |
| 1719 | ] |
| 1720 | }, |
| 1721 | { |
| 1722 | "id": "other-providers", |
| 1723 | "title": "使用其他提供商或本地模型", |
| 1724 | "blocks": [ |
| 1725 | { |
| 1726 | "p": "`codewhale auth list` 会列出 Codewhale 支持的所有提供商，以及每个提供商是否已有密钥。所有提供商的用法都一样：`codewhale auth set --provider <name>`，或者设置该提供商的环境变量。" |
| 1727 | }, |
| 1728 | { |
| 1729 | "p": "本地运行器——Ollama、vLLM 和 SGLang——默认不需要密钥，你的提示词也不会离开本机。先启动运行器，再选择它：" |
| 1730 | }, |
| 1731 | { |
| 1732 | "code": "codewhale auth list\ncodewhale --provider ollama --model <model-tag>", |
| 1733 | "lang": "终端" |
| 1734 | }, |
| 1735 | { |
| 1736 | "p": "[模型页面](/models) 列出了各家提供商、本地部署方式，以及如何在会话中切换模型。" |
| 1737 | } |
| 1738 | ] |
| 1739 | }, |
| 1740 | { |
| 1741 | "id": "account", |
| 1742 | "title": "登录 Codewhale 账户（可选）", |
| 1743 | "blocks": [ |
| 1744 | { |
| 1745 | "p": "提供商密钥和 Codewhale 账户是两回事。账户只用于账户相关的功能，比如云端智能体、在网页应用里接着使用某个会话。安装 Codewhale 和在本地工作都不需要账户。" |
| 1746 | }, |
| 1747 | { |
| 1748 | "rows": [ |
| 1749 | [ |
| 1750 | "codewhale login", |
| 1751 | "在浏览器中用一次性验证码登录。" |
| 1752 | ], |
| 1753 | [ |
| 1754 | "codewhale account status", |
| 1755 | "查看当前配置档登录的是哪个账户。" |
| 1756 | ], |
| 1757 | [ |
| 1758 | "codewhale account logout", |
| 1759 | "移除当前配置档的登录会话。" |
| 1760 | ], |
| 1761 | [ |
| 1762 | "codewhale account keys list", |
| 1763 | "列出保存在账户里的提供商密钥，永远不会显示密钥内容。" |
| 1764 | ] |
| 1765 | ], |
| 1766 | "codeTerms": true |
| 1767 | }, |
| 1768 | { |
| 1769 | "p": "`codewhale login` 不接收提供商密钥，提供商密钥一律通过 `codewhale auth set` 保存。登录会话优先保存在操作系统的凭据管理器中；没有凭据管理器时（例如通过 SSH 或在容器里），则保存在 Codewhale 的私有密钥文件中。" |
| 1770 | } |
| 1771 | ] |
| 1772 | } |
| 1773 | ], |
| 1774 | "next": [ |
| 1775 | { |
| 1776 | "href": "/docs/guide", |
| 1777 | "label": "开始第一个任务", |
| 1778 | "note": "在项目里打开 Codewhale，交给它一件具体的事。" |
| 1779 | }, |
| 1780 | { |
| 1781 | "href": "/docs/modes", |
| 1782 | "label": "设置模式与审批", |
| 1783 | "note": "决定 Codewhale 运行命令之前是否先问你。" |
| 1784 | }, |
| 1785 | { |
| 1786 | "href": "/docs/trust", |
| 1787 | "label": "了解哪些数据会离开本机", |
| 1788 | "note": "提供商会收到什么、哪些留在本地，以及如何关闭用量统计。" |
| 1789 | } |
| 1790 | ], |
| 1791 | "sourceNote": "来源文档：docs/INSTALL.md §8、docs/PROVIDERS.md、docs/CODEWHALE_AGENT.md · 修改时同步更新 docs-map.ts。" |
| 1792 | }, |
| 1793 | "docs-trust": { |
| 1794 | "metaTitle": "了解哪些数据会离开本机 · Codewhale 文档", |
| 1795 | "metaDescription": "哪些内容留在本地、模型提供商会收到什么、用量统计发送什么以及如何关闭、审计日志在哪里，以及如何报告安全漏洞。", |
| 1796 | "bodyClassName": "text-ink-soft leading-[1.9] tracking-wide", |
| 1797 | "title": "了解哪些数据会离开本机", |
| 1798 | "lede": "Codewhale 在你的电脑上运行，只与你选择的模型提供商通信。这一页按目前的实际实现，列出数据分别去了哪里、匿名用量统计包含什么，以及如何关闭它。", |
| 1799 | "sections": [ |
| 1800 | { |
| 1801 | "id": "boundaries", |
| 1802 | "title": "你的工作内容去了哪里", |
| 1803 | "blocks": [ |
| 1804 | { |
| 1805 | "rows": [ |
| 1806 | [ |
| 1807 | "留在本机", |
| 1808 | "运行时、你的工作区、会话历史、快照和审计日志。" |
| 1809 | ], |
| 1810 | [ |
| 1811 | "发给你的提供商", |
| 1812 | "每个回合所需的上下文——你的消息、Codewhale 为这一回合读取的文件和工具结果——直接发给你选定的提供商，中间没有 Codewhale 中转。" |
| 1813 | ], |
| 1814 | [ |
| 1815 | "完全留在本地", |
| 1816 | "使用本地模型（Ollama、vLLM、SGLang）时，推理完全不离开你的机器。" |
| 1817 | ], |
| 1818 | [ |
| 1819 | "无需账户", |
| 1820 | "在本地安装和运行 Codewhale 不需要 Codewhale 账户。" |
| 1821 | ], |
| 1822 | [ |
| 1823 | "Plan 模式", |
| 1824 | "不能修改文件，也不能运行 shell 命令。但它被允许进行的资料查询仍可能访问外部服务。" |
| 1825 | ] |
| 1826 | ] |
| 1827 | }, |
| 1828 | { |
| 1829 | "p": "你添加的工具可能把数据发到别处：MCP 服务器、网页搜索或钩子都以你的权限运行，能访问到它们能访问的一切。只添加你信任的工具。" |
| 1830 | } |
| 1831 | ] |
| 1832 | }, |
| 1833 | { |
| 1834 | "id": "telemetry", |
| 1835 | "title": "了解用量统计会发送什么", |
| 1836 | "blocks": [ |
| 1837 | { |
| 1838 | "p": "Codewhale 默认开启匿名用量统计，并在你第一次启动时明确告知，写明处理方是 Codewhale 和 PostHog。它具体包含：" |
| 1839 | }, |
| 1840 | { |
| 1841 | "rows": [ |
| 1842 | [ |
| 1843 | "从不发送", |
| 1844 | "提示词、回复、代码、diff、文件内容、文件名/仓库名/分支名、路径、模型 id、MCP 服务器名称、API 密钥或令牌、错误信息文本、按键记录，以及任何按回合或按工具的时间线。" |
| 1845 | ], |
| 1846 | [ |
| 1847 | "开启时发送", |
| 1848 | "版本与平台类别、会话时长与结果、以固定类别统计的功能与错误计数，以及一个每 90 天更换一次的随机安装 id。" |
| 1849 | ], |
| 1850 | [ |
| 1851 | "发往哪里", |
| 1852 | "`https://telemetry.codewhale.net/v1/telemetry`，一个第一方服务，源码就在仓库中。它不存储 IP 地址、国家或位置，不保留请求日志，数据保存三个月。" |
| 1853 | ], |
| 1854 | [ |
| 1855 | "PostHog", |
| 1856 | "只有在服务运营方另行配置后，才会转发给 PostHog；转发的字段完全相同，不会多出任何内容。" |
| 1857 | ] |
| 1858 | ] |
| 1859 | } |
| 1860 | ] |
| 1861 | }, |
| 1862 | { |
| 1863 | "id": "turn-off", |
| 1864 | "title": "关闭用量统计", |
| 1865 | "blocks": [ |
| 1866 | { |
| 1867 | "code": "codewhale config set telemetry false # stop, and erase the local id and buffer\nCODEWHALE_TELEMETRY=0 codewhale # stop for this process, erase nothing", |
| 1868 | "lang": "终端" |
| 1869 | }, |
| 1870 | { |
| 1871 | "p": "配置项是持久的选择：之后的版本都会沿用，命令行参数或环境变量也无法把它重新打开。你也可以在 `/settings` 中切换。关闭后，保存在你机器上的数据会被删除；已经发送的记录只与刚被删除的那个随机 id 关联，并会在三个月后过期。" |
| 1872 | }, |
| 1873 | { |
| 1874 | "p": "想确切看到会发送什么、但又不真的发送，可以在 `~/.codewhale/config.toml` 中设置 `telemetry_endpoint = \"\"`。此后每一批数据都会逐字节写入本机的 `$CODEWHALE_HOME/telemetry/dryrun.jsonl`，不会建立任何网络连接。" |
| 1875 | } |
| 1876 | ] |
| 1877 | }, |
| 1878 | { |
| 1879 | "id": "audit", |
| 1880 | "title": "查看本地审计日志", |
| 1881 | "blocks": [ |
| 1882 | { |
| 1883 | "p": "凭据、审批和提权相关的事件会追加写入 `$CODEWHALE_HOME/audit.log`（默认是 `~/.codewhale/audit.log`）。写入是尽力而为的：写入失败时会记录失败，而不是隐瞒。这份日志从不离开你的机器。" |
| 1884 | } |
| 1885 | ] |
| 1886 | }, |
| 1887 | { |
| 1888 | "id": "report", |
| 1889 | "title": "报告安全漏洞", |
| 1890 | "blocks": [ |
| 1891 | { |
| 1892 | "p": "请把安全问题发送到下方邮箱，不要公开提交 issue。请附上你的 Codewhale 版本（`codewhale --version`），如有复现步骤也请一并提供。" |
| 1893 | } |
| 1894 | ] |
| 1895 | } |
| 1896 | ], |
| 1897 | "next": [ |
| 1898 | { |
| 1899 | "href": "/docs/sandbox", |
| 1900 | "label": "限制命令的访问范围", |
| 1901 | "note": "各平台上操作系统沙箱实际限制了什么。" |
| 1902 | }, |
| 1903 | { |
| 1904 | "href": "/docs/modes", |
| 1905 | "label": "设置模式与审批", |
| 1906 | "note": "决定 Codewhale 不经询问可以做什么。" |
| 1907 | }, |
| 1908 | { |
| 1909 | "href": "/docs/auth", |
| 1910 | "label": "连接模型提供商", |
| 1911 | "note": "选择由谁接收你的回合内容——或者用本地模型让它留在本机。" |
| 1912 | } |
| 1913 | ], |
| 1914 | "sourceNote": "来源文档：docs/public-surface-facts.json（trust）、docs/TELEMETRY.md、docs/SANDBOX.md · 修改时同步更新 docs-map.ts。" |
| 1915 | }, |
| 1916 | "states": { |
| 1917 | "loadingLabel": "加载中…", |
| 1918 | "emptyTitle": "这里还没有内容", |
| 1919 | "emptyBody": "暂时没有可显示的记录。这里不会用编造的内容填充。", |
| 1920 | "errorTitle": "页面没有加载完成", |
| 1921 | "errorBody": "中途出了问题。你的操作没有丢失；请重试，如果持续失败，请报告给我们。", |
| 1922 | "retry": "重试", |
| 1923 | "reload": "重新加载页面", |
| 1924 | "homeLink": "返回首页", |
| 1925 | "docsIndexLink": "打开文档目录", |
| 1926 | "notFoundTitle": "谁还没打过错字呢。", |
| 1927 | "notFoundBody": "这个页面还不存在。\n这款游戏也一样。", |
| 1928 | "notFoundHomeLink": "返回基地", |
| 1929 | "notFoundPosterAlt": "虚构游戏《Codwhale: Modern Whalefare》的海报，一只身穿战术装备的蓝鲸。", |
| 1930 | "unavailableTitle": "实时记录尚未加载", |
| 1931 | "unavailableBody": "数据源没有响应上一次刷新，或者此页面自构建以来尚未刷新。这里不会用编造的内容填充。", |
| 1932 | "offlineTitle": "你已离线", |
| 1933 | "offlineBody": "操作已暂停，直到网络恢复。此处显示的内容不会刷新。", |
| 1934 | "reconnectingTitle": "正在重新连接…", |
| 1935 | "reconnectingBody": "正在检查连接（第 {attempt} 次）。", |
| 1936 | "degradedTitle": "连接不稳定", |
| 1937 | "degradedBody": "服务器没有响应上一次检查。你看到的内容可能已过时。", |
| 1938 | "onlineTitle": "已恢复在线", |
| 1939 | "onlineBody": "连接已恢复。", |
| 1940 | "retryNow": "立即重试", |
| 1941 | "dismiss": "关闭", |
| 1942 | "lastChecked": "上次检查 {time}" |
| 1943 | }, |
| 1944 | "changelog": { |
| 1945 | "metaTitle": "更新日志 · Codewhale", |
| 1946 | "metaDescription": "Codewhale 发布记录：最新已发布版本、尚未发布的源码候选版，以及每个版本的说明，均取自仓库中的 CHANGELOG.md。", |
| 1947 | "kicker": "发布记录", |
| 1948 | "title": "改了什么，在哪个版本。", |
| 1949 | "lead": "页面顶部是两个事实：最新发布的版本，以及源码树当前声明的版本。下面的内容逐节来自仓库自己的 CHANGELOG.md。", |
| 1950 | "publishedLabel": "最新已发布版本", |
| 1951 | "publishedValue": "{tag} · 发布于 {date}", |
| 1952 | "candidateLabel": "源码候选版", |
| 1953 | "candidateValue": "{version} · 未发布", |
| 1954 | "candidateMatches": "{version} · 与已发布版本一致", |
| 1955 | "releasesLink": "GitHub Releases ↗", |
| 1956 | "unreleasedHeading": "未发布", |
| 1957 | "unreleasedNote": "自上一个标签以来合并到主分支的改动。它们属于源码候选版，不属于任何已发布的包。", |
| 1958 | "compareLink": "在 GitHub 上比较 ↗", |
| 1959 | "releasePageLink": "发布页 ↗", |
| 1960 | "moreEntries": "显示 {shown} / {total} 条", |
| 1961 | "fullNotes": "完整说明见 CHANGELOG.md ↗", |
| 1962 | "releaseNotesLink": "{version} 完整说明 ↗", |
| 1963 | "emptyTitle": "没有解析出发布说明", |
| 1964 | "emptyBody": "构建时没有找到可解析的 CHANGELOG.md。GitHub 的发布列表仍然是权威记录。" |
| 1965 | }, |
| 1966 | "computer-use": { |
| 1967 | "metaTitle": "Mac 版 Computer Use · Codewhale", |
| 1968 | "metaDescription": "下载并设置 Mac 版 Codewhale Computer Use。提供应用后台操作、权限设置，以及由用户控制的暂停和停止功能。", |
| 1969 | "title": "Computer Use", |
| 1970 | "lead": "让 Codewhale 在应用中完成操作，你也可以继续工作。Mac 助手将权限设置、应用后台操作，以及暂停或停止输入的控制集中在菜单栏中。", |
| 1971 | "publisher": "由 Codewhale 开发", |
| 1972 | "download": "下载 Mac 版", |
| 1973 | "downloadZip": "ZIP 压缩包（供应用内更新使用）", |
| 1974 | "requirements": "macOS 13.5 或更高版本 · Apple 芯片与 Intel", |
| 1975 | "included": "只需下载一个应用，无需另行安装 Node 或编译器。", |
| 1976 | "pendingTitle": "Mac 下载包准备中", |
| 1977 | "pendingBody": "完成 Apple 公证和发布检查后，正式安装包将在此提供。", |
| 1978 | "unavailableTitle": "暂时无法查询下载状态", |
| 1979 | "unavailableBody": "请刷新页面重试，或通过下方链接查看已发布版本。", |
| 1980 | "releases": "已发布版本", |
| 1981 | "receipt": "下载校验信息", |
| 1982 | "setup": "设置你的 Mac", |
| 1983 | "steps": [ |
| 1984 | { |
| 1985 | "title": "安装应用", |
| 1986 | "body": "打开下载的磁盘映像，将 Codewhale Computer Use 拖入“应用程序”。从“应用程序”中打开它，然后点击菜单栏中的鲸鱼图标，选择 Computer Use。" |
| 1987 | }, |
| 1988 | { |
| 1989 | "title": "检查权限", |
| 1990 | "body": "通过设置按钮打开系统设置中的“辅助功能”和“屏幕录制”。由你决定授予哪些权限。" |
| 1991 | }, |
| 1992 | { |
| 1993 | "title": "运行后台检查", |
| 1994 | "body": "助手会打开一个临时练习窗口，输入文本并截取该窗口，同时检查运行期间指针或前台应用是否发生变化。" |
| 1995 | }, |
| 1996 | { |
| 1997 | "title": "连接 Codewhale", |
| 1998 | "body": "在 Codewhale 插件市场中审查、信任并启用 Computer Use。请使用插件 0.3.1 或更高版本，确保本地操作受助手的暂停和停止控制。" |
| 1999 | } |
| 2000 | ], |
| 2001 | "controlsTitle": "继续工作，掌握控制权。", |
| 2002 | "controlsBody": "受支持的操作可在选定应用的后台完成。需要前台控制的应用或手势必须得到你的授权。菜单会显示目标应用与输入模式；Pause 暂停助手输入，Stop 结束助手的现有会话。", |
| 2003 | "updateTitle": "由你决定何时更新", |
| 2004 | "updateBody": "在应用中选择 Check for updates。安装更新前，助手会校验下载文件、Codewhale 签名和 Apple 公证，并保留旧版应用以便恢复。", |
| 2005 | "help": "设置与故障排查", |
| 2006 | "notes": "版本说明", |
| 2007 | "demo": "查看后台检查演示", |
| 2008 | "source": "源码与其他平台", |
| 2009 | "platforms": "此下载适用于 Mac。Windows 和 Linux 目前通过源码插件及宿主端设置使用。" |
| 2010 | } |
| 2011 | } |
| 2012 |