dingtalk-workspace-cli(dws)事件订阅实战28类钉钉事件如何驱动Agent实时监听消息【免费下载链接】dingtalk-workspace-cliDingTalk Workspace is an officially open-sourced cross-platform CLI tool from DingTalk. It unifies DingTalk’s full suite of product capabilities into a single package, is designed for both human users and AI agent scenarios.项目地址: https://gitcode.com/gh_mirrors/di/dingtalk-workspace-clidingtalk-workspace-cli命令名为dws是钉钉官方开源的跨平台 CLI 工具。它的事件订阅能力通过钉钉 Stream 长连接实时监听当前用户的 28 类钉钉事件——IM 消息、已读/撤回/表情、群生命周期、OA 审批、VoIP 来电、待办与互动卡片并以 NDJSON 逐行输出到 stdout是构建事件驱动 Agent的核心入口。本文带你从零基础完成第一次监听。为什么用事件订阅而不是轮询传统做法是每隔几秒调一次拉消息列表接口延迟高、浪费配额还容易漏事件。dws event的思路是反向推送后台常驻一个bus进程对钉钉维持一条个人 Stream 长连接多个本地消费进程consume通过本地 socket 共享这一条连接事件到达后格式化输出Agent 直接读取管道即可。 官方建议不要写脚本轮询消息历史、审批列表或待办列表实时监听一律走dws event。架构细节见 internal/event/doc.go 的包注释。28类钉钉事件全景5大类别一次看懂官方只承认下表28 个事件码完整目录可用dws event list --category oa|voip|todo|card查看 IM 消息类16 个事件码触发场景user_im_message_receive_at有人 我user_im_message_receive_o2o/_o2o_all指定/全部单聊消息user_im_message_receive_group/_group_all指定/全部群聊消息user_im_message_receive_user某人发给我的消息单聊群聊user_im_message_read_o2o/_group我发的消息被已读user_im_message_recall_o2o/_group消息被撤回user_im_message_reaction_o2o/_group消息收到表情回应user_im_group_updated/member_added/member_exited/disbanded群改名、成员进出、群解散 OA 审批类7 个task_created新审批任务、task_finished、task_redirected转交、instance_started审批发起、instance_cc抄送我、instance_terminated终止、instance_finished完成——均以user_oa_approval_为前缀。 VoIP1 个与 ✅ 待办3 个user_voip_call_receive_invite收到语音通话邀请user_todo_task_create/update/delete与我相关的待办变化可用--role-types creator,executor,participant限定角色 互动卡片1 个user_card_action_triggered用户点击卡片按钮等业务回调快速上手3 条命令完成第一次监听前置条件已安装dws并执行过dws auth login登录。第一步监听我的消息dws event listen-im --kind at-me -f ndjsonlisten-im是普通 IM 监听的快捷方式它把自然意图编译成底层事件码自动拉起 bus 并输出就绪标记。第二步监听某人或某个群# 监听指定人的消息 表情回应直接用中文姓名 dws event listen-im --kind sender --user-query 张三 --events message,reaction -f ndjson # 监听指定群的消息、已读、撤回 dws event listen-im --kind group --chat-query 项目冲刺 --events message,read,recall -f ndjson第三步用高级 consume 消费 OA / VoIP / 待办事件# 新的审批任务创建时通知我 dws event consume user_oa_approval_task_created --flatten -f ndjson # 监听 VoIP 来电邀请 dws event consume user_voip_call_receive_invite --flatten -f ndjson # 同时监听三个待办事件共享一个角色范围 dws event consume user_todo_task_create user_todo_task_update user_todo_task_delete \ --role-types executor --flatten -f ndjson⚡ 同一目标的兼容事件尽量合并到一个 consume 进程里如上面把三个待办事件合并它们共享一条 bus 长连接资源开销最小。事件如何驱动 AgentNDJSON 与 ready 契约Agent 集成只需记住三件事输出即管道推荐--flatten -f ndjsonstdout 每行一个扁平 JSON消息正文、发送人、会话 ID 直接读顶层content、sender、conversation_id无需二次解析。等待 ready 标记消费端启动后stderr 会先输出[event] ready event_key... bus_pid... subscribe_id...Agent 看到该行再开始读 stdout不要靠sleep猜。优雅退出与自动清理本次新建的订阅在进程退出时自动退订用--max-events 10或--duration 5m可让监听自动收尾。子进程完整契约ready 行格式、退出码、stdin 关闭停机见 docs/event-subprocess-contract.md。典型 Agent 场景收到消息自动回复监听本身不发消息。事件到达后把顶层conversation_id群聊或sender_open_dingtalk_id单聊交给dws chat messages-send即可完成监听 → 决策 → 回复闭环dws event listen-im --kind sender --user-query 李四 -f ndjson # 事件行 → 解析 content/sender → 调用 dws chat messages-send 回复管理订阅生命周期dws event status --event user_im_message_receive_at # 查看订阅与 bus 状态 dws event stop subscribe_id --dry-run # 先预览 dws event stop subscribe_id --yes # 再确认常见问题排查症状处理bus 启动失败多为登录态过期dws auth status检查过期则dws auth login重登挂住没有输出误加了--foreground只跑 bus 不打印事件去掉即可有残留连不上dws event status查 stale用event stop --all --dry-run预览后--yes清理自测收不到消息自己发的消息会被isSelfLoop过滤请用他人或机器人发消息验证多组织场景下解析人名/群名与event consume/status/stop必须使用同一个全局--profile不要把 A 组织解析出的 ID 带入 B 组织。延伸资料事件完整参考28 个事件码、意图映射表、输出字段skills/mono/references/products/event.mdAgent Skill 入口与 Golden Routeskills/multi/dingtalk-event/SKILL.mdOA/VoIP/Todo 细分参考在 skills/multi/dingtalk-event/references/ 目录命令实现internal/app/event_command.go、internal/app/event_personal_command.go事件管线源码bus、consume、去重、传输层internal/event/从一条命令监听 我到7 个 OA 事件同进程消费dws event已把 28 类钉钉事件收敛为统一的订阅、输出与生命周期模型——这正是驱动你的 Agent 从轮询者进化为实时响应者的完整路径。【免费下载链接】dingtalk-workspace-cliDingTalk Workspace is an officially open-sourced cross-platform CLI tool from DingTalk. It unifies DingTalk’s full suite of product capabilities into a single package, is designed for both human users and AI agent scenarios.项目地址: https://gitcode.com/gh_mirrors/di/dingtalk-workspace-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考