@sns-parse/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 char46
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,30 @@
+# @sns-parse/core
+
+sns-parse 分层架构的**核心契约包**：所有层共享的类型与抽象，不依赖 Koishi / CLI 任一 SDK。
+
+## 内容
+
+| 模块 | 说明 |
+|------|------|
+| `types` | `ParsedData`、`LinkMatch`、`CustomPlatformConfig` 等数据模型 |
+| `logger` | 可注入的 `LoggerLike`（默认静默；宿主注入 Koishi Logger / console） |
+| `sender` | 发送层无关 IR `OutboundElement` + `OutboundSender` 契约 |
+| `extensions` | `VideoParserExtensions` 扩展契约（NSFW/合并/翻译/GIF） |
+| `platform` | `PlatformDefinition` 平台定义契约 |
+| `host` | `VideoParserHost` 宿主抽象、`ParserRuntimeLike`、`createHost()` |
+
+## 安装
+
+```bash
+npm i @sns-parse/core
+```
+
+## 用法
+
+```ts
+import { createHost, el, type OutboundSender, type PlatformDefinition } from '@sns-parse/core'
+```
+
+## 许可
+
+MIT

package/lib/extensions.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 扩展契约：core 不直接依赖 NSFW/合并/翻译/GIF 实现，而是通过可注入的
+ * VideoParserExtensions 调用。宿主可整体替换或按需覆盖单项能力。
+ *
+ * 默认实现由 extensions 包（@sns-parse/extensions）提供；runtime 会合并默认实现，
+ * 因此 core 编排层可直接调用，无需判空。
+ */
+import type { ParserRuntimeLike } from './host';
+export type MediaKind = 'cover' | 'image' | 'avatar' | 'music-cover';
+export interface ImageOutcome {
+    /** raw=原图 url；scrambled=混淆 buffer+token；link=仅链接文字；drop=不发送 */
+    kind: 'raw' | 'scrambled' | 'link' | 'drop';
+    url?: string;
+    buffer?: Buffer;
+    token?: string;
+}
+export interface VideoOutcome {
+    /** raw=照发；card=群内纯文字卡片+token（无封面无视频）；link=文字卡片+原链接；drop=仅文字卡片 */
+    kind: 'raw' | 'card' | 'link' | 'drop';
+    url?: string;
+    token?: string;
+}
+export interface TranslateResult {
+    text: string;
+    provider: string;
+}
+export interface GifOptions {
+    maxWidth: number;
+    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>;
+    /** 内容安全能力状态（启动日志） */
+    capability?(rt: ParserRuntimeLike): {
+        ferret: boolean;
+        moderation: string | null;
+    };
+}

package/lib/extensions.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/host.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 宿主抽象：core 只依赖 VideoParserHost，不依赖 Koishi/CLI 任一 SDK。
+ *
+ * - logger：分级日志（Koishi 注入 Logger，CLI 注入 console 实现）
+ * - baseDir：数据根目录（持久化缓存/Vault 落盘用）
+ * - getService：可选服务探测（如 ferret-transform 图片混淆）
+ * - sender：发送层实现（见 core/sender.ts）
+ * - extensions：扩展能力（见 core/extensions.ts）
+ */
+import { type LoggerLike } from './logger';
+import type { OutboundSender } from './sender';
+import type { VideoParserExtensions } from './extensions';
+export interface VideoParserHost {
+    logger: LoggerLike;
+    /** 数据根目录（如 koishi ctx.baseDir）；缺省时持久化走临时目录 */
+    baseDir?: string;
+    /** 探测宿主提供的可选服务 */
+    getService?<T = any>(name: string): T | undefined;
+    /** 发送层实现（缺省时由宿主适配层注入） */
+    sender?: OutboundSender;
+    /** 扩展实现（部分覆盖；缺省能力由内置实现补齐） */
+    extensions?: VideoParserExtensions;
+    /** 过渡期：底层上下文（koishi Context 等），core 新代码不应依赖 */
+    context?: any;
+}
+/**
+ * 运行期最小面（core 契约）：上层 runtime 结构上满足即可。
+ * 具体实现由各宿主/引擎提供，core 仅以此类型声明扩展方法的入参。
+ */
+export interface ParserRuntimeLike {
+    config: any;
+    http: any;
+    host: VideoParserHost;
+    extensions: VideoParserExtensions;
+    [key: string]: any;
+}
+/**
+ * 从宿主上下文（koishi Context / 任意对象）构建 Host。
+ * 已是 Host（含 getService 方法）时原样返回。
+ */
+export declare function createHost(source: any): VideoParserHost;

