@hywkp/sider 0.0.3 → 0.0.5

package/README.md

@@ -0,0 +1,280 @@
+# Sider OpenClaw Plugin 对接文档
+
+本文档面向两类同学：
+- 需要安装 `openclaw-plugins/sider` 的运维/后端同学
+- 需要消费 `typing/stream/tool` 事件的客户端同学（Web/iOS/Android）
+
+---
+
+## 1. 一键安装
+
+安装脚本默认执行：
+- `openclaw plugins install @hywkp/sider`
+- 若已安装（`plugin already exists`），自动尝试：`openclaw plugins update sider`
+
+仅安装插件（不改配置）：
+
+```bash
+curl -fsSL https://chat-demo.hyw.workers.dev/sider/install-openclaw-plugin.sh | RUN_CONFIGURE=0 bash
+```
+
+安装并写入 `channels.sider` 配置：
+
+```bash
+curl -fsSL https://chat-demo.hyw.workers.dev/sider/install-openclaw-plugin.sh | \
+  SIDER_GATEWAY_URL='http://127.0.0.1:8080' \
+  SIDER_SESSION_ID='s1' \
+  bash
+```
+
+可选参数：
+- `SIDER_RELAY_ID`
+- `SIDER_RELAY_TOKEN`
+- 兼容旧变量：`SIDER_SESSION_KEY`（会自动映射到 `SIDER_SESSION_ID`）
+
+---
+
+## 2. OpenClaw 配置示例
+
+`~/.openclaw/openclaw.json`：
+
+```json
+{
+  "channels": {
+    "sider": {
+      "enabled": true,
+      "gatewayUrl": "http://127.0.0.1:8080",
+      "sessionId": "s1",
+      "defaultTo": "session:s1",
+      "relayId": "openclaw-default"
+    }
+  }
+}
+```
+
+检查状态：
+
+```bash
+openclaw channels list
+openclaw status --json
+```
+
+---
+
+## 3. 基础协议（relay 侧）
+
+WebSocket 连接：
+- `ws://<gateway>/ws/relay`
+
+握手首帧：
+
+```json
+{"type":"register","session_id":"<session_id>","relay_id":"<relay_id>","token":"<optional>"}
+```
+
+发送持久化消息：
+
+```json
+{
+  "type":"message",
+  "session_id":"<session_id>",
+  "client_req_id":"<uuid>",
+  "parts":[{"type":"core.text","payload":{"text":"hello"}}]
+}
+```
+
+发送实时事件：
+
+```json
+{
+  "type":"event",
+  "session_id":"<session_id>",
+  "client_req_id":"<uuid>",
+  "event_type":"typing",
+  "payload":{"on":true},
+  "meta":{}
+}
+```
+
+ACK：
+
+```json
+{"type":"ack","session_id":"<session_id>","id":"<id>"}
+```
+
+---
+
+## 4. 客户端事件约定（typing / stream / tool）
+
+插件会发送以下实时事件（`type=event`，`source_role=relay`）。
+
+### 4.1 typing
+
+开始输入：
+
+```json
+{
+  "event_type":"typing",
+  "payload":{
+    "on":true,
+    "state":"typing",
+    "session_id":"<session_id>",
+    "ts":1730000000000
+  },
+  "meta":{
+    "channel":"sider",
+    "account_id":"default",
+    "schema_version":1
+  }
+}
+```
+
+停止输入时：`on=false`，`state=idle`。
+
+### 4.2 stream.start
+
+```json
+{
+  "event_type":"stream.start",
+  "payload":{
+    "session_id":"<session_id>",
+    "stream_id":"<uuid>",
+    "ts":1730000000000
+  }
+}
+```
+
+### 4.3 stream.delta
+
+```json
+{
+  "event_type":"stream.delta",
+  "payload":{
+    "session_id":"<session_id>",
+    "stream_id":"<uuid>",
+    "seq":1,
+    "delta":"你好，",
+    "done":false,
+    "chunk_chars":3,
+    "ts":1730000000001
+  }
+}
+```
+
+### 4.4 stream.done
+
+```json
+{
+  "event_type":"stream.done",
+  "payload":{
+    "session_id":"<session_id>",
+    "stream_id":"<uuid>",
+    "seq":99,
+    "done":true,
+    "reason":"final|interrupted",
+    "ts":1730000000999
+  }
+}
+```
+
+说明：
+- `reason=final`：流式正常结束
+- `reason=interrupted`：流式被中断（例如上游出错或中断）
+
+### 4.5 tool.call
+
+工具调用开始事件（来源于 OpenClaw `before_tool_call`）：
+
+```json
+{
+  "event_type":"tool.call",
+  "payload":{
+    "session_id":"<session_id>",
+    "seq":1,
+    "call_id":"<uuid>",
+    "phase":"start",
+    "tool_name":"read",
+    "tool_call_id":"<provider_call_id>",
+    "run_id":"<run_id>",
+    "session_key":"agent:main:...",
+    "tool_args":{"path":"README.md"},
+    "error":null,
+    "duration_ms":null,
+    "ts":1730000000002
+  },
+  "meta":{
+    "channel":"sider",
+    "account_id":"default",
+    "schema_version":1
+  }
+}
+```
+
+说明：
+- `call_id` 用于把同一次工具调用的 `tool.call` 和 `tool.result` 关联起来。
+- `tool_args` 即工具参数（例如 `read` 的 `path`）。
+- `tool_call_id` 为 provider 侧 call id（有则透传）。
+
+### 4.6 tool.result
+
+工具结果事件（来源于 OpenClaw `after_tool_call`）：
+
+```json
+{
+  "event_type":"tool.result",
+  "payload":{
+    "session_id":"<session_id>",
+    "seq":2,
+    "call_id":"<uuid>",
+    "tool_name":"read",
+    "tool_call_id":"<provider_call_id>",
+    "run_id":"<run_id>",
+    "session_key":"agent:main:...",
+    "tool_args":{"path":"README.md"},
+    "result":{"content":[{"type":"text","text":"..."}]},
+    "error":null,
+    "duration_ms":32,
+    "text":"",
+    "has_text":false,
+    "media_urls":[],
+    "media_count":0,
+    "is_error":false,
+    "ts":1730000000003
+  }
+}
+```
+
+说明：
+- `result` 为工具返回值（JSON-safe 序列化后）。
+- `error` 非空时表示工具执行失败。
+- `text` 为插件提取的“可读摘要”，仅从 `result.text/content/message/output/stdout` 取值，不做回退。
+- `tool.result` 是工具阶段的实时事件，不替代最终 `type=message`。
+
+---
+
+## 5. 客户端渲染建议
+
+- 使用 `stream_id + seq` 作为流式拼接键，按 `seq` 递增拼接 `delta`
+- `stream.*` 仅用于实时渲染，不作为历史消息源
+- `tool.call/tool.result` 仅用于实时状态，不作为历史消息源
+- 最终以 `type=message` 的持久化消息为准（用于会话历史）
+- 收到 `stream.done` 后，等待最终 `message` 到达再收敛 UI
+
+---
+
+## 6. 常见排查
+
+- 看不到 typing/stream：
+  - 检查是否连接到了同一个 `session_id`
+  - 检查客户端是否处理了 `type=event`
+- 收到附件但模型像“看不到文件”：
+  - 插件入站会先下载 `core.file/core.media` 到本地媒体存储，再把 `MediaPath(s)` 放入 OpenClaw 上下文
+  - 若下载失败，会降级为把附件 URL 拼进消息正文（日志关键字：`sider inbound media download failed`）
+- 图片/文件发送失败：
+  - 插件会走 `POST /v1/files/init` + 直传 `upload_url` + `POST /v1/files/complete(可选)`
+  - 若网关返回 `501 file service not enabled`，说明当前不是 S3 文件存储驱动
+- 发送成功但没收到最终回复：
+  - 检查是否收到 `ack`
+  - 检查 OpenClaw 日志中的 `sider` 相关错误
+- 收到 `replaced`：
+  - 表示同 `relay_id` 有新连接顶掉旧连接，需重连

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAI7D,QAAA,MAAM,MAAM;;;;;kBAKI,iBAAiB;CAIhC,CAAC;AAEF,eAAe,MAAM,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAI7D,QAAA,MAAM,MAAM;;;;;kBAKI,iBAAiB;CA2BhC,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/index.js

