mioku-plugin-music 3.0.3 → 3.1.0

package/README.md

@@ -6,11 +6,84 @@
 - 搜索结果截图列表
 - 编号听歌（语音）：`.听1`
 - 编号听歌（原曲文件，群聊也直接发文件）：`.原曲1`
+- 私聊文件解密：私聊发送匹配后缀的文件
 - AI skills：搜索、发送歌曲
 
 ## 已适配 Provider
 
 - `applemusic`
+- `netease`
+
+## 已适配 Dump Provider
+
+- `ncmdump`（`mioku-service-ncmdump`，支持 `.ncm`）
+
+## 可选服务与自动安装
+
+`defaultProvider` / `dumpProvider` 对应的服务都是可选安装：
+
+1. 在配置中选择（如 `base.dumpProvider = "ncmdump"`）
+2. 重启 Bot，插件检测到服务包未安装时自动在后台执行 `bun add mioku-service-ncmdump`（从 npm）
+3. 再次重启后服务加载，功能生效
+
+## Dump Provider 对接要求
+
+`music` 插件通过"服务 API + dump provider 适配器"接入新的解密服务（如 kgm/qmc 等）。规范与 music provider 对称：
+
+### 1. 服务 API 标准（服务包侧）
+
+服务包（`mioku-service-<name>`）需导出 `defineService` 的 `ServiceRef` 并实现以下接口：
+
+```ts
+export interface DumpConvertInput {
+  readonly inputPath: string; // 已下载到本地的加密文件
+  readonly outputDir?: string; // 缺省为输入文件所在目录
+}
+
+export interface DumpConvertOutput {
+  readonly filePath: string; // 解密后的本地文件
+  readonly fileName: string; // 输出文件名（含扩展名）
+}
+
+export interface DumpServiceApi {
+  ensureReady(): Promise<unknown>; // 确保二进制/依赖可用
+  convert(input: DumpConvertInput): Promise<DumpConvertOutput>;
+}
+```
+
+服务自身负责二进制/外部依赖的跨平台引导（Homebrew、gh-proxy 下载解压等），插件不感知平台差异。参考实现见 `mioku-service-ncmdump`。
+
+### 2. 插件侧适配器标准（`DumpProvider`）
+
+在 `dumps/` 下新增适配器并注册到 `dumps/factory.ts` 的 `DUMP_PROVIDER_REGISTRY`：
+
+```ts
+export interface DumpProvider {
+  readonly name: DumpProviderName;
+  readonly extensions: readonly string[]; // 触发后缀，如 [".ncm"]
+  dump(target: DumpTarget): Promise<DumpResult>;
+}
+
+export interface DumpTarget {
+  readonly sourcePath: string; // 已下载到本地的加密文件
+  readonly fileName: string; // 原始文件名
+  readonly outputDir: string; // 输出目录（temp/ncmdump/jobs/<id>）
+}
+
+export interface DumpResult {
+  readonly filePath: string; // 解密后的本地文件
+  readonly fileName: string; // 输出文件名
+}
+```
+
+同时补齐：`types.ts` 的 `DumpProviderName` / `DUMP_PROVIDER_NAMES`、`config.md` 的 `base.dumpProvider` 选项、`package.json` 的 peer/devDependencies。
+
+### 3. 行为约束
+
+- 只在**私聊**触发；文件名后缀匹配 `extensions` 才下载，尽量不拉取无关文件
+- **全程静默**：不回复任何进度或错误消息，成功直接发送结果文件；每个阶段的成败与原因都写入 ctx logger
+- 每个文件独立转换、串行执行，转换与下载产物放在 `temp/ncmdump/jobs/<id>/`，发送完成后清理
+- `convert` 一次只处理一个文件；失败抛 `Error`，由上层统一记录日志
 
 ## Provider 对接要求
 

package/config.md

@@ -19,12 +19,24 @@ fields:
         label: Apple Music
       - value: netease
         label: NetEase Cloud Music
+
+  - key: base.dumpProvider
+    label: 文件解密服务
+    type: select
+    description: 私聊发送匹配后缀的文件时自动解密并回传
+    options:
+      - value: ""
+        label: 未启用
+      - value: ncmdump
+        label: ncmdump（网易云 .ncm 解密）
 ---
 
 > 默认音乐源初始为「无」。请先在上方选择提供商，**重启 Bot 后会自动下载对应服务**。
-
+>
+> 文件解密初始为「未启用」。选择后 **重启 Bot 会自动从 npm 安装对应服务包**
 ```mioku-fields
 keys:
   - base.searchLimit
   - base.defaultProvider
+  - base.dumpProvider
 ```

package/config.ts

@@ -3,4 +3,5 @@ import type { MusicBaseConfig } from "./types";
 export const MUSIC_DEFAULTS: MusicBaseConfig = {
   searchLimit: 15,
   defaultProvider: "",
+  dumpProvider: "",
 };

package/dumps/factory.ts

