YG-Soft/X-Financial
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 新增agent开发文档和风险评估文档

Browse Source
This commit is contained in:
caoxiaozhu
2026-05-15 06:58:21 +00:00
parent 45abd36430
commit 4f3556a38b
35 changed files with 8257 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

58
document/development/agent/agent plan/00_README.md Normal file
View File

@@ -0,0 +1,58 @@
# Agent Plan 文档索引
本目录描述 X-Financial 后续要建设的双 Agent 财务智能架构。
核心目标：
- 建立一套共享的语义本体协议，统一理解用户问题、定时任务和规则触发上下文。
- 建设两套职责边界清晰的 Agent：
- Hermes：后台数字员工，负责内循环定时任务、风险巡检、统计、知识维护。
- 自建 Agent：用户流程助手，负责用户交互、流程操作、解释、查询、草稿生成。
- 建设 Agent Orchestrator，统一负责路由、权限、工具调用、审计和失败处理。
- 让规则中心、MCP、知识库、数据库查询和任务系统使用同一套语义协议。
## 与一周计划的关系
`document/development/agent week plan` 是一周开发路线图，只描述每天要完成的大方向和交付结果。
本目录是具体架构与实现依据，包含：
- 架构设计。
- 数据协议。
- Agent 职责。
- Orchestrator 流程。
- OCR、知识库、规则生命周期。
- 每天 daily 文档会引用到的设计依据。
执行时按这个顺序阅读：
1. 先看 `document/development/agent week plan/MASTER_TODO.md`，确认今天做什么。
2. 再看本目录的架构文档，理解为什么这样做。
3. 最后进入 `document/development/agent week plan/` 对应 Day 文档，在同一份文档中按详细执行清单开发。
推荐阅读顺序：
1. [01_overall_architecture.md](./01_overall_architecture.md)
2. [02_semantic_ontology.md](./02_semantic_ontology.md)
3. [03_agent_responsibilities.md](./03_agent_responsibilities.md)
4. [04_orchestrator_and_runtime_flow.md](./04_orchestrator_and_runtime_flow.md)
5. [05_development_roadmap.md](./05_development_roadmap.md)
6. [06_data_contracts_and_governance.md](./06_data_contracts_and_governance.md)
7. [07_capability_registry.md](./07_capability_registry.md)
8. [08_permission_confirmation.md](./08_permission_confirmation.md)
9. [09_observability_and_trace.md](./09_observability_and_trace.md)
10. [10_evaluation_and_testset.md](./10_evaluation_and_testset.md)
11. [11_ocr_invoice_architecture.md](./11_ocr_invoice_architecture.md)
12. [12_llm_wiki_knowledge_architecture.md](./12_llm_wiki_knowledge_architecture.md)
13. [13_rule_formation_lifecycle.md](./13_rule_formation_lifecycle.md)
14. [14_financial_document_canonical_model.md](./14_financial_document_canonical_model.md)
15. [15_feedback_learning_loop.md](./15_feedback_learning_loop.md)
16. [../agent week plan/00_README.md](<../agent week plan/00_README.md>)
开发原则：
- 先语义协议，后 Agent 能力。
- 先只读和建议，后写入和流程动作。
- 先人工确认，后有限自动化。
- 所有财务关键动作必须可审计、可回滚、可追责。
- 所有 Agent 能力必须注册、分级、可评测、可追踪。

163
document/development/agent/agent plan/01_overall_architecture.md Normal file
View File

@@ -0,0 +1,163 @@
# 双 Agent 总体架构
## 1. 背景
X-Financial 后续需要同时支持两类智能化能力：
1. 用户主动发起的交互式流程操作。
2. 系统后台自动运行的定时巡检、统计、预警和知识维护。
如果用一个万能 Agent 同时处理这两类任务，风险会很高：
- 用户流程操作需要权限、确认、上下文追问。
- 定时巡检需要稳定批处理、失败重试、审计记录。
- 财务系统不能让大模型直接决定审批、付款、规则上线。
因此建议建设双 Agent 架构：
```text
Hermes Agent
后台数字员工
面向系统内循环
定时、批量、巡检、统计、预警、知识候选
User Agent
自建用户流程助手
面向用户交互
查询、解释、创建草稿、流程操作、审批辅助
```
两套 Agent 共享一套语义本体协议，由 Agent Orchestrator 统一调度。
## 2. 总体架构图
```text
┌──────────────────────┐
│ 用户自然语言 / 定时任务 │
└───────────┬──────────┘
│
▼
┌──────────────────────┐
│ Semantic Ontology │
│ 语义本体解析层 │
└───────────┬──────────┘
│
▼
┌──────────────────────┐
│ Agent Orchestrator │
│ 路由 / 权限 / 审计 / 调度 │
└───────┬─────────┬────┘
│ │
┌─────────────▼─┐ ┌─▼──────────────┐
│ Hermes Agent │ │ User Agent │
│ 后台数字员工 │ │ 用户流程助手 │
└───────┬───────┘ └───────┬────────┘
│ │
└──────────┬──────────┘
│
┌────────────┬───────────┼───────────┬────────────┐
▼ ▼ ▼ ▼ ▼
规则中心 MCP 服务 业务数据库 知识库 任务系统
```
## 3. 核心分层
### 3.1 语义本体层
负责把自然语言或任务配置转成结构化 JSON。
输出不是最终答案，而是统一协议：
```json
{
"domain": "reimbursement",
"scenario": "invoice_validation",
"intent": "explain_risk",
"entities": [],
"time_range": {},
"constraints": {},
"risk_signals": [],
"next_step": "run_rule"
}
```
### 3.2 编排层
Agent Orchestrator 负责：
- 判断应该由 Hermes 还是 User Agent 处理。
- 判断是否需要查数据库、跑规则、调 MCP、检索知识库。
- 检查用户权限。
- 记录审计日志。
- 控制失败重试。
- 对高风险动作要求用户或管理员确认。
### 3.3 Agent 层
Hermes 和 User Agent 不直接决定财务关键状态。
它们负责：
- 理解任务。
- 组织工具调用。
- 汇总工具结果。
- 生成建议、解释、报告、草稿。
### 3.4 能力层
能力层包括：
- 规则中心：管理 `.md` 规则文件、审核、版本。
- MCP：封装外部服务，如发票验真、银行流水、OCR、差旅平台。
- 数据库查询：查询报销、报账、应收、应付、账款数据。
- 知识库：制度文档、FAQ、历史解释、规则说明。
- 任务系统：定时任务、批量任务、重试、运行日志。
## 4. 关键边界
Hermes 可以：
- 定时读取数据。
- 执行规则检查。
- 调 MCP 查询外部状态。
- 生成风险报告。
- 生成知识候选。
- 生成待处理工单。
Hermes 不可以：
- 自动提交报销。
- 自动发起付款。
- 自动审批通过。
- 自动发布知识库正式内容。
- 自动上线规则。
User Agent 可以：
- 帮用户查询状态。
- 帮用户解释风险。
- 帮用户创建报销或付款草稿。
- 帮审批人生成审批意见。
- 在用户确认后调用流程 API。
User Agent 不可以：
- 绕过权限。
- 未确认直接提交关键动作。
- 自动最终审批。
- 自动付款。
- 修改规则审核状态。
## 5. 推荐建设顺序
```text
Step 1: 建立语义本体 JSON 协议
Step 2: 建立规则中心的规则/技能/MCP/任务目录
Step 3: 建立 Orchestrator 路由和审计
Step 4: 建立 User Agent 的只读查询和解释能力
Step 5: 建立 Hermes 的定时任务和报告能力
Step 6: 接入 MCP 和业务数据库
Step 7: 增加用户确认后的流程写入能力
Step 8: 增加知识候选和规则优化闭环
```

457
document/development/agent/agent plan/02_semantic_ontology.md Normal file
View File

@@ -0,0 +1,457 @@
# 语义本体协议设计
## 1. 定位
语义本体协议是用户问题、定时任务、规则中心、MCP、数据库查询和 Agent 之间的统一中间层。
它解决的问题是：
- 用户到底在问哪个业务域？
- 这属于什么场景？
- 用户想做什么？
- 问题中涉及哪些对象？
- 有没有时间、金额、状态、部门等过滤条件？
- 是否涉及风险？
- 下一步应该查知识库、查数据库、跑规则、调 MCP，还是追问？
## 2. 第一版核心字段
第一版建议只强制落 8 个字段。
```json
{
"domain": "",
"scenario": "",
"intent": "",
"entities": [],
"time_range": {},
"constraints": {},
"risk_signals": [],
"next_step": ""
}
```
### 2.1 domain
一级业务域。
建议枚举：
```text
reimbursement
accounts_receivable
accounts_payable
general_finance
system_operation
```
含义：
- `reimbursement`：报销、差旅、发票、补件。
- `accounts_receivable`：应收账款、客户开票、收款、账龄。
- `accounts_payable`：应付账款、供应商发票、付款、对账。
- `general_finance`：通用财务知识、制度、统计。
- `system_operation`：系统巡检、任务运行、规则维护、MCP 健康检查。
### 2.2 scenario
细分场景。
报销：
```text
travel_reimbursement
daily_expense
invoice_validation
attachment_review
policy_overrun
reimbursement_audit
```
应收：
```text
customer_invoice
collection_followup
receivable_aging
payment_matching
bad_debt_risk
contract_receivable
```
应付：
```text
vendor_invoice
payment_request
payable_aging
vendor_reconciliation
invoice_matching
cash_outflow_forecast
```
系统运营：
```text
daily_risk_scan
daily_finance_statistics
knowledge_accumulation
mcp_health_check
rule_quality_review
```
### 2.3 intent
用户或任务的意图。
建议枚举：
```text
query
explain
create
validate
summarize
reconcile
monitor
predict
remind
generate
optimize
```
### 2.4 entities
识别出的业务对象。
统一结构：
```json
{
"type": "invoice",
"value": "INV-202605001",
"normalized_value": "INV-202605001",
"role": "target",
"confidence": 0.92
}
```
常见实体：
```text
employee
department
customer
vendor
invoice
contract
reimbursement_request
payment_order
receipt
bank_transaction
cost_center
project
policy
approval_node
rule
task
```
### 2.5 time_range
统一描述时间。
```json
{
"raw": "上个月",
"start": "2026-04-01",
"end": "2026-04-30",
"granularity": "month"
}
```
Hermes 定时任务也使用同一字段。
例如每日风险巡检：
```json
{
"raw": "昨日",
"start": "2026-05-09",
"end": "2026-05-09",
"granularity": "day"
}
```
### 2.6 constraints
查询、判断或执行条件。
```json
{
"status": "overdue",
"aging_days": ">30",
"amount": {
"operator": ">",
"value": 50000,
"currency": "CNY"
},
"department": "销售部",
"risk_level": ["medium", "high"]
}
```
### 2.7 risk_signals
风险信号。
建议枚举：
```text
duplicate_invoice
missing_attachment
policy_overrun
over_budget
overdue_receivable
bad_debt_risk
vendor_payment_risk
payment_mismatch
contract_mismatch
cashflow_pressure
mcp_unavailable
rule_quality_issue
```
### 2.8 next_step
下一步动作。
建议枚举：
```text
answer
ask_clarification
query_database
run_rule
call_mcp
search_knowledge
create_draft
create_task
generate_report
notify_user
escalate_to_human
```
## 3. 扩展字段
后续可以增加：
```json
{
"schema_version": "1.1",
"confidence": 0.86,
"ambiguity": [],
"missing_slots": [],
"required_capabilities": [],
"normalized_query": "",
"permission_scope": {},
"audit_tags": []
}
```
## 4. 混合语义解析架构
第一版可上线实现不应只依赖关键词和正则。
推荐采用：
```text
输入上下文装配
用户文本 + 页面上下文 + 附件名称 + OCR/VLM 摘要
↓
预抽取
时间、金额、单号、显式对象
↓
LLM 结构化解析
输出 scenario / intent / entities / missing_slots / ambiguity
↓
Schema 校验
JSON 解析、字段枚举、必填校验、类型归一化
↓
规则兜底
模型失败、低置信度或字段缺失时回退到规则解析
↓
澄清追问
低置信度、歧义、缺槽位时不允许直接查库
```
设计原则：
- 模型优先负责“理解意图和场景”。
- 规则优先负责“校验、补全和兜底”。
- 附件名称、OCR、VLM 结果只能作为证据，不等于已确认事实。
- 所有语义输出都必须标记置信度和来源。
## 5. 推荐新增字段
为支持模型优先解析，建议在扩展字段中至少增加：
```json
{
"missing_slots": [],
"ambiguity": [],
"field_confidence": {},
"field_source": {},
"attachment_context": [],
"parse_strategy": "llm_primary_with_rule_fallback"
}
```
字段说明：
- `missing_slots`：还缺哪些关键字段，例如费用类型、单据号、客户单位。
- `ambiguity`：当前可能混淆的理解结果。
- `field_confidence`：字段级置信度，而不是只给整体分数。
- `field_source`：字段来自 `llm`、`rule`、`ocr`、`vlm` 还是 `user_context`。
- `attachment_context`：本次可供语义解析使用的附件摘要。
- `parse_strategy`：标记本次是模型主解析还是规则回退。
## 6. 叙述型财务输入
语义层必须支持“不是查询句”的自然叙述。
典型样例：
```text
我今天去客户现场，招待了客户，花销了1000元
我垫付了打车费和餐费，帮我看看怎么报
上传了三张票，帮我整理成报销草稿
```
这类输入不能默认识别成 `query`。
建议默认策略：
- 优先识别为 `reimbursement` 域。
- 场景优先落到 `daily_expense`、`travel_reimbursement` 或 `attachment_review`。
- 意图优先落到 `create`、`generate` 或 `validate`。
- 缺失关键字段时返回 `ask_clarification`，而不是直接查数据库。
## 7. 模糊短句与澄清规则
以下输入应优先追问：
```text
我要报销
这个为什么还没处理
帮我看一下这个
上传好了，下一步呢
```
处理原则：
- 不允许直接执行工具。
- 不允许直接落到应收、应付查询。
- 必须生成澄清问题。
- 必须在审计中记录触发追问的原因。
扩展原则：
- 先不要把所有字段都做成数据库列。
- 语义结果建议存 JSONB。
- 使用 `schema_version` 管理版本。
- Orchestrator 只依赖稳定字段。
- 新字段以可选方式加入，不影响老任务。
## 4. 示例
### 4.1 用户查询应收账龄
用户问：
```text
上个月哪些客户应收逾期超过 30 天？
```
解析：
```json
{
"domain": "accounts_receivable",
"scenario": "receivable_aging",
"intent": "query",
"entities": [
{
"type": "customer",
"value": "客户",
"role": "group_by"
}
],
"time_range": {
"raw": "上个月",
"start": "2026-04-01",
"end": "2026-04-30",
"granularity": "month"
},
"constraints": {
"aging_days": ">30",
"status": "overdue"
},
"risk_signals": ["overdue_receivable"],
"next_step": "query_database"
}
```
### 4.2 用户解释发票拦截
用户问：
```text
这张发票为什么报销被拦截？
```
解析：
```json
{
"domain": "reimbursement",
"scenario": "invoice_validation",
"intent": "explain",
"entities": [
{
"type": "invoice",
"value": "这张发票",
"role": "target"
}
],
"time_range": {},
"constraints": {},
"risk_signals": ["unknown"],
"next_step": "run_rule"
}
```
### 4.3 Hermes 每日风险巡检
任务配置：
```json
{
"domain": "reimbursement",
"scenario": "daily_risk_scan",
"intent": "monitor",
"entities": [],
"time_range": {
"raw": "昨日"
},
"constraints": {
"risk_level": ["medium", "high"]
},
"risk_signals": [
"duplicate_invoice",
"missing_attachment",
"policy_overrun"
],
"next_step": "run_rule"
}
```

