lightclawbot 1.1.2 → 1.2.0-beta.1

package/README.md

@@ -69,7 +69,6 @@ src/
 ├── download-tool.ts    # AI 工具：下载/获取文件 URL
 ├── dedup.ts            # 消息去重与防抖
 ├── media.ts            # 媒体工具函数
-├── format-urls.ts      # 文件 URL 自动转 Markdown 链接
 ├── types.ts            # 类型定义
 └── history/            # 历史消息读取
 ```

package/dist/index.js

@@ -1,34 +1,41 @@
-import { emptyPluginConfigSchema } from "openclaw/plugin-sdk/core";
-import { myAssistantPlugin } from "./src/channel.js";
-import { setAssistantRuntime } from "./src/runtime.js";
-import { registerUploadTool } from "./src/upload-tool.js";
-// import { registerDownloadTool } from "./src/download-tool.js";
-const plugin = {
+/**
+ * LightClaw — 主入口文件
+ *
+ * 使用 OpenClaw SDK 标准的 defineChannelPluginEntry 工厂函数替代手动创建 plugin 对象，
+ * 遵循 Discord/Slack 等官方 channel 插件的标准 index.ts 模式。
+ *
+ * 该文件定义了 LightClawBot channel plugin 的入口配置，包括插件ID、名称、描述、
+ * 核心插件实现、运行时设置和工具注册等功能。
+ */
+// 导入 OpenClaw SDK 的核心功能
+import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
+// 导入本地模块
+import { lightclawPlugin } from "./src/channel.js"; // 核心插件实现
+import { setLightclawRuntime } from "./src/runtime.js"; // 运行时配置设置函数
+import { registerLightclawTools } from "./src/tools.js"; // 工具注册函数
+// 导出运行时设置函数，供外部使用
+export { setLightclawRuntime } from "./src/runtime.js";
+/**
+ * 创建并配置 LightClawBot channel plugin 入口
+ *
+ * 使用 defineChannelPluginEntry 工厂函数创建插件配置对象，
+ * 该函数返回一个类型安全的插件入口配置。
+ *
+ * @type {ReturnType<typeof defineChannelPluginEntry<ChannelPlugin>>}
+ */
+const entry = defineChannelPluginEntry({
+    // 插件唯一标识符，用于在系统中识别该插件
     id: "lightclawbot",
+    // 插件显示名称，在UI中展示给用户
     name: "LightClawBot",
+    // 插件功能描述，说明插件的主要用途
     description: "Channel plugin for LightClawBot",
-    configSchema: emptyPluginConfigSchema(),
-    register(api) {
-        setAssistantRuntime(api.runtime);
-        api.registerChannel({ plugin: myAssistantPlugin });
-        // 注册文件存储工具（飞书工厂函数模式：execute 时动态从 api.config 解析 apiKey）
-        registerUploadTool(api);
-        // registerDownloadTool(api);
-    },
-};
-export default plugin;
-export { myAssistantPlugin } from "./src/channel.js";
-export { setAssistantRuntime, getAssistantRuntime } from "./src/runtime.js";
-export * from "./src/types.js";
-export * from "./src/config.js";
-export * from "./src/gateway.js";
-export * from "./src/dedup.js";
-export * from "./src/media.js";
-export * from "./src/inbound.js";
-export * from "./src/socket/index.js";
-export * from "./src/outbound.js";
-export * from "./src/history/index.js";
-export * from "./src/file-storage.js";
-export * from "./src/upload-tool.js";
-export * from "./src/download-tool.js";
-//# sourceMappingURL=index.js.map
+    // 核心插件实现，包含消息处理、事件响应等核心逻辑
+    plugin: lightclawPlugin,
+    // 运行时设置函数，用于配置插件运行时的环境和参数
+    setRuntime: setLightclawRuntime,
+    // 完整工具注册函数，用于向系统注册插件提供的所有工具和能力
+    registerFull: registerLightclawTools,
+});
+// 导出默认入口配置，供 OpenClaw SDK 加载和使用
+export default entry;

package/dist/setup-entry.js

@@ -0,0 +1,32 @@
+/**
+ * LightClaw — Setup 入口文件
+ *
+ * 使用 OpenClaw SDK 提供的 defineSetupPluginEntry 工厂函数导出轻量级的 setup 插件配置。
+ *
+ * 该入口文件的主要作用是：
+ * - 当插件未配置或未启用时，OpenClaw 系统只会加载此轻量级入口
+ * - 避免拉起 ws 等运行时重依赖，减少系统启动开销
+ * - 提供插件的基本信息和配置能力，但不包含完整的运行时逻辑
+ *
+ * 这种设计模式有助于：
+ * - 降低系统启动时的内存占用
+ * - 提高插件加载性能
+ * - 支持按需加载插件功能
+ */
+// 导入 OpenClaw SDK 的 setup 插件入口定义函数
+import { defineSetupPluginEntry } from "openclaw/plugin-sdk/core";
+// 导入本地的 setup 插件实现
+import { lightclawSetupPlugin } from "./src/channel.setup.js";
+// 导出 setup 插件实现，供外部模块使用或测试
+export { lightclawSetupPlugin } from "./src/channel.setup.js";
+/**
+ * 默认导出 setup 插件入口配置
+ *
+ * 使用 defineSetupPluginEntry 工厂函数创建并配置 setup 插件：
+ * - 包装 lightclawSetupPlugin 实例
+ * - 提供标准的插件入口接口
+ * - 确保插件符合 OpenClaw SDK 的规范要求
+ *
+ * @returns {ReturnType<typeof defineSetupPluginEntry>} 配置完成的 setup 插件入口
+ */
+export default defineSetupPluginEntry(lightclawSetupPlugin);

package/dist/src/channel.js

@@ -1,272 +1,185 @@
 /**
  * LightClaw — ChannelPlugin 主定义
  *
- * 这是 OpenClaw 框架的「注册契约」：
- * 声明插件 ID、能力、配置管理、出站适配、Gateway 生命周期等。
- * 框架通过这个对象了解你的插件能做什么、怎么启动、怎么发消息。
+ * 使用 SDK 标准的 createChatChannelPlugin 构建器，
+ * 参照官方 Discord/Slack channel 实现。
+ *
+ * 结构：
+ *   base:     来自 shared.ts 的 createLightclawPluginBase + 扩展字段
+ *   security: DM 安全策略
+ *   outbound: 出站消息适配器
  */
-import { applyAccountNameToChannelSection, deleteAccountFromConfigSection, setAccountEnabledInConfigSection, } from "openclaw/plugin-sdk/core";
-import { CHANNEL_KEY, DEFAULT_ACCOUNT_ID, TEXT_CHUNK_LIMIT, listAccountIds, resolveAccount, defaultAccountId, applyAccountConfig, } from "./config.js";
-import { sendText, sendMedia } from "./outbound.js";
-import { startGateway } from "./gateway.js";
-/** 文本分块：按 limit 长度拆分，优先在换行 / 空格处切割 */
-function chunkText(text, limit) {
-    if (text.length <= limit)
-        return [text];
-    const chunks = [];
-    let remaining = text;
-    while (remaining.length > 0) {
-        if (remaining.length <= limit) {
-            chunks.push(remaining);
-            break;
-        }
-        let splitAt = remaining.lastIndexOf("\n", limit);
-        if (splitAt <= 0 || splitAt < limit * 0.5) {
-            splitAt = remaining.lastIndexOf(" ", limit);
-        }
-        if (splitAt <= 0 || splitAt < limit * 0.5) {
-            splitAt = limit;
-        }
-        chunks.push(remaining.slice(0, splitAt));
-        remaining = remaining.slice(splitAt).trimStart();
-    }
-    return chunks;
-}
+import { createChatChannelPlugin } from 'openclaw/plugin-sdk/core';
+import { chunkText, defaultAccountId } from './utils/index.js';
+import { CHANNEL_KEY, DEFAULT_ACCOUNT_ID, TEXT_CHUNK_LIMIT } from './config.js';
+import { sendText, sendMedia } from './outbound.js';
+import { startGateway } from './gateway.js';
+import { createLightclawPluginBase } from './shared.js';
+import { lightclawSetupAdapter } from './setup-core.js';
+import { normalizeTarget, looksLikeId } from './messaging.js';
 // ============================================================
-// ChannelPlugin 定义
+// ChannelPlugin 定义（使用 createChatChannelPlugin）
 // ============================================================
-export const myAssistantPlugin = {
-    id: CHANNEL_KEY,
-    // ---- 元信息 ----
-    meta: {
-        id: CHANNEL_KEY,
-        label: "LightClawBot",
-        selectionLabel: "LightClawBot",
-        docsPath: "/docs/channels/lightclawbot",
-        blurb: "Connect OpenClaw to your LightClawBot via WebSocket long-connection",
-        order: 60,
-    },
-    // ---- 能力声明 ----
-    capabilities: {
-        chatTypes: ["direct"],
-        media: true,
-        reactions: false,
-        threads: false,
-        // true = deliver 回调会收到 kind="block" 的中间块，实现流式推送
-        blockStreaming: true,
-    },
-    // ---- 配置管理（多账户） ----
-    config: {
-        listAccountIds: (cfg) => listAccountIds(cfg),
-        resolveAccount: (cfg, accountId) => resolveAccount(cfg, accountId),
-        defaultAccountId: (cfg) => defaultAccountId(cfg),
-        setAccountEnabled: ({ cfg, accountId, enabled }) => setAccountEnabledInConfigSection({
-            cfg,
-            sectionKey: CHANNEL_KEY,
-            accountId,
-            enabled,
-            allowTopLevel: true,
-        }),
-        deleteAccount: ({ cfg, accountId }) => deleteAccountFromConfigSection({
-            cfg,
-            sectionKey: CHANNEL_KEY,
-            accountId,
-            clearBaseFields: ["apiKeys", "apiBaseUrl", "name"],
+export const lightclawPlugin = createChatChannelPlugin({
+    base: {
+        // ---- 来自 shared.ts 的基础定义 ----
+        ...createLightclawPluginBase({
+            setup: lightclawSetupAdapter,
         }),
-        isConfigured: (account) => Boolean(account?.allApiKeys?.length),
-        describeAccount: (account) => ({
-            accountId: account?.accountId ?? DEFAULT_ACCOUNT_ID,
-            name: account?.name,
-            enabled: account?.enabled ?? false,
-            configured: Boolean(account?.allApiKeys?.length),
-            tokenSource: account?.secretSource,
-        }),
-        resolveAllowFrom: ({ cfg, accountId }) => {
-            const account = resolveAccount(cfg, accountId);
-            return account.allowFrom.map(String);
-        },
-    },
-    // ---- Setup（命令行配置） ----
-    setup: {
-        resolveAccountId: ({ accountId }) => accountId?.trim().toLowerCase() || DEFAULT_ACCOUNT_ID,
-        applyAccountName: ({ cfg, accountId, name }) => applyAccountNameToChannelSection({ cfg, channelKey: CHANNEL_KEY, accountId, name }),
-        validateInput: ({ input }) => {
-            if (!input.token && !input.useEnv) {
-                return "Requires --token <apiKey> or --use-env (set LIGHTCLAW_API_KEY, LIGHTCLAW_API_BASE_URL)";
-            }
-            return null;
-        },
-        applyAccountConfig: ({ cfg, accountId, input }) => {
-            return applyAccountConfig(cfg, accountId, {
-                apiKey: input.token,
-                apiBaseUrl: input.apiBaseUrl,
-                name: input.name,
-            });
+        // ---- 消息目标解析 ----
+        messaging: {
+            // 对原始目标字符串进行标准化处理，如去除空格、统一格式、转换编码等，返回标准化后的字符串
+            normalizeTarget: (target) => {
+                return normalizeTarget(target);
+            },
+            targetResolver: {
+                // 判断一个原始字符串是否看起来像一个 ID，用于在解析前快速分流处理逻辑
+                looksLikeId: (id, normalized) => {
+                    return looksLikeId(id, normalized);
+                },
+                /** 目标格式提示文本，显示在 CLI 帮助信息中 */
+                hint: `user:<userId> or channel:<groupId>`,
+            },
         },
-    },
-    // ---- 消息目标解析 ----
-    // 使用标准 user:/channel: 前缀，确保框架的 detectTargetKind 能正确识别 peer kind
-    messaging: {
-        normalizeTarget: (target) => {
-            // 剥离通道名前缀 (lightclawbot:)
-            const cleaned = target.replace(new RegExp(`^${CHANNEL_KEY}:`, "i"), "");
-            if (!cleaned)
-                return undefined;
-            // dm:xxx → user:xxx (私聊)
-            if (cleaned.startsWith("dm:")) {
-                return `user:${cleaned.slice(3)}`;
-            }
-            // group:xxx → channel:xxx (群聊)
-            if (cleaned.startsWith("group:")) {
-                return `channel:${cleaned.slice(6)}`;
-            }
-            // 已经是标准格式 user:/channel:，原样返回
-            if (/^(user|channel):/i.test(cleaned)) {
-                return cleaned;
-            }
-            // 纯 ID，默认当作私聊
-            return `user:${cleaned}`;
+        // ---- 状态面板 ----
+        status: {
+            defaultRuntime: {
+                accountId: DEFAULT_ACCOUNT_ID,
+                running: false,
+                connected: false,
+                lastConnectedAt: null,
+                lastError: null,
+            },
+            buildChannelSummary: ({ snapshot }) => ({
+                configured: snapshot.configured ?? false,
+                running: snapshot.running ?? false,
+                connected: snapshot.connected ?? false,
+                lastConnectedAt: snapshot.lastConnectedAt ?? null,
+                lastError: snapshot.lastError ?? null,
+            }),
+            buildAccountSnapshot: ({ account, runtime, cfg }) => ({
+                accountId: account?.accountId ?? defaultAccountId(cfg),
+                name: account?.name,
+                enabled: account?.enabled ?? false,
+                configured: Boolean(account?.apiKey),
+                running: runtime?.running ?? false,
+                connected: runtime?.connected ?? false,
+                lastConnectedAt: runtime?.lastConnectedAt ?? null,
+                lastError: runtime?.lastError ?? null,
+            }),
         },
-        targetResolver: {
-            looksLikeId: (id, normalized) => {
-                const value = (normalized ?? id).trim();
-                if (!value)
-                    return false;
-                // 标准前缀格式
-                if (/^(user|channel):/i.test(value))
-                    return true;
-                // lightclawbot 自有格式
-                const cleaned = value.replace(new RegExp(`^${CHANNEL_KEY}:`, "i"), "");
-                return /^(dm|group):\d+/.test(cleaned) || /^\d+$/.test(cleaned);
+        // ---- Gateway 生命周期（核心！） ----
+        gateway: {
+            /**
+             * 启动账户：建立 WS 长连接到 AI 助手 Server
+             * OpenClaw 会在加载配置后为每个 enabled 的账户调用此方法
+             */
+            startAccount: async (ctx) => {
+                const { account, abortSignal, log, cfg } = ctx;
+                log?.info(`[${CHANNEL_KEY}:${account.accountId}] Starting gateway...`);
+                // 启动并维持一个 Socket.IO Gateway 实例
+                await startGateway({
+                    account,
+                    abortSignal,
+                    cfg,
+                    log,
+                    /** WS 连接就绪回调 */
+                    onReady: () => {
+                        log?.info(`[${CHANNEL_KEY}:${account.accountId}] Gateway ready: WS connected`);
+                        const now = Date.now();
+                        ctx.setStatus({
+                            ...ctx.getStatus(),
+                            running: true,
+                            connected: true,
+                            lastConnectedAt: now,
+                            // 连接建立时即设置 lastEventAt，作为 health-monitor stale-socket 检测的初始基准
+                            lastEventAt: now,
+                        });
+                    },
+                    /** WS 连接断开回调 */
+                    onDisconnect: () => {
+                        log?.info(`[${CHANNEL_KEY}:${account.accountId}] Gateway ready: WS disconnect`);
+                        ctx.setStatus({
+                            ...ctx.getStatus(),
+                            connected: false,
+                        });
+                    },
+                    /** 错误回调：记录错误信息，不中断重连逻辑（由 gateway 内部处理） */
+                    onError: (error) => {
+                        log?.error(`[${CHANNEL_KEY}:${account.accountId}] Gateway error: ${error.message}`);
+                        ctx.setStatus({
+                            ...ctx.getStatus(),
+                            lastError: error.message,
+                        });
+                    },
+                    /**
+                     * 入站事件回调：每次收到消息时调用。
+                     * 刷新 lastEventAt 和 lastInboundAt，
+                     * 通知框架 health-monitor 该连接仍处于活跃状态。
+                     */
+                    onEvent: () => {
+                        log?.info(`[${CHANNEL_KEY}:${account.accountId}] Gateway Ready: WS message enter`);
+                        ctx.setStatus({
+                            ...ctx.getStatus(),
+                            lastEventAt: Date.now(),
+                            lastInboundAt: Date.now(),
+                        });
+                    },
+                });
+            },
+            /** 登出账户：清除凭证 */
+            logoutAccount: async ({ accountId, cfg }) => {
+                const nextCfg = { ...cfg };
+                const section = nextCfg.channels?.[CHANNEL_KEY];
+                let cleared = false;
+                if (section) {
+                    if (accountId === DEFAULT_ACCOUNT_ID && section.apiKeys) {
+                        delete section.apiKeys;
+                        cleared = true;
+                    }
+                    const accounts = section.accounts;
+                    if (accounts?.[accountId]?.apiKeys) {
+                        delete accounts[accountId].apiKeys;
+                        cleared = true;
+                    }
+                }
+                return { ok: true, cleared };
             },
-            hint: `user:<userId> or channel:<groupId>`,
         },
     },
     // ---- 出站消息适配器 ----
     outbound: {
-        deliveryMode: "direct",
-        chunker: chunkText,
-        chunkerMode: "markdown",
-        textChunkLimit: TEXT_CHUNK_LIMIT,
-        resolveTarget: ({ to, allowFrom, mode }) => {
-            // 优先使用显式 to；implicit 模式下回退到 allowFrom 第一个非通配符条目
-            const effectiveTo = to?.trim();
-            if (effectiveTo) {
-                return { ok: true, to: effectiveTo };
-            }
-            if (mode === "implicit" && allowFrom && allowFrom.length > 0) {
-                const candidate = allowFrom.find((entry) => entry && entry !== "*");
-                if (candidate) {
-                    return { ok: true, to: candidate };
+        base: {
+            deliveryMode: 'direct',
+            chunker: chunkText,
+            chunkerMode: 'markdown',
+            textChunkLimit: TEXT_CHUNK_LIMIT,
+            resolveTarget: ({ to, allowFrom, mode }) => {
+                // 优先使用显式 to；implicit 模式下回退到 allowFrom 第一个非通配符条目
+                const effectiveTo = to?.trim();
+                if (effectiveTo) {
+                    return { ok: true, to: effectiveTo };
                 }
-            }
-            return {
-                ok: false,
-                error: new Error(`No delivery target for ${CHANNEL_KEY}. Specify a target with --to or configure allowFrom.`),
-            };
-        },
-        sendText: async ({ to, text, accountId, replyToId, cfg }) => {
-            return sendText({ to, text, accountId, replyToId, cfg });
-        },
-        sendMedia: async ({ to, text, mediaUrl, accountId, replyToId, cfg }) => {
-            return sendMedia({ to, text, mediaUrl, accountId, replyToId, cfg });
-        },
-    },
-    // ---- Gateway 生命周期（核心！） ----
-    gateway: {
-        /**
-         * 启动账户：建立 WS 长连接到你的 AI 助手 Server
-         * OpenClaw 会在加载配置后为每个 enabled 的账户调用此方法
-         */
-        startAccount: async (ctx) => {
-            const { account, abortSignal, log, cfg } = ctx;
-            log?.info(`[${CHANNEL_KEY}:${account.accountId}] Starting gateway...`);
-            await startGateway({
-                account,
-                abortSignal,
-                cfg,
-                log,
-                onReady: () => {
-                    log?.info(`[${CHANNEL_KEY}:${account.accountId}] Gateway ready, WS connected`);
-                    const now = Date.now();
-                    ctx.setStatus({
-                        ...ctx.getStatus(),
-                        running: true,
-                        connected: true,
-                        lastConnectedAt: now,
-                        // 连接建立时即设置 lastEventAt，作为 health-monitor stale-socket 检测的初始基准
-                        lastEventAt: now,
-                    });
-                },
-                onDisconnect: () => {
-                    ctx.setStatus({
-                        ...ctx.getStatus(),
-                        connected: false,
-                    });
-                },
-                onError: (error) => {
-                    log?.error(`[${CHANNEL_KEY}:${account.accountId}] Gateway error: ${error.message}`);
-                    ctx.setStatus({
-                        ...ctx.getStatus(),
-                        lastError: error.message,
-                    });
-                },
-                onEvent: () => {
-                    // 通知框架收到了入站事件，防止 health-monitor 因 lastEventAt 过期而误判 stale-socket
-                    ctx.setStatus({
-                        ...ctx.getStatus(),
-                        lastEventAt: Date.now(),
-                        lastInboundAt: Date.now(),
-                    });
-                },
-            });
-        },
-        /** 登出账户：清除凭证 */
-        logoutAccount: async ({ accountId, cfg }) => {
-            const nextCfg = { ...cfg };
-            const section = nextCfg.channels?.[CHANNEL_KEY];
-            let cleared = false;
-            if (section) {
-                if (accountId === DEFAULT_ACCOUNT_ID && section.apiKeys) {
-                    delete section.apiKeys;
-                    cleared = true;
+                if (mode === 'implicit' && allowFrom && allowFrom.length > 0) {
+                    const candidate = allowFrom.find((entry) => entry && entry !== '*');
+                    if (candidate) {
+                        return { ok: true, to: candidate };
+                    }
                 }
-                const accounts = section.accounts;
-                if (accounts?.[accountId]?.apiKeys) {
-                    delete accounts[accountId].apiKeys;
-                    cleared = true;
-                }
-            }
-            return { ok: true, cleared };
+                return {
+                    ok: false,
+                    error: new Error(`No delivery target for ${CHANNEL_KEY}. Specify a target with --to or configure allowFrom.`),
+                };
+            },
         },
-    },
-    // ---- 状态面板 ----
-    status: {
-        defaultRuntime: {
-            accountId: DEFAULT_ACCOUNT_ID,
-            running: false,
-            connected: false,
-            lastConnectedAt: null,
-            lastError: null,
+        attachedResults: {
+            channel: CHANNEL_KEY,
+            sendText: async ({ to, text, accountId, replyToId, cfg }) => {
+                return sendText({ to, text, accountId, replyToId, cfg });
+            },
+            sendMedia: async ({ to, text, mediaUrl, accountId, replyToId, cfg }) => {
+                return sendMedia({ to, text, mediaUrl, accountId, replyToId, cfg });
+            },
         },
-        buildChannelSummary: ({ snapshot }) => ({
-            configured: snapshot.configured ?? false,
-            running: snapshot.running ?? false,
-            connected: snapshot.connected ?? false,
-            lastConnectedAt: snapshot.lastConnectedAt ?? null,
-            lastError: snapshot.lastError ?? null,
-        }),
-        buildAccountSnapshot: ({ account, runtime, }) => ({
-            accountId: account?.accountId ?? DEFAULT_ACCOUNT_ID,
-            name: account?.name,
-            enabled: account?.enabled ?? false,
-            configured: Boolean(account?.allApiKeys?.length),
-            tokenSource: account?.secretSource,
-            running: runtime?.running ?? false,
-            connected: runtime?.connected ?? false,
-            lastConnectedAt: runtime?.lastConnectedAt ?? null,
-            lastError: runtime?.lastError ?? null,
-        }),
     },
-};
-//# sourceMappingURL=channel.js.map
+});

package/dist/src/channel.setup.js

@@ -0,0 +1,16 @@
+/**
+ * LightClaw — Setup-only 轻量插件
+ *
+ * 参照 Discord 的 channel.setup.ts 模式：
+ * 仅包含 shared base 骨架（id, meta, config, setup），
+ * 不加载 gateway / inbound / outbound 等运行时重依赖。
+ *
+ * 用于插件未配置/未启用时的 setup 流程，避免拉起不必要的运行时。
+ */
+import { createLightclawPluginBase } from "./shared.js";
+import { lightclawSetupAdapter } from "./setup-core.js";
+export const lightclawSetupPlugin = {
+    ...createLightclawPluginBase({
+        setup: lightclawSetupAdapter,
+    }),
+};