mini-openclaw-v2/docs/v2/11-judgment-providers.md

可切换专项判断模块：Jev / 本地开源模型

日期：2026-09-28。状态：用户已明确可切换方向；本文件为工程设计候选，代码、配置加载和真实模型接入均未实现。对应 FR-JUD-01、BR-17–20、AC-17–21，并沿用 BR-05/09/12/13/16。

1. 产品职责与选择

模块负责回答“现有证据是否支持某个具体判断”，例如“提供的回款材料是否足以支持账期延长的解释”。输入同一套问题、经验适用条件、评价标准和证据；输出可被主审消费的结构化专项判断。历史经验归平台管理，不存成某一家模型的专有资产。

模式	实际执行方	凭据要求	对主审的作用
jev	Jev 官方服务，通过专用适配器	有效 Jev 凭据及数据出口授权	提供局部判断，按统一契约返回
local	客户/开发环境部署的开源模型推理服务，通过本地适配器	无需 Jev Key；本地服务自己的认证按部署设置	执行同一业务任务，按统一契约返回
disabled	不执行专项模型调用	无需专项模型凭据	主审继续使用规则、工具和经验，标明专项核查未完成

默认关闭；有已验证的本地配置后，可显式选择或将其设为默认。不得因为缺少 Jev Key 阻止整个服务启动。此处关闭只关闭专项模块，主审自身仍需独立的可用模型配置。

本地方案替代的是专项模块的业务职责，不是复制 Jev 权重、训练方法或原生概率能力。不承诺两者逐题同答、评分相等或准确率相等；这些必须通过相同样本上的独立测评证明。Jev 是否支持私有化不在本设计假设内。

2. 架构与唯一职责

目标调用链（未实现）：主审提出具体问题 → 统一判断入口 → 配置/题型/数据出口检查 → 所选适配器 → 输出归一化与证据校验 → 主审综合意见 → 硬规则与完整性校验。

• backend/contracts/prescreen.py 拟定义共享题目、请求和结果；前端不得依赖厂商响应。
• backend/services/judgment_provider.py 拟负责路由、预算与归一化；Jev/local 各有专用适配实现，落点在 M3 按模块大小拆分，避免再造通用插件平台。
• 主审拥有整体研判；适配器没有写 recommendation 或审批状态的权限。
• 经验检索、证据来源、确定性计算和硬规则沿用平台能力，不因更换专项模型更换一套。
• 输出解释由主审结合经核验的证据形成，不假设供应商必定返回理由或可靠引用。本地模型生成的文字也不自动当作证据。

问题示例：题型 choice；选项 supported / contradicted / insufficient；要求只判断“材料是否支持所述解释”。这三个选项不是项目的通过/否决/补件状态。同一题目可由所选 Jev 或 local 执行，日常运行只调用选中的提供方；综合结论仍由主审形成。

3. 配置契约与运行选择

JudgmentProfile 由管理员在后端部署配置维护：

字段	类型 / 约束
id / revision	非空字符串1–128字符 / 正整数；修改生成新修订
display_name	非空字符串1–100字符
provider	jev / local；disabled 不需要配置对象
endpoint_ref	后端已批准端点引用，不能由业务请求指定 URL
credential_ref	可空密钥引用；jev 必需，local 按服务认证要求；不保存密钥值
model_version / adapter_version / prompt_version / mapping_version	非空版本标识；无自定义提示的适配填 not_applicable；若厂商无不可变模型修订则标 unresolved，不宣称可精确回放，生产启用前解决
capabilities	choice / score / binary 的非空子集，表示已通过该配置验收的题型
allowed_data_domains	demo / production 的非空子集，另叠加项目和调用者权限
readiness	ready / unavailable；仅验证通过且配置完整者可为 ready

