# wechat-task

**Repository Path**: china0310/wechat-task

## Basic Information

- **Project Name**: wechat-task
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-22
- **Last Updated**: 2026-07-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 微助手 · wei-assistant

> Windows 本地优先的微信私域 CRM 工作台。读取本机微信的联系人与聊天记录，用大模型做客户意向分析、跟进建议和活动托管，帮私域销售**少漏客户、少写话术、多一次及时承接**。

数据全部保存在本机（`node:sqlite`），聊天记录、密钥、微信数据目录都不会离开你的电脑。AI 只给「建议」，发不发由你决定，遵守平台规则与沟通边界。

---

## ✨ 核心功能

- **多账号智能接入**：一个 Agent 自动检测微信、定位数据目录、逐个试读、连接并首次同步；多个微信号一次接入。数据层同步全部账号，向外发送只走「操作账号」。
- **客户工作台**：联系人 / 会话 / 意向 / 风险 / 跟进 / 活动，沉淀成一屏可看的销售台；谁该跟进、谁有意向、谁有风险，一眼清楚。
- **AI 客户分析**：结合聊天上下文，生成意向评分、成交概率、风险分、下一步动作和参考话术，写回客户档案。
- **AI 助理（ReAct）**：像业务顾问一样对话式查询客户、复盘对话、生成跟进计划；可按你的要求**生成 Excel / Word / Markdown / HTML 文件**并下载。
- **个人知识库（RAG）**：产品、报价、话术切块 + 向量召回 + 重排序检索，回复和分析时自动引用；支持**导入 / 同步 Obsidian vault**。
- **活动托管**：活动发出后不机械群发，而是在客户真实回复后，由 AI 判断并自然承接（人工确认后发送）。
- **风格学习**：从你「发出的消息」学习本人说话风格，注入到建议回复里。
- **增量同步**：后台按设置持续增量同步，展示同步历史、状态与错误。
- **桌面宠物**：贴在微信窗口上的像素宠物，可截图取词、辅助回复。
- **Windows 桌面打包**：一键生成 NSIS 安装包，运行时完全离线、native-dep-free。

---

## 🖼️ 界面预览

**今日工作台** —— 谁跟进、谁有意向、谁有风险，一屏看清

![工作台](docs/screenshots/dashboard.png)

**微信连接** —— 第一步下载登录微信，第二步「智能接入」，助手自动检测并同步

![微信连接](docs/screenshots/wechat-connect.png)

**大模型设置** —— 配置供应商、模型、接口地址与 API Key

![大模型设置](docs/screenshots/llm-settings.png)

---

## 🏗️ 架构

一套 `createApiApp()` 组装的 Express 应用，两种运行方式：**开发**下用 tsx + Vite，**桌面**下由 Electron 启动打包的 `node.exe` 跑同一套 API。应用**从不直接读微信数据库**，而是通过一个按需安装的私有 Python 运行时（`wechat-cli`）取数。

```mermaid
flowchart TB
  subgraph Desktop["桌面端 · Electron"]
    UI["React 单页应用<br/>src/App.tsx"]
    Pet["宠物挂件 + RPA<br/>截图 / 键鼠自动化"]
  end

  subgraph Server["Express API · server/app.ts · createApiApp()"]
    Setup["接入 Agent<br/>setupAgent（多账号）"]
    Sync["同步服务<br/>syncService / scheduler"]
    Analysis["语义分析<br/>semanticAnalysis"]
    Assistant["AI 助理<br/>ReAct + 文件生成"]
    Knowledge["知识库 RAG<br/>召回 + 重排"]
    Style["风格学习<br/>styleProfile"]
    Campaign["活动托管<br/>campaigns"]
  end

  DB[("node:sqlite<br/>crmDatabase")]
  CLI["wechat-cli<br/>私有 Python 运行时"]
  WeChat[["本机微信<br/>db_storage"]]
  LLM["大模型<br/>OpenAI 兼容 / 聚合平台"]
  Embed["向量 + 重排<br/>SiliconFlow bge"]
  Vault["Obsidian vault<br/>.md 文件夹"]

  UI -->|REST / SSE| Server
  Pet -->|截图 / RPA| Server
  Server --> DB
  Setup --> CLI
  Sync --> CLI
  CLI -->|读取| WeChat
  Analysis --> LLM
  Assistant --> LLM
  Style --> LLM
  Knowledge --> Embed
  Knowledge <-->|导入/同步| Vault
```

