Shopify Redirect Mapping 是一个面向 Shopify 店铺的重定向映射技能，目标是把一批失效（404）的旧 URL 转换为指向存活页面的 301 重定向，从而回收搜索权重并挽救流失访客。它不追求完美的 1:1 映射，而是强调“召回优先于精确”：一个相关但非完全正确的重定向优于 404，因为访客落到相近产品或正确分类仍可能转化，而 404 会让访客直接离开；Google 在 301 指向相关页面时会保留部分旧页面权重，404 则完全不保留。
主要能力
技能按 URL 前缀对失效路径分类，并只与同类型的存活库存进行模糊匹配，使用按类型区分的相似度阈值（默认值）：产品 0.85，集合 0.70，博客/页面 0.85，品牌页面解析到集合 0.70。当路径无法达到自身类型阈值时，按跨类型回退顺序处理：产品路径先尝试产品匹配 @0.85，再尝试模糊集合匹配 @0.70，最后进入审核队列；集合路径先尝试集合匹配 @0.70，再进入审核队列。技能明确禁止静默回退到首页（/），因为首页回退看似 100% 覆盖，却会破坏“该 URL 仍需人工关注”的信号，并稀释重定向的主题价值。
输出分为三个桶：auto-apply（已通过类型阈值，默认推送，但仍会人工过目）、review（低置信度匹配、媒体资源如 .jpg/.mp4//assets/、格式错误行以及所有落入队列的路径，由人工设定或确认目标）、skip（最佳目标等于源路径的空操作，源路径会去重，确保一个失效 URL 只产生一个重定向）。
使用方式
技能通过 Admin API 读取库存并写入重定向，提供两种访问通道。通道 A：自定义应用令牌，在 Shopify 后台 Settings → Apps and sales channels → Develop apps 创建应用，授予最小权限范围（read_products、read_content、read_online_store_navigation、write_online_store_navigation），安装后复制 Admin API 访问令牌，并通过环境变量设置：
export SHOPIFY_STORE="your-store.myshopify.com" export SHOPIFY_ACCESS_TOKEN="<your Admin API access token>" # env, not disk
通道 B：Shopify CLI OAuth（不存储令牌），运行 shopify store auth --store $SHOPIFY_STORE --scopes read_products,read_content,read_online_store_navigation,write_online_store_navigation，然后使用 shopify store execute 运行已验证的操作。通道 B 依赖 Shopify CLI，需先运行 shopify version 检查，缺失则安装。为获得完整的 Admin GraphQL schema 和已验证执行，可搭配 Shopify 官方 AI 工具包插件：在 Claude Code 中检查 claude plugin list，若不存在则运行 claude plugin marketplace add Shopify/Shopify-AI-Toolkit 和 claude plugin install shopify-plugin@shopify-ai-toolkit。
操作流程强调非破坏性：写入前先读取存活库存和现有重定向列表，创建前查询现有集合并跳过重复（urlRedirectCreate 对已重定向的源路径会报错）；大规模写入前先导出当前重定向（Matrixify 导出或 urlRedirects 转储）以便回滚；通过 Admin API 而非店面验证写入（店面有 CDN 缓存，不反映新鲜度），写入后重新查询重定向，并用 curl -I 抽查若干旧路径，确认返回 301 及映射的 location。
适用场景与限制
适用于店铺改版、迁移或批量清理 404 的场景，尤其是需要从 Google Search Console 导出 404 列表并批量映射到存活页面时。技能提供的是“配方而非脚本”：references/pipeline.md 中的 GraphQL 和匹配逻辑是可复制改编的起点，代理会针对当前 schema 编写一次性代码、运行后丢弃，以适应 Shopify 每季度的 schema 变更。
限制方面：阈值无法修复字符串几乎相同的规格错配（如 12mm 与 14mm 部件 slug 仅差一个字符，S 码与 XL 码变体几乎相同），模糊匹配会自信地选错，这些需在审核阶段人工剔除。审核预算方面，首次合作预计至少 2–3 轮迭代：运行、审核桶、调整阈值或手工编辑目标、重新运行。一次性完成的重定向映射通常意味着过度追求精确而牺牲了覆盖率。
参考与维护
references/pipeline.md 包含 8 步运行手册：从 GSC 404 导出 → 库存拉取 → 匹配算法规范 → 应用 → 重定向到 404 的腐烂扫描（urlRedirectUpdate）→ curl -I 验证，以及 WordPress URL 模式转换。最后验证日期为 2026-07-05，GraphQL 固定为 Admin API 2025-07，Shopify 按季度滚动弃用版本，使用前应在 shopify.dev 核对 mutation 和 query 名称。只读复核命令示例：
1. List existing redirects (confirms scope + shows current map)
curl -s "https://$SHOPIFY_STORE/admin/api/2025-07/graphql.json"
-H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN"
-H "Content-Type: application/json"
-d '{"query":"{ urlRedirects(first:10){ edges{ node{ path target } } } }"}'
2. Probe an old path and confirm it 301s where you expect
curl -sI "https://$SHOPIFY_STORE/old-path" | grep -iE "^(HTTP|location)"
官方文档参考 Shopify URL redirects 和 Admin GraphQL API；404 导出源为 Google Search Console（Pages → Not found）。这些技能记录的是文档未涵盖的操作经验，并非参考文档的替代品。