把 Amazon Listing 质检做成 Codex Skill：GitHub 开源，5 分钟跑出中文诊断报告

GitHub：dreambird25/amazon-listing-doctor
关键词：Codex Skill、Amazon Listing、SP-API、ERP、Evidence Policy、Agent 隔离

做 Amazon 运营的人，通常都遇到过这类问题：

• 标题和五点看起来“没问题”，但没有统一的质量标准；
• Amazon 后台报错、本地规则提示和 AI 优化建议混在一起；
• 让大模型批量改 Listing，担心它补写不存在的材质、尺寸或功能；
• 换一个模型或开启一段新对话，判断口径又变了。

我最早是在卖家精灵公众号看到一个开源的 Listing 质检 Skill。它证明了一个方向：与其每次重新写 Prompt，不如把检查流程、规则和脚本封装成可以复用的 Skill。

但原项目的取数流程更适合卖家精灵数据，无法直接读取我们自有店铺的 Seller Listing 和 ERP 数据。因此我在保留 MIT 来源与 Git 历史的基础上，重构出了一个证据优先、可接 ERP、支持中文报告的版本。

如果你也想给自己的 Amazon Listing 做批量质检，可以直接从 GitHub 克隆使用。

先看最终输出

普通用户不需要阅读机器状态码，默认报告会直接给出：

站点：美国站
ASIN：示例商品

Listing 内容质量：7.4 / 10
结论：需要优化

主要原因：标题堆叠多个使用场景，核心产品信息不够突出。
下一步行动：保留已经确认的商品事实，重新组织标题表达顺序。

原始值：当前 Listing 标题
候选值：暂未生成（缺少经过确认的产品事实）

Amazon 官方状态：尚未完成官方校验

这里故意把两件事分开：

1. 内容质量：文案是否清晰、完整、一致，属于内部评价；
2. 官方证据：Amazon 当前是否存在错误、候选预检是否通过，必须有绑定证据。

内部 10 分制不是 Amazon 官方评分，也不预测排名、流量和销量。

5 分钟快速上手

方式一：克隆仓库，在 Codex 中直接使用

git clone https://github.com/dreambird25/amazon-listing-doctor.git
cd amazon-listing-doctor
codex

进入 Codex 后输入：

$amazon-listing-doctor 检查 .agents/skills/amazon-listing-doctor/examples/listing-valid.json，
使用中文简洁报告，分别给出内容质量、官方证据、主要原因和下一步行动。

Skill 位于：

.agents/skills/amazon-listing-doctor/

Codex 会从仓库的 .agents/skills 目录发现它。OpenAI 官方文档也说明，Skill 是由 SKILL.md、可选脚本和参考资料组成的可复用工作流，既可以显式 $skill-name 调用，也可以按 description 自动匹配。详见 Build skills。

方式二：安装为个人 Skill

在 Codex 中调用：

$skill-installer

要求它从以下目录安装：

https://github.com/dreambird25/amazon-listing-doctor/tree/main/.agents/skills/amazon-listing-doctor

安装后，其他项目也可以通过 $amazon-listing-doctor 调用。

方式三：只运行确定性 Python CLI

如果暂时不需要 AI 语义分析，可以直接运行：

python scripts/diagnose_listing.py \
  --file .agents/skills/amazon-listing-doctor/examples/listing-valid.json

这部分只使用 Python 标准库，不联网、不写业务数据，也不需要 OpenAI API Key。

它与普通 Listing Prompt 有什么不同

我没有把它做成一段更长的 Prompt，而是把容易出错的部分拆成了明确边界。

普通 Prompt 常见问题	这个 Skill 的处理方式
Amazon 错误和 AI 建议混在一起	官方证据与内容质量双通道输出
缺数据时仍然强行给结论	输出“未评估”，不把未知当成通过或问题
只凭 ASIN 判断 Seller Listing	使用站点、Seller SKU、Seller 和时间范围绑定证据
模型自行补写商品卖点	候选值只能使用已经绑定的产品事实
批量商品互相污染上下文	每个商品使用新鲜、隔离的短上下文分析
分数随模型自由变化	固定评级映射，由确定性脚本计算分数

核心原则可以概括为一句话：

先确认一条证据能够证明什么，再决定系统允许输出什么结论。

整体架构

文件 / Excel / CSV / SP-API / ERP
                 │
                 ▼
        归一化 Listing JSON
                 │
       ┌─────────┴─────────┐
       ▼                   ▼
确定性官方证据诊断     隔离式七维语义评估
       │                   │
       └─────────┬─────────┘
                 ▼
        Hash 与 Evidence 校验
                 │
                 ▼
      中文简洁报告 / 详细审计报告

模型负责理解内容，Python 负责验证证据、派生状态和计算分数。即使以后更换模型，官方门禁、证据绑定和评分公式也不会随意漂移。

Skill 是如何创建出来的

1. 先把任务收窄

