培训转写稿 → 知识手册

这个技能解决什么问题

部门派人参加外部或内部培训，录音转成文字后是一大坨口语流水：寒暄、重复、跑题、口头禅、设备调试、逻辑跳跃混在一起。直接删减只能得到一份"精简版纪要"——读过的人嫌啰嗦，没到场的人看不懂。

本技能把转写稿重构成一份能独立阅读的知识手册：按知识逻辑重排，补全缺失的上下文，把口语经验升维成可复用的方法，用可视化组件承载不同类型的内容。

产出两份文件：*.md（可编辑的源）+ *.html（自包含单文件，双击即读）。需要 PDF 时由使用者在浏览器里 Ctrl+P 导出——样式表已内置专用打印版式（封面满页、每章起新页、隐藏导航），导出的 PDF 与网页视觉一致。

核心区分：这不是会议纪要

先想清楚这份文档的读者是谁——没参加过培训、也没听过录音的同事。他们需要的不是"当时讲了什么"，而是"我需要掌握什么"。

判断标准：如果读者读完某一段，无法回答"我因此会做什么/会判断什么"，这段就是噪声。

五条硬性原则

1. 按知识逻辑重排，不按讲述顺序

讲师 A→B→C 地讲，是因为现场节奏和记忆曲线，不代表读者应该 A→B→C 地学。允许并鼓励：

• 把散落在开头、中间、结尾的同一个知识点合并到一处
• 把"先垫一句的背景"移到它真正相关的位置
• 把讲师反复回扣的核心结论，提到该章开头做"先给结论"
• 把现场问答拆开，有价值的并入对应章节，成体系的单独成章

2. 严格区分「讲师原述」与「编者补充」

这条最重要：绝不编造讲师没说过的内容。三类内容、三种呈现：

宁可留一个"待核实"，也不要编一个看起来合理的数字。培训手册会被当作依据使用，错误数据的代价远大于空白。

3. 保留讲师的"人味"

转写稿里最值钱的往往不是标准条款（那些查得到），而是：

• 比喻——"评定不是考试，是给生产兜底"
• 教训——"我见过一个厂，就因为烘干箱温度计坏了，整批返工"
• 禁忌——"这个参数千万别动，动了整条线都要重评"
• 现场经验——"图纸上没写的，你得去问装配"

这些用 quote / case / warn / tip 原汁原味保留，只做最小限度的语法修整（去口头禅、断句）。全部改写成标准书面语，手册就死了。

4. 让断链的地方接上

讲师对着现场听众讲话，大量依赖共同语境。读者没有这个语境，必须补：

• 指代还原："这个" → "坡口角度"
• 省略补全："按老规矩" → 写出老规矩是什么（写不出就标 [待核实: "老规矩"具体指什么]）
• 术语首现给定义（concept 组件）
• 每章开头用 ::: lead 说明"本章解决什么问题"

5. 内容类型决定组件类型

不要通篇段落，也不要通篇卡片。按内容性质选容器：

• 能列举的 → 列表
• 有顺序的 → steps
• 有对照的 → compare 或表格
• 有条件的 → warn / tip
• 有出处的 → supplement
• 能一句话说清的结论 → keypoint

判断标准：同一份文档里，keypoint 不要超过章节数的 2 倍。满篇高亮等于没有重点。

工作流程

阶段 0 · 确认输入

确认四项信息（缺哪项问哪项，一次最多问三个问题）：

1. 转写稿文件路径
2. 培训主题、讲师、场次（用于封面元信息）
3. 阅读对象（决定详略：同专业人员可省基础，跨专业人员要补背景）
4. 期望输出（默认 Markdown + HTML；是否需要 PDF，PDF 走浏览器打印，不经脚本生成）

转写稿若是纯逐字稿，直接开工；若是分段带时间戳，先去掉时间戳。若稿件不足 500 字或缺失主体内容，先向用户确认是否上传了完整文件。

阶段 1 · 通读标记（只读，不写）

第一遍不要动笔改写。 完整读完，边读边在脑子里建五张清单：

噪声识别口径与疑点处理细则见 references/distillation-method.md。

阶段 2 · 设计章节骨架

先定 ## 章节，再动笔写内容。骨架定错，后面全是返工。

