口述稿整理成文 Skill

目的

把口语化口述稿整理成结构清晰、逻辑自洽的成文。口述稿天然带着散点、跳跃、重复和编号混乱，直接交付或排版会带上逻辑硬伤；本 skill 用「六项逻辑审校」在成稿前把这些硬伤找出来并理顺。措辞可适度润色，但金句与关键信息一字不动；不做内容压缩。

润色与结构边界

• 措辞：可适度润色——口语冗余、语病、明显不通顺的句子可以顺；重复啰嗦的表达可以精简字词。但两类东西一律不改：
  1. 金句：原文的生动比喻、口语化妙语、有个人风格的表述，保留原样；
  2. 关键信息：数字、日期、人名、产品名、金额、法条、事实与结论，一字不改。
• 拿不准某句是不是金句时，保留原样（宁可保守）。
• 结构：以原文逻辑为默认，不强制——默认跟着原文的论述顺序走；为阅读流畅可以重排段落、把后置的结论提前，但不删并内容、不丢任何论点。
• 润色幅度在「改动清单」中说明，方便用户复核。

触发场景

• 用户提供口述稿 / 录音转写 / 口语化草稿，要求「整理成文」「写成文章」「理顺逻辑」
• 成文后要发布到公众号、做成课程要点稿、讲座逐字稿等
• 用户问「哪些有矛盾」「前后不一致的地方」

代跑口径

一次代跑默认 ≤2 分钟交付；长稿（万字级）按实测基线 + 增量口径，只补缺的那一件，不重跑整链。
禁止：为"刷新"重跑等价成果、通读脚本源码、逐页读图复核。
确认依据以脚本定量输出为准（typo_prefilter.sh 的错字与引号命中数 / fix_quotes.py 的配对结果 / md2docx_macos.py 的字数与引号自检），只对告警处回原文读上下文；逐页目检留给人。

分级执行（脚本优先、省 token）

• 脚本优先：确定性检查一律用脚本，不靠 AI 逐条审——成稿前必跑 sh scripts/typo_prefilter.sh <稿件>（错字串候选扫描 + ASCII 直引号检查 + 英文单引号候选），只对命中行做语境判断。
• 成稿后必跑 python3 scripts/fix_quotes.py <成稿.md> 修引号。AI 写 md 时几乎必然会打出 ASCII 直引号（2026-09-12 实测：一篇 2000 字成稿里出了 38 个），逐个手工改既慢又易漏。脚本按开闭交替替换、自动跳过代码区与英文撇号、引号数为奇数时直接报错不猜。改完再跑一次 typo_prefilter.sh 确认第②③项归零。
• ⚠️ 脚本是幂等的，但只覆盖"跑的那一刻"：之后任何编辑（哪怕只改一个词、改一处措辞）都可能引入新的 ASCII 直引号。转 docx 前必须再跑一次 fix_quotes.py（成本近乎为零）。2026-09-25 实测踩坑：在 fix_quotes 之后用 Edit 改了 2 处措辞，正文里留下 2 个孤立右引号，肉眼完全看不出，卡在 md2docx 的交付自检上。
• ❗ 自检报「弯引号左右不等 / 配对异常」时，用 python3 scripts/fix_quotes.py <成稿.md> --verify 定位——逐位置配对扫描并打印每处孤立引号的行号与上下文，有问题以非零码退出。⚠️ 左右计数相等 ≠ 配对正确：2026-09-25 用毒样本自证，一个「左 3 / 右 3 计数相等、实际含 1 个孤立右引号 + 1 个未闭合左引号」的文件能骗过一切计数式检查，只有逐位置扫描抓得到。
• 脚本覆盖边界（勿误解脚本做了很多）：脚本只兜底最确定的 4 类——错字串、ASCII 双引号、直角引号、英文单引号候选。六项逻辑审校中的「编号断裂 / 结论重复 / 概念混用 / 一体两面 / 分工说明」，以及顿号、冒号、书名号、省略号、破折号等标点与语法病句，属语义判断，由 AI 按「基础档 / 全量档」逐库过。脚本兜底确定性，AI 兜底语义，两者分工不要混。
• ⚠️ 脚本兜不住语音转写造成的非词串（如把 WorkBuddy 简称 WB 转成「我巴」、把「自己识别字体字号」转成「之类自起自号」）——这类既不在同音错字表里，也不是标准错别字，只能靠 AI 读上下文判断。判断口诀：读起来不是词、但按上下文能猜出唯一含义的，就是语音转写的牺牲品，直接按上下文还原，不要因为"表里没有"就放过。
• ⚠️ 自己的自检正则也会误报：用 第[一二三四五] 查编号断裂时，「第一版」会被误判成序号词——序号词必须查「第N个/点/种/条/类」或句首序号，不能只查「第N」。误报要判语境，不能直接改稿。
• 基础档（所有任务必跑）：预过滤脚本 + homophone-corrections 第六节 12 组热表（命中先判语境）+ 语法五类病句模式（proofreading-rules 第一节）+ 六项逻辑审校。
• 全量档（法律文书、判决书摘要、涉外材料、交付级长文）：三库全量加载 + 规范表述 + 引文核查九条 + 数字跨度实算。
• 原则：表格是查询备料，不是必载上下文——短稿不整表加载。

