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。