page-template

HTML 展示页 — 页面模板

自我演进技能：此技能会在使用过程中不断改进。如果说明有误、参数发生漂移，或需要采用变通方案，请立即修复此文件，不要拖延。仅针对真实且可复现的问题进行更新。

一个静态 HTML 迷你网站，其导航结构就是文件系统布局本身。每个页面都链接到由 jsDelivr 提供的共享 CSS 内核；自动发现的导航栏和主 site-map.html 由 scripts/build-nav.py 根据你在网站根目录下创建的目录生成。页面是纯 HTML，可选择添加每页 CSS 覆盖。此架构建立在五项原则之上——扩展或分叉前，请先阅读 references/principles.md，从原理层面理解 WHY；导航约定请参阅 references/sitemap.md。

站点地图是默认方案

此技能生成的每个网站都采用相同的结构：

<site-root>/
  index.html              ← site home (recommended)
  overrides.css           ← optional per-site tweaks
  auto-nav.css            ← generated by build-nav.py
  auto-nav.js             ← generated by build-nav.py
  site-map.html           ← generated by build-nav.py
  <section-1>/            ← any subdirectory becomes a "section"
    index.html
    page-a.html
    page-b.html
  <2026-05-02-audit>/     ← YYYY-MM-DD- prefix sorts sections newest-first
    index.html
    findings.html

你无需手动编写导航。只需按需创建目录结构并添加 HTML 文件，然后运行 scripts/build-nav.py --root <site-root>。该脚本会遍历目录树，生成 site-map.html，写入导航栏的 CSS/JS，并通过注释标记将相同的导航栏注入每个页面。重复运行不会产生额外变化。

有关架构和权衡，请参阅 references/sitemap.md。

阅读此技能时，应关注原理，而非具体指令

此技能中的每个具体产物（类名、文件路径、特定 CDN URL、提交消息约定，甚至“section”的命名）都是一小组底层原则的 实例。理解这些原则后，你就能灵活调整任何具体实例，而不会破坏架构。如果只照着指令操作，一旦遇到不适合自身情况的内容，就可能让系统偏离原有结构。

这些原则列于 references/principles.md：

1. 单一事实来源 — 每项视觉决策都由一个文件统一管理
2. 语义优先于原子化 — 类名描述元素 是什么
3. 由令牌驱动 — 每个具体值都来自 CSS 自定义属性
4. 级联纪律 — @layer 顺序在全局范围内控制优先级
5. 不隐藏状态 — 不使用 JS、内联 CSS 或分散的覆盖规则
6. 文件系统即站点地图 — 目录布局就是导航图

此外还包括 AI 协作模式（说明此设计为何适合大模型），以及使用 CDN 而非副本的理由。

三层层级

层级	可变性	控制内容	所在位置
H1 — 内核	编辑一次 → 影响所有位置	令牌（颜色、间距、字体）、重置样式、基础元素、组件	assets/showcase.css（jsDelivr CDN）
H2 — 组合	按页面调整	区块顺序、内容、语义化标记	HTML 文件本身
H3 — 覆盖样式	按页面调整（可选）	为某个页面调整颜色或密度	HTML 旁的 overrides.css

内核是所有视觉决策的唯一事实来源（SSoT）。HTML 不会自行定义样式，只负责排列内核定义的组件。要自定义某个页面，可在 overrides.css 中添加几个 CSS 变量。要自定义所有页面，则编辑内核。

自动导航栏由程序_生成_，而非手动编写。其样式位于 auto-nav.css（由 build-nav.py 编写）；其内容会注入每个页面 <body> 中的 和 标记之间。

无论所在页面采用何种主题，导航栏和主页面 site-map.html 始终使用深色主题（slate-950 表面、slate-300 文本、indigo-400 强调色）。导航栏是每个页面上的固定元素；固定其主题可确保其视觉效果保持稳定，无论它覆盖的是浅色的承包商展示页，还是深色的遥测仪表板。

一个区块内的页面按创建顺序呈现，而非按字母顺序：

• index.html 始终排在第一位。
• 按 index_iter_<N>_<slug>.html 命名的页面按 N 的数值排序（因此 iter_10 排在 iter_9 之后，而非 iter_1 之后）。
• 其他顶层页面按文件系统创建时间（macOS 上的 st_birthtime）排序；编辑或重新构建都不会改变该时间。
• 嵌套页面则按原有的子目录分组、index 优先和字母顺序分组规则排序。

导航栏的运行时行为：

