dsh-wechat-persistent

真持久微信桥插件 for DeepSeek Harness — 一个微信用户 = 一个持久 DSH 会话。

Persistent WeChat bridge for DeepSeek Harness. One WeChat user = one persistent DSH session.

属于 DeepSeek Harness 社区插件生态（@deepseek-ai/dsh / Cordis 插件体系，dsh-* 命名规范）。

A DeepSeek Harness community plugin (Cordis plugin family of @deepseek-ai/dsh, dsh-* naming).

与社区现有微信桥（headless 一次性会话 + 历史注入）不同，本插件基于 DSH 官方 agents.create / agents.resume 实现真正的持久会话：上下文始终延续，进程重启后自动恢复。

Unlike community bridges (headless one-shot + history injection), this plugin uses DSH's official agents.create / agents.resume for real persistent sessions: context is preserved across messages and survives process restarts.

---

✨ 特性 / Features

• ✅ 真持久会话 / Real persistent sessions — 第二次消息记得第一次（同一会话延续）
• ✅ iLink 官方通道 / Official iLink channel — 腾讯官方微信 Bot API，无逆向、无封号风险
• ✅ Token 长期有效 / Long-lived token — 配对一次长期可用；-14 短暂过期自动暂停重试，不用每天扫码
• ✅ 会话映射持久化 / Persistent session registry — 微信用户 ↔ DSH 会话映射落盘，重启不丢
• ✅ 纯出站 / Pure outbound — 无需公网 IP、无需入站监听，本机直接长轮询

📦 安装 / Install

# 1. 克隆仓库
git clone https://github.com/<your-name>/dsh-wechat-persistent.git
cd dsh-wechat-persistent

# 2. 挂载到 profile（以 web 为例）
# 编辑 ~/.dsh/profiles/web/cordis.patch.yml，追加：

- insert:
    - id: dsh-wechat-persistent
      name: 'file:///绝对/路径/dsh-wechat-persistent/src/index.ts'

⚠️ Windows 必须用 file:///C:/... 格式，裸盘符 C:/... 会被当作 URL scheme 导致加载失败。

# 3. 启动 DSH
dsh web

📱 配对 / Pairing

node pair.mjs

终端会打印一个 liteapp.weixin.qq.com 链接，用手机微信打开并确认。配对成功后 token 自动写入 ~/.dsh/wechat-persistent/wechat-auth.json，重启 DSH 即生效。

The script prints a liteapp.weixin.qq.com URL — open it on your phone's WeChat and confirm. The token is saved to ~/.dsh/wechat-persistent/wechat-auth.json; restart DSH to apply.

🧠 工作原理 / How it works

WeChat message (iLink long-polling)
  → look up session registry
    ├─ no mapping  → agents.create({ sessionId, agentOptions, meta.cwd, setup: mount preset })
    └─ has mapping → agents.resume({ resumeSessionId })
  → agent.followup(userMessage(text))   // wake & enqueue next turn
  → agent.whenIdle()                    // wait until quiescence
  → session.deriveMessages()            // read the latest assistant reply
  → sendMessage back to WeChat

🕳️ 踩坑记录 / Pitfalls (all hard-won)

坑	症状	解法
Windows 插件路径	ERR_UNSUPPORTED_ESM_URL_SCHEME: Received protocol 'c:'	patch 路径用 file:///C:/...
缺 agentOptions	回合失败 {{model}} / {{provider}} has no value	agents.create/resume 传 agentOptions: { provider, model }
缺 meta.cwd	回合失败 {{cwd}} has no value (deployment:persona)	meta.cwd 必须有值（默认用户主目录）
缺 preset 挂载	会话没有官方工具（Bash/Read/Edit 全缺）	create/resume 的 setup 回调 presets.mount
agent.send() 不生效	消息进 session 但 agent 不跑	用 agent.followup()（wake 的正规 API）
社区传"凭证24h过期"	—	实测 token 长期有效；-14 暂停 10 分钟重试即可（Hermes 同款策略）
不 dispose	每次消息重建会话（假固定）	handleMessage finally 里 handle.dispose()
ask_user_question	提问微信收不到 + agent 永久等待	微信 preset 禁用 tool-ask-user，纯文本编号提问

📖 完整开发指南（正确路线 + 13 个坑 + 配置清单）见 DEVELOPMENT.md

Full developer guide (the right way + all 13 pitfalls + config checklist): see DEVELOPMENT.md

🧪 验证 / Verification

# 真持久验证：发两条消息
# 1. "你好" → 回复
# 2. "我刚才说了什么？" → 如果还记得，持久会话生效 ✅

🗂️ 目录结构 / Structure

DEVELOPMENT.md # 完整开发指南：正确路线 + 全部踩坑记录（README 的深度版）
README.md      # 项目介绍 + 快速开始
src/
  index.ts      # 主入口：长轮询 + 消息路由 + 回复
  session.mjs   # 会话路由：create/resume + followup + 读回复
  ilink.mjs     # iLink 协议客户端（MIT，参考 dsh-wechat-bridge & 腾讯官方 SDK 2.4.6）
pair.mjs        # 扫码配对脚本

🙏 致谢 / Credits

• iLink 协议实现参考 dsh-wechat-bridge（MIT）与腾讯官方 @tencent-weixin/openclaw-weixin@2.4.6
• 会话编排思路参考 dsh-memory-evolve 的 de_session（spawn/wake 封装）

📄 License

MIT