publication-channel-audit

用途

该技能查询所有活跃商品及其可见的发布渠道（销售渠道），并标记出处于活跃状态但未出现在关键渠道（例如 Online Store、Google Shopping、Meta）上的商品。其目的是防止因商品存在于目录中却在销售渠道上不可见而造成的隐性收入损失。该技能为只读操作，不执行任何变更。

前置条件

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

参数

参数	类型	必填	默认值	说明
store	string	是	—	商店域名（例如 mystore.myshopify.com）
required_channels	array	否	["Online Store"]	所有活跃商品都应发布到的渠道名称
format	string	否	human	输出格式：human 或 json

安全性

只读技能——不执行任何变更。可随时安全运行。

工作流程步骤

操作：publications — 查询
- 输入：first: 50
- 预期输出：所有可用的发布渠道（销售渠道），包含 id、name
操作：products — 查询
- 输入：query: "status:active"、first: 250、select publishedOnCurrentPublication、resourcePublications { publication { name } }、分页游标
- 预期输出：活跃商品及其渠道发布状态
对每个商品：检查其是否出现在每个 required_channels 中——若缺失于任一渠道则标记

GraphQL 操作

# publications:query — validated against api_version 2025-01
query SalesChannels {
  publications(first: 50) {
    edges {
      node {
        id
        name
        supportsFuturePublishing
        app {
          title
        }
      }
    }
  }
}

# products:query — validated against api_version 2025-01
query ProductPublications($after: String) {
  products(first: 250, after: $after, query: "status:active") {
    edges {
      node {
        id
        title
        handle
        status
        resourcePublications(first: 20) {
          edges {
            node {
              publication {
                id
                name
              }
              publishDate
              isPublished
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

会话跟踪

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

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: Publication Channel Audit            ║
║  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>

完成时输出：

对于 format: human（默认）：

══════════════════════════════════════════════
PUBLICATION CHANNEL AUDIT
  Active products:          <n>
  Sales channels found:     <n>
  Products missing channels: <n>

  Missing from "Online Store":
    "<product title>"  (<handle>)
  Output: publication_audit_<date>.csv
══════════════════════════════════════════════

对于 format: json，输出：

{
  "skill": "publication-channel-audit",
  "store": "<domain>",
  "active_products": 0,
  "channels_found": 0,
  "missing_channel_count": 0,
  "output_file": "publication_audit_<date>.csv"
}

输出格式

CSV 文件 publication_audit_<YYYY-MM-DD>.csv，包含列： product_id, title, handle, channel_name, is_published, publish_date, issue

错误处理

错误	原因	恢复方式
THROTTLED	超出 API 速率限制	等待 2 秒，最多重试 3 次
Channel not found	所需渠道未安装或已重命名	在摘要中将该渠道报告为缺失
No active products	目录为空	以 0 结果退出

最佳实践

在任何批量商品导入后运行——商品默认并不总是发布到所有渠道。
对于多渠道商店（Google、Meta、TikTok），将所有关键渠道添加到 required_channels，以捕获缺失于任一渠道的商品。
从某渠道取消发布商品可能是有意为之（例如仅批发商品）——在发布前请先审查被标记的列表。
与 product-data-completeness-score 配合使用——数据完整度得分低的商品应先修复，再发布到其他渠道。