# Stage 4：Plan / Artifact / Knowledge Reference Bridge

## 目标

以 Markdown-first、Reference-first 的方式，把计划、产物和知识提供者连接成
可追踪的公共元数据图。Stage 4 不读取 Markdown 正文，不解析私有知识库，不
上传内容，也不把本机路径变成公共引用。

## 交付范围

- 新增 `artifact` 公共契约，并给 Plan、Artifact、Knowledge Reference 增加
  有界的 `*Ids` 关系和可选 `updatedAt`。
- 新增 `src/bridge/index.mjs`：
  - `createReferenceSnapshot()` 只验证和解析已提供的契约对象；
  - `createReferenceOnlyProvider()` 只提供 `listReferences()` 和
    `describeReference()`；
  - Provider 不提供 `sync()`、上传或正文读取操作。
- 生成可安装的 `lib/bridge.js`，从根包导出公共 Bridge API。
- DSH Host 增加 `artifactBoard()` 和 `knowledgeReferenceCatalog()`，并让
  `planPanel()` 返回链接计数与 ID。
- DSH Web 增加独立的 Artifact Board、Knowledge References 面板；每个面板
  都有自己的 Cordis effect、disposer、错误边界和卸载路径。
- 添加全是合成数据的契约、配置、Bridge 和 Bundle 测试。

## 数据边界

允许跨边界的数据只有 ID、标题、状态、Provider、可见性、opaque `ref`、
sha256 `contentHash`、更新时间和有界 ID 列表。禁止 `content`、Markdown
正文、`body`、`transcript`、消息数组、原始聊天和绝对路径。

`ref` 只允许 `fixture://`、`local-config://` 或 `opaque://`。`file`、
`repository`、`url` 和 `plugin` Provider 在本阶段只是契约枚举和元数据
适配点，不代表会自动读取或同步对应来源。

## 非目标

- Markdown 文件发现、全文索引、向量化、搜索或内容上传；
- 远程知识库连接、Webhook、云端同步和自动提交；
- 计划编辑器、任务调度器和跨 Runtime 执行动作；
- 任何运行时的任意 shell 入口。

## 验收证据

1. 合约与 Bridge 测试验证链接解析、Provider 元数据读取、未解析链接拒绝、
   原始内容字段拒绝和 JSON-safe 投影。
2. `npm run build:dsh` 生成根包 Bridge 与 Web Bundle。
3. `npm run check`、DSH Extension preflight、`npm pack --dry-run` 通过，
   tarball 不含本机路径、凭据、私有内容或被忽略的机器配置。
4. 在隔离 DSH Web Profile 中冷启动，合成 Plan、Artifact、Knowledge
   Reference 可显示；卸载、禁用和恢复只影响新增控制面板。
5. 使用脱敏 `.reviews/stage-4/REVIEW-PACK.md` 请求本地 DSH DeepSeek Pro
   审核，并由父 Agent 对照真实 diff 和测试结果复核。

## 恢复方式

删除隔离 Profile 中的 `dsh-control-plane` Loader 行或使用 Profile overlay
禁用该行，然后重启 DSH；Host/Client 新增面板应消失，DSH 主体仍可启动。
重新移除禁用 overlay 并重启即可恢复。

## 状态

本文件只定义 Stage 4 的实现边界。是否完成必须以根路线图、测试输出、隔离
Profile 证据和脱敏 DeepSeek Pro 审核记录共同决定。