微信自动回复 shenianyang123/dsh-wechat-auto-reply

dsh-wechat-auto-reply

一个微信自动回复插件，接入 DeepSeek Harness（DSH）：监听 Windows 微信私聊消息，交给 DSH 智能体生成回复，再自动发回微信。

⚠️ 免责声明（请务必先读）

1. 本项目仅用于技术演示与学习交流，用来验证「DSH 插件 + Windows 微信自动化」这条技术链路，不构成任何产品或服务。
2. 请仅使用小号 / 测试账号进行测试。不要把本项目用于主力微信号，也不要在包含重要联系人、重要资料的微信上运行。
3. 存在账号被封禁的风险。微信官方用户协议原则上不允许使用第三方自动化工具操作客户端；本项目通过 UI 自动化模拟人工操作，仍可能被判定为异常行为，由此导致的封号、限制登录、消息丢失等后果由使用者自行承担。
4. 本项目与腾讯公司、微信团队没有任何隶属、合作或授权关系。「微信」「WeChat」等名称与商标归腾讯公司所有，本项目仅作技术描述性引用。
5. 请遵守你所在国家 / 地区的法律法规以及微信的用户协议，不要用于营销群发、骚扰他人、自动加好友、爬取通讯录等用途。
6. 本项目按 MIT 协议「按原样」提供，不附带任何明示或暗示的担保。

如果你不能接受以上任何一条，请不要下载、安装或运行本项目。

目录

- 1. 项目介绍
- 2. 工作原理
- 3. 环境要求
- 4. 安装步骤
- 5. 启动命令
- 6. 配置说明
- 7. 聊天指令
- 8. 日志与上下文
- 9. 常见问题
- 10. 目录结构
- 11. 开发与测试
- 12. 安全与合规建议
- 13. 许可证

1. 项目介绍

dsh-wechat-auto-reply 是一个 DeepSeek Harness 插件（Host 插件），它把「微信私聊」接到「DSH 智能体」：

- 你在微信里收到好友消息 → 插件读取消息 → 交给 DSH 生成回复 → 随机等待 3~8 秒后自动发回；
- 支持好友白名单，只有名单里的联系人会触发自动回复（默认名单为空，即不回复任何人）；
- 支持聊天指令：/off 暂停、/on 开启、/status 查看状态、/reset 清空上下文、/help 帮助；
- 每个联系人维护独立的对话上下文，并持久化到本地，DSH 重启后仍能延续；
- 每条收到的消息与每条发出的回复都会写入本地聊天日志（JSONL，按天切分）；
- 生成回复有两种后端：
- agent（默认）：通过 DSH 的智能体服务，每个联系人一个独立 DSH 会话，使用你在 DSH 里配置的模型；
- llm：通过 DSH 的 LLM 服务直接调用指定 provider / model，不启动完整智能体，开销更小。

适合：个人技术验证、把 DSH 接入日常通讯渠道的实验。
不适合：生产客服、营销、群发、多账号运营（见免责声明）。

2. 工作原理

┌──────────────┐ ①新消息 ┌───────────────────────────┐ │ PC 微信 │ ───────────▶ │ python/wxauto_bridge.py │
│ (wxauto UI │ │ - 监听/轮询消息 │
│ 自动化) │ ◀─────────── │ - 发送文本 │ └──────────────┘ ④发送回复 └────────────┬──────────────┘ │ ②stdin/stdout JSON 行协议 ▼ ┌──────────────────────────────┐ │ src/wechat/bridge.js │ │ 子进程管理 / 自动重启 / 超时 │ └──────────────┬───────────────┘ │ ③message 事件 ▼ ┌──────────────────────────────┐ │ src/runtime.js │ │ 白名单 → 指令 → 暂停判断 │ │ → 随机延迟 → 生成 → 发送 │ │ → 写日志 → 更新上下文 │ └───────┬──────────────┬───────┘ │ │ ┌───────────▼───┐ ┌──────▼──────────┐ │ agent-engine │ │ llm-engine │ │ ctx.agents │ │ ctx.llm.stream │
│ (DSH Agent) │ │ (直连模型) │
└───────────────┘ └─────────────────┘
关键设计：

