Ncurator/doc/prd/workbench.md

Workbench PRD

1. 文档定位

• 本文档是 workbench 用户可见功能的产品规格来源。
• 本文档描述功能目标、范围、术语、交互要求、状态反馈、边界情况与验收标准。
• 任何改动只要改变了 workbench 的用户可见行为、交互流程、状态反馈或阻塞逻辑，必须同步更新本文。
• 后续实现、测试、评审和 AI 最终汇报都应引用本文中的需求编号与验收编号。

2. 产品目标

• 让用户通过对话，让 AI 完成搜索、分析、回答、整理和文档处理等任务。
• 让用户在需要时可以把本地文档作为任务上下文，让 AI 优先基于这些资料完成检索、分析、回答、编辑和新增受支持文件。
• 让 workbench 成为“发起任务、查看过程、处理中断、确认修改、继续执行”的主工作台。

3. 产品原则

• 本地文档是 AI 的重要上下文来源，但不是唯一能力边界；没有本地资料时，AI 仍可完成不依赖本地文档的通用任务。
• 当用户显式选择工作区或 @ 资料范围时，AI 应优先基于这些资料完成任务，而不是忽略用户给出的范围。
• workbench 的目标不是只做问答，而是帮助用户把任务推进到可交付结果。
• 用户可见能力边界必须明确可见，尤其是哪些资料可检索、哪些格式可确认落盘、哪些情况只能查看或分析。

4. 范围

• 包含会话管理。
• 包含 composer 输入、发送、取消与模式切换。
• 包含 @ 资料范围插入与维护。
• 包含 AI 运行中的审批、补工作区和未加载资料提示。
• 包含右侧内容面板中的搜索结果、文档查看与确认修改。
• 包含基于本地资料和网页资料的上下文使用。
• 不包含设置页中的资料配置逻辑。
• 不包含视觉风格与基础控件样式定义。

5. 当前能力边界

• workbench 可使用本地资料和网页资料作为搜索、分析、回答和执行任务时的上下文来源。
• 没有选择本地资料时，智能模式仍可处理不依赖本地文档的通用任务。
• 当用户显式提供本地资料范围时，问答与受支持文件任务应优先基于这些资料；若资料不足或未提供，智能模式可退回模型通用知识完成通用部分。
• 当前可由 workbench 直接确认落盘的受支持文件类型为 docx，包括修改现有 docx 与新建 docx；后续新增其他类型时，应在本清单中明确扩展。
• 对于其他资料格式，当前不承诺提供与受支持文件相同的确认修改落盘流程；AI 在具备工作区绑定或明确资料范围并在需要时经审批后，仍可通过通用执行能力尝试处理，但这不属于受支持文件确认落盘能力保证范围。
• 搜索模式只检索当前已加载的资料；未加载的本地文件不会进入纯搜索结果。
• 涉及本地执行、命令、脚本或文件修改的请求，必须先具备工作区绑定或明确的本地资料范围。
• 智能模式下经审批调用的 terminal 输出，应能被后续回答、分析和文件产物继续消费。

6. 术语

• 会话：一条独立的聊天上下文。
• 资料范围：通过 @ 插入的目录、文件或网页资料。
• 工作区绑定：当前选中的工作区，或来自 @ 的工作区范围。
• 搜索模式：只执行本地检索，不启动 AI 运行。
• 智能模式：启动 AI 运行，允许产生阻塞、审批和确认修改。
• 受支持文件：当前已具备确认落盘能力的文件类型；当前包括 docx，后续新增类型时在 PRD 中扩展。
• 目标文件：用户要求新建受支持文件时，确认通过后最终创建的文件路径。
• 确认修改：用户查看确认副本、执行提交前校验，并决定是否写回源文件或创建目标文件的流程。
• 直接写回：将确认副本中的修改覆盖写入源文件。

7. 需求规则

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

8. 需求明细

8.1 核心能力与约束

