mini-openclaw/docs/兴邦金租系统改造书-v1.0.md

兴邦金租对公项目助手——系统改造书

版本：v1.0｜日期：2026-09-10｜基线提交：c57d291

适用仓库：F:/mini-OpenClaw-local-stable

文档性质：基于会议原稿、当前代码与本轮讨论形成的实施设计。本文中的“新增”“目标”“验收”均指待实施工作，不代表功能已经完成。本次仅交付改造书，不实施业务代码变更。

阅读建议：产品与范围看第 1—4 章；核心架构和组件实现看第 5—12、15—17 章；经验进化与演示看第 13—14 章；实施排期、验收和回退看第 18—22 章。当前可用能力与缺口集中在第 3 章。

1. 改造决策与项目定位

在现有 Python mini-openclaw 上增量改造，保留 AgentManager 作为模型与工具调用核心，保留 Next.js + FastAPI 技术栈。将现有按四 Agent 展示的工作台，整合为以项目为中心的对公业务助手。

产品承诺：选择项目，自动整理材料、执行检查、指出有依据的问题；补件后更新结果，支持方案比较，形成可修改的底稿，并把人员处理经验用于后续适用项目。

系统的灵活性由可插拔的数据源、Skills、规则、自然语言要求、报告模板和业务方案提供。业务人员看到简单入口，管理员维护组件，mini-openclaw 组织组件执行。

1.1 已确认约束

1. 必须使用本项目自己的 mini-openclaw；不换成外部 Agent 平台，也不另建绕过核心的生成链路。
2. 目前拿不到兴邦真实数据；先用完整模拟档案贯通业务，真实对接不作为开发前提。
3. 模拟的是输入资料和演示制度，查询、检查、计算、版本对比、导出和经验复用必须真实执行。
4. 保留可用模块，小步迁移；当前不存在的旧页面不恢复。
5. IT 统一配置连接与访问策略，业务人员不反复配置。权限在后台持续执行。
6. 自然语言可表达本次任务、编辑配置草案，不能静默改变正式制度或扩大工具权限。
7. 首版必须包含可展示的经验闭环；自动生成改进建议可以先做，模型训练和自动修改生产代码后置。

1.2 首期范围与后置范围

首期必须交付	后续扩展
项目材料接入、统一快照、问题清单、补件更新	全公司所有数据域的治理与迁移
有限参数的方案比较、可追溯底稿、Word 导出	完整定价优化、自动授信审批和 ERP 写回
可配置业务方案、原生 Skills、规则与模板	任意可视化工作流搭建和插件市场
人工反馈、经验提炼、审核、适用场景复用	自动生成并上线可执行代码、模型微调
模拟数据包、配置替换演示、版本回放	全量租后监控、外部付费征信持续订阅

“完整业务流”在首期指助手范围内的检查—补件—方案—底稿—经验闭环，不意味着复刻合同、放款、会计和催收等整个 ERP。

2. 会议需求依据及优先级

来源：仓库 ori_file/兴邦金租会谈-2026.8.18 (1).md。以下时间为录音时间，转写含有错字，涉及正式业务口径时仍需客户确认。

时间	会议事实或共识	改造要求
03:34—05:16	有客户保护权、权限分配、项目全生命周期信息	复用项目身份与关联关系，不做全员共享大库
10:19—14:46	现有评级模板主要线下使用，评级以参考为主	预留既有模型与模板适配，不自创权威评级
39:54—45:24	人员紧缺，耗时集中在资料、测算和报告；判断尺度有差异	统一事实、检查要求与证据表达，保留专业裁量
43:18—43:27	财报已有导入能力	重点在导入后的核对、分析、复用
48:01—51:14	尽调报告正在标准化，行业手册主要在线下	将手册转成有版本的检查要求
48:45—50:01	提前提供风险关注点，让业务经理先核实，不预先下审批结论	首发场景为送审前检查和补件
01:00:56	评审周期约 16—17 工作日	分开衡量人工处理、等待、补件；不承诺全周期压缩至一天
01:57—02:03	IT 关注个人/共享资料、权限和数据体系；已有公司级数仓	数据源优先复用可用数仓或只读视图，附件纳入同一权限体系
02:04—02:14	接受先用小助手，逐步扩展	首期界面简单，保持原业务审批责任体系
02:21:09	提效、积累经验、减少人员审查差异	验收同时覆盖效率、经验复用和检查一致性

保险条款检查保留为专业 Skill 扩展；会议未确认其是主要损失来源，不作为唯一卖点。120% 等会议提及数值不得直接写成通用正式标准；演示规则必须显式标注。

3. 当前系统审计与保留清单

本节为静态代码核查结论；真实 ERP 连通、模型质量和客户业务适用性均未因存在代码而得到验证。仓库已有历史测试留痕，但历史通过不等于新功能验收通过。

