dingtalk-workspace-cli(dws)事件订阅实战：28类钉钉事件如何驱动Agent实时监听消息

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-cli

dingtalk-workspace-cli（命令名为dws）是钉钉官方开源的跨平台 CLI 工具。它的事件订阅能力通过钉钉 Stream 长连接，实时监听当前用户的 28 类钉钉事件——IM 消息、已读/撤回/表情、群生命周期、OA 审批、VoIP 来电、待办与互动卡片，并以 NDJSON 逐行输出到 stdout，是构建"事件驱动 Agent"的核心入口。本文带你从零基础完成第一次监听。

为什么用事件订阅，而不是轮询？

传统做法是每隔几秒调一次"拉消息列表"接口：延迟高、浪费配额，还容易漏事件。dws event的思路是反向推送：

1. 后台常驻一个bus进程，对钉钉维持一条个人 Stream 长连接；
2. 多个本地消费进程（consume）通过本地 socket 共享这一条连接；
3. 事件到达后格式化输出，Agent 直接读取管道即可。

💡 官方建议：不要写脚本轮询消息历史、审批列表或待办列表，实时监听一律走dws event。架构细节见 internal/event/doc.go 的包注释。

28类钉钉事件全景：5大类别一次看懂

官方只承认下表28 个事件码，完整目录可用dws event list --category <oa|voip|todo|card>查看：

📩 IM 消息类（16 个）

📋 OA 审批类（7 个）

task_created（新审批任务）、task_finished、task_redirected（转交）、instance_started（审批发起）、instance_cc（抄送我）、instance_terminated（终止）、instance_finished（完成）——均以user_oa_approval_为前缀。

📞 VoIP（1 个）与 ✅ 待办（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 ndjson

+listen-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 长连接，资源开销最小。

事件如何驱动 Agent：NDJSON 与 ready 契约

Agent 集成只需记住三件事：

1. 输出即管道：推荐--flatten -f ndjson，stdout 每行一个扁平 JSON，消息正文、发送人、会话 ID 直接读顶层content、sender、conversation_id，无需二次解析。
2. 等待 ready 标记：消费端启动后，stderr 会先输出[event] ready event_key=... bus_pid=... subscribe_id=...，Agent 看到该行再开始读 stdout，不要靠sleep猜。
3. 优雅退出与自动清理：本次新建的订阅在进程退出时自动退订；用--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 # 再确认

常见问题排查

多组织场景下，解析人名/群名与event consume/status/stop必须使用同一个全局--profile，不要把 A 组织解析出的 ID 带入 B 组织。

延伸资料

• 事件完整参考（28 个事件码、意图映射表、输出字段）：skills/mono/references/products/event.md
• Agent Skill 入口与 Golden Route：skills/multi/dingtalk-event/SKILL.md，OA/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