mini-openclaw/docs/项目助手实施与验收说明.md

兴邦项目助手实施与验收说明

更新日期：2026 年 9 月 11 日。对应《兴邦金租系统改造书 v1.0》。本说明区分已实现、已离线验证和仍需联调的能力，不将模拟结果当作真实业务验收。

当前交付状态

项目工作台已接通可配置检查、真实材料解析、补件与来源确认、情景比较、报告章节操作、反馈及经验评测发布。新检查复用现有 AgentManager 的受控工具循环，确定性计算使用 Decimal。旧四 Agent 页面和接口保留。

尚未达到改造书“全部完成”的验收条件：

• 未提供内网模型地址及模型名称，真实语义质量、真实模型并发耗时和模型方法候选的语义评测没有完成。离线测试使用测试模型执行真正的 AgentManager 工具循环，不是对真实模型质量的证明。
• 当前运行环境没有可用的 LibreOffice 文档渲染器。DOCX 导出结构和引用已自动检查，Word 逐页视觉验收尚未通过；不能据此宣称页面无溢出。
• 经验支持人工填写和通过 AgentManager 从反馈提炼结构化草稿，真实模型提炼质量仍待联调。模型生成规则候选尚未实现。新业务页的人工经验表单覆盖回款依赖案例，更多条件可由受控 API 定义。
• 模型型 Skill 候选目前在发布门槛中明确阻断，需要补充真实模型与标注集的评测执行器。非演示数据源的组件发布也保守阻断；已存在的只读连接测试及接入管理仍可使用。
• 旧 API 与新项目助手使用相互隔离的业务对象，新助手原型数据已迁移为只读档案；尚未把全部旧业务对象转换成同一业务模型或将全部旧 API 委托到新服务。
• 中文扫描件 OCR 需要配置本地语言包；已覆盖未配置、空白页和解析失败的明确提示，尚未完成真实扫描件识别质量验收。

以上是实际剩余工作，不属于已经完成的功能。真实 ERP、正式制度阈值和客户模板的接入按改造书第 21 节独立推进。

客户经理使用流程

1. 打开 /xingbang-workbench，选择已授权项目。
2. 可填写“本次检查要求”，选择业务方案并点击“检查项目”。服务返回已排队状态，页面自动轮询。离开页面不取消任务；可在概览中主动取消。
3. 在“材料与问题”上传材料。查看解析位置和候选字段，填写核对说明后确认来源。上传不等于自动接受候选，旧值与旧来源始终保留。
4. 对缺件可选择字段人工补充，必须写明依据。保存后重新检查，在运行变更摘要中查看解决、保留和重新打开的问题。没有执行或没有证据的检查不能使旧问题自动解决。
5. 在“方案比较”填写金额。比较仅保存情景，不改融资基线。填写理由并明确采纳才更新项目并使相关底稿过期。
6. 在“报告底稿”选择运行和模板，生成尽调草稿、评审底稿或上会摘要。事实与检查清单来自冻结快照，需通过补件修正；人工意见章节可编辑。确认、锁定的章节重新生成时保留正文，并产生候选。所有章节确认且未过期后，审核人才能定稿。
7. 在“反馈与经验”记录纠正类型及来源运行。表达、事实和数据纠正不自动转为规则。核查遗漏等可以创建经验草稿，经过正反例评测、独立审核后生效。

本机预览允许一人演练不同角色；正式环境不允许编辑人审核发布自己的经验或组件。

演示档案与演练

所有金额均为虚构演示数据，默认币种 CNY、单位万元、2025 年度、合并口径。120% 不代表兴邦正式制度。

项目	初始情形	预期
DEMO-A	完整标准制造项目	已配置的确定性检查不产生问题；模型缺失时整体仍为部分完成
DEMO-B	财报负债 13200、尽调 12800；现金流缺失；重复设备；融资 5000、唯一设备价值 5400	四项待处理；补充尽调 13200、重复数 0 后解决两项；金额情景 4000 得到 1.3500，现金流仍缺失
DEMO-C	存在回款依赖，回款凭证缺失	发布匹配的团队经验后，产生实际回款凭证检查及 ExperienceApplication；DEMO-A 不匹配，不应用

