> ## Documentation Index
> Fetch the complete documentation index at: https://www.bazhuayu.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 输出与退出码

> 八爪鱼 CLI 的 JSON / JSONL 输出、stdout / stderr 与退出码，便于脚本、CI 与 Agent 集成。

> 在脚本、Agent、Codex 或 CI 中调用八爪鱼 CLI 时，优先使用结构化输出与退出码判断结果。

CLI 同时支持人类可读终端输出与机器可读 JSON / JSONL。

## JSON 输出（`--json`）

需要单次、完整的结构化响应时使用：

```bash theme={null}
bazhuayu task list --json
bazhuayu task show <taskId> --json
bazhuayu task-group list --json
bazhuayu browser status --browser-id chrome --json
bazhuayu data preview <taskId> --source cloud --limit 20 --json
bazhuayu auth status --json
bazhuayu local status <taskId> --json
bazhuayu detect URL --agent --agent-command "node make-plan.mjs" --goal "提取用户评论" --run-sample 3 --json
bazhuayu detect URL --prepare-agent --json --goal "提取用户评论" --output context.json
bazhuayu detect URL --auto --json --output task.json
```

成功时通常返回 `ok: true` 与 `data` 字段：

```json theme={null}
{
  "ok": true,
  "data": {
    "items": [
      {
        "taskId": "abc123",
        "taskName": "示例任务",
        "status": "Idle"
      }
    ]
  }
}
```

失败时通常返回 `ok: false` 与 `error`。各命令的 `data` 结构不同，编写脚本时请以具体命令输出为准，并容忍新增字段。

### 验证页提前终止

v0.1.32 的 `bazhuayu detect` 会在任务生成前识别验证码、访问限制和安全验证页面。命中时命令以非零退出码结束，JSON 输出为失败 envelope，不应假定存在可运行的 `generatedTask` 或任务文件。自动化流程应先处理验证或访问限制，再重试检测。

v0.1.28 新增的 `task-group`、`template`、`template-task`、`schedule cloud`、`data count` 和 `data preview` 均支持 `--json`。会修改远端状态的命令缺少 `--yes` 时会返回失败 envelope，脚本应把它当作需要人工确认或补齐确认参数处理。

### 用户浏览器状态

`browser status --json` 会返回浏览器安装情况、Profile、扩展状态、`readyForUserBrowserRun` 和 `nextActions`。自动化程序应逐步执行 `nextActions`，并且只在 `readyForUserBrowserRun` 为 `true` 后调用 `browser use user`。

```json theme={null}
{
  "ok": true,
  "data": {
    "supported": true,
    "readyForUserBrowserRun": false,
    "selectedProfileName": "Default",
    "nextActions": [
      {
        "action": "install_extension",
        "command": "bazhuayu browser install --browser-id chrome --profile \"Default\" --json"
      }
    ]
  }
}
```

### Agent 生成与样品采集

`detect --agent --run-sample <n> --json` 仍只输出一个 JSON envelope。其数据可能同时包含 `generatedTask`、`preview`、`agentFiles` 和 `sampleRun`。v0.1.27 起，API 列表任务会在 `generatedTask` 中带上 `mode: "api_list"` 和 `localOnly: true`：

```json theme={null}
{
  "ok": true,
  "data": {
    "generatedTask": {
      "taskId": "example-task",
      "file": "task.json",
      "mode": "api_list",
      "localOnly": true
    },
    "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`。

### 数据计数、预览与未导出数据

`data count` 和 `data preview` 适合在导出前做轻量检查：

```bash theme={null}
bazhuayu data count <taskId> --source cloud --json
bazhuayu data preview <taskId> --source cloud --limit 20 --json
bazhuayu data preview <taskId> --source cloud --unexported --limit 20 --json
```

`--unexported` 只读取云端未导出数据，不会把这些数据标记为已导出。自动化程序若需要维护导出状态，应另行调用对应 OpenAPI 或客户端能力。

## JSONL 事件流（`--jsonl`）

长时间运行或管道处理时使用：

```bash theme={null}
bazhuayu run <taskId> --jsonl
bazhuayu run <taskId> --task-file task.json --jsonl
```

每行一个 JSON 对象，便于流式处理进度：

```jsonl theme={null}
{"event":"run.started","taskId":"abc123","runId":"run-001"}
{"event":"row","taskId":"abc123","total":1,"data":{"title":"示例"}}
{"event":"run.stopped","taskId":"abc123","runId":"run-001","total":1}
```

`event` 字段是稳定判别字段。当前事件包括 `warning`、`billing.warning`、`billing.error`、`run.started`、`row`、`log`、`captcha`、`proxy`、下载事件以及运行暂停、恢复、停止和失败事件；解析时仍应容忍新增事件和未知字段。

## stdout 与 stderr

| 模式                   | stdout | stderr    |
| -------------------- | ------ | --------- |
| 人类可读模式               | 命令结果   | 诊断、警告、错误  |
| `--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 或完整凭据文件。