@kirigaya/openclaw-onebot 1.0.3 → 1.0.4

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 LSTM-Kirigaya
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 LSTM-Kirigaya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -23,9 +23,13 @@
 
 - ✅ 私聊：所有消息 AI 都会回复
 - ✅ 群聊：仅当用户 @ 机器人时回复（可配置）
-- ✅ 正向 / 反向 WebSocket 连接
-- ✅ TUI 配置向导：`openclaw onebot setup`
+- ✅ 自动获取上下文
 - ✅ 新成员入群欢迎
+- ✅ 自动合并转发长消息
+- ✅ normal 模式准流式回复：按短时间窗口聚合后增量发送，避免等到最后一次性吐出
+- ✅ **长消息生成图片**：超过阈值可将 Markdown 渲染为图片发送（可选主题：default / dust / custom 自定义 CSS）
+- ✅ 支持文件，图像读取/上传
+- ✅ 支持白名单系统
 - ✅ 通过 `openclaw message send` CLI 发送（无 Agent 工具，降低 token 消耗）
 
 ## 安装
@@ -64,6 +68,76 @@ openclaw onebot setup
 2. 重启 Gateway：`openclaw gateway restart`
 3. 在 QQ 私聊或群聊中发消息（群聊需 @ 机器人）
 
+## 长消息处理与 OG 图片渲染
+
+当单次回复超过**长消息阈值**（默认 300 字）时，可选用三种模式（`openclaw onebot setup` 中配置）：
+
+| 模式 | 说明 |
+|------|------|
+| `normal` | 准流式分段发送：边生成边聚合，按时间窗口或长度阈值增量发送 |
+| `og_image` | 将 Markdown 转为 HTML 再生成图片发送（需安装 `node-html-to-image`） |
+| `forward` | 合并转发（发给自己后打包转发） |
+
+`normal` 模式默认会开启块流式接收，并在插件侧做短时间聚合，默认规则：
+
+- `normalModeFlushIntervalMs`: `1200`
+- `normalModeFlushChars`: `160`
+
+也就是回复不会逐 token 刷屏，而是大约每 1.2 秒或累计到 160 字左右就发送一段。可在 `openclaw.json` 中手动调整：
+
+```json
+{
+  "channels": {
+    "onebot": {
+      "longMessageMode": "normal",
+      "normalModeFlushIntervalMs": 1200,
+      "normalModeFlushChars": 160
+    }
+  }
+}
+```
+
+选择 **生成图片发送（og_image）** 时，会额外询问**渲染主题**：
+
+| 选项 | 说明 |
+|------|------|
+| **default** | 无额外样式，默认白底黑字 |
+| **dust** | 内置主题：暖色、旧纸质感 |
+| **custom** | 自定义：在 `ogImageRenderThemePath` 中填写 CSS 文件绝对路径 |
+
+配置项（枚举 + 可选路径）：
+
+- `ogImageRenderTheme`：`"default"` | `"dust"` | `"custom"`
+- `ogImageRenderThemePath`：当为 `custom` 时必填，CSS 文件绝对路径
+
+示例（`openclaw.json`）：
+
+```json
+{
+  "channels": {
+    "onebot": {
+      "longMessageMode": "og_image",
+      "longMessageThreshold": 300,
+      "ogImageRenderTheme": "dust"
+    }
+  }
+}
+```
+
+自定义主题示例：
+
+```json
+{
+  "channels": {
+    "onebot": {
+      "longMessageMode": "og_image",
+      "ogImageRenderTheme": "custom",
+      "ogImageRenderThemePath": "C:/path/to/your-theme.css"
+    }
+  }
+}
+```
+
 ## 主动发送消息
 
 通过 `openclaw message send` CLI（无需 Agent 工具）：
