@qingtui/openclaw-plugin 0.0.0-stage → 1.1.0

package/dist/src/client.js

@@ -0,0 +1,416 @@
+/**
+ * nudge（轻推）平台连接与消息 API 客户端。
+ *
+ * 长连接由 @qingtui/socket-sdk 承载（socket.io 封装，源码在
+ * app-qingtui-msg-proxy/sdk/js/nudge-socket）：
+ *  - src/service.ts 的后台 service 启动时为每个已配置账号调
+ *    connectNudgeSocket 建连，关停时 disconnectNudgeSocket 断开；进程内
+ *    按 accountId 维护连接池（多机器人各自一条连接，凭证与生命周期互不影响）
+ *  - 出站（channel.ts outbound、inbound.ts delivery、stream.ts）经
+ *    nudgeChatApi / nudgeStreamApi 按 accountId 复用对应连接，经代理的
+ *    api-request 透传，响应统一为 {success, data|error}
+ *  - 代理只透传 JSON：白名单拉取、媒体上传等 REST 调用直接用 Node fetch
+ *    访问开放平台（地址来自该账号建连时传入的 openUrl）
+ *
+ * 动态白名单缓存 fail-closed：同步成功前缓存为空 = 全部拒绝。
+ */
+import { QingtuiSocketClient, } from "@qingtui/socket-sdk";
+import { loadWebMediaRaw, optimizeImageToJpeg, } from "openclaw/plugin-sdk/web-media";
+import { buildTargetedMessage, decodeNudgeTarget, encodeNudgeTarget, } from "./target.js";
+export { encodeNudgeTarget };
+/** accountId -> 连接上下文（多机器人各自独立） */
+const connections = new Map();
+/** 账号 id -> 连接池键（channel.ts 已规范化，这里只做缺省兜底） */
+function resolveSocketKey(accountId) {
+    return accountId?.trim() || "default";
+}
+/** 建立某账号到轻推消息代理的连接；重复调用会先断开该账号旧连接。 */
+export async function connectNudgeSocket(accountId, options, handlers = {}) {
+    disconnectNudgeSocket(accountId);
+    const client = new QingtuiSocketClient({
+        appid: options.appid,
+        appsecret: options.appsecret,
+        serverUrl: options.serverUrl,
+        // SDK 默认 5 次重连耗尽即永久放弃（不再自愈，只能重启 service），
+        // 长时间服务端中断会让连接死透 —— 默认无限重试兜底。
+        maxReconnectAttempts: Infinity,
+        ...options.socket,
+    });
+    if (handlers.onMessage)
+        client.on("message", handlers.onMessage);
+    if (handlers.onAuthenticated)
+        client.on("authenticated", handlers.onAuthenticated);
+    if (handlers.onDisconnected)
+        client.on("disconnected", handlers.onDisconnected);
+    if (handlers.onReconnected)
+        client.on("reconnected", handlers.onReconnected);
+    if (handlers.onError)
+        client.on("error", handlers.onError);
+    if (handlers.onHeartbeatTimeout)
+        client.on("heartbeatTimeout", handlers.onHeartbeatTimeout);
+    // 先保存句柄再连接：connect() 在首次 connect_error 时 reject，
+    // 但 SDK 内部仍会按指数退避自动重连 —— 句柄必须在重连成功后就可用，
+    // 否则恢复后出站仍报“未连接”。调用方决定是否把首次失败当作致命错误。
+    connections.set(resolveSocketKey(accountId), {
+        client,
+        openUrl: options.openUrl,
+        creds: { appid: options.appid, appsecret: options.appsecret },
+    });
+    await client.connect();
+    return client;
+}
+/** 断开指定账号的连接；不传 accountId 时断开全部 */
+export function disconnectNudgeSocket(accountId) {
+    if (accountId?.trim()) {
+        const key = resolveSocketKey(accountId);
+        connections.get(key)?.client.destroy();
+        connections.delete(key);
+        return;
+    }
+    for (const connection of connections.values())
+        connection.client.destroy();
+    connections.clear();
+}
+function requireConnection(accountId) {
+    const key = resolveSocketKey(accountId);
+    const connection = connections.get(key);
+    if (connection?.client.getStatus() !== "connected") {
+        throw new Error(`openclaw-nudge: 账号 "${key}" 到轻推消息代理的 socket 未连接` +
+            "（gateway 的 qingtui-inbound service 未运行或已断线）");
+    }
+    return connection;
+}
+// ---------------------------------------------------------------------------
+// 开放平台 REST 调用（绕过 socket 代理）
+// ---------------------------------------------------------------------------
+/** /v1/token 下发的 token 有效期 7200 秒；提前 5 分钟视为过期 */
+const REST_TOKEN_TTL_MS = (7200 - 300) * 1000;
+/**
+ * 解析开放平台 JSON 响应：HTTP 非 2xx 或 errcode 非零（轻推错误约定）即抛错。
+ */
+async function readOpenApiJson(res, what) {
+    if (!res.ok) {
+        throw new Error(`openclaw-nudge: ${what} HTTP 失败: ${res.status} ${res.statusText}`);
+    }
+    const data = (await res.json());
+    if (data.errcode !== undefined && data.errcode !== 0) {
+        throw new Error(`openclaw-nudge: ${what}失败: ${String(data.errmsg ?? "unknown")} (errcode: ${String(data.errcode)})`);
+    }
+    return data;
+}
+/** 经 REST /v1/token 获取 access_token（带进程内缓存，按账号隔离） */
+async function fetchRestAccessToken(connection) {
+    const cached = connection.restToken;
+    if (cached && cached.expiresAt > Date.now())
+        return cached.value;
+    const url = `${connection.openUrl}/v1/token?grant_type=client_credential` +
+        `&appid=${encodeURIComponent(connection.creds.appid)}` +
+        `&secret=${encodeURIComponent(connection.creds.appsecret)}`;
+    const data = await readOpenApiJson(await fetch(url), "获取 access_token ");
+    const token = data.access_token;
+    if (typeof token !== "string" || !token) {
+        throw new Error("openclaw-nudge: access_token 响应缺少 access_token");
+    }
+    connection.restToken = {
+        value: token,
+        expiresAt: Date.now() + REST_TOKEN_TTL_MS,
+    };
+    return token;
+}
+/**
+ * 带 access_token 执行 REST 调用：优先复用 socket 认证/刷新下发的 token，
+ * 不可用或调用失败时回退 REST /v1/token 获取的 token 重试一次。
+ * 白名单拉取和媒体上传共用这一策略。
+ */
+async function withAccessToken(connection, call) {
+    const socketToken = connection.client.getAccessToken();
+    if (socketToken) {
+        try {
+            return await call(socketToken);
+        }
+        catch {
+            // socket token 可能过期或不被该接口接受，回退 REST token
+        }
+    }
+    try {
+        return await call(await fetchRestAccessToken(connection));
+    }
+    catch (error) {
+        // REST token 也失败时作废缓存，下次重新获取
+        connection.restToken = undefined;
+        throw error;
+    }
+}
+// ---------------------------------------------------------------------------
+// 动态 allowFrom（nudge 侧可见范围白名单同步，按账号隔离）
+// ---------------------------------------------------------------------------
+/**
+ * 入站准入是同步读：每条消息不能现拉 nudge 接口，因此由 service 在建连后
+ * 按账号后台定时同步到本缓存。生效白名单只来自本缓存（无静态配置）。
+ * 首次同步成功前缓存为空 —— fail-closed。
+ */
+const dynamicAllowFromByAccount = new Map();
+/** 同步读：指定账号当前缓存的白名单（同步失败时保持旧值） */
+export function getDynamicAllowFrom(accountId) {
+    return dynamicAllowFromByAccount.get(resolveSocketKey(accountId)) ?? [];
+}
+/** 清空缓存（service 停止时调用，回到 fail-closed 初始态）；不传账号时清全部 */
+export function resetDynamicAllowFrom(accountId) {
+    if (accountId?.trim()) {
+        dynamicAllowFromByAccount.delete(resolveSocketKey(accountId));
+        return;
+    }
+    dynamicAllowFromByAccount.clear();
+}
+/**
+ * 拉取应用可见范围内的用户 open_id 与群聊 channel_id（合并在同一数组）：
+ *   GET /v1/app/followersandchannels?access_token=...
+ * 对应 Java 侧 AppApi.getFollowersAndInChannels，DM 与群聊共用这份白名单。
+ */
+async function fetchFollowersAndChannels(openUrl, accessToken) {
+    const url = `${openUrl}/v1/app/followersandchannels?access_token=${encodeURIComponent(accessToken)}`;
+    const data = await readOpenApiJson(await fetch(url), "获取 followers ");
+    const followers = data.followers;
+    if (!Array.isArray(followers)) {
+        throw new Error("openclaw-nudge: followers 响应缺少 followers 数组");
+    }
+    return followers.filter((v) => typeof v === "string" && !!v);
+}
+/**
+ * 拉取并刷新指定账号的动态白名单缓存。
+ * 返回本次同步的条目数；该账号 socket 未连接或请求期间连接已失效时返回
+ * null（静默跳过）。
+ * 拉取异常向外抛（调用方记日志），旧缓存保持不变。
+ */
+export async function refreshDynamicAllowFrom(accountId) {
+    const key = resolveSocketKey(accountId);
+    const connection = connections.get(key);
+    if (connection?.client.getStatus() !== "connected")
+        return null;
+    const ids = await withAccessToken(connection, (token) => fetchFollowersAndChannels(connection.openUrl, token));
+    // 请求期间连接可能已被断开（service 停止并清缓存）或被同账号重连替换：
+    // 只有发起请求的连接仍是当前连接时才写缓存，避免旧结果复活已清空的白名单
+    if (connections.get(key) !== connection)
+        return null;
+    const unique = [...new Set(ids)];
+    dynamicAllowFromByAccount.set(key, unique);
+    return unique.length;
+}
+function assertSendOk(response, what) {
+    if (response?.success === false) {
+        const errcode = response.error?.errcode ?? "?";
+        const errmsg = response.error?.errmsg ?? "unknown error";
+        throw new Error(`openclaw-nudge: ${what}发送失败: ${errmsg} (errcode: ${errcode})`);
+    }
+}
+/** 从开放平台响应里尽力提取消息 id（字段名随消息类型而异） */
+function extractMessageId(data) {
+    if (!data || typeof data !== "object")
+        return "";
+    const record = data;
+    const id = record.msg_id ?? record.message_id ?? record.id;
+    return typeof id === "string" || typeof id === "number" ? String(id) : "";
+}
+// ---------------------------------------------------------------------------
+// 媒体加载与上传（轻推 /v1/media/upload multipart/form-data）
+// ---------------------------------------------------------------------------
+/** 轻推限制：图片 ≤300KB（JPG/JPEG/PNG），文件 ≤30MB，media_id 暂无过期 */
+const IMAGE_MAX_BYTES = 300 * 1024;
+const FILE_MAX_BYTES = 30 * 1024 * 1024;
+const IMAGE_EXTS = new Set(["jpg", "jpeg", "png"]);
+function fileExtension(fileName) {
+    const dot = fileName.lastIndexOf(".");
+    return dot >= 0 ? fileName.slice(dot + 1).toLowerCase() : "";
+}
+/**
+ * 经宿主媒体加载器读取媒体（远程 URL 走宿主 SSRF 策略，本地路径限定在
+ * 宿主授权根目录内），并按轻推限制决定发图片还是文件：
+ *  - JPG/PNG 且 ≤300KB：图片
+ *  - JPG/PNG 但超限：先尝试压缩成 ≤300KB 的 JPEG，失败则按文件发送
+ *  - 其他类型：文件（≤30MB，超限由加载器拒绝）
+ */
+async function prepareMedia(mediaUrl, access) {
+    const loaded = await loadWebMediaRaw(mediaUrl, {
+        maxBytes: FILE_MAX_BYTES,
+        localRoots: access?.localRoots,
+        readFile: access?.readFile,
+        workspaceDir: access?.workspaceDir,
+    });
+    const fileName = loaded.fileName || "file";
+    const ext = fileExtension(fileName);
+    const asFile = {
+        buffer: loaded.buffer,
+        fileName,
+        mediaType: "file",
+        contentType: loaded.contentType || "application/octet-stream",
+    };
+    if (loaded.kind !== "image" || !IMAGE_EXTS.has(ext))
+        return asFile;
+    if (loaded.buffer.length <= IMAGE_MAX_BYTES) {
+        return {
+            buffer: loaded.buffer,
+            fileName,
+            mediaType: "image",
+            contentType: ext === "png" ? "image/png" : "image/jpeg",
+        };
+    }
+    try {
+        const optimized = await optimizeImageToJpeg(loaded.buffer, IMAGE_MAX_BYTES, {
+            contentType: loaded.contentType,
+            fileName,
+        });
+        if (optimized.buffer.length <= IMAGE_MAX_BYTES) {
+            return {
+                buffer: optimized.buffer,
+                fileName: `${fileName.replace(/\.[^.]+$/, "")}.jpg`,
+                mediaType: "image",
+                contentType: "image/jpeg",
+            };
+        }
+    }
+    catch {
+        // 图片处理器不可用或压缩失败：按文件发送，保证内容送达
+    }
+    return asFile;
+}
+/**
+ * 上传多媒体文件到轻推开放平台，返回 media_id。
+ * socket 代理的 api-request 只透传 JSON，无法承载 multipart，因此直接用
+ * Node fetch + FormData 访问该账号的开放平台地址。
+ */
+async function uploadMedia(connection, media) {
+    return withAccessToken(connection, async (accessToken) => {
+        const uploadUrl = `${connection.openUrl}/v1/media/upload?access_token=${encodeURIComponent(accessToken)}&type=${media.mediaType}`;
+        const formData = new FormData();
+        // Buffer 扩展 Uint8Array<ArrayBufferLike>，Blob 要求 BlobPart 不接受
+        // SharedArrayBuffer；经 Uint8Array 包装确保类型安全
+        formData.append("media", new Blob([new Uint8Array(media.buffer)], { type: media.contentType }), media.fileName);
+        const result = await readOpenApiJson(await fetch(uploadUrl, { method: "POST", body: formData }), "上传媒体");
+        const mediaId = result.media_id;
+        if (typeof mediaId !== "string" || !mediaId) {
+            throw new Error("openclaw-nudge: 上传媒体响应缺少 media_id");
+        }
+        return mediaId;
+    });
+}
+// ---------------------------------------------------------------------------
+// 出站 API
+// ---------------------------------------------------------------------------
+export const nudgeChatApi = {
+    /**
+     * 发送文本消息（OpenClaw 回复 -> nudge，按账号选连接）。
+     * 群聊且携带 replyToId 时升级为引用消息（type="ref"），引用入站提问消息。
+     */
+    async sendMessage(params) {
+        const { client } = requireConnection(params.accountId);
+        const target = decodeNudgeTarget(params.to);
+        // 群聊有引用目标时走代理的 v1/message/ref/send/channel
+        // （代理仓 MessageType.REF 分支 → sendRefMessage）；单聊或无
+        // replyToId 时仍走普通文本。
+        const isRef = target.sendType === "channel" && !!params.replyToId;
+        const response = await client.sendMessage({
+            type: isRef ? "ref" : "text",
+            sendType: target.sendType,
+            message: buildTargetedMessage(target, isRef
+                ? { ref_msg_id: params.replyToId, content: params.text }
+                : { content: params.text }),
+        });
+        assertSendOk(response, isRef ? "群聊引用消息" : "文本消息");
+        return { id: extractMessageId(response.data), chatId: target.id };
+    },
+    /**
+     * 发送媒体文件（OpenClaw 回复 -> nudge）：
+     *  1. 宿主媒体加载器读取（受 SSRF/本地根目录策略约束）并按平台限制分类
+     *  2. multipart POST /v1/media/upload 拿 media_id
+     *  3. 经 socket 代理 sendMessage(type: "image"|"file") 发送 media_id
+     *  4. 有附带文字时再单独发一条普通文本（平台图片/文件消息只认 media_id）
+     *
+     * 返回媒体消息的 id。文字发送失败时抛错，此时媒体已送达。
+     */
+    async sendFile(params) {
+        const connection = requireConnection(params.accountId);
+        const target = decodeNudgeTarget(params.to);
+        const media = await prepareMedia(params.mediaUrl, params.mediaAccess);
+        const mediaId = await uploadMedia(connection, media);
+        const response = await connection.client.sendMessage({
+            type: media.mediaType,
+            sendType: target.sendType,
+            message: buildTargetedMessage(target, { media_id: mediaId }),
+        });
+        assertSendOk(response, `${media.mediaType === "image" ? "图片" : "文件"}消息`);
+        const result = { id: extractMessageId(response.data), chatId: target.id };
+        const caption = params.text?.trim();
+        if (caption) {
+            await nudgeChatApi.sendMessage({
+                accountId: params.accountId,
+                to: params.to,
+                text: caption,
+            });
+        }
+        return result;
+    },
+};
+export const nudgeStreamApi = {
+    /**
+     * 创建流式消息占位符（“正在生成”空消息）。
+     * 代理把 type:"streamPlaceholder" 分发到轻推
+     * POST /v1/message/text/stream/send/placeholder。
+     * chatType 映射：群聊 -> "2"，轻应用单聊 -> "5"。
+     */
+    async createPlaceholder(ctx) {
+        const { client } = requireConnection(ctx.accountId);
+        const target = decodeNudgeTarget(ctx.to);
+        const response = await client.sendMessage({
+            type: "streamPlaceholder",
+            sendType: target.sendType,
+            message: {
+                chatType: target.sendType === "channel" ? "2" : "5",
+                launchMsgId: ctx.launchMsgId,
+                launchAccountId: ctx.launchAccountId,
+                toObjectId: target.id,
+            },
+        });
+        assertSendOk(response, "流式占位");
+        const data = response.data;
+        const msgId = data?.msgId;
+        const appMsgId = data?.appMsgId;
+        if (typeof msgId !== "string" ||
+            !msgId ||
+            typeof appMsgId !== "string" ||
+            !appMsgId) {
+            throw new Error("openclaw-nudge: 流式占位响应缺少 msgId/appMsgId");
+        }
+        return { msgId, appMsgId };
+    },
+    /**
+     * 发送一个流式分片（message 为增量文本，代理侧按占位符追加进分块流）。
+     *
+     * status: 1=生成中 2=结束 5=异常。代理按
+     * `${placeholderMsgId}_${launchAccountId}` 维护 ReadableStream，
+     * 超过 30 秒（STREAM_MESSAGE_TIMEOUT）没有新分片会被代理自动关流；
+     * 任一 status=1 分片都会重置该计时。status=2 时代理会先补发剩余内容
+     * 再关流并清缓存，因此结束分片可以直接携带最后一段增量。
+     */
+    async sendChunk(params) {
+        const { client } = requireConnection(params.ctx.accountId);
+        const target = decodeNudgeTarget(params.ctx.to);
+        const response = await client.sendMessage({
+            type: "stream",
+            sendType: target.sendType,
+            // 代理的 STREAM 分支优先读 options.sendType，显式带上避免歧义
+            options: { sendType: target.sendType },
+            message: {
+                ...(target.sendType === "channel"
+                    ? { channelId: target.id }
+                    : { toUser: target.id }),
+                status: params.status,
+                placeholderMsgId: params.placeholder.msgId,
+                placeholderAppMsgId: params.placeholder.appMsgId,
+                launchMsgId: params.ctx.launchMsgId,
+                launchAccountId: params.ctx.launchAccountId,
+                message: params.message,
+            },
+        });
+        assertSendOk(response, "流式分片");
+    },
+};

