# 工件

工件让你能够存储持久化的工作流输出，而不必增加主工作流状态载荷的大小。

工件适用于草稿文档、提取的 JSON 计划、引文、源清单、生成的文件路径，或你之后想检查的提示和响应快照。这对智能体工作流尤其有用：每次运行可能会生成大量中间输出，但最终状态仍可保持精简、易读。

## 为什么使用工件而不是工作流状态

工作流状态适合存放后续步骤需要立即使用的少量公开数据。

当输出比普通状态值更大、主要供日后检查、适用于审核或导出界面，或者用命名输出而非一个大型状态块来表示更合适时，工件是更好的选择。

## 为当前工作流步骤存储工件

如果代码已在工作流步骤中运行，请使用 `Queuety::put_current_artifact()`：

```php
use Queuety\Queuety;
use Queuety\Step;

final class DraftBriefStep implements Step
{
    public function handle(array $state): array
    {
        $draft = [
            'title' => 'Pricing brief',
            'body' => '...',
        ];

        Queuety::put_current_artifact(
            'draft',
            $draft,
            'json',
            [ 'source' => 'planner' ],
        );

        return [ 'draft_ready' => true ];
    }

    public function config(): array
    {
        return [];
    }
}
```

Queuety 会自动附加当前工作流 ID 和步骤索引。

## 在工作流外部存储工件

如果你已知道工作流 ID，请使用 `Queuety::put_artifact()`：

```php
Queuety::put_artifact(
    $workflow_id,
    'research_brief',
    "# Research Brief\n\nDone.",
    'markdown',
    metadata: [ 'reviewed_by' => 'editor@example.com' ],
);
```

## 读取工件

```php
$artifact = Queuety::workflow_artifact( $workflow_id, 'draft' );

$artifacts = Queuety::workflow_artifacts( $workflow_id );
```

每条工件记录都包含 `key`、`kind`、`content`、`metadata`、`step_index`、`created_at` 和 `updated_at` 字段。除非将 `true` 作为第二个参数传入，否则 `Queuety::workflow_artifacts()` 不会包含 `content`。

## 与工作流状态集成

`Queuety::workflow_status()` 现在包含简要的工件摘要：

```php
$status = Queuety::workflow_status( $workflow_id );

echo $status->artifact_count; // 2
print_r( $status->artifact_keys ); // ['draft', 'citations']
```

这样可以让工件在状态输出中可见，而无需载入其完整内容。

## CLI

列出某个工作流的工件：

```bash
wp queuety workflow artifacts 42
```

显示一个工件及其内容：

```bash
wp queuety workflow artifact 42 draft
```

完整命令参考请参阅 [工件CLI](https://queuety.inline0.dev/zh/docs/cli)。

## 导出和重放

工件会包含在工作流导出内容中，并复制到重放的工作流里。

因此，即使将智能体运行移至其他环境，或根据导出的执行历史重新创建运行，仍可检查其工件内容。