llm-judge

LLM Judge

使用结构化评估比较多个仓库中的代码实现。

用法

llm-judge <spec> <repo1> <repo2> [repo3...] [--labels=...] [--weights=...] [--branch=...]

参数

参数	必填	说明
spec	是	规格说明／需求文档的路径
repos	是	要比较的 2 个或更多仓库路径
--labels	否	以逗号分隔的标签（默认使用目录名）
--weights	否	覆盖权重，例如：functionality:40,security:30
--branch	否	用于与 main 比较的分支（默认：main）

工作流

1. 将 $ARGUMENTS 解析为 spec_path、repo_paths、labels、weights 和 branch。
2. 验证规格说明文件、各仓库路径以及仓库数量是否达到最低要求。
3. 将规格说明文档读入内存。
4. 加载此技能及其支持参考文件。
5. 收集各仓库的事实（每个仓库对应一个 Phase 1 单元）——只收集事实，不评分。
6. 在继续之前验证 repo-agent 的 JSON 结果。
7. 为每个维度评分（每个维度对应一个 Phase 2 单元）。
8. 汇总分数、计算加权总分、排列仓库名次并撰写报告。
9. 显示 Markdown 摘要并验证 JSON 报告。

硬性关卡

按顺序执行工作流：当前关卡通过之前，不得开始下一阶段。 每个通过条件都必须可检查（磁盘上的文件、非空内容或 json.load 成功），而不能只是“我已在内部审阅”。

关卡	通过条件	解锁内容
A — 输入	spec_path 是可读取的非空文件；len(repo_paths) ≥ 2；每个路径都包含 .git。	Phase 1 仓库 Agent
B — Phase 1 事实	对于每个仓库 Agent 输出：stdin/stdout 可解析为 JSON；必需的键／结构与 references/fact-schema.md 相符。	Phase 2 评审 Agent
C — Phase 2 分数	五个评审输出（每个维度一个）均可解析为 JSON；每个输出都为每个仓库标签提供分数（及理由）。	汇总
D — 报告文件	.beagle/llm-judge-report.json 存在；python3 -c "import json; json.load(open('.beagle/llm-judge-report.json'))" 退出码为 0。	向用户显示 Markdown 摘要
E — 一致性	摘要表格和结论使用的标签、权重及各维度分数，与 JSON 报告一致。	将任务标记为完成

允许在同一阶段内并行执行（所有 Phase 1 任务一起；所有 Phase 2 任务一起），但在关卡 B 通过之前不得开始 Phase 2，且在关卡 D 通过之前不得向用户显示摘要。

命令工作流

步骤 1：解析参数

解析 $ARGUMENTS 以提取：

• spec_path：第一个位置参数
• repo_paths：其余位置参数（必须为 2 个或更多）
• labels：取自 --labels，或根据目录名生成
• weights：取自 --weights，或使用默认值
• branch：取自 --branch，或使用 main

默认权重：

{
  "functionality": 30,
  "security": 25,
  "tests": 20,
  "overengineering": 15,
  "dead_code": 10
}

步骤 2：验证输入

[ -f "$SPEC_PATH" ] || { echo "Error: Spec file not found: $SPEC_PATH"; exit 1; }

for repo in "${REPO_PATHS[@]}"; do
  [ -d "$repo/.git" ] || { echo "Error: Not a git repository: $repo"; exit 1; }
done

