docs: 拆分用户与开发者文档

原因：原 README 同时承载产品介绍和开发维护说明，读者边界混乱。

影响：README 收敛为普通用户入口，新建 docs/developer-guide.md 承接环境、启动、测试、构建和文档导航。

风险：无运行时行为变化，无需额外回归。

Author: Loveyless

README.md

@@ -4,146 +4,44 @@
 
 # WeChat Auto Shell
 
-一个面向 Windows 的微信预览监听桌面壳：低打扰看左侧会话变化，把新消息整理到本地界面里，按需接翻译和 TTS。
+一个面向 Windows 的微信预览监听桌面壳。它做的事很单一：盯住微信左侧会话列表，把最新预览整理到独立界面里，并按需接翻译和朗读。
 
-它不是聊天机器人，不做主动发消息，不做自动回复，也不尝试读取完整聊天记录。它适合的是“看见左侧会话变化，快速浏览、翻译、朗读”的场景。
+它不是聊天机器人，也不是“完整聊天记录抓取器”。它不发消息、不自动回复、不写输入框，也不读取右侧聊天区全文。
 
-## 适合谁
+## 它适合谁
 
-- 想低打扰跟踪微信群/私聊的最新预览内容
-- 想把微信里的英文/中英文消息顺手翻成可读文本
-- 想在 Windows 上用本地桌面壳查看状态、日志和消息流
-- 想要一个不改微信客户端的监听方案
+- 想低打扰跟踪微信群或私聊最新动静的人
+- 想把英文或中英混合消息顺手翻译成可读文本的人
+- 想在 Windows 上单独看状态、消息预览和日志的人
+- 想要一个不改微信客户端的监听方案的人
 
-## 核心能力
+## 你会得到什么
 
 - 监听微信左侧可见会话预览，自动提取最新变化
-- 桌面壳展示会话列表、消息卡片、运行状态和健康信息
-- 支持翻译 provider：`deeplx`、`openai_compatible`、`passthrough`
-- 支持 TTS：`windows_system`、`doubao`、`tencent_cloud`
-- 支持单实例桌面壳，第二次启动只聚焦已有窗口
-- 运行时配置、日志和锁都落在 `%LOCALAPPDATA%\com.wechatauto.shell`
+- 在本地桌面壳里查看会话列表、消息卡片、运行状态和健康信息
+- 按需接入翻译服务，把外语消息转换成更容易读的文本
+- 按需接入朗读能力，让消息可以直接播出来
+- 单实例桌面壳，重复启动只聚焦已有窗口
 
 ## 你需要先接受的限制
 
 - 当前抓的是左侧会话预览，不是右侧聊天区全文
 - 长消息会被微信预览截断，后半段拿不回来
 - 当前只覆盖左侧可见会话，看不见的会话本轮抓不到
-- 这套方案适合低干扰浏览和翻译，不适合完整审计或归档
+- 这套方案适合低干扰浏览、翻译、朗读，不适合完整审计或归档
 - 不提供发送消息、发送文件、自动回复、写输入框等主动操作
 
-## 安装与启动
+## 普通用户怎么理解它
 
-先装 Python 依赖：
+- 如果你拿到的是安装包或现成的桌面应用，直接运行即可
+- 仓库跟踪的默认配置以“首启可进入设置页”为目标，不把翻译或云 TTS 密钥当成硬依赖
+- 只有当你主动启用额外翻译服务或云端朗读服务时，才需要额外补 URL 或凭据
+- 运行时配置、日志和锁文件会落到 `%LOCALAPPDATA%\com.wechatauto.shell`
 
-```bash
-pip install -r requirements.txt
-```
+## 文档分流
 
-再装前端依赖：
-
-```bash
-cd desktop-shell
-npm install
-```
-
-### 源码态启动
-
-开一个终端启动后端：
-
-```bash
-python listener_app/backend_main.py --config ".\config\listener.json"
-```
-
-再开一个终端启动前端开发页：
-
-```bash
-cd desktop-shell
-npm run dev
-```
-
-- HTTP 默认地址：`http://127.0.0.1:8765`
-- WebSocket 默认地址：`ws://127.0.0.1:8766/events`
-
-### Tauri 桌面壳
-
-如果本机已经装好 Rust toolchain：
-
-```bash
-cd desktop-shell
-npm run tauri dev
-```
-
-`npm run tauri dev` 会先构建 PyInstaller sidecar，再由 Tauri 壳托管 backend。
-
-### 打包
-
-```bash
-cd desktop-shell
-npm run tauri build
-```
-
-这一步会产出 Windows 桌面壳、backend sidecar 和 worker sidecar。首次启动时，如果没有 `.env.local`，默认也应该能先进入壳和设置页。
-
-## 默认配置
-
-仓库跟踪的默认配置是“首启可用”的，不把密钥当成硬依赖：
-
-- `translate.enabled=false`
-- `tts.provider=windows_system`
-
-如果你要接 DeepLX、OpenAI-compatible 翻译，或者启用豆包 / 腾讯云 TTS，再补对应 URL 和凭据即可。
-
-## 发布产物
-
-`npm run tauri build` 当前会产出：
-
-- `wechat-auto-shell.exe`
-- `wechat-auto-backend.exe`
-- `group_listener_worker.exe`
-- `msi`
-- `nsis setup.exe`
-
-第二次启动 `wechat-auto-shell.exe` 时，只会聚焦已有窗口，不会再拉第二份壳或 backend。
-Windows 打包图标现在统一来自 `desktop-shell/src-tauri/icons/icon.svg` 和它生成的 `icon.ico`；别再拿空壳默认图标糊弄发布产物。
-
-## 开发与构建
-
-如果你在本地做回归，最少跑这几步：
-
-```bash
-cd desktop-shell
-npm test
-npm run build
-npm run test:rust
-```
-
-更完整的交付闸口是：
-
-```bash
-python scripts/build_desktop_shell_sidecars.py --python python
-cd desktop-shell
-npm test
-npm run build
-npm run test:rust
-python scripts/smoke_desktop_shell_release.py
-```
-
-## 配置与排障
-
-- 配置说明：`config/listener.md`
-- 桌面壳测试与构建：`docs/desktop-shell-build.md`
-- 监听、健康契约和打包坑位：`docs/wechat-listening-pitfalls.md`
-
-## 项目结构
-
-```text
-config/
-desktop-shell/
-docs/
-listener_app/
-wechat_auto/
-```
+- 普通用户：看这份 `README.md` 就够了
+- 开发者 / 维护者：看 [docs/developer-guide.md](./docs/developer-guide.md)
 
 ## 协议
 

