/transcription-corrector

name: transcription-corrector
homepage: https://github.com/cat-xierluo/legal-skills
author: 杨卫薪律师（微信ywxlaw）
version: "1.0.9"
license: MIT
description: 转录稿纠错与轻度优化。本技能应在用户需要按用户词典纠正 ASR 转录稿同音字与英文专有名称漂移时使用。不要用于：重写为课程章节、报告、总结，或完全空白的素材创作。

Transcription Corrector

> 首次使用流程见 [references/first_use.md](references/first_use.md)。工作流中的判断准则见 [references/correction_patterns.md](references/correction_patterns.md)。

概述

把 raw 转录稿里"听得对但写不对"的同音/形近/拼写错误按用户词典统一改对，并按需做轻度润色。**不做**：改写、总结、删减、改事实、生成课程章节。

| 模式 | 触发 | 输出 | |---|---|---| | **纠错模式（默认）** | 拿到 raw 转录稿，要先做"校对" | `archive/.../{原文件}_corrected.md` + 校对对照日志 | | **纠错 + 轻度润色** | 还要顺手把发言人合并/标点整理 | 在纠错基础上再润色，输出到 `archive/.../{原文件}_polished.md` |

**与下游处理工作的边界**：

• 本 skill 不输出课程大纲、不重组章节、不改写为书面课程；只做"读起来对、不再丢脸"这一步。
• 用户词典 YAML 格式（`version` + `terms` 列表）已成为本 skill 公开的接口约定；其他下游处理工作可以按需读取同一份词典文件。

工作流程

工作流按 **5 个 Phase** 组织，每个 Phase 含 1-3 个 Step。默认开启 Phase 1-3，Phase 4 默认关闭（需要用户明确开启）。

Phase 1 准备
  Step 1.1  读取配置（词典）
  Step 1.2  TXT → MD 转换（如需要）

Phase 2 识别
  Step 2.1  识别文件结构
  Step 2.2  通读识别高置信误转写

Phase 3 修正（默认开启）
  Step 3.1  词典统一替换（改字）
  Step 3.2  基础空白清理（改空白）
  Step 3.3  口语词精简（删字）

Phase 4 润色（默认关闭）
  Step 4.1  发言人合并
  Step 4.2  标点规范
  Step 4.3  段落切分

Phase 5 输出
  Step 5.1  主归档（必出）
  Step 5.2  源文件目录镜像（必出）

**为什么这样分组**：

• **Phase 1 准备** vs **Phase 2 识别** vs **Phase 3 修正**：准备不接触文本内容；识别是"看"；修正是"改"。三者性质分明
• **Phase 3 内部三个 Step** 改的是三类不同对象：3.1 改字（语义）、3.2 改空白（格式）、3.3 删字（语言字符）。三类操作各自独立，可单独审计
• **Phase 3 vs Phase 4**：Phase 3 是"读起来对"（无损 / 轻损），默认开启；Phase 4 是"看起来专业"（结构调整），默认关闭。两者泾渭分明
• **Phase 5 输出** 与前 4 个 Phase 解耦：无论前 4 步做了什么，输出阶段都按相同策略双写

---

工作机制

转录稿修正的本质是"对每一处误转写做出独立判断"。这个判断的输入是上下文，输出是一处 Edit，三者必须由同一个 agent 在同一个上下文里完成。

**为什么按"每处 Edit"展开**

• **每处误转写是否成立，取决于它在上下文中的指向**。例如"style"可能是 skill 名，也可能是真正的"风格"——批量替换不能区分。
• **ASR 错误无穷无尽**（大小写漂移、空格漂移、断词重连、音节吞并、形近字……），任何静态规则都会漏。
• **词典是"目标值参考表"**，不是"错误词 → 正确词"的映射。`terms: ["WorkBuddy"]` 告诉 agent "正确的写法是 WorkBuddy"，但不告诉 agent "这处原文是否需要改"。

由此推出**自然的执行流**：