现有位置	已核实能力	处理决定
backend/graph/agent.py	build_task_agent、invoke_scoped 共用 Agent 工厂；显式模型/工具输入；通用聊天流式事件	必须保留；增加异步业务任务上下文和统一结构化结果适配
backend/graph/risk_task.py	业务任务调用 AgentManager.invoke_scoped，读取所选原生 Skills，并检查必需工具调用	保留为兼容适配器；逐步接到通用任务执行服务
backend/tools/risk_task_tools.py	只读授权快照，工具不直接操作生产数据库，任务输入深拷贝	保留隔离设计；扩展项目附件、经验和计算工具
backend/tools/skills_scanner.py	发现原生 SKILL.md，生成目录	保留格式兼容；新增 manifest 校验、版本和内容哈希
backend/api/risk_agent_config.py	连接/数据卡/Skills/规则/方案配置、发布审核、运行存档、自然语言规则	保留 API 和数据迁移入口；按服务拆出注册、执行、存储职责
backend/api/risk_agent_connectors.py	PostgreSQL/MySQL/SQLite 连接路径、只读 SELECT、允许表、限行超时、服务端凭据引用	保留；新增统一数据源适配接口及连接验收，不宣称 ERP 已接通
backend/api/risk_agent_alignment.py	期间、口径、单位、项目标识检查，多期数据保留	保留并补强精确金额和字段级来源冲突处理
backend/api/report_agent.py	快照底稿、章节锁定、模型候选稿、版本检查、Word 导出、经验状态流转	保留；将模板配置化，补章节依赖、更新差异和统一经验实体
backend/api/coordination_agent.py	补件任务、人员推荐、人工流转、方案版本及摘要	复用任务和方案结构；人员分配不作为首期主入口
backend/api/collateral_agent.py、collateral_checks.py	租赁物及增信核验、版本失效、PDF/图片/TXT 读取、条件式本地 OCR、材料下载	复用核验和文档能力；提取通用附件服务，避免只在租赁物模块能上传
backend/api/xingbang_projects.py	跨模块项目索引和快照关联	作为新项目总览的迁移起点
backend/api/risk_agent_access.py	服务器令牌身份、manager/reviewer/admin，manager 项目范围限制	保留接口；升级所有业务角色的资源授权。当前不是完整 ERP 权限继承
backend/data_layer/history_store.py、team_experience.py	案例存储、频次统计、经验 JSON 更新	作为旧数据导入来源；不能视作已经实现自学习
backend/graph/memory_indexer.py、raw_trace.py	通用记忆检索、调用轨迹记录	复用技术；业务记忆不能直接混入全局个人 MEMORY
src/app/*-workbench、data-access、trajectory	已存在项目、配置、报告、协同、核验、轨迹页面	复用组件，逐步统一入口和项目上下文
scripts/verify.py、部署配置	后端测试、前端构建、Compose 校验、可选容器验证与日志留痕	保留为每阶段验证门槛

3.1 必须解决的结构缺口

1. 配置化执行集中在风险 API 的固定分支；还不是通用 Skill 注册与依赖执行机制。
2. 当前工具读取校验只能证明“调用过”，不能证明输出逐条正确；需要结构校验和有效证据检查。
3. 数据卡、多期记录和报告已有快照，但尚缺统一项目附件、字段依赖和问题延续机制。
4. 新数据导致结果失效已有局部实现，尚未贯通问题、方案和报告章节。
5. 经验卡有审核状态，缺少反馈分类、适用条件检索、实际执行关联及对照评测。
6. 旧 xingbang_* 等 API 仍在 backend/app.py 注册。须盘点调用方后兼容迁移，不能因前端不显眼就直接删除。
7. 通用聊天与业务任务采用不同模型配置和工具范围。业务界面必须走受控业务链路，避免绕到通用终端/文件工具。

4. 产品信息架构与日常使用

4.1 业务入口

首页：我的项目、待处理事项、新建演示项目/上传材料。项目详情采用同一个页面框架，保留项目名称、数据时间、当前运行状态和身份上下文。

项目页提供“概览、材料与问题、方案比较、报告、经验记录”五个页签。前三个主操作固定为“检查项目”“补充材料”“生成底稿”；方案比较在项目方案区展示。自然语言输入作为辅助，可说“重点核对现金流”，不要求用户会写提示词。

结果默认展示未处理问题、依据、建议下一步；技术执行日志折叠到“查看执行依据”。系统只展示记录到的事实、工具动作和解释，不承诺暴露模型内部思考。

4.2 角色体验

角色	高频动作	配置职责
客户经理	检查本项目、补件、说明、生成尽调草稿	无需配置 SQL、Skills 或模型
主审员	核对证据、处理分歧、测算、评审底稿、贡献经验	提出规则/模板/经验调整
业务规则负责人	核对规则适用条件、发布业务方案与经验	维护业务口径，不负责数据库凭据
IT 管理员	数据源、映射、模型、权限与系统运行	不凭管理员身份自动获得所有项目资料

首期演示使用预置身份与项目授权；权限职责与业务角色分开建模，之后接 ERP 身份系统。

4.3 不增加使用负担的要求

• 从项目进入时自动携带项目 ID、默认方案和当前材料版本。
• 缺数据直接列明缺什么，支持继续完成不依赖该数据的检查。
• 补件后显示“已解决、仍待核实、新增、需重新判断”，不整页覆盖结果。
• 报告候选更新按段落查看，已经人工确认的内容保留。
• “保存为经验”由系统预填；用户只核对关键内容和共享范围。
• 真实调用慢或失败时展示阶段和可重试操作，不使用虚构进度百分比。

5. 目标架构：在 mini-openclaw 内扩展业务运行能力

flowchart TD
    UI[项目工作台与自然语言入口] --> API[FastAPI 身份与项目 API]
    ADMIN[配置后台] --> REG[版本化组件目录]
    API --> RUN[业务任务服务：冻结版本、检查依赖、保存状态]
    REG --> RUN
    RUN --> CORE[现有 mini-openclaw AgentManager]
    RUN --> DET[确定性 Skill 与规则执行器]
    CORE --> TOOLS[本次任务授权工具]
    TOOLS --> DATA[统一数据与附件快照]
    TOOLS --> EXP[已发布且有权访问的经验]
    TOOLS --> DET
    DET --> VALID[结果结构与证据校验]
    CORE --> VALID
    VALID --> OUT[问题、方案、底稿与执行记录]
    OUT --> UI
    DATA --> SOURCES[模拟数据 / 文件 / ERP / 数仓适配器]
    UI --> FB[人工修改与反馈]
    FB --> CAND[经验与组件改进候选]
    CAND --> EVAL[隔离评测与业务审核]
    EVAL --> REG
    EVAL --> EXP

业务任务服务是现有核心外围的执行保障，负责状态、依赖、检查、预算和结果保存，不替代 Agent。模型选择、工具调用循环和模型型 Skill 统一由现有 AgentManager 入口承载；确定性计算直接调用 Python 执行器。

首期采用模块化单体：FastAPI、现有数据库/附件存储、一个可恢复的业务任务 worker。无需先引入微服务、分布式消息集群或图数据库。SQLite 可用于单机模拟环境；多实例或较大并发时再迁移业务存储到 PostgreSQL，这与“连接客户 ERP 数据库”是两件事。

6. 可插拔组件协议

6.1 统一元数据

所有组件声明 id、kind、version、schema_version、status、owner、description、content_hash、effective_from、scope、dependencies。发布版本不可原地覆盖，运行记录保存准确版本和内容哈希。

组件种类：data_source、data_card、skill、rule_set、plan、template、experience。草稿可编辑；发布后修改产生新版本。系统配置数据库维护发布内容快照，磁盘 SKILL.md 是编辑和导入来源，避免两套可变内容同时成为运行事实来源。

6.2 原生 Skills 与业务能力统一

保留 backend/skills/*/SKILL.md。为缺少 manifest 的现有 Skills 提供兼容默认值；新 Skills 增加结构元数据，正文保留自然语言方法。目录里的 skill_id 作为旧别名，发布后使用稳定组件 ID。

