diff --git a/issues/plugin-refactor/phase-3_platform/PHASE_SUMMARY.md b/issues/plugin-refactor/phase-3_platform/PHASE_SUMMARY.md new file mode 100644 index 0000000000..7e89d5464d --- /dev/null +++ b/issues/plugin-refactor/phase-3_platform/PHASE_SUMMARY.md @@ -0,0 +1,34 @@ +# 阶段总结报告: Phase-3 平台 Provider 接缝(收窄版) + +- **阶段状态**: Completed +- **完成时间**: 2026-06-12 +- **关联阶段计划**: [链接](../../../.claude/plugin-refactor/phases/phase-3_platform/PHASE_PLAN.md) + +## 1. 阶段目标达成情况 + +1. ✅ 前置特征化 T1-T5 先行(7 测试 + antigravity bench×2 入基线); +2. ✅ `internal/gatewayplatform` 落地(Provider 两方法 v1 接口 + 构造期注册 Registry + 3 个单语句直返 adapter),Messages 端点两处平台分发经 registry,行为零变化(审计逐字符等价核对); +3. ✅ 可选小项:默认模型同构 switch 收敛单一来源; +4. ✅ 实施后对抗审计零 P0/P1(3 个非阻塞 P2 登记),突变 3/3 捕获; +5. ✅ OpenAI/v1beta/内核零触碰;每任务即提交 preview-dev(57a2e718 / f08f9111 / 625c691b)。 + +## 2. 任务完成统计 + +| 任务 | 状态 | 报告 | +|---|---|---| +| TASK-001 前置特征化 T1-T5 | Completed | [链接](./TASK-001_dispatch_characterization.md) | +| TASK-002 gatewayplatform 接缝 | Completed | [链接](./TASK-002_gatewayplatform_seam.md) | +| TASK-003 默认模型 switch 去重 | Completed | [链接](./TASK-003_default_models_dedup.md) | +| TASK-004 实施后对抗审计 | Completed | [链接](./TASK-004_post_audit.md) | + +## 3. 关键技术成果与裁决 + +- **诚实收窄**:双视角评审纠正摸底三处事实错误(OpenAI 路径归属、:794 条件语义、"Batch-1 六点"的集中化现状),Phase-3 从"消灭 19 个分发点"收窄为"Forward 承重接缝(2 点)+ 一处真实重复去重"——19 点中其余要么已集中化、要么永久留核心(清单归档); +- **Forward 承重接缝就位**:Phase-4 搬家的载体接口(Provider/ForwardRequest)已建立并被特征化与审计双重锁定; +- **禁止事项固化**:跨平台 result 统一(载荷计费字段)、错误包裹(errors.As 链)、为单点凑接口——三条都进了归档评审; +- Runtime 实例访问 API 改为可观测触发条件(首个真实 gateway.hook.* 模块进插装清单)。 + +## 4. 遗留与展望 + +- P2 观察项 ×3(Registry miss 防御 / bench 不覆盖 handler 层分配 / 测试夹具 nil service 脆弱性)——非阻塞备查; +- **Phase-4(搬家与领域拆分)就绪条件**:gatewayplatform/gatewayhook 两个承重接缝在位、安全网完备(45 包 + 9 基准)、每任务即提交纪律运转中。Phase-4 启动时需先规划:平台代码搬家顺序(建议从最小的 anthropic 9.7K 起)、依赖收敛为 ports 的路径、channel/notify 域拆分。 diff --git a/issues/plugin-refactor/phase-4_relocate/PHASE_SUMMARY.md b/issues/plugin-refactor/phase-4_relocate/PHASE_SUMMARY.md new file mode 100644 index 0000000000..5b10853695 --- /dev/null +++ b/issues/plugin-refactor/phase-4_relocate/PHASE_SUMMARY.md @@ -0,0 +1,30 @@ +# 阶段总结报告: Phase-4 平台代码搬家与域拆分 — Deferred + +- **阶段状态**: Deferred(2026-06-12,双视角评审实测裁决) +- **交付物**: C-C 依赖测绘(本目录 + .claude/plugin-refactor/phases/phase-4_relocate/INVENTORY.md) + +## 1. 裁决 + +Phase-4 原计划"把平台代码搬入独立包以铺路插件模块化",经双视角评审**实测证伪可行性前提**,裁决:**整包搬家 Deferred,本阶段交付依赖测绘**。 + +## 2. 决定性证据(实测,非估算) + +1. **规模认知硬伤**:摸底称"openai 7168 行单文件",实为 **46 非测试文件 ~29K 行 + 69 白盒测试 ~35K 行**的完整子系统; +2. **循环依赖已编译器证实**(`go build` → `import cycle not allowed`):正向 openai 引用 178 个 service 符号(64 未导出)、反向 service 引用 57 个 openai 符号;4 类骨架级反向硬耦合(ops_service 内嵌 struct / image_billing 签名吃 OpenAIForwardResult / token_refresh 构造器 / wire.Bind)+ 2 个接口(AccountRuntimeBlocker、OpenAI403CounterCache)定义在 openai 卫星却被 ratelimit/admin 核心消费; +3. **gate 缺失**:69 个 openai 测试 100% 白盒 `package service`,整包移动会让它们自己先编译不过——无稳定黑盒等价锚点; +4. **循环论证 + 无拉动**:L2 模块化触发=搬家完成、搬家收益=为 L2 铺路(自指);无任何待实现 gateway.platform.* 模块、无 Host 扩容、无测试隔离困难; +5. **先例一致**:Phase-2 对 payment.provider.*(5 文件、更弱耦合)已 Deferred,Phase-4(46 文件、双向硬环)无理由更激进。 + +## 3. 重启触发条件(任一满足) + +- 出现具体 gateway.platform.* 模块实现需求; +- openai 集群测试隔离产生可度量困难; +- service 包规模使 CI 编译时间成为可度量瓶颈。 + +## 4. 真实架构债务发现 + +`AccountRuntimeBlocker` 接口命名为 OpenAI 专属、定义在 openai 卫星文件,实为 RateLimitService/AdminService 的通用调度依赖——归属错误。修复属独立重构 PR(消费者侧定义接口 + 重命名契约 + 安全网全量验证),非搬家。 + +## 5. 经验 + +本阶段是"多轮审计制度"价值的最强体现:架构师把"搬家 ROI 是否循环论证"作为元问题主动提交评审,两个独立视角用编译器实测 + 符号级 grep 共同证伪了一个看似自然的下一步。**最优的架构决策有时是用证据证明某个动作现在不该做**——避免了一次 150+ 文件、零行为收益、必然成环的高风险改动。 diff --git a/issues/plugin-refactor/phase-4_relocate/REVIEW-ARCH.md b/issues/plugin-refactor/phase-4_relocate/REVIEW-ARCH.md new file mode 100644 index 0000000000..68406c7b76 --- /dev/null +++ b/issues/plugin-refactor/phase-4_relocate/REVIEW-ARCH.md @@ -0,0 +1,28 @@ +# Phase-4 评审 — 架构合理性/演进视角(2026-06-12) + +> 评审对象:SEAM-DESIGN v1。裁决见 SEAM-DESIGN v2【裁决记录】。 + +## 元问题立场 + +**Phase-4 第一刀应停在 C-C(测绘)+ ROADMAP 标 Deferred-until-pulled,不以 L1 推进。** + +## 核心论证 + +- **循环依赖面真实且宽**:openai 集群(46 文件 65K 行含测试)子包化双向成环;反向边经 6 个核心文件结构级引用 openai 专属类型(ops 内嵌 struct、image_billing 签名、token_refresh 构造器、wire.Bind、ratelimit/admin 经 AccountRuntimeBlocker 接口); +- **"零消费 GatewayService 方法"前提在子包视角失效**:同包语义为真,子包化后正向 178 符号 + 反向 57 符号双向锁死; +- **循环论证成立**:L2 触发=搬家完成、搬家收益=为 L2 铺路,自指;无外部拉动信号(无待实现模块/无 Host 扩容/无测试隔离困难); +- **先例一致**:Phase-2 payment.provider.*(5 文件、更弱耦合)已 Deferred,Phase-4 无理由更激进;Phase-3 对 gateway.hook.* 用"可观测触发条件"是正确模式。 + +## 裁决表 + +| # | 裁决 | +|---|---| +| Q1 | C-C;L0 正交(可读性,不支撑架构目标,不作第一刀);L1 否决 | +| Q2 | C-C 优先;C-A 前提被推翻(4 类硬环);C-B 无架构价值 | +| Q3 | 不第一刀做、不单列前置——C-C 测绘后基于成本决定;AccountRuntimeBlocker 归属错误记为债务 | +| Q4 | 现有特征化不足以 gate 整包移动(但非主阻塞,主阻塞是循环依赖面);测绘中清点白盒测试改造量 | +| Q5 | 是,应 Deferred + 可观测触发条件 | + +## 架构债务记录 + +`AccountRuntimeBlocker` 定义在 openai 卫星文件,却被 ratelimit_service.go(热路径)与 admin_service.go 消费——命名与归属错误。应由消费者侧定义接口。修复属独立重构周期(重命名/契约调整 + 安全网),非搬家。 diff --git a/issues/plugin-refactor/phase-4_relocate/REVIEW-RISK.md b/issues/plugin-refactor/phase-4_relocate/REVIEW-RISK.md new file mode 100644 index 0000000000..04c7885060 --- /dev/null +++ b/issues/plugin-refactor/phase-4_relocate/REVIEW-RISK.md @@ -0,0 +1,29 @@ +# Phase-4 评审 — 回归风险/循环依赖/YAGNI 视角(2026-06-12) + +> 评审对象:SEAM-DESIGN v1。结论与架构评审收敛:第一刀 C-C + Deferred。实验性移动已 git checkout 还原,工作区干净。 + +## 量化风险账(实测) + +- **规模硬伤**:设计称"openai 7168 行单文件",实为 46 非测试文件 ~29K 行 + 69 测试文件 ~35K 行; +- **循环依赖已编译器证实**:构造正向+反向 import 后 `go build` 报 `import cycle not allowed`——非"可能成环"而是必然; +- 正向 178 符号(64 未导出须导出/下沉);反向 57 符号(19 导出/38 未导出),含 4 类骨架级硬耦合(struct 内嵌/签名/构造器/wire.Bind); +- **gate 致命缺口**:69 个 openai 测试 100% 白盒 `package service`,move 后自身编译不过——用于证明等价的 gate 会被这次 move 摧毁,无稳定黑盒锚点; +- **diff 估算**:最小可编译动作触及 150+ 文件、导出 64 符号、下沉含计费载荷的类型、改写 69 测试,数千行——功能变化为零。 + +## 裁决表 + +| # | 裁决 | +|---|---| +| Q1 | C-C,本阶段不动代码 | +| Q2 | 必撞环(已实测);三选 C-C | +| Q3 | 下沉必须单列前置,绝不第一刀做(含 OpenAIForwardResult 计费载荷 R-2.1 高危) | +| Q4 | 不够,明确不通过(仅 3 passthrough 特征化,主体 29K 无黑盒) | +| Q5 | Deferred 成立(五项全中 YAGNI/过度设计:高 diff/零收益/必成环/gate 缺/无拉动) | + +## YAGNI 裁决 + +对照 CLAUDE.md"禁止过度设计:不为假设的需求编码"——openai 子包化无真实 L2 拉动,ROADMAP 的 L2 触发条件"搬家完成"是自指循环论证。高 diff 零行为收益是教科书反例。 + +## 副产品建议(R6) + +未来若推进,正确顺序:先黑盒化测试建 gate → 先打破反向边(接口化/类型下沉/AccountRuntimeBlocker 归位,**无需搬家**的低风险依赖收敛,独立 PR)→ 再评估子包化。R6 中最低风险高价值单项=AccountRuntimeBlocker 归位,列为需用户决策的可选下一步。