@@ -1,5 +1,5 @@
 import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
-import { setSiderRuntime, siderPlugin } from "./src/channel.js";
+import { emitSiderToolHookEvent, setSiderRuntime, siderPlugin } from "./src/channel.js";
 const plugin = {
     id: "sider",
     name: "Sider",
@@ -8,6 +8,29 @@ const plugin = {
     register(api) {
         setSiderRuntime(api.runtime);
         api.registerChannel({ plugin: siderPlugin });
+        api.on("before_tool_call", async (event, ctx) => {
+            await emitSiderToolHookEvent({
+                sessionKey: ctx.sessionKey,
+                phase: "start",
+                toolName: event.toolName ?? ctx.toolName,
+                toolCallId: event.toolCallId ?? ctx.toolCallId,
+                runId: event.runId ?? ctx.runId,
+                params: event.params,
+            });
+        });
+        api.on("after_tool_call", async (event, ctx) => {
+            await emitSiderToolHookEvent({
+                sessionKey: ctx.sessionKey,
+                phase: event.error ? "error" : "end",
+                toolName: event.toolName ?? ctx.toolName,
+                toolCallId: event.toolCallId ?? ctx.toolCallId,
+                runId: event.runId ?? ctx.runId,
+                params: event.params,
+                result: event.result,
+                error: event.error,
+                durationMs: event.durationMs,
+            });
+        });
     },
 };
 export default plugin;

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEhE,MAAM,MAAM,GAAG;IACb,EAAE,EAAE,OAAO;IACX,IAAI,EAAE,OAAO;IACb,WAAW,EAAE,uCAAuC;IACpD,YAAY,EAAE,uBAAuB,EAAE;IACvC,QAAQ,CAAC,GAAsB;QAC7B,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC7B,GAAG,CAAC,eAAe,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;IAC/C,CAAC;CACF,CAAC;AAEF,eAAe,MAAM,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAExF,MAAM,MAAM,GAAG;IACb,EAAE,EAAE,OAAO;IACX,IAAI,EAAE,OAAO;IACb,WAAW,EAAE,uCAAuC;IACpD,YAAY,EAAE,uBAAuB,EAAE;IACvC,QAAQ,CAAC,GAAsB;QAC7B,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC7B,GAAG,CAAC,eAAe,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;QAC7C,GAAG,CAAC,EAAE,CAAC,kBAAkB,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YAC9C,MAAM,sBAAsB,CAAC;gBAC3B,UAAU,EAAE,GAAG,CAAC,UAAU;gBAC1B,KAAK,EAAE,OAAO;gBACd,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ;gBACxC,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,GAAG,CAAC,UAAU;gBAC9C,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,GAAG,CAAC,KAAK;gBAC/B,MAAM,EAAE,KAAK,CAAC,MAAM;aACrB,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QACH,GAAG,CAAC,EAAE,CAAC,iBAAiB,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YAC7C,MAAM,sBAAsB,CAAC;gBAC3B,UAAU,EAAE,GAAG,CAAC,UAAU;gBAC1B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK;gBACpC,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ;gBACxC,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,GAAG,CAAC,UAAU;gBAC9C,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,GAAG,CAAC,KAAK;gBAC/B,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,UAAU,EAAE,KAAK,CAAC,UAAU;aAC7B,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;CACF,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/src/channel.d.ts

@@ -27,7 +27,19 @@ type ResolvedSiderAccount = {
     configured: boolean;
     config: SiderAccountConfig;
 };
+type SiderToolHookPayload = {
+    sessionKey?: string;
+    phase: "start" | "end" | "error";
+    toolName?: string;
+    toolCallId?: string;
+    runId?: string;
+    params?: Record<string, unknown>;
+    result?: unknown;
+    error?: string;
+    durationMs?: number;
+};
 export declare function setSiderRuntime(runtime: PluginRuntime): void;
+export declare function emitSiderToolHookEvent(params: SiderToolHookPayload): Promise<void>;
 export declare const siderPlugin: ChannelPlugin<ResolvedSiderAccount>;
 export {};
 //# sourceMappingURL=channel.d.ts.map

package/dist/src/channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../src/channel.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,KAAK,aAAa,EAElB,KAAK,aAAa,EAEnB,MAAM,qBAAqB,CAAC;AAQ7B,KAAK,kBAAkB,GAAG;IACxB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAMF,KAAK,oBAAoB,GAAG;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,kBAAkB,CAAC;CAC5B,CAAC;AA0HF,wBAAgB,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAE5D;AAkpCD,eAAO,MAAM,WAAW,EAAE,aAAa,CAAC,oBAAoB,CAsJ3D,CAAC"}
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../src/channel.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,KAAK,aAAa,EAElB,KAAK,aAAa,EAEnB,MAAM,qBAAqB,CAAC;AAU7B,KAAK,kBAAkB,GAAG;IACxB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAMF,KAAK,oBAAoB,GAAG;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,kBAAkB,CAAC;CAC5B,CAAC;AA+DF,KAAK,oBAAoB,GAAG;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AA8CF,wBAAgB,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAE5D;AAmyBD,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqExF;AA8yBD,eAAO,MAAM,WAAW,EAAE,aAAa,CAAC,oBAAoB,CAmK3D,CAAC"}