@zaofan/dsh-qqbot 1.6.9 → 1.7.1

package/dist/features/ext-capabilities.d.ts

@@ -0,0 +1,151 @@
+import type { Logger } from '../types.js';
+/** 媒体类型（与 sender.sendMedia 的 kind 对齐） */
+export type ExtMediaKind = 'image' | 'voice' | 'video' | 'file';
+/** 媒体源：URL 或本机绝对路径（二选一） */
+export interface ExtMediaSource {
+    url?: string;
+    localPath?: string;
+}
+/** 宿主 sender 里我们用到的子集（全部 duck-typing + 缺失即降级） */
+export interface ExtSenderLike {
+    sendText?: (target: unknown, text: string) => Promise<unknown>;
+    sendMarkdown?: (target: unknown, content: string) => Promise<unknown>;
+    sendMarkdownWithKeyboard?: (target: unknown, content: string, keyboard?: unknown) => Promise<unknown>;
+    sendMedia?: (target: unknown, kind: string, source: ExtMediaSource) => Promise<unknown>;
+}
+/** 官方 API 调用结果（与 GroupAdminClient.apiCall 同形） */
+export type ExtApiResult = {
+    ok: true;
+    data: unknown;
+} | {
+    ok: false;
+    err: {
+        code: string;
+        human: string;
+    };
+};
+/** 构造能力包的依赖（能给的都给，给不了的自动降级为「调用返回 false」） */
+export interface ExtCapsDeps {
+    /** 数据根（store 落盘用）。空 = store 不可用 */
+    dataRoot?: string;
+    logger?: Logger;
+    /** bot 凭证（api / appId / appSecret 用） */
+    appId?: string;
+    appSecret?: string;
+    /** 主人 openid 列表（user.isOwner / owners） */
+    owners?: string[];
+    /** 当前会话的发送器与目标（没有 = 发送类能力不可用） */
+    sender?: ExtSenderLike;
+    replyTarget?: unknown;
+    /** 当前会话的 agent（appendSilent / appendWake 用） */
+    agent?: {
+        session?: unknown;
+        followup?: (msg: unknown) => unknown;
+    } | undefined;
+    /** 当前会话标识 + 称呼（peer / user 展示用） */
+    scope?: string;
+    peerId?: string;
+    /** 触发者（命令的发送者 / 工具的调用会话所属人） */
+    actorOpenid?: string;
+    actorName?: string;
+    /** 带 token 的官方 API 调用（注入了就优先用它，否则用本模块自带的 token 管理） */
+    apiCall?: (method: 'GET' | 'POST' | 'PATCH' | 'DELETE', path: string, body?: unknown) => Promise<ExtApiResult>;
+    /** 扩展名（store 文件名 / 日志前缀） */
+    selfName?: string;
+    /** 扩展种类：tools / commands（决定 store 落在哪个子目录） */
+    kind?: string;
+    /**
+     * ★ 插件 ctx（"遥控器"）—— 见 {@link ExtCapabilities.kernel}。
+     * 由调用方把插件的 cordis Context 原样传进来；不传 = 没有这个能力。
+     */
+    kernel?: unknown;
+    /**
+     * 自重启实现（仅供测试注入；生产走内置 `selfRestart`）。
+     * ⚠️ 真跑它会 spawn 一个助手去 kill 宿主进程 —— 测试里**必须**用这个接缝替换。
+     */
+    restartImpl?: (delayMs?: number) => boolean;
+}
+/** 能力包对外形状（写扩展时看到的就是这个） */
+export interface ExtCapabilities {
+    appId: string;
+    appSecret: string;
+    at(id: string): string;
+    text(s: string): Promise<boolean>;
+    markdown(s: string): Promise<boolean>;
+    markdownCard(s: string, keyboard?: unknown): Promise<boolean>;
+    media(kind: ExtMediaKind, source: ExtMediaSource): Promise<boolean>;
+    image(source: ExtMediaSource | string): Promise<boolean>;
+    voice(source: ExtMediaSource | string): Promise<boolean>;
+    video(source: ExtMediaSource | string): Promise<boolean>;
+    file(source: ExtMediaSource | string): Promise<boolean>;
+    api(path: string, opts?: {
+        method?: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+        body?: unknown;
+    }): Promise<ExtApiResult>;
+    store: {
+        load<T = unknown>(): T | undefined;
+        save(value: unknown): boolean;
+        path: string;
+    };
+    appendSilent(text: string): Promise<boolean>;
+    appendWake(text: string): Promise<boolean>;
+    canAppendSilent(): boolean;
+    user: {
+        openid: string;
+        name: string;
+        isOwner: boolean;
+    };
+    owners: string[];
+    peer: {
+        scope: string;
+        peerId: string;
+    };
+    log(...args: unknown[]): void;
+    /**
+     * ★ **内核句柄（"遥控器"）**= 本插件自己的 cordis Context（`ctx`）。
+     *
+     * 拿到它就能做**受控能力包做不到的事**：
+     * ```js
+     * const ctx = env.kernel;
+     * ctx.get('sessions')                 // 读/建会话
+     * ctx.get('tools')                    // 工具注册表
+     * ctx.compaction.compactNow(a, s, id) // 调宿主的上下文压缩
+     * ctx.on('session/event', fn)         // 订阅宿主事件
+     * ctx.webServer.register({ path, handler })  // 开一个 HTTP 路由
+     * ```
+     *
+     * ⚠️ **三条代价（用之前先读）**：
+     * 1. **跟随宿主版本**：`ctx` 的形状由 dsh 决定，宿主升级可能让这段代码失效 ——
+     *    所以「成品能力」才是主路，`kernel` 是**逃生舱**。
+     * 2. **注册要自己收尾**：`ctx.tools.register()` / `ctx.on()` / `ctx.webServer.register()`
+     *    都返回 disposer；不 dispose 的话，热重载会**不断累积**（本插件自己也踩过这个坑，
+     *    见维护手册铁律 8：disposer 要存到跨模块实例可见的地方）。
+     * 3. **全权限**：它等价于"把遥控器交出去"。这是**你自己机器上、你自己写的代码**，
+     *    所以本来就是你的权利 —— 但别把它转手给不信任的代码。
+     */
+    kernel: unknown;
+    /**
+     * 触发宿主自重启（等价于内置的 `/bot-restart`）。
+     *
+     * 实现直接复用插件自己的 `selfRestart()` —— 它已经填平了所有坑
+     * （动态识别启动命令、**强制补 `--no-open`**、助手写系统 tmpdir 避开中文路径、
+     * detached+unref 保证宿主被杀后照样能拉起）。**别自己 spawn，很容易写错。**
+     *
+     * @param opts.requireOwner - 默认 `true`：只有主人（`env.user.isOwner`）触发才生效，
+     *   防止 AI 被群友一句话钓去重启机器人。**你自己的场景要谁都能重启，就传 `false`。**
+     * @param opts.delayMs - 延迟多久开始（默认 1600ms，给回执留时间）
+     * @returns 是否已触发（不代表重启成功，只代表助手已脱手启动）
+     */
+    restart(opts?: {
+        requireOwner?: boolean;
+        delayMs?: number;
+    }): boolean;
+}
+/**
+ * 造一份扩展能力包。**永远不会抛**：拿不到的依赖 → 对应能力返回 false / 空值。
+ *
+ * @param deps - 见 {@link ExtCapsDeps}
+ * @returns 能力包（见 {@link ExtCapabilities}）
+ */
+export declare function makeExtCaps(deps: ExtCapsDeps): ExtCapabilities;
+//# sourceMappingURL=ext-capabilities.d.ts.map

