前言¶

DSH 的插件化方式會把通道接入、工具調用和能力擴展拆成獨立組件。對於需要在釘釘裏使用本地 DeepSeek Harness（DSH）智能體的開發者，釘釘連接器主要解決兩個問題：消息通道是否能避開公網入站端點，以及二維碼、Client Secret、明文 /bind code 等敏感項如何避免進入機器可讀輸出或 checkpoint。

@dingtalk-real-ai/dsh-dingtalk 提供了一條基於 Stream 連接的釘釘接入路徑。它不要求公網入站端點，同時把需要人工處理的敏感憑據單獨交給本地終端完成。

這是什麼¶

@dingtalk-real-ai/dsh-dingtalk 是 DeepSeek Harness 的釘釘連接器，用於把本地 DSH 接入釘釘。倉庫地址是：

https://github.com/DingTalk-Real-AI/dsh-dingtalk

根據 package.json，許可證爲 MIT。該插件要求 Node.js 版本爲：

^22.19.0 || >=24.0.0

需要注意的是，這個機器人只在本地 dsh web 正在運行、並且電腦在線時可用。電腦睡眠、網絡斷開或本地進程退出後，它不會在雲端繼續運行。

核心功能¶

下面介紹已經列出的能力：

• 通過 Stream 連接把本地 DSH 接入釘釘，不需要公網入站端點。
• 支持 plan、apply、resume、doctor 等 JSON 命令。
• AI agent 可以檢查 setup plan，執行明確批准過的非機密步驟，並從 checkpoint 恢復。
• QR URL、Client Secret、明文 /bind code 不寫入機器 JSON 或 checkpoint，而是分配給單獨的終端 handoff。
• checkpoint 使用 mode 0600，並拒絕寫入 dedicated Client ID、Client Secret、QR/device-code、owner-ID 和明文 /bind 字段。
• checkpoint 會保存明確批准過的非機密 setup choices，因此應按私有本地元數據處理。
• setup 過程不會改變 credential file，也不會把 records 或 secrets 複製到 JSON。

安裝與啓用¶

下面按 setup 流程執行。先解析穩定版本，並把後續每一步固定到同一個 <version>：

npx @dingtalk-real-ai/dsh-dingtalk@latest --version

把命令輸出記錄爲 <version>。對於新安裝，可以使用 default；如果本機已經存在多個賬號，則應顯式選擇目標賬號。

先生成計劃：

npx @dingtalk-real-ai/dsh-dingtalk@<version> setup --plan --json --account default

這一步用於檢查將要執行的內容。根據計劃輸出，把需要的顯式選擇整理並保存爲 <answers.json>。不要把未明確批准的事項默認當作“是”。

經過上面的步驟後，應用計劃：

npx @dingtalk-real-ai/dsh-dingtalk@<version> setup --apply --json --answers <answers.json>

典型用法¶

應用後的恢復¶

如果流程進入需要人工處理敏感項的 checkpoint，可以在交互終端中執行私有 resume。私有 resume 會省略 --json，並且只接受交互終端：

npx @dingtalk-real-ai/dsh-dingtalk@<version> setup --resume <checkpoint-id>

在這一步中，QR URL、Client Secret、明文 /bind code 應由你自己在獨立終端裏處理，不要讓自動化流程讀取、記錄或代填。

JSON resume 與 doctor¶

人工步驟完成後，可以重新使用 JSON 模式恢復並檢查：

npx @dingtalk-real-ai/dsh-dingtalk@<version> setup --resume <checkpoint-id> --json
npx @dingtalk-real-ai/dsh-dingtalk@<version> doctor --json

doctor --json 用於檢查本地配置和最近運行狀態。經過上面的步驟後，最後還需要向機器人發送一條真實直聊消息，驗證消息通路。

退出碼與失敗處理¶

JSON 命令的退出碼含義如下：

• 0：協議成功返回。這裏包括需要人工等待的狀態，以及診斷結果爲 warning 或 unverified 的情況。
• 1：執行失敗或診斷失敗。
• 2：參數或 answers 無效。

如果失敗結果中的 error.code 爲 dsh_upgrade_required，說明已安裝的 DSH 版本過舊，無法在不丟失數據的情況下消費現有 credential records。此時應升級 DSH，然後重新創建並應用 plan。

適用場景與注意¶

適合在本地運行 DSH，並希望從釘釘直聊或釘釘會話中調用本地智能體的開發者。它適合需要本地化部署、不想暴露公網入站端點，並且希望把敏感憑據留在人工終端中的場景。

使用前需要注意：

• 本地必須保持 dsh web 運行，並且電腦處於在線狀態。
• 電腦睡眠、斷網或進程退出後，機器人不會繼續工作。
• Node.js 需要滿足 ^22.19.0 || >=24.0.0。
• checkpoint 應按私有本地元數據處理。
• 插件以當前 dsh 進程所在環境的權限運行。安裝或啓用前，應檢查倉庫源碼和許可證。

鏈接¶

倉庫地址：

https://github.com/DingTalk-Real-AI/dsh-dingtalk