local-transcript skill 解析¶

local-transcript 是一套面向本地音视频文件转写的端到端交付框架。它的核心设计思想是：转写任务的目标是围绕本地媒体文件，完成格式确认、依赖检查、音频抽取、ASR 选择、中文清洗、LLM 校对、段落化、缓存复用和成品导出，最终交付可直接复用的文稿。 因此它把格式解析、依赖检查、ASR 模式选择、三层缓存、中文清洗链路和结构化输出串成了一条明确流程。

1. 定义¶

local-transcript 用于：

• 将本地音频或视频文件转写为 txt、pdf 或 docx
• 对中文转写结果做简体转换、标点规范化、自然段落化
• 用确定性替换 + LLM 校对修正 Whisper 常见错误和上下文误识别
• 在 Apple Silicon 上优先使用本地 GPU 加速的 mlx-whisper
• 在需要时回退到 faster-whisper
• 通过缓存复用减少重复执行成本

它输出的不只是转写文本，还包括：

• 输入文件
• 检测到或推断的语言
• ASR backend、mode 和 model
• LLM 校对状态
• 请求的输出格式
• audio / raw transcript / clean transcript 三层缓存状态
• 最终输出路径
• 总处理时间
• 清洗是否成功

从设计上看，它更像一个“本地转写交付管道”，而不是一个只负责调用 Whisper 的提示词。

2. 背景与问题¶

这个 skill 要解决的，不是“模型不会调用转写工具”，而是本地转写任务在真实使用中经常停留在一个很尴尬的中间态：

• 识别能跑，但速度很慢
• 文本能出，但中文质量很差
• 输出存在，但仍远远达不到可交付状态

如果没有清晰框架，常见问题通常集中在 8 类：

local-transcript 的设计逻辑，就是先把“如何稳定地产生成品转录稿”拆成若干明确阶段，再把每个阶段的默认策略与回退路径固定下来。

3. 与常见替代方案的对比¶

先看它与几种常见做法的区别：

它的价值，不只是“把音频变成文字”，而是把转写任务从单次识别提升成可重复、可交付、可复用的本地文稿生产流程。

4. 核心设计逻辑¶

4.1 把“成品交付” vs “原始转写”当目标¶

local-transcript 从一开始就把最终产物定义成：

• cleaned final transcript
• txt / pdf / docx
• 自然段落
• 语言与标点规范化

这层设计非常关键，因为绝大多数“会转写”的方案，其实只完成了 ASR 阶段，而没有完成真正的交付阶段。评估也非常清楚地说明了这一点：without-skill 虽然能产出 5000+ 字符，但它仍然是 917 行短句、繁体中文、混合标点、错误未修正的中间文本；with-skill 才真正产出可复用文稿。

4.2 格式解析门禁 必须显式存在¶

这个 skill 在 agent 侧不允许在用户没有指定格式时自行猜测，而是要求：

• 用户明确说 txt / pdf / docx 就直接使用
• 用户要求多格式就同时生成
• 用户没说格式就先追问

底层脚本本身仍保留了直接调用时默认输出 txt 的行为，但 skill 这一层故意把“先确认交付格式”作为执行纪律固定下来。

这是个很直接的设计，因为“转写”不只是一种处理动作，也是一个交付动作。用户要 txt、pdf 还是 docx，决定了后续导出链路、字体处理和最终可用场景。skill 因此把格式当成执行前必须确认的显式输入，而不是上下文推测。

4.3 把 依赖门禁 放在真正执行前¶

local-transcript 会把依赖面显式列出来，并对不同层级的依赖分层校验：

• ffmpeg
• 本地 Python 执行
• mlx-whisper
• mlx-lm
• faster-whisper
• opencc
• reportlab
• python-docx
• 可选的 claude CLI
• 中文 PDF 所需字体

这层设计的价值，在于把依赖要求先说清楚，再尽量把能前移的失败前移。像 ffmpeg 这类系统级前置条件，会在较早阶段暴露；mlx-whisper、mlx-lm、faster-whisper 这类 Python 依赖，则是在进入对应转写或校对路径时加载和验证；claude CLI 属于可选后端，缺失时脚本会跳过该校对分支；中文 PDF 字体则是在实际写 PDF 时才检查。也就是说，这一层更准确的描述应是“依赖要求显式化，系统级依赖尽早校验，分支型依赖在对应路径上校验”。

4.4 默认 backend 是 mlx vs 更通用的 CPU 路径¶

local-transcript 的默认 backend 是 mlx，并优先走 Apple Silicon GPU。

