@xgjktech/xg_cwork_im 1.19.41 → 1.19.42

package/dist/src/channel-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-log.d.ts","sourceRoot":"","sources":["../../src/channel-log.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,MAAM;IACnB,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED,qDAAqD;AACrD,wBAAgB,QAAQ,CACpB,IAAI,EACE;IAAE,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GAC5H,SAAS,GAChB,MAAM,CAyCR"}

package/dist/src/channel-log.js

@@ -0,0 +1,45 @@
+/**
+ * Channel 统一日志适配器：兼容 ChannelLogSink 与带 `log` 方法的 sink。
+ */
+/** ChannelLogSink 的 info/warn/error 方法接受单个 string */
+export function toLogger(sink) {
+    const prefix = "[xg_cwork_im]";
+    const s = sink;
+    const emitInfo = (msg) => {
+        if (typeof s?.info === "function") {
+            s.info(msg);
+            return;
+        }
+        if (typeof s?.log === "function") {
+            s.log(msg);
+            return;
+        }
+        console.log(`${prefix} ${msg}`);
+    };
+    const emitWarn = (msg) => {
+        if (typeof sink?.warn === "function") {
+            sink.warn(msg);
+            return;
+        }
+        console.warn(`${prefix} ${msg}`);
+    };
+    const emitError = (msg) => {
+        if (typeof sink?.error === "function") {
+            sink.error(msg);
+            return;
+        }
+        console.error(`${prefix} ${msg}`);
+    };
+    return {
+        info: emitInfo,
+        warn: emitWarn,
+        error: emitError,
+        debug: (msg) => {
+            if (typeof sink?.debug === "function")
+                sink.debug(msg);
+            else
+                emitInfo(msg);
+        },
+    };
+}
+//# sourceMappingURL=channel-log.js.map

package/dist/src/channel-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-log.js","sourceRoot":"","sources":["../../src/channel-log.ts"],"names":[],"mappings":"AAAA;;GAEG;AASH,qDAAqD;AACrD,MAAM,UAAU,QAAQ,CACpB,IAEe;IAEf,MAAM,MAAM,GAAG,eAAe,CAAC;IAC/B,MAAM,CAAC,GAAG,IAAiF,CAAC;IAE5F,MAAM,QAAQ,GAAG,CAAC,GAAW,EAAQ,EAAE;QACnC,IAAI,OAAO,CAAC,EAAE,IAAI,KAAK,UAAU,EAAE,CAAC;YAChC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACZ,OAAO;QACX,CAAC;QACD,IAAI,OAAO,CAAC,EAAE,GAAG,KAAK,UAAU,EAAE,CAAC;YAC/B,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACX,OAAO;QACX,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,GAAG,MAAM,IAAI,GAAG,EAAE,CAAC,CAAC;IACpC,CAAC,CAAC;IAEF,MAAM,QAAQ,GAAG,CAAC,GAAW,EAAQ,EAAE;QACnC,IAAI,OAAO,IAAI,EAAE,IAAI,KAAK,UAAU,EAAE,CAAC;YACnC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACf,OAAO;QACX,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,GAAG,EAAE,CAAC,CAAC;IACrC,CAAC,CAAC;IAEF,MAAM,SAAS,GAAG,CAAC,GAAW,EAAQ,EAAE;QACpC,IAAI,OAAO,IAAI,EAAE,KAAK,KAAK,UAAU,EAAE,CAAC;YACpC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAChB,OAAO;QACX,CAAC;QACD,OAAO,CAAC,KAAK,CAAC,GAAG,MAAM,IAAI,GAAG,EAAE,CAAC,CAAC;IACtC,CAAC,CAAC;IAEF,OAAO;QACH,IAAI,EAAE,QAAQ;QACd,IAAI,EAAE,QAAQ;QACd,KAAK,EAAE,SAAS;QAChB,KAAK,EAAE,CAAC,GAAG,EAAE,EAAE;YACX,IAAI,OAAO,IAAI,EAAE,KAAK,KAAK,UAAU;gBAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;;gBAClD,QAAQ,CAAC,GAAG,CAAC,CAAC;QACvB,CAAC;KACJ,CAAC;AACN,CAAC"}

package/dist/src/channel.d.ts

