pounding-ozon-probe — 工具手册
0. 定位 Skill 目录
所有命令在 skill 根目录(含 scripts/cli.py 的目录)下执行。确定方式按优先级:
$SKILL_DIR → 当前目录含 scripts/cli.py → 向上级目录查找。Python ≥ 3.12。
1. 意图路由
先判断用户意图,再选管线。每次操作前重新判断,不因上下文而惯性选择。
完整意图路由决策树见
references/command-reference.md(各管线触发条件 + 输入输出)。 要点速记:① 有 URL 先判类型(1688商品页→A / Ozon商品页→B / 搜索类目页→C / 批量→F); ② 无 URL 按意图词:趋势→E(先 web_search)、跟卖→C、裂变→C--fission、上架→D、蓝海→C; ③ 说"自动采集/无人值守跑一批"→ C2 discover-task(干跑缺省,--to-box入采集箱); ④ 指代不清 / 数量不符 / 重上 → 必须追问核对,禁止猜测。
关键规则
① 有 URL 先判类型:搜索页/类目页走 C(discover --url),绝不去 B 跟卖单商品 ② 无 URL 按意图词: 趋势→E(先 web_search)、跟卖/蓝海→C、裂变→C
--fission、上架→D ③ 趋势选品命令层无 trend, agent 先 web_search + LLM 提炼再 discover(references/trend-selection.md)④ 裂变硬预算默认不无限跑 (references/discover-fission.md)⑤ 管线 B 禁止复制时降级 A(直采重建,offer_id/定价会变,须说明) ⑥ 复合意图(趋势+上架)→ 追问「趋势出款还是按词直接上(D)?」 ⑦ 「选 N 个」→ 追问意图 + 规模/硬性 ⑧ 截图:先转 URL 供 image_search;截图即目标商品 → 索要 1688 链接走 A(省图搜配额) ⑨ URL+弱化词("看看/能不能上")→ 先graph --no-submit展示等确认 ⑩ 指代不清/数量不符/重上 → 追问核对 ⑪ C(跟卖选品)与 D(上架)命令相同(discover),仅--auto-submit差别;discover 无follow_type⑫ 无人值守/任务式采集 → discover-task(缺省 ai 档粗筛;--target-count= 达标数 (profitable 出口数,达标即停护图搜配额),采集上限独立由--max-scan(默认 300)控制; 不带--to-box即干跑,入箱才真实写采集箱)。用户没说数量先问「要多少个符合要求的产品」 (router 也会追问);交互式单轮选品仍用 discover(--filter-profile ai可开同款粗筛,缺省 off 行为不变) ⑬ 任务 failed 重试无解 / Ozon 拒审反复 / 未知错误码 / 假成功 → 按references/error-report.md上报(MCP report_issue 或report命令),把 report_id 回给用户 ⑭ 长任务后台纪律:MCP 调 discover/discover-task/follow/seller/graph 等分钟级任务 一律background=true(立即返回 task_id,不阻塞对话)→ 干别的事 → 定期job_status看进度 → 完成后job_result取结果(graph 的 worker_task_ids 可直接喂query查云任务); 会话关闭任务照跑,重开会话job_list找回 ⑮ 免登录:1688/Ozon seller 未登录时 readiness 自动从本机其他浏览器导入 cookie (每小时最多一次);也可手动import-cookies导入,失败再走人工登录 ⑯ 双出口纪律:所有选品管线(1688 词搜/图搜、Ozon 选品/跟卖/任务式)都有两个出口——--to-box入采集箱(可逆,WebUI 认领后再上架)与--auto-submit直接上架 (真实创建商品)。用户没说走哪条就先问;入箱可自动执行,直接上架必须确认
2. 命令速查表
所有命令都是黑盒:先跑
python3 scripts/cli.py <命令> --help看用法,不要读cli.py源码(Cython 编译,读了浪费上下文)。命令输出即结果。 完整参数与示例见references/command-reference.md。
| 命令 | 用途 | 关键参数 | 副作用 | 适用场景 |
|---|---|---|---|---|
check |
环境检查(全量诊断) | 无 | 无 | 首次使用 / 排错 |
set_store |
配置 Ozon 店铺 | --name --client-id --api-key [--currency] |
写 data/config/ |
首次配置 |
set_token |
配置 MXOU_TOKEN | --token |
写 data/config/ |
首次配置 |
set_ak |
配置 1688 AK | --ak |
写 data/config/ |
首次配置 / AK 过期 |
update |
应用自动更新 | 无 | 覆盖 skill 文件(备份+保留 data/) | 版本升级 |
migrate_profile |
迁移 Chrome profile 统一路径 | [--apply] [--check] |
复制 profile(默认 dry-run) | 升级后迁移登录态 |
query |
查询 Worker 任务状态 | <任务ID> [--watch] |
只读 | 查进度/成败/明细 |
seller |
卖家店铺全产品运营分析 | --seller-id [--max-products] |
查 seller.ozon.ru(限速) | 跟卖卖家 → 店铺选品 |
get_ak |
浏览器自动获取 1688 AK | --timeout |
无 | AK 过期刷新 |
list_stores |
列出已配置店铺 | 无 | 无 | 查看配置 |
graph |
1688 上架 | --url/--item-id --store [--no-submit] [--ozon-ref-url] |
提交 Worker(除非 --no-submit) |
用户发 1688 商品链接 |
follow |
Ozon 跟卖 | --ozon-url --store [--auto-submit] [--review] |
提交 Worker(加 --auto-submit) |
用户发 Ozon 商品链接 |
image_search |
以图搜款 | --image [--source cdp] [--sort] [--limit] |
耗 1688 图搜配额 | 用户发图片 / 找同款 |
discover |
Ozon 选品 | --keyword/--url [--local] [--rules 挑选期,匹配期两段] [--auto-submit] [--fission] [--blue-ocean-source] [--filter-profile off|ai] [--base-filter] |
--auto-submit 提交 Worker;货源分析后生成 data/discovery/analysis_*.md |
找蓝海 / 跟卖选品 / 趋势执行 / 裂变 |
discover-task |
任务式全自动目标驱动选品(无人值守) | --keyword/--url [--target-count 达标数] [--max-scan 300] [--filter-profile ai] [--filters JSON规则文件(区间/品牌/价格/发货模式,FBS 含 rFBS,子串匹配,与库内口径一致,同名键覆盖 ai 默认)] [--base-filter] [--min-price/--max-price/--brand-filter] [--match-limit =目标×3] [--to-box|--auto-submit 二选一] [--dry-run] [--resume] [--expend-shop N 拓店(--url 须商品页种子,竞品卖家评级优先(评分≥4 展开;跟卖 widget 评分稀疏,无达标评级则不限)按价排序一跳店铺展开,预算 max(N×4,60),与 --keyword 互斥)] |
缺省干跑;--to-box 写采集箱(WebUI 认领后上架);--auto-submit 直上管线(必须确认);状态落 data/discovery/tasks/;粗筛池耗尽未达标会如实报缺口 |
"自动采集/无人值守/任务式跑 N 个" / "以这个商品为种子拓店" |
discover-multi |
多关键词批量选品 | --keywords a,b,c [--max-each] [--min-margin] |
同 discover(逐词跑) | 多词横向对比选品 |
search |
1688 关键词搜索 | query [--page-size] [--rules 挑选期,匹配期两段] [--to-box|--auto-submit 二选一] |
耗 1688 搜索配额;出口 flag 触发逐个信封+提交 | 按词找货(--rules "ai" 一键预设) |
import-cookies |
从本机其他浏览器导入 1688/Ozon 登录态 | 无 | 注入 cookie 进工具 Chrome | 未登录免手动登录(readiness 也会自动兜底) |
probe |
CDP 探针抓取单个 1688 商品 | --url [--timeout] |
无 | 调试单个商品 |
queries |
what-to-sell 蓝海/榜单查询 | --type all-queries|ozon-bestsellers|market-bestsellers [--keyword] [--export] |
成功后自动上报 worker PG;可 --export CSV/JSON |
选品前查蓝海/畅销榜 |
category |
查询 Ozon 类目 | <关键词> [--lang ZH_HANS|EN|RU] [--max N] |
只读 | 类目确认 / 排查类目匹配 |
report |
上报问题到 worker | --title [--severity] [--category] [--step]... [--task-ids] [--error-codes] |
写 worker error_reports | 任务失败/未知错误/用户抱怨(模板见 references/error-report.md) |
session-sync |
收割 seller 会话上传 worker 代管(脱敏) | --credential-id [--status] [--worker-url] |
写 worker 加密会话(AES-GCM,不回显值) | worker 提示 409 session_expired / check 提示会话过期 / 首次启用会话代管(细则见 references/session-sync.md) |
cleanup |
磁盘清理 | [--profile-cache] [--cache] [--temp] [--old-results --days N] |
删缓存/孤儿文件(登录态保留) | 磁盘占用高 |
batch_test.py |
批量处理 URL 列表 | --urls-file [--submit] [--wait] [--dry-run] |
提交 Worker(加 --submit) |
批量上架 / 回归 |
3. 决策边界
| 操作 | 策略 | 说明 |
|---|---|---|
check、pip install、set_store、set_token、set_ak |
自动执行 | 环境准备类操作,无需确认 |
graph、follow(含 --auto-submit) |
自动执行 | 用户给了明确 URL,直接上架 |
discover 选品后的最终提交 |
必须确认 | 展示候选列表,等用户说"提交" |
discover-task 干跑 / --to-box 入采集箱 |
自动执行 | 干跑零副作用;入箱可逆(WebUI 人工认领后才上架) |
--auto-submit 直上管线(任何选品命令)/ 批量直接上架 |
必须确认 | 真实提交 Worker 上架任务,影响面大 |
| 批量处理 | 必须确认 | 影响面大,需用户明确确认 |
| 利润率高低、候选产品优劣 | 展示不表态 | 陈列数据,不替用户判断 |
4. 常见越界行为
越界对照表见
references/anti-patterns.md。核心纪律:只用本文档命令、不自己写代码抓取、 提交前等用户明确确认、每次操作前重读 §1。
5. 参考文件索引
按需读取,不预先加载:
command-reference.md— 路由决策树 + 各管线完整参数/示例(选管线前、执行前查)error-codes.md— 错误码表 + 回复模板 + 进度口径(出错/问进度时查)error-report.md— 出错上报模板与纪律(任务 failed/未知错误/用户抱怨时查)session-sync.md— Ozon 卖家会话代管:worker 提示会话过期(409 session_expired)时 重同步的时机与闭环(对应场景查)output-schema.md— 输出字段解析 + 汇报模板(成功汇报时查)env-setup.md— 凭证/环境/check 排查(首次使用查)trend-selection.md/discover-fission.md— 趋势/裂变细则(对应场景查)anti-patterns.md— 越界行为对照(每次操作前自查)envelope_example.json— 信封结构示例;field_mapping.md— 字段映射规则
6. 常见问题与升级
- 缺依赖 →
pip install -r requirements.txt;graph/follow提示缺模块 → bootstrap 升级 (python3.12 bootstrap_update.py或重新下载最新包) - 升级后登录态丢失(老版本 profile 在
data/browser/profile)→ 老路径迁移先python3 scripts/migrate_profile.py --check预览,确认无误再--apply执行 (只复制不删除;细则见 references/env-setup.md)