Preface

DeepSeek Harness (DSH) promotes an “everything is a plugin” architecture. When you need to interact directly with a DSH agent in WeCom, you usually need a public endpoint or a Webhook. dsh-wecom-plugin is a minimum viable plugin designed to bidirectionally connect the WeCom intelligent bot (aibot WebSocket) with DSH. It supports persistent long-lived connections, and each WeCom conversation maps to a persistent DSH agent session.

Plugin Positioning

This plugin is maintained by zhengmz and is a feasibility validation demo. By implementing the official @wecom/aibot-node-sdk protocol, it establishes the link from the WeCom gateway to a local DSH plugin.

Installation and Enablement

When installing the plugin in the dsh web profile, you must use the file: prefix to ensure correct ESM module resolution:

dsh plugin --profile web add "file:<本插件仓库路径>"

Core Features

The plugin implements core capabilities through the following modules:

  • WeCom intelligent bot WebSocket client: located in src/aibot-client.js. It implements protocol details such as streaming replies, receipt waiting, heartbeat ack, event callbacks, fallback to 846608, retry on authentication failure, and prevention of mutual disconnection.
  • Conversation routing: located in src/bridge.js. It maps one WeCom message to one DSH agent session, supporting reply collection, chunking, and streaming push-back.
  • Local mock gateway: test/mock-wecom.js. Used for local development and testing, matching the behavior of the real gateway (for testing only; ack frames contain no cmd).

Configuration

After connecting to a real WeCom instance, you need to fill in credentials in the configuration file. The key configuration items are as follows:

Key Meaning Default
botId / secret WeCom intelligent bot credentials ''
websocketUrl Gateway address (change for local mock testing) wss://openws.work.weixin.qq.com
allowedUserIds WeCom userids allowed to interact; empty = allow all []
agent.sessionScope Session isolation mode: chat (shared in the group) / chat-user (isolated per group member, recommended) chat
agent.groupMention Group mention gating: none (reply to every message) / at (reply only when @bot) none
approval.enabled Master switch for authorization inside WeCom (permission requests are forwarded to the WeCom conversation) true
agent.cwd Default working directory for agent dsh process cwd

Usage Examples

  1. Quick validation: After installing the plugin, you can run the test script to validate the protocol and bridge functionality:
    node test/smoke.mjs

This test covers 43 protocol and bridge features, including media handling.
  1. End-to-end demo: Run node test/live-demo.mjs. This loads the plugin in an isolated DSH environment and connects to a local mock WeCom gateway, validating the full path of “WeCom message → real agent → real LLM → reply”.

Notes

  1. Demo status: The current version is a feasibility validation demo.
  2. Production deployment: You must install it with the file: prefix to avoid ESM module resolution issues.
  3. Development environment: If you need to develop with a bare path, the node_modules directory at the repository root must be linked to the DSH installation directory; otherwise, ERR_MODULE_NOT_FOUND will be reported.
  4. In-WeCom authorization: A one-time authorization code is required. The user replies with a keyword in WeCom (e.g., “agree”) to approve.

References