feat: expand intelligent investigation workspace

docs/agent-answer-ui.md

@@ -2,6 +2,48 @@
 
 统一样式见 [样式设计指南](style-design-guide.md)，聊天布局与报告交互见 [Agent 交互与报告设计](agent-chat-ui-design.md)。本文保留协议、组件参数与业务交互约定。
 
+## 实施进度（2026-10-30 更新）
+
+原生组件版的主要界面与交互状态保存已实现，已完成本地自动化验证；真实授权项目联调和发布尚待完成。下表的“已实现”指当前工作区代码，不代表运行服务已同步更新。相关改动仍未提交、未部署。
+
+| 能力 | 状态 | 已有范围与剩余边界 |
+| --- | --- | --- |
+| Agent 内容组织 | 已实现 | shadcn/ui 原生组件、内容分区、导航、指标与证据展示；沿用现有对话和工具执行通道 |
+| 任务语义与结果表达 | 2026-10-28 已接入工作区 | `Result`、回答用途、分区角色、疏密及具体说明标题；Agent 选择表达语义，宿主统一视觉与动作边界，真实模型联调待完成 |
+| 表格与图表 | 已实现 | 搜索、排序、折线/柱状/数据表切换、区间选择和序列显隐；只处理已加载数据 |
+| 报告与 Markdown 阅读 | 已实现 | 表格完整内容可横纵滚动；报告与 Mermaid 有界放大、暗色遮罩、图标按钮、焦点恢复及减少动态效果适配 |
+| 定位与资料补充 | 已实现 | 保留专用地图定位和补充资料表单；数据组件不提供勾选、分析篮或组件追问 |
+| 交互状态持久化（A） | 核心已实现 | 图表、表格、表单与证据状态按会话保存；支持刷新恢复、兼容迁移、失败重试和显式冲突处理 |
+| 阅读位置持久化 | 设计待实施 | reader 记录尚未保存到宿主；分析篮已按产品决定移除，旧 basket 设计不再作为实施目标 |
+| 提问与回答生命周期 | 2026-10-28 已接入工作区 | 自有 ask_user、独立草稿、答案持久化与固定 ID 续跑；历史 question 权威核对。真实模型完整链路及发布未验收 |
+| 压力历史探索（B） | 设计提案 | `HistoryExplorer` 和新时间窗分页查询尚未实现，不能将本地筛选当成重新查询 |
+| 自由代码运行时（C） | 未接入 | 仍采用受控原生组件；独立 iframe、生成代码运行及其通信协议需要另行架构评审 |
+| 外围与 Dev 窗口交互 | 已修复 | 窗口外地图可点击、拖动和滚轮缩放；窗口内部操作不穿透地图 |
+
+对应根目录研究文档的四个阶段：阶段一的标准组件路线已实现；阶段三的原生组件状态管理已提前落地；阶段四已接入部分地图、报告和追问流程；阶段二的自由代码运行时尚未接入。本文后续 A/B/C 是实施包名称，与研究文档的阶段编号不同。
+
+2026-10-30 展示范围调整已通过 lint、typecheck、146 个文件共 838 项单元测试，以及 25 项浏览器回归（含复跑，使用模拟接口）。浏览器覆盖桌面与窄屏、内联与展开表格、图表动效、会话状态恢复、地图定位和补充表单；不代表真实项目联调或部署完成。
+
+2026-10-30 分区、导航与来源精简已通过 lint、typecheck、842 项单元测试和 20 项浏览器回归（含复跑，使用模拟接口）；另覆盖节点追问移除后的详情与地图定位。
+
+以下为 2026-10-26 的历史验证记录，不代表后续工作区变更的验证结果：
+
+| 验证层 | 结果 | 覆盖边界 |
+| --- | --- | --- |
+| 前端静态检查与单元测试 | lint、typecheck 通过；121 个文件、631 项测试通过 | 当前原生 UI、状态管理和既有前端回归 |
+| Agent 检查与聚焦测试 | `bun run check` 通过；33 项测试通过 | 状态存储、权限、版本冲突、重试和会话生命周期 |
+| UI 浏览器验收 | 10 项通过 | 当时的交互状态、引用追问、Markdown 阅读，使用模拟接口；引用追问现已移除 |
+| 窗口鼠标行为回归 | 4 项通过 | 外围与 Dev 的窗口内外事件、地图拖动与缩放；修复前已复现遮挡 |
+| 前端构建 | 通过 | SPA、生产 CSS 校验和 TTS adapter 构建；不等于部署完成 |
+
+当前实现入口为 [原生回答组件](../src/features/agent/answer-ui/answer-ui-view.tsx)、[会话状态同步](../src/features/agent/session-state/answer-view-state-scope.ts) 和 [Agent 状态存储](../../next-tjwater-agent/src/sessions/answer-view-state-store.ts)。验证命令见下文“验证”，后续顺序见“后续待办与验收”。
+
+2026-10-27 已补齐 [交互状态设计](agent-interaction-state-design.md)，覆盖阅读位置、分析篮、正式报告私人状态、接口与存储、版本冲突和验收矩阵。其中阅读位置和正式报告状态尚未实施；分析篮于 2026-10-30 移除，旧设计不再适用。正式报告状态需要新增项目 BizDB 状态表，不能沿用聊天核心 A 阶段“无数据库迁移”的交付结论。后续追加的宿主提问实现状态单列如下。
+
+同日补充的宿主提问方案已于 2026-10-28 接入工作区，见上述文档第 11 节：以自有 ask_user 管理等待、草稿、答案与续跑，同时核对历史原生 question 的可用状态。独立完成此项不代表 reader 或正式报告状态已实施；此前历史故障的具体触发条件仍未取得现场响应。
+
+## 接入方式
+
 聊天保留 AI SDK `UIMessage`、AI Elements 与现有 Agent 后端，新增
 `@json-render/core` / `@json-render/react` 的本地注册组件。
 组件代码随前端构建发布，无 ChatKit iframe、domain key 或 Vercel/OpenAI
@@ -11,11 +53,32 @@
 
 `Stack`、`Section`、`Text`、`Result`、`Metric`、`Table`、`Chart`、`Evidence`、
 `MapLocation`、`FollowUpForm` 共十种组件。图表可切换折线、柱状和数据表；
-表格可搜索、排序和选择行，图表可切换已加载区间、显隐序列并选点追问；
+表格可搜索和排序，图表可切换已加载区间、显隐序列并查看数据点详情；
 证据可按类别筛选、折叠并标注来源；地图定位通过现有控制器执行；表单从空值开始，
 由用户主动提交，提交形成普通用户消息。业务证据是否保存以 Agent 实际工具结果为准。
 
-`Chart` 的页签、图例、区间摘要与数据点详情由前端固定实现，Agent 只提供标题、初始图形类型、类别、序列和来源。鼠标切换折线、柱状和数据表时使用 180ms Motion 滑块与内容过渡；键盘操作与减少动态效果模式即时完成。数据点详情只在点击图中数据点，或聚焦图形后按回车、方向键、Home/End 选点时出现，关闭后焦点回到图形；数据表页签不重复展示区间摘要和点详情，搜索与选行在视图切换后保留。
+数据组件用于展示与本地浏览，不提供勾选、加入分析、分析内容篮或针对组件追问。`MapLocation` 的定位与 `FollowUpForm` 的补充资料提交保留各自入口。
+
+短回答不显示内容导航；含表格、图表、补充表单或达到长内容标准、且包含至少两种可导航组件的回答才提供目录。单个证据或表单使用组件自身标题，多个独立条目才增加分组折叠；不叠加固定的分区说明。
+
+### 按任务表达内容
+
+Agent 选择组件、内容顺序与受控语义，前端负责实际视觉、响应式布局和可执行动作。新增字段均为 `answer-ui@1` 的兼容扩展，旧记录保持可读；Agent、Server 与前端需同步交付生成目录。
+
+| 组件 | 可配置语义 | 前端行为 |
+| --- | --- | --- |
+| `Result` | `title`、`summary`、`status`、`source` | 用小面积状态图标和文字区分 `success`、`partial`、`unconfirmed`、`error`；保留摘要及依据，不自动执行操作 |
+| `Stack` | 可选 `intent=response/comparison/report`、`density=compact/comfortable` | 指定简短回答、并列比较或报告；比较内容按可用宽度切换双列/单列；密度只调整内容间距 |
+| `Section` | 可选 `role=result/analysis/evidence/follow_up` | 将独立分区放入结果、分析、依据或补充资料区域，保留分区内部的顺序 |
+| `Text` | 可选 `title`，原有 `tone` 不变 | 使用具体说明标题，例如“能力限制”，避免所有说明都叫“注意事项” |
+
+`Stack` 原有 `columns`、`gap` 与其他组件原有必填参数不变。未给新语义时沿用既有布局；显式 `intent=comparison` 保留作者编排，不再拆成分析与依据区域。`density` 不改变字体、控件大小和触屏命中区域，也不折叠或截断原始数据。颜色、CSS、脚本及任意动作不属于模型可配置参数。
+
+已有执行结果适合 `Result`，批量对象适合表格，真实时间序列适合图表，后续定位适合 `MapLocation`，可选资料补充适合 `FollowUpForm`。模型只能以已有工具结果或明确事实表达成功；未确认的执行或现场状态应保持 `unconfirmed`。演练记录成功与实际业务处置分别说明，`Result` 状态本身不构成执行凭据。正文保留关键结论与边界，辅助组件补充数据和依据，避免重复整段文字。
+
+短结果及说明直接在对话内阅读；包含表格、图表、补充表单或长正文的回答提供展开入口。窗口尺寸、滚动与放大由宿主管理，不作为模型输出样式。
+
+`Chart` 的页签、图例、区间摘要与数据点详情由前端固定实现，Agent 只提供标题、初始图形类型、类别、序列和来源。鼠标切换折线、柱状和数据表时使用 180ms Motion 滑块与内容过渡；键盘操作与减少动态效果模式即时完成。数据点详情只在点击图中数据点，或聚焦图形后按回车、方向键、Home/End 选点时出现，关闭后焦点回到图形；数据表页签不重复展示区间摘要和点详情，搜索与排序在视图切换后保留。
 
 其余组件使用 `answer-motion.tsx` 统一交互过渡，沿用现有实体面板、字体、语义颜色和圆角。首次加载即时显示；鼠标展开、收起使用 180ms 透明度和位移，键盘与减少动态效果模式即时完成。折叠中的内容立即设为 `inert` 并退出无障碍树，动画结束后隐藏；保留原 React 内容实例，反向操作中断旧动画，避免旧退出回调隐藏重新展开的表单。
 
@@ -23,23 +86,40 @@
 | --- | --- |
 | `Stack`、`Section` | 保留既有布局，不为静态分区附加动画 |
 | `Text`、`Result` | 静态说明和已有结果直接阅读，不反复播放入场或宣告历史状态 |
-| `Metric` | 保留原始数值、单位与来源，仅加入分析的按钮图标过渡 |
-| `Table` | 搜索排序即时响应；选行操作栏进入退出使用统一过渡；空结果不叠加选行提示 |
+| `Metric` | 直接展示原始数值、单位与来源 |
+| `Table` | 搜索排序即时响应；无勾选列、选行提示或操作栏 |
 | `Evidence` | 正文展开收起和箭头转动使用统一过渡；保留来源、记录时间与资料编号 |
 | `MapLocation` | 关联要素详情使用统一折叠；定位中的反馈及结果短时淡入 |
 | `FollowUpForm` | 精简与外层重复的补充提示；保留标题、说明、校验及草稿，提交反馈短时淡入 |
-| 报告辅助分区与分析内容篮 | 分区、内容篮及所选引用详情统一展开收起；保留表单与分析目标草稿 |
+| 报告辅助分区 | 分区使用统一展开收起；保留补充表单草稿 |
+
+定位与资料提交的即时状态由用户操作及宿主回调驱动，不读取模型声明的成功状态。定位区分处理中、成功、部分缺失、零结果失败与回执未确认；失败可重试，不支持定位时说明原因。表单提交中阻止重复发送，失败保留草稿；修改字段后清除上一版发送反馈，必填错误与对应字段关联。即时反馈随组件实例存在，刷新后不恢复为本地操作成功；已实现的表单草稿、筛选与图表状态继续使用会话保存通道。
 
 Agent 通过 `present_answer` 发布完整的局部界面块，可在两块之间继续输出文字。
 消息顺序为文字、`data-answer_ui`、后续文字与最终报告。同一轮内相同
-`block_id` 更新原块；下一轮不会修改上一轮回答。
+`block_id` 更新原块，块内稳定的元素 ID 标识同一图表、表格和表单；下一轮不会修改上一轮回答。
 这是按内容块逐步出现的界面，不是逐 token 编译 JSX 或每个 JSON 属性都立即显示。
 结构化消息与普通聊天共用持久化、历史与断线恢复通道。
 
-生成期间展开显示过程；`final_answer` 到达后，仅展开最后报告的完整文字与
-`ui_block_ids` 明确引用的已发布组件，其余文字、界面与工具轨迹默认折叠在
-“查看处理过程”中。报告组件按引用顺序排列，同一组件不会同时作为报告和过程
-挂载，避免重复表单。未被报告引用的过程界面只供回看。
+新发布的块使用 `phase: "process" | "final"`，省略时按 `process` 发布。同一轮相同 `block_id` 的阶段不可改变；需要最终界面时使用独立 ID 发布 `phase: "final"`。过程块始终留在处理过程，即使误列最终引用也不能进入最终答复或读取、写入最终交互状态。
+
+`final_answer.answer` 中用独立一行的 `[[ui:block_id]]` 固定最终组件的位置，`ui_block_ids` 是允许引用的块 ID 列表，必须与标记去重后的顺序一致。例如：
+
+```text
+已完成本次记录核对，结果如下。
+
+[[ui:pressure-summary]]
+
+下面解释异常时间和后续核验建议。
+
+[[ui:pressure-trend]]
+```
+
+两个示例 ID 都必须先以 `phase: "final"` 发布，再调用最终答复工具。代码围栏、缩进代码和引用中的标记保持字面文本，不执行引用。重复有效标记只挂载一次；不存在、未授权或过程块的标记显示内容不可用，不泄露过程摘要。
+
+生成期间按原始顺序显示内容；`final_answer` 到达后，正文按标记位置穿插最终组件，其余文字、界面与工具轨迹折叠在“查看处理过程”中。完成态只保留这一层过程折叠，展开后直接列出步骤及状态图标，不再嵌套执行进度卡片、计数和折叠按钮。工具调用按独立行展示状态图标、工具图标及名称，具体参数默认收起。过程与工具参数展开前停止底部自动跟随，以当前消息位置作为锚点；鼠标操作使用短时淡入与位移动画，键盘与减少动态效果模式即时完成。外层箭头与步骤状态使用相同的 24px 图标占位；工具名换行时，状态、工具图标和右侧箭头对齐标题首行，参数说明沿用正文缩进。复制和语音使用相同的最终顺序，以组件摘要替代标记，并排除过程资料。旧历史中没有 `phase` 的块仍按明确引用兼容读取；没有位置标记的旧答复继续在正文后追加引用块，新发布不再依赖这一兼容路径。
+
+同一最终块从生成切换到状态保存时保持组件实例，不因启用持久化而重挂载；尚未完成的编辑先留在内存，最终答复完成后读取远端并合并本地变更。过程块不访问最终状态接口，关闭或切换会话也不产生远端写入。
 
 已发布交互界面的普通/协作聊天在最终答复完成、且没有待完成工具时停止本轮原生
 生成，防止最终报告之后反复自动修改界面。该收尾不标记后台调查任务完成；
@@ -49,7 +129,9 @@ Agent 通过 `present_answer` 发布完整的局部界面块，可在两块之
 
 ## 正式报告与主工作区
 
