前言¶
用命令行操作钉钉，第一道坎往往不是不会发消息，而是发消息时选错了参数：能发的文本没发出去、想@的人没@到、监听到的事件重复投递了一次、中文参数变成一串问号。这类问题通常不会在第一次执行时就暴露，而是在切换账号、重跑脚本、或者换一种发送方式之后才出现。
下面介绍的这个 Skill 不做命令字典，它只记录坑和决策规则：在什么场景下该选哪种发送方式、openDingTalkId 解析失败之后怎么自愈、切账号之后为什么要重新登录、监听事件为什么会重复、以及 dws 报错后如何走 recovery 闭环。它面向已经在用 DingTalk Workspace CLI（dws）的开发者，减少试错和重复排查的时间。
这是什么¶
这是一份社区发布的实战避坑手册，坐标 @user_f807d9b4/dingtalk-ops-playbook，版本 1.0.1，来源 community，分类 ai-agent，由 user_f807d9b4 发布，需要 API Key：否。
它不负责枚举 dws 的全部子命令，定位是「命令表之外的规则层」。当你不确定该用哪种方式发消息、不确定 openDingTalkId 能不能复用、或者不确定某个中文参数是否会乱码时，用它来做判断。
核心功能¶
以下是已核实的能力范围，共七项：
1、消息发送选型：给出在不同场景下（普通文本、需要@人、需要带格式）选择发送方式的规则，避免选错参数导致发送异常。
2、openDingTalkId 动态解析与自愈：openDingTalkId 不是永远稳定的输入，手册覆盖了动态解析的逻辑，以及解析失败时的自愈路径。
3、账号切换后重新登录：切换钉钉账号之后，原有的登录态不一定还有效，手册给出了重新登录的判断节点。
4、事件监听去重：监听钉钉消息事件时，可能出现重复投递，手册记录了去重的处理方法。
5、本地文件一步式发送：把本地文件发给钉钉的完整路径，避免分步操作中间出错。
6、中文参数乱码防护：中文参数在命令行传递过程中可能变成乱码，手册给出了防护做法。
7、dws recovery 恢复闭环：当 dws 命令报错或中途失败时，手册给出了恢复流程，而不是直接重试或放弃。
命令表本身以 dws --help 和「钉钉套件」技能为准，本 Skill 只记坑与决策规则，两者配合使用。
安装与启用¶
官方资料中未给出具体的安装命令、目录路径或配置文件字段。本 Skill 基于通用 SKILL.md 格式，因此需要把它放在支持该格式的 Agent 运行环境里才能加载，具体加载方式取决于你使用的客户端。
使用前确认两点：dws CLI 已安装且能在终端直接执行；你的运行环境支持加载通用 SKILL.md 格式的 Skill。至于各客户端（Cursor、Codex CLI、Claude Code 等）是否存在差异，官方资料中没有说明，此处不展开。
典型用法¶
官方简介给出的典型触发场景如下：
1、发消息遇到异常，不确定是参数问题还是方式选错时，先查消息发送选型规则。
2、发文件失败或中途断掉时，对照本地文件一步式发送的步骤排查。
3、@人不生效时，检查 openDingTalkId 的解析方式，而不是直接换一种写法重试。
4、监听到的事件重复出现时，先看事件监听去重的处理方式，再判断是不是重试逻辑的问题。
5、中文参数变成乱码时，按中文参数乱码防护的做法调整，而不是把参数改成英文规避。
6、dws 命令报错时，按 dws recovery 恢复闭环处理，避免在未恢复的状态下继续执行后续操作。
以上场景的共同点是：问题不在命令本身，而在命令之外的决策规则。这也是这个 Skill 存在的理由。
适用场景与注意¶
适合已经在用 dws CLI 操作钉钉、并且遇到上述七类问题之一的开发者。如果你还没用过 dws，先跑 dws --help 了解命令面，再回来看这份手册会更顺。
使用时要注意三点：
1、它不是命令字典，不要拿它查子命令参数，参数以 dws --help 为准。
2、它和「钉钉套件」技能配合使用，前者记坑，后者记命令，两者缺一不可。
3、资料中标注评分 100000、下载量 1325、安装数 0，这些是 SkillHub 页面上的公开数据，安装数为 0 不代表不可用，只能说明在页面统计口径下还没有记录到安装量。
结尾¶
这份手册的价值在于把踩过的坑固化成了判断规则，而不是事后描述。当你下一次需要在钉钉里发消息、发文件、@人、监听事件，或者发现 dws 命令报错时，先打开它对照一遍，能省掉大部分重复排查。
官方地址：https://api.skillhub.cn/user_f807d9b4/dingtalk-ops-playbook
SkillHub 页面：https://www.skillhub.cn/skills/user_f807d9b4/dingtalk-ops-playbook
