✨ 功能一览

🚀 快速开始

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

# 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> 指令 → 发回微信
      ↓
后台：群聊记忆自动总结 / 日程提醒 / 水位断点续读

双通道模式

切换方式：

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

🎭 面具系统

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

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

📝 内置命令

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

AI 自主指令

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

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

🖥️ Web 控制台

启动后访问 http://127.0.0.1:8640

首次登录：在启动日志里复制 [web] 登录 Token：xxx 粘贴进去。

📁 目录结构

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:默认值} 环境变量插值：

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