Ncurator/doc/prd/settings.md

Settings PRD

1. 产品目标

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

2. 范围

• 包含大模型可用服务配置的新增、编辑、删除，预设服务商与自定义配置两种形态。
• 包含工作地址的添加、包含检测、索引检查、索引更新、查看和移除。
• 包含全局网页资料的添加、检查更新、索引更新、打开和删除。
• 包含向量模型的列表加载、下载、进度展示和结果反馈。
• 包含设置页左侧栏中的官方使用帮助入口。
• 包含按伙伴、目录与截止日期清理运行缓存及文件修改历史。

3. 术语

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

4. 需求明细

4.1 通用设置

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

• 系统行为：通用设置默认开启 AI 运行终态通知。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-002-AC3 各设置页使用居中且统一限宽的内容（与大模型页一致）、简洁页头和分组面板；通用页按「应用偏好」（语言、官方服务线路、AI 完成通知）和「数据与诊断」（错误日志、伙伴缓存）组织。中英文说明及操作在窄窗口完整可见，树和列表仍可独立滚动。

SET-GENERAL-003 错误日志入口

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

SET-GENERAL-004 清理伙伴的缓存数据

• 系统行为：通用设置展示「伙伴缓存」及「管理缓存」，打开 680px 弹框。选择伙伴（支持全部伙伴）、勾选临时脚本、工具结果、附件与临时资源、文件修改历史、选择截止日期后，展示按日期和类型汇总的待清理数量及占用空间。默认当前伙伴、四类目录、当天日期；每次打开按当天重置截止日期。伙伴选中项与下拉项显示对应形状、颜色的小人头像及工作台同款动画，「全部伙伴」显示群组图标。弹框适配窗口高度，标题与底部汇总固定，筛选区紧凑排列，待清理列表独立滚动，小高度窗口允许内容区滚动。列表从旧到新，无逐文件列表或版本预览。
• 目录说明：临时脚本为 AI 执行任务时编写的临时脚本；工具结果为过长工具输出的完整文本；附件与临时资源为粘贴附件、读图缓存、文档渲染图片及网页截图；文件修改历史为修改前备份与差异预览，清理后无法回退。每行使用统一 BsFolder2Open 文件夹图标打开所选伙伴对应的完整目录，不受勾选或日期影响；全部伙伴时禁用，目录不存在提示暂无数据，不创建空目录。
• 时间规则：脚本/工具结果/资源按最后更新时间，互相依赖的产物按组内最新时间；修改历史按该次修改发生时间，整条记录和资源一起清理。截止日期取当天 00:00，严格删除早于截止时间的数据；快捷选择只提供「7 天前」「30 天前」，允许选择明天以清理今天的数据。
• 范围说明：「清理所选目录中截止日期前的数据。伙伴、聊天记录和工作目录文件等不会被删除。」只清理所选伙伴的对应缓存与修改历史，不回退实际文件，不触碰模型、索引、配置和未选伙伴。草稿正在使用的附件自动跳过；未选或未到截止时间的修改历史完整保留。运行、提交、收尾、清理中的伙伴不能再次清理；清理期间拒绝新任务。
• 统计反馈：分类行显示所选伙伴各目录的实际总占用，不受截止日期或目录勾选影响；待清理列表及底部预计释放只计算当前日期和勾选范围内可清理的数据。统计中显示「统计中」，读取失败显示错误，不能以 0 B 代替；空状态区分没有缓存、已有缓存但不符合筛选条件、未选择清理内容。日期与数量使用完整文案，不拼接粘连。
• 清理前显示确认窗口，说明范围、空间和不可恢复性；关闭、取消、Escape、遮罩均无副作用。执行期间禁用重复确认及取消，失败保留确认框并显示错误以便重试。执行前再次检查时间、草稿附件、运行状态和清理范围，不跟随符号链接。完成刷新预览并报告释放空间；部分失败如实反馈，保留可重试状态。
• 验收：
  • SET-GENERAL-004-AC1 入口、弹框标题和范围说明使用上述文案。
  • SET-GENERAL-004-AC2 伙伴及四类目录可选，伙伴头像与动画一致，说明可见，无逐文件列表。
  • SET-GENERAL-004-AC3 默认当天，7/30 天前快捷选项改变预览，仅清理严格早于截止时间的数据。
  • SET-GENERAL-004-AC4 总占用不随筛选变化，待清理汇总从旧到新，数量/空间/总计一致；统计中、失败与不同空状态可区分，无候选时禁用清理。
  • SET-GENERAL-004-AC5 文件夹图标打开正确目录；全部伙伴时禁用，缺失目录提示暂无数据。
  • SET-GENERAL-004-AC6 清理先确认，取消不删除；完成后刷新并报告释放空间。
  • SET-GENERAL-004-AC7 伙伴、聊天记录、配置、工作目录文件及未选伙伴数据保留。
  • SET-GENERAL-004-AC8 修改记录、备份与审核材料同步清理，保留时仍能精确回退。
  • SET-GENERAL-004-AC9 运行与清理互斥，草稿附件自动跳过；未选或未到截止时间的修改历史完整保留。
  • SET-GENERAL-004-AC10 无效范围、符号链接和文件变化不造成越界删除；失败可重试且如实反馈。

