mini-openclaw-v2/docs/v2/01-requirements.md

兴邦预审 v2 需求规格

状态：0.2 · 2026-09-29。产品目标和三模块方向已经用户确认；规格与工程门禁仍待审阅。规则编号作用域为本文，原编号保留，新增 BR-21–44 / E-16–26 / AC-22–45。

1. Requirement Overview

来源：URD 的 FR-FACT/HIST/EXP/REV/JEV/JUD/SIM/EVAL/PILOT-01。目标是把历史项目的争议、调查、证据和判断变化用于新项目预审。P0 使用明确标注的模拟数据；经授权脱敏数据进入 P1，不连接未知生产库，不执行正式审批，不展示未经校准的通过概率。

角色沿用 URD。补充术语：快照=不可变输入版本；来源域=data_domain，演示或生产；证据引用=可定位材料片段的 ID；有效经验=已发布、未过期且适用条件成立的版本；硬性规则=经业务确认且由程序执行的约束；幂等键=同一用户请求去重标识；版本冲突=客户端依据旧 revision 更新；专项判断=边界明确的局部判断；降级=保留可用结果并标识未完成检查；运行预算=限制轮数、调用量和耗时；保留集=开发时不可使用的验收样本；提供方（provider）=具体执行专项问题的模型后端；判断配置（profile）=已批准的提供方、模型、端点、数据范围与版本组合；能力声明=该配置已验证支持的题型；原生指标=提供方返回且带原语义的指标，不代表跨模型可比。

新增术语：评审会通过=公司项目评审会作出通过决定（结果代码映射见 OQ-05）；初期预审=初步材料收集阶段；评审方案=数据卡、已发布 Skills/Rules 及核查维度的版本化装配；trajectory=完整运行，step/span=其中一步；人工干预=本次要求或候选修改，不自动成为永久规则；origin=知识创建来源，与 data_domain 正交；改进候选=待测试审核的知识/编排修订；shadow=旁路评价，不影响当次业务结果。

“证据支持”不等于材料真实可信：材料真实性核验是单独的核查结果。风险严重程度、数据完整性、模型确定性、审批概率互不替代。

2. Data Model & Interface Contract

契约候选以 详细设计 为单一说明，实施时唯一代码定义拟在 backend/contracts/prescreen.py。现有 ProjectSnapshot/Evidence 不复制，版本适配后复用。

对象	本期字段摘要	使用面
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[]、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	验证看板

新增 ImportBatch、KnowledgeCard、ReviewPlan、DimensionSpec、TrajectoryStep、ReviewOutcome、ImprovementCandidate、ProbabilityView 契约见详细设计第9节；闭环语义见 三模块设计。

API 候选命名空间 /api/prescreen，通过同源 /api/core/prescreen 代理访问；下列端点尚未实现。请求/响应、错误、界限及 owner 见详细设计。P0 probability 必须为 null，并附原因 not_calibrated。

3. Surface Specification

项目预审总览：结论和信息基础在顶部；中间是核查问题与经验比较；右侧动作模拟；详情抽屉展示来源。历史经验页：时间线、原文与经验卡并排。验证页：样本锁定、结果对照和分歧复盘。

统一视图状态：idle/loading/ready/empty/error/submitting；运行另有 queued/running/awaiting_input/completed/partial/failed/cancelled。动作权限由后端判定，前端隐藏无权动作不能代替后端授权。详见 UI Spec。

4. Business Rules