WB-CORE-001 本地资料是可选上下文，不是唯一前提

• 系统行为：workbench 允许 AI 在无本地资料前提下执行通用任务；当存在本地资料时，可将其作为任务上下文使用。
• 验收：
  • WB-CORE-001-AC1 用户未选择任何本地资料时，智能模式仍可正常发起不依赖本地文档的任务。
  • WB-CORE-001-AC2 系统不会把“没有本地资料”误表现为“workbench 不可用”。

WB-CORE-002 用户显式选择的资料范围必须影响执行

• 系统行为：当用户选择工作区或插入 @ 资料范围后，后续搜索、分析和执行应优先基于这些范围收敛。
• 验收：
  • WB-CORE-002-AC1 搜索模式下，显式资料范围会直接影响检索结果。
  • WB-CORE-002-AC2 智能模式下，系统不会忽略用户已经绑定的工作区或 @ 范围。

WB-CORE-003 当前受支持文件的确认落盘能力边界必须明确

• 系统行为：workbench 明确区分“可进入确认修改并确认落盘的受支持文件”和“可由 AI 自行尝试处理但不提供同等保证能力的其他任务”；当前受支持文件类型包括 docx。
• 验收：
  • WB-CORE-003-AC1 当前支持确认落盘的受支持文件类型列表明确可见，现阶段包括现有 docx 修改与新建 docx。
  • WB-CORE-003-AC2 不在当前受支持文件类型列表中的资料不会被伪装成可直接进入同一确认修改落盘流程的编辑或创建目标。

WB-CORE-004 本地资料优先，不足时可退回模型通用知识

• 系统行为：当用户发起问答或受支持文件编辑 / 新增任务，且当前已绑定工作区或插入本地资料范围时，系统优先基于这些资料完成任务；若用户未提供本地资料，或显式资料不足以覆盖通用部分，智能模式仍可退回模型通用知识继续完成，但不能忽略或违背用户已给定的本地资料。
• 验收：
  • WB-CORE-004-AC1 用户已绑定本地资料范围时，问答或受支持文件结果不会脱离这些资料另起一套无关内容。
  • WB-CORE-004-AC2 用户未提供本地资料，或资料不足以覆盖通用部分时，系统仍可继续给出基于模型通用知识的回答或内容，而不是无故阻塞。

WB-CORE-005 terminal 结果必须可被后续交付消费

• 系统行为：当智能模式任务在同一轮执行中调用 terminal 并获得结果后，后续 assistant 回答、分析结论和文件产物应体现从 terminal 输出中提取出的关键信息；若 terminal 结果不足或执行失败，系统应明确说明限制，而不是伪造后续内容。
• 验收：
  • WB-CORE-005-AC1 terminal 执行成功后，后续用户可见输出会体现关键命令结果，而不是只表现为“命令执行过”。
  • WB-CORE-005-AC2 terminal 输出不足或执行失败时，assistant 会明确说明无法从当前结果得到所需信息，而不是编造结论或文档内容。

WB-CORE-006 标准任务应能闭环到可交付结果

• 系统行为：当用户提供了足够上下文的标准任务，且当前不需要额外阻塞或确认时，workbench 应支持 AI 沿同一条任务链完成资料使用、必要执行和最终交付，而不是只停留在搜索结果、工具调用或过程提示。
• 验收：
  • WB-CORE-006-AC1 用户已提供足够上下文且无需额外阻塞时，系统能把标准任务推进到可消费的最终结果或明确产物，而不是停留在中间态。
  • WB-CORE-006-AC2 最终结果会体现用户显式给定的资料范围与执行得到的关键信息，不会把范围、执行结果和最终交付割裂开。

8.2 会话管理

WB-SESSION-001 无会话时自动创建初始会话

• 系统行为：页面初始化拉取会话列表；若列表为空，系统自动创建一条默认标题为“新对话”的会话并进入该会话。
• 验收：
  • WB-SESSION-001-AC1 首次进入且没有历史会话时，界面不会停留在空会话状态。
  • WB-SESSION-001-AC2 自动创建成功后，当前会话标题为“新对话”。

