TEN Framework simple_http_server_cpp 扩展详解：用 libwebsockets 把 HTTP 请求桥接为 TEN 命令

人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载本篇指南围绕 TEN Framework 示例扩展simple_http_server_cpp展开它用 C 与 libwebsockets 在本地启动一个 HTTP 服务器将收到的 HTTP 请求GET/POST 等转换为 TEN 运行时命令cmd转发给目标扩展再把命令结果的detail属性作为 JSON 响应返回。读完本文你将掌握该包的目录结构、manifest.json/property.json配置含义、安装与构建方式并能从源码层面理解 HTTP 事件回调、跨线程命令桥接与优雅停机的完整实现。扩展定位与包结构simple_http_server_cpp是 TEN Framework 官方示例扩展之一定位为“TEN Framework 的 C HTTP 服务器扩展”Korean 文档见 README.ko-KR.md同目录还提供英文、日文、简中、繁中版本。它把 TEN 应用变成可被外部进程/脚本通过 HTTP 调用的服务入口外部客户端发起一次 HTTP 请求扩展就构造并发送一条 TEN 命令命令结果决定 HTTP 响应内容。从包目录结构看该扩展是一个标准的 TEN 软件包packages/example_extensions/simple_http_server_cpp/ ├── BUILD.gn # GN 构建配置 ├── LICENSE # 许可证 ├── manifest.json # 包元数据与依赖声明 ├── property.json # 扩展属性默认端口 ├── docs/ # 多语言 README └── src/ └── main.cc # 扩展核心实现manifest.json包元数据与依赖声明manifest.json 声明了该包的关键信息{ type: extension, name: simple_http_server_cpp, version: 0.11.73, tags: [cpp], dependencies: [ { type: system, name: ten_runtime, version: 0.11.73 } ] }type为extension表明它是可被 TEN 应用编排的扩展包dependencies中声明了对系统包ten_runtime版本0.11.73的依赖这是该扩展唯一的运行时依赖即原 Korean 文档中“manifest.json 指定的必需依赖”的具体所指readme.locales把各语言 README 指到docs/README.*.md因此本文分析的 Korean 文档就是该包在包管理器界面展示的说明文档。property.json默认服务端口property.json 只有一项配置{ server_port: 8001 }这是扩展启动时 HTTP 服务监听的端口。从 main.cc 的on_start实现看扩展通过ten_env.get_property_int64(server_port)读取该属性仅当取值大于 0 时覆盖默认值int server_port DEFAULT_SERVER_PORT; // 8001 auto port ten_env.get_property_int64(server_port); if (port 0) { server_port static_castint(port); } http_server create_http_server(DEFAULT_SERVER_URL, server_port);因此默认监听地址由DEFAULT_SERVER_URL固定为127.0.0.1即服务只在本机可达默认端口DEFAULT_SERVER_PORT为8001main.cc#L19-L21如需换端口只需在应用集成时把该扩展实例的server_port属性改为其他合法端口值即可不需要改代码。前提条件与安装原 Korean 文档的安装部分要求满足manifest.json中的依赖、按 TEN Framework 包安装指南操作、以 C 编译器与tgn构建工具链为前提。结合仓库内文档完整流程如下1. 环境前提开发/构建 C 扩展需要C 编译器gcc 或 clang可参考 quick-start 指南 中“C Development Environment Requirements”一节安装TEN 的 C/C 构建工具tgn基于 Google GN可用仓库内脚本安装bash tools/tgn/install_tgn.sh脚本见 install_tgn.sh。2. 安装扩展包在 TEN 应用目录下安装该扩展及其ten_runtime依赖tman install extension simple_http_server_cpp安装后TEN 会在应用目录下生成ten_packages/extension/simple_http_server_cpp/安装目录随后由应用构建流程编译该 C 扩展。tman的包安装机制、C 扩展的编译与运行流程详见 quick-start.md 的 “Advanced: Developing and Building C Extensions” 章节。BUILD.gn如何把 libwebsockets 编译进扩展BUILD.gn 展示了该扩展的完整构建定义核心是一个ten_package目标ten_package(simple_http_server_cpp) { package_kind extension enable_build true resources [ LICENSE, manifest.json, property.json, ] # docs/** 下的多语言 README 也会作为资源打包 sources [ src/main.cc ] include_dirs [ //core/src, //core, ] deps [ :simple_http_server_cpp_copy_websockets, //core/src/ten_runtime, //third_party/libwebsockets, //third_party/nlohmann_json, ] }要点解读package_kind extension与manifest.json的type一致构建产物会被打包到${root_out_dir}/ten_packages/extension/simple_http_server_cpp/源码只有一个编译单元src/main.cc头文件搜索路径指向仓库的//core与//core/src对应main.cc中#include include_internal/ten_runtime/binding/cpp/ten.h这类内部头文件位于 core/include_internal/ten_runtime/binding/ 下以及ten_buf_t等底层缓冲工具buf.hdeps引入三个关键依赖//core/src/ten_runtimeTEN 运行时 C 绑定//third_party/libwebsocketsHTTP/WebSocket 服务端库//third_party/nlohmann_json请求体 JSON 解析ten_websockets_copy_deps目标会在安装阶段把 libwebsockets 的运行时库拷贝进扩展包的lib/目录保证运行时链接可用若启用了ten_enable_ten_manager还会生成ten_package_publish目标用于把构建产物上传到 TEN Manager 的包服务器。核心实现http_server_extension_t 生命周期main.cc 约 730 行整个扩展由一个继承ten::extension_t的类http_server_extension_t驱动并通过TEN_CPP_REGISTER_ADDON_AS_EXTENSION(simple_http_server_cpp, http_server_extension_t)注册为名为simple_http_server_cpp的扩展插件main.cc#L730-L731。启动创建服务器、TEN 代理与服务线程on_start中完成三件事main.cc#L524-L540按server_port属性创建http_server_t内部创建 libwebsockets 上下文创建ten::ten_env_proxy_t——这是 libwebsockets 线程回调进 TEN 线程世界的桥梁启动独立 HTTP 服务线程并调用ten_env.on_start_done()宣告启动完成。服务器上下文参数在lws_context_new中固定main.cc#L472-L490协议表protocols、服务名http_server、监听端口、connect_timeout_secs 30、keepalive_timeout 60。服务线程是一个简单循环main.cc#L506-L518while (n 0 (http_server-react_ten_stopping_state REACT_TEN_STOPPING_COMPLETED)) { n lws_service(http_server-lws_context, 0); } lws_context_destroy(http_server-lws_context);即只要 TEN 尚未停机完成就持续调用lws_service处理事件停机完成后销毁上下文。每笔 HTTP 事务的数据结构每一笔 HTTP 事务从协议绑定到解绑的生命周期由http_transaction_data_t描述main.cc#L42-L75成员含义req_buf/resp_buften_buf_t缓冲分别累积请求体与待发送的响应体wsi/lws_context当前连接与会话的 libwebsockets 句柄http_server反向指回服务器对象便于跨线程协调method/url解析出的 HTTP 方法与请求 URL所有进行中的事务保存在http_server_t的all_http_session_data列表中main.cc#L84-L94该列表同时承担“停机时是否还有未响应请求”的判定职责。HTTP 事件回调一次请求的完整路径libwebsockets 通过event_callbackmain.cc#L304-L458驱动整个 HTTP 流程关键事件如下LWS_CALLBACK_HTTP_BIND_PROTOCOL协议绑定时为本次事务分配req_buf/resp_buf默认容量DEFAULT_BUF_CAPACITY 512字节可自动增长并把会话压入all_http_session_dataLWS_CALLBACK_HTTP收到请求头。先用parse_http_method从 URI token 判定方法支持 GET/POST/PUT/PATCH/DELETE/OPTIONS见 main.cc#L232-L260。GET/DELETE/OPTIONS 无请求体立即走“无 body”分支其余方法等待请求体收齐LWS_CALLBACK_HTTP_BODY把分片请求数据追加进req_bufLWS_CALLBACK_HTTP_BODY_COMPLETION请求体收齐走“带 body”分支LWS_CALLBACK_HTTP_WRITEABLETEN 线程写入响应后此处把响应头 响应体发回客户端然后调用lws_http_transaction_completed结束事务LWS_CALLBACK_HTTP_DROP_PROTOCOL清理本事务资源并在“所有请求已处理且 TEN 正在停机”时推进停机流程LWS_CALLBACK_EVENT_WAIT_CANCELLED被lws_cancel_service唤醒时触发统一触发待发送响应的写出trigger_lws_write_out_timing并配合停机判定。响应写出分两段main.cc#L97-L164return_response_header用lws_add_http_common_headers写入固定状态码200 OK、Content-Type: application/json与响应长度return_response_body以LWS_WRITE_HTTP_FINAL写出响应体。响应体始终是纯 JSON 文本成功时为命令结果的detail属性失败时为错误说明字符串。HTTP 请求到 TEN 命令的桥接这是该扩展的核心价值把 REST 风格请求翻译成 TEN 命令。两条路径分别是send_ten_msg_without_req_bodymain.cc#L684-L728与send_ten_msg_with_req_bodymain.cc#L581-L682。无请求体方法名即命令名GET/DELETE/OPTIONS 请求不携带 JSON body扩展直接以 HTTP 方法字符串作为命令名std::string method get_http_method_string(http_session_data-method); // 如 HTTP_GET auto cmd ten::cmd_t::create(method.c_str()); cmd-set_property(method, method); cmd-set_property(url, http_session_data-url); ten_env.send_cmd(std::move(cmd), /* callback */);也就是说应用侧被调用的扩展只要处理HTTP_GET/HTTP_DELETE/HTTP_OPTIONS这三个命令名即可接入该 HTTP 服务器命令属性里还附带method与url供业务区分请求来源。带请求体JSON 决定命令类型与路由POST/PUT/PATCH 等请求会把整个 body 按 JSON 解析并遵循如下约定main.cc#L600-L647若 body 含ten.type close_app构造内置的ten::close_app_cmd_t把命令发给本地应用用于从 HTTP 触发应用关闭若 body 含ten.name以该值作为自定义命令名创建ten::cmd_t若还带ten.dest含app/graph/extension三个字段则把命令定向到指定的应用/图/扩展若没有ten字段默认退化为以 HTTP 方法字符串作为命令名最终请求 JSON 会额外注入method与url字段并通过cmd-set_property_from_json整体写入命令属性随命令一起投递。命令结果如何变回 HTTP 响应ten_env.send_cmd的回调运行在 TEN 线程中处理逻辑统一为main.cc#L652-L680命令发送失败err ! nullptr响应体为The command is not supported. err:错误信息发送成功读取cmd_result的detail属性并序列化为 JSON 字符串作为响应体若取不到detail则回退为{}若扩展已进入停机状态is_stopping不再向 libwebsockets 线程推数据交由停机流程统一收尾。跨线程协作机制请求处理横跨两个线程域libwebsockets 服务线程与 TEN 线程。桥接手段有两个ten_env_proxy-notify(lambda)在 lws 线程捕获的回调被投递到 TEN 线程执行发送命令、构造响应数据均在 TEN 线程完成lws_cancel_service与lws_callback_on_writableTEN 线程写响应完成后调用prepare_response_data_from_ten_world先更新resp_buf再lws_cancel_service唤醒服务循环trigger_lws_write_out_timing对每个有待发响应的会话执行lws_callback_on_writable最终由LWS_CALLBACK_HTTP_WRITEABLE完成实际写出main.cc#L191-L210。优雅停机状态机与未决请求收尾停机逻辑由原子状态react_ten_stopping_state驱动共三态REACT_TEN_STOPPING_NOT_START → REACT_TEN_STOPPING → REACT_TEN_STOPPING_COMPLETEDmain.cc#L77-L81。流程为on_stop被 TEN 运行时调用置is_stopping true、状态进入REACT_TEN_STOPPING并lws_cancel_service唤醒服务循环main.cc#L562-L568停机期间新请求一律不再处理LWS_CALLBACK_HTTP中直接lws_http_transaction_completed拒绝main.cc#L338-L343对已收到请求但尚未得到 TEN 响应的会话统一写入默认响应TEN is closed.当最后一个会话被清理LWS_CALLBACK_HTTP_DROP_PROTOCOL且无待发响应时LWS_CALLBACK_EVENT_WAIT_CANCELLED状态置为COMPLETED并通过ten_env_proxy-notify回到 TEN 线程执行proceed_to_stop_http_extensionjoin HTTP 服务线程、释放ten_env_proxy、释放http_server最后调用ten_env.on_stop_done()通知运行时停机完成main.cc#L213-L230。这套“先排空在途请求、再退出线程、最后释放资源”的顺序保证了停机过程无请求悬挂、无资源泄漏。使用方式与验证把该扩展加入某个 TEN 应用的编排后应用启动时它会在127.0.0.1:8001或你配置的端口监听。可用的验证方式1. 无 body 请求GET/DELETE/OPTIONScurl -X GET http://127.0.0.1:8001/any/path扩展会构造名为HTTP_GET的命令属性含methodHTTP_GET、url/any/path发往应用。目标扩展处理命令后若其cmd_result设置了detail属性HTTP 响应体即该detail的 JSON否则响应为{}或错误说明文本。2. 带 body 请求POST发送自定义命令并定向到指定扩展curl -X POST http://127.0.0.1:8001/action \ -H Content-Type: application/json \ -d { ten: { name: my_custom_cmd, dest: { app: , graph: , extension: my_extension } }, foo: bar }其中ten.name决定命令名my_custom_cmdten.dest决定命令路由目标其余 JSON 字段含注入的method/url整体作为命令属性携带。也可以触发内置关闭命令curl -X POST http://127.0.0.1:8001/ \ -d {ten: {type: close_app}}响应统一为 HTTP 200 application/json业务语义成功detail、{}回退、The command is not supported. err:...错误串需按上述规则解读。3. 端口调整修改应用侧该扩展实例的server_port属性即可默认8001来自 property.json。若端口被占用可参考 quick-start 指南 中 “Port 8001 Already in Use” 的排查方法lsof -i :8001等。许可证该包随附 LICENSE采用 Apache License 2.0源文件头部注释亦声明了这一点是 TEN Framework 项目的组成部分。小结simple_http_server_cpp虽然只有一个src/main.cc却完整演示了 C 扩展与外部世界交互的三条关键路径libwebsockets 事件驱动 HTTP 服务协议表、事件回调、事务缓冲、通过ten_env_proxy的跨线程命令桥接请求 JSON →ten::cmd_t→cmd_result.detail→ JSON 响应、以及基于原子状态机的优雅停机与资源回收。对希望给 TEN 应用增加本地 HTTP 控制面外部触发命令、查询结果、关闭应用的开发者而言它是可直接安装复用的现成扩展也是阅读 TEN C 扩展开发指南 后理解ten::extension_t生命周期机制的最佳实战样本。赞分享人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载相关推荐TEN Framework C HTTP Server 扩展深度解析simple_http_server_cpp 从请求接入到命令分发的完整实现TEN Framework C HTTP Server 扩展深度解析simple_http_server_cpp 从请求接入到命令分发的完整实现 本篇以人工智能AI Agent多模态语音AI 应用TEN Framework 原生接入 Anthropic Claudeanthropic_llm2_python 扩展实战指南TEN Framework 原生接入 Anthropic Claudeanthropic_llm2_python 扩展实战指南 anthropic_llm2_人工智能AI Agent多模态语音AI 应用在 TEN Framework 中集成 NVIDIA Riva TTSnvidia_riva_tts_python 扩展实现详解在 TEN Framework 中集成 NVIDIA Riva TTSnvidia_riva_tts_python 扩展实现详解 本篇技术指南以 TEN Fr人工智能AI Agent多模态语音AI 应用上一篇为什么XB1ControllerBatteryIndicator是Xbox玩家必备解决低电量焦虑的7大理由下一篇ChatGPT Prompts for Bug Bounty Pentesting实战利用Google Dorks进行高效Recon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考