前言¶
用命令行操作釘釘，第一道坎往往不是不會發消息，而是發消息時選錯了參數：能發的文本沒發出去、想@的人沒@到、監聽到的事件重複投遞了一次、中文參數變成一串問號。這類問題通常不會在第一次執行時就暴露，而是在切換賬號、重跑腳本、或者換一種發送方式之後纔出現。
下面介紹的這個 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
