api-blackbox-test-reporter

name	api-blackbox-test-reporter
description	接口黑盒测试报告 Skill。当用户需要根据编码前测试方案、测试用例评审结论和编码后真实执行证据，评估需求覆盖率、用例执行覆盖率、接口覆盖率、业务场景覆盖率、接口 x 字段语义等价类矩阵执行覆盖率、场景 x 边界/异常覆盖率、跨接口一致性覆盖率、边界测试覆盖率、安全测试覆盖率、编排/集成链路覆盖率、性能测试建议、兼容性结论、测试是否通过、测试结果可信度，并为未通过、部分通过、阻塞和剩余风险输出根因分析、解决建议、复验范围和测试报告时使用。

接口黑盒测试报告

目标

基于 planner 的测试方案、reviewer 的测试用例评审结论和 executor 的真实执行证据，输出最终测试报告。报告和终端回复都必须包含测试执行汇总：计划用例数、已执行用例数、通过用例数、未通过用例数、跳过用例数、阻塞用例数、未执行用例数、未通过根因简述和最终测试结论。没有真实请求和 DB 验证证据时，不得给出“通过”结论，只能说明证据不足或阻塞。任一必测 接口 x 字段语义等价类矩阵 单元未执行时，不得给出“通过”结论。

如果测试报告结论不是 通过，本阶段必须输出可执行的下一动作并继续推进闭环。只有新的测试报告结论为 通过 时，完整黑盒测试流程才算闭环完成；失败、部分通过 和 阻塞 都不是完成态。阻塞 必须先尝试自动解除，只有 agent 已尝试且无法自行解除、缺口必须由用户或外部系统提供时，才允许进入 WAIT_USER_INPUT 暂停态。

最终结论前必须优先使用 ../api-blackbox-tester/scripts/validate_test_artifacts.py 和 ../api-blackbox-tester/scripts/check_report_gate.py 对同一测试目录做自动门禁校验。脚本失败时，最终结论不得为 通过；必须把失败项写入报告的失败项、根因分析、复验范围和剩余风险。脚本不可运行时，必须在报告中说明阻塞或证据不足原因，不得绕过门禁直接通过。

闭环状态

执行前必须读取 ../api-blackbox-tester/references/loop-state.md，按其中的闭环优先级、状态机和最新 artifact 判定算法选择下一阶段。该 reference 是 tester 和 reporter 共享的状态定义；如果本文件与 reference 出现不一致，以 reference 为准。

文件输出

本阶段必须将完整测试报告写入 Markdown 文件。默认路径为：

tests/【需求】_YYYYMMDD/测试报告.md

规则：

• 【需求】 必须与 planner、reviewer 和 executor 阶段目录保持一致；如果已有 tests/【需求】_YYYYMMDD/测试方案.md、tests/【需求】_YYYYMMDD/测试用例评审.md 或 tests/【需求】_YYYYMMDD/执行记录.md，应复用同一目录。
• YYYYMMDD 使用执行当天日期，例如 20260428；如果前序阶段已确定日期，以既有目录为准。
• 文件名中的 /、空格、冒号、引号等不适合作为路径的字符应替换为 _。
• 写入文件后，终端回复必须输出与报告一致的测试执行汇总、文件路径、最终结论、覆盖率摘要、未通过根因简述、下一步动作和剩余风险；不得只说明“已写入报告”。
• 无法写入文件时，必须标记为阻塞并说明原因，不得只在对话中输出完整报告后视为完成。

终端输出要求

完成报告文件写入后，终端回复必须包含一个简短但完整的同步摘要，字段不得缺失：

• 报告路径。
• 测试用例汇总：计划、已执行、通过、未通过、跳过、阻塞、未执行。
• 未通过根因简述：按问题或根因类别汇总；无未通过时写“无”。
• 覆盖率摘要：至少包含需求覆盖率、用例执行覆盖率、接口覆盖率、矩阵单元执行覆盖率和跨接口一致性覆盖率。
• 最终测试结论：通过、失败、部分通过或阻塞。
• 下一步动作：通过时给出发布建议；非通过时给出开发修复、补齐覆盖、阻塞解除或复验动作。
• 剩余风险：无风险时写“无”。