178
document/development/agent/agent plan/03_agent_responsibilities.md Normal file
View File

@@ -0,0 +1,178 @@
# Hermes 与自建 Agent 职责边界
## 1. 两套 Agent 的定位
### 1.1 Hermes
Hermes 定位为后台数字员工。
它不直接面向用户聊天，而是在系统后台做内循环工作。
关键词：
```text
定时
批量
巡检
统计
预警
知识维护
规则质量复盘
```
### 1.2 自建 Agent
自建 Agent 定位为用户流程助手。
它直接面对员工、财务人员、审批人和管理员。
关键词：
```text
用户触发
会话式
流程操作
查询解释
草稿生成
审批辅助
用户确认
```
## 2. Hermes 职责
Hermes 负责：
1. 每日风险巡检。
2. 每日报销、报账、账款统计。
3. 应收逾期预警。
4. 应付付款风险预警。
5. 规则命中质量复盘。
6. MCP 健康检查。
7. 知识库候选内容生成。
8. 高风险工单生成。
9. 任务运行报告生成。
Hermes 输出的内容包括：
```text
risk_report
risk_work_items
daily_finance_snapshot
knowledge_candidates
rule_improvement_items
mcp_health_report
task_run_log
```
Hermes 不允许：
1. 自动审批通过。
2. 自动发起付款。
3. 自动提交用户申请。
4. 自动发布正式知识库。
5. 自动上线规则。
6. 直接修改核心财务状态。
## 3. 自建 Agent 职责
自建 Agent 负责：
1. 查询报销单进度。
2. 创建报销或付款草稿。
3. 解释规则拦截原因。
4. 生成审批意见。
5. 检索制度知识。
6. 查询应收应付数据。
7. 帮用户对账。
8. 引导用户补充缺失信息。
9. 在用户确认后调用流程 API。
自建 Agent 输出的内容包括：
```text
natural_language_answer
form_draft
approval_opinion_draft
clarification_question
query_result_summary
next_action_suggestion
```
自建 Agent 不允许：
1. 未经用户确认提交关键动作。
2. 跳过权限校验。
3. 自动最终审批。
4. 自动付款。
5. 修改规则上线状态。
## 4. 权限边界
| 动作 | Hermes | 自建 Agent |
|---|---|---|
| 查询制度知识 | 可以 | 可以 |
| 查询业务数据 | 可以，按任务权限 | 可以，按用户权限 |
| 跑规则 | 可以 | 可以 |
| 调 MCP | 可以 | 可以 |
| 生成报告 | 可以 | 可以 |
| 生成草稿 | 不建议 | 可以 |
| 提交流程 | 不可以 | 用户确认后可以 |
| 审批通过 | 不可以 | 不可以直接做 |
| 发起付款 | 不可以 | 高权限确认后才可做草稿 |
| 发布知识 | 不可以 | 不可以 |
| 上线规则 | 不可以 | 不可以 |
## 5. 共享能力
两套 Agent 共享：
- 语义本体协议。
- 规则中心。
- MCP 服务。
- 知识库。
- 数据库查询服务。
- 审计日志。
- 权限系统。
不共享：
- 运行队列。
- 调度策略。
- 用户会话状态。
- 任务重试状态。
## 6. 示例
### 6.1 Hermes 场景
每日 02:00 自动运行：
```text
每日风险巡检
读取昨日报销、报账、发票、账款数据
执行规则
调用发票验真 MCP
调用账款流水 MCP
生成风险报告
生成风险工单
```
### 6.2 自建 Agent 场景
用户问：
```text
帮我看一下这张差旅报销为什么没通过。
```
处理：
```text
解析语义
查询报销单
读取规则命中
检索制度条款
组织解释
给出补件建议
```

385
document/development/agent/agent plan/04_orchestrator_and_runtime_flow.md Normal file
View File

