面向 Minecraft 插件的「全平台端到端测试编排」Gradle 插件 + 配套脚手架模板：把真实服务端/代理拉起、互联成测试拓扑，用机器人驱动端到端场景、判定结果并收尾，统一各插件五花八门的 E2E 做法。
v0.5.1，发布到 maven.wcpe.top。自举实机 E2E 覆盖全矩阵——单服(±bot) / 经代理（Waterfall·BungeeCord·Velocity）/ 集群 / 压测 / 单场景多 bot / 崩溃接管 / Folia 后端，CI 实机跑通；节点运行时注入（FR-20）已通过 Beacon 真实 BungeeCord 消费验证。能力与进度以 docs/PRD.md §4 FR 表状态列为准。
三层协作（详见 docs/ARCHITECTURE.md）：
- Gradle 编排插件（本仓库核心，
top.wcpe.mc-testkit）：内置下载并运行 Paper/Folia 后端与 Velocity/Waterfall/BungeeCord 代理（下载/运行模块自实现，不外挂第三方下载库，见 ADR-0001）；用mcTestkit { }DSL 声明「代理 + 多后端」拓扑，自动注册 prepare / 启动 bot / runServer / proxy / cluster / stress / verify / 缓存回写等任务，并固化已知环境契约。 - 服务端桩插件（随项目，模板提供骨架）：装备入服玩家、按场景驱动、与 bot 收发控制消息、判定结果写结果文件。
- mineflayer 机器人（随项目，模板提供内核）：模拟真实玩家入服，驱动购买/交互等端到端场景。
- 一行 DSL 声明并拉起「单后端」「代理 + N 后端」测试拓扑。
- 多后端集群（bot 经代理
/server跨服切换、桩跨服判定；代理 listenerpriorities含全部后端，默认后端宕机时 bot 重连回退到存活后端，支撑「崩溃接管」类 E2E，FR-15）与多后端持续压测（N 服 × M bot 钉服施压、各服结果聚合）编排。 - 单场景多 bot（FR-16）：一个场景驱动多个 bot——异质具名角色（如管理 GUI 的
admin/target）+ 同质批量复制（bot { count = N }，各唯一 username、经BOT_INDEX区分），用于集群多 bot 各自切服、单后端多 bot 直连分角色。 - 每后端身份注入（FR-12）：起每个后端下发其 DSL 声明名
MC_TESTKIT_E2E_BACKEND_NAME，消费方据此 per-backend 派生身份（如同组各服不同server-id）。 - 覆盖 Paper/Folia 后端 + Velocity/Waterfall/BungeeCord 代理（不含 Spigot/Bukkit/Sponge）。
- 经 Velocity 代理 modern forwarding（代理
velocity.toml+ 后端 paper-global velocity，共享 secret）：单后端经代理 / 集群/server切换 / 崩溃接管均可跑；Velocity 单端口不支持压测钉服（stress + via=velocity配置期中文报错）。补齐三代理平台「真能跑」（ADR-0010）。 - 自动编排：准备运行目录、注入待测/依赖插件、启动机器人、起服/起代理、读结果判定 PASS/FAIL、收尾杀进程、缓存回写。
- 节点运行时注入（FR-20，v0.5.0）：backend/proxy 可分别声明节点环境与模板目录，proxy 还可声明专属插件；任务启动前统一预检资源，环境优先级为“宿主 < 节点 < 框架”，
dependencies { }仍只注入后端，并兼容旧全局服务端模板环境变量。 - 持久手测 serve（FR-17/18/19，v0.4.0）：复用同一拓扑声明把「（可选代理 +）后端 + 插件」起起来挂住供真人客户端连入手动测试——单后端 / 集群
/server切服 / 可选并起 bot 人机混场；不判定、不自动收尾，手动停（Ctrl+C /stop<Key>Serve）时三重收尾、端口不漏（新增第 5 个顶层块serve { }，ADR-0011）。 - 固化环境契约：经代理时固定 bot 协议版本、paper-global 代理在线模式、BungeeCord 后端配置、依赖数据源/Redis 注入校验。
template/脚手架：新项目照抄即用的桩插件骨架 + bot 内核 + 一个示例场景。
mc-testkit/
build.gradle.kts / settings.gradle.kts # Gradle 插件工程（java-gradle-plugin + kotlin-dsl）
src/main/kotlin/top/wcpe/mc/testkit/ # 插件实现：McTestkitPlugin + mcTestkit{} DSL + 任务/编排助手
template/ # 脚手架：桩插件骨架 + mineflayer bot 内核 + 示例场景 + 复制说明
docs/ # PRD / ARCHITECTURE / API / ADR / 运维 / 贡献指南
.claude/rules/ # 防漂移规则（架构不变量 / 范围 / 决策 / 文档 / 质量 / 风格）
template/是纯拷贝脚手架（不被插件构建依赖、不进发布产物）；消费方照抄到自己项目按需改。
- 需求：
docs/PRD.md - 架构：
docs/ARCHITECTURE.md - 接口：
docs/API.md - 运维：
docs/OPERATIONS.md - 安全：
SECURITY.md - 决策：
docs/adr/ - 演进与维护：
docs/CONTRIBUTING.md - 变更史：
CHANGELOG.md
1. 声明插件仓库（settings.gradle.kts）：
pluginManagement {
repositories {
gradlePluginPortal()
maven("https://maven.wcpe.top/repository/maven-public/")
}
}2. 应用插件、声明拓扑与场景（build.gradle.kts）：
plugins {
id("top.wcpe.mc-testkit") version "0.5.1"
}
mcTestkit {
backend("s1") { platform = paper; version = "1.20.1"; port = 25565 }
proxy("wf") { platform = waterfall; port = 25577; routesTo("s1") }
scenario("buy") {
backend = "s1"; via = "wf"
bot { username = "Buyer"; action = "buy" } // 业务 env 经 bot { env(name, value) } 透传
}
dependencies {
pluginUnderTest = "MY_PLUGIN_JAR" // 环境变量名或 jar 路径
plugin("SampleLib") // 依赖插件（同上）
}
}3. 照抄脚手架并跑场景：把 template/（桩插件 + 机器人内核）拷进项目按 template/README.md 接线，然后：
./gradlew e2eBuy # 直连后端跑场景
./gradlew e2eBuyViaWf # 经 Waterfall 代理跑场景v0.5.0 节点声明示例：
backend("s1") {
env("MYPLUGIN_NODE", "s1")
templateDirectory("MC_TESTKIT_E2E_S1_TEMPLATE_DIR")
}
proxy("wf") {
routesTo("s1")
plugin("MC_TESTKIT_E2E_PROXY_PLUGIN_JAR")
env("MYPLUGIN_PROXY_NODE", "wf")
templateDirectory("MC_TESTKIT_E2E_PROXY_TEMPLATE_DIR")
}envOrPath 的非空环境变量值优先，否则按路径解析；节点 env(...) 不得声明大小写任意形式的 MC_TESTKIT_E2E_ 保留前缀。dependencies { } 仍只注入后端，不会把待测或依赖插件复制到代理。
服务端模板 / 依赖 jar / 规模等经 MC_TESTKIT_E2E_* 环境变量提供，完整任务名与环境变量约定见 docs/API.md。本仓库自身的构建/发布命令见 docs/OPERATIONS.md。
提交、分支、文档同步等协作约定见 docs/CONTRIBUTING.md 与 .claude/rules/。
MIT。