演示源数据和设备清单均有真实 CSV 文件内容、内容哈希及行号。设备清单按唯一编号去重，重复行不增加价值分子。同编号价值冲突时不计算总额。

可重复的离线验收及演示材料生成：

.\backend\venv\Scripts\python.exe scripts/assistant_acceptance.py

该脚本在临时 SQLite 中运行，不更改当前页面的数据。输出位于 test-evidence/assistant-acceptance-*，包括 CSV、三种 DOCX 及 JSON 验收结果。模型强制关闭，计时只代表离线确定性路径。

重置接口为 POST /api/xingbang/risk-agent/project-assistant/demo/reset，必须为有三个演示项目权限的管理员，并提供 {"confirmation":"RESET-DEMO-A-B-C"}。先归档，再只重置三个演示实例；不删除组件发布版本、旧审计或正式项目。

配置及模型调用关系

默认方案 corporate.default 组合新项目检查及旧目录的已发布 plan-default。因此旧配置页选中的数据卡、确定性 Skills、规则集会进入新运行，而不是只在页面上展示。每次排队会冻结配置、原生方法文本、当前资料、任务要求和服务端开关；之后编辑配置不改变已排队运行。

模型型检查通过 services/assistant_model.py 调用现有 agent_manager.invoke_scoped。模型只能读取本次快照、允许的材料、程序检查、已选方法和已授权经验；没有 SQL、终端或外部写入工具。结构化返回需要校验枚举、检查码、字段及证据 ID。模型未执行必需读取、超时、返回未知证据或缺少配置时，步骤失败并保留其他已完成结果。

组件治理页面支持草稿、隔离评测、发布和回退。已发布内容不允许覆盖。模型型候选不能冒充通过离线确定性评测，现阶段保持阻断。自定义确定性 Skill 使用 allowlist 中的执行器；不执行任意 Python、动态导入或 eval。

原生方法保留 risk_evidence/SKILL.md 旧路径别名，新增稳定 ID risk.evidence_review、版本、manifest；新旧工具协议分别读取各自被允许的工具。

运行与数据协议

• assistant_objects 存储项目、材料、输入快照、最终快照、运行、问题、情景、报告、经验及发布版本。
• assistant_jobs 为持久任务队列。工作进程用租约、心跳和 owner 检查防止迟到进程发布；最多恢复三次。已持久化完成步骤可复用。
• 运行状态有 queued、running、completed、partial、failed、cancelled。当前未实现 waiting_input 的原位恢复，缺输入以 partial 和补件后的新运行处理。
• assistant_idempotency 用于运行和报告请求去重。同一身份、操作和键若对应不同请求内容，返回 409。
• assistant_events 记录项目操作及步骤事件。项目页面展示最近 100 个事件。
• 快照中的金额用十进制字符串，缺失为 null。金额来源保留原值及单位；元/万元/亿元可归一到万元，币种、期间、口径不兼容时不跨口径计算。
• 机器 result 与人工状态、说明、历史分别保存。运行时项目已更新则标记 superseded，不覆盖当前问题状态。
• 每次报告生成引用明确的运行、快照和模板版本，不能使用历史运行搭配当前事实。定稿另存不可变副本。

文件解析限制

单文件最大 10 MB，文本总量 30 万字，PDF 每份最多 40 页。DOCX 使用正文段落及表格行定位，不伪造页码；XLSX 保存单元格位置、公式及已有缓存，不计算公式、不运行宏。旧 XLS/XLSM 不支持。CSV/TXT 需 UTF-8。

