Linkfox Plugin Web Data Crawler

跨境电商商品详情页采集

Overview

通过 startCrawlTask 接口把采集工作流投递给浏览器插件执行。覆盖 Amazon（全站点）和 SHEIN。 CLI 封装了 URL 构造、OPEN_TAB 剥离、品类字段注入、图片后处理——AI 只需调对命令，不需要手动拼接管道或逐步骤操作 workflow JSON。

核心规则：

• 修复失败的 workflow 时，🔴 绝不 Write/Edit sites/ 目录下任何文件——修复在内存中，通过临时文件 + send 子命令重试
• 下游执行器不支持并发——同一时间只能有一个 workflow 运行，必须等待当前任务完整结束
• Workflow 步骤内置 onFailure 自愈机制（selector 过期时自动 FIND_SELECTOR 重试），AI 只在自愈也失败时介入

When to Use

触发场景（匹配任一）：

• 用户给 Amazon ASIN（B 开头 10 位字母数字，如 B0C5J7X5N5）
• 用户给 amazon.com/dp/ 或 amazon.com/gp/product/ URL
• 用户给 shein.com/ URL
• 用户要"采集/爬取/抓取 Amazon/Shein 商品详情"，"获取商品详情/价格/评分"
• 用户提供商品标识符未说明平台（ASIN 模式明显 → 默认 Amazon）

不适用：

• 后端接口能直接返回的数据（走对应接口 skill）
• 列表页/搜索页（本 skill 仅覆盖详情页）
• 需要登录/付费墙后的内容

⚠️ Critical Rules

Execution Flow

Step 1 — 站点匹配

读 sites/INDEX.md，对照 Site Map 表匹配用户输入：

1. URL 域名 → 匹配 Domain 列，从 Locale(s) 列确定 --site 参数（如 amazon.co.jp → amazon-jp）
2. 产品 ID 匹配站点 README frontmatter 的 product_id_pattern → 确定 site key。Amazon ASIN（B + 9 位字母数字）是典型例子，默认 --site amazon-us
3. 用户明确说出站点名 → 匹配 Display Name 列
4. 均不匹配 → 追问用户

--site 合法值见 INDEX.md Site Map 表 + 站点 README 的 Locale 参考表。

Step 3 — 品类探测

前提：sites/<site>/_category-probe.json 存在。不存在则跳过，直接执行 Step 4。

跳过探针（满足任一）：

• 用户明确轻量意图（"只要价格"、"多少钱"）
• 用户输入匹配站点 README 品类关键词表中的关键词 → 直接确定 --category <key>

标准流程：

1. 检查用户输入是否命中 README 中的品类关键词 → 命中则推断 categoryKey，跳过探针
2. python scripts/run_crawl.py probe --site <key> --url <url>
3. 对照 sites/<site>/categories/INDEX.md 解析 breadcrumb + detail_keys，匹配品类
4. 不命中 → 默认 generic（仅用 base-full，不注入品类字段）

Step 4 — 采集

# 标准采集（无品类、无探针）
python scripts/run_crawl.py scrape --site amazon-us --url https://www.amazon.com/dp/B0XXX

# 品类采集（probe 之后，复用 tab）
python scripts/run_crawl.py scrape --site amazon-us --url https://www.amazon.com/dp/B0XXX --reuse-tab --category books

# 用户指定品类（跳过 probe）
python scripts/run_crawl.py scrape --site amazon-us --url https://www.amazon.com/dp/B0XXX --category electronics

轻量意图（用户只要部分字段）：CLI 当前仅内置 --scenario full。需要裁剪时，AI 从 base-full.json 读取步骤，手动构造 OPEN_TAB + WAIT + 目标 EXTRACT + CLOSE_TAB，通过 send 子命令发送：

python scripts/run_crawl.py send --site amazon-us --file /tmp/lightweight.json --url <url>

评论采集

python scripts/run_crawl.py reviews --site amazon-us --url https://www.amazon.com/product-reviews/B0XXX/

各站点的评论采集差异（如 Shein 评论在商品页底部懒加载）见对应 README 的 known_gotchas。

Part 2 — Failure Diagnosis

失败时读 references/part2-repair.md。三层递进：

最多 4 次总尝试（含原始执行）。全失败 → 输出诊断摘要。

⚠️ 修复重试与后处理：send 子命令不执行图片后处理（scrape 才做）。修复验证通过后，如果结果是完整商品详情（非轻量意图），建议用 scrape 重跑一次获得含后处理的完整结果。

⚠️ 修复后不要传 --category：如果修复后的 workflow 已自包含全部步骤（包括修复后的品类字段），不要传 --category 参数——否则 CLI 会从 categories/fields/ 注入原始未修复的品类字段，覆盖修复后的步骤。--category 仅用于原始 workflow 的品类注入。

输出

采集结果自动落盘到会话目录：

<linkfox_root>/<YYYY-MM-DD>/<session>/data/linkfox-plugin-web-data-crawler-<ts>.json

stdout 同步打印 [Saved] <路径> 和完整结果，供 AI 当场消费。

生成报告：采集完成后需生成产品情报 HTML 报告，进入 Part 3（references/part3-report.md）：

1. AI 分析原始采集 JSON → 产出标准化 clean_data.json
2. 调用 python scripts/generate_report.py <clean_data.json> <output.html>

脚本是纯模板注入引擎，不做数据解析。模板位于 templates/amazon-report.html。

缺参追问

分类型分轮，禁止混在一句话：

• 开放输入（商品 URL、ASIN）→ 自然语言直接问，如「请提供要采集的商品详情页 URL」
• 仅 ASIN 无 URL：默认 --site amazon-us，不追问。仅当上下文有明显线索指向非 US 站（如用户之前聊的是日本站商品）时才用 AskUserQuestion 确认站点（≤4 个选项，不含"跳过"）
• URL 已含域名 → 从域名推断 --site 参数（对照 sites/INDEX.md 的 Domain 列），不追问
• LINKFOX_AGENT_API_KEY 未配：提示用户前往 https://skill.linkfox.com/linkfoxskills/guide.htm 申请并设置环境变量后重试。LINKFOX_TOOL_GATEWAY 未配用默认值，不问

失败处理

• TIMEOUT / 网络异常 / 5xx：最多 3 次重试，退避 1s→2s→4s
• FAILED + "客户端不在线"：不重试，提示用户打开插件
• FAILED + 其它：进入 Part 2 诊断修复

新增站点

1. 创建 sites/<site-key>/base-full.json（站点特有选择器）
2. 创建 sites/<site-key>/README.md（含 frontmatter 元数据 + 品类关键词表）
3. 可选创建 _category-probe.json + categories/
4. 更新 sites/INDEX.md 添加一行
5. 有必要时添加 scripts/<site-key>_image_post.py（CLI 自动发现并执行）

扩展现有站点的 locale：更新 run_crawl.py 的 AMAZON_SITE_DOMAINS + sites/INDEX.md Locale(s) 列。

限制

• 仅覆盖商品详情页
• SHEIN 选择器需定期校准
• 仅支持 Amazon ASIN→URL 自动拼接
• 仅走同步 startCrawlTask

反馈

按 references/api.md 末尾 Feedback API 上报。