1194 lines
47 KiB
Markdown
1194 lines
47 KiB
Markdown
# PicoBot 子 Agent 编排与信号投递架构升级设计
|
||
|
||
> 状态：提案（2026-08）。
|
||
>
|
||
> 本文定义具名子 Agent、委托图、多 Provider、`delegate`、`emit_signal`、后台结果收件箱、`queue`/`steer` 投递以及可唤醒 `sleep` 的目标架构。本文描述待实现设计；在实现完成并通过测试前，当前行为仍以代码和 `docs/ARCHITECTURE.md` 为准。
|
||
|
||
## 1. 背景与现状
|
||
|
||
PicoBot 已经具备一版子 Agent 能力：根交互 Agent 通过 `delegate` 创建临时 Agent，支持 `inline`、`background` 和 `parallel`，可以过滤工具、绑定计划子项、持久化后台任务，并在后台任务完成后向原 Channel 发送通知。
|
||
|
||
当前实现适合作为“一次性子任务执行器”，但还不能表达完整的多 Agent 编排：
|
||
|
||
1. 所有子 Agent 复用同一个 `LLMProviderConfig`，不能按角色选择 Provider/Model。
|
||
2. 子 Agent 没有具名、可校验的角色文件；工具权限由 `delegate.allowed_tools` 临时决定。
|
||
3. 子 Agent 被统一移除 `delegate`，不能按受控委托图继续委派。
|
||
4. `DelegateContext` 只有 session/channel/chat，没有 caller、current agent、parent run、depth 和 ancestry，无法执行多级授权。
|
||
5. `parallel` 把“委托方是否等待”和“子任务是否并发”混成一个模式。
|
||
6. 后台完成通知直接走 `MessageBus.outbound` 发给用户，不会自动成为主 Agent 的输入。
|
||
7. 当前 steering mailbox 只建模用户输入；Agent 信号若直接复用会被误标为用户消息，并继承 `/stop` 丢弃语义。
|
||
8. `SleepTool` 只等待定时器；除整个 Turn 被取消外，不能被新用户输入或 Agent 信号唤醒。
|
||
9. `send_message` 同时覆盖跨 Channel 消息、目标会话历史写入和同 Turn 附件暂存，不能作为子 Agent 内部信号的安全替代。
|
||
|
||
本设计在保留 `AgentLoop` 无状态、每 Session 单 Turn、TurnSnapshot latest-wins、持久化后才 Completed 等既有不变量的基础上，引入显式编排层。
|
||
|
||
## 2. 设计目标
|
||
|
||
### 2.1 功能目标
|
||
|
||
- 每个子 Agent 由独立 Markdown 文件定义角色、工具、Provider profile、委托目标和资源上限。
|
||
- 主 Agent 和子 Agent、子 Agent 与子 Agent 之间可以按有向权限图委托任务。
|
||
- 主 Agent 是特殊根身份，只能委托其他 Agent，永远不能成为委托目标。
|
||
- 委托执行模式收敛为成对概念 `foreground | background`。
|
||
- 单任务/批量任务与串行/并发属于调度维度，不再作为第三种执行模式。
|
||
- Background Agent 可以主动发出非终态重要信号，最终完成/失败/超时/取消由运行时自动生成终态事件。
|
||
- Background 事件使用 `queue | steer` 决定进入下一 Turn 还是当前 Turn。
|
||
- 主 Agent 忙碌、空闲、等待 sleep、正在模型调用或工具调用时都有明确、无丢失的投递语义。
|
||
- Agent 信号和后台完成结果先持久化，再通过 SessionManager 投递；Gateway 崩溃或内存唤醒丢失后可以恢复。
|
||
- `sleep` 可以由当前 session 的新输入唤醒，但不能因此破坏 queue/steer 的内容可见性边界。
|
||
- 工具、任务树、事件和结果具备有界并发、取消、超时、去重、审计和可观测性。
|
||
|
||
### 2.2 架构目标
|
||
|
||
- Agent 编排属于 `agent`/`session` 领域，不把内部 Agent 信号塞入外部 Channel 数据面。
|
||
- ToolRegistry 只提供经过角色定义和系统策略共同裁剪后的能力。
|
||
- 所有慢 I/O 在 Session 锁外执行；投递 admission、Turn 关闭和可靠 fallback 保持原子。
|
||
- Background 任务与旧运行代绑定；配置热重载不在任务中途切换角色、Provider 或工具权限。
|
||
- 完成事件、主 Agent 消费确认和 Turn 持久化使用事务与条件更新，避免内存/数据库静默分叉。
|
||
|
||
## 3. 非目标
|
||
|
||
- 不把 PicoBot 改成分布式 Agent 集群；所有运行仍在单 Gateway 进程内。
|
||
- 不恢复 Gateway 崩溃前正在进行的 Provider 流或工具调用现场。
|
||
- 不承诺外部 LLM 调用严格 exactly-once；崩溃恢复可能重新调用 Provider。
|
||
- 不允许模型在委托参数中直接指定 API key、base URL、任意工具或任意目标 session。
|
||
- 不让子 Agent 直接访问 SessionManager 内部状态。
|
||
- 不把 Agent reasoning、Provider 私有 replay state 或完整工具轨迹转发给其他 Agent、客户端或日志。
|
||
- 不默认硬中断正在进行的 Provider 请求或有副作用工具；`steer` 只保证最近安全边界注入。
|
||
- 不用本功能替代跨进程可靠监控。小时/天级持久监控仍应优先使用 Scheduler 的 monitor job。
|
||
|
||
## 4. 术语与核心语义
|
||
|
||
| 术语 | 定义 |
|
||
|------|------|
|
||
| Root Agent | 当前用户会话的主 Agent，运行时身份为 `ROOT`，不属于可寻址子 Agent 目录 |
|
||
| Agent Definition | 从一个 Markdown 文件解析出的具名角色、模型、工具、委托边和限制 |
|
||
| Agent Catalog | 当前 Gateway 运行代中全部有效 Agent Definition 的不可变快照 |
|
||
| Agent Run | 一个 Agent 对一个具体任务的执行实例 |
|
||
| Run Group | 一次批量委托创建的多个同级 Agent Run |
|
||
| Foreground | 委托方等待任务终态并直接取得结果；不代表子任务串行 |
|
||
| Background | 委托调用立即返回 run ID，任务独立执行，结果通过事件投递 |
|
||
| Queue | 输入属于后续 Turn；不改变当前 Turn 的模型上下文 |
|
||
| Steer | 输入尝试进入当前 Turn，并在最近安全边界注入；失败时可靠退化为 queue |
|
||
| Agent Signal | Background Agent 在运行中主动发出的非终态重要事件 |
|
||
| Agent Completion | Agent Run 进入 completed/failed/timed_out/cancelled/interrupted 时由运行时自动产生的终态事件 |
|
||
| Agent Inbox | 持久化的主 Agent 内部收件箱，是 Background 结果与信号的权威来源 |
|
||
| Turn Mailbox | 当前 Turn 接受 steer 输入的有界内存邮箱，保留来源、顺序和 durable event ID |
|
||
|
||
### 4.1 两个正交维度
|
||
|
||
执行方式和结果投递必须分开：
|
||
|
||
```text
|
||
执行生命周期：foreground | background
|
||
后台事件投递：queue | steer
|
||
```
|
||
|
||
多个 foreground 子任务可以并发运行，父 Agent 仍同步等待全部结果。多个 background 子任务也可以并发运行，但 `delegate` 立即返回 run IDs。并发与否由批量请求、Coordinator 调度和并发配额决定，不由 mode 名称决定。
|
||
|
||
### 4.2 Foreground 与 Background
|
||
|
||
| 行为 | Foreground | Background |
|
||
|------|------------|------------|
|
||
| `delegate` 返回时机 | 子任务进入终态后 | 任务持久化并成功接纳后 |
|
||
| 直接返回 | 结构化结果 | run ID / group ID |
|
||
| 父 Agent 当前 Turn | 阻塞等待 | 继续运行 |
|
||
| 最终结果路径 | 当前 delegate tool result | Agent Inbox event |
|
||
| 适用场景 | 当前工作依赖结果 | 长任务、监控、可稍后处理的任务 |
|
||
|
||
若当前工作必须及时依赖结果，应使用 foreground。Background 的 queue completion 不保证参与发起它的原 Turn；需要抢占式关注的重要信号应显式使用 steer。
|
||
|
||
## 5. Agent Markdown 定义
|
||
|
||
### 5.1 文件位置
|
||
|
||
第一版只从受信任配置目录加载：
|
||
|
||
```text
|
||
~/.picobot/
|
||
├── config.json
|
||
└── agents/
|
||
├── researcher.md
|
||
├── coder.md
|
||
└── reviewer.md
|
||
```
|
||
|
||
角色文件决定工具权限和委托能力，属于安全配置，不应默认从可被普通 Agent 写入的 workspace 自动加载。未来若支持 workspace 角色目录，必须由配置显式开启，并说明它不是硬安全边界。
|
||
|
||
### 5.2 文件格式
|
||
|
||
```md
|
||
---
|
||
id: researcher
|
||
description: 搜索、阅读并整理技术资料
|
||
llm_profile: research-sonnet
|
||
|
||
tools:
|
||
- file_read
|
||
- file_search
|
||
- content_search
|
||
- web_fetch
|
||
|
||
delegates:
|
||
- reviewer
|
||
|
||
limits:
|
||
timeout_secs: 900
|
||
max_iterations: 24
|
||
max_children: 4
|
||
max_depth: 3
|
||
max_result_chars: 16000
|
||
---
|
||
|
||
# Role
|
||
|
||
你是一名严谨的研究 Agent。
|
||
|
||
- 优先使用原始资料。
|
||
- 明确区分事实、推断与建议。
|
||
- 只返回与任务有关的结论、证据和不确定性。
|
||
- 不修改项目文件。
|
||
```
|
||
|
||
Frontmatter 只保存非秘密引用和限制；API key、base URL、headers 继续保存在 `config.json`/`.env`。`llm_profile` 引用现有 `config.agents` key，由 `Config::get_provider_config()` 解析 Provider 与 Model。
|
||
|
||
### 5.3 配置扩展
|
||
|
||
```json
|
||
{
|
||
"agent_orchestration": {
|
||
"definitions_dir": "~/.picobot/agents",
|
||
"root_delegates": ["researcher", "coder", "reviewer"],
|
||
"max_tree_depth": 4,
|
||
"max_runs_per_tree": 16,
|
||
"max_concurrent_runs": 6,
|
||
"max_concurrent_runs_per_session": 4,
|
||
"max_pending_inbox_events_per_session": 128,
|
||
"inbox_event_ttl_hours": 168
|
||
}
|
||
}
|
||
```
|
||
|
||
`root_delegates` 是 Root Agent 的出边白名单。Root 不需要也不允许出现在 definitions 目录中。
|
||
|
||
### 5.4 加载与校验
|
||
|
||
AgentCatalog 在 Gateway 候选运行代准备阶段完成全部校验：
|
||
|
||
- 文件大小、UTF-8、frontmatter 格式和必填字段。
|
||
- ID 格式、重复 ID、保留 ID（`ROOT`、`main` 等）。
|
||
- `llm_profile` 能解析为完整 `LLMProviderConfig`。
|
||
- 每个工具已注册且允许委托。
|
||
- 每个 delegates 目标存在且不是 Root。
|
||
- 限制值在系统硬上限内。
|
||
- 角色正文和描述长度有界。
|
||
- canonical path 位于允许目录，拒绝越界 symlink。
|
||
|
||
任一引用错误应拒绝候选运行代激活，而不是静默删除工具或委托边。AgentCatalog 以 `Arc` 固定在运行代中，已启动任务不读取修改后的文件。
|
||
|
||
## 6. 总体组件设计
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
Root[Root Agent] --> DT[DelegateTool]
|
||
Sub[Sub Agent] --> DT
|
||
DT --> C[AgentCoordinator]
|
||
C --> AC[AgentCatalog]
|
||
C --> DP[DelegationPolicy]
|
||
C --> PF[ProviderFactory]
|
||
C --> TR[Filtered ToolRegistry]
|
||
C --> AR[AgentRunner]
|
||
AR --> AL[AgentLoop]
|
||
AR --> ES[AgentEventSink]
|
||
ES --> DB[(agent_runs / agent_inbox_events)]
|
||
DB --> RR[AgentResultRouter]
|
||
RR --> SM[SessionManager]
|
||
SM --> TM[TurnMailbox / Session Queue]
|
||
TM --> Root
|
||
SM --> DC[DeliveryCoordinator]
|
||
```
|
||
|
||
### 6.1 AgentCatalog
|
||
|
||
拥有运行代内不可变的 Agent Definition，提供按 ID 查找、委托目标描述和 definition hash。主 Agent系统提示只获得 ID 与短 description，不加载所有角色正文。
|
||
|
||
### 6.2 AgentCoordinator
|
||
|
||
替代当前承担过多职责的 `SubAgentManager`，负责：
|
||
|
||
- 解析 caller/target 和授权委托边。
|
||
- 创建 run/group ID、父子关系和预算。
|
||
- 持久化接纳状态后启动 AgentRunner。
|
||
- 管理 foreground await、background spawn、取消和超时。
|
||
- 控制全局、session、Agent 与任务树并发。
|
||
- 生成自动 completion event。
|
||
- 向 WorkManager 条件提交计划子项结果。
|
||
|
||
### 6.3 AgentRunner
|
||
|
||
负责一次 Agent Run：
|
||
|
||
1. 从 Definition 和运行代创建 Provider。
|
||
2. 构造有效 ToolRegistry。
|
||
3. 组装系统规则、角色正文、任务和显式上下文。
|
||
4. 调用无状态 AgentLoop。
|
||
5. 收集最终正文、媒体、usage、工具次数和子运行引用。
|
||
6. 返回类型化终态，不直接向 Channel 发消息。
|
||
|
||
### 6.4 AgentEventSink / AgentResultRouter
|
||
|
||
`AgentEventSink` 负责持久化 signal/completion；`AgentResultRouter` 负责把 pending inbox event 送到原 root session。Router 的内存 wakeup 是加速器，SQLite inbox 才是权威来源。
|
||
|
||
### 6.5 ProviderFactory
|
||
|
||
根据 `llm_profile` 创建 Provider，注入 Storage/Observer，并复用当前运行代的 workspace、input types、token limit 和价格信息。Provider 仍是纯 HTTP client，不感知 Session、Channel 或 Agent 图。
|
||
|
||
## 7. 委托图与权限模型
|
||
|
||
### 7.1 基本规则
|
||
|
||
每次委托必须同时满足：
|
||
|
||
```text
|
||
target != ROOT
|
||
target in allowed_targets(caller)
|
||
depth < effective_max_depth
|
||
tree_run_count < max_runs_per_tree
|
||
target not in current_agent_ancestry
|
||
remaining budget > 0
|
||
runtime admission is open
|
||
```
|
||
|
||
Root 的 allowed targets 来自 `root_delegates`；子 Agent 来自自身 Markdown 的 `delegates`。
|
||
|
||
配置可以出现 A→B 和 B→A，允许两者在不同任务树中互相委托，但一个执行链默认禁止再次出现同一 Agent ID，从而拒绝 A→B→A 的递归乒乓。未来若需要受控返工循环，应设计显式 iteration workflow，而不是放开隐式递归。
|
||
|
||
### 7.2 工具权限
|
||
|
||
调用参数不再提供 `allowed_tools` 扩权。有效工具集为：
|
||
|
||
```text
|
||
AgentDefinition.tools
|
||
∩ 当前运行代已注册工具
|
||
∩ 系统可委托工具策略
|
||
```
|
||
|
||
Tool 增加安全元数据：
|
||
|
||
```rust
|
||
enum DelegationPolicy {
|
||
RootOnly,
|
||
Delegatable,
|
||
RuntimeInjected,
|
||
}
|
||
```
|
||
|
||
- `reload_config`、`todo`、管理配置和任意外部发送默认 `RootOnly`。
|
||
- 普通只读工具在明确审查后标记 `Delegatable`。
|
||
- `delegate`、`emit_signal` 等由 Coordinator 根据运行上下文注入，标记 `RuntimeInjected`，不能仅靠 Markdown 获得。
|
||
- 新工具默认 `RootOnly`，避免未来工具无意暴露。
|
||
|
||
目标 Agent 可以拥有调用方没有的专业工具，因为委托边本身就是管理员授权调用该能力；模型不能在单次调用中越过 Definition 扩权。
|
||
|
||
## 8. AgentExecutionContext
|
||
|
||
当前只含 session/channel/chat 的隐式上下文不足以支持嵌套委托。目标结构为：
|
||
|
||
```rust
|
||
pub struct AgentExecutionContext {
|
||
pub root_session_id: String,
|
||
pub root_turn_id: Option<String>,
|
||
pub run_id: String,
|
||
pub group_id: Option<String>,
|
||
pub parent_run_id: Option<String>,
|
||
pub caller_agent_id: String,
|
||
pub current_agent_id: String,
|
||
pub ancestry: Vec<String>,
|
||
pub depth: u16,
|
||
pub plan_item_id: Option<String>,
|
||
pub cancellation: CancellationToken,
|
||
pub budget: AgentBudget,
|
||
pub signal_contract: Option<SignalContract>,
|
||
}
|
||
```
|
||
|
||
`ToolExecutionContext` 扩展为包含可选 `AgentExecutionContext`、Turn wakeup handle 和资源 scope。`DelegateTool`、`EmitSignalTool` 必须实现 `execute_with_context`；权限判断不能依赖模型参数或仅依赖 Tokio task-local。
|
||
|
||
task-local 可以继续作为同一调用栈的便利桥接，但不是授权事实来源。Background spawn 必须显式复制所需上下文，不能假设 task-local 跨 `tokio::spawn` 传播。
|
||
|
||
## 9. Delegate 工具设计
|
||
|
||
### 9.1 职责
|
||
|
||
`delegate` 只负责创建 Agent Run，不再同时承担查询、取消、列表。任务管理拆给 `agent_task`：
|
||
|
||
```text
|
||
delegate → run / run_many
|
||
agent_task → get / list / cancel / get_result
|
||
```
|
||
|
||
较小、单一的 schema 能减少模型错误调用，也便于分别授权。
|
||
|
||
### 9.2 单任务请求
|
||
|
||
```json
|
||
{
|
||
"target": "researcher",
|
||
"task": "分析当前 Provider 扩展点",
|
||
"context": "重点关注热重载和 usage 持久化",
|
||
"mode": "foreground",
|
||
"plan_item_id": "T2"
|
||
}
|
||
```
|
||
|
||
### 9.3 批量请求
|
||
|
||
```json
|
||
{
|
||
"mode": "foreground",
|
||
"tasks": [
|
||
{"target": "researcher", "task": "研究方案 A"},
|
||
{"target": "coder", "task": "分析实现 B"},
|
||
{"target": "reviewer", "task": "评审风险 C"}
|
||
]
|
||
}
|
||
```
|
||
|
||
批量 foreground 的三个子任务并发执行，delegate 等待全部终态后返回聚合结果。这等价于旧 `parallel`，但不再把 parallel 当作生命周期模式。
|
||
|
||
批量 background 同样并发接纳，立即返回：
|
||
|
||
```json
|
||
{
|
||
"group_id": "group-123",
|
||
"runs": [
|
||
{"run_id": "run-a", "agent": "researcher", "status": "queued"},
|
||
{"run_id": "run-b", "agent": "coder", "status": "queued"},
|
||
{"run_id": "run-c", "agent": "reviewer", "status": "queued"}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 9.4 Background 投递契约
|
||
|
||
```json
|
||
{
|
||
"target": "service-monitor",
|
||
"task": "监控服务错误率",
|
||
"mode": "background",
|
||
"delivery": {
|
||
"signal": "steer",
|
||
"completion": "queue",
|
||
"failure": "steer"
|
||
}
|
||
}
|
||
```
|
||
|
||
- `signal`：运行中主动事件的投递方式。
|
||
- `completion`：正常终态结果的投递方式，默认 queue。
|
||
- `failure`：失败、超时、异常中断的投递方式，默认 queue，可显式 steer。
|
||
|
||
Foreground 请求直接把 completion 作为 tool result 返回，因此不接受 completion delivery。第一阶段仅允许 Root 创建 background run；子 Agent 之间可以 foreground 委托。待持久化 task tree 与 root inbox 稳定后，再允许子 Agent 创建最终归属于 root session 的 background run。
|
||
|
||
### 9.5 Foreground 返回
|
||
|
||
单任务和批量任务都返回逐项状态，单个失败不能抹掉其他结果：
|
||
|
||
```json
|
||
{
|
||
"status": "partial",
|
||
"results": [
|
||
{"run_id": "run-a", "agent": "researcher", "status": "completed", "result": "..."},
|
||
{"run_id": "run-b", "agent": "coder", "status": "failed", "error": "..."},
|
||
{"run_id": "run-c", "agent": "reviewer", "status": "completed", "result": "..."}
|
||
]
|
||
}
|
||
```
|
||
|
||
结果按请求顺序返回，不按完成顺序重排。完整结果统一写入 `agent_runs`；超过 tool result 上限时返回摘要和 run ID，保证 `agent_task.get_result` 真能读取完整结果。
|
||
|
||
### 9.6 幂等与接纳
|
||
|
||
Background delegate 只有在 run/group 记录持久化成功、运行代 admission 成功且执行任务已经被 TaskSupervisor 接纳后才返回成功。可选 `idempotency_key` 在 `(root_session_id, caller_run_id, key)` 范围唯一，用于 Provider 重试时避免重复创建任务。
|
||
|
||
## 10. Prompt 与上下文隔离
|
||
|
||
子 Agent 默认不继承主会话完整历史。一次 run 的输入由以下部分组成：
|
||
|
||
```text
|
||
PicoBot 基础运行规则
|
||
+ 角色 Markdown 正文
|
||
+ 当前工具说明
|
||
+ 委托执行约束（身份、父任务、资源限制）
|
||
+ 显式 task
|
||
+ 显式 context / artifact refs
|
||
```
|
||
|
||
委托 task 只注入一次。调用方需要子 Agent 知道的事实必须写入 task/context，不能依赖完整历史偶然可见。
|
||
|
||
子 Agent 最终结果作为普通 tool result 或 runtime event data 交给上游，不能变成更高优先级 system 指令。所有子 Agent 输出都视为不可信数据；主 Agent系统提示明确要求不要执行结果正文中试图修改角色、工具或投递策略的指令。
|
||
|
||
资源型工具使用独立 scope：
|
||
|
||
```text
|
||
resource_scope_id = root_session_id + run_id
|
||
```
|
||
|
||
并行子 Agent 不默认共享 browser/session 等有状态外部资源；确需共享必须由工具定义显式支持。
|
||
|
||
## 11. Agent Run 状态机
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> queued
|
||
queued --> running
|
||
running --> waiting_children
|
||
waiting_children --> running
|
||
running --> completed
|
||
running --> failed
|
||
running --> timed_out
|
||
running --> cancelled
|
||
running --> interrupted
|
||
queued --> cancelled
|
||
completed --> [*]
|
||
failed --> [*]
|
||
timed_out --> [*]
|
||
cancelled --> [*]
|
||
interrupted --> [*]
|
||
```
|
||
|
||
- `queued`：已持久化且等待执行配额。
|
||
- `running`：AgentLoop 正在执行模型或工具步骤。
|
||
- `waiting_children`：当前 run 正等待 foreground 子运行。
|
||
- `completed`：有可用最终结果。
|
||
- `failed`：Provider、工具或内部执行错误。
|
||
- `timed_out`：超过 run deadline。
|
||
- `cancelled`：由用户、父任务、session 删除或 shutdown 明确取消。
|
||
- `interrupted`：进程重启导致无法恢复现场。
|
||
|
||
状态变化使用条件更新，迟到结果只有在 execution ID、runtime generation 和当前状态匹配时才能提交。
|
||
|
||
## 12. Agent 信号与自动 Completion
|
||
|
||
### 12.1 两种事件
|
||
|
||
| 事件 | 产生者 | 是否终止 run | 用途 |
|
||
|------|--------|--------------|------|
|
||
| Signal | 子 Agent 主动调用 `emit_signal` | 否 | 重要中间状态、监控告警 |
|
||
| Completion | AgentCoordinator 自动生成 | 是 | completed/failed/timed_out/cancelled/interrupted |
|
||
|
||
最终结果不能依赖模型记得调用工具。即使 Provider 异常、超时或任务被取消，Coordinator 也必须产生终态事件。
|
||
|
||
### 12.2 EmitSignalTool
|
||
|
||
```json
|
||
{
|
||
"key": "service-error-threshold",
|
||
"severity": "critical",
|
||
"summary": "服务错误率超过 5%",
|
||
"details": {
|
||
"current": 0.071,
|
||
"threshold": 0.05
|
||
},
|
||
"dedupe_key": "service-a:error-rate"
|
||
}
|
||
```
|
||
|
||
`emit_signal` 不接受 target session、channel、chat ID 或 delivery 参数。目标、queue/steer、最大次数、速率和 root session 全部来自 `AgentExecutionContext.signal_contract`。
|
||
|
||
工具调用只有在 signal event 持久化后才成功返回：
|
||
|
||
```json
|
||
{
|
||
"signal_id": "signal-123",
|
||
"status": "accepted",
|
||
"delivery": "steer"
|
||
}
|
||
```
|
||
|
||
Coordinator 强制执行：
|
||
|
||
- 每 run 信号总数与累计字节上限。
|
||
- 最小发送间隔和 burst 上限。
|
||
- dedupe key 冷却窗口。
|
||
- severity allowlist。
|
||
- summary/details 大小与 JSON 深度限制。
|
||
- 只能投递到创建该 run 的 root session。
|
||
|
||
普通进度不应滥用 signal。工具调用进度继续通过内部 Observer/TurnEvent 投影到 UI；只有需要主 Agent采取行动的事件才使用 `emit_signal`。
|
||
|
||
### 12.3 Completion 去重
|
||
|
||
Completion 包含本 run 已发出的 signal IDs。若最终总结重复某个信号，主 Agent可以识别并避免再次报告。正常 completion 可以配置 queue；关键 failure 可以配置 steer。禁止完全静默丢弃失败，`silent` 若未来开放也只能用于正常 completion。
|
||
|
||
## 13. SendMessage、EmitSignal 与附件职责
|
||
|
||
三者方向不同，不合并为一个万能工具：
|
||
|
||
```text
|
||
emit_signal 子 Agent → Agent Inbox → 主 Agent（内部输入）
|
||
send_message Agent → OutboundDispatcher → Channel/用户（外部输出）
|
||
attach_artifact 工具产物 → 当前 Turn → DeliveryCoordinator（当前回复附件）
|
||
```
|
||
|
||
### 13.1 send_message
|
||
|
||
只负责用户明确授权的跨 Channel/跨会话外部消息，具有真实外部副作用。默认 `RootOnly`，目标和文件参数继续受 Channel/file transfer 限制。`origin` 不再由模型自由填写，改由 ToolExecutionContext 生成，避免来源伪造。
|
||
|
||
### 13.2 emit_signal
|
||
|
||
只负责后台子 Agent 的结构化内部事件。它没有任意目标、媒体或直接用户投递能力，不写目标会话 assistant history。
|
||
|
||
### 13.3 attach_artifact
|
||
|
||
当前 `send_message(files=...)` 对同 session 的特殊暂存行为长期应拆成 `attach_artifact` 或统一 ToolResult media side channel。短期保留兼容路径，但新子 Agent 信号设计不得依赖它。
|
||
|
||
### 13.4 自动 completion
|
||
|
||
Completion 不是工具。AgentRunner 的终结路径统一保存结果并创建 event，避免模型遗漏。
|
||
|
||
## 14. 持久化模型
|
||
|
||
### 14.1 agent_runs
|
||
|
||
```text
|
||
agent_runs
|
||
----------
|
||
id TEXT PRIMARY KEY
|
||
group_id TEXT
|
||
root_session_id TEXT NOT NULL
|
||
root_turn_id TEXT
|
||
parent_run_id TEXT
|
||
caller_agent_id TEXT NOT NULL
|
||
agent_id TEXT NOT NULL
|
||
definition_hash TEXT NOT NULL
|
||
provider_profile TEXT NOT NULL
|
||
provider_name TEXT NOT NULL
|
||
model_id TEXT NOT NULL
|
||
mode TEXT NOT NULL
|
||
depth INTEGER NOT NULL
|
||
plan_item_id TEXT
|
||
task TEXT NOT NULL
|
||
context_json TEXT
|
||
status TEXT NOT NULL
|
||
result TEXT
|
||
error TEXT
|
||
prompt_tokens INTEGER
|
||
completion_tokens INTEGER
|
||
cost REAL
|
||
tool_calls_count INTEGER NOT NULL DEFAULT 0
|
||
iterations INTEGER NOT NULL DEFAULT 0
|
||
runtime_generation TEXT NOT NULL
|
||
attempt INTEGER NOT NULL DEFAULT 1
|
||
started_at INTEGER
|
||
finished_at INTEGER
|
||
created_at INTEGER NOT NULL
|
||
```
|
||
|
||
不保存 API key、Authorization header、Provider 私有 reasoning state 或完整 connection URL。
|
||
|
||
### 14.2 agent_run_groups
|
||
|
||
```text
|
||
agent_run_groups
|
||
----------------
|
||
id
|
||
root_session_id
|
||
caller_run_id
|
||
mode
|
||
completion_policy all | each
|
||
expected_runs
|
||
terminal_runs
|
||
deadline_at
|
||
status
|
||
created_at
|
||
finished_at
|
||
```
|
||
|
||
批量 background 默认 `completion_policy=all`，等全部 run 进入终态或 group deadline 后只唤醒主 Agent一次。独立 run 可通过 300–500ms debounce 合并，避免连续启动多个内部 Turn。
|
||
|
||
### 14.3 agent_inbox_events
|
||
|
||
```text
|
||
agent_inbox_events
|
||
------------------
|
||
id TEXT PRIMARY KEY
|
||
root_session_id TEXT NOT NULL
|
||
run_id TEXT NOT NULL
|
||
group_id TEXT
|
||
event_type signal | completion
|
||
event_key TEXT NOT NULL
|
||
delivery queue | steer
|
||
severity TEXT
|
||
payload_json TEXT NOT NULL
|
||
status pending | leased | admitted | consumed | dead_letter
|
||
attempt_count INTEGER NOT NULL DEFAULT 0
|
||
lease_token TEXT
|
||
lease_until INTEGER
|
||
admitted_turn_id TEXT
|
||
created_at INTEGER NOT NULL
|
||
consumed_at INTEGER
|
||
|
||
UNIQUE(run_id, event_type, event_key)
|
||
```
|
||
|
||
完整结果保存在 `agent_runs.result`，inbox payload 默认只放有界摘要、元数据和 result reference，避免复制大文本。
|
||
|
||
### 14.4 原子事务
|
||
|
||
Agent completion 必须在一个 Storage 事务中：
|
||
|
||
```text
|
||
UPDATE agent_runs terminal state/result/usage
|
||
UPDATE agent_run_groups terminal count/status
|
||
INSERT agent_inbox_events ... ON CONFLICT DO NOTHING
|
||
UPDATE bound task item by execution_id
|
||
COMMIT
|
||
```
|
||
|
||
事务失败时不能对外宣称任务完成。内存 wakeup 只有在 commit 成功后发送。
|
||
|
||
## 15. Background 事件投递
|
||
|
||
### 15.1 统一输入类型
|
||
|
||
当前 user-only SteeringMailbox 演进为保留来源的 TurnMailbox：
|
||
|
||
```rust
|
||
pub struct TurnInput {
|
||
pub id: String,
|
||
pub sequence: u64,
|
||
pub source: TurnInputSource,
|
||
pub delivery: InputDelivery,
|
||
pub content: String,
|
||
pub media_refs: Vec<MediaRef>,
|
||
pub durable_event_id: Option<String>,
|
||
pub received_at: i64,
|
||
}
|
||
|
||
pub enum TurnInputSource {
|
||
User,
|
||
AgentSignal { run_id: String, agent_id: String },
|
||
AgentCompletion { run_id: String, agent_id: String },
|
||
}
|
||
|
||
pub enum InputDelivery {
|
||
Queue,
|
||
Steer,
|
||
}
|
||
```
|
||
|
||
`SourceKind` 增加 `agent_signal`、`agent_result`。Provider 不支持 runtime role 时可以序列化为有明确 envelope 的 user-compatible message，但持久化来源、客户端渲染和取消恢复必须保持类型，不得显示成用户气泡。
|
||
|
||
### 15.2 路由规则
|
||
|
||
| 主 Agent 状态 | queue | steer |
|
||
|----------------|-------|-------|
|
||
| 无活动 Turn | 入 session queue，启动内部 Turn | 退化为 queue，启动内部 Turn |
|
||
| 活动 Turn 接受输入 | 入下一 Turn | 入当前 TurnMailbox |
|
||
| TurnMailbox 满/已关闭 | 保持 durable pending 后排队 | 可靠退化为 queue |
|
||
| Provider 请求进行中 | 等下一 Turn | 等请求结束后的安全边界 |
|
||
| 普通工具批次进行中 | 等下一 Turn | 等完整工具批次结束 |
|
||
| sleep 进行中 | 唤醒 sleep，内容仍留在 queue | 唤醒 sleep，并在工具批次后注入当前 Turn |
|
||
|
||
Steer 不承诺硬实时抢占。最迟可见时间由当前不可分割 Provider 请求或工具步骤决定。需要当前逻辑必然依赖子结果时应使用 foreground；不要用 background+steer 模拟同步调用。
|
||
|
||
### 15.3 原子 admission 与 fallback
|
||
|
||
AgentResultRouter 对 steer 事件执行与用户 steering 相同级别的原子判定：
|
||
|
||
1. 获取目标 Session。
|
||
2. 在 Session 状态锁内分配单调 sequence。
|
||
3. 若 active Turn 正在 accepting，尝试 push TurnMailbox。
|
||
4. 若 closed/full/不存在，创建内部 AgentTask 放入有界 session queue。
|
||
5. 内存 admission 结果与 durable event lease 关联。
|
||
|
||
任何竞态下事件只能属于当前 Turn 或后续 Turn之一，不能同时进入两者，也不能两者都不进入。Session queue 饱和时事件继续保持 durable pending，由 Router 重试；不能像普通瞬时通知一样丢弃。
|
||
|
||
### 15.4 Mailbox 容量与公平性
|
||
|
||
用户输入和 Agent 事件共享接收顺序，但使用独立容量配额，避免相互挤占：
|
||
|
||
```text
|
||
user steer lane: 32 messages / 64 KiB
|
||
agent event lane: 8 messages / 32 KiB
|
||
```
|
||
|
||
排空时按 session sequence 合并。重要 AgentSignal 可以保留专用容量，但不默认越过更早已接受的用户输入。信号洪泛由 emit_signal rate limit 和 inbox 上限共同控制。
|
||
|
||
### 15.5 安全边界注入
|
||
|
||
AgentLoop 只在以下边界排空 steer：
|
||
|
||
- 一个完整工具批次结束后。
|
||
- Provider 返回无工具候选最终回复、但 mailbox 有新输入时。
|
||
- 明确可安全取消的等待工具被唤醒后。
|
||
|
||
输入被排空后保留为 in-flight，只有整个 Turn 消息和 event consumption 原子提交成功才确认。Provider/工具/持久化失败时恢复原事件。
|
||
|
||
## 16. 主 Agent 忙碌与空闲
|
||
|
||
### 16.1 主 Agent 忙碌
|
||
|
||
- queue event 只进入后续内部任务，不改变当前上下文。
|
||
- steer event 进入 TurnMailbox，在安全边界参与当前 Turn。
|
||
- 当前 Turn 已 finalizing/closed 时，steer 自动退化为 queue。
|
||
- UI 可以立即展示“信号已接纳/后台任务已完成”，但用户可见最终结论仍由主 Agent产生。
|
||
|
||
### 16.2 主 Agent 空闲
|
||
|
||
Session worker 不做固定频率忙轮询。正常路径由 AgentResultRouter 发出 best-effort session wakeup；worker 被唤醒后领取 inbox event 并创建内部 Turn。Gateway 启动、reload 激活和周期恢复任务扫描 pending/expired lease，弥补丢失唤醒。
|
||
|
||
Session worker 调度优先级：
|
||
|
||
```text
|
||
当前活动 Turn
|
||
> 已排队用户输入
|
||
> queue background result continuation
|
||
> 等待新事件
|
||
```
|
||
|
||
Steer event 在没有活动 Turn 时按 queue 处理。用户输入优先避免后台总结打断新请求；UI 未读状态避免持续用户流量下结果不可见。
|
||
|
||
### 16.3 内部 continuation Turn
|
||
|
||
内部任务不是伪造的 InboundMessage：
|
||
|
||
```rust
|
||
enum AgentTaskSource {
|
||
UserInput,
|
||
BackgroundAgentResults { event_ids: Vec<String>, group_id: Option<String> },
|
||
ScheduledTask,
|
||
}
|
||
```
|
||
|
||
SessionManager 直接把领取的结果构造成 bounded runtime context，并加入一个内部触发语义：“检查这些后台结果，结合原始目标验证和汇总，再向用户报告。”内部输入不显示用户气泡；主 Agent输出按普通 assistant Turn 持久化和投递。
|
||
|
||
### 16.4 消费确认
|
||
|
||
领取流程：
|
||
|
||
```text
|
||
pending → leased → admitted → consumed
|
||
```
|
||
|
||
`lease_token` 防止重复 worker 处理。同一事务必须保存主 Agent Turn 和把对应 inbox events 标记 consumed。若 AgentLoop 失败、Turn 取消或 Gateway 崩溃，lease 到期后事件恢复 pending。
|
||
|
||
外部 LLM 调用无法严格 exactly-once。为降低恢复重跑的副作用，background result continuation 默认只开放只读/汇总工具；需要外部写操作时由主 Agent向用户确认，或工具自身使用幂等键。
|
||
|
||
## 17. 可唤醒 Sleep 设计
|
||
|
||
### 17.1 目标语义
|
||
|
||
`sleep` 仍是最长 24 小时、不可持久恢复的前台等待工具，但当前 session 接收到任何新输入时立即结束等待：
|
||
|
||
- user steer
|
||
- user queue
|
||
- AgentSignal queue/steer
|
||
- AgentCompletion queue/steer
|
||
- `/stop`、shutdown 和父 cancellation
|
||
|
||
Sleep 只负责唤醒，不负责消费输入。queue 内容仍属于下一 Turn；steer 内容仍由 TurnMailbox 在工具批次后注入。
|
||
|
||
### 17.2 Wakeup handle
|
||
|
||
`ToolExecutionContext` 增加：
|
||
|
||
```rust
|
||
pub struct TurnWakeupHandle {
|
||
pub receiver: watch::Receiver<TurnWakeupState>,
|
||
}
|
||
|
||
pub struct TurnWakeupState {
|
||
pub revision: u64,
|
||
pub pending_steer: usize,
|
||
pub pending_queue: usize,
|
||
pub latest_source: WakeupSource,
|
||
pub latest_preview: Option<String>,
|
||
}
|
||
```
|
||
|
||
使用 watch revision 而不是裸 Notify，避免输入恰好在 sleep 开始监听前到达而丢失唤醒。执行前先比较当前 revision/pending，再进入 select。
|
||
|
||
### 17.3 Sleep 执行
|
||
|
||
```rust
|
||
tokio::select! {
|
||
_ = tokio::time::sleep(duration) => SleepOutcome::Elapsed,
|
||
changed = wakeup.changed() => SleepOutcome::InputArrived(changed),
|
||
_ = cancellation.cancelled() => SleepOutcome::Cancelled,
|
||
}
|
||
```
|
||
|
||
返回示例：
|
||
|
||
```text
|
||
Sleep 提前结束：已等待 37 秒。
|
||
收到一条 steer AgentSignal（run_id=run-123）：服务错误率超过 5%。
|
||
该信号将在当前 Turn 的下一个安全边界注入。
|
||
```
|
||
|
||
queue 输入不能把正文泄漏给当前 Turn，否则等价于偷偷 steer。其返回只能说明类型和数量：
|
||
|
||
```text
|
||
Sleep 提前结束：收到一条排队输入。
|
||
内容不会进入当前 Turn，将在当前工作结束后的下一 Turn处理。
|
||
```
|
||
|
||
### 17.4 工具中断策略
|
||
|
||
新增工具元数据：
|
||
|
||
```rust
|
||
enum InputInterruptPolicy {
|
||
Never,
|
||
WakeOnly,
|
||
CancelSafe,
|
||
}
|
||
```
|
||
|
||
- `sleep`：`WakeOnly`，输入使工具正常提前返回。
|
||
- 明确只读且可重试的等待工具可标记 `CancelSafe`。
|
||
- bash、写文件、发送消息和未知外部副作用工具默认 `Never`。
|
||
|
||
Steer 不自动取消 `Never` 工具。未来若需要硬抢占，应新增独立 `interrupt` 策略并定义 partial tool 状态、幂等和恢复；本设计不把它隐含进 steer。
|
||
|
||
## 18. 取消、停止与恢复
|
||
|
||
### 18.1 Foreground 结构化取消
|
||
|
||
Foreground 子 run 是父 run 的结构化子任务：
|
||
|
||
- 父 Turn 取消会取消所有未终态 foreground 后代。
|
||
- timeout token 与父 cancellation token 组合。
|
||
- run 进入 waiting_children 时仍保留所有权，但不能长期占用模型执行 permit。
|
||
- 父取消后迟到结果不能提交为 completed。
|
||
|
||
### 18.2 Background 所有权
|
||
|
||
Background run 归 root session 所有，不归发起它的模型 future 所有。Root Turn结束不会自动取消它。
|
||
|
||
保留当前 `/stop` 的明确停止语义：取消目标 session 的 active Turn、排队用户输入以及所有非 Scheduler background Agent run。需要跨 `/stop` 和重启长期存在的监控应创建 Scheduler monitor，而不是普通 background delegate。
|
||
|
||
### 18.3 `/stop` 与 durable Agent events
|
||
|
||
用户 steering 按现有语义可被 `/stop` 丢弃；已经持久化的 AgentSignal/Completion 不能静默消失：
|
||
|
||
- 已进入 current Turn 但尚未提交的 durable event 恢复 pending。
|
||
- 被取消 background run 产生 cancelled completion，供 UI/主 Agent获知。
|
||
- 用户显式执行 `agent_task.cancel` 后，可以将该 run 未消费的普通 signal 标记 superseded，但保留审计记录。
|
||
|
||
### 18.4 Gateway reload
|
||
|
||
AgentCatalog、ProviderFactory、Coordinator 和 inbox router 属于 Gateway runtime generation：
|
||
|
||
- reload 关闭 admission 后不接受新 background run/signal。
|
||
- 已进入旧代的 run 固定使用旧 definition hash、Provider 和工具策略。
|
||
- 排空期等待前台 Turn、Scheduler 和 background run 到持久化边界。
|
||
- 超过总排空期限的 run 被取消/中断并写终态事件。
|
||
- pending inbox event 留在 SQLite，由新运行代恢复投递。
|
||
|
||
### 18.5 进程重启
|
||
|
||
进程退出后无法恢复正在进行的 LLM stream。启动恢复将旧 `running/waiting_children` 标记 `interrupted` 并生成 completion。普通有副作用 Agent run 不自动重试；只读、显式配置 idempotency/restart policy 的监控任务可以创建新 attempt，并保留原 run 的中断记录。
|
||
|
||
## 19. 并发、预算与死锁避免
|
||
|
||
### 19.1 限制层次
|
||
|
||
```text
|
||
Gateway 全局 active provider/tool permits
|
||
└── per-session permits
|
||
└── per-agent permits
|
||
└── per-tree max runs/depth/children/token/cost
|
||
```
|
||
|
||
批量请求必须有 `maxItems`，Coordinator 还会按剩余 tree budget 裁剪/拒绝，不能让模型生成任意数量任务。
|
||
|
||
### 19.2 父子等待死锁
|
||
|
||
不能让一个等待 foreground child 的父 run 一直持有唯一执行 permit，否则并发上限为 1 时形成：
|
||
|
||
```text
|
||
父 run 持有 permit → 等子 run → 子 run 永远拿不到 permit
|
||
```
|
||
|
||
permit 应限制活跃 Provider/工具步骤，而不是整个 Agent Run 生命周期。父 run 进入 `waiting_children` 前释放执行 permit，子 run 完成后父 run 再竞争 permit 继续模型迭代。Task tree ownership、timeout 和 cancellation 不随 permit 释放而消失。
|
||
|
||
### 19.3 预算传播
|
||
|
||
每次子委托从父 budget 派生硬上限：
|
||
|
||
```text
|
||
child deadline <= parent deadline
|
||
child max depth <= remaining depth
|
||
sum child token/cost reservation <= remaining tree budget
|
||
```
|
||
|
||
调用方可以收紧 timeout/结果大小，但不能超过 Agent Definition 和系统上限。
|
||
|
||
## 20. 可观测性与客户端表现
|
||
|
||
### 20.1 运行树
|
||
|
||
WebUI 管理面展示：
|
||
|
||
- group/run/parent ID。
|
||
- Agent ID、Provider profile、Model。
|
||
- queued/running/waiting_children/terminal 状态。
|
||
- signal 数量和最近 severity。
|
||
- duration、usage、cost、工具次数。
|
||
- 取消/超时/中断原因。
|
||
|
||
### 20.2 Chat 表现
|
||
|
||
- Foreground delegate 继续作为当前 Turn 的可折叠工具块。
|
||
- Background delegate 启动后显示 run/group ID，不假装任务已完成。
|
||
- AgentSignal 显示为独立运行时信号卡片，不显示成用户气泡。
|
||
- queue completion 在主 Agent内部 continuation 后只显示主 Agent汇总回复。
|
||
- steer 信号可以在当前 Turn 工具状态中显示“已接纳”，最终历史由 Turn commit 校准。
|
||
|
||
### 20.3 隐私与日志
|
||
|
||
- 不显示/记录 Agent reasoning 和 Provider 私有 state。
|
||
- 默认日志只记录 run ID、Agent ID、状态、duration、usage 和截断错误。
|
||
- task/result 正文不进入 info 日志。
|
||
- API key、headers、临时凭据、含 credential URL 永不落库或日志。
|
||
|
||
## 21. 失败语义
|
||
|
||
| 失败点 | 对外语义 |
|
||
|--------|----------|
|
||
| Agent Definition 无效 | 拒绝候选运行代；旧代继续服务 |
|
||
| 委托边不允许 | delegate 立即返回 permission denied，不创建 run |
|
||
| Background 持久化失败 | delegate 返回失败，不报告 run ID |
|
||
| TaskSupervisor 拒绝 spawn | run 条件更新 cancelled/failed，再返回失败 |
|
||
| Provider 创建失败 | run failed，foreground 返回错误；background 生成 failure event |
|
||
| Inbox wakeup 丢失 | pending event 由恢复扫描重新唤醒 |
|
||
| TurnMailbox closed/full | steer 可靠退化 queue |
|
||
| Session queue 满 | durable event 保持 pending，Router 有界重试 |
|
||
| Main continuation Provider 失败 | event lease 到期并重试；不标 consumed |
|
||
| 主 Agent回复持久化失败 | event 不确认，避免结果消失 |
|
||
| Channel 最终投递失败 | assistant history已持久化；沿用 DeliveryCoordinator terminal fallback |
|
||
|
||
所有重试必须有次数、退避、deadline 和分类；永久错误立即终态化，不能无界重试。
|
||
|
||
## 22. 兼容迁移
|
||
|
||
### 22.1 Delegate 参数
|
||
|
||
旧模式映射：
|
||
|
||
```text
|
||
inline → foreground
|
||
parallel → foreground + tasks[]
|
||
background → background
|
||
async → background（若曾接受该别名）
|
||
```
|
||
|
||
过渡期解析旧参数并在 tool result/日志中给出弃用提示；新 system prompt 只描述 canonical 值 `foreground/background`。
|
||
|
||
### 22.2 allowed_tools
|
||
|
||
旧 `allowed_tools` 首先变成只能收紧 Definition.tools 的兼容字段，不能扩权；随后从 schema 删除。没有 target 的旧委托映射到内置 `general` Agent Definition。
|
||
|
||
### 22.3 background_tasks
|
||
|
||
新增 `agent_runs` 后：
|
||
|
||
- 新任务只写新表。
|
||
- 管理 API 在过渡期 union 读取旧 `background_tasks` 与新 `agent_runs`。
|
||
- 旧终态记录按原 TTL 清理，不强制迁移正文。
|
||
- 旧 pending/running 记录在升级启动时按 interrupted/cancelled 规则收敛。
|
||
|
||
### 22.4 版本与文档
|
||
|
||
本设计文档本身不改变产品行为。实现功能合并时按项目规则增加中段版本，并同步更新 README、`docs/ARCHITECTURE.md`、AGENTS.md 和 `resources/skills/about-picobot/references/`。
|
||
|
||
## 23. 实现分期
|
||
|
||
### Phase 1：具名 Agent 与 Foreground
|
||
|
||
- 新增 AgentDefinition/AgentCatalog loader。
|
||
- Definition 解析不同 Provider profile 和固定工具集。
|
||
- Delegate schema 使用 target + foreground/background canonical modes。
|
||
- 批量 foreground 并发执行并聚合。
|
||
- 显式 AgentExecutionContext 和委托图授权。
|
||
- 保持旧 background 通知路径作为兼容，但不开放嵌套 background。
|
||
|
||
### Phase 2：统一 Agent Run 持久化
|
||
|
||
- 新增 `agent_runs`、`agent_run_groups`、Storage transaction API。
|
||
- 拆分 `delegate` 与 `agent_task`。
|
||
- Foreground 结果也持久化，修复截断结果不可查询。
|
||
- 实现结构化取消、预算与 permit 释放。
|
||
|
||
### Phase 3：Agent Inbox 与 Queue Completion
|
||
|
||
- 新增 `agent_inbox_events`、lease、恢复扫描。
|
||
- Background completion 从 Channel direct notification 改为主 Agent内部 continuation。
|
||
- 增加 SourceKind::AgentResult、内部 AgentTask 和 WebUI 投影。
|
||
- 批次 completion 合并与 debounce。
|
||
|
||
### Phase 4：Emit Signal 与 Steer
|
||
|
||
- 新增 EmitSignalTool、SignalContract 和 rate/dedupe。
|
||
- SteeringMailbox 泛化为来源感知 TurnMailbox。
|
||
- 实现 steer admission、queue fallback、durable ack/recovery。
|
||
- 添加 AgentSignal UI 和任务树。
|
||
|
||
### Phase 5：可唤醒 Sleep 与工具中断元数据
|
||
|
||
- ToolExecutionContext 增加 TurnWakeupHandle。
|
||
- SleepTool 使用 watch revision + timer + cancellation select。
|
||
- queue/steer 唤醒内容边界和测试。
|
||
- 为工具增加 InputInterruptPolicy，默认 Never。
|
||
|
||
## 24. 预计代码边界
|
||
|
||
建议模块拆分：
|
||
|
||
```text
|
||
src/agent/
|
||
├── definition.rs AgentDefinition / loader
|
||
├── catalog.rs immutable AgentCatalog
|
||
├── coordinator.rs authorization / lifecycle / budgets
|
||
├── run.rs AgentRun types / AgentRunner
|
||
├── inbox.rs event types / router contracts
|
||
└── sub_agent.rs 迁移兼容层，最终缩减或删除
|
||
|
||
src/tools/
|
||
├── delegate.rs create run/group only
|
||
├── agent_task.rs get/list/cancel/get_result
|
||
├── emit_signal.rs constrained internal signal
|
||
├── sleep.rs wake-aware wait
|
||
└── send_message.rs external delivery only
|
||
|
||
src/session/
|
||
├── turn_mailbox.rs typed steer inputs
|
||
├── agent_inbox.rs claim/admit/ack orchestration
|
||
└── session.rs typed AgentTask scheduling
|
||
|
||
src/storage/
|
||
├── agent_run.rs
|
||
└── agent_inbox.rs
|
||
```
|
||
|
||
`AgentLoop` 只需要理解来源感知输入的安全边界追加，不拥有 AgentCatalog、任务树或 inbox persistence。
|
||
|
||
## 25. 测试矩阵
|
||
|
||
### 25.1 Definition 与授权
|
||
|
||
- 解析合法 Markdown、frontmatter 与 Unicode 正文。
|
||
- 重复/保留 ID、未知 Provider、未知工具、未知 delegate target 拒绝加载。
|
||
- path traversal/symlink 越界拒绝。
|
||
- Root 永远不能成为 target。
|
||
- 未声明 A→B 时拒绝；声明后允许。
|
||
- A→B→A 在单链中拒绝。
|
||
- 模型参数不能扩大工具、timeout、depth 或预算。
|
||
|
||
### 25.2 Foreground/Background
|
||
|
||
- 单 foreground 结果立即成为父 tool result。
|
||
- 三个 foreground task 并发执行、父等待全部、结果按请求顺序。
|
||
- 单项失败不丢其他项结果。
|
||
- Background 只有持久化并成功 spawn 后才返回 run ID。
|
||
- 同 idempotency key 不重复创建 run。
|
||
- Background completion 不直接伪装为用户消息。
|
||
|
||
### 25.3 Provider 与工具
|
||
|
||
- 不同 Agent 使用不同 provider/model profile。
|
||
- Provider storage/observer 正确注入。
|
||
- RootOnly 工具不能通过 Markdown 或兼容 allowed_tools 获得。
|
||
- runtime-injected delegate/emit_signal 只在上下文允许时存在。
|
||
- 并行 run 的 browser/resource scope 隔离。
|
||
|
||
### 25.4 Inbox 与投递竞态
|
||
|
||
- completion update 与 inbox insert 原子。
|
||
- wakeup 丢失后启动扫描恢复。
|
||
- active accepting Turn 的 steer 进入 current Turn。
|
||
- finalizing/closed/full 时 steer 恰好一次退化 queue。
|
||
- 无活动 Turn 的 steer 启动内部 continuation。
|
||
- 用户队列优先于 queue completion。
|
||
- Turn persist 失败时 event 不 consumed。
|
||
- lease 超时后可重领，旧 lease token 不能提交。
|
||
- 多 run group 只触发一次汇总 Turn。
|
||
|
||
### 25.5 Signal
|
||
|
||
- emit_signal 无上下文或 foreground 禁止策略时失败。
|
||
- 不能指定任意 target/channel/delivery。
|
||
- dedupe key、速率、数量和大小上限生效。
|
||
- signal 不结束 Agent Run。
|
||
- Agent 异常退出仍自动生成 failure completion。
|
||
- 已发 signal IDs 出现在 completion，避免重复汇报。
|
||
|
||
### 25.6 Sleep
|
||
|
||
- 无输入时精确等待至 timer。
|
||
- user steer、AgentSignal steer 立即唤醒并随后注入当前 Turn。
|
||
- user queue、AgentCompletion queue 唤醒但正文不泄漏当前 Turn。
|
||
- 输入先于 sleep 订阅时 revision 检查仍立即返回。
|
||
- 多条输入只消费一次且顺序稳定。
|
||
- `/stop`、parent cancellation、shutdown 取消 sleep 并终态化工具块。
|
||
- wakeup 与 timer 同时发生时不丢输入；输入若未入当前 Turn则可靠排队。
|
||
|
||
### 25.7 取消、并发与恢复
|
||
|
||
- 父 foreground 取消级联后代。
|
||
- 父 waiting_children 不持有唯一 permit，无死锁。
|
||
- `/stop` 取消 session background runs，并恢复未提交 durable events。
|
||
- 迟到结果不能覆盖 cancelled/interrupted。
|
||
- reload 关闭 admission 后拒绝新 run/signal，pending inbox 由新代恢复。
|
||
- Gateway 重启把 running 标记 interrupted 并生成 completion。
|
||
- session 删除/归档后的事件按明确 dead-letter/cancel 策略收敛。
|
||
|
||
### 25.8 消息与客户端
|
||
|
||
- AgentSignal 不渲染为用户气泡。
|
||
- Internal continuation 输入不出现在普通历史，assistant 汇总正常持久化。
|
||
- reasoning/provider state 不进入信号、API、客户端和日志。
|
||
- send_message 仍走外部投递确认；emit_signal 不走 OutboundDispatcher。
|
||
- 同 Turn 附件兼容路径与未来 attach_artifact 不产生重复历史。
|
||
|
||
## 26. 必须保持的架构不变量
|
||
|
||
1. 同一 Session 最多一个活动主 Agent Turn；Agent 子 run 可以并行，但不能并发提交主会话历史。
|
||
2. Root Agent 不能成为委托目标，结果回传不等同于反向委托。
|
||
3. Foreground/Background 只描述委托方等待行为；并发是独立调度维度。
|
||
4. Queue 输入永不泄漏正文到当前 Turn；Steer 只在安全边界注入。
|
||
5. Signal 先持久化后唤醒；内存通知不是事实来源。
|
||
6. Signal 是非终态事件，Completion 由运行时自动生成且恰好对应一个 run 终态。
|
||
7. SendMessage 是外部输出，EmitSignal 是内部输入，不能用一个公开万能工具混合权限。
|
||
8. Durable Agent event 在 `/stop`、Turn 失败或 Gateway 崩溃时不能静默丢失。
|
||
9. Agent Definition 和 Provider 绑定 runtime generation；运行中不热切换。
|
||
10. 不持有 Session mutex 等待 Provider、工具、SQLite 或子 run。
|
||
11. 父 run 等待子 run 时不持有会造成递归死锁的执行 permit。
|
||
12. 完成状态、结果、usage、计划子项和 inbox event 使用事务/条件更新提交。
|
||
13. 客户端、Channel 和日志永不暴露 Provider 私有 reasoning state、secret 或本地内部路径。
|
||
|
||
## 27. 设计结论
|
||
|
||
目标架构把现有“一个 delegate 工具创建临时 Agent”提升为明确的编排系统：
|
||
|
||
```text
|
||
Markdown Agent Definition
|
||
↓
|
||
AgentCatalog + DelegationPolicy
|
||
↓
|
||
AgentCoordinator
|
||
├─ foreground：并发执行、父等待、tool result 返回
|
||
└─ background：run ID 返回、signal/completion 进入 durable inbox
|
||
↓
|
||
queue | steer
|
||
↓
|
||
Session queue | current TurnMailbox
|
||
↓
|
||
Root Agent
|
||
```
|
||
|
||
Foreground 解决依赖型子任务；Background+Queue 解决稍后统一处理；Background+Steer 解决长任务期间的重要监控信号；可唤醒 Sleep 为安全等待提供及时响应点。三条消息路径各自保持单一职责：`emit_signal` 内部告警、自动 completion 终态回传、`send_message` 外部投递。该划分能够在不破坏 PicoBot Session/Turn/Delivery 既有不变量的前提下分阶段实现，并为权限、持久化、取消、热重载和客户端表现提供可验证边界。
|