mini-openclaw/docs/v2/02-architecture.md

兴邦预审 v2 架构设计

状态：候选设计 0.2，产品方向已确认、工程门禁待审阅；本文件严格区分当前事实与拟议架构。

1. 概览与已核验基线

代码快照 4d5a420 已保存在 Gitea。当前架构从代码确认如下，图中不包含尚未实现的新模块：

flowchart LR
  U[业务用户] --> W[Next.js 项目工作台]
  W --> P[同源 Route Handler]
  P --> A[FastAPI 路由与权限]
  A --> S[ProjectAssistantService]
  S --> Q[DurableWorker]
  Q --> X[Skill 与规则执行]
  X --> M[受限模型 Agent Loop]
  S --> DB[SQLite 对象与审计]

已有能力	已检查代码	复用限制
项目快照/证据/问题契约	backend/contracts/project_assistant.py	本期复用，不另造同名概念
项目/任务/事务对象	backend/services/project_assistant.py、assistant_store.py、assistant_worker.py	巨大 service 不继续堆新领域，新增模块通过现有入口调用
数据卡/材料	backend/services/assistant_data.py、assistant_materials.py	继续冻结来源与人工确认候选
受限模型核查	backend/services/assistant_model.py	目前提示词禁止作审批决定；新增预审意见要单独设计并测试，不放宽旧版完整核查的权限
可审核经验	backend/services/assistant_experiences.py	已有范围、有效期、条件、审核发布；不能等同已学到客户历史经验
历史案例	backend/data_layer/history_store.py	实际是 JSONL + 行业/金额等简化筛选；文件注释不证明已建向量库
默认团队模式	backend/data_layer/team_experience.py	内置频次/阈值为代码默认样例，不是真实兴邦统计
模型与组件治理	backend/services/component_registry.py、component_evaluation.py	复用版本和验证机制

2. v2 拟议模块边界

以下是设计目标，尚未生成对应文件或调用链。owner 指代码唯一职责，人员待项目负责人分配。

模块 / 拟议落点	职责	依赖 / 禁止
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 校验、预算、失败状态	通过出口策略；不写审批或综合结论
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/可切换专项判断 → 验证证据与规则 → 主审综合预审 → 独立复核/正式审批入口。

历史经验用于选择核查动作和比较适用条件，不能用“相似案例通过”直接推出当前项目通过。专项模型的判断置信与主审解释都不是独立的真实性认证。

3. 数据模型与持久化

P0 候选使用现有 SQLite 事务存储承载新增对象类型。历史事件、经验版本、运行、判断、模拟和评测各有唯一 owner。schema 变更追加迁移，保留旧表；完整 DDL 与兼容策略在详细设计阶段定案。

本轮“v2”指产品代际。既有 xingbang_v2.py 和 schema_v2 是历史实现命名，不应重命名或删除。

材料保存原件哈希、段落/页码、发生时间和录入时间。经验同时记录来源事件、制度版本、专家确认及有效期。只持有最终批复的案例应标“过程不完整”。

演示和真实数据域分别存储或通过受测权限边界隔离；生产隔离架构未确认前只运行演示数据。版本冻结后撤回经验不删除历史记录，但新运行不得再应用；旧结果需标记失效经验并提示复核。

4. 关键流程与恢复

• 历史导入失败：保留原件和失败事件，允许补充/重新提炼，不伪造缺失过程。
• 主审识别矛盾：记录待核查事项，使用授权证据工具验证，达到预算停止为 partial/awaiting_input。
• 所选专项模型不可用或关闭：缺失项进入 degradations；主审只能依据已完成检查给出有限意见。
• 硬规则冲突：结果校验阻断建议推进，保留模型原始结构化提案供审计。
• 新证据进入：产生新快照、新运行，旧结果保留；模拟不进入这条正式更新路径。
• Worker 恢复：复用持久任务机制；幂等范围包含 actor/project/operation/key，禁止重复生成运行。

5. 接口与集成

