# Xhs Note Reader

> |

- **Type:** Skill
- **Install:** `agentstack add skill-teemoweng-xhs-note-reader-xhs-note-reader`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [teemoweng](https://agentstack.voostack.com/s/teemoweng)
- **Installs:** 0
- **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [teemoweng](https://github.com/teemoweng)
- **Source:** https://github.com/teemoweng/xhs-note-reader

## Install

```sh
agentstack add skill-teemoweng-xhs-note-reader-xhs-note-reader
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# xhs-note-reader

抓取小红书图文笔记（含图片本体）作为 Claude 上下文。

---

## ⚡ TL;DR — 两个固定菜单，**必须照抄，不许自由发挥**

### 第一层（用户粘了 xhs 链接但没说要干嘛）

> **📌 STOP. 你的整个回复 = 下面这个 codeblock 的内容（只替换 `` 和 ``）。
> 回复之后不要再写任何文字。不要 invoke 任何工具。不要"基于内容动态调整选项"。
> 如果你想自由发挥，把那个冲动留到用户选了 a) 之后。**

```
👀 看了一眼，这是一条小红书图文笔记，标题《》（作者：）。想让我：
a) 读一下，给你讲讲这篇在说什么
b) 抓下来整理成 .md 文档存到本地
c) 别的（告诉我）
```

### 第二层（用户选了 a 后、读完 6 段输出之后）

```
接下来想让我：
a) 要不要下载所有图片，打包到一个文件夹？
b) 抓一下评论区（用 Claude in Chrome 扩展走你浏览器的登录态拿）
c) 归档成 .md 文档存到本地（和图片放同一个文件夹）
d) 别的？
```

### 🚫 永远不要在菜单里出现的字眼

- **任何内部工具名**：xhs-note-reader、脚本、Python、抓取、capture、flow、context、上下文备用 …
- **任何第三方平台**：飞书 / Lark / Obsidian / Notion / Apple Notes / Bear / Logseq / Bear / 印象笔记 / 语雀 ……
- **任何"总结要点 / 拆解方法论 / 口头复述"** 之类的二次创作——这些是用户选了 a 之后才能聊的事

照抄上面两个 codeblock 的文案，**一字不差**。要发挥就发挥在内容理解上，不要发挥在菜单措辞上。

---

## 何时使用

- 用户消息里出现 `xiaohongshu.com/...` 或 `xhslink.com/...` 链接
- 且笔记是**图文笔记**（脚本会自动检测，遇到视频笔记直接退出并提示用户改用视频转写工具）

**触发分支**：

| 用户消息 | 行为 |
|---|---|
| 带明确动词（读/总结/翻译/作为上下文/喂给你 …）+ xhs 链接 | 直接跑脚本，跑完按用户动词执行 |
| `/xhs ` 或 `$xhs ` | 直接跑脚本，跑完报告路径让用户决定下一步 |
| 裸 xhs 链接，无动词 | **不要自动跑脚本**，做轻量 triage：从分享串里的标题/作者识别这是图文笔记，问用户想干什么 |

### 裸链接 triage —— **只能输出这 3 个固定选项，文案抄死不许改**

用户只粘了链接没说要干嘛 → **不要急着抓图**。直接照抄这个模板：

```
👀 看了一眼，这是一条小红书图文笔记，标题《》（作者：）。想让我：
a) 读一下，给你讲讲这篇在说什么
b) 抓下来整理成 .md 文档存到本地
c) 别的（告诉我）
```

a/b/c 是**预设动作**，**不许根据笔记内容动态改写**——你不需要"创造"，照抄就行。

**🚫 DON'T（这些都是真实出现过的违规）**：

| 错误输出 | 错在哪 |
|---|---|
| `a) 用 xhs-note-reader 抓下来作为上下文备用` | 暴露了内部工具名 |
| `b) 抓下来后再总结成要点 / 拆解方法论` | 擅自把 b 改成"总结要点" |
| `c) 抓下来归档到 Obsidian 或飞书文档` | 提第三方平台 |
| 出现 4 个选项（a/b/c/d 别的） | 这一层只有 3 个选项，**没有 d** |
| 选项措辞用了"作为上下文"、"flow"、"capture"、"留档备查" 等工程师味儿词 | 措辞要像跟朋友说话 |

**✅ DO**：

- **照抄模板，3 个选项一字不差**——把上面那 3 行复制过去就行
- 标题和作者从分享串里提（xhs 分享文案前面那段 `【标题 - 作者 \| 小红书】` 就是）
- **绝不**提及任何内部工具名（xhs-note-reader、脚本、Python、抓取……）
- **绝不**提及任何第三方平台（飞书 / Obsidian / Notion / Apple Notes / Bear / Logseq……）
- **绝不**自作主张把 b 改成"总结要点"或 c 改成"基于内容的追问"——那些是**用户选了 a 之后**才出现的二级菜单的事

### 用户选了以后怎么办

- 选 a) → 跑脚本 → 按完整 6 段格式输出（再进入二级 a/b/c/d 菜单）
- 选 b) → 跑脚本拿到 `note.md` + 图片 → 一起放到 `~/Downloads/xhs-/` → `open` 文件夹 → 报路径
- 选 c) → 用户会说他要干啥，按用户说的做

## 如何使用

```bash
python3 ~/.claude/skills/xhs-note-reader/scripts/xhs-fetch.py ''
```

输入可以是：
- `xhslink.com/o/...` 短链（脚本会自动跟 302）
- `xiaohongshu.com/discovery/item/?xsec_token=...` 完整链接（**`xsec_token` 必须保留**，否则鉴权失败）

成功时 stdout 第一行：

```
OK 
   note.md: /note.md
   images:  N
   stats:   👍X 💬Y
