# DSH-UX-001 采纳与验收记录

## Unreleased：原生首页引导接入（UX-49 部分采用）

最终本地复核：40 文件 / 274 测试、typecheck、build 通过；新增入口级主动清空不补填及 A/B 导航竞态回归。npm pack dry-run 通过（99 文件，约 13.93 MB，主要为既有中文字体）；未发布 npm。下文 263/272 项记录为开发过程阶段结果，不是最终计数。

引用权威规范 `AI-设计/DSH智能体开发交互规范方案.md` DSH-UX-001 v1.5.6 的 UX-49、第11.1及14节；UX-48 不变。模板 ID 为 `dsh-initial-draft/previsit/1`，正文严格采用第11.1节，SHA-256 在 `src/initial-draft.ts` 固定并测试。

已实现精确模板识别、向导保护、缺项 Skill 澄清、占位符 begin 防御和产品自有初始化内核。内核只接收显式新 Session 事件、消费标记后异步二次快照、revision=0 防输入后清空竞态、存储异常/能力缺失不写入；没有发送、工具或开台能力。内核端口是内部契约，不是虚构的 DSH 公开 API。

2026-09-15 按用户最新范围，已将原生 setDraft 接入新建访前菜单入口，创建后、打开前写入；不在挂载/恢复/切回时补写。保护已有草稿、附件、引用及输入后清空的修订记录，不自动发送、调用业务工具或展开工作台。新增真实入口函数的模拟 Host 测试，当前 `pnpm check` 40 文件 / 272 测试、类型检查和构建通过。尚未完成真实 DSH A/B/legacy/普通会话、IME、四插件组合验证，也无公开 Host 不抢焦点保证及持久化初始化 ledger。详见兼容记录，不能将此范围内实现等同于完整 UX-49 验收。

本地验证（2026-09-15）：`pnpm check` 通过，40 个测试文件 / 263 项测试、类型检查与构建通过；`git diff --check` 和 `npm pack --dry-run --ignore-scripts` 通过。`pnpm test:ui` 的 Chrome 首个场景进程未正常退出（status=null，未取得 UI 断言结果），不能计为通过。Skill 通用验证器因 Python 缺少 yaml 依赖未运行成功；仓库 Skill 契约测试已通过。完整门禁尚未通过，未 commit/push/创建 PR，无 PR CI 或真实 DSH 证据。

补充验证：Chrome 崩溃记录显示 SIGABRT，调用栈在 macOS `_RegisterApplication`，不是页面断言失败。通过本地只读 HTTP 服务在隔离浏览器重新加载同一构建的 fixture，浅/深色 × 1440×900、390×700 四组均达到 `uiReady=true`，全部布尔 dataset 断言无 false、菜单/历史/回填及页面无横向溢出通过。这是替代浏览器回归，不改写原命令失败记录，也不是实际 DSH 的 UX-49 验收。Python 临时环境补齐 yaml 后，通用 Skill 验证器拒绝原有 DSH `whenToUse` / `user-invocable` 字段；保持 DSH 元数据不变，以本仓 Skill 契约检查为准，不为通过 Codex 格式检查删改 DSH 属性。

## 0.1.25：只读历史阶段与事实展示

历史导航不改变当前 Session；扫描事实跟随原任务保存。执行成功与风险命中分别展示，不用绿色查询完成暗示企业安全。经营区域使用实际摘要而非固定状态占位。自动发布沿用 main CI → 注释 tag → OIDC npm 发布及 registry 核验。

## 0.1.24：稳定入口、首页品牌与历史详情

日期：2026-09-13。

| 交互要求 | 当前实现 |
| --- | --- |
| 菜单名称不能被加载或错误状态替换 | 左侧入口始终显示“访前尽调”；处理中仅使用 `aria-busy` 与禁用态，错误通过标题提示 |
| Host 调整 Hero 与 composer slot 层级后仍要显示业务首页 | 从本插件 composer seat 向上定位同一首页标题，宿主重渲染后继续同步“访前尽调一页纸智能体”、业务 LOGO 与预览标记 |
| 历史任务必须能打开和下载 | 携带该记录自身来源 Session 读取只读详情、内嵌报告与下载制品；不会重新查询或污染当前任务 |

## 0.1.23：旧记录兼容与 TaskScope 契约