@@ -0,0 +1,17 @@
+/**
+ * XG-IM Channel Plugin — 组装层
+ *
+ * 配置与解析见 channel-config.ts；入站正文见 inbound-display.ts；
+ * @ 后派发见 dispatch-mentioned-reply.ts（入站消息直投 OpenClaw，
+ * 忙碌排队/插话由 OpenClaw 原生 messages.queue 处理，见 docs/插件实现逻辑说明.md）。
+ * 单账号 WebSocket 连接运行见 account-connection.ts。
+ *
+ * 账号生命周期由 openclaw 8.1 框架驱动：注册本通道插件后，框架按账号调用
+ * gateway.startAccount（→ account-reconciler.startAccountLifecycle）并持有每账号
+ * AbortSignal；配置变更走 reload.configPrefixes + accountScopedRestart 做账号级
+ * stop→start。插件 register 不再自启连接，避免同账号重复 WebSocket。
+ */
+import type { PluginRuntime, XgImChannelPlugin } from "./types.js";
+export declare function setXgImRuntime(rt: PluginRuntime): void;
+export declare const xgCworkImChannelPlugin: XgImChannelPlugin;
+//# sourceMappingURL=channel.d.ts.map

package/dist/src/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../src/channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAYH,OAAO,KAAK,EAAuB,aAAa,EAAmB,iBAAiB,EAAc,MAAM,YAAY,CAAC;AAMrH,wBAAgB,cAAc,CAAC,EAAE,EAAE,aAAa,GAAG,IAAI,CAEtD;AAsSD,eAAO,MAAM,sBAAsB,EAGnB,iBAAiB,CAAC"}

package/dist/src/channel.js