- 微信与 DSH 进程隔离：wxauto 跑在独立 Python 子进程里，崩溃只会触发 Node 侧自动重启，不会拖垮 DSH；
- 协议极简：一行一个 JSON，stdout 只承载协议（库的 print 被重定向到 stderr），便于排查；
- 业务与平台解耦：runtime.js 不直接依赖 DSH 或 wxauto，桥接和引擎都是注入的，因此可以用 Mock 完整自测。

3. 环境要求

| 项目 | 要求 | 说明 |
| 操作系统 | Windows 10 / 11 | wxauto 依赖 Windows UI 自动化，macOS / Linux 无法运行微信客户端自动化 |
| Node.js | >= 20.10（推荐 22 LTS / 24） | 插件与桥接管理进程 |
| Python | 3.9 ~ 3.12（3.13 通常也可） | 运行 wxauto 桥接；建议单独建虚拟环境 |
| 微信 | PC 版微信 3.9.x 客户端（非"微信 4.x"） | 需保持登录、窗口不要最小化到托盘、测试期间不要锁屏后休眠 |
| DeepSeek Harness | 已安装并能正常工作 | 需要 ctx.agents / ctx.llm 服务（DSH 桌面版默认提供） |

其他要求：

- 需要能访问 DSH 已配置的模型服务（本地或云端），确保 DSH 里能正常对话；
- Python 需要能 pip install wxauto（国内网络可加镜像 -i https://pypi.tuna.tsinghua.edu.cn/simple）；
- 运行时请保持 PC 微信窗口处于未被遮挡、未最小化的状态（UI 自动化需要能读取到窗口），但不需要让微信一直保持在前台。

4. 安装步骤

4.1 获取代码

git clone https://github.com/shenianyang123/dsh-wechat-auto-reply.git
cd dsh-wechat-auto-reply

4.2 安装 Node 依赖

npm install

只有 yaml 一个运行时依赖；如果只是想先本地跑通流程，可以跳过这一步直接 npm run dev 看效果吗？不行——npm run dev 也会读 config.yaml，同样需要 yaml。

4.3 安装 Python 依赖（微信桥接）

建议在项目目录下创建虚拟环境，避免污染全局 Python
python -m venv .venv
.venv\Scripts\activate

pip install -r python/requirements.txt

验证 wxauto 是否可用（需先启动并登录 PC 微信）：

python python/wxauto_bridge.py --check

正常情况下会输出类似：

{"type":"ready","ok":true,"python":"3.11.9","wxauto":"3.9.11","wechat_ui":true,"notes":["已找到 PC 微信窗口，可以正常监听。"]}

如果 wechat_ui 为 false，请先解决微信连接问题（见 常见问题）。

4.4 作为 DSH 插件安装

本仓库同时是一个标准的 DSH 插件 bundle：package.json 里通过
"dsh": { "bundle": { "patch": "./cordis.patch.yml" } } 声明了插件 patch，cordis.patch.yml 会往
DSH 的插件列表里插入一行：

- insert:
- id: dsh-wechat-auto-reply
name: dsh-wechat-auto-reply
config: {}

安装方式（任选其一，具体界面以你的 DSH 版本为准）：

方式 A：通过 DSH 插件管理器安装本地插件

1. 打开 DeepSeek Harness → 设置 → 插件；
2. 选择"安装本地插件 / 从文件夹安装"，指向本仓库根目录（包含 package.json 的目录）；
3. 安装后重启 DSH，在插件列表里确认 dsh-wechat-auto-reply 已启用。

方式 B：手动合并 patch 到 DSH profile

1. 打开你的 DSH profile 目录（默认 Windows 为 C:\Users\<你>\.dsh\profiles\desktop\）；
2. 找到该 profile 的 cordis.patch.yml，把本仓库 cordis.patch.yml 里的 insert 行合并进去（name 必须能被 Node 解析到本仓库，通常是 npm install <本地路径> 或 npm link 到 profile 的 node_modules）；
3. 重启 DSH。

