企业官网建设流程全解析

1. 项目概述：这不是一个“工具包”，而是一套音源接口的生存指南

MusicFree音源接口汇总——看到这个标题，很多人第一反应是“又一个爬虫合集”“又一个音乐插件资源站”。但如果你真这么想，大概率会在三天内被报错堆满控制台、被跨域拦截卡死、被接口变更打蒙，最后删掉整个项目文件夹。我从2021年第一次接触MusicFree生态起，就不是在“用接口”，而是在和接口背后的协议、结构、生命周期打交道。它本质上不是一堆URL的罗列，而是一套动态演化的音源协议体系：每个接口背后都有明确的请求契约（method、headers、query、body）、响应契约（JSON schema、字段语义、错误码含义）、数据契约（歌曲ID如何生成、歌词时间轴格式、专辑图尺寸规范），甚至还有隐含的反爬契约（User-Agent指纹、Referer校验、Token刷新周期、请求频率窗口）。所谓“汇总”，不是把几十个js文件扔进一个文件夹，而是建立一套可验证、可回滚、可监控、可灰度发布的接口治理机制。核心关键词MusicFree、音源接口、json、js、插件，每一个都不是孤立存在：MusicFree是生态入口，音源接口是数据通道，json是契约载体，js是执行语言，插件是交付形态。适合三类人：一是LXMusic、NeteaseCloudMusicPlugin等客户端插件开发者，需要稳定接入多源；二是前端音乐聚合页作者，要绕过CORS直接调用；三是逆向学习者，想搞懂真实世界中API是如何被设计、被保护、被绕过的。它解决的从来不是“能不能播”，而是“怎么播得稳、播得准、播得可持续”。

2. 接口设计逻辑与演化规律：为什么不能只抄URL？

2.1 音源接口的本质：三层契约模型

MusicFree生态里的接口，表面看是几个GET请求返回JSON，实则由三层契约共同约束：

• 传输层契约：规定HTTP方法、路径、必要Header（如Origin: https://musicfree.io、Referer: https://musicfree.io/）、Query参数（如id=123456&platform=netease）。我见过太多人直接复制curl命令里的URL，却漏掉Referer，结果返回403——这不是服务器拒绝你，而是拒绝“非浏览器上下文”的请求。比如网易云接口常要求User-Agent必须包含Chrome/且版本号在90以上，否则返回空数组。

• 数据层契约：定义JSON响应结构。典型如{ "code": 200, "data": { "url": "https://xxx.mp3", "quality": "flac", "expires": 1718234567 } }。这里code不是HTTP状态码，而是业务码；expires是Unix时间戳，不是字符串；quality值域固定为["128k", "320k", "flac", "dolby"]。曾有开发者把expires当字符串解析，导致缓存失效逻辑全乱。更隐蔽的是字段缺失：QQ音乐接口在无版权时会直接 omiturl字段，而非设为null，JS里data.url === null判断永远为false，必须用'url' in data检测。

• 行为层契约：隐含在文档外的规则。例如：

  • 某豆瓣FM接口要求每分钟最多3次请求，超频后返回{"code":429,"msg":"rate limit"}，但该错误码在官方文档里根本没提；
  • 某B站音频接口返回的URL带有时效签名，30秒后失效，且签名算法依赖客户端时间戳，若本地时间偏差>5秒，URL直接404；
  • 某小众平台接口需先POST/login获取token，再在后续请求Header里带Authorization: Bearer xxx，但token有效期仅15分钟，且刷新接口本身也需token——形成闭环依赖。

这三层契约缺一不可。只关注URL，等于只记住了门牌号，却不知道开门密码、屋内布局、以及房东哪天会换锁。

2.2 接口演化的三大驱动力与应对策略

MusicFree接口不是静态文档，而是活体系统，其变更由三个引擎驱动：

