@kirigaya/openclaw-onebot 1.0.1 → 1.0.3

package/skills/onebot-ops/config.md

@@ -1,55 +1,71 @@
-# 配置参数
-
-## 参数表
-
-| 参数 | 说明 |
-|------|------|
-| type | `forward-websocket` / `backward-websocket` |
-| host | OneBot 主机地址 |
-| port | 端口 |
-| accessToken | 访问令牌（可选） |
-| path | 反向 WS 路径，默认 `/onebot/v11/ws` |
-| requireMention | 群聊是否需 @ 才回复，默认 `true` |
-| thinkingEmojiId | 表情 ID（set_msg_emoji_like），默认 60 |
-| groupIncrease | 新成员入群欢迎，详见 [receive.md](receive.md) |
-| cronJobs | 内置定时任务（无 AI 介入），详见下方 |
-
-## TUI 配置
-
-运行 `openclaw onebot setup` 进行交互式配置。
-
-配置写入 `openclaw.json` 的 `channels.onebot` 或通过 `LAGRANGE_WS_*` 环境变量提供。
-
-## 环境变量
-
-| 变量 | 说明 |
-|------|------|
-| LAGRANGE_WS_TYPE | forward-websocket / backward-websocket |
-| LAGRANGE_WS_HOST | 主机地址 |
-| LAGRANGE_WS_PORT | 端口 |
-| LAGRANGE_WS_ACCESS_TOKEN | 访问令牌 |
-| LAGRANGE_WS_PATH | 反向 WS 路径 |
-
-## cronJobs 配置
-
-在 `openclaw.json` 中配置内置定时任务，直接执行脚本并推送到群，无需 AI 介入：
-
-```json
-{
-  "channels": {
-    "onebot": {
-      "cronJobs": [
-        {
-          "name": "每日科技新闻",
-          "cron": "0 8 * * *",
-          "timezone": "Asia/Shanghai",
-          "script": "./Tiphareth/src/openclaw/cron/daily-news.ts",
-          "groupIds": [782833642, 1046693162]
-        }
-      ]
-    }
-  }
-}
-```
-
-脚本需导出 `default` / `run` / `execute` 函数，接收 `ctx: { onebot, groupIds }`。
+# 配置参数
+
+## 参数表
+
+| 参数 | 说明 |
+|------|------|
+| type | `forward-websocket` / `backward-websocket` |
+| host | OneBot 主机地址 |
+| port | 端口 |
+| accessToken | 访问令牌（可选） |
+| path | 反向 WS 路径，默认 `/onebot/v11/ws` |
+| requireMention | 群聊是否需 @ 才回复，默认 `true` |
+| whitelistUserIds | 白名单 QQ 号数组，非空时仅白名单内用户可触发 AI；为空则所有人可回复 |
+| renderMarkdownToPlain | 是否将 Markdown 转为纯文本再发送，默认 `true` |
+| collapseDoubleNewlines | 是否将连续多个换行压缩为单个，默认 `true`（减少 AI 输出的双空行） |
+| longMessageMode | 长消息模式：`normal` 正常发送、`og_image` 生成图片、`forward` 合并转发 |
+| 调试 | 设置 `OPENCLAW_ONEBOT_SEND_DEBUG=1` 可启用发送调试日志，写入 `openclaw-onebot/send-debug.log`（绝对路径见日志首行） |
+| longMessageThreshold | 长消息阈值（字符数），超过则启用 longMessageMode，默认 300 |
+| thinkingEmojiId | 表情 ID（set_msg_emoji_like），默认 60 |
+| groupIncrease | 新成员入群欢迎（enabled、message、command、cwd），详见 [receive.md](receive.md) |
+| cronJobs | 内置定时任务（无 AI 介入），详见下方 |
+
+## TUI 配置
+
+运行 `openclaw onebot setup` 进行交互式配置。
+
+配置写入 `openclaw.json` 的 `channels.onebot` 或通过 `ONEBOT_WS_*` 环境变量提供。
+
+## 环境变量
+
+| 变量 | 说明 |
+|------|------|
+| ONEBOT_WS_TYPE | forward-websocket / backward-websocket |
+| ONEBOT_WS_HOST | 主机地址 |
+| ONEBOT_WS_PORT | 端口 |
+| ONEBOT_WS_ACCESS_TOKEN | 访问令牌 |
+| ONEBOT_WS_PATH | 反向 WS 路径 |
+
+## cronJobs 配置
+
+在 `openclaw.json` 中配置内置定时任务，直接执行脚本并推送到群，无需 AI 介入：
+
+```json
+{
+  "channels": {
+    "onebot": {
+      "cronJobs": [
+        {
+          "name": "每日科技新闻",
+          "cron": "0 8 * * *",
+          "timezone": "Asia/Shanghai",
+          "script": "./Tiphareth/src/openclaw/cron/daily-news.ts",
+          "groupIds": [782833642, 1046693162]
+        }
+      ]
+    }
+  }
+}
+```
+
+脚本需导出 `default` / `run` / `execute` 函数，接收 `ctx: { onebot, groupIds }`。
+
+## 长消息处理
+
+当单次回复超过 `longMessageThreshold` 字符时，根据 `longMessageMode` 处理：
+
+| 模式 | 说明 |
+|------|------|
+| normal | 正常分段发送（默认） |
+| og_image | 将 Markdown 渲染为 HTML 并生成图片发送。需安装 `node-html-to-image`：`npm install node-html-to-image`。此模式下保留 Markdown 格式与代码高亮 |
+| forward | 将各块消息先发给自己，再打包为合并转发发送。需 OneBot 实现支持 `send_group_forward_msg` / `send_private_forward_msg` |

