@aalis/api-media 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ace Nyan <ace@acenyan.com>
+
+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/dist/index.d.ts

@@ -0,0 +1,212 @@
+import type { ModelRef } from '@aalis/api-llm';
+import type { Context } from '@aalis/core';
+import type { IncomingMessage, MessageAttachment } from '@aalis/schema-message';
+/** 媒体能力枚举（与 LLM Capability 互不重叠：LLM 描述模型能力，Media 描述处理动作） */
+export type MediaCapability = 
+/** 给图描述（含动图抽帧后整合） */
+'vision'
+/**
+ * 音频→文本。同一个能力同时覆盖：
+ * - 语音转写（whisper / LLM-as-ASR）
+ * - 音乐/环境音/旋律描述（需 audio-LLM）
+ * processor 在其 transcribe() 中返回适合该音频的文本表示。
+ */
+ | 'audio'
+/** 视频原生理解（passthrough，需要 LLM 支持 video） */
+ | 'video.passthrough'
+/** 文档内嵌图片识别（OCR / 图理解） */
+ | 'document.image';
+/** Processor 的处理动作语义。一个 backend 可同时声明多种 cap。 */
+export interface MediaProcessor {
+    /** 唯一标识，建议 `<provider>:<modelOrKind>` 形式 */
+    name: string;
+    /** 可处理的能力集 */
+    capabilities: MediaCapability[];
+    /** 显示名（UI 用） */
+    displayName?: string;
+    /** 优先级（数值大者优先；同 cap 多 processor 时由 MediaService 仲裁；默认 0） */
+    priority?: number;
+    /** 描述/识别（用于 vision / document.image / video.passthrough） */
+    describe?(input: DescribeInput, ctx: Context): Promise<DescribeResult>;
+    /**
+     * 音频→文本（用于 audio cap）。返回的 text 应能让下游 LLM
+     * “听懂”该音频：语音输原文转写；音乐/环境音输描述；听不清也要说出听到什么。
+     */
+    transcribe?(input: TranscribeInput, ctx: Context): Promise<TranscribeResult>;
+}
+export interface DescribeInput {
+    /** 待描述的附件（同一 batch 内 mime/kind 由调用方保证一致） */
+    attachments: MessageAttachment[];
+    /**
+     * 主提示词覆盖（可选）：调用方决定本次 describe 用哪段 prompt 时，
+     * 应该传 basePrompt 而非 hint —— adapter 会用 basePrompt 完全替换默认 base，
+     * 不会让默认 prompt 和调用方 prompt 同时存在产生指令冲突。
+     * 留空则 adapter 使用 wrap 时注入的默认 prompt（即 config 里的 vision.prompt）
+     * 或内置 DEFAULT_VISION_PROMPT。
+     */
+    basePrompt?: string;
+    /**
+     * 追加约束提示（可选）：在 base prompt 与 context 之后追加，
+     * 语义是"再加一条要求"，例如 "请重点描述左上角"。
+     * ⚠️ 不要把另一段完整 prompt 塞进 hint，会与 base 冲突；那种场景请用 basePrompt。
+     */
+    hint?: string;
+    /**
+     * 对话上下文文本（可选）：plugin-media 从近期聊天历史构建，
+     * processor 可拼接到 prompt 里让 LLM 能联系上下文理解附件。
+     */
+    context?: string;
+    /** 期望最大输出 token */
+    maxTokens?: number;
+    /** 调用语义：'single' 每个 attachment 单独描述；'combined' 合并描述 */
+    mode?: 'single' | 'combined';
+}
+export interface DescribeResult {
+    /** 与 attachments 等长（mode=single）或单元素（mode=combined） */
+    descriptions: string[];
+    /** 用于审计 / debug */
+    meta?: {
+        processor: string;
+        model?: string;
+        tokens?: number;
+    };
+}
+export interface TranscribeInput {
+    /** 单条音频 attachment */
+    attachment: MessageAttachment;
+    /** 期望语种（ISO 639-1，如 'zh' / 'en'）；不填由 backend 自检 */
+    language?: string;
+    /** 是否需要时间戳分段 */
+    withTimestamps?: boolean;
+    /**
+     * 对话上下文文本（可选）：仅当 backend 为 LLM-as-audio（如 gemma4:e4b）时有意义；
+     * 传统 Whisper 类 ASR 端点会忽略。
+     */
+    context?: string;
+}
+export interface TranscribeResult {
+    /** 完整文本 */
+    text: string;
+    /** 分段（如 backend 提供） */
+    segments?: Array<{
+        start: number;
+        end: number;
+        text: string;
+    }>;
+    /** 检测到的语种 */
+    language?: string;
+    meta?: {
+        processor: string;
+        model?: string;
+    };
+}
+/** plugin-media 暴露的服务（subsystem='media'） */
+export interface MediaService {
+    /** 注册非 LLM 的 backend（LLM 走内置 adapter 自动注册，无需手动调用） */
+    registerProcessor(p: MediaProcessor): () => void;
+    /** 列出当前可用 processor */
+    listProcessors(cap?: MediaCapability): MediaProcessor[];
+    /** 选 processor：优先 prefer（可是 processor name 字符串或 LLM ModelRef），再按 priority；找不到返回 null */
+    pickProcessor(cap: MediaCapability, prefer?: string | ModelRef | null): MediaProcessor | null;
+    /** 描述：根据每个 attachment 的 kind/mime 自动选 processor */
+    describe(attachments: MessageAttachment[], opts?: DescribeOptions): Promise<Array<string | undefined>>;
+    /** 转写：单条音频 */
+    transcribe(attachment: MessageAttachment, opts?: TranscribeOptions): Promise<string | undefined>;
+    /**
+     * 一站式：处理整条 IncomingMessage 的所有 attachments，
+     * 把每条附件的文本描述写入 msg._attachmentDescriptions（与 attachments 同长度）。
+     * 由 plugin-media 的 preprocessor 内部调用，外部一般不需要直接用。
+     */
+    processMessage(msg: IncomingMessage): Promise<MediaProcessReport>;
+    /**
+     * 主动描述单张图片（含动图自动多帧）。失败返回空串。
+     * 与 describe([att]) 不同：本方法专为 `analyze_image` 等单图工具优化，
+     * 内部走描述缓存（同 url 24h 内复用）；可传 hint 注入用户意图。
+     */
+    describeImage(imageUrl: string, opts?: DescribeImageOptions): Promise<string>;
+    /**
+     * 主动描述单个视频（按 URL 或本地路径）。抽帧 + 可选音轨转写，失败返回空串。
+     * 与 `describe([videoAttachment])` 等价但更适合按 URL 直接调用的工具/适配器场景。
+     */
+    describeVideo(videoUrl: string, opts?: DescribeVideoOptions): Promise<string>;
+    /** 查描述缓存（不触发识别）。未命中返回 null。 */
+    lookupDescription(imageUrl: string): string | null;
+    /** 写入描述缓存（一般由 describeImage 自动调用，外部很少用）。 */
+    rememberDescription(imageUrl: string, description: string): void;
+    /**
+     * 为含图消息构造视觉识别上下文（当前消息 + 引用消息 + 最近历史）。
+     * 用作 vision LLM 的 hint，让模型聚焦用户真正关心的问题。
+     */
+    buildContext(msg: IncomingMessage, opts?: BuildContextOptions): Promise<string>;
+}
+export interface DescribeImageOptions {
+    /** 用户意图 / 上下文（如 "找出图中的猫"） */
+    hint?: string;
+    /** 本地缓存路径（用于动图帧提取，避免重新下载远程文件） */
+    localPath?: string;
+    /** 跳过缓存读写（true 时即使有缓存也会重新识别） */
+    noCache?: boolean;
+    /** 最大输出 token */
+    maxTokens?: number;
+    /**
+     * 描述详略级别（默认 'auto'）：
+     * - `'casual'`：简洁日常描述（200 字以内、识别梗/游戏标志、不列点），用于聊天截图/表情包/生活照
+     * - `'detailed'`：详细图像识别（不限字数、聚焦图像整体详情/网络梗/代码/表格），用于一般信息密度高的图
+     * - `'professional'`：专业学科题目识别（严格 LaTeX、几何坐标识别、几何形状反幻觉），用于数学/物理/化学题
+     * - `'auto'`：先做轻量 4 标签分类（professional/document/casual/mixed）后选择对应档位；分类失败 fallback 到 detailed
+     */
+    detailLevel?: 'auto' | 'casual' | 'detailed' | 'professional';
+}
+export interface DescribeVideoOptions {
+    /** 用户意图 / 上下文（如 "提取视频中出现的所有人名"） */
+    hint?: string;
+    /** 本地缓存路径（避免重新下载） */
+    localPath?: string;
+    /** 最大输出 token */
+    maxTokens?: number;
+}
+export interface BuildContextOptions {
+    /** 最近前文条数，默认由实现决定 */
+    beforeLimit?: number;
+}
+export interface DescribeOptions {
+    hint?: string;
+    maxTokens?: number;
+    /** 强制使用某个 processor（processor name 或 LLM ModelRef） */
+    prefer?: string | ModelRef;
+}
+export interface TranscribeOptions {
+    language?: string;
+    withTimestamps?: boolean;
+    prefer?: string | ModelRef;
+}
+export interface MediaProcessReport {
+    total: number;
+    successCount: number;
+    /** 与 msg.attachments 同长度，对应每条的处理结果摘要 */
+    items: Array<{
+        kind: MessageAttachment['kind'];
+        cap?: MediaCapability;
+        processor?: string;
+        description?: string;
+        error?: string;
+    }>;
+}
+declare module '@aalis/core' {
+    interface AalisEvents {
+        /**
+         * 一条入站消息的所有附件已被 plugin-media 处理（成功或失败均会发）。
+         * 用于 webui / archive / 调试日志。
+         */
+        'media:processed': [data: {
+            sessionId: string;
+            report: MediaProcessReport;
+        }];
+    }
+}
+declare module '@aalis/core' {
+    interface ServiceTypeMap {
+        media: MediaService;
+    }
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,12 @@
+// ============================================================
+// @aalis/api-media — 多模态媒体识别契约
+//
+// Aalis 把"媒体 → 文本"的处理路径抽象为 MediaProcessor。
+// plugin-media 既是该契约的调度器，也是 LLM 服务的内置 adapter
+// （任意声明了 vision / audio 能力的 LLM 都自动暴露为对应 processor）。
+// 真正"非 LLM"的 backend（如 whisper.cpp / 云 ASR）则注册为独立 processor。
+//
+// 依赖：仅 @aalis/core 与 @aalis/schema-message。
+// ============================================================
+export {};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,+BAA+B;AAC/B,EAAE;AACF,2CAA2C;AAC3C,8CAA8C;AAC9C,qDAAqD;AACrD,6DAA6D;AAC7D,EAAE;AACF,4CAA4C;AAC5C,+DAA+D"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@aalis/api-media",
+  "version": "0.9.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AalisLabs/Aalis.git",
+    "directory": "packages/api-media"
+  },
+  "author": "Ace Nyan <ace@acenyan.com>",
+  "bugs": {
+    "url": "https://github.com/AalisLabs/Aalis/issues"
+  },
+  "homepage": "https://github.com/AalisLabs/Aalis#readme",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@aalis/api-llm": ">=0.9.0 <1.0.0",
+    "@aalis/schema-message": ">=0.5.1 <1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "@aalis/core": "0.10.0"
+  },
+  "aalis": {
+    "types": true
+  },
+  "peerDependencies": {
+    "@aalis/core": ">=0.2.0 <1.0.0"
+  },
+  "keywords": [
+    "aalis",
+    "aalis-api"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  }
+}