document/development/agent/agent_week_plan_html/day-4.html

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Day 4 - Orchestrator 运行时</title>
  <link rel="stylesheet" href="./styles.css">
</head>
<body>
  <div class="shell">
    <div class="topbar">
      <a class="brand" href="./index.html"><span class="brand-mark">D4</span><span>Day 4 View</span></a>
      <div class="quick-links">
        <a class="pill" href="./index.html">返回总览</a>
        <a class="pill" href="../agent%20week%20plan/day_4_orchestrator_runtime.md">周计划原文</a>
        <a class="pill" href="../agent%20week%20plan/day_4_orchestrator_runtime.md">合并文档原文</a>
      </div>
    </div>

    <div class="day-nav">
      <a class="pill" href="./day-1.html">Day 1</a>
      <a class="pill" href="./day-2.html">Day 2</a>
      <a class="pill" href="./day-3.html">Day 3</a>
      <a class="pill active" href="./day-4.html">Day 4</a>
      <a class="pill" href="./day-5.html">Day 5</a>
      <a class="pill" href="./day-6.html">Day 6</a>
      <a class="pill" href="./day-7.html">Day 7</a>
    </div>

    <section class="hero">
      <div class="hero-badge">Runtime</div>
      <h1>Day 4 Orchestrator 运行时</h1>
      <p>Day 4 把整个系统第一次串成“能跑的链”。用户消息和定时任务都先走 Orchestrator，由它创建 run、调用语义解析、做权限判断、选择 Agent、记录 ToolCall 和 Trace，然后再给下游执行。</p>
      <div class="hero-meta">
        <div class="meta-card"><div class="meta-label">上游依赖</div><div class="meta-value">Day 3 的语义解析结果，Day 1 的 Run / ToolCall，Day 2 的 active 资产。</div></div>
        <div class="meta-card"><div class="meta-label">下游交接</div><div class="meta-value">Day 5 User Agent 和 Day 6 Hermes 都通过它被调度。</div></div>
        <div class="meta-card"><div class="meta-label">当天关键</div><div class="meta-value">权限拦截和 Trace 必须在 Orchestrator 层，而不是散落在各 Agent。</div></div>
      </div>
    </section>

    <div class="section-kicker">Three-Layer Mapping</div>
    <h2 class="section-title">三层文档映射</h2>
    <div class="grid three">
      <section class="card tone-warm">
        <h3>路线图</h3>
        <p>周计划要求建立统一调度层，让用户请求和系统任务都先进入 Orchestrator，再根据语义、权限、能力注册路由到 User Agent、Hermes、MCP 或规则引擎。</p>
        <div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_4_orchestrator_runtime.md">day_4_orchestrator_runtime.md</a></div>
      </section>
      <section class="card tone-teal">
        <h3>执行细则</h3>
        <p>执行层拆成输入输出、Orchestrator 服务、路由规则、权限判断、能力查询、工具调用封装、API、最小 Trace 查看和测试。</p>
        <div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_4_orchestrator_runtime.md">agent week plan/day_4</a></div>
      </section>
      <section class="card tone-olive">
        <h3>架构依据</h3>
        <p>主要受运行时流程、能力注册、权限确认和可观测性约束。Day 4 的输出要能直接给前端展示，并支持 Day 5/6 的占位实现接入。</p>
        <div class="card-links">
          <a class="link-chip" href="../agent%20plan/04_orchestrator_and_runtime_flow.md">04</a>
          <a class="link-chip" href="../agent%20plan/07_capability_registry.md">07</a>
          <a class="link-chip" href="../agent%20plan/08_permission_confirmation.md">08</a>
          <a class="link-chip" href="../agent%20plan/09_observability_and_trace.md">09</a>
        </div>
      </section>
    </div>

    <div class="section-kicker">Build Order</div>
    <h2 class="section-title">推荐开发顺序</h2>
    <div class="timeline">
      <div class="timeline-step"><strong>Step 1</strong>先定 <code>OrchestratorRequest</code> 和 <code>OrchestratorResponse</code>。</div>
      <div class="timeline-step"><strong>Step 2</strong>写 <code>run(request)</code> 主流程：创建 Run、解析语义、判权限、选 Agent、更新状态。</div>
      <div class="timeline-step"><strong>Step 3</strong>把用户入口 / 任务入口的路由规则固化下来。</div>
      <div class="timeline-step"><strong>Step 4</strong>封装工具调用记录和降级策略。</div>
      <div class="timeline-step"><strong>Step 5</strong>暴露 API 和最小 Trace 页面或接口。</div>
    </div>

    <div class="section-kicker">Must Deliver</div>
    <h2 class="section-title">今天必须产出的东西</h2>
    <div class="grid two">
      <section class="card">
        <h3>统一入口</h3>
        <ul class="list">
          <li><code>source=user_message</code> 与 <code>source=schedule</code> 都能进同一入口。</li>
          <li>请求返回 <code>run_id</code>、<code>selected_agent</code>、<code>route_reason</code>、<code>permission_level</code>。</li>
          <li>返回结果要能被前端直接展示。</li>
        </ul>
      </section>
      <section class="card">
        <h3>权限与路由</h3>
        <ul class="list">
          <li>查询类走 User Agent，定时风险类走 Hermes。</li>
          <li><code>approval_required</code> 只返回确认，不直接执行。</li>
          <li><code>forbidden</code> 直接阻断，不调下游 Agent。</li>
        </ul>
      </section>
      <section class="card">
        <h3>能力与工具调用</h3>
        <ul class="list">
          <li>只查询 active 技能 / MCP / 任务。</li>
          <li>禁用能力不允许被调用。</li>
          <li>每次工具调用都能落 <code>AgentToolCall</code>。</li>
        </ul>
      </section>
      <section class="card">
        <h3>Trace 与降级</h3>
        <ul class="list">
          <li>Trace 能串起语义解析、路由、工具调用和最终结果。</li>
          <li>外部 MCP 失败要返回降级说明，不让前端拿到不可读错误。</li>
          <li>异常都要写进 <code>AgentRun.error_message</code>。</li>
        </ul>
      </section>
    </div>

    <div class="section-kicker">Acceptance Snapshot</div>
    <h2 class="section-title">验收快照</h2>
    <div class="table-like">
      <div class="row"><div class="row-label">路由结果</div><div class="row-value">同一句风险检查，在用户入口和任务入口会有不同路由结果。</div></div>
      <div class="row"><div class="row-label">权限边界</div><div class="row-value">“直接上线规则”和“直接付款”都不会被自动执行。</div></div>
      <div class="row"><div class="row-label">日志完整度</div><div class="row-value">每次运行至少有一条 <code>AgentRun</code>，工具调用有 0 到多条 <code>AgentToolCall</code>。</div></div>
      <div class="row"><div class="row-label">可观察性</div><div class="row-value">前端或 curl 可以完整看到一次运行链路，不需要直接查数据库猜过程。</div></div>
    </div>

    <div class="section-kicker">Common Misses</div>
    <h2 class="section-title">这一天最容易漏掉的点</h2>
    <ul class="list">
      <li>把权限判断放到 User Agent / Hermes 内部，导致系统没有统一边界。</li>
      <li>只记录成功 ToolCall，不记录失败 ToolCall，后面降级和排错会缺证据。</li>
      <li>路由能跑，但没有统一 Trace 输出，Day 7 演示时会非常难讲清链路。</li>
    </ul>

    <div class="footer">Day 4 的价值是把系统从“有很多零件”变成“有一条统一运行链”。</div>
  </div>
</body>
</html>