---

name: dfc-customer-sync description: > 巨懂车客户自动同步到大风车。后台守护进程每 10 分钟从巨懂车后台抓取新留资客户, 手机号去重后写入大风车客户列表。当用户说"同步巨懂车客户"、"巨懂车留资同步大风车"、 "启动客户同步"时使用。 license: MIT metadata: hermes: tags: [dafengche, sync, jvdc, automation] related_skills: [dfc-customer-steward, dfc-create-customer]

巨懂车客户同步大风车 (dfc-customer-sync)

Overview

后台守护进程,每 10 分钟自动把巨懂车后台的新留资客户同步到大风车客户列表。

• 巨懂车:浏览器自动化抓取(Playwright,持久化登录态)
• 大风车写入操作:APP_KEY 认证(Token),不再需要浏览器
• 跨平台支持:macOS / Windows / Linux

When to Use

应该触发：

• "同步巨懂车客户"
• "巨懂车留资同步大风车"
• "启动客户同步"
• "开始同步"
• "检查同步状态"
• "查看同步日志"

不该触发（路由到别的skill）：

• "帮我梳理一下客户" → dfc-customer-steward（客户管家）
• "新建一个客户" → dfc-create-customer（创建客户）
• "今天团队怎么样" → dfc-team-dashboard（团队看板）

跨平台支持

本技能支持以下操作系统:

系统	应用数据目录
macOS	~/Library/Application Support/大风车 AI 龙虾
Windows	%APPDATA%/大风车 AI 龙虾
Linux	~/.local/share/大风车 AI 龙虾

配置文件中的 <APP_DATA> 占位符会自动替换为对应系统的路径。

环境变量

• APP_KEY(必需)- 大风车认证,读写操作均使用 Token

项目结构

dfc-customer-sync/
├── config/                    # 配置文件
│   ├── config.json           # 运行时配置(自动生成)
│   └── config.example.json   # 配置模板
├── scripts/                   # 核心脚本
│   ├── sync_daemon.py        # 主守护进程
│   ├── auth.py               # 大风车认证模块
│   ├── dfc_client.py         # 大风车 CRM 客户端
│   ├── error_handler.py      # 错误处理(自动匹配 troubleshooting)
│   ├── jvdc_scraper.py       # 巨懂车抓取器
│   ├── list_staff.py         # 销售列表获取(自动/手动配置映射)
│   ├── mapping.py            # 字段映射
│   ├── state.py              # 状态管理
│   └── platform_utils.py     # 跨平台工具
├── references/                # 参考文档
│   ├── troubleshooting.md    # 故障排除指南
│   └── field-mapping.md      # 字段映射明细
├── archive/                   # 归档的调试/测试脚本
├── requirements.txt          # Python 依赖
└── SKILL.md                  # 本文档

安装

PyPI 安装（推荐）

# 国内用户使用清华镜像
pip install -U dfc-customer-sync -i https://pypi.tuna.tsinghua.edu.cn/simple

# 或者使用阿里云镜像
pip install -U dfc-customer-sync -i https://mirrors.aliyun.com/pypi/simple/

# 国外用户直接安装
pip install -U dfc-customer-sync

# 安装 Playwright Chromium
python -m playwright install chromium

安装后使用：

dfc-sync --setup
dfc-sync --check
dfc-sync

首次运行会自动在系统应用数据目录生成默认配置文件。

中国大陆用户

pip install -U dfc-customer-sync -i https://pypi.tuna.tsinghua.edu.cn/simple
dfc-sync --repair-cn
dfc-sync --setup
dfc-sync

--repair-cn 会迁移旧配置、清理旧 zip skill 目录、清理旧 Chromium 缓存、使用 Playwright 国内镜像安装 Chromium，并自动运行一次自检。

当前推荐且唯一维护的分发方式是 PyPI。GitHub Release zip 和安装脚本仅保留给旧版本归档，不建议新用户使用。

首次使用

快速开始

# 1. 安装或升级
pip install -U dfc-customer-sync

# 2. 安装浏览器依赖
python -m playwright install chromium

# 3. 首次登录巨懂车(自动检测 APP_KEY 并打开浏览器登录)
dfc-sync --setup

