lightclawbot 1.1.2 → 1.2.0-beta.1

package/dist/src/outbound.js

@@ -4,20 +4,39 @@
  * 处理 OpenClaw 框架层的主动消息发送（非 deliver 回调场景）。
  * 例如：用户通过 /message 命令发消息、cron 定时任务触发等。
  *
- * 发送策略：
+ * 发送策略（双通道 + 自动降级）：
  *   1. 优先通过 gateway 的 WS 长连接发送（socket-registry）
+ *      - 连接正常 → 走可靠发送（emitWithAck + 自动重试）
+ *      - 连接断开但 entry 存在（重连中）→ 缓冲消息，重连后自动 flush
  *   2. WS 不可用时 fallback 到 REST API（需配置 apiBaseUrl）
  */
-import { resolveAccount, CHANNEL_KEY, DEFAULT_ACCOUNT_ID, EVENT_MESSAGE_PRIVATE } from "./config.js";
-import { getAssistantRuntime } from "./runtime.js";
-import { getSocket, bufferMessage, hasEntry, getBotClientId, getReliableEmitter } from "./socket/index.js";
-import { formatCosUrls } from "./format-urls.js";
-/** 获取日志器 */
+import { CHANNEL_KEY, DEFAULT_ACCOUNT_ID, EVENT_MESSAGE_PRIVATE } from './config.js';
+import { getLightclawRuntime } from './runtime.js';
+import { getSocket, bufferMessage, hasEntry, getBotClientId, getReliableEmitter } from './socket/index.js';
+import { resolveAccount } from './utils/index.js';
+/**
+ * 获取出站模块专属日志器。
+ * 通过 getChildLogger 注入 module 标签，方便在日志系统中过滤出站相关日志。
+ */
 function getLogger() {
-    return getAssistantRuntime().logging.getChildLogger({ module: "outbound" });
+    return getLightclawRuntime().logging.getChildLogger({ module: 'outbound' });
 }
-/** 生成消息 ID */
+/**
+ * 出站消息 ID 计数器，用于生成全局唯一的消息序号。
+ * 模块级变量，进程生命周期内单调递增，不会重置。
+ */
 let outboundMsgCounter = 0;
