内置提示
除了工具和资源,espctl 还附带提示 —— 现成的对话开头,你的助手可以 用它们来处理常见情况。提示是处理“应该怎么问“比从头描述更容易时的 正确选择。
总共有 8 个内置提示。
| 提示 | 参数 | 做什么 |
|---|---|---|
setup-mcp-client | client(取值 claude-code、cursor、claude-desktop、codex、opencode 之一) | 在特定 AI 工具里设置 espctl 的分步指南,本地 espctl 路径已经填好。 |
diagnose-build-error | error_log(字符串) | 走一遍构建失败:哪里错了、为什么、怎么修。接收原始编译输出,返回结构化的解释。 |
diagnose-cmake-error | error_log(字符串) | 和上一个想法相同,但针对 CMake 特有的失败(target 找不到、generator 表达式无效、缺 find_package 等)调优。 |
migrate-idf-version | from_version、to_version | 带你在 IDF 版本之间迁移。列出已知的破坏性变更、废弃 API 和 sdkconfig 更新。 |
configure-project | (无) | 带你设置一个新项目 —— 芯片、IDF 版本、组件、可选特性。 |
setup-ble-matter | (无) | 给当前项目添加 BLE + Matter 组件,包括必要的 idf_component.yml 条目和 sdkconfig.defaults 覆盖。 |
convert-to-component | (无) | 把一个独立的 ESP-IDF 项目变成其他项目可以依赖的可复用 IDF 组件。 |
optimize-flash-size | (无) | 缩小固件 flash 用量的提示 —— 日志级别调整、死代码移除、分区表调优、移除未用组件。 |
怎么使用一个提示
具体语法看你的 AI 工具。日常中文通常就行:
用
setup-mcp-client提示,client 设为 opencode。
…或者更明确:
跑
diagnose-build-error提示,error_log用build://log/0abf...e2的内容。
你的 AI 工具向 espctl 要这个提示,espctl 返回一段现成的对话,AI 工具 从那里继续。机制你看不到 —— 在你看来,就像你的助手接住了提示留下的 对话继续走。
提示为什么存在
工具和资源覆盖你的助手能做什么。提示覆盖应该怎么问能得到一致 结果。它们在以下场景里特别有用:
- 入门(
setup-mcp-client、configure-project)—— 你的助手带着你 走完设置,你不需要事先知道该问什么。 - 从失败中恢复(
diagnose-build-error、diagnose-cmake-error) —— 无论底层日志多杂乱,你的助手每次都给你相同的结构化分析。 - 多步重构(
migrate-idf-version、convert-to-component)—— 提示 把专家知识编码进去,你的助手不必从零想清楚。
示例
“帮我设 Cursor”
用
setup-mcp-client提示,client 是 cursor。
你的助手会:
- 读
install://cursor拿到一份按你机器预填好的代码片段。 - 带你编辑
.cursor/mcp.json。 - 建议验证步骤。
- 在你重启 Cursor 后提议跑
doctor。
“我的构建挂了,救我”
读
build://log/latest,然后对它跑diagnose-build-error提示。
你的助手会:
- 拉日志。
- 调
parse_build_errors提取结构化错误信息。 - 用结构化输出运行
diagnose-build-error提示。 - 告诉你:哪里错了、为什么、要改哪些行,以及(如果可能)一行 patch 建议。
“我在从 v5.2 迁到 v5.3”
跑
migrate-idf-version,从 v5.2.2 到 v5.3.1。
你的助手返回一份 checklist:破坏性变更、你正在使用的废弃 API、
移动或移除的 sdkconfig key、需要更新的组件版本。