mini-openclaw/docs/兴邦金租对公智能评审平台技术路径与AgentLoop说明-v1.0.md

# 兴邦金租对公智能评审平台技术路径与 Agent Loop 说明

适用对象：没有代码基础的业务、产品、实施、数据和管理同事  
文档版本：v1.0  
代码基线：Git b10093f  
说明范围：只解释当前仓库中的实现，不泛化到其他 LangChain、LangGraph 或 OpenClaw 项目

## 一 先理解当前系统的结论

当前平台不是让大模型直接连接业务数据库后自由作答。系统先把业务数据和材料转换成标准字段，冻结本次输入以及数据卡、Skills、规则和模板版本，再执行确定性检查、已发布经验核查和受限模型核查。运行结果经过结构、证据和权限校验后，才形成问题、报告和评审对象。

业务人员看到的是一个统一业务助手和项目办理页面。底层仍由 mini-openclaw 的 `AgentManager` 提供 LangChain Agent 与工具循环，但业务运行使用独立上下文和受限工具，不继承普通聊天历史，不向模型开放数据库 SQL、终端或文件写入权限。

当前系统有两种 Agent Loop。

1. 通用对话循环：模型根据会话历史决定直接回答或调用通用工具，工具结果回到模型，直到模型给出最终文本。
2. 兴邦业务循环：服务先执行数据卡、确定性 Skills、规则和经验，再让模型通过只读工具读取冻结快照和方法，最后由程序校验模型 JSON 并写入业务对象。

第二种循环是兴邦项目的主要技术路径。它的目标不是让模型自由发挥，而是让每次判断都能回答四个问题：使用了什么数据，依据了什么方法，谁在什么时间作了什么决定，后来是否发生了版本变化。

## 二 系统分层

| 层次 | 当前技术 | 主要职责 | 关键位置 |
| --- | --- | --- | --- |
| 浏览器界面 | Next.js 14 与 React 18 | 业务助手、项目工作台、评审池、时效看板、配置治理 | `src/app` 与 `src/components/xingbang` |
| 同源代理 | Next.js Route Handler | 把浏览器请求转发到后端并传递身份信息 | `src/app/api/core` 与 `src/app/api/risk-agent` |
| API 层 | FastAPI | 参数校验、角色与项目权限、业务路由、SSE 流 | `backend/api` 与 `backend/app.py` |
| Agent 基座 | LangChain `create_agent` | 组装模型、工具和系统提示词 | `backend/graph/agent.py` |
| Agent 循环 | LangGraph 的模型节点与工具节点 | 模型调用、工具调用、再次模型调用、结束判断 | 由 LangChain `create_agent` 内部驱动 |
| 业务编排 | 项目服务与持久任务 Worker | 冻结快照、读取数据卡、执行组件、恢复任务 | `backend/services/project_assistant.py` 与 `assistant_worker.py` |
| 执行器 | Python 确定性程序与受限模型 Agent | 必填、对比、比率、重复项、规则和语义核查 | `skill_executor.py` 与 `assistant_model.py` |
| 持久化 | SQLite、JSON、JSONL 和向量索引 | 项目对象、任务、审计、会话、原始轨迹和长期记忆 | `backend/xingbang_data`、`sessions`、`raw_logs`、`storage` |

浏览器不直接连接数据库、模型或文件系统。所有读取和写入都经过后端接口及身份检查。

## 三 六个核心概念

### 三一 数据连接

数据连接描述系统允许连接到哪一个数据源，包括数据源类型、只读边界、表白名单和凭据环境变量引用。当前组件协议支持演示源、SQLite、PostgreSQL 和 MySQL。密码、令牌和 API Key 不允许直接写入组件内容或运行快照。

### 三二 数据卡

数据卡说明如何从一个数据连接中读取某一组业务字段。它包含参数化 SQL、源字段到标准字段的映射、单位、币种、期间和口径。数据卡的输出不是一段供人阅读的报表，而是一组标准事实和字段级证据。

### 三三 Skill

Skill 表示一种可执行的业务能力或方法。当前业务 Skill 分为确定性 Skill 和模型 Skill。

- 确定性 Skill 由固定 Python 执行器完成，例如必填检查、两来源比较、比例计算和重复项检查。
- 模型 Skill 使用已冻结的 `SKILL.md` 方法文本和只读工具，通过 mini-openclaw Agent Loop 做语义核查。

