站点可发现性与性能设计

本设计覆盖公开首页和双语文档元数据，在不改变产品定位、托管方式、应用行为或文档内容的前提下，改善页面体验和语言版本发现。

当前实现与已验证缺口

站点是由 GitHub Pages 发布的静态 HTML。首页已有规范 URL、说明、Open Graph 和 Twitter 卡片、 SoftwareSourceCode JSON-LD、robots.txt、sitemap.xml 和 llms.txt。文档页已有绝对规范链接及配对的中英文文件。

历史移动端 Lighthouse 对 https://openprogram.io/ 的 2026-08-13 测量得分为性能 92、无障碍 95、最佳实践 100、SEO 100。其图像、对比度、复制按钮和传输发现保留为测量基线。当前文档构建为发现的中英文配对生成互相对应的 hreflang 链接；无配对页面有意不输出替代语言链接。

参考资料与比较

参考建议行为当前状态决策
Google Search：本地化版本每个本地化页面通过完整绝对 URL 和互相对应的 hreflang 标注链接自身及全部替代版本。文档模板已对发现的中英文配对实现。保持扫描器与模板的配对发现逻辑同步。
web.dev：优化 LCP让初始 HTML 可发现 LCP 资源，避免懒加载，并对可能成为 LCP 的图像使用 fetchpriority="high" 。图像可发现且立即加载，但未提示优先级。采用一张高优先级主视觉图。
web.dev：响应式图像按实际渲染尺寸提供图像，并在适用时采用现代格式。一张宽 3024 像素、446 KiB 的 PNG 在桌面约渲染为 905 像素宽，移动端审计约为 517 像素。首页使用专用 800 像素 AVIF，保留原文档资源。
Google Search：SoftwareApplication 数据软件富媒体搜索结果要求应用专用属性及真实报价/评分数据。当前 SoftwareSourceCode 数据准确描述框架和源码仓库。不为获得富媒体结果资格而修改类型；当前不存在评分或商业报价数据。
Google Search：面包屑数据包含至少两个有序条目的 BreadcrumbList 可以描述典型可见导航路径。文档页显示面包屑和文档根链接，但未输出对应结构化数据。采用“文档根 → 当前页”两级路径，文档根页自身不输出。

目标行为与边界

失败与兼容行为

构建仅依据文档扫描器已发现的页面配对生成替代版本。URL 与规范链接使用相同站点源和部署前缀，避免相对或跨源标注。无配对时，页面仍有效并保留规范链接，但没有 hreflang。面包屑 JSON 由 Python 标准库序列化，并转义左尖括号，防止页面标题终止 script 元素。文档及现有链接仍可使用 PNG 资源。

验收标准

  1. python -m scripts.docs_site.check_landing 先拒绝旧首页标记和旧双语构建，再通过最终候选。
  2. python -m scripts.docs_site.build 和 python -m scripts.docs_site.checklinks 通过。
  3. 优化后的主视觉显著小于现有 PNG，且具备声明的固有尺寸。
  4. 新的移动端 Lighthouse 在未声明尺寸图像、颜色对比度、标签内容与名称不匹配、图像传输和 LCP 发现方面无失败；SEO 和最佳实践保持 100。
  5. 完整仓库 CI 在已审查提交上通过，该提交包含于 origin/main，且部署页面重现已验证标记。
  6. 生成的文档根不包含 BreadcrumbList；每个规范内容页恰有一条有效双条目路径，根为 https://openprogram.io/docs/.
  7. 首页提供一个 application/atom+xml 替代链接，指向 https://github.com/fzkuji-neo/OpenProgram/releases.atom.

实现证据