DLG-68 公开同步纳入听码文档与 worklog 排除修复¶
日期：2026-08-11 参与人：曾总（SPO）、听写助手（DT） 主题：公开文档同步脚本纳入听码 dip1/docs/ 文档、排除 dip1/docs/worklog/、执行全链路同步与部署 关联文档：DLG-67、PJM §4.3.6/4.3.7
一、背景¶
DLG-67 确立了"听码和听云的文档（排除 private 部分）纳入公开范围"的原则，并将 DIP1 与听云列为站点一级分类。但实际核查发现两个脚本缺陷：
sync-docs-helper.py未同步dip1/docs/：Step A 的git ls-tree仅扫描docs、发布、ops，导致公开仓hk2026-docs完全缺失听码的技术文档（架构设计、SPEC、OpenAPI、Schema 等）。build-site.py未排除dip1/docs/worklog/：MkDocs 站点构建时把听码的 DWLG 工作日志（含 UAT 测试报告、Bug 修复记录等开发过程文档）也纳入了站点，与"听云ops/worklog/整个排除"的规则不一致。
二、修复内容¶
2.1 scripts/sync-docs-helper.py¶
| 修改点 | 变更 |
|---|---|
Step A git ls-tree 参数 |
新增 "dip1/docs"，使公开仓同步听码技术文档 |
| Step B 清理目录 | 新增 dip1/docs，避免旧文件残留 |
Step C EXCLUDE_PREFIXES |
新增 "dip1/docs/worklog/"，排除听码工作日志 |
| Step E 验证清单 | 新增 dip1/docs/ 存在性检查、dip1/docs/worklog/ 排除验证、3 个关键文件（README/DIP1-ARC/DIP1-IMP）内容验证 |
| Step F commit message | 更新为 docs/ + 发布/ + ops/ + dip1/docs/ excl private/worklog |
2.2 scripts/build-site.py¶
| 修改点 | 变更 |
|---|---|
EXCLUDE_PREFIXES |
新增 "dip1/docs/worklog/"，与 ops/private/、ops/worklog/ 同等排除 |
| 日志输出 | 更新为"已排除 ops/private + ops/worklog + dip1/docs/worklog" |
2.3 scripts/url_map.py¶
| 修改点 | 变更 |
|---|---|
NAV_STRUCTURE DIP1 区块 |
移除 ("工作日志 DIP1-WLG", "dip1wlg") 导航项——因 dip1/docs/worklog/ 整个目录被排除，该页面不再存在于站点 |
MANUAL_MAP中的"dip1/docs/worklog/README.md": "dip1wlg"保留：文件本身被EXCLUDE_PREFIXES排除不会进入站点，映射条目无副作用，保留以备将来政策调整。
三、操作约定（对齐 DLG-67 §三）¶
后续当用户发出"公开文档同步"指令时，DT 应：
- 检查
ops/和dip1/docs/下是否有新增/删除/重命名的文档（听云/听码根据文档自主权原则可能调整结构） - 如有变化，更新
scripts/url_map.py中的MANUAL_MAP（slug 映射）和NAV_STRUCTURE（导航结构） - 确认
sync-docs-helper.py和build-site.py的EXCLUDE_PREFIXES仍正确覆盖所有 private/worklog 路径 - 执行 git 同步（§4.3.6）+ MkDocs 站点部署（§4.3.7）
本次确立的排除规则：
- ops/private/ — 听云私有文档（含凭证清单、部署细节）
- ops/worklog/ — 听云工作日志（OWLG）
- dip1/docs/worklog/ — 听码工作日志（DWLG）
四、变更文件清单¶
| 文件 | 变更内容 |
|---|---|
scripts/sync-docs-helper.py |
新增 dip1/docs 同步 + 排除 dip1/docs/worklog/ + 验证清单扩展 |
scripts/build-site.py |
EXCLUDE_PREFIXES 新增 dip1/docs/worklog/ |
scripts/url_map.py |
NAV_STRUCTURE 移除 DIP1-WLG 导航项 |
docs/工作日志/对话记录/20260811_听写助手对话记录68_*.md |
新建（本工作日志） |
五、执行步骤¶
- ✅ 修复
sync-docs-helper.py、build-site.py、url_map.py - ✅ 创建 DLG-68 工作日志
- ✅ 提交变更到 dev 分支并推送（commit f7a99e6）
- ✅ 执行
sync-docs-repo.ps1同步至公开仓：复制 145 个文件，排除 32 个 private/worklog，dip1/docs/ 首次纳入公开仓 - ✅ 执行
build-site.py构建 MkDocs 站点：121 md + 24 非 md 文件，5.81 秒，site/ 产物 199 个文件 - ✅ 执行
deploy-site.ps1部署至 Cloudflare Pages：上传 129 新文件（69 已缓存），生产 URL https://hk2026-docs.pages.dev
六、公开同步执行结果汇总¶
| 阶段 | 结果 |
|---|---|
| 主仓提交 | commit f7a99e6（dev 分支，4 文件变更，111 行新增） |
| 公开仓同步 | commit 0999669（master，12 新文件 = DIP1 11 文档 + DLG-68），同步 145 个文件，排除 32 个（ops/private + ops/worklog + dip1/docs/worklog） |
| 站点构建 | 124 个 slug，122 个 Markdown，199 个产物文件；导航一级分类：DIP1 子项目（9 项）、生产运维 OPS（听云 WCL，5 项） |
| 站点部署 | wrangler 上传 198 个文件（129 新 + 69 缓存命中），生产域名：https://hk2026-docs.pages.dev |
后续操作约定：当听云/听码在
ops/或dip1/docs/下调整文档结构时，通过"公开文档同步"指令一并处理——DT 会检查变化、更新 url_map，再执行本日志中的 3-6 步。
本日志记录公开同步脚本纳入听码文档与 worklog 排除修复的完整过程。