homepage-craft

把一个开源仓库变成一页拿得出手的主页：素材全部来自仓库本身（README、manifest、截图、git 元信息），产物是一个单文件 HTML，双击能开、推到 GitHub Pages 就能发布。视觉质量优先借力环境里已装的设计类 skill，本 skill 负责的是"仓库 → 内容 → 页面"这条流水线和发布可用性。

设计原则（贯穿整个 procedure）

风格基线：像一个头部开源项目的官网，不是像模板市场的 demo 页。

Inputs to collect

按需读取，不需要全部问用户：

• 项目路径：默认当前工作目录；用户给 GitHub URL 时走远程模式（见 Step 2）
• 输出位置：默认 <project-root>/docs/index.html（GitHub Pages 的 /docs 源约定）；docs/ 被文档框架占用时改用 homepage/index.html（见 Failure handling）
• 页面语言：默认跟随主 README 的语言，不问；用户指定了其他语言按用户的来
• 风格偏好（可选）：用户主动说了（"暗色"、"极简"）就记录；没说且有 companion 设计 skill 时交给它决定；两者都没有时，从基线三方向里按项目类型选，不追问（见 Step 3）
• 部署意向：不预设、不提前问——Step 7 生成完毕后再询问；用户一开始就明确说"部署到 GitHub Pages"的，Step 7 免询问直接走
• 发布策略：同样在 Step 7 与部署意向一起问（A：main + /docs；B：独立 gh-pages 分支），不预设默认偏好；用户在需求里指定了（"走 gh-pages"、"别动 main"）就跳过询问

Procedure

Step 1 — 扫描项目，收集素材

读取根目录列表和关键 manifest，确定 name、version、description、license、homepage/repository 字段。manifest 类型对照表与 readme-craft 一致（package.json / pyproject.toml / go.mod / Cargo.toml / pom.xml / Gemfile / composer.json / *.csproj）。

git 元信息（只读命令）：

git rev-parse --is-inside-work-tree   # 是否 git 仓库
git remote get-url origin             # 提取 <user>/<repo>，供仓库链接和 star 数用
git describe --tags --abbrev=0        # 最新 tag（供 version 展示）

视觉素材扫描（按优先级找，命中即记录路径）：

• README 里引用的图片一定真实存在才可用——引用前先验证文件在磁盘上（远程图片验证 URL 可达）
• 发现已有文档站配置（VitePress / Docusaurus / MkDocs / Jekyll）→ 记录下来，Step 6 决定输出位置时要避让

这是必做步骤——不读仓库就在主页上写功能介绍，几乎一定会编造。

Step 2 — 提取页面内容

从 README + manifest + git 信息整理一份内容清单，页面上只允许出现清单里的东西：

语言：跟随主 README（多语言 README 时跟随第一个/默认那个）。README 是中文就出中文页，英文就出英文页——主页和 README 语言打架是最常见的违和感来源。

措辞：把 README 的事实重写成页面语言（短句、动词开头、面向访客），但不添加 README 里没有的承诺。AI 上下文文件（AGENTS.md / CLAUDE.md）可以参考作者语气，敏感信息一律丢弃。

远程模式（用户给的是 GitHub URL 而非本地路径）：

1. 拉 https://raw.githubusercontent.com/<user>/<repo>/HEAD/README.md（失败依次试 main / master）
2. 拉 https://api.github.com/repos/<user>/<repo>（stars、license、topics、homepage 字段；未认证限流失败就跳过，相应内容不展示）
3. 图片一律用 raw.githubusercontent 绝对 URL（本地没有文件可拷）
4. 产物写到当前目录 <repo>-homepage/index.html，报告里说明"可整体拷入目标仓库 docs/ 发布"

Step 3 — 设计系统：探测并编排 companion skill

这是视觉质量的关键一步。检查本 session 的可用 skill 列表（系统会注入 available skills；名字可能带插件命名空间前缀，如 frontend-design:frontend-design，按去掉前缀后的基础名匹配）：

组合规则：

• ui-ux-pro-max 和 frontend-design 同时命中就同时用——前者决定"长什么样"（design tokens + 章节建议），后者管"怎么写得好看"（实现时的排版、层次、细节工艺），职责不冲突
• 同类多个命中（frontend-design 和 superdesign 都装了）取一个即可，优先 frontend-design
• 环境没有 Skill 工具时，退回按常见安装路径直接读它的 SKILL.md 并遵循（~/.agents/skills/、~/.claude/skills/、插件缓存目录）
• companion skill 加载失败或执行报错 → 降级到内置基线，报告里说明原因，不阻塞主流程