ID	可测试规则（唯一职责 owner）
BR-01	材料提取候选须经授权用户确认后才能进入项目事实；保留原件与来源。owner：材料确认服务
BR-02	历史事件缺少时间或原文时保留未知值和缺证标识，不生成虚构经过。owner：历史过程服务
BR-03	经验仅能通过草稿→待审核→发布的受控状态转换生效；无发布资格者不得发布。owner：经验治理
BR-04	检索有效经验时先按数据域、权限、状态、有效期和适用条件过滤，再做相关性比较。owner：经验检索
BR-05	主审形成综合预审意见；任一专项模型的单题结果不得直接写入 recommendation。owner：预审编排
BR-06	已确认的硬性阻断不能被模型或其他维度高分覆盖。owner：结果校验
BR-07	缺数据记 unknown；全部关键核查不可完成时 recommendation=insufficient_information。owner：结论完整性校验
BR-08	未通过来源校验的引用不能进入有效结论；相关判断退回缺证/复核。owner：证据校验
BR-09	专项关闭或运行期间所选服务失效时记录 skipped/failed 及降级原因；不能伪造判断。owner：专项模型适配
BR-10	材料中的指令不能扩展主审工具集合；金额与日期运算只能由确定性工具执行。owner：工具策略
BR-11	情景模拟只写独立假设结果，不能修改项目事实、正式运行或审批状态。owner：模拟服务
BR-12	未校准时 probability=null；Score、Noul、相似案例通过占比均不能直接映射为通过概率。owner：结果序列化
BR-13	每次运行冻结输入和规则/Skill/经验/模型/问题版本，过程修订不覆盖旧结果。owner：运行存储
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：运行配置解析
BR-21	预测目标绑定公司评审会结果及材料时点；未送审/待定/撤回不映射为会议否决。owner：结果标签映射
BR-22	材料集合导入逐文件保留来源、定位、解析版本和状态；未确认候选不进入冻结事实。owner：导入清单
BR-23	多来源事实冲突保留候选并要求显式处理，不按上传先后覆盖。owner：事实冲突服务
BR-24	卡片保留 origin 与 data_domain；历史提炼后人工修改仍保留历史谱系。owner：来源存储
BR-25	自然语言运行要求只影响当前作用域，变为持久知识必须生成待审候选。owner：指令作用域
BR-26	历史归纳 Rule 默认 advisory；缺少正式制度/授权依据和审核不得发布 hard 规则。owner：规则资格校验
BR-27	运行只能装配获准且有效的已发布方案依赖，冻结数据/Skill/Rule/经验版本。owner：方案解析
BR-28	维度按方案依赖的 dimension_id 去重；同 ID 不同刻度/语义拒绝合并。owner：维度解析
BR-29	演示估计仅在 demo 域以独立字段显示，真实 probability 未校准仍为 null，导出保留来源标识。owner：概率呈现契约
BR-30	沙盘按完整动作组合重算，结果须匹配当前选择；失败/乱序不改基线。owner：情景状态
BR-31	一次运行保存一条轨迹与多个可追溯步骤，记录可观察动作与版本，不伪造隐藏推理。owner：轨迹存储
BR-32	会议结果追加保存并按材料版本对齐；更正引用旧记录，无匹配快照不倒填初期预测标签。owner：会议结果服务
BR-33	改进候选只有通过固定对照与独立审核后才可发布；原运行和原版本不覆盖。owner：改进治理
BR-34	批量模拟案例必须有多类结果、可复现种子与生成版本；全过程标 demo，不声称真实准确率。owner：模拟数据生成
BR-35	开发/校准/保留集在经验提炼前按客户/项目关联分组并结合时间划分；保留材料及其衍生知识不进入开发。owner：数据集隔离
BR-36	高预测组实际通过比例同时报告覆盖率、可观察标签数与未观察数，分母为零返回不适用。owner：业务指标
BR-37	专项配置按业务任务及题型登记已验证能力，某任务合格不自动授权其他任务。owner：专项准入
BR-38	本地判断运行固定具体模型/checkpoint及映射版本；内部路由不得静默切换权重。owner：本地适配
BR-39	输入超出已验证上下文预算不得静默截断；返回未完成并保留所选证据范围。owner：证据预算
BR-40	判断模型的效果以固定专家标注集比较，不把模型自评或自身生成标签当作独立真值。owner：专项评测
BR-41	卡片来源、数据域、审核状态分别显示；来源使用文字/图标与样式共同区分。owner：卡片呈现
BR-42	人工新增和历史提炼 Skills/Rules 共用审核发布路径；编辑已发布内容生成新草稿版本。owner：卡片治理
BR-43	雷达只对同刻度且3–8维绘制；其余用完整列表/分组，不遗漏关键项或由面积计算概率。owner：维度呈现
BR-44	stop 只表示暂不建议推进并附依据；系统不得自动关闭项目或执行正式审批。owner：建议动作边界

5. Exception Scenarios

