# Day 4：Orchestrator 运行时 TODO

目标：建立统一调度层，让用户请求和系统任务都先进入 Orchestrator，再根据语义本体、权限、能力注册路由到 User Agent、Hermes、MCP 或规则引擎。

参考文档：

- `document/development/agent plan/04_orchestrator_and_runtime_flow.md`
- `document/development/agent plan/07_capability_registry.md`
- `document/development/agent plan/08_permission_confirmation.md`
- `document/development/agent plan/09_observability_and_trace.md`

## 0. 开始前检查

- [ ] 确认 Day 3 `POST /api/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，但只允许生成草稿。
- [ ] `permission.level=approval_required` 时设置 `requires_confirmation=true`。
- [ ] `permission.level=forbidden` 时不调用下游 Agent。
- [ ] 无法识别时返回澄清问题。

验收证据：

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

## 4. 权限判断

- [ ] 新增权限判断服务或函数。
- [ ] 查询类请求返回 `read`。
- [ ] 草稿类请求返回 `draft_write`。
- [ ] 审批、上线、付款类请求返回 `approval_required`。
- [ ] 用户无权限时返回 `forbidden`。
- [ ] 高风险动作不允许自动执行。
- [ ] 需要确认的动作返回确认提示。
- [ ] 权限判断结果写入 `AgentRun.permission_level`。

验收证据：

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

## 5. 能力注册查询

- [ ] 从 `AgentAsset` 查询 active 技能。
- [ ] 从 `AgentAsset` 查询 active MCP。
- [ ] 从 `AgentAsset` 查询 active 任务。
- [ ] 过滤 disabled 能力。
- [ ] 过滤未审核 active 条件不满足的规则。
- [ ] 为每次能力选择记录 `route_json`。
- [ ] 找不到能力时返回降级说明。

验收证据：

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

## 6. 工具调用封装

- [ ] 定义统一工具调用接口。
- [ ] 工具请求前写入 `AgentToolCall` running 或准备记录。
- [ ] 工具成功后写入响应和耗时。
- [ ] 工具失败后写入错误。
- [ ] 外部 MCP 调用失败时返回降级结果。
- [ ] 数据库查询失败时返回明确错误。
- [ ] LLM 调用失败时返回可读提示。

验收证据：

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

## 7. API 接口

- [ ] 新增 `POST /api/orchestrator/run`。
- [ ] 请求支持用户消息。
- [ ] 请求支持任务触发。
- [ ] 响应返回 `run_id`。
- [ ] 响应返回路由结果。
- [ ] 响应返回权限结果。
- [ ] 新增 `GET /api/orchestrator/runs/{run_id}/trace` 或复用 AgentRun 详情接口。
- [ ] 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] ~~...~~` 标记。

## 阻塞记录

- [ ] 暂无。

## 日终交接

- [ ] 写明路由规则现状。
- [ ] 写明权限判断现状。
- [ ] 写明 Day 5 User Agent 需要实现的接口契约。