Ncurator/doc/prd/settings.md

Settings PRD

1. 文档定位

• 本文档是 Settings -> 通用 / 大模型 / 工作空间（含网页资料） / 向量模型 / 使用帮助 的产品规格来源，描述用户可见功能、操作逻辑、状态反馈、边界和验收标准。
• 设置页的用户可见行为、入口、反馈或结果发生变化时，必须同步更新本文。
• 后续实现、测试、评审和 AI 最终汇报都应引用本文中的需求编号与验收编号。

2. 产品目标

• 用户在设置页完成模型配置、工作地址与网页资料管理，以及向量模型下载；设置项变更即时保存并对后续 workbench 与 AI 运行稳定生效。

3. 范围

• 包含大模型可用服务配置的新增、编辑、删除，预设服务商与自定义配置两种形态。
• 包含工作地址的添加、包含检测、索引检查、索引更新、查看和移除。
• 包含全局网页资料的添加、检查更新、索引更新、打开和删除。
• 包含向量模型的列表加载、下载、进度展示和结果反馈。
• 包含设置页左侧栏中的官方使用帮助入口。
• 不包含 workbench 聊天、已修改文件回退逻辑。
• 不包含视觉风格与基础控件样式定义。

4. 术语

• 大模型配置：一条可供 workbench 使用的模型连接配置，包含预设服务商配置与自定义配置两种形态。
• 预设服务商配置：选择内置服务商并填写 API Key 创建的配置，名称固定为服务商名，地址由应用维护，同服务商仅一条。
• 自定义配置：用户完整填写名称、服务地址和 API Key 的配置。
• 工作空间：设置页中「文件地址森林 + 全局网页资料」的管理区域。
• 工作地址：一条本地目录根路径（workspace_source.root_path UNIQUE），无名称字段。
• 检查更新：读取当前真实数据，判断哪些文件或网页需要重新建立索引。
• 更新索引：只处理可索引或失败资料，把内容写入后续检索可用的本地索引。
• 网页资料：全局一份，由 URL 导入并抓取；UNIQUE(normalized_url)。
• 向量模型：本地检索与知识库能力依赖的嵌入模型。

5. 需求规则

• 需求编号使用 SET-<模块>-<三位序号>。
• 验收编号使用 SET-<模块>-<三位序号>-AC<序号>。
• 需求编号稳定后不因措辞微调而重排；只有功能被废弃时才标记为废弃。

6. 需求明细

6.0 通用设置

SET-GENERAL-001 AI 运行系统通知

• 系统行为：通用设置默认开启 AI 运行终态通知。开关写入 app_settings.system_notifications_enabled。AI 运行成功、失败、取消以及应用启动时恢复为失败的中断任务，均发送一次电脑系统通知；等待审批不发送通知。通知展示馆长 logo，内容只包含状态提示，不展示 AI 输出正文。
• 系统行为：点击系统通知后恢复应用窗口，并打开对应伙伴。关闭开关后不发送系统通知，但不影响 AI 运行和页面内状态。
• 验收：SET-GENERAL-001-AC1 默认开启；SET-GENERAL-001-AC2 四类终态各发送一次；SET-GENERAL-001-AC3 关闭后静默；SET-GENERAL-001-AC4 点击通知打开对应伙伴；SET-GENERAL-001-AC5 系统通知不可用时应用不崩溃；SET-GENERAL-001-AC6 通知展示馆长 logo。

SET-GENERAL-002 设置页窗口层与操作区

• 系统行为：Windows 设置页的原生窗口控制层独立位于业务内容上方；业务拖动区不遮挡侧栏、返回和页面操作按钮。非 Windows 平台保留页面顶部拖动区。
• 验收：
  • SET-GENERAL-002-AC1 Windows 原生标题栏高度为 36px，业务内容从标题栏下方开始，页面按钮区不落入原生控制层。
  • SET-GENERAL-002-AC2 设置页主内容和侧栏拖动区可命中，侧栏折叠/展开按钮为 no-drag 且仍可操作。

SET-GENERAL-003 错误日志入口