@@ -0,0 +1,78 @@
+import type { NcmdumpServiceApi } from "mioku-service-ncmdump";
+import type { DumpProviderName } from "../types";
+import { NcmdumpProvider } from "./ncmdump";
+import type { DumpProvider } from "./types";
+
+export interface DumpProviderFactoryOptions {
+  ncmdump?: NcmdumpServiceApi;
+}
+
+interface DumpProviderRegistryItem {
+  readonly name: DumpProviderName;
+  readonly serviceName: string;
+  readonly extensions: readonly string[];
+  isAvailable(services: DumpProviderFactoryOptions): boolean;
+  create(services: DumpProviderFactoryOptions): DumpProvider;
+}
+
+const DUMP_PROVIDER_REGISTRY: DumpProviderRegistryItem[] = [
+  {
+    name: "ncmdump",
+    serviceName: "ncmdump",
+    extensions: [".ncm"],
+    isAvailable: (services) => Boolean(services.ncmdump),
+    create: (services) => {
+      if (!services.ncmdump) {
+        throw new Error("ncmdump 服务未加载");
+      }
+      return new NcmdumpProvider(services.ncmdump);
+    },
+  },
+];
+
+function getDumpProviderRegistryItem(
+  providerName: string,
+): DumpProviderRegistryItem | undefined {
+  const normalized = String(providerName || "").trim().toLowerCase();
+  return DUMP_PROVIDER_REGISTRY.find((item) => item.name === normalized);
+}
+
+export function resolveDumpProviderName(
+  preferredProviderName: unknown,
+  services: DumpProviderFactoryOptions,
+): DumpProviderName | null {
+  const preferred = String(preferredProviderName || "").trim();
+  if (preferred) {
+    const item = getDumpProviderRegistryItem(preferred);
+    if (item?.isAvailable(services)) {
+      return item.name;
+    }
+  }
+  return null;
+}
+
+export function getDumpProviderCandidates(): DumpProviderName[] {
+  return DUMP_PROVIDER_REGISTRY.map((item) => item.name);
+}
+
+export function createDumpProvider(
+  providerName: DumpProviderName,
+  services: DumpProviderFactoryOptions,
+): DumpProvider {
+  const item = getDumpProviderRegistryItem(providerName);
+  if (!item) {
+    throw new Error(`不支持的 dump 服务: ${providerName}`);
+  }
+  if (!item.isAvailable(services)) {
+    throw new Error(`${item.serviceName} 服务未加载`);
+  }
+  return item.create(services);
+}
+
+export function dumpProviderExtensions(
+  providerName: DumpProviderName,
+): readonly string[] {
+  return (
+    getDumpProviderRegistryItem(providerName)?.extensions ?? []
+  );
+}

package/dumps/file-source.ts

