X-Financial/document/development/agent plan/06_data_contracts_and_governance.md

# 数据契约与治理要求

## 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 自动修改财务核心数据。