跳到主要内容

Checkpoint: published-site-verifier

日期：2026-05-14
Controller：Labs-FinTecAI Admin
Lane：knowledge-refactor
状态：Completed

1. 本批完成​

Batch 7C 将公开站点 smoke 检查固化为 npm run verify:published-site。

本批只处理发布验证工具链和 Admin 恢复层，不修改项目正文、公共入口语义、Controller 产品事实源或知识库 IA。

2. 新增能力​

对象作用
scripts/verify-published-site.mjs检查公开站点的 docs-manifest.json、llms.txt、scope guard checkpoint 页面和 Pagefind entry
scripts/verify-published-site.test.mjs用纯 Node fixture 锁定 verifier 的 URL normalization、成功路径和缺失锚点失败路径
npm run verify:published-site发布闭环后可重复执行的公网 smoke 命令

默认 base URL 来自 docs-manifest.json 的 canonical_site。如需验证临时域名，可使用：

npm run verify:published-site -- --base-url https://example.test/

脚本默认追加 cache-bust query；如需复现固定 URL，可使用：

npm run verify:published-site -- --no-cache-bust

3. 检查范围​

当前脚本验证四类发布面：

  1. docs-manifest.json：可访问、JSON 可解析、repository / source-of-truth / canonical site / scope checkpoint 锚点存在；
  2. llms.txt：可访问，包含 scope guard required-check 状态入口；
  3. controllers/labs-fintecai-admin/checkpoints/2026-05-14-scope-guard-required-check/：可访问，包含 checkpoint slug 和 状态：Blocked；
  4. pagefind/pagefind-entry.json：可访问，JSON 可解析。

4. TDD 记录​

  • RED：node scripts/verify-published-site.test.mjs 首次失败于 ERR_MODULE_NOT_FOUND，因为 scripts/verify-published-site.mjs 尚不存在。
  • GREEN：实现 verifier 后，node scripts/verify-published-site.test.mjs 通过。

5. 验证​

  • node scripts/verify-published-site.test.mjs：通过。
  • npm run verify:published-site：通过，公开站点 4 项检查均 OK。
  • DOC_CHANGE_SCOPE=public-entrypoints,controllers,tooling npm run verify:change-scope：通过。
  • node -e "JSON.parse(require('fs').readFileSync('docs-manifest.json','utf8')); console.log('docs-manifest JSON parse OK')"：通过。
  • git diff --check：通过。
  • npm run build：通过，Docusaurus build 和 Pagefind 索引生成成功。
  • test -f build/controllers/labs-fintecai-admin/checkpoints/2026-05-14-published-site-verifier/index.html：通过，新 checkpoint 页面已进入本地 build。
  • rg -n "published-site-verifier|Published site verifier|verify:published-site" build/docs-manifest.json build/llms.txt build/controllers/labs-fintecai-admin/checkpoints/2026-05-14-published-site-verifier/index.html：通过，机器入口和页面产物均包含新 checkpoint。

6. 后续动作​

  1. 后续每次 Docs workflow deployment 成功后，运行 npm run verify:published-site 做公网发布闭环 smoke；
  2. 若新增关键发布面，应先扩展 scripts/verify-published-site.test.mjs，再扩展 verifier；
  3. 若未来切换 canonical domain，先更新 docs-manifest.json 的 canonical_site，再运行本脚本确认新域名发布面。