P0 不提供在线修改配置接口。候选只读接口 GET /api/prescreen/projects/{project_id}/judgment-profiles 返回 {profiles:[{id,revision,display_name,provider,capabilities}],default_profile_id:string?}；只列对当前项目、调用者和数据域已获准且 ready 的配置，返回默认值也须通过相同过滤。无可用配置返回空列表和 null；不返回端点或凭据。项目无访问权限沿用 404 NOT_FOUND。

运行请求沿用 enable_judgment:boolean=false，新增 judgment_profile_id:string?：

1. 开关 false 且 ID 为空：冻结 provider=disabled，其余配置版本为空；不访问任一专项服务。开关 false 同时传 ID 属于 E-07 INVALID_REQUEST，避免静默忽略选择。
2. 开关 true：有 ID 使用指定的当前修订；无 ID 则解析后台默认。不存在/未获准/不可用/没有默认均返回 E-13，不静默关闭。服务启动不校验未选中的 Jev 密钥。
3. 入队前冻结配置修订和模型/适配/提示/映射版本，返回 ScreeningRun.judgment_config。幂等重放返回原运行，即使默认配置已变化也不重新解析。
4. 队列执行与每次发送前仍校验当前授权和撤销状态。冻结版本不赋予永久外发权限；版本被禁用/凭据被撤销则记 E-06，出口被撤销记 E-10；不改用新版本或其他提供方。
5. 配置切换须创建新运行；旧运行保持原记录。预算耗尽、限流或故障按详细设计重试上限处理，不做自动跨提供方回退。

4. 统一问题与请求

拟内部接口 judge(request: JudgmentRequest, frozen_profile: JudgmentProfile) -> Judgment；异常由统一入口转为约定错误，厂商原始异常不能直接返回浏览器。

JudgmentRequest：run_id、snapshot_id、question_id、question_version（共同 ID 约束），type:choice/score/binary，question:string[1..2000]，criteria:string[1..4000]，evidence_ids:string[0..20]，options:string[]，score_range:{min:number,max:number}?。调用者提交引用，后端从冻结授权快照提取对应证据文本，用户不能用 ID 夹带其他项目片段。

choice 要求 options 为2–20个唯一非空选项（各1–100字符）；score 要求有限 min<max、options为空；binary 要求两者为空。题目版本一经冻结不变；适配器可以转格式，但不能更换业务问题、证据、等级定义或增减事实。证据为空按缺证处理，不请求模型，返回 completed+unknown，并保留缺证原因；不把材料缺失解释为不支持。

本地适配器采用所选服务已经验证支持的结构化输出方法，随后进行服务端严格校验；不能依赖“请返回 JSON”的提示就宣称有结构保证。不能支持所需题型时 E-14，畸形输出 E-15；不让主审悄悄猜一个分数补齐。

5. 统一答案与供应商差异

JudgmentAnswer 使用可辨识联合：

kind	字段	校验
choice	value:string	必须属于该题冻结 options
score	value:number	有限数值，且在该题 score_range 内
binary	value:boolean	仅表达该题命题是否得到支持，不表示审批通过
unknown	reason_code:missing_evidence/inconclusive	明确无法判断，不强制选择肯定或否定

正常答案 kind 与题型一致，unknown 对所有题型有效。结果字段见 详细设计：completed 必须有合法 answer；failed/skipped 的 answer 必须为 null；failed 必须有 error_code，skipped 必须有 skip_reason（disabled/not_configured/not_authorized/unsupported）。例如能力缺失为 skipped+unsupported，并附 E-14；传输/输出错误为 failed，分别 E-06/E-15。关闭时已计划的题目可记 skipped+disabled；无计划题目时运行级保留关闭标识及降级说明，不制造题目。状态成功不等于业务通过。

evidence_ids 保存进入该判断的授权证据范围；它不证明模型真的使用或正确理解了证据。新增引用需再校验，主审仍逐项检查是否支持意见。

NativeMetric：name:string、value:number（有限值）、semantics:string（非空）、source:provider_native/self_reported。native_metrics 可为空；范围校验根据版本化适配规范，禁止把缺失值填0或1。它只用于审计/独立评测，不成为通用置信阈值或审批概率。

