koishi-plugin-twitter-fetcher 0.0.4 → 1.0.2

package/lib/index.d.ts

@@ -1,13 +1,42 @@
 import { Context, Schema } from 'koishi';
 export declare const name = "twitter-fetcher";
-export declare const inject: string[];
-export interface Config {
+export declare const inject: {
+    required: string[];
+};
+declare module 'koishi' {
+    interface Tables {
+        twitter_subscriptions: {
+            id: string;
+            last_tweet_url: string;
+        };
+    }
+}
+interface BaseConfig {
     showScreenshot: boolean;
     sendText: boolean;
     sendMedia: boolean;
     cookie: string;
     useForward: boolean;
+    sub_showLink: boolean;
+    sub_showScreenshot: boolean;
+    sub_sendText: boolean;
+    sub_sendMedia: boolean;
+    sub_useForward: boolean;
     logDetails: boolean;
 }
+type SubscriptionConfig = {
+    enableSubscription: false;
+} | {
+    enableSubscription: true;
+    platform: string;
+    selfId: string;
+    updateInterval: number;
+    subscriptions: {
+        username: string;
+        groupIds: string[];
+    }[];
+};
+export type Config = BaseConfig & SubscriptionConfig;
 export declare const Config: Schema<Config>;
 export declare function apply(ctx: Context, config: Config): void;
+export {};

package/lib/index.js

@@ -28,118 +28,286 @@ __export(src_exports, {
 module.exports = __toCommonJS(src_exports);
 var import_koishi = require("koishi");
 var name = "twitter-fetcher";
-var inject = ["puppeteer"];
+var inject = {
+  required: ["puppeteer", "database"]
+};
 var logger = new import_koishi.Logger(name);
-var Config = import_koishi.Schema.object({
-  showScreenshot: import_koishi.Schema.boolean().description("是否发送推文截图。").default(true),
-  sendText: import_koishi.Schema.boolean().description("是否发送提取的推文文本。").default(true),
-  sendMedia: import_koishi.Schema.boolean().description("是否发送推文中的图片和视频。").default(true),
-  cookie: import_koishi.Schema.string().role("textarea").description("可选的 Twitter/X 登录 Cookie"),
-  useForward: import_koishi.Schema.boolean().description("是否使用合并转发的形式发送（仅 QQ 平台效果最佳）。").default(true),
-  logDetails: import_koishi.Schema.boolean().description("是否在控制台输出详细的调试日志。").default(false)
-});
+var Config = import_koishi.Schema.intersect([
+  // --- 第 1 块: 解析设置 ---
+  import_koishi.Schema.object({
+    showScreenshot: import_koishi.Schema.boolean().description("是否发送推文截图。").default(true),
+    sendText: import_koishi.Schema.boolean().description("是否发送提取的推文文本。").default(true),
+    sendMedia: import_koishi.Schema.boolean().description("是否发送推文中的图片和视频。").default(true),
+    cookie: import_koishi.Schema.string().role("textarea").description("Twitter/X 登录 Cookie(auth_token)."),
+    useForward: import_koishi.Schema.boolean().description("是否使用合并转发的形式发送(仅 QQ 平台效果最佳).").default(false)
+  }).description("解析设置 - 当手动发送链接时生效"),
+  // --- 第 2 块: 订阅推送内容设置 ---
+  import_koishi.Schema.object({
+    sub_showLink: import_koishi.Schema.boolean().description("推送时, 是否在消息顶部附带原始推文链接。").default(true),
+    sub_showScreenshot: import_koishi.Schema.boolean().description("推送时, 是否发送推文截图。").default(true),
+    sub_sendText: import_koishi.Schema.boolean().description("推送时, 是否发送提取的推文文本。").default(true),
+    sub_sendMedia: import_koishi.Schema.boolean().description("推送时, 是否发送推文中的图片和视频。").default(true),
+    sub_useForward: import_koishi.Schema.boolean().description("推送时, 是否使用合并转发。").default(false)
+  }).description("订阅推送内容设置 - 当自动推送订阅时生效"),
+  // --- 第 3 块: 订阅设置 ---
+  // 第一部分：仅用于在 UI 上创建“订阅设置”分组和那个可见的布尔开关
+  import_koishi.Schema.object({
+    enableSubscription: import_koishi.Schema.boolean().description("**【总开关】是否启用订阅功能。** 开启后会显示详细设置。").default(false)
+  }).description("订阅设置"),
+  // 第二部分：根据 enableSubscription 的值，来决定是否显示下方的详细配置
+  import_koishi.Schema.union([
+    import_koishi.Schema.object({
+      enableSubscription: import_koishi.Schema.const(false)
+      // 当开关为 false 时，此对象生效，不添加任何额外字段
+    }),
+    import_koishi.Schema.object({
+      enableSubscription: import_koishi.Schema.const(true),
+      // 当开关为 true 时，此对象生效，加载所有必填字段
+      platform: import_koishi.Schema.string().description("用于执行推送的机器人平台 (例如: onebot)。").required(),
+      selfId: import_koishi.Schema.string().description("用于执行推送的机器人账号/ID (例如: 12345678)。").required(),
+      updateInterval: import_koishi.Schema.number().min(1).description("每隔多少分钟检查一次更新。").default(5),
+      subscriptions: import_koishi.Schema.array(import_koishi.Schema.object({
+        username: import_koishi.Schema.string().description("推特用户名"),
+        groupIds: import_koishi.Schema.array(String).role("table").description("需要推送的群号列表")
+      })).role("table").description("订阅列表")
+    })
+  ]),
+  // --- 第 4 块: 调试设置 ---
+  import_koishi.Schema.object({
+    logDetails: import_koishi.Schema.boolean().description("是否在控制台输出详细的调试日志。").default(false)
+  }).description("调试设置")
+]);
 var TWEET_URL_REGEX = /https?:\/\/(twitter\.com|x\.com)\/(\w+)\/status\/(\d+)/g;
+async function getLatestTweetUrlByPuppeteer(puppeteer, username, cookie, log) {
+  log?.(`正在访问用户主页: https://x.com/${username}`);
+  const page = await puppeteer.page();
+  try {
+    if (cookie) await page.setCookie({ name: "auth_token", value: cookie, domain: ".x.com", path: "/", httpOnly: true, secure: true });
+    await page.goto(`https://x.com/${username}`, { waitUntil: "networkidle2", timeout: 3e4 });
+    await page.waitForSelector('article[data-testid="tweet"]', { timeout: 2e4 });
+    const latestTweetUrl = await page.evaluate(() => {
+      const articles = document.querySelectorAll('article[data-testid="tweet"]');
+      for (const article of articles) {
+        if (article.querySelector('[data-testid="socialContext"]')?.textContent.includes("Pinned")) continue;
+        const link = article.querySelector('a[href*="/status/"]');
+        if (link) return link.href;
+      }
+      return null;
+    });
+    if (latestTweetUrl) {
+      log?.(`成功获取到最新推文链接: ${latestTweetUrl}`);
+      return latestTweetUrl;
+    }
+    logger.warn(`[Puppeteer] 在 ${username} 的主页上未能找到任何推文链接.`);
+    return null;
+  } finally {
+    await page.close();
+  }
+}
+__name(getLatestTweetUrlByPuppeteer, "getLatestTweetUrlByPuppeteer");
+async function getTweetScreenshot(puppeteer, url, cookie, log) {
+  const page = await puppeteer.page();
+  try {
+    log?.(`准备截图页面: ${url}`);
+    if (cookie) await page.setCookie({ name: "auth_token", value: cookie, domain: ".x.com", path: "/", httpOnly: true, secure: true });
+    await page.goto(url, { waitUntil: "networkidle2", timeout: 2e4 });
+    const tweetElement = await page.waitForSelector('article[data-testid="tweet"]', { timeout: 15e3 });
+    if (!tweetElement) throw new Error("无法在页面上定位到推文元素.");
+    log?.("定位到推文元素, 正在生成截图...");
+    return await tweetElement.screenshot();
+  } finally {
+    await page.close();
+  }
+}
+__name(getTweetScreenshot, "getTweetScreenshot");
 function apply(ctx, config) {
-  logger.info("Twitter Fetcher 插件已启动。");
-  ctx.middleware(async (session, next) => {
-    TWEET_URL_REGEX.lastIndex = 0;
-    const match = TWEET_URL_REGEX.exec(session.content);
-    if (!match) return next();
-    const originalUrl = match[0];
-    if (config.logDetails) logger.info(`[1/5] 检测到推文链接: ${originalUrl}`);
-    const quote = (0, import_koishi.h)("quote", { id: session.messageId });
-    const statusMessage = await session.send(`${quote}正在解析推文链接，请稍候...`);
-    try {
-      const textParts = [];
-      const mediaParts = [];
-      let screenshotElement = null;
-      if (config.showScreenshot) {
-        try {
-          const screenshotBuffer = await getTweetScreenshot(ctx.puppeteer, originalUrl, config.cookie);
-          if (!screenshotBuffer) throw new Error("截图结果为空");
-          const dataUri = `data:image/png;base64,${screenshotBuffer.toString("base64")}`;
-          screenshotElement = import_koishi.h.image(dataUri);
-        } catch (error) {
-          if (config.logDetails) logger.warn(`[!] 截图失败: ${error.message}`);
+  logger.info("Twitter Fetcher 插件已启动.");
+  ctx.model.extend("twitter_subscriptions", { id: "string", last_tweet_url: "string" }, { primary: "id" });
+  const createLogStepper = /* @__PURE__ */ __name((prefix) => {
+    let step = 1;
+    return (message, isWarning = false) => {
+      if (config.logDetails) {
+        const logMessage = `[${prefix}] [步骤 ${step++}] ${message}`;
+        if (isWarning) {
+          logger.warn(logMessage);
+        } else {
+          logger.info(logMessage);
         }
       }
+    };
+  }, "createLogStepper");
+  async function processTweet(tweetUrl, options) {
+    const log = createLogStepper(tweetUrl);
+    log(`开始处理推文`);
+    const textParts = [];
+    const mediaParts = [];
+    if (options.showLink) {
+      log("配置了推送时附带链接, 在消息头部加入推文URL.");
+      textParts.push(tweetUrl);
+    }
+    let screenshotElement = null;
+    if (options.showScreenshot) {
+      log("开始获取推文截图.");
       try {
-        const apiUrl = originalUrl.replace(/(twitter\.com|x\.com)/, "api.vxtwitter.com");
-        const apiResponse = await ctx.http.get(apiUrl);
-        if (config.logDetails) logger.info(`[2/5] 收到 vxtwitter API 响应...`);
-        if (apiResponse.user_screen_name) textParts.push(`用户ID：${apiResponse.user_screen_name}`);
-        if (apiResponse.text && config.sendText) textParts.push(`推文内容：${apiResponse.text}`);
-        if (config.logDetails) logger.info(`[3/5] 文本部分构造完毕。`);
-        if (screenshotElement) mediaParts.push(screenshotElement);
-        if (config.sendMedia && apiResponse.media_extended) {
-          for (const media of apiResponse.media_extended) {
-            try {
-              const file = await ctx.http.file(media.url);
-              const buffer = Buffer.from(file.data);
-              const mimeType = file.mime || (media.type === "video" ? "video/mp4" : "image/jpeg");
-              const dataUri = `data:${mimeType};base64,${buffer.toString("base64")}`;
-              if (media.type === "image") mediaParts.push(import_koishi.h.image(dataUri));
-              else if (media.type === "video") mediaParts.push(import_koishi.h.video(dataUri));
-            } catch (error) {
-              if (config.logDetails) logger.warn(`下载媒体文件失败: ${media.url}`, error);
-            }
-          }
+        const screenshotBuffer = await getTweetScreenshot(ctx.puppeteer, tweetUrl, config.cookie, log);
+        if (screenshotBuffer) {
+          screenshotElement = import_koishi.h.image(`data:image/png;base64,${screenshotBuffer.toString("base64")}`);
+          log("截图成功并转换为 h.image 元素.");
         }
       } catch (error) {
-        logger.warn(`[!] 通过 API 获取内容失败:`, error);
+        log(`截图失败: ${error.message}`, true);
+      }
+    }
+    try {
+      const apiUrl = tweetUrl.replace(/(twitter\.com|x\.com)/, "api.vxtwitter.com");
+      log(`使用 vxtwitter API 进行解析: ${apiUrl}`);
+      const http = ctx.http.extend({ headers: { "User-Agent": "Koishi-Twitter-Fetcher" } });
+      const apiResponse = await http.get(apiUrl);
+      log("成功接收到 vxtwitter API 的响应.");
+      if (apiResponse.user_screen_name) textParts.push(`用户ID: ${apiResponse.user_screen_name}`);
+      if (apiResponse.text && options.sendText) textParts.push(`推文内容: ${apiResponse.text}`);
+      if (screenshotElement) mediaParts.push(screenshotElement);
+      if (options.sendMedia && apiResponse.media_extended) {
+        log(`发现 ${apiResponse.media_extended.length} 个媒体文件, 准备下载.`);
+        for (const [index, media] of apiResponse.media_extended.entries()) {
+          try {
+            const file = await http.file(media.url);
+            const dataUri = `data:${file.mime};base64,${Buffer.from(file.data).toString("base64")}`;
+            if (media.type === "image") mediaParts.push(import_koishi.h.image(dataUri));
+            else if (media.type === "video") mediaParts.push(import_koishi.h.video(dataUri));
+            log(`媒体文件 ${index + 1}/${apiResponse.media_extended.length} (${media.type}) 下载并转换成功.`);
+          } catch (error) {
+            log(`下载媒体文件失败: ${media.url}, 错误: ${error.message}`, true);
+          }
+        }
       }
       const hasText = textParts.length > 0;
       const hasMedia = mediaParts.length > 0;
       if (!hasText && !hasMedia) {
-        await session.send("未能获取到该推文的任何内容。");
+        log("处理完成, 但未能获取到任何文本或媒体内容.", true);
+        return "未能获取到任何内容.";
+      }
+      log("内容组装完毕, 准备发送.");
+      if (options.useForward && options.platform === "onebot") {
+        const forwardElements = [textParts.join("\n"), ...mediaParts].filter(Boolean);
+        return (0, import_koishi.h)("figure", {}, forwardElements);
       } else {
-        if (config.useForward && session.platform === "onebot") {
-          const forwardElements = [];
-          if (hasText) forwardElements.push(textParts.join("\n"));
-          if (hasMedia) forwardElements.push(...mediaParts);
-          if (config.logDetails) logger.info(`[4/5] 正在构造合并转发消息...`);
-          await session.send((0, import_koishi.h)("figure", {}, forwardElements));
-          if (config.logDetails) logger.info(`[5/5] 合并转发消息已发送。`);
-        } else {
-          const finalParts = [];
-          if (hasText) finalParts.push(textParts.join("\n"));
-          if (hasMedia) finalParts.push(...mediaParts);
-          const messageToSend = finalParts.join("\n\n");
-          if (config.logDetails) logger.info(`[4/5] 最终拼接的待发消息字符串:
----
-${messageToSend}
----`);
-          await session.send(messageToSend);
-          if (config.logDetails) logger.info(`[5/5] 消息已发送。`);
-        }
+        const finalParts = [textParts.join("\n"), ...mediaParts].filter(Boolean);
+        return finalParts.join("\n\n");
       }
     } catch (error) {
-      logger.error("处理推文链接时发生未知错误:", error);
-    } finally {
-      await session.bot.deleteMessage(session.channelId, statusMessage[0]);
+      logger.warn(`[!] API 处理失败:`, error);
+      return `获取推文内容失败: ${error.message}`;
     }
+  }
+  __name(processTweet, "processTweet");
+  ctx.middleware(async (session, next) => {
+    TWEET_URL_REGEX.lastIndex = 0;
+    const match = TWEET_URL_REGEX.exec(session.content);
+    if (!match) return next();
+    const statusMessage = await session.send((0, import_koishi.h)("quote", { id: session.messageId }) + "正在解析推文链接, 请稍候...");
+    const messageToSend = await processTweet(match[0], {
+      showLink: false,
+      showScreenshot: config.showScreenshot,
+      sendText: config.sendText,
+      sendMedia: config.sendMedia,
+      useForward: config.useForward,
+      platform: session.platform
+    });
+    await session.send(messageToSend);
+    await session.bot.deleteMessage(session.channelId, statusMessage[0]);
   });
-}
-__name(apply, "apply");
-async function getTweetScreenshot(puppeteer, url, cookie) {
-  const page = await puppeteer.page();
-  try {
-    if (cookie) {
-      const cookieObj = { name: "auth_token", value: cookie, domain: ".twitter.com", path: "/", httpOnly: true, secure: true };
-      const xCookie = { ...cookieObj, domain: ".x.com" };
-      await page.setCookie(cookieObj, xCookie);
+  async function checkAndPushUpdates(isManualTrigger = false) {
+    if (!config.enableSubscription) return;
+    if (config.logDetails) logger.info("[订阅] 开始新一轮更新检查...");
+    const botKey = `${config.platform}:${config.selfId}`;
+    const bot = ctx.bots[botKey];
+    if (!bot || !bot.online) {
+      logger.warn(`[订阅] 配置中指定的机器人 [${botKey}] 不存在或不在线, 跳过本轮检查.`);
+      return isManualTrigger ? `配置中指定的机器人 [${botKey}] 不存在或不在线.` : void 0;
     }
-    await page.goto(url, { waitUntil: "networkidle2", timeout: 2e4 });
-    const tweetSelector = 'article[data-testid="tweet"]';
-    await page.waitForSelector(tweetSelector, { timeout: 15e3 });
-    const tweetElement = await page.$(tweetSelector);
-    if (!tweetElement) throw new Error("无法在页面上定位到推文元素。");
-    return await tweetElement.screenshot();
-  } finally {
-    await page.close();
+    let updatesFound = 0;
+    for (const sub of config.subscriptions) {
+      if (!sub.username || !sub.groupIds || sub.groupIds.length === 0) continue;
+      const log = createLogStepper(`订阅:${sub.username}`);
+      log("开始处理此用户的订阅.");
+      try {
+        const latestTweetUrl = await getLatestTweetUrlByPuppeteer(ctx.puppeteer, sub.username, config.cookie, log);
+        if (!latestTweetUrl) {
+          log("未能获取到最新推文链接, 跳过.", true);
+          continue;
+        }
+        const record = await ctx.database.get("twitter_subscriptions", { id: sub.username });
+        const lastUrl = record[0]?.last_tweet_url;
+        log(`数据库中记录的上次链接: ${lastUrl || "无"}`);
+        const isNew = !lastUrl || lastUrl !== latestTweetUrl;
+        const shouldPush = isNew || isManualTrigger && latestTweetUrl;
+        if (shouldPush) {
+          updatesFound++;
+          logger.info(`[订阅] ★★★ 发现 [${sub.username}] 的新推文! ★★★`);
+          log(`准备推送新内容: ${latestTweetUrl}`);
+          const messageToSend = await processTweet(latestTweetUrl, {
+            showLink: config.sub_showLink,
+            showScreenshot: config.sub_showScreenshot,
+            sendText: config.sub_sendText,
+            sendMedia: config.sub_sendMedia,
+            useForward: config.sub_useForward,
+            platform: bot.platform
+          });
+          for (const groupId of sub.groupIds) {
+            await bot.sendMessage(groupId, messageToSend);
+          }
+          log(`已向 ${sub.groupIds.length} 个群组完成推送.`);
+          if (isNew) {
+            await ctx.database.upsert("twitter_subscriptions", [{ id: sub.username, last_tweet_url: latestTweetUrl }]);
+            log("数据库已更新为最新推文链接.");
+          }
+        } else {
+          log("链接无变化, 无需推送.");
+        }
+      } catch (error) {
+        logger.warn(`[订阅] 检查 [${sub.username}] 时发生错误:`, error);
+      }
+    }
+    if (config.logDetails) logger.info(`[订阅] 本轮更新检查结束, 共发现 ${updatesFound} 个更新.`);
+    if (isManualTrigger) {
+      return `手动检查完成, 共为 ${updatesFound} 个订阅执行了推送任务.`;
+    }
+  }
+  __name(checkAndPushUpdates, "checkAndPushUpdates");
+  if (config.enableSubscription) {
+    ctx.setInterval(() => checkAndPushUpdates(false), config.updateInterval * import_koishi.Time.minute);
+    ctx.command("测试推特用户推送 <username:string>", "测试指定用户的最新推文能否被正确获取和推送").action(async ({ session }, username) => {
+      if (!username) return "请输入要测试的用户名.";
+      await session.send(`正在为 [${username}] 获取最新推文并模拟推送到当前会话...`);
+      const log = createLogStepper(`测试:${username}`);
+      try {
+        const latestTweetUrl = await getLatestTweetUrlByPuppeteer(ctx.puppeteer, username, config.cookie, log);
+        if (!latestTweetUrl) return "无法找到该用户的最新推文链接.";
+        await session.send(`成功获取到最新推文链接: ${latestTweetUrl}
+正在生成内容...`);
+        const messageToSend = await processTweet(latestTweetUrl, {
+          showLink: config.sub_showLink,
+          showScreenshot: config.sub_showScreenshot,
+          sendText: config.sub_sendText,
+          sendMedia: config.sub_sendMedia,
+          useForward: config.sub_useForward,
+          platform: session.platform
+        });
+        await session.send(messageToSend);
+      } catch (error) {
+        logger.warn(`[测试] 测试 [${username}] 时出错:`, error);
+        return `测试失败: ${error.message}`;
+      }
+    });
+    ctx.command("测试群组推送", "立即获取所有订阅的最新推文并强制推送, 用于测试").action(async ({ session }) => {
+      session.send("正在手动触发所有订阅的强制推送任务...");
+      const result = await checkAndPushUpdates(true);
+      return result;
+    });
   }
 }
-__name(getTweetScreenshot, "getTweetScreenshot");
+__name(apply, "apply");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Config,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "koishi-plugin-twitter-fetcher",
-  "description": "自动解析 推特Twitter/X 链接，聚合推文截图、文本、图片和视频。",
-  "version": "0.0.4",
+  "description": "一个推特/Twitter/X内容获取与订阅插件，支持链接实时解析和用户后台订阅推送。",
+  "version": "1.0.2",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
   "files": [
@@ -25,7 +25,10 @@
     "x",
     "fetcher",
     "parse",
-    "resolver"
+    "resolver",
+    "subscribe",
+    "subscription",
+    "push"
   ],
   "peerDependencies": {
     "koishi": "^4.18.7",
@@ -33,11 +36,12 @@
   },
   "koishi": {
     "description": {
-      "zh": "自动解析 推特/Twitter/X 链接，聚合推文截图、文本、图片和视频。"
+      "zh": "自动解析推特/Twitter/X链接，聚合内容。现已支持订阅推送！"
     },
     "service": {
       "required": [
-        "puppeteer"
+        "puppeteer",
+        "database"
       ]
     }
   }

package/readme.md

@@ -3,20 +3,24 @@
 [![npm](https://img.shields.io/npm/v/koishi-plugin-twitter-fetcher.svg)](https://www.npmjs.com/package/koishi-plugin-twitter-fetcher)
 [![npm](https://img.shields.io/npm/dm/koishi-plugin-twitter-fetcher.svg)](https://www.npmjs.com/package/koishi-plugin-twitter-fetcher)
 
-一个 推特/Twitter/X 的链接解析插件。当你或群友在聊天中发送一条推特链接时，本插件会自动抓取该链接的全部信息，包含：
+一个 推特/Twitter/X 内容获取与订阅插件。它不仅可以在你发送推特链接时即时解析其完整内容，还能让你订阅喜爱的推特用户，自动将他们的最新动态推送到指定的群聊中。
 
-*   用户 ID 和推文内容
-*   推文截图
-*   推文中包含的所有图片和视频
+*   **链接解析模式**：当群友在聊天中发送一条推特链接时，插件会自动抓取该链接的全部信息，包含用户ID、推文内容、推文截图以及所有图片和视频。
+*   **订阅推送模式**：在后台定时检查你订阅的推特用户，一旦发现新推文，就会自动将其内容推送到你指定的群组。
 
 ---
 
 ## ✨ 功能特性
 
-*   **自动触发**: 无需任何指令，发送链接即可自动解析。
-*   **内容全面**: 同时获取推文的文本、截图、图片、视频。
-*   **高度可配置**: 可自由开关截图、文本、媒体、合并转发等功能。
-*   **智能回退**: 在非 QQ 平台或关闭合并转发时，会自动切换为图文拼接的发送模式。
+*   **双模工作**: 同时支持 **链接实时解析** 和 **用户后台订阅** 两种模式。
+*   **配置清晰**: 采用总开关控制订阅功能，启用后才显示详细配置，清爽直观。
+*   **定时推送**: 订阅功能可按指定频率自动检查并推送新推文。
+*   **内容全面**: 无论是解析还是推送，都能完整获取推文的文本、截图、图片、视频。
+*   **高度定制**: 链接解析和订阅推送的内容格式（如是否带截图、文本等）可分开独立配置。
+*   **多群组推送**: 可将同一个用户的更新推送到多个不同的群组。
+*   **智能发送**: 在 QQ 平台可使用合并转发，在其他平台则会自动切换为图文拼接模式。
+*   **内置测试指令**: 提供了方便的指令来测试用户推送和群组推送功能是否正常。
+*   **运行稳定**: 采用链接比对，防止出现重复推送的情况。
 
 ---
 
@@ -24,50 +28,112 @@
 
 1.  **从 Koishi 插件市场搜索并安装 `twitter-fetcher`。**
 
-2.  **安装前置依赖 `puppeteer`**：本插件的截图功能依赖于 `puppeteer` 服务，请确保你已经正确安装并配置了它。
+2.  **安装前置依赖 `puppeteer` 和 `database`**：本插件的功能依赖于 `puppeteer` 服务和 `database` 服务，请确保你已经正确安装并配置了它们。
     ```bash
     # 如果你尚未安装 puppeteer
     npm install koishi-plugin-puppeteer
-    ```
+
 
 ---
 
 ## ⚙️ 配置项
 
-你可以在插件配置页面中调整以下选项：
+你可以在插件配置页面中调整以下选项，它们被清晰地分成了不同模块：
+
+### 1. 解析设置
+> 这些选项仅在**手动发送链接**进行解析时生效。
 
 *   **`showScreenshot`**: 是否发送推文截图。(默认: `true`)
 *   **`sendText`**: 是否发送提取的推文文本。(默认: `true`)
 *   **`sendMedia`**: 是否发送推文中的图片和视频。(默认: `true`)
-*   **`cookie`**: (可选) 你的 Twitter/X 登录 Cookie。
-*   **`useForward`**: (推荐) 是否使用合并转发的形式发送。在非 `onebot` 平台会自动禁用。(默认: `true`)
-*   **`logDetails`**: 是否在控制台输出详细的调试日志。日常使用建议关闭。(默认: `false`)
+*   **`cookie`**: Twitter/X 登录 Cookie(auth_token)。
+*   **`useForward`**: 是否使用合并转发的形式发送。(默认: `false`)
+
+### 2. 订阅推送内容设置
+> 这些选项仅在**后台自动推送**订阅的推文时生效。
+
+*   **`sub_showLink`**: 推送时，是否附带原始推文链接。(默认: `true`)
+*   **`sub_showScreenshot`**: 推送时，是否发送截图。(默认: `true`)
+*   **`sub_sendText`**: 推送时，是否发送文本。(默认: `true`)
+*   **`sub_sendMedia`**: 推送时，是否发送媒体文件。(默认: `true`)
+*   **`sub_useForward`**: 推送时，是否使用合并转发。(默认: `false`)
+
+### 3. 订阅设置
+> 在这里启用并管理你的订阅列表。
+
+*   **`enableSubscription`**: **【总开关】** 是否启用订阅功能。这是一个总开关，开启后才会显示下面的详细设置，并使订阅功能真正开始工作。
+*   **`platform`**: (必填) 用于执行推送的机器人平台 (例如: `onebot`)。
+*   **`selfId`**: (必填) 用于执行推送的机器人账号/ID (例如: `12345678`)。
+*   **`updateInterval`**: 每隔多少分钟检查一次更新。(默认: `5` 分钟)
+*   **`subscriptions`**: 你的订阅列表。这是一个表格，你可以添加多行：
+    *   **`username`**: 你要订阅的推特用户名 (例如 `elonmusk`)。
+    *   **`groupIds`**: 一个或多个群号的列表，新推文将会被推送到这些群。
+
+### 4. 调试设置
+
+*   **`logDetails`**: 是否在控制台输出详细的分步调试日志。日常使用建议关闭。(默认: `false`)
 
 ---
 
 ## 📝 使用方法
 
-安装并启用插件后，无需任何额外操作。
-
-你只需要在任意群聊或私聊中，发送一条包含 Twitter/X 链接的消息即可。
+### 1. 链接解析
+安装并启用插件后，此功能默认开启。你只需要在任意群聊或私聊中，发送一条包含 Twitter/X 链接的消息即可。
 
 **例如:**
 > 快看这个！https://x.com/elonmusk/status/1585841233215102976
 
 机器人将会自动解析并回复聚合了全部内容的消息。
 
+### 2. 订阅功能
+1.  前往插件配置页，在 **【订阅设置】** 中，将 `enableSubscription` **总开关** 打开。
+2.  开启后，下方的详细设置会展开。请正确填写 `platform` 和 `selfId`，告诉插件使用哪个机器人账号进行推送。
+3.  在 `subscriptions` 表格中，点击“添加行”，然后填入你想订阅的 **推特用户名** 和希望接收推送的 **群号列表**。
+4.  保存配置。插件将自动开始按照 `updateInterval` 设定的时间间隔检查更新。当发现新推文时，会自动推送到指定的群组。
+
+### 3. Twitter/X auth_token 的获取
+1.  在电脑浏览器上打开 https://x.com 并登录你自己的账号。
+2.  按 F12 打开开发者面板。
+3.  在开发者工具面板的顶部菜单栏中，找到并点击 “应用” (Application) 选项卡。
+4.  在左侧的菜单中，展开 “存储” (Storage) 下的 “Cookie” (Cookies) 栏目。
+5.  在这个列表中找到名为 auth_token 的那一行。
+6.  在 auth_token 这一行中，找到 “值” (Value) 这一列对应的内容，它通常是一长串由字母和数字组成的字符串。
+7.  将刚刚复制的这一长串 auth_token 的值，粘贴到 Koishi 插件配置页面的 cookie 输入框中。
+
+---
+
+## ⌨️ 命令
+
+**注意：** 以下命令只有在配置中启用了 `enableSubscription` 总开关后才可用。
+
+*   `测试推特用户推送 <username:string>`
+    *   功能：测试获取指定用户的最新推文，并将生成的内容直接发送到当前会话。
+    *   用途：用于在添加到订阅列表前，验证对某个用户的抓取是否成功，以及预览推送消息的格式。
+    *   示例：`测试推特用户推送 elonmusk`
+
+*   `测试群组推送`
+    *   功能：立即手动触发一次对所有已配置订阅的检查，并将最新推文（无论是否已推送过）强制推送到目标群组。
+    *   用途：用于在配置好订阅列表后，立即验证机器人的推送功能是否正常工作，无需等待下一个检查周期。
+
 ---
 
 ## 🖼️ 效果演示
 
-![效果图](https://i.postimg.cc/dtc61yqd/1.png)
+**链接解析效果:**
+![链接解析效果图](https://i.postimg.cc/dtc61yqd/1.png)
+
+**订阅推送效果:** (与上方类似，但会根据你的“订阅推送内容设置”进行格式化，并自动发送到指定群组)
 
 ---
 
 ## ⚠️ 注意事项
 
 *   本插件的数据来源于 `vxtwitter.com` API，解析的成功与否依赖于该服务的稳定性。
-*   截图功能依赖 Puppeteer 访问 Twitter 官网，可能会因网络波动或 Twitter 前端代码更新而偶尔失败。
+*   截图和订阅功能依赖 Puppeteer 访问 Twitter 官网，可能会因网络波动或 Twitter 前端代码更新而偶尔失败。
+*   订阅功能会将已推送的推文链接记录在数据库中，以防止重复推送。
+*   遇到推送失败请优先重启 Puppeteer。
+*   如遇到推文截图内容被遮挡请修改 Puppeteer 浏览器设置中的 默认的视图宽度 和 默认视图高度 选项，建议2560*1440。
+
 
 ---
 
@@ -89,4 +155,5 @@
 
 *   **Koishi**: 提供了一切的基础。
 *   **`vxtwitter.com`**: 提供了稳定、好用的推文解析 API。
-*   **shangxue 的 `bilibili-videolink-analysis` 插件**: 本插件的文件处理方案深受其启发，特此感谢。
+*   **shangxue 的 `bilibili-videolink-analysis` 插件**: 本插件的文件处理方案深受其启发，特此感谢。
+*   特别鸣谢：Google Gemini 2.5 Pro。