huaqian695-sudo/dsh-wechat-bot

🤖 DSH 微信机器人

基于 DeepSeek Harness 的微信 AI 自动化机器人

让微信拥有 AI 对话、记忆、日程提醒、天气查询、联网搜索的能力

Python 3.10+
License: MIT
Tests
[Platform]()
GitHub stars

✨ 功能一览

💬 对话能力
- 私聊全自动：大号发消息全部 AI 回复
- 群聊 @ 回复：群里 @bot 才说话
- 双通道切换：API 秒回 / Harness 全权限
- 主动发言：冷场/被提/问句时自然插话

🧠 智能特性
- 面具系统：ai助手 / 女友 / 群聊助手，一键切换人格
- 长期记忆：记住人和事，跨会话持久
- 日程提醒：说"周五3点考试"，到点主动提醒
- 联网搜索 + 天气：实时信息自动查询

🛡️ 安全设计
- 群聊硬约束：技术上禁用 11 个危险工具
- 绝不退化：受限场景不会静默升级为全权限
- 长文本恢复：微信加密消息自动从全文索引恢复明文

🖥️ Web 控制台
- 零依赖本地看板（7 个 Tab）
- 会话管理 / 配置热重载 / 面具编辑
- 实时日志流（SSE）
- Token 鉴权保护

🚀 快速开始

方式一：直接运行（推荐）

1. 安装依赖
pip install pyyaml wechatauto-replica

2. 校验配置（不连微信）
python -m wechat_agent.main --check

3. 启动
python -m wechat_agent.main

方式二：使用打包好的 exe

1. 下载 dist-app 文件夹
2. 编辑 config/settings.yaml，填入微信昵称和账号目录
3. 确保 ~/.dsh/.credentials.yaml 里有 API Key
4. 登录小号微信，双击 wechat-agent.exe

启动前确认

- ✅ 小号微信已登录在电脑上
- ✅ 微信窗口未锁屏、未最小化
- ✅ config/settings.yaml 里的昵称和微信里完全一致

⚠️ 风险提示：个人微信自动化有封号风险，务必使用小号，勿用于非法用途。

📖 工作原理

你(大号) → 给小号发消息
↓
电脑端小号微信收到 → wechatauto 读数据库
↓
bot 判断：会话 → 面具 / 模式 / 是否监听 / 是否共享记忆
↓
拼提示词：人设 → 规则 → 记忆 → 群聊行为 → 上下文 → 指令协议
↓
调 LLM 通道 → API 直连(快) 或 本地 Harness(全权限)
↓
AI 回复 → 程序执行  指令 → 发回微信
↓
后台：群聊记忆自动总结 / 日程提醒 / 水位断点续读

双通道模式

| 模式 | 速度 | 能力 | 适合场景 |
|:---:|:---:|:---|:---|
| API 直连 | 2-5 秒 | 纯文本问答，无工具 | 快速闲聊、简单问答 |
| Harness | 10 秒 - 2 分钟 | 操作文件、执行命令、联网搜索 | 复杂任务、写代码、查资料 |

切换方式：
- 消息里带 【直连】 / 【harness】 临时切换（最高优先）
- Web 控制台「会话」页设置每会话默认模式
- 优先级：消息标记 > Web 设置 > 历史偏好 > 默认

🎭 面具系统

每个会话可选一个「面具」，决定 AI 的说话风格和能力：

| 面具 | 风格 | 权限 |
|:---:|:---|:---|
| 🤖 ai助手 | 靠谱、口语化 | 全权限（可操作电脑） |
| 💕 女友 | 亲昵、会撒娇、会关心 | 仅陪聊 |
| 😎 群聊助手 | 幽默、接地气、会接梗 | 群聊限定 |

- 私聊发 mask 查看当前面具，mask 女友 切换
- 每个面具有独立的对话历史、记忆、规则、日程
- Web 控制台可新增/编辑/删除面具

📝 内置命令

用户命令（直接发，不走 AI）

| 命令 | 功能 |
|:---|:---|
| #记住 我喜欢喝奶茶 | 写入长期记忆 |
| #查看记忆 | 查看当前记忆 |
| #清空记忆 / /clear | 清空对话历史 |
| #规则 群里绝不提考试 | 添加高等级规则 |
| #查看规则 / #清空规则 | 管理规则 |
| mask / mask 女友 | 查看/切换面具 |
| list | 查看能力说明（群聊/私聊通用） |

AI 自主指令

AI 回复里可夹带  块，程序自动执行（不显示给对方）：

remember: 对方喜欢喝奶茶
schedule: 周五下午3点 高数考试
weather: 安阳
websearch: 今天金价

🖥️ Web 控制台

启动后访问 http://127.0.0.1:8640
首次登录：在启动日志里复制 [web] 登录 Token：xxx 粘贴进去。