提示：插件配置里唯一可选项是 configPath，用于指定一个非默认位置的 config.yaml：
config: { configPath: "D:/path/to/config.yaml" }。不填则按
环境变量 DSH_WECHAT_CONFIG → 包目录 config.yaml → 当前工作目录 config.yaml 的顺序查找。

4.5 修改配置

编辑仓库根目录的 config.yaml，至少填写 wechat.whitelist（例如你的小号或"文件传输助手"），否则插件出于安全默认不会回复任何人。

4.6 启动

重启 DSH 或在插件管理里重新加载插件。成功时 logs/runtime-YYYY-MM-DD.log （以及 DSH 控制台）会看到：

dsh-wechat-auto-reply 已启动配置文件：...\config.yaml 回复后端：agent（每个联系人一个 DSH 会话，使用 DSH 默认模型）白名单：文件传输助手随机延迟：3~8 秒日志目录：...\logs 当前状态：运行中

然后用小号给登录的微信发一条消息试试。

5. 启动命令

5.1 作为 DSH 插件（正式使用）

安装 / 启用后由 DSH 自动拉起，没有额外命令。常用操作：

| 操作 | 方式 |
| 启动 / 重启 | 重启 DSH，或在插件管理器中停用→启用 |
| 查看运行日志 | 打开 logs/runtime-<日期>.log，或 DSH 控制台日志 |
| 查看聊天记录 | 打开 logs/chat-<日期>.jsonl |
| 临时暂停自动回复 | 用白名单内的微信发送 /off；恢复发送 /on |

5.2 本地自测（不接微信、不接 DSH）

npm run dev

用 Mock 微信 + Mock 模型把整条链路跑一遍，适合验证配置解析、指令、白名单、日志、上下文逻辑。
不会真的发微信、不会真的调用模型。

自定义演示脚本：

npm run dev -- --messages "文件传输助手|你好;/status;/off;在吗;/on"
npm run dev -- --config ./config.local.yaml # 指定配置文件
npm run dev -- --keep-delay # 保留 config.yaml 里的 3~8 秒延迟

5.3 单独调试微信桥接

python python/wxauto_bridge.py --check # 自检
python python/wxauto_bridge.py # 手动启动桥接（等 Node 侧发命令）

单独运行时它会等待 stdin 的 JSON 命令，可用于手工验证：

{"id":"1","cmd":"start","whitelist":["文件传输助手"],"pollInterval":0.4}
{"id":"2","cmd":"send","contact":"文件传输助手","text":"来自桥接的手工测试"}

5.4 语法检查

npm run check

5.5 其他 npm 脚本

| 命令 | 作用 |
| npm run dev | Mock 全链路自测（不接微信 / DSH） |
| npm run check | node --check + python -m py_compile 语法检查 |
| npm run bridge | 直接运行 Python 桥接（调试用） |
| npm run bridge:check | Python 桥接环境自检 |

6. 配置说明

配置文件为仓库根目录的 config.yaml（完整示例见文件内注释）。所有字段及默认值：

6.1 wechat —— 微信与白名单

| 字段 | 类型 | 默认值 | 说明 |
| whitelist | 数组 | [] | 好友白名单。只有列表中的联系人（备注名或昵称）会触发自动回复；空数组 = 不回复任何人（安全默认）。写 [""] 表示全部联系人，强烈不推荐。群聊可填群名，或填群成员的显示名来实现「只在某个人的发言时回复」。 |
| commandContacts | 数组 | [] | 允许发送 /off、/on 等控制指令的联系人；留空时等于 whitelist。建议单独填成你自己的账号，避免好友误关自动回复。 |

匹配规则：忽略大小写、做 Unicode NFKC 归一化（全角/半角视为相同）、去首尾空格。
请填写你在微信里看到的显示名（有备注时以备注为准）。

6.2 reply —— 回复行为

| 字段 | 类型 | 默认值 | 说明 |
| minDelaySeconds | 数字 | 3 | 收到消息后随机延迟的最小秒数 |
| maxDelaySeconds | 数字 | 8 | 随机延迟的最大秒数；两者相同则固定延迟，写 0 则立即回复 |
| maxReplyChars | 数字 | 800 | 单条回复最大字符数，超出截断；0 = 不限制 |
| replyToSelf | 布尔 | false | 是否把自己账号发出的消息也当作输入（一般保持 false） |

