wechat_ai/docs/development.md

微信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：

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. 复制配置：

cp agent/config.example.toml agent/config.toml

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

[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 配置重点：

[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。