```

失败时 stderr 一行原因，退出码 ≠ 0：
- 退出码 `2` → 视频笔记，建议引导用户改用视频转写工具（本 skill 不处理视频）
- 退出码 `1` → 其他错误（鉴权失败、页面结构变了、网络等）

## 输出结构

`/`（系统临时目录，**用完即弃**；图片 CDN 链接带时间戳，几小时后会 403）：

```
note.md      # YAML frontmatter + 正文 + 图片引用 + 互动数
img_01.jpg   # 按笔记原顺序
img_02.jpg
...
raw.json     # 原始 noteDetail JSON，debug 用
```

`note.md` 里图片用 `` 相对引用——**Claude 用 Read 工具直接读每张 jpg 即可**（多模态原生，不需要 OCR）。

## 消费输出（强制流程，不可跳过）

**核心原则**：skill 跑完 ≠ 上下文加载完。你必须把 note.md 和每张图都 Read 进来，才算"读过这篇笔记"。仅看 stdout 的统计数字就回复用户 = **失败**。

跑完脚本后，**在向用户输出任何文字之前**，按顺序执行：

1. **Read `/note.md`**（1 次 Read 调用）
2. **Read 每一张 `/img_NN.jpg`**（N 次 Read 调用，**全部读完，一张都不能省**）
   - 可以在一条消息里并行发起多个 Read 调用以提速
   - Claude 是多模态的，Read 图片就是看图，不要"觉得没必要"
3. **现在**你才真正"读完了这篇笔记"，可以开始回复

### 回复格式要求（强制 6 段结构）

**目标**：让用户读完你的回复后，**不用打开原笔记也能搞懂这篇在讲什么**——这个 skill 的使命是"帮用户预读"，所以输出必须能替代笔记本身。

**固定 6 段，固定顺序，固定 emoji 锚点**（让眼睛能扫，让格式可预期）：

```
🔍 这是一篇小红书图文笔记。

📌 标题

✍️ 正文（原文）
> 

