rapid-iteration

name	rapid-iteration
description	LLMGateway 的快速迭代开发循环。正式实现、修复、重构、协议或数据变更、Provider 接入、管理端开发、测试和生产级验收时首先使用；要求先研究参考项目的机制、许可证和踩坑，再核验本仓库事实与 owner，从真实失败出发实现，并以有头 Chromium 的真实管理员和用户路径持续验收、修复和复测。

快速迭代开发循环

把每个交付切成可以独立验收的生产级纵向切片。第一次测试通过不是终点；只有真实入口、状态、错误、恢复、用户体验和文档同时成立，当前循环才结束。

所有循环服从同一产品骨架：两个业务核心是合法上游资源池的统一接入、调度与韧性，以及管理员对成员、套餐、订阅、额度和 API 密钥的治理；用户友好、安全、快速迭代是贯穿二者的交付原则。测试以稳定、可观察的业务结果为单位，不以当前页面或代码形状为单位。

加载顺序

1. 完整读取根目录 AGENTS.md、spec.md、dev.md、README.md 和存在时的 plan.md。
2. 本 Skill 必须先于 .agents/skills/llmgateway-dev/SKILL.md 加载。
3. 中大型、跨模块、边界调整或生产级验收任务继续加载 .agents/skills/plan/SKILL.md，并实时维护根目录 plan.md。

强制循环

1. 先看参考实现

• 公共协议、Provider 模型、能力、错误和额度先核验官方文档与真实隔离 wire；参考仓库不能替代权威合同。
• 在 ref/repos 中选择与当前切片直接相关的项目，优先研究 New API、Sub2API、LiteLLM、Portkey Gateway 和 Uni API。
• 记录仓库版本、许可证、具体文件和实际机制，追踪管理写入、数据面读取、失败恢复、并发边界与用户交互，不凭 README 或界面文案推断。
• 明确哪些机制适合 LLMGateway、哪些坑必须拒绝。AGPL/LGPL 或归属不清的源码只研究，不复制到主干。
• 不读取参考仓库的 .env、凭据、日志、请求正文或个人数据。
• 当证据已能解释当前 owner、失败与恢复机制，并确认至少一个可采用机制和一个必须拒绝的坑时停止扩散研究；只有新失败无法解释时再回看。

2. 再看 LLMGateway

• 沿客户端、公共协议、API 密钥、活动成员、活动订阅、套餐版本、admission、模型/资源池、路由与上游 API Key、Provider、响应、usage、日志与审计追踪完整请求链。
• 管理面继续追踪编辑、校验、事务提交、实时生效、停用/退役和数据面读取；套餐发布追踪不可变版本与既有订阅引用。
• 列出当前事实 owner、输入、直接消费者、持久状态、展示出口、错误与恢复边界、测试和事实文档；对比参考机制时服从 LLMGateway 的唯一 owner。
• 派生查询可以组合多个 owner 的权威输入，但不得持久化、展示或重算第二套源事实；组合策略本身必须有单一 owner。

3. 从真实失败开始

• 断裂式重建后的测试入口先做静态预检：完整通读相关测试和编排脚本，核对当前路由、handler、schema、字段语义、fixture 与清理范围；旧合同漂移先删除或迁移，不能靠长测试逐步撞出。
• 先从真实 HTTP、CLI、数据库或浏览器入口复现用户可见失败，记录状态码、稳定错误类型、响应、控制台、网络请求和持久状态。
• 自动测试正向证明产品结果；不得用源码字符串、文件形状、路由存在或 mock 成功冒充真实链路。
• 先复用现有通用主旅程制造失败。只有主旅程无法稳定制造且属于账本、权限、安全、幂等、并发、发送边界或恢复不变量时才增加定向测试；不得为当前局部修改另造一套特例旅程。
• 没有可复现失败时，先证明当前行为与目标合同的差距，再修改实现。

4. 实现最小生产级切片

• 同一次交付闭合成功、拒绝、并发、取消、中断、恢复、安全、可观测性、测试和文档。
• 修改唯一事实 owner，并同步所有消费者；不留 501、占位成功、双轨读写、临时桥接或无验收落点的 TODO。
• 首次生产发布前一旦 owner、schema、状态机或公共合同被证据推翻，直接断裂式重建并压平唯一基线，删除旧 migration、旧接口和所有消费者；开发数据只用显式 reset 重建，不为本机状态写过渡迁移或兼容路径。
• 在新增事实或改变边界前更新 plan.md，然后运行最接近改动的确定性测试。