记录美感来源（companion 名称 + 它给的关键决策，或基线方向 A/B/C），Step 6 报告要用。

Step 4 — 生成单文件 HTML

按 Step 3 的设计系统和 Step 2 的内容清单写页面。章节选择、HTML 骨架、必备 meta、复制按钮等具体规范见 references/page-anatomy.md；走内置基线时的风格方向和反模板化规则见 references/design-baseline.md。

硬约束（无论美感来源是哪条路径都适用）：

• 单文件：CSS 内联 <style>，JS 只允许少量原生脚本（复制按钮、平滑滚动、滚动渐显），无框架无构建
• 外部依赖最多一项：Google Fonts（必须带系统字体 fallback，断网时页面不塌）
• 响应式：375px / 768px / 1440px 三档不破版；图片 max-width: 100%
• <head> 配齐：title、description、OG + Twitter card、内联 SVG favicon（data URI）、JSON-LD（SoftwareApplication）
• 安装命令区块带一键复制按钮
• 动效克制：只用 CSS transition，尊重 prefers-reduced-motion；不写视差滚动、粒子背景这类重 JS 效果
• 图片路径：拷进 docs/assets/ 用相对路径，或用 raw.githubusercontent 绝对 URL——GitHub Pages 从 docs/ 发布时 ../assets/x.png 是 404

页面好不好，七成在"少即是多"：章节宁少勿滥，每屏一个视觉重点。companion skill 给的建议和硬约束冲突时，以硬约束为准（它们是发布可用性的底线）。

Step 5 — 视觉自检

有浏览器工具（browser-use / web-gui-tester 等，检查本 session 可用工具）：

1. 打开页面截图：浏览器工具不支持 file:// 时（应用内浏览器普遍如此），先起 python -m http.server -d docs 8000，打开 http://127.0.0.1:8000/
2. 检查：hero 区完整、无横向滚动条、图片全部加载、复制按钮点击生效、无占位文本残留
3. 把视口缩到手机宽度（约 390px）再截一张，确认不破版；横向溢出常见元凶是 grid/flex 子元素的 min-width: auto 被 nowrap 内容撑开——给该子元素补 min-width: 0、轨道用 minmax(0, 1fr)
4. fullPage 拼接截图在 sticky 头部、平滑滚动下易出伪影（分段重复、内容缺失——是捕获问题不是页面问题）；存疑时改用滚动锚点逐段截视口图核对
5. 发现问题回 Step 4 修，修完复检

无浏览器工具：按 references/page-anatomy.md 末尾的自检清单逐项过——grep 占位符残留（TODO、xxx、YOUR-、lorem）、核对引用的资源路径真实存在、检查标签配对。

Step 6 — 写入并报告

1. 输出位置：默认 <project-root>/docs/index.html；docs/ 被文档框架占用（Step 1 检出 mkdocs.yml / docusaurus.config.* 等且 docs/ 是其内容目录）→ 写 homepage/index.html 并在报告里说明
2. 已有同名文件 → 先备份 <file>.bak；.bak 已存在改用带时间戳的 <file>.<YYYYMMDD-HHMMSS>.bak，绝不覆盖旧备份
3. 页面引用的本地图片拷贝到 docs/assets/（与 index.html 同级），README 原引用不动

4. 输出报告：

   已生成主页: docs/index.html（X KB + assets/ N 张图）
   美感来源: <companion skill 名称及关键决策 | 内置基线方向 B（清爽编辑风）>
   章节: Hero / Features / Quick Start / Screenshots / Footer
   本地预览: python -m http.server -d docs 8000

5. 不静默 commit / push——随即进入 Step 7 询问部署意向；用户拒绝部署时，在报告里补一句建议的提交说明和手动发布路径（GitHub → Settings → Pages → Source 选 /docs）

Step 7 — 部署到 GitHub Pages（可选，先问后动手）

部署是外向操作（推代码、改仓库设置），必须先询问；只有用户在需求里明确说了"部署"、"发布上线"才免询问直接走。

前置条件检测（按顺序查，决定询问时给哪些选项）：

询问 1 — 部署意向（优先用 ask_user 工具，环境没有该工具时在回复里列出选项问一次）：

