# dsh-wechat-persona 使用说明

本手册面向**使用者**（不是开发者），覆盖安装、首次配置、登录微信、白名单、在线时段、桌面通道前置条件、防封、常见问题、更新与卸载。

> ⚠️ **先读三句话**
> 1. 本插件通过自动化方式操作微信客户端/手机通知，**违反《微信软件许可及服务协议》**，账号可能被限制、封禁，**风险由你自行承担**。
> 2. **只用自己的小号**，别用主号；不要做加好友、群发、导流、刷单、诈骗等用途。
> 3. 插件只处理你配置的**白名单单聊**；支付、转账、红包、验证码、密码等敏感话题会被本地规则拦截并暂停。
> 完整声明见 [README 的「重要声明」](../README.md#dsh-wechat-persona)。版本变化见 [CHANGELOG.md](../CHANGELOG.md)。
>
> 本手册对应版本：**3.0.0-beta.1**（开发者预览，2026-11-01；未打 tag/未发布 npm/未创建正式 Release）。
> beta 默认安全模式会拒绝真实通道发送，真实微信环境未实机验收；请先读 [BETA-QUICKSTART.md](BETA-QUICKSTART.md) 与 [BETA-LIMITATIONS.md](BETA-LIMITATIONS.md)。
> 从 0.2.8 升级请先读 [MIGRATION-v3.md](MIGRATION-v3.md)。

---

## 目录

1. [它是什么、不是什么](#1-它是什么不是什么)
2. [安装前准备](#2-安装前准备)
3. [安装、更新、卸载](#3-安装更新卸载)
4. [打开设置界面](#4-打开设置界面)
5. [10 个标签页怎么用](#5-10-个标签页怎么用)
6. [登录微信（扫码、被踢、分身/双开）](#6-登录微信扫码被踢分身双开)
7. [白名单怎么加](#7-白名单怎么加)
8. [在线时段](#8-在线时段)
9. [四个通道怎么选](#9-四个通道怎么选)
10. [桌面通道前置条件与校准](#10-桌面通道前置条件与校准)
11. [日常操作](#11-日常操作)
12. [防封建议](#12-防封建议)
13. [必须由你手动完成的操作](#13-必须由你手动完成的操作)
14. [数据、隐私与清理](#14-数据隐私与清理)
15. [常见问题 FAQ](#15-常见问题-faq)
16. [版本与更新记录](#16-版本与更新记录)

---

## 1. 它是什么、不是什么

**是**：一个 DSH 插件。它按你设定的人格，在你指定的**白名单单聊**里，用拟人的节奏（随机“正在输入”、偶尔分条、偶尔发表情包）自动回复消息；本地规则先挡掉不该回的（非白名单、时段外、超频、敏感话题），**只有该回的消息才会花 token**。

**不是**：

- ❌ 不是微信官方功能，不是“外挂/协议库”，本质是模拟人操作客户端/手机通知；
- ❌ 不会帮你注册账号、加好友、进群、群发、导流；
- ❌ 不会代你完成微信登录、扫码、验证码、解封等安全操作（必须你本人做，见第 13 节）；
- ❌ 不保证 100% 不被微信风控识别——只尽量把行为做得像人、把频率压到最低。

---

## 2. 安装前准备

| 项目 | 要求 |
| --- | --- |
| DSH 桌面版 | 0.2.1-rc.3 或更新的版本（插件依赖宿主的工具/配置/客户端插件能力） |
| Node.js | 22 及以上（构建与测试用） |
| 微信账号 | **专门注册的小号**，已完成实名/正常使用一段时间更好（新号更敏感） |
| 通道环境 | 任选其一：安卓手机/云手机（`phone-adb`，推荐）／Windows 虚拟机（`windows-vm`）／本机微信 PC（`desktop`，默认关闭，风险最高） |
| 桌面通道额外要求 | Windows 10/11 + 已安装**中文（简体）OCR 语言包** + 屏幕分辨率 ≥ 1366×768（详见第 10 节） |
| Windows PowerShell | 5.1（系统自带；脚本由 `powershell.exe -NoProfile` 调用，不要用 PowerShell 7 替换） |
| 微信 PC 客户端 | 4.x（桌面通道只支持 Windows 版微信；更早版本窗口结构不同，未验证） |

建议先用 `mock` 通道把所有配置跑通（不碰真实微信），再切真实通道。

---

## 3. 安装、更新、卸载

### 3.1 安装（二选一）

**方式 A：链接安装（开发调试推荐）**

1. 在插件目录执行构建：

```powershell
cd <插件目录>            # 例如 C:\Users\<你>\...\dsh-wechat-persona
npm install --ignore-scripts --no-audit --no-fund
npm run build
```

> `--ignore-scripts`：本仓库没有需要执行的安装脚本；受限沙箱里带脚本安装可能失败。

2. 编辑 `C:\Users\<你>\.dsh\profiles\desktop\package.json`：
   - `dependencies` 里加：`"dsh-wechat-persona": "link:C:/Users/<你>/.../dsh-wechat-persona"`
   - `dsh.profile.bundles` 数组里加：`"dsh-wechat-persona"`
3. 重启 DSH 桌面版。加载成功后：设置页左侧出现「微信分身」，Plugins 页出现 `dsh-wechat-persona` 卡片。

**方式 B：plugin_manager 安装（正式环境）**

在 DSH 对话里让助手执行：

```text
plugin_manager action=install_bundle target=C:/Users/<你>/.../dsh-wechat-persona
```

安装结果应为 `applied`；重启 DSH 后生效。

### 3.2 更新

1. 用新版本文件覆盖插件目录（或 `git pull`）；
2. 重新执行 `npm install --ignore-scripts` 与 `npm run build`；
3. 重启 DSH。

> 你通过设置界面修改的配置保存在 profile 的 `cordis.patch.yml` 里，**更新插件不会丢配置**。升级后若看到「配置已迁移」提示（旧字段自动补全新字段），属正常，按提示保存一次即可。

### 3.3 卸载

1. 从 `C:\Users\<你>\.dsh\profiles\desktop\package.json` 的 `dependencies` 与 `dsh.profile.bundles` 中删除 `dsh-wechat-persona`（或用 `plugin_manager` 的移除功能）；
2. 重启 DSH；
3. 可选：删除数据目录（见第 14 节）——**删除前确认不再需要记忆与审计**。

---

## 4. 打开设置界面

两个入口，界面相同：

- **设置页**：左栏 →「微信分身」（`settings.section`）；
- **插件页**：Plugins → `dsh-wechat-persona` 卡片 → 配置页（`plugins.bundle.config`）。

界面顶部会显示当前引擎/通道状态；保存时通过 DSH 的配置编辑器写回 profile 的 `cordis.patch.yml`，**重启不丢**。如果宿主没有开放配置编辑能力，界面会变成**只读**并提示原因（此时只能改 profile 的 yaml 文件）。

> 小技巧：改了任何配置后，先看「概览」页状态是否正常，再用「日志与测试」里的“发送测试消息”验证通道。

---

## 5. 10 个标签页怎么用

### 5.1 概览

- 引擎状态（运行中／已暂停／风控熔断／通道状态）；
- 今日统计：模型调用次数、消耗 token、搜索次数、发送条数、草稿数、跳过数；
- 快捷操作：暂停、恢复、发测试消息。

### 5.2 人格

- 查看**内置人格**：小号（`builtin-small`，默认）、大肥鱼（`builtin-dafeiyu`）、老周（`builtin-senior`）、阿码（`builtin-geek`）；
- 点开可看风格、口癖、示例对话、禁忌话题；
- **切换**当前人格（立即生效，新回复使用新人格）；
- **导入**：支持本插件 v2 人格包 JSON、SillyTavern 角色卡、JSON/链接；
- **导出**：把当前人格导出为 JSON，便于备份/分享；
- **安装/卸载**：从本地或人格广场安装的包可以卸载（内置人格不可删）。

人格包字段（v2）：`id`、`name`、`avatar`、`style`、`catchphrases`、`systemPrompt`、`examples[{user,reply}]`、`taboo`、`stickers`、`author`、`description`、`tags`、`packVersion`。SillyTavern 角色卡里的 `char_name` 等字段会自动映射。

### 5.3 白名单

- 添加联系人：`id`（**最关键**）、`name`、`aliases`（别名）、备注；
- `whitelistOnly: true`（默认）时，只有白名单里的单聊会被回复；
- **为空 = 谁都不回**（安全默认值），装好后第一件事就是加白名单；
- 具体填写规则见第 7 节。

### 5.4 在线时段

- 工作日/周末分别设置起止时间（本地时区，可跨零点）；
- 每周低活跃日（`1`=周一…`7`=周日，`0`=关闭）：当天回复量自动收紧；
- 勾选“时段外暂停”后，时段外**完全不生成**（0 token，只记 skip 日志）。

### 5.5 回复策略

常用项：

| 配置 | 默认 | 建议 |
| --- | --- | --- |
| 单条最大字数 | 60 | 想更像真人打字可 30–60 |
| 采样温度 | 1.1 | 1.0–1.2 更活泼 |
| 思考等级 | 低 | 保持低，省 token |
| 拆条概率 | 0.35 | 拆 2–3 条更像真人 |
| 表情包概率 | 0.25 | 别太高，连刷表情最假 |
| “正在输入”范围 | 0.8–5 秒 | 太短像机器人 |
| 上下文条数 | 10 | 越大越贵 |
| 群聊开关 | 关闭 | 不建议开（风险高） |
| 单聊开关 | 开启 | — |

> 偏好记忆：插件会从对方消息里用 0-token 规则提取称呼/忌口/共同话题等稳定偏好，写入该联系人的记忆并在生成时作为背景；不额外调用模型。清空记忆时会一并清除。

### 5.6 表情包

- 按情绪分目录：`happy` 开心、`playful` 俏皮、`shy` 害羞、`comfort` 安慰、`curious` 好奇、`neutral` 中性；
- **多来源**：插件包内置 + 你上传的 + 当前人格包自带的会合并展示（同名文件按来源区分，不会互相覆盖）；
- 可以上传（png/gif/webp）、删除；
- 可设：是否启用、单条回复最多几个、最近多少次不重复；
- **只用你有权使用的图片**，避免版权/平台风险。

### 5.7 预算与安全

- 每日 token 预算（默认 50000）、草稿模式比例（默认 85%：达到后只生成不发，草稿写入 `drafts.jsonl`）；
- 每日摘要调用上限（摘要也花 token）；
- 安全关键词（转账、红包、收款、付款、验证码、密码、银行卡、借条、欠款、中奖、刷单、博彩、裸聊、加密货币、USDT 等）：命中即暂停并通知；
- 风控熔断开关（默认开）：识别到验证码/异常登录/限制提示 → 1 秒内暂停全部自动化。

### 5.8 日志与测试

- 查看最近审计日志（0-token 跳过原因、token 用量、搜索、发送、草稿）；
- **写一条模拟入站**：不依赖真实通道，验证“收到消息→按规则回复”的链路；
- **发送一条测试消息**：向指定白名单联系人发测试文本（不触发模型）；
- 清空某联系人记忆 / 清空全部记忆 / 清空审计日志（不可恢复，谨慎）。

### 5.9 人格广场

- 浏览远程人格索引（`market.indexUrl`），一键安装；
- 索引地址不可达/未配置时自动回退到**内置人格**，不影响使用；
- 可设“只用内置人格”（`builtinOnly`）。

### 5.10 帮助

- 直接展示本使用说明与更新记录（`GET /help` 读取 `docs/使用说明.md` 与 `CHANGELOG.md`）；
- 常用命令与 FAQ 摘要。

---

## 6. 登录微信（扫码、被踢、分身/双开）

### 6.1 扫码登录（必须你本人操作）

插件**不代登录、不读二维码、不碰你的账号凭据**。你需要：

1. 在微信客户端/手机上打开登录二维码；
2. 用**小号手机微信**扫码并在手机上确认登录；
3. 登录后把微信窗口/手机留在合适状态（见第 9、10 节）；
4. 在设置界面确认通道状态正常（`running`），再开启自动回复。

### 6.2 被踢下线后重新登录

微信会在“手机端主动退出电脑登录”“长时间未使用”“异地/异常登录”“切换设备”时把电脑端踢下线。处理步骤：

1. 插件会检测到异常/无窗口，通道状态变为 `degraded`，自动回复自然停止（不会硬发）；
2. 在电脑端微信点击重新登录 → 手机上确认；
3. 检查设置界面「概览」状态恢复为 `running`；
4. 若收到“异常登录/环境异常/限制登录”提示：**先人工在手机微信处理**（解封/验证），确认账号安全后再恢复插件（设置界面「恢复」或 `wechat_persona_resume`）。

### 6.3 微信分身 / 双开

- **安卓手机**：用系统自带“应用分身/双开”或厂商的双开功能再装一个微信，登录小号；`phone-adb` 通道读通知时按包名/标题匹配，双开微信的包名可能不同（例如 `com.tencent.mm` 之外的副本包名），需要在 `channels.phoneAdb.packageName` 填对应包名，否则读不到通知；
- **Windows 虚拟机**：在小号专用的 Windows VM 里登录微信，用 `windows-vm` 通道，与本机主号完全隔离（推荐给“不想共用设备”的人）；
- **同一台电脑登两个微信**：Windows 微信官方不支持多开；第三方多开工具属于修改客户端，风险高，**不建议**。桌面通道只应有一个可见微信窗口，否则脚本可能找错窗口；
- 无论哪种方式：**一个小号固定一台设备/一个环境**，不要多设备轮换登录同一小号（最容易被风控）。

---

## 7. 白名单怎么加

白名单条目有 4 个字段：

| 字段 | 是否必填 | 说明 |
| --- | --- | --- |
| `id` | ✅ | 匹配键。**不同通道含义不同**，见下 |
| `name` | 建议 | 展示名/昵称（桌面通道也用它定位聊天） |
| `aliases` | 可选 | 别名的其他叫法 |
| `note` | 可选 | 备注，不影响匹配 |

**按通道填 `id`：**

- `phone-adb`：`id` = 手机上微信通知标题里显示的名字（备注名/昵称，**完全一致**），如 `张三`；备注名和昵称不一致时，可把另一个填到 `aliases`；
- `desktop`：`id`/`name` 都要填**微信里能搜索到的备注名或昵称**（脚本用它在搜索框里找聊天，再点开）；建议把备注名改成简单、唯一、OCR 容易识别的名字（避免花体字/表情符号/生僻字）；
- `windows-vm`：与 `phone-adb` 一致，`id` = VM 内微信里该联系人的备注名/昵称；
- `mock`：随便填，入站 JSON 的 `contactId` 与之对应即可。

**操作步骤（设置界面）**：白名单标签页 → 新增 → 填 `id`/`name` → 保存 → 「日志与测试」发一条测试消息确认能发到对的人。

> 注意：插件**不会自动加好友**。要聊的人必须先由你手动加为好友并确认备注名。

---

## 8. 在线时段

- 默认在线：工作日 08:30–23:00，周末沿用（未填时回退工作日）；
- 时段外：不生成、不调用模型（审计里是 `skip`，原因 `offline-hours`）；
- **跨零点**写法：开始 `22:00`、结束 `02:00`，系统按“跨午夜”处理；
- 每周低活跃日：当天回复更少（默认周一），适合模拟“周一很忙”；
- 建议：小号刚上线时把在线时段设短（如 12:00–14:00、19:00–22:00），一两周后再逐步放宽。

---

## 9. 四个通道怎么选

| 通道 | 适合谁 | 与电脑解耦 | 抢键鼠/前台 | 风险 |
| --- | --- | --- | --- | --- |
| `mock` | 第一次安装、验收配置 | — | 否 | 无（不碰微信） |
| `phone-adb` **推荐** | 有备用安卓机/云手机 | ✅ 手机独立 | 否 | 中：需开 USB 调试、ADBKeyboard 输入法 |
| `windows-vm` | 有虚拟机 | ✅ 独立环境 | 仅 VM 内 | 中高：VM 指纹/网络与日常设备不同，别挂代理 |
| `desktop` | 只有本机、临时用 | ❌ 共用桌面 | ⚠️ 会打断你 | 最高：直接操作你的桌面，**默认关闭** |

切换通道后**务必先发测试消息**验证，再打开自动回复。各通道详细配置与风险见 [CHANNELS.md](CHANNELS.md)。

> **beta 注意**：`3.0.0-beta.1` 默认 `betaSafeMode=true`，真实通道的发送会被拒绝；beta 阶段请先用 `mock` 通道验证，不要把「发送测试消息」当作在真实联系人上验收 beta 的步骤（真实环境验收需单独授权）。

> 桌面通道的 `enabled` 与 `driverEnabled` 是**双开关**：两个都为 `true` 才真正发送；这是防止误开的安全设计。

---

## 10. 桌面通道前置条件与校准

桌面通道用**窗口区域截图 + Windows OCR + 坐标点击/键入**驱动微信 PC（不是读取控件树），因此对环境有额外要求：

### 10.1 前置条件（缺一不可）

1. **Windows 10/11**，微信 PC 已登录**小号**且保持登录；
2. **中文（简体）OCR 语言包**已安装：
   - 设置 → 时间和语言 → 语言和区域 → 添加语言「中文(简体，中国)」→ 语言选项 → 勾选“光学字符识别”；
   - 或 PowerShell（管理员）执行：`Get-WindowsCapability -Online -Name "Language.OCR*" | Add-WindowsCapability -Online`；
   - 验证：`Get-WindowsCapability -Online -Name "Language.OCR*"` 中 `zh-Hans-CN` 状态为 `Installed`；
3. 显示缩放与分辨率：**推荐 100%–150% 缩放、≥1366×768**；脚本会声明 DPI 感知，但过高缩放会让坐标比例漂移；
4. 微信窗口**不要最小化**（脚本会尝试恢复；过于频繁会打扰你），也不要把它拖到屏幕外/多显示器边缘；
5. 电脑**空闲**时使用：脚本检测到你键鼠活动（默认空闲 <5 秒）会放弃本轮操作；已有操作进行中会先让出 30 秒。

### 10.2 启用（两个开关都要开）

在设置界面「概览」把通道选为「本机桌面微信」，或直接改配置：

```yaml
activeChannel: desktop
channels:
  desktop:
    enabled: true              # 通道总开关
    windowTitle: "微信"        # 微信主窗口标题（一般不用改）
    userActivityIdleMs: 5000   # 你空闲 5 秒后才动手
    pauseSeconds: 30           # 检测到你活动就让出 30 秒
    driverEnabled: true        # 允许脚本发送
```

### 10.3 校准（识别不准时）

脚本按**窗口内比例**定位：左侧会话栏占窗口宽度 **62%**（聊天区在右侧 38%）。条件固定一般是准的；若你的微信版本/主题导致定位偏移，可用环境变量微调（在启动 DSH 的环境里设置）：

| 环境变量 | 默认 | 作用 |
| --- | --- | --- |
| `WXUIA_PANE_LEFT_RATIO` | `0.62` | 聊天分栏左边界占窗口宽度比例 |
| `WXUIA_SEND_WAIT_MS` | `900` | 点发送后等待 OCR 校验的毫秒数（500–1200） |
| `WXUIA_IDLE_MS` | `15000` | 脚本自身的键鼠空闲闸门（独立于插件配置） |
| `WXUIA_ACTIVE_HOURS` | 不设=不限 | 如 `22:00-02:00`，仅脚本层限时（在线时段建议交给插件 `schedule`） |
| `WXUIA_DEBUG` | 不设 | 设为 `1` 写调试日志到临时目录，或给一个日志文件路径 |
| `WXUIA_SHOT_DIR` | 不设 | 保存每次截图的目录（排障用，注意含聊天内容） |
| `WXUIA_FORCE` | 不设 | `1` = 忽略“你正在用电脑”的闸门（**仅在你自己盯着的排障时用**） |
| `WXUIA_NOBASELINE` | 不设 | `1` = 不做基线去重，每次读出全部可见消息（仅测试） |
| `WXUIA_CAPTURE` | `auto` | `printwindow`/`screen` 强制截图方式 |
| `WXUIA_STATE_PATH` | 默认数据目录 | 基线状态文件路径 |

排障常用做法：设 `WXUIA_DEBUG=1`，让插件读一次消息，然后看日志里的窗口几何、OCR 行坐标、候选消息，判断是“找不到窗口”“OCR 读不到”还是“分栏比例不对”。

### 10.4 已知限制

- 真实微信的 OCR 识别率受字体、主题、缩放、消息类型影响；**图片/表情包/引用/红包/语音/系统消息**不会作为文本消息回复；
- 桌面通道**不支持发送表情包/图片/语音**：通道声明了能力（`capabilities.stickers=false`），引擎会自动把表情概率降为 0，**不会尝试发送、也不会报错刷屏**；
- 发送后用 OCR 校验气泡；若气泡校验失败，会再看**输入框是否已清空**来判定是否已发出（已清空=成功），**判定失败也绝不重发**，宁可报错也不重复刷屏；
- 读取聊天记录时会做**防串聊校验**：标题栏 OCR 认不准时，用左侧会话列表里该联系人的最新消息预览交叉比对，对不上就拒绝读取（返回 `ok:false`），绝不把别人的聊天当成目标联系人的消息；
- 生僻字/形近字昵称（如「伟/磊」）OCR 可能识别不稳。**小技巧：给该好友设一个 OCR 友好的微信备注名**（如「张伟」「小王」），识别率会明显提升；
- 被最小化/被其他窗口完全遮挡时，可能触发「抢前台」或按安全设计拒发（宁可失败不发错人）；截图默认 PrintWindow 优先，正常使用时不会反复切前台。

> 桌面通道在**历史版本（0.2.x）**曾在真实微信 4.1.x + Windows 11 + Windows OCR 上做过端到端验证（列表识别、发送、读取、防串聊）。
> **`3.0.0-beta.1` 重构后的 OCR/发送未重新完成真实环境验收**，且 beta 默认拒绝真实通道发送；请勿把历史版本的验证当成 beta 的能力承诺。

---

## 11. 日常操作

| 想做什么 | 怎么做 |
| --- | --- |
| 看状态 | 设置界面「概览」，或让助手调用 `wechat_persona_status` |
| 紧急暂停 | 设置界面「暂停」，或助手调用 `wechat_persona_pause`，或白名单联系人发 `/stop` |
| 恢复 | 设置界面「恢复」（风控后**先人工确认账号安全**） |
| 发测试消息 | 「日志与测试」→ 发送测试消息（不触发模型），或助手调用 `wechat_persona_send_test` |
| 改人格 | 「人格」标签切换，或安装新人格包 |
| 清记忆 | 「日志与测试」→ 清空记忆（按联系人或全部） |
| 看为什么没回 | 「日志与测试」看审计 skip 原因：非白名单/时段外/超频/超预算/敏感词/熔断 |
| 看花了多少 token | 「概览」今日统计 + 审计日志 |

---

## 12. 防封建议

**最重要的一条：固定设备 + 固定网络。** 风控最敏感的信号是“同一账号短时间在不同设备/IP/时区登录”。

- ✅ 只用自己注册的**小号**；头像、昵称、简介手动设置成普通人（别写 AI/机器人/测试）；
- ✅ 固定一台手机/VM/电脑，固定同一个 Wi-Fi/出口 IP；**不要挂代理、VPN 换区、频繁切网络**；
- ✅ 新号先“养”7–14 天：先手动正常聊天、看朋友圈、别一上来就自动化；
- ✅ 频率由低到高：先只回 1–2 个白名单好友、每天几十条，稳定后再放宽；
- ✅ 在线时段外完全静默；每周留 1 天低活跃；每人每小时/每天有限频（可再收紧）；
- ✅ 拟人节奏：不秒回（0.8–5 秒随机“正在输入”）、偶尔分条、表情包别连刷；
- ✅ 只被动回复白名单单聊；**不主动加好友、不群发、不进群、不导流、不发链接轰炸**；
- ✅ 出现验证码/异常登录/环境异常/限制提示：**立即停手**（插件会自动熔断并暂停），人工在手机微信处理，**不要自动重试、不要换设备试**；
- ❌ 不要用主号；不要多设备轮流登录同一小号；不要用自动化做营销/诈骗/刷单；
- ❌ 不要为了“更稳”去 root/装 Xposed/改客户端——这类行为风险高得多。

---

## 13. 必须由你手动完成的操作

插件**不会**、也**不应**替你做这些事：

1. **扫码登录**微信（小号手机扫码 + 手机确认）；
2. 处理**验证码、异常登录、限制登录、解封**（必须在手机微信里人工完成）；
3. **加好友、设置备注名/昵称**（白名单匹配依赖你手动设置的备注名）；
4. 安装**中文 OCR 语言包**（桌面通道前置，见第 10 节）；
5. **上传表情包图片**（插件不提供版权素材；样例图仅供演示）；
6. 选择并准备好**通道环境**（备用手机/云手机/VM/微信 PC），开 USB 调试、装 ADBKeyboard、固定网络等；
7. 处理**微信客户端更新**导致的变化（新版本可能改变界面位置/标题，需要重新校准或等插件适配）；
8. 决定是否启用**桌面通道**（默认关闭，需要你明确同意“让自动化操作你的桌面”）。

---

## 14. 数据、隐私与清理

- **数据目录**：默认是 DSH 数据目录下的 `.dsh-wechat-persona/`（本机实测为 `C:\Users\<你>\.dsh\profiles\desktop\.dsh-wechat-persona\`）；可在设置里把 `dataDir` 填成**绝对路径**固定到别处；
- 目录内容：`state.json`（暂停/熔断/预算/限频）、`memory/`（每联系人记忆）、`audit.jsonl`（审计）、`alerts.jsonl`（风控通知）、`drafts.json` / `drafts.jsonl`（草稿队列/历史追加）、`send-ledger.json`（发送幂等账本，仅文本哈希）、`desktop-ack.json`（桌面通道 ack 水位线）、`outbox.jsonl`（mock 回复）、`uia-state.json`（桌面通道基线，在数据目录下）；
- **只写本地**：不把聊天内容上传到除“调用模型/搜索”之外的任何地方；模型/搜索走 DSH 宿主配置的服务；
- **清理**：审计/记忆可用设置界面或工具一键清空；彻底删除数据目录前请确认不再需要（不可恢复）；
- 桌面通道的 `WXUIA_SHOT_DIR` 若开启，会把你微信窗口截图写到该目录——**排障完记得关闭并删除**。

---

## 15. 常见问题 FAQ

**Q1：装好了，但设置页没有「微信分身」？**
A：确认 bundle 已安装并重启 DSH；检查 `node_modules` 已存在（链接安装时缺依赖会静默加载失败）；看 DSH 日志里的插件加载错误。若只有「插件配置」里出现，也正常——两个入口可能只显示其一（取决于宿主版本）。

**Q2：插件在跑，但消息不回？**
A：按顺序查：① 是否暂停/熔断（概览）；② 是否在在线时段；③ 白名单 `id` 是否与通知标题/微信备注名完全一致；④ 是否超频/超预算；⑤ 审计里 skip 的 `reason` 是什么；⑥ 通道状态是否 `degraded`。

**Q3：一直显示 mock 通道？**
A：`mock` 是默认安全通道，不会碰真实微信。要上线必须显式把 `activeChannel` 改成 `phone-adb`/`windows-vm`/`desktop`，并填白名单。

**Q4：桌面通道报“无法读取聊天窗口 / 无法确认已打开与「XX」的聊天”？**
A：常见原因：微信没登录/窗口被最小化；白名单 `id`/`name` 不是微信里可搜索的备注名；搜索框/分栏位置与预期不同（设 `WXUIA_DEBUG=1` 看日志，必要时调 `WXUIA_PANE_LEFT_RATIO`）；OCR 语言包缺失（会明确提示安装中文 OCR）。

**Q5：桌面通道报“气泡未确认且输入框未清空”？**
A：这表示脚本回车后既没看到新气泡、输入框里也还留着文字，判定为**可能没发出去**并已停止（**绝不自动重发**，避免重复刷屏）。先人工看微信里有没有这条消息；反复出现就开 `WXUIA_DEBUG=1` 用 `WXUIA_SHOT_DIR` 留截图排查（常见原因：输入框没点中、窗口被遮挡、OCR 认不出气泡）。

**Q6：OCR 读出来的字缺字/错字（如“消息”变“氵肖息”）？**
A：Windows OCR 在特定字体/缩放下会误识。影响：去重可能失效、校验可能失败。解决：调大微信字体/缩放、避免极小字号主题；或换 `phone-adb` 通道（基于通知文本，不含 OCR）。

**Q7：电脑休眠/唤醒后不工作了？**
A：唤醒后微信可能被踢或窗口变化，通道会进入 `degraded`。重新登录微信、确认窗口打开后，插件会自动恢复轮询；必要时「恢复」一次。

**Q8：token 花得比预期多？**
A：看「预算与安全」与审计：上下文条数、人格提示词长度、是否频繁触发搜索/摘要。可降 `memory.contextMessages`、`reply.maxTokens`、`reasoningEffort=low`、`search.maxPerDay`，并把预算/草稿比例调低。

**Q9：改了配置重启后又变回去了？**
A：设置界面保存需要宿主提供配置编辑能力；如果界面显示只读，请手动改 profile 的 `cordis.patch.yml`。另外确认改的是当前 profile（桌面版默认 `desktop`）。

**Q10：为什么有“草稿模式”？**
A：预算达到 `draftModeRatio`（默认 85%）后，插件只生成不发送，草稿写 `drafts.jsonl`，避免超支和刷屏；降低生成量或提高预算即可恢复发送。

**Q11：群聊会回吗？**
A：默认不回（`reply.groupChatEnabled=false`），群聊在通道层和规则层双重拦截。不建议开启。

**Q12：能发图片/文件吗？**
A：目前只支持**文本**和**表情包**（桌面通道连表情包都不支持）。图片/文件/语音不支持。

**Q13：会读我其他聊天记录吗？**
A：不会。只处理白名单单聊；非白名单消息在通道层就被丢弃，不写记忆、不进上下文。

**Q14：某个好友名字 OCR 总认不准（生僻字/形近字），会漏回吗？**
A：会受一点影响。插件对名字做了「整栏 OCR → 名字条二次 OCR → 列表预览交叉验证」三层兜底；仍认不准时，**建议给该好友设一个简单微信备注名**（如「张伟」「小王」），并确保白名单 `id`/`name` 与备注名一致，识别率会明显提升。

**Q15：日志里出现「无法确认当前聊天……已跳过读取」，是 bug 吗？**
A：这是**防串聊保护**，不是 bug：标题栏 OCR 和左侧列表预览两路都没能确认当前打开的确实是目标联系人的聊天时，插件会拒绝读取，避免把 A 的聊天当成 B 的消息（错读比不读严重）。处理：手动打开该聊天确认正常、或给好友改个 OCR 友好的备注名，再让它重试。

**Q14：提示“异常登录/环境异常”怎么办？**
A：插件会立即暂停（熔断）。**不要**用插件重试；在手机微信里人工处理（验证/解封），确认账号安全后再手动恢复。

**Q15：怎么确认它真的在回消息而不是 mock？**
A：beta 默认拒绝真实通道发送，请先在 `mock` 通道看 `<dataDir>/outbox.jsonl` 与审计 `sends` 是否增加；真实通道是否回复需维护者授权后另行实机验收，不要自行用真实联系人验证 beta。

---

## 16. 版本与更新记录

- 当前版本：**3.0.0-beta.1**（开发者预览，2026-11-01；**真实微信读取/OCR/自动发送未实机验收**，beta 默认拒绝真实通道发送；安装与 mock 体验见 [BETA-QUICKSTART.md](BETA-QUICKSTART.md)）——OCR 流水线重构（同帧截图、WinRT 2x 首读 + 可选 RapidOCR 同帧融合、气泡左右归属 uncertain 拒投、基线 pending/ack 水位线不丢消息、原子写）；发送可靠性（暂停可打断在飞生成/发送、`SendResult.delivery` 三态 `sent/not-sent/unknown`、unknown 不重试、无行坐标一律拒发、暂停期间入站消息 deferred 持久化后补处理、`/test/send` 统一走门禁）；API 鉴权加固（可选 Bearer token + 回环/Host/Origin/Sec-Fetch-Site 校验 + 限速 + 请求体限制 + 人格导入安全）；安全运行模式 `safeMode`、只读 OCR 诊断、首次配置向导、人格模拟器（仅 mock）。升级前请读 [MIGRATION-v3.md](MIGRATION-v3.md)，发布门槛见 [RELEASE-CHECKLIST.md](RELEASE-CHECKLIST.md)。
- （上一版）0.2.8（2026-10-31）——读取端新增「双引擎 OCR 投票」（系统 OCR 之外再用 RapidOCR 独立识别同一截图，两路按坐标+文字重合度投票）与「常用词字典纠错」（大吧鱼→大肥鱼、幽黑度→幽默度），英文/形近字误读概率进一步降低；0.2.3——读取聊天记录时用「列表预览交叉验证」防止读错人、表情能力降级（桌面通道不再尝试发表情）；0.2.2 提示词新增「像真人聊天」规则；0.2.1 桌面通道稳定性与可发布质量收尾：会话列表识别（4x 最近邻 + 绿底行锚点 + 名字条二次 OCR）、发送判定（气泡失败时用输入框清空兜底，绝不重发）、不抢前台（PrintWindow 优先）、宽松标题匹配、自问自答过滤、`selfcheck.ps1` 一键自检、文档/许可证补齐。
- 0.2.0（2026-10-30）——设置界面、人格库/人格广场、Host API、配置持久化、联系人偏好记忆与多来源表情包；桌面通道脚本重写并修复 read 空数组/发送假成功。
- 0.1.0（2026-10-30）——首个可用版本（MVP）。
- 完整变更见项目根 [CHANGELOG.md](../CHANGELOG.md)；设置界面「帮助」标签与 `GET /help` 也会直接展示本说明与更新记录。
- 验收方法见 [ACCEPTANCE.md](ACCEPTANCE.md)；通道细节与风险见 [CHANNELS.md](CHANNELS.md)。