id: corporate.financial_consistency
kind: skill
version: 1.0.0
schema_version: 1
status: draft
executor: hybrid
description: 对照财报与尽调材料，形成有来源的数据差异
input_schema: ProjectSnapshot.v1
output_schema: SkillResult.v1
required_inputs: [financial_statements, documents]
optional_inputs: [historical_findings]
allowed_tools: [read_project_snapshot, read_document, compare_fields]
depends_on: [corporate.document_extract]
timeout_seconds: 60
max_tool_calls: 12
side_effects: none

该 YAML 为目标示例，当前扫描器不会执行其中的全部字段。executor 首期支持 python、model、hybrid；规则执行器单独注册。Python 入口从服务器受控映射表解析，不接受上传字符串任意 import/eval。安装新的代码执行器需走开发测试；已有执行器参数和原生方法正文支持后台配置。

6.3 Skill 输出协议

{
  "schema_version": 1,
  "run_id": "run-demo-001",
  "step_id": "step-finance-01",
  "skill": {"id": "corporate.financial_consistency", "version": "1.0.0"},
  "status": "completed",
  "input_snapshot_id": "snapshot-demo-v1",
  "outputs": {},
  "findings": [{
    "code": "financial.liabilities.conflict",
    "result": "issue",
    "severity": "attention",
    "title": "负债金额来源不一致",
    "evidence_ids": ["e-finance-b12", "e-report-p3"],
    "basis_ids": ["demo-rule-consistency@1.0.0"],
    "suggested_action": "确认报表期间、口径及材料版本"
  }],
  "missing_inputs": [],
  "errors": []
}

步骤状态 completed/partial/failed/skipped 与检查结果 pass/issue/unknown/not_applicable/error 分离；执行完成不等于业务检查通过。重要数字使用计算输出，引用必须在授权证据集中存在。校验失败时允许有次数限制的结构修复；仍失败则保存未完成状态，不把自由文本当成合格结果。

6.4 规则协议及自然语言入口

类型	执行与维护方式
硬规则	字段、运算符、阈值、单位、期间、适用条件，确定性执行
语义规则	明确检查问题、所需依据、输出状态，模型辅助判断
专家裁量项	汇总证据及不同处理思路，留待授权人员判断
经验提醒	匹配适用场景后提出核实动作，不自动变为制度

自然语言入口分为本次要求和配置草案。“报告简短些”作用于本次输出；“以后增加一项检查”生成规则草案，展示解释后的条件、影响范围和测试结果。草案在发布前不修改正式方案。正式规则的强制要求优先于经验和本次偏好；无法同时满足时指出冲突，不能静默折中。

6.5 业务方案协议

方案包含适用项目、数据卡、必做 Skill、可选 Skill、规则、模板、停止条件和运行预算。发布前校验依赖存在、版本已发布、输入类型兼容、循环依赖、输出字段冲突和工具权限。

首期使用带依赖的步骤列表，无需拖拽画布。必做步骤由程序调度和核查，Agent 仅能在方案允许的可选能力中选择或追加。数据卡仍是平级数据来源；依赖图描述处理步骤，不强迫所有数据卡构成串行链。

7. 数据层：模拟到真实的统一合同

7.1 数据对象

对象	主键与主要内容
Project	内部 ID、外部项目号、客户 ID、行业、阶段、归属
Customer / RelatedParty	客户、集团成员、担保人及关联类型；不以名称作为唯一键
FinancialStatement	主体、期间、合并/母公司口径、币种、单位、版本、科目值
FinancingScenario	金额、期限、利率、还款方式、假设及关联基准方案
LeaseAsset / Guarantee	设备标识、评估记录、担保或保证金证据，避免重复计入
CreditEvent	事件、来源和截至日期；空集合不直接等于已查无异常
Document	文件哈希、类型、版本、页/段/单元格定位、所属项目、可见范围
ProjectSnapshot	本次运行冻结的事实、附件版本、来源和映射版本

连接器合同至少包含：连接测试、能力描述、项目读取、对象读取、附件清单和读取、源版本/更新时间信息。API、SQL、文件和模拟适配器返回同一协议。只读 SQL 路径复用当前实现，模型不自行拼 SQL 查询生产库。

7.2 口径、时点及来源

每条事实记录原始值、标准值、单位、币种、期间、口径、来源标识、抓取时间、源更新时间、证据定位和转换版本。金额内部用 Decimal 或整数最小单位，JSON 用十进制字符串；比例精度、舍入方式由指标定义。

未知值用 null 加原因；0 是明确数值。不能静默把母公司与合并口径、不同币种、不同期间相加。无汇率来源时不进行跨币种折算。多来源不一致保留双方证据，通过明确来源优先级或人工确认产生覆盖记录，不删除原始材料。

ERP 多表不一定支持一致性读取：能用事务快照就采用；否则记录各源读取时间和最大时间差，超出配置容差则标记混合时点待核实。数据层切换真实来源须做合同测试和对账，不宣称换一个连接字符串就完全完成。

7.3 一次配置的实际边界

IT 首次配置连接、只读视图、字段映射、附件地址、同步策略和权限来源；业务人员之后复用。字段结构变化、组织变动、凭据轮换和新数据域仍需维护。