package/skills/onebot-ops/receive.md

@@ -12,6 +12,43 @@ Agent 的回复通过 deliver 自动发送，支持：
 - **mediaUrl**：图片（`file://`、`http://`、`base64://`）
 - 无需 Agent 工具，Agent 输出即会送达
 
+## 同一问题下的多次发送（回复会话）
+
+AI 对一条用户消息可能分多次 deliver（流式输出多块内容）。**会话追踪是内置的，无需配置**：每次收到消息时自动设置 `sessionId`（如 `onebot:group:123`）和 `replySessionId`，发送时通过 reply-context 关联到对应会话。
+
+可选扩展：
+
+1. **replySessionId**：每次用户发消息会生成唯一的 `replySessionId`，同一问题下的所有 deliver 共享此 ID。可通过 `getActiveReplySessionId()`（reply-context）在发送时获取。调试日志（`OPENCLAW_ONEBOT_SEND_DEBUG=1`）会输出 `sessionId` 和 `replySessionId`。
+
+2. **onReplySessionEnd 钩子**（可选）：在 `openclaw.json` 中配置 `onReplySessionEnd` 为脚本路径，回复完成时（`info.kind === "final"`）会调用，传入：
+   - `replySessionId`：本次回复会话 ID
+   - `sessionId`：会话标识（如 `onebot:group:123`）
+   - `to`：回复目标
+   - `chunks`：已发送的所有块 `[{ index, text?, mediaUrl? }]`
+   - `userMessage`：用户原始消息
+
+```json
+{
+  "channels": {
+    "onebot": {
+      "onReplySessionEnd": "./on-reply-session-end.mjs"
+    }
+  }
+}
+```
+
+**无需此钩子即可知道每条发送属于哪个会话**：会话在收到消息时已自动建立，发送时通过 reply-context 关联。此钩子仅用于「回复完成后做额外处理」（如日志、合并、上报）。
+
+```js
+// on-reply-session-end.mjs
+export default async function (ctx) {
+  const { replySessionId, chunks, userMessage } = ctx;
+  const fullText = chunks.map((c) => c.text).filter(Boolean).join("\n");
+  console.log(`[${replySessionId}] 用户: ${userMessage} -> AI: ${fullText}`);
+  // 可做日志、合并、上报等统一处理
+}
+```
+
 ## 使用 message 工具发送时
 
 若 Agent 调用 `message` 工具（action: send）发送消息或图片：
