X-Financial/document/development/agent week plan/day_4_orchestrator_runtime.md

# Day 4：Orchestrator 运行时

## 今天的大开发点

建立统一调度层。用户请求和系统任务都先进入 Orchestrator，由它完成语义解析、权限判断、能力选择、Agent 路由、工具调用记录和失败降级。

## 为什么第四天做这个

没有 Orchestrator，User Agent 和 Hermes 会各自直接调用能力，权限、审计、降级、Trace 都会分散。生产系统必须有统一入口。

## 今天主要交付

- Orchestrator 请求和响应结构。
- 用户请求路由到 User Agent。
- 定时任务路由到 Hermes。
- 权限级别判断。
- 语义补槽完成后的报销草稿创建、草稿更新、提交动作路由。
- 高风险动作确认机制。
- 能力注册查询。
- 工具调用封装。
- AgentRun Trace 查询。
- 失败降级返回。

## 当前完成情况

- [x] ~~`/api/v1/orchestrator/run`、统一路由、权限阻断、ToolCall 记录、Trace 和降级结果已经可用。~~
- [x] ~~用户消息已能路由到 User Agent，占位 Hermes 任务也能由定时入口触发。~~
- [x] ~~附件名称、页面上下文和 OCR 摘要已能随 Orchestrator 请求透传到语义层和 User Agent。~~
- [x] ~~Orchestrator 已开始向前端返回结构化 `review_payload`，用于右侧预审面板展示识别意图、槽位、票据和分单建议。~~
- [x] ~~`conversation_id`、会话消息历史和 `draft_claim_id` 已接入 Orchestrator，会话内追问可继续落到同一张报销草稿。~~
- [x] ~~已新增最近会话恢复与用户级会话清空接口，个人工作台可显式继续旧会话或删除旧会话后新建。~~
- [x] ~~`clarification_required` 的报销请求已改为返回结构化核对结果，而不是只回一句追问文案。~~
- [x] ~~`review_action`、`review_form_values` 已能透传到 User Agent / 报销草稿服务，用于结构化修改后重识别和保存草稿。~~
- [ ] 真实 `expense_claims` 提交链路尚未接通；草稿建单 / 改单已接到真实落库，附件与 OCR 持久化仍未完成。
- [ ] 报销附件持久化服务、OCR 结果落库服务和前端 ToolCall 细粒度 Trace 展示尚未接通。

相关架构文档：

- [Orchestrator 与运行流程](<../agent plan/04_orchestrator_and_runtime_flow.md>)
- [能力注册](<../agent plan/07_capability_registry.md>)
- [权限与确认](<../agent plan/08_permission_confirmation.md>)
- [观测与 Trace](<../agent plan/09_observability_and_trace.md>)

## 当天验收门槛

- Orchestrator API 可用。
- 用户消息能路由到 User Agent 占位实现。
- 定时任务能路由到 Hermes 占位实现。
- forbidden 请求不会调用下游 Agent。
- 每次运行都有 `run_id` 和 Trace。
- 工具调用失败能记录并返回降级结果。
- 叙述型报销输入在满足最小槽位后能进入建单或改单流程。

## 今天不做

- 不做复杂任务编排 DAG。
- 不做多 Agent 协商。
- 不做自动高风险动作。

## 详细执行清单

以下内容为合并后的详细执行清单。

## 0. 开始前检查

- [x] ~~确认 Day 3 `POST /api/v1/ontology/parse` 可用。~~
- [x] ~~确认 `AgentRun` 可创建。~~
- [x] ~~确认 `AgentToolCall` 可创建。~~
- [x] ~~确认资产列表能查询技能、MCP、任务。~~
- [x] ~~确认权限级别枚举已稳定。~~
- [x] ~~找到后端服务层适合放 Orchestrator 的位置。~~

## 1. Orchestrator 输入输出

- [x] ~~定义 `OrchestratorRequest`。~~
- [x] ~~请求包含 `source`。~~
- [x] ~~请求包含 `user_id`。~~
- [x] ~~请求包含 `message`。~~
- [x] ~~请求包含 `task_id`。~~
- [x] ~~请求包含 `context_json`。~~
- [x] ~~定义 `OrchestratorResponse`。~~
- [x] ~~响应包含 `run_id`。~~
- [x] ~~响应包含 `selected_agent`。~~
- [x] ~~响应包含 `route_reason`。~~
- [x] ~~响应包含 `permission_level`。~~
- [x] ~~响应包含 `status`。~~
- [x] ~~响应包含 `result`。~~
- [x] ~~响应包含 `requires_confirmation`。~~
- [x] ~~响应包含 `trace_summary`。~~