package/dist/features/ext-capabilities.d.ts.map

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

package/dist/features/ext-capabilities.js

@@ -0,0 +1,308 @@
+/**
+ * ext-capabilities.ts — 给「用户扩展」用的统一能力包（2026-10-06）
+ *
+ * ── 为什么有这个东西 ───────────────────────────────────────────────
+ * 插件有三套用户扩展：`commands/`（自定义斜杠命令）、`tools/`（自定义 QQ 工具）、
+ * `botplay/`（卡片事件模块）。三套的能力面原本**严重不均**：
+ *
+ *   · botplay 卡片：`card()` / `emit` / `markdown` / `image` / `at` / `store` /
+ *     `api()` / **`appId`+`appSecret`** / `appendWake` —— 精装版
+ *   · 扩展工具  ：只有裸 `{cwd, manager, sender, replyTarget, exec, ctx, logger}`
+ *                 —— 想发张卡得自己 `sender.sendMarkdown(target, text)`，
+ *                    以至于主人不得不专门写一个 `send_md.mjs` 来干这一件事
+ *   · 自定义命令：**最窄**，只有一个消息 ctx
+ *
+ * 本模块把「大家都该有」的那部分做成**一套**，三处注入同一个面：
+ * 让**第三方作者**写扩展时不用再自己接生。
+ *
+ * ── 拿到什么（写扩展时直接 `env.xxx` / `caps.xxx`）───────────────────
+ *   发送： text(s) / markdown(s) / markdownCard(s) / image(src) / voice(src) /
+ *          video(src) / file(src) / media(kind, src) / at(openid)
+ *   官方 API： appId / appSecret / api(path, {method, body})
+ *              —— ★ 自带 token 与 2 小时缓存，**不依赖 groupAdmin 开关**
+ *   持久化： store.load() / store.save(obj)   （落数据根，插件升级不丢）
+ *   上下文： appendSilent(text) / appendWake(text)   ← 见下面「安全」
+ *   身份：  user.{openid,name,isOwner} / owners / peer.{scope,peerId}
+ *   杂项：  log(...)
+ *
+ * ── ★ 安全：appendSilent 必须过表面守卫 ─────────────────────────────
+ * dsh 的 v4 会话格式要求 `system/message`（人设）是 surface 的**第一个节点**
+ * （见 `session/surface-guard.ts` 的事故记录）。全新会话里人设还没落，
+ * 此时静默 append 会**把整份会话日志写废**。
+ * ⇒ 本模块的 `appendSilent` **一律先过 `canSilentlyAppend()`**，不安全就**拒绝执行**
+ *   并返回 false（内容不丢：调用方可以改走 `appendWake`）。
+ *   `appendWake` 走的是正常回合（dsh 会先补人设），所以**天然安全**。
+ *
+ * ── 设计取舍 ───────────────────────────────────────────────────
+ * 不直接复用 `botplay-ext.ts` 的 `makeExtContext()`：那个 ctx 带 `card()` /
+ * `clickCount` / `reloadSelf` 等**卡片专属**成员，给工具/命令用只会让作者困惑。
+ * 这里只做「三套共有」的那一层，实现上仍是同一批底层原语（sender / session / token）。
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { canSilentlyAppend } from '../session/surface-guard.js';
+import { selfRestart } from '../commands/exit.js';
+// ── 自带 token 管理（不依赖 groupAdmin 开关，第三方用户也能用）──────────────
+//   key = appId；value = { token, expireAt }。token 官方有效期 ~7200s，这里按 60s 余量提前过期。
+const tokenCache = new Map();
+async function fetchAccessToken(appId, appSecret) {
+    if (!appId || !appSecret)
+        return '';
+    const hit = tokenCache.get(appId);
+    if (hit && Date.now() < hit.expireAt)
+        return hit.token;
+    const res = await fetch('https://bots.qq.com/app/getAppAccessToken', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ appId, clientSecret: appSecret }),
+    });
+    const data = (await res.json());
+    const token = String(data?.access_token ?? '');
+    if (!token)
+        throw new Error('拿 access_token 失败(检查 appId/appSecret)');
+    const ttl = Number(data?.expires_in ?? 7200);
+    tokenCache.set(appId, { token, expireAt: Date.now() + Math.max(60, ttl - 60) * 1000 });
+    return token;
+}
+/** 「url 或本地路径」→ 媒体源对象（第三方作者常直接传字符串） */
+function toMediaSource(src) {
+    if (typeof src === 'string') {
+        return /^https?:\/\//i.test(src) ? { url: src } : { localPath: src };
+    }
+    return src ?? {};
+}
+/**
+ * 造一份扩展能力包。**永远不会抛**：拿不到的依赖 → 对应能力返回 false / 空值。
+ *
+ * @param deps - 见 {@link ExtCapsDeps}
+ * @returns 能力包（见 {@link ExtCapabilities}）
+ */
+export function makeExtCaps(deps) {
+    const logger = deps.logger;
+    const self = String(deps.selfName ?? 'ext');
+    const kind = String(deps.kind ?? 'ext');
+    const owners = Array.isArray(deps.owners) ? deps.owners.map(String) : [];
+    const appId = String(deps.appId ?? '');
+    const appSecret = String(deps.appSecret ?? '');
+    const actorOpenid = String(deps.actorOpenid ?? '');
+    const storeDir = deps.dataRoot ? join(deps.dataRoot, '.qqbot-extensions', kind, 'data') : '';
+    const storeFile = storeDir ? join(storeDir, `${self.replace(/\.(mjs?|cjs|js)$/i, '')}.json`) : '';
+    const warn = (what, err) => {
+        try {
+            logger?.warn?.(`[ext-caps] ${self} ${what} 失败: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        catch { /* 日志失败忽略 */ }
+    };
+    const send = async (what, fn) => {
+        try {
+            await fn();
+            return true;
+        }
+        catch (err) {
+            warn(what, err);
+            return false;
+        }
+    };
+    return {
+        appId,
+        appSecret,
+        // ── @人 ────────────────────────────────────────────────────────
+        at: (id) => `<@${String(id ?? '')}>`,
+        // ── 发送 ───────────────────────────────────────────────────────
+        text: (s) => {
+            const t = String(s ?? '');
+            // ⚠️ 用 trim 判"空"，但发出去的仍是原文（不裁剪内容语义）
+            if (!t.trim() || !deps.sender?.sendText)
+                return Promise.resolve(false);
+            return send('text', () => deps.sender.sendText(deps.replyTarget, t));
+        },
+        markdown: (s) => {
+            const t = String(s ?? '');
+            if (!t.trim() || !deps.sender?.sendMarkdown)
+                return Promise.resolve(false);
+            return send('markdown', () => deps.sender.sendMarkdown(deps.replyTarget, t));
+        },
+        markdownCard: (s, keyboard) => {
+            const t = String(s ?? '');
+            if (!t.trim())
+                return Promise.resolve(false);
+            if (deps.sender?.sendMarkdownWithKeyboard) {
+                return send('markdownCard', () => deps.sender.sendMarkdownWithKeyboard(deps.replyTarget, t, keyboard));
+            }
+            if (deps.sender?.sendMarkdown)
+                return send('markdownCard→markdown', () => deps.sender.sendMarkdown(deps.replyTarget, t));
+            return Promise.resolve(false);
+        },
+        media: (k, source) => {
+            if (!deps.sender?.sendMedia)
+                return Promise.resolve(false);
+            return send(`media(${k})`, () => deps.sender.sendMedia(deps.replyTarget, k, toMediaSource(source)));
+        },
+        image: (source) => {
+            if (!deps.sender?.sendMedia)
+                return Promise.resolve(false);
+            return send('image', () => deps.sender.sendMedia(deps.replyTarget, 'image', toMediaSource(source)));
+        },
+        voice: (source) => {
+            if (!deps.sender?.sendMedia)
+                return Promise.resolve(false);
+            return send('voice', () => deps.sender.sendMedia(deps.replyTarget, 'voice', toMediaSource(source)));
+        },
+        video: (source) => {
+            if (!deps.sender?.sendMedia)
+                return Promise.resolve(false);
+            return send('video', () => deps.sender.sendMedia(deps.replyTarget, 'video', toMediaSource(source)));
+        },
+        file: (source) => {
+            if (!deps.sender?.sendMedia)
+                return Promise.resolve(false);
+            return send('file', () => deps.sender.sendMedia(deps.replyTarget, 'file', toMediaSource(source)));
+        },
+        // ── 官方 API（自带 token；注入了 apiCall 就优先用注入的）──────────
+        api: async (path, opts) => {
+            const method = (opts?.method ?? 'GET');
+            const p = String(path ?? '');
+            if (!p)
+                return { ok: false, err: { code: 'BAD_PATH', human: 'path 不能为空' } };
+            if (typeof deps.apiCall === 'function') {
+                try {
+                    return await deps.apiCall(method, p, opts?.body);
+                }
+                catch (err) {
+                    warn('api(injected)', err);
+                }
+            }
+            try {
+                const token = await fetchAccessToken(appId, appSecret);
+                if (!token)
+                    return { ok: false, err: { code: 'NO_CREDENTIALS', human: '未配置 appId/appSecret' } };
+                const res = await fetch(`https://api.bot.qq.com${p.startsWith('/') ? p : `/${p}`}`, {
+                    method,
+                    headers: { authorization: `QQBot ${token}`, 'content-type': 'application/json' },
+                    ...(opts?.body === undefined ? {} : { body: JSON.stringify(opts.body) }),
+                });
+                const text = await res.text();
+                let data = text;
+                try {
+                    data = JSON.parse(text);
+                }
+                catch { /* 非 JSON 原样返回 */ }
+                if (!res.ok)
+                    return { ok: false, err: { code: String(res.status), human: `HTTP ${res.status}: ${text.slice(0, 200)}` } };
+                return { ok: true, data };
+            }
+            catch (err) {
+                return { ok: false, err: { code: 'THROW', human: err instanceof Error ? err.message : String(err) } };
+            }
+        },
+        // ── 持久化（落数据根，插件升级/重装不丢）─────────────────────────
+        store: {
+            path: storeFile,
+            load() {
+                if (!storeFile)
+                    return undefined;
+                try {
+                    if (!existsSync(storeFile))
+                        return undefined;
+                    return JSON.parse(readFileSync(storeFile, 'utf8'));
+                }
+                catch (err) {
+                    warn('store.load', err);
+                    return undefined;
+                }
+            },
+            save(value) {
+                if (!storeFile)
+                    return false;
+                try {
+                    mkdirSync(dirname(storeFile), { recursive: true });
+                    writeFileSync(storeFile, JSON.stringify(value ?? null, null, 2), 'utf8');
+                    return true;
+                }
+                catch (err) {
+                    warn('store.save', err);
+                    return false;
+                }
+            },
+        },
+        // ── 上下文（★ appendSilent 必须过表面守卫）───────────────────────
+        appendSilent: async (text) => {
+            const t = String(text ?? '').trim();
+            if (!t)
+                return false;
+            const session = deps.agent?.session;
+            if (!session || typeof session.append !== 'function')
+                return false;
+            if (!canSilentlyAppend(session)) {
+                try {
+                    logger?.debug?.('[ext-caps] appendSilent 被拒：该会话人设尚未落盘(surface 首节点不是 system/message)，硬写会报废会话日志');
+                }
+                catch { /* ignore */ }
+                return false;
+            }
+            try {
+                session.append('user/message', createUserMessage({ content: [{ type: 'text', text: t }], source: { kind: 'user' } }), { surfaceOp: 'append' });
+                return true;
+            }
+            catch (err) {
+                warn('appendSilent', err);
+                return false;
+            }
+        },
+        appendWake: async (text) => {
+            const t = String(text ?? '').trim();
+            if (!t)
+                return false;
+            const agent = deps.agent;
+            // 走正常回合：dsh 会先补人设 → 天然安全，不需要表面守卫
+            if (agent && typeof agent.followup === 'function') {
+                try {
+                    agent.followup(createUserMessage({ content: [{ type: 'text', text: t }], source: { kind: 'user' } }));
+                    return true;
+                }
+                catch (err) {
+                    warn('appendWake', err);
+                    return false;
+                }
+            }
+            // 没有 followup 能力 ⇒ 退回静默 append（仍受守卫保护）
+            return false;
+        },
+        canAppendSilent: () => canSilentlyAppend(deps.agent?.session),
+        // ── 身份 ───────────────────────────────────────────────────────
+        user: {
+            openid: actorOpenid,
+            name: String(deps.actorName ?? ''),
+            isOwner: actorOpenid !== '' && owners.includes(actorOpenid),
+        },
+        owners,
+        peer: { scope: String(deps.scope ?? ''), peerId: String(deps.peerId ?? '') },
+        log: (...args) => {
+            try {
+                logger?.info?.(`[ext:${self}] ${args.map((a) => (typeof a === 'string' ? a : JSON.stringify(a))).join(' ')}`);
+            }
+            catch { /* ignore */ }
+        },
+        // ── 内核句柄（遥控器）────────────────────────────────────────────
+        kernel: deps.kernel,
+        // ── 宿主自重启（复用内置 /bot-restart 的实现，别自己 spawn）──────
+        restart: (opts) => {
+            const requireOwner = opts?.requireOwner !== false; // 默认：仅主人
+            const isOwner = actorOpenid !== '' && owners.includes(actorOpenid);
+            if (requireOwner && !isOwner) {
+                try {
+                    logger?.warn?.(`[ext-caps] ${self} restart 被拒：仅主人可触发（想放开就传 { requireOwner: false }）`);
+                }
+                catch { /* ignore */ }
+                return false;
+            }
+            try {
+                logger?.warn?.(`[ext-caps] ${self} 触发了宿主自重启（owner=${isOwner} actor=${actorOpenid || '(未知)'}）`);
+            }
+            catch { /* ignore */ }
+            return (deps.restartImpl ?? selfRestart)(opts?.delayMs);
+        },
+    };
+}
+//# sourceMappingURL=ext-capabilities.js.map

