ai-shopping-audit

# 目录准备就绪 **人工智能购物代理真的能读取您的产品页面吗？** 目录准备就绪（CatalogReady）是针对人工智能购物的开源 Lighthouse。指向一个产品页面，即可获得 0-100 的透明度评分，查看机器可以和不能读取的确切产品数据，不受支持的营销声明，以及可以直接粘贴的修复方案。 **离线 · 确定性规则 · 无需 API 密钥 · 永远不会写入您的商店。** ```bash uvx --from catalogready-ai catalogready https://your-store.com/products/example ``` ```text 防水通勤鞋 - 蓝色 目录准备就绪评分：82/100（准备就绪） 产品身份 16/20 提供完整性 20/20 结构化数据 20/20 决策证据 14/15 媒体和变体 2/15 声明基础 10/10 0 个关键问题 · 2 个建议 · 0 个次要问题 完整报告：catalogready-report.html ``` HTML 报告是一个独立的文件：得分表、每个支柱的细分、每个发现都有一个稳定的规则 ID、商家才能回答的问题、根据页面上找到的证据构建的建议的 Product JSON-LD 块，以及可下载的 PNG 得分卡。 ## 为什么存在 ChatGPT 购物、Google AI 结果和 Perplexity 购买流程通过机器而不是眼睛来读取产品页面。对于人类来说，页面看起来很完美，但对于 AI 购物代理来说可能是不可见的或不可信的：缺少稳定的 ID、不完整的报价、缺少 Product JSON-LD 以及没有支持证据的营销声明。 目录准备就绪检查机器检查的内容 - 确定性、本地性和得分经得起审查： - **只有您的页面才能获得积分。** 目录准备就绪生成的内容不为评分做贡献。 - **阻止缺陷限制评分。** 重复 ID、不完整的报价、缺少结构化数据或不受支持的高风险声明会限制数量，无论其他内容多么完整。 - **每个发现都引用证据** 并带有规则 ID，您可以 grep 查找。[docs/RULES.md](docs/RULES.md) 用其来源记录每个规则 - Google 的商家列表要求、OpenAI 的 Agentic Commerce 源规范、Bing 的 Copilot 基础指南以及 OpenAI、Perplexity 和 Anthropic 的已发布爬虫文档。 参见 [docs/scoring-methodology.md](docs/scoring-methodology.md) 以获取完整的评分标准和上限。 ## 安装和运行 ```bash # 一次性（推荐首次尝试） uvx --from catalogready-ai catalogready https://your-store.com/products/example # 或作为 checkout uv sync uv run catalogready audit https://your-store.com/products/example # 完全离线：审核保存的页面而不是获取它 uv run catalogready audit https://your-store.com/products/example saved-page.html # 机器可读输出 uv run catalogready audit <url> [saved.html] --json ``` 获取时只有一个 HTTP GET 请求，审计引擎本身不进行网络调用 - 测试套件在禁用网络的情况下运行。 在不接触网络的情况下尝试捆绑的示例： ```bash uv run catalogready audit https://example.com/products/cr-001 examples/demo-store/index.html uv run catalogready catalog examples/messy-apparel.csv # 得分 51/100，并显示确切的原因 ``` ## 检查内容 | 支柱 | 规则示例 | |---|---| | 产品身份 | 稳定 ID（SKU/GTIN/MPN）、品牌、类别、规范 URL | | 提供完整性 | 价格 + 货币 + 可用性、完整的 Offer 标记 | | 结构化数据 | 产品 JSON-LD 存在、有效、与可见页面一致 | | 决策证据 | 页面上的描述、规格、运输/退货/护理/限制 | | 媒体和变体 | 主要图像、图像数量、变体属性和身份 | | 声明基础 | 最高级、“临床证明”、保修和性能声明根据页面证据进行检查 | 当缺少事实时，目录准备就绪会询问而不是捏造：报告列出商家才能回答的问题，`--answers merchant-answers.json` 继续审核具有验证值的。 ## 交互式代理会话 `catalogready chat` 打开一个类似 Claude Code 的终端会话，绑定代理 - 审核、询问、回答、修复： ```text catalogready> /audit https://your-store.com/products/example ● inspect_product_page — 提取了 3 个证据项 ... ● audit_product — 在 16/100 处测量准备情况并生成了 13 个发现。 目录准备就绪评分：16/100（需要改进） ... [阻止] 价格：当前验证的产品价格是多少？ catalogready> 为什么提供完整性这么低？ 提供完整性：0/20 ✗ 价格 ✗ 货币 ... catalogready> /answers sku=CR-100 price=49.00 currency=AUD availability=in_stock catalogready> /draft 隔离预览验证：16 → 60 (+44)，状态已验证。 catalogready> /report ``` 代理在无法验证的事实时暂停，而不是捏造它们；`/answers` 继续。自由文本问题根据审核结果确定性地回答；设置 `/provider openai`（或 `gemini`、`claude`、`deepseek` - 密钥通过服务器环境变量）用于开放式、模型回答的问题，严格基于审核 JSON。 ## 交互式仪表盘 一个命令为 Web UI 和本地 API 提供服务，位于同一端口并打开您的浏览器： ```bash uv run catalogready dashboard ``` 输入产品网址并点击审核 - 本地服务器为您获取页面（一个请求）。或者粘贴 HTML / 加载内置的好/坏演示以保持完全离线。每次审核都会生成一个纯语言摘要结论、自动生成的修复建议以及隔离的预览验证、可展开的每个支柱的评分解释、内联商家问题、可粘贴的 JSON-LD 补丁、“询问代理”聊天窗口以及可下载的 HTML 报告。UI 跟随您的浏览器语言（英语 / 中文，可在标题中切换）。所有操作都在本地运行；页面从不要求 API 密钥。 ## 与 ChatGPT、Claude、Gemini、Copilot 或 DeepSeek 一起使用 目录准备就绪附带了一个 MCP 服务器，因此您已经使用的 AI 助手可以作为工具审核页面： ```bash claude mcp add catalogready -- uv run catalogready-mcp ``` **[docs/QUICKSTART-AI-ASSISTANTS.md](docs/QUICKSTART-AI-ASSISTANTS.md)** 有 **ChatGPT/Codex**、**Claude** （代码 + 桌面）、**Gemini** （CLI + 企业 A2A）、**Copilot** （VS Code 代理模式）和 **DeepSeek** 的复制粘贴设置 - 涵盖两个方向：助手调用目录准备就绪作为工具，以及每个供应商作为目录准备就绪内的可选自带模型。协议详情：[docs/INTEROPERABILITY.md](docs/INTEROPERABILITY.md)。 ## 比较 | | 目录准备就绪 | Google Rich Results Test | 通用 SEO 爬虫 | AI 复制生成器 | |---|---|---|---|---| | 验证产品模式语法 | ✓ | ✓ | 部分 | ✗ | | 为 AI 购物代理评分完整性 | ✓ | ✗ | ✗ | ✗ | | 检查营销声明与证据 | ✓ | ✗ | ✗ | ✗ | | 离线运行，无帐户，无 API 密钥 | ✓ | ✗ | ✗ | ✗ | | 提供可粘贴的 JSON-LD 修复 | ✓ | ✗ | ✗ | 生成，无基础 | ## 自带模型密钥（可选） 上述所有操作都 **无需密钥**。要启用模型辅助规划、聊天答案和列表草稿，请在服务器的 `.env` 中设置提供商密钥 - 请参阅 [docs/BYO-KEYS.md](docs/BYO-KEYS.md)。密钥从不进入仪表盘、扩展或工具参数。 ## 包装内容 审核引擎是一个供应商中立的服务，具有多个薄表面。这些是次要于页面审核的，并记录在 [docs/ROADMAP.md](docs/ROADMAP.md) 中： - `catalogready catalog feed.csv` - 使用相同的扣除和上限评分进行 CSV 目录审核。 - `catalogready-api` - 具有 OpenAPI 文档和 A2A 代理卡的 HTTP 服务器。 - 铬扩展（`browser-extension/`）- 任何产品页面上的一个点击会捕获渲染的 HTML 并显示评分、发现、商家问题、自动生成的修复和询问代理框。在受机器人保护的商店上运行，因为它读取浏览器渲染的内容。 - 可选的模型辅助列表草稿（OpenAI、Gemini、Claude、DeepSeek）通过服务器环境变量携带自带密钥 - 永远不会在工具参数或浏览器存储中 - 以及具有发布安全上限的确定性声明评估。 ## 保证 - 确定性核心需要无 API 密钥且不进行网络调用。 - 目录准备就绪永远不会写入商店、源或商家系统。 - 它永远不会捏造产品属性、引用或排名。 - 准备情况评分并不是任何 AI 系统排名或引用的承诺 - 任何承诺此类承诺的工具都是在猜测。 ## 贡献 规则提案是最有价值的贡献 - 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 和问题模板。使用 `python -m unittest discover -s tests -v` 运行测试套件；它必须离线通过。 架构和模块设计：[docs/repository-design.md](docs/repository-design.md) · 规则及其来源：[docs/RULES.md](docs/RULES.md) · 评分：[docs/scoring-methodology.md](docs/scoring-methodology.md) · 互操作性：[docs/INTEROPERABILITY.md](docs/INTEROPERABILITY.md) · 路线图：[docs/ROADMAP.md](docs/ROADMAP.md) ## 联系 由 **Vincent Po Li** 构建。问题、修复帮助、合作伙伴或反馈： - 问题/讨论：[github.com/PO-VINCENT/ai-shopping-audit](https://github.com/PO-VINCENT/ai-shopping-audit/issues) - 电子邮件：[vincentli802@hotmail.com](mailto:vincentli802@hotmail.com) - LinkedIn：[vincent-po-li](https://www.linkedin.com/in/vincent-po-li-324291122/) - X：[@Vincent_Po_Li](https://x.com/Vincent_Po_Li) - 小红书 (Xiaohongshu)：`vincent726217` 在 [Apache-2.0](LICENSE) 下许可。