静态站点 → GitHub Pages
完整工作流:数据 → 独立HTML/CSS/JS页面 → 浏览器验证 → GitHub Pages发布。
目标:1到数百个条目的页面,单个作者,零运行时依赖。
何时使用
| 是 | 否 |
|---|---|
| “用这个列表/表格给我做个页面”、图库、数据仪表盘 | 带后端、认证、数据库的应用 → 请先询问 |
| “把它发布到GitHub/GitHub Pages” | 由框架(Next、Astro、Hugo)生成的站点 → 遵循框架流程 |
| 基于数据(标题、日期、价格……)复现现有页面 | 复制第三方站点的设计/CSS/HTML → 拒绝,重新设计干净版本 |
不可妥协的规则
- 自主设计。 绝不复制第三方站点的CSS、HTML或资源。可以借鉴信息结构,但不得抄袭其视觉规范。
- 事实可复用,作品不可抄袭。 标题、日期、价格、评分、链接 = 事实数据,可复用。文字内容、描述、视觉元素 = 受保护:不得复制。对于图片,使用原始CDN热链接而非提交到仓库(参见
reference/data-and-ethics.md)。 - 遵守访问保护。 若
robots.txt禁止爬取,或有Cloudflare/bot挑战 → 不得绕过。应寻找官方API、密钥,或降级为简单外部链接。 - 始终在真实浏览器中验证 在说“完成了”之前(截图 + 点击测试)。
- 在仓库名/账户不明确时,未经确认不得发布。
- 未经确认不得创建自定义域名。 若用户未提及,询问是否需要Cloudflare重定向以及哪个域名(步骤6)。绝不自作主张创建子域名:DNS是外部可见的副作用。
工作流
1. 框定(30秒)
-
什么数据?多少条目?一次性更新还是定期更新?
-
期望输出:单个页面?排序/搜索?有哪些业务显示规则?
-
发布位置:GitHub账户、仓库名、公开/私有(免费账户的Pages要求公开仓库)。
-
自定义域名——若未明确说明,需显式询问。 一次性提问,并提供默认建议:
是否需要将Cloudflare重定向到
<owner>.github.io(CNAME,proxy关闭)?如果是,使用哪个子域名/路径?名称在技能侧是自由的,但域名创建后立即公开:在没有明确回复前不要创建任何内容。如果用户回答“否”,则停止于
https://<owner>.github.io/<repo>/的URL,不创建DNS条目。
2. 获取数据
一次性脚本 → 一个 data.json = 真实数据源,与渲染分离。
python3 fetch_data.py # → data.json
礼貌要求:请求间隔0.3–0.7秒,显式User-Agent,遇到429/5xx时重试。
详情及易错情况(PoW Anubis、Cloudflare、模糊匹配、无密钥API):参见 reference/data-and-ethics.md。
3. 生成页面
基于模板,而非从空白开始:
cp .dsh/skills/static-site-publish/templates/{index.html,styles.css,script.js} ./site/
cp .dsh/skills/static-site-publish/templates/build.py ./site/ # data.json → index.html
python3 ./site/build.py
build.py:小型Python生成器(f-string +html.escape),将数据注入卡片网格。数据无需运行时JS。styles.css:默认暗色主题,auto-fill minmax()网格,CSS变量。script.js:即时搜索 + 排序 + 打开时计算的显示规则(使页面无需重建即可保持正确)。- 一切可在显示时计算的内容(状态、相对日期)都应使用JS实现:避免每天重建站点。
- HTML应在无JS时保持可读,JS应为渐进增强。
4. 验证
.dsh/skills/static-site-publish/scripts/verify-site.sh ./site/index.html
在Chrome无头模式下打开页面,写入 /tmp/site-shot.png,并运行点击重叠测试。查看截图(read_image 工具)后再做结论。
检查清单:桌面端和移动端渲染、数据完整(计数条目)、链接正确、无重叠。
5. 发布
.dsh/skills/static-site-publish/scripts/publish-gh-pages.sh ./site my-repo-name
脚本:gh auth status → git init/commit → gh repo create --source --push → gh api POST /pages → 轮询URL直到返回200 → 显示最终URL。
Pages的延迟为 20到90秒:在循环确认返回200之前,不要断定“它不工作”。还应验证 gh api repos/{owner}/{repo}/pages/builds/latest --jq .status = built。
6. 自定义域名 + Cloudflare
仅在用户要求时(参见步骤1)。DNS是公开的:不要将模糊的“是”重新解释为由AI选择的域名。
强制顺序:DNS优先,证书其次,Enforce HTTPS最后。 站点应已在 *.github.io 上返回200后再开始。
a. 在Cloudflare配置DNS重定向(MCP Cloudflare)
前提令牌:作用域 zone.read + dns.write(Zone Read / DNS Edit)。若缺少,停止并请求扩展——不要绕过。
GET /zones?name=<根域名>→zone.id。若零个zone:域名不在该账户中,请询问。GET /zones/{zone_id}/dns_records?name=<完全限定域名>→ 若已有相同的CNAME,则不重新创建(幂等性)。POST /zones/{zone_id}/dns_records:
{ "type": "CNAME", "name": "<子域名>", "content": "<owner>.github.io",
"proxied": false, "ttl": 1 }
proxied: false= 仅DNS,不可协商:Cloudflare代理会阻止GitHub颁发证书。- 目标为
<owner>.github.io,末尾无斜杠,不含仓库名(如jamesdadams.github.io,而非.../my-repo)。 ttl: 1= 自动。
- 通过公共解析而不是仅通过API验证:
dig +short <完全限定域名> CNAME @1.1.1.1 # → <owner>.github.io.
dig +short <完全限定域名> A @1.1.1.1 # → 185.199.108-111 .153
b. GitHub Pages端的域名 + Enforce HTTPS
.dsh/skills/static-site-publish/scripts/set-pages-domain.sh <owner>/<repo> <域名> ./site
脚本:在站点中写入 CNAME 文件(它在重新部署后仍然存在,避免丢失域名)→ PUT /repos/{owner}/{repo}/pages,带 cname 参数 → 等待 https_certificate.state = approved → 激活 https_enforced: true。
⚠️ https_enforced: true 在证书不存在之前返回 400。实际延迟:CNAME创建后5到20分钟。这就是脚本循环而不是失败的原因。在证书颁发之前不要手动勾选“Enforce HTTPS”,在此期间不要断定失败。
c. 最终验证
curl -sI https://<域名>/ | head -5 # 200 + server: GitHub.com 头部
然后在浏览器中重新打开页面(步骤4)使用自定义URL:返回200并不能证明相对路径(styles.css、script.js)能够解析——这是在域名根目录提供project pages时的经典陷阱。
7. 使更新成为可能
- 将git目录放在用户的项目目录中(而非
/tmp,重启后会被清除)。 - 在
README.md中记录:数据来源、如何重新运行提取、哪些是固定的(数据)vs 动态的(JS中计算的规则)。 - 明确告知用户哪些内容不会自动更新。
已遇到的陷阱
| 症状 | 原因 | 修正 |
|---|---|---|
| 403 “Just a moment…” | Cloudflare挑战 | 记录限制、官方API或外部链接;不要试图绕过 |
| 页面截断 “Making sure you're not a bot” | PoW Anubis | 解决挑战(参见reference)或要求用户导出 |
| 选择器返回0结果 | 错误模式(如 /games/lib/genre: 而非 /games/lib/popular/genre:) | 打印HTML样本并在循环前对1页测试正则表达式 |
| 点击卡片未打开正确链接 | <a> 层被定位的子元素覆盖 | 在装饰元素上使用 pointer-events: none;使用 elementFromPoint 测试 |
| GitHub Pages前几分钟404 | 构建进行中 | 轮询至多90秒 |
| 某列数据为空 | 源端标签可变(“Released” vs “Early Access”) | 宽容的模式 + 每项日志,绝不使用无声的 except: pass |
https_enforced 返回400 “certificate does not exist” | 证书尚未颁发 | 等待 https_certificate.state = approved(5-20分钟),脚本循环 |
| 自定义域名30分钟后404 | CNAME缺失/所有权错误/仓库中缺少 CNAME 文件 | 使用 dig 确认CNAME,重新运行 set-pages-domain.sh |
| 启用代理后HTTPS损坏 | 记录变为代理状态 | 改回 DNS only(proxied: false),GitHub证书无法通过代理验证 |
| “Domain is already in use” | 域名已在同一账户的另一个仓库上声明 | 每个仓库一个自定义域名;先释放旧域名再重新分配 |
自定义域名下CSS/JS返回404,但在 *.github.io/repo/ 下正常 | 在根目录提供project page时使用了绝对路径(/styles.css) | 使用相对路径(styles.css) |
参考
reference/data-and-ethics.md— 数据提取、PoW Anubis、Cloudflare、许可证、图片热链接reference/design-and-verify.md— 最小设计系统、浏览器测试、可访问性reference/publish-gh-pages.md—gh命令、命名、域名、故障排除scripts/publish-gh-pages.sh— 发布 + 激活Pagesscripts/set-pages-domain.sh— 自定义域名 + Enforce HTTPS(在Cloudflare CNAME之后)scripts/verify-site.shtemplates/{index.html,styles.css,script.js,build.py}