@@ -0,0 +1,385 @@
# Agent Orchestrator 与运行流程
## 1. Orchestrator 定位
Agent Orchestrator 是双 Agent 架构的调度中心。
它不负责生成最终答案，而是负责：
- 接收用户请求或定时任务。
- 调用语义解析。
- 判断处理方。
- 选择工具。
- 检查权限。
- 记录审计。
- 管理失败重试。
- 控制高风险动作确认。
## 2. 运行主流程
```text
输入
用户消息 / 页面按钮 / 定时任务 / 系统事件
↓
上下文装配
页面对象 / 附件名称 / OCR 摘要 / VLM 摘要 / 用户角色 / conversation_id / draft_claim_id
↓
语义解析
LLM 主解析 + 规则兜底，输出 ontology_json
↓
语义校验
confidence / missing_slots / ambiguity / permission 初判
↓
Orchestrator 决策
判断 agent = hermes | user_agent
判断 tool = rule | mcp | db | knowledge | task
↓
权限检查
用户权限 / 任务权限 / 数据范围
↓
业务写入
报销草稿创建 / 报销草稿更新 / 用户确认后提交
↓
工具执行
规则中心 / MCP / 数据库 / 知识库 / 任务系统
↓
Agent 汇总
Hermes 报告 / User Agent 回答
↓
审计记录
保存输入、语义、工具、结果、动作
```
## 3. 路由规则
### 3.1 Hermes 路由
满足以下条件之一，进入 Hermes：
```text
source = schedule
source = system_event
intent = monitor
intent = summarize and no active user session
next_step = generate_report and task_type is batch
scenario in daily_risk_scan / knowledge_accumulation / mcp_health_check
```
补充约束：
- 这里的 Hermes 指系统后台真实 Hermes 进程或 Hermes CLI，不是前端概念上的 “Hermes 模式”。
- Orchestrator 负责路由、权限、审计和 Trace，不负责替代 Hermes 自身执行。
- 当前阶段允许保留本地 fallback，但必须预留真实 Hermes 进程调用入口。
### 3.2 User Agent 路由
满足以下条件之一，进入自建 Agent：
```text
source = user_message
source = page_action
intent = query / explain / create / validate / reconcile
requires_user_context = true
next_step = ask_clarification
next_step = create_draft
```
### 3.3 工具路由
```text
next_step = query_database
调用数据库查询服务
next_step = run_rule
调用规则中心
next_step = call_mcp
调用 MCP 服务
next_step = search_knowledge
调用知识库检索
next_step = create_task
调用任务系统
next_step = create_expense_claim_draft
创建 expense_claims / expense_claim_items 草稿
next_step = update_expense_claim_draft
回写报销主表、明细和附件关联
next_step = submit_expense_claim
用户确认后更新 expense_claims.status = submitted
next_step = ask_clarification
返回追问
```
### 3.4 低置信度与缺槽位保护
当满足以下任一条件时，不允许直接进入数据库、MCP 或高风险流程：
```text
confidence < threshold
missing_slots 非空
ambiguity 非空
输入为叙述型报销，但缺少关键报销信息
```
处理方式：
```text
next_step = ask_clarification
selected_agent = user_agent
tool_count = 0
```
### 3.5 叙述型报销输入保护
像下面这类文本：
```text
我今天去客户现场，招待了客户，花销了1000元
我垫付了交通费和午餐费
我上传了票据，帮我整理一下
```
不能因为出现“客户”就落到应收查询。
Orchestrator 应依赖语义层返回的 `scenario + intent + missing_slots` 做决策，而不是二次猜测文本关键词。
### 3.6 报销建单与状态流转边界
当 `scenario = expense` 且已满足最小建单槽位时：
```text
next_step = create_expense_claim_draft
status = draft
```
当用户继续补充金额、地点、客户、参与人、附件时：
```text
next_step = update_expense_claim_draft
status 保持 draft
```
当用户明确说“提交报销”并完成确认时：
```text
next_step = submit_expense_claim
status = submitted
requires_confirmation = true
```
以下状态不应由 User Agent 直接改写：
```text
approved
rejected
paid
```
这些状态应由审批流、财务支付流或受控后台同步更新。
### 3.7 结构化核对回路
当 `scenario = expense` 且当前仍存在缺槽位、附件待核对或票据需拆单时，不直接返回一段自由文本，而是返回结构化核对结果：
```text
result.review_payload
intent_summary
body_message
slot_cards
risk_briefs
document_cards
claim_groups
confirmation_actions = 取消 / 修改 / 保存草稿或下一步
edit_fields
```
前端正文区只展示简洁提示，右侧展示字段、风险、票据与分单明细。
### 3.8 会话续接与重识别
用户对话不是无状态调用。Orchestrator 需要携带以下会话字段继续当前报销流程：
```text
conversation_id
draft_claim_id
conversation_history
review_action
review_form_values
```
其中：
```text
review_action = edit_review
表示用户基于结构化模板修改识别结果，需要重新进入语义识别
review_action = save_draft
表示信息未补齐，但允许先保存报销草稿
review_action = next_step
表示用户确认当前识别结果，可进入下一步流转
```
## 4. 用户流程示例
用户输入：
```text
上个月哪些客户应收逾期超过 30 天？
```
流程：
```text
Step 1: User Agent 接收消息
Step 2: semantic_parser 输出 ontology_json
Step 3: Orchestrator 识别 domain = accounts_receivable
Step 4: next_step = query_database
Step 5: 权限检查用户是否可看应收数据
Step 6: 查询应收账龄表
Step 7: User Agent 汇总结果
Step 8: 返回客户清单、金额、逾期天数、风险说明
```
## 5. Hermes 任务示例
任务：
```text
每日风险巡检
```
流程：
```text
Step 1: 任务调度器在 02:00 触发
Step 2: Orchestrator 构造 ontology_json
Step 3: 路由给 Hermes
Step 4: Hermes 拉取昨日业务快照
Step 5: 执行规则中心规则
Step 6: 调用 MCP 验真、账款流水
Step 7: 生成风险报告
Step 8: 写入风险工单
Step 9: 记录任务日志
Step 10: 通知财务风控组
```
### 5.1 Hermes 后台执行方式
推荐最小形态：
```text
任务系统 / 手动触发 API
↓
Orchestrator 生成 run_id、任务上下文、权限信息
↓
后端调用系统 Hermes CLI 或 Hermes 后台进程
↓
Hermes 执行知识同步 / 风险巡检 / 规则草稿形成
↓
结果回写 AgentRun / ToolCall / 审计日志
```
约束：
- Hermes 运行使用系统级配置，不在任务代码里再写一套模型配置。
- Hermes 运行失败要记录 stderr 或等价错误摘要。
- Hermes 输出的知识候选和规则草稿必须回写为结构化结果，不只保留终端文本。
## 5A. 用户报销建单示例
用户输入：
```text
我今天去客户现场，招待了客户，花销了1000元
```
流程：
```text
Step 1: User Agent 接收消息
Step 2: semantic_parser 输出 ontology_json
Step 3: Orchestrator 判断 scenario = expense, intent = draft
Step 4: 若缺客户、参与人、附件，则 next_step = ask_clarification
Step 5: 补齐最小槽位后，next_step = create_expense_claim_draft
Step 6: 创建 expense_claims / expense_claim_items
Step 7: 若有附件，则挂接 document_assets / expense_item_documents
Step 8: 用户确认提交后，next_step = submit_expense_claim
Step 9: 更新 expense_claims.status = submitted
Step 10: 写入 AgentRun、ToolCall、AuditLog
```
## 6. 审计日志
每次 Agent 运行都应该写入审计。
建议字段：
```json
{
"id": "",
"source": "user_message | schedule | system_event",
"agent": "hermes | user_agent",
"user_id": "",
"task_id": "",
"ontology_json": {},
"tools_called": [],
"permission_scope": {},
"result_summary": "",
"action_taken": "",
"requires_confirmation": false,
"created_at": ""
}
```
建议补充 Trace 字段：
```json
{
"semantic_provider": "",
"semantic_model": "",
"semantic_prompt_version": "",
"semantic_parse_strategy": "llm_primary | rule_fallback",
"semantic_fallback_reason": "",
"semantic_latency_ms": 0
}
```
## 7. 失败处理
### 7.1 用户交互失败
```text
数据库查询失败
返回“暂时无法查询”，记录错误
缺少关键字段
返回追问
权限不足
返回无权限说明
MCP 不可用
返回降级说明，必要时生成待处理项
```
### 7.2 Hermes 任务失败
```text
任务失败
自动重试 3 次
部分 MCP 失败
标记 partial_success
数据不完整
生成异常任务日志
连续失败
通知管理员
```

458
document/development/agent/agent plan/05_development_roadmap.md Normal file
View File

@@ -0,0 +1,458 @@
# 分阶段开发计划
## Phase 0：准备阶段
目标：统一概念和边界，不写复杂功能。
### Step 0.1 明确术语
产出：
- 规则：`.md` 审查规则文件。
- 技能：可复用的 Agent 能力，如审批意见生成、风险解释。
- MCP：外部服务连接。
- 任务：定时或批量运行的后台作业。
- Hermes：后台数字员工。
- User Agent：用户流程助手。
- Orchestrator：调度和路由层。
- Ontology：语义本体协议。
### Step 0.2 冻结第一版语义字段
第一版只强制 8 个字段：
```text
domain
scenario
intent
entities
time_range
constraints
risk_signals
next_step
```
### Step 0.3 建立设计文档
产出：
- 本目录所有文档。
- 后续数据库表设计草案。
- API 合同草案。
## Phase 1：任务规则中心基础建设
目标：先把管理后台搭起来。
### Step 1.1 完成前端信息架构
页签：
```text
规则 / 技能 / MCP / 任务
```
规则详情：
- Markdown 编辑器。
- 审核人。
- 审核状态。
- 版本列表。
- 版本切换确认。
技能详情：
- 技能配置。
- 输入上下文。
- 输出契约。
- 测试样例。
- 依赖能力。
MCP 详情：
- 服务地址。
- 鉴权方式。
- 权限范围。
- 健康检查。
- 调用记录。
任务详情：
- Cron。
- 运行窗口。
- 输入范围。
- 产出对象。
- 最近运行。
### Step 1.2 建立后端基础模型
建议表：
```text
agent_rules
agent_skills
agent_mcp_services
agent_tasks
agent_asset_versions
agent_asset_reviews
```
第一阶段可以先不做完整执行，只做 CRUD。
### Step 1.3 规则版本与审核
规则上线流程：
```text
草稿
↓
提交审核
↓
审核通过
↓
上线
```
关键约束：
- 没有审核人不能上线。
- 没有审核通过不能上线。
- 上线必须生成新版本。
- 历史版本只读。
## Phase 2：OCR 与财务单据标准模型
目标：让发票、附件、报销单和账款流水先标准化。
### Step 2.1 附件上传与文件分类
识别：
- 发票。
- 行程单。
- 合同。
- 付款凭证。
- 审批截图。
### Step 2.2 OCR MCP 接入
把附件转成结构化字段。
### Step 2.3 Invoice 标准模型
统一 OCR、MCP、用户填写和业务系统字段。
### Step 2.4 人工修正
允许财务人员修正 OCR 字段，并写入反馈池。
### Step 2.5 规则中心接入 OCR 结果
重复发票、附件完整性、金额不一致等规则开始使用标准模型。
## Phase 3：语义本体服务
目标：用户问题和任务配置都能转成 ontology_json。
### Step 3.1 建立 semantic_parser API
接口：
```text
POST /api/v1/semantic/parse
```
输入：
```json
{
"source": "user_message",
"text": "上个月哪些客户应收逾期超过 30 天？",
"context": {}
}
```
输出：
```json
{
"domain": "accounts_receivable",
"scenario": "receivable_aging",
"intent": "query",
"entities": [],
"time_range": {},
"constraints": {},
"risk_signals": [],
"next_step": "query_database"
}
```
### Step 3.2 建立模型优先解析器
要求：
- 使用运行时模型配置，而不是写死单一 provider。
- 输入包括文本、上下文、附件摘要和预抽取字段。
- 输出必须是结构化 JSON，而不是自由文本。
- 输出必须经过 Schema 校验。
- 模型失败时必须回退到规则解析。
### Step 3.3 建立 ontology schema 表
建议表：
```text
semantic_ontology_schemas
semantic_parse_logs
```
字段：
```text
id
schema_version
schema_json
status
created_at
updated_at
```
### Step 3.4 建立字段级校验与澄清策略
至少支持：
- 缺少费用类型时追问。
- 缺少业务对象时追问。
- 短句或模糊句时追问。
- 叙述型报销输入默认走 create/generate，而不是 query。
- 低置信度时禁止工具执行。
### Step 3.5 建立解析测试集
至少覆盖：
- 报销规则解释。
- 差旅报销创建。
- 叙述型报销创建。
- 发票验真。
- 应收逾期查询。
- 应付付款状态。
- 每日风险巡检。
- 知识库维护。
- 模糊短句追问。
- 附件输入解析。
## Phase 4：LLM Wiki 知识库
目标：让制度文档、FAQ、审批经验可被 Agent 检索和引用。
### Step 4.1 文档解析与分块
上传 PDF、Word、Excel 后抽取正文并 chunk。
### Step 4.2 元数据与向量索引
为知识块打 domain、scenario、tags、版本。
### Step 4.3 知识检索 API
User Agent 可以基于语义本体查询知识。
### Step 4.4 知识候选审核
Hermes 生成 FAQ 或条款候选，人工审核后发布。
## Phase 5：Orchestrator 基础版
目标：基于 ontology_json 做确定性路由。
### Step 5.1 建立路由规则
输入：
```text
source
domain
scenario
intent
next_step
```
输出：
```text
agent = hermes | user_agent
tools = []
permission_required = []
```
### Step 5.2 建立工具网关
第一批工具：
```text
rule_engine.run
knowledge.search
database.query
mcp.call
task.create
```
### Step 5.3 建立审计日志
所有请求都记录：
- 原始输入。
- 语义 JSON。
- 路由结果。
- 工具调用。
- 输出摘要。
- 错误信息。
## Phase 6：User Agent 第一版
目标：先做只读和解释，不做强写入。
### Step 6.1 支持制度问答
流程：
```text
用户问题
-> semantic_parse
-> search_knowledge
-> User Agent 生成回答
```
### Step 6.2 支持规则解释
流程：
```text
用户问为什么被拦截
-> semantic_parse
-> run_rule
-> search_knowledge
-> User Agent 解释风险原因
```
### Step 6.3 支持业务查询
先支持：
- 报销单状态查询。
- 应收账龄查询。
- 应付付款状态查询。
### Step 6.4 支持草稿生成
只生成草稿，不直接提交。
```text
用户确认前不写核心状态
```
## Phase 7：Hermes 第一版
目标：让后台数字员工开始跑任务。
### Step 7.1 每日风险巡检
输入：
- 昨日单据。
- 发票。
- 附件。
- 付款流水。
输出：
- 风险报告。
- 风险工单。
- 风险统计。
### Step 7.2 每日财务统计
统计：
- 报销金额。
- 报账金额。
- 应收账龄。
- 应付账龄。
- 付款状态。
- 账款异常。
### Step 7.3 知识候选积累
来源：
- 审批意见。
- 驳回原因。
- 高频问答。
- 规则误报反馈。
输出：
- FAQ 候选。
- 规则优化建议。
- 制度变更摘要。
## Phase 8：MCP 接入
目标：让 Agent 能安全调用外部系统。
优先接入：
1. 发票验真 MCP。
2. 附件 OCR MCP。
3. 银行流水 MCP。
4. 差旅平台 MCP。
5. ERP/付款状态 MCP。
每个 MCP 必须有：
- 服务地址。
- 鉴权方式。
- 权限范围。
- 超时设置。
- 降级策略。
- 健康检查。
- 调用日志。
## Phase 9：规则形成与反馈闭环
目标：让系统持续变聪明，但不失控。
闭环：
```text
Hermes 发现问题
-> 生成规则优化建议
-> 管理员审核
-> 更新规则
-> User Agent 使用新规则解释
-> 反馈继续进入 Hermes
```
关键限制：
- Hermes 只生成候选。
- 管理员审核后才能发布。
- 所有规则变更有版本。
- 所有上线动作有审核人。
### Step 9.1 规则候选池
Hermes 从制度、风险案例、反馈中生成规则候选。
### Step 9.2 规则测试样例
每条规则上线前必须有测试样例。
### Step 9.3 反馈池
收集 OCR 修正、规则误报、Agent 回答反馈。
### Step 9.4 质量看板
统计误报率、修正率、回答满意度、MCP 失败率。

