oh-my-claudecode Executor 基准夹具全解析从task-add-timestamp看任务定义、判分与评测运行【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode本文以 oh-my-claudecode 仓库中 task-add-timestamp.md 这一 Executor执行器评测任务夹具为研究对象逐层拆解“一条真实代码改动任务”在基准benchmark体系中是如何被定义、如何作为 Prompt 输入、如何被解析与量化打分的。读完你将掌握任务夹具fixture的文档结构与编写规范、与其配套的 Ground Truth真值标注格式、executor与deep-executor两代 Agent 提示词的评测对比思路以及完整跑通一次单任务基准的命令与结果解读方法。一、这个文件是什么评测体系里的一个“任务标本”在 oh-my-claudecode 中benchmarks/目录承载了针对不同 Agent 角色的自动化评测code-reviewer、debugger、executor、harsh-critic等各有一个子目录。每个子目录遵循统一结构benchmarks/executor/ ├── fixtures/ # 输入评测任务本身 │ └── tasks/ # ├─ task-add-timestamp.md │ └── ... # ├─ task-input-validation.md │ └── ... # └─ task-notification-refactor.md ├── ground-truth/ # 真值期望 Agent 找出的“关键点” │ └── task-add-timestamp.json ├── prompts/ # 被替代的旧 Agent 提示词存档 │ └── deep-executor.md └── run-benchmark.ts # 该子基准的启动器从评测框架看fixtures/tasks/这类“task 域”夹具由 shared/runner.ts 中的FIXTURE_DIRECTORY_TO_DOMAIN映射到task域——夹具的目录名决定领域文件名决定唯一标识。Runner 会遍历fixtures下每个子目录中的.md或.ts文件用file.replace(/\.(md|ts)$/, )得到id因此这里的task-add-timestamp.md的 id 就是task-add-timestamp它必须与ground-truth/task-add-timestamp.json一一对应。本文件的特殊使命在 run-benchmark.ts 的开头注释中写得很清楚评测目标是对比“合并了 deep-executor 的新版 executor”与“旧的 deep-executor 提示词”在实现质量上的差异。因此这个夹具会被分别喂给两个 Agent 系统提示词作为同一个用户问题模板的输入最终比较双方的命中率、漏报率与综合得分。二、任务夹具的结构解剖四段式“最小可执行规格”task-add-timestamp.md本身是一个自洽、可复现的代码改动任务说明书全文只有四段式结构却完整刻画了一次真实的需求交付Task标题一句话点明目标——给User接口增加createdAt时间戳。Context背景解释动机与验收标准——需要追踪用户创建时间字段要落地到“创建用户”的路径上。Existing Code现状代码给出三个文件的完整快照构成 Agent 的“代码库”。Requirements需求清单可逐条勾选验收的原子条款。这种设计让它兼具两种用途在基准体系里它是标准输入脱离基准单独阅读它也是一份可直接开工的 issue / 需求文档。2.1 Context 与类型定义type 层背景说明“We need to track when users are created”随后给出User类型的现状快照// src/types/user.ts export interface User { id: string; name: string; email: string; role: admin | user | viewer; isActive: boolean; }这条信息暗示了两点约束createdAt是新增字段而非替换现有字段类型系统要求我们一旦在接口中声明createdAt: Date所有构造User对象的代码路径都必须补上该字段否则编译期就会报错——这正是“类型层面的改动会影响实现层面”的经典连锁反应。2.2 服务层与路由层service / api 层// src/services/user-service.ts import { User } from ../types/user; import { db } from ../database; import { generateId } from ../utils/id; export async function createUser(input: { name: string; email: string; role: User[role] }): PromiseUser { const user: User { id: generateId(), name: input.name, email: input.email, role: input.role, isActive: true, }; await db.users.insert(user); return user; } export async function getUser(id: string): PromiseUser | null { return db.users.findById(id); } export async function listUsers(): PromiseUser[] { return db.users.findAll(); }// src/api/routes/users.ts import { createUser, getUser, listUsers } from ../../services/user-service; router.post(/users, async (req, res) { const { name, email, role } req.body; const user await createUser({ name, email, role }); res.status(201).json(user); }); router.get(/users/:id, async (req, res) { const user await getUser(req.params.id); if (!user) return res.status(404).json({ error: User not found }); res.json(user); }); router.get(/users, async (req, res) { const users await listUsers(); res.json(users); });从这三个文件可以看出仓库的既有模式类型与实现分层清晰createUser通过generateId()注入主键并在函数体内构造完整对象路由层只做 HTTP 边界转换。这些“模式信号”正是评判 Agent 是否“贴合现有代码风格”的依据。2.3 Requirements一份刻意克制的最小改动契约1. Add createdAt: Date to the User interface 2. Set createdAt to new Date() in the createUser function 3. No changes needed to routes or other services第三条是关键信息改动边界被显式收窄。评测不希望看到 Agent 顺手“重构”路由、补充无关服务或为单点逻辑引入抽象层。这与 executor 提示词中反复强调的约束高度一致——在 agents/executor.md 中可以读到“Prefer the smallest viable change”“Do not broaden scope beyond requested behavior”“Do not refactor adjacent code unless explicitly requested”其底层逻辑是“最常见的失败模式是做太多而非做太少the most common failure mode is doing too much, not too little”。而 deep-executor.md 同样要求“Prefer the smallest viable change”并列举了 Overengineering、Scope reduction 等失败模式。也就是说这个夹具本身就在直接检验 Agent 的“边界纪律”而不只是“能不能改对字段”。三、参考实现把需求翻译成两行最小 diff结合夹具的现状代码与 task-add-timestamp.json 真值一次符合验收的改动应精确落在两个位置改动一类型定义补字段// src/types/user.ts export interface User { id: string; name: string; email: string; role: admin | user | viewer; isActive: boolean; createdAt: Date; // 新增 }改动二创建路径赋值// src/services/user-service.ts export async function createUser(input: { name: string; email: string; role: User[role] }): PromiseUser { const user: User { id: generateId(), name: input.name, email: input.email, role: input.role, isActive: true, createdAt: new Date(), // 新增 }; await db.users.insert(user); return user; }要点说明createdAt的类型是Date而非string因此值必须是new Date()生成的Date实例这正是真值IMPL-TS-2校验的语义关键词包含new Date。时间应在“服务层创建对象时”打点而不是在路由层传入保证无论调用方是谁都能正确记录创建时刻。路由层无需改动res.status(201).json(user)序列化Date时会按 JavaScript 标准行为输出 ISO-8601 字符串形如2026-09-08T01:47:56.000ZHTTP 表现已满足要求——夹具明确声明这条链路“不需要改动”。四、Ground Truth这条任务如何被“可判分”地定义与夹具配套的 ground-truth/task-add-timestamp.json 定义了 Agent 输出应命中的全部“关键点”其 JSON Schema 由 shared/scorer.ts 中的validateSharedGroundTruth强校验fixtureId、domain、findings数组、isCleanBaseline均必须存在且 finding id 不允许重复。该夹具的真值内容如下表finding id严重级别类别摘要匹配关键词节选IMPL-TS-1CRITICALfinding必须在src/types/user.ts的User接口中新增createdAt: Date字段createdAt、User、interface、Date、fieldIMPL-TS-2CRITICALfindingcreateUser构造 user 对象时必须将createdAt设为new Date()createdAt、new Date、createUser、setIMPL-TS-3MAJORfinding改动范围必须最小——仅User接口与createUser两处路由、其它服务与测试无需改动scope、minimal、two files、interface、service同时标注了domain: task、expectedVerdict: trivial与isCleanBaseline: false。其中expectedVerdict: trivial与 executor 提示词中的任务分类法Trivial / Scoped / Complex呼应——这是一个“单点改动、边界清晰”的平凡任务Agent 不应开展大范围探索isCleanBaseline: false表示该夹具不是一个“零问题基线”即存在必须被发现的期望项与那些用于检验“是否乱报问题”的干净基线夹具语义相反。4.1 Agent 输出如何与真值匹配匹配与评分逻辑继承自 harsh-critic 的规范 scorershared/scorer.ts 会将task域投影为规范评分器可处理的analysis域核心机制有两层关键词重叠匹配Agent 的每一条 finding 文本需与真值关键词集合产生足够多的重叠。所需命中数随关键词集合大小按比例缩放约 40% 并向上取整shared 层另有MIN_KEYWORD_MATCHES 2的兜底下限常量见 shared/types.ts。严重级别容差ALLOW_ADJACENT_SEVERITY true即 CRITICAL 与 MAJOR 这类相邻级别之间允许互相认定。随后得出truePositiveRate真阳率、falseNegativeRate漏报率、falsePositiveRate误报率、missingCoverage、evidenceRate、processCompliance等维度。shared 层在 types.ts 中给出的权重参考为真阳率 0.25、漏报率 0.15、误报率 0.10、缺失覆盖 0.20、多视角覆盖 0.10、证据率 0.10、过程合规 0.10最终加权得到compositeScore。注意一个细节evidenceRate依赖 Agent 输出中的“证据痕迹”。shared/parser.ts 的EVIDENCE_PATTERN会把反引号包裹的代码片段以及文件路径:行号如user-service.ts:26识别为证据。因此一个高质量回答应当给出类似src/types/user.ts中新增createdAt: Date、src/services/user-service.ts的createUser中设置new Date()这样的带文件定位与代码片段的描述而不是空泛的“我加了时间戳”。五、把单个夹具跑起来底层调用链与命令行实操要单独针对这个夹具评测executorvsdeep-executor仓库给出了完整的 CLI 支持。5.1 运行命令npx tsx benchmarks/executor/run-benchmark.ts --fixture task-add-timestamprunner 会自动以默认双 Agentexecutor与deep-executor配对运行该夹具并输出对比报告。支持的参数见 run-benchmark.ts 与 shared/runner.ts参数说明默认值--agent name只运行单个 Agent 变体executordeep-executor--agents a,b以逗号分隔指定多个 Agent同上--fixture id只运行单个夹具此处传task-add-timestamp全部--output-dir path报告输出目录benchmarks/executor/results--model model评测使用的 Claude 模型claude-opus-4-6--dry-run不调用 API仅校验流水线关闭需要先设置环境变量ANTHROPIC_API_KEY或ANTHROPIC_AUTH_TOKEN可选ANTHROPIC_BASE_URL覆盖 API 地址见 shared/runner.ts。5.2 端到端调用链一次评测的实际流程对应 shared/runner.ts 的runBenchmark是装配提示词loadAgentPrompt先尝试仓库根目录agents/{name}.md若不存在再回落到benchmarks/{name}/prompts/{name}.mdrunner.ts。因此本基准中executor的提示词来自 agents/executor.md而deep-executor的提示词来自 benchmarks/executor/prompts/deep-executor.md旧版存档。构造用户消息buildUserMessage把夹具原文包进统一指令模板——“Implement the following task. Describe your approach, the files you would modify, and the changes you would make:”确保两侧 Agent 收到完全相同的输入。调用模型callClaude以max_tokens: 8192发起请求遇到529 / overloaded / rate / 500等可重试错误时按指数退避最多重试 5 次runner.ts。解析输出parseGenericOutput按 Markdown 小标题切分段落识别 Critical / Major / Minor 严重级别区块并抽取列表项为 findingparser.ts。这也是 executor 提示词中要求输出“Changes Made / Verification / Summary”结构化内容的原因——其格式与解析器天然兼容。载入真值并打分从ground-truth/读取同 id JSON经身份校验后匹配、计分。产出报告向输出目录同时写入results.json、report.md以及带时间戳的results_{ts}.json、report_{ts}.mdrunner.ts随后在终端打印 Fixture / Agent / Status / Quality / Tokens / API / Harness 汇总表并根据是否存在失败项设置进程退出码有失败返回 1。对于不想产生 API 成本的快速验证可先执行npx tsx benchmarks/executor/run-benchmark.ts --fixture task-add-timestamp --dry-run它会校验提示词加载、夹具加载、真值存在性与解析链路但跳过真实模型调用runBenchmark在dryRun时直接返回空结果。六、难度梯度从“平凡任务”看夹具集的设计意图单个夹具并非孤例。benchmarks/executor/fixtures/tasks/下共三个 task 域夹具构成一条刻意设计的能力梯度与 executor 提示词中“Trivial / Scoped / Complex”的任务分类一一对应夹具大致内容规模定位task-add-timestamp.md为User接口与createUser补createdAt字段Trivial类型 实现各一处边界明确task-input-validation.md为POST /api/products增加入参校验字段规则、SKU 正则、400 语义错误Scoped集中在服务层但规则细则多task-notification-refactor.md把单渠道邮件通知重构为 email / SMS / push 多渠道抽象ScopedComplex涉及接口抽象、类实现与向后兼容三者共享同一套“Context Existing Code Requirements”夹具骨架但要求的改动面、抽象深度与回归风险逐级递增——从“加一个字段”到“设计统一NotificationChannel接口并保证旧调用方默认走 email 的兼容性”。这为对比两代 Agent 在不同复杂度下的表现差异提供了可量化的素材也让task-add-timestamp这样的 Trivial 用例成为检验“是否过度设计、是否越界重构”的敏感探针一个在简单任务上仍忍不住扩大改面的 Agent其 compositeScore 会因漏掉IMPL-TS-3MAJOR以及引入误报而被显著拉低。七、把夹具当规格读给阅读者与二次使用者的建议这个文件的最终价值不只是“被跑一遍”。它示范了一套可复用的任务定义规范任何想为 executor 基准新增评测用例的人都可以照此模板产出新夹具标题一句话讲清交付物让 Agent 无需猜测目标Context 交代动机与验收口径“为什么做”“怎样算完成”Existing Code 提供完整、可直接编译的现状快照覆盖类型层、服务层与路由层便于 Agent 推断代码风格与调用链Requirements 逐条列出可判定的原子验收项并显式声明“不需要改动”的文件把改动边界写进契约配套一份 ground-truth JSON把每条期望改动映射为带严重级别与关键词的 finding从而能被关键词匹配器自动判分。在 oh-my-claudecode 的评测体系中一套夹具由此同时扮演“需求文档”“Agent 输入”和“打分基准”三重角色——这也正是benchmarks/目录能在不修改业务代码的前提下持续度量 executor 提示词迭代质量的根本原因。若想继续深入可对照阅读 shared/runner.ts评测主循环、shared/parser.ts输出解析与证据识别与 agents/executor.md被测 Agent 的完整行为契约即可完整拼出“一条任务从 Markdown 到 compositeScore”的全部路径。【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
