基准数据集方法论
Jarvis 的基准数据集不是单纯比较模型代码生成能力的排行榜。它要衡量的是一个完整编码工作台在真实工作流里的质量：模型、prompt、运行时适配器、Session OS、工具链、上下文策略和人工介入通道共同工作后的结果。
为什么先建设数据集
标题为“为什么先建设数据集”的章节在自动化评测流水线之前，先建设数据集和文档有三个原因：
- 定义要优化的产品行为：没有稳定任务和指标，流水线只能放大临时经验，不能回答“这次 prompt 或模型切换是否真的更好”。
- 让指标可复查：每个任务都要说明来源、成功条件、排除项和局限，避免把一次 demo 成功误当作稳定能力。
- 把 Session OS 纳入质量判断：Jarvis 的差异点不只是能写代码，而是能发现、复用、检查和协调多个编码会话；这些能力必须进入首批数据集。
这份方法论页面属于解释性文档。它说明为什么这么测、首批测什么、每个指标服务哪些产品决策；具体数据集和 runner 合同放在仓库 benchmarks/jarvis_eval/。当前公开 workflow 只在手动触发时运行 deterministic backend-contract smoke，不跑 live LLM。
评估对象
标题为“评估对象”的章节每个分数都应明确指向“模型 + Jarvis scaffold + 工具 + 预算 + 环境”的组合，而不是归因给裸模型。
| 层级 | 评估对象 | 典型问题 |
|---|---|---|
| 任务级 | 单个任务是否完成 | 代码是否修好、文档是否写对、输出 artifact 是否存在、测试是否通过 |
| 轨迹级 | Agent 是否走了合理路径 | 是否选对工具、是否先 inspect 再行动、是否避免无效重试、是否在阻塞时升级 |
| 会话级 | Session OS 是否让工作可被发现和接续 | find_sessions 是否找对会话、短 ref 是否解析正确、摘要和 digest 是否新鲜 |
| 平台级 | 成本、可靠性和回归风险 | 成功一次要花多少钱、是否依赖 fallback、同一任务重复运行是否稳定 |
方法论原则
标题为“方法论原则”的章节- 从产品决策反推指标：每个指标都要能指导具体决策，例如模型选择、prompt 调整、Session OS 改造或回归拦截。
- 最终状态和执行轨迹都要看：只看最后答案会漏掉错误会话操作、无效工具链、过度 fallback 和不必要的人工打断。
- 可确定的先确定，不确定的显式人工审阅：代码测试、文件状态、事件序列和 DB fixture 可自动判定；含糊需求和解释质量要保留人工 rubric。
- 首批任务覆盖现有能力和关键缺口：已有 coding-agent benchmark 可复用，但必须补上 Session OS 的发现、复用、缓存、摘要、回放和交付物路径。
- 不把生产隐私变成测试样本：生产日志只能用来归纳失败模式，数据集任务要脱敏、可复现，并避免包含私人路径、会话正文或密钥。
- 版本化维护：任务、oracle、指标和排除规则都要有版本；报告必须写清 denominator、排除项、重复次数和环境版本。
首批任务集
标题为“首批任务集”的章节首批任务按高信号路径选择，而不是按最容易自动化的路径选择。代码生成任务仍然重要，但 Jarvis 的核心风险更多出现在“找到对的会话、判断能不能接续、用对上下文、在正确时机叫人”这些工作台层行为上。
| 优先级 | 任务 | 要证明什么 |
|---|---|---|
| P0 | Harness integrity | 评测框架能区分纯成功、fallback、成本、耗时和 GO/NO-GO，避免指标本身失真 |
| P0 | Completion discipline | Agent 需要声明输出 artifact，并满足文件、测试或状态 oracle，而不是只说“已完成” |
| P0 | Session inventory | 能列出会话状态、运行时、来源、可用动作和分页边界 |
| P0 | Keyword search | 能用一个短关键词调用 find_sessions，理解它是 substring search，并检查 matched_in |
| P0 | Ref handling | 能正确使用 cc1、cx1、oc1、km1 等活会话短 ref，并在失效时回退完整 cs_ ID |
| P0 | Inspection before action | 对有风险的派发、停止、接管或回复操作，先检查会话 transcript、状态、workspace 和 interventions |
| P0 | Digest accuracy | 回答数量类问题时使用 digest 的 totals，不把当前页 page_count 当全量 |
| P0 | Reuse/control choice | 能区分继续派发活托管会话、resume 已退出原生会话、takeover 空闲外部会话和新开会话 |
| P0 | External-read-only safety | 不假设外部发现会话可写入终端、停止或中断；只按 allowed actions 行动 |
| P1 | Event replay/streaming | 能按 after_seq、limit 和 Last-Event-ID 处理事件回放，不重复也不漏判 |
| P1 | Deliverables | 优先使用交付物投影和结构化 metadata，而不是从终端 transcript 猜 artifact |
| P1 | Projection/cache awareness | 能区分 durable session row/event 与摘要、短 ref、终端 tail、运行时扫描缓存等可重建投影 |
首批指标
标题为“首批指标”的章节首批指标分成结果指标、轨迹指标、Session OS 指标和平台指标。它们可进入离线报告和回归门禁，但不同门禁可以只选择其中一部分。
| 指标 | 定义 | 测量方式 | 指导决策 |
|---|---|---|---|
task_success_rate |
任务在当前 oracle 下完成的比例 | 文件、测试、DB 状态、事件状态或人工 rubric | 判断某个模型 / prompt / runtime 是否可作为默认路径 |
pure_success_rate |
不依赖 fallback 的成功比例 | 成功结果中排除 fallback run | 判断默认 runtime 是否真的可用，而不是被兜底掩盖 |
completion_oracle_pass_rate |
输出 artifact 或最终状态满足任务规格的比例 | file_contains、focused tests、状态断言、人工 rubric |
防止“口头完成”进入回归数据 |
tool_selection_accuracy |
第一步或关键步骤是否选对工具 | trace 中的工具调用与 expected tool / chain 对比 | 调 prompt、工具描述和主会话工具暴露顺序 |
parameter_accuracy |
工具参数是否正确、最小且可执行 | 对 session id、path、q、limit、after_seq 等参数打分 | 修正工具 schema、示例和模型路由 |
trajectory_required_step_rate |
必需步骤是否出现 | 例如先 inspect_session 再 dispatch / stop / takeover |
判断 agent 是否可靠地遵守工作台操作纪律 |
session_discovery_topk_recall |
正确会话是否出现在 list/find 前 K 个候选中 | 固定 session fixture + expected session set | 优化发现排序、摘要生成和搜索入口 |
wrong_session_action_rate |
对错误会话执行写入、停止、接管或回复的比例 | trace 中 mutating action 的 session id 校验 | 决定是否收紧确认、ref 解析和高风险动作门禁 |
session_ref_resolution_accuracy |
短 ref 是否解析到正确活会话 | cc1/cx1/oc1/km1 fixture + restart/stale 场景 |
决定短 ref 展示、过期提示和 fallback 交互 |
stale_ref_recovery_rate |
短 ref 失效时是否停止并请求重新定位 | stale alias fixture + expected recovery behavior | 降低误操作风险，改善错误提示 |
session_utilization_rate |
需要会话上下文的任务中实际使用 Session OS 的比例 | trace 中 list/find/inspect/digest/replay 调用覆盖率 | 判断主会话是否真的把 Jarvis 当工作台，而不是裸聊天 |
session_reuse_rate |
应复用已有会话时选择复用的比例 | fixture 标注 expected action: dispatch/resume/takeover/new | 决定默认策略是新开会话还是继续上下文 |
reuse_lift |
复用会话相对新开会话带来的成功率、成本或耗时改善 | A/B：reuse allowed vs forced new session | 决定是否强化“找到并接续旧会话”的产品入口 |
summary_cache_fresh_rate |
摘要投影与最新事件状态一致的比例 | summary last event seq / age / semantic freshness check | 决定摘要刷新策略、失效策略和是否展示置信状态 |
prompt_cache_hit_rate |
支持缓存的运行时中 prompt/cache 被复用的比例 | provider/runtime telemetry 或可观测用量 metadata | 比较模型和上下文策略的成本效率 |
digest_total_accuracy |
数量类回答是否使用真实 totals |
固定 session count fixture + answer/rubric | 防止分页误读导致错误运营判断 |
event_replay_integrity |
回放和 stream 是否没有重复、缺失和顺序错误 | event seq fixture、after_seq、Last-Event-ID 检查 |
决定 SSE / replay 改动能否合入 |
deliverable_capture_rate |
应产生交付物的任务是否写入结构化 deliverable | deliverable projection 与 artifact metadata 校验 | 决定是否可以让主会话依赖交付物视图做验收 |
external_session_safety_rate |
外部只读会话是否没有被错误写入或中断 | allowed actions fixture + trace 检查 | 保护用户已有终端会话，降低破坏性误操作 |
blocked_escalation_latency |
发现缺权限、缺决策或无上下文后多久升级 | trace 时间戳：问题出现到 ask_human / notify_blocked |
调整 worker prompt 和超时策略 |
cost_per_success |
每个纯成功任务的平均成本 | 用量和成本 telemetry 除以 pure successes | 指导 Sonnet、Opus、GPT、Kimi 等模型的默认选择 |
产品价值映射
标题为“产品价值映射”的章节| 产品决策 | 主要看哪些指标 |
|---|---|
| 默认模型选型 | pure_success_rate、cost_per_success、blocked_escalation_latency、trajectory_required_step_rate |
| prompt 和工具描述调优 | tool_selection_accuracy、parameter_accuracy、wrong_session_action_rate、stale_ref_recovery_rate |
| Session OS 发现能力 | session_discovery_topk_recall、session_utilization_rate、digest_total_accuracy |
| 会话复用产品策略 | session_reuse_rate、reuse_lift、summary_cache_fresh_rate、prompt_cache_hit_rate |
| 高风险动作门禁 | wrong_session_action_rate、external_session_safety_rate、trajectory_required_step_rate |
| 回归检测 | task_success_rate、completion_oracle_pass_rate、event_replay_integrity、deliverable_capture_rate |
| 发布前质量判断 | pure_success_rate、fallback count、docs/build/test gate、关键 Session OS 指标 |
单条任务应记录什么
标题为“单条任务应记录什么”的章节每个数据集任务都应像一张小型 datasheet，而不是只有一段 prompt。
| 字段 | 作用 |
|---|---|
id、version、difficulty |
支持长期追踪、分层汇总和回归定位 |
product_decision |
说明这个任务影响哪个真实决策 |
setup_fixture |
固定仓库、文件、会话、事件、DB 或运行时前置状态 |
user_prompt |
Agent 实际看到的用户任务 |
allowed_tools / forbidden_actions |
明确安全边界，尤其是外部会话和 destructive action |
expected_trace |
关键工具、顺序、参数和必须出现的检查步骤 |
expected_state |
文件、测试、DB、事件、deliverable 或 UI 状态 oracle |
rubric |
自动 oracle 覆盖不了时的人工审阅标准 |
privacy_class |
标记是否可公开、是否脱敏、是否禁止进入训练或外发 |
limitations |
说明该任务不能证明什么 |
Harness 边界
标题为“Harness 边界”的章节第一版可运行 harness 采用 ports + adapters，而不是让 runner core 直接依赖 Jarvis 数据集或后端实现。
| 层 | 责任 |
|---|---|
harness/core/ |
通用 EvalTask、trace、evidence、score、runner、threshold，不 import Jarvis backend 或 v0 fixture |
| dataset adapter | 读取 v0 manifest、跑 schema/static validator、把 case/fixture 映射成通用任务 |
| environment adapter | 为每个 case 创建隔离临时 SQLite DB，并写入合成 Session OS fixture |
| tool executor adapter | 作为唯一明确边界调用真实 src.tools.* Session OS 工具模块 |
| oracle adapter | 根据 v0 rubric 检查工具调用、参数、输出事实和 forbidden action |
| report adapters | 输出 JSON、Markdown 和 GitHub step summary |
因此，MVP harness 的默认问题是：“Jarvis backend 在合成 Session OS fixture 上是否仍满足工具合同？”而不是“某个 live 模型是否会自己选对工具”。当前 shipped runner 只实现 backend-contract；agent-live / http-contract 是保留模式名，必须等真实 adapter 落地后才能运行，且不进入普通 PR CI。
如何阅读 Eval Report
标题为“如何阅读 Eval Report”的章节run_eval.py 会生成机器可读 JSON 和人类可读 Markdown；GitHub Actions 手动运行时，同一份 Markdown 也会写入 step summary。报告顶部会链接回本页、数据集卡和 harness README，因为单个报告只回答“这一次 run 的结果是什么”，不重复展开完整方法论。
| 字段 | 含义 | 阅读方式 |
|---|---|---|
Run ID |
本次运行生成报告的 UTC 时间戳 | 用来对应 artifact、日志和手动 workflow run |
Mode |
当前 runner 模式 | v0 只有 backend-contract 已实现；这不是 live LLM 评分 |
Dataset |
数据集 ID 和版本 | 对比历史结果时必须确认 dataset 版本一致 |
Thresholds |
所有配置阈值是否通过 | pass 代表本次所选 split/trial 满足门禁，不代表覆盖所有 Jarvis 能力 |
Total cases |
本次实际计入分母的 case 数 | 当前 CI smoke 是 10 个 public smoke case × 1 trial |
Case pass rate |
通过 case / 总 case | 用来判断端到端 deterministic contract 是否保持 |
Oracle pass rate |
自动 oracle 检查通过率 | 失败时优先看 case errors 和 JSON trace/evidence |
Backend tool success rate |
真实 Session OS tool adapter 调用成功率 | 用来区分 backend contract 破损和 oracle 不满足 |
Forbidden tool call rate |
命中 forbidden tool/action 的比例 | 任何非零值都说明安全边界或 trace 约束需要复查 |
解读失败报告时先看 Cases 表中的失败 case，再打开 JSON artifact 查看该 case 的 trace、evidence 和 checks。如果报告由 GitHub workflow 产生，artifact 只短期保留；需要长期比较时，把 JSON/Markdown 保存到明确的 benchmark evidence 或 release 记录中。
数据集与运行位置
标题为“数据集与运行位置”的章节数据集和 harness 源文件位于仓库中的以下路径：
- 数据集卡：
benchmarks/jarvis_eval/DATASET_CARD.md - v0 manifest：
benchmarks/jarvis_eval/v0/manifest.json - v0 cases：
benchmarks/jarvis_eval/v0/cases/ - harness core：
benchmarks/jarvis_eval/harness/core/ - Jarvis adapters：
benchmarks/jarvis_eval/harness/adapters/ - CI smoke config：
benchmarks/jarvis_eval/configs/ci.smoke.toml - local dev config：
benchmarks/jarvis_eval/configs/local.dev.toml
本地 smoke：
python3 benchmarks/jarvis_eval/scripts/validate_dataset.py benchmarks/jarvis_eval/v0/manifest.jsonpython3 benchmarks/jarvis_eval/scripts/run_eval.py \ --config benchmarks/jarvis_eval/configs/ci.smoke.tomlCI 文件是 .github/workflows/jarvis-eval.yml，使用 self-hosted jarvis-light runner，并且只通过 workflow_dispatch 手动触发。它不会在 PR 或 main push 上自动运行；手动运行会在临时 venv 中验证 public dataset、跑 focused benchmark unit tests、执行 backend-contract smoke harness、输出短期保留的 JSON/Markdown artifact，并把摘要写入 GitHub step summary。
不覆盖什么
标题为“不覆盖什么”的章节首批 Jarvis benchmark 不应声称覆盖这些能力：
- 广义软件工程能力或所有语言生态；
- 长期无人值守自治；
- 生产用户私人会话的真实成功率；
- 未经校准的 LLM judge 结论；
- 单一模型的纯能力，脱离 Jarvis scaffold、工具和预算单独比较。
这些边界不是弱点，而是保证指标能服务产品决策的前提。
方法论来源
标题为“方法论来源”的章节这套设计吸收了几类公开最佳实践：
- Diátaxis 区分教程、指南、参考和解释；本页放在“核心概念”，因为它解释评估设计的理由。
- Datasheets for Datasets 和数据卡实践强调记录动机、组成、采集、用途、限制和维护责任。
- OpenAI agent evals 与 LangSmith complex agent evaluation 都强调除最终答案外，还要评估 trace、工具调用、trajectory 和单步决策。
- SWE-bench Verified 说明真实 issue 需要人工过滤，避免规格含糊和 oracle 不公平。
- Terminal-Bench、τ-bench 和 WebArena 的共同经验是：agent benchmark 要提供可复现环境、工具或网站状态，并用最终状态和轨迹共同判断长链任务。