Agent Harness
Agent harness 是运行时，将用户消息（或 webhook 触发，或 cron tick）转换为完整的、使用工具的 LLM 交互。它拥有工具调用循环、sub-agent 调度、触发器分类管道以及围绕它们的钩子表面。
一个 turn 的形状
每个 turn——无论用户刚刚输入消息、Telegram webhook 触发、还是 9am cron tick——都经过相同的生命周期：
inbound → trigger triage → Agent::turn() → post-turn hooks
在 Agent::turn 中：
- 恢复会话 transcript（如果是新进程）
- 构建系统提示（仅首次 turn）
- 注入记忆上下文
- 进入工具调用循环
- 调度工具调用
- 上下文守卫/压缩
- 停止钩子检查
- 最终助手文本
工具调用循环
内部 Agent::turn，工具调用循环运行最多 max_tool_iterations 轮（默认 10）：
loop {
1. 上下文守卫 - 如果历史太大，微压缩/自动压缩
2. 停止钩子检查 - 预算上限、最大迭代、自定义杀死开关
3. 提供商调用 - 发送消息 + 工具规格，流式响应
4. 解析响应 - 从工具调用中分离助手文本
5. 如果无工具调用 - 返回最终文本
6. 执行工具调用 - 调度每个（下一节）
7. 总结过大 - 路由巨大工具输出通过总结器代理
8. 追加结果 - 将工具结果推入历史，循环
}
Sub-agents - 编排器模式
OpenHuman 是多 agent。用户聊天的 agent 是编排器——一个高级、策略级 agent，决定何时直接回答、何时使用直接工具、何时生成专业 sub-agent。
内置原型
| 原型 | 何时使用 |
|---|---|
orchestrator | 顶级 agent |
planner | 多步分解 |
researcher | 网络/文档查找 |
code_executor | 编写、运行、调试代码 |
critic | 代码审查 |
summarizer | 压缩过大工具结果 |
archivist | 记忆蒸馏 |
tool_maker | 自愈——为缺失命令编写 polyfill |
Spawn 层次和层级
三个层级：
chat- 快速、UX 聚焦reasoning- 慢速、深度思考worker- 叶子，什么都不能 spawn
| 层级 | 可以 spawn | 不能 spawn |
|---|---|---|
chat | reasoning, worker | 另一个 chat |
reasoning | worker | 另一个 reasoning、任何 chat |
worker | 无 | 任何东西 |
触发器分类
当 webhook 触发、cron tick 或 Composio 事件到达时，系统不能直接将其交给编排器。触发器分类管道是门：
TriggerEnvelope → run_triage → TriageDecision → apply_decision
│
├─► drop (噪音)
├─► notify only
├─► spawn trigger_reactor
└─► spawn orchestrator
钩子
停止钩子（turn 中）
停止钩子在工具调用循环的迭代之间触发。它们是预算上限、速率限制和自定义杀死开关的策略杠杆。
Post-turn 钩子
Post-turn 钩子在 turn 完成后在后台触发。内置消费者：
- Archivist - 提炼哪些事实值得持久化
- Learning - 反思、工具跟踪器、用户画像更新
- Cost log - 最终每 turn 成本行
中断
当用户按 Ctrl+C 或发送 /stop 时：
- 中断围栏翻转
- 每个运行的 sub-agent 看到相同标志并在其下一个检查点退出
- 飞行中的提供商流被丢弃
- 档案管理员仍会用任何部分上下文触发，因此对话不会丢失