n1cat-discord-script-manager 🤖

一個為 Discord.js 設計的強大、靈活的腳本管理系統，讓您能夠動態地加載、執行和管理機器人腳本。

目錄 (Table of Contents)

• 快速上手 (Quick Start)
• 功能特性 (Features)
• 安裝 (Installation)
• API 參考 (API Reference)
  • ScriptManager
  • CommandHandler
  • EventHandler
• 貢獻 (Contributing)
• 授權協議 (License)

🚀 快速上手 (Quick Start)

這是一個最簡潔的範例，展示如何快速啟動一個具備動態腳本功能的 Discord 機器人。

// bot.js
const { Client, GatewayIntentBits } = require("discord.js");
const {
  ScriptManager,
  CommandHandler,
  EventHandler,
} = require("n1cat-discord-script-manager");
require("dotenv").config(); // 用於管理 TOKEN

// 1. 創建 Discord Client
const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.MessageContent,
  ],
});

// 2. 初始化核心模組
const commandHandler = new CommandHandler(client);
const scriptManager = new ScriptManager(client, {
  scriptFolder: "./scripts", // 您的腳本存放目錄
  allowedUsers: ["YOUR_DISCORD_USER_ID"], // 設置管理員 ID
});
const eventHandler = new EventHandler(client, commandHandler, scriptManager);

// 3. 設置 Ready 事件並啟動
client.once("ready", async () => {
  console.log(`✅ Logged in as ${client.user.tag}`);
  await scriptManager.loadScripts();
  await commandHandler.registerCommands(); // 可選: process.env.GUILD_ID
  console.log("🚀 Scripts and commands initialized!");
});

// 4. 啟動事件監聽
eventHandler.initialize();

// 5. 登入 Discord
client.login(process.env.DISCORD_TOKEN);

腳本範例 (./scripts/hello.js):

// scripts/hello.js
module.exports = async function (handler) {
  // `handler` 是一個 MessageHandler 實例
  if (handler.content === "!hello") {
    await handler.reply("Hello from a dynamic script!");
  }
};

✨ 功能特性 (Features)

• 🚀 動態腳本管理: 無需重啟機器人即可熱加載、重載和卸載腳本。
• 🛡️ 安全的沙箱執行: 腳本在獨立的 Worker-thread 中運行，防止惡意代碼影響主進程。
• ⚙️ 內建指令處理: 自動加載和註冊斜線指令 (/)。
• 🔧 高度可配置: 提供豐富的選項，如執行時間限制、用戶權限控制等。
• 📊 性能監控: 追蹤每個腳本的執行次數和平均執行時間。
• 📦 模組化設計: ScriptManager, CommandHandler, EventHandler 各司其職，結構清晰。

📦 安裝 (Installation)

npm install n1cat-discord-script-manager discord.js

環境要求:

• Node.js: v16.9.0 或更高版本
• Discord.js: v14.0.0 或更高版本

📚 API 參考 (API Reference)

ScriptManager

管理所有使用者上傳的腳本。

new ScriptManager(client, options)

• client: Discord.js 的 Client 實例。
• options:
  • scriptFolder (string): [必需] 存放腳本的資料夾路徑。
  • debug (boolean): 是否啟用詳細日誌。 (預設: false)
  • allowedUsers (string[]): 允許使用管理指令的用戶 ID 列表。 (預設: [])
  • maxExecutionTime (number): 腳本最大執行時間（毫秒）。 (預設: 5000)
  • maxScriptSize (number): 腳本檔案的最大大小（字節）。 (預設: 1024 * 1024)
  • onError (function): 自定義錯誤處理函數。

主要方法:

• async loadScripts(): 從 scriptFolder 加載所有腳本。
• async reloadScript(fileName): 重新加載指定的腳本。
• async addScript(fileName, content, metadata): 新增一個腳本。
• async deleteScript(fileName): 刪除一個腳本。
• getScriptStats(fileName): 獲取指定腳本的執行統計數據。

CommandHandler

處理應用程式指令（斜線指令）的加載、註冊和執行。

new CommandHandler(client, options)

• client: Discord.js 的 Client 實例。
• options:
  • debug (boolean): 是否啟用詳細日誌。 (預設: false)

主要方法:

• loadCommands(): 從內建的指令資料夾 (src/commands) 加載指令。
• async registerCommands(guildId): 向 Discord 註冊所有已加載的指令。如果提供了 guildId，則為伺服器內指令；否則為全域指令。
• async handleInteraction(interaction): 處理傳入的 interaction 事件，並執行對應的指令。

EventHandler

作為事件的中心樞紐，將 client 的事件分派給 CommandHandler 和 ScriptManager。

new EventHandler(client, commandHandler, scriptManager, options)

• client: Discord.js 的 Client 實例。
• commandHandler: CommandHandler 的實例。
• scriptManager: ScriptManager 的實例。
• options:
  • debug (boolean): 是否啟用詳細日誌。 (預設: false)

主要方法:

• initialize(): 綁定所有必要的 client 事件監聽器，例如 ready, interactionCreate, 和 messageCreate。這是啟動整個系統的關鍵。

🤝 貢獻 (Contributing)

我們歡迎任何形式的貢獻！請參考 CONTRIBUTING.md 以了解詳細資訊。

📄 授權協議 (License)

本專案採用 MIT License 授權。