面向 Linux 本机运维与文件操作的桌面控制台，目标环境为 CachyOS/Arch Linux、niri 和 Wayland。
项目使用 Tauri 2 承载 Vue 3/TypeScript 界面，由 Rust appd 统一提供本机状态、应用资源、网络、远程连接、传输和日志数据。界面只展示后端或桌面协议返回的事实；不可用能力会保留为 degraded、unsupported 或 unreachable，并显示对应的 capability reason。
当前版本为
0.1.0，仍处于开发阶段。仓库针对 Linux/niri，不提供其他桌面环境或操作系统的兼容承诺。
- 仪表盘：集中展示后端能力目录和运行状态。
- 应用：基于
/proc的进程资源聚合，以及由 niri、Wayland idle 协议和 logind 提供事实依据的前台使用时长。 - 网络：通过 rtnetlink 获取接口计数器；按应用流量由独立 eBPF helper 提供，未授权时明确标记为 unsupported。
- 网络工具：按本机依赖情况提供基础测速、
iperf3、Wi-Fi 扫描和 IP 检查等能力。 - 远程连接：SSH 终端与 SFTP、显式 FTPS/可确认的明文 FTP、基于系统
libsmbclient的 SMB2/3 文件操作。 - 传输队列：持久化上传/下载任务，保留协议能力、冲突和恢复语义。
- 日志：日历/列表共用同一套 SQLite 实体，支持 Markdown 编辑、修订和导出；AI 会话提取仅从本机已存在且可读取的数据源获取事实。
- 音乐：本地音乐库和播放队列、QQ 公开歌单元数据、自定义来源下载，以及 QMC/QMC2/
musicex文件夹批量转换和封面修复。 - 设置：查看系统信息、能力状态和未开放配置边界。
具体能力取决于本机环境和权限。项目不会用模拟数据填补缺失值，也不会把未接入能力伪装为可操作功能。
Vue 3 / TypeScript UI
│ Tauri commands（固定契约）
▼
Tauri desktop bridge
│ Unix socket：$XDG_RUNTIME_DIR/localdesk/appd.sock
▼
Rust appd
├─ domain / IPC
├─ telemetry / system information
├─ network / usage accounting
├─ SSH / SFTP / FTP(S) / SMB
├─ transfer queue
├─ notes
└─ music / QQ local conversion
│
├─ system APIs：procfs、rtnetlink、Wayland、logind
└─ system tools/libraries：OpenSSH、libcurl、libsmbclient、SQLite
主要目录：
| 路径 | 用途 |
|---|---|
apps/desktop-ui |
Vue UI 与 Tauri 桌面桥接 |
bins/appd |
用户会话内的常驻后端 |
bins/telemetry-helper |
受控的遥测采集 helper |
bins/network-helper |
可选的 eBPF 按应用网络采集 helper |
crates/domain |
跨层领域类型与 capability 状态 |
crates/ipc |
Unix socket 消息、帧和客户端/服务端 |
crates/remote-* |
SSH/SFTP、FTP(S)、SMB 适配器 |
crates/transfers |
传输状态机、执行器和持久化 |
crates/notes |
日志实体、修订、查询与导出 |
crates/music |
本地音乐、来源、下载、QQ 解密和转换任务 |
helpers/qqmusic-wine-bridge |
仅供新版 musicex 使用的 32 位 Wine 桥接 |
packaging |
Linux 桌面入口和 Arch 包模板 |
- Linux x86_64，推荐 CachyOS/Arch Linux
- niri + Wayland 用户会话
- Rust
1.97（workspace 使用 edition 2024） - Node.js 与 pnpm
11.3.0 - C/C++ 构建工具、Clang/LLVM
- GTK 3、WebKitGTK 4.1、GLib、SQLite、libcurl、libsecret、libbpf
- OpenSSH、Samba client、systemd/logind、XDG Desktop Portal、FFmpeg/ffprobe 和 mpv
Arch 包的完整运行/构建依赖以 packaging/arch/PKGBUILD.in 为准。部分网络工具会在运行时探测 iperf3、nmcli、iw、pkexec 等程序；缺失时相应能力会降级或标记为不支持。
安装前端依赖：
pnpm install --frozen-lockfile在 niri/Wayland 图形会话中启动完整开发环境：
pnpm dev启动脚本会依次：
- 使用锁文件构建桌面端、
appd和所需 helper； - 启动
appd并等待 Unix socket 就绪； - 在
127.0.0.1:1420启动 Vite； - 启动 Tauri 桌面窗口。
普通开发启动不强制安装 cargo-xwin：存在该命令时会重建 QQ 音乐 Wine 桥接；不存在时会复用已有桥接 EXE，若两者都不存在则继续启动，带内置密钥的 QMC/QMC2 解密仍可使用。需要单独构建桥接时执行：
cargo install cargo-xwin
npm run build:qqmusic-bridge关闭桌面窗口或按 Ctrl+C 会结束整组开发进程。脚本要求 XDG_RUNTIME_DIR 已设置为当前用户拥有的绝对路径，并会拒绝复用已被占用的 socket 或 Vite 端口。
只启动前端界面可使用：
pnpm --filter desktop-ui dev此时没有桌面桥接和 appd，依赖后端的页面会如实显示不可达状态。
| 文件/能力 | 是否需要 Wine 和正在运行的 QQ 音乐 | 输出/行为 |
|---|---|---|
.qmc0、.qmc2、.qmc3 |
否 | MP3 |
.qmcflac |
否 | FLAC |
.qmcogg |
否 | Ogg Vorbis |
带内置 ekey 的 .mflac、.mflac0、.mgg、.mgg1、.mggl |
否 | FLAC 或 Ogg Vorbis |
文件尾为 musicex 且没有内置 ekey 的新版文件 |
是 | 通过受限的 32 位 Wine 桥接输出 FLAC 或 Ogg Vorbis |
| “仅补封面” | 否 | 原子更新已有 MP3、FLAC、Ogg 文件的封面标签，不转码音频 |
便携解密逻辑在 Rust 进程内完成。musicex 桥接只附加到名称精确为 QQMusic.exe 的唯一进程，并检查 QQMusicCommon.dll 所需导出；QQ 音乐升级后如果导出发生变化，界面会显示不兼容，不会继续尝试解密。
Arch/CachyOS 安装 Wine 后，在 Wine 中安装 Windows QQ 音乐并登录有权访问相应媒体的账号。默认前缀为 $HOME/.wine，自定义前缀可在启动应用前设置绝对路径：
export WINEPREFIX=/absolute/path/to/prefix
wine 'C:\Program Files (x86)\Tencent\QQMusic\QQMusic.exe'应用会自动检查 WINEPREFIX、$HOME/.wine、Bottles 常用目录和 Steam Proton compatdata。QQ 音乐默认下载目录通常位于：
$WINEPREFIX/drive_c/users/<用户>/Music/VipSongsDownload
图片缓存通常位于：
$WINEPREFIX/drive_c/users/<用户>/AppData/Roaming/Tencent/QQMusic/QQMusicCache/QQMusicPicture
进入“音乐 → 批量转换”后，顶部状态带会显示 ffmpeg、ffprobe、mpv、Wine、QQ 音乐进程、桥接 EXE、Wine 前缀、下载目录和图片缓存的真实检测结果。
- 选择“解密音乐”，分别选择加密音乐目录和输出目录；两个目录不得相同或互相包含。
- 点击“开始转换”。任务按文件持久化游标，支持取消；应用重启后可继续，部分失败可重试。
- 若目标目录存在同名音频，使用 ffprobe 比较无损/有损、位深、采样率、声道和码率：只有源音质更高才覆盖；相同或目标音质更高时跳过。
- 输出先写入权限为
0600的临时文件，验证音频签名并同步落盘后原子提交；源文件和输出目录中的无关文件不会被删除。
“仅补封面”直接选择已有解密音频目录。默认只使用本地 QQ 图片缓存，并要求音频的歌手和专辑与缓存键精确归一化匹配。用户可显式开启“允许在线补图”；在线回退只查询固定 QQ HTTPS 主机，并且仅在返回结果的歌手和专辑都精确匹配时写入，不会使用默认图或模糊匹配图。
| 界面状态 | 处理方法 |
|---|---|
Wine 不可用 |
仍可处理便携 QMC/QMC2；需要 musicex 时安装 Wine。 |
QQ 音乐未运行 |
在同一个 Wine server/prefix 中启动 QQ 音乐并保持唯一一个 QQMusic.exe。 |
QQ 音乐进程冲突 |
退出多余实例，只保留一个 QQMusic.exe 后重新检查。 |
Wine 桥接不可用 |
正式安装包应包含 /usr/lib/localdesk/localdesk-qqmusic-wine-bridge.exe；源码开发可运行 npm run build:qqmusic-bridge。 |
QQMusicCommon.dll 不兼容 |
当前客户端缺少桥接所需导出；不要批量重试，等待项目适配该客户端版本或使用已验证版本。 |
本地缓存没有精确封面 |
先让 QQ 音乐加载相应专辑图片，或在“仅补封面”模式显式允许在线补图。 |
当前真实运行验收使用 Wine 下的 32 位 QQ 音乐 22.52。这只是已验证样本，不是长期版本承诺；最终以页面的进程、DLL 导出和桥接检测结果为准。
不要默认运行全仓测试；按变更所在 package 执行最小检查。
前端：
pnpm --filter desktop-ui typecheck
pnpm --filter desktop-ui test单个 Rust package：
cargo fmt --package localdesk-appd -- --check
cargo test --locked -p localdesk-appd
cargo clippy --locked -p localdesk-appd --all-targets -- -D warnings将 localdesk-appd 替换为实际修改的 package 名称。独立适配器也可使用其 manifest，例如：
cargo test --locked --manifest-path crates/remote-ftp/Cargo.toml构建 UI 和发布二进制，并暂存为 Linux 文件系统树：
scripts/stage-release.sh --build /tmp/localdesk-stage
scripts/verify-release-stage.sh /tmp/localdesk-stage生成 x86_64 tarball 和配套 PKGBUILD：
scripts/prepare-arch-package.sh /tmp/localdesk-package若已经单独生成并验证过 release stage，可避免重复构建并复用该制品树：
scripts/prepare-arch-package.sh --stage /absolute/verified-stage /tmp/localdesk-package在干净的 Arch/CachyOS 机器上安装生成的包：
sudo pacman -U /tmp/localdesk-package/localdesk-*.pkg.tar.zst发布包会安装六个 Linux 可执行文件和一个 32 位 QQ 音乐桥接 EXE 到 /usr/lib/localdesk，并安装桌面入口、XDG autostart、组件许可证和 SHA-256 清单。Wine 保持可选依赖；没有 Wine 时应用与便携 QMC/QMC2 功能仍可使用。详细生命周期和可移植构建要求见 packaging/linux/README.md。
- IPC socket：
$XDG_RUNTIME_DIR/localdesk/appd.sock - 持久状态：
${XDG_STATE_HOME:-$HOME/.local/state}/localdesk - SQLite 数据包括使用时长、远程连接元数据、传输队列、日志、音乐下载和 QQ 批量转换任务。
- 远程密码/密钥口令使用 Secret Service 引用；配置数据库不保存明文 secret。
卸载软件包不会自动删除用户状态或 Secret Service 项。需要清理时应先停止当前图形会话中的 appd，再由用户明确删除对应数据。
- UI 不获得任意 shell、插件或文件系统权限；Tauri command 使用固定、结构化契约。
- SSH/SFTP 复用系统 OpenSSH，FTP(S) 复用 libcurl，SMB 复用 Samba
libsmbclient。 - 明文 FTP 必须显式确认；FTPS 默认验证系统 CA、主机名和证书有效期。
- SMB 最低为 SMB2，密码不进入命令行参数。
- 按应用网络统计默认不提权。若要启用，必须对不可由桌面用户替换的已安装 helper 单独授予最小的
cap_bpf,cap_net_admin=ep；具体部署和回滚流程见crates/network/README.md。 - 核心流程不依赖全局
Mod/Super快捷键、托盘、通知 action、持久剪贴板或固定屏幕坐标。
crates/network/README.md：网络计数与 eBPF helper 边界crates/usage/README.md：niri 前台使用时长核算契约crates/remote-ftp/README.md：FTP/FTPS 安全与恢复语义crates/remote-smb/README.md：SMB2/3 系统适配器边界packaging/linux/README.md：Linux 安装、升级和卸载约定design-qa.md：界面设计检查记录
MIT © 2026 skynit
音乐模块 vendored 的 qmc2-crypto 和遗留 QMC 映射实现按 MIT 或 Apache-2.0 使用；两套许可证文本保存在 crates/music/vendor/qmc2-crypto 和 crates/music/LICENSES。Wine 桥接使用的 Frida Core/binding 许可证文本保存在 helpers/qqmusic-wine-bridge/LICENSES。luyikk/qqmusic_decrypt 在审查版本中没有许可证，因此本仓库没有复制或链接其源码和二进制，只记录了行为研究。用户只能处理自己有权访问的媒体，并应自行确认适用的服务条款和当地法律。