基于 TypeSafe Jev 的事件驱动 Minecraft NPC 自主决策框架。
NPC 根据世界事件、当前状态、目标、记忆和关系选择结构化行为，再由 Minecraft 原生机制执行。Jev 是核心决策模型；聊天和 LLM 高级规划是后续可选扩展。
当前状态：Phase 0 工程验证已完成，M0 收口（2026-09-22）。 P0-01 锁定平台版本组合；P0-02 建立最小 Fabric 工程并实测构建／领域检查／服务端启动退出；P0-04 已在 Minecraft 1.21.11 + Fabric API 0.141.6 上 headless 实测原生能力（被取消攻击与实际伤害可区分、四类动作的启动／完成／取消入口与能力边界，见任务计划）；P0-05 已建立 GitHub Actions 工作流并本地验证同入口通过（无远端，远端运行记录待托管环境）；P0-03 已建立 jev-engine 协议核心与凭据门控真实调用入口、离线协议检查通过，并于 2026-09-22 服务端配置凭据后取得真实 Choice 证据（合成「玩家攻击村民」场景，HTTP 200、choice=CALL_GUARD、confidence=0.9、延迟 1298ms、usage 存在，脱敏样本落盘）。P0-06 已收口 M0 全部条件，远端 CI 运行记录（P0-05 限制）需 git 远端后触发。P1-01 已完成（2026-09-22）：最小领域类型（身份、位置、人格／当前目标、快照、事件、候选、上下文、决策与执行结果）在 :domain 落地，领域检查 96 用例 0 失败；P1-02／P1-04／P1-05 可开始。
Minecraft 事实 → 领域事件 → NPC／世界／记忆／关系快照
→ Jev Choice → 候选与状态复核 → 原生行为 → 执行反馈
首个演示计划采用“玩家攻击 NPC”：村民根据状态选择逃跑或请求现有守卫协助；只有具备战斗能力的实体才有攻击候选。行为执行前后都有明确校验，不将模型选择视为已经完成的动作。
项目不重写寻路、物理或实体系统，不要求每个动作调用 LLM，不以聊天机器人作为核心目标。
| 文档 | 内容 |
|---|---|
| 项目总纲 | 项目定位、愿景与功能方向 |
| 架构契约 | 决策闭环、线程、边界、故障与选型状态 |
| 模块契约 | 模块职责、依赖、共享类型归属与执行边界 |
| Jev 决策契约 | 内部上下文、官方 HTTP 映射、候选、置信度与退化 |
| NPC 模型契约 | 身份、状态、目标、三层记忆、关系与持久化 |
| 事件契约 | 事件 Schema、事实来源、分发、去重与反馈 |
| 实施路线图 | Phase 0—5 的交付物、验收条件与当前进度 |
| 任务规划与拆解 | 32 项任务的依赖、交付物、验收条件及首批执行顺序 |
| AGENTS.md | 面向代码代理的仓库协作规则 |
总纲定义方向；契约中的字段、边界和失败规则是本次补充的实现约定。建议和待核验项不代表已完成的技术选型。
版本组合由 P0-01 按官方资料选定，核验日期 2026-09-21。这里只完成资料核验与构件可达性检查；实际构建、启动与退出验证属于 P0-02，尚未执行。
| 领域 | 选定版本 | 来源与核验依据 |
|---|---|---|
| Minecraft | 1.21.11（release，2025-12-09 发布） | Mojang 版本清单；1.21.11 版本 JSON 声明 java-runtime-delta、majorVersion=21 |
| Fabric Loader | 0.19.5（stable） | Fabric meta：loader/1.21.11 首个 stable 项；fabric-loader-0.19.5.jar 实测 HTTP 200 |
| Fabric API | 0.141.6+1.21.11 | 官方示例 1.21.11 分支 gradle.properties；maven.fabricmc.net 上该构件实测 HTTP 200 |
| 映射 | Mojang 官方映射，mappings loom.officialMojangMappings() |
官方示例 1.21.11 分支 build.gradle；client.txt 映射文件实测 HTTP 200 |
| 构建插件（Loom） | 1.17.21，插件 id net.fabricmc.fabric-loom-remap |
fabric-loom maven-metadata 中 1.17 线最新稳定补丁；官方 1.21.11 模板写的是 1.17-SNAPSHOT，本项目不用 SNAPSHOT，P0-02 构建失败时再在该线内换补丁号。Loom 1.17 发布说明「Update to Gradle 9.5」，dev/1.17 分支 options.release = 21，README 声明支持 1.14.4 及以上 Minecraft。1.21.11 属混淆版本，因此用 -remap 插件 id |
| Gradle | 9.5.1，仅通过 Wrapper 使用 | 官方示例 1.21.11 分支 gradle/wrapper/gradle-wrapper.properties；发行包实测 HTTP 200；Gradle 兼容矩阵：运行 Gradle 需 Java 21 → ≥ 8.5、Java 25 → ≥ 9.1.0，9.5.1 两者皆可 |
| Java | 21（本机 Microsoft OpenJDK 21.0.11，JAVA_HOME 已指向） |
Minecraft 1.21.11 要求 21；官方示例 it.options.release = 21、fabric.mod.json 依赖 java >= 21；Loom 1.17 自身以 21 为目标 |
| 决策 | TypeSafe Jev System One HTTP API，Java 侧用 JDK HttpClient 直接接入；JSON 序列化／解析用 Gson 2.11.0 | 见 Jev 决策契约；P0-03 已建 jev-engine 协议核心（请求映射＋响应校验＋HTTP 传输＋故障分类）与凭据门控真实调用入口，离线协议检查 39 用例通过；2026-09-22 真实账户调用已取得首份脱敏 Choice 证据（见任务计划第 9 节 P0-03 完成记录）。Gson 选型理由见 gradle.properties |
| 存储 | Phase 2 使用 SQLite 保存自有状态、记忆和关系 | 驱动、表结构与迁移策略在 Phase 2 落实 |
| 后续 | 社会系统、生态系统、可选 LLM 规划 | 按 路线图推进 |
该组合只针对 1.21.11，不声称兼容全部 1.21+ 或 26.x。
2026-09-21 复核后基线仍为 1.21.11 + Java 21。 本机已装 Microsoft OpenJDK 25.0.4.1（C:\Users\17860\.jdks\ms-25.0.4.1），Minecraft 26.3 路线的 JDK 阻塞解除，相关构件也确认可下载（Loom 1.18.2 及其插件标记、fabric-api-0.161.0+26.3.jar 均 HTTP 200），但暂不升级，因为三项风险未消除：
- Loom 1.18 正式版发布于 2026-09-20，距核验只有一天，稳定补丁记录不足；
- Fabric 文档站的版本化文档只覆盖 1.20.4／1.21.1／1.21.11／26.1.2（sitemap 实测），没有 26.3；
- 26.3 是非混淆版本：intermediary 为
0.0.0、无 Yarn 映射、不写mappings、插件 id 改为net.fabricmc.fabric-loom、options.release = 25；P0-04 要验证的村民／铁傀儡／原生导航接口在新版本上参考资料最少。
升级触发条件：Fabric 文档出现 26.x 版本页且 Loom 1.18 有稳定补丁记录时重新评估；届时须同步总纲与架构契约的 Java 基线。
模块契约第 7 节要求领域模块可脱离 Minecraft 构建／测试，而 Loom 会把 Minecraft 加入其所在工程的编译类路径，因此确有构建隔离需要，拆为两个子项目，不为九个逻辑模块预建九套空工程：
JevNPC/
├── settings.gradle # pluginManagement 加 maven.fabricmc.net；include ':domain', ':minecraft-fabric'
├── build.gradle # 根工程只做公共 Java 设置，不应用 Loom
├── gradle.properties # 上表版本号集中在此
├── gradle/wrapper/ # gradle-9.5.1-bin.zip
├── domain/ # 纯 Java 21，不应用 Loom，不依赖 Fabric／Minecraft
└── minecraft-fabric/ # 应用 Loom 1.17.21，依赖 :domain，含入口、fabric.mod.json、原生端口实现
八个领域逻辑模块先以包边界存在于 domain；只有发布或测试隔离确有需要时再拆子项目。领域检查入口是 :domain:test（P0-02 已建立），不启动游戏。包根已在 P0-02 确定为 dev.jevnpc：领域八模块对应 dev.jevnpc.{core,event,memory,relationship,context,jev,behavior,runtime}，适配层入口位于 dev.jevnpc.fabric（映射依据见模块契约第 1 节）。P0-02 只建立包边界与命名空间，未预建任何空类型，领域类型随 P1-01 落地。
以下为 2026-09-21 在本机实测，未运行的项目如实标注：
| 项 | 现状 | 影响与处理 |
|---|---|---|
| Java | JAVA_HOME 指向 Microsoft OpenJDK 21.0.11；另装有 Microsoft OpenJDK 25.0.4.1（C:\Users\17860\.jdks\ms-25.0.4.1，2026-09-21 确认 java -version 可用）、corretto 21.0.4／21.0.6、corretto 11.0.26、GraalVM 24.0.2 |
构建使用 21.0.11，满足 1.21.11 + Loom 1.17。JDK 25 已具备，Minecraft 26.x／Loom 1.18 不再有 JDK 阻塞；基线按上节决定不升级 |
| Gradle | PATH 中无 gradle；~/.gradle/wrapper/dists 只有 5.2.1／6.9／7.5.1 |
只能经 Wrapper 构建，P0-02 需首次下载 9.5.1 发行包 |
| 版本控制 | git 2.53.0.windows.1 可用，全局身份已配置；G:\work\JevNPC 不是 git 仓库，无远端 |
P0-02 前需 git init 并写忽略规则；无远端托管意味着 P0-05 的远端 CI 运行条件尚未满足 |
| 构建期下载 | maven.fabricmc.net、services.gradle.org、plugins.gradle.org、repo1.maven.org、piston-meta／piston-data.mojang.com、libraries.minecraft.net 均可达；已确认 client.jar 约 31 MB、server.jar 约 56 MB、client.txt 约 12 MB 可下载 |
首次 Loom 构建还要反编译与生成缓存，实际耗时与占用未实测 |
| 受限主机 | raw.githubusercontent.com 不可达（HTTP 000，curl exit 7）；api.github.com 与 codeload.github.com 正常 |
获取模板走 API 或 zip 归档，不依赖 raw 主机 |
| 磁盘 | G: 可用 75 GB（已用 93%）；C: 可用 138 GB，Gradle 缓存位于 C:\Users\17860\.gradle |
空间足够，首次构建后需复核占用 |
| Jev 凭据与账户 | 2026-09-22 用户在 Windows User 作用域环境变量配置 JEVNPC_JEV_API_KEY（密钥不经对话／仓库／日志），真实调用成功：HTTP 200、responseModel=jev-1.13.0 与请求一致、choice=CALL_GUARD、confidence=0.9、延迟 1298ms、usage input_tokens=450/output_tokens=38 |
离线检查（:domain:test）与真实调用（:domain:jevRealCall）分别承载；脱敏样本在 domain/build/jev-trial/samples.jsonl（mode=REAL） |
| 代码托管／CI | 2026-09-22 核实无 git 远端（git remote -v 为空） |
P0-05 工作流 .github/workflows/ci.yml 已完成、本地同入口通过；远端运行待托管环境，不声称 CI 已运行 |
已查阅 TypeSafe 官方接口，并于 2026-09-22 完成首次真实请求（合成场景，脱敏记录）。Jev 核心接入方案需要网络与服务端 API key；“LLM 扩展可选”不表示 Jev 可离线推理。未配置或服务不可用时保留 Minecraft 原生行为，详见决策契约。
先阅读总纲与架构契约，再按所改领域阅读专项契约。Phase 0 的平台版本组合已确认，最小 Mod 工程已在 P0-02 建立并通过构建／启动／退出验证；P0-04 已 headless 实测原生能力与四类动作入口，P0-05 已落 CI 工作流并本地验证同入口，P0-03 已建 Jev 协议核心、离线检查与真实 Choice 证据。
按 任务计划推进：P0-01 至 P0-06 全部完成（2026-09-22），M0 收口；P1-01 已完成（最小领域类型），P1-02／P1-04／P1-05 可开始。Phase 1 在 P1-10 收口前完成单 NPC 决策闭环。
以下命令均在本机（Windows 11、Microsoft OpenJDK 21.0.11、Git Bash）于 2026-09-21 实测通过；Windows 的 cmd／PowerShell 用 gradlew.bat 替代 ./gradlew。首次构建需经 Wrapper 下载 Gradle 9.5.1 发行包，并由 Loom 下载 Minecraft 1.21.11（客户端约 31 MB、服务端约 56 MB、Mojang 映射约 12 MB）后反编译，耗时较长，之后走缓存。
| 目的 | 命令 | 实测结果 |
|---|---|---|
| 完整构建（领域 + Fabric，含领域测试与 remapJar） | ./gradlew build |
BUILD SUCCESSFUL，首次约 9 分 51 秒；产出 domain-0.1.0.jar、minecraft-fabric-0.1.0.jar（含 dev/jevnpc/fabric/JevNPCMod.class 与 fabric.mod.json） |
| 只跑领域检查，不启动游戏 | ./gradlew :domain:test |
96 用例 0 失败（3 个边界用例 + 36 个 P0-03 Jev 离线协议检查 + 57 个 P1-01 领域类型检查：非法值／未知类型拒绝、快照不可变、无 SDK 类型泄漏），daemon 热时约 5s，全程不触发任何 runServer／runClient，不需要 Jev 密钥 |
| 启动开发服务端并优雅退出 | ./gradlew --no-daemon :minecraft-fabric:runServer，待 Done 后于控制台输入 stop |
Fabric Loader 0.19.5 加载 43 个 mod（含 jevnpc 0.1.0），入口打印 [JevNPC] mod 已加载，Done (4.153s)!，stop 后保存三个维度并退出，GRADLE_EXIT=0 |
| P0-04 原生能力验证（headless，自动停服） | ./gradlew --no-daemon :minecraft-fabric:runServer -PjevnpcValidation |
NativeCapabilityValidation 在 SERVER_STARTED 跑同步探针 + 140 tick 有界观测后 halt(false)；GRADLE_EXIT=0，Done→Stopping server→Saving worlds。实测：被取消攻击（AttackEntityCallback 返 FAIL）无 AFTER_DAMAGE、生命不变；实际伤害（PASS／hurtServer→true）触发 AFTER_DAMAGE 且生命下降；RUN moveTo→true 后 villager 沿路径移动、isDone 转 true；CALL_GUARD setTarget 接受、doHurtTarget→true 造成伤害；ATTACK 村民设目标却不造成伤害（无战斗能力）。不带 -PjevnpcValidation 时不安装验证回调，保持 P0-02 最小加载 |
| P0-03 真实 Jev Choice 调用（凭据门控，独立入口） | JEVNPC_JEV_API_KEY=<key> ./gradlew :domain:jevRealCall |
有凭据时发一次真实 Choice 请求、把脱敏样本 + 延迟 + 用量写入 domain/build/jev-trial/samples.jsonl（gitignored）；无凭据时输出 SKIPPED_NO_CREDENTIALS、不联网、退出 0。不被 build／test／CI 触发，故默认测试不需要密钥。2026-09-22 已取得真实样本（mode=REAL） |
服务端首次启动前需在 minecraft-fabric/run/eula.txt 写入 eula=true 接受 Minecraft EULA；run/（含存档、日志、本地配置）已被 .gitignore 忽略，不会提交。用 --no-daemon 是为了让服务端控制台的标准输入真正连通以便键入 stop——runServer 任务已在 minecraft-fabric/build.gradle 显式接通 standardInput。本地验证用的 run/server.properties 设了 online-mode=false（无玩家时免去验证联网）与 max-tick-time=-1（禁用看门狗，容忍首次世界生成较慢），同样不提交。
当前工程布局（P0-02 建立，P0-03／P0-04／P0-05 扩充）：
JevNPC/
├── README.md
├── AGENTS.md
├── settings.gradle # pluginManagement 加 Fabric maven；include ':domain', ':minecraft-fabric'
├── build.gradle # 根工程：仅统一 group/version，不应用 Loom
├── gradle.properties # 平台版本号集中于此
├── gradlew / gradlew.bat
├── gradle/wrapper/ # Gradle 9.5.1（gradle-wrapper.jar / .properties）
├── .gitignore / .gitattributes
├── .github/workflows/ci.yml # P0-05 最小 CI：调用 ./gradlew build 与 :domain:test
├── docs/ # 总纲与各项契约、路线图、任务计划（注：docs/ 与 AGENTS.md 当前被 .gitignore 忽略）
├── domain/ # 纯 Java 21 领域层，不应用 Loom，不依赖 Fabric／Minecraft
│ ├── build.gradle
│ └── src/
│ ├── main/java/dev/jevnpc/
│ │ ├── package-info.java
│ │ ├── core/ # npc-core：身份、位置、人格／目标、快照、动作候选（P1-01）
│ │ ├── event/ # event-system：事件信封与 Phase 1 载荷（P1-01）
│ │ ├── context/ # context-builder：DecisionContext（P1-01）
│ │ ├── jev/ # jev-engine：协议核心（P0-03）＋NPCDecision（P1-01）＋trial/ 试验脚手架
│ │ └── behavior/ # behavior-engine：ExecutionResult（P1-01）
│ └── test/java/dev/jevnpc/
│ ├── DomainBoundaryTest.java
│ ├── DomainTypeLeakageTest.java # P1-01：领域类型不引用 SDK 类型的反射检查
│ ├── core/、event/、context/、jev/、behavior/ # 对应包的领域检查（P0-03／P1-01）
└── minecraft-fabric/ # Loom 适配层，依赖 :domain
├── build.gradle
└── src/main/
├── java/dev/jevnpc/fabric/
│ ├── JevNPCMod.java
│ └── validation/NativeCapabilityValidation.java # P0-04 原生能力验证 harness（门控）
└── resources/fabric.mod.json
领域八模块中 jev-engine（dev.jevnpc.jev）已随 P0-03 落地协议核心（请求映射、响应校验、HTTP 传输、故障分类）与试验脚手架，P1-01 落地其余首阶段类型：core／event／context／behavior 的最小领域类型与 jev 的 NPCDecision；memory／relationship／runtime 仍待后续阶段落地。:minecraft-fabric 入口在 P0-02 加载日志之外，新增 P0-04 原生能力验证 harness（jevnpc.validation.native 门控，默认不安装额外回调）。API key、存档数据库、玩家数据和本地配置不得提交到版本库（.gitignore 已覆盖 run/、build/、.gradle/、.env、secrets.*、*.local.properties；P0-03 脱敏样本写入 domain/build/jev-trial/，在 build/ 忽略范围内）。