zp-home/dsh-weixin-clawbot

DSH Weixin ClawBot

CI
Release
License: MIT
DSH Plugin
Agent Skill

一个独立的 DeepSeek Harness（DSH）Host Bundle，把腾讯官方微信
ClawBot/iLink 通道直接接入 DSH。配对后，可以在手机微信里下达电脑任务、
管理持久会话、切换模型和权限，并在任务运行中实时纠偏或取消。

手机微信 -> 腾讯官方 iLink -> dsh-weixin Bundle -> DSH Agent -> 电脑工具/工作区

本项目不修改 DSH 核心，不注入桌面微信，不依赖 WxHook，也不增加 Web 页面。
所有远程控制都通过微信文本命令完成；原版 Web 和桌面 DSH 仍可打开并继续同一
Session。

[!IMPORTANT]
这是社区独立适配项目，不是腾讯、微信、DeepSeek 或 DeepSeek Harness 官方项目。
腾讯官方 @tencent-weixin/openclaw-weixin-cli 面向 OpenClaw；DSH 用户应使用
本项目提供的 Bundle 安装和 dsh-weixin setup 配对流程。

Agent Skill 与市场收录

仓库同时提供一个独立的通用 Agent Skill，用于让 Codex、Claude Code、Cursor、
OpenClaw 等客户端正确安装、升级、验证和排查本插件。Skill 只包含操作说明和安全
约束，不包含微信 Token、二维码或本机状态，也不会把 DSH Bundle 伪装成 OpenClaw
原生代码插件。

从 skills.sh 兼容客户端安装：

npx skills add zp-home/dsh-weixin-clawbot --skill dsh-weixin-clawbot

OpenClaw 可直接使用同一索引来源：

openclaw skills install skills-sh:zp-home/dsh-weixin-clawbot/dsh-weixin-clawbot

Skill 源文件位于
skills/dsh-weixin-clawbot/SKILL.md。
它与实际运行在 DSH Host 内的 Bundle 是两个独立交付物；安装 Skill 不等于安装或
配对微信桥接。

能做什么

- 直接发送自然语言，让 DSH 在电脑工作区执行任务。
- 每个授权微信用户拥有独立的持久 Session 列表，可新建、切换、重命名和归档。
- /cancel 与 /steer 绕过普通消息队列，长任务运行时也能立即响应。
- 任务即时回执、定时进度、当前任务、队列深度和通道诊断。
- 主用户可在微信生成一次性配对码、查看/撤销授权并检查审计记录。
- workspace-write 越界操作可在微信用一次性审批码允许或拒绝。
- 查看或切换模型；为下一会话选择 Agent Preset 和工作目录。
- 会话级切换 workspace-write 与显式确认后的 danger-full-access。
- 将 /plan、/goal、/compact 等未知斜杠命令交给 DSH 原生命令系统。
- 复用 Web/桌面端已经打开的同一 Agent，不抢占、不重复创建、不错误释放。
- 重启 Host 后自动恢复 iLink 游标、微信用户映射和 DSH Session。

实际效果

微信官方 ClawBot 入口：扫码后建立官方 iLink 通道
手机端直接发任务：DSH 返回可执行命令与操作结果

DSH 电脑端工作区

电脑端仍是原版 DSH 工作区。手机创建的持久 Session 可由 Web 或桌面 Host 继续
使用，模型、工具、沙盒和会话持久化均由 DSH 本身提供。

兼容性

- 已验证 DSH 0.1.0-rc.8 与 0.1.1-rc.2。
- 支持 DSH Web Host 和桌面 DSH Host；Bundle 只运行在 Host 侧。
- Windows、macOS、Linux，Node.js 22.19.0 或更高版本。
- 需要常驻 Host。一次性 headless 进程退出后无法维持 iLink 长轮询。
- 当前接收文字和微信语音转写。图片/文件需要腾讯 CDN AES 媒体链路，暂不作为
普通文本处理。

新版本 DSH 的 sessionTitle、workspaceRegistry、commands 和 llm 服务通过
运行时能力探测接入。缺少某个可选服务时，插件会降级对应功能，不会阻止通道启动。

功能状态与路线图

已实现