package/dist/src/config.js

@@ -0,0 +1,164 @@
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId, patchScopedAccountConfig, } from "openclaw/plugin-sdk/setup";
+/** 渠道 ID：channels.<id>、路由与 manifest channels 使用；不同于插件 ID openclaw-nudge */
+export const NUDGE_CHANNEL_ID = "qingtui";
+/** 轻推服务地址缺省值（生产）；QA 环境为 https://qaqtopen.qingtui.com */
+export const DEFAULT_NUDGE_SERVER_URL = "https://open.qingtui.com";
+/** 读取渠道分节；非对象或不存在时返回 undefined */
+function readChannelSection(cfg) {
+    const section = cfg.channels?.[NUDGE_CHANNEL_ID];
+    if (!section || typeof section !== "object")
+        return undefined;
+    // 边界窄化：这里只确认分节是对象，各字段在使用点逐个 typeof 校验
+    return section;
+}
+/**
+ * 读取某账号的配置分节。
+ * 所有账号（含 default）统一读 accounts.<id>；渠道顶层不再有凭证键。
+ */
+export function readNudgeAccountConfig(cfg, accountId) {
+    const section = readChannelSection(cfg);
+    if (!section)
+        return undefined;
+    const normalized = normalizeAccountId(accountId ?? DEFAULT_ACCOUNT_ID);
+    const entry = section.accounts?.[normalized];
+    return entry && typeof entry === "object"
+        ? entry
+        : undefined;
+}
+/**
+ * 账号写盘统一落 accounts.<id>（含 default -> accounts.default）：
+ * scopeDefaultToAccounts 覆盖 patchScopedAccountConfig 的 default 写顶层
+ * 历史行为；ensure*Enabled 保证重跑向导后禁用态恢复。
+ */
+export function patchNudgeAccountConfig(params) {
+    return patchScopedAccountConfig({
+        cfg: params.cfg,
+        channelKey: NUDGE_CHANNEL_ID,
+        accountId: params.accountId,
+        patch: params.patch,
+        scopeDefaultToAccounts: true,
+        ensureChannelEnabled: true,
+        ensureAccountEnabled: true,
+    });
+}
+/** 写入渠道级轻推服务地址（向导用；所有账号共用） */
+export function patchNudgeServerUrl(cfg, serverUrl) {
+    return {
+        ...cfg,
+        channels: {
+            ...cfg.channels,
+            [NUDGE_CHANNEL_ID]: { ...readChannelSection(cfg), serverUrl },
+        },
+    };
+}
+/** 渠道总开关：缺省开启，仅显式 enabled:false 关闭 */
+export function isNudgeChannelEnabled(cfg) {
+    return readChannelSection(cfg)?.enabled !== false;
+}
+/** 单个账号是否已配置（appid + appsecret 齐备且账号未被禁用；不看渠道开关） */
+export function isNudgeAccountConfigured(cfg, accountId) {
+    const account = readNudgeAccountConfig(cfg, accountId);
+    return (account?.enabled !== false &&
+        typeof account?.appid === "string" &&
+        account.appid.length > 0 &&
+        typeof account?.appsecret === "string" &&
+        account.appsecret.length > 0);
+}
+/**
+ * 枚举账号 id：命名账号来自 accounts 分节；一个都没有（未配置）时
+ * 回退 ["default"]（向导首账号，不代表已有可用凭证）。
+ */
+export function listNudgeAccountIds(cfg) {
+    const section = readChannelSection(cfg);
+    const ids = new Set();
+    if (section?.accounts) {
+        for (const key of Object.keys(section.accounts)) {
+            const normalized = normalizeAccountId(key);
+            if (normalized)
+                ids.add(normalized);
+        }
+    }
+    if (ids.size === 0)
+        return [DEFAULT_ACCOUNT_ID];
+    return [...ids].sort((a, b) => a.localeCompare(b));
+}
+/** 默认账号：有 default 用 default（单账号语义），否则字典序第一个命名账号 */
+export function resolveDefaultNudgeAccountId(cfg) {
+    const ids = listNudgeAccountIds(cfg);
+    return ids.includes(DEFAULT_ACCOUNT_ID) ? DEFAULT_ACCOUNT_ID : ids[0];
+}
+/** 渠道是否已配置（任意账号凭证可用）；向导状态展示用 */
+export function isNudgeChannelConfigured(cfg) {
+    return listNudgeAccountIds(cfg).some((accountId) => isNudgeAccountConfigured(cfg, accountId));
+}
+/**
+ * 渠道级流式回复开关：channels.qingtui.streaming === false 时关闭，
+ * 缺省开启（还须是单聊且事件携带 account_id 才能真正开流，见 inbound.ts）。
+ */
+export function isNudgeStreamingEnabled(cfg) {
+    return readChannelSection(cfg)?.streaming !== false;
+}
+/**
+ * 规范化服务地址：要求 http(s) 绝对地址，去掉末尾斜杠；非法时返回 undefined。
+ * 向导校验与配置读取共用，避免拼接 REST 路径时出现双斜杠。
+ */
+export function normalizeNudgeUrl(value) {
+    if (typeof value !== "string" || !value.trim())
+        return undefined;
+    try {
+        const url = new URL(value.trim());
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            return undefined;
+        return url.toString().replace(/\/+$/, "");
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 已显式配置的轻推服务地址（向导回显用）；未配置或非法时 undefined */
+export function readConfiguredNudgeServerUrl(cfg) {
+    return normalizeNudgeUrl(readChannelSection(cfg)?.serverUrl);
+}
+/**
+ * Socket 代理地址（channels.qingtui.serverUrl），缺省生产地址。
+ * 不能依赖 SDK 自带的 localhost 默认值。
+ */
+export function resolveNudgeServerUrl(cfg) {
+    return readConfiguredNudgeServerUrl(cfg) ?? DEFAULT_NUDGE_SERVER_URL;
+}
+/**
+ * 开放平台 REST 地址（/v1/token、/v1/app/followersandchannels、
+ * /v1/media/upload）：优先 openUrl，其次 serverUrl（同一环境两者同域），
+ * 最后生产缺省值。
+ */
+export function resolveNudgeOpenUrl(cfg) {
+    return (normalizeNudgeUrl(readChannelSection(cfg)?.openUrl) ??
+        resolveNudgeServerUrl(cfg));
+}
+/** 按账号解析出已校验凭证；缺失/类型不对即抛错（调用点：channel config、inbound） */
+export function resolveAccount(cfg, accountId) {
+    const resolvedId = accountId
+        ? normalizeAccountId(accountId)
+        : resolveDefaultNudgeAccountId(cfg);
+    const account = readNudgeAccountConfig(cfg, resolvedId);
+    const appid = account?.appid;
+    const appsecret = account?.appsecret;
+    if (typeof appid !== "string" || !appid) {
+        throw new Error(`openclaw-nudge: appid is required (account "${resolvedId}")`);
+    }
+    if (typeof appsecret !== "string" || !appsecret) {
+        throw new Error(`openclaw-nudge: appsecret is required (account "${resolvedId}")`);
+    }
+    return { accountId: resolvedId, appid, appsecret };
+}
+/**
+ * 需要建连的账号（service 逐账号建连用）：渠道总开关关闭时返回空列表，
+ * 否则为凭证齐备且未禁用的账号。
+ */
+export function listConfiguredNudgeAccounts(cfg) {
+    if (!isNudgeChannelEnabled(cfg))
+        return [];
+    return listNudgeAccountIds(cfg)
+        .filter((accountId) => isNudgeAccountConfigured(cfg, accountId))
+        .map((accountId) => resolveAccount(cfg, accountId));
+}

package/dist/src/event.js

@@ -0,0 +1,81 @@
+function nonEmptyString(value) {
+    return typeof value === "string" && value ? value : undefined;
+}
+/**
+ * 把 socket 推送的原始负载归一化成统一事件。
+ * 只处理携带文本的消息事件（message / app_mention）；其他事件类型（成员
+ * 变更等）、残缺负载以及判定为群聊却缺少 channel_id 的事件返回 null
+ * （SDK 已 autoAck，直接忽略）。
+ */
+export function normalizeNudgeEvent(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    if (raw.type !== "event_callback")
+        return null;
+    const event = raw.event;
+    if (!event || typeof event !== "object")
+        return null;
+    if (event.type !== "message" && event.type !== "app_mention")
+        return null;
+    const id = nonEmptyString(raw.event_id);
+    const text = nonEmptyString(event.text);
+    if (!id || !text)
+        return null;
+    // 发送者标识：优先 open_id（单聊/普通消息），缺失时回退 account_id
+    // （群聊 app_mention 事件不携带 open_id，account_id = 发送者用户 id）
+    const from = nonEmptyString(event.open_id ?? event.account_id);
+    if (!from)
+        return null;
+    // 群聊类型推断：显式 chat_type="group"，或带 channel_id 的 app_mention
+    const channelId = nonEmptyString(event.channel_id);
+    const isGroup = event.chat_type === "group" ||
+        (event.type === "app_mention" && channelId !== undefined);
+    // 群聊必须有 channel_id：准入按群 id 匹配、回复发往群 id，缺失时若回退
+    // 发送者 id 会把回复编码成 channel:<用户id> 发错目标，直接丢弃
+    if (isGroup && !channelId)
+        return null;
+    // 群聊只响应 @机器人（app_mention），普通群消息不触发回复
+    if (isGroup && event.type !== "app_mention")
+        return null;
+    const eventTime = raw.event_time;
+    return {
+        id,
+        timestamp: typeof eventTime === "number" ? eventTime * 1000 : undefined,
+        from,
+        chatType: isGroup ? "group" : "direct",
+        chatId: isGroup && channelId ? channelId : from,
+        text,
+        // 平台目前不下发 event.msg_id，顶层 event_id 即提问消息 id；
+        // 将来下发 msg_id 时优先使用
+        msgId: nonEmptyString(event.msg_id) ?? id,
+        senderAccountId: nonEmptyString(event.account_id),
+    };
+}
+// ---------------------------------------------------------------------------
+// event_id 去重（服务端 ACK 重推兜底：1s 间隔最多 3 次）
+// ---------------------------------------------------------------------------
+const DEDUPE_TTL_MS = 5 * 60 * 1000;
+/**
+ * 按账号维度的事件去重器。键为 `accountId:eventId`：不同机器人各自收到的
+ * 推送互不影响。Map 保持插入顺序，过期清理从头扫到第一个未过期项即停。
+ */
+export function createEventDeduper(ttlMs = DEDUPE_TTL_MS) {
+    const seen = new Map();
+    return {
+        isDuplicate(accountId, eventId, now = Date.now()) {
+            for (const [key, seenAt] of seen) {
+                if (now - seenAt <= ttlMs)
+                    break;
+                seen.delete(key);
+            }
+            const key = `${accountId}:${eventId}`;
+            if (seen.has(key))
+                return true;
+            seen.set(key, now);
+            return false;
+        },
+        clear() {
+            seen.clear();
+        },
+    };
+}