听写助手对话记录 44¶
记录编号：DLG-44 日期：2026-08-06 智能体：听写（DT） 参与方：用户、DT 沟通渠道：AI 助手对话 主题：MkDocs 文档站点发布方案评估 + 设计 + 实施（PJM §4.3.7）
一、用户需求¶
用户提出 hk2026-docs 公开文档镜像仓（§4.3.6）的阅读体验问题：
"hk2026-docs 仓库中，目前大部分文档直接复制了 md 文件，但 md 文件用普通阅读器的效果不好，尤其是非专业技术人员的阅读感非常不好，我想在从 hk2026 同步到 hk2026-docs 仓库时，顺便完成格式转换，可以转成 html 或 pdf，是否还有更好的方案，请帮我提供建议并评估。"
核心诉求： 1. 改善非专业技术人员的文档阅读体验 2. 评估"同步时转 html/pdf"方案，寻求更优解 3. 方案需在项目管理文档中记录清楚
二、方案评估¶
2.1 问题诊断¶
| 维度 | 现状（hk2026-docs 直接复制 MD） | 影响 |
|---|---|---|
| Mermaid 图表 | Gitee 渲染器不渲染，显示为代码块 | 65+ 张架构/流程图无法阅读 |
| 全文搜索 | 无 | 跨文档检索困难 |
| 侧栏导航 | 无 | 非技术人员易迷失 |
| 深色模式 | 无 | 长时间阅读疲劳 |
| Gitee Pages | 2024 年已停服 | 无法托管静态站点 |
2.2 候选方案对比¶
| 方案 | 阅读体验 | 实现成本 | 维护负担 | 评估 |
|---|---|---|---|---|
| A. 同步时转 HTML（每篇 MD→单页 HTML） | 中（无统一导航/搜索） | 中（需 per-file 转换脚本） | 高（双份维护，链接易断） | ❌ 体验提升有限，链接重写复杂 |
| B. 同步时转 PDF | 低（PDF 不适合在线浏览） | 中 | 高（PDF 不可搜索/导航） | ❌ 与"在线阅读"目标相悖 |
| C. MkDocs Material 站点 | 高（搜索/导航/Mermaid 原生/深色模式） | 中（一次性配置） | 低（构建脚本自动化，源文件零修改） | ✅ 推荐 |
| D. Docusaurus / VitePress | 高 | 高（Node 生态，React/Vue 学习成本） | 中 | ❌ 过度工程，Python 生态更契合项目 |
| E. GitBook | 中 | 中 | 高（商业转向，免费版受限） | ❌ 不推荐 |
2.3 推荐结论：方案 C（MkDocs Material）¶
理由： 1. Python 生态（项目已用 Python 处理同步脚本），零额外语言成本 2. SuperFences 内置 Mermaid 原生渲染，无需额外插件，覆盖项目 65+ 张图 3. 源文件零修改（链接重写仅作用于临时副本），不污染主仓 4. Cloudflare Pages 全球 CDN 免费托管，规避 Gitee Pages 停服问题 5. 工作日志 43+ 份全部纳入站点（直达 URL 可访问），完整可追溯
2.4 用户决策¶
用户确认两点：
- 方案等效性确认：用户询问"MkDocs 方案是否等效于绕过 hk2026-docs"。
- 回答：是。MkDocs 站点从主仓
docs/直接构建，不经过 hk2026-docs 仓库，是独立的第二条发布路径。 -
用户接受："hk2026-docs 可以保留，而 mkdocs 方案多一个发布方式。"
-
双路径并行：保留 §4.3.6 公开镜像仓（MD 源码镜像，供查看源码者）+ 新增 §4.3.7 文档站点（供阅读者），整体方案记录至 PJM。
三、实施过程记录¶
步骤 1：跨边界链接模式调研¶
为设计准确的链接重写规则，对 docs/ 中跨边界链接做 git grep 全量调研：
| 链接类型 | 模式 | 出现位置 | 处理方式 |
|---|---|---|---|
| agents.md 链接 | ](../../PMG.md / ](../../agents.md |
docs/ 各 README + 工作日志 | 深度感知重写为 PMG.md |
| ref/ 链接 | ](../../参考资料.md) 按文件实际深度生成上溯前缀，统一修正链接 |
||
- RE_AGENTS = \]\((?:\.\./)+agents\.md([^)]*)\) 匹配任意深度，替换为深度感知 PMG.md\1 |
|||
- 默认非 strict（工作日志历史链接债务不应改动历史记录）；--strict 供未来源链接审计 |
步骤 4：创建 scripts/deploy-site.ps1（新建，CF 部署）¶
调用 build-site.py 构建 → 校验 site/ 产物 → 校验 wrangler + 环境变量 → wrangler pages deploy → 输出部署 URL。支持 -Branch preview / -DryRun / -SkipBuild。
步骤 5：更新 .gitignore¶
追加 site/、.build/ 排除规则（构建产物）。
步骤 6：更新 PJM（V1.7 → V1.8）¶
- 头部版本号 V1.7 → V1.8
- 新增 §4.3.7 文档站点发布（技术栈表/文件清单表/源文件零修改原则/链接处理表/排除项/构建模式/部署流程/与 §4.3.6 关系对照表）
- §4.3.4 版本控制范围表新增
mkdocs.yml（✅ 纳入）与site/、.build/（❌ 排除） - 修订记录新增 V1.8 行
步骤 7：更新 scripts/README.md（V1.0 → V1.1）¶
脚本清单新增 build-site.py、deploy-site.ps1；新增 §四 使用说明（前置条件/构建/部署/工作原理）。
步骤 8：修复源错误链接¶
docs/报价服务/报价模型设计.md:291：
- 原：[PMG §4.5 变更管理](../../PMG.md#45-变更管理)（AGENTS.md 无 §4.5，锚点失效）
- 改：[PJM §2.5 变更管理](../项目管理.md#25-变更管理)（PJM §2.5 变更管理为正确位置）
步骤 9：校验¶
| 校验项 | 结果 |
|---|---|
python -m py_compile build-site.py |
✅ 语法 OK |
| mkdocs.yml YAML 结构（忽略 python/name 标签） | ✅ 11 nav 项 / 5 not_in_nav / 17 扩展 |
| 源文件零修改核查 | ✅ docs/、AGENTS.md、发布/ 仅链接修复 1 处（报价模型设计.md），其余不动 |
| 本地构建验证（mkdocs build） | ⏳ 待用户安装 mkdocs-material 后执行 |
四、关键决策¶
| 决策 | 选择 | 理由 |
|---|---|---|
| 站点框架 | MkDocs Material | Python 生态，Mermaid 原生渲染，零额外语言成本 |
| 托管平台 | Cloudflare Pages | 全球 CDN 免费，规避 Gitee Pages 停服 |
| 与 hk2026-docs 关系 | 双路径并行 | 镜像仓供查看源码者，站点供阅读者，互不替代 |
| 源文件修改策略 | 零修改（链接重写仅作用临时副本） | 不污染主仓，构建可复现 |
| 链接重写策略 | 深度感知（按文件实际深度） | 顺带修正工作日志源中错误的链接深度 |
| 默认构建模式 | 非 strict | 工作日志历史链接债务不应改动历史记录；--strict 供未来审计 |
| 工作日志处理 | 全部构建 + not_in_nav | 43+ 份记录直达 URL 可访问，完整可追溯，侧栏不过深 |
五、产出物清单¶
| 序号 | 产出物 | 位置 | 状态 |
|---|---|---|---|
| 1 | mkdocs.yml 站点源配置 | mkdocs.yml | ✅ 新建 |
| 2 | build-site.py 构建编排 | scripts/build-site.py | ✅ 新建 |
| 3 | deploy-site.ps1 部署脚本 | scripts/deploy-site.ps1 | ✅ 新建 |
| 4 | .gitignore 追加 site/、.build/ | .gitignore | ✅ 更新 |
| 5 | PJM V1.7→V1.8 新增 §4.3.7 | docs/项目管理.md | ✅ 更新 |
| 6 | scripts/README.md V1.0→V1.1 | scripts/README.md | ✅ 更新 |
| 7 | 报价模型设计.md 错误链接修复 | docs/报价服务/报价模型设计.md | ✅ 修复 |
| 8 | DLG-44 本记录 | 本文件 | ✅ 新建 |
六、待办事项¶
| 序号 | 待办 | 责任人 | 截止时间 | 状态 |
|---|---|---|---|---|
| 1 | 一次性环境配置：pip install mkdocs-material + npm i -g wrangler + 注册 Cloudflare 账号 + 配置凭据 |
TL | 部署前 | 待执行 |
| 2 | 本地构建验证：python scripts/build-site.py（预期 ✓ 站点已构建: site/） |
DT / TL | 环境就绪后 | 待执行 |
| 3 | 本地预览验证：python scripts/build-site.py --serve 访问 http://127.0.0.1:8000 |
DT / TL | 构建通过后 | 待执行 |
| 4 | 首次部署：scripts/deploy-site.ps1，访问 https://hk2026-docs.pages.dev |
TL | 预览通过后 | 待执行 |
| 5 | 工作日志源链接一次性审计（启用 --strict 前置） |
DT | 低优先级 | 待评估 |
七、备注¶
- MkDocs 站点从主仓
docs/直接构建，不经过 hk2026-docs 仓库，是独立的第二条发布路径（用户已确认等效于绕过 hk2026-docs，双路径并行） - mkdocs.yml 中
!!python/name:标签是 MkDocs Material 标准语法，yaml.safe_load不识别但 MkDocs 自身加载器可正确解析（非错误） - DLG-43 修复的 sync 脚本编码方案（Python 生成 commit message）继续适用；本文档未涉及公开仓同步（MkDocs 站点独立于公开仓）
修订记录¶
| 版本 | 日期 | 修订人 | 修订内容 |
|---|---|---|---|
| V1.0 | 2026-08-06 | DT | 创建：MkDocs 文档站点发布方案评估 + 设计 + 实施（PJM §4.3.7） |
本记录由听写根据对话全过程整理。