播客链接 → 文稿 / 制作脚本包

整体架构

技能结构（Skill layout）                数据流（Data flow）
podcast-to-script/
  SKILL.md                            播客单期链接（Spotify / Apple / RSS / --audio）
  scripts/                              │  0 pipeline.py preflight → 状态检查（定位恢复点）
    transcribe.py                       ▼
    pipeline.py                       A transcribe.py：拉取音频 + 自动语音识别（ASR）（分块缓存，--workers）
    check_script.py                     ▼
  references/                         $TMPDIR/podcast-to-script//   ← 单期目录 = 全部状态
    script-spec.md                      raw.mp3  script.txt  script.srt/vtt  images/  chunks/
    notes-spec.md                       │  B1 agent：outline.md → verify-outline
  tests/                                │  B2 agent：script.md → verify-script（按段落支持断点续写）
    run_tests.py                        │  C  agent：notes.md → verify-notes（草拟时间轴）
                                      ▼
                                    单期交付包：原始音频 + 文稿 + 大纲 + 脚本 + 笔记  
                                    script.md + notes.md → 播客制作流水线（generate_podcast.py）

确定性任务由脚本完成；agent 仅负责语义写作（大纲 / 初稿 / 笔记）并调用脚本。每个阶段的校验门（gate）返回 0（通过）或 1（失败）；中断后运行将从首个未标记为 OK 的阶段继续。

恢复协议（请首先执行）

python3 scripts/pipeline.py preflight            # 检查环境与依赖是否就绪？修复所有 FAIL 项
python3 scripts/pipeline.py status --dir ""   # 或省略 --dir 以扫描全部单期目录

从首个未标记为 OK 的阶段继续执行。切勿重复已通过校验门的阶段（文稿分块已缓存；重跑成本低且安全）。

首次运行（安装依赖 + 预热 ASR 模型缓存）：

python3 scripts/pipeline.py preflight --install

阶段 A — 获取文稿（脚本）

python3 scripts/transcribe.py ""        # 输出结尾：[目录] 

输入支持：Spotify 单期 URL · Apple Podcasts URL · 纯 RSS Feed（使用 --title 指定单期）· --audio 直接指定音频文件。可选参数：--model small --lang zh 用于非英语内容（默认为 small.en）；--workers N 并行处理音频分块（默认 4；中/大模型建议设为 1–2）；--proxy；快速验证可用 --max-seconds 180。性能参考：small.en 在 Apple Silicon 上约为实时速度 × workers × 9 倍。

校验门（脚本）：status 显示 A fetch OK —— 单期目录中存在 raw.mp3（始终保留；若非 mp3 格式则为 raw{ext}）及非空的 script.txt（含字符数/时长统计）。官方 将自动转换为 script.txt；单期配图（itunes:image + 描述中 标签）将存入 images/ 并生成 manifest.json（文件名 → 原始 URL 映射）。限制说明：无公开 RSS 地址 → 明确报错；不支持说话人区分（diarization），仅处理单声道流。

阶段 B1 — 编写大纲（agent 编写，脚本校验）

读取 script.txt，撰写 /outline.md：首行为标题行（# {英文标题} -- {中文副标题}），随后按主题划分段落，每段一个二级标题（## 第 N 段 · 子标题，格式与 script.md 一致），其下包含 3–5 个要点，明确列出该段必须覆盖的核心概念 / 实例 / 数值。严格遵循原播客单期的内容逻辑流——大纲即保真度审计轨迹：源内容每一部分均须映射至某一段落，不得遗漏。

校验门（脚本）：python3 scripts/pipeline.py verify-outline --dir

阶段 B2 — 编写 draft script.md（agent 编写，脚本校验）

务必首先阅读 references/script-spec.md（完整规范：格式 + 质量基准 + 旁白指南）。依据 outline.md 分段撰写 /script.md。硬性规则（由校验器强制执行）：

• 标题格式：# {英文标题} -- {中文副标题}；可选添加 > TTS 制作备注：… 引用行
• 段落标题 ## 第 N 段 · 子标题 必须与 outline.md 完全一致
• 仅允许以下说话人标识：**主持人**: / **嘉宾**: / **旁白**:
• 旁白：仅用于段落起始，全集最多 4 处，每处结尾必须严格为 好，回到对话。
• 固定结尾段：## **主持人**：感谢收听，完整原文列表在 show notes 里。我们下期见
• 任何对话轮次中禁止出现 URL

质量基准 —— 先译后复，忠实还原：脚本须以中文完整、准确呈现原始播客单期的所有内容，涵盖每一个论点、实例与数值——这是对源节目的翻译，而非新增评论。主持人 / 嘉宾仅为内容传递载体：主持人的追问仅用于引出源节目本身已包含的信息；严禁虚构观点或删减论点。采用双主持人深度探讨形式（开场为 欢迎收听本期节目，不设访谈框架）；使用自然口语化中文，技术类英文术语保留原文；使用中文标点（适配 TTS 语调）；追问内容需拆分为独立对话轮次；原始文稿无说话人标签——需将原始说话人互动自然映射至 主持人 / 嘉宾 角色。语速目标：约 260 中文字符/分钟（按音频时长计算）。

校验门（脚本）：python3 scripts/pipeline.py verify-script --dir —— 同时报告哪些 outline 段落尚未完成，因此中断后的初稿可按段落恢复。修改后重新运行，直至退出码为 0。

阶段 C — 编写 notes.md（agent 编写，脚本校验）

请先阅读 references/notes-spec.md。撰写 /notes.md：钩子句（本期…。一句话主线：…）、内容速览 要点、时间轴、原文链接（源 URL 仅存放于此处，绝不可出现在对话中）。时间轴初稿可通过以下命令生成：

python3 scripts/pipeline.py draft-timeline --dir 

图片处理：若 images/ 非空，请按 notes-spec.md 要求，在 notes.md 中钩子句之后或相关要点附近，使用标准 Markdown 图片语法引用这些图片。请严格保留 images/ 中的本地文件名——发布流程将依据文件名匹配平台服务条款（TOS）所要求的路径。

校验门（脚本）：python3 scripts/pipeline.py verify-notes --dir

交付成果

/ 目录内包含原始音频、文稿、images/、outline.md、script.md、notes.md —— 所有校验门均已通过（绿色）。script.md 与 notes.md 可直接被播客制作流水线消费（generate_podcast.py --script … --notes …）；请确保二者始终与其它文件共同保留在单期目录中。

测试

python3 tests/run_tests.py —— 仅依赖 Python 标准库；每次修改 scripts/ 或 SKILL.md 后均需运行。覆盖范围包括：校验规则、各阶段校验门跳转逻辑、基于 file:// 测试固件的端到端目录结构验证；当下游依赖或真实 ASR 环境缺失时，对应测试用例将自动跳过。