thirdparty-api-integration-test skill 解析¶

thirdparty-api-integration-test 是一套面向 Go 第三方 API 客户端的安全执行框架。它的核心设计思想是：第三方 API 集成测试的关键在于怎样在真实配置、真实供应商、真实费用与配额约束下，把测试限定在正确范围、默认保持安全、保留可复现证据，并在失败时把问题更清楚地归类到配置、认证、网络、超时、契约或其他可操作原因上。 因此它把作用域校验、必需模式、配置门禁、供应商特定安全补充、安全规则、共享输出契约和选择性参考资料串成了一条高约束流程。

1. 定义¶

thirdparty-api-integration-test 用于：

• 为 Go 第三方 API 客户端编写和运行真实集成测试
• 在真实配置下验证 vendor 契约与业务语义
• 通过显式门禁、构建标签和生产保护把测试限制为按需执行
• 在外部调用失败时做结构化排障分诊
• 把高成本、高风险的第三方调用测试沉淀成可审计交付物

它输出的不只是测试代码，还包括：

• integration target
• 门禁变量与必需环境变量
• exact run commands
• timeout 与 retry policy
• result summary
• 失败分类
• missing prerequisites

从设计上看，它更像一个“第三方 API 测试治理框架”，而不是一个单纯帮你补几段 Go integration test 的提示词。

2. 背景与问题¶

这个 skill 要解决的，不是“模型不会写 Go API 测试”，而是第三方 API 集成测试天然比内部接口测试更容易出事故：

• 真实调用会消耗供应商额度、费用或限流预算
• 凭证、租户 ID、资源 ID 往往依赖运行时环境
• 错误来源可能来自配置、认证、网络、vendor contract、业务语义，而不是代码本身

如果没有明确流程，常见问题通常集中在 8 类：

thirdparty-api-integration-test 的设计逻辑，就是先把“这是不是第三方 vendor API、运行前提是否齐全、当前环境是否允许、数据生命周期是否安全、失败如何分类”说清楚，再决定生成什么测试代码。

3. 与常见替代方案的对比¶

先看它与几种常见做法的区别：

它的价值，不只是让测试“能调用第三方 API”，而是把第三方 API 测试从高风险即兴操作提升成可控、可复现、可审计的执行流程。

4. 核心设计逻辑¶

4.1 先做 作用域校验 vs 先写测试¶

thirdparty-api-integration-test 的第一道门禁就是 作用域校验门禁。它要求先判断目标是否真的是第三方 vendor API：

• 第三方 HTTP / gRPC API client：继续
• 内部 service / handler：转到 api-integration-test
• 纯单元测试：转到 unit-test
• 浏览器端到端流程：直接判定超出范围

这一步非常关键，因为“写 API 集成测试”在表面上听起来很像，但第三方 API 与内部 API 的风险模型完全不同。内部 API 通常受你自己控制，第三方 API 则牵涉：

• 额度与费用
• 认证与租户隔离
• vendor 版本与限流策略
• 不可控的外部失败模式

评估里最突出的差异也正来自这里：with-skill 在内部 webapp 场景里能明确识别“这不是第三方 API”，并推荐正确 skill；without-skill 虽然写出了高质量内部测试，但没有做任何 scope analysis。

需要说明的是，当前 SKILL.md 已经把这层写成显式的 作用域校验门禁；而现有评估报告仍沿用了更早快照中的表述，把这种边界识别描述为基于 scope 定义推导出来的能力。无论按当前 skill 还是按评估快照理解，这一层的设计价值都一致：它的重点不在生成能力，而在避免测试策略错配。

4.2 必需模式 要把 gate、构建标签 和生产保护写死¶

这个 skill 的 必需模式 非常刚性，要求：

1. 文件名必须是 <client>_integration_test.go
2. 顶部必须带双 构建标签
3. 必须有独立 run gate env var
4. 必须先验证运行时 env vars
5. 默认拒绝 production

这几条看起来像样板代码，但其实是整个 skill 的结构骨架。它解决的问题不是“格式统一”，而是：

• 避免误触发
• 避免 CI 默认路径运行高成本测试
• 避免把 credential var 当成唯一 gate
• 避免生产环境误打真实供应商

评估里 Gate env var isolation、生产环境安全门禁、Build tag isolation 都是最稳定的差异项，这说明 skill 真正的价值首先来自执行边界控制，而不是断言细节。

4.3 显式 gate env var 是最高杠杆设计之一¶

thirdparty-api-integration-test 明确要求：

• 使用独立 gate env var，如 THIRDPARTY_INTEGRATION=1 或 vendor-specific gate
• 凭证变量只负责认证，不负责决定是否运行

这层设计非常关键，因为如果只靠 GITHUB_TOKEN、OPENAI_API_KEY 这类 credential 变量做隐式 gate，那么开发者 shell、CI secret、共享 runner 环境里只要这些变量存在，测试就可能被意外触发。