@@ -0,0 +1,272 @@
+/**
+ * XG-IM Channel Plugin — 组装层
+ *
+ * 配置与解析见 channel-config.ts；入站正文见 inbound-display.ts；
+ * @ 后派发见 dispatch-mentioned-reply.ts（入站消息直投 OpenClaw，
+ * 忙碌排队/插话由 OpenClaw 原生 messages.queue 处理，见 docs/插件实现逻辑说明.md）。
+ * 单账号 WebSocket 连接运行见 account-connection.ts。
+ *
+ * 账号生命周期由 openclaw 8.1 框架驱动：注册本通道插件后，框架按账号调用
+ * gateway.startAccount（→ account-reconciler.startAccountLifecycle）并持有每账号
+ * AbortSignal；配置变更走 reload.configPrefixes + accountScopedRestart 做账号级
+ * stop→start。插件 register 不再自启连接，避免同账号重复 WebSocket。
+ */
+import { randomUUID } from "node:crypto";
+import { buildChannelConfigSchema } from "openclaw/plugin-sdk/core";
+import { getToken } from "./auth.js";
+import { getXgImConfig, isConfigured, XgImConfigSchema } from "./channel-config.js";
+import { toLogger } from "./channel-log.js";
+import { sendReplyDeliverBlock, sendTextMessage } from "./send-service.js";
+import { toolJsonResult } from "./tool-json-result.js";
+import { accountReconciler } from "./account-reconciler.js";
+// ─── 全局 Runtime（在 index.ts 的 register 中注入）────────────────────────────
+let xgImRuntime = null;
+export function setXgImRuntime(rt) {
+    xgImRuntime = rt;
+}
+const MESSAGE_ACTION_CHANNEL_PREFIX = "xg_cwork_im:";
+function actionFirstNonEmptyString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+/** 从 message.action 参数中解析目标会话 ID（群/单聊共用 groupId）。 */
+function resolveActionSendTarget(params) {
+    for (const key of ["to", "target", "groupId", "gid", "chatId", "channelId", "conversationId"]) {
+        const raw = params[key];
+        const direct = actionFirstNonEmptyString(raw);
+        if (direct) {
+            return direct.startsWith(MESSAGE_ACTION_CHANNEL_PREFIX)
+                ? direct.slice(MESSAGE_ACTION_CHANNEL_PREFIX.length)
+                : direct;
+        }
+        if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+            const nested = raw;
+            const id = actionFirstNonEmptyString(nested.id ?? nested.groupId ?? nested.chatId ?? nested.conversationId);
+            if (id)
+                return id;
+        }
+    }
+    return undefined;
+}
+/** 从 message.action 参数中解析发送正文；模型可能用 message/text/content/SendMessage 等别名。 */
+function resolveActionSendText(params) {
+    for (const key of ["message", "text", "content", "body", "SendMessage"]) {
+        const value = actionFirstNonEmptyString(params[key]);
+        if (value)
+            return value;
+    }
+    return "";
+}
+function resolveActionSendAtUsers(params) {
+    for (const key of ["atUserIds", "atUsers"]) {
+        const raw = params[key];
+        if (!Array.isArray(raw))
+            continue;
+        const ids = raw
+            .map((entry) => (typeof entry === "string" ? entry.trim() : ""))
+            .filter((entry) => entry.length > 0);
+        if (ids.length > 0)
+            return ids;
+    }
+    return [];
+}
+/**
+ * 处理网关 message.action：
+ * - action != "send" → 明确不支持（supportsAction 在支持该字段的宿主上会先行拦下）。
+ * - dryRun 只做参数校验，不真正发送。
+ * - 发送成功/失败通过抛错或 ok 结果让宿主得到确定语义；不写任何会话去重状态。
+ */
+async function handleChannelMessageAction(ctx) {
+    const channel = "xg_cwork_im";
+    const log = toLogger(undefined);
+    if (String(ctx?.action ?? "") !== "send") {
+        throw new Error(`xg_cwork_im does not support message action "${String(ctx?.action ?? "")}"`);
+    }
+    const params = ctx?.params && typeof ctx.params === "object" && !Array.isArray(ctx.params)
+        ? ctx.params
+        : {};
+    const accountId = actionFirstNonEmptyString(ctx?.accountId ?? ctx?.requesterAccountId) ?? undefined;
+    const groupId = resolveActionSendTarget(params);
+    const text = resolveActionSendText(params);
+    const atUserIds = resolveActionSendAtUsers(params);
+    if (ctx?.dryRun === true) {
+        return toolJsonResult({
+            ok: true,
+            channel,
+            action: "send",
+            dryRun: true,
+            to: groupId ?? null,
+            textLen: text.length,
+        });
+    }
+    if (!groupId) {
+        throw new Error("xg_cwork_im action send requires a target groupId (params.to/groupId/target/chatId)");
+    }
+    if (!text) {
+        throw new Error("xg_cwork_im action send requires text content (params.message/text/content)");
+    }
+    if (!ctx?.cfg) {
+        throw new Error("xg_cwork_im action send missing runtime cfg");
+    }
+    try {
+        const config = getXgImConfig(ctx.cfg, accountId);
+        const identity = await getToken(config, log);
+        log.info(`[action] send via message.action to=${groupId} accountId=${accountId ?? "default"} textLen=${text.length}`);
+        await sendTextMessage(config, identity.token, groupId, text, atUserIds, log);
+        return toolJsonResult({
+            ok: true,
+            channel,
+            action: "send",
+            to: groupId,
+            sentBy: identity.userId,
+        });
+    }
+    catch (err) {
+        log.error(`[action] send failed to=${groupId} accountId=${accountId ?? "default"} err=${String(err)}`);
+        throw err;
+    }
+}
+function buildChannelMessageActions() {
+    return {
+        supportsAction: ({ action }) => action === "send",
+        handleAction: (ctx) => handleChannelMessageAction(ctx),
+    };
+}
+// ─── Channel Plugin 定义 ─────────────────────────────────────────────────────
+const xgCworkImChannelPluginBase = {
+    id: "xg_cwork_im",
+    meta: {
+        id: "xg_cwork_im",
+        label: "XG CWork IM",
+        selectionLabel: "XG CWork IM (工作说说)",
+        docsPath: "/channels/xg_cwork_im",
+        blurb: "工作说说 IM 机器人，通过 WebSocket 长连接接收 @ 消息。",
+        aliases: ["xg_cwork_im", "im"],
+    },
+    configSchema: buildChannelConfigSchema(XgImConfigSchema),
+    reload: {
+        configPrefixes: ["channels.xg_cwork_im"],
+        // openclaw 8.1+ 支持账号级 stop→start；SDK 类型尚未声明该字段，运行时属性存在即生效。
+        accountScopedRestart: true,
+    },
+    capabilities: {
+        chatTypes: ["direct", "group"],
+        reactions: false,
+        threads: false,
+        media: true,
+        nativeCommands: false,
+        blockStreaming: true,
+    },
+    config: {
+        listAccountIds: (cfg) => {
+            try {
+                const config = getXgImConfig(cfg);
+                const accounts = config.accounts;
+                if (accounts) {
+                    if (!Array.isArray(accounts) && typeof accounts === "object") {
+                        const keys = Object.keys(accounts).filter((k) => k !== "default");
+                        return keys;
+                    }
+                }
+                return isConfigured(cfg) ? ["default"] : [];
+            }
+            catch {
+                return [];
+            }
+        },
+        resolveAccount: (cfg, accountId) => {
+            const id = accountId || "default";
+            try {
+                const config = getXgImConfig(cfg, id);
+                return {
+                    accountId: id,
+                    config,
+                    enabled: config.enabled !== false,
+                    configured: Boolean((config.robotKey ?? config.appKey) && config.baseUrl),
+                    name: config.name ?? null,
+                };
+            }
+            catch {
+                return {
+                    accountId: id,
+                    config: {},
+                    enabled: false,
+                    configured: false,
+                    name: null,
+                };
+            }
+        },
+        defaultAccountId: () => "default",
+        isConfigured: (account) => account.configured,
+        describeAccount: (account) => ({
+            accountId: account.accountId,
+            name: account.config?.name ?? "xg_cwork_im",
+            enabled: account.enabled,
+            configured: account.configured,
+        }),
+    },
+    groups: {
+        resolveRequireMention: (params) => {
+            try {
+                const config = getXgImConfig(params.cfg, params.accountId);
+                return config?.groupPolicy !== "open";
+            }
+            catch {
+                return true;
+            }
+        },
+    },
+    outbound: {
+        deliveryMode: "direct",
+        resolveTarget: (params) => {
+            const trimmed = params.to?.trim();
+            if (!trimmed) {
+                return {
+                    ok: false,
+                    error: new Error("XG-IM message requires --to <groupId>"),
+                };
+            }
+            return { ok: true, to: trimmed };
+        },
+        sendText: async (ctx) => {
+            const { cfg, to, text, accountId, log: ctxLog } = ctx;
+            const log = toLogger(ctxLog);
+            const config = getXgImConfig(cfg, accountId);
+            const identity = await getToken(config, log);
+            await sendTextMessage(config, identity.token, to, text, [], log);
+            return {
+                channel: "xg_cwork_im",
+                messageId: randomUUID(),
+            };
+        },
+        sendMedia: async (ctx) => {
+            const { cfg, to, text, mediaUrl, accountId, log: ctxLog } = ctx;
+            const log = toLogger(ctxLog);
+            const config = getXgImConfig(cfg, accountId);
+            const identity = await getToken(config, log);
+            if (!mediaUrl?.trim()) {
+                await sendTextMessage(config, identity.token, to, text || "", [], log);
+                return { channel: "xg_cwork_im", messageId: randomUUID() };
+            }
+            await sendReplyDeliverBlock(config, identity.token, to, { text: text || "", mediaUrl: mediaUrl.trim() }, [], log, undefined, undefined);
+            return {
+                channel: "xg_cwork_im",
+                messageId: randomUUID(),
+            };
+        },
+    },
+    gateway: {
+        startAccount: async (ctx) => {
+            await accountReconciler.startAccountLifecycle(ctx);
+        },
+    },
+};
+// actions 属于 ChannelPlugin 的 message-action 面（宿主版本间字段/类型存在差异），
+// 通过 base + spread 合并，既能保留 base 的字面量类型校验，又避免 actions 类型代际差异破坏构建。
+export const xgCworkImChannelPlugin = {
+    ...xgCworkImChannelPluginBase,
+    actions: buildChannelMessageActions(),
+};
+//# sourceMappingURL=channel.js.map