WB-SESSION-002 切换会话时重置当前运行态

• 系统行为：切换会话后，主区加载该会话消息，同时重置当前输入、@ 范围、待审批状态、待补工作区状态、右侧内容面板和确认修改状态。
• 验收：
  • WB-SESSION-002-AC1 点击其他会话后，消息区展示目标会话的历史消息。
  • WB-SESSION-002-AC2 切换后不会保留上一会话的搜索结果、确认修改或运行中的阻塞提示。

WB-SESSION-003 首条用户消息驱动标题更新

• 系统行为：当前会话若仍是默认状态，则在第一条用户消息发送后，将会话标题更新为该消息前 20 个字符。
• 验收：
  • WB-SESSION-003-AC1 第一条用户消息发送后，会话标题从“新对话”切换为该消息摘要。
  • WB-SESSION-003-AC2 之后继续发送消息时，不会再次自动改写已有标题。

WB-SESSION-004 删除会话后保持可继续操作

• 系统行为：删除会话后刷新列表；若删除的是当前会话，则先清空当前选中，再按最新列表回落到第一条或自动补新会话。
• 验收：
  • WB-SESSION-004-AC1 删除成功后，该会话不再出现在列表中。
  • WB-SESSION-004-AC2 删除当前会话后，页面仍保持可继续聊天，而不是落到不可操作状态。

WB-SESSION-005 同一会话里的续做保持任务主线

• 系统行为：用户在同一会话内基于上一轮结果继续提出局部修改、补写或 refinement 请求时，系统继续沿用当前会话上下文、上一轮产物和有效文件/确认修改入口，不把续做误当成全新无关任务。
• 验收：
  • WB-SESSION-005-AC1 续做请求发出后，系统会复用上一轮相关产物或上下文，而不是丢失已有任务主线。
  • WB-SESSION-005-AC2 续做完成后的结果体现的是对上一轮结果的继续修改或补充，而不是简单重复旧输出或重新开题。

8.3 Composer 输入与发送

WB-COMPOSER-001 发送前置条件

• 系统行为：只有当前存在会话、输入裁剪后非空且未处于发送中时，发送按钮才可执行。
• 验收：
  • WB-COMPOSER-001-AC1 纯空白输入不会触发发送。
  • WB-COMPOSER-001-AC2 发送中不会重复提交第二次相同操作。

WB-COMPOSER-002 键盘行为

• 系统行为：Enter 发送，Shift + Enter 插入换行。
• 验收：
  • WB-COMPOSER-002-AC1 按 Enter 后触发当前模式对应的发送逻辑。
  • WB-COMPOSER-002-AC2 按 Shift + Enter 后，输入区保留内容并新增换行，不触发发送。

WB-COMPOSER-003 智能模式发送路径

• 系统行为：智能模式发送时，系统先插入用户消息和一个空 assistant 消息壳，再启动 AI 运行并等待流式事件补全内容。
• 验收：
  • WB-COMPOSER-003-AC1 智能模式发送后，主区先可见用户消息与 assistant 占位消息。
  • WB-COMPOSER-003-AC2 AI 运行成功启动后，assistant 内容通过事件流逐步更新，而不是一次性静态替换。

WB-COMPOSER-004 搜索模式发送路径

• 系统行为：搜索模式发送时，不启动 AI 运行；主区插入用户消息和结果摘要消息，右侧进入搜索结果态。
• 验收：
  • WB-COMPOSER-004-AC1 搜索模式发送后，不产生 runId。
  • WB-COMPOSER-004-AC2 搜索成功后，右侧内容面板展示命中列表和命中详情。

WB-COMPOSER-005 本地执行请求必须先绑定工作区

