构建后分析

三个工具在构建成功后运行,告诉你固件多大、用了哪些库、有没有问题。

三个都需要一个已完成构建的 task_id。

size.run

对已完成的构建跑大小分析。解析 idf.py size 的输出,返回结构化 报告。

输入:

{
  "task_id": "0abf...e2",
  "detail": "summary"
}

返回:

{
  "task_id": "0abf...e2",
  "detail": "summary",
  "size_report": {
    "flash_used": 200000,
    "flash_remaining": 3800000,
    "ram_used": 42000,
    "ram_remaining": 285680
  }
}

"components" 级别按 ESP-IDF 组件拆分用量。"files" 级别到 单个目标文件。

CLI: espctl size

读取 idf.py size(或远程构建)写在 build/<target>/size_output.txt 里的尺寸报告,打印 flash/RAM 用量细分。它本身不会重跑 idf.py size —— 先跑一次构建。

espctl size [--target <chip>]

输入

输出

Human 模式:

Memory Usage:
  Flash: 200000 / 4194304 bytes (4.8%)
  RAM:    50000 / 327680 bytes (15.3%)

Sections:
  DRAM     50000 / 327680 bytes (15.3%)

JSON(--json):一个 SizeReport 对象,包含 flash_used、 flash_total、ram_used、ram_total 和 sections 数组。

失败模式

示例

# 用 .espctl.toml 里的默认 target
espctl size

# 显式指定 target
espctl size --target esp32s3

# JSON 输出,管道喂给比对脚本
espctl --json size --target esp32s3 | jq '.flash_used'

相关

• size.run —— MCP 等价工具,接受 task_id 和更细的 "components" / "files" 级别。
• parse_size_report —— 把原始 idf.py size 日志输出转成同一份结构化数据。

sbom.create

为已完成的构建生成 SPDX 软件物料清单。列出固件里用到的每个库和 组件。

输入:

{
  "task_id": "0abf...e2",
  "scan_vulnerabilities": true
}

返回: task ID 和 recipe_id（"idf_sbom"），告诉构建代理 执行 SBOM 生成。

适合:

• 发布前审计固件里有什么。
• 检查第三方组件是否有已知漏洞。
• 满足要求提供 SBOM 的合规要求。

隐私提示: scan_vulnerabilities 为 true 时,构建机器会通过 网络查询外部漏洞数据库（CVE/OSV）。你的依赖列表会发送到这些 服务。如果这是顾虑,关掉 scan_vulnerabilities,自己用本地工具 扫描 SBOM 文件。

diag.run

对已完成的构建运行 idf.py diag 收集诊断信息。构建成功但固件 行为异常时有用。

输入:

{ "task_id": "0abf...e2" }

返回: task ID 和 recipe_id（"idf_diag"），告诉构建代理 运行诊断。

另见

• 构建生命周期——怎么启动这些工具分析的构建。
• 日志与构建产物——parse_build_errors 和 parse_size_report 用于原始日志解析。
• 固件与烧录——分析完了下载和烧录固件。