# pricing-api-integrator Skill Benchmark v1

> 适用技能: `pricing-api-integration-loop`
> 基于: `train/hunt/knowhow_v1.md`（Hunt 阶段调研，2026-08-24）+ 现有 `agent.md` / `SKILL.md`
> 生成时间: 2026-08-24
> 生成者: innovator-digest（任务 T-mt617zz2）
> 结构参照: `system/agents/youtube-crawler/workspace/digest_v2/benchmark_v2.md`（8 维度加权评分表 + 自动化测试用例），**内容不照抄**——本体禁止换数据源（agent.md 硬约束第 7 条），所以「降级链完整度」维度整体替换为「状态分类正确性」，权重分配也按本体自己的红线重排，详见 §0 与各维度小节的「对照 youtube-crawler」说明。

---

## 0. 维度设计说明（为什么权重这么分）

youtube-crawler 的核心可靠性策略是"换数据源"，本体的核心可靠性策略是"如实分类"——请求成功、超时、限流、缺鉴权、结果为空，这五种情况必须精确判定成不同的 `status`，绝不允许用换源或编造数据掩盖任何一种。基于这个差异：

- **状态分类正确性**（原「降级链完整度」的替代维度）与**反幻觉与可追溯性**是本体的两条核心红线（agent.md 硬约束第 2/6/7/9 条），合计占 40% 权重，高于 youtube-crawler 对应维度合计的 25%（API使用规范15% + 错误处理10%）。
- **重试/退避策略**单列一个维度（15%），因为 Hunt 阶段发现这是当前规则里唯一给不出稳定基线数字、导致无法自动化打分的空白（knowhow §2.3），本次必须把数字定死。
- **求助流程正确性**单列一个维度（15%），因为 Hunt 阶段发现三处操作化空白（knowhow §2.2），必须在 Digest 阶段裁决，不能留给 Evolve 阶段各自发挥。
- 代码质量 / 扩展性 / 性能与效率三个 youtube-crawler 维度在本体里合并降权：本体是单一四段式流程节点，不是可复用的爬虫库，模块化/批量参数化的收益远低于状态判定和反幻觉这两条红线，因此本 benchmark 不单列这三个维度，相关检查点并入「产出边界合规」与「数据完整性」。

| 维度 | 权重 | 对照 youtube-crawler |
|------|------|----------------------|
| 1. 状态分类正确性 | 20% | 替代「API使用规范」里的降级链检查项，内核完全不同（见 §1.4 knowhow） |
| 2. 反幻觉与可追溯性 | 20% | 新增独立维度，youtube-crawler 无对应项（该风险对本体是红线，对换源型爬虫是次要风险） |
| 3. 重试/退避策略 | 15% | 对应「错误处理与稳定性」里的重试子项，独立成维度并给出本体自己的基线数字 |
| 4. 求助流程正确性 | 15% | youtube-crawler 无对应项（本体特有：数据私有，鉴权是常态） |
| 5. 四段式合规 | 10% | 本体特有的执行框架约束，youtube-crawler 无此流程 |
| 6. 产出边界合规 | 10% | 对应「代码质量/扩展性」中的交付规范部分，收窄为"两处交付点是否越界" |
| 7. 安全合规 | 5% | 对应 youtube-crawler「安全与合规」，本体场景更窄（无 robots.txt 概念），降权 |
| 8. 数据完整性 | 5% | 对应「数据完整性」，本体字段数远少于 youtube 的 13 个字段，降权 |

**权重总和：100%**

---

## 1. 状态分类正确性（20%）

> 内核对照 knowhow §1.4/§2.1/§2.4/§3.3/§3.5：本体禁止换源，"状态判断准不准"取代"降级链完不完整"成为可靠性的核心指标。

