AnvilWiki AGENTS.md

AGENTS.md

Workspace instructions for ZCode agents working on AnvilWiki.

Repository Purpose

AnvilWiki is an open-source (MIT) game wiki site template built with Astro 5 + Cloudflare Pages. It is a static-first Astro setup that deploys to Cloudflare with zero adapters and enjoys free unlimited bandwidth.

Goal: let beginners deploy a game wiki site to Cloudflare Pages for free (unlimited bandwidth) in ~30 minutes, with strong SEO, i18n, and ad-monetization built in.

Status (as of 2026-09-03): 当前最新 v2.14.1(文档中心全站搜索+GSC API 接入引导+顶栏搜索胶囊;学习手册 6 阶段 29 课+3 附录、开发手册 9 课)（发版历史见 Releases；下列批次按时间叠加）。v2.0.0 released — 内容经营操作系统（四件，模板仓库零 breaking，fork 常规 merge 零迁移）: ① auto-content.yml PR 门控内容管道（workflow_dispatch + 确定性生成器 import-csv→pnpm bulk-new-posts → 八道门禁前置（全绿才开 draft PR，GITHUB_TOKEN PR 不自动跑 CI 故验证前置）→ create-pull-request@v8 固定分支幂等；LLM 永不进 CI、secrets 零引用；门禁抽成共享 composite action .github/actions/gates（ci.yml 同源复用，tests/workflows.test.ts 钉契约）；ADR-004）② anvilwiki-ops 0.1.3→1.0.0（多站注册表 ~/.config/anvil-ops/sites.toml（凭据永不入表）+ --site/--all + sites list/add/remove，submit 拒绝 --all；AI 引用追踪三通道：CF Web Analytics AI referrals（referrer host 聚合 chatgpt/perplexity/gemini/claude/copilot）+ GSC AI_OVERVIEWS 探测（experimental）+ metrics --import-aio <csv> 导入 GSC gen-AI 报告；MCP 五工具加可选 site 参数 = 1.0 唯一 breaking；测试 60→111；ADR-005）③ pnpm gen-covers og:image 封面生成（satori+@resvg/resvg-js+subset-font；封面标准 800×450→1200×675（Google Discover 大图 ≥1200px）+ 全站 BaseLayout 补 max-image-preview:large；品牌色运行时读 globals.css；CJK 标题按字符子集 Noto Sans CJK（OTF 缓存 node_modules/.cache/gen-covers/fonts/ 不进 git）+ 内置 OFL Lato（scripts/fonts/）；manifest hash 缓存；demo 5 张封面已重生成 1200×675）④ AffiliateSuggestion 文末建议位（src/config/affiliates.ts 默认空=不渲染；复用 AffiliateLink 卡片 + shared.sponsoredLabel i18n en/ja；config 门控非 env）。文档: docs/content-pipeline.md + docs/multi-site.md 新增并进 docs/README 索引、手册 ai-ops 章双语补多站/管道/AI 引用（章数不变 learn 11/dev 7、提示词 18 不变）、ADR-004/005、staying-up-to-date.md MAJOR 措辞修订（里程碑 major）、roadmap.md 演化表 + v2.0 行、PRD §14.2 消歧旧 v2.0 撞号 + 更新记录补齐、README 中英特性升级 + 修 :226 8-chapter 漂移、CHANGELOG compare 链接补齐 1.15.0–1.19.0。决策记录: docs/superpowers/specs/2026-08-22-v2.0-content-os-design.md。Astro 刻意锁 5.x（7 已 GA，5→6→7 迁移留独立小版本，见 roadmap 候选池）。Prior v1.x 历史: 见 CHANGELOG.md 与 docs/roadmap.md 演化主线表。Live demo: anvilwiki.pages.dev (Lighthouse 4×100)。次日审计加固批（v2.0.1，详见 CHANGELOG [2.0.1]）:category 改 schema enum 硬门禁（软 404 根除）/check-i18n --strict-ui 让第八道门禁真正能红/setup.yml 开 PR 前跑 build 验证/auto-content add-paths+--require-output（CSV 不再入库、零产出响亮失败）/ci.yml 新增 ops-toolkit job（ops 测试进主 CI）/sitemap hreflang 按真实 MDX 覆盖生成（与页面级声明一致）/ops:MCP 站点解析不再吞错、GSC HTTP 错误带修复指引、audit/submit 走 worker 线程不冻结 stdio、测试 111→125/release-ops tag↔版本守卫。SEO 实战文档批（v2.1.0，2026-08-26，详见 CHANGELOG [2.1.0]，零代码变更）:新增 docs/sourcing.md（挖词 9 渠道 + 第 7 条判断「意图满足度」+ 选词决策管理表）、docs/ads.md（广告时机 + Adsterra 收款 USDT/Payoneer 双路线）、requirements/ 内容准备两模板（事实来源表 + 对标参考表）；seo.md 增外链策略章、deployment.md 增数据复盘指标 + Clarity 热力图、game-selection.md 定调首版 10-15 篇核心页分批上线（生成可 40-60 篇、部署分批）；学习手册第 7 章中英补「先说时机」。手册同步+初始化规范批（v2.1.1，2026-08-26，详见 CHANGELOG [2.1.1]）:学习手册 7 章双语接 v2.1.0 文档层（ch1 挖词 9 渠道+意图满足度/ch4 requirements 准备表+首版 10-15 篇分批/ch6 复盘指引/ch8 四条及格线指标表+Clarity/ch10 翻正节奏/ch11 外链策略/ch7 统计三件套 GA4+CF+Clarity 完整教程）;docs/apply-template.md 新增「初始化清理规范」章节（两通道删除清单首次文档化）;setup.yml zh 删除路径收窄+CLI wrangler vars 对齐（两处通道漂移修复）;en/weekly-ops tldr 超 480 上限修复。变现+外链实操文档批（v2.2.0，2026-08-26，详见 CHANGELOG [2.2.0]，零代码变更）:docs/ads.md 三新节——AdSense 收款完整教程（W-8BEN 10% 协定税率/PIN 明信片 4 次寄送+4 个月期限/电汇绑卡/21 日出账 20 日截点/结汇）、Adsterra 接入教程（五广告格式取舍表+Google 广告投放位置政策「挂 AdSense 的站禁触发 popunder」共存红线+脚本粘贴位置 BaseLayout.astro/ArticlePage.astro）、广告平台全景三档表（2026-08 实时门槛:Journey 1k sessions/Mediavine $5k 年收入门槛/Raptive 25k PV）+ 游戏垂直网络层（NitroPay 100k PV·NET-7·官方定位 niche gaming wikis/Venatus/Playwire/PubNation，全景表 11 平台全挂官网直链）+ 游戏 wiki 五档分阶段路线表;docs/seo.md 外链章扩到操作层（九渠道优先级清单+逐渠道步骤+三份英文 outreach 邮件模板+免费工具箱 Ahrefs/Hunter.io+做多少节奏节;HARO 2024-12 关停 2025-04 复活/Reddit 10% 全站规则调研校准）;手册第 7 章双语「第三步:收款三件事」节+tldr 两步走改三步走;Adsterra 起付信息对齐 2026 官方口径（USDT $100/Paxum $5/首两笔 $20）。新手动线优化批（v2.3.0，2026-08-26，详见 CHANGELOG [2.3.0]）:README 全面重构（新手动线三硬伤修复:pnpm 前置一行安装+快速开始补「push 回 fork」步骤+新增零终端 Actions→Initialize AnvilWiki 通道;wrangler.toml 警告从第一屏下沉到部署步骤提示框;特性区 9→10 条每条≤2 行细节链接化;双语文档导航收敛为 4 入口消除与 docs/README.md 双头漂移;英文区补快速链接表对齐中文区;语言切换锚点+首屏 demo 截图+CONTRIBUTING/CHANGELOG 链接+中文区补 License 行;删指向上游仓库的误导性 Deploy 按钮、Docs 徽章改链英文站;#5-分钟快速开始 锚点保留供 deployment.md 反链）;目录微调（Comments.astro 断链 spec 引用改指 docs/comments.md/PRD §15.2 文档策略表 7→20 项补齐/roadmap.md 版本头 v2.0.1→v2.2.0/ROADMAP-v1.5-v1.6.md 归档至 docs/superpowers/ 含 docs/README+PRD 两处引用同步）;落地页转化批（hero 与 FinalCta 主 CTA 改 Fork 直达 github.com/PNGTRID/AnvilWiki/fork/docsEntry SEO 卡与 devGuide 五步链接全部改站内手册章消除出站泄漏/landing.ts 写死章数 6 处移除（Hub 卡片本就动态计算）/two-digit stars 措辞去时效/公告条压缩一行/hero 副标题压缩;截图链接复用 tertiaryCta 故保持指向 Demo）;手册批（templatize-your-site 与 sync-and-contribute 两章「下一步」补 markdown 链接×双语/HandbookHub 新增 beginnerHint 零基础 start-here 胶囊,landing.ts 接口+en/zh 数据+组件三处联动）。紧急修复批（v2.3.1，2026-08-27，详见 CHANGELOG [2.3.1]）:tailwind.config.mjs 根除 ESM 文件内 CommonJS require() 地雷（插件行自 v0.1.0 写作 require('@tailwindcss/typography'),靠 Tailwind 加载器「原生 require 同步抛错才回退 jiti」侥幸存活;jiti 回退掩盖缺陷多年,但部分 Node 构建 require(esm) 路径把配置内 ReferenceError 以异步 unhandledRejection 上报、catch 接不住,fork 用户下载 ZIP 后 pnpm dev 首次访问即崩——Windows 用户截图报障实证）;改为纯 ESM import typography 导入,双加载路径最小复现+build/typecheck/lint/test 全绿验证,全仓扫描确认无其他 .mjs 含 require()。三站踩坑复盘加固批（v2.4.0，2026-08-29，详见 CHANGELOG [2.4.0]）:依据《Aniimo/No Man's Sky/Steal An Egg 三站生产事故复盘》（48 类问题）审计落地 16 项——trailingSlash never→always 全站翻转（localizePath 龙头/sitemap normalizePath 归一化/Pagefind 保斜杠/SiteHeader 高亮防 ///landing.ts 46 处/demo 内容迁移;⚠️ fork 行为变更,全站内链需跟随,check-content 新规则会拦,_redirects 反向重定向禁用）;空分类/空语言列表页 noindex+移出 sitemap+hreflang 按真实覆盖（config 侧 categoryCoverage 与页面侧 localesForCategory 同真相,防 Google 丢弃冲突簇）;文章级 faq frontmatter 字段（可见 <details> 区块+与 codes FAQ 合并单个 FAQPage JSON-LD;新 i18n 键 shared.faqTitle en/ja）;pageTitle 三分支智能后缀（含游戏名不加/>50 字符用 shortName/BaseLayout 三身份名防双拼）;相关文章三层兜底（tags 交集→同分类→全站最新仅零匹配时;纯函数 selectRelatedEntries 下沉 content-utils 可测）;新脚本 pnpm submit-indexnow（fs 读 dist sitemap→IndexNow 分批 POST,密钥自动检测/生成 public/<key>.txt,--dry-run 零副作用）+ pnpm gen-assets（品牌色原地生成 favicon 全套 svg+5 PNG/hero.webp 1200×630/manifest theme_color 同步,零引用改动;缓存在 node_modules/.cache;favicon.ico 因 sharp 不支持 ICO 有意保留不引用,BaseLayout 改指 svg+png）;check-content 新规则 5（非默认语言正文内链必须带语言前缀,error 级——Aniimo 177 处静默跳英文事故）/规则 6（正文 <3 条站内链接 warning）;文档批（deployment.md「唯一部署源」🚨 警告+「先绑域名→改 SITE_URL→再部署」顺序铁律+Crawler Hints/IndexNow 指引;ads.md Adsterra 教程改写 iframe sandbox 隔离模式+「怎么验证广告真的在展示」;content-format.md 关键词密度 1-3%+≥3 内链+先有文章再进 navigation;手册第 6 章双语 IndexNow 第 4 步+GSC 网页索引四状态灯;两 skill 内链口径反转）;小件（twitter:card 全局 summary_large_image/footer 补 /recent //tags 入口零新增 i18n 键/版权行与免责声明分行渲染修短路/.gitignore 密钥模式 *-secret.json/*.pem/*.key/seo-reports/）。StickyBanner 桌面 sticky 复核后保留（复盘 #37 针对 Adsterra 320×50 移动条桌面误显;本模板为 728×90 AdSense leaderboard+dismiss+CLS 预留,场景不同源）。八门禁全绿（lint/typecheck/test 96/check-config/check-content/check-i18n --strict-ui/build/check-links 3681 链接全通）。spec: docs/superpowers/specs/2026-08-29-retro-hardening-batch.md。CLI 真实模式 E2E 加固批（v2.4.1，2026-08-31，详见 CHANGELOG [2.4.1]）:合并首个外部代码贡献 PR #10（oyjq0000——apply-template removeLandingPage 先 rmSync 后 readdirSync 同路径,真实模式必崩 ENOENT,自 v1.12 存活;删后读模式全仓仅此一处,setup.yml bash 通道无恙）;全仓同类排查再清两处——home 模板 schema 漂移（CLI 写出 home.meta 仅 {watermark} 缺 title/description→HomePage 传 undefined 进 BaseLayout title.includes 崩;hero/closingCta 的 CTA 写 {label,href} 对象而组件按字符串渲染→fork 用户 CLI 初始化后首次 build 必炸;模板全量对齐 demo en.json 形态+HomePage meta 逐字段兜底+authors 清理虚报 ✅ 修为确实移除才打印）;新增 apply-template --answers answers.json 非交互模式（与交互同一 ask/askBool 路径,答案不足/多余均响亮报告;readline 管道驱动会丢行不可用）与 pnpm test:e2e（scripts/e2e-apply-template.mjs:git archive HEAD→临时目录装依赖→真实模式跑 CLI→断言输出形态→对产物完整 build;测的是提交树）+ ci.yml e2e-template job + workflows.test.ts 契约钉防删——八门禁抓不住『仅真实模式触发』类 bug,三个前科全在此类。八门禁全绿（test 97 含新契约）+E2E codes/guides 双预设全绿。生态技能吸收批（v2.5.0，2026-08-31，详见 CHANGELOG [2.5.0]）:向两个开源技能项目致谢并吸收方法论——① 新增 .agent/skills/anvil-adsense-audit（AdSense 申请前逐项体检:22 项 AD-* 清单四态判定+Blocker/High/Medium 分级+完整性门+Blocker 未清零不许建议提交;模板已解决项 ads.txt 占位/法律页路由/env 门控零广告/noindex 空分类预填证据,审计火力集中 fork 用户侧;主动提示模板无 robots.txt、用户自加不得挡 Mediapartners-Google;审计框架 inspired by yantoumu/adsense-site-auditor-skill——该仓库无 LICENSE,清单自 Google 公开文档模板特化重写未复制文本,技能内文末致谢）;② docs/sourcing.md 第四节「判决框架」（搜索需求轨七项打分参考+KD 分档动作表+早期爆发轨+两条防自欺判据「平台内流量≠独立需求/未测≠零」+新词 3/7/14/28 天复查节奏;参考 yan-labs/yan-skills 的 game-opportunity,MIT,节末致谢）+ game-selection.md 第 3 层互链;③ docs/seo.md 外链章新节「怎么验证外链真的生效」（已提交≠已公开≠已收录三态+跳转计数链/rel 属性两暗坑+743 条清单实测 5.5% 可用现实校准+推荐 yan-skills backlink 机读入口库）;④ 手册双语零 tldr 改动小节（enable-ads「懒人通道」接 /anvil-adsense-audit、weekly-ops「复盘纪律:只认面板上的数」）;⑤ 致谢三处（README 中英 Credits 段/官网落地页 footer en+zh 新增致谢行——landing.ts footer 接口加 creditsLabel+credits 字段、LandingLayout 渲染,fork 时 landing 整体移除不受影响/docs README 致谢节）。零代码行为变更。AdSense 审计实证批（v2.5.1，2026-08-31，详见 CHANGELOG [2.5.1]）:按 /anvil-adsense-audit 对 demo 站跑 22 项全项体检——裁决 Not ready(demo),缺口全部在内容经营侧(en 5 篇<15/codes 页 8 天 P0×2/items 空分类/pages.dev 域名),模板机制层零 Fail;据此实证修正技能判定基准——🚨 AD-17 原判定错误已改:法律五页是代码层组件 LegalContent.astro 内置正文(非空壳路由),隐私页本就含 Google AdSense 广告 cookie 披露段(线上渲染确认),默认 Pass,仅 fork 用户改写该组件才复查;docs/ads.md 新节「申请 AdSense 前的体检」六组速查表(canonical 归技能维护)+ demo 审计基线实例。Demo 内容整备批（v2.6.0，2026-08-31，详见 CHANGELOG [2.6.0]）:依据 seo.web.cafe AdSense 预检报告核查整改——9 篇 en 文章全部 800-1284 词(原 170-665),新增 4 篇成型页(items/forging-materials-guide + items/emberforged-armor-set 补齐空 items 分类 + bosses/frostbound-monarch 冰元素镜像 Boss + guides/forging-guide 锻造数学),sitemap 101→120 URL;🚨 页脚 SiteFooter legalLinks 补 contact(页有链无的信任页缺口)+ footer.contact UI 键 en/ja;ads.txt 内置就绪授权行(过审删 # 填 ID 即用,未过审保持注释态);🚨「Updated daily by the community」不实文案(en/ja ×2)改「逐篇标注验证日期」诚实口径——fork 用户 takeaway:不要虚称社区/更新频率,写你能兑现的;预检报告 3 项误判已核查标注(身份漂移=fork 时自动移除的 demo 专属层、ads.txt=设计使然、CMP=env 门控误测)。Fork 路径加固批（v2.6.1，2026-08-31，详见 CHANGELOG [2.6.1]）:完整 fork 模拟（git archive→apply-template --answers→build→产物体检 template-audit/check-config）抓出五个开箱陷阱并全修——① 联系页零渠道(official 不在列表+无邮箱;修:official 恒渲染+可选 site.contactEmail 三处同步+去硬编码 Discord 措辞);② CLI 写出模板虚假承诺(description "Updated by the community"/徽章 "Updated daily"/hero "tested daily");③ rewriteLocaleJson 清空 nav/overview 致 fork 首次 check-config 七项红+导航裸 key(修:按所选栏目自动填 nav+overview,titleCase 对齐脚手架);④ demo ja.json 残留=身份泄漏+check-config 红(「无害孤儿」结论推翻,未选语言 locale 文件直接删);⑤ wrangler [vars] 正则锚点吃到注释里的字样(双 [vars] 段;修:行首锚定;🚨 JS 正则两坑:\Z 是字面量 Z、m 标志下 $ 是行尾;demo FORKER 警示块重写后移除);另 DEMO_COVERS 漏 v2.6.0 新 4 封面+setup.yml 同步;E2E 新增 check-config 步骤+五条断言钉死——修复前 fork check-config ❌7 项/template-audit ❌9/11,修复后 ✅0 项/✅11/11。CLI 输入层修复批（v2.6.2，2026-08-31，详见 CHANGELOG [2.6.2]）:用户报障 issue #12「默认值按回车没反应,输入默认内容才能继续」——根因是 readline/promises 的 rl.question() 每次提问挂一次性 'line' 监听器,readline 不缓存「没有提问挂起时」到达的行;真 TTY(raw mode 逐键送达)永不触发,但一切缓冲型 stdin 通道(管道/AI agent 终端/多行粘贴/CI)必然触发——多行一个数据块到达,只有第一条被消费,其余静默丢弃;本仓库自己的历史教训「readline 管道驱动会丢行」(v2.4.1 E2E 为此绕道 --answers)正是同一 bug,当时绕过未根治。修复:新增 scripts/lib/prompt.ts 的 LinePrompt 常驻 FIFO 行队列(构造时挂唯一 'line' 监听器,任何时序零丢行;EOF 视为裸回车→printf '' | pnpm apply-template --dry-run 全程默认跑完,Proceed 门(默认 false)EOF 仍安全中止);apply-template/new-post/new-locale 三个交互 CLI 全部迁移,apply-template 顺带收敛单一 readline 实例(原 Proceed 框再开第二个 interface 的并列实例消掉);tests/prompt.test.ts 7 条(5 行为+2 静态契约:三 CLI 禁止再直调 rl.question、必须走 lib/prompt——防接线回退);管道 17 行逐值落位+纯回车全程+expect PTY 交互三通道验证,test:e2e 真实模式绿;另修 CHANGELOG [Unreleased] 指针停在 v2.4.0 连续 6 版漂移;demo ja codes 页补齐 en v2.6.0 扩写结构+lastModified 同步(issue #11 自动审计 P0 清零,refresh-audit 0 items——🚨 双语言 demo 内容批必须两语言同步动 lastModified,否则保鲜审计单边红);八门禁全绿(test 104)。apply-template 重跑安全四连修（v2.6.3，2026-09-01，详见 CHANGELOG [2.6.3]）:当日 24h 只读风险审计（五类:运行错误/数据丢失/权限绕过/资源泄漏/跨端兼容）P1-P4 同日落地——① locale 删分两类(新常量 DEMO_LOCALES=['en','ja'] 自动删;用户上轮或 new-locale 加的改 orphanLocales 响亮警告保留,不加新 prompt 故 --answers 18 项位置序不变);② clearDemoAssets 废 DEMO_ASSET_DIRS 整目录 rm -rf,改 DEMO_GALLERY_IMAGES(6)/DEMO_ARTICLE_IMAGES(2) 按名删(public/images/articles 正是 content-format.md 让用户放内文图的目录),setup.yml 同步 rm -f,静态契约测试钉两通道 .png 集合相等;③ rewriteLocaleJson ownable 过滤未选分类 nav 残留键+覆盖序反转(fixed<占位符<上一轮标签,重跑保用户已译;overview 整体替换有意保留——留旧值会泄漏 demo 游戏文案);④ wrangler [vars] 正则 \r?\n 容错+插入块跟随文件 EOL;配套纯函数下沉 scripts/lib/apply-rewrites.ts(SkinInput/slugify/buildHomePreset/rewriteLocaleJson/rewriteWranglerVars 纯签名+三清单;沿用 lib/prompt.ts 先例,vitest 直测),新增第 11 套件 tests/apply-template.test.ts(test 114),E2E 步骤 4.5 重跑断言(ja 删/ko 保留/二次运行幂等);八门禁全绿+E2E 双预设绿;发版提交 fd8dc23(文档清扫二轮)+cfa43e8(修复)+本定版。🚨 E2E 新坑:spawnSync 断言 CLI ⚠️ 警告须拼 stderr(console.warn 不走 stdout)。视频源工作流批（v2.7.0，2026-09-02，详见 CHANGELOG [2.7.0]）:anvil-new-article 新增 Step 0——素材是 YouTube 视频时抓字幕(用户粘贴/yt-dlp/youtube-transcript-api 三通道,按依赖从少到多)→结构化提取(核心话题→Step 1 判型/kebab-case slug/title/description/summary 直答/5-8 组 faq/问题式 H2 大纲/tags 复用词汇表)→MDX 草稿;双红线(口播数值/兑换码一律视为未验证素材,成品必须 draft:true 人工核实才转正;他人视频字幕只做事实参考、正文必须完全重写——演绎内容的 DMCA/重复内容风险,嵌入原视频为合规做法,缩略图 maxres→hq 仅作 gen-covers 视觉参考);致谢 kennyzir/7deer_skills(MIT)youtube-content-gen 五处同步(技能文内/README 中英 Credits/docs README/landing footer en+zh);实现层四硬伤裁决不抄(生成 Next.js tsx 代码/模板硬编码 Devil Hunter Nexus 站身份/JSON-LD 把 FAQPage 嵌 Article mainEntity 且 Jinja2 变量不转义/关键词模式靠 Google SERP 爬虫且查询硬编码站名);顺手修 PRD 架构树技能列表 v2.5.0 漏更(4→5 补 anvil-adsense-audit);门禁 typecheck/lint/test 114/build 全绿。apply-template 重跑安全加固+文档漂移修复（v2.7.1，2026-09-02，详见 CHANGELOG [2.7.1]）:90147f8 两项——① demo locale 删改内容判定（isDemoLocaleContent 纯函数下沉 lib/apply-rewrites.ts 直测:en/ja 仅在 site.name 仍是 demo 站名时自动删,上一轮已重写成用户游戏的文件警告保留——翻译成果不再被静默销毁,损坏 JSON 一律保留;E2E 加 rebranded ja 存活断言;docs/apply-template.md 两类表述更新为三类）;② rewriteSiteTs 八字段补单引号+反斜杠转义(撇号游戏名不再写出语法错误的 site.ts)+site.ts/navigation/routing/ui 四处替换改函数回调杜绝 $& 展开+domain 补 TOML 转义;文档漂移审计两处(1f9d2ff)——docs/ads.md demo 审计基线同步 v2.6.0 后状态(9 篇仍<15/items 已补齐不再是缺口/codes 页时效性表述/ads.txt 占位→就绪行)+anvil-adsense-audit 技能 ads.txt 行对齐就绪注释行;门禁 typecheck/lint/test 123/check-config/check-content/check-i18n --strict-ui/build/check-links 全绿。手册教学法重构第一批（v2.8.0，2026-09-02，详见 CHANGELOG [2.8.0]）:学习手册重构启动(spec: docs/superpowers/specs/2026-09-02-handbook-teaching-redesign.md,定案 29 课 6 阶段+3 附录,六原则:一课一事/例子先于概念/每课新词≤3 放文末/产出即验收/三个经典错误前置/主线地图)——本批上线阶段 0+1 找词线 8 课×中英(01 这门生意怎么赚钱/02 全程地图与学法含 AI 布置任务三招/03 挖候选/04 看懂 Trends/05 读懂结果页/06 意图满足度完整案例+五步检查表——兑现旧 ch1:77 甩给 docs/sourcing.md 的一句链接/07 打分拍板+决策管理表/08 首日 10 页清单);frontmatter 新增可选 stage 字段(列表页阶段分组+章节页徽标,dev 手册无 stage 渲染扁平);旧第 1 章 pick-your-game 拆除(slug 移除,站内引用改 find-candidates),学习手册 order 重排最终架构(新课 1-8/旧章 9-18),全部 18 章标题去「第 N 章/Chapter N」硬编码编号(编号由 order 渲染,标签 Chapter→Lesson/第…章→第…课);十余处章号互链改课名引用×中英;README/docs README 去「11 章/7 章/18 个提示词」硬编码计数;八门禁全绿(test 123)。剩余批次:阶段 2-5 逐批(含 theme-and-homepage 调入学习手册/GA4 独立成课/外链课拆分/五处折叠随课落地)+开发手册 7 章→9 课+附录三件。手册教学法重构第二批(v2.9.0,2026-09-02,详见 CHANGELOG [2.9.0]):阶段 2「把站立起来」4 课×中英——旧 launch-your-site 一拆二(课 10 run-your-site:fork/clone/pnpm dev 跑通样品站;课 11 rebrand-your-site:apply-template 15 题问答表+--dry-run+Initialize AnvilWiki 警示+图标支线+验收清单);课 09 install-tools 新骨架重写补 GitHub 2FA+恢复码(原零覆盖);课 12 theme-and-homepage 自 dev 手册调入 learn(order 12,选修:apply-template 已自动换色,本课教 8 行规矩+首页文案 JSON 改法);学习手册连续 order 1-20、dev 移出主题课后重编号 1-6;launch-your-site slug 移除,landing.ts 8 处引用+标签(第 3 章/Ch.3→课 N/Lesson N)同步,architecture/categories-and-locales/ai-ops 引用改向;门禁全绿(test 123)。剩余批次:阶段 3 内容生产、阶段 4 上线收录、阶段 5 变现经营+开发手册 9 课+附录三件。手册教学法重构第三批(v2.10.0,2026-09-02,详见 CHANGELOG [2.10.0]):阶段 3「内容生产」5 课×中英——旧 first-10-pages(161 行)一拆五:课 13 first-article(文件夹/笔记/攻略页提示词+意图分类表+frontmatter/质检/draft 三词)、课 14 codes-page(最粗红线:码只来自亲眼所见+⊕视频双红线:draft 核实转正/文案完全重写/嵌入合规)、课 15 tier-list-and-media(排行榜提示词+gameVersion+⊕三合法素材通道:自截自录/官方 press kit/CC 图库)、课 16 quality-gate(三关验收:draft 处置规则+一篇一 commit)、课 17 launch-batch-plan(10-15 分批放+到点就走);7 件不要做拆入各课经典错误;first-10-pages slug 移除(landing 4 处+课 12 链接同步),阶段 4-5 旧章顺延 18-24(学习手册连续 1-24);门禁全绿(test 123)。剩余:阶段 4/5 重构+开发手册 9 课+附录三件。手册教学法重构第四批(v2.11.0,2026-09-02,详见 CHANGELOG [2.11.0]):阶段 4+5 学习手册 29 课收官——新增课 20 计数器(CF beacon env+Clarity 贴脚本,按模板实情 Clarity 无 env)/21 第一周读数(三面板+四及格线+只认面板数)/23 收款三件事(W-8BEN 协定 10%/PIN 4 次 4 个月/电汇拼音+SWIFT,吸收 docs/ads.md 收款节)/24 GA4(延迟哲学+同意横幅门控)/26 clone-your-site(承接 templatize,template-audit+换皮清单+四步)/28 rank-one-keyword 与 29 trust-and-backlinks(seo-traffic 一拆二);enable-ads 重写(统计/收款拆出)、weekly-ops 重写(读数拆出);学习手册连续 1-29;seo-traffic/templatize slug 移除,landing SEO 卡改向;门禁全绿(test 123)。剩余:开发手册 9 课+附录三件+计数收口。手册教学法重构收官(v2.12.0,2026-09-02,详见 CHANGELOG [2.12.0]):开发手册 7 章→9 课——新增课 4「改完怎么自证」(本地七命令+CI 八门禁+三流水线+安全/性能底线,ci-and-security 并入后移除)、课 8「内容管道」与课 9「多站管理」(ai-ops 三拆,ai-ops 重写为纯运营课)、sync-and-contribute 一拆二为「同步上游」+「贡献回流」,dev order 连续 1-9;学习手册附录三件(A 作死红线总表五类/B 排查决策树六症状/C 术语 30+ 术语与 20 命令速查,order 30-32 挂「附录」阶段);README/docs README 计数收口为最终形态;门禁全绿(test 123)。手册重构五批全部完成(v2.8.0-v2.12.0)。阅读体验优化(v2.13.0,2026-09-02,详见 CHANGELOG [2.13.0]):用户反馈两条——①左侧目录标题过长:lib/handbook.ts 新增 shortTitle 纯函数(冒号前段/附录「 · 」后段/回退全称),HandbookNav 两态统一使用,4 单测;②右侧本页目录不跟随滚动:根因是三栏布局 xl(1280) 断点,用户窗口 1268px 差 12px 退化成文首静态折叠块——HandbookChapter 网格下探 lg(1024)窄侧栏三栏,TOC desktopAt lg,≥1024 粘性+spy 跟随(spy 脚本原本工作);第 13 课标题改「第一篇攻略」使短标题达意;test 123→127。文档中心搜索+GSC 引导批(v2.14.0,2026-09-03,详见 CHANGELOG [2.14.0]):用户问『模板有没有 GSC API 接入指引』AI 回答含糊——内容一直在开发手册第 7 课但三层引导失灵(spec: docs/superpowers/specs/2026-09-03-gsc-discovery-docs-search-design.md)。① 引导包:shortTitle 可选 frontmatter 覆盖字段(冒号派生法无法在侧边栏露出只在标题后半段的关键词),第 7 课改名×双语+短标题「AI 运营与 GSC 接入」/"AI ops & GSC setup"+H2 改「GSC API 接入(5 分钟)」露出页内 TOC,slug ai-ops 不动互链零影响;docs/README 决策树/deployment.md 复盘节(显式区分 GSC 站点验证≠API 接入)/anvil-ops README 三处指路;doctor gsc-config 缺配置 detail 追加教程 URL(fix 字段仅 FAIL 渲染,env 门控 ok:true 契约不变)。② 搜索:🚨 Pagefind 规则=站点任一页面标 data-pagefind-body 后未标记页面全部排除出索引——此前仅 ArticlePage 标记,落地页与手册 41 课×双语对站内搜索完全隐形;HandbookChapter 补标记+面包屑/页脚 ignore+H1 meta,SearchButton 增可选 labels 覆盖(zh 非 wiki locale,getUi 会回退英文)+locale 放宽 string,LandingLayout 增 search 开关+8 个 docs 路由(en+zh × hub/learn/dev/[slug]),营销 landing 不进索引;Pagefind 按 html lang 自动分语言索引(zh 页搜出 zh);契约测试钉 data-pagefind-body 防静默退出;产物验证 pagefind 片段 en 57/zh 41/ai-ops 双语各 1。test 127→133,ops 125 全绿。顶栏搜索胶囊(v2.14.1,2026-09-03,详见 CHANGELOG [2.14.1]):用户反馈小图标不显眼——SearchButton 增 variant='icon'|'field' 两态(默认 icon,wiki SiteHeader/404 零改动),docs header 搜索框改加宽胶囊(占位文字 sm+/⌘K 提示 md+/窄屏退化图标)置于品牌组后 flex 撑开 max-w-xs;营销 landing 与 wiki 侧不受影响。