From 34844e8e24632e587f8ea2eda917c85ae6d2ebad Mon Sep 17 00:00:00 2001
From: xiaoxiao_unai <xiaoxiao@aiyuntuan.com>
Date: Wed, 16 Sep 2026 13:13:20 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E5=AE=A2=E6=88=B7?=
 =?UTF-8?q?=E8=87=AA=E5=8A=A9=E5=AE=89=E8=A3=85=E6=8A=80=E8=83=BD=20wechat?=
 =?UTF-8?q?auto-replica-install=EF=BC=88SKILL.md=20+=20install.ps1?=
 =?UTF-8?q?=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 skills/wechatauto-replica-install/SKILL.md    | 126 ++++++++++++++++++
 .../scripts/install.ps1                       |  94 +++++++++++++
 2 files changed, 220 insertions(+)
 create mode 100644 skills/wechatauto-replica-install/SKILL.md
 create mode 100644 skills/wechatauto-replica-install/scripts/install.ps1

diff --git a/skills/wechatauto-replica-install/SKILL.md b/skills/wechatauto-replica-install/SKILL.md
new file mode 100644
index 0000000..4ad3b40
--- /dev/null
+++ b/skills/wechatauto-replica-install/SKILL.md
@@ -0,0 +1,126 @@
+---
+name: wechatauto-replica-install
+description: 客户自助安装 wechatauto-replica（微信 4.x Windows 客户端自动化，公司 Gitea 公开仓库）。覆盖：环境检查、git clone、venv、依赖安装、ai_config.json 配置、AI 客服引擎启动、发消息验证、常见坑。触发词：安装微信自动化、微信机器人安装、wechatauto 安装、客户安装微信、微信自动回复部署。
+---
+
+# wechatauto-replica 客户自助安装
+
+让客户在一台全新的 Windows 机器上自己装好微信自动化项目（发消息 + AI 自动回复），不用找我们远程。
+
+## 前置条件（先检查，缺哪个补哪个）
+
+1. Windows 10/11（64 位）
+2. 微信 4.x 桌面版（4.1.12+）已登录、窗口可见（发消息/回复走 GUI）
+3. Python 3.9+（3.12 实测可用）。检查：`python --version`；没有就去 python.org 装，勾选 Add to PATH
+4. git。检查：`git --version`；没有去 git-scm.com 装
+5. 管理员权限跑安装/启动（从 Weixin.exe 内存提 SQLCipher 密钥要管理员）
+
+## 安装步骤（三条路任选）
+
+### 路 A：一键脚本（推荐，Windows PowerShell）
+
+```powershell
+# 管理员 PowerShell 里执行
+irm https://gite.aiyuntuan.com/xiaoxiao_unai/wechatauto-replica/raw/branch/main/install.ps1 | iex
+```
+
+或本地有脚本：`.\install.ps1`。脚本自动完成：clone → venv → pip install -e . → 装 winsdk pypinyin → 生成 ai_config.json 模板 → 自检 import。
+
+### 路 B：手动装（不想跑脚本时）
+
+```bash
+# 1. 拉代码（公开仓库，无需账号密码）
+git clone https://gite.aiyuntuan.com/xiaoxiao_unai/wechatauto-replica.git
+cd wechatauto-replica
+
+# 2. 建虚拟环境
+python -m venv .venv
+# Windows:
+.venv\Scripts\activate
+
+# 3. 装依赖（核心 + 发消息 OCR 路径）
+pip install -e .
+pip install winsdk pypinyin
+
+# 4. 验证
+python -c "from wechatauto import WeChatDB; print('OK')"
+```
+
+### 路 C：pip 直装（只要库，不要项目文件）
+
+```bash
+pip install wechatauto-replica
+pip install winsdk pypinyin
+```
+
+## 配置 AI 客服（ai_config.json）
+
+首次安装后项目根目录会自动生成 ai_config.json 模板（或手动复制 ai_config.example.json → ai_config.json）。必改两项：
+
+1. **llm.api_key**：填客户的 DeepSeek API Key（https://platform.deepseek.com 申请，base_url=https://api.deepseek.com/v1，model=deepseek-chat）
+2. **reply.allowlist / only_prefix**：决定回复范围
+   - 灰度期只回指定好友：`"allowlist": ["wxid_xxx"]`
+   - 全量回所有 wxid 好友：`"only_prefix": ["wxid_"]` 且 allowlist 留空
+   - 注意：自定义微信号好友（非 wxid_ 开头）不会被 only_prefix 命中，想全回就加进 allowlist
+
+其他可选项：
+- `persona.system_prompt`：说话人设（默认已去 AI 味：短句口语、禁客服套话、禁 emoji、不硬推销、没把握的信息回「我确认下」）
+- `knowledge.vault_dir`：知识库目录（放 .md 资料，回复时检索注入；目录不存在则空载）
+
+## 启动 AI 客服引擎
+
+```bash
+.venv\Scripts\python.exe wechat_ai_reply.py
+# 或双击 start_ai_reply.bat（已指向 .venv python）
+```
+
+启动成功标志：日志第一行显示回复范围（所有好友 / 仅以下好友: xxx），随后每收到好友消息自动回复。停止：Ctrl+C（或杀进程）。单实例锁 engine.lock 防止重复启动。
+
+## 发消息验证（不用 AI 引擎也能测）
+
+```python
+from wechatauto import WeChatDB
+from wechatauto.guia import quick_send
+
+db = WeChatDB()          # 自动探测账号与数据目录（微信需已登录）
+me = db.get_self_info()  # 当前账号
+sessions = db.get_sessions(limit=10)
+for s in sessions:
+    print(db.get_nickname(s["username"]), s["unread"])
+
+# 发消息：who 用 username（wxid_xxx 或自定义微信号）
+quick_send("你好", "filehelper", verify=True)
+```
+
+## 读消息 / 监听（开发者用）
+
+```python
+from wechatauto import WeChatDB
+from wechatauto.db import Listener
+
+db = WeChatDB()
+lst = Listener(db, interval=1.0)
+lst.add_listener("filehelper", lambda msg, lst: print("new:", msg["content"]))
+lst.start()
+# ...
+lst.stop()
+```
+
+## 常见坑（客户最容易卡住的）
+
+1. **发消息/回复没反应**：微信没登录、或窗口最小化/锁屏。发消息走 GUI，必须微信窗口可见、桌面未锁屏。
+2. **提示权限不足/找不到 Weixin.exe 内存**：必须管理员权限跑。右键终端「以管理员身份运行」。
+3. **首次解密慢（约 6 秒）**：正常。解密缓存到 %TEMP%\wechatauto_db，之后秒开。
+4. **报 database disk image is malformed**：八成是开了两个引擎进程并发读写缓存。解决：杀光所有 python 里的 wechat_ai_reply 进程 → 删 %TEMP%\wechatauto_db 整个目录 → 删 engine.lock → 重启单实例。
+5. **改了 ai_config.json 不生效**：杀旧引擎进程再重启（旧进程内存里是旧配置）。
+6. **verify=True 报「未确认」**：消息已发出但落库有异步延迟，用 get_messages 读回确认即可，不是真失败。
+7. **OCR 找不到按钮**：微信 4.x 自绘界面，靠 OCR + 像素定位。拿不准就先用 ScreenOCR 扫描聊天面板底部工具栏定位话筒/发送按钮，再点击，别依赖硬编码坐标。
+8. **发语音条**：不是「按住说话」，是三步：点「发语音」按钮 → 微信开始录音 → 点「发送语音」。需要虚拟声卡（VB-Cable）把 TTS 音频桥进微信录音，本机默认已装（录音=CABLE Output，播放=CABLE Input）。
+9. **启动 bat 路径错误**：仓库自带 start_ai_reply.bat 里若写的旧路径（C:\Users\Administrator\...），改成本机实际项目路径，或直接命令行跑 .venv python。
+10. **多账号**：`WeChatDB(account=...)` + `list_accounts()` 支持多微信账号，默认探测当前登录账号。
+
+## 安全提示
+
+- Gitea 仓库是公开只读的，clone 不需要账号；写操作（推代码）才要凭证。
+- ai_config.json 里有客户自己的 API Key，别提交到仓库、别外发截图。
+- 数据库解密密钥只从本机 Weixin.exe 进程内存读取，数据不出本机。
diff --git a/skills/wechatauto-replica-install/scripts/install.ps1 b/skills/wechatauto-replica-install/scripts/install.ps1
new file mode 100644
index 0000000..a51e90c
--- /dev/null
+++ b/skills/wechatauto-replica-install/scripts/install.ps1
@@ -0,0 +1,94 @@
+# wechatauto-replica 一键安装脚本（Windows PowerShell，管理员运行）
+# 用法：irm https://gite.aiyuntuan.com/xiaoxiao_unai/wechatauto-replica/raw/branch/main/install.ps1 | iex
+# 或本地：.\install.ps1
+$ErrorActionPreference = "Stop"
+$RepoUrl = "https://gite.aiyuntuan.com/xiaoxiao_unai/wechatauto-replica.git"
+$InstallDir = "C:\wechatauto-replica"
+
+Write-Host "==== wechatauto-replica 一键安装 ====" -ForegroundColor Cyan
+
+# 1. 检查 git
+if (-not (Get-Command git -ErrorAction SilentlyContinue)) {
+    Write-Host "[错误] 未检测到 git。请先安装 https://git-scm.com/download/win" -ForegroundColor Red
+    exit 1
+}
+# 2. 检查 python
+if (-not (Get-Command python -ErrorAction SilentlyContinue)) {
+    Write-Host "[错误] 未检测到 python。请先安装 Python 3.9+ 并勾选 Add to PATH" -ForegroundColor Red
+    exit 1
+}
+$pyVer = python --version 2>&1
+Write-Host "[1/6] 环境: $pyVer, git 已就绪"
+
+# 3. clone（已存在则跳过）
+if (Test-Path "$InstallDir\.git") {
+    Write-Host "[2/6] 项目已存在: $InstallDir（跳过 clone）" -ForegroundColor Yellow
+} else {
+    Write-Host "[2/6] clone 公开仓库 -> $InstallDir"
+    git clone $RepoUrl $InstallDir
+    if ($LASTEXITCODE -ne 0) { Write-Host "[错误] clone 失败，检查网络（内网需连公司 VPN）" -ForegroundColor Red; exit 1 }
+}
+Set-Location $InstallDir
+
+# 4. venv
+if (-not (Test-Path ".venv\Scripts\python.exe")) {
+    Write-Host "[3/6] 创建虚拟环境 .venv"
+    python -m venv .venv
+} else {
+    Write-Host "[3/6] .venv 已存在（跳过）" -ForegroundColor Yellow
+}
+$Py = ".venv\Scripts\python.exe"
+
+# 5. 依赖
+Write-Host "[4/6] 安装依赖（pip install -e . + winsdk pypinyin）"
+& $Py -m pip install --upgrade pip
+& $Py -m pip install -e .
+& $Py -m pip install winsdk pypinyin
+if ($LASTEXITCODE -ne 0) { Write-Host "[错误] 依赖安装失败" -ForegroundColor Red; exit 1 }
+
+# 6. 生成 ai_config.json 模板（不存在才生成，保留客户已有配置）
+if (-not (Test-Path "ai_config.json")) {
+    Write-Host "[5/6] 生成 ai_config.json 模板（请填入 DeepSeek API Key）"
+    $tmpl = @'
+{
+  "llm": {
+    "api_key": "PASTE_YOUR_DEEPSEEK_API_KEY_HERE",
+    "base_url": "https://api.deepseek.com/v1",
+    "model": "deepseek-chat",
+    "timeout_sec": 60,
+    "max_retry": 2
+  },
+  "persona": {
+    "name": "微信本人",
+    "system_prompt": "你是这个微信账号本人，正在用自己的微信跟好友/客户聊天。用自己平时的口吻说话，像真人发微信，不是客服、不是机器人。短句口语、禁客服套话、禁 emoji、不硬推销；没把握的信息（价格、合同、承诺、资质、发货时间等）一律回「这个我确认下，回头回你」，别瞎编。"
+  },
+  "knowledge": { "vault_dir": "kb", "top_k": 3, "max_chars_per_note": 1500 },
+  "reply": {
+    "enabled": true,
+    "only_prefix": ["wxid_"],
+    "blocklist": ["filehelper"],
+    "cooldown_sec": 5,
+    "history_turns": 10,
+    "history_window_sec": 86400,
+    "fallback_reply": "【自动回复】已收到您的消息，稍后回复您。",
+    "keyword_rules": {},
+    "allowlist": []
+  },
+  "storage": { "conversation_dir": "data/conversations" }
+}
+'@
+    Set-Content -Path "ai_config.json" -Value $tmpl -Encoding UTF8
+} else {
+    Write-Host "[5/6] ai_config.json 已存在（跳过模板）" -ForegroundColor Yellow
+}
+
+# 7. 自检
+Write-Host "[6/6] 自检 import"
+& $Py -c "from wechatauto import WeChatDB; print('OK: wechatauto 安装成功')"
+if ($LASTEXITCODE -ne 0) { Write-Host "[错误] import 自检失败" -ForegroundColor Red; exit 1 }
+
+Write-Host ""
+Write-Host "==== 安装完成 ====" -ForegroundColor Green
+Write-Host "1) 编辑 $InstallDir\ai_config.json，把 llm.api_key 换成自己的 DeepSeek Key"
+Write-Host "2) 启动 AI 客服: cd $InstallDir && .venv\Scripts\python.exe wechat_ai_reply.py"
+Write-Host "3) 测试发消息: 看项目 README.md 的 Quick Start"