图片描述

ScriptIrc – 用智能体为你构建 Bukkit 插件

您只需要在网页中与 ScriptIrc 的智能体对话，描述您的玩法与需求。
智能体就会为您设计和生成一个完整的 Bukkit 插件项目（导出为项目文件）。
随后，服务器上的 ScriptIrc 编译插件就会将此项目编译成可加载的插件 JAR。

无需准备任何本地 IDE、构建工具或 JDK 项目模板
您主要专注于与智能体讨论“插件应该如何运作”
编译插件只负责“安全可靠地将智能体生成的项目转换为可运行的 Bukkit 插件”

注：本文档中，“智能体 + 编译插件”的组合统称为 ScriptIrc。
我们只在这里介绍主要功能和使用方法，不涉及底层实现细节。

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

打开 ScriptIrc 的聊天/项目界面（浏览器中访问 https://scriptirc.io/chat）并与智能体对话：
- 说明您的服务器类型、版本和已有插件生态
- 描述您想要的玩法、规则、命令
- 告诉智能体您期望的配置方式、权限和玩家体验
智能体基于对话创建或修改 Bukkit 插件项目：
- 规划 plugin.yml、命令、权限、依赖插件等
- 生成或调整核心逻辑代码及必要的资源文件
- 始终以“在服务器上作为 Bukkit 插件运行”为目标组织整个项目
当项目达到您满意的阶段时，在网页 UI 中点击 “导出插件项目 (.sirc)”，获得 .sirc 项目文件
将 .sirc 文件提供给服务器上的 ScriptIrc 编译插件：
- 使用编译命令将项目转为 Bukkit 插件 JAR
- 通过动态加载/重载部署或更新插件，无需重启服务器
后续想更改插件行为时，只需回到聊天界面，继续与智能体对话，导出新版本 .sirc 并重新编译即可

