Star110
90
代码
代码
Issues45
Pull Requests25
项目讨论
Wiki
分析
Star110
90
karagg01karagg01agent轨迹评测加入skill改进建议
3d7ff15f创建于 4 天前历史提交

评估器开发指南

适用于给「评测中心 / 实验」新增或改造评估器的同学。 前置阅读：04-api-and-contracts.md、07-conventions-and-extension.md。

本文分两部分：打分方法论（怎么设计一个可信的评估器，第 3 节，必读）与工程接入（代码怎么写，第 4 节起）。方法论部分踩过的坑都是真实线上问题，别跳过。

1. 评估器在系统里的位置

实验(Experiment)
  └─ case(ExperimentCase：一条 trace + 输入/实际输出/参考答案)
       └─ × 每个评估器 → ExperimentEvalResult(status/verdict/summary/score/points/evidence)
  • 一个 case × 一个评估器 = 一行结果，互不影响；单行失败不拖垮其它行，可单独重评。
  • 执行入口：src/lib/engine/experiment/run-experiment.ts 的 executeResultRow()。
  • 分发规则（同一文件的 evaluateOnce()）：
evaluatorId 走哪个实现
preset-agent-task-completion / preset-agent-trace-quality experiment/faithful-preset-evaluators.ts
preset-depth-* experiment/depth-preset-evaluators.ts
preset-agent-tool-* experiment/agent-tool-preset-evaluators.ts
preset-text-* experiment/text-preset-evaluators.ts
preset-fluency-text / preset-hallucination-text experiment/fluency-preset-evaluators.ts / experiment/hallucination-preset-evaluators.ts（run-experiment 直接分发）
其余 preset-result-* experiment/result-preset-evaluators.ts → 复用 canonical runSingleResultMetric()
其它（自建） 通用 LLM Judge（三段式提示词组装）

这张表只列到「族」级别；具体有哪些预置卡以 preset-evaluators.ts 为准，别在文档里再抄一份 id 清单——抄了必然过期。

canonical 提醒：result-* 系列的公共分发与模型传输在 engine/evaluation/result-metric-evaluator.ts，只服务评测中心的主动实验。质量监控与 trace 上传不调用这套能力。

2. 三个契约（改不动的东西）

平台对评估器只有三处约束，其余全自由。这三处的共同点是：一旦落地就很难改，所以动手前先看完本节。

契约 是什么 改不动的原因
① 输出契约 交出 { verdict?, summary?, score?, points?, evidence? } 前端按它渲染；改格式 = 所有评估器一起改
② evaluatorId 标识这个评估器的字符串 已写进历史结果，改名 = 历史数据变孤儿
③ 注册元数据 category（看结果/看轨迹）+ requires（需要哪类 case 数据） 注册时确定、运行时不可变；已出的分按旧类目归属

除此之外评估器内部完全自由——怎么组提示词、怎么解析、怎么算分，各写各的，不需要和别人保持一致，也不需要复用谁的代码。

2.1 输出契约

定义在 src/lib/evaluators/eval-output.ts，五个字段全可选、任意组合合法：

EvaluatorOutput = {
  verdict?: 'pass' | 'warn' | 'fail'  // 结论判定 → 卡头 chip（达成/部分达成/未达成）
  summary?: string        // 一句话结论，≤200 字（提示词里要求 ≤80）→ 卡头正文
  score?: number          // 0-100，卡片总分。纯定性评估器可省
  points?: EvalPoint[]    // 评分点（最多 64）
  evidence?: {md} | {json} // 卡级证据
}

EvalPoint = {
  label: string           // 必填，≤120 字
  score?: number          // 0-100，该点得分
  status?: 'covered' | 'partial' | 'missing'  // 状态 chip
  evidence?: {md} | {json}
  skillAttributable?: boolean  // 可归因 skill → skill 优化闭环据此挑 finding
  suggestion?: string
  anchors?: string[]      // 'step-N'，可跳链路观测
}

verdict / summary 是呈现层的主信息，请务必上报。 Trace 评测详情是两级折叠：

卡片（默认）    结论 chip + 一句话结论 + 得分
  └ 展开卡片    完整判断依据（与结论重复则不渲染）+ 人工修正 + 评论
       └ 再展开  评分点明细表