ID	触发 / HTTP与错误码	用户可见消息 / 恢复
E-01	解析失败，422 MATERIAL_PARSE_FAILED	材料未能完整解析，请核对原件或手工录入；保留原件
E-02	关键证据缺失，运行结果 MISSING_EVIDENCE	关键证据尚未取得，暂不能确认；补件后新运行
E-03	无权限，403 ACCESS_DENIED	无权执行此操作；不泄露其他项目对象是否存在
E-04	引用无效/跨项目，422 INVALID_EVIDENCE	结论引用未通过核验，请复核来源；拒绝有效化
E-05	乐观锁不符，409 REVISION_CONFLICT	内容已有更新，请刷新后重试；保留本地草稿
E-06	专项模型不可用，运行结果 JUDGMENT_UNAVAILABLE	专项核查未完成，已保留其他结果；允许明确重试
E-07	非法枚举/载荷/版本，422 INVALID_REQUEST	请求内容不符合当前版本，请检查后重试
E-08	预算耗尽，运行结果 RUN_BUDGET_EXCEEDED	本次核查已达到执行上限，请复核未完成项
E-09	幂等键载荷冲突，409 IDEMPOTENCY_CONFLICT	此请求编号已用于不同内容，请重新提交
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	专项结果未通过格式与语义校验，请复核或重试；不作为有效判断
E-16	文件集合空/类型或容量不满足，422 IMPORT_BATCH_INVALID	材料集合不符合导入要求，请检查文件类型和大小；逐文件错误沿用 E-01
E-17	关键事实有未解决冲突，运行结果 FACT_CONFLICT_UNRESOLVED	材料存在不一致，请核对并确认；不得静默选择
E-18	硬规则缺正式依据或审核，422 HARD_RULE_BASIS_REQUIRED	硬性规则需要正式依据和审核，当前仅可保存为建议草稿
E-19	方案/依赖未发布、失效或不可访问，422 PLAN_DEPENDENCY_INVALID	评审方案存在不可用组件，请更新后重新发起；不暴露无权组件
E-20	同维度ID语义/刻度冲突，422 DIMENSION_SCHEMA_CONFLICT	核查维度定义不一致，请统一后保存方案
E-21	真实域请求/展示演示估计，422 DEMO_ESTIMATE_FORBIDDEN	当前数据域不允许使用演示概率
E-22	假设互斥/前提缺失，422 SCENARIO_ASSUMPTION_CONFLICT	所选推进条件存在冲突或缺少前提，请调整
E-23	会议结果无对应材料版本，记录状态 OUTCOME_SNAPSHOT_UNMATCHED	评审记录已保存，但尚未关联送审材料版本；允许后续核对，不纳入该时点概率验证
E-24	改进未完成对照或未获审核，409 IMPROVEMENT_NOT_VALIDATED	改进尚未完成验证与审核，暂不能发布
E-25	输入超出模型已验证预算，运行结果 JUDGMENT_CONTEXT_EXCEEDED	本次证据超出专项核查范围，请缩小问题或转人工复核
E-26	会议结果代码无法映射，记录状态 OUTCOME_LABEL_UNMAPPED	评审结果口径尚未确认，已保留原记录，暂不计入通过率

运行级错误保存在 degradations/finding 中，HTTP 200 仅表示结果可读取，不表示核查通过。禁止把 failed 状态当作 completed。

6. Acceptance Criteria