🖼️ 图里讲了什么（N 张图）
10 或者笔记本身是清单型（每张一个独立条目，如词典/工具盘点/N 个 tip），
可降级为分类聚合（厨房系/魔法系/…），每类点 2-3 个代表即可，不要全数枚举。

**核心区别**：你要写"这张图在干什么"而不是"这张图上有什么字"。
你的读者已经知道这是图文笔记了，不需要你帮他读完字——他需要你帮他**看懂结构**。>

📊 互动
👍 X　⭐ Y　💬 Z　🔁 W

💬 评论区

🧭 一句话总结

接下来想让我：
a) 要不要下载所有图片，打包到一个文件夹？
b) 抓一下评论区（用 Claude in Chrome 扩展走你浏览器的登录态拿）
c) 归档成 .md 文档存到本地（和图片放同一个文件夹）
d) 别的？
```

**硬性要求：选项只能是这 4 个，文案固定，不许扩**。a/b/c 都是预设动作，不要换成"基于内容的追问"那种动态选项。用户想延伸具体内容方向，会走 d) 自己说。

**两个固定入口的具体处理**：

### 共用的目标目录约定

`a) 下载图片` 和 `c) 归档 .md` 都落到**同一个文件夹**：

```
~/Downloads/xhs-/
```

- `` = 笔记标题（保留中文，去掉 `/`、换行、不可见字符；过长截前 30 字）
- 整个 skill 运行期间，slug 算一次就锁定，a 和 c 用同一个
- 文件夹若已存在：
  - 同笔记重复操作（a 后再 c，或反之）→ **复用同一文件夹**，不要新建 `-2`
  - 真的撞名（不同笔记同标题，少见）→ 追加 `-2`、`-3`
- **路径不要写在菜单选项的描述里**——只在动作完成后报告

### 「a) 下载所有图片」具体处理

```bash
SRC=; DST="$HOME/Downloads/xhs-"
mkdir -p "$DST" && cp "$SRC"/img_*.jpg "$DST"/
( command -v open >/dev/null && open "$DST" ) || ( command -v xdg-open >/dev/null && xdg-open "$DST" ) || true
```

> 末行那条链式命令是为了跨平台：`open` 是 macOS 原生命令，Linux 用
> `xdg-open`。两个都没有就静默跳过（用户得自己进文件夹）。所有用到"打开文件夹"
> 的地方都按这个模板写。

- 只复制 `img_*.jpg`，不带 `note.md` / `raw.json`
- **`open` 必须**——自动用 Finder 打开文件夹，不让用户自己翻
- 反馈格式：
  > ✅ 已下载 **16** 张图到 `~/Downloads/xhs-你可能不认识的Claude-Code加载词/`
  > 已用 Finder 打开。

### 「c) 归档成 .md 文档」具体处理

```bash
SRC=; DST="$HOME/Downloads/xhs-"
mkdir -p "$DST" && cp "$SRC"/note.md "$DST"/
( command -v open >/dev/null && open "$DST" ) || ( command -v xdg-open >/dev/null && xdg-open "$DST" ) || true
```

- 只复制 `note.md`（脚本生成的那份，含 YAML frontmatter + 正文 + 互动数 + 图片引用）
- 如果 `$DST` 里已经有图片（用户先选了 a 又选 c）→ `note.md` 里的 `` 相对引用**直接生效**，在 Markdown 编辑器里可以渲染
- 如果用户**只**选了 c 没下图 → `note.md` 里的图片引用会指向不存在的文件。**默认不下图**，但反馈里要提醒用户
- 反馈格式：
  > ✅ 已归档 `.md` 到 `~/Downloads/xhs-你可能不认识的Claude-Code加载词/note.md`
  > 已用 Finder 打开。
  > （如需图片一起留存，再选 a 即可）

### 「b) 抓评论区」具体处理

xhs 评论 API 需要登录态签名，无 cookie 时返回 `-101 无登录信息`。绕路是借
**Claude in Chrome MCP**（官方扩展，工具前缀 `mcp__claude-in-chrome__*`）让
Chrome 用用户自己的登录态去拿。

**步骤 0：兼容性检测（每次都先做）**

用户选 b 之前你**必须**先确认 `mcp__claude-in-chrome__*` 这族工具是否可用：

- 检查方式：用 `ToolSearch query: "claude-in-chrome"` 或直接看本会话工具列表里有没有 `mcp__claude-in-chrome__tabs_context_mcp`、`mcp__claude-in-chrome__navigate` 等
- **检测结果分支**：

  | 状态 | 行动 |
  |---|---|
  | MCP 工具已就绪 | 直接进步骤 1 |
  | 工具不存在 / 未连接 | 进入「安装引导」分支，**不要让用户摸黑** |

**「安装引导」分支文案**（用户没装 Claude in Chrome 时贴这套）：

> 这个功能需要 **Claude in Chrome** 扩展（用你浏览器的 xhs 登录态拿评论）。三步可装好：
>
> 1. 装扩展：
> 2. 在本会话跑 `/chrome`——会自动写 native messaging 配置
>    - macOS：`~/Library/Application Support/Google/Chrome/NativeMessagingHosts/`
>    - Linux：`~/.config/google-chrome/NativeMessagingHosts/`
> 3. 完全退出 Chrome 再开（macOS 是 ⌘Q；Linux `pkill chrome`）+ 重启本 Claude Code 会话（MCP 列表是启动时加载的）
>
> 前提：Claude Max 订阅（Pro 不行）；Chrome 或 Edge（Arc / Brave / WSL 不行）。
> 装完告诉我，我重新跑一遍。
>
> 装不了的话也行——评论我抓不到，但其他 6 段内容是完整的。

**步骤 1：navigate + 抓评论 DOM**

- `mcp__claude-in-chrome__navigate` 到笔记的完整 xiaohongshu.com URL（**保留 `xsec_token`**，丢了拿不到登录态内容）
- 等页面 load 完，用 `javascript_tool` 跑 DOM 查询：
  - 根评论节点选择器：`[class*="comment-item"]`（注意 class 名可能含 hash，用 `[class*="..."]` 模糊匹配）
  - 找 `查看 N 条回复` / `展开` 按钮，程序化点击展开（一般 1-3 个）
  - 再次查询，拿到全部主评 + 已展开回复
- 提取每条：作者、文本、点赞数、（如有）回复
- **预期与显示数的 gap**：xhs 显示的"评论 N 条"可能 > 实抓数，差额来自更深嵌套 / 折叠 / 被删评论。这是正常的，在反馈里坦白提一句即可

**步骤 2：在会话里给出评论摘要**

按以下结构呈现，**不要原样贴所有评论**（用户要的是信号不是噪声）：

```
💬 评论区抓取完成（共 N 条，显示数 M——差额来自更深嵌套或折叠）

