benchmark_v1.md
21.8 KB
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（或反之）的未定义组合，或空结果与真实失败判为同一状态 |
三态判断混乱，或用 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 | 存在快照条目在日志里找不到对应请求记录，但未被识别/清理 |
| 存在编造的价格数据（快照有值但日志无对应真实请求），或转述数值与原始响应明显不符 |
检查项：
- [ ] 每条
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 兜底） |
| 无重试机制，或重试对 401/403 这类确定性失败依然重试（浪费预算且掩盖真实问题） |
检查项：
- [ ] 429 重试参数是否为 base 2s / max 60s / retry 5 次
- [ ] 5xx / 超时重试参数是否为 base 2s / max 30s / retry 3 次
- [ ] 是否优先读取
Retry-Afterheader - [ ] 401/403/400/404 是否直接分类，不进入重试循环
- [ ] 单目标是否有 45s 总耗时 deadline 兜底，超时后正确终止并标记
4. 求助流程正确性（15%）
对照 knowhow §2.2 指出的三处操作化空白，以下是 Digest 阶段的正式裁决，Evolve 阶段必须按此实现，不得各自发挥。
4.1 三处空白的裁决
- 去重粒度：按环境变量名去重，同一把 Key 在一次任务里只求助一次，即使清单里有 N 个目标共享同一变量名。裁决依据：agent.md 硬约束第 6 条"继续处理其它目标"暗示流程不应为同一件事反复打断；对人类而言 5 次重复请求同一把 Key 是纯噪音，不提供额外信息。
- 求助后是否阻塞等待：不阻塞。发出
human request后立即将该目标标记blocked_on_credential并继续处理清单里下一个目标，同一次 EXECUTE 内不回头轮询这把 Key 是否已配上（哪怕后续目标恰好检测到该环境变量已存在，也应按"该次 EXECUTE 开始时的探测结果"为准，不做运行中动态刷新）。裁决依据：四段式设计每次流转清空对话记忆，不支持"等待并回头检查"这种跨阶段轮询模式；agent.md 硬约束第 6 条明确"不许卡住"。 - 凭证缺失 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 | 存在同一变量名重复求助，或求助后阻塞等待拖慢其它目标 |
| 缺 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 | 阶段顺序被打乱，或某阶段产出缺失 |
| 未经四段流转直接发请求或汇报 PASS |
检查项：
- [ ] RESEARCH 阶段日志/记录中是否没有任何真实 curl 请求痕迹
- [ ] 每次
task transition是否携带正确的--artifact路径 - [ ] VERIFY 阶段贴的是真实终端输出还是复述性描述
- [ ] 是否存在"未经四段流转直接汇报 PASS"（一票否决）
6. 产出边界合规（10%）
| 分数 | 标准 |
|---|---|
| 90-100 | artifact（价格快照）与 log 均精确写入任务描述指定的路径，无任何文件写到写入边界或节点私有目录之外；两处产出均能被下游 graph_files 索引到 |
| 80-89 | 主产出路径正确，存在个别辅助文件（如 _research.md）路径轻微偏差但不影响索引 |
| 70-79 | 产出基本可读，但路径命名/组织不够规范 |
| 60-69 | 产出文件位置模糊，下游需要额外确认才能定位 |
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 | 日志或输出中可能间接泄露密钥片段 |
| 硬编码密钥，或日志完整记录了密钥值 |
检查项：
- [ ] 代码/命令中是否无硬编码 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 | 字段缺失明显，下游需要额外容错 |
| 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 |
| 不及格 | 不推荐上线，需大量改进 |
自动化测试用例
三个 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