# Pi → DSH 架构映射标准

本标准规定 pi2dsh 如何回答三个问题：理论上应该怎样兼容、当前实际上怎样兼容、问题
应归因给 pi2dsh 还是 DeepSeek Harness（下文简称 DSH）。

## 先说清楚：这条链是方法，不是架构层

```text
具体接口
→ Pi 能力契约
→ DSH 承载机制
→ DSH 公开 seam
→ 实际插件验证
→ 五级结论
```

这不是六层产品架构，也不是要求我们提前写完一张“永远完整”的接口表。它是分析任何
新接口、新插件时都要走一遍的**统一推理路线**：从真实调用出发，逐步证明语义、责任
归属、可实现性和实际结果，最后才下结论。

每一步解决一个不同的问题：

| 步骤 | 它回答什么 | 为什么不能跳过 |
|---|---|---|
| 具体接口 | 插件到底调用了哪个 API、事件或嵌套方法？ | 不从真实调用出发，容易讨论一个生态里根本没人依赖的假问题 |
| Pi 能力契约 | 这个接口真正保证什么：时机、数据、控制权、生命周期和呈现？ | 同名 API 可能语义不同，多个不同 API 也可能共同完成一项能力 |
| DSH 承载机制 | 按 DSH 自己的设计，这项责任应该属于会话、模型、工具、交互还是客户端？ | 防止为了“跑通”把状态随手塞进桥内，制造第二套宿主 |
| DSH 公开 seam | 仓外插件实际能否接入那个机制，入口是 service、provider、waterfall、event 还是 client slot？ | DSH 内部有代码不等于外部插件有权使用；没有公开插口就不能说架构可承载 |
| 实际插件验证 | 真实插件是否沿预期路径走到了 DSH 权威状态和用户结果？ | 单测、能挂载、能 import 都不能证明完整场景成立 |
| 五级结论 | 这项能力是原生承接、可靠翻译、旁路、缺失，还是宿主专属？ | 统一尺度后，才可以比较不同插件并决定该修桥还是推动 DSH 开 seam |

例如 `appendEntry()` 不是“有地方写一段 JSON 就算支持”。它的 Pi 契约是把插件自定义
事实写进会话，并在恢复、分支、压缩和回放后仍保持语义。DSH 有 session log 这一承载
机制，但仓外插件若没有 namespaced custom-entry 写入 seam，pi2dsh 写 sidecar 虽然能让
pi-btw 工作，也只能判 **3 级旁路完成**。这条链让我们准确说出卡在哪里，而不是笼统地
说“session 不兼容”。

## 第一部分：架构模型

### Pi：能力域 → 能力契约 → 具体接口

能力契约描述用户真正依赖的保证，而不是按源码文件机械分组。每项契约要说明：

- 用户目标；
- 介入时机；
- 读取或修改的权威状态；
- 生命周期与清理；
- 用户最终在哪里看到结果。

具体 API、事件、context 方法和嵌套 callable 都作为契约下面的叶子记录。发现新叶子就
补到相应分支；现有分支装不下时，先检查抽象是否错了，再拆分或新增能力契约。

### DSH：架构域 → 承载机制 → 公开 seam

DSH 侧也按责任组织：插件组合、会话、模型、执行、资源、编排、交互、客户端等。模块、
service、provider、waterfall、event 和 client slot 是这些机制下面的具体叶子。

判断可兼容的关键不是“DSH 内部有没有这个模块”，而是“仓外插件有没有公开 seam 能在
正确时机读写正确的权威状态”。内部私有函数不算 seam，事后通知也不能替代事前决策。

### 映射原则

Pi 契约与 DSH 机制从五个维度比较：用户目标、介入时机、权威状态、生命周期、原生
呈现。理论结果分四类：