445
document/development/agent/agent plan/06_data_contracts_and_governance.md Normal file
View File

@@ -0,0 +1,445 @@
# 数据契约与治理要求
## 1. 推荐数据表
### 1.1 语义本体
```text
semantic_ontology_schemas
```
字段：
```text
id
schema_version
schema_json
status
created_by
created_at
updated_at
```
```text
semantic_parse_logs
```
字段：
```text
id
source
user_id
raw_text
ontology_json
confidence
parse_strategy
created_at
```
### 1.2 Agent 资产
```text
agent_rules
agent_skills
agent_mcp_services
agent_tasks
```
通用字段：
```text
id
code
name
description
status
owner
reviewer
config_json
created_at
updated_at
```
### 1.3 版本与审核
```text
agent_asset_versions
```
字段：
```text
id
asset_type
asset_id
version
content
change_note
created_by
created_at
```
```text
agent_asset_reviews
```
字段：
```text
id
asset_type
asset_id
version
reviewer
review_status
review_note
reviewed_at
```
### 1.4 运行日志
```text
agent_runs
```
字段：
```text
id
agent
source
task_id
user_id
ontology_json
status
started_at
finished_at
result_summary
error_message
```
```text
agent_tool_calls
```
字段：
```text
id
run_id
tool_type
tool_name
request_json
response_json
status
duration_ms
created_at
```
### 1.5 财务业务主表
```text
expense_claims
expense_claim_items
accounts_receivable
accounts_payable
approval_records
```
治理要求：
- `expense_claims` 作为报销主表，不再继续扩张 `reimbursement_requests`。
- `expense_claim_items` 作为报销明细最小粒度，OCR 匹配、风险识别、票据挂接都优先挂到该粒度。
- `accounts_receivable` 与 `accounts_payable` 保持独立，避免因为 Agent 语义层接入而混用口径。
### 1.6 票据与文件资产表
```text
document_assets
document_asset_versions
document_derivatives
expense_item_documents
document_access_logs
```
职责：
- `document_assets`：原始附件主索引
- `document_asset_versions`：原件版本留痕
- `document_derivatives`：预览件、缩略图、脱敏件、逐页图片
- `expense_item_documents`：报销明细与票据关联
- `document_access_logs`：预览、下载、导出审计
### 1.7 OCR、验真与风险表
```text
document_ocr_results
invoice_structured_records
invoice_verification_records
risk_events
risk_actions
```
职责：
- `document_ocr_results`：每次 OCR 执行快照
- `invoice_structured_records`：标准化发票字段
- `invoice_verification_records`：发票验真结果留痕
- `risk_events`：风险命中事实
- `risk_actions`：风险处置动作
## 2. API 契约
### 2.1 语义解析
```text
POST /api/v1/semantic/parse
```
请求：
```json
{
"source": "user_message",
"text": "这张发票为什么被拦截？",
"context": {
"user_id": "emp_001",
"current_page": "reimbursement_detail"
}
}
```
响应：
```json
{
"domain": "reimbursement",
"scenario": "invoice_validation",
"intent": "explain",
"entities": [],
"time_range": {},
"constraints": {},
"risk_signals": ["unknown"],
"parse_strategy": "llm_primary",
"next_step": "run_rule"
}
```
### 2.2 Orchestrator 执行
```text
POST /api/v1/agent/orchestrate
```
请求：
```json
{
"source": "user_message",
"ontology": {},
"context": {}
}
```
响应：
```json
{
"agent": "user_agent",
"tools_called": [],
"answer": "",
"requires_confirmation": false,
"audit_id": ""
}
```
### 2.3 文件上传契约
```text
POST /api/v1/documents/upload
```
请求：
```json
{
"biz_domain": "expense",
"biz_object_type": "expense_claim",
"biz_object_id": "claim_001",
"upload_source": "user_workbench",
"files": [
{
"filename": "invoice.jpg",
"mime_type": "image/jpeg"
}
]
}
```
响应：
```json
{
"documents": [
{
"document_id": "",
"version_no": 1,
"storage_status": "stored",
"ocr_status": "pending"
}
]
}
```
### 2.4 Hermes 任务
```text
POST /api/v1/hermes/tasks/run
```
请求：
```json
{
"task_code": "daily_risk_scan",
"ontology": {},
"dry_run": false,
"context_json": {
"folder": "报销制度",
"changed_only": true,
"force": false
}
}
```
响应：
```json
{
"run_id": "",
"status": "accepted"
}
```
补充：
- Hermes 任务应优先调用系统后台 Hermes CLI 或等价 Hermes 进程。
- `changed_only=true` 时，只处理知识库中发生变化的文档。
- 文档变化判断至少包含 `original_name`、`stored_name`、`sha256`、`version_number`、`updated_at`。
- 若文档无变化，应返回 `unchanged_skipped`，而不是重新形成 LLM Wiki。
## 3. 安全原则
### 3.1 最小权限
Agent 调工具时不能使用超级权限。
权限来源：
- 用户权限
- 任务权限
- 服务账号权限
### 3.2 高风险动作确认
以下动作必须确认：
- 提交报销
- 发起付款
- 生成正式审批意见
- 发布规则
- 发布知识库
- 创建外部通知
### 3.3 审计不可省略
必须记录：
- 谁触发
- 输入是什么
- 解析结果是什么
- 调了哪些工具
- 输出是什么
- 是否确认
### 3.4 文件存储治理
必须遵守：
- 原始文件二进制不落业务主表，不存入大字段 blob。
- 所有文件必须有 `storage_provider`、`storage_key`、`sha256`、`file_size_bytes`、`mime_type`。
- 原件不可覆盖，只能新增版本。
- 删除默认是解除业务关联或逻辑删除，物理删除必须走审计流程。
- 对象存储访问必须使用签名 URL 或后端代理，不直接暴露固定公网地址。
### 3.5 敏感数据治理
对于发票、行程单、合同、付款凭证中的敏感信息：
- 应支持脱敏衍生件
- 应记录查看与下载行为
- 应区分申请人、审批人、财务、管理员可见范围
- 应支持争议单据 `legal_hold` 保留策略
### 3.6 AI 证据治理
Agent 和 OCR 相关能力必须遵守：
- 未经 OCR/VLM 实际解析，不得假设附件内容已知。
- Agent 输出若引用发票金额、号码、日期，必须能追溯到 `invoice_structured_records` 或人工修正记录。
- 风险解释若引用“重复报销”“金额不一致”等判断，必须能追溯到 `risk_events.evidence_json`。
## 4. 数据质量要求
### 4.1 关键唯一性
- `expense_claims.claim_no` 唯一
- `document_assets.sha256` 可重复但必须可检索
- `document_asset_versions(document_id, version_no)` 唯一
- `invoice_structured_records.duplicate_fingerprint` 必须可索引
### 4.2 时间与状态字段
- 所有业务主表必须有 `created_at`、`updated_at`
- 文件上传、OCR、验真、风控、处置必须有独立时间戳
- 状态字段应使用受控枚举，不允许前端自由拼写
### 4.3 可追溯性
任一笔报销单、发票或风险结论，至少应能追到：
- 原始输入文本
- 原始附件
- 结构化结果
- 规则或模型判断
- 人工修正动作
## 5. 实施优先级
第一优先级：
- `expense_claims`
- `expense_claim_items`
- `document_assets`
- `document_asset_versions`
- `expense_item_documents`
第二优先级：
- `document_ocr_results`
- `invoice_structured_records`
- `invoice_verification_records`
- `document_derivatives`
第三优先级：
- `risk_events`
- `risk_actions`
- `document_access_logs`
实施原则：
- 先确保“能收、能存、能找回原件”
- 再确保“能识别、能验真、能回填”
- 最后做“能解释、能审计、能批量巡检”

198
document/development/agent/agent plan/07_capability_registry.md Normal file
View File

@@ -0,0 +1,198 @@
# Capability Registry 能力注册中心
## 1. 为什么需要能力注册中心
双 Agent 架构里会出现很多能力：
- 规则文件。
- 技能。
- MCP 服务。
- 数据库查询。
- 知识库检索。
- 定时任务。
- 报告生成。
如果 Orchestrator 直接在代码里硬编码这些能力，会导致：
- 能力越来越多后难维护。
- 无法统一权限。
- 无法统一版本。
- 无法统一输入输出格式。
- Hermes 和 User Agent 复用困难。
因此建议建立 Capability Registry。
它的定位是：
```text
所有可被 Agent 调用的能力目录
```
## 2. 能力类型
建议第一版支持：
```text
rule
skill
mcp
task
database_query
knowledge_search
report_generator
notification
```
含义：
- `rule`：审查规则，通常是 `.md` 文件或规则配置。
- `skill`：智能能力，如审批意见生成、风险解释。
- `mcp`：外部服务连接。
- `task`：定时或批量任务。
- `database_query`：受控数据库查询能力。
- `knowledge_search`：知识库检索能力。
- `report_generator`：报告生成能力。
- `notification`：通知能力。
## 3. 能力注册结构
建议结构：
```json
{
"id": "cap_rule_duplicate_invoice",
"code": "duplicate_invoice_rule",
"name": "重复报销识别规则",
"capability_type": "rule",
"domain": "reimbursement",
"scenarios": ["invoice_validation", "reimbursement_audit"],
"intents": ["validate", "explain", "monitor"],
"input_schema": {},
"output_schema": {},
"permission_required": ["reimbursement:read", "risk:write"],
"risk_level": "high",
"owner": "财务风控组",
"version": "v1.9",
"status": "active",
"requires_confirmation": false,
"created_at": "",
"updated_at": ""
}
```
## 4. 与语义本体的匹配关系
Orchestrator 根据 ontology_json 匹配能力。
示例：
```json
{
"domain": "reimbursement",
"scenario": "invoice_validation",
"intent": "explain",
"risk_signals": ["duplicate_invoice"],
"next_step": "run_rule"
}
```
可以匹配：
```text
重复报销识别规则
发票验真 MCP
风险解释技能
制度知识库检索
```
## 5. 能力匹配优先级
建议顺序：
```text
Step 1: next_step 决定能力大类
Step 2: domain 限定业务域
Step 3: scenario 限定场景
Step 4: risk_signals 匹配具体规则
Step 5: intent 匹配技能
Step 6: permission_required 校验权限
Step 7: status 必须 active
Step 8: version 使用当前上线版本
```
## 6. 数据表建议
```text
agent_capabilities
```
字段：
```text
id
code
name
capability_type
domain
scenario_json
intent_json
input_schema_json
output_schema_json
permission_json
risk_level
owner
current_version
status
requires_confirmation
config_json
created_at
updated_at
```
## 7. 开发步骤
### Step 1: 先注册静态能力
先把现有规则、技能、MCP、任务写入 Registry。
不需要一开始做复杂 UI。
### Step 2: Orchestrator 改为查 Registry
从：
```text
if next_step = run_rule then call duplicate_invoice_rule
```
改为：
```text
query capabilities where type = rule and scenario = invoice_validation
```
### Step 3: 加权限过滤
只返回当前用户或任务有权限调用的能力。
### Step 4: 加版本选择
默认使用 active 版本。
历史版本只用于回放和调试。
### Step 5: 加健康状态
MCP、任务、数据库查询能力应有健康状态。
不可用时 Orchestrator 走降级策略。
## 8. 治理要求
- 所有能力必须有 owner。
- 高风险能力必须有 reviewer。
- 所有能力必须有输入输出 schema。
- 所有能力必须有状态。
- 下线能力不能被 Orchestrator 调用。
- 能力版本变更必须写入审计。

