Koishi 插件：Twitter Fetcher

一个 推特/Twitter/X 内容获取与订阅插件。它不仅可以在你发送推特链接时即时解析其完整内容，还能让你订阅喜爱的推特用户，自动将他们的最新动态推送到指定的群聊中。

• 链接解析模式：当群友在聊天中发送一条推特链接时，插件会自动抓取该链接的全部信息，包含用户ID、推文内容、推文截图以及所有图片和视频。
• 订阅推送模式：在后台定时检查你订阅的推特用户，一旦发现新推文，就会自动将其内容推送到你指定的群组。

✨ 功能特性

• 双模工作: 同时支持 链接实时解析 和 用户后台订阅 两种模式。
• 配置清晰: 采用总开关控制订阅功能，启用后才显示详细配置，清爽直观。
• 定时推送: 订阅功能可按指定频率自动检查并推送新推文。
• 智能筛选: 支持三种推文筛选模式 - 全部推文、仅含媒体推文、仅纯文字推文，满足不同需求。
• 内容全面: 无论是解析还是推送，都能完整获取推文的文本、截图、图片、视频。
• 高度定制: 链接解析和订阅推送的内容格式（如是否带截图、文本等）可分开独立配置。
• 多群组推送: 可将同一个用户的更新推送到多个不同的群组。
• 智能发送: 在 QQ 平台可使用合并转发，在其他平台则会自动切换为图文拼接模式。
• 内置测试指令: 提供了方便的指令来测试用户推送和群组推送功能是否正常。
• 运行稳定: 采用链接比对，防止出现重复推送的情况。
• 内置谷歌翻译: 可将推文内容自动翻译成指定语言，且手动解析和自动推送的翻译功能可独立开关和配置。

📦 安装

1. 从 Koishi 插件市场搜索并安装 twitter-fetcher。

2. 安装前置依赖 puppeteer 和 database：本插件的功能依赖于 puppeteer 服务和 database 服务，请确保你已经正确安装并配置了它们。

   # 如果你尚未安装 puppeteer
   npm install koishi-plugin-puppeteer
   
   

⚙️ 配置项

你可以在插件配置页面中调整以下选项，它们被清晰地分成了不同模块：

1. 解析设置

这些选项仅在手动发送链接进行解析时生效。

• showScreenshot: 是否发送推文截图。(默认: true)
• sendText: 是否发送提取的推文文本。(默认: true)
• sendMedia: 是否发送推文中的图片和视频。(默认: true)
• cookie: Twitter/X 登录 Cookie(auth_token)。
• useForward: 是否使用合并转发的形式发送。(默认: false)
• silentParsing: 是否关闭解析时的加载提示。(默认: false)

2. 订阅推送内容设置

这些选项仅在后台自动推送订阅的推文时生效。

• sub_showLink: 推送时，是否附带原始推文链接。(默认: true)
• sub_showScreenshot: 推送时，是否发送截图。(默认: true)
• sub_sendText: 推送时，是否发送文本。(默认: true)
• sub_sendMedia: 推送时，是否发送媒体文件。(默认: true)
• sub_useForward: 推送时，是否使用合并转发。(默认: false)

3. 翻译设置

在这里配置对推文内容的自动翻译功能。

• parse_enableTranslation: 【手动解析】 是否开启翻译。当手动发送链接时生效。
• parse_targetLang: 手动解析时，翻译的目标语言（提供常用语言下拉菜单）。
• sub_enableTranslation: 【订阅推送】 是否开启翻译。当自动推送订阅时生效。
• sub_targetLang: 自动推送时，翻译的目标语言（提供常用语言下拉菜单）。

4. 订阅设置

在这里启用并管理你的订阅列表。

