feat: add project-aware agent workspace

docs/ACRYLIC_DESIGN_INVENTORY.md

@@ -1,224 +0,0 @@
-# 亚克力设计类别与组件使用清单
-
-本文档记录当前前端的亚克力材质体系及实际使用位置。样式定义以 `src/styles.css` 为准，组件映射以 `src/features/` 下的现有代码为准。
-
-## 总览
-
-当前材质体系分为 3 组，共 13 个语义类：
-
-| 分组 | 数量 | 类别 | 是否使用背景模糊 |
-|---|---:|---|---|
-| 外层亚克力与临时玻璃 | 4 | 导航、面板、独立控件、临时任务浮层 | 是 |
-| 内部实体表面 | 4 | Dock、控件面、内容凹槽、阅读面 | 否 |
-| 语义状态表面 | 5 | 信息、正常、警告、危险、Agent 推理 | 否 |
-
-只有第一组属于真正的亚克力或玻璃外壳。第二组用于亚克力壳层内部，保证文字、表单和密集数据不受底图干扰。第三组只表达业务状态，不承担界面层级。
-
-## 1. 外层亚克力与临时玻璃
-
-这组样式包含冷色半透明底色、饱和度、明度混合、细噪点、边框和阴影，并使用 `backdrop-filter`。同一区域只应保留一个带模糊的外层壳体，内部子元素应改用实体表面。
-
-### `acrylic-navigation`
-
-- 用途：全局导航栏。
-- 模糊：使用面板级模糊，默认 22px，浅色底图 24px，卫星底图 20px。
-- 特征：保留底部分隔和下投影，不使用顶部高光。
-- 当前组件：
-  - `WorkbenchTopBar`，工作台顶部 Header。
-- 文件：`src/features/workbench/components/workbench-top-bar.tsx`。
-
-### `acrylic-panel`
-
-- 用途：承载持续显示或需要集中阅读的主要浮动面板。
-- 模糊：使用面板级模糊，20px 至 24px。
-- 当前组件：
-  - `AgentCommandPanel`，Agent 命令面板外壳。
-  - `AgentCollapsedRail`，Agent 收起状态侧栏。
-  - `ScheduledConditionFeed`，预约任务与工况面板，通过 `MAP_TOOL_PANEL_SURFACE_CLASS_NAME` 间接使用。
-  - `LayerControl`、`ControlPanel`、`Legend`、`BaseLayersControl`，地图工具面板，通过共享材质常量间接使用。
-  - `FeaturePopover`，要素详情浮层，通过 `MAP_FOCUS_SURFACE_CLASS_NAME` 间接使用。
-  - `FeatureInsightPanel`，要素洞察面板。
-  - `MapDevPanel`，地图开发调试面板。
-  - `AlertMenu`、`ScenarioMenu`、`UserMenu`，顶部导航下拉菜单。
-  - `MapNotice`，地图通知。
-- 直接或间接涉及文件：
-  - `src/features/agent/components/agent-command-panel.tsx`
-  - `src/features/agent/components/agent-collapsed-rail.tsx`
-  - `src/features/map/core/components/map-control-styles.ts`
-  - `src/features/map/core/components/notice.tsx`
-  - `src/features/workbench/components/scheduled-condition-feed.tsx`
-  - `src/features/workbench/components/feature-popover.tsx`
-  - `src/features/workbench/components/feature-insight-panel.tsx`
-  - `src/features/workbench/components/map-dev-panel.tsx`
-  - `src/features/workbench/components/workbench-top-bar-menus.tsx`
-
-### `acrylic-control`
-
-- 用途：始终悬浮在地图上的紧凑型独立控件。
-- 模糊：使用控件级模糊，默认 18px，浅色底图 20px，卫星底图 16px。
-- 当前组件：
-  - `Toolbar`，地图主工具栏。
-  - `DrawToolbar`，绘制工具栏。
-  - `ZoomControl`，缩放控件。
-  - `ScaleLine`，比例尺。
-  - `BaseLayersControl`，底图切换入口与预览控件。
-  - `map-workbench-page.tsx` 中的浮动地图控制入口。
-- 使用方式：上述组件主要通过 `MAP_CONTROL_SURFACE_CLASS_NAME` 间接引用。
-- 共享定义：`src/features/map/core/components/map-control-styles.ts`。
-
-### `glass-transient`
-
-- 用途：短时出现、需要突出当前任务状态的玻璃浮层。
-- 模糊：沿用控件级模糊，16px 至 20px。
-- 当前组件：
-  - `AgentTaskTicker` 的活动任务卡片。
-- 文件：`src/features/workbench/components/agent-task-ticker.tsx`。
-- 约束：仅用于活动任务浮条，非活动堆叠卡改用 `surface-control`。
-
-## 2. 内部实体表面
-
-这组样式不使用 `backdrop-filter`。它们用于亚克力外壳内部，通过不透明度和背景层级提高可读性，避免出现嵌套模糊。
-
-### `surface-dock`
-
-- 用途：预留给固定 Dock 或侧边停靠区域。
-- 当前状态：已在 `src/styles.css` 中定义，暂无组件直接使用。
-- 适用组件：
-  - 桌面端固定展开的 Agent 侧栏，前提是它从地图浮层改为占据稳定布局宽度的 Dock。
-  - 固定展开的预约工况详情侧栏或图层管理侧栏，前提是侧栏长期贴边并参与工作区布局。
-  - 后续可能增加的对象目录、调度队列等常驻侧栏。
-- 不适用：临时弹层、悬浮工具面板、下拉菜单和可覆盖地图的短时侧栏。这些组件仍应使用 `acrylic-panel`。
-
-### `surface-control`
-
-- 用途：面板内部的 Header、输入区域、筛选器、按钮、紧凑控制区和任务堆叠卡。
-- 当前组件范围：
-  - Agent 收起侧栏条目、输入操作栏和命令面板快捷入口。
-  - 图层、量测和通用控制面板中的交互控件。
-  - 预约任务面板与工况详情中的筛选器、元信息块和次级操作。
-  - 任务浮条的非活动卡片。
-  - 要素洞察面板的内部按钮。
-  - Header 下拉菜单的内部控制区。
-  - 通用 `IconButton`。
-- 主要文件：
-  - `src/features/agent/components/agent-collapsed-rail.tsx`
-  - `src/features/agent/components/agent-command-panel.tsx`
-  - `src/features/map/core/components/control-panel.tsx`
-  - `src/features/map/core/components/layer-control.tsx`
-  - `src/features/map/core/components/measure-panel.tsx`
-  - `src/features/workbench/components/agent-task-ticker.tsx`
-  - `src/features/workbench/components/scheduled-condition-feed.tsx`
-  - `src/features/workbench/components/scheduled-condition-detail-panel.tsx`
-  - `src/features/workbench/components/feature-insight-panel.tsx`
-  - `src/features/workbench/components/workbench-top-bar-menus.tsx`
-
-### `surface-well`
-
-- 用途：低密度内容区、空白支撑区、未选中的面板条目和内部凹槽。
-- 当前组件：
-  - `LayerPanel`、`LayerControl` 的未激活条目。
-  - `MeasurePanel`、`DrawToolbar`、`AnnotationPanel` 的内部区域。
-  - `ControlPanel`、`Legend`、`BaseLayersControl` 的分组与空白区域。
-  - Header 下拉菜单的普通菜单项。
-- 使用方式：部分组件直接引用，部分通过 `MAP_READABLE_SURFACE_CLASS_NAME` 间接引用。
-
-### `surface-reading`
-
-- 用途：消息、报告、表单、属性列表、时间线内容和其他密集阅读区域。
-- 当前组件范围：
-  - Agent 消息详情、UI Envelope 内容和命令面板空状态。
-  - 预约任务列表、工况详情、KPI、报告内容与下拉列表。
-  - 要素洞察、属性列表和底图名称标签。
-  - Header 下拉菜单中的详情块与空状态。
-- 主要文件：
-  - `src/features/agent/components/agent-command-panel.tsx`
-  - `src/features/agent/components/agent-message-details.tsx`
-  - `src/features/agent/components/agent-ui-envelope-renderer.tsx`
-  - `src/features/workbench/components/scheduled-condition-feed.tsx`
-  - `src/features/workbench/components/scheduled-condition-detail-panel.tsx`
-  - `src/features/workbench/components/feature-insight-panel.tsx`
-  - `src/features/workbench/components/feature-property-list.tsx`
-  - `src/features/workbench/components/workbench-top-bar-menus.tsx`
-  - `src/features/map/core/components/base-layers-control.tsx`
-
-## 3. 语义状态表面
-
-语义状态表面不使用模糊，只表达业务含义。它们不能替代 `acrylic-panel`、`surface-control` 或 `surface-reading` 来建立界面层级。
-
-| 类名 | 含义 | 当前使用位置 |
-|---|---|---|
-| `material-tone-info` | 信息、液位等蓝色状态 | `FeatureInsightPanel` 的雷达液位区块 |
-| `material-tone-normal` | 正常、健康、流量或水质状态 | `FeatureInsightPanel` 的水质、综合监测等区块 |
-| `material-tone-warning` | 风险、告警、超声流量等橙色状态 | `FeatureInsightPanel` 的告警与超声流量区块 |
-| `material-tone-danger` | 严重故障或事故状态 | 已定义，建议用于严重事故、关键设备故障和高风险工况内容块 |
-| `material-tone-agent` | Agent 推理或模型建议 | 已定义，建议用于 Agent 解释、推理结论和建议动作内容块 |
-
-## 未使用样式的建议落点
-
-### `surface-dock`
-
-建议用于参与页面布局的常驻停靠区，而不是覆盖在地图上的浮层。现有组件中，以下场景适合在布局调整后使用：
-
-- `AgentCommandPanel` 的桌面常驻模式。只有当面板固定贴左、占据稳定宽度并推动地图安全区时才使用。
-- `ScheduledConditionFeed` 或 `ConditionDetailPanel` 的常驻右侧模式。适用于调度员持续对照地图与工况详情的工作流。
-- `LayerPanel` 的常驻图层目录模式。适用于图层较多、需要持续管理的专业工作台。
-
-如果组件仍然悬浮在地图上、可以随时关闭或与其他浮层替换，应继续使用 `acrylic-panel`。
-
-### `material-tone-danger`
-
-建议用于已经确认的严重业务状态，不用于普通校验失败或短暂接口错误。现有组件中适合的落点包括：
-
-- `FeatureInsightPanel`：要素状态为 `critical`、严重故障、爆管或关键设备失效时的状态说明区块。
-- `ScheduledConditionDetailPanel`：工况风险等级为 `critical`，或任务状态为 `error` 且代表真实运行事故时的风险摘要和影响范围区块。
-- `MapNotice`：仅在需要持续强调严重运行事故时用于通知内容区，不替换通知最外层的 `acrylic-panel`。
-- Agent 权限或确认卡片：仅当待执行动作具有明确的高风险业务后果时使用，不能仅因提交失败就使用。
-
-不应使用在网络请求失败、加载失败、表单校验错误等通用技术错误上。这类错误继续使用局部红色图标、边框或文字即可，避免把技术故障误读为管网事故。
-
-### `material-tone-agent`
-
-建议用于明确由 Agent 或模型生成的内容，帮助用户区分事实数据、业务状态与机器推理。现有组件中适合的落点包括：
-
-- `FeatureInsightPanel` 的“Agent 解释”区块。该区块目前使用 `material-tone-warning`，如果内容只是解释或推理而非风险告警，更适合改用 `material-tone-agent`。
-- `AgentMessageDetails`：推理摘要、模型结论、建议方案等非原始证据内容。
-- `AgentUiEnvelopeRenderer`：由 Agent 返回的建议面板或注册组件中的结论区块。
-- `ScheduledConditionDetailPanel`：Agent 针对工况生成的处置建议区块。
-
-原始监测值、设备属性、人工录入内容和系统事实不应使用该样式。即使这些内容出现在 Agent 面板内，也应继续使用 `surface-reading` 或对应的业务状态色。
-
-## 共享类映射
-
-地图核心组件通过 `src/features/map/core/components/map-control-styles.ts` 复用材质类，避免在各组件中重复写样式值。
-
-| 共享常量 | 实际材质类 | 典型用途 |
-|---|---|---|
-| `MAP_CONTROL_SURFACE_CLASS_NAME` | `acrylic-control border` | 工具栏、缩放、比例尺、底图入口 |
-| `MAP_TOOL_PANEL_SURFACE_CLASS_NAME` | `acrylic-panel border` | 图层、图例、控制和预约任务面板 |
-| `MAP_FOCUS_SURFACE_CLASS_NAME` | `acrylic-panel border` | 要素详情等焦点浮层 |
-| `MAP_READABLE_SURFACE_CLASS_NAME` | `surface-well border` | 面板内部低密度区域 |
-| `MAP_READABLE_SURFACE_STRONG_CLASS_NAME` | `surface-control border` | 面板内部高可读控制区 |
-
-## 自适应与无障碍规则
-
-- `data-basemap-tone="light"` 会提高部分面板模糊强度，并降低导航、控件和任务浮条的背景不透明度。
-- `data-basemap-tone="satellite"` 会提高背景不透明度、轮廓和阴影强度，压制卫星底图纹理。
-- `prefers-reduced-transparency: reduce` 下，亚克力和玻璃表面会切换到接近不透明的背景并关闭模糊。
-- 不支持 `backdrop-filter` 的浏览器使用同样的高不透明度回退。
-- `forced-colors: active` 下，材质背景和边框改用系统颜色，并关闭背景图与阴影。
-
-## 使用约束
-
-1. 一个浮动区域只允许最外层使用 `acrylic-*` 或 `glass-transient`。
-2. 外层亚克力内部使用 `surface-control`、`surface-well` 或 `surface-reading`，不要叠加第二层模糊。
-3. 密集文字、表格、属性和值必须落在 `surface-reading` 等高可读表面上。
-4. `material-tone-*` 只表达状态，不表达层级，也不添加模糊。
-5. 新增地图控件时优先复用 `map-control-styles.ts` 中的共享常量。
-6. 组件只负责布局、圆角和交互状态，材质颜色、边框和阴影由全局语义类统一维护。
-
-## 当前待清理项
-
-- `surface-dock` 可在固定 Dock 落地时启用。如果产品不计划引入参与布局的常驻侧栏，可以移除该样式。
-- `material-tone-danger` 应等待明确的严重业务状态落点，不要为了消除未使用状态而套用到通用错误提示。
-- `material-tone-agent` 可优先用于 `FeatureInsightPanel` 的“Agent 解释”和 Agent 建议内容，替代不准确的警告语义。
-- Agent 面板仍有少量局部类直接使用 `--surface-control`、`--surface-reading` 或自定义透明背景。后续统一材质语义时，应评估是否迁移到对应的 `surface-*` 类。

docs/agent-answer-ui.md

@@ -1,5 +1,7 @@
 # 本地交互式回答
 
+统一样式见 [样式设计指南](style-design-guide.md)，聊天布局与报告交互见 [Agent 交互与报告设计](agent-chat-ui-design.md)。本文保留协议、组件参数与业务交互约定。
+
 聊天保留 AI SDK `UIMessage`、AI Elements 与现有 Agent 后端，新增
 `@json-render/core` / `@json-render/react` 的本地注册组件。
 组件代码随前端构建发布，无 ChatKit iframe、domain key 或 Vercel/OpenAI
@@ -9,7 +11,8 @@
 
 `Stack`、`Section`、`Text`、`Metric`、`Table`、`Chart`、`Evidence`、
 `MapLocation`、`FollowUpForm` 共九种组件。图表可切换折线、柱状和数据表；
-证据可折叠并标注来源；地图定位通过现有控制器执行；表单从空值开始，
+表格可搜索、排序和选择行，图表可切换已加载区间、显隐序列并选点追问；
+证据可按类别筛选、折叠并标注来源；地图定位通过现有控制器执行；表单从空值开始，
 由用户主动提交，提交形成普通用户消息。业务证据是否保存以 Agent 实际工具结果为准。
 
 Agent 通过 `present_answer` 发布完整的局部界面块，可在两块之间继续输出文字。
