# SourceDeck v3：后台研究、对话引用与完整主题适配

日期：2026-10-18。状态：**用户已批准本书面设计并要求落地、推送 Git；[实施计划](../plans/2026-10-18-sourcedeck-v3.md)已写待评审，核心产品实现尚未开始**。

中文为主；[English](2026-10-18-sourcedeck-v3-design.en.md)。前序调研见 [开发者工作流评审](../../research/2026-10-18-developer-workflow-review.md)。

## 1. 已确认的目标

用户优先场景是找开源库、比较技术方案，再把筛选结果用于当前项目开发。此次评审进一步明确：

1. 资料台默认双列，面板过窄自动单列，拉宽恢复；按面板自身宽度判断，不要求手动切换。
2. 仓库保留对应图片、缩略图、Logo 或头像；GitHub 明显展示 stars 与最近代码更新时间。
3. 全部内容适配浅色/深色，包括设置页下拉框展开后的选项、输入框、菜单、提示、禁用与错误状态。
4. 在左侧说“用资料台找……”即可启动，不要求先打开右侧再输入一遍。
5. 补搜不重复向左侧发送长搜索提问；右侧研究期间左侧仍能处理开发任务。
6. 右侧结果能引用进左侧草稿，用户追加诸如“参考这几个仓库，学习调研其中的 UI 设计，再考虑优化本仓库实现”的要求后自己发送。
7. 支持自定义插件图标时直接设计制作。

用户已在本轮选项中明确选择：**采用受管的后台研究子会话，默认沿用当前模型配置与凭据策略，接受并发模型请求**。

这修订了旧版“所有搜索由主会话 Agent 串行执行”的决定。保留的是主会话归属、资料集和引用关系；研究的执行会话独立。不能继续以“共用主 Agent 但隐藏 UI 消息”冒充并行。

## 2. 基线与范围

- 精确支持 `@deepseek-ai/dsh@0.2.1-rc.2`、Cordis `4.0.5`；上游固定 commit `687f282e8625c6b8d11ff58211a90524be2e4317`。
- 保留八表域及旧数据；扩展字段而不默认清空或迁移到新应用。
- 当前产品仍 `0.2.5`；本轮只完成调研、设计和图标资产，不重新打包同版本，不安装到生产。
- 不做项目知识库、全库索引、跨设备同步或无限并发研究。一个资料集同时只运行一轮研究。

## 3. 聊天入口与自动打开

### 自然语言

主 Agent 识别“用资料台找 4 个适合桌面端的 Markdown 编辑器”“把这些方案放到资料台筛选”等明确意图，调用新的 `deck_search` 工具。工具立即启动后台研究并返回简短状态，主 Agent 不等待全部搜索结束。

工具描述和会话内指导说明提供上述例句；不拦截普通“找/搜索”等所有文字。自然语言路径依赖当前模型的工具调用能力，需真实模型验收；确定性入口为 `/deck <需求>`。

### 命令与按钮

- `/deck`：只打开资料台，不发模型请求。
- `/deck <需求>`：Host 命令直接启动新主题的后台研究，不再先向主聊天插入另一条结构化 user prompt。
- 资料台“继续查找”：将保留、排除及原因、补充说明发给该主题的研究任务，不调用主会话 `session.prompt`。
- 输入区按钮：打开当前主题，不读取或清空聊天草稿。
- 新启动的主题携带明确的打开意图；Client 定向 `openTabIn(parentSessionId, 'sourcedeck', ...)`。切到其他会话后不得把结果打开到错误会话或抢走当前会话。
- 前端用已挂载的会话入口维护轻量活动观察；优先公共事件，未有已验证事件时采用小型 `getActivity` 轮询，不依赖未验证的推送接口。观察仅负责发现活动和刷新，不产生模型请求。

## 4. 后台研究执行

### 服务边界

- `ResearchCoordinator`：接收已确定归属的主 Agent、主题、轮次；记录任务身份；启动/观察/停止精确的子会话激活；不管理第二份凭据。
- 通过固定 RC 的 `ctx.subagents.startActivation` 和本地 spawn provider 创建 fresh 研究会话，显式传入本轮需求、可选的最近对话摘要和筛选反馈。
- 默认使用主会话开始研究时的模型路由和官方凭据解析；不读取、复制、保存 API key，不出现第二个模型设置流程。
- 使用 `delivery: 'caller'`，由资料台消费结果；研究完成不自动向主 Agent 注入一条完成提问或唤醒主模型。
- 子会话运行时的目录、父子身份、权限与生命周期遵守官方管理器。研究组合只提供检索/阅读/资料提交能力；在官方组合层验证工具限制，不能只写一段“不要改代码”的提示词就声称已限制写入。
- 依赖的 provider/service 不可用时显示可行动的错误，不静默退回主会话刷消息的旧路径，不自行升级 RC。

