API 文档

本文档按协议分组说明 Poco 的外部接口：

登录 Token：POST /openapi/v1/auth/token
OpenAI 对话：POST /openapi/v1/chat/completions
Messages 对话：POST /openapi/v1/messages

获取登录 Token

路由端点：POST /openapi/v1/auth/token

该接口通过账号密码、XGT SSO Token 或 API Key 签发 Poco 登录 Token。Token 默认有效期为 24 小时，服务端可通过 OPENAPI_LOGIN_TOKEN_TTL_SECONDS 调低，调用方不能在请求中指定有效期。

账号密码和 API Key 只应由第三方服务端提交，不要写入 Vue、React 等浏览器端代码，也不要放入 URL、日志或持久化页面状态。生产环境应在入口网关对该接口配置 IP 和 API Key 维度的请求频率限制。

账号密码

curl -X POST 'https://<poco-host>/openapi/v1/auth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "password",
    "username": "<账号>",
    "password": "<密码>"
  }'

XGT SSO Token

对于已有的 SSO 回调地址：

https://<poco-host>/zh/login?card=<工号>&token=<鉴权token>&redirect=<目标地址>

第三方服务只需提取其中的 token 参数并提交：

curl -X POST 'https://<poco-host>/openapi/v1/auth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "sso_token",
    "provider": "xgt",
    "sso_token": "<鉴权token>"
  }'

接口不接收也不信任 card。实际账号以 XGT 用户信息接口返回的 data.empNo 为准；用户不存在时，按照系统现有 SSO 默认团队、功能角色和场景配置自动创建。

API Key

curl -X POST 'https://<poco-host>/openapi/v1/auth/token' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"grant_type":"api_key"}'

权限规则：

conversation 范围不能换取登录 Token。
普通用户使用 global 范围，管理员使用 admin 范围。
Token 身份始终是 API Key 所属用户，不能指定或冒充其他用户。
API Key 删除、过期或所属用户被禁用后，不能继续签发新 Token；已经签发的 Token 最多继续有效至自身过期。

成功响应

{
  "access_token": "eyJhbGciOi...",
  "token_type": "bearer",
  "expires_in": 86400
}

该 Token 可用于 Poco 登录鉴权，也可提供给 Agent 外嵌 SDK 的 getAccessToken。接口不签发 Refresh Token，过期后需要重新执行原授权流程。

成功、业务错误和请求校验错误响应均包含以下响应头：

Cache-Control: no-store
Pragma: no-cache

错误响应

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid credentials"
  }
}

HTTP 状态码	说明
`400`	业务请求错误
`401`	账号密码、Token 或 API Key 无效或过期
`403`	用户被禁用或 API Key 范围不足
`422`	请求体字段、授权类型或 SSO Provider 不符合接口约束
`502`	SSO 服务不可用或响应异常

通用行为规则

两个端点都只读取 messages 中的 user 消息。
如果存在多条 user 消息，仅使用最后一条 user 消息作为本次输入。
system/developer/assistant/tool/function 在当前对话链路中会被忽略。
会话复用统一使用 metadata.session_id（可选，UUID）。
stream=true 时返回 SSE；stream=false 时返回 JSON。
实际执行模型由“API 访问”页面中对应密钥的模型配置决定；显式选择的模型固定在保存时的场景中，选择“自动”时跟随账号默认模型。请求体中的 model 保留用于协议兼容和响应回显。

OpenAI 对话

路由端点: /openapi/v1/chat/completions

鉴权

推荐请求头：

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx
content-type: application/json

兼容兜底：

x-api-key: sk-xxxxxxxxxxxxxxxxxxxx

文本对话

请求示例（非流式）：

{
  "model": "gpt-4o",
  "stream": false,
  "messages": [
    { "role": "user", "content": "你好" }
  ]
}

响应示例（非流式）：

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1739529600,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！"
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 10,
    "total_tokens": 30
  }
}

会话复用

基于 session_id 的会话复用.

请求示例：

{
  "model": "gpt-4o",
  "stream": false,
  "messages": [
    { "role": "user", "content": "继续上一轮" }
  ],
  "metadata": {
    "session_id": "<existing-session-uuid>"
  }
}

流式响应（SSE）