• 系统行为：当输入明显涉及本地执行、命令、脚本或文件修改，且当前既无选中工作区也无工作区范围 token 时，发送被拦截并提示先补工作区。
• 验收：
  • WB-COMPOSER-005-AC1 这类请求在无工作区绑定时不会直接启动 AI 运行。
  • WB-COMPOSER-005-AC2 拦截提示会明确要求先选择工作区，必要时再通过 @ 指定目录或文件。

WB-COMPOSER-006 AI 运行取消

• 系统行为：智能模式在已有 runId 且仍在运行时，composer 提供取消入口，用于中止当前运行。
• 验收：
  • WB-COMPOSER-006-AC1 运行中才显示取消入口。
  • WB-COMPOSER-006-AC2 取消成功后，当前运行结束并给出已取消反馈。

8.4 模式切换

WB-MODE-001 模式切换不切页面

• 系统行为：智能和搜索共用同一页面骨架与同一输入区，切换模式不跳转页面，也不替换成第二套输入组件。
• 验收：
  • WB-MODE-001-AC1 切换模式后，当前输入内容仍保留。
  • WB-MODE-001-AC2 切换模式后，后续发送逻辑立即按新模式执行。

WB-MODE-002 搜索模式严格范围校验

• 系统行为：搜索模式下若已显式选择严格范围，但这些范围中没有任何已加载本地资料，则不允许执行纯搜索。
• 验收：
  • WB-MODE-002-AC1 严格范围为空命中时，搜索不会执行。
  • WB-MODE-002-AC2 用户会收到“当前搜索范围没有已加载的本地资料，无法执行纯搜索”的明确提示。

8.5 @ 资料范围

WB-SCOPE-001 @ 候选来源规则

• 系统行为：输入 @ 后，根据当前模式、当前关键字和当前工作区返回候选范围；未选工作区时只返回网页资料，选中工作区后同时返回工作区目录、文件和网页资料。
• 验收：
  • WB-SCOPE-001-AC1 未选工作区时，候选中不返回其他工作区的本地目录或文件。
  • WB-SCOPE-001-AC2 选中工作区后，候选中同时可出现本地范围和网页资料。

WB-SCOPE-002 @ 插入与删除规则

• 系统行为：候选可通过键盘或鼠标插入为内联 token；目录、文件和网页资料都可作为合法 token 插入；输入区支持多个已插入 token 共存；按 Backspace 或点击 token 删除入口可移除范围。
• 验收：
  • WB-SCOPE-002-AC1 目录、文件或网页资料插入成功后，范围以 token 形式保留在输入流中，并进入后续发送参数。
  • WB-SCOPE-002-AC2 输入区支持多个已插入 token 共存，而不是后插入覆盖前一个范围。
  • WB-SCOPE-002-AC3 删除 token 后，对应范围不再参与后续发送。

WB-SCOPE-003 重复与跨工作区范围清理

• 系统行为：已插入的范围不重复出现在候选中；切换工作区后，属于旧工作区的本地范围 token 自动清理。
• 验收：
  • WB-SCOPE-003-AC1 同一范围不会被连续重复插入。
  • WB-SCOPE-003-AC2 切换工作区后，旧工作区的目录或文件 token 不再保留。

WB-SCOPE-004 空候选提示

• 系统行为：若当前没有可插入范围，系统按上下文给出明确提示。
• 验收：
  • WB-SCOPE-004-AC1 未选工作区且没有匹配网页资料时，提示“先选工作区，或直接搜索网页资料”。
  • WB-SCOPE-004-AC2 已选工作区但没有匹配项时，提示“当前工作区和网页资料中没有匹配项”。

8.6 AI 运行中的阻塞与提示

WB-BLOCKER-001 审批阻塞

• 系统行为：AI 运行收到审批事件后，在 composer 下方展示审批条，包含原因、风险级别、命令内容和批准 / 拒绝动作。
• 验收：
  • WB-BLOCKER-001-AC1 审批通过后，当前运行恢复加载态并继续执行。
  • WB-BLOCKER-001-AC2 审批拒绝后，当前运行结束，且不会执行被拒绝的命令。

