api-blackbox-tester

name	api-blackbox-tester
description	作为接口黑盒测试插件的统一编排入口使用。当用户需要完整接口黑盒测试流程，或不确定应该做编码前测试方案、测试用例评审、编码后接口执行还是最终覆盖率报告时使用本技能。本技能负责选择并串联 api-blackbox-test-planner、api-blackbox-test-reviewer、api-blackbox-test-executor、api-blackbox-test-reporter 四个阶段 Skill，并贯穿业务场景拆解、场景 x 边界/异常覆盖矩阵、接口 x 字段语义等价类矩阵、跨接口一致性验证、测试结果可信度评分和未执行必测单元不得通过的质量门禁。

接口黑盒测试编排入口

目标

这个 Skill 只负责阶段判断和流程编排，不承载具体测试细节。根据用户意图选择一个或多个阶段 Skill：

• api-blackbox-test-planner：编码前分析，输出测试范围、业务场景拆解、兼容性验证、测试用例、接口 x 字段语义等价类矩阵、场景 x 边界/异常覆盖矩阵、跨接口一致性用例、接口编排链路和测试数据计划。
• api-blackbox-test-reviewer：执行前测试用例评审，由资深测试工程师、资深产品经理、资深软件工程师、安全工程师四个角色评审 planner 输出；必须按业务场景、场景 x 边界/异常覆盖矩阵和接口 x 字段语义等价类矩阵逐项评审，通过或有条件通过后才允许 executor 执行，不通过则退回 planner 完善。
• api-blackbox-test-executor：编码后执行，使用 db-mcp 准备或获取数据，真实请求接口，执行编排链路，记录 curl、DB 验证，以及每个矩阵单元的已执行/跳过/阻塞状态和证据路径。
• api-blackbox-test-reporter：最终总结，汇总计划和执行证据，评估覆盖率、业务场景覆盖、矩阵单元执行完整性、测试结果可信度、通过结论、失败原因、根因分析、解决建议和剩余风险，输出报告。

阶段选择

• 用户说“编码前、先分析、先出方案、测试范围、测试用例、数据准备、接口编排设计”：使用 api-blackbox-test-planner。
• 用户说“评审测试用例、用例审核、执行前把关、测试方案是否完善、四角色评审”：使用 api-blackbox-test-reviewer。
• 用户说“编码完成后、执行测试、真实请求、curl、db-mcp 校验、按用例跑、接口编排执行”：使用 api-blackbox-test-executor。
• 用户说“总结、覆盖率、是否通过、测试报告、失败原因、发布建议”：使用 api-blackbox-test-reporter。
• 用户说“完整黑盒测试、全流程、从方案到报告”：按 planner -> reviewer -> executor -> reporter 顺序执行；如果 reporter 结论不是 通过，必须进入非通过结论强制闭环。只有 REPORT_PASS 是完成态；阻塞 不是完成态，必须先尝试解除阻塞，无法自行解除且必须用户或外部系统输入时才进入 WAIT_USER_INPUT 暂停态。
• 用户已有某阶段输出时，复用已有输出作为下一阶段输入，不重复生成无关内容。

闭环状态

执行前必须读取 references/loop-state.md，按其中的闭环优先级、状态机和最新 artifact 判定算法选择下一阶段。该 reference 是 tester 和 reporter 共享的状态定义，避免两个阶段对同一测试目录给出不同判断。

编排规则

• 四个阶段的交付物必须可衔接：planner 的用例 ID、链路 ID 和数据计划要被 reviewer 评审；reviewer 的最终结果决定是否允许 executor 执行；executor 的 curl 记录、响应、DB 验证要被 reporter 汇总。
• 业务场景拆解、场景 x 边界/异常覆盖矩阵 和 接口 x 字段语义等价类矩阵 是全流程硬追踪对象：planner 必须生成，reviewer 必须逐项评审，executor 必须记录执行状态和证据路径，reporter 必须按这些单元判断覆盖率、可信度和最终结论。
• 测试方案阶段必须根据需求、技术方案、验收标准、状态机、角色权限、数据生命周期和接口链路拆分所有业务场景；每个核心业务场景不能只测 Happy Path，必须覆盖适用边界值、异常路径、权限/状态/数据变体和跨接口失败链路。
• 对逻辑类似、共享字段语义或共享业务规则的接口，必须设计并执行跨接口一致性用例；不得用一个接口的测试结果替代另一个接口的测试结果。
• reviewer 必须让资深软件工程师先基于需求分析和技术方案判断测试范围是否充分，再结合代码变更和依赖关系识别扩散影响；如果改动公共方法、共享组件、公共校验、公共查询、权限逻辑、缓存逻辑、序列化结构、错误处理或数据模型，必须把可能受影响的其他接口、任务、消费者和业务链路纳入测试范围。必要时可使用 GitNexus 或代码搜索分析调用链、API 消费者、数据模型、副作用和跨模块影响。
• executor 执行前必须读取 reviewer 的影响点与影响范围评估，检查现有测试方案是否覆盖直接影响和扩散影响；未覆盖时必须先输出补充测试要求或补充用例草案。关键范围缺口回到 planner 完整补方案，非关键补证项回到 reviewer 评审补充内容，通过或有条件通过后再执行。上下文中缺少影响点和影响范围评估时，必须先基于需求分析和技术方案完成初步评估，再按需使用 GitNexus 等工具辅助。
• 四个阶段必须写入对应 Markdown 文件，默认保存在当前项目根目录下的 tests/【需求】_YYYYMMDD/ 目录中：
  • planner 阶段：tests/【需求】_YYYYMMDD/测试方案.md
  • reviewer 阶段：tests/【需求】_YYYYMMDD/测试用例评审.md
  • executor 阶段：tests/【需求】_YYYYMMDD/执行记录.md
  • reporter 阶段：tests/【需求】_YYYYMMDD/测试报告.md
