mioku-plugin-music 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mioku Lab
+
+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,233 @@
+# mioku-plugin-music
+
+## 功能
+
+- 点歌搜索：`点歌 晴天`
+- 搜索结果截图列表
+- 编号听歌：`听1`
+- 关键词直听：`听晴天`
+- AI skills：搜索、发送歌曲
+
+## 已适配 Provider
+
+- `applemusic`
+
+## Provider 对接要求
+
+`music` 插件通过“服务 API + provider 适配器”接入新音乐源。下面是完整接口约束和实现模板。
+
+### 1. 服务 API（`ctx.services.<provider>`）标准
+
+服务侧应暴露 `createClient(options)`，返回一个 client。推荐实现如下：
+
+```ts
+export interface ProviderClientOptions {
+  token?: string;
+  timeoutMs?: number;
+  // 其他需要的内容
+}
+
+export interface ProviderSearchSongItem {
+  id: string;
+  name: string;
+  artistName: string;
+  albumName: string;
+  artworkUrl?: string;
+  previewUrl?: string;
+  durationInMillis?: number;
+}
+
+export interface ProviderSearchResult {
+  query: string;
+  songs: ProviderSearchSongItem[];
+}
+
+export interface ProviderSongDetail {
+  id: string;
+  name: string;
+  artistName: string;
+  albumName: string;
+  artworkUrl?: string;
+  releaseDate?: string;
+  durationInMillis?: number;
+  previewUrl?: string;
+  audioTraits?: string[];
+}
+
+export interface ProviderAlbumTrack {
+  id: string;
+  name: string;
+  artistName: string;
+  durationInMillis?: number;
+}
+
+export interface ProviderAlbumDetail {
+  id: string;
+  name: string;
+  artistName: string;
+  artworkUrl?: string;
+  releaseDate?: string;
+  tracks: ProviderAlbumTrack[];
+}
+
+export interface ProviderSongDownloadResult {
+  filePath: string; // 本地可读路径，供 record 发送
+  sourceType: "hls" | "preview";
+}
+
+export interface ProviderCoverDownloadResult {
+  filePath: string; // 本地可读路径
+}
+
+export interface ProviderClient {
+  searchSongs(options: {
+    query: string;
+    limit?: number;
+    offset?: number;
+    storefront?: string;
+    language?: string;
+  }): Promise<ProviderSearchResult>;
+
+  getSongDetail(options: {
+    songId: string;
+    storefront?: string;
+    language?: string;
+  }): Promise<ProviderSongDetail>;
+
+  getAlbumDetail(options: {
+    albumId: string;
+    storefront?: string;
+    language?: string;
+  }): Promise<ProviderAlbumDetail>;
+
+  downloadSongAac(options: {
+    songId: string;
+    outputDir?: string;
+    fileName?: string;
+    storefront?: string;
+    language?: string;
+  }): Promise<ProviderSongDownloadResult>;
+
+  downloadCover(options: {
+    artworkUrl: string;
+    outputDir?: string;
+    fileName?: string;
+    size?: string;
+  }): Promise<ProviderCoverDownloadResult>;
+}
+
+export interface ProviderServiceApi {
+  createClient(options?: ProviderClientOptions): ProviderClient;
+}
+```
+
+### 2. 插件侧 Provider 适配器标准（`MusicProvider`）
+
+适配器负责把服务返回值映射成 music 插件统一结构，需满足：
+
+```ts
+export interface MusicProvider {
+  readonly name: MusicProviderName;
+  searchSongs(query: string, limit?: number): Promise<MusicSearchResult>;
+  getSongDetail(songId: string): Promise<MusicSongDetail>;
+  getAlbumDetail(albumId: string): Promise<MusicAlbumDetail>;
+  downloadSong(songId: string): Promise<DownloadSongResult>;
+  downloadCover(coverUrl: string, fileName?: string): Promise<string>;
+}
+```
+
+实现模板：
+
+```ts
+export class XxxMusicProvider implements MusicProvider {
+  readonly name: MusicProviderName = "xxxmusic";
+  private readonly client: ProviderClient;
+
+  constructor(api: ProviderServiceApi, options?: MusicProviderClientOptions) {
+    this.client = api.createClient({
+      mediaUserToken: options?.mediaUserToken,
+      storefront: options?.storefront,
+      language: options?.language,
+    });
+  }
+
+  async searchSongs(query: string, limit = 15): Promise<MusicSearchResult> {
+    const result = await this.client.searchSongs({ query, limit });
+    return {
+      query,
+      provider: this.name,
+      tracks: result.songs.map((item) => ({
+        id: item.id,
+        provider: this.name,
+        title: item.name,
+        artist: item.artistName,
+        album: item.albumName,
+        coverUrl: item.artworkUrl,
+        durationMs: item.durationInMillis,
+        previewUrl: item.previewUrl,
+      })),
+    };
+  }
+
+  async getSongDetail(songId: string): Promise<MusicSongDetail> {
+    const detail = await this.client.getSongDetail({ songId });
+    return {
+      id: detail.id,
+      provider: this.name,
+      title: detail.name,
+      artist: detail.artistName,
+      album: detail.albumName,
+      coverUrl: detail.artworkUrl,
+      releaseDate: detail.releaseDate,
+      durationMs: detail.durationInMillis,
+      previewUrl: detail.previewUrl,
+      audioTraits: detail.audioTraits,
+    };
+  }
+
+  async getAlbumDetail(albumId: string): Promise<MusicAlbumDetail> {
+    const detail = await this.client.getAlbumDetail({ albumId });
+    return {
+      id: detail.id,
+      provider: this.name,
+      title: detail.name,
+      artist: detail.artistName,
+      coverUrl: detail.artworkUrl,
+      releaseDate: detail.releaseDate,
+      tracks: detail.tracks.map((track) => ({
+        id: track.id,
+        title: track.name,
+        artist: track.artistName,
+        durationMs: track.durationInMillis,
+      })),
+    };
+  }
+
+  async downloadSong(songId: string): Promise<DownloadSongResult> {
+    const result = await this.client.downloadSongAac({ songId });
+    return {
+      filePath: result.filePath,
+      sourceType: result.sourceType,
+    };
+  }
+
+  async downloadCover(coverUrl: string, fileName?: string): Promise<string> {
+    const result = await this.client.downloadCover({
+      artworkUrl: coverUrl,
+      fileName: fileName || "cover",
+      size: "1200x1200",
+    });
+    return result.filePath;
+  }
+}
+```
+
+### 3. 错误与返回约束
+
+- 搜索无结果时返回空数组，不要抛错。
+- 参数非法、鉴权失败、网络失败、资源不存在时抛 `Error`，由上层统一提示。
+- `downloadSong` 必须返回可读的本地音频路径；`sourceType` 只能是 `"hls"` 或 `"preview"`。
+- 统一结构里的 `provider` 字段必须始终等于当前 provider 名称，不能留空或混用。
+- 返回值中的可选字段允许缺省，但字段类型必须稳定（例如 `durationMs` 始终是 number 或 undefined）。
+
+Provider 编写完成后可在本仓库提出issue请求适配，我们也欢迎积极的PR :)