• 系统行为：应用遇到索引、向量模型运行、LanceDB、AI 运行、主进程或 Renderer 未捕获错误时，自动写入用户数据目录的 logs/app.log。日志只记录错误，单文件最多 2MB，超出后保留最新内容。日志包含时间、应用版本、系统信息、错误模块、必要上下文、错误信息和堆栈。
• 隐私边界：日志不得记录 API Key、聊天正文、模型回答、文件正文或完整绝对路径；索引错误只记录文件名或工作地址相对路径。
• 系统行为：通用设置展示“错误日志”说明和带文件夹图标的“打开”按钮。点击后打开日志目录；目录不存在时自动创建。用户可将 app.log 发给作者排查问题。
• 验收：SET-GENERAL-003-AC1 发生已捕获错误后生成或追加 app.log；SET-GENERAL-003-AC2 日志遵守隐私边界和 2MB 上限；SET-GENERAL-003-AC3 点击按钮会打开日志目录。

6.1 大模型配置

概念

• 预设服务商：应用内置维护 4 家服务商接入信息（DeepSeek、通义千问、小米 MiMo、智谱 GLM：默认 API 地址 / host / providerKind）。推荐模型与免费模型列表、展示名、价格档位与能力仅由官网 GET /api/v1/preset-models、GET /api/v1/free-models 下发（无密钥）；桌面以磁盘缓存为唯一兜底（约 6 小时 TTL，打开选模可后台刷新）。无缓存且拉取失败时预设区为空，不伪造内置模型种子。该模型目录由 Workbench 模型选择器消费（见 workbench PRD），本页只维护服务商配置。预设服务商配置的名称固定为服务商名，地址固定为本地 registry 默认地址，同服务商只允许一条配置。
• 自定义配置：由用户填写名称、服务地址和 API Key 的配置，名称不可与其他配置重复。
• 预设与自定义由共享层按「地址命中预设服务商且名称等于服务商名」推导，不落库。

SET-MODEL-001 页面加载与配置列表展示

• 系统行为：进入大模型页后自动拉取全部配置。该页面只管理可用服务，不维护默认、启用或当前状态。配置列表展示服务商图标与配置名称；自定义配置在名称旁展示「自定义」标签。
• 验收：
  • SET-MODEL-001-AC1 页面打开后可见配置列表，而不是停留在未初始化状态。
  • SET-MODEL-001-AC2 配置列表展示服务商图标、配置名称和脱敏后的 API Key。
  • SET-MODEL-001-AC3 自定义配置名称旁展示「自定义」标签，预设配置不展示该标签。

SET-MODEL-002 新增与编辑配置

• 系统行为：新增和编辑共用同一弹框，表单依次为类型（推荐 / 自定义）、服务商或名称与地址、API Key。新增默认选中「推荐」；编辑默认落在当前配置所属类型。
  • 推荐类型：通过纯下拉选择预设服务商，选项带图标与名称；已配置服务商禁用并标注「已配置」；不展示名称输入框，配置名称由应用固定为服务商名，地址固定为目录默认地址，只要求填写 API Key。编辑推荐配置时服务商下拉可改，改为其他服务商保存后仍为推荐类型。
  • 自定义类型：填写名称、模型服务地址和 API Key；名称不得与现有配置重复。
  • 保存前校验必填字段；弹框点击遮罩区域时保持打开，避免误触丢失输入。
• 验收：
  • SET-MODEL-002-AC1 新增弹框存在「类型（推荐 / 自定义）」单选且默认推荐；推荐类型无名称输入框，只要求下拉选择服务商并填写 API Key。
  • SET-MODEL-002-AC2 保存推荐配置后名称等于服务商名、地址为目录默认地址，同服务商只存在一条配置；已配置服务商在下拉中禁用并标注「已配置」。
  • SET-MODEL-002-AC3 自定义类型可填写名称、地址和 API Key；名称重复时保存被拦截。
  • SET-MODEL-002-AC4 编辑推荐配置服务商下拉可改，改为其他服务商保存后仍为推荐类型且未新增记录；编辑自定义配置带出当前完整值。
  • SET-MODEL-002-AC5 必填字段不完整时，保存不会提交。
  • SET-MODEL-002-AC6 新增、编辑弹框点击遮罩区域时保持打开，用户输入不会因误触丢失；用户仍可通过取消或完成操作退出。

SET-MODEL-003 删除配置