WB-BLOCKER-002 补工作区后继续运行

• 系统行为：AI 运行收到 workspace_required 事件后，提示用户先补工作区；用户补好后点击继续，系统会基于上一条真实输入重新启动一次运行。
• 验收：
  • WB-BLOCKER-002-AC1 未补工作区时，继续运行按钮不会绕过校验直接执行。
  • WB-BLOCKER-002-AC2 继续运行时，系统会先插入一条“已补充工作区上下文，请继续处理上一条请求。”的用户消息，再以原请求重新启动运行。

WB-BLOCKER-003 未加载资料 warning

• 系统行为：当已选范围中存在未加载文件时，界面按模式显示对应 warning。
• 验收：
  • WB-BLOCKER-003-AC1 智能模式下提示 AI 可能直接读取原文件，耗时更长。
  • WB-BLOCKER-003-AC2 搜索模式下提示纯搜索只检索已加载资料，未加载文件不会进入候选结果。

8.7 右侧内容面板

WB-PANEL-001 面板状态切换

• 系统行为：右侧内容面板包含空态、搜索列表、文件预览和确认修改工作区四种状态；同一会话内继续发送消息时不默认清空，切换会话时才回到空态或当前会话对应状态。
• 验收：
  • WB-PANEL-001-AC1 同一会话继续发送消息后，右侧会保留当前搜索列表、文件预览或确认修改工作区；只有与当前文件对应的新 review 才会原地刷新当前内容。
  • WB-PANEL-001-AC2 切换会话后，右侧面板回到空态或当前会话对应状态。

WB-PANEL-002 搜索结果打开规则

• 系统行为：搜索模式下右侧固定展示搜索列表与命中摘要；网页结果使用系统浏览器打开，本地结果使用 modal 形式预览，关闭 modal 后仍回到搜索列表。
• 验收：
  • WB-PANEL-002-AC1 点击网页结果时，不进入本地文档预览，而是调用系统浏览器打开。
  • WB-PANEL-002-AC2 点击本地结果时，会打开文件预览 modal；关闭 modal 后，右侧搜索列表与当前选中命中仍然保留。

WB-PANEL-003 文档查看与确认修改衔接

• 系统行为：文件预览态与确认修改工作区都采用预览优先布局，右侧主体空间默认让给文件内容；确认修改工作区按文件 tab 组织，一个文件对应一个 review tab。
• 验收：
  • WB-PANEL-003-AC1 普通文件打开后，右侧除轻量工具条外全部用于文件预览。
  • WB-PANEL-003-AC2 同一会话存在多个待确认文件时，确认修改工作区会显示一文件一 tab，并保留全部入口。

8.8 确认修改

WB-REVIEW-001 打开 review 后的默认选中逻辑

• 系统行为：打开确认修改工作区时，先加载当前文件对应的 review 详情；默认选中当前文件 tab 和第一条修改。若当前文件在同会话中又生成了新的 review，则工作区原地刷新到该文件的最新 review。
• 验收：
  • WB-REVIEW-001-AC1 成功打开 review 后，界面立即可见当前文件 tab、状态和确认文档内容。
  • WB-REVIEW-001-AC2 在多文件场景下，默认落到当前选中文件 tab 的第一条修改，而不是空白态。

WB-REVIEW-002 修改导航与定位

• 系统行为：确认修改工作区通过上一处 / 下一处按钮切换当前修改，确认文档预览按对应 anchor 定位。
• 验收：
  • WB-REVIEW-002-AC1 切换上一处 / 下一处时，当前修改计数明确变化。
  • WB-REVIEW-002-AC2 预览定位与当前选中修改保持一致。

WB-REVIEW-003 提交前校验是落盘门禁

