Ncurator/doc/prd/settings.md

Settings PRD

1. 文档定位

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

2. 产品目标

• 让用户在设置体系中完成模型配置、工作空间管理、网页资料管理和向量模型下载。
• 让资料入口、状态展示和关键动作在设置页内闭环，不依赖隐式状态。
• 让设置结果能稳定影响后续 workbench 和 AI 运行。

3. 范围

• 包含大模型配置的新增、编辑、删除和切换启用。
• 包含工作空间的添加、扫描、加载、查看和移除。
• 包含网页资料的添加、筛选、抓取刷新和删除。
• 包含向量模型的列表加载、下载、进度展示和结果反馈。
• 不包含 workbench 聊天、搜索和确认修改逻辑。
• 不包含视觉风格与基础控件样式定义。

4. 术语

• 大模型配置：一条可供 workbench 使用的模型连接配置。
• 工作空间：一个本地目录，允许被扫描、加载并进入资料范围。
• 扫描：刷新目录快照并识别可追踪节点。
• 加载：把支持文件切块并写入后续检索可用的缓存。
• 网页资料：由 URL 导入并抓取的外部网页内容。
• 向量模型：本地检索与知识库能力依赖的嵌入模型。

5. 需求规则

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

6. 需求明细

6.1 大模型配置

SET-MODEL-001 页面加载与当前配置识别

• 系统行为：进入大模型页后自动拉取全部模型配置，并识别当前激活配置。
• 验收：
  • SET-MODEL-001-AC1 页面打开后可见配置列表，而不是停留在未初始化状态。
  • SET-MODEL-001-AC2 当前激活配置在列表和页头摘要中都有明确标识。

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

• 系统行为：新增配置打开空表单；编辑配置打开预填表单；保存前执行表单校验。
• 验收：
  • SET-MODEL-002-AC1 新增时可填写配置名称、Base URL、模型名称和 API Key。
  • SET-MODEL-002-AC2 编辑时会带出当前配置值，而不是空表单。
  • SET-MODEL-002-AC3 必填字段不完整时，保存不会提交。

SET-MODEL-003 默认激活与启用切换

• 系统行为：当列表为空时，新增的第一条配置自动成为激活配置；用户也可手动把任意配置设为当前使用。
• 验收：
  • SET-MODEL-003-AC1 第一条新增配置保存后自动成为当前模型。
  • SET-MODEL-003-AC2 点击“启用”后，目标配置变成当前模型，原激活配置失去当前标记。

SET-MODEL-004 配置变更事件外溢

• 系统行为：保存当前激活配置或切换激活配置成功后，系统派发 check-llm-config 事件，通知其他页面刷新模型状态。
• 验收：
  • SET-MODEL-004-AC1 修改当前激活配置后，不需要重启页面即可触发其他页面刷新。
  • SET-MODEL-004-AC2 切换激活配置后，workbench 后续使用新的模型配置。

SET-MODEL-005 删除配置

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

6.2 工作空间管理

SET-WORKSPACE-001 页面加载与默认选中

• 系统行为：进入工作空间页后自动拉取工作空间列表、目录节点和默认展开状态；若存在工作空间且当前未选中任何一项，则自动选中第一条。
• 验收：
  • SET-WORKSPACE-001-AC1 页面打开后，列表和详情区会完成初始化，而不是依赖手动刷新。
  • SET-WORKSPACE-001-AC2 有工作空间时，详情区默认显示第一条工作空间的状态和摘要。

SET-WORKSPACE-002 添加工作空间

• 系统行为：点击添加工作空间后弹出目录选择器；选择目录成功时立即创建工作空间，并自动切到新项。
• 验收：
  • SET-WORKSPACE-002-AC1 用户取消目录选择时，不会创建工作空间，也不会提示失败。
  • SET-WORKSPACE-002-AC2 创建成功后，新工作空间立刻出现在列表中并成为当前选中项。

SET-WORKSPACE-003 扫描工作空间

• 系统行为：点击“先扫描”后刷新目录快照，并在列表项和详情区同步展示扫描进度与状态。
• 验收：
  • SET-WORKSPACE-003-AC1 扫描执行中，界面可见进行中的动作状态或进度信息。
  • SET-WORKSPACE-003-AC2 扫描成功后，最近扫描时间、状态和目录树同步刷新。

SET-WORKSPACE-004 按模式加载工作空间

• 系统行为：用户可在 full、presence_only、changes_only 三种模式之间切换，再点击“开始加载”执行加载。
• 验收：
  • SET-WORKSPACE-004-AC1 当前选中的加载模式会进入实际加载请求，而不是只停留在界面展示。
  • SET-WORKSPACE-004-AC2 加载成功后，最近加载时间、摘要统计和状态 badge 同步刷新。