这一步的价值很明确，因为在这类本地转写任务里，真正的工程增量之一并不是“知道有 Whisper”，而是知道：

• 在 Apple Silicon 上应优先用 mlx-whisper
• 同样或更高质量的模型可以显著更快
• CPU fallback 只是回退方案，而不该是默认路径

评估里这点体现得非常明显：with-skill 的 ASR 阶段仅 116.4s，而 without-skill 的 CPU 路径约 670s，慢了 5.8 倍。更重要的是，with-skill 用的还是更大的模型，却仍然更快。这说明它不是在做“速度与质量的取舍”，而是在做“平台能力的正确利用”。

4.5 fast / balanced / accurate 三档 mode 要做成固定预设¶

这个 skill 并不让用户直接面对一堆分散参数，而是把 ASR 配置收敛成三档：

• fast
• balanced
• accurate

这层设计的重点在于，转写任务的主要决策，不是 beam size 该设多少，而是：

• 我现在更重视速度还是质量
• 当前机器能否承受更高成本配置
• 是否需要额外 LLM 校对兜底

固定预设把复杂参数封装起来，同时又保留了可解释的行为差异。这让 skill 在交付上更稳定，也减少了临时试错。

4.6 三层缓存是核心工程设计 vs 附加优化¶

local-transcript 明确缓存三层结果：

• 提取后的 WAV
• raw ASR transcript
• clean final transcript

这层设计特别重要，因为转写工作天然具有“重跑成本高、经常重复导出”的特征。用户很可能会：

• 先导出 txt
• 之后再要 pdf
• 或者在相同输入和相同清洗配置下重复执行

当前脚本最稳定支持的，是对相同输入的重复执行复用，以及格式导出时避免重复做音频抽取和 ASR。它并没有把“只重跑 clean 层、不重跑 raw 层”开放成一个独立刷新接口，clean cache 的键也不是为所有清洗参数变化单独建模的。因此，这里的设计重点应理解为“把重复工作尽量降到更少”，而不是“任意阶段都能单独重跑”。

4.7 中文清洗被设计成分层链路 vs 单一规则¶

local-transcript 对中文的清洗链路是分层组织的：

1. 简体转换
2. 确定性替换
3. LLM 上下文校对
4. LLM 后的安全替换回补
5. 专有名词统一

这种设计之所以有效，是因为中文转写错误并不是同一种错误：

• 有些是系统性 ASR 高频错字
• 有些是依赖上下文的语义误识别
• 有些是全文层面的名称不一致

如果只用规则，修不了上下文问题；如果只用 LLM，成本高且容易漏掉已知高频错误。分层链路正好把这几类问题拆开处理，让每层做自己最擅长的事。

4.8 确定性替换表和 LLM 校对要并存¶

脚本默认使用内置中文替换表，并提供可选的外置 JSON 替换文件扩展机制，同时保留了 LLM 校对。

这层设计的价值，在于它把错误分成两类：

• 跨视频、可重复出现的 Whisper 系统性错误
• 与具体内容、领域术语或上下文有关的误识别

前一类最适合用确定性替换处理，几乎零成本、零延迟；后一类则必须交给 LLM 和上下文理解。评估里像 大便车→搭便车、配剂制→配给制 这类高频固定错误，适合规则层处理；而“哈萨尼”这种跨段一致性问题，则更能体现上下文校对和后处理兜底的必要性。

4.9 LLM proofreading 默认只对中文开启¶

skill 明确规定：

• 中文默认开 LLM 校对
• 英文默认关闭
• 英文只有在特殊需求下再通过 --llm-proofread-en 开启

这个决策很合理，因为：

• 中文 ASR 错误中，同音字、近音词、简繁和标点规范问题更集中
• 英文场景里很多内容用原始 ASR 就足够
• LLM 校对是最主要的时间成本

也就是说，skill 不是盲目把 LLM 叠上去，而是在精度收益和执行成本之间做了语言相关的默认选择。

4.10 专有名词统一要放在 LLM 之后¶

local-transcript 会在 LLM 之后再做一轮有限的 CJK 变体归并，把满足特定启发式条件的低频近似写法并到主形式。

这层设计很实用，因为 LLM 虽然能修很多上下文错误，但仍可能让同一名字在不同 chunk 中出现多个接近写法。这里的统一并不是通用实体识别，而是一个范围受限的后处理兜底，重点解决若干 3 到 4 个汉字短词的低频近似变体问题。评估里的“哈萨尼”案例，就直接展示了这层价值。