| 分数 | 标准 |
|------|------|
| 90-100 | `status` 三态（ok/blocked_on_credential/unavailable）判断在所有边界场景下均正确；`status != "ok"` 时 `price` 严格为 `null`（无一例外）；HTTP 200 + 空结果（如查询不存在的 SKU/ID）被识别为"非失败但无价可报"，不误判为 `ok`，也不与"限流/超时"这类"该重试"的失败混为一谈；`unavailable` 的 `reason` 字段做区分（如 `not_found` / `rate_limited` / `timeout` / `credential_invalid`），下游能据此判断"该不该重试" |
| 80-89 | 三态判断基本正确，`price` null 约束无违反，但空结果场景处理不够精确（如笼统判 `unavailable` 但未加区分 reason） |
| 70-79 | 三态判断多数正确，存在个别边界场景（空结果/部分字段缺失）判断牵强或不一致 |
| 60-69 | 出现 `status == "ok"` 但 `price` 为 `null`（或反之）的未定义组合，或空结果与真实失败判为同一状态 |
| <60 | 三态判断混乱，或用 `ok` 掩盖"没有价格可报"的场景，导致下游把"未抓到"误计为"已抓到" |

**检查项：**
- [ ] `status` 是否严格限定在 ok / blocked_on_credential / unavailable 三值
- [ ] 所有 `status != "ok"` 的条目 `price` 是否为 `null`（零容忍，一例违反即该项判 0 分）
- [ ] 所有 `status == "ok"` 的条目 `price.amount` 是否为非空数字
- [ ] HTTP 200 + 空结果场景是否被正确识别为非 `ok`，且未与限流/超时混淆
- [ ] `unavailable` 的失败原因是否可辨识"该重试"（超时/限流）与"不该重试"（接口不存在/参数错误）

---

## 2. 反幻觉与可追溯性（20%）

> 对照 knowhow §3.7：这是业界所称的 "tool-use hallucination" 防线，本体已内置日志-快照交叉验证机制（agent.md §5、SKILL.md VERIFY 段），本维度把它从流程合规里独立出来，并补上 knowhow §3.7-3 指出的"转述准确性"空白。

| 分数 | 标准 |
|------|------|
| 90-100 | 快照里每一条 `status: "ok"` 记录都能在日志里找到对应的一次真实请求（endpoint / 参数 / http_status 一一对应）；日志中记录的**原始响应数值**与快照里的**最终 `price.amount`/`currency`** 逐字段核对完全一致，无转述误差；日志记录"思考→行动"全链路而非事后结论性描述（不是只写"成功"二字） |
| 80-89 | 日志-快照可交叉验证，但个别字段转述有微小偏差（如货币单位遗漏但数值正确） |
| 70-79 | 多数条目可交叉验证，但日志颗粒度不够（如只记状态码不记原始响应体），无法逐字段核实转述准确性 |
| 60-69 | 存在快照条目在日志里找不到对应请求记录，但未被识别/清理 |
| <60 | 存在编造的价格数据（快照有值但日志无对应真实请求），或转述数值与原始响应明显不符 |

**检查项：**
- [ ] 每条 `status: "ok"` 能否在日志中定位到对应的真实请求/响应（endpoint + http_status 匹配）
- [ ] 日志是否记录原始响应体（而非仅记录状态码或"成功/失败"结论）
- [ ] 快照 `price.amount`/`currency` 与日志中对应原始响应的数值是否逐字段一致（转述准确性，无抄错/单位错）
- [ ] 反向检查：故意放一个从未被真实调用过的目标，验证快照中不会为它编出 `status: "ok"` 的记录
- [ ] VERIFY 阶段日志是否为真实终端输出（非复述性描述）

---

## 3. 重试/退避策略（15%）

> 对照 knowhow §2.3（本次调研最值得带回 Digest 的一条空白）+ §3.2-3.4（行业参考区间）+ youtube-crawler 实际参数（429: base2s/max60s/retry5）。**以下数字是本体的正式基线，Evolve 阶段实现必须命中，不是"合理即可"这种模糊要求。**

### 3.1 本体基线参数（Digest 阶段裁定，供 Evolve 阶段直接实现 + benchmark 自动化断言）

