# 交互状态持久化与后续设计

整理日期：2026-11-10。本文只维护已实现的状态边界和仍有效的后续工作。2026 年 10 月原提案保存于 [历史设计](history/agent-interaction-state-proposal-2026-10.md)，其中分析篮、行选择和组件追问已取消，不再作为实施目标。组件内容与交互入口见 [本地交互式回答](agent-answer-ui.md)。

## 当前能力

| 范围 | 状态 | 边界 |
| --- | --- | --- |
| 聊天图表、表格、表单和证据控件状态 | 已实现 | 按用户、会话和内容身份保存；包含版本比较、失败重试和冲突处理 |
| 宿主 `ask_user` 请求、草稿、答案和续跑投递 | 已实现 | 使用独立请求与投递记录；历史原生 question 仍需核对当前原生请求是否有效 |
| 阅读位置 reader | 待实施 | 当前页面的阅读状态不等于刷新后的持久记录 |
| 正式报告私人状态 | 待实施 | 需要按读者、任务及报告版本独立保存，不借用报告发布会话 |
| 分析篮、行勾选、组件追问 | 已取消 | 不恢复旧 basket 协议或为其新增存储 |

## 聊天控件状态

控件状态与回答内容分别保存。内容由消息或报告持有，状态仅改变当前读者的本地浏览方式；恢复不能发送消息、提交表单、调用业务工具、定位地图或自动打开窗口。

状态身份需要保持会话、block 和内容版本边界。同块数据更新时清理已经失效的选择；迟到的恢复结果不能覆盖用户的新输入。失败保存保留内存交互并明确提示未保存，冲突需显式处理，不静默覆盖其他窗口的新版本。

当前实现入口：

- [前端状态同步](../src/features/agent/session-state/answer-view-state-scope.ts) 与 [原生回答组件](../src/features/agent/answer-ui/answer-ui-view.tsx)。
- [Agent 状态路由](../../next-tjwater-agent/src/routes/answer-view-state-routes.ts) 与 [状态存储](../../next-tjwater-agent/src/sessions/answer-view-state-store.ts)。
- [会话归属与存储](../../next-tjwater-agent/docs/user-isolation.md)，负责授权、删除及持久目录边界。

## 宿主提问与回复

聊天及人工任务协作通过宿主 `ask_user` 保存等待状态。问题定义、表单草稿、已提交答案和续跑投递是不同记录；工具和浏览器不能自行指定所有者、项目或目标会话。后台调查的任务提问由 Server 管理，见 [工况任务契约](../../next-tjwater-server/docs/operational-tasks.md)，不以浏览器存活为条件。

```text
模型 ask_user → 可信工具桥 → 宿主保存请求 → 显示问题卡，等待回答
用户提交 → 保存答案与投递记录 → 运行协调器 → 原会话续跑
                               ↑ 固定消息 ID 核对投递状态
```

浏览器通过 `/api/v1/session/:session_id/interactions` 读取请求，按 `interaction_id` 保存草稿并执行 `reply`、`skip`、`cancel` 或 `resume`。独立列表用于恢复问题；不能据此认定所有历史请求已经嵌入会话详情的分页投影。

保存答案成功与推理继续成功分开反馈。投递结果不明时核对固定原生消息 ID，不生成新 ID 重复注入。宿主恢复需要有效用户上下文，不持久保存 Bearer，也不悄悄创建新会话重放业务过程。旧 question 卡片能显示，不代表原生请求仍可回答。

实现入口为 [请求路由](../../next-tjwater-agent/src/routes/interaction-request-routes.ts)、[请求存储](../../next-tjwater-agent/src/sessions/interaction-request-store.ts) 与 [投递核对](../../next-tjwater-agent/src/sessions/interaction-delivery-reconciliation.ts)。原始字段设计、故障假设和当时的验证边界见历史设计第 11 节；“拟新增”和“尚未验证”仅反映提案阶段，不能替代当前代码核对。

## 后续阅读位置与正式报告状态

阅读位置应与高频控件和表单保存分开，使用内容身份和稳定锚点；数据变化或章节不存在时回退到有效位置。恢复位置不抢夺用户操作，不产生地图或业务副作用。

正式报告私人状态应绑定当前读者、项目、任务和报告版本，并在每次读写时检查当前读取权限。`source_session_id` 是报告的发布会话，不能作为读者授权或私人状态存储身份。该能力需要 Server API 与项目 BizDB 表及逐项目迁移，尚无可直接调用的已交付接口。

历史提案中的接口草案和容量数值仍是设计参考；实施前重新核对当前契约，不提前对外宣布可用。无需为已经取消的分析篮新增表、记录或权限。

## 验证与交付

前端与 Agent 的检查命令统一见 [回答 UI 验证](agent-answer-ui.md#验证)。重点覆盖刷新恢复、同块数据更新、两窗口冲突、保存失败、会话切换后迟到响应、删除后的迟到写入、问题提交与续跑结果不明，以及窄屏和键盘操作。

模拟 HTTP、浏览器交互、隔离原生投递验证、真实模型完整续跑和部署验收分别记录。此轮文档整理不重新执行推理、迁移或发布，也不将历史检查更新为当前验收结论。