企业官网建设流程全解析

Levyra 是一款面向 Android 与 Windows 的开源音乐播放器，集音乐发现、同步歌词、电台和本地播放于一体，无广告、无追踪。本文带你完整梳理 Levyra 的代码结构、工程规范，以及如何通过代码提交或翻译贡献参与这个开源项目，适合第一次参与开源的新手。

🎵 先认识 Levyra：开源音乐播放器概览

Levyra 的核心理念是Made for listening, not logging in——专为聆听而生，无需注册登录。它把在线流媒体和本地音乐文件放进同一个曲库，共享同一套播放列表、队列和历史记录，数据全部保存在设备本地。

主要特点：

• 原生播放：Android 端使用 Media3 / ExoPlayer，Windows 端通过 libVLC 直接解码，不套 Web 壳
• 无缝播放与音频调校：跨轨过渡、10 段均衡器、AutoEQ 耳机配置
• 同步歌词：支持点击跳转、时延修正与罗马音转写
• 零追踪：无遥测、无分析、无广告，播放数据留在设备上

技术栈以 Kotlin 为主，Android 端构建于 Jetpack Compose 与 Material 3，数据持久化使用 Room；Windows 端运行在 Compose Multiplatform（JVM 21）上。

📂 快速看懂 Levyra 的代码结构

Levyra 是一个多模块 Gradle 仓库，模块划分清晰，新手按目录入手即可定位代码。仓库结构总览见 settings.gradle.kts，架构说明见 docs/ARCHITECTURE.md。

Android 端的 UI、播放、数据库各层职责划分，以及单向数据流（用户输入 → ViewModel → 仓库/播放器 → 不可变状态 → Compose 渲染）在 docs/ARCHITECTURE.md 中有专门章节讲解，是修改代码前最值得先读的文件。

📐 工程规范：动手写代码之前必读

Levyra 用一系列AGENTS.md文件定义了工程契约，人类贡献者同样适用：

• 根目录 AGENTS.md：仓库级规则，要求Plan → Execute → Verify的工作方式，最小化改动、不做无关重构
• app/AGENTS.md：Android 模块规范，涵盖 Material 3 Expressive 设计、内存回归防护、Intent 安全等
• desktop/AGENTS.md：Windows 模块规范，明确core/保持纯 JVM、不依赖 Compose 或 VLC API
• docs/AGENTS.md：文档撰写标准，要求文档描述当前代码现状

其中几条对新手贡献者最实用的规则：

1. 使用仓库自带的 Gradle wrapper 构建，不要使用系统安装的 Gradle
2. 提交前运行质量门禁：

python3 scripts/ai_quality_gate.py --profile fast

推送或发起 PR 前则运行完整配置--profile full。缺少 SDK、签名或设备时，检查项应标记为 BLOCKED 而不是当作通过 3.提交前检查最终 diff：git diff --check，确认没有意外的版本、二进制或凭据变更 4.保护用户数据：除非任务明确要求，不得破坏下载、收藏、播放列表、队列、歌词、历史等数据 5.不提交密钥：.env、local.properties、keystore 等敏感文件严禁入库

完整的工程生命周期（实现、评审、CI、测试、合并、发布各阶段）记录在 docs/ai/WORKFLOW.md。

🛠️ 本地构建：最快上手步骤

克隆仓库

git clone https://gitcode.com/gh_mirrors/le/Levyra-deepsound cd Levyra-deepsound

构建 Android Debug 包

环境要求：JDK 17、Android SDK Platform 37，并使用仓库内的 Gradle wrapper：

./gradlew assembleDebug

Windows 上使用gradlew.bat assembleDebug。Debug APK 输出在app/build/outputs/apk/debug/，连接设备后可用./gradlew installDebug直接安装。

构建指南原文见 docs/site/development.md，Windows 桌面端版本与 Android 版本独立开发、独立发版，desktop/目录下有独立的 Gradle 构建脚本。

🚀 如何提交你的第一个代码贡献

1. 先找小问题入手：从 issue 列表中标记简单的 bug 或 UI 修正开始，避免一上来就改播放核心链路
2. 最小连贯改动：遵循仓库规则，一次只解决一个问题，不夹带无关重构
3. 先跑最窄的检查：改完立即运行对应模块的测试与质量门禁，再检查完整 diff
4. 用独立分支 + 草稿 PR 提交：PR 描述中如实说明改了什么、验证了哪些检查、还有哪些未验证
5. 保持播放链路同步：任何涉及播放的改动都要确认 MediaSession、通知、Android Auto、队列与后台服务状态一致

Levyra 由维护者公开开发，commit、PR 与 issue 全部开放，工程规则也直接放在仓库里供所有人查看，协作风格见 docs/site/development-notes.md。

🌍 翻译贡献：最容易参与的方式

即使不写代码，你也能为 Levyra 做出贡献——项目已覆盖41 种语言，且 Android 翻译覆盖率达到 100%。

• 源字符串与翻译文件位于app/src/main/res/，每种语言一个values-xx/目录，例如简体中文为 values-b+zh+Hans/strings.xml
• 翻译通过项目托管的 Web 翻译平台（Hosted Weblate）进行，入口与实时进度徽章见 README.md 的 Translations 小节
• 发现某句翻译读起来别扭、或术语前后不一致，同样可以直接在平台上修正
• 翻译时保持与现有术语一致（如"收藏"、"播放列表"、"离线混音"），注意长文本在按钮和标签里的溢出问题

对新手来说，翻译 PR 门槛低、反馈快，是熟悉项目流程和社区氛围的最佳起点。

📚 常用文档速查

常见问题 FAQ

Q：Levyra 是什么许可证？A：GPL-3.0，代码位于各模块内，第三方组件声明见 docs/THIRD_PARTY_NOTICES.md。

Q：没有 Android 设备能贡献什么？A：可以贡献翻译、文档、Windows 桌面端代码，或审查 issue 与 PR。

Q：改动很大要分几步提交？A：仓库要求"最小连贯改动"，大功能建议拆成多个可独立评审的 PR，先完成实现阶段再进入评审与发布阶段。

从翻译一句文案到修复一个播放问题，Levyra 的工程规范都为不同经验的贡献者留了明确路径。先读 AGENTS.md 和 docs/ARCHITECTURE.md，跑通一次本地构建，你就能开始提交自己的第一份贡献了。♫