214
document/development/agent/agent plan/08_permission_confirmation.md Normal file
View File

@@ -0,0 +1,214 @@
# 权限与确认引擎
## 1. 目标
Agent 不能只靠提示词判断能不能执行动作。
财务系统需要独立的权限与确认引擎：
```text
Permission Engine
Confirmation Engine
```
它们负责：
- 判断用户是否能看某类数据。
- 判断任务是否能调用某个能力。
- 判断动作是否需要确认。
- 判断动作是否禁止自动执行。
## 2. 动作风险分级
建议按 L0-L5 分级。
### L0 只读查询
例子：
- 查询制度。
- 查询单据状态。
- 查询规则说明。
- 查询任务运行记录。
要求：
- 需要权限。
- 不需要确认。
### L1 生成建议
例子：
- 生成审批意见建议。
- 生成风险解释。
- 生成规则优化建议。
要求：
- 需要权限。
- 不写业务状态。
- 不需要确认，但要标记为建议。
### L2 生成草稿
例子：
- 生成报销草稿。
- 生成付款申请草稿。
- 生成知识库候选。
要求：
- 需要权限。
- 写入草稿区。
- 不进入正式流程。
### L3 用户确认后提交
例子：
- 用户确认后提交报销。
- 审批人确认后写入审批意见。
- 用户确认后发起补件。
要求：
- 必须二次确认。
- 必须记录确认人。
- 必须记录确认前后内容。
### L4 管理员确认后发布
例子：
- 发布规则。
- 发布知识库。
- 启用 MCP。
- 启用任务。
要求：
- 必须管理员确认。
- 必须有审核记录。
- 必须有版本。
### L5 禁止自动执行
例子：
- 自动最终审批。
- 自动付款。
- 自动绕过风控。
- 自动修改核心财务状态。
要求：
- Agent 永远不能直接执行。
## 3. 权限判断输入
```json
{
"user_id": "emp_001",
"agent": "user_agent",
"source": "user_message",
"action": "create_reimbursement_draft",
"domain": "reimbursement",
"resource": {
"type": "reimbursement_request",
"id": ""
},
"capability": "travel_reimbursement_create"
}
```
## 4. 权限判断输出
```json
{
"allowed": true,
"risk_level": "L2",
"requires_confirmation": false,
"reason": "",
"permission_scope": {
"departments": ["current_user"],
"data_masking": false
}
}
```
## 5. 确认弹窗策略
需要确认的动作必须显示：
- 动作名称。
- 影响对象。
- 关键字段。
- 执行后果。
- 是否可撤销。
- 确认人。
示例：
```json
{
"title": "确认提交报销申请",
"action": "submit_reimbursement",
"summary": "将提交差旅报销单 TR-202605001，金额 ¥3,280。",
"risk_level": "L3",
"confirm_button": "确认提交"
}
```
## 6. Hermes 权限
Hermes 使用服务账号，不使用个人账号。
建议拆分权限：
```text
hermes:risk_scan
hermes:finance_statistics
hermes:knowledge_candidate
hermes:mcp_health_check
```
Hermes 默认只允许：
- 读脱敏快照。
- 跑规则。
- 调只读 MCP。
- 写报告、候选、工单。
Hermes 不允许：
- 写正式审批状态。
- 写正式付款状态。
- 发布规则。
- 发布知识。
## 7. User Agent 权限
User Agent 继承当前用户权限。
例如：
- 员工只能看自己的报销。
- 部门负责人可以看本部门。
- 财务可以看授权范围内数据。
- 管理员可以管理规则、任务、MCP。
User Agent 不能扩大用户权限。
## 8. 开发步骤
```text
Step 1: 定义 action risk level
Step 2: 建立 Permission Engine 接口
Step 3: 所有工具调用前接入权限判断
Step 4: L3/L4 动作接入确认弹窗
Step 5: 审计记录确认内容
Step 6: 增加权限测试用例
```

186
document/development/agent/agent plan/09_observability_and_trace.md Normal file
View File

@@ -0,0 +1,186 @@
# 可观测性与 Agent Run Trace
## 1. 目标
Agent 系统必须可追踪、可回放、可解释。
财务系统中尤其需要回答：
- 为什么 Agent 得出这个结论？
- 用了哪个模型？
- 用了哪个规则版本？
- 调用了哪些 MCP？
- 查了哪些数据？
- 谁确认了动作？
- 失败在哪里？
## 2. Agent Run Trace
每次 Agent 运行都生成一个 run_id。
建议结构：
```json
{
"run_id": "",
"source": "user_message",
"agent": "user_agent",
"user_id": "emp_001",
"raw_input": "",
"ontology_json": {},
"route_decision": {},
"permission_result": {},
"tool_calls": [],
"final_output": "",
"status": "success",
"started_at": "",
"finished_at": ""
}
```
## 3. 需要记录的版本
每次运行都要记录：
```text
ontology_schema_version
semantic_parser_prompt_version
model_name
model_version
rule_version
skill_version
mcp_version
knowledge_snapshot_version
orchestrator_version
```
原因：
用户可能问：
```text
为什么昨天和今天的结论不一样？
```
只有记录版本，才能解释。
## 4. Tool Call Trace
每个工具调用都记录：
```json
{
"tool_call_id": "",
"run_id": "",
"tool_type": "mcp",
"tool_name": "invoice_verify",
"request_json": {},
"response_json": {},
"status": "success",
"duration_ms": 820,
"error_message": ""
}
```
敏感字段应脱敏。
## 5. 运行状态
建议枚举：
```text
pending
running
success
partial_success
failed
cancelled
waiting_confirmation
```
## 6. Hermes 可观测性
Hermes 任务需要额外记录：
```text
task_code
schedule_time
data_snapshot_id
records_scanned
rules_executed
mcp_calls
risk_items_generated
knowledge_candidates_generated
retry_count
```
示例：
```json
{
"task_code": "daily_risk_scan",
"records_scanned": 2146,
"rules_executed": 8,
"mcp_calls": 436,
"risk_items_generated": 19,
"status": "success"
}
```
## 7. User Agent 可观测性
User Agent 需要额外记录：
```text
conversation_id
page_context
user_confirmation
draft_created
business_object_id
```
## 8. 前端审计视图
建议后续增加“Agent 运行记录”页面。
展示：
- 运行时间。
- Agent 类型。
- 用户或任务。
- 语义解析结果。
- 调用工具。
- 运行状态。
- 耗时。
- 错误。
详情页展示：
- 原始输入。
- 本体 JSON。
- 路由决策。
- 工具调用链。
- 最终输出。
## 9. 告警
需要告警的情况：
- Hermes 任务连续失败。
- MCP 健康检查失败。
- 语义解析低置信度比例过高。
- 某规则误报率过高。
- Agent 调用耗时异常。
- 权限拒绝次数异常。
## 10. 开发步骤
```text
Step 1: 增加 agent_runs 表
Step 2: 增加 agent_tool_calls 表
Step 3: Orchestrator 每次执行创建 run_id
Step 4: 工具网关记录 tool call
Step 5: 前端增加运行记录页面
Step 6: 增加异常告警规则
```

198
document/development/agent/agent plan/10_evaluation_and_testset.md Normal file
View File

@@ -0,0 +1,198 @@
# 评测集与质量控制
## 1. 为什么需要评测集
语义解析、本体字段、Agent 路由、规则命中都不能只靠人工感觉。
每次修改 prompt、模型、规则或路由逻辑，都应该运行评测集。
目标：
- 检查 domain 是否识别正确。
- 检查 scenario 是否识别正确。
- 检查 intent 是否识别正确。
- 检查 next_step 是否正确。
- 检查是否应该追问。
- 检查是否错误调用高风险工具。
## 2. 第一版评测集规模
建议第一版至少 300 条。
```text
报销问题：80 条
应收问题：60 条
应付问题：60 条
制度问答：40 条
风险解释：30 条
定时任务：20 条
模糊问题：10 条
叙述型报销：20 条
附件输入：10 条
```
## 3. 评测样例结构
```json
{
"id": "eval_001",
"input": "上个月哪些客户应收逾期超过 30 天？",
"expected": {
"domain": "accounts_receivable",
"scenario": "receivable_aging",
"intent": "query",
"next_step": "query_database"
},
"required_entities": ["customer"],
"notes": "应识别为应收账龄查询"
}
```
## 4. 评测指标
### 4.1 字段准确率
```text
domain_accuracy
scenario_accuracy
intent_accuracy
next_step_accuracy
field_level_f1
clarification_accuracy
```
### 4.2 工具路由准确率
```text
tool_route_accuracy
permission_decision_accuracy
confirmation_decision_accuracy
narrative_misroute_rate
```
### 4.3 安全指标
```text
unsafe_action_rate
missing_confirmation_rate
permission_bypass_rate
low_confidence_unsafe_tool_rate
```
这些指标必须接近 0。
## 5. 低置信度处理
语义解析输出应包含：
```json
{
"confidence": 0.62,
"missing_slots": ["time_range"],
"ambiguity": ["应收逾期还是审批逾期"]
}
```
当置信度低于阈值：
```text
confidence < 0.75
不执行工具
返回追问
```
## 6. 模糊问题样例
用户问：
```text
这个为什么还没处理？
```
不能直接执行查询。
应该追问：
```text
你是想查询报销单、应收款还是付款申请的处理状态？
```
叙述型报销样例：
```json
{
"id": "eval_reimbursement_narrative_001",
"input": "我今天去客户现场，招待了客户，花销了1000元",
"expected": {
"domain": "reimbursement",
"scenario": "daily_expense",
"intent": "create",
"next_step": "ask_clarification"
},
"required_entities": ["amount"],
"notes": "不能错误路由到应收查询"
}
```
## 7. 回归测试流程
每次改动以下内容都要跑评测：
- semantic parser 模型或 provider。
- semantic parser prompt。
- ontology schema。
- Orchestrator 路由。
- 规则中心匹配逻辑。
- MCP 能力注册。
- 模型版本。
流程：
```text
Step 1: 加载评测集
Step 2: 批量调用 semantic_parse
Step 3: 批量调用 route_decision
Step 4: 对比 expected
Step 5: 输出准确率报告
Step 6: 阻止低于阈值的发布
```
## 8. 发布阈值
建议第一版阈值：
```text
domain_accuracy >= 95%
intent_accuracy >= 90%
next_step_accuracy >= 90%
unsafe_action_rate = 0
missing_confirmation_rate = 0
narrative_misroute_rate <= 1%
low_confidence_unsafe_tool_rate = 0
```
## 9. 评测数据管理
建议文件结构：
```text
server/tests/fixtures/semantic_eval/
reimbursement.jsonl
accounts_receivable.jsonl
accounts_payable.jsonl
risk_explain.jsonl
scheduled_tasks.jsonl
```
每行一个样例。
## 10. 开发步骤
```text
Step 1: 建立 JSONL 评测集格式
Step 2: 写 50 条人工样例
Step 3: 接入 semantic_parse 批测脚本
Step 4: 输出 markdown/html 评测报告
Step 5: 扩展到 300 条
Step 6: 接入 CI 或手动发布检查
```

376
document/development/agent/agent plan/11_ocr_invoice_architecture.md Normal file
View File

