manai_scraping

针对1688、淘宝/天猫、京东等电商平台,自动完成商品页面的高保真物料爬取(标题、属性、SKU、主图、详情图等),并自主编写新平台的抓取插件,输出标准化商品数据 Excel 与图片目录,助力快速上架。

SKILL.md

GitHub

E-commerce Product Material Scraping & R&D SKILL

本 SKILL 指引 Agent 扮演高级电商自动化专家,针对各种电商平台进行商品页面的高保真物料爬取与采集(包括商品标题、属性、SKU参数、商品主图、详情图、颜色款式图等)。

在面对没有现成抓取脚本的电商平台时,指引 Agent 利用项目内置 BrowserWorker 插件浏览器自动分析网页结构,并自主编写、调试、集成全新的抓取 Action 脚本。


1. 守护进程与工具链说明 (Daemon & Tool Integration)

本平台使用项目内置 BrowserWorker 插件 daemon 操控浏览器。端口发现顺序为 BrowserWorker_PORT / BrowserWorker_LOCK_FILE / MANAI_WORKSPACE_ROOT 或 MANAI_HOME 下的 storage/browser_daemon.lock / 默认 12321。安装到 macOS 或 Windows 用户机器后,不要求用户额外安装 ChromeDriver、Playwright、Selenium 或独立 CDP 调试环境。

1.1 浏览器控制机制

  1. 自动生命周期管理:守护进程由 GUI 自动拉起和销毁,Agent 无需手动拉起 任何后台进程,也无需手动读写本地锁文件或发送 HTTP 网络请求。
  2. 免维护调用:所有网页控制与数据抓取操作,均应通过 BrowserWorker /execute 加载 scripts/actions 中的 Action,或通过平台内置浏览器控制工具间接调用。
  3. 工具参数格式:
    {
      "action": "action_name",
      "action_search_path": "<skill_path>/scripts/actions",
      "args": {
        "url": "..."
      }
    }
    

2. 核心物料采集流程

第一阶段:安全前置提示与收集待抓取 URL

  1. 前置提示(必须首先告知用户):在开始任何采集或分析任务前,Agent 必须主动向用户提示以下三点注意事项,确认用户知晓后再进行后续操作:
    • 插件浏览器接管:本工具会通过 BrowserWorker 插件浏览器访问目标平台,不要求用户安装或打开日常 Chrome。
    • 登录要求:如平台要求登录或验证码,Action 会调用 request_help,用户在插件浏览器中完成后继续。
    • 安全频次:单日抓取量建议不要过大(例如控制在 200 条以内),以防平台检测并封禁账号或 IP。
  2. 向用户确认待抓取的商品详情页 URL 列表。
  3. 若用户仅提供"平台"和"搜索关键词":引导 Agent 使用 BrowserWorker 插件浏览器执行关键词搜索,并将搜索结果页中提取出的前 N 个商品详情链接作为最终要抓取的 URL 列表呈现给用户确认。

第二阶段:检查并复用现有插件

  1. 优先使用现有抓取插件: 在爬取以下平台时,必须优先使用已有的 BrowserWorker Action,严禁重新研发:

    • 1688:使用动作 scrape_1688 (对应文件为 scripts/actions/scrape_1688.py),支持 https://detail.1688.com/offer/<offerId>.html 与带 offerId=<offerId> 的移动端链接。
    • 淘宝 (Taobao):使用动作 scrape_taobao (对应文件为 scripts/actions/scrape_taobao.py)
    • 天猫 (Tmall):使用动作 scrape_tmall (对应文件为 scripts/actions/scrape_tmall.py),针对 detail.tmall.com 提取完整 PC 详情页 SPU 物料。
    • 京东 (JD):使用动作 scrape_jd (对应文件为 scripts/actions/scrape_jd.py),面向 item.jd.com 商品详情页,提取清洗后的标题、价格/原价、SKU 与完整参数,下载 商品主图、商品详情页图、颜色规格图,生成两级表头 商品数据-<ItemId>.xlsx 与 商品整理.log。不要把旧版 JSON-only 结果当作完整物料交付。

    例如,调用 BrowserWorker /execute:

    {
      "action": "scrape_jd",
      "action_search_path": "<skill_path>/scripts/actions",
      "args": {
        "url": "https://item.jd.com/1000123456.html"
      }
    }
    
  2. 解析返回的 JSON 结果,向用户展示抓取到的商品标题、SKU 数量与保存路径。