从 references/document-architecture.md 选一个模板（技术型 / 标准宣贯型 / 案例经验型），按主线调整。

骨架要求：

• 每章只回答一个问题，标题写知识本身，不写"第一部分""第二部分"
• 3–7 章为宜（1 小时培训约 4–6 章）
• 按"先总后分、先概念后操作、先基础后进阶"排序
• 每章开头一句 ::: lead 说明本章解决什么问题
• 章末若内容多，用 ::: summary 收口

把骨架先给用户看一眼再往下写——省掉大量返工。

阶段 3 · 重构写作

逐章写，遵循以下要点（完整对照表见 references/distillation-method.md）：

• 段落控制在 3–5 行，长段落拆开
• 每章至少一个非段落元素（表格 / steps / compare / case）
• 操作类内容一律 steps，每条写成"动作：做法与判据"
• 讲师强调的易错点用 warn，不要写成普通段落
• 参数、判据、对照关系用表格，不要用文字罗列
• 讲师原话用 quote，署名写讲师姓氏 + 身份
• 有数据的地方标清单位和前提条件

组件语法速查见 references/component-reference.md。

阶段 4 · 构建

Markdown 写完后用构建脚本生成 HTML：

python scripts/build.py <手册>.md
# 常用参数
python scripts/build.py <手册>.md --theme cyan --open

脚本零第三方依赖，纯标准库。它会：

• 解析 frontmatter 生成封面元信息
• 由 ## / ### 自动生成侧边导航与章节编号
• 解析 ::: 组件容器为对应视觉组件
• 输出 [stats] 统计，用于核对章节数、组件数、待核实项

主题（--theme 或 frontmatter 的 theme）：

阶段 5 · 质检与交付

按 references/quality-checklist.md 逐项过一遍，重点核：

• 章节标题是不是知识性的（不是"第三部分"）
• 有没有编造的数据（search [待核实]，确认每一条都是真的存疑）
• 每章是否有非段落元素
• keypoint 是否泛滥
• 讲师原话是否保留下来（至少 3 处）
• 念一遍首段：没到场的人能看懂吗

交付两个文件：.md（可继续编辑）+ .html（可直接分发）。

若使用者要 PDF：用浏览器打开 HTML → Ctrl+P → 目标打印机选「另存为 PDF」，并在「更多设置」里勾选背景图形（否则卡片底色和配色会丢失）；建议边距选「默认」、勾选「页眉和页脚」去掉。打印样式已按章节自动分页，无需手动调整。

> 不要在脚本里调用无头浏览器生成 PDF。企业终端常装有全盘透明加密客户端（如亿赛通 E-SafeNet），无头进程写出的 PDF 会被加密，换台机器或发给同事就打不开；而浏览器自己打印、自己另存为的文件是正常明文。这一条踩过坑，写进规范里。

输出结构

<工作目录>/
├── <培训主题>.md        # 源文件，后续修改改这个
└── <培训主题>.html      # 自包含单文件，可直接发同事

Frontmatter 模板

---
title: 低合金高强钢焊接工艺控制
subtitle: 从材料特性到现场执行的六个关键判断
kicker: 内部培训知识手册
theme: amber
meta:
  主讲: 张工（工艺技术部）
  培训来源: 2026 年第三期焊接技术培训
  培训时间: 2026-09-18
  面向读者: 焊接工艺组、生产准备组
footnote: 本手册依据现场录音转写整理，对口语内容做了删减与结构化重组。标注为「补充」的内容为整理时补入的背景资料，标注为「待核实」的内容原文未明确，使用前请与讲师或现行标准核对。
---

meta 下每一条生成封面上的一格元信息，建议 4 条（2×2 布局）。

反模式

出现以下任一情况，说明做成了纪要而不是手册：

• 章节按"开场 / 第一部分 / 第二部分 / 总结"划分
• 正文里还有"下面我讲"、"大家看这里"、"刚才说过"
• 全篇纯段落，没有表格、步骤、卡片
• 通篇 keypoint，或一个 keypoint 里塞了 8 条要点
• 讲师的原话、比喻、教训一处不剩
• 出现讲师没说过的具体参数（编造）
• 问答部分被堆在文末当附录，或直接删掉
• 每章标题下没有导语，读者不知道这章为什么存在

附带资源