# 路线图

本文件记录**尚未完成**的工作与明确暂缓的方向。已完成的能力见 [README](README.md) 与 [docs/PRODUCT.md](docs/PRODUCT.md) §6。

优先级不构成承诺，实际顺序取决于 DSH 上游契约的演进与本项目维护带宽。欢迎在 Issue 中讨论或直接提 PR。

## 近期（已有接口或明确入口，可直接动手）

### 1. 宿主动作缺失降级的自动化测试

**已完成（2026-09-11）。** 渲染级测试已落地：`test/render-smoke.test.js` 用真实 `react-dom/server` 渲染初始状态（不引入 jsdom，DOM 缺失面由 `test/helpers/dom-stub.js` 补齐），对五处守卫逐一断言——

| 文件 | 自动化覆盖 |
| --- | --- |
| `src/research-workbench.js` | SSR：降级提示存在、写入/发送按钮带 `disabled`；对照组（提供 inputActions）恢复可用 |
| `src/composer-overlay.js` | SSR：关闭态渲染不抛错；接线断言：`hasDraftAction` 守卫与 `setNotice` 降级存在 |
| `src/research-vault.js` | SSR：完整渲染不抛错；接线断言：`setDraft` 守卫存在（降级走异步 `setError`，初始渲染不可见） |
| `src/database-query-panel.js` | SSR：完整渲染不抛错；接线断言：`canWrite` 守卫与写入前提前返回存在 |
| `src/research-evidence-vault.js` | SSR：写入按钮带 `disabled`；接线断言：`canWrite` 与选择数联合守卫存在 |

**边界（不掩饰）**：SSR 只覆盖初始渲染态。「点击后是否真的不写入」属于交互，需要真实 DOM 事件运行时（jsdom 或浏览器级 harness）才能构造，目前仍由纯逻辑决策测试（`planCitationWrite` 三态）+ 源码接线断言 + 真实 profile 现场核对（W2/W3）三层共同守护。若要继续推进交互级覆盖，需在 CI 引入 jsdom 并把现有桩换成可触事件的 DOM 实现——这是本项后续的演进方向，不是缺口。

**为什么重要**：这是插件与宿主契约之间最主要的降级路径，也是真实 profile 烟测中唯一无法从外部构造的项。

### 2. 工作台左列 sticky（已完成 · 2026-09-12）

**落地**：左列列表 `position: sticky`，偏移 = 一级导航（`--rk-console-nav-h`）+ 二级吸顶带（新增 `--rk-workbench-toolbar-h`，`ResizeObserver` border-box 实测、随折行变化，不写死像素），列表以视口内 `maxHeight` 约束并内部滚动。源码接线由 `test/sticky-header.test.js` 守护；现场确认并入 MANUAL-QA 合并走查清单。

### 3. 证据图谱连线的方向表达（已完成 · 随 §4d 落地）

**已完成（2026-09-11）。** 原状是连线固定「从左缘连到右缘」，边方向本身逆向时（如 `workflow → resource`，工作流列在资源列右侧）线段会穿过节点、产生穿越感；当时没有数据会触发该路径。§4d 把已保存证据接入图谱后产生了该方向的边，本项随之落地：箭头按两端节点的**实际水平位置**选锚点——正向走「右缘 → 左缘」，逆向走「左缘 → 右缘」，不再固定「左进右出」。因锚点自适应会让箭头指向不再自明，图谱说明显式标注「箭头表示关系方向」。

实现见 `src/research-evidence-graph.js` 的 `edgePoints()`；真实验收见 [MANUAL-QA](docs/MANUAL-QA.md) 的 G4。

> 编号未回填：§4 及其下的 4a–4d 切片编号被多份文档与源码注释引用，重编号会让这些引用失效。本节保留原位置与编号，只更新状态。

### 3.1 专用科研证据 Viewer

**已完成（2026-09-11）。** 分区④在既有关系图（节点、边、方向性锚点、链路流动动画）之上补齐了面向科研证据的探索能力，全部在插件内实现、未接入第三方渲染器：