• 版权压力驱动：最频繁的变更源。某日突然发现网易云接口返回{"code":400,"msg":"版权受限"}，查日志发现是平台方新增了X-Copyright-CheckHeader校验。对策不是硬编码绕过，而是建立版权状态映射表：将platform+songId哈希为key，存储last_success_time和last_fail_reason，当连续3次失败且fail_reason含“版权”字样，自动降级到备用源（如SoundCloud）或触发人工审核流程。

• 反爬升级驱动：比版权变更更隐蔽。去年某接口开始要求Cookie: session_id=xxx; csrf_token=yyy，而csrf_token需从/api/csrf接口预取。但该接口本身又要求X-Requested-With: XMLHttpRequest。这种链式依赖必须拆解为原子化请求单元：每个接口封装成独立函数，内部自动处理前置依赖（如自动fetch token、自动注入cookie），对外暴露纯净的getSongUrl(songId)接口。我用Proxy对象实现透明代理，让调用方完全感知不到底层复杂性。

• 架构迁移驱动：影响最大。2023年某主流源从RESTful迁移到GraphQL，所有URL失效，响应结构从扁平JSON变为嵌套查询体。此时“汇总”价值凸显：我们提前在sources/目录下按v1/、v2/分版本存放，index.js通过source.version字段路由到对应实现。新旧版本并存期长达4个月，期间v1接口逐步返回{"deprecated":true}提示，v2接口要求Content-Type: application/json且body必须是GraphQL query字符串。这种迁移不是“改URL”，而是整个通信范式的切换。

不理解演化逻辑，所谓“长期更新”就是一句空话。真正的长期，靠的是把接口当作有生命周期的实体来管理，而非字符串常量。

2.3 “插件”形态的技术本质：运行时环境决定一切

热搜词里高频出现“插件”，但MusicFree插件绝非传统意义上的浏览器扩展。它的技术本质是沙箱化JS执行环境，具体分三类：

• LXMusic类桌面客户端插件：基于Electron，拥有Node.js完整API（fs、child_process、net）。可直接读取本地JSON配置、调用ffmpeg转码、监听系统托盘事件。优势是能力全面，劣势是打包体积大、更新需用户手动下载。我开发的lyric-sync插件就利用child_process.spawn('ffprobe')实时分析音频时长，再动态调整歌词滚动速度。

• 浏览器书签脚本（Bookmarklet）：纯前端，受限于CSP和跨域。典型如javascript:(function(){fetch('https://api.xxx.com/song?id=123').then(r=>r.json()).then(d=>console.log(d))})()。优点是零安装，缺点是无法处理需要Cookie或Referer的接口。解决方案是注入<iframe>加载目标域页面，通过postMessage跨域通信——把iframe当“代理浏览器”，自己页面只负责UI。

• VS Code插件（如music-free-extension）：运行在Extension Host进程，可调用VS Code API（workspace、window、commands），但无DOM访问权。适合做“音乐元数据补全”：右键歌曲文件→“Fetch Lyrics”，插件调用音源接口获取歌词，再用vscode.workspace.applyEdit()写入.lrc文件。这里的关键是权限声明：package.json中必须声明"permissions": ["webviewPanel"]才能加载外部网页，声明"contentSecurityPolicy"放宽脚本限制。

混淆这三类环境，会导致代码在A环境能跑，在B环境直接报ReferenceError: require is not defined。所谓“musicfree插件”，首先要问清：它跑在哪？这是所有技术选型的起点。

3. JSON结构解析与JS实操要点：从字符串到可用数据的七道关卡

3.1 JSON不是万能胶：解析前的五重校验

拿到一个JSON响应，别急着JSON.parse()。真实世界中，约37%的“JSON接口”会返回非标准内容。我建立了一套强制校验流水线：

1. HTTP状态码初筛：response.status !== 200直接reject，不进解析流程。曾遇到某接口在维护时返回200 OK但body是HTML维护页，所以必须结合内容类型二次判断。

2. Content-Type精判：检查response.headers.get('content-type')是否包含application/json。某CDN节点故障时返回text/html;charset=utf-8，但状态码仍是200。用正则/^application\/json/i.test(contentType)比简单includes('json')更可靠。

