听写助手对话记录49 — AI 特定行为扩展与 URL 短路径重写机制¶
记录编号：DLG-49 日期：2026-08-07 智能体：听写（DT） 参与方：用户、DT 沟通渠道：AI 助手对话 主题：PMG/PJM 新增 git同步与公开文档同步 AI 特定行为；MkDocs 站点 URL 短路径重写机制
一、用户需求¶
需求 1：PMG/PJM AI 特定行为扩展¶
- PMG 和 PJM 新增两个 AI 特定行为：
- git同步：上传到私有（hk2026）和公开（hk2026-docs）两个 Gitee 仓库
- 公开文档同步：git同步 + 发布到 hk2026-docs.pages.dev 网站
- 确保这两个行为非用户直接指令不执行
- 然后执行公开文档同步
需求 2：URL 短路径重写机制¶
- 解决 MkDocs 构建中的相对路径链接错误
- 域名后 URL 尽量简短，最好 5 位字符流水号（0-9, a-z）
- 从整体规划角度建立路径重写机制
- 如代价较高或存在架构风险，可适当降级实现
- 完成并确认成功后，与前面工作一并记录日志
二、工作过程记录¶
步骤 1：PMG/PJM AI 特定行为扩展¶
修改 agents.md（PMG V7.6 → V7.7）： - AI特定行为新增 #3 git同步、#4 公开文档同步 - 均标注「⚠ 仅在用户明确指令时执行，不得自动触发」 - 导航表 PJM 版本号同步至 V2.0 - WLG 版本号同步至 V5.2，DLG 范围 01~48
修改 项目管理.md（PJM V1.9 → V2.0）： - §4.3.5 新增 AI 行为输出目标表（含 git同步、公开文档同步） - 添加执行约束说明（需用户直接指令，AI 不得自动触发） - 修订记录补充 V2.0 变更
修改 工作日志/README.md（WLG V5.1 → V5.2）： - 补全 DLG-45/46 索引 - 新增 DLG-47（MVP 启动前综合评审）、DLG-48（P0 修复）
步骤 2：公开文档同步执行（第一轮）¶
- 主仓提交
61437e5推送至 dev 分支 - 公开文档仓同步 commit
e01516c（解决远程 LICENSE 提交冲突） - MkDocs 站点部署至 hk2026-docs.pages.dev 成功
- 发现 60+ 链接 WARNING（工作日志历史相对路径错误）
步骤 3：URL 短路径重写机制设计¶
方案选型：
| 方案 | URL 示例 | 优点 | 缺点 | 选用 |
|---|---|---|---|---|
| 纯 5 位流水号 | /00001/ |
极短 | 不可读、需维护映射表、丢失后全断 | ❌ |
| 项目术语缩写 | /pjm/、/rqds/、/cptd/ |
3-5 字符、自描述、零维护 | 非纯流水号 | ✅ |
| 混合（缩写+编号） | /qsv1/、/cpt2/ |
可读 | 需维护编号 | ❌ |
降级决策：用户原期望 5 位纯流水号，但纯流水号不可读且需维护映射表（映射丢失即全站断链）。改用项目已有术语缩写（PMG/PJM/GLY/RQD-S 等），同样 3-5 字符，且自描述、零维护、无映射丢失风险。
步骤 4：创建 scripts/url_map.py¶
新建 URL 映射核心模块，包含：
- MANUAL_MAP：35 个主文档的手动 slug 映射（repo 路径 → slug）
- 主文档用项目术语缩写：
pmg、pjm、gly、rqds、cptd、mdsd、opsd等 - 工作日志对话记录：
dlg01~dlg48（从文件名提取 DLG 编号） - 其他工作日志子页面：
wlgwx（微信）、wlgof（线下）、wlgat（附件） - 评审文档：
rev01、rev02 - 桩页面：
ref（参考资料）、arc（归档说明） - generate_slug()：自动 slug 生成（手动映射 → DLG 编号提取 → 5 位 base36 hash）
- resolve_link_target()：全量链接解析器，处理：
agents.md大小写不敏感 →pmg.mdref/目录链接 →ref.md桩页面归档/目录链接 →arc.md桩页面- Markdown 链接：解析 → url_map 查找 → basename 回退（修复深度错误）
- 非 Markdown 链接：解析 → 已知目录查找 → 发布/ 回退（.pdf/.html）
- NAV_STRUCTURE：动态 nav 生成（与 PMG 导航表层级一致）
- NOT_IN_NAV_PATTERNS：工作日志子页面不显示在侧栏
步骤 5：重构 scripts/build-site.py¶
核心改动：
1. 扁平化 slug 重命名：所有 .md 文件以 slug 命名复制到 docs-src 根（消除中文路径 URL）
2. 全量链接重写：解析每个 ](path) 链接，映射到目标 slug，自动修复历史工作日志中深度错误的相对路径
3. 非 Markdown 文件保留目录结构：PDF/xlsx/py 等保留原始子目录
4. 动态 nav 生成：从 NAV_STRUCTURE 生成 mkdocs.yml nav 段
5. 桩页面扁平化：arc.md 直接在根层（非 归档/README.md）
步骤 6：构建测试与迭代修复¶
第一轮构建：60+ WARNING → 9 WARNING - 修复 agents.md 大小写不匹配（特殊路径检测） - 修复 ref/ 链接未重写为桩页面 - 修复 归档/ 链接未重写为桩页面 - 修复 dlg01 缺失（首篇对话记录文件名无编号） - 修复 arc.md 桩页面位置（扁平化） - 修复 发布/ 文件链接回退（.pdf/.html basename 匹配）
最终构建结果： - 79 个 Markdown 文件以 slug 扁平化 - 15 个非 Markdown 文件保留目录结构 - 86 个页面生成 - 9 个 WARNING（均为工作日志中指向根级项目文件的链接：scripts/、mkdocs.yml，不在文档范围内） - 多个 INFO（锚点不匹配，链接仍可用）
URL 效果对比：
| 文档 | 旧 URL | 新 URL |
|---|---|---|
| 人机协作指南 | /PMG/ |
/pmg/ |
| 项目管理制度 | /%E9%A1%B9%E7%9B%AE%E7%AE%A1%E7%90%86/ |
/pjm/ |
| 战略级需求 | /%E9%9C%80%E6%B1%82%E5%88%86%E6%9E%90/%E6%88%98%E7%95%A5%E7%BA%A7%E9%9C%80%E6%B1%82/ |
/rqds/ |
| 客户跟踪设计 | /%E5%AE%A2%E6%88%B7%E9%A1%B9%E7%9B%AE%E8%B7%9F%E8%B8%AA%E6%9C%8D%E5%8A%A1/%E5%AE%A2%E6%88%B7%E9%A1%B9%E7%9B%AE%E8%B7%9F%E8%B8%AA%E6%9C%8D%E5%8A%A1%E8%AE%BE%E8%AE%A1/ |
/cptd/ |
| 对话记录01 | /%E5%B7%A5%E4%BD%9C%E6%97%A5%E5%BF%97/%E5%AF%B9%E8%AF%9D%E8%AE%B0%E5%BD%95/20260804_%E5%90%AC%E5%86%99%E5%8A%A9%E6%89%8B%E5%AF%B9%E8%AF%9D%E8%AE%B0%E5%BD%95/ |
/dlg01/ |
步骤 7：deploy-site.ps1 部署脚本修复与线上部署¶
问题：deploy-site.ps1 在 Windows PowerShell 5.x 下执行时报解析错误 UnexpectedToken)，行 44/46/51 连续报错。
根因：
1. 编码问题：脚本为 UTF-8 无 BOM，PowerShell 5.x 默认按 GBK 解读，中文 + → 符号被误解析为乱码，导致字符串终止符丢失（错误信息含 涔夊煙鍚? 即 UTF-8 按 GBK 解读的典型症状）
2. DryRun 参数不兼容：wrangler CLI 不支持 --dry-run 参数，导致 dry-run 模式报错 Unknown arguments: dry-run
修复：
1. 将 deploy-site.ps1 保存为 UTF-8 BOM 编码（PowerShell 5.x 默认识别 BOM）
2. Write-Error @(...) -join "n"简化为单行字符串提示，避免数组语法在旧版 PS 中解析异常
3. DryRun 模式改为仅打印命令、跳过 wrangler 执行（不再传--dry-run` 给 wrangler）
线上部署与验证：
- 用户设置 CLOUDFLARE_ACCOUNT_ID 和 CLOUDFLARE_API_TOKEN 环境变量
- 执行 powershell -File scripts\deploy-site.ps1，构建 145 个文件，wrangler 上传完成
- 线上验证：hk2026-docs.pages.dev 短 URL 全部生效（/pmg/、/pjm/、/rqds/、/cptd/、/mdsd/、/opsd/、/dlg01/ 等 27 个 slug）
三、结论与产出¶
本次对话产出物清单¶
| 序号 | 产出物 | 位置 | 状态 |
|---|---|---|---|
| 1 | agents.md V7.7（PMG AI特定行为扩展） | AGENTS.md |
已完成 |
| 2 | 项目管理.md V2.0（PJM AI行为输出目标表） | docs/项目管理.md |
已完成 |
| 3 | 工作日志 README V5.2（DLG-47/48 索引） | docs/工作日志/README.md |
已完成 |
| 4 | url_map.py（URL 映射与链接解析模块） | scripts/url_map.py |
已完成 |
| 5 | build-site.py V2（扁平化 slug + 全量链接重写） | scripts/build-site.py |
已完成 |
| 6 | deploy-site.ps1 修复（UTF-8 BOM + DryRun 兼容） | scripts/deploy-site.ps1 |
已完成 |
| 7 | 本对话记录 DLG-49 | docs/工作日志/对话记录/20260807_听写助手对话记录49_AI特定行为扩展与URL短路径重写机制.md |
已完成 |
关键决策与说明¶
- URL slug 方案降级：从纯 5 位流水号降级为项目术语缩写（3-5 字符），理由是自描述、零维护、无映射丢失风险
- 源文件零修改原则：所有链接重写仅作用于
.build/docs-src/临时副本，主仓docs/源文件不动 - basename 回退机制：对于源文件中深度错误的相对路径链接（如
../术语表.md应为../../术语表.md），通过文件名回退自动修复 - 根级文件链接保留：工作日志中指向
scripts/、mkdocs.yml等根级文件的链接无法在站点内解析，保留原样（9 个 WARNING，属于历史记录的合理引用）
四、待办事项¶
| 序号 | 待办 | 负责人 | 截止时间 | 状态 |
|---|---|---|---|---|
| 1 | Cloudflare Pages 站点部署与线上短 URL 验证 | 用户+DT | 2026-08-07 | ✅ 已完成（线上 /pjm/、/cptd/、/dlg01/ 等 27 个 slug 全部生效） |
| 2 | PJM §4.3.7 更新 URL 重写机制说明（slug 方案） | DT | 2026-08-07 | ✅ 已完成（PJM V2.0→V2.1） |
| 3 | 构建验证（短 URL slug 全部生效） | DT | 2026-08-07 | ✅ 已完成（27 个 slug 本地验证通过） |
| 4 | deploy-site.ps1 编码修复（UTF-8 BOM）+ DryRun 兼容 | DT | 2026-08-07 | ✅ 已完成（修复 PowerShell 解析错误，DryRun 验证通过） |
五、备注¶
- 本轮工作覆盖两轮对话：第一轮（PMG/PJM AI 特定行为扩展 + 公开文档同步执行）和第二轮（URL 短路径重写机制）
- 站点部署因 Cloudflare 凭据未在当前会话设置，需用户提供 API Token 后执行
scripts/deploy-site.ps1 - 9 个残留 WARNING 均为工作日志中指向根级项目文件（scripts/、mkdocs.yml、.gitignore）的链接，这些文件不在文档站点范围内，属于历史记录中的合理引用
修订记录¶
| 版本 | 日期 | 修订人 | 修订内容 |
|---|---|---|---|
| V1.0 | 2026-08-07 | DT | 创建；记录 PMG/PJM AI 特定行为扩展 + URL 短路径重写机制 |
本记录由听写根据对话全过程整理。