package/config.md

@@ -0,0 +1,49 @@
+---
+title: Music 插件配置
+description: 在这里调整 music 插件的配置项目
+fields:
+  - key: base.searchLimit
+    label: 默认搜索条数
+    type: number
+    description: 点歌时默认拉取的歌曲数量，建议 1-15
+    placeholder: 15
+
+  - key: base.defaultProvider
+    label: 默认音乐源
+    type: select
+    description: 需要安装对应的服务
+    options:
+      - value: applemusic
+        label: Apple Music
+
+  - key: base.applemusic.storefront
+    label: Apple Music Storefront
+    type: text
+    description: 默认地区代码，例如 cn、us、jp。
+    placeholder: cn
+
+  - key: base.applemusic.language
+    label: Apple Music 语言
+    type: text
+    description: 默认语言代码，例如 zh-CN、en-US。
+    placeholder: zh-CN
+
+  - key: base.applemusic.defaultMediaUserToken
+    label: 默认 Media User Token
+    type: secret
+    description: Apple Music 下载高质量 AAC 必需 token，无token仅能下载30s音频
+    placeholder: eyJ...
+---
+
+```mioku-fields
+keys:
+  - base.searchLimit
+  - base.defaultProvider
+```
+
+```mioku-fields
+keys:
+  - base.applemusic.storefront
+  - base.applemusic.language
+  - base.applemusic.defaultMediaUserToken
+```

package/config.ts

@@ -0,0 +1,11 @@
+import type { MusicBaseConfig } from "./types";
+
+export const MUSIC_DEFAULTS: MusicBaseConfig = {
+  searchLimit: 15,
+  defaultProvider: "applemusic",
+  applemusic: {
+    storefront: "cn",
+    language: "zh-CN",
+    defaultMediaUserToken: "",
+  },
+};

package/index.ts

