# 微信AI助手开发文档

本文为当前项目总览文档，记录仓库现状、已实现能力、启动边界与后续维护重点。

## 项目定位

本项目是一个本地桌面端“微信AI助手 / AI微信分身助手”原型，用于在本机选择微信或桌面窗口、标注微信界面区域、实时预览微信窗口、读取聊天内容、生成建议回复，并通过配置控制是否自动点击或发送。

当前形态不是已上线生产系统，而是桌面 RPA + 多模态识别 + UI 概念展示的混合原型：

- 已有实现：微信/桌面窗口选择、截屏、区域标注、标注 JSON 保存/加载、Go sidecar 启停、Go vision stream 实时预览、Go agent dry-run 任务生成、Python 视觉检测与自动化实验脚本。
- UI/概念展示：知识库、skill 市场、员工蒸馏、部分日志与二级详情窗口主要来自 `src/data/mockData.js` 或 `PlaceholderWindow`，尚未接入真实后端、数据库或持久化业务配置。
- Go `agent/REAMD.md` 标注为“golang 智能体”，默认 agent 日志为 “Go RPA agent demo”，因此本文把 agent 链路描述为原型/实验能力。

运行边界：

- 桌面主应用由 Tauri 启动，前端嵌入 React/Vite 页面。
- 视觉与自动化能力依赖本机屏幕/窗口权限、可见微信窗口、`agent/config.toml`、`wechat_vision/best.onnx` 和本地 HTTP 服务 `127.0.0.1:8765`。
- 当前工作站是 Windows；Tauri 标注链路已有 Windows 原生 `EnumWindows` 兜底枚举，并可通过桌面截图裁剪完成窗口标注截图。Go sidecar 已存在 Windows 打包产物 `agent/agent-x86_64-pc-windows-msvc.exe`，但 Python 视觉窗口捕获脚本仍偏 macOS 实现（Quartz、avfoundation、macOS private API 相关配置），Windows 自动化视觉脚本仍需另行适配或验证。

## 技术栈

| 层级 | 技术/依赖 | 现状与证据 |
| --- | --- | --- |
| 前端 | React 19、React DOM 19、Vite 7、Tailwind CSS 3、PostCSS、Autoprefixer、Lucide React、Radix Select | 来自 `package.json` 的 dependencies：`react ^19.0.0`、`react-dom ^19.0.0`、`vite ^7.0.0`、`tailwindcss ^3.4.17`、`postcss ^8.5.0`、`autoprefixer ^10.4.20`、`lucide-react ^1.17.0`、`@radix-ui/react-select ^2.3.0`。 |
| 桌面壳 | Tauri 2.11、Rust 2021、`tauri-plugin-shell`、`tauri-plugin-log`、`screenshots`、`xcap`、`image`、`windows-sys` | 来自 `src-tauri/Cargo.toml`：`edition = "2021"`，`tauri = "2.11.2"`，`tauri-plugin-shell = "2.3.5"`，`tauri-plugin-log = "2"`，`screenshots = "0.8"`，`xcap = "0.6"`，`image = "0.25"`，`windows-sys = "0.61.2"`。 |
| Tauri 配置 | 产品名、窗口、sidecar、asset protocol | 来自 `src-tauri/tauri.conf.json`：`productName = "微信A助手"`，主窗口标题 `微信AI助手`，尺寸 `500x900`，`decorations = false`，`transparent = true`，`externalBin = ["../agent/agent"]`，asset scope 为 `$APPDATA/data/screenshots/**`。 |
| Go agent | Go module `agent`、Go `1.26.1`、`github.com/pelletier/go-toml/v2` | 来自 `agent/go.mod`：`module agent`，`go 1.26.1`，依赖 `github.com/pelletier/go-toml/v2 v2.2.4`。 |
| Python 视觉/自动化 | `numpy`、`Pillow`、`onnxruntime`、`Quartz`、`pyautogui`、`pyperclip`、标准库 HTTP server/threading/subprocess | 来自 `wechat_vision/*.py` imports。仓库未提供 Python 依赖清单；本文只记录现状，不新增 `requirements.txt`。 |
| 模型/视觉 | ONNX 检测模型、FFmpeg/avfoundation 实时流实验 | `wechat_vision/best.onnx` 是检测模型；`ffmpeg_realtime_detect.py` 使用 FFmpeg `avfoundation`；`demos/go-ffmpeg-wechat-stream/README.md` 标注 macOS only。 |
| LLM/服务 | 火山方舟（Volcengine Ark）/豆包兼容 OpenAI API | 来自 `agent/config.example.toml`：默认 `base_url = "https://ark.cn-beijing.volces.com/api/v3"`，模型 `doubao-seed-2-0-lite-260428`。Go agent 和 Python algorithm live 均读取/复用该配置思路。 |

