@kirigaya/openclaw-onebot 1.0.3 → 1.0.5

package/dist/markdown-to-html.js

@@ -2,24 +2,32 @@
  * Markdown 转 HTML（保留格式，含代码高亮）
  * 用于 OG 图片模式下的 Markdown 渲染
  */
+import { readFileSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
 import { marked } from "marked";
 import hljs from "highlight.js";
-const HIGHLIGHT_CSS = `
-.hljs{display:block;overflow-x:auto;padding:1em;background:#1e1e1e;color:#d4d4d4;border-radius:6px;font-family:Consolas,Monaco,monospace;font-size:13px;line-height:1.5}
-.hljs-keyword{color:#569cd6}
-.hljs-string{color:#ce9178}
-.hljs-number{color:#b5cea8}
-.hljs-comment{color:#6a9955}
-.hljs-function{color:#dcdcaa}
-.hljs-title{color:#4ec9b0}
-.hljs-params{color:#9cdcfe}
-.hljs-built_in{color:#4ec9b0}
-.hljs-class{color:#4ec9b0}
-.hljs-variable{color:#9cdcfe}
-.hljs-attr{color:#9cdcfe}
-.hljs-tag{color:#569cd6}
-.hljs-name{color:#569cd6}
-.hljs-meta{color:#808080}
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** 内置 dust 主题 CSS 文件路径（相对当前模块，包根目录下的 themes/dust.css） */
+function getDustThemePath() {
+    return join(__dirname, "..", "themes", "dust.css");
+}
+const HIGHLIGHT_CSS = `
+.hljs{display:block;overflow-x:auto;padding:1em;background:#1e1e1e;color:#d4d4d4;border-radius:6px;font-family:Consolas,Monaco,monospace;font-size:13px;line-height:1.5}
+.hljs-keyword{color:#569cd6}
+.hljs-string{color:#ce9178}
+.hljs-number{color:#b5cea8}
+.hljs-comment{color:#6a9955}
+.hljs-function{color:#dcdcaa}
+.hljs-title{color:#4ec9b0}
+.hljs-params{color:#9cdcfe}
+.hljs-built_in{color:#4ec9b0}
+.hljs-class{color:#4ec9b0}
+.hljs-variable{color:#9cdcfe}
+.hljs-attr{color:#9cdcfe}
+.hljs-tag{color:#569cd6}
+.hljs-name{color:#569cd6}
+.hljs-meta{color:#808080}
 `;
 function highlightCode(code, lang) {
     if (lang && hljs.getLanguage(lang)) {
@@ -42,34 +50,62 @@ marked.use({
         },
     },
 });
-const WRAPPER_STYLE = `
-<style>
-*{margin:0;padding:0;box-sizing:border-box}
-body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;font-size:15px;line-height:1.6;color:#24292e;background:#fff;padding:24px;max-width:800px}
-h1,h2,h3,h4,h5,h6{margin:16px 0 8px;font-weight:600;line-height:1.25}
-h1{font-size:1.5em}
-h2{font-size:1.3em}
-h3{font-size:1.15em}
-p{margin:8px 0}
-ul,ol{margin:8px 0;padding-left:24px}
-li{margin:4px 0}
-code{background:#f6f8fa;padding:2px 6px;border-radius:4px;font-size:0.9em;font-family:Consolas,Monaco,monospace}
-pre{margin:12px 0;overflow-x:auto}
-pre code{background:transparent;padding:0}
-blockquote{border-left:4px solid #dfe2e5;padding-left:16px;margin:8px 0;color:#6a737d}
-a{color:#0366d6;text-decoration:none}
-a:hover{text-decoration:underline}
-table{border-collapse:collapse;margin:12px 0}
-th,td{border:1px solid #dfe2e5;padding:8px 12px;text-align:left}
-th{background:#f6f8fa;font-weight:600}
-${HIGHLIGHT_CSS}
-</style>
+const WRAPPER_STYLE = `
+<style>
+*{margin:0;padding:0;box-sizing:border-box}
+body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;font-size:15px;line-height:1.6;color:#24292e;background:#fff;padding:24px;max-width:800px}
+h1,h2,h3,h4,h5,h6{margin:16px 0 8px;font-weight:600;line-height:1.25}
+h1{font-size:1.5em}
+h2{font-size:1.3em}
+h3{font-size:1.15em}
+p{margin:8px 0}
+ul,ol{margin:8px 0;padding-left:24px}
+li{margin:4px 0}
+code{background:#f6f8fa;padding:2px 6px;border-radius:4px;font-size:0.9em;font-family:Consolas,Monaco,monospace}
+pre{margin:12px 0;overflow-x:auto}
+pre code{background:transparent;padding:0}
+blockquote{border-left:4px solid #dfe2e5;padding-left:16px;margin:8px 0;color:#6a737d}
+a{color:#0366d6;text-decoration:none}
+a:hover{text-decoration:underline}
+table{border-collapse:collapse;margin:12px 0}
+th,td{border:1px solid #dfe2e5;padding:8px 12px;text-align:left}
+th{background:#f6f8fa;font-weight:600}
+${HIGHLIGHT_CSS}
+</style>
 `;
 export function markdownToHtml(md) {
     if (!md || typeof md !== "string")
         return "";
     return marked.parse(md, { async: false });
 }
-export function getMarkdownStyles() {
-    return WRAPPER_STYLE;
+/**
+ * 获取用于 OG 图片的完整样式（基础 + 主题）
+ * @param theme "default" 无额外样式；"dust" 内置 dust 主题；或 custom 时的 CSS 文件绝对路径
+ */
+export function getMarkdownStyles(theme) {
+    let extra = "";
+    const t = (theme || "default").trim();
+    if (t === "dust") {
+        const dustPath = getDustThemePath();
+        try {
+            if (existsSync(dustPath)) {
+                const dustCss = readFileSync(dustPath, "utf-8");
+                extra = `<style>body{background:var(--background) !important;padding:24px;max-width:800px;}${dustCss}</style>`;
+            }
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    else if (t !== "default" && t !== "none" && (t.includes("/") || t.includes("\\"))) {
+        try {
+            if (existsSync(t)) {
+                extra = `<style>${readFileSync(t, "utf-8")}</style>`;
+            }
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    return WRAPPER_STYLE + extra;
 }

package/dist/og-image.d.ts

@@ -2,4 +2,6 @@
  * Markdown 转 OG 图片
  * 依赖可选的 node-html-to-image（需安装：npm install node-html-to-image）
  */
-export declare function markdownToImage(md: string): Promise<string | null>;
+export declare function markdownToImage(md: string, opts?: {
+    theme?: string;
+}): Promise<string | null>;

package/dist/og-image.js

@@ -7,7 +7,7 @@ import { join } from "path";
 import { tmpdir } from "os";
 import { markdownToHtml, getMarkdownStyles } from "./markdown-to-html.js";
 const OG_TEMP_DIR = join(tmpdir(), "openclaw-onebot-og");
-export async function markdownToImage(md) {
+export async function markdownToImage(md, opts) {
     if (!md?.trim())
         return null;
     let nodeHtmlToImage;
@@ -21,8 +21,10 @@ export async function markdownToImage(md) {
     if (!nodeHtmlToImage)
         return null;
     const bodyHtml = markdownToHtml(md);
-    const styles = getMarkdownStyles();
-    const fullHtml = `<!DOCTYPE html><html><head><meta charset="utf-8">${styles}</head><body>${bodyHtml}</body></html>`;
+    const styles = getMarkdownStyles(opts?.theme);
+    const theme = (opts?.theme || "").trim();
+    const wrappedBody = theme === "dust" ? `<div class="markdown">${bodyHtml}</div>` : bodyHtml;
+    const fullHtml = `<!DOCTYPE html><html><head><meta charset="utf-8">${styles}</head><body>${wrappedBody}</body></html>`;
     mkdirSync(OG_TEMP_DIR, { recursive: true });
     const outPath = join(OG_TEMP_DIR, `og-${Date.now()}-${Math.random().toString(36).slice(2)}.png`);
     try {
@@ -31,7 +33,11 @@ export async function markdownToImage(md) {
             html: fullHtml,
             type: "png",
             quality: 90,
-            puppeteerArgs: { headless: true, args: ["--no-sandbox", "--disable-setuid-sandbox"] },
+            puppeteerArgs: {
+                headless: true,
+                args: ["--no-sandbox", "--disable-setuid-sandbox"],
+                executablePath: process.env.PUPPETEER_EXECUTABLE_PATH || "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+            },
         });
         return `file://${outPath.replace(/\\/g, "/")}`;
     }

package/dist/setup.js

@@ -49,6 +49,27 @@ export async function runOneBotSetup() {
         ],
         initialValue: "normal",
     }));
+    let ogImageRenderTheme = "default";
+    let ogImageRenderThemePath;
+    if (longMessageMode === "og_image") {
+        const themeChoice = guardCancel(await clackSelect({
+            message: "长消息生成图片时的渲染样式：",
+            options: [
+                { value: "default", label: "default（无额外样式，默认白底黑字）" },
+                { value: "dust", label: "dust（内置暖色旧纸质感）" },
+                { value: "custom", label: "custom（自定义 CSS 文件路径）" },
+            ],
+            initialValue: "default",
+        }));
+        ogImageRenderTheme = themeChoice;
+        if (themeChoice === "custom") {
+            const customPath = guardCancel(await clackText({
+                message: "CSS 文件绝对路径",
+                initialValue: "",
+            }));
+            ogImageRenderThemePath = (customPath || "").trim() || undefined;
+        }
+    }
     const longMessageThreshold = guardCancel(await clackText({
         message: "长消息阈值（字符数，超过则启用上述模式）",
         initialValue: "300",
@@ -86,6 +107,7 @@ export async function runOneBotSetup() {
         requireMention: true,
         renderMarkdownToPlain,
         longMessageMode,
+        ...(longMessageMode === "og_image" ? { ogImageRenderTheme, ...(ogImageRenderThemePath != null ? { ogImageRenderThemePath } : {}) } : {}),
         longMessageThreshold: Number.isFinite(thresholdNum) ? thresholdNum : 300,
         ...(whitelistIds.length > 0 ? { whitelistUserIds: whitelistIds } : {}),
     };

package/dist/tools.d.ts

@@ -2,16 +2,18 @@
  * Agent 工具注册
  * 供 OpenClaw cron 等场景下，AI 调用 OneBot 能力
  */
-import { sendPrivateMsg, sendGroupMsg, sendGroupImage, sendPrivateImage, getGroupMsgHistory, getGroupInfo, getStrangerInfo, getGroupMemberInfo, getAvatarUrl } from "./connection.js";
+import { sendPrivateMsg, sendGroupMsg, sendGroupImage, sendPrivateImage, getGroupMsgHistory, getGroupMsgHistoryInRange, getGroupInfo, getStrangerInfo, getGroupMemberInfo, searchGroupMemberByName, getAvatarUrl } from "./connection.js";
 export interface OneBotClient {
     sendGroupMsg: typeof sendGroupMsg;
     sendGroupImage: typeof sendGroupImage;
     sendPrivateMsg: typeof sendPrivateMsg;
     sendPrivateImage: typeof sendPrivateImage;
     getGroupMsgHistory: typeof getGroupMsgHistory;
+    getGroupMsgHistoryInRange: typeof getGroupMsgHistoryInRange;
     getGroupInfo: typeof getGroupInfo;
     getStrangerInfo: typeof getStrangerInfo;
     getGroupMemberInfo: typeof getGroupMemberInfo;
+    searchGroupMemberByName: typeof searchGroupMemberByName;
     getAvatarUrl: typeof getAvatarUrl;
 }
 export declare const onebotClient: OneBotClient;

package/dist/tools.js

@@ -4,7 +4,7 @@
  */
 import WebSocket from "ws";
 import { loadScript } from "./load-script.js";
-import { getWs, sendPrivateMsg, sendGroupMsg, sendGroupImage, sendPrivateImage, uploadGroupFile, uploadPrivateFile, getGroupMsgHistory, getGroupInfo, getStrangerInfo, getGroupMemberInfo, getAvatarUrl, } from "./connection.js";
+import { getWs, sendPrivateMsg, sendGroupMsg, sendGroupImage, sendPrivateImage, uploadGroupFile, uploadPrivateFile, getGroupMsgHistory, getGroupMsgHistoryInRange, getGroupInfo, getStrangerInfo, getGroupMemberInfo, searchGroupMemberByName, getAvatarUrl, } from "./connection.js";
 import { getRenderMarkdownToPlain } from "./config.js";
 import { markdownToPlain } from "./markdown.js";
 export const onebotClient = {
@@ -13,9 +13,11 @@ export const onebotClient = {
     sendPrivateMsg,
     sendPrivateImage,
     getGroupMsgHistory,
+    getGroupMsgHistoryInRange,
     getGroupInfo,
     getStrangerInfo,
     getGroupMemberInfo,
+    searchGroupMemberByName,
     getAvatarUrl,
 };
 export function registerTools(api) {
@@ -120,14 +122,16 @@ export function registerTools(api) {
     });
     api.registerTool({
         name: "onebot_get_group_msg_history",
-        description: "获取群聊历史消息（需 Lagrange.Core，go-cqhttp 可能不支持）。用于定时总结、日报等场景",
+        description: "获取群聊历史消息。可指定 hours 获取最近 N 小时内消息（分页拉取），不指定则返回单页（始终从旧到新）。需 Lagrange.Core",
         parameters: {
             type: "object",
             properties: {
                 group_id: { type: "number", description: "群号" },
-                count: { type: "number", description: "获取条数，默认 50" },
-                message_seq: { type: "number", description: "可选，起始消息序号" },
-                message_id: { type: "number", description: "可选，起始消息 ID" },
+                hours: { type: "number", description: "可选。指定则获取从现在到过去 N 小时内的消息（如 24 即过去 24 小时）" },
+                count: { type: "number", description: "单页条数（未指定 hours 时生效），默认 50" },
+                message_seq: { type: "number", description: "可选，起始消息序号（分页用，未指定 hours 时生效）" },
+                message_id: { type: "number", description: "可选，起始消息 ID（未指定 hours 时生效）" },
+                limit: { type: "number", description: "指定 hours 时最多返回条数，默认 3000" },
             },
             required: ["group_id"],
         },
@@ -137,10 +141,26 @@ export function registerTools(api) {
                 return { content: [{ type: "text", text: "OneBot 未连接" }] };
             }
             try {
+                const hoursNum = params.hours != null ? Number(params.hours) : undefined;
+                if (typeof hoursNum === "number" && Number.isFinite(hoursNum) && hoursNum > 0) {
+                    const startTime = Math.floor(Date.now() / 1000) - hoursNum * 3600;
+                    const msgs = await getGroupMsgHistoryInRange(params.group_id, {
+                        startTime,
+                        limit: params.limit ?? 3000,
+                        chunkSize: 100,
+                    });
+                    const summary = 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)}`;
+                    });
+                    return { content: [{ type: "text", text: summary.join("\n") || "无历史消息", metadata: { count: msgs.length } }] };
+                }
                 const msgs = await getGroupMsgHistory(params.group_id, {
                     count: params.count ?? 50,
                     message_seq: params.message_seq,
                     message_id: params.message_id,
+                    reverse_order: true,
                 });
                 const summary = msgs.map((m) => {
                     const text = typeof m.message === "string" ? m.message : JSON.stringify(m.message);
@@ -154,6 +174,35 @@ export function registerTools(api) {
             }
         },
     });
+    api.registerTool({
+        name: "onebot_search_group_member",
+        description: "按名字模糊匹配群成员，返回匹配到的 QQ 号与展示名（群名片优先）。用于根据昵称/群名片查 QQ 号",
+        parameters: {
+            type: "object",
+            properties: {
+                group_id: { type: "number", description: "群号" },
+                name: { type: "string", description: "要搜索的名字（群名片或昵称，支持模糊匹配）" },
+            },
+            required: ["group_id", "name"],
+        },
+        async execute(_id, params) {
+            const w = getWs();
+            if (!w || w.readyState !== WebSocket.OPEN) {
+                return { content: [{ type: "text", text: "OneBot 未连接" }] };
+            }
+            try {
+                const list = await searchGroupMemberByName(params.group_id, params.name);
+                if (!list.length) {
+                    return { content: [{ type: "text", text: `未找到匹配「${params.name}」的群成员` }] };
+                }
+                const lines = list.map((m) => `QQ: ${m.user_id}  展示名: ${m.displayName}`);
+                return { content: [{ type: "text", text: lines.join("\n"), metadata: { count: list.length, matches: list } }] };
+            }
+            catch (e) {
+                return { content: [{ type: "text", text: `搜索失败: ${e?.message}` }] };
+            }
+        },
+    });
     api.registerTool({
         name: "onebot_run_script",
         description: "执行用户配置的 JS/TS 脚本（.mjs/.ts/.mts），脚本可调用 OneBot API（获取群历史、发图等）。用于定时任务中实现自定义逻辑（如 OG 图片生成、日报汇总）",

package/openclaw.plugin.json

@@ -1,10 +1,11 @@
 {
   "id": "openclaw-onebot",
   "name": "OneBot Channel",
-  "version": "1.0.1",
+  "version": "1.0.5",
   "description": "OneBot v11 protocol channel (QQ/Lagrange.Core via WebSocket)",
   "author": "Lagrange.Onebot",
   "channels": ["onebot"],
+  "commands": ["onebot"],
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
@@ -33,6 +34,16 @@
         "default": true,
         "description": "是否将机器人回复中的 Markdown 渲染为纯文本再发送（去除 **、# 等标记）"
       },
+      "normalModeFlushIntervalMs": {
+        "type": "number",
+        "default": 1200,
+        "description": "normal 模式下聚合发送的等待窗口（毫秒）。块流式开启后，插件会在该时间窗口内合并回复再发送。"
+      },
+      "normalModeFlushChars": {
+        "type": "number",
+        "default": 160,
+        "description": "normal 模式下聚合发送的字符阈值。达到该长度会提前 flush，而不是继续等待时间窗口结束。"
+      },
       "groupIncrease": {
         "type": "object",
         "properties": {
@@ -71,6 +82,16 @@
         "default": 300,
         "description": "长消息阈值（字符数），超过则启用 longMessageMode"
       },
+      "ogImageRenderTheme": {
+        "type": "string",
+        "enum": ["default", "dust", "custom"],
+        "default": "default",
+        "description": "长消息 og_image 时的渲染主题：default 无额外样式，dust 内置 dust 样式，custom 时需填写 ogImageRenderThemePath"
+      },
+      "ogImageRenderThemePath": {
+        "type": "string",
+        "description": "当 ogImageRenderTheme 为 custom 时，填写 CSS 文件绝对路径"
+      },
       "cronJobs": {
         "type": "array",
         "description": "内置定时任务（无 AI 介入，直接执行脚本并推送到群聊）",
@@ -97,6 +118,10 @@
     "host": { "label": "主机地址", "placeholder": "127.0.0.1" },
     "port": { "label": "端口", "placeholder": "8080" },
     "requireMention": { "label": "群聊需 @ 回复" },
-    "renderMarkdownToPlain": { "label": "Markdown 转纯文本" }
+    "renderMarkdownToPlain": { "label": "Markdown 转纯文本" },
+    "normalModeFlushIntervalMs": { "label": "normal 聚合窗口(ms)" },
+    "normalModeFlushChars": { "label": "normal 提前发送阈值" },
+    "ogImageRenderTheme": { "label": "OG 图片渲染主题（default/dust/custom）" },
+    "ogImageRenderThemePath": { "label": "自定义 CSS 路径（仅当主题为 custom 时）" }
   }
 }

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "@kirigaya/openclaw-onebot",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "OneBot v11 protocol channel plugin for OpenClaw (QQ/Lagrange.Core/go-cqhttp)",
   "license": "MIT",
-  "publishConfig": { "access": "public" },
+  "publishConfig": {
+    "access": "public"
+  },
   "author": "LSTM-Kirigaya",
   "repository": {
     "type": "git",
@@ -26,13 +28,19 @@
   "exports": "./dist/index.js",
   "files": [
     "dist",
+    "themes",
     "skills",
     "openclaw.plugin.json",
     "README.md"
   ],
   "openclaw": {
-    "extensions": ["./dist/index.js"],
-    "skills": ["skills/onebot-ops", "skills/onebot-scripts"],
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "skills": [
+      "skills/onebot-ops",
+      "skills/onebot-scripts"
+    ],
     "channel": {
       "id": "onebot",
       "label": "OneBot",
@@ -40,40 +48,50 @@
       "docsPath": "/channels/onebot",
       "blurb": "OneBot v11 protocol via WebSocket (go-cqhttp, Lagrange.Core, etc.)",
       "order": 85,
-      "aliases": ["qq", "lagrange", "cqhttp"]
+      "aliases": [
+        "qq",
+        "lagrange",
+        "cqhttp"
+      ]
     }
   },
   "scripts": {
+    "openclaw": "openclaw",
     "build": "tsc",
     "test:connect": "npx tsx scripts/test-connect.ts",
     "test:group-welcome": "npx tsx scripts/test-group-welcome.ts",
     "test:group-increase-handler": "npx tsx scripts/test-group-increase-handler.ts",
+    "test:render-og-image": "npx tsx test/render-og-image.ts",
     "prepublishOnly": "npm run build",
     "pub": "npm run build && npm publish"
   },
   "dependencies": {
-    "ws": "^8.17.0",
     "@clack/prompts": "^1.0.0",
-    "tsx": "^4.0.0",
     "cron": "^4.4.0",
+    "fuse.js": "^7.1.0",
+    "highlight.js": "^11.10.0",
     "marked": "^15.0.0",
-    "highlight.js": "^11.10.0"
+    "tsx": "^4.0.0",
+    "ws": "^8.17.0"
   },
   "optionalDependencies": {
     "node-html-to-image": "^3.0.0"
   },
   "peerDependencies": {
-    "openclaw": "*",
     "clawdbot": "*"
   },
   "peerDependenciesMeta": {
-    "clawdbot": { "optional": true },
-    "openclaw": { "optional": true }
+    "clawdbot": {
+      "optional": true
+    },
+    "openclaw": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "typescript": "^5.4.0",
     "@types/node": "^22.0.0",
-    "@types/ws": "^8.5.10"
+    "@types/ws": "^8.5.10",
+    "typescript": "^5.4.0"
   },
   "engines": {
     "node": ">=22"

package/skills/onebot-ops/SKILL.md

@@ -46,16 +46,27 @@ openclaw plugins install ./openclaw-onebot
 | **图片消息** | message 为 `[{ type: "image", data: { file } }]` |
 | **delete_msg** | 撤回消息 |
 | **get_msg** | 获取单条消息 |
-| **get_group_msg_history** | 获取群历史（Lagrange.Core 扩展） |
+| **get_group_msg_history** | 获取群历史（Lagrange.Core 扩展），支持 reverse_order 分页 |
 | **upload_group_file** | 上传群文件 |
 | **upload_private_file** | 上传私聊文件 |
 | **set_msg_emoji_like** | 表情回应（Lagrange/QQ NT 扩展） |
 
-## 常用命令
+## Agent 工具与 CLI
+
+插件提供群历史、按名字搜 QQ 等能力，既注册为 **Agent 工具**（供 Cron/脚本/AI 调用），也提供等价的 **CLI 命令**，便于 AI 与人工按文档调用。
+
+**详细说明与所有命令用法见：[agent-tools.md](agent-tools.md)**
+
+### 常用 CLI 一览
 
 | 命令 | 说明 |
 |------|------|
 | `openclaw onebot setup` | 交互式配置 OneBot 连接 |
-| `openclaw message send --channel onebot --target group:xxx --message "hi"` | 发送群消息 |
+| `openclaw onebot get-group-msg-history --group-id <群号> [--hours N]` | 获取群历史（单页或最近 N 小时内，从旧到新） |
+| `openclaw onebot search-group-member --group-id <群号> --name <名字>` | 按名字模糊搜群友 QQ 号 |
+| `openclaw onebot upload-file --target group:<群号> --file <路径> --name <文件名>` | 上传文件到群/私聊 |
+| `openclaw message send --channel onebot --target group:xxx --message "hi"` | 发送文本/图片 |
 | `openclaw gateway status` | 查看 Gateway 状态 |
 | `openclaw logs --follow` | 查看日志 |
+
+AI 或脚本需要「获取群历史、查群友 QQ」时，应使用上述 CLI 或查阅 [agent-tools.md](agent-tools.md) 中的完整参数说明。

package/skills/onebot-ops/agent-tools.md

@@ -0,0 +1,116 @@
+# OneBot Agent 工具与 CLI
+
+插件通过 WebSocket 与 OneBot（Lagrange.Core / go-cqhttp）通信，提供 **Agent 工具**（供 Cron/脚本/AI 调用）和等价的 **CLI 命令**（供人工或工作流直接调用）。  
+AI 或脚本应优先使用 **CLI**，便于复现、调试和文档化。
+
+---
+
+## 前置条件
+
+- **Gateway 已启动**：`openclaw gateway`（或 `openclaw gateway run`）
+- OneBot 已运行并连接；若为正向 WS，CLI 会按配置自动建连
+- 配置：`openclaw.json` 的 `channels.onebot` 或环境变量 `ONEBOT_WS_*`
+
+---
+
+## 1. 获取群历史消息
+
+**Agent 工具**：`onebot_get_group_msg_history`  
+**CLI**：
+
+```bash
+openclaw onebot get-group-msg-history --group-id <群号> [--hours <N>] [--count 50] [--message-seq <序号>]
+```
+
+- 指定 **`--hours N`**：获取**从现在到过去 N 小时**内的消息（内部按时间范围分页拉取），例如 `--hours 24` 即过去 24 小时。
+- 不指定 `--hours`：按单页返回，始终**从旧到新**；分页时用上一批最早一条的 `message_seq` 作为 `--message-seq`。
+
+| 参数 | 说明 |
+|------|------|
+| `--group-id` | 群号（必填） |
+| `--hours` | 获取最近 N 小时内的消息（可选；指定后按时间范围拉取） |
+| `--count` | 条数，默认 50（未指定 --hours 时生效） |
+| `--message-seq` | 起始消息序号（可选，分页用，未指定 --hours 时生效） |
+
+示例：
+
+```bash
+openclaw onebot get-group-msg-history --group-id 123456789
+openclaw onebot get-group-msg-history --group-id 123456789 --hours 24
+openclaw onebot get-group-msg-history --group-id 123456789 --hours 1 --limit 500
+```
+
+---
+
+## 2. 按名字模糊搜索群成员（查 QQ 号）
+
+**Agent 工具**：`onebot_search_group_member`  
+**CLI**：
+
+```bash
+openclaw onebot search-group-member --group-id <群号> --name <名字>
+```
+
+| 参数 | 说明 |
+|------|------|
+| `--group-id` | 群号（必填） |
+| `--name` | 要搜的名字（群名片或昵称，模糊匹配） |
+
+输出：匹配到的 QQ 与展示名。
+
+示例：
+
+```bash
+openclaw onebot search-group-member --group-id 123456789 --name 小明
+```
+
+---
+
+## 3. 发送文本
+
+**Agent 工具**：`onebot_send_text`  
+**CLI**（推荐使用主命令）：
+
+```bash
+openclaw message send --channel onebot --target group:<群号> --message "内容"
+openclaw message send --channel onebot --target user:<QQ号> --message "内容"
+```
+
+---
+
+## 4. 发送图片
+
+**Agent 工具**：`onebot_send_image`  
+**CLI**：
+
+```bash
+openclaw message send --channel onebot --target group:<群号> --media "file:///path/to.png"
+openclaw message send --channel onebot --target user:<QQ号> --media "https://example.com/pic.jpg"
+```
+
+---
+
+## 5. 上传文件到群/私聊
+
+**Agent 工具**：`onebot_upload_file`  
+**CLI**：
+
+```bash
+openclaw onebot upload-file --target group:<群号> --file <本地绝对路径> --name <显示文件名>
+openclaw onebot upload-file --target user:<QQ号> --file <本地绝对路径> --name <显示文件名>
+```
+
+---
+
+## 6. 执行脚本（Cron 等）
+
+**Agent 工具**：`onebot_run_script`  
+**CLI**：无直接一对一命令，可由 Cron 或工作流调用脚本，脚本内使用上述 CLI 或 `onebotClient` API。
+
+---
+
+## 使用建议
+
+- **AI / 自动化**：优先使用上述 **CLI 命令**，便于在 Skill 中写明「如何调用」、可复现。
+- **Cron / 内置任务**：在 `openclaw.json` 的 `cronJobs` 中配置 `script`，脚本内通过 `onebotClient` 或子进程调用 CLI。
+- **临时查询**：直接运行 `openclaw onebot search-group-member ...` 等。