esp_cli_service 版本演进与实战指南：从 UART REPL 到服务/工具动态命令

esp_cli_service 是 ESP-IDF 高级多媒体开发框架（ESP-ADF，全称 Espressif Advanced Development Framework for Multimedia Applications）中一个基于 esp_service_t 的服务组件，它把 ESP-IDF 的 esp_console UART REPL 完整嵌入 ADF 的服务生命周期，通过串口终端即可完成堆内存/芯片信息查询、服务启停控制，乃至 JSON Schema 工具的动态调用。本文以该组件的 CHANGELOG.md 为主线，结合 esp_cli_service.h、esp_cli_service.c 等源码与配套示例，系统梳理从 v0.5.0 首版到 v0.5.2 的演进脉络，并给出可直接上手的配置、命令与二次开发方法。

版本演进总览：三次迭代做了什么

CHANGELOG 完整记录了该组件的发布轨迹：

版本	类型	变更内容
v0.5.0	Features	组件初始版本：esp_service_t 子类 + esp_console UART REPL；esp_cli_service_register_static_command() 静态命令；esp_cli_service_bind_manager() 动态 svc/tool 命令；为 esp_service_manager 暴露的每个工具自动生成命令；支持位置参数与 flag 风格选项的参数解析
v0.5.0~1	Changes	为 README.md 与 README_CN.md 添加 Component Registry 徽章
v0.5.1	Features	新增 USB Serial 与 USB CDC 后端支持
v0.5.2	Features	改用组件注册表中的 cJSON 替代 IDF 组件

下面逐个版本展开其技术内涵。

v0.5.0：初始版本的核心能力

v0.5.0 定义了组件的全部骨架能力，这些能力至今仍是它的核心。

作为 esp_service_t 子类的 REPL 服务

esp_cli_service 在结构上内嵌了 esp_service_t 基类（见 esp_cli_service_internal.h 中的 struct esp_cli_service），并通过 esp_service_init() 与一组生命周期回调注册为 ADF 服务：

static const esp_service_ops_t s_cli_ops = {
    .on_start  = cli_on_start,
    .on_stop   = cli_on_stop,
    .on_deinit = cli_on_deinit,
};

这段代码位于 esp_cli_service.c。它实现了三个关键钩子：

• cli_on_start()（L176-L260）：创建并启动 esp_console REPL 任务，依次注册核心命令（svc/tool）与静态命令，最后调用 esp_console_start_repl()；
• cli_on_stop()（L262-L278）：调用 esp_console_stop_repl() 停止 REPL，并清理命令注册状态；
• cli_on_deinit()（L280-L289）：服务销毁时兜底停止 REPL。

因此，REPL 的启停与 esp_service_start() / esp_service_stop() / esp_service_destroy() 严格绑定，天然融入 ADF 的服务生命周期管理，无需额外维护 console 初始化代码。这也正是 README 中所说"UART REPL integration —— 调用 esp_service_start() 时启动，停止/销毁时关闭"的源码级依据。

静态命令：esp_cli_service_register_static_command()

静态命令是直接以 esp_console_cmd_t 描述符注册的固定命令，实现位于 esp_cli_service_cmd_static.c：

• clone_static_cmd()（L60-L90）会校验命令名不能含空格、func 与 func_w_context 二选一，并将命令名/帮助文本/提示文本深拷贝到堆上，保证调用方传入的描述符只需在注册调用期间有效；
• add_static_command_internal()（L104-L176）在 REPL 未启动时把命令存入待注册队列；若 REPL 已运行，则立即通过 esp_console_cmd_register() 注册，实现"REPL 启动前后均可随时注册"；
• 重复命令名会返回 ESP_ERR_INVALID_STATE。

组件还预置了 4 个内置系统命令（L178-L216）：

命令	说明	底层调用
sys_heap	打印当前空闲堆大小	esp_get_free_heap_size()
sys_chip	打印芯片型号、核心数、修订版本与特性	esp_chip_info()
sys_uptime	打印自启动以来的毫秒数	esp_timer_get_time() / 1000
sys_reboot	软件复位	esp_restart()

这 4 个命令在 esp_cli_service_create() 内部即完成预注册（cli_register_default_static_commands()，见 esp_cli_service.c），因此"始终可用"。

动态命令：svc 与 tool

CHANGELOG 所称的"动态 svc/tool 命令"实现集中在 esp_cli_service_cmd_dynamic.c，它们使用 esp_console_cmd_t 的 func_w_context 携带服务句柄作为上下文：