• enableSubscription: 【总开关】 是否启用订阅功能。这是一个总开关，开启后才会显示下面的详细设置，并使订阅功能真正开始工作。
• platform: (必填) 用于执行推送的机器人平台 (例如: onebot)。
• selfId: (必填) 用于执行推送的机器人账号/ID (例如: 12345678)。
• updateInterval: 每隔多少分钟检查一次更新。(默认: 5 分钟)
• subscriptions: 你的订阅列表。这是一个表格，你可以添加多行：
  • username: 你要订阅的推特用户名 (例如 elonmusk)。
  • groupIds: 一个或多个群号的列表，新推文将会被推送到这些群。
  • excludeRetweets: 是否排除转推(Repost)？(默认: true)
  • tweetFilterMode: 最新推文筛选模式。(默认: 全部)
    • 全部: 推送该用户的所有推文（不论是否包含媒体）
    • 仅含媒体: 只推送包含图片、视频或GIF的推文
    • 仅纯文字: 只推送不包含任何媒体的纯文字推文

5. 调试设置

• logDetails: 是否在控制台输出详细的分步调试日志。日常使用建议关闭。(默认: false)

📝 使用方法

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

• 测试群组推送

  • 功能：立即手动触发一次对所有已配置订阅的检查，并将最新推文（无论是否已推送过）强制推送到目标群组。
  • 用途：用于在配置好订阅列表后，立即验证机器人的推送功能是否正常工作，无需等待下一个检查周期。

🖼️ 效果演示

链接解析效果:

订阅推送效果: (与上方类似，但会根据你的“订阅推送内容设置”进行格式化，并自动发送到指定群组)

⚠️ 注意事项

• 本插件的数据来源于 vxtwitter.com API，解析的成功与否依赖于该服务的稳定性。
• 截图和订阅功能依赖 Puppeteer 访问 Twitter 官网，可能会因网络波动或 Twitter 前端代码更新而偶尔失败。
• 订阅功能会将已推送的推文链接记录在数据库中，以防止重复推送。
• 遇到推送失败请优先重启 Puppeteer。
• 如遇到推文截图内容被遮挡请修改 Puppeteer 浏览器设置中的 默认的视图宽度 和 默认视图高度 选项，建议2560*1440。

⚖️ 免责声明

1. 工具属性: 本插件是一个基于 Koishi 框架的技术工具，旨在通过聚合公开的互联网信息，为用户提供便利的浏览体验。

2. 内容来源: 本插件展示的所有文本、图片、视频及截图内容，均来源于第三方 API (vxtwitter.com) 及 Twitter/X 平台本身。插件开发者不拥有、不生产、不存储、也不对这些内容的合法性、准确性或完整性做任何保证。

3. 用户责任: 使用本插件的用户，必须在遵守当地法律法规及 Koishi 和 Twitter/X 平台用户协议的前提下进行。用户通过本插件获取和传播的所有信息，其责任由用户本人承担。严禁使用本插件从事任何非法活动或传播不当内容。

4. 免责条款: 开发者不对因使用、不当使用或无法使用本插件而导致的任何直接、间接、偶然、特殊或后果性的损害承担任何责任。

您在下载、安装或使用本插件时，即表示您已阅读、理解并同意以上所有条款。

💖 致谢

• Koishi: 提供了一切的基础。
• vxtwitter.com: 提供了稳定、好用的推文解析 API。
• shangxue 的 bilibili-videolink-analysis 插件: 本插件的文件处理方案深受其启发，特此感谢。
• 特别鸣谢：Google Gemini 2.5 Pro。

更新日志

• v1.1.6：新增“原图下载”功能，支持在解析和推送时分别配置是否下载最高画质的原图（支持 :orig 后缀）。
• v1.1.5：新增“静默解析”选项，可关闭解析链接时的加载提示。
• v1.1.3：修复置顶和转推的关键词识别问题。
• v1.1.2：所有 h.image() 和 h.video() 的调用不再使用 Base64 字符串，改用 buffer 发送媒体文件。在订阅轮询任务中，处理完一个用户的推送后，会增加 3 秒的延迟再处理下一个用户。