接入顺序：先询问已有数仓/专项视图是否满足；其次 ERP 只读视图或接口；临时文件接入始终保留。只接首期所需数据，不要求先完成全公司的统一数据平台。

8. 附件与证据服务

从现有租赁物模块提取通用材料服务，旧接口继续委托调用。首期支持 PDF、DOCX、XLSX/CSV、TXT 和图片；每种支持程度通过 capability 返回，解析器未安装或 OCR 不可用时明确标记。

流程：接收文件 → 计算哈希和版本 → 识别类型 → 读取文本/表格或 OCR → 生成可定位证据 → 提取候选字段 → 校验 → 纳入新项目快照。

PDF 使用页码及必要坐标；DOCX 使用段落/表格/单元格位置，不虚构稳定页码；Excel 使用工作表和单元格。表格公式保留公式及缓存值，缺少可靠值时不编造计算结果。扫描识别不确定的关键金额需人工核对。

文件处理与执行脚本分离，不运行附件宏。证据、原件、提取文本、向量索引和下载均继承项目可见范围。材料含有指令性文字时仍按证据处理。

演示附件必须可真实打开、解析、定位；不能只在前端显示文件名，后端读取另一份预写答案。

9. mini-openclaw 运行机制

9.1 一次任务的执行顺序

1. 校验身份、项目、操作和组件权限，创建 run_id，记录用户要求。
2. 解析方案并冻结所有依赖版本、模型配置标识、经验版本和任务预算。
3. 读取授权数据，生成不可变项目快照；尚未取得的数据标注缺失。
4. 检查依赖，执行必做的数据校验、提取和确定性计算。
5. 检索适用经验；Agent 在可用工具集合内追加必要核实与分析。
6. 语义分析、报告草稿等模型型步骤通过 AgentManager 执行。
7. 检查结构、证据、计算引用与必做项覆盖；不完整步骤如实记录。
8. 保存问题、计算、建议和执行事件，发布运行完成/部分完成状态。

9.2 运行状态与恢复

queued → running → completed / partial / failed / cancelled；等待补充材料为 waiting_input。waiting_input 不占 worker；补件后创建带 parent_run_id 的新运行，旧快照和结果保留。

同步接口逐步改为“创建任务返回 202 + run_id”。任务状态持久化，支持 SSE 和断线后的事件补读。SSE 断线不取消任务。客户端显式取消只阻止后续执行；无法中止的外部调用结果不再发布到已取消任务。

首期 worker 使用数据库领取任务和租约心跳；重启后识别中断状态。读取、计算步骤可重试；写入任务、保存报告等副作用使用幂等键，禁止因重试重复创建。模型请求超时不假装成功，已完成的确定性结果仍可展示。

每个步骤记录输入摘要、输入哈希、执行器版本、尝试次数、开始/结束时间、状态、输出位置和错误码。对不确定完成状态保留 interrupted，不盲目重放副作用。

9.3 固定要求与灵活执行

程序负责强制检查、权限、计算和状态；Agent 负责理解补充意图、选用可选能力、解释材料、组织结果。预算包括超时、模型调用次数、工具次数、输入长度和输出大小，不允许无界自循环。

现有 invoke_scoped 的工具隔离原则保留，新增业务上下文含 actor_id、project_id、run_id、snapshot_id、allowed_tools、component_versions。不得修改全局模型/工具来切换项目，避免并发任务互相影响。

9.4 模型与演示运行模式

• 正式演示使用真实模型调用，记录所用端点配置标识和模型名称，不硬编码品牌依赖。
• 优先兼容已有 ChatOpenAI 内网路径；把配置从风险 API 提取到业务模型适配服务，旧入口继续调用。
• 企业模式只使用经 IT 配置的数据处理路径；推理、OCR、嵌入、日志分别列明部署位置。内网地址不能单独证明服务下游没有外发。
• 无模型时运行确定性检查，并标记语义部分未完成。固定回放可用于测试或讲解，但必须显示“回放”，不能伪装实时智能分析。
• 单元测试可用当前 ToolModel 风格的可控模型；演示验收另跑真实模型，不用单元测试替代质量验证。

10. 问题清单、补件与增量更新

10.1 问题是业务实体

Finding 保留稳定 ID、项目、对象、规则/经验来源、证据、首次/最近出现运行、当前状态、责任人、处理意见和处理记录。标题文字不是唯一键。

初始业务状态：待处理、待补件、待复核、已解决、不适用。机器检查状态与人工处理状态分离。用户关闭问题必须留下处理依据；“不适用”要记录原因，不能默默删除。

10.2 补件如何闭环

用户在问题上点击“补充材料”，自动关联问题和项目；同一文件可关联多项问题。系统解析新材料生成新版本，触发受影响检查，产生“解决、保留、新增、重新打开”的差异摘要。

问题匹配采用对象 ID + 稳定检查 code + 适用范围；涉及规则版本语义变化时标记需迁移匹配，不仅比较标题字符串。不能仅因新结果没提到旧问题就关闭，必须确认原检查仍执行且有解决依据。

10.3 增量执行与保守回退

维护依赖链：字段/材料 → Skill → 规则/经验 → Finding → 报告章节。输入或组件版本变化时，将下游标记 stale。无明确依赖声明的语义 Skill 先视为依赖整个项目快照，宁可重跑，不遗漏影响。

复用旧计算仅限输入哈希、执行器/规则版本、权限范围一致。复用结果明确记录来源 run_id；最终输出是新快照下的新结果包，不改写旧包。人工覆盖值和确认意见若受变化影响，提示重新确认，不直接覆盖。

11. 方案比较与租赁物能力复用

保留现有 coordination 的方案版本及 collateral 的确定性核验能力，将方案建模为独立 Scenario。用户通过表单或自然语言提出调整，系统先展示识别出的参数变化，再创建情景版本。

首期最低范围：调整融资金额，比较同一评估时点下的租赁物价值覆盖比例；条件具备后增加期限、利率和明确还款方式下的还款计划、现金流覆盖比较。

