前言¶
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 开发者，这是一个可靠的工具选择。
