feat: 重构 AuditView 支持规则/技能分类，新增 Agent 开发文档

document/development/agent plan/00_README.md

@@ -0,0 +1,38 @@
+# Agent Plan 文档索引
+
+本目录描述 X-Financial 后续要建设的双 Agent 财务智能架构。
+
+核心目标：
+
+- 建立一套共享的语义本体协议，统一理解用户问题、定时任务和规则触发上下文。
+- 建设两套职责边界清晰的 Agent：
+  - Hermes：后台数字员工，负责内循环定时任务、风险巡检、统计、知识维护。
+  - 自建 Agent：用户流程助手，负责用户交互、流程操作、解释、查询、草稿生成。
+- 建设 Agent Orchestrator，统一负责路由、权限、工具调用、审计和失败处理。
+- 让规则中心、MCP、知识库、数据库查询和任务系统使用同一套语义协议。
+
+推荐阅读顺序：
+
+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)
+
+开发原则：
+
+- 先语义协议，后 Agent 能力。
+- 先只读和建议，后写入和流程动作。
+- 先人工确认，后有限自动化。
+- 所有财务关键动作必须可审计、可回滚、可追责。
+- 所有 Agent 能力必须注册、分级、可评测、可追踪。

document/development/agent plan/01_overall_architecture.md

@@ -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: 增加知识候选和规则优化闭环
+```
+

document/development/agent plan/02_semantic_ontology.md

@@ -0,0 +1,362 @@
+# 语义本体协议设计
+
+## 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": []
+}
+```
+
+扩展原则：
+
+- 先不要把所有字段都做成数据库列。
+- 语义结果建议存 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"
+}
+```
+

document/development/agent plan/03_agent_responsibilities.md

@@ -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
+解析语义
+查询报销单
+读取规则命中
+检索制度条款
+组织解释
+给出补件建议
+```
+

document/development/agent plan/04_orchestrator_and_runtime_flow.md

