hunjing/docs/architecture/agent-runtime.md

Agent 运行时

1. 运行模型

Conversation → Run → Turn → ModelCall / ToolCall → Message

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

2. 周天体系

运行层以周天为循环叙事，承接 Hunjing 旧版（main 分支）的小周天/大周天设计并补全其架构（决策见 ADR-023）：

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

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（登记于协议与稳定标识）。

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

四阶段评估：

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

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

3. 状态机

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. 单轮时序

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 规则见记忆与知识架构。

9. 多 Agent 编排

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，不得自动重试有副作用操作。