@mocrane/wecom 2026.3.20 → 2026.3.24-beta

package/README.md

@@ -22,7 +22,7 @@
 <a id="sec-1"></a>
 ## 💡 核心价值：为什么选择本插件？
 
-### 独创架构：Bot + Agent 双模融合 (Original Design by YanHaidao)
+### 独创架构：Bot + Agent 双模融合
 
 传统的企微插件通常只能在 "只能聊天的机器人 (Bot)" 和 "只能推送的自建应用 (Agent)" 之间二选一。
 本插件采用 **双模并行架构**，同时压榨两种模式的极限能力：
@@ -30,7 +30,7 @@
 *   **Bot 通道 (智能体)**：负责 **实时对话**。提供毫秒级流式响应（打字机效果），零延迟交互。
 *   **Agent 通道 (自建应用)**：负责 **能力兜底**。当需要发送图片/文件、进行全员广播、或 Bot 对话超时（>6分钟）时，无缝切换到 Agent 通道接管。
 
-### 🚀 企业级：多账号（Multi-account）矩阵隔离 (Original Design)
+### 🚀 企业级：多账号（Multi-account）矩阵隔离
 
 本插件支持 **无限扩展的账号矩阵**，这是本插件区别于普通插件的核心壁垒：
 
@@ -332,8 +332,8 @@ openclaw channels status
 7. 记录回调 Token 和 EncodingAESKey
 
 <div align="center">
-  <img src="https://cdn.jsdelivr.net/npm/@mocrane/wecom@latest/assets/03.bot.page.png" width="45%" alt="Bot Config" />
-  <img src="https://cdn.jsdelivr.net/npm/@mocrane/wecom@latest/assets/03.agent.page.png" width="45%" alt="Agent Config" />
+  <img src="https://raw.githubusercontent.com/TencentCloud-Lighthouse/openclaw-wecom/main/assets/03.bot.page.png" width="45%" alt="Bot Config" />
+  <img src="https://raw.githubusercontent.com/TencentCloud-Lighthouse/openclaw-wecom/main/assets/03.agent.page.png" width="45%" alt="Agent Config" />
 </div>
 
 ---
@@ -476,13 +476,12 @@ Agent 输出 `{"template_card": ...}` 时自动渲染为交互卡片：
 
 <a id="sec-legal"></a>
 
-## ⚖️ 授权与原创声明
+## ⚖️ 授权与致谢
 
-本项目采用 **ISC License** 开源协议，并在此强调以下要求：
+本项目采用 **ISC License** 开源协议。
 
-1. **保留署名**：根据 ISC 协议，您在任何分发、修改或使用本项目（或其部分逻辑）时，**必须**在显著位置完整保留本项目的版权声明（Copyright Notice）。
-2. **尊重原创**：本项目包含的“Bot/Agent 自动化互补架构”、“长对话超时接力”、“WeCom 全媒体流自动化处理”等核心逻辑均为作者 **YanHaidao** 独立思考与实践的原创成果。
-3. **维权申明**：对于恶意删除署名、像素级抄袭、混淆视听的恶意搬运行为，作者保留在社区公示及通过法律途径维权的权利。
+- **开源协议**：您在分发、修改或使用本项目时，请遵循 ISC 协议的相关要求。
+- **致谢**：本项目最初基于 **YanHaidao** 的企业微信插件 fork 而来，感谢其在早期版本中的工作与贡献。当前版本已由 **mocrane** 独立重构与维护。
 
 ---
 

package/index.ts

@@ -1,5 +1,5 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema, ensureConfigHelpers } from "./src/compat/plugin-sdk-shim.js";
 
 import { handleWecomWebhookRequest } from "./src/monitor.js";
 import { setWecomRuntime } from "./src/runtime.js";
