n1cat-discord-script-manager 🤖

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

目錄 (Table of Contents)

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

🚀 快速上手 (Quick Start)

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

``javascript
// 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):

`javascript
// 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)

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

環境要求:

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

📚 API 參考 (API Reference)

$3

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

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): 獲取指定腳本的執行統計數據。

$3

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

new CommandHandler(client, options)

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

主要方法:

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

$3

作為事件的中心樞紐，將 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 授權。