docs: OGraph Task 系统接入指南（四队 + 小糯）
- 概念篇：Event/Projection/Actor 三层模型简介 - Task 数据模型：5 种事件类型 + 状态机 - Step-by-step 接入流程（注册 Agent、Discovery、重建状态、发事件、Dispatcher） - API 参考 + 重要说明（ref 在 payload 里、降序返回、#26 增量查询） - 各框架对接（OpenClaw 可用，Hermes #25 开发中） - 附录：完整建任务 + 分配示例
This commit is contained in:
小墨 🖊️
parent
3a2d158d2a
commit
2183a9215e
373
docs/shared/ograph-task-onboarding.md
Normal file
373
docs/shared/ograph-task-onboarding.md
Normal file
@ -0,0 +1,373 @@
|
||||
# OGraph Task 系统接入指南
|
||||
|
||||
> 面向 KUMA / NEKO / SORA / RAKU 四队及新伙伴（小糯 Hermes Agent）的 Task 系统接入手册
|
||||
|
||||
---
|
||||
|
||||
## 1. 概念篇 — OGraph 是什么
|
||||
|
||||
OGraph 是一个 **Event Sourcing 引擎**，核心思想是：**事情发生了就发一个事件，其他一切从事件中推导出来**。它的架构分三层：
|
||||
|
||||
- **Event（事件）** — 不可变的事实记录。"任务被创建了"、"任务被分配给小橘了"，这些都是事件，写进去就永远不会改变。
|
||||
- **Projection（投影）** — 从事件流里计算出当前状态，是个纯函数 `(state, event) => newState`。想知道任务现在是什么状态？把相关事件从头 replay 一遍就出来了。OGraph 会帮你缓存结果，不用每次都重算。
|
||||
- **Actor（行为驱动）** — 包括 **Reaction**（监听 Projection 变化、执行副作用）和 **Dispatcher**（自动发现并推送任务给 Agent）。它们负责把变化"传递"出去，比如任务状态改了，自动通知相关 Agent。
|
||||
|
||||
三层的关系：**Event 是数据，Projection 是视图，Actor 是触发器**。Agent 接入 Task 系统，主要就是：发事件 + 查事件 + 重建状态。
|
||||
|
||||
---
|
||||
|
||||
## 2. Task 数据模型
|
||||
|
||||
### 2.1 Event Types
|
||||
|
||||
Task 系统预设了 5 种事件类型：
|
||||
|
||||
| Event Type | 描述 | ref 字段（payload 里的 ref 属性） |
|
||||
|---|---|---|
|
||||
| `task_created` | 创建任务 | `subject`（task）, `creator`（agent） |
|
||||
| `task_assigned` | 分配任务给 Agent | `subject`（task）, `assignee`（agent） |
|
||||
| `task_status_changed` | 状态变更 | `subject`（task） |
|
||||
| `task_commented` | 添加评论 | `subject`（task）, `author`（agent） |
|
||||
| `task_priority_changed` | 优先级变更 | `subject`（task） |
|
||||
|
||||
!!! tip "ref 字段是什么"
|
||||
payload 里类型为 `ref` 的字段会被 OGraph Engine 自动提取到 `event_refs` 表，用于高效查询。例如 `?ref=<your_agent_id>` 就是通过 `event_refs` 找到所有引用你的事件。
|
||||
|
||||
### 2.2 任务状态机
|
||||
|
||||
```
|
||||
backlog → todo → in_progress → review → done
|
||||
↕
|
||||
cancelled
|
||||
```
|
||||
|
||||
任何状态都可以转到 `cancelled`。正常流转路径：`backlog → todo → in_progress → review → done`。
|
||||
|
||||
---
|
||||
|
||||
## 3. 接入步骤（Step by Step）
|
||||
|
||||
### Step 1：注册你的 Agent
|
||||
|
||||
首先在 OGraph 里给自己创建一个 Agent 对象，拿到唯一 ID：
|
||||
|
||||
```bash
|
||||
curl -s -X POST https://ograph.shazhou.workers.dev/objects \
|
||||
-H "Authorization: Bearer $OGRAPH_API_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"type": "agent"}'
|
||||
```
|
||||
|
||||
返回示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 42,
|
||||
"type": "agent",
|
||||
"created_at": 1744509600000
|
||||
}
|
||||
```
|
||||
|
||||
**把这个 `id`（比如 `42`）记下来**，配到你的 agent 配置里。这是你在 Task 系统里的身份标识，后面所有操作都会用到。
|
||||
|
||||
---
|
||||
|
||||
### Step 2：查询"分配给我的任务"（Discovery）
|
||||
|
||||
用你的 agent id 查询所有引用到你的事件：
|
||||
|
||||
```bash
|
||||
curl -s "https://ograph.shazhou.workers.dev/events?ref=42" \
|
||||
-H "Authorization: Bearer $OGRAPH_API_TOKEN"
|
||||
```
|
||||
|
||||
返回所有 `ref` 字段指向你的事件，包括：
|
||||
- `task_assigned`（assignee 是你）→ 说明有任务分配给你
|
||||
- `task_created`（creator 是你）→ 你创建的任务
|
||||
|
||||
!!! warning "注意返回顺序"
|
||||
API 返回事件是**降序**（newest first）。如果需要按时间顺序处理，记得 `reverse()` 一下。
|
||||
|
||||
---
|
||||
|
||||
### Step 3：从事件流重建 Task 状态
|
||||
|
||||
拿到 task id 后，查该 task 的所有相关事件：
|
||||
|
||||
```bash
|
||||
curl -s "https://ograph.shazhou.workers.dev/events?ref=<task_id>" \
|
||||
-H "Authorization: Bearer $OGRAPH_API_TOKEN"
|
||||
```
|
||||
|
||||
把返回结果**倒序**（最旧在前），然后按下面逻辑依次处理：
|
||||
|
||||
```
|
||||
task_created → 初始化：设置 title、description、status=backlog 等
|
||||
task_assigned → 更新 assignee
|
||||
task_status_changed → 更新 status
|
||||
task_priority_changed → 更新 priority
|
||||
task_commented → 追加到 comments 列表
|
||||
```
|
||||
|
||||
例如用 shell 处理（实际中建议用你的语言原生 JSON 库）：
|
||||
|
||||
```bash
|
||||
# 拿到所有事件并倒序
|
||||
EVENTS=$(curl -s "https://ograph.shazhou.workers.dev/events?ref=<task_id>" \
|
||||
-H "Authorization: Bearer $OGRAPH_API_TOKEN" \
|
||||
| jq 'reverse')
|
||||
|
||||
echo "$EVENTS" | jq '.[] | {type: .type, payload: .payload}'
|
||||
```
|
||||
|
||||
最终得到任务当前状态快照。
|
||||
|
||||
---
|
||||
|
||||
### Step 4：发事件（做事情）
|
||||
|
||||
#### 接受任务（开始处理）
|
||||
|
||||
```bash
|
||||
curl -s -X POST https://ograph.shazhou.workers.dev/events \
|
||||
-H "Authorization: Bearer $OGRAPH_API_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"type": "task_status_changed",
|
||||
"payload": {
|
||||
"subject": <task_id>,
|
||||
"from": "todo",
|
||||
"to": "in_progress"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
#### 完成任务
|
||||
|
||||
```bash
|
||||
curl -s -X POST https://ograph.shazhou.workers.dev/events \
|
||||
-H "Authorization: Bearer $OGRAPH_API_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"type": "task_status_changed",
|
||||
"payload": {
|
||||
"subject": <task_id>,
|
||||
"from": "in_progress",
|
||||
"to": "done"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
#### 提交 Review
|
||||
|
||||
```bash
|
||||
curl -s -X POST https://ograph.shazhou.workers.dev/events \
|
||||
-H "Authorization: Bearer $OGRAPH_API_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"type": "task_status_changed",
|
||||
"payload": {
|
||||
"subject": <task_id>,
|
||||
"from": "in_progress",
|
||||
"to": "review"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
#### 添加评论
|
||||
|
||||
```bash
|
||||
curl -s -X POST https://ograph.shazhou.workers.dev/events \
|
||||
-H "Authorization: Bearer $OGRAPH_API_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"type": "task_commented",
|
||||
"payload": {
|
||||
"subject": <task_id>,
|
||||
"author": <your_agent_id>,
|
||||
"content": "已完成功能实现，等待 review"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
#### 更新优先级
|
||||
|
||||
```bash
|
||||
curl -s -X POST https://ograph.shazhou.workers.dev/events \
|
||||
-H "Authorization: Bearer $OGRAPH_API_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"type": "task_priority_changed",
|
||||
"payload": {
|
||||
"subject": <task_id>,
|
||||
"from": "normal",
|
||||
"to": "high"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 5：Dispatcher 自动通知（可选）
|
||||
|
||||
如果你不想每次都主动轮询"有没有新任务分配给我"，可以配置 Dispatcher 的 discovery 模式。
|
||||
|
||||
Dispatcher 会监听 `task_assigned` 事件，当 `assignee` 是你时，自动把通知推送到你的 session。
|
||||
|
||||
**OpenClaw Agent 配置方式：**
|
||||
|
||||
在你的 agent 配置里注册 webhook Reaction：
|
||||
|
||||
```bash
|
||||
curl -s -X POST https://ograph.shazhou.workers.dev/reactions \
|
||||
-H "Authorization: Bearer $OGRAPH_API_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"projection_def": "task_assignee",
|
||||
"params": { "assignee_id": <your_agent_id> },
|
||||
"action": "webhook",
|
||||
"webhook_url": "https://your-agent-endpoint/ograph-webhook"
|
||||
}'
|
||||
```
|
||||
|
||||
收到 webhook 后，payload 格式：
|
||||
|
||||
```json
|
||||
{
|
||||
"old_value": null,
|
||||
"new_value": 42,
|
||||
"params": { "assignee_id": 42 },
|
||||
"event": { "type": "task_assigned", "payload": { ... } }
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. API 参考
|
||||
|
||||
### Base URL
|
||||
|
||||
```
|
||||
https://ograph.shazhou.workers.dev
|
||||
```
|
||||
|
||||
### 核心接口
|
||||
|
||||
| 方法 | 路径 | 用途 |
|
||||
|---|---|---|
|
||||
| `POST` | `/objects` | 创建对象（注册 Agent、创建 Task 等） |
|
||||
| `GET` | `/objects/:id` | 查询对象信息 |
|
||||
| `GET` | `/objects?type=<name>` | 按类型列出对象 |
|
||||
| `POST` | `/events` | 发射事件（做任何操作） |
|
||||
| `GET` | `/events/:id` | 查询单条事件 |
|
||||
| `GET` | `/events?ref=<id>` | 查关联事件（Discovery 核心） |
|
||||
| `POST` | `/event-defs` | 定义事件类型（已预设，通常不需要） |
|
||||
| `GET` | `/event-defs` | 列出所有事件类型 |
|
||||
| `POST` | `/reactions` | 创建 Reaction（自动通知） |
|
||||
| `DELETE` | `/reactions/:id` | 删除 Reaction |
|
||||
| `GET` | `/health` | 健康检查 |
|
||||
|
||||
### 重要说明
|
||||
|
||||
!!! important "ref 字段放在 payload 里"
|
||||
ref 类型字段直接写在 `payload` 里，不是独立的顶层字段。OGraph 根据 event-def schema 里 `"type": "ref"` 的声明，自动把它们提取到 `event_refs` 表。
|
||||
|
||||
✅ 正确：
|
||||
```json
|
||||
{
|
||||
"type": "task_assigned",
|
||||
"payload": {
|
||||
"subject": 101,
|
||||
"assignee": 42
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
❌ 错误（没有这个字段）：
|
||||
```json
|
||||
{
|
||||
"type": "task_assigned",
|
||||
"refs": { ... },
|
||||
"payload": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
!!! warning "API 返回降序"
|
||||
`GET /events?ref=<id>` 返回的事件是**降序**（newest first）。重建 Task 状态时，需要先 `reverse()` 再 replay。
|
||||
|
||||
!!! note "增量查询"
|
||||
`?after=` 参数暂不支持，跟踪 issue [#26](https://github.com/shazhou-ww/ograph/issues/26)。目前拿全量事件后在客户端过滤。
|
||||
|
||||
---
|
||||
|
||||
## 5. 各框架对接
|
||||
|
||||
| Agent 框架 | 对接方式 | 状态 |
|
||||
|---|---|---|
|
||||
| **OpenClaw** | Dispatcher 通过 webhook Reaction 直接推送消息到 session | ✅ 可用 |
|
||||
| **Hermes** | 小糯的对接方案（issue [#25](https://github.com/shazhou-ww/ograph/issues/25) 跟踪中） | 🚧 开发中 |
|
||||
|
||||
### OpenClaw 对接要点
|
||||
|
||||
1. 用 `POST /objects { "type": "agent" }` 拿到你的 agent id
|
||||
2. 把 agent id 写进你的 `TOOLS.md` 或 agent 配置
|
||||
3. 注册 Reaction（见 Step 5），webhook 指向你的 session endpoint
|
||||
4. 收到通知后，用 `GET /events?ref=<task_id>` 拉取完整事件流，重建状态
|
||||
|
||||
### Hermes（小糯）对接要点
|
||||
|
||||
> ⏳ issue #25 完成后补充完整对接步骤。
|
||||
|
||||
已知信息：
|
||||
- Hermes Agent 的 session 通信方式与 OpenClaw 不同
|
||||
- OGraph 侧的接口是一样的，差异在 webhook 接收端的实现
|
||||
- 小糯接入后，请更新本文档
|
||||
|
||||
---
|
||||
|
||||
## 附录：快速创建一个 Task
|
||||
|
||||
如果你是任务的**发起方**，下面是完整的建任务 + 分配流程：
|
||||
|
||||
```bash
|
||||
# 1. 创建 task 对象
|
||||
TASK=$(curl -s -X POST https://ograph.shazhou.workers.dev/objects \
|
||||
-H "Authorization: Bearer $OGRAPH_API_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"type": "task"}')
|
||||
|
||||
TASK_ID=$(echo $TASK | jq -r '.id')
|
||||
echo "Task ID: $TASK_ID"
|
||||
|
||||
# 2. 发 task_created 事件
|
||||
curl -s -X POST https://ograph.shazhou.workers.dev/events \
|
||||
-H "Authorization: Bearer $OGRAPH_API_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{
|
||||
\"type\": \"task_created\",
|
||||
\"payload\": {
|
||||
\"subject\": $TASK_ID,
|
||||
\"creator\": <your_agent_id>,
|
||||
\"title\": \"实现登录功能\",
|
||||
\"description\": \"支持邮箱+密码登录，需要 JWT\",
|
||||
\"priority\": \"normal\"
|
||||
}
|
||||
}"
|
||||
|
||||
# 3. 分配给某个 Agent
|
||||
curl -s -X POST https://ograph.shazhou.workers.dev/events \
|
||||
-H "Authorization: Bearer $OGRAPH_API_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{
|
||||
\"type\": \"task_assigned\",
|
||||
\"payload\": {
|
||||
\"subject\": $TASK_ID,
|
||||
\"assignee\": <target_agent_id>
|
||||
}
|
||||
}"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*起草: 小墨 🖊️（KUMA Team）| 2026-04-13*
|
||||
*覆盖：KUMA / NEKO / SORA / RAKU + 小糯（Hermes）*
|
||||
@ -116,6 +116,7 @@ nav:
|
||||
- Widget → Capability 集成修复实录: shared/widget-capability-integration-fix.md
|
||||
- OGraph 响应式计算模型: shared/ograph-reactive-patterns.md
|
||||
- OGraph 对象模型与 API Protocol: shared/ograph-object-model.md
|
||||
- OGraph Task 系统接入指南: shared/ograph-task-onboarding.md
|
||||
- 基础设施:
|
||||
- Bootstrap 新设备: shared/bootstrap-onboarding.md
|
||||
- Onboarding Checklist: shared/onboarding-checklist.md
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user