@sns-parse/core 0.5.0-alpha.1 → 0.6.0-alpha.2

package/lib/engine/runtime.js

@@ -5,13 +5,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createRuntime = createRuntime;
 /**
- * 运行时构建（自宿主 runtime 下沉，平台无关）。
+ * 运行时装配（本文件在 core 内，平台无关）。
  *
- * 平台定义列表（defs）由调用方传入：
- * - koishi 兼容层传内置 BUILTIN_PLATFORMS（本地 definitions）
- * - CLI 传 collectPlatformDefinitions()（已安装的 @sns-parse/platform-*）
- * 默认扩展实现同样由宿主注入（loadExtensionImplementations() 发现已安装 ext-*）；
- * core 只负责调度，不持有任何功能实现。
+ * 平台定义列表（defs）由宿主按已加载平台插件声明注入：
+ * - koishi 兼容层：collectPlatformDefinitions(anchor)（聚合包 + 粒度包并集）
+ * - CLI：collectPlatformDefinitions()
+ * 工作流阶段基线在 createDefaultPipeline()，扩展经 WorkflowExtension.setup(hooks) 注入/替换。
+ * core 不依赖任何扩展包、不含扩展实现。
  */
 const axios_1 = __importDefault(require("axios"));
 const https_proxy_agent_1 = require("https-proxy-agent");
@@ -20,10 +20,11 @@ const cache_1 = require("../utils/cache");
 const field_mapping_1 = require("../utils/field-mapping");
 const platform_config_1 = require("./platform-config");
 const gateway_1 = require("./gateway");