4.11 脚本外置执行是这个 skill 的重要设计¶

local-transcript 的核心能力并不只写在 SKILL.md 里，更大部分外置在 scripts/local_transcript.py 中。

这是一种很高效的组织方式，因为：

• 复杂执行逻辑不需要每次加载进上下文
• skill 本身只负责流程编排和参数策略
• 真正的工程能力通过脚本执行，几乎不消耗额外上下文 token

评估里的 Token 效费比之所以特别高，很大程度上就来自这点：大约 1100 多行执行逻辑都在脚本里运行，而不是占用模型上下文。

4.12 包含 backend、cache 和 cleaning 状态的输出契约¶

这个 skill 的 输出契约 要求返回：

• input
• language
• backend
• mode
• model
• LLM proofreading status
• requested formats
• cache status
• final paths
• total time
• cleaned successfully

这层设计的价值，在于转写结果不只是“给你一个文件”，而是“告诉你这个文件理论上走了哪条执行路径”。这对于：

• 复现问题
• 比较不同 mode
• 判断是否真正命中了 cache
• 追踪某次结果是否经过清洗与 LLM

都非常重要。它显著提高了可审计性，不过当前实现中 claude 后端缺失时会发生运行时跳过，因此这份摘要更接近“高可见度执行记录”，而不是对每个分支都完全精确的审计日志。

5. 这个设计解决了哪些具体问题¶

结合当前 SKILL.md、脚本实现和评估报告，可以把它解决的问题归纳为：

6. 主要亮点¶

6.1 它把“转写”定义成文稿交付，而不是语音识别¶

这是整个 skill 最重要的定位差异。它的目标是最终稿，不是原始 transcript。

6.2 Apple Silicon 上的默认路线很关键¶

mlx-whisper + 本地 GPU 是这个 skill 最核心的工程优势之一，评估也直接验证了这一点。

6.3 中文清洗链路设计得非常完整¶

简体转换、确定性替换、LLM 校对、post-LLM safety、专有名词统一，层次非常清楚。

6.4 缓存分层对应了真实重复执行场景¶

这让它不是一次性脚本，而是能承接格式变化和重复导出的生产型流程。

6.5 脚本外置让效费比很高¶

复杂逻辑跑在脚本里，LLM 只加载流程说明，这是它 token 效率很高的关键原因。

6.6 当前版本的价值，不只在准确率，也在工程完整度¶

评估里最明显的差异不仅是错别字修正，还包括性能、缓存、多格式输出、语言规范化和专有名词一致性。这说明 local-transcript 不是单点提升，而是一整套本地转写工程实践。

7. 什么时候适合用，什么时候不该硬用¶

8. 结论¶

local-transcript 的真正亮点，不是它能跑一次本地 Whisper，而是它把本地转写任务里最容易被忽略的工程判断系统化了：先确认格式和依赖，再选择合适的 ASR backend 与 mode，用缓存复用降低重跑成本，再通过简体转换、确定性替换、LLM 校对和专有名词统一把原始识别结果升级成真正可交付的文稿，最后再用结构化输出把整个执行过程说明白。

从设计上看，这个 skill 很清楚地体现了一条原则：高质量转写的关键，不是“先识别出文字”，而是让文字足够快、足够准、足够整洁，并且可以被稳定地重复生产出来。 这也是它特别适合中文本地媒体转写与成品输出场景的原因。

9. 文档维护¶

当以下内容发生变化时，这份文档应该同步更新：

• skills/local-transcript/SKILL.md 中的 工作流程、格式解析门禁、依赖门禁、默认行为、清洗规则 或 输出契约 发生变化。
• skills/local-transcript/scripts/local_transcript.py 中的 backend 默认值、mode presets、缓存版本、LLM proofreading 逻辑、proper noun unification、输出格式导出或依赖列表发生变化。
• skills/local-transcript/scripts/zh_replacements.json 或脚本内置替换表中的关键规则发生变化。
• evaluate/local-transcript-skill-eval-report.md 或 evaluate/local-transcript-skill-eval-report.zh-CN.md 中支撑本文判断的核心结果发生变化。

建议按季度复查一次；如果 local-transcript 的 backend 默认策略、中文清洗链路或缓存机制有明显重构，则应立即复查。

10. 相关阅读¶

• skills/local-transcript/SKILL.md
• skills/local-transcript/scripts/local_transcript.py
• skills/local-transcript/scripts/zh_replacements.json
• evaluate/local-transcript-skill-eval-report.md
• evaluate/local-transcript-skill-eval-report.zh-CN.md