• 首次加载：宽度自动适配最长的未换行链接（使用 width: max-content 测量每个链接的实际固有宽度，不受导航栏当前尺寸影响），并限制在 [220, 760]px 范围内。
• 拖动右侧边缘的手柄：可在 [220, 1200]px 范围内手动调整大小；选定的宽度会保存在 localStorage 中。
• 双击手柄：清除已保存的宽度并重新自动适配（语义上即“重置为智能默认值”）。
• 手柄的可点击区域为 14px，带有始终可见的 2px 指示线，以及说明双重操作的悬停提示。
• 区块内上一页/下一页：区块内的页面会在“Site”标题行显示紧凑的 ‹ › 按钮（不增加高度），并支持兼容 Chrome 的独立 [ / ] 键盘快捷键。‹ / [ 跳转到上一个同级页面（较新），› / ] 跳转到下一个同级页面（较旧）；在列表两端时，相应按钮会显示为灰色。按住修饰键或焦点位于搜索框中时，快捷键不会响应，因此不会打断输入。

默认启用搜索

每个导航栏（以及主 site-map.html）顶部都会添加一个 Search 区块， 由 Pagefind 提供支持。Pagefind 是一款用 Rust 构建的静态搜索工具，可生成独立索引，无需服务端、构建流水线， 客户端 UI 仅约 70 KB。

接入方式：

• build-nav.py 会按严格顺序向每个页面的 <head> 注入 4 个标签： Pagefind CSS → auto-nav CSS → Pagefind JS → auto-nav JS。
• 导航栏的第一个区块是 <div id="auto-nav-search"></div>； Pagefind 加载完成后，auto-nav.js 会调用 new PagefindUI({...})。
• 实际索引位于 <site-root>/pagefind/，通过运行 pagefind --site <site-root> 生成。
• scripts/site.sh nav 会运行 build-nav.py 和 pagefind --site — 每次重建导航栏时都会自动刷新搜索索引。

如果未安装 pagefind，导航栏仍会显示搜索输入框，但不会执行搜索； 当 window.PagefindUI 未定义时，auto-nav.js 的 mountSearch() 会直接返回。可通过 brew install pagefind 安装（或参阅官方安装文档）。

推送钩子自动重新同步

install.sh --hook 会在 .githooks/pre-push 安装 Git 推送前钩子， 并配置 git config core.hooksPath .githooks。之后，每次 git push main 都会自动：

1. 自动检测仓库中的所有站点目录（包含 site-map.html 的目录）
2. 运行 scripts/site.sh nav <site-dir>（重建导航栏和搜索索引）
3. 运行 scripts/site.sh push <site-dir>（通过 Tailscale 使用 rsync 同步到 myhost）

该钩子不会阻塞推送 — 即使 rsync 失败（蜂窝网络、咖啡馆、 myhost 宕机），仍会继续推送到 GitHub。可跳过的环境变量：

变量	作用
NO_HTMLSHOWCASE_HOOK=1	完全跳过该钩子
NO_HTMLSHOWCASE_SYNC=1	运行导航栏和搜索，但跳过 rsync
NO_HTMLSHOWCASE_SEARCH=1	跳过 pagefind 重新生成步骤
HTMLSHOWCASE_SITES="a b c"	使用显式列表覆盖自动检测

四种贡献者角色

选择与你的任务相符的角色。每种角色的完整工作流见 references/contributing.md。

角色	示例任务	修改内容	影响范围
使用者	“为我制作一个承包商展示站点”	你的 HTML	仅你的站点
定制者	“将此站点重新设置为我们的品牌青绿色”	overrides.css	仅你的站点
贡献者	“在内核中添加一个 .timeline 组件”	上游内核 CSS	所有使用此内核的站点
发布者	“我们的团队派生内核，并从自己的 GitHub 发布”	你派生版本的内核	指向_你的_ CDN URL 的站点

何时使用此技能

• 创建静态 HTML 站点（单页或多页），用于记录结构化工作：审计、 提交、指标、报告、承包商展示、遥测视图、每周摘要
• 将内联 CSS 页面替换为共享设计系统和自动导航栏
• 搭建多页迷你站点，并逐步扩展为承包商作品集、每周摘要归档或 发行说明中心 — 无需手动维护导航

请勿用于：博客文章、营销落地页、交互式 Web 应用。

此技能包含的内容

路径	用途
templates/index.html	网站首页骨架（主视觉区 + 3 个示例区块 + 页脚 + 标记）
templates/section-index.html	区块落地页骨架
templates/overrides.css.example	各网站自定义的参考文件（重命名为 overrides.css）
templates/lychee.toml	链接检查器配置
scripts/build-nav.py	通用站点地图构建器 — 自动导航 + site-map.html 生成
scripts/check-orphan-pages.py	纯标准库的孤立页面图验证器
scripts/site.sh	构建导航 + 验证 + 通过 Tailscale 推送到 myhost（见下文）
scripts/install.sh	一次性引导：将全部 3 个脚本安装到任意仓库
references/principles.md	原理 — 五项原则 + AI 模式
references/sitemap.md	方法 — 以文件系统作为站点地图的约定、导航栏渲染
references/contributing.md	方法 — 四种立场及完整工作流
references/publishing.md	位置 — 发布渠道（CDN 与 tailnet）+ myhost 设置

