用途
commercetools AI Hub 用于把 commercetools 中的商品数据导出为面向多个渠道的商品 Feed。这里的 "AI Hub" 指整个导出流程，而不是某一个渠道。支持的渠道包括：OpenAI Commerce feed（ChatGPT 购物）、OpenAI Ads feed、Google Merchant Center 和 Microsoft Merchant Center。
主要能力
- 按商品选择、分类、商品类型、SKU、商品键、门店品类（store assortment）或查询条件筛选要导出的商品。
- 为每个指定渠道生成一份半成品工作文件：包含每一行、每个渠道字段，commercetools 中没有值的字段留空，并在每行标注缺失的必填字段。
- 业务团队离线补全工作文件后，工具可将补全后的文件原样转换为渠道上传格式。
- 渠道规范不硬编码：build 和 finalize 在运行时读取各渠道发布的规范（字段、必填/条件必填/可选、允许值、长度限制、Microsoft 的补充字段），并与 commercetools 数据到字段的映射代码合并。新增规范字段会成为空列，移除的字段会被丢弃，报告会列出两者。
- 数据完整性：commercetools 是商品数据的唯一来源。不写入、改写、缩短、翻译、摘要或推断商品内容（标题、描述、品牌、GTIN、MPN、分类、颜色、尺寸、状态、库存、价格或图片）。mapping.json 只改变值的读取位置（属性名、分类和 Store 字段、id 策略）以及现有值对渠道的拼写方式（valueMaps、单位、分隔符），本身不持有值。
- Feed 资格标志是商家设置而非商品数据，默认值：discovery 开启（is_eligible_search=true）、checkout 关闭（is_eligible_checkout=false），仅 OpenAI Ads feed 的 is_ads_eligible=true。商品属性可覆盖这些默认值。Google 和 Microsoft 没有 checkout 标志，其商品默认用于 discovery。
- Storefront URL、卖家名称和政策 URL（隐私、条款、退款）来自通过 --store 传入的 Store。
使用方式
工具链为 scripts/aihub_feeds.py（Python 3.9+，仅标准库）。运行 aihub_feeds.py <command> --help 查看选项。网络仅用于下载和读取渠道当前规范；规范按运行缓存，因此重建和 finalize 可离线进行。
使用 python3 scripts/aihub_feeds.py 运行（Windows 上用 py -3，因为 python3 常缺失或为 Microsoft Store 存根）。若找不到 Python 3.9+，应告知用户从 python.org 安装并停止，不要用其他语言重写脚本。
工作流：
- 文档搜索（必需，首先运行）：首次在会话中使用此技能时，必须先运行 docs-search.mjs 脚本，收集最新验证文档作为主要依据。
- 确认选择和市场：收集凭据（含 CTP_* 变量的 dotenv 文件，用 --env-file 传入，绝不打印或复制密钥值）、Store、货币、国家、分销渠道、locale。aihub_feeds.py fetch --list-stores 可打印项目的货币、国家、语言、渠道以及每个 Store 的语言、国家、渠道键、商品选择和 storefront 字段。
- 筛选：商品选择、分类、商品类型、SKU、商品键、属性条件（--attribute color=blue）、查询谓词（--where）、搜索过滤器（--search-filter）的任意组合。--list-categories 和 --list-attribute 可将用户措辞映射到键。
- 渠道：由用户指定；若请求未说明则询问。build 需要 --vendors（openai、openai-ads、google、microsoft）。
- 解析后下载：先运行 aihub_feeds.py fetch --dry-run，不写入任何内容，显示每个名称解析结果、匹配商品数、抽样检查是否在 Store 品类中、检查 feed locale 与数据是否一致。用户确认后运行下载。
- 构建工作文件：aihub_feeds.py build --run <run> --vendors <named vendors> 为每个请求的渠道写一份工作文件，以及 report/gap-report.md、report/issues.csv 和 NEXT-STEPS.md。首次 build 写入 <run>/mapping.json。
- 与用户审查缺口：报告每个渠道哪些必填字段已填、哪些缺失（附示例 SKU），以及规范条件可能适用的 ⚠? 字段。缺口分为映射缺口（值在 commercetools 中以其他名称存在，可指向 attributes.、store.、categoryFields 或添加 valueMaps 条目）和 commercetools 没有的值（在工作文件中留空，标记在 _missing_required）。
- 移交工作文件：指向 working/ 和 NEXT-STEPS.md，说明如何安全编辑文件（以文本导入以保持 GTIN 和 SKU 形式，保留表头行）以及每个辅助列的含义。
- Finalize 补全文件：用户交回补全文件后，运行 aihub_feeds.py finalize --vendor <v> --input <file> --out <dir>（Google 和 Microsoft：--kind supplemental|primary，可选 --columns）。将 finalize 报告作为事实报告：行数、仍缺失或无效的必填字段、补充列中的空单元格、渠道不接受的列。然后给出该渠道的上传指南。不要替用户决定是否上传。
适用场景
- 需要将 commercetools 商品数据导出为 OpenAI Commerce feed、OpenAI Ads feed、Google Merchant Center 或 Microsoft Merchant Center 格式的商家。
- 需要按商品选择、分类、商品类型、SKU、商品键、门店品类或查询条件筛选商品并生成 Feed 的场景。
- 需要业务团队离线补全缺失字段后再转换为渠道上传格式的工作流。
限制
- 范围外：上传文件、决定是否上传、定期交付（Connect 任务，见 commercetools-connect）、运费和税费设置（在各 merchant center 按账户配置）、修改 commercetools 中的商品数据。
- 不写入、改写、缩短、翻译、摘要或推断商品内容。
- 渠道规范变化频繁，因此运行时读取；若规范页面无法读取，报告会说明使用了哪个回退并链接该页面。
- 补充行仅适用于 id 与主 feed 匹配的商品；SKU 与 key 不匹配不会更新任何内容，也不报告错误。
- 每次上传被视为完整目录；后续上传中缺失的商品最多 14 天后会掉出。
- Microsoft 补充 feed 仅接受 Microsoft 列出的字段（运行时读取；id、title、description、size、color、custom_label_0–4、promotion_ID 当捕获时）；其他字段属于主 feed。
- 价格来自价格选择（货币、国家、渠道）；可用性来自库存，无库存条目时留空。
- OpenAI Ads feed 是广告账户中的独立 feed（有自己的 SFTP），不是商家门户 feed。商品需要 is_ads_eligible=true；ads_metadata 键来自 Ads 设置，绝不虚构。
参考索引
- 凭据、范围、--list-stores、筛选、门店品类、市场上下文、dry run：references/selecting-products.md
- mapping.json、工作文件、finalize、阅读缺口报告：references/mapping-and-files.md
- 运行时渠道规范、各渠道事实、文件格式、上传步骤：references/vendors.md