前言¶

把 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 凭据。

1. 打开钉钉开发者控制台，创建内部应用。
2. 添加机器人能力，或使用钉钉官方的 one-click OpenClaw robot 应用流程。
3. 在 credentials 页面复制 Client ID（ formerly AppKey）和 Client Secret（ formerly AppSecret）。
4. 将 Client ID 放入 DINGTALK_CLIENT_ID，并将 Client Secret 存入 Harness credential reference DINGTALK_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 / 幻方无官方从属关系，不应理解为官方应用商店。

链接¶

• 社区目录页：https://www.skillhub.cn/plugins/sliverp/DeepSeek-harness-dingtalk
• GitHub 仓库：https://github.com/sliverp/DeepSeek-harness-dingtalk