6.3 dsh —— 回复后端

| 字段 | 类型 | 默认值 | 说明 |
| backend | agent \| llm | agent | agent：每个联系人一个独立 DSH Agent 会话（共享 DSH 默认模型与工具）；llm：直接调用 ctx.llm.stream，更轻量。 |
| provider | 字符串 | "" | 仅 backend: llm 时使用；agent 模式留空即使用 DSH 默认模型 |
| model | 字符串 | "" | 同上 |
| timeoutMs | 数字 | 180000 | 单次生成超时（毫秒），超时则该条消息不回复并写错误日志 |
| maxTokens | 数字 | 0 | 最大生成 token 数；0 = 交给 DSH / 模型默认值 |
| temperature | 数字 \| null | 0.7 | 采样温度；llm 后端生效，null = 不传该参数 |
| systemPrompt | 字符串 | 见配置注释 | 人设 / 角色提示词，建议保留「不要透露自己是 AI 正在自动回复」等约束 |
| context.maxTurns | 数字 | 12 | 每个联系人保留最近多少轮对话（一轮 = 用户 + 助手） |
| context.maxChars | 数字 | 6000 | 每个联系人上下文的字符上限，超出从最旧的开始丢弃 |
| context.persist | 布尔 | true | 是否把上下文持久化到磁盘（DSH 重启后延续） |

6.4 logging —— 日志

| 字段 | 类型 | 默认值 | 说明 |
| dir | 字符串 | ./logs | 日志目录，相对路径相对 config.yaml 所在目录 |
| console | 布尔 | true | 是否同时输出到控制台 / DSH 日志 |

生成的日志：
- logs/chat-YYYY-MM-DD.jsonl：聊天记录（收到的消息 + 发出的回复，含时间、联系人、方向、后端、耗时）；
- logs/runtime-YYYY-MM-DD.log：运行日志（启动、白名单拦截、错误、桥接重启等）；
- logs/state/：插件内部状态（/on /off 暂停状态、DSH 会话 id、每个联系人的上下文），不要提交到 git。

6.5 bridge —— Python 桥接

| 字段 | 类型 | 默认值 | 说明 |
| python | 字符串 | python | Python 命令（如 .venv\\Scripts\\python.exe 或绝对路径） |
| script | 字符串 | ./python/wxauto_bridge.py | 桥接脚本路径 |
| pollInterval | 数字 | 0.4 | 轮询间隔（秒），越小越灵敏但越耗 CPU；建议 0.2 ~ 1.0 |
| maxRestarts | 数字 | 5 | 桥接进程异常退出后的最大重启次数 |
| readyTimeoutMs | 数字 | 20000 | 等待桥接就绪的超时（微信登录慢时可调大） |
| sendTimeoutMs | 数字 | 15000 | 单条消息发送超时 |

6.6 commands —— 聊天指令

| 字段 | 类型 | 默认值 | 说明 |
| prefix | 字符串 | / | 指令前缀，可改为 ! 等 |
| replyWhenPaused | 布尔 | false | 暂停期间收到消息时，是否回一句"已暂停，稍后回复" |

7. 聊天指令

在有指令权限的会话（默认 = 白名单联系人）里发送以下消息（大小写不敏感，支持中英文别名）：

| 指令 | 别名 | 作用 |
| /on | /开启、/打开 | 恢复自动回复（插件重启后暂停状态依旧保留） |
| /off | /关闭、/暂停 | 暂停自动回复；暂停期间收到的消息只记录、不回复（replyWhenPaused 可回提示） |
| /status | /状态 | 查看开关、后端、白名单、微信连接、上下文轮数与本次运行统计 |
| /reset | /重置、/清空 | 清空与你的对话上下文，并开启一个全新的 DSH 会话 |
| /help | /帮助 | 显示帮助 |

示例：

/status
【自动回复状态】开关：运行中后端：agent 白名单：文件传输助手微信连接：已连接与你的上下文：3 轮本次运行：收到 6 条 / 已回复 4 条 / 忽略 2 条 / 出错 0 次