• 系统行为：提交前校验在用户点击“确认替换”时触发；只有 review 状态仍可处理、确认副本存在且校验 ready=true 时，才允许提交落盘。对于修改现有受支持文件的任务，提交会写回源文件；对于新建受支持文件的任务，提交会创建目标文件。当前这两类任务均以 docx 为首个支持类型。
• 验收：
  • WB-REVIEW-003-AC1 校验有问题时，逐条展示问题，并阻止本次提交落盘。
  • WB-REVIEW-003-AC2 校验通过时，界面允许继续完成本次确认替换或确认创建。

WB-REVIEW-004 提交落盘与放弃修改

• 系统行为：确认修改工作区以文件为最小操作单位；提交会按任务类型执行当前文件的落盘：修改现有受支持文件时，以覆盖方式把确认文档写回源文件；新建受支持文件时，把确认文档创建为目标文件。放弃只清理当前文件的确认副本，不替换源文件，也不创建目标文件。
• 验收：
  • WB-REVIEW-004-AC1 修改现有 docx 的提交成功后，仅当前文件 tab 对应的确认文档被写回源文件。
  • WB-REVIEW-004-AC2 新建 docx 的提交成功后，仅当前文件 tab 对应的确认文档被创建为目标文件。
  • WB-REVIEW-004-AC3 放弃成功后，仅当前文件 tab 对应的确认副本被清理，其他文件 tab 不受影响。

WB-REVIEW-005 已结束 review 的状态收敛

• 系统行为：当 review 已 committed、discarded、superseded 或其他不可继续状态时，只保留状态说明与有效查看入口，不再暴露确认副本预览、确认副本打开按钮、提交或放弃等无效操作。
• 验收：
  • WB-REVIEW-005-AC1 已结束 review 不允许继续执行提交或放弃动作，也不继续展示确认副本操作入口。
  • WB-REVIEW-005-AC2 界面明确展示结束原因，例如已写回、已放弃或已失效；若仍提供查看结果入口，只能指向有效的源文件或当前可用结果。

WB-REVIEW-006 当前会话 review 清空后的回退

• 系统行为：若当前会话下已经没有任何 active review tab，则右侧确认修改工作区自动回退为空态，并同步清空 assistant turn 上的 review target。
• 验收：
  • WB-REVIEW-006-AC1 review 列表为空时，右侧不残留已过期确认内容。
  • WB-REVIEW-006-AC2 assistant turn 不继续展示失效的确认修改入口。

WB-REVIEW-007 同一轮多个确认文档入口保留

• 系统行为：同一 run 或同一会话下若生成多个待确认文件，assistant turn 和右侧确认修改工作区都要保留全部入口；右侧按文件 tab 聚合，一个文件只保留该文件最新 active review。
• 验收：
  • WB-REVIEW-007-AC1 同一 run 生成的多个确认文档都会出现在同一 assistant turn 的确认列表中，不会被后写入的 target 覆盖。
  • WB-REVIEW-007-AC2 点击不同确认文档入口或切换不同文件 tab 时，右侧会加载对应文件的最新 review，会话之间不会互相覆盖或丢失导航入口。

WB-REVIEW-008 同文件多轮修改显示累计差异

• 系统行为：同一会话内，AI 可以基于该文件最新草稿继续修改；右侧确认修改工作区展示的是源文件与当前最新草稿之间的最终累计差异，而不是仅本轮增量差异。
• 验收：
  • WB-REVIEW-008-AC1 同一文件多轮未提交修改后，右侧展示仍然包含先前轮次保留到最新草稿中的差异。
  • WB-REVIEW-008-AC2 若后一轮覆盖了前一轮的某处修改，则右侧只展示相对源文件仍然成立的最新差异，不重复保留已被覆盖的旧标记。

9. 非目标

• 不定义设置页中的工作空间、网页资料或模型配置行为。
• 不定义按钮尺寸、颜色 token、面板圆角等视觉风格。
• 不定义 AI 内部节点实现、prompt 结构或工具路由细节。