PimpinPumpkin/Vela
GitHub: PimpinPumpkin/Vela
Vela 是一款无需 Google Play Services 的 Android 地图与导航应用，通过开放地图数据加设备端抓取公开接口的方式，在保护隐私的同时提供高质量的地图、搜索和实时导航体验。
Stars: 69 | Forks: 10
# Vela Maps
一款适用于 Android 的去 Google 化地图与导航客户端 —— *正如 NewPipe 之于 YouTube，
Vela 之于 Google Maps。* 底图使用开放的矢量瓦片，由设备本身抓取 Google 的公开
Web 接口（基于单用户，无后端）来获取那些只有 Google 做得好的功能：POI 质量、
路线规划以及**支持实时交通的预计到达时间（ETA）**。专为在
GrapheneOS 及其他无 GMS 的 ROM 上运行而构建。
## 截图
| 导航 | 地图与搜索 | 地点详情 | 路线 | 搜索结果 |
|:-:|:-:|:-:|:-:|:-:|
| 
| 
| 
| 
| 
|
| 公共交通 | 浅色主题 - 地图 | 浅色主题 - 地点 |
|:-:|:-:|:-:|:-:|
| 
| 
| 
|
*带车道引导、路线盾牌和时速表的分步导航；无密钥的
OpenFreeMap 底图采用了 Google 自身的采样颜色和 Roboto 标签，
带有评分的 POI 图标和分层圆点；实时地点数据；包含
备选路线、纯文本交通状况和避开选项的路线面板；以及应用内的
浅色/深色主题（与操作系统解耦）。*
## 安装
[
](https://apps.obtainium.imranr.dev/redirect?r=obtainium://add/https://github.com/PimpinPumpkin/Vela) [
](FDROID.md)
点击徽章 —— 无需 Play Store，无需账号。Obtainium 会自动追踪
**每周稳定版**发布；开启“包含预发布版本”，您将获得
**每日构建版**频道（每次推送到 main 分支时更新）。F-Droid 徽章指向的是
**Vela 自己的仓库**，而不是 f-droid.org 目录 —— 将
`https://pimpinpumpkin.github.io/Vela/repo` 添加到任何 F-Droid 客户端中，它将提供
相同的已签名 APK，默认为每周稳定版（指纹和每日构建频道的
设置详见 [FDROID.md](FDROID.md))。或者直接从
[Releases](https://github.com/PimpinPumpkin/Vela/releases) 获取 APK。
## 功能特性
- **真正的分步导航。** 语音播报由完全在手机上运行的神经网络语音合成，包含车道图、出口盾牌、时速表、自动重新规划路线，以及当您的目的地在您到达后一小时内关闭时的提醒（通过卡片和语音播报）。
🔊 **听听 Vela 的导航语音** —— 默认语速下的实际应用内语音：
https://github.com/user-attachments/assets/17f246e4-51c8-4d01-998b-dcd7f29dc15f
- **在 Google 移动内容时自我修复。** 抓取规则存在于应用启动时检查的已签名
配置中 —— 当 Google 更改某个字段或接口时，修复程序会在几分钟内推送到每个安装中，无需更新。同一频道还可以
将提醒通知（“搜索功能已瘫痪，修复即将推出”）直接推送到地图上。
- **语音对话。** 点击麦克风并说出您的需求。Vela Voice 在手机上进行语音转录
（需一次性下载 58 MB），或者移交给您已有的语音输入应用。无论哪种方式，您说的话都不会发送到云端语音服务。
- **离线工作。** 下载一次州或国家，其地图、分步
路线规划以及其中的每个地点都可以在没有信号的情况下保持可搜索 —— 包括输入的街道
地址。
- **真实的地点信息。** 营业时间（包括节假日）、可搜索的评论、照片
图库、繁忙时段、电话和网站 —— 这些都是您开车去某地之前真正需要检查的内容，并在您到达时已经关闭的情况下发出警告。
- **可读的交通状况。** 路线选择会在绿色/琥珀色/红色的时间旁边用文字说明交通畅通、中度拥堵或严重拥堵，最快的路线排在列表首位。
- **实时油价。** 搜索加油站，每个加油站的当前价格都会直接
显示在地图标记上、结果列表中和地点页面上。
- **Material You 主题（如果需要）。** 一个可选开关使用您的壁纸颜色为 Vela 的界面着色（Android 12+）；默认关闭，且无论哪种方式，地图本身都保持整洁。
- **公共交通。** 包含路线胶囊标签、逐站停靠点以及
前往站台的逐步指引的行程。
- **无账号，无追踪。** 无 Google 账号，无 GMS，无遥测。Google 的服务器能看到和不能看到的内容在 [PRIVACY.md](PRIVACY.md) 中有明确记录。
- **其他功能。** Android Auto，15 种语言（包括希伯来语，这是第一个 RTL 语言），应用内浅色/深色主题，全 D-pad 操作
适用于按键手机，停车记忆，地点列表，以及内置更新程序（支持每周稳定版或每日构建版频道）。
完整的功能运行列表位于 [FEATURES.md](FEATURES.md)。
## 十秒了解日常功能
- **保存您的停车位**：停车时点击地图上的 **P** 按钮。稍后点击青色
图钉获取步行返回的路线，或者在您离开时点击图钉的清除按钮。
长按 **P** 查看您的停车历史记录，以防您不小心覆盖了某个地点。
- **列表**：类别标签旁边的书签按钮会打开 **您的列表**。
在此处创建一个列表，或从任何地点的页面添加（⋮ → 保存到列表），可以为每个
地点添加备注。列表可以在设置中备份到文件。
- **导入 Google Maps 列表**：将 `maps.app.goo.gl` 分享链接粘贴到
搜索栏中。该列表的地点将作为结果显示，并带有所有者的备注；点击
**保存列表**以保留本地副本。
## 为什么去 Google 化的应用要使用 Google
没有 Google Play Services 的手机无法运行 Google Maps，而且开放的地图
数据集在搜索、评论、营业时间和实时交通状况方面远远不够。因此 Vela 是
一个基于 Google 公开 Web 接口的轻量级客户端。它像未登录的浏览器一样向它们
发出请求，基于每个用户单独运行，没有账号，没有共享的 API key，也
没有中间服务器。NewPipe 对 YouTube 做的也是同样的事情。这里没有广告，您
的搜索、保存的地点和历史记录都保留在手机上。如果您运行 GrapheneOS
或其他无 GMS 的 ROM，这能让您重新使用可用的地图。
地图本身、街道、标签和房屋号码全部来自 OpenStreetMap。Google 仅用于地点、搜索、路线规划和交通状况。因此，街道名称和房屋号码可能与 Google Maps 显示的不同，您在离线状态下看到的细节程度取决于 OpenStreetMap 对您所在区域的覆盖程度。我正在寻找改进 OSM 并填补数据空白的方法。敬请期待。
## 隐私
**没有 Vela 后端，没有账号，也没有遥测**。Vela 直接从您的手机获取 Google
数据，就像未登录的浏览器一样 —— Google 能看到您的 IP、查询和
地图区域，但**看不到 Google 账号或任何应用 key**，这很像在
隐身窗口中使用 `google.com/maps`。您保存的地点、历史记录和设置
永远不会离开设备。**[阅读关于每个服务究竟接收什么数据的详细说明 → `PRIVACY.md`](PRIVACY.md)。**
简而言之：Google 从*知道您是谁以及您去过哪里*缩减为
*偶尔回答一个匿名问题*。而且对于驾驶来说最重要的部分 ——
您的 GPS 轨迹、您的地图浏览 —— 根本不会传到 Google。
| Google 获取的内容 | Google Maps 应用 | Google Maps 网页版 | Vela |
| --- | --- | --- | --- |
| 与您的 Google 账号绑定 | 是，始终登录 | 是，除非使用隐身模式 | 从不 —— 没有登录 |
| 持久性设备标识符 | 是（通过 Play Services 获取设备 ID 和广告 ID） | 浏览器 Cookie | 无账号，无应用 key；只有像任何网站访问者一样的 IP |
| 您的精确 GPS 位置 | 打开时持续获取，如果启用位置记录还会获取位置历史 | 选项卡打开时获取 | 从不发送。位置保留在手机上；搜索只发送您正在查看的地图区域 |
| 地图的每次平移和缩放 | 是 —— 他们的服务器渲染地图 | 是 | 否 —— 地图瓦片来自 OpenFreeMap，因此 Google 永远不会看到您的浏览 |
| 您的搜索 | 是，保存到您的账号历史记录 | 是 | 查询文本仅在您搜索时匿名到达 Google |
| 您打开的地点页面 | 是 | 是 | 地点查询匿名到达 Google |
| 分步导航路线 | 是，完整的行程遥测 | 是 | 路线在开放的 OSRM/GraphHopper 上运行；Google 只会看到一次匿名的 ETA 检查，永远不会看到您的实时位置 |
| 保存的地点、家、公司 | 存储在他们的服务器上 | 存储在他们的服务器上 | 仅存储在您的手机上 |
| 建立广告画像 | 填充您的广告画像 | 填充您的广告画像 | 没有任何可附加的内容 |
| 在完全不与 Google 交互的情况下工作 | 否 | 否 | 是 —— 下载的区域完全离线进行搜索、路线规划和导航 |
每次请求的完整详细信息请参见 [PRIVACY.md](PRIVACY.md)。
## 工作原理
每一项功能、其背后的无密钥方法以及建议首先阅读的文件都在
**[docs/HOW-IT-WORKS.md](docs/HOW-IT-WORKS.md)** 中进行了说明 —— 这是代码库的一屏索引
（底图、Google 抓取、开放路线规划、离线技术栈、远程自我修复等）。
更深入的内容见 [`SPEC.md`](SPEC.md)。
## 文档 —— 去哪查看
| 文件 | 包含的内容 |
|---|---|
| [`README.md`](README.md) | 本文件 —— Vela 是什么、为什么开发它、隐私比较以及构建/运行 |
| [`docs/HOW-IT-WORKS.md`](docs/HOW-IT-WORKS.md) | 每一项功能、其背后的无密钥方法，以及建议首先阅读的文件 |
| [`FEATURES.md`](FEATURES.md) | 所有已发布功能的完整分类列表（百科全书） |
| [`SPEC.md`](SPEC.md) | 权威的**重构规范** —— 架构、提取器契约（pb 布局 + 响应索引）、弹性层、硬性约束 |
| [`ROADMAP.md`](ROADMAP.md) | 计划的工作 + 大胆尝试（可选遥测、Vela 自有交通图层、超大国家图谱拆分等） |
| [`PRIVACY.md`](PRIVACY.md) | 每次 Google 接口请求具体接收了什么 |
| [`CLAUDE.md`](CLAUDE.md) | 构建规则、模块布局以及来之不易的坑点 —— 适用于贡献者（人类或 AI） |
| [`docs/dpad.md`](docs/dpad.md) | D-pad / 无触摸屏操作 —— 设计、发现、各界面审查以及与上游合并的策略 |
| [`docs/CALIBRATION.md`](docs/CALIBRATION.md) | 深入探讨 Google 提取器和已签名的远程修复通道 |
| [`docs/MAP-STYLE.md`](docs/MAP-STYLE.md) | 底图、字体、自定义图层和主题设置详情 |
## 架构
两个具有严格边界的 Gradle 模块（AGP 8.7.3、Kotlin 2.1、Compose、Hilt、
R8 发布构建）：**`:core`** 是采用
NewPipeExtractor 模式、与 UI 无关的“提取器” —— 包含模型、Google 抓取器和解析器、开放路由器、
纯导航引擎和远程配置层 —— 而 **`:app`** 是基于
MapLibre 的 Compose UI。`MapDataSource` 是它们之间的承重接缝：用于
离线开发的 Mock，今天的 Google，以及未来的 Overture/OSM 源或可自托管的
后端都以相同的方式插入。完整的模块树和每个接都在
[`SPEC.md`](SPEC.md) 中。
## 构建与运行
标准 Android 工具链：
```
# debug build（compile check / local install）
./gradlew :app:assembleDebug
# 真正的 distribution build - R8 + resource shrinking。
# 始终发布 release：在地图 scroll/nav 期间，debug builds 会出现明显的卡顿。
./gradlew :app:assembleRelease
# 针对纯逻辑（polyline codec、nav engine）的 unit tests
./gradlew :core:test
```
发布签名来自 CI 环境变量（`VELA_KEYSTORE_PATH`、
`VELA_KEYSTORE_PASSWORD`、`VELA_KEY_ALIAS`）；本地构建会回退到
debug keystore，因此 `adb install` 仍然可以工作。
**CI**：每次推送到 `main` 分支都会构建、测试并发布一个签名的 nightly
预发布版（`v0.4.`）；每周一次的任务会将最新的 nightly 版本提升为
稳定版，并且 F-Droid 仓库索引会根据两者重新构建。发布
流水线的详细信息（密钥、频道、版本控制）位于
[`CLAUDE.md`](CLAUDE.md) 中。在默认情况下，应用通过无密钥的 OpenFreeMap
底图与实时的 Google 数据源通信；`MockMapDataSource` 是
离线回退方案。
## Google 提取器与校准
完整的说明已移至 [`docs/CALIBRATION.md`](docs/CALIBRATION.md)：基于用户的
提取器、已签名的远程修复通道以及重新校准手册。
## 去 Google 化 / GrapheneOS 注意事项
- **位置：** 使用 AOSP 的 `LocationManager`，从不使用 `FusedLocationProviderClient`。在
GrapheneOS 上，启用 PSDS（设置 → 位置）会将冷启动 GPS 定位时间从
~30 秒缩短到几秒钟 —— 当 Vela 注意到定位缓慢时，会显示一次性提示。
- **语音：** 神经网络导航语音和 Whisper 语音搜索都完全
在设备上运行（捆绑 sherpa-onnx runtime，模型在应用内下载）；可以选择任何系统
TTS 引擎替代。详情见 [FEATURES.md](FEATURES.md)。
- **任何地方都没有 GMS：** 没有 Fused Location、没有 FCM、没有 Firebase、没有 Play
Integrity。所有内容（MapLibre、OkHttp、Compose、Hilt）都是纯 AOSP。
## 地图样式
详情已移至 [`docs/MAP-STYLE.md`](docs/MAP-STYLE.md)。
## 路线图
到目前为止发布的所有内容都在 [FEATURES.md](FEATURES.md)（完整列表）和每个版本的
发布说明中。仍然开放的内容（详见 [ROADMAP.md](ROADMAP.md)）：
- [ ] 餐厅菜单可靠性（Google 对菜单照片的标记不一致；正在深入研究）
- [ ] 卫星图像图层（开放的 Esri World Imagery）
- [ ] **预测性**（未来交通状况）出发时间 ETA —— 需要进行 directions-`pb` 校准
- [ ] 可选的离线高速公路参考信息
- [ ] 嵌入式 Mapillary/KartaView 街道图像（需要 token；街景目前在浏览器中打开 Google 的无密钥全景图）
- [ ] F-Droid 提交 + 可重现构建
**不可能实现的功能** —— 任何需要您登录 Google 或将数据交给
后端的功能：贡献评论/照片/编辑、实时位置共享和共享 ETA、位置
时间线，以及 Google 从匿名请求中剥离的受登录限制的数据（实时繁忙程度）。
Vela 的核心主旨就是没有账号和服务器能看到您。
## 关于名称的说明
**Vela Maps** (`app.vela`) —— 导航员的星座“船帆座”，在
几种语言中也是“航行”的意思。该名称已经过审查，确保没有与地图应用发生
商标冲突。
## 贡献
首先阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md) —— 它涵盖了硬性规则（无
后端、无静态 Google key、去 Google 化 runtime、`:core`/`:app` 模块
边界、在同一提交中包含文档以及所有 14 种语言的翻译）以及如何
发送更改。特意没有单独的行为准则文档：一切以
代码为准。安全问题请通过 [`SECURITY.md`](SECURITY.md)（GitHub
私有漏洞报告）处理，而不是公开的 issue。
## 许可证
[](http://www.gnu.org/licenses/gpl-3.0.en.html)
Vela 是自由软件：您可以自由使用、学习、分享和改进它。您可以使用、修改和重新分发本项目，但前提是您的修改必须在相同的许可证下保持开源。
| | | | |
| 公共交通 | 浅色主题 - 地图 | 浅色主题 - 地点 |
|:-:|:-:|:-:|:-:|
| | | |
*带车道引导、路线盾牌和时速表的分步导航；无密钥的
OpenFreeMap 底图采用了 Google 自身的采样颜色和 Roboto 标签，
带有评分的 POI 图标和分层圆点；实时地点数据；包含
备选路线、纯文本交通状况和避开选项的路线面板；以及应用内的
浅色/深色主题（与操作系统解耦）。*
## 安装
[](https://apps.obtainium.imranr.dev/redirect?r=obtainium://add/https://github.com/PimpinPumpkin/Vela) [](FDROID.md)
点击徽章 —— 无需 Play Store，无需账号。Obtainium 会自动追踪
**每周稳定版**发布；开启“包含预发布版本”，您将获得
**每日构建版**频道（每次推送到 main 分支时更新）。F-Droid 徽章指向的是
**Vela 自己的仓库**，而不是 f-droid.org 目录 —— 将
`https://pimpinpumpkin.github.io/Vela/repo` 添加到任何 F-Droid 客户端中，它将提供
相同的已签名 APK，默认为每周稳定版（指纹和每日构建频道的
设置详见 [FDROID.md](FDROID.md))。或者直接从
[Releases](https://github.com/PimpinPumpkin/Vela/releases) 获取 APK。
## 功能特性
- **真正的分步导航。** 语音播报由完全在手机上运行的神经网络语音合成，包含车道图、出口盾牌、时速表、自动重新规划路线，以及当您的目的地在您到达后一小时内关闭时的提醒（通过卡片和语音播报）。
🔊 **听听 Vela 的导航语音** —— 默认语速下的实际应用内语音：
https://github.com/user-attachments/assets/17f246e4-51c8-4d01-998b-dcd7f29dc15f
- **在 Google 移动内容时自我修复。** 抓取规则存在于应用启动时检查的已签名
配置中 —— 当 Google 更改某个字段或接口时，修复程序会在几分钟内推送到每个安装中，无需更新。同一频道还可以
将提醒通知（“搜索功能已瘫痪，修复即将推出”）直接推送到地图上。
- **语音对话。** 点击麦克风并说出您的需求。Vela Voice 在手机上进行语音转录
（需一次性下载 58 MB），或者移交给您已有的语音输入应用。无论哪种方式，您说的话都不会发送到云端语音服务。
- **离线工作。** 下载一次州或国家，其地图、分步
路线规划以及其中的每个地点都可以在没有信号的情况下保持可搜索 —— 包括输入的街道
地址。
- **真实的地点信息。** 营业时间（包括节假日）、可搜索的评论、照片
图库、繁忙时段、电话和网站 —— 这些都是您开车去某地之前真正需要检查的内容，并在您到达时已经关闭的情况下发出警告。
- **可读的交通状况。** 路线选择会在绿色/琥珀色/红色的时间旁边用文字说明交通畅通、中度拥堵或严重拥堵，最快的路线排在列表首位。
- **实时油价。** 搜索加油站，每个加油站的当前价格都会直接
显示在地图标记上、结果列表中和地点页面上。
- **Material You 主题（如果需要）。** 一个可选开关使用您的壁纸颜色为 Vela 的界面着色（Android 12+）；默认关闭，且无论哪种方式，地图本身都保持整洁。
- **公共交通。** 包含路线胶囊标签、逐站停靠点以及
前往站台的逐步指引的行程。
- **无账号，无追踪。** 无 Google 账号，无 GMS，无遥测。Google 的服务器能看到和不能看到的内容在 [PRIVACY.md](PRIVACY.md) 中有明确记录。
- **其他功能。** Android Auto，15 种语言（包括希伯来语，这是第一个 RTL 语言），应用内浅色/深色主题，全 D-pad 操作
适用于按键手机，停车记忆，地点列表，以及内置更新程序（支持每周稳定版或每日构建版频道）。
完整的功能运行列表位于 [FEATURES.md](FEATURES.md)。
## 十秒了解日常功能
- **保存您的停车位**：停车时点击地图上的 **P** 按钮。稍后点击青色
图钉获取步行返回的路线，或者在您离开时点击图钉的清除按钮。
长按 **P** 查看您的停车历史记录，以防您不小心覆盖了某个地点。
- **列表**：类别标签旁边的书签按钮会打开 **您的列表**。
在此处创建一个列表，或从任何地点的页面添加（⋮ → 保存到列表），可以为每个
地点添加备注。列表可以在设置中备份到文件。
- **导入 Google Maps 列表**：将 `maps.app.goo.gl` 分享链接粘贴到
搜索栏中。该列表的地点将作为结果显示，并带有所有者的备注；点击
**保存列表**以保留本地副本。
## 为什么去 Google 化的应用要使用 Google
没有 Google Play Services 的手机无法运行 Google Maps，而且开放的地图
数据集在搜索、评论、营业时间和实时交通状况方面远远不够。因此 Vela 是
一个基于 Google 公开 Web 接口的轻量级客户端。它像未登录的浏览器一样向它们
发出请求，基于每个用户单独运行，没有账号，没有共享的 API key，也
没有中间服务器。NewPipe 对 YouTube 做的也是同样的事情。这里没有广告，您
的搜索、保存的地点和历史记录都保留在手机上。如果您运行 GrapheneOS
或其他无 GMS 的 ROM，这能让您重新使用可用的地图。
地图本身、街道、标签和房屋号码全部来自 OpenStreetMap。Google 仅用于地点、搜索、路线规划和交通状况。因此，街道名称和房屋号码可能与 Google Maps 显示的不同，您在离线状态下看到的细节程度取决于 OpenStreetMap 对您所在区域的覆盖程度。我正在寻找改进 OSM 并填补数据空白的方法。敬请期待。
## 隐私
**没有 Vela 后端，没有账号，也没有遥测**。Vela 直接从您的手机获取 Google
数据，就像未登录的浏览器一样 —— Google 能看到您的 IP、查询和
地图区域，但**看不到 Google 账号或任何应用 key**，这很像在
隐身窗口中使用 `google.com/maps`。您保存的地点、历史记录和设置
永远不会离开设备。**[阅读关于每个服务究竟接收什么数据的详细说明 → `PRIVACY.md`](PRIVACY.md)。**
简而言之：Google 从*知道您是谁以及您去过哪里*缩减为
*偶尔回答一个匿名问题*。而且对于驾驶来说最重要的部分 ——
您的 GPS 轨迹、您的地图浏览 —— 根本不会传到 Google。
| Google 获取的内容 | Google Maps 应用 | Google Maps 网页版 | Vela |
| --- | --- | --- | --- |
| 与您的 Google 账号绑定 | 是，始终登录 | 是，除非使用隐身模式 | 从不 —— 没有登录 |
| 持久性设备标识符 | 是（通过 Play Services 获取设备 ID 和广告 ID） | 浏览器 Cookie | 无账号，无应用 key；只有像任何网站访问者一样的 IP |
| 您的精确 GPS 位置 | 打开时持续获取，如果启用位置记录还会获取位置历史 | 选项卡打开时获取 | 从不发送。位置保留在手机上；搜索只发送您正在查看的地图区域 |
| 地图的每次平移和缩放 | 是 —— 他们的服务器渲染地图 | 是 | 否 —— 地图瓦片来自 OpenFreeMap，因此 Google 永远不会看到您的浏览 |
| 您的搜索 | 是，保存到您的账号历史记录 | 是 | 查询文本仅在您搜索时匿名到达 Google |
| 您打开的地点页面 | 是 | 是 | 地点查询匿名到达 Google |
| 分步导航路线 | 是，完整的行程遥测 | 是 | 路线在开放的 OSRM/GraphHopper 上运行；Google 只会看到一次匿名的 ETA 检查，永远不会看到您的实时位置 |
| 保存的地点、家、公司 | 存储在他们的服务器上 | 存储在他们的服务器上 | 仅存储在您的手机上 |
| 建立广告画像 | 填充您的广告画像 | 填充您的广告画像 | 没有任何可附加的内容 |
| 在完全不与 Google 交互的情况下工作 | 否 | 否 | 是 —— 下载的区域完全离线进行搜索、路线规划和导航 |
每次请求的完整详细信息请参见 [PRIVACY.md](PRIVACY.md)。
## 工作原理
每一项功能、其背后的无密钥方法以及建议首先阅读的文件都在
**[docs/HOW-IT-WORKS.md](docs/HOW-IT-WORKS.md)** 中进行了说明 —— 这是代码库的一屏索引
（底图、Google 抓取、开放路线规划、离线技术栈、远程自我修复等）。
更深入的内容见 [`SPEC.md`](SPEC.md)。
## 文档 —— 去哪查看
| 文件 | 包含的内容 |
|---|---|
| [`README.md`](README.md) | 本文件 —— Vela 是什么、为什么开发它、隐私比较以及构建/运行 |
| [`docs/HOW-IT-WORKS.md`](docs/HOW-IT-WORKS.md) | 每一项功能、其背后的无密钥方法，以及建议首先阅读的文件 |
| [`FEATURES.md`](FEATURES.md) | 所有已发布功能的完整分类列表（百科全书） |
| [`SPEC.md`](SPEC.md) | 权威的**重构规范** —— 架构、提取器契约（pb 布局 + 响应索引）、弹性层、硬性约束 |
| [`ROADMAP.md`](ROADMAP.md) | 计划的工作 + 大胆尝试（可选遥测、Vela 自有交通图层、超大国家图谱拆分等） |
| [`PRIVACY.md`](PRIVACY.md) | 每次 Google 接口请求具体接收了什么 |
| [`CLAUDE.md`](CLAUDE.md) | 构建规则、模块布局以及来之不易的坑点 —— 适用于贡献者（人类或 AI） |
| [`docs/dpad.md`](docs/dpad.md) | D-pad / 无触摸屏操作 —— 设计、发现、各界面审查以及与上游合并的策略 |
| [`docs/CALIBRATION.md`](docs/CALIBRATION.md) | 深入探讨 Google 提取器和已签名的远程修复通道 |
| [`docs/MAP-STYLE.md`](docs/MAP-STYLE.md) | 底图、字体、自定义图层和主题设置详情 |
## 架构
两个具有严格边界的 Gradle 模块（AGP 8.7.3、Kotlin 2.1、Compose、Hilt、
R8 发布构建）：**`:core`** 是采用
NewPipeExtractor 模式、与 UI 无关的“提取器” —— 包含模型、Google 抓取器和解析器、开放路由器、
纯导航引擎和远程配置层 —— 而 **`:app`** 是基于
MapLibre 的 Compose UI。`MapDataSource` 是它们之间的承重接缝：用于
离线开发的 Mock，今天的 Google，以及未来的 Overture/OSM 源或可自托管的
后端都以相同的方式插入。完整的模块树和每个接都在
[`SPEC.md`](SPEC.md) 中。
## 构建与运行
标准 Android 工具链：
```
# debug build（compile check / local install）
./gradlew :app:assembleDebug
# 真正的 distribution build - R8 + resource shrinking。
# 始终发布 release：在地图 scroll/nav 期间，debug builds 会出现明显的卡顿。
./gradlew :app:assembleRelease
# 针对纯逻辑（polyline codec、nav engine）的 unit tests
./gradlew :core:test
```
发布签名来自 CI 环境变量（`VELA_KEYSTORE_PATH`、
`VELA_KEYSTORE_PASSWORD`、`VELA_KEY_ALIAS`）；本地构建会回退到
debug keystore，因此 `adb install` 仍然可以工作。
**CI**：每次推送到 `main` 分支都会构建、测试并发布一个签名的 nightly
预发布版（`v0.4.标签：Jetpack Compose, MapLibre, 去谷歌化, 后台面板检测, 地图导航, 安卓应用, 矢量瓦片