终端摘要必须来自同一份执行证据和报告内容，不能与 测试报告.md 中的数字、结论或根因不一致。

输入要求

尽量收集：

• 编码前测试范围、兼容性验证、测试用例、边界测试、安全测试、补充验证项、接口编排/集成链路、性能测试建议和测试数据计划。
• planner 输出的接口 x 字段语义等价类矩阵，以及跨接口一致性测试计划。
• 测试用例评审记录，包括四角色意见、小组讨论结论、最终评审结果、退回项和 executor 执行关注项。
• 编码后测试数据准备记录。
• 所有 curl 请求记录、请求参数、返回数据、是否通过和不通过原因。
• 测试用例执行统计，包括计划、已执行、通过、未通过、跳过、阻塞和未执行数量。
• 接口编排/集成链路的步骤记录、数据提取、传递目标、是否包含非本次变更接口和步骤结果。
• 每个矩阵单元的执行状态、证据路径、失败/跳过/阻塞原因。
• 跨接口一致性用例中每个参与接口的独立请求证据和对比结果。
• db-mcp 查询或写入验证证据。
• 失败、阻塞、跳过和清理记录。
• 已修复后的复验记录；如果是复验报告，必须区分首次执行证据和复验证据。

覆盖率评估

基于计划和执行证据评估：

• 需求覆盖率：已验证需求点数 / 需求点总数。
• 用例执行覆盖率：已执行用例数 / 计划用例总数。
• 矩阵单元执行覆盖率：已执行必测矩阵单元数 / 必测矩阵单元总数。
• 接口覆盖率：已请求接口数 / 计划接口总数。
• 边界测试覆盖率：已执行边界用例数 / 计划边界用例总数。
• 安全测试覆盖率：已执行安全用例数 / 计划安全用例总数。
• 编排/集成链路覆盖率：已执行编排/集成链路数 / 计划编排/集成链路总数。
• 业务场景覆盖率：已验证业务场景数 / 计划业务场景总数。
• 场景 x 边界/异常覆盖率：已执行必测场景覆盖单元数 / 必测场景覆盖单元总数。
• 性能测试建议覆盖率：已评估性能风险接口或链路数 / 计划评估接口或链路总数。
• 数据场景覆盖率：已验证数据场景数 / 计划数据场景总数。
• 兼容性覆盖率：已验证兼容性检查数 / 计划兼容性检查总数。
• 跨接口一致性覆盖率：已执行跨接口一致性用例数 / 计划跨接口一致性用例总数。

覆盖率不能只给百分比，必须列出未覆盖项和原因。

用例执行覆盖率之外，必须单独输出用例结果分布，不能只给百分比：计划用例总数、已执行、通过、未通过、跳过、阻塞、未执行。未通过 包含断言失败、接口契约失败、DB 校验失败、兼容性失败和安全失败；阻塞 和 跳过 必须单独计数，不能并入通过。

矩阵单元结论规则

• 必测矩阵单元全部 已执行 且关联断言通过，才允许报告结论为 通过。
• 任一必测矩阵单元为 阻塞，且原因是环境、凭证、依赖、测试数据、安全授权或不可访问接口，最终结论必须为 阻塞。
• 任一必测矩阵单元为 跳过 或缺少证据路径，且不属于已确认范围外，最终结论最多为 部分通过。
• 任一必测矩阵单元执行失败，最终结论必须为 失败，除非该单元经 reviewer 明确降级为非关键且核心路径全部通过，此时最多为 部分通过。
• 对逻辑类似接口，如果缺少跨接口一致性执行证据，不得因为其中一个接口已通过而判定另一个接口通过。
• 对业务场景拆解，如果核心业务场景缺少边界/异常执行证据，或 场景 x 边界/异常覆盖矩阵 中任一必测覆盖单元未执行，最终结论不得为 通过。

测试结果可信度评分

报告必须读取 ../api-blackbox-tester/references/reliability-scoring.md，按其中规则输出 0-100 的测试结果可信度评分、可信度等级和是否允许作为发布门禁依据。可信度评分低于 85 时，即使核心用例通过，也不得给出发布通过建议；最多为 部分通过 或带明确风险的非发布结论。

根因分析和解决建议