第三阶段:进入新脚本研发 (R&D) 流程

若无匹配脚本,必须严格按照以下五个步骤自主研发新插件:

步骤 1:启动采样与源码提取

为了分析网页结构,Agent 应优先读取当前页面匹配的 page_semantics,按 semantic_key 理解页面上的稳定业务元素(如 search.primary_input、search.submit、result_card.primary_link)。缺少语义记录或置信度不足时,再通过 BrowserWorker 插件浏览器执行页面导航、滚动、DOM 快照及页面内 JS 提取。真实截图能力在当前 BrowserWorker 规范中禁用时,不要强依赖截图;优先使用 snapshot / evaluate / document.body.innerText 来验证当前页面事实并补充语义证据。

flexible_access 采样与源码提取工具调用示例:

{
  "action": "flexible_access",
  "action_search_path": "<BrowserWorker>/browser_service/actions",
  "args": {
    "steps": [
      {"op": "goto", "args": ["<target_url>"]},
      {"op": "wait_for_timeout", "args": [5000]},
      {"op": "evaluate", "args": ["window.scrollBy(0, 800)"]},
      {"op": "wait_for_timeout", "args": [1500]},
      {"op": "content"}
    ],
    "keep_open": true
  }
}

执行完毕后,将返回的 content 源码写入临时文件夹中的 page_source.html(临时目录路径优先使用 temp/ 下按日期建的子目录),并在命令行向用户展示"HTML 已保存",然后立即自主进入步骤 2。当前 BrowserWorker 禁用真实浏览器截图,验证页面状态时使用 snapshot、title、url、content 或 evaluate。snapshot 返回的 ref / handle 只能用于当前页面的一次性闭环验证,不得写入可复用脚本;需要长期复用时写入或更新 page_semantics 中的 semantic_key 与定位证据。

步骤 2:分析结构

  1. 元素搜索:读取并检索保存的临时 HTML 页面源码。
  2. 提取定位:
    • 搜索包含商品名、价格、商品属性、规格、轮播主图等数据的 DOM Class、ID 或包含配置信息的 JSON 数据块(例如 script 标签里的 window.__INITIAL_STATE__ 或 window.pageData 等全局变量)。
    • 提炼出能够使用页面内 JavaScript browser.evaluate 获取对应信息的规则或选择器。优先使用 semantic_key、稳定业务属性、文本匹配和 DOM 结构,不依赖动态 CSS 哈希类名;页面关键控件和重复数据卡片应沉淀为 page_semantics 证据,后续执行时先解析语义键再重验证当前 DOM。

步骤 3:编写新抓取插件脚本

在 scripts/actions/ 目录下新增文件 scrape_<platform_name>.py(全小写,下划线分隔,如 scrape_pinduoduo.py)。脚本必须严格遵循以下规范:

插件规范一:元数据声明

脚本顶部必须声明 metadata,格式示例如下:

metadata = {
    "name": "scrape_pinduoduo",
    "description": "输入拼多多商品 URL,提取商品标题、价格、SKU 并下载主图/详情图/属性表到指定的物料上架目录中。",
    "parameters": {
        "type": "object",
        "properties": {
            "url": {"type": "string", "description": "商品详情页的完整 URL"},
            "output_dir": {"type": "string", "description": "用户指定的物料输出目录路径"}
        },
        "required": ["url"]
    }
}
插件规范二:核心处理接口

