Robot 流水线中的每个阶段由专门的 Agent 执行。你实现这些 Agent 的方式与普通 Yao Agent 完全相同 —— 一个 `package.yao`、一个系统提示词，以及可选的 Create/Next Hook。唯一的关键区别是 `package.yao` 中的 **`type` 字段**。
## `type` 字段 —— UI 如何找到你的 Agent
在 Mission Control 中配置 Robot 时，每个阶段都有一个下拉框选择 Agent。这个下拉框通过查询 `type` 与阶段匹配的 Agent 来填充。
**没有正确的 `type`，你的 Agent 不会出现在下拉框中，无法被选中。**
| 阶段 | 必填的 `type` 值 |
|------|-----------------|
| P0 Inspiration | `robot-inspiration` |
| P1 Goals | `robot-goals` |
| P2 Tasks | `robot-tasks` |
| P4 Delivery | `robot-delivery` |
| P5 Learning | `robot-learning` |
| Validation | `robot-validation` |
| Host（跨阶段） | `robot-host` |
> P3（Run）是内置的任务调度器 —— 没有专属 Phase Agent，也没有对应的 `type` 值。
每个阶段的最小 `package.yao` 如下：
```json
{
"name": "My Inspiration Agent",
"type": "robot-inspiration",
"connector": "$ENV.DEFAULT_CONNECTOR",
"automated": true,
"mentionable": false
}
```
修改 `type` 以匹配阶段，其余保持不变。
---
## 注册 Phase Agents
创建好带有正确 `type` 的 Agent 后，告诉框架每个阶段使用哪个 Agent。有两个层级：
**全局默认** —— 应用于所有 Robot，在 `agent.yml` 中设置：
```yaml
uses:
inspiration: myns/inspiration-agent
goals: myns/goals-agent
tasks: myns/tasks-agent
delivery: myns/delivery-agent
learning: myns/learning-agent
host: myns/host-agent
validation: myns/validation-agent
```
**单 Robot 覆盖** —— 覆盖特定 Robot 的全局默认，在其 `robot_config` 中设置（Mission Control → 高级设置）：
```json
{
"resources": {
"phases": {
"delivery": "myns/slack-delivery-agent"
}
}
}
```
优先级：单 Robot `resources.phases` → 全局 `uses` → 报错（阶段未配置）。
---
## P0 — Inspiration (`robot-inspiration`)
**触发：** 仅 Clock
**输入：** 当前时间、时区、Robot 身份和可用资源
**输出：** Markdown 简报（`InspirationReport`）传递给 P1
Inspiration Agent 根据 Robot 可访问的资源（KB、DB、Agent、MCP 工具）和当前时间上下文生成每日或定期简报。Human 和 Event 触发完全跳过 P0。
```json
{
"name": "My Inspiration Agent",
"type": "robot-inspiration",
"connector": "$ENV.DEFAULT_CONNECTOR",
"description": "P0 — 分析上下文并生成每日简报。",
"automated": true,
"mentionable": false,
"options": { "max_tokens": 4096 }
}
```
### 系统提示词示例
```
你是一个 Inspiration Agent。根据当前日期、时间和 Robot 的可用资源，
生成简洁的 Markdown 简报：
1. 时间上下文（星期几、重要日期）
2. 知识库中的待办事项
3. 建议 Goals Agent 今天的重点方向
控制在 300 字以内。
```
---
## P1 — Goals (`robot-goals`)
**输入：** P0 的 `InspirationReport`（Clock）或触发载荷（Human/Event）
**输出：** 包含具体、可衡量目标的 Markdown 文档
```json
{
"name": "My Goals Agent",
"type": "robot-goals",
"connector": "$ENV.DEFAULT_CONNECTOR",
"description": "P1 — 将简报或触发输入转化为优先目标。",
"automated": true,
"mentionable": false
}
```
### 系统提示词示例
```
你是一个 Goals Agent。根据每日简报（或干预请求），
为本次执行定义 2–5 个具体、可衡量的目标。
以 Markdown 输出，每个目标用 ## Goal N 标题。
每个目标必须用已列出的可用资源可以实现。
```
---
## P2 — Tasks (`robot-tasks`)
**输入：** P1 的 Goals 文档
**输出：** 结构化的 `Task` 对象列表
Tasks Agent 将每个目标拆分为有序的可执行任务。每个任务声明其执行器，让 P3 知道如何运行。
```json
{
"name": "My Tasks Agent",
"type": "robot-tasks",
"connector": "$ENV.DEFAULT_CONNECTOR",
"description": "P2 — 将目标拆解为可执行任务。",
"automated": true,
"mentionable": false
}
```
### 任务执行器类型
每个任务必须包含 `executor_type` 和 `executor_id`：
| `executor_type` | `executor_id` 格式 | 说明 |
|-----------------|-------------------|------|
| `assistant` | Agent 路径，如 `myns/report-agent` | 调用 Yao Agent |
| `mcp` | `mcp_server.mcp_tool` | 调用指定 MCP 工具 |
| `process` | Yao Process，如 `scripts.report.Generate` | 调用 TypeScript 函数 |
**Assistant 任务：**
```json
{
"executor_type": "assistant",
"executor_id": "myns/report-agent",
"messages": [{ "role": "user", "content": "汇总上周的数据。" }],
"expected_output": "包含关键指标的 Markdown 报告"
}
```
**MCP 任务：**
```json
{
"executor_type": "mcp",
"mcp_server": "agents.myns.myagent.tools",
"mcp_tool": "search_records",
"messages": [{ "role": "user", "content": "查找所有标记为 'urgent' 的项目。" }]
}
```
**Process 任务：**
```json
{
"executor_type": "process",
"executor_id": "scripts.report.Generate",
"args": ["weekly", "2025-01-01", "2025-01-07"]
}
```
---
## P3 — Run（无专属 Agent）
P3 由 Robot 执行器直接处理 —— 它不是可插拔的 Agent 阶段。执行器读取 P2 的任务列表并将每个任务分发到正确的执行器：
```
executor_type == "assistant" → 通过 Assistant.Stream() 调用 Agent
executor_type == "mcp" → 调用 MCP 工具
executor_type == "process" → 调用 Yao Process
```
所有结果（成功和失败）都会收集并传递给 P4。默认情况下，即使某个任务失败，执行器也会继续执行后续任务。
---
## P4 — Delivery (`robot-delivery`)
**输入：** 完整执行上下文（目标、任务、所有结果）
**输出：** `DeliveryContent`（摘要 + Markdown 正文 + 可选附件）
Delivery Agent 可以访问每个阶段的输出，并生成最终报告。完成后，框架将结果推送到已配置的通道（Webhook、Yao Process）。参见 [触发与交付](./triggers)。
```json
{
"name": "My Delivery Agent",
"type": "robot-delivery",
"connector": "$ENV.DEFAULT_CONNECTOR",
"description": "P4 — 格式化执行结果并触发交付通道。",
"automated": true,
"mentionable": false
}
```
### 系统提示词示例
```
你是一个 Delivery Agent。审查已完成的执行：
- P1 中定义的目标
- P2 中规划的任务
- P3 的结果（包括任何失败）
生成：
1. 一段摘要（用于通知和 Webhook 载荷）
2. 完整的 Markdown 报告（用于正文）
如实反映失败情况。在适用的地方建议下一步。
```
---
## P5 — Learning (`robot-learning`)
> **注意：** Learning 阶段在当前标准执行器中为占位实现 —— 它会记录一条模拟条目，但尚未调用专门的 Learning Agent 或使用下述 `learn` 配置。此处为设计文档，完整实现计划在后续版本中提供。
**输入：** 完整执行上下文
**输出：** `LearningEntry` 列表，保存到 Robot 的私有知识库
```json
{
"name": "My Learning Agent",
"type": "robot-learning",
"connector": "$ENV.DEFAULT_CONNECTOR",
"description": "P5 — 从执行中提取模式和经验教训。",
"automated": true,
"mentionable": false
}
```
学习类型：
| 类型 | 说明 |
|------|------|
| `execution` | 全局运行中观察到的模式 |
| `feedback` | 值得记住的错误或修复模式 |
| `insight` | 未来执行的提示和优化 |
在 `robot_config` 中配置 Robot 的学习行为：
```json
{
"learn": {
"on": true,
"types": ["execution", "feedback"],
"keep": 30
}
}
```
`keep` 单位为天；`0` 表示永久保留。
---
## Host Agent — 跨阶段 (`robot-host`)
Host Agent 不是流水线阶段 —— 它在执行过程中并行运行，处理实时人机交互。当某个任务发出 `NeedInput: true` 信号时，Host Agent 向用户展示问题并将响应注入回执行流程。
```json
{
"name": "My Host Agent",
"type": "robot-host",
"connector": "$ENV.DEFAULT_CONNECTOR",
"description": "在执行过程中调解用户与 Robot 之间的交互。",
"automated": false,
"mentionable": false
}
```
在 `agent.yml` 中与其他 Phase Agent 一起注册：
```yaml
uses:
host: myns/host-agent
```
