YG-Soft/X-Financial

Fork 0

Files

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

2026-05-15 06:58:21 +00:00

7.2 KiB

Raw Blame History

数据契约与治理要求

1. 推荐数据表

1.1 语义本体

semantic_ontology_schemas

字段：

id
schema_version
schema_json
status
created_by
created_at
updated_at

semantic_parse_logs

字段：

id
source
user_id
raw_text
ontology_json
confidence
parse_strategy
created_at

1.2 Agent 资产

agent_rules
agent_skills
agent_mcp_services
agent_tasks

通用字段：

id
code
name
description
status
owner
reviewer
config_json
created_at
updated_at

1.3 版本与审核

agent_asset_versions

字段：

id
asset_type
asset_id
version
content
change_note
created_by
created_at

agent_asset_reviews

字段：

id
asset_type
asset_id
version
reviewer
review_status
review_note
reviewed_at

1.4 运行日志

agent_runs

字段：

id
agent
source
task_id
user_id
ontology_json
status
started_at
finished_at
result_summary
error_message

agent_tool_calls

字段：

id
run_id
tool_type
tool_name
request_json
response_json
status
duration_ms
created_at

1.5 财务业务主表

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 票据与文件资产表

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、验真与风险表

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 语义解析

POST /api/v1/semantic/parse

请求：

{
  "source": "user_message",
  "text": "这张发票为什么被拦截？",
  "context": {
    "user_id": "emp_001",
    "current_page": "reimbursement_detail"
  }
}

响应：

{
  "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 执行

POST /api/v1/agent/orchestrate

请求：

{
  "source": "user_message",
  "ontology": {},
  "context": {}
}

响应：

{
  "agent": "user_agent",
  "tools_called": [],
  "answer": "",
  "requires_confirmation": false,
  "audit_id": ""
}

2.3 文件上传契约

POST /api/v1/documents/upload

请求：

{
  "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"
    }
  ]
}

响应：

{
  "documents": [
    {
      "document_id": "",
      "version_no": 1,
      "storage_status": "stored",
      "ocr_status": "pending"
    }
  ]
}

2.4 Hermes 任务

POST /api/v1/hermes/tasks/run

请求：

{
  "task_code": "daily_risk_scan",
  "ontology": {},
  "dry_run": false,
  "context_json": {
    "folder": "报销制度",
    "changed_only": true,
    "force": false
  }
}

响应：

{
  "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

实施原则：

先确保“能收、能存、能找回原件”
再确保“能识别、能验真、能回填”
最后做“能解释、能审计、能批量巡检”

7.2 KiB Raw Blame History Unescape Escape