• 系统行为：删除配置后刷新列表并移除对应记录。
• 验收：
  • SET-MODEL-003-AC1 删除成功后，该配置不再出现在列表中。
  • SET-MODEL-003-AC2 删除失败时，界面会给出明确错误提示。

6.2 工作地址

设置页「工作空间」管理文件地址森林与全局网页资料。用户直接添加目录；树的顶层节点就是各地址。网页资料是全局一份，与文件地址并列。Workbench 发送门禁由伙伴是否已创建决定。

SET-WORKSPACE-001 页面加载

• 系统行为：进入工作空间页后自动拉取全部文件地址，详情区使用 文件 / 网页 两个 tab。文件 tab 展示全部地址组成的目录森林；网页 tab 展示全局网页列表。
• 验收：
  • SET-WORKSPACE-001-AC1 页面打开后，文件地址树和网页 tab 会完成初始化，而不是依赖手动刷新。

SET-WORKSPACE-006 添加与移除文件地址

• 系统行为：文件 tab 只支持添加目录作为工作地址。候选路径已存在、或已落在现有地址内时，弹窗提示原因并拒绝；若新地址是现有地址的父路径，自动用父路径替换被包含的子根（不二次确认）。添加成功后立即保存并开始后台扫描；扫描结束后左侧可索引数与目录树状态同步刷新。目录树顶层即各地址，可先读取首层，扫描进度独立显示。
• 验收：
  • SET-WORKSPACE-006-AC1 点击添加目录后，可为资料范围新增一条工作地址。
  • SET-WORKSPACE-006-AC2 移除成功后，该地址从树中消失，其本地资料不会继续出现在后续资料范围选择里。
  • SET-WORKSPACE-006-AC4 添加地址后立即开始后台扫描，页面可见扫描进度；用户无需等待扫描完成即可看到顶层首层；扫描结束后左侧可索引数自动更新。
  • SET-WORKSPACE-006-AC5 候选路径已存在时弹窗提示「目录已添加」并拒绝；候选是现有地址的子路径时弹窗提示「目录已包含」并拒绝；候选包含现有子根时，父路径自动替换这些子根。

SET-WORKSPACE-007 空态与无文件提示

• 系统行为：无文件地址时展示空态；某个地址没有可显示文件时该地址节点展示局部空态。
• 验收：
  • SET-WORKSPACE-007-AC1 没有文件地址时，详情区不是空白页，而是明确提示还没有文件地址。
  • SET-WORKSPACE-007-AC2 某个地址没有可显示文件时，该地址节点显示明确局部空态。

6.3 本地文件视图与文件/网页分区

目录树刷新契约：进入工作空间页时读取一次全部文件地址的顶层；检查运行期间不重载目录树、不清空已显示节点；任务进入成功、失败或取消终态后，对当前已展示的目录层级刷新索引状态，保留展开/折叠，不把已折叠地址重新全部展开。手动点目录树刷新同样只更新已展示节点状态，不重置展开。扫描总数未知时显示活动状态，不显示静态 0% 进度。

更新索引逐文件处理期间只更新索引 job 进度，不广播目录刷新；job 终态统一触发一次目录树和摘要更新，刷新过程中保留旧节点与展开状态，返回后替换可见数据。刷新请求发生竞态时只接受最新响应，旧响应不得覆盖当前目录或 loading 状态。

左侧索引数字对全部文件地址合计：可索引数 = 全部地址的待索引与失败文件之和。

SET-WORKSPACE-003 检查目录变化

• 系统行为：点击“检查更新”后启动持久化后台任务，读取全部文件地址的真实目录并识别新增、变更、删除和未索引文件。执行中两个操作按钮保持可用（重复触发由后台任务去重承接），页面展示总进度；完成后同步刷新索引摘要和目录树状态。
• 验收：
  • SET-WORKSPACE-003-AC1 检查执行中，界面可见持久化进度信息，且“检查更新”和“更新索引”按钮保持可用。
  • SET-WORKSPACE-003-AC2 检查成功后，最近检查时间、状态和目录树同步刷新。
  • SET-WORKSPACE-003-AC3 检查执行中离开工作空间页再进入时，仍能恢复当前检查进度。
  • SET-WORKSPACE-003-AC4 程序关闭导致检查中断时，下次启动后该任务收敛为失败并退出执行中状态。
  • SET-WORKSPACE-003-AC5 文件检查分为两个持久化阶段：目录扫描阶段上报已扫描条目和已发现可索引文件数；索引比对阶段以发现的文件总数上报真实 N/M 百分比，不得为计算总数额外遍历目录。

