scrape-analyze-page

此文件共 134 行，请全部阅读。

下文中的 SKILL_DIR 表示包含此文件的目录的绝对路径。

你正在从网页中提取结构化数据。给定已保存的 HTML，请识别所有可用字段并提取其值。

输入

这是用户提示：$ARGUMENTS。你需要从中提取以下信息：

1. 已保存 HTML 文件的路径，例如 product1.html。这是你需要分析的文件。如果未提供，请勿继续。
2. 输出文件的路径，例如 product1.json。如果提供，此路径就是保存结构化分析结果的位置。
3. 数据类型 spec.json 的路径。如果提供，它将通过架构字段名称、描述和示例来指导提取。
4. 如果提供了架构，是否严格只提取架构中列出的字段。如果要求严格提取，则仅提取架构字段，不要添加其他字段。
5. --list-mode：如果存在，表示该页面是列表页。将所有重复的项目实例（例如每张产品卡片）都提取为数组，而不是单个对象。

处理流程

1. 清理并读取页面

仅处理此页面。 不要读取或比较其他页面的分析文件。

.scrape/.work/ 由协调器和其他同时运行的 Agent 共享。任何时候都不要删除或“清理”其中的任何内容——完成后请保留中间文件。

清理 HTML 并提取元数据，将输出保存到工作目录。使用 {page_id}.{html_variant} 作为文件名基础，以避免冲突：

uv run --python 3.14 SKILL_DIR/scripts/clean_html.py PAGE.html -l1 -o .scrape/.work/analysis/{page_id}.{html_variant}.cleaned.html
uv run --python 3.14 SKILL_DIR/scripts/extract_metadata.py PAGE.html -u PAGE_URL -o .scrape/.work/analysis/{page_id}.{html_variant}.metadata.json

仅读取清理后的 HTML（绝不要读取原始 HTML）和元数据 JSON。如果页面没有结构化数据，元数据可以为空 {}。

2. 提取字段

重要：绝不要读取原始 HTML 文件（PAGE.html），哪怕只读取部分内容，也不要通过 Bash 等工具读取。只能使用第 1 步中的清理后 HTML 作为 HTML 数据源。

同时使用清理后的 HTML 和元数据作为数据源。元数据（尤其是 JSON-LD）中的值通常比 HTML 中显示的内容更干净、更完整，例如结构化的 price/priceCurrency 与渲染后的 "$29.99"、带评价数的 aggregateRating，以及作为结构化对象的 brand。有些字段可能仅存在于元数据中（例如 sku、gtin、@type）。

检查这两个数据源，并提取所有有意义的数据字段。有意义的字段是指描述页面自身主题的字段：排除周边网站内容，例如导航、广告，以及作为相关内容、推荐内容或最近浏览内容列出的其他项目。对于每个字段，确定：

• name：描述性 snake_case 字段名称
• type：JSON Schema 类型名称——string、number、integer、boolean、array 或 object
• value：提取的值

根据参数选择四种模式：

• 无 schema（阶段 1——发现）：提取页面中的所有有意义字段。自行设计描述性的 snake_case 名称。
• Schema（阶段 2——默认）：使用 schema 中的确切名称、描述和 examples 作为格式参考来提取字段。同时提取 schema 中未列出的其他字段——这些字段可能揭示用户尚未了解的数据。
• Schema + strict（阶段 2——重新分析）：仅提取 schema 中的字段，不添加其他字段。
• 列表模式（--list-mode）：识别页面上的重复容器元素（例如 article.product_pod、.search-result）。使用 schema 字段名称提取所有条目。不添加其他字段，仅提取 schema 字段。输出一个数组。

在 schema 模式下：

• 提取每个有值的 schema 属性，并使用 schema 中的确切字段名称保存。
• 对于 schema 字段，优先遵循字段描述和示例；在输出文件中保留完整值，并使用 schema 提供的 JSON Schema 类型标签（string、number、integer、array、object）。
• 如果清理后的 HTML 或元数据中没有 schema 字段的值，则省略该字段，不必在最终回复中提及。
• 除非用户要求严格提取，否则也提取元数据或清理后内容中明确存在的有意义额外字段。
• 对于没有 schema 类型的额外字段，使用 string、number、integer、boolean、array 或 object。
• 对于商品媒体字段，优先选择符合 schema/example 格式的显示 URL，而非规范 URL、缩略图、放大图或调整尺寸后的替代版本。
• 有意义的额外字段包括商品面包屑导航、完整的变体/报价列表，以及明显的派生计数（例如根据提取的 tools_included 列表得出的 tool_count）。
• 如果同时有单张商品图片和图片列表，且两者都有意义，则同时保存最佳单图字段和图片列表。

3. 处理较大的值

对于值较大的字段（长文本、HTML 内容、嵌套结构），提取完整值以保存，并准备一个截断版本用于摘要。

截断值时，保留其原样的开头部分，并注明省略了多少内容：

• 长文本：保留前 100 个字符（与保存的值完全一致），并注明字符总数。
• 列表或字典：保留开头的条目（与保存的值完全一致），并注明条目总数。

4. 保存完整输出

如果提供了 output_path，则将完整提取结果保存到 output_path；否则跳过此步骤。 如果用户指定了格式和结构，则按要求处理。 否则，写入符合以下结构的 JSON 文件。

标准格式（详情页，不使用 --list-mode）：

{
  "fields": {
    "name": {"type": "string", "value": "Widget X"},
    "price": {"type": "string", "value": "$29.99"},
    "description": {"type": "string", "value": "Full long description..."}
  }
}

列表模式格式（使用 --list-mode）：包含所有提取条目的数组：

{
  "url": "https://...",
  "values": [
    {"title": "A Light in the Attic", "price": "£51.77"},
    {"title": "Tipping the Velvet", "price": "£53.74"}
  ]
}

5. 返回摘要

总结你保存的文件：

uv run --python 3.14 SKILL_DIR/scripts/summarize.py OUTPUT_PATH

它会读取保存的 JSON 或 YAML，并打印每个字段的名称、类型和值；长字段会按照第 3 步所述进行截断。将其输出原样用作最终消息。

仅当未提供 output_path 时，才自行编写摘要：列出每个提取字段的名称、类型和值，不得遗漏或重命名字段，也不得用描述代替引用值，例如“8 个报价”或“24 个规格值”。

示例：

These fields were discovered:
  name (string): "Widget X"
  price (string): "$29.99"
  description (string): "Premium widget with advanced..." (2340 chars)
  rating (number): 4.5
The full report is saved to $output_path

列表模式：报告数量和一个样例：

list-1 (https://...), saved to $output_path:
  20 items extracted
  sample: title="A Light in the Attic", price="£51.77"

截断长值可以让摘要保持精简，从而与其他页面的摘要一起载入编排器的主上下文。