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

2026-05-15 06:58:21 +00:00
parent 45abd36430
commit 4f3556a38b
35 changed files with 8257 additions and 0 deletions
--- a/plan/06_data_contracts_and_governance.md
+++ b/plan/06_data_contracts_and_governance.md
@@ -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`
+
+实施原则：
+
+- 先确保“能收、能存、能找回原件”
+- 再确保“能识别、能验真、能回填”
+- 最后做“能解释、能审计、能批量巡检”