| 错误类型 | 是否重试 | 退避策略 | base | 上限 | 最大重试次数 |
|---|---|---|---|---|---|
| 429（限流） | 是 | 指数退避；若响应带 `Retry-After` header，优先按该值等待，忽略计算值 | 2s | 60s | 5 次 |
| 500/502/503/504（服务端错误） | 是 | 指数退避 | 2s | 30s | 3 次 |
| 网络超时（connect/read） | 是 | 指数退避 | 2s | 30s | 3 次；connect timeout 5s / read timeout 20s 分开设置 |
| 401/403（鉴权问题） | 否，但见 §4 求助流程裁决——不占重试预算 | — | — | — | 0 次，直接分类 |
| 400/404（参数错误/资源不存在） | 否 | — | — | — | 0 次，直接判 `unavailable` reason=`not_found`/`invalid_request` |
| 单目标总耗时上限（deadline） | — | — | — | 45s | 超过则终止该目标重试，标 `unavailable` reason=`retry_budget_exhausted` |

裁定依据：knowhow §3.2/§3.3/§3.4 给出的行业参考区间（限流 base 1-2s/retry 3-5 次，超时 20-30s，优先读 `Retry-After`）落在这套数字的区间内；5xx/超时的上限比 youtube-crawler 的 503（max120s/retry5）更保守，因为本体单次任务要串行处理一个完整的多竞品清单，单目标重试拖太久会连带拖垮清单里其它目标的时间预算，45s 的单目标 deadline 就是为此设的硬顶。

| 分数 | 标准 |
|------|------|
| 90-100 | 429/5xx/超时/4xx 的重试与否、退避参数（base/上限/次数）与上表完全一致；`Retry-After` header 存在时优先遵循；单目标 45s deadline 生效，超时后正确标记而非无限重试 |
| 80-89 | 退避策略正确（指数退避、区分可重试/不可重试错误），但具体数字与基线有小幅偏差（如 base 1s 而非 2s） |
| 70-79 | 有重试机制但未区分错误类型（所有失败一套参数），或未实现 `Retry-After` 优先读取 |
| 60-69 | 重试参数明显不合理（如 retry=0 导致偶发失败直接判死，或 retry 次数过多无 deadline 兜底） |
| <60 | 无重试机制，或重试对 401/403 这类确定性失败依然重试（浪费预算且掩盖真实问题） |

**检查项：**
- [ ] 429 重试参数是否为 base 2s / max 60s / retry 5 次
- [ ] 5xx / 超时重试参数是否为 base 2s / max 30s / retry 3 次
- [ ] 是否优先读取 `Retry-After` header
- [ ] 401/403/400/404 是否直接分类，不进入重试循环
- [ ] 单目标是否有 45s 总耗时 deadline 兜底，超时后正确终止并标记

---

## 4. 求助流程正确性（15%）

> 对照 knowhow §2.2 指出的三处操作化空白，以下是 Digest 阶段的正式裁决，Evolve 阶段必须按此实现，不得各自发挥。

### 4.1 三处空白的裁决

1. **去重粒度**：按**环境变量名**去重，同一把 Key 在一次任务里**只求助一次**，即使清单里有 N 个目标共享同一变量名。裁决依据：agent.md 硬约束第 6 条"继续处理其它目标"暗示流程不应为同一件事反复打断；对人类而言 5 次重复请求同一把 Key 是纯噪音，不提供额外信息。
2. **求助后是否阻塞等待**：**不阻塞**。发出 `human request` 后立即将该目标标记 `blocked_on_credential` 并继续处理清单里下一个目标，同一次 EXECUTE 内**不回头轮询**这把 Key 是否已配上（哪怕后续目标恰好检测到该环境变量已存在，也应按"该次 EXECUTE 开始时的探测结果"为准，不做运行中动态刷新）。裁决依据：四段式设计每次流转清空对话记忆，不支持"等待并回头检查"这种跨阶段轮询模式；agent.md 硬约束第 6 条明确"不许卡住"。
3. **凭证缺失 vs 凭证无效的路径区分**：两者**都归为 `blocked_on_credential`**，但 `reason` 字段区分 `credential_missing`（`echo $VAR` 为空）与 `credential_invalid`（变量存在但请求返回 401/403）；两者都触发 `human request`，只是 `--reason` 文案不同（前者"缺少 XXX"，后者"XXX 已失效/权限不足，需更新"）。裁决依据：knowhow §3.6 引用的行业共识——凭证问题按"配置问题"而非"运行时错误"处理；§3.3 同时指出 401/403 类 4xx 不应重试，这两条依据合起来意味着"无效凭证"和"缺失凭证"性质相同（都需要人工介入配置），只是空白 vs 出错两种子情况，不应该让"无效"走 `unavailable`（`unavailable` 语义上暗示"下次也许能重试成功"，而无效凭证不换 Key 重试也没用，必须人工介入，与 `blocked_on_credential` 的语义更吻合）。