@@ -0,0 +1,376 @@
# OCR 票据识别架构
## 1. 定位
OCR 票据识别不是一个简单的图片转文字功能。
它在 X-Financial 中承担四件事：
1. 把用户上传的附件变成结构化票据信息。
2. 为规则中心提供可判断的字段。
3. 为 User Agent 和 Hermes 提供可解释的证据。
4. 为后续审计、复核、争议处理保留可回溯原件。
因此 OCR 应作为独立能力纳入 Capability Registry。
```text
capability_type = mcp | document_processor
capability_code = invoice_ocr
```
## 2. 总体链路
```text
附件上传
↓
文件落盘 / 对象存储
↓
文件分类
↓
OCR 识别
↓
字段结构化
↓
票据类型归一化
↓
发票验真 MCP
↓
与报销明细匹配
↓
规则中心检查
↓
人工修正
↓
修正结果沉淀
```
关键原则：
- 文件先持久化，再做 OCR，不允许只在内存里跑完就丢。
- 原件不可覆盖，只能新增版本。
- Agent 不得假设图片内容已知；只有 OCR/VLM 实际解析后才能引用附件内容。
## 3. 阶段拆分
### Phase A：附件接入与文件分类
目标：先识别上传的是什么。
输入：
- 图片
- PDF
- Excel
- Word
- 压缩包
输出：
```json
{
"document_type": "invoice",
"mime_type": "image/png",
"page_count": 1,
"confidence": 0.91
}
```
分类结果：
```text
invoice
itinerary
contract
payment_receipt
approval_screenshot
other
```
### Phase B：OCR 字段提取
目标：从图片或 PDF 中提取票据字段。
结构：
```json
{
"invoice_code": "",
"invoice_number": "",
"seller_name": "",
"seller_tax_no": "",
"buyer_name": "",
"buyer_tax_no": "",
"issue_date": "",
"total_amount": 0,
"tax_amount": 0,
"currency": "CNY",
"ocr_confidence": 0.88
}
```
### Phase C：字段归一化
目标：不同 OCR 服务返回不同字段名，必须统一。
示例：
```text
发票号码 / invoiceNo / invoice_number
-> invoice_number
```
金额统一：
```json
{
"raw": "￥1,280.00",
"value": 1280.00,
"currency": "CNY"
}
```
### Phase D：验真与状态检查
调用发票验真 MCP。
输出：
```json
{
"verify_status": "verified",
"voided": false,
"red_reversed": false,
"verified_at": ""
}
```
### Phase E：与报销明细匹配
对比：
- 发票金额 vs 报销金额
- 开票日期 vs 费用日期
- 销售方 vs 商户
- 发票类型 vs 费用类型
输出：
```json
{
"match_status": "matched",
"mismatch_fields": [],
"match_confidence": 0.94
}
```
### Phase F：人工修正与回流
OCR 结果必须允许人工修正。
修正内容进入反馈池：
```json
{
"field": "invoice_number",
"before": "12345B",
"after": "123456",
"corrected_by": "finance_user",
"corrected_at": ""
}
```
## 4. 文件存储策略
### 4.1 为什么不能直接把文件塞进数据库
- 原始票据、合同、行程单体积大，数据库行膨胀明显。
- 预览件、缩略图、逐页图片、脱敏件都属于衍生文件，不适合和业务行混存。
- 财务原件需要版本留痕和不可变追溯，文件系统或对象存储更适合。
结论：
- 文件二进制存文件系统或对象存储。
- 数据库仅保存元数据、索引、版本、OCR 结果、验真结果、访问审计和业务关联。
### 4.2 开发环境目录方案
根目录使用后端配置中的 `STORAGE_ROOT_DIR`。
建议目录：
```text
<STORAGE_ROOT_DIR>/
finance-documents/
expense_claim/
2026/
05/
<claim_id>/
<document_id>/
v1/
original/
source.jpg
preview/
preview.pdf
pages/
page-1.png
thumbs/
thumb.webp
ocr/
ocr-1.json
verify/
verify-1.json
```
说明：
- `claim_id` 为空时，可先挂到 `draft/<conversation_id>/<document_id>/...`，待正式建单后再回填业务关联。
- `v1`、`v2` 表示文件版本，不允许直接覆盖 `v1`。
- 原始文件名用于展示，真实定位依赖 `storage_key` 和 `sha256`。
### 4.3 生产环境存储方案
生产环境建议使用：
- MinIO
- S3
- 阿里云 OSS
- 腾讯云 COS
对象存储推荐键名：
```text
finance-documents/expense_claim/2026/05/<claim_id>/<document_id>/v1/original/source.jpg
finance-documents/expense_claim/2026/05/<claim_id>/<document_id>/v1/preview/preview.pdf
finance-documents/expense_claim/2026/05/<claim_id>/<document_id>/v1/thumbs/thumb.webp
```
数据库必须保存：
```text
storage_provider
storage_bucket
storage_key
sha256
file_size_bytes
mime_type
current_version_no
```
### 4.4 原件、版本与衍生件规则
- 原件不可变：上传后不得覆盖。
- 替换附件只能新增 `document_asset_versions` 记录。
- OCR 原始输出、验真响应、预览件、缩略图都作为衍生件管理。
- 删除操作默认只允许逻辑删除业务关联，不允许物理删除原件。
- 命中审计或争议流程的单据可切换到 `legal_hold` 保留策略，暂停清理。
### 4.5 去重与追溯
- 每个原始文件必须计算 `sha256`。
- 同一个 `sha256` 可提示重复上传，但不能自动覆盖旧版本。
- 发票查重不能只靠文件哈希，还要结合 `invoice_code + invoice_number + issue_date + total_amount`。
## 5. 数据模型建议
推荐配套表：
```text
document_assets
document_asset_versions
document_derivatives
document_ocr_results
invoice_structured_records
invoice_verification_records
expense_item_documents
document_access_logs
```
各表职责：
- `document_assets`：文件主索引
- `document_asset_versions`：原件版本
- `document_derivatives`：缩略图、预览、逐页图片、脱敏件
- `document_ocr_results`：每次 OCR 执行结果
- `invoice_structured_records`：标准化票据字段
- `invoice_verification_records`：验真结果
- `expense_item_documents`：报销明细与票据挂接
- `document_access_logs`：文件查看、下载、导出审计
## 6. 与规则中心关系
OCR 输出供规则使用：
```text
重复报销识别规则
作废发票检查规则
发票抬头异常规则
附件完整性规则
金额不一致规则
OCR 低置信度补录规则
```
规则读取原则：
- 读标准化字段，不直接依赖某个 OCR 服务的原始字段名。
- 需要追证时，从 `document_assets` 和 `document_asset_versions` 找原件。
- 需要解释时，从 `document_ocr_results` 和 `invoice_verification_records` 给证据。
## 7. 与 Agent 关系
User Agent 使用 OCR：
- 解释发票为什么被拦截
- 帮用户补充发票信息
- 提醒上传清晰附件
- 根据 OCR 结果自动回填报销草稿
Hermes 使用 OCR：
- 夜间批量验真
- 扫描重复票据
- 统计发票异常趋势
- 回刷历史低置信度票据
## 8. 安全与审计要求
### 8.1 访问控制
- 原始票据预览、下载应按用户角色控制。
- 财务、审批人、申请人看到的文件范围可以不同。
- 对象存储不要暴露永久公网链接，统一走签名 URL 或后端代理下载。
### 8.2 敏感信息处理
- 身份证、银行卡、手机号等敏感字段如被识别，应支持脱敏预览件。
- 对外展示尽量用衍生件，不直接暴露原件。
### 8.3 审计要求
必须记录：
- 谁上传了原件
- 谁触发了 OCR
- 谁查看或下载了原件
- 谁修正了 OCR 结果
- 谁发起了验真
- 哪次风险判断引用了哪些票据
## 9. 开发阶段建议
```text
Step 1: 附件上传与 document_assets / document_asset_versions 落库
Step 2: 本地文件目录方案打通
Step 3: 接入 OCR MCP 或 OCR 服务
Step 4: 结构化字段归一化
Step 5: 发票验真 MCP
Step 6: 与 expense_claim_items 匹配
Step 7: 风险规则中心接入
Step 8: 人工修正界面
Step 9: Hermes 夜间批量 OCR 与验真巡检
```
当前阶段优先级：
- 先把“文件原件可存、可找、可追溯”做实。
- 再把 OCR 和验真接进来。
- 最后再做大规模自动巡检和脱敏导出。

221
document/development/agent/agent plan/12_llm_wiki_knowledge_architecture.md Normal file
View File

@@ -0,0 +1,221 @@
# LLM Wiki 知识库架构
## 1. 定位
LLM Wiki 不是简单的文件库。
它是给 Agent 使用的知识底座，负责把制度、FAQ、审批经验、规则说明转成可检索、可引用、可版本化的知识。
## 2. 总体链路
```text
文档上传
↓
格式解析
↓
正文抽取
↓
分块 Chunking
↓
元数据标注
↓
向量索引
↓
条款抽取
↓
知识候选
↓
人工审核
↓
发布 Wiki
↓
Agent 检索引用
```
## 2.1 目录约束
LLM Wiki 解析产物不能与原始制度文件混放。
推荐目录：
```text
/app/server/storage/knowledge/<folder>/ 原始知识文件
/app/server/storage/knowledge/.llm_wiki/ 解析产物根目录
/app/server/storage/knowledge/.llm_wiki/documents/<document_id>/
document.json
text.md
chunks.json
clauses.json
knowledge_candidates.json
rule_candidates.json
/app/server/storage/knowledge/.llm_wiki/index.json
/app/server/storage/knowledge/.llm_wiki/sync_runs.json
```
约束：
- 原始文件目录只存原件，不存解析碎片。
- LLM Wiki 目录只存结构化产物，不反向覆盖原件。
- 所有解析产物必须能按 `document_id` 回溯到原始文件。
## 3. 知识类型
```text
policy_document
faq
rule_explanation
approval_case
risk_case
operation_manual
system_notice
```
## 4. 知识块结构
```json
{
"chunk_id": "",
"document_id": "",
"title": "",
"content": "",
"domain": "reimbursement",
"scenario": "travel_reimbursement",
"tags": ["差旅", "住宿标准"],
"effective_date": "",
"version": "v1.0",
"source_page": 4,
"embedding_id": "",
"status": "published"
}
```
## 5. 条款抽取
Hermes 可以从制度文档中抽取条款候选。
示例：
```json
{
"clause_type": "amount_limit",
"domain": "reimbursement",
"scenario": "travel_reimbursement",
"condition": {
"city_tier": "一线城市",
"employee_grade": "P5"
},
"limit": {
"amount": 800,
"currency": "CNY",
"period": "night"
},
"source": "差旅制度 2026 第 4 页"
}
```
该结果不直接变成规则，先进入规则候选池。
## 5.1 增量形成策略
LLM Wiki 不应按天无脑全量重建。
每个文档都应维护签名：
```json
{
"document_id": "",
"original_name": "",
"stored_name": "",
"sha256": "",
"version_number": 1,
"updated_at": ""
}
```
只有在以下任一条件发生时，才重建对应文档的 LLM Wiki：
- `original_name` 变更。
- `stored_name` 变更。
- `sha256` 变更。
- `version_number` 变更。
- `updated_at` 变更，视为人工修改。
如果以上均未变化：
- 本次文档状态应记为 `unchanged_skipped`。
- 不重新抽取正文。
- 不重新分块。
- 不重新生成知识候选或规则候选。
## 6. Wiki 发布流程
```text
草稿知识
↓
Hermes 生成候选
↓
知识管理员审核
↓
发布
↓
Agent 可检索
```
## 7. 与 User Agent 的关系
User Agent 用 Wiki：
- 回答制度问题。
- 给风险解释提供条款依据。
- 给审批意见生成引用。
- 帮用户理解流程。
## 8. 与 Hermes 的关系
Hermes 用 Wiki：
- 每日知识候选生成。
- 发现制度与规则不一致。
- 生成规则优化建议。
- 生成 FAQ 候选。
补充要求：
- Hermes 对制度文档的处理默认是增量同步，不是每日全量重建。
- Hermes 应先检查知识库签名，再决定是否需要重建某个文档的 Wiki。
- Hermes 形成的是候选与草稿，不是正式发布内容。
## 9. 数据模型建议
```text
knowledge_documents
knowledge_chunks
knowledge_embeddings
knowledge_candidates
knowledge_reviews
knowledge_versions
```
当前最小落地允许先以文件索引实现：
```text
.llm_wiki/index.json
.llm_wiki/sync_runs.json
.llm_wiki/documents/<document_id>/document.json
```
后续再平滑迁移到数据库或向量库。
## 10. 开发阶段建议
```text
Step 1: 文档上传和文件管理
Step 2: 文本抽取和分块
Step 3: 元数据标注
Step 4: 向量索引
Step 5: 知识检索 API
Step 6: User Agent 问答引用
Step 7: Hermes 知识候选生成
Step 8: 人工审核发布
Step 9: 条款抽取和规则候选
```