配图占位符（作者要自己插图时）

触发：用户说「我还要插入图片」「图我自己配」，或成稿要发公众号。

做法：
- 在逻辑位置插入独立成段的 【配图 N | 建议内容】，N 全文连续编号；
- 「建议内容」要写清这张图要给读者看什么（哪个界面、哪个按钮的位置、导出后的什么结果），让作者照单截图即可，不用回头猜意图；
- 头图 / 效果总览图放在引子之后、正文之前——读者第一眼先看到成果，再看怎么做到；
- 「可选」图标注出来，方便作者按成本取舍；
- 插图位置由内容决定，不硬凑数量：讲一步插一张，无图可插的纯观点段落不插。
- 交付时在改动清单里一并汇报占位符数量与清单（转换脚本会自动统计并高亮）。

原稿自带图片：原位保留（图文混排口述稿）

触发：用户说「图片和文字的相对位置不要改变」「图片全都保存」，或源 docx 本身就带一堆截图（典型：视频语音转写的逐字稿 + 讲师 PPT 截图，一次可达上百张）。

铁律：此时禁止走 md2docx_macos.py——它是 pandoc 重建文档，原图会全丢、位置全乱。

正确做法是以原 docx 为基底重建（图片连尺寸一起继承，一轮搞定）：

1. 抓图片段落：python-docx 打开原文档，遍历 p，取 a:blip 的 r:embed → part.rels[rid].target_ref 得到 media/imageN.jpeg，以 imageN 为键 copy.deepcopy(p._element)。
   ⚠️ 命名空间坑：blip 在 drawingml 命名空间（.../drawingml/2006/main），不是 w:。写成 p.iter(qn('w:blip')) 会静默返回 0 命中，让你误判「这文档没有图片」而放弃保图方案。判断文档里到底有没有图，先 document.xml 里 grep blip 计数。
2. 清空正文：删掉 body 下所有 w:p。⚠️ 不少转写工具生成的 docx 根本没有 w:sectPr，body.find(qn('w:sectPr')) 返回 None，脚本会崩。需 OxmlElement('w:sectPr') 自建并 body.append，再设 A4（21×29.7cm）+ 2.54cm 页边距。
3. 按整理稿 md 重建：图片位置在 md 里写成独立成段的占位符 {{img:imageN}}（不带扩展名，正则好写）。逐行扫描：占位符 → sectPr.addprevious(克隆元素)；文本/标题 → doc.add_paragraph() 并显式设 w:eastAsia=微软雅黑。
4. 先量图宽再定页边距：<wp:extent cx cy> ÷ 360000 = cm；内容宽必须 ≥ 图宽，否则图会溢出页面。（实测案例：全套图统一 15.17×7.62cm，A4+2.54cm 边距容宽 15.92cm，刚好放得下。）
5. 必跑校验（不看渲染也要看这个）：解析产物 docx，按文档顺序抽 a:blip → 图片编号序列必须严格递增、无缺号、无重号；再核 word/media/ 文件数、document.xml.rels 引用数、wp:extent 数三处相等。三项全等才算过。

⚠️ 图文混排稿的第一铁律：图文锚定，只能段内精简