Skill 不能仅靠文字获得新权限。它可以声明允许使用哪些只读工具，实际工具集合仍由后端白名单控制。

### 三四 规则卡

规则卡适合执行明确的条件判断，例如覆盖率低于阈值、某字段大于上限或在特定条件下必须补充资料。规则卡不调用大模型。阈值和操作符由程序读取，金额使用十进制数计算。

### 三五 业务方案

业务方案把数据卡、Skills、规则、报告模板、适用角色、运行类型和工具预算组合在一起。客户经理 AI 预审和评审员独立复核是两张不同方案。它们可以复用基础数据和部分确定性 Skills，但使用不同的模型 Skill、报告模板和预算。

### 三六 快照与运行

快照保存某一次运行实际看到的项目事实、材料、来源、数据卡结果和内容哈希。运行保存执行人、身份、方案、组件版本、步骤、问题、证据、开始结束时间和最终状态。快照和已发布组件版本不可被覆盖。

## 四 从数据进入到业务结果的完整路径

```text
业务数据库或上传材料
  → 数据连接和数据卡读取
  → 标准字段与字段级来源
  → 人工确认材料候选
  → 冻结输入快照和组件版本
  → 确定性 Skills
  → 规则卡
  → 已发布经验核查
  → 受限模型 Skill 和工具循环
  → 结构与证据校验
  → 问题与运行结果
  → 报告草稿
  → 客户经理提交评审池
  → 评审员领取和独立评审
  → 退回或批准
```

这条路径中，大模型只参与受限模型 Skill。数据卡、金额换算、口径校验、比例计算、阈值判断、任务持久化和人工审批都由普通程序完成。

## 五 数据卡如何把多张表变成标准事实

### 五一 为什么需要数据卡

同一个业务事实在不同系统中可能使用不同表名、列名、金额单位和期间。Skill 如果直接依赖源系统列名，一旦 ERP 或财务系统调整字段，所有检查都会受影响。数据卡把源系统结构与业务标准字段隔开。

例如，源表中的 `total_liability`、`liab_total` 或中文负债合计，都可以映射到标准字段 `financial.total_liabilities`。后续 Skill 和规则只依赖标准字段。

### 五二 当前标准字段示例

| 标准字段 | 业务含义 | 可能来源 |
| --- | --- | --- |
| `facility.amount` | 融资金额 | 项目融资表或审批申请 |
| `lease.total_value` | 租赁物价值 | 租赁物台账或评估材料 |
| `financial.total_liabilities` | 财务报表负债 | 财务报表数据卡 |
| `due_diligence.liabilities` | 尽调口径负债 | 尽调材料或尽调数据表 |
| `financial.operating_cashflow` | 经营现金流 | 现金流量表 |
| `lease.duplicate_count` | 重复设备数量 | 设备清单去重结果 |
| `credit.overdue_count` | 征信逾期数量 | 征信数据卡 |
| `collection.evidence` | 回款依据 | 回款说明或附件 |

### 五三 SQL 执行边界

数据卡只允许一条参数化 `SELECT` 或 `WITH SELECT`。项目条件使用服务端参数 `:project_id`，不能通过字符串拼接项目编号。数据连接可以配置允许访问的表，SQL 不能访问白名单之外的业务表或系统表。SQLite 以只读方式打开，并由数据库授权器再次禁止写操作。

模型不获得 SQL 工具。执行 SQL 的是数据卡层，模型只能看到数据卡已经读取、映射、授权并冻结的结果。

### 五四 字段映射与口径校验

`assistant_data.py` 读取数据卡后依次处理以下事项：

1. 检查演示数据域与生产数据域不能混用。
2. 使用项目编号参数读取数据行。
3. 按数据卡映射生成标准字段。
4. 按字段单位把元、万元等换算为统一量纲。
5. 保留期间、口径、单位和币种。
6. 为每个字段生成证据编号、来源名称和定位信息。
7. 对查询结果计算行哈希，记录本次读到了哪一版数据。

若同一标准字段来自多个来源且值不一致，程序会把当前值置为空并记录冲突，不会让模型自动选择其中一个。金额和比例计算前会检查币种、单位、口径和期间；不一致时停止交叉计算。

### 五五 多张表与多张数据卡

当前演示业务库包含客户、项目、融资方案、财务报表、租赁物、保险、增信、征信、诉讼、还款来源和材料等多张表。管理员可以按业务域拆成多张数据卡，例如项目主数据卡、财务现金流卡、租赁物保险卡、征信涉诉卡和增信还款卡。业务方案选择多张卡后，运行会把它们统一映射到同一份标准字段快照。