package/dist/src/channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.js","sourceRoot":"","sources":["../../src/channel.ts"],"names":[],"mappings":"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"}

package/dist/src/connection-workspace-event.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=connection-workspace-event.test.d.ts.map

package/dist/src/connection-workspace-event.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-workspace-event.test.d.ts","sourceRoot":"","sources":["../../src/connection-workspace-event.test.ts"],"names":[],"mappings":""}

package/dist/src/connection-workspace-event.test.js

@@ -0,0 +1,74 @@
+import assert from "node:assert/strict";
+import { once } from "node:events";
+import { describe, it } from "node:test";
+import { WebSocketServer } from "ws";
+import { startWebSocket } from "./connection.js";
+import { OPENCLAW_WORKSPACE_EVENT_CMD } from "./workspace-event-protocol.js";
+const quietLog = {
+    info: () => undefined,
+    warn: () => undefined,
+    error: () => undefined,
+};
+describe("connection workspace event routing", () => {
+    it("routes workspace control messages without invoking the chat callback", async () => {
+        const server = new WebSocketServer({ port: 0 });
+        await once(server, "listening");
+        const address = server.address();
+        if (typeof address === "string" || address == null)
+            throw new Error("test server has no TCP port");
+        let chatCalls = 0;
+        let workspaceCalls = 0;
+        const handle = startWebSocket({
+            baseUrl: `http://127.0.0.1:${address.port}`,
+            wsBaseUrl: `ws://127.0.0.1:${address.port}`,
+            agentId: "main",
+            maxConnectionAttempts: 0,
+        }, "test-token", () => {
+            chatCalls += 1;
+        }, quietLog, {
+            onWorkspaceEvent: async (params) => {
+                workspaceCalls += 1;
+                return {
+                    _wsRelayId: params._wsRelayId,
+                    event: "TREE_RESULT",
+                    groupId: params.groupId,
+                    success: true,
+                    path: "",
+                    entries: [],
+                    nextCursor: null,
+                };
+            },
+        });
+        try {
+            const [socket] = await once(server, "connection");
+            const responsePromise = once(socket, "message");
+            socket.send(JSON.stringify({
+                cmd: OPENCLAW_WORKSPACE_EVENT_CMD,
+                params: {
+                    _wsRelayId: "relay-connection",
+                    event: "TREE_REQUEST",
+                    groupId: "42",
+                    workspace: {
+                        sourceType: "LOCAL",
+                        rootPath: "x",
+                        localRoot: { kind: "workspace_relative", path: "x" },
+                    },
+                    path: "x",
+                },
+            }));
+            const [raw] = await responsePromise;
+            const response = JSON.parse(raw.toString());
+            const params = response.params;
+            assert.equal(response.cmd, OPENCLAW_WORKSPACE_EVENT_CMD);
+            assert.equal(params._wsRelayId, "relay-connection");
+            assert.equal(params.event, "TREE_RESULT");
+            assert.equal(workspaceCalls, 1);
+            assert.equal(chatCalls, 0);
+        }
+        finally {
+            handle.stop();
+            await new Promise((resolve) => server.close(() => resolve()));
+        }
+    });
+});
+//# sourceMappingURL=connection-workspace-event.test.js.map

