| 1 | # codewhale 运维手册（Operations Runbook） |
| 2 | |
| 3 | > 英文原文：[OPERATIONS_RUNBOOK.md](../OPERATIONS_RUNBOOK.md)。 |
| 4 | > 最后与英文同步日期（last synced with English revision）：2026-09-29。 |
| 5 | |
| 6 | 本手册覆盖本地 CLI/TUI 运行时（runtime）的实用调试与事故响应。 |
| 7 | |
| 8 | ## 快速分诊 |
| 9 | |
| 10 | 1. 确认二进制与配置： |
| 11 | - `cargo run -- --version` |
| 12 | - `cat ~/.codewhale/config.toml`（或检查已配置的 profile） |
| 13 | 2. 打开详细日志： |
| 14 | - `RUST_LOG=codewhale_tui=debug cargo run` |
| 15 | - HTTP 重试／重连：`RUST_LOG=codewhale_tui::client=debug cargo run` |
| 16 | 3. 抓取当前状态： |
| 17 | - `ls ~/.codewhale/sessions` |
| 18 | - `ls ~/.codewhale/sessions/checkpoints` |
| 19 | - `ls ~/.codewhale/tasks` |
| 20 | |
| 21 | ## 事故：回合（turn）挂起或流停止 |
| 22 | |
| 23 | 症状： |
| 24 | - TUI 一直停在加载状态 |
| 25 | - 智能体输出不完整且没有结束 |
| 26 | |
| 27 | 检查： |
| 28 | 1. 查看重试／健康日志（`codewhale_tui::client`） |
| 29 | 2. 验证端点连通性： |
| 30 | - `curl -sS https://api.deepseek.com/beta/models -H "Authorization: Bearer $DEEPSEEK_API_KEY"` |
| 31 | 3. 确认工具输出里没有本地沙箱（sandbox）／权限死锁 |
| 32 | |
| 33 | 处置： |
| 34 | 1. 如果有一个前台 shell 命令正在运行，按 `Ctrl+B` 把它移到后台（回合继续运行，该命令会变成 `/jobs` 下的后台作业）；如果你要取消这个回合，就改用 `Ctrl+C`。 |
| 35 | 2. 如果该命令是在后台启动的，请让智能体用 `Bash` 加上 `action: "cancel"` 和返回的进程 id 来取消。 |
| 36 | 3. 当你要停掉请求本身时，用 `Esc` 或 `Ctrl+C` 中断当前回合。 |
| 37 | 4. 重试提示词（prompt）；如果仍然失败，重启 TUI。 |
| 38 | 5. 重启后，确认之前排队中／在途的运行时回合显示为已中断，而不是仍处于运行状态。 |
| 39 | |
| 40 | ## 事故：网络中断／离线行为 |
| 41 | |
| 42 | 预期行为： |
| 43 | - 离线模式生效期间，新的提示词会排入队列 |
| 44 | - 队列状态按会话（session）持久化到 |
| 45 | `~/.codewhale/sessions/checkpoints/<session-id>.offline_queue.json`；旧的全局 |
| 46 | `offline_queue.json` 会在升级时被采纳一次 |
| 47 | |
| 48 | 检查： |
| 49 | 1. 在 TUI 中打开队列：`/queue list` |
| 50 | 2. 确认持久化的队列文件存在，且时间戳在更新 |
| 51 | |
| 52 | 处置： |
| 53 | 1. 恢复连通性 |
| 54 | 2. 重新发送排队的条目（从 `/queue edit <n>` + Enter，或走正常的输入流程） |
| 55 | 3. 确认队列为空时队列文件会被清除 |
| 56 | |
| 57 | ## 事故：需要崩溃恢复 |
| 58 | |
| 59 | 预期行为： |
| 60 | - 每个会话都会把检查点（checkpoint）写到 |
| 61 | `~/.codewhale/sessions/checkpoints/<session-id>.json`；旧的 `latest.json` |
| 62 | 仍会被读取用于恢复，但不再写入 |
| 63 | - 除非提供 `--resume`/`--continue`，启动时会开一个新的会话 |
| 64 | |
| 65 | 处置： |
| 66 | 1. 用 `codewhale --resume <id>` 显式恢复先前的工作（别名 |
| 67 | `codewhale resume <id>`；`codewhale --continue` 会恢复该工作区里最新的 |
| 68 | 已中断检查点），或在 TUI 里按 `Ctrl+R` |
| 69 | 2. 如果需要检查检查点内容，就查看 `checkpoints/<session-id>.json`（或残留的旧 |
| 70 | `latest.json`）里的 schema 不匹配／细节 |
| 71 | 3. 如果 schema 比二进制支持的更新，就升级二进制，或删除过期的检查点 |
| 72 | |
| 73 | ## 事故：持久化状态的 schema 错误 |
| 74 | |
| 75 | 症状： |
| 76 | - 类似 `schema vX is newer than supported vY` 的错误 |
| 77 | |
| 78 | 受影响的存储： |
| 79 | - 会话（`~/.codewhale/sessions/*.json`） |
| 80 | - 运行时线程／回合／条目记录 |
| 81 | - 任务（`~/.codewhale/tasks/tasks/*.json`） |
| 82 | |
| 83 | 处置： |
| 84 | 1. 确认二进制版本与迁移预期 |
| 85 | 2. 在编辑之前备份状态目录 |
| 86 | 3. 二选一： |
| 87 | - 换用更新且兼容的二进制运行，或 |
| 88 | - 归档不兼容的记录并重新生成状态 |
| 89 | |
| 90 | ## 事故：MCP／工具执行失败 |
| 91 | |
| 92 | 检查： |
| 93 | 1. 校验 `~/.codewhale/mcp.json` 的 schema 与服务器命令路径 |
| 94 | 2. 确认服务器进程可以手动启动 |
| 95 | 3. 在 TUI 历史／日志里检查沙箱拒绝 |
| 96 | |
| 97 | 处置： |
| 98 | 1. 带上所需的审批（approval）重试（只在合适时才用 YOLO） |
| 99 | 2. 暂时禁用出问题的 MCP 服务器，把问题隔离开 |
| 100 | 3. 用 `/mcp` 诊断验证之后再重新启用 |
| 101 | |
| 102 | ## 事后清单 |
| 103 | |
| 104 | 1. 保留日志和相关的状态文件 |
| 105 | 2. 记录触发条件、影响与缓解措施 |
| 106 | 3. 增加或更新回归测试（重试／恢复／schema） |
| 107 | 4. 如果行为有变化，就更新本手册和架构文档 |
| 108 |