@zhin.js/plugin-music 1.0.26 → 1.1.2

package/README.md

@@ -17,21 +17,23 @@
 ## 📦 安装
 
 ```bash
-pnpm add @zhin.js/plugin-music
+zhin install @zhin.js/plugin-music
 ```
 
 ## 🚀 使用
 
-### 配置
+### 挂载插件
 
-在 `zhin.config.ts` 中添加插件：
+`zhin install` 会安装依赖，并把插件实例写入 `package.json#zhin.plugins`。手工挂载时使用同一份拓扑契约：
 
-```typescript
-export default defineConfig({
-  plugins: [
-    'music'  // 添加音乐插件
-  ]
-})
+```json
+{
+  "zhin": {
+    "plugins": [
+      { "package": "@zhin.js/plugin-music", "instanceKey": "music" }
+    ]
+  }
+}
 ```
 
 ### 命令列表
@@ -200,22 +202,18 @@ interface ShareContent {
 }
 ```
 
-### 导出的服务
+### 运行时代码中使用服务
 
 ```typescript
-import { musicServices } from '@zhin.js/plugin-music'
-
-// 使用音乐搜索服务
-const qqMusic = musicServices.qq
-const results = await qqMusic.search('周杰伦', 10)
-const cover = await qqMusic.getCover('音乐ID')
-const detail = await qqMusic.getDetail('音乐ID')
-
-// 获取音频直链（需要 Meting API）
-const audioUrl = await qqMusic.getAudioUrl?.('音乐ID')
-
-// 获取歌词
-const lyric = await qqMusic.getLyric?.('音乐ID')
+import { defineCommand } from 'zhin.js/command'
+import { musicRuntimeToken } from '@zhin.js/plugin-music'
+
+export default defineCommand({
+  async execute({ use }) {
+    const qqMusic = use(musicRuntimeToken).services.qq
+    return qqMusic.search('周杰伦', 10)
+  },
+})
 ```
 
 ### 配置工具
