X-Financial/document/development/agent plan/05_development_roadmap.md

# 分阶段开发计划

## 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 失败率。