Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

工具参考 — 总览

espctl 给你的 AI 助手 42 个 MCP 工具名 —— 6 组里 29 个独立工具 实现,加上 9 个 RSHome 工具用于智能家居设备配置,再加 4 个为 兼容旧配置而保留的别名(29 + 9 + 4 = 42);加上 CLI 子命令用于 手动操作(见 IDE 集成 和 CLI 实用工具)。 这一页是地图;每个小节链接到一组工具的完整参考。

一览

组工具用来干嘛
构建生命周期build(别名 build.start)、build.status、build.cancel、build.rust_elf、set_target.run、generate_build_plan、get_clean_plan启动、跟踪、停止、规划固件构建;Rust no_std bundle
项目管理project.init、project.create、project.create_component、set_target、validate_config、idf_select_version(别名 idf.select_version)创建项目、脚手架、检查设置
ESP-IDF Storestore_versions、idf.versions(同源不同视图,不是别名)、doctor(别名 doctor.run)看构建服务器有哪些 IDF 版本,健康检查
日志与构建产物logs.tail、list_artifacts(别名 artifacts.list)、artifacts.manifest、parse_build_errors、parse_size_report看构建日志、看输出文件、看懂错误信息
固件与烧录firmware.list、firmware.download、elf.download、flash.run、monitor.run列出、下载、烧录固件,捕获串口输出,拉调试用 ELF
构建后分析size.run、sbom.create、diag.run大小报告、SBOM、诊断
RSHomershome.validate、rshome.components.*、rshome.pin_map、rshome.codegen.preview、rshome.modules.*、rshome.solutions.*、rshome.assembly.preview智能家居设备配置
IDE 集成espctl ide sync在不本地安装 ESP-IDF 的前提下,配置本地 clangd 的代码补全
CLI 实用工具version、skills、--skills、--json、--quiet版本信息、机器可读的 skills 清单、全局标志

两种命名风格

工具名有两种风格:

  • 点式命名(build.cancel、build.status、project.init、 logs.tail、firmware.list)—— 比较新的工具。
  • 下划线命名(idf_select_version、list_artifacts、 generate_build_plan、get_clean_plan、parse_build_errors、 parse_size_report、set_target、store_versions、 validate_config)—— 比较早的工具,保留下来不破坏已有的配置。

有正好四个工具有别名:build ⇄ build.start、doctor ⇄ doctor.run、idf_select_version ⇄ idf.select_version,以及 list_artifacts ⇄ artifacts.list。每个别名指向同一份实现 —— 挑 你 AI 工具展示得更自然的那个用,然后保持一致。

store_versions 和 idf.versions 不是别名。 它们是两个不同 的工具实现 —— store_versions 给一个轻量列表(版本号 + 路径), idf.versions 给详细视图(commit、默认标志、工具链路径)。

决策树:我要哪个工具?

我想…                                              →  用…
────────────────────────────────────────────────────────────────
… 创建一个全新的 ESP-IDF 项目                     →  project.init
… 从模板创建项目                                  →  project.create
… 给项目添加一个组件                               →  project.create_component
… 修改一个已有项目的芯片                           →  set_target
… 在构建机器上跑 set-target                        →  set_target.run
… 检查我的 .espctl.toml 是否合法                   →  validate_config
… 决定一次构建会用哪个 IDF 版本                    →  idf_select_version
… 看构建服务器有哪些 IDF 版本                      →  store_versions
… 看 IDF 版本详情(路径、commit、默认)            →  idf.versions
… 检查所有东西是否设好了                           →  doctor
… 编译固件                                        →  build
… 看我那个跑着的构建是否结束了                     →  build.status
… 停止一个正在跑的构建                             →  build.cancel
… 看一次构建会做什么(不真的运行)                 →  generate_build_plan
… 看一次清理会删什么                               →  get_clean_plan
… 读构建日志行                                    →  logs.tail
… 看构建产生了哪些文件                             →  list_artifacts
… 读官方的 manifest.json                           →  artifacts.manifest
… 把原始编译错误转成可读的形式                     →  parse_build_errors
… 读构建的 flash/RAM 用量                          →  parse_size_report
… 详细的大小分析(按组件/文件)                    →  size.run
… 生成软件物料清单                                →  sbom.create
… 对构建跑诊断                                    →  diag.run
… 列出有固件可下载的构建                           →  firmware.list
… 获取固件下载元数据                               →  firmware.download
… 拉构建时保留的不剥离符号 ELF(JTAG 调试用)      →  elf.download
… 通过 USB 烧录固件到设备                          →  flash.run
… 烧录后捕获设备串口输出                            →  monitor.run
… 把 Rust no_std ELF 打成 flash bundle             →  build.rust_elf

工具是怎么调用的

每个工具都接收一个名字和一个 JSON 参数对象。具体的触发方式取决于你 的 AI 工具 —— 大多数助手会根据你说的话自动选工具和参数,但你也可以 明确指定:

调用 build 工具,target 设为 esp32s3,profile 设为 release。

如果你想在调用前看某个工具接受什么参数,问:

给我看 build 工具的 schema。

大多数 AI 工具会输出输入/输出的形状。

所有工具的通用约定

  • task_id —— 构建工具立即返回 task_id,然后在后台跑完。你的 助手通过 build.status(或读 build://log/{task_id})跟进。要提前 停止,用 build.cancel。
  • 状态值 —— pending、running、succeeded、failed、canceled。
  • 错误 —— 当构建本身出问题时(编译错误、链接失败),工具是 成功的 —— 失败信息出现在 build.status 和日志里。工具错误专门 留给“工具自己坏了“。
  • 路径 —— 所有路径都来自构建服务器的文件系统。它们看起来像 /work/...,因为构建服务器跑在沙箱里;它们和你电脑上的任何东西 都不对应。

准备好了?从最重要的一组开始:构建生命周期。