评估里的 GitHub 场景就清楚说明了这一点：with-skill 使用 GITHUB_INTEGRATION=1 + GITHUB_TOKEN 二级 gate；without-skill 则只靠 GITHUB_TOKEN。这类区别在平时不显眼，但一旦进入自动化环境，就是典型的“默认危险，显式安全”差异。

4.4 生产环境安全门禁 必须是硬门禁¶

skill 明确规定：

• ENV=prod / production 时默认 t.Skip
• 只有 INTEGRATION_ALLOW_PROD=1 才允许 override

这层设计是整个 skill 最有安全价值的部分之一。对第三方 API 而言，生产环境不是抽象风险，而是非常具体的成本和影响：

• 调用付费 API 产生费用
• 消耗 quota
• 触发 vendor rate-limit
• 对真实租户 / 账户产生副作用

评估也把这层列为 skill-only 能力：with-skill 3/3，without-skill 0/3。这说明在第三方 API 场景里，生产保护不是“锦上添花”，而是最基础的执行门槛。

4.5 把 env var 解析与校验写得这么细¶

thirdparty-api-integration-test 不只要求读取 env var，还要求：

• strings.TrimSpace
• strconv.ParseInt
• 逗号分隔列表逐项校验
• t.Logf 输出解析后的非敏感值

这层设计很务实，因为第三方 API 测试常常依赖：

• tenant ID
• label ID
• target resource ID
• region
• config path

这些值一旦格式不规范，测试就会以非常模糊的方式失败。skill 通过前置校验，把“运行时莫名其妙失败”变成“启动前就知道缺什么或格式不对”。这也是评估里 Env var validation 能形成明确差异的原因。

4.6 强调真实 client 与真实运行路径¶

这个 skill 明确要求：

• 通过项目配置加载器构建 client
• 走 production code path
• 执行真实外部调用

它要解决的问题是：很多所谓“第三方 API integration test”其实只是把 transport mock 掉，最后只验证本地参数组装逻辑。这种测试当然也有价值，但它已经不是这个 skill 的目标。

thirdparty-api-integration-test 要保住的是外部契约验证这层价值：

• 配置是否真能构建 client
• 请求是否真能打到 vendor
• 响应结构是否符合协议
• 业务语义是否仍然成立

这让它和普通 unit-test 或 fake-based test 的边界非常清楚。

4.7 要求协议级与业务级双重断言¶

这个 skill 不满足于只检查：

• 状态码
• 非空字段
• require.NoError

而是要求同时断言：

• protocol-level contract
• business-level invariant

这层设计很重要，因为第三方 API 测试最容易出现的一种假通过是：

• 请求发通了
• 返回了对象
• 测试就结束了

但一个 vendor API 即使保持 200 OK，也可能在语义层发生回归，比如：

• 标识符不一致
• 响应字段含义变化
• 状态语义漂移

评估里 GitHub 场景与 OpenAI 场景都说明，基础模型本来就会写基本断言；skill 的增量在于把“协议通过”和“业务仍正确”同时纳入检查目标。

4.8 expected failure path 必须检查 error type/code¶

skill 明确要求：对于预期失败路径，不能只写 require.Error，而要断言明确 error type / code。

这层设计非常关键，因为第三方 API 的失败模式往往本身就是契约的一部分。例如：

• 404 变成 403
• auth failure 变成 generic 500
• vendor SDK 包装 error type 变化

如果测试只写 err != nil，这些真正重要的回归很可能被掩盖。评估里的 GitHub 404 场景就是这个问题的标准例子：with-skill 能检查 *statusError 与 404，without-skill 则只能证明“有错”。

4.9 test data lifecycle 必须显式声明¶

thirdparty-api-integration-test 要求把测试数据生命周期写清楚：

• setup 来源
• idempotency key 策略
• cleanup 或 safe reuse policy

这层设计很成熟，因为第三方 API 测试不像本地单测那样天然可重复。很多风险都来自数据层：

• 共享 tenant 被污染
• 同一个 ID 被重复消费
• mutation endpoint 造成脏状态

skill 通过 lifecycle 声明，把“这个测试用什么数据、是否可重跑、是否需要清理”纳入设计，而不是让这些信息散落在实现细节里。

4.10 供应商特定安全补充 要强调 idempotent 默认路径¶

这个 skill 明确偏好：

• 默认使用 idempotent endpoint
• 对 mutation endpoint 额外要求 dedicated test tenant / account 与显式 opt-in gate
• 对 rate-limit 行为进行分类而不是误判成 contract failure

这层设计很有针对性，因为第三方 API 与内部 API 最大的不同之一，就是你无法完全控制其副作用成本。skill 因此优先把默认执行路径收敛到低风险调用，再把高风险 mutation 调用变成额外授权动作。

这也是为什么它对 paid API、rate-limit header、Retry-After、secret logging 都有单独补充规则。它不是在追求“更全面”，而是在追求“默认更安全”。

4.11 共享输出契约¶

这个 skill 要求每次执行都输出共享报告，至少包括：