ID	Given / When / Then	覆盖
AC-01	Given 已解析候选，When 未确认/确认，Then 分别不进入/进入事实且能定位原文；解析失败可人工补录	BR-01, E-01
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 任一专项模型返回正面单题判断但整体证据冲突，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 专项已关闭或运行时所选服务失效/超时/畸形输出，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
AC-13	Given 同一项目产生新证据版本，When 重跑或旧 revision 更新，Then 新旧运行分别留存或返回版本冲突	BR-13, E-05
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
AC-22	Given 已确认会议事件和未送审/附条件记录，When 按版本映射标签，Then 未送审不当否决，未确认附条件口径保留原码与未映射状态	BR-21, E-26
AC-23	Given 文件集合含正常、损坏、超限及重复文件，When 导入与确认，Then 逐项保留状态和页码/单元格来源，失败可重试，未确认不入事实	BR-22, E-16, E-01
AC-24	Given 同期间金额的两个冲突来源，When 冻结事实，Then 保留冲突和来源并要求确认，不默认覆盖	BR-23, E-17
AC-25	Given 历史提炼卡及人工创建卡，When 人工编辑前者并保存，Then 前者仍为历史来源并有父版本，后者为人工来源，数据域独立	BR-24, E-05
AC-26	Given 本次补充说明要求优先核查或永久改规则，When 运行与保存，Then 仅当前授权范围生效，持久修改只能形成草稿且不能扩大工具权限	BR-25, E-03, E-07
AC-27	Given 只有历史频次的规则候选，When 请求发布为硬规则，Then 拒绝并给正式依据缺失文案，可保留 advisory 草稿	BR-26, E-18
AC-28	Given 含已发布/草稿/撤回/跨域组件的方案，When 启动运行，Then 只接受全部有效且授权的依赖并冻结版本，其他拒绝	BR-27, E-19
AC-29	Given 两张卡引用同一维度或相同ID不同刻度，When 保存方案，Then 相同定义只出现一次，不同定义拒绝合并	BR-28, E-20
AC-30	Given demo/production 项目与人工情景值，When 查看API/UI/导出，Then 仅demo显示独立演示字段及标识，真实 probability 仍为空，越域拒绝	BR-29, E-21
AC-31	Given 互斥动作及快速连续勾选，When 创建情景且旧请求晚到或当前请求失败，Then 冲突拒绝，旧结果丢弃，失败保留基线并标未完成，不累加提升	BR-30, E-22, E-06
AC-32	Given 一个run中两次工具调用及一次失败，When 查看轨迹，Then 同一trajectory有独立step及版本/证据引用，失败保留，不生成隐藏思维	BR-31, E-04
AC-33	Given 会议记录无法关联材料快照或后续更正，When 保存并对照，Then 无匹配单列，更正追加并引用旧版，不改原预测	BR-32, E-23, E-05
AC-34	Given 无对照证据或未经独立审核的改进，When 请求发布，Then 拒绝且旧版本有效；验证审核合格才生成新发布版本	BR-33, E-24
AC-35	Given 同seed/版本的模拟数据配置，When 生成两次并查看报告，Then 规范化清单一致且涵盖多种结果，所有材料/标签/导出标demo	BR-34, E-07
AC-36	Given 同客户关联项目、近重复案例和保留集材料，When 划分后提炼或尝试混入衍生Skill，Then 关联组不跨集合；保留内容不可进入提炼，泄漏标作废	BR-35, E-11
AC-37	Given 高预测组有已评审和未送审样本或空分母，When 计算指标，Then 报告通过分子/可观察分母/覆盖率/未观察数，零分母不填0%	BR-36, E-26
AC-38	Given 仅通过提炼质检验收的配置，When 用于实时预审或其他题型，Then 拒绝未获准任务并显示未完成，不以安装或其他任务成功放行	BR-37, E-14
AC-39	Given 冻结本地checkpoint的运行，When 内部路由尝试换模型，Then 拒绝不匹配并记录失败；新模型只可用于新配置/新运行	BR-38, E-15
AC-40	Given 超出上下文预算的证据包，When 执行判断，Then 不静默截断、不外发该题，记录未完成与原证据范围	BR-39, E-25
AC-41	Given 专项评价只有同模型自评或其生成标签，When 登记效果合格证据，Then 拒绝当作独立评测；专家标签和数据划分版本可追溯	BR-40, E-24
AC-42	Given 历史/人工/制度来源且审核状态不同的卡片，When 颜色关闭或键盘查看，Then 仍能通过文字和图标区分来源、数据域与状态	BR-41, E-07
AC-43	Given 人工新增/历史提炼候选与已发布卡片，When 保存/编辑/审核，Then 共用同一治理入口；已发布编辑产生新草稿，无权及自批均拒绝	BR-42, E-03, E-05, E-07
AC-44	Given 0/2/6/9个维度或异刻度，When 展示结果，Then 只对同刻度3–8维画雷达，其余完整列表，硬阻断独立且面积不推概率	BR-43, E-20
AC-45	Given 预审建议stop，When 查看结果或模型试图关闭项目，Then 展示依据及人工决定入口，不修改正式审批/项目关闭状态	BR-44, E-03

7. Open Questions & Decision Record

OQ-01 至 OQ-06 见 决策记录。本轮规格是待评审草案；P0 演示可用模拟材料，真实数据出口、正式权限和概率校准不得用临时假设替代确认。

已定方向：公司评审会通过为目标、初始材料预审、三模块闭环、人工与历史卡片共治、方案动态维度、可切换专项判断、P0纯模拟演示、真实结果驱动受控改进。被否方案：单题判断直接审批、经验未经审核自动生效、复制整库后再定义用途、用模拟提升冒充因果效果。