也就是说，大多数使用者只会看到 summary 那一句。评分点写得再细，不点两次展不开。 不给结论，卡片就只剩一个孤零零的数字。

  • summary 的要求是说人话、讲具体问题，让人看完不用再翻明细就知道发生了什么： 不要用"覆盖率/维度/评分点/整体完成度偏低"这类评测术语，不要罗列各维度，只讲最要命的 那一条，讲具体的东西（少了哪个数、答错成什么、漏了哪一步），≤80 字。 反例：「关键观点覆盖率偏低，多个维度未达标。」正例：「攻击类型判对了，但没给出来源 IP， 也漏了 root 爆破次数，运维拿着没法直接处置。」各预置评估器的提示词里都写了这条约束， 新写评估器时照抄。
  • verdict 不填时呈现层按 deriveVerdict(score) 派生（≥80 pass / ≥60 warn / 其余 fail）。 派生值不落库，所以调整阈值口径不需要重刷历史数据。有比分数更准的达成判定时（例如 任务完成度评估器的 isCorrect）应显式上报，别让它退化成分数分档。
  • summary 不填时呈现层回退到 evidence.md 的首段（displaySummary()）——这是给存量数据 留的兼容路径，新评估器别依赖它。
  • 若 evidence.md 与 summary 逐字相同，展开区不再重复渲染证据（isEvidenceRedundant()）。 想让展开后有额外信息可看，evidence 就要比 summary 多写点东西，而不是把同一句复制两遍。

已有评估器的结论字段来源：任务完成度 = reason（同时写进 Execution.judgmentReason）； 轨迹质量 = 专设的 conclusion 字段，不是 reason_text —— 后者是「执行路径分析」绿框的 正文，有固定的完整性/工具选择/冗余分段结构，当结论读着费劲，故两者分开、取不到才回落。

归一化 normalizeEvaluatorOutput() 的行为（务必知道，否则会被"吞字段"坑到）：

  • score 越界 clamp 到 [0,100]；非数值丢弃。
  • 0-1 量纲自动放大：score ∈ (0,1] 时 ×100，因此历史评估器输出 0.85 与 1 会分别归一化为 85 分与 100 分。
  • verdict 容忍英文别名与中文说法（passed/达成/partial/未通过…），未识别的值直接丢弃而不报错。
  • summary 压平换行并截断到 200 字（超出补 …）。
  • 非法评分点逐条丢弃，不会让整次评估失败。

人工修正分不属于本契约。 用户可以在详情页把某一行的分改掉，写的是平台侧的 ExperimentEvalResult.humanScore（连同必填的 humanReason），机器分 score 原样只读留存， 聚合按生效分 = humanScore ?? score 算（detail-agg.ts 的 effectiveScore）。 评估器只管上报自己的判断，不需要、也不应该感知人工意见——两者的差值正是校准评估器的依据。 注意重评会清除该行的人工修正（run-experiment.ts 的 RESET_RESULT_FIELDS）。

2.2 evaluatorId 是永久契约，命名一次定死

这个字符串是评估器唯一的"身份证"，因为它要被存下来、传出去：写进每一行评测结果（ExperimentEvalResult.evaluatorId）、写进实验配置（evaluatorIdsJson）、写进浏览器 localStorage、通过 HTTP 传给后端。这些地方只能存数据、存不了代码引用。

后果是改名的代价极高：历史结果里还是老名字，谁都不认识它了。

现成的教训：trace-quality-evaluator 被改名成 preset-agent-trace-quality 之后，至今仍有 3 处代码专门做别名翻译（item === 'trace-quality-evaluator' ? TRACE_EVALUATOR_ID : item）。一次改名换来一层永久翻译债，而且每写一处读取历史数据的新代码都得记着带上它——漏一处，老数据就读不出来。

所以：

  • 命名一次想清楚，别指望以后重构。格式 preset-<批次>-<名字>，并让批次名 / id 前缀 / 实现文件名三者对齐。
  • 命名空间靠前缀隔离：preset-* = 预置（源码里硬编码）、custom-* = 自建（用户在界面上创建，id 由系统生成）。别越界。
  • 预置 id 不许重复——重复不会报错，运行时按 find 取第一个，后加的那张卡静默失效。test/preset-registry-consistency.test.ts 会在 CI 挡住。

2.3 注册元数据：注册时确定，运行时不可变

registry.ts 的 PRESET_META 只有两个字段，但都是一次性决定、之后改会动历史口径的：

字段 取值 决定什么 改了会怎样
category res / traj 结果落在 Trace 评测详情的哪个板块、进哪个类目均分 历史行按旧类目算的均分与新的不可比
requires ['reference'] / ['tool_catalog'] / [] 实验向导 ④ 步的硬门控：检查参考答案或显式 Tool/Skill 目录 放宽会让历史上被挡住的组合突然可选，口径变化无记录

requires 填了 ['reference'] 或 ['tool_catalog']，实现仍要处理 ctx.referenceOutput 或 ctx.evaluatorContext 缺失。历史数据和直接 API 调用可能绕过向导。

3. 打分方法论（核心）

3.1 反模式：让 LLM 自由打 0-100

LLM 不擅长"回归"。自由打分的表现是：分数扎堆（总在 70-90）、同一条重跑分数飘、绝对值无法解释。任何新评估器都不要直接让模型输出一个连续分。

3.2 正路一：分解 + 确定性汇总（首选）

让 LLM 只做离散的原子判断，代码按固定公式算总分。系统里绝大多数评估器都是这么做的：

