安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install pdd-sync-shop
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 pdd-sync-shop。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

拼多多店铺同步是 Openclaw Skills 中的一款工具，用于采集店铺当前的商品目录、近 30 天交易记录和商品变更事件，然后将其存储在本地 SQLite 数据库或企业级 ClickHouse 中。可按需运行或每日运行，以建立有用的店铺活动和趋势历史记录。
它是只读的：该技能从商家后台采集数据，不会修改店铺记录。可从零配置的 SQLite 开始，或配置 ClickHouse，以进行长期分析和多店协作。多店模式会为每个店铺分别保留浏览器登录状态，并按顺序采集各店铺。

应用场景

获取拼多多店铺商品和近期活动的当前快照。
按需或按日程刷新店铺数据，建立用于趋势分析的历史记录。
根据别名、显示名称或 mall ID，采集一个已注册店铺的数据。
按顺序同步所有已注册店铺，生成汇总数据集。
将数据存储在 SQLite 中，采用简单的零部署配置。
在需要企业级存储、多店汇总或团队访问时，将数据发送到 ClickHouse。
根据返回的操作指引和各端点健康状态，处理登录过期或平台错误。

工作原理

连接到已登录拼多多商家后台的 Chrome 或 Edge 会话，或者注册店铺并通过店铺管理器完成登录。
运行采集器，选择单个店铺、指定名称的店铺或注册表中的所有店铺。
该技能通过浏览器的 Chrome DevTools Protocol 连接与商家后台通信，并采集商品目录、近 30 天交易记录和商品变更数据。
默认将采集到的快照存储在 SQLite 中；配置 PDD_CH_URL 后则存储在 ClickHouse 中。
返回一行 JSON 结果，其中包含采集和存储信息；失败时会包含 action 字段，用于指引下一步操作。
跟踪端点健康状态，并在需要时执行重试或冷却策略。在多店模式下，一个店铺失败不会中断其他店铺的采集。

配置指南

Python 3.8 或更高版本。
安装了 Chrome 或 Edge，并拥有已登录的拼多多商家会话和 CDP 访问权限；默认 CDP 端口为 9222。
无需第三方 Python 软件包。标准 Python 构建版本已包含 SQLite 支持。
运行同步
将 {baseDir} 替换为已安装技能的目录。在 Windows 上需要时，可使用 python 或 py 代替 python3。

同步默认的单个店铺

python3 {baseDir}/scripts/run.py --port 9222

根据别名、显示名称或 mall ID 同步已注册店铺

python3 {baseDir}/scripts/run.py --shop "Shop Alias"

同步所有已注册店铺

python3 {baseDir}/scripts/run.py --all
注册店铺以进行多店采集
每个店铺都需要独立的 Chrome 实例、用户数据目录和固定 CDP 端口。店铺管理器会处理登录流程，并在登录后记录店铺。
python3 {baseDir}/scripts/chrome_manager.py list
python3 {baseDir}/scripts/chrome_manager.py add "Shop Alias" --label "Display Name"
python3 {baseDir}/scripts/chrome_manager.py remove "Shop Alias"
请按照已打开浏览器中的登录提示操作。登录期间不要手动关闭或终止浏览器；管理器会在优雅关闭浏览器之前持久化并验证凭据。
选择存储方式
SQLite 是默认选项，无需配置。若要使用 ClickHouse，请将 PDD_CH_URL 设为服务器端点；从 Claw School 获取所需的建表 SQL。设置 PDD_DB_PATH 可自定义 SQLite 文件位置。在受限的代理沙盒中，可将数据库和健康状态文件重定向到可写工作区：
PDD_DB_PATH=./pdd.db PDD_HEALTH_PATH=./health.json python3 {baseDir}/scripts/run.py --all

数据架构

存储和运维文件
数据或元数据 默认位置 用途
SQLite 数据库 ~/.pdd-data/pdd.db 用于存储采集到的店铺快照；可通过 PDD_DB_PATH 覆盖。
店铺注册表 ~/.pdd-data/shops.yaml 已注册店铺的身份和标签，供指定店铺及全部店铺运行使用。首次采集时可补充店铺的 mall_id。
健康状态 ~/.pdd-data/health.json 各端点的失败和冷却状态；可通过 PDD_HEALTH_PATH 覆盖。
中间商品目录数据 技能管理的固定路径 采集暂存数据，后续运行时会覆盖。
ClickHouse 表 已配置的 ClickHouse 服务器 设置 PDD_CH_URL 后用于企业级存储；请使用 Claw School 提供的建表 SQL。
采集的数据涵盖当前商品目录、此前 30 天的交易记录以及商品变更事件。该技能会返回一行 JSON 响应，其中包含 ok、collected、stored 和 usage 等字段；失败时还可能包含 action 和端点健康信息。技能文档没有指定固定的表或列架构，因此请使用提供的 ClickHouse SQL，不要假设特定的表名。

高级特性

多店轮换：
使用独立的 Chrome 配置文件和凭据注册店铺，然后通过 --all 按顺序采集；每个店铺之间暂停八秒。
店铺级故障隔离：
某个店铺的会话失败或过期，不会妨碍处理其余已注册店铺。
按端点熔断：
重复失败会触发冷却，并记录在健康状态中。遇到速率限制信号、登录失败或疑似界面变更时，会停止重试，避免反复调用存在问题的端点。
分类重试：
临时错误可重试一次；平台限流、登录过期和疑似 API 变更不会盲目重试。
可执行的机器可读输出：
JSON 结果会提供状态和后续操作指引，包括何时通知用户、重试或联系支持人员。
注重隐私的变更报告：
疑似界面变更可能触发结构化匿名报告，其中包含技能和端点诊断信息，不包含 cookies、店铺数据或订单。报告按指纹进行速率限制，也可通过
PDD_BUG_REPORT=0
禁用。
企业级存储路径：
配置 ClickHouse 以支持长期趋势分析以及多店或团队工作流，同时保留无需配置的 SQLite 默认选项。
适配沙盒的文件处理：
当代理沙盒阻止写入默认数据目录时，可通过环境变量重定向数据路径。

name: pdd-sync-shop description: Syncs a Pinduoduo merchant shop's live catalog, 30-day trade history and change events into a zero-setup local SQLite store or enterprise ClickHouse, with multi-shop rotation. Use when the user wants to pull or refresh their PDD shop data. 同步拼多多店铺在售商品、30天交易与商品改动记录到本地零部署数据库（或企业 ClickHouse），支持店群多店轮转与登录保活提醒；用户要同步、更新店铺数据时使用。 homepage: https://claw-school.com