## 六 上传材料如何进入同一条数据链

材料入口支持 TXT、CSV、DOCX、XLSX、PDF 和图片，单文件上限为 10 MB。解析器会保存原件、文件哈希、版本、文本片段、定位和警告。每个文本片段生成独立证据编号。

解析结果先形成候选字段。候选字段不会自动覆盖项目事实。客户经理必须确认值、期间、单位、口径和来源后，系统才更新项目数据版本。旧材料和旧字段来源继续保留。

DOCX 和 XLSX 通过压缩包内的 XML 读取，不执行宏。XLSX 公式只读取文件中已有的缓存值。PDF 和图片通过现有页面提取能力获取文本；无法识别的页产生警告。材料正文被视为不可信数据，其中写入的指令不会变成 Agent 指令。

## 七 Skills 在当前项目中的两种形态

### 七一 原生方法 Skill

`backend/skills` 下的 `SKILL.md` 由 `skills_scanner.py` 扫描。文件头包含名称、说明、分类、输入字段和版本。扫描结果形成 `SKILLS_SNAPSHOT.md`，供通用对话 Agent 了解可用方法。

兴邦业务运行不会在执行中临时读取变化中的文件。方案冻结时，系统读取选中的 `SKILL.md` 全文并计算内容哈希，保存到 Skill 组件的 `methods` 中。之后即使管理员修改本地文件，本次运行仍使用入队时冻结的内容。

当前金租方法包括承租人及还款能力、租赁物适格性与权属、售后回租真实性、增信与关联交易集中度、独立评审与报告证据核查。

### 七二 可执行业务 Skill

当前允许的执行器如下。

| 执行器 | 用途 | 是否调用模型 |
| --- | --- | --- |
| `required` | 检查标准字段是否缺失 | 否 |
| `compare` | 比较两个来源值及其期间口径 | 否 |
| `ratio` | 用十进制数计算比例并生成输出字段 | 否 |
| `duplicate` | 判断重复项数量是否大于零 | 否 |
| `quality` | 检查输入字段质量 | 否 |
| `overdue` | 处理逾期类输入 | 否 |
| `model` | 通过受限 Agent 做语义核查 | 是 |

执行器集合写死在 `skill_executor.py`。系统不根据上传内容动态导入 Python 模块，也不使用 `eval` 执行表达式。首版 Skill 只支持无外部副作用的读取与判断。

### 七三 当前预置确定性 Skills

| Skill | 输入 | 输出或判断 |
| --- | --- | --- |
| 负债金额来源不一致 | 财报负债、尽调负债 | 两个来源一致、冲突或无法判断 |
| 现金流完整性 | 经营现金流 | 已提供或材料不足 |
| 设备清单重复项 | 重复设备数量 | 有重复、无重复或缺少数据 |
| 租赁物价值覆盖测算 | 租赁物价值、融资金额 | 生成 `metrics.coverage` |

确定性 Skill 的结果可以重复计算和单元测试。它们不依赖模型是否可用。

## 八 规则卡怎样使用 Skill 输出

规则卡由一个或多个条件组成，每个条件包含字段、操作符、阈值、问题标题和建议动作。支持大于、小于、等于、大于等于和小于等于。

当前演示覆盖规则读取 `metrics.coverage`。这个字段先由比例 Skill 计算，再由规则比较是否低于 1.2。执行顺序由 Skill 依赖和业务方案控制。规则命中时形成问题；字段缺失或无法计算时形成材料不足；条件不适用时形成不适用。

规则卡中的 1.2 是演示阈值。正式环境必须由兴邦金租确认规则来源、适用范围、例外、版本和生效日期后再发布。

## 九 业务方案如何冻结一次运行

`component_registry.py` 维护已发布组件版本和发布指针。运行开始时，`freeze` 按方案解析数据卡、数据连接、Skills、规则和模板，并完成以下检查：

- 所有组件属于相同的数据域。
- Skill 执行器和允许工具在白名单内。
- Skill 依赖不存在循环，比例输出字段不冲突。
- 规则操作符和阈值有效。
- 报告模板章节不为空且编号不重复。
- 原生 `SKILL.md` 存在，并把方法全文读入当前组件。