stream=true 时返回 text/event-stream
输出为 OpenAI 风格 data: {json}
结束事件：data: [DONE]

片段示例：

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1739529600,"model":"gpt-4o","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1739529600,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":"你"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1739529600,"model":"gpt-4o","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Messages 对话

路由端点: /openapi/v1/messages

鉴权

请求头：

x-api-key: sk-xxxxxxxxxxxxxxxxxxxx
content-type: application/json

会话复用

请求示例：

{
  "model": "poco-agent",
  "stream": false,
  "messages": [
    { "role": "user", "content": "继续这个会话" }
  ],
  "metadata": {
    "session_id": "<existing-session-uuid>"
  }
}

附件上传（图片/文件）

请求示例（图片 + 文件）：

{
  "model": "poco-agent",
  "stream": false,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "请总结这份文档并结合图片给出结论"
        },
        {
          "type": "image",
          "file_name": "screen.png",
          "source": {
            "type": "base64",
            "media_type": "image/png",
            "data": "<BASE64_IMAGE>"
          }
        },
        {
          "type": "file",
          "file_name": "spec.pdf",
          "source": {
            "type": "base64",
            "media_type": "application/pdf",
            "data": "<BASE64_PDF>"
          }
        }
      ]
    }
  ]
}

支持来源：

image：base64、http(s) URL、data-url、attachments/...
file/document：base64、data-url、attachments/...

限制：file/document 暂不支持 http(s) 直链下载。

流式响应（SSE）

stream=true 时返回 text/event-stream
常见事件：message_start、content_block_start、content_block_delta、content_block_stop、message_delta、message_stop、error、ping

片段示例：

event: message_start
data: {"type":"message_start","message":{"id":"msg_xxx","role":"assistant","content":[]}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"你好"}}

event: message_stop
data: {"type":"message_stop","stop_reason":"end_turn"}

会话与运行产物管理

路由端点: /openapi/v1/sessions/...、/openapi/v1/runs/...

鉴权

推荐请求头：

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx
content-type: application/json

兼容兜底：

x-api-key: sk-xxxxxxxxxxxxxxxxxxxx

获取来自外部接口的会话列表

GET /openapi/v1/sessions

查询参数：

limit（可选，默认 100，范围 1-500）
offset（可选，默认 0）

说明：

仅返回当前 API Key 所属用户且 kind=api 的会话。
按 updated_at DESC（其次 created_at DESC）排序。

响应示例：

{
  "items": [
    {
      "session_id": "<session-uuid>",
      "title": "请帮我总结这个仓库",
      "status": "completed",
      "created_at": "2026-02-14T08:30:00Z",
      "updated_at": "2026-02-14T08:31:05Z"
    }
  ],
  "total": 1,
  "limit": 100,
  "offset": 0
}

获取历史记录

GET /openapi/v1/sessions/{session_id}/messages

返回指定会话的历史消息（含每条消息关联的上传附件信息）。

响应示例：

{
  "session_id": "<session-uuid>",
  "messages": [
    {
      "id": 123,
      "role": "user",
      "text_preview": "你好",
      "content": { "_type": "UserMessage", "content": [] },
      "attachments": []
    }
  ]
}

获取会话产物

GET /openapi/v1/sessions/{session_id}/artifacts

返回 workspace 文件树与打包下载链接（如已就绪）。

响应示例：

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

获取本轮产物

GET /openapi/v1/runs/{run_id}/artifacts

返回指定运行本轮新增或修改的文件树，以及本轮产物压缩包下载链接。run_id 可从对话接口响应头 X-Run-Id 获取。

说明：

本接口只返回该轮新增或内容发生变化的文件，不包含工作区中未被本轮修改的历史文件。
archive 为 .tar.gz 格式，包含 files 中列出的全部本轮产物。
历史上未启用逐轮产物采集的运行会返回 artifact_status=unavailable。
API Key 只能读取所属用户的运行产物。

artifact_status 取值：

状态	说明
`pending`	运行中，或运行完成后的产物正在上传
`ready`	本轮产物已就绪
`failed`	运行失败、停止，或产物采集失败
`unavailable`	该运行未启用逐轮产物采集

响应示例：

{
  "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://...",
    "filename": "run-artifacts-<run-uuid>.tar.gz"
  },
  "error": null
}