@@ -0,0 +1,194 @@
+# Agent Orchestrator 与运行流程
+
+## 1. Orchestrator 定位
+
+Agent Orchestrator 是双 Agent 架构的调度中心。
+
+它不负责生成最终答案，而是负责：
+
+- 接收用户请求或定时任务。
+- 调用语义解析。
+- 判断处理方。
+- 选择工具。
+- 检查权限。
+- 记录审计。
+- 管理失败重试。
+- 控制高风险动作确认。
+
+## 2. 运行主流程
+
+```text
+输入
+  用户消息 / 页面按钮 / 定时任务 / 系统事件
+  ↓
+语义解析
+  输出 ontology_json
+  ↓
+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
+```
+
+### 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 = ask_clarification
+  返回追问
+```
+
+## 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: 通知财务风控组
+```
+
+## 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": ""
+}
+```
+
+## 7. 失败处理
+
+### 7.1 用户交互失败
+
+```text
+数据库查询失败
+  返回“暂时无法查询”，记录错误
+
+缺少关键字段
+  返回追问
+
+权限不足
+  返回无权限说明
+
+MCP 不可用
+  返回降级说明，必要时生成待处理项
+```
+
+### 7.2 Hermes 任务失败
+
+```text
+任务失败
+  自动重试 3 次
+
+部分 MCP 失败
+  标记 partial_success
+
+数据不完整
+  生成异常任务日志
+
+连续失败
+  通知管理员
+```
+

document/development/agent plan/05_development_roadmap.md

@@ -0,0 +1,435 @@
+# 分阶段开发计划
+
+## 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 建立 ontology schema 表
+
+建议表：
+
+```text
+semantic_ontology_schemas
+semantic_parse_logs
+```
+
+字段：
+
+```text
+id
+schema_version
+schema_json
+status
+created_at
+updated_at
+```
+
+### Step 3.3 建立解析测试集
+
+至少覆盖：
+
+- 报销规则解释。
+- 差旅报销创建。
+- 发票验真。
+- 应收逾期查询。
+- 应付付款状态。
+- 每日风险巡检。
+- 知识库维护。
+
+## 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 失败率。

document/development/agent plan/06_data_contracts_and_governance.md

@@ -0,0 +1,334 @@
+# 数据契约与治理要求
+
+## 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
+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
+```
+
+## 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"],
+  "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 Hermes 任务
+
+```text
+POST /api/v1/hermes/tasks/run
+```
+
+请求：
+
+```json
+{
+  "task_code": "daily_risk_scan",
+  "ontology": {},
+  "dry_run": false
+}
+```
+
+响应：
+
+```json
+{
+  "run_id": "",
+  "status": "accepted"
+}
+```
+
+## 3. 安全原则
+
+### 3.1 最小权限
+
+Agent 调工具时不能使用超级权限。
+
+权限来源：
+
+- 用户权限。
+- 任务权限。
+- 服务账号权限。
+
+### 3.2 高风险动作确认
+
+以下动作必须确认：
+
+- 提交报销。
+- 发起付款。
+- 生成正式审批意见。
+- 发布规则。
+- 发布知识库。
+- 创建外部通知。
+
+### 3.3 审计不可省略
+
+必须记录：
+
+- 谁触发。
+- 输入是什么。
+- 解析结果是什么。
+- 调了哪些工具。
+- 输出是什么。
+- 是否确认。
+- 是否失败。
+
+## 4. 数据治理
+
+### 4.1 脱敏
+
+Hermes 批处理尽量使用脱敏快照。
+
+敏感字段：
+
+- 身份证。
+- 银行卡。
+- 手机号。
+- 个人住址。
+- 个人发票抬头中的敏感信息。
+
+### 4.2 数据保留
+
+建议：
+
+- Agent 运行日志保留 180 天。
+- 工具调用详细请求保留 90 天。
+- 错误日志保留 365 天。
+- 审核记录永久保留。
+
+### 4.3 版本治理
+
+规则、技能、MCP、任务都应版本化。
+
+规则版本尤其重要：
+
+- 当前版本必须明确。
+- 历史版本可查看。
+- 切换版本需要确认。
+- 上线版本必须审核通过。
+
+## 5. 发布策略
+
+### 5.1 第一阶段
+
+只允许只读能力：
+
+- 查知识库。
+- 查状态。
+- 看规则。
+- 看任务报告。
+
+### 5.2 第二阶段
+
+允许生成草稿：
+
+- 报销草稿。
+- 付款申请草稿。
+- 审批意见草稿。
+- 知识候选草稿。
+
+### 5.3 第三阶段
+
+允许确认后执行：
+
+- 用户确认后提交报销。
+- 审批人确认后写入审批意见。
+- 管理员确认后发布知识。
+- 管理员确认后上线规则。
+
+### 5.4 禁止项
+
+长期禁止：
+
+- Agent 自动最终审批。
+- Agent 自动付款。
+- Agent 自动绕过规则。
+- Agent 自动修改财务核心数据。
+

document/development/agent plan/07_capability_registry.md

@@ -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 调用。
+- 能力版本变更必须写入审计。
+

document/development/agent plan/08_permission_confirmation.md

@@ -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: 增加权限测试用例
+```
+

document/development/agent plan/09_observability_and_trace.md

@@ -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: 增加异常告警规则
+```
+

document/development/agent plan/10_evaluation_and_testset.md

@@ -0,0 +1,173 @@
+# 评测集与质量控制
+
+## 1. 为什么需要评测集
+
+语义解析、本体字段、Agent 路由、规则命中都不能只靠人工感觉。
+
+每次修改 prompt、模型、规则或路由逻辑，都应该运行评测集。
+
+目标：
+
+- 检查 domain 是否识别正确。
+- 检查 scenario 是否识别正确。
+- 检查 intent 是否识别正确。
+- 检查 next_step 是否正确。
+- 检查是否应该追问。
+- 检查是否错误调用高风险工具。
+
+## 2. 第一版评测集规模
+
+建议第一版至少 300 条。
+
+```text
+报销问题：80 条
+应收问题：60 条
+应付问题：60 条
+制度问答：40 条
+风险解释：30 条
+定时任务：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
+```
+
+### 4.2 工具路由准确率
+
+```text
+tool_route_accuracy
+permission_decision_accuracy
+confirmation_decision_accuracy
+```
+
+### 4.3 安全指标
+
+```text
+unsafe_action_rate
+missing_confirmation_rate
+permission_bypass_rate
+```
+
+这些指标必须接近 0。
+
+## 5. 低置信度处理
+
+语义解析输出应包含：
+
+```json
+{
+  "confidence": 0.62,
+  "missing_slots": ["time_range"],
+  "ambiguity": ["应收逾期还是审批逾期"]
+}
+```
+
+当置信度低于阈值：
+
+```text
+confidence < 0.75
+  不执行工具
+  返回追问
+```
+
+## 6. 模糊问题样例
+
+用户问：
+
+```text
+这个为什么还没处理？
+```
+
+不能直接执行查询。
+
+应该追问：
+
+```text
+你是想查询报销单、应收款还是付款申请的处理状态？
+```
+
+## 7. 回归测试流程
+
+每次改动以下内容都要跑评测：
+
+- 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
+```
+
+## 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 或手动发布检查
+```
+

