用途
Judge 是一个质量评估技能，在任务完成边界充当质量门禁。它依据 KLS（Krogstie-Lindland-Sindre）质量框架派生的三维评分表，对智能体任务输出进行打分，并产出结构化的裁决记录。适用于需要对智能体产出进行自动 Quality Gate 的场景。
评分表：三个 KLS 维度
评分表复用了 disciplined-quality-evaluation 中定义的 KLS 质量框架的三个维度：
| 维度 | 问题 | 评判标准 |
|---|---|---|
| Semantic（语义） | 是否准确表示领域？ | 事实正确性、领域术语、无矛盾 |
| Pragmatic（语用） | 是否支持预期的决策/行动？ | 可操作、有用、解决任务目标 |
| Syntactic（句法） | 是否内部一致且结构良好？ | 格式合规、结构完整、无损坏引用 |
评分
| 分值 | 含义 |
|---|---|
| 1 | 差——存在重大问题，阻碍使用 |
| 2 | 低于标准——有显著缺口 |
| 3 | 合格——达到最低标准 |
| 4 | 良好——清晰、有用、问题很少 |
| 5 | 优秀——典范、无问题 |
裁决阈值
| 条件 | 裁决 |
|---|---|
| 所有维度 >= 3 且平均值 >= 3.5 | accept |
| 任一维度 < 3 或平均值 < 3.5，但所有维度 >= 2 | improve |
| 任一维度 < 2 | reject |
| 模型之间在 accept/reject 上存在分歧 | escalate |
裁决格式
每次评估都会生成一个 JSON 裁决记录，完整 schema 见 automation/judge/verdict-schema.json。最小结构如下：
{ "task_id": "issue-18", "model": "opencode/gpt-5-nano", "mode": "quick", "verdict": "accept", "scores": { "semantic": 4, "pragmatic": 4, "syntactic": 5 }, "average": 4.33, "reasoning": "Brief justification for scores", "improvements": [], "timestamp": "2026-02-17T14:30:00Z" }
输出必须仅为有效 JSON——不得包含 markdown 围栏、前言或尾随文本。
评审模式
快速评审（Quick Judge）
- 模型：opencode/gpt-5-nano（快速、低延迟）
- 用途：任务完成时的快速通过/不通过筛查
- 超时：30 秒
- 提示词模板：references/prompt-quick.md
- 输出：包含评分与一行理由的裁决 JSON
深度评审（Deep Judge）
- 模型：opencode/kimi-k2.5-free（全面、具备推理能力）
- 用途：带改进建议的详细评估
- 超时：60 秒
- 提示词模板：references/prompt-deep.md
- 输出：包含评分、推理链和改进列表的裁决 JSON
仲裁评审（Tiebreaker）
- 模型：opencode/gpt-5.1-codex-mini（独立视角、不同供应商）
- 用途：解决快速与深度评审之间在 accept/reject 上的分歧
- 超时：45 秒
- 提示词模板：使用深度提示词并附上先前裁决
- 触发条件：快速与深度裁决在 accept 与 reject/improve 上不一致
多轮协议
- 运行快速评审 | +-- accept --> 完成（accept） +-- reject --> 完成（reject，记录改进项） +-- improve --> 运行深度评审 | +-- accept --> 完成（accept） +-- reject --> 完成（reject，记录改进项） +-- improve --> 人工回退
当快速与深度在 accept 与 reject 上不一致时：
- 快速：accept + 深度：reject --> 运行仲裁评审
- 快速：reject + 深度：accept --> 运行仲裁评审
- 仲裁裁决为最终结果（不再进一步迭代）
最多 3 次模型调用后即转到人工回退。
人工回退标准
出现以下情况时升级到人工复核：
- 三次模型调用后仍未达成共识
- 任一模型在重试后返回无效 JSON
- 任一模型在重试后超时
- 快速与深度评审的裁决均为 "improve"（质量模糊）
- 任务涉及安全敏感或合规关键内容
集成点
运行脚本
Judge 由 automation/judge/run-judge.sh（v2）调用，该脚本会：
- 将提示词写入临时文件（消除文件内容导致的 shell 转义问题）
- 使用 opencode 配合 --file <tempfile> 实现可靠的提示词传递
- 从 opencode 的 JSON 事件流中解析裁决 JSON
- 实现多轮协议（quick -> deep -> tiebreaker）
- 可选地用 terraphim-cli 术语匹配来丰富裁决日志
裁决日志
所有裁决都会追加写入 automation/judge/verdicts.jsonl，每行一个 JSON 对象。这支持：
- 所有质量评估的审计追踪
- 跨任务的趋势分析
- 模型性能对比
Pre-Push 钩子
Judge 可通过 automation/judge/pre-push-judge.sh 作为 pre-push 钩子调用，阻止获得 "reject" 裁决的推送。
Terraphim 集成（可选）
当 terraphim-cli 可用时，judge 运行器会使用基于知识图谱的术语归一化来识别模型推理中的评分表维度。
知识图谱设置：
安装 judge KG 文件并配置角色
bash automation/judge/setup-judge-kg.sh
验证安装
terraphim-cli thesaurus --limit 50 terraphim-cli find "factual correctness and actionability"
KG 文件位于 automation/judge/kg/：
| 文件 | 归一化术语 | 用途 |
|---|---|---|
| judge-semantic.md | judge-semantic | 语义质量维度的同义词 |
| judge-pragmatic.md | judge-pragmatic | 语用质量维度的同义词 |
| judge-syntactic.md | judge-syntactic | 句法质量维度的同义词 |
| judge-verdicts.md | judge-verdicts | 裁决词汇归一化 |
| judge-checklist.md | judge-checklist | 必需裁决要素 |
故障开放设计
如果未安装 terraphim-cli，judge 会回退到直接的 JSON 提取，不进行术语归一化。所有核心功能在没有 terraphim 的情况下均可工作——KG 集成只是增强层。
资源
references/：
- prompt-quick.md——快速评审提示词模板，用于快速筛查
- prompt-deep.md——深度评审提示词模板，用于全面评估