## 代码结构与模块职责

- `src/`：React UI。入口 `src/main.jsx` 渲染 `src/App.jsx`；`App` 根据 hash 在主壳、标注页、二级窗口之间切换；`MainShell` 渲染微信分身、知识库、skill 市场、员工蒸馏四个底部 Tab。
- `src/pages/ClonePage.jsx`：微信分身首页。负责启动/停用 agent 与 vision stream，并通过 `enter_window_select_mode` 进入标注；调用 Tauri 命令 `start_vision_stream`、`start_agent`、`stop_agent`、`stop_vision_stream`、`load_regions`。
- `src/pages/AnnotationPage.jsx`：截屏与全屏标注页。支持矩形区域创建、区域类型/描述编辑、区域保存/加载；保存字段包括 `bbox_image`、`bbox_source`、`bbox_screen`、`scaleFactor`；调用 Tauri 命令 `capture_screen`、`load_regions`、`save_regions`。
- `src/windows/SecondaryWindow.jsx`：二级窗口路由。承载设置、日志及知识库/Skill/员工蒸馏占位窗口。
- `src-tauri/src/lib.rs`：Tauri 命令层。管理 `AgentProcess` 与 `VisionStreamProcess`，启动 sidecar `agent` 和 `agent vision-stream`，提供截屏、窗口/桌面来源枚举、区域 JSON 持久化、弹窗创建。
- `agent/`：Go RPA agent。`main.go` 支持默认 run-once、`vision-stream`、`ax-probe`、`sync-chat`；默认 run-once 读取 `config.toml`、加载 `data/regions/wechat.json` 与 `data/screenshots/WeChat.jpg`、推断缺失区域类型、请求 LLM、保存 latest/history task，最后日志明确“未真实执行鼠标键盘”。`sync-chat` 会基于 `chat_content` 标注区域滚动、截图、调用 LLM 抽取当前页聊天，并保存到 `data/chats/wechat_chat_records.json`。
- `agent/vision_stream.go`：Go 实时预览服务。提供 `go-window-capture` 来源、JPEG 帧、`latest.json` 状态和事件数据；当前前端不再包含独立工作台消费页面。
- `wechat_vision/`：Python 视觉实验/自动化。`app.py` 用本地 `best.onnx` 对 `wechat_vision/test` 图片做离线推理并输出标注图/CSV；`ffmpeg_realtime_detect.py` 用 FFmpeg avfoundation + ONNX 检测输入框；`wechat_window_live.py` 用 Quartz 找微信窗口并捕获/检测/提供 MJPEG；`wechat_algorithm_live.py` 基于标注区域监测聊天变化、可调用 LLM、可自动点击徽标并粘贴/发送回复；shell 脚本负责后台启动/停止。
- `demos/go-ffmpeg-wechat-stream/`：独立 Go FFmpeg 微信窗口流 demo，作为实验/demo 存在，不属于主启动链路。

## 核心流程

### 区域标注流程

1. 主界面点击“开始标注”。
2. `ClonePage.startAnnotation` 调用 `list_capture_sources`，Tauri 返回 display/window 来源列表。
3. 用户选择桌面或应用窗口后，`ClonePage.beginAnnotationWithSource` 调用 `capture_source`。
4. Tauri 将截图保存到 `$APPDATA/data/screenshots/WeChat.jpg`，并把截图路径、尺寸、scale factor、来源信息返回前端。
5. 标注页打开 `/annotate`，用户拖拽绘制区域，编辑区域名称、类型和用途描述。
6. `AnnotationPage.save` 组装 annotation，区域字段包含 `bbox_image`、`bbox_source`、`bbox_screen`、`scaleFactor`。
7. `save_regions` 保存 `$APPDATA/data/regions/wechat.json`；后续 `load_regions` 可回读。

### 引擎启动流程

1. 主界面点击“启动引擎”。
2. `ClonePage.toggleAgent` 先调用 `start_vision_stream`，启动 Go sidecar `agent vision-stream`。
3. 前端再调用 `start_agent`，启动默认 Go run-once agent。
4. 如果 agent 启动失败，前端回滚并调用 `stop_vision_stream`，随后进入错误状态。
5. 两个进程启动成功后，主页面状态切换为运行中并记录启动日志。
6. 用户停用引擎时，依次调用 `stop_agent`、`stop_vision_stream`，主页面状态切换为停止。

### Go agent run-once 流程

