使用教學與指令表

一、邀請機器人與權限

需要在該伺服器擁有「管理伺服器」權限才能邀請。按上方「邀請機器人」，選擇伺服器並保留預設勾選的權限後授權即可。已經邀請過的伺服器，用同一個連結重新授權一次就能補上新權限。

選用：若希望揪團或公告能通知「不可被提及」的身分組或 @everyone，請另外為機器人開啟「提及所有人」權限。

邀請完成後，管理員可以在 Discord 輸入 /setup 打開設定精靈，一次設好揪團頻道、自動語音房、遊戲偏好身分組面板，並檢查上表權限是否齊全。任何人都可以輸入 /help 看互動教學。

二、調整身分組順序（很重要）

1. 開啟「伺服器設定 → 身分組」。
2. 找到機器人的身分組（通常叫做「桌伴 TableMate」），把它拖到所有玩家身分組的上方，然後儲存。
3. 回到控制台的「總覽」確認沒有權限警告；總覽也會顯示機器人目前的最高身分組。

三、開始一局遊戲

1. 建立場次在想開局的文字頻道輸入 /game create，mode 選「狼人殺」「阿瓦隆」「血染鐘樓」「誰是臥底」「間諜地點」「窺探」「狼人真言」「一夜終極狼人」「滲透任務」「月會」或「自由模式」，name（場次名稱）可不填。機器人會發出大廳面板，並建立 🎲 場次名稱 分類與遊戲頻道（只有你看得到的回覆裡有各頻道連結）。
2. 玩家報名玩家在大廳面板按「✋ 加入」，想退出就按「🚪 離開」。每個人同時只能參加一個場次。
3. 調整設定（GM 遊戲）主持人按「⚙️ 遊戲設定」：
   • 狼人殺：使用預設配套，或自訂狼人與各神職數量。
   • 阿瓦隆：勾選要加入的派西維爾、莫甘娜、莫德雷德、奧伯倫。
   • 血染鐘樓：必須選出說書人（需已加入場次），角色可隨機或手動選擇。
   • 誰是臥底：選臥底／白板人數（預設依人數自動）與每輪討論時間。
   • 間諜地點：選討論分鐘數。
   • 窺探：選題目難度、問答時間與猜中後的討論時間。
   • 狼人真言：選咒語難度與問答時間。
   • 一夜終極狼人、月會：選白天討論時間（牌組與角色依人數自動配置）。
   • 滲透任務：不需設定，任務人數依人數自動套用。
4. 開始遊戲主持人按「▶️ 開始遊戲」（或輸入 /game start，加上 shuffle:True 可隨機座號）。機器人會分配座號、修改暱稱，並在 ⚡行動 頻道邀請大家進入 🔊 語音交流。人數或設定不符時會提示原因。
5. 進行遊戲到 ⚡行動 頻道使用遊戲面板：「🔍 查看身分」看自己的角色，「⚡ 行動」執行夜晚技能或組隊，投票時到投票訊息選擇。身分與行動都是「只有你看得到」的訊息，不需要開私訊。主持人用「⏭️ 下一階段」推進流程。誰是臥底按「查看密語」、間諜地點按「查看身分」看自己的詞或地點，面板會顯示討論倒數，主持人可延長 1 分鐘或提早投票。窺探、狼人真言、一夜終極狼人、滲透任務、月會會把身分與夜晚結果私訊給你；收不到私訊時按面板上的「查看身分」一樣能看到，提問與猜詞則用跳出的表單輸入。
6. 結束遊戲結束時面板會出現「🔁 再來一局」與「🏁 結束並還原暱稱」。也可以隨時輸入 /game end 結束：還原所有暱稱、刪除遊戲頻道，📜行動紀錄 封存到 🗂️ 遊戲紀錄。

自由模式不會有 GM 面板，開始後由主持人用 /game status、/game tag 或控制台手動更新玩家狀態。

這些指令可以在建立場次的頻道，或該場次自動建立的任何頻道中使用。

四、指令總表

「主持人」指建立場次的人；擁有「管理暱稱」權限的成員也能使用主持人指令。

名單用空白、逗號或頓號分隔，例如 /tool teams teams:2 choices:小明 小華 阿美 阿傑。

範例：/lfg create game:阿瓦隆 slots:8 time:週六 19:30 place:DC 語音 note:新手友善 ping:@桌遊

主揪快速上手

