资源
除了工具(你的助手能调的东西),espctl 还有资源 —— 你的助手 能按需获取的只读 URL。资源是“给我看 X“而不是“做 X“。
总共有 15 个可读 URL(13 个固定资源加 2 个 URI 模板),分成 4 组。
安装资源 — install://*
每个 AI 工具的自文档化设置代码片段。让你的助手读其中任意一个,它会 返回一段可粘贴的配置块,预填了你机器上的实际路径。
| URL | 返回内容 |
|---|---|
install://overview | 完整的设置指南,包含环境变量表和仅计划模式 vs 远程构建模式的解释。 |
install://claude-code | 给 Claude Code 的 .claude/settings.json 片段。 |
install://cursor | 给 Cursor 的 .cursor/mcp.json 片段。 |
install://claude-desktop | 给 Claude Desktop 的 claude_desktop_config.json 片段。 |
install://codex | 给 Codex CLI 的 ~/.codex/config.toml 片段。 |
install://opencode | 给 OpenCode 的 opencode.json 片段。 |
提示: 这些就是第二部分 — 客户端配置 每一章里出现的同一组片段,只不过预填了 espctl 自己能在你机器上检测 到的实际
espctl路径。
构建服务器资源 — store://*
构建服务器装了什么的只读视图。“store” 住在构建服务器上,不在你电脑上。
| URL | 返回内容 |
|---|---|
store://versions | 构建服务器上的 ESP-IDF 版本列表(数据和 store_versions 工具一样,但作为资源)。 |
store://manifest | 完整的服务器清单,包含工具路径、校验和和元数据。 |
项目资源 — project://*
当前项目的只读视图(espctl 设置去看的那个文件夹)。
| URL | 返回内容 |
|---|---|
project://config | .espctl.toml 的内容。 |
project://idf-version | .idf-version 的内容(项目级 IDF pin 文件)。 |
project://sdkconfig | 当前 sdkconfig(默认值合并后的最终设置)。 |
project://compile_commands | 最近一次构建的 compile_commands.json,用于 IDE 集成。 |
如果你想让 clangd 或其他代码智能工具理解你项目的 include 路径,
project://compile_commands 特别好用。
构建资源 — build://*
构建状态的实时视图 —— 日志行和输出文件。它们存在,是因为当你的助手 只需要对新数据反应时,反复问是浪费的。
| URL | 返回内容 |
|---|---|
build://log/latest | 最近一次构建(任意任务)的日志行。 |
build://log/{task_id} | 特定构建的日志行。新行到达时推送。 |
build://artifacts/{target} | 特定芯片的产物列表(数据和 list_artifacts 一样)。 |
build://log/{task_id} 是读实时构建输出的首选方式 —— 它是流式
资源,所以你的助手不需要反复问。大多数 AI 工具同时支持一次性读和
实时订阅。
怎么获取一个资源
具体语法看你的 AI 工具。一个典型请求看起来:
读取
install://overview资源。
…或者:
订阅
build://log/0abf...e2,新行给我看。
底层,你的 AI 工具向 espctl 要这个资源。响应是 markdown 文本或 结构化 JSON,取决于具体是哪个资源。
资源 vs 工具 —— 什么时候用哪个
| 你想… | 用… |
|---|---|
| …触发一个有副作用的动作 | 工具 |
| …读实时状态 | 资源 |
| …读一次状态 | 都行(资源对于反复读略便宜) |
| …随时间观察一个值变化 | 资源(订阅) |
两者的边界可以是模糊的。规则是:如果它有副作用或者参数会改变行为, 它是工具。如果它只是给你一个快照,它是资源。