1688-selection-upload

[!IMPORTANT] 前置插件约束：运行本技能前必须确认 1688 采购助手插件 (1688-extension) 已安装。平台会在触发 1688-selection-upload 任务时自动校验插件状态。若未检测到 1688 插件，平台将拦截任务并引导由运营主管（ops_director）使用 chrome-plugin 技能安装 1688 插件。

统一入口：

python3 {baseDir}/run.py <command> [options]

该技能使用项目内置 BrowserWorker daemon 的 extension-first transport，不再直接依赖 CDP 控制页面，也不要求用户机器安装 ChromeDriver、Playwright、Selenium 或固定 Chrome 路径。页面读取通过 BrowserWorker 插件浏览器执行 browser.evaluate(...)，因此能读取 1688 原页面和采购助手插件渲染到当前 DOM 中的内容。

意图判断

触发本技能：

• 用户要求在 1688 搜索、选品、筛选商品。
• 用户提到采购助手、待采商品勾选、选品勾选。
• 用户要求按月代销、48H 揽收率、实力商家/源头旗舰筛选。

命令选择：

只查看符合条件的商品 -> scan
勾选符合条件的采购助手商品，不最终提交 -> collect

命令

命令	用途	语法
scan	扫描并返回符合条件的商品，不点击页面	python3 run.py scan [关键词] [--pages 页数]
collect	扫描并勾选符合条件商品，不点击最终提交按钮	python3 run.py collect [关键词] [--pages 页数] [--max 最大采集数] [--dry]

默认值：

• 关键词：女鞋
• --pages：1
• --max：0 表示不限制
• --dry：只列待勾选商品，不点击

新架构流程

1. run.py 获取浏览器锁，然后调用 daemon /execute。
2. run.py 必须传入本 skill 的 action_search_path={baseDir}/scripts/actions。
3. daemon 必须优先加载 action_search_path 下的 scan_1688.py 或 collect_1688.py；BrowserWorker 内置 actions 只是 fallback，不能覆盖本 skill 同名 action。
4. /execute 返回里的 action_path 可用于确认实际加载的 action 文件。
5. action 通过 browser.goto/evaluate/wait_ms/request_help 操作 BrowserWorker 插件浏览器页面。
6. action 先进入 1688 搜索页，输入关键词，进入搜索结果页。
7. action 拼接排序和商家过滤参数：
   • 销量降序：sortType=va_sales360&descendOrder=true
   • 商家标签：filtMemberTags=5179713,5125953,5343297
8. 分段滚动页面，等待懒加载和采购助手插件数据面板渲染。
9. 在页面 DOM 中提取商品卡片、月代销、48H 揽收、价格、勾选状态。
10. scan 返回符合条件商品；collect 只勾选商品卡片内的采购助手复选框，并更新 data/ledger.json。不要继续点击最终提交、确认、批量采集或一键上架按钮。

筛选口径

当前硬规则：

• 月代销 != "100以内"，视为月代销 > 100。
• 48h揽收 > 90%。
• 搜索 URL 会附带实力商家/源头旗舰相关标签过滤。

返回字段包括：

• offerId
• title
• dx：月代销桶值
• ls：48H 揽收率数字
• price
• href
• qualify
• collected

快速定位和排查

如果页面结构变化导致勾选失败，按这个顺序处理：

1. 先读取当前页面匹配的 page_semantics，优先按 semantic_key 理解关键元素和重复商品卡片，例如 search.primary_input、search.submit、result_card、result_card.primary_link、selection.checkbox。
2. page_semantics 缺失、低置信或执行失败时，再用 BrowserWorker snapshot 验证当前页面事实并补充证据。
   • 页面简单：可用 full snapshot。
   • 搜索结果/卡片列表：优先 data snapshot。
   • snapshot 返回的 ref / handle 只用于当前页面的一次性验证，不写入脚本或台账。
3. snapshot 找不到时，用小 JS probe 检查真实 DOM：

(() => [...document.querySelectorAll("a.search-offer-wrapper,[class*='search-offer-wrapper']")]
  .slice(0, 20)
  .map(el => ({
    text: (el.innerText || "").replace(/\s+/g, " ").trim().slice(0, 240),
    href: el.href || el.querySelector("a[href]")?.href || ""
  })))()

4. 页面很复杂、hover 才出现按钮、插件 UI 难判断时，让用户用 BrowserWorker 扩展录制并上传。
5. 读取上传后的三层数据：
   • *.trace.json
   • *.interests.json
   • *.script_hints.json
6. 根据录制里的 page_key/page_role、semantic_key 和候选节点证据更新 page_semantics、action 的结构化目标或 DOM parser；不要把 @eN、临时 handle、长路径 selector 当作长期定位键。

人工处理

遇到登录、滑块、验证码时，action 会通过 browser.request_help(...) 提示用户在 BrowserWorker 插件浏览器中处理，然后继续执行。不要绕过安全验证。

输出和台账

collect 默认读取并更新本 skill 下的 data/ledger.json，避免重复勾选已成功的 offerId。也可以用环境变量 MANAI_1688_SELECTION_LEDGER 指向外部台账；如果旧版根目录 ledger.json 已存在且 data/ledger.json 不存在，会兼容读取旧文件。

run.py 默认将符合条件的商品链接保存到 data/outputs/1688_selection_<关键词>.json。如果 ManAI 全局配置里有 data_directory，或设置了 MANAI_1688_SELECTION_OUTPUT_DIR，允许写到外部目录。脚本和 action 实现必须留在 {baseDir}/ 内；运行产物可配置。

验证

修改 action 后至少运行：

python3 - <<'PY'
from pathlib import Path
for p in [
  "scripts/actions/scan_1688.py",
  "scripts/actions/collect_1688.py",
  "run.py",
]:
    src = Path(p).read_text(encoding="utf-8")
    compile(src, p, "exec")
print("syntax ok")
PY

真实验证：

python3 run.py scan 保温杯 --pages 1
python3 run.py collect 保温杯 --pages 1 --max 3 --dry