每个指标明确分子、分母、单位、期间、公式版本和必要假设。“租赁物价值/融资金额”与“可用于还款现金流/应偿本息”是不同指标，界面不可混称覆盖率。保险、担保、保证金不能无依据简单相加后宣称风险已覆盖。

对比结果显示原方案、情景方案、指标差异、问题变化、仍缺材料和假设。没有回款时间表时不输出精确偿债结论；没有客户内部模型和口径时，不声称计算结果已符合兴邦实际租金测算。

用户确认前不改变原方案；确认采用后生成新方案版本，并使相关底稿和检查失效待更新。首期不写回 ERP 正式授信或审批结果。

12. 底稿与报告服务

保留现有 Word 导出、人工章节锁定和模型候选稿机制。将代码内固定模板逐步转成版本化模板，首期提供尽调草稿、评审底稿和上会摘要三种交付形态。

模板定义章节、必需事实、引用方式、适用角色、可编辑区域、篇幅和缺失值表示。明确“尽调材料”与“主审内部判断”的访问范围。

生成过程从同一次运行的结构化结果取值；事实数字由程序填充，模型只撰写允许的文字部分。导出包含数据截至时间、方案版本、来源摘要、草稿/定稿状态和演示标识。不得在正文中混入 SQL、插件路径、模型参数等技术信息。

数据更新后按章节依赖生成修改建议；已确认章节保留旧内容并标记可能过期，由人员选择接受或继续保留并说明理由。正式报告保留当时快照，不因后续规则升级而被后台改写。

Word 导出验收包含页面渲染和视觉检查：表格不越界、长中文正常换行、证据标号可对应、草稿/演示标签清晰。报告文字质量用业务检查表评价，不仅检查能下载文件。

13. 经验沉淀与可验证进化

13.1 反馈来源与分类

FeedbackEvent 记录项目/run/问题/章节、修改前后、作者、原因、证据、发生时间和共享意愿。支持主动“保存为经验”和系统在定稿后自动提出候选，不要求每个动作都弹窗。

分类：表达偏好、事实纠正、补充数据、规则遗漏、规则误报、专业判断、流程建议。修改文字不自动等于纠正了专业结论；多次重复意见只作为候选信号。

13.2 经验卡结构与状态

经验卡包含标题、适用行业/阶段/对象、触发条件、建议动作、不适用条件、原始依据、支持与反例、共享范围、版本、审核者、有效期、替代关系、审批结果及租后观察窗口。

状态：草稿 → 待确认 → 已发布 → 暂停/过期/归档。业务共享审核复用现有机制；“有租后观察”单列证据状态，不仅凭填写一段结果就给经验永久贴上“正确”的标签。

批准案例、否决案例、待定案例及失败案例都可以记录；批准不等于好经验，否决不等于坏经验。不得从审批结果直接推断因果。

13.3 应用方式

先按主体权限、模拟/真实域、状态、有效期、行业和阶段过滤，再检索语义相似内容。项目私有经验默认不跨项目泄露；发布可共享经验时核查其中可识别资料并限定可共享内容。

经验被使用时生成 ExperienceApplication：经验版本、匹配理由、触发输入、调用的 Skill/新增检查、执行结果和用户反馈。可见提示为“依据某条已确认经验，增加了哪些核实动作”。只引用一段案例文字不计为执行改进。

同类专家意见冲突保留不同条件与来源，提交负责人处理；不得自动投票改成正式规则。现行制度优先，过期经验可保留历史回放但不默认参与新任务。

13.4 组件改进闭环

系统复盘反馈 → 提出 ImprovementProposal → 创建候选组件版本 → 在隔离样例集回放 → 比较旧版与新版 → 业务/技术审核 → 发布 → 观察 → 必要时回退。

ImprovementProposal 包含目标组件、原版/候选版、修改理由、支持案例、例外场景、差异、评测结果和风险范围。首期自动候选限定为规则条件、Skill 方法说明、方案步骤和模板要求；可执行代码变更通过开发流程处理。

个人偏好由用户明确表达后仅在个人范围生效；团队经验与正式规则需发布。正式规则发布复用现有编辑/审核分离，不额外给日常每次检查增加审批。

13.5 评测设计

固定留出集不用于提炼候选，包含正例、反例、缺材料、过期规则及相似但不适用场景。比较检查召回、误报、引用有效性、人工修改、延迟和调用成本；不同目标不合成来源不明的“智能分”。

确定性任务要求固定结果；模型输出允许措辞差异，按结构与业务条件评价并多次运行观察波动。候选不得仅由同一模型自行打分通过。真实业务经验生效后仍需真实观察，模拟评测不能证明降低坏账。

每次发布冻结组件版本；正在执行任务和历史定稿不跟随变化。回退切换后续运行的发布版本，已生成报告和记录保留。

14. 模拟数据与演示剧本

14.1 模拟体系

新增版本化 fixture 包，放在专用测试/演示目录。每个包包含结构数据、可打开附件、检查规则、业务方案、预期结果、变更事件和生成脚本。数据按固定种子生成，金额/报表勾稽由程序校验。

预期结果仅供测试使用，业务 Agent 不得读取 ground truth。演示重置只作用于明确的演示实例；模拟 ID、经验、索引和报告均携带 data_domain=demo，不能混入真实域。

14.2 三类项目与受控变化

项目	初始场景	后续事件	预期能力
DEMO-A 标准制造项目	材料齐全、口径一致	仅改一处报告表达	正常完成，不硬找风险；只学习表达偏好
DEMO-B 设备项目	财报与尽调冲突、现金流缺项、重复设备	补交新版财报，修正设备清单	引用定位、部分解决、重新测算、保留未完成项
DEMO-C 回款依赖项目	存在某种收入确认但到账依据不足	专家提出补件经验，随后新建符合条件/不符合条件的变体	提炼经验、审核、跨项目复用及适用边界

建议演示金额：设备去重后价值 5,400 万元，原融资金额 5,000 万元，覆盖比例 108%；模拟阈值 120%。情景金额调整为 4,000 万元后比例 135%。界面标明示例阈值，且这一变化不能自动解决缺失现金流资料的问题。