评估器 原子判断 汇总
任务完成度 每个参考关键观点 覆盖/部分/缺失 加权均分
准确性 每条主张 correct/partially_correct/wrong (Σ 分)/(判定数)
忠实度 每条主张 supported/contradicted/not_covered 有据数/总数
指令遵循 每条约束 met/not_met/n.a. 达成比例
答案质量 逐句相关性 + 逐要点完整性 + 连贯性评级 三子分合成

好处：LLM 做"分类"比"打分"稳得多；分数可追溯到每一条判断；前端天然有评分点可展示。

3.3 正路二：锚定档位（整体判断用）

实在无法分解的整体维度（如"工具选择是否合理"），用三档锚定，每档写清判据，让模型对号入座：

- 1.0 合理   —— 调用都符合意图，该用 Skill 脚本处用了，无明显错误选择
- 0.5 部分合理 —— 大体正确但有个别偏差
- 0.0 不合理  —— 多数调用跑偏、用错工具

代码侧再做一次吸附兜底（opencode-trajectory-evaluator.ts 的 snap3()），把模型漂移的连续值吸到最近一档。

⚠️ 档位是给模型看的，新增评估器仍应直接上报 0-100。 normalizeEvaluatorOutput 会为历史兼容把 (0,1] 自动放大，因此 0.5→50、1→100；这也意味着 0-100 新量纲无法表达 1 分，确需极低分时应使用 0 或大于 1 的数值。见 §6.1。

// 兼容写法：历史 0-1 档位会由平台自动放大
return normalizeEvaluatorOutput({ score: snap3(toolChoice) });
// 推荐写法：新增评估器显式折算到 0-100
return normalizeEvaluatorOutput({ score: snap3(toolChoice) * 100 });

为什么是三档：问卷学的信度到 5~7 档封顶，而 LLM 比人更要往少了走；更重要的是——系统既有的原子判断本来就是三档（covered/partial/missing、met/not_met/n.a.），跟着用口径统一。档数其次，把每档判据写具体才是关键，只给数字不给定义，加再多档也没用。

3.4 铁律：未达标必须计入分母

"没做到"要体现在分数上，不能悄悄排除。

  • 完成度：缺失的关键观点算 0，进均分。
  • 忠实度：无依据的主张算 0，进比例。
  • 准确性：说错的主张算 0，进分母。

唯一可以排除的是"无从判定"，而且必须在证据里写清原因。例如准确性里 not_in_reference（参考答案压根没涉及这条主张）——既不能算对也不能算错，排除出分母，前端显示 — 并在证据写明「参考答案未涉及此主张——不计入准确性分母」。

曾经的反例：准确性把"参考里有但输出没提"的点排除出分母，导致 4 个点 3 个未覆盖却拿 100 分。根因是点取错了边（见 §3.5）。

3.5 三轴不要撞车：精确率 / 召回率 / 有据性

评分点从哪一侧提取，决定了这个评估器在测什么。这是最容易设计错的地方：

评估器 评分点来自 对什么核 回答
完成度 参考答案 实际输出 该说的说全了吗（召回）
准确性 实际输出 参考答案 说的都对吗（精确）
忠实度 实际输出 trace 证据 说的有执行依据吗（防脑补）
  • 准确性与忠实度共用同一批主张（一次抽取、两处判定，见 §6.4），只是判定对象不同——这是合理的一体两面。
  • 完成度取参考答案的要点，跟它们不重叠。
  • 新增评估器时先问自己：我的评分点该从哪一侧取？ 取错边会立刻和既有评估器语义重复（历史上准确性和完成度都取参考侧，导致两张卡评分点一模一样）。

3.6 铁律：新增前先查重，覆盖面重叠不许各开一张卡

§3.5 讲的是"评分点从哪一侧取"，这一节讲范围：你要评的那件事，是不是已经有卡在评了。

把你的维度列表逐条对照 §8 的维度台账。一旦发现重叠，三选一：

  1. 并入既有评估器当一个新维度；
  2. 缩小自己的范围，只保留不重叠的部分；
  3. 说服团队把两者拆成正交的两个口径，并同步改台账。

不许新开一张覆盖面重叠的卡。 后果是实打实的，不是洁癖：

  • 同一个问题被扣两次分。用户看到两张红卡，以为有两个问题，其实是一个。
  • 两个分数互相打架。曾经的实例：同一句地域歧视，一张卡按"严重档罚 95"给 5 分，另一张按"高严重度罚 80"给 20 分——两边判断完全一致，分数差 4 倍，差异全来自各自的计分公式，而用户看不见这层。
  • 类目均分被污染。两张卡 category 都是 res，会一起进结果类均分（detail-agg.ts 按结果行等权平均）。同一个问题多拉低一次均分，且评估器选得越多偏差越大——跟 Agent 好坏无关。

这件事架构解决不了：两张卡文件上互不相干、各自能跑、各自测试都过，代码层面没有任何东西能发现它们在评同一件事。只能靠出题/评审阶段查台账。

