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

package/dist/src/cli/credentials.js

@@ -0,0 +1,342 @@
+/**
+ * 登录态同步（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. 重签冷却熔断
+ */
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { CLI_AUTH_TIMEOUT_MS, CLI_KILL_FORCE_WAIT_MS, CLI_KILL_GRACE_MS, CLI_LOG, CLI_MAX_OUTPUT_BYTES, CLI_RESIGN_COOLDOWN_MS, } from "./const.js";
+import { resolveStateDir } from "../state-dir-resolve.js";
+import { spawn } from "./process-launcher.js";
+import { BoundedOutputCollector } from "./process-output.js";
+export class CliAuthError extends Error {
+    errcode;
+    constructor(message, errcode) {
+        super(message);
+        this.errcode = errcode;
+    }
+}
+const sha256Hex = (s) => crypto.createHash("sha256").update(s, "utf8").digest("hex");
+// ============================================================================
+// 路径
+// ============================================================================
+/** 目录名里secret 指纹的长度 */
+const FINGERPRINT_LEN = 8;
+/** 兄弟目录清理时用于识别"本插件生成的目录"的形状 */
+const DIR_SHAPE = new RegExp(`^(.+)-([0-9a-f]{${FINGERPRINT_LEN}})$`);
+const cliStateRoot = () => path.join(resolveStateDir(), "wecom-cli");
+const safeBotId = (botId) => botId.replace(/[^A-Za-z0-9_-]/g, "_");
+const credentialsPath = (dir) => path.join(dir, "credentials.enc");
+const keyPath = (dir) => path.join(dir, ".encryption_key");
+/**
+ * 配置目录 = `<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 function cliConfigDirFor(botId, secret) {
+    const fp = sha256Hex(`${botId}:${secret}`).slice(0, FINGERPRINT_LEN);
+    return path.join(cliStateRoot(), `${safeBotId(botId)}-${fp}`);
+}
+/**
+ * 短路判据：两个文件都在就认为已授权。
+ *
+ * 短路不是性能优化而是**必需项**：`auth init` 内部无任何幂等检查，
+ * 每次调用都会打一次 `fetch_auth`，而该接口有 45009 频率超限。
+ *
+ * `.encryption_key` 的存在性同样要查：文件缺失但密文还在时，cli 会回退到
+ * keyring 取密钥，而 keyring 可能被系统锁定/不可用 → 静默表现为"未授权"。
+ */
+function isAuthorized(dir) {
+    return fs.existsSync(credentialsPath(dir)) && fs.existsSync(keyPath(dir));
+}
+/**
+ * 清理同一 bot 的旧 secret 目录。
+ *
+ * 时机必须是**授权成功之后**：反过来先清理，一旦授权失败就连旧凭据都没了，
+ * 把"可降级"变成"直接不可用"。
+ *
+ * 双重约束防误删：父目录固定在 `<state>/wecom-cli/`，且名字必须严格匹配
+ * `<safeBotId>-<8位hex>`。清理是卫生工作而非正确性前提，失败只 warn。
+ */
+function cleanupSiblings(botId, currentDir) {
+    const root = cliStateRoot();
+    const prefix = safeBotId(botId);
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const m = DIR_SHAPE.exec(entry.name);
+        if (!m || m[1] !== prefix)
+            continue;
+        const full = path.join(root, entry.name);
+        if (full === currentDir)
+            continue;
+        try {
+            fs.rmSync(full, { recursive: true, force: true });
+            console.log(`${CLI_LOG} 已清理旧凭据目录 ${entry.name}`);
+        }
+        catch (err) {
+            console.warn(`${CLI_LOG} 清理旧凭据目录失败（不影响本次调用）${entry.name}: ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+// ============================================================================
+// auth init
+// ============================================================================
+/** 从 cli 的错误输出里提取 errcode，兼容两种形态 */
+function extractErrcode(stdout) {
+    try {
+        const parsed = JSON.parse(stdout);
+        // `{"error":{...}}` 是常规形态；裸 `{"errcode":...}` 来自 Transport::Api 的原样透传
+        const code = parsed?.error?.code ?? parsed?.errcode;
+        return typeof code === "number" ? code : null;
+    }
+    catch {
+        return null;
+    }
+}
+function extractMessage(stdout) {
+    try {
+        const parsed = JSON.parse(stdout);
+        return parsed?.error?.message ?? parsed?.errmsg ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `auth init` 全局串行（**跨 bot 也串**）。
+ *
+ * keyring 是全局资源，macOS Keychain 的并发写入行为不确定。
+ * 授权频率极低（首次 + 重签），全局串行的代价可忽略，换来行为确定性。
+ * 业务命令仍按 botId 串行，不受这里影响。
+ */
+let authChain = Promise.resolve();
+function serializeAuth(task) {
+    const next = authChain.then(task, task);
+    authChain = next.catch(() => undefined);
+    return next;
+}
+/**
+ * 执行非交互授权。
+ *
+ * 刻意**不复用** tool.ts 的 runCli：
+ *   - runCli 会把 `argv.join(" ")` 打进日志，那样 secret 会被写进 openclaw
+ *     日志文件并持久化/上报，比 `ps` 可见严重得多
+ *   - 两者的错误分类逻辑也不同（这里 exit 2 意味着"cli 版本不支持"）
+ *
+ * 门禁提醒：cli 只在 **stderr 非 TTY** 时才走 `--bot-id/--secret` 直连分支，
+ * 否则**静默忽略参数**并回退扫码。`stdio` 的 pipe 天然满足；
+ * stdin 用 `ignore` 而非 pipe——万一走到交互分支，让它立刻拿到 EOF 而不是挂着等输入。
+ */
+function spawnAuthInit(binPath, botId, secret, dir, env) {
+    return new Promise((resolve, reject) => {
+        const started = Date.now();
+        const child = spawn(binPath, ["auth", "init", "--bot-id", botId, "--secret", secret], {
+            shell: false,
+            cwd: resolveStateDir(),
+            env: {
+                PATH: process.env.PATH ?? "",
+                HOME: process.env.HOME ?? "",
+                ...(process.platform === "win32"
+                    ? { USERPROFILE: process.env.USERPROFILE ?? "", SystemRoot: process.env.SystemRoot ?? "" }
+                    : {}),
+                WECOM_CLI_CONFIG_DIR: dir,
+                WECOM_CLI_LOG_LEVEL: "warn",
+                // 端点与业务调用同源：授权和调用现在由同一个二进制、同一份 env 解析，
+                // 不可能再出现"授权在测试环境、调用在生产"的错配
+                ...env,
+            },
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const stdout = new BoundedOutputCollector(CLI_MAX_OUTPUT_BYTES, "head");
+        const stderr = new BoundedOutputCollector(CLI_MAX_OUTPUT_BYTES, "tail");
+        let timedOut = false;
+        let settled = false;
+        let graceTimer;
+        let forceWaitTimer;
+        child.stdout.on("data", (chunk) => stdout.append(chunk));
+        child.stderr.on("data", (chunk) => stderr.append(chunk));
+        const clearTimers = () => {
+            clearTimeout(killTimer);
+            if (graceTimer)
+                clearTimeout(graceTimer);
+            if (forceWaitTimer)
+                clearTimeout(forceWaitTimer);
+        };
+        const finish = (status) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimers();
+            resolve({
+                status,
+                stdout: stdout.result().text,
+                stderr: stderr.result().text,
+                ms: Date.now() - started,
+                timedOut,
+            });
+        };
+        const killTimer = setTimeout(() => {
+            timedOut = true;
+            if (child.exitCode === null && child.signalCode === null)
+                child.kill("SIGTERM");
+            graceTimer = setTimeout(() => {
+                if (child.exitCode === null && child.signalCode === null)
+                    child.kill("SIGKILL");
+                forceWaitTimer = setTimeout(() => {
+                    child.stdout.destroy();
+                    child.stderr.destroy();
+                    finish(child.exitCode);
+                }, CLI_KILL_FORCE_WAIT_MS);
+            }, CLI_KILL_GRACE_MS);
+        }, CLI_AUTH_TIMEOUT_MS);
+        child.on("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimers();
+            reject(err);
+        });
+        child.on("close", (status) => finish(status));
+    });
+}
+async function runAuthInit(binPath, botId, secret, dir, env) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const redact = (s) => (secret ? s.split(secret).join("***") : s);
+    const shortBot = `${botId.slice(0, 10)}…`;
+    console.log(`${CLI_LOG} 授权中 auth init --bot-id ${shortBot} --secret *** → ${path.basename(dir)}`);
+    const out = await spawnAuthInit(binPath, botId, secret, dir, env);
+    if (out.timedOut) {
+        throw new CliAuthError(`企业微信授权超时（${CLI_AUTH_TIMEOUT_MS / 1000}s）。` +
+            "常见原因：网络不可达，或系统钥匙串（Keychain）弹出了授权确认而无人响应。");
+    }
+    // exit 2 = clap 参数错误。插件依赖已锁定支持该能力的版本，所以这属于"不该发生"，
+    // 通常说明二进制被外部替换（binPath 指向旧二进制 / 全局安装的 cli）
+    if (out.status === 2) {
+        throw new CliAuthError("当前 wecom-cli 不支持非交互授权（缺少 --bot-id/--secret）。" +
+            "插件已锁定支持该能力的版本，出现此错误通常说明二进制被外部替换——" +
+            "请检查 `channels.wecom.cli.binPath` 是否指向了旧二进制或全局安装的 cli。");
+    }
+    if (out.status !== 0) {
+        // 错误在 stdout（cli 统一 `println!(err.render())`）；stderr 只有 cliclack 的
+        // 进度装饰与 ANSI 控制符，塞进用户文案会污染，只在 stdout 为空时兜底
+        const code = extractErrcode(out.stdout) ?? undefined;
+        const detail = extractMessage(out.stdout) ??
+            (out.stdout.trim() || out.stderr.trim() || `exit ${out.status}`).slice(0, 500);
+        throw new CliAuthError(`企业微信授权失败：${redact(detail)}${code != null ? `（errcode=${code}）` : ""}。` +
+            "请检查 openclaw 配置 `channels.wecom` 中的 botId / secret 是否正确。", code);
+    }
+    // 防御性：exit 0 但文件没落地（例如 cli 未来改了目录语义）
+    if (!isAuthorized(dir)) {
+        throw new CliAuthError(`wecom-cli 授权返回成功，但 ${dir} 下未生成凭据文件。` +
+            "可能是 cli 版本行为变更，请检查插件依赖的 @wecom/cli 版本。");
+    }
+    console.log(`${CLI_LOG} 授权成功 botId=${shortBot} (${out.ms}ms)`);
+    cleanupSiblings(botId, dir);
+}
+// ============================================================================
+// ensureSynced
+// ============================================================================
+/** 进程内并发去重，key = 配置目录（含 secret 指纹，改secret 不会复用旧 inflight） */
+const inflight = new Map();
+/** 上次实际开始强制重签的时间，用于服务端频控保护 */
+const lastResignAttempt = new Map();
+/** 上次强制重签成功的时间，仅用于区分尝试与成功的状态语义 */
+const lastResignSucceeded = new Map();
+/**
+ * 确保指定 bot 的登录态已就绪，返回其配置目录。
+ *
+ * @param force 强制重新授权（业务命令报凭据类错误时的兜底），受冷却熔断约束。
+ *              注意 cli 没有 `--force` 参数，也不需要：`auth init` 本身无幂等，
+ *              每次调用都会重新签发，所以"force"只是跳过插件自己的短路。
+ */
+export async function ensureSynced(params) {
+    const { binPath, botId, secret, env = {}, force = false } = params;
+    if (!botId?.trim() || !secret?.trim()) {
+        throw new CliAuthError("当前企业微信账号未配置 botId / secret，请检查 openclaw 配置 `channels.wecom`");
+    }
+    const dir = cliConfigDirFor(botId, secret);
+    if (!force && isAuthorized(dir))
+        return dir;
+    // 普通授权与强制重签都按目录复用同一个进行中的任务，避免并发重复签发。
+    const existing = inflight.get(dir);
+    if (existing)
+        return existing;
+    // 授权本身全局串行；冷却时间在任务真正开始时记录，不把排队时间算作重签尝试。
+    const task = serializeAuth(async () => {
+        // 排队期间可能已被前一个任务授权好了（同目录并发），再查一次省一次鉴权请求
+        if (!force && isAuthorized(dir))
+            return dir;
+        let attemptAt;
+        if (force) {
+            const last = lastResignAttempt.get(dir) ?? 0;
+            const elapsed = Date.now() - last;
+            if (elapsed < CLI_RESIGN_COOLDOWN_MS) {
+                const waitSec = Math.ceil((CLI_RESIGN_COOLDOWN_MS - elapsed) / 1000);
+                const succeeded = (lastResignSucceeded.get(dir) ?? 0) >= last;
+                const state = succeeded ? "凭据刚刚重新签发成功但仍然不可用" : "凭据刚刚尝试重新签发但未成功";
+                throw new CliAuthError(`${state}，${waitSec} 秒内不再重试，` +
+                    `以避免触发企业微信换取凭据的频率限制（45009）。` +
+                    `请检查 openclaw 配置 \`channels.wecom\` 中的 botId / secret 是否正确。`);
+            }
+            attemptAt = Date.now();
+            lastResignAttempt.set(dir, attemptAt);
+        }
+        try {
+            await runAuthInit(binPath, botId, secret, dir, env);
+            if (force)
+                lastResignSucceeded.set(dir, Date.now());
+            return dir;
+        }
+        catch (err) {
+            if (force) {
+                console.warn(`${CLI_LOG} 强制重签失败，保留本次尝试的冷却保护 ` +
+                    `(attemptAt=${attemptAt ?? "unknown"}): ${err instanceof Error ? err.message : String(err)}`);
+            }
+            throw err;
+        }
+    }).finally(() => {
+        if (inflight.get(dir) === task)
+            inflight.delete(dir);
+    });
+    inflight.set(dir, task);
+    return task;
+}
+/** 仅用于测试 */
+export function resetCredentialState() {
+    inflight.clear();
+    lastResignAttempt.clear();
+    lastResignSucceeded.clear();
+    authChain = Promise.resolve();
+}

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

