scrape-define

你正在帮助用户快速定义要从网站提取哪些内容。下载 1 个详情页，发现字段，并在终端中迭代调整架构，直到获得批准。

阅读 ${CLAUDE_SKILL_DIR}/../scrape/references/python-environments.md。

输出是一个草案规范文件夹，其中包含已批准的架构和值（不存储页面——这是第 2 阶段的工作）。可通过 /scrape-spec 扩展（更多页面、变体比较、导航）。

硬性约束——绝不可违反：

• 你绝不能自行获取、读取、搜索或解析任何 HTML 文件。页面下载由 /scrape-explore-site 子 Agent 处理；字段发现由 /scrape-analyze-page 子 Agent 处理。主 Agent 只负责协调并使用它们的输出。
• 这包括 raw.html、rendered.html、*.cleaned.html 以及任何其他已保存的页面 HTML。你可以检查文件是否存在，但绝不能由主 Agent 打开、打印、搜索、解析这些文件，或针对它们运行提取脚本。
• 在构建任何架构之前，你必须先将 /scrape-analyze-page 作为子 Agent 调用。未先运行该子 Agent 就根据原始 HTML 构建架构属于严重错误。
• 等待 /scrape-analyze-page 时，不要读取 HTML 文件、运行 clean_html.py、extract_metadata.py 或任何内联解析器代码，即使 Agent 的回复建议继续处理无关工作也不行。等待子 Agent 完成，然后只读取其保存的 JSON 输出。

解析意图

从 $ARGUMENTS 中确定：

• target_url：起始 URL
• data_type：要提取的数据类型，始终使用单数——无论用户明确指出，还是你根据 URL/页面推断。如果用户说“books”，使用“book”；“products” → “product”；“articles” → “article”。如果是推断得出，使用单数项目名词（例如，“product”而非“products”，“book”而非“books”）。在任何地方使用前都要先改为单数。
• field_hints：用户提到的任何具体字段（可以为空）
• site_name：简短标识符（例如，“books-toscrape”、“realestate-listings”）——根据网站和数据类型确定

第 1 步：设置文件夹

确保 site_name 唯一：

BASE="books-toscrape"  # your derived site_name
NAME="$BASE"
N=2
while [ -d ".scrape/$NAME" ]; do NAME="${BASE}-${N}"; N=$((N+1)); done
echo "$NAME"

创建文件夹结构（{data_type} 必须为单数，例如 book 而非 books）：

.scrape/{site_name}/
  {data_type}/
.scrape/.work/{site_name}/
  explore/
  analyze-page/

第 2 步：获取详情页

通过 AskUserQuestion 询问用户如何获取详情页：

• question：“我应该如何获取一个详情页进行分析？”
• header：“详情页”
• options：
  • Provide a URL — “我会粘贴一个详情页 URL（例如商品页面）。”
  • Explore the site — “从目标 URL 自动查找一个。”

如果用户选择“Provide a URL”：使用纯文本提示继续询问——“请粘贴详情页 URL。”——并等待用户的下一条消息。然后使用 download.py 下载该页面：

uv run ${CLAUDE_SKILL_DIR}/../scrape-explore-site/scripts/download.py --skill scrape-define --log-file .scrape/.work/{site_name}/explore/download.log <<'EOF'
[{"url": "USER_URL", "output_dir": ".scrape/.work/{site_name}/explore/pages/detail-1", "page_type": "detail"}]
EOF

如果用户选择“Explore the site”：使用子 Agent 以最少数量运行 /scrape-explore-site 技能。子 Agent 提示应为：

Run /scrape-explore-site {target_url} .scrape/.work/{site_name}/explore 1 0

这会将主页和 1 个详情页下载到 .scrape/.work/{site_name}/explore/pages/。

如果网站被拦截，建议使用 Zyte。只有在用户同意后，才调用 /scrape-zyte-login。该技能返回后，重新运行上述 scrape-explore-site 子 Agent。

步骤 3：分析详情页