@@ -29,13 +32,44 @@ Agent 通过 `present_answer` 发布完整的局部界面块，可在两块之
 
 后台调查执行继续走任务报告与任务展示通道，聊天界面块不构成业务完成或浏览器回执。
 
+## 正式报告与主工作区
+
+正式报告可携带 `ui_blocks?: Array<{ block: AnswerUiBlock; evidence_refs: string[] }>`，最多 8 块，总 UTF-8 JSON 不超过 400000 字节。每块绑定报告中的已有证据，Server 验证任务归属；事实字段与审批不由 UI 块替代。组件树与聊天共用 `answer-ui@1`。例如：
+
+```json
+{
+  "ui_blocks": [{
+    "evidence_refs": ["saved-evidence-id"],
+    "block": {
+      "version": "answer-ui@1",
+      "block_id": "pressure-summary",
+      "fallback_text": "已保存记录中的压力为 0.30 MPa。",
+      "spec": {
+        "root": "pressure",
+        "elements": {
+          "pressure": { "type": "Metric", "children": [], "props": {
+            "label": "压力", "value": "0.30", "unit": "MPa", "source": "已保存监测记录"
+          } }
+        }
+      }
+    }
+  }]
+}
+```
+
+此片段仅展示新增字段，发布时仍需完整报告与真实存在的证据编号。保存沿用 `agent-artifacts`、报告 JSON、幂等键和 revision；读取沿用报告列表、指定版本、任务详情及 Agent context，不新增写入端点或数据库表。
+
+`InvestigationReportBlocks` 将正式报告接入 `AnswerUiView`，证据组件使用保存记录中的摘要、来源、时间与类别。未知版本或无法解析的块展示 fallback，报告固定事实仍可读。报告追问携带 `report_revision`、`reportGeneration` 和引用文本；表单先带入会话，确认后才发送。
+
+`ExpandableReading` 将同一个 React 内容实例移至主工作区，保留图表视图、搜索、行选择、表单草稿。关闭恢复入口焦点，重开恢复阅读位置。主工作区宽度至少 960px 可对照地图，其余宽度在两者之间切换；原地图实例保留。
+
 ## 扩展组件
 
 1. 在 `src/features/agent/answer-ui/catalog.ts` 增加严格的 Zod 参数定义、用途描述与必要的数据上限。
 2. 在 `answer-ui-view.tsx` 注册 React 组件。需要工作台交互时通过 Agent 公共 API 的回调接入，保持依赖方向。
 3. 从本仓库运行 `pnpm export:answer-ui-contract`，更新相邻 Agent 仓库的
-   `src/chat/answer-ui-catalog.json`。组件目录是唯一参数定义源，生成文件需随两边一起交付。
-4. 如新组件存在跨字段约束，同时更新两端的协议校验并加边界和交互测试。
+   `src/chat/answer-ui-catalog.json` 和 Server 的 `contracts/answer-ui-catalog.json`。组件目录是唯一参数定义源，生成文件需随三端一起交付。
+4. 如新组件存在跨字段约束，同时更新三端的协议校验并加边界和交互测试。
 
 导出脚本接受可选目标文件：
 
@@ -50,8 +84,8 @@ node scripts/export-answer-ui-contract.mjs /path/to/agent/src/chat/answer-ui-cat
 
 ## 校验边界
 
-两端拒绝未知组件、额外属性、任意脚本/事件定义、缺失引用、循环、重复或游离节点。
-每块最多 48 节点、深度 12、约 100 KB，图表必须对齐且数值有限；表格每行与列数
+三端拒绝未知组件、额外属性、任意脚本/事件定义、缺失引用、循环、重复或游离节点。
+每块最多 48 节点、深度 12、完整序列化结果不超过 100000 个 JavaScript UTF-16 代码单元，图表必须对齐且数值有限；表格每行与列数
 一致，表单字段名唯一。组件只消费明确的 props，没有动态代码、网络 URL 或任意动作 DSL。
 无法解析的历史内容显示该块的 `fallback_text`。
 
@@ -61,7 +95,7 @@ node scripts/export-answer-ui-contract.mjs /path/to/agent/src/chat/answer-ui-cat
 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