停止会话

POST /openapi/v1/sessions/{session_id}/stop

停止当前 API Key 所属用户的会话，不需要请求体：

curl -X POST "https://your-domain/openapi/v1/sessions/<session-uuid>/stop" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx"

说明：

API Key 只能停止所属用户的会话；会话不存在返回 404，不属于当前用户返回 403。
首次停止且执行器确认取消后返回 stop_state=stopped；未确认取消时返回 stop_state=stopping，会话状态仍为 stopped。
取消请求进行中，或上次取消未确认后的 5 秒内，并发及频繁请求返回 HTTP 200 和 stop_state=stopping，不会重复请求执行器取消或发送停止 webhook。
5 秒后再次请求会仅重试执行器取消，不会重复修改会话数据或发送停止 webhook；取消已确认后的重复请求返回 stop_state=already_stopped。
已完成或失败的会话返回 HTTP 200 和 stop_state=not_running，不会修改会话状态。

响应示例：

{
  "session_id": "<session-uuid>",
  "status": "stopped",
  "stop_state": "stopped",
  "termination_reason": "user_requested_stop",
  "cancelled_runs": 1,
  "expired_user_input_requests": 0,
  "executor_cancelled": true
}

删除会话

DELETE /openapi/v1/sessions/{session_id}

响应示例：

{
  "id": "<session-uuid>",
  "cleanup": {
    "scheduled": true
  }
}

获取当前 capability_config

GET /openapi/v1/sessions/{session_id}/capability-config

响应示例：

{
  "session_id": "<session-uuid>",
  "capability_config": {
    "browser_enabled": true,
    "browser_impl": "playwright_mcp",
    "mcp_server_ids": [1, 2],
    "skill_ids": [3],
    "plugin_ids": [4],
    "subagent_ids": [5]
  }
}

公开发布页

获取公开发布页列表

GET /api/v1/public/publishes

无需鉴权。返回所有已公开到看板且未删除的发布页列表，时间字段使用北京时间，格式为 YYYY-MM-DD HH:mm:ss。

查询参数：

参数	类型	必填	说明
`account`	string	否	按所属用户账号精确筛选
`category`	string	否	按分类精确筛选
`name`	string	否	按发布页名称模糊搜索

请求示例：

curl "https://api.example.com/api/v1/public/publishes?account=zhangsan&category=炼铁&name=日报"

响应示例：

{
  "code": 0,
  "message": "OK",
  "data": [
    {
      "publish_key": "daily-report",
      "name": "日报发布",
      "description": "每日生产日报",
      "category": "炼铁",
      "latest_published_at": "2026-04-30 18:30:00",
      "version_count": 3,
      "created_at": "2026-04-28 09:00:00",
      "updated_at": "2026-04-30 18:30:00",
      "owner": {
        "account": "zhangsan",
        "name": "张三",
        "department": "生产部"
      }
    }
  ]
}

Office Mode

路由端点: /api/v1/office-mode/...

用于第三方系统读取 Agent 办公室看板、会话详情、运行记录、工作区产物和实时事件流。

鉴权

请求头：

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx
content-type: application/json

说明：

管理员需要先登录平台，在 /zh/capabilities/api-access 新增秘钥，并将生效范围设置为“管理后台”（admin scope）。
Office Mode 所有接口只接受 Authorization: Bearer <api_key> 认证，不使用 x-api-key。
API Key 必须是 admin scope，且创建者仍为管理员；conversation 或 global scope API Key 无法访问。
管理员可读取办公室快照、会话详情、运行记录、工作区文件和事件流。

获取办公室快照

GET /api/v1/office-mode/snapshot

查询参数：

参数	类型	必填	默认值	说明
`limit`	number	否	`72`	返回运行实体数量，范围 `1-96`
`tz`	string	否	`Asia/Shanghai`	统计今日数据时使用的时区

请求示例：

curl "https://api.example.com/api/v1/office-mode/snapshot?limit=72&tz=Asia%2FShanghai" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx"

响应示例：