使用 rendered.html 进行分析。如果该文件不存在，则使用 raw.html。仅通过检查文件是否存在来选择；主 Agent 不得读取、搜索、打印、清理或解析任何一个 HTML 文件。

使用分析技能运行一个子 Agent。子 Agent 提示词必须以 /scrape-analyze-page 开头，且子 Agent 必须调用该技能；主 Agent 不得改用 clean_html.py、extract_metadata.py、sed、grep、cat 或内联 Python/lxml 解析来代替。

Agent(description="analyze detail-1 rendered", prompt="/scrape-analyze-page Extract data from .scrape/.work/{site_name}/explore/pages/detail-1/rendered.html and save it into .scrape/.work/{site_name}/analyze-page/detail-1.rendered.json")

启动分析子 Agent 后，等待其完成。如果预期的 JSON 文件不存在，则重试 /scrape-analyze-page 子 Agent，或报告阻塞问题。不得自行根据 HTML 创建分析 JSON。

从 .scrape/.work/{site_name}/analyze-page/detail-1.rendered.json 读取分析结果。分析子 Agent 返回后，不得检查下载的网页 HTML 或任何清理后的 HTML；对于主 Agent，JSON 结果是唯一允许用于发现字段的输入。

步骤 4：构建架构

根据分析结果构建 JSON Schema：

• 收集所有字段名称及其类型
• 映射类型：str → string，float → number，int → integer，list → array，dict → object
• 为每个字段添加 description（根据上下文推断）
• 将与 field_hints 匹配的字段标记为 "source": "requested"，其他字段标记为 "source": "discovered"

步骤 5：快速检查架构

在终端中展示包含值的架构。按 requested/discovered 分组：

Found {N} fields on {detail_page_url}:

Requested:
  title (string): "A Light in the Attic"
  price (string): "£51.77"

Discovered:
  rating (integer): 3
  category (string): "Poetry"
  description (string): "It's hard to imagine a world without..." (2340 chars)
  upc (string): "a897fe39b1053632"
  image_url (string): "https://books.toscrape.com/media/cache/fe/72/..."

等待用户回复。用户可以：

• 批准：“looks good”“ok”“approve”等 → 进入步骤 6
• 删除字段：“drop description, image_url” → 从架构中删除，并展示更新后的架构
• 保留发现的字段：“keep rating” → 将 source 改为 "requested"
• 重命名：“rename upc to product_code” → 在架构中重命名
• 编辑描述：“price should be without currency symbol” → 更新描述和值
• 其他指示：应用指示并展示更新后的架构

循环上述过程，直到用户批准。每次变更后都重新展示架构。

步骤 6：保存规范

数据类型规范

写入 .scrape/{site_name}/{data_type}/spec.json。输出必须是有效的 JSON Schema（draft/2020-12）——严格使用下方所示的结构。不要编造自定义格式（例如，纯字段对象数组）。在每个架构字段中包含 examples，其值为用户批准的值（包括任何修正）。这会告知 Stage 2 预期的格式。所有字段都必须包含 examples。超过 200 个字符的值需截断并添加 "..."，同时保留足够内容以展示格式。

{
  "url": "https://books.toscrape.com",
  "data_type": "product",
  "html_variant": "rendered",
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "description": "Book title as displayed on the detail page",
        "source": "requested",
        "examples": ["A Light in the Attic"]
      },
      "price": {
        "type": "string",
        "description": "Book price without currency symbol",
        "source": "requested",
        "examples": ["51.77"]
      }
    }
  }
}

站点级规范

写入 .scrape/{site_name}/spec.json：

{
  "url": "https://books.toscrape.com",
  "data_types": ["{data_type}"]
}

注意：data_types 仅列出主要数据类型。/scrape-spec 稍后会添加 "navigation"。

完成

Spec draft saved to .scrape/{site_name}/:
  {data_type}: {N} fields

Run /scrape-spec .scrape/{site_name} to explore more pages and validate.