深入解析 TEN Framework C++ 扩展示例：simple_echo_cpp 回声扩展实现与集成指南-平芜编程栈

人工智能
AI Agent
多模态
语音
AI 应用

【免费下载链接】ten-framework

Open-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`并注册为 addon
`manifest.json`	包的元数据清单：类型、名称、版本、多语言展示名与依赖声明
`property.json`	扩展默认属性配置，本示例为空对象`{}`
`BUILD.gn`	GN 构建脚本，声明打包资源、编译源文件与依赖
`docs/`	多语言 README（en-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_ptr<ten::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_ptr<ten::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_instance（new出扩展实例）与on_destroy_instance（delete销毁实例）两个虚函数；
注册扩展：通过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.h"；
deps：链接//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_cpp）；
connections中按消息类型（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++ 扩展。