V1.8.6

.agents/skills/bfe-rd-workflow/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: bfe-rd-workflow
+description: 引导用户在 bfe 代码库中完成一次完整的功能研发流程，包括需求对齐、文档修改、代码实现、集成测试与回归验证。
+---
+
+# BFE 代码库研发流程
+
+本 Skill 适用于在 `bfe/` 目录中新增或修改 BFE 功能（例如 AI Gateway 的多 API-Key 会话亲和性、限流、计费、路由、协议支持等）的完整研发流程。
+
+## 触发语
+
+当用户提出以下类型请求时启用本流程：
+
+- “我要实现 xxx 功能”
+- “请帮我完成 xxx 的代码与测试”
+- “请在 BFE 中增加/修改 xxx”
+
+## 执行原则
+
+1. **分阶段暂停确认**：本流程将研发拆分为多个 Phase。每个 Phase 执行完毕后，必须暂停并等待用户确认“可以继续”后，再进入下一个 Phase。不要在未获得用户确认的情况下自动推进到下一阶段。
+2. **Git 提交前确认**：在任何 `git commit`、`git push` 或其他会改变 Git 仓库状态的操作之前，必须先向用户说明变更内容并取得明确同意。禁止自动执行 Git 提交或推送。
+3. **Git push 默认目标为 origin**：如果获得用户授权执行 `git push`，默认推送到 `origin` 远程仓库，而不是 `upstream`。除非用户明确指定其他 remote，否则不使用 `upstream`。
+
+## 研发阶段
+
+### Phase 0. 需求澄清与范围界定
+
+1. 让用户明确：
+   - 功能目标（一句话描述）
+   - 验收标准（必须通过的测试/行为）
+   - 影响范围（是否改配置协议、是否改 Redis/状态、是否影响既有请求路径）
+2. 判断是否为“非平凡改动”（多文件、有架构选择、用户偏好影响实现）：
+   - 是 → 调用 `EnterPlanMode`，先出设计文档/plan 再执行。
+   - 否 → 直接进入 Phase 1。
+
+完成本阶段后暂停，等待用户确认后再进入下一阶段。
+
+### Phase 1. 修改 modifications 文档
+
+BFE 侧的改动必须在 `bfe/docs/zh_cn/modifications/` 留下修改说明，便于后续维护与审计。
+
+1. 在 `bfe/docs/zh_cn/modifications/` 下新建日期化目录，例如：
+   ```
+   bfe/docs/zh_cn/modifications/2026-08-26-ai-key-session-affinity/
+   ```
+2. 在该目录下创建 `design-changes.md`，包含：
+   - 背景与目标
+   - 主要改动点（数据结构、模块行为、新增字段）
+   - 配置影响
+   - 兼容性说明
+3. 如已有同主题目录，则更新其中的文档，不要重复创建。
+
+完成本阶段后暂停，等待用户确认后再进入下一阶段。
+
+### Phase 2. 更新 configuration 文档
+
+如果改动涉及配置文件（`cluster_conf.data`、`mod_*.conf`、`bfe.conf` 等），必须同步更新中英文配置文档：
+
+1. 中文：`bfe/docs/zh_cn/configuration/`
+2. 英文：`bfe/docs/en_us/configuration/`
+
+更新原则：
+
+- 新增字段要说明类型、默认值、是否必填、示例。
+- 修改字段要说明前后行为差异。
+- 两个语言目录尽量保持内容一致。
+
+完成本阶段后暂停，等待用户确认后再进入下一阶段。
+
+### Phase 3. 更新 sys_design 文档
+
+如果改动涉及系统设计、协议交互或状态存储，需要更新 `bfe/docs/zh_cn/sys_design/`：
+
+1. 查找现有相关文档（例如 `multi_api_key.md`）。
+2. 在文档中新增/修改对应章节，说明：
+   - 方案选型
+   - 数据流
+   - 状态存储（如 Redis key 格式、TTL）
+   - 边界情况与优化
+3. 如需新增独立文档，直接创建 `.md` 文件，并在相关文档中建立链接。
+
+完成本阶段后暂停，等待用户确认后再进入下一阶段。
+
+### Phase 4. 代码实现
+
+1. 阅读相关源码，确认：
+   - 配置结构体（`bfe_config/bfe_cluster_conf/cluster_conf/`）
+   - 模块加载与处理逻辑（`bfe_modules/mod_*`）
+   - 反向代理与 Key 选择逻辑（`bfe_server/reverseproxy.go` 及相关测试）
+2. 做最小改动，优先匹配现有代码风格：
+   - 不引入未使用的依赖。
+   - 不修改与本次需求无关的逻辑。
+3. 关键实现完成后，先跑模块级单元测试：
+   ```bash
+   cd bfe
+   go test ./bfe_server/... ./bfe_modules/<相关模块>/...
+   ```
+
+完成本阶段后暂停，等待用户确认后再进入下一阶段。
+
+### Phase 5. 编写集成测试设计文档
+
+BFE 的集成测试设计文档位于 `bfe/tests/integration/测试设计文档/`。在写测试代码之前，先补充对应场景的设计文档，便于后续维护与评审。
+
+1. 在 `bfe/tests/integration/测试设计文档/` 下新建 scenario 目录，命名规范：
+   ```
+   scenario-SC<序号>-<简短中文描述>
+   ```
+2. 编写 `场景说明.md`，包含：
+   - 场景背景与目的
+   - 运行模式
+   - 涉及的 BFE 配置文件
+   - 测试 Cluster 与关键配置（AIConf、KeyPolicy、路由表等）
+   - 测试例列表
+   - 每个测试例的详细说明（目的、前置条件、请求构造、执行步骤、预期结果、清理）
+   - 公共基础设施
+   - 与其他场景的依赖关系
+3. 为每个测试例编写独立的 `TC-<序号>-<测试例名称>.md`，结构与现有 TC 文档保持一致。
+4. 更新 `bfe/tests/integration/测试设计文档/测试场景总体说明.md`：
+   - 在“场景清单”中新增一行；
+   - 在“场景与测试例对应关系”中新增该 scenario 的 TC 列表。
+
+完成本阶段后暂停，等待用户确认后再进入下一阶段。
+
+### Phase 6. 编写集成测试代码
+
+BFE 的集成测试代码位于 `bfe/tests/integration/implementation/`。
+
+1. 选择最接近的现有 scenario 作为模板（例如需要 Redis 的可参考 `scenario-SC07-ai-rate-limit-redis-key`）。
+2. 新建 scenario 目录，命名规范：
+   ```
+   scenario-SC<序号>-<简短英文描述>
+   ```
+3. 复制模板后，修改 `testdata/` 中的：
+   - `server_data_conf/host_rule.data`：host
+   - `server_data_conf/route_rule.data`：cluster
+   - `cluster_conf/gslb.data`：cluster 名称
+   - `mod_ai_route/ai_route.data`：apikey owner / route binding
+   - `mod_ai_token_auth/mod_ai_token_auth.conf`、`mod_ai_rate_limit/mod_ai_rate_limit.conf` 等
+4. 编写 `_test.go`，覆盖：
+   - 正常路径
+   - 功能开关开启/关闭对比
+   - 边界场景（单 Key、多 ClientKeyId、BFE 重启后状态保持、错误码/降级）
+5. 运行集成测试：
+   ```bash
+   cd bfe
+   go test ./tests/integration/implementation/scenario-SC<xx>-<描述>/... -v
+   ```
+
+完成本阶段后暂停，等待用户确认后再进入下一阶段。
+
+### Phase 7. 回归验证
+
+1. 运行本次新增 scenario 的测试。
+2. 运行与被改动模块相关的既有 scenario：
+   - 多 API-Key 轮换：`scenario-SC02-multi-api-key`
+   - Redis 限流：`scenario-SC07-ai-rate-limit-redis-key`
+3. 运行相关单元测试：
+   ```bash
+   go test ./bfe_server/... ./bfe_modules/mod_ai_route/... ./bfe_modules/mod_ai_token_auth/...
+   ```
+4. 如有失败，优先修复；修复后再次回归，直到全部通过。
+
+完成本阶段后暂停，等待用户确认后再进入下一阶段。
+
+### Phase 8. 收尾与总结
+
+1. 检查是否有注释/文档描述的是旧行为，及时同步更新。
+2. 向用户汇报：
+   - 改动了哪些文件
+   - 新增/修改了哪些测试
+   - 验证结果
+   - 仍存在的风险或待决策点（如有）
+
+3. **Git 提交前必须人工确认**：如果用户要求或流程需要执行 `git commit`、`git push` 等 Git 操作，必须先向用户清晰说明本次提交内容（包含文件清单与主要变更摘要），并取得明确同意后再执行。禁止在未获授权的情况下自动提交或推送。获得授权后，`git push` 默认推送到 `origin`，不要推送到 `upstream`，除非用户明确指定。
+
+## 常见陷阱
+
+- **cluster 名称不一致**：`route_rule.data`、`gslb.data`、ai_route 中的 cluster 名称必须一致，否则 BFE 启动会报 `no backend conf`。
+- **ApikeyRouteTableBindings 遗漏**：新增 client apiKey 时，必须在 `mod_ai_route/ai_route.data` 的 `ApikeyRouteTableBindings` 中为其绑定路由表。
+- **Redis 绑定 key 格式**：确认代码中实际使用的 key 格式（如 `bfe:ai:key_affinity:<cluster>:<client_key_id>`）。
+- **单 Key 优化**：如果实现了“单 Key 不走 Redis”，需要同时避免读和写，否则集成测试里 `Exists` 会误判。
+- **BFE 端口冲突**：集成测试里 `processEnv.StartBFE` 会自动分配端口，不要手动写死。
+
+## 推荐命令速查
+
+```bash
+# 模块单元测试
+cd bfe
+go test ./bfe_server/... ./bfe_modules/mod_ai_route/... ./bfe_modules/mod_ai_token_auth/...
+
+# 单个集成测试场景（详细日志）
+go test ./tests/integration/implementation/scenario-SC<xx>-<描述>/... -v
+
+# 相关场景回归
+go test ./tests/integration/implementation/scenario-SC02-multi-api-key/...
+go test ./tests/integration/implementation/scenario-SC07-ai-rate-limit-redis-key/...
+```