@@ -0,0 +1,5 @@
+export { createWeComCliTool, type CreateWeComCliToolOptions } from "./tool.js";
+export { CLI_TOOL_NAME } from "./const.js";
+export { cliConfigDirFor, ensureSynced } from "./credentials.js";
+export { locateCliBinary } from "./locate.js";
+export { normalizeArgs, tokenize, assertSafeArgv, CliArgvError } from "./argv.js";

package/dist/src/cli/index.js

@@ -0,0 +1,5 @@
+export { createWeComCliTool } from "./tool.js";
+export { CLI_TOOL_NAME } from "./const.js";
+export { cliConfigDirFor, ensureSynced } from "./credentials.js";
+export { locateCliBinary } from "./locate.js";
+export { normalizeArgs, tokenize, assertSafeArgv, CliArgvError } from "./argv.js";

package/dist/src/cli/legacy-tool-warning.d.ts

@@ -0,0 +1,12 @@
+export interface ToolPolicyConfig {
+    profile?: string;
+    alsoAllow?: string[];
+}
+/**
+ * 仅在旧白名单确实导致 `wecom-cli` 不可见时提示迁移。
+ *
+ * 不做配置卫生检查：profile=full、已放行具体 tool、已放行插件 ID 时，
+ * 旧条目只是无害残留，不应制造启动噪音。
+ */
+export declare function shouldWarnLegacyToolAllow(tools: ToolPolicyConfig | undefined): boolean;
+export declare const LEGACY_TOOL_WARNING: string;