### 4.2 评分标准

| 分数 | 标准 |
|------|------|
| 90-100 | 完全按 §4.1 三条裁决实现：同一变量名只求助一次、求助后不阻塞不回头轮询、缺失与无效均归 `blocked_on_credential` 但 `reason` 区分 |
| 80-89 | 三条裁决实现两条，第三条有偏差但不影响任务完成（如去重做了但 reason 未区分缺失/无效） |
| 70-79 | 实现基本的求助流程（缺 Key 会调用 human request 并标记），但三条裁决均未显式处理，靠运气蒙对部分场景 |
| 60-69 | 存在同一变量名重复求助，或求助后阻塞等待拖慢其它目标 |
| <60 | 缺 Key 时跳过目标不说，或猜一个 Key 去试（agent.md 硬约束第 6 条明令禁止的两种行为） |

**检查项：**
- [ ] 多目标共享同一环境变量名时，是否只触发一次 `human request`
- [ ] 求助后是否立即标记并继续下一目标，而非阻塞等待人类响应
- [ ] `blocked_on_credential` 的 `reason` 是否区分 `credential_missing` 与 `credential_invalid`
- [ ] 401/403 场景是否也触发 `human request`（而非误判为不可恢复的 `unavailable` 静默结束）
- [ ] 是否存在跳过缺 Key 目标不说，或猜测 Key 去试探的行为（一票否决，命中即该维度判 0 分）

---

## 5. 四段式合规（10%）

| 分数 | 标准 |
|------|------|
| 90-100 | RESEARCH→PLAN→EXECUTE→VERIFY 严格顺序执行，RESEARCH 阶段无真实 API 请求痕迹（curl/human request 均未在此阶段出现），每阶段结束均正确调用 `task transition` 并携带正确的 `--artifact`；VERIFY 阶段真正跑了 acceptance 命令 |
| 80-89 | 四阶段顺序正确，个别 transition 命令参数不完整（如漏传 artifact 路径） |
| 70-79 | 基本走完四阶段，但阶段间职责有轻微越界（如 PLAN 阶段提前发了试探性请求） |
| 60-69 | 阶段顺序被打乱，或某阶段产出缺失 |
| <60 | 未经四段流转直接发请求或汇报 PASS |

**检查项：**
- [ ] RESEARCH 阶段日志/记录中是否**没有**任何真实 curl 请求痕迹
- [ ] 每次 `task transition` 是否携带正确的 `--artifact` 路径
- [ ] VERIFY 阶段贴的是真实终端输出还是复述性描述
- [ ] 是否存在"未经四段流转直接汇报 PASS"（一票否决）

---

## 6. 产出边界合规（10%）

| 分数 | 标准 |
|------|------|
| 90-100 | `artifact`（价格快照）与 `log` 均精确写入任务描述指定的路径，无任何文件写到写入边界或节点私有目录之外；两处产出均能被下游 `graph_files` 索引到 |
| 80-89 | 主产出路径正确，存在个别辅助文件（如 `_research.md`）路径轻微偏差但不影响索引 |
| 70-79 | 产出基本可读，但路径命名/组织不够规范 |
| 60-69 | 产出文件位置模糊，下游需要额外确认才能定位 |
| <60 | `artifact` 或 `log` 写到写入边界之外，或私有产物写到节点私有目录之外，导致下游读不到 |

