bare-eval

裸模式评测 — 隔离评测调用

运行 claude -p --bare，快速、干净地进行评测和评分，无需承担插件开销。

需要 CC 2.1.81。 --bare 标志会跳过钩子、LSP、插件同步和技能目录遍历。

适用场景

• 根据断言为技能输出评分
• 触发分类（判断哪个技能匹配提示词）
• 迭代优化描述
• 任何不需要插件的脚本化 -p 调用

不适用场景

• 测试技能路由（需要 --plugin-dir）
• 测试 Agent 编排（需要完整的插件上下文）
• 交互式会话

前提条件

# --bare requires ANTHROPIC_API_KEY (OAuth/keychain disabled)
export ANTHROPIC_API_KEY="sk-ant-..."

# Verify CC version
claude --version  # Must be >= 2.1.81

快速参考

调用类型	命令模式
评分	claude -p "$prompt" --bare --max-turns 1 --output-format text
触发	claude -p "$prompt" --bare --json-schema "$schema" --output-format json
流式评分	claude -p "$prompt" --bare --max-turns 1 --output-format stream-json
优化	echo "$prompt" | claude -p --bare --max-turns 1 --output-format text
强制指定技能	claude -p "$prompt" --bare --print --append-system-prompt "$content"
提示词中使用 @ 文件	claude -p "grade @fixtures/case-1.md against rubric" --bare（CC 2.1.113 Remote Control 自动补全）

长时间运行的测试框架（CC 2.1.199+）： 设置 CLAUDE_CODE_RETRY_WATCHDOG=1，以便在无人值守的评测批次中运行——它会将非容量类瞬时错误的默认重试次数提高到 300，并取消 CLAUDE_CODE_MAX_RETRIES 的 15 次上限，使通宵评分任务能够熬过 API 瞬时故障，而不会在批次中途终止。

--output-format stream-json

以换行符分隔的 JSON 事件（每个令牌/工具调用一条）——让运行器可以为部分输出评分，或在探测失败时提前中止，而无需等待完整响应。

claude -p "$prompt" --bare --max-turns 1 --output-format stream-json \
  | while IFS= read -r line; do
      # line is a single JSON event; inspect $.type == "content_block_delta"
      jq -r 'select(.type == "content_block_delta") | .delta.text' <<< "$line"
    done

以下情况使用 stream-json 而非 json：

• 为长输出评分，并希望逐步评分；
• 逐步传递给另一个 CLI 步骤（例如 ork:eval-runner）；
• 需要同时获取每个令牌的计时数据和内容。

调用模式

加载详细模式和示例：

Read("references/invocation-patterns.md")

评分架构

结构化评测输出的 JSON 架构：

Read("references/grading-schemas.md")

流水线集成

OrchestKit 的评测脚本（npm run eval:skill）会自动检测裸模式：

# eval-common.sh detects ANTHROPIC_API_KEY → sets BARE_MODE=true
# Scripts add --bare to all non-plugin calls automatically

裸模式调用： 触发分类、强制指定技能、基线、所有评分。 绝不使用裸模式： run_with_skill（路由测试需要插件上下文）。

CC 2.1.119：--print 遵循 Agent 的 tools: / disallowedTools:（M122）

在 CC 2.1.119 之前，无论 Agent frontmatter 中的 tools: 和 disallowedTools: 如何设置，--print 模式都会使用完整的默认工具集。裸模式评测的评分实际上不受限制——评分器可以调用任意工具，即使 Agent 定义对其加以限制也是如此。

从 2.1.119 起，--print 会强制遵循 Agent 声明的工具范围。 对评测设计的影响：

影响	操作
依赖不受限工具访问的评测评分器现在可能会失败	检查评分器提示词，确认其实际需要的工具；通过 Agent 的 tools: frontmatter 显式添加允许项
评测结果与交互式运行相符	提高了可复现性——评测模型实际能做什么，而非它在未沙盒化的 --print 中能做什么
--agent <name> 在 --print 中也遵循 permissionMode	受权限限制的工具（Bash、Edit）需要设置 permissionMode: acceptEdits，或在 Agent 定义中显式列入允许列表

迁移测试：

# Run an eval against an agent with a deliberately tight tools: list.
# Graders that previously called Read/Bash freely will now fail unless those
# tools are declared on the agent.
claude -p "$prompt" --bare --print --agent grader-test

