AI 工具与环境参考

先选择你的路线

第一次使用，请先看 一句话制作游戏和应用。本页整理语言选择、环境要求、命令行、MCP、设备调试和发布细节，需要时再查。

C 或 C++，都可以

PXA 提供独立的 C SDK 和 C++ SDK，使用相同 Core ABI 和系统服务。创建模板默认 C++；也可以直接用 init apps/demo --id pxa-demo --language c 生成 C 项目，包含对应头文件和 CMake 构建方式。见 SDK 指南。

更高效，也有明确边界

应用任务只修改选定应用；SDK、PXA 接口、运行时、模拟器和板子源码作为只读参考。缺失的平台能力应单独说明，不能为了让应用通过测试而修改平台。

.pxa/pxa scope begin --mode app --project apps/demo
.pxa/pxa context apps/demo --query ui --language cpp
.pxa/pxa build apps/demo
.pxa/pxa verify apps/demo --profiles pai-touch
.pxa/pxa scope check

新建应用会自动开始边界记录。context 只返回匹配的头文件片段、行号和示例，减少上下文占用。日常迭代保留 SDK 锁和增量缓存，先测相关屏幕；交付前再覆盖要求的设备布局。场景脚本支持触摸、手柄、等待、截图，手柄步骤会自动松键。完成任务后可用 scope end 归档通过的检查。

边界检查保留原有脏文件，以开始时的状态比较后续修改；Git 工作区检查受版本控制及非忽略文件，独立 SDK 检查源码与开发工具。它不替代文件系统沙箱。发现越界时停止后续构建或验收，列出改动，不擅自清除或重新记录基线掩盖问题。

适配硬件走独立的 AI 新板适配流程，可编辑本板 BSP、Profile 与自动生成的本板依赖锁，仍保持 SDK、ABI 与共享代码只读。

第一次配置环境

AI 会检查电脑系统、安装轻量的 uv 工具，再下载并校验官方 PXA Agent Kit、DevKit、编译工具和模拟器。准备完成后会真正编译并运行一个应用，生成截图；失败会继续诊断，不会只告诉你“依赖已安装”。首次需要联网下载，后续可离线编译。

你不需要手动配置 ESP-IDF、LLVM、CMake、WASI 或交叉编译器。当前稳定 DevKit 为 0.10.0，独立 AI 工具为 0.6.1。

已有容器引擎会复用；没有则 AI 帮你按操作系统安装/启动。首次系统安装、开启虚拟化、Docker Desktop 条款、AI 客户端登录可能需要你操作一次。工具不会绕过系统权限，也不会替你输入账号密码。容器内可截图调试，原生开发包可提供窗口显示；Windows 的窗口、音频与 COM 仍需目标电脑验证。

喜欢自己执行命令的话，先安装 uv，然后只需：

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

支持哪些 AI 平台

不修改全局模型、权限或其他 MCP。新配置未立即出现时重新打开工作区；CLI 可立即使用，不需要等 MCP 生效。DSH 不同安装方式的全局 composition 不同，所以工具提供 .pxa/dsh-mcp.yaml 片段，由 AI 按现有配置合并，不擅自覆盖整个配置。

让 AI 自动调试，再按反馈修改

告诉 AI 你的目标和完成条件。它会按“实现 → 编译 → 真实模拟器运行 → 操作 → 查看截图 → 修复”推进。多屏检查包括竖屏、横屏、圆屏、高 DPI 与小屏。适配不是只把截图拉伸，而是按系统安全区和实际可用空间布局。

反馈直接接着说：

按钮再大一些，配色跟随系统。手柄按 B 返回时保留倒计时，再验证一次。

会继续修改原应用，保留应用 ID、签名身份、SDK 锁和存档。截图、日志放在被忽略的 local/artifacts/，应用源码在 apps/<应用名>。自动检查通过后，AI 还需要看实际画面；模拟器运行成功不代表所有真机都已验证。

常用命令（在工作区目录，Windows 用 .pxa\pxa.cmd 替代 .pxa/pxa）：

.pxa/pxa doctor
.pxa/pxa recipes
.pxa/pxa new apps/counter --recipe counter --title 计数器
.pxa/pxa run apps/counter --profile pai-touch --watch

new 从可运行配方创建应用；目前提供计数器和番茄钟，要求选中的 DevKit 为 0.10.0 或更新。已有目录不会被覆盖，旧项目也不会自动迁移。其他应用或游戏可以使用 init，再通过 context 查找锁定 SDK 的对应示例。

run 已包含增量构建，保存代码即可重启。先按 Ctrl+C 停止 watch，再验证生成的用户操作流程：

.pxa/pxa verify apps/counter --profiles pai-touch espp4-a --scenario apps/counter/tests/journey.json --require-ui --jobs 2
# 源码、依赖、SDK、测试宏、签名和包都未改变时，受校验地复用构建
.pxa/pxa verify apps/counter --profiles pai-touch espp4-a --scenario apps/counter/tests/journey.json --require-ui --jobs 2 --no-build

