koishi-plugin-xiaohongshu-parser-node

自用的小红书分享链接解析插件，基于 Koishi 4，支持图文 / 视频内容提取、自动解析白名单与合并转发。

功能特性

• 链接解析
  • 支持小红书多种 URL 形式
    https://www.xiaohongshu.com/explore/...
https://www.xiaohongshu.com/discovery/item/...
https://www.xiaohongshu.com/notes/...
http(s)://xhslink.com/... 等
• 内容提取
  • 标题、正文文案
  • 图集（完整图集 + 去重后的大图）
  • 视频直链及封面图
• 自动解析与合并转发
  • 手动指令 xhs 解析
  • 支持白名单会话自动解析消息中的小红书链接
  • 多链接场景可生成合并转发消息（forward）
• 安全防护
  • SSRF 防护：只允许访问指定域名，拒绝内网 / 私有地址
  • URL 长度与危险字符过滤
• 日志与调试
  • 可选的解析过程调试日志
  • QQ 卡片消息结构日志，方便排查卡片解析问题

安装

npm install koishi-plugin-xiaohongshu-parser-node
# 或
yarn add koishi-plugin-xiaohongshu-parser-node
# 或
pnpm add koishi-plugin-xiaohongshu-parser-node

在 Koishi 控制台中启用插件，或在代码里手动注册：

ctx.plugin(require('koishi-plugin-xiaohongshu-parser-node'), {
  // 配置见下文
})

配置

基础配置

export interface Config {
  // 基础配置
  allowedDomains?: string[]       // 允许解析的域名（默认: DEFAULT_ALLOWED_DOMAINS）
  userAgent?: string              // HTTP 请求使用的 User-Agent
  requestTimeout?: number         // 请求超时时间，毫秒（默认: 10000）
  maxRetries?: number             // 请求失败时的最大重试次数（默认: 3）
  customHeaders?: Record<string, string>  // 追加的自定义请求头

  // 功能配置
  enableLog?: boolean             // 启用解析过程和结果日志（默认: false）
  enableForward?: boolean         // 启用自动解析 + 合并转发（默认: false）
  maxUrlsPerMessage?: number      // 单条消息最多处理的链接数量（默认: 5）

  // 自动解析白名单
  autoParseGuilds?: string[]      // 自动解析白名单群聊（guildId 或 platform:guildId）
  autoParseUsers?: string[]       // 自动解析白名单私聊（userId 或 platform:userId）

  // 视频下载与发送
  downloadVideoAsFile?: boolean   // 尝试先下载首个视频再以文件形式发送，缓解"资源已过期"
  videoDownloadMode?: 'buffer' | 'file' | 'base64'  // 视频发送模式
}

完整配置示例

ctx.plugin(require('koishi-plugin-xiaohongshu-parser-node'), {
  // 基础配置
  allowedDomains: ['www.xiaohongshu.com', 'xiaohongshu.com', 'xhslink.com'],
  userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...',
  requestTimeout: 10000,
  maxRetries: 3,
  customHeaders: {
    'Accept-Language': 'zh-CN,zh;q=0.9'
  },

  // 功能配置
  enableLog: false,
  enableForward: true,
  maxUrlsPerMessage: 5,

  // 自动解析白名单
  // 仅这些会话会启用"自动解析消息中的小红书链接"
  autoParseGuilds: [
    '1234567890',            // 仅按 guildId 匹配
    'onebot:987654321'      // 指定平台 + guildId
  ],
  autoParseUsers: [
    '11223344',
    'onebot:55667788'
  ],

  // 视频下载与发送（可选）
  downloadVideoAsFile: false,
  videoDownloadMode: 'buffer',     // 'buffer' | 'file' | 'base64'
})

使用方法

手动指令

插件会注册 Koishi 指令：

xhs <url>

支持的选项：

• -r, --raw
  输出相对"干净"的纯文本内容（具体行为可按场景调整）
• -m, --merge
  当参数中包含多个链接时，尝试一次性解析并生成合并转发消息

示例：

• 解析单个链接：

  xhs https://www.xiaohongshu.com/explore/xxxxxxxx

• 合并转发多个链接：

  xhs https://www.xiaohongshu.com/explore/aaa \
      https://www.xiaohongshu.com/explore/bbb \
      -m

自动解析（白名单）

当同时满足以下条件时，将自动解析消息中的小红书链接：

1. enableForward = true
2. 会话在自动解析白名单中：
   • 群聊：autoParseGuilds 命中 guildId 或 platform:guildId
   • 私聊：autoParseUsers 命中 userId 或 platform:userId
3. 消息中包含至少 1 个有效的小红书链接
   （支持从文本、QQ 卡片 json/node 段中提取 jumpUrl）

行为说明：

