n1cat-discord-script-manager/README.md

A Discord.js plugin for dynamic script management and execution

[![NPM version](https://img.shields.io/npm/v/n1cat-discord-script-manager.svg)](https://www.npmjs.com/package/n1cat-discord-script-manager)
[![NPM downloads](https://img.shields.io/npm/dm/n1cat-discord-script-manager.svg)](https://www.npmjs.com/package/n1cat-discord-script-manager)

# n1cat-discord-script-manager 🤖

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

## 目錄 (Table of Contents)

- [快速上手 (Quick Start)](#-快速上手-quick-start)
- [功能特性 (Features)](#-功能特性-features)
- [安裝 (Installation)](#-安裝-installation)
- [API 參考 (API Reference)](#-api-參考-api-reference)
  - [`ScriptManager`](#scriptmanager)
  - [`CommandHandler`](#commandhandler)
  - [`EventHandler`](#eventhandler)
- [貢獻 (Contributing)](#-貢獻-contributing)
- [授權協議 (License)](#-授權協議-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)

### `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](CONTRIBUTING.md) 以了解詳細資訊。

## 📄 授權協議 (License)

本專案採用 [MIT License](LICENSE) 授權。