跑不起来、登录异常或网页识别失败时，先用这些命令排查环境。
octopus doctor（检查运行环境）
doctor 会检查 Node.js、CLI 运行时、浏览器依赖等。若某项为 ok: false，按提示修复后再运行采集任务。
octopus browser doctor（检查浏览器环境）
detect 和本地 run 都依赖可用浏览器环境。若网页无法打开、扩展注册失败或 Chrome 不可用，优先运行此命令。
octopus auth status（查看登录状态）
高频排障
| 现象 | 处理建议 |
|---|---|
octopus 命令找不到 | 检查 Node.js 目录和 npm 全局 bin 是否在 PATH |
中文 --goal 参数异常 | 使用双引号：--goal "提取电影名称、评分" |
| PowerShell 多行命令报错 | 使用反引号 ` 续行，或写成单行 |
| URL 导航失败 | 检查 https://、域名和路径是否完整 |
--output 文件位置不对 | 先切换到工作目录，或传绝对路径 |
octopus recognize 报未知命令 | v0.1.23 已更名为 octopus detect |
--run-sample 报参数错误 | 仅在 detect --agent 中使用，并传入正整数 |
| Agent plan preview 不通过 | 打开上下文中的截图和候选区裁剪图，补全 visualReview，并确保候选 ID 与 selection 一致 |
| Agent 任务已生成但样品采集失败 | 检查 JSON 中的 sampleRun.exitCode、sampleRun.summary 和样品输出目录 |
安装 @latest 卡住 | 使用固定版本：npm install -g bazhuayu-cli@0.1.24 |
下一步
命令速查表
全部常用命令一览。
输出与退出码
在脚本与 CI 中使用
--json / --jsonl。