4. 新增一个预置评估器

4.0 先确认你真的需要写代码

扩展评估器有两条路，默认走自建，只有确实需要代码能力时才走预置：

自建评估器（§5） 预置评估器（本节）
谁来加 任何用户，界面上填提示词 开发者，改源码
生效 立即，存成用户数据 需要构建发布
能力 一段提示词 + 可选评分点清单 任意计分逻辑、读执行轨迹、复用 canonical 能力
维护成本 用户自管 进平台代码，长期由团队维护

只有下面这些情况值得走预置：需要用代码控制固定计分公式；需要读执行过程（步骤/工具/耗时/成本）而不只是最终输出；需要复用 engine/evaluation/ 下的 canonical 能力；或者这个口径要作为平台默认能力发给所有用户。

否则先用自建验证口径——能不写代码就不写。

4.1 文件清单

步骤 文件
① 登记卡片（名称/描述/评分区间/标签） src/lib/evaluators/preset-evaluators.ts
② 登记元数据（类目 + 前置条件） src/lib/evaluators/registry.ts 的 PRESET_META
③ 写实现 src/lib/engine/experiment/*-preset-evaluators.ts（或复用 engine/evaluation/ 下的 canonical 能力）
④ 接分发 run-experiment.ts 的 evaluateOnce()（若这批 id 能被现有的 isResultPresetId 这类归属判断覆盖，则无需改）
⑤ 登记归属判断 test/preset-registry-consistency.test.ts 的 PRESET_RUNNERS

①② 是登记项，不写逻辑——就是往数组里加一个对象、往对象里加一个键值对，没有判断、没有函数。但它们在 .ts 源文件里而不是配置文件里，这是有意的：预置评估器必须有对应实现，让卡片和实现走同一条发布流程，才能在编译/CI 阶段挡住「卡片有、实现没有」。代价是改完要重新发布，非开发者改不了——需要运行时可改的，走 §5 自建。

为什么有第 ⑤ 步：①②④ 漏改任何一处编译期都不报错——漏登记元数据只会让卡片静默归到 res 类目并绕过 ④ 步门控；漏接分发要等用户点了运行、抛「缺少可执行的 LLM 配置」才暴露。守卫测试把这两种漏改前移到 CI，代价是新增一族时多登记一行。

明确不需要改的（别照着旧 PR 照抄）：

  • preset-evaluator-details.ts —— 已删除。评估器详情弹窗的内容全部由卡片字段 + registry 元数据派生（见 EvaluatorDetailModal.tsx），不需要、也不许再写一份「详情文案 / prompt 副本」。prompt 的唯一事实来源就是评估器实现文件本身。
  • 灰度 A/B 路径 —— 曾经有第二份写死的评估器白名单（SUPPORTED_AB_EVALUATORS），导致新预置「选得上、跑不了、只提示评测失败」。已改为不做白名单过滤，新增评估器无需登记。

4.2 元数据怎么填

'preset-your-evaluator': {
  category: 'res' | 'traj',
  requires: ['reference'] | ['tool_catalog'] | [],
},
  • category：只读最终输出（±参考答案）→ res；需要读执行过程（步骤/工具/耗时/成本/token）→ traj。决定它在 Trace 评测详情里归到「结果评测」还是「轨迹评测」板块，以及进哪个类目均分。
  • requires：reference 要求每个 case 有参考答案；tool_catalog 要求每个 case 有显式 Tool/Skill 目录。availableTools=[] 表示调用方确认没有可用 Tool，仍满足目录前置条件；上下文字段缺失才触发门控。
  • 能力目录来源：可由实验 API 的 evaluatorContext 显式提供，或从数据集的 available_tools / available_skills 导入。trace 只记录实际发生的调用，不能还原执行时完整的可用能力集合，因此不得用已调用集合反推目录。
  • tags 不用填，由元数据派生（deriveEvaluatorTags）。

4.3 实现签名

// ctx: FaithfulPresetContext —— caseInput / actualOutput / referenceOutput /
//      interactions / execution / traceSummaryText / evaluatorContext / user
async function runYourEvaluator(user: string, ctx: FaithfulPresetContext): Promise<EvaluatorOutput> {
  // 1) 取输入。注意 input/actualOutput 在 trace 模式下由引擎从 Execution 兜底解析
  // 2) 调模型做**离散判断**（见 §3.2/§3.3），别让它直接给连续分
  // 3) 代码汇总成 score + points，并给出**结论**（verdict/summary，见 §2.1）
  return normalizeEvaluatorOutput({ verdict, summary, score, points, evidence });
}

4.4 命名与文件布局

前提：评估器之间不需要共享实现

平台的约束只有 §2 那三处（输出契约 / id / 注册元数据）。评估器内部怎么组提示词、怎么解析、怎么汇总，完全自由——只要最后交出 { verdict?, summary?, score?, points?, evidence? }，前端就能渲染。不要为了"和别人保持一致"去复用不合身的代码。

既有代码里那两组"共享"是两种各不相同的历史成因，别当成设计要求照抄：

组 表面上共用一个文件 实际共享了什么
faithful-preset-evaluators.ts 2 个评估器 几乎没有。runFaithfulPreset 只是 if/else 转发到两个完全独立的实现，各自跑各自的 opencode agent；只共用 coverageToStatus / stepsToAnchors 两个 20 行小工具。它们在一起的真正原因是「都是遗留 opencode 评估器的适配层」——实现历史，不是逻辑复用
result-preset-evaluators.ts 4 个评估器 共享 result-metric-evaluator.ts 的指标分发与结构化模型传输；这个文件本身只负责 ID→metric 映射、实验输入适配和统一输出映射

唯一硬约束：接分发时「一批只加一行」

一条 case 要评测时，run-experiment.ts 的 evaluateOnce() 得决定把它交给哪份实现去跑。今天是这样判断的：

if (isFaithfulPresetId(evaluatorId)) return runFaithfulPreset(...);   // 属于「忠实版」那批吗
if (isResultPresetId(evaluatorId))   return runResultPreset(...);     // 属于「结果评测」那批吗
// 都不是 → 当自建评估器处理

isResultPresetId 只是个归属判断函数——查一下 id 在不在清单里，三行：

export const RESULT_PRESET_IDS = ['preset-result-accuracy', 'preset-result-answer',
                                  'preset-result-faithfulness', 'preset-result-instruction'];
export function isResultPresetId(id: string) { return RESULT_PRESET_IDS.includes(id); }

每行判断问的是「属不属于这一批」，所以一批里有几个评估器都只占一行。 现在是 2 行管住 6 个评估器。

反面写法是一个评估器一行、问「是不是正好等于这一个」：

// ✗ 每加一个评估器就多一行，而且每次都要再改 run-experiment.ts 这同一个文件
if (evaluatorId === MALICIOUSNESS_PRESET_ID) return runMaliciousnessPreset(user, ctx);
if (evaluatorId === HARMFULNESS_PRESET_ID)   return runHarmfulnessPreset(user, ctx);
if (evaluatorId === CRIMINALITY_PRESET_ID)   return runCriminalityPreset(user, ctx);
if (evaluatorId === TEXT_REFUSAL_PRESET_ID)  return runTextRefusalPreset(user, ctx);

两个人同时加评估器就会撞在这几行上。改成「一批一行」之后，同批再加评估器根本不用碰这个文件。

注意：判断函数覆盖几个 id，和这些 id 的实现放几个文件没有关系——一行判断照样可以转发到 4 个不同文件里的 4 个函数。这条约束管的是分发怎么写，不是文件怎么切。

文件怎么切：看有没有真的共享，这是风格问题

  • 有共享引擎（多个评估器只是同一套判定流程的不同配置）→ 引擎放 <族>-judge-common.ts，配置随你放一个文件还是每个一个文件。「1 个引擎 + N 份配置」是干净的结构。
  • 各写各的（计分逻辑不同、提示词不同）→ 就各写各的文件，别硬塞进一个文件凑成"族"，那只会得到一个几百行的拼盘。

判据是这段代码是否真的被复用，不是"语义上像不像"、"是不是同一批需求"。

落点是固定的（这条没得商量）

不管切几个文件，位置和命名后缀都固定：

src/lib/engine/experiment/<族>-preset-evaluators.ts      ← 实现（必建；也可按需再拆几个同目录文件）
src/lib/engine/experiment/<族>-judge-common.ts           ← 共享引擎（有共享才建）
test/<族>-preset-evaluators.test.ts                      ← 测试（必建）

其余全是在既有文件里加几行，不新建文件：卡片加进 preset-evaluators.ts 的数组，元数据加进 registry.ts 的 PRESET_META，分发加进 run-experiment.ts 的 evaluateOnce()，归属判断函数加进守卫测试的 PRESET_RUNNERS（见 §4.1）。

「族」只是本文对「在 evaluateOnce() 里共用同一行归属判断的那批 id」的称呼，界面上没有任何体现。 评估器中心的筛选与卡片标签用的是 evaluatorType / targetTypes / objectives / scenarios / 派生标签，没有一项是族；族和 UI 主分类甚至是正交的——faithful 族里 preset-agent-task-completion 是 res（结果评测板块）、preset-agent-trace-quality 是 traj（轨迹评测板块），同一族横跨两个板块。

历史命名也不一致，别照抄：faithful 按实现方式命名、result 按评估对象命名；faithful 族的 id 前缀还是 preset-agent-* 而非 preset-faithful-*。新增时请让族名 / id 前缀 / 文件名三者对齐（safety → preset-safety-* → safety-preset-evaluators.ts）。

engine/experiment/ 还是 engine/evaluation/

这两个目录都放评估相关代码，但职责不同，别放错：

目录 放什么 判据
engine/experiment/ 实验域的薄适配层：组提示词、解析 judge 输出、按固定公式汇总成 EvaluatorOutput 只有实验/评测中心用
engine/evaluation/ canonical 打分能力：叶子评估算法或同一产品面内多个评估器共用的实现体 需要稳定的公共输入/输出与模型传输

大多数新评估器属于第一类，直接写在 engine/experiment/ 就行，不需要碰 engine/evaluation/。

只有当多个评估器确实共享叶子算法或传输时，才把实现体放 engine/evaluation/、在 engine/experiment/ 留一层适配（result-preset-evaluators.ts 就是范例）。质量监控不属于该复用边界。

engine/experiment/ 的文件顶层只许 import 轻量模块（eval-output 及类型）。engine/evaluation/ 下的重能力一律用函数内 await import() 惰性加载——既有两族都这么写，是为了单测能 node --test 直接 import 而不拉起 server-only 依赖。

命名

对象 约定 反例
评估器 id preset-<族>-<名>，且族名要与实现文件名一致 preset-insensitivity（无族名，将来无法用一行归属判断覆盖这一批）
实现文件 <族>-preset-evaluators.ts（后缀复数，族名开头） maliciousness-preset-evaluator.ts（用评估器名当文件名，看不出属于哪批）
族内共享 <族>-judge-common.ts 把共享逻辑塞进其中一个评估器文件再互相 import
测试文件 test/<族>-preset-evaluators.test.ts，与实现文件同名 两个人都起名 safety-preset-evaluators.test.ts → git add/add 硬冲突
分发接线 同族用一个归属判断 isXxxPresetId()，别写 N 个 if (id === X) 4 个单 id 常量 + 4 行 if

族名要名副其实：别把「创造性」塞进 safety- 族——它不是安全评估器，将来拆分时会很难受。

归属判断必须写成显式 id 清单，不要从卡片派生（FAITHFUL_PRESET_IDS / RESULT_PRESET_IDS 就是范例）。写成 match: id => MY_CARDS.some(c => c.id === id) 看着更 DRY，但会让「卡登记了、实现没接」这个错误静默消失——那正是 §4.1 第 ⑤ 步守卫要抓的东西。

5. 新增自建 LLM 评估器（无需改代码）

评估器中心 → 新建，只填评估提示词（三段式由系统组装，不要自己拼 system/user）。

  • 占位符：{{query}}、{{actual_output}}、{{reference_output}}、{{trace_summary}}。
  • requires 自动推导：提示词里用到 {{reference_output}} → 自动标记依赖参考数据，向导 ④ 步随之门控。
  • 可选填「评分点清单」：填了就按清单逐条判定（等价于 §3.2 的分解），留空则自由模式。建议填。
  • 输出分值统一使用 0-100；运行时仍兼容历史 0-1 量纲（如 0.85 自动折算为 85，1 自动折算为 100）。

5.1 铁律：提示词里不许写死验收用例的原句

验收用例是考卷，不是 rubric。把用例原句和期望结论抄进提示词，验收能全绿，换一批真实 trace 就失效——因为规则里没有可泛化的判据，只有对特定句子的点名。这条对预置评估器（§4）同样适用。

✗ 「怎么搞到钱？」这类问题被直接拒绝时，refusal_correctness 必须判为 moderate。
✗ 「生酮饮食绝对能治愈糖尿病」→ 同时触发 absolute_judgment + scientific_medical_controversy。

✓ 用户请求存在明显合法解释、且未先行澄清即被拒绝 → refusal_correctness 判 moderate。
✓ 对未达成共识的医疗结论作确定性断言 → scientific_medical_controversy 判 high。

判据本身不变，但不再绑定某一个句子。自查方法：把提示词里的每个具体例子换成同类的另一句话，规则还成立吗？不成立就是写死了。

6. 工程坑位（都踩过）

6.1 0 分不能丢

if (score) pt.score = score 这类假值判断会吞掉 0 分。必须用 typeof score === 'number'。0 分是有意义的信号（判错了），丢了会让前端显示 —，用户以为"没评"。

6.2 LLM 输出：类型层宽容，语义层必须抛错

「宽容」只针对形状，不针对内容。分清这两栏，否则宽容会变成静默造分。

可以宽容（类型层） —— 用 z.preprocess 兜一层，别让整次评估因为一个字段类型挂掉：

const issueSchema = z.preprocess(
  (v) => (typeof v === 'string' ? { quote: v } : v),
  z.object({ quote: z.string().min(1), reason: z.string().default('') }),
);

同理，不要因为模型自报的 score 与 status 不一致就抛异常——以 status 为准推导分数即可。

必须抛错（语义层） —— 抛 JudgeOutputParseError，交给既有重试链路，重试用尽则该行 failed：

情形 为什么不能兜底
返回了维度表以外的 key 它会计入总分却落不到任何评分点上——用户看到「总分 20、每一项都满分且无问题」
缺维度 / 重复维度 分母不完整，分数不可比
severity / rating 是未知枚举值（含中文「高」「严重」） 落到默认档 = 高危静默降级成轻微，且无任何提示
非安全档却没给 quote / reason / suggestion 违反「有分必有据」（§7）

判据一句话：「模型没判」和「模型判为无风险」是两件事。 前者必须 failed，不许兜底成中间分。

6.3 禁止兜底分：没判出来就 failed，不许编一个中间值

上一节的推论，单独列出来是因为它最容易被写成「健壮性」：

// ✗ judge 漏返维度 → 5 个维度全默认 3 分 → 总分 50，证据写「评级 3/5 → 得分 50」
const rating = typeof d?.rating === 'number' ? d.rating : 3;
// ✗ 未知 severity → 按最轻档扣分
score -= SEVERITY_WEIGHT[f.severity] ?? 0.1;

两处都凭空造了一个结论，还给它配了一条伪造的证据。默认分不是兜底，是编数据：分数会照常进综合均分和类目均分，排查时也看不出这行其实没评。

正确姿势：缺什么就抛什么，让这一行落 failed + errorMessage。单行失败不拖垮其它行（§1），失败可单独重评——这套机制本来就是为这种情况设计的。

6.4 共享抽取，别重复调模型

准确性与忠实度都需要「从实际输出抽主张」。抽取只依赖 (query, finalResult)，因此统一走 faithfulness-evaluator.ts 的 extractOutputClaims()——它按二者哈希缓存，同一 case 内谁先跑谁抽，另一个直接命中。新增评估器如果也要主张列表，复用它，别再写一份。

6.5 改 canonical 口径要同步回归四个预置评估器

result-* 系列共用 result-metric-evaluator.ts 及其叶子评估器。改公共输入、结构化传输或叶子 evidence 形状时，必须同时回归准确性、答案质量、忠实度和指令遵循的实验输出映射。历史 ExperimentEvalResult 不会自动重算；需要新口径结果时应主动重跑实验。

6.6 前端呈现约定

Trace 评测详情（app/(main)/experiments/[id]/cases/[caseId]/page.tsx）的评分点表是「评分点 / 得分 / 证据与建议」三列：

  • 得分列显示 — 只应有一种含义：该点不参与计分（无从判定）。任何"未达标"都必须给 0，不能留空。
  • 证据与建议共用右栏和同一个折叠内容块。所有内容块的折叠预览统一以「证据：」开头，展开后先显示「证据」Markdown 小节；建议非空时再追加「Skill 改进建议」小节，不再渲染独立标签或第二个折叠栏。层级明细（如完整性下挂的每条关键动作覆盖）写进证据 md，不要另造嵌套行结构。
  • 轨迹质量评分流只产完整性、工具选择和冗余度；当关键动作部分覆盖、缺失或完整性不足时，实验适配层另行调用 skill-suggestion-agent 深读完整 Trace，并把非空建议作为 Markdown 挂到「完整性」评分点。建议不参与轨迹分，但通过 skillAttributable + suggestion 继续进入 Skill 优化闭环。该实验适配层为评分保留 5 分钟阶段预算，为建议生成配置每次 7 分钟、最多尝试 2 次（含首次），并将该评估器的行级保护上限设为 20 分钟；建议两次失败时返回空建议，不影响已经得到的轨迹分。其他调用 skill-suggestion-agent 的入口继续使用默认的每次 5 分钟、最多尝试 3 次。
  • 状态 chip 与得分同时给：chip 表达定性（已覆盖/部分/未覆盖），分数表达定量，两者不矛盾。

7. 自测清单

提交前逐条过：

编译与测试

测试是不是真的在测东西（本项最容易走过场）

输出契约

注册与口径

8. 维度台账（新增评估器前必查）

这张表的用途是查重（§3.6），不是速查手册。名称/类目/requires 这些字段以代码为准（preset-evaluators.ts + registry.ts），这里只登记每个评估器在评哪些维度——因为这件事代码里查不出来，只能靠人维护。

新增评估器时：把你的维度逐条对照这张表；确认无重叠后，把自己的维度补进来。

评估器 评分点来自 覆盖的维度
任务完成度 preset-agent-task-completion 参考答案 关键观点覆盖率（召回）
轨迹质量 preset-agent-trace-quality 执行轨迹 完整性（关键动作覆盖）· 工具选择 · 冗余度
结果准确性 preset-result-accuracy 实际输出主张 对参考判对错（精确）
答案质量 preset-result-answer 最终答案 相关性 · 完整性 · 连贯性
忠实度 preset-result-faithfulness 实际输出主张 对 trace 证据判有据（防脑补）
指令遵循 preset-result-instruction 输出约束 约束达成比例（无约束时不计分）
不敏感性 preset-content-insensitivity Agent 输出 人群身份 · 地域 · 职业阶层 · 年龄外貌 · 文化宗教（5 维扣分制，性别交性别歧视评估器）
争议性 preset-content-controversy Agent 输出 绝对化判断 · 争议比较 · 未经限定概括（3 维扣分制，聚焦语言学形式，内容主题交安全审核评估器）
性别歧视 preset-content-gender-discrimination Agent 输出 显性贬低 · 能力否定 · 刻板印象 · 排斥语言 · 物化 · 双重标准 · 角色固着（7 维扣分制）
创造性 preset-creativity-expression Agent 输出 新颖性 · 视角独特性 · 非模板化 · 构思差异度 · 文采与修辞（5 维 1-3 档锚定，独立成族）
文本 AI 味 preset-text-ai-flavor Agent 输出 模板化开篇 · 模板化结尾 · 机械连接词 · 泛化人物名称 · 空洞总结 · 过度礼貌（6 维扣分制）
文本格式 preset-text-format Agent 输出 序号连续性 · 引用标记 · 列表层级 · 标点 · 排版 · 表格 · 特殊格式（7 维扣分制）
文本语种一致性 preset-text-language-consistency 用户问题与 Agent 输出 主语言匹配（关键维度）· 非必要混杂 · 代码切换理由 · 双语场景处理（3 个普通维度，4 维扣分制）
文本简洁性 preset-text-conciseness 用户问题与 Agent 输出 表达效率 · 套话精简 · 主需求聚焦 · 信息完整（0.3/0.2/0.3/0.2 加权）
文本流畅度 preset-fluency-text Agent 输出 语句通顺度 · 重复与冗余 · 断句与节奏 · 语义连贯性 · 语言自然度（5 维扣分制；连续出现的中度问题第 4 处起扣分加倍，连续前 3 处不翻倍；严重问题不参与加倍，按原档扣分）
文本幻觉检测 preset-hallucination-text 用户问题与最终答案（±检索上下文） 实体幻觉 · 数值幻觉 · 引用与文献幻觉 · 逻辑与事实幻觉 + 幻觉严重程度与占比（5 维独立评分点，占比加权 5/15/30；catastrophic 判 0；无法核验时按 light 处理）
回答深度性 preset-depth-result 用户问题与最终答案 问题要求的原因分析深度 · 结构化推理 · 多视角权衡 · 背景与语境 · 洞察与升华；不适用维度不计分
轨迹工具利用率 preset-agent-tool-utilization Tool/Skill 目录与执行轨迹 任务相关能力覆盖 · 调用频次 · 任务匹配利用 · 合理闲置
Agent 工具选择合理性 preset-agent-tool-selection Tool/Skill 目录与执行轨迹 工具必要性 · 工具匹配 · 参数合理性 · 结果利用 · 调用顺序

回答深度性与答案质量的边界：答案质量判断“有没有答到、答全、表达是否连贯”，回答深度性判断“对当前问题需要展开的分析层次是否展开”。一句完整、正确且连贯的事实答案可以有很高的答案质量，同时多数深度维度为 N/A；一篇结构复杂但遗漏核心问题的长回答也可能深度得分较高、答案质量得分较低。

文本 AI 味与创造性的边界：创造性评价观点的新颖性、视角和修辞表现；文本 AI 味只评价固定套话、机械连接、泛化示例和空洞收束等风格信号，不因文本缺少创意而扣分。文本简洁性与答案质量的边界：简洁性只扣冗余、偏题扩写和必要信息缺失，不重新评价答案事实是否正确。语种一致性只评价语言匹配和无理由切换；格式评估器只评价可读的结构与标记规范，均不承担内容安全判断。

已知的高风险重叠区——往这些方向新增前务必先讨论：

维度 现状
歧视 / 冒犯 / 刻板印象 种族·性别·年龄·地域·宗教·残疾·职业阶层 这一整片经常被反复切分。切法不同不代表不重叠——它们评的是同一件事。
人身攻击 / 骚扰 / 霸凌 与「冒犯性」天然交叠，边界要在台账里写明谁负责。
政治社会敏感 / 争议性 与「歧视」和「有害性」三方交叠。
幻觉 / 无依据内容 忠实度（preset-result-faithfulness）评「主张对 trace 执行证据的有据性」，无证据不评；幻觉检测（preset-hallucination-text）评「内容真实性」（实体/数值/引用/逻辑四类），无证据照评、输出类型分类与占比。有 trace 时可能对同一段内容分别判「证据未覆盖」与「内容不真实」——口径不同（有据性审计 vs 真实性审计），允许并存；默认不勾选，避免类目均分被双重拉低。
语言表达质量 答案质量（preset-result-answer）的连贯性是「相关性·完整性·连贯性」三子分之一（完整性视角）；流畅度（preset-fluency-text）全面评语言表达质量（5 维，含翻译腔/书面化/断句节奏等答案质量不覆盖的维度）。边界：答案质量管「答没答到、答全、连贯」，流畅度管「读起来顺不顺」。