package/dist/src/cli/legacy-tool-warning.js

@@ -0,0 +1,20 @@
+const LEGACY_TOOL_NAME = "wecom_mcp";
+const CLI_TOOL_NAME = "wecom-cli";
+const PLUGIN_ID = "wecom-openclaw-plugin";
+/**
+ * 仅在旧白名单确实导致 `wecom-cli` 不可见时提示迁移。
+ *
+ * 不做配置卫生检查：profile=full、已放行具体 tool、已放行插件 ID 时，
+ * 旧条目只是无害残留，不应制造启动噪音。
+ */
+export function shouldWarnLegacyToolAllow(tools) {
+    if (tools?.profile === "full")
+        return false;
+    const allow = tools?.alsoAllow;
+    if (!Array.isArray(allow) || !allow.includes(LEGACY_TOOL_NAME))
+        return false;
+    return !allow.includes(CLI_TOOL_NAME) && !allow.includes(PLUGIN_ID);
+}
+export const LEGACY_TOOL_WARNING = "检测到旧工具白名单 `wecom_mcp`。该工具已移除，企微业务能力已统一迁移到 `wecom-cli`。" +
+    "请在 `tools.alsoAllow` 中添加 `wecom-cli`（旧条目可保留或自行删除），然后重启 Gateway。" +
+    "也可直接放行插件 ID：`wecom-openclaw-plugin`。";

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