至少再准备数据源失败、模型不可用、OCR 失败、无权项目和中途重启五种异常，用于验收与解释边界。

14.3 一次演示顺序

1. 打开 DEMO-B，点击检查，展示实际执行步骤。
2. 点开金额冲突，定位原附件或单元格；让客户看到依据。
3. 上传补件，展示问题差异，保留仍需人工核实事项。
4. 调整融资金额，比较指标与问题变化，原方案保留。
5. 导出 Word 底稿，展示已核实事实和未解决事项。
6. 专家补充一条处理经验，查看系统提炼的条件，完成演示审核。
7. 新建适用项目触发经验，再打开反例展示不机械套用。
8. 管理后台替换规则/模板/Skill，展示同一数据上的可解释变化。

真实模型耗时受端点和材料规模影响，演示时展示实际耗时，不预写秒数。可准备固定回放用于故障讲解，但入口清晰区分“实时运行”和“历史回放”。

15. 权限、数据使用与操作边界

一次配置是用户体验目标，后台每次读写仍校验主体、项目、操作及数据域。以现有 authorize 为迁移入口，对所有角色应用资源范围，不继续沿用“仅 manager 限项目、其他角色自然全可见”的简化模式。

权限资源包含项目、附件、运行结果、报告、经验、检索索引、执行轨迹、下载和后台任务。后台任务继承发起者权限；运行期间权限被撤销时，后续读取/发布重新检查。已冻结的数据不因此自动允许向失去权限的用户返回。

IT 连接凭据仅留服务端；组件内容不携带密码。通用聊天、文件浏览及调试日志保留为受限开发功能，正式业务入口不得绕过业务资源边界。项目会话与全局 MEMORY 分离，生成结果、缓存、检索和日志均携带范围信息。

模型调用和长日志可能包含业务数据。生产配置记录必要证据与动作摘要，原始报文访问、脱敏及保留周期由 IT 配置；不把 API key 过滤等同于业务资料已脱敏。

首期所有 ERP 接入只读，外部邮件/消息、审批、放款、写回等副作用不在默认能力范围。系统可生成补件文本和本地任务，不自动向客户发送。

16. 数据存储与接口设计

16.1 逻辑实体

实体组	建议实体
项目与数据	projects、external_id_mappings、project_members、documents、document_versions、snapshots、evidence
配置	components、component_versions、release_records
执行	runs、run_steps、run_events、run_component_versions、artifact_dependencies
业务产物	findings、finding_events、supplement_tasks、scenarios、report_versions
经验进化	feedback_events、experiences、experience_versions、experience_applications、improvement_proposals、evaluation_runs

以上是逻辑模型，不要求首期全部建立独立大表。先复用现有 SQLite 与 JSON body；为查询、授权、关联、版本和状态建立必要列/索引。正式报表事实与组件发布版本不可被随意覆盖。

16.2 新增接口建议

使用统一前缀 /api/xingbang/project-assistant；旧 /api/xingbang/risk-agent 保留适配。以下为待实现契约，不是现有可调用接口。

接口	用途
GET /projects、GET /projects/{id}	授权项目列表和详情
POST /projects/{id}/documents	上传、关联问题并创建解析任务
POST /projects/{id}/runs	选择方案/快照及本次要求，返回 202
GET /runs/{id}、GET /runs/{id}/events	状态和 SSE/增量事件
POST /runs/{id}/cancel	显式取消
GET /projects/{id}/findings、POST /findings/{id}/actions	问题清单与人工处理
POST /projects/{id}/scenarios、POST /scenarios/{id}/compare	创建情景并比较
POST /projects/{id}/reports、GET /reports/{id}/export	创建报告和导出
POST /feedback、POST /experiences/extract	反馈和经验候选
POST /experiences/{id}/publish	授权审核共享
POST /improvements/{id}/evaluate、POST /components/{id}/release	候选评测和发布

写操作使用对象 revision/If-Match 和必要幂等键；冲突返回 409，权限 403，输入 422。结果未完整不只依赖 HTTP 成功码判断，必须读取业务状态。

16.3 旧数据兼容

建立旧项目、run、报告和经验 ID 到新实体的映射；旧报告保留 source_id。新字段缺失以 legacy/unknown 标注，不猜造过去的组件哈希、页码或审核人。旧草稿经验不得默认迁移为已发布。

迁移脚本支持 dry-run、数量统计、引用完整性检查、重复执行幂等和事务回滚。快照复制不会自动扩大共享范围。避免同一对象在新旧存储双向写入；迁移后确定唯一写入口，旧接口委托调用。

17. 文件级改造方案

新增目录与文件名是建议位置，实施前检查最新工作区和调用方，避免机械照抄造成重复模块。

工作项	保留/修改位置（backend 内）	建议新增位置（backend 内）	注意事项
核心上下文	graph/agent.py、graph/risk_task.py	graph/project_task.py	沿用 AgentManager 工厂，旧 invoke_risk_task 保留适配
协议与注册	tools/skills_scanner.py、api/risk_agent_config.py	contracts/、services/component_registry.py	保持旧 SKILL.md 和目录 ID 兼容
业务执行	api/risk_agent_config.py 的 run 分支	services/run_service.py、skill_executor.py、run_worker.py	迁出已有质量/比例规则后做输出对照
模型服务	api/risk_agent_config.py 的 local_model	services/model_provider.py	风险、报告、协调、租赁物调用方一并检查
数据适配	api/risk_agent_connectors.py、risk_agent_alignment.py	services/project_data.py、data_layer/adapters/	保留 SQL 校验，旧 erp_connector 不直接当真实已接通路径
材料服务	api/collateral_agent.py 的 extract_pages/upload	services/document_service.py、evidence_service.py	保留旧鉴权和限制，再扩格式
问题与补件	api/coordination_agent.py	services/finding_service.py、change_impact.py	复用任务流转，不增加并行补件台账
方案比较	api/coordination_agent.py、collateral_checks.py	services/scenario_service.py	基准与情景分开，公式版本固定
报告	api/report_agent.py	services/report_service.py、模板组件目录	保留 Word 导出和章节锁定测试
经验	api/report_agent.py、data_layer/team_experience.py	services/feedback_service.py、experience_service.py	导入旧经验后唯一存储
评测与发布	配置审核及 test-evidence 机制	services/evaluation_service.py、improvement_service.py	候选评测不污染正式环境
项目 API	api/xingbang_projects.py、app.py	api/project_assistant.py	新路由使用同一授权层

