koishi-plugin-xhs-parser 0.1.0

package/README.md

@@ -0,0 +1,36 @@
+# koishi-plugin-xhs-parser
+
+小红书 / RedNote 链接解析插件，支持普通链接、`xhslink.com` 短链和聊天平台卡片消息中的链接提取，可选合并转发。
+
+## 功能
+
+- 解析 `https://www.xiaohongshu.com/explore/...`
+- 解析 `https://www.xiaohongshu.com/discovery/item/...`
+- 解析 `https://xhslink.com/...`，例如 `http://xhslink.com/m/AixEkyLwpfs`
+- 从 Koishi 卡片元素的 `data` 字段、转义 JSON、普通文本中提取小红书链接
+- 支持图片、视频链接、原文链接和基础互动数据返回
+- 支持 OneBot / Red 适配器的合并转发元素
+
+## 本地测试
+
+```bash
+npm install
+npm test
+npm run build
+```
+
+也可以直接跑一次真实解析：
+
+```bash
+npm run dev -- "http://xhslink.com/m/AixEkyLwpfs"
+```
+
+## Koishi 使用
+
+构建后在 Koishi 配置中加载本地插件：
+
+```yaml
+plugins:
+  /absolute/path/to/xhs-parser/lib:
+    enabled: true
+```

package/lib/index.d.ts

@@ -0,0 +1,28 @@
+import { Context, Schema } from 'koishi';
+export declare const name = "xhs-parser";
+export interface Config {
+    enabled: boolean;
+    parseMode: ('link' | 'card')[];
+    waitTip?: string | null;
+    useForward: boolean;
+    quote: boolean;
+    middleware: boolean;
+    parseLimit: number;
+    minimumInterval: number;
+    userAgent: string;
+    cookie?: string;
+    timeout: number;
+    imageFormat: 'jpeg' | 'png' | 'webp' | 'heic' | 'avif' | 'auto';
+    showImages: boolean;
+    maxImages: number;
+    maxDescLength: number;
+    descTruncateSuffix: string;
+    showVideo: boolean;
+    showStats: boolean;
+    showLink: boolean;
+    showError: boolean;
+    loggerinfo: boolean;
+}
+export declare const Config: Schema<Config>;
+export declare const usage = "\n\u53D1\u9001\u5C0F\u7EA2\u4E66\u94FE\u63A5\u6216\u5E73\u53F0\u5361\u7247\u5373\u53EF\u81EA\u52A8\u89E3\u6790\u3002\n\n\u652F\u6301\u793A\u4F8B\uFF1A\n\n- https://www.xiaohongshu.com/explore/...\n- https://www.xiaohongshu.com/discovery/item/...\n- http://xhslink.com/m/AixEkyLwpfs\n";
+export declare function apply(ctx: Context, config: Config): void;

