前言¶
把 DeepSeek Harness（DSH）的智能體接入釘釘時，常見的問題是通道側還要處理公網回調、消息解析、媒體下載、工具審批和會話隔離。deepseek-harness-dingtalk 是面向 DSH 的釘釘通道插件，使用官方 Stream WebSocket 連接，不需要公開回調服務器。應用機器人只需要 Client ID 和 Client Secret 即可接入，並把文本、Markdown、富文本、語音轉寫、圖片和普通文件送入 DSH Agent。
這是什麼¶
deepseek-harness-dingtalk 由 sliverp 維護，採用 MIT 許可。它的一句話定位是：DingTalk Stream text, image, and file channel bridge for DeepSeek Harness。它解決的是 DSH Agent 與釘釘會話之間的通道適配：輸入、輸出、媒體、審批和會話都在釘釘側完成。
核心能力¶
輸入與媒體¶
插件支持以下輸入：
- 文本
- Markdown
- 富文本
- 語音轉寫
- 圖片
- 普通文件
對圖片和文件，插件使用官方 downloadCode 獲取。普通文件會安全存入 Agent 工作區。多模態輸入會根據模型能力處理，並保留 text-only fallback metadata。
輸出與執行¶
插件支持：
- 釘釘原生 Markdown 回覆
- 生成圖片上傳
- 工作區文件上傳
- 完整 Harness Agent Loop 執行
- 結構化 tool events
- final-visible-reply-only delivery
會話是持久且隔離的，會恢復對應 Agent preset，並借用一個已存在的 live Agent writer。
審批與命令¶
工具審批在同一會話內完成，使用一次性代碼：
/approve <code>
/reject <code>
插件還支持 /new、已註冊的 Harness slash commands，以及以下檢查命令：
/bot-ping
/bot-help
/bot-image-test
/bot-file-test
/bot-status
/bot-cancel
啓動與容錯¶
Client Secret 通過 Harness credential service 解析。如果 Client ID 或 Client Secret 未配置，插件以 dormant 方式啓動；單獨安裝它不會阻塞 Harness Web。
連接側使用官方 Stream WebSocket 和 heartbeat，並帶有插件監督的重連，包含對 SDK promise failures 的處理。憑據缺失或無效時，該通道離線並記錄日誌，但不會阻止 Harness 啓動。
環境要求¶
運行前需要滿足：
Node.js 22.19 or later
pnpm 10.33.4
DeepSeek Harness 0.1.0-rc.7 or later
package.json 中當前版本號爲 0.1.5。
安裝與啓用¶
確認版本後，添加插件：
pnpm dsh plugin --profile web add github:sliverp/DeepSeek-harness-dingtalk
如果使用本地 checkout，可以改成絕對路徑：
pnpm dsh plugin --profile web add /absolute/path/to/DeepSeek-harness-dingtalk
配置釘釘應用¶
先完成釘釘應用配置，再配置 DSH 憑據。
- 打開釘釘開發者控制檯，創建內部應用。
- 添加機器人能力，或使用釘釘官方的 one-click OpenClaw robot 應用流程。
- 在 credentials 頁面複製 Client ID（ formerly AppKey）和 Client Secret（ formerly AppSecret）。
- 將 Client ID 放入
DINGTALK_CLIENT_ID，並將 Client Secret 存入 Harness credential referenceDINGTALK_CLIENT_SECRET。
開發環境可以使用環境變量：
export DINGTALK_CLIENT_ID='ding_your-client-id'
export DINGTALK_CLIENT_SECRET='your-client-secret'
pnpm dsh --profile web
長期使用建議把 Client ID 放入 ~/.dsh/.env，並通過 Harness credential settings 界面保存 Client Secret。不要提交憑據。
驗證¶
配置完成後，先發送：
/bot-ping
/bot-image-test
/bot-file-test
再發送一個帶圖片或普通文件的問題，檢查工具、圖片和文件路徑：
What files do I have?
如果需要驗證審批，可以請求一個需要審批的操作，然後回覆插件給出的精確代碼：
/approve <code>
/reject <code>
審批碼用於同一會話內的一次性決定。
策略與超時¶
直聊和羣聊策略接受 open、allowlist 或 disabled。啓用白名單時，應配合最小權限的 Harness tool 和 workspace 權限。
如果配置審批超時，approvalTimeoutMs 需要小於 responseTimeoutMs。
安全邊界¶
插件的安全處理包括：
sessionWebhook只用於對應的原始回覆，不記錄、不持久化，也不暴露給模型。- 媒體傳輸使用釘釘官方 API，包括經過認證的 HTTP/HTTPS signed download URLs；圖片和文件有數量與字節限制。
- 入站文件使用安全文件名和私有目錄。
- 出站文件只接受當前工作區內明確鏈接的普通文件，並拒絕 symlink escape。
- 憑據缺失或無效時，該通道離線並記錄日誌，不阻塞 Harness 啓動。
會話命名空間¶
README 中關於 0.1.1 的說明使用新的 dingtalk-v2 會話命名空間。舊的 dingtalk-v1 會話不會被刪除，並繼續保留在 Harness persistence 中；該通道不再向這些可能已被污染的會話追加內容，而是從一個乾淨的 v2 會話開始。/new 可以創建另一個 durable session，同時保留已有記錄。
package.json 當前版本號爲 0.1.5，版本間的會話遷移關係請按對應版本說明覈對。
適用場景與注意¶
適合：
- 想把 DSH Agent 接到釘釘會話中的開發者。
- 需要文本、Markdown、富文本、語音轉寫、圖片和普通文件輸入的通道。
- 需要在釘釘側處理工具審批、會話隔離和媒體輸入輸出的場景。
使用前注意：
- 插件會以當前 DSH 進程的權限運行，安裝前應檢查源碼、依賴和 MIT 許可證。
- 不要把 Client ID 或 Client Secret 提交到倉庫。
- 白名單應和最小權限工具、工作區權限一起使用。
- 社區目錄是獨立站點，與 DeepSeek / 幻方無官方從屬關係，不應理解爲官方應用商店。