[ ${#REPO_PATHS[@]} -ge 2 ] || { echo "Error: Need at least 2 repositories to compare"; exit 1; }

步骤 3：读取规格说明文档

SPEC_CONTENT=$(cat "$SPEC_PATH") || { echo "Error: Failed to read spec file: $SPEC_PATH"; exit 1; }
[ -z "$SPEC_CONTENT" ] && { echo "Error: Spec file is empty: $SPEC_PATH"; exit 1; }

步骤 4：加载技能

将此 llm-judge 技能及其参考文件加载到上下文中。

步骤 5：Phase 1 — 收集各仓库的事实

如果 Agent 支持子 Agent，则为每个仓库并行分派一个 Phase 1 仓库 Agent；否则按顺序逐个仓库执行相同的事实收集步骤——两种方式的输出完全相同。向每个单元提供以下说明：

You are a Phase 1 Repo Agent for the LLM Judge evaluation.

**Your Repo:** $LABEL at $REPO_PATH

**Spec Document:**
$SPEC_CONTENT

**Instructions:**
1. Load the **llm-judge** skill's references/repo-agent.md for detailed instructions
2. Follow references/fact-schema.md for the output format
3. Load the **llm-artifacts-detection** skill ([../../../beagle-core/skills/llm-artifacts-detection/SKILL.md](../../../beagle-core/skills/llm-artifacts-detection/SKILL.md), if available) for dead-code/overengineering analysis

Explore the repository and gather facts. Return ONLY valid JSON following the fact schema.

Do NOT score or judge. Only gather facts.

将所有仓库的输出汇总到 ALL_FACTS。

步骤 6：验证 Phase 1 结果

echo "$FACTS" | python3 -c "import json,sys; json.load(sys.stdin)" 2>/dev/null || { echo "Error: Invalid JSON from $LABEL"; exit 1; }

步骤 7：Phase 2 — 按维度评分

如果 Agent 支持子 Agent，则为每个维度并行分派一个评审 Agent（共五个）；否则按顺序为各维度评分——两种方式的输出完全相同。向每个单元提供以下说明：

You are the $DIMENSION Judge for the LLM Judge evaluation.

**Spec Document:**
$SPEC_CONTENT

**Facts from all repos:**
$ALL_FACTS_JSON

**Instructions:**
1. Load the **llm-judge** skill's references/judge-agents.md for detailed instructions
2. Follow references/scoring-rubrics.md for the $DIMENSION rubric

Score each repo on $DIMENSION. Return ONLY valid JSON with scores and justifications.

步骤 8：汇总分数

for repo_label in labels:
    scores[repo_label] = {}
    for dimension in dimensions:
        scores[repo_label][dimension] = judge_outputs[dimension]['scores'][repo_label]

    weighted_total = sum(
        scores[repo_label][dim]['score'] * weights[dim] / 100
        for dim in dimensions
    )
    scores[repo_label]['weighted_total'] = round(weighted_total, 2)

ranking = sorted(labels, key=lambda l: scores[l]['weighted_total'], reverse=True)

步骤 9：生成结论

指出获胜者，解释其获胜原因，并说明结果接近的情况或权衡之处。

步骤 10：写入 JSON 报告

mkdir -p .beagle

写入 .beagle/llm-judge-report.json，其中包含版本、时间戳、仓库元数据、权重、分数、排名和结论。

步骤 11：显示摘要

呈现包含评分表、排名、结论和详细理由的 Markdown 摘要。

步骤 12：验证

python3 -c "import json; json.load(open('.beagle/llm-judge-report.json'))" && echo "Valid report"

输出格式

生成的报告应包含：

• 仓库标签和路径
• 各维度的评分和理由
• 加权总分和排名
• 解释获胜者的结论

参考文件

文件	用途
references/fact-schema.md	第 1 阶段事实的 JSON 架构
references/scoring-rubrics.md	各维度的详细评分标准
references/repo-agent.md	第 1 阶段 Agent 的说明
references/judge-agents.md	第 2 阶段评审 Agent 的说明

评分模型

维度	默认权重	评估内容
功能性	30%	规范符合度、测试通过率
安全性	25%	漏洞、安全模式
测试质量	20%	覆盖率、DRY、模拟边界
过度设计	15%	不必要的复杂性
死代码	10%	未使用代码、TODO

评分等级

分数	含义
5	优秀——超出预期
4	良好——满足要求，仅有轻微问题
3	一般——功能正常，但存在明显缺漏
2	低于平均水平——存在重大问题
1	差——未达到基本要求

第 1 阶段：收集各仓库的事实

对每个仓库运行一个事实收集单元（如果支持子 Agent，则并行运行；否则依次运行）：

You are a Phase 1 Repo Agent for the LLM Judge evaluation.

**Your Repo:** $REPO_LABEL at $REPO_PATH
**Spec Document:**
$SPEC_CONTENT

**Instructions:** Follow the **llm-judge** skill's references/repo-agent.md

Gather facts and return a JSON object following the schema in references/fact-schema.md.

Load the **llm-artifacts-detection** skill ([../../../beagle-core/skills/llm-artifacts-detection/SKILL.md](../../../beagle-core/skills/llm-artifacts-detection/SKILL.md), if available) for dead code and overengineering analysis.

Return ONLY valid JSON, no markdown or explanations.

将所有 repo-agent 的输出收集到 ALL_FACTS。

第 2 阶段：按维度评分

收集完所有第 1 阶段事实后，对五个维度进行评分（如果支持子 Agent，则并行运行；否则依次运行），每个维度对应一个单元：

You are the $DIMENSION Judge for the LLM Judge evaluation.

**Spec Document:**
$SPEC_CONTENT

**Facts from all repos:**
$ALL_FACTS_JSON

**Instructions:** Follow the **llm-judge** skill's references/judge-agents.md

Score each repo on $DIMENSION using the rubric in references/scoring-rubrics.md.

Return ONLY valid JSON following the judge output schema.

汇总

1. 收集五个评审输出。
2. 使用配置的权重计算各仓库的加权总分。
3. 按加权总分降序排列仓库。
4. 生成结论，说明结果及任何势均力敌的情况。
5. 写入 .beagle/llm-judge-report.json。

输出

显示包含评分、排名、结论和详细理由的 Markdown 摘要。

验证

完成前（对应硬性门槛 D 和 E）：

1. 门槛 D： .beagle/llm-judge-report.json 存在，且 json.load 可以成功加载。
2. 门槛 E / 完整性： 每个仓库标签都包含所有维度的评分；每个 weighted_total 均等于按配置权重计算的各维度 (score × weight / 100) 之和；Markdown 摘要与 JSON 报告一致。

规则

• 继续之前始终验证输入
• 完成所有第 1 阶段事实收集后，才能开始第 2 阶段评分（如果支持子 Agent，则在阶段内并行；否则依次进行）
• 第 2 阶段每个维度运行一个单元
• 每个分数都必须附有理由
• 显示摘要之前先写入 JSON 报告