主线议题：
- 

值得注意的几条：
- @用户A（👍 X）："...原话引用..."  ← 标注为什么有意思
- @用户B（👍 Y）："..."
- ...（3-5 条高赞 / 有信息量的）

未回答的关键提问：
- @用户C 问 "X"——作者没回 / 评论区也没人答

作者运营节奏（如有）：
- 作者回了 N 条，集中在 ，主要在 
```

**步骤 3：主动追问（**必做，不能跳**）——把成果固化到本地**

抓完评论后，**根据"本次会话有没有归档过 note.md"分两条路追问**：

- **情况 A：已经归档过 note.md**（用户之前从二级菜单选过 c，文件已在 `~/Downloads/xhs-/note.md`）
  > 要不要我把这份评论也追加到 `note.md` 里？路径 `~/Downloads/xhs-/note.md`。
  - 用户同意 → 在 note.md 末尾追加一段（heading：`## 评论区（N 条）` + 主线议题 + 值得注意的几条 + 未回答的提问 + 作者运营节奏，markdown 格式）→ `open` 文件夹 → 报路径

- **情况 B：还没归档过 note.md**（本次会话没选过 c）
  > 注意到你还没把这条笔记归档成 .md。要不要现在把**标题 + 正文 + 这 N 张图 + 刚抓的 M 条评论**一起整理成一个 `note.md`，跟图片一起放到 `~/Downloads/xhs-/`？
  - 用户同意 → 相当于自动跑一遍二级菜单的 a + c + 评论追加（图片 cp + note.md cp + 评论 append）→ `open` 文件夹 → 报路径
  - 这是一次"主动替用户把这次会话的成果固化下来"的升级追问，**不是询问要不要**，而是**告诉用户你打算这么做**，给他一个否决的机会

