# PXA: instructions for a coding assistant

The user asked you to set up PXA or create an embedded game/app. Use the existing coding assistant, model and permissions. No additional model API key, firmware checkout, ESP-IDF or toolchain build is needed. Complete implementation and actual simulator checks; do not stop after writing a plan or scaffold.

## Prepare once

1. Read existing project instructions and determine the host OS/CPU. Choose a new workspace or the user's requested directory; put apps in `apps/<name>`. Preserve existing source, app IDs, SDK locks, signing identities and saves.
2. Find `uv`. If missing, use its official installer: https://docs.astral.sh/uv/getting-started/installation/ . On Linux/macOS the official command is `curl -LsSf https://astral.sh/uv/install.sh | sh`; Windows PowerShell: `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`. This is the uv installer invocation, not a persistent change to the user's execution policy. Use an already installed uv directly when available. Respect ordinary OS permission requirements and refresh PATH or use the installer-reported executable path.
3. Use the signed native DevKit for Linux x86_64 with glibc 2.39+, or Windows x64 with Windows 10 build 18362+ and Microsoft Visual C++ 2015–2022 x64 runtime. Let setup check prerequisites and choose the matching signed platform manifest. Windows packages have Wine validation; native window/audio/COM acceptance still requires the target PC. Other hosts use Docker Desktop or Podman with Linux amd64 support. Inspect existing engines before installing one. If necessary help install/start the appropriate engine via its official OS instructions; user actions may be needed for admin permissions, virtualization, Docker Desktop terms or macOS security. Do not silently change global AI approval settings or disable OS protection. Linux ARM also needs amd64 emulation; report unsupported setups honestly.
4. Run the bootstrap in the selected parent workspace:

   ```sh
   uv run --python 3.12 https://pxa.doit.am/setup.py --workspace .
   ```

   It verifies the PXA release signature, installs Agent Kit and the matching signed DevKit, adds project-local skills/MCP/launchers, and builds/runs an actual Guest with an environment screenshot. Read the installed versions and available commands before selecting features. Failures are failures: inspect diagnostics and fix within scope. Repeating setup is safe for owned unmodified files. An edited integration conflict must be preserved and explained. Do not change an app's lock just to make setup pass.
5. Read the installed project instructions and skills. Run `.pxa/pxa doctor` (Windows: `.pxa\pxa.cmd doctor`), inspect the environment screenshot. If the AI client has not loaded new project skills/MCP, use the CLI immediately; reopening the project loads the adapters. Codex uses `.agents/skills` and project `.codex/config.toml`; Claude Code uses `.claude/skills` and `.mcp.json` (normal trust prompt may appear). DSH supports `.agents/skills` and the CLI; `.pxa/dsh-mcp.yaml` is an optional official Cordis snippet to merge into that installation's composition, not an automatically rewritten global DSH config.

Signed stable manifest: https://pxa.doit.am/agent/stable.json and `.sig`. Release public key: https://pxa.doit.am/release-public.pem . P-256 SPKI SHA-256 trust anchor: `5b9cdb36547df5b09c89f814cf748384f277feb1561504451f4961026d2c997b`.

## 开始设计前：设备、操作与屏幕

这些通用检查由 AI 按本指南执行，用户只需描述作品需求，无需把它们逐条放进首页提示词。