前端：复用 src/app/xingbang-workbench 及现有工作台，提取到 src/components/xingbang/project/；旧地址保留项目参数导航。演示与测试：新增 backend/fixtures/xingbang_demo/ 和对应 test_*.py，运行数据使用独立临时目录，fixtures 可以进入版本管理。

不立即删除 review_assist.py、xingbang_router.py、xingbang_v2.py、xingbang_unified.py、xingbang_workspace.py、risk_assess.py。它们仍被注册，需核查前后端、脚本、测试和外部使用后再决定归档；当前阶段停止将新能力写入重复旧链路。

18. 分阶段实施与交付门槛

所有阶段在同一 mini-openclaw 基线上前进。估时采用人日作为初步规划，并非固定交付承诺；模型兼容、文件质量及真实系统对接另行测量，业务审核等待不计入开发人日。

阶段	主要工作	交付物与退出条件	初步工作量
P0 基线和协议	调用链、备份、协议、验收样例、功能开关	测试留痕；可恢复基线；旧核心继续运行	2—3 人日
P1 组件与数据	manifest、发布快照、适配器、三类模拟包、授权入口	数据源可换；旧 Skill 可跑；新规则可发布；无跨项目数据	4—6 人日
P2 执行与检查	worker、步骤状态、工具范围、结构校验、基础 Skills	一次点击得到有证据的问题；失败可见；重启可恢复	5—8 人日
P3 材料与补件	通用解析、证据定位、问题生命周期、变化影响	补件实际改变结果；未执行检查不被当成通过	5—7 人日
P4 方案与底稿	有限情景比较、模板、章节更新、Word QA、UI 整合	检查—补件—方案—报告完成端到端验收	4—6 人日
P5 经验与演示	反馈、经验审核/检索、候选评测、演示重置与异常	A 项目经验在 B 应用，C 反例不误用；脚本可重复	4—6 人日

首版合计初估 24—36 人日，阶段间存在依赖，不能按人数简单相除。P3 后可展示“检查与补件”；完整首版定义包含 P5，不能把体验样片当成全部交付。

18.1 首批任务顺序

1. 固定 DEMO-B 项目和端到端预期，明确现有输出与目标差异。
2. 新增 ProjectSnapshot、SkillResult、Evidence、Finding 协议及兼容适配测试。
3. 将现有 quality/ratio 执行迁入注册表，验证旧结果一致，再增加新 Skill。
4. 将 API 中内嵌 SAMPLES 提取为可复位模拟适配器与 fixtures。
5. 打通项目页到新运行任务，核心仍为 AgentManager。
6. 扩通用附件、补件对比，再接现有报告导出。
7. 增加情景比较和经验闭环，统一业务导航。

先确保纵向业务闭环，再扩组件数量，避免先做大量配置页面却没有可运行结果。

18.2 每阶段验证顺序

在本仓库根目录执行，使用项目虚拟环境；不要直接采用旧文档中另一工作目录。修改前先 status、log，再搜索相关调用方；每次行为修改新增或更新对应测试。

git status --short
git log --oneline -6
# 修改完成后，先在 backend 工作目录运行相关测试。
Push-Location backend
.\venv\Scripts\python.exe -m unittest test_risk_core test_risk_agent_config -v
Pop-Location
# 然后在仓库根目录执行统一验证。
.\backend\venv\Scripts\python.exe scripts/verify.py
git status --short
git diff --stat
git diff --check

相关测试名单随改动扩展。统一脚本按 backend 工作目录运行全部 test_*.py，随后前端生产构建和两套 Compose 配置校验。涉及镜像运行/部署变更时追加 scripts/verify.py --docker；其会操作容器与端口，应在隔离验证环境使用。

计划、命令、完整日志与结果保留在 test-evidence/。失败必须修复或缩小改动，不发布镜像。文档设计、离线单元测试、真实模型联调、真实 ERP 验收分别记录，互不替代。

19. 功能验收矩阵

以下为目标验收条件，尚未执行新功能测试。全部固定模拟用例必须通过；模型语义质量由已标注评测集度量，不宣称现实业务零错误。

ID	场景	通过标准
CORE-01	检查、报告、经验提炼	模型调用经过现有 AgentManager，无旁路生成
CORE-02	两项目并发	快照、工具、对话、经验和结果无交叉
COMP-01	新增方法 Skill	按协议注册并执行，不修改主业务分支
COMP-02	替换规则/模板	新任务应用新版，正在执行任务与历史报告保持旧版
COMP-03	缺失/循环依赖	发布或执行前明确报错，不进入无限执行
NL-01	本次自然语言与必查规则冲突	说明冲突并保留必查项；正式变更只生成配置草案
DATA-01	模拟换本地 SQLite 测试源	同一标准数据得到相同确定性指标和问题
DATA-02	混合口径、单位、重复、空数据	换算或明确拒绝，不静默汇总、不把缺失当 0
DOC-01	PDF/DOCX/XLSX/扫描件	支持格式可定位；识别失败明确显示，无伪页码
RUN-01	模型或数据源失败	已完成结果保留，整体标记 partial/failed
RUN-02	刷新、断线、重启	可查询/恢复，不重复创建报告或任务
FIND-01	补交材料	预期问题解决，其余保留，状态改变有依据
FIND-02	新材料再造成矛盾	问题可重新打开，保留历史人工意见
SCEN-01	5,000 调至 4,000 万元	示例比例 108% 到 135%，原方案不变，缺现金流仍提示
REPORT-01	生成导出	数字与快照一致，未核实项保留，Word 页面无溢出
REPORT-02	已确认章节受变化影响	更新候选和过期提示，不直接覆盖人工正文
EXP-01	专家纠正	草稿包含适用/例外条件及来源，不自动全员生效
EXP-02	新项目使用经验	产生实际检查动作；反例不误用
EXP-03	过期/冲突/私有经验	正确过滤或提示，不泄露、不覆盖制度
EVO-01	候选规则或 Skill	留出集对比可查，失败候选不发布
EVO-02	版本回退	后续任务使用旧版，新旧运行均可追溯
AUTH-01	越权项目、文件、报告、日志、经验	全路径拒绝越权，覆盖 worker 和下载
DEMO-01	重置与现场改数	只重置指定演示实例，改数实际改变结果
UX-01	普通用户首次使用	不输入 SQL/JSON/Skill 名即可完成主流程

