> For the complete documentation index, see [llms.txt](https://tinyhumans.gitbook.io/openhuman/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tinyhumans.gitbook.io/openhuman/zh/kai-fa/architecture/agent-harness.md).

# 代理执行器

代理一次运行是如何进行的：工具调用循环、子代理分发、原型、分诊、钩子，以及围绕它们的成本和预算机制。

`crates/openhuman-core/src/agent/` 是智能体轮次的宿主端。TinyAgents 负责通用的工具调用循环、调用解析、会话身份与对话记录重放，以及可复用的轮次运行器机制。OpenHuman 则将这些基础机制适配到产品策略和宿主端口：提供方选择、访问控制与审批、会话持久化、子智能体的产品行为、中断策略和成本核算。TinyChannels 负责提供方实现，以及规范的强类型通道和 Web 事件契约。

## 将 OpenHuman 嵌入为库

`openhuman_embed` 提供两步式 API。 `Runtime::builder()` 为每个进程启动一个进程内核心、后台服务、已注册的领域系列、后端 URL 和 TinyHumans API 密钥；而 `Runtime::agent(spec)` 则可在其上实例化任意数量的智能体。每个 `AgentSpec` 都完整描述一个智能体：提供方端点和模型、访问级别、 `action_dir`、MCP 服务器、自有进程内工具、技能包、系统提示词、工具范围、沙箱模式、允许列表，以及范围更窄的 `DomainSet` / `ToolGroups`。运行时的身份标识为 `HostKind::Library`：推理不依赖 OpenHuman 应用登录；工作流智能体节点的推理就绪检查也不例外。

### 嵌入方自己的工具

`AgentSpec::tools` 接收宿主自己的 `Box<dyn Tool>` 对象。这些对象会作为真正的工具提供给模型，在传输内容中携带各自的架构，并以各自的名称调用。在此功能出现之前，唯一的途径是 `AgentSpec::mcp`，这会让模型为间接调用付出代价：先发起发现调用以了解服务器提供哪些功能，再使用一个 `mcp_call_tool` 封装；其内部的 `arguments` 对象无法由任何提供方验证，也无法据此约束解码过程。

它接收的是工厂，而不是一整套工具。 `Agent` 实现了 `Clone` ，而 `Box<dyn Tool>` 并未实现；此外，每轮都会根据 `Config` 重建规范背后的会话，因此任何持有 `dyn Tool` 的对象都无法在轮次之间保留下来。因此，该闭包每轮运行一次。这也意味着，如果宿主的工具生命周期短于智能体（例如仅存在于一个剧集、一个房间或一项任务中），就可以每次返回不同的一组工具，而不必再注册一个智能体。

通过 `Tool` 实现 `openhuman_embed::Tool`，不要直接依赖 `tinytools` ：通过另一条路径依赖该 crate 会产生不兼容的 Rust 类型，因此基于它构建的工具根本无法传递给会话。

关于工具集会变化的一点注意事项。提示词中的工具目录与工具集在同一次构建中生成，因此在任何会组合提示词的轮次中，两者都保持一致。但恢复会话时会重用已持久化的系统消息，因此，如果长期运行的对话线程中的工具集发生变化，提示词仍会描述该线程开始时的工具集。只有在使用独立会话运行的轮次中，才应更换工具集。

每个智能体的隔离是通过上下文实现的，而不是另建一个核心。 `Runtime::agent` 克隆运行时的基础 `Config`，应用规范，并派生一个子项 `CoreContext` (`CoreContext::derive_with`)，其中携带该配置、代理的域名集合、工具组和技能根目录策略。每一轮都会在该上下文中分派（`CoreRuntime::run_in` → `agent_chat_for` 并显式传入 `AgentDefinition`），因此配置加载器、域名门控、工具组筛选器和技能发现机制读取的都是该代理自己的设置。对话记录以代理 ID 为键，每一轮只会恢复该代理自己的会话线程。

运行时自有根目录下的目录布局： `<root>/config.toml` 和凭据存储； `<root>/workspace/` 其中包含会话数据库、 `session_raw/` 对话记录，以及每个代理的 `agents/<id>/skills/`；还有 `<root>/agents/<id>/action/` 作为每个代理的默认工作根目录（与 workspace 同级，绝不位于其中）。

`Harness` 是单代理用法的简写：一个运行时加一个名为 `harness`的代理。构建一个运行时，并在其代理上并发调用 `run` 或 `turn(...).send()` ；不要为每个代理单独构建一个 core。每次调用都会拥有独立会话，除非提供了先前的会话 ID。

库模式下使用 TinyHumans API 密钥进行身份验证（`RuntimeBuilder::api_key`），并以 `api-key` 身份验证配置的形式存储在运行时的 `config.toml`旁边。托管推理会将其作为 bearer 凭据发送到兼容 OpenAI 的端点；后端 REST 调用则发送 `x-api-key`；没有会话 JWT，也无需担心过期。自行指定 `Provider` 的代理（BYOK）不会使用该密钥。该密钥适用于所有托管功能，具体受后端作用域限制：推理、嵌入、语音、搜索、媒体、Composio 及其他集成、渠道和套接字。只有与会话绑定的 `/auth/*` 流程（OAuth 连接、渠道链接令牌）仍需使用 `HarnessBuilder::session`.

`Workspace::Inherit` 与 `Provider::inherit()` 搭配使用且不提供 API 密钥，并不意味着推理会经由库路由。它会借用已安装的 OpenHuman 配置，因此仍会进行已安装应用的会话检查。嵌入时若不使用应用登录，请提供显式的 provider 或 API 密钥。

有些设置对所有代理仍是运行时级别的（实时自主策略的 `auto_approve*`、审批门控开关、子代理目录、配置子代理重读）；crate README 在“仍为运行时级别”一节中列出了这些内容。

每轮代理运行都会经过已发布的 [`tinyagents`](https://crates.io/crates/tinyagents) 运行框架。共有三个入口： `Agent::turn`、通道和 CLI 总线路径，以及 `run_subagent`。它们都会经过位于 [`crates/openhuman-core/src/agent/tinyagents/`](https://github.com/tinyhumansai/openhuman/tree/main/crates/openhuman-core/src/agent/tinyagents/README.md) (`TurnSpec::run`）。上下文裁剪由 `MessageTrimMiddleware`负责，取消则通过 tinyagents steering 通道处理。策略停止钩子（预算、线程目标和迭代次数上限）使用上游的 `tinyagents-hooks` `StopHookMiddleware` ，并在首次收到停止投票时暂停运行。Web 聊天的接入和排队机制使用 TinyAgents 的 `TurnRunner`；OpenHuman 的 `web_chat` 宿主负责提供入口接入、会话检出、审批、持久化和终端事件策略。通道提供方传输，以及类型化 Web 事件的架构和投影，由基于 TinyBus 的 TinyChannels v2 模块提供。OpenHuman 会在其进程事件总线上发布这些规范事件，并仅保留宿主路由元数据。共享的 `TurnProgress` 接口位于 `agent/session_host/tool_progress.rs`.

TinyAgents 的 `tinyagents-orchestration` crate 负责与宿主无关的子代理生命周期。OpenHuman 提供用于生成策略、持久会话解析、取消、进度和完成通知的产品适配器。多代理编排运行在 TinyAgents 图层上，经由 `tinyagents-orchestration`的 `parallel` 模块、宿主的 `spawn_parallel` 适配器，以及从 `graph::orchestration` `TaskStore` 重新导出的生命周期基元 [`orchestration/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-core/src/agent/orchestration/mod.rs)。当前宿主接口见 [编排职责归属图](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-core/src/agent/orchestration/README.md); [`spawn_subagent_host_impl.rs`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-core/src/agent/orchestration/tools/spawn_subagent_host_impl.rs) 会将子运行绑定到其调用方的执行上下文：

* OpenHuman 的子代理适配器、取消、进度和面向 UI 的投影，详见 [编排职责归属图](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-core/src/agent/orchestration/README.md)；通用图和任务执行由 TinyAgents 负责。
* 工作流阶段引擎会将每个阶段的代理分派到图上并行运行（`with_max_concurrency`）。持久化的 `WorkflowRun` 账本仍是恢复执行的事实来源。
* `spawn_parallel_agents` 通过宿主的 `spawn_parallel` 适配器，基于 `tinyagents_orchestration::parallel`.
* 分离子代理注册表由类型化的 `TaskStore` 生命周期账本提供支持（Pending、Running，然后是 Completed、Failed 或 Cancelled）。

## TinyAgents crate：功能与兼容性

OpenHuman 通过路径依赖使用拆分后的 TinyAgents crate 系列，这些 crate 位于 vendored git 子模块 `vendor/tinyagents`中，包括 `tinyagents-harness` （功能 `multimodal`, `builtin-tools`), `tinyagents-definition`, `tinyagents-registry`, `tinyagents-session`, `tinyagents-runtime`, `tinyagents-orchestration` 以及可选的 `tinyagents-live`，还有 `tinyinference` ，来自 `vendor/tinyagents/vendor/tinyinference`，因此可以在代码库内测试 SDK 变更，再将其上游提交（参见 [`crates/openhuman-core/Cargo.toml`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-core/Cargo.toml)）。TinyFlows 负责工作流图检查点及其 `graph.*` 存储架构。这样做的原因如下，确保未来升级不会导致回归：

* 采用原生 TinyAgents 模型接口，产品策略由 OpenHuman 负责。每条实时路由都是一个 `Arc<dyn ChatModel<()>>`：TinyAgents 的 OpenAI 兼容客户端涵盖在线协议等效的托管、本地和 BYOK 路由，而主机端 `ChatModel` 实现则涵盖 Claude SDK/Code 和 Codex 专用传输方式。OpenHuman 仍负责凭据解析、OAuth、访问控制、端点选择、出站数据披露、账单元数据和错误分类。
* OpenHuman 持久化采用一条原生 SQLite 依赖链。OpenHuman 根目录和 Tauri Cargo 环境固定使用 `rusqlite = "=0.40.2"` (`bundled`）；固定的 Rust 1.99 工具链（1.96 或更高版本）提供其构建脚本所需的 `cfg_select!` 宏。两个环境最终都解析为单一的 `libsqlite3-sys` 依赖链。TinyFlows 通过其驱动程序自有的检查点器和架构持久化工作流检查点。
* WhatsApp Web 位于 TinyChannels 模块（`tinychannels/whatsapp-web`）中，而不在 OpenHuman 中。OpenHuman 没有 `whatsapp-web` 功能，也没有 `whatsapp-rust` 或 `wacore` 常规依赖图中的依赖项。该模块的存储桥接层记录在 tinychannels 仓库中。
* 没有脚本运行时。这里没有 `repl` 或 Rhai 脚本功能，也没有 `rhai_workflows` 工具。Rhai 仍是 `tinyflows` 的依赖项，用于其自身的 JSON 查询栈，与智能体执行框架无关。
* 所有权映射：模型构建 → `inference::provider::create_chat_model*`；工作流检查点 → TinyFlows 的驱动程序架构；通用分离执行器状态 → `DetachedTaskRegistry`；面向控制器的持久化 → OpenHuman SQL/JSON 运行记录（`running_subagents`, `workflow_runs`, `agent_teams`, `command_center`）。通用执行框架／中间件／事件原语直接使用，不作修改。

智能体执行框架会将用户消息、webhook 事件或 cron 定时触发转换为完整的工具交互流程。TinyAgents 负责通用循环和可复用的执行原语。OpenHuman 提供特定于产品的子智能体与触发器工作流、策略钩子和宿主能力。提供商传输和渠道规范化由 TinyChannels 负责；工具实现、提示组装和记忆存储则由各自所属的领域负责。

本页将先介绍一轮交互中的处理过程，然后逐一深入讲解各个组成部分。

## 一轮交互的流程

无论用户刚输入一条消息、Telegram webhook 被触发，还是上午 9 点的 cron 定时任务启动，每一轮交互都会经历相同的生命周期：

消息渠道的入口由配置的 TinyChannels v2 模块通过类型化总线操作和共享线路类型进行准备。OpenHuman 执行账户授权和宿主策略，然后提供 TinyAgents 会话与对话记录机制所用的持久化接口。TinyAgents 负责通用轮次执行、会话身份、对话记录重放和可复用的轮次运行器。提供商传输、规范化以及规范化 Web 输出投影由 TinyChannels 负责；OpenHuman 则负责账户授权、审批、会话和投递策略，以及宿主适配器和持久化实现。

```
┌─ 入站 ─────────────────────────────────────────────────────────┐
│ 用户消息 · 渠道入站 · webhook · cron · composio 事件 │
└──────────────────────────┬────────────────────────────────────────┘
                           │
                           ▼  （仅限外部触发）
                ┌──────────────────────┐
                │   触发器分流         │  分类 → 丢弃 / 通知 /
                │   （小型本地 LLM）   │  启动 reactor / 启动 orchestrator
                └──────────┬───────────┘
                           │
                           ▼
            ┌──────────────────────────────┐
            │      Agent::turn()           │
            │  1. 恢复对话记录             │
            │  2. 构建系统提示*            │
            │  3. 召回记忆包               │
            │  4. 进入工具调用循环 ────────┼──► 提供商调用
            │  5. 分发工具调用 ────────────┼──► 工具执行 / 启动子智能体
            │  6. 上下文保护 / 压缩         │
            │  7. 停止钩子检查             │
            │  8. 最终助手文本             │
            └──────────┬───────────────────┘
                       │ 异步执行，在用户看到回复后
                       ▼
              ┌─────────────────┐
              │  轮次后处理     │  成本日志 · 对话
              │  钩子           │  缓冲记忆数据
              └─────────────────┘

* 系统提示词仅在第一轮构建。之后的
  轮次会原样复用渲染后的提示词，因此推理
  后端的 KV 缓存前缀仍然有效。
```

本页其余部分是同一张图的展开说明。

## 会话与 `Agent::turn`

会话是一个正在运行的 `Agent` 实例所持有的实时对话。该 `Agent` 结构体拥有：

* 对话历史（系统、用户、助手和工具消息）。
* 要调用的提供方客户端（模型由 [模型路由器](/openhuman/zh/gong-neng/model-routing.md)).
* 模型可见的工具注册表。
* memory `memory` 工具（启用记忆引擎时），模型可通过它按需回忆、检索、学习和遗忘。
* 每轮预算：最大工具迭代次数、最大负载大小、最大美元成本。
* 本地操作预算：滚动的每小时副作用工具操作上限，读取自 `config.autonomy.max_actions_per_hour`.

`Agent::turn(user_message)` 是核心执行路径。单轮中，它会：

1. 如果这是一个新进程，则恢复会话记录，从磁盘重新加载精确的提供方消息，以确保推理后端的 KV 缓存前缀仍然命中。
2. 构建系统提示词（仅在第一轮构建）。此步骤会通过提示词分段构建器汇集身份、灵魂、个人资料、记忆、已连接的集成、可用工具和安全前言。
3. 回忆一组记忆。TinyMemory 的智能体生命周期会记录用户轮次，并回忆一组受令牌预算限制的内容（学习所得和信念、大脑文档、本智能体的历史记录、其他智能体的轮次），将其包装在 `<memory-context>` 中，并临时添加到该轮对模型的请求中；它绝不会持久化到对话记录中，因此不会影响提示词缓存。模型仍可调用 `memory` 工具来生成带引文的回答（参见 [记忆架构](/openhuman/zh/kai-fa/architecture/memory.md)).
4. 进入工具调用循环（下一节）。
5. 在后台启动轮次结束后的钩子：用户会先收到回答，之后才完成成本记录和对话记录。

后续轮次不会重新构建系统提示词。即使只是外观上的字节变化，也会使 KV 缓存前缀失效并强制完整重新预填充，因此每轮动态上下文（工具结果、记忆回忆结果）会作为用户可见的消息内容追加，而不是插入系统提示词。

#### 可缓存的前缀范围比系统提示词更广

冻结提示词只是这项约定的三分之一，另外两项更容易被破坏，因为它们看起来都不像缓存相关内容：

* 工具区块也会计入，而且它排在 *前面*。生产环境中的所有前缀缓存都会在对话之前渲染工具目录；聊天模板必须将其放在模型读取第一轮用户消息之前的位置。OpenAI 的自动缓存、Anthropic 的 `cache_control` （工具 → 系统 → 消息）、DeepSeek 的上下文缓存，以及任何 vLLM/SGLang 基数缓存都采用这种方式。因此，如果每轮之间发生变化， `tools` 数组也会使冻结的系统提示词失效，而请求体的 JSON 键顺序（它会将 `messages` 放在 `tools`之前）对此毫无说明。会话中途的 Composio 协调仍然是正确的做法；对工具能力的描述若与模型实际可调用的能力不符，比冷启动预填充更糟。但只有能力确实发生变化时才应触发协调；除此之外，内容必须保持字节级稳定。 `connected_set_hash` 会在哈希前排序，因此后端响应顺序变化不会触发重建； `collect_orchestrator_tools` 也会出于同样的原因对已连接工具包枚举值排序。
* 历史记录必须只追加。第 N 轮的序列化内容必须原样保留，并作为第 N+1 轮的开头。 `pair_tool_cycles` 会在序列化时丢弃未完成的工具调用周期，因此对某条记录的判定必须只取决于该记录及其紧邻的下一条记录，绝不能受之后追加的内容影响；否则，较早消息是否存在会被追溯性地改变，前缀也会因此移出缓存。上下文压缩是唯一有意为之的例外：它会重写中间部分，并承担重新预填充的成本。

恢复会话时，重放的前缀会并入 `Agent::history` 而不是拼接到单个请求中，因此请求、后续轮次和持久化的对话记录读取到的都是同一序列。拼接的做法让对话付出了双重代价：下一轮请求没有带上该前缀，而之后写入的对话记录（从 `history`序列化）也只包含新一轮内容；于是 *下一次* 恢复时读回的仍是这份记录，每次重启都会让对话线程再缩短一些。

#### 只有在线路上明确标示，稳定前缀才能发挥作用

保持字节稳定是必要条件，但还不够：还必须 *告知* 提供商进行缓存，而且有两家提供商需要显式告知。

* Anthropic 若没有 `cache_control` 标记，就不会缓存任何内容；其 OpenAI 兼容端点也无法携带这些标记。Anthropic 文档说明，该路径不支持提示缓存，并且报告的 `prompt_tokens_details` 始终为空。因此， `cloud_providers` 中 `auth_style = "anthropic"` 的条目会构建为 crate 原生的 Messages 适配器（`tinyinference_llm::providers::anthropic`），它会在最后一个工具、最后一个系统块和最后一条消息上放置标记，使不断增长的工具调用循环能够复用上一轮迭代的缓存，而不只是缓存系统提示。唯一的例外是文本模式（`native_tools = false`，由提示引导的工具）：只有 Chat Completions 适配器实现了这种模式，并且它会保留兼容客户端，因此仍需支付全额费用。
* OpenRouter 会将标记转发给 Anthropic 和 Gemini，但不会自行添加标记；托管版 OpenAI 会拒绝未知的内容部分字段。OpenRouter 的 slug（以及任何位于 `openrouter.ai`上的端点）会启用 `OpenAiModel::with_explicit_cache_control`，为最后一条系统消息和最后一条用户消息添加标记；其他所有 Chat Completions 端点都不会添加标记。
* 路由提示与标记彼此独立。harness 会根据声明的稳定前缀生成 `prompt_cache_key` ，并将其放入 `provider_options`，这样对话线程的每一轮，以及共享系统提示和工具集的每个子代理，都会被路由到支持分片的提供商上的同一缓存分片（OpenAI 的 `prompt_cache_key`）。没有这类概念的适配器会丢弃该字段。托管后端会将它作为顶层请求体字段接收，与 `thread_id`.

并列。 `RunPolicy::cache.protect_prompt_prefix`是这三项设置的共同来源：主机无条件设置该字段；而可缓存前缀则由 tinyagents 循环根据会话冻结的系统前缀（系统提示层级，然后是工具目录）在每个请求中声明；主机本身没有为此设置任何中间件。在 tinyagents 开始将这一生效策略写入发出的请求之前，两个读取方都只会查看 `request.cache_policy` ，而这里的值始终是 `None` ，因此该标志仅用于诊断，标记或键从未真正发送到线上。现在，每次模型调用的 `[cache]` 调试日志行都会报告是否注入了键，以及声明了多少个可缓存片段； `cache_read_tokens` 是返回的用量数据中的指标，可据此确认缓存是否生效。

与其推测，不如实际测量。 `CAPTURE_ALL=1 node scripts/debug/capture-first-inference.mjs` 记录整个会话的请求， `scripts/debug/run-multi-turn-capture.mjs` 通过生产环境 RPC 驱动多轮对话，并且 `scripts/debug/audit-inference-prefix.mjs` 报告首次出现差异的位置并追溯其原因。单轮捕获无法发现这些问题；关键从来不是第 1 轮的开销，而是第 2 轮能否复用第 1 轮的内容。

### AGENTS.md 项目指令

除了身份、灵魂、个人资料和记忆之外，系统提示词还会加载 AGENTS.md 指令文件。它相当于 OpenHuman 版的 Claude Code `CLAUDE.md` / Codex 的 `AGENTS.md`。系统提示词构建时会加载以下两个层级（每轮不会重新读取，因此可确保前缀固定并遵守 KV 缓存约定）：

* 全局： `<workspace_dir>/AGENTS.md`，即用户的 OpenHuman 工作区（其中 `SOUL.md` / `USER.md` 位于此处）。适用于每次运行。
* 项目： `<action_dir>/AGENTS.md`，即智能体正在操作的文件夹。对于使用 git 工作树覆盖设置运行的子智能体（`SubagentRunOptions.worktree_action_dir`），该覆盖目录会作为项目层级。

全局层级先渲染，项目层级后渲染（项目指令优先，冲突时以其为准），并置于 `## Project instructions (AGENTS.md)` 标题下。如果两个目录解析到同一路径，则只加载一次（去重）。缺失、无法读取或为空的文件会被静默跳过；每个层级最多读取 `BOOTSTRAP_MAX_CHARS` （约 20,000 个字符），并附加 `[... truncated]` 标记，避免大文件挤占提示词空间。

加载器为 `agent::prompts::agents_md` （返回预加载字符串的纯函数；读取时会限制长度，避免异常的数 MB 文件在渲染阶段的长度限制生效前耗尽内存）；这些字符串会传入 `PromptContext` (`agents_md_global` / `agents_md_local`）中，并由 `AgentsInstructionsSection`渲染。该部分位于默认构建器和子智能体构建器中，处于用户文件部分之后、工具目录之前。主智能体／编排器智能体及其他内置动态智能体（`PromptSource::Dynamic`）会通过 `render_*` 辅助函数组装各自的正文，因此相同的 `AgentsInstructionsSection` 内容由 `SystemPromptBuilder::from_dynamic`集中注入，追加在智能体自身正文之后、中央 grounding 约定之前，而不是由每个 `agents/<id>/prompt.rs` 构建器分别注入。此功能由 `agent.agents_md_enabled` 控制（默认开启）；关闭时，不会加载或注入任何 AGENTS.md 内容。

## 工具调用循环

在 `Agent::turn`中，工具调用循环是内部引擎。它是已发布的 tinyagents crate 中的 `AgentHarness` 循环，由 `TurnSpec::run` ([`crates/openhuman-core/src/agent/tinyagents/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-core/src/agent/tinyagents/mod.rs)）在每轮中组装而成。它最多运行到本轮的迭代上限，该上限由 `session_host/builder/iteration_cap.rs`解析：显式设置的 `[agent] max_tool_iterations_override` （或 `OPENHUMAN_AGENT_MAX_TOOL_ITERATIONS`）优先，其次是智能体定义中的上限（编排器的上限为 200），最后是 `max_tool_iterations` （默认值为 10），适用于未定义智能体的轮次。当预算分别达到 50% 和 80% 时，模型会收到剩余调用次数的提示；而 `inference_agent_chat` 会通过以下内容报告触及上限的轮次： `hit_cap: true` 以及其 `checkpoint` 文本：

```
loop {
    1. 上下文防护     - 如果历史记录过大，则进行微型压缩/自动压缩
    2. 停止钩子检查   - 预算上限、最大迭代次数、自定义终止开关
    3. 调用提供方     - 发送消息和工具规范，并流式接收响应
    4. 解析响应       - 将助手文本与工具调用分开
    5. 没有工具调用时 - 返回最终文本
    6. 执行工具调用   - 分派各项调用（见下一节）
    7. 汇总超大输出   - 将超大的工具输出交由摘要智能体处理
    8. 附加结果       - 将工具结果加入历史记录，然后再次循环
}
```

每次迭代都会发出实时 `AgentProgress` 事件，以便 UI 逐 token 渲染流式输出、“正在调用工具 X”状态，以及每次迭代的成本更新。

一个引擎，三个入口。循环位于 TinyAgents 中。OpenHuman 的聊天主机、频道/CLI 路由和子智能体主机分别在适配器边界提供产品策略；生成的子智能体通过 `agent/subagent_host`进入，由中立的 `tinyagents_orchestration::subagent::SubagentDriver` 驱动，而不是由 OpenHuman runner 驱动。主机负责提供方/模型选择、工具与安全范围的收窄、工作区/产物处理、进度信息以及持久化的产品状态投影。中立驱动程序负责生命周期顺序、任务键合并，以及互斥的“暂停或终止”持久化决策。不存在 `harness/subagent_runner` 路径，也不得将其重新引入为门面或兼容性导出。

### 工具分派与工具调用方言

`agent.tool_dispatcher` （可通过 `OPENHUMAN_TOOL_DISPATCHER`在单次启动时覆盖）决定如何向模型传递工具信息。 `auto` （默认值）使用原生工具调用，通过 `ChatModel` 适配器会在提供方配置支持时回传结构化调用；对于本地 Ollama 等由提示词引导的提供方，则回退到 JSON-in-tag。 `python` 和 `typescript` 是可选启用的：它们会将工具目录渲染为代码签名，并回读代码风格的调用，但在某些模型上会解析错误。会话会为所选方言编写提示词，并在轮次执行器上固定使用相同方言，因此文本方言不会将其架构发送到线上，而执行器则会使用匹配的语法恢复调用。

规范的 `tinytools_agent::dialect::ToolDialect` 实现会直接提供与对话记录兼容的解析和渲染；OpenHuman 只在这些 I/O 边界转换持久化记录和提供方记录：

* 原生（`native`），结构化工具调用字段。
* XML（`xml`), `<tool_call>{...}</tool_call>` 标签位于助手文本中，提示词中包含完整的 JSON 架构。
* P-Format（`pformat`），紧凑的位置参数格式 `<tool_call>name[0|a|1|b]</tool_call>` ，并在提示词中提供 `name[0|<a>|1|<b>]` 签名；需选择启用。
* 代码（`python` / `typescript`），工具目录是函数签名列表（`def read_file(path: str, limit: int = None) -> str` 或 `function read_file(path: string, limit?: number): string;`），模型则在标签内编写函数调用： `read_file(path="src/main.rs", limit=20)` 或 `read_file({path: "src/main.rs", limit: 20})`。它与 P-Format 一样紧凑，但采用语法简单、经过代码训练的小型模型早已会用的形式； `python` 是默认选项。

所有文本方言共用一个解析器：先将 `<tool_call>` 主体按 P-Format 尝试解析，然后按代码调用解析，最后按 JSON 解析，因此即使模型混用多种形式，也能正确理解。持久化的会话历史可能包含上述任意形式的后缀，因此会话外壳会保留分派器，以便在恢复对话记录时忠实地解析并重放这些内容。

### 工具规则：允许、拒绝、隐藏、审批

你可以使用模式规则，限制代理能够看到和调用哪些工具。规则语言是 `tinytools::ToolRules`，tinyagents 循环通过 `RunPolicy::tool_rules`强制执行这些规则。一套规则会决定所有三个作用面：请求中的工具架构、 `tool_search` 及延迟加载的工具目录，以及所有调用（包括嵌套调用）。因此，被规则移除的工具无法通过搜索找到，也无法通过猜测名称来调用。

规则来自三个位置，并按层叠加。每一层都必须允许某个工具：

1. **`[tool_rules]` 位于 `config.toml`.** 运维人员的规则层，应用于每个代理，包括子代理。
2. **智能体定义。**
   * `disallowed_tools` 和 `tool_rules` 在定义 TOML 中。
   * `tool_rules` 在智能体注册表条目中， `agent.registry` 补丁可以设置它。
   * `AgentDefinitionSpec::tool_rules` 供嵌入方使用。
3. **子智能体。** 子智能体会继承操作者的各层规则，但不会继承其父智能体自身的限制，因为编排器通常会恰好禁止它委派出去的工具。随后，子智能体会添加其自身定义中的规则层。

```toml
[[tool_rules.rules]]
id = "only-github-mcp"
effect = "deny"                  # allow | deny | hide | require_approval | auto_approve
match = { name = "mcp_*" }       # name / family / tags 通配模式、category、exposure、
except = { family = "github" }   # permission bounds、side_effects、arg
reason = "Only the GitHub MCP server is approved."

[[tool_rules.rules]]
effect = "deny"
match = { name = "shell" }
when = { channel = "telegram" }  # 上下文：channel、agent
```

规则的行为：

* **优先级。** `deny` 在同一规则层内优先级最高。 `hide` 使工具仍可调用，但不在列表中显示。 `require_approval` 会延迟调用，其效果与工具声明 `approval_required`; `auto_approve` 会免除该声明的要求。
* **模式。** 通配模式支持 `*` 和 `?` ，并且不区分 ASCII 大小写，因此 `gmail_*` 可以匹配 `GMAIL_SEND_EMAIL`。定义中的名称列表（`disallowed_tools`）通过 `tools::rules::glob_list_matches`使用相同的语法。该函数现在是唯一的匹配器实现。
* **拒绝调用。** 拒绝的调用会返回规则的 id、层级和原因。

代码： `crates/openhuman-core/src/tools/rules/`。每个会话只会组合一次其规则层（`session_rule_set`）；每一轮都会在自己的上下文中评估这些规则（`OpenHumanRunContext::tool_rules`).

### 循环中的上下文管理

较长的工具调用链可能会超出上下文窗口。两层机制负责处理这一问题：

* 工具结果预算：每个工具结果都会根据单次调用的字节预算进行检查，并由 tinyagents 工具中间件强制执行。超出预算的内容会被硬截断，并附上说明标记，让模型知道自己看到的并非完整输出。
* 微压缩／自动压缩：当历史记录总量逐渐接近上下文窗口上限时，tinyagents 中间件（消息裁剪 + 安装在 `tinyagents/middleware.rs` 和 `tinyagents/context_wiring.rs`中的压缩钩子；阶梯顺序和大小由 `tinyagents-harness` `ContextLadder`负责管理）会在下次调用提供方之前，将较早的轮次压缩为摘要。压缩后的历史会保留系统提示和最近几轮的原样内容（以保持 KV 缓存稳定），并改写中间部分。除非 `[context] summarizer_model` (`OPENHUMAN_CONTEXT_SUMMARIZER_MODEL`）指定了其他模型，否则摘要由该轮自己的模型生成；该模型通过该轮的提供方路由调用，并使用相同的凭据和端点（`inference/turn_models.rs`）。每轮都会在 debug 级别记录所选模型，格式如下： `[context_compression] summarizer model=<id> source=config|turn`。摘要生成失败时会回退到确定性裁剪，而不是改用该轮的模型。

### 超大工具结果：摘要处理流程

有些工具调用会返回极大的负载：例如，Composio 操作导出 200 KB 的 JSON、网页抓取返回 50 KB 的 Markdown，或者 `file_read` 读取包含数千行的日志。若在负载中间硬截断，截断点之后的内容就会被丢弃。

当工具结果超过摘要器的阈值（`summarizer_payload_threshold_tokens`，默认值为 4 000）时，编译后的 TinyJuice 模块会决定是否在结果进入父级历史之前对其进行摘要。该模块负责提取提示、摘要缓存和按线程设置的失败熔断器，并将原始内容存入其 CCR 存储，以便 `juice_retrieve` 能够将其取回。主机负责调用模型，因为它了解模型和轮次上下文。 `ToolOutputMiddleware` 通过 `PayloadSummarizer::prepare`绑定当前轮次的一个一元子调用，在一次性 harness 上注册受限模型（`tinyagents/payload_summarizer.rs`），模块则通过类型化的 `tinyjuice-bus` `MlHost.Generate` 契约回调。只有编排器会携带摘要模型；即使关闭了压缩路由，它也始终能看到 `juice_retrieve`，因为摘要的页脚会注明这一点。凡是符合摘要条件但未能生成摘要的结果，都会标记为未摘要，无论失败发生在模块还是主机端，这样模型就不会因此重新运行工具。摘要复用和熔断器的作用范围限定为线程；如果没有线程，则限定为运行。若摘要失败，或者负载大到对其调用 LLM 在经济上不划算，下游仍会以硬截断作为最后一道保障。

压缩、CCR 存储与恢复、内容查询、HTML 提取，以及静态工具声明和线缆 DTO 均由 TinyJuice 和 `tinyjuice-bus`负责。OpenHuman 的工具是适配器：它们将类型化请求传递给模块，并将文件系统授权保留在主机侧。句柄查询会访问模块的 CCR 存储；工件查询则将经过授权的内容（而非路径）发送给同一个模块操作。主机没有并行的 CCR 存储，也没有本地算法回退方案。若模块不可用，必需的查询和提取操作会报告该操作不可用；可选的工具输出压缩则保持其文档所述的直通行为。即使当前设置不再创建新句柄，恢复的线程仍会保留其记录的 Juice 声明和架构；执行仍受当前策略和模块可用性约束。

调用方关注点。工具可以通过添加 `summary_focus` 参数选择加入此可选功能，方法是在其架构中添加 `tokenjuice::focus::summary_focus_property()` ； `web_fetch` 和 `web_search_tool` 做什么。模型用它说明自己需要从结果中获得什么，例如“速率限制”。 `before_tool` 会在验证前从调用中移除该参数，因此工具永远不会收到它。只有架构中包含这个确切属性的工具会丢弃它；任何其他具有同名参数的工具都会保留该参数。它会随结果一起传递给 TinyJuice，在那里用于引导摘要、作为缓存键，并为确定性压缩器排列文本。对于会自行限制输出的工具，例如 `web_fetch`，通常会让它自行限制输出并溢出到文件。当调用方提供了关注重点时，也会对其进行摘要，因为仅对原始页面分页无法回答问题。

### 文件系统卸载： `outputs/` 和 `workspace/`

仅靠压缩无法支撑长时间运行的任务。摘要仍会随着每一步不断累积，而且无论怎样压缩，都无法恢复已丢失的信息。因此，对于持续数分钟到数小时的任务，运行框架会将大型结果移出上下文并保存到磁盘，然后把文件路径交给下一步。

运行时在代理现有的 `action_dir` 下创建两个目录（实现位于 `crates/openhuman-core/src/agent/harness/artifact_offload/`):

| 目录                      | 用途                            |
| ----------------------- | ----------------------------- |
| `action_dir/outputs/`   | 交付物。用于在生成它的步骤结束后继续保留，并通过路径传递。 |
| `action_dir/workspace/` | 临时工作区。工作进程需要但不会交回的中间文件。       |

注意 `action_dir/workspace/` 是代理操作根目录中的临时文件夹，并非核心内部的 `workspace_dir`；代理写入的内容可能永远不会到达后者。

这一约定由两部分共同落实：

* 提示词。实际持有 `file_write` 工具的子代理会在系统提示词中收到“长时程任务产物卸载”约定：超过约 2,000 个 token 的结果应写入 `outputs/`下的文件，回复内容则为该文件的相对路径和简短摘要。这里的限制是有意设置的：提示词只能提及代理实际能够调用的工具，否则模型会发出无法成功执行的工具调用。经过技能筛选的专用代理不会收到这段约定文本，并且专门的防护检查会断言其提示词中绝不提及文件系统工具。它们仍由下文所述的运行框架机制覆盖，无需模型配合。 `planner` 提示词会说明这一约定对其自身工作的含义：规划器会被要求在 DAG 节点之间引用产物路径，而不是把内容直接粘贴到后续节点。
* 运行框架。 `offload_oversized_result` 会对每个子代理的执行结果运行，因此即使工作进程仍将超大结果直接内联，结果也会被卸载到文件。它会在应用定义中的 `max_result_chars` 上限之前触发，因此完整内容会写入磁盘，而不是被截断。

父代理收到的是指针，而非内容：

```
[产物] kind=output path=outputs/presentation_agent/sub-1234-result.md bytes=52318
读取方式：file_read {"path":"outputs/presentation_agent/sub-1234-result.md"}
说明：完整结果已写入操作工作区，而非直接内联。…

[摘要]
主要发现…
```

`SubagentRunOutcome.artifact_paths` 以结构化形式携带相同路径，这些路径是从输出中的 `[artifact]` 指针解析而来，因此无论结果是由运行框架卸载，还是由工作进程自行写入文件，交接内容都会包含路径。父代理接收的任何路径，都可以在子代理上下文消失很久之后，通过普通的 `file_read` 调用读取。

摘要器是后备方案，而不是首选方案。Offload 可处理常见情况；摘要器分流以及 `tool_result_budget_bytes` 以上的截断仍会处理它未能处理的所有情况，包括这里提到的每一种故障模式。Offload 被拒绝或失败时，会有意采用宽松处理：调用方保留内联载荷，并继续由这些后备机制处理。

路径加固采用失败即关闭策略。 `resolve_artifact_path` 会拒绝绝对路径、 `..` 路径遍历，以及在词法规范化后逃出约定根目录的任何路径。如果 `SecurityPolicy` 可用，它还会拒绝位于 `workspace_dir`下的任何路径，既会进行全面的包含检查，也会通过 `is_workspace_internal_path`进行检查。Offload 目标会解析到 `action_dir`下，而不会解析到 `workspace_dir`下；即使有人将 `action_dir` 配置在工作区根目录内，也会拒绝所有 Offload，而不会悄悄写入内部状态。

写入操作会记录日志 `[artifact] wrote worker artifact under action_dir`；交接携带的每个路径都会记录日志 `[artifact] handoff carried an artifact path to the parent`，生成端和接收端都会记录，因此运行日志能显示每个指针的两端。

### TokenJuice：基于内容感知的工具输出精简

新的工具结果进入历史记录之前（并且先于字节预算后备机制），会先通过已编译的 TinyJuice 模块中的 TokenJuice 内容路由器处理；OpenHuman 适配器位于 `crates/openhuman-core/src/inference/tokenjuice/`。该路由器受 Headroom 启发， *会检测内容类型* （JSON、代码、日志、搜索、差异、HTML、纯文本），依据字节内容和/或从工具名称及参数推导出的提示，然后分发给专用压缩器：

* JSON → SmartCrusher：将对象数组转换为表格（每个键只保留一次），并保留包含错误或数值异常值的行。
* 代码 → tree-sitter（Rust/TS/JS/Python）签名保留器，用于折叠函数体；若不可用，则回退到基于大括号深度的启发式方法。
* 日志 → 用于 *命令* 输出（git/cargo/npm/…）的 100 条规则引擎；其他情况则基于信号保留失败信息。
* 搜索 → 按相关性排序，每个文件保留前 K 个匹配项，并附带 `+N more` 计数。
* 差异 → 保留已更改的代码块，折叠未更改的上下文，并概述锁文件代码块。
* HTML → 去除标记，转换为可读文本。
* 纯文本 → 使用确定性的 TextCrusher。

每次有损压缩都会将原始内容卸载到 CCR（Compress-Cache-Retrieve，压缩-缓存-检索）存储中，并附上 `⟦tj:<hash>⟧` 标记，因此精简实际上是无损的：智能体可按需调用 `juice_retrieve` （令牌以及可选的字节/行范围）来获取完整原文。同一引擎还以通用接口 `compress_content(content, hint, opts)` 的形式提供，可用于任意大型载荷（文件读取、网页抓取）；同时也提供只读的 `tokenjuice.*` 调试 RPC。精简默认启用（`context.compaction_enabled`; `OPENHUMAN_COMPACTION=0` （不适用）。较大的结果会被存储，并替换为一行统计信息、前 500 个字符，以及一个供只读 `juice_find` / `juice_extract` / `juice_summarize` 工具查询的句柄（`tokenjuice.repl_handle_enabled`），因此对于获得句柄的结果，会跳过 LLM 摘要阶段。可通过 `[tokenjuice]` 配置块 / `OPENHUMAN_TOKENJUICE_*` 环境变量进行配置。智能体定义可以通过以下配置覆盖工具结果压缩设置： `tokenjuice_compression = "auto" | "full" | "light" | "off"`; `auto` 会将编码模型智能体（`[model] hint = "coding"`）解析为 `light`，这会禁用基于 CCR 的有损压缩，使编码智能体保留原始的构建、测试、差异和搜索文本，除非精简过程确实无损。其他智能体默认使用 `full`。纯文本压缩使用确定性的 TextCrusher。

### 缺失的能力

没有自愈型原型。缺少主机命令时，会将情况反馈给用户，而不会用兼容实现补上。

## 子智能体：编排器模式

OpenHuman 是一个多智能体系统。用户正在对话的智能体是主智能体（稳定的内部 ID： `orchestrator`），它是一个能力全面的默认智能体，能够直接回答问题并完成常规工作，包括“检查 → 编辑 → 验证”的编码循环。当并行处理、更深入的推理或专门能力能显著提升效果时，它会启动专业子智能体。

### 为什么采用多智能体

一个无所不知的单体智能体，其系统提示词也会长得像一本小书。将工作分配给不同的专家有以下好处：

* 每个子智能体都只会收到范围明确的系统提示词，其中仅包含所需章节（可移除身份、记忆和安全前言）。
* 每个子智能体都会获得经过筛选的工具注册表：图像智能体不需要文件系统工具，任务管理器也不需要 Composio 目录。
* 子智能体的历史记录绝不会泄露给父智能体：父智能体只会看到一条精简的工具结果，而不是内部对话。
* 较便宜的模型可以处理叶节点任务。编排器使用强推理模型，而研究子智能体可能使用速度更快、成本更低的模型。

### 内置原型

每种原型都位于 `agents/<name>/` 目录下，并包含一个 `agent.toml` （元数据、工具范围、模型提示）和一个提示词。编排器可在对话中委派任务的智能体，列于其 `[subagents]` 许可列表中：

| 原型                   | 编排器在何时选择它                                  |
| -------------------- | ------------------------------------------ |
| `orchestrator`       | 主智能体：顶层、能够直接处理任务的默认智能体。不会由其他编排器启动。         |
| `task_manager_agent` | 添加、预览、获取、更新或移除任务来源、工作流包和制品。                |
| `vision_agent`       | 任何依赖图像内容的任务（描述、OCR、UI 元素）。                 |
| `image_agent`        | 生成或编辑图像。                                   |
| `video_agent`        | 生成视频或为图像添加动画。                              |
| `presentation_agent` | 制作带有依据和引用的幻灯片（功能 `documents`).             |
| `skill_setup`        | 从注册表中查找、安装和管理技能（`setup_skills`).           |
| `workflow_builder`   | 编写或编辑已保存的工作流（`build_workflow`）；返回提案，但绝不保存。 |
| `flow_discovery`     | 推荐值得配置的工作流（`discover_workflows`).          |

其他内置代理绝不会作为聊天委派对象：

| 原型                                   | 执行者                                                                                    |
| ------------------------------------ | -------------------------------------------------------------------------------------- |
| `planner`, `critic`                  | 只有 `parallel_research_cross_check` 工作流运行模板（分解和研究 = `planner`，cross\_check = `critic`). |
| `summarizer`                         | 由运行框架调用，用于压缩超出容量的工具结果；也用于该工作流运行模板的综合阶段。                                                |
| `trigger_triage` / `trigger_reactor` | 对传入的外部事件进行分类，并做出轻量级响应。                                                                 |
| `morning_briefing`                   | 定时任务：每日摘要，使用指定的只读工具集。                                                                  |

编排器本身通过内联技能处理编码、加密货币、设置、日程安排、产品文档和 MCP 服务器： `use_skill` 加载工具包的指南和架构（`coding`, `web3`, `system`, `scheduling`, `docs`, `mcp`），这些工具也都处于 `Deferred` 状态，因此 `tool_search` 可以找到其中任意一个。运行已安装技能是编排器自己的 `run_workflow`。参见 [`tools/toolpacks/README.md`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-core/src/tools/toolpacks/README.md).

自定义原型以 TOML 文件形式随附，存放在 `$OPENHUMAN_WORKSPACE/agents/*.toml` （或 `~/.openhuman/agents/*.toml` ，用于用户全局专用代理）。自定义定义在 ID 冲突时会覆盖内置定义。

### 运行可复用的子代理

当编排器调用 `spawn_subagent`时，默认契约是持久且异步的。该工具会根据父会话/线程、代理 ID、模型覆盖项、沙箱模式、操作根目录以及规范化后的任务键/标题，构建一个确定性的兼容性选择器。随后，它会在生成子代理之前检查 `orchestration::subagent_sessions` ：

* 如果已有兼容的工作线程正在运行，指令会通过其 `RunQueue` 注入，父代理会快速收到一个 `subagent_session_id` / `task_id` 引用。
* 如果兼容的工作线程处于空闲状态，或已暂停且具有可复用的历史记录，运行框架会为同一个持久化的 `subagent_session_id` 启动一次新的临时运行，并通过 `SubagentRunOptions.initial_history`传入已保存的子代理历史记录，同时将新指令作为用户可见的后续消息追加。
* 如果运行配置不兼容、工作线程已关闭、传入了 `fresh: true` ，或者不存在会话，运行框架就会创建新的持久化会话和工作线程。

子代理运行由 OpenHuman 主机通过中立的 TinyAgents 生命周期进行准备和执行：

1. 从其类型化运行上下文接收父级取消信号和工作区；其余旧版提供方、沙箱和对话记录输入仍保持原有作用域，直至完成明确的迁移。
2. 解析子代理使用的模型：首先采用内联的 `model` 覆盖项，其次采用配置级固定值（`[orchestrator].model`, `[teams.*].lead_model`, `[teams.*].agent_model`），最后采用原型提示或继承的父模型。
3. 根据定义中的 `tools`, `disallowed_tools`和 `skill_filter`筛选父代理的工具注册表。在 `fork` 模式下，会逐字继承父代理的完整注册表。
4. 构建精简的系统提示词，并省略定义要求移除的部分。
5. 将准备好的子代理传递给 `tinyagents-orchestration` ，以确保生命周期顺序，并且仅执行一次暂停或终止状态的持久化操作。
6. 将子代理历史记录和工作线程指针持久化到 `subagent_session_id` 下，以便后续轮次可以恢复或检查该会话。暂停后的续接也会保留完整的 TinyAgents 任务键。

`wait_subagent` 和 `steer_subagent` 接受持久的 `subagent_session_id` 或临时的 `task_id`；跨轮次使用时，优先选择持久 ID。 `list_subagents` 会显示当前父线程中可重复使用的子代理，而 `close_subagent` 会将工作代理标记为不可重复使用，并在其仍在运行时取消它。通过 `blocking: true`.

合成的原型委派（`delegate_*`, `build_workflow`以及其他 `delegate_name` 工具）遵循相同的契约：默认通过持久的异步路径进行路由，并立即返回 `[async_subagent_ref]` （包含 `subagent_session_id` + `task_id`），完成的结果则通过 `background_completions`/`background_delivery`作为新的系统轮次插入父聊天中。其背后的队列是运行框架的 `tinyagents_tasks::CompletionRouter` ，通过每个工作区的 `JsonlCompletionStore` (`.openhuman/background_completions.jsonl`（按聊天线程作为键）：它按任务 ID 去重，保留父级在线收集结果或 Stop/删除操作取消任务所产生结果的墓碑记录，统计投递尝试次数，并返回已放弃投递的记录。在投递轮次完成之前，记录会一直处于租用状态（`mark_delivered`）；因此，已完成但尚未投递的结果会在重启后重新投递。宿主会保留 `<background_agent_*>` 措辞（由 `CompletionFormatter`生成）、3 秒空闲防抖、系统轮次及其 web\_chat 事件，以及将已放弃结果持久化到线程中的写入器。投递轮次会持久化自己的结束消息， `sender: "agent"`，ID 为 `agent:<run_id>`, `extraMetadata.requestId = run_id`，然后以 `chat_done` 和 `client_id: "system"`发出；前端会复用该 ID，因此常规的 `chat_done` 追加操作会合并到同一行（对话存储对这些确定性的 `agent:`前缀 ID 具有幂等性；其他所有 ID 都是新生成的 UUID，因此仍走常数时间追加路径），而不会再次持久化已投递的结果。交互式轮次遵循相同的契约： `web_chat::presentation::deliver_response` 会将回复存储在 `agent:<request_id>` 发布前 `chat_done`，因此无论客户端是否在线接收通知，核心生成的答案都会保存在磁盘上；套接字断开或 WebView 重新加载只会导致界面重绘，而不会丢失回复。例外情况是分段交付：客户端为每个分段维护一行数据，核心不存储任何内容；前端会保留生成的 ID，正是出于这个原因。如果没有父级代理轮次或没有可交付消息的聊天线程（cron/CLI），或者传入了 `blocking: true` ，系统会自动回退到内联阻塞模式。跨轮次连续性由以下三个部分保障：每轮的 `[active_subagents]` 名册会合并实时内存注册表与持久化的 `subagent_sessions` 存储（因此冷启动的编排器仍能看到之前的工作代理）； `continue_subagent` 会在暂停检查点不可用时回退到持久化存储，利用已保存的历史记录恢复空闲工作代理；此外，如果已完成子代理的历史记录中存在 `workflow_proposal` 负载，则会将其持久化为父线程消息（`extraMetadata.scope = "workflow_proposal"`），前端在线程加载时会据此重新生成提案卡片。

### 派生层级与梯队

并非每个代理都可以派生其他所有代理。该框架采用三级层级结构，对应模型在成本、延迟和思考深度方面的差异：

```
Primary     （具备直接执行能力，`coding` 提示下的 Master Agent）
  │
  ├─► Worker      ◄─── 快速路径：委派一次，由叶节点完成工作
  │
  └─► Reasoning   （速度较慢、深度思考，例如 `reasoning` 提示下的规划器）
        │
        └─► Worker  ◄─── 深度路径：Reasoning 拆解任务，Worker 执行
```

每个 `AgentDefinition` 都包含一个 `agent_tier` 字段（`chat` / `reasoning` / `worker`，默认值为 `worker`）。约定如下：

| 梯队          | 可以派生                  | 不得派生                      | 典型成员                                        |
| ----------- | --------------------- | ------------------------- | ------------------------------------------- |
| `chat`      | `reasoning`, `worker` | 另一个 `chat`                | `orchestrator`                              |
| `reasoning` | `worker`              | 另一个 `reasoning`，任意 `chat` | `planner` （目前唯一的标准成员）                       |
| `worker`    | 无[^1]                 | 任何                        | critic、image\_agent、task\_manager\_agent、…… |

规则背后的原因。

* *Chat → chat 毫无意义。* chat 层旨在提供灵敏的用户体验。让一个 chat 代理再生成另一个 chat 代理，只会让 TTFT 翻倍并浪费 token，却不会带来任何新能力。
* *Reasoning → reasoning 会导致深度失控。* reasoning 层成本高昂。reasoning 代理组成的链条往往会反复拆解同一个问题，并形成不断扩张的层级结构。
* *Worker → anything 会混淆执行与编排。* Worker 是叶节点，因此父代理始终只会看到一份精简结果，而不是嵌套委派的完整记录。

强制执行分为两层：

1. 加载时（静态）。 `tinyagents_definition::DefinitionSet::validate_tier_hierarchy` 会检查合并后的注册表（内置项 + 工作区 TOML 文件），并拒绝启动包含同层级条目或带有子代理的 worker 条目的注册表。内置 archetype 会在加载期间检查；用户提供的 TOML 文件则在加载工作区时检查。
2. 运行时深度门限（动态）。无论层级如何，子代理运行器都会将生成链的总深度限制为 `MAX_SPAWN_DEPTH = 3` 它通过任务局部计数器实现，该计数器会在 `run_subagent`调用过程中递增，并以 `SpawnDepthExceeded` 代理错误的形式呈现。这样，即使用户提供的 TOML 文件移除了层级注解，也无法递归超过三层。

> 状态：加载时层级检查、 `agent_tier` 字段和运行时深度计数器任务局部变量均已启用。深度同时受静态加载器约定和运行时 `MAX_SPAWN_DEPTH = 3` 保护机制限制。

### 工具包专用专家代理

对于包含数百个操作的 Composio 工具包（仅 GitHub 就有 500 多个操作），将所有操作都加载到子代理的工具集中会大幅增加提示词长度。运行框架会使用轻量级、仅依赖 CPU 的筛选器（动词检测、词元重叠、动词匹配加权），根据父代理细化后的任务提示词对工具包操作进行排序，并只将排名靠前的子集加载到子代理中。整个过程不调用模型，完全基于启发式规则，既快速又易于解释。

## 分诊：处理外部触发事件

Webhook 触发、cron 定时任务运行或 Composio 事件到达时，系统不能直接将其交给编排器。大多数触发事件都是噪声；有些值得通知；只有少数需要启动完整的代理轮次。触发事件分诊流水线就是这道关口。

```
TriggerEnvelope ──► run_triage ──► TriageDecision ──► apply_decision
                       │                                     │
                       │                                     ├─► 丢弃（噪声）
                       │                                     ├─► 仅通知
                       │                                     ├─► 生成 trigger_reactor
                       │                                     └─► 生成 orchestrator
                       │
                       └── 小型本地 LLM（失败重试时回退到云端 LLM）
```

评估器特意设计得成本低廉：条件允许时使用小型本地模型，重试时则回退到远程模型。决策会被缓存，因此相同的触发事件不会被重复分类。只有升级为“生成 orchestrator”的触发事件才会进入完整的 `Agent::turn` 处理流程。

## Hooks：可观测性与策略控制

循环两端分别设有两类 hook：

### 停止 hook（轮次中）

停止 hook 会在工具调用循环的迭代之间触发，可用于实施预算上限、速率限制和自定义紧急停止开关。内置 hook：

* 预算停止 hook：使用逐次迭代的成本累加器，限制每轮累计费用（美元）。
* 每次调用的支出预算：发送前，每次提供方调用都会在本轮共享账本中预留一个保守的上限，并根据实际用量结算。该机制作用于附件渲染之后，因此，照片、贴纸或文档所在的轮次会根据渲染后的文本获准执行，图像解读结果则计入同一账本。预算生效期间，模型接收的是图像解读结果和提取出的文档文本，而非原生媒体。
* 最大迭代次数停止钩子：可从代理的持久化配置之外限制迭代次数。
* 操作预算策略： `SecurityPolicy` 会强制执行 `config.autonomy.max_actions_per_hour` ，限制会产生副作用的工具操作。用户可在“设置”>“高级”>“代理自主性”中调整此值；运维人员也可以通过以下配置项覆盖： `OPENHUMAN_MAX_ACTIONS_PER_HOUR`.

钩子返回 `Stop` 时，会中止循环，并提供明确原因，供调用方告知用户。停止钩子不同于中断（见下一节）：它由策略触发，而非由用户触发。

### 轮次结束后钩子

轮次结束后钩子会在本轮完成后于后台触发。它们会收到以下信息： `TurnContext` 快照、用户消息、助手回复、每次工具调用及其参数和结果、总耗时、迭代次数和会话 ID。内置使用方包括：

* 费用日志：记录每轮最终费用。
* 对话日志： `memory` 生命周期会在轮次结束后记录回复，并为工具结果记录单行摘要（绝不记录参数）；不进行批量处理，也不会在空闲时刷新。请参阅 [记忆架构](/openhuman/zh/kai-fa/architecture/memory.md).

长期事实由代理显式写入：代理会调用 `memory` 工具的 `learn` 操作。系统不会自动归档。

钩子通过 `tokio::spawn`运行，因此用户会先收到回答，之后钩子才会全部执行完毕。

## 中断：优雅取消

取消是 tinyagents 的控制通道。用户按下 Ctrl+C 或发送 `/stop`时，运行器会将请求转发到执行框架的控制/取消接口，并在安全检查点停止循环：每次执行工具之前、每次启动子代理之前，以及每次调用提供方之前：

* 所有正在运行的子代理共用同一个取消作用域，并会在下一个检查点退出。
* 正在进行的提供方数据流会被丢弃。
* 缓冲的对话轮次仍会被保存（在空闲刷新时，或退出时执行最终刷新）。

中断由用户触发；停止钩子由策略触发。两者都会进入同一套执行框架暂停/停止流程，但触发来源不同。

## 费用核算

每个提供方响应都包含一个 `UsageInfo` 数据块，其中包含输入令牌数、输出令牌数、缓存输入令牌数，以及由 OpenHuman 后端填充的权威字段 `charged_amount_usd` 。 `TurnCost` 会汇总一轮内所有提供方调用的费用，让执行框架能够：

* 通过进度通道发送每次迭代的费用遥测数据。
* 为预算停止钩子提供数据，使失控的轮次能在循环中途自行终止。
* 记录准确的轮次结束费用。

如果后端未提供已计费金额（例如较旧版本，或未通过该后端计费的提供方），系统会使用按层级划分的小型费率表，根据令牌费率估算费用下限。如有后端直接提供的费用数据，则始终优先使用。

## Web 通道事件和 RPC（assistant-ui 元素传递阶段）

assistant-ui-elements 集成新增了一批增量式 `WebChannelEvent`以及 RPC，以便前端无需轮询即可呈现工具参数/耗时、计划/目标/队列状态和轮次生命周期。 `EVENTS_VERSION` (`core/bus.rs`) 是 `1.4.0`；每个新增字段都设为可选或提供默认值，因此较旧的订阅方仍能解析较新的发布方发出的内容。

新增/扩展的套接字事件（由 `DomainEvent` 桥接到 `WebChannelEvent` ，由 `web_chat::event_bus` 和 `openhuman_rpc::server::socketio`):

* `ts` （纪元毫秒）会在每个事件上由 `publish_web_channel_event` 在生产者未设置该值时加盖时间戳，使前端无需猜测接收时间即可对事件排序并测量延迟。
* `chat_done.timing`: `{ first_token_ms, first_tool_ms, total_ms, tokens_per_second }`，通过 `TurnTiming` ，从进度桥接器中按轮次记录的 `ProgressBridgeHandle::timing_snapshot()`. `tokens_per_second` 由 `output_tokens / (total_ms / 1000)` 在两者都已知且 `total_ms > 0`.
* `chat_done.usage.context_tokens`：根代理最终一次模型调用的输入与输出 token 数之和。该值用于上下文窗口仪表，不包括更早的调用和子代理； `input_tokens` 和 `output_tokens` 仍表示整轮累计消耗。
* `chat_cancelled`: `{ thread_id, client_id, request_id, cancel_reason: "user_stop" | "superseded", superseded_by }`。它会与现有事件同时发出（而非取而代之）：包括未限定/限定范围的停止路径、新请求取代旧请求的路径，以及并行轮次的协作取消路径（此前该路径完全不会发布终止事件）。 `chat_error{error_type:"cancelled"}`，适用于未限定/限定范围的停止路径、新请求取代旧请求的路径，以及并行轮次的协作取消路径（此前该路径完全不会发布终止事件）。
* `chat_error{error_type:"guardrail"}`：包含 `guardrail: { verdict, score, reasons: [{code,message}] }` 负载；当 `start_chat` 通过 `StartChatError::Guardrail` 拒绝消息时触发（提示注入/安全护栏）。其他所有 `start_chat` 拒绝仍归为 `error_type:"inference"`。RPC 接口（`channel.web_chat` 的 `Result<_, String>`）编码了与 `GUARDRAIL:<json>` 哨兵字符串相同的结构化判定（`web_chat::ops::start_chat::{GUARDRAIL_ERROR_PREFIX, is_guardrail_error_message}`，与现有的 `BACKEND_UNAVAILABLE:` 模式一致）。提示注入筛查器在 `start_chat` 已接受回合后将其拦截（会话防护机制或托管门禁拒绝提示或工具输出，包括安全模块无法响应的情况）时，会返回 `chat_error{error_type:"prompt_screened", error_source:"security", copy_key:"chat_error.prompt_screened"}`，且可重试。
* `turn_cost`：通过 `AgentProgress::TurnCostUpdated`提供实时的每回合成本读数，每回合最多每 750 毫秒发送一次（首次更新始终立即发送）： `{ thread_id, client_id, request_id, round, usage: { input_tokens, output_tokens, cached_input_tokens, cost_usd, context_window, context_tokens, subagents } }`. `context_tokens` 是根代理最后一次调用的输入与输出 token 数，用于显示其上下文窗口用量；不会对多次调用或子代理进行求和。 `subagents` 在此实时事件中始终为空（这里只包含父代理的累计汇总）；每个子代理的归因信息仍仅在终结事件 `chat_done.usage`.
* `approval_decided` / `plan_review_decided`：由 `DomainEvent::ApprovalDecided` / `PlanReviewDecided`桥接而来；它新增了 `thread_id`, `client_id`, `tool_call_id`和 `resolution` (`"expired"` 表示 TTL 到期或清理操作触发， `"cancelled"` 表示决策通道被丢弃， `None` 表示普通用户决策；在网络传输中沿用现有的 `cancel_reason` 字段）。只有当原始挂起操作同时具有 `thread_id` 和 `client_id` （由聊天路由）时才会显示。
* `run_mode_changed`: `{ thread_id, client_id: "", message: "plan" | "build" }`，由 `DomainEvent::ThreadRunModeChanged`桥接而来，由以下对象发布 `threads::run_mode::set_mode`.
* `thread_todos_changed`, `queue_item_queued` / `queue_item_delivered` / `queue_item_removed`, `queue_item` 携带 `{ id, lane, text_preview }`.
* 子代理关联： `subagent_spawned`/`subagent_completed`/`subagent_failed`/`subagent_awaiting_user` 携带 `subagent.parent_call_id` （生成工具调用的 ID：同一 `spawn_parallel_agents` 次调用的所有工作线程共享该 ID）； `subagent_completed` 还携带 `subagent.output` （截断后的最终文本）。 `tool_call.args`/`tool_result.args`+`elapsed_ms` 现在携带真实参数和耗时，而不再是 `null` （来自 tinyagents 的 `AgentEvent::ToolStarted.input`).
* Artifact 事件（`ArtifactPending`/`ArtifactReady`/`ArtifactFailed`）携带 `tool_call_id` 和 `turn_request_id`，后者取自发起该事件的轮次中的 `ApprovalChatContext::request_id` ，以便前端将 artifact 卡片关联到生成它的确切轮次（对于没有聊天上下文的 CLI/cron/子代理生成器，该值为`None` ）。

新增 RPC：

* `agent.set_run_mode { thread_id, mode }` / `agent.get_run_mode { thread_id }`，读取或切换线程的 Plan/Build `RunModeHandle`. `channel.web_chat` 还接受一个可选的 `run_mode: "plan" | "build"` 参数（与 socket 保持一致 `chat:start` 负载），以便轮次可以直接以请求的模式启动线程，而不必与单独的 RPC 调用竞争；无法识别的值会被记录并忽略。
* `threads.token_usage { thread_id }`：返回已持久化的线程总用量，以及 `last_turn_context_tokens`，即根代理最后一次调用的输入与输出总量，供上下文窗口用量指示器使用。对于没有逐次调用用量数据的旧轮次，则回退为输入与输出的总和。
* `threads.goal_get` / `threads.todos_get`：直接读取线程当前的目标／待办事项状态。
* `threads.token_usage { thread_id }`：返回已持久化的线程总用量，以及 `last_turn_context_tokens`，即根代理最后一次调用的输入与输出总量，供上下文窗口用量指示器使用。对于没有逐次调用用量数据的旧轮次，则回退为输入与输出的总和。
* `threads.edit_message { thread_id, message_id, content, client_id? }` / `threads.regenerate { thread_id, message_id?, client_id? }`，两者都会返回 `{ request_id }`。它们会取消线程中正在进行的轮次，通过 `TranscriptLocator::truncate_into_next_generation` 在截断点处分叉会话记录（被截断的封存代次不会受到影响，仍保证“压缩不会擦除”），截断会话存储中的消息日志以及所有被丢弃轮次的轮次状态快照，然后使用编辑后的内容（`edit_message`）或原始提示（`regenerate`）重新启动轮次。完整的 UI 消息 ID 到记录截断点的映射，请参阅 `threads::ops::edit`的模块文档。
* `channel.web_queue_remove { client_id, thread_id, item_id }`：从线程的运行队列中移除一个指定的排队项目。
* `agent.context_breakdown { agent_id?, thread_id? }`：提供代理渲染后提示词大小的 UI 友好视图（拆分为系统、工具和历史记录），供撰写器的上下文用量指示器使用。
* `commands.list`：将内置命令与 `skills.list` 和 `flows.list` 合并为一个斜杠命令目录。

`plan_exit` （用于将线程从 Plan 切换回 Build 的工具）只有在线程上没有仍处于挂起状态的计划审核时才会切换模式（`plan_review::gate::PlanReviewGate::parked_review_for_thread`）。审核会在 `request_plan_review` 将控制权交还给代理之前完成，因此这只关系到时机不当／并发的 `plan_exit` 调用与仍待处理的审核发生竞争的情况；在用户实际批准之前，不能因此解锁所有工具。

## 显式运行上下文与主机能力

`OpenHumanRunContext` 是共享聊天、频道和子代理轮次交界处的实时载体。根代理会快照当前作用域中的来源、进度、停止钩子、分派状态、线程、路由槽位和工作区授权，然后在将上下文传递给运行器之前，持有或显式接收一个取消令牌；递归子代理则通过 `child()`派生上下文，在隔离路由观测和用量核算的同时，共享取消／策略句柄。共享运行器通过 `RunContext<OpenHumanRunContext>` 和 `into_tinyagents`创建上下文；OpenHuman 组装层和中间件注册表会直接使用这个类型化上下文。路由和线程作用域仍仅在驱动期间保留，以兼容类型化框架边界之外的旧版工具／模型 API。递归扇出会从其类型化父级 `RunContext` 和 `ToolDispatch`；它从不读取环境中的取消状态。

`OpenHumanHostBundleFactory` 是 B1 主机的组合入口。它使用相同的会话/运行时输入构造上下文、定义、安全、模型、记忆、预算、进度、工具结果和体验适配器。OpenHuman 保留所有策略决策；目前 TinyAgents 只接收最终生成的规范运行上下文。将完整的主机能力包接入每次调用仍是后续切换步骤。

## 自愈回顾

主循环之上还有几个小型自适应系统：

* 工具输出摘要熔断器：如果某个线程连续三次摘要失败，TinyJuice 就会停止为该线程请求摘要，使结果回退到压缩和截断处理。
* 分流本地与远程重试：优先使用本地 LLM；解析失败时回退到远程模型。
* 未知工具和格式错误参数的恢复：中间件会将无效的模型工具调用改写为可恢复的结果，而不是中止运行。

这些机制都不会改变循环的结构，只是让常见故障能够自行恢复，无需用户介入。

## 代码位置

运行框架外壳位于 `crates/openhuman-core/src/agent/`，与 tinyagents 的适配器接口位于 `crates/openhuman-core/src/agent/tinyagents/` ，原型定义位于 `crates/openhuman-core/src/agent_registry/`。 `crates/openhuman-core/src/agent/` 中的 README 列出了公开接口；以下是最关键的文件（路径相对于 `crates/openhuman-core/src/agent/` ，除非另有前缀）：

| 文件 / 目录                                | 内容                                                                                               |
| -------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `session_host/runtime_session.rs`      | `Agent::turn`：上述生命周期；通过 `tinyagents/turn_exec.rs`.                                               |
| `tinyagents/mod.rs`                    | `TurnSpec::run`：共享的 tinyagents 运行框架组装（实时循环）。                                                     |
| `tinyagents/middleware.rs`             | 具名的 OpenHuman 中间件栈（审批/安全、工具策略、恢复、预算、熔断器）。                                                        |
| `../channels/runtime/turn_driver.rs`   | 通道/CLI 总线轮次驱动器，位于通道运行时目录中，并路由到 tinyagents 运行器。                                                   |
| `subagent_host/`                       | 面向 `tinyagents-orchestration::subagent`的直接 OpenHuman 规划器/执行器/持久化适配器；产品提示、工具、模型、安全、制品和进度行为仍由此处负责。 |
| `orchestration/subagent_sessions/`     | 可持久化、可复用的子代理身份、兼容性匹配以及持久化状态/历史记录。                                                                |
| `../agent_registry/host_definition.rs` | 基于 `tinyagents_definition::AgentDefinition`.                                                     |
| `subagent_host/ops/runner.rs`          | 集成工具排序和主机执行叶节点；通用生命周期仍由 `tinyagents-orchestration`.                                              |
| `tinyagents/payload_summarizer.rs`     | TinyJuice 对超大工具结果进行摘要时所调用的模型。                                                                    |
| `session_host/tool_progress.rs`        | 仍由 OpenHuman 负责的接口： `TurnProgress`.                                                              |
| `message_convert.rs`                   | 围绕规范工具调用方言 API 实现具体且可靠的提供方转换。                                                                    |
| `triage/`                              | 外部触发分类与升级处理。                                                                                     |
| `../agent_registry/agents/`            | 内置原型：每个代理对应一个子目录。                                                                                |
| `hooks.rs` / `stop_hooks.rs`           | 轮次结束后和轮次进行中的钩子接口。                                                                                |
| `cost.rs`                              | 按轮次统计美元/令牌用量。                                                                                    |
| `progress.rs`                          | 向 UI 实时发送进度事件。                                                                                   |

## 基于 tinyagents 的代理引擎与编排

每个代理轮次都使用 TinyAgents。聊天和频道/CLI 调用方会调用会话/轮次宿主，而子代理调用则进入 `agent/subagent_host` 及其直接的 `tinyagents-orchestration::subagent` 生命周期。不存在 `harness/subagent_runner` 兼容路径。外围的 OpenHuman 接口：

| 文件（`crates/openhuman-core/src/agent/tinyagents/`) | 职责                                                                                                                               |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `mod.rs`                                          | 运行器（`TurnSpec::run`）：安装原生 `ChatModel`、宿主工具适配器和中间件到 `AgentHarness`上；运行一个轮次；通过原生 `MaxTokensModel`限制输出；镜像进度；转发引导指令；并在达到模型调用上限时优雅暂停。 |
| `mod.rs` / `model.rs` / `tools.rs` / `convert.rs` | `RunPolicy` / `ChatModel` / `Tool` / 消息适配器（包括未知工具策略和带外推理转发）。                                                                     |
| `observability.rs`                                | Harness `AgentEvent` → `AgentProgress` + 成本； `GraphTracingSink` 用于图事件。                                                           |
| `orchestration.rs`                                | 重新导出 `graph::orchestration` 任务存储类型；map-reduce 扇出直接使用 TinyAgents SDK 接口。                                                          |
| `orchestration/README.md`                         | OpenHuman 的子代理适配器和面向产品的持久化投影；通用任务执行归 TinyAgents 所有。                                                                              |

基于图的编排（`crates/openhuman-core/src/agent/orchestration/`):

* 工作流执行使用 TinyFlows 图执行；OpenHuman 保留工作流定义、控制器接口和持久化运行记录。
* 代理团队执行和通用委派归 TinyAgents 所有；OpenHuman 保留产品策略、适配器和面向 UI 的投影。
* 分离运行的子代理（`running_subagents.rs`) 使用 TinyAgents 的 `DetachedTaskRegistry` 来实现感知所有权的快照、等待/超时、引导查找、协作式取消、强制中止和终态清理。OpenHuman 保留持久化任务存储投影、产品/会话元数据、RPC 与交付语义，以及 `RunQueue` 兼容性回退机制。

有意不纳入该 crate 的基础原语（这些是设计决策，而非功能缺失）：

* 子代理宿主策略（`subagent_host/`) 仍由 OpenHuman 所有：定义解析、原型工具筛选、提供方解析、精简提示构建、记忆上下文、工作线程镜像、交接配置以及产品检查点/会话投影。它直接实现 TinyAgents 的规划器/执行器/持久化特征。中立驱动程序（而非宿主本地运行器）负责生命周期排序和任务键合并。
* 持久化运行日志（`workflow_runs`, `agent_teams`, `command_center`, `subagent_sessions`) 在其控制器投影和重启语义映射到 TinyAgents 任务/状态/日志记录之前，仍使用 openhuman SQLite/JSON。 `agent_teams` 具备竞态安全性的 SQL 比较并交换任务认领机制仍由 OpenHuman 所有。

> TinyAgents 提供 harness 存储/缓存/会话基础原语（`harness::store` 含 JSONL 追加存储、 `harness::cache`, `harness::subagent`、具备血缘感知能力的状态）、图任务存储、分离运行时注册表和一致性契约。会话外壳以及产品专用的子代理构建/交付流水线仍由 OpenHuman 所有。

## 可靠性：熔断器、交接与分类故障

三种协同机制可防止运行流程偏离轨道或悄无声息地终止：

无进展熔断器（`RepeatedToolFailureMiddleware`, `crates/openhuman-core/src/agent/tinyagents/middleware.rs`）是该 crate 的 `NoProgressTracker`的轻量驱动器。它会为每次工具调用的参数生成指纹，并将结果纳入逐级升级流程： `Continue` → `Nudge` （通过 `SteeringCommand::InjectMessage`注入结构化的“自步骤 X 起没有进展”纠正信息；在交互轮次中使用是安全的）→ `Halt` （将根因摘要记录到 `HaltSummarySlot`，通过控制手柄暂停）。相同参数的重试会计入熔断阈值（连续 3 次相同失败）； *可恢复* 失败（超时、连接重置、速率限制、5xx）采用扩展的余量阶梯，而不是固定的 crate 阈值。

子代理交接（`subagent_host/`）：子代理运行最终会处于以下三种状态之一：

* `Completed`：正常完成并给出最终答复。
* `AwaitingUser { question, options }`：子代理调用了 `ask_user_clarification`；宿主会将完整检查点（历史记录、问题、选项和覆盖项）存入完整的 TinyAgents 任务键下 `(root_run_id, parent_run_id, thread_id, task_id)`。恢复运行时会找回原始键，而不是根据新的父级轮次派生一个新键。
* `Incomplete { reason }`：子代理被熔断器终止，或达到模型调用上限。负责委派的父代理会转达阻碍原因，而不会把已停止的子代理当作已完成的答复，也不会再次发起完全相同的委派。

顶层运行被熔断器终止时，同样绝不会静默结束；熔断器的根因摘要也不会原样展示给用户：它是面向模型编写的（“将此内容转述回去，不要重试”）。 `hit_cap` / `breaker_halt` 会显示在轮次结果中；聊天轮次会以与工具轮次在没有最终文本的情况下结束时相同的方式关闭已停止的运行（`session_host/driver/grounded_close.rs`):

1. 一次禁用工具的收尾调用，其指令会重述本轮的工具记录，包括每次失败各自的消息；并将熔断器摘要作为停止说明传入，以便解释情况，而不是重复内容。
2. 一次单独的检查调用，只能看到请求、记录和候选答复。如果答复只是在描述意图、与记录矛盾，或遗漏了能够解释请求为何未完成的失败信息，就会被拒绝。
3. 如果答复为空、调用了工具、被拒绝或未经验证（检查失败或未给出判定），则使用确定性的回退方案。该方案会引用每项工具结果和停止说明。

只有通过检查后才会流式传输已接受的文本，因此被拒绝的答复绝不会显示出来。

工具失败分类（`tinytools::status`， vendored 于 `vendor/tinyagents/vendor/tinytools`）：每次工具调用失败都会被归类为与传输方式无关的 `ClassifiedFailure { class, category, cause_plain, next_action, recoverable }`。类别包括 `MissingPermission`, `MissingApp`, `ServiceUnavailable`, `BadCredentials`, `BlockedByPolicy`, `ModelConnection`, `Timeout`, `Denied`, `ApprovalExpired`；类别与界面状态一一对应： *可恢复* （可安全自动重试）， *被策略阻止* （更改设置）， *需要用户确认* （登录 / 安装 / 授权）， *用户已拒绝* （绝不自动重试）。分类信息会随 `AgentProgress::ToolCallCompleted.failure` （包括子代理调用）写入聊天时间线。

## 日志、重放与迁移影子机制

每次运行都会追加到持久化事件日志（`tinyagents/journal.rs`）：一个 `StoreEventJournal` ，基于位于 `{workspace}/tinyagents_store/journal`的 JSONL 追加式存储构建，由 `FanOutSink` （实时桥接 + 日志）→ `RedactingSink` （持久化前屏蔽凭据）组成，并使用重启后保持稳定的事件 ID（`{run_id}-evt-{offset}`）。即使后台轮次未被观察到，也可以事后重建。三个只读 RPC 可用于查看： `agent_run_events` （分页查询，可按 `run_id`/`offset`/`limit`), `agent_run_status` （最新的运行框架状态），以及 `agent_runs_active` （活动运行，可按线程或根运行筛选）。

其余存储切换仍在影子脚手架上运行。产品行为保持不变，差异会被记录：

* 会话存储在存储后端（`DriverSessionStores`）中；文件时代的双写和影子读取已移除； `config.session_shadow_reads` 已不再生效，旧的 `session_dual_write` 键在加载时会被忽略。

目标和待办事项已完全由 crate 提供支持，不再使用影子机制：线程目标存储在 crate 的 `graph.goals` KV 存储（`agent/goals/store.rs`）中，会话待办列表则存储在进程内 crate 的 `graph.todos` 存储（`agent/todos/ops.rs`）中；请参阅 [目标和待办事项](/openhuman/zh/gong-neng/goals-and-todos.md).

## 工作负载路由与突发层

`tinyagents/routes.rs` 是面向 OpenHuman 工作负载角色的声明式 TinyAgents `ModelRouter` ，用于以下角色： `chat`, `reasoning`, `agentic`, `coding`, `burst`, `summarization`和 `vision`，按其 `hint:*` 别名进行索引。它负责回退链和能力门控； `inference::provider::factory` 会将每个选定角色解析为其配置的原生 `ChatModel`；在托管后端上，则解析为固定的默认模型（`openrouter/deepseek/deepseek-v4-flash` ，除非在“设置 → 路由 → 默认模型”中更改）；没有按角色划分的层级端点。该 `burst` 角色用于低上下文、高扇出的工作进程。

## 另请参阅

* [架构概览](/openhuman/zh/kai-fa/architecture.md)：了解该 harness 在整体架构中的位置。
* [记忆](/openhuman/zh/gong-neng/memory.md) 和 [记忆架构](/openhuman/zh/kai-fa/architecture/memory.md)： `memory` 工具、每轮对话的记忆生命周期以及对话日志记录。
* [自动模型路由](/openhuman/zh/gong-neng/model-routing.md)：了解如何将 `model: "hint:reasoning"` 解析为具体的提供方和模型。
* [原生工具：智能体协调](/openhuman/zh/gong-neng/native-tools/agent-coordination.md)：面向用户的 `spawn_subagent`, `delegate_*`, `todo`.

[^1]: 技能通配符条目（`{ skills = "*" }`）不受此限制，因为它们没有指定代理：它们会展开为可通过 `Deferred` 代理可使用 `tool_search`调用的已连接 Composio 操作，而不会生成子代理。