日期：2026-09-13。

| 交互要求 | 当前实现 |
| --- | --- |
| 历史升级不能丢弃旧 Host 记录 | 缺少 Workspace / Session 的合法旧记录继续进入 Profile 历史，并规范化为空来源哨兵 |
| 来源缺失不得猜测或重绑 | 卡片明确显示“未记录（旧记录）”；旧记录不匹配任何当前 Session，也不能由当前页下载或回写 |
| 当前任务与历史查询边界应可复用 | `HostedTaskListScope` 显式区分 `current` 和 `profile-history`；独立 TaskScope 文档覆盖 Session A/B/legacy fixtures |
| 长来源信息不能破坏布局 | 浅色/深色 × 桌面/窄屏四种隔离 Chrome 场景检查跨 Session 长路径与旧记录标识 |

## 0.1.22：跨 Session 历史汇总

日期：2026-09-13。

| 交互要求 | 当前实现 |
| --- | --- |
| 重新打开插件后仍能查看历史任务 | “任务历史”读取当前 DSH Profile 内全部访前尽调 Host 记录，不再只筛选当前 Session |
| 历史与当前任务不得混淆 | 当前任务、阶段进度、报告回写和下载仍严格绑定当前 Session；历史卡片显示来源 Workspace / Session |
| 原生对话归属必须可追溯 | 历史只汇总任务状态与报告制品，完整消息和证据引用仍保留在来源 DSH 原生会话中 |

## 0.1.21：真实进度与状态语义分层

日期：2026-09-13。

| 交互要求 | 当前实现 |
| --- | --- |
| 长任务不能数分钟没有反馈 | 资料采集与证据核验持续显示当前查询、真实查询数、闭环数、最近完成项与耗时；工具调用间隙显示正在研判整理 |
| 已完成不能被旧待处理状态染黄 | Host runs 按业务维度只投影最新记录；后续完成、无数据或无需执行覆盖同维度的旧合成占位 |
| 流程状态不能冒充风险预警 | 顶部阶段的待复核改为中性灰；黄色只用于真正待处理的业务结果或关注级风险内容 |
| 经营状态灰卡必须可解释 | 八项标明互斥关系，并逐项显示当前研判、非当前研判、未形成结论或待研判；覆盖状态由独立采集结果承担 |

进度卡不显示不可验证的百分比。绿色仍只代表当前维度已查询完成、明确无数据或按规则无需执行，不代表企业绝对无风险。

## 0.1.20：真实 Provider 状态与风险语义色

日期：2026-09-12。

| 交互要求 | 当前实现 |
| --- | --- |
| MCP 成功取得的信息应直接显示完成 | 识别企查查 Provider 的中文业务对象；非空成功对象、明确零记录、无权限和失败分别归一，不再依赖不存在的通用 `success/data/items` 包装 |
| “已取得 / 已核查”不能与待核验计数矛盾 | 容器改名为“采集结果 / 核验结果”，并独立显示已完成、待确认、未完成和失败计数 |
| 零风险不是预警 | 明确的“条目数 0 / 本次未发现公开记录”使用绿色完成态；只有实际关注项使用黄色，红线使用红色，普通信息使用蓝色 |
| 风险明细应按真实计数闭环 | 解析生产返回中的 `风险因子扫描 / 明细工具 / 条目数`，兼容数字与数字字符串；零计数标记无需执行，非零计数仍要求下钻 |

绿色仅表示本次公开数据核查成功且未发现相应记录，不表示企业绝对无风险；无权限、无法判断或未执行不会显示为绿色。

## 0.1.19：工作台输入隔离与核验闭环

日期：2026-09-12。

| 交互要求 | 当前实现 |
| --- | --- |
| 侧栏中文输入不得影响原生会话 | “拜访客户”逐字输入只更新插件 Session Store，不调用宿主 `setDraft`；键盘与 composition 事件继续隔离，仅点击“开始尽调”才一次性提交 |
| 档位不应提前终止核验 | 移除 8 / 18 / 40 次插件硬上限；三档只控制查询优先级、覆盖深度与目标时长 |
| 必查与无需执行都要闭环 | 风险非零项必须实际下钻；零计数逐项记录“无需执行”。关键人员有数据时必须执行董监高风险扫描，无数据时明确跳过 |
| 每一子项有可解释状态色 | `done / no-data / skipped` 绿色，`unknown / no-permission / not-executed` 黄色，失败红色，运行中蓝色；跳过原因随 Host run 同步 |