package/lib/host.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHost = createHost;
+/**
+ * 宿主抽象：core 只依赖 VideoParserHost，不依赖 Koishi/CLI 任一 SDK。
+ *
+ * - logger：分级日志（Koishi 注入 Logger，CLI 注入 console 实现）
+ * - baseDir：数据根目录（持久化缓存/Vault 落盘用）
+ * - getService：可选服务探测（如 ferret-transform 图片混淆）
+ * - sender：发送层实现（见 core/sender.ts）
+ * - extensions：扩展能力（见 core/extensions.ts）
+ */
+const logger_1 = require("./logger");
+/**
+ * 从宿主上下文（koishi Context / 任意对象）构建 Host。
+ * 已是 Host（含 getService 方法）时原样返回。
+ */
+function createHost(source) {
+    if (source && typeof source === 'object' && typeof source.getService === 'function') {
+        return source;
+    }
+    const ctx = source && typeof source === 'object' ? source : {};
+    return {
+        logger: ctx.logger ?? logger_1.silentLogger,
+        baseDir: ctx.baseDir,
+        getService: (name) => ctx[name],
+        sender: ctx.sender,
+        extensions: ctx.extensions,
+        context: ctx,
+    };
+}

package/lib/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @sns-parse/core 公共出口。
+ */
+export * from './types';
+export * from './logger';
+export * from './sender';
+export * from './extensions';
+export * from './platform';
+export * from './host';

package/lib/index.js

@@ -0,0 +1,25 @@
+"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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * @sns-parse/core 公共出口。
+ */
+__exportStar(require("./types"), exports);
+__exportStar(require("./logger"), exports);
+__exportStar(require("./sender"), exports);
+__exportStar(require("./extensions"), exports);
+__exportStar(require("./platform"), exports);
+__exportStar(require("./host"), exports);

package/lib/logger.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 宿主无关的可注入日志层。
+ *
+ * - core 默认使用静默 logger（测试/嵌入式场景不产生噪音）
+ * - Koishi 层启动时 setLogger(ctx.logger)
+ * - CLI 层启动时 setLogger(consoleLogger)
+ *
+ * 日志分级：
+ * - info/warn/error 正常输出
+ * - debug/verbose 级配合 setVerboseLogging(true) 提升为 info
+ */
+export interface LoggerLike {
+    info(...args: any[]): void;
+    warn(...args: any[]): void;
+    error(...args: any[]): void;
+    debug(...args: any[]): void;
+    success?(...args: any[]): void;
+}
+/** 静默实现：默认注入，保证无宿主时不产生副作用 */
+export declare const silentLogger: LoggerLike;
+/** 控制台实现：CLI / 独立使用 */
+export declare const consoleLogger: LoggerLike;
+/** 注入宿主日志实现（插件启动时调用一次） */
+export declare function setLogger(l: LoggerLike): void;
+export declare function getLogger(): LoggerLike;
+export declare function setVerboseLogging(v: boolean): void;
+/** 始终代理到当前注入的 logger，支持运行期替换 */
+export declare const logger: LoggerLike;
+/** debug/verbose 级日志：debug 配置开启后提升为 info，否则 debug 级 */
+export declare function debugLog(...args: any[]): void;

