shopify-blog-seo-optimizer

Shopify 博客 SEO 优化器

这是一个 Admin 写入技能，支持预览、内容审查、研究和写入后验证。

商家体验

1. 安装此技能，并配置一个私有的 skill-hub.env 文件。
2. 运行连接检查。此技能会报告商店、连接模式、已授予的权限范围和下一步操作。
3. 提供文章 URL、确切标题或文章 ID。此技能会在审查前确认匹配的文章。
4. Agent 会审查当前内容、调查敏感或事实性声明，并创建候选 HTML 版本。
5. Agent 会生成一份独立的 HTML 报告，其中包含审查结果、变更摘要、E-E-A-T 证据、审批材料包和响应式店面预览。
6. 商家审阅报告，并明确批准或拒绝建议修改的字段。
7. 只有在获得批准后，此技能才会调用 articleUpdate；随后重新读取文章，并验证语义标记、链接和 HTML 安全性。

商家无需手动编写 audit-plan.json 或访问令牌。Agent 负责候选内容和报告数据；确定性辅助工具负责验证和呈现。

必需参考资料

• 首次运行对话和连接边界，请阅读 references/onboarding-guide.md。
• 确定性检查和严重程度规则，请阅读 references/audit-checklist.md。
• 对事实性和敏感声明进行评分或修改前，请阅读 references/eeat-methodology.md。
• 创建候选内容或审批材料前，请阅读 references/report-schema.md。
• 呈现合并后的 HTML 报告前，请阅读 references/storefront-preview.md。

连接错误

仅在请求失败后执行；保留已选的访问方式。

• 网络错误（fetch failed、ETIMEDOUT、ECONNRESET、ENETUNREACH）：切勿猜测代理端口。如果运行时已配置使用获准的代理，请重试一次；否则，请商家为此进程开放代理。
• 407：在运行时密钥存储中修复代理凭据；切勿在聊天中粘贴凭据。
• CLI_NOT_FOUND / ENOENT：解决已配置的 CLI 入口或平台命令问题；这是启动器错误。
• 401/403 / invalid_client：检查商店、凭据和应用安装情况。
• SCOPE_UPDATE_REQUIRED：显示缺少的权限范围，获取批准，在 Shopify 中批准，刷新令牌，然后重试。
• shop_not_permitted：使用获准访问此商店的应用；不要反复尝试。GraphQL 错误：修正查询或输入；不要盲目重试。
• 仅在此路径失败且用户同意后，才建议改用其他访问方式。

安装并首次连接

从公共源安装：

npx skills add lvsao/shopify-skill-hub --skill shopify-blog-seo-optimizer

在用户的工作目录中创建私有配置：

node <absolute-path-to-skill>/scripts/shopify-blog-seo-admin.mjs init-env --method shopify_cli_oauth --env skill-hub.env

快速模式会打开 Shopify 浏览器授权，只需要店铺地址。若要直接访问 Dev App，请选择 dev_dashboard_client_credentials 并填写以下私有值：

SKILL_HUB_SHOPIFY_ACCESS_METHOD=dev_dashboard_client_credentials
SKILL_HUB_SHOPIFY_STORE_DOMAIN=<store>.myshopify.com
SKILL_HUB_SHOPIFY_CLIENT_ID=<private-client-id>
SKILL_HUB_SHOPIFY_CLIENT_SECRET=<private-client-secret>

应用必须安装在目标店铺中，并具有最低限度的内容权限范围组合：read_content 加 write_content，或文档中提到的替代组合 read_online_store_pages 加 write_online_store_pages。直接连接器会在内存中用客户端凭据换取短期令牌，绝不会将其写入文件或报告。如果没有直接凭据，请选择 shopify_cli_oauth，并按照 CLI 授权提示操作。

如果直接模式任务需要更多权限范围，请按照 references/onboarding-guide.md 中的双重同意权限升级流程操作。在初次 Dev Dashboard 入门设置期间配置可选的 Automation Token，获批的未来版本即可在无需收集另一项凭据的情况下运行；该令牌不会授予店铺同意。商家仍必须在 Shopify 管理后台中打开已安装的应用，并批准待处理的权限更新，然后 Agent 才会刷新令牌并重试。

在将文章交给技能之前，先运行连接检查：

node <absolute-path-to-skill>/scripts/shopify-blog-seo-admin.mjs connection-check --env skill-hub.env

如果连接检查报告缺少读取权限范围，请勿继续。若缺少写入权限范围，技能可以继续执行审核并生成报告，但在权限更新获批之前，必须停止，不得执行已批准的写入操作。

目标选择

必须且只能接受以下一种参数：

• --url <public Shopify article URL>
• --title <exact or close article title>
• --article-id <gid://shopify/Article/...>