冻结结果计算整体内容哈希。运行对象还保存每个组件的稳定编号、版本和内容哈希。发布新版本只影响后续运行，不会改变历史运行。

当前主要方案如下。

| 方案 | 适用身份 | 主要差异 |
| --- | --- | --- |
| 客户经理 AI 预审 | 客户经理 | 使用综合核查 Skill 和 AI 预审报告模板 |
| 评审员独立复核 | 评审员 | 使用独立评审 Skill、独立评审模板和更高工具预算 |
| 多表业务库 AI 预审 | 客户经理 | 使用多张业务数据卡读取模拟数据库 |

## 十 业务 Agent Loop 的十二个步骤

### 十一 接收指令与权限检查

业务助手或页面按钮调用项目服务。服务端检查当前身份、角色、项目授权、方案受众和项目版本。评审员方案还要求当前评审员已经从评审池领取项目。

### 十二 幂等检查

前端为发起运行和生成报告提供幂等键。后端把执行人、操作、幂等键、请求哈希和对象编号保存在 `assistant_idempotency`。相同请求重复点击返回原对象；同一幂等键用于不同请求会被拒绝。

### 十三 冻结输入快照

系统保存当前项目事实、来源、材料、数据版本和材料片段证据。每个材料片段根据文件、内容哈希、序号和定位生成稳定证据编号。这个快照写入后不可覆盖。

### 十四 冻结组件

系统按方案解析当前发布的数据卡、Skills、规则和模板，读取原生 Skill 方法文本并计算哈希。模型配置和功能开关一并写入运行对象。

### 十五 创建持久任务

系统创建状态为 `queued` 的运行和 `assistant_jobs` 任务，并立即向页面返回运行编号。浏览器不需要保持长连接。

### 十六 Worker 领取与续租

后台 Worker 领取任务，写入执行人、尝试次数和租约。执行期间定时续租。进程异常后，租约过期的任务可以被重新领取。已完成步骤写入运行对象，恢复时可以复用，不必从第一步全部执行。

### 十七 执行数据卡

Worker 从输入快照和冻结数据卡读取业务数据，做字段映射、单位换算和冲突检查，生成正式业务快照、数据集行哈希和数据错误。

### 十八 执行确定性 Skills

非模型 Skills 先运行。每个步骤保存输入哈希、开始结束时间、输出、问题、缺失输入、错误和状态。比例 Skill 产生的新字段会加入后续步骤使用的 `values`。

### 十九 执行规则卡

规则读取当前标准字段和前序 Skill 输出，形成通过、发现问题、材料不足或不适用的检查结果。每项结果包含字段、值、证据编号、规则编号与版本和建议动作。

### 十十 执行已发布经验

运行第一次建立业务快照时冻结当时可用的经验版本。经验先检查数据域、项目或团队范围、行业、触发条件、例外条件和有效期。匹配后生成一项可追溯检查，并保存实际应用记录。

### 十十一 执行模型 Skill

模型 Skill 通过同一个 `AgentManager` 创建隔离 Agent，但不读取普通聊天历史。模型只能使用方案授权的只读工具。工具结果回到模型，模型可再次选择工具，直到输出最终 JSON。

### 十十二 校验与发布结果

程序用 Pydantic 校验模型 JSON，检查问题编号、结果枚举、标准字段、证据编号和材料读取记录。通过后，系统合并所有检查，更新问题生命周期，保存证据、步骤、运行摘要和结束状态。若运行期间项目数据版本已经变化，本次运行标记为已被新版本取代，不覆盖当前问题状态。

## 十一 模型 Skill 内部的 Agent Loop

### 十一一 模型第一次收到的内容

模型不会直接收到整个数据库或服务器目录。初始任务包含选中方法清单、材料编号清单、人工提出的本次关注点和 Skill 指令。系统提示明确要求模型必须使用受限工具读取事实、计算结果和方法，不能执行 SQL、修改文件或作审批决定。

### 十一二 可用只读工具

| 工具 | 读取内容 | 关键限制 |
| --- | --- | --- |
| `read_project_snapshot` | 当前冻结的标准字段与字段级来源 | 只能读本次项目快照 |
| `read_document` | 当前快照中的指定材料片段 | 材料编号必须属于本次快照 |
| `read_checks` | 确定性检查、已发布规则和本次要求 | 不允许模型自行改规则 |
| `read_method` | 被方案选择并冻结的 `SKILL.md` 方法 | 未选择的方法不能读取 |
| `read_experiences` | 已授权且适用的已发布经验 | 不提供来源项目专有信息 |