document/development/agent plan/11_ocr_invoice_architecture.md

@@ -0,0 +1,221 @@
+# OCR 票据识别架构
+
+## 1. 定位
+
+OCR 票据识别不是一个简单的图片转文字功能。
+
+它在 X-Financial 中承担三件事：
+
+1. 把用户上传的附件变成结构化票据信息。
+2. 为规则中心提供可判断的字段。
+3. 为 Hermes 和 User Agent 提供可解释的证据。
+
+因此 OCR 应作为独立能力纳入 Capability Registry。
+
+```text
+capability_type = mcp | document_processor
+capability_code = invoice_ocr
+```
+
+## 2. 总体链路
+
+```text
+附件上传
+  ↓
+文件分类
+  ↓
+OCR 识别
+  ↓
+字段结构化
+  ↓
+票据类型归一化
+  ↓
+发票验真 MCP
+  ↓
+与报销明细匹配
+  ↓
+规则中心检查
+  ↓
+人工修正
+  ↓
+修正结果沉淀
+```
+
+## 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. 数据模型建议
+
+```text
+document_assets
+document_ocr_results
+invoice_structured_records
+invoice_verification_records
+document_corrections
+```
+
+## 5. 与规则中心关系
+
+OCR 输出供规则使用：
+
+```text
+重复报销识别规则
+作废发票检查规则
+发票抬头异常规则
+附件完整性规则
+金额不一致规则
+```
+
+## 6. 与 Agent 关系
+
+User Agent 使用 OCR：
+
+- 解释发票为什么被拦截。
+- 帮用户补充发票信息。
+- 提醒上传清晰附件。
+
+Hermes 使用 OCR：
+
+- 夜间批量验真。
+- 扫描重复票据。
+- 统计发票异常趋势。
+
+## 7. 开发阶段建议
+
+```text
+Step 1: 附件上传和文件分类
+Step 2: 接入 OCR MCP
+Step 3: 结构化字段归一化
+Step 4: 人工修正界面
+Step 5: 发票验真 MCP
+Step 6: 与报销明细匹配
+Step 7: 规则中心接入
+Step 8: Hermes 夜间批量 OCR 巡检
+```
+

document/development/agent plan/12_llm_wiki_knowledge_architecture.md

