Follow-up: a7 test / skills / docs review findings

[guoqqqi]

背景

在准备实际投入使用前，对 a7 当前测试体系、skills、文档做了一轮完整审查与本地复跑。

飞书详细报告：

• https://www.feishu.cn/docx/AR0Qd3d1xo4I0Bx2PGQccwCBnXe

当前结论

• CI 基础测试可通过
• 严格按当前 CI 的 E2E workflow 口径，本地复跑可以通过
• 但该“通过”包含大量 skip
• 当补充 A7_GATEWAY_URL=http://192.168.10.100:19080 与 HTTPBIN_URL=http://192.168.10.100:3030 后，原先很多被跳过的关键流量 case 暴露出真实问题
• 当前 skills 没有 dedicated e2e，也没有 validate-skills
• 当前总代码覆盖率约为 41.4%

主要问题

1. route / debug / stream-route / secret 测试模型和当前 EE API 不匹配

当前已确认的问题包括：

• route create 相关测试仍按旧模型构造请求，缺少当前 EE 所要求的 service_id
• debug trace 相关测试仍使用旧 route 模型，导致真实失败
• stream-route 相关测试与当前 schema 要求不一致
• secret 的文档和测试使用的参数形式与当前 CLI 不匹配

2. skills 自动化缺失

• 没有 scripts/validate-skills.sh
• 没有 make validate-skills
• 没有 test/e2e/skills

3. skills 文档和当前实现/环境不一致

已确认的问题包括：

• docs/skills.md 中声明了仓库里并不存在的 skill 名称
• persona 文档中引用了当前 CLI 不存在的命令，如 health、portal
• 多个 recipe 文档仍围绕旧的 route/upstream 模型编写
• upstream create 在当前 EE 环境中直接返回 resource not found

需要继续跟进的事项

P0

• 重写 route 相关 e2e

  • 采用 service create + route create(service_id) 的当前可行模型

• 重写 debug trace e2e

  • 基于当前真实可用的 route/service 模型

• 重写 stream-route e2e

  • 与当前 schema 对齐

• 重写 secret e2e

  • 与当前 CLI 参数形式对齐

• 重写 auth 类场景验证

  • 统一改用 credential create 的当前可用模型

• 为 skills 增加自动化

  • validate-skills
  • test/e2e/skills

P1

• 系统修正文档中的旧模型示例

  • route
  • upstream
  • debug
  • auth
  • recipe

• 修正 docs/skills.md 中不存在的 skill 名称和 roadmap 项

• 对现有 skills 做一轮“当前环境可落地性”清洗

  • 区分：可用、需改文档、依赖外部系统、当前不可用

P2

• 继续补 unit test，逐步拉升覆盖率
• 将关键行为 case 从“可人工验证”固化为自动化测试

建议产出

• 先完成一轮“模型纠偏”

  • 先把 route / credential / debug / stream-route / secret 测试模型和文档统一到当前 EE API

• 再补 skills 自动化

  • 不要在旧模型基础上直接堆自动化

• 最终形成：

  • 可维护的 e2e
  • 可执行的 skill 验证
  • 与当前实现一致的文档

[guoqqqi]

详细盘点和当前结论请见飞书报告：
https://www.feishu.cn/docx/AR0Qd3d1xo4I0Bx2PGQccwCBnXe

以下内容按 a7 当前状态拆解，便于直接在 issue 中继续分析和推进。

当前状态

• CI 基础测试：本地复跑成功
• 严格按当前 CI workflow 环境变量口径：E2E 本地复跑成功
• 但该“成功”包含大量 skip
• 当补充：
  • A7_GATEWAY_URL=http://192.168.10.100:19080
  • HTTPBIN_URL=http://192.168.10.100:3030
    之后，原先很多被 skip 的关键流量 case 暴露出真实问题
• 当前没有 validate-skills
• 当前没有 test/e2e/skills
• 总覆盖率：41.4%

严格 CI 口径下的主要问题

当前 workflow 之所以能绿，核心原因不是关键场景都通过了，而是很多 case 没有真实执行。

典型 skip 包括：

• Consumer_WithKeyAuth
• DebugTrace_*
• Route_* 多数关键 case
• StreamRoute_* 多数关键 case
• Secret_CRUD

补齐网关地址后暴露出的真实问题

当本地补充 A7_GATEWAY_URL 和 HTTPBIN_URL 后，情况变成：