19.1 性能与质量测量

固定机器、模型和材料规模建立基准，例如单项目 10 份材料、合计 50 页、3 期财报，单任务和 3 任务并发分别记录首个状态、解析、检查、模型、导出及总耗时。

建议交互目标：创建任务后 2 秒内显示已接收，状态查询 p95 小于 1 秒；P0/P1 测量后确认实际阈值。模型完成时间先测再设目标，不承诺未知硬件固定速度。

金融数值计算在指定精度下与基准完全一致；引用 ID 有效性在固定测试集中 100%；关键漏检和越权用例不得通过。语义误报/漏报报告分项数量和分母，质量门槛在标注后确定。人工效率先量处理用时与修改量，不将模拟测试换算成未经验证的坏账节省。

20. 迁移、发布与回退

20.1 变更前留存回滚点

以当前分支/提交留回滚点，不提交凭据或客户运行资料。SQLite 使用一致性备份方式，不在写入时简单复制单个文件；同时备份附件、配置、运行和版本。按项目惯例建立备份目录，并核对绝对路径在目标工作区内。

20.2 兼容迁移顺序

1. 增加新协议与服务，旧 API 可用，先通过旧测试。
2. 功能开关下启用新模拟项目路径，做结果对照。
3. 旧接口逐一委托新服务，检查风险、报告、协同和核验调用方。
4. 新项目页复用组件，旧页面保留带项目参数的导航。
5. 迁移 dry-run 和引用检查通过后，切换指定对象的唯一写入口。
6. 确认旧路由无使用方且回退窗口结束，单独任务决定删除或归档。

功能开关建议：新执行器、新项目 UI、经验应用、候选评测、演示数据域。默认值纳入发布记录，不能依赖个人浏览器状态决定业务规则。

20.3 回退

出现结果回归、旧数据无法读取、鉴权绕过或迁移引用丢失时停止切换。先停新任务写入，切回兼容接口或旧组件版本；数据库不兼容时执行已演练恢复流程。

上线后已有新业务写入时，先保留新事件，采取前向修复或合并，不能直接恢复旧备份丢弃新数据。回退演练要打开旧项目、报告、附件和经验来源，不仅检查服务启动。代码、数据库 schema、组件发布集合与迁移记录组成同一发布清单。

21. 真实数据接入的交付边界

模拟闭环完成后，真实接入作为独立阶段，不推迟当前建设。届时收集：数据字典、只读方式、项目/用户映射、附件读取规则、正式手册和模板、部署与数据处理要求。

实施顺序：最小只读视图/接口 → 映射一个授权项目 → 字段与附件对账 → 单位/期间/来源核对 → 替换演示规则 → 验证权限 → 影子运行和人工复核 → 小范围启用。

模拟配置不能自动升为正式配置，模拟经验不自动进入生产；旧 run 保留 demo 标记。真实模型端点、硬件规模、ERP 类型和附件质量当前未知，影响对接工作量，不影响上层协议和现在的开发。

客户已有评级模板时，适配其输入输出和计算流程，对账后作为受控 Skill；不依赖模型复述模拟模板计算。正式行业阈值、风险偏好及审批流程由客户确认。

22. 完成定义与交付清单

完整首版完成必须同时满足：

1. 自有 mini-openclaw 贯穿模型任务，组件可替换，有版本和执行证据。
2. 三类虚构项目、真实附件、规则及预期可复位，能现场改数据运行。
3. 检查—补件—比较—底稿—经验复用通过验收。
4. 业务用户无需理解技术组件；管理员可配置数据、方案、规则、Skills 和模板。
5. 经验适用边界可见，改进候选可验证、可审核、可回退。
6. 旧功能和历史数据可用，规定测试、构建和部署校验留痕。
7. 真实接入合同、权限适配及待确认事项已文档化，演示与生产能力清楚区分。

交付物：系统代码、组件协议与样例、模拟档案与生成脚本、演示规则/模板、数据迁移和恢复脚本、评测集、测试证据、操作手册、配置说明、演示脚本、真实对接清单及已知限制。

第一轮实施从 P0/P1 和一个纵向项目闭环开始。评判改造是否成功，要看用户能否完成工作、能否解释结果和变化、能否将已确认经验带到下一个项目。

附录 A：设计来源

• 用户本轮讨论：自有 mini-openclaw、模拟数据先行、组件可插拔、体验简单、经验沉淀与进化。
• 本仓库 AGENTS.md：最小改动、先读调用方、联动检查、测试留痕和失败不发布。
• ori_file/兴邦金租会谈-2026.8.18 (1).md：业务痛点与试用意向，定位见第 2 节。
• 当前代码及测试：清单见第 3、17 节；根目录 ARCHITECTURE.md 描述通用聊天基础，不能单独代表最新业务实现。
• LangChain Memory overview：案例、知识与操作方法分层参考，不要求采用其外部平台。
• Anthropic Agent evals：程序及人工评价 Agent 的工程参考。
• OWASP Authorization Cheat Sheet：持续执行资源授权的参考。

外部资料仅作为工程方法参考，兴邦正式规则不从公开文章推断。设计数值与工作量均为规划值；未获客户确认的规则属于演示规则。