验收证据：

- [x] ~~Orchestrator 响应能直接被前端展示。~~

## 2. 建立 Orchestrator 服务

- [x] ~~新增 `OrchestratorService`。~~
- [x] ~~实现 `run(request)` 主入口。~~
- [x] ~~主入口第一步创建 `AgentRun`。~~
- [x] ~~主入口第二步调用语义解析。~~
- [x] ~~主入口第三步执行权限判断。~~
- [x] ~~主入口第四步选择 Agent。~~
- [x] ~~主入口第五步调用目标 Agent 或返回阻断结果。~~
- [x] ~~主入口第六步更新 `AgentRun` 状态。~~
- [x] ~~所有异常都写入 `AgentRun.error_message`。~~

验收证据：

- [x] ~~正常请求状态为 `succeeded`。~~
- [x] ~~被权限拦截请求状态为 `blocked`。~~
- [x] ~~异常请求状态为 `failed`。~~

## 3. 路由规则

- [x] ~~`source=user_message` 默认路由到 User Agent。~~
- [x] ~~`source=schedule` 默认路由到 Hermes。~~
- [x] ~~`intent=risk_check` 且来源为 schedule 时路由到 Hermes。~~
- [x] ~~`intent=query` 且来源为 user_message 时路由到 User Agent。~~
- [x] ~~`intent=explain` 路由到 User Agent。~~
- [x] ~~`intent=draft` 路由到 User Agent，并可返回结构化核对结果、草稿结果或草稿更新结果。~~
- [x] ~~`scenario=expense` 且最小建单槽位完整时，允许进入 `create_expense_claim_draft`。~~
- [x] ~~`scenario=expense` 且已有 `claim_id` 或会话内 `draft_claim_id` 时，允许进入 `update_expense_claim_draft`。~~
- [ ] `scenario=expense` 且用户明确确认提交时，允许进入 `submit_expense_claim`。
- [x] ~~`permission.level=approval_required` 时设置 `requires_confirmation=true`。~~
- [x] ~~`permission.level=forbidden` 时不调用下游 Agent。~~
- [x] ~~无法识别或信息不足时返回澄清问题。~~

验收证据：

- [x] ~~同一句风险检查，在用户入口和任务入口有不同路由结果。~~

## 4. 权限判断

- [x] ~~新增权限判断服务或函数。~~
- [x] ~~查询类请求返回 `read`。~~
- [x] ~~草稿类请求返回 `draft_write`。~~
- [ ] 报销草稿字段补全、附件挂接返回 `draft_write`。
- [ ] 报销单提交返回 `approval_required`，并要求显式用户确认。
- [ ] 审批、上线、付款类请求返回 `approval_required`。
- [x] ~~用户无权限时返回 `forbidden`。~~
- [x] ~~高风险动作不允许自动执行。~~
- [x] ~~需要确认的动作返回确认提示。~~
- [x] ~~权限判断结果写入 `AgentRun.permission_level`。~~

验收证据：

- [x] ~~“直接上线规则”不会被自动执行。~~
- [x] ~~“直接付款”不会被自动执行。~~

## 5. 能力注册查询

- [x] ~~从 `AgentAsset` 查询 active 技能。~~
- [x] ~~从 `AgentAsset` 查询 active MCP。~~
- [x] ~~从 `AgentAsset` 查询 active 任务。~~
- [ ] 查询可用的报销单写入服务和附件挂接服务。
- [ ] 查询可用的 OCR 结果持久化服务和票据文件回溯服务。
- [x] ~~过滤 disabled 能力。~~
- [x] ~~过滤未审核 active 条件不满足的规则。~~
- [x] ~~为每次能力选择记录 `route_json`。~~
- [x] ~~找不到能力时返回降级说明。~~

验收证据：

- [x] ~~禁用 MCP 不会被 Orchestrator 调用。~~

## 6. 工具调用封装