-正式报告可携带 `ui_blocks?: Array<{ block: AnswerUiBlock; evidence_refs: string[] }>`，最多 8 块，总 UTF-8 JSON 不超过 400000 字节。每块绑定报告中的已有证据，Server 验证任务归属；事实字段与审批不由 UI 块替代。组件树与聊天共用 `answer-ui@1`。例如：
+正式报告可携带 `ui_blocks?: Array<{ block: AnswerUiBlock; evidence_refs: string[] }>`，最多 8 块，总 UTF-8 JSON 不超过 400000 字节。每块绑定报告中的已有证据，Server 验证任务归属；事实字段与审批不由 UI 块替代。组件树与聊天共用 `answer-ui@1`。
+
+正式报告块只接受 `phase: "final"` 或未标阶段的旧块，拒绝 `process`；读取旧记录时继续省略阶段字段，不将其改写为 `null`。例如：
 
 ```json
 {
@@ -74,9 +156,9 @@ Agent 通过 `present_answer` 发布完整的局部界面块，可在两块之
 
 此片段仅展示新增字段，发布时仍需完整报告与真实存在的证据编号。保存沿用 `agent-artifacts`、报告 JSON、幂等键和 revision；读取沿用报告列表、指定版本、任务详情及 Agent context，不新增写入端点或数据库表。
 
-`InvestigationReportBlocks` 将正式报告接入 `AnswerUiView`，证据组件使用保存记录中的摘要、来源、时间与类别。未知版本或无法解析的块展示 fallback，报告固定事实仍可读。报告追问携带 `report_revision`、`reportGeneration` 和引用文本；表单先带入会话，确认后才发送。
+`InvestigationReportBlocks` 将正式报告接入 `AnswerUiView`，证据组件使用保存记录中的摘要、来源、时间与类别；块外只补充尚未在证据卡中展示的引用依据，表格和降级内容仍保留来源。未知版本或无法解析的块展示 fallback，报告固定事实仍可读。补充表单带入会话时携带 `report_revision`、`reportGeneration` 和资料文本，确认后才发送；不提供通用组件追问入口。
 
-`ExpandableReading` 将同一个 React 内容实例移至主工作区，保留图表视图、搜索、行选择、表单草稿。关闭恢复入口焦点，重开恢复阅读位置。主工作区宽度至少 960px 可对照地图，其余宽度在两者之间切换；原地图实例保留。
+`ExpandableReading` 将同一个 React 内容实例移至主工作区，保留图表视图、搜索、排序、表单草稿。关闭恢复入口焦点，重开恢复阅读位置。主工作区宽度至少 960px 可对照地图，其余宽度在两者之间切换；原地图实例保留。
 
 ## 扩展组件
 
@@ -109,8 +191,9 @@ node scripts/export-answer-ui-contract.mjs /path/to/agent/src/chat/answer-ui-cat
 ```bash
 pnpm lint
 pnpm typecheck
-pnpm test src/features/agent/answer-ui src/features/workbench/hooks/agent-session-message-state.test.ts
-pnpm test:browser tests/browser/agent-answer-ui.e2e.ts tests/browser/agent-start-page.e2e.ts tests/browser/agent-report-workspace.e2e.ts
+pnpm test
+pnpm test:browser tests/browser/agent-answer-state.e2e.ts tests/browser/agent-answer-ui.e2e.ts tests/browser/agent-intelligent-workspace.e2e.ts --workers=1
+pnpm test:browser tests/browser/floating-panel-pointer.e2e.ts tests/browser/peripheral-sample-panel.e2e.ts --grep 'panel keeps outside|项目分析成果打开时|外围面板只读取' --workers=1
 pnpm build
 ```
 
@@ -118,6 +201,7 @@ Agent 仓库：
 
 ```bash
 bun run check
+bun test tests/sessions/answerViewState.test.ts tests/routes/answerViewStateRoutes.test.ts tests/sessions/workspaceStore.test.ts tests/routes/chatSession.test.ts
 bun test tests/chat/answer-stream-projection.test.ts tests/chat/answer-ui.test.ts tests/routes/chatStream.test.ts tests/routes/taskCollaboration.test.ts tests/runtime/opencode.test.ts
 bun run tests/integration/answer-ui-smoke.ts
 ```
@@ -149,3 +233,157 @@ Vite 统一解析 React/React DOM，Playwright 按端口使用独立的依赖缓
 运行的开发服务将旧临时目录的 React 预构建写回测试缓存。
 
 消息入口为 `POST /api/v1/responses`，采用 Responses 文本输入、Response 输出和标准 SSE 生命周期。前端 `ResponsesChatTransport` 将网络事件转换为已有 UIMessage 渲染数据；审批、凭据续期、地图动作及 answer-ui 走 `tjwater.*` 扩展事件，不将 AI SDK 的 UIMessage 流作为网络协议。会话、模型及动作回执等接口统一使用 `/api/v1` 前缀，原 `/agent/chat` 路径已移除；Agent 服务和现有会话数据保留。
+
+## 可持续分析工作区：实现与后续设计
+
+状态：2026-10-30 更新。A 的控件状态保存已实现，阅读位置持久化待补齐；分析篮已移除；B 为尚未实现的受控查询方案；C 为独立架构扩展的接入条件。
+
+### 目标与实施次序
+
+以工作区根目录的 [Intelligent UI 研究文档](../../intelligent%20UI.md) 为方向，下一阶段让用户能够保留探索状态、在回答内查询新时间窗、联动地图，再带着明确的对象与范围继续分析。视觉规范仍只引用 [样式设计指南](style-design-guide.md)。
+
+原生组件已具备宿主状态保存，下一步优先验证真实项目中的恢复流程，再推进受控数据查询。自由代码运行时在原生组件无法满足具体场景时单独评审。当前实现沿用既有 Agent 框架与存储，没有新增独立 UI Planner、新数据库或环境变量。
+
+原共享架构 `agent_ui_architecture_without_sandbox.md` 明确排除生成代码执行。本提案的可实施范围仍是原生组件；研究文档中的 sandbox 路线列为独立架构扩展，不借此改变当前运行时约束。
+
+### 已解决问题与剩余缺口
+
+| 问题或约束 | 当前状态 |
+| --- | --- |
+| 按完整数据设置 React key 导致控件重建 | 已改为稳定节点身份和显式兼容迁移 |
+| 控件状态仅在组件内存中，刷新后丢失 | 已接入受控 store 与宿主保存；阅读位置仍未持久化；分析篮已移除 |
+| 流式消息写入可能覆盖交互状态 | 已独立保存到 `chat/answer-view-state.json`，复用宿主串行队列、身份及删除校验 |
+| `answer-ui@1` 仅接受固定组件与 props | 保留此边界；新交互通过注册组件和受控回调扩展 |
+| Server 已有历史查询服务、项目连接与 scada.view 校验 | 新数据查询可以复用原服务，无须让每次选区都调用模型 |
+| 公开历史查询接口目前未暴露分页，而服务与 MCP 已支持 row_limit/row_offset | 交互探索需要增加有界的公开分页入口，不能把无限读取的风险留给浏览器 |
+
+这些结论来自源码核对；本轮未请求真实项目数据、模型或生产服务。
+
+### B 阶段目标工作区（尚未实现）
+
+首个场景选择“压力历史分析”。Agent 获取真实监测对象和资料后选择原生组件，简单解释仍只显示文字。聊天流保留结论、判断边界与轻量内容；用户主动展开后，在原工作区内探索。
+
+```text
+对话：结论、判断边界、关键读数、展开入口
+  |
+  v
+压力历史分析                         来源与记录时间
+对象选择  起止时间  [更新数据]         当前探索 / 原回答快照
+趋势 / 数据                          [筛选已加载数据]
+选中对象的读数、单位、缺测说明         [定位地图]
+依据与说明                           [以此继续分析]
+```
+
+- `更新数据` 明确查询新时间窗；图内的范围选择、搜索与排序只处理已加载数据。参数改动先成为草稿，按按钮提交一次，不随每次键入发请求。
+- 桌面继续复用现有地图对照工作区，手机使用同一个实例切换地图与内容。沿用 `Card`、`Tabs`、`Select`、`DateTimeField`、`Table`、`Alert` 和 `Button`；不在窄聊天列内增加固定多栏仪表盘。
+- 地图联动以点击为触发，不因悬停、恢复历史或数据到达改变视角。所选对象由明确的图层与 feature ID 表示；名字和数组序号不能充当资产标识。
+- `以此继续分析` 将对象、时间窗、来源类别与引用的回答版本带入输入区，由用户确认发送。Agent 重新核验所需数据，不把浏览器传入的数值自动当成服务端事实。
+- 历史回答是生成时的快照。探索新时间窗不重写原结论；重新分析产生新的回复。正式报告版本与证据也保持不可变。
+
+### A. 保存交互状态（核心已实现）
+
+下述控件状态与 GET/PUT 接口已接入 Agent 对话中完成的最终回答。前端使用稳定节点标识、受控 store 和按登录范围持有的会话缓存；500ms 防抖保存，恢复期间按字段合并新编辑，保存失败可重试，冲突须明确选择保留本地或重载远端。正式报告的同实例展开保留内存交互，但尚未接入这套聊天状态持久化。
+
+本阶段不扩展模型可生成的组件协议。宿主新增 `answer-view-state@1`，状态身份由当前登录主体、业务项目、sessionId、assistantMessageId、blockId、nodeId 共同确定；主体和项目只能从认证上下文取得。
+
+前端在验证成功后，按 spec.elements 的键建立 nodeId。通过本地渲染适配注入状态句柄，不把 nodeId 注入字段或状态表达式开放给模型。使用 json-render 已有受控 store/StateProvider 接口，将控件改为受控状态，避免第二份组件本地状态与宿主状态竞争。库提供状态绑定机制，但允许持久化哪些字段由本地组件目录决定，见 [json-render 数据绑定](https://json-render.dev/docs/data-binding)。
+
+| 内容 | 保存字段 | 新数据到达时的处理 |
+| --- | --- | --- |
+| 图表 | 视图、隐藏序列、区间、选中点、详情展开 | 保留视图；序列名与顺序一致才复用显隐；唯一时间标签可重定位选点；无法匹配时清除选择并提示 |
+| 图表内数据表 | 搜索、排序 | 切换序列时清理排序；视图切换和状态恢复保留兼容的搜索与排序 |
+| 表格 | 搜索、排序 | 搜索保留；列变化清除无效排序；不恢复历史选行 |
+| 资料表单 | 字段草稿 | 同 nodeId、同字段名和类型才合并；删除或变更类型的字段不迁移，不自动提交 |
+| 证据 | 类别筛选、展开项 | 保留仍存在的证据；不存在的筛选回到全部 |
+
+为兼容已部署的 `answer-view-state@1` 严格校验，表格与图表数据表仍在传输时携带 `selection: []`；前端丢弃旧快照中的选行，不提供相关界面。
+
+尚未持久化：阅读锚点与相对偏移。当前同实例展开/收起的内存保留，不等于刷新后的宿主恢复。
+
+补齐方案见 [Intelligent UI 交互状态补齐设计](agent-interaction-state-design.md)：保留现有 controls 接口，计划新增独立 reader 记录；旧 basket 部分已停止实施；正式报告按当前读者及报告版本保存到 Server，不使用发布报告的 Agent 会话充当读者身份。
+
+状态记录附带完整 spec 摘要 `schema_digest`、单块 `revision` 与最后请求 ID。`schema_digest` 由服务端从会话里已保存的块计算；客户端摘要只用于检查过期。摘要变化后执行上表的兼容迁移，再写新版本。按数据整体设置 key 的逻辑改为稳定节点身份加显式兼容处理，不能只删除 key 而沿用越界索引。
+
+已实现的 Agent 接口：
+
+| 接口 | 输入与行为 |
+| --- | --- |
+| `GET /api/v1/session/:sessionId/ui-state?message_id=…&block_id=…` | 校验会话归属和块存在；返回对应状态、revision、schema_digest；未保存返回空状态及 revision 0 |
+| `PUT /api/v1/session/:sessionId/ui-state` | 输入 message_id、block_id、schema_digest、expected_revision、request_id、nodes、block；只接受对应组件允许的状态字段 |
+
+写入在同一串行队列内读取旧记录、检查 expected_revision、校验并原子替换。回执保留最近 32 条且总量不超过 128 KiB；窗口内相同 request_id 且内容一致返回原结果，相同 ID 携带不同内容拒绝。回执过期后，旧请求仍受版本检查保护。版本冲突返回 409 及当前版本，前端保留未保存草稿并提供重载或重新保存，不静默覆盖另一个窗口的状态。保存失败显示“未保存”，不声称刷新后可恢复。
+
+初次恢复完成前允许阅读和编辑，但不以 revision 0 覆盖未知的已保存状态；记录本地变更字段，读取成功后按字段合并，用户刚输入的内容优先于迟到的恢复结果。失败时保留草稿并允许重试，重载远端状态必须明确提示会替换哪些本地改动。
+
+持久化使用宿主 `chat/answer-view-state.json`，独立于 messages.json；文件已加入 SessionWorkspaceStore 的受控记录列表，读取消息、检查版本和原子写入均在宿主队列内执行。状态来自用户交互及其兼容迁移，不进入模型可写的 workspace/，不进入默认推理上下文。删除会话沿用宿主删除标记和串行清理，迟到写入不能复活记录；分叉会话不继承未提交表单。
+
+当前限制：每块状态最多 32 KiB UTF-8，单会话状态文件最多 1 MiB；只保存控件字段及迁移依据，不复制原始时序读数、授权凭据或错误堆栈。服务端超限返回 413，前端单块预检超限时不发送；两者均保留当前内存草稿并提示未保存。前端 500ms 防抖，切换会话时对已完成初次读取的改动发起保存；退出时清空内存，不能依赖页面卸载请求保证保存成功。无须迁移旧 messages.json，旧会话首次保存时惰性创建状态记录。
+
+### B. 压力历史探索（设计提案，未实现）
+
+新增注册组件 `HistoryExplorer`，作为拥有固定业务语义的原生组件，不开放模型编写请求 URL、工具名或任意 action。其 props 为 title、targets、initial_start、initial_end、source；targets 只允许查询结果中明确关联的 junction ID 与 device ID，最多 5 组；source 首批只允许 scada_raw 或 scada_cleaned。时间为带时区 ISO 字符串，单次范围不超过 24 小时。缺少对象关联时继续展示原有 Chart 与数据缺口说明，不生成猜测绑定。
+
+该组件仍通过 answer-ui@1 的目录扩展交付，保持 envelope 与快照格式不变；前端为参数唯一来源，导出 Agent、Server 的 props schema，并在三端增加相同的交叉校验。旧客户端遇到新组件显示 fallback_text，不能执行未知组件。Agent 和 Server 先支持校验，前端发布后再启用该组件的生成指令；旧客户端仍可阅读摘要。
+
+前端 `agent` 模块只声明 `onQueryHistory` 回调与数据结果类型，`workbench` 实现身份、项目头、请求和地图控制器。不能从 agent 深入导入 workbench，也不在 Agent 服务里新建通用查询代理。
+
+```text
+已有 Agent Harness -> present_answer -> 现有校验与消息通道
+                                           |
+                                           v
+                                    原生回答 + 交互状态
+                                           |
+                                      用户显式操作
+                                           |
+                                    Workbench 适配器
+                                     /            \
+                              地图控制器      Server 历史服务
+                                           |
+                                查询结果回到当前探索视图
+```
+
+Server 拟新增 `POST /api/v1/timeseries/views/element-history/page`，复用 TimeseriesHistoryService.query 的 row_limit/row_offset 路径及当前项目数据库连接，保留 scada.view 授权。请求包含上述明确对象与时间窗，以及 limit、offset；首批只支持 observed。limit 默认 500、最大 1000，offset 为非负整数，最多 5 个对象、24 小时。返回 series、page.limit、page.offset、page.has_more、queried_at；不改变原无分页接口。
+
+每次“更新数据”最多读取 5000 个点或 10 页，以先到者为准；超过预算保留已读部分并明确“时间窗未完整覆盖”，提示缩小范围。Server 每页有界，浏览器也限制累计体积；到达 2 MiB 停止继续加载。不能用前 100 点冒充完整 24 小时。分页是在有数据写入的系统中逐页读取，不承诺跨页一致快照；按对象、设备、来源、时间去重，保留查询时刻和查询参数，正式证据仍由后端报告流程形成。
+
+新请求取消旧请求并提升 request generation；结果只有在项目、会话、节点和 generation 均匹配时可应用。超时或服务失败保留旧图，并同时显示旧图的实际时间窗与失败原因；无数据与请求失败分开表达。返回 null 的点显示缺测断线，不补零；按 source_unit 展示，转换需有明确单位规则；原始、清洗、实时模型和分析结果不能混为同一种来源。
+
+刷新数据不修改消息快照。查询参数和控件状态可以保存，未固化的探索数据只留在当前会话内存；刷新页面后先显示原回答或待加载状态，用户点击“更新数据”重新取数。需要跨日保存的业务结论仍通过现有正式报告与证据通道发布。
+
+### C. 自由代码运行时（未接入，需独立评审）
+
+本轮只确定接入条件：出现标准组件难以表达、且确有使用价值的交互图解或模拟，再单独评审 sandbox 协议与运行环境。阀门工况计算必须复用实际仿真服务；可拖动示意图不等同于水力模型。
+
+后续设计参考 [MCP Apps 的 AppBridge](https://github.com/modelcontextprotocol/ext-apps/blob/main/src/app-bridge.ts) 的初始化、能力协商、结果推送和 teardown，把动态程序当作独立实例管理。其工具转发能力不能原样映射为“允许调用全部供水工具”。iframe 本身也不能证明资源消耗或业务权限已受控。
+
+接入前须完成：独立来源与 CSP/网络策略、消息来源与实例校验、显式能力列表、宿主中止与生命周期、版本替换及状态迁移、崩溃后的文本回退、真实浏览器资源预算验证。生产控制、业务写入和审批继续由既有服务执行。本阶段不新增 sandbox 入口、依赖或服务器，因此不会留下无法使用的占位 UI。
+
+### 后续待办与验收
+
+A 与 B 可独立交付，B 尚未实现不影响已有聊天控件的状态保存。建议按以下顺序推进，正式提交和发布按各仓库分别执行。
+
+| 顺序 | 待办 | 完成标准 |
+| --- | --- | --- |
+| 1 | 已实现能力的真实联调与交付 | 在隔离 Agent 与已授权项目中验证保存读回、刷新恢复、会话隔离、报告/表单回传；补充真实模型组件选择验收，再整理提交与发布记录 |
+| 2 | B 阶段压力历史探索 | 用户选择对象和时间窗后显式查询；分页有上限、缺测不补零、旧响应不覆盖新请求；定位地图并携带查询范围继续分析 |
+| 3 | 实施已补齐的状态设计 | 优先独立交付宿主提问生命周期；聊天 reader 和正式报告私人状态另分两批，分别验证恢复、清理与版本隔离 |
+| 4 | C 阶段架构评审 | 先确认原生组件无法满足的具体场景，再决定是否引入沙箱及其权限、通信、资源预算和生命周期 |
+
+| 阶段 | 主要修改位置 | 必须验证 |
+| --- | --- | --- |
+| A 前端（已实现） | answer-ui/answer-ui-view.tsx、answer-parts-view.tsx、answer-view-state.ts、answer-view-state-provider.tsx；agent/session-state/；workbench/hooks/use-workbench-agent.ts；agent/api/client.ts | 状态注入、同块更新、无效选择清理、迟到恢复不覆盖新输入、会话隔离 |
+| A Agent（已实现） | sessions/workspace-store.ts、sessions/answer-view-state-store.ts、routes/answer-view-state-routes.ts、routes/chat.ts | 身份和块归属、原子版本检查、幂等重试、冲突、字节限制、会话删除竞态 |
+| B 前端 | answer-ui/catalog.ts、contract.ts、answer-ui-view.tsx；新增 history-explorer.tsx、workbench/api/element-history-client.ts；现有 workbench-agent-panels.tsx 的回调装配 | 参数校验、请求与本地筛选区分、取消和旧响应、缺测、单位、地图定位失败 |
+| B Agent / Server | 导出的 answer-ui-catalog.json；三端 answer-ui 校验；Server timeseries/composite.py、timeseries_history.py 的分页请求/响应模型；Agent instruction.md | 旧消息降级、新组件约束一致、Server 分页限制、scada.view 和项目隔离 |
+
+前端执行 `pnpm lint`、`pnpm typecheck`、`pnpm test`，并扩充 `tests/browser/agent-answer-ui.e2e.ts` 的 320/375/1440px 用例。A 在 Agent 执行 `bun run check` 及 `tests/sessions/workspaceStore.test.ts`、新增状态存储/路由测试、`tests/routes/chatSession.test.ts`。B 追加 Agent `tests/chat/answer-ui.test.ts`，Server `tests/unit/test_timeseries_history.py`、`test_timeseries_history_schema.py`、`test_report_ui.py` 与新增分页 API 授权测试。新增 schema 后运行 `pnpm export:answer-ui-contract`；发布前完成前端构建和真实授权项目的有界读查询验收。
+
+验收场景必须包含：保存后刷新、两窗口编辑冲突、数据更新时仍在填写表单、重复序列标签、数据集换序、断网与 403、切换项目后旧响应返回、删除会话后迟到保存、未知组件回退、减少动态效果、键盘焦点与窄屏无溢出。保存成功必须有读回证据，不能仅以组件没报错作为通过。
+
+最关键的前提是查询结果能明确关联监测设备与管网对象；现有数据若缺少关联，地图入口应显示不可定位并保留读数，不能使整个分析失效。真实模型选型与数据质量均需独立验收，组件测试不替代它们。
+
+发布 A 时先部署 Agent 的可选状态接口，再部署前端；没有接口或保存失败时保持可读和内存交互，并显示未保存。回退保留新状态文件和已有消息，不清理用户资料。B 回退时停止生成 HistoryExplorer，旧客户端按已有 fallback 读取，保留原查询接口。上述两阶段均不需要新账号、密钥或环境变量。
+
+### 地图与外部展示动作
+
+`answer-ui@1` 继续描述可保留的回答内容；动作统一为 `{command: {action, ...字段}}`。Chat 的 `present_view` 使用 `frontend-action@2` 和 `frontend-action-result@2`，调查任务事件及 Dev JSONL 使用相同 command，由共用执行器处理。定位按钮也使用该执行器。十种动作和验证步骤见 [调查任务展示与 Dev 测试](investigation-dev-tools.md#统一展示动作)。动作是一次性过程副作用，不因 final_answer 引用 UI 或历史渲染而重放；block_id/phase/正文锚点规则不变。

docs/agent-chat-ui-design.md

@@ -26,7 +26,7 @@ Agent 相关弹窗、面板及菜单统一保持本地 shadcn/ui 设计，具体
 | 人工参与 | 权限审批、问题回答和跳过、补充资料 | 对应回复内保留可操作表单，确认前不执行 |
 | 分析结果 | 指标、表格、折线和柱状图、证据 | 回复中的交互内容，可搜索、排序、选点、筛选序列及已加载区间 |
 | 展开阅读 | 聊天回答与正式报告进入主工作区 | 明确点击进入，保留唯一组件实例、筛选、表单草稿和阅读位置 |
-| 内容追问 | 指标、数据点、表格行、证据 | 带来源的可删除引用；正式报告另带版本和轮次；确认后发送 |
+| 数据浏览 | 指标、数据点、表格、证据 | 展示与本地查看；不提供行勾选、分析篮或组件追问 |
 | 正式报告 | 当前结论、结论边界、证据、缺口、待办、审批与历史版本 | 固定事实区与可选交互分析模块组合 |
 | 地图联动 | 定位实际要素、显示定位结果 | 对应内容内的明确按钮 |
 | 回复工具 | 复制正文及交互摘要、朗读和选段朗读 | 回复底部低强调操作及文字选择入口 |
@@ -114,13 +114,13 @@ Agent 面板
 └─ 输入区：引用 / 多行输入 / 权限、模型、语音、发送或停止
 ```
 