上述规则延续工作台初始关闭、Session 单例 Tab、企查查蓝品牌和招投标式阶段菜单，不改变宿主容器控制权。

## 0.1.18：输入法隔离、任务快照与默认设定

日期：2026-09-12。本轮保持工作台初始关闭、Session 单例 Tab 和五阶段菜单，只修复输入提交边界、Host 进度可见性及常用设定效率。

| 交互要求 | 0.1.18 实现 |
| --- | --- |
| 表单输入不得触发宿主发送 | “拜访客户”输入框的 keydown/keyup/composition 事件止于组件；输入法确认候选词不启动任务 |
| 已提交任务不受后续草稿影响 | 点击开始时读取 Store 最新值并冻结企业、选项快照；Host 启动后以任务 query/confirmed entity 为展示事实源 |
| 动态过程优先于空的输出骨架 | 报告整理中继续停留最后一次真实采集或核验页；报告制品就绪后才切材料输出 |
| 候选确认提示必须状态准确 | 仅 `needs-entity-confirmation` 显示选定企业提示；已锚定主体显示已同步调用数或报告整理进度 |
| 高频选项默认可见且可修改 | 默认银行/信贷客户经理、六项关注全选、3分钟速览、一页纸简报；场合不预设，避免臆造首次/复访事实 |

隔离验证覆盖 21 个非安装器测试文件 / 140 项、TypeScript、Host/Client 构建和 4 个真实 Chrome 布局场景；未调用真实企查查 Provider。

## 0.1.17：终态不可回退与多状态进度反馈

日期：2026-09-11。本轮不改信息架构、工作台初始关闭和 Session 单例 Tab，仅修正报告终态与可视化进度的一致性。

| 交互要求 | 0.1.17 实现 |
| --- | --- |
| 完成状态不可回退 | 报告上架后禁止新 run 和同 ID 重定向；重复 finalize 幂等，保留原制品和完成时间 |
| 当前任务与历史状态一致 | 只要 Host 已有有效报告制品，两处均显示“报告已生成”；旧版回退记录读取时自愈 |
| 阶段和子项完成后变色 | 阶段菜单、四个子步骤和维度标签统一使用蓝/绿/黄/红/灰状态语义；子步骤同时变更边框和图标 |
| 不用颜色伪造证据完整性 | 查询成功或明确无数据为绿色；结构无法确认的返回为黄色待核验；未执行保持灰色虚线 |

## 0.1.16：输入 overlay 和 Host 阶段驱动补齐

日期：2026-09-11。本轮不改工作台初始关闭、Session 单例 Tab 和招投标式五阶段菜单，只修复原生输入与执行状态的两个接入断点。

| 交互要求 | 0.1.16 实现 |
| --- | --- |
| 提示词按钮不占用正文首行 | 对齐数据清洗补全：输入卡片顶部预留 48px，overlay 本身不拦截指针，仅按钮恢复交互 |
| 原生对话可直接发起任务 | 识别 DSH 嵌套 `message.role`；即使本地任务尚未认领，也主动从当前 Session 取回 Host PVT 任务 |
| 主体显示以已锭定法律实体为准 | 收到 Host `entity.fullName` 后立即更新范围确认页，不保留部分检索词 |
| 阶段必须由真实执行驱动 | 首次发现任务和 Host 阶段变更时才自动前进；用户在同一阶段手动查看其它页面时不被每秒拉回 |

隔离验证：非安装器测试 20 文件 / 129 项通过；TypeScript 与构建通过；浅色/深色 × 1440×900 / 390×700 的 4 个 Chrome 布局场景通过。真实 Provider 仍需用户 OAuth 和额度，本轮未消耗。

## 0.1.15：状态真实性与可操作反馈补齐

日期：2026-09-11。本轮不改变 DSH-UX-001 v1.5.2 的信息架构、招投标式阶段菜单、数据清洗补全式首页快捷按钮、企查查蓝品牌样式或工作台初始关闭规则；改动聚焦于开发规划中的“真实业务事件驱动状态”与“失败必须可见、可继续”。

