工件

以 Markdown 格式查看在 GitHub 上编辑文档位置 2cc7b2b

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

工件适用于草稿文档、提取的 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

列出某个工作流的工件：

命令行

wp queuety workflow artifacts 42

显示一个工件及其内容：

命令行

wp queuety workflow artifact 42 draft

完整命令参考请参阅工件CLI。

导出和重放

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

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