llmgateway-dev

name	llmgateway-dev
description	维护 LLMGateway 时使用。适用于修改实现、公共协议、Provider、账号池、调度、额度、数据、管理面、测试、事实文档、依赖、构建和运行配置；要求先完成全局语义调查，再按生产级纵向切片闭环实现、恢复、验证和文档。

LLMGateway Development

开始前

1. 首先完整读取并执行 .agents/skills/rapid-iteration/SKILL.md，以参考研究、真实失败和有头浏览器/真实入口验收驱动当前切片。
2. 完整读取根目录 AGENTS.md、spec.md、dev.md、README.md 和存在时的当前 plan.md。
3. 检查 Git 状态、分支、未提交改动、目录结构、运行入口、持久状态、测试与完整验证入口。
4. 区分已确认事实、owner 提供但未验证的事实、推测、计划事项和已经验证的完成事项。
5. 从客户端入口沿公共协议、鉴权、权限/额度、admission、路由、凭据、调度、adapter、上游、响应、usage、日志与审计完成全局语义调查。
6. 管理面继续追踪写入、校验、事务提交、实时生效、停用与退役；套餐发布额外追踪不可变版本与既有订阅引用。
7. 中大型实现任务读取 .agents/skills/plan/SKILL.md，以 plan.example.md 为参考创建或更新根目录 plan.md。讨论和骨架阶段不创建。

判断边界

• 先确认改动落在两个业务核心之一：合法上游资源池的统一接入、调度与韧性，或管理员对成员、套餐、订阅、额度和 API 密钥的治理。用户友好、安全和快速迭代是横切要求，不另建业务事实。
• Provider catalog 是代码拥有的 adapter 校验能力，只在资源池表单提供平台和模型选项；不要把它实现成独立 Provider 页面、导航或管理员维护对象。
• 先找事实 owner，再列出输入、消费者、持久状态、输出、错误、恢复、测试、配置和文档。
• 质疑用户建议、现有实现、历史方案、参考项目和第一判断，直到证据收束。
• Provider 外部事实先核验官方资料；参考源码只用于研究，复用前检查许可证和维护边界。
• 方案优先复用成熟组件提供的机制，但 LLMGateway 自己拥有协议语义、调度规则、额度账本和恢复状态机。

实现标准

• 采用生产级纵向切片：阶段范围可以小，进入主干的成功、错误、并发、中断、恢复、安全、可观测性、测试和文档必须完整。
• 不提交 demo、假成功、虚假余额、只在内存成立的关键状态、已知破损恢复或准备以后删除的双轨逻辑。
• 每个事实只有一个 owner；handler、adapter、presenter 和测试不复制规则。
• Provider 差异只进入对应 adapter 或明确 policy；通用 OpenAI-compatible adapter 不吞掉无法无损表达的差异。
• Key 选择、限流、重试、熔断、usage 结算和恢复各由明确边界拥有。未知副作用不得因换 Key 而盲目重放。
• 套餐未授权的资源池以及资源池之间严格隔离；任一池耗尽不自动消费其他资源。
• 错误分类服务控制流，不以散落 message 匹配代替稳定 error kind。
• 单一职责按 owner 与变化原因判断；出现第二个独立变化原因、跨 owner 业务判断、事实重复计算、领域反向依赖交付/存储、循环依赖，或文件超过 300 行时触发职责审查。审查可以决定保持、收窄、移动或拆分，不按行数机械切割。
• 不覆盖 owner 的无关改动，不建立旧别名、兼容转发、历史包装、双 schema 读写或临时桥接。
• 不在错误模型上叠补丁。局部实现错误在根因处修复；owner、schema、公共合同或状态机被推翻时，修改唯一源并完整重建/再生成受影响消费者，删除旧路径，不增加例外分支或兼容壳。
• 当前尚无正式生产 schema 和必须保留的生产数据。首次生产发布前，不兼容的 schema、API、配置、事件和生成合同直接重建当前基线并同步全部消费者，不积累过渡 migration。
• 上述重建是强制断裂边界：新事实成立后必须在同一切片删除旧 migration、旧字段、旧状态、旧端点和全部消费者；开发数据库或本机持久状态不构成迁移与兼容理由，只能通过范围明确的显式 reset 重建。
• 开发/测试清理必须是独立、显式、范围可核验的操作，不混入普通启动、验证或升级。只有 owner 明确确认已有必须保留的正式生产数据后，才使用一次性前向迁移；完成后删除旧路径。

工程卫生

• 内部变量、类型、函数、文件、模块、配置和测试按领域职责命名，不用 v1/v2/v3、new/old、legacy、temp 或 final 表达演进顺序。外部协议版本、官方模型名和迁移序号忠实保留，但不扩散成内部版本壳。
• 命名迁移逐文件语义修改并检查消费者，不使用无审查批量替换、跨文件正则或大小写不受控改名。
• 核心领域使用显式类型；任意 JSON 只停留在明确 wire 边界。Token、金额、字节、持续时间和时间点显式表达单位，金额不用浮点数结算。
• 配置由单一类型化 owner 在启动时完整校验，无效配置失败退出，不保留旧 env 别名或静默回退。
• 生成物只由明确源和确定性命令产生，禁止手改；生成漂移进入完整验证。
• 依赖引入前核验必要性、许可证、维护状态、发布来源和跨平台支持，使用锁文件固定解析结果；生产管理端不运行时加载会接触敏感信息的 CDN 代码。
• 时间、随机数和 ID 等非确定性来源可注入测试。注释说明原因，不复述代码；无 owner 或计划落点的 TODO、死配置和占位实现直接删除。

