用途：在 Project Profile 标明 build_system: platformio，或工作区存在 platformio.ini 时，用来自动探测环境并执行 PlatformIO 构建、清理或上传，为烧录或调试提供新的 ELF/HEX/BIN 产物。
主要能力：脚本自动检测 pio 命令与版本；解析 platformio.ini 的环境列表，提取 platform、board、framework 和上传协议；识别 [platformio] 中的 default_envs 作为默认环境；在 .pio/build/<env>/ 中按 ELF > HEX > BIN 顺序搜索产物；存在多个同样合理环境时列出候选而不静默猜测。脚本启动会自动复用工程根目录 .em_skill.json 中上次成功的 profile 作为默认参数（显式参数优先），--resume 仅用于断言缓存必须存在，无缓存则非零退出；无缓存或要求重新探测时回退到正常扫描。
使用方式：先阅读 references/usage.md 确认本次是环境探测、列出环境、执行构建还是仅扫描产物。不确定环境时就绪状态时，先运行 scripts/platformio_builder.py 的 --detect 模式；用 --list-envs --project-dir <dir> 确认可用环境，再用 --project-dir + --env 执行构建；读取输出的构建结果与产物扫描报告，并将构建环境、绝对产物路径和板卡信息写回 Project Profile。
失败分流：pio 不可用返回 environment-missing；platformio.ini 不存在或环境名无效返回 project-config-error；构建成功但无可烧录/调试产物返回 artifact-missing；多个同等合理环境返回 ambiguous-context。
适用场景与交接：烧录或调试需要新固件时使用；成功后推荐 flash-openocd 或 debug-gdb-openocd，需要符号信息或调试会话时交给 debug-gdb-openocd。PlatformIO 自带 --upload 可在简单场景直接使用。
限制：PlatformIO 跨平台（Linux / macOS / Windows），脚本用 Python 标准库和 subprocess 调用 pio，构建路径跨平台；输出产物路径应保持绝对路径。必要输入为含 platformio.ini 的工作区路径或已有 Project Profile，以及可选环境名。其他收费、价格、平台支持细节暂未提供。