- **数据层** `server/db/crmDatabase.ts`：`node:sqlite` 同步 API，负责建表 / 迁移 / 全部查询，按 `account_id` 做多账号隔离。
- **微信取数** `server/wechat/wechatCliClient.ts`：串行化调用 `wechat-cli`，按账号 `init --db-dir` 切换（CLI 有状态，需串行）。
- **大模型**：全部走 OpenAI 兼容 chat-completions；设置存在库里（`server/analysis/`、`server/assistantSkills.ts`）。

---

## 🧰 技术栈

| 层 | 技术 |
| --- | --- |
| 前端 | React · Vite · TypeScript · lucide-react |
| 后端 | Express · Node.js 24 · `node:sqlite` |
| AI | Vercel AI SDK · OpenAI 兼容端点 · 向量召回 + 重排（bge） |
| 文件生成 | exceljs · docx（纯 JS，无原生依赖） |
| 桌面端 | Electron · electron-builder（NSIS） |
| 微信取数 | 私有 Python 运行时 `wechat-cli` |
| 测试 | Vitest |

---

## 🚀 快速开始

### 环境要求

- Windows 10 / 11
- Node.js **24**（数据库用 `node:sqlite` 的 `DatabaseSync`）
- 微信电脑版（**WeChat 4.1.8**）已登录，并至少打开过一次聊天窗口

### 安装与开发

```bash
npm install
npm run dev
# 前端 http://127.0.0.1:5173 · 后端 http://127.0.0.1:4173
```

### 上手两步（顺序很重要）

1. **先配大模型**：进入「设置 → 大模型设置」，选供应商、模型，填 API Key，保存。智能接入依赖大模型，先配好它。
2. **再连微信**：进入「设置 → 微信连接」，第一步下载并登录 WeChat 4.1.8，第二步点「智能接入」，剩下的交给助手。

### 常用命令

```bash
npm run build            # tsc --noEmit + vite build（类型检查是主要门禁）
npm test -- --run        # 跑一遍全部测试
npm run build:desktop-server   # esbuild 打包桌面端服务
npm run dist:win         # 生成 Windows NSIS 安装包 → release/
npm run pack:win         # 生成免安装目录
npm run verify:package-privacy # 校验安装包无私有数据
```

---

## 📦 打包

打包完全离线、依赖已固定：需要预下载 Electron 运行时到 `electron/electron-dist/`，脚本会把当前 `node.exe` 一并打进安装包。产物默认：

```text
release/wei-assistant-setup-0.1.0.exe
```

---

## 📁 项目结构

```text
src/                  React 前端（单页，App.tsx 为主）
server/               Express API、数据库、各服务
  ├─ db/              crmDatabase：schema / 迁移 / 查询
  ├─ wechat/          wechat-cli 适配层（按账号切换）
  ├─ setup/           接入 Agent（多账号）与首次向导
  ├─ sync/            四种同步流 + 调度
  ├─ analysis/        大模型客户端与语义分析
  ├─ knowledge/       RAG 检索 + Obsidian 同步
  ├─ documents/       Excel/Word/MD/HTML 生成与导出
  └─ style/           owner 风格画像
electron/             Electron 主进程、preload、RPA / 宠物
desktop/              桌面端服务入口
scripts/              打包与隐私检查脚本
docs/                 设计文档与规格（docs/superpowers/specs/）
```

---

## 🔒 隐私与数据

`data/`、`logs/`、`*.sqlite`、解密后的微信数据、`.env` 与打包产物都在 `.gitignore` 中，**永不入库**。提交前可执行 `npm run verify:package-privacy`。

本地运行数据通常位于：

```text
data/
%LOCALAPPDATA%\WeChatCRM\
```

请勿把本地数据库、微信数据目录、API Key 或任何客户数据提交到仓库或公开分享。

---

## 远程仓库

```text
https://gitee.com/china0310/wechat-task.git
```