一张图对应它下方的一组文字。这段文字原先在哪张图下面，整理后必须还在那张图下面。文字可以精简，位置不能动。

这意味着在图文混排的口述稿上，禁止：
- 删除整段（会让下方图与上一段文字错位绑定）
- 合并相邻段（相当于把两段变成一段，图与文字的段落级对应被破坏）
- 把文字跨图搬运

允许：段内删冗余词句、句内压缩、把寒暄句删短到最低限度。

验收判据（必须跑）：把两个文档都折成「图/文」交替序列（I/T 字符串），两边必须逐位完全相同。

# 提取 图文交替模式
flow = ''.join('I' if 段落含图片 else 'T' for 段 in 文档段落)
assert flow_her == flow_mine       # 不相等就是动了位置，一律返工

⚠️ 踩坑实录（2026-09-24）：作者第一次让我精简时，我用"删段+合并段"的方式把 3.3 万字压到 2.6 万，段落数从 400 降到 381；作者立刻指出"文字跟图片的相对位置不能变，一个图片对应一段文字"。返工做法是：从作者版 docx 提取完整段落流（图 + 文），逐段一对一映射到精简版（相似度 ≥0.5 贪心配对），配不上的段落手工段内精简，最后按原段落流重建——精简率从 20% 降到 17%，但图文关系 100% 保住。

⚠️ 顺带记住：用"我的 md"去重建带图的文档是危险的——md 里图片只是占位符，看不出图与文字的段落级绑定；一旦 md 的段落结构与作者版不同，重建出来的图文关系就变了。图文混排稿的基准永远是作者那份 docx 的段落流，不是任何 md。

轻量改动路径：原位改写文字段落（只改字、不动结构）

若这一轮只是改措辞 / 统一术语 / 补点破句（不删段、不合并段、不挪文字跨图），不要走 deepcopy 重建——重建把段落级格式（numPr 自动编号、缩进、行距）一并重来，风险大于收益。正确做法是在原 docx 上原位改写：

1. python-docx 打开原文档，对每个要改的段落只删 <w:r>（保留 w:pPr，numPr/ind/spacing/jc 原样不动），再按新文本追加 run；
2. 新 run 的 rPr 照抄原段落模板：<w:rFonts ascii/hAnsi/eastAsia="微软雅黑"/> + <w:b/>（非粗用 <w:b w:val="0"/>）+ <w:color w:val="1A1A1A"/><w:sz w:val="22"/>，<w:t xml:space="preserve">；用 ** 标记在改写字典里标出加粗范围，与原文加粗范围保持一致；
3. 段落序号按原样处理：自动编号段（有 numPr）的新文本里不能再写"1. "；手打编号段（无 numPr、正文里本来就是"2. "）必须把"2. "写进新文本——两类混在同一篇里是常态，写反了不是双号就是缺号；
4. 落盘后跑「图文交替模式」校验 + 逐段文本 diff + 图片三项计数（blip 引用数 / word/media/ 文件数 / wp:extent 数；注意 word/media/ 那条目录项本身不是孤儿图），并核对 rFonts w:eastAsia 缺失的 run 数与原文档相等（等值即无回归；带图段落常有 1 个空 run 无 rPr，属正常）。

⚠️ pandoc 提取的假警报（2026-09-26 实测）：源 docx 本身用弯引号时，pandoc -f docx -t markdown 会把弯引号规范化成 ASCII 直引号（默认 smart 扩展），于是 typo_prefilter.sh 第 ② 项报满屏命中——这是假警报，不是源文件的毛病。复核真相用 python-docx 读 p.text，或 pandoc -t markdown-smart；若逐段 p.text 都是弯引号，正文引号无需再改（本轮新写的字仍必须写弯引号）。

核心：六项逻辑审校

对全文逐段检查以下六类问题，发现问题先列出清单（含原文引用），再动手整理：

① 编号断裂

