[Merge]: 合入 Qz-Miner 5.1.0 发布候选

- 候选提交：`1cd341f956abfdbce71dedced20962651c66c016`。

- 冻结 5.1 minor-family 兼容、wire 与 schema 基线。

- 候选 CI：`branch-ci.yml` run [`30190860784`](https://github.com/QuanhuZeYu/Qz-Miner/actions/runs/30190860784)，exact SHA 已通过。

- 真实 mixed/missing client/dedicated 运行态仍为 **INCOMPLETE**，不由 CI 结果替代。

Author: QuanhuZeYu

.changelogs/5.1.0.md

@@ -0,0 +1,27 @@
+# Qz-Miner 5.1.0
+
+## 本次更新
+
+- 自动工具换位协议升级为 v4：接替请求使用独立、发布即烧号的 `takeoverRequestId`，库存 mutation
+  只提交一次，完整库存 publication 与动作回执可按同一请求精确重试；目标局部失败只跳当前目标。
+- 方块身份统一覆盖完整 signed `int` 合同：存在目标的 block ID 为 `1..Integer.MAX_VALUE`，metadata
+  为 `0..Integer.MAX_VALUE`，block ID `0` 保留为空气/缺席 sentinel；对象组 selector 同步覆盖完整非负 int 域。
+- 服务端规划与客户端预览统一采用 context 级 1024:1 空气候选预算；CHAIN 按冻结工具能力断链，AREA
+  保持空间范围宽进并由服务端主线程逐目标终裁。
+- `INTERACT` 接通同类方块、液体源、全部作物、未成熟作物施肥四种完整立方范围交互；BLOCK/AIR
+  统一进入宽泛右键入口，执行前继续逐目标重验世界、权限、冻结身份和当前手持物。
+
+## 5.1 兼容合同
+
+- 客户端与服务端只要都提供完整合法的 `5.1.x[-prerelease][+build]` 版本，即忽略 patch 与 qualifier
+  互通；stable、prerelease、branch/dirty dev 均适用。`5.0.x`、`5.10.x` 与畸形版本明确拒绝。
+- 5.1 family 冻结当前 16 个 packet discriminator/Side、协议版本、字段顺序、framing、ordinal、wire
+  code、对象组 mode bit 与 24-path 配置 schema。不兼容变化必须升级到新的 minor family。
+- 远端版本表缺少 `qz_miner` 时 Forge checker 在 CLIENT/SERVER 两侧均放行，但这只放宽 mod-list
+  检查，不保证无 Qz-Miner 对端拥有网络 channel 或业务运行安全。
+
+## 验证边界
+
+- 5.1 回归基线、本地 `test` / `compileJava` / `check` / `build` 与文档门禁以候选提交记录为准。
+- branch CI、tag、Release、发布资产、clean consumer、Forge status query，以及真实 5.1 mixed/missing
+  client/dedicated 运行态尚未执行，均明确保持 **INCOMPLETE**；本说明不把自动化证据升级为实机通过。

.github/workflows/branch-ci.yml

@@ -102,6 +102,8 @@ jobs:
     needs: prepare-baselines
     runs-on: ubuntu-24.04
     timeout-minutes: 90
+    env:
+      VERSION: 5.1.0-ci+${{ github.sha }}
     strategy:
       fail-fast: false
       max-parallel: 2
@@ -161,6 +163,72 @@ jobs:
       - name: Build the mod
         run: ./gradlew --info --stacktrace "-Pelytra.manifest.version=${{ matrix.manifest }}" build
 
+      - name: Verify injected version in generated source and main JAR
+        shell: bash
+        run: |
+          python3 <<'PY'
+          import os
+          import re
+          import struct
+          import zipfile
+          from pathlib import Path
+
+          expected = f"5.1.0-ci+{os.environ['GITHUB_SHA']}"
+          declaration = re.compile(
+              r'^\s*public\s+static\s+final\s+String\s+VERSION\s*=\s*"([^"]+)"\s*;\s*$',
+              re.MULTILINE,
+          )
+
+          generated = []
+          for path in sorted(Path("build").rglob("Tags.java")):
+              values = declaration.findall(path.read_text(encoding="utf-8"))
+              generated.extend((path, value) for value in values)
+          if not generated:
+              raise SystemExit("generated Tags.VERSION declaration not found")
+          wrong = [(str(path), value) for path, value in generated if value != expected]
+          if wrong:
+              raise SystemExit(f"generated Tags.VERSION mismatch: {wrong!r}; expected {expected!r}")
+
+          jars = sorted(Path("build/libs").glob("*.jar"))
+          main_jars = [
+              path for path in jars
+              if not path.name.endswith(("-dev.jar", "-sources.jar", "-javadoc.jar"))
+          ]
+          if len(main_jars) != 1:
+              raise SystemExit(f"expected one main JAR, found {[str(path) for path in main_jars]!r}")
+
+          with zipfile.ZipFile(main_jars[0]) as archive:
+              class_bytes = archive.read("club/heiqi/qz_miner/Tags.class")
+          if class_bytes[:4] != b"\xca\xfe\xba\xbe":
+              raise SystemExit("generated Tags.class has an invalid classfile header")
+
+          constants = []
+          offset = 8
+          constant_count = struct.unpack_from(">H", class_bytes, offset)[0]
+          offset += 2
+          index = 1
+          fixed_width = {3: 4, 4: 4, 7: 2, 8: 2, 9: 4, 10: 4, 11: 4,
+                         12: 4, 15: 3, 16: 2, 17: 4, 18: 4, 19: 2, 20: 2}
+          while index < constant_count:
+              tag = class_bytes[offset]
+              offset += 1
+              if tag == 1:
+                  length = struct.unpack_from(">H", class_bytes, offset)[0]
+                  offset += 2
+                  constants.append(class_bytes[offset:offset + length].decode("utf-8"))
+                  offset += length
+              elif tag in (5, 6):
+                  offset += 8
+                  index += 1
+              elif tag in fixed_width:
+                  offset += fixed_width[tag]
+              else:
+                  raise SystemExit(f"unsupported constant-pool tag {tag}")
+              index += 1
+          if expected not in constants:
+              raise SystemExit(f"main JAR Tags.class does not contain exact version {expected!r}")
+          PY
+
   build:
     name: build
     if: ${{ always() }}

.opencode/agents/build.md

@@ -49,7 +49,9 @@ fixer 只改写集、执行任务单验证、提交并填写“结果”。随
 
 ## 纠偏与 task_id
 
-- 任何 Task 调用返回后，旧 `task_id` 不得复用，也不得传给任何 agent
+- 任何 Task 返回首个非空回执后，旧 `task_id` 不得复用，也不得传给任何 agent
+- 唯一例外是结果缺失、空串或纯空白：同一主会话可向同一 agent 复用原 ID，只要求继续并返回缺失回执；任务单、目标和范围不得改变
+- 写盘 agent 空返回时先核对 Git 与任务单；若写盘/提交已发生，续接只补结果且禁止重复实施。取得非空结果、明确失败/取消、合同变化、直接冲突的外部漂移或跨会话后，原 ID 立即失效且不得写入 handoff
 - 纠偏、重试或继续工作时，主 agent 将已验证事实写回任务单，删除已完成范围，把动作与写集覆盖为更窄的剩余范围，再创建全新 task
 - reviewer 的 P0/P1 必须有具体失败行为和证据；P2 不阻断当前验收
 - 发现产品取舍、公共 API/兼容性变化、宪章偏离、不可逆操作、发布、merge、push、密钥或授权问题时，用中文 question 集中请用户拍板
@@ -67,6 +69,6 @@ fixer 只改写集、执行任务单验证、提交并填写“结果”。随
 
 ## 跨会话
 
-长任务的会话工作记忆写入 `.opencode/session-handoff.md`，规则见 `docs/控制律层/编排模式/SESSION-HANDOFF.md`。handoff 只保留活动任务单路径、已验证事实、剩余动作和未决用户决定；新会话先核对事实再续接，不复用旧 `task_id`。
+长任务的会话工作记忆写入 `.opencode/session-handoff.md`，规则见 `docs/控制律层/编排模式/SESSION-HANDOFF.md`。handoff 只保留活动任务单路径、已验证事实、剩余动作和未决用户决定；空回执续接只限当前主会话，任何 `task_id` 都不写入 handoff，新会话核对事实后创建全新 task。
 
 任务完成时清理无持续价值的会话记录；涉及 docs 改动后或合并前运行 `pwsh -NoProfile -File scripts/check-doc-discipline.ps1`。

AGENTS.md

@@ -75,7 +75,7 @@
 ### 1.6 Subagent 编排
 - 编排走 `docs/控制律层/编排模式/SUBAGENT-ORCHESTRATION.md`；非平凡任务以 `.opencode/task.md` 作为唯一活动任务单，格式见 `docs/控制律层/编排模式/TASK-BRIEF.md`
 - 主 agent 只向子 agent 传任务单路径和一句执行指令；fixer 按任务单写集实施、验证并提交，写盘改动随后由 reviewer 读取同一任务单与 Git diff 独立复审
-- 任何 Task 调用一旦返回主 agent，旧 `task_id` 不得复用。纠偏、重试或继续工作必须覆盖任务单为更窄范围，并创建全新 task
+- 任何 Task 返回首个非空回执后，旧 `task_id` 不得复用；纠偏、重试或继续工作必须覆盖任务单为更窄范围并创建全新 task。仅当 `task_result` 缺失/空串/纯空白时，可在同一主会话、同一任务单和同一 agent 上复用原 ID 索取缺失回执；写盘已发生时只补结果、不得重复实施。非空结果、明确失败/取消、合同变化或跨会话后立即失效，空返回 ID 不写入 handoff
 - `qz-control-envelope/v1` 已弃用，不再是写盘或复审前置条件
 - 决策点用中文 question 向用户拍板，subagent 不替用户做架构决定
 

README.md

@@ -27,7 +27,7 @@ Qz-Miner 是一个面向 `Minecraft 1.7.10 + Forge + GTNH` 环境的连锁挖掘
 
 - `CHAIN`：以当前目标为起点做邻近连锁，适合常规挖掘、矿石和伐木
 - `AREA`：按范围盒扫收集目标，适合平面清理、矿区切面和隧道开掘
-- `INTERACT`：对一批同类目标连续执行右键交互，适合作物和可右键方块
+- `INTERACT`（范围交互）：以宽泛右键为统一入口，在完整立方范围内盒扫目标，并按子模式连续执行正常右键语义
 - `SPECIAL`：放特定模组兼容逻辑，目前包含 LootGames 扫雷预览与 GT 线缆替换
 
 ### 当前可用子模式
@@ -40,8 +40,10 @@ Qz-Miner 是一个面向 `Minecraft 1.7.10 + Forge + GTNH` 环境的连锁挖掘
 - `AREA_ORE`：范围内按宽泛矿石匹配
 - `AREA_TUNNEL`：按配置选择视线主轴或命中面朝方块内部，生成 `3 x 3 x radius` 的指向性隧道区域
 - `AREA_SECTION_CLEAR`：按被挖方块所在的 `16 x 16 x 16` 区段生成固定清理区域
-- `INTERACT_BASE`：默认同类右键交互
-- `INTERACT_CROP`：作物交互模式，支持原版小麦与 IC2 作物
+- `INTERACT_BASE`：同类方块；严格匹配触发方块的 block、完整 metadata 与方块实体身份，并保留旧对象组扩展
+- `INTERACT_LIQUID_SOURCE`：液体源；只处理与触发 source 同种且当前仍可排出的静态液体源
+- `INTERACT_CROP`：全部作物；处理已可靠识别的成熟和未成熟作物，并保留旧对象组扩展
+- `INTERACT_FERTILIZE_IMMATURE_CROP`：未成熟作物施肥；只处理当前可靠确认仍未成熟的作物
 - `SPECIAL_LOOTGAMES_MINESWEEPER`：对准 LootGames 扫雷棋盘时，通过服务端读取雷位并在客户端标记
 - `SPECIAL_GT_CABLE_REPLACE`：对准 GT 线缆时，连续替换同类连通线缆
 
@@ -52,9 +54,20 @@ Qz-Miner 是一个面向 `Minecraft 1.7.10 + Forge + GTNH` 环境的连锁挖掘
 - 想砍树时，用 `CHAIN_LOGGING`
 - 想开矿道时，用 `AREA_TUNNEL`
 - 想按 `16 x 16 x 16` 的固定区段整体清理时，用 `AREA_SECTION_CLEAR`
-- 想批量右键收作物时，用 `INTERACT_CROP`
+- 想批量右键收作物时，用 `INTERACT_CROP`；想只给未成熟作物使用当前手持肥料时，用 `INTERACT_FERTILIZE_IMMATURE_CROP`
+- 想让当前手持物逐个尝试右键同种静态液体源时，用 `INTERACT_LIQUID_SOURCE`；是否处理流体由物品自身决定
 - 如果客户端卡顿明显，可关闭 `clientEnablePreviewRender`，或调低 `clientPreviewMaxRadius` 与 `clientPreviewMaxTargets`
 
+### 范围交互执行边界
+
+- 四个范围交互子模式的服务端规划与客户端预览都使用预算化 `BoxScanTraverser`，扫描以触发点为中心、边长 `2 x radius + 1` 的完整立方范围；目标无需相邻，不匹配坐标只会被跳过，不会阻断后续空间扫描
+- 四个子模式都观察方块右键与空气右键。普通方块右键保留 Forge event 目标；空气右键从动作生效前的当前射线解析目标。液体模式对两种动作都使用包含液体的射线，客户端预览也使用同一射线数学，因此标准空桶对准原版 source 的空气右键可以成为入口
+- 规划结果不是执行授权。服务端主线程在每个目标执行前都会重验当前世界身份，并继续检查方块存在、世界保护与玩家编辑权限
+- 每个目标都重新读取当前手持物品。普通方块和作物使用带目标坐标的 Forge 方块右键；液体源经精确目标射线进入正常 Forge 空气右键与 Item 路径，不按桶、工业单元或未知物品类型预判能力，也不直接排液、改方块、搜索背包或构造容器
+- 单目标无动作、被拒绝、返回 false 或抛出异常只结算该目标，后续计划目标继续尝试；本次不为同一动作可能出现的 BLOCK/AIR 双事件建立复杂去重事务
+- 对象组仍只扩展 `INTERACT_BASE` 与 `INTERACT_CROP`，不会扩展液体源或未成熟作物施肥模式
+- 本地自动化不能替代真实模组运行态：vanilla bucket / GT 或 IC2 单元 / 第三方 Item / GT CropCard / EFR / 保护插件、client 与 dedicated server 的连续四模式验证仍为 **INCOMPLETE**
+
 ### 并行执行说明
 
 - 服务端连锁规划使用有界线程池调度，默认核心线程数为 `1`，最大线程数为 `20`
@@ -63,7 +76,19 @@ Qz-Miner 是一个面向 `Minecraft 1.7.10 + Forge + GTNH` 环境的连锁挖掘
 
 ## 版本说明
 
-从 `4.0` 到当前 `5.0`，模组做过一次较大的重构。对使用者来说，比较重要的变化包括：
+### 5.1 网络兼容
+
+- `5.1.x` 客户端与服务端只要版本字符串完整合法，就忽略 patch、prerelease 与 build qualifier
+  互通；stable、prerelease、branch/dirty dev 均适用。
+- `5.0.x`、`5.10.x` 与畸形版本不会被当成 5.1；5.1 family 内的 16 个 packet ID/Side、wire
+  framing、协议、ordinal/code/mask 与 24-path 配置 schema 已冻结。不兼容变更必须升级新 minor。
+- 远端模组表缺少 `qz_miner` 时 Forge checker 在 CLIENT/SERVER 两侧都会放行，但这只表示不由
+  mod-list 检查拒绝；它不会为无 Qz-Miner 对端创建网络 channel，也不是无 Mod 运行安全保证。
+- 当前真实 5.1 mixed/missing client 与 dedicated server 运行态仍为 **INCOMPLETE**；本地测试或
+  branch CI 不能替代实机证据。完整合同见
+  `docs/反馈层/决策/network-version-compatibility.md`。
+
+从 `4.0` 到当前 `5.1`，模组做过一次较大的重构。对使用者来说，比较重要的变化包括：
 
 - 完成 `AREA` 模式、`INTERACT` 模式和作物交互模式迁移
 - 为 `CHAIN` 与 `AREA` 接入宽泛矿石匹配子模式
@@ -88,7 +113,7 @@ Qz-Miner 是一个面向 `Minecraft 1.7.10 + Forge + GTNH` 环境的连锁挖掘
 - `AREA` 模式完整闭环：盒扫搜索、执行、HUD、预览已接通
 - `AREA_TUNNEL`：支持按玩家偏好选择视线主轴或命中面方向，生成 `3 x 3 x radius` 的指向性隧道区域
 - `AREA_SECTION_CLEAR`：支持按被挖方块所在 `16 x 16 x 16` 区段生成固定清理区域
-- `INTERACT` 模式完整闭环：右键触发、默认同类交互、作物交互已接通
+- `INTERACT` 模式完整闭环：四种范围交互统一盒扫，同类方块、液体源、全部作物与未成熟作物施肥均已接通执行期重验
 - 统一子模式框架：主模式下可挂载多个子模式，并同步到客户端与服务端
 - `CHAIN_ORE` 与 `AREA_ORE`：宽泛矿石匹配，面向 GT / BW / GT++ / 原版矿石体系
 - `CHAIN_LOGGING`：伐木子模式，只匹配原木，使用壳层扩张搜索而不是默认 6 邻洪泛