@@ -0,0 +1,32 @@
+/**
+ * wecom-cli 二进制寻址
+ *
+ * 为什么不依赖 PATH：
+ * 1. 插件私有的 node_modules/.bin 不在 PATH 上
+ * 2. 更重要的是——PATH 上可能存在用户**全局安装**的 wecom-cli，
+ *    它绑定的是用户自己的 bot（默认目录 ~/.config/wecom）。
+ *    误用会导致"拿 A 企业的凭据查 B 企业的数据"，是静默的数据越权。
+ *    因此这里只接受"插件依赖内的二进制"或"配置显式指定的路径"。
+ */
+/** 按主包 package.json 的 bin 声明解析 shim，兼容字符串和对象两种形式。 */
+export declare function binCandidatesFromPackageManifest(root: string): string[];
+export type LocateResult = {
+    ok: true;
+    binPath: string;
+    source: string;
+} | {
+    ok: false;
+    tried: string[];
+};
+/**
+ * 定位 wecom-cli 二进制。
+ *
+ * 优先级：
+ * 1. 配置显式指定 `channels.wecom.cli.binPath`（联调期塞本地 cargo 产物用）
+ * 2. 平台子包 `<prefix>-<platform>-<arch>`（跳过 bin/wecom.js 那层 node shim，
+ *    每次调用少一次 node 冷启动）
+ * 3. 主包 `<prefix>` 自带的 bin
+ */
+export declare function locateCliBinary(explicitPath?: string): LocateResult;
+/** 仅用于测试：清除寻址缓存 */
+export declare function resetLocateCache(): void;

