Robot 通过**触发器**唤醒,通过**交付通道**推送结果。触发和交付均在 Mission Control UI 中配置 —— 你不需要手动编写 JSON 配置文件。
本页说明每种触发类型的概念,并记录你的代码将接收的交付载荷格式。
---
## 触发器
触发器在 **Mission Control → Robot 设置** 中按 Robot 配置。三种触发类型:
| 触发器 | 起始阶段 | 说明 |
|--------|----------|------|
| **Clock** | P0(Inspiration) | 按计划运行完整的六阶段流水线 |
| **Human** | P1(Goals) | 用户或外部系统发送指令;跳过 P0 |
| **Event** | P1(Goals) | 当 webhook 到达或数据库行变化时触发;跳过 P0 |
### Clock
按计划执行。三种模式:
| 模式 | 行为 |
|------|------|
| **times** | 在特定日期的特定时间运行(如每周一到五的 09:00 和 18:00) |
| **interval** | 每隔 N 时间运行一次(如每 2 小时) |
| **daemon** | 持续运行 —— 每次完成后立即重启 |
所有 Clock 设置(时间、星期、时区、超时)都在 Mission Control UI 中配置。
### Human
Human 触发器在用户向 Robot 发送指令时触发 —— 例如分配任务、调整目标或发出直接指令。干预消息成为 P1 的目标上下文。
支持的干预动作:
| 动作 | 说明 |
|------|------|
| `instruct` | 直接向 Robot 发送指令 |
| `task.add` / `task.cancel` / `task.update` | 管理任务 |
| `goal.add` / `goal.adjust` / `goal.complete` / `goal.cancel` | 管理目标 |
| `plan.add` / `plan.remove` / `plan.update` | 管理计划队列 |
### Event
Event 触发器在外部信号到达时触发。两种来源:
- **Webhook** —— 向已配置的路径发送 HTTP `POST` 唤醒 Robot。可选的 filter 用于匹配传入的载荷。
- **Database** —— Yao 监控指定表的插入/更新操作,当匹配行出现时触发 Robot。
---
## 交付
P4(Delivery Agent)生成摘要后,Yao 将结果推送到已配置的交付通道。三种通道可用:
- **Email** —— 自动发送给 Robot 的管理员;可配置额外收件人。
- **Webhook** —— 向外部 URL 发送签名的 JSON 载荷。
- **Yao Process** —— 调用你的 TypeScript 函数并传递结构化载荷。
三种通道可以同时启用。交付目标在 **Mission Control → Robot 设置 → 交付** 中配置。
作为开发者,Webhook 和 Yao Process 通道需要你编写代码来接收载荷。格式如下。
---
### Webhook
Yao 向每个已配置的 URL 发送 `POST` 请求,JSON body 如下:
> **注意:** `trigger_type` 已在 payload 结构中定义,但在当前实现中可能为空。修复已在计划中。
```json
{
"event": "robot.delivery",
"timestamp": "2025-01-01T12:00:00Z",
"execution_id": "exec-xxx",
"member_id": "member-xxx",
"team_id": "team-xxx",
"trigger_type": "clock",
"content": {
"summary": "周报:3 个任务已完成。",
"body": "## 摘要\n\n..."
},
"attachments": [
{
"title": "任务 1 结果",
"description": "...",
"task_id": "task-xxx",
"file": "/path/to/file"
}
]
}
```
#### 签名验证
如果配置了签名密钥,Yao 会添加两个 Header:
```
X-Yao-Signature: <请求 body 的 HMAC-SHA256 十六进制值>
X-Yao-Signature-Algorithm: HMAC-SHA256
```
在你的服务端验证:
```typescript
import { createHmac } from "crypto";
function verifySignature(body: Buffer, signature: string, secret: string): boolean {
const expected = createHmac("sha256", secret).update(body).digest("hex");
return expected === signature;
}
```
---
### Yao Process
当 Process 交付触发时,Yao 使用单个结构化参数调用你的 TypeScript 函数:
```typescript
{
content: {
summary: string,
body: string,
attachments: Attachment[]
},
context: {
execution_id: string,
member_id: string,
team_id: string,
trigger_type: "clock" | "human" | "event"
}
}
```
#### 示例:自定义通知脚本
```typescript
// scripts/notify.ts
import { Process, log } from "@yao/runtime";
export function Send(payload: {
content: { summary: string; body: string };
context: { team_id: string; trigger_type: string };
}) {
const { content, context } = payload;
log.Info("[notify.Send] 收到交付", {
team_id: context.team_id,
trigger_type: context.trigger_type,
summary: content.summary,
});
Process("scripts.im.SendMessage", context.team_id, content.summary);
}
```
#### 额外参数
如果在目标上配置了固定的额外参数,Yao 会在载荷之后传递它们:
```
Send(payload, "extra-value-1", "extra-value-2", …)
```
交付载荷始终是第一个参数。
---
### 多通道并用
Email、Webhook 和 Process 可以同时启用。Yao 按顺序调用所有目标,如果某个目标失败会记录日志但不会中断其他交付。