内部 API 以 /api/prescreen 为候选命名空间；沿用当前项目鉴权和同源代理。前端不能直接访问模型厂商。现有 assistant_model 的受信端点规则不自动适用于 Jev，专项模块需独立出口与域策略；local 也只能使用管理员批准的端点，不能从浏览器传入任意 URL。

Jev 接口概念参考 TypeSafe 官方文档：https://docs.typesafe.ai/introduction 、https://docs.typesafe.ai/confidence 。当前没有 SDK 安装、Key、版本或延迟实测；实施前重核版本与中文金租样本效果。Jev 是可选提供方，本地开源模型通过独立适配器执行同一业务任务；拿不到 Jev Key 不阻塞本地路径。统一契约和差异处理见 专项判断模型切换。

概率预测为后续独立模型，输入仅使用预测时可得事实和判断特征。主审解释模型输出但不能改写原始概率；目标事件已明确为公司评审会通过；结果代码/时点/样本偏差和校准验证未明确前 probability=null。

6. 副作用边界

真实数据外发、经验发布、正式审批是不同权限。模型只能读冻结事实和生成候选意见；发布经验由授权人操作，正式审批不在 v2 自动化范围。普通聊天的终端/文件工具不能进入预审工具白名单。

2026-09-29本轮更新仅为文档写入；Gitea备份需另以本轮SHA核验记录为准；没有模型数据外发、云端部署、数据库迁移或镜像发布。

7. ADR

ADR-01 保留现有技术基线，按模块增量扩展，否决全面换框架。 ADR-02 主审综合判断+确定性约束+可切换专项复核，否决单模型 yes/no 审批。 ADR-03 经验以过程和来源为核心，否决只按最终结果记忆。 ADR-04 经验发布复用现有治理，否决自动从反馈直接生效。 ADR-05 先做验证和数据合作，再建设概率校准，否决专家分数转百分比。 ADR-06 v2 独立目录与资源，旧版保留；本轮先文档后迁移，目录尚未创建。

状态、影响和未决项统一维护在 决策记录。

8. 拟建立的架构验证

业务 service 不导入 src；预审工具集合不含 terminal/任意 SQL；跨域经验不可检索；引用必须属于授权快照；模拟不修改真实快照；无校准时概率为 null；经验发布只能经过一个治理入口。专项模型只能通过统一接口接入；local 不依赖 Jev 凭据；配置冻结且故障不自动切换。映射 AC-04/06/08/10/11/12/16/17/18/19/20/21。

这些是待实施的机器检查；现有测试覆盖另列，不能标成 v2 已通过。

9. 三模块目标分层（未实现）

文件集合/授权数据源 → 证据与事实层 → 冻结快照
历史开发案例 → 时间线/经验候选 → 人工编辑与统一发布 → Skills/Rules
数据卡 + 已发布Skills/Rules → 评审方案与维度 → miniOpenClaw受控编排
受控编排 → 确定性Tools/Rules + 可选专项判断 → 主审建议与补件
冻结运行 → 独立沙盘 / 可回放trajectory
trajectory + 对应材料版本的会议结果 → 改进候选 → 固定对照/审核 → 新版本
概率模块：独立消费当时可得事实与核查特征，P0真实概率为空

新增职责：material_import负责集合清单而不另造上传链；review_plan负责装配与维度版本；trajectory复用运行审计；review_outcomes拥有会议原始结果和映射；improvement复用经验/组件发布入口。详细对象owner见03第9节，不再为每个页面建立一套业务服务。

本地Laya部署为独立模型服务，后端通过judgment_provider的任务契约访问；其依赖不混入旧版venv。主审、专项、概率三类模型配置彼此独立。厂商模型不能写正式规则、概率或审批状态。每次run固定方案、证据和全部模型配置，撤销权限在实际调用前重验。

编排可以在方案授权范围内由模型决定先查什么、调用哪个Skill；必查项、硬规则、工具权限、预算和发布门禁由程序强制。初期改进针对知识/题库/编排配置，训练主审权重不在P0。

对应ADR-09–14；当前没有新增服务/迁移/模型进程，目标图不能作为运行事实。