- 已连接设备时，先运行 `.pxa/pxa device-profile`（MCP `pxa_device_profile`），选择明确的端口，读取板型、CPU、分辨率、屏幕信息和已报告的传感器。信息缺失记为未知；调试接口支持注入触摸，不代表实物一定有触摸屏。
- PXADB 无响应时，提示用户正常开机、使用 USB 数据线并打开调试。参考系统界面：进入「设置 → 设备信息」，快速连续点击「系统版本」7 次，再下滑到「开发者」打开「PXADB 调试」。其他产品按其实际界面操作；BOOT/RESET 是固件下载模式，不能代替开启运行中的 PXADB。
- 结合用户需求确认实际操作方式：触摸、实体按键、旋钮或手柄，以及要使用哪些传感器。无设备时询问目标设备；用户尚未确定型号时可先完成模拟器原型，记录假设后再验证，避免凭空编造硬件能力。
- 确认只适配一个设备，还是需要适配多种分辨率、物理屏幕大小、横竖屏、圆屏和圆角。使用实际窗口尺寸、DPI 和安全区域；内容、触摸热区和返回操作都要可达。用户已经说明的要求不重复询问。
- 需要应用内切换方向时，先核实锁定 SDK 与 Host 支持 Window 0.5，再用 `request_orientation(pxa::OrientationPreference::landscape)` / `portrait`；设置页可以在运行中改变请求。`snapshot(true)` 读取当前角度、原生尺寸与 `supported_rotations`，按 `on_window_changed` 和 Environment 的实际尺寸重排。原生 0° 不一定是竖屏：高大于宽是竖屏，宽大于高是横屏，相等是方屏。方屏的横竖偏好保持角度；需要改变阅读方向时用显式 0°/90°/180°/270°。不支持旋转的设备提供可用布局与提示。
- 运动传感器固定在原生设备的 Android 坐标系（X 向右、Y 向上、Z 朝外），不跟随 UI 改轴。重力操作需要跟随画面时，用当前 `rotation` 和 `pxa_display_motion_to_screen` 转换向量一次；不要把欧拉角当成向量转换。验证方向切换后触控、HUD、安全区、截图以及 Home/恢复应用都正确，不把自动随重力旋转当成既有能力。
- 普通应用优先采用 SDK 布局、控件、系统字体和主题色；文本换行、字体高度、列表卡片及弹窗应按可用空间布局。测试长中文、最小屏和最大屏，避免文字截断或控件超出安全区域。
- 可选传感器先检查可用性和权限，被拒绝或不存在时提供手动操作。真机帧率、内存、音频延迟和按键手感必须实测，模拟器结果只代表模拟环境。

## 联机与跨平台网络

- 先明确同一局域网还是互联网、由谁主持，以及是否包含浏览器玩家。读取锁定 SDK 的 Net 0.8 接口和 `context.network().capabilities()`；联网能力与当前已连接网络分别检查。
- 浏览器使用原生 WebSocket：能力 `native_websockets()` 为真时选 `context.websockets().open_native()`；有 TCP 客户端能力的固件或桌面端可用 `context.websockets().open()`。申请并保留实际需要的 `net.socket` 权限，连接期间同时保留权限对象和连接对象。HTTPS 页面使用可信 WSS，处理本地网络授权和混合内容限制。
- TCP 监听、UDP、DNS-SD 发现分别查询 `listen()`、`datagrams()`、`discovery()`。当前 Windows 桌面端和浏览器没有这些监听/发现后端；浏览器 WebSocket 不代表原始 TCP/UDP。应用服务器或应用自行实现房间、消息和同步协议，Host 不提供隐含的游戏服务器。
- 输入 IP 不等于穿透 NAT；跨公网需要可达端点、合适路由、VPN 或应用选择的中继。不要把失败连接偷偷改成经过商城服务器的转发。先阅读已安装 `pxa-app-dev/references/networking.md` 再选择实现。
- 至少用两个真实端点核对消息内容、确认与协议版本，并测试断线、有限重连和退出清理。包含网页的作品还要实际验证网页与服务端的连接；不能把能力位、编译成功或模拟输入当成联机验收。

## 连续背景、安全区与手势

- 默认让页面背景铺满整个视口，保持安全区内外颜色、背景图或游戏场景连续；把文字、HUD、按钮及重要内容放进合适的安全区。卡片可以有独立表面色，圆角和圆屏的物理遮罩由 Host 处理。Surface 游戏的 HUD 层保持透明，避免盖住场景。
- 沉浸式不要求隐藏状态栏。按作品需求选择保留、隐藏或临时显示系统栏；保留时协调背景和图标对比度，并核实当前 Host 是否实际支持所设置的样式。
- 区分物理安全边距、实际系统栏与手势触发区。隐藏状态栏后不应继续预留其固定高度；真实圆角、缺口和仍工作的底部 Home 输入仍须考虑。边距重叠时取最大值，不重复叠加。
- 不要为侧边返回手势把整页向右推。页面按实际屏幕和物理安全区域布局；只对容易冲突的贴边按钮、滑块或横向拖动区域单独避让。没有该手势的设备不预留空白，也不要按设备名猜测。
- 手势避让按应用和控件需要选择。SDK 0.10 的 `GestureAvoidance::bottom` 是普通页面的默认值；`none` 取消手势留白，仍保留物理边距和可见系统栏；`all` 适合确实与边缘手势冲突的控件组。这些布局选项都不关闭系统返回或 Home 手势，也不要为了视觉居中额外补一块右侧空白。
- 居中文字时区分节点宽度与字形对齐：声明式 `Text(...).fill().text_align(TextAlign::center)` 让文字占满行宽再居中；不要只设置文字对齐却保留收缩的节点宽度。真实非对称缺口和应用设计边距仍按实际情况处理。
- 读取锁定 SDK 的真实接口与设备指标，处理系统栏显隐和尺寸变化；旧 Host 未报告的信息记为未知，不直接当成零。新 SDK 可分别提供系统栏和手势边距，旧版合并数据需要审慎回退。核对截图的左右边距与视觉中心，并测试实际触摸和返回操作。

