@wecom/wecom-openclaw-plugin 2026.7.2-beta.1 → 2026.8.17-beta.1

package/README.md

@@ -17,9 +17,9 @@
 
 # 🤖 WeCom OpenClaw Plugin
 
-**WeCom channel plugin for [OpenClaw](https://github.com/openclaw)** — by the Tencent WeCom team.
+**WeCom channel and business capability plugin for [OpenClaw](https://github.com/openclaw)** — by the Tencent WeCom team.
 
-> A channel plugin powered by WeCom. Supports **Bot mode** (WebSocket long-polling or HTTP webhook with JSON callbacks) and **Agent mode** (HTTP webhook with XML encrypted callbacks). Direct messages, group chats, streaming replies, and proactive messaging.
+> A channel and business capability plugin powered by WeCom. Supports **Bot mode** (WebSocket long-polling or HTTP webhook with JSON callbacks), **Agent mode** (HTTP webhook with XML encrypted callbacks), direct messages, group chats, streaming replies, proactive messaging, and built-in `wecom-cli` business operations.
 
 ---
 
@@ -41,8 +41,7 @@
 - 🔒 Built-in access control: DM Policy (pairing / open / allowlist / disabled) and Group Policy (open / allowlist / disabled)
 - 🔑 Command authorization: per-account command permission control with access group support
 - 👥 Multi-account support: run multiple WeCom accounts with independent bot/agent configs
-- 🧩 MCP tool integration (`wecom_mcp`) with interceptor pipeline (biz-error, media, smartpage-create, smartpage-export)
-- 🎯 **15 built-in Skills**: contact lookup, doc management, todo, meeting, schedule, messaging, smartsheet, template cards, and more
+- 🧰 Built-in business Skills powered by the plugin-provided `wecom-cli` tool
 - 🔀 Dynamic Agent routing: auto-create isolated agents per user/group
 - 📁 Local file sending with configurable media path allowlist (`mediaLocalRoots`)
 - 📊 Smart media size limits with auto-downgrade (image 10MB → file, video 10MB → file, voice 2MB/AMR-only → file, max 20MB)
@@ -51,6 +50,25 @@
 - 🛡️ Anti-kick protection: suppresses auto-restart on server-side disconnection to prevent mutual kicking loops
 - 🧙 Interactive CLI setup wizard
 
+### Enterprise Business Capabilities
+
+The plugin includes the `wecom-cli` tool and corresponding Skills, covering the following WeCom business domains:
+
+| Domain | Capabilities |
+|---|---|
+| 💬 Messaging | Proactively send messages to direct or group chats that recently interacted with the bot; supports Markdown, image, file, voice, and video messages |
+| 📧 Email | Send, reply to, and forward email; search messages and retrieve full email details |
+| 📄 Documents | Create, import, read, append to, and overwrite online documents |
+| 🗂️ Document Management | Search across multiple document types; rename online documents, spreadsheets, smart sheets, and smart documents; manage members, permissions, and join rules |
+| 📊 Spreadsheets | Create online spreadsheets, import CSV/Excel files, read and update content, append rows, and manage sheets |
+| 🧮 Smart Sheets | Create smart sheets; manage sheets, fields, records, views, charts, and row/column styles |
+| 📰 Smart Documents | Create smart documents, retrieve and edit page content, and access embedded data table information |
+| ✅ Todo | Create, read, update, and delete todo items; assign participants and mark items as complete |
+| 📅 Calendar | Create, read, update, and delete events; manage participants, query attendee availability, and search or reserve meeting rooms |
+| 🎥 Meetings | Schedule, cancel, and update meetings; manage attendees, query meeting lists and details, and retrieve minutes and transcripts |
+| 💾 WeDrive | Search files, retrieve file metadata, and upload or download files |
+| 👤 Contacts | Search members by name, pinyin, or alias and retrieve member details for meetings, calendar events, and other multi-user workflows |
+
 ---
 
 ## 🚀 Getting Started
@@ -102,6 +120,17 @@ openclaw config set channels.wecom.enabled true
 openclaw gateway restart
 ```
 
+### Enable Business Tools
+
+The enterprise business capabilities above are exposed through the plugin-provided `wecom-cli` tool. Unless `tools.profile` is set to `full`, allow the plugin and restart the Gateway:
+
+```shell
+openclaw config set tools.alsoAllow '["wecom-openclaw-plugin"]'
+openclaw gateway restart
+```
+
+> Allowing the plugin ID enables all tools currently or subsequently registered by this plugin. If `tools.alsoAllow` already contains other entries, merge `wecom-openclaw-plugin` into the existing array instead of replacing it.
+
 ### Mode Overview
 
 The plugin supports two connection modes that can be used independently or together:

package/dist/index.js

@@ -1,7 +1,7 @@
 import { emptyPluginConfigSchema } from "./src/openclaw-compat.js";
 import { wecomPlugin } from "./src/channel.js";
-import { createWeComMcpTool } from "./src/mcp/index.js";
-import { getSessionChatInfo } from "./src/state-manager.js";
+import { createWeComCliTool, CLI_TOOL_NAME } from "./src/cli/index.js";
+import { LEGACY_TOOL_WARNING, shouldWarnLegacyToolAllow, } from "./src/cli/legacy-tool-warning.js";
 import { setWeComRuntime } from "./src/runtime.js";
 import { CHANNEL_ID, WEBHOOK_PATHS } from "./src/const.js";
 import { createWecomAgentWebhookHandler } from "./src/agent/webhook.js";
@@ -13,25 +13,16 @@ const plugin = {
     configSchema: emptyPluginConfigSchema(),
     register(api) {
         setWeComRuntime(api.runtime);
+        if (shouldWarnLegacyToolAllow(api.config.tools)) {
+            api.logger.warn(LEGACY_TOOL_WARNING);
+        }
         api.registerChannel({ plugin: wecomPlugin });
-        // 注册 wecom_mcp：通过 HTTP 直接调用企业微信 MCP Server
+        // 注册 wecom-cli：包装 @wecom/cli 二进制，按会话所属bot 注入独立配置目录
         api.registerTool((ctx) => {
-            const trustedRequesterUserId = ctx.messageChannel === CHANNEL_ID ? ctx.requesterSenderId?.trim() ?? undefined : undefined;
-            // 按 sessionKey 精确取回「原始大小写」的 chatId / chatType。
-            // 数据由 monitor.ts 在消息入站时通过 setSessionChatInfo 写入，
-            // 避免 parseSessionKeyChat 反解导致 chatId 被 OpenClaw core 小写化
-            // （小写后的 chatId 调用企业微信 aibot_send_biz_msg 会报 invalid chatid）。
-            const sessionChat = getSessionChatInfo(ctx.sessionKey);
-            console.log(`[mcp] registerTool ctx: sessionKey="${ctx.sessionKey}", messageChannel="${ctx.messageChannel}", ` +
-                `requesterSenderId="${ctx.requesterSenderId}", agentAccountId="${ctx.agentAccountId}", ` +
-                `sessionChat=${JSON.stringify(sessionChat)}`);
-            return createWeComMcpTool({
-                requesterUserId: trustedRequesterUserId,
-                accountId: ctx.agentAccountId,
-                chatId: sessionChat?.chatId,
-                chatType: sessionChat?.chatType,
-            });
-        }, { name: "wecom_mcp" });
+            console.log(`[wecom-cli:tool] registerTool ctx: sessionKey="${ctx.sessionKey}", ` +
+                `messageChannel="${ctx.messageChannel}", agentAccountId="${ctx.agentAccountId}"`);
+            return createWeComCliTool({ accountId: ctx.agentAccountId });
+        }, { name: CLI_TOOL_NAME });
         const agentWebhookHandler = createWecomAgentWebhookHandler(api.runtime);
         // 注册 Agent 模式 HTTP 路由（prefix match 覆盖带 accountId 的子路径）
         api.registerHttpRoute({
@@ -57,7 +48,7 @@ const plugin = {
                 match: "prefix",
             });
         }
-        // 注入媒体发送指令和文件大小限制提示词（仅对企业微信 channel 生效）
+        // 注入企业微信专用工具约束、媒体发送指令和文件大小限制提示词（仅对企业微信 channel 生效）
         api.on("before_prompt_build", (_event, ctx) => {
             // 只在企业微信 channel 的会话中注入，避免影响其他 channel 插件
             if (ctx?.channelId !== CHANNEL_ID) {
@@ -65,8 +56,10 @@ const plugin = {
             }
             return {
                 appendSystemContext: [
+                    "重要：企业微信通讯录、文档、会议、日程、待办、智能表格等能力必须调用专用 `wecom-cli` tool。禁止通过 exec、bash、shell、npx 或全局命令运行 wecom-cli；专用 tool 内部自行寻址并启动二进制是正常实现，不属于此禁止范围。",
+                    "重要：即使 `wecom-cli` tool 调用失败、不可见、权限不足或提示授权，也不得降级到 exec 或手动执行 auth init；应向用户返回工具权限或 `channels.wecom` 配置问题。调用 tool 时，`args` 只传 wecom-cli 后面的参数，不传命令前缀、WECOM_CLI_* 环境变量或配置目录。",
                     "重要：涉及发送图片/视频/语音/文件给用户时，请务必使用 `MEDIA:` 指令。详见  wecom-send-media 这个 skill（技能）。",
-                    "重要：当需要向用户发送结构化卡片消息（如通知、投票、按钮选择等）时，请在回复中直接输出 JSON 代码块（```json ... ```），其中 card_type 字段标明卡片类型。详见 wecom-send-template-card 技能。"
+                    "重要：当需要向用户发送结构化卡片消息（如通知、投票、按钮选择等）时，请在回复中直接输出 JSON 代码块（```json ... ```），其中 card_type 字段标明卡片类型。详见 wecom-send-template-card 技能。",
                 ].join("\n"),
             };
         });

package/dist/src/cli/argv.d.ts

@@ -0,0 +1,36 @@
+/**
+ * argv 解析与安全校验
+ *
+ * tool 入参刻意对齐 cli 命令行本身（`args` = `wecom-cli ` 之后的全部内容），
+ * 这样 skills 里的命令表、参数说明、返回字段表都不需要改写。
+ *
+ * 但"对齐命令行"不等于"走shell"——spawn 一律 `shell: false`，
+ * 这里只做极简词法切分：认单引号 / 双引号 / 反斜杠，遇到任何 shell
+ * 元字符直接拒绝（出现元字符说明模型在拼 shell，而不是在传参数）。
+ */
+export declare class CliArgvError extends Error {
+}
+/**
+ * 极简 POSIX-ish 词法切分。
+ *
+ * 支持：
+ *   'single quoted'      → 内部原样，不做任何转义
+ *   "double quoted"      → 支持 \" \\ 转义
+ *   bare\ token          → 反斜杠转义空格
+ * 不支持（且拒绝）：裸的管道、重定向、命令组合。
+ *
+ * shell 组合符的检查是**引号感知**的：只有引号外的裸字符才会被拒绝。
+ * 这样 `--json '{"a":1}'` 和 `--json {"a":1}` 都能通过，
+ * 而 `... | jq .` 里裸的管道符会被拦住。
+ */
+export declare function tokenize(input: string): string[];
+/**
+ * 安全校验。
+ *
+ * 关键点：`WECOM_CLI_CONFIG_DIR` 由服务端按当前会话的 bot 注入，
+ * 模型既看不到也改不了。这里额外拦住模型试图自行覆盖配置目录/端点的行为——
+ * 一旦被覆盖，就可能拿 A 企业的凭据调 B 企业的接口。
+ */
+export declare function assertSafeArgv(argv: string[]): void;
+/** 归一化 tool 入参为 argv 数组，并完成安全校验 */
+export declare function normalizeArgs(args: unknown): string[];

package/dist/src/cli/argv.js

@@ -0,0 +1,155 @@
+/**
+ * argv 解析与安全校验
+ *
+ * tool 入参刻意对齐 cli 命令行本身（`args` = `wecom-cli ` 之后的全部内容），
+ * 这样 skills 里的命令表、参数说明、返回字段表都不需要改写。
+ *
+ * 但"对齐命令行"不等于"走shell"——spawn 一律 `shell: false`，
+ * 这里只做极简词法切分：认单引号 / 双引号 / 反斜杠，遇到任何 shell
+ * 元字符直接拒绝（出现元字符说明模型在拼 shell，而不是在传参数）。
+ */
+import { CLI_FORBIDDEN_AUTH_ACTIONS, CLI_FORBIDDEN_SUBCOMMANDS, CLI_SHELL_METACHARS, CLI_SUBCOMMAND_RE, } from "./const.js";
+export class CliArgvError extends Error {
+}
+/**
+ * 极简 POSIX-ish 词法切分。
+ *
+ * 支持：
+ *   'single quoted'      → 内部原样，不做任何转义
+ *   "double quoted"      → 支持 \" \\ 转义
+ *   bare\ token          → 反斜杠转义空格
+ * 不支持（且拒绝）：裸的管道、重定向、命令组合。
+ *
+ * shell 组合符的检查是**引号感知**的：只有引号外的裸字符才会被拒绝。
+ * 这样 `--json '{"a":1}'` 和 `--json {"a":1}` 都能通过，
+ * 而 `... | jq .` 里裸的管道符会被拦住。
+ */
+export function tokenize(input) {
+    const out = [];
+    let cur = "";
+    let has = false;
+    let i = 0;
+    while (i < input.length) {
+        const ch = input[i];
+        if (ch === " " || ch === "\t") {
+            if (has) {
+                out.push(cur);
+                cur = "";
+                has = false;
+            }
+            i += 1;
+            continue;
+        }
+        if (ch === "'") {
+            has = true;
+            i += 1;
+            const end = input.indexOf("'", i);
+            if (end < 0)
+                throw new CliArgvError("args 中单引号未闭合");
+            cur += input.slice(i, end);
+            i = end + 1;
+            continue;
+        }
+        if (ch === '"') {
+            has = true;
+            i += 1;
+            while (i < input.length && input[i] !== '"') {
+                if (input[i] === "\\" && i + 1 < input.length) {
+                    const next = input[i + 1];
+                    cur += next === '"' || next === "\\" ? next : `\\${next}`;
+                    i += 2;
+                }
+                else {
+                    cur += input[i];
+                    i += 1;
+                }
+            }
+            if (i >= input.length)
+                throw new CliArgvError("args 中双引号未闭合");
+            i += 1;
+            continue;
+        }
+        if (ch === "\\" && i + 1 < input.length) {
+            has = true;
+            cur += input[i + 1];
+            i += 2;
+            continue;
+        }
+        // 裸字符（不在任何引号内）：此处才做shell 组合符检查
+        if (CLI_SHELL_METACHARS.test(ch)) {
+            throw new CliArgvError(`args 中包含未被引号包裹的 shell 组合符 ${JSON.stringify(ch)}。` +
+                "本 tool 直接执行 wecom-cli，不经过 shell，因此不支持管道、重定向与命令组合。" +
+                "若该字符是参数值的一部分，请用引号包裹，或改用数组形式的 args。");
+        }
+        // 裸的命令替换 `$(`：单独的 `$` 是合法值字符（如金额），但 `$(` 只可能是拼shell
+        if (ch === "$" && input[i + 1] === "(") {
+            throw new CliArgvError("args 中包含未被引号包裹的命令替换 `$(`。本 tool 不经过 shell 执行，" +
+                "请直接给出参数值；若该内容是参数值的一部分，请用引号包裹或改用数组形式的 args。");
+        }
+        has = true;
+        cur += ch;
+        i += 1;
+    }
+    if (has)
+        out.push(cur);
+    return out;
+}
+/**
+ * 安全校验。
+ *
+ * 关键点：`WECOM_CLI_CONFIG_DIR` 由服务端按当前会话的 bot 注入，
+ * 模型既看不到也改不了。这里额外拦住模型试图自行覆盖配置目录/端点的行为——
+ * 一旦被覆盖，就可能拿 A 企业的凭据调 B 企业的接口。
+ */
+export function assertSafeArgv(argv) {
+    if (argv.length === 0) {
+        throw new CliArgvError("args 不能为空，至少需要指定品类，如 `contact users search --json '{}'`");
+    }
+    const head = argv[0];
+    if (!CLI_SUBCOMMAND_RE.test(head)) {
+        throw new CliArgvError(`第一个参数 ${JSON.stringify(head)} 不是合法的子命令名。` +
+            `应为品类名（如 contact / doc / meeting / todo / calendar）或 auth / cache。`);
+    }
+    if (CLI_FORBIDDEN_SUBCOMMANDS.has(head)) {
+        throw new CliArgvError(`子命令 \`${head}\` 已被禁用：它是交互式流程且会改写全局凭据存储。` +
+            `企业微信凭据请在 openclaw 配置 \`channels.wecom\` 中维护。`);
+    }
+    // `auth init` 的 argv[0] 是 auth 而非 init，不在上面的顶层禁用集内，需单独拦
+    if (head === "auth" && argv[1] && CLI_FORBIDDEN_AUTH_ACTIONS.has(argv[1])) {
+        throw new CliArgvError(`\`auth ${argv[1]}\` 已被禁用：企业微信凭据由插件按当前会话的机器人自动管理，` +
+            `不需要（也不允许）手动授权。若提示凭据不可用，请检查 openclaw 配置 ` +
+            `\`channels.wecom\` 中的 botId / secret。`);
+    }
+    for (const tok of argv) {
+        if (/^WECOM_CLI_[A-Z_]*=/.test(tok)) {
+            throw new CliArgvError(`args 中不允许出现环境变量赋值 ${JSON.stringify(tok)}；运行环境由插件按当前会话的机器人注入。`);
+        }
+        if (/^--config-dir(=|$)/.test(tok) || /^--home(=|$)/.test(tok)) {
+            throw new CliArgvError(`args 中不允许覆盖配置目录（${JSON.stringify(tok)}）；配置目录由插件按当前会话的机器人决定。`);
+        }
+    }
+}
+/** 归一化 tool 入参为 argv 数组，并完成安全校验 */
+export function normalizeArgs(args) {
+    let argv;
+    if (Array.isArray(args)) {
+        argv = args.map((a) => {
+            if (typeof a === "string")
+                return a;
+            if (typeof a === "number" || typeof a === "boolean")
+                return String(a);
+            throw new CliArgvError(`args 数组元素必须是字符串，收到 ${typeof a}`);
+        });
+    }
+    else if (typeof args === "string") {
+        argv = tokenize(args);
+    }
+    else {
+        throw new CliArgvError(`args 必须是字符串或字符串数组，收到 ${typeof args}`);
+    }
+    // 容错：模型可能把 "wecom-cli" 本身也带上
+    if (argv[0] === "wecom-cli" || argv[0] === "wecom")
+        argv = argv.slice(1);
+    assertSafeArgv(argv);
+    return argv;
+}

package/dist/src/cli/const.d.ts

@@ -0,0 +1,94 @@
+/**
+ * wecom-cli tool 常量
+ */
+/** tool 名（与 openclaw.plugin.json 的 contracts.tools 必须完全一致） */
+export declare const CLI_TOOL_NAME = "wecom-cli";
+/**
+ * 日志前缀。
+ *
+ * 必须与 agent 通过 exec 直接执行 `wecom-cli` 的情形可区分——
+ * 两者在日志里都叫 wecom-cli，排查"串号"问题时需要靠这个前缀分辨。
+ */
+export declare const CLI_LOG = "[wecom-cli:tool]";
+/** 单次业务命令 spawn 超时（实测热缓存调用仅 300~500ms） */
+export declare const CLI_TIMEOUT_MS = 45000;
+/**
+ * `auth init` 的 spawn 超时，比业务命令短。
+ *
+ * 授权只有一次 HTTP 鉴权，30s 足够覆盖慢网。
+ * 更重要的是它是**唯一**能兜住"cli 写 keyring 时挂住"的手段：
+ * cli 的 save_key 对 keyring 失败只 warn，但 macOS Keychain 可能弹窗等待授权，
+ * 而 gateway 是后台进程 → 弹窗没人点 → 进程永久挂住。
+ */
+export declare const CLI_AUTH_TIMEOUT_MS = 30000;
+/** 超时后 SIGTERM 到 SIGKILL 的宽限期 */
+export declare const CLI_KILL_GRACE_MS = 3000;
+/** SIGKILL 后等待 close 事件的上限，超过后主动结束插件侧等待 */
+export declare const CLI_KILL_FORCE_WAIT_MS = 3000;
+/** 返回给模型的输出上限。openclaw 无通用截断机制，必须由插件自己兜住 */
+export declare const CLI_MAX_OUTPUT_BYTES: number;
+/** 同一配置目录的重签冷却，避免 secret 失效时反复撞 45009 频率超限 */
+export declare const CLI_RESIGN_COOLDOWN_MS: number;
+/**
+ * 禁止的顶层子命令。
+ *
+ * `init` 无非交互入口，会拉起cliclack /扫码流程。
+ */
+export declare const CLI_FORBIDDEN_SUBCOMMANDS: Set<string>;
+/**
+ * 禁止的 `auth` 子动作（`argv[0] === "auth"` 时检查 `argv[1]`）。
+ *
+ * 为什么单独拦：授权命令是 `auth init`，`argv[0]` 是 `auth` 而非 `init`，
+ * 不在上面的顶层禁用集内。而凭据现在完全由插件管理
+ * （`credentials.ts` 会按当前会话机器人 spawn `auth init --bot-id/--secret`），
+ * 模型自行触发只有两种结果：
+ *   - 不带凭据 → stderr 非 TTY 下走扫码分支 → 挂到超时
+ *   - 带凭据 → 它拿不到 secret，只能瞎猜；即便猜对也绕过了 openclaw 配置
+ * `auth show` / `auth status` 之类只读动作不受影响。
+ */
+export declare const CLI_FORBIDDEN_AUTH_ACTIONS: Set<string>;
+/**
+ * argv[0] 合法格式。
+ *
+ * 这里刻意不用"品类白名单"——品类由服务端 discovery 动态下发，
+ * 白名单会在cli 新增品类时过期，违背"cli 加品类、插件零改动"的目标。
+ */
+export declare const CLI_SUBCOMMAND_RE: RegExp;
+/**
+ * shell 组合符：仅对**未被引号包裹的裸字符**生效。
+ *
+ * 这不是安全边界——spawn 一律 `shell: false`，argv 直接交给进程，
+ * 不存在 shell 解释。它只是一个启发式：识别"模型在拼 shell"并给出可操作的
+ * 报错，而不是把管道符当参数传下去、让 cli 报一个费解的错。
+ *
+ * 因此**刻意不包含** `{}` `()` `$`：
+ *   - `{` `}` 是 JSON 参数的必备字符（`--json '{"a":1}'`）
+ *   - `(` `)` 会出现在成员名里（如 `张三(jackzhang22)`）
+ *   - `$` 会出现在普通文本值里（如金额）
+ * 误杀合法参数的代价远大于放过一个怪参数——后者只会得到一个正常的 cli 报错。
+ */
+export declare const CLI_SHELL_METACHARS: RegExp;
+/**
+ * 允许从插件配置透传给 cli 的环境变量白名单。
+ *
+ * 仅供联调指向测试环境。注意这三个变量在 cli 侧受 `custom-endpoint`
+ * feature 门控（默认关闭），正式包上不生效。
+ *
+ * 模型提供的任何 env 一律拒绝——这里只接受插件配置来源。
+ */
+export declare const CLI_ENV_PASSTHROUGH: readonly ["WECOM_CLI_BASE_URL", "WECOM_CLI_AUTH_ENDPOINT", "WECOM_CLI_ADDITIONAL_HEADERS"];
+/** cli 侧错误码 */
+export declare const CLI_ERR: {
+    /** AuthRequiredError：无 token 或凭据不可解密 */
+    readonly AUTH_REQUIRED: 893999;
+    /** cli token 已过期（cli 会尝试自动刷新） */
+    readonly TOKEN_EXPIRED: 853004;
+    /** cli token 无效 */
+    readonly TOKEN_INVALID: 853005;
+    /** bot_id / secret 无效或签名校验失败 */
+    readonly BAD_CREDENTIAL: 853000;
+    /** 换取 token 频率超限 */
+    readonly RATE_LIMITED: 45009;
+};
+/** 需要触发"强制重签 + 重试一次"的错误码 */
+export declare const CLI_RESIGN_CODES: Set<number>;

package/dist/src/cli/const.js

@@ -0,0 +1,107 @@
+/**
+ * wecom-cli tool 常量
+ */
+/** tool 名（与 openclaw.plugin.json 的 contracts.tools 必须完全一致） */
+export const CLI_TOOL_NAME = "wecom-cli";
+/**
+ * 日志前缀。
+ *
+ * 必须与 agent 通过 exec 直接执行 `wecom-cli` 的情形可区分——
+ * 两者在日志里都叫 wecom-cli，排查"串号"问题时需要靠这个前缀分辨。
+ */
+export const CLI_LOG = "[wecom-cli:tool]";
+/** 单次业务命令 spawn 超时（实测热缓存调用仅 300~500ms） */
+export const CLI_TIMEOUT_MS = 45_000;
+/**
+ * `auth init` 的 spawn 超时，比业务命令短。
+ *
+ * 授权只有一次 HTTP 鉴权，30s 足够覆盖慢网。
+ * 更重要的是它是**唯一**能兜住"cli 写 keyring 时挂住"的手段：
+ * cli 的 save_key 对 keyring 失败只 warn，但 macOS Keychain 可能弹窗等待授权，
+ * 而 gateway 是后台进程 → 弹窗没人点 → 进程永久挂住。
+ */
+export const CLI_AUTH_TIMEOUT_MS = 30_000;
+/** 超时后 SIGTERM 到 SIGKILL 的宽限期 */
+export const CLI_KILL_GRACE_MS = 3_000;
+/** SIGKILL 后等待 close 事件的上限，超过后主动结束插件侧等待 */
+export const CLI_KILL_FORCE_WAIT_MS = 3_000;
+/** 返回给模型的输出上限。openclaw 无通用截断机制，必须由插件自己兜住 */
+export const CLI_MAX_OUTPUT_BYTES = 64 * 1024;
+/** 同一配置目录的重签冷却，避免 secret 失效时反复撞 45009 频率超限 */
+export const CLI_RESIGN_COOLDOWN_MS = 5 * 60 * 1000;
+/**
+ * 禁止的顶层子命令。
+ *
+ * `init` 无非交互入口，会拉起cliclack /扫码流程。
+ */
+export const CLI_FORBIDDEN_SUBCOMMANDS = new Set(["init"]);
+/**
+ * 禁止的 `auth` 子动作（`argv[0] === "auth"` 时检查 `argv[1]`）。
+ *
+ * 为什么单独拦：授权命令是 `auth init`，`argv[0]` 是 `auth` 而非 `init`，
+ * 不在上面的顶层禁用集内。而凭据现在完全由插件管理
+ * （`credentials.ts` 会按当前会话机器人 spawn `auth init --bot-id/--secret`），
+ * 模型自行触发只有两种结果：
+ *   - 不带凭据 → stderr 非 TTY 下走扫码分支 → 挂到超时
+ *   - 带凭据 → 它拿不到 secret，只能瞎猜；即便猜对也绕过了 openclaw 配置
+ * `auth show` / `auth status` 之类只读动作不受影响。
+ */
+export const CLI_FORBIDDEN_AUTH_ACTIONS = new Set(["init", "login", "logout", "bind", "unbind"]);
+/**
+ * argv[0] 合法格式。
+ *
+ * 这里刻意不用"品类白名单"——品类由服务端 discovery 动态下发，
+ * 白名单会在cli 新增品类时过期，违背"cli 加品类、插件零改动"的目标。
+ */
+export const CLI_SUBCOMMAND_RE = /^[a-z][a-z0-9_-]*$/;
+/**
+ * shell 组合符：仅对**未被引号包裹的裸字符**生效。
+ *
+ * 这不是安全边界——spawn 一律 `shell: false`，argv 直接交给进程，
+ * 不存在 shell 解释。它只是一个启发式：识别"模型在拼 shell"并给出可操作的
+ * 报错，而不是把管道符当参数传下去、让 cli 报一个费解的错。
+ *
+ * 因此**刻意不包含** `{}` `()` `$`：
+ *   - `{` `}` 是 JSON 参数的必备字符（`--json '{"a":1}'`）
+ *   - `(` `)` 会出现在成员名里（如 `张三(jackzhang22)`）
+ *   - `$` 会出现在普通文本值里（如金额）
+ * 误杀合法参数的代价远大于放过一个怪参数——后者只会得到一个正常的 cli 报错。
+ */
+export const CLI_SHELL_METACHARS = /[;|&`<>\n\r]/;
+/**
+ * 允许从插件配置透传给 cli 的环境变量白名单。
+ *
+ * 仅供联调指向测试环境。注意这三个变量在 cli 侧受 `custom-endpoint`
+ * feature 门控（默认关闭），正式包上不生效。
+ *
+ * 模型提供的任何 env 一律拒绝——这里只接受插件配置来源。
+ */
+export const CLI_ENV_PASSTHROUGH = [
+    "WECOM_CLI_BASE_URL",
+    "WECOM_CLI_AUTH_ENDPOINT",
+    "WECOM_CLI_ADDITIONAL_HEADERS",
+];
+/** cli 侧错误码 */
+export const CLI_ERR = {
+    /** AuthRequiredError：无 token 或凭据不可解密 */
+    AUTH_REQUIRED: 893999,
+    /** cli token 已过期（cli 会尝试自动刷新） */
+    TOKEN_EXPIRED: 853004,
+    /** cli token 无效 */
+    TOKEN_INVALID: 853005,
+    /** bot_id / secret 无效或签名校验失败 */
+    BAD_CREDENTIAL: 853000,
+    /** 换取 token 频率超限 */
+    RATE_LIMITED: 45009,
+};
+/** 需要触发"强制重签 + 重试一次"的错误码 */
+export const CLI_RESIGN_CODES = new Set([
+    CLI_ERR.AUTH_REQUIRED,
+    CLI_ERR.TOKEN_EXPIRED,
+    CLI_ERR.TOKEN_INVALID,
+    // 业务命令报 853000 = 磁盘凭据里的 secret 已失效（服务端禁用/轮换），
+    // 而 openclaw 配置里可能已是新 secret → 重签一次即可自愈。
+    // ⚠️ 注意不对称：`auth init` **自身**报 853000 表示"配置里的 secret 就是错的"，
+    // 那种情况绝不重试（见 credentials.ts），否则只是多打一次鉴权、离45009 更近。
+    CLI_ERR.BAD_CREDENTIAL,
+]);

package/dist/src/cli/credentials.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 登录态同步（ensureSynced）
+ *
+ * 职责：确保当前会话的 bot 在自己的配置目录里有可用登录态，返回该目录。
+ *
+ * **授权动作整体委托 cli**：spawn `wecom-cli auth init --bot-id <ID> --secret <SECRET>`
+ * （cli >= 0.1.9-build.149，stderr 非 TTY 时走直连授权分支）。
+ * 插件不再复刻凭据协议——签名算法、AES-GCM格式、`.encryption_key`、原子写
+ * 全部由 cli 负责。那些代码曾是整套方案最脆的部分：cli 改一处格式，
+ * 插件就静默解密失败，且表现为"未授权"，完全不指向真实原因。
+ *
+ * 本文件只保留 cli 里不存在的 **openclaw 侧策略**：
+ *   1. 目录隔离：每个 (botId, secret) 组合一个目录 → 多 bot 隔离 + secret 轮换即时生效
+ *   2. 短路：`auth init` 无幂等，每次调用都会打一次鉴权接口（45009 频率限制）
+ *   3. 并发去重 + 全局串行
+ *   4. 重签冷却熔断
+ */
+export declare class CliAuthError extends Error {
+    readonly errcode?: number | undefined;
+    constructor(message: string, errcode?: number | undefined);
+}
+export type CliEnvOverrides = Partial<Record<"WECOM_CLI_BASE_URL" | "WECOM_CLI_AUTH_ENDPOINT" | "WECOM_CLI_ADDITIONAL_HEADERS", string>>;
+/**
+ * 配置目录 = `<state>/wecom-cli/<safeBotId>-<sha8(botId:secret)>`。
+ *
+ * 为什么把 secret 指纹编进目录名，而不是另外维护一份 meta 文件：
+ * 删掉自实现的crypto 后插件不再解密 `credentials.enc`，也就永远读不到里面的
+ * secret，"磁盘上这份凭据是不是用当前配置签出来的"这个问题就无法回答。
+ * 把指纹放进目录名后，secret 一变目录就变 → 天然没有凭据 → 自动重新授权，
+ * 且走的是普通路径（不碰 force 熔断），所以**改配置立即生效**。
+ *
+ * 分隔符 `:` 是必需的：否则 `ab`+`c` 与 `a`+`bc` 会得到同一指纹。
+ *
+ * 已知取舍：`safeBotId` 的字符归一化可能碰撞（`a.b` 与 `a_b` 同名），
+ * 清理兄弟目录时可能误删另一个 bot 的目录。代价仅是"那个 bot 下次调用
+ * 重新授权一次"，不是数据丢失、更不是串号，因此接受。
+ */
+export declare function cliConfigDirFor(botId: string, secret: string): string;
+/**
+ * 确保指定 bot 的登录态已就绪，返回其配置目录。
+ *
+ * @param force 强制重新授权（业务命令报凭据类错误时的兜底），受冷却熔断约束。
+ *              注意 cli 没有 `--force` 参数，也不需要：`auth init` 本身无幂等，
+ *              每次调用都会重新签发，所以"force"只是跳过插件自己的短路。
+ */
+export declare function ensureSynced(params: {
+    binPath: string;
+    botId: string;
+    secret: string;
+    env?: CliEnvOverrides;
+    force?: boolean;
+}): Promise<string>;
+/** 仅用于测试 */
+export declare function resetCredentialState(): void;