Pi Extensions 一等支持设计附录

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

目标

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

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

模块边界

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 且产品明确展示该覆盖时，才允许自动解析。

实施前验收

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

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

4.3 KiB Raw Blame History Unescape Escape