企业微信 AI 客服助手 · WeCom AI Reply Copilot

客户在企业微信上找你聊天，AI 自动帮你写好回复草稿，你挑一条发出去——AI 只起草，人来定稿，绝不自动发送。

开源项目。内置一个通用会员制门店的演示，消息接入、话术、客户资料、界面都能替换，适配到各类服务业（美业、医美、教培、家政、门店零售…）。

⚠️ 本项目会处理客户聊天内容和身份信息。不要把接口直接暴露到公网；内置的企业微信 OAuth 登录用于保护员工端接口，上线前请先读 SECURITY.md。

---

它能帮你做什么（大白话）

想象你是店里回消息的人，这套系统帮你：

• 客户消息自动收进来：客户在企业微信发来的话，系统自动接住，不用你一直盯着。
• AI 替你写回复，还一次给三种语气：每条客户消息，AI 生成三版草稿——「暖心唠嗑」「简洁高效」「专业细致」，你挑最顺眼的一条，复制发出去，不用从头打字。
• 发不发，你说了算 ⭐：AI 只写草稿，绝不自动发给客户。发哪条、要不要改，全由你决定——不怕 AI 乱说话得罪人。
• 记得住每个老客户：谁上次啥时候来的、喜欢什么款、办了多少钱的卡，写回复时自动带上，让每句话都像认识很久的熟人。
• 能顺嘴帮你约时间：接上排班后，AI 直接告诉客户「周三下午 X 老师有空」，而不是干巴巴一句「我帮你查一下」。
• 越用越懂你：你对每条草稿点赞 👍 / 点踩 👎 / 改写 ✏️，系统都记下来，慢慢摸清你想要的语气。
• 不接企业微信也能先试玩：自带一个模拟器，填个 AI 的 key 就能在本地体验「客户发消息 → AI 出三版草稿」的完整效果。

适合谁：高客单、靠回头客、回错一句话代价大的服务业（美业 / 医美 / 教培 / 家政 / 高端零售…）——想用 AI 省事，但不放心把话直接交给 AI 发出去的人。

为什么这么设计

企业微信 AI 客服最大的坑是「自动回复翻车」：AI 一旦直接发给客户，编价格、编时间、答非所问，一次就砸招牌。所以本项目的核心是 人在环中（human-in-the-loop）——AI 只做最费时的「起草」，把「发不发、发哪条」这个最关键的判断留给人。

---

功能清单（技术向）

• 企业微信员工 OAuth 登录（签名 HttpOnly 会话 cookie）
• 企业微信会话存档轮询 + RSA / SDK 解密
• 客户档案、到店记录、活跃度分级（SQLite）
• 可选：外部 CRM 客户上下文与排班接口
• 三种语气 AI 草稿：暖心 / 简洁 / 专业
• 员工反馈采集（采纳 / 拒绝 / 改写）
• React 员工侧边栏 + 本地模拟器
• Mock 消息源：无企业微信凭据也能开发

目录结构

backend/   FastAPI、SQLModel、消息接入与 AI 起草
frontend/  React、TypeScript、Vite、Ant Design

快速开始：Mock 模式（无需企业微信）

环境要求：Python 3.12+、uv、Node.js 20+、npm。

git clone <your-repository-url>
cd wecom-ai-reply-copilot

cd backend
cp .env.example .env
# 填入 DEEPSEEK_API_KEY，并生成 AUTH_SESSION_SECRET：
# openssl rand -hex 32
uv sync
uv run python -m scripts.seed_demo
uv run uvicorn app.main:app --reload --port 8766

另开一个终端：

cd frontend
npm ci
npm run dev

打开 http://localhost:5180。Vite 开发模式会显示合成客户选择器。backend/app/seed.py 里的所有姓名、电话、到店记录都是虚构的演示数据。

配置

把 backend/.env.example 复制成 backend/.env，主要项：

变量	用途
DEEPSEEK_API_KEY	默认 LLM 提供方的 API key
AUTH_SESSION_SECRET	员工会话签名用的随机密钥
CORS_ORIGINS	允许的前端来源（逗号分隔）
BUSINESS_NAME / AI_STAFF_NAME	注入给模型的身份（店名 / AI 名字）
MESSAGE_SOURCE	mock 或 wecom
WECOM_CORPID / WECOM_AGENT_ID / WECOM_SECRET	企业微信应用凭据
WECOM_OAUTH_REDIRECT_URI	在企业微信注册的 HTTPS OAuth 回调
CUSTOMER_DATA_SOURCE	sqlite 或 external
EXTERNAL_CUSTOMER_API_URL	可选的 CRM 接口地址
WECOM_FINANCE_*	可选的会话存档凭据与路径

切勿提交 .env、数据库、私钥、客户导出文件，以及企业微信官方的会话存档 SDK。

企业微信 OAuth 登录

1. 新建或选择一个企业微信自建应用。
2. 配置它的可信域名和 OAuth 回调。
3. 设置 WECOM_CORPID、WECOM_AGENT_ID、WECOM_SECRET、WECOM_OAUTH_REDIRECT_URI。
4. 让前端和 /api 走同一个 HTTPS 源，或相应调整反向代理与 CORS。
5. 从企业微信应用里打开 /sidebar。返回 401 时浏览器会跳转到 /api/v1/auth/login。

只有携带内部 UserId 的成功企业微信响应才会拿到员工会话。公开路由仅限 /healthz、OAuth 出入口，以及带签名的企业微信消息回调。

会话存档

存档 SDK 由企业微信官方分发，不包含在本仓库。请把对应库放在 Git 之外并设置 WECOM_FINANCE_SDK_PATH；RSA 私钥同样放在 Git 之外并设置 WECOM_RSA_PRIVATE_KEY_PATH。

使用会话存档可能需要企业微信付费版、企业的明确授权，并遵守适用的隐私法规。存档合约到期后，服务将停止接收新消息。

外部 CRM 对接

当 CUSTOMER_DATA_SOURCE=external 时，后端会请求：

• GET /api/v1/internal/customer-context/{phone}
• GET /api/v1/internal/availability?date=YYYY-MM-DD

外部服务应保持私有或独立鉴权。内置适配器刻意做得很小，方便你替换成自己的 CRM。

验证

cd backend
uv run python -m unittest discover -s tests -v
uv run python -m compileall -q app

cd ../frontend
npm ci
npm run lint
npm run build

上线检查清单

• 使用 HTTPS 和反向代理。
• 每个环境生成独立的 AUTH_SESSION_SECRET。
• 把企业微信应用限制给指定员工。
• 若 API schema 敏感，保持 /docs 关闭或加保护。
• 数据库做备份并加密。
• 为客户消息定义留存与删除策略。
• 发送前先人工审核 AI 草稿——生成内容可能出错。
• 监控存档订阅状态与接入错误。

贡献

见 CONTRIBUTING.md。安全问题请按 SECURITY.md 上报，不要走公开 issue。

许可

Apache License 2.0，见 LICENSE。