-纯指标的双列 `Stack` 合并为紧凑摘要区，容器宽度达到 240px 即可并排；名称、原始数值、单位和来源完整保留，不用省略号截断。指标提问按钮放在名称旁，减少单独操作行。混合内容的双列仍使用 440px 断点。助手正文直接进入消息流，证据按需折叠，补充表单保留独立操作区；表面与间距统一引用样式设计指南。
+纯指标的双列 `Stack` 合并为紧凑摘要区，容器宽度达到 240px 即可并排；名称、原始数值、单位和来源完整保留，不用省略号截断。指标仅展示名称、数值、单位和来源。混合内容的双列仍使用 440px 断点。助手正文直接进入消息流，证据按需折叠，补充表单保留独立操作区；表面与间距统一引用样式设计指南。
 
 图表首先显示标题、视图切换、序列和趋势。范围选择默认收起，展开后可选择起止点及重置；收起只改变展示，不取消已选范围。序列按钮使用低强调色，图例颜色保留数据对应关系；至少一条序列可见。数据点的各序列值分行对齐，保留原始精度。
 
 正式报告展开后采用连续文档排版，章节之间使用细分隔线。目录跟随阅读区滚动，包含实际存在的结论、分析、调查进展、待办、处置、缺口、脉络、依据、时间线和版本。目录使用导航语义，点击或键盘激活后立即滚动并将焦点交给目标章节；手机目录可横向滚动。接近文档末尾、目标无法滚至顶部时，保留主动选择的章节标记，直到用户再次滚动。该导航只改变阅读位置，不控制任务执行或审批。
 
-空会话采用“简短引导、首次输入、推荐问题”的顺序，整组在 Agent 面板内横向居中，放在会话栏下方可用区域的中部。居中容器最多 600px，桌面内边距 24px，手机左右内边距 16px；短屏内容超过可用高度时从顶部排列并允许滚动。判断依据是当前会话有无消息，不取决于帐号是否保存其他历史会话。加载历史或已有任务状态、审批、结构化结果时保留正常阅读区，不覆盖为欢迎页。
+空会话采用“简短引导、首次输入、推荐问题”的顺序，整组在 Agent 面板内横向居中，放在会话栏下方可用区域的中部。居中容器最多 600px，桌面内边距 24px，手机左右内边距 16px；短屏内容超过可用高度时从顶部排列并允许滚动。判断依据是当前会话有无消息，不取决于帐号是否保存其他历史会话。加载历史、引用任务或已有工具权限审批、结构化结果时保留正常阅读区，不覆盖为欢迎页。
 
 输入文字区初始高度 64px，按内容增长至视口允许的高度。首次发送后同一个输入组件回到底部；新建空会话后恢复居中布局。使用 `motion/react` 的位置布局动画处理这两种状态，沿用项目的 180ms 缓动，不缩放输入文字，也不对 Resizable 连续调宽添加动画。系统开启减少动态效果时直接切换位置。表单实例和草稿在布局变化时保留。
 