| 理论结果 | 含义 |
|---|---|
| 直接承接 | 一个公开 DSH seam 可以表达完整契约 |
| 组合承接 | 需要多个公开机制组合，但仍使用 DSH 权威状态 |
| 宿主语义翻译 | 目标可保留，但 Pi 终端表示需要改成 DSH Web/CLI 表示 |
| 缺公开 seam | 正确数据或决策时机位于仓外插件不可到达的位置 |

## 第二部分：验证矩阵

理论映射说“应该怎么接”，实践记录说“实际上有没有接住”。真实插件必须沿五层取证：

```text
Pi 插件实际调用
→ pi2dsh 实际翻译
→ DSH 公开 seam
→ DSH 原生权威状态
→ 用户可观察、恢复和回放的结果
```

每项能力单独判级，禁止给整包一个含糊的“兼容”：

| 等级 | 判定 | 标准 |
|---:|---|---|
| 1 | 原生承接 | 公开 seam 直接完成，事实进入 DSH 原生状态和界面 |
| 2 | 可靠翻译 | 表示不同但目标完整，没有第二套 runtime 或权威状态 |
| 3 | 旁路完成 | 用户能用，但依赖 sidecar、桥内 store 或自有展示通道 |
| 4 | 降级或缺失 | 时机、数据或控制能力不完整，只能拒绝或 no-op |
| 5 | 宿主专属，不计分 | Pi 终端/CLI 实现不应原样搬到 DSH |

## 第三部分：架构结论

| 证据组合 | 结论 |
|---|---|
| 合理映射 + 已实现 + 真实插件达到 1/2 级 | 已证明成立 |
| DSH 有合理公开 seam，但桥未接好 | pi2dsh 欠账 |
| 缺公开 seam，且有真实消费者、完整数据流和最小复现 | 已确认 DSH 缺口 |
| 属于 Pi 特定终端实现 | 宿主差异 |
| 理论能映射但未走真实插件 | 理论可行、尚未实证 |

## 文档怎样组织

架构知识只保留四层普通 Markdown：

```text
映射标准（本页，只定义方法）
  ↓
架构模型（可扩展知识树 + 理论映射）
  ↓
插件验证（真实插件记录块）
  ↓
架构结论（只汇总三类结果）
```

不建立架构 JSON 总账，不用生成器产出架构结论，也不在 CI 写死接口或模块数量：

- [`architecture-mapping-matrix.md`](architecture-mapping-matrix.md)：可扩展的 Pi/DSH
  Markdown 知识树和理论映射；
- [`plugin-validation-matrix.md`](plugin-validation-matrix.md)：按插件分块、逐项走五层后的
  实践记录；
- [`dsh-architecture-conformance.md`](dsh-architecture-conformance.md)：已成立、桥欠账和
  DSH 缺口三类总体结论。

运行时 [`capabilities/`](capabilities/README.md) 仍可从代码生成，但它在这四层架构知识
之外，只说明当前实现行为，不参与自动生成理论分类或架构结论。

## 开放世界原则

架构抽象应相对稳定，接口和模块清单必须允许继续生长。曾经盘出的 “111 条 Pi 规则”
和 “45 个 DSH 子系统”只代表特定版本、特定扫描口径下的**当前快照**，不代表完整总量，
也不是标准的前提。嵌套对象、动态注册面、客户端能力或新版本模块都可能让清单增加。

因此维护时遵守四条：

1. 新接口或模块优先追加到现有 Markdown 分支，不因数字变化改标准；
2. 新事实无法合理落入现有分支时，允许拆分抽象并说明原因；
3. 数量只能带版本和口径出现，不能用固定数量证明“全覆盖”；
4. 自动化只核对运行时直接生成的事实，不生成架构分类、理论映射或归因结论。

以后汇报单个插件，固定回答：用了哪些 Pi 能力、理论应落到哪些 DSH 机制、公开 seam
是什么、五层实际走到哪里、每项达到哪一级、最终归因是什么。汇报总体情况则沿同一套
Markdown 分支汇总，不再依赖聊天记录，也不把某次扫描数字冒充永恒边界。