@@ -54,9 +91,11 @@ Agent 的回复通过 deliver 自动发送，支持：
 | `{groupId}` | 群号 |
 | `{avatarUrl}` | 新成员头像链接 |
 
-### 自定义 handler 脚本
+### 自定义 command（生成图片并发送）
+
+当需要根据新成员 ID 信息生成图片并发送时，配置 `command` 和 `cwd`。命令在 `cwd` 下用系统 shell 执行，通过环境变量传入上下文。
 
-需要生成图片、调用外部 API 时，可配置 `handler` 路径（.mjs 或 .ts/.mts）：
+**1. 在 openclaw.json 中配置：**
 
 ```json
 {
@@ -64,22 +103,59 @@ Agent 的回复通过 deliver 自动发送，支持：
     "onebot": {
       "groupIncrease": {
         "enabled": true,
-        "handler": "./welcome.mjs"
+        "command": "npx tsx src/openclaw/trigger/welcome.ts",
+        "cwd": "C:/path/to/Tiphareth"
       }
     }
   }
 }
 ```
 
-脚本接收上下文 `ctx`，返回 `{ text?, imagePath?, imageUrl? }`：
+- **command**：在 cwd 下执行的命令（如 `npx tsx welcome.ts`）
+- **cwd**：命令执行的工作目录（绝对路径）
 
-```js
-// welcome.mjs 或 welcome.ts
-export default async function (ctx) {
-  // ctx: { groupId, groupName, userId, userName, avatarUrl }
-  // 可用 ctx.avatarUrl 获取头像，生成图片后写入文件
-  const path = "./welcome-out.png";
-  // ... 你的图片生成逻辑 ...
-  return { text: `欢迎 ${ctx.userName}！`, imagePath: path };
+**2. 调用方注入参数（追加到 command 末尾）：**
+
+| 参数 | 说明 |
+|------|------|
+| `--userId` | 新成员 QQ 号 |
+| `--username` | 新成员昵称（含空格会正确转义） |
+| `--groupId` | 群号 |
+
+环境变量（可选补充）：`GROUP_NAME`、`AVATAR_URL`
+
+**3. 命令两种用法：**
+
+- **自行发送**：命令内调用 `openclaw message send` 发送图片和文本，无需输出
+- **输出 JSON**：向 stdout 输出一行 JSON `{"text":"...","imagePath":"..."}` 或 `{"imageUrl":"..."}`，由 handler 代为发送
+
+**4. Tiphareth welcome.ts 示例：**
+
+Tiphareth 的 `welcome.ts` 生成欢迎图后调用 `openclaw message send` 发送：
+
+```json
+{
+  "groupIncrease": {
+    "enabled": true,
+    "command": "npx tsx src/openclaw/trigger/welcome.ts",
+    "cwd": "C:/Users/K/project/Lagrange.onebot/Tiphareth"
+  }
 }
 ```
+
+需确保 Gateway 已启动，且 `openclaw` CLI 可用。
+
+### 测试欢迎（无需真人入群）
+
+**方式一：群内 @ 机器人并发送 /group-increase**
+
+在群内 @ 机器人并发送 `/group-increase`，会模拟当前发送者入群并触发欢迎。上下文（userId、nickname、群名等）取自该人的真实信息。需 `groupIncrease.enabled: true`。
+
+**方式二：CLI 脚本**
+
+```bash
+cd openclaw-onebot
+npm run test:group-welcome -- --group <群号> --user <QQ号>
+```
+
+可选 `--config ./path/to/openclaw.json` 指定配置文件。脚本会连接 OneBot 并模拟指定用户入群。