# 4. 自检并启动守护进程
dfc-sync --check
dfc-sync

环境变量说明

技能会自动从用户环境变量中获取大风车 APP_KEY,无需手动配置:

• 使用 APP_KEY 环境变量

运行 --setup 时会自动检测并验证 APP_KEY 是否有效。

各系统依赖要求

依赖项	macOS	Windows	Linux	说明
Python 3.8+	✅	✅	✅	必需
pip	✅	✅	✅	必需
playwright	✅	✅	✅	浏览器自动化
Chromium	✅	✅	✅	通过 playwright 安装
Xcode Command Line Tools	✅	❌	❌	macOS 专用
Visual C++ Redistributable	❌	✅	❌	Windows 专用

依赖检查

运行 --setup 或 --check 时会自动检测:

1. playwright - 浏览器自动化库
2. Chromium - Playwright 浏览器
3. APP_KEY - 大风车认证(从环境变量自动获取)
4. 浏览器 Profile - 巨懂车登录态

如果检测到缺失的依赖,会提示用户安装命令。

Windows 用户注意:

• 使用 python 而不是 python3
• 首次运行前确保已安装 Visual C++ Redistributable(Playwright 依赖)

macOS 用户注意:

• 脚本已处理 Keychain 弹窗问题(使用 --password-store=basic 参数)

常用命令

python scripts/sync_daemon.py            # 启动守护进程
python scripts/sync_daemon.py --setup    # 登录巨懂车
python scripts/sync_daemon.py --check    # 运行前自检
python scripts/sync_daemon.py --status   # 查看同步状态
python scripts/sync_daemon.py --reset    # 重置同步起点

Windows 用户将 python 替换为 python 或 py。

认证架构(v3.0)

大风车写入操作使用 APP_KEY Token,不再需要浏览器登录态。

• 写操作(新增):APP_KEY → Token → pcbotwall/crm/customerObjectAction/saveCustomer.json

只需配置 APP_KEY 环境变量,Token 自动获取,无需手动登录大风车。

核心模块

dfc_client.py - 统一 CRM 客户端

大风车 CRM 的客户写入客户端:

• DfcClient 类:处理新增客户操作
• build_fields() 函数:将简化数据转换为 CRM 接口需要的完整 fields 数组
• 字段映射:同步流程中实际使用的字段(手机号、姓名、来源、等级、性别、重点客户、销售、意向描述、微信号、门店)

mapping.py - 字段映射

同步流程中实际使用的映射:

• map_source():巨懂车来源渠道 → 大风车 source 中文名
• map_source_code_to_name():大风车 source CRM code → 中文名
• map_grade():巨懂车级别/状态 → 大风车意向等级(H/A/B/C/N)
• map_gender():性别映射
• 枚举字典:SOURCE, GRADE, GENDER, IMPORTANT(中文名 → CRM code)

platform_utils.py - 跨平台工具

处理 macOS / Windows / Linux 差异的工具模块:

• get_os_type():检测操作系统类型
• get_app_data_dir():获取跨平台的应用数据目录
• get_playwright_cache_dir():获取 Playwright 浏览器缓存目录
• find_chrome_binary():自动查找 Chrome/Chromium 可执行文件
• kill_process_on_port():跨平台清理端口占用
• get_default_browser_data_dir():获取默认浏览器数据目录

字段映射

见 references/field-mapping.md。核心:

• 手机号 → customer_field_phone(写入字段；同步去重以巨懂车本地同步状态为准)
• 来源 → customer_field_source(守护进程同步统一写入“懂车帝”)
• 级别 → customer_field_grade(H/A/B/C/N)
• 门店 → APP_KEY 对应门店(自动获取)
• 销售 → 自动匹配完整名称或唯一包含关系（失败时回退 owner_id）

与 dfc-create-customer 技能的关系

本技能的 CRM 操作参考了 dfc-create-customer 技能:

• 使用相同的 API 端点(/pcbotwall/crm/customerObjectAction/saveCustomer.json)
• 使用相同的认证方式(APP_KEY → Token)
• 使用相同的字段构建方式(build_fields 函数)
• 使用相同的枚举字典(中文名 → CRM code)

