@zaofan/dsh-qqbot 1.10.9 → 1.10.11

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

@@ -0,0 +1,238 @@
+import type { Logger } from '../types.js';
+/** 出站扩展子目录名（与 inbound / hooks / tools / botplay 并列的第六套） */
+export declare const EXT_OUTBOUND_SUBDIR = "outbound";
+/** 其他扩展取"出站操控器"的全局键（Symbol.for ⇒ 跨模块实例单例，同 ext-inbound 的 HANDLER_KEY 手法） */
+export declare const OUTBOUND_API_KEY: unique symbol;
+/** 一次出站的载体（正文 + 元信息），扩展可读写 `text` */
+export interface OutboundCtx {
+    /** 本条出站正文（扩展可读；改它请用 rewrite()） */
+    text: string;
+    /** 解析后的段（rich-media.parseOutbound 的结果；拿不到时是空数组） */
+    segments: unknown[];
+    /** 这条出站是什么 */
+    kind: 'text' | 'markdown' | 'media' | 'card' | 'forward' | 'other';
+    /** 回复目标（被动回复优先靠它自带的 msgId） */
+    target: {
+        scope?: string;
+        peerId?: string;
+        msgId?: string;
+    } | null;
+    /** 本回合 id（同一回合的所有正文块共享；没有回合概念时是空串） */
+    turnId: string;
+    /** 本回合内的第几个正文块（从 0 起） */
+    chunkIndex: number;
+    /** **是否本回合最后一个正文块** —— 示范（按正文配表情包）就看它，避免每块都配一张 */
+    isLastChunk: boolean;
+    /** 当前发送器（发媒体/文本用） */
+    sender: unknown;
+    /** 数据根 */
+    dataRoot: string;
+    /** 主人 openid 白名单 */
+    owners: string[];
+    /** 带 token 的官方 API 调用 */
+    apiCall?: unknown;
+    /** 插件自己的 cordis Context（能力包里的 kernel） */
+    kernel?: unknown;
+    /** 插件 logger */
+    logger: Logger;
+    /** 改写本条出站正文；返回 false = 已经消灭了（改也没意义） */
+    rewrite(newText: string): boolean;
+    /** 消灭本条出站（**之后不要调 next()**，否则引擎会记 warn）；返回 false = 已熔断/被拒 */
+    annihilate(reason: string): boolean;
+    /**
+     * ★★ 2026-10-16 主人定的架构：**丢后台** ★★
+     *
+     * 出站链与"正文发送"唯一的联系就是**读一眼内容**；任何"选图/算分/发媒体"这类重活
+     * **一律丢到后台独立跑**，绝不 await、绝不阻塞正文 —— 正文该多快就多快，
+     * 图片是**事后补发**的（走 `ctx.sendMedia` 的"先被动后主动"独立通道）。
+     *
+     * 用法（扩展里）：
+     * ```js
+     * ctx.background(async () => {
+     *   const kw = await 选图耗时逻辑(ctx.text);
+     *   await ctx.sendMedia({ path });
+     * });
+     * return next();     // ← 立刻放行正文，不等上面跑完
+     * ```
+     */
+    /**
+     * ★★ 2026-10-16：**这一趟是哪个阶段**（主人实测指出：一段回复有多段正文，
+     *   每段都各走一次 `sendRichOutbound` ⇒ "第一段"根本不是回合最后一块）★★
+     *   · `'send'`    = 正文**发送前**（挂载点在 `sendRichOutbound` 入口）—— 只做**改写/消灭**
+     *                   这类必须同步生效的事；**配图不要放这里**。
+     *   · `'turnEnd'` = **回合真正结束**（挂载点在 `outbound.ts` 的 `turn/end`：flush 之后、
+     *                   与 passive 收尾同一时机）—— 这里 `text` 就是 `turnBlocks.last`，
+     *                   **是这一回合权威的最后一块正文**，且正文早发完了，配图随便慢。
+     */
+    phase: 'send' | 'turnEnd';
+    background(task: () => unknown): void;
+    /** 额外发一条媒体（**先被动后主动**）；返回是否成功 */
+    sendMedia(input: {
+        path?: string;
+        url?: string;
+        text?: string;
+    }): Promise<boolean>;
+    /** 额外发一条文本（**先被动后主动**）；返回是否成功 */
+    send(text: string, opts?: {
+        adaptive?: boolean;
+    }): Promise<boolean>;
+    /** 审计/诊断一行（走 logger.debug + 落盘审计，最坏也只是丢日志，绝不抛） */
+    note(msg: string): void;
+    emit?: (text: string) => unknown;
+    markdown?: (text: string) => unknown;
+    image?: (url: string) => unknown;
+    media?: (kind: string, source: string, text?: string) => unknown;
+    store?: {
+        load: (k: string) => unknown;
+        save: (k: string, v: unknown) => unknown;
+    };
+    identity?: {
+        user?: unknown;
+        owners?: string[];
+        peer?: unknown;
+    };
+    api?: (path: string) => Promise<unknown>;
+    appendSilent?: (text: string) => unknown;
+    appendWake?: (text: string) => unknown;
+}
+/** 出站中间件签名：与 inbound 的 `(ctx, next)` 对称 */
+export type OutboundMiddleware = (ctx: OutboundCtx, next: () => Promise<void>) => unknown;
+/** 一个已装载的出站扩展 */
+export interface OutboundExtension {
+    /** 文件名（含扩展名） */
+    file: string;
+    /** 绝对路径 */
+    path: string;
+    /** 展示名：模块导出的 `name` 优先，否则去扩展名的文件名 */
+    name: string;
+    /** 中间件 */
+    middleware: OutboundMiddleware;
+    /** 可选：`dispose()` */
+    dispose?: () => unknown;
+}
+/** 一次装载的汇总 */
+export interface OutboundLoadResult {
+    total: number;
+    skipped: number;
+    /** 按文件名升序（直接交给 runOutboundChain） */
+    middleware: OutboundMiddleware[];
+    extensions: OutboundExtension[];
+    files: string[];
+}
+export interface LoadOutboundOptions {
+    dataRoot: string;
+    logger: Logger;
+}
+/** 跑链的入参（除正文外都可缺，缺了对应能力降级） */
+export interface RunOutboundOptions {
+    dataRoot?: string;
+    owners?: string[];
+    sender?: unknown;
+    target?: unknown;
+    turnId?: string;
+    chunkIndex?: number;
+    isLastChunk?: boolean;
+    kind?: OutboundCtx['kind'];
+    segments?: unknown[];
+    apiCall?: unknown;
+    kernel?: unknown;
+    logger?: Logger;
+    /** ★ 2026-10-16：'send'（正文发送前，默认）或 'turnEnd'（回合结束，可做配图） */
+    phase?: 'send' | 'turnEnd';
+}
+export declare function outboundExtensionsDir(dataRoot: string): string;
+/** 配置出站扩展的数据根与日志器（插件启动时调一次；热刷时复用） */
+export declare function configureOutboundExtensions(opts: {
+    dataRoot: string;
+    logger: Logger;
+}): void;
+/** 重新装载（供热刷用）：没配置过则安静返回空结果 */
+export declare function reloadOutboundExtensions(): Promise<OutboundLoadResult>;
+/**
+ * 扫描 `{dataRoot}/.qqbot-extensions/outbound/*.mjs` 并装载。
+ *
+ * 目录不存在 / 为空 → 返回空结果、**不打日志**；
+ * 单文件失败 → 只 warn 并继续；本函数**永不抛出**。
+ * 重新调用 = 热重载（`loaded` 整体替换）。
+ */
+export declare function loadOutboundExtensions(opts: LoadOutboundOptions): Promise<OutboundLoadResult>;
+/** 当前已装载的出站扩展（诊断用） */
+export declare function listOutboundExtensions(): OutboundExtension[];
+/** 改文件 + tools_reload = 复位通道 */
+export declare function resetOutboundBreaker(name?: string): void;
+/** 当前是否正在跑出站链（其他扩展可用于"别在我发消息时又触发我"） */
+export declare function outboundActive(): boolean;
+/** 最近一次出站的 ctx（其他扩展可用它拿 target 往同一个会话补发） */
+export declare function lastOutboundCtx(): OutboundCtx | null;
+/**
+ * 构造一条出站的 ctx（**导出**出来，方便其他扩展/工具直接造一条去发）。
+ */
+export declare function makeOutboundCtx(initialText: string, opts?: RunOutboundOptions, state?: {
+    text: string;
+    killed: boolean;
+    reason: string;
+}): OutboundCtx;
+/** 一条出站的执行结果 */
+export interface OutboundRunResult {
+    /** 最终要发的正文（可能被扩展改写） */
+    text: string;
+    /** 是否被消灭（调用方应**跳过发送**） */
+    killed: boolean;
+    /** 消灭原因（诊断用） */
+    reason: string;
+    /** 跑过的扩展数 */
+    ran: number;
+}
+/**
+ * 依次跑出站链（文件名升序，与 inbound 同款"链式 + 幂等 next"）。
+ *
+ * 语义（**与 inbound 对齐**）：
+ *   · `next()` **幂等**：误调两次只算第一次；
+ *   · `next()` 一定被 await（扩展忘 await 时引擎替它 await）；
+ *   · 扩展**不调 next() 且没 annihilate** ⇒ 引擎替它放行（防新手卡死链）+ 记 warn；
+ *   · `annihilate()` 之后**即便又调了 next() 也不再往下走**。
+ */
+export declare function runOutboundChain(text: string, opts?: RunOutboundOptions): Promise<OutboundRunResult>;
+/**
+ * ★★ 回合结束钩子（2026-10-16 主人定）★★
+ *
+ * 挂载点：`transport/outbound.ts` 的 `turn/end` —— 在 `buffer.flush()` 之后、
+ * 与 passive 收尾（`maybeResendLastBlock`）**同一时机**。传进来的 `lastText`
+ * 就是 `turnBlocks.last`，**是这一回合权威的最后一块正文**。
+ *
+ * 为什么需要它：一段 assistant 回复可能包含"正文 → 工具调用 → 正文"多段，
+ * 每段都各走一次 `sendRichOutbound`。若把配图挂在入口（phase='send'），
+ * 第一段就会被当成本回合正文拿去判定 —— **错得离谱**（主人 2026-10-16 实测抓到）。
+ *
+ * 扩展怎么写：在 `onOutbound(ctx, next)` 里判 `ctx.phase === 'turnEnd'` ⇒ 做配图；
+ * `phase === 'send'` ⇒ 只做改写/消灭（或直接 `next()`）。
+ */
+export declare function runOutboundTurnEnd(lastText: string, opts?: RunOutboundOptions): Promise<OutboundRunResult>;
+/**
+ * 直接经"先被动后主动"通道发一条东西。
+ *
+ * ⚠️ 这条通道**不跑出站扩展链**（否则自己发的又会被自己拦，形成回环）；
+ *    要走链请用 {@link runOutboundChain}。
+ */
+export declare function sendViaOutboundChannel(payload: {
+    text?: string;
+    path?: string;
+    url?: string;
+    kind?: string;
+}, opts?: RunOutboundOptions, sendOpts?: {
+    adaptive?: boolean;
+}): Promise<boolean>;
+/**
+ * 其他扩展获取"出站操控器"的入口（`globalThis[OUTBOUND_API_KEY]`）。
+ *
+ * 用法（任何扩展里）：
+ * ```js
+ * const ob = globalThis[Symbol.for('im-qqbot.outbound')];
+ * await ob?.send('补一句', { adaptive: true });
+ * await ob?.sendMedia({ path: 'D:/pics/a.png' });
+ * const target = ob?.last()?.target;   // 往"刚才那个会话"发
+ * const scores = await ob?.embed('正文', ['标签A', '标签B']);  // 本地小模型语义分（可为 null）
+ * ```
+ */
+export declare function installOutboundApi(): void;
+//# sourceMappingURL=ext-outbound.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ext-outbound.d.ts","sourceRoot":"","sources":["../../src/features/ext-outbound.ts"],"names":[],"mappings":"AAwCA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAK1C,2DAA2D;AAC3D,eAAO,MAAM,mBAAmB,aAAa,CAAC;AAE9C,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,eAAkC,CAAC;AAEhE,qCAAqC;AACrC,MAAM,WAAW,WAAW;IAC1B,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,cAAc;IACd,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IACnE,8BAA8B;IAC9B,MAAM,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACnE,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,WAAW,EAAE,OAAO,CAAC;IACrB,qBAAqB;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU;IACV,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,yBAAyB;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yCAAyC;IACzC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gBAAgB;IAChB,MAAM,EAAE,MAAM,CAAC;IAGf,uCAAuC;IACvC,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAClC,6DAA6D;IAC7D,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IACpC;;;;;;;;;;;;;;;OAeG;IACH;;;;;;;;OAQG;IACH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,UAAU,CAAC,IAAI,EAAE,MAAM,OAAO,GAAG,IAAI,CAAC;IACtC,iCAAiC;IACjC,SAAS,CAAC,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnF,iCAAiC;IACjC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpE,kDAAkD;IAClD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAGxB,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACjC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACrC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACjC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;IACjE,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;QAAC,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,KAAK,OAAO,CAAA;KAAE,CAAC;IACnF,QAAQ,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACjE,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CACxC;AAED,2CAA2C;AAC3C,MAAM,MAAM,kBAAkB,GAAG,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC;AAE1F,iBAAiB;AACjB,MAAM,WAAW,iBAAiB;IAChC,gBAAgB;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW;IACX,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU;IACV,UAAU,EAAE,kBAAkB,CAAC;IAC/B,qBAAqB;IACrB,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC;CACzB;AAED,cAAc;AACd,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,8BAA8B;AAC9B,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,IAAI,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC3B,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE9D;AAYD,qCAAqC;AACrC,wBAAgB,2BAA2B,CAAC,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAE5F;AAED,8BAA8B;AAC9B,wBAAsB,wBAAwB,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAG5E;AAwCD;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA6CnG;AAED,sBAAsB;AACtB,wBAAgB,sBAAsB,IAAI,iBAAiB,EAAE,CAE5D;AAQD,gCAAgC;AAChC,wBAAgB,oBAAoB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAGxD;AAcD,uCAAuC;AACvC,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAED,4CAA4C;AAC5C,wBAAgB,eAAe,IAAI,WAAW,GAAG,IAAI,CAEpD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE,kBAAuB,EAC7B,KAAK,GAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAqD,GAC1G,WAAW,CAmEb;AAED,gBAAgB;AAChB,MAAM,WAAW,iBAAiB;IAChC,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,MAAM,EAAE,OAAO,CAAC;IAChB,gBAAgB;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,kBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAuD9G;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,iBAAiB,CAAC,CAG5B;AAID;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EACtE,IAAI,GAAE,kBAAuB,EAC7B,QAAQ,GAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAO,GACpC,OAAO,CAAC,OAAO,CAAC,CAoDlB;AAwED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CA0BzC"}