1. `agent/main.go` 默认进入 `runOnce()`；子命令 `vision-stream`、`ax-probe`、`sync-chat` 分别走独立流程。
2. `runOnce()` 读取 `agent/config.toml`；缺失时返回“读取 config.toml 失败”。
3. `loadConfig` 应用默认值：`app_data_dir` 默认 `~/Library/Application Support/com.tauri.dev`，regions/screenshot/tasks 路径默认位于 `data/regions/wechat.json`、`data/screenshots/WeChat.jpg`、`data/tasks/latest_task.json`、`data/tasks/history`，聊天同步默认输出 `data/chats/wechat_chat_records.json`。
4. 根据 `app_data_dir` 定位标注文件和截图，读取区域并汇总。
5. 对缺失区域类型做启发式推断；要求至少存在或推断出 `chat_content` 与 `input_box`。
6. 如果 `observe_mode` 需要滚动观察，会按配置滚动聊天区域后再读取截图。
7. 读取 `WeChat.jpg`，构造 prompt，请求豆包兼容多模态模型识别聊天内容并生成任务计划。
8. 解析 LLM 返回的 task JSON，调用 `finalizeTask` 补齐区域、截图、dry-run 等信息。
9. 保存 `latest_task.json` 与 history task 文件。
10. 默认 `dry_run = true`，且 `runOnce()` 结束日志为“Go RPA agent demo 完成，未真实执行鼠标键盘”。

### Python algorithm live 实验流程

1. `wechat_vision/start_wechat_algorithm_live.sh` 后台执行 `./venv/bin/python wechat_algorithm_live.py`。
2. 默认参数包括 `--fps 30`、`--host 127.0.0.1`、`--port 8765`、`--click-on-badge`、`--llm-on-click`、`--llm-on-chat-change`、`--reply-on-chat-change`、`--send-reply`。
3. `wechat_algorithm_live.py` 默认读取 `~/Library/Application Support/com.tauri.dev/data/regions/wechat.json` 与 `agent/config.toml`。
4. 脚本复用 `wechat_window_live.py` 的 `find_wechat_window`、`capture_window_image` 等能力，按标注区域监测聊天内容变化。
5. 触发后可调用 LLM 读取当前聊天、生成 `reply_text`，并通过 `pyautogui`/`pyperclip` 点击、粘贴、按 Enter。
6. 该流程是高风险实验能力：虽然脚本参数里 `--dry-run` 默认值存在，但启动脚本同时传入了点击与发送相关参数；执行前必须确认 dry-run 行为、系统权限、目标微信窗口和发送策略，避免误点或误发。

补充：Go `sync-chat` 子命令会读取相同配置和标注，首次同步时先滚动到聊天顶部，再按 `chat_sync_max_pages` 逐页截图与调用 LLM 抽取聊天消息，去重后写入 `chat_records_path`。

## 已完成进度

### 已完成/已有代码

- Tauri 桌面壳与透明无边框主窗口。
- 主 UI 四个 Tab：微信分身、知识库、skill 市场、员工蒸馏。
- 设置、知识库、skill、员工蒸馏等二级窗口框架。
- 主题切换与跨窗口 localStorage 同步。
- 截屏来源枚举：桌面 display 与可见窗口 window。
- 桌面/窗口截图保存到 Tauri app data。
- 区域标注、区域类型/描述编辑、区域 JSON 保存/加载。
- Go sidecar 启停：`start_agent` / `stop_agent`。
- Go vision stream 启停：`start_vision_stream` / `stop_vision_stream`。
- 引擎工作台实时帧展示、FPS 展示、区域 overlay、聊天读取结果与建议回复展示。
- Go agent dry-run 任务生成链路：读取配置、读取标注与截图、请求 LLM、保存 latest/history task。
- Python ONNX 检测与 MJPEG 预览脚本。
- Python algorithm live 自动化实验脚本。
- Go FFmpeg 微信窗口流 demo。
- Go `sync-chat` 聊天记录同步 demo：滚动 `chat_content` 区域、抽取聊天页、去重保存本地聊天归档。

### 仅 UI/Mock 或未接真实后端

- 知识库列表、skill 市场、员工蒸馏数据来自 `src/data/mockData.js`。
- 日志面板部分使用 mock `logs`。
- 知识库创建/详情、skill 创建、员工详情、蒸馏开始是 `PlaceholderWindow` 占位内容。
- 设置页是表单/开关展示，没有看到持久化配置写入逻辑。
- 前端没有测试文件覆盖关键页面或 Tauri 调用链路。

## 开发与启动说明

### Node/Tauri

`package.json` 提供以下 npm scripts：

```bash
npm run dev      # vite --host 127.0.0.1
npm run tauri    # tauri
npm run build    # vite build
npm run preview  # vite preview --host 127.0.0.1
```

说明：本文档任务不要求安装依赖或运行构建；以上命令仅记录仓库脚本现状。

### Tauri 配置

