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 查询。
• 失败降级返回。

当前完成情况

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

相关架构文档：

• Orchestrator 与运行流程
• 能力注册
• 权限与确认
• 观测与 Trace

当天验收门槛

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

今天不做

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

详细执行清单

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

0. 开始前检查

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

1. Orchestrator 输入输出

• 定义 OrchestratorRequest。
• 请求包含 source。
• 请求包含 user_id。
• 请求包含 message。
• 请求包含 task_id。
• 请求包含 context_json。
• 定义 OrchestratorResponse。
• 响应包含 run_id。
• 响应包含 selected_agent。
• 响应包含 route_reason。
• 响应包含 permission_level。
• 响应包含 status。
• 响应包含 result。
• 响应包含 requires_confirmation。
• 响应包含 trace_summary。

验收证据：

• Orchestrator 响应能直接被前端展示。

2. 建立 Orchestrator 服务

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

验收证据：

• 正常请求状态为 succeeded。
• 被权限拦截请求状态为 blocked。
• 异常请求状态为 failed。

3. 路由规则

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

验收证据：

• 同一句风险检查，在用户入口和任务入口有不同路由结果。

4. 权限判断

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

验收证据：

• “直接上线规则”不会被自动执行。
• “直接付款”不会被自动执行。

5. 能力注册查询

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

验收证据：

• 禁用 MCP 不会被 Orchestrator 调用。

6. 工具调用封装

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

验收证据：

• 每次 Orchestrator 运行至少可以看到 0 到多条工具调用记录。

7. API 接口

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

验收证据：

• 前端或 curl 可以完整看到一次运行链路。

8. 前端最小 Trace 查看

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

验收证据：

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

9. 测试

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

验收证据：

• Orchestrator 核心测试通过。

10. Day 4 验收

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

阻塞记录

• 暂无。

日终交接

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