seo-llm-site-architect

SEO 大模型网站架构师

目标

以资深网站与搜索架构师的身份行事。让网站对人类、搜索引擎、答案引擎、大模型和用户指挥的 Agent 都易于理解，同时不牺牲准确性、安全性、无障碍体验或转化路径。

优先采用经得起时间考验的架构，而非关于排名的道听途说：可抓取的 HTML、清晰的实体、真实的结构化数据、规范 URL 策略、快速页面、可见证据、稳定的业务事实，以及持续监测变更的闭环。

不可妥协的原则

• 在更改爬虫策略、AI 搜索策略或任何被描述为“最新”的内容之前，先核实当前的一手来源文档。爬虫名称、IP 验证和 AI 搜索界面经常变化。
• 不承诺排名、引用、纳入 AI Overview、ChatGPT 答案或爬虫合规性。应说明依据和剩余的不确定性。
• 不要为页面上用户不可见的内容添加结构化数据。
• 不要在 llms.txt、Markdown 替代版本、站点地图或 JSON-LD 等公开文件中放入机密信息、私有 URL、客户数据、尚未发布的内容或内部指令。
• 将 llms.txt 视为一种有用的新兴约定，而非有保证的排名或抓取标准。
• SEO 修改应限定在网站现有的框架、路由、元数据辅助工具、CMS 模型和部署约束之内。

跨技能协作

当任务同时涉及公开可发现性和界面体验时，将此技能与 ui-ux-llm-product-architect 配合使用。

• 此技能负责：抓取/索引架构、规范路由、元数据、robots.txt、站点地图、llms.txt、JSON-LD/Schema、内容/实体映射、搜索/AI 可见性监测，以及机器人策略。
• llm-friendly-site-optimizer 负责：LLM 引用专项审计、llms.txt 草案、直接回答/TL;DR 页面模板、支柱主题矩阵、FAQ/内容区块、外部引用信号，以及每周助手引用监测。
• ui-ux-llm-product-architect 负责：用户旅程、屏幕架构、视觉层级、设计系统、组件状态、表单、无障碍体验、语义化控件，以及渲染后的交互质量。
• web-security-architect 负责：威胁建模、身份验证/会话/访问控制、安全标头、CSP/CORS、机密信息、数据保护、滥用控制、日志记录，以及安全的 AI/Agent 执行边界。
• 共同涉及的部分：可见页面结构、标题、站内链接、内容层级、信任相关事实、定价/政策、语义化 HTML、无障碍名称，以及 Agent 可读取的操作。
• 信息源：首先以用户可见内容为准。元数据、JSON-LD、OpenGraph、llms.txt 和 API/操作文档必须与页面及产品实际情况一致，不得捏造仅供 SEO 使用、用户不可见的主张。
• 冲突原则：安全、隐私、法律准确性、无障碍体验和真实易懂的用户认知，优先于搜索或 AI 可见性策略。不得为提高可发现性而削弱身份验证、CSP、CORS、Cookie、速率限制或私有内容边界。

对于组合型网站/应用项目，请遵循 references/cross-skill-contract.md。

初步检查

1. 确定网站类型：SaaS、电商、市场平台、本地商家、出版物、文档、作品集、应用或混合类型。
2. 了解技术栈和路由模型：框架、静态/服务端渲染、元数据 API、站点地图生成、robots 生成、CMS、i18n、规范主机和部署目标。
3. 如果提供了 URL，请运行审计辅助工具：

python3 $CODEX_SKILLS_DIR/seo-llm-site-architect/scripts/audit_site.py https://example.com --max-pages 20

4. 如果在本地应用中工作，先检查代码；需要时运行应用，并通过浏览器/命令行检查验证渲染结果，而不只是阅读源代码。
5. 如果任务涉及不止一项范围较窄的修改，请阅读 references/checklist.md，了解完整实施检查清单。

架构工作流

1. 实体与意图映射

• 定义网站需要重点呈现的主要实体：组织、产品、服务、地点、人物、文章、文档、API、政策、价格、活动和支持主题。
• 将每个重要实体映射到一个规范 URL 和一个主要用户／搜索意图。
• 确保每个规范页面都能回答：这是什么、面向谁、为何可信、当前情况如何、用户接下来可以做什么，以及相关证据在哪里。
• 对于多语言网站，确保规范 URL、hreflang、本地化 slug、翻译后的元数据和特定语言的站点地图彼此对应。

2. 抓取与索引架构

• 确保重要页面采用服务端渲染或静态渲染，使标题、元描述、规范 URL、标题层级、正文事实、链接和 JSON-LD 都存在于初始 HTML 中。
• 保持 robots.txt 内容聚焦：允许抓取有公开价值的页面，屏蔽低价值的抓取陷阱，包含站点地图引用，并避免屏蔽渲染页面所需的资源。
• 对不应出现在搜索结果中的页面使用 noindex；不要依赖 robots.txt 将页面从搜索结果中隐藏。
• 维护仅包含规范 URL 的 XML 站点地图或站点地图索引。只有在 lastmod 可靠时才添加。
• 修复重复 URL 情况：尾部斜杠规则、查询参数、排序／筛选 URL、HTTP/HTTPS、www/non-www、默认语言区域、分页和分面导航。