确认匹配的标题、句柄、博客、文章 ID、发布状态、作者、更新日期和店面 URL。绝不要默默选择第一个相近结果。公共 URL 仅用于定位；Admin GraphQL 才是事实来源。

审核与候选内容工作流

使用辅助工具执行确定性检索和检查：

node <absolute-path-to-skill>/scripts/shopify-blog-seo-admin.mjs find --env skill-hub.env --url <article-url>
node <absolute-path-to-skill>/scripts/shopify-blog-seo-admin.mjs audit --env skill-hub.env --article-id <article-gid> --output audit.json

阅读 references/audit-checklist.md 和 references/eeat-methodology.md。随后，Agent 会创建 candidate.json，其中包含原始文章身份信息、候选 body 和可选的 summary、通俗易懂的 changes 列表、研究来源、E-E-A-T 发现，以及准确的 updates 数据包。以 references/report-schema.md 为准。

生成整合报告，无需商家整理中间计划：

node <absolute-path-to-skill>/scripts/shopify-blog-seo-admin.mjs report --audit audit.json --candidate candidate.json --output shopify-blog-seo-report.html --lang zh-CN

报告必须包含：

• 带有严重程度和证据的确定性审核结果；
• 通俗易懂的更改前后对比；
• 研究来源、E-E-A-T 证据、置信度和未解决的问题；
• 准确的拟议 Shopify 字段以及有意保持不变的字段；
• Preview only — not published 标记；
• 支持响应式布局的候选文章预览，包含可点击的目录和可用的 FAQ 展开项；
• 仅当实时页面可访问时使用 real-storefront-reference，否则使用 theme-like-fallback 并说明访问原因。
• 按以下顺序确定报告语言：明确请求、最新的报告请求／当前对话；并传入 --lang en 或 --lang zh-CN。不要使用店面区域设置来选择报告文案。

安全的优化范围

默认低风险的更改包括稳定的标题 ID、可点击的目录、有证据支持的实用常见问题解答／HowTo 内容、清晰易读的标题和列表、拼写和语法修正、清理空元素、修复已验证的链接、符合上下文的图片替代文本，以及在当前摘要为空时添加简洁的摘要。

凭据、第一手经验、作者资质、专家审核、客户证据、新事实声明、受监管或与安全相关的建议，以及会改变文章含义的更改，都需要商家提供信息。不得编造 E-E-A-T 证据。

除非商家明确扩大范围，否则不得更改 handle、发布状态、作者、标签、图片、主题文件或 metafields。不得在文章正文 HTML 中放入脚本、JSON-LD、JavaScript、表单、iframe、事件处理程序或隐藏的关键词区块。如果 Article API 无法直接编辑 meta 标题、meta 描述、canonical、robots、Open Graph 和 JSON-LD，请单独审核这些内容。

审批和写入

报告 candidate.json 中的确切字段。始终可以进行试运行：

node <absolute-path-to-skill>/scripts/shopify-blog-seo-admin.mjs apply --env skill-hub.env --input candidate.json

商家明确批准合并报告后，创建一个包含 approved: true（或 approval.confirmed: true）的已批准计划并执行：

node <absolute-path-to-skill>/scripts/shopify-blog-seo-admin.mjs apply --env skill-hub.env --input approved-plan.json --execute
node <absolute-path-to-skill>/scripts/shopify-blog-seo-admin.mjs verify --env skill-hub.env --article-id <article-gid>

此辅助工具仅写入 body 和 summary，检查 userErrors，并拒绝在没有明确审批标记的情况下使用 --execute。之后请比较语义标记，而非逐字节比较 HTML，因为 Shopify 可能会规范化标记。

确定性验证

提交或更新 Hermes PR 前，运行无网络回归测试套件：

node --test <absolute-path-to-skill>/tests/test-shopify-blog-seo-optimizer.mjs

该套件涵盖报告 CSP 和不可信 HTML 处理、公共 URL 验证、拒绝指向私有范围的 DNS 解析结果，以及仅用于预览的报告路径。无需 Shopify 商店、凭据或安装软件包。

故障处理

• ARTICLE_NOT_FOUND：显示候选项，或询问是否使用其他定位信息。
• SCOPE_UPDATE_REQUIRED：显示确切缺失的范围类别，并在写入前停止。
• shop_not_permitted：说明直接使用客户端凭据仅适用于符合条件的已安装商店；提供 CLI OAuth 备用方案。
• 受密码保护或遭屏蔽的店面：使用明确标注的类似主题的备用方案生成报告；绝不可声称已验证真实前端。
• 研究结果不确定：保留原始说法，标记为待审核，不得捏造权威依据。