- **确定性分层布局与端口路由**（`layoutEvidenceGraph` / `routeEvidenceEdges`，纯逻辑）：按节点 kind 分列、同列按 id 字典序，新增节点不让已有节点跳位；边按两端实际水平位置选锚点，同侧多条边按端口展开，贝塞尔连线避免穿越；
- **缩放、平移、复位**：Ctrl / ⌘ 滚轮缩放（限幅 40%–250%）与按钮缩放以视口中心为锚，拖拽平移带边界钳制（图拖不丢），一键复位；
- **迷你地图**：右下角常驻全图缩略，点击跳转，视口框实时联动；
- **聚焦 / 上游 / 下游 / 两点路径四种范围模式**：BFS 邻域与无向最短路均为纯逻辑（`evidenceNeighborhood` / `findEvidencePath`），路径模式忽略箭头方向——用户问的是「这两个东西怎么连上的」；非范围内节点降透明度而非移除，保留参照系；
- **键盘可达**：节点是 `role="button"` + `tabIndex`，Enter / 空格触发聚焦；
- **`prefers-reduced-motion` 静态降级**：系统关闭动画时链路流动自动停止；窄屏（<880px）随统一容器单列收敛，画布不再有固定最小宽度；
- **URL 只保存视图状态**：焦点、范围模式、路径两端与缩放经 `encodeGraphView` 写入 hash，**不编码任何证据内容**——链接会被转发，标题与标识符都不该进去；
- **脱敏静态导出（用户显式触发）**：SVG 与离线可打开的 HTML 双格式；导出弹窗与导出文件正文都写明元数据范围（仅含节点标题、来源库、稳定标识符、核验状态与关系，不含笔记、全文、检索词、附件或输入框草稿）；导出物把当前主题解析为真实色值，脱离 CSS 变量后不再依赖宿主环境。

**自动化覆盖**：布局确定性/稳定性/分列规则、路由锚点、邻域/路径语义、缩放限幅、URL 编解码往返（含「内容不进链接」）共 17 项纯逻辑测试（`test/evidence-graph.test.js`）。

**剩余验收**：真实 profile 上以至少一条「数据库 → 查询 → 来源 → 已保存证据」的链路完成聚焦、上下游、路径、缩放与迷你地图操作；窄屏可读；导出物脱敏且离线可打开。导出与复制链接时的元数据范围提示已在实现中落地，现场核对即可。该项已登记到 [MANUAL-QA](docs/MANUAL-QA.md) 待验清单（V1–V4）。

**同批交付的另两项可视化能力（不在本节的遗留清单内）**：工作台「组装回放」（`src/route-replay.js` + archify viewer 弹窗）与「研究结果解释图生成」工作流 + 出图工具链（`scripts/render-diagrams.mjs` / `validate-diagrams.mjs`）已随本次交付落地，细节见 [CHANGELOG](CHANGELOG.md)。本节的分区④ Viewer 只覆盖证据图谱，**不是**本仓库可视化能力的全部——按路线图判断可视化进度时不要只看本节。

### 12. 工作流新增字段的契约校验

**现状**：`scripts/add-agent-fields.mjs` 一次性为全部 349 条工作流补入了 `input_schema` / `tool_mode` / `agent_guidance` / `checkpoints` 四个字段，把目录条目接到 MCP 工具链上。但这四个字段**既不在 `scripts/validate-catalog-lib.mjs` 的校验范围内，也没有任何测试断言**——改坏、漏填或写错阶段名都不会让 `npm run check` 失败（同一批脚本 `sync-tool-docs.mjs`、`check-doc-stats.mjs` 都是事后才补上落点的，本项是同一类遗漏）。

**要做**：按字段性质分成两类校验——`input_schema` 与 `placeholders` 是同一份字段的两种表示，应当断言逐字段一致（键集合、必填集合、`requiresFiles` 时追加 `files`）；`checkpoints[].required` 与 `after_stage` 属于流程语义，至少断言 `required` 为布尔、`after_stage` / `action` 非空且在条目内唯一。`tool_mode` 取值限定在两个枚举内。同时补进「三落点」纪律的登记清单。

**门槛**：新增规则必须做反向验证——临时篡改一条工作流的字段，确认校验器以非零退出报出「文件 + 条目 id」；只加规则不做反向验证等于没加。