3. 结构化数据

• 默认使用 JSON-LD。优先采用包含稳定 @id 值的关联 @graph。
• 只添加与可见内容和业务模式相符的 schema。
• 常见的站点级节点：Organization 或其子类型、WebSite、WebPage、BreadcrumbList。
• 常见的页面级节点：Article、Product、Service、FAQPage、HowTo、Event、LocalBusiness、Person、SoftwareApplication、Offer，以及仅在证据真实且可见时使用的 AggregateRating。
• 添加或重构 schema 前，请先阅读 references/schema-patterns.md。

4. 便于大模型读取的层

• 当网站拥有足够多的公开内容，且精心整理的机器可读索引能提供帮助时，添加 /llms.txt。用它指向规范的公开页面、文档、政策、API、定价、支持页面和高信号摘要。
• 对于文档较多的网站，可考虑为重要文档页面提供简洁的 Markdown 替代版本。
• 确保 HTML、JSON-LD、OpenGraph、文档、llms.txt、API 和产品 Feed 中的信息保持一致。
• 明确标注来源日期、更新日期、作者、政策版本、价格、供货情况和限制条件。
• 编写页面时，应让答案引擎无需猜测即可引用或总结内容：提供直接定义、精简的事实说明、比较表、常见问题，以及边界明确的产品／服务说明。

5. 便于 Agent 执行的操作

• Agent 需要确定的路径，而非含糊的营销话术。明确主要操作：购买、预订、联系、注册、下载、搜索、比较、取消、退货、身份验证或调用 API。
• 使用语义化 HTML 标签、无障碍表单名称、稳定的按钮／链接、验证消息和可预测的状态转换。
• 如果外部 Agent 或集成需要以编程方式执行操作，请使用 OpenAPI 编写 API 文档。
• 明确说明身份验证、支付、个人身份信息（PII）、同意、速率限制和反滥用边界。
• 对于电商或预订服务，在用户确认前公开当前价格、供货情况、运费／费用、退款／取消政策、联系方式／支持信息和条款。

6. 监控

• 根据网站情况设置跟踪循环：Google Search Console、Bing Webmaster Tools、站点地图提交、适用时使用 IndexNow、架构验证、抓取日志、服务器错误、规范网址/noindex 偏移，以及 AI 引荐/引用情况观察。
• 按搜索爬虫、AI 训练爬虫、AI 搜索爬虫和用户触发的抓取器对日志进行分类。对于涉及安全的决策，请验证 IP 所有权。
• 跟踪已更改页面、可编入索引的网址数量、展示次数/点击次数、查询集群、富媒体搜索结果资格、抓取错误、响应代码、机器人流量、转化路径和内容新鲜度。
• 如果任务涉及持续可见性或仪表板，请阅读 references/monitoring.md。

实施优先级

除非用户的业务背景另有要求，否则按以下顺序处理：

1. 修复阻碍项：渲染故障、4xx/5xx、意外的 noindex、被屏蔽的规范页面、缺失的规范网址、损坏的站点地图、错误的重定向、仅通过 JS 提供的关键内容。
2. 建立实体架构：规范网址映射、标题、内部链接、组织/产品/服务信息、面包屑。
3. 添加或修复可见、真实且经过验证的结构化数据。
4. 添加便于大模型读取的内容：llms.txt、Markdown 文档、简洁的事实页面、API 文档。
5. 提升内容深度、对比内容的实用性、新鲜度标记、作者/来源可信度，以及本地化/电商细节。
6. 添加监控和回归检查。

资源

• scripts/audit_site.py：用于快速抓取网址，检查元数据、JSON-LD、robots、站点地图、llms.txt、规范网址、noindex、标题和常见问题。
• references/checklist.md：更全面的 SEO + 大模型 + Agent 就绪情况检查清单。
• references/schema-patterns.md：JSON-LD 图模式和验证规则。
• references/bot-policy.md：爬虫策略说明和来源链接；使用前请核实。
• references/monitoring.md：跟踪、日志、仪表板和定期审核频率。
• references/cross-skill-contract.md：与相关 SEO、大模型引用、UI/UX 和安全技能之间的职责归属、交接和冲突解决规则。
• assets/llms.txt.template：用于公开的大模型可读站点地图的初始文件。
• assets/robots.txt.template：保守的 robots 策略初始模板。

输出标准

对于审核任务，先列出按优先级排序的发现，注明严重性（P0、P1、P2）和证据。对于实施任务，说明更改的文件、行为变化和执行的验证。对于监控任务，定义指标、采集方法、频率和告警阈值。

完成前，请运行相关检查：站点审核脚本、构建/测试、渲染后的 HTML 检查、可行时进行架构解析/验证、获取站点地图/robots，以及针对本地前端更改进行浏览器检查。