Introduction

DSH’s plugin architecture splits channel access, tool invocation, and capability extension into independent components. For developers who need to use the local DeepSeek Harness (DSH) agent within DingTalk, the DingTalk connector mainly addresses two issues: whether the message channel can bypass public network inbound endpoints, and how to prevent sensitive items such as QR codes, Client Secret, and plaintext /bind codes from entering machine-readable outputs or checkpoints.

@dingtalk-real-ai/dsh-dingtalk provides a DingTalk access path based on Stream connection. It does not require a public network inbound endpoint, while separately handing over sensitive credentials that require manual handling to the local terminal.

What is this

@dingtalk-real-ai/dsh-dingtalk is the DingTalk connector for DeepSeek Harness, used to connect the local DSH to DingTalk. The repository address is:

https://github.com/DingTalk-Real-AI/dsh-dingtalk

According to package.json, the license is MIT. This plugin requires a Node.js version of:

^22.19.0 || >=24.0.0

It is important to note that this bot is only available when dsh web is running locally and the computer is online. After the computer sleeps, the network is disconnected, or the local process exits, it will not continue running in the cloud.

Core Features

Below are the listed capabilities:

  • Connect local DSH to DingTalk via Stream connection without requiring a public network inbound endpoint.
  • Support JSON commands like plan, apply, resume, and doctor.
  • The AI agent can inspect the setup plan, execute non-confidential steps that have been explicitly approved, and resume from checkpoint.
  • QR URL, Client Secret, and plaintext /bind code are not written into machine JSON or checkpoint; instead, they are assigned to a separate terminal handoff.
  • Checkpoint uses mode 0600 and rejects writing dedicated Client ID, Client Secret, QR/device-code, owner-ID, and plaintext /bind fields.
  • Checkpoint saves explicitly approved non-confidential setup choices, so it should be treated as private local metadata.
  • The setup process does not modify the credential file and does not copy records or secrets into JSON.

Installation and Enablement

The setup process is executed step-by-step below. First, parse the stable version and fix subsequent steps to the same <version>:

npx @dingtalk-real-ai/dsh-dingtalk@latest --version

Record the command output as <version>. For a new installation, you can use default; if multiple accounts already exist on the machine, you should explicitly select the target account.

First, generate a plan:

npx @dingtalk-real-ai/dsh-dingtalk@<version> setup --plan --json --account default

This step is used to check what will be executed. Based on the plan output, organize and save the required explicit choices as <answers.json>. Do not assume unapproved items are “yes”.

After the above steps, apply the plan:

npx @dingtalk-real-ai/dsh-dingtalk@<version> setup --apply --json --answers <answers.json>

Typical Usage

Post-Application Recovery

If the process enters a checkpoint requiring manual handling of sensitive items, you can execute a private resume in an interactive terminal. Private resume omits --json and only accepts the interactive terminal:

npx @dingtalk-real-ai/dsh-dingtalk@<version> setup --resume <checkpoint-id>

In this step, QR URL, Client Secret, and plaintext /bind code should be handled by yourself in a separate terminal; do not let the automated process read, record, or auto-fill them.

JSON Resume and Doctor

After manual steps are completed, you can resume and check again using JSON mode:

npx @dingtalk-real-ai/dsh-dingtalk@<version> setup --resume <checkpoint-id> --json
npx @dingtalk-real-ai/dsh-dingtalk@<version> doctor --json

doctor --json is used to check local configuration and recent run status. After the above steps, you also need to send a real direct chat message to the bot to verify the message channel.

Exit Codes and Failure Handling

The meanings of exit codes for JSON commands are as follows:

  • 0: Protocol succeeded in returning. This includes states requiring manual waiting, as well as diagnostic results that are warnings or unverified.
  • 1: Execution failed or diagnosis failed.
  • 2: Parameters or answers are invalid.

If error.code in the failure result is dsh_upgrade_required, it indicates that the installed DSH version is too old to consume existing credential records without losing data. In this case, you should upgrade DSH, then recreate and apply the plan.

Suitable Scenarios and Notes

Suitable for developers who run DSH locally and wish to call the local agent from DingTalk direct chat or DingTalk sessions. It is suitable for scenarios requiring local deployment, not wanting to expose a public network inbound endpoint, and wanting to keep sensitive credentials in a manual terminal.

Notes before use:

  • dsh web must remain running locally, and the computer must be online.
  • The bot will not continue working after the computer sleeps, network disconnection, or process exit.
  • Node.js must meet ^22.19.0 || >=24.0.0.
  • Checkpoint should be treated as private local metadata.
  • The plugin runs with the permissions of the current environment where the dsh process is located. Before installing or enabling, you should check the repository source code and license.

Links

Repository address:

https://github.com/DingTalk-Real-AI/dsh-dingtalk