@@ -0,0 +1,71 @@
+import { definePlugin } from "mioki";
+import type { AIService } from "../../src/services/ai/types";
+import type { ScreenshotService } from "../../src/services/screenshot/types";
+import type { ConfigService } from "../../src/services/config/tpyes";
+import type { AppleMusicServiceApi } from "../../src/services/applemusic/types";
+import { resetMusicRuntimeState, setMusicRuntimeState } from "./runtime";
+import { MusicPluginRuntime } from "./runtime-core/service";
+import { MUSIC_DEFAULTS } from "./config";
+import type { MusicBaseConfig } from "./types";
+
+function cloneConfig<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+export default definePlugin({
+  name: "music",
+  version: "1.0.0",
+  description: "点歌与听歌插件",
+  async setup(ctx) {
+    const configService = ctx.services?.config as ConfigService | undefined;
+    const aiService = ctx.services?.ai as AIService | undefined;
+    const screenshotService = ctx.services?.screenshot as
+      | ScreenshotService
+      | undefined;
+    const applemusicService = ctx.services?.applemusic as
+      | AppleMusicServiceApi
+      | 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;
+      }
+    } else {
+      ctx.logger.warn("config-service 未加载，music 插件将使用默认配置");
+    }
+
+    const runtime = new MusicPluginRuntime({
+      logger: ctx.logger,
+      aiService,
+      screenshotService,
+      applemusicService,
+    });
+    runtime.updateConfig(baseConfig);
+
+    setMusicRuntimeState({ runtime });
+
+    const disposers: Array<() => void> = [];
+    if (configService) {
+      disposers.push(
+        configService.onConfigChange("music", "base", (next) => {
+          baseConfig = next as MusicBaseConfig;
+          runtime.updateConfig(baseConfig);
+        }),
+      );
+    }
+
+    ctx.handle("message", async (event: any) => {
+      await runtime.handleMessage(ctx, event);
+    });
+
+    return () => {
+      for (const dispose of disposers) {
+        dispose();
+      }
+      resetMusicRuntimeState();
+    };
+  },
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "mioku-plugin-music",
+  "version": "1.1.0",
+  "description": "音乐插件：点歌、搜索音乐、听歌语音发送",
+  "main": "index.ts",
+  "keywords": [
+    "mioku"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mioku-lab/mioku-plugin-music.git"
+  },
+  "mioku": {
+    "services": [
+      "config",
+      "ai",
+      "screenshot"
+    ],
+    "help": {
+      "title": "音乐",
+      "description": "点歌并发送语音，支持搜索结果图片列表",
+      "commands": [
+        {
+          "cmd": "点歌 <歌曲名>",
+          "desc": "搜索歌曲/歌手/专辑，返回最多 15 条结果图片列表",
+          "usage": "/点歌 晴天",
+          "role": "member"
+        },
+        {
+          "cmd": "听 <编号>",
+          "desc": "发送上次搜索列表中的指定歌曲语音",
+          "usage": "听1",
+          "role": "member"
+        },
+        {
+          "cmd": "听 <关键词>",
+          "desc": "直接按关键词搜索并发送第一首歌曲语音",
+          "usage": "听晴天",
+          "role": "member"
+        }
+      ]
+    }
+  }
+}

package/providers/applemusic-provider.ts