• TestDebugTrace_JSONOutput：真实失败
• TestDebugTrace_YAMLOutput：真实失败
• TestConsumer_WithKeyAuth：不再只是“没网关地址”，而是 credential schema 不匹配
• TestRoute_TrafficForwarding：route 创建仍缺 service_id
• TestRoute_*：多数仍因旧 route 模型与当前 EE API 不匹配而 skip
• TestStreamRoute_*：schema 不匹配
• TestSecret_CRUD：CLI 参数形式不匹配

当前已确认可用的正向模型

目前已经本地验证过的正向链路包括：

• service create + route create(service_id) + gateway curl

  • 已真实跑通 proxy-rewrite

• consumer create + credential create

  • 已真实跑通 key-auth 相关认证链路的资源创建模型

这说明：

• 不是所有能力都不可用
• 但当前很多文档 / 测试仍停留在旧模型

a7 Skills 本地手动验收结果

已确认通过

• a7-shared
• a7-plugin-ai-prompt-decorator
• a7-plugin-ai-prompt-template
• a7-plugin-ai-proxy
• a7-plugin-basic-auth
• a7-plugin-consumer-restriction
• a7-plugin-cors
• a7-plugin-datadog
• a7-plugin-fault-injection
• a7-plugin-grpc-transcode
• a7-plugin-hmac-auth
• a7-plugin-http-logger
• a7-plugin-ip-restriction
• a7-plugin-jwt-auth
• a7-plugin-kafka-logger
• a7-plugin-key-auth
• a7-plugin-limit-count
• a7-plugin-limit-req
• a7-plugin-openid-connect
• a7-plugin-prometheus
• a7-plugin-proxy-rewrite
• a7-plugin-redirect
• a7-plugin-response-rewrite
• a7-plugin-skywalking
• a7-plugin-traffic-split
• a7-plugin-wolf-rbac
• a7-plugin-zipkin

已确认有问题

• a7-persona-developer
  • 文档里引用 a7 portal publish，当前 CLI 无此命令
• a7-persona-operator
  • 文档里引用 a7 health，当前 CLI 无此命令
• a7-plugin-ai-content-moderation
  • 当前按 skill 名对应插件查询返回 unknown plugin
• a7-plugin-ext-plugin
  • 当前按 skill 名对应插件查询返回 unknown plugin
• a7-plugin-serverless
  • 当前按 skill 名对应插件查询返回 unknown plugin
• a7-recipe-api-versioning
• a7-recipe-blue-green
• a7-recipe-canary
• a7-recipe-circuit-breaker
• a7-recipe-health-check
  • 这些 recipe 都依赖 upstream create
  • 当前环境里 upstream create 直接返回 resource not found
• a7-recipe-graphql-proxy
  • route 示例还是旧模型
• a7-recipe-mtls
  • 同时依赖 upstream create、旧 route 模型、secret / ssl 组合示例
• a7-recipe-multi-tenant
  • gateway-group / consumer-group 思路可用，但 route 模型仍旧

文档与 skills 的共性问题

skills 文档失真

• docs/skills.md 声称存在：
  • scripts/validate-skills.sh
  • make validate-skills
  • 仓库里都没有

skill 名称和 roadmap 不一致

• 文档中存在但仓库里没有的 skill / roadmap 项：
  • a7-recipe-gateway-group
  • a7-persona-platform-eng
  • a7-recipe-service-template
  • a7-plugin-ai-rag
  • a7-plugin-ai-token-limiter
  • a7-recipe-service-registry

persona 文档引用不存在命令

• health
• portal

route / recipe 文档仍是旧模型

• 多数仍直接写 route + upstream
• 但当前真实可用模型应优先切到：
  • service create
  • route create(service_id)

需要继续推进的待办

P0

• 重写 route 相关 e2e

  • 统一改成 service_id 模型

• 重写 debug trace e2e

• 重写 stream-route e2e

• 重写 secret e2e

• 重写 auth 类示例与测试

  • 统一改用 credential create

• 增加 validate-skills

• 增加 test/e2e/skills

P1

• 系统修正文档中的旧模型示例

  • route
  • upstream
  • auth
  • debug
  • recipes

• 修正 docs/skills.md 中不存在的 skill 名称和 roadmap

• 清洗所有 skills，区分：

  • 可用
  • 需改文档
  • 依赖外部系统
  • 当前不可用

P2

• 继续补 unit tests，提高覆盖率
• 把当前已人工验证通过的 skill 场景逐步固化成自动化