Files
mini-openclaw/docs/v2/01-requirements.md
T
2026-09-29 12:09:18 +08:00

176 lines
23 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 兴邦预审 v2 需求规格
状态:0.2 · 2026-09-29。产品目标和三模块方向已经用户确认;规格与工程门禁仍待审阅。规则编号作用域为本文,原编号保留,新增 BR-21–44 / E-16–26 / AC-22–45。
## 1. Requirement Overview
来源:[URD](URD.md) 的 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
契约候选以 [详细设计](03-detailed-design.md) 为单一说明,实施时唯一代码定义拟在 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节;闭环语义见 [三模块设计](14-experience-loop.md)。
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](04-ui-spec.md)。
## 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 见 [决策记录](09-decisions.md)。本轮规格是待评审草案;P0 演示可用模拟材料,真实数据出口、正式权限和概率校准不得用临时假设替代确认。
已定方向:公司评审会通过为目标、初始材料预审、三模块闭环、人工与历史卡片共治、方案动态维度、可切换专项判断、P0纯模拟演示、真实结果驱动受控改进。被否方案:单题判断直接审批、经验未经审核自动生效、复制整库后再定义用途、用模拟提升冒充因果效果。