DeepSeek Harness 微信插件

English

基于腾讯官方 iLink/ClawBot 协议和扫码授权，为 DeepSeek Harness 提供独立的微信私聊通道。

这是 DeepSeek Harness 原生插件，不依赖 OpenClaw。iLink 协议、扫码流程、AES 媒体处理和消息字段参考了腾讯以 MIT 许可证开源的 Tencent/openclaw-weixin 2.4.6 实现。

功能

• 微信官方二维码登录，不需要 AppID、AppSecret 或手工申请的 key。
• 登录令牌由 Harness 凭据服务保存，不进入插件配置。
• 长轮询游标原子持久化，重启后继续消费。
• 每个微信用户对应一个持久 Harness 会话。
• 完整接入 Harness Agent preset 生命周期、结构化工具执行和 Web live session 复用。
• 接收文字、语音转写、引用上下文、AES 加密图片和普通文件。
• 发送文字，并通过微信 CDN 加密上传图片和普通文件。
• 出站文字支持与腾讯插件一致的部分 Markdown 渲染。
• 当前模型不支持视觉时，自动保存图片并降级为附件说明。
• 支持允许名单、禁用策略、有界并发、去重、重试和完整清理。
• 内置 /bot-ping、/bot-help、/bot-status、/bot-image-test、/bot-file-test、/bot-cancel。
• 按需扫码不阻塞 Harness Web；Linux 登录命令可在 Web 启动前独立完成授权。
• 工具请求审批时，可在同一微信会话用 /approve <短码> 或 /reject <短码> 决定。
• /new、/reset 创建新的持久 session；其他 Harness 斜杠命令直接进入命令运行时。

腾讯当前的 ClawBot/iLink 接入仅支持私聊。

环境要求

• Node.js 22.19 或更高版本
• pnpm 10.33.4
• DeepSeek Harness 0.1.0-rc.7 或更高版本

前置条件：ClawBot 权限

这个通道不使用 API key。你的微信账号必须已经出现官方 ClawBot 插件入口：

微信 → 我 → 设置 → 插件 → ClawBot

腾讯仍在逐步开放该功能。如果没有这个入口，不是缺少 key，也没有单独的 key 申请页面；需要等待账号获得资格，或先使用其他通道。

安装

直接从 GitHub 安装到 web profile（以下假设 dsh 已加入全局 PATH）：

dsh plugin --profile web add github:sliverp/DeepSeek-harness-weixin

安装只会更新 profile。服务尚未运行时用下面的命令启动；已经运行则重启：

dsh web

启动 dsh web 时，插件只会恢复已有凭据；没有凭据时保持离线，不会自动创建二维码，也不会阻塞或关闭 Harness Web。

需要扫码登录或更换当前微信账号时，运行：

dsh plugin --profile web exec dsh-weixin login --wait

--wait 会先显示二维码，再持续等待微信授权；成功退出码为 0，超时、扫码失败或凭据写入失败时退出码非 0。这个命令不要求 dsh web 已经运行：Web 未运行时，它会独立完成扫码并通过 Harness 官方凭据存储写入 WEIXIN_ILINK_CREDENTIAL，以后启动 Web 会自动恢复连接；Web 已运行时，它会使用仅当前用户可访问的本机 Unix Socket 请求插件登录，扫码确认前保留旧连接，确认后覆盖凭据并等待热切换完成。

这个流程即使微信已经连接也会强制重新扫码并覆盖配置，不会返回“微信已经连接，无需扫码”。命令不会启动或重启 Web，也不会把二维码链接写入 session。二维码失效或流程超时后，重新运行命令即可生成新二维码。

只需要二维码 URL（例如交给其他脚本）并等待最终结果时使用：

dsh plugin --profile web exec dsh-weixin login --url --wait

该模式会立即把 URL 写到标准输出，然后保持进程运行直到授权完成。标准输出严格等于 URL 本身：不渲染二维码、不输出状态文字，也不附加换行；诊断写入标准错误。扫码并完成连接切换（或在 Web 未运行时完成凭据持久化）后退出 0，超时或失败退出非 0，因此脚本可以直接检查退出码。Web 中的 /weixin-login 仍保留为辅助入口，但不是 Linux 命令扫码的前提。

