第 4 篇:文档生成

第 4 篇：文档生成

从空白页面开始写文档是很多开发者抵触的事情。我见过太多人对着空白的 Word 页面发呆半小时，最后只憋出一个标题。WordBuddy 的文档生成功能就是把"写"变成"生成"——你给一个提纲，它给你一篇完整的文档。这篇把生成功能讲透，包括提纲怎么设计、输入怎么给、参数怎么调、生成完了怎么验收、出问题了怎么处理。

一、从提纲到文档

最直接的用法是提供一个标题和章节列表：

WordBuddy 会根据大纲结构，按照默认的内容风格生成每个章节的正文。生成的内容不会很空洞——它会根据标题推理出这个章节应该写什么。

但同样一个标题，不同的人用，出来的质量可以差很多。差别就在提纲设计上。这里有几个我从实践中总结的技巧，直接决定生成质量：

标题要带"动词"或"结果"。 "技术选型"这种纯名词标题，生成出来的内容通常是把几种方案挨个介绍一遍，泛泛而谈。"评估三种缓存方案的取舍"这种标题，生成出来的内容就明显更聚焦，会围绕取舍展开。WordBuddy 是顺着标题的语义去发挥的，标题越具体，内容越不跑偏。

两级标题起步，三级标题更稳。 只有一级标题的提纲，每个章节都是平铺直叙，段落之间没有内在结构。加上二级标题之后，章节内部就有了骨架。拿"实施方案"来说，下面分出"部署架构"和"上线步骤"，生成出来的内容结构感完全不一样。再往下拆一层，每个小节就更像有人专门写过。

把关键约束写进标题。 如果你希望文档里体现某个技术栈、某个约束条件，直接把它写进标题。"基于 Kubernetes 的部署方案"就比"部署方案"多了一层约束，生成的段落里会自动围绕 Kubernetes 展开，而不是写一堆无关的通用内容。

章节顺序就是逻辑顺序。 先背景、再方案、后风险，这是经典的技术文档叙述结构。相邻章节最好有因果关系，WordBuddy 会尝试在章节之间建立衔接——前一章铺垫的上下文，后一章会自动引用。

你也可以给更多上下文：

--context 参数传递的信息会被 WordBuddy 用来调整内容的风格和细节。提供的信息越多，生成的内容越贴合实际。我个人的经验是，把团队规模、技术栈、目标读者、要避开的坑这四类信息放进去，效果提升最明显。尤其是"目标读者"——告诉它读者是管理层还是开发同学，语气和详略会完全不同。

二、输入方式对比

WordBuddy 支持三种输入方式：

直接输入文本。 适合简单场景，不需要额外文件。适合快速出个草稿看看效果，比如临时生成一份周报初稿。

从文件读取。 适合结构清晰的大纲或详细需求。大纲文件建议用 Markdown 格式，标题层级就是文档的章节层级，一目了然，还能进 git 做版本管理。

从标准输入。 适合管道操作，接收上一个命令的输出。适合在脚本里串流程，比如先把数据库里的数据加工成大纲，再喂给 WordBuddy 生成。

三种方式的对比：

三种方式的最终结果是一样的——WordBuddy 都会解析输入内容、理解结构、生成文档。选择哪种取决于你的使用习惯和当前的工作流。我的建议是：正式场景用文件输入，因为大纲文件本身可以进 git，改起来方便，还能用 diff 查看改动。随手草稿用直接输入，省得建文件。

三、输出质量控制

生成的文档质量取决于几个因素：

提纲的详细程度。 一层标题生成的文档不如两层标题的文档结构清晰。"实施方案"下面如果分出"部署架构"和"上线步骤"两个三级标题，WordBuddy 写出来的内容会更聚焦。

上下文信息的多少。--context 参数传递的信息量直接决定内容的准确性。给得越多，生成的内容越不容易出现"看起来对但其实用不了"的泛泛概括。

长度控制。 通过 --length 参数控制每个章节的篇幅。

--length 参数的可选值通常为 brief、normal、detailed。默认是 normal。

三个档位的效果差异，拿"系统架构"这个章节举例：

长度不只是字数差异。detailed 模式下 WordBuddy 会主动补充背景说明、常见坑、替代方案这类信息；brief 模式则会把所有非核心的展开全部砍掉，只留骨架。

