mcpField
L
ln-840-benchmark-compare

ln-840-benchmark-compare

github.com/levnikolaevich测试与质量584149 次安装2 天前更新
代码仓库

关于 ln-840-benchmark-compare

面向 Claude Code 的 A/B 基准测试技能，用于比较内置工具与 hex-line。它按预期差异验证场景结果，并报告激活、正确性、耗时、成本和令牌指标。

主要功能

  1. 01按场景运行 A/B 测试
  2. 02基于差异验证正确性
  3. 03为每次运行隔离工作树
  4. 04统计激活与使用指标
  5. 05生成 Markdown 和机器可读报告

适用场景

  1. 01比较使用与不使用 hex-line 的 Claude Code
  2. 02检查基准场景是否符合预期差异
  3. 03查看运行时间、成本和令牌变化

MCP 相关

该技能将配置 hex-line MCP 服务的 Claude 会话与仅使用内置工具的会话进行基准比较。若第三方 MCP 兼容会话能生成所需日志和差异产物，也可纳入比较。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/levnikolaevich/claude-code-skills --skill ln-840-benchmark-compare

安装后在 Claude Code 中输入/ln-840-benchmark-compare确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
benchmark_worker_runtime_contract.md
coordinator_summary_contract.md
expectations.json
goals.md
mcp-bench.json
monitor_integration_pattern.md
references/scripts/benchmark-worker-runtime/
cli.mjs
references/scripts/benchmark-worker-runtime/lib/
guards.mjs
phases.mjs
store.mjs
references/scripts/coordinator-runtime/lib/
artifacts.mjs
cli-helpers.mjs
core.mjs
loop-health.mjs
runtime-constants.mjs
schemas.mjs
validate.mjs
worker-guards.mjs
worker-runtime.mjs
scripts/
extract-scenarios.mjs
parse-results.mjs
run-benchmark.sh

详细介绍

**路径：**文件路径（references/）相对于此技能目录。

基准测试对比

**类型：**L3 Worker **类别：**8XX Optimization -> 840 Benchmark

在 Claude Code 中运行一组干净的 A/B 基准测试：一个会话仅使用内置工具，另一个使用 hex-line。基准测试基于场景、通过差异验证、由清单驱动并以运行时为依据。它会衡量激活情况、正确性、耗时、成本和令牌数。当前运行器有意限定为此内部 A/B 测试。单凭它本身无法证明其表现优于所有外部替代方案。

输入 / 输出

方向内容
输入包含 mcp/hex-line-mcp/ 的仓库检出，可选的 references/goals.md、可选的 references/expectations.json
输出对比报告，位于 plugins/optimization-suite/skills/ln-840-benchmark-compare/results/{date}-comparison.md，以及机器可读的基准测试摘要产物

先决条件

  • claude --version 执行成功
  • git 执行成功
  • mcp/hex-line-mcp/server.mjs 存在
  • mcp/hex-line-mcp/hook.mjs 存在
  • plugins/optimization-suite/skills/ln-840-benchmark-compare/references/goals.md 存在
  • plugins/optimization-suite/skills/ln-840-benchmark-compare/references/expectations.json 存在
  • plugins/optimization-suite/skills/ln-840-benchmark-compare/references/mcp-bench.json 存在

快速运行

bash plugins/optimization-suite/skills/ln-840-benchmark-compare/scripts/run-benchmark.sh \
  [plugins/optimization-suite/skills/ln-840-benchmark-compare/references/goals.md] \
  [plugins/optimization-suite/skills/ln-840-benchmark-compare/references/expectations.json]

可选的额外会话配置：

EXTRA_SESSION_ID=other-mcp \
EXTRA_SESSION_LABEL="Other MCP" \
EXTRA_MCP_CONFIG=/abs/path/to/other-mcp.json \
EXTRA_SETTINGS='{"disableAllHooks":true}' \
bash plugins/optimization-suite/skills/ln-840-benchmark-compare/scripts/run-benchmark.sh
监控集成（Claude Code 2.1.98+）

**必须阅读：**加载 references/monitor_integration_pattern.md

