跳转到主要内容
在脚本、Agent、Codex 或 CI 中调用八爪鱼 CLI 时，优先使用结构化输出与退出码判断结果。
CLI 同时支持人类可读终端输出与机器可读 JSON / JSONL。

​
JSON 输出（--json）

需要单次、完整的结构化响应时使用： 
octopus task list --json
octopus auth status --json
octopus local status <taskId> --json
octopus detect URL --agent --agent-command "node make-plan.mjs" --goal "提取用户评论" --yes --run-sample 3 --json
octopus detect URL --prepare-agent --json --goal "提取用户评论" --output context.json
octopus detect URL --auto --json --output task.json
成功时通常返回 ok: true 与 data 字段： 
{
  "ok": true,
  "data": {
    "items": [
      {
        "taskId": "abc123",
        "taskName": "示例任务",
        "status": "Idle"
      }
    ]
  }
}
失败时通常返回 ok: false 与 error。各命令的 data 结构不同，编写脚本时请以具体命令输出为准，并容忍新增字段。

​
Agent 生成与样品采集

detect --agent --run-sample <n> --json 仍只输出一个 JSON envelope。其数据可能同时包含 generatedTask、preview、agentFiles 和 sampleRun： 
{
  "ok": true,
  "data": {
    "generatedTask": {
      "taskId": "example-task",
      "file": "task.json"
    },
    "sampleRun": {
      "requestedRows": 3,
      "exitCode": 1,
      "envelope": {
        "ok": false,
        "error": {
          "code": "RUN_FAILED"
        }
      },
      "summary": {
        "sampledRows": [],
        "fieldFillRates": {},
        "missingFieldsByRow": [],
        "judgment": "sample run failed"
      }
    }
  }
}
样品采集失败不会自动把顶层任务生成判为失败。自动化程序必须分别检查顶层 ok 与 sampleRun.exitCode；需要判断数据质量时，再读取 sampleRun.summary。

​
JSONL 事件流（--jsonl）

长时间运行或管道处理时使用： 
octopus run <taskId> --jsonl
octopus run <taskId> --task-file task.json --jsonl
每行一个 JSON 对象，便于流式处理进度： 
{"type":"run.started","taskId":"abc123","timestamp":"2026-01-01T10:00:00.000Z"}
{"type":"row.saved","taskId":"abc123","count":1}
{"type":"run.completed","taskId":"abc123","savedRows":1}
事件字段可能随版本调整，解析时请容忍未知字段。

​
stdout 与 stderr

模式stdoutstderr
人类可读模式命令结果诊断、警告、错误
--json / --jsonl结构化数据仍可能输出诊断信息
管道处理时建议只解析 stdout 中的业务数据，单独保留 stderr 便于排错。

​
退出码

退出码含义常见原因
0成功命令按预期完成
1操作失败认证失败、任务不存在、导出错误等
2运行环境失败Node 版本不符、Chrome 不可用、引擎初始化失败
3任务定义不支持使用内核浏览器或 Legacy 工作流（CLI v1 不支持）
非零退出码表示自动化步骤应视为失败。

​
自动化建议

  • 单次查询、识别上下文、状态检查使用 --json。
  • Agent 生成任务并试采时，同时检查顶层 ok 与 sampleRun.exitCode。
  • 长时间本地运行使用 --jsonl 跟踪进度。
  • 在 CI 中根据退出码判断步骤成败。
  • 单独收集 stderr 便于排查。
  • 切勿在日志中打印 API Key、Access Token 或完整凭据文件。