拼多多客服工作台自动化SDK

⚠️ 重要提示：本项目仅供学习研究使用，请勿用于商业用途或任何违反拼多多服务条款的行为。使用本工具产生的任何后果由使用者自行承担。

📖 项目简介

本项目是一个基于 Python 和 Playwright 的拼多多客服工作台自动化 SDK，提供了完整的 API 接口用于管理多个客服工作台实例。项目支持消息接收、发送、订单查询、会话转移等常用客服功能，并提供了回调机制，方便接入 AI 大模型实现智能自动回复。

✨ 主要功能

• 🔄 多工作台管理：支持创建和管理多个客服工作台实例
• 💬 消息处理：自动接收和发送客服消息
• 📦 订单查询：查询用户订单信息
• 🔀 会话转移：支持将会话转移给其他客服
• 🏷️ 备注标签：更新订单备注和标签
• 💰 退款申请：支持小额打款和退款申请
• 📊 回调机制：提供完善的事件回调系统，便于接入 AI 自动回复
• 🔐 API 认证：支持 API Key 认证机制

🛠️ 技术栈

• Python 3.x
• FastAPI - Web 框架
• Playwright - 浏览器自动化
• SQLite - 数据存储
• Pydantic - 数据验证
• Uvicorn - ASGI 服务器

📋 环境要求

• Python 3.8+
• Windows 10/11（当前版本主要支持 Windows）
• 至少 2GB 可用磁盘空间（用于浏览器缓存）

🚀 快速开始

1. 克隆项目

git clone https://github.com/jiulingyun/pdd-customer-service-sdk.git
cd pdd-customer-service-sdk

2. 安装依赖

pip install -r requirements.txt

3. 配置项目

⚠️ 重要：首次使用必须复制配置文件！

项目不包含 config.yaml 文件，您需要从模板文件创建：

Windows 系统：

copy config.yaml.example config.yaml

Linux/Mac 系统：

cp config.yaml.example config.yaml

然后编辑 config.yaml 文件，配置相关参数：

base:
  open_auth: true  # 是否开启API认证
  valid_api_key: your_api_key_here  # 请修改为您的API密钥

workstation:
  initial_url: https://mms.pinduoduo.com/chat-merchant/index.html
  message_queue_size: 100
  operation_timeout: 30

注意：config.yaml 文件已在 .gitignore 中，不会被提交到仓库，请妥善保管您的配置文件

4. 运行项目

python main.py

首次运行会自动下载 Chromium 浏览器（如果未安装）。

5. 访问 API 文档

启动后访问 http://localhost:8001/docs 查看完整的 API 文档。

📚 API 接口说明

工作台管理

• POST /workstations/create - 创建工作台
• POST /workstations/open - 打开工作台
• GET /workstations/list - 获取工作台列表
• POST /workstations/set_callback_url - 设置回调地址
• POST /workstations/del_callback_url - 删除回调地址

消息操作

• POST /{workstation_id}/send_message - 发送消息
• POST /{workstation_id}/cs_list - 获取客服列表

订单操作

• POST /{workstation_id}/user_order - 获取用户订单
• POST /{workstation_id}/order_pickup_info - 获取订单取货信息
• POST /{workstation_id}/update_note_tag - 更新订单备注标签

其他功能

• POST /{workstation_id}/move_conversation - 转移会话
• POST /{workstation_id}/recommend_goods - 获取推荐商品
• POST /{workstation_id}/send_mall_goods_card - 发送商品卡片
• POST /{workstation_id}/small_transfer_application_apply - 小额打款申请
• POST /{workstation_id}/ask_refund_apply - 申请退款

🔔 回调事件

项目支持以下回调事件类型：

• login_redirect - 登录重定向
• page_navigated - 页面导航
• page_loaded - 页面加载完成
• status_update - 状态更新
• realtime_message - 实时消息
• login_confirm - 登录确认
• new_message - 新消息
• move_conversation - 会话转移
• logout - 登出
• error - 错误事件

📝 使用示例

创建工作台

import httpx

async with httpx.AsyncClient() as client:
    response = await client.post(
        "http://localhost:8001/workstations/create",
        json={
            "name": "测试工作台",
            "workstation_id": "test_001"
        },
        headers={"Authorization": "your_api_key"}
    )
    print(response.json())

发送消息

response = await client.post(
    "http://localhost:8001/test_001/send_message",
    json={
        "uid": "user_id",
        "message": "您好，有什么可以帮您的吗？"
    },
    headers={"Authorization": "your_api_key"}
)

设置回调地址

response = await client.post(
    "http://localhost:8001/workstations/set_callback_url",
    json={
        "url": "http://your-server.com/callback"
    },
    headers={"Authorization": "your_api_key"}
)

📁 项目结构

pdd-customer-service-sdk/
├── browser_manager.py      # 浏览器管理器
├── callback_handler.py      # 回调处理器
├── config_manager.py       # 配置管理器
├── main.py                 # 主程序入口
├── config.yaml.example     # 配置文件模板（首次使用需复制为config.yaml）
├── requirements.txt        # 依赖列表
├── LICENSE                 # 开源协议
├── README.md               # 项目说明文档
├── workstation/            # 工作台模块
│   ├── workstation.py     # 工作台核心逻辑
│   └── workstation_manager.py  # 工作台管理器
├── models/                 # 数据模型
│   ├── api_request_model.py
│   └── models.py
├── service/                # 服务层
│   └── db_service.py       # 数据库服务
└── workstation_cache/      # 浏览器缓存目录（自动生成）

⚙️ 配置说明

启动参数

python main.py [options]

Options:
  --debug                  开启debug模式
  --api_auth=<value>       设置环境变量: PDD_OPEN_API_AUTH
  --api_secret=<value>     设置环境变量: PDD_OPEN_API_SECRET

配置文件

主要配置项位于 config.yaml：

• base.open_auth: 是否开启 API 认证
• base.valid_api_key: API 密钥
• workstation.initial_url: 工作台初始 URL
• workstation.message_queue_size: 消息队列大小
• callback.endpoint: 回调地址列表

⚠️ 注意事项

1. 仅供学习使用：本项目仅供学习研究使用，请勿用于商业用途
2. 服务条款：使用前请确保遵守拼多多相关服务条款
3. 账号安全：请妥善保管您的账号信息，不要泄露给他人
4. API 限制：请注意 API 调用频率，避免触发平台限制
5. 浏览器资源：项目会占用一定的系统资源，请合理使用

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

本项目采用 MIT 许可证，详见 LICENSE 文件。

🙏 致谢

感谢以下开源项目的支持：

• Playwright
• FastAPI
• Pydantic

📮 联系方式

如有问题或建议，请通过以下方式联系：

• 提交 Issue

---

再次提醒：本项目仅供学习研究使用，请勿用于商业用途或任何违反平台服务条款的行为。