对话记录 DLG-29¶
日期：2026-08-05 参与方：SPO（用户）· DT（听写 AI 文档助手） 沟通方式：Trae AI 对话 会话主题：执行 AGENTS.md「AI 特定行为·文档汇总输出」—— 业务设计架构 19 篇文档汇总为单一 PDF
一、用户需求¶
SPO 要求：
先理解 agents.md 的 AI 特定行为。然后将业务设计架构涉及的必要文档，进行文档汇总输出。
特定行为规则（AGENTS.md V6.5 新增）： 1. 将指定范围的若干文档，直接顺序汇总成为单一的 PDF 文档，不进行任何修改 2. 各文档以"篇"的形式分隔 3. mermaid 转换为图片，并且与代码合并输出
范围：分图一（业务设计架构）19 个必要要素文档。
二、工作过程¶
2.1 理解特定行为¶
AGENTS.md V6.5 新增「特定行为」章节，定义两种输出模式： - 文档汇总输出：原文顺序汇总为 PDF，不修改，篇分隔，mermaid 转图片 - 文档汇报输出：总结提炼为 HTML PPT，详尽突出重点
本次执行第一种。
2.2 环境工具检查¶
| 工具 | 状态 | 用途 |
|---|---|---|
| node / npm | ✅ 已有 | mermaid-cli 运行环境 |
| python markdown 3.10.2 | ✅ 已有 | md→html 转换 |
| Chrome 浏览器 | ✅ 已有 | mermaid 渲染 + PDF 打印 |
| weasyprint | ⚠️ 缺 GTK 库 | 弃用，改 Chrome headless |
| pandoc / mmdc | ❌ 缺失 | mmdc 需安装 |
2.3 安装 mermaid-cli¶
PUPPETEER_SKIP_DOWNLOAD=true
npm install -g @mermaid-js/mermaid-cli
C:\Program Files\Google\Chrome\Application\chrome.exe）
2.4 转换方案设计¶
19 个 md 文档
↓ python markdown（tables/fenced_code/toc 扩展）
提取 mermaid 代码块 → mmdc 渲染为 PNG（透明背景，宽 1400，scale 2）
↓ 替换 mermaid 块为 <img>
合并 HTML（封面 + 19 篇 banner + 分页符）
↓ Chrome headless --print-to-pdf
单一 PDF
2.5 执行结果¶
- 文档数：19 篇全部成功
- mermaid 图：28 个，27 个成功渲染为 PNG，1 个失败（mermaid_16002，TSMM 标签更新流程图，含特殊字符括号/问号导致 mermaid 解析失败）→ fallback 为代码块展示
- PDF 产出：128 页，8.5 MB
- 耗时：约 3 分钟（mermaid 渲染 + PDF 打印）
2.6 问题与处理¶
| 问题 | 处理 |
|---|---|
| weasyprint 缺 libgobject（GTK） | 弃用，改 Chrome headless --print-to-pdf |
| npm 在 python subprocess 找不到 | 用 APPDATA 路径 + shell fallback |
| mermaid_16002 渲染失败 | 按"不修改原文"原则，保留代码块 fallback |
| Chrome 与已开实例冲突 | 加 --user-data-dir 独立配置目录 |
三、产出物¶
| 产出 | 路径 | 说明 |
|---|---|---|
| 汇总 PDF | 业务设计架构文档汇总.pdf | 128 页 / 8.5 MB / 19 篇 / 27 张 mermaid 图 |
| 转换脚本 | %TEMP%\doc-merge\merge_docs.py |
可复用，支持后续重新生成 |
| 中间 HTML | %TEMP%\doc-merge\merged.html |
199KB 合并 HTML |
| mermaid PNG | %TEMP%\doc-merge\png\ |
27 张渲染图片 |
PDF 结构¶
- 封面页：项目名 + 副标题 + 范围说明 + 日期
- 第一篇~第十九篇：每篇以深色 banner 分隔，page-break 分页
- 第一~四篇：RQD 需求分析（README/S/B/O）
- 第五~七篇：QSV 报价服务（README/D/QMD）
- 第八~十篇：CPT 客户跟踪（README/D/F）
- 第十一~十七篇：MDS 主数据（README/D/SCL/BPL/WPL/CPL/TSMM）
- 第十八~十九篇：TND 技术文档（README/P）
四、关键决策¶
- Chrome headless 替代 weasyprint：weasyprint 在 Windows 缺 GTK 依赖，Chrome headless 原生支持 CSS @page、中文字体、本地图片，质量更高
- mermaid-cli 复用系统 Chrome：跳过 chromium 下载（省 100MB+），用 puppeteer-config 指向系统 Chrome
- mermaid 渲染失败 fallback：按"不修改原文"原则，失败的图保留源代码展示，不修改原文档
- 篇 banner 设计：深色背景 + 篇号（金色）+ 标题，page-break-before 实现篇分隔
五、待办事项¶
| 编号 | 内容 | 负责人 | 状态 |
|---|---|---|---|
| 1 | mermaid_16002（TSMM 标签更新流程图）mermaid 语法含特殊字符，后续可考虑优化原文语法 | DT/SPO | 待确认 |
| 2 | 脚本可复用于其他范围汇总（如项目管理架构 5 篇） | DT | 待需 |
六、DT 复盘¶
本次首次执行 AGENTS.md「特定行为·文档汇总输出」，建立了可复用的转换流水线： - 环境准备：mermaid-cli + Chrome headless（无需 pandoc/GTK） - 脚本化：merge_docs.py 可调整文档清单后复用 - 日志记录：本轮主动记录 DLG-29，未再出现漏记
经验：weasyprint 在 Windows 的 GTK 依赖问题是常见坑，Chrome headless 是更稳妥的 HTML→PDF 方案。
本记录编号 WLG DLG-29，关联文档 AGENTS.md V6.5「特定行为」、业务设计架构文档汇总.pdf。