@@ -158,13 +158,45 @@ Agent 形象基于 [Obsidian 原版动画资源](https://ejiidnob33g9ap1r.public
 
 推荐依据使用独立的近期会话页，历史搜索和翻页不改变输入。缓存摘要按活动 ID、标题、内容、状态及来源计算，单纯心跳时间变化不触发推理。生成新推荐时保留上一组问题。
 
-每个会话持有独立 Chat 实例、生成连接、草稿、引用、阅读位置和审批状态。切换历史或新建对话保留原会话后台生成；后台需要审批或回答时，通过历史入口提示返回处理。模型、项目头和凭据续期绑定原会话。后台浏览器动作返回 `SESSION_NOT_ACTIVE`，提示用户回到会话后重新请求；切换时取消原会话尚在执行的浏览器动作。恢复失败保持可重试的连接异常状态，不将断流视为任务完成。切换业务项目由工作台统一处理，会话、主题及缓存按业务项目隔离。
+推荐失败后，面板保持打开时在错误缓存到期后重试，同一轮最多请求三次；服务从离线恢复时立即重试失败项，也提供“重试推荐”入口。成功缓存继续复用，重试不改变输入草稿，模型目录尚未加载时不发送空模型请求。
+
+Agent 面板、历史和主题窗口及正文阅读窗口共用选区复制处理，仅移除浏览器附加的末尾段落换行。正文内部段落、代码缩进、表格制表符与用户输入的有效换行保留；输入框沿用原生复制。
+
+每个会话持有独立 Chat 实例、生成连接、草稿、引用、阅读位置和审批状态。切换历史或新建对话保留原会话后台生成；后台需要审批或回答时，通过历史入口提示返回处理。模型、项目头和凭据续期绑定原会话。后台浏览器动作返回 `SESSION_NOT_ACTIVE`，提示用户回到会话后重新请求；切换时取消原会话尚在执行的浏览器动作。切换业务项目由工作台统一处理，会话、主题及缓存按业务项目隔离。
+
+头部在线状态由 Agent 公共 `/health` 的就绪结果独立决定，单次业务失败、提问等待、主动停止和新建对话不直接改为离线或在线。在线时每 15 秒探测，失败后按 1、2、4、8、15 秒退避，单次超时 5 秒；浏览器恢复联网、窗口聚焦或页面重新可见时立即重检。服务恢复后刷新初始化信息和当前会话的提问、输入队列，保留草稿与阅读位置。
+
+已知会话的 Responses 流意外断开后，改用该会话的只读订阅恢复；订阅中断同样按 1 至 15 秒退避重连，合并权威消息尾部并保留已加载历史。重连不重发问题、不重启模型、不重做工具操作，也不将断流视为任务完成。权限失效、会话不存在、主动停止和所属工作台销毁时终止重连；切换到其他对话仍由原会话持有后台恢复连接。
 
 ## 4. 内容与状态
 
+### 任务驱动的回答表达
+
+按 Intelligent UI 的声明式组件路线增强当前对话：Agent 使用既有 Harness 与 `present_answer` 决定文字、指标、趋势、对照表、证据及补充表单的组合，前端负责本地交互和视觉层次。简单回答保留文字；说明和判断边界使用本地 shadcn/ui `Alert` 的图标、标题与正文组合，静态历史内容使用 `note` 语义，避免恢复会话时反复播报警告。
+
+包含两类及以上可导航组件，且含表格、图表、补充表单或达到长内容标准时，回答上方出现“浏览回答”菜单，按实际组件显示类别和数量。选中项目在当前内容实例内滚动并交接键盘焦点；Escape 关闭菜单后回到触发按钮。导览沿用 `DropdownMenu`、`Button`、`Badge`，不切换页面、不重建图表或表单。只有一种可导航组件或内容较短时不增加导览。导航入口与内容类别摘要在窄屏保持紧凑，长标签自然换行。
+
+图表保留折线、柱状和数据页签；范围筛选收进标题右侧的控件，所选非完整区间仍明确显示。数据点详情按需展开，点击图上数据点自动展开对应读数；键盘用户通过“查看数据点”及选择器完成同等操作。收起详情保留所选点。当前界面交互均只影响已加载数据；新查询与仿真仍走原业务工具。
+
+消息标题区明确助手身份和真实生成状态。指标保留原始精度、单位与来源；证据继续区分事实和推断；资料表单通过 `CardHeader`、`CardContent` 划分说明和输入，提交是明确的主操作，失败保留填写内容。颜色、字体与表面沿用样式设计指南，交互状态不冒充业务状态。
+
+本次无需新增 UI 协议、环境变量或数据库迁移。自由代码沙箱、跨会话保存控件状态和参数驱动的新数据查询属于后续能力；当前表单、筛选与选择在聊天和展开工作区之间移动时保留，历史恢复仍从已保存的回答结构重新建立控件。
+
+后续的状态保存、压力历史探索与沙箱接入条件见 [可持续分析工作区设计](agent-answer-ui.md#下一阶段设计可持续分析工作区)。该部分是未实现的提案，不能作为当前功能清单。
+
 `answer-ui@1` 仍由严格参数校验与本地注册组件驱动。已有的 `Stack`、`Section`、`Text`、`Metric`、`Table`、`Chart`、`Evidence`、`MapLocation`、`FollowUpForm` 使用新外观。聊天继续使用现有 Responses 事件；正式报告增加可选 `ui_blocks` 字段，复用相同的内容块协议。实现契约见 [本地交互式回答](agent-answer-ui.md)。
 
-生成中显示已经到达的文字、内容块和公开执行摘要；最终答复到达后，正文和它明确引用的内容留在主阅读流，其他记录进入处理过程。待回答问题、权限审批和失败状态保持可见，不能因最终文字到达而被隐藏。这里借鉴 Reasoning 的折叠行为，呈现的数据是服务端已发布的过程信息，不额外生成思考文本，也不根据耗时推算完成比例。
+处理过程统一位于回复正文下方。生成中，文字与回答内容块在前，公开执行摘要、标记为过程的内容块和待办在后；最终答复到达或回复流结束后，过程收起为底部“查看处理过程”，入口位于语音播放左侧，没有 `final_answer` 标记的历史回复也遵循同一布局。最终答复明确引用的回答内容块留在主阅读流，其他记录进入处理过程。待回答问题、权限审批和失败状态在正文下方保持可见，不能因回复结束而被隐藏。这里借鉴 Reasoning 的折叠行为，呈现的数据是服务端已发布的过程信息，不额外生成思考文本，也不根据耗时推算完成比例。
+
+最终答复到达后，正文、回复状态与语音/复制操作在同一次交接中切换，网络流的后续收尾不再改变这条回复的展示阶段。输入框仍根据真实执行状态接受引导或排队消息。过程复用生成时的容器和步骤实例，保留工具详情的展开状态；无论用户是否向上滚动或查看过工具详情，交接后默认收起过程并优先让结果正文可读；用户可通过“查看处理过程”重新展开。历史回放直接显示保存的结果，不重新播放交接。
+
+补充问题打断后继续执行时，依据提问记录的 `message_id` 和补充回答的 `delivery.native_message_id` 将前后过程归到续接答复下方；连续补充时沿同一关联链顺序归组。没有正文的旧过程消息不再单独占位，原有正文和用户补充回答仍保留。尚未出现续接答复、历史分页缺少关联消息、仍有待回答问题或审批、关联之间出现新用户请求时，保留原位置。该归组仅影响展示，不改原始记录或消息标识。
+
+生成中、补充后续接和历史恢复共用一个处理过程容器，边框、背景和内边距保持一致；各段执行记录合并为一份列表，不再嵌套另一张“执行进度”卡片。步骤显示身份包含来源消息，避免前后轮次的同名步骤互相覆盖；生成时统一控制整个过程的最近三项与展开全部，完成后由底部入口统一折叠。
+
+已提交的回答以原生用户消息 ID 保存纯净文本和 `data-interaction_reply` 快照，首屏即可还原同一张“已回答”卡片并归组前后过程，不等待独立提问接口。该接口返回较新修订后更新投递状态和重试操作。旧历史由 Agent 按所属会话中已保存的投递 ID 补齐相同表示，不通过文本前缀猜测对应关系，也不改写历史文件。给模型的“用户提交的提问回复”协议前缀只用于推理输入。
+
+提问等待和续接失败不禁用消息发送。生成中或存在未解决的提问/续接时，输入区提供“引导当前任务”和“排队处理”；消息通过既有 Responses 输入接口进入原生收件箱。没有宿主执行轮次时只保存输入，不自行启动模型，也不把消息当作提问表单的答案。读取续接状态时，服务端可以依据已消费的原生回答和已完成的原生输出恢复丢失的确认；仅有部分文字或原生状态不可用时保留未确认状态。若输入在入队前被明确告知当前轮次已结束，客户端刷新状态后作为新一轮发送；其他错误不自动重发。
 
 证据类别明确区分查询记录、用户提供、分析推断和演练数据。地图定位的按钮结果以实际回调为准；资料表单提交后只表示发送消息，业务证据是否保存取决于后端实际结果。最终回复不等于后台调查任务完成。
 
@@ -184,15 +216,17 @@ Agent 形象基于 [Obsidian 原版动画资源](https://ejiidnob33g9ap1r.public
 
 ## 7. 交互规则与范围
 
+数据组件按展示与本地浏览组织：短内容不附加目录；单个证据或补充表单不叠加分组标题与固定提示；来源已在证据卡中显示时，报告外层只列出其余依据。调查脉络节点保留详情、缩放和地图定位，不提供节点追问按钮。
+
 | 内容 | 本轮实现 | 数据与操作边界 |
 | --- | --- | --- |
-| 指标 | 值、单位、来源，针对指标提问 | 不补造变化率、单位或精度 |
-| 表格 | 搜索、三态排序、行选择、引用所选行 | 只处理当前数据；更换数据集时重置行选择 |
+| 指标 | 值、单位、来源 | 不补造变化率、单位或精度 |
+| 表格 | 搜索、三态排序 | 只处理当前数据；不提供勾选与引用操作 |
 | 图表 | 折线 / 柱状 / 数据，序列显隐，加载区间，点击或键盘选点 | 最少保留一条序列；区间不触发查询或重算 |
 | 证据 | 来源、类别、时间、编号，展开与类别筛选 | 正式报告使用已保存证据覆盖生成的摘要、来源和类别 |
 | 地图 | 显式定位，地图对照或切换 | 使用真实定位结果与失败反馈 |
 | 表单 | 空白初始值、必填校验、提交中禁用、失败保留 | 聊天表单主动发送；报告表单先带入对话，确认后发送 |
-| 追问 | 输入区引用卡片、详情、移除 | 不自动发送；报告引用带选中的版本与轮次 |
+| 任务与报告对话 | 输入区引用卡片、详情、移除 | 保留专用任务、报告和补充表单入口；通用数据组件不产生引用 |
 | 历史内容 | 固定报告事实可读，不支持的块显示摘要 | 降级不执行未知组件或事件 |
 
 本轮未包含参数重算、新数据查询控件、附件上传、导出、报告版本差异比较。后续扩展时需要独立定义参数校验、数据来源和执行反馈；不能把本地筛选当作重新分析。后台任务完成、业务审批和证据写入继续以各自服务端状态为准。
@@ -205,14 +239,11 @@ Agent 形象基于 [Obsidian 原版动画资源](https://ejiidnob33g9ap1r.public
 
 组件参数唯一来源为前端 `catalog.ts`，导出到 Agent 与 Server；跨字段约束在三端分别验证。Agent `publish_task_report` 使用正式报告通道，聊天 `present_answer` 使用聊天通道。实现与生成命令见 [本地交互式回答](agent-answer-ui.md)。
 
-## 聊天过程与回答恢复
+任务业务审核统一从 header 的“状态和提醒”进入对应任务详情，由关联的负责节点或动作卡承接人工审核。会话只保留任务引用、讨论和消息，不注入固定的任务状态、人工事实或业务审核表单；调查详情继续负责草稿编辑、批准、拒绝及执行回执。工具执行权限审批和用户问题仍按会话交互协议处理。
 
-处理过程统一位于回复正文下方。生成中，文字与回答内容块在前，公开执行摘要、标记为过程的内容块和待办在后；最终答复到达或回复流结束后，过程收起为底部“查看处理过程”，入口位于语音播放左侧，没有 `final_answer` 标记的历史回复也遵循同一布局。最终答复明确引用的回答内容块留在主阅读流，其他记录进入处理过程。待回答问题、权限审批和失败状态在正文下方保持可见，不能因回复结束而被隐藏。这里借鉴 Reasoning 的折叠行为，呈现的数据是服务端已发布的过程信息，不额外生成思考文本，也不根据耗时推算完成比例。
 
-最终答复到达后，正文、回复状态与语音/复制操作在同一次交接中切换，网络流的后续收尾不再改变这条回复的展示阶段。输入框仍根据真实执行状态接受引导或排队消息。过程复用生成时的容器和步骤实例，保留工具详情的展开状态；无论用户是否向上滚动或查看过工具详情，交接后默认收起过程并优先让结果正文可读；用户可通过“查看处理过程”重新展开。历史回放直接显示保存的结果，不重新播放交接。
+## 调查报告与自由对话的分工
 
-补充问题打断后继续执行时，依据提问记录的 `message_id` 和补充回答的 `delivery.native_message_id` 将前后过程归到续接答复下方；连续补充时沿同一关联链顺序归组。没有正文的旧过程消息不再单独占位，原有正文和用户补充回答仍保留。尚未出现续接答复、历史分页缺少关联消息、仍有待回答问题或审批、关联之间出现新用户请求时，保留原位置。该归组仅影响展示，不改原始记录或消息标识。
+后台调查的固定问答放在右侧调查报告的“补充回答”中，支持选项、自定义文字、提交状态和历史回答。任务通知打开该报告；提交直接保存到原任务并接续调查，无需创建或发送左侧聊天消息。数据缺口旁的“回答当前调查问题”定位到报告内待答表单。
 
-生成中、补充后续接和历史恢复共用一个处理过程容器，边框、背景和内边距保持一致；各段执行记录合并为一份列表，不再嵌套另一张“执行进度”卡片。步骤显示身份包含来源消息，避免前后轮次的同名步骤互相覆盖；生成时统一控制整个过程的最近三项与展开全部，完成后由底部入口统一折叠。
-
-已提交的回答以原生用户消息 ID 保存纯净文本和 `data-interaction_reply` 快照，首屏即可还原同一张“已回答”卡片并归组前后过程，不等待独立提问接口。该接口返回较新修订后更新投递状态和重试操作。旧历史由 Agent 按所属会话中已保存的投递 ID 补齐相同表示，不通过文本前缀猜测对应关系，也不改写历史文件。给模型的“用户提交的提问回复”协议前缀只用于推理输入。
+左侧 Agent 保留自由讨论、追问和进一步分析。“Agent 协作”和“讨论此缺口”是明确的讨论入口；固定任务回答不经过这些入口转发。

docs/agent-interaction-state-design.md

@@ -0,0 +1,375 @@
+# Intelligent UI 交互状态补齐设计
+
+> 2026-10-30 产品决定：数据组件仅用于展示与本地浏览，已移除表格勾选、分析内容篮及组件追问；专用地图定位和补充资料表单保留。本文分析篮、行选择和引用操作的方案属于历史设计，不再作为当前实施目标。阅读位置、表单草稿及宿主提问的独立设计仍可参考，当前行为以 [本地交互式回答](agent-answer-ui.md) 为准。
+
+历史设计状态：2026-10-27 设计稿；2026-10-28 第 11 节宿主提问已接入工作区代码，其余补齐项仍待实现。当前代码进度见 [本地交互式回答](agent-answer-ui.md)。本设计补齐阅读位置、分析篮和正式报告的私人交互状态，不改变模型可生成的 `answer-ui@1` 组件协议。第 11 节单独处理 question 的执行生命周期。
+
+## 1. 目标与方案
+
+用户刷新后，再次打开同一回答或同一版报告，可以继续阅读、筛选和填写资料。恢复只改变当前用户的界面，不发送消息、不提交表单、不调用业务工具、不定位地图，也不自动打开窗口。
+
+推荐保留已实现的聊天控件状态接口，新增阅读与分析篮的补充记录；正式报告的状态由 Server 按当前读者保存。三种记录独立比较版本，避免滚动保存与表单输入、选行互相冲突。前端继续复用受控 store 和现有保存协调器，只由来源适配器决定请求 Agent 还是 Server。
+
+最小方案是仅增加会话内存缓存，但刷新后仍会丢失，不能满足目标。把全部状态塞入原接口会破坏旧客户端的严格校验，也会让分析篮挤占控件的 32 KiB 限额，因此采用补充记录。正式报告不能借用 `source_session_id` 保存：它指向发布报告的执行会话，报告读者未必拥有这个会话。
+
+新增服务、账号、密钥和环境变量均为零；正式报告需要在已有项目 BizDB 增加一张私人状态表。预计涉及三个仓库、超过 8 个实现文件，按第 10 节拆成可独立交付的两批。
+
+```text
+聊天最终回答 -> Agent 来源适配器 -> 已授权会话 / 控件记录 + 补充记录
+                                      ^
+                                      |
+读取/编辑 -> 前端状态协调器 -> 受控组件、阅读位置、分析篮
+                                      |
+                                      v
+指定版本报告 -> Workbench 来源适配器 -> Server 报告权限 / 当前读者状态
+
+用户主动“带入对话” -> 现有输入区 -> 用户确认发送 -> 既有 Agent 流程
+```
+
+基础能力沿用 [json-render 的运行时状态支持](https://json-render.dev/docs/data-binding) 和 [React 的外部 store 订阅](https://react.dev/reference/react/useSyncExternalStore)。阅读容器尺寸变化使用 [ResizeObserver](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver) 观测；这些机制不替代宿主的权限、持久化和版本校验。实现以仓库当前安装版本为准，不因本设计升级依赖。
+
+## 2. 当前依据与状态分工
+
+| 当前实现 | 补齐方式 |
+| --- | --- |
+| `answer-view-state@1` 保存图表、表格、表单、证据状态 | 保留接口、32 KiB 限额和迁移规则；复用其保存/恢复机制 |
+| `ExpandableReading` 用 `useId()` 标识实例；阅读偏移放在 DOM dataset | 注入业务来源身份；只保存可序列化的阅读位置，DOM、host、focus 回调留在内存 |
+| Markdown 表格的行内和放大视图是两份 DOM，图示可移动同一个 host | 按阅读面分别记录位置，不假设搬动 DOM 等于持久化 |
+| `AnswerUiView` 的分析篮只存 `{title,text}`，意图由 Tray 的 `useState` 保存 | 增加来源、选择描述和摘要；篮与意图一起受控保存 |
+| `InvestigationReportBlocks` 接收报告快照，并用任务证据覆盖 Evidence 展示 | 按报告版本及当前读者加载状态；两端核对实际渲染内容摘要 |
+| 正式报告属于项目任务，读取使用 `operational_task.view` | 私人状态沿用报告读取权限，不要求读者拥有发布会话，不写回正式报告 |
+
+| 记录 | 持久化内容 | 保持临时的内容 |
+| --- | --- | --- |
+| controls，按块 | 现有节点控件状态和证据类别筛选 | 请求中的 loading/error、悬停、菜单和下拉框开关 |
+| reader，按文档 | 阅读面的位置、锚点、局部偏移和内容摘要 | 是否打开弹窗、当前焦点、地图相机、窗口尺寸、DOM 引用 |
+| basket，按块 | 有序选择项、来源描述、选取时文本快照、分析意图 | 正在带入对话、临时提示、浏览器文本选区 |
+
+说明：分析篮仍以一个回答块为边界，本次不扩展为跨消息、跨报告的全局收藏。证据大分区、范围工具栏的折叠开关沿用当前内存行为；它们不决定所选数据。Mermaid 平移/缩放也只在当前实例内保留，重新打开时按可用空间适配，不保存会随图形重新布局失效的像素变换。
+
+## 3. 身份与版本
+
+| 来源 | 文档身份 | 块身份 | 权威校验 |
+| --- | --- | --- | --- |
+| 聊天 | 当前主体、个人/项目范围、sessionId、assistantMessageId | 文档身份 + blockId | Agent 校验会话归属、已保存的助手消息及最终回答引用；旧版没有 final 的记录沿用既有兼容规则 |
+| 正式报告 | 当前 user_id、project_id、task_id、report_revision | 文档身份 + blockId | Server 校验当前成员身份、`operational_task.view` 和指定报告是否存在 |
+
+`nodeId` 来自验证后的 `spec.elements` 键；不得使用标题、数组当前序号、React `useId()` 或 DOM selector 作为业务身份。客户端不能指定状态所有者，主体和项目必须来自服务端认证上下文。
+
+报告的 `revision` 在任务内唯一，`execution_generation` 由服务端从报告推导并回传，不作为另一个客户端命名空间。历史 `null` 保留为 `null`，不能替换为 0 或任务当前轮次。文档与块的 `state_revision` 是私人交互版本，不能与报告 revision 混用。
+
+打开任务仍默认查看当前报告，不自动恢复为上次选中的历史版本。用户主动选择某个版本后才恢复该版本的状态。新报告使用新的身份和空状态，不自动复制旧版表单或分析篮；旧版记录保留供用户回看。放大窗口保留旧版内容时，状态写入也绑定当时的旧版，直到用户点击“查看最新内容”。
+
+最容易失效的前提是“相同 blockId 就是相同数据”。本设计用内容摘要、节点类型和选择描述复核，无法唯一匹配时保留可核对的草稿并清理无效选择，不将旧数组下标套到新数据。
+
+## 4. 记录与接口
+
+### 4.1 保留现有接口，新增补充接口
+
+| 所属服务 | 接口 | 状态范围 |
+| --- | --- | --- |
+| Agent，已有 | `GET/PUT /api/v1/session/:sessionId/ui-state` | 聊天 controls，保持原 `answer-view-state@1` 协议 |
+| Agent，拟新增 | `GET/PUT /api/v1/session/:sessionId/interaction-state` | 聊天 reader 或 basket；以 message_id、kind 和 basket 所需的 block_id 定位 |
+| Server，拟新增 | `GET/PUT /api/v1/operational-tasks/:taskId/reports/:reportRevision/interaction-state` | 正式报告 controls、reader 或 basket；controls/basket 需要 block_id |
+
+GET 的 kind 只有 `reader`、`basket`，Server 额外允许 `controls`。reader 属于整个文档，不接受 block_id；其内部阅读面可以引用块。GET 无记录返回对应空 payload、state_revision 0 和当前内容摘要，不写入空记录。未知 kind、无效字段或不存在的块返回 400/404，不隐式建立来源。
+
+GET 选择器放在 query，PUT 放在 body；Agent 两种方法均要求 message_id，Server 报告身份只取 URL。PUT 另要求 `version="ui-interaction-state@1"`。两端错误在前端适配器内统一为 code、message、current：Agent 沿用顶层 code/detail，Server 沿用现有 detail envelope，不让通用组件处理两套响应形状。所有响应使用 private/no-store。
+
+新接口的记录版本为 `ui-interaction-state@1`。字段固定如下；不接受任意对象透传。
+
+| 字段 | 规则 |
+| --- | --- |
+| `source` | 只出现在响应中，返回服务端确认的聊天或报告身份；不返回用户 token、宿主路径 |
+| `kind`、`block_id` | 标识记录种类及块；reader 的 block_id 不存在 |
+| `state_revision` | 每个记录独立的非负整数，只出现在响应中 |
+| `source_digest` | 服务端规范化内容的 SHA-256；PUT 原样带回，用于拒绝过期内容上的保存 |
+| `payload` | 由 kind 选择严格 schema，字段见第 5、6 节；report controls 使用已有 nodes/block 的允许字段与迁移规则 |
+| `updated_at` | 服务端写入时间；空记录为 null，不用客户端时间决定覆盖顺序 |
+| `item_status` | 仅 basket 响应包含，按 item_id 返回当前有效性与原因；不接受客户端写入 |
+| `expected_revision`、`request_id` | 只用于 PUT；版本比较和最近请求重试沿用现有规则 |
+
+选择器对应的身份摘要、version、revision 和请求标识均受限长与整数范围校验。source_digest 为 64 位小写十六进制；request_id 为 1 至 128 字符；message_id 为 1 至 200 字符；block_id 沿用原协议。state_revision/expected_revision 使用 JavaScript 安全整数范围，禁止负数或溢出。
+
+`source_digest` 的材料：聊天 reader 为已发布报告文字与引用块，basket 为所在块的实际 spec；报告 reader 为指定版本的报告正文及其可见证据投影，controls/basket 为对应块的实际渲染 spec。规范化 JSON 对对象键排序，数组顺序不变，摘要算法跨语言使用同一组固定测试样例。摘要是过期检查依据，不是客户端提交文字的真实性证明。
+
+### 4.2 正式报告的 Evidence 投影
+
+报告原 spec 与实际显示的 Evidence 可能不同：当前实现从任务证据补充摘要、来源、时间、类别，找不到证据时显示提示文本。Server 与前端必须采用相同投影规则，控件验证及摘要计算以投影后的 spec 为准。
+
+Server 状态读取先按现有报告/证据访问规则取得来源，计算投影及 source_digest；前端对已经加载的报告与证据执行同一规则并计算摘要。两者不一致时，不把旧状态应用到当前节点：对指定报告和任务证据做一次有界刷新，再核对摘要；仍不一致则显示“内容已更新，交互状态暂未恢复”，允许用户重试，禁止无限刷新。无需在状态响应中再复制整份报告或原始图表数据。
+
+PUT 在事务中重读报告和证据，投影变化返回 409 `UI_INTERACTION_SOURCE_CHANGED`，并返回当前记录和摘要。前端先更新来源，再迁移合法控件；无权访问的证据不以篮子快照重新显示。此投影规则需要前后端共用测试样例，不能各自猜测字段映射。
+
+### 4.3 存储与容量
+
+聊天补充记录放在宿主 `chat/answer-interaction-state.json`，加入 `SessionWorkspaceStore` 允许列表，复用同一队列、所有权校验、删除标记及原子写入。已有 controls 文件保持不变，旧客户端读写不会抹掉新状态。新文件每个 document reader、每个 block basket 独立版本，文件总量最多 1 MiB，包含回执；与已有 controls 文件合计最多 2 MiB/会话。
+
+正式报告新增项目 BizDB 表 `workbench.report_user_view_states`，每个 `(project_id,user_id,task_id,report_revision)` 一行，JSONB document 内分别保存 controls、reader、baskets 和最近回执。每个子记录有独立 state_revision；行锁只用于版本比较、容量检查和原子替换，不把滚动和表单合并成一个逻辑版本。报告外键 `(project_id,task_id,report_revision)` 使用物理删除级联；user_id 来自 `ProjectContext`，不建立跨数据库外键。
+
+首次写入采用插入空行且忽略唯一键冲突，再锁定同一私人状态行，避免两个 revision 0 请求同时成功。事务失败回滚空行和状态修改；报告删除由外键与事务约束阻止迟到写入复活。状态表不是报告事实表，保存私人状态只要求报告读权限，不借此授予任务写入或审批权限。
+
+拟新增迁移 `next-tjwater-server/resources/sql/026_report_user_view_states.sql`，沿用项目 BizDB 显式迁移流程。当前最高编号为 025，实施时若编号已占用，顺延编号。接口不执行建表；未迁移的项目返回安全的 503，报告仍可阅读，草稿留在当前内存。
+
+| 项目 | 限额 |
+| --- | --- |
+| controls payload | 32 KiB UTF-8/块，沿用现有节点数量和字段限制 |
+| reader payload | 8 KiB UTF-8/文档，最多 16 个阅读面 |
+| basket payload | 64 KiB UTF-8/块，最多 8 项；正文组合不超过现有 8000 个 UTF-16 代码单元；分析意图最多 800 个 UTF-16 代码单元 |
+| 正式报告私人状态行 | 1 MiB，计入所有子记录和回执 |
+| 补充记录重试回执 | 每个聊天补充文件或报告私人状态行，最近 32 条且最多 128 KiB；过期请求仍受旧 expected_revision 阻止重放 |
+
+大小检查包括标识与元数据的序列化体积，不截断表单或选择内容来勉强保存。超限返回 413，保留当前草稿，提示先减少分析篮内容或清除不再需要的记录。业务限制 8000/800 由三端按相同 UTF-16 计数规则校验，不能用 Python 字符数直接替代。发送消息时仍检查问题、意图、引用及来源说明的完整文本是否超过现有 10000 限额。
+
+不按每次滚动追加历史；当前快照覆盖、回执有界。记录数量随实际访问的用户/报告组合增长，使用上述复合主键直接读写，不扫描全部用户状态；本版本不增加自动 TTL，避免无提示删除草稿。
+
+## 5. 阅读位置
+
+reader payload 为 `positions` 和 `recent_reader_keys`，前者按宿主生成的 readerKey 保存位置，后者是最近使用顺序。两者最多 16 项且键集合一致；位置键、锚点 id 最多 200 个字符，不接受 DOM selector 或脚本。每项位置字段如下。
+
+| 字段 | 含义 |
+| --- | --- |
+| `content_digest` | 该阅读面实际内容的摘要；用于判断是否可复用整体滚动比例 |
+| `anchor` | 可空的 `{kind,id,occurrence}`；kind 为 section、node、markdown，id 来自稳定业务键或规范化 Markdown 块摘要 |
+| `anchor_offset_ratio` | 锚点内部偏移，有限数值，范围 0 到 1 |
+| `scroll_y_ratio`、`scroll_x_ratio` | 容器可滚动距离的比例，范围 0 到 1；无可滚动距离时为 0 |
+
+readerKey 只由宿主注册：`workspace`、`report-result`、原生 `blockId/nodeId` 对应阅读面，以及 Markdown 内容块摘要派生的表格/图示阅读面。纯文本最终回答也可建立 document reader，无须伪造 answer-ui 块。标题或“第 n 个表”不是跨内容更新的稳定键；相同内容重复出现时 occurrence 只在摘要相同的文档内使用。
+
+这里只保存版本明确的内容。当前调查进展、实时任务时间线、审批卡和报告版本选择器仍属于实时任务界面，不绑定到某个报告 revision 的阅读状态。用户输入、审批焦点和地图位置均不通过 reader 恢复。
+
+恢复流程：
+
+1. 用户主动打开对应阅读面，绑定不可变的 source 身份并订阅状态。尚未加载历史消息/报告时不为了恢复位置自动翻完全部历史，也不自动切换会话或报告版本。
+2. 内容挂载、控件恢复和必要字体准备完成后，用连续两帧相同尺寸判断可定位；最多等待 1500ms。`ResizeObserver` 仅用于这次定位，不能持续把用户拉回旧位置。
+3. 优先定位仍唯一存在的锚点，再恢复锚点内部偏移。没有锚点但 content_digest 相同，则使用整体滚动比例；内容已变化且锚点无法对应，回到本阅读面起点，提示“内容已变化，原阅读位置无法恢复”。
+4. 比例始终按当前实际滚动范围计算并夹紧；窄屏和宽屏互切不能直接复用旧像素 scrollTop。Markdown 行内与放大表格使用不同 readerKey，横向位置也分别记录。
+5. 每次主动打开最多执行一次自动定位。等待期间出现用户滚轮、触摸、指针按下、滚动键、文本选择、编辑或内容导航，则取消自动定位；迟到 GET 只进入缓存，不移动当前视口。需要回到上次位置时由用户点击入口。
+
+阅读保存使用 1000ms 防抖，连续滚动每 5 秒最多提交一次；关闭阅读面或切换来源时保存最后位置。位置未变化不发送；程序恢复产生的 scroll 事件不标记为用户编辑，不反向触发保存循环。最多 16 个位置，超出时只淘汰最久未使用的阅读位置，保留当前阅读面；分析篮和表单不参与此淘汰。
+
+reader 冲突不弹出阻断窗口：保留当前视口，接收远端的新 revision 供下一次真实用户滚动保存，显示轻量“阅读位置未同步”状态；不自动覆盖远端，也不因远端更新跳动当前页面。下次用户操作只更新对应位置，合并远端其他阅读面的位置和最近使用顺序，不能用整个旧 positions 覆盖它们。网络失败可随下一次用户滚动重试或由用户手动重试。
+
+## 6. 分析篮与表单草稿
+
+basket payload 为同一份 `{items,intent}`。items 是有序数组，新增、移除、清空和意图编辑由一份受控状态管理；不拆成八个各自保存的项目。
+
+| 选择项字段 | 规则 |
+| --- | --- |
+| `item_id` | 本地生成的稳定 UUID，保存与重排时保持；不用于权限证明 |
+| `node_id`、`selection_kind` | 必须对应来源中的真实节点；首批 kind 为 metric、table_rows、chart_point、chart_range |
+| `selector` | table_rows 为原始行索引及数据摘要；chart 为点/区间索引、对应标签、可见序列索引与名称；metric 不带行索引 |
+| `source_digest` | 选取时所在块的有效内容摘要，由已读取来源取得 |
+| `title`、`snapshot_text` | 选取时的纯文本显示快照，title 最多 200 个 UTF-16 代码单元；正文计入组合总限额 |
+
+服务端校验节点类型、索引上限和选择描述，并校验来源摘要；快照文本是用户引用内容，不提升为事实证据，不执行其中指令。它是“不复制原始数据”原则的有界例外，只保存用户明确选取的文本，不保存整份时序数据。正式报告的 evidence_refs 及报告身份由宿主从块与报告补充，不信任客户端伪造来源。
+
+去重依据是节点、选择描述和选取时内容摘要；不同节点即使文本相同也可分别选取。每个选项保留当时的文本，不随筛选、排序或数据更新悄悄重算。服务器计算恢复状态为 valid、stale 或 unavailable，客户端不能提交该标记：
+
+- 内容仍一致为 valid，正常使用。
+- 节点仍存在但数据/结构摘要变化为 stale，显示“内容已变化，此项为先前快照”；保留快照供核对，整篮“带入对话”暂不可用，须移除该项或从当前内容重新选择。不会自动迁移篮中行索引。
+- 来源节点或证据已不可用时为 unavailable，停止返回相关快照文本，只保留可移除的占位；不得通过篮子绕过当前来源访问规则。整个文档失去权限时按第 8 节处理。
+
+新增选择只接受当前 source_digest；已保存的 stale 项可以原样保留或移除，不能借保存意图修改它的快照/来源。兼容校验先按 item_id 对比已存项，再检查新增项。无法自动迁移时不将 stale 项冒充当前数据。
+
+GET 响应另有 `item_status`，按 item_id 返回状态及简短原因，不混入可写 payload。unavailable 项以相同 item_id 和来源标识返回，title/snapshot_text 使用固定不可用提示；PUT 只能保留这个经过屏蔽的占位或删除它。幂等重试返回回执前也要重新检查当前来源可用性并屏蔽不可用文本，不能直接回放旧的含文本响应。回执确认原写入版本，不构成允许再次显示旧快照的授权。
+
+items 与 intent 分别记录 dirty 路径；清空动作原子设置 `items=[]`、`intent=""`，即使值为空也保留 dirty 标记，迟到 GET 不得把旧项目重新并入。清空保存期间又新增内容时，旧回执只能确认它发送时对应的修改序号，新内容继续保留并按新 revision 保存。
+
+“带入对话”只复制捕获的篮内容和意图到现有输入区，成功后仍保留篮子。异步回调同时捕获 source、目标 session 和当前作用域代次；用户已切换项目/会话时，旧回调不得填入新的输入区。实际发送继续由用户确认，失败不清空篮或表单。
+
+表单草稿沿用现有控件存储。普通聊天发送成功后，只清除与该次发送快照仍相同的字段；发送期间新输入的字段保留。正式报告的表单默认带入对话，未获得实际发送确认前不清草稿。恢复只填充字段，不调用提交回调，不把报告表单写入正式证据。
+
+## 7. 保存与冲突规则
+
+共同流程为读取、合并本地编辑、待保存、保存中、已保存；异常分为未保存、冲突、来源变化和失去访问权限。展示不要求网络先成功，写入必须等已知 revision 和来源摘要。控件及分析篮继续使用 500ms 防抖，读取失败只保留一次首次编辑触发的补读，其余由显式重试触发，不轮询。
+
+| 情况 | 处理 |
+| --- | --- |
+| GET 比用户编辑晚到 | 按 dirty 字段合并；items 是一个整体，不做数组 union；清空和删除也不能被恢复覆盖 |
+| PUT 尚未返回又发生编辑 | 保留更新的 changeSeq；回执只清除已确认的旧 dirty 字段，再保存后续版本 |
+| 响应丢失，无法判断写入是否成功 | 先以原 request_id 和原始 payload 重试；确认后再发后续编辑 |
+| 409 `UI_INTERACTION_STATE_CONFLICT` | controls/basket 保留本地草稿，停止自动重试；允许“保留本地并重新保存”或确认后“加载远端” |
+| 409 `UI_INTERACTION_SOURCE_CHANGED` | 先有界刷新来源并兼容迁移；不可直接拿新摘要覆盖旧索引；stale 篮项目按第 6 节处理 |
+| 同 request_id 携带不同 payload | 409 `UI_INTERACTION_REQUEST_CONFLICT`；视为客户端错误，保留草稿，不能自动换 ID 继续重放 |
+| 413 或服务不可用 | 保留内存草稿，说明未保存；不切片、截断或循环提交 |
+| 服务端确认目标回答正在生成或等待落盘 | 返回 503 `UI_INTERACTION_SOURCE_NOT_READY`，保留草稿；首次用户编辑可触发一次补读，之后显式重试，不等同于来源被删除；仅会话存在不能证明回答正在落盘，不存在的来源仍返回 404 |
+| 临时 401 | 沿用现有认证刷新机制；不能因此扩大权限或换用其他主体保存 |
+
+来源摘要冲突必须先解决来源变化，再决定是否覆盖交互版本；“保留本地”不是绕过数据校验。不同浏览器不增加 WebSocket 或后台同步：打开来源时读取，保存时发现冲突。自动读取到较新状态也不能改动用户正在操作的视口或表单。
+
+状态提示按记录聚合：“已保存”表示本界面当前脏记录全部已确认；控件已保存而篮子未保存时明确标出分析篮。纯阅读位置同步异常只在阅读面显示轻量状态，不让每次滚动占据对话通知区。
+
+“加载远端”的确认绑定当前记录和确认时的 changeSeq；确认后又出现新的本地输入，旧确认结果不得覆盖它，应保留新输入并重新呈现冲突选择。
+
+## 8. 清理、权限与删除
+
+- 切换会话时，未失败的待保存写入仍使用捕获的旧 source；新来源创建独立订阅。组件卸载不立即丢掉同一认证作用域内的草稿。
+- 登出、切换主体或项目时，取消未发送计时器、移除旧订阅并清理对应缓存。已发出的请求不能撤销既成写入，但回执不得进入新的作用域。
+- 401 经认证处理确认失效、403 或来源不存在的 404，关闭来源恢复通道，清除该来源缓存中的正文快照和草稿，不在新用户界面显示；不能将这些响应当普通离线错误长期保留敏感快照。后续重新获得访问权限时重新授权读取。
+- 显式“清空”使用带 expected_revision 的空 payload 写入，并增加 state_revision；保留空记录和近期回执，不删成 revision 0，防止迟到保存使已清内容复活。表单、篮和 reader 各自清空，不连带删除业务报告。
+- 聊天删除沿用宿主删除标记与队列，清除两个状态文件；聊天分叉不复制私人控件、篮和阅读位置。
+- 正式报告物理删除时由外键级联删除私人状态。任务取消、源撤回或进入新轮次不等于报告删除；只要旧报告仍按现有规则可读，其私人状态继续按旧 revision 保留。
+- 每次 GET/PUT 重新检查报告权限。成员撤权对后续请求生效；已经通过鉴权的在途请求可能按当时权限完成，不承诺跨 metadata 与 BizDB 事务的即时强撤回。错误响应不能返回其他用户状态或证据快照。
+
+## 9. 验收矩阵
+
+| 场景 | 必须满足的结果 |
+| --- | --- |
+| 刷新后主动打开同一回答/报告 | 恢复控件、篮意图和阅读位置；不自动打开弹窗、定位地图或发送消息 |
+| 桌面与 320px 窄屏互换 | 锚点/比例按新布局恢复，表格横纵滚动均有效，无越界和全页横向溢出 |
+| 阅读恢复晚到、字体/图表延迟渲染 | 用户未操作时最多定位一次；用户已滚动或导航后不抢位置；1500ms 后不无限等待 |
+| 同一 Markdown 内有重复标题/表格 | 同内容版本可按 occurrence 恢复；内容改变后匹配不唯一只清该位置 |
+| 篮清空后 GET 或旧 PUT 回来 | 已清项目不复活，清空之后的新编辑不丢失 |
+| 数据换序、重复标签、列变化或 Evidence 消失 | 控件执行明确迁移；篮快照标为 stale/unavailable，不静默换成别的数据 |
+| 报告当前版变成下一版 | 旧阅读窗仍向旧版保存；用户选择新版本才加载其独立状态 |
+| 两位有报告权限的用户 | 可分别保存同一报告，不能互读或互相冲突；均不要求拥有 source_session_id |
+| 同一用户两窗口修改 | 控件/篮出现明确冲突；阅读位置不跳动；原请求重试不增加重复版本 |
+| 状态保存中切换用户、项目或来源 | 旧响应和带入对话回调不污染新作用域；失去权限不返回缓存快照 |
+| 32/64 KiB 边界、emoji/CJK、文件或报告行满额 | 字节和 UTF-16 限制一致，失败不截断、不丢当前草稿 |
+| 会话删除、报告删除、空记录清除竞态 | 不复活删除对象，不把空记录误当从未保存 |
+| Server 项目未迁移或接口回退 | 保持可读和当前内存交互，明确未保存；旧版聊天 controls 接口继续工作 |
+| 回答正在落盘与来源已删除 | 前者保留草稿并有界重试，后者清理来源缓存；不能将普通 404 无限转成等待 |
+| reduced motion、键盘打开和关闭 | 定位不增加动画；恢复不抢焦点，关闭回到触发按钮 |
+
+单元测试覆盖状态归一化、dirty/tombstone、字节预算和迁移；浏览器使用有意延迟、响应丢失和冲突的模拟接口验证行为；Server/Agent 聚焦测试验证真实存储事务、权限和删除。最后以隔离 Agent、已授权项目和真实报告完成保存读回，明确区分模拟接口与真实服务结果。
+
+## 10. 实施顺序与文件交接
+
+第一批补齐聊天 reader/basket，可独立上线，不等待报告表迁移。
+
+| 仓库 | 修改位置 | 工作 |
+| --- | --- | --- |
+| frontend | `src/features/agent/session-state/`、`src/features/agent/api/` | 增加补充记录 schema 与来源适配器，复用现有队列/dirty/retry；保持旧 controls 接口 |
+| frontend | `answer-ui/answer-selection.ts`、`answer-selection-tray.tsx`、`answer-ui-interactions.tsx`、`answer-ui-view.tsx` | 选择描述、稳定项目身份、受控 items/intent、快照有效性及带入对话保护 |
+| frontend | `src/shared/ui/reading-workspace-context.ts`、`reading-workspace.tsx`、`src/shared/ai-elements/markdown-reading.tsx` | 只接收通用 source key 和位置读写回调；锚点、容器测量与恢复取消，不导入业务模块 |
+| Agent | `src/sessions/workspace-store.ts`；拟新增 `src/sessions/answer-interaction-state-store.ts`、`src/routes/answer-interaction-state-routes.ts`；`src/routes/chat.ts`、`src/server.ts` | 受控补充文件与新接口、来源校验、CAS、容量和删除 |
+
+第二批接入正式报告，复用第一批组件和补充记录协议。
+
+| 仓库 | 修改位置 | 工作 |
+| --- | --- | --- |
+| Server | 拟新增 `resources/sql/026_report_user_view_states.sql` | 项目 BizDB 私人状态表及报告删除外键 |
+| Server | 拟新增 `app/domain/schemas/report_view_state.py`、`app/services/report_view_states.py`、`app/infra/db/postgresql/report_view_states.py`；`app/api/v1/endpoints/operational_tasks.py` | 状态模型、Evidence 投影、读者权限、行锁、独立子记录版本和错误契约 |
+| frontend | `src/features/workbench/api/operational-task-client.ts`；拟新增 `api/report-view-state-client.ts` | 读取指定报告版本、通过现有项目请求头访问私人状态接口，解析 Server 错误 envelope |
+| frontend | `components/investigation-report-blocks.tsx`、`investigation-task-report.tsx`、`investigation-expand-card.tsx` | 显式报告身份、冻结阅读版本对应的状态绑定、投影摘要核对和只读者状态接线 |
+
+Workbench 通过 Agent 公共 API 注入保存适配器，Agent 组件不能反向导入 Workbench；shared 阅读组件只处理通用锚点与滚动，不接触 token、taskId 或业务请求。
+
+验证命令沿用各仓库 AGENTS：前端 `pnpm lint`、`pnpm typecheck`、`pnpm test`，新增 `tests/browser/agent-interaction-state.e2e.ts` 并回归既有阅读/状态用例；Agent `bun run check`，新增 `tests/sessions/answerInteractionState.test.ts`、`tests/routes/answerInteractionStateRoutes.test.ts`；Server 新增 `tests/unit/test_report_view_states.py`、`tests/api/test_report_view_states.py`，覆盖本节矩阵的存储与权限分支。新测试文件在实现时创建，本设计不将它们标为已存在或已通过。
+
+发布顺序：聊天先 Agent 补充接口、后前端；报告先对目标项目备份并应用迁移，再发布 Server 和前端。迁移必须包含可重复执行与旧报告外键校验，不能对未授权项目批量执行。回退前端保留两类状态文件与报告状态表；回退 Server 关闭新接口即可，不需要删除数据。每批完成后记录实际提交、迁移项目、服务版本和读回结果，不以本地测试代替发布验收。
+
+## 11. 宿主管理提问与回复
+
+2026-10-28 实施记录：已接入宿主存储、工具桥与门禁、问题卡、草稿保存、Responses 续跑及历史原生 question 核对。当前实现通过独立列表恢复问题，明确重试继续；尚未将全部历史请求嵌入会话详情的分页投影。已使用隔离原生实例验证固定输入 ID 去重与重启持久化，未调用付费模型验证实际工具选择和完整推理续跑。下述契约保留为设计与验收依据；未提交、未部署。
+
+原生验证发现：已回答或取消的 form 在重启后可能返回不存在。因此兼容入口优先保留宿主已知终态，未知且原生缺失的历史卡片显示失效；不能仅凭 form 缺失推断用户已经回答。新协议不依赖原生 form 保持等待状态。
+
+本次验证：Agent 静态检查及 67 项聚焦测试通过，追加边界修改后对应 13 项回归通过；前端 lint、typecheck、125 个文件共 655 项测试及生产构建通过。桌面和 320px 浏览器场景通过，一次重复运行在打开面板前超时，独立重跑通过。构建使用 Node 24.13.0，低于 package.json 要求的 24.22.1，发布前还需在规定 Node 版本复验。隔离原生检查不调用模型，不替代真实授权项目完整推理验收。
+
+### 11.1 决策与当前证据
+
+用户允许在必要时自行设计提问机制，不依赖 OpenCode 内置 question。推荐新增受控工具 `ask_user`：模型提出问题，Agent 宿主保存请求并结束当前模型轮次；用户提交答案后，宿主在原会话启动一次有身份绑定的续跑。等待人的时间不占用一个原生 question Promise，问题是否可回答也不由前端卡片判断。
+
+这不是替换推理引擎。继续使用 OpenCode 执行模型和既有工具，但提问协议、草稿、答案、取消及投递记录由宿主管理。正式报告 FollowUpForm 仍是补充资料入口，不自动变成阻塞提问；Shell/MCP 权限审批继续走原有审批通道，不由 ask_user 代替。
+
+当前代码依据：
+
+- 前端 `QuestionRequestCard` 的选项草稿在组件 `useState` 中；切换后重建组件会重新初始化草稿。
+- Agent 的 `chatInteractionRoutes.ts` 要求内存 `activeRuns` 和 `pendingQuestions` 存在；`runtime/opencode.ts` 随后读取并回复原生 form。历史卡片存在不能证明原生请求仍有效。
+- 当前切换会话不直接终止旧运行，尚未复现用户此前的错误，因此不能将历史故障确定归因为切换动作。
+- `ResponseInputTracker` 本身是内存 Map，不能直接当作持久化队列。可复用的是 runtime 中固定消息 ID、inbox 与 message 读回的投递核对，以及 `chatStream.ts` 在工具完成后中断并等待 idle 的已有轮次结束机制。
+
+最小替代方案是补原生 form 状态核对与选项缓存，改动较少，但恢复仍受原生请求生命周期约束。选择宿主方案是为了独立保存等待状态，不再为每次运行状态丢失拼接恢复逻辑。官方支持[自定义工具及独立工具名称](https://opencode.ai/docs/custom-tools/)；本站示例 API 与当前仓库 OpenCode 2 插件 API 不完全相同，实施使用本地 `.opencode/tool.ts` 和插件注册方式，不照搬官网导入路径。
+
+### 11.2 请求与草稿分离
+
+首批仅用于 `ordinary_chat` 和 `task_collaboration`，一个会话最多一个未解决的提问组，每组最多 3 个问题。后台 `task_execution` 不等待浏览器，继续使用缺失资料报告及人工证据流程。工具和浏览器都不能指定所有者、项目或目标续跑会话。
+
+新增宿主记录协议 `agent-interaction-request@1`，身份为已授权 actor/project/session + 宿主生成的 interaction_id。绑定原始消息、宿主 turn_id、工具 call_id；用 session/turn/call 唯一键去重创建，原生 form_id 不参与新协议。
+
+| 记录 | 字段和规则 |
+| --- | --- |
+| 提问定义 | 不可变的 questions；每题包含稳定 question_id、标题、正文、选项 id/label、single/multiple、allow_custom、required；每题最多 12 个选项 |
+| 请求状态 | revision、pending/answered/skipped/cancelled/invalidated、创建时间、解决时间；已回答答案不可覆盖，修正需发新消息 |
+| 草稿 | 独立 draft_revision、各题 selected_option_ids/custom_text；请求待回答时可保存；迟到草稿回执不能恢复终态请求 |
+| 用户答案 | 按 question_id 提交选项 ID 和自定义文字；宿主按原始定义补齐标签，拒绝不存在的选项、重复 ID 和非法多选 |
+| 续跑记录 | 稳定 native_message_id、queued/dispatching/delivered/blocked/cancelled、错误码和关联 response_id；与答案在同一次原子写入中建立 |
+
+所有 schema 严格校验。标识最多 128 字符；标题、问题正文、选项标签分别最多 200、2000、200 个 UTF-16 代码单元；每题自定义输入最多 2000，问题或答案的完整文本各最多 10000。定义最多 32 KiB，答案和草稿各最多 16 KiB UTF-8。默认选中不是已提交，也不能触发自动回复。
+
+新增 `chat/interaction-requests.json`，复用宿主所有权、原子替换、串行更新及删除标记，最多 2 MiB、1000 个请求，先到限额者生效；连同第 4 节两类状态文件，交互文件预算最多 4 MiB/会话。已解决记录保留用于重试和审计，不自动淘汰未回答项；满额拒绝新提问并返回普通文字说明，不截断已有答案。首次实现沿用单宿主进程拥有会话的部署边界，不能把进程内队列宣传为跨实例锁。
+
+### 11.3 提问、等待与续跑
+
+```text
+模型 ask_user -> 可信工具桥 -> 宿主原子保存请求 -> 问题卡片
+                                  |
+                             本轮结束，等待回答
+                                  |
+用户提交 -> 宿主保存答案和投递记录 -> 既有运行协调器 -> OpenCode 原会话续跑
+                    ^                    |
+                    +--- 按固定消息 ID 核对回执 ---+
+```
+
+1. 工具桥复用现有内部桥认证及运行会话上下文，session/turn/call 从可信上下文获得，模型参数只包含问题定义。严格注册工具 schema，拒绝模型传入身份、URL、命令或恢复回调。首次发布前确认没有其他正在执行的工具；同组并行调用时拒绝创建提问并要求在结果收齐后重试，不能把已开始的业务动作说成已撤销。
+2. 先原子保存 pending 请求，再发布含 interaction_id/revision 的事件。保存失败不显示可提交卡片。工具立即返回“已登记，等待用户”的结果，不挂起 Promise；宿主在原生工具结果完成后结束该轮并等待 idle，记录专门的 `waiting_input` 结束原因，不显示为执行失败或最终报告完成。
+3. 从登记成功到模型 idle，插件和宿主都拒绝该轮新工具调用，避免模型尚未收到答案就继续依赖答案执行。已有 final_answer 结束机制可复用，但 ask_user 的结束原因、落盘及重连投影需要单独实现；仅增加一句“请等待”提示词不满足验收。创建后崩溃时，宿主从持久记录重建等待状态并核对旧轮次，不继续旧的工具链。
+4. 浏览器显式提交答案，宿主比较请求 revision、验证答案并原子写入 answered 和 queued 投递记录，返回已保存回执。原轮次尚未 idle 时只排队，不并发启动第二轮。提交不能依赖 `activeRuns` 必须仍有旧对象。
+5. 抽取并复用既有 `/responses` 的会话启动、事件订阅、鉴权上下文、消息持久化和模型选择，建立单一运行协调入口，不从路由外直接裸调用 runtime.prompt。新轮次采用宿主固定 native_message_id，通过已有原生 prompt 的 id 能力投递结构化问题与答案，标注为用户回答，不伪装成原 question 工具返回值。
+6. 投递前先按固定 ID 查原生 inbox/message：已入队则接续观察，已消费则补记 delivered，仅确认不存在才投递。网络失败保留 dispatching 并核对，不生成新 ID。已消费后生成失败只允许继续该轮结果处理，不能再次注入同一答案；不承诺跨系统恰好执行一次业务动作。
+7. 宿主重启不会丢掉已保存答案。恢复在下一次已授权的会话打开、回复或用户重试时触发，先恢复事件订阅，再核对投递与原生运行状态；不持久保存 Bearer，也不在无有效用户上下文时自动发起推理。OpenCode 会话不可恢复时标记 blocked，允许复制答案，但不能悄悄创建新会话、重放整段业务操作或伪造工具结果。
+
+本方案最脆弱的前提是固定消息 ID 的核对能够区分未投递与已消费，以及提问后能形成可靠的轮次结束边界。上线门槛是用当前原生版本验证这两个行为；若无法确认，保持“答案已保存，继续失败”并停止自动重试，不回退到不受控的重复执行。当前设计没有执行这些原生故障注入验证。
+
+### 11.4 接口与 UI 行为
+
+接口均拟新增在 Agent 的 `/api/v1/session/:sessionId/interactions` 下，沿用会话鉴权；不建立 Server 表或引入新服务。内部创建桥为 `/internal/chat-interactions`，不对浏览器开放创建权限。会话详情增加未解决请求和当前消息页涉及的请求投影；独立列表使用稳定游标，默认 20、最多 50 条，不为恢复卡片拉取全部历史。
+
+| 方法与相对路径 | 行为 |
+| --- | --- |
+| GET 根路径；GET `/:interactionId` | 返回权威请求、当前草稿和续跑状态；以 interaction_id 去重，读取不自动回答 |
+| PUT `/:interactionId/draft` | 带 expected_draft_revision、request_id 和草稿；500ms 防抖，终态拒绝写入；与正式提交使用不同版本 |
+| POST `/:interactionId/reply` | 带 expected_revision、request_id 和完整答案；同请求同内容返回原回执，不重复建续跑记录 |
+| POST `/:interactionId/skip` | 所有问题均非必填时允许；原子记录 skipped 并安排一次明确的跳过输入，不编造默认答案 |
+| POST `/:interactionId/cancel` | 仅 pending 可取消；关闭提问且不续跑，用户可以改发普通消息 |
+| POST `/:interactionId/resume` | 只核对并继续原投递记录；不修改答案、不创建新的投递 ID |
+
+写接口均使用严格 version、expected_revision 和 request_id 校验，draft 使用自己的 revision；resume 比较续跑记录 revision。400 表示定义或答案非法，409 区分版本冲突、请求已解决与幂等键内容不一致，413 表示容量不足，503 表示服务暂不可用。回复已落盘但模型暂不可用时返回已保存状态及 queued/blocked，不把答案当作提交失败让用户反复重发。GET 使用 private/no-store，权限失效与删除沿用第 8 节。
+
+前端复用 shadcn 的 RadioGroup、Checkbox、Textarea、Button、状态提示和现有卡片布局，独立封装宿主提问卡，不新增任意代码渲染。可恢复的状态如下。
+
+| 状态 | 界面和操作 |
+| --- | --- |
+| 核对中 | 显示问题与草稿，提交暂不可用；不能凭历史 pending 直接放行 |
+| 待回答 | 支持单选、多选、自定义输入，草稿保存提示；必填项不提供跳过 |
+| 提交中 | 禁止双击；保留完整输入；响应丢失按同请求 ID 核对 |
+| 已回答，等待继续 | 只读显示已确认答案和续跑状态；重试只操作续跑记录 |
+| 已回答并继续 | 显示答案摘要和后续回复；不再展示提交按钮 |
+| 已跳过、已取消、已失效 | 展示对应原因，不显示可点击的过期选项；不统一称为“状态丢失” |
+
+切换对话只切换订阅，旧回执绑定旧 session/interaction，不改变新对话；切回与刷新时先读权威状态，再合并当前作用域未保存的草稿。打开页面不自动提交、弹窗、聚焦或滚动。两窗口提交不同答案只有一个成功，另一窗口显示服务端已接受答案；保留冲突输入供复制，不覆盖已经提交的答案。
+
+有 pending 提问时，普通输入区提示先回答或取消；服务端也拒绝绕过等待直接启动新一轮。已提交答案的续跑排队时同样阻止抢占，避免问答顺序错乱。“停止”会显式取消仍 pending 的提问；已经提交的答案仍保留，未投递记录可停止，已投递的运行沿用既有停止语义，不伪造未执行状态。停止与投递通过同一会话协调入口串行化。
+
+### 11.5 兼容、实施与验收
+
+新请求使用独立类型和 ID，不把历史原生 question 卡片直接改成宿主 pending。旧请求读取时核对原生状态：仍待回答才保留旧回复入口，已回复/取消则同步终态，明确不存在时显示已失效；503 时显示暂不可核对，不能误判失效。用户可以复制旧问题另起交互，但不会自动替旧工具伪造回答。
+
+前端通过 `host-question@1` 能力声明支持新卡片，宿主在每轮启动时固定能力快照。有能力的新轮次注册 ask_user 并禁用内置 question；旧客户端不生成其无法操作的新卡片。既有原生请求的回复路由保留。灰度按新轮次边界生效，不热替换正在等待的工具。旧客户端打开新记录至少能看到文本和已解决状态，待回答请求提示使用支持该能力的客户端，不能静默降级后绕过等待。
+
+该项可在 reader/basket 和正式报告持久化之前独立交付。预计涉及 Agent 与 frontend 两个仓库、超过 8 个文件；新增服务、数据库、账号、环境变量均为零，内部桥复用现有服务凭据。
+
+| 位置 | 交付内容 |
+| --- | --- |
+| Agent `.opencode/tools/ask_user.ts`、`.opencode/plugins/tjwater-tools.ts`、工具与 instruction 策略 | 新工具、严格 schema、轮次能力判断和等待期工具约束；前者为拟新增文件 |
+| Agent 拟新增 `src/sessions/interaction-request-store.ts`、`src/routes/interaction-request-routes.ts`、`src/routes/chat-interaction-bridge.ts` | 单文件事务、草稿版本、原子答案/投递记录、内部创建与用户接口 |
+| Agent `src/sessions/workspace-store.ts`、`src/routes/chatStreamRoute.ts`、`chatStream.ts`、`chatSessionRoutes.ts`、`src/runtime/opencode.ts` | 文件允许列表、提问轮次结束、共享运行入口、重连核对、稳定消息 ID、删除及旧请求兼容 |
+| frontend `src/features/agent/api/`、拟新增 `components/agent-interaction-request-card.tsx`、`src/features/workbench/hooks/agent-session-runtime.ts`、`use-workbench-agent.ts` | 协议解析、受控提问卡、草稿保存、请求状态核对与会话隔离 |
+
+验收必须包括：A 会话提问后切到 B 再切回提交；刷新恢复草稿；两窗口同时提交；清空草稿后的迟到 GET；提交成功但回执丢失；原生已消费但宿主未记回执时崩溃；宿主重启后授权恢复；原生会话丢失；提问与另一工具并行；提问后模型继续调用工具；停止与续跑竞争；旧客户端及旧 question；权限失效和会话删除。前端覆盖键盘操作、320px 窄屏、焦点及 reduced motion。
+
+实现时运行前端 `pnpm lint`、`pnpm typecheck`、`pnpm test` 和拟新增浏览器 `tests/browser/agent-question-lifecycle.e2e.ts`；Agent 运行 `bun run check`，为状态存储、路由及原生续跑新增聚焦测试。浏览器模拟通过后，还需隔离原生运行验证固定 ID 与故障恢复，不能把模拟 Map 的幂等行为当作 OpenCode 的保证。
+
+发布先增加服务端读写、文本投影与旧请求核对，再上线客户端，最后在支持能力的新轮次启用 ask_user。回退时先停止创建新请求，保留新协议的读取、提交和续跑兼容接口，直到待回答及待投递请求被解决或用户取消；不能直接删除接口把已发布问题遗留成死卡片。记录和答案始终保留，不因回退重置 revision。

docs/investigation-dev-tools.md

@@ -0,0 +1,106 @@
+# 调查任务展示与 Dev 测试
+
+可直接打开顶部 Dev 入口载入、编辑、校验并执行本地测试案例，无需先选择调查或开启实时跟随。纯数据和界面块可独立预览，包含地图或图表展示指令时需等待地图就绪。验证实际调查联动时，在“工况任务 → 调查任务”选择一项任务，再打开 Dev。Dev 默认打开“调查测试”页签，保留当前选择，显示调查代次、实时图表数、已保存报告中的图表/表格/地图入口数，以及最近的展示动作。上一轮报告会明确标注，不当成本轮新成果。
+
+Dev 分为“调查测试”和“地图调试”两个页签：前者按“准备数据 → 校验与执行 → 检查结果”组织 JSONL 流程，后者保留要素定位、水流、图层和标注工具。切换页签保留输入与展示状态，不清除当前预览。地图重置操作仅显示在地图调试页。
+
+## 当前识别链路
+
+| 内容 | 来源和行为 |
+| --- | --- |
+| 实时地图、图表和覆盖层 | 从工作台事件流读取 `operational.presentation.requested`，核对所选 task、run 和 generation，验证命令后使用调查展示控制器执行 |
+| 已保存的结构化界面 | 任务报告的 `ui_blocks` 使用既有 `answer-ui@1` 校验及 json-render 组件；未知或不合法的内容不作为可执行界面 |
+| JSONL 数据 | Dev 中显式载入、校验后在展示面板预览；调查数据行仅展示，只有受控展示指令行会在点击“执行本地预览”后操作地图或图表 |
+
+选中调查任务时，通过只读 `GET /api/v1/operational-tasks/{task_id}/presentation-events` 分页读取该任务保存的展示事件，并载入左下列表；同时载入本轮最新报告中已保存的有效界面块。已完成任务、关闭实时跟随时也可读取。历史报告仍在任务详情可读。开启跟随或重连时先建立固定事件游标，载入不超过该游标的历史，期间到达的新事件暂存，历史完成后再顺序消费，避免间隙或重复。“载入当前报告”加载该任务最新保存的报告界面块，供本地检查，不重新发布报告。
+
+Dev 与工况详情共用右侧工具位置，切换调查时先关闭 Dev 回到任务列表，再打开 Dev 检查新的选择。实时展示面板位于地图左下方，打开 Dev 后仍可看见。新图表进入其滚动区时会滚动到图表，保留标题；手动收起面板后仍接收指令，展开再查看。切换项目、调查或执行代次会清理临时效果并取消未完成的本地预览。上述清理保留本次页面会话内的动作快照，只有切换项目会同时清空历史。已绑定调查时关闭跟随也会清理该调查的当前临时展示；未选择调查的本地预览不受跟随开关影响。面板外仍可操作地图，手动拖拽或滚轮暂停镜头自动跟随。
+
+## 本地测试步骤
+
+1. 在默认展开的“调查测试”页签准备数据。“载入合成样例”在当前地图中心生成合成空间展示、压力曲线、候选表格和一条候选数据；所选调查进度存在地图目标时，另加入该目标的高亮测试。所有合成结果均有明确标记。
+2. 可选：点击“校验 JSONL”单独查看识别出的展示指令、界面块、调查数据数量。也可直接执行本地预览，执行入口会自动校验当前全部内容。
+3. 点击“执行本地预览”，自动校验通过后对照地图和左下展示面板中的图表、结构化界面与数据摘要；Dev 的“原始数据检查”可点击对象查看原始行内容。动作记录区分“实时指令”和“本地测试”，显示应用或失败结果。
+4. 按需“下载测试 JSONL”保存当前已校验输入；“清除临时展示”清除当前浏览器的高亮、图表和覆盖层。测试不改变服务端事件游标，不发起调查、审批、工单或设备写入。
+
+样例与导出仅存在当前页面或用户下载的文件中，不写 Agent 工作区，不伪造已保存证据。Dev 不会自动枚举 Agent 生成的本地文件；要检查已有 JSONL，可将通过受控入口取得的文件内容粘贴到编辑区。当前最多 200 KB、40 行、8 个界面块；地图与图表继续遵守原展示协议的数量、几何及序列约束。
+
+## 可切换测试案例
+
+“JSONL 测试案例”选择框不依赖调查选择；地图就绪后即可切换并载入内容，显示该案例的预期结果。本地预览无需选择调查或开启跟随，表格、卡片、数据摘要、图表与范围统一在地图左下方的“本地预览展示”中显示，Dev 只保留输入、校验、原始数据检查与执行记录；“载入合成样例”重新生成当前案例，尚未选择时载入组合联动。修改输入会重置案例选择与校验状态，仍可继续手工测试。“载入当前报告”继续加载所选任务已保存的界面块。
+
+| 案例 | 核对内容 |
+| --- | --- |
+| 组合联动 | 地图点、调查现有目标高亮、压力曲线、候选表格与数据 |
+| 地图定位与高亮 | 有目标时高亮真实关联目标；无目标时只显示合成点，不虚构资产查询编号 |
+| 压力趋势对比 | 两条合成压力曲线、时间轴、单位与图例 |
+| 影响用户统计 | 合成用户数柱状图，不作为真实停水统计 |
+| 合成影响范围 | 当前地图中心附近的合成 Polygon |
+| 投诉热力分布 | 三个具有非负权重的合成投诉点 |
+| 候选管段对比 | 合成候选表格及两条 candidate 数据，不查询虚拟管段 |
+| 隔离阀门清单 | 合成阀门表格及两条 valve 数据，不执行关阀 |
+| 纯 JSONL 数据 | 只显示数据；内嵌 action 字段不作为动作执行 |
+| 错误：JSON 语法 | 第二行语法错误时整批拒绝，不执行第一行合法动作 |
+| 错误：不支持的动作 | 拒绝协议未支持的动作 |
+| 错误：图表数据不齐 | 拒绝时间轴和序列长度不一致的图表 |
+
+切换前若执行过本地预览，会先清除它的当前临时地图、图表和业务结果，保留动作历史供回看；仅选择或编辑 JSONL 不执行新指令。有内容时即可点击“执行本地预览”，无需先点单独校验；每次执行都会重新校验当前全部输入。任何一行错误都会拦截整批，显示具体错误，不执行部分指令；地图尚未就绪时也显示原因。仅空输入或正在执行时禁用按钮，不以调查选择或实时跟随作为本地执行前提。测试不会写入 Server、重启调查或发送 Agent 对话。案例定义位于 [investigation-dev-cases.ts](../src/features/workbench/utils/investigation-dev-cases.ts)。
+
+## JSONL 格式
+
+以下每行都是独立对象。第一行只在点击执行后清理本地高亮；第二行预览合成说明；第三行仅为候选数据，不触发高亮、定位或计算。
+
+```jsonl
+{"record_type":"presentation","command":{"action":"clear_highlights"}}
+{"record_type":"ui_block","evidence_refs":[],"block":{"version":"answer-ui@1","block_id":"dev-note","fallback_text":"本地合成格式示例","spec":{"root":"note","elements":{"note":{"type":"Text","props":{"text":"本地合成格式示例，不代表调查成果。","tone":"warning"},"children":[]}}}}}
+{"record_type":"candidate","origin":"synthetic","source_evidence_refs":[],"element_id":"DEMO-PIPE-01","status":"example_only"}
+```
+
+仓库内的可复制数据示例为 [unified-presentation.jsonl](../tests/fixtures/unified-presentation.jsonl)，覆盖十种 command、一个 `phase: final` 界面块和带来源的普通数据行；`P1` 是浏览器测试夹具中的测点，业务项目应使用已核实的实际编号。内置案例从同一个记录生成器输出，并在生成时通过当前校验器。错误案例单独保留，专门验证拒绝行为。
+
+每行必须显式使用 `record_type: presentation`、`record_type: ui_block`，或带来源的调查数据类型。裸 command、裸 `answer-ui@1` block 和旧 chat 的 name/params 格式均拒绝。展示指令统一接受 `locate_features/zoom_to_map/highlight_features/clear_highlights/open_chart/close_chart/set_overlay/clear_overlay/render_scada_analysis/clear_scada_analysis`，不能加入项目、运行身份、URL、脚本或任意命令。Dev 的覆盖层样例直接提供合成几何，仅用于本地渲染测试；任务 Agent 的 `set_overlay` 可只传证据编号，由 Server 提取几何；传入 data 时必须与保存的证据快照一致。Chat 和 Dev 执行已提供并校验的 data。不能把 Dev 格式当成 Server 写入接口。
+
+数据行需要 `record_type`、`origin`、`source_evidence_refs`，其余字段按实际内容保留。`origin` 接受 system_data、synthetic、derived、human_input，仅说明本地数据来源，不构成 Server 证据认证。显示合成表格不等于运行过定位或完成现场处置。
+
+## 验证范围
+
+聚焦测试：
+
+```bash
+pnpm exec vitest run src/features/workbench/utils/investigation-dev-preview.test.ts src/features/workbench/components/map-dev-panel.test.tsx src/features/workbench/hooks/investigation-presentation-follower.test.ts
+PLAYWRIGHT_PORT=5194 pnpm exec playwright test tests/browser/investigation-dev-tools.e2e.ts tests/browser/floating-panel-pointer.e2e.ts --workers=1 --reporter=line
+```
+
+浏览器用隔离 API/SSE fixture 验证所选任务到真实 MapLibre/React 展示的消费链、Dev 开启与收起、JSONL 校验和下载、任务切换清理、紧凑窗口及面板外地图输入；不调用付费模型或真实工单、设备接口。真实 Agent 是否发布了正确的事件、报告或 JSONL 文件，仍需按实际项目运行记录核对。
+
+## 统一展示动作
+
+Chat 使用 `present_view({command, reason})`，在线通过 SSE 的 `tjwater.frontend_action` 承载 `frontend-action@2`，动作字段为 command，不再接收 name/params。浏览器回传 `frontend-action-result@2`。任务事件和 Dev JSONL 的 command 使用相同结构，并进入同一执行器。Chat、调查和 Dev 预览分别拥有地图源、SCADA 图层及图表状态；清理、切换会话和切换任务不会误清其他入口。Chat 动作按接收顺序执行，切换会话取消正在执行及排队动作；过期动作不会执行。任务仍只记录发布状态，不等待浏览器。查看历史回答不会重放动作。
+
+动作 schema 的维护源是 `src/features/agent/presentation/command-schema.ts`。修改后在前端仓库运行 `node scripts/export-view-command-contract.mjs`，同步 Agent 主机/原生工具共用的 TypeScript schema 和 Agent/Server JSON Schema；运行同一命令加 `--check` 检查一致性。Server 任务入口继续执行证据归属和快照校验。
+
+## 已有案例与示例迁移
+
+仓库内正向示例统一使用以下格式；测试输入中的旧格式仅用于明确的拒绝用例。
+
+| 内容 | 当前格式 |
+| --- | --- |
+| 地图、图表和 SCADA 动作 | `{"record_type":"presentation","command":{"action":"动作名",…}}` |
+| 图表动作 | `open_chart`，图表数据位于 `command.chart`，明确提供 `chart_id` 和 `evidence_refs` |
+| 结构化界面 | `{"record_type":"ui_block","block":{"version":"answer-ui@1","block_id":"…","phase":"final",…},"evidence_refs":[]}` |
+| 调查数据 | 保留 `record_type/origin/source_evidence_refs`，不把内嵌 action 提升为指令 |
+| Chat 调用 | `present_view({command, reason})`，不再调用旧的独立展示工具 |
+
+本轮迁移只覆盖仓库内的内置案例、夹具和文档示例，未修改历史会话、数据库或外部下载文件。没有增加运行时旧格式转换。
+
+
+## 展示动作历史
+
+调查实时展示按所选任务读取 Server 已保存的展示动作，各任务的历史在浏览器中分别保留、切换时按任务展示。对话展示和本地预览展示继续保留当前项目、本次页面会话内收到的动作。清除类动作不纳入历史。展示面板的“切换展示动作”以最新优先倒序排列，“当前（最新）”始终置顶，动作编号保留发生顺序。可选择任一已完成、未完成或取消的动作，也可用上一步/下一步逐步回看；进行中的动作显示状态但不可选择。“回到当前”恢复最新展示。 当前结果与最后一条已完成动作相同时，合并显示为“当前（最新）”，下拉和前后导航不再重复这一项。清理后当前结果与最后快照不同，最后一条仍作为历史结果可选。切换任务、切换案例、关闭图表和清除当前展示都会保留历史；切换项目或刷新页面后清空浏览器缓存，重新选择调查任务可再次读取 Server 保存的事件。不设最近若干条的截断。载入和回看不向 Server 发布事件，不重启调查、审批或现场操作；重复选择同一任务按任务编号和事件序号去重。
+
+本地快照保存图表、界面块、数据、证据摘要、地图几何及镜头。Server 历史保留原发布指令和空间证据快照；只有要素编号的旧定位指令在首次载入时按当前项目读取可访问几何，不声称这些是历史时刻的资产位置。载入后回看使用本地快照，不重复查询。上一轮结果可作为历史查看，不混入本轮当前状态。单条过期或不合法指令显示失败记录，其他有效结果继续载入。历史导航直接渲染快照，不重新查询资产、执行原指令或发送调查请求。关闭图表、显示/隐藏及定位覆盖层、界面块关联要素定位等操作会产生记录；清除临时展示、清除地图展示，以及 `clear_highlights/clear_overlay/clear_scada_analysis` 指令只更新当前状态，不创建历史条目，已有结果快照仍保留；地图手动拖拽和证据展开属于查看操作，不逐帧记录。记录不是完整底图或外部实时数据的离线副本。
+
+回看期间，新动作继续更新“当前”，面板保留正在查看的历史并提示后续动作数。“回到当前”恢复这些最新结果。历史画面禁止关闭图表、修改覆盖层和发起新的关联要素查询，仍可查看依据、检查表格并定位已有覆盖层。地图与界面使用已有过渡，并尊重减少动画设置。Dev 原始数据检查对应编辑器最近一次执行的输入，不随展示历史切换；历史结果及快照以展示面板为准。
+
+
+历史接口按 `after`、`through` 游标和 `limit` 分页，返回 `task_id/event_cursor/items/next_after`；客户端固定首次授权游标，不截断为最近一页。Server 按项目、任务及展示事件类型读取现有事件日志，不需要新增数据表。新接口需与前端一起发布；测试覆盖的是当前源码的服务/仓储/API 单元检查与浏览器模拟 API 联动，未替代真实项目验收。

docs/non-map-ui.md

@@ -27,7 +27,7 @@
 | 成果预览与文档 | 1280/375px，桌面标题与折叠栏几何边界 |
 | 图层、测量、标注、更多、开发面板 | 非地图浮层边界，开发面板表单控件统一 |
 
-`FeatureInsightPanel` 当前只有定义，没有运行入口，未伪造页面声称已完成运行检查。实际要素详情使用地图上的 `FeaturePopover`，不在本次非地图面板范围。
+实际要素详情使用地图上的 `FeaturePopover`；未接入运行入口的 `FeatureInsightPanel` 已在冗余清理中移除。
 
 ## 验证与限制
 
@@ -108,7 +108,7 @@
 
 - 新增 `WorkbenchSection`、`WorkbenchNotice` 和 `WorkbenchEmptyState`，统一标题、状态、提示和空态，减少同级彩色卡片与大面积空白。
 - 生命周期确认、定时计划、目标编译、运行控制、运行对比、人工复核和 Evidence 导入统一状态语言与操作层级。
-- 外围样板将连接与场景、历史回放、待提交来源、已有任务放在前面；synthetic 数据、测试工单、测试数据和 request_id 查询移到辅助区并默认折叠。
+- 外围样板将连接与场景、历史回放、待提交来源、已有任务放在前面；测试工单、测试数据和 request_id 查询移到辅助区并默认折叠。外围工单统一按系统数据处理。
 - `FieldSelect`、`Checkbox`、`Disclosure` 和 `DateTimeField` 统一焦点、hover、按压和禁用反馈。日期时间弹层继续支持 Esc 取消并返回焦点。
 - 数据表使用等宽数字并将数值右对齐；320、375 和 1280px 下均无横向溢出。
 

docs/style-design-guide.md

@@ -1,6 +1,6 @@
 # 样式设计指南
 
-供水前端统一以本地 shadcn/ui 为组件基础，使用 Tailwind CSS、共享变体和语义变量。Agent 相关弹窗、面板与菜单保持 shadcn/ui 设计；地图控件与其他工作台浮层使用本文规定的 Acrylic 视觉。适用于工作台、地图控件、Agent、报告、表单和弹层。
+供水前端统一以本地 shadcn/ui 为组件基础，使用 Tailwind CSS、共享变体和语义变量。Agent 相关弹窗、面板与菜单，以及 Dev 测试面板、外围系统面板、调查与本地预览展示面板保持 shadcn/ui 设计；其他地图控件与工作台浮层使用本文规定的 Acrylic 视觉。适用于工作台、地图控件、Agent、报告、表单和弹层。
 
 本文是唯一的样式规范。业务交互见 [Agent 交互与报告设计](agent-chat-ui-design.md)，状态含义见 [状态语言](status-language.md)。本文规定统一目标；历史局部配色和样式覆盖需在后续组件修改中逐步对齐，文档合并不代表运行样式已全部迁移。
 
@@ -16,6 +16,24 @@
 
 ### Agent 弹窗与面板
 
+回答正文与注意事项、表格等结构块之间使用 20px 的布局间距。Markdown 复制容器使用 `display: contents` 时，不使用直接子元素 margin 实现这段间距，避免间距丢失。
+
+回复生成期间只在正文左侧显示一处“正在回复”状态，状态组与正文左边缘对齐；不再在空正文中重复显示“正在生成”。
+
+过程切换为正式结果时，先将旧内容淡出，再统一切换正文、过程归档与底部操作，最后淡入结果，整体约 200ms；只改变透明度，不对长内容高度做插值。切换期间保护阅读锚点，用户滚动或操作后停止自动位置补偿。系统要求减少动态效果时直接交接，仍保留阅读位置和工具展开状态。
+
+面板头部使用紧凑字号：助手名称为 14px/20px，在线状态和主题选择为 12px/16px，保留原有按钮点击区域。对话中的用户消息、回答正文与输入文字为 16px，消息正文与输入行高为 28px；回复状态、依据轮次、输入引用、协作标签及操作文字为 14px，说明行高为 20px。引用标题通过字重区分，说明与标题间隔 4px。输入框顶部不重复显示等待回答的常驻提示，提问与继续状态由对应提问卡片呈现。
+
+起始推荐问题及其加载、失败提示统一使用 14px/20px、常规字重，窄屏下允许完整换行。
+
+输入框按上方引用、中间编辑、下方工具栏排列，外壳使用 22px 圆角和轻边框。任务引用使用无独立底色的紧凑行，引用图标为 14px，文字为 14px/20px；任务名称与轮次、报告版本放在同一文字流中，窄屏在完整短语之间换行。上下内边距各 4px，不在输入底栏重复显示“任务协作问答”标签。内容引用复用紧凑行，原文与分析方向按需展开。权限、模型和消息发送方式的下拉入口沿用 10px 圆角矩形，箭头不设独立圆形区域；悬停和打开时使用整行的淡底色，箭头保持中性颜色；整行保持可点击。语音与发送按钮继续使用圆形。
+
+Agent 输入框使用 `--shadow-agent-composer` 的柔和双层阴影区分白色阅读背景，桌面、窄屏和浮动输入框复用同一规则。聚焦与未聚焦保持相同边框和阴影，不显示蓝色外圈；工具按钮保留键盘焦点提示。左侧始终显示权限模式与文字，任务协作会话同样保留该入口，运行期间按原规则禁用。右侧依次放模型、语音和发送操作；运行时模型位置切换为引导或排队方式，主按钮沿用原有停止与发送切换；停止使用柔和红底和深红图标，悬停时红底略深，发送保持蓝色。工具图标统一为 16px、2px 描边，下拉箭头统一为 12px 单箭头；语音使用声波图标，监听时保留动态声波反馈。发送使用左右对称的 20px 上箭头和 40px 圆形按钮，图标通过网格居中；禁用时使用浅底、灰色图标，启用时使用蓝底、白色图标。模型名称按输入框实际宽度显示。待处理消息队列位于编辑框上方，区别于尚未发送的草稿。
+
+助手回复底部使用单行操作栏：“查看处理过程”靠左，语音与复制组成右侧操作组，复制位于最右。展开区域使用白色背景、细边框和完整圆角，与回答正文区分；外边缘与过程入口左侧对齐，普通进度与工具调用的状态图标统一左对齐；工具调用平铺显示，不额外包裹卡片、边框或背景，参数内容按文字列对齐。过程入口保留标准 hover 反馈，使用对称的水平留白。普通步骤和工具调用复用同一状态图标组件：24px 圆形容器、14px 线性图标，完成为圆圈勾选、失败为圆圈叉号、进行中为加载图标。操作图标统一为 16px、2px 描边，按钮高 32px；窄容器下语音与复制收起可见标签，保留中文可访问名称和提示。复制反馈不改变操作栏布局，过程展开、语音播放与复制各自独立。
+
+Dev 测试、外围系统、调查实时展示与本地预览展示面板也遵循本节：使用实体表面、语义颜色、细边框和标准控件，复用 `workbench-shadcn-surface` 主题；日期与选择菜单通过 Portal 渲染时继续传递这一主题。外围面板内的工单、SCADA 和 Dev 内的 JSONL 测试区采用同一规则。Dev 按调查测试与地图调试两个页签组织；工单用分类标题和摘要列表组织，完整报告按需展开，避免多层边框挤压表单；SCADA 先展示最新值，再提供异常演练。调查与本地展示面板使用固定标题和状态、独立滚动区、紧凑的地图操作及图表 Card；图表标题与关闭按钮同行，嵌入式渲染不再叠加旧灰色图表容器，长标题与图例可换行。面板与图表进入退出、依据展开使用 Motion 的短时透明度和位移过渡，布局变化采用 transform 投影；键盘操作及减少动态效果模式即时完成。地图定位采用可中断的 450ms 平滑 fit，覆盖层以 180ms 淡入淡出，减少动态效果时关闭这些过渡。两个浮层保持非模态，仅自身表面接收指针输入，外部地图保留点击、拖拽和滚轮操作。 展示面板的动作切换放在固定标题区，使用紧凑的 Select、前后按钮和“回到当前”；历史状态与后续动作数可见。回看切换保留短时淡入淡出，退出画面立即设为 inert 并从无障碍树隐藏，避免旧操作仍可点击。Dev 只显示测试输入、校验与原始数据，业务表格、卡片与图表统一进入展示面板。
+
 Agent 相关界面保持项目本地 shadcn/ui 组件的设计，包括背景、边框、圆角、阴影、排版、间距及交互状态。该规则覆盖主对话面板、手机 Agent 面板、历史对话、主题新建与管理、模型菜单、权限与问题确认、Agent 回答的展开阅读面板，以及这些界面的子弹窗和提示。
 
 | 场景 | 组件与组合 |
@@ -23,7 +41,7 @@ Agent 相关界面保持项目本地 shadcn/ui 组件的设计，包括背景、
 | 历史、主题表单、独立详情与确认 | `Dialog`、`DialogTitle`、`DialogDescription`，组合 `Input`、`Button` 和列表 |
 | 对话、审批、问答与展开阅读面板 | 本地 shadcn/ui 面板布局，按需组合 `Card`、`Separator`、`Tabs`、`ResizablePanelGroup` 与 AI Elements |
 | 模型、主题与会话操作菜单 | `DropdownMenu` 及其菜单项、分组和分隔线 |
-| 辅助说明与状态 | `Tooltip`、`HoverCard`、`Badge` 及共享状态组件 |
+| 辅助说明与状态 | `Alert`、`Tooltip`、`HoverCard`、`Badge` 及共享状态组件 |
 
 - 使用已配置的 shadcn/ui 主题变量：`bg-background`、`bg-card`、`bg-popover`、`text-foreground`、`text-muted-foreground`、`border-border`、`ring-ring` 等。按钮、输入和菜单项优先使用本地默认样式及 `variant`、`size`，不为 Agent 另建配色和控件外观。
 - 历史和主题弹窗使用 `bg-card`，与 Agent 主对话区保持白色实体表面，标题区和列表不另铺灰色底。通过 Portal 渲染的弹窗及菜单标记 `data-agent-theme="chat"`，复用主面板的现有主题变量，避免继承工作台银灰色底板；保留本地 `Dialog` 的遮罩、边框、阴影与交互样式。
@@ -79,6 +97,8 @@ import { Card, CardContent, CardHeader, CardTitle } from "@/shared/ui/card";
 
 地图中的管线一起显示，以管径对应的颜色和线宽体现差异。水库、泵站、水箱和水质监测点保持清晰；阀门、普通节点与常规 SCADA 使用随缩放连续变化的大小和透明度。密集设施的工程符号自动避让，底层保留轻量圆点以表达位置和支持点选。选中与异常分析标记单独突出，普通设施以连续变化为主；普通节点从 12 级、阀门从 13 级开始显示，图标、标注与命中范围同步限制。
 
+Agent、调查展示和 Dev 本地预览的要素定位复用地图调试的选中样式，按原业务源保留线宽、边框、圆环半径、设备类型过滤和缩放规则。展示覆盖层从当前地图样式派生，独立管理高亮与清理范围；闪烁只改变强调透明度，结束后恢复静态样式。
+
 管道透明度不随缩放变化，缩放渐变体现在管线与描边的宽度上，远看纤细、放大清晰；图层开关时仍使用透明度淡入淡出。
 
 图层开关统一使用约 320ms 的透明度淡入淡出，覆盖管线、设施、监测点、GIS 原始数据和模拟结果。矢量瓦片可绘制后才开始淡入计时，避免加载期间耗尽过渡时间。淡入淡出只临时叠加透明度系数，结束后恢复图层原有样式；快速反向切换从当前进度继续。隐藏时立即关闭命中层与交互强调层，淡入结束后恢复；减少动态效果偏好下直接切换。管线用过滤器区分开关状态，透明度保持统一数值，避免逐帧重写属性表达式触发瓦片重算。
@@ -93,7 +113,7 @@ Agent 使用 shadcn/ui 的实体表面和现有主题色，不将这种外观列
 
 ## 4. 材质与层级
 
-本节的 Acrylic 材质规则适用于地图与其他工作台界面；Agent 弹窗与面板按前述 shadcn/ui 规则执行。Acrylic 通过半透明色调、背景模糊、混合层和细噪点建立层级，边缘高光与阴影保持克制。常驻、参与布局的业务区域使用实体底板；Mica 仅作为这一底板角色的设计参考，Web CSS 实体色不等同于原生系统 Mica。
+本节的 Acrylic 材质规则适用于地图与其他工作台界面；Agent、Dev 测试、外围系统、调查与本地展示面板按前述 shadcn/ui 规则执行。Acrylic 通过半透明色调、背景模糊、混合层和细噪点建立层级，边缘高光与阴影保持克制。常驻、参与布局的业务区域使用实体底板；Mica 仅作为这一底板角色的设计参考，Web CSS 实体色不等同于原生系统 Mica。
 
 | 表面类 | 用途 |
 |---|---|
@@ -179,5 +199,3 @@ Agent 界面另检查所有弹窗、面板及其子菜单是否沿用本地 shad
 - [shadcn/ui 组件原则](https://ui.shadcn.com/docs)、[主题变量](https://ui.shadcn.com/docs/theming)、[Vite 接入](https://ui.shadcn.com/docs/installation/vite)、[CLI 配置](https://ui.shadcn.com/docs/components-json)。
 - [Tailwind CSS 主题变量](https://tailwindcss.com/docs/theme)、[自定义样式与层叠](https://tailwindcss.com/docs/adding-custom-styles)。
 - [Fluent Acrylic](https://learn.microsoft.com/en-us/windows/apps/design/style/acrylic)、[Mica](https://learn.microsoft.com/en-us/windows/apps/design/style/mica)。
-
-聊天的生成、续接与刷新恢复共用一个过程容器和一份步骤列表。过程入口在回复底部靠左，语音和复制靠右。发送保持蓝色圆形按钮，停止使用柔和红底与深红图标，悬停时红底略深。