## 中期（需要上游支持或较大改动）

### 4. 研究资产库：本地证据库

**目标**：在沉淀层「研究资产库」中维护与「灵感资产」并列的「证据库」子模块，沉淀用户**明确保存且可追溯**的论文、数据集、临床试验和数据库记录，供后续研究任务检索与复用。

**产品定位**：不新增第五个并列工作台分区。沉淀层在 4a–4b 落地后已更名为「研究资产库」，内含「灵感资产 / 证据库」两个子模块：灵感资产回答“想过什么”，证据库回答“依据什么”。关系可视化由既有的独立第四分区「研究证据图谱」承担，它是只读的，不替代证据条目的管理与核验。

**隐私与数据边界**（不可协商，适用于下面每一个切片）：

- 仅持久化用户确认的元数据与主动写下的笔记；默认不保存原始 API 响应、检索词、完整全文、附件或未经用户确认的模型摘要；
- 本地持久化改用 IndexedDB，而不是无上限扩张 `localStorage`；提供按项目导出、导入与彻底删除；
- 不在草稿增强、工作流启动或 Agent 调用时静默注入历史证据；所有复用必须经历“检索 → 预览 → 用户勾选 → 写入 Prompt”；
- 写入 Prompt 时不得将本地条目表述为已证实结论，必须保留来源与人工核验责任。

**交付切片**：按依赖顺序拆为四片，**每片独立验收、独立上线**。四片截至 2026-09-11 **已全部交付**，各片的范围与验收结论保留如下（逐片细节见 [CHANGELOG](CHANGELOG.md)，现场验收项见 [MANUAL-QA](docs/MANUAL-QA.md)）。

**已完成：4a 保存与条目。** 条目字段（标题 / 来源数据库 / 稳定标识符 / 原始链接 / 保存时间 / 项目 / 标签 / 保存原因 / 用户笔记 / 核验状态）已落地，持久化直接建 IndexedDB 最小 schema；保存入口在查询结果条目上逐条触发，列表在沉淀层分区的「证据库」子模块。细节见 [CHANGELOG](CHANGELOG.md)。

**已完成：4b 持久化与项目隔离。** 跨刷新持久化走 IndexedDB；按项目隔离与切换，当前项目作为工作上下文跨会话保留；同一稳定标识符在**同项目内**去重（跨项目不去重——项目隔离优先），命中重复时交给用户裁决「覆盖已有 / 仍然另存」，不自动合并；单条删除与按项目彻底删除；按项目导出 JSON 备份与增量导入（已存在条目跳过，恢复是补齐不是回滚）。细节见 [CHANGELOG](CHANGELOG.md)。

**已完成：4c 勾选写入 Prompt。** 证据库子模块内勾选条目后给出引用块预览，「写入 Prompt（N）」把带来源链接与「尚未经逐条核验、不得据此直接断言结论」边界的引用块写入当前会话输入框；宿主未提供输入框操作时按钮禁用、引用块转为手工复制。选择以**全部证据条目**为基准，不随筛选条件变化被静默撤销。注入与否由纯函数 `planCitationWrite()` 决策（`empty / unsupported / write` 三态，仅 `write` 允许调用 `setDraft`），本节原定的两项验收——「未选择不注入」回归测试与写入边界断言——均已落地。**真实 profile 验收（[MANUAL-QA](docs/MANUAL-QA.md) 的 W1–W3）已于 2026-09-11 通过**：勾选后按钮可用、未选择时按钮点不动、写入不自动发送且提示条数与实际注入一致。细节见 [CHANGELOG](CHANGELOG.md)。

**已完成：4d 图谱接入。** 已保存证据作为独立节点接入图谱，节点上展示来源库、稳定标识符与核验状态，**不携带笔记、全文或检索词**；证据按来源库连到同库资源节点，并按 URL 或稳定标识符匹配本会话查询来源，工作流仍经资源节点形成可追溯链路。原先「连线方向表达」的遗留问题随之解决——箭头按两端节点的实际水平位置选择左右锚点，逆向关系不再固定「左进右出」。**真实 profile 验收已于 2026-09-11 通过**：测试证据与 PubMed 资源共呈 2 个节点 / 1 条关系，图谱说明明确标注箭头含义。细节见 [CHANGELOG](CHANGELOG.md)。

