PIO Agent

PIO Agent

PIO Agent 是面向嵌入式开发、以 Agent 为先的开源硬件执行层，基于 PlatformIO MCP 运行时构建。

发布状态

规范版 3.1.0 运行时已发布。3.2.0 候选版将 pio-agent CLI 设为主要适配器（除非明确要求，否则不会有进程持续运行），并 新增原生 Codex 面板和公开插件列表元数据。有关已实现的 行为以及各软件包名称的发布状态，请参阅 更新日志、兼容性指南 和分发就绪情况。

品牌与兼容性

PIO Agent 是产品和 Codex 插件名称。PlatformIO MCP 是底层 MCP 运行时，也是现有安装所使用的兼容标识。Codex 插件 ID、市场 ID、配置键和技能命名空间仍为 platformio-mcp。在 npm 上，platformio-mcp 是规范软件包，而 pio-mcp 和 pio-agent 是委托给它的轻量兼容软件包。规范软件包还会安装 platformio-mcp 和 pio-agent 这两个可执行文件名称。这样，现有用户无需迁移即可升级，同时新用户在整个界面中看到的都是 PIO Agent。

它通过以下方式提供 PlatformIO 工作流，涵盖开发板发现、项目设置、构建、烧录、监控、诊断和任务编排：

• MCP 服务适配器
• 一流的 CLI 适配器（platformio-mcp / pio-agent）
• 可选的本地仪表板，用于查看和控制

MCP 是一种适配器。PlatformIO 是第一个后端。

快速开始（推荐）

npm install -g platformio-mcp
pio-agent devices
pio-agent build --project-dir . --json

无需服务端，无需配置客户端，命令之间也不会有进程持续运行。

与编码 Agent 配合使用

安装技能，并将 Agent 指向 pio-agent 二进制文件。pio-manager 技能详细介绍了每条命令。

MCP 服务（可选）

仍完全支持 MCP，适用于偏好使用 MCP 的客户端：

claude mcp add platformio -- node /path/to/platformio-mcp/build/index.js

请注意，每个以这种方式连接的会话都会运行各自的服务进程。上面的 CLI 则可避免这种情况。其他宿主的配置方式请参阅下文的手动 MCP 配置。

Agent 优先功能

• 项目就绪状态验证（agent_validate_project）
• 丰富的构建诊断，包含结构化错误分类（agent_build_diagnose）
• 感知开发板的 GPIO 安全审计（agent_safe_pin_audit）
• 烧录 + 监控 + 运行时断言（agent_flash_monitor_verify）
• 持久化工作流产物，保存在 .pio-mcp-workspace/（lastAgentReport.json、boardReport.json）
• 开发板智能报告（agent_generate_board_report）
• 策略配置文件检查（get_policy_status）
• 精确的项目/环境/设备绑定（agent_resolve_target）
• 有界、基于游标的串口健康检查（agent_monitor_health）
• 幂等的任务取消和精简历史记录（cancel_task、list_task_history）
• 为 Agent 提供只读审批状态；审批仍由人工控制

所有高风险操作仍须遵守策略和审批规则。

快速开始

1. 运行仪表板

npx platformio-mcp dashboard --serve

2. 使用 CLI

支持全部三个 npm 名称。platformio-mcp 是规范名称；pio-mcp 和 pio-agent 通过仅依赖别名安装相同的 CLI：

npx platformio-mcp --help
npx pio-mcp --help
npx pio-agent --help

npx --package platformio-mcp pio-agent devices
npx --package platformio-mcp pio-agent boards --filter esp32
npx platformio-mcp init --board esp32dev --framework arduino --project-dir ./firmware
npx platformio-mcp build --project-dir ./firmware
npx platformio-mcp flash --project-dir ./firmware --port auto
npx platformio-mcp monitor --project-dir ./firmware --port auto --expect BOOT_OK --timeout 30
npx platformio-mcp agent-validate --project-dir ./firmware
npx platformio-mcp agent-build-diagnose --project-dir ./firmware
npx platformio-mcp agent-safe-pin-audit --project-dir ./firmware --board esp32dev
npx platformio-mcp agent-flash-monitor-verify --project-dir ./firmware --expect-all BOOT_OK --reject-patterns "Guru Meditation,Brownout detector,WDT reset" --timeout 45
npx platformio-mcp agent-last-report --project-dir ./firmware
npx platformio-mcp policy-status --project-dir ./firmware
npx platformio-mcp task-status <task-id>

使用 --json 获取机器可读输出：

npx platformio-mcp build --project-dir ./firmware --json

3. 安装到 AI 宿主

npx platformio-mcp install --cline
npx platformio-mcp install --claude
npx platformio-mcp install --vscode
npx platformio-mcp install --antigravity
npx platformio-mcp install --codex

4. 安装完整的 Codex Plugin

