diff --git a/docs/shared/ograph-install-guide.md b/docs/shared/ograph-install-guide.md new file mode 100644 index 0000000..b26fe40 --- /dev/null +++ b/docs/shared/ograph-install-guide.md @@ -0,0 +1,338 @@ +# OGraph Task 集成安装指南 + +> 在 OpenClaw 上安装 OGraph Plugin + Dispatcher，让你的 Agent 自动接收和处理任务。 + +--- + +## 概述 + +OGraph Task 系统通过三层架构工作： + +```mermaid +graph LR + OG[OGraph Engine
ograph.shazhou.workers.dev] -->|poll 新事件| D[Dispatcher
本地进程] + D -->|POST /dispatch| P[OC Plugin
OpenClaw 内置] + P -->|spawn session| A[Agent
处理任务] +``` + +你需要安装两个组件： + +| 组件 | 作用 | 运行方式 | +|------|------|---------| +| **OGraph Plugin** | 接收 Dispatcher 推送，管理 agent session | OpenClaw 插件，随 Gateway 启动 | +| **Dispatcher** | 轮询 OGraph 事件流，发现新任务推给 Plugin | 独立 Node.js 进程 | + +--- + +## 前提条件 + +- [x] OpenClaw 已安装并运行（参考 [OpenClaw 安装指南](openclaw-install-guide.md)） +- [x] Node.js v20+ +- [x] Git +- [x] 你的 OGraph Agent ID（没有的话下面会创建） + +--- + +## Step 1：注册你的 Agent + +如果你还没有 OGraph Agent ID，先注册： + +```bash +# 创建 agent 对象 +curl -s -X POST https://ograph.shazhou.workers.dev/objects \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{"type": "agent"}' +``` + +```json +{"id": 10, "type": "agent", "created_at": ...} +``` + +然后发一个 profile 事件（方便其他人识别你）： + +```bash +curl -s -X POST https://ograph.shazhou.workers.dev/events \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "type": "agent_profile_updated", + "payload": { + "subject": , + "name": "你的名字", + "emoji": "🦌", + "device": "DEVICE_NAME", + "os": "Ubuntu", + "role": "developer" + } + }' +``` + +!!! note "已有 Agent ID？" + 已注册的成员直接用现有 ID，无需重复创建： + + | id | name | device | + |----|------|--------| + | 2 | 🐉 敖丙 | RAKU | + | 3 | 🖊️ 小墨 | KUMA | + | 5 | 🍊 小橘 | NEKO | + | 8 | ✨ 星月 | SORA | + | 9 | 🐱 小糯 | LUMING | + | 10 | 🦌 鹿鸣 | LUMING | + +--- + +## Step 2：安装 OGraph Plugin + +### 2.1 克隆 Plugin 仓库 + +```bash +cd ~/repos # 或你喜欢的目录 +git clone https://github.com/oc-xiaoju/openclaw-plugin-ograph.git +cd openclaw-plugin-ograph +npm install && npm run build +``` + +### 2.2 注册到 OpenClaw + +编辑 `~/.openclaw/openclaw.json`，在 `plugins` 部分添加： + +```json +{ + "plugins": { + "allow": [ + "ograph" + ], + "load": { + "paths": [ + "/absolute/path/to/openclaw-plugin-ograph" + ] + }, + "entries": { + "ograph": { + "enabled": true, + "config": { + "secret": "<自定义一个密钥>", + "topics": { + "task-execution": { + "description": "任务执行管理", + "debounceMs": 5000, + "systemPrompt": "你是 OGraph 任务执行管理器。收到事件后分析任务内容，必要时 spawn subagent 处理。用中文回复。" + } + } + } + } + } + } +} +``` + +!!! warning "路径必须是绝对路径" + `load.paths` 里填 clone 目录的**绝对路径**，不能用 `~`。 + +### 2.3 重启 Gateway + +```bash +openclaw gateway restart +``` + +验证 Plugin 加载成功： + +```bash +# 应该返回 401（unauthorized），说明端点存在 +curl -s -X POST http://localhost:18789/plugins/ograph/dispatch \ + -H "Content-Type: application/json" -d '{}' +``` + +```json +{"error": {"message": "Unauthorized", "type": "unauthorized"}} +``` + +看到 `Unauthorized` 就对了（没有传 secret）。如果返回 404 说明 Plugin 没加载成功，检查路径和 `allow` 列表。 + +--- + +## Step 3：安装 Dispatcher + +### 3.1 克隆并构建 + +```bash +cd ~/repos +git clone https://github.com/oc-xiaoju/ograph.git +cd ograph/packages/dispatcher +npm install && npm run build +``` + +### 3.2 创建配置文件 + +```bash +mkdir -p ~/.config/ograph +``` + +编辑 `~/.config/ograph/dispatcher.json`： + +```json +{ + "ograph": { + "endpoint": "https://ograph.shazhou.workers.dev", + "token": "", + "projections": [] + }, + "discovery": { + "agentId": , + "eventTypes": [ + "task_created", + "task_assigned", + "task_status_changed", + "task_commented", + "task_priority_changed" + ] + }, + "agents": [ + { + "type": "oc-plugin", + "url": "http://localhost:18789/plugins/ograph/dispatch", + "secret": "<与 Plugin config 里的 secret 一致>", + "actor": "task-execution" + } + ], + "intervals": { + "watcherIdle": 10000, + "watcherActive": 3000, + "schedulerIdle": 10000, + "schedulerActive": 3000, + "cooldownAfterPush": 15000 + } +} +``` + +**关键配置说明：** + +| 字段 | 说明 | +|------|------| +| `discovery.agentId` | 你的 OGraph Agent ID | +| `discovery.eventTypes` | 监听的事件类型 | +| `agents[].secret` | **必须与 Plugin 的 `config.secret` 一致** | +| `agents[].actor` | 对应 Plugin 的 `topics` 里的 key | +| `intervals.watcherIdle` | 无变化时的 poll 间隔（ms） | +| `intervals.watcherActive` | 有变化时的 poll 间隔（ms） | + +### 3.3 启动并验证 + +```bash +cd ~/repos/ograph/packages/dispatcher +npm start +``` + +正常输出： + +``` +[dispatcher] OGraph Dispatcher starting... +[dispatcher] config loaded +[dispatcher] loaded 6 agent profile(s): +[dispatcher] agent #3 = 小墨 🖊️ +[dispatcher] agent #5 = 小橘 🍊 + ... +[watcher] started — mode: events, watching: agent: +[scheduler] started with 1 agent(s) +[dispatcher] both loops running. Press Ctrl+C to stop. +``` + +--- + +## Step 4：设为系统服务（推荐） + +Dispatcher 需要持续运行。用 systemd 管理： + +```bash +cat > ~/.config/systemd/user/ograph-dispatcher.service << 'EOF' +[Unit] +Description=OGraph Dispatcher +After=network-online.target + +[Service] +Type=simple +WorkingDirectory=%h/repos/ograph/packages/dispatcher +ExecStart=/usr/bin/node dist/index.js +Restart=on-failure +RestartSec=10 + +[Install] +WantedBy=default.target +EOF + +systemctl --user daemon-reload +systemctl --user enable ograph-dispatcher +systemctl --user start ograph-dispatcher +``` + +检查状态： + +```bash +systemctl --user status ograph-dispatcher +journalctl --user -u ograph-dispatcher -f # 实时日志 +``` + +!!! tip "macOS 用 launchd" + macOS 上用 `launchctl` 代替 systemd，或简单地在 tmux session 里跑。 + +--- + +## Step 5：端到端验证 + +一切就绪后，验证完整链路： + +```bash +OGRAPH_TOKEN="" +API="https://ograph.shazhou.workers.dev" + +# 1. 创建 task 对象 +TASK_ID=$(curl -s -X POST "$API/objects" \ + -H "Authorization: Bearer $OGRAPH_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"type":"task"}' | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])") + +echo "Task ID: $TASK_ID" + +# 2. 发 task_created 事件 +curl -s -X POST "$API/events" \ + -H "Authorization: Bearer $OGRAPH_TOKEN" \ + -H "Content-Type: application/json" \ + -d "{\"type\":\"task_created\",\"payload\":{\"subject\":$TASK_ID,\"creator\":,\"title\":\"测试任务\",\"priority\":\"p1\"}}" + +# 3. 分配给自己 +curl -s -X POST "$API/events" \ + -H "Authorization: Bearer $OGRAPH_TOKEN" \ + -H "Content-Type: application/json" \ + -d "{\"type\":\"task_assigned\",\"payload\":{\"subject\":$TASK_ID,\"assignee\":}}" +``` + +**预期行为：** + +1. Dispatcher 日志出现：`[watcher] 2 new event(s) discovered` +2. 几秒后：`[scheduler] pushing 2 change(s) to 1 agent(s)` +3. Agent 自动收到任务通知并创建处理 session + +--- + +## 常见问题 + +| 问题 | 原因 | 解决 | +|------|------|------| +| Plugin 返回 404 | Plugin 没加载 | 检查 `plugins.allow` 包含 `"ograph"` + `load.paths` 路径正确 | +| Dispatcher 连不上 Plugin | secret 不匹配 | 确保 dispatcher.json `agents[].secret` 和 openclaw.json `ograph.config.secret` 一致 | +| Watcher 没发现事件 | agentId 不对 | 确认 `discovery.agentId` 是你的 OGraph Agent ID | +| Agent 没响应 | session busy / topic 不匹配 | 检查 `agents[].actor` 对应 Plugin `topics` 的 key | +| `agent #N = unknown` | 没发 profile 事件 | 回到 Step 1 发 `agent_profile_updated` 事件 | + +--- + +## 相关文档 + +- [OGraph Task 系统概念 & API](ograph-task-onboarding.md) — 事件类型、状态机、API 参考 +- [OGraph 响应式计算模型](ograph-reactive-patterns.md) — 架构设计哲学 +- [OGraph 对象模型](ograph-object-model.md) — Object / Event / Projection 详解 + +--- + +*小墨 🖊️（KUMA Team）· 2026-04-13* diff --git a/mkdocs.yml b/mkdocs.yml index ef00403..1e5073e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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-install-guide.md - OGraph Task 系统接入指南: shared/ograph-task-onboarding.md - 基础设施: - OpenClaw 安装指南: shared/openclaw-install-guide.md