| 1 | import type { DocsTroubleshootingDict } from "../types"; |
| 2 | |
| 3 | /** 「排查问题」页的简体中文词典；与 `en/docs-troubleshooting.ts` 逐段对应，报错原文保持英文。 */ |
| 4 | export const docsTroubleshooting: DocsTroubleshootingDict = { |
| 5 | metaTitle: "排查问题 · Codewhale 文档", |
| 6 | metaDescription: |
| 7 | "用一条命令诊断 Codewhale，再逐一解决常见问题：找不到命令、没有回复、密钥被拒、网络错误、回合卡住、会话无法恢复，以及 MCP 服务器问题。", |
| 8 | bodyClassName: "text-ink-soft leading-[1.9] tracking-wide", |
| 9 | title: "排查问题", |
| 10 | lede: "先运行一条诊断命令，再在下面找到你遇到的症状。每条解决办法都写明了你会看到的确切报错。", |
| 11 | sections: [ |
| 12 | { |
| 13 | id: "diagnose", |
| 14 | title: "运行诊断", |
| 15 | blocks: [ |
| 16 | { |
| 17 | code: `codewhale --version |
| 18 | codewhale doctor |
| 19 | codewhale doctor --probe-api # one real test call to your provider |
| 20 | codewhale auth status --provider deepseek # which key is in use`, |
| 21 | lang: "终端", |
| 22 | }, |
| 23 | { |
| 24 | p: "`codewhale doctor --json` 会生成一份不含任何密钥的诊断包，可以直接附到 issue 上。单独运行 `doctor` 不会告诉你当前用的是哪把密钥，即使没有密钥也会正常退出；查密钥请用 `auth status`。", |
| 25 | }, |
| 26 | ], |
| 27 | }, |
| 28 | { |
| 29 | id: "install", |
| 30 | title: "安装与更新", |
| 31 | blocks: [ |
| 32 | { |
| 33 | rows: [ |
| 34 | ["`codewhale: command not found`", "当前终端的 PATH 中没有 `~/.local/bin`。把 `export PATH=\"$HOME/.local/bin:$PATH\"` 加入 shell 配置文件，然后打开一个新终端。"], |
| 35 | ["`npm error code EACCES`", "你的 Node 由系统管理。不要用 sudo：用 `npm config set prefix \"$HOME/.npm-global\"` 让 npm 安装到你自己的目录，把其中的 `bin` 加入 PATH，再重新安装。"], |
| 36 | ["`refusing to replace existing ~/.local/bin/codewhale`", "那里已经装了另一个版本。运行 `codewhale update`，或者先删除旧的二进制文件。"], |
| 37 | ["`checksum mismatch`", "下载的文件损坏或被篡改，因此没有安装任何东西。请重试；如果一再出现，不要使用镜像源。"], |
| 38 | ["`The package-managed executable was not changed.`", "你是通过 npm、Cargo 或 Homebrew 安装的，请用对应的工具更新，例如 `npm install -g codewhale`。"], |
| 39 | ], |
| 40 | }, |
| 41 | ], |
| 42 | }, |
| 43 | { |
| 44 | id: "model", |
| 45 | title: "没有回复，或密钥被拒", |
| 46 | blocks: [ |
| 47 | { |
| 48 | rows: [ |
| 49 | ["消息发出后一直没有回复", "没有配置密钥，而 v0.10.0 不会提示你。按 F3，选择你的提供商，粘贴密钥。"], |
| 50 | ["`API key not found`", "哪里都找不到密钥。用 `codewhale auth set --provider <name>` 保存一把。"], |
| 51 | ["`Authentication Fails … is invalid`", "密钥错误或已被吊销。运行 `auth status` 查看用的是哪个来源——已保存的密钥优先于环境变量——然后保存正确的密钥，或运行 `codewhale auth clear --provider <name>`。"], |
| 52 | ["`Network error: SSE stream request failed …`", "通常是连不上提供商。用 `curl -sI https://api.deepseek.com` 检查（返回 401 说明能连通）。在代理后面时请导出 `HTTPS_PROXY`；在 Windows 或限制严格的代理环境下，可以试试 `CODEWHALE_FORCE_HTTP1=1`。"], |
| 53 | ], |
| 54 | }, |
| 55 | ], |
| 56 | }, |
| 57 | { |
| 58 | id: "turn", |
| 59 | title: "回合卡住了", |
| 60 | blocks: [ |
| 61 | { |
| 62 | list: [ |
| 63 | "按 Esc 取消当前回合。Esc 会先关闭已打开的菜单，所以如果开着菜单，需要再按一次。", |
| 64 | "如果是一条耗时很长的 shell 命令拖住了回合，按 Ctrl-B 把它移到后台。回合会继续进行，`/jobs` 中可以看到这条命令。", |
| 65 | "`/retry` 会重新发送上一次请求。", |
| 66 | ], |
| 67 | }, |
| 68 | { |
| 69 | p: "需要详细记录时，用 `RUST_LOG=codewhale_tui=debug` 启动 Codewhale（排查连接重试用 `RUST_LOG=codewhale_tui::client=debug`）。日志写在 `~/.codewhale/logs/` 下。", |
| 70 | }, |
| 71 | ], |
| 72 | }, |
| 73 | { |
| 74 | id: "sessions", |
| 75 | title: "恢复会话", |
| 76 | blocks: [ |
| 77 | { |
| 78 | code: `codewhale sessions # list saved sessions |
| 79 | codewhale resume <id> # an id or a unique prefix |
| 80 | codewhale -c # the latest session in this folder`, |
| 81 | lang: "终端", |
| 82 | }, |
| 83 | { |
| 84 | p: "在 Codewhale 中按 Ctrl-R 可以打开会话选择器。如果 `codewhale exec --continue` 报出 `No saved sessions found for workspace`，说明之前那次是普通的 `exec` 运行，它不会被保存；想接着运行的任务请使用 `--output-format stream-json`。", |
| 85 | }, |
| 86 | { |
| 87 | p: "离线时发送的消息会随会话一起保存在队列中，`/queue list` 可以查看。网络恢复后，用 `/queue edit <n>` 打开其中一条，按 Enter 发送。", |
| 88 | }, |
| 89 | ], |
| 90 | }, |
| 91 | { |
| 92 | id: "mcp", |
| 93 | title: "MCP 工具不见了", |
| 94 | blocks: [ |
| 95 | { |
| 96 | list: [ |
| 97 | "修改 `mcp.json` 或服务器凭据后，运行 `/mcp reload`。`/mcp validate` 只会刷新界面上显示的内容。", |
| 98 | "在 shell 中亲自运行一遍服务器命令，确认它能启动。", |
| 99 | "如果配置文件丢失或损坏，`codewhale mcp init --force` 会重新生成一份。", |
| 100 | ], |
| 101 | }, |
| 102 | ], |
| 103 | }, |
| 104 | { |
| 105 | id: "docker", |
| 106 | title: "在 Docker 中运行", |
| 107 | blocks: [ |
| 108 | { |
| 109 | code: `docker volume create codewhale-home |
| 110 | docker run --rm -it \\ |
| 111 | -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \\ |
| 112 | -v codewhale-home:/home/codewhale/.codewhale \\ |
| 113 | -v "$PWD:/workspace" -w /workspace \\ |
| 114 | ghcr.io/codewhale-hq/codewhale:latest`, |
| 115 | lang: "终端", |
| 116 | }, |
| 117 | { |
| 118 | p: "镜像以非 root 用户运行，把你的设置和会话保存在命名卷里。想要可重复的环境，请固定某个发布标签而不是 `latest`；每个项目使用单独的卷；永远不要把密钥打包进镜像。", |
| 119 | }, |
| 120 | ], |
| 121 | }, |
| 122 | ], |
| 123 | next: [ |
| 124 | { |
| 125 | href: "/docs/auth", |
| 126 | label: "连接模型提供商", |
| 127 | note: "保存密钥、查看当前使用的是哪一把，或改用本地模型。", |
| 128 | }, |
| 129 | { |
| 130 | href: "/install", |
| 131 | label: "安装 Codewhale", |
| 132 | note: "所有安装方式，以及每一步应有的输出。", |
| 133 | }, |
| 134 | { |
| 135 | href: "/docs/review", |
| 136 | label: "查看改动", |
| 137 | note: "把文件回滚到出问题之前那个回合的快照。", |
| 138 | }, |
| 139 | ], |
| 140 | sourceNote: "来源文档：docs/INSTALL.md §13、docs/OPERATIONS_RUNBOOK.md、docs/DOCKER.md · 修改时同步更新 docs-map.ts。", |
| 141 | }; |
| 142 |