dsh-wechat-auto-reply
一个接入 DeepSeek Harness（DSH） 的微信自动回复插件：监听 Windows 微信私聊消息，交给 DSH Agent 生成回复，再自动发回微信。
⚠️ 免责声明（请务必先读）
- 本项目仅用于技术演示与学习交流，用于验证「DSH 插件 + Windows 微信自动化」这条技术链路，不构成任何产品或服务。
- 请仅使用小号 / 测试账号进行测试。不要把本项目用于主力微信号，也不要在包含重要联系人、重要资料的微信上运行。
- 存在账号被封禁的风险。微信官方用户协议原则上不允许使用第三方自动化工具操作客户端；本项目通过 UI 自动化模拟人工操作，仍可能被判定为异常行为，由此导致的封号、限制登录、消息丢失等后果由使用者自行承担。
- 本项目与腾讯公司、微信团队没有任何隶属、合作或授权关系。"微信"、"WeChat" 等名称与商标归腾讯公司所有，本项目仅作技术描述性引用。
- 请遵守你所在国家 / 地区的法律法规以及微信的用户协议，不要用于营销群发、骚扰他人、自动加好友、爬取通讯录等用途。
- 本项目按 MIT 协议"按原样"提供，不附带任何明示或暗示的担保。
如果你不能接受以上任何一条，请不要下载、安装或运行本项目。
目录
1. 项目介绍
dsh-wechat-auto-reply 是一个 DeepSeek Harness 插件（Host 插件），它把「微信私聊」接到「DSH Agent」：
- 你在微信里收到好友消息 → 插件读取消息 → 交给 DSH 生成回复 → 随机等待 3~8 秒后自动发回；
- 支持好友白名单，只有名单里的联系人会触发自动回复（默认名单为空，即不回复任何人）；
- 支持聊天指令：
/off 暂停、/on 开启、/status 查看状态、/reset 清空上下文、/help 帮助；
- 每个联系人维护独立的对话上下文，并持久化到本地，DSH 重启后仍能延续；
- 每条收到的消息与每条发出的回复都会写入本地聊天日志（JSONL，按天切分）；
- 生成回复有两种后端：
agent（默认）：通过 DSH 的 Agent 服务，每个联系人一个独立 DSH 会话，使用你在 DSH 里配置的模型；llm：通过 DSH 的 LLM 服务直接调用指定 provider / model，不启动完整 Agent，开销更小。
适合：个人技术验证、把 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 插件管理器安装本地插件
- 打开 DeepSeek Harness → 设置 → 插件；
- 选择"安装本地插件 / 从文件夹安装"，指向本仓库根目录（包含
package.json 的目录）；
- 安装后重启 DSH，在插件列表里确认
dsh-wechat-auto-reply 已启用。
方式 B：手动合并 patch 到 DSH profile
- 打开你的 DSH profile 目录（默认 Windows 为
C:\Users\<你>\.dsh\profiles\desktop\）；
- 找到该 profile 的
cordis.patch.yml，把本仓库 cordis.patch.yml 里的 insert 行合并进去
（name 必须能被 Node 解析到本仓库，通常是 npm install <本地路径> 或 npm link 到 profile 的 node_modules）；
- 重启 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. 启动后完全没反应，微信发消息也不回
按顺序排查：
config.yaml 的 wechat.whitelist 是否填了对方？为空时插件不会回复任何人（日志会有一行 WARN 提示）；- 看
logs/runtime-*.log 里是否有"联系人不在白名单内"；
- 是否处于暂停状态（发
/status 或删除 logs/state/auto-reply.json 后重启）；
- DSH 插件是否真的加载成功（插件列表里是否启用、DSH 日志里有没有本插件启动横幅）；
- 检查
bridge.python 是否指向装好 wxauto 的那个 Python（用虚拟环境时尤其容易错）。
Q2. 日志提示"启动失败 / 导入 wxauto 失败"
# 在插件使用的 Python 环境里执行
pip install -r python/requirements.txt
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. 如何只让某一个人触发自动回复？
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. 开发与测试
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
