README_zh.md

Tweetcord

Discord的Twitter通知機器人

English | 繁體中文

📝簡介

Tweetcord是一個Discord機器人，它使用tweety-ns將指定Twitter用戶的即時推文更新傳送到你的Discord伺服器。只需設置想要關注的Twitter用戶和Discord頻道，Tweetcord就會自動將推文轉發到指定頻道，確保你不會錯過重要的更新。🐦

✨功能

截圖

👇每當關注的用戶發布新推文時，你的伺服器也會收到通知。

指令

👉 /add notifier username channel | mention type media_type account_used

參數	類型	描述
username	str	你想要開啟通知的Twitter用戶的用戶名
channel	discord.TextChannel | discord.Thread	機器人發送通知的頻道
mention	discord.Role	通知時提及的身分組
type	str	設定是否啟用轉推和引用的通知
media_type	str	設定是否啟用包含多媒體的通知，或僅啟用包含多媒體的通知
account_used	str	用來追蹤用戶推文的Twitter客戶端

👉 /remove notifier channel username

參數	類型	描述
channel	str	設置為發送通知的頻道
username	str	你想要關閉通知的Twitter用戶的用戶名

👉 /list users | account channel

• 列出所有當前伺服器開啟通知的Twitter用戶

參數	類型	描述
account	str	你想要篩選的客戶端名稱（用來追蹤的帳號）
channel	str	你想要篩選的頻道名稱

👉 /sync

• 將新Twitter帳戶的通知與資料庫同步。如果你更改了bot使用的Twitter帳戶，請使用此指令

👉 /customize settings channel username

參數	類型	描述
channel	str	機器人發送通知的頻道
username	str	欲自定義設定的Twitter用戶的用戶名

送出指令後將會出現設定面板，目前支持修改 mention、type、media_type 以及自訂義通知訊息，account_used 仍僅能使用 /add notifier 指令進行修改。

自定義通知訊息為 f-string 格式，目前支援4種特別的變數可供使用，將在下面說明：

• {action} : 發文者的動作（例如 推了、轉推了、引用了），實際顯示的文字取決於 configs.yml 中的 locale 設定
• {author} : 發文者的顯示名稱
• {mention} : 發送到discord時提及的身份組
• {url} : 推文的連結

以預設通知為例，如果將訊息自定義為以下格式（支援Discord的markdown格式）：

{mention}**{author}** just {action} here: 
{url}

則會在推文發送時會以此格式發出通知（這裡舉一個實際例子）：

@Ping_SubTweet ﾅﾁｮﾈｺ just tweeted here: 
https://twitter.com/nyachodayo/status/1869000108697960952

👉 /customize translation username | language

參數	類型	描述
username	str	欲設定自定義翻譯語言的Twitter用戶的用戶名
language	str	欲翻譯成的語言代碼（例如 en、ja），留空則使用預設值

【注意】：你需要在 embed 設定中將 auto_translation 設為 true 才能使用（僅能在 embed.type 選擇了 built_in 模式或是在 proxy 模式中選用 fx 作為嵌入代理服務時使用，其他嵌入代理服務並不支援此功能）。

📥安裝

在運行機器人之前，你需要安裝必要的模組。

pip install -r requirements.txt

⚡使用

📢本教學適用於0.6或更高版本，舊版設定請參考各個歷史版本的README。

⬆️查看歷史版本升級指南

1. 創建並配置.env文件

BOT_TOKEN=YourDiscordBotToken
TWITTER_TOKEN=NameForYourTwitterToken:YourTwitterAccountAuthToken
DATA_PATH=./data

Note

這裡的 NameForYourTwitterToken 是可以隨意定義的，僅用來作為輸入指令時指定帳戶用的代號，不一定要和Twitter帳號名稱一致。

範例

BOT_TOKEN=FAKE1234567890ABCDEFGHIJKLMNO.PQRSTUVWXYZ1234567890.ABCDEFGHIJKLMNOPQRSTUVWXYZ123456
TWITTER_TOKEN=Account1:12345abcde67890fghij12345klmnop67890qrstuv,Account2:abcdef123456ghijkl7890mnopqrst123456uvwx
DATA_PATH=./data