SET-WORKSPACE-004 更新文件索引

• 系统行为：点击“更新索引”后启动持久化后台任务，先检查全部文件地址的目录变化，再处理新增、变更、可索引和失败文件。多个文件地址时按地址顺序执行，前一个地址进入终态后再启动下一个。执行中「检查更新」保持可用；「更新索引」不 disable、不加 loading，文案变为「取消」。进度条从点击后保持可见：目标总数尚未算出时显示活动进度条，不先闪文案再出条，也不在算出总数后继续停在准备中的空进度。算出总数后按已处理目标数 / 目标总数展示真实进度，每个目标（包括失败目标）只计一次；进度块标题右侧不显示百分比或 已处理/总数，当前处理文件文案保留在进度条下方。点「取消」先弹出确认框（点击遮罩不关闭）：确认停止后，尚未完成的将不会继续索引，已经完成的索引会保留。主按钮「停止」，次按钮「继续更新」。确认停止后，当前嵌入批次（每批最多 4 小段）跑完即停，不再继续该文件剩余批次；已写入的已索引与本次失败保留；未处理与当前未写完的文件回到处理前状态（needs_index 或原来的 failed），不因取消标失败；尚未启动的文件地址不再开始。若确认时任务已到成功或失败终态，停止为空操作，不把 job 改成 cancelled，不回退已索引。确认后按钮显示「停止中」直到任务终态；job 终态为 cancelled（任务已跑完则为原成功/失败）。向量模型未安装时“更新索引”禁用并提示先安装模型。界面只提供“检查更新”和“更新索引”。无文件地址时“检查更新”禁用；可索引数为 0 时“更新索引”禁用。不做暂停；用户可再次点击“更新索引”处理剩余可索引文件。
• 验收：
  • SET-WORKSPACE-004-AC1 更新索引时，实际处理范围会包含新增、变更、未索引和失败文件，而不是只停留在界面展示。
  • SET-WORKSPACE-004-AC2 更新成功后，可索引摘要和文件节点状态同步刷新；失败文件继续参与下次更新索引。
  • SET-WORKSPACE-004-AC3 更新索引执行中，界面可见持久化进度条和进度条下方的当前处理文件文案，「检查更新」保持可用，「更新索引」文案变为「取消」且可点。目标总数尚未算出时显示活动进度条；总数算出后按已处理目标数 / 目标总数展示真实比例，每个目标（包括失败目标）只计一次；进度块标题右侧不显示百分比或 已处理/总数。
  • SET-WORKSPACE-004-AC4 更新索引执行中离开工作空间页再进入时，仍能恢复当前索引进度。
  • SET-WORKSPACE-004-AC5 程序关闭导致索引中断时，下次启动后任务和索引中的文件都收敛为失败状态。
  • SET-WORKSPACE-004-AC6 向量模型未安装时，“更新索引”按钮禁用并展示“为什么不能更新索引”说明；安装模型后按钮恢复可用。
  • SET-WORKSPACE-004-AC7 更新索引运行期间不因逐文件完成而广播目录刷新；job 进入成功、失败或取消终态后，目录树只刷新一次，且不出现 loading/空态闪烁或展开状态被清空。
  • SET-WORKSPACE-004-AC8 单个文件索引失败时应用与 Settings 页面保持可用，失败文件保留 failed / last_error，其他文件状态不因该失败丢失。
  • SET-WORKSPACE-004-AC9 更新索引执行中，Workbench 的 kb_search / kb_list_documents 返回错误，提示正在更新知识库；检查更新不拦截检索；用户取消更新索引后检索恢复可用。
  • SET-WORKSPACE-004-AC10 无文件地址时「检查更新」禁用；可索引数为 0 时「更新索引」禁用。有地址但可索引为 0 时，「检查更新」仍可用。
  • SET-WORKSPACE-004-AC11 多个文件地址时，「更新索引」按地址顺序执行，等前一个地址任务终态后再启动下一个。
  • SET-WORKSPACE-004-AC12 更新索引执行中，「更新索引」按钮文案为「取消」且可点。
  • SET-WORKSPACE-004-AC13 点「取消」后出现确认框，说明尚未完成的将不会继续索引、已完成的会保留；选「继续更新」则任务继续跑。确认框不展示已完成/剩余数量。
  • SET-WORKSPACE-004-AC14 确认停止后，已完成的索引保留，剩余文件仍为可索引或原来的失败，不出现成批「含失败」。
  • SET-WORKSPACE-004-AC15 多个文件地址时，确认停止后尚未启动的地址不再开始更新索引。
  • SET-WORKSPACE-004-AC16 确认停止时正在处理、尚未写完的文件不落成已索引；当前嵌入批次跑完即停，不继续该文件剩余批次。
  • SET-WORKSPACE-004-AC17 确认框仍打开时任务已到成功或失败终态，再点「停止」不把 job 改为 cancelled，不回退已索引文件。

