shopify-admin-agentic-crawler-access

用途

如果商店的 robots.txt 没有按名称处理 AI 爬虫，或者更糟——明确禁止它们，那么 ChatGPT、Claude、Perplexity 等助手可能永远不会读取你的商店内容，商店在 AI 购物者面前就等于不存在。Shopify 会根据主题模板（templates/robots.txt.liquid）生成 robots.txt。本技能读取该模板，并为主要 AI user-agent 追加显式的允许（allow）规则（使用清晰、幂等的受管代码块），使基础模型和 AI 搜索获准抓取你的页面。用于修复 agentiq.report 的 robots-ai-rules 检查项。

前置条件

已认证的 Shopify CLI 会话（shopify auth login --store <domain>）
所需 API 权限范围：read_themes、write_themes

参数

所有技能都接受以下通用参数：

参数	类型	必填	默认	说明
store	string	是	—	商店域名（例如 mystore.myshopify.com）
format	string	否	human	输出格式：human（默认）或 json
dry_run	bool	否	true	预览新的 robots.txt.liquid 而不写入（默认开启——因为这会编辑线上主题）

技能专属参数：

参数	类型	必填	默认	说明
theme_id	string	否	—	要编辑的主题 GID（默认为已发布的 MAIN 主题）
agents	string	否	GPTBot,OAI-SearchBot,ChatGPT-User,ClaudeBot,Claude-Web,PerplexityBot,Perplexity-User,Google-Extended,Amazonbot,Applebot-Extended	以逗号分隔的、需放行的 AI user-agent 列表
mode	string	否	allow	allow（添加 Allow 规则）或 audit（仅报告当前状态，不写入）

安全性

⚠️ 第 2 步（themeFilesUpsert）会修改线上已发布主题中的文件。格式错误的 robots.txt.liquid 可能导致商店被所有搜索引擎取消索引。本技能仅在清晰界定的 # BEGIN agentic-crawler-access … # END 受管块内写入（重新运行只会替换该块，绝不会动你的其他规则），默认 dry_run: true，并建议先复制主题。在将 dry_run 设为 false 之前，请审阅完整的拟议文件。

工作流步骤

OPERATION: themes — query
- 输入：roles: [MAIN]（除非给定了 theme_id），然后 theme.files(filenames: ["templates/robots.txt.liquid"])
- 预期输出：当前 robots.txt.liquid 内容（或不存在——若模板不存在，Shopify 会使用默认值）。
COMPUTE（无 API）：构造新模板。如果不存在自定义模板，则从 Shopify 默认值（{{ robots.default_groups }}）开始，并为 agents 中的每个 agent 追加带有 User-agent:/Allow: / 语句的受管块。如果受管块已存在，则只替换它。输出完整的拟议文件 diff。
OPERATION: themeFilesUpsert — mutation
- 输入：themeId, files: [{ filename: "templates/robots.txt.liquid", body: { type: TEXT, value: <新内容> } }]（当 dry_run 或 mode: audit 时跳过）。
- 预期输出：被 upsert 的主题文件；收集 userErrors。

GraphQL 操作

# themes:query — 对照 api_version 2025-01 验证
query CrawlerThemeFile {
  themes(first: 1, roles: [MAIN]) {
    nodes {
      id
      name
      files(filenames: ["templates/robots.txt.liquid"]) {
        nodes {
          filename
          body { ... on OnlineStoreThemeFileBodyText { content } }
        }
      }
    }
  }
}

# themeFilesUpsert:mutation — 对照 api_version 2025-01 验证
mutation CrawlerAllowUpsert($themeId: ID!, $files: [OnlineStoreThemeFilesUpsertFileInput!]!) {
  themeFilesUpsert(themeId: $themeId, files: $files) {
    upsertedThemeFiles { filename }
    userErrors { filename code message }
  }
}

写入 templates/robots.txt.liquid 的受管块（位于 {{ robots.default_groups }} 之后）：

# BEGIN agentic-crawler-access (managed by shopify-admin-agentic-crawler-access)
User-agent: GPTBot
Allow: /
User-agent: ClaudeBot
Allow: /
User-agent: PerplexityBot
Allow: /
User-agent: Google-Extended
Allow: /
# ... one stanza per agent in `agents`
# END agentic-crawler-access

会话跟踪

Claude 必须在每个阶段输出以下内容。这是强制要求。

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: <skill name>                         ║
║  Store: <store domain>                       ║
║  Started: <YYYY-MM-DD HH:MM UTC>             ║
╚══════════════════════════════════════════════╝

每个步骤之后输出：

[N/TOTAL] <QUERY|MUTATION>  <OperationName>
          → Params: <brief summary of key inputs>
          → Result: <count or outcome>

如果 dry_run: true，则在每个 mutation 步骤前加 [DRY RUN] 前缀，并且不执行它。

完成时输出：

对于 format: human（默认）：

══════════════════════════════════════════════
OUTCOME SUMMARY
  <Metric label>:   <value>
  Errors:           0
  Output:           <filename or "none">
══════════════════════════════════════════════

对于 format: json，输出：

{
  "skill": "<skill-slug>",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": false,
  "steps": [
    {
      "step": 1,
      "operation": "<OperationName>",
      "type": "query",
      "params_summary": "<string>",
      "result_summary": "<string>",
      "skipped": false
    }
  ],
  "outcome": {
    "metric_key": 0,
    "errors": 0,
    "output_file": null
  }
}

输出格式

human：before/after 的 robots.txt.liquid，以及现在被允许的 agent 列表。
json：{ theme_id, agents_allowed:[...], wrote: true|false, errors }。

错误处理

错误	原因	恢复方式
THROTTLED	API 速率限制	等待 2 秒，最多重试 3 次
ACCESS_DENIED	缺少 write_themes	中止并给出清晰的权限范围提示；不要部分写入
upsert 上的 userErrors	无效的模板正文	不写入；将 Liquid 错误暴露出来供审查

最佳实践

写入前复制已发布主题（Online Store → Themes → Duplicate），以便即时回滚。
在阅读完整个拟议文件之前保持 dry_run: true——损坏的 robots.txt.liquid 可能导致整个商店被取消索引。
使用受管块标记；绝不要手工合并——重新运行技能时只会干净地更新它自己的块。
允许 AI 爬虫 ≠ 交出内容；这只是允许它们像 Googlebot 一样读取公开页面。可与 shopify-admin-agentic-llms-txt 搭配使用，让爬虫还能获取一个引导性的摘要。