钉钉操作优化指南

问题背景

在 Agent 场景里，调钉钉 DWS 经常不是“会不会写命令”的问题，而是命令选择、身份解析、认证状态和错误恢复被混在一起。同一个 openDingTalkId 可能不可复用，账号切换后 token 可能仍指向旧身份，文件消息和文本消息的参数也不同，中文参数在错误 locale 下可能直接写坏用户可见字段。本技能针对这些高频坑点给出操作前的判断规则，不重复官方命令表。

工作方式

它把钉钉操作拆成几类决策：

• 消息发送：优先原子命令 dws chat message send，群消息、单聊和机器人批量场景分别选择目标参数；内容含换行、引号等特殊字符时优先用 --text，避免位置参数被 shell 或 CLI 解释。
• 联系人身份：不把 openDingTalkId 当稳定主键，发送前用 dws contact user search --query 姓名 动态解析；脚本中保留 {name, openId} 结构，并在解析或发送失败时重新查询。
• 认证与恢复：切换账号后执行 dws auth logout 再重新登录；遇到认证类错误不要反复重试业务命令；stderr 出现 RECOVERY_EVENT_ID= 时进入 recovery 闭环，基于返回事实包判断。
• 事件与文件：事件监听优先 dws event consume --flatten，避免轮询消息历史，并对重复投递做 eventId / msgId 去重；文件发送先判断用户要“发文件”还是“发正文”，单聊文件场景先取 openConversationId。
• 中文本地化：在 LC_CTYPE=C 等弱 UTF-8 环境下，避免直接拼 shell 字符串，优先用 Python subprocess.run([...]) 传参数列表，再读 JSON 字段验证真实内容。

适用边界

该技能适合与官方 dingtalk-unified 和连接器 connector-dingtalk 配合，用于 Agent 生成钉钉操作前做检查。它不提供完整命令手册，也不保证覆盖所有 DWS 新行为；静态坑位记录会随版本演进变化，执行前仍应以命令返回、错误码和授权状态为准。