PlantAI-dev/docs/superpowers/specs/2026-07-10-ppi-code-convergence-design.md

PPI ID 修订代码收敛设计

日期：2026-07-10

目标

在不丢失已经生效的 PPI ID 功能、不增加新功能的前提下，收敛本轮修订产生的代码和测试复杂度，使生产执行路径易读、可维护、可用真实 Ft→soe 数据验证。

本轮要保留的用户价值只有：

1. 目标 canonical ID 始终保留，不被参考物种或 STRING ID 替换。
2. 保留 canonical ID → Ortholog reference ID 的逐关系证据。
3. 使用参考注释包中的 accession、NCBI GeneID 等本地证据完成 STRING ID 映射。
4. 输出 STRING preferredName 和完整 ID 对照表。
5. 区分“STRING 正常返回空网络”和“HTTP/JSON/API 请求失败”。

当前基线

只读盘点显示：

• skills/ppi/run.py：Task 3 前 574 行，当前约 1301 行，净增加约 690 行。
• 新增 gfa_core/id_resolution.py：约 396 行。
• 新增 gfa_core/string_rate_gate.py：约 163 行。
• tests/unit/test_ppi_id_resolution.py：约 1523 行。
• tests/unit/test_id_resolution.py：约 281 行。

这些数字用于发现复杂度，不作为机械删代码指标。任何收敛都必须以功能等价和真实数据验证为前提。

约束

必须保留

• 已由生产路径实际调用、并直接支持上述五项用户价值的行为。
• 已经生效的空网络与 API 失败分类。
• 已经生效的 ID provenance 和 preferred name 输出。
• 当前确实参与生产请求的基本超时、请求节流和错误处理。
• 参考包 ncbi_gene_id 字段以及共享本地别名读取能力。

不得发生

• 不整体回滚 PPI 修订。
• 不永久删除本轮已有实现或测试；移出活跃路径的内容必须先归档。
• 不增加 Reset、CLI 新参数、Manifest 新结构、前端新展示或新的 STRING 协议能力。
• 不为单一调用点创建新的通用框架、插件层、配置层或额外兼容层。
• 不因为追求行数而改坏已经通过的科学语义。

归档策略

修改前，将本轮相关文件完整复制到：

项目记录/代码归档/2026-07-10_PPI_ID修订收敛前快照/

归档至少包含：

• skills/ppi/run.py
• gfa_core/id_resolution.py
• gfa_core/string_rate_gate.py
• gfa_core/ppi_string_policy.py
• apps/web/pipeline_backend.py 的完整快照
• 三个相关单元测试文件
• 当前测试命令、结果和代码行数记录

活跃文件中不保留数百行被注释代码。确认不参与生产路径的实现进入归档，原位置只保留必要的简短说明。

收敛方法

1. 建立可信基线

当前会话曾在修改过程中被中断，因此不得直接假设磁盘状态仍是最后一次绿色状态。

先运行现有聚焦测试、后端相关测试和静态检查。若当前状态不绿，只处理被中断的局部修改，使其回到可验证基线；不得借此增加新功能。

2. 标记真实生产路径

以 CodeGraph 和直接调用检查确认唯一活跃流程：

pipeline_backend → skills/ppi/run.py → 本地 ID map → STRING mapping → STRING network → resolution/network artifacts

每个保留的类、函数和字段必须至少满足一项：

• 位于这条生产调用链；
• 直接生成用户需要的 ID/provenance 产物；
• 是保证现有请求成功、空网络分类或错误分类所必需的最小逻辑。

3. 简化而不改变行为

• 合并只在一个位置使用的薄封装。
• 合并重复的字符串、taxon、候选 ID 转换。
• 减少只为中间状态存在的数据对象；保留最终逐关系结果结构。
• 删除活跃路径中已经确认无调用的兼容分支，但在归档中保存原实现。
• 保留共享别名模块边界，但把单用途证据对象和重复索引压缩为最小实现。
• 保留请求节流能力；若现有实现能在更少代码下保持相同并发行为，允许等价重写，否则原样保留。

每次重写必须先有等价测试，不能一次性重写整个 PPI 文件。

4. 测试收敛

活跃测试重点保留约 15–25 个行为场景：

• canonical/Ortholog 逐关系保留；
• exact accession 与 versionless accession；
• GeneID fallback；
• 收敛与歧义；
• 部分映射和零映射；
• 24 条关系、12 个查询的真实形状；
• preferredName 输出；
• 空网络成功；
• HTTP/JSON 失败；
• 生产路径确实使用解析后的 STRING ID；
• 参考包 numeric GeneID 不覆盖 LOC gene ID；
• 一个节流/并发核心测试。

重复验证同一内部实现、只覆盖极端伪造协议响应的测试移入归档。核心测试必须面向行为，不绑定可以被简化的内部类和私有方法。

验证

分步验证

1. 收敛前基线：记录测试结果、行数和生产调用路径。
2. 每个小改动：运行相关最小测试集合。
3. 收敛完成：运行 PPI/ID/backend 聚焦回归和 Python 静态检查。
4. 真实数据：使用现有 Ft→soe 项目数据执行 PPI ID 解析和网络阶段。

真实数据验收

真实 Ft→soe 结果必须证明：

• canonical target ID 数量和原输入一致；
• 每条 Ortholog relationship 都保留 exact reference accession；
• raw accession 和 GeneID fallback 均能在对照表中解释；
• 输出包含 STRING ID 和 preferredName；
• 网络为 0 条时，如果 API 正常返回空列表，阶段仍为成功且标记 empty network；
• API 故障不能伪装成 0 interactions；
• 不依赖测试 fake 得出最终结论。

如果当前环境无法访问 STRING，必须如实报告，并至少完成真实本地 ID map 与请求前 selected STRING ID 验证；不得声称完成在线网络验证。

完成标准

• 已生成可恢复的收敛前归档。
• 活跃生产路径没有确认无调用的兼容分支或重复实现。
• 活跃测试聚焦用户行为，重复/极端内部测试已归档。
• 所有保留功能通过收敛前后对比验证。
• 完成真实 Ft→soe 验证或明确记录唯一外部阻塞。
• 最终报告给出：归档位置、修改文件、收敛前后行数、测试结果、真实数据结果和未验证风险。
• 不以达到某个行数为完成条件，但不得再出现与一个 PPI ID 功能不成比例的新增框架。