{
  "code": 0,
  "message": "Agent office snapshot retrieved successfully",
  "data": {
    "generated_at": "2026-06-04T06:10:00Z",
    "overview": {
      "total": 12,
      "running": 2,
      "pending": 1,
      "failed": 1,
      "completed": 8,
      "idle": 0,
      "visible_conversations": 12,
      "total_cost_usd": 1.23,
      "total_tokens": 45678
    },
    "permissions": {
      "allow_other_conversations": false,
      "conversation_access_label": "self_or_admin"
    },
    "teams": [
      {
        "id": "team-1",
        "name": "技术组",
        "budget_amount_usd": 100,
        "today_active": 3,
        "scheduled_task_count": 4,
        "today_cost_usd": 0.56,
        "today_total_tokens": 12345,
        "created_at": "2026-06-01T02:00:00Z",
        "updated_at": "2026-06-04T06:00:00Z"
      },
      {
        "id": "__unassigned__",
        "name": "未分配",
        "budget_amount_usd": null,
        "today_active": 1,
        "scheduled_task_count": 0,
        "today_cost_usd": 0.08,
        "today_total_tokens": 2345,
        "created_at": "2026-06-04T06:10:00Z",
        "updated_at": "2026-06-04T06:10:00Z"
      }
    ],
    "entities": [
      {
        "id": "<run-uuid>",
        "kind": "session-run",
        "title": "生成日报",
        "subtitle": "张三",
        "status": "running",
        "meta": "运行中",
        "progress": 65,
        "detail": null,
        "team_id": "team-1",
        "team_name": "技术组",
        "run_id": "<run-uuid>",
        "session_id": "<session-uuid>",
        "session_title": "生成日报",
        "user_id": "<user-id>",
        "username": "zhangsan",
        "full_name": "张三",
        "started_at": "2026-06-04T06:00:00Z",
        "finished_at": null,
        "updated_at": "2026-06-04T06:10:00Z",
        "elapsed_seconds": 600,
        "last_error": null,
        "total_cost_usd": 0.12,
        "total_tokens": 3456,
        "message_count": 8,
        "artifact_count": 2,
        "can_view_conversation": true,
        "conversation_access_mode": "admin_readonly"
      }
    ],
    "recent_sessions": [
      {
        "id": "<session-uuid>",
        "session_id": "<session-uuid>",
        "run_id": "<run-uuid>",
        "user_id": "<user-id>",
        "username": "zhangsan",
        "full_name": "张三",
        "team_id": "team-1",
        "team_name": "技术组",
        "title": "生成日报",
        "session_title": "生成日报",
        "status": "completed",
        "updated_at": "2026-06-04T05:55:00Z",
        "can_view_conversation": true,
        "conversation_access_mode": "admin_readonly"
      }
    ]
  }
}

团队统计说明：

teams 会返回数据库中的真实团队，并在需要时追加虚拟团队 {"id": "__unassigned__", "name": "未分配"}。
“未分配”只在今日存在未分配活跃用量，或当前存在未分配实时运行实体时出现；该实时运行判断不受本次快照展示 limit 限制，仅存在未分配定时任务数量不会单独显示该虚拟团队。
未分配归属口径为：usage_logs.team_id_snapshot、agent_runs.team_id_snapshot、users.team_id 都为空时归入 __unassigned__。
Office Mode 前端 HUD 弹窗顶部的“今日活跃 / 定时 / 今日 Tokens”直接读取 snapshot.teams 中对应团队的统计字段，不使用 /today-active-runs 结果做兜底；/today-active-runs 仅用于弹窗内今日活跃任务列表和分页。

获取团队今日活跃运行列表

GET /api/v1/office-mode/teams/{team_id}/today-active-runs

按团队查询今日活跃运行任务列表，支持页码分页。不传 source_type 时，该接口的 total 与办公室快照中 teams[].today_active 使用同一套团队归属与计数口径（今日内出现过用量的不同会话数；查询未分配团队时，还包含当前 live 且今日尚无未分配用量的会话）；传入 source_type 时，会在同一口径上额外按运行来源过滤。item_total 表示可展开为任务列表行的会话数，分页相关的 has_more 与 next_page 基于 item_total 计算。