@@ -22,6 +22,11 @@ const plugin = {
    * 5. 注入 MEDIA 指令提示词（仅 wecom 通道），指导 LLM 使用 MEDIA: 语法发送文件。
    */
   register(api: OpenClawPluginApi) {
+    // 初始化兼容层：确保 deleteAccountFromConfigSection 等函数在
+    // gateway 启动前绑定完成（register 执行与 gateway startAccount 之间
+    // 有充足的异步间隙）。
+    void ensureConfigHelpers();
+
     setWecomRuntime(api.runtime);
     api.registerChannel({ plugin: wecomPlugin });
     const routes = ["/plugins/wecom", "/wecom"];
@@ -38,12 +43,12 @@ const plugin = {
     api.registerTool(createWeComMcpTool(), { name: "wecom_mcp" });
 
     // 注入媒体发送指令和文件大小限制提示词（与官方 @wecom/wecom-openclaw-plugin 保持一致）。
-    // 仅 wecom 通道注入，避免影响其他通道。
+    // 仅 wecom 通道注入，避免污染其他通道（如 Telegram/Discord）的 system prompt。
     // deliver 回调中保留兜底正则解析，作为双重保障。
     api.on("before_prompt_build", (_event, ctx) => {
       if (ctx.channelId !== "wecom") return;
       return {
-        prependContext: [
+        systemPrompt: [
           "【发送文件/图片/视频/语音】",
           "当你需要向用户发送文件、图片、视频或语音时，必须在回复中单独一行使用 MEDIA: 指令，后面跟文件的本地路径。",
           "格式：MEDIA: /文件的绝对路径",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mocrane/wecom",
-  "version": "2026.3.20",
+  "version": "2026.3.24-beta",
   "type": "module",
   "description": "OpenClaw WeCom (WeChat Work) intelligent bot channel plugin",
   "main": "index.ts",

package/src/channel.ts

@@ -3,10 +3,11 @@ import type {
   ChannelPlugin,
   OpenClawConfig,
 } from "openclaw/plugin-sdk";
+
 import {
   deleteAccountFromConfigSection,
   setAccountEnabledInConfigSection,
-} from "openclaw/plugin-sdk";
+} from "./compat/plugin-sdk-shim.js";
 
 import {
   DEFAULT_ACCOUNT_ID,
@@ -39,10 +40,12 @@ function normalizeWecomMessagingTarget(raw: string): string | undefined {
   return trimmed.replace(/^(wecom-agent|wecom|wechatwork|wework|qywx):/i, "").trim() || undefined;
 }
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- onboarding 在 >=3.22 中已重命名为 setupWizard，
+// 但我们仍设置旧字段以兼容 <3.22 版本的 OpenClaw。
 export const wecomPlugin: ChannelPlugin<ResolvedWecomAccount> = {
   id: "wecom",
   meta,
-  onboarding: wecomOnboardingAdapter,
+  onboarding: wecomOnboardingAdapter as any,
   setup: {
     resolveAccountId: ({ cfg, accountId }) => {
       return accountId?.trim() || resolveDefaultWecomAccountId(cfg as OpenClawConfig) || DEFAULT_ACCOUNT_ID;
@@ -111,14 +114,14 @@ export const wecomPlugin: ChannelPlugin<ResolvedWecomAccount> = {
         accountId,
         enabled,
         allowTopLevel: true,
-      }),
+      }) as OpenClawConfig,
     deleteAccount: ({ cfg, accountId }) =>
       deleteAccountFromConfigSection({
         cfg: cfg as OpenClawConfig,
         sectionKey: "wecom",
         accountId,
         clearBaseFields: ["bot", "agent"],
-      }),
+      }) as OpenClawConfig,
     isConfigured: (account, cfg) => {
       if (!account.configured) {
         return false;

package/src/compat/plugin-sdk-shim.ts

@@ -0,0 +1,210 @@
+/**
+ * OpenClaw Plugin SDK 兼容 Shim — 同步接口
+ *
+ * 解决 v2026.3.23 中 plugin-sdk 子路径重构导致部分符号从主入口消失的问题。
+ *
+ * 策略：
+ * 1. 纯类型 → 直接从 `openclaw/plugin-sdk` 主入口重导出（所有版本均可）
+ * 2. DEFAULT_ACCOUNT_ID → 硬编码常量 "default"（所有版本一致）
+ * 3. deleteAccountFromConfigSection / setAccountEnabledInConfigSection
+ *    → 通过在构建/加载时探测子路径，回退到主入口 compat 层
+ * 4. readJsonFileWithFallback / writeJsonFileAtomically / withFileLock
+ *    → 异步解析（仅 mcp-config.ts 需要，该模块中函数本身就是 async）
+ * 5. promptAccountId → 异步解析（仅 onboarding.ts 需要，configure 回调本身是 async）
+ */
+
+// ─── 类型重导出 ───
+export type { OpenClawConfig } from "openclaw/plugin-sdk";
+export type { PluginRuntime } from "openclaw/plugin-sdk";
+export type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+export type { ChannelPlugin, ChannelConfigSchema } from "openclaw/plugin-sdk";
+export type { ChannelAccountSnapshot } from "openclaw/plugin-sdk";
+export type { ChannelGatewayContext } from "openclaw/plugin-sdk";
+export type { WizardPrompter } from "openclaw/plugin-sdk";
+export type {
+  ChannelOutboundAdapter,
+  ChannelOutboundContext,
+} from "openclaw/plugin-sdk";
+
+// ─── 值：emptyPluginConfigSchema（主入口始终导出） ───
+export { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+
+// ─── DEFAULT_ACCOUNT_ID ───
+export const DEFAULT_ACCOUNT_ID = "default";
+
+// ─── 安全动态导入 ───
+async function tryImport<T>(specifier: string): Promise<T | undefined> {
+  try {
+    return await import(specifier) as T;
+  } catch {
+    return undefined;
+  }
+}
+
+// ────────────────────────────────────────────────────
+// deleteAccountFromConfigSection / setAccountEnabledInConfigSection
+// 这些函数在 channel.ts 的 config 回调中同步使用。
+// 使用 "eager init + cache" 模式：模块加载时立即解析并缓存。
+// ────────────────────────────────────────────────────
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyFn = (...args: any[]) => any;
+
+let _deleteAccountFromConfigSection: AnyFn | undefined;
+let _setAccountEnabledInConfigSection: AnyFn | undefined;
+
+// 立即触发的异步自解析
+const _configHelpersReady = (async () => {
+  for (const subpath of [
+    "openclaw/plugin-sdk/core",
+    "openclaw/plugin-sdk/channel-plugin-common",
+  ]) {
+    const mod = await tryImport<Record<string, AnyFn>>(subpath);
+    if (mod?.deleteAccountFromConfigSection && mod?.setAccountEnabledInConfigSection) {
+      _deleteAccountFromConfigSection = mod.deleteAccountFromConfigSection;
+      _setAccountEnabledInConfigSection = mod.setAccountEnabledInConfigSection;
+      return;
+    }
+  }
+  // 如果子路径都没有，抛出明确错误
+  throw new Error(
+    "[wecom-compat] Cannot resolve config section helpers. " +
+    "Ensure openclaw >=2026.2.24 is installed.",
+  );
+})();
+
+/**
+ * 等待 config section helpers 解析完成。
+ * 在使用 deleteAccountFromConfigSection / setAccountEnabledInConfigSection 之前调用。
+ */
+export async function ensureConfigHelpers(): Promise<void> {
+  await _configHelpersReady;
+}
+
+/** 同步获取 deleteAccountFromConfigSection（须确保 ensureConfigHelpers 已完成） */
+export function deleteAccountFromConfigSection(...args: unknown[]): unknown {
+  if (!_deleteAccountFromConfigSection) {
+    throw new Error("[wecom-compat] Config helpers not initialized. Call ensureConfigHelpers() first.");
+  }
+  return _deleteAccountFromConfigSection(...args);
+}
+
+/** 同步获取 setAccountEnabledInConfigSection（须确保 ensureConfigHelpers 已完成） */
+export function setAccountEnabledInConfigSection(...args: unknown[]): unknown {
+  if (!_setAccountEnabledInConfigSection) {
+    throw new Error("[wecom-compat] Config helpers not initialized. Call ensureConfigHelpers() first.");
+  }
+  return _setAccountEnabledInConfigSection(...args);
+}
+
+// ────────────────────────────────────────────────────
+// promptAccountId (仅 onboarding.ts 需要，异步调用)
+// ────────────────────────────────────────────────────
+type PromptAccountIdFn = (params: {
+  cfg: unknown;
+  prompter: unknown;
+  label: string;
+  currentId: string;
+  listAccountIds: (cfg: unknown) => string[];
+  defaultAccountId: string;
+}) => Promise<string>;
+
+let _promptAccountId: PromptAccountIdFn | undefined;
+
+export async function resolvePromptAccountId(): Promise<PromptAccountIdFn> {
+  if (_promptAccountId) return _promptAccountId;
+
+  for (const subpath of [
+    "openclaw/plugin-sdk/matrix",
+    "openclaw/plugin-sdk/channel-setup",
+    "openclaw/plugin-sdk/setup",
+  ]) {
+    const mod = await tryImport<{ promptAccountId?: PromptAccountIdFn }>(subpath);
+    if (mod?.promptAccountId) {
+      _promptAccountId = mod.promptAccountId;
+      return _promptAccountId;
+    }
+  }
+
+  // 兜底实现
+  _promptAccountId = async (params) => params.currentId || params.defaultAccountId;
+  return _promptAccountId;
+}
+
+// ────────────────────────────────────────────────────
+// readJsonFileWithFallback / writeJsonFileAtomically / withFileLock
+// (仅 mcp-config.ts 需要，函数本身为 async)
+// ────────────────────────────────────────────────────
+type FileLockFn = <T>(
+  filePath: string,
+  options: unknown,
+  fn: () => Promise<T>,
+) => Promise<T>;
+
+type ReadJsonFn = <T>(
+  filePath: string,
+  fallback: T,
+) => Promise<{ value: T; exists: boolean }>;
+
+type WriteJsonFn = (filePath: string, value: unknown) => Promise<void>;
+
+export type FileIoHelpers = {
+  withFileLock: FileLockFn;
+  readJsonFileWithFallback: ReadJsonFn;
+  writeJsonFileAtomically: WriteJsonFn;
+};
+
+let _fileIo: FileIoHelpers | undefined;
+
+export async function resolveFileIoHelpers(): Promise<FileIoHelpers> {
+  if (_fileIo) return _fileIo;
+
+  const jsonStore = await tryImport<Partial<FileIoHelpers>>("openclaw/plugin-sdk/json-store");
+  const msteams = await tryImport<{ withFileLock?: FileLockFn }>("openclaw/plugin-sdk/msteams");
+
+  const readFn = jsonStore?.readJsonFileWithFallback;
+  const writeFn = jsonStore?.writeJsonFileAtomically;
+  const lockFn = msteams?.withFileLock;
+
+  if (readFn && writeFn && lockFn) {
+    _fileIo = { readJsonFileWithFallback: readFn, writeJsonFileAtomically: writeFn, withFileLock: lockFn };
+    return _fileIo;
+  }
+
+  // ── Node.js 原生回退实现 ──
+  const fs = await import("node:fs/promises");
+  const nodePath = await import("node:path");
+
+  const fallbackRead: ReadJsonFn = async <T>(filePath: string, fallback: T) => {
+    try {
+      const raw = await fs.readFile(filePath, "utf-8");
+      return { value: JSON.parse(raw) as T, exists: true };
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        return { value: fallback, exists: false };
+      }
+      return { value: fallback, exists: false };
+    }
+  };
+
+  const fallbackWrite: WriteJsonFn = async (filePath: string, value: unknown) => {
+    const dir = nodePath.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+    const content = JSON.stringify(value, null, 2) + "\n";
+    const tmpPath = `${filePath}.tmp.${process.pid}`;
+    await fs.writeFile(tmpPath, content, { mode: 0o600 });
+    await fs.rename(tmpPath, filePath);
+  };
+
+  const fallbackLock: FileLockFn = async <T>(
+    _filePath: string,
+    _options: unknown,
+    fn: () => Promise<T>,
+  ): Promise<T> => fn();
+
+  _fileIo = {
+    readJsonFileWithFallback: readFn ?? fallbackRead,
+    writeJsonFileAtomically: writeFn ?? fallbackWrite,
+    withFileLock: lockFn ?? fallbackLock,
+  };
+  return _fileIo;
+}

package/src/mcp/transport.ts

@@ -14,7 +14,7 @@ import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { generateReqId } from "@wecom/aibot-node-sdk";
-import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID } from "../compat/plugin-sdk-shim.js";
 import { getWsClient } from "../ws-adapter.js";
 import { withTimeout } from "../timeout.js";
 

package/src/mcp-config.ts

@@ -11,11 +11,7 @@ import os from "os";
 import path from "path";
 import type { WSClient } from "@wecom/aibot-node-sdk";
 import { generateReqId } from "@wecom/aibot-node-sdk";
-import {
-    readJsonFileWithFallback,
-    writeJsonFileAtomically,
-    withFileLock,
-} from "openclaw/plugin-sdk";
+import { resolveFileIoHelpers } from "./compat/plugin-sdk-shim.js";
 import type { WecomRuntimeEnv } from "./monitor/types.js";
 import { withTimeout } from "./timeout.js";
 
@@ -122,6 +118,9 @@ async function saveMcpConfigToPluginJson(
         },
     };
 
+    const { withFileLock, readJsonFileWithFallback, writeJsonFileAtomically } =
+        await resolveFileIoHelpers();
+
     await withFileLock(wecomConfigPath, lockOptions, async () => {
         // 读取现有配置（不存在时使用空对象）
         const { value: pluginJson } = await readJsonFileWithFallback<Record<string, unknown>>(

package/src/onboarding.ts

@@ -4,12 +4,50 @@
  */
 
 import type {
-    ChannelOnboardingAdapter,
-    ChannelOnboardingDmPolicy,
     OpenClawConfig,
     WizardPrompter,
 } from "openclaw/plugin-sdk";
-import { DEFAULT_ACCOUNT_ID, promptAccountId } from "openclaw/plugin-sdk";
+import {
+    DEFAULT_ACCOUNT_ID,
+    resolvePromptAccountId,
+} from "./compat/plugin-sdk-shim.js";
+
+// ─── 类型兼容 ───
+// v2026.3.2 使用 ChannelOnboardingAdapter / ChannelOnboardingDmPolicy（来自 onboarding-types.ts）
+// v2026.3.22+ 重命名为 ChannelSetupWizardAdapter / ChannelSetupDmPolicy（setup-wizard-types.ts）
+// 且 ChannelPlugin.onboarding → ChannelPlugin.setupWizard
+// 为同时支持新旧版本，此处直接声明本地接口。
+type ChannelOnboardingDmPolicy = {
+    label: string;
+    channel: string;
+    policyKey: string;
+    allowFromKey: string;
+    getCurrent: (cfg: OpenClawConfig, accountId?: string) => string;
+    setPolicy: (cfg: OpenClawConfig, policy: string, accountId?: string) => OpenClawConfig;
+    promptAllowFrom?: (params: {
+        cfg: OpenClawConfig;
+        prompter: WizardPrompter;
+        accountId?: string;
+    }) => Promise<OpenClawConfig>;
+};
+
+type ChannelOnboardingAdapter = {
+    channel: string;
+    dmPolicy?: ChannelOnboardingDmPolicy;
+    getStatus: (ctx: { cfg: OpenClawConfig }) => Promise<{
+        channel: string;
+        configured: boolean;
+        statusLines: string[];
+        selectionHint?: string;
+        quickstartScore?: number;
+    }>;
+    configure: (ctx: {
+        cfg: OpenClawConfig;
+        prompter: WizardPrompter;
+        accountOverrides: Record<string, string | undefined>;
+        shouldPromptAccountIds: boolean;
+    }) => Promise<{ cfg: OpenClawConfig; accountId?: string }>;
+};
 import { listWecomAccountIds, resolveDefaultWecomAccountId, resolveWecomAccount, resolveWecomAccounts } from "./config/index.js";
 import type { WecomConfig, WecomBotConfig, WecomAgentConfig, WecomDmConfig, WecomAccountConfig } from "./types/index.js";
 
@@ -299,12 +337,13 @@ async function resolveOnboardingAccountId(params: {
     const override = params.accountOverride?.trim();
     let accountId = override || defaultAccountId;
     if (!override && params.shouldPromptAccountIds) {
+        const promptAccountId = await resolvePromptAccountId();
         accountId = await promptAccountId({
             cfg: params.cfg,
             prompter: params.prompter,
             label: "WeCom",
             currentId: accountId,
-            listAccountIds: (cfg) => listWecomAccountIds(cfg),
+            listAccountIds: (cfg) => listWecomAccountIds(cfg as OpenClawConfig),
             defaultAccountId,
         });
     }
@@ -690,9 +729,9 @@ const dmPolicy: ChannelOnboardingDmPolicy = {
         const account = resolveWecomAccount({ cfg });
         return (account.bot?.config.dm?.policy ?? "pairing") as "pairing";
     },
-    setPolicy: (cfg: OpenClawConfig, policy: "pairing" | "allowlist" | "open" | "disabled") => {
+    setPolicy: (cfg: OpenClawConfig, policy: string) => {
         const accountId = resolveDefaultWecomAccountId(cfg);
-        return setWecomDmPolicy(cfg, "bot", { policy }, accountId);
+        return setWecomDmPolicy(cfg, "bot", { policy: policy as "pairing" | "allowlist" | "open" | "disabled" }, accountId);
     },
     promptAllowFrom: async ({ cfg, prompter }: { cfg: OpenClawConfig; prompter: WizardPrompter }) => {
         const allowFromStr = String(