你可以從cookies中獲取你的token，或是你可以探索其他獲取它的方法。

2. 配置configs.yml文件

建立 configs.yml 並將 configs.example.yml 的內容複製過去，並依照自己的喜好編輯它。請不要刪除或修改 configs.example.yml 的內容，它會作為預設的配置並和你設定配置合併，若你自定義的配置錯誤或缺少參數，它會協助回退到預設的配置並警告。

Important

這裡的所有配置說明和最新版本同步，舊版用戶請參考舊版README。

基本

參數	描述	限制
locale	機器人訊息與指令說明所使用的語言。	目前支援 en 和 zh-TW。
prefix	機器人命令的前綴，只會對前綴指令生效。	無，但建議選擇簡單且易於識別的前綴，並避免使用空字串。
activity_name	機器人顯示的活動名稱。	無。
activity_type	機器人顯示的活動類型。	僅限 playing、streaming、listening、watching 和 competing。
users_list_pagination_size	list users 指令的分頁大小。	只接受整數，不宜使用過大或過小的值。
users_list_page_counter_position	list users 指令的分頁計數器位置。	僅限 title 和 footer 。
enable_prefix_commands_in_guild	是否在伺服器啟用前綴指令（關閉這個選項僅會影響前綴指令，不影響任何功能，需要使用前綴指令上傳/備份資料庫或下載日誌可以私訊機器人），若為 false，則可以禁用訊息內容意圖 (Message Content Intent)。	布林值。

自定義活動名稱為 f-string 格式，目前支援1種特別的變數可供使用，將在下面說明：

• {count} : 目前被機器人追蹤的使用者數量，會即時更新

計時器 & 計數器

參數	描述	單位
tweets_check_period	檢查推文的頻率，不建議將此值設置得太低，以避免速率限制。安全值：18（為什麼是這個數值？），經過測試設置在 10 通常不會遇到速率限制，不推薦低於 10。如果Tweetcord控制的帳號和你平常在使用的帳號相同，請適當提高這個數值以避免速率限制。	秒
tweets_updater_retry_delay	當Tweets Updater遇到異常時的重試間隔。	分鐘
tasks_monitor_check_period	檢查每個任務是否正常運行的間隔，如果某個任務停止了，嘗試重新啟動。	分鐘
tasks_monitor_log_period	將當前運行中的任務列表輸出到執行日誌的間隔。	小時
auth_max_attempts	登入Twitter帳號時的最大嘗試次數，失敗超過此次數將會強制停止機器人運行。	次

控制帳戶行為

參數	描述
auto_change_client	如果為現有使用者指定新用戶端，則自動使用新用戶端對該使用者進行追蹤。
auto_turn_off_notification	如果某個使用者的所有通知都已停用，決定是否停用該使用者的通知（Twitter端）。
auto_unfollow	如果某個使用者的所有通知都已停用，決定是否取消追蹤該使用者。

資料庫

參數	描述
auto_repair_mismatched_clients	當資料庫中含有環境變數未定義的 client_used 的話，是否自動使用目前環境變數所定義的第一個客戶端取代這些無效的客戶端名稱。
init_latest_tweet_on_startup	啟動時將所有使用者的最後發文時間設定為當前時間，開啟這個設定可以讓機器人不補發在下線時錯過的通知（避免一上線洗頻）。

嵌入內容風格

參數	描述
type	決定嵌入內容的類型，支援的類型有: built_in / proxy。
trans_default_lang	啟用 auto_translation 時使用的預設翻譯語言。

built_in:

參數	描述
fx	與 FixupX 整合的進階設定。機器人透過 Tweety 從 Twitter 的通知獲取新推文，由於 Twitter 通知的 API 較舊，對於轉推、引用的多媒體以及文字可能會有缺失，透過向 FixupX 請求可以獲得更完整的內容。media、rt_text 或 auto_translation 選項啟用時，每篇新推文通知發送前都會額外向 FixupX API 請求，若只單獨開啟 mosaic，則只會在必要時進行請求。詳細說明請見下方列表。
video_link_button	當多媒體為影片時，決定是否使用一個連結按鈕做為提示。
legacy_logo	設為true的話會使用推特以前的藍鳥logo做為footer而不是新的X標誌。