指令不会进入对话上下文，也不消耗模型调用。/off 状态会写入 logs/state/auto-reply.json，所以重启插件后依然是暂停状态，需要 /on 才会恢复（这是有意设计，避免重启后意外开始自动回复）。

8. 日志与上下文

8.1 聊天日志 logs/chat-YYYY-MM-DD.jsonl

每行一个 JSON：

{"ts":"2026-10-18T08:12:33.512Z","time":"16:12:33","direction":"in","contact":"文件传输助手","text":"你好","msgType":"friend","backend":"","latencyMs":null,"note":""} {"ts":"2026-10-18T08:12:38.902Z","time":"16:12:38","direction":"out","contact":"文件传输助手","text":"你好！有什么可以帮你的吗？","msgType":"friend","backend":"agent","latencyMs":4390,"note":""}

字段说明：

| 字段 | 说明 |
| direction | in 收到 / out 发出 |
| contact | 会话（好友）名 |
| text | 消息正文 |
| msgType | friend / self / system 等；指令回复为 system |
| backend | 生成回复的后端；指令 / 系统提示为 system |
| latencyMs | 从开始生成到发送完成的耗时 |
| note | 备注，如 command:/off |

用 jq 快速统计：

jq -r 'select(.direction=="out") | .contact' logs/chat-.jsonl | sort | uniq -c

8.2 上下文

- 每个联系人独立上下文（以会话名区分），默认保留最近 12 轮 / 6000 字符；
- agent 后端：上下文由 DSH Agent 会话自身维护，同时插件在本地保存一份（用于 maxTurns 裁剪与持久化， /reset 时会连同 DSH 会话一起换新）；
- llm 后端：上下文完全由本插件维护，直接拼进 messages；
- 上下文持久化在 logs/state/ctx-.json，重启 DSH 后继续沿用；
- 想彻底重新开始：发 /reset，或停止插件后删除 logs/state/ 目录。

9. 常见问题

Q1. 启动后完全没反应，微信发消息也不回

按顺序排查：

1. config.yaml 的 wechat.whitelist 是否填了对方？为空时插件不会回复任何人（日志会有一行 WARN 提示）；
2. 看 logs/runtime-.log 里是否有"联系人不在白名单内"；
3. 是否处于暂停状态（发 /status 或删除 logs/state/auto-reply.json 后重启）；
4. DSH 插件是否真的加载成功（插件列表里是否启用、DSH 日志里有没有本插件启动横幅）；
5. 检查 bridge.python 是否指向装好 wxauto 的那个 Python（用虚拟环境时尤其容易错）。

Q2. 日志提示"启动失败 / 导入 wxauto 失败"

在插件使用的 Python 环境里执行
pip install -r python/requirements.txtbash
python python/wxauto_bridge.py --check

若提示找不到 python 命令，把 bridge.python 改成绝对路径，例如 C:/Users/you/AppData/Local/Programs/Python/Python311/python.exe 或 .venv\\Scripts\\python.exe。

Q3. 提示「连接 PC 微信失败」

- 确认 PC 版微信已启动并登录（wxauto 需要的是 PC 客户端，不是网页版/手机版）；
- 确认微信版本是 3.9.x（微信 4.x 的 UI 结构变化，wxauto 旧版本可能不兼容）；
- 把微信窗口从托盘恢复出来，不要最小化；测试时不要锁屏；
- 关闭其他同样操作微信窗口的工具（如其他自动化脚本），避免抢占 UI 自动化接口；
- 如果改过微信字体缩放 / 高分屏缩放，尝试恢复 100% 再试。

Q4. 能收到消息但发不出去 / 发送超时

- 检查是否被微信风控限制（手动发一条是否能成功）；
- 调大 bridge.sendTimeoutMs（如 30000）；
- 查看桥接 stderr（运行日志里会有 [wxauto-bridge] 前缀的内容）；
- 确认目标会话没有被「折叠/免打扰隐藏」到无法定位。

Q5. 回复很慢