@@ -266,10 +264,12 @@ export class MyMusicService implements MusicSearchService {
 // src/sources/index.ts
 import { MyMusicService } from './my-music.js'
 
-export const musicServices = {
-  qq: new QQMusicService(),
-  netease: new NeteaseMusicService(),
-  mymusic: new MyMusicService(), // 添加新服务
+export function createMusicServices(credentials: CredentialStore) {
+  return {
+    qq: new QQMusicService(credentials),
+    netease: new NeteaseMusicService(credentials),
+    mymusic: new MyMusicService(),
+  }
 }
 ```
 
@@ -286,6 +286,7 @@ export type MusicSource = 'qq' | 'netease' | 'mymusic'
 2. **版权问题**：仅用于搜索和分享链接，不提供下载功能
 3. **网络问题**：部分 API 可能需要稳定的网络连接
 4. **平台兼容**：ICQQ 特定功能仅在 ICQQ 适配器下可用
+5. **AI 工具平台限制**：旧版 `music-search` / `music-share` 工具曾通过 `.platform('icqq')` 限制仅 icqq 平台可用；现行 `defineAgentTool`（`@zhin.js/tool`）不支持 platform 约束，迁移后工具对所有平台可见
 
 ## 🐛 故障排除
 

package/commands/cookie/delete/[source]/index.js

@@ -0,0 +1,23 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from 'zhin.js/command';
+import { musicRuntimeToken } from "../../../../lib/runtime.js";
+import { SOURCE_DISPLAY_NAME } from "../../../../lib/config.js";
+const VALID_SOURCES = new Set(['qq', 'netease', 'kuwo', 'kugou']);
+export default defineCommand({
+    description: '删除音乐平台凭证',
+    alias: ['删除'],
+    params: { source: { type: 'string', description: '音乐源（qq/netease/kuwo/kugou）' } },
+    permit: ['role(master)'],
+    async execute({ params, args, use }) {
+        const source = String(params.source ?? '').trim();
+        const key = String(args[0] ?? '').trim();
+        if (!VALID_SOURCES.has(source)) {
+            return `不支持的音乐源：${source}`;
+        }
+        if (!key) {
+            return `格式：cookie delete ${source} <key>`;
+        }
+        await use(musicRuntimeToken).credentials.delete(source, key);
+        return `[${SOURCE_DISPLAY_NAME[source]}] 凭证 ${key} 已删除`;
+    },
+});

package/commands/cookie/delete/[source]/index.ts

@@ -0,0 +1,27 @@
+import { defineCommand } from 'zhin.js/command';
+import { musicRuntimeToken } from '../../../../src/runtime.js';
+import { SOURCE_DISPLAY_NAME } from '../../../../src/config.js';
+import type { MusicSource } from '../../../../src/types.js';
+
+const VALID_SOURCES = new Set<string>(['qq', 'netease', 'kuwo', 'kugou']);
+
+export default defineCommand({
+  description: '删除音乐平台凭证',
+  alias: ['删除'],
+  params: { source: { type: 'string', description: '音乐源（qq/netease/kuwo/kugou）' } },
+  permit: ['role(master)'],
+  async execute({ params, args, use }) {
+    const source = String(params.source ?? '').trim();
+    const key = String(args[0] ?? '').trim();
+
+    if (!VALID_SOURCES.has(source)) {
+      return `不支持的音乐源：${source}`;
+    }
+    if (!key) {
+      return `格式：cookie delete ${source} <key>`;
+    }
+
+    await use(musicRuntimeToken).credentials.delete(source as MusicSource, key);
+    return `[${SOURCE_DISPLAY_NAME[source as MusicSource]}] 凭证 ${key} 已删除`;
+  },
+});

package/commands/cookie/get/[source]/index.js

@@ -0,0 +1,29 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from 'zhin.js/command';
+import { musicRuntimeToken } from "../../../../lib/runtime.js";
+import { SOURCE_DISPLAY_NAME } from "../../../../lib/config.js";
+const VALID_SOURCES = new Set(['qq', 'netease', 'kuwo', 'kugou']);
+export default defineCommand({
+    description: '查看音乐平台凭证（脱敏）',
+    alias: ['查看'],
+    params: { source: { type: 'string', description: '音乐源（qq/netease/kuwo/kugou）' } },
+    permit: ['role(master)'],
+    async execute({ params, args, use }) {
+        const source = String(params.source ?? '').trim();
+        const key = String(args[0] ?? '').trim();
+        if (!VALID_SOURCES.has(source)) {
+            return `不支持的音乐源：${source}`;
+        }
+        if (!key) {
+            return `格式：cookie get ${source} <key>`;
+        }
+        const sourceName = SOURCE_DISPLAY_NAME[source];
+        const value = await use(musicRuntimeToken).credentials.get(source, key);
+        if (!value)
+            return `[${sourceName}] 凭证 ${key} 未设置`;
+        const masked = value.length > 10
+            ? `${value.slice(0, 4)}****${value.slice(-4)}`
+            : '****';
+        return `[${sourceName}] ${key} = ${masked}`;
+    },
+});

package/commands/cookie/get/[source]/index.ts

@@ -0,0 +1,33 @@
+import { defineCommand } from 'zhin.js/command';
+import { musicRuntimeToken } from '../../../../src/runtime.js';
+import { SOURCE_DISPLAY_NAME } from '../../../../src/config.js';
+import type { MusicSource } from '../../../../src/types.js';
+
+const VALID_SOURCES = new Set<string>(['qq', 'netease', 'kuwo', 'kugou']);
+
+export default defineCommand({
+  description: '查看音乐平台凭证（脱敏）',
+  alias: ['查看'],
+  params: { source: { type: 'string', description: '音乐源（qq/netease/kuwo/kugou）' } },
+  permit: ['role(master)'],
+  async execute({ params, args, use }) {
+    const source = String(params.source ?? '').trim();
+    const key = String(args[0] ?? '').trim();
+
+    if (!VALID_SOURCES.has(source)) {
+      return `不支持的音乐源：${source}`;
+    }
+    if (!key) {
+      return `格式：cookie get ${source} <key>`;
+    }
+
+    const sourceName = SOURCE_DISPLAY_NAME[source as MusicSource];
+    const value = await use(musicRuntimeToken).credentials.get(source as MusicSource, key);
+    if (!value) return `[${sourceName}] 凭证 ${key} 未设置`;
+
+    const masked = value.length > 10
+      ? `${value.slice(0, 4)}****${value.slice(-4)}`
+      : '****';
+    return `[${sourceName}] ${key} = ${masked}`;
+  },
+});

package/commands/cookie/set/[source]/index.js

@@ -0,0 +1,23 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from 'zhin.js/command';
+import { musicRuntimeToken } from "../../../../lib/runtime.js";
+import { SOURCE_DISPLAY_NAME } from "../../../../lib/config.js";
+const VALID_SOURCES = new Set(['qq', 'netease', 'kuwo', 'kugou']);
+export default defineCommand({
+    description: '保存音乐平台凭证',
+    alias: ['设置'],
+    params: { source: { type: 'string', description: '音乐源（qq/netease/kuwo/kugou）' } },
+    permit: ['role(master)'],
+    async execute({ params, args, use }) {
+        const source = String(params.source ?? '').trim();
+        const [key, ...valueParts] = args.map(String);
+        if (!VALID_SOURCES.has(source)) {
+            return `不支持的音乐源：${source}\n支持：${[...VALID_SOURCES].join(', ')}`;
+        }
+        if (!key || valueParts.length === 0) {
+            return `格式：cookie set ${source} <key> <value>\n示例：cookie set netease cookie MUSIC_U=xxx`;
+        }
+        await use(musicRuntimeToken).credentials.set(source, key, valueParts.join(' '));
+        return `[${SOURCE_DISPLAY_NAME[source]}] 凭证 ${key} 已保存`;
+    },
+});

package/commands/cookie/set/[source]/index.ts

@@ -0,0 +1,27 @@
+import { defineCommand } from 'zhin.js/command';
+import { musicRuntimeToken } from '../../../../src/runtime.js';
+import { SOURCE_DISPLAY_NAME } from '../../../../src/config.js';
+import type { MusicSource } from '../../../../src/types.js';
+
+const VALID_SOURCES = new Set<string>(['qq', 'netease', 'kuwo', 'kugou']);
+
+export default defineCommand({
+  description: '保存音乐平台凭证',
+  alias: ['设置'],
+  params: { source: { type: 'string', description: '音乐源（qq/netease/kuwo/kugou）' } },
+  permit: ['role(master)'],
+  async execute({ params, args, use }) {
+    const source = String(params.source ?? '').trim();
+    const [key, ...valueParts] = args.map(String);
+
+    if (!VALID_SOURCES.has(source)) {
+      return `不支持的音乐源：${source}\n支持：${[...VALID_SOURCES].join(', ')}`;
+    }
+    if (!key || valueParts.length === 0) {
+      return `格式：cookie set ${source} <key> <value>\n示例：cookie set netease cookie MUSIC_U=xxx`;
+    }
+
+    await use(musicRuntimeToken).credentials.set(source as MusicSource, key, valueParts.join(' '));
+    return `[${SOURCE_DISPLAY_NAME[source as MusicSource]}] 凭证 ${key} 已保存`;
+  },
+});

package/commands/cookie/status/index.js

@@ -0,0 +1,25 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from 'zhin.js/command';
+import { musicRuntimeToken } from "../../../lib/runtime.js";
+import { SOURCE_DISPLAY_NAME } from "../../../lib/config.js";
+export default defineCommand({
+    description: '查看各平台凭证配置状态',
+    alias: ['状态'],
+    permit: ['role(master)'],
+    async execute({ use }) {
+        const allCreds = await use(musicRuntimeToken).credentials.list();
+        const lines = ['--- 音乐凭证状态 ---'];
+        for (const source of ['qq', 'netease', 'kuwo', 'kugou']) {
+            const name = SOURCE_DISPLAY_NAME[source];
+            const creds = allCreds.filter((c) => c.source === source);
+            if (creds.length === 0) {
+                lines.push(`${name}: 未配置`);
+            }
+            else {
+                const keys = creds.map((c) => c.key).join(', ');
+                lines.push(`${name}: ${keys} (${creds.length} 项)`);
+            }
+        }
+        return lines.join('\n');
+    },
+});

package/commands/cookie/status/index.ts

@@ -0,0 +1,25 @@
+import { defineCommand } from 'zhin.js/command';
+import { musicRuntimeToken } from '../../../src/runtime.js';
+import { SOURCE_DISPLAY_NAME } from '../../../src/config.js';
+import type { MusicSource } from '../../../src/types.js';
+
+export default defineCommand({
+  description: '查看各平台凭证配置状态',
+  alias: ['状态'],
+  permit: ['role(master)'],
+  async execute({ use }) {
+    const allCreds = await use(musicRuntimeToken).credentials.list();
+    const lines: string[] = ['--- 音乐凭证状态 ---'];
+    for (const source of ['qq', 'netease', 'kuwo', 'kugou'] as MusicSource[]) {
+      const name = SOURCE_DISPLAY_NAME[source];
+      const creds = allCreds.filter((c) => c.source === source);
+      if (creds.length === 0) {
+        lines.push(`${name}: 未配置`);
+      } else {
+        const keys = creds.map((c) => c.key).join(', ');
+        lines.push(`${name}: ${keys} (${creds.length} 项)`);
+      }
+    }
+    return lines.join('\n');
+  },
+});

package/commands/login/[platform]/index.js

@@ -0,0 +1,66 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from 'zhin.js/command';
+import { loginSessionKey, } from "../../../lib/login/index.js";
+import { resolveMessageIds } from "../../../lib/session.js";
+import { SOURCE_DISPLAY_NAME } from "../../../lib/config.js";
+import { musicRuntimeToken } from "../../../lib/runtime.js";
+const QR_LOGIN_SOURCES = {
+    qq: 'qq',
+    netease: 'netease',
+};
+export default defineCommand({
+    description: '扫码登录音乐平台获取凭证（master 专用）',
+    params: {
+        platform: { type: 'string', description: '音乐平台（qq / netease / 取消）' },
+    },
+    permit: ['role(master)'],
+    async execute({ params, input, use }) {
+        const platform = String(params.platform ?? '').trim();
+        const ids = resolveMessageIds(input);
+        if (!ids)
+            return '无法识别会话信息，请在群聊或私聊中使用';
+        const key = loginSessionKey(ids.endpointId, ids.conversationId, ids.senderId);
+        const runtime = use(musicRuntimeToken);
+        if (platform === '取消' || platform === 'cancel') {
+            return runtime.logins.cancel(key) ? '已取消登录' : '没有进行中的登录会话';
+        }
+        const source = QR_LOGIN_SOURCES[platform];
+        if (!source) {
+            return `不支持的平台：${platform || '(空)'}\n支持：qq, netease`;
+        }
+        const existing = runtime.logins.get(key);
+        if (existing) {
+            return `正在进行 ${SOURCE_DISPLAY_NAME[existing.source]} 登录，请先完成或发送"音乐登录 取消"`;
+        }
+        const sourceName = SOURCE_DISPLAY_NAME[source];
+        let qrResult;
+        try {
+            qrResult = await runtime.logins.start(source, key);
+        }
+        catch (err) {
+            return `[${sourceName}] 获取二维码失败：${err instanceof Error ? err.message : String(err)}`;
+        }
+        const replyFn = input?.$reply;
+        if (!replyFn)
+            return '无法发送消息';
+        await replyFn([
+            `[${sourceName}] 请使用 ${sourceName} App 扫描二维码登录：\n`,
+            qrResult.imageSegment,
+            `\n二维码有效期 2 分钟，发送"音乐登录 取消"可中止`,
+        ]);
+        const finalResult = await runtime.logins.poll(key, async (result) => {
+            if (result.status === 'scanned') {
+                await replyFn(`[${sourceName}] ${result.message}`);
+            }
+            else if (result.status === 'confirmed') {
+                await replyFn(`[${sourceName}] 登录成功！cookie 已自动保存，现在可以搜索和播放高品质音乐了`);
+            }
+            else if (result.status === 'expired' || result.status === 'error') {
+                await replyFn(`[${sourceName}] ${result.message}`);
+            }
+        });
+        if (finalResult.status === 'confirmed')
+            return undefined;
+        return `[${sourceName}] ${finalResult.message}`;
+    },
+});

package/commands/login/[platform]/index.ts

@@ -0,0 +1,74 @@
+import { defineCommand } from 'zhin.js/command';
+import type { Message } from '@zhin.js/core/runtime';
+import {
+  loginSessionKey,
+  type QrLoginSource,
+} from '../../../src/login/index.js';
+import { resolveMessageIds } from '../../../src/session.js';
+import { SOURCE_DISPLAY_NAME } from '../../../src/config.js';
+import { musicRuntimeToken } from '../../../src/runtime.js';
+
+const QR_LOGIN_SOURCES: Record<string, QrLoginSource> = {
+  qq: 'qq',
+  netease: 'netease',
+};
+
+export default defineCommand<unknown, string, Message>({
+  description: '扫码登录音乐平台获取凭证（master 专用）',
+  params: {
+    platform: { type: 'string', description: '音乐平台（qq / netease / 取消）' },
+  },
+  permit: ['role(master)'],
+  async execute({ params, input, use }) {
+    const platform = String(params.platform ?? '').trim();
+
+    const ids = resolveMessageIds(input!);
+    if (!ids) return '无法识别会话信息，请在群聊或私聊中使用';
+    const key = loginSessionKey(ids.endpointId, ids.conversationId, ids.senderId);
+    const runtime = use(musicRuntimeToken);
+
+    if (platform === '取消' || platform === 'cancel') {
+      return runtime.logins.cancel(key) ? '已取消登录' : '没有进行中的登录会话';
+    }
+
+    const source = QR_LOGIN_SOURCES[platform];
+    if (!source) {
+      return `不支持的平台：${platform || '(空)'}\n支持：qq, netease`;
+    }
+
+    const existing = runtime.logins.get(key);
+    if (existing) {
+      return `正在进行 ${SOURCE_DISPLAY_NAME[existing.source]} 登录，请先完成或发送"音乐登录 取消"`;
+    }
+
+    const sourceName = SOURCE_DISPLAY_NAME[source];
+    let qrResult;
+    try {
+      qrResult = await runtime.logins.start(source, key);
+    } catch (err) {
+      return `[${sourceName}] 获取二维码失败：${err instanceof Error ? err.message : String(err)}`;
+    }
+
+    const replyFn = input?.$reply;
+    if (!replyFn) return '无法发送消息';
+
+    await replyFn([
+      `[${sourceName}] 请使用 ${sourceName} App 扫描二维码登录：\n`,
+      qrResult.imageSegment,
+      `\n二维码有效期 2 分钟，发送"音乐登录 取消"可中止`,
+    ]);
+
+    const finalResult = await runtime.logins.poll(key, async (result) => {
+      if (result.status === 'scanned') {
+        await replyFn(`[${sourceName}] ${result.message}`);
+      } else if (result.status === 'confirmed') {
+        await replyFn(`[${sourceName}] 登录成功！cookie 已自动保存，现在可以搜索和播放高品质音乐了`);
+      } else if (result.status === 'expired' || result.status === 'error') {
+        await replyFn(`[${sourceName}] ${result.message}`);
+      }
+    });
+
+    if (finalResult.status === 'confirmed') return undefined as unknown as string;
+    return `[${sourceName}] ${finalResult.message}`;
+  },
+});

package/commands//347/202/271/346/255/214/[keyword]/index.js

@@ -0,0 +1,63 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from 'zhin.js/command';
+import { searchMusic, formatSearchResults } from "../../../lib/music-lib.js";
+import { resolveSourceAlias, SOURCE_DISPLAY_NAME } from "../../../lib/config.js";
+import { sessionKey, resolveMessageIds } from "../../../lib/session.js";
+import { musicRuntimeToken } from "../../../lib/runtime.js";
+export default defineCommand({
+    description: '搜索音乐并点歌（支持QQ/网易云/酷我/酷狗）',
+    params: { keyword: { type: 'string' } },
+    shortcut: {
+        'QQ点歌': { keyword: '' },
+        'qq点歌': { keyword: '' },
+        '网易云点歌': { keyword: '' },
+        '酷我点歌': { keyword: '' },
+        '酷狗点歌': { keyword: '' },
+    },
+    async execute({ params, config, input, use }) {
+        const rawKeyword = String(params.keyword ?? '').trim();
+        if (!rawKeyword) {
+            const sources = Object.values(SOURCE_DISPLAY_NAME).join('/');
+            return `请输入歌曲名称，如：点歌 稻香\n支持音乐源：${sources}`;
+        }
+        let source = config?.defaultSource ?? 'qq';
+        let keyword = rawKeyword;
+        const triggerText = input?.content?.trim() ?? '';
+        for (const [prefix, s] of Object.entries({
+            'QQ点歌': 'qq',
+            'qq点歌': 'qq',
+            '网易云点歌': 'netease',
+            '酷我点歌': 'kuwo',
+            '酷狗点歌': 'kugou',
+        })) {
+            if (triggerText.startsWith(prefix)) {
+                source = s;
+                keyword = triggerText.slice(prefix.length).trim() || rawKeyword;
+                break;
+            }
+        }
+        const sourceFromKeyword = resolveSourceAlias(keyword.split(/\s+/)[0] ?? '');
+        if (sourceFromKeyword) {
+            source = sourceFromKeyword;
+            keyword = keyword.slice(keyword.indexOf(' ') + 1).trim();
+            if (!keyword)
+                return '请输入歌曲名称';
+        }
+        const pageSize = config?.pageSize ?? 5;
+        const result = await searchMusic(use(musicRuntimeToken), keyword, source, pageSize);
+        if (result.total === 0) {
+            return `[${SOURCE_DISPLAY_NAME[source]}] 未找到"${keyword}"相关歌曲`;
+        }
+        const ids = input ? resolveMessageIds(input) : null;
+        if (ids) {
+            const key = sessionKey(ids.endpointId, ids.conversationId, ids.senderId);
+            use(musicRuntimeToken).sessions.set(key, {
+                results: result.results,
+                source: result.source,
+                keyword,
+                timestamp: Date.now(),
+            });
+        }
+        return formatSearchResults(result.results, result.source);
+    },
+});

package/commands//347/202/271/346/255/214/[keyword]/index.ts

@@ -0,0 +1,75 @@
+import { defineCommand } from 'zhin.js/command';
+import type { Message } from '@zhin.js/core/runtime';
+import { searchMusic, formatSearchResults } from '../../../src/music-lib.js';
+import { resolveSourceAlias, SOURCE_DISPLAY_NAME } from '../../../src/config.js';
+import { sessionKey, resolveMessageIds } from '../../../src/session.js';
+import type { MusicSource } from '../../../src/types.js';
+import { musicRuntimeToken } from '../../../src/runtime.js';
+
+interface MusicConfig {
+  defaultSource?: MusicSource;
+  pageSize?: number;
+}
+
+export default defineCommand<MusicConfig, string, Message>({
+  description: '搜索音乐并点歌（支持QQ/网易云/酷我/酷狗）',
+  params: { keyword: { type: 'string' } },
+  shortcut: {
+    'QQ点歌': { keyword: '' },
+    'qq点歌': { keyword: '' },
+    '网易云点歌': { keyword: '' },
+    '酷我点歌': { keyword: '' },
+    '酷狗点歌': { keyword: '' },
+  },
+  async execute({ params, config, input, use }) {
+    const rawKeyword = String(params.keyword ?? '').trim();
+    if (!rawKeyword) {
+      const sources = Object.values(SOURCE_DISPLAY_NAME).join('/');
+      return `请输入歌曲名称，如：点歌 稻香\n支持音乐源：${sources}`;
+    }
+
+    let source: MusicSource = (config as MusicConfig | undefined)?.defaultSource ?? 'qq';
+    let keyword = rawKeyword;
+
+    const triggerText = input?.content?.trim() ?? '';
+    for (const [prefix, s] of Object.entries({
+      'QQ点歌': 'qq',
+      'qq点歌': 'qq',
+      '网易云点歌': 'netease',
+      '酷我点歌': 'kuwo',
+      '酷狗点歌': 'kugou',
+    } as Record<string, MusicSource>)) {
+      if (triggerText.startsWith(prefix)) {
+        source = s;
+        keyword = triggerText.slice(prefix.length).trim() || rawKeyword;
+        break;
+      }
+    }
+
+    const sourceFromKeyword = resolveSourceAlias(keyword.split(/\s+/)[0] ?? '');
+    if (sourceFromKeyword) {
+      source = sourceFromKeyword;
+      keyword = keyword.slice(keyword.indexOf(' ') + 1).trim();
+      if (!keyword) return '请输入歌曲名称';
+    }
+
+    const pageSize = (config as MusicConfig | undefined)?.pageSize ?? 5;
+    const result = await searchMusic(use(musicRuntimeToken), keyword, source, pageSize);
+    if (result.total === 0) {
+      return `[${SOURCE_DISPLAY_NAME[source]}] 未找到"${keyword}"相关歌曲`;
+    }
+
+    const ids = input ? resolveMessageIds(input) : null;
+    if (ids) {
+      const key = sessionKey(ids.endpointId, ids.conversationId, ids.senderId);
+      use(musicRuntimeToken).sessions.set(key, {
+        results: result.results,
+        source: result.source,
+        keyword,
+        timestamp: Date.now(),
+      });
+    }
+
+    return formatSearchResults(result.results, result.source);
+  },
+});

package/components/share-music/index.js

@@ -0,0 +1,24 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineComponent } from 'zhin.js/component';
+import { sourceConfigMap } from "../../lib/config.js";
+import { musicRuntimeToken } from "../../lib/runtime.js";
+export default defineComponent({
+    async render({ platform, musicId }, context) {
+        const service = context.use(musicRuntimeToken).services[platform];
+        if (!service)
+            return 'unsupported music source';
+        const detail = await service.getDetail(musicId);
+        return {
+            type: 'share',
+            data: {
+                title: detail.title,
+                url: detail.url,
+                image: detail.image,
+                audio: detail.audio,
+                duration: detail.duration,
+                artist: detail.artist,
+                config: sourceConfigMap[platform],
+            },
+        };
+    },
+});

package/components/share-music/index.ts

@@ -0,0 +1,29 @@
+import { defineComponent } from 'zhin.js/component';
+import { sourceConfigMap } from '../../src/config.js';
+import type { MusicSource } from '../../src/types.js';
+import { musicRuntimeToken } from '../../src/runtime.js';
+
+interface ShareMusicProps {
+  readonly platform: MusicSource;
+  readonly musicId: string;
+}
+
+export default defineComponent<ShareMusicProps>({
+  async render({ platform, musicId }, context) {
+    const service = context.use(musicRuntimeToken).services[platform];
+    if (!service) return 'unsupported music source';
+    const detail = await service.getDetail(musicId);
+    return {
+      type: 'share',
+      data: {
+        title: detail.title,
+        url: detail.url,
+        image: detail.image,
+        audio: detail.audio,
+        duration: detail.duration,
+        artist: detail.artist,
+        config: sourceConfigMap[platform],
+      },
+    };
+  },
+});

package/lib/config.d.ts

@@ -1,9 +1,9 @@
 import type { MusicSourceConfig, MusicSource } from './types.js';
-/** 音乐源配置映射 */
 export declare const sourceConfigMap: Record<MusicSource, MusicSourceConfig>;
-/** 格式化时长 */
+export declare const SOURCE_ALIASES: Record<string, MusicSource>;
+export declare const SOURCE_DISPLAY_NAME: Record<MusicSource, string>;
+export declare function resolveSourceAlias(input: string): MusicSource | undefined;
 export declare function formatDuration(seconds?: number): string;
-/** 格式化音乐信息 */
 export declare function formatMusicInfo(music: {
     title: string;
     artist?: string;