1. 發團在想揪人的文字頻道輸入 /lfg create，在表單填好遊戲、時間、人數、地點／費用與備註後送出。時間寫成「今晚 9 點」「週六 19:30」「10/5 20:00」這類格式，機器人才會在開始前自動提醒；送出後只有你看得到的回覆會顯示機器人解讀到的時間。
2. 等大家報名成員按「報名」或「+1 帶朋友」。額滿後再報名的人會自動排進候補，有人取消時由候補依序遞補，並通知被遞補的人，不需要你手動處理。
3. 用主揪工具管理按揪團訊息上的「主揪工具」，可以編輯內容、成團／截止報名、建立成員討論串、通知成員、移除成員、點名、存成模板、結束或取消。只有主揪與擁有「管理訊息」權限的管理員能打開。
4. 成團第一次額滿或你按「成團／截止報名」時，機器人會自動開一個只有成員看得到的私人討論串，把大家拉進去討論細節。
5. 開始前機器人依設定在討論串 @ 所有成員並私訊提醒；如果人數還沒滿，會另外私訊你還差幾人。
6. 開打遊戲是阿瓦隆、狼人殺、血染鐘樓、誰是臥底、間諜地點、窺探、狼人真言、一夜終極狼人、滲透任務或月會時，主揪工具會出現「開遊戲房」，一鍵開好機器人遊戲場次並把成員加進去，接著照 開始一局遊戲 進行。要語音的話按「開團員語音房」，機器人會開一間只有成員能進的語音頻道並通知大家。
7. 下次再揪在主揪工具按「存成模板」，下次輸入 /lfg create template:模板名稱 就會帶入同樣的內容。

五、使用網頁控制台

1. 開啟 控制台，按「使用 Discord 登入」並授權（只會讀取你的基本資料與伺服器列表）。
2. 在「選擇伺服器」挑一個你擁有「管理伺服器」權限的伺服器；還沒邀請機器人的伺服器會顯示「邀請機器人」按鈕。
3. 左側選單切換：總覽（機器人是否在線、延遲）、遊戲場次、揪團（發團、看名單與候補、成團或取消）、揪團範本、發送公告、設定（揪團頻道與提醒、開放的遊戲、指令開關）。遊戲場次頁每 5 秒、揪團頁每 10 秒自動同步。
4. 用完按右上角「登出」。從桌伴網站登入時，登入狀態只保存在目前這個分頁。

如果看到「尚未連接機器人後端」或「無法連線到控制台後端」，代表機器人目前沒有連上網站，Discord 內的指令可能也暫時無法使用；請稍後再試，或請機器人管理者依 網頁控制台設定 檢查。

六、網頁控制台設定（給機器人管理者）

桌伴網站只提供控制台的網頁畫面，實際動作由你電腦上的機器人執行（預設 http://localhost:8080）。完整的逐步教學在機器人資料夾的 DASHBOARD_SETUP.md，不確定哪裡沒設好時執行 .\.venv\Scripts\python tools\check_dashboard.py --online，它會列出下一步（不會顯示任何密碼）。

1. 先在本機用Discord Developer Portal → 應用程式 → OAuth2 → Redirects 新增 http://localhost:8080/callback，在 .env 填 DISCORD_CLIENT_SECRET，重新啟動機器人（建議用 tools\start_all.bat，當機會自動重開），再開 http://localhost:8080 登入。
2. 取得固定的 https 網址擇一：Cloudflare 具名通道（網域 DNS 需在 Cloudflare，執行 tools\setup_named_tunnel.bat 建立例如 https://bot-api.tablematetw.com）；Tailscale Funnel（不用改網域，以系統管理員身分執行 tailscale funnel --bg 8080）；或只想試用時用 tools\start_dashboard_tunnel.bat 的臨時網址（每次重開都會變）。
3. 設定機器人的 .env 並重新啟動

   DASHBOARD_URL=https://你的網址
   DASHBOARD_FRONTEND_URL=https://tablematetw.com/dcbot/dashboard/
   DASHBOARD_ALLOWED_ORIGINS=https://www.tablematetw.com,https://tablemate-82533.web.app,https://tablemate-82533.firebaseapp.com

4. 新增第二個 Redirect在 OAuth2 → Redirects 再加 https://你的網址/callback（本機的保留）並儲存。打開 https://你的網址/api/health 看到 "ok": true 代表通道已通。
5. 先測試開啟 https://tablematetw.com/dcbot/dashboard/?api=https://你的網址 登入看看；這只影響你的瀏覽器，按上方提示條的「改回網站預設」即可取消。
6. 正式啟用把網站 /dcbot/dashboard/config.js 的 window.DCBOT_API 改成同一個網址（結尾不要加 /）並部署網站；想開機自動啟動機器人，執行 tools\register_autostart.bat。

安全性：跨網域登入使用一次性、60 秒內有效的登入代碼換取 Bearer token，只會導回上面允許的網址；API 的 CORS 也只開放給這些來源，登出時 token 立即失效。