+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 build
 ```
 
@@ -77,8 +111,8 @@ bun run tests/integration/answer-ui-smoke.ts
 事件验证组件、更新、历史恢复、键盘展开证据、表单提交和 320/375px 布局，不能当作
 真实模型已正确选择组件或现场资料已核验的证明。
 
-前端与 Agent 需一起更新，Agent 进程需重新加载原生插件。无需新增环境变量、
-domain key 或数据库迁移。当前开发实例通过现有监听机制重新加载；既有聊天与调查工作进程保留。
+前端、Agent 与 Server 需同步更新；Agent 进程需重新加载原生插件，Server 需加载新报告 schema。无需新增环境变量、
+domain key 或数据库迁移。本轮不重启既有服务；浏览器演练和本地测试不代表运行中的服务已完成同步。
 
 ## 真实模型验收（显式启用）
 

docs/agent-chat-ui-design.md

@@ -0,0 +1,204 @@
+# Agent 交互与报告设计
+
+本文维护供水前端 Agent 对话、正式调查报告和展开阅读的功能、布局与业务交互。组件基础、配色、材质、排版和无障碍样式统一遵循 [样式设计指南](style-design-guide.md)，阶段验证结果见 [实现记录](history/agent-chat-ui-implementation-notes.md)。
+
+Agent 相关弹窗、面板及菜单统一保持本地 shadcn/ui 设计，具体外观规则由样式设计指南维护。本文规定的历史全屏、展开阅读、审批和主题管理等布局均遵循该规则。
+
+## Intelligent UI 的目标
+
+本文中的 Intelligent UI 参考 [ChatGPT Intelligent UI](https://help.openai.com/en/articles/20001598-intelligent-ui-in-chatgpt)：回答根据内容选择交互呈现，用户在阅读中探索数据、核查来源并继续提问。Vercel AI Elements 和 shadcn/ui 提供组件与布局参考，功能通过本项目本地组件实现。
+
+当前落地为“左侧对话 + 主工作区”。聊天回答与正式调查报告共用指标、图表、表格、证据、定位和资料表单。复杂内容由用户点击展开到主工作区；调查状态、结论边界、证据、审批和版本仍由 Server 保存的事实驱动。模型只在注册组件中选择呈现方式。
+
+## 功能梳理
+
+以当前组件、回调和消息契约核对功能，再决定它们出现的位置，不继承原有界面分区。
+
+| 功能组 | 已有能力 | 新布局中的位置 |
+| --- | --- | --- |
+| 会话管理 | 新建、历史加载、重命名、删除、折叠和关闭 | 顶部会话栏，历史通过独立窗口按需打开 |
+| 上下文 | 会话标题、主题选择及管理 | 主题收于助手导航区；会话标题独占下方宽度，最多两行 |
+| 输入 | 多行文字、引用报告或任务、语音输入、草稿 | 底部统一输入区，空会话使用独立欢迎状态 |
+| 模型与权限 | 模型选择、审批模式 | 输入组件底栏，保留当前选项反馈 |
+| 运行控制 | 停止、运行中引导、排队消息、投递方式和未消费消息撤回编辑 | 输入组件顶部的紧凑队列与底栏发送方式 |
+| 消息阅读 | 流式文字、Markdown、历史恢复、滚动跟随 | 主阅读流，用户消息与助手回复分层 |
+| 过程与状态 | 执行进度、工具结果、待办、错误、连接状态 | 回复内的过程区域及顶部真实连接状态 |
+| 人工参与 | 权限审批、问题回答和跳过、补充资料 | 对应回复内保留可操作表单，确认前不执行 |
+| 分析结果 | 指标、表格、折线和柱状图、证据 | 回复中的交互内容，可搜索、排序、选点、筛选序列及已加载区间 |
+| 展开阅读 | 聊天回答与正式报告进入主工作区 | 明确点击进入，保留唯一组件实例、筛选、表单草稿和阅读位置 |
+| 内容追问 | 指标、数据点、表格行、证据 | 带来源的可删除引用；正式报告另带版本和轮次；确认后发送 |
+| 正式报告 | 当前结论、结论边界、证据、缺口、待办、审批与历史版本 | 固定事实区与可选交互分析模块组合 |
+| 地图联动 | 定位实际要素、显示定位结果 | 对应内容内的明确按钮 |
+| 回复工具 | 复制正文及交互摘要、朗读和选段朗读 | 回复底部低强调操作及文字选择入口 |
+| 任务协作 | 任务引用、报告轮次、协作问答模式 | 输入引用区和回复依据，保留协作语义 |
+
+普通用户的阅读路径为：确认当前项目，提出问题，阅读回答，核查来源，再按需要定位地图或补充资料。审批和队列在有实际内容时出现，历史与处理过程按需展开。
+
+运行中的输入区使用一个外框：顶部显示待处理消息，正文最多预览两行，溢出时提供“展开全文”；每条消息只保留正文、简短的处理方式和一个菜单。编辑、处理方式切换、关闭排队统一进入该菜单。底栏在生成期间用“引导 / 排队”替代暂时不能切换的模型选择，生成完成后恢复模型选择。右下角的同一个按钮在运行且输入为空时停止，有内容时发送追加消息，空闲时发送新消息。输入正文默认高 64px，随多行内容自动增高至视口高度的 24%，最多 160px；超出后在输入区内部滚动，清空后恢复 64px；队列单独限制滚动高度，工作台支持的窄屏和短窗口保留可见的输入操作。
+
+## 1. 交互参考
+
+[AI Elements](https://elements.ai-sdk.dev/) 基于 shadcn/ui，提供组合式的 AI 应用组件。它将对话容器、消息、输入、过程、来源和工具状态拆成独立组件，适合在同一条消息中呈现文字与交互内容。官方当前提示组件正在迁入 shadcn/ui；本项目维护本地源码，参考交互方式，按需要适配组件。本文不要求整体替换现有依赖。
+
+| 官方参考 | 采用的设计方式 | 本项目对应内容 |
+| --- | --- | --- |
+| [Chatbot 示例](https://elements.ai-sdk.dev/examples/chatbot) | 以消息阅读为主体，输入区独立，辅助操作低强调 | 左侧会话布局、空会话入口和回复操作 |
+| [Conversation](https://elements.ai-sdk.dev/components/conversation) | 自动跟随消息，离开底部后提供返回入口 | 保留本地滚动管理与“滚动到最新消息” |
+| [Message](https://elements.ai-sdk.dev/components/message) | 用户与助手分层，正文、流式 Markdown、操作栏组合 | 用户气泡、开放式助手正文、复制和朗读 |
+| [Prompt Input](https://elements.ai-sdk.dev/components/prompt-input) | 输入、模型、工具和发送组成同一个输入组件 | 统一输入面、权限模式、模型、语音、停止与发送 |
+| [Reasoning](https://elements.ai-sdk.dev/components/reasoning) | 生成过程可展开，完成后收起 | 已有执行摘要与“查看处理过程” |
+| [Tool](https://elements.ai-sdk.dev/components/tool) | 工具状态与输入、输出按需展开 | 真实执行进度、审批与用户问题 |
+| [Sources](https://elements.ai-sdk.dev/components/sources) | 来源单独呈现，详情按需展开 | 来源名称、证据类别、记录时间及资料编号 |
+| [shadcn/ui Tabs](https://ui.shadcn.com/docs/components/radix/tabs) | 同一内容的视图用键盘可操作的页签切换 | 图表折线、柱状、原始数据切换 |
+
+用户消息与助手回复分层组织，图表、证据与资料输入按内容用途组合。交互内容表达已有数据和可执行动作，不用虚构指标或装饰性进度制造智能感。
+
+## 2. 组件规则
+
+| 区域 | 组件组合 | 展示与行为 |
+| --- | --- | --- |
+| 消息列表 | AI Elements `Conversation`、`Message`、`MessageContent` | 用户右对齐，助手使用完整阅读宽度 |
+| 助手标识 | 共享 `AgentPersona`、shadcn `Badge` | 角色、真实回复状态及交互内容标记 |
+| 回复操作 | AI Elements `MessageActions`、`MessageAction` | 复制正文与结构化摘要，保留朗读能力 |
+| 指标 | shadcn `Card`、`CardContent` | 名称、值、单位、来源；同组指标使用紧凑对照条，提问入口采用有名称的图标按钮 |
+| 图表 | `Card`、`Tabs`、`Collapsible`、现有图表渲染器 | 折线、柱状、数据三种视图；范围筛选按需展开，收起时仍显示已选范围 |
+| 表格 | 本地 shadcn/ui `Table` 组件组合 | 列头、标题、数值、键盘可达的滚动容器 |
+| 证据 | `Collapsible`、`Button`、`Badge` | 收起时可读来源与类别，展开显示完整摘要和编号 |
+| 地图定位 | `Button`、位置图标 | 由用户点击触发，显示依据和实际定位结果 |
+| 补充资料 | `Input`、`Textarea`、`DateTimeField`、`Button` | 从空值开始，明确必填和提交状态 |
+| 历史对话 | `Dialog`、`Input`、会话列表 | 跨主题标题及正文搜索、时间分组、游标分页与会话操作 |
+| 模型与主题 | `DropdownMenu` | 模型选择、主题归类与管理；数据权限跟随当前业务项目 |
+| 报告目录 | `nav`、`Button` | 展开阅读时固定于阅读区顶部，仅显示实际章节；支持键盘跳转和滚动位置提示 |
+| 工作区分栏 | `ResizablePanelGroup`、`ResizablePanel`、`ResizableHandle` | Agent 与主工作区、地图与报告均可拖拽；分隔线可通过 Tab 聚焦，方向键及 Home / End 调整宽度 |
+
+尺寸、圆角和交互状态按样式设计指南选用共享变体。尚未接入的附件、网页搜索和回答重试不展示可点击占位按钮。
+
+## 3. 布局
+
+```text
+桌面
+┌───────────────────────┬──────────────────────────────────────┐
+│ Agent 对话            │ 主工作区                             │
+│ 会话 / 上下文         │ 默认地图                             │
+│ 消息、交互摘要        │ 点击展开 → 报告与分析                │
+│ 待答问题与权限审批    │ 宽度足够 → 地图对照 / 专注阅读       │
+│ 队列摘要 / 引用 / 输入│ 宽度不足 → 查看地图 / 返回报告       │
+└───────────────────────┴──────────────────────────────────────┘
+```
+
+主工作区可用宽度至少 960px 时开放地图与报告双列；较窄窗口在地图与报告之间切换。地图实例保留，不重新初始化。手机只显示当前阅读面；展开时保留原抽屉内容实例，收起后恢复。
+
+2026-10-21 分栏实现更新：采用 [shadcn/ui Resizable](https://ui.shadcn.com/docs/components/radix/resizable)，通过本地 [resizable.tsx](../src/shared/ui/resizable.tsx) 封装 `react-resizable-panels` v4。外层直接承载 Agent 和主工作区，替代手写 Pointer Events 拖拽；内层直接承载地图和报告，替代固定的双列 Grid。
+
+Agent 保留 400px 最小宽度与按窗口计算的最大宽度，上限 640px。收起、临时缩窄窗口及恢复桌面后沿用本次页面内的用户选择。地图与正式报告默认等分，每栏至少 360px；已有分析成果沿用每栏至少 600px 的限制。切换专注阅读后再次分栏，恢复上次调整的比例。手机隐藏分隔线，继续使用抽屉和地图 / 报告切换。尺寸记忆保存在当前页面内，不写入持久化存储。
+
+两级分栏的容器保持挂载，地图 canvas 跟随实际容器尺寸更新；报告内容继续通过单实例移动保留草稿和阅读位置。手柄使用浅灰细线与可见拖拽标记，键盘焦点使用主题蓝色轮廓；连续调宽不附加布局过渡动画。
+
+展开操作移动同一个内容实例，避免两份表单、重复提交和草稿分歧；关闭或 Escape 后回到原入口并恢复键盘焦点。阅读位置随文档保留。报告版本改变时切换到该版本自己的内容状态。会话或报告卸载时关闭对应工作区。
+
+
+```text
+Agent 面板
+├─ 会话栏：助手标识 / 连接状态 / 新建与历史 / 折叠或关闭
+├─ 上下文条：会话标题 / 主题
+├─ 可滚动消息区
+│  ├─ 用户问题
+│  └─ 助手回复
+│     ├─ 角色和真实生成状态
+│     ├─ 正文与指标、趋势、表格
+│     ├─ 证据、地图入口、资料表单
+│     ├─ 可展开的处理过程
+│     └─ 复制与朗读
+└─ 输入区：引用 / 多行输入 / 权限、模型、语音、发送或停止
+```
+
+纯指标的双列 `Stack` 合并为紧凑摘要区，容器宽度达到 240px 即可并排；名称、原始数值、单位和来源完整保留，不用省略号截断。指标提问按钮放在名称旁，减少单独操作行。混合内容的双列仍使用 440px 断点。助手正文直接进入消息流，证据按需折叠，补充表单保留独立操作区；表面与间距统一引用样式设计指南。
+
+图表首先显示标题、视图切换、序列和趋势。范围选择默认收起，展开后可选择起止点及重置；收起只改变展示，不取消已选范围。序列按钮使用低强调色，图例颜色保留数据对应关系；至少一条序列可见。数据点的各序列值分行对齐，保留原始精度。
+
+正式报告展开后采用连续文档排版，章节之间使用细分隔线。目录跟随阅读区滚动，包含实际存在的结论、分析、调查进展、待办、处置、缺口、脉络、依据、时间线和版本。目录使用导航语义，点击或键盘激活后立即滚动并将焦点交给目标章节；手机目录可横向滚动。接近文档末尾、目标无法滚至顶部时，保留主动选择的章节标记，直到用户再次滚动。该导航只改变阅读位置，不控制任务执行或审批。
+
+空会话采用“简短引导、首次输入、推荐问题”的顺序，整组在 Agent 面板内横向居中，放在会话栏下方可用区域的中部。居中容器最多 600px，桌面内边距 24px，手机左右内边距 16px；短屏内容超过可用高度时从顶部排列并允许滚动。判断依据是当前会话有无消息，不取决于帐号是否保存其他历史会话。加载历史或已有任务状态、审批、结构化结果时保留正常阅读区，不覆盖为欢迎页。
+
+输入文字区初始高度 64px，按内容增长至视口允许的高度。首次发送后同一个输入组件回到底部；新建空会话后恢复居中布局。使用 `motion/react` 的位置布局动画处理这两种状态，沿用项目的 180ms 缓动，不缩放输入文字，也不对 Resizable 连续调宽添加动画。系统开启减少动态效果时直接切换位置。表单实例和草稿在布局变化时保留。
+
+推荐由现有接口生成，排列在首次输入框下方，使用低强调的圆角按钮，窄屏自动换行显示完整问题，实际来源仍可通过 hover 或键盘焦点提示查看。点击发送完整原始问题。加载或生成失败时显示简短状态，也不影响普通输入。材质与边界复用共享样式，输入底栏保留现有操作。
+
+Agent 形象基于 [Obsidian 原版动画资源](https://ejiidnob33g9ap1r.public.blob.vercel-storage.com/obsidian-2.0.riv)，通过本地定制的 `obsidian-water-v1.riv` 使用已确认的 02「冰水蓝」材质并增加离线水纹，以高遮蔽度的浅冰蓝底色和白色高光保留柔和羽化、流动反射与不规则边缘水纹。完整视觉与交互规格见 [Persona 设计](agent-persona-design.md)。默认形象与悬浮入口使用 64 × 64px，画布填满点击范围；入口距地图左侧、顶部导航下沿均为 12px，由同一层内边距控制。桌面及手机面板标题栏中的形象也使用 64px，手机地图入口使用 40px。三处通过同一个 `AgentPersona` 组件显示，保留原版资源自身的羽化留白。悬浮形象不附加状态文案、状态点、箭头、卡片或按钮底圈。完整业务状态继续通过按钮无障碍名称与原生悬停提示提供，点击或 Enter / Space 展开对话。
+
+标题区分为导航与标题两层。导航行高 80px：左侧为 64px persona，其右侧首行并列助手名称与连接状态，状态位于名称右侧；下方间隔 6px 放置主题下拉，使用文件夹图标与名称，不再另列“主题”标签。连接状态保留共享状态点和文字，主题按钮使用本地 `Button` 的 `outline` / `sm` 变体，高 32px，使用文件夹和 Lucide 上下切换箭头。右侧集中放置新建、历史及折叠或关闭按钮，命中范围均为 40px。导航与会话标题之间只保留一条本地 `Separator`，使用 1px、`bg-border/40` 的低对比度分界线。默认空白会话不渲染“新对话”占位标题，也不保留空标题行。有实际会话时，标题区四周留白 12px，只显示当前会话标题，独占宽度、最多两行，不再增加下边框。长主题名在导航剩余空间内收缩，完整名称通过提示与可访问描述保留；320px 手机宽度下不挤压三个操作按钮。
+
+在线动画由 Rive WebGL2 播放原资源的 `default` 状态机。沿用原生 `thinking`、`listening`、`speaking` 和 `hover` 控制项，状态过渡及水纹细节由资源自身完成。原版公开组件可见 [AI Elements Persona 源码](https://github.com/vercel/ai-elements/blob/main/packages/elements/src/persona.tsx)；图形制作数据位于运行资源中，可编辑设计文件是 `.rev`，见 [作者的定制说明](https://elements.surge.studio/docs/customization)。已移除之前自行生成球缘曲线、光带和局部高光的实现，也移除改写原版明暗的 CSS 滤镜。配色直接写入 Rive 材质，暗部保持蓝色倾向，高光使用白色。
+
+离线通过同一 Rive 资源中的 `asleep` 状态呈现“静水待机”：关闭外围三层光圈，保留完整蓝色球体及内部柔光的低速、小幅度流动。在线与离线切换保持同一个动画实例，通过资源内的状态混合衔接，恢复连接后回到在线光圈与节奏。参数和图层说明统一维护在 [Agent 动画资源说明](agent-persona-resource.md)。首次加载、加载失败和系统开启减少动态效果时显示从当前资源渲染的在线或离线静态帧，离线静态帧同样不带外围光圈；兜底形象与按钮功能持续可用。
+
+鼠标悬停沿用原生 `hover` 动画和光圈尺寸；进入、移动、离开坐标通过共享组件交给 Rive 原生监听，使白色高光跟随鼠标局部移动，避免只开 hover 却使反射固定在中心。移出后恢复常态。球体组件移除 Motion，取消按压缩放、弹簧回弹和明暗变化；触摸按下不触发额外动画。点击、触摸轻点及 Enter / Space 继续展开对话，离线时同样可用。系统开启减少动态效果时显示静态帧，不初始化 Rive。强制颜色模式显示高对比圆形轮廓，保留键盘操作。球体动画与面板布局独立，不对 Resizable 连续调宽增加动画。
+
+渲染生命周期继续遵守 [Rive 内存问题记录](rive-persona-incident.md)：延迟一帧初始化，元素离开视口或页面隐藏时卸载渲染实例，不绑定 View Model；仅缓存不可变的 `.riv` 字节，展开、折叠和不同入口复用一次成功下载。失败下载不永久缓存，后续挂载可重试。动态组件准备完成前保留本地静态帧，原生进入动画在显示切换前完成。静态帧与动画通过 180ms CSS 透明度渐变衔接，结束后才隐藏静态帧，避免首次加载瞬间切换造成的跳动；画布的位置与尺寸始终固定。本轮没有新增依赖，也没有恢复已知存在内存问题的颜色绑定。
+
+### 离线动画的资源改造
+
+已解析原版的图形、属性、关键帧和状态机，保存为可读的运行时 JSON，并验证可以逐字节恢复原始 `.riv`。修改后的资源保留 5 个原生状态输入，在原有 20 段动画后增加 3 段离线循环，修正 `asleep` / `wake` 中隐藏和缩小球体的关键帧。修改、再生成及保真验证见 [Agent 动画资源说明](agent-persona-resource.md)。这份 JSON 是运行时数据，不是完整恢复的 `.rev` 编辑器工程。
+
+### 历史窗口、缓存与后台会话
+
+“主题”参考 [ChatGPT Projects 的会话组织方式](https://help.openai.com/en/articles/10169521-projects-in-chatgpt)，作为会话组织单元，用于归集相关事件和问题；与决定数据权限的业务项目分开。Agent 的主题下拉参考 shadcn [TeamSwitcher 模板](https://github.com/shadcn-ui/ui/blob/main/apps/v4/registry/new-york-v4/blocks/sidebar-07/components/team-switcher.tsx)的起始对齐、触发器宽度与最小菜单宽度，配合本地 `DropdownMenuRadioGroup` 表示主题单选。菜单标注“切换主题”，主题列表独立滚动，新建与管理操作保留在底部；支持未分类、主题选择、新建和管理；原无处理逻辑的“新建项目”入口移除。Agent 默认访问当前工作台业务项目的数据，移除聊天面板中的“个人／项目数据”切换入口及前端个人会话分支。数据访问权限由项目身份和服务端授权决定，后续按角色限制可访问范围，主题选择不改变数据权限；业务项目切换仍从工作台入口进入。选择主题开启该主题的新对话，当前会话草稿和后台生成继续保留；新建对话沿用当前主题。主题名可修改，删除主题时会话保留为未分类；历史行操作可将已有会话移入其他主题或移出为未分类。主题列表内存缓存 5 分钟，登录和业务项目隔离，并发复用。旧会话默认未分类，不移动现有业务数据。本轮主题用于组织记录，不自动合并其他会话上下文、共享指令或附件。
+
+主题新建、重命名、管理与删除确认使用标准 `DialogHeader`、`DialogDescription`、`Input` 和 `DialogFooter`。表单显示名称标签、80 字符限制、错误与取消/提交按钮；管理页使用可滚动的平面列表，每行保留重命名与删除入口，底部提供新建与完成。重命名和删除进入有明确标题的独立步骤，删除前确认会话保留规则。打开表单聚焦名称输入，打开管理页聚焦新建入口；失败保留输入，关闭后恢复主题按钮焦点。主题增删改先完成共享列表读取，再更新服务端与缓存，防止旧列表请求晚返回覆盖刚创建或修改的主题。
+
+历史按钮打开独立模态窗口，桌面最大宽度 760px、高度不超过视口的 80%；小于 640px 时使用全屏窗口，保留安全区和独立滚动。窗口包含当前业务项目、标题及正文搜索、主题筛选、时间分组、会话状态和关闭入口。标题最多两行，重命名和删除进入每行操作菜单，删除需明确确认。选择会话成功后关闭窗口，失败时保留当前聊天与列表并显示错误。关闭、Escape 及取消操作恢复触发按钮焦点；模态期间底层地图和通知不覆盖窗口。
+
+会话列表每页 30 条，标题及可见消息正文搜索在服务端覆盖当前用户及当前业务项目下的全部主题及未分类记录，结果显示所属主题和正文命中摘要，输入防抖 250ms，按更新时间及 ID 排序；时间按浏览器本地时区分为今天、昨天、近 7 天和更早。窗口浏览期间保持条目顺序，运行状态原位更新；有新的排序结果时由用户点击更新。关闭窗口保留已加载页和搜索缓存。历史统一包含普通对话和手动任务协作，不展示后台执行会话。主题筛选独立于搜索词，默认“全部主题”，不随当前对话主题隐式收窄。
+
+正文首次读取最近 40 条，向上滚动或点击“加载更早消息”继续读取。插入旧页保持当前可见消息的位置。用户向上阅读后停止自动跟随，点击返回最新消息恢复跟随。恢复流也使用最近消息页，客户端按稳定消息 ID 合并旧页和实时尾部，断线区间缺口通过分页补齐。服务端仍保留完整历史，续聊只发送本轮输入；UI 分页不截断原生会话和保存记录。当前磁盘存储仍整份读取 JSON，分页主要减少网络传输和浏览器渲染。
+
+缓存属于当前登录生命周期，按业务项目隔离并跨工作台重挂载复用；退出登录后释放。历史列表和已读正文缓存 60 秒，授权项目列表 5 分钟，推荐问题 10 分钟，推荐生成失败缓存 30 秒。有效期内打开窗口和面板不重复请求。过期刷新保留已有内容，并发消费者共用请求，单个消费者关闭不取消共享请求。主动刷新及真实数据变更按需更新缓存，项目进入操作仍核验访问上下文。
+
+推荐依据使用独立的近期会话页，历史搜索和翻页不改变输入。缓存摘要按活动 ID、标题、内容、状态及来源计算，单纯心跳时间变化不触发推理。生成新推荐时保留上一组问题。
+
+每个会话持有独立 Chat 实例、生成连接、草稿、引用、阅读位置和审批状态。切换历史或新建对话保留原会话后台生成；后台需要审批或回答时，通过历史入口提示返回处理。模型、项目头和凭据续期绑定原会话。后台浏览器动作返回 `SESSION_NOT_ACTIVE`，提示用户回到会话后重新请求；切换时取消原会话尚在执行的浏览器动作。恢复失败保持可重试的连接异常状态，不将断流视为任务完成。切换业务项目由工作台统一处理，会话、主题及缓存按业务项目隔离。
+
+## 4. 内容与状态
+
+`answer-ui@1` 仍由严格参数校验与本地注册组件驱动。已有的 `Stack`、`Section`、`Text`、`Metric`、`Table`、`Chart`、`Evidence`、`MapLocation`、`FollowUpForm` 使用新外观。聊天继续使用现有 Responses 事件；正式报告增加可选 `ui_blocks` 字段，复用相同的内容块协议。实现契约见 [本地交互式回答](agent-answer-ui.md)。
+
+生成中显示已经到达的文字、内容块和公开执行摘要；最终答复到达后，正文和它明确引用的内容留在主阅读流，其他记录进入处理过程。待回答问题、权限审批和失败状态保持可见，不能因最终文字到达而被隐藏。这里借鉴 Reasoning 的折叠行为，呈现的数据是服务端已发布的过程信息，不额外生成思考文本，也不根据耗时推算完成比例。
+
+证据类别明确区分查询记录、用户提供、分析推断和演练数据。地图定位的按钮结果以实际回调为准；资料表单提交后只表示发送消息，业务证据是否保存取决于后端实际结果。最终回复不等于后台调查任务完成。
+
+## 5. 实现边界
+
+保留 Vite 和 React SPA。通用 AI 展示组件位于 `src/shared/ai-elements/`，基础组件位于 `src/shared/ui/`；消息业务组合位于 `src/features/agent/components/`，结构化回答位于 `src/features/agent/answer-ui/`。
+
+不引入 Next.js 路由、服务端组件或第二套聊天接口。地图控制器、会话存储和审批流程沿用已有实现。报告内容扩展同时进入 Agent 校验、Server 校验、现有报告 JSON 存储和 OpenAPI。组件按需加入本地源码，避免批量覆盖已定制的共享组件。AI Elements 负责展示组合，现有 Responses transport 负责消息传输，两者的职责分开。
+
+## 6. 响应式与业务验收
+
+桌面验证 1280px 及以上窗口，并检查面板宽度 400px、640px 的真实布局；手机验证 320px、375px。手机 Agent 默认打开全高抽屉，输入区进入正常布局，阅读内容不藏在悬浮输入框下面；抽屉仍可手动调低查看地图。混合内容在手机上使用单列，短指标按容器宽度保留双列。输入、发送、模型菜单、证据展开和滚动返回均需可操作。
+
+本轮聚焦验收包括图表页签与方向键、证据键盘展开、历史恢复、表单提交、复制回复、流式结束和面板缩放。检查文字与背景对比度、减少动态效果和强制颜色模式。运行 lint、类型检查、相关单测、聚焦浏览器测试；依赖变化额外运行构建。浏览器演练数据必须标明来源，截图不代表真实业务核验。
+
+当前文档描述本轮目标与实现约定，实际通过的检查和预览截图以交付记录为准。
+
+## 7. 交互规则与范围
+
+| 内容 | 本轮实现 | 数据与操作边界 |
+| --- | --- | --- |
+| 指标 | 值、单位、来源，针对指标提问 | 不补造变化率、单位或精度 |
+| 表格 | 搜索、三态排序、行选择、引用所选行 | 只处理当前数据；更换数据集时重置行选择 |
+| 图表 | 折线 / 柱状 / 数据，序列显隐，加载区间，点击或键盘选点 | 最少保留一条序列；区间不触发查询或重算 |
+| 证据 | 来源、类别、时间、编号，展开与类别筛选 | 正式报告使用已保存证据覆盖生成的摘要、来源和类别 |
+| 地图 | 显式定位，地图对照或切换 | 使用真实定位结果与失败反馈 |
+| 表单 | 空白初始值、必填校验、提交中禁用、失败保留 | 聊天表单主动发送；报告表单先带入对话，确认后发送 |
+| 追问 | 输入区引用卡片、详情、移除 | 不自动发送；报告引用带选中的版本与轮次 |
+| 历史内容 | 固定报告事实可读，不支持的块显示摘要 | 降级不执行未知组件或事件 |
+
+本轮未包含参数重算、新数据查询控件、附件上传、导出、报告版本差异比较。后续扩展时需要独立定义参数校验、数据来源和执行反馈；不能把本地筛选当作重新分析。后台任务完成、业务审批和证据写入继续以各自服务端状态为准。
+
+## 8. 正式报告契约
+
+`InvestigationReport.ui_blocks` 可省略；每项包含 `block: AnswerUiBlock` 和 `evidence_refs: string[]`。最多 8 块，总 UTF-8 JSON 不超过 400000 字节；单块完整序列化结果不超过 100000 个 JavaScript UTF-16 代码单元，最多 48 节点、深度 12。每块绑定至少一条报告证据，`Evidence` 节点只能引用该块的依据。Server 发布时再检查这些证据确属当前任务。
+
+固定报告字段不变：阶段、结果、结论、边界、数据缺口、证据和建议仍独立校验。新字段通过原有报告 JSON 保存，跟随 revision 与 execution_generation 读取；请求幂等沿用原有机制。旧报告缺省为空，不因缺省字段而产生虚假的报告更新通知。无需数据库表或环境变量迁移。
+
+组件参数唯一来源为前端 `catalog.ts`，导出到 Agent 与 Server；跨字段约束在三端分别验证。Agent `publish_task_report` 使用正式报告通道，聊天 `present_answer` 使用聊天通道。实现与生成命令见 [本地交互式回答](agent-answer-ui.md)。

docs/agent-persona-design.md

@@ -0,0 +1,100 @@
+# Agent Persona 设计
+
+更新日期：2026-10-22。本文保存供水前端当前的 Persona 视觉与交互规格，作为后续调整的基线。资源解析、再生成及缓存实现见 [动画资源说明](agent-persona-resource.md)；通用控件和语义表面继续遵循 [样式设计指南](style-design-guide.md)。
+
+## 1. 形象与材质
+
+采用 Obsidian 原生 Rive 水纹球，保留柔和羽化、流动反射、不规则边缘水纹和状态机。配色采用已选定的 02「冰水蓝」：浅色水体承载白色高光，暗部保持蓝色，外围水纹提供地图上的辨识度。主体底色具有较高遮蔽度，减少地图道路穿过球体的现象。
+
+| 角色 | 当前值 | 用途 |
+| --- | --- | --- |
+| 球面底色 | `#DCEFFA` | 浅冰蓝底层，独立于流动反射 |
+| 底色不透明度 | 待机 94%，活动 98% | 保持主体清楚，避免背景纹理干扰 |
+| 水体反射 | `#299FDF` | 提供蓝色层次与流动感 |
+| 同色相暗部 | `#1482BC` | 保留体积，避免灰黑混色 |
+| 高光 | `#FFFFFF` | 保留清晰、干净的反射 |
+| 外围水纹 | `#4C9ECC` | 提高浅色地图上的辨识度 |
+
+颜色直接写入 Rive 资源，不使用 CSS 色相、亮度或对比度滤镜。通用 UI 仍引用共享语义颜色；上表仅定义动画资源本身的材质。参数源为 [obsidian-material.json](../design/agent/obsidian-material.json)。
+
+以下为当前资源的实际静态帧，用于辨认在线与离线外观；运动行为以第 4 节为准。
+
+| 在线待机 | 离线静水待机 |
+| --- | --- |
+| <img src="../public/agent/obsidian-water-idle.png" width="64" height="64" alt="冰水蓝在线 Persona，有外围水纹"> | <img src="../public/agent/obsidian-water-offline.png" width="64" height="64" alt="冰水蓝离线 Persona，无外围光圈"> |
+
+## 2. 尺寸与定位
+
+| 使用位置 | 画布尺寸 | 布局要求 |
+| --- | --- | --- |
+| `AgentPersona` 默认 | 64 × 64px | 固定尺寸，不随状态变化 |
+| 桌面收起入口 | 64 × 64px | 画布填满按钮命中范围 |
+| 桌面与手机面板标题栏 | 64 × 64px | 与名称、状态共同形成身份区 |
+| 手机地图入口 | 40 × 40px | 使用同一资源，适应地图工具栏 |
+
+桌面收起入口距地图左侧 **12px**，距顶部导航下沿 **12px**。两个方向由同一定位层的内边距控制；当前导航高 56px，因此入口左上角为视口中的 `(12px, 68px)`。这里的顶部距离以导航下沿为起点。
+
+尺寸指整个 Rive 画布，包含资源固有的羽化留白。放大时保留画板比例，不裁掉外围水纹。悬浮入口仅显示 Persona；状态通过按钮名称与悬停提示提供，避免增加卡片、状态点、箭头或底圈。
+
+## 3. Agent 标题区
+
+身份行高 **80px**，左右内边距 12px、上下 8px。左侧为 64px Persona，旁边上下排列名称“供水助手”和连接状态；右侧集中排列对话操作。
+
+| 内容 | 规格与行为 |
+| --- | --- |
+| 名称 | 14px、半粗，与现有标题排版一致 |
+| 连接状态 | 12px 辅助文字配共享 `StatusDot`；显示实际的“连接中 / 在线 / 离线” |
+| 操作 | 新建对话、历史、折叠；手机末项为关闭，每项命中范围 40 × 40px |
+| 上下文行 | 高 36px，保留会话标题与项目或个人范围切换 |
+
+身份行与上下文行保持连续的浅色表面，在标题区底部使用分隔线。历史展开、键盘导航和关闭后焦点恢复沿用现有行为。320px 手机宽度下，名称、状态和三个操作均应完整显示且互不重叠。
+
+## 4. 动画与状态
+
+动画由 Rive WebGL2 的同一个 `default` 状态机驱动，业务层提供真实状态。在线水纹持续流动；离线保持完整球体，通过节奏与光圈变化表达连接不可用。
+
+| 状态 | 呈现 |
+| --- | --- |
+| `idle` | 原生待机流动与外围水纹 |
+| `thinking` | 原生处理状态动画 |
+| `listening` | 原生等待输入动画，具体含义由业务映射决定，不单凭形象表示麦克风录音 |
+| `speaking` | 原生输出状态动画 |
+| `asleep` | 内部柔光低速、小幅流动，外围三层光圈透明度为 0 |
+| `hover` | 鼠标附近的局部白色反射随指针移动，与当前业务状态叠加 |
+
+离线设计称为“静水待机”。在线与离线以 **600ms** 混合切换，可见实例保持挂载；离线球体持续运动，恢复在线后恢复外围光圈。离线悬停也不重新打开外围光圈。
+
+离线三层循环周期为 **15s / 19.25s / 31.375s**，位移与呼吸振幅为原来的 25%，完整旋转保持循环闭合。时间轴速率由 60 调至 24，约为原速 40%；此值不代表屏幕渲染帧率上限。详细图层参数见 [obsidian-offline.json](../design/agent/obsidian-offline.json)。
+
+## 5. 悬停与点击
+
+悬停沿用原版三层反射的尺寸、渐变、亮度和淡入淡出。白色高光跟随鼠标所在位置：从左侧移到右侧时，高光随之移动；鼠标离开后恢复常态。不能只打开 `hover` 布尔值而遗漏坐标，否则原生指针目标停在默认中心，造成球体中间大片变白。球体、点击范围和常态外围水纹尺寸均保持原定义。
+
+共享 `Persona` 保留 Rive 原生指针监听，将主指针的进入、移动、离开和取消转交给画布；坐标转换与资源内的跟随约束由 Rive 完成。触摸及按压不转交动画，不绑定 View Model。悬浮入口和标题形象共用这条通路，画布就绪后才接收交互。
+
+点击、触摸轻点及 Enter / Space 展开对话，离线时同样可用。球体不添加 Motion 按压缩放、弹簧回弹或按下变暗；触摸按下不模拟 hover。外层面板的布局动画独立维护，Resizable 连续调宽保持直接响应。
+
+## 6. 加载、降级与缓存
+
+首次加载显示当前资源导出的静态帧。Rive 加载后先等待 600ms 完成原生进入动画，再以 **180ms CSS 透明度渐变**衔接，尺寸和位置保持固定。在线、离线分别使用相应的本地 PNG，避免银灰占位与蓝色动画之间的突变。
+
+系统开启“减少动态效果”时显示静态帧，不初始化 Rive；资源失败时保留相应静态形象与按钮功能。强制颜色模式显示高对比轮廓，保留焦点和键盘操作。元素离开视口或页面隐藏时卸载渲染实例，可见后恢复。
+
+客户端按页面内存、Cache Storage、网络的顺序取得资源。仅共享不可变 `.riv` 字节，每个可见入口独立创建动画实例；不共享实例或绑定 View Model。资源重建时同步生成 SHA-256 版本，URL 带版本参数，使旧缓存自然更新。缓存范围与校验逻辑见 [动画资源说明](agent-persona-resource.md)。
+
+## 7. 实现与维护
+
+| 入口 | 文件 |
+| --- | --- |
+| 业务形象与降级 | [AgentPersona](../src/features/agent/components/agent-persona.tsx) |
+| 原生状态机接入 | [Persona](../src/shared/ai-elements/persona.tsx) |
+| 桌面悬浮按钮 | [AgentCollapsedRail](../src/features/agent/components/agent-collapsed-rail.tsx) |
+| 标题区 | [AgentCommandPanel](../src/features/agent/components/agent-command-panel.tsx) |
+| 资源生成与原版还原 | [build-agent-persona.mjs](../scripts/build-agent-persona.mjs) |
+| 资源版本与缓存 | [persona-resource.ts](../src/shared/ai-elements/persona-resource.ts) |
+
+材质与离线参数以对应 JSON 为准，悬停沿用原始资源中的几何与指针约束；改动时同步本文与资源说明。原始解析数据保留以便逐字节还原 `.riv`；该数据不等于作者完整的 `.rev` 编辑器工程。
+
+验收时检查 64px 桌面入口、64px 标题形象与 40px 手机入口，覆盖默认、悬停进入与退出、快速切换、离线和恢复在线。桌面检查 1024/1440px 视口及 400/640px 面板，手机检查 320/375px。确认左上间距一致、按压无缩放、首次加载无画面硬切、底色能遮蔽地图、离线无外围光圈、缓存刷新后仍加载当前版本。
+
+资源级检查使用固定时间步对照原版与修改版：在线状态保持相同材质下的逐像素一致；悬停检查左右移动时局部高光跟随指针，移出后完全恢复。工作台检查鼠标坐标实际到达悬浮入口和标题形象的 Rive 监听器，不能仅断言 hover 开关变化。离线检查完整球体、持续变化和光圈关闭。运行命令见 [资源说明](agent-persona-resource.md)，各次实际验证结果记录在 [实施记录](history/agent-chat-ui-implementation-notes.md)。

