url-redirect-audit

用途

该技能用于查询 Shopify 店铺中的全部 URL 重定向，并识别以下问题：

重定向链：某个重定向的目标本身又被另一个重定向指向（A→B→C）。重定向链会增加额外的 HTTP 往返延迟，并损害 SEO。
重复目标：多个来源路径指向同一个目标地址。
孤立重定向：指向不存在页面的重定向。

该技能为只读操作，不执行任何变更。

主要能力

通过 GraphQL 操作 urlRedirects 分页查询所有重定向，每页 250 条，直到 hasNextPage 为 false。
构建 fromPath → target 路径映射。
检测重定向链：对每个重定向，检查其 target 是否出现在其他重定向的 fromPath 中。
检测重复目标：统计指向同一目标的来源路径是否多于一个。
输出人类可读摘要或 JSON 格式结果，并生成 CSV 审计文件。

使用方式

前置条件：

已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_content
API 权限范围：read_content

参数：

store（字符串，必填）：店铺域名，例如 mystore.myshopify.com。
format（字符串，可选，默认 human）：输出格式，human 或 json。

工作流程：

执行 OPERATION：urlRedirects 查询，输入 first: 250 与分页游标，输出包含 fromPath、target 的全部重定向，分页直到 hasNextPage: false。
构建路径映射：fromPath → target。
检测链：对每个重定向，检查其 target 是否作为其他重定向的 fromPath 出现。
检测重复：目标被多个来源路径指向的情况。

GraphQL 操作（已针对 api_version 2025-01 验证）：

query URLRedirects($after: String) {
  urlRedirects(first: 250, after: $after) {
    edges {
      node {
        id
        path
        target
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

会话跟踪：技能要求在开始、每步之后和完成时输出指定格式的状态信息。开始输出包含技能名、店铺域名和开始时间的方框；每步输出 [N/TOTAL] 操作名、参数摘要和结果；完成时按 format 输出摘要。

human 格式完成输出示例：

══════════════════════════════════════════════
URL REDIRECT AUDIT
  Total redirects:    <n>
  Redirect chains:    <n>
  Duplicate targets:  <n>

  Chains:
    /old-page → /intermediate → /final
  Duplicates:
    /path-a → /product/x
    /path-b → /product/x  (same target)
  Output: redirect_audit_<date>.csv
══════════════════════════════════════════════

json 格式完成输出示例：

{
  "skill": "url-redirect-audit",
  "store": "<domain>",
  "total_redirects": 0,
  "chains": 0,
  "duplicate_targets": 0,
  "output_file": "redirect_audit_<date>.csv"
}

输出文件：CSV 文件 redirect_audit_<YYYY-MM-DD>.csv，列包括 redirect_id、from_path、target、issue_type、chain_path。

适用场景

在每次重大店铺迁移或产品/集合结构调整导致 URL 批量变更后运行。
需要检查重定向链、重复目标和孤立重定向以改善 SEO 与访问延迟时。

限制与安全

只读技能，不执行任何变更，可随时安全运行。
错误处理：THROTTLED（API 速率限制超出）时等待 2 秒并最多重试 3 次；无重定向（新店铺或干净设置）时以 ✅ 无重定向找到退出。
修复链或删除重复项后，需使用 Shopify 后台 → 导航 → URL 重定向进行更正。Admin API 不支持批量删除，但可通过 urlRedirectDelete 变更删除单个重定向。
该技能依赖已认证的 Shopify CLI 会话与 read_content 权限。

技能介绍

用途

主要能力

使用方式

适用场景

限制与安全