+/**
+ * 生成出站消息的唯一 ID。
+ *
+ * ID 格式：`ob-<时间戳base36>-<随机串>-<序号base36>`
+ * - `ob-` 前缀：标识来源为 outbound 模块，便于日志追踪
+ * - 时间戳（base36）：毫秒级，保证时间有序性
+ * - 随机串（6位）：防止同一毫秒内的碰撞
+ * - 序号（base36）：进程内单调递增，兜底保证唯一性
+ *
+ * @returns 格式为 `ob-<ts>-<rand>-<seq>` 的唯一消息 ID
+ */
 function generateOutboundMsgId() {
     const ts = Date.now().toString(36);
     const rand = Math.random().toString(36).substring(2, 8);
@@ -25,40 +44,68 @@ function generateOutboundMsgId() {
     return `ob-${ts}-${rand}-${seq}`;
 }
 /**
- * 解析目标用户 ID：去掉各种前缀，提取纯 ID
- * 支持格式: user:xxx, channel:xxx, lightclawbot:dm:xxx, lightclawbot:group:xxx, dm:xxx, 纯ID
+ * 解析消息目标地址，提取纯用户/群组 ID。
+ *
+ * 支持的输入格式（均会被剥离前缀，返回纯 ID）：
+ * - `lightclawbot:dm:123`    → `123`
+ * - `lightclawbot:group:456` → `456`
+ * - `user:123`               → `123`
+ * - `channel:456`            → `456`
+ * - `dm:123`                 → `123`
+ * - `group:456`              → `456`
+ * - `123`                    → `123`（纯 ID，原样返回）
+ *
+ * @param to - 原始目标地址字符串
+ * @returns 去除所有前缀后的纯 ID 字符串
  */
 function resolveTarget(to) {
-    return to
-        .replace(new RegExp(`^${CHANNEL_KEY}:`, "i"), "")
-        .replace(/^(user|channel|dm|group):/, "");
+    return (to
+        // 第一步：去掉通道名前缀（如 "lightclawbot:"）
+        .replace(new RegExp(`^${CHANNEL_KEY}:`, 'i'), '')
+        // 第二步：去掉类型前缀（user: / channel: / dm: / group:）
+        .replace(/^(user|channel|dm|group):/, ''));
 }
 /**
- * 通过 WS 发送消息。
+ * 通过 WebSocket 长连接发送消息。
  *
- * 策略：
- *   1. socket connected → 直接发送
- *   2. socket 断开但 entry 存在（正在重连中）→ 缓冲消息，重连后自动 flush
- *   3. entry 不存在 → 返回 null（gateway 尚未启动或已销毁）
+ * 内部策略（按优先级）：
+ *   1. **可靠发送**：entry 存在且 socket 已连接 → 使用 `emitWithAck` 发送，
+ *      内置 ACK 确认 + 自动重试，发送失败时记录错误日志。
+ *   2. **直接 emit（兜底）**：可靠发送器不可用时，直接调用 `socket.emit`，
+ *      不保证送达，仅作为最后防线。
+ *   3. **消息缓冲**：socket 断开但 entry 仍存在（正在自动重连）→
+ *      将消息写入缓冲队列，重连成功后由 gateway 自动 flush。
+ *   4. **返回 null**：entry 不存在（gateway 未启动或已销毁）→
+ *      调用方应降级到 REST API。
+ *
+ * @param accountId - 发送账户 ID，为空时使用 DEFAULT_ACCOUNT_ID
+ * @param target    - 已解析的纯目标 ID（用户 ID 或群组 ID）
+ * @param text      - 消息文本内容
+ * @param replyToId - 回复的原始消息 ID（可选）
+ * @returns 成功时返回消息 ID 字符串；无法通过 WS 发送时返回 null
  */
 function sendViaSocket(accountId, target, text, replyToId) {
     const resolvedAccountId = accountId || DEFAULT_ACCOUNT_ID;
+    // 从 socket-registry 中获取当前账户的 socket entry
     const entry = getSocket(resolvedAccountId);
     const msgId = generateOutboundMsgId();
+    // 构造标准消息体，格式与 gateway 入站消息保持一致
     const message = {
         msgId,
-        from: entry?.botClientId ?? getBotClientId(resolvedAccountId) ?? "",
+        // 优先使用 entry 中缓存的 botClientId，entry 不存在时从 registry 直接查询
+        from: entry?.botClientId ?? getBotClientId(resolvedAccountId) ?? '',
         to: target,
-        content: formatCosUrls(text),
+        content: text,
         timestamp: Date.now(),
+        // undefined 表示非回复消息，避免发送多余字段
         replyToMsgId: replyToId ?? undefined,
     };
     if (entry) {
-        // Socket connected — 优先走可靠发送
+        // 策略 1：Socket 已连接，优先走可靠发送（emitWithAck + 自动重试）
         const emitter = getReliableEmitter(resolvedAccountId);
         if (emitter) {
-            emitter.emitWithAck(EVENT_MESSAGE_PRIVATE, message, msgId)
-                .then(ok => {
+            emitter.emitWithAck(EVENT_MESSAGE_PRIVATE, message, msgId).then((ok) => {
+                // ok=false 表示重试耗尽仍未收到 ACK，记录错误供告警系统捕获
                 if (!ok) {
                     getLogger().error(`[${CHANNEL_KEY}] outbound delivery failed after retries: msgId=${msgId}`);
                 }
@@ -66,18 +113,20 @@ function sendViaSocket(accountId, target, text, replyToId) {
             getLogger().info(`[${CHANNEL_KEY}] outbound sent via reliable WS: to=${target} msgId=${msgId}`);
             return msgId;
         }
-        // fallback: 直接 emit（不应走到这里，但保留兜底）
+        // 策略 2：可靠发送器不可用，直接 emit（兜底，正常情况不应走到此分支）
         try {
             entry.socket.emit(EVENT_MESSAGE_PRIVATE, message);
             getLogger().info(`[${CHANNEL_KEY}] outbound sent via WS (fallback): to=${target} msgId=${msgId}`);
             return msgId;
         }
         catch (err) {
+            // emit 本身抛异常（如 socket 已关闭），降级到 REST API
             getLogger().warn(`[${CHANNEL_KEY}] outbound WS emit failed: ${err}`);
             return null;
         }
     }
-    // Socket 断开但 entry 存在（正在自动重连），缓冲消息
+    // 策略 3：Socket 断开但 entry 存在（正在自动重连），将消息写入缓冲队列
+    // 重连成功后，gateway 会自动 flush 缓冲队列，保证消息最终送达
     if (hasEntry(resolvedAccountId)) {
         const buffered = bufferMessage(resolvedAccountId, message);
         if (buffered) {
@@ -85,32 +134,47 @@ function sendViaSocket(accountId, target, text, replyToId) {
             return msgId;
         }
     }
-    // Entry 不存在，gateway 未启动或已销毁
+    // 策略 4：entry 不存在，gateway 未启动或已销毁，返回 null 触发 REST 降级
     return null;
 }
 /**
- * 发送文本消息
- * 由 channel.outbound.sendText 调用
+ * 发送纯文本消息。
+ *
+ * 由 `channel.outbound.sendText` 调用，是框架层文本消息的统一出口。
+ *
+ * 发送流程：
+ *   1. 解析账户配置（API Key、Base URL 等）
+ *   2. 规范化目标地址（去除前缀，提取纯 ID）
+ *   3. 优先通过 WS 发送；WS 不可用时降级到 REST API
+ *   4. REST API 也不可用时抛出错误，由框架层统一处理
+ *
+ * @param ctx - OpenClaw 框架注入的出站上下文，包含 to、text、accountId、replyToId、cfg 等字段
+ * @returns `{ channel, messageId }` — 发送成功后的通道标识和消息 ID
+ * @throws 当 WS 和 REST API 均不可用时抛出 Error
  */
 export async function sendText(ctx) {
     const log = getLogger();
     try {
+        // 解析账户配置（含 apiKey、apiBaseUrl、accountId 等）
         const account = resolveAccount(ctx.cfg, ctx.accountId);
+        // 将框架格式的目标地址转换为纯 ID
         const target = resolveTarget(ctx.to);
-        // 优先走 WS
+        // 优先走 WS 长连接（低延迟、无额外网络开销）
         const wsMsgId = sendViaSocket(account.accountId, target, ctx.text, ctx.replyToId);
         if (wsMsgId) {
             return { channel: CHANNEL_KEY, messageId: wsMsgId };
         }
-        // Fallback: REST API
+        // WS 不可用，降级到 REST API
+        // 若未配置 apiBaseUrl，则无法降级，直接抛出错误
         if (!account.apiBaseUrl) {
-            throw new Error("WS not connected and apiBaseUrl not configured, cannot send outbound message");
+            throw new Error('WS not connected and apiBaseUrl not configured, cannot send outbound message');
         }
         log.info(`[${CHANNEL_KEY}] outbound fallback to REST API: to=${target}`);
         const resp = await fetch(`${account.apiBaseUrl}/send`, {
-            method: "POST",
+            method: 'POST',
             headers: {
-                "Content-Type": "application/json",
+                'Content-Type': 'application/json',
+                // Bearer Token 鉴权，apiKey 来自账户配置
                 Authorization: `Bearer ${account.apiKey}`,
             },
             body: JSON.stringify({
@@ -119,11 +183,13 @@ export async function sendText(ctx) {
                 replyToMessageId: ctx.replyToId,
             }),
         });
+        // HTTP 非 2xx 状态码视为发送失败，读取响应体作为错误信息
         if (!resp.ok) {
             const errText = await resp.text();
             throw new Error(`Send failed (${resp.status}): ${errText}`);
         }
         const data = (await resp.json());
+        // 服务端未返回 messageId 时，使用时间戳兜底，保证返回值非空
         return { channel: CHANNEL_KEY, messageId: data.messageId ?? `msg_${Date.now()}` };
     }
     catch (err) {
@@ -132,50 +198,69 @@ export async function sendText(ctx) {
     }
 }
 /**
- * 发送媒体消息
- * 由 channel.outbound.sendMedia 调用
+ * 发送媒体消息（图片、文件、视频等）。
+ *
+ * 由 `channel.outbound.sendMedia` 调用，是框架层媒体消息的统一出口。
+ *
+ * 发送策略（媒体消息比文本消息更复杂，需区分是否有 mediaUrl）：
+ *   - **无 mediaUrl**：仅发送文字说明，走 WS → REST 降级链路（与 sendText 一致）
+ *   - **有 mediaUrl + 有 REST API**：走 REST API 发送完整媒体消息（含 URL）
+ *   - **有 mediaUrl + 无 REST API**：WS 不支持大文件传输，仅发送文字说明部分
+ *   - **WS 和 REST 均不可用**：抛出错误
+ *
+ * 注意：WS 通道不适合传输大文件（二进制数据），因此媒体文件始终通过 REST API 发送；
+ * WS 仅用于发送媒体消息的文字说明部分（作为降级兜底）。
+ *
+ * @param ctx - OpenClaw 框架注入的出站上下文，包含 to、text、mediaUrl、accountId、replyToId、cfg 等字段
+ * @returns `{ channel, messageId }` — 发送成功后的通道标识和消息 ID
+ * @throws 当 WS 和 REST API 均不可用时抛出 Error
  */
 export async function sendMedia(ctx) {
     const log = getLogger();
     try {
+        // 解析账户配置
         const account = resolveAccount(ctx.cfg, ctx.accountId);
+        // 规范化目标地址
         const target = resolveTarget(ctx.to);
-        // 优先走 WS（媒体消息只发文本部分，因为 WS 不方便传大文件）
-        // 如果有 mediaUrl 且没有 REST API，仍用 WS 发文本
+        // 无 mediaUrl 时，退化为纯文本发送，走 WS → REST 降级链路
         if (!ctx.mediaUrl) {
             const wsMsgId = sendViaSocket(account.accountId, target, ctx.text, ctx.replyToId);
             if (wsMsgId) {
                 return { channel: CHANNEL_KEY, messageId: wsMsgId };
             }
         }
-        // Fallback: REST API
+        // 未配置 REST API 时的兜底处理：
+        // 即使有 mediaUrl 也无法发送完整媒体，退而发送文字说明部分（通过 WS）
         if (!account.apiBaseUrl) {
-            // 没有 REST API 也没有 mediaUrl，用 WS 发文本
             const wsMsgId = sendViaSocket(account.accountId, target, ctx.text, ctx.replyToId);
             if (wsMsgId) {
                 return { channel: CHANNEL_KEY, messageId: wsMsgId };
             }
-            throw new Error("WS not connected and apiBaseUrl not configured, cannot send outbound media");
+            // WS 也不可用，彻底无法发送，抛出错误
+            throw new Error('WS not connected and apiBaseUrl not configured, cannot send outbound media');
         }
+        // 通过 REST API 发送完整媒体消息（含 mediaUrl）
         log.info(`[${CHANNEL_KEY}] outbound media via REST API: to=${target}`);
         const resp = await fetch(`${account.apiBaseUrl}/send-media`, {
-            method: "POST",
+            method: 'POST',
             headers: {
-                "Content-Type": "application/json",
+                'Content-Type': 'application/json',
                 Authorization: `Bearer ${account.apiKey}`,
             },
             body: JSON.stringify({
                 target,
-                text: ctx.text,
-                mediaUrl: ctx.mediaUrl,
+                text: ctx.text, // 媒体消息的文字说明（可选）
+                mediaUrl: ctx.mediaUrl, // 媒体资源 URL（图片/文件/视频等）
                 replyToMessageId: ctx.replyToId,
             }),
         });
+        // HTTP 非 2xx 状态码视为发送失败
         if (!resp.ok) {
             const errText = await resp.text();
             throw new Error(`Send media failed (${resp.status}): ${errText}`);
         }
         const data = (await resp.json());
+        // 服务端未返回 messageId 时，使用时间戳兜底
         return { channel: CHANNEL_KEY, messageId: data.messageId ?? `msg_${Date.now()}` };
     }
     catch (err) {
@@ -183,4 +268,3 @@ export async function sendMedia(ctx) {
         throw err;
     }
 }
-//# sourceMappingURL=outbound.js.map

package/dist/src/runtime.js

@@ -1,11 +1,9 @@
-import { CHANNEL_KEY } from "./config.js";
-let runtime;
-export function setAssistantRuntime(rt) {
-    runtime = rt;
-}
-export function getAssistantRuntime() {
-    if (!runtime)
-        throw new Error(`[${CHANNEL_KEY}] PluginRuntime not initialized — register() not called yet`);
-    return runtime;
-}
-//# sourceMappingURL=runtime.js.map
+/**
+ * LightClaw — 插件运行时存储
+ *
+ * 使用 SDK 标准的 createPluginRuntimeStore 替代手动单例管理，
+ * 确保与官方 channel 插件（Discord/Slack）的模式一致。
+ */
+import { createPluginRuntimeStore } from 'openclaw/plugin-sdk/runtime-store';
+const { setRuntime: setLightclawRuntime, getRuntime: getLightclawRuntime } = createPluginRuntimeStore('LightClaw runtime not initialized');
+export { getLightclawRuntime, setLightclawRuntime };

package/dist/src/setup-core.js

@@ -0,0 +1,27 @@
+/**
+ * LightClaw — Setup 核心逻辑
+ *
+ * 从 channel.ts 中提取的 setup 适配器，
+ * 被 channel.ts（完整插件）和 channel.setup.ts（轻量 setup 插件）共享。
+ */
+import { applyAccountNameToChannelSection } from 'openclaw/plugin-sdk/core';
+import { CHANNEL_KEY, applyAccountConfig } from './config.js';
+import { defaultAccountId } from './utils/account.js';
+export const lightclawSetupAdapter = {
+    resolveAccountId: ({ accountId, cfg }) => accountId?.trim().toLowerCase() || defaultAccountId(cfg),
+    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 }) => {
+        const token = input.token;
+        return applyAccountConfig(cfg, accountId, {
+            apiKey: token,
+            apiBaseUrl: input.apiBaseUrl,
+            name: input.name,
+        });
+    },
+};

package/dist/src/shared.js

@@ -0,0 +1,141 @@
+/**
+ * LightClaw — 插件基础定义（shared）
+ *
+ * 参照官方 Discord/Slack 的 shared.ts 模式：
+ * - 提供 createLightclawPluginBase() 工厂函数
+ * - 共享 config adapter 和常量
+ *
+ * 此模块被 channel.ts（完整插件）和 channel.setup.ts（轻量 setup 插件）同时使用。
+ */
+import { createChannelPluginBase, deleteAccountFromConfigSection, setAccountEnabledInConfigSection, } from 'openclaw/plugin-sdk/core';
+import { CHANNEL_KEY, DEFAULT_ACCOUNT_ID } from './config.js';
+import { listAccountIds, resolveAccount, defaultAccountId } from './utils/account.js';
+// ============================================================
+// 配置适配器
+// ============================================================
+/**
+ * LightClaw 配置适配器（config section）
+ *
+ * 官方渠道使用 createScopedChannelConfigAdapter，
+ * LightClaw 因有自定义的 apiKeys 数组等特殊配置，保留自定义实现。
+ */
+export const lightclawConfigAdapter = {
+    /**
+     * 列出当前配置中所有已注册的账户 ID。
+     * @param cfg - 全局 OpenClaw 配置对象
+     */
+    listAccountIds: (cfg) => listAccountIds(cfg),
+    /**
+     * 根据账户 ID 解析出完整的账户配置对象（含 API Key、Base URL 等）。
+     * @param cfg       - 全局配置对象
+     * @param accountId - 目标账户 ID
+     */
+    resolveAccount: (cfg, accountId) => {
+        return resolveAccount(cfg, accountId);
+    },
+    /**
+     * 获取默认账户 ID（通常为 DEFAULT_ACCOUNT_ID 常量）。
+     * @param cfg - 全局配置对象
+     */
+    defaultAccountId: (cfg) => defaultAccountId(cfg),
+    /**
+     * 启用或禁用指定账户。
+     * 委托给 SDK 的 setAccountEnabledInConfigSection 工具函数，
+     * allowTopLevel=true 表示允许在顶层配置节（非 accounts 子对象）中操作。
+     */
+    setAccountEnabled: ({ cfg, accountId, enabled }) => {
+        return setAccountEnabledInConfigSection({
+            cfg,
+            sectionKey: CHANNEL_KEY,
+            accountId,
+            enabled,
+            allowTopLevel: true,
+        });
+    },
+    /**
+     * 从配置中删除指定账户，同时清除关联的基础字段。
+     * clearBaseFields 指定了删除账户时需要一并清空的顶层字段。
+     */
+    deleteAccount: ({ cfg, accountId }) => {
+        return deleteAccountFromConfigSection({
+            cfg,
+            sectionKey: CHANNEL_KEY,
+            accountId,
+            clearBaseFields: ['apiBaseUrl', 'name'],
+        });
+    },
+    /**
+     * 判断账户是否已完成配置， apiKey是否存在。
+     * @param account - 已解析的账户对象
+     */
+    isConfigured: (account) => {
+        return Boolean(account?.apiKey);
+    },
+    /**
+     * 将账户信息序列化为框架可展示的摘要对象。
+     * 用于 CLI 的 `status` 命令和 UI 的账户列表展示。
+     * @param account - 已解析的账户对象
+     */
+    describeAccount: (account) => ({
+        accountId: account.accountId ?? DEFAULT_ACCOUNT_ID,
+        name: account.name || '',
+        enabled: account.enabled ?? false,
+        configured: Boolean(account?.apiKey),
+    }),
+    /**
+     * 解析账户的 allowFrom 白名单列表（允许接收消息的来源 ID）。
+     * 返回字符串数组，供框架做入站消息过滤。
+     * @param cfg       - 全局配置对象
+     * @param accountId - 目标账户 ID
+     */
+    resolveAllowFrom: ({ cfg, accountId }) => {
+        const account = resolveAccount(cfg, accountId);
+        return account.allowFrom?.map(String) ?? [];
+    },
+};
+// ============================================================
+// 插件基础工厂
+// ============================================================
+/**
+ * createLightclawPluginBase
+ *
+ * 参照 Discord 的 createDiscordPluginBase / Slack 的 createSlackPluginBase 模式，
+ * 使用 SDK 提供的 createChannelPluginBase 构建插件骨架。
+ *
+ * 返回的字段集（id, meta, capabilities, streaming, configSchema, config, setup）
+ * 被 channel.ts 和 channel.setup.ts 共享。
+ */
+export function createLightclawPluginBase(params) {
+    return createChannelPluginBase({
+        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,
+        },
+        streaming: {
+            blockStreamingCoalesceDefaults: { minChars: 1500, idleMs: 1000 },
+        },
+        reload: { configPrefixes: [`channels.${CHANNEL_KEY}`] },
+        configSchema: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {},
+            },
+        },
+        config: lightclawConfigAdapter,
+        setup: params.setup,
+    });
+}