跳转至

EGM 网站和文档

  • 作者: @n3wth
  • 状态: 提议。维护者范围批准待定。
  • 日期: 2026-11-04
  • 范围 Issue: #303。相关工作:#7、#58、#301 和 #302。

概述

使用 Astro Starlight 从 docs/site/ 中的网站 Markdown 发布指南和技能页面。 在整个网站中保持一个共享的页眉、页脚、字体比例和颜色系统。 在无需服务器运行时的情况下提供 Markdown 导出和本地搜索。

现有原型是审查的证据。它不替代设计审批,也不授权生产发布。

问题

当前网站介绍了 EGM,但将大部分说明引导到 GitHub。 读者需要清晰的安装步骤和直达每个技能的路径。 学生、架构师、项目经理和软件工程师需要一种不假设编码工作流程的说明。

默认的草稿和设计审查技能面向软件设计。 自定义审查技能通过显式的审查者和标准选择来支持其他文档。 网站必须解释这一区别,而无需在首页加上密集的免责声明。

Issue #7 提议一个单一指南页面,并排除搜索和多个文档页面。 本提案具有独立范围。Issue #7 和工作示例 Issue #58 需要单独的工作。

目标

  • 发布 /guide、/install、/getting-started、/workflow 和 /skills。
  • 为现有七个技能各发布一个 /skills/<skill-name> 页面。
  • 在 docs/site/skills/ 中为每个技能保留一个页面。每个页面都向使用插件的人解释该技能。
  • 将每个技能页面链接到其规范的 SKILL.md。
  • 将网站指南文本保留在 docs/site/ 中,位于展示组件之外。
  • 在首页和文档之间共享页眉和页脚。
  • 使用现有的 Material Web gBreeze 样式、字体、标记和技能图标。
  • 在两种主题中为正文文本赋予一个共享的颜色角色。
  • 提供键盘可访问的本地搜索和“复制为 Markdown”操作。
  • 将每个文档页面导出为 Markdown,并生成三个 llms.txt 变体。
  • 保留现有的 GitHub Pages 生产部署。

非目标

  • 更改技能执行、审查权限或主机支持。
  • 更改插件清单、类别、策略链接或技能描述。
  • 替换现有的生产同意和分析规则。
  • 添加账户、数据库、远程搜索或 AI 聊天服务。
  • 制作录制的审查示例,或声称虚构的示例是真实审查。
  • 用原型批准替代仓库贡献流程。
  • 添加对另一款 AI 应用程序的支持。

未决问题

  • 维护者必须批准新范围,并将其 Issue 标记为 design-ready。
  • 设计必须合并后,Issue 才能获得 pr-ready 进入实施。
  • PR #302 保留其独立的元数据范围决策。本提案不授予该例外。

关键用户旅程

理解 EGM

  • 给定: 一位读者在之前不了解 EGM 的情况下访问首页。
  • 当: 读者浏览说明和流程示意图。
  • 那么: 读者可以区分上下文感知的作者与独立的审查者。
  • 那么: 读者会看到由人检查发现并决定哪些变更。

安装插件

  • 给定: 读者使用受支持的桌面应用程序或命令行应用程序。
  • 当: 读者打开 /install。
  • 那么: 已发布的 ChatGPT 和 Codex 桌面链接首先出现,并带有其仅限桌面的限制。
  • 那么: 单独的章节介绍 Claude Cowork 和现有的命令行安装路径。
  • 那么: 读者可以继续阅读首个项目指南,并查看主机支持限制。

选择并阅读技能

  • 给定: 读者知道下一个任务,但不知道其命令。
  • 当: 读者打开 /skills 并选择一个任务组。
  • 那么: 页面显示每个技能的规范图标、名称、命令和简短用途。
  • 那么: 技能链接打开一个单独页面,解释该技能并链接到其仓库说明。
任务组 技能与命令
构思创意 Brainstorm (/egm-brainstorm)、Draft (/egm-draft)
审查文档 Review (/egm-review)、Resolve findings (/egm-resolve)、Custom review (/egm-review-loop)
处理代码 Document a codebase (/egm-bootstrap)、Check for drift (/egm-drift-report)