const esp_console_cmd_t svc_cmd = {
    .command = "svc",
    .help = "Service management: list/info/start/stop/pause/resume",
    .func_w_context = cmd_svc_dispatch,
    .context = svc,
};

（esp_cli_service_cmd_dynamic.c，tool 命令结构相同。）

svc 命令族支持六种子命令，其服务查找遵循"先查跟踪列表、后查绑定 manager"的顺序（find_service_for_cli()，L30-L89）：

svc list
svc info <service>
svc start <service>
svc stop <service>
svc pause <service>
svc resume <service>

• svc list 列出跟踪服务，并打印每个服务的类别、状态与 last_err（print_service_line()，L338-L360）；
• 生命周期子命令最终调用 esp_service_start/stop/pause/resume（L415-L444），这些接口定义于 esp_service.h，即从终端即可驱动任何已注册服务的状态机。

tool 命令族则面向 esp_service_manager 暴露的 JSON Schema 工具：

tool list
tool info <tool_name>
tool call <tool_name> [key=value ...]
tool call <tool_name> --json '<json_string>'

• tool list / tool info 通过 esp_service_manager_clone_tools() 获取深拷贝快照（L93-L101），避免与并发注销竞争；
• tool call 先按工具的 inputSchema 把 key=value 参数序列化为 JSON 对象（build_args_json_from_kv()，L193-L336），再调用 esp_service_manager_invoke_tool()（L656）执行。

参数解析：位置参数与 flag 风格选项

CHANGELOG 提到的"支持位置参数与 flag 风格选项"，对应 esp_cli_service_parse.c 中的三个严格解析函数：

• cli_parse_i64()（L14-L29）：基于 strtoll，校验 errno、非空输入与整串消费，用于 integer 字段；
• cli_parse_double()（L31-L46）：基于 strtod，用于 number 字段；
• cli_parse_bool()（L48-L62）：仅接受小写 true / false，用于 boolean 字段。

配合 add_typed_arg()（esp_cli_service_cmd_dynamic.c），key=value 风格的 tool call 会根据字段类型自动构造正确的 JSON 类型；遇到 array/object 等嵌套类型或非法 token、重复字段、未知字段、缺失必填字段时，会给出明确的错误提示并建议改用 --json。

v0.5.0~1：组件注册徽章

该版本仅更新文档：为 README.md 与 README_CN.md 添加了 Component Registry 徽章。这意味着组件已发布到 Espressif 组件注册表，可通过 idf_component.yml 依赖声明直接引入（见下文 v0.5.2 的依赖配置）。

v0.5.1：USB Serial 与 USB CDC 后端支持

v0.5.1 的实质变化在 REPL 后端的可选择性。此前 esp_cli_service 仅面向 UART，现在 cli_on_start() 会按 sdkconfig 编译期宏选择后端（esp_cli_service.c）：

#if CONFIG_ESP_CONSOLE_UART_DEFAULT || CONFIG_ESP_CONSOLE_UART_CUSTOM
    /* UART（默认或自定义 UART）→ esp_console_new_repl_uart() */
#elif CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG
    /* USB Serial/JTAG → esp_console_new_repl_usb_serial_jtag() */
#elif CONFIG_ESP_CONSOLE_USB_CDC
    /* USB CDC → esp_console_new_repl_usb_cdc() */
#else
    /* 无可用后端 → ESP_ERR_NOT_SUPPORTED */
#endif

实际使用中只需在 sdkconfig 中选择 IDF 的 console 类型：

CONFIG_ESP_CONSOLE_UART_DEFAULT=y
CONFIG_ESP_CONSOLE_UART_BAUDRATE=115200
CONFIG_ESP_CONSOLE_UART_NUM=0

以上三行来自示例工程的 sdkconfig.defaults。若你的板卡需要 USB 串口或 USB CDC 作为交互终端，可改为 CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG=y 或 CONFIG_ESP_CONSOLE_USB_CDC=y（以当前 ESP-IDF 版本支持的选项为准），代码无需任何改动，这正是该版本"增加 USB Serial 与 USB CDC 支持"的实现机理。

v0.5.2：cJSON 依赖切换

v0.5.2 将 JSON 解析依赖从 IDF 内置组件切换到组件注册表发布版本，体现在 idf_component.yml：

dependencies:
  espressif/esp_service:
    require: public
    version: "^0.5"
    override_path: "../esp_service"
  espressif/cjson:
    version: '^1.7'