列表从今日 usage_logs 反查关联的 agent_runs，因此已完成但今天产生用量的运行也会返回。
团队归属优先级与快照一致：usage_logs.team_id_snapshot -> agent_runs.team_id_snapshot -> users.team_id -> __unassigned__。
查询未分配团队时，路径参数 team_id 传 __unassigned__。
查询未分配团队时，当前 live 且今日尚无未分配用量的运行会排在今日用量反查出的运行之前；传入 source_type 时，仅按同一运行来源判断是否已有用量，避免快照顶部计数与弹窗列表不一致。
只有能关联到 run_id 的用量记录会出现在任务列表；无 run_id 的用量仍可能计入 today_active 与 total（按会话计），但无法展开为任务行，也不会计入 item_total。
total 与快照接口的团队统计都会包含今日产生过用量的软删除会话；能关联到 run_id 的软删除会话仍会出现在任务列表与 item_total 中，并通过 is_deleted 标识，便于对今日已产生成本/用量的历史任务进行审计。
列表项中的 total_cost_usd 与 total_tokens 是该会话今日内的用量聚合，不包含今日之前的历史用量。

路径参数：

参数	类型	必填	说明
`team_id`	string	是	团队 ID；未分配团队使用 `__unassigned__`

查询参数：

参数	类型	必填	默认值	说明
`limit`	number	否	`10`	每页数量，范围 `1-50`
`page`	number	否	`1`	页码，从 `1` 开始
`source_type`	string	否	-	运行来源过滤；可选 `normal_session` 或 `scheduled_task`，不传则返回全部
`tz`	string	否	`Asia/Shanghai`	统计今日数据时使用的时区

请求示例：

curl "https://api.example.com/api/v1/office-mode/teams/team-1/today-active-runs?limit=10&page=1" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx"

响应示例：

{
  "code": 0,
  "message": "Agent office team today active runs retrieved successfully",
  "data": {
    "team_id": "team-1",
    "generated_at": "2026-06-08T08:10:00Z",
    "items": [
      {
        "id": "<session-uuid>:<run-uuid>",
        "kind": "session-run",
        "title": "生成日报",
        "subtitle": "技术组",
        "status": "running",
        "is_deleted": false,
        "meta": "实时任务",
        "progress": 65,
        "detail": "请生成今日日报",
        "team_id": "team-1",
        "team_name": "技术组",
        "source_type": "scheduled_task",
        "run_id": "<run-uuid>",
        "scheduled_task_id": "<scheduled-task-uuid>",
        "scheduled_task_step_id": "<scheduled-task-step-uuid>",
        "session_id": "<session-uuid>",
        "session_title": "生成日报",
        "user_id": "<user-id>",
        "username": "zhangsan",
        "full_name": "张三",
        "started_at": "2026-06-08T08:00:00Z",
        "finished_at": null,
        "updated_at": "2026-06-08T08:10:00Z",
        "elapsed_seconds": 600,
        "last_error": null,
        "total_cost_usd": 0.12,
        "total_tokens": 3456,
        "message_count": 8,
        "artifact_count": 0,
        "can_view_conversation": true,
        "conversation_access_mode": "admin_readonly"
      }
    ],
    "total": 23,
    "item_total": 20,
    "limit": 10,
    "page": 1,
    "has_more": true,
    "next_page": 2
  }
}

获取会话详情

GET /api/v1/office-mode/sessions/{session_id}/detail

返回会话聚合详情，包含会话成本、Token、消息摘要和运行摘要。

响应示例：

{
  "code": 0,
  "message": "Agent office session detail retrieved successfully",
  "data": {
    "session_id": "<session-uuid>",
    "session_title": "生成日报",
    "session_status": "completed",
    "total_cost_usd": 0.24,
    "total_tokens": 6789,
    "message_count": 12,
    "artifact_count": 3,
    "messages": [
      {
        "id": 101,
        "role": "user",
        "text_preview": "请生成今日日报",
        "created_at": "2026-06-04T05:00:00Z"
      }
    ],
    "runs": [
      {
        "run_id": "<run-uuid>",
        "status": "completed",
        "progress": 100,
        "started_at": "2026-06-04T05:00:10Z",
        "finished_at": "2026-06-04T05:10:00Z",
        "elapsed_seconds": 590,
        "total_cost_usd": 0.24
      }
    ]
  }
}

会话只读接口

