听写助手对话记录 57 · 文档公开发布与站点 P0 修复（首页 404 / m0 缺失）¶
记录编号：DLG-57 日期：2026-08-07 时段：19:30 - 20:10 参与方：用户（SPO）、听写（DT） 沟通渠道：AI 对话（Trae） 关联文档：PJM §4.3.6-7 / build-site.py / url_map.py / WLG V6.0
一、用户需求¶
用户在 DLG-56（MVP-FS 培训手册 + m0 子目录迁移）完成后，触发 PMG 定义的 AI 特定行为 #4「公开文档同步」，即：
- 主仓 git 提交推送（私有仓 dev 分支）
- docs/ + 发布/ 同步至公开文档仓 hk2026-docs
- MkDocs 站点构建 + Cloudflare Pages 部署（hk2026-docs.pages.dev）
同步后发现站点存在两处 P0 级问题，启动本次修复闭环。
二、工作过程¶
阶段 A：首次公开文档同步（19:30 - 19:40）¶
按 PJM §4.3.6 / §4.3.7 流程标准执行：
| 步骤 | 动作 | 结果 |
|---|---|---|
| A1 | 主仓提交变更（MVP-WX 方案、m0 目录、培训手册） | commit fe5d355 → push origin dev → Gitee OK |
| A2 | sync-docs-repo.ps1 同步公开仓 |
112 文件同步（docs 91 md + 21 非 md）；公开仓无增量（上一轮已同步） |
| A3 | build-site.py 构建站点 |
94 slug 生成；构建成功，产物写入 site/ |
| A4 | deploy-site.ps1 部署 Cloudflare Pages |
wrangler 上传成功，目标项目 hk2026-docs (main 分支) |
阶段 B：线上站点验证与问题发现（19:40 - 19:48）¶
对部署后的站点 https://hk2026-docs.pages.dev 执行 6 项关键 URL 验证：
| URL | 预期 | 实际 | 等级 |
|---|---|---|---|
/ 根路径 |
显示 PMG 人机协作指南 | 404 Not Found | P0 |
/m0/ MVP 方案目录 |
显示 m0 README 及子文档链接 | 404 Not Found | P0 |
/pjm/ 项目管理制度 |
正常显示 | ✅ PASS | — |
/tnd/ 技术文档目录 |
正常显示 | ✅ PASS | — |
/dlg53/ 工作日志 |
正常显示 | ✅ PASS | — |
| 发布区 m0 HTML | 通过侧栏或短链访问 | 404 或链接跳错 | P1 |
根因诊断：
- 首页 404：MkDocs 扁平化 slug 命名后，
nav列表第一项为pmg.md，生成的静态文件为site/pmg/index.html，根路径site/index.html缺失。Cloudflare Pages 默认请求/index.html，找不到时返回 404。 - m0/ 404：
scripts/url_map.py的MANUAL_MAP中，仅定义了docs/技术文档/MVP实施方案.md → mvp的旧映射，未包含 DLG-54/55/56 新迁移的 m0 目录 4 个文档，因此这些文件只能通过 5 位 hash slug 访问，不可读且不在导航树中。 - NAV 三级嵌套缺陷：本次将 MVP 方案从 TND 下二级节点调整为「MVP 方案 m0 → 4 个子文档」的三级结构，原
generate_nav_yaml()仅支持二级嵌套，导致site/.build/mkdocs.yml第 156 行 YAML 解析报错。
阶段 C：脚本修复（19:48 - 20:00）¶
C1. url_map.py 修复（3 处）
- 新增 MANUAL_MAP 条目（docs/技术文档/m0/ 四文档 + 发布/m0/README）：
docs/技术文档/m0/README.md → m0 docs/技术文档/m0/MVP-FS实施方案.md → mvpfs docs/技术文档/m0/MVP-WX实施方案.md → mvpwx docs/技术文档/m0/MVP方案对比.md → mvpcmp 发布/m0/README.md → pubm0 - 更新 NAV_STRUCTURE：TND 段将原「MVP 实施方案 → mvp」单条替换为「MVP 方案 m0 → (索引, FS, WX, CMP)」三级嵌套组；发布文档段将「发布文档 → pub」扩展为二级（总目录 pub / MVP 发布区 pubm0）。
- 升级 generate_nav_yaml：新增递归检测，检测到二级
sub_rest为列表时输出-缩进的三级条目，保持 YAML 语法正确。
C2. build-site.py 修复（2 处）
- 主文档映射预览列表扩展：追加
tnde, m0, mvpfs, mvpwx, mvpcmp, pubm06 个新 slug，构建日志预览中可见关键映射。 - 新增 §10.5「build 模式首页修复」（在 MkDocs build 完成后、清理临时目录前执行）：
- 若
site/index.html不存在，生成兜底跳转页：<meta refresh>跳转 +window.location.replace("pmg/")双保险，支持禁用 JS 环境。 - 写入
site/_redirects（Cloudflare Pages 原生支持），添加两条 301 规则：此方案优先走 CF Pages 服务器端 301（SEO 友好、响应快），客户端 meta refresh 为回退兜底。/ /pmg/ 301 /m0 /m0/ 301
阶段 D：构建验证与二次提交（20:00 - 20:10）¶
| 步骤 | 动作 | 结果 |
|---|---|---|
| D1 | 首次重新构建 | YAML parse error（line 156）→ 执行 C1 的 generate_nav_yaml 升级 |
| D2 | 二次重新构建 | ✅ 构建成功，166 个文件；新增输出：✓ 修复首页：根 index.html → pmg/、✓ 写入 _redirects |
| D3 | 本地验证产物 | site/index.html + site/_redirects 内容正确；m0/index.html、mvpfs/index.html 等 m0 子文件均生成 |
| D4 | 主仓提交脚本修复 | commit 3708510：fix(site): 修复首页404与m0目录缺失 — 新增 m0 slug 映射、根 index.html 跳转、_redirects 规则（2 文件 52 行变更） |
| D5 | push 私有仓 dev | fe5d355..3708510 dev -> dev → Gitee OK |
| D6 | 同步公开仓 | 112 文件已同步，scripts/ 变更不进公开仓，显示 [SKIP] No changes to commit，符合预期 |
阶段 E：用户侧执行部署（待执行）¶
由于 Cloudflare 凭据（CLOUDFLARE_ACCOUNT_ID / CLOUDFLARE_API_TOKEN）仅在用户终端 Shell 会话中设置，AI 沙箱调用时环境变量丢失，因此部署操作需由用户在本机终端执行：
# 确认凭据存在（如未设置，先执行 $env:CLOUDFLARE_ACCOUNT_ID = "..." 等）
$env:CLOUDFLARE_ACCOUNT_ID; $env:CLOUDFLARE_API_TOKEN
# 复用已构建产物（site/ 166 文件），跳过二次构建
powershell -ExecutionPolicy Bypass -File scripts/deploy-site.ps1 -SkipBuild
部署成功后返回：
- 生产 URL：https://hk2026-docs.pages.dev
- 关键验证点：
1. / → 301 → /pmg/（浏览器不显示 404，秒级跳转）
2. /m0/ → 显示 MVP 方案目录索引（含 FS / WX / CMP 三链接）
3. 侧栏「技术文档 TND → MVP 方案 m0 → ...」4 条可点击展开
4. 侧栏「发布文档 → MVP 方案发布区 m0」显示 pubm0.md 内容
三、结论与决策¶
- P0 问题已在脚本层修复，但部署需用户持凭据执行（AI 沙箱不持有 CF 令牌，符合安全原则）。
- 本次新增的 6 个 slug（
m0, mvpfs, mvpwx, mvpcmp, pubm0, tnde）已在 NAV 主树显式挂载，后续构建不会再次漏出。 _redirects机制为 Cloudflare Pages 标准特性，后续新增目录级短链均可按该模式扩展，无需侵入 MkDocs 构建流程。
四、待办事项（T 列表）¶
| 编号 | 事项 | 负责人 | 状态 | 截止 |
|---|---|---|---|---|
| T1 | 用户本机终端执行 deploy-site.ps1 -SkipBuild 完成部署 | SPO | ⏳ 待执行 | 2026-08-07 当日 |
| T2 | 部署后线上 6 URL 复证（/、/m0/、/pjm/、/tnd/、/dlg53/、/pubm0/） | SPO/DT | ⏳ 待验证 | 同 T1 |
| T3 | 创建 DLG-57 并追加 WLG 索引（即本记录） | DT | ✅ 进行中 | 2026-08-07 |
| T4 | 后续 MVP-FS 正式接单后，按 DLG-53 脚本计划执行 MVP 数据质量检查 / 周报 | OL/ML | ⭕ 未开始 | Phase 0 启动周 |
五、附件引用¶
- 提交记录：主仓
3708510（scripts/ 脚本修复）、主仓fe5d355（MVP 双路径文档 + 发布/m0 迁移） - 关联脚本：
scripts/url_map.py（MANUAL_MAP + NAV 生成）、scripts/build-site.py（首页修复段） - 关联规则：PJM §4.3.6 Git 同步、PJM §4.3.7 MkDocs + Cloudflare Pages 部署、PMG AI 特定行为 #4