HN 播客存档

建立或维护一个可重复执行的处理流程，该流程需完成以下任务：

1. 读取 RSS 订阅源；
2. 检测新发布的剧集；
3. 下载音频文件；
4. 使用本地 Whisper 进行语音转录；
5. 为每期剧集生成一份 Markdown 格式的存档文件；
6. 更新索引文件与状态文件。

工作流程

1. 阅读 references/layout.md 文件，了解预期的存档目录结构及输出内容。
2. 以 scripts/hn_podcast_archive.py 作为主要实现脚本。
3. 运行 python3 scripts/hn_podcast_archive.py --help 查看可用参数选项。
4. 首次配置时，请确保所需二进制程序和 Python 模块均已安装就绪。
5. 如需自动化运行，请将该脚本按固定周期（例如每几小时一次）调度执行，并指定一个稳定的输出目录。

必需的运行时依赖项

脚本依赖以下环境组件：

• ffmpeg 已加入系统 PATH
• whisper 已加入系统 PATH
• Python 3.10 或更高版本
• Python 包 feedparser

若任一依赖缺失，应明确提示配置说明，而非假装流程已准备就绪并尝试执行。

推荐命令

python3 skills/hn-podcast-archive/scripts/hn_podcast_archive.py 
  --feed-url "https://example.com/podcast.rss" 
  --output-dir ./data/hn-podcast-archive 
  --whisper-model turbo

输出预期

对每个已处理的剧集，生成以下内容：

• 音频文件存于 audio/ 目录下
• 转录文本存于 transcripts/ 目录下
• Markdown 存档文件存于 episodes/ 目录下

持续更新以下共享文件：

• index.md
• state.json
• run-log.jsonl

自动化建议

建议采用 cron 或常驻任务方式触发自动化运行，例如每几小时执行一次。该脚本在单集粒度上具备幂等性：通过在 state.json 中记录已处理的 GUID 或 URL 来避免重复处理。

安全操作准则

• 切勿覆盖与当前任务无关的存档内容；
• 跳过已处理过的剧集，除非显式启用强制重处理；
• 保留原始元数据（标题、发布日期、音频 URL、GUID）；
• 若音频下载成功但转录失败，应保留原始音频文件，并在日志或状态文件中记录失败信息。

可定制化选项

常用命令行参数包括：

• --limit N：测试期间仅处理最近 N 条条目
• --force：强制重新处理已被标记为已处理的条目
• --dry-run：预览将执行的操作，不实际写入任何输出
• --whisper-model：在处理速度与转录精度之间进行权衡

打包与发布

从其所在文件夹对本技能进行打包。仅当本地验证通过且认证可用后，方可使用 ClawHub 发布。