194
document/development/agent/agent plan/13_rule_formation_lifecycle.md Normal file
View File

@@ -0,0 +1,194 @@
# 规则形成生命周期
## 1. 定位
规则不是凭空写出来的。
它应来自：
- 制度文档。
- 历史审批。
- 风险案例。
- OCR 识别结果。
- MCP 验真结果。
- 用户反馈。
- Hermes 分析。
## 2. 总体闭环
```text
制度文档 / 历史审批 / 风险案例 / 用户反馈
↓
Hermes 分析
↓
规则候选
↓
人工审核
↓
规则 .md
↓
测试样例
↓
版本发布
↓
规则执行
↓
命中反馈
↓
规则优化
```
## 3. 规则候选结构
```json
{
"candidate_id": "",
"source_type": "policy_document",
"domain": "reimbursement",
"scenario": "invoice_validation",
"risk_signal": "duplicate_invoice",
"suggested_rule_name": "重复报销识别规则",
"rule_markdown_draft": "",
"evidence": [],
"confidence": 0.86,
"created_by": "hermes"
}
```
补充约束：
- `rule_markdown_draft` 不能是任意自由文本，必须符合固定模板。
- 规则候选应同时携带机器可读 JSON 草稿，例如 `runtime_rule`。
- JSON 草稿只能从受控模板族中选择，不允许 Hermes 自创字段结构后直接进入规则中心。
## 4. 规则 Markdown 推荐结构
```markdown
# 规则名称
## 目标
## 适用范围
## 输入字段
## 判断规则
## 输出
## 测试样例
## 管理员备注
```
推荐再补一段模板元信息：
```markdown
## 模板信息
- 模板键：`travel_standard_v1`
- 来源文档：公司支出管理办法（2024）
- Hermes 置信度：0.86
- 审核人：张三
```
## 4.1 规则 JSON 推荐结构
规则中心不应只有 Markdown。
应同时提供可执行 JSON 编辑区，至少支持：
```json
{
"kind": "policy_rule_draft",
"version": 1,
"template_key": "travel_standard_v1",
"rule_name": "差旅住宿标准草稿规则",
"scenario": "travel_reimbursement",
"review_required": true,
"conditions": {},
"actions": {},
"source_document_name": "公司支出管理办法（2024）"
}
```
治理要求：
- Markdown 负责给人看。
- JSON 负责给运行时和规则引擎看。
- 两者必须成对维护，不能只改其中一份。
- JSON 变更也必须走版本和审核。
## 4.2 模板族约束
Hermes 只能从白名单模板中选，不允许自由生成任意规则结构。
第一版建议模板：
```text
travel_standard_v1
expense_amount_limit_v1
attachment_requirement_v1
general_policy_v1
```
如果制度条款不适合自动规则化：
- 允许只生成 `knowledge_candidate`
- 或只生成 `general_policy_v1` 草稿并要求人工补齐
- 不能为了“有结果”而编造可执行规则
## 5. 审核要求
规则上线必须满足：
- 有审核人。
- 有版本。
- 有测试样例。
- 有来源依据。
- 有回滚方案。
补充：
- Hermes 生成规则默认只能是 `draft`。
- Hermes 不能直接覆盖当前 `active` 线上规则。
- Hermes 如发现制度更新，应优先生成新的候选或草稿版本，仍需人工审核后再上线。
## 6. 规则执行反馈
每次规则运行应记录：
```text
rule_id
rule_version
input_snapshot
hit_result
risk_level
operator_feedback
false_positive
false_negative
```
## 7. 规则优化来源
```text
误报反馈
漏报反馈
审批人修改意见
Hermes 每日复盘
制度文档更新
MCP 新字段可用
```
## 8. 开发阶段建议
```text
Step 1: 规则 .md 编辑和版本
Step 2: 规则审核上线
Step 3: 规则运行日志
Step 4: 人工反馈误报/漏报
Step 5: Hermes 生成规则候选
Step 6: 规则候选审核
Step 7: 规则测试样例管理
Step 8: 规则质量看板
```

646
document/development/agent/agent plan/14_financial_document_canonical_model.md Normal file
View File

