mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-08-04 19:45:34 +08:00
SaladDay
112 lines
8.8 KiB
Markdown
112 lines
8.8 KiB
Markdown
# Pi 支持项目级重启裁决:前置工程结构与测试先行
|
||
|
||
> 文档状态:项目级裁决(用户 2026-08-01 批准),优先级高于既有契约、修正案 1/2 的交付与审查结构条款;契约的技术条款(不变量、类型、义务)继续有效。
|
||
> 触发:R4 未通过,三个 invariant 家族第四次出现,按修正案 2 §G 项目级硬停止。
|
||
> 裁决依据:四轮证据表明问题不再是契约缺失或未落实(R4 时 oracle 已真实、类型屏障已就位),而是**认证单元过大**(12k 行 × 高不变量密度 × 零 High 标准 = 每轮必有新 High)与**实现方稳定的"九成对一成微妙错"率**共同作用。修复对象是认证结构与工作方式,不是再写一份修正案。
|
||
|
||
## 1. 新结构:三个前置工程 + 主工程,认证单元 ≠ PR 数量
|
||
|
||
单体累积认证(检查点 A/B/C)废止。改为:
|
||
|
||
| 工程 | 范围 | 认证对象 | 预算 |
|
||
|---|---|---|---|
|
||
| 前置 A | Provider 类型化写面 + endpoint 所有权(全 app) | `dao/provider_write.rs`、相关 service 入口、扫描器及其测试 | 2–3 轮 |
|
||
| 前置 B | Data-only canonical restore(含 R4 新发现:safety backup 并发丢写窗口、binary TOCTOU、incremental auto-vacuum 保留) | `database/backup.rs`、`schema.rs` 的 restore 面及测试 | 2–3 轮 |
|
||
| 前置 C | 只读 native inspection(完全由 pinned Pi 语义向量驱动) | `pi_config/raw_schema.rs`、`composer.rs`、`native.rs`、`gateway.rs`(capability 部分)、oracle 夹具及测试 | 2–3 轮 |
|
||
| 主工程 | Skills/Prompts/Sessions/UI/i18n + gateway 数据面 | 建立在已认证前置之上,认证结构届时另定 | 另计 |
|
||
|
||
- 每个前置工程是独立认证对象:两位 fresh blind reviewer 审**该组件的完整文件与测试**(组件级审计,不是 diff 审计),小到一轮看得透;
|
||
- 依据 handoff §2.2"双盲审数量不等于 PR 数量"与规则 8/9"同一 invariant 重复失败 → 重审 boundary 与 test strategy":重构认证结构正是执行该规则,各前置工程作为新认证对象持有独立小预算,这不是绕过七轮纪律,而是其结论;
|
||
- **最终交付仍是一个 PR**(用户要求不变);前置工程在同一分支上以 commit 组推进;
|
||
- 任一前置工程在自己的预算内不收敛 → 单独停止上报,不牵连其他工程。
|
||
|
||
## 2. 工作方式反转:测试先行
|
||
|
||
四轮共同病根之一是实现方的字面合规:契约文字与测试之间的任何缝隙都会变成缺陷。自本裁决起:
|
||
|
||
1. **Claude 先交付认证级测试套件**:把 R1–R4 审出的全部故障场景 + 契约义务固化为可执行测试(含扫描器负向 fixture);测试即契约的字面;
|
||
2. **Codex 实现到全绿**:不得修改认证测试(发现测试本身有错时,报告并由 Claude 裁决修订);可以自由增补自己的测试;
|
||
3. 全绿 + 内部自审(修正案 2 §F 对应节)后进入该前置工程的盲审;
|
||
4. 盲审 finding 若揭示测试套件的缺口,缺口先补进测试,再修实现——测试套件是活的认证资产,逐工程滚动加厚。
|
||
|
||
## 3. R4 finding 的归属(全部并入对应前置工程的测试范围)
|
||
|
||
| Finding | 归属 |
|
||
|---|---|
|
||
| managed DTO 把 thinkingLevelMap 收窄为 `Option<String>`,oracle 证明必须无损 | 前置 C |
|
||
| gateway 把 Authorization/x-api-key/x-goog-api-key 列为 protected 并强制 apiKey,header-auth 配置误降 DirectOnly | 前置 C |
|
||
| restore 行校验只查 storage class/JSON/decimal,`sort_index=-1` 可发布后生产读取失败 | 前置 B |
|
||
| safety backup 与 publish 之间并发丢写窗口;binary restore TOCTOU;canonical stage 丢 incremental auto-vacuum | 前置 B |
|
||
| `update_provider_settings_config` 绕过类型化写面且零行静默成功 | 前置 A |
|
||
| `reconcile_provider_record` 先查存在再分支,并发 create 冲突退化为覆盖更新 | 前置 A |
|
||
|
||
结构教训一并纳入:**DML allowlist 必须缩到 `provider_write.rs` 模块级**(R4 逃逸正是因为按文件豁免了整个旧 DAO);"252/252 字段执行过"不等于下游语义正确,前置 C 必须有 oracle→managed→inspection 的**端到端无损往返**测试。
|
||
|
||
## 4. 盲审材料与验证(每个前置工程)
|
||
|
||
- 材料:该组件的规范契约节选(中立重生成)、组件文件清单、oracle/provenance(前置 C)、验证命令、通用审查维度;不含任何轮次历史、finding、自审报告;
|
||
- 验证:`cargo fmt --all -- --check`、**`cargo clippy --lib --tests -- -D warnings`(必须带 `--tests`,认证模块是 `#[cfg(test)]`,不带就不编译它)**、`cargo test --lib` 全套 + 组件认证测试全绿 + 扫描器负向 fixture 红名单确认,均在干净 SHA 上;
|
||
- 完成条件:零 validated blocker/high/data-integrity finding。
|
||
|
||
> 文档考据说明:修正案 1/2(`pi-support-contracts-amendment-*.md`)的条款已按其自身要求**合并**进 `pi-support-contracts-zh.md` 与 `pi-support-review-contract-zh.md`,独立文件已随合并删除,这是预期状态而非丢失;本文引用的"修正案 2 §F/E1"以合并后的规范文档对应章节为准。
|
||
|
||
## 4.7 协议放宽:契约纲领化(用户裁决,2026-08-02,优先于 §2、§4)
|
||
|
||
自本条起,**所有后续契约以纲领为主**:只给目标与验收标准,实现方(编码 Codex)
|
||
获得相当大的自由度。§2"测试先行 + 冻结认证套件"的重仪式**不再默认适用**。
|
||
|
||
**保留的最小规则**(全部有实证代价支撑,不是仪式):
|
||
|
||
1. **既有测试不得弱化**:测试总数只增不减,盲审核对;
|
||
2. **冻结物不动**:pinned 夹具、已重冻的 infra 三文件、restore 面;
|
||
3. **行为主张须有证据**:凡断言"pinned Pi 如此行为",须有 oracle 或
|
||
request-capture 实证(`scripts/pi-transport-capture.mjs`)。此条是四轮
|
||
返工换来的——读源码推断先后写反过 Google header-only 契约与 authHeader 次序;
|
||
4. **不 push、不建 PR、不动 `stash@{0}`、不碰 PR #5598**。
|
||
|
||
**取消的**:精确红绿账本与"偏离即硬停止";每工程 2 轮 fresh 双审的固定配额;
|
||
实现路径、DTO 形状、测试组织方式的规定;裁决方逐条批准。实现方自行判断何时
|
||
完成,自行组织验证与审查,完成后报终态 SHA。
|
||
|
||
**审查范围(2026-08-02 补充)**:§1 的"组件级审计、不是 diff 审计"改为增量制——
|
||
① 某 SHA 上审干净即记为**已审基线**,之后只审 diff since 基线;
|
||
② 但**契约条款一旦新增或修改,其作用域必须全域扫调用点**(grep 定向扫描,不必通读),
|
||
这保住 R3 那类"契约写对而错误旧路径仍在"的漏网面;
|
||
③ 发 PR 前做**一次**完整组件通读作保险。
|
||
④ 验证 pinned Pi 行为**不再逐行读上游源码**:跑 oracle 或
|
||
`scripts/pi-transport-capture.mjs` 取实证,快一个数量级且更可靠。
|
||
|
||
**为什么放宽**:前置 A/B/C 的证据表明,重仪式的边际收益在下降而成本在上升——
|
||
后期盲审 finding 多为"防作弊机器"的自我军备竞赛,且契约越长裁决方自身出错越多
|
||
(表名、文件映射、虚假覆盖声称、与上游相反的契约,均为契约复杂化后的产物)。
|
||
实现方在四个工程中零作弊记录(精确硬停、拒改认证文件、顶住 reviewer 的错误建议),
|
||
信任已由行为挣得。
|
||
|
||
## 4.6 前置 B 终止关账(用户裁决,2026-08-02,优先于 §4.5)
|
||
|
||
§4.5 的缩围执行后,重认证 R1 仍在**存量产品面**出现 3 项 High(配置目录可变
|
||
性竞态、restore 未复用写面校验链、safety backup 可预测文件名)。用户裁决:
|
||
**PR 聚焦 Pi 业务,restore 老面放一放,不乱扩张**。据此前置 B **终止关账**:
|
||
|
||
- Pi 耦合面已达成且在两套认证套件中持续全绿,Pi 工程期间完成的加固随 PR 保留;
|
||
- 5 项未决 finding 与 v1–v15 历史导入移交 `docs/restore-hardening-debt-zh.md`
|
||
(独立"Restore 加固工程"债务登记),不在本 PR 范围;
|
||
- infra 基线(schema.rs/migration.rs/backup.rs)已在前置 A 套件中按 `3fa6b1f1`
|
||
状态**重冻**:本 PR 内任何再触碰即认证红,机械防止范围回潮;
|
||
- 前置 B 不再有重认证轮次;§4.5 的 N/N−1 缩围作为已落地事实保留。
|
||
|
||
## 4.5 范围修订(用户批准,2026-08-02)
|
||
|
||
前置 B 的不可信恢复(SQL/binary 双入口)缩围为**仅接受 user_version N 与 N−1**
|
||
(当前 16/17):迁移语义 invariant 家族四次复发均位于历史迁移链,其对抗深度与
|
||
"导入远古备份"的产品价值长尾严重不匹配。v1–v15 输入结构化拒绝;**本地升级链
|
||
v1→17 完全不受影响**(LocalUpgrade 就地迁移照旧);升级前备份(N−1)回滚路径
|
||
保留并专测。v1–v15 恢复立项为"历史备份导入"独立未来工程,已建成的
|
||
MigrationSourceSpec 架构留作其地基。
|
||
|
||
## 5. 冻结事实(2026-08-01)
|
||
|
||
- 分支 `feat/pi-native-support`,HEAD = 10f2dacb(R4 检查点),工作树干净;
|
||
- R1–R4 已耗于已废止的单体认证;前置工程各持新的 2–3 轮预算;
|
||
- 未 push、无 PR;`stash@{0}`、`legacy/pi-041ff113`、PR #5598 不触碰。
|