夜雨聆风
从2天到1小时:我是如何把交付文档效率提升20倍的
大家好，我是老马，一个靠 AI 续命的老码农。
已经好久没更新了，因为最近再折腾交付助手(delivery-assistant)这个agent skill，原本以为半天能搞定的，没想到在Mermaid转图片这个环节卡了好久，差点就放弃了折腾了，还好最后还是搞出了一个版本。
做过项目经理和研发的都知道，每次项目交付的时候都巨痛苦，原本应该是设计阶段的东西基本都是在最后的时候匆匆忙忙搞出来的，概要设计、详细设计、数据库设计、操作手册…一大堆文档。每次都要重新排版、画图、调格式，重复劳动特别多。更别说有些项目还有一些特殊的格式要求，叽叽歪歪啰里啰嗦。
上个月有个项目交付时，监理那边就反馈说文档格式不统一，让重新整理一遍。当时我就想，要是能有个工具自动生成这些文档就好了。当时其实想到了现在红红火火的小龙虾，不过碍于时间紧迫，我决定第一阶段还是先使用Claude Code + Skill来救火，等把火扑灭了再来搞点事情。
我合计了下，这个skill事情倒是不难，不管是技术上还是大模型已经很成熟了，反正代码也不需要我来写，都交给Claude Code就行了。主要解决2个问题：1、流程图怎么转成图片。2、文章过程上下文怎么塞得下；反正没想明白，那也不打紧，那就让AI给我个方案咯。于是我得到了设计方案：
整体架构
这个时候就遇到最大的一个坑了。方案中说明，调用 mermaid-cli (mmdc) 渲染为 PNG 图片，再嵌入 Word。但是吧mmdc那个工具无论是在Windows上还是mac上装依赖都装到崩溃，node版本要求很高，Puppeteer下载总是超时，我差点弃疗了。最后还是挂了个梯子才搞定的。但是这个就不适合推广了。
我只能继续和AI软磨硬泡，啃吃啃吃半天，终于AI这边又给了一个解决方案直接用Playwright + Mermaid CDN的方式，不生成中间文件。写个HTML字符串，用CDN加载Mermaid.js，然后直接截图。试了一下，居然可以！而且不依赖Node.js那套东西，只要装个playwright Python库就行。
测试了几个流程图，都能正常渲染。但测试完整流程的时候发现问题了——我当时的方案是先生成Word，再从Word里提取Mermaid代码，渲染成图片，最后替换回Word。这流程太绕了，而且容错性极差，任何一步出错整个流程就挂。
睡了一觉起来，重新理了一遍思路。得换个方案，代码和图片应该分离处理。
后来想到了占位符方案：
-
Markdown里正常写Mermaid代码块
-
转JSON的时候，把Mermaid代码抽出来，存成独立的
.mmd文件 -
JSON里用占位符标记图片位置，比如
hld_diagram_1.png -
单独跑渲染脚本，把
.mmd文件批量转成PNG -
生成Word时，看到占位符就插入对应图片
这样做的好处是：代码和图片分离，渲染失败了可以重试，不用从头来过。
开始改代码。主要改md_to_json.py，让它在转换时自动提取Mermaid。根据文档类型自动命名：概要设计的图叫hld_diagram_1.png，详细设计的叫lld_diagram_1.png，数据库设计的叫dbd_diagram_1.png。
然后在generate_docx.py里加图片插入逻辑。如果图片文件存在就插入，不存在就显示占位符文本（这样至少文档能生成出来）。
改完测试了一遍，整个流程变成了三步：
# 步骤1：Markdown转JSON，同时提取Mermaidpython md_to_json.py 概要设计-完整版.md "XX系统" "张三" content.json# 步骤2：渲染Mermaid为图片python render_mermaid_cdn.py --mmd-dir ./mermaid_codes --img-dir ./images# 步骤3：生成Wordpython generate_docx.py 概要设计.docx --file content.json
当然这些个代码我是一行也不回写的。必须让Claude Code自己搞定，自己验证。我还特意让它模拟了一个虚拟项目智慧菜市场管理系统，毕竟公司的项目太敏感，没法放出来。看了下生成的图表效果还不错。概要设计的架构图展示了系统的分层结构：
逻辑架构图：
技术架构图展示了Spring Boot、Vue、MySQL、Redis的技术选型：
| 技术点 | 选择方案 | 版本 | 选型理由 |
|---|---|---|---|
| 后端框架 | Spring Boot | 3.2 | 快速开发，生态完善 |
| 前端框架 | Vue | 2.6 | 轻量级，易上手 |
| 数据库 | MySQL | 8.0 | 成熟稳定，性能优秀 |
| 缓存 | Redis | 7.0 | 高性能，支持多种数据结构 |
半小时不到，我手里有了：
-
概要设计说明书.docx – 15页，包含4张架构图
-
详细设计说明书.docx – 24页，包含5张流程图和时序图
-
数据库设计说明书.docx – 18页，包含完整ER图和13张表设计
内容确实不多，毕竟是假的项目。。。不过基本的要素都有了。
第一个基础版本v1就这样完成了。
示例 1：生成概要设计说明书
示例 1：生成概要设计说明书
用户：项目交付助手，帮我生成XXX电商系统的概要设计说明书。 系统用 Spring Boot + Vue3，MySQL 数据库。AI：我将为您生成 XXX电商系统概要设计说明书。 [确认信息 → 展示大纲 → 逐章生成 → 生成 Word]
示例 2：生成数据库设计说明书
用户：项目交付助手，从 SQL 文件生成数据库设计说明书：/project/db/schema.sqlAI：正在提取表结构... [调用 extract_db_schema.py] 提取到以下表：t_user, t_order, t_product... 正在生成 ER 图和表结构文档...
当然，AI生成的文档需要人工审核和调整。但它已经帮我们完成了80%的重复性工作，剩下的20%才是真正需要你动动你的小手指挥一下。
下次老大再催你交文档，你可以淡定地说：
“稍等，给我一首歌的时间。”
写评论或者发送公众号消息交付助手免费获取交付助手(delivery-assistant)这个agent skill。
互动时间
你还在手写文档吗？
留言告诉我，你最讨厌写哪种文档？
点赞👍 + 评论👀，让更多技术人员解放双手！
关于老马一个在技术圈摸爬滚打多年的老程序员，热衷于用AI提升开发效率。
如果你也对AI辅助开发感兴趣，欢迎关注我，一起探索更多可能性！