| 交互要求 | 0.1.15 实现 |
| --- | --- |
| 认领任务后不重复打断 | 发送任务即表示同意所选档位的有界 MCP 调用；只在搜索命中多个法律实体时请用户消歧 |
| 主体标识一致 | 工作台读取 Host 已确认的完整企业全称和信用代码，不继续展示用户的部分检索词 |
| 阶段状态可追溯 | 资料采集、证据核验、材料输出及顶部总状态均由 Host 任务、run 和制品驱动；菜单切换仍不伪造进度 |
| 完成与下载有闭环 | 完整八段报告经 `previsit_finalize` 或同 Session 会话捕获回写后，同步显示“报告已生成”、历史完成状态和可下载 HTML；制品未就绪时点击按钮会告知原因 |
| 重启后不丢失展示状态 | 任务元数据、主体、调用记录、状态和报告制品通过 Host `storageDomain` 持久化；不持久化企查查原始返回 |

自动化证据：Node 24.21.0 的 `pnpm check` 通过 20 个测试文件 / 130 项测试、类型检查和 Host/Client 构建；浅色/深色 × 1440×900 / 390×700 共 4 个隔离 Chrome UI 场景通过。

## 0.1.14：DSH-UX-001 v1.5.2 Workspace 归组与普通会话隔离

日期：2026-09-11。本轮延续 v1.5.1 的可选工作台边界，只修正 Workspace / Session 所有权和原生新会话的隔离语义；不改页面信息架构、容器选择或业务状态真实性规则。

| v1.5.2 要求 | 本仓实现 | 保护边界 |
| --- | --- | --- |
| 业务 Session 归属当前 Workspace | 按当前 Session 所属 Workspace、`recentWorkspaceId`、首个可用 Workspace 的顺序解析 `workspaceId`；通过 `sessions.create({ workspaceId, sessionId })` 创建 | 保留 `session-dsh-pre-duediligence-*` 命名空间和严格返回 id 校验；无 Workspace 或创建失败时不导航 |
| 普通“新建会话”不复用业务空 Session | 同时适配 DSH 0.1.1 的 `workspaces.connectWorkspace` 与 DSH 0.1.2 的 `uiWorkspace.connectWorkspace` | 统一排除访前尽调、数据清洗补全、AI 填表、招投标四个命名空间；不改普通 Session 的宿主返回 |
| 可复用候选不跨边界 | 仅选择同 Workspace 的 `sessionIds` 成员、同 `cwd`、`blank === true`、且未归档的普通 Session | 无合法候选时以 `sessions.create({ workspaceId })` 新建；并发请求按 Workspace 合并，失败原样向上抛出 |
| 保留已有容器交互 | 入口只进入业务 Session，初始不打开 Sidebar；五项流程按钮定位同一 Session 单例 Tab | 无 Sidebar 只给可执行提示；Tab X 和宿主折叠后从原流程按钮恢复，不变更任务/历史/制品 |

自动化证据：Node 24 下 18 个测试文件 / 125 项断言、类型检查和构建通过；浅/深色 × 1440×900 / 390×700 的 4 个隔离 Chrome UI 场景通过。真实 Host 在三个临时 `DSH_HOME` 路径验证无 Sidebar、Sidebar `0.18.1`、Sidebar `0.17.1`；两个 DSH 基线均覆盖只有业务空 Session 时的普通新会话创建与归组。未配置模型/OAuth，未调用付费 MCP，未读写生产 `~/.dsh`。

## 0.1.13：DSH-UX-001 v1.5.1 可选工作台第一阶段

- Better Sidebar 继续作为唯一可视化工作台容器，但不再是基础安装前置；本阶段不新增自有抽屉，也不开始原生容器替换。
- 无 Sidebar 时，客户端不等待或运行时导入第三方包；左侧入口、专属 Session、首页、提示词生成器和原生 composer 保持注册。用户点击五项工作台流程按钮时收到可执行提示，当前草稿、任务和会话不被修改。
- 基础路径仍装 MCP Connector 与访前插件；Skill、Host 预算/主体确认工具和原生会话报告不依赖 Sidebar。五阶段可视化、工作台历史和 HTML 下载仍需兼容 Sidebar。
- 安装器默认 `DSH_PREVISIT_WORKBENCH=off`，只有显式设为 `on` 才安装成套 Sidebar；已安装但与当前 Host 冲突的 Sidebar 仍在任何 Profile 写入前被拒绝。
- 本阶段不抢占 DSH `details`，不用 `shell.overlay` 或 `position: fixed` 自建侧栏，不通过 DOM 点击模拟宿主导航；不引入未进入 DSH `0.1.2-rc.1` 验证安装树的 `ui-sidebar-right`、dockkit 或 file-upload。
- 业务状态与报告投影继续以 Session / Host 数据为事实源，Better Sidebar 调用集中在独立 adapter。本轮只清理后续 `WorkbenchSurfacePort` 适配边界，不实现或发布 DSH 原生容器迁移。