@@ -0,0 +1,148 @@
+# LLM Wiki 知识库架构
+
+## 1. 定位
+
+LLM Wiki 不是简单的文件库。
+
+它是给 Agent 使用的知识底座，负责把制度、FAQ、审批经验、规则说明转成可检索、可引用、可版本化的知识。
+
+## 2. 总体链路
+
+```text
+文档上传
+  ↓
+格式解析
+  ↓
+正文抽取
+  ↓
+分块 Chunking
+  ↓
+元数据标注
+  ↓
+向量索引
+  ↓
+条款抽取
+  ↓
+知识候选
+  ↓
+人工审核
+  ↓
+发布 Wiki
+  ↓
+Agent 检索引用
+```
+
+## 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 页"
+}
+```
+
+该结果不直接变成规则，先进入规则候选池。
+
+## 6. Wiki 发布流程
+
+```text
+草稿知识
+  ↓
+Hermes 生成候选
+  ↓
+知识管理员审核
+  ↓
+发布
+  ↓
+Agent 可检索
+```
+
+## 7. 与 User Agent 的关系
+
+User Agent 用 Wiki：
+
+- 回答制度问题。
+- 给风险解释提供条款依据。
+- 给审批意见生成引用。
+- 帮用户理解流程。
+
+## 8. 与 Hermes 的关系
+
+Hermes 用 Wiki：
+
+- 每日知识候选生成。
+- 发现制度与规则不一致。
+- 生成规则优化建议。
+- 生成 FAQ 候选。
+
+## 9. 数据模型建议
+
+```text
+knowledge_documents
+knowledge_chunks
+knowledge_embeddings
+knowledge_candidates
+knowledge_reviews
+knowledge_versions
+```
+
+## 10. 开发阶段建议
+
+```text
+Step 1: 文档上传和文件管理
+Step 2: 文本抽取和分块
+Step 3: 元数据标注
+Step 4: 向量索引
+Step 5: 知识检索 API
+Step 6: User Agent 问答引用
+Step 7: Hermes 知识候选生成
+Step 8: 人工审核发布
+Step 9: 条款抽取和规则候选
+```
+

document/development/agent plan/13_rule_formation_lifecycle.md

@@ -0,0 +1,126 @@
+# 规则形成生命周期
+
+## 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"
+}
+```
+
+## 4. 规则 Markdown 推荐结构
+
+```markdown
+# 规则名称
+
+## 目标
+
+## 适用范围
+
+## 输入字段
+
+## 判断规则
+
+## 输出
+
+## 测试样例
+
+## 管理员备注
+```
+
+## 5. 审核要求
+
+规则上线必须满足：
+
+- 有审核人。
+- 有版本。
+- 有测试样例。
+- 有来源依据。
+- 有回滚方案。
+
+## 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: 规则质量看板
+```
+

document/development/agent plan/14_financial_document_canonical_model.md

@@ -0,0 +1,126 @@
+# 财务单据标准模型
+
+## 1. 为什么需要标准模型
+
+OCR、MCP、用户填写、业务数据库可能都描述同一张发票，但字段名和格式不同。
+
+如果没有标准模型：
+
+- 规则无法复用。
+- Agent 难以解释。
+- Hermes 难以批量统计。
+- MCP 返回结果难以合并。
+
+## 2. 标准对象
+
+第一版建议定义这些对象：
+
+```text
+Invoice
+Receipt
+ReimbursementRequest
+PaymentRequest
+BankTransaction
+Contract
+Customer
+Vendor
+Employee
+CostCenter
+```
+
+## 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. ReimbursementRequest 标准模型
+
+```json
+{
+  "request_id": "",
+  "request_no": "",
+  "employee_id": "",
+  "department_id": "",
+  "expense_type": "",
+  "amount": 0,
+  "currency": "CNY",
+  "status": "",
+  "submitted_at": "",
+  "approval_stage": "",
+  "invoices": [],
+  "attachments": [],
+  "risk_flags": []
+}
+```
+
+## 5. BankTransaction 标准模型
+
+```json
+{
+  "transaction_id": "",
+  "bank_account": "",
+  "transaction_date": "",
+  "amount": 0,
+  "currency": "CNY",
+  "counterparty_name": "",
+  "summary": "",
+  "matched_object_type": "",
+  "matched_object_id": "",
+  "match_status": ""
+}
+```
+
+## 6. 字段来源优先级
+
+建议优先级：
+
+```text
+人工确认字段
+  > MCP 验真字段
+  > 业务系统字段
+  > OCR 字段
+  > LLM 推断字段
+```
+
+LLM 推断字段必须标记来源和置信度。
+
+## 7. 与语义本体关系
+
+语义本体识别的是用户意图和对象。
+
+标准模型承载对象的结构化字段。
+
+```text
+ontology.entities[].type = invoice
+  -> 映射到 Invoice 标准模型
+```
+
+## 8. 开发阶段建议
+
+```text
+Step 1: 定义 Invoice 标准模型
+Step 2: 定义 ReimbursementRequest 标准模型
+Step 3: OCR 输出映射到 Invoice
+Step 4: MCP 输出映射到 Invoice
+Step 5: 规则中心基于标准模型执行
+Step 6: 扩展 AR/AP 标准模型
+Step 7: 建立字段血缘和置信度
+```
+

document/development/agent plan/15_feedback_learning_loop.md

@@ -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: 建立质量看板
+```
+