产物管理

Poco 提供两种产物视角：

视角	端点	适用场景
会话产物	`GET /openapi/v1/sessions/{session_id}/artifacts`	获取当前工作区的完整文件树和 ZIP 归档
本轮产物	`GET /openapi/v1/runs/{run_id}/artifacts`	只获取某轮运行新增或修改的文件和 tar.gz 归档

session_id 和 run_id 分别来自对话响应头 X-Session-Id、X-Run-Id。API Key 只能读取所属用户的数据；会话绑定 Key 时，还必须使用创建或绑定该会话的同一 Key，本轮产物遵循所属会话的归属限制。

获取会话产物

curl 'https://<poco-host>/openapi/v1/sessions/<session-uuid>/artifacts' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx'

{
  "session_id": "<session-uuid>",
  "workspace_export_status": "ready",
  "files": [
    {
      "name": "README.md",
      "type": "file",
      "path": "/README.md",
      "url": "https://storage.example.com/preview",
      "downloadUrl": "https://storage.example.com/download"
    }
  ],
  "archive": {
    "url": "https://storage.example.com/workspace.zip",
    "filename": "workspace-<session-uuid>.zip"
  }
}

字段	说明
`workspace_export_status`	工作区导出状态；就绪后才能稳定获取文件和归档
`files`	当前会话工作区的完整文件树
`files[].url`	文件预览地址，可能为空或具有有效期
`files[].downloadUrl`	文件下载地址，可能为空或具有有效期
`archive`	整个工作区的 ZIP 归档信息；未就绪时可能没有可用 URL

预签名地址通常有有效期，不要长期存储 URL；需要下载时重新调用接口。

获取本轮产物

curl 'https://<poco-host>/openapi/v1/runs/<run-uuid>/artifacts' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx'

{
  "session_id": "<session-uuid>",
  "run_id": "<run-uuid>",
  "artifact_status": "ready",
  "file_count": 1,
  "total_size": 1024,
  "files": [
    {
      "name": "report.md",
      "type": "file",
      "path": "/report.md",
      "oss_status": "added",
      "oss_meta": {
        "size": 1024,
        "sha256": "<sha256>"
      }
    }
  ],
  "archive": {
    "url": "https://storage.example.com/run-artifacts.tar.gz",
    "filename": "run-artifacts-<run-uuid>.tar.gz"
  },
  "error": null
}

本轮接口只返回该轮新增或内容发生变化的文件，不包含未被本轮修改的历史文件。归档格式为 .tar.gz，内容与 files 列表对应。

artifact_status 取值：

状态	说明	调用方处理
`pending`	运行中，或运行结束后产物仍在上传	稍后再次查询
`ready`	本轮产物已就绪	读取文件列表或下载归档
`failed`	运行失败、停止或产物采集失败	查看 `error`，不要继续等待 ready
`unavailable`	该运行没有逐轮产物记录	改查会话产物，或确认运行创建时间和配置

如何选择

需要最终完整项目：查询会话产物。
需要判断这一轮改了哪些文件：查询本轮产物。
业务流程只关心“文件已可读取”：订阅 workspace_export.completed 后再查询会话产物。
生成文件时应在提示词中明确文件名和格式，例如“将结果写入 report.md”；仅在消息中返回自然语言不会自动产生工作区文件。

获取会话产物

获取本轮产物

如何选择

On this page