前言¶
DeepSeek Harness（DSH）採用插件化架構，允許通過擴展能力增強 Agent 的工具箱。yiyunet/dsh-dingtalk-connector 是一個 DSH 插件，旨在解決釘釘 AI 表格（多維表 / aitable）數據接入 DSH 的問題。
該插件不直接調用釘釘 REST 接口，而是通過包裝官方 CLI dws 來執行操作。這種方式降低了端點維護成本，並利用 dws 自身的鑑權與分頁邏輯來保證穩定性。安裝後，插件會向 DSH 註冊 10 個 dingtalk_aitable_* 工具，並提供一個「釘釘文檔」設置面板。
核心能力¶
插件提供了對釘釘 AI 表格的完整 CRUD 操作支持，同時兼顧了安全性與實用功能：
- 數據操作：支持 Base（文件）、數據表、字段的查詢、創建、修改與刪除。
- 記錄管理：支持按 ID 或條件查詢記錄（支持全量拉取），以及記錄的批量寫入、修改與刪除。
- 發現與掃描：提供候選 Base 發現功能，並包含可讀性實測，幫助確認哪些 Base 可被正常訪問。
- 數據導出：支持全量導出 CSV，文件包含 BOM 頭，且支持覆蓋同名文件。
- 定時任務：支持創建、列取、刪除、啓停定時導出任務，以及立即執行任務。
- 安全控制：包含自檢（版本/授權）工具，以及受控直通（
dingtalk_aitable_raw）能力。
安裝與前置條件¶
該插件依賴外部 CLI dws，安裝前需滿足以下條件：
- 運行時環境：Node.js 版本 ≥ 22.19。
- 釘釘 CLI (
dws)：需全局安裝dingtalk-workspace-cli。 - 釘釘側授權：需在釘釘開發者後臺開通「AI 表格記錄讀寫」權限，並在目標 Base 中將應用添加爲協作者（可編輯）。
安裝步驟¶
# 1. 安裝插件
dsh plugin --profile web add @yiyunet/dsh-dingtalk-connector
# 2. 重啓 dsh web 以加載插件
# 3. 使用輔助腳本檢查環境（可選）
npx @yiyunet/dsh-dingtalk-connector install
npx @yiyunet/dsh-dingtalk-connector doctor
配置¶
插件依賴 cordis.patch.yml 文件進行配置。以下是關鍵配置項說明：
| 配置項 | 默認值 | 說明 |
|---|---|---|
dwsCommand |
dws |
PATH 上的命令名 |
dwsEntry |
無 | Windows 建議設置：指向 dws 的 JS 入口絕對路徑，避免 shell 注入風險 |
timeoutMs |
60000 | 單條命令超時時間 |
clientIdEnv / clientSecretEnv |
DWS_CLIENT_ID / DWS_CLIENT_SECRET |
用於憑證的環境變量名 |
allowWrite |
false | 開關：允許 create / update 操作 |
allowDelete |
false | 開關：允許 delete 操作（獨立開關，且每次操作需確認） |
maxBatch |
30 | 單次批量操作的最大記錄數 |
關於 dwsEntry 的安全配置¶
在 Windows 環境下，.cmd 文件必須通過 shell 啓動。Shell 會解析參數中的特殊字符（如引號、&、\|），若記錄文本包含這些字符可能導致注入攻擊。插件在檢測到不安全的啓動方式時會返回錯誤。
要徹底解決，請將 dwsEntry 指向 dws 的 JS 入口（例如 npm root -g 下的路徑），完全繞過 shell 啓動。
# cordis.patch.yml 示例
dwsEntry: '<npm root -g>/dingtalk-workspace-cli/bin/dws.js'
工具列表¶
安裝完成後，DSH 註冊了以下 10 個工具：
dingtalk_aitable_diagnose：自檢工具，檢查版本、授權狀態及命令註冊情況。dingtalk_aitable_base：Base 文件管理（查/建/改/刪）。dingtalk_aitable_table：數據表管理（查表與字段、建/改/刪）。dingtalk_aitable_field：字段管理（查/建/改/刪）。dingtalk_aitable_record_query：查詢記錄，支持按 ID 或條件查詢，all=true可全量拉取。dingtalk_aitable_record_write：批量寫/改/刪記錄。dingtalk_aitable_raw：受控直通，可執行註冊表內任意子命令。dingtalk_aitable_scan：候選 Base 發現與可讀性實測。dingtalk_aitable_export_csv：全量導出 CSV（帶 BOM，覆蓋同名）。dingtalk_sync_job：定時導出任務管理（建/列/刪/啓停/立即執行）。
安全機制：雙鎖¶
刪除操作需要雙重確認：
1. 配置層鎖：allowDelete: true（在配置文件中開啓）。
2. 交互層鎖：每次刪除操作需 confirm=true 參數，表示已獲同意。
注意事項¶
- 三層依賴：插件本身是純 JS，但依賴外部 CLI
dws。若 Node、dws或釘釘側授權任一環缺失，操作將失敗。 - 列表限制：釘釘官方 API 不提供“列出全部 Base”的接口。插件提供的掃描功能是“候選 ∪ 人工補錄”，不保證窮盡所有 Base。
- 默認門禁：出於安全考慮，寫與刪除門禁默認全關。如需啓用，必須修改配置文件中的
allowWrite和allowDelete。 - 定時器機制：定時導出任務運行在 DSH host 進程內，DSH 關閉時任務不執行，重啓後重算觸發點。
總結¶
yiyunet/dsh-dingtalk-connector 爲 DeepSeek Harness 提供了與釘釘 AI 表格交互的標準能力。通過包裝 dws CLI，它避免了自行維護 REST 接口的風險，並提供了 CSV 導出與定時任務等實用功能。對於需要處理釘釘多維表數據的 Agent 開發者，這是一個可靠的工具選擇。