搜索并复制文档

  • 给定: 读者在 JavaScript 可用时打开文档页面。
  • 当: 读者打开搜索,输入词条,并选择结果。
  • 那么: Pagefind 搜索本地索引,并打开匹配的页面或章节。
  • 当: 读者选择“复制页面”。
  • 那么: 网站复制页面的 Markdown 并提示成功。
  • 那么: 复制失败时,会显示直接的 Markdown 链接和错误消息。

在没有 JavaScript 或宽屏的情况下阅读

  • 给定: JavaScript 不可用,或者读者使用窄屏。
  • 当: 读者打开一个文档 URL。
  • 那么: 静态页面文本和普通链接仍然可用。
  • 那么: 当 JavaScript 可用时,移动端导航和布局会适配视口。
  • 那么: 较宽的代码和表格会在其内容区域内滚动。

技术计划

静态内容流水线

Astro 保持静态输出。Starlight 提供文档布局、导航、目录、搜索集成和代码渲染。

Astro 内容加载器读取 docs/site/**/*.md。

每个集合条目的 ID 是 docs/site/ 下的文件路径(不含 .md),路由为 / 加上该 ID。

例如,docs/site/skills/egm-review.md 的路由为 /skills/egm-review。

SKILL.md 文件向 AI 助手提供说明。网站不会渲染这些文件。

规范的技能说明保持不变。

Markdown 转换会将相对仓库引用解析为规范的 GitHub URL。

它必须保留绝对 URL、网站路由、锚点和代码示例。

依赖与加载器选择

使用 Node.js 22.23.4 或更高版本。候选 lockfile 解析出以下包版本:

Package Version
astro 7.4.5
@astrojs/starlight 0.42.9
starlight-llms-txt 0.12.0
@astrojs/markdown-remark 7.3.5
unified 11.0.5
remark-parse 11.0.0
remark-gfm 4.0.1
remark-stringify 11.0.0

在 package-lock.json 中保留这些解析结果。使用 npm ci 进行验证和部署。 候选方案通过这些版本的 Astro 检查、静态构建和文档检查。

使用 defineCollection 以及来自 astro/loaders 的 Astro glob 加载器定义 docs 集合。 以仓库根目录作为其基准路径(从 site/ 向上为 ..),模式为 docs/site/**/*.md。 使用 generateId 生成集合条目 ID。 使用 Starlight 的 docsSchema() 校验 frontmatter。 通过 schema 校验拒绝缺少标题或包含无效 Starlight 元数据的条目。

技能页面

每个技能页面的文件名为 docs/site/skills/<skill-name>.md,其中 <skill-name> 与技能目录名称一致。 图标查找、侧边栏和重定向都依赖该名称。 每个页面按以下顺序包含这些部分:What it does、When to use it、What you get、Example、Full instructions。 frontmatter title 是上方任务组表格中的显示名称。frontmatter description 是网站文本。它不会改变技能的规范性描述。 新技能需要页面、侧边栏条目和重定向。 如果页面与其 SKILL.md 不一致,则以 SKILL.md 为准,页面存在缺陷。

对于 Markdown 导出,使用 unified、remark-parse 和 remark-gfm 解析 entry.body。 应用共享的仓库转换,然后使用 remark-stringify 序列化。 为页面标题和描述添加前缀。在已渲染页面的 Astro remark 管道中使用相同的转换。

仓库 URL 规则

仓库引用使用 main 修订版本。这些链接有意跟随当前仓库内容,而非固定的构建修订版本。 相对路径基于源 Markdown 文件解析,而非其网站路由。 保留查询字符串和片段。保持绝对 URL、根相对网站路径和纯锚点引用不变。 在文档检查期间,拒绝仓库之外的路径和缺少相对目标的链接。

  • 通过 https://github.com/google/elephant-goldfish-model/blob/main/<path> 链接到仓库文件。
  • 通过 https://github.com/google/elephant-goldfish-model/tree/main/<path> 链接到仓库目录。
  • 通过 https://raw.githubusercontent.com/google/elephant-goldfish-model/main/<path> 解析图片节点。
  • 对于图片使用的引用定义,使用 raw 资源目标。其他定义遵循文件或目录规则。