• 文中出现「第一/第二/第三」「特点/作用/点」「首先/其次/另外/最后」等序号词时，逐一核对：
• 每个序号是否都有对应项？
• 「第二个 X」前面有没有「第一个 X」？
• 同一层级的称呼是否统一（特点/作用/点不能混用）？
• 处理：统一编号层级；缺失的第一项从上下文补出，或删掉孤立序号。
• 作用域冲突（多层同名序号，高频）：外层已有「第一步 / 第二步」，内层又冒出「第一步 / 第二步 / 第三步」，读者会串层，误以为内层第一步是全文第一步。处理：不动操作步骤的措辞（用户说「步骤不要改」时尤其），只在内层序号组前补一句作用域引导，如「那如何完成呢？一共三步。」——用引导句把内层框进「XX 上的操作」，而不是改写用户的步骤原文。

② 结论重复

• 同一结论是否在不同位置重复出现（换了说法但实质相同）？
• 处理：合并到一处，删掉重复的那句；若重复处各有侧重，则明确分工后保留。

③ 概念混用

• 常见陷阱：把「操作繁琐」（原生有但难用）说成「功能欠缺」（原生根本没有）。
• 处理：区分两类并分别归类，必要时用一句话点明区别（如「补的是原生根本没有的能力，跟『只是麻烦、不是没有』是两回事」）。

④ 一体两面未点破

• 同一个动作同时被夸「方便」又被批「有缺点」时，检查是否点明了两者是同一动作的两面。
• 处理：补点破句，如「方便的是『转发』这个动作，缺的是全文留存」。

⑤ 分工说明补位

• 文中同时出现「能力强 / 效果流畅」与「效果不佳 / 会出错」时，通常缺一句「谁负责什么」的分工说明。
• 处理：补桥梁句，如「人定规则、Agent 执行，两者配合才不会乱」。

⑥ 术语与中文标点统一

• 品牌名大小写（Workbuddy / WorkBuddy）、别名（ima Agent = ima Copilot）、笔误（dema agent → ima agent）在成稿前统一。
• 若全文用别名（如「自带 Agent」），在开头第一次出现处点明与正式名（如「ima Copilot」）的关系。
• 中文引号铁律（2026-08-30 实测踩坑）：成稿的 md 源里引号必须直接写中文弯引号“”，禁止打 ASCII 直引号 "。实测踩坑：成文时图省事打了 22 个直引号，pandoc 转 docx 后按英文规则配西文字体渲染，中文语境下左引号也显示成下引号。
• 默认用弯引号“”，不要用直角引号「」（2026-09-22 实测）：作者已发布文章的抽样统计里，弯引号占绝对多数（《写了一个Skill…》122 处、《微信文件存入ima…》36 处），直角引号极少。
• ⚠️ 直角引号是全流程的雷区，已加机械防线：md2docx_macos.py 只统计弯引号左右配对，全篇用直角引号它会显示「弯引号 左 0 / 右 0 ✘→看似通过」，报不出来；fix_quotes.py 同理。所以预过滤脚本第 ②b 项专门统计直角引号（2026-09-23 实测踩坑：成稿全篇 14 对直角引号，两个脚本都"看似通过"，只有人工核对才发现）。写稿时直接写弯引号 “”，别靠事后脚本兜。
• 修复方法：写入成稿后直接跑 python3 scripts/fix_quotes.py <成稿.md>（开闭交替替换、自动跳过代码区与英文撇号、奇数则报错不猜），比手工替换可靠；转完给全部样式补 w:eastAsia=微软雅黑 中文字体声明（python-docx 遍历 doc.styles 设 rFonts.eastAsia）双保险。
• 同音错字校验（流程详见 references/homophone-corrections.md）：①跑 sh scripts/typo_prefilter.sh 确定性预过滤，再对照库复核；②对照表没有且不确定的专有名词，主动联网查证官方正确写法（大小写、空格、中文名），不等用户开口；③全网叫法不统一的，按最主流/官方写法修正，并主动说明"存在多种叫法，已采用 XXX"；④修正后汇报口径："已联网查证 X 项，修正 Y 项，存疑 Z 项"；查不到的保留原文加 [存疑：可能为XXX] 标注。
• ⚠️ 语境依赖词对（权力/权利、伏法/服法、法治/法制、定金/订金等）命中先判语境，禁止机械替换——「行使权利」在民商事语境是正确表述，改错会造成实质性法律错误。热表见 homophone-corrections.md 第六节；错别字大表（副/幅、度/渡、义近词、敬谦辞、成语误用等）见 references/common-typo-table.md。
• 语法标点数字规则库：语病顺句、标点（含中英混排全角）、数字时间、涉外与地区事务的规范表述、引文核查五类，逐类对照 references/proofreading-rules.md 执行（按「分级执行」定档）。