如果评分器因“工具未获允许”错误而失败，请将所需工具添加到 Agent 的 tools: frontmatter 中，然后重新运行。

CC 2.1.121：用于确保评分器确定性的 CLAUDE_CODE_FORK_SUBAGENT=1（#1545）

在 CC 2.1.121 之前，此环境变量仅在交互式会话中生效。从 2.1.121 开始，非交互式路径（claude -p、SDK）也会遵循此设置——每次评分器调用都会获得全新的分叉子 Agent 上下文。

此设置解决的交叉评估状态泄漏问题：

不进行分叉时，按顺序运行的 claude -p --bare 评分器会继承测试框架状态：

继承的内容	症状
memory MCP 查询缓存	评分器看到上一次运行留下的过期命中；相同的测试样例得到不同的评分
磁盘上的 .claude/chain/*.json	为「实现」评分的评分器认为「探索」已运行（文件来自之前的测试）
ToolSearch 延迟工具缓存	第一个评分器加载的 MCP 会泄漏到下一个评分器的工具注册表中
模型选择器偏好	评分器 N 继承评分器 N-1 的 --model=opus

这导致约 5–10% 的重试率，评分也无法复现——评估基线会在不同运行之间漂移，工程师则疲于追查并不存在的回归问题。

修复：tests/evals/scripts/lib/eval-common.sh 会导出 CLAUDE_CODE_FORK_SUBAGENT=1，因此所有引用它的脚本（run-trigger-eval、run-quality-eval、run-agent-eval、optimize-description 等）都会自动使用分叉评分器。CI 工作流 .github/workflows/skill-eval.yml 也会在工作流级别设置此变量（其前身 orchestkit-eval.yml 已于 2026-08-01 退役——其评分阶段评估的是描述文本，而非行为）。旧版 CC 会静默忽略此环境变量（不执行任何操作）。

确定性约定：对同一个测试样例连续运行两次相同的评分器，会产生相同的评分。已通过 tests/evals/scripts/test-grader-determinism.sh 验证。

性能

场景	不使用 --bare	使用 --bare	节省时间
单次评分调用	启动约需 3-5s	约 0.5-1s	2-4 倍
触发（每条提示词）	约 3-5s	约 0.5-1s	2-4 倍
完整评估（50 次调用）	约 150-250s 开销	约 25-50s	3-5 倍

规则

Read("rules/_sections.md")

故障排除

Read("references/troubleshooting.md")

动态工作流测试框架（技能中的模板）

workflows/skill-fitness.js 是可运行的动态工作流模板，是静态一致性评分器（scripts/eval/conformance-check.mjs）的工作流补充方案。它会为每个技能派出一个独立上下文 Agent，对适用度（新鲜度／路由清晰度／结构）进行评分，并综合生成排名评分卡；它可以发现静态 grep 无法发现的定性偏差（描述与正文数量不匹配、标题重复、特定安装环境的绝对路径、版本漂移）。使用 Workflow 工具运行：

Workflow({ scriptPath: "${CLAUDE_SKILL_DIR}/workflows/skill-fitness.js",
           args: ["assess", "commit", "doctor"] })

请将其视为模板，而非可逐字照用的脚本——请根据用途调整 SKILLS 列表和评分标准。实际成本不低（每个技能约 50k 个 token；为全部约 112 个技能评分约需 6M 个 token），因此请通过 args 传入明确的批次。优先采用静态检查：先运行 conformance-check.mjs（零 token）进行预筛选，再运行此测试框架，评估 grep 无法判断的内容。

留出集 Bake-Off 评分

留出集晋级门会通过裸模式分叉评分器，对同一份密封留出集上的冠军和挑战者 SKILL.md 进行评分——这是上述确定性约定的标准应用场景：相同的评分器、相同的 ork-rubric/1.0 和相同的密封集合，并设置 CLAUDE_CODE_FORK_SUBAGENT=1，确保唯一变量是受测版本。两种 --bare 限制均适用（需要 ANTHROPIC_API_KEY，会直接产生 token 费用 → 仅按需或在 CI 中运行）。使用 bash tests/evals/scripts/run-skill-eval.sh --holdout-promote <skill> 运行。

相关内容

• eval:skill npm 脚本——统一的技能评估运行器
• eval:trigger——触发准确性测试
• eval:quality——A/B 质量比较
• optimize-description.sh——迭代改进描述
• 版本兼容性：doctor/references/version-compatibility.md