hunjing/docs/architecture/agent-runtime.md

# Agent 运行时

## 1. 运行模型

```text
Conversation → Run → Turn → ModelCall / ToolCall → Message
```

- 一个用户输入创建或继续一个 Run。
- 一个 Run 可包含多个 Turn。
- 一个 Turn 可包含多个模型 attempt 和并行 ToolCall。
- 每次重试、故障转移、`pause_turn` 续跑都创建新的 ModelCall 记录。
- 子 Agent 是独立 Run 或 ChildRun，必须引用父 Run，并继承更窄权限。

## 2. 周天体系

运行层以周天为循环叙事，承接 Hunjing 旧版（main 分支）的小周天/大周天设计并补全其架构（决策见 [ADR-023](../decisions/README.md#adr-023周天体系统一小周天闭环与大周天演化)）：

- **小周天**：一次 Run 从输入到答复或行动结果的可追踪认知闭环。上节 Run/Turn/ModelCall/ToolCall 分层即小周天的可追踪链路；闭环完成时记录完成信号（含归真、记忆候选与观测摘要的引用）。
- **大周天**：跨 Run 的角色自我评估演化循环（见 [ADR-018](../decisions/README.md#adr-018角色内驱力与大周天演化进入-10)），以 `BigCycle`（`cycle_`）为聚合根持久化，执行为一个受托后台 Run。

```mermaid
flowchart TB
  IN[run input] --> CTX[context assembly]
  CTX --> MT[model and tool turns]
  MT --> OUT[streamed output]
  OUT --> SIG[run completed signal]
  SIG --> ACC[signal accumulation]
  ACC -->|threshold or window or manual| TRIG[BigCycle triggered]
  TRIG --> P1[phase recall]
  P1 --> P2[phase evaluate]
  P2 --> P3[phase propose]
  P3 --> P4[phase submit]
  P4 --> REV[existing candidate review]
  REV --> EFF[approved evolutions]
  EFF --> CTX2[future context assembly]
```

### 2.1 小周天闭环

- 闭环链路：输入 → 上下文装配 → 模型/工具 Turn → 流式输出 → 观测记录（usage、工具轨迹、审计）→ 完成信号。
- 完成信号是小周天对大周天的唯一输出面：包含 Run ID、归真引用、产生的候选引用、token/费用与时间窗；不包含隐藏推理。
- 流式运转（增量、节流、事件序）由灵台引擎小周天模块（`hj_stream`）承载；触发条件与预算核算的确定性计算由洛书（`hj_plan`）承载。

### 2.2 大周天循环

`BigCycle`（`cycle_`，UUIDv7）聚合：触发条件快照、输入引用集（窗口内小周天 Run、记忆变化、时间窗）、阶段状态与阶段记忆（`_phase_memory`：每阶段输入输出摘要，供审计与幂等）、产物候选引用、预算与执行 Run 关联。状态机 `big_cycle_status`：`pending` → `running` → `completed`/`failed`（登记于[协议与稳定标识](../contracts/README.md)）。

触发条件为可配置阈值组合，逐角色设频率上限：累计小周天数、归真数量、记忆候选存量、距上次大周天时间窗、用户手动触发。

四阶段评估：

| 阶段 | 职责 | 产物 |
| --- | --- | --- |
| 回顾（recall） | 拉取窗口内小周天完成信号与归真结果 | 输入引用集与阶段记忆 |
| 对照（evaluate） | 以内驱力维度对照当前道体基线与关系状态 | 差异与演化方向摘要 |
| 提议（propose） | 生成记忆、人格、关系、世界认知与次生目标候选（含叩心候选） | 携带 `big_cycle` 来源的候选集 |
| 提交（submit） | 候选进入既有审核流转，cycle 关闭 | 审核引用与演化谱系 |

经审核生效的演化（人格版本、关系、记忆）进入后续小周天的上下文装配（第 7 节顺序的第 2、4 层），形成"小周天运转 → 大周天评估 → 演化生效 → 影响后续小周天"的增益闭环。约束：大周天执行是受托后台 Run，不形成第二个角色身份；守一、预算受控、候选先于写入与用户可关闭原则见 ADR-018。

## 3. 状态机

```mermaid
stateDiagram-v2
  [*] --> queued
  queued --> running
  running --> waiting_approval
  waiting_approval --> running : approved
  waiting_approval --> cancelled : denied or expired
  running --> completed
  running --> failed
  running --> cancelled
  completed --> [*]
  failed --> [*]
  cancelled --> [*]
```

## 4. 单轮时序

```mermaid
sequenceDiagram
  participant C as Client
  participant A as API
  participant R as Runtime
  participant M as Model Adapter
  participant P as Policy
  participant T as Tool Runtime
  participant O as Observability

  C->>A: user message
  A->>R: create or continue Run
  R->>O: run.started / turn.started
  R->>M: model request
  M-->>R: text and tool_use blocks + usage
  R->>O: model.request.completed
  alt no tool call
    R-->>A: final message stream
  else tool call
    R->>P: decide capability and risk
    alt approval required
      P-->>C: approval request
      C-->>P: allow or deny
    end
    P->>T: execute allowed calls
    T-->>R: tool results
    R->>M: continue with all tool results
    M-->>R: final response + usage
  end
  R->>O: turn.completed / run.completed
  R-->>C: final event
```

## 5. 模型调用规则

- 业务只使用逻辑模型和能力需求；Adapter 决定上游协议和模型 ID。
- 请求前保存 `context_snapshot` 清单和不可逆摘要，不默认保存完整拼接 Prompt。
- 流式输出以最终固化 Message 为权威；delta 是临时事件。
- 记录上游 request ID、开始时间、首 token、结束时间、stop reason 和真实 usage。
- `input_tokens + cache_creation_input_tokens + cache_read_input_tokens` 才是总输入规模。
- Provider 未提供 token 时 `usage_source=unavailable`；估算值必须标记为 `gateway_estimate`。
- Provider 原生 Prompt Cache 与平台响应缓存是两个概念，字段不得混用。

## 6. Tool Use 规则

- `tool_use.id` 与 `tool_result.tool_use_id` 必须一一对应。
- 同一模型响应中的并行工具先全部执行，再以一个用户工具结果消息返回。
- 工具入参先按 JSON Schema 校验，再交给 Policy。
- 工具失败返回结构化 `is_error`，不能丢弃失败后假装没有调用。
- 副作用工具必须有幂等键；重试前检查已有结果。
- 工具结果先作为带来源的观察，经过大小限制、脱敏和内容安全处理后才能进入后续上下文。
- 行动自主性分级 `autonomy_level`（登记于契约）：自省（无外部后果的内部整理，可自动执行）、循律（既有授权内执行）、请命（需确认）、禁域（拒绝）；分级由 Policy 按能力、数据、后果、情境四维判定。
- Skill 与工具只提供受限工作方法：与角色基线、用户当前指令、关系边界或 Policy 规则冲突时必须让位，不得以"技能惯例"扩大权限。

## 7. 上下文装配

稳定顺序：

1. 可用工具定义；
2. 系统与角色稳定指令；
3. 当前路径消息；
4. 获准记忆和知识；
5. 动态运行上下文；
6. 当前用户输入。

Prompt Cache 依赖字节级前缀一致。工具和系统稳定内容置前；时间、请求 ID、当前输入等动态内容置后。缓存命中只由 Provider usage 判定。

## 8. 记忆写入

记忆提取在 Message 完成后异步生成 MemoryCandidate；Candidate 经 Policy 与必要的人工确认后才能创建不可变 MemoryVersion。自动提取不能修改 `identity_baseline`，敏感资料、关系结论、高影响推断和第三方信息默认要求确认。完整的所有权、写入、纠正、召回和 ContextSnapshot 规则见[记忆与知识架构](memory-and-knowledge.md)。

## 9. 多 Agent 编排

```mermaid
flowchart TD
  C[Coordinator Run] --> P[Plan and Budget]
  P --> A1[Child Run A]
  P --> A2[Child Run B]
  P --> A3[Child Run C]
  A1 & A2 & A3 --> H[Structured Handoff]
  H --> V[Coordinator Verification]
  V --> F[Final Result]
```

- Coordinator 只在任务可独立并行、需要不同专长或上下文隔离时创建 ChildRun。
- ChildRun 使用独立上下文与事件流，共享文件/对象必须通过显式资源授权。
- 深度、并发、总 token、费用、墙钟时间和工具调用数由 RunBudget 硬限制。
- 子 Agent 的插件、工具、网络、设备和数据范围是父权限的交集子集。
- Handoff 包含结论、证据 ID、产物 ID、未完成项、错误和 usage，不传隐藏推理。
- 角色 Agent 的后台子 Run 不形成第二个角色身份，也不能独立演进关系或人格。
- 用户可以查看、暂停、取消单个 ChildRun 或整个协调 Run。

## 10. 取消与恢复

- 取消信号传播到模型流、工具执行和子 Run。
- 已产生的部分文本标记为 `interrupted`，不作为完成答复。
- 服务重启从持久化状态恢复；等待审批的 Run 不因 Worker 更换丢失。
- 无法证明工具是否执行时，状态为 `unknown_outcome`，不得自动重试有副作用操作。