wsz987/dsh-channels
把微信 / QQ / 钉钉 / 飞书 / Telegram 接入 DeepSeek Harness：统一配置、扫码授权，直接在各 IM 与 Agent 对话；支持图片与文件收发，Agent 可读取 PDF、DOCX、XLSX 和文本内容。
安装Install
npx @deepseek-ai/dsh plugin --profile web add -w @wsz987/dsh-channels@latest把 wsz987/dsh-channels 加入你的 DSH 配置（web profile）即可启用。
READMEREADME
dsh-channels
将微信、QQ、钉钉、飞书和 Telegram 接入 DeepSeek Harness
多渠道集成，统一配置，并在各平台与 Agent 对话
支持图片与文件收发，Agent 可直接读取 PDF、DOCX、XLSX 和文本内容
English | 简体中文
本项目是社区维护的 DeepSeek Harness 渠道扩展，不是 DeepSeek Harness 或各消息平台的官方项目。项目参考各平台面向 OpenClaw 提供的渠道接入方案，结合官方 SDK / API 适配到 DeepSeek Harness；运行时不依赖 OpenClaw。
效果预览
接入后，在 Harness Web“设置 → 渠道”面板统一配置与扫码授权，并在各平台对话框中直接与 Agent 对话（图片来源：docs/ScreenShot）：
Harness Web · 渠道设置与 Telegram 接入示例（图片与文件收发、附件内容读取）
各平台对话框
能力总览
| 渠道 | 文本 | 图片 | 文件 | 流式回复 | 状态 |
|---|---|---|---|---|---|
| 微信 | 支持 | 收发 | 入站读取 | - | ✅ |
| 支持 | 收发 | 收发 | 支持 | ✅ | |
| 钉钉 | 支持 | 收发 | 收发 | 支持 | ✅ |
| 飞书 | 支持 | 收发 | 收发 | 支持 | ✅ |
| Telegram | 支持 | 收发 | 收发 | 支持 | 实验性，待 live gate |
- 支持视觉的多模态模型可直接识别图片；PDF、DOCX、XLSX 和文本附件可提取内容供 Agent 读取（入站单文件上限 100 MiB）；音频和视频暂为降级处理。
使用前须知
- 确认
npx @deepseek-ai/dsh可运行，且 Harness Web 普通会话可正常对话。 - 0.5.x 版本线要求 DeepSeek Harness
0.1.1-rc.2及以上、Node22.19+；仍在使用 Harness0.1.0-rc.7的用户请停留在0.4.x（版本线对照见 兼容矩阵）。 - 渠道会话通常使用
Workspace Write；仅在确需访问 Workspace 外文件且信任当前任务时启用Full access。 - 项目仍在快速迭代，升级前请备份数据。
从 0.3.x 或更早版本升级？ 0.4.1 起收紧了渠道访问权限。升级后请前往 Harness Web → 设置 → 渠道 → 选择已启用的渠道 → 安全访问，重新确认允许使用 Bot 的账号和群聊。完成前，即使渠道显示连接正常，普通消息也可能无法进入 Agent。
安装
# 安装稳定版 bundle
npx @deepseek-ai/dsh plugin --profile web add -w @wsz987/dsh-channels@latest
# 检查 bundle 是否合并到 profile
npx @deepseek-ai/dsh --profile web --dump-config
# 启动 Harness Web
npx @deepseek-ai/dsh web
安装完成后，在 Harness Web 的“设置 → 渠道”中配置或登录需要使用的渠道，并完成“安全访问”设置。
更新与卸载
安装、更新和卸载时请保留 -w 参数。
跨版本线升级（如 0.4.x → 0.5.x）？
update只在 package.json 当前版本范围内更新，跨版本线必须先升级 Harness CLI，再用add ...@latest重新安装（顺序不能颠倒，否则旧宿主上会出现运行不兼容）：npm i -g @deepseek-ai/dsh@latest # 先升级 Harness（0.5.x 需要 0.1.1-rc.2+，Node ≥ 22.19） npx @deepseek-ai/dsh plugin --profile web add -w @wsz987/dsh-channels@latest
# 在当前 package.json 版本范围内更新
npx @deepseek-ai/dsh plugin --profile web update -w @wsz987/dsh-channels
# 卸载 bundle
npx @deepseek-ai/dsh plugin --profile web remove -w @wsz987/dsh-channels
新版本提示（仅提示，不自动安装）
运行时会定期检查 npm 上 @wsz987/dsh-channels 是否有比本地更新的版本（默认每 24 小时一次；离线或检查失败时静默跳过）。发现新版本时：
- Web「设置 → 渠道」页面顶部会显示新版本提示条，并给出升级命令；跨版本线（如 0.4.x → 0.5.x）时提示两步升级（先升 Harness CLI，再重装 bundle），同版本线提示单条 update 命令。
- 渠道会话内发送
/version可查看当前版本与同样的升级提示。
该功能只做提示，绝不会自动安装或升级。浏览器不直接访问 npm registry（检查由 host 侧完成，页面只读净化后的结果）。如需关闭或调整频率，可在 profile patch 中覆盖 channels-control（注意 patch 是整体替换，需保留完整字段）：
- id: channels-control
name: '@wsz987/dsh-channels/control'
inject: [channels, credentials]
config:
updateCheck:
enabled: true # 设为 false 关闭新版本检查
intervalHours: 24 # 两次检查的最小间隔（小时）
配置与登录
| 渠道 | 必要信息 | 登录方式 |
|---|---|---|
| 微信 | 无 | 扫码登录，凭据自动持久化 |
| AppID、AppSecret | QQ 开放平台创建机器人 | |
| 钉钉 | clientId、clientSecret（可选） | 扫码或在钉钉开放平台创建应用 |
| 飞书 | AppId、AppSecret | 在飞书开放平台创建应用，或扫码创建智能体 |
| Telegram | Bot Token | 在 @BotFather 创建机器人并填写 Token |
密钥由 Harness 凭据管理，cordis.patch.yml 只填写 appSecretRef 等引用。完整示例见 minimal-profile；配置 patch 会整体替换 config，不会深度合并。
Telegram adapter 最低支持 Bot API 10.2；formatting.mode: auto 默认使用 Rich
Markdown。项目不维护旧 Bot API server 的自动兼容，plain 仅作为显式输出模式或
格式错误时的单次降级。
Telegram 当前只实现 getUpdates 长轮询。启动时会调用 deleteWebhook，因此会移除
该 Bot 已配置的 webhook；不要让同一 Bot 同时承担其他 webhook 消费者。当前实现订阅
message 与 callback_query，但交互按钮只应视为支持带 message.chat 上下文的
callback；Rich Message、draft streaming、callback、媒体错误处理与限流恢复在真实 Bot
live gate 完成前均不视为生产验证通过。
必做：配置安全访问
首次安装或从 0.3.x 升级后，需要在“安全访问”中确认谁可以通过 Bot 使用本机 Agent。系统默认不会把“能给 Bot 发消息的人”自动视为已授权用户。
- 微信会根据当前扫码账号自动设置为“仅当前扫码微信账号”。
- 钉钉、飞书和 Telegram 请点击“识别我的账号”，按页面提示私聊 Bot 发送一次识别指令，然后回到本地页面确认检测到的账号。
- QQ 私聊由平台限制为创建者可用，不显示“识别我的账号”；群聊访问仍需在本地明确配置。
- 完成确认后，默认启用“仅自己使用”：只有已确认的账号可以通过私聊驱动 Agent，群聊默认关闭。
在账号尚未识别、访问配置缺失或配置无效时，渠道可以保持连接以完成账号识别，但普通消息和命令都会被安全阻止，不会进入 Agent、创建会话或执行 /stop 等操作。页面上预先选中的“仅自己使用”只是建议配置，必须先识别并确认所有者后才会生效。
除 QQ 外，私聊访问可分别选择“禁用”“仅自己”“指定用户”或“所有人（危险）”；QQ 私聊仅由平台允许创建者使用，不显示本地私聊访问配置。群聊访问单独选择“指定群组”并填写 Group ID，或选择“所有群组（危险）”并配置统一的群成员规则。“私聊所有人”不会自动开放任何群聊。微信当前仅支持私聊，不显示群聊配置。
常用操作
渠道指令
任意渠道会话内可直接发斜杠指令，由 Harness 官方命令系统解析执行：
部分指令暂不支持在群聊中使用，具体可用范围以当前渠道和会话为准。
| 指令 | 说明 |
|---|---|
/stop |
立即终止当前任务（最高优先级：不等渠道排队消息，直接取消当前 Agent） |
/new |
开启全新会话（遇到 bug 可以尝试使用） |
/help [command] |
查看当前会话实际生效的命令，或单个命令的用法 |
/status |
查看当前 Session / Agent / 模型状态 |
/version |
查看当前 bundle 版本、Harness 兼容基线与新版本提示 |
/models [provider] |
查看 Harness 当前注册的模型 Provider 及其模型 |
/model [<provider> <model> [<reasoningEffort>]] |
查看或切换当前会话模型 |
- 若宿主加载了官方插件（
/compact、/goal、/plan、/feedback等），这些命令也会自动出现在渠道里，无需额外升级。 - 未注册的斜杠指令直接拒绝（与官方 rc.2 Host 行为一致）：回复一条「未知命令」提示，不会作为普通用户输入发给模型。
/model 示例
/model # 查看当前会话解析到的模型
/model deepseek deepseek-chat
/model openai gpt-5.6 high # 指定 reasoning effort
/model切换当前会话，并同步写入 Harness 的全局默认模型，供后续新会话使用。
主动外发
在渠道会话中让 Agent 调用 send_channel_message，可以主动向当前渠道发送文本、图片或支持的文件。Harness Web 直接创建的普通会话没有渠道绑定，不能执行渠道外发。
Workspace 隔离
默认按“渠道 / 账号”创建独立 Workspace，路径为 <dsh-home>/workspaces/channels/<channel>/<account>，无需额外配置。
如需复用 Harness 启动目录或关闭隔离，可在 profile patch 中覆盖 channels-harness：
- id: channels-harness
name: '@wsz987/dsh-channels/harness'
inject: [channels, agents, agentDefaultModel, agentPresets, llm, commands, apiProxy]
config:
workspace:
mode: channel-account # channel-account（默认）| host-cwd | disabled
autoCreate: true
Harness patch 会整体替换目标插件配置，并非局部合并；覆盖时请保留该插件需要的完整字段。
关闭不需要的渠道
在 profile patch 中将对应渠道插件的 enabled 设为 false，或删除可选的 channels-files 行以关闭通用文件扩展。
已知限制
| 当前限制 | 临时处理方式 | 后续方向 |
|---|---|---|
| 渠道内没有权限切换指令 | 在 Harness Web 中调整未来新会话的默认权限，或修改对应会话的 Access 设置 | 完善渠道内的会话管理能力 |
该限制是当前渠道交互层尚未接入对应能力，不代表 Harness 不支持。相关上游能力可查阅 Harness Reference。
Roadmap
- 完善渠道内的会话管理和异常恢复体验。
- 接入更多即时通讯渠道（画饼中）。
从源码运行
git clone https://github.com/wsz987/dsh-channels.git
cd dsh-channels
pnpm install
pnpm build
pnpm channels
pnpm web:debug
pnpm channels可指定渠道，例如pnpm channels weixin qq。- 修改代码后重新构建并重启 Harness；切回 npm 版本前运行
pnpm channels:clean。
提交前运行完整门禁：
pnpm ci:check
📚 文档
- 架构总览
- 公共/统一代码设计
- 多渠道规划
- 架构决策记录（ADR）
- 入站访问控制（安全）
- 渠道身份映射（安全）
- 第三方渠道接入指南
- 发布流程
- 兼容矩阵（Harness / Node / 必测场景）
- 微信 live 验证手册
- 渠道权限核验（接口/权限/上游漂移对照）
- 第三方版权声明
- 各子包 README：
packages/*/README.md（每个包的安装、配置、开发说明）
🤝 二次开发规范
参考主流开源项目（Koishi / Wechaty 风格）的分层约定：适配器层零侵入核心，核心层不感知平台。
仓库结构
| 目录 | 职责 |
|---|---|
packages/channels |
对外 bundle @wsz987/dsh-channels（聚合 patch） |
packages/channel-core |
Channel Contract：类型 + ctx.channels Service + defineChannelAdapter |
packages/channel-harness |
渠道 ↔ Harness 桥；只保留可选 ChannelFileProvider 端口 |
packages/channel-files |
可选通用文件扩展：私有存储、成熟文档解析库、读取工具 |
packages/channel-control |
控制面：配置 / 凭据 / 扫码授权 / 运行时生命周期 |
packages/channel-{weixin,qq,dingtalk,lark,telegram} |
五个内置渠道适配器 |
packages/channel-{compat,testkit,verify,web} |
契约验证 / 测试工具 / Web 可视化 |
templates/channel-adapter |
新渠道脚手架 |
使用核心包（channel-core）
适配器只需实现 ChannelAdapter 契约，核心自动完成注册 / 挂载 / 回执 / 健康检查：
import { defineChannelAdapter } from '@wsz987/channel-core';
export default defineChannelAdapter({
id: 'my-channel',
capabilities: {
text: true, image: false, file: false,
audio: false, video: false, markdown: false,
cards: false, reactions: false, threads: false,
streaming: 'buffered', // native | edit | buffered
},
async start(ctx) { /* 连接平台、ctx.emit('message', ...) */ },
async stop() { /* 幂等清理 */ },
async send(target, message) { /* 发送 */ },
// 可选：createReply 流式 / beginAuth+pollAuth 扫码 / getHealth 健康
});
三条红线（详见 docs/adapter-authoring.md）：
- 不在 core 里按渠道做特判——渠道差异由 core 按
capabilities协商处理 - 适配器禁止调用 Harness Agent API（
ctx.agents...） - 平台原始 payload 必须映射为结构化
MessagePart，禁止直塞给模型
契约表达不了的需求 → 上报 contract gap，禁止改 channel-core / channel-harness。
新增渠道四步
- 复制
templates/channel-adapter为packages/channel-<name>，实现defineChannelAdapter（含 config / transport / mapper） - 在
packages/channels/cordis.patch.yml加一行（pnpm channels自动识别新渠道） pnpm build && pnpm typecheck && pnpm testpnpm verify packages/channel-<name> --test跑契约验证（fixtures + manifest + 测试套件）
新增渠道指令
指令以 factory 形式放在 packages/channel-harness/src/commands/，加入 commandFactories 数组即随 Agent 自动注册（官方 @deepseek-ai/dsh-commands 格式，无需改 bridge）：
// packages/channel-harness/src/commands/reset.ts
export function createResetCommand(deps: ChannelCommandDependencies): CommandDefinition {
return {
name: 'reset',
description: 'Reset the current session',
async handler(invocation) {
if (invocation.rawInput.trim().length > 0) return { kind: 'error', text: '用法：/reset' };
if (invocation.agent.status !== 'idle') return { kind: 'error', text: '当前会话仍在运行，请稍后再试。' };
// ...调用 deps 提供的 bridge 能力
return { kind: 'success', text: '已重置会话。' };
},
};
}
commandFactories是唯一注册点：['createNewCommand', createResetCommand]- 需要 bridge 新能力时，在
ChannelCommandDependencies加一个方法（平台无关），bridge 侧实现即可
提交与发布
- Commit：Conventional Commits（
feat(scope): .../fix(scope): .../docs: ...），scope 用包名（如channel-qq） - PR：过 CI（build + typecheck + test + 契约验证 + live gate 前检）
- 发布：
pnpm changeset记录变更 → CI 合入后pnpm release（Changesets 自动发版，见 docs/release.md）
🙏 致谢
本项目基于以下开源项目：
- deepseek-ai/deepseek-harness —— DeepSeek Harness（
@deepseek-ai/*） - DingTalk-Real-AI/dingtalk-openclaw-connector —— 钉钉渠道插件（
@dingtalk-real-ai/dingtalk-connector） - tencent-connect/openclaw-qqbot —— QQ 机器人渠道插件（
@tencent-connect/openclaw-qqbot） - larksuite/openclaw-lark —— 飞书渠道插件（
@larksuite/openclaw-lark） - Tencent/openclaw-weixin —— 微信渠道插件（
@tencent-weixin/openclaw-weixin）
License
相关推荐Related
- deepseek-ai/deepseek-harness DeepSeek Harness: Everything is a Plugin.
- deepseek-ai/deepseek-harness DeepSeek Harness (dsh) — 由 DeepSeek AI 开发的开源 agent harness（智能体框架）。一切皆插件：核心 + 插件 + 技能 = 可热插拔的 AI 编程工作台。DeepSeek Harness: …
-
ruvnet/ruflo
🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build c…
-
amruthpillai/reactive-resume
A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source a…
-
volcengine/OpenViking
Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
-
Molunerfinn/PicGo
:rocket: The Ultimate Image Uploader for Efficient Creators. Supports Obsidian, Typora, VS Code etc. and 60+ image hosti…
-
titanwings/colleague-skill
将冰冷的离别化为温暖的 Skill，欢迎加入数字生命1.0！Transforming cold farewells into warm skills? It's giving rebirth era. Welcome to Digital …
-
nocobase/nocobase
NocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything fr…