sc-evaluate

LLM 评估技能

使用 Oracle LLM-as-judge 评分，针对黄金标准数据集运行 LLM 工作流评估。按加权维度衡量输出质量，识别薄弱步骤，并提出提示词改进建议。

快速开始

# Full evaluation (all test cases, all steps)
/sc:evaluate

# Quick spot check
/sc:evaluate --cases=case_1,case_2 --steps=1,2,3

# Re-evaluate existing results without re-running pipeline
/sc:evaluate --skip-pipeline

# Generate outputs only (no evaluation)
/sc:evaluate --skip-eval

# Specify judge model
/sc:evaluate --judge-model=gpt-4o

# Dry run to preview plan
/sc:evaluate --dry-run

行为流程

1. 发现 - 查找评估脚本、黄金标准和提示词文件
2. 配置 - 解析评估范围（用例、步骤、模型覆盖设置）
3. 执行 - 针对黄金标准输入运行工作流
4. 评估 - 通过 LLM-as-judge，根据黄金标准为输出评分
5. 分析 - 识别薄弱步骤、维度细分结果和模式
6. 建议 - 针对低分步骤提出具体的提示词改进建议
7. 报告 - 生成 JSON 和 Markdown 评估报告

标志

标志	类型	默认值	描述
--cases	string	all	要评估的测试用例 ID，以逗号分隔
--steps	string	all	要评估的步骤编号，以逗号分隔
--model	string	env default	覆盖工作流模型
--judge-model	string	env default	覆盖评审器／Oracle 模型
--skip-pipeline	bool	false	跳过工作流执行，评估现有结果
--skip-eval	bool	false	仅运行工作流，跳过评估
--dry-run	bool	false	预览执行计划，不调用 API
--output	string	eval_runs/YYYYMMDD_HHMMSS/	输出目录
--concurrency	int	5	并行评审器调用数
--threshold	int	70	“需要改进”的评分阈值

阶段 1：发现项目结构

定位评估组件：

组件	常见位置	用途
评估脚本	scripts/run_eval.py、eval/run.py	编排工作流和评分
黄金标准	gold_standards/、test_data/、fixtures/	预期输出
提示词	prompts/、templates/	工作流提示词模板
评分细则	eval/rubrics.py、config/rubrics.yaml	评分维度和权重

如果未找到标准结构，请询问用户指定路径。

阶段 2：配置范围

解析参数以确定：

• 要运行哪些测试用例（默认：所有已发现的用例）
• 要评估哪些工作流步骤（默认：全部）
• 工作流和评审器的模型覆盖设置
• 输出目录（默认：带时间戳的目录）

创建输出目录：

OUTPUT_DIR="${output:-eval_runs/$(date +%Y%m%d_%H%M%S)}"
mkdir -p "$OUTPUT_DIR"

阶段 3：执行工作流

针对黄金标准输入运行工作流：

python <eval_script> \
  --output "$OUTPUT_DIR" \
  --verbose \
  [--cases CASES] \
  [--steps STEPS] \
  [--model MODEL] \
  [--skip-pipeline] \
  [--skip-eval]

API 调用量估算：

• 工作流：步骤数 x 用例数次 API 调用
• 评估：评分维度数 x 用例数次评审器调用

为快速验证，建议先用 1-2 个用例和 2-3 个步骤运行。

阶段 4：使用 LLM-as-Judge 进行评估

针对每个步骤的输出，使用 Oracle LLM-as-judge 与黄金标准进行比较：

评估维度（可按项目自定义）：

维度	衡量内容
内容一致性	输出是否涵盖相同的要点？
结构匹配度	组织方式／格式是否相似？
细节准确性	具体声明和数据是否正确？
完整性	是否包含所有预期元素？

每个维度都有一个权重（0.0-1.0），每个步骤的权重总和为 1.0。

阶段 5：分析结果

阅读并分析评估报告：

1. 总体相似度分数：涵盖所有用例和步骤
2. 每个步骤的分数 —— 突出显示低于阈值的项（默认：70/100）
3. 每个用例的分数 —— 找出表现持续不佳的测试用例
4. 薄弱步骤的维度细分结果

分数解读：

分数范围	评估	操作
85-100	优秀	无需更改
70-84	良好	可进行小幅调整
60-69	需要改进	建议修改提示词
低于 60	较差	提示词可能需要重写

阶段 6：推荐改进方案

对于每个得分低于阈值的步骤：

1. 阅读当前提示词模板
2. 阅读黄金标准输出（预期结果）
3. 阅读流水线输出（实际结果）
4. 比较并找出差距：
   • 缺少黄金标准中包含的指令
   • 指令过于宽泛，导致输出不一致
   • 格式／结构差异
   • 具体程度不足

提出可执行的建议：

### Step N: <step_name> (Score: XX/100)

**Weakest Dimension**: <dimension> (XX/100)

**Gap Analysis**:
- Gold standard includes <X> but prompt doesn't instruct it
- Output format diverges: gold uses <format>, output uses <other>

**Suggested Prompt Changes**:
1. Add instruction: "<specific instruction>"
2. Clarify format: "<format guidance>"
3. Add example: "<example output snippet>"

输出结构

eval_runs/YYYYMMDD_HHMMSS/
  results/                    # Pipeline outputs
    case_1/
      step_01_<name>.md
      step_02_<name>.md
      ...
    case_2/
      ...
  evaluation/                 # Judge scores
    evaluation_report.json
    evaluation_report.md
    per_step_scores.csv
    per_case_scores.csv

MCP 集成

PAL MCP（可选）

工具	何时使用	用途
mcp__pal__thinkdeep	得分较低的步骤	深入分析输出不一致的原因
mcp__pal__consensus	修订提示词	使用多个模型验证拟议的更改
mcp__pal__codereview	评估脚本	审查评估流水线代码

Rube MCP（可选）

工具	何时使用	用途
mcp__rube__RUBE_REMOTE_WORKBENCH	大规模评估运行	在 Python 沙箱中处理结果
mcp__rube__RUBE_MULTI_EXECUTE_TOOL	通知	将结果报告到 Slack／email

错误处理

场景	操作
未找到评估脚本	向用户询问脚本路径
未找到黄金标准	向用户询问黄金标准目录
API 速率限制	降低并发数，增加延迟
流水线步骤失败	记录错误，继续执行剩余步骤
评审器返回无效分数	重试一次，然后标记为需要人工审查
输出目录已存在	追加时间戳后缀

护栏

• 始终传递 --verbose 以查看进度
• 全量运行前提醒 API 调用次数
• 建议先在子集上快速验证，再进行完整评估
• 保留所有中间输出以便调试
• 切勿修改黄金标准文件

工具协调

• Bash - 运行评估脚本
• Read - 检查提示词、黄金标准、输出和报告
• Write - 生成报告
• Grep - 搜索输出中的模式
• PAL MCP - 深入分析得分差距