会话历史与恢复

选择 load、resume、分页 transcript 或导出，并处理恢复超时和游标失效。

This page has not been translated into English yet. The original Chinese version is shown below.

daemon 的实时会话和 SSE 环形缓冲在内存中，持久对话写在磁盘。重启后可以恢复已保存上下文，但不承诺自动重跑未完成任务或重建每个客户端的全部状态。

选择接口

接口	适合用途	capability
POST /session/:id/load	UI 没有历史，恢复并注入当前有限回放快照	session_load
POST /session/:id/resume	UI 已有历史，只恢复 agent 上下文和句柄，不重复 UI 回放	session_resume
GET /session/:id/transcript	读取完整活动磁盘记录的分页回放	session_transcript
GET /workspaces/:workspace/session/:id/transcript	明确工作区的活动记录分页	workspace_persisted_transcript
GET /workspaces/:workspace/session/:id/export	从可信工作区导出完整活动会话附件	workspace_session_export
GET /workspaces/:workspace/session/:id/archive/export	直接导出已归档记录，不取消归档	workspace_archived_session_export

客户端先检查对应 capability。不要仅凭 session_export 或 workspace_qualified_rest_core 推断 secondary 支持导出；旧版本可能只导出 primary。当前 Web Shell 活动会话导出仍为 primary，归档行在能力存在时支持可信 primary/secondary。

load 的快照不是完整 transcript，受 compactedReplay 和当前 liveJournal 限制；缺历史时以 history_truncated 开头。resume 的旧 capability 别名 unstable_session_resume 仅用于兼容。

分页与导出

curl -H "Authorization: Bearer $QWEN_SERVER_TOKEN" \
  "http://127.0.0.1:4170/session/$SESSION_ID/transcript?limit=100"

先把 SESSION_ID 设为目标。分页事件没有实时事件 ID，不会通过这条读取附着客户端、创建 live session 或改变 SSE 窗口。limit 指活动聊天记录数，不是最终回放帧数；一条记录可生成多帧。向后分页为保留轮次和工具调用/结果边界，可扩展到最多 3 倍 limit。

第一页冻结 JSONL 快照大小，之后忽略新追加。hasMore 为 true 时用 nextCursor 继续；文件被删除、截断、替换、归档或与游标冲突则返回 409。过大快照在索引前返回 413 transcript_too_large，避免请求路径无限扫描。

工作区限定的正向页与 cursor 页由 daemon 本地读取；live session 的向后第一页可能通过 ACP 刷新持久尾部。此类游标只在当前 daemon 生命周期有效，重启后从第一页重新开始。

导出支持 html、md、json、jsonl。归档导出不会退回活动存储或 primary，活动但未归档的 ID 返回 409 session_not_archived。

恢复竞争与超时

同一 ID 的同类恢复请求会合并；load 与 resume 竞争，或指定 ID 的创建与恢复竞争，返回 409 restore_in_progress，通常 Retry-After 为 5 秒。

默认恢复期限 60000 毫秒；显式 initialize-timeout-ms 更长时会提高默认恢复预算，不会因更短初始化期限而缩短。SDK 和 Web Shell 分别增加 10 秒与 15 秒客户端余量。

超时返回可重试的 504 session_restore_timeout，不证明 daemon 已退出。未完成 child 请求仍被隔离，清理期间同 ID 重试返回 restore_in_progress、reason 为 awaiting_abandoned_cleanup，Retry-After 按预算限制在 5–120 秒。

清理无法确认或超过额外预算仍未结束时，新会话可能暂时收到 503 acp_channel_unavailable，reason 为 restore_cleanup_failed 或 restore_settlement_overdue。新会话初始化也有对应 new_session_cleanup_failed、new_session_settlement_overdue。已经 live 的会话仍可使用，不应因某次恢复观察超时就重启整个 daemon。

崩溃与读取成本

ACP 子进程崩溃会发 session_died 并移除 live 记录；只要能启动新子进程，磁盘会话仍可 load。daemon 重启丢失正在运行的内存会话和回放环，但不删除持久历史。文件原子写入只保证写入落地方式，不自动重放操作。

旧单数 transcript 路由在 channel-idle-timeout-ms 默认 0 时，空闲 ACP 可能每页后即退出，导致后续页重新启动并扫描快照。连续读取可配置正的 idle grace；容量回收仍可能提前收回 idle child。工作区限定正向/cursor 页避免这条重复 ACP 路径。

官方 Local Deployment 旧段落写“重启只可新建”，应以主章现有 load/resume 和磁盘恢复说明为准。应用级队列、未完成副作用和业务事务仍需由调用方设计恢复。