如果没有全局 dsh，可以把上述命令中的 dsh 换成 pnpm dsh；URL-only 模式应使用 pnpm --silent dsh ...，避免 pnpm 自己的 $ node ... 提示混入标准输出。

不要转发二维码备用链接，也不要复制或提交保存后的 JSON 凭据；两者都能授权访问已连接的 ClawBot。

配置

组合包默认插入：

- id: weixin-channel
  name: deepseek-harness-weixin
  config:
    credentialRef: WEIXIN_ILINK_CREDENTIAL
    cwd: !!js process.env.DSH_WEIXIN_CWD ?? process.cwd()
    permissionPreset: workspace-write
    statePath: !!js process.env.DSH_WEIXIN_STATE_PATH ?? ''
    controlSocketPath: !!js process.env.DSH_WEIXIN_CONTROL_SOCKET ?? ''

如需调整，在 ~/.dsh/profiles/web/cordis.patch.yml 覆盖这一行：

- id: weixin-channel
  name: deepseek-harness-weixin
  config:
    credentialRef: WEIXIN_ILINK_CREDENTIAL
    cwd: /absolute/path/the-agent-may-work-in
    agentPreset: standard
    permissionPreset: workspace-write
    statePath: /absolute/path/weixin-sync.json
    controlSocketPath: /absolute/path/weixin-control.sock
    autoLogin: false
    accessPolicy: allowlist
    allowFrom: [your-ilink-user-id]
    imageInputMode: auto
    responseTimeoutMs: 300000
    approvalTimeoutMs: 240000
    maxInFlightMessages: 8
    maxReplyImages: 4
    maxInboundFiles: 10
    maxInboundFileBytes: 31457280
    maxInboundMessageFileBytes: 104857600
    maxReplyFiles: 5
    maxOutboundFileBytes: 31457280

statePath 为空时，游标默认保存在 ~/.dsh/weixin/，并以原子写入和 0600 文件权限保护。

controlSocketPath 为空时默认为 ~/.dsh/weixin/control.sock，目录权限为 0700，Socket 权限为 0600。它只用于 Web 已运行时的登录热切换，不是 login --wait 的启动前提。如自定义路径，CLI 使用相同的 DSH_WEIXIN_CONTROL_SOCKET 环境变量，或传入 dsh-weixin login --socket <path>。

autoLogin 默认为 false：缺少凭据时保持离线，只有运行上面的 Linux 命令才发起扫码。设为 true 可恢复启动 Web 时在后台自动显示二维码的行为；无论取值如何，扫码都不会阻塞 Web。

imageInputMode 默认为 auto：支持视觉的模型会收到持久图片块；纯文本模型会收到附件元数据，避免整轮失败。只有确认模型支持图片时才使用 always；使用 never 可强制文本降级。

收到 iLink FILE 消息项后，插件会在模型回合开始前下载并完成 AES 解密。文件名会收敛为安全叶子名，每条消息使用 <cwd>/.dsh-weixin/inbox/ 下独立的私有目录；模型只收到相对路径和绝对路径，并通过正常文件工具读取，插件不会执行文件，也不会把内容悄悄复制进提示词。默认最多接收 10 个文件、单文件 30 MiB、单条消息合计 100 MiB。

模型需要主动回传工作区文件时，应在最终可见回复中提供明确的 Markdown 文件链接。插件会解析真实路径，拒绝不存在的文件、目录、符号链接逃逸、空文件以及 session cwd 之外的目标，再使用官方 media_type=FILE 加密上传和 FILE 消息项发送。默认每次回复最多 5 个文件、单文件 30 MiB。

agentPreset 可省略，默认采用 Harness preset roster 当前的默认项。新 session 会把最终解析出的 preset 记录到 header；恢复持久 session 时会采用该 session 记录的 preset（包括后续的 agent-preset/selected 事件）。只有完全没有 preset 记录的旧 session 才会明确回退到当前配置或默认 preset。同一 session 已经被 Web 加载时，微信通道会复用该 live Agent，不会启动第二个 writer。

permissionPreset 可省略。配置后会先通过 ctx.permissionPresets 校验，并且只在创建新的通道 session 时写入；恢复持久 session 或借用 live Agent 时会保留该 session 已记录的权限。Harness Agent Loop 发出 approval/request 时，插件会把结构化 tool/call 中的工具名和命令发送到发起该回合的微信会话，例如：