@@ -0,0 +1,101 @@
+import type { AppleMusicServiceApi } from "../../../src/services/applemusic/types";
+import type {
+  DownloadSongResult,
+  MusicAlbumDetail,
+  MusicProvider,
+  MusicProviderClientOptions,
+  MusicProviderName,
+  MusicSearchResult,
+  MusicSongDetail,
+  MusicTrack,
+} from "../types";
+
+function mapTrack(item: any): MusicTrack {
+  return {
+    id: item.id,
+    provider: "applemusic",
+    title: item.name,
+    artist: item.artistName,
+    album: item.albumName,
+    coverUrl: item.artworkUrl,
+    durationMs: item.durationInMillis,
+    previewUrl: item.previewUrl,
+  };
+}
+
+export class AppleMusicProvider implements MusicProvider {
+  readonly name: MusicProviderName = "applemusic";
+  private readonly client: ReturnType<AppleMusicServiceApi["createClient"]>;
+
+  constructor(api: AppleMusicServiceApi, options?: MusicProviderClientOptions) {
+    this.client = api.createClient({
+      mediaUserToken: options?.mediaUserToken,
+      storefront: options?.storefront || "cn",
+      language: options?.language || "zh-CN",
+      allowPreviewFallback: false,
+    });
+  }
+
+  async searchSongs(query: string, limit: number = 15): Promise<MusicSearchResult> {
+    const result = await this.client.searchSongs({
+      query,
+      limit,
+    });
+    return {
+      query,
+      provider: "applemusic",
+      tracks: result.songs.map(mapTrack),
+    };
+  }
+
+  async getSongDetail(songId: string): Promise<MusicSongDetail> {
+    const detail = await this.client.getSongDetail({ songId });
+    return {
+      id: detail.id,
+      provider: "applemusic",
+      title: detail.name,
+      artist: detail.artistName,
+      album: detail.albumName,
+      coverUrl: detail.artworkUrl,
+      releaseDate: detail.releaseDate,
+      durationMs: detail.durationInMillis,
+      previewUrl: detail.previewUrl,
+      audioTraits: detail.audioTraits,
+    };
+  }
+
+  async getAlbumDetail(albumId: string): Promise<MusicAlbumDetail> {
+    const detail = await this.client.getAlbumDetail({ albumId });
+    return {
+      id: detail.id,
+      provider: "applemusic",
+      title: detail.name,
+      artist: detail.artistName,
+      coverUrl: detail.artworkUrl,
+      releaseDate: detail.releaseDate,
+      tracks: detail.tracks.map((track) => ({
+        id: track.id,
+        title: track.name,
+        artist: track.artistName,
+        durationMs: track.durationInMillis,
+      })),
+    };
+  }
+
+  async downloadSong(songId: string): Promise<DownloadSongResult> {
+    const result = await this.client.downloadSongAac({ songId });
+    return {
+      filePath: result.filePath,
+      sourceType: result.sourceType,
+    };
+  }
+
+  async downloadCover(coverUrl: string, fileName?: string): Promise<string> {
+    const result = await this.client.downloadCover({
+      artworkUrl: coverUrl,
+      fileName: fileName || "cover",
+      size: "1200x1200",
+    });
+    return result.filePath;
+  }
+}

package/providers/factory.ts

@@ -0,0 +1,81 @@
+import type { AppleMusicServiceApi } from "../../../src/services/applemusic/types";
+import { AppleMusicProvider } from "./applemusic-provider";
+import {
+  type MusicProvider,
+  type MusicProviderClientOptions,
+  type MusicProviderName,
+} from "../types";
+
+export interface MusicProviderFactoryOptions {
+  applemusic?: AppleMusicServiceApi;
+}
+
+interface MusicProviderRegistryItem {
+  readonly name: MusicProviderName;
+  readonly serviceName: string;
+  isAvailable(services: MusicProviderFactoryOptions): boolean;
+  create(
+    services: MusicProviderFactoryOptions,
+    clientOptions?: MusicProviderClientOptions,
+  ): MusicProvider;
+}
+
+const MUSIC_PROVIDER_REGISTRY: MusicProviderRegistryItem[] = [
+  {
+    name: "applemusic",
+    serviceName: "applemusic",
+    isAvailable: (services) => Boolean(services.applemusic),
+    create: (services, clientOptions) => {
+      if (!services.applemusic) {
+        throw new Error("applemusic 服务未加载");
+      }
+      return new AppleMusicProvider(services.applemusic, clientOptions);
+    },
+  },
+];
+
+function getProviderRegistryItem(
+  providerName: string,
+): MusicProviderRegistryItem | undefined {
+  const normalized = String(providerName || "").trim();
+  return MUSIC_PROVIDER_REGISTRY.find((item) => item.name === normalized);
+}
+
+export function resolveMusicProviderName(
+  preferredProviderName: unknown,
+  services: MusicProviderFactoryOptions,
+): MusicProviderName | null {
+  const preferred = String(preferredProviderName || "").trim();
+  if (preferred) {
+    const preferredItem = getProviderRegistryItem(preferred);
+    if (preferredItem?.isAvailable(services)) {
+      return preferredItem.name;
+    }
+  }
+
+  const fallbackItem = MUSIC_PROVIDER_REGISTRY.find((item) =>
+    item.isAvailable(services),
+  );
+  return fallbackItem?.name || null;
+}
+
+export function getMusicProviderCandidates(): MusicProviderName[] {
+  return MUSIC_PROVIDER_REGISTRY.map((item) => item.name);
+}
+
+export function createMusicProvider(
+  providerName: MusicProviderName,
+  services: MusicProviderFactoryOptions,
+  clientOptions?: MusicProviderClientOptions,
+): MusicProvider {
+  const item = getProviderRegistryItem(providerName);
+  if (!item) {
+    throw new Error(`不支持的音乐源: ${providerName}`);
+  }
+
+  if (!item.isAvailable(services)) {
+    throw new Error(`${item.serviceName} 服务未加载`);
+  }
+
+  return item.create(services, clientOptions);
+}

package/providers/provider-labels.ts

