D4 Day 4 View
返回总览 周计划原文 合并文档原文
Runtime

# Day 4 Orchestrator 运行时

Day 4 把整个系统第一次串成“能跑的链”。用户消息和定时任务都先走 Orchestrator，由它创建 run、调用语义解析、做权限判断、选择 Agent、记录 ToolCall 和 Trace，然后再给下游执行。

上游依赖
Day 3 的语义解析结果，Day 1 的 Run / ToolCall，Day 2 的 active 资产。
下游交接
Day 5 User Agent 和 Day 6 Hermes 都通过它被调度。
当天关键
权限拦截和 Trace 必须在 Orchestrator 层，而不是散落在各 Agent。
Three-Layer Mapping

## 三层文档映射

### 路线图

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

day_4_orchestrator_runtime.md

### 执行细则

执行层拆成输入输出、Orchestrator 服务、路由规则、权限判断、能力查询、工具调用封装、API、最小 Trace 查看和测试。

agent week plan/day_4

### 架构依据

主要受运行时流程、能力注册、权限确认和可观测性约束。Day 4 的输出要能直接给前端展示，并支持 Day 5/6 的占位实现接入。

04 07 08 09
Build Order

## 推荐开发顺序

Step 1先定 `OrchestratorRequest` 和 `OrchestratorResponse`。
Step 2写 `run(request)` 主流程：创建 Run、解析语义、判权限、选 Agent、更新状态。
Step 3把用户入口 / 任务入口的路由规则固化下来。
Step 4封装工具调用记录和降级策略。
Step 5暴露 API 和最小 Trace 页面或接口。
Must Deliver

## 今天必须产出的东西

### 统一入口

- `source=user_message` 与 `source=schedule` 都能进同一入口。
- 请求返回 `run_id`、`selected_agent`、`route_reason`、`permission_level`。
- 返回结果要能被前端直接展示。

### 权限与路由

- 查询类走 User Agent，定时风险类走 Hermes。
- `approval_required` 只返回确认，不直接执行。
- `forbidden` 直接阻断，不调下游 Agent。

### 能力与工具调用

- 只查询 active 技能 / MCP / 任务。
- 禁用能力不允许被调用。
- 每次工具调用都能落 `AgentToolCall`。

### Trace 与降级

- Trace 能串起语义解析、路由、工具调用和最终结果。
- 外部 MCP 失败要返回降级说明，不让前端拿到不可读错误。
- 异常都要写进 `AgentRun.error_message`。

Acceptance Snapshot

## 验收快照

路由结果
同一句风险检查，在用户入口和任务入口会有不同路由结果。
权限边界
“直接上线规则”和“直接付款”都不会被自动执行。
日志完整度
每次运行至少有一条 `AgentRun`，工具调用有 0 到多条 `AgentToolCall`。
可观察性
前端或 curl 可以完整看到一次运行链路，不需要直接查数据库猜过程。
Common Misses

## 这一天最容易漏掉的点

- 把权限判断放到 User Agent / Hermes 内部，导致系统没有统一边界。
- 只记录成功 ToolCall，不记录失败 ToolCall，后面降级和排错会缺证据。
- 路由能跑，但没有统一 Trace 输出，Day 7 演示时会非常难讲清链路。