SET-WORKSPACE-009 索引速度

• 系统行为：文件 tab 与网页 tab 的「检查更新 / 更新索引」按钮组上方提供「索引速度」区块，标题样式与「索引状态」一致，下一行用双按钮切换慢速 / 高速。旁侧问号说明两档差异。默认慢速。偏好写入 app_settings.knowledge_index_speed，两 tab 共用。切换后下次「更新索引」按新档位限制本地嵌入线程；慢速大约占用一半逻辑核并关闭 ORT spinning，高速只留 1～2 核给系统操作。文件或网页「更新索引」进行中禁用切换，任务终态后恢复；「检查更新」不锁定。
• 验收：
  • SET-WORKSPACE-009-AC1 默认选中慢速；刷新设置页后选择保持。
  • SET-WORKSPACE-009-AC2 问号说明：慢速占用电脑较少的资源来完成索引，完成速度会比较慢；高速全力使用电脑资源来完成索引，完成速度会比较快。
  • SET-WORKSPACE-009-AC3 文件 tab 与网页 tab 展示并保存同一全局档位。
  • SET-WORKSPACE-009-AC4 更新索引进行中禁用慢/高速；任务终态后恢复。检查更新不禁用。

SET-WORKSPACE-005 文件与网页分区

• 系统行为：详情区使用 文件 / 网页 两个 tab。文件 tab 左侧展示全部地址合计的可索引数与检查/更新操作；网页 tab 展示全局网页资料。
• 验收：
  • SET-WORKSPACE-005-AC2 文件 tab 中始终能查看可索引数；该数字对全部文件地址合计；可索引数包含失败文件，存在失败文件时在可索引块内以辅助文案提示失败数量。
  • SET-WORKSPACE-005-AC3 详情区使用 文件 / 网页 tab 直接切换两类资料管理区域，而不是跳到独立页面。

SET-WORKSPACE-008 目录树显示真实目录与索引状态

• 系统行为：目录树顶层即各文件地址，不依赖历史快照。进入文件 tab 时只读取各地址的第一层；顶层地址行可折叠/展开其下内容，默认展开；新添加目录成功后只展开该地址，其余顶层自动折叠。用户展开子目录时才读取该目录的第一层，已读取目录在当前页面缓存。目录树右上刷新、以及更新索引/检查更新终态后的刷新，只重读当前已展示层级并更新索引状态，不改变展开折叠，不出现空态闪烁。目录结构始终来自本机文件系统，索引库仅补充当前可见文件的状态。当前支持索引 .doc、.docx、.pdf、.md、.markdown、.txt、.xlsx、.xlsm、.xltx、.xltm；Excel 只索引文件名、文档标题与工作表名等元数据，不索引单元格内容。文件项只展示文件名和状态 tag。顶层行尾提供删除。
• 可见性规则：任意层级中名称以 . 开头的文件或目录均不展示；除此之外不维护额外目录黑名单，node_modules 等目录正常可见，但不会因进入页面而被递归读取。
• 验收：
  • SET-WORKSPACE-008-AC1 用户能在目录树中看到当前真实目录结构，顶层节点就是各文件地址，而不是过期快照。
  • SET-WORKSPACE-008-AC2 支持索引的文件节点会展示索引状态，不支持索引的文件不会伪装成可索引文件。
  • SET-WORKSPACE-008-AC4 各地址首次读取显示加载反馈；展开子目录时仅该目录显示加载反馈，读取失败可重试，且不会显示为“空目录”。
  • SET-WORKSPACE-008-AC5 目录树不提供「全部展开 / 全部折叠」入口；顶层地址行可单独折叠，其下子目录仅由用户逐项展开；新添加成功后只展开该地址，其余顶层折叠。
  • SET-WORKSPACE-008-AC6 点击目录树右上刷新后，已展开/折叠状态保持不变，已展示节点的索引状态会更新。

