面向拼多多商家后台的桌面端 AI 客服：自动接管买家消息、调用商品/客服知识库生成回复、命中关键词时自动转人工。 多店铺并行、全本地运行、LLM 供应商可切换。
拼多多商家客服的工作是高重复、强时限的：买家问的都是尺码、发货、退换、优惠券；回复慢了影响店铺分。人力盯盘既费人又漏消息。
CommerceAgent 把这件事拆成三步：监听消息 → 判断该谁处理 → 有依据地回复。所有商品知识与客服话术都落在本地 SQLite，模型只负责表达，不负责编造。
| 模块 | 能力 |
|---|---|
| 自动回复 | 多店铺账号并行挂载 WebSocket，独立线程 + 独立队列，单账号故障不影响其他店铺 |
| AI 回复 | 多轮会话上下文、图片消息理解（多模态）、Token 超限自动摘要压缩、工具调用循环 |
| 知识库 | 商品知识（从商品列表 + 图片由 LLM 抽取）、客服知识（人工维护 / Excel 批量导入导出） |
| 关键词转人工 | 命中"退款""投诉""开发票"等词自动转接人工客服，支持营业时间窗口 |
| LLM 工具 | get_product_knowledge、search_customer_service_knowledge、get_shop_products、send_goods_link、transfer_conversation |
| 账号管理 | Playwright 复用本机 Chrome/Edge 登录，持久化 Profile，免扫码重复登录 |
拼多多 WebSocket
│
▼
PDDChannel ──► 消息队列（每账号有界，天然背压）
│
▼
MessageConsumer（固定 worker 池）
│
├─ KeywordDetectionHandler ──► 命中关键词 → 转人工客服
│
└─ AIReplyHandler ──► CustomerAgent
├─ 组装 Prompt（知识库 + 历史）
├─ LLM 调用 ⇄ 工具执行（最多 N 轮）
└─ ReplySender → 文本 / 图片 / 商品卡片
- Python 3.11+
- Windows（打包与安装器面向 Windows；源码运行跨平台）
- 本机已安装 Chrome 或 Edge（登录拼多多商家后台需要）
- 一个可用的 LLM API（DeepSeek / 火山引擎 / Kimi / 智谱 / 通义 / 任意 OpenAI 兼容端点）
git clone https://github.com/<your-name>/CommerceAgent.git
cd CommerceAgent
uv sync # 或 pip install -e .
python app.py # 启动首次启动会生成 config.json。也可直接打包：
python scripts/build_win_exe.py --clean # 产出 dist/installer/CommerceAgent-Setup-<ver>.exe- 设置 → 填入 LLM 供应商、模型名、API Key、Base URL（保存前会做连通性与能力探测）
- 账号管理 → 添加店铺账号，走浏览器登录流程，登录态会持久化
- 知识库 → 同步商品知识（自动抽取）或 Excel 导入客服话术
- 自动回复 → 选择账号启动，日志页可观察每条消息的处理结果
app.py 入口：配置 → DI 容器 → 数据库 → 日志 → UI
├── config.py Pydantic 校验配置，API Key 加密落盘
├── core/ 依赖注入容器、连接状态管理、服务注册
├── Channel/ 渠道层（当前仅拼多多）：WebSocket、登录、API 封装
├── Message/ 消息抽象、有界队列、消费者池、处理器链
├── bridge/ 渠道无关的传输层：Context / Reply / ReplySender
├── Agent/ AI 核心：会话管理、LLM 客户端、工具执行器、工具集
├── database/ SQLAlchemy 模型与知识检索
├── service/ UI 与数据层之间的薄封装
├── ui/ PyQt6 + Fluent Widgets 界面
├── utils/ 日志、LLM 传输、密钥存储、运行时路径
└── scripts/ PyInstaller spec、Inno Setup、抓包与调试脚本
分层原则：Message 与 Agent 层不 import 任何具体渠道。发送走 bridge.sender，新增渠道只需实现 ReplySender 并注册。
数据表：channels → shops → accounts / product_knowledge / customer_service_knowledge，级联删除。
数据目录：开发态在项目内；打包后落在 %LOCALAPPDATA%\CommerceAgent（可写目录，不污染安装目录）。
python -m unittest discover -v # 测试（15 个用例文件，覆盖消息路由/多模态/配置/打包）
python -m compileall -q Agent Channel Message bridge core database service ui utils
python scripts/capture_pdd_ws.py # 抓取拼多多 WebSocket 原始报文，排查协议问题CI：.github/workflows/build-windows.yml，推 v* tag 自动构建安装包并发布 Release。
- 本项目仅作为商家自有店铺的客服效率工具，不做任何形式的批量营销或账号操作。
- 商品知识由模型抽取后仍建议人工抽检；客服话术请以自己店铺的真实政策为准。
- 请勿把
config.json、temp/*.db、浏览器 Profile 提交到版本库（.gitignore已覆盖）。
MIT