package/dist/src/connection-workspace-event.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-workspace-event.test.js","sourceRoot":"","sources":["../../src/connection-workspace-event.test.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,eAAe,EAAkB,MAAM,IAAI,CAAC;AAErD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAC;AAE7E,MAAM,QAAQ,GAAQ;IAClB,IAAI,EAAE,GAAG,EAAE,CAAC,SAAS;IACrB,IAAI,EAAE,GAAG,EAAE,CAAC,SAAS;IACrB,KAAK,EAAE,GAAG,EAAE,CAAC,SAAS;CACzB,CAAC;AAEF,QAAQ,CAAC,oCAAoC,EAAE,GAAG,EAAE;IAChD,EAAE,CAAC,sEAAsE,EAAE,KAAK,IAAI,EAAE;QAClF,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;QAChD,MAAM,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QAChC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;QACjC,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,IAAI,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;QAEnG,IAAI,SAAS,GAAG,CAAC,CAAC;QAClB,IAAI,cAAc,GAAG,CAAC,CAAC;QACvB,MAAM,MAAM,GAAG,cAAc,CACzB;YACI,OAAO,EAAE,oBAAoB,OAAO,CAAC,IAAI,EAAE;YAC3C,SAAS,EAAE,kBAAkB,OAAO,CAAC,IAAI,EAAE;YAC3C,OAAO,EAAE,MAAM;YACf,qBAAqB,EAAE,CAAC;SACb,EACf,YAAY,EACZ,GAAG,EAAE;YACD,SAAS,IAAI,CAAC,CAAC;QACnB,CAAC,EACD,QAAQ,EACR;YACI,gBAAgB,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;gBAC/B,cAAc,IAAI,CAAC,CAAC;gBACpB,OAAO;oBACH,UAAU,EAAE,MAAM,CAAC,UAAU;oBAC7B,KAAK,EAAE,aAAa;oBACpB,OAAO,EAAE,MAAM,CAAC,OAAO;oBACvB,OAAO,EAAE,IAAI;oBACb,IAAI,EAAE,EAAE;oBACR,OAAO,EAAE,EAAE;oBACX,UAAU,EAAE,IAAI;iBACnB,CAAC;YACN,CAAC;SACJ,CACJ,CAAC;QAEF,IAAI,CAAC;YACD,MAAM,CAAC,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,MAAM,EAAE,YAAY,CAAgB,CAAC;YACjE,MAAM,eAAe,GAAG,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;YAChD,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC;gBACvB,GAAG,EAAE,4BAA4B;gBACjC,MAAM,EAAE;oBACJ,UAAU,EAAE,kBAAkB;oBAC9B,KAAK,EAAE,cAAc;oBACrB,OAAO,EAAE,IAAI;oBACb,SAAS,EAAE;wBACP,UAAU,EAAE,OAAO;wBACnB,QAAQ,EAAE,GAAG;wBACb,SAAS,EAAE,EAAE,IAAI,EAAE,oBAAoB,EAAE,IAAI,EAAE,GAAG,EAAE;qBACvD;oBACD,IAAI,EAAE,GAAG;iBACZ;aACJ,CAAC,CAAC,CAAC;YACJ,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,eAAe,CAAC;YACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,CAA4B,CAAC;YACvE,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAiC,CAAC;YAE1D,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,4BAA4B,CAAC,CAAC;YACzD,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,EAAE,kBAAkB,CAAC,CAAC;YACpD,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;YAC1C,MAAM,CAAC,KAAK,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC;YAChC,MAAM,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;QAC/B,CAAC;gBAAS,CAAC;YACP,MAAM,CAAC,IAAI,EAAE,CAAC;YACd,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QACxE,CAAC;IACL,CAAC,CAAC,CAAC;AACP,CAAC,CAAC,CAAC"}