• 单链接：直接解析并发送笔记内容
• 多链接：解析后将多条结果封装为 forward 合并转发消息
• 非白名单会话：不会自动解析任何消息，仍可使用 xhs 指令手动解析

安全特性

SSRF 防护

插件在解析 URL 前会做安全校验：

• 仅允许访问 allowedDomains 中配置的域名与子域名
• 拒绝内网/私有地址：
  • 10.x.x.x, 127.x.x.x, 169.254.x.x, 172.16-31.x.x, 192.168.x.x
  • localhost、*.local、*.internal 等主机名
• 仅允许 http / https 协议
• 限制 URL 最大长度（默认 2048 字符）

输入验证

• 去除末尾常见标点（句号、引号、括号等）
• 解码 HTML 实体，处理 QQ 卡片 / 富文本中的转义 URL
• 过滤明显无效或危险的 URL

媒体处理

图文笔记

• 尝试优先使用页面中的 JSON-LD 数据和初始状态脚本，获取完整图集
• 对图片对象进行去重，避免 infoList 预览图导致"10 图变 20 图"
• 优先选择清晰度较高的图片（按 imageScene 评分）

视频笔记

• 解析出视频直链（含多种字段与备选链接），并进行去重与 HTTPS 规范化
• 默认行为：
  • 不下载文件，直接发送直链（在部分 QQ / OneBot 实现中可能被标记为"资源已过期"）
• 当 downloadVideoAsFile = true 时：
  • 使用 ctx.http.file() 拉取首个视频
  • 根据 videoDownloadMode 采用不同的发送方式：
    • buffer：以二进制 Buffer 的方式传给 h.video（推荐默认）
    • file：写入临时文件并以 file:// 形式发送
    • base64：转换为 base64://... 段发送（OneBot 常见格式）
  • 如果下载或转换失败，会自动回退为直链发送

注意：在 Napcat QQ / OneBot 等环境下，对外链视频是否"过期"往往由 QQ / 网关控制，启用下载模式可以改善部分场景，但无法完全绕过平台限制。

日志与调试

当 enableLog = true 时：

• xhs-basic-client 会输出：
  • 请求发起 / 重试 / 重定向信息
  • 命中的 JSON-LD、note 详情、图片 / 视频数量等
• 自动解析中间件会输出：
  • 会话平台 / guildId / channelId / userId
  • QQ json / node 卡片消息的结构摘要（经简化和截断）
  • 自动解析触发的 URL 列表与最终行为

错误处理

• 网络错误：带有限次重试与指数级等待
• URL 错误：统一返回"链接无效或不在允许的域名中"等友好提示
• HTML / JSON 解析错误：记录日志并使用元标签 / 兜底策略
• 所有异常均会被捕获，避免把堆栈或敏感信息直接暴露给用户

更新日志

v0.0.22

• 重构基础解析客户端 BasicXHSClient，统一 Axios + Cheerio 实现
• 增强图集解析：
  • 解决 10 图笔记重复生成 20 图的问题
  • 基于图片唯一标识符进行去重，优化 infoList 选择策略
• 新增自动解析白名单：
  • autoParseGuilds / autoParseUsers 精确控制哪些会话自动解析
  • 非白名单会话不再做多链接兼容模式，避免刷屏
• 新增视频下载与发送模式：
  • downloadVideoAsFile + videoDownloadMode = buffer | file | base64
  • 在 OneBot / QQ 等环境下改善部分视频播放体验
• 增强 QQ 卡片支持：
  • 从 json / node 段中提取 jumpUrl，配合自动解析使用
• 安全性与健壮性：
  • 更严格的 URL 校验与 SSRF 防护
  • JSON 解析前清洗 undefined / NaN / Infinity 等非法值

v0.0.13

• 初始发布，小红书链接解析
• 支持图文 / 视频内容提取
• 支持多链接合并转发
• 内置基础 SSRF 防护与配置项

支持与反馈

• GitHub Issues：https://github.com/FHfanshu/koishi-plugin-xiaohongshu-parser-node/issues
• 欢迎提交 issue 反馈解析问题、兼容性问题或新需求

许可证

本项目使用 MIT License，详见仓库中的 LICENSE 文件。

免责声明

本插件仅供学习和个人研究使用。使用者应当：

• 遵守小红书平台的用户协议和服务条款
• 尊重内容创作者的知识产权
• 合理使用解析功能，避免对平台服务器造成过大负担
• 不得将本插件用于商业用途或恶意爬取

开发者不对因使用本插件而产生的任何法律纠纷或技术问题承担责任。使用本插件即表示您同意自行承担相关风险。

致谢

感谢以下开源项目的支持：

• Koishi - 优秀的机器人框架
• Cheerio - 快速的HTML解析器
• Axios - 强大的HTTP客户端