- backend: agent 会启动完整 Agent 会话（含工具），首条消息较慢；可以换成 backend: llm 并显式指定 provider/model；
- 延迟本身由 reply.minDelaySeconds / maxDelaySeconds 控制，检查是否配置过大；
- 模型侧网络慢也会体现在 latencyMs 上，结合日志判断。

Q6. 如何只让某一个人触发自动回复？
yaml
wechat:
whitelist:
- "文件传输助手" # 再安全一点：先用文件传输助手自测

注意：白名单是「允许自动回复的会话」，不是「忽略列表」。

Q7. 上下文错乱 / 想清空记忆

发送 /reset，或停止插件后删除 logs/state/ctx-.json 与 logs/state/agent-sessions.json。

Q8. 会不会封号？

有风险，而且无法给出安全承诺。 任何通过 UI 自动化操作微信的方案都可能被判定为异常。
请只在小号上测试、控制回复频率（保留 3~8 秒延迟）、不要群发、不要自动加好友。
如果你不能承担风险，请不要运行本项目。

Q9. 支持 macOS / Linux 吗？

不支持。wxauto 依赖 Windows UI 自动化（uiautomation），只能在 Windows 上运行。
macOS / Linux 用户可以用 npm run dev 验证插件逻辑，但无法接入真实微信。

Q10. 支持微信 4.x 吗？

暂不保证。本项目针对 PC 微信 3.9.x + wxauto 3.9.x 编写；微信 4.x 的界面结构不同，可能需要等待 wxauto 适配或自行修改 python/wxauto_bridge.py 中获取消息/发送消息的部分。

Q11. 会不会把聊天记录上传到别处？

不会。除调用你配置的 DSH 模型服务生成回复外，消息只写入本地 logs/ 目录，不会上传到本项目的任何服务器（本项目没有服务器）。

10. 目录结构

dsh-wechat-auto-reply/
├── package.json # npm 包信息 + dsh.bundle.patch（DSH 插件声明） ├── cordis.patch.yml # DSH 插件行 patch ├── config.yaml # 用户配置 ├── AGENTS.md # 贡献 / 二次开发指南 ├── README.md # 本文档 ├── LICENSE # MIT ├── scripts/ │ └── check-syntax.js # 语法检查 ├── src/ │ ├── index.js # DSH 插件入口（apply） │ ├── config.js # 配置加载与校验 │ ├── logger.js # 聊天 / 运行日志 │ ├── context.js # 单用户上下文 │ ├── runtime.js # 消息处理主流程 │ ├── util.js # 工具函数 │ ├── dev.js # 本地 Mock 自测 │ ├── dsh/ │ │ ├── factory.js │ │ ├── agent-engine.js │ │ └── llm-engine.js │ └── wechat/ │ ├── bridge.js │ └── mock-bridge.js └── python/ ├── wxauto_bridge.py # wxauto 桥接进程 └── requirements.txt

11. 开发与测试 bash
npm install
npm run check # 语法检查（JS + Python）
npm run dev # Mock 全链路自测

npm run dev 会用 Mock 微信与 Mock 模型走真实业务逻辑（指令、白名单、延迟、去重、串行队列、
日志、上下文全部是同一份代码），输出示例：

[dev] 投递：文件传输助手 → 你好，请用一句话介绍你自己 [dsh-wechat-auto-reply] 已回复「文件传输助手」（生成耗时 31 ms）：【开发模式】... ================ 开发模式结果 ================ 模拟消息：7 条引擎调用：3 次实际发送：6 条

改动建议与代码约定见 AGENTS.md。

12. 安全与合规建议

- 只用小号 / 测试号，主力微信不要装；
- 白名单只填必要联系人，永远不要用 [""]；
- 保留随机延迟（3~8 秒），不要改成 0 秒高频回复；
- 不要在公开仓库 / 截图里暴露自己的微信号、二维码、聊天记录；
- 不要把本插件用于群发、营销、自动加好友、爬取通讯录；
- 定期清理 logs/（含聊天记录），避免本地敏感数据长期堆积；
- 商业用途请先自行完成合规评估，本项目不提供任何合规承诺。

13. 许可证

MIT © 2026 dsh-wechat-auto-reply contributors