.claude/skills/bfe-rd-workflow/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: bfe-rd-workflow
+description: 引导用户在 bfe 代码库中完成一次完整的功能研发流程，包括需求对齐、文档修改、代码实现、集成测试与回归验证。
+---
+
+# BFE 代码库研发流程
+
+本 Skill 适用于在 `bfe/` 目录中新增或修改 BFE 功能（例如 AI Gateway 的多 API-Key 会话亲和性、限流、计费、路由、协议支持等）的完整研发流程。
+
+## 触发语
+
+当用户提出以下类型请求时启用本流程：
+
+- “我要实现 xxx 功能”
+- “请帮我完成 xxx 的代码与测试”
+- “请在 BFE 中增加/修改 xxx”
+
+## 执行原则
+
+1. **分阶段暂停确认**：本流程将研发拆分为多个 Phase。每个 Phase 执行完毕后，必须暂停并等待用户确认“可以继续”后，再进入下一个 Phase。不要在未获得用户确认的情况下自动推进到下一阶段。
+2. **Git 提交前确认**：在任何 `git commit`、`git push` 或其他会改变 Git 仓库状态的操作之前，必须先向用户说明变更内容并取得明确同意。禁止自动执行 Git 提交或推送。
+3. **Git push 默认目标为 origin**：如果获得用户授权执行 `git push`，默认推送到 `origin` 远程仓库，而不是 `upstream`。除非用户明确指定其他 remote，否则不使用 `upstream`。
+
+## 研发阶段
+
+### Phase 0. 需求澄清与范围界定
+
+1. 让用户明确：
+   - 功能目标（一句话描述）
+   - 验收标准（必须通过的测试/行为）
+   - 影响范围（是否改配置协议、是否改 Redis/状态、是否影响既有请求路径）
+2. 判断是否为“非平凡改动”（多文件、有架构选择、用户偏好影响实现）：
+   - 是 → 调用 `EnterPlanMode`，先出设计文档/plan 再执行。
+   - 否 → 直接进入 Phase 1。
+
+完成本阶段后暂停，等待用户确认后再进入下一阶段。
+
+### Phase 1. 修改 modifications 文档
+
+BFE 侧的改动必须在 `bfe/docs/zh_cn/modifications/` 留下修改说明，便于后续维护与审计。
+
+1. 在 `bfe/docs/zh_cn/modifications/` 下新建日期化目录，例如：
+   ```
+   bfe/docs/zh_cn/modifications/2026-08-26-ai-key-session-affinity/
+   ```
+2. 在该目录下创建 `design-changes.md`，包含：
+   - 背景与目标
+   - 主要改动点（数据结构、模块行为、新增字段）
+   - 配置影响
+   - 兼容性说明
+3. 如已有同主题目录，则更新其中的文档，不要重复创建。
+
+完成本阶段后暂停，等待用户确认后再进入下一阶段。
+
+### Phase 2. 更新 configuration 文档
+
+如果改动涉及配置文件（`cluster_conf.data`、`mod_*.conf`、`bfe.conf` 等），必须同步更新中英文配置文档：
+
+1. 中文：`bfe/docs/zh_cn/configuration/`
+2. 英文：`bfe/docs/en_us/configuration/`
+
+更新原则：
+
+- 新增字段要说明类型、默认值、是否必填、示例。
+- 修改字段要说明前后行为差异。
+- 两个语言目录尽量保持内容一致。
+
+完成本阶段后暂停，等待用户确认后再进入下一阶段。
+
+### Phase 3. 更新 sys_design 文档
+
+如果改动涉及系统设计、协议交互或状态存储，需要更新 `bfe/docs/zh_cn/sys_design/`：
+
+1. 查找现有相关文档（例如 `multi_api_key.md`）。
+2. 在文档中新增/修改对应章节，说明：
+   - 方案选型
+   - 数据流
+   - 状态存储（如 Redis key 格式、TTL）
+   - 边界情况与优化
+3. 如需新增独立文档，直接创建 `.md` 文件，并在相关文档中建立链接。
+
+完成本阶段后暂停，等待用户确认后再进入下一阶段。
+
+### Phase 4. 代码实现
+
+1. 阅读相关源码，确认：
+   - 配置结构体（`bfe_config/bfe_cluster_conf/cluster_conf/`）
+   - 模块加载与处理逻辑（`bfe_modules/mod_*`）
+   - 反向代理与 Key 选择逻辑（`bfe_server/reverseproxy.go` 及相关测试）
+2. 做最小改动，优先匹配现有代码风格：
+   - 不引入未使用的依赖。
+   - 不修改与本次需求无关的逻辑。
+3. 关键实现完成后，先跑模块级单元测试：
+   ```bash
+   cd bfe
+   go test ./bfe_server/... ./bfe_modules/<相关模块>/...
+   ```
+
+完成本阶段后暂停，等待用户确认后再进入下一阶段。
+
+### Phase 5. 编写集成测试设计文档
+
+BFE 的集成测试设计文档位于 `bfe/tests/integration/测试设计文档/`。在写测试代码之前，先补充对应场景的设计文档，便于后续维护与评审。
+
+1. 在 `bfe/tests/integration/测试设计文档/` 下新建 scenario 目录，命名规范：
+   ```
+   scenario-SC<序号>-<简短中文描述>
+   ```
+2. 编写 `场景说明.md`，包含：
+   - 场景背景与目的
+   - 运行模式
+   - 涉及的 BFE 配置文件
+   - 测试 Cluster 与关键配置（AIConf、KeyPolicy、路由表等）
+   - 测试例列表
+   - 每个测试例的详细说明（目的、前置条件、请求构造、执行步骤、预期结果、清理）
+   - 公共基础设施
+   - 与其他场景的依赖关系
+3. 为每个测试例编写独立的 `TC-<序号>-<测试例名称>.md`，结构与现有 TC 文档保持一致。
+4. 更新 `bfe/tests/integration/测试设计文档/测试场景总体说明.md`：
+   - 在“场景清单”中新增一行；
+   - 在“场景与测试例对应关系”中新增该 scenario 的 TC 列表。
+
+完成本阶段后暂停，等待用户确认后再进入下一阶段。
+
+### Phase 6. 编写集成测试代码
+
+BFE 的集成测试代码位于 `bfe/tests/integration/implementation/`。
+
+1. 选择最接近的现有 scenario 作为模板（例如需要 Redis 的可参考 `scenario-SC07-ai-rate-limit-redis-key`）。
+2. 新建 scenario 目录，命名规范：
+   ```
+   scenario-SC<序号>-<简短英文描述>
+   ```
+3. 复制模板后，修改 `testdata/` 中的：
+   - `server_data_conf/host_rule.data`：host
+   - `server_data_conf/route_rule.data`：cluster
+   - `cluster_conf/gslb.data`：cluster 名称
+   - `mod_ai_route/ai_route.data`：apikey owner / route binding
+   - `mod_ai_token_auth/mod_ai_token_auth.conf`、`mod_ai_rate_limit/mod_ai_rate_limit.conf` 等
+4. 编写 `_test.go`，覆盖：
+   - 正常路径
+   - 功能开关开启/关闭对比
+   - 边界场景（单 Key、多 ClientKeyId、BFE 重启后状态保持、错误码/降级）
+5. 运行集成测试：
+   ```bash
+   cd bfe
+   go test ./tests/integration/implementation/scenario-SC<xx>-<描述>/... -v
+   ```
+
+完成本阶段后暂停，等待用户确认后再进入下一阶段。
+
+### Phase 7. 回归验证
+
+1. 运行本次新增 scenario 的测试。
+2. 运行与被改动模块相关的既有 scenario：
+   - 多 API-Key 轮换：`scenario-SC02-multi-api-key`
+   - Redis 限流：`scenario-SC07-ai-rate-limit-redis-key`
+3. 运行相关单元测试：
+   ```bash
+   go test ./bfe_server/... ./bfe_modules/mod_ai_route/... ./bfe_modules/mod_ai_token_auth/...
+   ```
+4. 如有失败，优先修复；修复后再次回归，直到全部通过。
+
+完成本阶段后暂停，等待用户确认后再进入下一阶段。
+
+### Phase 8. 收尾与总结
+
+1. 检查是否有注释/文档描述的是旧行为，及时同步更新。
+2. 向用户汇报：
+   - 改动了哪些文件
+   - 新增/修改了哪些测试
+   - 验证结果
+   - 仍存在的风险或待决策点（如有）
+
+3. **Git 提交前必须人工确认**：如果用户要求或流程需要执行 `git commit`、`git push` 等 Git 操作，必须先向用户清晰说明本次提交内容（包含文件清单与主要变更摘要），并取得明确同意后再执行。禁止在未获授权的情况下自动提交或推送。获得授权后，`git push` 默认推送到 `origin`，不要推送到 `upstream`，除非用户明确指定。
+
+## 常见陷阱
+
+- **cluster 名称不一致**：`route_rule.data`、`gslb.data`、ai_route 中的 cluster 名称必须一致，否则 BFE 启动会报 `no backend conf`。
+- **ApikeyRouteTableBindings 遗漏**：新增 client apiKey 时，必须在 `mod_ai_route/ai_route.data` 的 `ApikeyRouteTableBindings` 中为其绑定路由表。
+- **Redis 绑定 key 格式**：确认代码中实际使用的 key 格式（如 `bfe:ai:key_affinity:<cluster>:<client_key_id>`）。
+- **单 Key 优化**：如果实现了“单 Key 不走 Redis”，需要同时避免读和写，否则集成测试里 `Exists` 会误判。
+- **BFE 端口冲突**：集成测试里 `processEnv.StartBFE` 会自动分配端口，不要手动写死。
+
+## 推荐命令速查
+
+```bash
+# 模块单元测试
+cd bfe
+go test ./bfe_server/... ./bfe_modules/mod_ai_route/... ./bfe_modules/mod_ai_token_auth/...
+
+# 单个集成测试场景（详细日志）
+go test ./tests/integration/implementation/scenario-SC<xx>-<描述>/... -v
+
+# 相关场景回归
+go test ./tests/integration/implementation/scenario-SC02-multi-api-key/...
+go test ./tests/integration/implementation/scenario-SC07-ai-rate-limit-redis-key/...
+```