小红书笔记内容提取器
从小红书分享链接中自动提取笔记核心信息：笔记 ID、标题、正文内容、标签。
原理: 使用移动端 User-Agent 访问分享链接，读取服务端渲染页面中 window.__INITIAL_STATE__.noteData.data.noteData 的结构化笔记数据。若页面使用旧结构，再尝试 detail-desc。
适用场景
- 用户分享了小红书链接（含 xsec_token 的分享链接），需要快速获取笔记文字内容
- 批量处理多个笔记链接，整理成结构化数据
- 配合审核工具使用，提取笔记内容进行审核
使用方式
单条提取
python3 scripts/extract_xhs_note.py "https://www.xiaohongshu.com/explore/6a7441bd000000002500048d?xsec_token=xxx&xsec_source=app_share"
# 指定输出格式
python3 scripts/extract_xhs_note.py "<url>" --format text
批量提取（推荐）
# 将链接写入文件（每行一个），同时产出终端汇总 + Excel 文件
python3 scripts/extract_xhs_note.py links.txt --batch --summary --format xlsx -o 结果.xlsx
输出格式
| 格式 | 参数 | 说明 |
|---|---|---|
| XLSX | --format xlsx |
Excel 文件，含"提取结果"和"汇总统计"两个 Sheet |
| JSON | --format json（默认） |
完整结构化数据 |
| Text | --format text |
人类可读摘要 |
| CSV | --format csv |
Tab 分隔，可粘贴到 Excel |
其他参数
| 参数 | 说明 |
|---|---|
--summary |
在终端打印 Total 汇总（成功/失败列表、失败链接及原因） |
--output / -o |
指定输出文件路径 |
--delay |
批量模式每条请求后的等待秒数，默认 2；这批 50 条样本在该间隔下全部取回正文 |
--workers |
最大并发数，默认 1；仅在站点允许且需要提高吞吐时增加，并核对成功率 |
提取字段
| 字段 | 说明 |
|---|---|
note_id |
笔记唯一标识（24位十六进制） |
title |
笔记标题（detail-desc 中第一个非标签、有意义的行） |
content |
完整笔记正文，不在 JSON、CSV 或 Excel 导出时主动截断 |
tags |
话题标签列表；先去掉页面附加的 [话题] 后缀，再去重保序 |
url |
原始链接 |
链接格式要求
使用带有效 xsec_token 的分享链接（从小红书 APP 分享 → 复制链接获得），短链接可由脚本自动跳转：
https://www.xiaohongshu.com/explore/{note_id}?xsec_token=xxx&xsec_source=app_share
https://www.xiaohongshu.com/discovery/item/{note_id}?xsec_token=xxx&xsec_source=pc_share
http://xhslink.cn/o/XXXXX （短链接，自动解析）
提取原理
移动端 HTTP GET（一次请求完成短链跳转与页面下载）→ HTML 页面 → 解析 __INITIAL_STATE__ →
├── 标题：noteData.data.noteData.title
├── 正文：noteData.data.noteData.desc，完整保留
├── 标签：合并 tagList 和正文中的 #话题，去掉 `[话题]` 类型后缀后去重保序
└── 互动：interactInfo
旧页面若没有结构化笔记数据，则回退到 `detail-desc` 和页面 meta。
产物说明
执行 --batch --summary --format xlsx 会产生两个产物：
- 终端汇总：Total 统计（总计/成功/失败），列出所有成功笔记的标题+标签，以及失败链接的具体 URL 和原因
- Excel 文件：包含两个 Sheet
- "提取结果" — 所有笔记的序号、状态、笔记ID、标题、正文、标签、原始链接、错误信息
- "汇总统计" — 总计/成功/失败/成功率 + 失败链接详情
注意事项
- 基础提取仅依赖 Python 标准库 +
curl（macOS 自带），无需安装任何依赖 - Excel 导出（
--format xlsx）需要openpyxl：pip install openpyxl - 链接必须包含有效的
xsec_token，否则页面不会渲染 detail-desc xsec_token有时效性，过期后需重新从 APP 分享获取新链接- 短链接（xhslink.cn）会自动跟随重定向解析
- 请求间隔默认 2 秒；降低间隔后应核对成功率与正文完整性
- 遇到登录页跳转会明确报错；这类响应无法从页面提取笔记内容。提高并发前后应比较成功率。
故障排除
| 问题 | 原因 | 解决方案 |
|---|---|---|
| "未找到 detail-desc" | 页面既没有结构化笔记数据，也没有旧版正文节点 | 检查链接/登录状态，必要时从 APP 重新分享 |
| 标题为空或为标签 | 笔记以 #标签开头 | 脚本已处理，取第一个有效行 |
| 短链接解析失败 | 网络或链接问题 | 手动访问短链接复制完整 URL |
回归测试
修改提取逻辑后，在本 skill 根目录运行：
python3 -m unittest discover -s tests -v
测试覆盖移动端笔记状态解析、短链跳转、登录页、完整正文导出、空标题和 [话题] 后缀去重。Excel 用例需要可选依赖 openpyxl。
