CC-Switch/docs/pi-main-project-zh.md

Pi 主工程契约(纲领)

适用规则:docs/pi-support-restructure-zh.md §4.7(契约纲领化、协议放宽、增量审查)。 前置 A/B/C 已认证;本文是本工程唯一契约,不再有逐条裁决。 技术不变量以 docs/pi-support-contracts-zh.md 的五份契约为准(未变)。

目标

把 Pi 做成 cc-switch 的一等公民 app,与 Claude/Codex/OpenCode/Hermes 同级: 用户能在 Pi 这个 app 下管理供应商、模型、Skills、Prompts、Sessions、MCP, 能用网关代理它,能看到原生 models.json 的真实状态而不被我们的抽象骗。

验收标准

1. 同级:AppType::Pi 在既有 app 的每一条通路上都存在且行为一致—— 供应商与端点、切换与故障转移、Skills/Prompts/Sessions、MCP、深链、设置、 目录配置、可见性、使用统计、导入导出。以 Hermes 为最近先例逐条对照; 凡先例有而 Pi 没有的通路,要么实现,要么在本文件写明为何不适用。
2. 原生真实:Pi 的原生资产(models.json、AGENTS.md / SYSTEM.md / APPEND_SYSTEM.md、prompts、sessions)以 pinned Pi 的语义读写; exists = active,不造影子状态;只读检查面已由前置 C 认证,主工程复用它, 不得另起一套判定。
3. 网关数据面:Pi 供应商可经网关代理;候选物化、失败转移、协议身份沿用 前置 C 认证的判定结果。OAuth 凭证(sk-ant-oat 子串)在本工程实现—— Anthropic 族按实测发 Authorization: Bearer + oauth beta 头、不发 x-api-key; 完成前维持前置 C 的诚实降级(DirectOnly),不得半实现。
4. 可用:UI/i18n 中英文齐全;新用户能从零添加一个 Pi 供应商并切换成功。
5. 不回退:测试总数只增不减;既有 app 的行为不受影响。

边界

• 不碰:pinned 夹具、已重冻的 infra 三文件(schema.rs/migration.rs/backup.rs)、 restore 面(见 docs/restore-hardening-debt-zh.md)、三份认证套件、 stash@{0}、PR #5598;
• extensions 只做设计附录,themes 不做(用户已裁定);
• 不 push、不建 PR(终态交付仍是一个 PR,由用户决定何时发)。

证据规则

凡断言"pinned Pi 如此行为",须有 oracle 或 scripts/pi-transport-capture.mjs 的实证,不接受读源码推断——这是四轮返工换来的唯一保留仪式。

自由度

范围划分、commit 粒度、DTO 与模块组织、测试组织、验证与审查节奏,全部自定。 不必对齐红绿账本,不必按固定轮次做盲审,偏离不必硬停上报。 遇到本文与既有契约冲突、或需要用户拍板的产品取舍(功能取舍、范围增删), 才上报;其余自行裁量,完成后报终态 SHA。