故障排除

如遇问题,查阅 references/troubleshooting.md

项目文件

核心文档

• SKILL.md - 本文档,技能说明
• references/troubleshooting.md - 故障排除指南(遇到问题必读)
• references/field-mapping.md - 字段映射明细

脚本说明

• scripts/sync_daemon.py - 主守护进程(setup/daemon/check/status/reset)
• scripts/auth.py - 大风车认证模块(APP_KEY → Token)
• scripts/dfc_client.py - 大风车 CRM 客户端(读写操作)
• scripts/error_handler.py - 错误处理(自动匹配 troubleshooting 章节)
• scripts/jvdc_scraper.py - 巨懂车抓取器(浏览器自动化)
• scripts/list_staff.py - 销售列表获取(自动/手动配置映射)
• scripts/mapping.py - 字段映射(枚举字典)
• scripts/state.py - 状态管理(同步进度)
• scripts/platform_utils.py - 跨平台工具(macOS/Windows/Linux)

Must Not Do

• 不同步存量客户(仅新留资)
• 不回写大风车改动到巨懂车
• 巨懂车登录态过期时不静默失败,提示重新 --setup
• APP_KEY 无效时不静默失败,提示检查环境变量

升级说明

v3.6.15（当前）

销售映射修复：

1. 支持跟进人模糊匹配 — 巨懂车“朱元巍”可唯一匹配大风车“天成汽贸朱元巍”，避免错误回退到默认销售

v3.6.14

业务修复：

1. 固定同步客户来源 — 守护进程写入大风车时统一使用“懂车帝”，不再受巨懂车页面来源文本格式影响

v3.6.13

稳定性修复：

1. 修复销售自动映射 — 使用订单接口的 order_field_owner 提取销售 recordId，兼容没有用户列表接口的门店
2. 修复 setup 浏览器空白页 — setup 自动停止旧守护进程、使用动态 CDP 端口并等待浏览器就绪；登录成功后不再跳转空白页

v3.6.12

代码清理：

1. 删除大风车手机号查询接口和相关函数 — 同步过程只依赖巨懂车本地同步状态，不保留远程手机号查重死代码

v3.6.11

同步策略调整：

1. 移除大风车手机号前置查重 — 只按巨懂车本地同步状态避免重复抓取，不再判断大风车已有客户
2. 增加写入失败日志 — 记录失败手机号、留资时间、错误类型和错误消息，方便定位字段/API 问题

v3.6.10

中国大陆修复安装：

1. 新增 dfc-sync --repair-cn — 迁移旧配置、删除旧 zip skill 目录、清理旧 Chromium 缓存、重新安装 Chromium 并自检
2. 修复旧 zip 版本残留问题 — 用户以后统一通过 PyPI 包入口 dfc-sync 运行

v3.6.9

中国大陆分发适配：

1. 新增 dfc-sync --install-cn — 使用 Playwright 国内镜像安装 Chromium 并运行自检
2. 文档新增大陆用户安装路径 — 使用清华 PyPI 镜像 + --install-cn

v3.6.8

PyPI 分发稳定性修复：

1. 修复包入口导入 — dfc-sync / python -m dfc_customer_sync 安装后可直接运行
2. 首次运行自动生成配置 — 默认配置写入系统应用数据目录
3. wheel 内置配置模板 — PyPI 包不再依赖源码目录里的 config/

v3.6.7

代码优化 & 文档完善：

1. 移除 extract_staff_info 包装函数 — sync_daemon.py 直接使用 staff_dict.values() 遍历，删除多余函数
2. SKILL.md 适配龙虾 AI 技能格式 — 新增 When to Use 章节、metadata.hermes 标签
3. 曾使用 about:blank 清理页面 — 该方案已在 v3.6.13 移除，避免 setup 完成后显示空白页

v3.6.6

Bug 修复 & 优化：