1. agent 用 `Read` 把源文件读进上下文（必须通读全文） 2. 对每一处候选误转写，agent 在上下文中独立判断"换 / 不换" 3. 用 `Edit` 把每一处的决策落盘 4. 用 `Write` 写出 `correction_log.md` / `meta.json` / 源目录镜像

**为什么这个流是自洽的**

• 上下文只在 Read 之后才完整；判断必须在 Read 之后进行
• Edit 是"局部变更"工具，自然对应"每处决策"
• Write 写整文件，对应日志/元数据这种"一次性产出"
• 这三步组成了最小可执行闭环。任何其他方式（脚本批量、sub-agent 转交、regex 列表）都至少缺失其中一步的语义保证

---

Phase 1：准备

Step 1.0：加载 skill 配置（开关默认值）

skill 各项润色开关由 `config/config.env` 控制。加载顺序：

1. 命令行/调用参数传入的 `key=value` 覆盖 2. `config/config.env`（本 skill 自带） 3. `config/config.env.example`（默认值的"母本"，缺失 step 2 时用） 4. 若 step 2 和 step 3 都不存在，Phase 4 所有 Step 全部关闭，仅 Phase 1-3 跑

**配置示例**（`config/config.env.example`）：

# Phase 4 润色开关（默认全开，按需关闭）
POLISH_MERGE_SPEAKERS=true     # Step 4.1
POLISH_PUNCTUATION=true        # Step 4.2
POLISH_PARAGRAPH_SPLIT=true    # Step 4.3
POLISH_TOPIC_SECTION=true      # Step 4.4
POLISH_SUMMARY=true            # Step 4.5

# 输出策略
SOURCE_MIRROR=true             # 源文件目录镜像
SOURCE_MIRROR_CONFLICT=timestamp  # 冲突加时间戳

# 日志详细度
LOG_VERBOSITY=verbose          # verbose | compact

缺失的键统一按本节表格的"默认值"列取值（不在文件中硬编码，每个 Step 自己的 § 段注明默认值）。

Step 1.1：读取词典

1. 词典文件查找顺序（找到第一个存在的即用）：

• 命令行/调用参数传入的 `dictionary` 路径
• `config/user_dictionary.yaml`（本 skill 自带）
• 若都不存在，提示用户复制 `config/user_dictionary.example.yaml` 为 `config/user_dictionary.yaml`

2. 词典 YAML 格式：

version: 1
terms:
  - "WorkBuddy"
  - "Claude Code"
  - "Codex"

3. 词典的角色：**目标值 + 置信度权重**，不是触发器

• 词典项是"正确写法"——告诉 AI 目标值是什么
• 词典项**不直接触发替换**：AI 仍然必须先做上下文判断（这个词在当前上下文里是否指向词典项所代表的对象）
• 词典项**提高候选替换的胜出权重**：当 AI 在多个候选写法中二选一时，词典登记的写法优先级更高
• 也就是说：词典让"workbody / work body / Workbuddy"在竞争中更倾向被改写为"WorkBuddy"，但前提仍然是上下文明显指向 WorkBuddy 这个产品；脱离上下文的同形词不会被词典"硬拉"过去
• **不要**把词典当作"错误词 → 正确词"映射表来使用
• **不要**为了使用词典而强行替换普通词
• 模糊或低置信场景一律保持原文

Step 1.2：TXT → Markdown 转换（如需要）

当输入是 `.txt` 文件时，先做格式转换再进入 Phase 2。

**触发条件**：输入文件扩展名是 `.txt`。

**转换规则**（保守——只做格式包装，不改内容）：

1. **发言人 + 时间戳行**（如 `发言人 1 00:33:09`）：

• 识别正则：`^(发言人|说话人|Speaker|S)\s*[\d一二三四五六七八九十]+[\.、]?\s*(\d{1,2}:\d{2}(?::\d{2})?)$`
• 转成 Markdown 加粗行：`**发言人 1 00:33:09**`