其中 espressif/cjson 即 CHANGELOG 所述"来自组件注册表的 cJSON"。esp_cli_service 的源码中，cJSON.h 被用于 esp_cli_service_cmd_dynamic.c 的 Schema 解析、参数类型判定与 JSON 序列化，以及示例程序中的参数读取。该组件同时依赖 esp_service（通过 override_path 指向本仓库的 components/esp_service，即使用本地源码而非注册表副本），并在 CMakeLists.txt 中声明 console 与 vfs 两个 REQUIRES 依赖。

完整配置指南：esp_cli_service_config_t

公共配置结构定义于 esp_cli_service.h，字段含义与默认值如下：

字段	类型	说明	默认值
struct_size	uint32_t	必须等于 sizeof(esp_cli_service_config_t)，用于 ABI 校验	由宏自动设置
reserved[2]	uint32_t	保留字段，必须为零	{0, 0}
base_cfg	esp_service_config_t	核心服务注册配置（服务名等）	ESP_SERVICE_CONFIG_DEFAULT()
prompt	const char *	REPL 提示符（创建时内部拷贝）	"cli>"
max_cmdline_length	uint16_t	最大命令行长度	256
task_stack	uint32_t	REPL 任务栈大小（字节）	4096
task_prio	uint32_t	REPL 任务优先级	2
manager	esp_service_manager_t *	可选管理器，供 tool 命令使用（也是 svc 的兜底查找来源）	NULL

推荐做法是用宏初始化后再按需覆盖：

esp_cli_service_config_t cfg = ESP_CLI_SERVICE_CONFIG_DEFAULT();
cfg.prompt = "app>";
cfg.max_cmdline_length = 512;   /* 按需加大命令行上限 */
cfg.manager = mgr;              /* 绑定 manager，启用 tool 命令 */

参数取值范围与校验

esp_cli_service_create() 在 esp_cli_service.c 中对配置做了严格的运行时校验：

• struct_size 必须精确等于 sizeof(esp_cli_service_config_t)，reserved 必须为零，否则返回 ESP_ERR_INVALID_ARG；
• max_cmdline_length 有效范围 32～8192（源码常量 ESP_CLI_SERVICE_MAX_CMDLINE_LENGTH_MIN/MAX，L23-L24）；
• task_stack 有效范围 2048～512×1024 字节（L25-L26）；
• task_prio 必须 ≥ 1 且小于 configMAX_PRIORITIES（L27、L337）；
• 任一字段取 0 时会被替换为默认值（L324-L326）。

这些约束使配置错误在 create 阶段即可被发现，而非在 REPL 运行时才暴露。

快速上手：完整示例工程

示例位于 components/esp_cli_service/examples/，核心代码在 examples/main/app_main.c，它演示了三条核心用法：

1. 创建并绑定 manager 与 CLI（L618-L638）：

esp_service_manager_t *mgr = NULL;
esp_service_manager_config_t mgr_cfg = ESP_SERVICE_MANAGER_CONFIG_DEFAULT();
ESP_ERROR_CHECK(esp_service_manager_create(&mgr_cfg, &mgr));

esp_cli_service_t *cli = NULL;
esp_cli_service_config_t cli_cfg = ESP_CLI_SERVICE_CONFIG_DEFAULT();
cli_cfg.base_cfg.name = "esp_cli_service";
cli_cfg.prompt = "adf_cli>";
cli_cfg.manager = mgr;
ESP_ERROR_CHECK(esp_cli_service_create(&cli_cfg, &cli));

2. 跟踪服务并注册静态命令（L640-L653）：

ESP_ERROR_CHECK(esp_cli_service_track_service(cli, &player->base, "audio"));
ESP_ERROR_CHECK(esp_cli_service_track_service(cli, &led->base, "display"));
ESP_ERROR_CHECK(esp_cli_service_track_service(cli, &wifi->base, "network"));

const esp_console_cmd_t ping_cmd = {
    .command = "ping",
    .help = "Simple static command registered by app",
    .func = cmd_ping,
};
ESP_ERROR_CHECK(esp_cli_service_register_static_command(cli, &ping_cmd));

3. 启动服务与 REPL（L655-L656）：

ESP_ERROR_CHECK(esp_service_manager_start_all(mgr));
ESP_ERROR_CHECK(esp_service_start((esp_service_t *)cli));

示例中 player（audio）、led（display）、wifi（network）三个 demo 服务通过 esp_service_manager_register() 注册，每个服务附带一段 JSON 数组形式的工具描述（s_player_tool_desc 等，如 L187-L193）。启动后终端出现 adf_cli> 提示符，即可直接体验示例日志建议的命令（L659-L663）：

svc list
tool list
tool call player_service_set_volume volume=75
tool call wifi_service_simulate_got_ip ip=192.168.1.2

构建烧录方式（README.md）：

