从研究
问题走向
可复现运行。

# 1. Clone the repository
git clone https://github.com/shuangyan123/tutorbench.git
cd tutorbench

# 2. Install dependencies
npm ci

# 3. Run the Quickstart (no API key)
npm run quickstart

• 无需 API key 即可本地运行
• 使用 tutor-eval-v0.1@0.1 中的 4 个固定案例
• 无需 Judge，无需网络连接
• 确定性检查（不产生正式分数）
• 不具备排行榜资格

这是不产生总分的开发/冒烟演示；Quickstart 不会削弱标准基准的边界。

tutorbench health \
  --http https://partner.example.com/respond \
  --suite productive-struggle-intervention-v0.1 \
  --tutor-provider partner \
  --tutor-model production \
  --prompt-version v17 \
  --output artifacts/partner-pilot

• 写出 evaluation.json、health-report.json 和 health-report.txt
• 记录 Tutor 服务提供方、模型/配置和 prompt 版本来源
• 报告 Tutor Health Score、显式覆盖、Release Gate、发现项与回归目标
• 无 Judge 的运行保持 UNRESOLVED，并标记为证据不完整

当前 13 情境套件是人工编写的合成设计产物，只覆盖部分健康维度；它不是经过验证的一般 Tutor 质量或学习结果测量。

npm run benchmark

• 当前数据集：tutor-eval-v0.2a@0.2a.6
• 标准产物中的 48 个公开案例
• 没有显式 Judge 时，需要 Judge 的标准保持未解决
• 所需证据不可用时不报告分数

标准运行不同于四案例 Quickstart；没有 Judge 配置时可能报告错误或不产生分数。

python examples/http-python-tutor/server.py

tutorbench run --http http://127.0.0.1:8000/respond --limit 3

• 输入 TutorTurnInput JSON；输出 { text, metrics? } JSON
• 默认请求超时为 30 秒
• 外部请求不会自动重试
• 产品 Tutor 证据与标准模型证据保持分离

适配器在边缘评估 Tutor 回复；仅供评估器使用的证据保留在 TutorBench 内部。

tutorbench collect --http http://127.0.0.1:8000/respond --provider <provider> --model <actual-model-id> --prompt-version product-config-v3 --provenance external --limit 3 --output artifacts/product/product.json

tutorbench collect-model --http http://127.0.0.1:9000/generate --provider <provider> --model <actual-model-id> --limit 3 --output artifacts/real-model/model.json

tutorbench evaluate --corpus artifacts/real-model/model.json

# Export the semantic and canonical packets
npm run tutor:export-execution -- -- --case fraction-misconception-001
npm run tutor:export-cases

# Validate and replay a frozen corpus
npm run tutor:corpus:validate -- -- --corpus path/to/corpus.json
npm run benchmark:corpus -- -- --corpus path/to/corpus.json

# OpenAI Judge dry-run (no network)
npm run judge:openai -- -- --dry-run

# Frozen-corpus DeepSeek Judge subset
node dist/src/cli/tutorbench.js evaluate \
  --corpus artifacts/real-model/baseline.json \
  --limit 1 \
  --judge-deepseek

• 产品 Tutor 与标准模型采集是不同路径
• TutorExecutionPacket 与 TutorGenerationSpec 标识标准请求
• OpenAI Responses 与 DeepSeek Chat Completions 是显式 Judge 路径
• 标准模型采集使用 baseline-native-default
• 受控可选生成参数：无
• 本地产物仍属初步、未校准且不公开

采集不等于发布、校准或取得排行榜资格；冻结证据可以离线检查和重放。baseline-native-default 配置不约束可选的 temperature、reasoning 和 seed 控制项，避免将不同服务提供方的原生行为误称为一致。tutor:export-cases 是 Tutor 可见的语义适配器数据包；tutor:export-execution 是用于使模型运行可比较的标准基准数据包。两者均不包含仅供评估器使用的注释。使用同一基准并不意味着每个服务提供方都提供相同的推理控制项。