## 0.1.11 整改：v1.5.0 容器控件收敛

日期：2026-09-10。权威规范为 `DSH智能体开发交互规范方案.md` v1.5.0 第 7、13.4、14、15、15.1 节；交互参考为 `DSH智能体_企查查蓝_UI_Mockup_v1.5.0.html`。本轮发布 `dsh-pre-duediligence@0.1.11`；插件市场投稿保持独立流程，不以 npm 发布替代真实 DSH 或 Provider 验收。

### 实现映射

| v1.5.0 要求 | 本仓实现 |
| --- | --- |
| 唯一容器 | 保留 `dsh-pre-duediligence:agent`、`registerTab` / `openTab`、`single: true`、Session scope；不新增 fixed 抽屉、分隔条或私有宽度状态 |
| 容器控件归宿主 | 删除内容头 `qccPwClose` /“关闭访前尽调工作台”和页脚“返回会话”；业务内容不再写 `panelOpen` / `bottomOpen`，宿主负责收起、宽度、停靠、浮窗和 Tab X |
| 流程定位 | 对话区五个按钮映射对象与目标、范围确认、资料采集、证据核验、任务历史；历史是同一 Tab 内一级视图，材料输出仍可由同一 Tab 的阶段导航进入 |
| 幂等与隔离 | 每次按钮点击都以目标 Session 调用 type-only `openTab` 聚焦单例 Tab；相同内部视图严格 no-op，不创建/替换任务，不调用 MCP；非前台 Session 的 reveal 只排队或修改目标 Session store，不改变前台几何 |
| 兼容与降级 | 仅接受 Better Sidebar 0.17.x / 0.18.x，同时探测 `targetedOpen`、`stateSubscription`、注册、定向打开、启用状态、快照和订阅方法；缺失或不兼容时保留纯对话并显示安装/升级提示，不生成备用侧拉 |
| 卸载 | 使用宿主 `registerTab` disposer 注销 descriptor；React effect 返回会话快照订阅 disposer；插件根 effect 令入口失效并清空 reveal target / pending 队列，不关闭、移动或清空其它 Tab |

### 本轮证据与边界

- 定向单元/契约测试覆盖：内容区无重复 X/返回控件、Tab 单例 descriptor、流程映射、定位幂等、Session 状态隔离、非前台 Session 不改变前台几何、浮窗不改几何、缺依赖/缺能力降级、注销 disposer 和 pending reveal 清理。
- 使用受支持的 Node 24.19.0 执行 `pnpm check` 已通过：17 个测试文件 / 111 项测试、类型检查和 Host/Client 构建全部成功。系统默认 Node 25.9.0 会被安装器按声明的 Node 22/24 边界拒绝，未为通过测试而扩大引擎范围。
- `pnpm test:ui` 已通过浅色/深色 × 1440×900 / 390×700 共 4 个隔离 Chrome 场景；除原有布局、焦点和 Session 隔离外，新增五项流程标签及业务内容无重复容器 X/返回按钮断言。
- `npm pack --dry-run --ignore-scripts --json` 使用隔离缓存通过，共 42 个发布文件；生成后的 `lib/client.js` 与类型声明已纳入本轮发布，未把 `_scratch` 测试产物加入发布清单。
- 已在临时 `DSH_HOME` 以 DSH 0.1.2-rc.1、Better Sidebar 0.18.1、MCP Connector 0.2.37 及可选 Context 0.48.0 启动真实 Web，验证初始关闭、五入口、同 Tab 定位/重复 no-op、宿主 Tab X 后恢复、提示词生成与原生草稿回填，浏览器控制台无 error/warn。该结果只覆盖候选组合的无付费交互，不覆盖右/底/浮窗迁移、后台 Session、运行中任务、四款业务插件共装或真实企查查 Provider。
- 后续组合回归：在隔离 Profile 分别使用 Sidebar 0.17.x / 0.18.x，与数据清洗补全、AI 填表、招投标同装；覆盖初始关闭、五入口重复点击、前后台 Session、宿主收起/恢复、Tab X/重开、右侧/底部/浮窗迁移、任务运行中操作、单包卸载和完整重启。验证两类宿主关闭动作都不改变 taskId、历史或制品。