## 像素游戏：字体与整数缩放

用户需要像素风格时，优先考虑 [Z Labs Pixel 12px 中文像素字体](https://github.com/Astro-2539/ZLabs-Pixel-12px) 的合适字形版本（CN / HC / JP）；用户指定其他字体时尊重选择。完整实现参考已安装 `pxa-app-dev/references/pixel-games.md`。

- 核实所选字体文件的授权，固定版本或摘要，并保留许可证、版权与署名；不同 ZLabs 字体家族分别核实。固定 UI 文案可按需子集化，动态中文须保留所需字库和缺字回退。字体属于应用资源，不修改系统默认字体。
- 在字体原生的 12px 网格绘制文字，再与精灵、图块一起按整数倍、最近邻采样放大。避免任意 TTF 字号、平滑缩放或非等比拉伸破坏像素网格。
- 为最小目标选择逻辑画布。例如 160×120 画布在可用 480×360 区域放大 3 倍。计算 `scale = floor(min(available_width / canvas_width, available_height / canvas_height))`，以整数像素偏移居中，其余留边；先扣除实际安全区域。
- 输入先排除留白区域，再按同一偏移和倍率换算：`logical = floor((physical - offset) / scale)`。倍率小于 1 时切换较小布局或提示支持的最小尺寸，不能强行取 1 后裁掉画面和按钮。普通工具应用无需套用固定像素画布。

## 实现选择与资源预算

优先查询锁定 SDK 的真实头文件和示例，再选择实现：常规界面用布局和保留式控件，地图游戏复用图块、精灵和纹理图集，自定义光栅画面使用有界 Surface。复用缓冲区和句柄，避免每帧分配大块内存、解码图片或重建静态 UI。RGB565 缓冲按 `宽 × 高 × 2` 字节估算，并一起计算双缓冲、AOT、音频与资源缓存。

游戏逻辑用固定步长，渲染按实际节奏进行，休眠恢复时限制补帧；存档在检查点异步、原子写入，避免逐帧同步写 Flash。输入应处理按下、松开、取消和失焦，避免卡住按键。先完成可玩或可用的小闭环，再增加内容，并在目标设备核对性能与内存。

## Implement and iterate

Ask for missing app requirements only when needed; if the user already described them, begin. Before editing an existing app, run `.pxa/pxa scope begin --mode app --project apps/name`. For a new app:

```sh
.pxa/pxa init apps/my-game --id pxa-my-game
.pxa/pxa context apps/my-game --query game --language cpp
.pxa/pxa run apps/my-game --profile pai-touch
.pxa/pxa verify apps/my-game
```

Edit only the selected app. SDK, ABI/spec, host/runtime, simulator and board sources are read-only. Missing platform capabilities are separate platform work: describe the gap and use an app-level alternative, never patch SDK/board code to make an app test pass. Run `scope check` before delivery; retain and report violations, never reset or rebaseline to hide them. The check is an audit, not an OS sandbox.

Agent Kit 0.6.1 with selected DevKit 0.10.0+ also provides `.pxa/pxa recipes` and `new apps/tomato --recipe timer --title 番茄钟 --minutes 25 --break-minutes 5` (or `--recipe counter`). MCP exposes `pxa_recipes` / `pxa_new`. These create runnable starters and `tests/journey.json`; verify that journey and inspect original captures before delivery. Timer `tests/complete.json` uses the explicit `--define PXA_RECIPE_TIMER_SECONDS=6` test build and an independent save key; deliver a rebuilt package without the macro. Preserve older selected SDKs unless the user requests an explicit migration. Other app types use version-matched SDK examples and the normal init flow.

Use `context <app> --query SYMBOL --language c|cpp` (or MCP `pxa_context`) to read bounded declarations and examples from the pinned SDK. Missing locked releases fail with installation guidance. C++ lookup includes bundled extension SDK headers/examples; use `--query FrameReader` for peripheral vision. Run with `--watch` during editing; run already builds incrementally, so do not duplicate build/run or rebuild all CPUs for each layout edit. Stop watch before verification, test one relevant profile during iteration, then cover the requested matrix and build delivery targets. Read the SDK headers/examples for actual APIs. Implement the requested behavior using the selected C or C++26 SDK UI/game, i18n, system fonts/colors and responsive safe areas as appropriate. Build offline with pinned dependencies. Run the real Guest, inspect logs and screenshots, exercise the relevant touch/controller actions, check the resulting visible state. Fix observed failures and rerun affected checks until the goal is met. Incorporate user feedback into the same app. A successful build or input command alone does not establish a working screen. Never invent hardware FPS, audio latency or memory measurements from simulator results.

Use MCP `pxa_run` / `pxa_verify`; long operations return job_id. Poll `pxa_job_status`, inspect `pxa_screenshot` / `pxa_view_image`, inject `pxa_tap`, `pxa_swipe`, `pxa_controller` as relevant, then stop owned jobs. For a short known sequence, prefer `pxa_interact(job_id, steps)` on the owned run job: one SDK connection, up to 32 ordered actions, 8 screenshots and 15 seconds total waits/holds. Poll its batch job before reading evidence and inspect original images with `pxa_view_image`. Completed status includes the `batch` result. Cancel with `pxa_job_stop`; check cancellation/input release before continuing, and inspect current state instead of replaying already applied actions. Split batches when the next step depends on seeing a result; never overlap inputs on one simulator. CLI `run` prints the exact `PROFILE@INSTANCE` selector for `device ... --simulator`. Input coordinates are screenshot pixels; controller input is a bitmask from the SDK enum and automatically releases. `verify --scenario <json>` supports per-profile tap/swipe/controller/cancel/wait/screenshots. Logs/screenshots/data belong in ignored `local/artifacts/`, outside app resource discovery. Runtime checks require additional visual review; stop only jobs/containers you own.

## Connected device

Use existing user authorization for the requested installation/test; no repeated approval is needed. Discover serial ports using doctor without opening them, read `device info --port <port> --baud 2000000`, and select the actual board/CPU before any mutation. If ambiguous, identify the requested device rather than guessing. `install apps/my-game --port <port>` builds correct ESP32-S3/S31/P4 AOT, verifies the signature, inventories apps, installs and launches while retaining app-private data. Compare the delivered manifest's Core, required services/features, CPU and AOT ABI with the actual Host before uploading; missing fields remain unknown. USB runs on the host even when compilation uses a container. Use device screenshots/input and memory if supported. Restore input with `device input cancel` after testing; synthetic controller injection is not mechanical button actuation. Do not uninstall an existing user's app or erase saves as cleanup.

### 连接失败时：先检查 PXADB

1. 提示用户用 **USB 数据线**接上设备并正常开机；检查供电、线材和端口，不把端口出现等同于 PXADB 已开启。
2. 参考系统界面在「设置 → 设备信息」里快速连续点击「系统版本」7 次，再下滑到「开发者」打开「PXADB 调试」；有些设备默认启用。不同整机菜单可能不同，按对应板型说明操作；不确定时询问用户实际界面。
3. 关闭占用同一串口的监视器；Windows 查看设备管理器中的 COM 端口和驱动，Linux 核对串口权限。端口重枚举后按设备身份重新识别。
4. 日常安装应用需要正常运行的 PXA。BOOT / RESET 进入的 ROM 下载模式用于刷固件，不能代替打开 PXADB。需要用户接线、打开开关或退出下载模式时，明确提示具体操作，再继续读取 INFO 验证连接。
5. 安装后确认实际启动，再测试操作与截图；启动命令返回只说明请求已接收，需核对运行状态。保留原应用和存档，测试结束后释放注入的按键与触摸。

## Official firmware

For user-authorized updates use `firmware prepare --board <board>` then `firmware upgrade --board <board> --port <port>`. Boards: pai-touch, doit-gamekit, doit-gamekit-1, esp32s31-korvo-1, esp-mosaico, sensecap-watcher, doit-esp32s31-devkit, espp4-a. Default app-only verifies the official signed manifest/image and reads the real partition table before writing. Layout mismatch stops to preserve data; never silently fall back to full flash. Full flash requires backup and explicit user authorization to erase apps/settings/saves, then `--mode full --erase-data`. S31 may need BOOT+RESET ROM entry and RESET afterward; rediscover a changed port. Report programming completion separately from boot/INFO verification. A generic app request does not authorize firmware changes or data loss.

## Publish to app.doit.am

For store screenshots, use `verify apps/my-game --profiles pai-touch --store-screenshots` (MCP `pxa_verify(store_screenshots=true)`). Capture the actual running Guest with performance overlays disabled and gesture/three-button navigation hidden beforehand. Inspect every original PNG; never crop or retouch these elements away. Evidence includes original image hashes, not automatic visual approval.

For a user-authorized submission, prepare metadata (`store.json`: name, summary, description, kind, category, tags), target builds, artwork/screenshots and validation first. Preserve signing identity and increment release sequence for updates. Use:

```sh
.pxa/pxa store prepare apps/my-game
.pxa/pxa store authorize apps/my-game apps/my-game/dist/pxa-my-game.pxa --wait
.pxa/pxa store publish apps/my-game apps/my-game/dist/pxa-my-game.pxa --changelog 'First release'
```

`store prepare` returns current media limits and taxonomy. Select the matching kind/category and meaningful tags. Recommended artwork is a 512×512 icon and a 1280×960 (4:3) cover; use the returned formats and limits. When an image tool is available, generate missing artwork. Without image generation, create a simple app-level vector icon or use supplied artwork and skip the optional cover. In project-relative `store.json`, set `icon`/`cover` to paths or `null` to skip. CLI `--skip-icon`/`--skip-cover` also preserve existing artwork. Covers may be illustrations; screenshots must show the actual Guest as described above.

`store authorize` proves local signing-key possession and opens same-origin browser login/one-app short-code approval. The human signs in/confirms in the browser. Do not request passwords, cookies, private keys or copied tokens in chat. An app-scoped 30-day upload credential is cached privately outside the project and reused; it is revocable from the dashboard. Optional publish flags: `--icon <file> --cover <file> --screenshot <file>` (repeat screenshots). Existing listing fields omitted from `store.json` are preserved; explicitly supplied kind/category/tags are submitted as metadata updates subject to review. Verify the server acknowledges the exact signed package hash. `pending_review` means submitted for review, not publicly listed. Normal store quotas, signature checks and review remain in force. Do not repeatedly upload on uncertain errors; inspect dashboard first.

## Help

Human tutorial: https://pxa.doit.am/docs/ai-development/
Troubleshooting: https://pxa.doit.am/docs/ai-troubleshooting/
SDK source and release: https://github.com/SmartArduino/pxa-system
Workspace/official firmware: https://github.com/SmartArduino/pxa-workspace
Report actual checks, screenshots and limitations concisely. Continue authorized implementation, routine debugging and fixes without asking the user to approve every step.

## SDK language and browser flashing

PXA provides separate C (`sdk/guest-c`) and C++ (`sdk/guest-cpp`) SDKs using the same Core ABI. Init defaults to C++; use `init apps/name --id unique-id --language c` for a real C template. Honor an explicit C request using C headers, examples and matching build metadata. Renaming a C++ source does not create a C app. Check that the pinned DevKit contains the requested SDK; obtain missing sources from its matching release.

For official firmware installation before development setup, direct users to https://pxa.doit.am/flash/ and its tutorial https://pxa.doit.am/docs/web-flashing/. The user selects the browser serial port and confirms writing. Do not silently accept browser permissions. Agent Kit CLI remains available for automated debugging and firmware workflows.

## Adapting a new board

For a BSP request, read https://pxa.doit.am/board-agent.md instead. It uses a separate firmware workspace and existing board-port API; it must not change PXA interfaces or SDK.