- 产品名：`微信A助手`。
- 窗口标题：`微信AI助手`。
- 主窗口：`500x900`，最小 `500x900`，透明、无边框、可调整尺寸。
- devUrl：`http://127.0.0.1:5173`。
- beforeDevCommand：`npm run dev`。
- beforeBuildCommand：`npm run build`。
- bundle externalBin：`../agent/agent`。
- asset protocol scope：`$APPDATA/data/screenshots/**`。
- app identifier 当前仍为 `com.tauri.dev`。
- `macOSPrivateApi` 已启用。

### Go agent

1. 复制配置：

```bash
cp agent/config.example.toml agent/config.toml
```

2. 填写火山方舟/豆包 API key：

```toml
[volcengine]
base_url = "https://ark.cn-beijing.volces.com/api/v3"
api_key = "YOUR_ARK_API_KEY"
model = "doubao-seed-2-0-lite-260428"
```

3. 默认 agent 配置重点：

```toml
[agent]
app_data_dir = "~/Library/Application Support/com.tauri.dev"
regions_path = "data/regions/wechat.json"
screenshot_path = "data/screenshots/WeChat.jpg"
task_output_path = "data/tasks/latest_task.json"
task_history_dir = "data/tasks/history"
dry_run = true
observe_mode = "normal"
max_scrolls = 1
scroll_delta_y = 6
chat_records_path = "data/chats/wechat_chat_records.json"
chat_sync_max_pages = 3
chat_sync_top_scrolls = 8
```

4. `runOnce()` 默认读取当前工作目录下的 `config.toml`；如果从 `agent/` 目录外启动，需要注意工作目录和配置文件位置。
5. `config.go` 当前会强制 `config.Agent.DryRun = true`，因此 Go run-once 链路按现状不会真实执行鼠标键盘。

### Python 视觉

- 主要入口：
  - `wechat_vision/app.py`：ONNX 模型离线推理验证，读取 `wechat_vision/test`，输出标注图片与 `coordinates.csv` 到 `wechat_vision/ouptsw`。
  - `wechat_vision/ffmpeg_realtime_detect.py`：FFmpeg avfoundation + ONNX 输入框检测实验。
  - `wechat_vision/wechat_window_live.py`：Quartz 微信窗口捕获、检测、MJPEG/HTTP 预览。
  - `wechat_vision/wechat_algorithm_live.py`：基于标注区域的聊天变化监测、LLM 读取、自动点击/回复实验。
  - `wechat_vision/start_wechat_algorithm_live.sh` / `stop_wechat_algorithm_live.sh`：后台启动/停止 algorithm live。
- 启动脚本默认使用 `./venv/bin/python`，本地需自行准备 venv。
- 本地需自行准备 Python 依赖、FFmpeg/ffplay、屏幕录制权限、辅助功能权限、微信可见窗口。
- 仓库没有 Python 依赖清单；不要把当前 Python 脚本当作跨平台即插即用能力。

## 待完善事项

- Python 没有依赖清单，缺少 `requirements.txt` 或等价环境说明。
- 仓库未发现自动化测试；前端关键页面、Tauri 命令、Go agent、Python 视觉链路均缺少测试覆盖。
- Go `runOnce()` 默认要求 `agent/config.toml` 或当前工作目录下 `config.toml` 存在，否则直接失败。
- Python 视觉脚本偏 macOS Quartz/avfoundation；Tauri 标注截图已补充 Windows 原生窗口枚举/裁剪兜底，但 Windows 上的 Python 自动化视觉流程仍需适配/验证。
- Tauri app identifier 仍为 `com.tauri.dev`，发布前应替换为正式 identifier。
- `agent/REAMD.md` 文件名疑似 `README.md` 拼写错误；本次文档任务不改名。
- 知识库、skill 市场、员工蒸馏需要接入真实数据源、业务 API 或本地持久化后，才能从 UI/概念展示升级为真实功能。
- 设置页配置项需要明确写入目标：Tauri store、文件、数据库或 agent config，目前仅看到表单展示。
- Python algorithm live 的真实点击/发送能力需要增加更明确的安全门禁、dry-run 可视化确认和操作日志。

## 维护建议

- 保持本文档是现状说明，不把 mock UI 写成生产功能。
- 后续若新增真实后端、数据库或自动执行能力，同步更新 `docs/development.md` 的“已完成进度”和“核心流程”。
- 涉及自动点击/发送的改动必须在文档中标注风险、默认行为、开关位置和验证方式。
- Tauri 命令、Go agent 配置、Python 脚本参数发生变化时，同步更新“代码结构与模块职责”和“开发与启动说明”。
- 如果以后引入项目记忆系统，可另建 `.memory/`；本次不创建 `.memory/`，因为本次交付范围固定为 `/docs/development.md`。