@xgjktech/xg_cwork_im 1.11.6 → 1.11.7

package/dist/src/channel.js

@@ -1,17 +1,21 @@
 /**
- * XG-IM Channel Plugin — 核心定义
+ * XG-IM Channel Plugin — 组装层
  *
- * 遵循 OpenClaw Channel Plugin 架构（参考 openclaw-channel-dingtalk）：
- * - config   : 账户解析
- * - outbound : AI 回复发送
- * - gateway  : 启动 WebSocket 长连接，接收 robotMention 消息后通过
- *              PluginRuntime 路由给 OpenClaw 处理
+ * 配置与解析见 channel-config.ts；入站正文见 inbound-display.ts；
+ * 排队调度见 gateway-session-queue.ts；@ 后派发见 dispatch-mentioned-reply.ts。
  */
 import { randomUUID } from "node:crypto";
+import { resolveAgentWorkspaceDir } from "openclaw/plugin-sdk/memory-core-host-engine-foundation";
 import { buildChannelConfigSchema } from "openclaw/plugin-sdk/core";
-import { z } from "zod";
 import { clearTokenCache, getToken } from "./auth.js";
+import { getXgImConfig, isConfigured, resolveInboundCommandAuthorized, XgImConfigSchema, } from "./channel-config.js";
+import { parseRobotMentionAgentContext } from "./agent-context-types.js";
+import { resolveInboundGroupSystemPrompt } from "./resolve-inbound-group-prompt.js";
+import { toLogger } from "./channel-log.js";
+import { applySyncMappingFromWsParams } from "./apply-sync-mapping.js";
 import { startWebSocket } from "./connection.js";
+import { createRunWithSessionQueue } from "./gateway-session-queue.js";
+import { buildInboundDisplayText, buildUntrustedContext, collectFileItems, isActuallyMentioned, isBypassQueueStopMessage, mediaFieldsFromFileItems, } from "./inbound-display.js";
 import { normalizeInboundWorkspaceSubdir, saveInboundFilesToWorkspace } from "./inbound-media-local.js";
 import { sendReplyDeliverBlock, sendTextMessage } from "./send-service.js";
 // ─── 全局 Runtime（在 index.ts 的 register 中注入）────────────────────────────
@@ -24,500 +28,6 @@ function getXgImRuntime() {
         throw new Error("[cwork_im] Plugin runtime not initialized");
     return xgImRuntime;
 }