CSS 内核本身位于插件级别 （plugins/html-showcase/assets/showcase.css），并通过 jsDelivr 提供 — 骨架 HTML 引用的是公开 CDN URL，而不是本地文件。

完成的网站托管位置

两个渠道，两种用途：

渠道	内容	使用场景
jsDelivr CDN（公开）	仅内核 CSS	始终使用 — 每个页面都从同一个共享 URL 导入内核
tailnet 上的 myhost	渲染后的网站	内部受众的默认选择（无需 DNS、身份验证界面或公开披露）
jsDelivr / Pages / Workers	渲染后的网站	仅当外部读者确实需要访问该页面时

对于面向内部受众的网站（审计报告、承包商展示、遥测视图、每周摘要），myhost tailnet 路径是最省事的选择。在任何仓库中采用该方案，只需一条命令：

ROOT="$(cc-plugin-root html-showcase)"
bash "$ROOT/skills/page-template/scripts/install.sh"

这会将全部三个流水线脚本（build-nav.py、 check-orphan-pages.py、site.sh）安装到 <repo>/scripts/，并将 **/.published.json 追加到 .gitignore。安装程序具有 幂等性（重复运行不会产生变化），且不会破坏现有文件 （使用 --force 覆盖）。如需同时创建一个入门网站目录：

bash "$PLUGIN/skills/page-template/scripts/install.sh" --site contractor-site

然后，scripts/site.sh push <site-dir> 会重新生成站点地图，在本地进行验证（lychee + 孤立页面检查），并通过 rsync 推送到 myhost:~/sites/<repo>/<site-dir>/，页面地址为 https://myhost.tailnet-name.ts.net:8448/<repo>/<site-dir>/。推送端 的门禁（build-nav + lychee + 孤立页面检查）是唯一门禁。完整 机制、URL 公式、何时不应使用 myhost，以及 myhost 的一次性设置说明，请参阅 references/publishing.md。

通用密度调节项

showcase.css 顶部的两个 CSS 自定义属性控制整个 视觉节奏。可在 overrides.css 中覆盖其中任意一个，以重新调整单个网站：

:root {
  --density: 0.85; /* spacing multiplier; 1.0 baseline, lower = tighter */
  --font-scale: 0.94; /* type multiplier; 1.0 baseline, lower = smaller */
}

内核中的所有内边距、间距、外边距和区块节奏都由 间距刻度决定；间距刻度则由 --density 决定。正文的 字体大小由 --font-scale 决定。组件 CSS 中没有零散的神奇数字 — 请参阅 references/principles.md 中的原则 3。

组件词汇表

内核定义了以下语义类，HTML 会使用这些类。要查看完整列表，请打开内核 CSS 并搜索类选择器。

类	用途
.hero + .hero__inner / __eyebrow / __title / __lede / __cta-row	带渐变的顶部横幅
.chip--solid / .chip--ghost	Hero CTA 按钮
.metric-grid + .metric-card	一目了然的数据面板；修饰符 --accent、--success、--warning
.phase-grid + .phase-card	分阶段时间线卡片；修饰符 --audit、--fix、--perf
.commit-stack + .commit-card	详细的提交卡片，包含 SHA 标签和详情网格
.bug-grid + .bug-card（--high 修饰符）	紧凑的问题卡片
.feature-grid + .feature-card	带图标的通用四列展示网格
.reco-list + .reco-item（--p0 / --p1 / --p2）	按优先级排序的建议
.badge（--high / --medium / --low / --success / --info / --neutral / --accent）	严重程度 / 状态标签
.section-head / .section-intro	每个分区的标题行和说明段落
.shell	居中的内容容器，带最大宽度和响应式内边距
.site-footer + .site-footer__grid / __legal	来源信息页脚

自动导航栏使用自身的非内核类（.auto-nav-rail、 .rail-link、.rail-section 等），这些类定义在 auto-nav.css 中，因此 导航栏保持独立，仓库可以采用导航栏而不采用内核。

如果页面需要本表中没有的内容组件，有两种选择——两者都合理，也都记录在 references/contributing.md 中：

• 将其添加到内核（立场 3）：在 components @layer 中使用语义类名、引用令牌的值，以及 BEM 修饰符变体。
• 使用本地覆盖处理一次性情况（立场 2）：仅当该模式确实只适用于一个页面时使用；反复出现的模式应归入内核。