SET-GENERAL-005 界面语言

• 系统行为：提供「跟随系统」「简体中文」「English」，默认跟随系统。匹配电脑首选语言列表中的已支持语言，无匹配时使用英文。设置即时保存，重启后统一生效，不强制打断运行中的任务；保存后明确提示重启生效。
• 中文界面品牌为「馆长」，英文界面为「NCurator」。页面、编辑器、菜单、业务提示和系统通知使用同一有效语言；聊天正文、AI 输出和用户内容不自动翻译。语言不改变服务线路、安装名称和更新渠道。
• 验收：SET-GENERAL-005-AC1 三个选项及默认行为正确；SET-GENERAL-005-AC2 保存、重启和升级后保留偏好；SET-GENERAL-005-AC3 生效范围包含通用组件和通知；SET-GENERAL-005-AC4 中文与英文布局可用，语言与线路独立。

SET-GENERAL-006 官方服务线路

• 系统行为：只提供「中国大陆」「国际」。没有有效配置时根据发行包初始化并保存：国内包为中国大陆，国际包为国际，无法识别发行标识时为中国大陆。已有有效配置不被重启、升级或重新识别发行包覆盖。
• 用户手动切换后即时保存，后续官方服务操作使用新线路，在途请求保持原入口。请求失败及重试不自动跨线路切换。设置不影响用户配置的模型地址，不改变固定的应用更新渠道。
• 验收：SET-GENERAL-006-AC1 只有两个选项且初始化正确；SET-GENERAL-006-AC2 手动值持久化，更新其他设置不覆盖；SET-GENERAL-006-AC3 新请求切换、在途请求固定、失败不换线；SET-GENERAL-006-AC4 界面语言与自动更新渠道独立。

4.2 大模型配置

概念

• 预设服务商：应用内置 DeepSeek、通义千问、小米 MiMo、智谱 GLM 四家接入信息；名称和地址由应用维护，同服务商只允许一条配置。本页管理服务连接，模型目录的选择与反馈见 Workbench 的 WB-COMPOSER-007。
• 自定义配置：由用户填写名称、服务地址和 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 删除失败时，界面会给出明确错误提示。

4.3 工作地址

设置页「工作空间」管理文件地址森林与全局网页资料。用户直接添加目录；树的顶层节点就是各地址。网页资料是全局一份，与文件地址并列。

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 某个地址没有可显示文件时，该地址节点显示明确局部空态。

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

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

更新索引逐文件处理期间只更新进度，不反复刷新目录树；任务终态统一刷新一次目录树和摘要。刷新期间保留旧节点与展开状态；连续操作的旧结果不能覆盖当前目录或当前加载状态。

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

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，文案变为「取消」。进度条从点击后保持可见：目标总数尚未算出时显示活动进度条，不先闪文案再出条，也不在算出总数后继续停在准备中的空进度。算出总数后按已处理目标数 / 目标总数展示真实进度，每个目标（包括失败目标）只计一次；进度块标题右侧不显示百分比或 已处理/总数，当前处理文件文案保留在进度条下方。点「取消」先弹出确认框（点击遮罩不关闭）：确认停止后，尚未完成的将不会继续索引，已经完成的索引会保留。主按钮「停止」，次按钮「继续更新」。确认停止后，当前一小批处理结束即停，不再继续该文件剩余内容；已完成的索引与本次失败保留，未处理或未写完的文件回到处理前状态，不因取消新增失败；尚未启动的文件地址不再开始。若确认时任务已到成功或失败终态，停止为空操作，保持原任务终态，不回退已索引。确认后按钮显示「停止中」直到任务终态；任务最终显示已取消；已经完成的任务保留原成功或失败状态。向量模型未安装时“更新索引”禁用并提示先安装模型。界面只提供“检查更新”和“更新索引”。无文件地址时“检查更新”禁用；可索引数为 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 更新索引运行期间不因逐文件完成而反复刷新目录树；任务进入成功、失败或取消终态后，目录树只刷新一次，且不出现加载态或空态闪烁或展开状态被清空。
  • SET-WORKSPACE-004-AC8 单个文件索引失败时应用与 Settings 页面保持可用，失败文件保留失败状态和原因，其他文件状态不因该失败丢失。
  • SET-WORKSPACE-004-AC9 更新索引执行中，Workbench 的知识库检索与资料列表查询 返回错误，提示正在更新知识库；检查更新不拦截检索；用户取消更新索引后检索恢复可用。
  • 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 确认框仍打开时任务已到成功或失败终态，再点「停止」保持原任务终态，不回退已索引文件。

SET-WORKSPACE-009 索引速度