模型 Skill 声明 `allowed_tools`，后端再从固定工具集合中取交集。Skill 文件中的文字不能创造一个新工具。

### 十一三 LangChain 与 LangGraph 的职责

`AgentManager.build_task_agent` 调用 LangChain 的 `create_agent`。LangChain 提供模型适配、消息和工具定义。`create_agent` 内部由 LangGraph 驱动模型节点和工具节点之间的循环。

```text
任务和系统提示词
  → 模型节点
  → 模型返回普通文本或 tool_calls
  → 如有 tool_calls 则进入工具节点
  → Python 工具返回 ToolMessage
  → ToolMessage 回到模型节点
  → 模型继续调用工具或输出最终 JSON
  → 没有未完成工具调用时结束
```

一次业务模型核查可能调用模型多次，但对用户仍是一项运行步骤。后端设置递归上限、总超时和最大工具调用次数。客户经理方案默认 120 秒和最多 12 次工具调用，评审员方案默认 180 秒和最多 18 次工具调用。

### 十一四 强制读取与输出校验

模型完成前必须至少读取项目快照、已有检查和每个选中的方法。缺少任一必需读取，步骤失败。

最终输出必须是结构化 JSON，包含 `findings` 和 `requirement_response`。每个判断只能使用四种结果：通过、发现问题、材料不足、不适用。判断为通过或发现问题时必须有证据。引用材料证据前必须实际调用 `read_document` 读取对应材料。引用未知字段、未授权证据或重复检查码都会导致步骤失败。

这种校验不能保证模型永远正确，但可以防止它把无法追溯的文字直接写入正式问题列表。

## 十二 确定性检查与模型检查如何合并

Worker 按以下顺序执行：非模型 Skills、规则卡、已发布经验、模型 Skills。所有检查汇总后，`reconcile` 根据稳定问题编号处理问题生命周期。

| 场景 | 问题状态处理 |
| --- | --- |
| 新检查首次发现问题或材料不足 | 创建待处理、待补件或待复核问题 |
| 新运行确认此前问题已通过 | 标记已解决，保留历史 |
| 已解决问题再次出现 | 重新打开并记录新运行 |
| 规则或 Skill 依据版本变化 | 原结果进入待复核，不静默沿用 |
| 运行期间项目数据变化 | 本次运行不覆盖当前问题状态 |

人工可以把问题标记为待补件、待复核或不适用，并填写说明。已解决状态只由有依据的新检查确认，避免业务人员直接把问题点掉后失去证据。

## 十三 当前记忆系统的整体设计

当前项目不存在一个把所有内容自动记住的单一记忆库。不同用途使用不同存储，并有不同的可信度和生命周期。

| 记忆类型 | 存储位置 | 主要用途 | 是否进入业务审批依据 |
| --- | --- | --- | --- |
| 会话短期记忆 | `backend/sessions/{session_id}.json` | 让通用聊天记住同一会话前文 | 否 |
| 压缩会话摘要 | 会话文件的 `compressed_context` 与 `sessions/archive` | 缩短过长聊天上下文 | 否 |
| 长期记忆 | `backend/memory/MEMORY.md` | 保存跨会话的重要背景 | 否，除非转成正式业务对象 |
| 长期记忆向量索引 | `backend/storage/memory_index` | RAG 模式按问题检索记忆片段 | 否 |
| 原始模型轨迹 | `backend/raw_logs` | 调试模型请求、响应和工具调用 | 否，属于敏感技术日志 |
| 项目业务记忆 | `project_assistant.sqlite3` | 项目事实、来源、快照、运行、问题、报告和决定 | 是 |
| 组织经验记忆 | SQLite 中的经验版本和应用记录 | 在适用条件下复用已审核经验 | 审核发布后可作为检查依据 |
| 时间与审计记忆 | `assistant_events` 与 `business_time_events` | 记录操作和阶段耗时 | 是，作为流程留痕 |

## 十四 通用聊天记忆

### 十四一 会话短期记忆

每个会话保存标题、创建和更新时间以及用户与助手消息。下一轮对话前，`SessionManager.load_session_for_agent` 合并连续助手消息，只把用户和助手正文重新放入上下文。工具调用的完整轨迹不直接全部塞回模型，而是单独保存在原始日志。

### 十四二 会话压缩