6.4 全局网页资料视图

网页资料是全局一份。同一规范化 URL 只保留一条（UNIQUE(normalized_url)）。

SET-WEB-001 页面加载与统一布局

• 系统行为：进入工作空间页后，网页 tab 自动拉取全局网页资料列表；网页 tab 使用与文件 tab 同构的双栏布局：左侧索引状态和操作，右侧网页列表。
• 验收：
  • SET-WEB-001-AC1 打开网页 tab 后，全局网页资料列表和索引摘要完成初始化。
  • SET-WEB-001-AC2 网页 tab 左侧始终显示可索引数和核心操作按钮；可索引数包含失败网页，存在失败网页时在可索引块内以辅助文案提示失败数量。
  • SET-WEB-001-AC3 网页 tab 右侧始终显示网页列表，而不是单条详情页。

SET-WEB-002 添加网页资料

• 系统行为：添加弹窗支持一次输入多行 URL，每行一条。提交后按规范化 URL 去重并写入 可索引 状态，关闭弹窗并刷新列表；实际抓取在「更新索引」时执行。
• 验收：
  • SET-WEB-002-AC1 输入为空时，提交会被拦截，并提示至少输入一个 URL。
  • SET-WEB-002-AC2 提交成功后，提示“网页已添加，等待索引”，输入内容被清空。
  • SET-WEB-002-AC3 提交成功后，添加弹窗关闭，且全局网页资料列表完成刷新。
  • SET-WEB-002-AC4 添加网页资料弹窗点击遮罩区域时保持打开，已输入 URL 不会因误触丢失。

SET-WEB-003 检查网页更新

• 系统行为：点击“检查更新”后启动持久化后台任务，检查全局网页是否变化。执行中两个操作按钮保持可用（重复触发由后台任务去重承接）；变化网页标记为 可索引，不直接重建索引。无网页列表时“检查更新”禁用。
• 验收：
  • SET-WEB-003-AC1 检查执行中，界面可见持久化进度信息，且“检查更新”和“更新索引”按钮保持可用。
  • SET-WEB-003-AC2 检查成功后，网页列表的状态会刷新。
  • SET-WEB-003-AC3 检查执行中离开网页 tab 再进入时，仍能恢复当前检查进度。
  • SET-WEB-003-AC4 程序关闭导致检查中断时，下次启动后该任务收敛为失败并退出执行中状态。
  • SET-WEB-003-AC5 无网页列表时「检查更新」禁用；有网页后即使可索引为 0，「检查更新」仍可用。

SET-WEB-004 更新网页索引