• 系统行为：文件 tab 与网页 tab 的「检查更新 / 更新索引」按钮组上方提供「索引速度」，标题样式与「索引状态」一致，下一行用双按钮切换慢速 / 高速，旁侧问号说明差异。默认慢速，两 tab 共用并保存同一偏好，下一次更新索引生效。慢速使用较少电脑资源，高速优先索引速度。文件或网页更新索引期间禁用切换，操作后立即显示运行反馈，终态恢复；「检查更新」不锁定。
• 验收：
  • 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；DOCX/Excel/PPT/PDF 复用输入框原有彩色类型图标，MD/普通文件使用 react-icons 的 PiFileMdLight / PiFileTextLight 细线文档图标，目录使用线性图标，目录为 16px、文件为 18px，与 @ 候选一致，目录分别以 BsFolder / BsFolder2Open 表达收起/展开，箭头、图标与文字按层级固定对齐，未选中行无悬停底色。顶层行尾提供删除。
• 可见性规则：任意层级中名称以 . 开头的文件或目录均不展示；除此之外不维护额外目录黑名单，node_modules 等目录正常可见，但不会因进入页面而被递归读取。
• 验收：
  • SET-WORKSPACE-008-AC1 用户能在目录树中看到当前真实目录结构，顶层节点就是各文件地址，而不是过期快照。
  • SET-WORKSPACE-008-AC2 支持索引的文件节点会展示索引状态，不支持索引的文件不会伪装成可索引文件。
  • SET-WORKSPACE-008-AC4 各地址首次读取显示加载反馈；展开子目录时仅该目录显示加载反馈，读取失败可重试，且不会显示为“空目录”。
  • SET-WORKSPACE-008-AC5 目录树不提供「全部展开 / 全部折叠」入口；顶层地址行可单独折叠，其下子目录仅由用户逐项展开；新添加成功后只展开该地址，其余顶层折叠。
  • SET-WORKSPACE-008-AC6 点击目录树右上刷新后，已展开/折叠状态保持不变，已展示节点的索引状态会更新。
  • SET-WORKSPACE-008-AC7 文件类型和目录图标与工作台列表一致，Office/PDF 保持原有彩色专属图标，MD/普通文件/目录使用 react-icons，目录图标为 16px、文件为 18px，与 @ 候选一致，MD 与普通文件形状区分，目录展开/收起图形不同；普通行高、缩进和箭头/图标/文字对齐一致，未选中行不因悬停改变背景，状态 tag、刷新及懒加载操作保留。

4.5 全局网页资料视图

网页资料是全局一份，同一规范化 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，文案变为「取消」。进度条从点击后保持可见：目标总数尚未算出时显示活动进度条；算出后按已处理目标数 / 目标总数展示真实进度，每个目标（包括失败目标）只计一次；进度块标题右侧不显示百分比或 已处理/总数，当前阶段处理文案保留在进度条下方，不得继续停在准备中的空进度。点「取消」先弹出确认框（点击遮罩不关闭）：确认停止后，尚未完成的将不会继续索引，已经完成的索引会保留。主按钮「停止」，次按钮「继续更新」。确认框不展示已完成/剩余数量。确认停止后，当前一小批处理结束即停；已完成的网页保留；未完成的回到进入本轮前的 可索引 / 爬取失败 / 索引失败，不因取消标成新的失败。若确认时任务已到成功或失败终态，停止为空操作。任务最终显示已取消；已经完成的任务保留原成功或失败状态。向量模型未安装时“更新索引”禁用并提示先安装模型。可索引数为 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 的知识库检索与资料列表查询 返回错误；检查更新不拦截检索；用户取消更新索引后检索恢复可用。
  • 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 确认框仍打开时任务已到成功或失败终态，再点「停止」保持原任务终态，不回退已索引网页。

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

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

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

模型只由用户主动下载或恢复已有下载任务，知识库与索引不隐式下载。删除后知识库查询提示模型不可用，不终止聊天；重新安装后可恢复使用。工作地址与向量模型配置不阻止普通 AI 任务启动。

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 删除成功后重新点击下载，必须为真实完整下载，而非复用其他位置的模型副本。

4.7 使用帮助

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

• 系统行为：设置页左侧栏在“向量模型”下方展示同级、同样式的“使用帮助”入口，点击后先展示确认弹框，说明将通过系统默认浏览器打开官网使用帮助，并展示目标地址。官网域名按当前官方服务线路选择，手册路径按当前生效的界面语言选择；确认「打开官网」后才跳转，当前设置页保持不变。
• 验收：
  • SET-HELP-001-AC1 “使用帮助”入口紧接在“向量模型”下方，使用与其他设置菜单项一致的样式，并具有“查看使用帮助”的可访问名称。
  • SET-HELP-001-AC2 点击“使用帮助”先显示目标地址和跳转确认，确认后只调用一次系统外链能力，地址符合当前线路和生效语言，不改变设置页路由。
  • SET-HELP-001-AC3 取消、关闭、Escape 或点击遮罩均只关闭弹框，不调用系统外链能力；打开失败显示本地化错误并可重试。

5. 非目标

• 不定义 workbench 中的聊天、资料范围和已修改文件回退逻辑。
• 全局视觉、配色与基础控件规范由 UI 风格 维护；本 PRD 保留设置页专属展示与交互规格。
• 不定义底层扫描、抓取、下载服务的内部实现细节。