package/dist/src/connection.d.ts

@@ -0,0 +1,110 @@
+/**
+ * XG-IM WebSocket 连接管理模块
+ *
+ * 功能：
+ * - 建立 wss://<baseUrl>/ws-notify/websocket?accessToken=<token> 长连接
+ * - 接收 robotMention / groupMessage 并回调
+ * - 流式推送：BEGIN → 进度事件 →（可选 RUN_USAGE）→ FINISHED（无占位 ack；正文走 HTTP）
+ * - 指数退避 + 抖动的自动重连机制
+ * - 主动发送 WebSocket ping 保活，超时自动重连
+ */
+import type { Log } from "./auth.js";
+import type { ImStreamRunUsageData } from "./run-usage.js";
+import type { WsMessage, XgImConfig } from "./types.js";
+export type OnMessageCallback = (msg: WsMessage) => void;
+/** IM 下发的目录同步映射信令（与聊天消息分流） */
+export type OnSyncMappingCallback = (params: Record<string, unknown>) => void | Promise<void>;
+/** 工作区控制信令处理器；返回值会原样作为 openclawWorkspaceEvent.params 回传。 */
+export type OnWorkspaceEventCallback = (params: Record<string, unknown>) => Record<string, unknown> | Promise<Record<string, unknown>>;
+export declare const OPENCLAW_APPLY_SYNC_MAPPING_CMD = "openclawApplySyncMapping";
+export { OPENCLAW_WORKSPACE_EVENT_CMD } from "./workspace-event-protocol.js";
+export interface StartWebSocketHooks {
+    onSyncMapping?: OnSyncMappingCallback;
+    onWorkspaceEvent?: OnWorkspaceEventCallback;
+    /** 重连次数耗尽且未 stop 时回调（整机不再收 WS 入站） */
+    onReconnectExhausted?: (info: {
+        maxAttempts: number;
+        lastCloseCode?: number;
+        lastCloseReason?: string;
+    }) => void;
+}
+/** {@link ImStreamClient.start} 参数 */
+export interface ImStreamStartOpts {
+    groupId?: string;
+    toUserId?: string | null;
+    /** 触发本轮的用户入站消息 id（`robotMention.params.msgId`），用于 BEGIN 的 replyToMsgId。 */
+    replyToMsgId?: string;
+}
+/** {@link ImStreamClient.end} 参数 */
+export interface ImStreamEndContext {
+    groupId?: string;
+    replyToMsgId?: string;
+}
+/** 进度类 `params.event`（不经占位 ack；助手正文走 HTTP） */
+export type ImStreamProgressEventName = "TOOL_PHASE" | "PLAN_UPDATE" | "ITEM_UPDATE" | "RUN_EVENT" | "SUBAGENT_STAT" | "PLAN_STAT";
+export interface ImStreamProgressOpts {
+    groupId: string;
+    replyToMsgId: string;
+    event: ImStreamProgressEventName;
+    /** 主展示一行 */
+    displayText: string;
+    /** 可选：命令/路径等细节或输出摘要，默认最长 200 字 */
+    summary?: string;
+}
+export interface ImStreamSendEventOpts {
+    groupId: string;
+    replyToMsgId: string;
+    event: string;
+    data: Record<string, unknown>;
+}
+/** WS `im_stream_msg` 文本帧载荷（前端契约：cmd / params.event / params.data 字段与顺序逐字节稳定）。 */
+export interface ImStreamMessagePayload {
+    cmd: "im_stream_msg";
+    params: {
+        event: string;
+        data: Record<string, unknown>;
+    };
+}
+/**
+ * 构建 BEGIN 载荷。
+ * groupId / replyToMsgId 任一为空白时返回 null（对应原实现直接 return，不发帧）。
+ */
+export declare function buildBeginPayload(opts: ImStreamStartOpts): ImStreamMessagePayload | null;
+/**
+ * 构建进度事件载荷（TOOL_PHASE / PLAN_UPDATE / RUN_EVENT 等）。
+ * groupId / replyToMsgId / displayText 任一空白时返回 null；summary 超长裁剪为 200 字（… 结尾）。
+ */
+export declare function buildProgressPayload(opts: ImStreamProgressOpts): ImStreamMessagePayload | null;
+/** 构建 RUN_USAGE 载荷；groupId / replyToMsgId 任一空白时返回 null。 */
+export declare function buildRunUsagePayload(data: ImStreamRunUsageData): ImStreamMessagePayload | null;
+/** 构建自定义事件载荷（SUBAGENT_STAT / PLAN_STAT / ACTION_DISPATCH / CHAT_FILE 等）；空锚点时返回 null。 */
+export declare function buildSendEventPayload(opts: ImStreamSendEventOpts): ImStreamMessagePayload | null;
+/** 构建 FINISHED 载荷；groupId / replyToMsgId 任一空白时返回 null。 */
+export declare function buildFinishedPayload(reason: string, ctx?: ImStreamEndContext): ImStreamMessagePayload | null;
+/**
+ * 基于 WebSocket 的流式消息客户端（无占位 ack）。
+ *
+ * - start(): 发送 BEGIN
+ * - streamProgress(): 发送 TOOL_PHASE / PLAN_UPDATE / RUN_EVENT 等
+ * - streamUsage(): 发送 RUN_USAGE（一轮可选；在 FINISHED 之前）
+ * - sendEvent(): 发送自定义事件（如 SUBAGENT_STAT）
+ * - end(): 发送 FINISHED
+ */
+export interface ImStreamClient {
+    start: (opts: ImStreamStartOpts) => Promise<void>;
+    streamProgress: (opts: ImStreamProgressOpts) => Promise<void>;
+    streamUsage: (data: ImStreamRunUsageData) => Promise<void>;
+    sendEvent: (opts: ImStreamSendEventOpts) => Promise<void>;
+    end: (reason: string, ctx?: ImStreamEndContext) => Promise<void>;
+}
+/**
+ * 启动 WebSocket 连接并监听消息。
+ *
+ * @returns 一个 `stop()` 函数，调用后永久断开连接，不再重连。
+ */
+export declare function startWebSocket(config: XgImConfig, token: string, onMessage: OnMessageCallback, log: Log, hooks?: StartWebSocketHooks): {
+    stop: () => void;
+    streamClient: ImStreamClient;
+    isReconnectExhausted: () => boolean;
+};
+//# sourceMappingURL=connection.d.ts.map

package/dist/src/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/connection.ts"],"names":[],"mappings":"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"}