图片和普通链接可以共享同一个引用定义。对该定义使用 raw 目标,以确保图片保持有效。 在渲染的 HTML 和 Markdown 导出中,同时测试内联图片、图片引用定义、目录以及带片段的文档链接。 保持代码示例不变。

旧版 HTML 路由按以下方式重定向:

  • /docs 重定向到 /guide。
  • /docs/getting-started 重定向到 /getting-started。
  • /docs/workflow 重定向到 /workflow。
  • /docs/skills 重定向到 /skills。
  • /docs/skills/<skill-name> 重定向到 /skills/<skill-name>,适用于上述七个命令。

其他旧版路径不属于本契约的一部分。

flowchart LR
  A[Repository Markdown] --> B[Astro content collection]
  B --> C[Static HTML]
  B --> D[Markdown exports]
  B --> E[llms.txt variants]
  C --> F[Local Pagefind index]
  C --> G[GitHub Pages production]

共享界面

Nav.astro 负责 wordmark、站点链接、活动分区和 GitHub 链接。 Starlight 头部包装器添加搜索功能并预留移动端菜单空间。 两种布局都使用相同的 68 像素头部高度和共享的页面边距。

Material Web 提供已安装的 @material/web 包。 其 labs/gb 样式通过原生元素类和 CSS 自定义属性实现 gBreeze。 站点包装器复用这些类,无需 Lit 自定义元素运行时。 共享 token 来源是 site/src/styles/tokens.css。

共享页脚负责法律链接和主题控制。 主题菜单在页脚上方打开,并支持键盘导航。 主题选择在本地持久化,当读者选择 System 时会跟随系统设置。

使用一种正文文本角色、一种标题角色以及现有的次要文本角色。 将 Starlight 的中性色映射到这些共享 token,而不是复制十六进制值。 wordmark 在深色模式下保持白色,在浅色模式下保持深色。 保持品牌标志颜色和代码语法颜色与正文颜色分离。

文档正文文本使用 18 像素字号、1.7 行高和 42 rem 的最大宽度。 外部桌面网格的最大宽度为 1160 像素。 在空间允许的情况下,每个导航栏使用 200 像素。 在较窄的宽度下,布局会折叠为 Starlight 移动端导航。

使用标准技能 SVG,不改变其几何形状。 在本地打包 Google Material Symbols Rounded 作为界面图标。 搜索对话框使用紧凑文本和扁平结果行,并具有清晰的焦点状态。 Expressive Code 保留语法高亮和复制行为,不包含装饰性的终端控件。

机器可读内容

每个文档 URL 都有对应的 .md URL 和 HTML alternate 链接。 Markdown 端点使用与 HTML 页面相同的集合和引用转换。 starlight-llms-txt 生成 /llms.txt、/llms-full.txt 和 /llms-small.txt。 这些文件改善内容访问。它们不承诺模型兼容性或回答质量。

外部数据与隐私

构建过程可能获取一次公开的 GitHub star 数量,超时时间为五秒。 数据无效或网络故障时会移除该数量,而不会导致站点构建失败。 浏览器不会获取 GitHub 数量或远程字体。

保留当前 main 分支中的生产主机名和同意门控。 在 localhost 或非规范主机上不加载任何 Google Analytics 资源。 不要在此功能中更改同意行为。 文档布局在生产环境发布之前必须获得与生产环境相同的同意行为。

将现有的内联同意脚本提取到 site/src/components/Analytics.astro 中,同时不改变其逻辑。 该组件接受 pageTitle: string,并在构建期间读取 PUBLIC_GA_MEASUREMENT_ID。 Base.astro 和 Starlight 的 Head.astro override 都会渲染此组件。 当测量 ID 为空时,该组件不输出任何脚本。 其脚本在加载外部资源之前仍会检查 window.location.hostname === 'egm.dev'。 共享页脚保留同意管理控件。

更新 site/tests/analytics.test.mjs 以测试提取出的脚本。 更新 site/scripts/verify-analytics.mjs,以在相同的同意情形下同时测试首页和文档 HTML。 在两种布局上检查待处理、已拒绝、已接受、已撤销、初始化失败和非规范主机状态。

部署

GitHub Pages 仍是 egm.dev 的生产目标。 其构建会响应站点文件、网站 Markdown 以及技能图标的变化。 每日构建会刷新公开的 star 数据。

