# Agent Orchestrator 与运行流程

## 1. Orchestrator 定位

Agent Orchestrator 是双 Agent 架构的调度中心。

它不负责生成最终答案，而是负责：

- 接收用户请求或定时任务。
- 调用语义解析。
- 判断处理方。
- 选择工具。
- 检查权限。
- 记录审计。
- 管理失败重试。
- 控制高风险动作确认。

## 2. 运行主流程

```text
输入
  用户消息 / 页面按钮 / 定时任务 / 系统事件
  ↓
上下文装配
  页面对象 / 附件名称 / OCR 摘要 / VLM 摘要 / 用户角色 / conversation_id / draft_claim_id
  ↓
语义解析
  LLM 主解析 + 规则兜底，输出 ontology_json
  ↓
语义校验
  confidence / missing_slots / ambiguity / permission 初判
  ↓
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
```

补充约束：

- 这里的 Hermes 指系统后台真实 Hermes 进程或 Hermes CLI，不是前端概念上的 “Hermes 模式”。
- Orchestrator 负责路由、权限、审计和 Trace，不负责替代 Hermes 自身执行。
- 当前阶段允许保留本地 fallback，但必须预留真实 Hermes 进程调用入口。

### 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 = create_expense_claim_draft
  创建 expense_claims / expense_claim_items 草稿

next_step = update_expense_claim_draft
  回写报销主表、明细和附件关联

next_step = submit_expense_claim
  用户确认后更新 expense_claims.status = submitted

next_step = ask_clarification
  返回追问
```

### 3.4 低置信度与缺槽位保护

当满足以下任一条件时，不允许直接进入数据库、MCP 或高风险流程：

```text
confidence < threshold
missing_slots 非空
ambiguity 非空
输入为叙述型报销，但缺少关键报销信息
```

处理方式：

```text
next_step = ask_clarification
selected_agent = user_agent
tool_count = 0
```

### 3.5 叙述型报销输入保护

像下面这类文本：

```text
我今天去客户现场，招待了客户，花销了1000元
我垫付了交通费和午餐费
我上传了票据，帮我整理一下
```

不能因为出现“客户”就落到应收查询。

Orchestrator 应依赖语义层返回的 `scenario + intent + missing_slots` 做决策，而不是二次猜测文本关键词。

### 3.6 报销建单与状态流转边界

当 `scenario = expense` 且已满足最小建单槽位时：

```text
next_step = create_expense_claim_draft
status = draft
```

当用户继续补充金额、地点、客户、参与人、附件时：

```text
next_step = update_expense_claim_draft
status 保持 draft
```

当用户明确说“提交报销”并完成确认时：

```text
next_step = submit_expense_claim
status = submitted
requires_confirmation = true
```

以下状态不应由 User Agent 直接改写：

```text
approved
rejected
paid
```

这些状态应由审批流、财务支付流或受控后台同步更新。

### 3.7 结构化核对回路

当 `scenario = expense` 且当前仍存在缺槽位、附件待核对或票据需拆单时，不直接返回一段自由文本，而是返回结构化核对结果：

```text
result.review_payload
  intent_summary
  body_message
  slot_cards
  risk_briefs
  document_cards
  claim_groups
  confirmation_actions = 取消 / 修改 / 保存草稿或下一步
  edit_fields
```

前端正文区只展示简洁提示，右侧展示字段、风险、票据与分单明细。

### 3.8 会话续接与重识别

用户对话不是无状态调用。Orchestrator 需要携带以下会话字段继续当前报销流程：

```text
conversation_id
draft_claim_id
conversation_history
review_action
review_form_values
```

其中：

```text
review_action = edit_review
  表示用户基于结构化模板修改识别结果，需要重新进入语义识别

review_action = save_draft
  表示信息未补齐，但允许先保存报销草稿

review_action = next_step
  表示用户确认当前识别结果，可进入下一步流转
```

## 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: 通知财务风控组
```

### 5.1 Hermes 后台执行方式

推荐最小形态：

```text
任务系统 / 手动触发 API
  ↓
Orchestrator 生成 run_id、任务上下文、权限信息
  ↓
后端调用系统 Hermes CLI 或 Hermes 后台进程
  ↓
Hermes 执行知识同步 / 风险巡检 / 规则草稿形成
  ↓
结果回写 AgentRun / ToolCall / 审计日志
```

约束：

- Hermes 运行使用系统级配置，不在任务代码里再写一套模型配置。
- Hermes 运行失败要记录 stderr 或等价错误摘要。
- Hermes 输出的知识候选和规则草稿必须回写为结构化结果，不只保留终端文本。

## 5A. 用户报销建单示例

用户输入：

```text
我今天去客户现场，招待了客户，花销了1000元
```

流程：

```text
Step 1: User Agent 接收消息
Step 2: semantic_parser 输出 ontology_json
Step 3: Orchestrator 判断 scenario = expense, intent = draft
Step 4: 若缺客户、参与人、附件，则 next_step = ask_clarification
Step 5: 补齐最小槽位后，next_step = create_expense_claim_draft
Step 6: 创建 expense_claims / expense_claim_items
Step 7: 若有附件，则挂接 document_assets / expense_item_documents
Step 8: 用户确认提交后，next_step = submit_expense_claim
Step 9: 更新 expense_claims.status = submitted
Step 10: 写入 AgentRun、ToolCall、AuditLog
```

## 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": ""
}
```

建议补充 Trace 字段：

```json
{
  "semantic_provider": "",
  "semantic_model": "",
  "semantic_prompt_version": "",
  "semantic_parse_strategy": "llm_primary | rule_fallback",
  "semantic_fallback_reason": "",
  "semantic_latency_ms": 0
}
```

## 7. 失败处理

### 7.1 用户交互失败

```text
数据库查询失败
  返回“暂时无法查询”，记录错误

缺少关键字段
  返回追问

权限不足
  返回无权限说明

MCP 不可用
  返回降级说明，必要时生成待处理项
```

### 7.2 Hermes 任务失败

```text
任务失败
  自动重试 3 次

部分 MCP 失败
  标记 partial_success

数据不完整
  生成异常任务日志

连续失败
  通知管理员
```
