Preface

DeepSeek Harness (DSH) is built on the Cordis architecture, whose core design philosophy is “everything is a plugin.” When building multi-channel agent applications, integrating directly with external IM platforms (such as WeChat, QQ, email, etc.) often involves complex Webhook management, session context maintenance, and message-loop handling. dsh-im-gateway aims to solve this problem. As a DSH plugin, it is responsible for bridging external IM messages into Harness, leveraging DSH’s Agent mechanism to process logic, and finally routing replies back to the original channel.

What Is It

This is a DeepSeek Harness (DSH) plugin maintained by the developer masquerator-coder. It is an open-source tool (MIT License) whose core function is to implement a multi-channel gateway, supporting unified ingestion of external IM messages and creating a persistent Agent for each external session to preserve conversation context while ensuring isolation between different channels and sessions.

Core Features

The plugin mainly provides the following capabilities:
* Multi-channel gateway: Supports multiple access methods including 5G messages, email, Feishu, WeChat, QQ, and HTTP callbacks.
* Persistent Agent: Maps each external chat session to a stable Harness Agent, supporting context retention across messages.
* Reply routing: Retrieves Agent replies from the global session stream through the rpcId mechanism and routes them back to the original sending channel.
* Session keying and isolation: Generates unique session IDs based on channel and chat_id, ensuring that different channels or different message sources with the same ID do not interfere with each other.
* Built-in gateway protection: Includes access control, deduplication, serialization, retry limits, and other security and stability mechanisms.
* IM-side confirmation: Supports Agent-scoped hydration events for tool approvals (approval) and user questions (user-questions).

Installation and Prerequisites

No official automated installation command was found in the current materials. The plugin exists as a standalone code repository and must be configured according to environment requirements.

Environment Requirements

  • Node.js: ^22.19.0 or >=24.0.0
  • Package manager: pnpm version @11.25.0
  • Dependencies:
    • @deepseek-ai/cordis (version ^4.0.4)
    • @deepseek-ai/dsh-agent (version >=0.1.0-rc.8 <0.2.0)
    • @deepseek-ai/dsh-agent-default-model (version >=0.1.0-rc.8 <0.2.0)

Code Structure

The plugin contains the following core files:
* lib/, src/: core source code
* cordis.patch.yml: Cordis patch configuration
* README.md: documentation
* LICENSE: MIT License

Typical Usage and Logic

Workflow

External IM platforms send messages to the gateway via the corresponding channel transports (Webhook/WS/IMAP/Bot API). The gateway injects them into a persistent Agent bound to a Workspace. The Agent’s replies are retrieved from the global session stream through the rpcId claim mechanism and sent back to the user by the gateway over the same channel.

Session Keying and Isolation

To ensure session stability, the plugin generates session IDs using a hash algorithm:

SessionId = im-<sha1(f"{channel}:{chat_id}")[0:16]>

If an explicit working directory (cwd) is configured, the key includes that directory:

SessionId = im-<sha1(f"{channel}:{chat_id}@{cwd}")[0:16]>

This design ensures that the same external chat_id arriving through different channels (such as email and 5G) is treated as different sessions. In addition, cwd is included in the key to ensure the Agent always runs in a specific Workspace.

Agent Composition

The Agent in the DSH gateway is composed in the following way:
1. Real workspace attach: each session is bound to a real Harness Workspace (an explicit cwd or the plugin default path), avoiding conflicts with the persisted _no-cwd log.
2. Webhook-aligned composition: prefer the model provider/model configured for the channel; otherwise use the currently active model in the DSH runtime; mount configured Agent presets and pin the default permission preset for deployment.
3. Cross-restart continuation: when the process restarts, detect existing sessions and resume them through sessionQuery.observeSession; only new IDs use agents.create, so restarts do not create conflicts.
4. rpcId reply claiming: each user message carries an rpcId, subscribes to the global session/event stream, and precisely retrieves the corresponding round’s reply sequence.

Built-in Gateway Protection

The plugin includes a set of protection mechanisms to ensure robust message processing:
* Sender access control: after configuring allowlist, only whitelisted senderIds can drive the Agent; unauthorized messages are rejected before the Agent intervenes.
* Inbound deduplication: repeated identical chat + text within 5 seconds is suppressed to prevent platform replays from triggering duplicate model invocations.
* Session-level serialization: each session can have at most one in-progress turn at a time; concurrent messages are queued rather than overwritten.
* Source metadata injection: the <dsh_im_source> tag is injected into the Prompt only when the session sender or channel changes, avoiding tag flooding in history.
* Bounded delivery retries: if a reply push fails, it retries up to 2 times; each failure is logged, and when finally abandoned, it clearly logs reply NOT delivered.
* Active session reuse: prevents conflicts with existing Agents. If an Agent has already been opened in the Web UI, the gateway reuses that Agent instead of recreating it or failing silently.
* Failures are never silent: when Agent retrieval fails, times out, the model errors, or the reply is empty, an error message is sent back to the original IM channel (e.g., ⚠️ Processing failed, unable to reply. Reason: ...).
* Honest connection status:
* WeChat: relies on getupdates polling rounds; 10 consecutive failures (about 15 seconds) degrade the status to error.
* China Mobile 5G: an independent watchdog monitors Socket status and Ping/Pong freshness; half-open connections are forcibly reconnected.
* QQ: startup is considered successful only after receiving a READY/RESUMED response; non-retryable close codes (such as 4013) stop the reconnection loop.

Applicable Scenarios and Notes

This plugin is suitable for developers who need to integrate multi-channel instant messaging capabilities into DeepSeek Harness. When using it, note the following:
* The plugin runs with the permissions of the current DSH process and involves filesystem operations; it is recommended to review the source code and license before installation.
* The gateway module is integrated using cordis.patch.yml; ensure DSH environment compatibility.
* Configuration for different channels (such as QQ and WeChat) must be completed through the multi-channel settings UI on the DSH Plugins page.

Summary

dsh-im-gateway provides a complete end-to-end solution from external IM to DeepSeek Harness. Through persistent Agents and strict session isolation mechanisms, it addresses context management and message routing issues in multi-channel integration. Its built-in protection mechanisms effectively prevent message loss and state inconsistency, making it a valuable tool for building enterprise-level IM agent gateways.

  • Project URL: https://github.com/masquerator-coder/dsh-im-gateway
  • Plugin directory: https://www.skillhub.cn/plugins/masquerator-coder/dsh-im-gateway