• fx
  • media.enabled：啟用後可擷取引用推文中的多媒體。
  • media.external：是否擷取外部連結提供的縮圖。
  • rt_text.enabled：是否顯示引用推文的原文，開啟此設定後對於較長的轉推內容也會完整顯示。
  • rt_text.simplified：內容較多時是否精簡資訊（通常發生於引用推文），啟用時對於過長的訊息會截斷部份引用原文的內容，並隱藏嵌入內容內的右側頭像（thumbnail）。
  • mosaic：當有多張圖片時是否使用 FixupX 的組合圖片，對於無法顯示多張圖片嵌入的iOS系統友善。
  • auto_translation：是否自動將推文內容翻譯為 trans_default_lang 指定的語言。

proxy:

參數	描述
service	傳送推文連結時的嵌入代理服務，可以是 fx 或 vx。
domain_name	傳送推文連結時的域名，使用 fx 服務時可選 fxtwitter 或 fixupx，使用 vx 服務時可選 vxtwitter 或 fixvx。
original_url_button	在訊息最下方加入連結按鈕，導向原始推文連結，可以解決某些裝置點擊嵌入代理服務網址不會開啟APP的問題。
auto_translation	傳送推文連結時的自動翻譯設定，僅有使用 fx 時可以啟用（使用其他嵌入代理服務時會自動關閉）。開啟設定後預設將貼文翻譯成 trans_default_lang 設定的語言，詳細請參考 Translate Posts (X/Twitter)。

Note

如果需要支援更多嵌入代理服務，請透過 Issue 告訴我們。

訊息

參數	描述
default_message	全域設定預設的訊息格式，格式和自定義訊息相同，使用f-字串並支援4個特殊變數。相關細節請參考指令。
emoji_auto_format	對於自定義訊息，是否自動轉換短格式的表情符號，若是啟用，則支援使用如 :jerry: 的格式來使用當前伺服器的表情符號而不需要輸入完整名稱 <:jerry:720576643583836181>。

3. 運行機器人並邀請至你的伺服器

python bot.py

權限設定

🔧機器人權限設定（Permissions Integer）：2147666944

啟用	權限
✔️	讀取訊息 (Read Messages/View Channels)
✔️	發送訊息 (Send Messages)
✔️	嵌入連結 (Embed Links)
✔️	附加檔案 (Attach Files)
✔️	提及 @everyone、@here 和所有身分組 (Mention Everyone)
✔️	使用應用程式命令 (Use Slash Commands)

Note

請在 Discord Developer Portal 生成帶有預設權限的邀請連結，而不是邀請機器人進伺服器後才手動調整權限。

特權意圖設定

啟用	意圖
❌	成員狀態意圖 (Presence Intent)
❌	伺服器成員意圖 (Server Members Intent)
⚠️	訊息內容意圖 (Message Content Intent)

如果你在 configs.yml 中將 enable_prefix_commands_in_guild 禁用，則可禁用訊息內容意圖，反之，請啟用它。

Note

如果想將機器人架到伺服器上，這裡推薦一個基本免費的服務：fly.io。 (更新：fly.io已停止向新用戶提供免費的方案)

⚙️如果你使用fly.io的話你可能會需要的一些配置檔案

• dockerfile

FROM python:3.11.11
WORKDIR /bot
COPY requirements.txt /bot/
RUN pip install -r requirements.txt
COPY . /bot/
CMD python bot.py

• fly.toml

app = "你的APP名稱"
primary_region = "你的APP地區"

[env]
  DATA_PATH = "/data"

[mounts]
  source = "你的APP的VOLUME名稱"
  destination = "/data"

4. 玩得開心

現在你可以回到Discord，並使用 /add notifier 指令來設置你想要接收更新的Twitter用戶！

💪貢獻者

感謝所有貢獻者。

這個專案也受益於為我們提供標誌的藝術家的創意貢獻。