**整体验收**：四片已全部落地，其中 4c、4d 已在真实 DSH profile 上验收（见 [MANUAL-QA](docs/MANUAL-QA.md) 的 W1–W3 与 G1–G4）。

**已完成：4e Agent 批量初判。** 证据库提供一键批处理入口，默认跳过人工已处理条目，可显式勾选后重新获取当前会话模型的最新初判。请求按小批次执行，支持进度、取消、结构化输出校验和并发快照保护；结果与人工评估分开保存并保留最近历史，不推进核验状态。该能力只向模型发送证据元数据与用户笔记，不读取 DOI/URL 全文，仍需人工核验，不能替代 `research_evidence_assess` 的人工评估或来源核验工具。

### 5. Memory Center 项目记忆检索（检索流程已落地 · 2026-09-12；现场核验待宿主接入）

**归属判据（定死）**：可追溯到外部稳定标识符（DOI / PMID / NCT / 数据集编号 / 原始链接）的来源归证据库（§4a 流程）；项目内部的决策与上下文（无外部稳定标识符）归 Memory Center。两者不混流：Memory 检索结果只作为增强上下文，**永不写入**证据库、灵感资产或知识库。

**已交付**：`dsh/memory-search.js` 检索路由（`POST /dsh-research-kit/memory-search`）——从工具注册表探测宿主已连接的 Memory Center MCP（默认服务器名 `memory-center`，请求可显式指定 `server` / `tool`），按目标工具自己的 JSON Schema 合成参数；无法可靠合成的必填参数（枚举 / 标识类 / 复杂结构）明确拒绝并给出诊断，**绝不拿猜的参数打 MCP，也绝不代打 `mcp__` 前缀之外的原生工具**。浏览器端：增强器 `searchMemory` 合并「会话已选资源摘要 + Memory 检索结果」并带来源标签；是否进入 Prompt 仍由 vendored 面板的「项目记忆」显式开关控制——检索 → 来源预览 → 用户选择 → 组装，**禁止静默注入**（源码断言钉住）。部署未接入 Memory Center 时如实回落「仅会话资源摘要」，增强不报错。

**要做（后续）**：在宿主实际接入 Memory Center MCP 的部署上现场核验（探测命中 → 检索返回 → 面板预览 → 勾选注入，见 MANUAL-QA M1）。

### 6. 宿主能力探测（部署级探测已落地 · 2026-09-12；条目级升级按门槛另行执行）

**目标**：按 DSH 实际已连接的 MCP / 工具标注数据源与技能，而不是让用户自己判断。

**已交付（部署级）**：`dsh/host-capabilities.js` 探测路由（`GET /dsh-research-kit/host-capabilities`）——从工具注册表解析 `mcp__<server>__<tool>` 命名，得到「已连接 MCP 服务器」的**事实清单**（排序、去重、有界截断），并报告 Web / Shell / 文件系统 / 模型路由四项**装配事实**；任何一步失败都退化为「未知」，探测不抛错。浏览器端 `src/host-capabilities-client.js` 汇总为一行事实摘要（进程级 5 分钟缓存），在工作台数据源详情「宿主能力」行展示。**不根据资源名称推断数据库已可用**；消费端不改写目录标注（测试断言钉住）。

**门槛（不变）**：条目从 `requires-mcp` 升级为 `available-in-host` 需要条目级验证——为条目声明其依赖的具体 MCP 服务器 / 工具，探测命中且经最小真实查询核验后才可升级，并同步双向契约校验。本阶段的部署级探测只是事实底座，不构成升级依据。

**与 `available-in-plugin` 的区别**：本项解决的是「宿主给了什么」，与插件自身是否已实现直查无关。11 个条目已因插件内置适配器标为 `available-in-plugin`（由目录与实现的契约校验守护），不构成本项的交付，也不因此免除能力探测。

### 7. 发送前自动增强

**目标**：在用户点发送时自动对草稿做一次增强。

