前言¶

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