idf.py set-target <chip>
idf.py build flash monitor

组件测试脚本 examples/pytest_esp_cli_service_example.py 会在 esp32s3 目标上验证固件启动后输出 CLI ready. 标志，可作为冒烟验证的参考。

命令实战：系统、服务与工具三层命令

系统命令（始终可用）

sys_heap      →  heap_free=xxxxxx
sys_chip      →  chip_model=N cores=2 revision=vX features=0x...
sys_uptime    →  uptime_ms=xxxxx
sys_reboot    →  rebooting...

svc 命令：从终端驱动服务生命周期

svc list
svc info player
svc start player
svc stop player
svc pause player
svc resume player

svc 可见的服务来源优先级：先查 esp_cli_service_track_service() 维护的跟踪列表，再查绑定的 manager（find_service_for_cli() 的既定逻辑）。因此即使某服务未显式跟踪，只要它注册在绑定的 manager 中，svc info/start/stop 也能生效（输出会标注 manager fallback，类别显示 <untracked>）。

tool 命令：JSON Schema 工具的调用入口

tool list
tool info player_service_set_volume
tool call player_service_set_volume volume=75
tool call led_service_blink --json '{"period_ms":300}'

tool call 的两种传参方式：

• key=value 风格：引擎解析工具 inputSchema，按字段类型自动转换——string 直接写入、integer 走 cli_parse_i64、number 走 cli_parse_double、boolean 仅接受 true/false；并校验必填字段（required）、拒绝未知字段与重复字段；
• --json '<json>' 风格：绕过 Schema 解析，直接透传完整 JSON 参数对象，适用于包含 array/object 嵌套类型等复杂 Schema 的场景。

调用结果（工具回调写出的 JSON 字符串）会直接打印到终端；空结果回退为 {}。工具执行的结果缓冲区上限为 2048 字节（CLI_TOOL_RESULT_MAX，esp_cli_service_cmd_dynamic.c），且结果缓冲分配在堆上而非栈上，以控制 REPL 任务栈占用。

底层架构与线程安全

从源码结构看，esp_cli_service 的运行时状态（esp_cli_service_internal.h）包括：

• base：内嵌的 esp_service_t 基类，负责服务状态机；
• manager：绑定的 esp_service_manager_t 指针；
• repl / repl_starting：REPL 实例与启动中间态标记；
• lock：FreeRTOS 互斥锁，保护 manager、repl 与两个向量；
• tracked：tracked_service_entry_t 向量（服务名/类别/指针）；
• static_cmds：static_cmd_entry_t 向量（命令描述符深拷贝 + 注册状态）。

线程安全策略：

• esp_cli_service_track_service()、untrack_service()、bind_manager()、register_static_command() 均受内部互斥锁保护（锁超时 1000ms，见 CLI_LOCK_TIMEOUT_MS，esp_cli_service.c），可从任意任务调用；
• create() / destroy() 需在服务静止（quiesced）状态下调用；
• 命令处理器通过 func_w_context 携带服务上下文，tool list/info 使用 esp_service_manager_clone_tools() 获取深拷贝快照，避免工具元数据在并发注销时失效。

常见问题排查

• 终端不出现提示符：确认已调用 esp_service_start()（REPL 任务仅在启动时创建）；检查串口端口、波特率（默认 115200）与 sdkconfig 中 console 类型；若注册命令分配大量数据，默认 4096 字节 task_stack 可能不足，可调大 cfg.task_stack。
• svc/tool 打印 "manager not bound"：需要在配置中设置 cfg.manager = my_mgr，或运行时调用 esp_cli_service_bind_manager() 绑定管理器。
• tool call 提示 "use --json"：工具的 inputSchema 含 array/object 等无法从 key=value 自动构造的字段类型，改用 tool call <name> --json '<json>' 传入完整参数。
• 版本与依赖：组件要求 ESP-IDF ≥ 5.4；依赖 espressif/esp_service（^0.5，本地 override_path）与 espressif/cjson（^1.7），详见 idf_component.yml。

小结

从 v0.5.0 的首版定型，到 v0.5.1 的 USB 后端扩展、v0.5.2 的 cJSON 依赖规范化，esp_cli_service 以三次迭代完成了从"基础可用"到"多后端、标准依赖"的演进。当前版本提供三层命令体系：内置系统命令用于快速诊断，svc 命令让服务生命周期控制触手可及，tool 命令则为 AI Agent 或主机侧自动化提供了一条基于 JSON Schema 的直接调用路径。若需在自有工程中复刻这套能力，可直接参考 components/esp_cli_service/examples/ 工程按上述流程接入。