Sessions API

GET /api/sessions

前端用于：

• 获取会话列表
• 在 Auto 模式下推导当前默认 session
• 补充 status 和 last_task_id

关键字段

{
  "id": "session-uuid",
  "status": "idle",
  "last_task_id": "task-uuid"
}

鉴权

默认需要登录。服务在 --disable-auth 模式下会返回全部 session 记录；开启鉴权时只返回当前用户可见的 session。

POST /api/sessions

用于主动创建会话，常见于：

• 会话页手动新建
• 预先创建 profile/session 绑定

典型返回结构：

{
  "success": true,
  "session": {
    "id": "session-uuid",
    "status": "idle",
    "live_path": "/api/sessions/session-uuid/live"
  }
}

常见用途

• 会话页手动新建
• 聊天页先建空 session 再绑定任务
• 预先建立 profile / label 对应的运行上下文

GET /api/sessions/:id

前端右侧运行态的核心恢复接口。

前端最依赖的字段

{
  "snapshot": {
    "session": {},
    "last_frame": {},
    "overlays": []
  }
}

约束

• 只要 snapshot.last_frame 和 snapshot.overlays 已经有数据，右侧就应该能恢复出实时画面和步骤
• 如果页面空白但这里有数据，优先检查前端 session 绑定逻辑

常见字段

• snapshot.session
• snapshot.last_frame
• snapshot.overlays
• snapshot.route_summary

常见错误

状态码	场景
401	需要鉴权但未登录
404	session 不存在或对当前用户不可见

GET /api/sessions/:id/live

会话实时流入口，主要用于：

• 订阅会话 live event
• 在不重新拉全量 snapshot 的情况下增量更新

联调建议

• 右侧运行态恢复优先看 GET /api/sessions/:id，/live 是增量补链，不是首个真相源。
• 如果 session detail 已经有 last_frame 和 overlays，但页面仍然空白，优先检查前端绑定逻辑而不是 live 流本身。

POST /api/sessions/:id/share

为当前 session 创建分享上下文。

DELETE /api/sessions/:id/share

撤销 session 分享上下文。

POST /api/sessions/:id/pointer

更新 session 当前路由指针，常见于手动接管、页面聚焦或浏览器路由同步。