## 0.1.9 整改：目标 v1.2.0，全文核验待完成

日期：2026-09-07。根据团队同步邮件 DSH-AGENT-SYNC-001 中的 v1.2.0 摘要实施；邮件所列权威文件在当前机器对应路径不存在，故不声明已完成 v1.2.0 全文采纳。仓库仅记录采用版本、业务差异、例外和证据，不复制权威规范。

本轮变更：可选 Sidebar 及 0.17/0.18 能力适配；会话输入机替代全页面草稿改写；任务快照报告替代 DOM 抓取；独立报告/维度完成状态；Agent-owned 高层工具经 ToolRuntime 调用、用户付费预算确认、主体确认、防绕过与取消；安装矩阵和发布门禁。详细边界、四层验收及发布证据见 [兼容与验收记录](COMPATIBILITY.md)。

未完成：权威 v1.2.0 全文回读；真实 DSH 四插件共装/切换/升级/卸载；企查查 Provider 两基线契约与最小业务验收；awesome-dsh-plugin [PR #4587](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/pull/4587) 虽已通过两层门禁，但仍待维护者合并和目录生效。本轮自动化通过情况应引用本次执行结果，不复用下面历史 59 项结论。

## 以下为 0.1.8 / v1.1.3 历史记录

日期：2026-09-07。业务插件：`dsh-pre-duediligence@0.1.8`。规范源：[共享交互规范 v1.1.3](../../../../AI-设计/DSH智能体开发交互规范方案.md)，视觉参考：[企查查蓝交互 Mockup（原文件名 v1.1.0，内容 v1.1.3）](../../../../AI-设计/DSH智能体_企查查蓝_UI_Mockup_v1.1.0.html)。

## 页面与品牌映射

| 规范区域 | 本插件实现 | 隔离边界 |
| --- | --- | --- |
| 左侧入口 | 菜单名固定为“访前尽调”，使用 Mockup 的线性建筑 SVG；只创建并进入专属 Session | 位于工作区列表前；不调用 `openTab`，初始页右栏关闭；隐藏 Better Sidebar 标签菜单项 |
| 中央首页 | 标题“访前尽调一页纸智能体”，同排建筑 LOGO，独立说明行 | 只在插件创建的空白 Session 可逆改写；卸载时恢复宿主标题、图标和预览标识 |
| 原生输入区 | Composer 下方五项数据清洗补全式描边卡片快捷菜单（上图标、下短标签）；左上角“提示词生成” | 不替换输入框、模型、权限和原生发送按钮；窄屏只在菜单内部横向滚动，不撑宽页面 |
| 提示词向导 | 对象 → 角色场景 → 范围深度 → 确认输出 | Portal 到 body；回填不发送；已有草稿显式选择替换、追加或取消 |
| 右侧工作台 | 当前任务 / 任务历史；当前任务按 Session 隔离，历史汇总本 Profile 全部访前 Session；招投标式五步等宽导航（上图标、下短标题、无描述）；由输入框下方快捷按钮打开和恢复 | Better Sidebar 是唯一权威工作台；关闭不取消会话任务；历史卡片标注来源 Workspace / Session；不另设会话头打开入口；窄屏菜单不横向越界 |
| 下载材料 | 自包含 HTML 一页纸报告 | 只使用已捕获的当前 Session 报告，不跨 Session 合并 |

## 菜单与阶段映射

| 首页菜单 | 工作台视图 |
| --- | --- |
| 企业核验 | 对象与目标 |
| 经营画像 | 资料采集 |
| 风险核查 | 证据核验 |
| 访前材料 | 材料输出 |
| 任务历史 | 任务历史 |

五步导航为：对象与目标 → 范围确认 → 资料采集 → 证据核验 → 材料输出。导航采用招投标右侧菜单的单行等宽分栏、上图标下短标题、细分隔线样式；选中项使用浅蓝底、蓝字和底部蓝线，菜单内不显示第二行描述。导航选择仅表示用户正在查看的页面，不表示阶段已经完成。

## 状态映射

| UI 状态 | 真实依据 |
| --- | --- |
| 待设定 | 当前 Session 未认领访前任务 |
| 等待确认 / 继续 | 已有任务但未运行，或 Agent 已停止且尚未捕获符合契约的完整报告 |
| 正在尽调 | 当前 Session 快照 `running === true` |
| 报告已生成 | 当前 Session 已捕获含核心研判及现场必问/覆盖说明的报告 |
| 需要处理 | 当前 Session 有 Agent 错误 |

工作台不以“运行停止”代替“报告完成”，也不以菜单点击或阶段切换伪造执行状态。

## Token 与组件

浅色品牌 / 动作色为 `#128BED / #0875D1`，深色为 `#55ADFF / #82C3FF`；表头、背景、文字、边框、成功和复核色均按 v1.1.3 候选表实现。小号白字主按钮使用动作色，深色模式动作按钮使用深色文字。所有变量限定在 `.qcc*` 自有节点，不覆盖全局 `:root`。

## DSH 兼容范围与例外

- 依赖 DSH `>=0.1.1-rc.2` 与 `dsh-better-sidebar@0.17.1` 的公开能力。
- 首页标题因宿主暂未提供会话级 headline slot，采用已知 `[data-phase="hero"]` / headline DOM 的局部、可逆兼容桥；未知结构下保留宿主原样。
- 任务历史复用现有 Host 持久库，汇总当前 DSH Profile 内所有访前尽调 Session；不另建浏览器历史库。完整消息和证据引用仍以来源 DSH 原生会话为准。
- 尚未在所有未来 DSH 版本和所有第三方插件组合中完成实机视觉验收，兼容范围不外推。

## 自动化证据

- `pnpm run typecheck`：TypeScript 严格模式通过。
- `pnpm run test`：11 个测试文件、59 项测试通过，覆盖会话归属、LOGO/首页文本、菜单、提示词草稿合并、首页纵向描边卡片、五步状态、阶段菜单样式与描述移除、完成判定、报告导出、安装与 Skill 契约。
- `pnpm run test:ui`：真实 React、隔离宿主 DOM 与本机 Headless Chrome 的浅色/深色 × 桌面/移动共 4 组通过；检查快捷菜单的五项单行、纵向布局、54px 高度、中性描边、内部横向滚动与视口边界，并覆盖三处同源 LOGO、五步导航、弹窗、焦点、主题 Token 及页面横向溢出。
- `pnpm run build` 与 `npm pack --dry-run`：发布前执行，结果以发布提交的 CI / Release 记录为准。

视觉回归截图和机器结果生成于 `_scratch/ui-layout/`，该目录不提交仓库，也不进入 npm 包。

## 实机验收清单

1. 普通会话不出现访前标题、菜单、提示词触发器或工作台恢复入口。
2. 从“访前尽调”进入后，只显示专属初始会话，右侧工作台关闭；菜单与首页显示同一建筑 LOGO，首页名称和说明行居中。
3. 浅色、深色及 390px 窄屏下，无横向页面溢出；移动输入字号不低于 16px。
4. 向导正文可滚动、头尾固定；Tab 不越出弹窗，Escape 关闭并恢复焦点。
5. 输入框已有文字时验证替换、追加、取消三条路径；回填后不自动发送。
6. 输入框下方五项业务按钮为数据清洗补全式单行描边卡片、上图标下短标签；390px 窄屏仅菜单内部横向滚动，页面不越界。
7. 点击上述卡片后才打开对应工作台视图；关闭不取消任务，再点同组按钮可重新打开。
8. 右侧五阶段菜单为等宽分栏、上图标下短标题且无第二行描述；选中项有浅蓝底、蓝字和底部蓝线，390px 窄屏不横向越界。
9. Agent 停止但无完整报告时仍显示“等待确认 / 继续”；完整报告出现后才显示“报告已生成”并允许下载。