134 lines
12 KiB
Markdown
134 lines
12 KiB
Markdown
# 兴邦项目助手实施与验收说明
|
||
|
||
更新日期：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 文件内容、内容哈希及行号。设备清单按唯一编号去重，重复行不增加价值分子。同编号价值冲突时不计算总额。
|
||
|
||
可重复的离线验收及演示材料生成：
|
||
|
||
```powershell
|
||
.\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 发布前均执行项目边界。
|
||
|
||
```text
|
||
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_*`。
|
||
|
||
```powershell
|
||
# 默认只读检查
|
||
.\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`。不把旧原型伪定位升级成真证据。重复迁移不重复写入。新助手只写新对象表；旧原型运行、底稿、经验表只读保留。
|
||
|
||
已有新写入时不可直接恢复旧库覆盖它。先保留当前库与事件，检查恢复副本、引用和旧资料，再决定前向修复或受控合并。脚本刻意不提供破坏性的原地恢复。
|
||
|
||
## 验证与发布纪律
|
||
|
||
```powershell
|
||
.\backend\venv\Scripts\python.exe scripts/verify.py
|
||
```
|
||
|
||
统一脚本先后运行 diff 检查、全部后端单元测试、前端生产构建和两套 Compose 配置验证。开发缓存已隔离到 `.next-dev`，生产构建继续使用 `.next`，验证不会再覆盖正在运行的开发页面资源。
|
||
|
||
测试覆盖真实 AgentManager 工具循环、引用伪造拒绝、项目并发隔离、配置冻结、发布门槛、失效租约恢复、取消、权限撤销、真实格式解析、十进制换算、SQLite/mock 一致性、补件状态、底稿锁定候选、经验正反例以及迁移幂等。具体运行次数及日志以 `test-evidence` 中最后一次报告为准。
|
||
|
||
本轮未发布镜像，未执行真实 ERP 接入或真实模型质量验收。文档渲染失败也单独记录，不会被绿色单元测试掩盖。
|
||
|
||
## 真实对接前需要确认
|
||
|
||
内网模型地址、模型名、工具调用及 JSON 输出能力；标注的语义检查正反例和误报漏报门槛；正式规则、评级模板和报告格式；只读数据字典及项目/用户/团队映射；材料访问与保密要求；OCR 语言包；服务器资源、并发规模、备份保留期及发布审批人。
|