PDF 和图片复用本地 PyMuPDF 提取。OCR 可配置 XINGBANG_OCR_TESSDATA，需要 chi_sim 与 eng 本地语言包。无文字或 OCR 失败时显示部分完成及原因，不当作空白证明。

当前结构化候选优先识别标准字段的键值行和明确的设备清单格式，任意非结构化材料不会被伪装成已自动理解。

身份与开关

XINGBANG_AUTH_USERS 在服务器配置身份、令牌、role、projects、teams。不要把令牌提交 Git。管理员和审核人也必须有明确项目授权，不能因为能管配置而读取客户材料。新增项目接口、附件和 Word 下载以及 worker 发布前均执行项目边界。

XINGBANG_REQUIRE_AUTH=1
XINGBANG_LOCAL_MODEL_URL=http://内网IP:端口/v1
XINGBANG_LOCAL_MODEL_NAME=模型名
XINGBANG_LOCAL_MODEL_KEY=由服务器安全配置
XINGBANG_ASSISTANT_ENABLED=1
XINGBANG_ASSISTANT_DEMO_ENABLED=1
XINGBANG_ASSISTANT_EXPERIENCES=1
XINGBANG_ASSISTANT_EVALUATION=1

模型连接仅允许 localhost/回环或私有网段 IP，不把项目材料发送到公共模型地址。XINGBANG_ASSISTANT_ENABLED=0 停止新助手入口和启动新 worker；旧业务入口保留。若要停止正在执行的进程任务，应先取消任务并有序重启，不能只修改启动后的环境文件。

迁移与回退

迁移前使用一致性 SQLite backup，不在写入期间裸拷贝单个数据库文件。实际迁移前已建立 _backup_pre_full_assistant_20260911 和带时间戳的 _backup_pre_assistant_migration_*。

# 默认只读检查
.\backend\venv\Scripts\python.exe scripts/assistant_migrate.py --dry-run

# 一致性备份后迁移；建议先停止旧后端写入
.\backend\venv\Scripts\python.exe scripts/assistant_migrate.py --apply

# 从指定备份恢复到新文件，绝不覆盖当前库
.\backend\venv\Scripts\python.exe scripts/assistant_migrate.py --database _backup_pre_assistant_migration_时间戳/project_assistant.sqlite3 --restore-copy test-evidence/recovered-assistant.sqlite3

旧原型表保留，历史记录复制到 legacy_archive，ID 为 原表名:原ID，来源标记 legacy_unknown。不把旧原型伪定位升级成真证据。重复迁移不重复写入。新助手只写新对象表；旧原型运行、底稿、经验表只读保留。

已有新写入时不可直接恢复旧库覆盖它。先保留当前库与事件，检查恢复副本、引用和旧资料，再决定前向修复或受控合并。脚本刻意不提供破坏性的原地恢复。

验证与发布纪律

.\backend\venv\Scripts\python.exe scripts/verify.py

统一脚本先后运行 diff 检查、全部后端单元测试、前端生产构建和两套 Compose 配置验证。开发缓存已隔离到 .next-dev，生产构建继续使用 .next，验证不会再覆盖正在运行的开发页面资源。

测试覆盖真实 AgentManager 工具循环、引用伪造拒绝、项目并发隔离、配置冻结、发布门槛、失效租约恢复、取消、权限撤销、真实格式解析、十进制换算、SQLite/mock 一致性、补件状态、底稿锁定候选、经验正反例以及迁移幂等。具体运行次数及日志以 test-evidence 中最后一次报告为准。

本轮未发布镜像，未执行真实 ERP 接入或真实模型质量验收。文档渲染失败也单独记录，不会被绿色单元测试掩盖。

真实对接前需要确认

内网模型地址、模型名、工具调用及 JSON 输出能力；标注的语义检查正反例和误报漏报门槛；正式规则、评级模板和报告格式；只读数据字典及项目/用户/团队映射；材料访问与保密要求；OCR 语言包；服务器资源、并发规模、备份保留期及发布审批人。