### 任务身份与结果

创建轮次时预留 worker sessionId 并先持久化归属，再启动，避免快速回调先于绑定。每轮记录 parentSessionId、setId、roundId、workerSessionId、requestId；不能再按“此刻活跃集合”猜测结果归属。

`deck_submit_sources` 校验可信执行身份与轮次绑定：研究子会话只能写回分配给它的资料集。传入任意 setId/roundId 不赋予写入权。每批只发布一次集合快照。主会话显式收集资料的旧路径保持可读和独立，不能误写后台轮次。

以受管 activation 的完成/失败作为轮次结束依据，候选到达只代表已有部分结果。正常结束但没有新候选明确显示“无新结果”；全重复结果也能结束。取消、失败、超时保留已到达候选；迟到结果不污染新主题。

### 并行的实际含义

左右的草稿、筛选状态、排队与取消独立；主 Agent 可做开发，研究 worker 同时检索。已有候选可在研究期间筛选、收藏、对比和引用，不因搜索 busy 而全局禁用这些动作。两者仍共享提供方额度、网络和主机资源，不能承诺在任何限流下耗时完全不变。

停止资料台研究只停止对应 worker，不调用主会话停止。主会话切换不终止研究；重开可恢复持久化状态。Host 重启后无法证实仍在运行的任务显示“已中断，可重试”，不伪造搜索中。

## 5. 主聊天的消息可见性

当前 `session.prompt` 的请求只有 requestId/sessionId/mode/content/clientTimeZone；它会创建普通 user message，没有 `hidden` 开关。旧版补搜气泡因此是当前实现路径的直接结果。

v3 把内部研究提问留在研究会话，只在主聊天保留用户原始请求、必要的简短启动状态和资料台卡片。完整研究记录仍可审计；官方子会话目录/生命周期记录可能存在，不能承诺“所有日志都消失”。仅靠 CSS 隐藏消息不在方案内。

## 6. 结果引用到左侧草稿

### 主流程

右侧主要动作改为 **“引用到对话（N 条）”**。点击后创建不可变选择快照，在对应主会话的输入区插入一个引用标签，聚焦输入区，由用户继续补写并发送；不会自动发送 prompt，也不会以 `setDraft` 覆盖已有正文或附件。

示例：

```text
[@资料台 · 已选 3 条]
参考这几个仓库，学习调研其中的 UI 设计，
再结合本仓库现有组件和约束，提出优化方案并实施。
```

左侧 `@deck` 提供当前主会话的已选资料/历史选择快照，作为第二个入口；不需要再次打开右侧。引用可移除、打开预览、查看具体条目。

### 引用协议

- 使用固定 RC 的 `inputTriggers.registerSource`、`ReferenceInsert` 与 source-owned `codec.serialize`。发送给模型时展开为标题、URL、必要的说明/元数据及来源；不能只把模型无法读取的 refId 发出去。
- 快照包含精确的条目身份、当时的标题/URL/选择，后续继续筛选不改变已插入的引用。历史选择可读；跨会话访问需验证归属。
- 复用 selections 表，新增区分引用快照与最终提交的 kind/快照内容等可选字段；创建引用不把集合锁为 submitted。
- 异步插入用官方 draft revision guard；若用户已继续编辑或正在提交，保留草稿并给出重试入口，不强行替换文本。
- 引用解析失败、已清理或插件不可用时明确阻止带失效引用的发送并提示修复，不静默把空引用交给模型。
- 原“直接发送筛选摘要”降为明确的次要操作，沿用稳定 requestId 与已确认投递状态，避免重复发送。旧 submitted 集合保持只读。

引用这些仓库不等于文件已下载、网页已读完或用户已批准安装依赖；主 Agent 根据用户续写的开发要求继续使用既有工具和权限。

## 7. 全部主题与布局验收

以 DSH 主题服务的 active scheme 和 `--dsw-alias-*` token 为准。固定 RC 的 ThemePresenter 已向根设置 color-scheme、向 body 设置 `data-ds-dark-theme`。插件不修改全局主题、不仅依赖操作系统 prefers-color-scheme、不假定现有 `--dsw-text-primary` 等兼容别名一定存在。

| 界面 | 必验状态 |
|---|---|
| 搜索首屏、候选卡片、对比、收藏、历史 | 默认、悬停、焦点、选择、空结果、加载、错误、禁用 |
| 设置页 | select 闭合与展开选项、选中/悬停项、输入与 placeholder、勾选框、预设、保存/失败提示 |
| 聊天引用与卡片 | 引用标签、引用预览、失效引用、既有草稿、长名称、键盘焦点 |
| 图片与图标 | 浅/深背景、透明 Logo、图片失败、32/48/64px 图标 |

