xhs-dl — 小红书单篇下载

给一个小红书链接，出一张资源卡片。单篇、极简、完全自包含（本地 ASR 转写 + 本地 OCR，双通道互补）。

快速使用（Skill 自包含，无需外部项目）

本 Skill 完全自包含：代码在 scripts/，模型和环境在首次使用时由 setup.py 自动下载+建立。不依赖任何外部硬盘/项目目录。

cd ~/.exflower/skills/xhs-dl
python3 scripts/xhs.py "<小红书链接>"       # Mac / Linux
python  scripts/xhs.py "<小红书链接>"       # Windows
python3 scripts/xhs.py <链接1> <链接2>     # 可多传几个

输出（在 skill 根下）：

• out/<note_id>.md 资源卡片（核心产物）
• out/<note_id>/ 图文原图（仅图文笔记）

首次运行 xhs.py 会自动引导：当前 Python 无 sherpa_onnx → 用 skill 根下 .venv 重执行 → .venv 缺失时提示跑 scripts/setup.py。

首次环境搭建（唯一前置，必须执行一次）

Skill 不自带模型/环境（保持轻量可分发），新机器/新环境首次使用必须先跑：

python3 scripts/setup.py        # Mac / Linux
python scripts/setup.py         # Windows
# 做什么: ① 建 .venv + 装依赖（2-3 分钟）
#         ② 下载 ASR 模型 paraformer-bilingual 224MB（国内走 hf-mirror，1-5 分钟）
#         ③ 验证环境就绪

• 一套脚本双平台：setup.py 是 Python 写的跨平台安装脚本（替代 bash），Mac/Windows 同一套代码
• 依赖按平台自动选择：Mac 装 ocrmac（Vision 框架）/ Windows 装 winrt-Windows.Media.Ocr（系统级 OCR）
• .venv 绑定 CPU 架构：换机器/换架构重跑 setup.py（模型和代码通用）
• 检查系统 python3 是否支持 venv：python3 -m venv --help；不行就装完整版（Mac: brew install python@3.11 / Windows: python.org）
• 分发时不带 models/ 和 .venv/（体积大），接收方跑一次 setup.py 即完整可用

三类内容的处理策略（自动分流）

视频全程零落盘（ffmpeg -vn 只拉音频流；抽帧图片用完即删）。

执行要点（为什么这么做）

1. 链接解析：短链 xhslink.cn 用 curl -sL 跟跳转拿真实 URL；note_id 从 /(?:explore|discovery/item)/([0-9a-f]{20,}) 提取
2. 视频路径：yt-dlp --skip-download --dump-json 拿元数据+CDN 直链（xsec_token 有则带，无也能跑）。直链有时效性（几小时），拿到立刻拉音频
3. 图文路径：yt-dlp 对图文会报 "No video formats found"（stdout 空）——这是正常的，自动切页面解析：抓 HTML → 括号配对截取 __INITIAL_STATE__ → yt-dlp 的 js_to_json 处理（页面含 undefined 等非标准 JS）→ 提取 title/desc/tagList/imageList/user
4. 转写：sherpa_onnx OfflineRecognizer.from_paraformer，音频要 16k 单声道 wav、采样 float32 归一化（int16 会乱码）；短音频/纯音乐偶发 ONNX 报错——正常，自动走 OCR 兜底
5. 画面 OCR（重要，双通道核心）：有口播的视频也抽帧 OCR（首帧 + 每 15s 一帧），因为生僻工具名/项目名 ASR 必错（"Tapestry"→"tap scturb o"、"OpenViking"→"open working"），而画面里的 GitHub 仓库页是白纸黑字的权威拼写，还能白捡 star 数/本周增长/作者/语言/项目描述等元数据。实测 183s 周榜视频 14 帧全命中，工具名 100% 正确
6. OCR 纠错：ocrmac（macOS Vision 框架）还能纠正标题拼写错误（实测 "Fireclawl"→"Firecrawl"）

已知坑（真实实测，详见 references/已知坑.md）

• 图文笔记走页面解析而不是 yt-dlp（yt-dlp 对图文报错是正常的）
• __INITIAL_STATE__ 必须括号配对截取（贪婪正则吞后续 JS）
• 原图下载必须带 Referer
• ocrmac 必须装进 .venv（xhs.py 在 .venv 里跑，装系统 Python 会静默返回空）
• 生僻工具名 ASR 必错，别指望换模型解决——用画面 OCR 兜底（见 references/模型选型.md 的最终结论）
• 模型选型结论：paraformer-bilingual 是唯一主模型（详见 references/模型选型.md）

输出卡片格式

固定模板（ALWAYS）：

# 📌 <标题>
- **类型**: 🎬 视频 / 🖼️ 图文
- **来源**: 小红书 (<链接>)
- **note_id**: `...`
- **博主**: <昵称> (`<ID>`)
- **时长**: <s>（视频）
- **收录**: <时间>

## 📝 正文        （图文）
## 🏷️ 标签
## 🎙️ 口播转写     （视频，> 引用）
## 📺 画面OCR      （有口播视频/无口播视频/图文有文字时均会有）
## 🖼️ 图片        （图文原图列表）
## 💡 资源线索     （英文标签识别 + 画面OCR中的项目/仓库自动提炼）

增值步骤（Agent 接手卡片后）

「资源线索」段自动识别英文标签 + 画面 OCR 里的 GitHub 仓库名（owner/repo 模式，实测可提炼 15 个）。真正价值在 AI 提炼：从正文/口播转写/OCR 里识别项目名/工具名，结合标题和标签做拼写纠错（ASR 音译错乱 → 用 OCR 权威拼写校正），输出结构化资源条目。

输出模板（ALWAYS 遵循）：

📌 资源：<正确名称>（<一句话说明>）
   类型：开源项目 / 工具 / Agent / 框架
   亮点：<从转写/OCR 提炼的 1-3 条关键信息，如 star 数、特性>
   来源：小红书 <博主>《<标题>》 → <链接>

示例（来自 GitHub 周榜实测卡片）：

📌 资源：MoneyPrinterTurbo（一句话生成短视频）
   类型：开源项目 · AI 视频
   亮点：一句话给主题自动写文案/配素材/剪成片；11.5 万 star；支持 9 种主流大模型；TikTok 一键发布
   来源：小红书 @某博主《GitHub 本周热门…》 → https://xhslink.cn/o/9EcARTChLhJ

📌 资源：OpenViking（面向 AI Agent 的上下文数据库）
   类型：开源项目 · Agent 基础设施（字节跳动/火山引擎开源）
   亮点：记忆/资源/技能挂到虚拟文件系统，agent 用 ls/tree/find 找上下文；3.2 万 star
   来源：同上

拼写纠错规则：

• ASR 转写里的音译错乱（"tap scturb o"）→ 用画面 OCR 的权威拼写（MoneyPrinterTurbo）校正
• 标题里的拼写错误（Fireclawl）→ 用 OCR/常识校正（Firecrawl）

合规边界

处理自己收藏的内容做个人学习，OK。不要高频请求（防风控）、不要批量分发他人笔记。