@@ -140,7 +214,9 @@ openclaw message send --channel onebot --target group:987654321 --media "file://
 --userId ${userId} --username ${username} --groupId ${groupId}
 ```
 
-## 测试连接
+## 测试
+
+### 测试连接
 
 项目内提供测试脚本（需 `.env` 或环境变量）：
 
@@ -149,6 +225,22 @@ cd openclaw-onebot
 npm run test:connect
 ```
 
+### 测试 OG 图片渲染效果
+
+用于预览「Markdown 转图片」在不同主题下的渲染效果（需安装 `node-html-to-image`）：
+
+```bash
+cd openclaw-onebot
+# 无额外样式
+npm run test:render-og-image -- default
+# 内置 dust 主题
+npm run test:render-og-image -- dust
+# 自定义 CSS 文件（绝对路径）
+npm run test:render-og-image -- "C:/path/to/your-theme.css"
+```
+
+生成图片保存在 `test/output-render-<主题>.png`，可直接打开查看。
+
 ## 参考
 
 - [OneBot 11](https://github.com/botuniverse/onebot-11)

package/dist/cli-commands.d.ts

@@ -0,0 +1,4 @@
+/**
+ * OneBot CLI 子命令：与 Agent 工具等价，供人工/工作流/AI 调用
+ */
+export declare function registerOneBotCli(onebot: any, api: any): void;

package/dist/cli-commands.js

@@ -0,0 +1,119 @@
+/**
+ * OneBot CLI 子命令：与 Agent 工具等价，供人工/工作流/AI 调用
+ */
+import { getOneBotConfig } from "./config.js";
+import { ensureConnection, getGroupMsgHistory, getGroupMsgHistoryInRange, searchGroupMemberByName, uploadGroupFile, uploadPrivateFile, } from "./connection.js";
+function getApi() {
+    return globalThis.__onebotApi;
+}
+async function ensureOneBotConnection() {
+    const api = getApi();
+    const config = getOneBotConfig(api);
+    if (!config) {
+        console.error("OneBot 未配置，请先运行 openclaw onebot setup 或配置 openclaw.json channels.onebot");
+        process.exit(1);
+    }
+    await ensureConnection(() => getOneBotConfig(getApi()), 15000);
+}
+function parseGroupId(v) {
+    const n = parseInt(String(v).trim(), 10);
+    if (!Number.isFinite(n)) {
+        console.error("--group-id 必须为数字");
+        process.exit(1);
+    }
+    return n;
+}
+export function registerOneBotCli(onebot, api) {
+    if (!onebot || typeof onebot.command !== "function")
+        return;
+    onebot
+        .command("get-group-msg-history")
+        .description("获取群历史消息（单页或最近 N 小时内，始终从旧到新），需 Lagrange.Core")
+        .requiredOption("--group-id <id>", "群号")
+        .option("--hours <n>", "获取最近 N 小时内的消息（指定后按时间范围分页拉取）")
+        .option("--count <n>", "条数（未指定 --hours 时生效）", "50")
+        .option("--limit <n>", "指定 --hours 时最多条数", "3000")
+        .option("--chunk-size <n>", "指定 --hours 时每页条数", "100")
+        .option("--message-seq <seq>", "起始消息序号（分页用，未指定 --hours 时生效）")
+        .action(async (opts) => {
+        await ensureOneBotConnection();
+        const groupId = parseGroupId(opts.groupId);
+        const hoursOpt = opts.hours != null && opts.hours !== "" ? parseInt(String(opts.hours), 10) : undefined;
+        if (Number.isFinite(hoursOpt) && hoursOpt > 0) {
+            const hours = hoursOpt;
+            const limit = parseInt(String(opts.limit || 3000), 10) || 3000;
+            const chunkSize = parseInt(String(opts.chunkSize || 100), 10) || 100;
+            const startTime = Math.floor(Date.now() / 1000) - hours * 3600;
+            const msgs = await getGroupMsgHistoryInRange(groupId, { startTime, limit, chunkSize });
+            const lines = msgs.map((m) => {
+                const text = typeof m.message === "string" ? m.message : JSON.stringify(m.message);
+                const nick = m.sender?.nickname ?? m.sender?.user_id ?? "?";
+                return `[${new Date(m.time * 1000).toISOString()}] ${nick}: ${text.slice(0, 200)}`;
+            });
+            console.log(lines.join("\n") || "无历史消息");
+            return;
+        }
+        const count = parseInt(String(opts.count || 50), 10) || 50;
+        const messageSeq = opts.messageSeq != null ? parseInt(String(opts.messageSeq), 10) : undefined;
+        const msgs = await getGroupMsgHistory(groupId, {
+            count,
+            reverse_order: true,
+            message_seq: Number.isFinite(messageSeq) ? messageSeq : undefined,
+        });
+        const lines = msgs.map((m) => {
+            const text = typeof m.message === "string" ? m.message : JSON.stringify(m.message);
+            const nick = m.sender?.nickname ?? m.sender?.user_id ?? "?";
+            return `[${new Date(m.time * 1000).toISOString()}] ${nick}: ${text.slice(0, 200)}`;
+        });
+        console.log(lines.join("\n") || "无历史消息");
+    });
+    onebot
+        .command("search-group-member")
+        .description("按名字模糊搜索群成员，返回 QQ 与展示名")
+        .requiredOption("--group-id <id>", "群号")
+        .requiredOption("--name <name>", "要搜索的名字（群名片或昵称）")
+        .action(async (opts) => {
+        await ensureOneBotConnection();
+        const groupId = parseGroupId(opts.groupId);
+        const name = String(opts.name || "").trim();
+        if (!name) {
+            console.error("--name 不能为空");
+            process.exit(1);
+        }
+        const list = await searchGroupMemberByName(groupId, name);
+        if (list.length === 0) {
+            console.log(`未找到匹配「${name}」的群成员`);
+            return;
+        }
+        list.forEach((m) => console.log(`QQ: ${m.user_id}  展示名: ${m.displayName}`));
+    });
+    onebot
+        .command("upload-file")
+        .description("上传文件到群或私聊")
+        .requiredOption("--target <t>", "group:<群号> 或 user:<QQ号>")
+        .requiredOption("--file <path>", "本地文件绝对路径")
+        .requiredOption("--name <name>", "显示文件名")
+        .action(async (opts) => {
+        await ensureOneBotConnection();
+        const t = String(opts.target || "").replace(/^onebot:/i, "").trim();
+        const file = String(opts.file || "").trim();
+        const name = String(opts.name || "").trim();
+        if (!file || !name) {
+            console.error("--file 与 --name 必填");
+            process.exit(1);
+        }
+        const getConfig = () => getOneBotConfig(getApi());
+        if (t.startsWith("group:")) {
+            await uploadGroupFile(parseInt(t.slice(6), 10), file, name, getConfig);
+            console.log("群文件上传成功");
+        }
+        else if (t.startsWith("user:")) {
+            await uploadPrivateFile(parseInt(t.replace(/^user:/, ""), 10), file, name, getConfig);
+            console.log("私聊文件上传成功");
+        }
+        else {
+            console.error("--target 格式须为 group:<群号> 或 user:<QQ号>");
+            process.exit(1);
+        }
+    });
+}

package/dist/config.d.ts

@@ -7,6 +7,15 @@ export declare function getOneBotConfig(api: any, accountId?: string): OneBotAcc
 export declare function getRenderMarkdownToPlain(cfg: any): boolean;
 /** 是否将连续多个换行压缩为单个换行，默认 true（AI 常输出 \n\n 导致双空行） */
 export declare function getCollapseDoubleNewlines(cfg: any): boolean;
+/** normal 模式下聚合发送的等待窗口，默认 1200ms */
+export declare function getNormalModeFlushIntervalMs(cfg: any): number;
+/** normal 模式下聚合发送的字符阈值，达到后提前 flush，默认 160 */
+export declare function getNormalModeFlushChars(cfg: any): number;
 /** 白名单 QQ 号列表，为空则所有人可回复；非空则仅白名单内用户可触发 AI */
 export declare function getWhitelistUserIds(cfg: any): number[];
+/**
+ * OG 图片渲染主题：枚举 default（无额外样式）、dust（内置）、custom（使用 ogImageRenderThemePath）
+ * 返回用于 getMarkdownStyles 的值：default | dust | 自定义 CSS 绝对路径
+ */
+export declare function getOgImageRenderTheme(cfg: any): "default" | "dust" | string;
 export declare function listAccountIds(apiOrCfg: any): string[];

package/dist/config.js

@@ -55,11 +55,24 @@ export function getRenderMarkdownToPlain(cfg) {
     const v = cfg?.channels?.onebot?.renderMarkdownToPlain;
     return v === undefined ? true : Boolean(v);
 }
+function getFiniteNumber(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
 /** 是否将连续多个换行压缩为单个换行，默认 true（AI 常输出 \n\n 导致双空行） */
 export function getCollapseDoubleNewlines(cfg) {
     const v = cfg?.channels?.onebot?.collapseDoubleNewlines;
     return v === undefined ? true : Boolean(v);
 }
+/** normal 模式下聚合发送的等待窗口，默认 1200ms */
+export function getNormalModeFlushIntervalMs(cfg) {
+    const value = getFiniteNumber(cfg?.channels?.onebot?.normalModeFlushIntervalMs, 1200);
+    return Math.max(200, Math.min(5000, Math.round(value)));
+}
+/** normal 模式下聚合发送的字符阈值，达到后提前 flush，默认 160 */
+export function getNormalModeFlushChars(cfg) {
+    const value = getFiniteNumber(cfg?.channels?.onebot?.normalModeFlushChars, 160);
+    return Math.max(20, Math.min(2000, Math.round(value)));
+}
 /** 白名单 QQ 号列表，为空则所有人可回复；非空则仅白名单内用户可触发 AI */
 export function getWhitelistUserIds(cfg) {
     const v = cfg?.channels?.onebot?.whitelistUserIds;
@@ -67,6 +80,19 @@ export function getWhitelistUserIds(cfg) {
         return [];
     return v.filter((x) => typeof x === "number" || (typeof x === "string" && /^\d+$/.test(x))).map((x) => Number(x));
 }
+/**
+ * OG 图片渲染主题：枚举 default（无额外样式）、dust（内置）、custom（使用 ogImageRenderThemePath）
+ * 返回用于 getMarkdownStyles 的值：default | dust | 自定义 CSS 绝对路径
+ */
+export function getOgImageRenderTheme(cfg) {
+    const v = cfg?.channels?.onebot?.ogImageRenderTheme;
+    const path = (cfg?.channels?.onebot?.ogImageRenderThemePath ?? "").trim();
+    if (v === "dust")
+        return "dust";
+    if (v === "custom" && path.length > 0)
+        return path;
+    return "default";
+}
 export function listAccountIds(apiOrCfg) {
     const cfg = apiOrCfg?.config ?? apiOrCfg ?? globalThis.__onebotGatewayConfig;
     const accounts = cfg?.channels?.onebot?.accounts;

package/dist/connection.d.ts

@@ -1,7 +1,9 @@
 /**
  * OneBot WebSocket 连接与 API 调用
  *
- * 图片消息：网络 URL 会先下载到本地再发送（兼容 Lagrange.Core retcode 1200），
+ * 图片消息：
+ * - 本机回环连接时：网络 URL 会先下载到本地再发送（兼容部分实现的 retcode 1200）
+ * - 跨机器连接时：本地文件会自动转成 base64://，避免把宿主机绝对路径发给远端 OneBot
  * 并定期清理临时文件。
  */
 import WebSocket from "ws";
@@ -40,8 +42,8 @@ export declare function sendPrivateImage(userId: number, image: string, log?: {
     info?: (s: string) => void;
     warn?: (s: string) => void;
 }, getConfig?: () => OneBotAccountConfig | null): Promise<number | undefined>;
-export declare function uploadGroupFile(groupId: number, file: string, name: string): Promise<void>;
-export declare function uploadPrivateFile(userId: number, file: string, name: string): Promise<void>;
+export declare function uploadGroupFile(groupId: number, file: string, name: string, getConfig?: () => OneBotAccountConfig | null): Promise<void>;
+export declare function uploadPrivateFile(userId: number, file: string, name: string, getConfig?: () => OneBotAccountConfig | null): Promise<void>;
 /** 撤回消息 */
 export declare function deleteMsg(messageId: number): Promise<void>;
 /**
@@ -60,6 +62,26 @@ export declare function getGroupMemberInfo(groupId: number, userId: number): Pro
     nickname: string;
     card: string;
 } | null>;
+/** 群成员简要信息（用于列表与搜索） */
+export interface GroupMemberItem {
+    user_id: number;
+    nickname: string;
+    card: string;
+}
+/**
+ * 获取群成员列表（OneBot get_group_member_list）
+ */
+export declare function getGroupMemberList(groupId: number): Promise<GroupMemberItem[]>;
+/**
+ * 按名字模糊匹配群成员（匹配群名片 card 与昵称 nickname），返回匹配到的 QQ 与展示名。
+ * 使用 Fuse.js 模糊匹配，结果按相关度排序。
+ */
+export declare function searchGroupMemberByName(groupId: number, name: string): Promise<Array<{
+    user_id: number;
+    nickname: string;
+    card: string;
+    displayName: string;
+}>>;
 /** 获取群信息（含 group_name） */
 export declare function getGroupInfo(groupId: number): Promise<{
     group_name: string;
@@ -79,19 +101,44 @@ export declare function getMsg(messageId: number): Promise<{
     message: string | unknown[];
 } | null>;
 /**
- * 获取群聊历史消息（Lagrange.Core 扩展 API，go-cqhttp 等可能不支持）
+ * 获取群聊历史消息（Lagrange.Core 扩展 API，与 Lagrange.onebot context 一致）
+ * 仅使用 message_seq 分页（不传 message_id），与 Tiphareth getLast24HGroupMessages 调用方式一致。
  * @param groupId 群号
- * @param opts message_seq 起始序号；message_id 起始消息 ID；count 数量
+ * @param opts message_seq 起始序号（不传表示从最新一页）；count 本页条数；reverse_order true 表示从旧到新，便于用 batch[0].message_seq 向前翻页
  */
 export declare function getGroupMsgHistory(groupId: number, opts?: {
     message_seq?: number;
     message_id?: number;
     count: number;
+    reverse_order?: boolean;
 }): Promise<Array<{
     time: number;
     message_type: string;
     message_id: number;
-    real_id: number;
+    real_id?: number;
+    message_seq?: number;
+    sender: {
+        user_id?: number;
+        nickname?: string;
+    };
+    message: string | unknown[];
+}>>;
+/**
+ * 按时间范围分页获取群历史消息，严格对齐 Tiphareth getLast24HGroupMessages 算法：
+ * getGroupMsgHistory(groupId, messageSeq, chunkSize, true)，用 batch[0] 的 message_seq 向前翻页，去重与时间截断。
+ * @param groupId 群号
+ * @param opts startTime 仅保留 >= startTime 的消息（Unix 秒）；limit 最多条数；chunkSize 每页条数
+ */
+export declare function getGroupMsgHistoryInRange(groupId: number, opts?: {
+    startTime?: number;
+    limit?: number;
+    chunkSize?: number;
+}): Promise<Array<{
+    time: number;
+    message_type: string;
+    message_id: number;
+    real_id?: number;
+    message_seq?: number;
     sender: {
         user_id?: number;
         nickname?: string;