PIO Agent Codex Plugin 添加了捆绑的 MCP 运行时、专用的内嵌技能、安全的应用内仪表板流程，以及监控自动化指南。Codex 要求使用一个稳定的插件标识符，因此安装选择器和技能命名空间仍为 platformio-mcp；安装后的产品显示为 PIO Agent。从克隆仓库安装：

npm install
npm --prefix web install
npm run plugin:build
node build/cli.js install --codex-plugin

从 npm 安装：

npx -y platformio-mcp install --codex-plugin

安装后启动新的 Codex 任务。旧版 install --codex 命令仍可用于仅配置 MCP。有关更新、卸载、浏览器回退、策略、自动化和回滚的详细信息，请参阅完整的 Codex Plugin 指南。

插件发布门禁会在 Windows、macOS 和 Linux 上运行，在 Chromium 中测试经过身份验证的仪表板，验证捆绑运行时和公共工具注册表，并将实体开发板的验证材料保留在单独的手动工作流中。该工作流仅上传有限且经过净化的验证材料；原始硬件日志会留在可自托管的运行器上。请参阅发布与验证指南。

如需无头验证和状态检查，同一 CLI 还提供 plugin validate、target-resolve、monitor-status、monitor-health、task-history、approval-status 和 pending-approvals。运行 platformio-mcp --help 查看有限选项和 JSON 输出支持。

手动配置 MCP

{
  "mcpServers": {
    "platformio": {
      "command": "npx",
      "args": ["-y", "platformio-mcp", "serve"]
    }
  }
}

在 Windows 上，如果宿主要求显式解析 shim，请使用 npx.cmd。

核心功能

• 发现 PlatformIO 支持的硬件板卡和设备
• 初始化项目并检查配置
• 构建、上传、监控及轮询后台任务
• 为构建／上传／串口故障提供结构化诊断
• 安全与策略防护措施（审批门禁、审计日志、脱敏）
• 在仪表板中查看命令、日志、锁和安全状态

安全模型

PIO Agent 会在 CLI 和 MCP 流程中执行策略决策。

• 操作可设为 allow、deny 或 requires_approval
• 高风险操作（例如固件上传／重置流程）需要明确审批
• 所有操作均可审计
• 对外提供的日志流会对机密信息进行脱敏

可通过 .pio-mcp-policy.json 按项目选择策略配置文件：

{
  "profile": "flash_requires_approval"
}

支持的配置文件：

• read_only
• build_only
• monitor_only
• flash_requires_approval
• lab_runner（需要明确且会过期的无人值守实验室策略）
• lab_admin

CLI 审批工作流：

npx platformio-mcp approvals --status pending --json
npx platformio-mcp approve <approval-id> --json
npx platformio-mcp deny <approval-id> --json

Codex 用法

面向 Codex 的文档和提示词手册：

• Codex 使用指南
• Codex 提示词手册

文档

入门指南：

• LLM 安装指南

指南和参考：

• Agent 自定义指南
• MCP 服务命令参考
• 故障排除指南
• Agent 优先的嵌入式工作流
• 竞争定位
• MCP-U 集成模板
• Agent 技能目录

规范：

• PIO Agent 设计规范
• Web UX 设计规范
• 开发指南

开发

前置条件：

• Node.js >= 20（包括捆绑的 direct-serial 运行时）
• PlatformIO Core CLI（安装指南）

本地设置：

git clone https://github.com/jl-codes/platformio-mcp.git
cd platformio-mcp
npm install
npm run build
npm run test
npm run smoke-test

CI/CD 测试层级：

• npm run test:ci:unit 运行跨平台 CI 中使用的单元/组件覆盖率测试。
• npm run test:e2e:ci 运行适用于 CI 的端到端测试，覆盖 Agent 工作流和 CLI 接线。
• .github/workflows/ci.yml 会在拉取请求/推送时运行类型检查、测试和软件包冒烟检查。
• .github/workflows/hardware-e2e.yml 是一个手动触发的可自托管运行器工作流，用于执行一次明确确认的实体开发板写入、捆绑插件协议检查、刷写后的身份/串口断言、清理证明和经过脱敏的证据。

贡献

欢迎贡献。

• 有 Bug 或功能请求时，请提交 issue
• 在适用时，请提交附带测试的拉取请求

许可证

MIT。参见 LICENSE。

固件崩溃和大小分析

MCP 工具 decode_backtrace 和 size_report 使用项目注册的 GNU 工具链分析明确选定的项目/环境。元数据和内存检查需要构建权限，因为它们可能会执行项目脚本。报告会指出确切的 ELF，保留未解析的崩溃地址，并区分 PlatformIO 内存用量与 GNU 估算值。它们无法证明设备上运行的是哪个固件。输入、审批行为、证据和当前限制，请参见固件分析。