Jev 专有 Choice/Score/Noul 等响应只在适配器内部处理，具体厂商 schema 在真实接入前依据官方版本确认。若某题由原生连续输出转为 binary，须有该模型/题型独立验证过的映射和拒答区间；未验证就不声明 binary 能力，不默认套用0.5阈值。原始供应商指标仅保留原语义，不为 local 捏造同名概率。

本地模型可返回 choice/score/binary/unknown；没有原生概率就返回空指标。模型自己写的“置信度90%”即使记录也只能标 self_reported，不作为已校准概率。两类模型的原生指标都不能改写 ScreeningRun.probability；P0 仍为 null。

6. 失败边界与回滚

配置拒绝 E-13 发生在创建运行之前；运行中能力不支持 E-14、输出非法 E-15、调用故障 E-06、外发禁止 E-10、预算耗尽 E-08 均有可见记录。相关题目未完成时保留其他结果；关键依据缺失则依主审完整性规则给补件/信息不足，不能默认推进。

默认配置切回旧修订只影响未来新运行；持久化的运行配置与判断字段通过追加迁移引入。DDL 在 M1 定案，不覆盖旧对象或当前生产库。外部模型权重、密钥、原始材料不作为 Git 备份内容。

7. 验收与交付范围

AC-17：同题/同证据，两适配器输出可被同一主审契约消费；local 在无 Jev Key 的环境实际运行，调用记录无 Jev 请求。 AC-18：畸形值拒绝；指标保留原语义；local 自评分不成为审批概率；无证据与合理拒答返回 unknown。 AC-19：配置权限、禁用状态、能力缺失和出口撤销均有反例测试；不外发未批准材料。 AC-20：排队后切换默认不会改变该运行；重试不改提供方，幂等重放不改配置。 AC-21：两种服务均不可用时仍可关闭专项模块运行主审，结果明确限制。

业务效果验收使用同一冻结样本集和专家标准，分别统计两种模式的漏检、误报、无依据结论、拒答率、时延和成本。契约兼容不代表模型能力等价；验收合格才能将对应配置标为 ready。Jev 没有 Key 时其 live 测试标未验证，不阻塞已经通过验证的 local 模式。

本地具体模型、硬件和服务协议仍属于 OQ-03/04，接入前选择并验证；没有真实历史数据时只报告演示和合成用例结果。当前交付仅为设计，后续按 M3 落代码、测试与配置模板。

8. Laya 候选与按任务替换（2026-09-29）

用户已同意专项能力可替换、本地路径优先验证的方向。候选为 NandhaKishorM/laya，官方仓库提供本地推理和HTTP服务。Jev 的有界题型参考 TypeSafe 官方介绍。以上外部事实于2026-09-29查阅，实施时固定实际代码/权重修订并重新核验。

Laya 官方限制说明：基础模型在部分决策任务上需要领域适配；多语言概率不能视为已在兴邦校准；它的 confidence 与 Jev 定义不同。还存在上下文/选项预算及否定表述风险。因此“接口兼容”“本地可启动”“中文金租效果合格”是三项独立验收。不得复制宣传时延、把英文专项模型成绩推广为中文能力。官方限制

8.1 配置拆分与职责

保留现有 provider=jev/local/disabled 业务契约，不新增 Laya 业务卡片。local 表示受管本地服务，实际实现由以下配置描述；mock仅测试/演示fixture，不列入production可用模型。

新增字段（JudgmentProfile）	类型 / 语义
engine	jev_api/laya/structured_llm；与provider一致性校验
checkpoint_ref	string?；local模型必须固定权重修订与校验摘要；远程不可变版本不可得则unresolved
tokenizer_revision / runtime_revision	string；无独立tokenizer则not_applicable；用于复现与预算计算
evidence_selector_version	string；冻结取证/分段规则，不允许暗改证据来“提升”结果
task_validations	{task,rubric_version,dataset_ref,report_ref,decision:passed/failed/unverified,allowed_usage:offline/shadow/runtime}[]
task	extraction_grounding/experience_applicability/trajectory_quality/evidence_support，以上task字段的枚举
calibration_ref	string?；属于专项判断校准，绝不是项目通过概率校准
input_token_limit / option_token_limit	positive int；以选定模型和实测预算配置，不能照搬另一模型默认值
language_scope	string[]；如zh-CN，仅在对应语料验收后声明
deployment_mode	managed_local/approved_remote；与端点及数据策略校验，local不自动获得生产数据权限