docs/developer-guide.md

@@ -0,0 +1,103 @@
+# 开发者文档
+
+这份文档只服务开发、调试、回归和打包。普通用户别看这个，噪音太多；产品说明回 `README.md`。
+
+## 适用范围
+
+- 当前正式路径只有 `listener_app/backend_main.py + desktop-shell/`
+- Tk 回退链已经下线，不要再按“双桌面入口并存”理解仓库
+- 当前分支不维护发送消息、发送文件、自动回复、写输入框等主动操作能力
+
+## 先装环境
+
+```bash
+pip install -r requirements.txt
+cd desktop-shell
+npm install
+```
+
+如果你要跑 Tauri 壳，还要保证本机能用 `cargo` / `rustc`。缺 Rust toolchain 时，只能验证源码态后端和 Vite 页面，别把它硬说成桌面壳已通过。
+
+## 启动方式
+
+### 源码态后端 + 前端开发页
+
+```bash
+python listener_app/backend_main.py --config ".\config\listener.json"
+cd desktop-shell
+npm run dev
+```
+
+默认地址：
+
+- HTTP：`http://127.0.0.1:8765`
+- WebSocket：`ws://127.0.0.1:8766/events`
+
+### Tauri 壳调试
+
+```bash
+cd desktop-shell
+npm run tauri dev
+```
+
+这条命令会先跑 `python ..\scripts\build_desktop_shell_sidecars.py`，再由 Tauri 壳托管 backend sidecar。不要手工再起一份 `backend_main.py` 去制造双实例噪音。
+
+## 测试与构建
+
+### 最小回归
+
+```bash
+cd desktop-shell
+npm test
+npm run build
+npm run test:rust
+```
+
+`npm run build` 不能省。`tauri::generate_context!()` 依赖 `desktop-shell/dist`，你不先构建，Rust 测试就会炸。
+
+### Release 壳交付闸口
+
+```bash
+python scripts/build_desktop_shell_sidecars.py --python python
+cd desktop-shell
+npm test
+npm run build
+npm run test:rust
+python scripts/smoke_desktop_shell_release.py
+```
+
+上面这套没跑完，就别把 release 壳当成可交付产物。
+
+### 产物
+
+`npm run tauri build` 当前会产出：
+
+- `desktop-shell/src-tauri/target/release/wechat-auto-shell.exe`
+- `desktop-shell/src-tauri/target/release/wechat-auto-backend.exe`
+- `desktop-shell/src-tauri/target/release/group_listener_worker.exe`
+- `desktop-shell/src-tauri/target/release/bundle/msi/*.msi`
+- `desktop-shell/src-tauri/target/release/bundle/nsis/*-setup.exe`
+
+## 运行时边界
+
+- 源码态 `python listener_app/backend_main.py --config ".\config\listener.json"` 读取仓库里的 `config/listener.json`
+- `npm run tauri dev`、安装包和 `wechat-auto-shell.exe` 读取 `%LOCALAPPDATA%\com.wechatauto.shell\config\listener.json`
+- 这两套配置目录不会自动同步；桌面壳设置页只会改当前 backend 正在使用的那一套
+- `.env.local` 在源码态默认读仓库根目录；Tauri 壳优先读 `%LOCALAPPDATA%\com.wechatauto.shell\.env.local`
+
+## 关键文档入口
+
+- 配置契约与字段说明：[`config/listener.md`](../config/listener.md)
+- 桌面壳测试、构建、产物与发布闸口：[`docs/desktop-shell-build.md`](./desktop-shell-build.md)
+- 监听、健康契约、打包与排障坑位：[`docs/wechat-listening-pitfalls.md`](./wechat-listening-pitfalls.md)
+
+## 目录总览
+
+```text
+config/          运行配置与字段说明
+listener_app/    Python backend、runtime、worker、TTS、translate
+desktop-shell/   React + Vite + Tauri 桌面壳
+scripts/         sidecar 构建与 release smoke
+wechat_auto/     微信窗口与 UIA 读取基础能力
+docs/            深水区文档
+```