GitHub 源码快照

这页基于 GitHub 仓库 Moekotori/ECHO 的 main 分支整理。它不是路线图，也不承诺未来功能；它只记录当前源码里已经能从 README.md、package.json 和 docs/ECHO_NEXT_*.md 看到的工程事实。

仓库事实

项目	当前状态
仓库	`Moekotori/ECHO`
默认分支	`main`
可见性	Public
包名	`echo-next`
当前 `package.json` 版本	`26.6.7`
License	`Apache-2.0`
Electron appId	`app.echo.next`
产品名 / 可执行文件名	`ECHO NEXT`

普通用户下载仍以 GitHub Releases 和官网镜像说明为准；源码快照只用于理解工程结构和维护边界。

核心定位

GitHub README 把 ECHO NEXT 定位为“面向本地曲库、HiFi 输出和长期维护的开源桌面音乐播放器”。源码文档强调它不是旧 ECHO 上继续堆功能的补丁层，而是重新拆分边界的桌面音乐播放器工程。

当前工程优先级可以概括为：

本地播放可靠。
音频链路稳定。
大曲库不把 Renderer 卡死。
用户数据安全。
网络能力只作为补全和扩展，不压过本地曲库和基础播放。

运行与分层

源码文档中的架构分层是：

React Renderer
  pages, components, virtual lists, settings, player controls
        |
Typed Preload Bridge
        |
Electron Main Process
  IPC, windows, lifecycle, services, system integration
        |
        +-- Library Core
        |     SQLite, scans, metadata, covers, folders, playlists
        |
        +-- Audio Core
        |     AudioSession, decoder pipeline, output bridge, device state
        |
        +-- Native Hosts
        |     echo-audio-host, WASAPI, ASIO, EQ, SMTC helper
        |
        +-- Experience Services
              lyrics, MV, streaming, plugins, remote sources

边界要求很明确：

Renderer 负责页面、列表、歌词、MV、设置和播放控制界面。
Preload 只暴露 typed window.echo.* API，不暴露 raw ipcRenderer、Node fs/path/process。
Main process 组合窗口、IPC、服务和系统集成，业务逻辑应下沉到对应 service。
Library Core 是曲库事实来源，不能让 Renderer 持有全量曲库或临时重组专辑墙。
Audio Core 是播放事实来源，Renderer 不猜权威播放位置。
Native hosts 承担 Electron/Node 不适合直接做的音频输出、DSP、SMTC 和底层 helper。

当前主要技术栈

方向	GitHub 当前依赖 / 线索
桌面运行时	Electron `^37.10.3`、electron-vite `^5.0.0`、electron-builder `^26.8.1`
前端	React `^18.2.0`、React DOM `^18.2.0`、TypeScript `^5.3.3`、Vite `^7.3.3`
UI 与动效	`lucide-react`、`motion`、`@tanstack/react-virtual`、`@fontsource/outfit`
本地数据库	SQLite + `better-sqlite3` `^12.9.0`
媒体处理	`music-metadata`、`sharp`、`taglib-wasm`、FFmpeg 工具链
文本与搜索辅助	`iconv-lite`、`pinyin-pro`、`opencc-js`、`kuroshiro`、`kuromoji`
播放 / 媒体能力	Native audio host、`shaka-player`、HQPlayer/Connect 相关服务
AirPlay RAOP	optional dependency `@lox-audioserver/node-libraop`，打包时带 `airplayRaopHelper.cjs`
测试	Vitest `^4.1.6`、Testing Library、jsdom、Playwright

依赖名只能证明源码当前包含这些工程能力，不等于所有场景都已经公开承诺完整支持。公开能力边界仍以用户文档、设置页说明和实际发布说明为准。

构建脚本

package.json 暴露的关键脚本：

