术语表

本手册中你会看到的术语。

A

Aegis —— 包含构建服务器、构建机器软件和 espctl CLI/MCP 服务的 伞形项目。代码在 github.com/ff4415/aegis。

artifacts.manifest —— 返回完成构建的官方 manifest.json 的 MCP 工具,包括每个二进制的 flash 偏移。

B

Bandwidth limiter（带宽限制器） —— 每通道的字节计数器,强制 许可中的 max_bandwidth_kbps。超过时触发反压;不断开连接。

Bootloader —— 在你的应用之前在 ESP32 上运行的第一阶段固件。 构建产生一个独立的 bootloader.bin,你把它烧到偏移 0x0（或者 0x1000,取决于芯片）。

构建机器 —— 在沙箱中真正运行 ESP-IDF 构建的 Linux 主机。 通过 HTTPS 向构建服务器查看任务,接受来自客户端的 WebRTC peer 连接。 永远不为构建流量开放入站 TCP 端口。

build（工具） —— 把固件构建提交到远程构建机器的 MCP 工具。 立即返回 task_id;构建本身异步运行。

Build cache（构建缓存） —— build/ 下的硬盘状态,让增量构建 跳过已经编译的翻译单元。切换芯片 target 会让缓存失效。

构建服务器 —— 公开的 HTTP 服务。颁发许可、代理 WebRTC 信令、 把任务调度到构建机器。无状态。从不接触构建内容。

build.status —— 你用来查看构建是仍在运行、已完成还是失败的 MCP 工具。

C

CMake —— ESP-IDF 底层用的构建系统。构建机器跑 idf.py build, 后者本身是 CMake + Ninja 的薄包装。

cwd —— 在 MCP 服务配置里,MCP 服务应该运行的工作目录。对 espctl 而言,这通常是构建机器应该操作的 ESP-IDF 项目的绝对路径。

D

Data channel（数据通道） —— WebRTC 基础工具,让两个 peer 在 加密连接上交换消息。Aegis 用三个:espctl、pty、firmware。

doctor —— 在 store、项目配置、环境变量、构建服务器连通性上跑 全面健康检查的 MCP 工具。排查问题时先跑这个。

E

ESP-IDF —— Espressif 官方的 IoT Development Framework —— 给 ESP32 系列芯片的 C/C++ SDK 和工具链。

espctl —— 本手册的核心 CLI 二进制。子命令包括 mcp serve （启动 MCP 服务）,以及独立的 CLI verb（doctor、build 等）。

ESPCTL_STORE_ROOT —— 指向工具链 store 目录的环境变量。构建 机器使用。

F

Firmware channel（固件通道） —— 第三个 WebRTC 数据通道,专门 用来把编译好的 .bin 从构建机器流回客户端。有自己的带宽预算,与 其他通道分离。

Flash —— 既是动词（把固件写到设备）也是名词（设备的非易失性 存储）。一次构建的输出是一个或多个在特定 flash 偏移上的 .bin 文件。

I

IDF version（IDF 版本） —— ESP-IDF 的一个特定标记发布（例如 v5.3.1）。store 可以同时持有多个版本;项目通过 .idf-version 或 .espctl.toml pin 自己想要的版本。

J

job_id —— 标识单个许可 + 构建会话的不透明 UUID。在 URL 里 用,例如 /signaling/{job_id}/offer。

M

MCP（Model Context Protocol） —— 把 AI agent 连接到工具、资源 和提示的开放协议。见 modelcontextprotocol.io。

MCP_AUTH_SECRET —— 客户端发给构建服务器证明自己被允许请求许可 的鉴权 token。

P

许可（Permission） —— 一个签名 token,记录用户、任务、允许的 WebRTC 通道、带宽/速率限制和过期时间。由构建服务器颁发,由构建 机器验证。

许可 TTL —— 许可的有效时间。默认 5-30 秒。短是有意的。

Plan-only mode（仅计划模式） —— CONTROL_BASE_URL 和 MCP_AUTH_SECRET 未设置时 MCP 服务的模式。服务可以读状态、生成 计划,但不能真的构建。见 仅计划模式 vs 远程构建。

Prompt（提示） —— 在 MCP 中,服务向客户端提供的参数化消息 模板。Aegis 附带 8 个内置提示;见内置提示。

project.init —— 通过写 .espctl.toml 初始化 espctl 项目的 MCP 工具。

PTY（伪终端） —— Linux 内核功能,创建一对模拟真实终端的文件 描述符。Aegis 把 PTY 用于交互式会话,例如 idf.py monitor。

R

Remote build mode（远程构建模式） —— 设了 CONTROL_BASE_URL 和 MCP_AUTH_SECRET 时 MCP 服务的模式。构建在远程构建机器上跑。

Resource（资源） —— 在 MCP 中,服务向客户端暴露的只读 URI。 Aegis 提供 15 个可读 URL(13 个固定资源加 2 个模板),覆盖安装片段、 store 状态、项目状态和实时构建日志。

S

沙箱（Sandbox） —— 把每次构建隔离在自己空间里的隔离环境, 无网络访问、无宿主文件系统访问（除了一个明确挂载的工作区）、限制 权限。

Store —— 装着所有已安装 IDF 版本和工具链的硬盘目录。见 ESPCTL_STORE_ROOT。

Store manifest（store 清单） —— store 中的一个 JSON 文件, 把 IDF 版本映射到工具路径和校验和。由 provision-store.sh 准备。

T

task_id —— build 返回的、单次构建的不透明标识符。你查看 build.status 并读 build://log/{task_id} 来跟踪构建。

Toolchain（工具链） —— 给特定 ESP 芯片家族的编译器、链接器 和支持二进制（xtensa-esp32-elf、riscv32-esp-elf 等）。store 每个 IDF 版本的每个家族持有一个工具链。

W

WebRTC —— 浏览器实时点对点通信的标准。Aegis 用它（具体是 数据通道）在客户端和构建机器之间发送构建请求、日志和固件。

另见

• 系统总览 —— 在上下文里看到大多数 这些术语。