ScriptIrc - 让 Agent 帮你生成 Bukkit 插件

你只需要在网页里和 ScriptIrc 的智能 Agent 对话，描述玩法和需求，Agent 会为你设计和产出一个完整的 Bukkit 插件项目（导出为 .sirc 项目文件）；然后，再由你服务器上的 ScriptIrc 编译器插件把这个项目编译成可加载的插件 JAR。

不需要在本地安装 IDE、构建工具或 JDK 工程模板
你的主要精力用来和 Agent 讨论“插件应该怎样实现，工作”
编译器插件只负责“把 Agent 生成的项目安全、稳定地变成可运行的 Bukkit 插件”

说明：本文以“Agent + 编译器插件”这一整体能力统称为 ScriptIrc，只介绍主要功能和使用方式，不展开底层实现细节。

从想法到 Bukkit 插件：ScriptIrc 的整体流程

在浏览器中打开 ScriptIrc 的聊天/项目界面（https://scriptirc.io/chat），与 Agent 对话：
- 说明服务器类型、版本和已有插件生态；
- 描述你希望实现的玩法、规则和指令；
- 告诉 Agent 你期望的配置方式、权限控制以及玩家体验。
Agent 会基于你的对话创建/修改一个 Bukkit 插件项目：
- 规划 plugin.yml、命令、权限、依赖插件等；
- 生成或调整核心逻辑代码和必要的资源文件；
- 让整个项目始终围绕“在服务器上作为 Bukkit 插件运行”这一目标。
当项目达到你满意的阶段，在网页中点击“导出插件项目（.sirc）”，得到一个 .sirc 项目文件。
把 .sirc 提供给服务器上的 ScriptIrc 编译器插件：
- 使用编译命令把 .sirc 项目编译为 Bukkit 插件 JAR；
- 通过动态加载/重载，在不重启服务器的前提下上线或更新插件。
如果后续想修改插件行为，只需回到聊天界面继续和 Agent 对话，再导出新版本 .sirc，重新编译即可。

简单说：网页里的 Agent 负责“想和写”，服务器上的 ScriptIrc 负责“编和载”。

安装说明：安装 ScriptIrc 编译器插件

从作者提供的渠道获取 最新版本 ScriptIrc 编译器插件 JAR。
将该 JAR 文件放入服务器的 plugins/ 目录（例如 plugins/ScriptIrc-x.x.x.jar）。
启动或重启服务器。
在服务器控制台或游戏内（有权限的账号）执行命令，确认插件已加载，例如：
- /scriptirc help 或
- /si help（如果配置了简写别名）
首次启动后，插件会在 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，以减少你手动处理依赖的负担：

服务器自身依赖
- 自动包含当前正在运行的 Minecraft 服务器核心（如 Spigot/Paper）所提供的 API。
- 你在脚本中直接使用 Bukkit/Spigot API，无需额外配置。
ScriptIrc 自身依赖
- ScriptIrc 内部已经打包并重定位（shade）部分第三方库（如 byte-buddy 等），在编译和运行时自动可用。
scripts/lib 目录中的自定义 JAR
- 如果你的脚本或项目需要额外的第三方库（例如 Vault API、某些自定义 SDK），
  只需将对应 JAR 放入 plugins/ScriptIrc/scripts/lib/，编译时会自动加入 classpath。
依赖诊断与修复建议
- 当编译失败且错误与缺失依赖相关时，可以使用：
  - /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 等配置中。

解码流程总体为：

读取 .sirc 文本
Base64 解码得到 JSON 字符串
解析 JSON 得到 fileSystem 与 metadata
递归遍历 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：编译失败时该怎么办？

查看 ScriptIrc 返回的错误信息与服务器控制台日志。
如果是脚本，可以使用 /scriptirc compiler <脚本名> fixreport 获取依赖修复建议。
检查你是否已经把需要的第三方库放入 scripts/lib/。
对 .sirc 项目，确认导出文件没有被截断或损坏，必要时重新在在线端导出一次。

Q4：提示无法通过 WebSocket 获取 `.sirc` 项目？

说明 ScriptIrc Engine 未连接到服务器提供的 WebSocket 服务，或当前没有在线的本地编译器客户端。
你仍然可以先从在线端导出 .sirc 文件，再手动上传到服务器后使用 /scriptirc compiler MyProject.sirc 编译。

Q5：可以同时使用脚本和 `.sirc` 项目吗？

可以。
你可以在同一台服务器上既使用 .sirc 项目编译出来的正式插件，也能通过纯脚本形式编译插件。ScriptIrc 不限制你只选其中一种方式。

许可

ScriptIrc 当前以 闭源形式 提供，插件与相关服务的具体使用条款、商业授权与限制以作者发布的最新说明为准。

未经授权，请不要擅自反编译、二次分发或用于超出授权范围的商业用途。
如需商用合作或深度集成，请通过作者指定渠道联系。

本文档仅作为使用说明，不构成法律意义上的完整许可协议。

鸣谢

感谢 Minecraft / Bukkit / Spigot/Paper 社区长期维护的生态与文档。
感谢参与 ScriptIrc 内测与反馈的服务器主、开发者与玩家，你们的建议直接推动了系统的改进。

如果你正在使用 ScriptIrc，也欢迎在合适的场合向玩家或同行简单介绍它，
让更多人可以在不被繁琐环境配置束缚的前提下，把自己的玩法想法变成真正跑在服务器上的插件。