package/dist/src/cli/locate.js

@@ -0,0 +1,196 @@
+/**
+ * wecom-cli 二进制寻址
+ *
+ * 为什么不依赖 PATH：
+ * 1. 插件私有的 node_modules/.bin 不在 PATH 上
+ * 2. 更重要的是——PATH 上可能存在用户**全局安装**的 wecom-cli，
+ *    它绑定的是用户自己的 bot（默认目录 ~/.config/wecom）。
+ *    误用会导致"拿 A 企业的凭据查 B 企业的数据"，是静默的数据越权。
+ *    因此这里只接受"插件依赖内的二进制"或"配置显式指定的路径"。
+ */
+import { createRequire } from "node:module";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { CLI_LOG } from "./const.js";
+const require_ = createRequire(import.meta.url);
+/**
+ * npm 包名前缀候选。
+ *
+ * 联调期用内网包 `@tencent/wecom-cli`（discovery 分支、启用 custom-endpoint），
+ * 正式发布用公开包 `@wecom/cli`。两者平台子包命名规则不同，故依次尝试。
+ */
+const PACKAGE_PREFIXES = ["@tencent/wecom-cli", "@wecom/cli"];
+/** node platform/arch → 平台子包后缀 */
+function platformSuffix() {
+    const { platform, arch } = process;
+    if (platform === "darwin" && arch === "arm64")
+        return "darwin-arm64";
+    if (platform === "darwin" && arch === "x64")
+        return "darwin-x64";
+    if (platform === "linux" && arch === "arm64")
+        return "linux-arm64";
+    if (platform === "linux" && arch === "x64")
+        return "linux-x64";
+    if (platform === "win32" && arch === "x64")
+        return "win32-x64";
+    return null;
+}
+function binName() {
+    return process.platform === "win32" ? "wecom-cli.exe" : "wecom-cli";
+}
+/** 判断路径是否为可执行文件 */
+function isExecutable(p) {
+    try {
+        if (!fs.statSync(p).isFile())
+            return false;
+        if (process.platform !== "win32")
+            fs.accessSync(p, fs.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** 从平台包根目录推断原生二进制位置 */
+function binCandidatesFromPkgRoot(root) {
+    return [path.join(root, "bin", binName()), path.join(root, binName())];
+}
+/** 按主包 package.json 的 bin 声明解析 shim，兼容字符串和对象两种形式。 */
+export function binCandidatesFromPackageManifest(root) {
+    try {
+        const manifest = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+        const values = typeof manifest.bin === "string"
+            ? [manifest.bin]
+            : manifest.bin && typeof manifest.bin === "object"
+                ? [manifest.bin["wecom-cli"], ...Object.values(manifest.bin)]
+                : [];
+        const candidates = [];
+        for (const value of values) {
+            if (typeof value !== "string" || !value.trim())
+                continue;
+            const candidate = path.resolve(root, value);
+            const relative = path.relative(root, candidate);
+            if (relative.startsWith("..") || path.isAbsolute(relative))
+                continue;
+            if (!candidates.includes(candidate))
+                candidates.push(candidate);
+        }
+        return candidates;
+    }
+    catch {
+        return [];
+    }
+}
+let cached = null;
+/** 已打印过寻址结果的 binPath，避免每次调用都刷日志 */
+const logged = new Set();
+const EXPLICIT_SOURCE = "channels.wecom.cli.binPath";
+/**
+ * 打印一次寻址结果。
+ *
+ * 排查"是否误用了全局 cli"时，这是唯一的直接证据：
+ * `source` 为npm 包名 → 命中插件依赖内的二进制（正确）；
+ * `source` 为 binPath  → 来自配置逃生舱，需人工确认该路径不是全局安装。
+ */
+function logHit(binPath, source) {
+    if (logged.has(binPath))
+        return;
+    logged.add(binPath);
+    if (source === EXPLICIT_SOURCE) {
+        console.warn(`${CLI_LOG} 二进制寻址命中 source=${source} path=${binPath} ` +
+            "（来自配置显式指定，请确认它不是全局安装的 wecom-cli：" +
+            "配置目录仍由插件按会话机器人注入，但版本可能与 skills 不匹配）");
+        return;
+    }
+    console.log(`${CLI_LOG} 二进制寻址命中 source=${source} path=${binPath}`);
+}
+/**
+ * 定位 wecom-cli 二进制。
+ *
+ * 优先级：
+ * 1. 配置显式指定 `channels.wecom.cli.binPath`（联调期塞本地 cargo 产物用）
+ * 2. 平台子包 `<prefix>-<platform>-<arch>`（跳过 bin/wecom.js 那层 node shim，
+ *    每次调用少一次 node 冷启动）
+ * 3. 主包 `<prefix>` 自带的 bin
+ */
+export function locateCliBinary(explicitPath) {
+    if (explicitPath?.trim()) {
+        const p = path.resolve(explicitPath.trim());
+        if (isExecutable(p)) {
+            logHit(p, EXPLICIT_SOURCE);
+            return { ok: true, binPath: p, source: EXPLICIT_SOURCE };
+        }
+        return { ok: false, tried: [`${p} (配置指定，但不存在或不可执行)`] };
+    }
+    if (cached?.ok)
+        return cached;
+    const tried = [];
+    const suffix = platformSuffix();
+    for (const prefix of PACKAGE_PREFIXES) {
+        // 平台子包优先
+        if (suffix) {
+            const pkg = `${prefix}-${suffix}`;
+            try {
+                const root = path.dirname(require_.resolve(`${pkg}/package.json`));
+                for (const c of binCandidatesFromPkgRoot(root)) {
+                    if (isExecutable(c)) {
+                        cached = { ok: true, binPath: c, source: pkg };
+                        logHit(c, pkg);
+                        return cached;
+                    }
+                    tried.push(c);
+                }
+            }
+            catch {
+                tried.push(`${pkg} (未安装)`);
+            }
+        }
+        // 退化到主包：先从主包自身的依赖上下文找平台包（兼容 pnpm 严格布局），
+        // 最后按 package.json.bin 运行主包 shim。
+        try {
+            const manifestPath = require_.resolve(`${prefix}/package.json`);
+            const root = path.dirname(manifestPath);
+            if (suffix) {
+                const pkg = `${prefix}-${suffix}`;
+                try {
+                    const requireFromMain = createRequire(manifestPath);
+                    const platformRoot = path.dirname(requireFromMain.resolve(`${pkg}/package.json`));
+                    for (const c of binCandidatesFromPkgRoot(platformRoot)) {
+                        if (isExecutable(c)) {
+                            cached = { ok: true, binPath: c, source: pkg };
+                            logHit(c, pkg);
+                            return cached;
+                        }
+                        tried.push(c);
+                    }
+                }
+                catch {
+                    tried.push(`${pkg} (主包依赖中未找到)`);
+                }
+            }
+            const candidates = [
+                ...binCandidatesFromPackageManifest(root),
+                ...binCandidatesFromPkgRoot(root),
+            ];
+            for (const c of [...new Set(candidates)]) {
+                if (isExecutable(c)) {
+                    cached = { ok: true, binPath: c, source: prefix };
+                    logHit(c, prefix);
+                    return cached;
+                }
+                tried.push(c);
+            }
+        }
+        catch {
+            tried.push(`${prefix} (未安装)`);
+        }
+    }
+    const result = { ok: false, tried };
+    console.warn(`${CLI_LOG} 未找到 wecom-cli 二进制，尝试过：\n  ${tried.join("\n  ")}`);
+    return result;
+}
+/** 仅用于测试：清除寻址缓存 */
+export function resetLocateCache() {
+    cached = null;
+    logged.clear();
+}

package/dist/src/cli/process-launcher.d.ts

@@ -0,0 +1 @@
+export { spawn } from "node:child_process";

package/dist/src/cli/process-launcher.js

@@ -0,0 +1 @@
+export { spawn } from "node:child_process";

package/dist/src/cli/process-output.d.ts

@@ -0,0 +1,14 @@
+export type CollectedOutput = {
+    text: string;
+    originalBytes: number;
+    truncated: boolean;
+};
+export declare class BoundedOutputCollector {
+    private readonly maxBytes;
+    private readonly keep;
+    private buffer;
+    private originalBytes;
+    constructor(maxBytes: number, keep?: "head" | "tail");
+    append(chunk: Buffer | string): void;
+    result(): CollectedOutput;
+}