api-design 技能评估报告¶
评估框架: skill-creator A/B 实测对比法 评估日期: 2026-04-18 评估对象:
skills/api-design/（REST API 合约设计与审查技能）
api-design 技能的评估呈现出明显的场景分化规律：标准多缺陷审查和最小上下文降级场景中基线表现接近完美，但破坏性变更评估场景（公共 API + 12 个合作方集成）中基线质量仅 66.7%，是本次已评估技能中跌幅最大的单一场景。Gate 3 STOP 机制和 §8.7 兼容性评估框架是技能对于该场景的核心差异化来源。
1. Skill 概述¶
核心组件：
| 文件 | 行数 | 职责 |
|---|---|---|
SKILL.md | ~380 行 | 主框架：4 Gate、3 深度、16 项 Checklist、12 项 Scorecard、9 节输出合约 |
references/error-model-patterns.md | ~180 行 | Standard/Deep：标准错误信封、幂等键实现、ETag 并发控制、IDOR-safe 404 |
references/compatibility-rules.md | ~200 行 | Deep/破坏性变更：向后兼容矩阵、Sunset 协议、版本共存、合约测试 CI |
references/api-anti-examples.md | ~140 行 | 扩展反例 AE-7 至 AE-13 |
技能核心安全规范： - AE-1: URL 中含动词（/createUser）→ 破坏 REST 语义和工具链 - AE-2: HTTP 200 用于错误 → 欺骗 CDN/客户端/监控 - AE-3: 无 machine-parseable 错误码 → 客户端只能字符串匹配 - AE-5: 无对象级授权（IDOR）→ OWASP API Security Top 1 - Breaking Change GUARDRAIL: 公共 API 任何字段删除/重命名/类型变更必须触发 Gate 3 STOP，强制 migration plan
2. 测试设计¶
2.1 场景定义¶
| # | 场景名称 | 背景 | 核心挑战 | 期望结果 |
|---|---|---|---|---|
| 1 | 多缺陷 REST API 审查 | 内部订单管理 API，React/iOS 消费者 | verb URL + 200 for errors + IDOR + 无幂等键 | Critical 0/3，Scorecard FAIL |
| 2 | 公共 API 破坏性变更 | v1 公共 API，12 合作方集成 | 4 项破坏性变更无版本规划 | Gate 3 STOP，v2 + deprecation 90 天 |
| 3 | 最小上下文（降级模式） | 版本/消费者/public-internal 全部未知 | 支付 API，无任何架构背景 | Minimal 模式，consumer type unknown |
2.2 断言矩阵（24 项）¶
场景 1 — 多缺陷 REST API 审查（9 项）
| ID | 断言 | With-Skill | Without-Skill |
|---|---|---|---|
| A1 | 识别 /createOrder、/cancelOrder URL 含动词为 Critical 缺陷（AE-1） | PASS | PASS |
| A2 | 识别 HTTP 200 用于错误响应为 Critical 缺陷（AE-2） | PASS | PASS |
| A3 | 识别 GET /orders/{id} 无 IDOR 授权检查为 Critical 缺陷（OWASP #1） | PASS | PASS |
| A4 | 识别缺少 Idempotency-Key 为 Standard 缺陷（移动端重试导致重复订单） | PASS | PASS |
| A5 | 建议标准错误信封格式 {error: {code, message, details[], trace_id}} | PASS | PASS |
| A6 | 建议 cursor-based pagination（替代 offset，避免高并发数据漂移） | PASS | PASS |
| A7 | 原始 API Scorecard: Critical 0/3（URL 命名/错误模型/IDOR 全部 FAIL） | PASS | PASS |
| A8 | §8.9 使用规定 4 列表格（Area | Reason | Impact | Follow-up） | PASS | PASS |
| A9 | 明确引用 Anti-example 编号（AE-1、AE-2、AE-5）交叉参照 | PASS | PARTIAL |
场景 1 小结：With-Skill 9/9，Without-Skill 8.5/9（PARTIAL: AE 编号仅随机提及 AE-5，未系统引用）
场景 2 — 公共 API 破坏性变更（9 项）
| ID | 断言 | With-Skill | Without-Skill |
|---|---|---|---|
| B1 | 识别删除 phone_number 为 breaking change（字段删除） | PASS | PASS |
| B2 | 识别添加 required billing_address 为 CRITICAL breaking（现有客户端全部 4xx 失败） | PASS | PASS |
| B3 | 识别错误格式从 string → object 结构变更为 breaking（所有 error path 受影响） | PASS | PASS |
| B4 | 识别 order_status → status 字段重命名为 breaking change | PASS | PASS |
| B5 | 建议创建 /api/v2/ 版本（path versioning），v1 保持不变 | PASS | PASS |
| B6 | 建议 Deprecation + Sunset headers 协议（最少 90 天窗口） | PASS | PASS |
| B7 | Gate 3 STOP 条件显式触发（UNSAFE，需要 migration plan 方可继续） | PASS | FAIL |
| B8 | §8.9 使用规定 4 列表格（Area | Reason | Impact | Follow-up） | PASS | FAIL |
| B9 | Data basis: 标注（full context / degraded / minimal） | PASS | FAIL |
场景 2 小结：With-Skill 9/9，Without-Skill 6/9（3 项 FAIL：Gate 框架、§8.9 格式、Data basis 标注）
场景 3 — 最小上下文降级模式（6 项）
| ID | 断言 | With-Skill | Without-Skill |
|---|---|---|---|
| C1 | 声明 Minimal/Degraded Mode 并标注 | PASS | PASS |
| C2 | §8.9 包含 "consumer type unknown" 风险项 | PASS | PASS |
| C3 | §8.9 包含 "public vs internal unknown" 风险项 | PASS | PASS |
| C4 | §8.9 使用规定 4 列表格（Area | Reason | Impact | Follow-up） | PASS | PASS |
| C5 | 识别 POST /payments 缺少 Idempotency-Key（金融交易，重试即重复扣款） | PASS | PASS |
| C6 | Data basis: minimal 标注 | PASS | PASS |
场景 3 小结：With-Skill 6/6，Without-Skill 6/6（场景 3 无差距）
3. 通过率对比¶
3.1 总体断言通过率¶
| 配置 | PASS | PARTIAL | FAIL | 通过率（严格） |
|---|---|---|---|---|
| With Skill | 24/24 | 0 | 0 | 100% |
| Without Skill | 20/24 | 1 | 3 | 83.3% + 2.1% partial |
Delta：+14.6 percentage points（严格 PASS 口径）
3.2 按场景通过率¶
| 场景 | With-Skill | Without-Skill | 失分项 |
|---|---|---|---|
| S1 多缺陷审查 | 9/9 (100%) | 8.5/9 (94.4%) | A9: AE 编号引用 |
| S2 破坏性变更 | 9/9 (100%) | 6/9 (66.7%) | B7/B8/B9: Gate STOP + §8.9格式 + Data basis |
| S3 最小上下文 | 6/6 (100%) | 6/6 (100%) | 无差距 |
3.3 场景差距分析¶
S2 是所有已评估技能场景中基线质量最低的单场景（66.7%）。
原因：公共 API 破坏性变更场景需要技能框架的三项特定能力： 1. Gate 3 STOP 机制：无 Skill 组直接给出叙述性建议，未触发 STOP/PROCEED 框架 2. §8.9 Uncovered Risks 表格：无 Skill 组使用"Compatibility Summary"和"What Must Be Done"等自由格式，未使用 4 列表格 3. Data basis 标注：无 Skill 组的输出末尾无此标注
S1 基线高（94.4%）是因为多缺陷识别（AE-1/AE-2/AE-5）是基础模型的强项——REST 设计反模式属于普遍知识。S3 基线满分（100%）原因与之前评估相同。
4. 关键差异分析¶
4.1 With-Skill 专有行为¶
| 行为 | 出现场景 | 依据 |
|---|---|---|
| Gate 3 STOP 显式声明（UNSAFE + 要求 migration plan） | S2 | §2 Mandatory Gates 框架 |
| §8.1–§8.9 规范节编号（含 §8.7 Compatibility Assessment） | S1、S2、S3 | §8 Output Contract |
| AE 编号系统引用（AE-1、AE-2、AE-5） | S1 | §6 Anti-Examples 交叉参照 |
| 每项变更独立的 breaking/non-breaking 分类 + 迁移方案 | S2 | §5.4/references/compatibility-rules.md |
| Data basis 在 Scorecard 后强制标注 | S1、S2、S3 | §8 Scorecard 合约 |
4.2 S2 的无 Skill 基线失分分析¶
无 Skill 组（14,053 tokens）在 S2 场景中产生了本次评估中最小的 token 消耗，同时产生了最低的质量分。这揭示了一个重要规律：
当基线 LLM 不跟随框架时，它倾向于用更少 token 给出更直觉性的建议，而非系统性的逐项分析。在简单场景下这是正确行为；在需要结构化分析的复杂场景（如公共 API 破坏性变更评估）中，这导致关键框架要素（Gate STOP、§8.9 格式、Data basis）缺失。
4.3 技术知识对比¶
| 检查点 | With-Skill | Without-Skill |
|---|---|---|
| 4 类 breaking change 识别 | PASS | PASS |
| Sunset 协议（90 天警告） | PASS | PASS |
| v1/v2 版本共存策略 | PASS | PASS |
| IDOR 返回 404 而非 403 | PASS | PASS |
| Idempotency-Key 金融交易 | PASS | PASS |
| Gate 3 STOP 框架显式触发 | PASS | FAIL |
| §8.7 Compatibility Assessment 分项表格 | PASS | FAIL |
5. Token 效费比分析¶
5.1 Skill 上下文 Token 成本¶
| 组件 | 行数 | 估算 Token 数 | 加载时机 |
|---|---|---|---|
SKILL.md | ~380 | ~5,000 | 每次 |
error-model-patterns.md | ~180 | ~2,300 | Standard/Deep |
compatibility-rules.md | ~200 | ~2,600 | Deep/breaking change |
5.2 实际运行 Token 消耗¶
| 代理 | 场景 | Total Tokens | Tool Calls | 输出质量 |
|---|---|---|---|---|
| Without Skill | S1 | 36,546 | 2 | 探索式，全部缺陷均找到 |
| With Skill | S1 | 18,229 | 0 | 结构化，AE 引用 |
| Without Skill | S2 | 14,053 | 0 | 叙述性，漏 Gate/§8.9/Data basis |
| With Skill | S2 | 18,577 | 0 | 完整 §8.x 结构，Gate STOP |
| Without Skill | S3 | 36,028 | 2 | 探索式，质量与技能相当 |
| With Skill | S3 | 16,420 | 0 | 结构化，Minimal 模式 |
5.3 效费比计算¶
| 指标 | S1 | S2（异常） | S3 | 均值 |
|---|---|---|---|---|
| 无 Skill Token | 33,536 | 14,053 | 32,257 | 26,615 |
| 有 Skill Token | 18,229 | 18,577 | 16,420 | 17,742 |
| Token 变化 | −45.7% | +32.2% | −49.1% | −33.3% |
| 质量提升 | +5.6 pp | +33.3 pp | 0 pp | +14.6 pp |
S2 Token-质量倒置是本次评估最独特的发现：
- 无 Skill 组（14,053 tokens）更便宜但质量更差：叙述性分析，跳过 §8.x 框架
- 有 Skill 组（18,577 tokens）更贵但质量更好：完整 §8.1–§8.9 + Gate 分析 + 兼容性矩阵
结论：当结构化输出本身就是价值所在时（公共 API 破坏性变更需要可追溯的逐项分析），Token 成本的增加是可接受的。S2 中多付出的 ~4,500 tokens 换来的是 +33.3 pp 质量提升，效率最高。
相比之下，S1/S3 场景中技能节省约 47% Token 同时维持或提升质量。
6. 综合评分¶
6.1 分维度评分（5 分制）¶
| 维度 | With Skill | Without Skill | 差值 |
|---|---|---|---|
| Critical 缺陷识别（URL/错误/IDOR） | 5.0 | 4.8 | +0.2 |
| API 合约输出结构（§8.x 规范完整性） | 5.0 | 3.5 | +1.5 |
| 破坏性变更评估框架（Gate + §8.7） | 5.0 | 3.0 | +2.0 |
| 错误模型设计（信封/状态码/IDOR-safe 404） | 5.0 | 4.5 | +0.5 |
| 降级模式处理（Minimal context） | 5.0 | 4.5 | +0.5 |
| Anti-Pattern 框架引用（AE 编号/Gate） | 5.0 | 3.5 | +1.5 |
6.2 加权总分（满分 10 分）¶
| 维度 | 权重 | With-Skill | Without-Skill | 评分理由 |
|---|---|---|---|---|
| Critical 缺陷识别 | 25% | 10.0/10 | 9.5/10 | 两者均正确识别 IDOR/AE-1/AE-2；无 Skill 在 IDOR 说明深度上略浅 |
| API 合约输出结构 | 20% | 10.0/10 | 7.0/10 | §8.x 规范格式：有 Skill 100% 合规；无 Skill 在 S2 完全未使用 §8.9 表格 |
| 破坏性变更框架 | 20% | 10.0/10 | 6.0/10 | Gate 3 STOP + §8.7 分项矩阵：无 Skill 仅给叙述性建议，未触发框架 |
| 错误模型设计 | 15% | 10.0/10 | 9.0/10 | 两者均建议标准信封；有 Skill 含 metric/audit 可观测性字段 |
| 降级模式处理 | 10% | 10.0/10 | 9.0/10 | S3 两者均满分；有 Skill 的 §8.9 风险列更完整（12 vs 8 条） |
| Anti-Pattern 引用 | 10% | 10.0/10 | 7.0/10 | AE 编号引用：有 Skill 系统交叉引用；无 Skill 偶发提及 |
| 加权总分 | 100% | 10.00/10 | 7.95/10 | — |
7. 核心发现与建议¶
发现 1：破坏性变更评估是 api-design 技能最大差异化来源¶
与 pg/mongo/redis 迁移/缓存技能不同，api-design 的差异不均匀分布在各场景：
| 场景类型 | 基线质量 | 技能价值来源 |
|---|---|---|
| 标准多缺陷审查（S1） | 94.4% | 框架引用规范性（微小差距） |
| 公共 API 破坏性变更（S2） | 66.7% | Gate 3 STOP + §8.7 兼容性矩阵（最大差距） |
| 最小上下文降级（S3） | 100% | 无差距 |
对于团队管理公共 API + 外部合作方集成的场景，技能的 ROI 远高于标准内部 API 审查。
发现 2：S2 Token-质量倒置揭示"框架开销即价值"规律¶
当基线选择省略结构化框架时（S2 无 Skill: 14,053 tokens），它产生了更便宜但质量更差的输出。这揭示了一个关键规律：
框架（§8.x 输出合约）本身不仅是格式要求，它强制触发思考过程。Gate 3 STOP 机制迫使评审者逐项分类 breaking/non-breaking，而叙述性分析很容易跳过这一步直接给建议。
发现 3：与同类技能横向对比¶
| 技能 | 基线质量 | Delta | S2 等价场景质量 |
|---|---|---|---|
| mysql-migration | 52% | +48 pp | — |
| pg-migration | 87% | +13 pp | — |
| mongo-migration | 87.5% | +12.5 pp | S3 异常 −15% Token |
| redis-cache-strategy | 89.6% | +10.4 pp | 无异常 |
| api-design | 85.4% | +14.6 pp | S2 最大场景差距（33.3 pp） |
api-design 是迄今场景差距最不均匀的技能，这反映了 REST API 设计知识的异质性：CRUD 基础规范已普遍训练，但公共 API 破坏性变更的结构化分析框架尚未内化。
改进建议¶
-
§8.7 Compatibility Assessment 应成为独立触发条件：当用户请求含"breaking"、"版本"、"deprecation"时，即使是 Lite 深度也应加载
compatibility-rules.md，而非仅限 Deep depth。 -
增加 webhook API golden fixture（COVERAGE.md 已记录为 Medium 优先级缺口）：webhook 是 partner API 的常见模式，目前无专用场景测试。
-
增加 S2 类场景的 golden fixture：当前 11 个 fixture 中无专门测试"多项 breaking change 同时触发 Gate 3 STOP"的场景。API-006 只测试单一 breaking change，覆盖不足。
8. 结论¶
api-design 技能评定：生产就绪，推荐优先用于公共 API 和合作方集成场景。
核心价值点： 1. Breaking Change 评估框架：Gate 3 STOP + §8.7 兼容性矩阵对公共 API 场景带来 +33.3 pp 质量提升，是已评估技能中单场景最大 ROI 2. 结构化输出可审计性：§8.1–§8.9 规范节格式使 API 变更评估结果可追溯、可审计，尤其适合需要合规记录的 partner API 场景 3. Token 效率分化明显：S1/S3 节省约 47% Token；S2 因框架开销增加 32%，但对应质量提升最大
推荐使用场景优先级： 1. 最高 ROI：公共/合作方 API 破坏性变更评估（S2 类场景） 2. 标准推荐：内部 API 全表面多缺陷审查（S1 类场景） 3. 可选使用：最小上下文场景（S3 类场景，基线已能满足，技能主要贡献结构规范性）