- **情况 C：用户拒绝固化** → 一句"好的，评论只留在会话里"收尾，不留尾巴

**为什么这一步必做**：评论抓取是这个 skill 里最重的操作（需要装扩展、跨进程、有失败率），结果如果只留在会话里、用户关掉就没了，太可惜。skill 应该替用户想到"这次的成果值得保留"。

**反馈格式（追加到 note.md 成功后）**：
> ✅ 评论已追加到 `~/Downloads/xhs-/note.md`（+M 条 / +X KB）
> 已用 Finder 打开。

**几条硬性规则**：

1. **正文（原文）部分必须 verbatim**——不许总结、不许改写、不许"修正"emoji 或话题 tag 的位置。这是 xhs 笔记最有特色的部分，丢了就丢了。
2. **图意部分必须独立成段**，开头隐式或显式标明"以下是图片内容的提炼"——让用户清楚边界：哪段是原作者的话、哪段是 Claude 替你看的。
3. **下一步选项里禁止出现"读完 N 张图""读取图片内容"之类**——那应该已经做完了。
4. **下一步选项 b) 是"抓评论区"，固定保留**——选了之后按本文档「b) 抓评论区」具体处理段执行：先检测 Claude in Chrome MCP 是否就绪，没装则给出 3 步安装引导；抓完之后**必须**根据"本次会话有没有归档过 note.md"主动追问要不要把成果固化到本地。
5. **一句话总结放最后**，作为"理解校验"——用户看完前 5 段后，这句话应该跟用户脑子里浮现的总结一致；不一致就回去再看。

---

❌ **错误 A**（仅 metadata，证明没读图）：
> 这是 AI小白 写的笔记，主题是 Claude Code 加载词，16 张图，👍2300。想让我 a) 读完 16 张图整理成表格 …

❌ **错误 B**（读了图但跳过论点 + 缺结构）：
> 读完了。这篇整理了 100+ 个 spinner words。几个有意思的观察：厨房系 Baking/Brewing/Simmering…程序员内梗 Wrangling/Herding… 想让我 a) 整理词表 b) 沉淀到 Obsidian …
>
> （问题：没有原文引用、没有标题段、没有评论区段、没有一句话总结）

✅ **正确**（完整 6 段）：