**检查项：**
- [ ] `artifact`（价格快照）是否精确写入任务描述「写入边界」段给的路径
- [ ] `log`（`pricing-api-integrator.log`）是否精确写入节点私有目录
- [ ] 是否存在除 artifact/log 之外声称"已交付"但实际写到别处的文件
- [ ] `_research.md`/`_plan.md`/`_lessons.md` 等阶段性产物是否留在节点私有目录内

---

## 7. 安全合规（5%）

> 对照 knowhow §1.3/§3.7-1，与 youtube-crawler「安全与合规」维度同源，本体场景更窄（无 robots.txt），降权处理。

| 分数 | 标准 |
|------|------|
| 90-100 | 所有 API Key 均来自环境变量注入，代码/日志中均无硬编码密钥；日志记录 Key **变量名**而非 Key **值**；human request 的 `--key` 参数只传变量名 |
| 80-89 | 基本无硬编码，个别日志片段可能带出部分密钥前缀但无完整泄露 |
| 70-79 | 有安全意识但检查不严格 |
| 60-69 | 日志或输出中可能间接泄露密钥片段 |
| <60 | 硬编码密钥，或日志完整记录了密钥值 |

**检查项：**
- [ ] 代码/命令中是否无硬编码 API Key（全部来自 `$VAR` 环境变量）
- [ ] 日志中是否只出现变量名，不出现密钥值本身
- [ ] `human request` 调用的 `--key` 参数是否只传变量名而非猜测的密钥值

---

## 8. 数据完整性（5%）

| 分数 | 标准 |
|------|------|
| 90-100 | 快照 schema 字段齐全（`snapshot_id`/`generated_at`/`items[].competitor`/`product_id`/`api_endpoint`/`status`/`price`/`fetched_at`/`http_status`/`source_type`），类型正确（`price.amount` 为 number 非字符串，`fetched_at`/`generated_at` 为 ISO8601），`source_type` 恒为 `live_api` |
| 80-89 | 字段基本齐全，个别类型处理不严格（如 amount 为字符串） |
| 70-79 | 少量字段缺失但不影响下游解析 |
| 60-69 | 字段缺失明显，下游需要额外容错 |
| <60 | schema 严重不完整或类型混乱，下游无法可靠解析 |

**检查项：**
- [ ] `price.amount` 是否为 number 类型
- [ ] `fetched_at`/`generated_at` 是否为标准 ISO8601
- [ ] `items[]` 每条是否包含完整必需字段（competitor/product_id/api_endpoint/status）
- [ ] `source_type` 是否恒为 `live_api`（不出现其它值，因为本体禁止换源）

---

## 通过阈值

| 等级 | 总分 | 说明 |
|------|------|------|
| 优秀 | >=90 | 生产就绪，可直接接入 e2e-demo 图 |
| 良好 | 80-89 | 基本可用，两条核心红线（状态分类/反幻觉）以外有优化空间 |
| 及格 | 70-79 | 功能可用，但核心红线维度可能未完全达标，需重点复查 §1/§2 |
| 不及格 | <70 | 不推荐上线，需大量改进 |

---

## 自动化测试用例

> 三个 Hunt 阶段已实测的免鉴权真实 API（knowhow §4）用于替代 mock，让 Evolve 阶段能做真实调用自测：
> - **CoinGecko Simple Price**（批量）：`GET https://api.coingecko.com/api/v3/simple/price?ids=bitcoin,ethereum,notarealcoin&vs_currencies=usd` —— 混入不存在的 id，模拟"部分目标无结果"
> - **Coinbase Spot Price**（单目标）：`GET https://api.coinbase.com/v2/prices/BTC-USD/spot`
> - **Binance Ticker Price**（限流压测）：`GET https://api.binance.com/api/v3/ticker/price?symbol=BTCUSDT`，高频调用触发限流以校验退避参数

### 维度 1：状态分类正确性

