Office Mode

使用管理员 API Key 读取 Agent 办公室快照、团队运行、会话详情、工作区文件和实时事件。

Office Mode API 面向管理看板或审计系统，提供跨团队的运行状态、成本、Token、消息摘要、工作区文件和实时事件。

鉴权与权限

所有端点位于 /api/v1/office-mode/*，只接受：

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx

API Key 必须在“API 访问”页面创建，scope 设为 admin，且创建者当前仍是管理员。conversation 或 global scope 不能访问这些接口，Office Mode 也不接受 x-api-key。

普通管理员仍受内容隐私限制，不能读取其他用户已开启内容隐私的会话；超级管理员按对应读取权限处理。外嵌会话不属于这些会话读取接口的范围。

获取办公室快照

端点：GET /api/v1/office-mode/snapshot

查询参数	类型	默认值	范围	说明
`limit`	integer	`72`	`1-96`	返回多少个运行实体
`tz`	string	`Asia/Shanghai`	IANA 时区	统计“今日”时使用的时区

curl 'https://<poco-host>/api/v1/office-mode/snapshot?limit=72&tz=Asia%2FShanghai' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx'

响应 data 的结构：

字段	说明
`generated_at`	快照生成时间
`overview`	当前 limit 内可见 entities 的运行、状态、会话、成本和 Token 汇总
`permissions`	当前调用方的会话读取权限说明
`teams`	各团队今日活跃、定时任务、成本和 Token 统计
`entities`	当前展示的会话运行实体
`recent_sessions`	最近会话摘要

{
  "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
      }
    ],
    "entities": [
      {
        "id": "<run-uuid>",
        "kind": "session-run",
        "title": "生成日报",
        "status": "running",
        "progress": 65,
        "team_id": "team-1",
        "run_id": "<run-uuid>",
        "session_id": "<session-uuid>",
        "username": "zhangsan",
        "total_cost_usd": 0.12,
        "total_tokens": 3456,
        "can_view_conversation": true,
        "conversation_access_mode": "admin_readonly"
      }
    ],
    "recent_sessions": []
  }
}

未分配团队口径

需要时 teams 会追加虚拟团队：

{ "id": "__unassigned__", "name": "未分配" }

它只在今日存在未分配活跃用量，或当前存在未分配实时运行时出现。归属判断依次使用 usage_logs.team_id_snapshot、agent_runs.team_id_snapshot、users.team_id；三者都为空时归入 __unassigned__。

snapshot.teams[].today_active 是团队今日活跃统计的权威值。团队运行列表用于展开任务明细，不应反向覆盖该统计。

获取团队今日活跃运行

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

未分配团队的 team_id 使用 __unassigned__。

查询参数	类型	默认值	说明
`limit`	integer	`10`	每页数量，范围 `1-50`
`page`	integer	`1`	页码，从 1 开始
`source_type`	string	不传	`normal_session` 或 `scheduled_task`
`tz`	string	`Asia/Shanghai`	统计今日数据的时区

curl 'https://<poco-host>/api/v1/office-mode/teams/team-1/today-active-runs?limit=10&page=1' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx'

响应中的分页字段：

字段	说明
`total`	今日活跃会话数；不传 `source_type` 时与快照的 `today_active` 口径一致
`item_total`	实际能展开为任务列表行的会话数
`has_more`	是否还有下一页，基于 `item_total` 计算
`next_page`	下一页页码；没有下一页时为空

无 run_id 的用量仍可能计入 total，但不能生成列表行，因此 total 可能大于 item_total。软删除但今日产生过用量的会话仍可能出现，并通过 is_deleted 标识。

列表项的 total_cost_usd 和 total_tokens 只统计该会话今天的用量，不是会话历史累计值。

获取会话聚合详情

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

返回会话成本、Token、最多 80 条消息摘要和最近 20 个运行摘要。完整历史请使用分页只读接口：

{
  "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、before_id、run_id、from_stream_seq、limit 和 order；from_stream_seq 必须与 run_id 一起使用。
office-runs 和 run-rounds：limit 默认 100、范围 1-500，offset 默认 0。
office-runs 可传 include_inherited，默认 false，决定是否包含分支继承运行。
浏览器截图的 tool_use_id 只允许字母、数字、下划线和短横线。

工作区文件

文件树：GET /api/v1/office-mode/sessions/{session_id}/workspace/files

导出未就绪时返回空数组。文件节点包含路径、MIME 类型，以及可能有有效期的预览和下载地址：

{
  "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

导出未就绪时仍返回成功响应，但 data.url 为 null：

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

实时事件流

会话级事件流

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

查询参数：after_id 默认 0，replay 默认 false。也可通过 Last-Event-ID 请求头续接。

指定运行事件流

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

必须传 run_id，可选 after_id。

id: 128
event: chat.stream.content_block_delta
data: {"id":128,"type":"chat.stream.content_block_delta","session_id":"<session-uuid>","run_id":"<run-uuid>","stream_seq":12,"payload":{"event":{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"你好"}}}}

: heartbeat

两个端点都返回 text/event-stream，空闲时发送 : heartbeat。会话级在 after_id=0 且 replay=false 时、运行级在 after_id=0 时，从连接时最新事件之后订阅。两者均支持 Last-Event-ID，与 query 的 after_id 取较大值。Office 保留原始事件封装，内容位于 payload.event，不能按 Messages SSE 直接解包。

同一运行的高频事件带有递增 stream_seq。如果客户端发现序号缺口，可调用 stream-events，同时传 run_id 和缺失位置的 from_stream_seq 补拉。

On this page