这个 Skill 只负责：

对用户提供的 Amazon Listing 证据进行只读诊断，分别输出官方状态和内容优化建议。

它不会执行真实 PATCH、Feed 提交、生产数据库写入或自动发布，也不会承诺提升排名和销量。

2. 使用标准 Skill 目录

.agents/skills/amazon-listing-doctor/
├── SKILL.md          # 触发条件、执行步骤和安全边界
├── scripts/          # 确定性诊断、合并、渲染和批量回归
├── references/       # 报告契约、证据模型和接入规范
├── examples/         # 合成与占位测试数据
├── i18n/             # 中英文展示映射
└── agents/openai.yaml

SKILL.md 保留每次都需要执行的主流程，详细规则按需放在 references/。这种渐进式加载可以避免一个 Skill 把大量无关资料一次性塞进上下文。

3. 把确定性判断交给脚本

以下工作不应该依赖模型自由发挥：

• Payload SHA-256 与请求指纹校验；
• Seller、Marketplace、SKU 和 Product Type 范围匹配；
• Amazon issue severity 映射；
• 长度、字节数和数组数量约束；
• 证据字段路径与值 Hash 校验；
• 固定评分公式和中文状态映射。

内容质量由 Agent 进行七维判断，再由 merge_report.py 验证证据绑定；不满足契约的语义结果不能进入正式报告。

4. 让候选文案有事实边界

系统不会因为用户说“帮我优化标题”，就自动加入没有证据的材质、容量或适用场景。

精确候选使用 fact_bindings + suggested_template：每个事实都要绑定原始字段和值 Hash。无法验证时，报告直接显示“暂未生成候选值”。

这可能没有自由改写那么惊艳，但更适合真实商品数据。

100 个真实产品的批量实践

我在公司 dev 环境中，只读选择了 100 个近 30 天观察到销量的北美和欧洲站产品：

站点	样本数
美国站	75
德国站	15
英国站	10

每个商品分别交给一个全新隔离子代理，只接触一个规范化样本。最终结果为：

• 100/100 重复诊断与合并结果一致；
• 0 个引擎系统异常；
• 96 个商品获得内部评分，平均 5.95 分；
• 15 个商品存在当前官方阻断证据；
• 100 个图片维度均未强行评价，因为只有 URL、没有真实画面观察；
• 0 个商品自动生成候选文案，因为缺少经过人工确认的事实绑定。

这组数据证明批量取数、隔离分析、确定性合并和 Excel 报告链路可以跑通；它不能证明模型评级准确率。准确率还需要运营人员建立私有 Golden Set 进行校准。

真实 ASIN、SKU、账号、接口响应和商品原文都没有提交到公共仓库。公开仓库只保留规则、占位示例和脱敏回归测试。

如何接入自己的数据

这个 Skill 支持多种数据来源，但公共仓库不会替你保存 SP-API 凭据或登录 Seller Central。

只有标题、五点和描述

可以进行内容质量评估；官方证据部分会明确显示未评估。

Excel 或 CSV

让 Agent 先把列映射为公共 JSON 契约，再运行诊断。不要假设任意表格都能直接作为官方证据。

SP-API 或 ERP

在自己的私有适配器中只读获取 Listings Items、Catalog Items、PTD 或 Validation Preview，再归一化为公共输入。凭据、内部接口、表结构和真实商品数据继续留在私有环境。

这种设计让公共 Skill 可以持续升级，同时不会把公司的数据层公开出去。

当前边界

v1.5.5 适合：

• 单个或批量 Listing 人工质检；
• 中文运营报告；
• ERP 发布前辅助复核；
• 自动阻止已经正确绑定的 Amazon 官方错误；
• 作为自己构建领域 Skill 的参考实现。

暂不适合：

• 无人值守自动放行或自动发布；
• 把内部内容分数当成 Amazon 官方分数；
• 只输入 ASIN 就推断卖家贡献和后台问题；
• 没有查看图片画面就评价图片质量；
• 把 AI 候选文案未经人工确认直接提交。

写在最后

可靠的 Skill 不是一段“更聪明的 Prompt”，而是一套可以反复执行、检查和复用的工作流：

固定输入输出
→ 确定性脚本承接硬规则
→ 模型处理语义判断
→ 每条结论绑定证据
→ 私有数据留在仓库外
→ 通过真实样本持续校准

如果你正在做 Amazon Listing 运营、SP-API、跨境 ERP，或者想学习如何把领域经验封装成 Codex Skill，可以直接克隆项目跑一下示例。

项目地址：https://github.com/dreambird25/amazon-listing-doctor

如果这个方向对你有帮助，欢迎 Star、Fork，或者提交 Issue 分享你的输入格式和使用场景。后续会继续完善真实样本校准、Excel 批量报告和 ERP 适配规范。

---

参考资料：

• OpenAI 官方：Build skills
• Amazon Listing Doctor GitHub