Bash 请求执行：ls -la
回复 /approve 123456 或 /reject 123456
该审批将在 240 秒后失效。

只有同一微信会话中的匹配短码有效；每个短码只能决定一次。批准会向 Harness 返回 allowed-once，拒绝返回 rejected，超时、发送失败、取消或服务退出则按不可用/已取消闭合。approvalTimeoutMs 必须小于 responseTimeoutMs，以便审批后 Agent Loop 还有时间执行工具并生成最终回复。审批命令不受普通消息的并发上限阻塞。

本 checkout 使用 workspace-write。当前主机没有可用的本地沙箱后端时，Bash 可能请求一次性升级到 danger-full-access；只有明确回复对应的 /approve 后才会执行。批准这类升级意味着该次工具调用不受文件沙箱约束，因此必须保持 allowFrom 足够严格并在批准前检查命令。

Agent Loop 修复后的旧 session 处理

session ID namespace 已升级为 weixin-v3-single-...。已有 weixin-v1-single-... 和 weixin-v2-single-... session 都不会被删除或改写，仍可在 Web 中查看。微信通道不再恢复 v1，因为其中可能已经把工具调用载体保存成普通 assistant 文本；也不再恢复 v2，因为文字审批接入前发起的审批可能留下未闭合 turn。升级后从微信发送第一条消息时会创建干净的 v3 session。每次 /new 或 /reset 会切换到后缀为 -new-N 的新 session；旧日志保持原样，服务重启后会继续编号最大的最新 session。

斜杠命令

/new 和 /reset 由微信通道处理：如当前 Agent 正在运行，会先取消并等待其闭合，然后创建新的持久 Harness session。旧 session 不会删除，仍可在 Web 中恢复或查看。

/weixin-login 是 Linux CLI 之外的辅助入口，可从 Web 强制拉起重新扫码；它不会进入模型。其他语法合法的斜杠命令会调用 ctx.commands.execute(agent, line, signal)，而不是作为用户文字交给模型；因此会产生 Harness 原生的 command/run 和 command/done 事件。实际命令目录取决于当前 Harness 组合，通常包括 /plan、/compact、/permission、/goal、/feedback 和 /export。未知或格式错误的斜杠命令会直接返回命令提示，同样不会进入模型。

Markdown 兼容性

iLink 协议的出站文字只是普通 text_item.text 字符串，不存在独立的富文本消息类型。发送前，本插件会采用腾讯 openclaw-weixin 2.4.6 相同的部分 Markdown 过滤策略：保留代码块、行内代码、表格、列表、引用、分隔线、H1-H4 标题、粗体、删除线和非 CJK 斜体标记；微信不支持的 CJK 斜体/粗斜体标记以及 H5-H6 标记会被移除，但正文保留。Markdown 图片引用会被移除，因为 Harness 图片块会改走 AES 加密的微信 CDN 媒体链路。

这是针对微信显示能力的部分兼容，不等同于完整 CommonMark 或 HTML 渲染。

验证

日志出现 iLink 凭据验证成功后，从已连接的微信会话发送 /bot-ping，应收到：

pong — DeepSeek Harness 微信机器人已连接。

发送 /bot-image-test 和 /bot-file-test 可以独立验证 AES 加密、微信 CDN 图片和文件投递，不依赖模型生成媒体。然后发送普通文字、照片和一个小文档，让机器人读取文档；再要求它创建并回传文件，回复中应收到原生文件附件。

工具审批可发送“我当前有啥文件？”验证。收到 Bash 请求执行：... 后，原样回复其中的 /approve <短码>；插件应先确认批准，随后只发送工具执行后的最终文件列表。回复 /reject <短码> 则拒绝该次调用。

重新登录

无需先删除凭据，直接运行 dsh plugin --profile web exec dsh-weixin login --wait 即可强制重新扫码并覆盖 WEIXIN_ILINK_CREDENTIAL。如果微信提示 ClawBot 已绑定其他本地实例，请先在微信中解除旧连接。

开发

pnpm install
pnpm run check

仓库固定使用 pnpm 10.33.4，不要求 pnpm 11。

仓库提交构建后的 dist/，因此从 GitHub 安装时不需要授权依赖执行构建脚本。

许可证与上游声明

MIT。协议派生部分在 [LICENSE](LICENSE) 中保留腾讯版权和许可证声明。