# Pi Extensions 一等支持设计附录

> 状态：仅设计，不含实现。主工程不实现 extensions；themes 明确不在范围内。
> authority：任何上游路径、加载顺序、启用规则或 tool 组合语义，在实施前都必须
> 由 pin `ab366ebe94cacd419d986be454f12b1b9913aaca` 的 oracle 或
> `scripts/pi-transport-capture.mjs` 实际执行确认，本文不以源码阅读代替证据。

## 目标

未来让用户在 cc-switch 中观察、导入、启用和停用 Pi extensions，同时满足：

1. 原生文件/目录是真相，`exists = active`，不制造与 Pi 分叉的 enabled 影子状态；
2. 只接管 cc-switch 明确拥有或用户显式、可验证采用的内容；
3. extension 提供的 tools 与 pinned core tools 分开展示，不伪装为 MCP server；
4. 所有写操作可并发检测、可补偿，portable import 不覆盖目标设备的未知资产；
5. 复用前置 C inspection 与当前 Skill/Prompt 的共享文件、fingerprint、ownership
   和协调器原语。

## 模块边界

```text
PiExtensionInspector (只读、oracle 驱动)
        │
        ├── NativeExtensionObservation
        │      path / fingerprint / manifest / contributed tools
        │      validity / reasons / ownership
        │
        └── PiExtensionCoordinator (唯一写入口)
               ├── exact-content adoption
               ├── CAS + atomic replace
               ├── ownership ledger transaction
               ├── catalog epoch / UI invalidation
               └── compensation on partial failure
```

- `PiExtensionInspector` 只负责原生观察和结构化诊断；不得写数据库或文件。
- `PiExtensionCoordinator` 是唯一写入口；命令、deeplink、portable reconcile 与
  UI mutation 都调用它，禁止各自复制目录。
- 通用 `shared_file`、Skill tree fingerprint 与 ownership ledger 可复用；
  extension-specific manifest/加载规则必须先新增捕获向量，不能借 Skill 规则猜测。
- gateway 只消费 coordinator 发布后的 immutable runtime snapshot；extension
  不能在请求中途直接改 candidate/header 计划。

## 状态模型

建议公开三个正交维度：

- `discovery`: `absent | active | invalid | unknown`，只来自 native observation；
- `ownership`: `external | adoptable_exact | managed | conflict`；
- `capability`: `inspectable | manageable | unsupported | unknown`。

不得增加独立 `enabled` 布尔值。用户点击“停用”时，语义是对受管原生资产执行可逆
移除；外部资产只能显式采用后再管理。内容变化导致 fingerprint 不匹配时进入
`conflict`，不得覆盖。

## Tools 与 MCP

- capture 已确认 pinned core tool inventory 为
  `bash/edit/find/grep/ls/read/write`；未来 capture 应分别记录每个 extension
  注入前后的 tool inventory 与来源。
- UI 将 tools 按 `core` / `extension:<id>` 分组，并展示冲突与覆盖次序的实测结果。
- MCP 页面仍不为 Pi 建虚假 registry。即使某个 extension 通过自身机制连接外部
  tool，也属于 extension capability，除非未来 pinned Pi 真正提供 MCP registry
  且由新证据和契约明确升级。

## Portable 与冲突策略

- 备份只携带 cc-switch 拥有的 extension 描述、内容 hash 和期望状态，不携带绝对
  目录、设备 token 或未知外部目录。
- 导入先观察目标设备；missing 可部署，exact 可采用，different 必须 conflict，
  绝不“最后写入者获胜”。
- 多 extension 贡献同名 tool、command 或资源时 fail-closed；只有 oracle/capture
  证明 Pi 的确定 precedence 且产品明确展示该覆盖时，才允许自动解析。

## 实施前验收

1. 扩展 transport capture：发现路径、空/损坏 manifest、启停、重复 ID、资源覆盖、
   tool inventory、相对路径和 symlink 负例。
2. 冻结 schema/oracle provenance，建立 lossless raw observation；未知形状为
   `unknown`，不得整目录连坐隐藏合法兄弟。
3. 服务级测试覆盖显式采用、并发 CAS loser、写后补偿、portable reconcile、
   外部冲突、目录越界与 UI 的 `exists = active`。
4. 中英文 UI 与可访问性完成后，再进入独立实现与盲审。

Themes 不与 extensions 共用该项目：其资源语义、预览与安全面另行立项。