local/pxa-apps 是工作区约定的应用仓库位置，对应公开仓库 SmartArduino/pxa-apps。这里维护应用源码和共享素材，可以用于体验 PXA、学习真实应用结构，以及作为开发新应用的参考。
1. 三个仓库如何配合
| 仓库 | 典型位置 | 主要内容 |
|---|---|---|
| pxa-workspace | 当前工作区根目录 | ESP 产品集成、板级驱动、开发与调试入口 |
| pxa-system | deps/pxa-system/ |
Host Core、SDK、运行时、打包器及最小 Hello |
| pxa-apps | local/pxa-apps/ |
商城、天气、游戏、实验应用和共享素材 |
工作区忽略 local/ 下的应用 checkout，但 local/pxa-apps 自己是独立 Git 仓库。修改其中源码，应在应用仓库里查看 diff、提交和推送；这些修改不会作为 App 文件出现在工作区的提交中。
2. 获取仓库
先完成环境与源码准备。在 PXA 工作区根目录执行：
mkdir -p local
git clone https://github.com/SmartArduino/pxa-apps.git local/pxa-apps
如果目录已经存在，不要再次 clone 或覆盖，先确认远端与本地改动：
git -C local/pxa-apps remote -v
git -C local/pxa-apps status --short
git -C local/pxa-apps log -1 --oneline
确认自己的修改已经妥善保存后，再用 git -C local/pxa-apps pull --ff-only 更新。应用会随着 SDK 演进，应记录工作区、系统与应用仓库各自的提交号，确保使用匹配版本。
3. 自动发现，无需逐个填路径
工作区工具会检查 local/pxa-apps/<源码目录名>/package.json。没有更高优先级的源码配置时，下面的命令可以直接使用：
tools/app.sh build arcade --target simulator
tools/dev.sh sim arcade --watch
tools/dev.sh sim arcade --profile sensecap-watcher --watch
因此，放在约定位置的应用通常不需要再写 local/apps.toml。把仓库放在其他位置时，再按apps.toml 教程逐应用登记父目录。
[apps.arcade]
source_root = "/home/me/projects/pxa-apps"
[apps.store]
source_root = "/home/me/projects/pxa-apps"
如果已有 catalog 把 arcade 指到了其他 checkout，catalog 会优先于自动发现。要明确使用这份仓库，可临时传入 --source-root local/pxa-apps。
4. 从哪个应用开始阅读
以下是当前 checkout 中具有代表性的应用；完整清单以各目录的 package.json 为准。
| 源码目录 | 内容 | 适合学习 |
|---|---|---|
arcade |
小型街机游戏集合 | 多源文件组织、UI Canvas、时钟与输入、可选音频权限 |
store |
PXA 应用商城客户端 | 目录浏览、网络权限、窗口布局与 Host 管理的安装流程 |
weather |
天气、城市搜索与预报 | 异步网络、失败回退、持久化城市选择、系统输入法 |
lab |
ABI 交互诊断工具 | 设备、时钟、存储、私有文件与内存行为 |
wasi-lab |
WASI 示例 | libc、时钟与随机数等能力 |
abi-v1-smoke、abi-v1-ipc-smoke |
Core v1 / 多组件诊断 | 导入接口、签名组件与 IPC 联调 |
game-render-bench |
2D / 3D 分阶段基准 | Raster 服务和渲染性能诊断 |
pixel-dungeon |
回合制地牢游戏 | GameRender、资源生成、音频、可变显示布局 |
jump-jump-3d、tomb-explorer |
3D 交互应用 | 输入映射、相机与几何绘制 |
garden-guard、plane-shooter、voxel-craft |
游戏与沙盒应用 | 场景状态、素材与复杂交互组织 |
刚接触 SDK 时，先完成 pxa-system 中的 Hello 教程，再阅读 arcade 或 weather。大型游戏和 benchmark 对渲染服务、内存与资源准备要求更高，不适合作为验证工具链是否安装正确的第一步。
仓库中部分应用清单已声明 Core SDK [1,0]，而最小 Hello 等示例可能采用其他版本。不要把文档页中的“开发版”标签或旧示例数值当成所有应用的兼容性要求；构建与运行以当前 App manifest、SDK 和 Host 实际支持的版本为准。
开源应用运行截图
下面是 local/pxa-apps/voxel-craft 的桌面包在 412×412 矩形窗口中的实际运行画面，通过 PXADB 读取屏幕帧。这组截图未启用 Watcher 的圆屏裁切；画面中的帧率只是本次桌面运行的瞬时值。
启动菜单：NEW GAME 创建世界，LOAD SAVE 读取存档，SETTINGS 进入设置。 点击图片查看原图。
进入 NEW GAME 后的游戏画面，可结合源码阅读场景渲染、物品栏与触控输入。 点击图片查看原图。
本地体验：
tools/app.sh build voxel-craft --target simulator
tools/dev.sh sim voxel-craft --profile pai-touch --watch
以上命令使用 Pai Touch 的 296×240 外形。若要复现图中的 412×412 矩形窗口，按 Profile 教程创建宽高为 412、round=false 的配置，再用 --profile 选择它。
5. 完整运行一个示例
以 arcade 为例，从工作区根目录构建后安装到模拟器：
tools/app.sh build arcade --target simulator
tools/simulator.sh service start --profile pai-touch
pxadb package install local/app-output/pai-touch/pxa-arcade.pxa --simulator pai-touch
pxadb package run pxa-arcade --simulator pai-touch
运行命令会占用当前终端，查看截图或管理包时另开一个终端。想改用标准 UI 启动时，先退出当前 product 窗口，再运行：
tools/simulator.sh ui --profile pai-touch --app-root local/pxa-apps
--app-root 用于生成源码 manifest 目录，不负责构建或安装所有应用。若只有卡片而没有对应 Guest 行为，先按前面的命令构建并安装该应用。
对比不同屏幕时，运行 tools/dev.sh sim arcade --profile esp32s31-korvo-1 --watch 可以使用 800×480 外形；此命令仍运行桌面制品。Profile 与芯片目标的区别见多设备模拟。
6. 商城与天气示例的额外条件
商城 store
tools/app.sh build store --target simulator
tools/dev.sh sim store --watch
商城需要 Host 提供网络、权限和 store-installer 等服务，以及可用的目标设备目录。桌面页面能运行，不代表全部真机安装能力或所有服务器 Profile 都已支持；网络错误、无兼容制品和缺少服务应分别排查。
自建商城还要同步调整应用声明的网络 origin scope 与服务端配置。它们属于已签名清单的一部分，不应只改一个 URL 字符串而忽略权限范围。
天气 weather
当前 weather/README.md 描述的是 IP 位置估计、Open-Meteo 及回退服务，当前实现不要求在 App 中嵌入 API key。仓库根 README 中仍有旧 weather_config.h 说明；使用时优先核对应用自己的 README、源码与当前版本，不能直接照搬旧密钥配置。
城市输入需要系统输入法。测试完整输入流程时，先安装应用，再从标准 UI 进入：
tools/app.sh build weather --target simulator
tools/simulator.sh service start --profile pai-touch
pxadb package install local/app-output/pai-touch/pxa-weather.pxa --simulator pai-touch
tools/simulator.sh ui --profile pai-touch --app-root local/pxa-apps
从启动器选择已安装的 Weather。单独 product 模式不承载完整系统输入法，不能据此认定 App 的文本输入有问题。联网时需要目标域名权限；位置结果是 IP 估计，不是 GPS 测量。
7. 素材与构建准备
典型 App 目录包含 package.json、C 源码、assets/、i18n/，较复杂应用还包含模块、测试和生成工具。仓库另有 common/art/ 等共享素材目录；不要假定复制一个 main.c 就能重建整个 App。
例如 Pixel Dungeon 的 README 说明了上游素材获取、图像 / 音频 / 文本生成、桌面音乐和 ESP32-S3 音乐制品准备。先在应用目录阅读并运行相应准备工具，再回到工作区根目录执行 tools/app.sh。
App 目录中的 README、LICENSE 和素材来源说明应一起阅读；不同应用和第三方资源可能有不同许可，不能把所有公开源码和素材一概当作同一种授权。保留应用要求的许可证、来源标注和资源声明。
8. 参考示例开发自己的应用
- 先构建并运行未修改示例，确认基线。
- 在独立应用仓库或自己的分支中复制完整应用结构，保留所需资源和生成流程。
- 给新应用使用自己的目录名、
pxa-<目录名>ID、名称、版本和图标。 - 按实际需要调整 Service 与权限，删除不再需要的网络访问或资源。
- 用
local/apps.toml登记新仓库路径，进入 watch 循环。 - 在不同 Profile 与真实设备上检查交互、内存、退出和更新。
- 使用自己的发布密钥打包，再按商城上架教程发布。
源码中已有的发布者开发夹具用于测试，不能用作自己的正式发布身份。正式包需要可追溯的源码、素材、SDK 版本与签名配置。
9. 与系统 SDK 同步升级
遇到缺少头文件、导入函数、Service feature 或 ABI 不匹配，先检查三个仓库的版本关系。不要只降低 min_sdk 或删除清单里的服务要求来绕过检查，这并不会为旧 Host 增加新能力。
git rev-parse --short HEAD
git -C deps/pxa-system rev-parse --short HEAD
git -C local/pxa-apps rev-parse --short HEAD
保存这三个提交号、App manifest 和构建错误，即可让问题报告更容易复现。应用改动查看 git -C local/pxa-apps diff；硬件和工具改动查看工作区 diff，两者分别维护。