**阻塞项**：依赖宿主下发「发送当前草稿」钩子（onSubmitDraft），当前 DSH 槽位契约未提供。上游支持前不做。

### 8. 目录内容扩充（工作流）（上游对账已办结 · 2026-09-12）

**现状**：工作流目录已按流程族分片维护于 `catalog/workflows/`（`index.js` 聚合），共 349 条、28 个类目。原 8 个预留空分片（生态、神经科学、物理、天文、社会科学、数学、机器学习、工程）已全部由 K-Dense 上游条目中文化迁入填满。

**对账结论（2026-09-12，快照：k-dense-byok 本地同步版）**：上游 326 条工作流中非金融 285 条按 id 逐一比对，**id 级缺口为 0**——仅 2 条属同义改名迁入（上游 `write-paper` → 本目录 `write-full-manuscript`「撰写完整论文初稿」；上游 `systematic-review` → 本目录 `systematic-review-protocol`「系统综述方案设计」），其余全部同 id 在库。此前记写的「约 10 条散落缺口（基金申请 -2 / 基因组学 -3 / 细胞生物学 -4 / 药物发现 -1）」经复核为**记账错误**：那是「我方分片条数 vs 上游类目条数」的差值，实际对应迁移时的既定跨类归置——管线类工作流（bulk/single-cell RNA-seq、变异检测、ChIP-seq、ATAC-seq、甲基化、空间转录组共 7 条）按「执行管线归生物信息学」的分工落在 `bioinformatics.json`；细胞类型注释、轨迹拟时序、免疫画像按「基因组学扩充轮」的既定设计落在 `genomics.json`；研究计划、数据管理计划按初期设计落在研究设计。这些归置服务检索直觉，不回改——只为类目计数对齐而搬家会让检索变差。

**要做**：无存量缺口。后续新增上游条目时先按 id 对账（同义改名算已迁），每条新增工作流至少做一次「最小材料」人工走查——检查模型是否被引导为虚构事实、过度承诺或遗漏不确定性。

### 9. 科研模式领域预设（已完成）

**已完成。** `src/research-workbench.js` 的 `SCIENCE_MODE_PRESETS` 现有 **6 个**预设：通用研究（general）/ 文献与论文（literature）/ 生物信息学（bioinformatics）/ 作物遗传育种（cropBreeding）/ 临床与人群研究（clinical）/ 数据分析与可视化（dataVisualization），与 [README](README.md)、[架构文档 §3.0b](docs/ARCHITECTURE.md)、[开发指南](docs/DEVELOPMENT.md) 的口径一致。原文称该常量仅有三个预设（基因遗传 / 临床队列 / 通用科研），那是合并前的状态，已失效——按本节判断进度会以为要做的事其实早已做完。

**扩展方式**：新增领域预设仍只需在该常量中加条目（技能组合 + 纪律段 + 标签）。

**注意**：本节与 §8 是不同文件、不同层——工作流是目录资产，领域预设是附加到 Prompt 上的科研纪律段，两者不可互相替代。

> 编号未回填：本节保留原编号与位置，只更新状态（同 §3 的处理）。

### 10. vendored 工件的可维护化

**现状**：`vendor/promptkit-embed.js` 是 SHA 锁定的生成工件，约 637 KB，已进入 bundle。仓库现有 **3 个** vendored 工件——promptkit 工件 + `vendor/archify/template.html`（756 KiB，整段注入为全局字符串）+ `vendor/archify/i18n.mjs`（参与拼接），清单见 `vendor/vendor-manifest.json`；三者合计约占构建产物 2.3 MB 中的 1.36 MB。

**动机**：主要不是体积——对本地插件而言 637 KB 不是主要成本——而是它**不可手改、不可逐行 review，且 SHA 锁定意味着任何升级都只能整体替换**。目标是逐步换成可维护、可审查的源码子模块。

**要做**：视维护需要逐步替换。

**门槛**：替换后的模块必须在真实 DSH profile 上通过 [MANUAL-QA.md](docs/MANUAL-QA.md) 的完整清单。

### 11. 动线整合：把「发现 → 构造 → 沉淀 → 证据」连成动线（规划中 · 2026-09-12 立项）

