# 文档解析与附件 UI 设计

本文定义 [PRD](./prd.md) FR-H1 至 FR-H12、FR-I1 至 FR-I5 的完整交互，状态决策以
[逻辑设计](./logic-design.md)为准。当前实现细节见[生产实现](./implementation.md)，验证
状态记在 [进度](./progress.md)。配置、解析、预览、选图、发送和资源清理属于同一验收范围。

## 1. 容器与共享组件

遵循根目录 [UI 设计系统](../../../UI-DESIGN.md)，保留当前应用容器结构。下表依据
2026-09-18 源码核对，标为新增的内容需要实现，不能当作现有 API。

| 位置 | 现有结构及设计用法 |
| --- | --- |
| 设置中心 | `SettingsPanel.tsx` 整窗 Modal 内的 `DocumentParsingSettingsSection.tsx`；继续使用 `SettingsCategoryHeader`、`settings-section`、`field`，不套第二个 PageShell 或一级标题 |
| 聊天 | `App.tsx` 的 `PageShell variant="reading"`；附件卡位于原 Composer 内，待发送队列仍在 Composer 外，不在助手工作栏增加附件栏目 |
| 知识库 | `App.tsx` 已提供 `PageShell variant="master-detail"`，`KnowledgeWorkspace.tsx` 内含库导航与 DocumentsView；需在文档区域新增解析详情及返回列表，不再嵌套页面壳层或新建知识库级页签 |
| 解析预览 | 新增共享内容视图，分别嵌入设置诊断 Modal、聊天附件 Modal 和知识库文档详情；共享数据和交互，外层容器负责标题、范围、关闭与滚动 |
| 页签与选择 | `WorkspacePrimitives.tsx` 的 `PageTabs variant="segmented"` 承载正文、图片、详情；来源及过滤模式使用 `SegmentedControl`，不能用它替换页签语义 |
| 浮层 | Modal 沿用 body Portal、`activateModalFocus` 与 `trapTabFocus`；测试及附件菜单复用 `AnchoredMenu`，由共享 `FloatingPortal` 挂入所属 Modal 并在 top layer 绘制。通知遵循根 UI 规范 |
| 图文内容 | 复用 `MarkdownRenderer.tsx` 的排版、表格滚动和静态 HTML 处理边界；补齐受管图片与 OCR HTML 表格适配，现有 Markdown 渲染器并未直接支持这些资源 |
| 状态与反馈 | `ScopeBadge`、`EmptyState`、共享按钮、`toggle-row` Switch、应用 `onNotify`；图片多选用 Checkbox，失败重试就地显示 |

全部颜色、间距、字体、边框、圆角和动效使用根设计令牌。连续正文使用阅读字号，图片格不
加装饰阴影。长文件名截断并提供完整名称，不能挤走状态、关闭和发送。图片和解析结果不是
生成图片成果，不使用生图操作卡或生图重试入口。

### 1.1 入口与职责

