diff --git a/docs/v2/01-requirements.md b/docs/v2/01-requirements.md index 5c0895f..dae5232 100644 --- a/docs/v2/01-requirements.md +++ b/docs/v2/01-requirements.md @@ -4,9 +4,9 @@ ## 1. Requirement Overview -来源：[URD](URD.md) 的 FR-FACT/HIST/EXP/REV/JEV/SIM/EVAL/PILOT-01。目标是把历史项目的争议、调查、证据和判断变化用于新项目预审。P0 使用模拟或经授权的脱敏数据，不连接未知生产库，不执行正式审批，不展示未经校准的通过概率。 +来源：[URD](URD.md) 的 FR-FACT/HIST/EXP/REV/JEV/JUD/SIM/EVAL/PILOT-01。目标是把历史项目的争议、调查、证据和判断变化用于新项目预审。P0 使用模拟或经授权的脱敏数据，不连接未知生产库，不执行正式审批，不展示未经校准的通过概率。 -角色沿用 URD。补充术语：快照=不可变输入版本；来源域=data_domain，演示或生产；证据引用=可定位材料片段的 ID；有效经验=已发布、未过期且适用条件成立的版本；硬性规则=经业务确认且由程序执行的约束；幂等键=同一用户请求去重标识；版本冲突=客户端依据旧 revision 更新；专项判断=边界明确的局部判断；降级=保留可用结果并标识未完成检查；运行预算=限制轮数、调用量和耗时；保留集=开发时不可使用的验收样本。 +角色沿用 URD。补充术语：快照=不可变输入版本；来源域=data_domain，演示或生产；证据引用=可定位材料片段的 ID；有效经验=已发布、未过期且适用条件成立的版本；硬性规则=经业务确认且由程序执行的约束；幂等键=同一用户请求去重标识；版本冲突=客户端依据旧 revision 更新；专项判断=边界明确的局部判断；降级=保留可用结果并标识未完成检查；运行预算=限制轮数、调用量和耗时；保留集=开发时不可使用的验收样本；提供方（provider）=具体执行专项问题的模型后端；判断配置（profile）=已批准的提供方、模型、端点、数据范围与版本组合；能力声明=该配置已验证支持的题型；原生指标=提供方返回且带原语义的指标，不代表跨模型可比。 “证据支持”不等于材料真实可信：材料真实性核验是单独的核查结果。风险严重程度、数据完整性、模型确定性、审批概率互不替代。 @@ -19,8 +19,8 @@ | CaseTimeline | id、project_id、data_domain、revision、events[] | 历史过程 | | DecisionEvent | id、event_type、occurred_at?、recorded_at、question、evidence_ids[]、judgment_before?、judgment_after?、conditions[] | 争议时间线 | | ExperienceCard | id、version、status、title、source_event_ids[]、conditions、exceptions、scope、expires_at、reviewer_id?、revision | 经验审核 | -| ScreeningRun | id、snapshot_id、status、recommendation?、findings[]、missing_inputs[]、applied_experiences[]、probability、degradations[]、versions、revision | 预审总览 | -| Judgment | id、question_id、question_version、type、status、answer?、evidence_ids[]、provider、model_version? | 专项复核 | +| ScreeningRun | id、snapshot_id、status、recommendation?、findings[]、missing_inputs[]、applied_experiences[]、probability、degradations[]、judgment_config、versions、revision | 预审总览 | +| Judgment | id、question_id、question_version、type、status、answer?、evidence_ids[]、provider、model_version?、profile_id?、profile_revision?、native_metrics[] | 专项复核 | | Simulation | id、base_run_id、assumptions[]、changed_findings[]、unresolved_findings[]、formal_result=false | 推进沙盘 | | Evaluation | id、dataset_version、split_id、run_versions、locked_at?、status、metrics | 验证看板 | @@ -40,11 +40,11 @@ API 候选命名空间 `/api/prescreen`，通过同源 `/api/core/prescreen` 代 | BR-02 | 历史事件缺少时间或原文时保留未知值和缺证标识，不生成虚构经过。owner：历史过程服务 | | BR-03 | 经验仅能通过草稿→待审核→发布的受控状态转换生效；无发布资格者不得发布。owner：经验治理 | | BR-04 | 检索有效经验时先按数据域、权限、状态、有效期和适用条件过滤，再做相关性比较。owner：经验检索 | -| BR-05 | 主审形成综合预审意见；Jev 的单题结果不得直接写入 recommendation。owner：预审编排 | +| BR-05 | 主审形成综合预审意见；任一专项模型的单题结果不得直接写入 recommendation。owner：预审编排 | | BR-06 | 已确认的硬性阻断不能被模型或其他维度高分覆盖。owner：结果校验 | | BR-07 | 缺数据记 unknown；全部关键核查不可完成时 recommendation=insufficient_information。owner：结论完整性校验 | | BR-08 | 未通过来源校验的引用不能进入有效结论；相关判断退回缺证/复核。owner：证据校验 | -| BR-09 | Jev 未配置、未批准或调用失败时记录 skipped/failed 及降级原因；不能伪造判断。owner：专项模型适配 | +| BR-09 | 专项关闭或运行期间所选服务失效时记录 skipped/failed 及降级原因；不能伪造判断。owner：专项模型适配 | | BR-10 | 材料中的指令不能扩展主审工具集合；金额与日期运算只能由确定性工具执行。owner：工具策略 | | BR-11 | 情景模拟只写独立假设结果，不能修改项目事实、正式运行或审批状态。owner：模拟服务 | | BR-12 | 未校准时 probability=null；Score、Noul、相似案例通过占比均不能直接映射为通过概率。owner：结果序列化 | @@ -52,6 +52,10 @@ API 候选命名空间 `/api/prescreen`，通过同源 `/api/core/prescreen` 代 | BR-14 | 相同 actor+project+operation+幂等键和相同载荷返回同一对象；载荷不同返回冲突。owner：命令入口 | | BR-15 | 盲测在预测锁定之前不向推理输入提供目标项目的标签、最终意见或后续表现。owner：评测服务 | | BR-16 | 真实数据外发前按数据域与接收端策略核验；未批准出口不可调用。owner：模型出口策略 | +| BR-17 | 专项问题经统一入口路由到所选的 Jev 或本地提供方；local 路径不读取 Jev 凭据，不调用 Jev。owner：判断路由 | +| BR-18 | 统一输出只接受题目规定的答案或 unknown；提供方原生指标保留语义且不得互换阈值或补造缺失概率。owner：判断结果归一化 | +| BR-19 | 选择仅限当前用户/数据域获准的已验证配置；不支持所需题型的配置拒绝执行该题。owner：判断配置校验 | +| BR-20 | 运行创建时冻结专项配置修订；切换仅影响新运行，故障不得自动切换提供方。owner：运行配置解析 | ## 5. Exception Scenarios @@ -69,6 +73,9 @@ API 候选命名空间 `/api/prescreen`，通过同源 `/api/core/prescreen` 代 | E-10 | 未批准出口，403 EGRESS_NOT_APPROVED | 当前数据不允许发送至该模型服务 | | E-11 | 评测标签提前暴露，409 EVALUATION_CONTAMINATED | 当前样本不再满足盲测条件，已排除 | | E-12 | 经验已失效/不适用，运行结果 EXPERIENCE_EXCLUDED | 该经验不适用于本次核查；展示可见范围内的排除原因 | +| E-13 | 配置不存在、不可用或未获准，422 JUDGMENT_CONFIG_INVALID | 当前专项模型配置不可用，请选择可用配置或关闭专项核查；不暴露无权限配置详情 | +| E-14 | 不支持题型/映射未验证，运行结果 JUDGMENT_CAPABILITY_UNSUPPORTED | 当前模型尚不支持此项核查，已标记未完成；不改题、不猜测结果 | +| E-15 | 非法答案/非有限数值/指标来源不明，运行结果 JUDGMENT_OUTPUT_INVALID | 专项结果未通过格式与语义校验，请复核或重试；不作为有效判断 | 运行级错误保存在 degradations/finding 中，HTTP 200 仅表示结果可读取，不表示核查通过。禁止把 failed 状态当作 completed。 @@ -80,11 +87,11 @@ API 候选命名空间 `/api/prescreen`，通过同源 `/api/core/prescreen` 代 | AC-02 | Given 缺少事件日期的历史材料，When 提炼时间线，Then occurred_at=null 且显示缺证，不编日期 | BR-02, E-02 | | AC-03 | Given 草稿经验与无权发布人，When 请求发布，Then 拒绝且无有效版本；合资格审核走合法状态后生效 | BR-03, E-03, E-07 | | AC-04 | Given 过期/异域/例外触发/有效经验，When 新运行检索，Then 仅有效且授权的版本可应用 | BR-04, E-12 | -| AC-05 | Given Jev 返回正面单题判断但整体证据冲突，When 汇总，Then 主审记录冲突与理由，单题不能覆盖综合意见 | BR-05, E-02 | +| AC-05 | Given 任一专项模型返回正面单题判断但整体证据冲突，When 汇总，Then 主审记录冲突与理由，单题不能覆盖综合意见 | BR-05, E-02 | | AC-06 | Given 确认硬性阻断与模型建议推进，When 校验，Then 拒绝推进并指出规则版本；边界值由程序计算 | BR-06, E-07 | | AC-07 | Given 全部关键资料缺失，When 预审，Then 信息不足并列补件，不判企业高风险 | BR-07, E-02 | | AC-08 | Given 无效或跨项目引用，When 结论校验，Then 拒绝引用并标缺证，不暴露无权原文 | BR-08, E-04, E-03 | -| AC-09 | Given Jev 未配置/超时/畸形输出，When 调用，Then 保留 skipped/failed 与降级，不生成默认高分 | BR-09, E-06, E-07 | +| AC-09 | Given 专项已关闭或运行时所选服务失效/超时/畸形输出，When 执行，Then 保留 skipped/failed 与降级，不生成默认高分 | BR-09, E-06, E-15 | | AC-10 | Given 材料包含终端调用指令，When 模型读材料，Then 工具权限不变；耗尽预算停止并列未完成项 | BR-10, E-08 | | AC-11 | Given 基线运行与假设动作，When 模拟，Then 原快照哈希不变；冲突假设被拒绝 | BR-11, E-07 | | AC-12 | Given 未校准模型，When 查看/导出结果，Then probability=null 且注明原因，即使 Noul 接近 1 也不改写 | BR-12, E-07 | @@ -92,9 +99,14 @@ API 候选命名空间 `/api/prescreen`，通过同源 `/api/core/prescreen` 代 | AC-14 | Given 相同/不同载荷复用幂等键，When 并发提交，Then 分别返回同一运行/409，不重复写入 | BR-14, E-09 | | AC-15 | Given 客户保留集，When 锁定预测前尝试读取目标标签，Then 拒绝；发生泄露则样本作废 | BR-15, E-11, E-03 | | AC-16 | Given 未批准的真实数据出口，When 请求 Jev 或其他外部模型，Then 无网络发送并记录策略拒绝 | BR-16, E-10 | +| AC-17 | Given 没有 Jev Key 和可用本地配置，When 本地实际运行并用厂商 fixture 验证 Jev 适配契约，Then 契约一致、local 不访问 Jev，主审不依赖厂商字段 | BR-17, E-06 | +| AC-18 | Given local 自报 confidence 或 Jev 原生指标，When 归一化/展示，Then 不生成缺失概率、不跨提供方套阈值；畸形/NaN/未知选项返回失败 | BR-18, E-15 | +| AC-19 | Given 未授权/不存在配置或缺题型能力，When 发起运行/执行题目，Then 分别返回配置错误/未完成，不发送该题，也不静默替代 | BR-19, E-13, E-14 | +| AC-20 | Given 排队或执行中的旧运行，When 修改默认配置或所选服务故障，Then 旧运行保留已冻结版本；新选择创建新运行；不得自动外发或替换 | BR-20, E-06 | +| AC-21 | Given 专项开关关闭且两种模型都无凭据，When 主审预审，Then 无专项模型调用，已计划题目 Judgment=skipped、运行明确关闭原因，主审仍受证据和硬规则约束 | BR-09, BR-17, E-06 | ## 7. Open Questions & Decision Record OQ-01 至 OQ-06 见 [决策记录](09-decisions.md)。本轮规格是待评审草案；P0 演示可用模拟材料，真实数据出口、正式权限和概率校准不得用临时假设替代确认。 -已定方向：主审综合研判、历史过程优先、Jev 局部判断、模拟与正式分离、先验证再谈概率。被否方案：单题判断直接审批、经验未经审核自动生效、复制整库后再定义用途、用模拟提升冒充因果效果。 +已定方向：主审综合研判、历史过程优先、可切换专项模型局部判断、模拟与正式分离、先验证再谈概率。被否方案：单题判断直接审批、经验未经审核自动生效、复制整库后再定义用途、用模拟提升冒充因果效果。 diff --git a/docs/v2/02-architecture.md b/docs/v2/02-architecture.md index e907811..10ec8e1 100644 --- a/docs/v2/02-architecture.md +++ b/docs/v2/02-architecture.md @@ -38,15 +38,15 @@ flowchart LR | history_cases / backend/services/history_cases.py | 提炼历史事件、来源及未知项 | 依赖材料与存储；不直接批准经验 | | experience_catalog / backend/services/experience_catalog.py | 关联案例与经验版本、先授权过滤再相关性比较 | 复用既有经验生命周期，不建立平行发布路径 | | prescreen / backend/services/prescreen.py | 主审制定核查、调用专业能力、综合意见 | 只访问冻结授权上下文；不直接操作通用 terminal/SQL | -| judgment_provider / backend/services/judgment_provider.py | Jev 窄问题、schema 校验、预算、失败状态 | 通过出口策略；不写审批或综合结论 | +| judgment_provider / backend/services/judgment_provider.py | 统一窄问题契约、Jev/本地适配、schema 校验、预算、失败状态 | 通过出口策略；不写审批或综合结论 | | prescreen_policy / backend/services/prescreen_policy.py | 硬规则、证据、缺证及概率输出约束 | 不依赖页面，不以模型高分绕过硬约束 | | scenario_service / backend/services/prescreen_scenarios.py | 保存独立情景与差异 | 引用不可变基线；不覆盖真实事实 | | prescreen_evaluation / backend/services/prescreen_evaluation.py | 冻结样本、版本、预测及专家对照 | 标签与推理侧隔离 | | prescreen contracts / backend/contracts/prescreen.py | 新对象与错误契约 | 后端单一定义，前端由 OpenAPI 生成；生成器待建设 | -拟议数据流：材料/授权数据 → 标准事实和来源 → 冻结快照 → 硬规则和计算 → 检索有效经验 → 主审提出具体核查问题 → 专业 Skills/Jev → 验证证据与规则 → 主审综合预审 → 独立复核/正式审批入口。 +拟议数据流：材料/授权数据 → 标准事实和来源 → 冻结快照 → 硬规则和计算 → 检索有效经验 → 主审提出具体核查问题 → 专业 Skills/可切换专项判断 → 验证证据与规则 → 主审综合预审 → 独立复核/正式审批入口。 -历史经验用于选择核查动作和比较适用条件，不能用“相似案例通过”直接推出当前项目通过。Jev 的判断置信与主审解释都不是独立的真实性认证。 +历史经验用于选择核查动作和比较适用条件，不能用“相似案例通过”直接推出当前项目通过。专项模型的判断置信与主审解释都不是独立的真实性认证。 ## 3. 数据模型与持久化 @@ -62,16 +62,16 @@ P0 候选使用现有 SQLite 事务存储承载新增对象类型。历史事件 - 历史导入失败：保留原件和失败事件，允许补充/重新提炼，不伪造缺失过程。 - 主审识别矛盾：记录待核查事项，使用授权证据工具验证，达到预算停止为 partial/awaiting_input。 -- Jev 不可用：缺失项进入 degradations；主审只能依据已完成检查给出有限意见。 +- 所选专项模型不可用或关闭：缺失项进入 degradations；主审只能依据已完成检查给出有限意见。 - 硬规则冲突：结果校验阻断建议推进，保留模型原始结构化提案供审计。 - 新证据进入：产生新快照、新运行，旧结果保留；模拟不进入这条正式更新路径。 - Worker 恢复：复用持久任务机制；幂等范围包含 actor/project/operation/key，禁止重复生成运行。 ## 5. 接口与集成 -内部 API 以 /api/prescreen 为候选命名空间；沿用当前项目鉴权和同源代理。前端不能直接访问模型厂商。现有 assistant_model 的受信端点规则不自动适用于 Jev，后者需独立出口与域策略。 +内部 API 以 /api/prescreen 为候选命名空间；沿用当前项目鉴权和同源代理。前端不能直接访问模型厂商。现有 assistant_model 的受信端点规则不自动适用于 Jev，专项模块需独立出口与域策略；local 也只能使用管理员批准的端点，不能从浏览器传入任意 URL。 -Jev 接口概念参考 TypeSafe 官方文档：https://docs.typesafe.ai/introduction 、https://docs.typesafe.ai/confidence 。当前没有 SDK 安装、Key、版本或延迟实测；实施前重核版本与中文金租样本效果。 +Jev 接口概念参考 TypeSafe 官方文档：https://docs.typesafe.ai/introduction 、https://docs.typesafe.ai/confidence 。当前没有 SDK 安装、Key、版本或延迟实测；实施前重核版本与中文金租样本效果。Jev 是可选提供方，本地开源模型通过独立适配器执行同一业务任务；拿不到 Jev Key 不阻塞本地路径。统一契约和差异处理见 [专项判断模型切换](11-judgment-providers.md)。 概率预测为后续独立模型，输入仅使用预测时可得事实和判断特征。主审解释模型输出但不能改写原始概率；审批阶段、样本偏差和校准结果未明确前 probability=null。 @@ -84,7 +84,7 @@ Jev 接口概念参考 TypeSafe 官方文档：https://docs.typesafe.ai/introduc ## 7. ADR ADR-01 保留现有技术基线，按模块增量扩展，否决全面换框架。 -ADR-02 主审综合判断+确定性约束+Jev 专项复核，否决单模型 yes/no 审批。 +ADR-02 主审综合判断+确定性约束+可切换专项复核，否决单模型 yes/no 审批。 ADR-03 经验以过程和来源为核心，否决只按最终结果记忆。 ADR-04 经验发布复用现有治理，否决自动从反馈直接生效。 ADR-05 先做验证和数据合作，再建设概率校准，否决专家分数转百分比。 @@ -94,6 +94,6 @@ ADR-06 v2 独立目录与资源，旧版保留；本轮先文档后迁移，目 ## 8. 拟建立的架构验证 -业务 service 不导入 src；预审工具集合不含 terminal/任意 SQL；跨域经验不可检索；引用必须属于授权快照；模拟不修改真实快照；无校准时概率为 null；经验发布只能经过一个治理入口。映射 AC-04/06/08/10/11/12/16。 +业务 service 不导入 src；预审工具集合不含 terminal/任意 SQL；跨域经验不可检索；引用必须属于授权快照；模拟不修改真实快照；无校准时概率为 null；经验发布只能经过一个治理入口。专项模型只能通过统一接口接入；local 不依赖 Jev 凭据；配置冻结且故障不自动切换。映射 AC-04/06/08/10/11/12/16/17/18/19/20/21。 这些是待实施的机器检查；现有测试覆盖另列，不能标成 v2 已通过。 diff --git a/docs/v2/03-detailed-design.md b/docs/v2/03-detailed-design.md index 6c6d990..60ffb40 100644 --- a/docs/v2/03-detailed-design.md +++ b/docs/v2/03-detailed-design.md @@ -1,6 +1,6 @@ # 兴邦预审 v2 详细设计候选 -状态：0.1 草案，阶段①/②未定案；以下端点和新类型尚未实现。覆盖 BR-01–16 / E-01–12 / AC-01–16，先形成可评审的契约，再编写代码。 +状态：0.1 草案，阶段①/②未定案；以下端点和新类型尚未实现。覆盖 BR-01–20 / E-01–15 / AC-01–21，先形成可评审的契约，再编写代码。 ## 1. 约定与契约归属 @@ -8,7 +8,7 @@ 共同字段：id/project_id/snapshot_id 等为非空字符串（1–128 字符），revision 为正整数，时间为带时区 ISO-8601；未知发生时间允许 null，记录时间必填；data_domain 为 demo/production；所有输入禁止未知字段。列表分页候选 limit 默认 20，范围 1–100，cursor 可空。 -P0 初始工程限制提案（非业务阈值）：沿用单材料 10 MB；单次最多 10 个 Jev 问题、每题最多 20 条证据、每次最多 10 个模拟动作；工具最多 20 次、总运行 120 秒、单次模型请求 30 秒、可重试故障最多重试 1 次且计入总预算。管理员只能在部署配置中降低初期限制；放宽须重新验证并更新规格。这些值在 OQ-04 定案前不得当作性能承诺。 +P0 初始工程限制提案（非业务阈值）：沿用单材料 10 MB；单次最多 10 个专项判断问题、每题最多 20 条证据、每次最多 10 个模拟动作；工具最多 20 次、总运行 120 秒、单次模型请求 30 秒、可重试故障最多重试 1 次且计入总预算。管理员只能在部署配置中降低初期限制；放宽须重新验证并更新规格。这些值在 OQ-04 定案前不得当作性能承诺。 ## 2. 接口草案 @@ -20,7 +20,8 @@ P0 初始工程限制提案（非业务阈值）：沿用单材料 10 MB；单 | GET /case-timelines/{id} | 无 body | 200 CaseTimeline | history_cases；E-03；不存在统一 404 NOT_FOUND | | POST /case-timelines/{id}/experiences | title:string[1..200], source_event_ids:string[1..50], conditions:Condition[], exceptions:Condition[], scope:project/team, expires_at:datetime | 201 ExperienceCard draft | 经验治理；E-03/04/07/09 | | POST /experiences/{id}/transitions | action:submit/approve/reject/withdraw, expected_revision:int, note:string[1..2000] | 200 ExperienceCard | 复用经验治理；E-03/05/07 | -| POST /projects/{project_id}/runs | snapshot_id:string, enable_judgment:boolean=false | 202 ScreeningRun queued | prescreen；E-03/07/09/10 | +| GET /projects/{project_id}/judgment-profiles | 无 body | 200 {profiles:[{id,revision,display_name,provider,capabilities}],default_profile_id:string?}；仅授权可用项 | 判断配置；不存在/无权项目404；详见专项设计 | +| POST /projects/{project_id}/runs | snapshot_id:string, enable_judgment:boolean=false, judgment_profile_id:string? | 202 ScreeningRun queued | prescreen；E-03/07/09/10/13 | | GET /runs/{id} | 无 body | 200 ScreeningRun | prescreen；E-03；不存在 404 NOT_FOUND | | POST /runs/{id}/cancel | expected_revision:int | 200 ScreeningRun | prescreen；E-03/05/07 | | POST /runs/{id}/simulations | assumptions:Assumption[1..10] | 201 Simulation | scenario_service；E-03/05/07/09 | @@ -38,13 +39,13 @@ P0 初始工程限制提案（非业务阈值）：沿用单材料 10 MB；单 | Condition | field:string（标准字段白名单）；operator:eq/in/present/absent；value:string/bool/string[]/null；数据类型按 operator 校验，不执行表达式 | 经验治理 | | ExperienceCard | id, project_id, data_domain, revision；version:string；title；status:draft/in_review/published/rejected/withdrawn；source_event_ids:string[]；conditions/ exceptions:Condition[]；scope:project/team；team_id:string?；expires_at；reviewer_id:string?；policy_version:string? | 经验治理 | | Finding | 复用既有 Finding；展示 title/result/evidence_ids/basis_ids/suggested_action/status；无依据只能 unknown，已有枚举不改名 | 预审编排 | -| ScreeningRun | id, project_id, data_domain, revision, snapshot_id；status 见第4节；recommendation:advance/supplement/stop/insufficient_information/null；findings:Finding[]；missing_inputs:string[]；applied_experiences:{id,version,reason,evidence_ids}[]；probability:null；probability_reason:not_calibrated；degradations:{code,message}[]；versions:{schema,policy,skills,experiences,model,questions}；created_at；finished_at:datetime? | 运行存储 | -| Judgment | id, run_id, question_id, question_version；type:choice/score/noul；status:completed/skipped/failed；answer:object?；evidence_ids:string[]；provider:string；model_version:string?；error_code:string? | judgment_provider | +| ScreeningRun | id, project_id, data_domain, revision, snapshot_id；status 见第4节；recommendation:advance/supplement/stop/insufficient_information/null；findings:Finding[]；missing_inputs:string[]；applied_experiences:{id,version,reason,evidence_ids}[]；probability:null；probability_reason:not_calibrated；degradations:{code,message}[]；judgment_config:{enabled,profile_id?,profile_revision?,provider,model_version?,adapter_version?,prompt_version?,mapping_version?}；versions:{schema,policy,skills,experiences,model,questions}；created_at；finished_at:datetime? | 运行存储 | +| Judgment | id, run_id, question_id, question_version；type:choice/score/binary；status:completed/skipped/failed；answer:JudgmentAnswer?；evidence_ids:string[]；provider:jev/local/disabled；profile_id:string?；profile_revision:int?；model_version:string?；native_metrics:NativeMetric[]；error_code:string?；skip_reason:string? | judgment_provider | | Assumption | action_id:string；description:string[1..1000]；field_changes:{field,value}[]；required_evidence_ids:string[] | scenario_service | | Simulation | id, project_id, base_run_id；assumptions:Assumption[]；changed_findings:{code,before,after,basis_ids}[]；unresolved_findings:string[]；formal_result:false；created_at | scenario_service | | Evaluation | id, dataset_version, split_id；run_versions:object；locked_at:datetime?；status:prepared/running/locked/revealed/invalidated；metrics:{name,numerator,denominator,value?,scope}[] | prescreen_evaluation | -Jev answer 为严格可辨识类型：Choice={choice:string, probabilities:map, confidence:float[0..1]}；Score={score:float, probabilities:map, confidence:float[0..1]}，范围按问题等级；Noul={noul:float[0..1]}，无独立 confidence。必须与已冻结题型/选项/等级吻合；畸形、NaN、未知选项都记 failed。具体厂商 envelope 由适配器转换，不能把任意 JSON 直接存成有效判断。 +JudgmentAnswer、NativeMetric、JudgmentProfile 及配置选择规则统一详见 [专项判断模型切换](11-judgment-providers.md) 第3–5节。题型统一为 choice/score/binary；原草案中的 noul 是厂商语义，改由 Jev 适配器处理，不再进入业务题型。该草案从未实现，无已上线 API 迁移。未知可作为显式答案；completed 只表示完成该题处理与校验（允许缺证直接返回 unknown），不表示支持结论或项目通过。 Evidence 来源可定位不代表真实性已核验，真实性结果须单列 Finding。conditions 非空，team 范围必有 team_id；例外命中即排除；首次发布缺失 reviewer_id 不合法。撤回不删除历史引用。 @@ -76,7 +77,7 @@ recommendation 在 queued/running 时为 null，终态仍可能为 insufficient_ ## 7. 测试映射 -history_cases→AC-01/02；经验治理与检索→AC-03/04/13；prescreen+policy→AC-05/06/07/08/12；judgment_provider→AC-09/16；工具策略→AC-10；scenario_service→AC-11；命令入口→AC-14；evaluation→AC-15。具体测试提案见验证方案，当前均不是已执行的新功能测试。 +history_cases→AC-01/02；经验治理与检索→AC-03/04/13；prescreen+policy→AC-05/06/07/08/12；judgment_provider→AC-09/16/17/18/19/20/21；工具策略→AC-10；scenario_service→AC-11；命令入口→AC-14；evaluation→AC-15。具体测试提案见验证方案，当前均不是已执行的新功能测试。 ## 8. 未决项 diff --git a/docs/v2/04-ui-spec.md b/docs/v2/04-ui-spec.md index b36dfc8..7490d81 100644 --- a/docs/v2/04-ui-spec.md +++ b/docs/v2/04-ui-spec.md @@ -66,3 +66,11 @@ P0 顶部不显示百分比“通过率”。展示 recommendation、missing_inp 来源点击与权限 AC-01/08；未知时间 AC-02；经验审核 AC-03/04；降级 AC-07/09；模拟隔离 AC-11；无伪概率 AC-12；盲测标签 AC-15。 UI 门禁尚未通过：路由位置、统一 token 实现、i18n 文件、视觉稿、键盘和对比度验收待完成。截图自评不能单独算通过，应有可复现的 DOM/行为断言及独立评审记录。 + +## 8. 专项判断选项（候选） + +预审发起表单增加“专项核查”：关闭 / 本地模型 / Jev 官方服务；实际选项来自后端授权配置（JudgmentProfile），不能只按品牌静态显示可用。用户看到模型名称、提供方和可用状态；配置 ID/修订和供应商指标放“依据与版本”。管理员在部署配置中管理端点和凭据，P0 不新增在线编辑密钥页面。 + +无 Jev Key 时 Jev 配置不进入可选列表；本地可用则可选择本地。没有可用配置时仅保留关闭并说明未配置。业务请求只传 judgment_profile_id，不传 URL 或 Key；后端重新校验，失败按 E-13 显示。提交中禁改本次选择，运行结束或排队后修改选择均需发起新运行。 + +结果展示本次实际提供方、未完成题目和拒答/unknown；关闭显示“专项核查已关闭”。失效/超时不把选中项悄悄变为另一个模型，不展示占位高分。对应 AC-17/18/19/20/21；页面路由及真实交互待 UI 阶段实施。 diff --git a/docs/v2/05-implementation-plan.md b/docs/v2/05-implementation-plan.md index ce9dd32..5f2d93d 100644 --- a/docs/v2/05-implementation-plan.md +++ b/docs/v2/05-implementation-plan.md @@ -27,7 +27,7 @@ | M0 文档与恢复点（本轮） | Gitea 快照、流程适配、URD/规格草案 | 远程 SHA 一致；文档检查；不是新版功能交付 | | M1 独立基座 | v2 源码、环境模板、契约生成与追加迁移骨架 | 阶段①–③相应门禁通过；独立路径、完整构建、回归通过 | | M2 历史过程与经验 | 时间线、原文定位、审核发布和检索 | AC-01/02/03/04/08/13，模拟与真实域隔离 | -| M3 主审与专项判断 | 有界 Agent Loop、Jev 可选适配、证据和硬规则约束 | AC-05/06/07/09/10/12/14/16；先 mock，再批准环境小样本 | +| M3 主审与专项判断 | 有界 Agent Loop、统一 JudgmentProvider、本地开源模型适配、可选 Jev 适配、证据和硬规则约束 | AC-05/06/07/09/10/12/14/16/17/18/19/20/21；先契约 mock，再验证本地路径；有 Key 后单独启用 Jev 实测，缺 Key 不阻塞 local 交付 | | M4 沙盘与展示 | UI 状态、假设动作、正式/模拟对照 | UI门禁通过，AC-11；源快照哈希不变 | | M5 脱敏试点 | 数据授权清单、保留集盲测和复盘 | AC-15/16，专家评审、指标事先锁定 | | M6 概率校准（后续） | 事件口径、训练/校准/测试、漂移监测 | OQ-05 关闭且样本支持；审批概率与违约风险分开 | @@ -45,3 +45,9 @@ 代码通过可回滚提交/镜像标签恢复。数据迁移追加并有幂等守卫；旧库先快照，升级/回退边界经测试后才部署。回退代码不等于撤销已写入数据。v2 使用独立工作目录、Compose 项目、容器名、数据卷及端口，具体值在 OQ-06 定案。 本轮不实施剪裁、不改业务行为、不创建远程 v2 仓库、不部署。先把评审文档写清，避免规范到位后返工。 + +## 5. M3 专项模块实施顺序 + +按 [专项判断设计](11-judgment-providers.md) 先落统一题库/请求/答案契约与配置冻结，再接本地推理服务并完成真实本地集成测试。Jev 适配独立实现；无 Key 时只验证厂商响应 fixture，live 用例标 skipped，不宣称原版已接通。mock 仅用于测试，不能冒充业务推理结果。 + +两条路径都读取同一版历史经验和证据，主审不写提供方分支。上线某个配置之前，该提供方/模型/提示/题库组合必须独立完成相同业务验收；合同测试通过不能证明模型效果合格。 diff --git a/docs/v2/06-validation.md b/docs/v2/06-validation.md index 877d69b..7a8cf9e 100644 --- a/docs/v2/06-validation.md +++ b/docs/v2/06-validation.md @@ -10,7 +10,8 @@ | 经验审核、检索与版本 | AC-03/04/13 | 权限/集成：无资格、不适用、过期、撤回、异域不可应用；旧版本可追溯 | | 主审与硬约束 | AC-05/06/07 | 有冲突和缺证的固定样例：单题正面不覆盖硬规则，缺数据不判高风险 | | 证据真实性边界 | AC-08 | 伪造 ID、跨项目、无权片段被拒；有引用不等于真实性已证实 | -| Jev 降级 | AC-09/16 | mock：未配置、超时、畸形响应、未批准出口；零伪造判断、零未授权发送 | +| 专项模型降级 | AC-09/16 | mock：未配置、超时、畸形响应、未批准出口；零伪造判断、零未授权发送 | +| 提供方切换与契约 | AC-17/18/19/20/21 | 单测/集成：无 Jev Key 的 local、disabled、畸形答案、题型缺失、配置冻结、无自动跨提供方回退；调用 spy 核验实际发送目标 | | Agent 工具与预算 | AC-10 | 注入材料无法调用 terminal/任意SQL；预算耗尽确实停止 | | 模拟隔离 | AC-11 | 真实快照哈希/数据库记录前后不变；关联改进不可简单相加 | | 概率门禁 | AC-12 | UI/API/导出均无未经校准概率；Noul、Score不转审批率 | @@ -27,7 +28,7 @@ ## 3. 业务验证设计 -同一批材料按版本冻结比较：A=现有助手；B=主审+历史经验；C=B+Jev。对照回答“经验有没有帮助”和“Jev有没有额外收益”，不把两项改进混成一个原因。先用合成反例暴露故障，再用客户持有的脱敏保留集检验。 +同一批材料按版本冻结比较：A=现有助手；B=主审+历史经验；C-local=B+本地专项模型；有 Key 且获准时加入 C-Jev=B+Jev。对照回答“经验有没有帮助”和“所选专项模型有没有额外收益”，不把两项改进混成一个原因。先用合成反例暴露故障，再用客户持有的脱敏保留集检验。 样本包含通过、退回、否决、附条件通过、资料不全及意见分歧。按项目分组、按预测时间截断，只使用当时已取得的材料；区分首次提交通过和补件后最终通过。开发集不能看到保留集答案，也不能通过完整历史报告间接泄漏目标答案。 @@ -53,3 +54,9 @@ 失败→复现→定位→最小修复→同一检查复验，完整记录。未解决故障不得发布镜像。仅保存源码恢复快照不等同发布，快照注明验证状态。 人工评审按正确性、一致性、安全、测试四维；未经独立评审不标通过。线上效果须在真实交付环境观测，本地测试不能替代。 + +## 6. 提供方效果与可用性分别验收 + +同一冻结题库、证据和专家标签验证 Jev/local 的业务含义与结构契约，不要求逐题答案或数值相同。分别统计错误、漏检、拒答/unknown、耗时及成本；模型不支持的题型也计入未完成项，不能从分母偷偷排除。阈值和映射按提供方/模型/题型独立登记，先定再测。 + +local 集成须在没有 Jev 凭据的环境实际执行，并验证未发送 Jev 请求；本地模型服务本身的授权配置另行处理。Jev live 无凭据则明确跳过，fixture 通过仅证明适配代码结构。两者未真实执行前，当前文档一律不宣称切换功能可用。 diff --git a/docs/v2/07-deployment-and-gitea.md b/docs/v2/07-deployment-and-gitea.md index 57397d8..0c4efda 100644 --- a/docs/v2/07-deployment-and-gitea.md +++ b/docs/v2/07-deployment-and-gitea.md @@ -87,3 +87,15 @@ git -C F:\mini-OpenClaw-restore-20260928 rev-parse HEAD 当前仓库只有 .github/workflows/verify.yml，未发现 .gitea/workflows。Gitea Actions 开关、runner、required checks 均未核验。不能声称 Gitea 已自动测试。 后续接入 CI 时：先核对服务器能力和 runner→使用同一本地验证入口→上传 test-evidence→验证失败阻断发布→确认对最终 SHA 真正执行。只新增 YAML 不算 CI 接入完成。 + +## 8. 专项判断提供方配置提案（尚未实现） + +配置结构以 [专项判断模型切换](11-judgment-providers.md) 为准，不向现有 .env / Compose 写入尚未被代码消费的变量。拟新增后端专用配置 `judgment.default_profile_id`（可空）及 `judgment.profiles`；默认关闭，管理员验证本地配置后才选为默认或显式选择。 + +- Jev：按将来核实的官方接口配置端点与后端凭据引用；缺 Key 不影响主审或 local 配置启动。没有凭据不能标记 Jev 已就绪。 +- local：指定经许可的本地/内网推理服务、模型版本和提示版本；不需要 Jev Key。本地服务是否需要自己的访问令牌取决于其部署认证；开源模型权重许可、硬件资源、结构化输出能力和中文评审效果在接入前核实。 +- disabled：零专项请求，保留规则、历史经验和主审预审；结果显示缺失专项核查。不能把 disabled 当作 local 的成功结果。 + +模型服务与业务后端分开配置端口/资源。容器内 localhost 指容器自身，实际地址须从后端容器连通性验证，不能照抄宿主机地址。配置只接受已批准端点，校验重定向/解析目标和数据范围；名称叫 local 不证明全系统数据不外发，主审等其他模型出口也须核对。 + +每个配置有不可变修订，运行引用其版本；敏感值通过后端密钥引用解析，不写前端、Git或日志。变更默认配置只作用于新运行，回滚选择已验证旧配置并新建运行，不篡改旧记录。 diff --git a/docs/v2/08-data-pilot-and-demo.md b/docs/v2/08-data-pilot-and-demo.md index 616b191..a5820d7 100644 --- a/docs/v2/08-data-pilot-and-demo.md +++ b/docs/v2/08-data-pilot-and-demo.md @@ -17,7 +17,7 @@ 示例故事：利润增长但现金流偏弱，最初要求回款核查；部分证据支持正常账期，部分显示恶化；主审比较差异后形成补件或附条件推进意见。明确标“虚构演示案例”，不使用真实客户名称作背书。 -技术展开层展示：冻结快照、命中经验版本、工具调用结果、Jev具体问题、缺失项和硬规则。主页面显示业务含义，避免用技术图掩盖未验证结论。 +技术展开层展示：冻结快照、命中经验版本、工具调用结果、专项模型具体问题及实际提供方、缺失项和硬规则。主页面显示业务含义，避免用技术图掩盖未验证结论。 ## 3. 首批数据清单 @@ -53,6 +53,6 @@ ## 6. 试点验收与扩展条件 -使用验证文档的重大问题漏检、无依据结论、误报、有效补件、专家分歧与效率指标。阈值先约定，结果差也如实展示；基线/经验增强/Jev增强分开测。客户数据从开发样本到保留样本逐步开放，不以模型推荐代替专家复盘。 +使用验证文档的重大问题漏检、无依据结论、误报、有效补件、专家分歧与效率指标。阈值先约定，结果差也如实展示；基线/经验增强/本地专项增强/Jev增强（可选）分开测。客户数据从开发样本到保留样本逐步开放，不以模型推荐代替专家复盘。 通过试点后再扩大业务范围；失败则给出问题归因（提取、检索、经验适用、主审推理、数据缺失），不靠调漂亮分数掩盖。数据接入后的价值应通过相同边界的对照证明。 diff --git a/docs/v2/09-decisions.md b/docs/v2/09-decisions.md index b3d40cb..b3bc288 100644 --- a/docs/v2/09-decisions.md +++ b/docs/v2/09-decisions.md @@ -7,12 +7,13 @@ | ID | 决策 / 状态 | 被否方案 / 理由 | 影响 | |---|---|---|---| | ADR-01 | 复用 Next.js+FastAPI 与现有组件，工程候选 | 全面换框架；无法复用已验证链路 | 先迁移可运行基座，再逐步拆模块 | -| ADR-02 | 主审综合意见、Jev局部判断，用户已明确 | Jev单题直接决定通过；缺乏整体研判 | 证据与硬规则约束最终有效输出 | +| ADR-02 | 主审综合意见、专项模型局部判断（Jev或本地），用户已明确 | Jev单题直接决定通过；缺乏整体研判 | 证据与硬规则约束最终有效输出 | | ADR-03 | 历史评审过程是核心资产，用户已明确 | 只存通过/不通过标签；丢失核查和判断变化 | 优先收集问询、补件、修改和批复条件 | | ADR-04 | 经验经审核、有适用范围，工程候选 | 自动把任意反馈变成规则；会固化错误 | 复用现有经验治理，建立历史过程关联 | | ADR-05 | 无真实校准前不宣称审批概率，已讨论方向 | 分数/Noul直接转通过率；没有业务验证 | P0概率字段为空；先做可追溯预审和试点 | | ADR-06 | 独立v2代码目录待迁移，当前先备份与文档，用户最新顺序 | 直接覆盖现有部署；难回退 | 旧版Gitea恢复点先核验；v2目录尚未建立 | | ADR-07 | 按用户最新要求直接适配流程正文，原文保留在Gitea恢复点 | 照搬Electron路径/发布命令；无法执行 | AGENTS统一入口，正文按兴邦事实执行 | +| ADR-08 | 专项判断支持 Jev 官方服务、本地开源模型和关闭；可切换方向用户已明确，契约细节为工程候选 | 把 Jev Key 作为产品依赖或用通用模型自评分伪装等效概率；供应依赖和指标口径不可控 | 统一业务题库/接口，独立适配/验收；本地路径先交付，Jev 接入不阻塞 | ## 2. Open Questions @@ -22,7 +23,7 @@ needed-by 是明确阶段门，不虚构双方尚未约定的日历时间。 |---|---|---|---|---| | OQ-01 | 首批业务类型、关键核查项、正式硬规则 | 只使用标注演示规则；不宣称兴邦制度 | 项目负责人+兴邦评审专家 | M2真实经验建模前 | | OQ-02 | 经验发布资格、独立复核、真实身份体系 | 演示角色明确标示；生产数据入口不开启 | 兴邦业务负责人+系统管理员 | M2生产权限实现前 | -| OQ-03 | Jev/主审模型端点、客户数据出口、保留策略 | mock/合成样本；不发送真实材料 | 兴邦数据负责人+技术负责人 | 任何真实材料模型调用前 | +| OQ-03 | 专项/主审模型端点、本地模型与硬件、客户数据出口、保留策略 | mock/合成样本；先验证本地路径，缺 Jev Key 不阻塞；不发送真实材料 | 兴邦数据负责人+技术负责人 | 任何真实材料模型调用前 | | OQ-04 | 验收阈值、时延预算、资源/费用上限 | 文档工程限制仅提案，报告耗时不承诺效果 | 产品+测试+实施负责人 | M3配置定案及M5盲测前 | | OQ-05 | “通过”阶段、预测时点、样本量与选择偏差 | probability=null | 兴邦审批负责人+建模负责人 | M6概率需求进入架构前 | | OQ-06 | v2新仓库、云端目录、端口、容器/卷 | 暂用当前独立文档分支；不复用旧生产资源 | 项目负责人+运维 | M1迁移及任何v2部署前 | @@ -35,8 +36,8 @@ needed-by 是明确阶段门，不虚构双方尚未约定的日历时间。 |---|---| | Term | 草案已列术语，待业务评审 | | Contract | 已有候选字段/状态/错误；未生成类型或确认DDL | -| Rule | BR-01–16已拆分并标职责，待评审 | -| Exception | E-01–12有错误和文案，契约校验仍待实现 | +| Rule | BR-01–20已拆分并标职责，待评审 | +| Exception | E-01–15有错误和文案，契约校验仍待实现 | | Coverage | 文档AC覆盖机械检查本轮执行；新功能行为测试未实现 | | Decision | OQ项按里程碑阻断，未宣告需求阶段全过 | diff --git a/docs/v2/10-delivery-record.md b/docs/v2/10-delivery-record.md index a2d5655..b71f85f 100644 --- a/docs/v2/10-delivery-record.md +++ b/docs/v2/10-delivery-record.md @@ -48,3 +48,13 @@ 源码恢复可从已核验分支克隆到新目录，不重置当前工作区。文档修改保留独立提交，可通过后续revert撤销，不删除原始规范。远程资源仅新增分支，无main改写；无需进行破坏性恢复演练。 剩余：需求与方案评审、独立v2代码抽取、真实权限/模型出口确认、历史过程提炼、Jev适配、沙盘实现、脱敏盲测与后续概率校准。全部列入实施计划和OQ，当前未宣称完成。 + +## 6. 追加：专项模型可选设计（2026-09-28） + +用户补充可能无法取得 Jev Key，要求官方服务与本地开源模型可选且承担相同任务。新增 [专项判断设计](11-judgment-providers.md)，同步 URD、规格、架构、详细接口、UI约束、实施/验证计划、部署、数据试点和 ADR-08。原有需求编号保留，追加 BR-17–20 / E-13–15 / AC-17–21。 + +统一题库和答案契约，提供 jev/local/disabled；local 不读取 Jev 凭据，故障不自动改用外部服务。主审形成综合意见，专项模型不能决定整体通过；模型原生指标分别验证，不将本地自报置信度转为审批概率。先实现本地路径，Jev live 缺 Key 可明确跳过。 + +检查：26份Markdown、94个本地链接、20条BR/15条E/21条AC的编号和覆盖、GWT、表格连续性、URD验收引用、文档范围与git diff格式均通过。命令/计划/文件哈希见 test-evidence/20260928-judgment-providers/。仅修改docs/v2，按纯文档轻量路径验证，本次未重跑旧版全量测试。新适配代码、真实模型调用和业务效果均未验证；未更改部署或旧版业务代码。 + +沿用 codex/xingbang-v2-docs-20260928 独立提交并备份；最终提交/远程SHA以该证据目录中的 delivery.json 为准。不修改原始备份分支或 main；独立评审及实现阶段仍待完成。 diff --git a/docs/v2/11-judgment-providers.md b/docs/v2/11-judgment-providers.md new file mode 100644 index 0000000..ed83a3b --- /dev/null +++ b/docs/v2/11-judgment-providers.md @@ -0,0 +1,104 @@ +# 可切换专项判断模块：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