2. **段落间空行**：连续的非空行视为同一段（保留原始换行），段落之间补一个空行 3. **不删除任何文字**：空行、空白、ASCII 装饰线（`---`、`===`）等全部保留 4. **不识别 H3 / H4 标题层级**：只到 H2 层级——H2 标题在 Phase 4 Step 4.4 中按"主题分章"原则插入；不主动把某段升级为 `###`/`####` 5. **不识别列表**：不把 `- xxx` 改成 markdown 列表——保持原样

**输出**：

• 中间产物：`{原文件 basename}_converted.md`，保留在 archive 子目录
• 后续 Step 2.1~5.2 在 converted 副本上进行
• 原始 `.txt` 文件保持不动

**示例**：

输入（`raw.txt`）：

发言人 1  00:33:09
我先说一下比较好的部分，就是整个最终的报告篇幅是比较充分的。
然后大家在一开始不知道怎么样一个报告是比较完善的，也知道怎么样去借鉴他山之石。
从这个阿尔法 gpt里面的这报告相当于蒸馏他的一个一个想法啊。
这个这个在前期一开始搭基建的时候确实是很有必要的一个措施。

发言人 1  00:33:57
呃然后。我注意到咱们在最终生成法律服务意见书的时候...

输出（`raw_converted.md`）：

**发言人 1  00:33:09**
我先说一下比较好的部分，就是整个最终的报告篇幅是比较充分的。
然后大家在一开始不知道怎么样一个报告是比较完善的，也知道怎么样去借鉴他山之石。
从这个阿尔法 gpt里面的这报告相当于蒸馏他的一个一个想法啊。
这个这个在前期一开始搭基建的时候确实是很有必要的一个措施。

**发言人 1  00:33:57**
呃然后。我注意到咱们在最终生成法律服务意见书的时候...

**不识别的格式**（保持原文）：

• 没有时间戳的"发言人 1："→ 保留为正文
• "Speaker A:" → 保留为正文
• 纯文本无发言人标记 → 整段视为正文

---

Phase 2：识别

Step 2.1：识别文件结构

通读 raw 稿，识别组织方式：

• **按发言人 + 时间戳分块**（如 `**发言人 1 00:33:09**`）— 多数 ASR 输出
• **自由段落**（无显式分块）
• **混合**（标题 + 段落 + 引用）

识别目的：决定 Phase 4 润色时是否合并同发言人连续发言。**不要改写分块结构**，保留原貌。

Step 2.2：通读识别高置信误转写

**必须完整通读全文**，以 Agent 视角扫描。**不列静态错误表**——ASR 错误无穷无尽（大小写漂移、空格、漏词、错位、同音字、形近字、断词重连、音节吞并…），任何预设列表都会漏判。

**核心原则**： > **仅在上下文明确指向某个词典术语时，才将近似误转写替换为该术语。** > **模糊或低置信场景保持原文，不做猜测式替换。**

**启动扫描的高频易错类别**（不是错误表，是判断启动点）：

1. **人名**：律师、当事人、证人姓名是否首次出现 + 后续引用是否一致 2. **英文产品/工具/平台名**：是否在工具使用、命令行、平台介绍等场景 3. **机构/活动/品牌名**：律协、青训营、训练营、赛题 4. **法律术语同音/形近**：代理 vs 带理、抵押 vs 抵压、知情 vs 至清 5. **数字/单位/时间戳**：1/7、0/6、中英文逗号混用；**保守原则**

**形式漂移识别**（参考但不穷举）：

• 大小写漂移（WorkBuddy vs workbuddy vs WORKBUDDY）
• 空格漂移（work body / Work Buddy）
• 连字符（Claude-code / Claude-Code）
• 拆分被识别为中文（"克劳德 code"）
• 漏字残字（"body" 残留在"让，如果 body帮我们"）
• 同音/形近字（"张律师 / 张老师 / 章律师" 类推）
• 断词重连（"然后让" 被拆成"让，如果"）

**禁止**：

• 只用 grep/正则匹配清单（必然漏）—— 详见 §"工作机制"为什么按每处判断展开
• 把"我"改成"我们"等无明确对照的"风格化"改写
• 替换词典外的术语
• 强行补全"看上去缺字"的句子——除非能确定是组合错误

---

Phase 3：修正（默认开启）

> Phase