question: "主页已生成，要部署到 GitHub Pages 吗？"
options:
  - 自动部署（commit + push + 开启 Pages，推荐）
  - 只 commit + push（Pages 我自己在网页上开）
  - 不部署（文件我自己处理）
# gh 不可用时第一个选项换成"只 commit + push"，并说明原因

询问 2 — 发布策略（仅在选择部署后问；两种都合法，把取舍说给用户听，不替用户拍板）：

question: "主页放哪里发布？两种策略各有适用场景。"
options:
  - 随 main 分支 + /docs 目录（推荐）
  - 独立 gh-pages 分支（main 只留源码）

一句话取舍（询问时附上）：没有构建步骤、希望主页随仓库内容同 commit 同步选前者；要求 main 纯净只放源码、或将来打算上 CI 自动生成主页选后者。

策略 A 流程（main + /docs）：

1. commit：只 git add 本次生成的文件（逐个列出 docs/index.html、docs/assets/ 下实际拷贝的图片）——绝不 git add -A / git add .，用户工作区里其他未完成的改动不属于这次提交。提交说明风格跟随目标仓库已有提交（如 docs: add project homepage）
2. push：git push origin <当前分支>——绝不 --force、绝不自动 pull/rebase；被拒（落后远端、分支保护）就停下报告原因，由用户决定怎么处理
3. Pages 源 = <当前分支> + /docs（开启方式见下方"开启 Pages"）

策略 B 流程（独立 gh-pages 分支）：

发布拷贝进孤立分支，全程用 git worktree 在临时目录操作，绝不切换用户工作区的分支：

1. 本地 docs/index.html 保留为预览副本（不提交进 main，报告里说明它的角色）

2. 准备 worktree：

   # 首次（gh-pages 不存在）：建孤儿分支
   git worktree add --detach .pages-tmp HEAD
   git -C .pages-tmp switch --orphan gh-pages
   # 非首次（gh-pages 已存在）：直接检出
   git worktree add .pages-tmp gh-pages

3. 把 docs/index.html 拷为 .pages-tmp/index.html（分支根目录），图片拷到 .pages-tmp/assets/；孤儿分支首次提交时 worktree 里残留的旧文件都是未跟踪状态，只 add 拷贝进去的文件
4. 在 worktree 内 commit（如 docs: publish project homepage）→ git push origin gh-pages——绝不 --force；分支已存在且落后远端被拒时停下报告
5. git worktree remove --force .pages-tmp
6. Pages 源 = gh-pages + /

开启 Pages（两策略通用，gh api，先查再动，保证幂等）：

gh api repos/<user>/<repo>/pages        # 200 = 已开启；404 = 未开启
gh api repos/<user>/<repo>/pages -X POST -f 'source[branch]=<分支>' -f 'source[path]=<路径>'
# 策略 A：<分支>=当前分支，<路径>=/docs；策略 B：<分支>=gh-pages，<路径>=/

• 未开启（404）→ POST 创建
• 已开启且源与本次策略一致 → 无需操作，push 完等构建即可
• 已开启但源不同（包括 A/B 策略互切）→ 停下来问用户——切换源会顶掉现有站点，不能替用户决定

等构建与报告（两策略通用）：gh api repos/<user>/<repo>/pages/builds/latest --jq .status 约 15 秒轮询一次、最多 2 分钟；超时未 built 先给 URL 注明"构建中"。报告含公开 URL（通常 https://<user>.github.io/<repo>/）、构建状态、commit hash、所用发布策略；仓库已有自定义域名的沿用，不碰域名设置。

降级分支：

• 用户选"只 commit + push"或 gh 不可用 → 按所选策略执行 commit/push 部分，附网页开启路径：Settings → Pages → Build and deployment → Source: Deploy from a branch → <分支> + <路径>（策略 B 还需先在本地完成 worktree 推送，或说明手工步骤）
• 连 push 条件都不满足（无 remote、无写权限）→ 停在 commit，报告手动步骤
• 用户选"不部署" → 什么都不做，报告里给建议的提交说明
• 策略 B 下 worktree 创建失败（磁盘 / 权限）→ 回退策略 A 流程并说明原因

Output contract

