ba28627f11
- Update 00_README.md: refresh week plan overview and structure - Update MASTER_TODO.md: update master todo list for new week - Update day_1_foundation_models.md: expand foundation models tasks - Update day_2_rule_center_integration.md: add rule center integration tasks - Update day_3_semantic_ontology_mvp.md: add semantic ontology tasks - Update day_4_orchestrator_runtime.md: add orchestrator runtime tasks - Update day_5_user_agent_mvp.md: add user agent tasks - Update day_6_hermes_mvp.md: add hermes agent tasks - Update day_7_hardening_demo_acceptance.md: add hardening tasks
8.9 KiB
8.9 KiB
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 任务也能由定时入口触发。- 真实
expense_claims建单 / 改单 / 提交链路尚未接通，当前草稿路径仍是占位执行。
相关架构文档：
当天验收门槛
- Orchestrator API 可用。
- 用户消息能路由到 User Agent 占位实现。
- 定时任务能路由到 Hermes 占位实现。
- forbidden 请求不会调用下游 Agent。
- 每次运行都有
run_id和 Trace。 - 工具调用失败能记录并返回降级结果。
- 叙述型报销输入在满足最小槽位后能进入建单或改单流程。
今天不做
- 不做复杂任务编排 DAG。
- 不做多 Agent 协商。
- 不做自动高风险动作。
详细执行清单
以下内容为合并后的详细执行清单。
0. 开始前检查
确认 Day 3POST /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时，允许进入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 任务。- 查询可用的报销单写入服务和附件挂接服务。
过滤 disabled 能力。过滤未审核 active 条件不满足的规则。为每次能力选择记录route_json。找不到能力时返回降级说明。
验收证据：
禁用 MCP 不会被 Orchestrator 调用。
6. 工具调用封装
定义统一工具调用接口。- 工具请求前写入
AgentToolCallrunning 或准备记录。 工具成功后写入响应和耗时。工具失败后写入错误。- 报销草稿创建、更新、提交也按工具调用或等价服务调用记录。
外部 MCP 调用失败时返回降级结果。数据库查询失败时返回明确错误。LLM 调用失败时返回可读提示。
验收证据：
每次 Orchestrator 运行至少可以看到 0 到多条工具调用记录。
7. API 接口
新增POST /api/v1/orchestrator/run。请求支持用户消息。请求支持任务触发。响应返回run_id。响应返回路由结果。响应返回权限结果。复用GET /api/v1/agent-runs/{run_id}查看 Trace。Trace 接口返回语义解析、路由、工具调用、最终结果。
验收证据：
前端或 curl 可以完整看到一次运行链路。
8. 前端最小 Trace 查看
- 在合适位置展示最近运行记录。
点击当前对话结果可查看run_id。展示 selected_agent。展示 route_reason。展示 permission_level。- 展示工具调用列表。
展示错误信息。- 展示耗时。
验收证据：
开发调试时不需要直接查数据库才能理解主要路由结果。
9. 测试
测试用户查询路由到 User Agent。测试定时任务路由到 Hermes。- 测试叙述型报销输入可路由到报销建单服务。
- 测试报销单提交前必须显式确认。
测试 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。