另外几个不常被提到但很实用的参数：

--toc 自动生成目录，适合长文档。--style 指定内容风格，可选 technical、business、casual 等。--template 指定模板文件，模板里可以写死封面、页眉页脚这些固定结构。

组合使用的效果：

这一条命令生成的就是一篇带目录、技术风格、内容详实的技术方案，基本可以直接进评审流程。

四、迭代修改

一次生成很少就是最终版本。WordBuddy 支持基于已有文档进行迭代：

edit 命令读取已有文档，应用修改指令，输出更新后的版本。这比重新生成整篇文档更高效——框架保持不动，只改需要调整的部分。

修改指令可以连续叠加：

看一个多轮迭代的具体案例。假设你生成了一篇技术方案，经过三轮修改才定稿：

第一轮，补充细节：

第二轮，调整结构和深度：

第三轮，面向读者调整：

三轮迭代下来，文档从"通用技术方案"变成了"面向管理层的决策材料"。注意每次迭代都输出到新文件，保留历史版本，方便对比和回退。这是用文档工具的好习惯——别覆盖原文件，你永远不知道什么时候要回头看上一版。

五、实际案例：生成一份技术方案

假设你要写一份前端框架选型的技术方案。给 WordBuddy 的大纲可以是：

加上团队和项目的上下文信息：

把这个案例完整走一遍。第一步，准备大纲。光有上面这个骨架还不够，把二级标题补上，让 WordBuddy 有更多抓手：

第二步，生成第一版。第三步，检查生成结果，重点看三处：对比表格的数据是否合理、评估标准是否覆盖了团队真正关心的维度、迁移计划的时间线是否具体到可以执行。第四步，迭代修正——把生成稿里模糊的部分用 edit 命令修掉，再补充只有团队内部才知道的信息，比如"现有 Vue 2 项目有 20 个历史模块，其中 3 个使用了已废弃的 API"这种上下文。

生成的文章结构完整，包含对比表格、优劣势分析、时间线预估。你需要在生成后做的是：验证数据的准确性、补充你了解但 WordBuddy 不知道的团队细节、调整语气。记住：WordBuddy 负责搭骨架和填肉，你负责把关数据和对齐事实。

六、生成内容的质量评估标准

怎么判断一篇生成出来的文档是"能用"还是"得返工"？我整理了一套快速评估标准，生成后逐条过一遍：

六条里通过四条以上，就可以进入人工精修阶段。如果结构本身就乱了，直接回到提纲层面调整重新生成，别在烂地基上修修补补——那比重新生成还费时间。

七、常见生成问题及解决方案

用多了总会遇到几个反复出现的问题，逐个说：

问题一：生成内容太泛，全是"正确的废话"。

原因通常是提纲标题太笼统、context 信息太少。解决方案：标题加动词和关键词，context 里写明硬性约束，比如"必须兼容 Windows Server 2012"、"数据量预计 500 万条"。

问题二：某几个章节明显比其他章节弱。

通常是这几个章节的标题层级太浅。把弱章节下面的子标题拆出来，WordBuddy 就有素材去展开了。子标题本身就是提示，告诉它这个章节应该覆盖哪些点。

问题三：生成了事实错误的内容。

WordBuddy 是生成模型，不是数据库。涉及具体数字、版本号、API 名称、库的写法这类内容，它可能编造。尤其是技术文档，版本号和接口名这种信息必须人工核对。规则很简单：生成内容里所有"看起来像事实"的信息，都要验证一遍。

问题四：文档太长或太短。

用 --length 参数控制，或者用 edit 命令加"精简第三部分，控制在两段以内"这样的指令。长度问题不要靠事后删除解决，从参数层面控制更省事。

问题五：同一个版本反复修改还是不满意。

与其继续 edit 打补丁，不如回到提纲层面调整。提纲是生成质量的上限，改提纲往往比改十次内容更有效。

试试看： 想一个你最近需要写的文档，列出 3-5 个章节的大纲，记得给每个章节配上二级标题和带关键词的标题，用 WordBuddy 生成第一版。对比你之前写同类文档的时间，看看效率提升了多少。