快速开始（使用者立场，按站点地图组织）

最快的方法：运行安装程序来初始化流水线脚本和起始站点，然后逐步迭代。

ROOT="$(cc-plugin-root html-showcase)"

# 1. Bootstrap the pipeline + starter site directory
bash "$ROOT/skills/page-template/scripts/install.sh" --site contractor-site

# 2. (Optional) Add one or more sections under contractor-site/
mkdir -p contractor-site/2026-05-02-first-section
ROOT="$(cc-plugin-root html-showcase)"
cp "$ROOT/skills/page-template/templates/section-index.html" \
   contractor-site/2026-05-02-first-section/index.html
cp "$ROOT/skills/page-template/templates/index.html" \
   contractor-site/2026-05-02-first-section/page-a.html

# 3. Fill {{ PLACEHOLDERS }} in the HTML, then build the sitemap + nav
scripts/site.sh nav contractor-site

# 4. Validate (lychee + orphan check)
scripts/site.sh check contractor-site

# 5. View — any page reaches every other via the rail
open contractor-site/index.html
open contractor-site/site-map.html

或者，如果你更愿意不使用安装程序，手动复制模板：

ROOT="$(cc-plugin-root html-showcase)"
DEST=/path/to/your-site
mkdir -p "$DEST"
cp "$ROOT/skills/page-template/templates/index.html"   "$DEST/"
cp "$ROOT/skills/page-template/templates/lychee.toml"  "$DEST/"
python3 "$ROOT/skills/page-template/scripts/build-nav.py" --root "$DEST"

如果 <repo>/scripts/ 中没有 site.sh，它会回退到插件附带的 build-nav.py，因此即使不使用安装程序，也可以在任何仓库中直接使用插件附带的脚本推送到 myhost。

关于另外三种立场（定制者、贡献者、发布者），请参阅 references/contributing.md。关于通过 Tailscale 发布到 myhost 的流程，请参阅 references/publishing.md。

CDN 版本管理

在早期迭代阶段，内核 URL 固定指向 @main 分支；内核稳定后，则固定到带标签的版本：

@main      → always-latest         → use during development; jsDelivr cache flushed automatically on each release
@v<X.Y.Z>  → immutable, content-locked → use for production-stable pages
@<sha>     → immutable, commit-locked  → use for forensic-grade pinning

每次发布时，发布流程都会自动清除 @main 的缓存，并对 @v<X.Y.Z> 执行冒烟测试。若要在两次发布之间强制刷新 @main（例如，内核正在密集迭代时），请在 cc-skills 仓库根目录运行 bash tasks/release/cdn-purge。若要在单个页面上完全绕过缓存，请在内核链接后附加 ?v=$(date +%s)。

自动导航资源（auto-nav.css、auto-nav.js）由 build-nav.py 在本地生成，并与 HTML 文件放在一起——它们不会由 CDN 提供。这些 URL 上的 ?v=N 查询字符串也可用于绕过缓存；更改 build-nav.py 中导轨的 CSS 或 JS 主体时，请递增 --asset-version。

硬性规则

这些规则已内置于内核和模板中；如果你想打破这些规则，请改为修复内核（参见 references/contributing.md 中的立场 3）。

• 不得使用内联 <style> 块。
• HTML 元素上不得使用 style="" 属性。
• HTML 中不得堆砌工具类——类名应具有语义（.metric-card、.badge--high），不得使用原子类（flex p-4 bg-blue-500）。
• 内核是所有视觉决策的唯一事实来源。
• HTML 只负责排列组件，不得自行创造组件。
• 文件系统布局就是导航图；不得手动编写 和 之间的导轨 HTML。 任何结构变更后，都要重新运行 scripts/build-nav.py。
• 每个站点都必须通过 Lychee 链接检查和孤立页面检测，才能视为已交付。

执行后反思

此技能完成后，请在结束任务前进行反思：

0. 确认你的位置。 — 编辑前，找到此 SKILL.md 的规范路径。
1. 出了什么问题？ — 修复相关指令。如果缺少内核组件，请添加它（立场 3）。如果站点地图导轨的渲染结果出乎意料，请同时修复 build-nav.py 和 references/sitemap.md。如果某项_原则_不明确，请修复 references/principles.md。
2. 哪些地方比预期更顺利？ — 如果新的章节模式反复出现，请将其提炼为内核组件或 templates/section-index.html 中的内容。
3. 有哪些不一致？ — 确保 SKILL.md、模板和 build-nav.py 中的 CDN URL 固定版本、覆盖示例、组件术语和导轨 HTML 标记保持一致。
4. 记录下来。 — 添加演进日志条目，记录触发原因、修复内容和证据。

请勿推迟。下一次调用将继承你留下的内容。