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”路径。

脚本 与 项目文件 的区别

可以简单记住：
脚本 = 你自己写代码；项目文件 .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，也欢迎在合适的场合向玩家或同行简单介绍它，
让更多人可以在不被繁琐环境配置束缚的前提下，把自己的玩法想法变成真正跑在服务器上的插件。