TEN Framework 钉钉机器人扩展集成指南：让 AI 助手通过 LLM 工具向钉钉群推送消息

人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载本指南围绕 TEN Framework 开源仓库中的dingtalk_bot_tool_python扩展展开讲解如何将该扩展作为 LLM 可调用工具集成到语音 AI 助手中使 AI 在对话中识别通知、提醒、群发等意图后自动向钉钉群聊发送文本消息。读完本文你将掌握该扩展的配置项含义、底层签名与发送原理以及把它接入voice-assistant示例应用的全流程实操方法。扩展概览一个会发消息的 LLM 工具dingtalk_bot_tool_python是 TEN Framework 生态中一个 Python 编写的扩展包位于 ai_agents/agents/ten_packages/extension/dingtalk_bot_tool_python。它本身不参与语音采集、识别或合成而是作为一个**工具Tool**挂载到 LLM 上当用户说出帮我通知团队今天下午 3 点开会这类指令时LLM 判断应当调用工具扩展随即通过钉钉群机器人的 Webhook 把消息推送到目标群聊。其核心特性包括LLM 工具集成以标准工具元数据向 LLM 注册send_message工具支持智能消息发送消息推送向钉钉群聊发送文本消息msgtype: text安全认证支持钉钉机器人的access_token与加签HMAC-SHA256 签名双重校验异步处理基于AsyncTenEnv与AsyncLLMToolBaseExtension构建非阻塞、高性能详细日志从启动、配置加载、工具注册到消息发送的每个环节都有结构化日志便于调试与监控。系统要求在集成前请确认环境满足以下条件依据 manifest.json 与 pyproject.toml 中的声明要求说明Python 版本文档要求 3.8pyproject.toml中requires-python 3.10建议按 3.10 准备TEN Runtime Python 0.11manifest 中ten_runtime_python版本声明为 0.11TEN AI Base 0.7manifest 中ten_ai_base版本声明为 0.7钉钉群机器人一个有效的自定义机器人 Webhook 及安全凭证依赖仅有一个requests用于向钉钉 API 发送 HTTP 请求requirements.txt中即一行requestspyproject.toml中进一步限定为requests2.34.2。安装依赖pip install -r requirements.txt源码结构从 Addon 注册到消息发送的实现链路在动手配置前先梳理扩展的源码结构有助于理解后续每个配置项的作用。包内关键文件如下ai_agents/agents/ten_packages/extension/dingtalk_bot_tool_python/ ├── README.md / README_CN.md # 使用文档 ├── __init__.py # 包初始化 ├── addon.py # Addon 注册入口 ├── extension.py # 扩展核心实现 ├── manifest.json # 扩展清单依赖、API 声明 ├── property.json # 默认属性凭证占位 ├── pyproject.toml # Python 工程配置 └── requirements.txt # 依赖列表Addon 注册addon.pyaddon.py 通过register_addon_as_extension(dingtalk_bot_tool_python)将扩展注册为名为dingtalk_bot_tool_python的 addon并在on_create_instance中创建DingTalkBotExtension实例register_addon_as_extension(dingtalk_bot_tool_python) class DingTalkBotAddon(Addon): def on_create_instance(self, ten_env: TenEnv, name: str, context) - None: ten_env.on_create_instance_done(DingTalkBotExtension(name), context)这就是为什么在图的节点配置中name与addon都填写dingtalk_bot_tool_python——addon对应注册名name是图中实例名。扩展核心extension.pyextension.py 是核心实现包含三大部分工具元数据定义工具名为send_message描述为 Send a message to DingTalk group chat. Use this when user wants to notify team members or send information to DingTalk.唯一参数contentstring 类型、必填即要发送的消息内容。生命周期方法on_start中通过DingTalkBotConfig.create_async(ten_envten_env)异步加载配置对应property.json中的access_token与secret随后构造tool_register命令并send_cmd发送给主控制器完成工具注册on_cmd中处理tool_call命令解析工具名与arguments命中send_message时调用run_tool执行。消息发送实现_send_dingtalk_message方法负责构造 Webhook URL 并 POST 文本消息其中签名逻辑严格对应钉钉官方加签算法if secret: timestamp str(round(time.time() * 1000)) secret_enc secret.encode(utf-8) string_to_sign {}\n{}.format(timestamp, secret) string_to_sign_enc string_to_sign.encode(utf-8) hmac_code hmac.new( secret_enc, string_to_sign_enc, digestmodhashlib.sha256 ).digest() sign urllib.parse.quote_plus(base64.b64encode(hmac_code)) webhook_url f{webhook_url}timestamp{timestamp}sign{sign}即以毫秒时间戳timestamp \n secret作为待签名字符串用secret作为密钥做 HMAC-SHA256再经 Base64 编码与 URL 编码得到sign拼接到 Webhook 上最终请求体为{msgtype: text, text: {content: content}}。发送结果以errcode 0判定成功失败时把钉钉返回的错误码与错误信息回传给 LLM方便模型向用户解释原因。API 契约manifest.jsonmanifest.json 声明了扩展的 APIcmd_intool_call属性含namestring必填与argumentsobjectcmd_outtool_register属性tool为包含name、description、parameters数组格式的对象返回结果含response。api.property.properties.params声明了两个可配置项access_token与secret与配置章节一一对应。这也印证了配置时需将凭证写入节点的property下也可包裹在params对象中取决于图配置写法BaseConfig.create_async会按声明结构读取。配置获取凭证并写入扩展属性获取钉钉机器人凭证在钉钉群中添加自定义机器人机器人类型选择自定义设置安全设置建议同时启用关键词与加签其中加签会生成secret从 Webhook 地址中提取access_tokenURL 中access_token后的部分若启用了加签保存secret密钥。配置文件设置编辑扩展的 property.json默认内容为两个空字符串占位{ access_token: your_dingtalk_access_token_here, secret: your_dingtalk_secret_here }在实际应用中更推荐把凭证写在应用图app 的property.json中对应扩展节点的property字段里并使用环境变量引用见下文避免敏感信息入库。重要安全提示不要将包含真实凭证的property.json提交到版本控制系统建议使用环境变量或密钥管理服务存储敏感信息。环境变量可选可以通过环境变量注入凭证。TEN 框架的图配置支持${env:VAR_NAME}语法voice-assistant示例中agora_rtc、stt、llm等节点即使用该语法因此可将节点属性写成property: { access_token: ${env:DINGTALK_ACCESS_TOKEN}, secret: ${env:DINGTALK_SECRET} }对应的环境变量设置export DINGTALK_ACCESS_TOKENyour_access_token export DINGTALK_SECRETyour_secret使用${env:VAR}语法后真实凭证只存在于运行环境中property.json可以安全入库。集成到 voice-assistant 示例完整三步原文档给出了把该扩展接入 ai_agents/agents/examples/voice-assistant 示例的详细步骤。以下是基于仓库实际文件manifest.json 与 property.json整理的完整流程。步骤 1添加扩展依赖编辑 ai_agents/agents/examples/voice-assistant/tenapp/manifest.json在dependencies数组中追加仓库中该文件第 157 行附近是weatherapi_tool_python依赖可紧随其后添加{ dependencies: [ // ... 其他依赖 ... { path: ../../../ten_packages/extension/dingtalk_bot_tool_python } ] }该相对路径从tenapp目录出发指向ai_agents/agents/ten_packages/extension/dingtalk_bot_tool_python与示例中其他扩展如weatherapi_tool_python的写法一致。步骤 2添加扩展节点编辑 ai_agents/agents/examples/voice-assistant/tenapp/property.json在ten.predefined_graphs[0].graph.nodes数组中追加钉钉扩展节点示例中weatherapi_tool_python节点之后是合适的插入位置{ type: extension, name: dingtalk_bot_tool_python, addon: dingtalk_bot_tool_python, extension_group: default, property: { access_token: your_dingtalk_access_token_here, secret: your_dingtalk_secret_here } }步骤 3注册工具到主控制器在同一个文件的connections部分找到main_control的cmd配置仓库中tool_register连接位于约第 120-128 行当前source中只有weatherapi_tool_python把钉钉扩展追加进source数组{ extension: main_control, cmd: [ { names: [ tool_register ], source: [ { extension: weatherapi_tool_python }, { extension: dingtalk_bot_tool_python } ] } ] }这条连接的意义在于dingtalk_bot_tool_python在on_start中会主动发送tool_register命令只有把它加入main_control的tool_register来源主控制器即 LLM 编排层才能收到并登记该工具。完整配置示例综合以上三步property.json中修改后的关键结构如下{ ten: { predefined_graphs: [ { name: voice_assistant, auto_start: true, graph: { nodes: [ // ... 其他节点(agora_rtc, stt, llm, tts 等) ... // 添加钉钉扩展节点 { type: extension, name: dingtalk_bot_tool_python, addon: dingtalk_bot_tool_python, extension_group: default, property: { access_token: your_dingtalk_access_token_here, secret: your_dingtalk_secret_here } } ], connections: [ { extension: main_control, cmd: [ // 注册工具到主控制器 { names: [tool_register], source: [ {extension: weatherapi_tool_python}, {extension: dingtalk_bot_tool_python} // 添加这一行 ] } ] } // ... 其他连接配置 ... ] } } ] } }需要修改的文件与配置参数汇总需要修改两个文件manifest.json示例约第 157 行添加扩展路径依赖property.json两处修改一处在nodes中新增扩展节点另一处在main_control的tool_register连接的source中追加钉钉扩展。核心配置参数参数类型必填说明access_tokenstring✅钉钉机器人的 access token取自 Webhook URLsecretstring✅钉钉机器人的加签密钥启用加签安全设置时获得extension_groupstring✅扩展组设置为default与weatherapi_tool_python同组便于统一管理验证配置与运行效果配置完成后启动 voice-assistant 应用观察日志确认扩展正常加载。扩展在on_start阶段会输出以下关键日志对应 extension.py 中的日志埋点[DingTalkBotExtension] on_start BEGIN [DingTalkBotExtension] Config loaded successfully [DingTalkBotExtension] - access_token: SET (length32) [DingTalkBotExtension] - secret: SET (length32) [DingTalkBotExtension] Registering tool with parameter array format... [DingTalkBotExtension] Tool registration result: ... [DingTalkBotExtension] on_start END 日志会回显access_token与secret是否已设置仅打印长度不泄露明文以及tool_register命令的返回结果可用于确认工具是否成功注册。正常运转时AI 与用户的交互效果如下用户: 帮我通知团队今天下午3点开会 AI: 好的我已经向钉钉群发送了会议通知钉钉群内收到的消息今天下午3点开会当send_message被执行时日志中会出现run_tool CALLED、DingTalk API response等记录若errcode 0扩展返回成功信息给 LLM否则会把钉钉的错误码与错误消息回传便于排查。常见问题排查Q配置后扩展没有加载检查manifest.json中dependencies里的路径是否正确指向ai_agents/agents/ten_packages/extension/dingtalk_bot_tool_python确认已运行task install安装依赖若使用 TEN Agent 的 Taskfile 工作流使扩展包被拉取到本地ten_packages目录观察启动日志中是否出现[DingTalkBotExtension] on_start BEGIN确认 addon 是否被创建addon.py 中on_create_instance会打印 Creating DingTalk Bot Extension instance。Q消息发送失败检查access_token与secret是否正确、是否与钉钉后台一致查看日志中的错误码与错误信息DingTalk API response中的errcode/errmsg常见如errcode310000签名错误或关键词不匹配等确认钉钉机器人的安全设置若启用了加签secret必须正确若启用了关键词消息内容需包含关键词否则钉钉会拒绝推送。Q工具未注册到 LLM检查connections中main_control的tool_register连接是否已将dingtalk_bot_tool_python加入source确认tool_register命令的连接配置正确且扩展与主控制器在同一图graph中确认扩展节点的extension_group设置为default与weatherapi_tool_python保持一致避免工具注册链路被分组隔离。小结dingtalk_bot_tool_python以标准的 LLM 工具形态为 TEN Framework 语音助手补上了钉钉群消息推送能力它通过tool_register完成工具登记通过tool_call接收 LLM 的调用意图内部用钉钉官方的 HMAC-SHA256 加签算法构造 Webhook 并发送文本消息全程异步并输出结构化日志。集成只需在应用的manifest.json与property.json中完成三处修改即可让 AI 助手在对话中自动完成群通知任务。若需自定义消息类型或扩展更多能力如 Markdown、ActionCard 消息可基于 extension.py 中的_send_dingtalk_message方法进一步改造。赞分享人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载相关推荐C无锁并发队列完整指南moodycamel::ConcurrentQueue单头文件集成与预分配调优C无锁并发队列完整指南moodycamel::ConcurrentQueue单头文件集成与预分配调优 最近给一条实时渲染管线做性能分析profiling人工智能AI Agent多模态语音AI 应用WePush钉钉消息推送机器人消息与工作通知的完整实现WePush钉钉消息推送机器人消息与工作通知的完整实现 想要实现高效的钉钉消息批量推送吗WePush作为一款专注批量推送的小而美工具提供了完整的钉钉消息推开发工具MeterSphere钉钉机器人消息通知配置指南MeterSphere钉钉机器人消息通知配置指南 问题背景 在使用MeterSphere测试平台时许多团队希望通过钉钉机器人接收项目相关的测试通知。近期有用户测试接口测试测试管理后端前端AI 应用上一篇Crawlee v3 升级指南从 Apify SDK v2 迁移到 Crawlee 的完整破坏性变更清单下一篇Mastra 云端部署与可观测性架构解析Deploy → Token → Traces → Storage 全链路实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考