> 🔍 这是一篇小红书图文笔记。
>
> 📌 **标题**
> 你可能不认识的Claude Code加载词
>
> ✍️ **正文（原文）**
> > Flibbertigibbeting，Razzmatazzing，Topsy-turvying…… 在Claude Code思考时，命令行里总会出现这些奇奇怪怪的词，你有没有像我一样好奇它们是什么意思。我把这些加载词（又叫Spinner Words）汇总整理了一番，选取了一些有趣的词汇制成图表跟大家一起学习。
> >
> > 理解了它们的意思之后，你或许会感觉到，这些幽默、拟人、古灵精怪、充满想象力的词汇，把枯燥的Loading或Thinking状态，变成了某种具有极客浪漫和赛博生命感的表达。AI在这些小小的加载词中鲜活了起来。
> >
> > 在Claude团队内部，这些Spinner Words的代号是"Tengu"（天狗，日本民间传说中一种怪力神通的生物）。加载词列表维护在Claude的服务器端，仍然会不定期动态更新。如果你见到一些新的、有趣的加载词，欢迎在评论区分享。
> >
> > #ClaudeCode #VibeCoding #AI工具 #知识以一种奇怪的方式入脑 #单词 #趣味英语 #每日一词
>
> 🖼️ **图里讲了什么（16 张图）**
> 16 张卡片图按字母 A→W 排列，每张含 1 个 Loading 词 + 中文释义 + 小漫画图标 + 一句吐槽。共收录约 100+ 词。几个有意思的分组：
> - 厨房系：Baking、Brewing、Blanching、Simmering、Marinating、Mulling、Proofing、Seasoning、Stewing、Percolating——AI 在"做菜"
> - 冷幽默对照：Discombobulating（搞乱中）↔ Combobulating（整理中）——后者是前者反推造出来的伪词
> - 程序员内梗：Crunching（number crunching）、Hashing、Herding（herding cats）、Wrangling（data wrangling）
> - 玄学/魔法：Conjuring、Divining、Enchanting、Wizarding（"彻底把自己当哈利波特"）、Prestidigitating、Transmuting（炼金）
> - 生物/孵化：Hatching、Incubating、Germinating、Pollinating、Metamorphosing、Nucleating、Osmosing
> - 拟声/萌系：Booping（戳鼻子）、Honking（捣蛋鹅按喇叭）、Wibbling、Smooshing、Noodling
> - Gen Z 味儿：Vibing（感受氛围中）、Manifesting（愿望成真）、Quantumizing（遇事不决量子力学）
> - 封面那个让作者起念头的词是 Hullaballooing（喧嚷中）
>
> 📊 **互动**
> 👍 2300　⭐ 1809　💬 119　🔁 989（收藏率和转发率都偏高，是典型的"工具类干货"传播曲线）
>
> 💬 **评论区**
> 暂未抓取（需登录态）。119 条评论。
>
> 🧭 **一句话总结**
> 一篇把 Claude Code 那些奇怪 loading 词（团队代号 Tengu）整理出来配中文释义的"工具类干货"笔记，作者的 take 是：这些词让 AI 的等待时间变得有"赛博生命感"。
>
> **接下来想让我**：
> a) 要不要下载所有图片，打包到一个文件夹？
> b) 抓一下评论区（用 Claude in Chrome 扩展走你浏览器的登录态拿）
> c) 整理成完整词表 markdown 表格（含字母序和主题分类两套）
> d) 别的？

## 限制

- ❌ **不支持视频笔记**（type=video 直接退出，引导用户改用视频转写工具）
- ❌ **不抓评论正文**（评论 API 需要登录态签名，无登录返回 -101）。但评论**数量**有，作为 metadata 在 frontmatter 里
- ⚠️ **图片 CDN 链接时效约几小时**——超时后回到 tmpdir 重新读图会 403。所以默认放系统临时目录，需要长期保留请让用户手动 `cp` 出去
- ⚠️ **`xsec_token` 是鉴权参数**，从分享口令里粘 URL 时务必保留全串

## 关于作者字段

`note.md` frontmatter 里的 `author` 是发帖账号（来自 `user.nickname`）。图片水印里的署名可能是另一个名字（原创插画师/工作室等）——遇到水印和 frontmatter 名字对不上，**以 frontmatter 为准**，那是平台数据；水印只是图片内的文字。

## 测试

skill 没有内置测试样本——xhs 分享链接里的 `xsec_token` 有时效，硬编码的 URL
过段时间就会失效。要验证 skill 可用，自己随便找一条小红书图文笔记，复制分享
口令里完整的链接（含 `xsec_token`）丢给 Claude Code 即可。

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [teemoweng](https://github.com/teemoweng)
- **Source:** [teemoweng/xhs-note-reader](https://github.com/teemoweng/xhs-note-reader)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-teemoweng-xhs-note-reader-xhs-note-reader
- Seller: https://agentstack.voostack.com/s/teemoweng
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.