Alternatives Considered

保留单一的自定义指南页面

此选项依赖更少,但需要自定义导航、搜索和内容导出代码。 它不满足所选的多页指南和技能参考需求。

将文档迁移到托管式文档服务

此选项提供了完整的文档界面,但增加了另一套部署和内容系统。 所选设计保留仓库 Markdown、当前 Astro 站点和现有生产主机。

渲染每个 SKILL.md 文件

此设计的第一个版本将每个 skills/*/SKILL.md 文件渲染为其技能页面。 此选项为每个技能保留一份文本,并且不会产生不一致。 SKILL.md 文件面向 AI 助手:其中说明了参数、工具调用和循环规则。 它不满足提供不预设编码工作流的解释说明这一要求。

在渲染的 SKILL.md 上方添加书面介绍

此选项将规范文本保留在页面上。 读者看到的页面大部分仍是助手指令,本地搜索也会返回这些内容。 所选设计改为链接到规范文件。

风险

风险 缓解措施或接受情况
技能页面与其 SKILL.md 不一致。 npm run check:docs 要求每个技能目录对应一个页面,并且每页链接到各自的 SKILL.md。内容检查是 #391 中的独立工作。
SKILL.md 的更改不会触发站点构建。 接受。页面文本并非来自该文件。每日构建会发现已删除或重命名的链接目标。
Markdown 导出和 llms.txt 包含的是页面文本,而不是助手指令。 接受。每个导出都链接到规范指令。
本地搜索无法找到仅出现在 SKILL.md 中的术语。 接受。
“完整指令”链接指向 main,这可能与已安装的插件版本不同。 接受。

非功能性需求

可访问性

保留语义化标题、描述性链接、可见的键盘焦点以及装饰性图标旁的文字标签。 正文文本在两种主题下都必须满足 4.5:1 的对比度。 所选正文颜色与主要页面背景的对比度超过 9:1。 静态内容在未启用 JavaScript 时也必须保持可读。

性能

保留静态 HTML 和本地资源。通过现有的 Starlight 集成加载本地搜索实现。 不要添加服务器运行时或远程搜索请求。 保留自托管字体,并遵循减少动态效果偏好。

发布与回滚

在实施之前先评审设计。在发布到生产环境之前检查确切的实现分支。 使用本地浏览器截图进行视觉评审。原型不能作为生产环境审批的依据。 如果路由、资源或同意行为出现问题,则回滚生产实现提交。

Detailed Implementation

范围边界与 PR 依赖

该实现仍作为一个功能,通过四个相互依赖的 Stage 2 PR 进行评审。 评审单元包括:依赖与基础部分、文档引擎、共享界面和首页。 每个单元都保留本设计、issue #303 以及完整的功能审批要求。 这种拆分缩小了评审范围,并且不使用 minor-patch 例外。 将插件元数据更改保留在 PR #302 中,将已发布的安装文档保留在 PR #301 中。 这两个 PR 都不是站点功能的必需代码依赖。

草稿实现 PR 可以在审批之前展示技术栈以供评审。 在本设计合并且 issue 获得 pr-ready 标记之前,任何实现 PR 都不能合并。

实施阶段

  1. 添加内容集合、路由映射、引用转换、导出及其构建检查。 要求所有文档 URL、Markdown 导出和生成的资源都能成功解析。
  2. 添加共享界面和同意组件。连接首页和 Starlight 布局。 要求 Astro 检查、同意测试以及桌面端和移动端浏览器检查全部通过。
  3. 添加最终内容、规范图标、代码样式和生产构建触发器。 在实施评审之前,要求完成完整的站点和仓库检查。

检查每个中间技术栈状态。在文档引擎和共享界面完成后评审首页。 在较早的 PR 合并之前,后续的上游 diff 会包含前述提交。其描述必须提供增量比较链接。

接口契约

接口 约定
内容加载器 每个集合条目的 ID 等于 docs/site/ 下不含 .md 的文件路径。
内容元数据 每个页面都在 frontmatter 中定义标题和描述。该 schema 要求必须提供标题。
repositoryLink(url, file) 返回一个解析后的 URL 字符串。保留协议、根相对 URL 和锚点不变。将其他路径相对于仓库中的源文件进行解析。
transformRepositoryMarkdown(tree, file) 修改该树。重写 link、image 和 definition 的 URL。保持代码节点不变。
Markdown 端点 为每个集合条目返回一个静态路径,并将其条目作为 props。序列化页面标题、描述和转换后的正文。使用 text/markdown; charset=utf-8。
githubStars 导出 Promise<number \| null>。仅接受安全的非负整数。使用可选的构建 token 和五秒超时。任何失败时均返回 null。
Nav 接受可选的 embedded: boolean 和一个具名搜索插槽。嵌入形式使用现有的 Starlight 头部容器。
PageActions 接受位置 title、rail 或 standalone。将反馈和回退状态限定到每个可见操作。
按钮包装器 保留现有变体和无障碍标签。转发原生 popover 属性和 data-* 属性。保留链接安全属性。
Symbol 接受本地符号名称和可选类。在符号缺失时抛出异常。将渲染后的符号视为装饰性内容。
主题控制 在 starlight-theme 下存储 light、dark 或一个表示 System 的空值。存储失败仅影响持久化。系统更改遵循媒体查询。
跨标签页主题更改 不要添加跨标签页同步契约。每个页面在加载时读取存储的偏好设置。
文档检查 检查可选的 star-data 失败情况、URL 保留、相对引用、未更改的代码示例、路由导出以及现有本地资源文件。

文件操作

创建以下内容:网站的 Markdown 文件、集合加载器、Home.astro、文档适配器、符号资源、内容辅助函数、Markdown 端点、网格样式表和文档样式表。 修改以下现有内容:配置、依赖文件、工作流、README、页头、页脚、基础布局、首页路由、tokens 和全局样式。 创建 site/src/components/gb/Symbol.astro。更改 Button.astro、IconButton.astro 和 site/src/components/Install.astro。 创建 Analytics.astro。更改 site/tests/analytics.test.mjs 和 site/scripts/verify-analytics.mjs 以进行共享的同意验证。 创建 site/scripts/check-docs.mjs,并更改 tests/unit/test_link_integrity.py。 在移除它们的调用方之后,删除已被替换的首页组件 Hero.astro、Install.astro、Model.astro、Loop.astro 和 Skills.astro。 为文档页面保留 SkillIcon.astro。不要添加未使用的符号,也不要给 Starlight 未更改的页脚添加包装器。 不要提交生成的输出。

文档与配置文件

文件 更改与原因
docs/site/guide.md、docs/site/install.md、docs/site/getting-started.md、docs/site/workflow.md、docs/site/skills.md 添加归仓库所有的网站文本和页面路由。
docs/site/skills/<skill-name>.md(七项技能) 为每项技能添加一个页面,向读者解释该技能。
site/src/content.config.ts 加载 docs/site/ 中的网站 Markdown。
site/astro.config.mjs 添加 Starlight、组件覆盖、代码设置、导出、重定向和显式侧边栏。
site/package.json、site/package-lock.json 声明并锁定文档依赖项和验证命令。
.github/workflows/deploy-site.yml 监听源 Markdown 和图标,运行文档检查,并刷新 star 数据。
site/README.md 说明本地开发、内容所有权、验证和部署。

共享接口文件

文件 更改与原因
site/src/pages/index.astro、site/src/components/Home.astro 发布简洁的首页、流程示意图、安装操作和任务链接。
site/src/components/Nav.astro、site/src/components/Footer.astro 共享导航、激活状态、法律链接和主题选择。
site/src/layouts/Base.astro 在保留生产环境同意门控的同时,加载共享 tokens 和网格样式。
site/src/components/Analytics.astro、site/tests/analytics.test.mjs、site/scripts/verify-analytics.mjs 共享现有的同意脚本,并通过两种页面布局进行检查。
site/src/styles/tokens.css、site/src/styles/grid.css、site/src/styles/global.css、site/src/styles/docs.css 共享文本角色、网格间距、可读内容宽度、主题颜色和文档样式。
site/src/components/Install.astro 更新其界面步骤中的指南目标,然后连同旧首页一起移除该面板。
site/src/components/gb/Button.astro、site/src/components/gb/IconButton.astro、site/src/components/gb/Symbol.astro 复用原生 Material Web 类和本地圆角符号。

Starlight 适配器文件

此表中的所有路径均以 site/src/components/docs/ 开头。

文件 更改与原因
Header.astro、PageFrame.astro 将共享的网站页头和页脚嵌入 Starlight。
Head.astro 发布自托管字体和机器可读的备用链接。
Sidebar.astro、MobileMenuToggle.astro 提供扁平的任务导航和无障碍的移动端控件。
PageTitle.astro、PageSidebar.astro 显示页面元数据、规范技能图标、目录和页面操作。
PageActions.astro 复制 Markdown,并带有实时反馈和可见的失败回退。
Search.astro 从共享的圆角图标按钮打开 Starlight 原生搜索。
ThemeSelect.astro 通过原生 popover 应用并持久化共享的主题选择。
Pagination.astro 保持上一页和下一页操作紧凑。使用 Starlight 默认页脚,无需适配器。

资源与内容辅助函数

文件 更改与原因
site/src/assets/symbols/README.md 记录图标来源和许可证。
site/src/assets/symbols/arrow_back.svg, arrow_forward.svg, check.svg, close.svg, content_copy.svg, dark_mode.svg 在本地打包圆角界面图标。
site/src/assets/symbols/description.svg, menu.svg, search.svg 完善本地打包的界面图标集。
site/src/lib/github-stars.ts 在构建期间获取并检查可选的公开星标数据。
site/src/lib/repository-markdown.mjs 保留代码示例并重写仓库相对链接。
site/src/pages/[...slug].md.ts 从内容集合导出页面 Markdown。
site/scripts/check-docs.mjs 检查路由、导出、引用转换、本地资源、搜索输出及星标获取失败。
tests/unit/test_link_integrity.py 将网站路由解析到源 Markdown,并排除生成的构建输出。

复用当前 main 分支中的 site/src/components/SkillIcon.astro 和 skills/*/assets/icon.svg。 请勿在站点实现中添加或编辑规范的技能说明、清单或生成的运行时文件。