场景按真实按钮文字定位并点击，再等待计数显示由 0 变为 1；不依赖某块屏幕的固定坐标。--require-ui 检查真实保留式节点树；纯 Surface 游戏通过画面和行为验证。结果会记录步骤耗时、错误和原始截图，contact-sheet.png 方便比较多屏，但不能作为商城截图。检查原图后才判断布局是否正确。修改源码后不能继续复用过期包。

番茄钟可以直接创建并测试开始、暂停、重置和专注/短休：

.pxa/pxa new apps/tomato --recipe timer --title 番茄钟 --minutes 25 --break-minutes 5
.pxa/pxa verify apps/tomato --scenario apps/tomato/tests/journey.json --require-ui
# 用独立测试存档快速验证倒计时完成
.pxa/pxa verify apps/tomato --profiles pai-touch --define PXA_RECIPE_TIMER_SECONDS=6 --scenario apps/tomato/tests/complete.json --require-ui

交付前重新构建不带测试宏的包。配方使用单调时间和异步检查点，重新打开按最近已保存的进度暂停恢复，不是关机后仍运行的闹钟。日常只测相关屏幕，交付时再覆盖用户要求的分辨率与操作方式。

MCP 工具可直接返回截图给 AI。对已经确认位置的一组操作，pxa_interact 会复用同一个模拟器连接，依次执行点击、滑动、手柄和截图，减少重复启动开销。每批最多 32 步、8 张截图和累计 15 秒等待/按住；等批次任务结束后检查原图。下一步依赖画面时先停下来观察，不对同一个模拟器并发输入。任务状态会直接附带批次结果；可以随时让 AI 停止该批次，工具会取消实际执行并松键，正常取消后模拟器仍可继续调试。继续前先看当前画面，不把已执行的点击整批重放。命令行可用 verify --scenario。编译、验证和刷机等长操作返回任务编号，AI 查询状态后继续处理，不依赖一次调用一直等待。结束时清理自己启动的模拟器和容器。

多目标交付只启动一次构建：CLI 使用 --target esp32s3,esp32s31,esp32p4,simulator,wasm；MCP 调用 pxa_build 时传入 targets: ["esp32s3", "esp32s31", "esp32p4", "simulator", "wasm"]。工具复用公共 Wasm 编译与增量缓存。日常迭代保留默认 simulator 即可，避免每次都生成所有设备版本。

查询任务进度时，pxa_job_status 使用 include_log: false；失败或需要诊断时再读取日志。已完成任务的耗时保持固定，重复查询不会重新运行任务。模拟器任务仍会返回连接入口，便于继续操作。

接上设备，安装与实机调试

Agent Kit、项目 DevKit、设备固件和应用版本分别编号。安装先核对实际包的 Core、服务、功能位、CPU/AOT 与容器需求；发行号不同不一定不兼容，发行号相同也不能代替能力检查。device-profile --port PORT --package apps/counter/dist/pxa-counter.pxa 可只读比较；install --strict-compatibility 还会阻止旧设备未报告的未知需求。

用能传数据的 USB 线把设备接到电脑，然后说：

设备已接上，请识别设备，把这个应用安装进去，实际验证主要操作。保留已有应用数据和存档，完成后告诉我设备状态。

AI 会列串口、读取 INFO 核对板型和 CPU，再编译匹配的 S3/S31/P4 AOT、验证签名、安装并启动。端口不明确时会先识别；不会把桌面屏幕 Profile 当成设备 CPU。即使用容器编译，USB 操作也由电脑端执行，不需要配置 USB 转发。

.pxa/pxa device info --port /dev/ttyACM0 --baud 2000000
.pxa/pxa install apps/counter --port /dev/ttyACM0

Windows 端口一般是 COM 数字，macOS 常见 /dev/cu.*，Linux 常见 /dev/ttyACM*、/dev/ttyUSB*，以实际发现为准。真机工具支持截图、输入、应用管理和设备所支持的内存诊断。手柄注入结束会释放模拟按键；这不能代替机械按压的手感测试。FPS、音频延迟等以对应真机测量为准。

先给新设备安装系统

设备尚未安装 PXA 时，打开 网页烧录，选择设备与方式，通过浏览器连接 USB 安装，无需先搭建编译环境。已有设备默认保留数据升级；完整重装会清除 Flash 中的应用、设置与存档。详见 烧录教程。

让 AI 升级官方固件

请识别我接上的 doit-gamekit-1，升级到官方稳定固件。保留应用、设置和存档；如果分区变化需要清数据，请先停止并说明。

工具先验证官方发行签名和镜像摘要，默认只更新应用分区；写入前读取设备实际分区表，匹配才写。遇到旧版 Mosaico 的分区变化等情况会停止。只有备份并明确同意丢失数据后，才可使用完整刷机。

.pxa/pxa firmware prepare --board doit-gamekit-1
.pxa/pxa firmware upgrade --board doit-gamekit-1 --port /dev/ttyACM0