流式查看基准测试进度： Monitor(command="bash plugins/optimization-suite/skills/ln-840-benchmark-compare/scripts/run-benchmark.sh 2>&1 | grep --line-buffered -E 'scenario|PASS|FAIL|error|session'", timeout_ms=3600000, description="benchmark run")

回退方案：Bash(run_in_background=true)。

运行器负责：

  • 语法预检
  • SessionStart 预检
  • 从 goals.md 提取场景
  • 为每个场景/会话创建隔离的工作树
  • 生成每个场景的差异
  • 生成最终对比报告

当前范围：

  • 内置 Claude 会话
  • Claude 加 hex-line
  • 通过 EXTRA_SESSION_* 环境变量配置的可选第三种兼容 Claude 的会话配置

外部基准说明：

  • 使用相同的 goals.md 和 expectations.json
  • 不要为了适配外部工具而重写场景
  • 不要仅凭内部 A/B 测试就声称其为“顶级工具”
  • 只有在可选的第三种会话配置能够生成相同形状的 stream-json 日志和差异产物时，才可使用

工作流

第 1 阶段：定义规范测试套件

使用此技能维护的唯一规范测试套件：

  • plugins/optimization-suite/skills/ln-840-benchmark-compare/references/goals.md
  • plugins/optimization-suite/skills/ln-840-benchmark-compare/references/expectations.json

规则：

  • 测试套件必须均衡涵盖常见工程场景。
  • 不要将测试套件设计成偏向 hex-line。
  • goals.md 中的每个场景都必须在 expectations.json 中有对应条目。
  • expectations.json 是判断正确性的唯一依据。
  • 今后进行任何外部基准测试时，都必须原样复用这对文件。

每个场景支持的预期字段：

字段含义
id用于结果文件名的场景标识符
expectedChangedFiles必须发生更改的文件
forbiddenChangedFiles不得发生更改的文件
requiredDiffPatterns已保存的差异中必须匹配的正则表达式
forbiddenDiffPatterns差异中不得出现的正则表达式
requiredResultPatterns最终助手结果文本中必须匹配的正则表达式
requiredCommands必须匹配至少一条 Bash 命令的正则表达式
exactChangedFiles如果为 true，则不允许更改任何额外文件
阶段 2：预检

运行器必须通过：

  • node --check server.mjs
  • node --check hook.mjs
  • node --check extract-scenarios.mjs
  • node --check parse-results.mjs
  • hook.mjs 中的 SessionStart 冒烟检查

如果预检失败，基准测试无效，必须在运行场景前停止。

阶段 3：逐个场景执行

对于 goals.md 中的每个 ## 场景：

  1. 生成独立的提示词文件
  2. 从同一提交创建两个干净的工作树
  3. 运行内置 Claude 会话
  4. 运行 hex-line Claude 会话
  5. 保存 .jsonl 日志和 .diff.txt 产物
  6. 移除两个工作树

内置会话：

  • 不使用 MCP
  • 禁用钩子

Hex-line 会话：

  • 使用指向 server.mjs 的已解析 MCP 配置
  • outputStyle: "hex-line"
  • 通过 hook.mjs 使用 PreToolUse 钩子
阶段 4：解析结果

parse-results.mjs 会评估每个场景在两个会话中的结果。

场景通过条件：

  • 运行有效
  • 会话成功完成
  • 变更的文件符合预期
  • diff 模式符合预期
  • 结果文本模式符合预期
  • 确实执行了所需命令
阶段 5：阅读报告

最终报告包含以下部分：

  • 场景结果
  • 激活情况
  • 耗时
  • 成本
  • Token
  • 工具总数
  • 有效性

解读规则：

  • invalid run 表示设置／采用失败，而非产品性能问题
  • 场景 FAIL 表示未满足正确性契约
  • 激活情况是 hex-line 产品质量的一部分，并非外部噪声
  • 此报告是内部 A/B 评估的必要条件，但不足以支持关于最佳替代方案的主张

报告约定

plugins/optimization-suite/skills/ln-840-benchmark-compare/results/{date}-comparison.md 必须回答：

  • 每个场景是否正确完成？
  • hex-line 是否顺利激活，且未出现发现偏差？
  • 墙钟时间、API 时间、成本、输出 Token 和工具调用总数有哪些变化？
  • 本次运行是否有效？