• 系统行为：点击“更新索引”时启动持久化后台任务，仅对全局列表中状态为 可索引 / 爬取失败 / 索引失败 的网页执行爬取和索引更新；有抓取动作时进度块标题展示“抓取网页”，下方阶段文案保留“步骤 1/2 抓取网页：N/M”；进入索引阶段时标题展示“建立索引”，下方保留“步骤 2/2 建立索引：N/M”；无抓取动作时直接展示建立索引阶段。执行中「检查更新」保持可用；「更新索引」不 disable、不加 loading，文案变为「取消」。进度条从点击后保持可见：目标总数尚未算出时显示活动进度条；算出后按已处理目标数 / 目标总数展示真实进度，每个目标（包括失败目标）只计一次；进度块标题右侧不显示百分比或 已处理/总数，当前阶段处理文案保留在进度条下方，不得继续停在准备中的空进度。点「取消」先弹出确认框（点击遮罩不关闭）：确认停止后，尚未完成的将不会继续索引，已经完成的索引会保留。主按钮「停止」，次按钮「继续更新」。确认框不展示已完成/剩余数量。确认停止后，当前嵌入批次跑完即停；已完成的网页保留；未完成的回到进入本轮前的 可索引 / 爬取失败 / 索引失败，不因取消标成新的失败。若确认时任务已到成功或失败终态，停止为空操作。job 终态为 cancelled（任务已跑完则为原成功/失败）。向量模型未安装时“更新索引”禁用并提示先安装模型。可索引数为 0 时“更新索引”禁用。不做暂停；用户可再次点击“更新索引”处理剩余可索引网页。
• 验收：
  • SET-WEB-004-AC1 更新索引执行中，网页状态会进入 爬取中 或 索引中。
  • SET-WEB-004-AC2 更新成功后，网页状态变为 已索引，抓取时间同步刷新。
  • SET-WEB-004-AC3 更新失败时，会区分 爬取失败 与 索引失败。
  • SET-WEB-004-AC4 更新索引执行中，界面可见抓取/索引分阶段进度条和进度条下方的当前阶段处理文案，「检查更新」保持可用，「更新索引」文案变为「取消」且可点。目标总数尚未算出时显示活动进度条；总数算出后按已处理目标数 / 目标总数展示真实比例，每个目标（包括失败目标）只计一次；进度块标题右侧不显示百分比或 已处理/总数。
  • SET-WEB-004-AC5 更新索引执行中离开网页 tab 再进入时，仍能恢复当前阶段和进度。
  • SET-WEB-004-AC6 程序关闭导致网页索引中断时，下次启动后任务收敛为失败，爬取中 网页变为 爬取失败，索引中 网页变为 索引失败。
  • SET-WEB-004-AC7 向量模型未安装时，“更新索引”按钮禁用并展示“为什么不能更新索引”说明；安装模型后按钮恢复可用。
  • SET-WEB-004-AC8 更新网页索引执行中，Workbench 的 kb_search / kb_list_documents 返回错误；检查更新不拦截检索；用户取消更新索引后检索恢复可用。
  • SET-WEB-004-AC9 可索引数为 0 时「更新索引」禁用。
  • SET-WEB-004-AC10 更新索引执行中，「更新索引」按钮文案为「取消」且可点。
  • SET-WEB-004-AC11 点「取消」后出现确认框，说明尚未完成的将不会继续索引、已完成的会保留；选「继续更新」则任务继续跑。确认框不展示已完成/剩余数量。
  • SET-WEB-004-AC12 确认停止后，已完成的网页索引保留，未完成网页回到进入本轮前状态，不出现成批新失败。
  • SET-WEB-004-AC13 确认停止时正在抓取或索引、尚未写完的网页不落成已索引；当前嵌入批次跑完即停。
  • SET-WEB-004-AC14 确认框仍打开时任务已到成功或失败终态，再点「停止」不把 job 改为 cancelled，不回退已索引网页。

SET-WEB-005 列表项信息、外链打开与删除

• 系统行为：网页列表项展示标题、URL、状态和抓取时间；点击“打开”用系统浏览器打开；删除后刷新全局列表。
• 验收：
  • SET-WEB-005-AC1 列表项展示标题、URL、状态和抓取时间。
  • SET-WEB-005-AC2 点击“打开”后，用系统浏览器打开原网页，而不是进入本地文档预览。
  • SET-WEB-005-AC3 删除成功后，该网页资料从列表中消失。

6.5 向量模型管理（列表 / 下载 / 删除）

SET-VECTOR-001 模型列表加载

• 系统行为：进入向量模型页后自动拉取模型列表，并展示名称、说明、标签和是否已安装。
• 验收：
  • SET-VECTOR-001-AC1 模型列表加载成功后，可区分已安装模型与可下载模型。
  • SET-VECTOR-001-AC2 获取模型列表失败时，页面给出明确错误提示。

SET-VECTOR-002 单任务下载与进度显示

