企业官网建设流程全解析

• 音视频
• 音频处理
• 嵌入式
• 物联网
• 语音

本文是 esp-adf 中esp_service组件框架级测试与仿真工具链（components/esp_service/test_apps）的完整实战指南。test_apps承担着与使用示例互补的使命：示例（components/esp_service/examples/mock_services）只演示如何使用六个 mock 服务，而真正压测框架本身（service manager、MCP JSON-RPC、四种传输通道、PC 仿真）的代码全部集中在这里。读完本文，你将掌握如何在真机上跑 Unity 单元测试与传输通道冒烟测试、如何用 Python 客户端脚本从工作站驱动开发板验证 HTTP/SSE/WS/UART 四种 MCP 传输，以及如何在 PC 上通过 FreeRTOS POSIX 移植构建出五个独立的仿真与测试可执行程序。

框架级测试的定位与设计思想

esp_service是一个将设备能力抽象为可注册服务、并通过 MCP（Model Context Protocol）JSON-RPC 暴露为可调用工具的框架。其测试策略分两层：

• 使用级验证：由 components/esp_service/examples/mock_services/README.md 对应的示例工程演示；
• 框架级验证：由本test_apps承载，覆盖 service manager、MCP JSON-RPC 协议、各传输通道以及 PC 仿真环境。

一个关键设计是mock 服务即取即用：六个 mock 服务（button_service、cloud_service、led_service、ota_service、player_service、wifi_service，位于 components/esp_service/examples/mock_services/components）通过EXTRA_COMPONENT_DIRS直接被 test_apps 消费，示例与测试因此天然保持同步——任何对 mock 服务的修改会同时作用于两边。这一点在设备端工程 components/esp_service/test_apps/CMakeLists.txt 中可以看到明确实现：

set(EXTRA_COMPONENT_DIRS "${_ESP_SERVICE_ROOT}" "${_MOCK_COMPS}" )

PC 侧工程同样复用同一份 mock 服务源码（EXAMPLE_COMPS_DIR指向../../examples/mock_services/components），并刻意将"纯服务逻辑"（example_services）与"MCP 适配层"（example_services_mcp）拆分为两个静态库，以便某个测试场景可以完全不链接 cJSON 与 MCP 代码，验证"零 MCP 依赖"的纯函数调用路径。

目录结构解析

components/esp_service/test_apps/ ├── CMakeLists.txt # IDF 设备端工程（EXTRA_COMPONENT_DIRS 引入 mock 服务） ├── sdkconfig.defaults # 设备端默认配置（传输开、冒烟测试关） ├── sdkconfig.ci # CI 注入 WiFi 凭据 ├── pytest_esp_service_test_apps.py ├── main/ # IDF 设备端运行器（Unity + 可选传输冒烟） │ ├── app_main.c │ ├── ut_esp_service_core.c │ ├── ut_service_manager.c │ ├── ut_*_transport.c # 由 Kconfig 门控（见 CMakeLists.txt） │ ├── ut_transport_lifecycle_test.c │ ├── ut_transport_smoke_helpers.h │ ├── Kconfig.projbuild │ └── CMakeLists.txt ├── scripts/ # PC 端 MCP JSON-RPC 客户端（对真机） │ ├── README.md │ ├── test_mcp_http.py # 纯 HTTP POST /mcp │ ├── test_mcp_sse.py # HTTP+SSE（配合 ESP_SVC_TEST_SSE_HOLD_AFTER_SMOKE） │ ├── test_mcp_ws.py # WebSocket（配合 ESP_SVC_TEST_WS_HOLD_AFTER_SMOKE） │ └── test_mcp_uart.py # UART（配合 ESP_SVC_TEST_UART_HOLD_AFTER_SMOKE） └── pc/ # PC / 主机端运行器（FreeRTOS POSIX 移植，原生 CMake） ├── CMakeLists.txt ├── FreeRTOSConfig.h ├── service_sim_example.c ├── sim_support.{c,h} ├── service_tool_dispatch_test.c ├── service_integration_test.c ├── service_coverage_test.c ├── mcp_http_server.c ├── svc_helpers.h ├── host_http_transport.{c,h} ├── embedded_files.c # JSON schema 数据块 └── compat/ # IDF → POSIX 垫片（esp_err.h、esp_log.h、esp_timer.h 等）

设备端各测试文件的编译由 components/esp_service/test_apps/main/CMakeLists.txt 按 Kconfig 开关逐个追加：