SET-WORKSPACE-005 工作空间状态、错误与摘要

• 系统行为：详情区展示最近扫描时间、最近加载时间、最近错误、摘要统计和目录树。
• 验收：
  • SET-WORKSPACE-005-AC1 有错误时，详情区能直接看到最近一次错误，而不是只写控制台。
  • SET-WORKSPACE-005-AC2 详情区始终能查看目录数、文件数、已加载数和待处理数。

SET-WORKSPACE-006 打开路径与移除工作空间

• 系统行为：支持在系统中打开工作空间根目录，也支持移除工作空间；移除后该工作空间不再出现在资料范围和聊天范围中。
• 验收：
  • SET-WORKSPACE-006-AC1 点击“打开路径”后，会调用系统定位工作空间目录。
  • SET-WORKSPACE-006-AC2 移除成功后，该工作空间从列表中消失，且不会继续出现在后续资料范围选择里。

SET-WORKSPACE-007 空态、无文件和旧数据提示

• 系统行为：无工作空间时展示空态；目录树没有可追踪文件时展示空态；检测到旧本地导入残留时展示迁移提示。
• 验收：
  • SET-WORKSPACE-007-AC1 没有工作空间时，详情区不是空白页，而是明确提示用户先选择或添加。
  • SET-WORKSPACE-007-AC2 没有可追踪文件时，目录树区域显示“没有可追踪文件”。
  • SET-WORKSPACE-007-AC3 检测到旧本地导入数据时，页面顶部出现迁移清理提醒。

6.3 网页资料管理

SET-WEB-001 页面加载、筛选与默认选中

• 系统行为：进入网页资料页后自动拉取列表；过滤关键字对当前列表做本地筛选；若筛选结果非空且当前未选中任何一项，则默认选中第一条。
• 验收：
  • SET-WEB-001-AC1 页面打开后，来源列表和详情区完成初始化。
  • SET-WEB-001-AC2 输入关键字后，列表按标题、URL 或标准化 URL 过滤。
  • SET-WEB-001-AC3 过滤结果为空时，页面明确展示当前筛选为空，而不是表现成加载失败。

SET-WEB-002 添加网页资料

• 系统行为：添加弹窗支持一次输入多行 URL，每行一条；提交成功后把 URL 加入抓取队列，关闭弹窗并刷新列表。
• 验收：
  • SET-WEB-002-AC1 输入为空时，提交会被拦截，并提示至少输入一个 URL。
  • SET-WEB-002-AC2 提交成功后，提示“网页资料已加入队列”，输入内容被清空。

SET-WEB-003 单条重新抓取

• 系统行为：用户可对当前选中的网页资料执行重新抓取。
• 验收：
  • SET-WEB-003-AC1 单条抓取执行中，当前资料显示刷新中的状态。
  • SET-WEB-003-AC2 抓取成功后，最近抓取时间和状态刷新。

SET-WEB-004 当前列表的全部抓取

• 系统行为：点击“全部抓取”时，仅对当前列表中的网页资料并发触发重新抓取。
• 验收：
  • SET-WEB-004-AC1 当前列表为空时，不执行抓取，只提示“暂无可抓取的网页资料”。
  • SET-WEB-004-AC2 全部抓取结束后，会按成功数和失败数给出汇总反馈。

SET-WEB-005 详情展示、外链打开与删除

• 系统行为：详情区展示当前网页资料的状态、最近抓取时间和最近错误；点击 URL 用系统浏览器打开；删除后刷新列表。
• 验收：
  • SET-WEB-005-AC1 没有错误时，详情区明确显示“暂无抓取错误”。
  • SET-WEB-005-AC2 点击 URL 后，用系统浏览器打开原网页，而不是进入本地文档预览。
  • SET-WEB-005-AC3 删除成功后，该网页资料从列表中消失。

6.4 向量模型下载

SET-VECTOR-001 模型列表加载

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

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

• 系统行为：同一时间只允许一个下载任务进行；下载过程中展示百分比、当前文件和文件完成数。
• 验收：
  • SET-VECTOR-002-AC1 已有下载任务时，其他模型的下载入口不可继续触发新任务。
  • SET-VECTOR-002-AC2 下载过程中，界面持续更新当前文件、完成数和总进度。

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

• 系统行为：下载完成后自动刷新列表并切换到已安装状态；下载失败时记录错误并给出反馈。
• 验收：
  • SET-VECTOR-003-AC1 下载完成后，对应模型显示为“已安装”，不再显示下载按钮。
  • SET-VECTOR-003-AC2 下载失败时，界面提示失败原因，并退出下载中状态。

7. 非目标

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