mirror of
https://github.com/jnMetaCode/superpowers-zh.git
synced 2026-09-02 22:54:06 +08:00
932ffdcd01
上一轮我把官网审计做成了纯技术体检（robots / CSP / 图片字节 / og 标签），扫的是
「哪里不对」，没扫「访客需要什么、站上却没有」。按内容维度重查，查出两个比那些
重得多的空洞。
## ① v1.7.11 的核心信息，官网完全没有
这个版本的全部意义是一句话：Codex CLI / VS Code / Windsurf / Qwen Code / DeerFlow /
Claw Code 六款此前装了不生效，请重装。而官网上关于这件事的表述实测为零：
重新安装 / 变更 / 更新日志 / Release / RELEASE-NOTES 首页出现 0 次
重装 1 次，但在全局安装 FAQ 里，与本事无关
v1.7.11 1 次，就是统计块里那个数字
**上周装过的用户今天来站上，没有任何途径知道自己装的那份是坏的。** README 顶部有
整块更新亮点，官网一个字都没有。
hero 下方加一条可点的版本提示条（三语），点进 RELEASE-NOTES。版本号不手写：从
RELEASE-NOTES.zh.md 的最新条目解析，再与 package.json 交叉校验 —— 两边漂了直接
构建失败。需要重装的工具列表抽成 REINSTALL_TOOLS 常量，三语共用一份。
## ② docs/ 里 22 份工具安装指南，官网零暴露
全站链接到它们的次数：0。而官网「安装」区全文只有 378 字，内容就是「选工具 →
复制命令」。那 22 份文档里装的恰恰是这里缺的：
docs/README.codex.md ## ⚠️ v1.7.10 及更早的项目级安装装错了地方
docs/README.kiro.md ## ⚠️ v1.7.9 及更早版本请重新安装
docs/README.windsurf.md > 📌 --global 装到了 Windsurf 不读的目录，等于装了不生效
Kiro 用户想知道「为什么要重装、旧布局怎么清」，站上没有出口。
工具墙的 pill 改成：有专属文档的 20 款直接链过去（带 ↗ 与 title 提示），没有文档的
3 款（Claude Code / Cursor / Copilot CLI）保持纯文本，不造不存在的链接。
## 新增三条构建期门禁（都反向验证过）
| 门禁 | 造错 | 实际拦下 |
|---|---|---|
| release notes 与 package.json 版本一致 | 把条目改成 v1.7.12 | `版本漂移：package.json 是 1.7.11，RELEASE-NOTES 最新条目是 v1.7.12` |
| 工具文档必须存在 | doc 改成 windsurfff | `工具 Windsurf 的文档不存在：docs/README.windsurfff.md` |
| release notes 结构可解析 | 抹掉版本标题 | 退回上一条目并报版本漂移，而不是静默渲染空版本 |
第二条尤其必要：官网链到 GitHub 上一个不存在的 docs 文件，就是又一条「编造出处」,
而本仓已经因为编造链接栽过一次（033adc3）。
## 验证
- 三语版本条渲染正确，链接指向 RELEASE-NOTES.zh.md
- 工具墙：可点 20 款 / 纯文本 3 款，与 docs/ 实际拥有的文档一一对应
- **20 条文档链接逐条 curl，全部 200**（不抽样）；RELEASE-NOTES 链接 200
- 官网 66 页构建，站内死链 0、无效 href="#" 0、缺 height 的 img 0
- audit 170 pass 0 fail；verify-release 115 pass 0 fail
- tests/kimi · pi · opencode · brainstorm-server 全 PASS
superpowers-zh 官网
零依赖静态站生成器。一条命令产出中/英双语站点 + 每个 skill 的详情（操作文档）页，内容全部来自 ../skills/*/SKILL.md，与源文件同步、不会漂移。
构建 / 预览
node site/build.mjs # 生成 site/dist/（66 个页面）
npx serve site/dist # 本地预览（或 python3 -m http.server）
产物结构：
dist/
index.html # 中文首页
sponsors.html # 中文赞助商页（每种语言一份）
en/index.html # 英文首页
skills/<name>.html # 中文 skill 详情（操作文档）× 20
en/skills/<name>.html # 英文 skill 详情 × 20
styles.css app.js # 深/浅主题 + 交互（原生 JS，零依赖）
assets/ # 图标 + 公众号/抖音二维码
_headers # Cloudflare Pages 缓存策略
特性
- 中英双语：服务端生成两套真实页面（非前端切换），SEO 友好、无闪烁。导航栏「中文 / EN」互切。
- 深 / 浅主题：CSS 变量 + localStorage 记忆，内联脚本在首屏前生效，无白屏闪烁。导航栏 ◐ 按钮切换。
- Skill 详情页：内置零依赖 Markdown 渲染器（
md.mjs），把每个SKILL.md渲染成完整操作文档，支持标题/代码块/表格/列表/引用。 - 安装命令生成器、Skill 搜索 / 分类筛选、一键复制 —— 全部原生 JS。
改内容改哪里
| 想改什么 | 改哪里 |
|---|---|
| Skill 正文 / 文档内容 | 源头 skills/<name>/SKILL.md（改完重新 node site/build.mjs） |
| Skill 中/英标题、英文简介、分组 | site/build.mjs 的 SKILL_META |
| 首页所有文案（中/英） | site/build.mjs 的 T.zh / T.en |
| 支持工具 / 安装命令 | site/build.mjs 的 TOOLS（与 bin/superpowers-zh.js 的 TARGETS 对齐；每条的 mode = auto 自动识别 / manual 必须 --tool / global 只有 --global 才生效）。条目数由 scripts/audit.sh 卡死 = TARGETS 条目数 + 1（Copilot CLI 单独计数） |
| 赞助商（logo / banner / 文案 / 链接 / 优惠码） | site/build.mjs 的 SPONSORS（logo 小图标 + img 大 banner 都放 assets/sponsors/，构建时自动拷进 dist/assets/sponsors/）——首页不放赞助内容，全部在 sponsors.html。改完同步改 README.md / README.zh-Hant.md 的赞助商区块 |
| 赞助商页文案 / 赞助权益 / 赞助 FAQ | site/build.mjs 的 T.<lang>.sp |
| 谁上旗舰位 | SPONSORS 里该条的 tier：'flagship' 用大 banner 单独成块（读 img + w / h，不读 logo），其余是紧凑卡（读 logo，简介截 4 行）；没有 flagship 时该区块渲染成「虚位以待」招商卡。改 tier 时字段要跟着换 —— 构建期 assertSponsors() 会校验字段齐全、素材文件存在、三语文案不缺，缺了直接构建失败 |
| 样式 / 主题 | site/template/styles.css |
| 交互逻辑 | site/template/app.js |
| Markdown 渲染规则 | site/md.mjs |
部署到 Cloudflare Pages
发布目录 site/dist，三选一：
方式 A — 连接仓库自动构建（推荐，无需密钥）
Cloudflare Dashboard → Pages → 连接 GitHub 仓库 jnMetaCode/superpowers-zh：
- Build command：
node site/build.mjs - Build output directory：
site/dist
之后每次 push 自动重建发布。绑自定义域名（当前线上：sp.aiolaola.com）。
方式 B — 命令行一键发布
npx wrangler login # 浏览器登录（交互，仅首次）
npm run site:deploy # = 构建 + wrangler pages deploy site/dist
在本会话中可用
!前缀直接登录：!npx wrangler login
方式 C — GitHub Actions 自动部署
仓库已含 .github/workflows/deploy-site.yml。在 Settings → Secrets and variables → Actions 配置：
CLOUDFLARE_API_TOKEN（Pages 编辑权限）CLOUDFLARE_ACCOUNT_ID
之后 site/ 或 skills/ 变更 push 到 main 即自动部署。
国内访问优先用 Cloudflare Pages + 自定义域名；GitHub Pages 在国内访问较慢，不建议作为主站。