3. BOM头清除：UTF-8 BOM（\ufeff）会导致JSON.parse()报错Unexpected token。实测方案：text = text.replace(/^\uFEFF/, '')，放在response.text()之后、JSON.parse()之前。

4. 空白字符归一化：某些接口返回{ "code" : 200 , "data" : { ... } }，空格不规范但合法；更糟的是返回{"code":200,"data":{...}}\n末尾带换行。JSON.parse(text.trim())是底线操作。

5. JSONP兜底：极少数接口用JSONP（如callback({...})）。需用正则提取/^\w+\(([\s\S]*)\)$/捕获组，再JSON.parse(captured)。我封装成safeJsonParse(text, {jsonpCallback: 'callback'})，内部自动识别。

这五步耗时不足1ms，却避免了80%的解析崩溃。没有校验的JSON.parse()，就像没系安全带开车。

3.2 JS判断字符串是否包含：不只是indexOf那么简单

热搜词里“js判断字符串是否包含”看似基础，但在音源接口场景下充满陷阱：

• 大小写敏感陷阱：某接口返回{"platform":"NetEase"}，而你的判断逻辑是res.platform.includes('netease')，永远为false。正确做法是res.platform.toLowerCase().includes('netease')，或用正则/netease/i.test(res.platform)。

• 子串歧义：判断url是否含qq.com，但实际返回https://y.qq.com/xxx（含）和https://qqmusic.com/xxx（不含）。includes('qq.com')会误判后者。应使用new URL(res.url).hostname.endsWith('qq.com')，精确匹配域名。

• JSON路径嵌套：需判断data.album.artists[0].name是否含“周杰伦”。若artists为空数组，[0]返回undefined，undefined.name报错。安全写法：

  const artistName = res.data?.album?.artists?.[0]?.name || ''; if (artistName.includes('周杰伦')) { /* ... */ }

  可选链（?.）和空值合并（??）是ES2020标配，不支持的老环境需用lodash.get(res, 'data.album.artists[0].name', '')。

• 正则性能陷阱：对10MB歌词JSON做/副歌/g全局匹配，V8引擎会卡顿。改用indexOf或includes，除非真需复杂模式。我测试过：100KB文本中查找固定字符串，includes()比/str/.test()快3.2倍。

• Unicode边界：中文名“王菲”可能被编码为"王\uFE0F\u200D\u2640\uFE0F菲"（带变体选择符）。'王菲'.includes('王菲')为true，但'王\uFE0F\u200D\u2640\uFE0F菲'.includes('王菲')为false。解决方案：标准化字符串str.normalize('NFC')后再比较。

这些细节，决定了你的插件是“偶尔崩”，还是“永不崩”。

3.3 JSON数组的健壮遍历：从for循环到管道流

音源接口常返回{ "songs": [...] }，遍历songs数组是高频操作。但新手常犯三类错误：

• 忽略空数组：res.songs.forEach(...)在res.songs为undefined时直接报错。正确姿势：

  const songs = Array.isArray(res.songs) ? res.songs : []; songs.forEach(song => { /* ... */ });

• 修改原数组副作用：songs.map(...)创建新数组没问题，但songs.sort()会污染原始响应。音源数据需保持原始顺序（如按热度排序），排序应在UI层做，而非数据层。我用Object.freeze(res)冻结响应对象，强制开发者复制后再操作。

• 异步遍历阻塞：需为每个歌曲调用getLyrics(song.id)，若用for await (const lyric of songs) {...}会串行等待，10首歌耗时10秒。改用Promise.allSettled(songs.map(getLyrics))并发执行，总耗时≈单个请求最长时间。

更进一步，我构建了JSON数组管道流：

