GPU_GUARD_MONOREPO/docs/code-wiki/entities/agent-runtime.md

---
title: Agent 运行时
created: 2026-04-13
updated: 2026-04-23
type: entity
tags: [runtime, agent, llm, backend]
sources: [packages/backend/src/modules/netaclaw/service/chat_orchestrator.ts, packages/backend/src/modules/netaclaw/session-tree/, packages/backend/src/modules/netaclaw/runtime/, packages/backend/src/modules/netaclaw/service/tool_resolver.ts, packages/backend/src/modules/netaclaw/subagent/]
---

# Agent 运行时

Agent 运行时是 NetaClaw 对话执行链路的核心。当前实现已经从“线性消息 + 单次 runAgent 调用”升级为“Session Tree 快照 + ChatOrchestrator 编排 + ToolResolver/Manifest 治理 + Subagent Worker”的组合架构。

它同时负责：

- 维护会话树、活动路径和运行时上下文，详见 [[session-tree-runtime]]。
- 按 Agent 配置、模型能力、治理策略解析最终可用工具，详见 [[tool-governance]] 和 [[tool-runtime-policy]]。
- 构建 Prompt、执行 ReAct 循环、流式返回 token/thinking/tool 事件。
- 在主 Agent 与子 Agent 之间聚合委派结果，详见 [[subagent-session]]。
- 将快照和增量事件推送给前端，详见 [[websocket-gateway]] 和 [[frontend-architecture]]。

## 关键文件

| 文件 | 职责 |
| --- | --- |
| `service/chat_orchestrator.ts` | 对话主编排：创建会话、追加用户/助手节点、驱动运行、写回结果 |
| `session-tree/provider.ts` | Session Tree provider 抽象 |
| `session-tree/mysql_provider.ts` | MySQL 持久化 provider |
| `session-tree/file_provider.ts` | 文件持久化 provider |
| `session-tree/context_builder.ts` | 从 active path 构造模型上下文 |
| `runtime/agent.ts` | ReAct 循环执行入口 |
| `runtime/prompt_builder.ts` | Prompt Builder 分层注入 |
| `service/tool_resolver.ts` | 工具治理、Agent 覆盖、运行时诊断投影 |
| `tools/manifest.ts` | 工具 manifest 和 worker routing 基础画像 |
| `tools/runtime_policy.ts` | Subprocess worker policy 与工具路由状态推导 |
| `subagent/process_runner.ts` | 子 Agent 独立进程 runner |
| `subagent/process_protocol.ts` | 子进程 JSONL 事件协议 |

## 当前运行链路

```text
用户输入
  -> ChatOrchestrator 接收
  -> SessionTreeProvider 创建或恢复 session
  -> appendMessage(user) 写入会话树
  -> SessionTreeContextBuilder 读取 active path
  -> ToolResolver 生成 toolNames / disabledReasons / runtimeDiagnostic
  -> Prompt Builder 注入工具、记忆、技能、压缩摘要
  -> runAgent 执行 ReAct 循环
  -> 工具调用经 ToolResolver 提供的工具实例执行
  -> 如触发 delegate_task/delegate_parallel，进入 SubagentService
  -> appendEntry 写入 message、compaction、subagent_batch、subagent_result 等节点
  -> WebSocket 推送 snapshot/patch/event
  -> 前端 chat store 按 active path 渲染
```

## 与旧实现的关键区别

旧实现偏向按 `netaclaw_message` 的线性历史恢复对话。现在的运行时以会话树为主轴：

- `activePath` 决定当前模型上下文，而不是简单取全量消息列表。
- `leafEntryId` 表示当前分支叶子，支持分支、重置 leaf、派生 session。
- `compaction`、`branch_summary`、`label`、`session_info`、`subagent_batch`、`subagent_result` 都是树节点，而不是散落在消息 metadata 里的附属状态。
- 前端刷新后通过 session tree snapshot 恢复历史，不依赖浏览器 localStorage 存完整消息。

## 工具运行时