原生 select/option 遵循宿主 color-scheme，并设置当前 token 对应的前景/背景；若平台展开菜单不能稳定显示，使用固定 RC 已有的公共选择组件，不写全局 option 覆盖。主题切换与面板切列不清空输入、筛选、原因、对比或引用。

默认两列、窄面板一列，初始断点约 620 CSS px；在 320/420/640/900px 面板宽度和 100%/125% 缩放验证，正文保持可读。

## 8. 仓库图像与插件图标

仓库卡片保持此前确认的真实缩略图/Logo/头像、stars、最后代码更新时间、数据来源和查询时间。用户已报告内嵌预览图片出现“暂不可用”；此前本地浏览器可见不能等同于用户预览或官方 Desktop 验收。外链失败与权限、网络等具体原因需在实际宿主记录验证，不能声称已经解决。图像回退保持内容与动作完整，不绕过宿主资源策略。

插件自身图标已制作：`assets/icon.svg`（848 bytes）与 `assets/icon.png`（256×256，8,082 bytes）。视觉为叠放资料卡加筛选勾选，使用蓝/青色和不透明底板；SVG 不含脚本、字体或远程资源。已检查深浅底的 32/64px 栅格预览；不冒充 Desktop 插件列表验收。

下一版清单接入方式：顶层 `"icon": "./assets/icon.svg"`；将 SVG 加入 `files`。已有 `./package.json` 导出可供 Host 读取。可用 `locale/en.json` / `locale/zh.json` 的 meta.title/meta.description 提供简短中英展示名与描述，替换安装列表里的技术包名/长英文段落。

固定 RC 支持 SVG/PNG/JPEG/WebP，单图不超过 256 KiB，路径必须位于包内；Host 转为 data URL，故插件图标无需依赖外部图片服务器。本轮尚未修改 package.json 或重打 tgz，现有安装包不会自动获得新图标。

## 9. 固定 RC 接口证据

以下均来自 commit `687f282e8625c6b8d11ff58211a90524be2e4317`，不是 master 或 alpha 接口：

- `packages/api/session-controller/src/types.ts`、`index.ts`、`commands.ts`：prompt 请求及普通 user message 的生成、requestId 去重。
- `packages/subagent/subagent/src/index.ts`、`types.ts`：startActivation、delivery caller、子会话身份与结果/取消。
- `packages/subagent/subagent-spawn-in-process/src/index.ts`：fresh child、主模型路由合并能力；只启服务不等于 provider 已注册。
- `packages/client/ui-input-trigger/src/types.ts`、`client/controller.ts`：reference codec、序列化失败拒绝发送；输入提交拦截只轮询对应 `/` 或 `@` 前缀，不能拿它假冒通用自然语言识别。
- `packages/client/ui-conversation/src/client/contract/input.ts`、`draft-editor.ts`：ReferenceInsert、作用域插入、captureInsertion/insertText 的草稿保护。
- `packages/client/ui-layout/src/client/theme-presenter.ts` 与 ui-theme 样式：主题权威状态、color-scheme、alias token。
- `packages/boot/app-boot/src/package-meta.ts`、`docs/cookbook/adding-a-package.zh.md`：图标与 locale 元数据路径、类型和体积规则。

公共 API 存在是可行性证据；实际 provider 是否启用、冷会话恢复、工具组合限制、引用插入路径和并行模型行为必须在固定 RC 官方沙箱通过。

## 10. 验收与交付

1. 纯逻辑：主/子/轮次身份校验、迟到结果、空/重复结果结束、取消/超时、重开/重启、重试幂等、旧数据兼容、引用快照不可变。
2. 组件：主题切换所有状态、下拉菜单展开、草稿不覆盖、异步插入冲突、引用序列化失败、历史卡片定向打开；键盘/IME 不被资料台抢占。
3. 固定 RC 集成：自然语言与 `/deck query` 各启动；补搜不新增主 user prompt；右侧研究时左侧真实执行一项独立任务；取消右侧不停止左侧；通过引用+用户续写完成主会话中的调研/开发指令。
4. 图像与 metadata：原图可见和失败回退都验收；图标包内路径、pack 内容、Host metadata data URL 和已安装列表深浅色实际截图；禁用插件后图标仍可读取。
5. 构建/pack 前 bump 新版本，精确 peer、类型和 lazy-CJS 检查；只通过沙箱 Install-Plugin.ps1 安装。记录真实模型与无模型检查的区别。
6. 核心实现、清单与安装尚未开始；正式书面设计获批后再写实施计划。生产安装仍单独获得用户明确批准。