典型 8 步工作流
这是你让 AI 助手构建固件时,它运行的标准端到端流程。读一遍,手册 其他部分会清晰得多。
1. 助手读 install://overview → 确认你的设置
2. 助手运行 doctor → 检查一切是否健康
3. 助手运行 store_versions → 看到 IDF v5.3.1 可用
4. 助手运行 project.init (target: esp32s3) → 写 .espctl.toml
5. 助手运行 build (target: esp32s3) → 返回 task_id
6. 助手看 build.status 直到 succeeded → 跟踪进度
7. 助手运行 logs.tail 显示构建输出 → 给你看发生了什么
8. 助手运行 artifacts.manifest → 显示固件大小 + 可烧录的文件
下面是每一步做什么、为什么。
1. 读 install://overview
助手 → espctl: read("install://overview")
espctl → 助手: 环境变量表、模式、基础设置
espctl 自带一份设置指南作为资源。在会话开始时读一次,可以让助手 立即对以下内容有清晰画面:
- 你设了哪些环境变量（以及没设哪些）。
- 它在远程构建模式（默认）还是仅计划模式。
- AI 工具列表和它们的配置代码片段 URL。
排查问题时这也是好的第一步 —— 如果资源不可达,espctl 本身就没在 跑,这种“事后看显而易见“的细节,助手不查很容易漏过。
2. 运行 doctor
助手 → espctl: doctor
espctl → 助手: { status: "healthy", checks: [...], errors: [] }
doctor 跑几项健康检查(构建服务器可达、访问密钥有效、项目设置
能解析、IDF 版本匹配)。任何一项有问题,它就快速失败,返回结构化的
错误指向出问题的检查项。
每次开新会话都跑,即使昨天还能用。在你试图做真正的工作之前, catches 最常见的“为什么不工作?“故障。
3. 列出构建服务器版本
助手 → espctl: store_versions
espctl → 助手: { versions: ["v5.2.2", "v5.3.1"], default: "v5.3.1" }
确认构建默认会用哪个 IDF 版本,以及还有什么备选。如果你的项目在
.espctl.toml 里 pin 了特定版本,助手会注意到不匹配,根据
idf_select_version 的决定使用 pin 或回落到默认。
4. 初始化项目
助手 → espctl: project.init { target: "esp32s3" }
espctl → 助手: { project_root: "...", config_path: ".espctl.toml", ... }
创建 .espctl.toml 和构建子文件夹。跑两次没事 —— 如果项目已经设好,
这不做任何事。
如果你在已有项目上工作,跳过这一步。助手仍然会对已有的 .espctl.toml
跑 validate_config,确保没坏。
5. 启动构建
助手 → espctl: build { target: "esp32s3", profile: "release" }
espctl → 助手: { task_id: "0abf...e2", status: "pending" }
构建被发到构建服务器,在沙箱里开始跑。你立即拿到 task_id —— 构建
本身在后台跑。
6. 看到结束为止
loop:
助手 → espctl: build.status { task_id: "0abf...e2" }
espctl → 助手: { status: "running", phase: "compiling", progress: 0.42 }
等 2s
until status == "succeeded" or "failed"
大多数助手每 1–3 秒查一次。更高效的模式是订阅
build://log/{task_id} 资源,获得推送更新 —— 但反复问简单且到处可用。
7. 读日志
助手 → espctl: logs.tail { task_id: "0abf...e2", lines: 100 }
espctl → 助手: { lines: [{ seq, ts, stream, text }, ...] }
构建结束后,拉最后 N 行输出。这就是你的助手会展示给你看的“构建日志“。
如果构建失败,你的助手还会跑 parse_build_errors 提取结构化错误信息
—— 比直接堆 500 行原始输出有用得多。
8. 读清单
助手 → espctl: artifacts.manifest { task_id: "0abf...e2" }
espctl → 助手: { artifacts: [...], flash_size, flash_freq, ... }
清单是构建产生了什么以及怎么烧录的权威记录。你的助手可以把单个
.bin 文件流式落到你本地硬盘,或者直接交给 esphome.cloud 网页烧录器。
安全提示: 你编译好的固件可能包含嵌入的敏感信息（Wi-Fi 密码、 API key）。把
.bin文件当作敏感文件。
变体
这是幸福路径。真实工作流常常有分支:
- 第 6 步构建失败 → 助手对日志跑
parse_build_errors,然后跑diagnose-build-error提示。你得到结构化的“哪里错了、这是修法“, 而不是一墙文字。 - 你切换芯片 → 在第 4 步和第 5 步之间插入一次
set_target调用。 助手会警告你这会清掉构建缓存。 - 构建结束后你需要交互式串口监视器 → 用
Monitor 标签或
espctl monitor --port /dev/ttyUSB0。 - 你想知道构建会做什么但不真的运行 → 把第 5 步(
build)替换 为generate_build_plan。无副作用。