- [x] 通过腾讯官方 iLink 通道完成二维码配对，不修改 DSH 核心，也不依赖桌面微信或 WxHook。
- [x] 接收微信文本任务，并将 DSH 执行结果以文本形式回复；长回复会自动分段。
- [x] 接收微信语音的官方转写文本，并按普通文本任务处理。
- [x] 为授权微信用户维护持久 DSH Session，支持新建、切换、重命名、归档和跨 Host 重启恢复。
- [x] 支持 /cancel、/steer，可在长任务执行期间取消或追加纠偏。
- [x] 支持查看或切换模型、Preset、工作目录与会话权限。
- [x] 支持将未由插件处理的 DSH 原生命令，例如 /plan、/goal、/compact，转交给 DSH 命令系统。
- [x] 可复用 Web 或桌面端已打开的同一 DSH Session，避免重复创建 Agent。
- [x] 首次配对账号默认进入授权名单；未授权消息会在送入 Agent 前被丢弃。
- [x] 默认使用 workspace-write；切换为 danger-full-access 需要发送明确确认命令。
- [x] 支持 /task、/queue、/doctor、任务即时回执和长任务定时进度。
- [x] 回复先写入持久 Outbox；临时发送失败会指数退避，Host 重启后继续重试。
- [x] 支持 /search、/archive-all confirm 和批量会话整理。
- [x] 主用户可通过 /users、/invite、/revoke、/audit 管理授权用户。
- [x] workspace-write 的 DSH 审批可通过 /approve、/reject 在微信一次性处理。

当前限制

- [ ] 当前仅处理文本和微信侧语音转写文本，不接收或理解原始语音音频。
- [ ] 不支持接收微信图片、文件、视频或其他媒体内容。
- [ ] 不支持向微信发送图片、文件、音频或视频；DSH 的结果目前仅以文本回复。
- [ ] 图片和文件需要接入腾讯 CDN 的 AES 媒体下载、解密与完整性校验链路，尚未实现。
- [ ] Host 必须常驻运行；一次性 headless 任务结束后无法持续接收微信消息。
- [ ] DSH 的 ask_user_question 仍由 Web/桌面唯一 Provider 处理；微信任务需要信息时会直接回复问题并结束当前轮次。
- [ ] 本项目按设计不提供 Windows 开机启动、计划任务或系统服务安装。

后续计划

媒体能力

- [ ] 图片接收：下载并解密微信图片媒体，校验大小和 MIME 类型后保存为受控附件，并将图片与文字上下文传给支持视觉能力的 DSH Agent。
- [ ] 文件接收：支持常见文档、代码、压缩包和表格文件的下载、解密、完整性校验及安全落盘，再作为 DSH 工作区附件处理。
- [ ] 媒体结果回传：支持将 DSH 生成或处理后的图片、文档和其他文件上传并发送到微信。
- [ ] 语音能力完善：在保留语音转写输入的基础上，评估原始音频附件处理及语音结果回传。

使用与安全

- [ ] 媒体安全策略：增加文件类型白名单、大小限制、哈希校验、隔离目录、过期清理和敏感文件保护。
- [ ] 历史查询：在不突破用户隔离的前提下增加已归档会话查询和恢复。

工程质量

- [ ] 为图片、文件和媒体回传链路补充协议测试、解密测试、异常恢复测试和端到端集成测试。
- [ ] 建立持续集成检查，覆盖支持的 DSH 版本、Windows、macOS 和 Linux。
- [ ] 在媒体协议稳定后补充兼容性矩阵、配置示例和故障排查文档。

安装

快速安装：GitHub

已经安装全局 dsh CLI 时，可直接把公开仓库安装到原版 Web Profile：

dsh plugin --profile web add github:zp-home/dsh-weixin-clawbot

桌面版把 web 换成桌面构建实际启动的 Profile。安装后继续执行下方的微信配对
步骤。需要可复现的固定版本时，使用 GitHub Release 中的 .tgz，不要依赖会变化的
main 分支。

1. 获取并打包

git clone https://github.com/zp-home/dsh-weixin-clawbot.git
cd dsh-weixin-clawbot
npm ci --legacy-peer-deps
npm test
npm pack

2. 安装进 DSH Profile

全局 dsh CLI：

dsh plugin --profile web add --force .\local-dsh-weixin-0.3.0.tgz

直接运行 DSH 源码仓库：

cd D:\path\to\deepseek-harness
node --import tsx/esm apps/cli/src/bin.ts plugin --profile web add --force D:\path\to\dsh-weixin-clawbot\local-dsh-weixin-0.3.0.tgz

桌面版把 web 换成桌面构建实际启动的 Profile。Bundle 代码和配置相同，不需要
修改桌面端源码。

Windows 上建议安装 .tgz，避免部分 DSH/pnpm 组合把绝对
link:D:/path/to/plugin 解析成错误链接。

3. 微信配对

从希望 DSH 操作的工作目录执行：

cd D:\your-workspace
D:\path\to\dsh-weixin-clawbot\node_modules\.bin\dsh-weixin.cmd setup --agent-cwd D:\your-workspace