必须实现 handler(browser, args) 接口,其中 browser 是 BrowserWorker 插件浏览器对象,args 包含传入参数。不得使用 cdp.send_cmd、Target.*、Page.*、Runtime.* 或直接连接 Chrome DevTools Protocol。它必须包含以下流程:

  1. 导航与加载:使用 browser.goto(url, timeout_ms=45000, tab_key="main") 打开商品 URL,并用 browser.wait_ms 等待页面稳定。
  2. 获取与解析:通过 browser.evaluate 在页面上下文中执行 JS,提取商品名、店铺/商家名、参数表、SKU 数据(规格、价格、库存等)。在解析商品属性时,必须尽可能完整地提取并保留所有页面能获取到的字段(如材质、品牌、各项规格参数等),不得遗漏。
  3. 输出物料文件:
    • 在用户指定的本地输出目录下(格式为:{平台名}商品{时间戳},若用户未指定输出目录,则默认为全局配置 data_directory 目录下的 {平台名}商品{时间戳}/),并在该父目录下新建三位序号递增 of SPU 目录(如 001聚氨酯pu棒...)。
    • 新建 SPU 目录下的子目录:商品主图、商品详情页图、颜色规格图(颜色规格图目录同时用于存放颜色款式图与规格尺寸图)。
    • 标准 Excel 导出:使用 openpyxl 导出 商品数据-<OfferID>.xlsx。表头必须是两级合并表头,第一行是字段分组标题("商品名称"、"商品规格"、"价格与库存"、"商品属性"等),第二行是具体字段名。
    • 分级过滤图片下载:
      • 主图:过滤并保留大小 >= 50KB 的图片。
      • 详情图:过滤并保留大小 >= 50KB 的图片。
      • 款式颜色图:过滤并保留大小 >= 50KB 的图片。所有款式颜色与规格图片需统一存放在 颜色规格图 目录下。图片下载与保存时,其命名必须按照在页面上出现的先后顺序带上三位数字编号前缀(从 001 开始一直往后编号,如 001黄色.jpg,002大号黑色.jpg),以便于人工 Review 与整理归档,严禁使用无意义的哈希或纯随机命名。
      • URL 黑名单过滤:自动跳过包含 banner, logo, cert, promise, service, shipping 等非商品素材关键词的图片 URL。
  4. 更新商品日志:
    • 将当前 SPU 的名称、状态、SKU 数量、主图/详情图/颜色规格图数量,追加写入父目录下的 商品整理.log。

直接参考同目录下已有的 scrape_1688.py、scrape_taobao.py、scrape_jd.py 的 BrowserWorker 插件写法进行编写。

步骤 4:运行测试与回显

  1. 热加载运行: 守护进程在处理调用请求时会自动重新加载 actions/ 目录下的最新脚本。 Agent 通过 BrowserWorker /execute,传入 action: "scrape_<platform>" 与 action_search_path 运行该脚本。
  2. 反馈确认: 展示运行结果的 JSON 报告(包含 SKU 数量、主图与详情图的下载张数、以及输出的物料目录路径),并向用户发出询问:

    "已成功运行新编写的 scrape_<platform> 采集脚本进行测试。生成的物料目录为 ...,包含 SPU 和 SKU 数据。请您检查或确认结果是否正确?"

步骤 5:循环迭代与批量抓取

  1. 反馈修正: 如果用户指出数据或图片有缺失或不正确,根据反馈重新阅读 page_semantics、页面 HTML、snapshot 或页面内 evaluate 结果,修改 scripts/actions/scrape_<platform>.py 的解析逻辑;若发现新的重要语义元素,更新对应 semantic_key 的证据,再调用工具重新测试,直到用户确认无误。
  2. 批量运行: 用户确认无误后,Agent 对用户给出的剩余 URL 列表进行批量迭代抓取,记录所有爬取日志,并生成总的物料文件夹。

3. 商品图片与详情缺失的补图引导

在物料采集过程中,如果发现以下情况:

  • 原电商页面缺少主图或详情图。
  • 详情图分辨率过低,无法用于拼多多上架。
  • 用户抓取后,提出"帮我重新做几张主图/场景图"等补图要求。

必须立即引导用户切换至【商品图片生成 SKILL (manai_image_generation_skill.md)】,使用 Manai 智能生图工具对采集回来的基础素材进行补充生成。


4. 安全与规范约束 (Constraints)

  1. 绝对路径禁止:生成的脚本和日志中不得包含任何形式硬编码的个人电脑绝对路径,必须使用相对路径或系统变量动态获取。
  2. 错误处理与清理:不要在 Action 内直接管理 Chrome Target。/lock/release 只释放并发锁,默认保留页面;需要关闭浏览器页面时,显式调用 /session/close、/browser/close-session、/tabs/close,或在 /lock/release 请求中传入 close_browser: true。
  3. 临时文件清理:在临时目录下生成的临时 DOM 源码、快照 JSON 等中间结果,一旦采集脚本研发成功并投入运行,必须在任务结束前将其删除,做到"用完即删"。