-// ─── 配置 Schema ──────────────────────────────────────────────────────────────
-const XgImAccountConfigSchema = z.object({
-    // 注意：为了兼容 OpenClaw doctor 生成的 accounts.default（仅包含默认项，不含 appKey/robotKey），这里先放宽为 optional，
-    // 然后在 XgImConfigSchema.superRefine 中强制校验：除 default 之外的账号必须提供 robotKey 或 appKey。
-    robotKey: z.string().min(1).optional(),
-    appKey: z.string().min(1).optional(),
-    agentId: z.string().optional().default("main"),
-    name: z.string().optional(),
-    groupPolicy: z.enum(["open", "mention"]).optional().default("mention"),
-    fileUploadFormField: z.string().min(1).optional(),
-    maxAttachmentBytes: z.number().int().positive().optional(),
-    inboundMediaWorkspaceSubdir: z.string().optional(),
-    inboundMediaOpenClawPath: z.enum(["workspaceRelative", "absoluteFileUrl"]).optional(),
-    inboundMediaSandboxRootPrefix: z.string().optional(),
-    systemPrompt: z.string().optional(),
-    maxPendingMessages: z.number().int().min(0).optional(),
-});
-const XgImConfigSchema = z.object({
-    robotKey: z.string().optional(),
-    appKey: z.string().optional(),
-    agentId: z.string().optional().default("main"),
-    baseUrl: z.string().url("baseUrl must be a valid URL"),
-    wsBaseUrl: z.string().url("wsBaseUrl must be a valid URL").optional(),
-    enabled: z.boolean().optional().default(true),
-    name: z.string().optional(),
-    groupPolicy: z.enum(["open", "mention"]).optional().default("mention"),
-    allowFrom: z.array(z.string()).optional().default([]),
-    debug: z.boolean().optional().default(false),
-    maxConnectionAttempts: z.number().int().positive().optional().default(10),
-    initialReconnectDelay: z.number().int().positive().optional().default(1_000),
-    maxReconnectDelay: z.number().int().positive().optional().default(60_000),
-    reconnectJitter: z.number().min(0).max(1).optional().default(0.3),
-    fileUploadFormField: z.string().min(1).optional(),
-    maxAttachmentBytes: z.number().int().positive().optional(),
-    /**
-     * 非空时：将入站附件下载到 `resolveAgentWorkspaceDir(cfg)` 下该相对子目录，
-     * 再向 OpenClaw 传 workspace 相对路径或 file://（见 inboundMediaOpenClawPath、inbound-media-local）。
-     */
-    inboundMediaWorkspaceSubdir: z.string().optional(),
-    inboundMediaOpenClawPath: z.enum(["workspaceRelative", "absoluteFileUrl"]).optional(),
-    /** 沙箱内 workspace 挂载根，如 `/workspace`；与 workspaceRelative 组合生成绝对引用 */
-    inboundMediaSandboxRootPrefix: z.string().optional(),
-    /** 群聊入站时写入 OpenClaw `GroupSystemPrompt`（与 accounts 内字段合并规则见 getXgImConfig） */
-    systemPrompt: z.string().optional(),
-    /** 每个会话（群组）最多可排队等待处理的消息数量（默认 5，设 0 表示不排队直接通知丢弃） */
-    maxPendingMessages: z.number().int().min(0).optional().default(5),
-    // 多账户：对象 map（key 为 accountId）
-    accounts: z.record(z.string(), XgImAccountConfigSchema).optional(),
-}).superRefine((val, ctx) => {
-    const badSubdir = (s) => typeof s === "string" && s.trim().length > 0 && normalizeInboundWorkspaceSubdir(s) == null;
-    if (badSubdir(val.inboundMediaWorkspaceSubdir)) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            path: ["inboundMediaWorkspaceSubdir"],
-            message: "inboundMediaWorkspaceSubdir must be a relative path under workspace (no .., no absolute path)",
-        });
-    }
-    const badSandboxPrefix = (s) => typeof s === "string" && s.trim().length > 0 && !s.trim().startsWith("/");
-    if (badSandboxPrefix(val.inboundMediaSandboxRootPrefix)) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            path: ["inboundMediaSandboxRootPrefix"],
-            message: "inboundMediaSandboxRootPrefix must be empty or an absolute path such as /workspace",
-        });
-    }
-    const accounts = val.accounts;
-    if (!accounts)
-        return;
-    for (const [key, acc] of Object.entries(accounts)) {
-        if (key === "default")
-            continue;
-        if (!acc || typeof acc !== "object")
-            continue;
-        if (!acc.robotKey && !acc.appKey) {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                path: ["accounts", key, "robotKey"],
-                message: "robotKey (or appKey) is required for account entries (except accounts.default)",
-            });
-        }
-        if (badSubdir(acc.inboundMediaWorkspaceSubdir)) {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                path: ["accounts", key, "inboundMediaWorkspaceSubdir"],
-                message: "inboundMediaWorkspaceSubdir must be a relative path under workspace (no .., no absolute path)",
-            });
-        }
-        if (badSandboxPrefix(acc.inboundMediaSandboxRootPrefix)) {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                path: ["accounts", key, "inboundMediaSandboxRootPrefix"],
-                message: "inboundMediaSandboxRootPrefix must be empty or an absolute path such as /workspace",
-            });
-        }
-    }
-});
-// ─── 辅助函数 ─────────────────────────────────────────────────────────────────
-/**
- * 规范化 key 字段：优先取 robotKey，没有则取 appKey，统一写入 appKey。
- * 这样下游代码（auth.ts 等）只需读 config.appKey，无需感知 robotKey 的存在。
- */
-function normalizeRobotKey(config) {
-    const resolved = config.robotKey ?? config.appKey;
-    if (resolved === config.appKey)
-        return config;
-    return { ...config, appKey: resolved };
-}
-/** 从顶层 cfg 中取出 XgImConfig，支持多账户（README：channels.xg_cwork_im） */
-function getXgImConfig(cfg, accountId) {
-    const raw = cfg?.channels?.xg_cwork_im;
-    if (!raw)
-        throw new Error("[cwork_im] channels.xg_cwork_im config not found");
-    const accounts = raw.accounts;
-    const accountMap = accounts && typeof accounts === "object" && !Array.isArray(accounts)
-        ? accounts
-        : undefined;
-    const defaults = accountMap?.default ? { ...accountMap.default } : undefined;
-    // 指定了具体账户 ID 时，优先合并对应账户配置
-    if (accountId && accountId !== "default" && accountMap) {
-        const sub = accountMap[accountId];
-        if (sub)
-            return normalizeRobotKey({ ...raw, ...(defaults ?? {}), ...sub });
-    }
-    // 没有指定 accountId（如 Cron outbound 场景），自动 fallback 到「第一个账户」
-    // 避免顶层 raw 没有 appKey/robotKey 时 getToken 失败
-    if (accountMap && !raw.appKey && !raw.robotKey) {
-        const firstKey = Object.keys(accountMap).find((k) => k !== "default");
-        const first = firstKey ? accountMap[firstKey] : undefined;
-        if (first)
-            return normalizeRobotKey({ ...raw, ...(defaults ?? {}), ...first });
-    }
-    return normalizeRobotKey(raw);
-}
-/**
- * 合并 `channels.xg_cwork_im` 顶层、`accounts.default`、以及 `accounts.<accountId>` 后的 `systemPrompt`，
- * 写入 OpenClaw 入站 `GroupSystemPrompt`（与 getXgImConfig 的非 default 账户合并方式一致；对 default 账户会合并 default 片段）。
- */
-function resolveXgImGroupSystemPrompt(cfg, accountId) {
-    try {
-        const raw = cfg?.channels?.xg_cwork_im;
-        if (!raw)
-            return undefined;
-        const accountMap = raw.accounts && typeof raw.accounts === "object" && !Array.isArray(raw.accounts)
-            ? raw.accounts
-            : undefined;
-        const defaults = accountMap?.default ? { ...accountMap.default } : {};
-        const base = { ...raw, ...defaults };
-        let merged = base;
-        if (accountId && accountId !== "default" && accountMap?.[accountId]) {
-            merged = { ...base, ...accountMap[accountId] };
-        }
-        const t = merged.systemPrompt?.trim();
-        return t || undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-function isConfigured(cfg) {
-    try {
-        const c = getXgImConfig(cfg);
-        return Boolean(c?.appKey && c?.baseUrl);
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * OpenClaw 对入站命令：`CommandAuthorized === undefined` 会按 false 处理，文本 /command 会被静默忽略（仍走普通 AI）。
- * 见 openclaw LINE #26996 等修复。此处与 channels.xg_cwork_im.allowFrom 对齐；allowFrom 为空表示不限制发送者。
- */
-function isSenderInXgImAllowFrom(config, senderId) {
-    const allow = config.allowFrom ?? [];
-    if (allow.length === 0)
-        return true;
-    const id = senderId?.trim();
-    if (!id)
-        return false;
-    return allow.includes(id);
-}
-function resolveInboundCommandAuthorized(rt, cfg, p) {
-    const r = rt;
-    const fn = r?.channel?.commands?.resolveControlCommandGate;
-    if (typeof fn === "function") {
-        try {
-            const out = fn({
-                cfg,
-                channel: "xg_cwork_im",
-                accountId: p.accountId,
-                senderId: p.senderId ?? "",
-                chatType: "group",
-            });
-            if (typeof out === "boolean")
-                return out;
-            if (out && typeof out === "object" && "commandAuthorized" in out) {
-                return Boolean(out.commandAuthorized);
-            }
-        }
-        catch {
-            /* 回退到 allowFrom */
-        }
-    }
-    return isSenderInXgImAllowFrom(p.config, p.senderId);
-}
-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);
-        },
-    };
-}
-// ─── WebSocket 入站：纯函数与 @ 后派发 ───────────────────────────────────────
-function collectFileItems(msgContent) {
-    // 保留有 url（需下载/引用的媒体）或有 content（IM 侧已内嵌解析文本）的项；两者均为空的占位项丢弃。
-    return (msgContent?.files ?? []).filter((f) => f.url?.trim() || f.content?.trim());
-}
-function buildInboundDisplayText(msgContent, fileItems) {
-    let rawText = msgContent?.text ?? "";
-    if (fileItems.length > 0) {
-        const lines = fileItems.map((f) => {
-            const name = f.name?.trim() || f.fileId || "未命名文件";
-            return `- \`${name}\``;
-        });
-        const block = `**附件（${fileItems.length}）**\n${lines.join("\n")}`;
-        rawText = rawText.trim() ? `${rawText.trim()}\n\n${block}` : block;
-        const parsedParts = fileItems
-            .map((f) => {
-            const c = f.content?.trim();
-            if (!c)
-                return null;
-            const name = f.name?.trim() || f.fileId || "未命名文件";
-            return `### ${name}\n\n${c}`;
-        })
-            .filter((x) => x != null);
-        if (parsedParts.length > 0) {
-            const parsedBlock = `**附件解析内容**\n\n${parsedParts.join("\n\n")}`;
-            rawText = `${rawText.trim()}\n\n${parsedBlock}`;
-        }
-        const urlGuard = "**附件 URL 使用约束**\n" +
-            "处理附件时必须逐字原样使用消息中提供的完整 URL；禁止修改、删除或重排任何 query 参数。";
-        rawText = `${rawText.trim()}\n\n${urlGuard}`;
-    }
-    return rawText;
-}
-function isActuallyMentioned(msg, params, bot, rawTextForLegacy) {
-    const mentions = params.mentions;
-    const isMentioned = Array.isArray(mentions) && (mentions.includes(bot.userId) || mentions.includes("all"));
-    const isLegacyMentioned = msg.cmd === "robotMention" &&
-        (!params.mentions || params.mentions.length === 0) &&
-        new RegExp(`@${bot.name}\\b`).test(rawTextForLegacy);
-    return isMentioned || isLegacyMentioned;
-}
-function mediaFieldsFromFileItems(fileItems) {
-    // 只传有实际 url 的项；content-only 项无需 MediaPath（内容已通过 buildInboundDisplayText 内联传入）。
-    // 不传 MediaType(s)：预签名 URL 的 query 中常含 response-content-type，额外给 MediaType 容易导致模型改写 URL 使签名失效。
-    const urlItems = fileItems.filter((f) => f.url?.trim());
-    if (urlItems.length === 0)
-        return {};
-    if (urlItems.length === 1) {
-        return {
-            MediaPath: urlItems[0].url,
-        };
-    }
-    return {
-        MediaPaths: urlItems.map((f) => f.url),
-    };
-}
-/** ext / 用户 background / 附件元数据（不含下载 URL，避免预签名链过长；URL 已在入站 MediaPath(s)） */
-function buildUntrustedContext(msgExt, senderBackground, fileItems) {
-    const parts = [];
-    if (msgExt)
-        parts.push(JSON.stringify(msgExt));
-    if (senderBackground)
-        parts.push(String(senderBackground));
-    if (fileItems.length > 0) {
-        const summary = fileItems.map((f) => ({
-            name: f.name ?? null,
-            format: f.format ?? null,
-            fileId: f.fileId ?? null,
-            size: f.size ?? null,
-            contentChars: f.content?.trim() ? f.content.trim().length : null,
-        }));
-        parts.push(`xg_cwork_im.attachments: ${JSON.stringify(summary)}`);
-    }
-    return parts.length > 0 ? parts : undefined;
-}
-function buildTargetReplyMeta(params) {
-    return {
-        targetMsgId: params.msgId,
-        targetUserId: params.userInfo?.id ?? "",
-        targetUserName: params.userInfo?.name ?? "未知用户",
-        previewText: params.msgContent?.text ?? "",
-    };
-}
-/** 流式 START → dispatch → 必发 END；首包超时走 HTTP 覆盖占位 */
-async function dispatchMentionedReply(args) {
-    const { rt, cfg, config, log, logPrefix, route, inboundCtx, params, currentIdentity, streamClient } = args;
-    log.info(`${logPrefix} [dispatch] Dispatching to OpenClaw AI, sessionKey=${route.sessionKey}`);
-    let isFirstReply = true;
-    const dispatchStart = Date.now();
-    const { msgId: ackPlaceholderMsgId } = await streamClient.start({
-        groupId: params.groupId,
-    });
-    const ackRawStr = ackPlaceholderMsgId == null ? "" : typeof ackPlaceholderMsgId === "string" ? ackPlaceholderMsgId : String(ackPlaceholderMsgId);
-    const streamMsgId = ackRawStr.trim();
-    log.info(`${logPrefix} [stream] START acknowledged placeholder rawLen=${ackRawStr.length} trimmedLen=${streamMsgId.length} ` +
-        `summary=${streamMsgId.length === 0 ? "(empty)" : streamMsgId.length <= 28 ? streamMsgId : `${streamMsgId.slice(0, 14)}…${streamMsgId.slice(-8)}(len=${streamMsgId.length})`}`);
-    if (!streamMsgId) {
-        log.warn(`${logPrefix} [stream] WARNING: START ack msgId empty after trim — HTTP cannot merge streaming placeholder; IM likely shows「AI未响应」plus a separate reply bubble`);
-    }
-    let hasFirstReply = false;
-    const firstReplyTimeoutMs = config.firstReplyTimeoutMs ?? 30 * 60_000;
-    const timeoutLabel = `${logPrefix} [stream] First reply timeout after ${firstReplyTimeoutMs}ms, updating thinking message as error`;
-    const firstReplyTimeout = setTimeout(async () => {
-        if (hasFirstReply)
-            return;
-        log.warn(timeoutLabel);
-        try {
-            const reply = buildTargetReplyMeta(params);
-            const timeoutText = "当前请求处理超时，请稍后重试。";
-            await sendTextMessage(config, currentIdentity.token, params.groupId, timeoutText, [reply.targetUserId], log, streamMsgId, reply);
-            // 标记已发送，让 finally 以 reason=stop 结束，避免后台再显示"AI未响应"
-            hasFirstReply = true;
-            log.info(`${logPrefix} [send] Timeout reply sent via HTTP: groupId=${params.groupId} msgId=${streamMsgId} text="${timeoutText}"`);
-        }
-        catch (err) {
-            log.error(`${logPrefix} [timeout] Failed to send timeout reply: ${String(err)}`);
-        }
-    }, firstReplyTimeoutMs);
-    let deliverInvokeCount = 0;
-    let deliverCallCount = 0;
-    let deliverSkippedCount = 0;
-    let dispatchError = undefined;
-    // 捕获 deliver 抛出后被 dispatcher 静默吞掉的错误：postImMessage 已带 5 次重试，
-    // 进到这里说明所有重试均失败（IM 后台不可用 / 4xx / resultCode 业务错误等），需要让 finally 走兜底分支
-    let lastDeliverError = undefined;
-    try {
-        await rt.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
-            ctx: inboundCtx,
-            cfg,
-            /**
-             * OpenClaw 2026.x：群聊默认 `messages.groupChat.visibleReplies` / `messages.visibleReplies` 未为 `automatic` 时，
-             * 会启用 `message_tool_only`，从而 suppressDelivery=true，不向 channel ReplyDispatcher（本插件 deliver）
-             * 投递 block/final；模型仍会运行且网页端可读会话 transcript，表现为 IM invoke=0、占位 END no_reply。
-             * 工作说说必须由本插件回 HTTP，此处强制 automatic。
-             */
-            replyOptions: {
-                sourceReplyDeliveryMode: "automatic",
-            },
-            dispatcherOptions: {
-                responsePrefix: "",
-                // Logged when normalizeReplyPayload decides to skip a payload (e.g. heartbeat, silent token, empty).
-                onSkip: (payload, meta) => {
-                    deliverSkippedCount++;
-                    log.info(`${logPrefix} [deliver] Payload skipped by normalizer kind=${meta.kind} reason=${meta.reason}`);
-                },
-                // Logged when deliver throws and the dispatcher catches it (error would otherwise be silently dropped).
-                onError: (err, meta) => {
-                    lastDeliverError = err;
-                    log.error(`${logPrefix} [deliver] Dispatcher caught unhandled error kind=${meta.kind}: ${String(err)}`);
-                },
-                deliver: async (payload) => {
-                    try {
-                        deliverInvokeCount++;
-                        const textPart = (payload.markdown || payload.text || "").trim();
-                        const hasMedia = Boolean(payload.mediaUrl?.trim()) ||
-                            Boolean(payload.mediaUrls?.some((u) => typeof u === "string" && u.trim()));
-                        const textPreview = textPart.length > 120 ? `${textPart.slice(0, 120)}…(len=${textPart.length})` : textPart;
-                        log.info(`${logPrefix} [deliver] invoke #${deliverInvokeCount} isThinking=${payload.isThinking ?? false} ` +
-                            `textLen=${textPart.length} hasMedia=${hasMedia} mediaUrl=${Boolean(payload.mediaUrl?.trim())} ` +
-                            `preview=${JSON.stringify(textPreview || "(empty)")}`);
-                        if (!textPart && !(hasMedia && !payload.isThinking)) {
-                            log.info(`${logPrefix} [deliver] Payload has no sendable content, skipping` +
-                                ` (isThinking=${payload.isThinking ?? false} hasMedia=${hasMedia})`);
-                            return;
-                        }
-                        deliverCallCount++;
-                        if (isFirstReply) {
-                            const ttfr = Date.now() - dispatchStart;
-                            log.info(`${logPrefix} [deliver] First response block received from AI (TTFB: ${ttfr}ms)`);
-                            isFirstReply = false;
-                        }
-                        const reply = buildTargetReplyMeta(params);
-                        const atIds = [reply.targetUserId];
-                        if (!hasFirstReply) {
-                            clearTimeout(firstReplyTimeout);
-                            log.info(`${logPrefix} [deliver] First HTTP will merge streaming placeholder msgId=${streamMsgId.length > 0 ? `yes(len=${streamMsgId.length})` : "NO(empty)"}`);
-                            await sendReplyDeliverBlock(config, currentIdentity.token, params.groupId, payload, atIds, log, streamMsgId, reply);
-                            hasFirstReply = true; // set after successful send
-                            const preview = textPart.length > 80 ? `${textPart.slice(0, 80)}...` : textPart || "[media]";
-                            log.info(`${logPrefix} [send] First reply sent via HTTP: groupId=${params.groupId} msgId=${streamMsgId} preview="${preview}"`);
-                            return;
-                        }
-                        await sendReplyDeliverBlock(config, currentIdentity.token, params.groupId, payload, atIds, log, undefined, reply);
-                        const preview = textPart.length > 80 ? `${textPart.slice(0, 80)}...` : textPart || "[media]";
-                        log.info(`${logPrefix} [send] Additional reply sent via HTTP: groupId=${params.groupId} preview="${preview}"`);
-                    }
-                    catch (err) {
-                        log.error(`${logPrefix} [deliver] Reply deliver failed: ${String(err)}`);
-                        throw err;
-                    }
-                },
-            },
-        });
-        log.info(`${logPrefix} [dispatch] Dispatch completed for sessionKey=${route.sessionKey}` +
-            ` (invoke=${deliverInvokeCount} delivered=${deliverCallCount} skipped=${deliverSkippedCount})`);
-        if (deliverInvokeCount === 0) {
-            log.warn(`${logPrefix} [dispatch] OpenClaw never invoked channel deliver() for this turn — ` +
-                `this plugin will not POST /im/message/send; IM「收到消息」若存在，多半来自占位/END 或其它通道，而非本插件 HTTP 合并`);
-        }
-        else if (deliverCallCount === 0) {
-            log.warn(`${logPrefix} [dispatch] deliver() invoked ${deliverInvokeCount} time(s) but none had sendable text/media — ` +
-                `check model output (thinking-only / empty blocks) or OpenClaw normalizer`);
-        }
-    }
-    catch (dispatchErr) {
-        dispatchError = dispatchErr;
-        log.error(`${logPrefix} [dispatch] Dispatch failed (invoke=${deliverInvokeCount} delivered=${deliverCallCount} skipped=${deliverSkippedCount}): ${String(dispatchErr)}`);
-    }
-    finally {
-        clearTimeout(firstReplyTimeout);
-        // 兜底原则：
-        // - 有"实际错误"（dispatch 自身异常 / deliver 全部重试后仍失败）且尚未发过任何消息
-        //   → 主动告知用户，以 reason=stop 结束（后台信任已发消息）。
-        // - 无错误也无回复（AI 输出为空 / 全部被 normalizer skip / /reset 类静默命令）
-        //   → 以 reason=no_reply 结束，由后台展示"AI未响应"。
-        if (!hasFirstReply) {
-            const reportableError = dispatchError ?? lastDeliverError;
-            if (reportableError !== undefined) {
-                const errSource = dispatchError !== undefined ? "dispatch" : "deliver";
-                log.warn(`${logPrefix} [dispatch] ${errSource} error with no prior reply` +
-                    ` (invoke=${deliverInvokeCount} delivered=${deliverCallCount} skipped=${deliverSkippedCount}), sending error notice`);
-                const replyMeta = buildTargetReplyMeta(params);
-                try {
-                    await sendTextMessage(config, currentIdentity.token, params.groupId, `当前请求处理时出现异常，请稍后重试。\n错误信息：${String(reportableError)}`, [replyMeta.targetUserId], log, streamMsgId, replyMeta);
-                    hasFirstReply = true;
-                }
-                catch (fallbackErr) {
-                    log.error(`${logPrefix} [dispatch] Failed to send error notice (${errSource} error): ${String(fallbackErr)}`);
-                }
-            }
-            else {
-                log.warn(`${logPrefix} [dispatch] No reply was sent to user` +
-                    ` (invoke=${deliverInvokeCount} delivered=${deliverCallCount} skipped=${deliverSkippedCount}), ending with reason=no_reply` +
-                    (deliverInvokeCount === 0
-                        ? " — plugin did not run POST /im/message/send this turn"
-                        : ""));
-            }
-        }
-        // reason=stop：已通过 HTTP 发送了至少一条回复（含兜底错误消息），后台信任已有消息。
-        // reason=no_reply：本次无任何回复且无异常，后台凭此展示"AI未响应"。
-        const endReason = hasFirstReply ? "stop" : "no_reply";
-        try {
-            await streamClient.end(streamMsgId, endReason);
-            log.info(`${logPrefix} [stream] END sent: msgId=${streamMsgId} reason=${endReason}`);
-        }
-        catch (endErr) {
-            log.error(`${logPrefix} [stream] END failed (msgId=${streamMsgId}): ${String(endErr)}`);
-        }
-    }
-}
 // ─── Channel Plugin 定义 ─────────────────────────────────────────────────────
 export const xgCworkImChannelPlugin = {
     id: "xg_cwork_im",
@@ -529,8 +39,6 @@ export const xgCworkImChannelPlugin = {
         blurb: "工作说说 IM 机器人，通过 WebSocket 长连接接收 @ 消息。",
         aliases: ["xg_cwork_im", "im"],
     },
-    // 双重类型转换绕过 zod v3/v4 的 TS 类型不兼容
-    // buildChannelConfigSchema 会将 schema 包装成可序列化的形式，避免 DataCloneError
     configSchema: buildChannelConfigSchema(XgImConfigSchema),
     capabilities: {
         chatTypes: ["group"],
@@ -541,7 +49,6 @@ export const xgCworkImChannelPlugin = {
         blockStreaming: false,
     },
     reload: { configPrefixes: ["channels.xg_cwork_im"] },
-    // ── 账户配置 ────────────────────────────────────────────────────────────────
     config: {
         listAccountIds: (cfg) => {
             try {
@@ -549,7 +56,6 @@ export const xgCworkImChannelPlugin = {
                 const accounts = config.accounts;
                 if (accounts) {
                     if (!Array.isArray(accounts) && typeof accounts === "object") {
-                        // 推荐写法：对象 key 作为 accountId
                         const keys = Object.keys(accounts).filter((k) => k !== "default");
                         return keys;
                     }
@@ -568,7 +74,7 @@ export const xgCworkImChannelPlugin = {
                     accountId: id,
                     config,
                     enabled: config.enabled !== false,
-                    configured: Boolean(config.appKey && config.baseUrl),
+                    configured: Boolean((config.robotKey ?? config.appKey) && config.baseUrl),
                     name: config.name ?? null,
                 };
             }
@@ -582,8 +88,6 @@ export const xgCworkImChannelPlugin = {
                 };
             }
         },
-        // 注意：OpenClaw 可能在缺省路由时使用 defaultAccountId。
-        // 我们使用 "default" 作为别名：getXgImConfig 会自动 fallback 到第一个非 default 的真实账号。
         defaultAccountId: () => "default",
         isConfigured: (account) => account.configured,
         describeAccount: (account) => ({
@@ -593,7 +97,6 @@ export const xgCworkImChannelPlugin = {
             configured: account.configured,
         }),
     },
-    // ── 群聊设置 ─────────────────────────────────────────────────────────────────
     groups: {
         resolveRequireMention: (params) => {
             try {
@@ -601,11 +104,10 @@ export const xgCworkImChannelPlugin = {
                 return config?.groupPolicy !== "open";
             }
             catch {
-                return true; // 默认需要 @
+                return true;
             }
         },
     },
-    // ── 出站消息（openclaw 主动发送时调用）────────────────────────────────────────
     outbound: {
         deliveryMode: "direct",
         resolveTarget: (params) => {
@@ -629,7 +131,6 @@ export const xgCworkImChannelPlugin = {
                 messageId: randomUUID(),
             };
         },
-        /** 出站带媒体：上传资源后发 FILE，与网关 deliver 逻辑一致（OpenClaw 要求与 sendText 同时实现） */
         sendMedia: async (ctx) => {
             const { cfg, to, text, mediaUrl, accountId, log: ctxLog } = ctx;
             const log = toLogger(ctxLog);
@@ -646,27 +147,22 @@ export const xgCworkImChannelPlugin = {
             };
         },
     },
-    // ── 网关（WebSocket 长连接）─────────────────────────────────────────────────
     gateway: {
         startAccount: async (ctx) => {
             const account = ctx.account;
             const config = account.config;
             const log = toLogger(ctx.log);
             const logPrefix = `[${account.accountId}:${config.agentId || "main"}]`;
-            if (!config.appKey || !config.baseUrl) {
-                throw new Error(`${logPrefix} appKey and baseUrl are required in config`);
+            if (!(config.robotKey ?? config.appKey) || !config.baseUrl) {
+                throw new Error(`${logPrefix} robotKey and baseUrl are required in config`);
             }
             log.info(`${logPrefix} Starting xg-cwork-im channel...`);
-            // 1. 获取机器人 token（有效期一年，缓存后无需重复请求）
             const identity = await getToken(config, log);
-            // 2. 获取 PluginRuntime（用于路由消息给 OpenClaw）
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const rt = getXgImRuntime();
-            // 3. 若 abort 信号已触发则不启动
             if (ctx.abortSignal?.aborted) {
                 throw new Error(`${logPrefix} Connection aborted before start`);
             }
-            // 4. 消息去重（按账户隔离）
             const processedMsgIds = new Set();
             const MSG_DEDUP_MAX = 1_000;
             const isDuplicate = (msgId) => {
@@ -683,74 +179,13 @@ export const xgCworkImChannelPlugin = {
                 processedMsgIds.add(msgId);
                 return false;
             };
-            const busySessions = new Set();
-            const sessionQueues = new Map();
-            const maxPendingMsgs = config.maxPendingMessages ?? 5;
-            /**
-             * 将一次"提到我"的派发请求提交给队列调度器。
-             * - 若当前会话空闲：直接调用 dispatchMentionedReply。
-             * - 若当前会话忙碌：通知用户已排队，然后入队；上一条处理完成后自动出队执行。
-             * - 若队列已满（maxPendingMsgs > 0）：通知用户并丢弃。
-             * - maxPendingMsgs = 0：禁用排队，直接通知用户稍后再试。
-             */
-            const runWithSessionQueue = async (sessionKey, pending, streamClient) => {
-                if (busySessions.has(sessionKey)) {
-                    // 注意：JS 单线程，此处到第一个 await 之间不会被打断，所以队列长度判断和 push 均是原子的。
-                    // 必须在任何 await 之前完成 push，否则并发进入的消息会读到相同的 queue.length，
-                    // 导致多条消息计算出相同的队列位置（重复通知"第 1 位"等竞态问题）。
-                    const queue = sessionQueues.get(sessionKey) ?? [];
-                    if (maxPendingMsgs === 0 || queue.length >= maxPendingMsgs) {
-                        const reason = maxPendingMsgs === 0
-                            ? "当前不支持任务排队，请等待处理完成后再发送。"
-                            : `当前任务队列已满（最多 ${maxPendingMsgs} 条），请等待处理完成后再重新发送。`;
-                        log.warn(`${logPrefix} [queue] Session ${sessionKey} busy & queue full/disabled (max=${maxPendingMsgs}), dropping`);
-                        // 通知是 fire-and-forget：不 await，避免阻塞当前调用栈
-                        sendTextMessage(config, pending.currentIdentity.token, pending.params.groupId, reason, [pending.params.userInfo?.id ?? ""], log).catch((notifyErr) => {
-                            log.error(`${logPrefix} [queue] Failed to send queue-full notice: ${String(notifyErr)}`);
-                        });
-                        return;
-                    }
-                    // ★ 先同步 push，再异步发通知：确保并发调用看到的 queue.length 各不相同
-                    const queuePos = queue.length + 1;
-                    queue.push(pending);
-                    sessionQueues.set(sessionKey, queue);
-                    log.info(`${logPrefix} [queue] Session ${sessionKey} busy, queued message (pos=${queuePos})`);
-                    // 通知是 fire-and-forget：不 await
-                    sendTextMessage(config, pending.currentIdentity.token, pending.params.groupId, `收到，当前正在处理其他任务，您的消息已排队（队列第 ${queuePos} 位），处理完成后将自动回复。`, [pending.params.userInfo?.id ?? ""], log).catch((notifyErr) => {
-                        log.warn(`${logPrefix} [queue] Failed to send queue notification: ${String(notifyErr)}`);
-                    });
-                    return;
-                }
-                busySessions.add(sessionKey);
-                try {
-                    await dispatchMentionedReply({
-                        rt,
-                        cfg: ctx.cfg,
-                        config,
-                        log,
-                        logPrefix,
-                        route: pending.route,
-                        inboundCtx: pending.inboundCtx,
-                        params: pending.params,
-                        currentIdentity: pending.currentIdentity,
-                        streamClient,
-                    });
-                }
-                finally {
-                    busySessions.delete(sessionKey);
-                    const queue = sessionQueues.get(sessionKey);
-                    if (queue && queue.length > 0) {
-                        const next = queue.shift();
-                        if (queue.length === 0)
-                            sessionQueues.delete(sessionKey);
-                        log.info(`${logPrefix} [queue] Dispatching next queued message for session ${sessionKey} (remaining=${queue.length})`);
-                        runWithSessionQueue(sessionKey, next, streamClient).catch((err) => {
-                            log.error(`${logPrefix} [queue] Error processing queued dispatch: ${String(err)}`);
-                        });
-                    }
-                }
-            };
-            // 6. 收到 WebSocket 消息时的处理逻辑
+            const runWithSessionQueue = createRunWithSessionQueue({
+                config,
+                log,
+                logPrefix,
+                rt,
+                cfg: ctx.cfg,
+            });
             const handleMessage = async (msg) => {
                 const params = msg.params;
                 try {
@@ -785,7 +220,6 @@ export const xgCworkImChannelPlugin = {
                     log.info(`${logPrefix} Message from ${senderName}(${senderId ?? "unknown"}) in group=${params.groupId}: ${text}`);
                     const currentIdentity = await getToken(config, log);
                     const actuallyMentioned = isActuallyMentioned(msg, params, currentIdentity, text);
-                    // 通过 PluginRuntime 路由消息到 OpenClaw
                     const route = rt.channel.routing.resolveAgentRoute({
                         cfg: ctx.cfg,
                         channel: "xg_cwork_im",
@@ -819,12 +253,40 @@ export const xgCworkImChannelPlugin = {
                         senderId,
                         config,
                     });
-                    const groupSystemPromptResolved = resolveXgImGroupSystemPrompt(ctx.cfg, account.accountId);
-                    if (config.debug) {
-                        log.info(`${logPrefix} [GroupSystemPrompt] ` +
-                            (groupSystemPromptResolved
-                                ? `active len=${groupSystemPromptResolved.length} preview=${JSON.stringify(groupSystemPromptResolved.slice(0, 96))}`
-                                : "(empty — 若已配置 systemPrompt：检查网关是否加载了含本字段的插件构建，或把 systemPrompt 写到 accounts.<id> 再试)"));
+                    const agentContext = parseRobotMentionAgentContext(params);
+                    if (params.agentContext != null && !agentContext) {
+                        log.error(`${logPrefix} [agent-context] invalid params.agentContext (schema validation failed)`);
+                    }
+                    let workspaceHostRoot;
+                    if (agentContext?.localRoot.kind === "workspace_relative") {
+                        try {
+                            workspaceHostRoot = resolveAgentWorkspaceDir(ctx.cfg, route.agentId);
+                        }
+                        catch {
+                            log.warn?.(`${logPrefix} [agent-context] cannot resolve workspace host root for workspace_relative localRoot`);
+                        }
+                    }
+                    const groupSystemPromptResolved = resolveInboundGroupSystemPrompt({
+                        cfg: ctx.cfg,
+                        accountId: account.accountId,
+                        config,
+                        agentContext,
+                        workspaceHostRoot,
+                        log,
+                        logPrefix,
+                    });
+                    if (agentContext) {
+                        const gsp = groupSystemPromptResolved ?? "";
+                        const projectMarker = "## 项目工作区";
+                        const projectIdx = gsp.indexOf(projectMarker);
+                        log.info(`${logPrefix} [GroupSystemPrompt] dispatch ` +
+                            `len=${gsp.length} hasProjectBlock=${projectIdx >= 0} ` +
+                            `head=${JSON.stringify(gsp.slice(0, 80))} ` +
+                            `tail=${JSON.stringify(gsp.slice(-120))}`);
+                    }
+                    else if (config.debug && groupSystemPromptResolved) {
+                        log.info(`${logPrefix} [GroupSystemPrompt] static-only len=${groupSystemPromptResolved.length} ` +
+                            `preview=${JSON.stringify(groupSystemPromptResolved.slice(0, 96))}`);
                     }
                     const inboundCtx = rt.channel.reply.finalizeInboundContext({
                         Body: body,
@@ -850,19 +312,16 @@ export const xgCworkImChannelPlugin = {
                         GroupChannel: route.sessionKey,
                         ...mediaFieldsFromFileItems(fileItems),
                         UntrustedContext: buildUntrustedContext(msgExt, senderBackground, fileItems),
-                        // 同时保留原始 ext 供可能的后续逻辑使用
                         XgImExt: msgExt,
                     });
-                    // 若消息内容为 /reset，则在将其转交给 OpenClaw 之前完整打印一次入站上下文，便于排查 reset 行为
                     if (text.trim() === "/reset") {
                         try {
                             log.info?.(`${logPrefix} [reset] inboundCtx payload before dispatch: ${JSON.stringify(inboundCtx)}`);
                         }
                         catch {
-                            // 忽略 JSON 序列化异常，避免影响正常流程
+                            /* ignore */
                         }
                     }
-                    // 【所有消息都必须做】记录到数据库！让 AI 产生“记忆”
                     log.info(`${logPrefix} [session] Recording inbound session sessionKey=${inboundCtx.SessionKey || route.sessionKey}`);
                     await rt.channel.session.recordInboundSession({
                         storePath,
@@ -879,10 +338,23 @@ export const xgCworkImChannelPlugin = {
                         },
                     });
                     if (actuallyMentioned) {
-                        await runWithSessionQueue(route.sessionKey, { route, inboundCtx, params, currentIdentity }, wsHandle.streamClient);
+                        let agentWorkspaceDir;
+                        try {
+                            agentWorkspaceDir = resolveAgentWorkspaceDir(ctx.cfg, route.agentId);
+                        }
+                        catch {
+                            /* 解析失败时静默降级 */
+                        }
+                        await runWithSessionQueue(route.sessionKey, {
+                            route,
+                            inboundCtx,
+                            params,
+                            currentIdentity,
+                            agentWorkspaceDir,
+                            skipSessionQueue: isBypassQueueStopMessage(text),
+                        }, wsHandle.streamClient);
                     }
                     else {
-                        // 没 @ 我，仅作为旁观者缓存记忆，不打扰群里聊天
                         log.debug?.(`${logPrefix} Not mentioned in group, quietly memorized the message context.`);
                     }
                 }
@@ -890,9 +362,15 @@ export const xgCworkImChannelPlugin = {
                     log.error(`${logPrefix} handleMessage error: ${String(err)}`);
                 }
             };
-            // 7. 启动 WebSocket 连接
-            const wsHandle = startWebSocket(config, identity.token, handleMessage, log);
-            // 8. 阻塞到 abortSignal 触发（若存在）；若无 abortSignal，则交由进程生命周期管理
+            const wsHandle = startWebSocket(config, identity.token, handleMessage, log, {
+                onSyncMapping: (params) => applySyncMappingFromWsParams({
+                    config,
+                    cfg: ctx.cfg,
+                    rt,
+                    log,
+                    logPrefix,
+                }, params),
+            });
             if (ctx.abortSignal) {
                 await new Promise((resolve) => {
                     const abortHandler = () => {