• 系统行为：同一时间只允许一个下载任务进行；下载过程中展示百分比、当前文件和文件完成数。下载使用用户选定或默认的下载源（当前可选 ModelScope 镜像与 HuggingFace 镜像），同一下载任务全程使用同一源，不会自动切换。
• 验收：
  • SET-VECTOR-002-AC1 已有下载任务时，其他模型的下载入口不可继续触发新任务。
  • SET-VECTOR-002-AC2 下载过程中，界面持续更新当前文件、完成数和总进度。
  • SET-VECTOR-002-AC3 离开向量模型页面不会中断下载；再次进入页面时恢复当前文件、完成数和总进度。
  • SET-VECTOR-002-AC4 应用启动时若存在进行中的下载快照，后台自动恢复任务，页面展示恢复后的进度，并沿用快照中的下载源。

SET-VECTOR-003 下载完成与错误收敛

• 系统行为：下载完成后自动刷新列表并切换到已安装状态；下载失败时记录错误并给出反馈，同时提供更换下载源重新下载的入口。下载失败后残留的未完成文件会被清理，更换源后的重新下载为完整下载。
• 验收：
  • SET-VECTOR-003-AC1 下载完成后，对应模型显示为“已安装”，不再显示下载按钮。
  • SET-VECTOR-003-AC2 下载失败时，界面提示失败原因，并退出下载中状态。
  • SET-VECTOR-003-AC3 下载失败后，失败提示区域展示“更换源下载”入口。
  • SET-VECTOR-003-AC4 点击“更换源下载”后弹出源选择对话框，列出全部可选下载源并标注最近失败的源；确认选择后从该源重新完整下载。
  • SET-VECTOR-003-AC5 取消源选择时保持失败状态，不触发重新下载。
  • SET-VECTOR-003-AC6 下载失败不会自动切换到其他源；换源只由用户主动选择触发。

SET-VECTOR-004 模型删除确认与反馈

• 系统行为：已安装模型或下载中的模型均可点击“删除”：删除前先显示确认提示；确认后取消进行中的下载并移除本应用模型目录中的已下载文件；取消确认时保持原状态。模型不跨安装复用，删除后重新下载为完整下载。
• 验收：
  • SET-VECTOR-004-AC1 用户确认删除且删除成功后，模型回到可下载状态。
  • SET-VECTOR-004-AC2 删除失败时页面提示失败原因，并保持已安装状态。
  • SET-VECTOR-004-AC3 点击删除入口后先出现确认弹框，不立即执行删除。
  • SET-VECTOR-004-AC4 取消确认后不执行删除，也不进入成功或失败结果态。
  • SET-VECTOR-004-AC5 下载中的模型同样提供删除入口；确认后取消当前下载、移除已下载文件，模型回到可下载状态。
  • SET-VECTOR-004-AC6 下载中删除成功不提示“下载失败”等错误信息；确认弹框说明删除将取消当前下载。
  • SET-VECTOR-004-AC7 删除成功后重新点击下载，必须为真实完整下载，而非复用其他位置的模型副本。

6.6 使用帮助

SET-HELP-001 设置页使用帮助入口

• 系统行为：设置页左侧栏在“向量模型”下方展示同级、同样式的“使用帮助”入口，点击后通过系统默认浏览器打开国内官网中文使用手册 https://www.guanzhangai.cn/zh/manual，当前设置页保持不变。
• 验收：
  • SET-HELP-001-AC1 “使用帮助”入口紧接在“向量模型”下方，使用与其他设置菜单项一致的样式，并具有“查看使用帮助”的可访问名称。
  • SET-HELP-001-AC2 点击“使用帮助”后调用系统外链能力打开官方中文使用手册，不改变当前设置页路由。

7. 非目标

• 不定义 workbench 中的聊天、资料范围和已修改文件回退逻辑。
• 不定义页面视觉风格、配色 token 或圆角规则。
• 不定义底层扫描、抓取、下载服务的内部实现细节。

附录：废弃编号

编号保留，不再作为现行验收。

编号	原能力
SET-WORKSPACE-001-AC2	默认选中某个具名工作空间
SET-WORKSPACE-002	添加具名工作空间弹窗
SET-WORKSPACE-005-AC1	工作空间头部只展示名称与操作
SET-WORKSPACE-005-AC4	左侧具名列表同时表达文件数与网页数
SET-WORKSPACE-006-AC3	设置页承担 Workbench 发送门禁提示
SET-WORKSPACE-008-AC3	文件视图内直接设置当前工作空间地址