工作流

1. 通读：完整读原文，不做摘要。源文件是 .docx 时先用 pandoc -f docx -t markdown --wrap=none <源> -o 原文.md 提取为 md。口述稿直接贴在对话里时（没有文件），先把原文一字不改地落成 00-原口述稿.md 再往下走——typo_prefilter.sh 只吃文件路径、读不到对话文本；落成文件同时留下一份「改动前」的基准，事后做改动清单时可逐项对照，不靠记忆。⚠️ 提取出的 md 里的 ASCII 直引号不能直接当成源文件的毛病——pandoc 的 smart 扩展会把源文件里的弯引号规范化成直引号（判据见「轻量改动路径」一节的假警报说明）。
2. 审校：先跑 sh scripts/typo_prefilter.sh <稿件> 确定性预过滤（错字候选 + 双引号 + 单引号候选），再跑六项清单，输出问题清单（问题类型 + 原文引用 + 处理动作）；按「分级执行」定档，全量档过 references/proofreading-rules.md 五类规则，不确定的专有名词联网查证。
3. 确认：问题清单给用户过目，确认后再动手（用户明确授权直接改的除外）。
4. 整理：按清单逐项整理——结构可重排、措辞可按「润色与结构边界」适度润色，金句与关键信息一字不改；「点破句」是唯一允许新增的内容，且必须用原文口吻。写完立刻跑 python3 scripts/fix_quotes.py <成稿> 修引号，别留到最后。
   - 需要 Word 交付时，跑 PATH="/opt/homebrew/bin:$PATH" python3 scripts/md2docx_macos.py <成稿.md> [出参.docx] 一步到位：pandoc 转换 + 微软雅黑（含 w:eastAsia）钉死 + 配图占位符高亮 + 交付前引号自检（ASCII 直引号 / 弯引号左右配对）。自检不过关脚本以非零码退出，不交付。
   • ⚠️ 必须显式带 PATH（2026-10-02 实测）：沙箱内的 Bash 找不到 pandoc（报 FileNotFoundError: 'pandoc'，退出码 1），而本机 pandoc 在 /opt/homebrew/bin/pandoc。不带 PATH 前缀会误判成"脚本坏了"。

5. 自检：对照六项清单复核输出，确认无残留问题；关键信息（数字/日期/人名/产品名/结论）与原文逐项核对无改动；术语全局一致（同一产品不得出现两种写法）；同音错字自检：命中候选均已判语境（无机械替换）、全部修正、存疑项已标注、已按口径汇报查证结果；发现的新对照项当次任务内沉淀入库，新错字串同步加入 typo-patterns.txt；规则库自检：语法病句模式、标点（含中英混排全角）、数字倍数与范围、规范表述（涉外与地区事务）逐类过一遍无残留；文内事实回素材核：文中出现的位置、页数、顺序（如"最后一页""第三部分"）、数字、书名、产品名，一律回原始素材（课件/文件/原稿）实测一遍再定稿 —— 口述里的位置感常常不准，靠叙述写必错；同一事物在正文与素材里的叫法也要一致（如正文"关键资料索引" vs 课件"关键资源链接索引"，须择一或明确区分）；引号自检（不过关不交付）：重跑 sh scripts/typo_prefilter.sh 第②/②b/③项——ASCII 直引号与直角引号数量都必须为 0，英文单引号逐处判语境（don't/it's 等英文撇号可保留、中文语境单引号改弯引号 ‘’），中文语境引号全部为弯引号 “”（不用直角引号「」）。