**背景**：四个分区能力集合各自完整，但闭环动线只存在于文档里——产品中没有任何一条线把四层串起来（用户走查结论：空间不在「缺功能」，在「断链」）。本主题收纳跨分区动线类工作，避免它们散落在各分区条目里失焦。

**基础设施第一片（已落地 · 2026-09-18）**：新增 `research-context-store`，提供跨分区一致的「当前项目 + 最小研究运行」上下文。工作流写入、发送或复制时创建不含 Prompt/原始内容的运行记录（草稿 / 活跃等 UI 状态），并同步既有证据库项目选择；控制台导航显示当前项目与活跃运行。工作流 Prompt 会带入格式受限的 `run_id` 协作指令；MCP `research_evidence_save` / `research_evidence_list` 与 `research_run_export` 可消费该可选关联键，checkpoint 与 Agent 活动面板据此收敛到同一次运行。`run_id` 不参与证据去重，也不把“写入输入框”表述为工具已执行。

**第一切片（已落地 · 2026-09-12，待 MANUAL-QA 现场核对 L1–L3）：P5「资产-证据互链」最小闭环。**
- 数据模型：link 关系（assetId ↔ evidenceId）落**证据库侧**新增 IndexedDB link 表（`evidence-vault-store` 版本 1 → 2，`onupgradeneeded` 按 `objectStoreNames.contains` 守卫创建，老库平滑升级——已由「v1 老库升级不丢数据」专项测试钉住）；不扩展 vendored asset provider 契约（避开 METHOD-WORKSHOP 工件治理）。
- 入口 A（主）：灵感资产卡新增「关联证据」区——按当前项目 + 标签重合 + **既有机器链种子**（knowledge-store 节点上已同时带 `assetId` 与 `evidenceIds`，同节点配对为最强信号）推导候选，用户勾选后点「建立关联（N）」显式建立，**绝不自动建**。
- 入口 B（反查，只读）：证据条目显示「被引用于」哪些灵感资产（标题由分区③传入，悬空资产如实标注）。
- 出口：图谱消费 link 表画「资产 → 支撑证据」边（`supports`，随「持久沉淀」范围收敛）；视图 hash 只编码焦点 id，不编码内容。
- 验收：候选推导与 link 去重走纯函数测试（`test/asset-evidence-links.test.js`，含 v1→v2 升级、证据删除联动清链、500 条保险丝、降级路径行为一致）→ 接线契约断言 → MANUAL-QA 现场条目（L1–L3）。
- Non-goals：不做自动建边、不做双向同步、不碰 `vendor/`、首版不进备份导出/导入（导出完成文案已如实注明「关联关系不在备份内」）。
- 已知约束：资产可从增强器知识区等 vendored 面板删除，删除钩子只能挂在自有 vault UI（已挂）——残余悬空由图谱末尾边过滤与反查兜底（进验收条目，不当边缘情况）。

**后续候选（按痛点登记，未定案）**：P1 草稿三出口互不知情（最小解：写入成功提示带来源标签 + 当前草稿前 N 字预览，不新增出口）；P2 目录「浏览型」缺下一步动线（注意：推荐下一步工作流 `recommendedWorkflowsForResources` 已存在于输入框弹层，工作台侧未接入——先复用再新造）；P9 领域预设「假全局」（最小解：分区①常驻条 + 目录默认收窄到相关类目，不碰工坊）；P6 核验激励（挂点在 P5：核验状态决定边的视觉权重）；P8 开启说明的防御性措辞精简（小活）。

## 明确暂缓（不做或暂不做）

以下方向**刻意不做**，理由是它们会重复 DSH 已承担的能力，并带来权限、保密、成本与状态同步问题：

- 自动并行子 Agent；
- 长任务调度与后台恢复；
- 自动化事实核查结论；
- 独立沙箱、成本限额与计算资源管理；
- 对原始科研数据的自动修改；
- 自带模型路由、自持 API Key 或独立 Agent 运行时。

若你认为其中某项对你有价值，欢迎开 Issue 说明使用场景——"暂缓"不等于"永不"，但需要有能说服人的理由。