简单来说：浏览器中的智能体负责 “设计与编码”，服务器上的 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 <脚本名>`	编译 `scripts` 目录下的单文件 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/                     # 插件根数据目录
│
├── scripts/                           # 脚本与项目工作区，包含以下子目录：
│   ├── src/                          # 单文件 Java 脚本目录
│   │   └── 您可以在此编写脚本，通过 `/scriptirc compiler <脚本名>` 编译
│   ├── lib/                          # 自定义依赖库目录
│   │   └── 放入额外应参与编译的 JAR（如第三方 API），编译时自动加入 classpath
│   └── output/（默认配置为 scripts/output） # ScriptIrc 编译出的 JAR 插件输出目录
│       └── 命令如 `/scriptirc load <插件名>` 会从此处加载插件
│       └── Data/                     # 启用“数据文件夹重定向”时，此目录作为外部插件的数据根目录
│           └── 每个由 ScriptIrc 加载的插件将在此获得自己的数据子目录
│
├── messages/                         # 多语言消息文件目录，用于自定义日志与提示
│   └── 例如：zh_CN.properties、en_US.properties
│
└── 其他辅助目录与配置文件（例如 config.yml）

config.yml 可控制自动重载、日志级别、本地化等行为。大多数情况下默认配置已足够。

🔗 编译依赖解析机制

编译脚本或项目时，ScriptIrc 会自动构造一个“尽可能接近真实服务器环境”的编译 classpath，因此您大多数情况下无需手动管理依赖：

服务器端依赖
自动包含当前运行的 Minecraft 服务器核心（如 Spigot/Paper）提供的 API。
您可以直接在脚本中使用 Bukkit/Spigot API，无需额外配置。
ScriptIrc 内部依赖
ScriptIrc 内部附带了部分经过 shade 和 relocate 的第三方库（如 byte-buddy），这些库在编译时和运行时自动可用。
scripts/lib/ 下的自定义 JAR
如果您的脚本或项目需要额外的第三方库（例如 Vault API 或某个自定义 SDK），只需将对应的 JAR 放入 plugins/ScriptIrc/scripts/lib/，编译时它们会自动加入 classpath。
依赖诊断与修复建议
当编译因缺少依赖而失败时，可以使用：
```
/scriptirc compiler <插件名> fixreport
```
ScriptIrc 会分析编译错误，给出类似“可能缺少哪些依赖”的提示，帮助您决定应在 scripts/lib/ 下放入哪些 JAR，或如何调整脚本。

注意：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
描述整个项目的目录与文件的树状结构。
目录：对象（可多层嵌套）
文件：字符串，每个值再次经过 Base64gzip(file content) 编码
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 的公共在线构建器界面（具体 URL 可能随官方公告变化）。在这里您可以：

用自然语言描述玩法与规则，让 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” 路径。

⚖️ 脚本与项目文件的区别

项目	脚本（`.java` 文件）	项目文件（`.sirc`）
形式	单个 Java 源文件	完整项目快照，包含多个文件与配置
开发入口	直接在 `scripts/src` 下编写代码	通过在线编辑器的聊天与文件视图构建项目
复杂度	适合小功能、简单逻辑	适合中大型玩法和长期维护的插件
元数据管理	通过脚本内的字段或注释提供	由项目元数据集中管理
可移植性	需要手动打包或复制多个文件	单个 `.sirc` 文件承载完整项目
推荐场景	熟悉 Java 的用户编写辅助工具	主力服务器玩法与打算分享的插件
在 ScriptIrc 中的角色	补充性、轻量级	主要、核心格式

简单记忆：
脚本 = 您自己写代码；.sirc 项目文件 = 您与 ScriptIrc Engine 共同开发插件。

❓ 常见问题

Q1：使用 ScriptIrc 一定要懂 Java 吗？
不需要。
ScriptIrc 的主要功能集围绕 “项目 + .sirc” 工作流设计。
您主要通过自然语言和 UI 操作在在线编辑器中进行项目开发，由 ScriptIrc 协助处理代码与结构。
脚本仅为已熟悉 Java 的用户提供的额外入口。

Q2：为什么推荐使用 .sirc 而不是全部写成脚本？
.sirc 更利于复杂玩法和长期维护，具有完整的目录结构、配置与文档。
它更容易在多人、多环境间分享与迁移，也便于 ScriptIrc 管理版本和生成文档。
脚本更适合“小工具”。

Q3：编译失败该怎么办？

查看 ScriptIrc 返回的错误信息与服务器控制台日志。
对于脚本，可使用 /scriptirc compiler <脚本名> fixreport 获取依赖修复建议。
确认所需的所有第三方库都已放入 scripts/lib/。
对于项目，确认导出的 .sirc 文件未截断或损坏；必要时从在线编辑器重新导出。

Q4：ScriptIrc 无法通过 WebSocket 获取 .sirc 怎么办？
这通常意味着 ScriptIrc Engine 未连接到服务器的 WebSocket 服务，或当前无在线本地编译客户端。
您仍可从在线编辑器导出 .sirc 文件，手动上传到服务器，然后使用 /scriptirc compiler MyProject.sirc 进行编译。

Q5：我可以同时使用脚本和 .sirc 项目吗？
可以。
您可以在同一服务器上运行来自项目的插件和基于脚本的插件。
ScriptIrc 不强制您只选择一种方式。

📄 许可说明

ScriptIrc 目前以闭源形式提供。
插件的具体使用条款、商业许可与限制以作者最新官方声明为准。

未经授权，请勿对 ScriptIrc 进行反编译、重新分发或超出允许的商业范围使用。
如需商业合作或更深度的集成，请通过指定渠道联系作者。

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

🙏 致谢

感谢 Minecraft / Bukkit / Spigot / Paper 社区长期维护其生态与文档。
感谢参与 ScriptIrc 测试与反馈的服主、开发者与玩家；您的建议直接推动了系统的进步。
如果您正在使用 ScriptIrc，欢迎在适当场合向玩家或同行简要介绍它，让更多人不必被繁琐的环境搭建阻挡，将玩法想法变成服务器上真实运行的插件。

现在就开始，用对话创造您的专属插件吧！
👉 https://scriptirc.io/chat

Overview