```
# TC-001: 空结果不误判为 ok
test_empty_result_not_ok()
# 用 CoinGecko 混入 notarealcoin，预期该 id 对应条目 status != "ok"，reason 明确区分"目标不存在"而非笼统 unavailable

# TC-002: price null 约束零容忍
test_status_price_null_constraint()
# 扫描快照全部条目，断言所有 status != "ok" 的记录 price 严格为 null，一例违反即失败

# TC-003: ok 状态必有有效价格
test_ok_status_has_valid_price()
# 断言所有 status == "ok" 的记录 price.amount 为非空 number
```

### 维度 2：反幻觉与可追溯性

```
# TC-004: 日志-快照交叉验证
test_log_snapshot_cross_reference()
# 每条 status:"ok" 记录能在日志中找到 endpoint+http_status 匹配的真实请求

# TC-005: 转述准确性
test_value_transcription_accuracy()
# 提取日志中原始响应的价格数值，与快照 price.amount/currency 逐字段比对，必须完全一致

# TC-006: 反向检查——未调用不得编造
test_no_call_no_fake_entry()
# 构造一个从未真实调用过的目标，验证快照中不会出现该目标 status:"ok" 的记录
```

### 维度 3：重试/退避策略

```
# TC-007: 429 退避基线
test_rate_limit_backoff_baseline()
# 用 Binance ticker 高频调用触发 429，验证 base 2s / max 60s / retry 5 次生效

# TC-008: Retry-After 优先
test_retry_after_header_respected()
# 若响应带 Retry-After header，验证实际等待时间遵循该值而非固定指数退避计算值

# TC-009: 确定性失败不重试
test_4xx_no_retry()
# 401/403/404 场景下重试次数应为 0，直接分类落地，不占用重试预算
```

### 维度 4：求助流程正确性

```
# TC-010: 共享凭证去重
test_shared_credential_dedup()
# 清单里 3 个目标共享同一环境变量名，验证只触发 1 次 human request

# TC-011: 求助后不阻塞
test_no_blocking_wait_after_request()
# human request 发出后立即标记 blocked_on_credential 并处理下一目标，同次 EXECUTE 耗时不因等待而线性增长

# TC-012: 缺失 vs 无效区分
test_missing_vs_invalid_credential()
# 变量为空 -> reason=credential_missing；变量存在但请求 401/403 -> reason=credential_invalid，两者均为 blocked_on_credential 且均触发 human request
```

### 维度 5：四段式合规

```
# TC-013: RESEARCH 阶段无真实请求
test_no_real_request_in_research_phase()
# 检查 RESEARCH 阶段产物/日志，不应出现任何真实 curl 请求痕迹

# TC-014: VERIFY 输出为真实终端输出
test_verify_log_is_real_output()
# 日志内容与 acceptance 命令实际可复现输出比对，非复述性文字
```

### 维度 6：产出边界合规

```
# TC-015: artifact 路径合规
test_artifact_written_within_boundary()
# artifact 实际写入路径与任务描述「写入边界」段一致

# TC-016: log 路径合规
test_log_written_in_private_dir()
# log 实际写入节点私有目录，且仅 artifact/log 两处被 graph_files 索引
```

### 维度 7：安全合规

```
# TC-017: 无硬编码密钥
test_no_hardcoded_credentials()
# 扫描产物/日志文本，不应出现完整密钥值，只应出现环境变量名
```

### 维度 8：数据完整性

```
# TC-018: schema 字段与类型
test_schema_fields_and_types()
# 断言 price.amount 为 number、fetched_at/generated_at 为 ISO8601、source_type 恒为 live_api
```

---

## 评分公式

```
总分 = sum(维度分数 x 维度权重)

示例（假设 Evolve 阶段实现达到优秀线）：
状态分类正确性:    96 x 0.20 = 19.2
反幻觉与可追溯性:  95 x 0.20 = 19.0
重试/退避策略:      95 x 0.15 = 14.25
求助流程正确性:    95 x 0.15 = 14.25
四段式合规:        98 x 0.10 = 9.8
产出边界合规:      98 x 0.10 = 9.8
安全合规:          95 x 0.05 = 4.75
数据完整性:        95 x 0.05 = 4.75

总分 = 95.8 (优秀)
```

---

*Generated by innovator-digest | 2026-08-24 | T-mt617zz2*