当会话过长时，压缩接口选取前一部分消息，调用模型生成不超过 500 字的摘要。原消息归档到 `sessions/archive`，摘要写入 `compressed_context`。下一轮把摘要作为开头的助手上下文。

摘要可能遗漏细节，因此重要业务事实不能只保存在聊天摘要中。正式项目数据必须进入项目事实、材料、问题或报告对象。

### 十四三 长期记忆

长期记忆文件是 `backend/memory/MEMORY.md`。当前 `backend/config.json` 中 `rag_mode` 为 `false`，因此整个文件作为系统提示词的一部分加载。切换为 RAG 模式后，系统不再把全文放入提示词，而是把文件切分为约 256 token、重叠 32 token 的片段，使用 `BAAI/bge-small-zh` 建立向量索引，并按问题检索前三个片段。

索引使用 MEMORY 文件的 MD5 判断是否需要重建，保存在 `backend/storage/memory_index`。索引加载失败时返回空检索结果并继续运行。

当前代码没有一个自动把每天聊天内容总结后写入 `MEMORY.md` 的后台学习流程。工作区规则可以要求 Agent 使用工具维护记忆，但那是受权限控制的操作约定，不应宣传为全自动学习。

### 十四四 原始模型轨迹

通用对话把完整 human、assistant 和 tool 消息写入 `{session_id}.msgs.jsonl`，把每次模型请求、响应、工具调用、token 用量和耗时写入另一份 JSONL。页面可以显示截短的工具结果，但完整工具消息保存在轨迹中。

原始轨迹用于故障排查，不是业务事实库。它可能包含业务文本，必须按敏感日志管理和设置保留周期。

## 十五 兴邦业务记忆

### 十五一 为什么业务运行不使用聊天记忆

业务检查必须可复现。如果模型继承某个用户前一次聊天中的项目编号、判断或材料片段，很容易造成跨项目污染。因此 `AgentManager.invoke_scoped` 为每次模型 Skill 创建隔离 Agent，不传入共享聊天历史。

### 十五二 SQLite 中的核心表

| 表 | 内容 |
| --- | --- |
| `assistant_objects` | 使用种类和编号保存项目、快照、运行、问题、报告、评审决定、组件版本、经验等 JSON 对象 |
| `assistant_events` | 记录谁在什么时间对哪个项目执行什么动作 |
| `assistant_idempotency` | 防止重复点击创建重复运行或报告 |
| `assistant_jobs` | 保存持久任务状态、执行人、租约和尝试次数 |
| `business_time_events` | 保存资料收集、预审、排队、评审办理和外部等待等时间区间 |

`assistant_objects` 采用乐观版本号。更新时可以要求客户端提交预期 revision，若页面数据已经过期，服务返回内容已更新，要求刷新后重试。快照和发布版本使用不可变写入。

### 十五三 项目事实与来源

项目对象保存标准字段 `values`、所有字段来源 `sources`、当前选择来源 `selected_sources`、材料编号、数据版本和待确认候选。字段来源包含证据编号、来源名称、定位、期间、口径、单位和币种。

### 十五四 输入快照与业务快照

输入快照在运行入队时创建，保存当时的项目对象和材料。业务快照在 Worker 执行数据卡后创建，加入数据集记录、映射结果、数据错误和内容哈希。模型和后续步骤只读取这份业务快照。

### 十五五 运行步骤和问题

运行保存方案、组件版本、模型配置、步骤、检查、证据、摘要和状态。每个步骤独立保存输入哈希、输出、错误和技术轨迹。问题保存稳定检查码、当前状态、证据、依据组件以及人工处理历史。

### 十五六 报告与评审决定

报告绑定运行、快照、模板和数据版本。系统章节来自冻结快照和运行结果，允许编辑的人工章节保存修改历史、确认和锁定状态。评审决定绑定评审员、时间、节点、意见、运行、快照、证据和依据组件。最终退回或批准还绑定六个节点决定引用。

## 十六 组织经验记忆

评审反馈不会直接变成规则。当前流程如下。

```text
评审员记录具体反馈
  → 创建经验草稿
  → 写清触发条件、核查动作、例外、范围和有效期
  → 在隔离留出样本上评测正例和反例
  → 独立审核人发布
  → 后续运行冻结已发布版本
  → 条件匹配时生成检查并记录应用
  → 不再适用时停用回滚
```

