深入解析 TEN Framework C++ 扩展示例：simple_echo_cpp 回声扩展实现与集成指南

人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载导读simple_echo_cpp是 TEN Framework 官方提供的一个用 C 编写的最小化扩展示例包它接收来自 TEN Graph 的命令cmd、数据data、视频帧video_frame与音频帧audio_frame并原样或在命令名后追加 , too回传给调用方是理解 TEN 扩展Extension生命周期、消息类型体系与 C 绑定 API 的理想起点。读完本文你将掌握一个 C 扩展包的完整组成源码、清单、构建脚本、四大消息回调的实现套路以及如何将扩展节点接入 TEN 应用图graph进行实际运行验证。一、包概览一个最小化 C 扩展的完整骨架该包位于仓库 packages/example_extensions/simple_echo_cpp 目录下整个包由五个文件组成结构如下文件作用src/main.cc扩展的核心实现定义simple_echo_extension_t并注册为 addonmanifest.json包的元数据清单类型、名称、版本、多语言展示名与依赖声明property.json扩展默认属性配置本示例为空对象{}BUILD.gnGN 构建脚本声明打包资源、编译源文件与依赖docs/多语言 READMEen-US、zh-CN、zh-TW、ja-JP、ko-KR从 manifest 可以看出该包的类型为extension名称simple_echo_cpp版本0.11.73标签为cpp且唯一依赖是系统级包ten_runtime版本同样为0.11.73——这正是文档「前置条件manifest.json 中指定的必需依赖项」所指的内容即依赖声明位于 packages/example_extensions/simple_echo_cpp/manifest.json 的dependencies字段中。二、源码逐段解析四大消息回调的实现原理扩展主体定义在 src/main.cc 中。它继承自ten::extension_t构造函数将扩展名称透传给基类class simple_echo_extension_t : public ten::extension_t { public: explicit simple_echo_extension_t(const char *name) : ten::extension_t(name) {} ... };值得说明的是基类ten::extension_t定义见 core/include/ten_runtime/binding/cpp/detail/extension.h在构造时已通过ten_extension_create将on_configure、on_init、on_start、on_stop、on_deinit、on_cmd、on_data、on_audio_frame、on_video_frame九个 C 层回调函数与 C 层虚函数一一绑定。其中on_cmd等四个虚函数在基类中已有默认实现如on_cmd默认返回 default 结果见 extension.h而simple_echo_extension_t通过 override 重写了这四个消息回调构成了本示例的全部业务逻辑。2.1 on_cmd命令回显void on_cmd(ten::ten_env_t ten_env, std::unique_ptrten::cmd_t cmd) override { std::string cmd_name cmd-get_name(); auto cmd_result ten::cmd_result_t::create(TEN_STATUS_CODE_OK, *cmd); cmd_result-set_property(detail, cmd_name , too); ten_env.return_result(std::move(cmd_result)); }处理逻辑为读取命令名 → 创建状态码为TEN_STATUS_CODE_OK的结果对象 → 将detail属性设置为命令名, too→ 通过ten_env.return_result返回给调用方。这段代码演示了 TEN 命令-响应command/result机制的核心用法结果对象必须基于原命令创建以关联上下文返回内容存放在detail属性中。return_result的 C 封装位于 core/include/ten_runtime/binding/cpp/detail/ten_env.h底层最终调用 C APIten_env_return_result。2.2 on_data数据缓冲区复制回传void on_data(ten::ten_env_t ten_env, std::unique_ptrten::data_t data) override { auto buf >new_audio_frame-set_sample_rate(audio_frame-get_sample_rate()); new_audio_frame-set_bytes_per_sample(audio_frame-get_bytes_per_sample()); new_audio_frame-set_samples_per_channel(audio_frame-get_samples_per_channel()); new_audio_frame-set_channel_layout(audio_frame-get_channel_layout()); new_audio_frame-set_number_of_channels(audio_frame-get_number_of_channels()); new_audio_frame-set_timestamp(audio_frame-get_timestamp()); new_audio_frame-set_eof(audio_frame-is_eof()); new_audio_frame-set_data_fmt(audio_frame-get_data_fmt()); new_audio_frame-set_line_size(audio_frame-get_line_size());视频帧回调则复制宽高、像素格式、时间戳与 EOF 标志new_video_frame-set_width(video_frame-get_width()); new_video_frame-set_height(video_frame-get_height()); new_video_frame-set_pixel_fmt(video_frame-get_pixel_fmt()); new_video_frame-set_timestamp(video_frame-get_timestamp()); new_video_frame-set_eof(video_frame-is_eof());这段代码的工程价值在于当扩展需要透传或转发音视频帧时仅复制原始字节是不够的采样率、声道布局、像素格式、时间戳等元数据必须同步保留下游扩展才能正确解码与播放。示例中用到的audio_frame_t、video_frame_t的 getter/setter 接口分别定义于 core/include/ten_runtime/binding/cpp/detail/msg/audio_frame.h 与 core/include/ten_runtime/binding/cpp/detail/msg/video_frame.h。2.4 addon 注册TEN_CPP_REGISTER_ADDON_AS_EXTENSION文件末尾一行完成了扩展的注册TEN_CPP_REGISTER_ADDON_AS_EXTENSION(simple_echo_cpp, simple_echo_extension_t);该宏定义在 core/include/ten_runtime/binding/cpp/detail/addon_manager.h。宏展开后做了三件事生成 addon 类simple_echo_cpp_default_extension_addon_t实现on_create_instancenew出扩展实例与on_destroy_instancedelete销毁实例两个虚函数注册扩展通过ten_addon_register_extension将扩展名与 addon 实例注册到运行时并利用ten_path_get_module_path定位插件所在目录利用TEN_CONSTRUCTOR静态构造在程序加载阶段自动把注册函数挂入 addon manager从而无需手工初始化即可完成扩展的自我注册。这一机制意味着任何 C 扩展只要按此宏声明编译进应用后即可被 TEN 运行时按 addon 名称即 manifest 中的包名动态实例化。三、manifest.json扩展包的元数据契约manifest.json 是 TEN 包安装与加载的依据本示例完整清单的关键字段如下{ type: extension, name: simple_echo_cpp, version: 0.11.73, display_name: { locales: { zh-CN: { content: 简单回声 C 扩展 } } }, description: { locales: { zh-CN: { content: 使用 C 语言编写的 TEN Framework 简单回声扩展示例 } } }, readme: { locales: { zh-CN: { import_uri: docs/README.zh-CN.md } } }, tags: [cpp], dependencies: [ { type: system, name: ten_runtime, version: 0.11.73 } ], api: {} }字段语义说明type/name/version包类型extension、包名与版本号三者共同构成包的唯一标识display_name/description/readme面向不同语言区域en-US、zh-CN、zh-TW、ja-JP、ko-KR的展示信息readme.import_uri指向 docs/README.zh-CN.md这正是本包的说明文档被框架管理工具索引的入口tags检索与分类标签dependencies声明对系统包ten_runtime的依赖安装该扩展时会一并校验运行时版本api本示例为空即不对外暴露 schema 化的命令/数据接口对比可见interface_schema_check等测试会对带api的扩展做 schema 校验。四、BUILD.gn如何编译与打包BUILD.gn 定义了扩展的构建目标ten_package(simple_echo_cpp)package_kind extension声明这是扩展包resources打包时携带LICENSE、manifest.json、property.json以及docs/**目录下的全部多语言文档sources [ src/main.cc ]唯一的编译单元include_dirs指向//core/src与//core使源码能#include ten_runtime/binding/cpp/ten.hdeps链接//core/src/ten_runtime与//third_party/nlohmann_json源码头部#include nlohmann/json.hpp即依赖于此。此外当启用 ten_manager 时还会生成ten_package_publish(upload_simple_echo_cpp_to_server)目标用于将构建产物发布到包服务器。property.json在本包中为空对象{}表示扩展不声明任何默认属性。五、集成到 TEN 应用在 property.json 图中挂载扩展按照文档「此包可以根据框架规范集成到 TEN 应用程序中」的说明扩展需要被应用app的property.json中的predefined_graphs引用。仓库集成测试真实使用了本扩展例如 tests/ten_runtime/integration/cpp/interface_schema_check/interface_schema_check_app/property.json 中将其挂载为图节点并建立数据连接{ ten: { predefined_graphs: [ { name: default, auto_start: true, graph: { nodes: [ { type: extension, name: simple_http_server_cpp, addon: simple_http_server_cpp, extension_group: http_server }, { type: extension, name: simple_echo_cpp, addon: simple_echo_cpp, extension_group: echo }, { type: extension, name: default_extension_cpp, addon: default_extension_cpp, extension_group: default } ], connections: [ { extension: default_extension_cpp, data: [ { name: text_data, dest: [ { extension: simple_echo_cpp } ] } ] }, { extension: simple_echo_cpp, data: [ { name: text_data, dest: [ { extension: default_extension_cpp } ] } ] } ] } } ] } }接入时需要注意应用manifest.json的dependencies中需声明simple_echo_cpp依赖可参见 tests/ten_runtime/integration/cpp/interface_schema_check/interface_schema_check_app/manifest.json框架会据此安装/加载该扩展包图的nodes中addon字段值必须与扩展包的manifest.json中的name一致此处即simple_echo_cppconnections中按消息类型cmd/data/audio_frame/video_frame声明数据流方向simple_echo_cpp收到的每种消息都会被回传因此适合置于数据链路的中间做透传观测该扩展同样出现在 tests/ten_runtime/integration/cpp/restful/restful_app/property.json 与 tests/ten_runtime/integration/cpp/import_graph/import_graph_app/graphs/test_graph.json 等测试场景中作为 C 扩展与图编排的验证载体。六、运行与验证获取扩展包按照 TEN Framework 的包安装指南使用 tman 等工具将simple_echo_cpp安装到应用目录的ten_packages/extension/下其依赖ten_runtime系统包会被自动解析版本要求见 manifest.json 的dependencies。构建通过 TEN 框架的 GN/ninja 构建体系编译应用simple_echo_cpp会按 BUILD.gn 中声明的deps链接运行时与 nlohmann_json。启动验证应用启动后向simple_echo_cpp节点发送命令命令结果中的detail字段应返回原命令名, too向节点发送数据、音频帧或视频帧对应消息应被原样含全部元数据回传。七、小结simple_echo_cpp虽然功能简单却是理解 TEN Framework C 扩展开发的最小闭环它完整覆盖了扩展类定义、addon 自注册宏、四类消息回调、缓冲区复制规范、manifest 依赖声明、GN 构建打包以及应用图挂载的全部环节。开发者可以此包为模板将on_cmd、on_data、on_audio_frame、on_video_frame四个回调替换为真实业务逻辑如调用 ASR/LLM/TTS 服务即可快速搭建自己的 C 扩展。相关资源扩展实现源码packages/example_extensions/simple_echo_cpp/src/main.cc包元数据packages/example_extensions/simple_echo_cpp/manifest.json构建配置packages/example_extensions/simple_echo_cpp/BUILD.gnC 绑定基类core/include/ten_runtime/binding/cpp/detail/extension.haddon 注册宏定义core/include/ten_runtime/binding/cpp/detail/addon_manager.h集成测试图配置tests/ten_runtime/integration/cpp/interface_schema_check/interface_schema_check_app/property.json赞分享人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载相关推荐TEN Framework C 回声扩展 simple_echo_cpp 深度解析与集成实战TEN Framework C 回声扩展 simple_echo_cpp 深度解析与集成实战 simple_echo_cpp 是 TEN Framework人工智能AI Agent多模态语音AI 应用TEN Framework 官方 Python 回声扩展示例 simple_echo_python 完全解读从安装集成到消息回显实现TEN Framework 官方 Python 回声扩展示例 simple_echo_python 完全解读从安装集成到消息回显实现 本篇技术指南围绕 TEN人工智能AI Agent多模态语音AI 应用TEN Framework 简单回声 Python 扩展simple_echo_python从源码到集成全解析TEN Framework 简单回声 Python 扩展simple_echo_python从源码到集成全解析 本指南以 TEN Framework 官方示人工智能AI Agent多模态语音AI 应用上一篇Rack::Cache源码解读核心类与关键方法的深度分析下一篇ZeroTierOne身份认证新范式zeroidc模块的Rust实现与应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考