package/lib/logger.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * 宿主无关的可注入日志层。
+ *
+ * - core 默认使用静默 logger（测试/嵌入式场景不产生噪音）
+ * - Koishi 层启动时 setLogger(ctx.logger)
+ * - CLI 层启动时 setLogger(consoleLogger)
+ *
+ * 日志分级：
+ * - info/warn/error 正常输出
+ * - debug/verbose 级配合 setVerboseLogging(true) 提升为 info
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = exports.consoleLogger = exports.silentLogger = void 0;
+exports.setLogger = setLogger;
+exports.getLogger = getLogger;
+exports.setVerboseLogging = setVerboseLogging;
+exports.debugLog = debugLog;
+/** 静默实现：默认注入，保证无宿主时不产生副作用 */
+exports.silentLogger = {
+    info() { },
+    warn() { },
+    error() { },
+    debug() { },
+    success() { },
+};
+/** 控制台实现：CLI / 独立使用 */
+exports.consoleLogger = {
+    info: (...a) => console.log(...a),
+    warn: (...a) => console.warn(...a),
+    error: (...a) => console.error(...a),
+    debug: (...a) => { if (process.env.DEBUG)
+        console.debug(...a); },
+};
+let current = exports.silentLogger;
+let verbose = false;
+/** 注入宿主日志实现（插件启动时调用一次） */
+function setLogger(l) { current = l ?? exports.silentLogger; }
+function getLogger() { return current; }
+function setVerboseLogging(v) { verbose = v; }
+/** 始终代理到当前注入的 logger，支持运行期替换 */
+exports.logger = {
+    info: (...a) => current.info(...a),
+    warn: (...a) => current.warn(...a),
+    error: (...a) => current.error(...a),
+    debug: (...a) => current.debug(...a),
+    success: (...a) => (current.success ?? current.info)(...a),
+};
+function fmt(args) {
+    return args.map(a => {
+        try {
+            return typeof a === 'object' ? JSON.stringify(a) : String(a);
+        }
+        catch {
+            return '[unserializable]';
+        }
+    }).join(' ');
+}
+/** debug/verbose 级日志：debug 配置开启后提升为 info，否则 debug 级 */
+function debugLog(...args) {
+    const line = fmt(args);
+    if (verbose)
+        exports.logger.info(line);
+    else
+        exports.logger.debug(line);
+}

package/lib/platform.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 平台定义契约：每个平台的自描述单元，是「每平台一个包」的基础。
+ *
+ * 一个 PlatformDefinition 应自包含该平台的全部静态信息（链接规则、专属 API、
+ * 提示等）；动态解析逻辑（normalize/parseNative）在后续阶段以可选钩子加入。
+ */
+export interface PlatformDefinition {
+    /** 平台类型标识（与 config.platformEnabled 的键一致） */
+    type: string;
+    /** 链接识别规则（全局标志由聚合层统一处理） */
+    rules: RegExp[];
+    /** 平台专属 API（双网关；缺省走主 API） */
+    dedicated?: {
+        /** 旧网关 api.bugpk.com（无需 Key） */
+        legacy?: string;
+        /** 新网关 api-new.ifphp.com（需 Key） */
+        next?: string;
+    };
+    /** 是否默认优先专属 API（可被 config.platformDedicatedFirst 覆盖） */
+    dedicatedFirst?: boolean;
+    /** 解析失败时的平台特定引导提示 */
+    hints?: string[];
+}

package/lib/platform.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/sender.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 发送层契约（core 与宿主解耦的关键接缝）。
+ *
+ * core 只构建与发送层无关的「出站元素」(OutboundElement)，由宿主提供的
+ * OutboundSender 翻译为具体实现：
+ * - Koishi 层：翻译为 koishi `h` 元素并调用 `session.send`
+ * - CLI 层：翻译为纯文本 / 下载动作
+ *
+ * 这样 core 的 flush/compose/forward 不依赖任何宿主 SDK。
+ */
+/** 出站元素（发送层无关 IR） */
+export type OutboundElement = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    url?: string;
+    buffer?: Buffer;
+    mime?: string;
+} | {
+    type: 'video';
+    url: string;
+} | {
+    type: 'audio';
+    url: string;
+} | {
+    type: 'quote';
+    id: string;
+};
+/** 合并转发的一个气泡 */
+export interface ForwardBubble {
+    content: OutboundElement[];
+    /** 气泡作者 id（缺省由发送层用 session.selfId） */
+    id?: string;
+    /** 气泡作者昵称 */
+    name?: string;
+}
+/** 会话最小面（Koishi session / CLI 上下文均可满足） */
+export interface SessionLike {
+    platform?: string;
+    selfId?: string;
+    userId?: string;
+    channelId?: string;
+    guildId?: string;
+    messageId?: string;
+    send?(content: any): Promise<any>;
+    [key: string]: any;
+}
+export interface OutboundSender {
+    /** 发送一组出站元素；retries 覆盖默认重试次数 */
+    send(session: SessionLike, elements: OutboundElement[], retries?: number): Promise<any>;
+    /** 发送合并转发（每个 ForwardBubble 一个气泡） */
+    sendForward(session: SessionLike, bubbles: ForwardBubble[], retries?: number): Promise<any>;
+}
+/** 出站元素构造器（避免各模块散落字面量） */
+export declare const el: {
+    text: (text: string) => OutboundElement;
+    image: (url: string) => OutboundElement;
+    imageBuffer: (buffer: Buffer, mime: string) => OutboundElement;
+    video: (url: string) => OutboundElement;
+    audio: (url: string) => OutboundElement;
+    quote: (id: string) => OutboundElement;
+};
+/** 视频元素发送失败时的文本降级 */
+export declare function videoFallback(element: OutboundElement): OutboundElement;