所有未通过、部分通过、阻塞、跳过、未覆盖项和剩余风险都必须给出问题根因分析和解决建议，不能只列问题。

要求：

• 根因分析必须基于接口响应、curl 请求、DB 验证、日志、配置、环境、数据准备或需求/契约证据；证据不足时必须写明“疑似根因”和需要补充的定位证据。
• 解决建议必须指向可执行动作，例如修改接口实现、补充参数校验、修复权限判断、修正 DB 写入、补充测试数据、恢复依赖服务、补齐凭证或更新测试方案。
• 每个问题必须标明责任阶段：开发修复、测试数据准备、环境/运维、需求澄清、测试方案补充或安全授权。
• 每个问题必须给出复验范围，包括需要重跑的用例 ID、接口、链路 ID、DB 校验和兼容性/安全回归项。
• 剩余风险不能只写风险描述；必须说明根因、影响、建议处理方式、是否阻塞发布，以及后续验证方法。

测试结论规则

• 通过：关键用例全部通过，所有必测矩阵单元均已执行且通过，跨接口一致性必测项已执行且通过，兼容性检查通过，没有阻塞关键路径。
• 失败：存在需求功能、接口契约、数据库状态或兼容性失败。
• 部分通过：核心路径通过，但存在非关键失败或未覆盖项。
• 阻塞：关键环境、数据、凭证或依赖缺失，无法形成有效结论。

当结论为 失败、部分通过 或 阻塞 时：

• 不得给出发布通过建议。
• 必须输出“开发修复与复验计划”。
• 必须继续推动下一动作；不能只说明修复后需要回到 executor。
• 失败 必须转成开发修复任务并立即执行；修复完成并通过最小验证/单测后，必须回到 executor 执行真实 HTTP/gRPC 复验，再由 reporter 基于复验证据重新评估。
• 部分通过 必须补齐未执行/未覆盖用例，或修复非关键失败，再回到 executor 复验。
• 阻塞 不得只输出报告。必须生成并执行“阻塞解除计划”，解除后立即回到 executor 复验；只有自动解除动作失败且缺口必须由用户或外部系统提供时，才进入 WAIT_USER_INPUT。

阻塞解除计划

当结论为 阻塞 时，必须按阻塞类型执行以下自动尝试，并在报告中记录动作、结果、证据和下一步：

阻塞类型	必须自动尝试
缺 token 或凭证	搜索本地 env/config/script；查找登录接口；尝试使用测试账号登录；仍失败则 WAIT_USER_INPUT
DB 实例不匹配	使用 db_list_instances、db_switch、db_describe，按表和用户/业务主键查询；仍失败则 WAIT_USER_INPUT
服务未部署或未重启	根据项目脚本执行 build/start/restart，最多 3 次
测试数据缺失	确认测试库安全后构造带 codex_api_test_ 标记的数据，执行后清理
依赖服务不可用	检查健康接口、日志、启动脚本、本地 mock/stub 或降级配置；无法控制则 WAIT_USER_INPUT

进入 WAIT_USER_INPUT 时，只能询问一个最小必要输入，并写明已尝试的自动解除动作、失败证据和用户提供输入后的复验范围。用户提供输入后，必须自动回到 executor 复验，不得重新停在报告说明。

输出格式

使用 references/report-template.md 输出报告。报告必须包含：

• 测试执行汇总，包括执行了多少条测试用例、通过多少条、未通过多少条、跳过/阻塞/未执行多少条、未通过根因简述和最终测试结论。
• 测试目标和环境。
• 编码前测试方案摘要。
• 测试用例评审结论。
• 执行证据。
• 所有接口请求的 curl 记录。
• 接口编排链路和数据传递记录。
• 性能测试评估与建议。
• 失败项。
• 问题根因分析与解决建议。
• 开发修复与复验计划。
• 闭环执行状态，包括最小验证/单测、最多 3 次自动编译/重启尝试、executor 复验和阻塞原因。
• 覆盖率评估。
• 矩阵单元执行完整性和跨接口一致性覆盖。
• 业务场景覆盖、场景 x 边界/异常覆盖和测试结果可信度评分。
• 测试数据和清理状态。
• 兼容性说明。
• 最终总结和发布建议。
• 剩余风险。