经验匹配会检查数据域、项目或团队、行业、触发字段、例外字段和有效期。团队经验在发布前检查是否含来源项目编号、客户名称等专有信息。表达、事实或数据纠正不能直接升级为核查经验，必须先修正原对象。

隔离评测至少包含适用样本、条件不匹配样本、数据域隔离、过期样本、例外样本、无团队权限或其他项目样本，以及经验实际生成缺件检查的验证。评测通过不等于自动发布，还需要独立审核。

这套机制属于受控知识沉淀，不是模型参数训练。系统不会因为某个评审员点了一次不采纳就自动改变所有项目的规则。

## 十七 报告生成路径

报告生成不调用自由聊天记录。服务选择一个已完成或部分完成的业务运行，读取其快照、问题、证据和模板，按章节生成草稿。模板决定章节顺序和依赖字段。

客户经理使用 AI 预审报告模板，评审员使用独立评审报告或上会摘要模板。报告保存来源快照、运行编号、数据版本、模板版本和证据。项目数据或新运行变化后，旧报告标记为待更新，但不会被自动覆盖。用户选择按最新运行更新时，系统先生成候选内容，人工采纳后才替换正文。

提交正式评审时，当前报告作为不可覆盖的送审版本写入评审池。重新推送会创建新序号，旧送审版本保留。

## 十八 评审员独立复核路径

评审员从评审池领取项目后，系统记录领取时间并关闭排队等待时间。评审员方案重新运行独立复核，不直接继承客户经理的最终判断。

运行结果按六个业务节点组织：主体信息、财务与现金流、租赁物、增信措施、征信与涉诉、交易结构与还款。每个节点包含数据来源、AI 检查、依据组件和评审员结论。

评审员可以选择确认无异常、风险可控、要求补件、转现场核查、不采纳 AI 或不适用。需要专业判断的结论必须填写意见。批准前，所有节点必须有结论，且不能存在要求补件、转现场核查等未闭环决定。最终批准或退回由评审员执行，不由模型工具执行。

## 十九 时间和审计链

系统使用 `assistant_events` 保存动作事件，使用 `business_time_events` 保存阶段区间。阶段记录包括项目、阶段码、阶段名称、角色、时间类别、开始和结束时间、来源对象和详情。

客户经理提交报告时开始评审排队；评审员领取时结束排队并开始评审办理；退回或批准时结束评审办理。AI 预审和独立评审运行也有独立时间区间。

时效看板把时间分为人员处理、排队等待、外部等待和系统执行。该分类用于发现流程瓶颈，不应把所有等待时间都归因于工作人员或模型。

## 二十 权限与安全边界

### 二十一 身份和项目权限

后端在每个项目接口校验身份、角色和项目授权。客户经理只能使用面向客户经理的方案和模板；评审员必须领取项目后才能形成评审决定；配置管理员负责组件配置。演示身份选择器不是生产鉴权。

### 二十二 模型地址

业务模型从 `XINGBANG_LOCAL_MODEL_URL` 读取，只接受 HTTP 或 HTTPS 的本机、回环或内网地址，不允许在 URL 中嵌入用户名、密码、查询参数或片段。模型 Key 从环境变量读取。

### 二十三 工具权限

通用聊天 Agent 可以配置终端、Python、网页、文件和知识库等工具，因此生产代理只应向授权管理员开放。兴邦业务模型只使用五个只读业务工具，不开放终端、Python、网页、SQL 或文件写入。

### 二十四 超时和失败

通用聊天有空闲和总时长限制，超时后不会自动重放可能有副作用的工具。业务任务有方案级超时和工具预算。单个模型步骤失败时，其他确定性步骤保留，运行状态可能为部分完成。部分完成不能被解释为全部通过。

## 二十一 当前已实现与当前边界

| 能力 | 当前状态 | 说明 |
| --- | --- | --- |
| 多表 SQLite 演示库与多张数据卡 | 已实现 | 可演示 SQL 读取、字段映射和完整流程 |
| 客户经理 AI 预审与报告 | 已实现 | 支持持久运行、问题、报告和送审 |
| 评审池、领取、退回和批准 | 已实现 | 记录提交时间、等待时间和办理时间 |
| 六节点独立评审 | 已实现 | 每个节点保存证据和人工结论 |
| Skills 与规则版本冻结 | 已实现 | 运行保留版本和内容哈希 |
| 经验草稿、评测、发布和应用 | 已实现 | 不自动成为正式制度 |
| 通用会话记忆与 MEMORY RAG | 已实现 | 当前配置为 RAG 关闭 |
| 生产统一身份和单点登录 | 需部署确认 | 演示角色选择器不能替代生产鉴权 |
| 正式业务数据字典和阈值 | 需兴邦确认 | 演示字段和 120% 阈值不是制度 |
| 正式 OCR 与大模型质量验收 | 需专项验证 | 当前代码不能替代模型效果和 OCR 验收 |
| 自动把全部聊天转成企业经验 | 未实现且不建议直接实现 | 经验需要明确条件、评测和审核 |