脚本	作用
`npm run dev`	rebuild native、确保 audio host 后启动 Electron + Vite 开发环境
`npm run dev:full`	额外构建 SMTC host 后启动完整开发环境
`npm run build`	TypeScript 检查后执行 electron-vite build
`npm run build:win`	Windows 正式构建链路，包含 native rebuild、FFmpeg 校验、audio host、SMTC host、native scanner、Electron build、NSIS 资源、electron-builder 和 AirPlay 包验证
`npm run build:win:unsigned`	Windows unsigned 构建链路，仍会走 AirPlay 包验证
`npm run build:linux`	通过 `scripts/build-linux.mjs` 构建 Linux x64 包
`npm run test`	Vitest 测试
`npm run typecheck`	TypeScript 类型检查
`npm run verify:ffmpeg`	校验 FFmpeg 工具链
`npm run verify:airplay-package`	校验 Windows 打包后的 AirPlay RAOP 资源
`npm run smoke:audio-host` / `smoke:native-scanner` / `smoke:smtc-host`	对原生 helper 做烟测

文档改动通常不需要跑桌面端全量构建；涉及官网本身时跑 ECHO Page 的 npm run build 更直接。涉及 ECHO 桌面端构建链路时，按对应平台和改动范围选择脚本。

平台与产物

平台	当前源码配置
Windows x64	NSIS 安装包 + portable，产品名 `ECHO NEXT`，快捷方式名 `ECHO`
Linux x64	AppImage + deb
macOS	`package.json` 没有 macOS 打包目标

Windows 打包资源包括：

echo-audio-host.exe
echo-smtc-host.exe
echo-native-scanner.exe
airplayRaopHelper.cjs
electron-app/tools

Linux 打包资源包括：

echo-audio-host
echo-native-scanner
electron-app/tools-linux

Linux 源码文档明确当前是 x64 基础构建和基础播放边界：AppImage/deb、本地曲库扫描、本地 WAV / FLAC / MP3 播放、Linux shared native output、ALSA 后端。Linux arm64、Flatpak、Snap、JACK 原生后端、PipeWire 原生后端、Linux 独占/bit-perfect 级 HiFi 后端都不应写成已支持。

源码文档里的核心边界

Library Core

SQLite 是本地曲库事实来源。
扫描、metadata、封面、专辑聚合、搜索索引、健康报告、move candidate 都在主进程服务边界内。
Renderer 只拿分页数据，不拿全量曲库、不读 SQL、不生成封面、不重组专辑墙。
文件变化观察和 move repair 都必须保守，不能自动删除、自动合并或偷偷移动真实音频文件。

Audio Core

Audio Core 负责播放、时钟、输出设备、解码、DSP 状态和 HiFi 可解释性。
本地稳定播放优先级高于歌词、MV、下载、网络任务和插件。
播放进度应来自输出侧或 Audio Core 权威状态，Renderer 不应靠 timer 猜。
WASAPI Shared、WASAPI Exclusive、ASIO、DSD、ReplayGain、EQ、重采样和 bit-perfect 状态必须诚实区分。

Network Metadata

网络元数据是弱补全，不是第二个 metadata reader。
pending / reading 不等于缺失。
网络结果先进入候选表和决策表，不能覆盖 manual、embedded、sidecar 或 folder structure。
网络封面必须通过本地封面缓存后再展示，不能直接把远程 URL 当作最终封面事实。

Linux Build

Linux 包必须在 Linux x64 环境构建。
build:linux 会检查平台、FFmpeg、native ABI、audio host、electron-builder 产物和打包后的资源。
CI 构建通过只说明包能产出，不代表真实桌面音频已经验收。

维护建议

更新这页时，优先重新核对 GitHub 当前 package.json、README.md 和 docs/ECHO_NEXT_*.md。不要把旧 roadmap、实验想法、issue 讨论或本地未发布分支写成公开能力。

如果源码事实和官网公开说明冲突，先以用户安全、播放稳定和实际发布说明为准，再决定是否更新官网文档或等待桌面端实现稳定。