// 定义可复用的管道操作符 const filterValid = arr => arr.filter(song => song.url && song.duration > 0); const sortByQuality = arr => [...arr].sort((a,b) => (b.quality || '').localeCompare(a.quality || '')); const dedupeById = arr => [...new Map(arr.map(song => [song.id, song])).values()]; // 链式调用 const processedSongs = pipe( filterValid, sortByQuality, dedupeById )(res.songs || []);

pipe函数来自lodash/fp，让数据转换像乐高一样可组合。这种设计让“汇总”不再是静态列表，而是可编程的数据流。

3.4 JSON Schema验证：给接口加一道保险

“failed to deserialize the json body into the target type: input: missing fie”——这个错误提示暴露了核心问题：没有Schema验证。我为每个音源接口定义JSON Schema：

{ "type": "object", "properties": { "code": { "type": "integer", "enum": [200, 400, 404, 429] }, "data": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "quality": { "type": "string", "enum": ["128k", "320k", "flac"] }, "expires": { "type": "integer", "minimum": 1700000000 } }, "required": ["url"] } }, "required": ["code", "data"] }

用ajv库验证：

const ajv = new Ajv(); const validate = ajv.compile(schema); if (!validate(response)) { console.error('JSON Schema validation failed:', validate.errors); // 触发降级逻辑或上报监控 }

Schema验证带来三重收益：

1. 开发期报错：接口变更时，验证失败立刻定位字段缺失；
2. 运行时防护：阻止非法数据进入业务逻辑，避免Cannot read property 'url' of undefined；
3. 文档即代码：Schema本身就是最新、最准的接口文档，比README更可靠。

没有Schema的JSON接口，就像没有说明书的精密仪器。

4. 实操全流程：从零搭建可维护的音源接口仓库

4.1 项目结构设计：为什么用monorepo而非单仓库？

“MusicFree音源接口汇总”不是单个JS文件，而是一个可演化的monorepo。结构如下：

musicfree-sources/ ├── packages/ │ ├── core/ # 公共工具：request封装、schema验证、日志 │ ├── sources/ # 各音源实现：netease/, qq/, bili/, douban/ │ └── plugins/ # 插件适配层：lxmusic/, vscode/, bookmarklet/ ├── scripts/ │ ├── update-sources.js # 自动抓取最新接口定义 │ └── test-all.js # 并发测试所有接口 ├── docs/ │ └── interface-spec.md # 接口规范文档（自动生成） └── package.json

选择monorepo而非单仓库，源于三个现实痛点：

• 版本碎片化：网易云接口v2.1修复了歌词时间轴bug，但QQ音乐v1.8仍需兼容旧格式。单仓库只能统一版本，monorepo允许packages/sources/netease发布2.1.0，packages/sources/qq发布1.8.3，互不影响。

• 依赖隔离：core包用TypeScript，plugins/bookmarklet必须输出ES5无依赖JS。单仓库需复杂babel配置，monorepo中每个package独立tsconfig.json和rollup.config.js，core编译为ES2018，bookmarklet编译为ES5+IIFE。

• 测试精准性：test-all.js可指定只测试netease包：node scripts/test-all.js --source netease，避免每次修改都跑全量测试。实测将平均测试时间从47秒降至6.3秒。

关键决策点：sources/目录下每个音源是一个独立package，而非子文件夹。这确保了npm publish packages/sources/netease可单独发布，供其他项目直接npm install musicfree-netease引用。

4.2 接口实现模板：每个音源的五个必写文件

以packages/sources/netease/为例，必须包含：

• index.ts：主入口，导出getSongUrl(id: string): Promise<string>等核心函数。

  import { request } from '@musicfree/core'; import { validate } from './schema'; export async function getSongUrl(songId: string): Promise<string> { const res = await request.get(`https://api.netease.com/song?id=${songId}`); validate(res); // Schema验证 return res.data.url; }

• schema.ts：JSON Schema定义，如前文所示。

• types.ts：TypeScript接口，与Schema强一致：

  export interface NeteaseResponse { code: 200 | 400 | 404; data: { url: string; quality: '128k' | '320k' | 'flac'; expires: number; }; }

• test.spec.ts：基于真实响应Mock的单元测试：

  it('should return valid url for existing song', async () => { mockAxios.onGet(/song\?id=/).reply(200, { code: 200, data: { url: 'https://xxx.mp3', quality: 'flac', expires: Date.now() + 300 } }); const url = await getSongUrl('123'); expect(url).toBe('https://xxx.mp3'); });

• CHANGELOG.md：记录每次变更：

  ## [2.1.0] - 2024-05-20 ### Changed - 修复歌词时间轴格式：从`[mm:ss.xx]`改为`[mm:ss.xx]text`（#45） ### Fixed - 解决高并发下token失效问题（#42）

这五个文件构成最小可行单元。少一个，就失去可维护性。types.ts和schema.ts双保险，确保TS类型与JSON结构100%同步。

4.3 自动化更新机制：如何让“长期更新”不变成口号？

“长期更新”的核心是自动化。我用scripts/update-sources.js实现：

1. 源发现：爬取https://github.com/musicfree-org/awesome-musicfree的README，提取所有[NetEase](...)链接；
2. 接口探测：对每个链接发起HEAD请求，检查Content-Type: application/json和X-Source-VersionHeader；
3. Schema推断：对成功响应，用json-schema-infer库生成初始Schema；
4. 差异对比：将新Schema与本地schema.tsdiff，仅当字段增减或类型变更时触发更新；
5. PR自动提交：生成GitHub PR，标题为[auto] Update Netease schema: add 'copyright' field，描述含diff详情。

关键技巧：

• 人工审核开关：update-sources.js默认只生成draft PR，需管理员/approve后才合并，避免机器误判；
• 变更分级：Schema变更分三级——patch（字段默认值变更）、minor（新增可选字段）、major（必填字段删除或类型变更），自动更新只处理patch和minor，major需人工介入；
• 回滚保障：每次更新前，自动备份旧版到backup/v2.0.0/，git tag v2.0.0，确保可一键回退。

这套机制让每周更新从2小时人工操作，压缩到5分钟确认。真正的“长期”，靠的是把人力从重复劳动中解放出来。

4.4 插件适配层：让同一接口服务不同宿主

packages/plugins/是桥梁，将sources/的通用能力，转化为各平台所需形态：

• LXMusic插件（plugins/lxmusic/index.js）：

  // LXMusic要求导出特定对象 module.exports = { name: 'NetEase MusicFree', version: '2.1.0', api: { getSongUrl: (songId) => { // 调用sources/netease的getSongUrl return require('@musicfree/sources/netease').getSongUrl(songId); } } };

  关键是require路径映射：package.json中"exports"字段配置"./plugins/lxmusic": "./packages/plugins/lxmusic/index.js"，确保LXMusic加载时路径正确。

• VS Code插件（plugins/vscode/extension.ts）：

  export function activate(context: vscode.ExtensionContext) { let disposable = vscode.commands.registerCommand('musicfree.fetchLyrics', async () => { const songId = await vscode.window.showInputBox({ prompt: 'Enter song ID' }); if (songId) { const lyrics = await getLyrics(songId); // 来自sources await vscode.window.showInformationMessage(`Lyrics: ${lyrics.substring(0,50)}...`); } }); }

  这里getLyrics函数从@musicfree/sources/netease导入，但VS Code插件本身不直接依赖axios，所有网络请求走VS Code的vscode.env.openExternal()或Webview，规避CSP限制。

• Bookmarklet生成器（plugins/bookmarklet/build.js）：

  // 将sources/netease编译为单文件IIFE const bundle = await rollup({ input: 'packages/sources/netease/index.js', plugins: [typescript(), commonjs()], output: { format: 'iife', name: 'MusicFree' } }); const code = bundle.output[0].code; const bookmarklet = `javascript:(function(){${code};MusicFree.getSongUrl('123').then(console.log)})()`; fs.writeFileSync('dist/netease-bookmarklet.js', bookmarklet);

  输出的netease-bookmarklet.js可直接拖入浏览器书签栏，点击即执行。

适配层的价值在于：sources/专注数据，plugins/专注交付。当网易云接口变更时，只需改sources/netease/，所有插件自动受益，无需逐个修改。

5. 常见问题与实战排错：那些文档里不会写的坑

5.1 CORS跨域问题：不是加个代理就能解决

“跨域”是音源接口第一大拦路虎，但解决方案远不止proxy：

• 代理服务器局限：Webpack DevServer的proxy只在开发环境生效，生产环境无效。LXMusic等客户端根本不走webpack proxy。

• 真正的跨域根源：浏览器同源策略禁止https://my-app.com脚本读取https://api.netease.com响应，但不禁止发起请求。很多接口返回Access-Control-Allow-Origin: *，却漏了Access-Control-Allow-Headers: X-Requested-With，导致预检请求（OPTIONS）失败。解决方案：在request封装中自动添加X-Requested-With: XMLHttpRequest到Headers，并确保服务端响应包含该header。

• 终极解法：Service Worker劫持：在支持SW的环境（Chrome/Firefox），注册SW拦截所有fetch请求：

  self.addEventListener('fetch', event => { if (event.request.url.includes('api.netease.com')) { event.respondWith( fetch(event.request.clone(), { mode: 'cors', // 强制cors模式 headers: { 'Origin': 'https://my-app.com' } }) ); } });

  SW在浏览器进程运行，不受同源策略限制，且可缓存响应，比代理更底层、更稳定。

• 降级方案：JSONP+iframe：当SW不可用时，动态创建<iframe src="https://api.netease.com/song?id=123&callback=cb">，在父页面定义window.cb = data => { /* 处理 */ }。虽有安全风险，但对老旧环境是唯一选择。

记住：跨域不是“能不能发请求”，而是“能不能读响应”。所有方案都围绕后者展开。

5.2 Token失效与刷新：状态管理的生死线

某接口要求Header带Authorization: Bearer xxx，但token 15分钟过期。常见错误：

• 全局token变量：let token = ''，多个请求并发时，A请求刷新token，B请求还在用旧token，导致401。
  解法：用Promise缓存刷新过程：

  let refreshPromise: Promise<string> | null = null; async function getToken() { if (!refreshPromise) { refreshPromise = fetch('/refresh').then(r => r.json()).then(d => d.token); } return refreshPromise; }

• 未处理401重试：请求返回401后，直接报错，不触发刷新。
  解法：在request封装中加入重试逻辑：

  async function request(url, options = {}) { let res = await fetch(url, options); if (res.status === 401) { const newToken = await getToken(); options.headers['Authorization'] = `Bearer ${newToken}`; res = await fetch(url, options); // 重试 } return res; }

• 时间漂移误差：客户端时间比服务器慢10秒，token已过期，但本地判断未过期。
  解法：首次请求时，从响应Header读取Date，计算时间差serverTimeOffset = serverDate.getTime() - Date.now()，后续所有token过期判断用Date.now() + serverTimeOffset。

Token管理不是功能，而是基础设施。一个没处理好的401，会让整个插件瘫痪。

5.3 JSON解析失败：从错误信息反推真相

failed to deserialize the json body into the target type: input: missing fie这类错误，关键在missing fie——明显是missing field拼写错误，说明后端返回了非JSON内容。排查路径：

1. 打印原始响应：console.log(await response.text())，而非console.log(await response.json())。我封装了debugResponse(response)函数，自动输出status、headers、text；
2. 检查Content-Encoding：某接口返回gzip压缩体，但response.text()自动解压，response.arrayBuffer()才得原始字节。若解压失败，text()返回乱码，JSON.parse()必然失败；
3. 验证字符编码：response.headers.get('content-type')含charset=gbk，但response.text()默认用UTF-8解码。需用response.arrayBuffer()转TextDecoder('gbk')；
4. 检查BOM：如前所述，\ufeff导致解析失败；
5. 查看网络面板：Chrome DevTools Network Tab中，点击请求→Preview，看是否显示“Failed to load response data”。若是，说明响应体损坏，需检查服务端日志。

错误信息是线索，不是结论。missing fie指向字段缺失，但根源可能是编码、压缩或网络传输问题。

5.4 插件兼容性问题：VS Code与LXMusic的隐式约定

VS Code插件和LXMusic插件看似都是JS，但运行时差异巨大：

因此，同一段代码：

// 在VS Code中OK const fs = require('fs'); const data = fs.readFileSync('./config.json'); // 在LXMusic中报错：ReferenceError: fs is not defined

解决方案：

• 条件编译：用process.env.PLATFORM === 'vscode'区分环境；
• 抽象层：定义Storage接口，VS Code实现用fs，LXMusic实现用localStorage；
• 构建时剔除：Rollup配置external: ['fs']，VS Code打包时保留，LXMusic打包时替换为空对象。

不理解宿主环境，写出来的插件注定是半成品。

6. 工程化实践：让“汇总”成为可持续的协作项目

6.1 质量门禁：CI/CD中的三道防线

在GitHub Actions中，pull_request触发以下检查：

1. TypeScript编译检查：tsc --noEmit，确保所有sources/和plugins/类型正确。曾因types.ts中expires: number写成expires: string，导致运行时Math.floor(expires)返回NaN，编译检查提前拦截。

2. JSON Schema验证：npx ajv compile -s packages/sources/*/schema.json，验证所有Schema语法有效。某次提交因逗号遗漏导致Schema无效，CI直接失败。

3. 接口连通性测试：node scripts/test-all.js --dry-run，对每个音源发起真实请求（限速1QPS），检查HTTP状态码和基本字段。失败时截图响应体，上传Artifacts供人工分析。

这三道防线，让每次PR合并前，代码质量、契约合规、运行可用性全部达标。没有CI的“汇总”，只是代码快照，不是工程产品。

6.2 文档自动化：从代码注释到可交互文档

docs/interface-spec.md不是手写，而是从JSDoc自动生成：

/** * 获取歌曲播放URL * @param songId 歌曲ID（网易云为数字ID，QQ音乐为QZ_开头字符串） * @returns 播放URL，30秒内有效 * @throws {Error} 当songId不存在或版权受限时 * @example * ```js * const url = await getSongUrl('123456'); * // https://xxx.mp3?Expires=1234567890&OSSAccessKeyId-xxx&Signature=xxx * ``` */ export async function getSongUrl(songId: string): Promise<string> { /* ... */ }

用typedoc生成HTML文档，再用markdown-it转为Markdown。关键增强：

• 实时示例：文档中嵌入<iframe src="https://run.musicfree.dev/?source=netease&songId=123456">，点击即运行真实接口；
• 变更追踪：每个接口文档页底部显示Last updated: 2024-05-20 (v2.1.0)，链接到对应commit；
• 贡献指引：文档页顶部有Edit this page on GitHub按钮，点击跳转到packages/sources/netease/README.md编辑界面。

文档即代码，代码即文档。用户查文档时，看到的就是正在运行的最新版本。

6.3 社区协作机制：如何让“长期更新”不依赖个人

“长期更新”的最大风险是作者失联。为此设计：

• 轮值维护者制度：每月由一名社区成员担任maintainer，负责审核PR、发布版本、处理issue。名单在MAINTAINERS.md公示，轮值表自动生成；
• 自动化发布：release分支合并后，GitHub Action自动执行：
  1. npm version patch/minor/major（根据commit message中的feat:/fix:/BREAKING CHANGE:）；
  2. npm publish所有changed packages；
  3. 创建GitHub Release，附带Changelog摘要；
• 健康度仪表盘：/health端点返回JSON：

  { "total_sources": 12, "healthy_sources": 11, "last_updated": "2024-