| Tab | 功能 |
|:---:|:---|
| 📊 监控 | 状态卡片 + 实时日志流 |
| 💬 会话 | 监听/主动发言/模式/面具/共享记忆，批量保存 |
| ⚙️ 配置 | settings.yaml 可视化编辑，支持热重载 |
| 🎭 人设 | 面具卡片增删改 |
| 📜 规则 | 规则列表增删改 |
| 🔒 安全 | 群聊禁用工具开关 |
| ⏰ 提醒 | 日程提醒增删改 |

📁 目录结构

wechat-agent/
├── src/wechat_agent/
│   ├── main.py              # 组合根：装配 + 启动
│   ├── domain/              # 纯领域逻辑（零 I/O）
│   ├── ports/               # 接口定义（Protocol）
│   ├── infra/               # 基础设施实现
│   │   ├── llm/             # API 直连 + Harness + 路由
│   │   ├── wechat/          # 微信数据库 + GUI + 监听
│   │   ├── store/           # 文件存储
│   │   ├── webui.py         # Web 控制台后端
│   │   └── webui.html       # Web 控制台前端（可热改）
│   └── app/                 # 应用层
│       ├── pipeline/        # 私聊/群聊流水线
│       ├── service/         # 对话/提醒/总结/主动发言
│       ├── commands/        # 命令系统
│       └── prompts.py       # 提示词构建
├── config/                  # YAML 配置文件
├── group-skills/            # 群聊技能（SKILL.md）
├── tools/                   # 天气等工具脚本
├── tests/                   # 测试用例（47 个）
├── build.py                 # PyInstaller 打包脚本
└── pyproject.toml

⚙️ 配置说明

所有配置在 config/ 目录下，YAML 格式，支持 ${ENV:默认值} 环境变量插值：

| 文件 | 用途 |
|:---|:---|
| settings.yaml | 微信目标、LLM 通道、行为参数、Web 控制台 |
| personas.yaml | 面具定义（人设/开场白/别名） |
| rules.yaml | 默认规则 + 联网搜索指导 |
| group-policy.yaml | 群聊安全策略（禁用工具清单） |

LLM 配置示例

小米 MiMo
llm:
api_url: https://api.xiaomimimo.com/v1/chat/completions
api_model: mimo-v2.5-pro
api_key_field: XIAOMI_API_KEY

DeepSeek 官方
llm:
api_url: https://api.deepseek.com/v1/chat/completions
api_model: deepseek-chat
api_key_field: DEEPSEEK_API_KEY

OpenCode 中转
llm:
api_url: https://opencode.ai/zen/go/v1/chat/completions
api_model: deepseek-v4-flash
api_key_field: OPENCODE_GO_API_KEY

API Key 存在 ~/.dsh/.credentials.yaml：
XIAOMI_API_KEY: sk-你的key
DEEPSEEK_API_KEY: sk-你的key

🧪 测试

运行全部测试（47 个用例，约 0.7 秒）
python -m pytest -q

运行指定测试文件
python -m pytest tests/test_timeparse.py -v

覆盖：时间解析、指令协议、日程到期、提示词预算、配置补丁、共享记忆路由、会话管理、完整流水线集成测试。

🏗️ 技术架构

┌─────────────────────────────────────────┐
│  main.py  （组合根）                      │
├─────────────────────────────────────────┤
│  app/     应用层：流水线 / 服务 / 命令     │
├─────────────────────────────────────────┤
│  domain/  领域层：纯数据 + 纯函数          │
├─────────────────────────────────────────┤
│  ports/   接口层：Protocol 定义           │
├─────────────────────────────────────────┤
│  infra/   基础设施：所有 I/O 实现          │
└─────────────────────────────────────────┘

- 依赖方向：main → app → ports（接口）← infra（实现）
- 领域层零依赖：不依赖任何 I/O / 微信 / LLM 实现
- 存储：文件系统（md 可手改 + json/jsonl 版本化 + 原子写）
- 并发：per-chat RLock + 串行发送队列 + 后台 worker 线程
- 前端：零框架 SPA，单文件 webui.html，可热更新

📦 打包发布

使用 PyInstaller 打包成 exe
python build.py

输出到 dist-app/：
dist-app/
├── wechat-agent.exe      # 双击运行
├── config/               # 模板配置（用户改这里）
├── group-skills/         # 技能文件
├── tools/                # 工具脚本
└── 使用说明.txt           # 快速上手指南

把 dist-app 整个文件夹压缩发给别人就能用。

⚠️ 已知限制

- 个人微信自动化有封号风险，务必用小号
- 长消息若微信未建搜索索引（FTS），可能只还原截断预览
- 群聊默认走 API（快、无工具）；需 harness 请带 【harness】
- Windows 平台（依赖 wechatauto + UIA 驱动）

📄 License

MIT

如果这个项目对你有帮助，给个 ⭐ 吧！