@@ -0,0 +1,10 @@
+import type { MusicProviderName } from "../types";
+
+export const MUSIC_PROVIDER_LABELS: Record<MusicProviderName, string> = {
+  applemusic: "Apple Music",
+};
+
+export function getMusicProviderLabel(provider: MusicProviderName | string): string {
+  const key = String(provider || "").trim() as MusicProviderName;
+  return MUSIC_PROVIDER_LABELS[key] || key || "Unknown";
+}

package/render/search-list.ts

@@ -0,0 +1,73 @@
+import type { MusicSearchResult } from "../types";
+import { getMusicProviderLabel } from "../providers/provider-labels";
+
+function escapeHtml(value: string): string {
+  const source = String(value || "");
+  return source
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#039;");
+}
+
+export function renderMusicSearchListHtml(search: MusicSearchResult): string {
+  const providerLabel = getMusicProviderLabel(search.provider);
+  const items = search.tracks
+    .map((track, index) => {
+      const coverUrl = track.coverUrl
+        ? escapeHtml(track.coverUrl.replace("{w}x{h}", "240x240"))
+        : "";
+      const cover = coverUrl
+        ? `<img src="${coverUrl}" alt="cover" class="h-14 w-14 rounded-2xl object-cover ring-1 ring-teal-200/70 dark:ring-teal-300/20" />`
+        : `<div class="h-14 w-14 rounded-2xl bg-teal-100/70 text-2xl text-teal-600 dark:bg-teal-400/10 dark:text-teal-300 flex items-center justify-center">♪</div>`;
+
+      return `
+        <div class="group relative overflow-hidden rounded-2xl border border-teal-200/60 bg-white/80 p-3 shadow-[0_10px_28px_rgba(6,49,57,0.12)] backdrop-blur-sm transition dark:border-teal-300/20 dark:bg-slate-900/70">
+          <div class="pointer-events-none absolute inset-0 opacity-0 transition group-hover:opacity-100 bg-gradient-to-r from-teal-300/10 via-transparent to-cyan-300/10"></div>
+          <div class="relative grid grid-cols-[40px_56px_minmax(0,1fr)] items-center gap-3">
+            <div class="h-9 w-9 rounded-full bg-teal-500/12 text-[16px] text-teal-700 dark:text-teal-200 dark:bg-teal-300/15 flex items-center justify-center font-extrabold">${index + 1}</div>
+            ${cover}
+            <div class="min-w-0">
+              <div class="truncate text-[18px] font-extrabold tracking-[0.01em] text-slate-900 dark:text-slate-100">${escapeHtml(track.title)}</div>
+              <div class="mt-1 truncate text-[15px] text-slate-600 dark:text-slate-300/90">
+                <span>${escapeHtml(track.artist)}</span>
+                <span class="mx-1.5 text-slate-400 dark:text-slate-500">·</span>
+                <span>${escapeHtml(track.album)}</span>
+              </div>
+            </div>
+          </div>
+        </div>
+      `;
+    })
+    .join("");
+
+  return `
+    <style>
+      html, body {
+        margin: 0;
+        padding: 0;
+        width: auto;
+        height: auto;
+        min-width: 0;
+        min-height: 0;
+        overflow: visible;
+      }
+      body {
+        display: inline-block;
+        background: transparent;
+      }
+    </style>
+    <div class="w-[860px] p-7 font-['Noto_Sans_SC','PingFang_SC','Hiragino_Sans_GB',sans-serif] bg-[radial-gradient(circle_at_0%_0%,rgba(53,210,200,0.22),transparent_40%),radial-gradient(circle_at_92%_14%,rgba(14,165,160,0.2),transparent_38%)] bg-teal-50 text-slate-900 dark:bg-slate-950 dark:text-slate-100">
+      <div class="mb-5 rounded-3xl border border-teal-200/70 bg-white/85 px-7 py-6 shadow-[0_18px_46px_rgba(6,49,57,0.16)] backdrop-blur-sm dark:border-teal-300/20 dark:bg-slate-900/75">
+        <div class="text-center text-[36px] leading-[1.08] font-black tracking-[0.01em]">音乐搜索结果</div>
+        <div class="mt-2 text-center text-[17px] text-slate-600 dark:text-slate-300">检索歌曲：${escapeHtml(search.query)} · 共 ${search.tracks.length} 条</div>
+      </div>
+      <div class="grid gap-3">${items}</div>
+      <div class="mt-5 flex items-center justify-between text-[16px] text-slate-600 dark:text-slate-300">
+        <div>音源：${escapeHtml(providerLabel)}</div>
+        <div>发送「听1」播放第一首歌曲</div>
+      </div>
+    </div>
+  `;
+}