接口	说明
`GET /api/v1/office-mode/sessions/{session_id}`	获取会话基础信息，包含当前运行状态和最近失败错误
`GET /api/v1/office-mode/sessions/{session_id}/messages-with-files`	获取会话消息和关联附件
`GET /api/v1/office-mode/sessions/{session_id}/summary`	获取会话摘要
`GET /api/v1/office-mode/sessions/{session_id}/stream-events`	分页获取会话事件
`GET /api/v1/office-mode/office-runs/session/{session_id}`	获取会话运行列表
`GET /api/v1/office-mode/sessions/{session_id}/run-rounds`	获取会话运行轮次
`GET /api/v1/office-mode/sessions/{session_id}/context-usage`	获取会话上下文用量
`GET /api/v1/office-mode/sessions/{session_id}/computer/browser/{tool_use_id}`	获取浏览器截图预签名访问地址

常用查询参数：

messages-with-files：limit（默认 200，范围 1-200）、before_id（可选）
stream-events：after_id（默认 0）、before_id（可选）、run_id（可选）、from_stream_seq（可选，必须与 run_id 一起使用）、limit（默认 500，范围 1-500）、order（默认 asc，可选 asc/desc）
office-runs/session/{session_id}：limit（默认 100，范围 1-500）、offset（默认 0）
run-rounds：limit（默认 100，范围 1-500）、offset（默认 0）
computer/browser/{tool_use_id}：tool_use_id 只允许字母、数字、下划线和短横线

获取工作区文件树

GET /api/v1/office-mode/sessions/{session_id}/workspace/files

返回 workspace 文件树。文件节点会包含预签名的预览地址和下载地址；如果导出未就绪，返回空数组。

响应示例：

{
  "code": 0,
  "message": "Agent office workspace files retrieved successfully",
  "data": [
    {
      "id": "/README.md",
      "name": "README.md",
      "type": "file",
      "path": "/README.md",
      "children": null,
      "url": "https://storage.example.com/preview-url",
      "downloadUrl": "https://storage.example.com/download-url",
      "mimeType": "text/markdown"
    }
  ]
}

获取工作区归档下载地址

GET /api/v1/office-mode/sessions/{session_id}/workspace/archive

返回 workspace zip 包下载地址。如果导出未就绪，url 为 null。

响应示例：

{
  "code": 0,
  "message": "Agent office workspace archive URL generated",
  "data": {
    "url": "https://storage.example.com/workspace.zip",
    "filename": "workspace-<session-uuid>.zip"
  }
}

未就绪示例：

{
  "code": 0,
  "message": "Agent office workspace export not ready",
  "data": {
    "url": null,
    "filename": "workspace-<session-uuid>.zip"
  }
}

会话事件流（SSE）

会话级事件流

GET /api/v1/office-mode/sessions/{session_id}/stream

查询参数：

参数	类型	必填	默认值	说明
`after_id`	number	否	`0`	只读取大于该 ID 的事件
`replay`	boolean	否	`false`	是否从当前 `after_id` 回放历史事件

也可通过请求头 Last-Event-ID 续接事件流。

指定运行事件流

GET /api/v1/office-mode/sessions/{session_id}/run-events/stream

查询参数：

参数	类型	必填	默认值	说明
`run_id`	UUID	是	-	只订阅指定 run 的事件
`after_id`	number	否	`0`	只读取大于该 ID 的事件

片段示例：

id: 128
event: content_block_delta
data: {"id":128,"type":"content_block_delta","session_id":"<session-uuid>","run_id":"<run-uuid>","stream_seq":12,"payload":{"text":"你好"}}

: heartbeat

说明：

两个 SSE 端点都返回 text/event-stream。
空闲时会返回 : heartbeat 保持连接。
after_id=0 且未开启会话级 replay 时，从当前最新事件之后开始订阅。
同一 run 的高频流事件带有递增的 stream_seq。自定义客户端应按连续序号处理；发现缺口时，可调用 stream-events 并传入 run_id 与缺失位置的 from_stream_seq 补拉。

通用错误响应

chat/completions：

{
  "error": {
    "message": "错误描述",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}

messages / sessions/*：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "错误描述"
  }
}

常见错误类型：

authentication_error（401）
invalid_request_error（400/413）
permission_error（403）
not_found_error（404）
timeout_error（504）
api_error（500）

On this page