+const default_1 = require("../workflow/default");
 function createRuntime(source, config, opts = {}) {
     const host = (0, host_1.createHost)(source);
     const ctx = host.context;
-    const extensions = { ...(opts.defaultExtensions || {}), ...(host.extensions || {}) };
+    const extensions = [...(opts.extensions || []), ...(host.extensions || [])];
     const dedupCache = new cache_1.SimpleLRUCache(1000, config.deduplicationInterval * 1000);
     const cacheTTL = (config.cacheTTL || 600) * 1000;
     const urlCacheLocal = new cache_1.SimpleLRUCache(500, cacheTTL);
@@ -61,7 +62,12 @@ function createRuntime(source, config, opts = {}) {
         axiosConfig.proxy = false;
     }
     const http = axios_1.default.create(axiosConfig);
-    return {
+    const pipeline = (0, default_1.createDefaultPipeline)(null);
+    for (const ext of extensions) {
+        if (ext && typeof ext.setup === 'function')
+            ext.setup(pipeline);
+    }
+    const runtime = {
         host,
         ctx,
         config,
@@ -76,5 +82,8 @@ function createRuntime(source, config, opts = {}) {
         defs,
         dedicatedApis,
         extensions,
+        pipeline,
     };
+    pipeline.rt = runtime;
+    return runtime;
 }

package/lib/extensions.d.ts

@@ -1,21 +1,25 @@
 /**
- * 扩展契约：core 不直接依赖 NSFW/合并/翻译/GIF 实现，而是通过可注入的
- * VideoParserExtensions 调用。宿主可整体替换或按需覆盖单项能力。
+ * 扩展契约：core 完整工作流 + 基线行为；扩展经阶段钩子注入/修改。
  *
- * 默认实现由 extensions 包（@sns-parse/extensions）提供；runtime 会合并默认实现，
- * 因此 core 编排层可直接调用，无需判空。
+ * core 不内建任何扩展实现（NSFW/合并/翻译/GIF），也不依赖扩展包；
+ * 基线行为保证无扩展时全链路可跑（媒体直通、不合并逐张发、GIF 退化发视频、不翻译）。
+ * 扩展导出 WorkflowExtension（含 setup(hooks)），由宿主收集后注入管道。
  */
+import type { ConfigContribution } from './config';
 import type { ParserRuntimeLike } from './host';
+import type { WorkflowHooks } from './workflow/hooks';
 export type MediaKind = 'cover' | 'image' | 'avatar' | 'music-cover';
 export interface ImageOutcome {
-    /** raw=原图 url；scrambled=混淆 buffer+token；link=仅链接文字；drop=不发送 */
+    /** raw=原图 url 或 buffer 直发；scrambled=混淆 buffer+token；link=只发链接文本；drop=丢弃 */
     kind: 'raw' | 'scrambled' | 'link' | 'drop';
     url?: string;
     buffer?: Buffer;
     token?: string;
+    /** buffer 直发时的 mime（缺省 image/jpeg） */
+    mime?: string;
 }
 export interface VideoOutcome {
-    /** raw=照发；card=群内纯文字卡片+token（无封面无视频）；link=文字卡片+原链接；drop=仅文字卡片 */
+    /** raw=直发视频；card=群内容易吞 → 暂存+token，无法直发视频；link=只发卡片+原链接；drop=只发卡片 */
     kind: 'raw' | 'card' | 'link' | 'drop';
     url?: string;
     token?: string;
@@ -29,29 +33,23 @@ export interface GifOptions {
     fps: number;
     maxDurationSec: number;
 }
-/** 扩展能力集合（全部可选；runtime 会与默认实现合并） */
-export interface VideoParserExtensions {
-    /** 同源切图合并；返回 null 表示不合并 */
-    mergeImages?(rt: ParserRuntimeLike, urls: string[]): Promise<{
-        buffer: Buffer;
-    } | null>;
-    /** 单张出站图片处理（NSFW 策略） */
-    processImage?(rt: ParserRuntimeLike, platform: string, url: string, kind: MediaKind): Promise<ImageOutcome>;
-    /** 出站视频处理（NSFW 策略） */
-    processVideo?(rt: ParserRuntimeLike, platform: string, videoUrl: string, coverUrl: string, meta: {
-        title?: string;
-        author?: string;
-        requesterId: string;
-    }): Promise<VideoOutcome>;
-    /** 合并图审核；返回 null 表示回退逐张处理 */
-    processMergedImage?(rt: ParserRuntimeLike, platform: string, buffer: Buffer, refUrl: string): Promise<ImageOutcome | null>;
-    /** 视频转 GIF；失败返回 null 回退原视频 */
-    mp4ToGif?(rt: ParserRuntimeLike, url: string, durationSec: number, opts: GifOptions): Promise<Buffer | null>;
-    /** 文本翻译；失败返回 null */
-    translate?(rt: ParserRuntimeLike, text: string, target: string, sourceLang?: string): Promise<TranslateResult | null>;
-    /** 内容安全能力状态（启动日志） */
+export interface VideoMeta {
+    title?: string;
+    author?: string;
+    requesterId: string;
+}
+/** 单个扩展片段：能力注册（setup 钩子注入）+ 可选配置贡献/能力位 */
+export interface WorkflowExtension {
+    name: string;
+    setup(hooks: WorkflowHooks): void;
+    configContribution?: ConfigContribution;
     capability?(rt: ParserRuntimeLike): {
         ferret: boolean;
         moderation: string | null;
     };
 }
+/** 汇总各扩展能力位（日志用） */
+export declare function collectCapabilities(extensions: WorkflowExtension[] | undefined, rt: ParserRuntimeLike): {
+    ferret: boolean;
+    moderation: string | null;
+};

package/lib/extensions.js

@@ -1,2 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectCapabilities = collectCapabilities;
+/** 汇总各扩展能力位（日志用） */
+function collectCapabilities(extensions, rt) {
+    let ferret = false;
+    let moderation = null;
+    for (const e of extensions || []) {
+        if (typeof e.capability !== 'function')
+            continue;
+        try {
+            const c = e.capability(rt);
+            if (c?.ferret)
+                ferret = true;
+            if (c?.moderation)
+                moderation = c.moderation;
+        }
+        catch {
+            // 能力位探测失败不影响主链路
+        }
+    }
+    return { ferret, moderation };
+}

package/lib/host.d.ts

@@ -9,7 +9,7 @@
  */
 import { type LoggerLike } from './logger';
 import type { OutboundSender } from './sender';
-import type { VideoParserExtensions } from './extensions';
+import type { WorkflowExtension } from './extensions';
 export interface VideoParserHost {
     logger: LoggerLike;
     /** 数据根目录（如 koishi ctx.baseDir）；缺省时持久化走临时目录 */
@@ -19,7 +19,7 @@ export interface VideoParserHost {
     /** 发送层实现（缺省时由宿主适配层注入） */
     sender?: OutboundSender;
     /** 扩展实现（部分覆盖；缺省能力由内置实现补齐） */
-    extensions?: VideoParserExtensions;
+    extensions?: WorkflowExtension[];
     /** 过渡期：底层上下文（koishi Context 等），core 新代码不应依赖 */
     context?: any;
 }
@@ -31,7 +31,7 @@ export interface ParserRuntimeLike {
     config: any;
     http: any;
     host: VideoParserHost;
-    extensions: VideoParserExtensions;
+    extensions: WorkflowExtension[];
     [key: string]: any;
 }
 /**

package/lib/index.d.ts

@@ -21,7 +21,13 @@ export * from './engine/config';
 export * from './engine/platform-config';
 export * from './engine/translate';
 export * from './engine/parser';
+export * from './engine/generic';
 export * from './engine/fetcher';
+export * from './engine/compose';
+export * from './engine/forward';
+export * from './engine/flush';
 export * from './engine/runtime';
 export * from './engine/config-io';
+export * from './workflow/hooks';
+export * from './workflow/default';
 export * from './registry';

package/lib/index.js

@@ -37,7 +37,13 @@ __exportStar(require("./engine/config"), exports);
 __exportStar(require("./engine/platform-config"), exports);
 __exportStar(require("./engine/translate"), exports);
 __exportStar(require("./engine/parser"), exports);
+__exportStar(require("./engine/generic"), exports);
 __exportStar(require("./engine/fetcher"), exports);
+__exportStar(require("./engine/compose"), exports);
+__exportStar(require("./engine/forward"), exports);
+__exportStar(require("./engine/flush"), exports);
 __exportStar(require("./engine/runtime"), exports);
 __exportStar(require("./engine/config-io"), exports);
+__exportStar(require("./workflow/hooks"), exports);
+__exportStar(require("./workflow/default"), exports);
 __exportStar(require("./registry"), exports);

package/lib/registry.d.ts

@@ -1,20 +1,28 @@
+/**
+ * 已安装碎片包（平台 @sns-parse/platform-* / 扩展 @sns-parse/ext-*）的动态发现。
+ *
+ * - 平台：先聚合包（@sns-parse/platforms 的 definitions[]），再逐个候选粒度包，
+ *   按 type 去重合并（粒度包覆盖聚合条目）；宿主可传自己的 require 锚点
+ *   （koishi/CLI 包路径），pnpm strict 下也能发现宿主直依赖。
+ * - 扩展：loadWorkflowExtensions() 返回 WorkflowExtension[]（含 setup 钩子），
+ *   未安装的自动缺席（能力/配置贡献同时缺席，不报错）。
+ */
+import { createRequire } from 'node:module';
 import type { PlatformDefinition } from './platform';
 import type { ConfigContribution } from './config';
-import type { VideoParserExtensions } from './extensions';
-/** 收集已安装平台的定义（含 label/rules/dedicated） */
-export declare function collectPlatformDefinitions(): PlatformDefinition[];
-/** 已安装平台的链接规则（扁平） */
-export declare function collectPlatformLinkRules(): {
+import type { WorkflowExtension } from './extensions';
+type NodeRequire = ReturnType<typeof createRequire>;
+/** 收集已加载平台的定义（聚合包 + 粒度包并集；粒度包覆盖聚合条目） */
+export declare function collectPlatformDefinitions(anchor?: NodeRequire): PlatformDefinition[];
+/** 已加载平台的链接规则（按平台声明） */
+export declare function collectPlatformLinkRules(anchor?: NodeRequire): {
     pattern: RegExp;
     type: string;
 }[];
-export interface LoadedExtension {
-    name: string;
-    contribution?: ConfigContribution;
-    extension?: Partial<VideoParserExtensions>;
-}
-/** 探测并加载全部已安装扩展 */
-export declare function loadExtensions(): LoadedExtension[];
-export declare function loadExtensionContributions(): ConfigContribution[];
-/** 合并所有已安装扩展的能力片段 */
-export declare function loadExtensionImplementations(): Partial<VideoParserExtensions>;
+/** 探测并实例化全部已安装扩展（WorkflowExtension[]；含 setup 钩子） */
+export declare function loadWorkflowExtensions(anchor?: NodeRequire): WorkflowExtension[];
+/** 已安装扩展的配置贡献（settings 动态渲染用） */
+export declare function loadExtensionContributions(anchor?: NodeRequire): ConfigContribution[];
+/** 兼容旧名（已废弃：请用 loadWorkflowExtensions） */
+export declare function loadExtensionImplementations(anchor?: NodeRequire): WorkflowExtension[];
+export {};

package/lib/registry.js

@@ -2,76 +2,100 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.collectPlatformDefinitions = collectPlatformDefinitions;
 exports.collectPlatformLinkRules = collectPlatformLinkRules;
-exports.loadExtensions = loadExtensions;
+exports.loadWorkflowExtensions = loadWorkflowExtensions;
 exports.loadExtensionContributions = loadExtensionContributions;
 exports.loadExtensionImplementations = loadExtensionImplementations;
 /**
- * 已安装碎片包的动态收集（平台 @sns-parse/platform-* 与扩展 @sns-parse/ext-*）。
+ * 已安装碎片包（平台 @sns-parse/platform-* / 扩展 @sns-parse/ext-*）的动态发现。
  *
- * - 可自选安装单个碎片包；安装聚合包（@sns-parse/platforms / extensions）则全部到位
- * - 未安装的碎片自动缺席（链接识别、配置项与能力同时缺席）
- * - koishi 兼容层与 CLI 均经此处收集定义与配置声明
+ * - 平台：先聚合包（@sns-parse/platforms 的 definitions[]），再逐个候选粒度包，
+ *   按 type 去重合并（粒度包覆盖聚合条目）；宿主可传自己的 require 锚点
+ *   （koishi/CLI 包路径），pnpm strict 下也能发现宿主直依赖。
+ * - 扩展：loadWorkflowExtensions() 返回 WorkflowExtension[]（含 setup 钩子），
+ *   未安装的自动缺席（能力/配置贡献同时缺席，不报错）。
  */
 const node_module_1 = require("node:module");
-const nodeRequire = (0, node_module_1.createRequire)(typeof __filename !== 'undefined' ? __filename : process.cwd() + '/');
+const fallbackRequire = (0, node_module_1.createRequire)(typeof __filename !== 'undefined' ? __filename : process.cwd() + '/');
+function req(anchor) {
+    return anchor || fallbackRequire;
+}
 const PLATFORM_TYPES = [
     'bilibili', 'douyin', 'kuaishou', 'xiaohongshu', 'weibo', 'xigua', 'youtube',
     'tiktok', 'acfun', 'zhihu', 'weishi', 'huya', 'haokan', 'meipai', 'twitter',
     'instagram', 'doubao', 'doubao_image', 'jimeng', 'oasis', 'wechat_channel',
     'lishi', 'quanmin', 'pipigx', 'pipixia', 'zuiyou', 'toutiao',
 ];
-/** 收集已安装平台的定义（含 label/rules/dedicated） */
-function collectPlatformDefinitions() {
-    const out = [];
+/** 收集已加载平台的定义（聚合包 + 粒度包并集；粒度包覆盖聚合条目） */
+function collectPlatformDefinitions(anchor) {
+    const nodeRequire = req(anchor);
+    const byType = new Map();
+    // 1) 聚合包（若安装）：一次拿全声明
+    try {
+        const agg = nodeRequire('@sns-parse/platforms');
+        const defs = agg?.definitions || agg?.default?.definitions || [];
+        for (const d of defs) {
+            if (d && d.type && !byType.has(d.type))
+                byType.set(d.type, d);
+        }
+    }
+    catch {
+        // 未装聚合包 → 只看粒度包
+    }
+    // 2) 粒度包（可覆盖聚合条目）
     for (const type of PLATFORM_TYPES) {
         try {
             const mod = nodeRequire(`@sns-parse/platform-${type}`);
             const def = mod.default || mod[type];
             if (def && def.type)
-                out.push(def);
+                byType.set(def.type, def);
         }
         catch {
-            // 未安装该平台包 → 跳过
+            // 未装该平台 → 缺席
         }
     }
-    return out;
+    return [...byType.values()];
 }
-/** 已安装平台的链接规则（扁平） */
-function collectPlatformLinkRules() {
-    return collectPlatformDefinitions().flatMap(d => d.rules.map(pattern => ({ pattern, type: d.type })));
+/** 已加载平台的链接规则（按平台声明） */
+function collectPlatformLinkRules(anchor) {
+    return collectPlatformDefinitions(anchor).flatMap(d => d.rules.map(pattern => ({ pattern, type: d.type })));
 }
 const EXTENSION_SPECS = [
-    { name: 'ext-nsfw', contributionKey: 'nsfwConfigContribution', extensionKey: 'nsfwExtension' },
+    { name: 'ext-nsfw', extensionKey: 'nsfwExtension', contributionKey: 'nsfwConfigContribution' },
     { name: 'ext-merge', extensionKey: 'mergeExtension' },
     { name: 'ext-translate', extensionKey: 'translateExtension' },
     { name: 'ext-gif', extensionKey: 'gifExtension' },
 ];
-/** 探测并加载全部已安装扩展 */
-function loadExtensions() {
+/** 探测并实例化全部已安装扩展（WorkflowExtension[]；含 setup 钩子） */
+function loadWorkflowExtensions(anchor) {
+    const nodeRequire = req(anchor);
     const out = [];
     for (const spec of EXTENSION_SPECS) {
         try {
             const mod = nodeRequire(`@sns-parse/${spec.name}`);
-            out.push({
-                name: spec.name,
-                contribution: spec.contributionKey ? mod[spec.contributionKey] : undefined,
-                extension: spec.extensionKey && typeof mod[spec.extensionKey] === 'function'
-                    ? mod[spec.extensionKey]()
-                    : undefined,
-            });
+            const factory = mod?.[spec.extensionKey];
+            if (typeof factory !== 'function')
+                continue;
+            const ext = factory();
+            if (!ext || typeof ext.setup !== 'function')
+                continue;
+            if (!ext.configContribution && spec.contributionKey && mod[spec.contributionKey]) {
+                ext.configContribution = mod[spec.contributionKey];
+            }
+            out.push(ext);
         }
         catch {
-            // 未安装该扩展 → 跳过（配置项与能力同时缺席）
+            // 未安装的扩展 → 缺席（能力与配置贡献同时缺席）
         }
     }
     return out;
 }
-function loadExtensionContributions() {
-    return loadExtensions()
-        .map(e => e.contribution)
+/** 已安装扩展的配置贡献（settings 动态渲染用） */
+function loadExtensionContributions(anchor) {
+    return loadWorkflowExtensions(anchor)
+        .map(e => e.configContribution)
         .filter((c) => !!c);
 }
-/** 合并所有已安装扩展的能力片段 */
-function loadExtensionImplementations() {
-    return Object.assign({}, ...loadExtensions().map(e => e.extension || {}));
+/** 兼容旧名（已废弃：请用 loadWorkflowExtensions） */
+function loadExtensionImplementations(anchor) {
+    return loadWorkflowExtensions(anchor);
 }

package/lib/workflow/default.d.ts

@@ -0,0 +1,3 @@
+import { Pipeline } from './hooks';
+/** 构建带全部基线实现的管道；随后调用各扩展 setup(hooks) 注入/覆盖 */
+export declare function createDefaultPipeline(rt: any): Pipeline;

package/lib/workflow/default.js

@@ -0,0 +1,74 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDefaultPipeline = createDefaultPipeline;
+const hooks_1 = require("./hooks");
+const fetcher = __importStar(require("../engine/fetcher"));
+const compose = __importStar(require("../engine/compose"));
+const forward = __importStar(require("../engine/forward"));
+async function sendDispatch(rt, input) {
+    const { items, session, sender, quoteId } = input;
+    const config = rt.config || {};
+    const forwardAllowed = config.enableForward && (session.platform === 'onebot' || session.platform === 'satori');
+    if (forwardAllowed) {
+        await forward.sendForward(rt, sender, session, items);
+        return;
+    }
+    if (config.sendStrategy === 'split') {
+        for (const item of items)
+            await compose.sendSplit(rt, sender, session, item, { quoteId });
+        return;
+    }
+    for (const item of items) {
+        await compose.sendSingle(rt, sender, session, item, { quoteId });
+    }
+}
+/** 构建带全部基线实现的管道；随后调用各扩展 setup(hooks) 注入/覆盖 */
+function createDefaultPipeline(rt) {
+    const p = new hooks_1.Pipeline(rt);
+    p.replace('parse', (input, r) => fetcher.fetchApi(r, input.url, input.type, input.fieldMapping, input.platformConf));
+    // 通用链接解析（预留）：基线=未实现（null）——非平台链接不进入解析流程；
+    // 后续由宿主/扩展 replace 注入（OG/HTML/LLM，契约见 engine/generic.ts）
+    p.replace('parse.generic', async () => null);
+    p.replace('translate', async () => null);
+    p.replace('media.image', async (input) => ({ kind: 'raw', url: input.url }));
+    p.replace('media.video', async (input) => ({ kind: 'raw', url: input.videoUrl }));
+    p.replace('media.merged', async (input) => ({ kind: 'raw', buffer: input.buffer, url: input.refUrl }));
+    p.replace('merge', async () => null);
+    p.replace('transcode', async () => null);
+    p.replace('compose', (input, r) => compose.buildUnits(r, input.item));
+    p.replace('send', (input, r) => sendDispatch(r, input));
+    return p;
+}

package/lib/workflow/hooks.d.ts

@@ -0,0 +1,130 @@
+/**
+ * 工作流阶段钩子管道（core 内建完整工作流，扩展经钩子注入/修改）。
+ *
+ * 每阶段结构：{ before[], impl, after[] }
+ * - before：前置，可改输入（返回新输入；返回 undefined 表示不变）
+ * - after：后置，可改输出（返回新输出；返回 undefined 表示不变）
+ * - replace：整体替换该阶段实现（后注册者胜）
+ *
+ * 基线实现见 workflow/default.ts（无扩展时全链路可跑：
+ * 不合并逐张发 / GIF 退化发视频 / 不翻译 / 媒体直通）。
+ */
+import type { ParsedData } from '../types';
+import type { ImageOutcome, VideoOutcome, TranslateResult, GifOptions, MediaKind, VideoMeta } from '../extensions';
+import type { ProcessedItem, MessageUnit } from '../engine/compose';
+import type { OutboundSender, SessionLike } from '../sender';
+import type { GenericLinkInput, GenericLinkResult } from '../engine/generic';
+export type StageName = 'parse' | 'parse.generic' | 'translate' | 'media.image' | 'media.video' | 'media.merged' | 'merge' | 'transcode' | 'compose' | 'send';
+export interface ParseInput {
+    url: string;
+    type: string;
+    fieldMapping?: Record<string, string>;
+    platformConf?: any;
+}
+export interface TranslateInput {
+    text: string;
+    target: string;
+    sourceLang?: string;
+}
+export interface MediaImageInput {
+    platform: string;
+    url: string;
+    kind: MediaKind;
+}
+export interface MediaVideoInput {
+    platform: string;
+    videoUrl: string;
+    coverUrl: string;
+    meta: VideoMeta;
+}
+export interface MediaMergedInput {
+    platform: string;
+    buffer: Buffer;
+    refUrl: string;
+}
+export interface MergeInput {
+    urls: string[];
+}
+export type MergeResult = {
+    buffer: Buffer;
+    layout?: any;
+} | null;
+export interface TranscodeInput {
+    url: string;
+    durationSec: number;
+    opts: GifOptions;
+}
+export interface ComposeInput {
+    item: ProcessedItem;
+}
+export interface SendInput {
+    items: ProcessedItem[];
+    session: SessionLike;
+    sender: OutboundSender;
+    quoteId?: string;
+}
+export interface StageIO {
+    parse: {
+        input: ParseInput;
+        output: ParsedData;
+    };
+    'parse.generic': {
+        input: GenericLinkInput;
+        output: GenericLinkResult | null;
+    };
+    translate: {
+        input: TranslateInput;
+        output: TranslateResult | null;
+    };
+    'media.image': {
+        input: MediaImageInput;
+        output: ImageOutcome;
+    };
+    'media.video': {
+        input: MediaVideoInput;
+        output: VideoOutcome;
+    };
+    'media.merged': {
+        input: MediaMergedInput;
+        output: ImageOutcome | null;
+    };
+    merge: {
+        input: MergeInput;
+        output: MergeResult;
+    };
+    transcode: {
+        input: TranscodeInput;
+        output: Buffer | null;
+    };
+    compose: {
+        input: ComposeInput;
+        output: MessageUnit[];
+    };
+    send: {
+        input: SendInput;
+        output: void;
+    };
+}
+export type StageImpl<S extends StageName = StageName> = (input: StageIO[S]['input'], rt: any) => StageIO[S]['output'] | Promise<StageIO[S]['output']>;
+export type BeforeHandler<S extends StageName = StageName> = (input: StageIO[S]['input'], rt: any) => StageIO[S]['input'] | void | Promise<StageIO[S]['input'] | void>;
+export type AfterHandler<S extends StageName = StageName> = (output: StageIO[S]['output'], input: StageIO[S]['input'], rt: any) => StageIO[S]['output'] | void | Promise<StageIO[S]['output'] | void>;
+/** 扩展注入面：before/after 可插入，replace 可整体替换（后注册者胜） */
+export interface WorkflowHooks {
+    before<S extends StageName>(stage: S, h: BeforeHandler<S>): void;
+    after<S extends StageName>(stage: S, h: AfterHandler<S>): void;
+    replace<S extends StageName>(stage: S, h: StageImpl<S>): void;
+}
+export declare class Pipeline implements WorkflowHooks {
+    rt: any;
+    private impls;
+    private befores;
+    private afters;
+    constructor(rt: any);
+    before<S extends StageName>(stage: S, h: BeforeHandler<S>): void;
+    after<S extends StageName>(stage: S, h: AfterHandler<S>): void;
+    replace<S extends StageName>(stage: S, h: StageImpl<S>): void;
+    run<S extends StageName>(stage: S, input: StageIO[S]['input']): Promise<StageIO[S]['output']>;
+}
+/** 取（或懒挂）runtime 的管道；裸 rt 对象也能工作（自动挂默认管道）。 */
+export declare function ensurePipeline(rt: any): Pipeline;
+export declare function runStage<S extends StageName>(rt: any, stage: S, input: StageIO[S]['input']): Promise<StageIO[S]['output']>;