6. 后续修订（交付之后又来新要求）：作者会在 WPS / 腾讯文档里直接改那份 .docx，本机 .md 随即落后。所以：
   - 动手前先判基准：读 docx 的 docProps/app.xml（Application 会变成 WPS Office… / Tencent office）与 docProps/core.xml 的 dcterms:modified，与 md 的 mtime 比对；以 docx 为准，禁用旧 md 当基准，也不得把「md 里有、docx 里没有」当成作者漏改。
   - 她指定位置（常为编辑器选区）时，只改该处，其余（含她自己改过的段落）一处不碰。
   - 改 docx 走 tencent-local-office-edit 的 editor_sdk 通道：get_pool_status 取 file_id（不要 open_file）→ doc_find 定位拿 UTF-16 坐标（不手算）→ doc_replace_text / doc_insert_text（多处替换从后往前，逐次重查坐标）→ save_file；不主动 close_file。
   - is_dirty=true 说明作者有未保存的改动：先 doc_resolve_document_structure（mode=full, limit=0）把内存里的正文读一遍再动手，避免踩掉她的在编辑内容。
   - ⚠️ editor_sdk 报 document is not open 时的降级（2026-10-03 实测）：现象是 get_pool_status 能列出实例，但 doc_find / doc_* 一律回 document is not open；该实例的 file_path 常指向 …/document-save-staging/<uuid>.docx 这种已被清空的临时目录（先 ls 确认目录为空，即可判定这条通道就用不了）。

   • 不要用 open_file 去"救"：open_with_existing=true 在磁盘文件已更新时会清掉旧实例重开，可能丢掉未落盘的改动；默认 fresh open 又会另开一个与前端预览脱节的实例。
   • 改走 python-docx 原位改写磁盘 docx（按本文件「轻量改动路径」：只删目标段落的 <w:r>、保留 w:pPr、新 run 的 rPr 照抄原文模板）。
   • 三条安全动作缺一不可：① 改前 cp -p 备份（注意备份时机——若作者刚插过图，早先的备份可能不含图，不能用于完整回滚，改完应再备份一份"含图版"）；② 改后逐段 diff 证明只有目标段变化（其余段落逐字未动）；③ 核图片三项计数（word/media/ 文件数 / document.xml.rels 的 media 引用数 / document.xml 里 <a:blip> 与 <w:drawing> 数）。python-docx 保存会原样保留既有 drawing，但顺手验一遍成本极低。
   • 顺手扫失效图片引用：<a:blip r:embed=""/>（值为空）就是一张坏图，Word 里显示为破图占位框——作者插图未完成或上传失败时会留下这种元素。只报告、不擅自删（可能正在上传中）。
   • 收尾仍要提醒"关闭重开"：作者那个已打开的窗口显示的是内存副本，save_file／磁盘改写都不会自动刷新；并警告在旧窗口按保存会把刚落盘的改动整个盖掉。
   • 改完把 md 同步成与 docx 一致的文本版并做逐字比对（剥掉 Markdown 标记与空白后应完全相等）；docx 里有图片时 md 无法承载，须在汇报里说明。
   • 改完必须提醒"关闭重开"：save_file 只落盘，作者那个已打开的窗口里是打开时读进内存的副本，不会自动刷新，会误以为没改。同时必须警告：在旧窗口里按保存＝把刚落盘的改动整个盖掉。汇报时给出可自查的锚点（改后应搜不到的词 / 应搜得到的词），并说明本地 docx 与腾讯文档在线副本是两份独立副本，改本地不会同步线上。

禁止项

• ❌ 不摘要、不压缩原文内容（论点和事实一条不丢）
• ❌ 润色不碰金句与关键信息（数字/日期/人名/产品名/金额/法条/结论一字不改）
• ❌ 不凭空添加原文没有的收益、数据、结论
• ❌ 不擅自删用户明确点名的内容

输出

• 结构化的整理稿（Markdown 或按用户要求的格式）
• Word 交付用 scripts/md2docx_macos.py 生成（字体、引号、配图占位均已自检）；但原稿自带图片的图文混排稿必须改走「原稿自带图片：原位保留」一节的做法，否则图片全丢
• 附「改动清单」：新增 / 删除 / 移动 / 改名的具体位置，方便用户复核；末尾单列存疑项——语义不明、无法从上下文唯一还原的原文句子，写明原文与暂定处理，请作者确认

<!-- © 2024-2026 陆凌燕（北京德恒（无锡）律师事务所）. Licensed under MIT. -->

> 法律科技实务工具 · 维护者陆凌燕律师（北京德恒·无锡）