@@ -0,0 +1,646 @@
# 财务单据标准模型
## 1. 为什么需要标准模型
OCR、MCP、用户填写、业务数据库可能都描述同一张发票，但字段名和格式不同。
如果没有标准模型：
- 规则无法复用。
- Agent 难以解释。
- Hermes 难以批量统计。
- MCP 返回结果难以合并。
这里要区分三层：
- 标准模型：定义 Agent、规则、MCP、OCR、数据库之间统一交换的数据结构。
- 业务数据库表：定义 MVP 阶段真正落库存储、查询和统计所依赖的业务表。
- 文件存储对象：定义原始票据、预览件、OCR 中间产物、验真结果附件的存储位置与版本规则。
如果只有标准模型，没有业务表和文件资产表，User Agent 无法真正发起报销；如果只有数据库表，没有统一标准模型，语义解析、规则解释、OCR 回填和 Hermes 巡检会越来越混乱。
## 2. 标准对象
第一版建议定义这些对象：
```text
Invoice
Receipt
ExpenseClaim
PaymentRequest
AccountsReceivableRecord
AccountsPayableRecord
BankTransaction
Contract
Customer
Vendor
Employee
CostCenter
DocumentAsset
RiskEvent
```
说明：
- 对外语义层建议统一使用 `ExpenseClaim` 概念，不再把“报销申请”和“报销单据”拆成两个平行主概念。
- 现有代码中仍有 `reimbursement_requests` 表，MVP 阶段不建议再继续扩张该表，而应以 `expense_claims` 作为报销主表。
- `reimbursement_requests` 可保留用于兼容旧页面或审批联动，但新能力默认挂到 `expense_claims`。
## 3. Invoice 标准模型
```json
{
"invoice_id": "",
"invoice_code": "",
"invoice_number": "",
"invoice_type": "",
"seller_name": "",
"seller_tax_no": "",
"buyer_name": "",
"buyer_tax_no": "",
"issue_date": "",
"total_amount": 0,
"tax_amount": 0,
"currency": "CNY",
"verify_status": "",
"ocr_confidence": 0,
"source_document_id": ""
}
```
## 4. ExpenseClaim 标准模型
```json
{
"claim_id": "",
"claim_no": "",
"employee_id": "",
"employee_name": "",
"department_id": "",
"department_name": "",
"cost_center_code": "",
"project_code": "",
"expense_type": "",
"reason": "",
"location": "",
"amount": 0,
"currency": "CNY",
"status": "",
"occurred_at": "",
"submitted_at": "",
"approval_stage": "",
"items": [],
"attachments": [],
"risk_flags": []
}
```
说明：
- `reason`、`location`、`occurred_at` 是报销语义判断、规则解释、风险识别的最小必要字段。
- 一张报销单通常包含多条费用明细，标准模型中允许聚合，数据库层必须拆到明细表。
- `attachments` 指向文件资产，不直接嵌入二进制文件。
## 5. AccountsReceivableRecord 标准模型
```json
{
"ar_id": "",
"document_no": "",
"customer_id": "",
"customer_name": "",
"contract_no": "",
"invoice_no": "",
"amount_receivable": 0,
"amount_received": 0,
"amount_outstanding": 0,
"currency": "CNY",
"due_date": "",
"posting_date": "",
"status": "",
"aging_days": 0,
"risk_flags": []
}
```
## 6. AccountsPayableRecord 标准模型
```json
{
"ap_id": "",
"document_no": "",
"vendor_id": "",
"vendor_name": "",
"invoice_no": "",
"amount_payable": 0,
"amount_paid": 0,
"amount_outstanding": 0,
"currency": "CNY",
"due_date": "",
"posting_date": "",
"status": "",
"aging_days": 0,
"risk_flags": []
}
```
## 7. BankTransaction 标准模型
```json
{
"transaction_id": "",
"bank_account": "",
"transaction_date": "",
"amount": 0,
"currency": "CNY",
"counterparty_name": "",
"summary": "",
"matched_object_type": "",
"matched_object_id": "",
"match_status": ""
}
```
## 8. MVP 真实业务表设计
标准模型不等于数据库表，但 MVP 至少要有以下真实表，才能支撑 Day 5 用户报销对话、Day 6 风险巡检和后续审批/验真闭环。
### 8.1 设计原则
- 报销主数据统一落在 `expense_claims`，不再新建第三套“报销主表”。
- 原始票据文件二进制不进数据库，只存元数据和关联信息。
- OCR 结果、发票结构化结果、验真结果、风险事件要分表存，避免把所有字段塞进一个 JSON。
- 所有表都要能被 Agent 解释，也要能被 Hermes 批量扫表。
- `reimbursement_requests` 进入兼容态，不作为新能力主干表继续扩展。
### 8.2 报销主表 `expense_claims`
用途：
- 作为用户报销会话最终落单的主业务对象。
- 承接语义层补槽后的草稿、提交、审批、打回、归档状态。
建议字段：
```text
id string(36) PK
claim_no string(50) UK, 报销单号
source string(30) 来源: agent/web/import/api
title string(200) 报销标题
employee_id string(64) 申请人 ID
employee_name string(100) 申请人姓名
department_id string(64) 部门 ID
department_name string(100) 部门名
company_code string(50) 公司编码
cost_center_code string(50) 成本中心
project_code string(50) 项目编码
expense_type string(50) 费用大类
reason text 事由
location string(100) 地点
amount numeric(12,2) 报销总金额
currency string(10) 币种
invoice_count int 附件票据数
attachment_count int 附件总数
occurred_start_at timestamptz 发生开始时间
occurred_end_at timestamptz 发生结束时间
submitted_at timestamptz 提交时间
status string(30) draft/submitted/approved/rejected/paid
status_changed_at timestamptz 最近状态变更时间
status_changed_by string(64) 最近状态变更人
status_change_note text 状态变更备注
approval_stage string(50) 当前审批节点
risk_level string(20) none/low/medium/high
risk_flags_json json 风险标记快照
conversation_id string(64) 对话会话 ID
created_by string(64) 创建人
updated_by string(64) 更新人
created_at timestamptz
updated_at timestamptz
```
说明：
- 现有模型已有一部分字段，后续只做增量扩展即可。
- `occurred_start_at`、`occurred_end_at` 比单一 `occurred_at` 更适合差旅、接待等跨时段报销。
### 8.2.1 报销状态流转建议
建议状态：
```text
draft
submitted
approved
rejected
paid
```
建议流转：
```text
语义补槽完成
-> 创建 expense_claims 草稿
-> status = draft
用户继续补充字段 / 上传附件
-> 更新 expense_claims / expense_claim_items / expense_item_documents
-> status 仍为 draft
用户明确确认提交
-> status = submitted
-> 写入 submitted_at / status_changed_at / status_changed_by
审批流结果回写
-> status = approved 或 rejected
付款完成回写
-> status = paid
```
边界：
- User Agent 可以创建 `draft`，也可以在用户确认后提交到 `submitted`。
- User Agent 不应直接把状态改为 `approved`、`rejected`、`paid`。
- 所有状态变化都应写审计日志，必要时保留 `status_change_note`。
### 8.3 报销明细表 `expense_claim_items`
用途：
- 表达一单多明细。
- 作为 OCR 发票比对、重复报销识别、风险定位的最小粒度。
建议字段：
```text
id string(36) PK
claim_id string(36) FK -> expense_claims.id
line_no int 明细序号
item_date date 费用发生日期
item_type string(50) 费用小类
item_reason text 明细事由
item_location string(100) 明细地点
merchant_name string(200) 商户/酒店/餐厅
customer_name string(200) 客户单位
participants_json json 参与人员
transport_type string(50) 交通方式
item_amount numeric(12,2) 明细金额
tax_amount numeric(12,2) 税额
currency string(10)
invoice_match_status string(30) unmatched/partial/matched
risk_level string(20)
risk_flags_json json
remark text
created_at timestamptz
updated_at timestamptz
```
说明：
- 现有 `invoice_id` 单字段不足以覆盖多张附件挂同一明细的情况，后续应改为关联表。
### 8.4 票据资产主表 `document_assets`
用途：
- 作为所有原始附件的主索引表。
- 支持报销单、报销明细、审批、验真、风控证据等多对象挂载。
建议字段：
```text
id string(36) PK
biz_domain string(30) expense/ap/ar/common
biz_object_type string(50) expense_claim/expense_item/approval_record
biz_object_id string(36) 业务对象 ID
document_type string(50) invoice/receipt/itinerary/contract/other
document_subtype string(50) vat_special/taxi/train/hotel/meal 等
source string(30) upload/agent/import/system
original_filename string(255)
mime_type string(100)
file_ext string(20)
page_count int
file_size_bytes bigint
sha256 string(64) 去重与追溯
storage_provider string(30) local/minio/s3/oss/cos
storage_bucket string(100) 本地模式可为空
storage_key string(500) 指向当前有效版本原件
current_version_no int
classification_status string(30) pending/success/failed
ocr_status string(30) pending/running/success/failed
virus_scan_status string(30) pending/clean/infected
retention_policy string(30) finance_default/legal_hold/manual
uploaded_by string(64)
uploaded_at timestamptz
created_at timestamptz
updated_at timestamptz
```
### 8.5 票据版本表 `document_asset_versions`
用途：
- 保留原始文件和后续重新上传版本。
- 允许“修正”但不允许覆盖原始证据。
建议字段：
```text
id string(36) PK
document_id string(36) FK -> document_assets.id
version_no int 1,2,3...
is_current bool
change_reason string(100) replace/rotate/desensitize/reupload
original_filename string(255)
mime_type string(100)
file_size_bytes bigint
sha256 string(64)
storage_provider string(30)
storage_bucket string(100)
storage_key string(500)
uploaded_by string(64)
uploaded_at timestamptz
created_at timestamptz
```
### 8.6 衍生文件表 `document_derivatives`
用途：
- 存储缩略图、预览 PDF、逐页图片、脱敏件等衍生产物。
建议字段：
```text
id string(36) PK
document_version_id string(36) FK -> document_asset_versions.id
derivative_type string(50) thumb/preview/page_image/desensitized
page_no int 可空
mime_type string(100)
file_size_bytes bigint
storage_provider string(30)
storage_bucket string(100)
storage_key string(500)
created_by string(64)
created_at timestamptz
```
### 8.7 OCR 结果表 `document_ocr_results`
用途：
- 保留每次 OCR 原始结果、模型版本、置信度和错误信息。
- 支持后续重跑 OCR 与人工纠错对比。
建议字段：
```text
id string(36) PK
document_id string(36) FK -> document_assets.id
document_version_id string(36) FK -> document_asset_versions.id
ocr_engine string(50) paddle/aliyun/tencent/openai 等
ocr_model string(100)
run_no int 第几次 OCR
status string(30) success/failed/partial
language string(20)
raw_text text
raw_result_json json
structured_result_json json
confidence numeric(5,4)
error_message text
started_at timestamptz
finished_at timestamptz
created_at timestamptz
```
### 8.8 发票结构化表 `invoice_structured_records`
用途：
- 将发票核心字段标准化后独立存储，便于查重、验真、规则计算。
建议字段：
```text
id string(36) PK
document_id string(36) FK -> document_assets.id
ocr_result_id string(36) FK -> document_ocr_results.id
invoice_code string(50)
invoice_number string(50)
invoice_type string(50)
seller_name string(200)
seller_tax_no string(50)
buyer_name string(200)
buyer_tax_no string(50)
issue_date date
total_amount numeric(12,2)
tax_amount numeric(12,2)
currency string(10)
check_code string(100)
is_red_invoice bool
is_electronic bool
ocr_confidence numeric(5,4)
normalized_status string(30) normalized/manual_corrected
duplicate_fingerprint string(100) 发票号+代码+金额+日期
created_at timestamptz
updated_at timestamptz
```
### 8.9 发票验真记录表 `invoice_verification_records`
用途：
- 保留每次调用税局/第三方验真服务的结果，支持追溯。
建议字段：
```text
id string(36) PK
invoice_record_id string(36) FK -> invoice_structured_records.id
verification_channel string(50) tax_mcp/third_party/manual
request_payload_json json
response_payload_json json
verify_status string(30) verified/unverified/voided/error
voided bool
red_reversed bool
verified_amount numeric(12,2)
verified_issue_date date
error_code string(50)
error_message text
verified_by string(64)
verified_at timestamptz
created_at timestamptz
```
### 8.10 明细与票据关联表 `expense_item_documents`
用途：
- 解决一条明细可关联多张票据、一张票据也可能支撑多条拆分明细的场景。
建议字段：
```text
id string(36) PK
claim_id string(36) FK -> expense_claims.id
claim_item_id string(36) FK -> expense_claim_items.id
document_id string(36) FK -> document_assets.id
relation_type string(30) evidence/invoice/boarding_pass/receipt
allocated_amount numeric(12,2) 分摊到该明细的金额
match_status string(30) unmatched/partial/matched
match_confidence numeric(5,4)
created_at timestamptz
updated_at timestamptz
```
### 8.11 风险事件表 `risk_events`
用途：
- 记录风险命中，而不是只在主表里塞一个 `risk_flags_json`。
- 作为 Agent 解释“为什么拦截”的核心依据。
建议字段：
```text
id string(36) PK
biz_domain string(30) expense/ap/ar
biz_object_type string(50) expense_claim/expense_item/invoice
biz_object_id string(36)
risk_code string(50) duplicate_invoice/amount_mismatch 等
risk_name string(100)
risk_level string(20) low/medium/high
hit_source string(30) rule/agent/hermes/manual
evidence_json json
status string(30) open/confirmed/resolved/ignored
detected_at timestamptz
detected_by string(64)
resolved_at timestamptz
resolved_by string(64)
resolution_note text
created_at timestamptz
updated_at timestamptz
```
### 8.12 风险处置表 `risk_actions`
用途：
- 记录每次人工确认、驳回、忽略、要求补件等处置动作。
建议字段：
```text
id string(36) PK
risk_event_id string(36) FK -> risk_events.id
action_type string(30) confirm/reject/ignore/request_more
action_note text
operator_id string(64)
operator_name string(100)
created_at timestamptz
```
### 8.13 文件访问审计表 `document_access_logs`
用途：
- 记录谁看过、下载过、导出过原始票据。
- 支撑财务审计和数据安全追溯。
建议字段：
```text
id string(36) PK
document_id string(36) FK -> document_assets.id
document_version_id string(36) FK -> document_asset_versions.id
action string(30) preview/download/export/delete
operator_id string(64)
operator_name string(100)
operator_role string(50)
client_ip string(64)
user_agent string(255)
trace_id string(64)
created_at timestamptz
```
## 9. 表关系建议
```text
expense_claims
└─ expense_claim_items
└─ expense_item_documents
└─ document_assets
└─ document_asset_versions
└─ document_derivatives
└─ document_ocr_results
└─ invoice_structured_records
└─ invoice_verification_records
risk_events -> 可指向 expense_claims / expense_claim_items / invoice_structured_records
risk_actions -> risk_events
document_access_logs -> document_assets / document_asset_versions
```
原则：
- 主业务对象和文件资产解耦。
- OCR、验真、风险都挂在文件资产或业务对象之上，不把责任塞到一个巨表。
- 文件版本和业务关系分离，避免替换附件时把历史证据冲掉。
## 10. 与现有表的衔接策略
当前代码中已经存在：
- `expense_claims`
- `expense_claim_items`
- `reimbursement_requests`
建议策略：
- `expense_claims` 继续作为未来报销主表。
- `expense_claim_items` 增量扩字段并替换当前单一 `invoice_id` 直连方式。
- `reimbursement_requests` 暂不删除，但冻结扩表。
- 如旧流程仍引用 `reimbursement_requests`，可在过渡期建立：
- `request_no -> claim_no` 对照字段
- 或由 `approval_records` 同时支持两类来源对象
不建议做法：
- 再新建第四张“报销申请主表”。
- 把原始发票图片以 blob 方式存进 `expense_claims`。
- 把 OCR、验真、风控结果全塞进一个 JSON 大字段。
## 11. 实施顺序建议
Phase 1：
- 扩展 `expense_claims`
- 扩展 `expense_claim_items`
- 新增 `document_assets`
- 新增 `document_asset_versions`
- 新增 `expense_item_documents`
Phase 2：
- 新增 `document_ocr_results`
- 新增 `invoice_structured_records`
- 新增 `invoice_verification_records`
- 新增 `document_derivatives`
Phase 3：
- 新增 `risk_events`
- 新增 `risk_actions`
- 新增 `document_access_logs`
Phase 4：
- 逐步弱化 `reimbursement_requests`
- 将 Agent 草稿、审批、OCR、验真、风控全收敛到 `expense_claims` 体系
## 12. 对 Agent 的直接收益
- 用户说“我要报销”时，Agent 能先创建 `expense_claims` 草稿，再持续补槽。
- 用户上传票据后，系统有明确的 `document_assets` 与 `expense_item_documents` 可挂载。
- OCR 和验真结果不是一次性临时输出，而是可追溯、可回放、可审计的长期资产。
- Agent 回答“为什么被拦截”时，可以直接引用 `risk_events` 和票据证据，不再靠拼字符串解释。

119
document/development/agent/agent plan/15_feedback_learning_loop.md Normal file
View File

@@ -0,0 +1,119 @@
# 反馈闭环与持续学习
## 1. 定位
Agent 系统必须能从人工反馈中持续变好。
反馈来源：
- OCR 人工修正。
- 规则误报/漏报。
- 审批人修改意见。
- 用户对回答的反馈。
- Hermes 风险复盘。
- MCP 调用失败和降级。
## 2. 反馈类型
```text
ocr_correction
rule_false_positive
rule_false_negative
agent_answer_feedback
approval_opinion_edit
knowledge_answer_feedback
mcp_failure_feedback
task_result_feedback
```
## 3. 反馈结构
```json
{
"feedback_id": "",
"feedback_type": "rule_false_positive",
"source_object_type": "rule_run",
"source_object_id": "",
"before": {},
"after": {},
"comment": "",
"created_by": "",
"created_at": ""
}
```
## 4. 反馈流向
```text
人工反馈
↓
反馈池
↓
Hermes 聚类分析
↓
候选改进项
↓
人工审核
↓
更新规则 / 知识 / OCR 映射 / Prompt
```
## 5. 反馈不直接自动生效
反馈只能生成候选，不直接修改线上规则。
必须人工审核：
- 规则修改。
- 知识发布。
- Prompt 修改。
- OCR 字段映射调整。
## 6. Hermes 每日反馈复盘
Hermes 每日任务：
```text
读取昨日反馈
聚类相似问题
统计误报高发规则
统计低评分回答
生成优化候选
```
输出：
```text
rule_improvement_candidates
knowledge_update_candidates
ocr_mapping_candidates
prompt_improvement_notes
```
## 7. 质量指标
建议监控：
```text
ocr_correction_rate
rule_false_positive_rate
rule_false_negative_rate
agent_answer_like_rate
agent_answer_rewrite_rate
knowledge_no_hit_rate
mcp_failure_rate
```
## 8. 开发阶段建议
```text
Step 1: 增加反馈按钮和反馈表
Step 2: OCR 修正写入反馈池
Step 3: 规则误报/漏报反馈
Step 4: Agent 回答反馈
Step 5: Hermes 每日反馈聚类
Step 6: 生成优化候选
Step 7: 人工审核发布
Step 8: 建立质量看板
```