## 二十二 如何判断一次运行是否可信

查看一次运行时，应按以下顺序核对：

1. 身份和项目是否正确，方案是否适用于当前角色。
2. 输入快照是否对应预期数据版本。
3. 数据卡是否读取成功，期间、口径、单位和币种是否一致。
4. 确定性步骤是否完成，比例和比较是否有证据。
5. 模型步骤是否完成必需工具读取，是否超时或超过预算。
6. 模型问题是否通过结构和证据校验。
7. 运行是否因项目中途更新而被标记为已取代。
8. 问题是否经过人工处理，评审节点是否全部形成结论。
9. 报告是否绑定正确快照和模板版本。
10. 最终批准或退回是否由有权限的评审员完成。

只看到一段自然语言结论，不足以证明一次运行可信。可信运行必须同时具有数据快照、证据、组件版本、步骤状态和人工决定。

## 二十三 术语对照

| 页面用语 | 技术对象 | 解释 |
| --- | --- | --- |
| 项目数据版本 | `project.data_revision` | 人工确认或补件后递增 |
| 本次运行 | `run` | 一次 AI 预审或独立评审任务 |
| 来源快照 | `snapshot` | 数据卡读取和材料证据冻结结果 |
| 问题 | `finding` | 跨运行维护状态的业务待办 |
| 检查 | `check` | 某一步在某一次运行产生的原始判断 |
| 数据卡 | `data_card` | SQL、映射、单位和口径配置 |
| Skill 卡 | `skill` | 确定性执行器或模型方法 |
| 规则卡 | `rule_set` | 阈值和条件判断集合 |
| 方案 | `plan` | 数据卡、Skills、规则、模板和预算组合 |
| 报告模板 | `template` | 报告章节和字段依赖 |
| 经验 | `experience_version` | 经过评测和审核的条件化核查知识 |
| 操作凭证 | 对象编号或事件编号 | 用于回到项目中追溯执行结果 |

## 二十四 代码定位索引

| 主题 | 主要文件 |
| --- | --- |
| 通用 Agent 创建与工具循环 | `backend/graph/agent.py` |
| 系统提示词拼装 | `backend/graph/prompt_builder.py` |
| 会话短期记忆和压缩摘要 | `backend/graph/session_manager.py` 与 `backend/api/compress.py` |
| 长期记忆向量索引 | `backend/graph/memory_indexer.py` |
| 数据卡读取与字段对齐 | `backend/services/assistant_data.py` |
| 确定性 Skill 和规则执行 | `backend/services/skill_executor.py` |
| 组件版本、发布与冻结 | `backend/services/component_registry.py` |
| 项目、评审池、补件和决定 | `backend/services/project_assistant.py` |
| 持久任务和执行顺序 | `backend/services/assistant_worker.py` |
| 受限模型工具和输出校验 | `backend/services/assistant_model.py` |
| 经验适用、评测和发布 | `backend/services/assistant_experiences.py` |
| SQLite 对象、事件和时间区间 | `backend/services/assistant_store.py` |
| 业务助手命令路由 | `backend/api/project_assistant.py` |
| 客户经理与评审员工作台 | `src/app/xingbang-workbench/page.tsx` |
| 业务助手 | `src/components/xingbang/BusinessAssistant.tsx` |

## 二十五 最终理解

当前兴邦项目把大模型放在一条受控的业务链中。数据卡解决数据从哪里来和如何对齐，确定性 Skills 解决可以程序化计算的问题，规则卡解决明确阈值和条件，模型 Skill 解决需要阅读方法和材料的语义核查，业务方案决定本次运行使用哪些组件，记忆系统分别保存聊天上下文、业务快照、组织经验和审计时间。

系统的核心不是让模型记住更多内容，而是让每次运行只读取被授权且已经冻结的内容，让所有输出经过证据和结构校验，再由客户经理和评审员完成业务闭环。