📊 XHS Feedback — 小红书数据自动回写 Obsidian

一行命令，自动采集小红书创作者中心的全部笔记数据，匹配到本地 Obsidian 文件，写入 YAML frontmatter，并生成结构化复盘报告。

✨ 功能

• 自动采集：Playwright 自动打开创作者中心，翻页采集所有笔记的曝光、观看、CTR、互动等数据
• 智能匹配：三层匹配策略（YAML title → 正文关键词 → 日期+目录名），匹配率 >70%
• YAML 写入：匹配成功的笔记自动更新 frontmatter metrics: 字段
• 复盘报告：自动生成 Markdown 格式的表现分析报告（排行、CTR 分析、收藏率排行）
• 纯本地运行：数据不上传任何第三方，全程在你的电脑上跑

📸 效果预览

更新后的笔记 YAML：

metrics:
  impressions: 185593
  views: 41780
  cover_ctr: "23.60%"
  likes: 1937
  comments: 142
  collected: 2898
  followers: 102
  shares: 389
  avg_view_duration: "35s"
metrics_updated_at: 2026-04-05 10:06

自动生成的报告包含：

• 📈 核心数据排行（按曝光量排序）
• 🎯 封面点击率 (CTR) 分析
• ⭐ 收藏率排行（内容价值指标）
• ❌ 未匹配笔记列表

🚀 快速开始

前置要求

• macOS / Linux / Windows
• Python 3.9+
• Obsidian 笔记库（笔记需按目录组织）

1. 克隆仓库

git clone https://github.com/manwithshit/xhs-feedback.git
cd xhs-feedback

2. 安装依赖

pip install -r requirements.txt
playwright install chromium

3. 配置

cp config.example.json config.json

编辑 config.json，填入你的 Obsidian 笔记库路径：

{
  "obsidian_root": "/Users/你的用户名/ObsidianVault",
  "published_dir": "60_Published/xiaohongshu",
  "drafts_dir": "50_Temp/drafts",
  "report_dir": "40_Reference/performance"
}

说明：published_dir、drafts_dir、report_dir 是相对于 obsidian_root 的路径，按你的 vault 结构修改。

4. 运行

python3 xhs_feedback.py

首次运行会弹出浏览器要求扫码登录，之后 cookies 自动保存复用（有效期约 7-14 天）。

📖 使用方式

# 完整运行（采集 → 匹配 → 更新 → 报告）
python3 xhs_feedback.py

# 仅采集数据（不更新本地文件）
python3 xhs_feedback.py --scrape-only

# 仅用已有数据生成报告（不重新采集）
python3 xhs_feedback.py --report-only

# 无头模式（定时任务用，cookie 过期则退出）
python3 xhs_feedback.py --headless

# 指定配置文件
python3 xhs_feedback.py --config /path/to/config.json

🧩 匹配策略

脚本通过三层策略将采集到的笔记标题匹配到本地文件：

层级	方法	权重	说明
1	YAML title 精确匹配	最高 (20)	frontmatter 中的 title 字段
2	正文关键词匹配	中 (4-12)	解决发布时改标题的情况
3	日期 + 目录名匹配	兜底 (8-10)	容错 ±1 天

匹配阈值：总分 ≥ 15 才会更新（避免误匹配）。

🔧 目录结构要求

脚本假设你的 Obsidian 笔记按以下方式组织：

ObsidianVault/
├── 60_Published/xiaohongshu/     ← 已发布的笔记（每篇一个子目录）
│   ├── 260115_笔记太多整理不过来让AI帮你干/
│   │   └── index.md              ← 必须有 YAML frontmatter
│   ├── 260117_把 Gemini 塞进 Obsidian/
│   │   └── index.md
│   └── ...
├── 50_Temp/drafts/               ← 草稿（可选）
└── 40_Reference/performance/     ← 报告输出目录（自动创建）

每篇笔记的 .md 文件需要有 YAML frontmatter（--- 开头），脚本会在其中插入或更新 metrics: 块。

🔒 安全注意事项

1. config.json 不要提交到 Git — 已在 .gitignore 中排除
2. creator_cookies.json 包含你的登录态 — 绝对不要分享
3. 数据纯本地 — 脚本不会上传任何数据到第三方服务
4. stealth.min.js — 来自开源项目 puppeteer-extra-plugin-stealth（MIT License）

⚙️ 配合定时任务

macOS launchd

可以配合 launchd 定时执行（如每周日 10:00）：

python3 xhs_feedback.py --headless

Cookie 过期时会返回退出码 2，不会卡住。你可以用另一个脚本捕获退出码并发送提醒。

📋 常见问题

Q: Cookie 过期了怎么办？

A: 重新运行 python3 xhs_feedback.py（不带 --headless），会弹出浏览器让你扫码。

Q: 匹配不到本地文件？

A: 确保笔记的 .md 文件有 YAML frontmatter，且 title 字段与小红书发布标题一致。或者检查目录名是否包含发布日期前缀。

Q: 支持 Windows 吗？

A: 支持。Python 和 Playwright 都是跨平台的。只需修改 config.json 中的路径格式。

📜 License

MIT License

🙏 致谢

• Playwright — 浏览器自动化
• Obsidian — 知识管理
• puppeteer-extra-plugin-stealth — 反检测脚本