强制生命周期审查

每项功能在设计、实现和测试收口前逐项检查：接受、执行、提交、中断、失败、恢复、重放和清理。

至少回答：

• 接受和额度预留何时持久化；
• 客户端断连、重复提交、重复取消和进程强杀会留下什么状态；
• 上游发送与流式部分完成的未知边界如何表达；
• 并发请求是否会超额、重复结算或漏结算；
• 上游 429/5xx、超时、畸形响应和账号停用如何进入冷却、重试或终态；
• 持久存储、协调设施、套餐发布、资源写入或异步轮询中断后由哪个 owner 恢复；
• 清理、回调、恢复和重放是否幂等；
• 套餐授权与资源池隔离是否在所有错误路径保持成立。

无法回答时不能收口。详细规则读取 dev.md。

测试规则

• 断裂式重建后执行集成测试、浏览器旅程或长档前，先完整通读测试与编排脚本，逐项对齐当前路由、handler、schema、字段语义、fixture 和清理范围；先修复静态可见漂移，再运行测试。
• 测试先保护唯一核心而非铺满层级。每个稳定业务结果选择最有证明力的一层；真实主旅程、mock 浏览器、组件、handler、service 与 repository 不得重复保护同一结果。
• 核心链未闭合时，浏览器只保留少量通用管理员/成员桌面主旅程；只为账本、权限、安全、幂等、并发、发送边界和恢复增加无法由主旅程替代的定向测试。发现重复立即删除，不等待测试数量继续增长。
• 修复回归先建立可复现失败测试或等价证据，再改实现。
• 长期测试只保护核心业务结果、公共协议、Provider wire、权限、额度、调度、持久状态、恢复、幂等、安全和跨边界合同；实现重构后仍必须有产品意义，不以测试数量表现能力。
• 覆盖成功、空状态、无权限、限额、极值、并发、取消、中断、崩溃和恢复。
• 测试正向验证稳定业务结果；不测试文件、路由、字符串或实现不存在，不用关键词、文案片段、源码扫描或目录形状冒充行为验收。
• UI 新增、删除、改名或重新排列，除非改变稳定业务结果、权限边界或公共合同，否则不得增加或修改测试；不断言菜单数量、标题、按钮存在性、导航入口全集、展示文案、颜色、对齐和组件排列。可访问名称可以定位主旅程中的操作，但定位本身不是产品结果。
• 判断一份测试是否值得长期存在时，先用一句业务语言描述它保护的结果；若只能描述按钮、页面、文件、调用次数、查询批次或内部步骤，而不能描述用户结果、公共合同、持久事实或高风险不变量，则删除或提升到正确层级。
• 每份测试都必须通过迭代阻力审查：稳定业务合同不变时仍会因新增功能、信息架构调整、模块重建、文件改名或内部实现替换而需要重写的测试，直接删除或收敛。不得为测试保留旧 UI、旧模块、固定文件名、测试专用路径或兼容壳。
• 每份测试必须明确属于多 Provider 统一服务或管理员/成员治理的哪个稳定结果、为何已有证据不能覆盖、重建后是否仍成立；答不出即删除。超过一分钟的测试还必须说明不可由短测替代的风险、最小有效时长、频率和预算；长档只按对应风险运行，everything 只作为发布候选组合证据。
• 时间与并发测试等待事件或可观察状态，不使用固定 sleep，不靠重复运行过关。
• 真实 Provider 验收与日常确定性测试分层；未运行真实验收时明确说明。
• 视觉审美由人类验收，Agent 不凭截图宣布整体观感合格；Web 核心路径必须用 Playwright 真实浏览器正向验证结构、不溢出、导航、表单、状态和交互事实。

文档闭环

• 产品事实、不变量、技术栈、模块边界、运行拓扑或管理端信息架构变化同步 spec.md。
• 工程纪律或验收门槛变化同步 AGENTS.md、dev.md 和本 Skill。
• 用户安装、运行、配置或验证方式变化同步 README.md。
• 当前中大型任务的范围、事实、设计、状态和验证同步 plan.md。
• 删除能力时同步清理实现、配置、测试和当前文档；不为“已删除”添加负性保护测试。
• 未实现或未验证内容不得在任何载体写成已实现或已通过。

验证与交付

• 骨架阶段至少运行 git diff --check、文件范围、占位项、敏感信息和链接检查。
• 技术栈确定时建立唯一完整验证命令，并同步 AGENTS.md、dev.md、README 和本 Skill。
• 先运行最接近改动的检查，再运行完整验证和当前阶段核心路径；不靠复跑掩盖抖动。
• Agent 只自行运行预计一分钟以内的定向测试；长测试统一交由 owner 运行 python .\start_test.py <mode>，从 owner 提供的日志路径读取一次结果并继续。
• 最终检查差异和工作区，只交付当前任务内容。
• commit、push、部署和发布只在 owner 明确授权时执行。
• 收口说明完成事实、实际验证、未验证项和剩余风险。