• 单文件 docs/index.html（远程模式为 <repo>-homepage/index.html），HTML 本体 ≤ 200KB，超出需在报告说明原因
• file:// 双击可开，推上 GitHub Pages（/docs 源）即发布完成态，无需任何构建
• OG / Twitter meta、favicon、JSON-LD 齐全；分享出去有社交预览卡片
• 页面内容 100% 来自仓库真实素材；拿不到的数据不展示、不留占位
• 375px / 768px / 1440px 三档响应式不破版
• 报告注明美感来源（哪个 companion skill 或哪条基线方向）
• 选择部署时：commit 只含本次生成的文件，push 成功后按用户所选发布策略开启 Pages（A：页面随 docs/ 进当前分支提交；B：发布拷贝在 gh-pages 分支根，本地 docs/index.html 仅作预览、不进 main 提交），并报告公开 URL；任何一步失败都停在原地说明原因——绝不 force push、绝不静默切换已有的 Pages 源、绝不动用户没让动的仓库设置

Failure handling

Examples

输入：本地 Node 库，README 英文、有 3 张截图，环境装了 frontend-design 和 ui-ux-pro-max

操作：扫描 manifest + README + git → 内容清单（英文）→ ui-ux-pro-max 出设计系统（如：Glassmorphism + 蓝紫配色 + Inter/Space Grotesk）→ 加载 frontend-design 后写单文件页面 → 浏览器截图自检 → 写 docs/index.html，拷 3 张截图进 docs/assets/

输出：docs/index.html（约 40KB）+ docs/assets/（3 张图）；报告注明美感来源两个 companion skill；附 GitHub Pages 开启步骤

输入：用户给 https://github.com/foo/bar，本地没有代码，环境无任何设计 skill

操作：远程模式拉 README + API → 基线按项目类型选方向（CLI 工具 → 暗色科技风）→ 图片用 raw URL → 写 bar-homepage/index.html → 无浏览器工具，走清单自检

输出：bar-homepage/index.html 单文件；报告说明可整体拷入目标仓库 docs/ 发布，美感来源为内置基线方向 A

输入：Python 教程仓库，README 中文，用户说"要极简白底的感觉"

操作：用户风格偏好直接映射基线方向 B（清爽编辑风）→ 中文页面 → 章节从简（hero + 学习内容 + 快速开始 + 链接）

输出：docs/index.html 中文极简页；报告注明"用户指定风格，基线方向 B"

输入：主页生成后用户选择"自动部署"；remote 是 GitHub，gh 已登录，仓库没开过 Pages

操作：git add docs/index.html docs/assets/（逐个列出，不带工作区其他改动）→ commit（docs: add project homepage，风格随仓库）→ push 当前分支 → gh api GET pages 得 404 → POST 开启（当前分支 + /docs）→ 轮询构建至 built

输出：报告 https://<user>.github.io/<repo>/ 已上线 + commit hash + 构建状态

输入：主页生成后用户选择"自动部署"，但仓库已有一个从 gh-pages 分支发布的 Jekyll 站

操作：commit + push 照常 → GET pages 发现源是 gh-pages + / → 停下询问是否切换（切换会顶掉现有站点）→ 用户说"别动" → 只报告 push 完成，Pages 保持原样

输出：新主页已在仓库 docs/ 里（随 push 上远端），现有站点不受影响；报告说明原委

输入：用户选择自动部署，并在询问 2 里选"独立 gh-pages 分支"，理由是要保持 main 只放源码

操作：git worktree add --detach .pages-tmp HEAD → worktree 内 switch --orphan gh-pages → 拷贝 docs/index.html 为分支根 index.html → 只 add 该文件 → commit + push origin gh-pages → worktree remove --force → gh api 开启 Pages（gh-pages + /）→ 轮询构建

输出：站点源为 gh-pages 分支；main 未新增任何页面文件，本地 docs/index.html 保留为预览副本（报告注明）；公开 URL 照常给出

与相邻 skill 的边界

Windows (win32) platform notes

流程型 skill：扫描、读取、写 HTML、拷贝图片全用 Read / Write / Glob / Grep 工具，无平台差异。shell 用于 git 只读检测、可选的本地预览（python -m http.server -d docs 8000，python 不可用时提示用户直接双击 index.html）和 Step 7 的可选部署（git add/commit/push、git worktree 与 gh api，均为跨平台命令，Git Bash / PowerShell 通用；gh 未安装时按 Step 7 降级）。浏览器自检用 file:///D:/... 形式的绝对 URL（正斜杠）。拷贝图片到 docs/assets/ 属于文件操作，用工具完成，不依赖 shell 命令。