if(CONFIG_ESP_SVC_TEST_ENABLE_LIFECYCLE_STRESS) list(APPEND srcs "ut_transport_lifecycle_test.c") endif() if(CONFIG_ESP_SVC_TEST_ENABLE_HTTP_TRANSPORT) list(APPEND srcs "ut_http_transport.c") endif() # ... SSE / WS / UART 同理

基础测试（ut_esp_service_core.c、ut_service_manager.c）始终编译，传输相关测试则完全由 Kconfig 门控，保证默认镜像只跑无网络依赖的纯框架测试。

设备端（IDF）测试：构建与运行

构建命令

cd components/esp_service/test_apps idf.py set-target esp32s3 idf.py menuconfig # 设置 Wi-Fi，在 "ESP Service test_apps Configuration" 下开关传输 idf.py build flash monitor

默认配置解读

[sdkconfig.defaults](https://link.gitcode.com/i/48294e905fe5334e2e13abf5698805d4)的默认策略是：MCP 网络传输全部启用，但所有设备端冒烟测试全部关闭：

CONFIG_ESP_MAIN_TASK_STACK_SIZE=4096 CONFIG_FREERTOS_HZ=1000 # 四种 MCP 传输通道全部编译进固件 CONFIG_ESP_MCP_ENABLE=y CONFIG_ESP_MCP_TRANSPORT_HTTP=y CONFIG_ESP_MCP_TRANSPORT_SSE=y CONFIG_ESP_MCP_TRANSPORT_WS=y CONFIG_ESP_MCP_TRANSPORT_UART=y # 默认只开生命周期压力测试；其余冒烟测试默认关闭 CONFIG_ESP_SVC_TEST_ENABLE_LIFECYCLE_STRESS=y # CONFIG_ESP_SVC_TEST_ENABLE_HTTP_TRANSPORT is not set # CONFIG_ESP_SVC_TEST_ENABLE_SSE_TRANSPORT is not set # CONFIG_ESP_SVC_TEST_ENABLE_WS_TRANSPORT is not set # CONFIG_ESP_SVC_TEST_ENABLE_UART_TRANSPORT is not set # 控制台走 UART0（CP2102 / ttyUSB0） CONFIG_ESP_CONSOLE_UART_DEFAULT=y # WebSocket 依赖 HTTP 服务器支持 CONFIG_HTTPD_WS_SUPPORT=y CONFIG_UNITY_ENABLE_64BIT=y

因此在默认配置下，固件只运行带[esp_service]标签的 Unity 测试（ut_esp_service_core+ut_service_manager，MCP 使用桩传输），无需网络即可完成。需要 SSE/WS/UART 冒烟或生命周期压力测试时，再在 menuconfig 中打开ESP_MCP_TRANSPORT_*与ESP_SVC_TEST_ENABLE_*。注意：HTTP / SSE / WS 三种传输冒烟测试同一时间只应启用一种。

CI 场景中，WiFi 凭据由 sdkconfig.ci 从环境变量注入：

CONFIG_ESP_SVC_TEST_WIFI_SSID="${CI_WIFI_SSID}" CONFIG_ESP_SVC_TEST_WIFI_PASSWORD="${CI_WIFI_PASSWORD}"

自动化集成由 pytest_esp_service_test_apps.py 完成——它对 esp32s3 目标依次断言串口输出中的ESP Service - test_apps与TEST_APPS RUN COMPLETE两个标记：

@pytest.mark.generic @idf_parametrize('target', ['esp32s3'], indirect=['target']) def test_esp_service_test_apps(dut: IdfDut) -> None: dut.expect(r'ESP Service - test_apps', timeout=60) dut.expect(r'TEST_APPS RUN COMPLETE', timeout=600)

设备端运行流程（app_main）

main/app_main.c 的执行顺序清晰地呈现了测试层级：

1. 调用esp_service_ut_core_force_link()与esp_service_ut_manager_force_link()，防止--gc-sections丢弃TEST_CASE的构造函数注册；
2. UNITY_BEGIN()后通过unity_run_tests_by_tag("[esp_service]", false)运行所有带该标签的 Unity 用例；
3. 依次执行 Kconfig 门控的集成演示：生命周期压力 → UART → WS → SSE → HTTP 冒烟测试；
4. 打印TEST_APPS RUN COMPLETE收尾。

Kconfig 测试开关全景

[main/Kconfig.projbuild](https://link.gitcode.com/i/6f7b655583ea882f8f7e8aac9ba9cd27)定义了ESP Service test_apps Configuration菜单，下表汇总全部选项（含默认值与依赖关系）：

几个值得注意的细节：

• SSE 端点布局：GET /mcp/sse建立事件流，POST /mcp/messages?sessionId=<id>发送请求（MCP 2024-11-05 风格）；
• WS 默认端点：ws://<ip>:8081/mcp，且 WS 传输依赖CONFIG_HTTPD_WS_SUPPORT=y；
• UART 默认引脚：ESP32-S3 UART0 的 GPIO43/44，115200 波特率；
• 生命周期压力测试在设备端刻意不测 STDIO 传输：ESP 控制台 VFS 后端是非阻塞的，会让 STDIO 读任务在循环间忙转从而触发任务看门狗；STDIO 的端到端覆盖由 PC 侧通过阻塞管道完成（见 main/ut_transport_lifecycle_test.c 的注释说明）。

设备端 Unity 测试内容

ut_esp_service_core.c（[esp_service][core] 组）聚焦 components/esp_service/include/esp_service.h 的公开 API 边界：

• NULL/非法参数拒绝：esp_service_init(NULL, ...)、esp_service_deinit(NULL)、各种get_*输出指针为 NULL 时均返回ESP_ERR_INVALID_ARG；
• 完整生命周期：INITIALIZED → RUNNING → INITIALIZED，验证get_state/get_name/get_user_data/is_running；
• 状态机非法转移：未初始化时start返回ESP_ERR_INVALID_STATE；
• 事件 API：publish_event拒绝 service 为 NULL 或 event_id 为 0；state_to_str输出"RUNNING"等字符串；未知事件 ID 返回ESP_ERR_NOT_FOUND；
• on_init失败传播：esp_service_init将on_init回调返回的错误码（如ESP_ERR_INVALID_CRC）直接透传给调用者并完成清理。

ut_service_manager.c（[esp_service][manager] 组）使用内存桩传输（esp_service_mcp_trans_init+ 自定义ESP_SERVICE_MCP_TRANS_CUSTOMops），因此不依赖 STDIO/UART/WiFi 即可验证 manager 与 MCP 服务器逻辑：

• esp_service_manager_create/register/find_by_name的 NULL 参数拒绝；
• 空注册表下clone_tools返回 OK 且计数为 0；
• invoke_tool对未知工具返回ESP_ERR_NOT_FOUND；
• MCP 服务器创建时 tool_provider 或 transport 为 NULL 均被拒绝；
• 端到端协议验证：注册player_service（带player_service_mcp_schema()工具描述与player_service_tool_invoke）后，向桩传输上的 MCP 服务器发送{"jsonrpc":"2.0","id":1,"method":"tools/list"}，断言响应 JSON 中含player_service_set_volume；发送tools/call调用player_service_get_volume，断言响应含"result"与音量值33。

ut_transport_lifecycle_test.c对启用的非 WiFi 传输（UART）反复执行 create→start→stop→destroy，在每批前后采样堆使用量以暴露累积泄漏，专门防护读任务关闭路径、传输资源泄漏与 MCP 服务器跨传输状态跟踪三类回归。SSE/HTTP/WS 的生命周期压力则内嵌在对应ut_*_transport.c中，在 WiFi 就绪后执行。

PC 端脚本：从工作站驱动真机

固件启动后（SSE/WS/UART 需要同时打开对应的 "hold after smoke" 选项以获得长驻服务器），即可从工作站驱动开发板。务必在test_apps/目录下执行，保证 Python 导入与路径可预测：

cd components/esp_service/test_apps python3 scripts/test_mcp_http.py <device-ip> python3 scripts/test_mcp_sse.py <device-ip> [http-port] python3 scripts/test_mcp_ws.py <device-ip> [port] python3 scripts/test_mcp_uart.py <serial-port> [baud]

实例：

python3 scripts/test_mcp_http.py 192.168.1.100 python3 scripts/test_mcp_sse.py 192.168.1.100 8080 python3 scripts/test_mcp_ws.py 192.168.1.100 8081 python3 scripts/test_mcp_uart.py /dev/ttyUSB0 115200

Python 依赖：pip install requests（HTTP 客户端）、pip install websockets（WS 客户端）、pip install pyserial（UART 客户端）。

各脚本的测试策略：

• test_mcp_http.py：对http://<ip>:8080/mcp发起 18 项顺序测试——tools/list枚举工具、调用 player（play/set_volume 75/get_volume/get_status）、LED（blink 1000ms/get_state/set_brightness 80）、WiFi（get_status/get_ssid/get_rssi/reconnect 到GuestNetwork后复查 SSID）、OTA（get_version/check_update/get_progress），最后覆盖错误路径（invalid_tool_name、invalid/method）；
• test_mcp_sse.py：按 MCP 2024-11-05 风格实现最小 SSE 会话——GET /mcp/sse建立流，读取强制的endpoint事件，随后通过POST /mcp/messages?sessionId=...发送 JSON-RPC 并在 SSE 流上读取匹配的message事件（固件需ESP_SVC_TEST_ENABLE_SSE_TRANSPORT+ESP_SVC_TEST_SSE_HOLD_AFTER_SMOKE）；
• test_mcp_ws.py：基于websockets的异步客户端，验证持久连接、JSON-RPC 2.0 协议、工具枚举/调用、错误处理与多客户端并发；
• test_mcp_uart.py：基于pyserial的行式协议客户端——每行一条 JSON-RPC 请求（\n结尾），每行一条响应。内置 8 组功能测试：串口连接、工具枚举、工具调用（player/LED 全套）、多请求、错误处理（非法工具名、非法方法、畸形 JSON{broken json!!!、缺 method 字段）、10 连发吞吐（输出平均耗时与 req/s）、JSON-RPC 合规（响应含jsonrpc与匹配的id）、断线重连。脚本还会打印硬件接线提示：ESP32-S3 UART0 的 GPIO43(TX)/GPIO44(RX) 直连 USB 转串口芯片（也可用ESP_SVC_TEST_UART_TX_PIN/RX_PIN改引脚）。

PC（主机端）仿真：在开发机上跑 FreeRTOS

PC 侧是一个独立的原生 CMake 工程，基于FreeRTOS POSIX 移植（GCC_POSIX port，V11.2.0）拉起完整的 FreeRTOS 调度器、真实 TCP 套接字与多个服务实例，因此这些程序属于集成/场景测试而非 Unity 单元测试。

cd components/esp_service/test_apps/pc cmake -S . -B build -G Ninja && cmake --build build

构建脚本（pc/CMakeLists.txt）通过 FetchContent 拉取 FreeRTOS-Kernel 与 cJSON，并做了一件精巧的事：为 IDF 风格的#include "freertos/FreeRTOS.h"（带前缀）生成符号链接包装目录，同时用 pc/compat 下的esp_err.h、esp_log.h、esp_timer.h垫片把 IDF 依赖映射到 POSIX 环境，从而让esp_service核心代码几乎原样在 PC 上编译。

CMake 工程产出五个可执行程序：

service_sim_example：多服务事件拓扑仿真

该程序（pc/service_sim_example.c）构建了一个五服务 + 监控订阅者的完整事件拓扑：Button（随机 PROVISION/PLAY/VOL_UP/VOL_DOWN/MODE）、WiFi（随机 scan/connect/disconnect 并对按钮事件作出反应）、OTA（响应 WiFiGOT_IP并执行同步升级流）、Player（随机动作并对 button/wifi/ota 反应）、LED（事件驱动指示器）。sim_support.h定义了流量整形器（burst/bulk 事件参数）、运行 profile（sim_runtime_profile_t：时长、按钮次数、WiFi 轮数、OTA 上限、player 动作数、判定阈值）与跨服务订阅装配函数sim_setup_subscriptions，运行时可用SIM_SEED环境变量固定随机种子保证可复现。

service_tool_dispatch_test：无 MCP 的本地分发

该程序（pc/service_tool_dispatch_test.c）演示了 manager 的纯本地能力，六个演示步骤即为完整的 API 速查：

1. start_all：批量启动所有已注册服务；
2. find_by_name：按名查找（"player"命中、"nonexistent"返回ESP_ERR_NOT_FOUND）；
3. find_by_category：枚举同类别服务（player 与 led 同属"device"类别，用于演示异构服务枚举）；
4. invoke_tool：按工具名本地调用——player_service_play、player_service_set_volume {"volume":75}、player_service_get_status、led_service_blink {"period_ms":200}、led_service_get_state；
5. unregister：运行时动态摘除服务（先esp_service_stop再unregister）；
6. 直接 C API 与工具分发共存：led_service_on()、player_service_play()与 invoke_tool 可同时作用于同一实例。

值得注意，该测试工程刻意设置为auto_start_services = false，并只链接example_services_mcp+esp_service+cjson，不链接任何 MCP 传输——用链接层保证"本地分发不依赖网络协议"。

service_coverage_test：16 段全覆盖套件

pc/service_coverage_test.c 通过自研的微型断言宏（TEST_BEGIN/TEST_END/EXPECT/EXPECT_EQ）组织为 16 个独立区块（S1–S16），覆盖面远超设备端 Unity 用例：

• S1–S3：adf_event_hub的边界/NULL 覆盖、功能覆盖（sub/pub/unsub/queue/cb/ANY_ID）、统计与 payload 所有权/释放；
• S4–S6：服务核心边界、完整状态机迁移与非法转移、事件 API（publish/subscribe/last_error）；
• S7–S9：manager 边界、功能覆盖（register/find/invoke）、容量上限（max_services）；
• S10–S12：多线程压力——多发布者 + 回调订阅者、多发布者 + 队列订阅者、并发invoke_tool分发；
• S13：快速 create/start/stop/destroy 生命周期压力；
• S14：大动态 payload 由 hub 释放的压力测试；
• S15：错误路径——on_start失败会发出new_state=ERROR的STATE_CHANGED；publish_event在提前返回（非法参数/无 hub）时调用release_cb，保证调用方永不泄漏；
• S16：UAF 回归——一个任务持续 unregister/re-register 服务的同时，另一任务并发invoke_tool。

service_integration_test：三种交互模式共存

pc/service_integration_test.c 模拟真实嵌入式设备的四服务并发场景（player/led/button/wifi + MCP HTTP 服务器），用三个 FreeRTOS 任务同时走三条路径：Mode A直接 C API（延迟敏感的设备内逻辑）、Mode B经esp_service_manager_invoke_tool的本地工具分发（无网络、无 JSON-RPC 帧）、Mode C远程 AI Agent 经 HTTPPOST /mcp发送tools/call。事件驱动层则由 button_service 的按键事件（PLAY/VOL_UP/VOL_DOWN/MODE）与 wifi_service 的连接事件（CONNECTING/CONNECTED/GOT_IP/DISCONNECTED）驱动 player 与 LED。程序内置统计计数器（直接调用/分发调用/MCP 调用/事件回调），运行约 12 s（TEST_DURATION_MS 12000）后校验结果；传--llm参数则测试结束后保持 HTTP 服务器存活，供外部 LLM bridge（mcp_bridge.py）交互式或批处理接入。

mcp_http_server：可联调 LLM 的常驻服务器

pc/mcp_http_server.c 是一个"运行时目标"而非自包含测试：创建 manager（auto_start_services = true），注册 player（类别audio）、led（display）、ota（system）、wifi（network）四个 mock 服务，随后通过svc_mcp_http_start(mgr, port, ...)在MCP_PORT环境变量指定的端口（默认 9876）上提供http://127.0.0.1:<port>/mcp服务。程序持续运行直到收到 SIGINT/SIGTERM，对外暴露如wifi_service_get_status/get_ssid/get_rssi/reconnect、OTA 版本/升级等工具，配合 tools/mcp_llm_bridge 可让 LLM 直接调用这些"设备能力"。

相关资源

• 使用示例（本测试框架的配套工程）：components/esp_service/examples/mock_services
• 组件 README：components/esp_service/README.md
• mcp_http_server的 LLM bridge：tools/mcp_llm_bridge/README.md
• PC 客户端脚本说明：components/esp_service/test_apps/scripts/README.md

小结

esp_service的 test_apps 呈现了一条完整的"框架级验证链路"：设备端用 Unity 验证 API 边界与状态机（不依赖网络），用 Kconfig 门控的传输冒烟与生命周期压力测试验证四种 MCP 通道的真实可用性；PC 端用 FreeRTOS POSIX 移植把同一份框架代码搬到开发机，以五个可执行程序覆盖纯函数调用、本地工具分发、MCP-over-HTTP、全覆盖压力与多模式集成；最后由 Python 客户端脚本把真机与工作站串成端到端闭环。这套"示例即用、测试即证"的架构，让esp_service的服务抽象、MCP 协议实现与传输层可以在最小成本下获得持续的回归保障。

• 音视频
• 音频处理
• 嵌入式
• 物联网
• 语音