124 lines
8.6 KiB
Markdown
124 lines
8.6 KiB
Markdown
# 风险研判 Agent 验证版
|
||
|
||
本次范围：数据连接、数据卡、Skills、规则集、研判方案的持久化管理，以及按方案执行项目自查。
|
||
|
||
## 访问
|
||
|
||
- 当前验证地址：http://127.0.0.1:3012/data-access
|
||
- 验证后端：http://127.0.0.1:8012/docs
|
||
- 示例项目：`XB-2026-001`
|
||
|
||
正常应用入口 `backend/app.py` 已注册相同 API；首页侧边栏的风险研判入口指向本控制台。
|
||
独立后端使用 `python risk_agent_preview.py`，监听回环地址 8012，不初始化旧聊天模块的模型与索引。
|
||
前端代理默认指向 8002；验证服务通过 `RISK_AGENT_BACKEND_URL=http://127.0.0.1:8012` 指向独立后端。
|
||
|
||
## 操作
|
||
|
||
1. 数据卡：新建或复制卡片，选择复用连接，配置参数化 SQL、标准字段映射、单位和口径。
|
||
2. Skills：选择质量检查、比率计算、征信输入检查或本地模型执行器，配置输入及输出字段。
|
||
3. 规则集：配置标准字段、gt/lt/eq 运算符、阈值和核查建议。
|
||
4. 研判方案：勾选所需数据卡、Skills、规则集，保存并发布。
|
||
5. 项目自查：输入项目编号，选择方案运行。结果包含执行轨迹、来源字段和规则版本。
|
||
|
||
归档会保留历史配置；存在有效引用时禁止归档。编辑旧版本会被拒绝，需刷新后重试。
|
||
编辑并保存草稿后，该对象将不能被正式方案运行，重新发布后恢复。
|
||
数据卡测试执行的是已保存版本，非编辑框中未保存的草稿。
|
||
卡片所关联的 Skills 用作能力关联；执行清单以研判方案中的勾选为准。
|
||
|
||
## 当前真实执行能力
|
||
|
||
- SQLite 存储配置、修订和运行快照，文件位于已被 Git 忽略的 `backend/xingbang_data/risk_agent.sqlite3`。
|
||
- 对演示数据库真实执行 SQL；SQLite authorizer 禁止写入与附加数据库，绑定项目参数，限制执行步数和返回行数。
|
||
- 多张表可在 SQL 中关联，数据卡之间保持平级。支持唯一记录、最新一期、指定期间、保留多期四种方式。保留多期的数据供模型综合分析，不静默汇总成单个指标。
|
||
- 配置项目标识、期间字段和口径字段，检查错项目、重复记录、混合口径。金额支持元/万元/亿元换算为万元，保留原始值与转换后证据。
|
||
- 财务比率拒绝跨期间、跨口径混算。自定义金额字段通过 `field_units` 声明单位，已知金额标准字段默认采用数据卡单位。
|
||
- 执行所选 Skill 的质量检查、比率计算、征信输入检查，并应用所选规则。
|
||
- 输入缺失、单位冲突、分母无效、取数失败、依赖未发布均不作为无风险。
|
||
- 每次运行保存配置和数据证据，修改配置不覆盖历史运行。
|
||
- 规则集支持自然语言规则与可视化阈值条件。自然语言规则会在确定性计算和规则检查后与平级数据卡一并交给本地模型；无需再额外勾选模型 Skill。未配置模型时明确显示未完成。
|
||
- 支持建议及证据 JSON 导出，同项目在当前页面再次运行可比较指标变化。
|
||
|
||
## 本地模型
|
||
|
||
模型 Skill 可选，不配置模型时，确定性计算和规则仍能运行。
|
||
在启动后端前配置 OpenAI-compatible 内网端点：
|
||
|
||
```text
|
||
XINGBANG_LOCAL_MODEL_URL=http://127.0.0.1:11434/v1
|
||
XINGBANG_LOCAL_MODEL_NAME=本地模型名称
|
||
XINGBANG_LOCAL_MODEL_KEY=可选认证凭据
|
||
```
|
||
|
||
仅接受 localhost、回环或 RFC1918 内网 IPv4 地址。关闭环境代理和重定向，不使用旧项目外部模型配置。
|
||
模型建议单独标注待人工核实，不自动成为审批结论。
|
||
|
||
## mini-openclaw 内核接入
|
||
|
||
风险模型分析现已通过 `graph/agent.py` 中的 `AgentManager.invoke_scoped` 执行。
|
||
通用聊天与风险任务共享 `build_task_agent` / LangChain `create_agent` 工厂。
|
||
风险任务按次注入内网模型、授权工具和系统边界，不修改聊天模型配置、不读取通用聊天记忆。
|
||
|
||
执行链：授权项目取数和确定性检查 → `AgentManager` 工具循环 → 建议与完整消息轨迹 → 受项目权限保护的运行快照。
|
||
|
||
受控工具包括：`list_data_cards`、`read_data_card`、`read_checks_and_rules`、`read_selected_skill`。
|
||
工具只访问本次取得的不可变快照；模型不能自行取其他项目、写 SQL、调用终端或任意 Python。
|
||
确定性计算和制度检查仍为强制前置步骤，不交给模型决定是否跳过。
|
||
|
||
Skills 编辑页可选择原生 `backend/skills/**/SKILL.md`，目录由原有扫描器的共享发现函数读取。
|
||
默认综合研判使用 `risk_evidence/SKILL.md`。原生 Skill 内容及 Agent 的 assistant/tool 消息保存在本次运行记录，页面执行轨迹可以展开查看。
|
||
模型没有读取全部所选数据卡或所选原生 Skills 时，运行明确标记未完成，不接受无工具证据的直接回答。
|
||
|
||
本地模型须支持 OpenAI-compatible tool calling；未配置模型时仍完成确定性检查，但综合 Agent 分析显示未完成。
|
||
这不等于已完成现场模型联调。内核工具循环用无网络测试模型验证，现场模型能力需实际验收。
|
||
|
||
## 真实数据库连接
|
||
|
||
已实现 SQLite、PostgreSQL、MySQL 只读连接器，SQLAlchemy 执行绑定参数查询，sqlglot 检查单条 SELECT 和授权表清单。禁止自定义函数、写入、导出和锁定语句。限制超时与行数。
|
||
|
||
- SQLite：服务器配置 `XINGBANG_SQLITE_ROOT`，数据库文件必须在该目录内。使用只读文件模式及 SQLite authorizer。已通过临时真实数据库测试。
|
||
- PostgreSQL：填写主机、端口、数据库、只读账号、授权表及密码环境变量名称。使用 TLS 和只读事务。
|
||
- MySQL：填写同类信息，使用只读会话、查询及网络超时。部署前按兴邦网络策略配置链路加密。
|
||
- 密码不进入界面或配置历史。使用 `password_env` 引用 `XINGBANG_DB_` 前缀的服务器环境变量；部署时可以由外部密钥管理系统注入。
|
||
- 数据卡的“测试已保存版本”会真实执行配置 SQL，并展示结果与对齐检查。PostgreSQL/MySQL 尚无现场实例联调，不视为客户 ERP 已接通。
|
||
- SQL Server/Oracle 驱动尚未实现。
|
||
|
||
## 身份和审核
|
||
|
||
服务器可配置 `XINGBANG_AUTH_USERS` 为 JSON 数组，每项包含 `id`、高强度随机 `token`、`role` 和可选的 `projects`。
|
||
页面右上角“访问身份”输入分配的令牌，令牌仅保存在当前浏览器会话中。后端校验身份，不接受客户端自报角色。
|
||
|
||
```json
|
||
[
|
||
{"id":"it-editor","token":"REPLACE_WITH_RANDOM_EDITOR_TOKEN","role":"admin"},
|
||
{"id":"risk-reviewer","token":"REPLACE_WITH_RANDOM_REVIEWER_TOKEN","role":"reviewer"},
|
||
{"id":"customer-manager","token":"REPLACE_WITH_RANDOM_MANAGER_TOKEN","role":"manager","projects":["XB-2026-001"]}
|
||
]
|
||
```
|
||
|
||
不要使用上述占位符作为真实令牌。正式部署设置 `XINGBANG_REQUIRE_AUTH=1`，在 HTTPS 反向代理后运行。
|
||
|
||
- admin：保存草稿、提交审核、测试查询、运行研判。
|
||
- reviewer：查看配置和待审核版本，批准或驳回；不能修改配置或执行查询。
|
||
- manager：只查看已发布方案、运行授权项目、查看授权项目历史；无法读取 SQL 配置或管理数据卡。
|
||
- 正式模式禁止直接发布。审核人不能是编辑人或提交人。提交后修改的版本无法批准，必须重新提交。
|
||
- `/reviews/list` 展示审核记录；页面“发布审核”可核对版本并填写意见。
|
||
- `/audit/events` 为管理员/审核员提供配置创建、修改、提交、发布、归档、测试和研判的审计记录。
|
||
- 未配置身份时仅允许本机回环地址预览，并在页面标记“本机预览”；该模式保留一键发布以便演示。
|
||
|
||
这些是应用级基础授权与审核，并非企业 SSO、完整组织权限或合规认证。现场仍需接入兴邦身份体系、真实项目授权及运维密钥管理。
|
||
|
||
## 尚需现场确认
|
||
|
||
兴邦真实 ERP 连接及字段映射、正式风险规则、实际模型端点、项目授权来源、企业单点登录、附件/OCR 和财务特殊口径仍需现场配置或开发联调。当前建议不会代替正式业务决定，模型文本标记待人工核实，不能视为已验证结论。
|
||
|
||
## 验证
|
||
|
||
```text
|
||
python -m unittest discover -s backend -p "test_risk_agent*.py"
|
||
npx tsc --noEmit
|
||
node verify-risk-agent.cjs
|
||
```
|
||
|
||
23 项后端测试涵盖权限、审核、自然语言规则传入模型、只读真实 SQLite、SQL 限制、多期对齐与历史快照。模型调用使用替身测试，尚无实际模型联调。
|
||
浏览器脚本使用本机附带的 Playwright，验证桌面/手机布局、风险执行、Skill CRUD、方案勾选、数据对齐、规则表单及审核入口。
|