![hszjj.png](m-attach://695838005809caa601d903e7) # ScriptIrc - 让 Agent 帮你生成 Bukkit 插件你只需要在网页里和 ScriptIrc 的智能 Agent 对话，描述玩法和需求，Agent 会为你设计和产出一个完整的 Bukkit 插件项目（导出为 `.sirc` 项目文件）；然后，再由你服务器上的 ScriptIrc 编译器插件把这个项目编译成可加载的插件 JAR。 - 不需要在本地安装 IDE、构建工具或 JDK 工程模板 - 你的主要精力用来和 Agent 讨论“插件应该怎样实现，工作” - 编译器插件只负责“把 Agent 生成的项目安全、稳定地变成可运行的 Bukkit 插件” > 说明：本文以“Agent + 编译器插件”这一整体能力统称为 **ScriptIrc**，只介绍主要功能和使用方式，不展开底层实现细节。 --- ## 从想法到 Bukkit 插件：ScriptIrc 的整体流程 1. 在浏览器中打开 ScriptIrc 的聊天/项目界面（`https://scriptirc.io/chat`），与 Agent 对话： - 说明服务器类型、版本和已有插件生态； - 描述你希望实现的玩法、规则和指令； - 告诉 Agent 你期望的配置方式、权限控制以及玩家体验。 2. Agent 会基于你的对话创建/修改一个 **Bukkit 插件项目**： - 规划 `plugin.yml`、命令、权限、依赖插件等； - 生成或调整核心逻辑代码和必要的资源文件； - 让整个项目始终围绕“在服务器上作为 Bukkit 插件运行”这一目标。 3. 当项目达到你满意的阶段，在网页中点击“导出插件项目（.sirc）”，得到一个 `.sirc` 项目文件。 4. 把 `.sirc` 提供给服务器上的 ScriptIrc 编译器插件： - 使用编译命令把 `.sirc` 项目编译为 Bukkit 插件 JAR； - 通过动态加载/重载，在不重启服务器的前提下上线或更新插件。 5. 如果后续想修改插件行为，只需回到聊天界面继续和 Agent 对话，再导出新版本 `.sirc`，重新编译即可。 > 简单说：**网页里的 Agent 负责“想和写”，服务器上的 ScriptIrc 负责“编和载”。** --- ## 安装说明：安装 ScriptIrc 编译器插件 1. 从作者提供的渠道获取 **最新版本 ScriptIrc 编译器插件 JAR**。 2. 将该 JAR 文件放入服务器的 `plugins/` 目录（例如 `plugins/ScriptIrc-x.x.x.jar`）。 3. 启动或重启服务器。 4. 在服务器控制台或游戏内（有权限的账号）执行命令，确认插件已加载，例如： - `/scriptirc help` 或 - `/si help`（如果配置了简写别名） 5. 首次启动后，插件会在 `plugins/ScriptIrc/` 下自动生成默认配置、脚本目录和相关资源。 > ScriptIrc 只依赖正在运行的 Minecraft 服务器自身环境，无需你再单独搭建任何本地 Maven/Gradle 项目或 IDE 工程。 --- ## 编译器命令介绍 > 以下命令示例以 `/scriptirc` 作为主命令，部分环境可使用别名 `/si`。 ### 基本管理命令 - `/scriptirc help` 显示帮助信息与可用子命令列表。 - `/scriptirc list` 列出当前由 ScriptIrc 管理的外部插件列表。 - `/scriptirc load <插件名或JAR文件名>` 从 ScriptIrc 的外部插件目录中加载指定插件。 - `/scriptirc unload <插件名>` 卸载指定外部插件。 - `/scriptirc reload <插件名>` 重新加载指定外部插件（等价于先卸载后再加载）。 ### 编译相关命令 - `/scriptirc compiler <脚本名>` 编译位于脚本目录中的 **单文件 Java 脚本**（`.java`）。 - 例如：`/scriptirc compiler HelloWorld` 或 `/scriptirc compiler HelloWorld.java` - `/scriptirc compiler <脚本名> fixreport` 在编译失败时生成依赖修复建议报告，帮助你定位缺失的库或错误的依赖设置。 - `/scriptirc compiler <项目名>.sirc` 直接从本地 `.sirc` 项目文件进行解包与编译。 - 例如：`/scriptirc compiler MyProject.sirc` - `/scriptirc compiler sirc:<会话ID>` 通过 ScriptIrc Engine WebSocket 从在线会话中拉取 `.sirc` 项目并编译。 - 例如：`/scriptirc compiler sirc:123456` - 适合你在在线编辑端完成项目后，直接在服务器上按会话 ID 编译最新版本。 ### 项目浏览与调试命令 - `/scriptirc search <类名>` 或 `/scriptirc findclass <类名>` 在当前服务器与依赖库中搜索指定类的完整包路径，用于帮助你确认依赖是否存在。 - `/scriptirc sirctree <项目名>` 在不解包到磁盘的前提下，查看指定 `.sirc` 项目的虚拟目录结构，快速了解项目内部文件布局。 ### 其它实用命令 - `/ai-builder` 在游戏内输出一个可点击的链接，引导玩家或管理员打开 ScriptIrc 的在线构建器页面（例如 `http://scriptirc.io/`），用于图形化/对话式创建与编辑项目。 > 实际可用命令和参数可能随版本演进略有调整，请以插件内 `/scriptirc help` 返回的信息为准。 --- ## 编译器目录结构安装并首次运行 ScriptIrc 后，插件会在 `plugins/ScriptIrc/` 下创建一套标准目录结构。常用目录说明如下： - `plugins/ScriptIrc/` 插件数据根目录。 - `plugins/ScriptIrc/scripts/` **脚本与项目工作区**，包含以下子目录： - `src/` - 放置 **单文件 Java 脚本** 的目录。 - 你可以在这里编写脚本，然后通过 `/scriptirc compiler <脚本名>` 编译。 - `lib/` - 自定义依赖库目录。 - 将额外需要参与编译的 JAR（如第三方 API）放在这里，编译时会一并加入 classpath。 - `output/`（默认配置为 `scripts/output`） - ScriptIrc 编译完成后输出的插件 JAR 目录。 - `/scriptirc load <插件名>` 等命令会从这里加载插件。 - `plugins/ScriptIrc/scripts/output/Data/` 当启用“数据文件夹重定向”功能时，用作外部插件的数据根目录：每个由 ScriptIrc 加载的外部插件都会在此目录下获得自己的数据子目录。 - `plugins/ScriptIrc/messages/` 多语言消息文件目录，便于定制日志与提示文本（例如 `zh_CN.properties` / `en_US.properties`）。 - 其他辅助目录与配置文件（如 `config.yml` 等） - 控制自动重载、日志级别、多语言等行为。 - 一般默认配置即可满足大部分服务器使用。 --- ## 编译器如何获取依赖？在编译脚本或 `.sirc` 项目时，ScriptIrc 会自动构建一条“尽可能接近真实服务器环境”的编译 classpath，以减少你手动处理依赖的负担： 1. **服务器自身依赖** - 自动包含当前正在运行的 Minecraft 服务器核心（如 Spigot/Paper）所提供的 API。 - 你在脚本中直接使用 Bukkit/Spigot API，无需额外配置。 2. **ScriptIrc 自身依赖** - ScriptIrc 内部已经打包并重定位（shade）部分第三方库（如 `byte-buddy` 等），在编译和运行时自动可用。 3. **`scripts/lib` 目录中的自定义 JAR** - 如果你的脚本或项目需要额外的第三方库（例如 Vault API、某些自定义 SDK），只需将对应 JAR 放入 `plugins/ScriptIrc/scripts/lib/`，编译时会自动加入 classpath。 4. **依赖诊断与修复建议** - 当编译失败且错误与缺失依赖相关时，可以使用： - `/scriptirc compiler <插件名> fixreport` - ScriptIrc 会分析编译错误并给出“可能缺失哪些依赖”的提示，帮助你决定应将哪些 JAR 放入 `scripts/lib/` 或调整脚本用法。 > ScriptIrc 不会自动从互联网下载依赖，它只会基于当前服务器环境和 `scripts/lib` 中的内容来构建编译依赖链。 --- ## 编译器支持的两种格式：`.java` / `.sirc` ScriptIrc 编译器可以处理 **两种来源的输入**： - **`.java`**：单文件 Java 脚本（脚本文件） - **`.sirc`**：项目文件（完整插件工程的打包格式）在 ScriptIrc 的术语中： - **“脚本” 特指 `.java` 源码文件** - **“项目文件” 或 “项目” 特指 `.sirc` 文件** 下面分别介绍两种格式的特点与推荐用法。 --- ### `.sirc` 项目文件（项目文件，主线格式） #### `.sirc` 是什么？ - `.sirc` 是 ScriptIrc 的 **项目打包格式**，由在线编辑端统一导出。 - 在 ScriptIrc 在线界面中，你可以在“文件”标签页底部点击“导出插件项目（.sirc）”，浏览器会下载一个以当前项目名命名的 `.sirc` 文件。 - `.sirc` 本质上是： - 一段 Base64 编码的 JSON 文本； - JSON 中包含： - `fileSystem`：虚拟文件系统目录树 - `metadata`：项目元信息（项目名、版本、依赖、命令等） > 形式化地说： > `.sirc` = Base64( JSON({ fileSystem, metadata }) ) #### `.sirc` 内部大致长什么样？ - `fileSystem` - 以树结构描述整个项目的目录与文件。 - 目录：对象（多级嵌套）； - 文件：字符串，内容为 `gzip(文件内容)` 再经过 Base64 编码。 - `metadata` - 包含项目名称、描述、目标游戏版本、版本号、依赖插件列表、命令与权限等。 - 这些元数据会在编译时被映射到 `plugin.yml` 等配置中。解码流程总体为： 1. 读取 `.sirc` 文本 2. Base64 解码得到 JSON 字符串 3. 解析 JSON 得到 `fileSystem` 与 `metadata` 4. 递归遍历 `fileSystem`，对每个文件节点执行 “Base64 解码 → gzip 解压 → 写入磁盘” 在 ScriptIrc 内部，由专门的解码器负责这一过程，你通常无需手动操作。 #### `.sirc` 的使用方式 - **项目开发主路径** - 在线端中，你围绕某个玩法或功能创建“项目”，按模块拆分文件和配置。 - 当项目达到你满意的阶段，就导出为 `.sirc`。 - **在服务器上编译 `.sirc`** - 将 `.sirc` 文件放到 ScriptIrc 可访问的位置，使用例如： - `/scriptirc compiler MyProject.sirc` - 或通过会话 ID 直接从在线 Engine 拉取并编译： - `/scriptirc compiler sirc:<会话ID>` - **项目迁移与分享** - `.sirc` 是可以在不同环境之间流转的独立文件： - 你可以将它备份、分享给他人或在另一台服务器上重新编译。 #### 在线编辑端 `scriptirc.io/chat` `scriptirc.io/chat` 是 ScriptIrc 对外提供的在线构建界面（具体地址以作者最新公布为准）。在这里你可以： - 以对话的方式描述玩法和规则，由 AI 协助生成与调整工程结构和代码； - 管理虚拟文件系统（增删改文件、预览内容）； - 配置项目元信息（名称、版本、依赖、命令、权限等）； - 一键导出 `.sirc` 项目文件，供服务器端 ScriptIrc 编译使用。简单理解：**你在网页里做“项目”，在服务器里用 ScriptIrc 编译 `.sirc`。** --- ### `.java` 脚本文件（脚本，补充格式）在 ScriptIrc 中，**只有 `.java` 源码文件才被称为“脚本”**。脚本是相对于 `.sirc` 项目文件的“轻量级入口”，适合熟悉 Java 的用户手动快速实现小功能。 #### 脚本放在哪里？ - 服务器路径：`plugins/ScriptIrc/scripts/src/` - 在该目录中，每一个 `.java` 文件都可以视作一个独立脚本。 - 当前设计要求：**一个脚本 = 一个源码文件**，请不要将逻辑拆成多个源码文件。 #### 脚本需要满足什么结构？（以下是脚本开发规范的要点汇总，完整细节请参考仓库中的脚本开发指南文档） - 脚本主类需继承自 `JavaPlugin`，是一个标准的 Bukkit/Spigot 插件主类。 - 你可以通过两种方式提供元数据（用于生成 `plugin.yml`）： 1. **静态字段方式**：如 `VERSION`、`DESCRIPTION`、`AUTHOR`、`COMMANDS`、`PERMISSIONS` 等； 2. **注释方式**：在类的 JavaDoc 中使用 `@pluginName`、`@version`、`@description`、`[command]...[/command]`、`[permission]...[/permission]` 等标签。 - 命令与权限可以通过数组字段或注释标签统一声明，ScriptIrc 会自动在生成的 `plugin.yml` 中填充。 #### 如何编译与加载脚本？ - 编译脚本： - `/scriptirc compiler <脚本文件名>` - 例如：`/scriptirc compiler HelloWorld.java` 或 `/scriptirc compiler HelloWorld` - 编译失败时获取依赖建议： - `/scriptirc compiler <脚本文件名> fixreport` - 加载编译后的插件： - `/scriptirc load <插件名>` - 例如：`/scriptirc load HelloWorld` > 相比 `.sirc` 项目，脚本更适合作为 **手写小工具 / 快速验证某个想法** 的途径。 > 对于完整玩法与长期维护的内容，推荐使用“项目 + `.sirc`”路径。 --- ## 脚本与项目文件的区别 | 对比项 | 脚本（`.java` 文件） | 项目文件（`.sirc`） | |------------------|---------------------------------------------|-------------------------------------------------------------| | 形态 | 单个 Java 源码文件 | 含多文件、多配置的完整工程快照 | | 开发入口 | 直接在 `scripts/src` 中写代码 | 在在线编辑端通过对话与文件视图构建项目 | | 复杂度 | 适合小功能、简单逻辑 | 适合中大型玩法、长期维护的插件 | | 元数据管理 | 由脚本中的字段或注释提供 | 由项目 `metadata` 集中管理 | | 可迁移性 | 需手动打包或复制多个文件 | `.sirc` 单文件即可携带完整工程 | | 推荐使用场景 | 熟悉 Java 的开发者手写辅助脚本 | 服务器玩法主项目、对外分享的正式插件 | | 在 ScriptIrc 中的定位 | **补充、偏精简** | **主要、核心形态** | > 可以简单记住： > **脚本 = 你自己写代码；项目文件 `.sirc` = 你和 ScriptIrc Engine 一起开发一个插件。** --- ## 常见问题（FAQ） ### Q1：必须会写 Java 才能用 ScriptIrc 吗？ **不必须。** ScriptIrc 的主线功能是围绕“项目 + `.sirc`”设计的，你可以主要在在线端通过自然语言与界面操作完成项目开发，由 ScriptIrc 协助处理代码和结构。脚本只是为熟悉 Java 的用户提供的额外入口。 ### Q2：为什么推荐优先使用 `.sirc` 项目，而不是全部写脚本？ - `.sirc` 更适合复杂玩法与长期维护：有完整目录结构、配置和说明。 - 它更易于在多人之间分享和迁移，也更便于 ScriptIrc 做版本管理和说明生成。 - 脚本更适合作为“小工具”。 ### Q3：编译失败时该怎么办？ 1. 查看 ScriptIrc 返回的错误信息与服务器控制台日志。 2. 如果是脚本，可以使用 `/scriptirc compiler <脚本名> fixreport` 获取依赖修复建议。 3. 检查你是否已经把需要的第三方库放入 `scripts/lib/`。 4. 对 `.sirc` 项目，确认导出文件没有被截断或损坏，必要时重新在在线端导出一次。 ### Q4：提示无法通过 WebSocket 获取 `.sirc` 项目？ - 说明 ScriptIrc Engine 未连接到服务器提供的 WebSocket 服务，或当前没有在线的本地编译器客户端。 - 你仍然可以先从在线端导出 `.sirc` 文件，再手动上传到服务器后使用 `/scriptirc compiler MyProject.sirc` 编译。 ### Q5：可以同时使用脚本和 `.sirc` 项目吗？可以。你可以在同一台服务器上既使用 `.sirc` 项目编译出来的正式插件，也能通过纯脚本形式编译插件。ScriptIrc 不限制你只选其中一种方式。 --- ## 许可 ScriptIrc 当前以 **闭源形式** 提供，插件与相关服务的具体使用条款、商业授权与限制以作者发布的最新说明为准。 - 未经授权，请不要擅自反编译、二次分发或用于超出授权范围的商业用途。 - 如需商用合作或深度集成，请通过作者指定渠道联系。 > 本文档仅作为使用说明，不构成法律意义上的完整许可协议。 --- ## 鸣谢 - 感谢 Minecraft / Bukkit / Spigot/Paper 社区长期维护的生态与文档。 - 感谢参与 ScriptIrc 内测与反馈的服务器主、开发者与玩家，你们的建议直接推动了系统的改进。如果你正在使用 ScriptIrc，也欢迎在合适的场合向玩家或同行简单介绍它，让更多人可以在不被繁琐环境配置束缚的前提下，把自己的玩法想法变成真正跑在服务器上的插件。