5. 用真人路径验收

• Web 验收必须使用有头 Chromium 并复用管理员与成员的桌面主任务。本地运行时保持浏览器窗口可见，让 owner 可以观察实际操作；管理控制台不实现或验收移动布局。
• 真实主旅程已经覆盖的业务结果不再由 mock Chromium 和组件测试重复保护；mock 只保留快速 smoke 或真实环境无法稳定制造的通用交互边界。
• 最终验收连接真实 Go 进程、PostgreSQL、Valkey 和仓库构建的前端；mock server 只用于组件级确定性回归，不能证明真实产品链路。
• 像真实管理员和用户一样通过页面点击、输入、提交、等待、取消、刷新、返回、重登和重启。检查 DOM、URL、焦点、网络、控制台、长文本、溢出、加载/空/错误状态与持久化结果。
• 检查并删除单侧竖线、另一侧留空的伪 sidebar/callout。强调与分组使用完整边界、背景、间距或排版；侧栏只有在承载真实导航、工具或运行事实时才成立。
• 公共 API 继续使用标准 SDK 或 CLI 走真实网络合同；浏览器内 fetch 只能补同源证据，不能替代客户端验收。
• 截图、video 和 trace 只保留结构与失败证据，出现一次性 Key、Provider 凭据或敏感正文时禁用、裁掉或脱敏；视觉审美由 owner 判断，Agent 不宣布颜色、间距或品牌感合格。

6. 主动制造恶劣路径

• 按当前切片覆盖重复提交、并发冲突、断连、取消、超时、429/5xx、畸形或部分流、凭据停用、存储短暂失败、Valkey flush、进程强杀、重启与多实例竞争。
• 未知上游副作用不得盲目重放，套餐未授权的资源池以及资源池之间保持硬隔离，恢复、取消和清理必须幂等。
• 只制造与当前切片相关的故障；不适用的路径明确记录为 N/A 及理由。flush、kill、重建和存储故障只能作用于名称与范围均可核验的隔离测试资源。

7. 回看、优化、再测试

• 根据真实使用中暴露的问题回到参考实现和本仓库 owner，修根因后重跑定向测试、同一真人路径与相关恶劣路径。
• 不因第一次绿灯停止，不靠重复运行掩盖竞态；持续循环，直到当前切片没有已知破损路径。
• 每轮同时审查测试负担：删除与通用主旅程或 owner 不变量重复、绑定临时 DOM/文案/内部步骤、或只为当前补丁存在的用例。核心链未闭合时优先继续实现，不扩张页面级和跨层同义测试矩阵。
• UI 新增、删除、改名或调整排列不触发测试，除非稳定业务结果、权限边界或公共合同随之改变。不得保护菜单数量、标题、按钮存在性、导航入口全集、展示文案、颜色、对齐或组件排列；可访问名称只用于完成主旅程操作，不作为独立验收结果。
• 用“稳定合同未变时是否仍需重写”审查每份测试；答案为是时，它正在阻碍快速迭代，必须删除或收敛到稳定业务结果。不得为了让既有测试继续通过而保留旧 UI、旧模块、固定文件名、测试专用分支或兼容路径。
• 每份测试还要回答保护两个业务核心中的哪个结果、为何现有证据不能覆盖、重建页面/模块/文件后是否仍成立；答不出就删除。预计超过一分钟的档位必须说明短测无法替代的风险、最小有效时长、频率和预算，否则拆分、降频或删除；everything 只用于发布候选组合证据。
• 收口时运行完整验证、检查差异与敏感信息、同步事实文档，只提交并推送已完整闭环的 owner 切片。
• Agent 只自行运行预计一分钟以内的定向测试。更长的 daily/full/Provider/容量/发布验收由 owner 运行 python .\start_test.py <mode> 并提供 .build/test-logs/ 路径；读取一次日志后从首个真实失败继续，不轮询长进程。

交付证据

只陈述实际完成的路径、运行过的命令、观察到的持久状态、未验证项和剩余风险。mock、单元测试、真实后端浏览器、真实 Provider 与故障演练分别标注，不能互相替代。