- [x] ~~定义统一工具调用接口。~~
- [ ] 工具请求前写入 `AgentToolCall` running 或准备记录。
- [x] ~~工具成功后写入响应和耗时。~~
- [x] ~~工具失败后写入错误。~~
- [ ] 报销草稿更新、提交也按工具调用或等价服务调用记录。
- [x] ~~报销草稿创建按工具调用或等价服务调用记录。~~
- [ ] 附件挂接、OCR 结果落库、票据回溯查询也按工具调用或等价服务调用记录。
- [x] ~~外部 MCP 调用失败时返回降级结果。~~
- [x] ~~数据库查询失败时返回明确错误。~~
- [x] ~~LLM 调用失败时返回可读提示。~~

验收证据：

- [x] ~~每次 Orchestrator 运行至少可以看到 0 到多条工具调用记录。~~

## 7. API 接口

- [x] ~~新增 `POST /api/v1/orchestrator/run`。~~
- [x] ~~请求支持用户消息。~~
- [x] ~~请求支持任务触发。~~
- [x] ~~响应返回 `run_id`。~~
- [x] ~~响应返回路由结果。~~
- [x] ~~响应返回权限结果。~~
- [x] ~~复用 `GET /api/v1/agent-runs/{run_id}` 查看 Trace。~~
- [x] ~~Trace 接口返回语义解析、路由、工具调用、最终结果。~~
- [x] ~~`POST /api/v1/orchestrator/run` 返回的 `result` 已可携带 `review_payload`。~~

验收证据：

- [x] ~~前端或 curl 可以完整看到一次运行链路。~~

## 8. 前端最小 Trace 查看

- [ ] 在合适位置展示最近运行记录。
- [x] ~~点击当前对话结果可查看 `run_id`。~~
- [x] ~~展示 selected_agent。~~
- [x] ~~展示 route_reason。~~
- [x] ~~展示 permission_level。~~
- [ ] 展示工具调用列表。
- [x] ~~展示错误信息。~~
- [ ] 展示耗时。
- [ ] 展示报销写链路中的 claim_id / claim_no / status 变化。

验收证据：

- [x] ~~开发调试时不需要直接查数据库才能理解主要路由结果。~~

## 9. 测试

- [x] ~~测试用户查询路由到 User Agent。~~
- [x] ~~测试定时任务路由到 Hermes。~~
- [x] ~~测试叙述型报销输入可路由到报销建单服务。~~
- [x] ~~测试同一 `conversation_id` 下的追问会继续更新已有报销草稿。~~
- [ ] 测试报销单提交前必须显式确认。
- [x] ~~测试 forbidden 不调用下游 Agent。~~
- [x] ~~测试 approval_required 返回确认。~~
- [x] ~~测试工具失败写入 ToolCall。~~
- [x] ~~测试 Orchestrator 异常写入 AgentRun。~~

验收证据：

- [x] ~~Orchestrator 核心测试通过。~~

## 10. Day 4 验收

- [x] ~~Orchestrator API 可用。~~
- [x] ~~用户请求能路由到 User Agent 占位实现。~~
- [x] ~~定时任务能路由到 Hermes 占位实现。~~
- [x] ~~语义补槽完成后的报销输入能路由到建单动作。~~
- [x] ~~语义补槽完成后的报销输入能路由到改单动作。~~
- [x] ~~权限阻断有效。~~
- [x] ~~运行 Trace 可查询。~~
- [x] ~~工具调用日志可查询。~~
- [x] ~~降级结果可读。~~
- [x] ~~所有完成项已用 `[x] ~~...~~` 标记。~~

## 阻塞记录

- [x] ~~暂无。~~

## 日终交接

- [x] ~~当前路由规则已稳定为：`user_message -> user_agent`、`schedule -> hermes`、`clarification_required -> blocked`。~~
- [x] ~~当前权限判断已稳定为：`read / draft_write / approval_required / forbidden`，高风险动作默认阻断或要求确认。~~
- [x] ~~Day 5 需承接的接口契约已明确：Orchestrator 向 User Agent 传入语义结果、能力码、工具结果，并期待返回 `answer / citations / suggested_actions / draft_payload / risk_flags`。~~
- [x] ~~Day 5 当前已扩展接口契约：除 `answer / citations / suggested_actions / draft_payload / risk_flags` 外，还返回 `review_payload` 用于前端预审工作台。~~
- [x] ~~下一步仍需补齐的运行时写链路是：附件持久化、OCR 结果落库和提交状态流转。~~