package/dist/features/ext-capabilities.js.map

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

package/dist/gateway/bootstrap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../src/gateway/bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAKnD,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAK5E,OAAO,KAAK,EAAE,aAAa,EAAsB,MAAM,cAAc,CAAC;AACtE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAqC1C,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAmnBf"}
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../src/gateway/bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAKnD,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAK5E,OAAO,KAAK,EAAE,aAAa,EAAsB,MAAM,cAAc,CAAC;AACtE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAqC1C,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAqnBf"}

package/dist/gateway/bootstrap.js

@@ -127,7 +127,7 @@ export async function bootstrapGateway(ctx, agents, config, logger) {
     });
     logger.info(`QQBot SDK initialized (UA: ${userAgent})${watchJoinRequests ? ' [watchJoinRequests: GROUP_MEMBER_EVENT 已订阅]' : ''}`);
     // ── 中间件链 ──
-    await setupMiddlewares(bot, config, manager, logger);
+    await setupMiddlewares(bot, config, manager, logger, ctx);
     // ── 入站：经过中间件链后的消息交给 dsh agent ──
     bot.on('message', async (mCtx) => {
         const msg = mCtx.message;
@@ -466,6 +466,8 @@ export async function bootstrapGateway(ctx, agents, config, logger) {
     // ⚠️ 必须与事件文件同源(dataRootOf), 否则面板报的路径与实际加载的不是一处, 主人改错文件还找不到原因
     () => dataRootOf(config));
     registerBotplayController(myNs, botplayController);
+    // ★ 内核句柄：把插件 ctx 交给 botplay（卡片 ctx.kernel / 与扩展工具·命令对齐）
+    botplayController.setKernel(ctx);
     // 昵称兜底(2026-10-05 主人定: "兜底的时候用 api，其余的时候用台账"):
     //   台账/会话壳都查不到时, 后台调官方「获取群成员信息」接口拿 username。
     //   ⚠️ 该接口官方标注「内邀接入中」(11253=无权限) ⇒ 失败静默、只记一行日志。