# CLI 参考手册

默认情况下，所有 Queuety 操作都可通过 WP-CLI 在 `wp queuety` 命名空间下使用。

如果要以不同根命令发布相同的命令树（例如 `wp themequeue`），请在 Queuety 启动之前定义 `QUEUETY_CLI_COMMAND`。

对于代理测试框架和其他 virtual-bash 集成，请将此页面作为人工参考，并使用 PHP 桥接作为机器接口：

- `Queuety::cli_command_map()` 提供可序列化的命令目录
- `Queuety::resolve_cli_command( $path, $args, $assoc_args )` 将解析后的 `wp queuety ...` 输入转换为规范化执行计划，并优先使用直接的 PHP 可调用对象

此命令树中没有状态机命令；请通过 [状态机](https://queuety.inline0.dev/zh/docs/state-machines) 中介绍的 PHP API 检查状态机。

## 作业命令

### `wp queuety work`

启动一个处理作业的工作进程。

```bash
wp queuety work [--queue=<queue>] [--once] [--workers=<n>]
wp queuety work [--queue=<queue>] [--min-workers=<n>] --max-workers=<n>
```

| 选项 | 说明 |
|---|---|
| `--queue=<queue>` | 要处理的 Queue(s)，多个队列以逗号分隔并按优先级排序（默认：`default`） |
| `--once` | 最多处理一个作业后退出（没有可领取的作业时也会立即退出） |
| `--workers=<n>` | 派生 N 个工作进程（需要 `pcntl` 和 `posix` 扩展，`--min-workers` 和 `--max-workers` 也需要） |
| `--min-workers=<n>` | 自适应池的最小工作进程数。需要 `--max-workers` |
| `--max-workers=<n>` | 自适应池的最大工作进程数 |

```bash
# Single worker on default queue
wp queuety work

# Process a specific queue
wp queuety work --queue=emails

# Process multiple queues in priority order
wp queuety work --queue=critical,default,low

# One-shot mode
wp queuety work --once

# Multi-worker mode
wp queuety work --workers=4

# Adaptive worker pool
wp queuety work --queue=providers --min-workers=2 --max-workers=6
```

指定多个队列时，工作进程会按所列顺序尝试从每个队列领取作业。第一个有可用作业的队列会被选中。`--workers` 会保持工作进程池规模固定。`--min-workers` 和 `--max-workers` 会为相同的命令启用自适应扩缩容。有关部署策略，请参阅 [工作进程](https://queuety.inline0.dev/zh/docs/features/workers)；有关自适应池背后的准入模型，请参阅 [资源管理](https://queuety.inline0.dev/zh/docs/features/resource-management)。

### `wp queuety flush`

处理所有待处理的作业后退出。

```bash
wp queuety flush [--queue=<queue>]
```

| 选项 | 说明 |
|---|---|
| `--queue=<queue>` | 要清空的 Queue(s)，多个队列以逗号分隔并按优先级排序（默认：`default`） |

```bash
# Flush a single queue
wp queuety flush --queue=emails

# Flush multiple queues in priority order
wp queuety flush --queue=critical,default,low
```

### `wp queuety dispatch`

从命令行分发作业。

```bash
wp queuety dispatch <handler> [--payload=<json>] [--queue=<queue>] [--priority=<priority>] [--delay=<seconds>]
```

| 选项 | 说明 |
|---|---|
| `<handler>` | 处理器名称或类（必填） |
| `--payload=<json>` | JSON 负载（默认：`{}`） |
| `--queue=<queue>` | 队列名称（默认：`default`） |
| `--priority=<priority>` | 优先级，范围为 0-3（默认：`0`） |
| `--delay=<seconds>` | 延迟秒数（默认：`0`） |

```bash
wp queuety dispatch send_email --payload='{"to":"user@example.com"}' --queue=emails
```

### `wp queuety status`

显示队列统计信息。

```bash
wp queuety status [--queue=<queue>]
```

| 选项 | 说明 |
|---|---|
| `--queue=<queue>` | 按队列名称筛选 |

### `wp queuety list`

列出作业。

```bash
wp queuety list [--queue=<queue>] [--status=<status>] [--format=<format>]
```

| 选项 | 说明 |
|---|---|
| `--queue=<queue>` | 按队列筛选 |
| `--status=<status>` | 按状态筛选（`pending`、`processing`、`completed`、`failed`、`buried`） |
| `--format=<format>` | 输出格式：`table`（默认）、`json`、`csv`、`yaml` |

### `wp queuety inspect`

显示作业的完整详情，包括负载和日志历史记录。

```bash
wp queuety inspect <id>
```

| 选项 | 说明 |
|---|---|
| `<id>` | 作业 ID（必填） |

### `wp queuety retry`

重试指定作业。

```bash
wp queuety retry <id>
```

| 选项 | 说明 |
|---|---|
| `<id>` | 要重试的作业 ID（必填） |

### `wp queuety retry-buried`

重试所有已搁置的作业。

```bash
wp queuety retry-buried
```

### `wp queuety bury`

手动搁置作业。

```bash
wp queuety bury <id>
```

| 选项 | 说明 |
|---|---|
| `<id>` | 要搁置的作业 ID（必填） |

### `wp queuety delete`

删除作业。

```bash
wp queuety delete <id>
```

| 选项 | 说明 |
|---|---|
| `<id>` | 要删除的作业 ID（必填） |

### `wp queuety recover`

恢复卡在 `processing` 状态的过期作业。

```bash
wp queuety recover
```

### `wp queuety purge`

清除已完成的作业。

```bash
wp queuety purge [--older-than=<days>]
```

| 选项 | 说明 |
|---|---|
| `--older-than=<days>` | 删除超过 N 天的作业（默认：`QUEUETY_RETENTION_DAYS`） |

### `wp queuety pause`

暂停队列，使工作器跳过该队列。

```bash
wp queuety pause <queue>
```

| 选项 | 说明 |
|---|---|
| `<queue>` | 要暂停的队列名称（必填） |

### `wp queuety resume`

恢复已暂停的队列。

```bash
wp queuety resume <queue>
```

| 选项 | 说明 |
|---|---|
| `<queue>` | 要恢复的队列名称（必填） |

### `wp queuety metrics`

显示各处理器的指标。

```bash
wp queuety metrics [--minutes=<minutes>] [--format=<format>]
```

| 选项 | 说明 |
|---|---|
| `--minutes=<minutes>` | 时间窗口，单位为分钟（默认：`60`） |
| `--format=<format>` | 输出格式：`table`（默认）、`json`、`csv`、`yaml` |

### `wp queuety discover`

发现目录中的处理器类。

```bash
wp queuety discover <directory> <namespace> [--register]
```

| 选项 | 说明 |
|---|---|
| `<directory>` | 要扫描处理器类的目录（必填） |
| `<namespace>` | 该目录的 PSR-4 命名空间前缀（必填） |
| `--register` | 实际注册发现的处理器 |

## 工作流命令

### `wp queuety workflow status`

显示工作流状态和进度。

```bash
wp queuety workflow status <id>
```

| 选项 | 说明 |
|---|---|
| `<id>` | 工作流 ID（必填） |

`status` 会显示当前步骤、可选的步骤名称、版本/哈希元数据、等待模式、工件摘要；如果工作流当前因信号或依赖项而阻塞，还会显示 `WaitInfo` JSON 数据块。

### `wp queuety workflow list`

列出工作流。

```bash
wp queuety workflow list [--status=<status>] [--format=<format>]
```

| 选项 | 说明 |
|---|---|
| `--status=<status>` | 按状态筛选：`running`、`completed`、`failed`、`paused`、`waiting_for_signal`、`waiting_for_workflows`、`cancelled` |
| `--format=<format>` | 输出格式：`table`（默认）、`json`、`csv`、`yaml` |

该命令最多返回 50 个工作流。它会读取 `--limit` 值，但 WP-CLI 目前会拒绝此标志，因为该命令未声明该标志（[#12](https://github.com/inline0/queuety/issues/12)）；如需使用其他限制值，请使用 `Queuety::list_workflows()`。

默认表格包含 `StepName` 和 `WaitMode`，让你更容易查看受阻的工作流。

### `wp queuety workflow retry`

从失败的步骤重试失败的工作流。

```bash
wp queuety workflow retry <id>
```

| 选项 | 说明 |
|---|---|
| `<id>` | 工作流 ID（必填） |

### `wp queuety workflow approve`

向工作流发送批准信号。

```bash
wp queuety workflow approve <id> [--data=<json>] [--signal=<name>]
```

| 选项 | 说明 |
|---|---|
| `<id>` | 工作流 ID（必填） |
| `--data=<json>` | 可选的 JSON 对象负载 |
| `--signal=<name>` | 覆盖批准信号名称（默认：`approval`，与 `wait_for_approval()` 匹配；`wait_for_decision()` 步骤默认会监听 `approved`，因此请在那里传入 `--signal=approved`） |

### `wp queuety workflow reject`

向工作流发送拒绝信号。

```bash
wp queuety workflow reject <id> [--data=<json>] [--signal=<name>]
```

| 选项 | 说明 |
|---|---|
| `<id>` | 工作流 ID（必填） |
| `--data=<json>` | 可选的 JSON 对象负载 |
| `--signal=<name>` | 覆盖拒绝信号名称（默认：`rejected`） |

### `wp queuety workflow input`

向工作流发送结构化输入。

```bash
wp queuety workflow input <id> [--data=<json>] [--signal=<name>]
```

| 选项 | 说明 |
|---|---|
| `<id>` | 工作流 ID（必填） |
| `--data=<json>` | 可选的 JSON 对象负载 |
| `--signal=<name>` | 覆盖输入信号名称（默认：`input`） |

### `wp queuety workflow artifacts`

列出工作流中存储的工件。

```bash
wp queuety workflow artifacts <id> [--format=<format>] [--with-content]
```

| 选项 | 说明 |
|---|---|
| `<id>` | 工作流 ID（必填） |
| `--format=<format>` | 输出格式：`table`（默认）或 `json` |
| `--with-content` | 在输出中包含工件内容 |

### `wp queuety workflow artifact`

显示工作流中存储的某个工件。

```bash
wp queuety workflow artifact <id> <key>
```

| 选项 | 说明 |
|---|---|
| `<id>` | 工作流 ID（必填） |
| `<key>` | 工件键（必填） |

### `wp queuety workflow pause`

暂停正在运行的工作流。

```bash
wp queuety workflow pause <id>
```

| 选项 | 说明 |
|---|---|
| `<id>` | 工作流 ID（必填） |

### `wp queuety workflow resume`

恢复已暂停的工作流。

```bash
wp queuety workflow resume <id>
```

| 选项 | 说明 |
|---|---|
| `<id>` | 工作流 ID（必填） |

### `wp queuety workflow cancel`

取消尚未处于 `completed` 或 `cancelled` 状态的工作流。Queuety 会在同一事务中将状态设为 `cancelled`，将该工作流待处理和正在处理的作业移入搁置状态，并记录日志 `workflow_cancelled`；随后运行补偿逻辑和任何已注册的清理处理器。

```bash
wp queuety workflow cancel <id>
```

| 选项 | 说明 |
|---|---|
| `<id>` | 要取消的工作流 ID（必填） |

```bash
wp queuety workflow cancel 42
```

### `wp queuety workflow timeline`

显示工作流的事件时间线。展示所有步骤事件（已启动、已完成、已失败），以及时间戳、处理器和持续时间。

```bash
wp queuety workflow timeline <id> [--limit=<limit>] [--offset=<offset>] [--format=<format>]
```

| 选项 | 说明 |
|---|---|
| `<id>` | 工作流 ID（必填） |
| `--limit=<limit>` | 要返回的最大事件数（默认：`100`） |
| `--offset=<offset>` | 要跳过的较早事件数（默认：`0`） |
| `--format=<format>` | 输出格式：`table`（默认）、`json`、`csv`、`yaml` |

```bash
wp queuety workflow timeline 42
```

输出列：`ID`、`Step`、`Event`、`Handler`、`Duration_ms`、`Error`、`Created_at`。

### `wp queuety workflow state-at`

显示特定工作流步骤完成或恢复后的公开工作流状态。

```bash
wp queuety workflow state-at <id> <step>
```

| 选项 | 说明 |
|---|---|
| `<id>` | 工作流 ID（必填） |
| `<step>` | 步骤索引，从 0 开始（必填） |

```bash
wp queuety workflow state-at 42 0
```

有关记录内容和适用场景的详情，请参阅 [工作流事件日志](https://queuety.inline0.dev/zh/docs/workflows/event-log)。

### `wp queuety workflow rewind`

将工作流回退到之前的步骤，并从该步骤之后继续执行。状态会从指定步骤的事件日志 `state_after` 中恢复，并将下一步骤（`<step> + 1`）加入队列；指定步骤本身不会重新运行。

```bash
wp queuety workflow rewind <id> <step>
```

| 选项 | 说明 |
|---|---|
| `<id>` | 工作流 ID（必填） |
| `<step>` | 要回退到的步骤索引，从 0 开始（必填） |

```bash
wp queuety workflow rewind 42 1
```

详情请参阅 [时间旅行](https://queuety.inline0.dev/zh/docs/workflows/time-travel)。

### `wp queuety workflow fork`

将正在运行的工作流分叉为一个基于当前状态的独立副本。分叉后的工作流会获得新的 ID，并独立继续运行。

```bash
wp queuety workflow fork <id>
```

| 选项 | 说明 |
|---|---|
| `<id>` | 要分叉的工作流 ID（必填） |

```bash
wp queuety workflow fork 42
# Success: Workflow #42 forked. New workflow ID: 43.
```

详情请参阅 [分叉](https://queuety.inline0.dev/zh/docs/workflows/forking)。

### `wp queuety workflow export`

将工作流的完整执行历史导出到 JSON。包括工作流行、作业、工作流事件、日志条目、存储的信号以及工作流依赖项等待记录。

```bash
wp queuety workflow export <id> [--output=<file>]
```

| 选项 | 说明 |
|---|---|
| `<id>` | 工作流 ID（必填） |
| `--output=<file>` | 写入 JSON 的文件路径。默认为标准输出。 |

```bash
# Print to stdout
wp queuety workflow export 42

# Write to a file
wp queuety workflow export 42 --output=/tmp/workflow-42.json
```

有关 JSON 结构的详情，请参阅 [导出和重放](https://queuety.inline0.dev/zh/docs/workflows/export-replay)。

### `wp queuety workflow replay`

从 JSON 文件重放已导出的工作流。创建一个具有已导出状态、元数据和历史时间线的新工作流。

```bash
wp queuety workflow replay <file>
```

| 选项 | 说明 |
|---|---|
| `<file>` | 已导出的 JSON 文件路径（必填） |

```bash
wp queuety workflow replay /tmp/workflow-42.json
# Success: Workflow replayed. New workflow ID: 85.
```

详情请参阅 [导出与重放](https://queuety.inline0.dev/zh/docs/workflows/export-replay)。

## 调度命令

### `wp queuety schedule list`

列出所有定期计划。

```bash
wp queuety schedule list [--format=<format>]
```

| 选项 | 说明 |
|---|---|
| `--format=<format>` | 输出格式：`table`（默认）、`json`、`csv`、`yaml` |

### `wp queuety schedule add`

添加定期计划。

```bash
wp queuety schedule add <handler> [--every=<interval>] [--cron=<expression>] [--payload=<json>] [--queue=<queue>]
```

| 选项 | 说明 |
|---|---|
| `<handler>` | 处理器名称或类（必填） |
| `--every=<interval>` | 间隔表达式（e.g、`1 hour`、`30 minutes`） |
| `--cron=<expression>` | Cron 表达式（e.g、`0 3 * * *`） |
| `--payload=<json>` | JSON 负载（默认：`{}`） |
| `--queue=<queue>` | 队列名称（默认：`default`） |

必须指定 `--every` 或 `--cron`。

```bash
wp queuety schedule add cleanup_handler --every="1 hour"
wp queuety schedule add nightly_report --cron="0 3 * * *" --queue=reports
```

### `wp queuety schedule remove`

按处理器名称移除计划。

```bash
wp queuety schedule remove <handler>
```

| 选项 | 说明 |
|---|---|
| `<handler>` | 要移除的处理器名称（必填） |

### `wp queuety schedule run`

手动触发一次调度器运行。为所有到期计划加入作业队列。

```bash
wp queuety schedule run
```

## 日志命令

### `wp queuety log`

查询日志条目。

```bash
wp queuety log [--job=<id>] [--workflow=<id>] [--handler=<name>] [--event=<event>] [--since=<datetime>] [--limit=<n>] [--format=<format>]
```

| 选项 | 说明 |
|---|---|
| `--job=<id>` | 按作业 ID 筛选 |
| `--workflow=<id>` | 按工作流 ID 筛选 |
| `--handler=<name>` | 按处理器名称筛选 |
| `--event=<event>` | 按事件类型筛选（`started`、`completed`、`failed`、`buried`、`retried`、`workflow_started`、`workflow_completed`、`workflow_failed`、`workflow_paused`、`workflow_resumed`、`workflow_cancelled`、`workflow_rewound`、`workflow_forked`、`workflow_deadline_exceeded`、`debug`） |
| `--since=<datetime>` | 显示此日期时间之后的条目 |
| `--limit=<n>` | 要显示的最大条目数（默认值：`50`） |
| `--format=<format>` | 输出格式：`table`（默认）、`json`、`csv`、`yaml` |

筛选条件不会组合：Queuety 会按 `--job`、`--workflow`、`--handler`、`--event`、`--since` 的顺序应用第一个存在的筛选条件。`--job` 和 `--workflow` 会按从最早到最新的顺序返回所有条目，并忽略 `--limit`。`--handler` 和 `--event` 会按从最新到最早的顺序返回条目。不指定筛选条件时，命令会读取过去 24 小时的数据；该查询和 `--since` 都按从最早到最新的顺序列出条目，因此 `--limit` 会保留时间窗口中最早的条目。

```bash
# Logs from the last 24 hours (oldest first)
wp queuety log

# Logs for a job
wp queuety log --job=42

# Failed events
wp queuety log --event=failed --limit=100

# Logs since a specific time
wp queuety log --since="2025-03-01 00:00:00"
```

### 清除日志

`LogCommand` 定义了一个 `purge` 子命令（`wp queuety log purge --older-than=<days>`），但 WP-CLI 将 `wp queuety log` 注册为单个命令，因此无法调用该子命令，并会报错“Too many positional arguments: purge”（[#11](https://github.com/inline0/queuety/issues/11)）。改用 PHP 清除旧日志条目：

```bash
wp eval 'echo Queuety\Queuety::purge_logs( 30 );'
```

## Webhook 命令

### `wp queuety webhook add`

为某个事件注册一个 webhook URL。

```bash
wp queuety webhook add <event> <url>
```

| 选项 | 说明 |
|---|---|
| `<event>` | 事件名称：`job.completed`、`job.failed`、`job.buried` 或 `workflow.failed`（必填） |
| `<url>` | 用于 POST 通知的 URL（必填） |

```bash
wp queuety webhook add job.buried https://hooks.slack.com/services/...
```

### `wp queuety webhook list`

列出所有已注册的 webhook。

```bash
wp queuety webhook list [--format=<format>]
```

| 选项 | 说明 |
|---|---|
| `--format=<format>` | 输出格式：`table`（默认）、`json`、`csv`、`yaml` |

### `wp queuety webhook remove`

按 ID 移除 webhook。

```bash
wp queuety webhook remove <id>
```

| 选项 | 说明 |
|---|---|
| `<id>` | 要移除的 Webhook ID（必填） |