Agent 运行时不直接相信静态工具列表。最终工具集由 [[tool-governance]] 统一裁决：

- 全局工具状态来自 `netaclaw_tool` 和 catalog 同步。
- Agent 编辑页可以保存 `tools.enabled`、`tools.disabled`、`toolOverrides`、`subagentConfig.allowedToolNames` 等局部配置。
- 后端输出 `runtimeDiagnostic`，前端工具管理页、Agent 编辑页、对话页应使用同一份投影。
- 子 Agent 的工具还会经过 [[tool-runtime-policy]] 推导，区分 `worker-local`、`main-process-proxy`、`disabled`。

## 子 Agent 运行时

主 Agent 通过 `delegate_task` 或 `delegate_parallel` 发起委派后，`SubagentService` 会根据配置构造受限 Agent，并优先走独立 worker 进程执行。子进程通过 JSONL 协议向父进程上报：

- `run_start`
- `token`
- `thinking`
- `tool_call`
- `tool_result`
- `proxy_tool_call`
- `run_end`
- `run_error`

需要主进程能力的工具会通过 `proxy_tool_call` 回到父进程执行，避免子进程直接持有所有写入、记忆、技能管理权限。详见 [[subagent-session]] 和 [[tool-runtime-policy]]。

## 前端消费方式

前端 `agent/store/chat.ts` 现在围绕 session tree snapshot 工作：

- 保存最近 session/agent 的轻量指针到 localStorage。
- 通过 snapshot 恢复 `sessionMeta`、`entries`、`childrenByParentId`、`activePathIds`。
- `visibleEntries` 渲染 message、branch summary、compaction、custom message、subagent batch/result。
- 工具渲染统一通过 `projectToolRender` 和工具 renderer registry。

这意味着“刷新后历史看不到”一类问题应优先检查后端 session tree provider、session id 恢复、snapshot 加载，而不是把完整对话塞进浏览器 localStorage。

## 相关页面

- [[session-tree-runtime]]
- [[tool-runtime-policy]]
- [[tool-governance]]
- [[tool-system]]
- [[subagent-session]]
- [[context-compaction]]
- [[prompt-builder]]
- [[frontend-architecture]]
- [[websocket-gateway]]
- [[netaclaw-module]]

## 2026-04-22 Subagent Replay

The Agent runtime persists subagent evidence and process replay through session tree entries instead of transient chat state.

- `SubagentService` collects worker process events and writes projected events into `resultPayload.processEvents`.
- `ChatOrchestrator` aggregates completed task data into `subagent_result.metadata.processEvents` and `subagent_result.metadata.evidenceSummaries`.
- `SessionTreeProvider.getSnapshot()` is the refresh boundary: after page reload, the frontend should recover subagent evidence cards and replay timeline from `subagent_result` entries in the snapshot.
- These metadata fields are intentionally excluded from `runtimeContext.messages` so refresh/replay UI data does not contaminate the next LLM prompt.

## 2026-04-23 Canonical Projection Boundary

这一轮更新后，Agent runtime 对子 Agent 回放数据的口径进一步收敛：

- `gateway/session.ts` 在返回 `getSnapshot()`、`switchLeaf()`、`appendSubagentResultEntry()` 等结果前，会统一调用 `projectSubagentSnapshot()` / `projectSubagentEntry()`。
- `session-tree/subagent_projection.ts` 负责把 `subagent_result`、历史 tool message 或旧 metadata 中的委派结果整理为 `metadata.subagentProjection`，这才是前端首选的 canonical UI projection。
- projection 会生成 `taskPanels`、`toolExecutions`、`evidenceSummaries`、`processEvents` 和 `diagnostics`，并做数量裁剪，避免把整份原始 payload 直接暴露给 UI。
- 前端保留对旧 payload / metadata 的解析能力只是为了兼容历史会话；当前代码路径应优先依赖后端生成的 `subagentProjection`，而不是在页面里重复拼装结果。
- 这意味着“子 Agent 结果怎么展示”已经不再是纯前端约定，而是 Agent runtime 在 session 边界稳定输出的一部分契约。