1. 尝试改用用户列表 API — 该接口在部分租户不存在，v3.6.13 已恢复订单接口作为兼容方案
2. 修复 run_setup Chrome 进程泄漏 — 使用 try/finally 确保 Chrome 进程在所有路径下都被 terminate
3. 修复 jvdc_scraper.py 调试日志不走 logger — 新增 logger 参数，daemon 模式下日志写入日志文件而非 print
4. 清理 auth.py 死代码 — 删除未被任何模块调用的 api_post() 函数

v3.6.5

Bug 修复：

1. 修复 list_staff.py 无法获取销售列表 — 改用销售列表接口查询员工信息，避免错误使用客户查询接口
2. 增加销售列表获取日志 — 逐页显示获取进度，方便排查问题

v3.6.4

Bug 修复：

1. 修复 auth.api_post() 调用 sys.exit(1) 导致守护进程退出 — 改为 raise Exception()，让 daemon 的 try/except 能正常捕获
2. 修复 mapping.py 缺少 map_source() / map_source_code_to_name() — 新增来源映射函数，补全字段映射链
3. 修复 map_gender("先生") 返回"未知" — 增加中文名透传逻辑
4. 修复来源硬编码"懂车帝" — 改为使用巨懂车实际来源字段，通过 mapping.map_source() 映射
5. 修复 jvdc_scraper.py 的 source_keywords 缺"抖音"等常见来源 — 补全来源关键词，文本回退时能正确提取
6. 修复 follower_mapping 只配了一条"薛"导致其他销售匹配不上 — 改为始终自动拉取全量销售 + config 覆盖
7. 修复幽灵记录每轮循环 — process_leads 水位线推进 1 分钟，消除 >= 幽灵击穿
8. 修复 list_staff.py 调用错误 API 网关 — 改为销售列表专用接口，自动拉取销售功能可正常使用

浏览器弹窗修复：

1. daemon 改为纯 headless 模式 — 移除 CDP 回退路径，守护进程运行时零弹窗
2. Windows 专用 headless=new — Chrome 112+ 新版 headless 反检测更强
3. 平台特定 UA — Windows/Mac/Linux 分别使用对应的 User-Agent
4. 反检测增强 — 新增 hardwareConcurrency 覆盖，降低 headless 被识别概率
5. 清理死代码 — 删除不再使用的 _start_chrome_cdp()、_launch_browser_unlock_keychain() 函数

文档同步：

1. 版本号统一为 3.6.4（__init__.py、SKILL.md、pyproject.toml）
2. 销售字段描述从"留空"更新为"自动匹配巨懂车跟进人"
3. 项目结构补全 list_staff.py
4. field-mapping.md 清理 v3.4.0 已删除的废弃枚举字典描述

测试修复：

1. 修复 FakeRow 缺少 query_selector_all() 导致测试崩溃
2. 修复 test_dfc_client.py mock 用 return_value（应 side_effect raise）
3. 重写 test_sync_daemon.py 的 FakeClient，对齐实际接口

v3.6.3

（内部版本，无变更记录）

v3.6.2

（内部版本，无变更记录）

v3.6.1

Bug 修复：

1. 修复 Windows CDP 模式页面空白 — _start_chrome_cdp() 启动参数缺少 --disable-blink-features=AutomationControlled，导致巨懂车检测到自动化浏览器后返回空白页

v3.6.0

稳定性优化（P0/P1/P2）：

1. P0: 浏览器崩溃自动恢复 — 检测到浏览器崩溃时自动重启，无需手动干预
2. P0: 防止多实例运行 — PID 锁机制，确保只有一个守护进程实例
3. P1: 浏览器健康检查 — 每轮同步前检查浏览器是否存活
4. P1: 登录态过期醒目提示 — 登录态过期时输出醒目的警告信息
5. P2: 日志轮转 — 使用 RotatingFileHandler（5MB × 7 份），避免日志无限增长
6. P2: 错误分类 — 区分可恢复错误（自动重试）和不可恢复错误

Bug 修复：

1. 修复 handle_error() 参数不匹配 — error_handler.handle_error() 没有 context 参数，调用时传入 context=... 会导致 TypeError 并使守护进程退出

v3.5.1

Bug 修复：