package/lib/index.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.usage = exports.Config = exports.name = void 0;
+exports.apply = apply;
+const koishi_1 = require("koishi");
+const parser_1 = require("./parser");
+exports.name = 'xhs-parser';
+const logger = new koishi_1.Logger(exports.name);
+exports.Config = koishi_1.Schema.intersect([
+    koishi_1.Schema.object({
+        enabled: koishi_1.Schema.boolean().default(true).description('开启小红书链接/卡片解析。'),
+        parseMode: koishi_1.Schema.array(koishi_1.Schema.union([
+            koishi_1.Schema.const('link').description('普通链接'),
+            koishi_1.Schema.const('card').description('卡片消息'),
+        ])).role('checkbox').default(['link', 'card']).description('选择解析来源。'),
+        waitTip: koishi_1.Schema.union([
+            koishi_1.Schema.const(null).description('不发送提示'),
+            koishi_1.Schema.string().description('解析前发送提示语').default('正在解析小红书链接...'),
+        ]).default(null).description('等待提示。'),
+    }).description('基础设置'),
+    koishi_1.Schema.object({
+        useForward: koishi_1.Schema.boolean().default(false).description('开启合并转发。主要适用于 onebot / red 适配器。').experimental(),
+        quote: koishi_1.Schema.boolean().default(true).description('普通发送时引用原消息。'),
+        middleware: koishi_1.Schema.boolean().default(false).description('以前置中间件模式捕获消息。').experimental(),
+        parseLimit: koishi_1.Schema.number().min(1).max(10).step(1).default(3).description('单条消息最多解析的链接数量。'),
+        minimumInterval: koishi_1.Schema.number().min(0).max(3600).step(1).default(180).description('同频道同链接去重间隔，单位秒。0 表示不去重。'),
+    }).description('发送设置'),
+    koishi_1.Schema.object({
+        imageFormat: koishi_1.Schema.union([
+            koishi_1.Schema.const('jpeg').description('jpeg'),
+            koishi_1.Schema.const('png').description('png'),
+            koishi_1.Schema.const('webp').description('webp'),
+            koishi_1.Schema.const('heic').description('heic'),
+            koishi_1.Schema.const('avif').description('avif'),
+            koishi_1.Schema.const('auto').description('原图格式'),
+        ]).default('jpeg').description('图片返回格式。'),
+        showImages: koishi_1.Schema.boolean().default(true).description('返回图片。'),
+        maxImages: koishi_1.Schema.number().min(0).max(18).step(1).default(9).description('单个笔记最多发送图片数。'),
+        maxDescLength: koishi_1.Schema.number().min(0).max(2000).step(10).default(160).description('描述最大字数。设为 0 时不展示描述。'),
+        descTruncateSuffix: koishi_1.Schema.string().default('...(已截断)').description('描述超出最大字数时追加的截断标志。'),
+        showVideo: koishi_1.Schema.boolean().default(true).description('返回视频元素。'),
+        showStats: koishi_1.Schema.boolean().default(true).description('展示点赞、收藏、评论、分享数据。'),
+        showLink: koishi_1.Schema.boolean().default(true).description('展示原文链接。'),
+    }).description('内容设置'),
+    koishi_1.Schema.object({
+        userAgent: koishi_1.Schema.string().default('Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36 Edg/143.0.0.0').description('请求小红书页面时使用的 User-Agent。'),
+        cookie: koishi_1.Schema.string().role('textarea').default('').description('可选 Cookie。遇到风控或无法读取页面数据时可填写。'),
+        timeout: koishi_1.Schema.number().min(3).max(60).step(1).default(15).description('请求超时时间，单位秒。'),
+        showError: koishi_1.Schema.boolean().default(false).description('解析失败时向聊天发送错误提示。'),
+        loggerinfo: koishi_1.Schema.boolean().default(false).description('输出调试日志。').experimental(),
+    }).description('网络与调试'),
+]);
+exports.usage = `
+发送小红书链接或平台卡片即可自动解析。
+
+支持示例：
+
+- https://www.xiaohongshu.com/explore/...
+- https://www.xiaohongshu.com/discovery/item/...
+- http://xhslink.com/m/AixEkyLwpfs
+`;
+function apply(ctx, config) {
+    if (!config.enabled)
+        return;
+    const recent = new Map();
+    ctx.middleware(async (session, next) => {
+        const content = session.content || session.stripped?.content || '';
+        const isCard = /^<\w+\s/i.test(content) || content.includes('data=');
+        if (isCard && !config.parseMode.includes('card'))
+            return next();
+        if (!isCard && !config.parseMode.includes('link'))
+            return next();
+        const links = (0, parser_1.extractXhsLinks)(content).slice(0, config.parseLimit);
+        if (!links.length)
+            return next();
+        const targets = links.filter((link) => shouldProcess(recent, session.channelId || session.guildId || 'private', link, config.minimumInterval));
+        if (!targets.length)
+            return next();
+        handleLinks(session, targets, config).catch((error) => {
+            logger.warn(error);
+        });
+        return next();
+    }, config.middleware);
+}
+async function handleLinks(session, links, config) {
+    let waitTipMessageId;
+    if (config.waitTip) {
+        const result = await session.send(`${koishi_1.h.quote(session.messageId)}${config.waitTip}`);
+        waitTipMessageId = Array.isArray(result) ? result[0] : result;
+    }
+    try {
+        const allMessages = [];
+        for (const link of links) {
+            if (config.loggerinfo)
+                logger.info(`parse ${link}`);
+            const note = await (0, parser_1.fetchXhsNote)(link, config);
+            allMessages.push(...(0, parser_1.buildXhsMessages)(note, config, session));
+        }
+        if (!allMessages.length)
+            return;
+        if (config.useForward && (session.platform === 'onebot' || session.platform === 'red')) {
+            await session.send((0, koishi_1.h)('figure', { children: allMessages }));
+            return;
+        }
+        if (config.quote) {
+            await session.send((0, koishi_1.h)('message', koishi_1.h.quote(session.messageId), allMessages[0].children));
+            for (const message of allMessages.slice(1))
+                await session.send(message);
+            return;
+        }
+        for (const message of allMessages)
+            await session.send(message);
+    }
+    catch (error) {
+        logger.warn(error);
+        if (config.showError)
+            await session.send(`小红书解析失败：${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        if (waitTipMessageId) {
+            await session.bot?.deleteMessage?.(session.channelId, waitTipMessageId).catch?.(() => undefined);
+        }
+    }
+}
+function shouldProcess(recent, channelId, link, seconds) {
+    if (seconds <= 0)
+        return true;
+    const key = `${channelId}:${link}`;
+    const now = Date.now();
+    const last = recent.get(key);
+    if (last && now - last < seconds * 1000)
+        return false;
+    recent.set(key, now);
+    return true;
+}

package/lib/parser.d.ts

@@ -0,0 +1,40 @@
+import { h } from 'koishi';
+export interface XhsConfigLike {
+    userAgent: string;
+    timeout: number;
+    imageFormat: 'jpeg' | 'png' | 'webp' | 'heic' | 'avif' | 'auto';
+    showVideo: boolean;
+    showImages: boolean;
+    maxImages: number;
+    maxDescLength: number;
+    descTruncateSuffix: string;
+    showStats: boolean;
+    showLink: boolean;
+    cookie?: string;
+}
+export interface XhsNote {
+    id: string;
+    url: string;
+    title: string;
+    desc: string;
+    type: 'video' | 'normal' | 'unknown';
+    authorName: string;
+    authorId: string;
+    likedCount?: string | number;
+    collectedCount?: string | number;
+    commentCount?: string | number;
+    shareCount?: string | number;
+    imageUrls: string[];
+    videoUrls: string[];
+}
+export declare function extractXhsLinks(content: string): string[];
+export declare function resolveXhsLink(rawUrl: string, config: XhsConfigLike): Promise<string>;
+export declare function fetchXhsNote(rawUrl: string, config: XhsConfigLike): Promise<XhsNote>;
+export declare function buildXhsMessages(note: XhsNote, config: XhsConfigLike, session?: {
+    userId?: string;
+    username?: string;
+    author?: {
+        nickname?: string;
+    };
+}): h[];
+export declare function extractInitialStateNote(html: string): any | null;

package/lib/parser.js

@@ -0,0 +1,317 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractXhsLinks = extractXhsLinks;
+exports.resolveXhsLink = resolveXhsLink;
+exports.fetchXhsNote = fetchXhsNote;
+exports.buildXhsMessages = buildXhsMessages;
+exports.extractInitialStateNote = extractInitialStateNote;
+const koishi_1 = require("koishi");
+const URL_BOUNDARY = '[^\\s"\'<>\\\\^`{|}，。；！？、【】《》]+';
+const LINK_PATTERNS = [
+    new RegExp(`https?://www\\.xiaohongshu\\.com/explore/${URL_BOUNDARY}`, 'gi'),
+    new RegExp(`https?://www\\.xiaohongshu\\.com/discovery/item/${URL_BOUNDARY}`, 'gi'),
+    new RegExp(`https?://xhslink\\.com/${URL_BOUNDARY}`, 'gi'),
+    new RegExp(`http://xhslink\\.com/${URL_BOUNDARY}`, 'gi'),
+];
+const DEFAULT_HEADERS = {
+    accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8',
+    referer: 'https://www.xiaohongshu.com/explore',
+};
+function extractXhsLinks(content) {
+    const candidates = expandTextCandidates(content);
+    const links = [];
+    for (const candidate of candidates) {
+        const normalized = normalizeText(candidate);
+        for (const pattern of LINK_PATTERNS) {
+            pattern.lastIndex = 0;
+            let match;
+            while ((match = pattern.exec(normalized))) {
+                links.push(cleanUrl(match[0]));
+            }
+        }
+    }
+    return [...new Set(links)];
+}
+async function resolveXhsLink(rawUrl, config) {
+    const url = ensureProtocol(rawUrl);
+    if (!/xhslink\.com/i.test(url))
+        return url;
+    const response = await fetchWithTimeout(url, config, { redirect: 'manual' });
+    const location = response.headers.get('location');
+    if (location)
+        return new URL(location, url).toString();
+    if (response.status >= 300 && response.status < 400)
+        return url;
+    const followed = await fetchWithTimeout(url, config, { redirect: 'follow' });
+    return followed.url || url;
+}
+async function fetchXhsNote(rawUrl, config) {
+    const url = await resolveXhsLink(rawUrl, config);
+    const html = await fetchText(url, config);
+    const data = extractInitialStateNote(html);
+    if (!data) {
+        throw new Error('未能从页面中读取小红书笔记数据。可能需要 Cookie，或链接已失效。');
+    }
+    return buildNote(data, url, config);
+}
+function buildXhsMessages(note, config, session) {
+    const messages = [];
+    const text = formatNoteText(note, config);
+    messages.push((0, koishi_1.h)('message', {
+        userId: session?.userId,
+        nickname: session?.author?.nickname || session?.username,
+    }, koishi_1.h.text(text)));
+    if (config.showImages) {
+        for (const imageUrl of note.imageUrls.slice(0, config.maxImages)) {
+            messages.push((0, koishi_1.h)('message', {
+                userId: session?.userId,
+                nickname: session?.author?.nickname || session?.username,
+            }, koishi_1.h.image(imageUrl)));
+        }
+    }
+    if (config.showVideo) {
+        for (const videoUrl of note.videoUrls.slice(0, 1)) {
+            messages.push((0, koishi_1.h)('message', {
+                userId: session?.userId,
+                nickname: session?.author?.nickname || session?.username,
+            }, koishi_1.h.video(videoUrl)));
+        }
+    }
+    return messages;
+}
+function extractInitialStateNote(html) {
+    const scripts = [...html.matchAll(/<script[^>]*>([\s\S]*?)<\/script>/gi)]
+        .map((match) => match[1].trim())
+        .reverse();
+    const script = scripts.find((item) => item.startsWith('window.__INITIAL_STATE__='));
+    if (!script)
+        return null;
+    const payload = script
+        .replace(/^window\.__INITIAL_STATE__=/, '')
+        .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, '');
+    const state = parseLooseObject(payload);
+    return deepGet(state, ['noteData', 'data', 'noteData'])
+        || getFirstNoteFromDetailMap(deepGet(state, ['note', 'noteDetailMap']))
+        || null;
+}
+function expandTextCandidates(content) {
+    const values = new Set([content]);
+    try {
+        for (const element of koishi_1.h.parse(content))
+            collectElementText(element, values);
+    }
+    catch {
+        // Some adapters deliver partial XML snippets; regex extraction below still handles them.
+    }
+    for (const match of content.matchAll(/\bdata=(?:"([^"]*)"|'([^']*)')/gi)) {
+        values.add(match[1] || match[2] || '');
+    }
+    for (const value of [...values]) {
+        const decoded = decodeHtmlEntities(value);
+        values.add(decoded);
+        maybeCollectJsonValues(decoded, values);
+    }
+    return [...values];
+}
+function collectElementText(element, values) {
+    if (typeof element === 'string') {
+        values.add(element);
+        return;
+    }
+    for (const value of Object.values(element.attrs || {})) {
+        if (typeof value === 'string')
+            values.add(value);
+    }
+    for (const child of element.children || []) {
+        collectElementText(child, values);
+    }
+}
+function maybeCollectJsonValues(text, values) {
+    try {
+        const json = JSON.parse(text);
+        walkJson(json, values);
+    }
+    catch {
+        const unescaped = text.replace(/\\"/g, '"').replace(/\\\//g, '/');
+        if (unescaped !== text)
+            values.add(unescaped);
+    }
+}
+function walkJson(value, values) {
+    if (typeof value === 'string') {
+        values.add(value);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            walkJson(item, values);
+        return;
+    }
+    if (value && typeof value === 'object') {
+        for (const item of Object.values(value))
+            walkJson(item, values);
+    }
+}
+function normalizeText(text) {
+    let value = decodeHtmlEntities(text).replace(/\\\//g, '/');
+    try {
+        value = decodeURIComponent(value);
+    }
+    catch {
+        // Keep the original if it is only partly percent-encoded.
+    }
+    return value;
+}
+function decodeHtmlEntities(text) {
+    return text
+        .replace(/&quot;/g, '"')
+        .replace(/&#34;/g, '"')
+        .replace(/&#x22;/gi, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&#39;/g, "'")
+        .replace(/&#x27;/gi, "'")
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>');
+}
+function cleanUrl(url) {
+    return ensureProtocol(url)
+        .replace(/[),，。；;！？!]+$/g, '')
+        .replace(/&amp;/g, '&');
+}
+function ensureProtocol(url) {
+    return /^https?:\/\//i.test(url) ? url : `https://${url}`;
+}
+async function fetchText(url, config) {
+    const response = await fetchWithTimeout(url, config, { redirect: 'follow' });
+    if (!response.ok)
+        throw new Error(`请求小红书页面失败：HTTP ${response.status}`);
+    return response.text();
+}
+async function fetchWithTimeout(url, config, init) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), config.timeout * 1000);
+    try {
+        return await fetch(url, {
+            ...init,
+            signal: controller.signal,
+            headers: {
+                ...DEFAULT_HEADERS,
+                'user-agent': config.userAgent,
+                ...(config.cookie ? { cookie: config.cookie } : {}),
+                ...(init.headers || {}),
+            },
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function parseLooseObject(payload) {
+    return JSON.parse(payload);
+}
+function getFirstNoteFromDetailMap(map) {
+    if (!map || typeof map !== 'object')
+        return null;
+    const first = Object.values(map)[0];
+    return first?.note || null;
+}
+function buildNote(data, url, config) {
+    const id = get(data, 'noteId') || extractIdFromUrl(url);
+    const type = normalizeType(get(data, 'type'));
+    return {
+        id,
+        url: id ? `https://www.xiaohongshu.com/explore/${id}` : url,
+        title: get(data, 'title') || '小红书笔记',
+        desc: get(data, 'desc') || '',
+        type,
+        authorName: get(data, 'user.nickname') || get(data, 'user.nickName') || '未知作者',
+        authorId: get(data, 'user.userId') || '',
+        likedCount: get(data, 'interactInfo.likedCount'),
+        collectedCount: get(data, 'interactInfo.collectedCount'),
+        commentCount: get(data, 'interactInfo.commentCount'),
+        shareCount: get(data, 'interactInfo.shareCount'),
+        imageUrls: extractImageUrls(data, config.imageFormat),
+        videoUrls: extractVideoUrls(data),
+    };
+}
+function formatNoteText(note, config) {
+    const lines = [
+        `小红书：${note.title}`,
+        `作者：${note.authorName}`,
+    ];
+    if (note.desc && config.maxDescLength > 0) {
+        lines.push(trimText(note.desc, config.maxDescLength, config.descTruncateSuffix));
+    }
+    if (config.showStats) {
+        lines.push(`点赞：${displayCount(note.likedCount)}  收藏：${displayCount(note.collectedCount)}  评论：${displayCount(note.commentCount)}  分享：${displayCount(note.shareCount)}`);
+    }
+    if (config.showLink)
+        lines.push(note.url);
+    return lines.join('\n');
+}
+function extractImageUrls(data, format) {
+    const images = Array.isArray(data?.imageList) ? data.imageList : [];
+    const urls = [];
+    for (const image of images) {
+        const source = image?.urlDefault || image?.url;
+        if (!source || typeof source !== 'string')
+            continue;
+        const token = extractImageToken(source);
+        if (!token)
+            continue;
+        urls.push(format === 'auto'
+            ? `https://sns-img-bd.xhscdn.com/${token}`
+            : `https://ci.xiaohongshu.com/${token}?imageView2/format/${format}`);
+    }
+    return [...new Set(urls)];
+}
+function extractImageToken(url) {
+    try {
+        const parsed = new URL(url.replace(/\\u002F/g, '/'));
+        return parsed.pathname.split('/').slice(3).join('/').split('!')[0];
+    }
+    catch {
+        return url.split('/').slice(5).join('/').split('!')[0];
+    }
+}
+function extractVideoUrls(data) {
+    const originVideoKey = get(data, 'video.consumer.originVideoKey');
+    if (originVideoKey)
+        return [`https://sns-video-bd.xhscdn.com/${originVideoKey}`];
+    const streams = [
+        ...(get(data, 'video.media.stream.h265') || []),
+        ...(get(data, 'video.media.stream.h264') || []),
+    ].filter(Boolean);
+    streams.sort((a, b) => (a.height || 0) - (b.height || 0));
+    const best = streams[streams.length - 1];
+    return best?.backupUrls?.[0] ? [best.backupUrls[0]] : best?.masterUrl ? [best.masterUrl] : [];
+}
+function normalizeType(type) {
+    if (type === 'video')
+        return 'video';
+    if (type === 'normal')
+        return 'normal';
+    return 'unknown';
+}
+function get(source, path) {
+    return deepGet(source, path.split('.'));
+}
+function deepGet(source, path) {
+    let cursor = source;
+    for (const key of path) {
+        if (cursor == null)
+            return undefined;
+        cursor = cursor[key];
+    }
+    return cursor;
+}
+function extractIdFromUrl(url) {
+    return url.match(/\/(?:explore|item)\/([^/?#]+)/)?.[1] || '';
+}
+function trimText(text, maxLength, suffix) {
+    return text.length > maxLength ? `${text.slice(0, maxLength)}${suffix}` : text;
+}
+function displayCount(value) {
+    return value == null || value === '' ? '-' : String(value);
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "koishi-plugin-xhs-parser",
+  "version": "0.1.0",
+  "description": "Parse Xiaohongshu links and cards for Koishi.",
+  "main": "lib/index.js",
+  "typings": "lib/index.d.ts",
+  "files": [
+    "lib",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "dev": "tsx scripts/local-test.ts"
+  },
+  "keywords": [
+    "chatbot",
+    "koishi",
+    "plugin",
+    "xiaohongshu",
+    "xhs",
+    "rednote"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "koishi": "^4.16.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.10",
+    "koishi": "^4.18.8",
+    "tsx": "^4.20.3",
+    "typescript": "^5.5.4",
+    "vitest": "^1.6.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,164 @@
+import { Context, Logger, Schema, h } from 'koishi'
+import { buildXhsMessages, extractXhsLinks, fetchXhsNote } from './parser'
+
+export const name = 'xhs-parser'
+
+const logger = new Logger(name)
+
+export interface Config {
+  enabled: boolean
+  parseMode: ('link' | 'card')[]
+  waitTip?: string | null
+  useForward: boolean
+  quote: boolean
+  middleware: boolean
+  parseLimit: number
+  minimumInterval: number
+  userAgent: string
+  cookie?: string
+  timeout: number
+  imageFormat: 'jpeg' | 'png' | 'webp' | 'heic' | 'avif' | 'auto'
+  showImages: boolean
+  maxImages: number
+  maxDescLength: number
+  descTruncateSuffix: string
+  showVideo: boolean
+  showStats: boolean
+  showLink: boolean
+  showError: boolean
+  loggerinfo: boolean
+}
+
+export const Config: Schema<Config> = Schema.intersect([
+  Schema.object({
+    enabled: Schema.boolean().default(true).description('开启小红书链接/卡片解析。'),
+    parseMode: Schema.array(Schema.union([
+      Schema.const('link').description('普通链接'),
+      Schema.const('card').description('卡片消息'),
+    ])).role('checkbox').default(['link', 'card']).description('选择解析来源。'),
+    waitTip: Schema.union([
+      Schema.const(null).description('不发送提示'),
+      Schema.string().description('解析前发送提示语').default('正在解析小红书链接...'),
+    ]).default(null).description('等待提示。'),
+  }).description('基础设置'),
+  Schema.object({
+    useForward: Schema.boolean().default(false).description('开启合并转发。主要适用于 onebot / red 适配器。').experimental(),
+    quote: Schema.boolean().default(true).description('普通发送时引用原消息。'),
+    middleware: Schema.boolean().default(false).description('以前置中间件模式捕获消息。').experimental(),
+    parseLimit: Schema.number().min(1).max(10).step(1).default(3).description('单条消息最多解析的链接数量。'),
+    minimumInterval: Schema.number().min(0).max(3600).step(1).default(180).description('同频道同链接去重间隔，单位秒。0 表示不去重。'),
+  }).description('发送设置'),
+  Schema.object({
+    imageFormat: Schema.union([
+      Schema.const('jpeg').description('jpeg'),
+      Schema.const('png').description('png'),
+      Schema.const('webp').description('webp'),
+      Schema.const('heic').description('heic'),
+      Schema.const('avif').description('avif'),
+      Schema.const('auto').description('原图格式'),
+    ]).default('jpeg').description('图片返回格式。'),
+    showImages: Schema.boolean().default(true).description('返回图片。'),
+    maxImages: Schema.number().min(0).max(18).step(1).default(9).description('单个笔记最多发送图片数。'),
+    maxDescLength: Schema.number().min(0).max(2000).step(10).default(160).description('描述最大字数。设为 0 时不展示描述。'),
+    descTruncateSuffix: Schema.string().default('...(已截断)').description('描述超出最大字数时追加的截断标志。'),
+    showVideo: Schema.boolean().default(true).description('返回视频元素。'),
+    showStats: Schema.boolean().default(true).description('展示点赞、收藏、评论、分享数据。'),
+    showLink: Schema.boolean().default(true).description('展示原文链接。'),
+  }).description('内容设置'),
+  Schema.object({
+    userAgent: Schema.string().default('Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36 Edg/143.0.0.0').description('请求小红书页面时使用的 User-Agent。'),
+    cookie: Schema.string().role('textarea').default('').description('可选 Cookie。遇到风控或无法读取页面数据时可填写。'),
+    timeout: Schema.number().min(3).max(60).step(1).default(15).description('请求超时时间，单位秒。'),
+    showError: Schema.boolean().default(false).description('解析失败时向聊天发送错误提示。'),
+    loggerinfo: Schema.boolean().default(false).description('输出调试日志。').experimental(),
+  }).description('网络与调试'),
+])
+
+export const usage = `
+发送小红书链接或平台卡片即可自动解析。
+
+支持示例：
+
+- https://www.xiaohongshu.com/explore/...
+- https://www.xiaohongshu.com/discovery/item/...
+- http://xhslink.com/m/AixEkyLwpfs
+`
+
+export function apply(ctx: Context, config: Config) {
+  if (!config.enabled) return
+
+  const recent = new Map<string, number>()
+
+  ctx.middleware(async (session, next) => {
+    const content = session.content || session.stripped?.content || ''
+    const isCard = /^<\w+\s/i.test(content) || content.includes('data=')
+
+    if (isCard && !config.parseMode.includes('card')) return next()
+    if (!isCard && !config.parseMode.includes('link')) return next()
+
+    const links = extractXhsLinks(content).slice(0, config.parseLimit)
+    if (!links.length) return next()
+
+    const targets = links.filter((link) => shouldProcess(recent, session.channelId || session.guildId || 'private', link, config.minimumInterval))
+    if (!targets.length) return next()
+
+    handleLinks(session, targets, config).catch((error) => {
+      logger.warn(error)
+    })
+
+    return next()
+  }, config.middleware)
+}
+
+async function handleLinks(session: any, links: string[], config: Config) {
+  let waitTipMessageId: string | undefined
+
+  if (config.waitTip) {
+    const result = await session.send(`${h.quote(session.messageId)}${config.waitTip}`)
+    waitTipMessageId = Array.isArray(result) ? result[0] : result
+  }
+
+  try {
+    const allMessages: h[] = []
+
+    for (const link of links) {
+      if (config.loggerinfo) logger.info(`parse ${link}`)
+      const note = await fetchXhsNote(link, config)
+      allMessages.push(...buildXhsMessages(note, config, session))
+    }
+
+    if (!allMessages.length) return
+
+    if (config.useForward && (session.platform === 'onebot' || session.platform === 'red')) {
+      await session.send(h('figure', { children: allMessages }))
+      return
+    }
+
+    if (config.quote) {
+      await session.send(h('message', h.quote(session.messageId), allMessages[0].children))
+      for (const message of allMessages.slice(1)) await session.send(message)
+      return
+    }
+
+    for (const message of allMessages) await session.send(message)
+  } catch (error) {
+    logger.warn(error)
+    if (config.showError) await session.send(`小红书解析失败：${error instanceof Error ? error.message : String(error)}`)
+  } finally {
+    if (waitTipMessageId) {
+      await session.bot?.deleteMessage?.(session.channelId, waitTipMessageId).catch?.(() => undefined)
+    }
+  }
+}
+
+function shouldProcess(recent: Map<string, number>, channelId: string, link: string, seconds: number) {
+  if (seconds <= 0) return true
+
+  const key = `${channelId}:${link}`
+  const now = Date.now()
+  const last = recent.get(key)
+  if (last && now - last < seconds * 1000) return false
+
+  recent.set(key, now)
+  return true
+}

package/src/parser.ts

@@ -0,0 +1,376 @@
+import { h } from 'koishi'
+
+export interface XhsConfigLike {
+  userAgent: string
+  timeout: number
+  imageFormat: 'jpeg' | 'png' | 'webp' | 'heic' | 'avif' | 'auto'
+  showVideo: boolean
+  showImages: boolean
+  maxImages: number
+  maxDescLength: number
+  descTruncateSuffix: string
+  showStats: boolean
+  showLink: boolean
+  cookie?: string
+}
+
+export interface XhsNote {
+  id: string
+  url: string
+  title: string
+  desc: string
+  type: 'video' | 'normal' | 'unknown'
+  authorName: string
+  authorId: string
+  likedCount?: string | number
+  collectedCount?: string | number
+  commentCount?: string | number
+  shareCount?: string | number
+  imageUrls: string[]
+  videoUrls: string[]
+}
+
+const URL_BOUNDARY = '[^\\s"\'<>\\\\^`{|}，。；！？、【】《》]+'
+const LINK_PATTERNS = [
+  new RegExp(`https?://www\\.xiaohongshu\\.com/explore/${URL_BOUNDARY}`, 'gi'),
+  new RegExp(`https?://www\\.xiaohongshu\\.com/discovery/item/${URL_BOUNDARY}`, 'gi'),
+  new RegExp(`https?://xhslink\\.com/${URL_BOUNDARY}`, 'gi'),
+  new RegExp(`http://xhslink\\.com/${URL_BOUNDARY}`, 'gi'),
+]
+
+const DEFAULT_HEADERS = {
+  accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8',
+  referer: 'https://www.xiaohongshu.com/explore',
+}
+
+export function extractXhsLinks(content: string): string[] {
+  const candidates = expandTextCandidates(content)
+  const links: string[] = []
+
+  for (const candidate of candidates) {
+    const normalized = normalizeText(candidate)
+    for (const pattern of LINK_PATTERNS) {
+      pattern.lastIndex = 0
+      let match: RegExpExecArray | null
+      while ((match = pattern.exec(normalized))) {
+        links.push(cleanUrl(match[0]))
+      }
+    }
+  }
+
+  return [...new Set(links)]
+}
+
+export async function resolveXhsLink(rawUrl: string, config: XhsConfigLike): Promise<string> {
+  const url = ensureProtocol(rawUrl)
+  if (!/xhslink\.com/i.test(url)) return url
+
+  const response = await fetchWithTimeout(url, config, { redirect: 'manual' })
+  const location = response.headers.get('location')
+  if (location) return new URL(location, url).toString()
+
+  if (response.status >= 300 && response.status < 400) return url
+
+  const followed = await fetchWithTimeout(url, config, { redirect: 'follow' })
+  return followed.url || url
+}
+
+export async function fetchXhsNote(rawUrl: string, config: XhsConfigLike): Promise<XhsNote> {
+  const url = await resolveXhsLink(rawUrl, config)
+  const html = await fetchText(url, config)
+  const data = extractInitialStateNote(html)
+
+  if (!data) {
+    throw new Error('未能从页面中读取小红书笔记数据。可能需要 Cookie，或链接已失效。')
+  }
+
+  return buildNote(data, url, config)
+}
+
+export function buildXhsMessages(note: XhsNote, config: XhsConfigLike, session?: { userId?: string, username?: string, author?: { nickname?: string } }) {
+  const messages: h[] = []
+  const text = formatNoteText(note, config)
+
+  messages.push(h('message', {
+    userId: session?.userId,
+    nickname: session?.author?.nickname || session?.username,
+  }, h.text(text)))
+
+  if (config.showImages) {
+    for (const imageUrl of note.imageUrls.slice(0, config.maxImages)) {
+      messages.push(h('message', {
+        userId: session?.userId,
+        nickname: session?.author?.nickname || session?.username,
+      }, h.image(imageUrl)))
+    }
+  }
+
+  if (config.showVideo) {
+    for (const videoUrl of note.videoUrls.slice(0, 1)) {
+      messages.push(h('message', {
+        userId: session?.userId,
+        nickname: session?.author?.nickname || session?.username,
+      }, h.video(videoUrl)))
+    }
+  }
+
+  return messages
+}
+
+export function extractInitialStateNote(html: string): any | null {
+  const scripts = [...html.matchAll(/<script[^>]*>([\s\S]*?)<\/script>/gi)]
+    .map((match) => match[1].trim())
+    .reverse()
+
+  const script = scripts.find((item) => item.startsWith('window.__INITIAL_STATE__='))
+  if (!script) return null
+
+  const payload = script
+    .replace(/^window\.__INITIAL_STATE__=/, '')
+    .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, '')
+
+  const state = parseLooseObject(payload)
+  return deepGet(state, ['noteData', 'data', 'noteData'])
+    || getFirstNoteFromDetailMap(deepGet(state, ['note', 'noteDetailMap']))
+    || null
+}
+
+function expandTextCandidates(content: string): string[] {
+  const values = new Set<string>([content])
+
+  try {
+    for (const element of h.parse(content)) collectElementText(element, values)
+  } catch {
+    // Some adapters deliver partial XML snippets; regex extraction below still handles them.
+  }
+
+  for (const match of content.matchAll(/\bdata=(?:"([^"]*)"|'([^']*)')/gi)) {
+    values.add(match[1] || match[2] || '')
+  }
+
+  for (const value of [...values]) {
+    const decoded = decodeHtmlEntities(value)
+    values.add(decoded)
+    maybeCollectJsonValues(decoded, values)
+  }
+
+  return [...values]
+}
+
+function collectElementText(element: h, values: Set<string>) {
+  if (typeof element === 'string') {
+    values.add(element)
+    return
+  }
+
+  for (const value of Object.values(element.attrs || {})) {
+    if (typeof value === 'string') values.add(value)
+  }
+
+  for (const child of element.children || []) {
+    collectElementText(child as h, values)
+  }
+}
+
+function maybeCollectJsonValues(text: string, values: Set<string>) {
+  try {
+    const json = JSON.parse(text)
+    walkJson(json, values)
+  } catch {
+    const unescaped = text.replace(/\\"/g, '"').replace(/\\\//g, '/')
+    if (unescaped !== text) values.add(unescaped)
+  }
+}
+
+function walkJson(value: unknown, values: Set<string>) {
+  if (typeof value === 'string') {
+    values.add(value)
+    return
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) walkJson(item, values)
+    return
+  }
+  if (value && typeof value === 'object') {
+    for (const item of Object.values(value)) walkJson(item, values)
+  }
+}
+
+function normalizeText(text: string) {
+  let value = decodeHtmlEntities(text).replace(/\\\//g, '/')
+  try {
+    value = decodeURIComponent(value)
+  } catch {
+    // Keep the original if it is only partly percent-encoded.
+  }
+  return value
+}
+
+function decodeHtmlEntities(text: string) {
+  return text
+    .replace(/&quot;/g, '"')
+    .replace(/&#34;/g, '"')
+    .replace(/&#x22;/gi, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&#39;/g, "'")
+    .replace(/&#x27;/gi, "'")
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+}
+
+function cleanUrl(url: string) {
+  return ensureProtocol(url)
+    .replace(/[),，。；;！？!]+$/g, '')
+    .replace(/&amp;/g, '&')
+}
+
+function ensureProtocol(url: string) {
+  return /^https?:\/\//i.test(url) ? url : `https://${url}`
+}
+
+async function fetchText(url: string, config: XhsConfigLike) {
+  const response = await fetchWithTimeout(url, config, { redirect: 'follow' })
+  if (!response.ok) throw new Error(`请求小红书页面失败：HTTP ${response.status}`)
+  return response.text()
+}
+
+async function fetchWithTimeout(url: string, config: XhsConfigLike, init: RequestInit) {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), config.timeout * 1000)
+
+  try {
+    return await fetch(url, {
+      ...init,
+      signal: controller.signal,
+      headers: {
+        ...DEFAULT_HEADERS,
+        'user-agent': config.userAgent,
+        ...(config.cookie ? { cookie: config.cookie } : {}),
+        ...(init.headers || {}),
+      },
+    })
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+function parseLooseObject(payload: string) {
+  return JSON.parse(payload)
+}
+
+function getFirstNoteFromDetailMap(map: unknown) {
+  if (!map || typeof map !== 'object') return null
+  const first = Object.values(map)[0] as any
+  return first?.note || null
+}
+
+function buildNote(data: any, url: string, config: XhsConfigLike): XhsNote {
+  const id = get(data, 'noteId') || extractIdFromUrl(url)
+  const type = normalizeType(get(data, 'type'))
+
+  return {
+    id,
+    url: id ? `https://www.xiaohongshu.com/explore/${id}` : url,
+    title: get(data, 'title') || '小红书笔记',
+    desc: get(data, 'desc') || '',
+    type,
+    authorName: get(data, 'user.nickname') || get(data, 'user.nickName') || '未知作者',
+    authorId: get(data, 'user.userId') || '',
+    likedCount: get(data, 'interactInfo.likedCount'),
+    collectedCount: get(data, 'interactInfo.collectedCount'),
+    commentCount: get(data, 'interactInfo.commentCount'),
+    shareCount: get(data, 'interactInfo.shareCount'),
+    imageUrls: extractImageUrls(data, config.imageFormat),
+    videoUrls: extractVideoUrls(data),
+  }
+}
+
+function formatNoteText(note: XhsNote, config: XhsConfigLike) {
+  const lines = [
+    `小红书：${note.title}`,
+    `作者：${note.authorName}`,
+  ]
+
+  if (note.desc && config.maxDescLength > 0) {
+    lines.push(trimText(note.desc, config.maxDescLength, config.descTruncateSuffix))
+  }
+  if (config.showStats) {
+    lines.push(`点赞：${displayCount(note.likedCount)}  收藏：${displayCount(note.collectedCount)}  评论：${displayCount(note.commentCount)}  分享：${displayCount(note.shareCount)}`)
+  }
+  if (config.showLink) lines.push(note.url)
+
+  return lines.join('\n')
+}
+
+function extractImageUrls(data: any, format: XhsConfigLike['imageFormat']) {
+  const images = Array.isArray(data?.imageList) ? data.imageList : []
+  const urls: string[] = []
+
+  for (const image of images) {
+    const source = image?.urlDefault || image?.url
+    if (!source || typeof source !== 'string') continue
+
+    const token = extractImageToken(source)
+    if (!token) continue
+    urls.push(format === 'auto'
+      ? `https://sns-img-bd.xhscdn.com/${token}`
+      : `https://ci.xiaohongshu.com/${token}?imageView2/format/${format}`)
+  }
+
+  return [...new Set(urls)]
+}
+
+function extractImageToken(url: string) {
+  try {
+    const parsed = new URL(url.replace(/\\u002F/g, '/'))
+    return parsed.pathname.split('/').slice(3).join('/').split('!')[0]
+  } catch {
+    return url.split('/').slice(5).join('/').split('!')[0]
+  }
+}
+
+function extractVideoUrls(data: any) {
+  const originVideoKey = get(data, 'video.consumer.originVideoKey')
+  if (originVideoKey) return [`https://sns-video-bd.xhscdn.com/${originVideoKey}`]
+
+  const streams = [
+    ...(get(data, 'video.media.stream.h265') || []),
+    ...(get(data, 'video.media.stream.h264') || []),
+  ].filter(Boolean)
+
+  streams.sort((a, b) => (a.height || 0) - (b.height || 0))
+  const best = streams[streams.length - 1]
+  return best?.backupUrls?.[0] ? [best.backupUrls[0]] : best?.masterUrl ? [best.masterUrl] : []
+}
+
+function normalizeType(type: unknown): XhsNote['type'] {
+  if (type === 'video') return 'video'
+  if (type === 'normal') return 'normal'
+  return 'unknown'
+}
+
+function get(source: any, path: string) {
+  return deepGet(source, path.split('.'))
+}
+
+function deepGet(source: any, path: string[]) {
+  let cursor = source
+  for (const key of path) {
+    if (cursor == null) return undefined
+    cursor = cursor[key]
+  }
+  return cursor
+}
+
+function extractIdFromUrl(url: string) {
+  return url.match(/\/(?:explore|item)\/([^/?#]+)/)?.[1] || ''
+}
+
+function trimText(text: string, maxLength: number, suffix: string) {
+  return text.length > maxLength ? `${text.slice(0, maxLength)}${suffix}` : text
+}
+
+function displayCount(value: unknown) {
+  return value == null || value === '' ? '-' : String(value)
+}