前言¶
DeepSeek Harness (DSH) 基于 Cordis 架构，其核心设计理念是“一切皆插件”。在构建多渠道智能体应用时，直接对接外部 IM 平台（如微信、QQ、邮件等）通常涉及复杂的 Webhook 管理、会话上下文维护以及消息回路的处理。dsh-im-gateway 旨在解决这一问题，它作为 DSH 的一个插件，负责将外部 IM 消息桥接到 Harness 内部，并利用 DSH 的 Agent 机制处理逻辑，最后将回复路由回原渠道。
它是什么¶
这是一个 DeepSeek Harness (DSH) 插件，由开发者 masquerator-coder 维护。它是一个开源工具（MIT 许可证），核心功能是实现一个多通道网关，支持将外部 IM 消息统一接入，并为每个外部会话创建持久化的 Agent，从而保持对话上下文，同时确保不同渠道和会话之间的隔离。
核心功能¶
该插件主要提供以下能力：
* 多通道网关：支持 5G 消息、邮件、飞书、微信、QQ 和 HTTP 回调等多种接入方式。
* 持久化 Agent：为每个外部聊天会话映射一个稳定的 Harness Agent，支持跨消息的上下文保持。
* 回复路由：通过 rpcId 机制从全局会话流中获取 Agent 回复，并路由回原始发送渠道。
* 会话键控与隔离：基于 channel 和 chat_id 生成唯一的会话 ID，确保不同渠道或同一 ID 的不同消息来源不会互相干扰。
* 内置网关防护：包含访问控制、去重、序列化、重试限制等安全与稳定性机制。
* IM 端确认：支持工具审批 (approval) 和用户提问 (user-questions) 的 Agent 作用域水合事件。
安装与前置条件¶
当前资料中未找到官方提供的自动安装命令。该插件作为独立代码库存在，需根据环境要求进行配置。
环境要求¶
- Node.js:
^22.19.0或>=24.0.0 - 包管理器:
pnpm版本@11.25.0 - 依赖项:
@deepseek-ai/cordis(版本^4.0.4)@deepseek-ai/dsh-agent(版本>=0.1.0-rc.8 <0.2.0)@deepseek-ai/dsh-agent-default-model(版本>=0.1.0-rc.8 <0.2.0)
代码结构¶
插件包含以下核心文件：
* lib/, src/: 核心源码
* cordis.patch.yml: Cordis 补丁配置
* README.md: 说明文档
* LICENSE: MIT 许可证
典型用法与逻辑¶
工作流程¶
外部 IM 平台通过相应的通道传输（Webhook/WS/IMAP/Bot API）将消息发送给网关，网关将其注入到绑定了 Workspace 的持久化 Agent 中。Agent 的回复通过 rpcId 声明机制从全局会话流中获取，并由网关通过同一条渠道发送回用户。
会话键控与隔离¶
为了确保会话的稳定性，插件使用哈希算法生成会话 ID：
SessionId = im-<sha1(f"{channel}:{chat_id}")[0:16]>
如果配置了显式的工作目录 (cwd)，键值会包含该目录：
SessionId = im-<sha1(f"{channel}:{chat_id}@{cwd}")[0:16]>
这种设计使得同一个外部 chat_id 通过不同渠道（如邮件和 5G）到达时，会被视为不同的会话。此外，cwd 也被纳入键值，确保 Agent 始终运行在特定的 Workspace 中。
Agent 组成方式¶
DSH 网关中的 Agent 按照以下方式组合：
1. Real workspace attach：每个会话绑定到一个真实的 Harness Workspace（显式 cwd 或插件的默认路径），避免与持久化的 _no-cwd 日志冲突。
2. Webhook-aligned composition：优先使用通道配置的模型提供者/模型，否则使用 DSH 运行时当前激活的模型；挂载配置好的 Agent 预设，并固定部署默认权限预设。
3. Cross-restart continuation：进程重启时，通过 sessionQuery.observeSession 探测已存在的会话并恢复；仅新 ID 走 agents.create，重启不会创建冲突。
4. rpcId reply claiming：每个用户消息携带 rpcId，订阅全局 session/event 流并精确获取对应轮次的回复序列。
内置网关防护¶
插件内置了一套防护机制，以保证消息处理的健壮性：
* 发送者访问控制：配置 allowlist 后，仅白名单 senderId 可驱动 Agent，未授权消息在 Agent 介入前被拒绝。
* 入站去重：相同 chat + text 在 5 秒内重复发送会被抑制，防止平台重放导致重复触发模型调用。
* 会话级序列化：每个会话同一时间最多只能有一个进行中的轮次，并发消息会排队而非覆盖。
* 来源元数据注入：仅在会话发送者或渠道变更时注入 <dsh_im_source> 标签到 Prompt，避免历史记录中标签泛滥。
* 有界投递重试：回复推送失败时最多重试 2 次，每次失败均记录日志，最终放弃时明确记录 reply NOT delivered。
* 活跃会话复用：防止与已存在的 Agent 冲突。如果 Agent 已在 Web UI 中被打开，网关会复用该 Agent 而非重新创建或静默失败。
* 失败永不静默：Agent 获取失败、超时、模型错误或回复为空时，错误信息会回传至原 IM 渠道（如 ⚠️ 处理失败，未能回复。原因：…）。
* 诚实连接状态：
* 微信：依赖 getupdates 轮次，连续 10 次失败（约 15 秒）将状态降级为错误。
* 中国移动 5G：独立看门狗监控 Socket 状态及 Ping/Pong 新鲜度，半开连接会被强制重连。
* QQ：仅在收到 READY/RESUMED 响应后才视为启动成功；遇到不可重试关闭码（如 4013）会停止重连循环。
适用场景与注意事项¶
该插件适合需要在 DeepSeek Harness 中集成多渠道即时通讯能力的开发者。使用时需注意：
* 插件以当前 DSH 进程的权限运行，涉及文件系统操作，安装前建议检查源码与许可证。
* 网关模块使用 cordis.patch.yml 进行集成，需确保 DSH 环境兼容。
* 不同渠道（如 QQ 和微信）的配置需在 DSH 的 Plugins 页面通过多通道设置 UI 进行配置。
总结¶
dsh-im-gateway 提供了一套从外部 IM 到 DeepSeek Harness 的完整链路方案，通过持久化 Agent 和严格的会话隔离机制，解决了多渠道接入时的上下文管理和消息路由问题。其内置的防护机制有效避免了消息丢失和状态不同步，是构建企业级 IM 智能体网关的有力工具。
- 项目地址: https://github.com/masquerator-coder/dsh-im-gateway
- 插件目录: https://www.skillhub.cn/plugins/masquerator-coder/dsh-im-gateway
