---

✨ 功能一览

💬 对话能力 私聊全自动：大号发消息全部 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 回复 → 程序执行 <actions> 指令 → 发回微信
      ↓
后台：群聊记忆自动总结 / 日程提醒 / 水位断点续读

双通道模式

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

切换方式：

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

---

🎭 面具系统

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

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

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

---

📝 内置命令

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

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

AI 自主指令

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

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

---

🖥️ 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

---