JudgmentRequest增加task、rubric_version、usage:offline/shadow/runtime；Judgment增加task、rubric_version、actual_checkpoint_ref:string?、input_digest:string、evidence_selector_version:string及运行实际版本记录。profile.capabilities验证题型，task_validations验证业务任务和用途，两者都通过才可执行；服务连通只能影响健康状态，不等于task合格。

任务与配置的绑定由管理员维护，业务人员装配方案并查看专项核查状态；授权高级选项可沿原设计显式选择已批准profile。未指定则使用方案冻结绑定。最终生效配置在入队时保存；任意一项越权、被撤销或不匹配均按E-13/14/15处理，不悄悄替换。

8.2 独立服务部署候选

Laya使用独立模型服务进程/容器与独立依赖环境，不将重型推理依赖直接安装进旧版backend/venv。项目后端及其测试仍用项目venv；模型服务环境属于新增独立服务，需另有锁定依赖与部署验收。P0先由内部HTTP适配器调用，不为此引入完整插件市场或新编排框架。

首次加载所需权重先在获准环境准备，记录模型许可/代码修订/权重摘要。离线验收断网验证预加载、重启恢复和零外发；不能因供应商称“本地模型”就承诺全产品离线，主审模型仍有独立出口。

使用明确checkpoint，禁用自动按语言更换权重的隐式路由；若未来需要路由，整个路由规则及各权重都需版本化单独验收。实际服务端口、CPU/GPU与资源上限在T08探测；不停止旧版服务抢端口。

8.3 有界问题与证据处理

一个请求只回答一个可核对的问题，例如“这些流水是否支持所述回款解释”。按冻结snapshot提取授权证据，保留反例与冲突来源；问题拆分、取证规则同样要评测。不要把全部PDF或整段长trajectory直接拼接输入。

调用前使用对应tokenizer计算正文、标准和全部选项预算；超过已验范围时返回failed+E-25，保留原引用范围，不默默截断。可由上层新建更窄问题后再次执行；新问题留新question/version记录，不在适配器里偷偷改变命题。映射未知、否定/例外存在歧义或证据不足时明确unknown/人工复核，不硬选正面结果。

Laya等非文本判断模型不必提供解释；解释由主审结合真实证据生成并验证，界面不得声称解释是模型内部推理。原始指标保留本义，各任务阈值依据固定评测单独确定；没有校准证据就不能使用统一“0.8即可信”的门限。

8.4 接入顺序与准入

1. 完成统一契约fixture，验证disabled、unknown、失败和越权反例。
2. 先用本地候选评估 extraction_grounding 与 trajectory_quality。轨迹未实现前仅可测提炼任务。
3. 固定专家标注题集，加入中文否定、条件例外、矛盾、长证据和工具失败样例；比较现有判断基线与Laya、其他可用本地模型。
4. 分任务报告误判/漏判、无依据支持、拒答和覆盖、耗时/成本；未达到预先阈值则保持unverified/failed，不影响主审disabled路径。
5. 合格后先shadow旁路对照，再按任务允许runtime；shadow输出不改变当次建议。
6. 有Jev Key和授权后用同一题集独立评估；没Key时仅fixture通过，live未验证。

领域微调属于后续实验：训练/校准/测试分开，专家纠正和可追溯结果为来源；生成模型和判断模型互相打高分不能视为自我提升。回放、审核、发布及回滚走同一改进治理链。对应 AC-38/39/40/41，原 AC-17–21 保持有效。