ESP32-S31 如无法自动进入下载模式，需要按住 BOOT、按 RESET、松 BOOT，写完再按 RESET。端口可能变化，AI 会重新发现。刷写完成与启动后 INFO 验证分别报告。普通应用开发不会顺带替你刷固件。

一句话准备上架商城

请把这个应用准备上架 app.doit.am，完善名称、简介、分类、标签、图标、封面和真实运行截图，验证目标设备包后提交审核。

首次会打开浏览器，登录商城账号并确认应用短码。工具自动证明本机持有签名私钥、登记公钥、创建或复用你的作品资料；无需复制密钥或令牌给 AI。获得的上传权限仅限这一个应用，有效 30 天，可在开发者后台撤销。后续修改版本可复用授权。

.pxa/pxa store authorize apps/counter apps/counter/dist/pxa-counter.pxa --wait
.pxa/pxa store publish apps/counter apps/counter/dist/pxa-counter.pxa --changelog '首次发布'

私钥留在本机，凭据存到源码目录外的私有文件中。可用 store.json 设置新作品资料，已有商店资料不会被自动覆盖。提交后会核对签名包摘要，返回 pending_review 表示等待审核；通过审核后才公开。详见 商城发布。

常见问题

更新工具后要升级所有项目吗？ 不需要。重复 setup 保留已选择的 SDK；应用继续使用 pxa.lock。确实要迁移时，先停止 watch 和构建，运行 .pxa/pxa workspace migrate --sdk-version 0.10.0 选择工作区工具，再对要迁移的应用显式运行 .pxa/pxa sdk update apps/counter --offline，重新构建与验收。前一步不会改写应用锁、身份或存档，失败也不会切到半安装的 SDK。

磁盘占用太大怎么办？ 用 .pxa/pxa doctor --usage 查看实际占用，.pxa/pxa sdk cache 查看下载缓存。.pxa/pxa sdk prune --dry-run 预览，确认后去掉 --dry-run，只清理受签名清单识别的已安装发行归档，保留 SDK。需要离线复装时在首次 setup 使用 --keep-archives 或保留完整离线发行目录。项目缓存用 .pxa/pxa clean apps/counter --keep 2 --dry-run 预览；不删除项目源码、身份、存档和当前输出引用的内容。

SDK 文件损坏了？ 先停止使用该 SDK 的构建与模拟器，再运行 .pxa/pxa sdk repair，按签名清单恢复相同版本。已保留完整归档时可加 --offline --keep-archives。不要手动改安装目录或删锁来掩盖问题；自选的外部 SDK 路径不会被自动替换。

AI 只写了代码，没有运行？ 告诉它“继续实际构建、启动模拟器、操作并看截图，修到满足目标”。项目技能已经要求执行这个闭环；是否能使用工具仍取决于所选 AI 平台与权限。

能离线吗？ 首次下载依赖与发行包后可以离线构建、模拟器调试和真机安装。商城登录、上传和获取新版本需要联网。维护者可分发签名清单、归档与锁定 Python 缓存；高级命令见 Agent Kit README。

重复配置会覆盖我的设置吗？ 只更新工具自己拥有且未改动的文件或配置块，保留已有模型、权限、其他 MCP 与项目规则。遇到你修改过的工具文件会报冲突并保留，不强制覆盖。

哪些步骤仍需要本人？ 已有 AI 账号登录、系统要求的安装/虚拟化操作、首次商城授权，以及必要的 BOOT/RESET。普通编译、调试和已授权的更新无需逐步确认。

下载可靠吗？ 引导程序通过 HTTPS 获取签名清单，使用内置 P-256 发行公钥验证，再核对归档 SHA-256 与逐文件清单。DevKit、容器、官方固件都使用签名发行数据；不因下载失败而关闭验证。开源代码见 pxa-system。

遇到环境、编译、串口或提交问题时，查看 AI 开发排障。商城截图须通过真实模拟器拍摄，拍摄前关闭性能浮层和底部导航，上传前逐张检查原图。

设备没被 AI 找到

先接上 USB 数据线并正常开机，打开设备的「设置 → PXADB 调试」开关。参考系统界面若未显示该项，进入「设置 → 设备信息」，快速点按「系统版本」7 次，再向下找到「开发者 → PXADB 调试」；不同产品菜单可能有所不同，关闭其他串口工具，再请 AI 执行 .pxa/pxa device-profile。选定端口后执行 .pxa/pxa device-profile --port COM7，Linux 使用发现的 /dev/ttyACM… 或 /dev/ttyUSB…。该工具只读取信息，不安装、不重启、不刷机。

它会给出 CPU、设备报告的分辨率、调试输入及传感器信息，旧固件没有报告的字段保留为未知。请补充真实操作方式，以及是否需要适配横竖屏、圆屏、圆角和不同屏幕尺寸。BOOT/RESET 进入烧录模式，不是开启 PXADB；安装应用时正常开机即可。