@kirigaya/openclaw-onebot 1.0.2 → 1.0.3

package/README.md

@@ -1,9 +1,23 @@
+<div align="center">
+
 # openclaw-onebot
 
-将 **OneBot v11 协议**（QQ/Lagrange.Core、go-cqhttp 等）接入 [OpenClaw](https://openclaw.ai) Gateway 的渠道插件。
+[OpenClaw](https://openclaw.ai)  的 **OneBot v11 协议**（QQ/Lagrange.Core、go-cqhttp 等）渠道插件。
+
+[![npm version](https://img.shields.io/npm/v/@kirigaya/openclaw-onebot?style=flat-square)](https://www.npmjs.com/package/@kirigaya/openclaw-onebot)
+[![GitHub stars](https://img.shields.io/github/stars/LSTM-Kirigaya/openclaw-onebot?style=flat-square)](https://github.com/LSTM-Kirigaya/openclaw-onebot)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D22-brightgreen?style=flat-square)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.4-blue?style=flat-square)](https://www.typescriptlang.org/)
+[![OpenClaw](https://img.shields.io/badge/OpenClaw-Plugin-9cf?style=flat-square)](https://openclaw.ai)
+
+</div>
 
-[![npm version](https://img.shields.io/npm/v/openclaw-onebot.svg)](https://www.npmjs.com/package/openclaw-onebot)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+---
+
+## 教程
+
+📖 **完整安装与配置教程**：[让 QQ 接入 openclaw！让你的助手掌管千人大群](https://kirigaya.cn/blog/article?seq=368)
 
 ## 功能
 
@@ -13,7 +27,6 @@
 - ✅ TUI 配置向导：`openclaw onebot setup`
 - ✅ 新成员入群欢迎
 - ✅ 通过 `openclaw message send` CLI 发送（无 Agent 工具，降低 token 消耗）
-- ✅ **内置定时任务**：配置 `cronJobs` 后，在指定时间直接执行脚本并推送到群聊，**无需 AI 介入**
 
 ## 安装
 
@@ -65,6 +78,68 @@ openclaw message send --channel onebot --target group:987654321 --media "file://
 
 `--target` 格式：`user:QQ号` 或 `group:群号`。回复场景由 deliver 自动投递，Agent 输出 text/mediaUrl 即会送达。
 
+## 新成员入群欢迎（自定义图片）
+
+当有新成员加入群时，可根据其 ID 信息生成欢迎图片并发送。详见 [receive.md](skills/onebot-ops/receive.md#新成员入群欢迎)。
+
+1. 在 `openclaw.json` 中配置：
+
+```json
+{
+  "channels": {
+    "onebot": {
+      "groupIncrease": {
+        "enabled": true,
+        "command": "npx tsx src/openclaw/trigger/welcome.ts",
+        "cwd": "C:/path/to/Tiphareth"
+      }
+    }
+  }
+}
+```
+
+2. `command` 在 `cwd` 下用系统 shell 执行，环境变量传入 `GROUP_ID`、`GROUP_NAME`、`USER_ID`、`USER_NAME`、`AVATAR_URL`。命令可调用 `openclaw message send` 自行发送，或向 stdout 输出 JSON 行供 handler 发送。
+
+3. 测试：`npm run test:group-increase-handler`（DRY_RUN 模式，仅生成图片）
+
+## 回复白名单
+
+默认为空回复所有人的消息。如果设置的话，那么机器人就只会回复设置的数组里的用户的消息。
+
+```json
+{
+  "channels": {
+    "onebot": {
+      "whitelistUserIds": [1193466151],
+    }
+  }
+}
+```
+
+## 新人入群触发器
+
+如果有人入群之后，可以通过这个来实现触发器。
+
+```json
+{
+  "channels": {
+    "onebot": {
+      "groupIncrease": {
+        "enabled": true,
+        "command": "npx tsx welcome.ts",
+        "cwd": "/path/to/triggers"
+      }
+    }
+  }
+}
+```
+
+实现的脚本必须支持这三个参数：
+
+```
+--userId ${userId} --username ${username} --groupId ${groupId}
+```
+
 ## 测试连接
 
 项目内提供测试脚本（需 `.env` 或环境变量）：

package/dist/channel.js

@@ -136,7 +136,7 @@ export const OneBotChannelPlugin = {
             }
             const getConfig = () => getOneBotConfig(api, accountId);
             try {
-                const result = await sendTextMessage(to, text, getConfig);
+                const result = await sendTextMessage(to, text, getConfig, cfg);
                 if (!result.ok) {
                     return { channel: "onebot", ok: false, messageId: "", error: new Error(result.error) };
                 }
@@ -159,7 +159,7 @@ export const OneBotChannelPlugin = {
             }
             const getConfig = () => getOneBotConfig(api, accountId);
             try {
-                const result = await sendMediaMessage(to, mediaUrl, text, getConfig);
+                const result = await sendMediaMessage(to, mediaUrl, text, getConfig, cfg);
                 if (!result.ok) {
                     return { channel: "onebot", ok: false, messageId: "", error: new Error(result.error) };
                 }

package/dist/config.d.ts

@@ -3,4 +3,10 @@
  */
 import type { OneBotAccountConfig } from "./types.js";
 export declare function getOneBotConfig(api: any, accountId?: string): OneBotAccountConfig | null;
+/** 是否将机器人回复中的 Markdown 渲染为纯文本再发送，默认 true */
+export declare function getRenderMarkdownToPlain(cfg: any): boolean;
+/** 是否将连续多个换行压缩为单个换行，默认 true（AI 常输出 \n\n 导致双空行） */
+export declare function getCollapseDoubleNewlines(cfg: any): boolean;
+/** 白名单 QQ 号列表，为空则所有人可回复；非空则仅白名单内用户可触发 AI */
+export declare function getWhitelistUserIds(cfg: any): number[];
 export declare function listAccountIds(apiOrCfg: any): string[];

package/dist/config.js

@@ -50,6 +50,23 @@ export function getOneBotConfig(api, accountId) {
     }
     return null;
 }
+/** 是否将机器人回复中的 Markdown 渲染为纯文本再发送，默认 true */
+export function getRenderMarkdownToPlain(cfg) {
+    const v = cfg?.channels?.onebot?.renderMarkdownToPlain;
+    return v === undefined ? true : Boolean(v);
+}
+/** 是否将连续多个换行压缩为单个换行，默认 true（AI 常输出 \n\n 导致双空行） */
+export function getCollapseDoubleNewlines(cfg) {
+    const v = cfg?.channels?.onebot?.collapseDoubleNewlines;
+    return v === undefined ? true : Boolean(v);
+}
+/** 白名单 QQ 号列表，为空则所有人可回复；非空则仅白名单内用户可触发 AI */
+export function getWhitelistUserIds(cfg) {
+    const v = cfg?.channels?.onebot?.whitelistUserIds;
+    if (!Array.isArray(v))
+        return [];
+    return v.filter((x) => typeof x === "number" || (typeof x === "string" && /^\d+$/.test(x))).map((x) => Number(x));
+}
 export function listAccountIds(apiOrCfg) {
     const cfg = apiOrCfg?.config ?? apiOrCfg ?? globalThis.__onebotGatewayConfig;
     const accounts = cfg?.channels?.onebot?.accounts;

package/dist/connection.d.ts

@@ -26,6 +26,16 @@ export declare function sendGroupImage(groupId: number, image: string, log?: {
     info?: (s: string) => void;
     warn?: (s: string) => void;
 }, getConfig?: () => OneBotAccountConfig | null): Promise<number | undefined>;
+/** 发送群合并转发消息。messages 为节点数组，每节点 { type: "node", data: { id } } 或 { type: "node", data: { user_id, nickname, content } } */
+export declare function sendGroupForwardMsg(groupId: number, messages: Array<{
+    type: string;
+    data: Record<string, unknown>;
+}>, getConfig?: () => OneBotAccountConfig | null): Promise<void>;
+/** 发送私聊合并转发消息 */
+export declare function sendPrivateForwardMsg(userId: number, messages: Array<{
+    type: string;
+    data: Record<string, unknown>;
+}>, getConfig?: () => OneBotAccountConfig | null): Promise<void>;
 export declare function sendPrivateImage(userId: number, image: string, log?: {
     info?: (s: string) => void;
     warn?: (s: string) => void;

package/dist/connection.js

@@ -11,6 +11,8 @@ import http from "http";
 import { writeFileSync, mkdirSync, readdirSync, statSync, unlinkSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
+import { logSend } from "./send-debug-log.js";
+import { shouldBlockSendInForwardMode, getActiveReplyTarget, getActiveReplySessionId } from "./reply-context.js";
 const IMAGE_TEMP_DIR = join(tmpdir(), "openclaw-onebot");
 const DOWNLOAD_TIMEOUT_MS = 30000;
 /** 使用 Node 内置 http(s) 下载 URL，避免 fetch 在某些环境下的兼容性问题 */
@@ -206,6 +208,18 @@ export async function ensureConnection(getConfig, timeoutMs = 30000) {
     return waitForConnection(timeoutMs);
 }
 export async function sendPrivateMsg(userId, text, getConfig) {
+    if (shouldBlockSendInForwardMode("private", userId)) {
+        logSend("connection", "sendPrivateMsg", { targetId: userId, blocked: true, sessionId: getActiveReplyTarget(), replySessionId: getActiveReplySessionId() });
+        return undefined;
+    }
+    logSend("connection", "sendPrivateMsg", {
+        targetType: "user",
+        targetId: userId,
+        textPreview: text?.slice(0, 80),
+        textLen: text?.length,
+        sessionId: getActiveReplyTarget(),
+        replySessionId: getActiveReplySessionId(),
+    });
     const socket = getConfig
         ? await ensureConnection(getConfig)
         : await waitForConnection();
@@ -213,9 +227,23 @@ export async function sendPrivateMsg(userId, text, getConfig) {
     if (res?.retcode !== 0) {
         throw new Error(res?.msg ?? `OneBot send_private_msg failed (retcode=${res?.retcode})`);
     }
-    return res?.data?.message_id;
+    const mid = res?.data?.message_id;
+    logSend("connection", "sendPrivateMsg", { targetId: userId, messageId: mid, sessionId: getActiveReplyTarget(), replySessionId: getActiveReplySessionId() });
+    return mid;
 }
 export async function sendGroupMsg(groupId, text, getConfig) {
+    if (shouldBlockSendInForwardMode("group", groupId)) {
+        logSend("connection", "sendGroupMsg", { targetId: groupId, blocked: true, sessionId: getActiveReplyTarget(), replySessionId: getActiveReplySessionId() });
+        return undefined;
+    }
+    logSend("connection", "sendGroupMsg", {
+        targetType: "group",
+        targetId: groupId,
+        textPreview: text?.slice(0, 80),
+        textLen: text?.length,
+        sessionId: getActiveReplyTarget(),
+        replySessionId: getActiveReplySessionId(),
+    });
     const socket = getConfig
         ? await ensureConnection(getConfig)
         : await waitForConnection();
@@ -223,9 +251,22 @@ export async function sendGroupMsg(groupId, text, getConfig) {
     if (res?.retcode !== 0) {
         throw new Error(res?.msg ?? `OneBot send_group_msg failed (retcode=${res?.retcode})`);
     }
-    return res?.data?.message_id;
+    const mid = res?.data?.message_id;
+    logSend("connection", "sendGroupMsg", { targetId: groupId, messageId: mid, sessionId: getActiveReplyTarget(), replySessionId: getActiveReplySessionId() });
+    return mid;
 }
 export async function sendGroupImage(groupId, image, log = getLogger(), getConfig) {
+    if (shouldBlockSendInForwardMode("group", groupId)) {
+        logSend("connection", "sendGroupImage", { targetId: groupId, blocked: true, sessionId: getActiveReplyTarget(), replySessionId: getActiveReplySessionId() });
+        return undefined;
+    }
+    logSend("connection", "sendGroupImage", {
+        targetType: "group",
+        targetId: groupId,
+        imagePreview: image?.slice?.(0, 60),
+        sessionId: getActiveReplyTarget(),
+        replySessionId: getActiveReplySessionId(),
+    });
     log.info?.(`[onebot] sendGroupImage entry: groupId=${groupId} image=${image?.slice?.(0, 80) ?? ""}`);
     const socket = getConfig ? await ensureConnection(getConfig) : await waitForConnection();
     log.info?.(`222[onebot] sendGroupImage entry: groupId=${groupId} image=${image?.slice?.(0, 80) ?? ""}`);
@@ -240,13 +281,58 @@ export async function sendGroupImage(groupId, image, log = getLogger(), getConfi
             throw new Error(res?.msg ?? `OneBot send_group_msg (image) failed (retcode=${res?.retcode})`);
         }
         log.info?.(`[onebot] sendGroupImage done: retcode=${res?.retcode ?? "?"}`);
-        return res?.data?.message_id;
+        const mid = res?.data?.message_id;
+        logSend("connection", "sendGroupImage", { targetId: groupId, messageId: mid, sessionId: getActiveReplyTarget(), replySessionId: getActiveReplySessionId() });
+        return mid;
     }
     catch (error) {
         log.warn?.(`[onebot] sendGroupImage error: ${error}`);
     }
 }
+/** 发送群合并转发消息。messages 为节点数组，每节点 { type: "node", data: { id } } 或 { type: "node", data: { user_id, nickname, content } } */
+export async function sendGroupForwardMsg(groupId, messages, getConfig) {
+    logSend("connection", "sendGroupForwardMsg", {
+        targetType: "group",
+        targetId: groupId,
+        nodeCount: messages.length,
+        isForward: true,
+        sessionId: getActiveReplyTarget(),
+        replySessionId: getActiveReplySessionId(),
+    });
+    const socket = getConfig ? await ensureConnection(getConfig) : await waitForConnection();
+    const res = await sendOneBotAction(socket, "send_group_forward_msg", { group_id: groupId, messages });
+    if (res?.retcode !== 0) {
+        throw new Error(res?.msg ?? `OneBot send_group_forward_msg failed (retcode=${res?.retcode})`);
+    }
+}
+/** 发送私聊合并转发消息 */
+export async function sendPrivateForwardMsg(userId, messages, getConfig) {
+    logSend("connection", "sendPrivateForwardMsg", {
+        targetType: "user",
+        targetId: userId,
+        nodeCount: messages.length,
+        isForward: true,
+        sessionId: getActiveReplyTarget(),
+        replySessionId: getActiveReplySessionId(),
+    });
+    const socket = getConfig ? await ensureConnection(getConfig) : await waitForConnection();
+    const res = await sendOneBotAction(socket, "send_private_forward_msg", { user_id: userId, messages });
+    if (res?.retcode !== 0) {
+        throw new Error(res?.msg ?? `OneBot send_private_forward_msg failed (retcode=${res?.retcode})`);
+    }
+}
 export async function sendPrivateImage(userId, image, log = getLogger(), getConfig) {
+    if (shouldBlockSendInForwardMode("private", userId)) {
+        logSend("connection", "sendPrivateImage", { targetId: userId, blocked: true, sessionId: getActiveReplyTarget(), replySessionId: getActiveReplySessionId() });
+        return undefined;
+    }
+    logSend("connection", "sendPrivateImage", {
+        targetType: "user",
+        targetId: userId,
+        imagePreview: image?.slice?.(0, 60),
+        sessionId: getActiveReplyTarget(),
+        replySessionId: getActiveReplySessionId(),
+    });
     log.info?.(`[onebot] sendPrivateImage entry: userId=${userId} image=${image?.slice?.(0, 80) ?? ""}`);
     const socket = getConfig ? await ensureConnection(getConfig) : await waitForConnection();
     const filePath = image.startsWith("[") ? null : await resolveImageToLocalPath(image);
@@ -258,7 +344,9 @@ export async function sendPrivateImage(userId, image, log = getLogger(), getConf
         throw new Error(res?.msg ?? `OneBot send_private_msg (image) failed (retcode=${res?.retcode})`);
     }
     log.info?.(`[onebot] sendPrivateImage done: retcode=${res?.retcode ?? "?"}`);
-    return res?.data?.message_id;
+    const mid = res?.data?.message_id;
+    logSend("connection", "sendPrivateImage", { targetId: userId, messageId: mid, sessionId: getActiveReplyTarget(), replySessionId: getActiveReplySessionId() });
+    return mid;
 }
 export async function uploadGroupFile(groupId, file, name) {
     if (!ws || ws.readyState !== WebSocket.OPEN)

package/dist/handlers/group-increase.d.ts

@@ -3,7 +3,8 @@
  *
  * 支持：
  * 1. 简单文本模板（message），占位符：{name}、{userId}、{groupName}、{groupId}、{avatarUrl}
- * 2. 自定义 handler 脚本，可生成图片并返回，接收完整上下文
+ * 2. 自定义 command：在 cwd 下用系统 shell 执行命令，通过环境变量传入上下文
+ *    命令自行负责发送（如调用 openclaw message send），或向 stdout 输出 JSON 行供本 handler 发送
  */
 import type { OneBotMessage } from "../types.js";
 export interface GroupIncreaseContext {

package/dist/handlers/group-increase.js

@@ -3,11 +3,14 @@
  *
  * 支持：
  * 1. 简单文本模板（message），占位符：{name}、{userId}、{groupName}、{groupId}、{avatarUrl}
- * 2. 自定义 handler 脚本，可生成图片并返回，接收完整上下文
+ * 2. 自定义 command：在 cwd 下用系统 shell 执行命令，通过环境变量传入上下文
+ *    命令自行负责发送（如调用 openclaw message send），或向 stdout 输出 JSON 行供本 handler 发送
  */
 import { sendGroupMsg, sendGroupImage, getStrangerInfo, getGroupMemberInfo, getGroupInfo, getAvatarUrl, } from "../connection.js";
-import { loadScript } from "../load-script.js";
+import { getRenderMarkdownToPlain } from "../config.js";
+import { markdownToPlain } from "../markdown.js";
 import { resolve } from "path";
+import { spawn } from "child_process";
 async function resolveContext(groupId, userId) {
     const [groupInfo, memberInfo] = await Promise.all([
         getGroupInfo(groupId),
@@ -38,6 +41,49 @@ function applyTemplate(template, ctx) {
         .replace(/\{groupId\}/g, String(ctx.groupId))
         .replace(/\{avatarUrl\}/g, ctx.avatarUrl);
 }
+function escapeForShell(s) {
+    const str = String(s);
+    if (process.platform === "win32") {
+        return '"' + str.replace(/"/g, '""') + '"';
+    }
+    return '"' + str.replace(/\\/g, "\\\\").replace(/"/g, '\\"') + '"';
+}
+function runCommand(command, cwd, args, env) {
+    const fullCmd = `${command} --userId ${args.userId} --username ${escapeForShell(args.username)} --groupId ${args.groupId}`;
+    return new Promise((resolvePromise) => {
+        const isWin = process.platform === "win32";
+        const shell = isWin ? "cmd.exe" : "sh";
+        const shellArg = isWin ? "/c" : "-c";
+        const child = spawn(shell, [shellArg, fullCmd], {
+            cwd,
+            env: { ...process.env, ...env },
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.on("data", (d) => { stdout += d.toString(); });
+        child.stderr?.on("data", (d) => { stderr += d.toString(); });
+        child.on("close", (code) => {
+            resolvePromise({ stdout, stderr, code });
+        });
+    });
+}
+function parseCommandOutput(stdout) {
+    const line = stdout.trim().split("\n").pop();
+    if (!line)
+        return null;
+    try {
+        const data = JSON.parse(line);
+        return {
+            text: typeof data.text === "string" ? data.text : undefined,
+            imagePath: typeof data.imagePath === "string" ? data.imagePath : undefined,
+            imageUrl: typeof data.imageUrl === "string" ? data.imageUrl : undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+}
 export async function handleGroupIncrease(api, msg) {
     const cfg = api.config;
     const gi = cfg?.channels?.onebot?.groupIncrease;
@@ -54,24 +100,43 @@ export async function handleGroupIncrease(api, msg) {
         return;
     }
     let result = {};
-    const handlerPath = gi?.handler;
-    if (handlerPath?.trim()) {
+    const command = gi?.command?.trim();
+    const cwd = gi?.cwd?.trim();
+    if (command && cwd) {
+        const env = {
+            GROUP_ID: String(ctx.groupId),
+            GROUP_NAME: ctx.groupName,
+            USER_ID: String(ctx.userId),
+            USER_NAME: ctx.userName,
+            AVATAR_URL: ctx.avatarUrl,
+        };
+        const args = {
+            userId: String(ctx.userId),
+            username: ctx.userName,
+            groupId: String(ctx.groupId),
+        };
         try {
-            const mod = await loadScript(handlerPath);
-            const fn = mod?.default ?? mod?.generate ?? mod;
-            if (typeof fn === "function") {
-                result = (await fn(ctx)) ?? {};
+            const { stdout, stderr, code } = await runCommand(command, resolve(cwd), args, env);
+            if (stderr)
+                api.logger?.warn?.(`[onebot] groupIncrease command stderr: ${stderr}`);
+            if (code !== 0)
+                api.logger?.warn?.(`[onebot] groupIncrease command exit code: ${code}`);
+            const parsed = parseCommandOutput(stdout);
+            if (parsed && (parsed.text || parsed.imagePath || parsed.imageUrl)) {
+                result = parsed;
             }
         }
         catch (e) {
-            api.logger?.error?.(`[onebot] groupIncrease handler failed: ${e?.message}`);
+            api.logger?.error?.(`[onebot] groupIncrease command failed: ${e?.message}`);
         }
     }
     const message = gi?.message;
-    if (message?.trim() && !result.text) {
+    if (message?.trim() && !result.text && !command) {
         result.text = applyTemplate(message, ctx);
     }
-    const text = (result.text ?? "").trim();
+    let text = (result.text ?? "").trim();
+    if (text && getRenderMarkdownToPlain(cfg))
+        text = markdownToPlain(text);
     const imagePath = result.imagePath?.trim();
     const imageUrl = result.imageUrl?.trim();
     if (!text && !imagePath && !imageUrl)
@@ -80,9 +145,10 @@ export async function handleGroupIncrease(api, msg) {
         if (text)
             await sendGroupMsg(groupId, text);
         if (imagePath) {
+            const baseDir = cwd || process.cwd();
             const abs = imagePath.startsWith("file://") || imagePath.startsWith("http://") || imagePath.startsWith("https://")
                 ? imagePath
-                : resolve(process.cwd(), imagePath);
+                : resolve(baseDir, imagePath);
             await sendGroupImage(groupId, abs);
         }
         if (imageUrl && !imagePath)

package/dist/handlers/process-inbound.d.ts

@@ -8,4 +8,22 @@ export declare const sessionHistories: Map<string, {
     timestamp: number;
     messageId: string;
 }[]>;
+export declare function startForwardCleanupTimer(): void;
 export declare function processInboundMessage(api: any, msg: OneBotMessage): Promise<void>;
+/** 回复会话上下文，供 onReplySessionEnd 钩子使用 */
+export interface ReplySessionContext {
+    /** 本次回复会话的唯一 ID，同一用户问题下的多次 deliver 共享此 ID */
+    replySessionId: string;
+    /** 会话标识，如 onebot:group:123 或 onebot:456 */
+    sessionId: string;
+    /** 回复目标，如 onebot:group:123 或 onebot:456 */
+    to: string;
+    /** 本次回复中已发送的所有块（按顺序） */
+    chunks: Array<{
+        index: number;
+        text?: string;
+        mediaUrl?: string;
+    }>;
+    /** 用户原始消息 */
+    userMessage: string;
+}