docs/agent-persona-resource.md

@@ -0,0 +1,91 @@
+# Agent 动画资源与离线水纹
+
+Agent 保留原版 Obsidian 图形与运动结构，采用经实际动画对比选定的 02「冰水蓝」配色，并在 Rive 文件内部增加“静水待机”离线设计。在线保留外围水纹光圈；离线关闭外围三层光圈，仅保留球体内部的缓慢流动。在线、离线和交互使用同一个 `default` 状态机。
+
+当前视觉规格、尺寸、标题区与交互约定统一见 [Persona 设计](agent-persona-design.md)。本文维护资源结构、生成过程与缓存实现。
+
+## 文件与再生成
+
+| 文件 | 用途 |
+| --- | --- |
+| [运行时源数据](../design/agent/obsidian-runtime.json) | 从原版解析的 775 个对象，包含图形、属性、关键帧、状态机和绑定数据 |
+| [冰水蓝材质参数](../design/agent/obsidian-material.json) | 已确认的水体、暗部、白色高光和水纹颜色，以及球面底色遮蔽度 |
+| [离线设计参数](../design/agent/obsidian-offline.json) | 可编辑的播放速度、振幅、混合时长和三层柔光/反射强度 |
+| [生成脚本](../scripts/build-agent-persona.mjs) | 验证原版重编码、修改离线动画，生成本地资源 |
+| [应用资源](../public/agent/obsidian-water-v1.riv) | 前端加载的 9,879 字节资源 |
+| [缓存版本清单](../src/shared/ai-elements/persona-resource-manifest.json) | 生成脚本同步输出的路径、SHA-256 和字节数，用于客户端缓存更新 |
+| [静态帧生成脚本](../scripts/render-agent-persona-stills.mjs) | 从实际资源渲染在线、离线 PNG，供首次加载、减少动态效果和失败兜底使用 |
+| [资源对照测试](../tests/browser/agent-persona-resource.e2e.ts) | 真实 WebGL2 运行时定时推进，比较原版与修改版画面 |
+
+在前端仓库运行：
+
+```bash
+node scripts/build-agent-persona.mjs
+node scripts/render-agent-persona-stills.mjs
+node scripts/build-agent-persona.mjs --check
+# 将原版还原到一个尚不存在的文件，应用资源不会被替换
+node scripts/build-agent-persona.mjs --restore-original /tmp/obsidian-original.riv
+pnpm test:browser tests/browser/agent-persona-resource.e2e.ts tests/browser/agent-orb.e2e.ts --workers=1
+```
+
+JSON 保存原始运行数据；脚本负责可审查的定制。`--check` 验证原始数据能逐字节恢复，并检查生成结果与应用资源一致。基线 SHA-256 为 `c6ae7d08f5787a560e38d3453ba155c28250acf2db75e6acf2b0d1a0cd6017db`。替换上游基线时需重新解析和验证，不应只修改散列值跳过检查。
+
+配色编辑 `obsidian-material.json`，其中 `bodyColor` 只控制球面底色，`bodyOpacity` 控制它在待机/活动时的遮蔽度，其他蓝色反射沿用 `colors` 映射；离线动画编辑 `obsidian-offline.json`；重新生成 `.riv` 和静态帧后刷新前端。静态帧脚本使用已安装的 Playwright、esbuild 与 Rive WASM，无需访问外部动画服务。`fps` 控制离线时间轴速度，`amplitude` 控制位移与缩放的变化幅度，`transitionMs` 控制在线/离线的混合时长。各层 `opacity` 中的 `rest` 和 `crest` 是相对原始透明度的比例，分别对应循环开始/结束与中点。数值需满足 `0 ≤ rest ≤ crest ≤ 1`；保留循环端点一致，避免接缝。外围三个光圈均固定为 `0`。
+
+`--restore-original` 使用只创建模式，目标文件已存在时会报错，避免覆盖已有编辑。原版还原文件与基线逐字节相同，包含原版离线消失的行为；前端继续加载带离线设计的应用资源。
+
+## 冰水蓝与离线设计
+
+材质采用经原生 Rive 预览选定的 02 方案：水体 `#299FDF`、同色相暗部 `#1482BC`、白色高光 `#FFFFFF`、外围水纹 `#4C9ECC`。外围水纹从初选时的 `#B0E3FF` 加深，以提高浅色地图上的辨识度；光圈粗细、渐变 alpha 和运动保持原定义。球面底色独立设置为 `#DCEFFA`，待机/活动时的不透明度为 94%/98%，同步调整对应的活动状态关键帧。浅色且高遮蔽度的底层减少地图道路穿过球体的现象，蓝色反射仍由原来的运动图层呈现；暗部沿用蓝色调，避免叠加灰黑阴影。渐变位置、羽化、裁剪、运动曲线及其他节点的原有 alpha 保留，不添加 CSS 滤镜或 View Model 绑定。
+
+此前 A「水务蓝」使用灰蓝主体、浅蓝高光与 78%/90% 的底色不透明度，在白底实际动画中显得发灰、浑浊，已被本方案替换。后续调整以同一背景下的真实动画及 40/64px 入口效果为准，不以色卡单独判断材质。
+
+离线以“水面逐渐平静”表达连接不可用：外围三层光圈在 600ms 混合期间消退至完全不可见，内部柔光降低并保持缓慢流动。球体整体透明度和缩放保持完整；悬停不会重新打开离线光圈。恢复在线时重新显现光圈与在线节奏。业务状态仍由入口按钮的可访问名称和提示提供。
+
+| 层 | 柔光强度 | 反射强度 | 循环周期 |
+| --- | --- | --- | --- |
+| 内层与下侧柔光 | 56%–68% | 0，关闭 | 15 秒 |
+| 中层与内部柔光 | 48%–62% | 0，关闭 | 19.25 秒 |
+| 外层与上侧柔光 | 60%–72% | 0，关闭 | 31.375 秒 |
+
+上表是设计参数当前值的解释。内部柔光以原版贝塞尔缓动从 `rest` 升到 `crest` 再回落，周期错开，避免同步闪烁；光圈透明度保持为零。40/64px 入口共用同一资源，状态切换不改变布局尺寸。
+
+参数中的图层名称是根据运行时结构补充的语义别名，不是恢复出的作者原始命名。`objectId` 是画板组件编号，不能用 JSON 对象数组的索引替代：绑定记录不占组件编号。
+
+## 解析结果与修改
+
+原版有 1 个 `Obsidian` 画板、20 段动画、13 个状态机层和 5 个布尔输入。`asleep` 动画在第 45 帧将节点 4 的透明度从 1 降至 0，并将节点 3、190、199、208 的缩放降至 0.6–0.8，因此离线时球体消失。
+
+修改版保留原有图形、渐变结构、羽化、裁剪和在线运动，改变以下部分：
+
+- 根据已选定的配色映射 RGB，并独立设置底色填充节点 189 的颜色、节点 186 的静止及活动透明度；原始 JSON 不改动，仍可完整还原银灰原版 `.riv`。
+- `asleep` / `wake` 的透明度与缩放关键帧保持 1，避免隐藏或缩小球体。
+- 在原有 20 段动画后追加 `offline_loop_1`、`offline_loop_2`、`offline_loop_3`，保持原有动画编号。
+- 离线循环复用原版三层水纹，时间轴速率从 60 改为 24，约为原速的 40%；这是时间轴播放速度，不是将屏幕渲染限制为 24fps。
+- 位移和呼吸振幅缩至原来的 25%；完整旋转保留首尾角度，避免循环接缝。
+- 离线循环增加六个柔光/光圈节点的透明度轨道，其中节点 190、199、208 的光圈透明度固定为零；在线循环对应增加原始透明度常量轨道，确保恢复连接后完整恢复。
+- 三个循环层根据既有 `asleep` 输入切换，使用 600ms 状态混合。其他输入、状态层和交互保持原定义。
+
+生成结果包含 957 个对象、23 段动画。调整设计参数后需再生成并运行对照测试；无需修改前端组件或安装额外依赖。
+
+## 前端接入与生命周期
+
+悬停沿用原版节点 110 的反射尺寸，以及节点 129 对指针目标 1 的跟随约束。`Persona` 保留 Rive 监听器，通过外层 Pointer Events 向画布转交鼠标的进入、移动和离开坐标，Rive 自行完成画布与画板坐标转换。画布内部不直接命中鼠标或触摸，只有就绪的外层接收并筛选主指针；不转交触摸和按压，因此手机点击不会触发白色高光。仅手动设置 `hover` 而禁用原生监听，会使目标停在中心，造成中央大片变白。这个问题由事件通路修复，不通过缩小光圈或改变材质补偿。
+
+`persona-resource.ts` 加载同源的 `/agent/obsidian-water-v1.riv?v=<SHA-256>`。同一页面共用下载 Promise，跨刷新、再次打开页面使用浏览器 Cache Storage 的 `tjwater-agent-persona-v1` 缓存；只共享不可变字节，不共享 Rive 实例或 View Model。
+
+读取顺序为页面内存、当前版本的持久缓存、网络。下载及缓存命中均检查字节数和 `RIVE` 文件头；支持 Web Crypto 时进一步验证 SHA-256。损坏缓存重新下载，错误页或不匹配的资源不写入缓存。新版本成功保存后，只删除本缓存中该资源路径的旧版本，不清理其他应用数据。重新生成动画时同步更新版本清单，`--check` 同时验证资源与清单。
+
+持久缓存不可用、被禁用或空间不足时仍可下载并在当前页面复用。Cache Storage 需要安全上下文，生产环境使用 HTTPS，本机 localhost 开发可用；浏览器清理站点数据也可能移除缓存，见 [Cache API 说明](https://developer.mozilla.org/en-US/docs/Web/API/Cache)。缓存测试覆盖真实页面刷新，并阻断资源网络路径验证动画仍能播放。
+
+Agent 服务不可用不妨碍前端读取该资源。这项缓存仅覆盖 `.riv`，Rive WASM、应用代码与其他资源沿用各自的加载策略；不构成整站离线支持。浏览器完全断网且应用或运行时尚未加载时，仍可能无法播放动画。
+
+在线与离线切换不卸载可见的 Rive 实例，由状态机处理过渡。静态帧仅用于首次加载、资源失败、减少动态效果及未挂载动画的情况：在线使用 `obsidian-water-idle.png`，离线使用无外围光圈的 `obsidian-water-offline.png`。两张 192px PNG 均由当前 Rive 材质直接渲染，URL 携带资源版本；首次加载维持 180ms 淡入，不再出现银灰占位图。保留可见性卸载、Strict Mode 延迟初始化和原版悬停；没有重新加入 Motion 按压效果或 View Model 绑定。历史约束见 [Rive 内存记录](rive-persona-incident.md)。
+
+## 验证边界与来源
+
+运行时 JSON 能恢复当前 `.riv`，但不等于作者的 `.rev` 编辑器工程；导出时省略的编辑信息没有凭空恢复。原作者提供可编辑 `.rev` 的说明见 [资源定制文档](https://elements.surge.studio/docs/customization)，格式差异见 [Rive 备份说明](https://rive.app/docs/editor/exporting/exporting-for-backup)。
+
+原始图形来源为 [Surge Obsidian 动画](https://ejiidnob33g9ap1r.public.blob.vercel-storage.com/obsidian-2.0.riv)。解析时参考了 [rive-rs-cli 的格式读取实现](https://github.com/George-RD/rive-rs-cli/blob/main/src/validator/parser.rs)及其从 Rive 定义生成的类型/属性表；应用不依赖或包含该工具。原图形的作者归属不因解析和局部修改而改变。
+
+对照测试在同一 WebGL2 运行时以固定时间步推进。就绪、思考、待回复、输出和悬停状态要求与“仅应用相同冰水蓝材质的原版”采样画面逐像素一致，并验证主色由灰变蓝、合成到白底后仍保有蓝色，球体中心采样区域的不透明度不低于 90%。悬停另外比较左右指针位置对应的高光重心，要求局部反射随指针移动且移出后完全恢复。工作台测试验证实际坐标到达原生监听器。离线检查完整球体、持续变化、初始离线和反复恢复；通过外围像素计数验证光圈完全消失，悬停不会重新出现，恢复在线后再次可见。另用相同运动轨迹、取消离线光照变化的对照资源，验证快速切换后在线明暗完整恢复。该检查覆盖固定采样时刻，不是所有设备、运行时间和状态序列的穷举验证。

docs/component-design-system.md

@@ -1,96 +0,0 @@
-# 新增业务组件设计规范
-
-本规范覆盖调查任务、运行控制、人工复核、外围样板、日期时间与共享表单组件。地图仍是主工作区，侧栏负责定位当前任务、显示状态、给出下一步操作和按需展开证据。
-
-## 1. 视觉主题
-
-方向为宝石蓝操作、银灰亚克力、少量香槟重点的浅色专业调度台。界面保持高信息密度，使用稳定的标题、状态、操作、证据顺序。沿用既有字体、布局、圆角和 acrylic 材质，以透底、色调和轻微背景色差区分导航、面板、分组与阅读区。
-
-## 2. 色彩角色
-
-采用同色相色阶与低彩度互补色规则。宝石蓝 `#4263C7` 转换为 OKLCH 后约为 `L=0.529317, C=0.160186, h=267.059148°`；中性材质和文字保持该色相，香槟辅助色使用 `(h + 180°) mod 360°`。色阶先计算后转换为 sRGB HEX，均处于 sRGB 色域。透明度不参与色板生成。
-
-| 角色 | L | C | h | HEX |
-|---|---:|---:|---:|---|
-| 宝石蓝主色 | 0.529317 | 0.160186 | 267.06° | `#4263C7` |
-| 银霜材质 | 0.935 | 0.012 | 267.06° | `#E6E9F2` |
-| 冷瓷阅读面 | 0.975 | 0.005 | 267.06° | `#F5F7FA` |
-| 香槟辅助色 | 0.820 | 0.065 | 87.06° | `#D6C294` |
-| 深墨文字 | 0.280 | 0.025 | 267.06° | `#232935` |
-
-完整色板见 [宝石蓝配色](gem-blue-palette.svg)。
-
-- `--surface-navigation`：宝石蓝 8% 与银霜在 OKLab 空间混合的导航色调。浅色混色使用 OKLab，避免低彩度颜色在色相插值时偏色。
-- `--surface-panel`：银霜色调；`--surface-well` 为其半透明次级面。
-- `--surface-subtle`：`L=0.950, C=0.010, h=267.06°`，得到 `#EBEEF5`，供桌面 dock、分组和普通控件使用。
-- `--surface-reading`：冷瓷正文、表单和报告阅读面，保持较高遮蔽度。
-- `--action-selection-soft`：`L=0.920, C=0.035, h=267.06°`，得到 `#DAE5FD`，文字使用深宝石蓝。
-- `--action-blue`：主操作 `#4263C7`；hover 将 L 降低 0.055、C 乘 0.95，得到 `#3653B0`；pressed 将 L 降低 0.105、C 乘 0.90，得到 `#2B469C`。
-- `--surface-border` / `--surface-divider`：保持同色相，分别使用 `(L=0.815, C=0.015)` 和 `(L=0.885, C=0.012)`，得到银灰边界 `#BEC2CD` / `#D5D9E1`。
-- `--action-focus-ring`：深宝石蓝焦点环；`--ink-muted`：`L=0.450, C=0.030, h=267.06°`，得到辅助文字 `#4E5566`。
-- `cyan-700`：外围样板入口及其来源标识。
-- `emerald`：已完成、已通过。
-- `--status-warning-soft`：香槟色 25% 与冷瓷混合的确认、暂停和结果未知提示底色；同互补色相的文字使用 `(L=0.430, C=0.070)`，得到 `#604D1D`；状态标记使用 `(L=0.600, C=0.090)`，得到 `#977D3C`。
-- `rose`：失败、冲突或破坏性操作。
-
-宝石蓝用于工作台操作和选中状态，银灰用于工作台材质层级。Agent 对话区使用独立的低饱和雾蓝灰层次：工作面 `#E8ECF3`、阅读面 `#F8F9FC`、用户消息 `#DDE4F1`，主操作使用岩蓝 `#465F91`。岩蓝与工作台品牌色保持同一视觉语言，同时降低亮度和饱和度，避免输入区显得刺眼。这组颜色按阅读层级和对比度选择，不要求遵循固定的相似色公式，也不扩散到地图和顶部工作台。香槟色只用于确认、警告与 Agent 欢迎标记的小面积点缀，不作为普通面板的整块底色。成功、失败、地图业务图层和数据曲线保留各自语义色。
-
-## 3. 排版规则
-
-沿用 Noto Sans SC。侧栏标题使用 14px，业务区标题使用 13px，正文和表单标签使用 12px，辅助信息使用 11px。编号、修订号、时间和数量使用等宽数字。标签左对齐，数值列右对齐。
-
-## 4. 组件规则
-
-- `WorkbenchSection` 统一业务区标题、说明、状态和操作，不在内部再次堆叠同级标题卡。
-- `WorkbenchNotice` 使用左侧状态线传达信息、警告与错误，避免大面积色块。
-- `WorkbenchEmptyState` 只说明当前为空和下一步，不占用过高空间。
-- 表单控件高度为 40px，按钮使用现有 8px 或 12px 圆角体系。
-- 主操作每个业务区最多一个。其余操作使用 outline 或 ghost。
-
-## 5. 布局原则
-
-每个业务区按“定位、状态、下一步、证据”排列。侧栏内容使用 12px 至 14px 的紧凑间距。复杂原始对象、请求参数、历史和测试资源按需展开。移动端保持单列，不用横向滚动承载业务字段。
-
-地图背景延伸到顶部导航背后，地图控件和分析正文仍预留 56px 导航高度。独立浮层使用完整亚克力材质，阅读面和控件内部的填色不额外叠加模糊；任务堆叠保留完整圆角和每层 7px 的错位。时间轴容器不足 640px 时省略统计摘要，优先保证日期、图例和操作按钮互不重叠。
-
-## 6. 层级与深度
-
-保持既有亚克力半透明材质，在透底、模糊、噪点和边缘高光上调整色调。桌面 Agent dock 使用雾蓝灰实体底板，导航、历史和底部操作区保留同色调的局部亚克力；正文和文字输入区使用冷白实体阅读面，岩蓝只用于主操作、焦点和交互反馈。文字输入与权限、模型、语音和发送操作栏分开承担材质，聚焦边框仅围绕文字输入区。对话内容直接进入消息流，不在顶部重复展示分析摘要。每个功能区只保留一层模糊，历史展开内容与导航共用材质层。
-
-桌面普通空会话使用浅雾蓝灰工作面和冷白文字输入区，居中输入组件距面板两侧至少 12px，最大宽度 600px，文字输入区初始高度 160px、字号 16px；多行输入的高度按可用视口限制，保持操作栏和推荐问题可见。模型根据当前用户与项目的近期任务、告警、分析成果和普通会话生成最多三条问题，在输入组件下方独立显示来源与时间，点击直接发送；首次开始对话时，同一个表单以 280ms 位移和尺寸过渡回到底部，随后使用 48px 的紧凑文字区和 40px 操作控件，减少动态效果偏好下则立即切换。移动端保留紧凑输入布局，生成的问题仍使用独立悬浮胶囊。推荐异步加载，不阻塞输入；打开空会话、切换模型或新建空会话时触发，普通重渲染和宽度变化不重新生成，模型失败时不以固定问题冒充生成结果。
-
-| 材质 | 浅色底图 alpha | 影像底图 alpha |
-|---|---:|---:|
-| 导航 | 0.64 | 0.80 |
-| 浮动业务面板 | 0.56 | 0.72 |
-| 地图控件 | 0.74 | 0.86 |
-| Agent 移动抽屉和历史 | 0.82 | 0.88 |
-| Agent 浮动输入区 | 0.86 | 0.90 |
-| 正文阅读面 | 0.96 | 0.985 |
-
-分组标题及次级数据使用银灰色差，不叠加投影。模糊仍为面板 24px、控件及 Agent 浮层 18px。地图和影像中的底色应能透过外层材质；报告正文保留更高遮蔽度，保证阅读。
-
-## 7. 使用约束
-
-- 必须优先显示当前状态和可执行的下一步。
-- 调查计划由 Agent 动态发布。默认呈现本次选中的路线和当前待办，未选路线及旧修订按需展开；条件、并行和审核状态只读取明确的结构化字段。
-- 必须明确 synthetic、只读、结果未知和未配置状态。
-- 必须保留完整请求号、对象修订和证据来源的可读入口。
-- 不用颜色代替文字状态。
-- 不在一个业务区内放置多个同等醒目的主按钮。
-- 不用大块空卡显示一句空状态。
-- 不引入第二套字体、主题或 CSS 方案。
-
-## 8. 响应式与无障碍
-
-支持 1280px 桌面和 320px、375px 窄屏。所有交互控件保留可见焦点，触控目标至少 40px。弹层受视口高度和宽度限制。hover 仅在支持 hover 的设备启用，按压使用轻微缩放，并尊重 reduced motion。
-
-表单字段使用共享 `.form-field` 规则：聚焦时只改变原有 1px 边框的颜色，不叠加外环或浏览器默认轮廓。组合输入由最外层字段容器承担焦点边界，内部输入保持无边框；无边框的亚克力输入区使用 1px 内描边，保持材质与布局不变。无效字段保留错误色，按钮与选择控件保留单独的键盘焦点提示。全局焦点样式仅作为基础层兜底，不能覆盖组件自身规则。
-
-底图选择卡片的选中态使用 1px 主题边框和勾选标记，不附加常驻外环。键盘聚焦使用共享的 1px 内描边；鼠标选中、聚焦与按压均保持卡片尺寸及半透明表面不变。图层面板、独立底图面板与浮动底图控件使用同一规则。
-
-普通文字与实际背景对比度至少 4.5:1，焦点和必要的非文字状态标记至少 3:1。透明区域按合成背景计算。不支持模糊或降低透明度时保留不透明的银霜、冷瓷层级；强制颜色模式使用系统颜色。主题由现有 Tailwind 与 CSS 变量统一提供，不新增切换入口。
-
-## 9. 交互提示
-
-任务面板先显示任务状态和下一步，再提供计划、目标、运行与证据。运行暂停时突出检查点校验或恢复中的一个主操作。外围面板先显示连接状态、历史回放和待提交来源，测试资源与原始请求回执默认按需展开。

docs/history/agent-chat-ui-implementation-notes.md

@@ -0,0 +1,87 @@
+# Agent 聊天与报告实现记录
+
+本页归档原设计文档中的阶段记录，仅反映各次验证范围，不作为当前样式或验收结论。现行样式见 [样式设计指南](../style-design-guide.md)，交互与报告规则见 [Agent 交互与报告设计](../agent-chat-ui-design.md)。
+
+2026-10-20 本地验证：前端 lint、类型检查、514 项单测和构建通过；23 项聚焦浏览器用例通过，涵盖聊天、历史、流式稳定、表单、图表、展开阅读、报告版本、320/375px、键盘与强制颜色。最终引用来源调整另通过组件测试，并重新运行 5 项聊天及报告工作区浏览器用例。
+
+Agent 类型检查及 16 项相关测试通过；隔离 OpenCode 工具发现验证通过，未调用模型推理。Server 的报告 schema、发布幂等、证据归属、历史读取和报告 API 共 76 项聚焦测试通过；OpenAPI 检查通过，Agent 类型与副本同步，三端组件参数目录一致。
+
+另有原有 API 测试 `test_approved_task_source_uses_server_delegation` 失败：测试期待 `delegated=True`，当前接口返回 False；使用 HEAD 中的原版测试复现相同结果。该问题未混入本轮 UI 修改。
+
+浏览器截图使用明确标注的演练数据。此次没有重启既有 Agent/Server、部署、调用真实模型生成报告或连接真实数据库验收；正式运行前需要同步三端版本并验证实际报告生成与落库。构建仍有大 chunk 提示。参数重算、附件、导出与版本差异比较属于后续范围。
+
+同日后续细化：合并指标摘要区、收起图表范围筛选、对齐数据点读数，并增加正式报告章节导航。当前结果的状态标签与标题并排；当前最终结论去除重复的“调查结论”标题，历史、阶段性判断和证据不足的说明继续显示。
+
+320px 浏览器实测，聊天展开视图的指标区从 310px 降为 118px；趋势图距阅读区顶部从 596px 降为 396px。测量使用同一演练数据，图表仍保留 220px 高度，文本内容与数值未裁剪。检查并更新聊天内嵌、聊天展开、报告内嵌、报告展开共 4 类视图（checked 4 / changed 4 / left 0）。
+
+本次增量验证：lint、类型检查、515 项单测、18 项聚焦浏览器用例及 `git diff --check` 通过。浏览器覆盖 320/375px 与桌面、范围筛选和重置、章节键盘跳转与吸顶、滚动章节提示、草稿保留、版本引用、原有审批内容和强制颜色。改动限于前端展示与导航，没有新增依赖或更改接口；本次未重跑构建和 Agent/Server 测试。
+
+2026-10-21 Resizable 分栏验证：新增 `react-resizable-panels@4.14.7`，移除手写 Agent 拖拽 Hook。`pnpm lint`、`pnpm typecheck`、`pnpm test`（100 个文件、515 项测试）、`pnpm build` 和 `git diff --check` 通过；构建仍有原有大 chunk 提示。25 项聚焦浏览器用例通过，覆盖 Agent 与地图/报告两级拖拽、键盘方向键及 Home / End、最小/最大宽度、折叠恢复、320/375px 与桌面往返、报告比例记忆、表单草稿及地图 canvas 连续绘制。运行命令：`pnpm exec playwright test tests/browser/agent-panel-resize.e2e.ts tests/browser/agent-answer-ui.e2e.ts tests/browser/agent-report-workspace.e2e.ts tests/browser/workspace-main-frame.e2e.ts tests/browser/workbench-resizable.e2e.ts --workers=1`。
+
+键盘调宽回调可能早于 DOM 宽度更新，Agent 的尺寸记忆使用回调中的新比例计算，避免记录上一帧宽度；回归用例已先复现失败再验证通过。两处分栏回调均已核对，内层直接保存布局比例，不读取旧 DOM 尺寸。浏览器预览采用演练数据，本轮仅改动前端，未提交、部署或进行真实业务验收。
+
+2026-10-21 首次提问与 Motion 增量验证：lint、类型检查、519 项单测（100 个文件）及 `git diff --check` 通过。10 项相关浏览器用例分批通过，覆盖居中提问、400/640px 调宽、首次发送与新建对话、表单实例保留、Motion 逐帧位移、减少动态效果、320/375px 与短屏输入、悬浮入口及历史富内容恢复。并行任务期间发生过整例超时，动画用例随后单独复核通过；截图辅助逻辑已修复通知退出导致的定位漂移。验证使用演练数据，未新增依赖，本轮未重跑构建或后台测试，未提交或部署。
+
+2026-10-21 悬浮入口白色材质验证：lint、类型检查、519 项单测及 2 项聚焦浏览器用例通过，覆盖桌面折叠恢复、键盘展开、减少透明度降级和 375px 窄屏。检查了实际渲染截图；本轮只调整入口材质，未新增依赖。
+
+2026-10-21 悬浮入口精简验证：入口改为 56 × 56px 圆形按钮，移除附加状态文案、状态点、箭头和详情提示卡片。lint、类型检查、519 项单测及 `git diff --check` 通过。桌面 1024/1440px 尺寸、键盘展开、减少透明度和 375px 手机共 2 项浏览器用例分批通过；桌面首次验证在展开后的布局断言超时，未改业务代码单独复测通过。截图采用浏览器演练环境。
+
+2026-10-21 水纹球与交互验证：形象改为本地 CSS 与 Motion 绘制的水纹球，加入指针跟随、按压形变和触点水波；离线保留完整球体与操作反馈。lint、类型检查、519 项单测及 9 项聚焦浏览器用例通过，覆盖状态切换、离线可见与展开、鼠标移出复位、手机触摸及取消、减少动态效果、强制颜色、键盘、桌面尺寸和 320/375px。此前 3 项首次加载等待超时，已将连接状态首次就绪的等待上限调整为 30 秒，交互断言保持原有超时。检查了实际工作台与交互预览截图，使用演练数据，未新增依赖、提交或部署。
+
+同日高光跟随修正：固定球体位置与边缘反光，改为在固定高光层内移动渐变中心，并缩小、柔化亮斑。720px 预览视口内，48px 球体右下角悬停时，高光层相对球面的偏移从横向 5.34px、纵向 5.34px 降为 0；32/40/48px 的左上、右下悬停均保持贴合。悬浮入口、标题栏、手机入口共检查 3 处、更新 3 处、遗留 0 处（checked 3 / changed 3 / left 0）。lint、类型检查、519 项单测、6 项水纹球浏览器用例和 `git diff --check` 通过；触摸取消、按压水波、离线可见与互动、键盘及减少动态效果保持有效。
+
+同日球缘涟漪补充：实际渲染并对照 Obsidian 原资源的就绪、待回复、思考、输出和悬停状态，增加三层错峰向外传播的球缘水波，触碰改为三道渐弱涟漪；移除球内固定同心纹理，保留柔和流光与已修正的局部高光。检查 32/40/48px 及离线预览，三处共享入口同步更新。lint、类型检查、519 项单测、6 项浏览器用例和 `git diff --check` 通过；浏览器逐帧确认波纹半径实际增大，并检查离线与减少动态效果停止循环、鼠标及手机操作。仅变更前端形象与设计说明，未引入远程资源依赖或新增包。
+
+2026-10-21 Motion 曲线细化：三层球缘改为闭合贝塞尔带状轮廓，内部改为两道持续形变的宽幅明暗光带；状态切换保留相位，悬停只扰动靠近指针的球缘，保留局部高光和三道按压水波。增加几何单测验证循环连续、曲线边界、状态差异及局部扰动。lint、类型检查、526 项单测（101 个文件）及 6 项水纹球浏览器用例通过，覆盖实际路径变化、视口外暂停恢复、处理状态、离线可见、鼠标与触摸取消、减少动态效果、强制颜色和键盘展开。原版 / 上一版 / 新版动态对照页已检查五种状态和 32/40/48px；高光层与球面最大偏差小于 0.03px，多个实例的 SVG ID 无重复，375px 预览无横向溢出。对照页为本地预览产物；工作台仅使用本地 Motion 实现，没有新增包或更改业务状态映射。`git diff --check` 通过，本轮未提交或部署。
+
+2026-10-21 Obsidian 原版恢复：根据源码和实际资源核对，改回 Rive WebGL2 原动画，保留原版羽化、反射、水纹和 hover 状态。删除自绘 Motion 几何实现及对应几何单测；Motion 用于外层按压。离线、减少动态效果及加载失败显示从原动画导出的静态帧。三个入口共检查 3 处、更新 3 处、遗留 0 处（checked 3 / changed 3 / left 0）。lint、类型检查、523 项单测（101 个文件）、构建及 7 项聚焦浏览器用例通过，覆盖真实原版画面变化、单次资源下载、移出视口释放、状态切换、鼠标与触摸取消、离线、资源失败、键盘和强制颜色。构建保留已有的大 chunk 提示。本轮未新增包、提交或部署。
+
+原版 / 接入版动态对照已检查五种状态和 32/40/48px，375px 预览无横向溢出；在线保留原版动画，离线切为原版静态帧。独立对照预览的 35 秒浏览器渲染进程 RSS 从约 193.3 MiB 回落至 177.2 MiB，未观察到持续增长；这是单次短时预览观察，不代表长时间运行或真实业务负载验收。`git diff --check` 通过。
+
+2026-10-21 取消球体按压反馈：`AgentPersona` 移除 Motion，取消缩放、回弹、变暗及触摸触发 hover，保留原版鼠标悬停、水纹和状态动画。减少动态效果改用系统媒体查询监听；离线仍显示原版静态帧。lint、类型检查、523 项单测、7 项球体浏览器用例及 `git diff --check` 通过，覆盖桌面点击、手机触摸、离线、键盘和强制颜色。另在组件预览中验证减少动态效果的实时切换，以及按下前后静态图片一致；未新增依赖或重跑构建。
+
+2026-10-21 首次加载衔接与尺寸修正：逐帧复现静态帧到 Rive 的透明度从 0 直接变为 1，球体位置和尺寸保持不变，确认跳动来自画面硬切。改为 180ms CSS 渐变，结束后隐藏占位；新浏览器用例在修改前失败、修改后通过。悬浮画布从 48px 放大至 56px，桌面标题栏从 40px 放大至 48px，手机入口从 32px 放大至 40px，三个入口均复核。lint、类型检查、523 项单测及 8 项聚焦浏览器用例分批通过，检查了 320/375px 实际画面、加载衔接、原版动画、按压无反馈、离线、触摸和键盘。未新增依赖、提交或部署。
+
+## 2026-10-21 Rive 资源内离线水纹
+
+解析原版 775 个运行时对象，JSON 重新编码与原文件逐字节一致。保留原图形和在线动画，新增三段离线循环，并修正 asleep / wake 的透明度与缩放关键帧；同源资源为 `public/agent/obsidian-water-v1.riv`。实现与再生成说明见 [Agent 动画资源](../agent-persona-resource.md)。
+
+验证通过：生成一致性检查、lint、类型检查、547 项单测、构建、`git diff --check`。10 项相关浏览器用例分批通过，包含真实 WebGL2 在线状态采样逐像素对照、原版离线消失与修改版离线持续运动、初始离线、反复恢复、工作台单实例、加载衔接、按压无反馈、资源失败、减少动态效果、键盘及 320/375px。首次运行有 1 项动画就绪等待超时；未修改运行代码，带 trace 复测通过，首次超时根因未确认。
+
+独立预览检查 5 种状态及 40/48/56px，离线仍为实时 canvas；30 秒渲染进程 RSS 约 209 MiB 至 176 MiB，未见持续增长。这是本地短时观察，不替代长时间运行验证。构建保留原有大 chunk 提示，本轮未新增依赖、提交或部署。
+
+## 2026-10-21 静水待机与客户端资源缓存
+
+在资源内为六个柔光/反射节点增加离线强度循环，保留原版整体轮廓与在线画面，在线/离线混合时长调整为 600ms。可编辑参数独立保存为 `design/agent/obsidian-offline.json`；生成脚本增加原始 `.riv` 还原命令，实测输出 SHA-256 与原版一致。浏览器对照覆盖在线采样逐像素一致、离线持续变化、正常恢复与快速反复切换后的原版光照恢复。
+
+`.riv` 增加页面内存与 Cache Storage 两级缓存，使用生成脚本同步输出的内容 SHA-256 作为版本。下载和缓存读取验证内容，损坏缓存重新获取，写入新版本后仅清理该动画的旧条目；缓存不可用、权限或配额失败不阻止网络资源播放。真实工作台刷新后阻断动画文件的网络路径，仍能加载并持续播放，下载次数保持为一次。缓存仅覆盖动画资源，不代表应用和 Rive WASM 的完整离线支持。
+
+最终验证通过：lint、类型检查、554 项单测、11 项聚焦浏览器用例、构建、资源与缓存清单再生成一致性、生产资源与打包版本核对、文档链接及 `git diff --check`。实际预览检查 5 种状态及 40/48/56px，浏览器用例覆盖桌面和 320/375px。构建仍有已有大 chunk 提示；未新增依赖、提交或部署。
+
+## 2026-10-21 冰水蓝与光圈辨识度
+
+初版 A「水务蓝」在实际动画中出现灰蓝混色、底色过厚的观感问题。将三个新配色放入原生 Rive 动画，在白底、五种状态与 40/48/56px 下对比后，采用用户选定的 02「冰水蓝」：水体 `#299FDF`、暗部 `#1482BC`、白色高光，底色不透明度为 12%/32%。根据工作台截图反馈，外围水纹进一步从 `#B0E3FF` 加深为 `#4C9ECC`，提升浅色地图上的轮廓辨识度；光圈粗细、渐变 alpha、羽化与运动曲线保持原定义。
+
+离线仍关闭三层外围光圈，保留内部缓慢水纹。在线、离线兜底 PNG 从实际资源重新渲染，内容版本与客户端缓存清单同步更新；仅加深光圈前后，离线 PNG 逐字节一致。悬浮入口、标题栏和手机入口共享资源，检查 3 处、更新 3 处、遗留 0 处（checked 3 / changed 3 / left 0）。
+
+验证通过：lint、类型检查、12 项相关单测及 12 项聚焦浏览器用例分批通过。初次资源对照的深蓝显色阈值不适用于新选定的浅色方案，已调整白底合成后的蓝色检查，并保留原版几何及在线动画的逐像素对照。光圈加深后，重新通过 7 项聚焦浏览器用例，覆盖原版运动、离线无光圈及悬停、恢复在线、缓存刷新、工作台入口和 320/375px。最终构建、资源再生成一致性、生产副本与缓存版本、文档链接及 `git diff --check` 通过；构建保留已有大 chunk 提示。此次未新增依赖、提交或部署。
+
+## 2026-10-21 64px 入口、主体遮蔽与标题区重排
+
+默认 persona、悬浮入口和面板标题区形象统一为 64px，手机地图入口保留 40px。悬浮入口通过同一层 12px 内边距定位，替换原来左侧 12px、导航下方 20px 的独立偏移；1440px 和 1024px 视口实测入口为 64 × 64px，距左侧和顶部导航下沿均为 12px。三个组件调用位置均检查，修改两处呈现尺寸，遗留零处（checked 3 / changed 2 / left 0）。
+
+根据地图道路穿透球体的截图，为球面底色增加独立 `bodyColor`，设为浅冰蓝 `#DCEFFA`，待机/活动不透明度提高至 94%/98%。反射层继续使用选定的冰水蓝配色，外围光圈颜色及离线关闭规则保持。真实 Rive 前后对比检查了带线条背景，中心区域的运行时 alpha 采样不低于 90%；静态帧与缓存版本重新生成，原版几何与在线运动对照仍通过。
+
+标题区身份行重排为 64px persona、上下排列的名称与连接状态，以及右侧三个 40px 操作按钮。上下文行继续提供会话标题与项目切换；两个区域共用白色背景，仅在底部保留分隔线。400px、640px 桌面面板和 320px 手机截图已检查，名称与操作按钮无重叠。历史展开、重命名取消、键盘焦点恢复、新建、折叠和手机关闭入口保留。
+
+最终验证通过：lint、类型检查、556 项单测（102 个文件）、构建和 17 项相关浏览器用例分批通过。浏览器覆盖资源及主体遮蔽、离线、缓存、加载衔接、布局与标题区、320/375px、短屏输入，以及首次发送与新建会话的居中恢复。生产资源、PNG 副本、缓存版本清单、文档链接和 `git diff --check` 通过。构建保留已有大 chunk 提示；未新增依赖、提交或部署。
+
+## 2026-10-22 Persona 设计归档与悬停坐标修复
+
+当前视觉规格保存为 [Persona 设计](../agent-persona-design.md)，记录冰水蓝材质、主体遮蔽、64px 默认尺寸、12px 等距定位、标题区、状态动画、交互、降级与缓存边界，并从 README、交互设计和资源说明关联。
+
+悬停中央大片变白的原因是共享 `Persona` 禁用了 Rive 指针监听，仅手动设置 `hover`，导致原生反射的指针目标始终位于中心。恢复原生监听并通过 Pointer Events 转交主指针的进入、移动、离开与取消；Rive 完成坐标转换和原生约束更新。触摸、按压和触摸生成的鼠标事件不进入动画通路。撤销此前的 80% 光圈缩放，应用 `.riv` 与此次调整前逐字节一致。
+
+三个调用位置均复核（checked 3 / changed 3 via shared component / left 0）：桌面悬浮入口、面板标题区、手机地图入口。新增工作台回归在修复前收到空坐标并失败，修复后通过，覆盖悬浮入口和标题区的左右移动。资源级对照验证高光重心跟随左右指针移动，且画面与相同材质的原版逐像素一致；鼠标移出后完全恢复。实际组件的 64px 与 160px 放大画面已检查，手机 320/375px、离线、键盘、减少动态效果、失败降级和无按压反馈由相关浏览器用例覆盖。
+
+lint、构建内类型检查、558 项单测（103 个文件）及构建通过；14 项相关浏览器用例分批通过。首次综合运行中，加载衔接的 5 秒前置等待和多次挂载缓存检查的整例 30 秒时限超时，未改代码或断言，单独复测两项均通过。资源还原与再生成校验、本文涉及的文档链接和 `git diff --check` 通过。构建仍有已有大 chunk 提示；未新增依赖、提交或部署。

docs/non-map-ui.md

@@ -104,7 +104,7 @@
 
 ## 新增业务组件统一设计
 
-2026-09-18 对调查任务与外围样板的新组件完成统一重构。完整规则见 `docs/component-design-system.md`，视觉方向是浅色专业调度台，保留地图为主工作区，并将侧栏内容稳定为“定位、状态、下一步、证据”的阅读顺序。
+2026-09-18 对调查任务与外围样板的新组件完成统一重构。现行规则见 [样式设计指南](style-design-guide.md)，视觉方向是浅色专业调度台，保留地图为主工作区，并将侧栏内容稳定为“定位、状态、下一步、证据”的阅读顺序。
 
 - 新增 `WorkbenchSection`、`WorkbenchNotice` 和 `WorkbenchEmptyState`，统一标题、状态、提示和空态，减少同级彩色卡片与大面积空白。
 - 生命周期确认、定时计划、目标编译、运行控制、运行对比、人工复核和 Evidence 导入统一状态语言与操作层级。

docs/project-switching.md

@@ -0,0 +1,54 @@
+# 工作台项目切换
+
+2026-10-21：新增用户菜单内的项目切换，首批核对 `tjwater_v2` 与 `fengyang_v2`。
+
+## 启动与加载状态
+
+身份认证和授权项目加载共用启动界面：左对齐平台标识与标题，中性浅色表面和宝石蓝状态标识。认证阶段显示“检查登录状态”；项目阶段依次显示“读取授权项目”和“准备项目环境”。项目列表返回后才将第一步标为完成，并显示实际选中的授权项目名称；项目配置与访问上下文返回前不挂载工作台，不用计时器或百分比模拟进度。
+
+加载中提供图形反馈和文字说明，系统开启减少动态效果时停止旋转。失败后移除加载状态，展示错误原因和单一重试操作；项目重试回到读取列表阶段，认证重试重新连接。桌面与手机使用同一组件，长项目名和错误信息自然换行。外观与组件选择遵循 [样式设计指南](style-design-guide.md)。
+
+## 用户入口与选择规则
+
+打开右上角用户菜单，点击“切换项目”进入弹窗。弹窗恢复中性乳白亚克力表面、小型平台标识、左对齐标题、当前项目说明和通栏“进入项目”按钮的布局。弹窗与下拉浮层使用 82% 中性白色亚克力底色，沿用模糊、噪点和边缘高光；遮罩保留轻微压暗与 3px 背景模糊。降低透明度或不支持背景模糊时回退为不透明白色。选择框与禁用按钮使用中性白色表面和低对比灰色边框；主按钮和选中态恢复工作台宝石蓝。
+
+共享 Select 下拉列表显示项目名称与当前使用标记，选择区补充可用状态，后端返回角色时显示中文角色。首次打开和重新打开弹窗时，焦点显式落在“项目环境”选择框，不自动展开列表；Tab 与 Shift+Tab 保留正常焦点顺序。点击主按钮后才提交切换；选择相同项目时主按钮禁用。关闭按钮或 Escape 关闭弹窗并恢复用户菜单按钮焦点。下拉列表只列出后端授权列表中的活动项目；弹窗及下拉浮层覆盖地图工具栏，适配 1440、375 和 320px 视口。
+
+动效使用 `motion/react`：遮罩淡入淡出，弹窗以 8px 位移进入并保留退出动画，项目列表以 4px 位移展开；键盘操作和系统“减少动态效果”设置下即时呈现。列表关闭后直接恢复选择框焦点并保留蓝色焦点边框；弹窗容器不显示浏览器默认 outline，避免选择项变化时焦点临时回落导致黑边。下拉外层只负责裁切，实际滚动统一由 Radix Viewport 管理，避免 4px 入场位移触发外层滚动条；长列表仍支持滚动与键盘定位。
+
+浏览器保存最近一次成功选择的项目 ID。刷新后先重新加载授权列表，只有仍在列表中的 ID 才会恢复；否则使用部署默认工作空间对应的授权项目，再退到列表中的首个项目。项目查询失败显示重试入口，不凭本地存储获得权限。
+
+切换前查询目标项目元数据和访问上下文，两者均通过项目 ID 核对后才提交选择。失败时保留原工作台、弹窗和目标选择，并显示错误提示；请求期间禁用选择与关闭操作。切换只改变浏览器正在查看的项目，不取消服务端工况任务。
+
+## 数据与生命周期
+
+`project-workbench.tsx` 持有唯一选中项目。它将 `WorkbenchRequestContext` 传入工作台，其中包含项目元数据、认证令牌提供器以及已取得的展示信息。现有 API 参数名 `getAccessToken` 为兼容保留，类型 `WorkbenchAccess` 同时接受旧认证提供器和显式项目上下文；主应用始终传显式上下文。
+
+地图瓦片、WFS 定位与可用图层探测读取当前项目的 `gs_workspace`。SCADA、实时流量、运行态、事件流、任务、成果、GIS 属性与 Agent 项目会话读取同一个项目 ID。业务请求继续由后端通过 Bearer 与 `X-Project-Id` 校验权限。
+
+项目 ID 作为工作台 SWR 边界的 React key；切换时新建业务缓存并重新挂载工作台，清理地图选择、报告、绘图和旧业务订阅，当前 Agent 视图进入新项目的空会话。登录级资源位于该边界之外，保留按归属隔离的历史、推荐、项目列表缓存和后台 Agent 会话；原会话生成、草稿及阅读位置继续由其会话实例持有。实现依据 [React 状态重置](https://react.dev/learn/preserving-and-resetting-state) 与 [SWR 缓存提供器](https://swr.vercel.app/docs/advanced/cache)。地图销毁后，绘图及要素交互不再访问旧样式；异步设施与 SCADA 图片注册受地图生命周期 AbortSignal 约束。
+
+## 凤阳的数据边界
+
+凤阳使用已有的 `fengyang_v2` 工作空间及元数据地图范围。固定奉贤演示工况、场景与空间覆盖不会在凤阳兜底显示。奉贤原始 GIS 图层不复制，图层入口根据当前工作空间中的实际数据探测。
+
+地址定位支持文字搜索及地图取点反编码，两者复用当前项目的配置与服务端 Key。取点结果保留点击坐标，关闭工具或切换项目取消未完成查询。地名搜索读取 Metadata DB 的 `projects.map_config.place_search`，按当前项目的 `enabled`、`provider`、`admin_code` 和 `region` 启用查询并显示区域文案。奉贤、凤阳和其他项目使用同一实现；未配置、关闭或配置无效时显示“当前项目暂未配置地名搜索”。区域由后端从授权项目读取，浏览器不能在搜索请求中覆盖行政区。外围样板服务仍有独立项目配置；本次复制其空表结构，不复制奉贤工单，也不扩大外部服务的访问范围。
+
+## 验证
+
+```bash
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm build
+pnpm test:browser tests/browser/project-switching.e2e.ts tests/browser/project-presentation-backend.e2e.ts --workers=2 --reporter=line
+```
+
+浏览器覆盖用户菜单切换、地图工作空间、业务与 Agent 请求项目、元数据视角、刷新恢复、切回原项目及目标访问失败；同时检查切换期间无页面异常。浏览器接口使用隔离测试数据，不代表生产身份登录验收。
+
+数据库补齐方法与备份记录见 Server 仓库的 `docs/workbench-database-rollout.md`。
+
+
+## 项目列表缓存
+
+授权项目列表按当前登录的凭据提供器隔离，内存缓存 5 分钟，分页结果完整合并后缓存；并发读取复用同一请求，单个消费者退出只取消自身等待。窗口直接展示已加载项目，有效期内反复打开不会重新查询。目标项目进入操作继续核验其元数据及访问上下文，复用这次已验证的展示信息，避免工作台挂载后再次读取相同上下文。缓存不替代业务接口授权，退出登录清理本次登录缓存。

docs/rive-persona-incident.md

@@ -79,3 +79,13 @@ pnpm build
 - 不要移除 Strict Mode 延迟初始化，除非重新验证开发和生产生命周期。
 - 更新 Rive 版本时，至少验证单次 `.riv` 请求、状态机切换、页面切换后的实例清理和
   30 秒以上的浏览器进程内存趋势。
+
+## 2026-10-21 原版恢复后的现状
+
+Agent 入口使用基于原版 Obsidian 定制的冰水蓝资源。继续保留 Strict Mode 延迟初始化、按可见性挂载和禁止 View Model 绑定；配色直接写入资源，不应用旧版的 brightness / contrast 滤镜。`persona-resource.ts` 在页面内存与浏览器 Cache Storage 中缓存动画字节，按内容版本更新，不共享 Rive 实例或 View Model。
+
+业务离线由本地 `obsidian-water-v1.riv` 的 `asleep` 状态播放内部缓慢水纹并关闭外围光圈，在线/离线切换保留同一实例。减少动态效果、加载和失败时显示从当前资源渲染的 `obsidian-water-idle.png` 或无光圈的 `obsidian-water-offline.png`。隐藏和减少动态效果会卸载实例，不通过 CSS 同时隐藏多个仍运行的 Persona。资源改造见 [Agent 动画资源说明](agent-persona-resource.md)。`hover` 输入由外层交互控制，Rive 自带的 DOM 监听关闭，避免和原生入口按钮及触摸操作重复响应。
+
+回归验证已覆盖原始字节缓存、失败后的重试、无 View Model 绑定、原生状态及 hover 切换、真实 canvas 动画和桌面/手机单实例。
+
+独立原版 / 接入版预览进行了 35 秒浏览器渲染进程 RSS 观察：约 193.3 MiB 至 177.2 MiB，未观察到持续增长。该结果仅覆盖本地短时对照预览；本轮没有重新引入 View Model 绑定，也未更新 Rive 版本。

docs/style-design-guide.md

@@ -0,0 +1,169 @@
+# 样式设计指南
+
+供水前端统一以本地 shadcn/ui 为组件基础，使用 Tailwind CSS、共享变体和语义变量。Agent 相关弹窗、面板与菜单保持 shadcn/ui 设计；地图控件与其他工作台浮层使用本文规定的 Acrylic 视觉。适用于工作台、地图控件、Agent、报告、表单和弹层。
+
+本文是唯一的样式规范。业务交互见 [Agent 交互与报告设计](agent-chat-ui-design.md)，状态含义见 [状态语言](status-language.md)。本文规定统一目标；历史局部配色和样式覆盖需在后续组件修改中逐步对齐，文档合并不代表运行样式已全部迁移。
+
+## 1. 组件基础
+
+- 优先复用 [src/shared/ui](../src/shared/ui/) 的本地组件；缺少能力时，按需引入与现有 Radix 技术栈匹配的 shadcn/ui 源码，再做样式适配。
+- shadcn/ui 提供组件结构与组合方式，Radix 提供相应的基础交互。定制外观时保留语义、键盘操作、焦点管理、禁用和加载行为。
+- 业务模块组合共享组件，负责数据、权限和动作；共享组件保持通用。AI Elements 用于聊天展示组合，与 Agent 的 shadcn/ui 组件使用同一套主题变量。
+- 不批量覆盖已有组件，不引入第二套 UI 或样式体系。使用 CLI 前先核对 `components.json`；配置继续指向 Vite、TypeScript、Tailwind 4、`@/shared/ui` 和 `@/shared/ui/cn`，关闭 React Server Components。
+- 界面图标统一从 `lucide-react` 按名称引入，使用其默认 2px 描边，不复制图标 SVG 路径或用字符替代操作图标。常规控件图标为 16px，紧凑说明可用 12px 至 14px；图标尺寸与按钮命中区域分别设置。图标按钮提供中文可访问名称，装饰性图标使用 `aria-hidden`。
+- 界面动画统一使用 Motion，React 动画组件与 Hook 从 `motion/react` 引入，覆盖入场、退出、位置与布局变化及交互过渡。尊重 `prefers-reduced-motion`，减少动态效果时关闭非必要动画；连续拖拽调宽不附加布局动画。
+- 保留本地 shadcn/ui 组件自带的基础动效，避免重复叠加。`AgentPersona` 等已有 Rive 专用资源动画继续按其功能文档维护，Motion 不替代资源内部的状态机与动画。
+
+### Agent 弹窗与面板
+
+Agent 相关界面保持项目本地 shadcn/ui 组件的设计，包括背景、边框、圆角、阴影、排版、间距及交互状态。该规则覆盖主对话面板、手机 Agent 面板、历史对话、主题新建与管理、模型菜单、权限与问题确认、Agent 回答的展开阅读面板，以及这些界面的子弹窗和提示。
+
+| 场景 | 组件与组合 |
+|---|---|
+| 历史、主题表单、独立详情与确认 | `Dialog`、`DialogTitle`、`DialogDescription`，组合 `Input`、`Button` 和列表 |
+| 对话、审批、问答与展开阅读面板 | 本地 shadcn/ui 面板布局，按需组合 `Card`、`Separator`、`Tabs`、`ResizablePanelGroup` 与 AI Elements |
+| 模型、主题与会话操作菜单 | `DropdownMenu` 及其菜单项、分组和分隔线 |
+| 辅助说明与状态 | `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` 的遮罩、边框、阴影与交互样式。
+- Agent 表面不套用 `acrylic-panel`、`acrylic-panel-white`、`acrylic-control`、`glass-transient` 等地图材质类，也不以 `surface-dock`、`surface-reading` 等材质类替换 shadcn/ui 面板背景。不叠加毛玻璃、噪点、渐变高光、发光边缘或额外阴影。
+- 业务适配可调整宽高、最大高度、滚动、分栏、层级和响应式布局；手机全屏历史与抽屉布局仍沿用相同的组件设计。保留组件的标题、说明、关闭、焦点、键盘和禁用行为，避免用全局 CSS 重绘 Agent 内的按钮、输入、菜单或弹窗。
+- 危险操作使用明确的确认步骤和 `destructive` 按钮变体；失败保留输入与原内容。审批、提问与历史操作的业务规则由对应功能文档维护。
+- Agent 打开的既有地图或业务工具仍遵循其所属模块规范。`AgentPersona` 动画资源按专用设计文档维护，周边面板与控件遵循本节。
+
+## 2. Tailwind 定制方式
+
+样式统一进入 [src/styles.css](../src/styles.css)。Tailwind 工具类负责布局、间距、尺寸、排版、响应式及交互状态；共享变量负责颜色和材质参数，共享变体负责重复的组件外观。
+
+1. 先选组件，再选语义表面，最后调整布局与状态。常用差异通过组件的 `variant`、`size` 表达；局部差异通过 `className` 与 [cn](../src/shared/ui/cn.ts) 合并。
+2. 使用 `bg-background`、`bg-card`、`bg-popover`、`text-foreground`、`border-border` 和 `ring-ring` 等语义工具类。`@theme inline` 将它们映射到项目变量；背景与前景成对维护。
+3. 地图与工作台 Acrylic 的混合层、噪点和回退集中封装为材质类，组件内不重复拼装颜色、模糊和阴影配方，也不把整个控件设置为半透明而降低文字对比度。
+4. 需要允许工具类覆盖的复合样式放入 `@layer components`；需要支持 Tailwind 变体的自定义工具使用 `@utility`。修改现有未分层规则前，先核对层叠关系及回退，不直接搬移整段样式。
+5. 避免同一属性的冲突类；`cn` 处理已知 Tailwind 类的合并，不负责解决任意 CSS 的层叠。自定义材质类不应依赖 `className` 的书写先后来决定优先级，也不靠持续增加选择器权重或 `!important` 定制外观。
+6. 显式颜色仅用于主题定义、图表与地图 API、资源固有颜色和必要的动态值；业务 JSX 优先引用语义变量。
+
+```tsx
+import { Button } from "@/shared/ui/button";
+import { Card, CardContent, CardHeader, CardTitle } from "@/shared/ui/card";
+
+// 独立地图浮层；放入已有 Acrylic 外壳时改用内部内容表面。
+<Card className="acrylic-panel w-full max-w-sm">
+  <CardHeader className="p-3">
+    <CardTitle className="text-sm">分析结果</CardTitle>
+  </CardHeader>
+  <CardContent className="surface-reading space-y-3 p-3">
+    <p className="text-sm text-foreground">展示已有结论与证据。</p>
+    <Button variant="outline" size="sm">查看依据</Button>
+  </CardContent>
+</Card>
+```
+
+## 3. 颜色与状态
+
+地图与工作台 Acrylic 界面的视觉方向为宝石蓝操作、银灰外壳、冷瓷阅读面和少量香槟提示。完整色阶见 [宝石蓝配色](gem-blue-palette.svg)。下表为其材质基线，实际使用通过变量引用；Agent 弹窗与面板沿用已配置的 shadcn/ui 主题变量，不从下表另建局部色板。
+
+| 角色 | 语义变量 | 基线 |
+|---|---|---|
+| 主操作 | `--action-blue` | `#4263C7` |
+| 主操作 hover / 按压 | `--action-blue-hover` / `--action-blue-pressed` | `#3653B0` / `#2B469C` |
+| 外壳色调 | `--surface-panel` | 银霜 `#E6E9F2` |
+| 常驻底板、普通控件 | `--surface-dock` / `--surface-subtle` | `#EBEEF5` |
+| 正文与表单 | `--surface-reading` | 冷瓷 `#F5F7FA`，按阅读场景保持高遮蔽度 |
+| 选中背景 | `--action-selection-soft` | `#DAE5FD` |
+| 正文 / 辅助文字 | `--ink` / `--ink-muted` | `#232935` / `#4E5566` |
+| 边框 / 分隔线 | `--surface-border` / `--surface-divider` | `#BEC2CD` / `#D5D9E1` |
+| 警告与确认提示 | `--status-warning-*` | 香槟色系，小面积使用 |
+
+状态使用 `status-tone-neutral/info/success/warning/danger` 与共享 `StatusBadge`、`StatusIcon`、`StatusDot`，同时提供文字或图标。业务状态、交互选中和数据系列颜色各自独立；`material-tone-agent` 只标记 Agent 解释或建议，原始监测值和人工资料继续使用普通阅读面。
+
+Agent 使用 shadcn/ui 的实体表面和现有主题色，不将这种外观列为待迁移到 Acrylic 的差异。已有 Agent 专用配色、材质和控件 CSS 覆盖应在对应组件调整时收敛到本地 shadcn/ui 样式；是否完成以运行界面验收为准。
+
+## 4. 材质与层级
+
+本节的 Acrylic 材质规则适用于地图与其他工作台界面；Agent 弹窗与面板按前述 shadcn/ui 规则执行。Acrylic 通过半透明色调、背景模糊、混合层和细噪点建立层级，边缘高光与阴影保持克制。常驻、参与布局的业务区域使用实体底板；Mica 仅作为这一底板角色的设计参考，Web CSS 实体色不等同于原生系统 Mica。
+
+| 表面类 | 用途 |
+|---|---|
+| `acrylic-navigation` | 透出地图背景的顶部导航 |
+| `acrylic-panel` | 图层、图例、工况、要素详情和菜单等独立地图浮层 |
+| `acrylic-panel-white` | 与 `acrylic-panel` 配合的白色变体，如项目切换对话框 |
+| `acrylic-control` | 工具栏、缩放、比例尺和底图入口 |
+| `glass-transient` | 活动任务浮条和地图临时通知 |
+| `surface-dock` | 非 Agent 的常驻业务面板、分析成果及业务报告外壳与标题区 |
+| `surface-control` | 内部按钮、筛选器和紧凑操作区 |
+| `surface-well` | 低密度分组、空白支撑区和内部凹槽 |
+| `surface-reading` | 消息、报告、表格、属性、证据和表单 |
+
+一个浮动区域只由最外层承担背景模糊，内部使用内容表面。同一区域的工具面板相互替换，避免叠加 Acrylic。常驻底板可以承载独立临时浮层，标题栏按背景关系选择材质。
+
+地图纹理可影响外壳空白区，不能穿透密集文字。透明度、模糊和阴影由全局变量及 `data-basemap-tone` 适配；具体参数以 CSS 为准，不在多份文档重复维护固定数值。入场动画与定位容器需保证背景采样正常，结束后不保留不必要的合成提示。
+
+减少透明度偏好或不支持 `backdrop-filter` 时，切换高遮蔽度背景并关闭模糊；强制颜色模式使用系统色，关闭纹理与阴影。项目已有浅色主题是当前基线，暗色类名不代表已完成暗色验收。
+
+地图组件继续复用 [map-control-styles.ts](../src/features/map/core/components/map-control-styles.ts)：
+
+| 共享常量 | 材质类 |
+|---|---|
+| `MAP_CONTROL_SURFACE_CLASS_NAME` | `acrylic-control border` |
+| `MAP_TOOL_PANEL_SURFACE_CLASS_NAME` | `acrylic-panel border` |
+| `MAP_FOCUS_SURFACE_CLASS_NAME` | `acrylic-panel border` |
+| `MAP_READABLE_SURFACE_CLASS_NAME` | `surface-well border` |
+| `MAP_READABLE_SURFACE_STRONG_CLASS_NAME` | `surface-control border` |
+
+## 5. 排版、密度与布局
+
+沿用 Noto Sans SC，中文正文自然换行，不额外拉开字距。编号、时间和数值使用等宽数字，标签左对齐，数值列右对齐。
+
+| 场景 | 排版约定 |
+|---|---|
+| 侧栏标题、业务分组标题 | 分别为 14px、13px |
+| 紧凑正文与字段标签、辅助信息 | 分别为 12px、11px |
+| Agent 消息正文 | 14px，行高 24px |
+| 欢迎提示与展开报告标题 | 20px，行高 28px |
+| 指标值、单位 | 分别为 24px、12px，数值使用等宽数字 |
+
+业务区间距为 12px 至 14px，Agent 消息之间保留 24px。地图与业务面板的普通控件和内部区域沿用 8px、12px 圆角，独立大面板使用共享 16px 圆角；具体值复用组件变体和地图圆角常量。Agent 弹窗、面板和表单控件沿用本地 shadcn/ui 的默认圆角、间距及尺寸变体。
+
+地图与业务表单的主要按钮目标高度为 40px；基础 `Input` 当前默认 36px，这些业务场景通过 `h-10` 或适配后的字段组件统一。Agent 控件优先沿用 shadcn/ui 默认尺寸和 `size` 变体。紧凑控件保留至少 40px 的互不重叠命中区域，可通过周边留白适配触屏。
+
+地图保持主工作区。浮层、导航、时间轴和正文预留各自安全区，地图背景可延伸到 56px 顶部导航背后。业务内容按“定位、状态、下一步、证据”排列，原始对象与历史按需展开；移动端单列，表格只在自己的容器内横向滚动。
+
+Agent 与主工作区、地图与报告使用共享 `Resizable` 分栏；连续调宽不增加布局过渡。报告展开保留同一组件实例、草稿、筛选与阅读位置。具体尺寸、切换条件和任务交互由 [Agent 交互与报告设计](agent-chat-ui-design.md) 维护。
+
+## 6. 组件与交互规则
+
+| 用途 | 优先组件 |
+|---|---|
+| 操作 | `Button`，复用 `default`、`outline`、`secondary`、`ghost`、`link` 和 `destructive` 变体 |
+| 输入与选择 | `Input`、`Textarea`、`InputGroup`、`FieldSelect`、`Select`、`Checkbox`、`Radio`、`DateTimeField` |
+| 分组、状态、数据 | `Card`、`Separator`、共享状态组件、`Table`、`Tabs` |
+| 证据与过程 | `Disclosure`、`Accordion`、`Collapsible` |
+| 菜单、弹层、解释 | `DropdownMenu`、`Dialog`、`Tooltip`、`HoverCard` |
+| 可调工作区 | `ResizablePanelGroup`、`ResizablePanel`、`ResizableHandle` |
+
+`WorkbenchSection` 统一标题、说明、状态和操作；`WorkbenchNotice` 使用局部状态线；`WorkbenchEmptyState` 只说明为空原因与下一步。以分隔线、留白和浅色差组织内容，避免重复嵌套同级卡片。
+
+每个业务区最多一个醒目的主操作。按钮覆盖默认、hover、按压、焦点、禁用和加载态；hover 仅用于支持 hover 的设备，加载时阻止重复提交并保留可读状态。地图与业务控件沿用共享按压反馈，Agent 控件保留本地 shadcn/ui 交互状态；具有专用资源交互的 `AgentPersona` 保留原版悬停，不额外缩放或变暗。
+
+地图与业务表单字段复用 `.form-field`，聚焦只改变原有 1px 边框；组合输入由外层承担焦点边界，无边框输入使用内描边。Agent 字段保留本地 shadcn/ui 输入组件的边框、焦点和错误样式。错误通过文字、`aria-invalid` 和关联说明表达，失败后保留输入。选中与焦点不改变控件尺寸，底图选择卡片使用主题边框和勾选标记，键盘焦点使用共享内描边。
+
+弹层保留标题、关闭入口、焦点管理及触发控件的焦点返回。表单弹窗显式将初始焦点放在首要业务字段，选择框获焦不自动展开。Esc 从内到外处理，外层尊重已消费事件；弹窗容器可承接程序焦点，业务控件仍保留可见焦点。模态遮罩阻断底层地图操作。
+
+状态必须区分无数据、加载中、失败、无权限、未配置与结果未知；保留完整证据、修订及请求号的可读入口。演练数据明确标记，前端展示不能暗示已经完成业务执行或写入。
+
+## 7. 验证与维护
+
+文档修改检查引用路径、示例中的本地组件与属性、命令及 `git diff --check`。运行代码变更执行 `pnpm lint`、`pnpm typecheck`、`pnpm test`；可见 UI 变化增加聚焦的 `pnpm test:browser`，依赖、构建或运行集成变化增加 `pnpm build`。
+
+界面验收覆盖 1280px 及以上桌面和 320px、375px 窄屏，检查长内容、按钮与命中区域、弹层边界、Tab、方向键、Esc、焦点返回及减少动态效果。普通文字与实际合成背景对比度至少 4.5:1，焦点与必要非文字状态至少 3:1，并验证强制颜色、减少透明度与模糊不可用时的回退。
+
+Agent 界面另检查所有弹窗、面板及其子菜单是否沿用本地 shadcn/ui 设计，是否存在地图材质类、额外模糊和阴影、独立 Agent 配色或重绘基础控件的 CSS。尺寸和层级适配不能改变这些组件的视觉规范。
+
+设计规则只在本文维护；业务协议与动作留在功能文档，历史测试结果留在交付记录，不作为当前全量验收结论。
+
+## 官方参考
+
+- [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)。