必需测试

  • 在 site/ 中运行 npm ci、npm run check、npm run build、npm run check:docs 和 npm test。
  • 运行仓库单元测试套件和包一致性测试。
  • 检查每个文档路由、Markdown 导出、生成的资源引用和旧版重定向。
  • 检查每个技能目录是否只有一个技能页面,每个页面是否链接到其自己的 SKILL.md,以及每个页面是否使用规范图标。
  • 检查搜索打开、查询、清除、结果导航、Escape 和焦点返回。
  • 检查复制成功、权限被拒以及直接 Markdown 回退。
  • 检查主题菜单、系统偏好更改和持久化选择。
  • 在桌面端浅色和深色主题下比较首页、指南、安装和技能页面。
  • 检查移动端导航、内容溢出、表格滚动和代码滚动。
  • 在生产发布前,检查两种布局是否都具有生产环境同意行为。
  • 检查 localhost 和非规范主机是否不会请求 Google Analytics 资源。

该原型通过了站点构建、文档检查、九个站点单元测试和 336 个仓库单元测试。 测试运行跳过了两个可选的原生主机探测。这些结果不能替代最终实现分支上的测试。 完整的 EGM 审查、剪贴板拒绝检查和生产环境同意一致性仍然是明确的审查要求。

设计审查记录

新上下文审查者应用 EGM Zoom Out、理解力、实施就绪度和代码库详情评审标准。 该草案现在定义了技能组、重定向、文件操作、接口契约、阶段以及所需的同意提取。 Zoom Out 审查未发现重大问题。理解力审查的发现通过了解决情况检查。 就绪度审查确定了两种文件分类。草案现在明确陈述了这两种操作。 精确的界面尺寸保留在本文件中,以保持所选视觉目标的可衡量性。

2026-11-09,技能页面从渲染的 SKILL.md 文件转变为面向人类读者编写的页面。 新上下文审查者以功能规格标准对该变更应用了结构、风格和设计评论者角色。 草案现在记录了被拒绝的备选方案、风险以及技能页面契约。 上述原型测试结果早于该变更。

这些范围有限的评审标准审查并不能确立完整的 egm-review 完成或收敛。 完整协议和维护者批准仍处于待定状态。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 el/elephant-goldfish-model