@@ -0,0 +1,279 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { Attachment, Logger, MessageEvent, MessageSegment } from "mioku";
+
+export interface IncomingFile {
+  readonly name: string;
+  saveTo(destPath: string): Promise<void>;
+}
+
+type SegmentData = Readonly<Record<string, unknown>>;
+
+const strOf = (data: SegmentData, key: string): string | undefined => {
+  const value = data[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+};
+
+const isHttpUrl = (value: string | undefined): value is string =>
+  typeof value === "string" && /^https?:\/\//i.test(value);
+
+const isAbsoluteFsPath = (value: string | undefined): value is string =>
+  typeof value === "string" &&
+  (/^\//.test(value) || /^[A-Za-z]:[\\/]/.test(value));
+
+const toFsPath = (value: string): string => {
+  if (!value.startsWith("file://")) return value;
+  let p = decodeURIComponent(value.slice("file://".length));
+  if (/^\/[A-Za-z]:\//.test(p)) p = p.slice(1);
+  else if (!p.startsWith("/")) p = `/${p}`;
+  return p;
+};
+
+const baseNameOf = (value: string): string =>
+  path.basename(toFsPath(value).split("?")[0] ?? "");
+
+const looksLikeFileName = (value: string | undefined): value is string =>
+  typeof value === "string" && /^[^/\\]+\.[A-Za-z0-9]{1,8}$/.test(value.trim());
+
+const attachmentOf = (seg: MessageSegment): Attachment | undefined => seg.attachment;
+
+async function downloadTo(url: string, destPath: string): Promise<void> {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`文件下载失败: HTTP ${response.status}`);
+  }
+  const buffer = Buffer.from(await response.arrayBuffer());
+  await fs.writeFile(destPath, buffer);
+}
+
+async function copyLocalFile(localPath: string, destPath: string): Promise<void> {
+  const local = toFsPath(localPath);
+  try {
+    await fs.copyFile(local, destPath);
+  } catch {
+    throw new Error(`本地文件读取失败（bot 与 NapCat 不在同一台机器时属预期）: ${local}`);
+  }
+}
+
+interface FileSource {
+  readonly url?: string;
+  readonly localPath?: string;
+  readonly base64?: string;
+}
+
+async function saveSource(source: FileSource, destPath: string): Promise<void> {
+  if (source.base64) {
+    await fs.writeFile(destPath, Buffer.from(source.base64, "base64"));
+    return;
+  }
+  if (isHttpUrl(source.url)) {
+    await downloadTo(source.url, destPath);
+    return;
+  }
+  if (source.localPath) {
+    await copyLocalFile(source.localPath, destPath);
+    return;
+  }
+  throw new Error("无法获取文件下载地址");
+}
+
+function describeSource(source: FileSource): string {
+  if (source.base64) return "get_file base64";
+  if (isHttpUrl(source.url)) return `url ${source.url.slice(0, 80)}`;
+  if (source.localPath) return `本地路径 ${source.localPath}`;
+  return "未知来源";
+}
+
+interface OneBotGetFileResult {
+  readonly file?: string;
+  readonly url?: string;
+  readonly base64?: string;
+  readonly file_name?: string;
+}
+
+function fromOneBot(
+  event: MessageEvent,
+  seg: MessageSegment,
+  logger: Logger,
+): IncomingFile | null {
+  const data = seg.data as SegmentData;
+  const fileField = strOf(data, "file");
+  const name =
+    strOf(data, "file_name") ??
+    strOf(data, "name") ??
+    (looksLikeFileName(fileField) ? fileField.trim() : undefined) ??
+    (isAbsoluteFsPath(fileField) ? baseNameOf(fileField) : undefined) ??
+    attachmentOf(seg)?.name;
+  if (!name) return null;
+
+  const segmentUrl = strOf(data, "url");
+  const segmentLocalPaths = [strOf(data, "path"), fileField].filter(
+    (value): value is string => typeof value === "string" && isAbsoluteFsPath(value),
+  );
+  const idCandidates = [
+    strOf(data, "file_id"),
+    strOf(data, "fid"),
+    looksLikeFileName(fileField) ? undefined : fileField,
+  ].filter((value): value is string => typeof value === "string" && value.length > 0);
+
+  const get_file = async (fileId: string): Promise<OneBotGetFileResult | null> => {
+    try {
+      return await event.bot.sendApi<OneBotGetFileResult>("get_file", {
+        file_id: fileId,
+        file: fileId,
+      });
+    } catch (error) {
+      logger.warn(`[music] get_file(${fileId.slice(0, 60)}) 失败: ${String(error)}`);
+      return null;
+    }
+  };
+
+  const sourcesFromGetFile = (result: OneBotGetFileResult | null): FileSource[] => {
+    if (!result) return [];
+    const sources: FileSource[] = [];
+    if (typeof result.base64 === "string" && result.base64) {
+      sources.push({ base64: result.base64 });
+    }
+    if (isHttpUrl(result.url)) {
+      sources.push({ url: result.url });
+    }
+    if (typeof result.file === "string" && result.file) {
+      sources.push({ localPath: result.file });
+    }
+    return sources;
+  };
+
+  return {
+    name,
+    async saveTo(destPath: string): Promise<void> {
+      let lastError: unknown;
+
+      const trySources = async (
+        sources: readonly FileSource[],
+        tag: string,
+      ): Promise<boolean> => {
+        for (const source of sources) {
+          try {
+            await saveSource(source, destPath);
+            logger.info(`[music] ${name}: ${tag} 成功 (${describeSource(source)})`);
+            return true;
+          } catch (error) {
+            lastError = error;
+            logger.warn(`[music] ${name}: ${tag} 失败 (${describeSource(source)}): ${String(error)}`);
+          }
+        }
+        return false;
+      };
+
+      // 新版 NapCat：段内自带真实下载 URL
+      if (isHttpUrl(segmentUrl)) {
+        if (await trySources([{ url: segmentUrl }], "消息段 url")) return;
+      }
+
+      // 新版 NapCat：get_file（enableLocalFile2Url 时返回 base64，否则返回 NapCat 本地路径）
+      for (const fileId of idCandidates) {
+        const result = await get_file(fileId);
+        if (await trySources(sourcesFromGetFile(result), `get_file(${fileId.slice(0, 60)})`)) return;
+      }
+
+      // NapCat 扩展：私聊文件真实 URL
+      for (const fileId of idCandidates) {
+        try {
+          const result = await event.bot.sendApi<{ url?: string }>("get_private_file_url", {
+            file_id: fileId,
+          });
+          if (isHttpUrl(result?.url)) {
+            if (await trySources([{ url: result.url }], "get_private_file_url")) return;
+          }
+        } catch (error) {
+          logger.warn(`[music] get_private_file_url(${fileId.slice(0, 60)}) 失败: ${String(error)}`);
+        }
+      }
+
+      // 旧版 NapCat 兜底：段内是本机绝对路径（bot 与 NapCat 同机时可用）
+      if (await trySources(segmentLocalPaths.map((localPath) => ({ localPath })), "本地路径直读")) {
+        return;
+      }
+
+      throw lastError ?? new Error("无法获取文件下载地址");
+    },
+  };
+}
+
+interface IcqqFriendFileApi {
+  pickFriend(userId: string): {
+    getFileInfo(fid: string): Promise<{ url?: string; file?: string; name?: string }>;
+  };
+}
+
+function fromIcqq(event: MessageEvent, seg: MessageSegment): IncomingFile | null {
+  const data = seg.data as SegmentData;
+  const fileField = strOf(data, "file");
+  const fid = strOf(data, "fid") ?? fileField?.replace(/^fid:/, "");
+  const name = strOf(data, "name") ?? attachmentOf(seg)?.name;
+  if (!fid || !name) return null;
+
+  return {
+    name,
+    async saveTo(destPath: string): Promise<void> {
+      const bot = event.bot.as<IcqqFriendFileApi>();
+      if (typeof bot.pickFriend !== "function") {
+        throw new Error("当前 icqq bot 不支持 pickFriend，无法下载文件");
+      }
+      const info = await bot.pickFriend(String(event.user_id ?? "")).getFileInfo(fid);
+      await saveSource(
+        {
+          url: typeof info?.url === "string" ? info.url : undefined,
+          localPath: typeof info?.file === "string" ? info.file : undefined,
+        },
+        destPath,
+      );
+    },
+  };
+}
+
+function fromAttachment(_event: MessageEvent, seg: MessageSegment): IncomingFile | null {
+  const data = seg.data as SegmentData;
+  const attachment = attachmentOf(seg);
+  const url = strOf(data, "url") ?? attachment?.url;
+  const name =
+    strOf(data, "name") ??
+    attachment?.name ??
+    (isHttpUrl(url) ? decodeURIComponent(baseNameOf(url)) : undefined);
+  if (!name || !isHttpUrl(url)) return null;
+
+  return {
+    name,
+    async saveTo(destPath: string): Promise<void> {
+      await downloadTo(url, destPath);
+    },
+  };
+}
+
+function buildIncomingFile(
+  event: MessageEvent,
+  seg: MessageSegment,
+  logger: Logger,
+): IncomingFile | null {
+  const adapter = event.identity.adapter;
+  if (adapter === "onebotv11") return fromOneBot(event, seg, logger);
+  if (adapter === "icqq") return fromIcqq(event, seg);
+  return fromAttachment(event, seg);
+}
+
+export function extractIncomingFiles(
+  event: MessageEvent,
+  extensions: readonly string[],
+  logger: Logger,
+): IncomingFile[] {
+  const normalized = extensions.map((ext) => ext.toLowerCase());
+  const files: IncomingFile[] = [];
+  for (const seg of event.message.filterByType("file")) {
+    const file = buildIncomingFile(event, seg, logger);
+    if (!file) continue;
+    if (normalized.some((ext) => file.name.toLowerCase().endsWith(ext))) {
+      files.push(file);
+    }
+  }
+  return files;
+}

package/dumps/ncmdump.ts

@@ -0,0 +1,22 @@
+import type { NcmdumpServiceApi } from "mioku-service-ncmdump";
+import type { DumpProviderName } from "../types";
+import type { DumpProvider, DumpResult, DumpTarget } from "./types";
+
+export class NcmdumpProvider implements DumpProvider {
+  readonly name: DumpProviderName = "ncmdump";
+  readonly extensions: readonly string[] = [".ncm"];
+
+  private readonly service: NcmdumpServiceApi;
+
+  constructor(service: NcmdumpServiceApi) {
+    this.service = service;
+  }
+
+  async dump(target: DumpTarget): Promise<DumpResult> {
+    const result = await this.service.convert({
+      inputPath: target.sourcePath,
+      outputDir: target.outputDir,
+    });
+    return { filePath: result.filePath, fileName: result.fileName };
+  }
+}

package/dumps/types.ts

@@ -0,0 +1,18 @@
+import type { DumpProviderName } from "../types";
+
+export interface DumpTarget {
+  readonly sourcePath: string;
+  readonly fileName: string;
+  readonly outputDir: string;
+}
+
+export interface DumpResult {
+  readonly filePath: string;
+  readonly fileName: string;
+}
+
+export interface DumpProvider {
+  readonly name: DumpProviderName;
+  readonly extensions: readonly string[];
+  dump(target: DumpTarget): Promise<DumpResult>;
+}

package/index.ts

@@ -1,42 +1,76 @@
 import { definePlugin } from "mioku";
-import { AppleMusicService } from "mioku-service-applemusic";
-import { NeteaseService } from "mioku-service-netease";
 import { getService, Services } from "mioku";
+import type { MessageEvent } from "mioku";
+import type { AppleMusicServiceApi } from "mioku-service-applemusic";
+import type { NeteaseServiceApi } from "mioku-service-netease";
+import type { NcmdumpServiceApi } from "mioku-service-ncmdump";
 import { MusicPluginRuntime } from "./runtime-core/service";
 import { MUSIC_DEFAULTS } from "./config";
 import type { MusicBaseConfig } from "./types";
 import { createMusicSkills } from "./skills/music";
+import { importOptionalService } from "./runtime-core/optional-service";
+import { installMissingOptionalServices } from "./runtime-core/auto-install";
+import { DumpFlow } from "./runtime-core/dump-flow";
+import { dumpProviderExtensions } from "./dumps/factory";
+import { extractIncomingFiles } from "./dumps/file-source";
 
 function cloneConfig<T>(value: T): T {
   return JSON.parse(JSON.stringify(value)) as T;
 }
 
+function mergeWithDefaults(next: unknown): MusicBaseConfig {
+  return { ...cloneConfig(MUSIC_DEFAULTS), ...(next as MusicBaseConfig) };
+}
+
+type PrivateMessageRoute =
+  | "onebotv11:message.private"
+  | "icqq:message.private"
+  | "qq-official:message.private";
+
+const PRIVATE_MESSAGE_ROUTES: readonly PrivateMessageRoute[] = [
+  "onebotv11:message.private",
+  "icqq:message.private",
+  "qq-official:message.private",
+];
+
 export default definePlugin({
   name: "music",
   async setup(ctx) {
     const configService = getService(ctx, Services.Config);
     const aiService = getService(ctx, Services.AI);
     const screenshotService = getService(ctx, Services.Screenshot);
-    const applemusicService = getService(ctx, AppleMusicService);
-    const neteaseService = getService(ctx, NeteaseService);
+    const [applemusicRef, neteaseRef, ncmdumpRef] = await Promise.all([
+      importOptionalService<AppleMusicServiceApi>(
+        "mioku-service-applemusic",
+        "AppleMusicService",
+      ),
+      importOptionalService<NeteaseServiceApi>("mioku-service-netease", "NeteaseService"),
+      importOptionalService<NcmdumpServiceApi>("mioku-service-ncmdump", "NcmdumpService"),
+    ]);
+    const applemusicService = applemusicRef ? getService(ctx, applemusicRef) : undefined;
+    const neteaseService = neteaseRef ? getService(ctx, neteaseRef) : undefined;
+    const ncmdumpService = ncmdumpRef ? getService(ctx, ncmdumpRef) : undefined;
     let baseConfig = cloneConfig(MUSIC_DEFAULTS);
 
     if (configService) {
       await configService.registerConfig("music", "base", baseConfig);
       const nextBase = await configService.getConfig("music", "base");
       if (nextBase) {
-        baseConfig = nextBase as MusicBaseConfig;
+        baseConfig = mergeWithDefaults(nextBase);
       }
     } else {
       ctx.logger.warn("config-service 未加载，music 插件将使用默认配置");
     }
 
+    installMissingOptionalServices(ctx.logger, baseConfig);
+
     const runtime = new MusicPluginRuntime({
       logger: ctx.logger,
       aiService,
       screenshotService,
       applemusicService,
       neteaseService,
+      ncmdumpService,
     });
     runtime.updateConfig(baseConfig);
 
@@ -48,13 +82,28 @@ export default definePlugin({
     if (configService) {
       disposers.push(
         configService.onConfigChange("music", "base", (next) => {
-          baseConfig = next as MusicBaseConfig;
+          baseConfig = mergeWithDefaults(next);
           runtime.updateConfig(baseConfig);
+          installMissingOptionalServices(ctx.logger, baseConfig);
         }),
       );
     }
 
-    const react = (event: any) => runtime.tryReactToCommandMessage(ctx, event);
+    const dumpFlow = new DumpFlow({ logger: ctx.logger });
+    disposers.push(
+      ctx.handle(PRIVATE_MESSAGE_ROUTES, (event) => {
+        const provider = runtime.resolveDumpProvider();
+        if (!provider) return;
+        const files = extractIncomingFiles(
+          event,
+          dumpProviderExtensions(provider.name),
+          ctx.logger,
+        );
+        for (const file of files) dumpFlow.enqueue(ctx, event, provider, file);
+      }),
+    );
+
+    const react = (event: MessageEvent) => runtime.tryReactToCommandMessage(ctx, event);
 
     ctx.command({
       prefixes: false,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mioku-plugin-music",
-  "version": "3.0.3",
-  "description": "音乐插件：点歌、搜索音乐、听歌语音发送",
+  "version": "3.1.0",
+  "description": "音乐插件：点歌、搜索音乐、听歌语音发送、私聊 ncm 文件解密",
   "main": "index.ts",
   "type": "module",
   "keywords": [
@@ -21,11 +21,13 @@
   "peerDependencies": {
     "mioku": "^1.0.0",
     "mioku-service-applemusic": "^3.0.0",
-    "mioku-service-netease": "^2.0.0"
+    "mioku-service-netease": "^2.0.0",
+    "mioku-service-ncmdump": "^1.0.0"
   },
   "devDependencies": {
     "mioku": "workspace:*",
     "mioku-service-applemusic": "workspace:*",
-    "mioku-service-netease": "workspace:*"
+    "mioku-service-netease": "workspace:*",
+    "mioku-service-ncmdump": "workspace:*"
   }
 }

package/runtime-core/auto-install.ts

@@ -0,0 +1,54 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import * as path from "node:path";
+import type { Logger } from "mioku";
+import type { MusicBaseConfig } from "../types";
+
+const SERVICE_PACKAGE_PREFIX = "mioku-service-";
+const attempted = new Set<string>();
+
+function desiredServiceShortNames(config: MusicBaseConfig): string[] {
+  const names: string[] = [];
+  for (const value of [config.defaultProvider, config.dumpProvider]) {
+    const short = String(value ?? "").trim().toLowerCase();
+    if (short) names.push(short);
+  }
+  return [...new Set(names)];
+}
+
+function isPackageInstalled(pkgName: string): boolean {
+  return existsSync(path.join(process.cwd(), "node_modules", pkgName, "package.json"));
+}
+
+export function installMissingOptionalServices(
+  logger: Logger,
+  config: MusicBaseConfig,
+): void {
+  for (const short of desiredServiceShortNames(config)) {
+    const pkgName = `${SERVICE_PACKAGE_PREFIX}${short}`;
+    if (attempted.has(pkgName) || isPackageInstalled(pkgName)) continue;
+    attempted.add(pkgName);
+
+    logger.info(
+      `[music] ${short} 已在配置中启用但服务包未安装，正在后台执行 bun add ${pkgName}，完成后重启生效`,
+    );
+    const child = spawn("bun", ["add", pkgName], {
+      cwd: process.cwd(),
+      detached: true,
+      shell: process.platform === "win32",
+      stdio: "ignore",
+      windowsHide: true,
+    });
+    child.on("error", (err: unknown) => {
+      logger.warn(`[music] 自动安装 ${pkgName} 失败: ${String(err)}`);
+    });
+    child.on("close", (code: number | null) => {
+      if (code === 0) {
+        logger.info(`[music] ${pkgName} 安装完成，重启后生效`);
+      } else {
+        logger.warn(`[music] 自动安装 ${pkgName} 失败（退出码 ${code ?? "unknown"}）`);
+      }
+    });
+    child.unref();
+  }
+}

package/runtime-core/dump-flow.ts

@@ -0,0 +1,72 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import type { Logger, MessageEvent, MiokuContext } from "mioku";
+import type { DumpProvider } from "../dumps/types";
+import type { IncomingFile } from "../dumps/file-source";
+import { sendFileMessage } from "./message";
+
+const DUMP_TEMP_ROOT = path.join(process.cwd(), "temp", "ncmdump");
+const JOBS_DIR = path.join(DUMP_TEMP_ROOT, "jobs");
+
+function sanitizeFileName(name: string): string {
+  const base = path.basename(name).replace(/[\u0000-\u001f]/g, "");
+  return base.length > 0 ? base : `file-${Date.now()}`;
+}
+
+function stripExtension(fileName: string): string {
+  const index = fileName.lastIndexOf(".");
+  return index > 0 ? fileName.slice(0, index) : fileName;
+}
+
+function shortError(error: unknown): string {
+  return String(error)
+    .replace(/^Error:\s*/, "")
+    .trim()
+    .slice(0, 160);
+}
+
+async function createJobDir(): Promise<string> {
+  const jobDir = path.join(JOBS_DIR, `${Date.now()}-${randomUUID().slice(0, 8)}`);
+  await fs.mkdir(jobDir, { recursive: true });
+  return jobDir;
+}
+
+export class DumpFlow {
+  private tail: Promise<void> = Promise.resolve();
+
+  constructor(private readonly deps: { logger: Logger }) {}
+
+  enqueue(ctx: MiokuContext, event: MessageEvent, provider: DumpProvider, file: IncomingFile): void {
+    this.tail = this.tail
+      .then(() => this.process(ctx, event, provider, file))
+      .catch((error: unknown) => {
+        this.deps.logger.warn(`[music] dump 任务异常: ${shortError(error)}`);
+      });
+  }
+
+  private async process(
+    ctx: MiokuContext,
+    event: MessageEvent,
+    provider: DumpProvider,
+    file: IncomingFile,
+  ): Promise<void> {
+    const { logger } = this.deps;
+    const jobDir = await createJobDir();
+    try {
+      const sourcePath = path.join(jobDir, sanitizeFileName(file.name));
+      await file.saveTo(sourcePath);
+      const result = await provider.dump({
+        sourcePath,
+        fileName: file.name,
+        outputDir: jobDir,
+      });
+      await sendFileMessage(ctx, event, result.filePath, stripExtension(result.fileName));
+      logger.info(`[music] dump 完成: ${file.name} -> ${result.fileName} (${provider.name})`);
+    } catch (error) {
+      logger.error(`[music] dump 失败 (${file.name}): ${shortError(error)}`);
+    } finally {
+      await fs.rm(jobDir, { recursive: true, force: true });
+    }
+  }
+}

package/runtime-core/message.ts

@@ -1,5 +1,6 @@
 import * as fs from "fs/promises";
 import * as path from "path";
+import type { MessageEvent, MessageSegment, MiokuContext } from "mioku";
 
 function normalizeFileSource(file: string): string {
   const value = String(file || "").trim();
@@ -15,112 +16,88 @@ function normalizeFileSource(file: string): string {
     return value;
   }
   if (value.startsWith("/") || /^[A-Za-z]:[\\/]/.test(value)) {
-    return `file://${value}`;
+    const normalized = value.replace(/\\/g, "/");
+    return `file:///${normalized.replace(/^\//, "")}`;
   }
   return value;
 }
 
-function getBotAndTarget(ctx: any, event: any): {
-  bot: any;
+function getBotAndTarget(event: MessageEvent): {
+  bot: MessageEvent["bot"];
   groupId?: string;
   userId?: string;
 } {
-  const bot = event?.bot;
   const groupId = String(event?.group_id ?? "").trim();
   const userId = String(event?.user_id ?? "").trim();
 
   return {
-    bot,
+    bot: event?.bot,
     groupId: event?.message_type === "group" ? groupId : undefined,
     userId: event?.message_type !== "group" ? userId : undefined,
   };
 }
 
-export async function sendTextMessage(
-  ctx: any,
-  event: any,
-  text: string,
+async function sendSegments(
+  ctx: MiokuContext,
+  event: MessageEvent,
+  segments: readonly MessageSegment[],
 ): Promise<void> {
-  const { bot, groupId, userId } = getBotAndTarget(ctx, event);
-  const payload: any[] = [];
-
-  payload.push(ctx.segment.text(text));
-
+  const { bot, groupId, userId } = getBotAndTarget(event);
   if (bot && groupId != null && groupId !== "") {
-    await bot.sendGroupMsg(groupId, payload);
+    await bot.sendGroupMsg(groupId, [...segments]);
     return;
   }
   if (bot && userId != null && userId !== "") {
-    await bot.sendPrivateMsg(userId, payload);
+    await bot.sendPrivateMsg(userId, [...segments]);
     return;
   }
   if (typeof event?.reply === "function") {
-    await event.reply(text);
+    await event.reply([...segments]);
     return;
   }
-  throw new Error("当前上下文不支持文本发送");
+  throw new Error("当前上下文不支持消息发送");
+}
+
+export async function sendTextMessage(
+  ctx: MiokuContext,
+  event: MessageEvent,
+  text: string,
+): Promise<void> {
+  await sendSegments(ctx, event, [ctx.segment.text(text)]);
 }
 
 export async function sendImageMessage(
-  ctx: any,
-  event: any,
+  ctx: MiokuContext,
+  event: MessageEvent,
   imagePath: string,
 ): Promise<void> {
-  const { bot, groupId, userId } = getBotAndTarget(ctx, event);
-  const sendPayload = async (source: string) => {
-    const payload: any[] = [];
-    payload.push(ctx.segment.image(normalizeFileSource(source)));
-
-    if (bot && groupId != null && groupId !== "") {
-      await bot.sendGroupMsg(groupId, payload);
-      return;
-    }
-    if (bot && userId != null && userId !== "") {
-      await bot.sendPrivateMsg(userId, payload);
-      return;
-    }
-    if (typeof event?.reply === "function") {
-      await event.reply(payload);
-      return;
-    }
-    throw new Error("当前上下文不支持图片发送");
+  const send = async (source: string): Promise<void> => {
+    await sendSegments(ctx, event, [
+      ctx.segment.image(normalizeFileSource(source)),
+    ]);
   };
 
   try {
-    await sendPayload(imagePath);
+    await send(imagePath);
   } catch {
     const buffer = await fs.readFile(imagePath);
-    const base64 = `base64://${buffer.toString("base64")}`;
-    await sendPayload(base64);
+    await send(`base64://${buffer.toString("base64")}`);
   }
 }
 
 export async function sendFileMessage(
-  ctx: any,
-  event: any,
+  ctx: MiokuContext,
+  event: MessageEvent,
   filePath: string,
   name: string,
 ): Promise<void> {
   const ext = path.extname(filePath);
   const fileName = ext ? `${name}${ext}` : name;
-  const { bot, groupId, userId } = getBotAndTarget(ctx, event);
-  const sendPayload = async (source: string) => {
-    const payload: any[] = [];
-    payload.push(ctx.segment.file(normalizeFileSource(source), { name: fileName }));
 
-    if (bot && groupId != null && groupId !== "") {
-      await bot.sendGroupMsg(groupId, payload);
-      return;
-    }
-    if (bot && userId != null && userId !== "") {
-      await bot.sendPrivateMsg(userId, payload);
-      return;
-    }
-    if (typeof event?.reply === "function") {
-      await event.reply(payload);
-      return;
-    }
-    throw new Error("当前上下文不支持文件发送");
+  const send = async (source: string): Promise<void> => {
+    await sendSegments(ctx, event, [
+      ctx.segment.file(normalizeFileSource(source), { name: fileName }),
+    ]);
   };
 
   const canReadLocalFile =
@@ -128,7 +105,7 @@ export async function sendFileMessage(
 
   let fileSendError: unknown;
   try {
-    await sendPayload(filePath);
+    await send(filePath);
     return;
   } catch (error) {
     fileSendError = error;
@@ -149,9 +126,8 @@ export async function sendFileMessage(
       : new Error(String(fileSendError || "文件发送失败"));
   }
 
-  const base64 = `base64://${buffer.toString("base64")}`;
   try {
-    await sendPayload(base64);
+    await send(`base64://${buffer.toString("base64")}`);
   } catch (base64Error) {
     const message = String(base64Error || "");
     const timeoutLike =
@@ -167,28 +143,14 @@ export async function sendFileMessage(
 }
 
 export async function sendRecordMessage(
-  ctx: any,
-  event: any,
+  ctx: MiokuContext,
+  event: MessageEvent,
   audioPath: string,
 ): Promise<void> {
-  const { bot, groupId, userId } = getBotAndTarget(ctx, event);
-  const sendPayload = async (source: string) => {
-    const payload: any[] = [];
-    payload.push(ctx.segment.record(normalizeFileSource(source)));
-
-    if (bot && groupId != null && groupId !== "") {
-      await bot.sendGroupMsg(groupId, payload);
-      return;
-    }
-    if (bot && userId != null && userId !== "") {
-      await bot.sendPrivateMsg(userId, payload);
-      return;
-    }
-    if (typeof event?.reply === "function") {
-      await event.reply(payload);
-      return;
-    }
-    throw new Error("当前上下文不支持语音发送");
+  const send = async (source: string): Promise<void> => {
+    await sendSegments(ctx, event, [
+      ctx.segment.record(normalizeFileSource(source)),
+    ]);
   };
 
   const canReadLocalFile =
@@ -196,7 +158,7 @@ export async function sendRecordMessage(
 
   let fileSendError: unknown;
   try {
-    await sendPayload(audioPath);
+    await send(audioPath);
     return;
   } catch (error) {
     fileSendError = error;
@@ -217,9 +179,8 @@ export async function sendRecordMessage(
       : new Error(String(fileSendError || "语音发送失败"));
   }
 
-  const base64 = `base64://${buffer.toString("base64")}`;
   try {
-    await sendPayload(base64);
+    await send(`base64://${buffer.toString("base64")}`);
   } catch (base64Error) {
     const message = String(base64Error || "");
     const timeoutLike =

package/runtime-core/optional-service.ts

@@ -0,0 +1,14 @@
+import type { ServiceRef } from "mioku";
+
+export async function importOptionalService<T>(
+  moduleName: string,
+  exportName: string,
+): Promise<ServiceRef<T> | undefined> {
+  try {
+    const mod = (await import(moduleName)) as Record<string, unknown>;
+    const ref = mod[exportName];
+    return ref ? (ref as ServiceRef<T>) : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/runtime-core/service.ts

@@ -2,7 +2,14 @@ import type { AIService } from "mioku";
 import type { ScreenshotService } from "mioku";
 import type { AppleMusicServiceApi } from "mioku-service-applemusic";
 import type { NeteaseServiceApi } from "mioku-service-netease";
+import type { NcmdumpServiceApi } from "mioku-service-ncmdump";
 import { MUSIC_DEFAULTS } from "../config";
+import {
+  createDumpProvider,
+  getDumpProviderCandidates,
+  resolveDumpProviderName,
+} from "../dumps/factory";
+import type { DumpProvider } from "../dumps/types";
 import {
   createMusicProvider,
   getMusicProviderCandidates,
@@ -30,6 +37,7 @@ interface MusicPluginRuntimeDeps {
   screenshotService?: ScreenshotService;
   applemusicService?: AppleMusicServiceApi;
   neteaseService?: NeteaseServiceApi;
+  ncmdumpService?: NcmdumpServiceApi;
 }
 
 export class MusicPluginRuntime {
@@ -59,6 +67,31 @@ export class MusicPluginRuntime {
         `music defaultProvider=${configured} 不可用，已回退到 ${resolved}`,
       );
     }
+    this.warnDumpProvider(nextConfig);
+  }
+
+  private warnDumpProvider(config: MusicBaseConfig): void {
+    const configured = String(config.dumpProvider || "").trim();
+    if (!configured) return;
+    if (resolveDumpProviderName(configured, this.getDumpServices())) return;
+    const candidates = getDumpProviderCandidates();
+    this.deps.logger.warn(
+      `music dumpProvider=${configured} 不可用，私聊文件解密未启用。候选列表=${candidates.join(", ")}`,
+    );
+  }
+
+  resolveDumpProvider(): DumpProvider | null {
+    const services = this.getDumpServices();
+    const configured = String(this.config.dumpProvider || "").trim();
+    const resolved = resolveDumpProviderName(configured, services);
+    if (!resolved) return null;
+    return createDumpProvider(resolved, services);
+  }
+
+  private getDumpServices() {
+    return {
+      ncmdump: this.deps.ncmdumpService,
+    };
   }
 
   setSessionMediaUserToken(event: any, token: string): void {

package/types.ts

@@ -2,11 +2,16 @@ export type MusicProviderName = "applemusic" | "netease";
 
 export const MUSIC_PROVIDER_NAMES: MusicProviderName[] = ["applemusic", "netease"];
 
+export type DumpProviderName = "ncmdump";
+
+export const DUMP_PROVIDER_NAMES: DumpProviderName[] = ["ncmdump"];
+
 export type MusicProviderQuality = "standard" | "exhigh" | "lossless" | "hires";
 
 export interface MusicBaseConfig {
   searchLimit: number;
   defaultProvider?: MusicProviderName | string;
+  dumpProvider?: DumpProviderName | string;
 }
 
 export interface MusicTrack {