A Discord.js plugin for dynamic script management and execution
npm install n1cat-discord-script-manager

一個為 Discord.js 設計的強大、靈活的腳本管理系統,讓您能夠動態地加載、執行和管理機器人腳本。
- 快速上手 (Quick Start)
- 功能特性 (Features)
- 安裝 (Installation)
- API 參考 (API Reference)
- ScriptManager
- CommandHandler
- EventHandler
- 貢獻 (Contributing)
- 授權協議 (License)
這是一個最簡潔的範例,展示如何快速啟動一個具備動態腳本功能的 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):
`javascripthandler
// scripts/hello.js
module.exports = async function (handler) {
// 是一個 MessageHandler 實例`
if (handler.content === "!hello") {
await handler.reply("Hello from a dynamic script!");
}
};
- 🚀 動態腳本管理: 無需重啟機器人即可熱加載、重載和卸載腳本。
- 🛡️ 安全的沙箱執行: 腳本在獨立的 Worker-thread 中運行,防止惡意代碼影響主進程。
- ⚙️ 內建指令處理: 自動加載和註冊斜線指令 (/)。ScriptManager
- 🔧 高度可配置: 提供豐富的選項,如執行時間限制、用戶權限控制等。
- 📊 性能監控: 追蹤每個腳本的執行次數和平均執行時間。
- 📦 模組化設計: , CommandHandler, EventHandler 各司其職,結構清晰。
`bash`
npm install n1cat-discord-script-manager discord.js
環境要求:
- Node.js: v16.9.0 或更高版本
- Discord.js: v14.0.0 或更高版本
管理所有使用者上傳的腳本。
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)
- : 獲取指定腳本的執行統計數據。
處理應用程式指令(斜線指令)的加載、註冊和執行。
new CommandHandler(client, options)
- client: Discord.js 的 Client 實例。options
- :debug
- (boolean): 是否啟用詳細日誌。 (預設: false)
主要方法:
- loadCommands(): 從內建的指令資料夾 (src/commands) 加載指令。async registerCommands(guildId)
- : 向 Discord 註冊所有已加載的指令。如果提供了 guildId,則為伺服器內指令;否則為全域指令。async handleInteraction(interaction)
- : 處理傳入的 interaction 事件,並執行對應的指令。
作為事件的中心樞紐,將 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.md 以了解詳細資訊。
本專案採用 MIT License 授權。