小红书链接解析

给 Agent 用的解析器：输入链接 → 输出结构化数据。不需要 Cookie，不需要登录，不需要任何 API Key。

0. 唯一硬约束：链接必须带 `xsec_token`

这是实测出来的唯一门槛，不是配置问题：

| 条件 | 结果 | |---|---| | 有 xsec_token + 无 Cookie | ✅ 完整解析（PC/移动 UA、explore/discovery 路径均可） | | 无 xsec_token（任何 UA / 任何路径） | ❌ 返回「你访问的页面不见了」空壳页 |

怎么判断能不能解析：不看来源，只看 URL 里有没有 xsec_token= 这一串。有就能过，没有就一定过不了。

| 链接来源 | 是否带 token | 结果 | |---|---|---| | App「分享→复制链接」的口令 | ✅ 一定带（短链跳转后） | ✅ | | 网页端从搜索/推荐流点进笔记，复制地址栏 | ✅ 通常带（xsec_source=pc_search 这类） | ✅ 已验证 | | 只有纯笔记 ID（手敲、他人转述、被截断的链接） | ❌ | ❌ 报 NO_TOKEN |

报 NO_TOKEN 时让用户重新复制一次即可，不要反复重试 —— 重试多少次都不会成功。

1. 用法

Python（3.9+，标准库，无需 pip install）

cd ~/.workbuddy/skills/xhs-link-parser/scripts
python3 xhs_resolve.py "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy"
python3 xhs_resolve.py "78 复制本条信息... https://xhslink.cn/o/xxx"       # 直接粘口令
python3 xhs_resolve.py links.txt --format md                                # 批量 / Markdown
python3 xhs_resolve.py <url> --download --out ./media                       # 顺带存图

短链域名 xhslink.com 和 xhslink.cn 都认（App 分享两种都会出）；xiaohongshu.com 带不带 www 都行。

Node（18+，内置 fetch，无需 npm install）

node xhs_resolve.mjs "<链接或口令>"
node xhs_resolve.mjs "<链接>" --md

作为模块给 Agent 调用

import { resolveLink } from './xhs_resolve.mjs';
const r = await resolveLink(userInput);
if (r.ok) { /* r.note.title / r.note.desc / r.note.stats ... */ }
else if (r.error === 'NO_TOKEN') { askUser('请用小红书 App 重新复制链接'); }

stdout 只输出机器可读结果（JSON/Markdown），日志与报错一律走 stderr —— 管道直接消费即可，不会被日志污染。

1.5 部署到扣子（Coze）

coze/ 目录里有现成产物：

coze/xhs_parse.js —— 扣子代码插件版，粘贴进 Coze IDE 即可，扁平化输出（20 个字段已按 Coze 规范声明好）
coze/安装到扣子.md —— 手把手步骤，含输入输出参数表、Bot 提示词片段、排错
coze/server.js —— 自建 HTTP 服务（Coze 云端 IP 被风控时的兜底）

两条路径：代码插件（零部署，先试）→ 不通则 HTTP 服务（请求改从你自己的服务器发出）。

2. 输出结构

{
  "ok": true,
  "note": {
    "note_id": "6a40a14e000000001101d1eb",
    "type": "normal",              // normal=图文 / video=视频
    "title": "惊！女明星剪指甲、缝袜子图 流出",
    "desc": "#范冰冰[话题]# #泰国[话题]#",
    "author": { "nickname": "P先生", "user_id": "6663...", "avatar": "https://..." },
    "publish_time": "2026-06-28 12:21",
    "ip_location": "浙江",
    "stats": { "liked": 17000, "collected": 1671, "comment": 1209, "shared": 4849 },
    "tags": ["范冰冰", "泰国"],
    "images": [
      { "index": 1, "url": "https://sns-webpic-qc.xhscdn.com/...", "width": 1440,
        "height": 1920, "is_live": true, "live_video": "https://...mp4" }
    ],
    "video": { "kind": "m3u8", "url": "https://..." },   // 图文笔记为 null
    "source_url": "https://..."
  }
}

细节：

stats 已把 1.7万 这类中文计数转成整数（17000）；分享数字取 shareCount 字段。
images[].url 已去掉 CDN 转码后缀，是原图直链。
is_live / live_video 标识 Live 实况图及其视频流。
video.kind 为 m3u8（HLS，需 ffmpeg 合并）或 mp4（直链）。

3. 错误码（Agent 据此决定下一步）

| error | 含义 | Agent 该做什么 | |---|---|---| | NO_TOKEN | 链接缺 xsec_token | 让用户重新复制一次完整链接（App 分享，或网页端点进笔记后复制地址栏）；别重试 | | NO_NOTE_ID | 抽不出笔记 ID | 让用户提供完整链接 | | EMPTY_NOTE | token 失效/空壳页 | 让用户重新复制一次 | | NO_STATE / NETWORK | 风控或网络 | 降低频率后重试一次 | | NO_LINK | 文本里没找到链接 | 让用户发链接 |

失败时输出形如 {"ok":false,"error":"NO_TOKEN","message":"...","hint":"..."}，hint 可直接转述给用户。

4. 原理速览

正则从分享口令里抽链接（自动剔除中文标点）
xhslink.com / xhslink.cn 短链跟随重定向，拿到带 token 的真实 URL
带浏览器 UA 请求 explore/{id}?xsec_token={tok}
用括号平衡法从 HTML 里抠出 window.__INITIAL_STATE__（正则 .*? 会因转义截断，必须平衡法）
多路径定位 note.noteDetailMap[id].note，多字段兜底提取

图片"无水印"不是擦除，是去掉 CDN 出图后缀 !nd_dft_xxx；视频取 originVideoKey（258 无水印版，259 是带水印版）。详见 references/实测报告与原理.md（含六组合实测数据与不可行兜底记录）。

5. 与其他技能衔接

拿到 images[].url → image-understanding 出图片 brief → copywriting + female-empathy 写稿
拿到 stats → xhs-viral-analysis 十维打分、爆款归因
标题/正文结构 → 对照 xhs-viral-logic 找可复用公式
视频直链 → video-visual-analysis 抽帧分析

6. 合规与节制

只做公开页面 HTML 读取：不逆向签名、不伪造设备指纹、不用代理池。
请求间隔 ≥1.5s，禁止并发轰炸；单 Agent 场景本就低频。
用于内容查看、竞品调研、数据留档；转载搬运、二次发布需自行取得授权，著作权归原作者。
不臆造：取不到就返回结构化错误，不返回看起来合理的假数据。

小红书链接解析

小红书链接解析

0. 唯一硬约束：链接必须带 xsec_token

1. 用法

Python（3.9+，标准库，无需 pip install）

Node（18+，内置 fetch，无需 npm install）

作为模块给 Agent 调用

1.5 部署到扣子（Coze）

2. 输出结构

3. 错误码（Agent 据此决定下一步）

4. 原理速览

5. 与其他技能衔接

6. 合规与节制

0. 唯一硬约束：链接必须带 `xsec_token`