终端会显示二维码，同时写入 $DSH_HOME/dsh-weixin/pairing-qr.png。用手机微信扫码
并按提示确认。配对返回的 Token 写入 DSH credential provider，不写入插件状态。

检查状态：

D:\path\to\dsh-weixin-clawbot\node_modules\.bin\dsh-weixin.cmd status

然后重启常驻 DSH Host，在微信里发送：

/status

解除本机配对并删除本机保存的 Token：

dsh-weixin disconnect

卸载 Bundle：

dsh plugin --profile web remove @local/dsh-weixin

卸载不会替你删除工作区内容。若要同时解除微信配对，应先执行
dsh-weixin disconnect。

微信命令

| 命令 | 作用 |
| --- | --- |
| /sessions | 列出当前微信用户的未归档会话。 |
| /use  | 切换到已有会话。 |
| /new [标题] | 保留旧会话并新建会话。 |
| /rename  | 重命名当前会话。 |
| /archive [序号或短ID] | 归档指定会话；不带参数时归档当前会话。 |
| /archive-all confirm | 批量归档当前用户的全部未归档会话。 |
| /search  | 按标题、ID 或工作区搜索未归档会话。 |
| /cancel | 立即取消正在运行的任务。 |
| /steer  | 在最近的 DSH step 边界追加修正。 |
| /task / /queue / /doctor | 查看任务、队列和通道诊断。 |
| /model [provider/model] | 查看或切换当前会话模型。 |
| /preset [id] | 查看或设置下一新会话使用的 Preset。 |
| /permission workspace-write | 使用工作区写入沙盒。 |
| /permission danger-full-access confirm | 显式确认当前会话拥有完整机器访问。 |
| /approve  / /reject  | 处理 workspace-write 的一次性操作审批。 |
| /users / /invite / /revoke ... confirm | 主用户管理授权用户。 |
| /audit [1-20] | 主用户查看最近审计记录。 |
| /cwd [路径] | 查看或设置下一新会话的工作区。 |
| /status | 查看会话、任务、工作区、Preset、权限和模型。 |
| /help | 显示手机端命令摘要。 |

完整语义和例子见 微信命令手册。

安全模型

- 首次扫码账号成为主用户；主用户生成的 10 分钟一次性配对码可增加授权用户。
- 未授权发送者在 Agent 解析前被丢弃，不提供可用于探测授权状态的错误回复。
- 不同微信用户的 Session 索引隔离，不能通过短 ID 访问其他用户的会话。
- 默认 workspace-write；需要越界时向对应微信用户发送 5 分钟一次性审批码，超时、取消或通道不可用均默认拒绝。
- 插件只处理自己创建或恢复的 Agent 的审批；借用 Web/桌面 Agent 时继续交给原界面。
- 完整机器访问必须发送精确命令
/permission danger-full-access confirm；新会话恢复配置中的默认权限。
- 状态文件不保存 bot token，但会保存 iLink 游标、允许用户 ID 和 Session 映射，仍应
视为私有文件。
- 不要提交 $DSH_HOME/.credentials.yaml、state.json、配对二维码或未经脱敏的日志。

更多细节见 安全策略 与 架构说明。

配置

Bundle 默认配置位于 cordis.patch.yml：

| 字段 | 含义 |
| --- | --- |
| stateDir | 状态目录；默认 $DSH_HOME/dsh-weixin。 |
| credentialRef | DSH credential 引用，默认 DSH_WEIXIN_BOT_TOKEN。 |
| agentCwd | 手机创建 Agent 的默认绝对工作区。 |
| agentPreset | 新微信用户/会话的默认 Agent Preset。 |
| permissionPreset | workspace-write 或部署级显式 danger-full-access。 |
| maxReplyChars | 单条微信回复的最大字符数，超长内容自动分段。 |
| turnTimeoutSeconds | 单轮手机任务的最长运行时间。 |
| pollTimeoutSeconds | iLink 长轮询初始超时。 |
| progressIntervalSeconds | 长任务进度提醒间隔；默认 90 秒。 |
| taskAcknowledgements | 是否在收到普通任务后立即回执。 |
| systemPrompt | 微信通道附加的 Agent 系统提示。 |

DSH patch 配置采用整值替换。覆盖 dsh-weixin 配置时，请完整重写需要保留的字段。

开发

npm ci --legacy-peer-deps
npm run check
npm test
npm pack

当前测试覆盖 iLink 协议封装、Unicode 分段、凭据文件保留、Agent 回复折叠、旧状态
迁移、多会话清洗、命令解析、授权审计、持久 Outbox 和一次性审批生命周期。

贡献前请阅读 CONTRIBUTING.md。第三方协议来源和声明见
THIRD_PARTY_NOTICES.md。

License

MIT