sub2api-cn-relay-manager/docs/2026-05-30-PROJECT_LEARNINGS_AND_LOCAL_SKILLS.md

2026-05-30 项目经验总结与本地 Skills 沉淀

目标

把这次 sub2api-cn-relay-manager 项目里反复验证过、且明显提升任务完成质量的经验沉淀为可复用 skills，减少后续任务中的以下问题：

• 只做本地验证就误判“已完成”
• 控制面、运行态、数据面三层割裂
• provider_status / last_probe_status 和真实用户数据面不一致
• 长链路任务推进数小时后，状态板、远端环境和实际代码版本发生漂移

本次新增的项目内 skills 放在：

• .agent/skills/remote-truth-closure/SKILL.md
• .agent/skills/routing-data-plane-e2e/SKILL.md
• .agent/skills/false-negative-status-triage/SKILL.md

项目级经验

1. “本地通过”不能代表“任务完成”

这次项目里最重要的经验不是某个接口，而是交付链必须闭环：

1. 本地测试与门禁通过
2. 提交并推到目标远端
3. 真实远端部署到指定实例
4. 真实入口或真实用户链路验证
5. EXECUTION_BOARD.md 如实落盘

任何一步缺失，都不应声明“已完成”。

2. 控制面、运行态、数据面必须分开看

本项目后期已经清晰分成三层：

• 控制面：logical_group / route / shadow_group / public_model
• 运行态：sticky / cooldown / failover / route health
• 数据面：真实 /v1/chat/completions 与 host usage_logs

如果只验证控制面创建成功，不能证明路由真正可用；如果只看前端目录展示，也不能证明普通用户真的能用。

3. stock host 的 shadow provider 尽量使用 canonical model

真实验证证明，把 alias/public model 直接下沉到 stock host 的 shadow group，容易触发 channel pricing restriction 一类兼容问题。

更稳的策略是：

• public alias 留在插件层
• stock host 的 shadow provider 尽量只承载 canonical upstream model

4. 最终证据优先级要固定

这次项目里，很多误判都来自错误地把低优先级信号当成最终真相。

更可靠的证据顺序是：

1. 真实用户数据面结果
2. host usage_logs
3. route decision / sticky / failover 日志
4. provider / inventory 投影状态
5. probe-only 结果

尤其是 host 侧，后续要优先看 usage_logs，不要再拿 api_keys.usage_* 当最终证据。

5. false-negative 不应通过“隐藏错误”解决，而应通过“修正语义”解决

这次最后一轮修复很典型：

• batch_status=partially_succeeded 仍然保留
• 但只要真实 access_status 已 ready，provider_status 就不该继续显示为 degraded
• 对单帐号、真实 access 已 ready、smoke_model_seen=true 的场景，provider_account 也不应继续显示 broken/failed

关键不是把失败抹掉，而是让不同层级状态各自表达正确语义。

6. 长链路任务必须把“代码提交”和“验收记录提交”分开

这次项目反复证明，分开提交非常重要：

• 功能提交：表达行为变化
• docs/验收提交：表达真实验证结果

7. 远端环境必须主动清理，避免测试噪音

remote43 的历史目录、旧进程、旧 bundle、旧 checkout 残留，会直接污染验证结果，甚至制造绑定歧义、路由归属冲突这类假问题。

后续长项目应尽早建立：

• 仅保留一个 active app 目录
• 仅保留一个 latest fixed checkout
• 主动清理旧 bundle、旧辅助进程、临时逻辑分组

新增 skills 的作用

1. remote-truth-closure

作用：把“本地开发 -> 提交推送 -> 远端部署 -> 真验 -> 状态板更新”收成一个强约束工作流。

解决的问题：

• 任务推进到一半就误判完成
• 远端跑的版本和本地以为的版本不一致
• EXECUTION_BOARD.md 和真实状态脱节

2. routing-data-plane-e2e

作用：专门约束逻辑分组、route、shadow host/group/model、managed key 与真实 chat 数据面的闭环验收。

解决的问题：

• 只验证了 resolve，没验证真实 /chat/completions
• 没有 host 侧 usage 证据，无法证明命中目标帐号
• public alias 与 canonical shadow model 混用导致 host 兼容问题

3. false-negative-status-triage

作用：当 provider_status / account_status / probe_status 和真实用户请求不一致时，强制按四层信号做对比，并把修复限定在最小语义边界内。

解决的问题：

• 真实用户链路通了，但后台仍显示 degraded 或 broken
• 误把 raw probe 失败直接投影成最终可用性
• 用过度宽松的规则掩盖真实坏样本

对后续任务的直接收益

完成质量

• 更少虚假的“已完成”
• 更少只验证局部能力的片面结论
• 更强的远端真相约束
• 更少由测试残留导致的错误判断

完成能力

• 更快从卡住状态恢复真实进度
• 更快定位是控制面问题、运行态问题，还是数据面问题
• 更快把“现象冲突”收口为“语义修复”而不是无休止试错

后续建议

如果后面继续在这条产品线上推进，建议默认套用：

1. 任何带部署与真验的任务：remote-truth-closure
2. 任何 logical group、route、shadow provider 任务：routing-data-plane-e2e
3. 任何“真实可用但后台显示失败”的任务：false-negative-status-triage

这三者合起来，基本就是本项目后半程最有效的经验压缩。