package/lib/sender.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * 发送层契约（core 与宿主解耦的关键接缝）。
+ *
+ * core 只构建与发送层无关的「出站元素」(OutboundElement)，由宿主提供的
+ * OutboundSender 翻译为具体实现：
+ * - Koishi 层：翻译为 koishi `h` 元素并调用 `session.send`
+ * - CLI 层：翻译为纯文本 / 下载动作
+ *
+ * 这样 core 的 flush/compose/forward 不依赖任何宿主 SDK。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.el = void 0;
+exports.videoFallback = videoFallback;
+/** 出站元素构造器（避免各模块散落字面量） */
+exports.el = {
+    text: (text) => ({ type: 'text', text }),
+    image: (url) => ({ type: 'image', url }),
+    imageBuffer: (buffer, mime) => ({ type: 'image', buffer, mime }),
+    video: (url) => ({ type: 'video', url }),
+    audio: (url) => ({ type: 'audio', url }),
+    quote: (id) => ({ type: 'quote', id }),
+};
+/** 视频元素发送失败时的文本降级 */
+function videoFallback(element) {
+    return element.type === 'video' ? exports.el.text(`视频链接：${element.url}`) : element;
+}

package/lib/types.d.ts

@@ -0,0 +1,74 @@
+export interface VideoQuality {
+    quality: string;
+    url: string;
+    bit_rate?: number;
+}
+export interface ParsedData {
+    type: string;
+    title: string;
+    desc: string;
+    author: string;
+    uid: string;
+    avatar: string;
+    cover: string;
+    video: string;
+    videos: VideoQuality[];
+    images: string[];
+    live_photo: Array<{
+        image: string;
+        video: string;
+    }>;
+    music: {
+        title?: string;
+        author?: string;
+        cover?: string;
+        url?: string;
+    };
+    like: number;
+    comment: number;
+    collect: number;
+    share: number;
+    play: number;
+    duration: number;
+    publishTime: number;
+    author_followers: number;
+    author_signature: string;
+    admire: number;
+    /** 推文动图（animated_gif）：True 时可按配置转 GIF 发送 */
+    isGif?: boolean;
+    /** 多视频推文的其余视频（第一个在 video 字段；每项带自身 isGif/时长/封面） */
+    extraVideos?: {
+        url: string;
+        isGif?: boolean;
+        duration?: number;
+        cover?: string;
+    }[];
+    /** 推文语种（BCP-47 短码，如 fr/zh/und），供翻译跳过判定 */
+    lang?: string;
+    /** 外语推文译文（tweetTranslate 开启时填充，经 ${翻译} 展示） */
+    translation?: string;
+    /** 译文提供方（Grok / Google / MyMemory），随译文一起展示 */
+    translationProvider?: string;
+}
+export interface LinkMatch {
+    type: string;
+    url: string;
+    id: string;
+}
+export interface ApiItem {
+    url: string;
+    label: string;
+    apiKey?: string;
+    authHeaderType?: string;
+    customHeaderName?: string;
+    fieldMapping?: Record<string, string>;
+}
+export interface CustomPlatformConfig {
+    name: string;
+    apiUrl: string;
+    apiKey: string;
+    authHeaderType: string;
+    customHeaderName: string;
+    fieldMapping?: Record<string, string>;
+    proxy?: any;
+}

package/lib/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@sns-parse/core",
+  "version": "0.1.0",
+  "description": "sns-parse 核心契约与宿主抽象：类型、可注入日志、Host、发送层契约、平台定义",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf lib",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "sns-parse",
+    "video",
+    "parser",
+    "core",
+    "koishi"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "rimraf": "^5.0.5",
+    "typescript": "^5.3.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sns-parse/core.git"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}