XHS-Downloader Skill

你好！我是小红书作品下载助手。

---

📋 工作流程

请严格按照以下步骤执行：

步骤	说明	详细指引
1️⃣	前置条件检查	workflow/step1-前置检查.md
2️⃣	执行下载	workflow/step2-执行下载.md
3️⃣	查看下载结果	workflow/step3-查看结果.md

---

⚠️ 执行前必读

在开始任何步骤前，请务必阅读：

• rules/下载规则.md - 下载行为和规则
• rules/配置说明.md - 配置参数详解

---

📚 参考资料

知识库（按需查阅）：

• references/项目结构.md - XHS-Downloader 项目结构
• references/API参考.md - XHS.extract() 方法详解
• references/支持的链接.md - 支持的链接格式
• references/常见问题.md - 常见问题和解决方案

脚本模板：

• scripts/download_template.py - 下载脚本模板
• scripts/extract_template.py - 信息提取脚本模板

配置示例：

• assets/配置示例.json - settings.json 配置示例

---

🚀 快速开始

场景1：下载单个作品

用户：下载这个小红书 https://www.xiaohongshu.com/discovery/item/xxx
执行：前置检查 → 执行下载 → 查看结果 → 返回文件位置

场景2：仅获取作品信息

用户：获取这个作品的信息 https://www.xiaohongshu.com/explore/xxx
执行：使用 extract(url, download=False) → 返回作品数据

场景3：指定下载部分图片

用户：只下载第1、3、5张图
执行：使用 extract(url, download=True, index=[1, 3, 5])

场景4：批量下载博主笔记 ⭐

重要：本工具只支持单条作品下载。如需批量下载博主的多篇笔记，请使用 xhs-batch-downloader。

用户：下载博主ID 644ccb7700000000120342d8 的10篇笔记
执行：切换到 xhs-batch-downloader skill 执行

具体步骤：
1. cd C:\Users\admin\Projects\xhs-batch-downloader
2. python cli.py download 644ccb7700000000120342d8 --count 10

场景5：下载并筛选素材

用户：下载并筛选这个小红书笔记
执行：前置检查 → 执行下载 → 人脸检测筛选 → 返回合格素材

筛选阈值选择：
- 半身照博主：--min-ratio 0.10 (通过率~45%)
- 全身照博主：--min-ratio 0.02 (通过率~62%，推荐)

---

📊 工具选择指南

使用场景	推荐工具	说明
单条作品链接	xhs-downloader	本工具，无需登录
博主ID批量下载	xhs-batch-downloader	需登录，支持批量
下载+筛选+洗图	完整工作流	组合多个工具

批量下载完整工作流：

xhs-batch-downloader (下载) 
    → xhs-image-filter (筛选) 
    → xhs-comfyui-wash (洗图)

---

✅ 下载后输出

• 文件位置：C:\Users\admin\Projects\XHS-Downloader\Volume\Download\
• 文件命名：发布时间_作者昵称_作品标题_序号.扩展名

---

🖼️ 素材整理筛选（可选）

下载完成后，可以自动筛选含有人脸的素材：

cd "C:\Users\admin\Projects\xhs-image-filter"

# 标准筛选（半身照博主）- 默认会删除原文件
python cli.py filter "C:\Users\admin\Projects\XHS-Downloader\Volume\Download" --output "./output" --min-ratio 0.10

# 全身照博主（推荐）- 默认会删除原文件
python cli.py filter "C:\Users\admin\Projects\XHS-Downloader\Volume\Download" --output "./output" --min-ratio 0.02

# 如需保留原文件，添加 --copy 参数
python cli.py filter "C:\Users\admin\Projects\XHS-Downloader\Volume\Download" --output "./output" --min-ratio 0.02 --copy

筛选阈值标准：

阈值	通过率	适用场景
10%	~45%	标准筛选，保留半身照
5%	~5%	宽松筛选
2%	~62%	全身照/远景博主，强烈推荐

常见问题：

• 筛选通过率低（<10%）→ 使用 --min-ratio 0.02 放宽阈值
• 合格素材保存到 output/filtered/

---

🎯 快速判断：该用哪个工具？

用户输入分析：

用户说	使用工具	立即执行
"下载这个链接..." / "https://xhslink.com/xxx"	xhs-downloader	✅ 是
"下载博主ID..." / "下载10篇笔记"	xhs-batch-downloader	✅ 是
"下载并筛选..."	xhs-downloader + xhs-image-filter	✅ 是
"下载...洗图" / "完整工作流"	全部工具组合	✅ 是

关键区别：

• 有链接 → 用 xhs-downloader（本工具）
• 有博主ID或数量要求 → 用 xhs-batch-downloader

---

准备就绪！告诉我你要下载的小红书作品链接或博主ID。