前言¶
把 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 / 幻方无官方从属关系，不应理解为官方应用商店。