• 【需求】 应取用户需求的简短标题；如果用户未提供标题，应根据需求内容提炼 8 到 20 个中文字符。文件名中的 /、空格、冒号、引号等不适合作为路径的字符应替换为 _。
• YYYYMMDD 使用执行当天日期，例如 20260428。如果用户明确指定日期，以用户指定日期为准。
• 每个阶段完成后，除在对话中给出摘要外，必须说明已写入的文件路径。无法写文件时必须明确标记为阻塞，并给出原因。
• reviewer 阶段最终结果为 通过 或 有条件通过 时，才允许进入 executor；结果为 不通过 或 阻塞 时，必须退回 planner 完善测试方案或补充输入后重新评审。
• executor 阶段开始前必须读取或确认 测试用例评审.md；如果没有评审记录，或评审结果不是 通过 / 有条件通过，应阻塞并说明需要先完成评审。
• 如果缺少执行环境、凭证、base URL 或安全测试库确认，执行阶段应先阻塞并说明缺口，不要跳到报告结论。
• 复杂需求默认询问或判断是否需要接口编排；如果不需要，planner 必须说明原因。
• 最终报告不能只基于计划输出，必须基于 executor 的真实请求和 DB 验证证据；没有执行证据时，只能输出计划覆盖评估或阻塞结论。
• 最终报告发现任一必测矩阵单元未执行时，不得给出 通过；如果未执行原因是环境、凭证、依赖或数据不可用，结论应为 阻塞，其他非关键未执行项最多为 部分通过。
• 最终报告发现任一必测场景覆盖单元未执行时，不得给出 通过；核心业务场景只有 Happy Path 执行证据时，不得给出发布通过建议。
• reporter 给出最终结论前必须运行 skills/api-blackbox-tester/scripts/validate_test_artifacts.py 和 skills/api-blackbox-tester/scripts/check_report_gate.py。脚本失败时不得结论为 通过，必须把失败项纳入根因分析、复验范围和剩余风险。
• reporter 结论为 失败、部分通过 或 阻塞 时，全流程不得视为完成；必须把所有未通过、部分通过、阻塞和剩余风险整理成下一动作输入，包含问题根因分析、解决建议、复验范围和再次执行的用例/链路 ID，并立即进入强制闭环。用户明确要求暂停或只给建议时，只能停止动作，不能把流程标记为完成。
• 开发修复完成后，必须执行最小验证/单测；如果服务无需重启，直接回到 executor 执行 HTTP/gRPC 接口复验，并由 reporter 基于新的复验证据重新评估测试报告。如果服务需要重启，必须先自动尝试重新编译并重启服务，最多重试 3 次；自动重启成功后继续复验，3 次失败或缺少必要权限/外部控制面时才标记 FIXED_WAIT_RESTART，用户确认后继续复验。循环直到最终结论为 通过；无法自行解除的外部输入缺口只能进入 WAIT_USER_INPUT 暂停态。

非通过结论强制闭环门禁

如果 reporter 结论不是 通过，当前 turn 不得以“已完成测试”结束，也不得把 阻塞 当作流程结束。必须立即选择下一动作：

1. 失败：进入开发修复，修改代码，执行最小验证/单测，必要时自动编译/重启最多 3 次，回到 executor 复验，再由 reporter 重新评估。
2. 部分通过：补齐未执行或未覆盖用例，或修复非关键失败；完成补充验证后回到 executor 复验，再由 reporter 重新评估。
3. 阻塞：先尝试解除阻塞，再复验；不得直接 final。必须按阻塞类型自动尝试：
   • 缺 token 或凭证：搜索本地环境变量、配置、脚本、登录接口和测试账号文档；若可登录则自动获取 token 后复验。
   • DB 实例不匹配：列出实例、切换实例、查询 schema；若可定位目标库则复验。
   • 服务未部署或未重启：执行项目构建、启动或重启命令，最多 3 次。
   • 测试数据缺失：确认是安全测试库后，构造带 codex_api_test_ 标记的最小数据并复验。
   • 依赖服务不可用：检查健康接口、日志、启动脚本或本地替代方案；可控制则启动或修复后复验。

只有阻塞原因必须由用户或外部系统提供，且 agent 已尝试可用自动解除动作并记录失败证据后，才允许暂停。暂停状态必须写为 WAIT_USER_INPUT，不是完成态；只能提出一个最小必要输入，例如“请提供用户 7464942 的 api-test token”。用户提供输入后，必须自动回到 executor 复验。

快速输出

当用户只要求“怎么用”或“下一步怎么做”时：

• 如果没有进行中的测试目录、执行记录或失败/部分通过/阻塞测试报告，才输出应使用的阶段 Skill 和示例 prompt。
• 如果已经存在失败、部分通过或阻塞报告，必须按闭环优先级继续执行下一阶段，不得只输出 prompt 或建议。

示例：

使用 $api-blackbox-test-planner 为当前需求输出接口黑盒测试方案。
使用 $api-blackbox-test-reviewer 对测试方案和测试用例做执行前评审。
使用 $api-blackbox-test-executor 在评审通过后按已有测试用例执行真实接口请求并用 db-mcp 校验。
使用 $api-blackbox-test-reporter 根据测试方案、评审结论和执行证据输出覆盖率评估和测试报告。
如果测试报告结论不是通过，必须按报告中的根因分析和解决建议自动进入开发修复、最小验证/单测、自动编译/重启最多 3 次、接口复验和报告再评估闭环。