• integration target
• gate vars
• exact commands
• timeout / retry
• result summary
• 失败分类
• missing prerequisites

这层设计解决的是一个现实问题：团队往往拿到测试代码后，依然不知道：

• 该设置哪些变量
• 该跑什么命令
• 为什么当前是 skip
• 失败是配置问题还是契约问题

结构化输出把“测试文件”升级成“测试交付物”。评估里这也是 skill-only 差异之一：with-skill 的报告可以直接支持复现与 triage，without-skill 只有简短摘要。

4.12 references 要按任务形态加载¶

thirdparty-api-integration-test 的 references 不是一次全读，而是分层使用：

• common-integration-gate.md 总是要读
• common-output-contract.md 总是要读
• checklists.md 在 authoring / triage 时读
• vendor-examples.md 在仓库内没有现成 vendor 模式时读

这种设计很合理，因为第三方 API 测试有一部分是共性问题：

• gate
• prod safety
• 输出契约

另一部分则是 vendor-specific 模板与运行命令。通过 selective loading，skill 把高频共性规则固定住，把低频模板延后加载，既提高了规则密度，也控制了 token 成本。评估里的 token 数据也支持这一点：它用很小的 SKILL.md 就获得了非常高的效费比。

5. 这个设计解决了哪些具体问题¶

结合当前 SKILL.md、关键 references 和评估报告，可以把它解决的问题归纳为：

6. 主要亮点¶

6.1 它把第三方 API 测试先定义为安全问题，再定义为测试问题¶

先控制运行边界，再谈断言细节，这是这个 skill 最重要的设计取向。

6.2 显式 gate + prod safety + 构建标签 形成了清晰的安全闭环¶

这三层组合在一起，让第三方 API 集成测试默认 opt-in、默认隔离、默认拒绝生产。

6.3 范围 boundary 识别非常有辨识度¶

它不只是会写测试，还会判断什么时候不该用自己，并把任务转给更合适的 skill。

6.4 它把“失败可诊断”纳入设计目标¶

失败分类、缺失前置条件、精确命令，使测试结果可以直接进入排障分诊，而不是只留下一个红灯。

6.5 它对高成本 vendor 场景非常敏感¶

paid API、rate-limit、mutation endpoint、tenant 污染、secret logging，这些都被纳入了默认规则。

6.6 当前版本的真正增量，在执行治理而不在基本测试代码能力¶

评估已经说明：基础模型本来就会写 context.WithTimeout、基本断言、真实 client 路径、文件命名；真正的差距在 gate env vars、prod safety、构建标签、error precision、scope analysis 和 structured output。这说明 thirdparty-api-integration-test 的核心价值是第三方测试治理，而不是单纯“更会写 Go integration test”。

7. 什么时候适合用，什么时候不该硬用¶

8. 结论¶

thirdparty-api-integration-test 的真正亮点，不是它能写出一条第三方 API 调用，而是它把第三方集成测试里最容易失控的因素系统化了：先判断 scope，再建立显式 gate、生产保护和 构建标签 隔离，再对 env vars、真实 client 路径、协议级与业务级断言、失败分类和测试数据生命周期做严格约束，最后把执行结果结构化交付出来。

从设计上看，这个 skill 很清楚地体现了一条原则：高质量第三方 API 集成测试的关键，不是尽快打通一次请求，而是让每次真实外部调用都默认安全、默认可控、默认可诊断，并且让团队知道什么时候该跑、为什么没跑、失败属于哪一类、下一步该怎么复现。 这也是它特别适合 vendor contract verification、外部调用故障排查和高成本 API gated regression 场景的原因。

9. 文档维护¶

当以下内容发生变化时，这份文档应该同步更新：

• skills/thirdparty-api-integration-test/SKILL.md 中的 作用域校验门禁、必需模式、配置门禁、供应商特定安全补充、安全规则 或 输出契约 发生变化。
• skills/thirdparty-api-integration-test/references/common-integration-gate.md、common-output-contract.md、checklists.md 或 vendor-examples.md 中的关键 gate、报告格式、checklist 或 vendor 模板发生变化。
• evaluate/thirdparty-api-integration-test-skill-eval-report.md 或 evaluate/thirdparty-api-integration-test-skill-eval-report.zh-CN.md 中支撑本文判断的核心结果发生变化。

建议按季度复查一次；如果 thirdparty-api-integration-test 的 scope 路由、显式 gate 规则、prod safety、构建标签 规则或输出契约有明显重构，则应立即复查。

10. 相关阅读¶

• skills/thirdparty-api-integration-test/SKILL.md
• skills/thirdparty-api-integration-test/references/common-integration-gate.md
• skills/thirdparty-api-integration-test/references/common-output-contract.md
• skills/thirdparty-api-integration-test/references/checklists.md
• skills/thirdparty-api-integration-test/references/vendor-examples.md
• evaluate/thirdparty-api-integration-test-skill-eval-report.md
• evaluate/thirdparty-api-integration-test-skill-eval-report.zh-CN.md