本表规定完整功能的入口和配置归属，源码现状及证据统一见
[菜单核对记录](./progress.md#菜单核对)。应用中心的四应用清单、启用、常驻和排序继续遵循
[应用导航](../application-tool-navigation/README.md)，文档解析不新增第五个应用或右侧工作栏栏目。

| 用户任务 | 主入口与路由 | 范围及目标行为 |
| --- | --- | --- |
| 配置解析与 OCR | 侧栏底部“设置” → “文档解析”（`document-parsing`） | 设备级共享配置，分别保留聊天与知识库工作流；HTTP 地址、凭据和高级选项只在此维护，不随当前项目或会话切换 |
| 管理本地 OCR 文件 | 同一“文档解析”分类的本地模型区 | 下载、校验、ZIP、删除和目录操作；全局模型下载源仍在“平台功能 / 通用设置”，与 OCR 来源选择分开 |
| 查看或释放本地 OCR 内存 | “应用中心” → “本机推理监控”（`local-inference` Modal），或其常驻入口 | 只管理本机执行服务；应用启用及常驻控制入口，不控制解析功能；HTTP 服务不出现在本机服务列表，也不提供远程启停 |
| 添加文件或图片 | “当前对话” → “添加附件”，或输入框粘贴 | 先加入当前草稿，再按输入类型处理；上传按钮继续直接选文件，不改成先选 OCR 的菜单 |
| 查看聊天解析结果 | 草稿或历史消息的附件卡 | 规划中的共享预览；来源消息与目标草稿分别显示，历史输入只读 |
| 查看知识文档结果 | “知识库” → 选库 → “文档与来源”中的文档操作 | 规划新增“查看解析结果”和文档详情；返回恢复库、列表筛选和位置；不改变活动会话 |
| 把文档插图用于聊天 | 聊天或知识文档预览 → “图片” → “添加所选图片” | 明确目标会话草稿后复制；设置测试预览无此操作；已有“用于当前对话”仍负责知识库检索范围，不代替选图 |

从解析失败或未配置提示提供“前往文档解析设置”时，须直达 `document-parsing` 分类并保留
来源预览、目标和草稿；关闭设置返回原位置。跳转沿用设置中心离开保护，不复制配置表单。
保存后只更新后续解析采用的配置，不自动重试、重解析或发送。本机推理监控现有“模型与连接
设置”不是分类直达入口，不将它作为 HTTP OCR 配置路径。

### 1.2 附件操作菜单

下表规定交互。卡片提供查看入口，移除保留独立按钮；次操作放在卡片“更多”菜单，
菜单项包含附件名称以区分多个文件。普通图片的“提取图片文字”可作为就近次操作，不能和
菜单形成两套状态或重复执行。菜单复用 `AnchoredMenu` 的定位、键盘和焦点恢复。

草稿、历史消息和队列预览中的“查看解析结果”“更多附件操作”使用共享 `icon-button`
视觉，图标分别为文档查阅和省略号，点击区域为 `32px × 32px`，在独立操作行内排列。
按钮提供含文件名的可访问名称、悬停提示及键盘焦点提示；草稿移除和导入取消使用同尺寸
叉号。导入卡按进度图标、文件信息、取消按钮排列，进度条独占下一行。
文件名保持单行省略，悬停可读完整名称；解析状态、发送方式和大小在元数据行按空间换行，
不将次操作拉伸成整行文字按钮。布局以卡片所在容器宽度为准，沿用主题令牌和共享焦点环。

| 对象 | 查看操作 | 可改变内容的操作 |
| --- | --- | --- |
| 草稿文档 | 查看解析结果、打开原文件 | 使用当前设置重新解析、移除；图片多选只在预览中进行 |
| 草稿图片，发送原图 | 打开原图；已有 OCR 结果时可查看 | 提取图片文字、移除 |
| 草稿图片，发送提取文字 | 查看解析结果、打开原图 | 改为发送原图、使用当前设置重新提取文字、移除 |
| 历史消息附件 | 查看已保存结果、打开原件 | 需要重解析或改变发送方式时先添加到当前可编辑草稿；不修改原消息 |
| 已入队附件 | 仅有附件时显示“查看附件”，查看入队时冻结的结果与发送方式；无附件时隐藏入口 | 修改整条输入使用“恢复到草稿”，按 L-H7 合并；不直接修改队列附件 |
| 知识文档 | 查看解析结果、打开来源、管理分块 | 使用当前设置重新解析；失败时使用重试，不再并列一个同义重解析按钮；来源同步仍属于来源级操作 |
| 设置测试结果 | 查看正文、图片、详情及原件 | 重新测试、关闭；没有加入草稿、知识库或发送操作 |

操作依据对象、资源和任务状态显示。解析中仅保留可用旧结果的查看、进度和取消，不允许重复
解析；缺少结果或原件时说明缺失原因并给出重选入口。已有历史数据不显示能恢复完整资源的
假菜单。没有受管解析资产的外部知识库结果沿用其已有查看能力，不提供本地重解析或选图。
尚未接入生产链路的动作不先加入应用菜单或附件菜单充当可用功能。

## 2. 文档解析设置

### 2.1 信息顺序与保存

分类页头为“文档解析”，说明“配置聊天文档附件和知识库导入使用的解析方式”。右侧依次为
“测试解析”“保存设置”，仅保存为主按钮。现有两处场景测试按钮合并到页头测试入口，入口
展开“聊天附件 / 知识库导入”选择后打开文件对话框；场景预设仍各自编辑。

内容依次为运行状态、使用场景、OCR 来源与对应配置、默认折叠的高级设置。原生解析、OCR、
转换分别显示状态；远程 OCR 未配置不把原生解析标成不可用，旧 Office 转换沿用现状说明。
切换来源不发网络请求，不清空隐藏配置，也不改变已保存来源。显示“有未保存的修改”，
所有字段、过滤项和来源切换参与设置中心已有离开保护。

未保存时禁用测试和连接检查，旁边持续说明“请先保存设置，再测试解析”，通过
`aria-describedby` 关联；不得使用旧配置测试。保存期间防止重复操作，失败保留输入并在
分类页头显示原因。保存成功走应用通知，测试成功直接打开结果并呈现状态，不再同时弹
“测试成功”通知。取消文件选择不清除上次结果、不创建任务。

### 2.2 来源配置

“OCR 来源”使用共享分段控件，选项为“本地模型”“远程服务”，下方显示已保存来源与当前
编辑值是否不同。聊天和知识库分别保留工作流选择，不增加每会话 Provider 配置副本。

本地区域保留已有模型档位、下载源、安装校验、取消下载、ZIP 导入导出、删除及打开目录。
本地模型缺失只影响需要本地 OCR 的任务。切到远程后不要求先安装本地模型。

远程区域固定服务类型“HTTP PaddleOCR-VL”，包含有持久标签的服务地址、认证方式、密钥
输入和“已保存凭据 / 未配置凭据”。仅显示已实现的认证方式，技术契约见
[配置与请求](./http-paddleocr-vl-technical-design.md#配置与请求)。更改地址、临时选择无需
认证或切回本地都不清除已保存密钥；清除使用显式操作。密钥不回填明文。

配置旁持续说明“需要 OCR 的页面或图片将发送到此服务；快速文本模式不自动上传，主动提取图片文字仍使用此服务”。不增加
逐文件授权。“检查连接”是远程区域的次操作，成功文案为“服务可连接，解析能力需用文件
测试”；显示检查时间，不把 health 成功呈现为图表、印章等模型已可用。

### 2.3 高级设置

高级设置用原生 `details/summary` 默认折叠，按用途分组，不铺开 API 字段墙。

| 分组 | 控件与文案 | 生效语义 |
| --- | --- | --- |
| 内容保留 | 过滤模式“服务默认 / 全部保留 / 自定义”；自定义内为“保留页眉文字、页眉图片、页脚文字、页脚图片、页码、脚注、侧栏文字”正向 Switch | “保留”开启代表对应标签不进入排除列表；服务默认与空列表不同，见 L-H2 |
| 页面处理 | 方向分类、页面去扭曲、版面检测 | 各项原生选择框“服务默认 / 开启 / 关闭”，三态不能伪装成二态 Switch |
| 内容识别 | 图表识别、印章识别、图片块文字识别 | 同上；持续显示“接口已声明，尚未实测”或带测试条件的验证信息 |
| Markdown 格式 | 美化 Markdown、显示公式编号、格式化块内容、合并版面块 | 同上，不把未知服务默认显示成关闭 |
| 跨页整理 | “合并跨页表格”“调整标题层级”共享 Switch，默认关闭 | 明确会增加重组请求，保留源页集合；结果无变化如实报告 |
| 解析限制 | 最大页数、超时与现有适用的并发参数 | 显示单位和共享契约允许范围；本地单页超时与 HTTP 请求超时分开，不对未实现参数展示可保存控件 |

过滤项在文字和图片两个小组排列，标签使用正向“保留”。自定义从未编辑过时以全部保留
初始化并标明这一行为；已有自定义值切换模式后保留，不能根据未知的服务默认猜开关位置。
技术或已有配置含其他排除标签时以带名称的补充行显示并可恢复保留，例如 `text`；不能保存
一次表单就丢掉未列在常用组的排除项。“恢复服务默认”改变草稿，保存后才生效。

正文引用的插图默认保存，不设置“自动发送全部插图”。保留页眉图片等内容过滤与保存已引用
图片是两件事：被过滤且未引用的图片无需保存。高级能力证据仅描述相应部署和样例；没有证据
仍可由用户明确配置并测试，错误指出关联选项，完整实现范围包含这些已约定能力。

## 3. 共享解析预览

### 3.1 框架与正文

头部显示文件名、来源范围、结果状态、“打开原文件”和关闭或返回。设置测试标为“测试结果”，
聊天标明会话，知识库显示库名与 `ScopeBadge`。下一行固定正文、图片、详情三个 PageTabs，
页签及直接包装层 `flex: 0 0 auto`，仅当前面板滚动。查看已存结果不发 OCR 请求。

正文面板按来源页或章节呈现 Markdown、HTML 表格及受管图片。页面导航显示真实页号；
PPTX 显示“幻灯片 N”，没有分页的原生文档显示工作表或标题定位，不生成假页码。点击图片
旁的“第 N 页”或“查看正文位置”切到正文并聚焦对应标题；正文图片的“在图片中查看”反向
定位图片卡。跨页表格显示全部来源页链接，不把合表结果归给单一页。

“打开原文件”经 Main 打开保存的文件。聊天使用会话原件；知识库 managed 使用受管原件，
reference 使用原路径。reference 原件失效时显示“原文件不可用”，已保存正文与图片仍可看。
测试原件只在测试预览生命周期内使用，不承诺关闭预览后持久保留。旧附件没有解析资产时显示
“此附件未保存解析结果”，提供重新添加文件入口，不显示空白成功或自动补跑 OCR。

### 3.2 图片与详情

图片面板显示“已保存 N 张”及缺失数量，按原始页、页内顺序排列。每卡含缩略图、可读名称、
页码或定位、格式、尺寸和打开大图操作；图片使用 contain，不裁掉图表坐标轴。大图沿用共享
整窗浮层规则，Escape 只关闭顶层并返回图片卡，不能误关闭整个设置。

正文中的缺图替换为具体说明，例如“第 3 页图片 2 未保存：服务仅返回链接”，图片面板保留
不可选择的缺失项及原因。没有插图时显示“此结果没有提取图片”，说明原生解析器可能只提取
文字；加载中、读取失败、没有图片和筛选无结果分别呈现。仅有图片的结果显示“仅图片，无
可发送正文”，仍可预览并选择图片，不把空正文附件当成已就绪文本。

详情显示解析时间、实际工作流、Provider、无凭据的服务标识、原格式、总页数、OCR 页数、
文字量、图片保存情况、耗时、生效选项、服务默认项以及按页警告。服务未提供置信度显示
“未提供”。配置取自这次结果，不取当前设置；无法得知服务默认实际值时显示“服务默认，
实际值未提供”。跨页整理分别显示请求状态、是否观察到变化和来源映射，HTTP 200 不等于
“合并成功”。详情内不展示密钥、授权头、Base64 或原始错误响应。

### 3.3 测试与重解析

测试运行显示文件、场景、阶段、已完成页数（可确定时）和取消；未知进度使用不定进度条，
不模拟百分比。测试期间设置禁止关闭，用户可先取消，结算后再关闭。测试失败就地保留原因
和“重试”；有部分产物时可以查看，但不能标为成功。关闭测试预览后释放无引用测试资源。
测试预览不提供“添加到会话”，防止诊断文件进入用户草稿或知识库。

“使用当前设置重新解析”是聊天草稿和知识库文档的次操作，点击前显示将使用的已保存来源。
历史消息和队列冻结已接受的输入；其预览只读。历史消息使用“添加到当前草稿重新解析”，
产生草稿附件而不改写已发送正文；队列修改使用“恢复到草稿”，避免原队列和修改稿重复发送。
重解析期间旧结果仍可查看，顶部显示“正在重新解析，
当前显示上次结果”；成功才替换，失败或取消保留旧结果及单独的本次失败说明。

## 4. 文档插图加入会话

### 4.1 选择与添加

聊天和知识库预览的图片卡提供原生 Checkbox，标签含文档名、页码和图片序号；默认零选择，
打开预览不自动选图。点缩略图只放大，不勾选。页签切换保留本次勾选，关闭预览清除尚未
添加的选择；已添加状态由目标草稿查询得到，不用 Checkbox 冒充已附加状态。

底部操作条显示目标会话及项目、待添加数量、已在草稿数量和“添加所选图片”。仅对未附加
图片显示可勾选项；已附加卡显示“已在此会话草稿”与“从草稿移除”。取消勾选只取消本次
待添加选择，不删除已经附加的图片。无选择时禁用添加并说明原因，无默认全选行为。

添加只将选中的图片复制为目标草稿中的视觉附件，不发送消息、不附带整份知识库正文、不
自动启用知识库，也不重跑 OCR。成功后清除已提交勾选，显示已附加状态，提供“前往会话”
并通过一次应用通知反馈；失败保留勾选和原草稿，操作条就地显示原因，不重复通知。

同一来源结果的同一 imageId 加入同一草稿是幂等操作。点击两次或从正文和图片面板重复
添加都只产生一个附件；已发送后在新一条草稿中可再次选择。重新解析生成的新图片不按
文件名、页内键或视觉相似度与旧图片合并，也不自动替换草稿中的旧副本。

### 4.2 目标会话

从聊天当前草稿打开时，目标为该草稿；从历史附件打开时，目标为当前可编辑草稿，头部明确
区分来源消息与目标。知识库有有效活动会话时显示“添加到：会话名”，并保留其草稿文字。
浏览知识库不会自动改变活动会话或把知识库归属当作目标项目。

没有可编辑活动会话、会话已删除或当前为不可编辑消息通道时，保留图片选择，操作条显示
“选择会话后添加”，提供“选择会话”和“新建会话”。选择复用应用的项目与最近会话导航信息，
新建沿用现有 `startNewConversation` 的项目限制与空会话复用规则；该函数当前会切到聊天，
实现时须补齐目标会话返回和预览恢复接线，不能直接调用后假定选择仍在。需要先选可创建项目时在同一流程
显示原因和项目入口。新建或选择后回到预览核对目标，用户点击添加才复制，不自动发消息。
取消目标选择保留图片选择，不创建空附件。

提交时冻结显示的目标 conversationId。异步期间切换到其他会话不改变归属，完成提示带原
目标名称；目标已删除则失败并清理本次复制。重新打开预览按当前目标重新计算已附加状态。

### 4.3 发送与移除

选出图片的卡片显示“文档名 · 第 N 页 · 图片 M”，副标题为“文档插图 · 图片输入”。来源
跳转在原结果仍存在时可用；原结果删除后仍显示来源文字，副本照常打开与发送。

当前草稿本来含父文档时，父文档只提供一次解析文本，选出的图片分别占普通图片附件位置；
不为每张图片再次拼入父文档全文。移除父文档不级联删除已复制图片，反馈“已移除文档，
所选图片仍在草稿中”；移除图片不删父文档、不改知识库。移除只释放对应草稿引用，已发送
或队列仍引用的资源保留。数量按父文档和每个图片附件分别计数。

添加前和发送前均核对共享附件数量、容量和本次模型与 Runtime 图片能力，详见
[L-I3 至 L-I5](./logic-design.md#选图与发送)。超限拒绝整个本次选图批次并保留选择，列出
当前占用和可调整项，不能只取前几张。能力不匹配不丢图：草稿可保留图片，发送阻止并给出
“切换模型或 Runtime”“提取图片文字”“移除图片”。切换入口返回后保留草稿并重新校验。
活动回复期间沿用已有模型选择锁定规则，图片仍可进入下一条草稿，不能借预览绕开该锁定。
能力失配的队列项沿用队列的可恢复错误呈现，提供“恢复到草稿”供修改。恢复合并保留原
草稿，超限时队列与草稿均不改变并提示先整理草稿；具体合并规则见 L-H7。

## 5. 普通图片与文档附件状态

普通图片默认显示原图缩略图、“图片输入”及“提取图片文字”次操作。是否允许发送由实际
生效模型和 Runtime 共同决定，未知能力显示“尚未确认图片输入能力”，不能当作支持。
支持视觉也允许明确 OCR。OCR 中显示“正在提取文字”和取消，成功后同一附件变为
“原文件名 · 提取文字”，持续显示“仅发送提取文字，原图保留”，可查看正文和打开原图。
原始文件名不被磁盘重命名；来源与发送方式独立保存。“改为发送原图”恢复图片模式并重新
校验能力，不需要重新 OCR。失败、取消或没有文字时保持原先发送方式，不声称转换完成。
文档选出的图片执行 OCR 时采用相同交互，并保留文档、页码、图片序号来源。

| 附件状态 | 显示及操作 | 发送条件 |
| --- | --- | --- |
| 读取、解析、校验、保存中 | 文件名、阶段、批次序号、已知页数、取消 | 本批完成前阻止发送及重复导入，草稿文字可继续编辑 |
| 完整结果 | “解析完成”、页数、文字量、已保存图片数；查看解析结果、打开原件、移除 | 持久化和能力校验通过 |
| 部分结果 | “部分解析：第 N 页 OCR 失败”等持续提示；查看、重试、移除 | 仅逻辑允许的自动聊天结果可发送，发送内容携带不完整说明；不弹重复确认 |
| 仅图片结果 | “仅图片，无可发送正文”；查看和选择图片 | 选择至少一张该结果的图片或其提取文字后可发送；父文档保留来源并占附件位置，但不生成空文本上下文；也可移除父文档后单独发图片 |
| 失败或取消 | 具体原因或“已取消”；重试、移除 | 不可发送该项；批次回滚后保留失败摘要和重新选择入口 |
| 中断后重启 | “解析已中断”；从已保存原件重试，原件未保存则重新选择 | 不自动恢复 HTTP 推理，不把未完成状态变成成功 |
| 旧附件缺少资源 | “此附件未保存解析结果”；重新添加文件 | 不将旧元数据当成新的可恢复资源 |

导入仍遵守既有批次回滚：失败或取消时移除本批新增的未提交附件，保留之前草稿。失败摘要
不是可发送卡片。已添加附件重解析失败则保留其旧卡片，不适用首次导入回滚。取消停止后续
客户端请求；文案不承诺服务端 GPU 任务立即停止。取消生成与取消解析不同，前者不删除
已提交附件。入队保存失败保留草稿，队列显示不得早于资源持久化完成。

## 6. 知识库与生命周期呈现

DocumentsView 的文档操作增加“查看解析结果”，在新增文档详情区域呈现共享预览，保留来源、
同步、任务和 chunk 管理入口。图片预览不建立图片向量索引。正文页码与现有 chunk 来源
定位相连，图片选择不依赖该库是否已启用聊天检索。

完整索引或高保真缺页、缺图、重组失败时，本次任务标失败；旧文档仍可检索并显示“上次
结果仍可用”。首次导入失败没有可用旧结果时显示失败与重试，不能出现已索引成功标记。
删除文档或来源沿用危险操作确认，说明知识库派生资源会清理；已经复制到会话的图片不受
影响。删除聊天会话遵循会话删除流程，不在图片预览再实现平行删除系统。

草稿和队列恢复后仍能打开原图与解析结果。移除队列项仅释放该项引用，取消生成保留消息
附件；资源清理结果不能仅凭卡片消失验收，文件及数据库检查见验收矩阵。

## 7. 响应式与无障碍

按容器可用宽度响应，助手工作栏展开后不能只看窗口宽度。宽布局图片格多列，窄布局单列，
操作条换行；知识库按根规范在窄窗口转为列表和详情单面板，并提供返回列表。设置继续使用
既有左右分类 Modal；预览 Modal 使用共享尺寸与外边距，不另设全屏页面。正文表格独立
横向滚动，不撑宽 Composer 或 Modal。200% 缩放时目标会话、警告、取消和发送仍可达。

PageTabs 保留 tablist、tab、tabpanel、aria-selected、游标焦点和方向键/Home/End。
Switch 用 `role="switch"`，图片选择保留 checkbox 语义；图片卡内选择与放大为独立焦点。
表单字段有持久标签，错误用 aria-describedby 关联；进度使用 polite 实时区域，只播报
阶段和有意义的页数变化，失败使用 alert。图片替代文字描述来源，不凭空生成内容描述。

Modal 初始聚焦关闭按钮，确认删除初始聚焦取消。Tab 循环、背景隔离、顶层 Escape 和焦点
返回使用既有辅助函数；触发卡片被删除时返回附件区或文档列表的稳定入口。整窗遮罩纳入
共享 no-drag 选择器，原生浏览器 viewport 使用既有遮挡机制，不靠提高 z-index。
主题和 reduced-motion 遵循全局设置，不仅凭颜色区别部分、失败与完整结果。

## 8. 完整验收矩阵

以下为产品验收要求，是否通过及验证层次以进度记录为准。场景细节见
[User Stories](./user-stories.md)，实现验证路径见 [技术设计](./http-paddleocr-vl-technical-design.md#实施与验证顺序)。

| 用例 | 覆盖与可观察结果 | 追溯 |
| --- | --- | --- |
| A-01 配置与升级 | 旧配置继续本地；来回切换保留两套配置及凭据；不安装本地模型即可用 HTTP；保存失败、未保存测试和离开保护可恢复 | FR-H1、H11、H12；US-H1、H8、H12 |
| A-02 工作流 | 聊天/知识库混合 PDF、图片型 PPTX、快速模式、高保真及纯图片分别走约定路径，保留真实页码 | FR-H2、I1、I4；US-H2、H8、I1、I6 |
| A-03 高级参数 | 页眉页脚正向开关、服务默认、空排除列表、其他标签往返不丢失；声明与实测分开；未知选项或模型缺失明确报错 | FR-H4、H7；US-H4、H9 |
| A-04 跨页整理 | 用能触发合并的样例验证表格、标题和 sourcePages；无变化、映射失败均如实显示，不把请求成功当质量通过 | FR-H5；US-H5 |
| A-05 预览 | 三入口共用正文/图片/详情；同名图片键不串页；HTML img/table、页码互跳、原件打开、历史配置、置信度缺省正确 | FR-H3、H7、H11、H12；US-H3、H12、H14 |
| A-06 失败与取消 | 401/429/5xx、超时、损坏/超限文件、URL 图片、缺页缺图、磁盘保存失败；自动聊天部分与严格工作流失败不同；取消停止后续请求且可重试 | FR-H3、H6、H9；US-H6、H7、H15 |
| A-07 显式 OCR | 支持视觉仍可提取文字；成功改名并明确仅发文字、原图可开；失败/取消/空文字保持原方式；改回原图重验能力 | FR-I1、I2、I3；US-I2、I3、I11 |
| A-08 文档选图 | 零默认选择、勾选与已附加区分、重复添加幂等；父文档文字仅一次；父文档/图片独立移除；重新解析不替换已复制图片 | FR-I5；US-I7、I8 |
| A-09 知识库选图 | 有活动会话、无会话、不可编辑通道、选择/新建取消、异步切会话；只加入明确目标草稿且不自动发消息或启用检索 | FR-I5、H10；US-I9 |
| A-10 能力与限制 | 模型支持但 Runtime 不支持、未知能力、切换后失配、队列恢复失配；普通附件与选图共用数量/容量检查，整批超限不静默截取 | FR-I1、I5；US-I2、I10 |
| A-11 持久化 | 发送/入队/草稿后重启，外部原文件移走，正文/原图/图片仍可开；解析中重启显示中断；入队失败保留草稿 | FR-H8、H9、I3；US-H10、H15、I4、I5 |
| A-12 替换与清理 | managed/reference 重解析失败保留旧 chunks；成功替换；移除草稿、队列、会话、项目、库来源均核对文件和 DB；KB 删除不损坏会话副本，其他有效引用保留 | FR-H9、H10、H11、I5；US-H11、H13、I8、I9 |
| A-13 测试隔离 | 测试不创建会话/知识记录，不提供选图入草稿；取消文件选择无副作用，关闭预览清理测试资产 | FR-H7、H12；US-H14 |
| A-14 界面质量 | 浅/深主题、宽/中/窄窗口与工作栏压缩、200% 缩放、纯键盘、嵌套 Modal、浏览器 viewport 遮挡、短窗口页签不收缩 | FR-H12、I5；US-H14、I12 |
| A-15 菜单与返回 | 全局解析配置与本机监控分离；附件菜单随草稿/历史/队列状态变化；设置直达返回保留选择；知识库“用于当前对话”不替代选图，新建目标后恢复预览 | FR-H1、H11、H12、I2、I5；US-H16、I9 |

跨平台、真实本地模型和远端 Runtime 的执行证据按现有仓库规则记录。Mock、静态稿和
健康检查均不能替代完整产品入口验收。