如果场景正确性未得到确认，不要仅依据原始耗时／成本进行判断。

外部基准政策

  • 此技能负责维护规范测试套件，而非通用排行榜。
  • 如果维护者将 hex-line 与外部替代方案进行比较，必须沿用同一份 goals.md、expectations.json 和基于 diff 的评估规则。
  • 外部运行可以使用不同的测试框架，但必须保留相同的任务文本、起始提交和正确性契约。
  • 如果某个外部工具无法满足契约格式，应将其记录为测试框架限制，而不是改写测试套件以适应该工具。
  • 如果报告仅涵盖内置 Claude 与 hex-line 的比较，必须明确说明。

运行时约定

必须阅读： 加载 references/benchmark_worker_runtime_contract.md、references/coordinator_summary_contract.md

运行时 CLI：

node references/scripts/benchmark-worker-runtime/cli.mjs start --skill ln-840-benchmark-compare --identifier suite-default --manifest-file <file>
node references/scripts/benchmark-worker-runtime/cli.mjs checkpoint --skill ln-840-benchmark-compare --identifier suite-default --phase PHASE_0_CONFIG --payload '{...}'
node references/scripts/benchmark-worker-runtime/cli.mjs record-summary --skill ln-840-benchmark-compare --identifier suite-default --payload '{...}'
node references/scripts/benchmark-worker-runtime/cli.mjs complete --skill ln-840-benchmark-compare --identifier suite-default

必需的状态字段：

  • report_ready
  • summary_recorded
  • final_result
  • self_check_passed

领域检查点：

  • PHASE_0_CONFIG
  • PHASE_1_PREFLIGHT
  • PHASE_2_LOAD_SUITE
  • PHASE_3_RUN_SCENARIOS
  • PHASE_4_PARSE_RESULTS
  • PHASE_5_WRITE_REPORT
  • PHASE_6_WRITE_SUMMARY
  • PHASE_7_SELF_CHECK

保护规则：

  • 未记录当前阶段的检查点，不得进入下一阶段
  • 未记录 benchmark-worker 摘要，不得完成
  • 自检未通过，不得完成
运行时协调
  • 受管理的运行可以传入确定性的 runId 和准确的 summaryArtifactPath。
  • 支持独立运行。如果两者均未提供，运行时会创建独立运行，并为 benchmark-worker 系列写入默认的摘要产物路径。

运行时摘要产物

必须阅读： 加载 references/coordinator_summary_contract.md

写入比较报告后，输出一个 benchmark-worker 摘要信封。

托管模式：

  • 写入确切的 summaryArtifactPath

独立模式：

  • 写入 .hex-skills/runtime-artifacts/runs/{run_id}/benchmark-worker/ln-840-benchmark-compare--{identifier}.json

建议的载荷：

  • scenarios_total
  • scenarios_passed
  • scenarios_failed
  • activation_valid
  • validity_verdict
  • report_path
  • warnings
  • metrics

已知问题

问题解决方案
hex-line 运行中不存在 SessionStart预检失败并停止
Agent 在使用 hex-line 前转而使用 ToolSearch将其视为激活问题并记录在报告中
先前崩溃后工作树仍然存在添加新工作树前将其移除
缺少差异产物将场景正确性判定为失败
简单场景更适合内置功能如果这是常见场景，就将其保留在测试套件中；诚实比挑选有利案例更重要
外部比较使用了经过编辑的场景或放宽后的预期将该比较视为无效

完成定义

  • goals.md 定义了规范的平衡测试套件
  • expectations.json 完整描述了场景正确性
  • 运行器通过语法和 SessionStart 预检
  • 每个场景都从同一提交在两个干净的工作树中运行
  • 解析器根据日志和差异评估激活情况及场景正确性
  • 最终报告保存至 plugins/optimization-suite/skills/ln-840-benchmark-compare/results/
  • benchmark-worker 摘要产物已写入托管或独立运行时路径
  • 临时工作树已移除
  • 报告明确说明结果仅为内部 A/B 比较，还是包含其他外部基线

版本： 2.0.0 最后更新： 2026-03-24

评论

支持 Markdown