1. 修复 Dict 类型注解未导入：sync_daemon.py 添加 from typing import Dict
2. 恢复 error_handler.py：该模块在 v3.4.0 被误删，现已恢复，自动匹配 troubleshooting 给 agent 参考
3. 修复 jvdc_scraper.py 中 Path 未导入：添加 from pathlib import Path
4. 修复 daemon 重复初始化代码：清理重复的 token/account 获取

优化：

1. setup 添加依赖检查：自动检测 playwright 和 chromium 是否安装，给出清晰的安装命令
2. daemon 添加前置检查：启动前检查 APP_KEY、浏览器 profile、验证 token，失败时给出明确提示
3. 配置文件检查：config.json 不存在时提示复制模板

v3.5.0

主要变更：

1. APP_KEY 自动检测：setup 时自动从环境变量获取 APP_KEY（优先 DAFENGCHE_APP_KEY，备选 APP_KEY），不再询问用户
2. Setup 流程优化：先自动验证 APP_KEY 有效性，自检通过后再打开浏览器让用户登录
3. 交互体验改进：更清晰的提示信息，引导用户完成登录操作

v3.4.0

主要变更:

1. 代码精简:删除未使用的模块(dfc_writer.py, setup_wizard.py, install_check.py, fix_keychain.py)
2. 字段映射精简:mapping.py 只保留同步流程中实际使用的映射
3. CRM 客户端精简:dfc_client.py 的 build_fields() 只保留实际使用的字段构造器
4. 抓取器精简:删除未使用的 JudongcheScraper 类
5. 项目结构优化:从 13 个脚本精简到 8 个,删除约 4000 行未使用代码

注:error_handler.py 在 v3.5.1 中已恢复

v3.3.0

主要变更:

1. 智能错误处理:新增 error_handler.py,自动捕获错误并查阅 reference 给 agent 参考
2. 灵活处理机制:reference 仅作为参考,agent 可根据实际情况灵活处理
3. 支持 10+ 种错误类型:登录态、浏览器启动、端口占用、API 认证等

v3.2.1

主要变更:

1. 添加故障排除指南:新增 references/troubleshooting.md,记录 12 个常见问题及解决方案
2. SKILL.md 更新:添加故障排除章节,指引 agent 在用户遇到问题时查阅 reference
3. 一键安装脚本:自动安装技能到 OpenClaw skills 目录

v3.2.0

主要变更:

1. 交互式设置向导:新增 setup_wizard.py,用户只需运行一个命令即可完成所有配置
2. 修复 Profile 加载问题:移除 --no-sandbox 参数,确保 Chromium 正确加载保存的 profile
3. 统一启动参数:setup 和 daemon 使用相同的浏览器启动参数
4. 添加调试日志:显示实际使用的 profile 目录路径

v3.1.1

主要变更:

1. 修复硬编码路径:jvdc_scraper.py 调试路径改为跨平台
2. 修复 os 导入:JudongcheScraper 类方法中正确导入 os
3. 配置文件优化:config.json 使用 <APP_DATA> 占位符
4. 添加 .env.example:提供环境变量配置模板
5. 清理废弃文件:将调试/测试脚本移到 archive/ 目录
6. 添加项目结构说明:文档中说明目录结构

v3.1

主要变更:

1. 跨平台支持:新增 platform_utils.py 模块,支持 macOS / Windows / Linux
2. 配置文件优化:使用 <APP_DATA> 占位符,自动适配不同系统的应用数据目录
3. Chrome 查找优化:自动查找 Playwright 安装的 Chrome,支持多架构(arm64/x64)
4. 进程管理跨平台:端口占用清理支持 Windows(netstat + taskkill)
5. 安装自检:新增 install_check.py 自动检测并安装依赖

v3.0

主要变更:

1. 统一 CRM 客户端:dfc_client.DfcClient 同时处理读写操作
2. 完整枚举字典:与 dfc-create-customer 技能完全对齐
3. 删除过时的 dfc_browser_writer.py(浏览器 Cookie 方式)
4. 简化 dfc_writer.py 为兼容包装

v2.0

主要变更:

1. 移除大风车浏览器登录要求(--dfc-setup 命令已删除)
2. 写操作改用 APP_KEY Token 认证
3. 简化部署流程,只需配置 APP_KEY 环境变量