modsmith 0.6.2 → 0.7.1

package/src/rcon.mjs

@@ -49,15 +49,21 @@ export function makeRcon(host, port, password) {
     s.on('close', () => fail(new Error('RCON 连接断了')));
     s.on('connect', () => {
       send(3, password);
-      waiters.push(() => resolve((cmd) => new Promise((res, rej) => {
-        const timer = setTimeout(() => rej(new Error(`RCON 命令 15s 无响应：${cmd.slice(0, 60)}`)), 15000);
-        send(2, cmd);
-        waiters.push((value, err) => {
-          clearTimeout(timer);
-          if (err) rej(err);
-          else res(value);
+      waiters.push(() => {
+        const api = (cmd) => new Promise((res, rej) => {
+          const timer = setTimeout(() => rej(new Error(`RCON 命令 15s 无响应：${cmd.slice(0, 60)}`)), 15000);
+          send(2, cmd);
+          waiters.push((value, err) => {
+            clearTimeout(timer);
+            if (err) rej(err);
+            else res(value);
+          });
         });
-      })));
+        // CLI 一个进程会串好几步（onboard）：socket 不关，事件循环就一直挂着，
+        // 所有步骤完成后进程也不退出（实测）。
+        api.close = () => { try { s.end(); } catch { /* 已经断开 */ } };
+        resolve(api);
+      });
     });
   });
 }

package/src/server-fingerprint.mjs

@@ -22,12 +22,12 @@ export function fingerprintOf(files) {
 }
 
 /**
- * 不参与指纹的文件：`modsmith-sidecar-*` 是我们自己产出的通用侧车。
- *
- * 它只注册命令、不注册任何方块/物品，**不可能让 id 位移**；把它算进指纹会让
- * "装上侧车 → verify 立刻说 ids 过期"——实测在 onboard 链上直接卡死。
+ * 不参与指纹的文件：
+ *   - `modsmith-sidecar-*`：只注册命令、不注册任何方块/物品，不可能让 id 位移；
+ *   - `modsmith-dump-*`：只读注册表写 JSON，同样不注册内容。把它算进指纹会让
+ *     “装了 dump → ids 立刻过期”，而 dump 本来就是一次性测量工具，不该成为运行时依赖。
  */
-const IGNORED = [/^modsmith-sidecar.*\.jar$/i];
+const IGNORED = [/^modsmith-sidecar.*\.jar$/i, /^modsmith-dump.*\.jar$/i];
 
 /** 读一个 mods 目录（顶层文件），算出指纹。目录不存在/读不了会抛，由调用方决定怎么报。 */
 export function fingerprintDir(dir) {

package/src/stations.mjs

@@ -19,6 +19,26 @@ const VANILLA_STATION_TYPES = new Set([
   'campfire_cooking', 'stonecutting', 'smithing_transform', 'smithing_trim',
 ]);
 
+/** verify --stations 真的会执行的三种机制。 */
+export const STATION_EXECUTORS = new Set(['sidecar-recipe', 'two-step-use', 'place-and-wait']);
+
+/**
+ * 站点为什么"已知但未验"（不是失败）：
+ *   - 机制没有执行器
+ *   - sidecar-recipe 的命令还没写回（没编译/没安装侧车）
+ * 缺 recipeType 不在这里——那是清单数据错误，调用方按失败报。
+ */
+export function stationSkipReason(station) {
+  if (!station?.recipeType) return null;
+  if (!STATION_EXECUTORS.has(station.kind)) {
+    return `机制 ${station.kind} 还没有执行器（已知但未验）`;
+  }
+  if (station.kind === 'sidecar-recipe' && !station.command) {
+    return '侧车命令没有写回（未编译/未安装）：已知但未验';
+  }
+  return null;
+}
+
 /** 配方类型 → 可能的方块名词干（类型词干之外再兜一层别名）。 */
 const STEM_ALIASES = {
   cooking: ['cooking_pot', 'pot', 'oven', 'stove'],
@@ -190,7 +210,8 @@ export function inferStations(manifest, opts = {}) {
       st.recipeType = type;
     }
     if (kind === 'sidecar-recipe') {
-      st.command = `/${id} cook {recipe}`;
+      // **不在这里写 command**：这时还没有侧车，写了就是让机器人去调一条不存在的命令
+      // （AGENTS 约束 2）。命令由 sidecar 编译成功后写回；没写回时 verify 报“已知但未验”。
       st.recipeType = type;
     }
     stations.push(st);

package/src/validate.mjs

@@ -1,223 +1,231 @@
-/**
- * Manifest 校验器 —— 和宿主侧 `mod-manifest.ts` 同一套规则，去掉 TS 类型。
- *
- * 为什么随包发这份：任何 mineflayer 项目只要读 `<pack>.json` + `<pack>-ids.json`
- * 两个文件就能用，那么"这两个文件长什么样"的规范必须跟包一起走，不能只存在于
- * 某个宿主项目的源码里。
- *
- * 分两级：
- *   error —— 这份清单用不了（缺必填、类型错）
- *   warn  —— 能用，但效果会打折（没站点、没提示词）
- */
-
-const STATION_KINDS = ['two-step-use', 'place-and-wait', 'sidecar-recipe'];
-
-const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
-
-/**
- * @returns {Array<{level: 'error'|'warn', path: string, message: string}>}
- */
-export function validateManifest(raw) {
-  const issues = [];
-  const err = (path, message) => issues.push({ level: 'error', path, message });
-  const warn = (path, message) => issues.push({ level: 'warn', path, message });
-
-  if (!isObject(raw)) {
-    err('', 'manifest 不是一个对象');
-    return issues;
-  }
-
-  for (const key of ['mod', 'version']) {
-    if (typeof raw[key] !== 'string' || !raw[key].trim()) err(key, `缺必填字段 ${key}（字符串）`);
-  }
-  for (const key of ['blocks', 'items', 'crops', 'names']) {
-    if (!isObject(raw[key])) err(key, `缺必填字段 ${key}（对象）`);
-  }
-  if (!Array.isArray(raw.recipes)) err('recipes', '缺必填字段 recipes（数组）');
-
-  if (raw.namespace !== undefined) {
-    if (typeof raw.namespace !== 'string' || !/^[a-z0-9_]+$/.test(raw.namespace)) {
-      err('namespace', 'namespace 只能是小写字母、数字、下划线');
-    }
-  } else {
-    warn('namespace', '没写 namespace，读取方会从方块名前缀推；生成时写死更稳');
-  }
-
-  if (isObject(raw.blocks)) {
-    for (const [name, spec] of Object.entries(raw.blocks)) {
-      if (!name.includes(':')) err(`blocks.${name}`, '方块名要带命名空间（ns:name）');
-      if (!isObject(spec)) { err(`blocks.${name}`, '方块规格不是对象'); continue; }
-      if (!Array.isArray(spec.states)) err(`blocks.${name}.states`, 'states 要是数组');
-      if (typeof spec.solid !== 'boolean') err(`blocks.${name}.solid`, 'solid 要是布尔值');
-      if (spec.solid && spec.box != null && (!Array.isArray(spec.box) || spec.box.length !== 6)) {
-        err(`blocks.${name}.box`, 'box 要是 6 个数字或 null');
-      }
-    }
-  }
-
-  if (isObject(raw.items)) {
-    for (const name of Object.keys(raw.items)) {
-      if (!name.includes(':')) err(`items.${name}`, '物品名要带命名空间（ns:name）');
-    }
-  }
-
-  if (isObject(raw.crops)) {
-    for (const [name, spec] of Object.entries(raw.crops)) {
-      const at = `crops.${name}`;
-      if (!isObject(spec)) { err(at, '作物规格不是对象'); continue; }
-      if (typeof spec.seed !== 'string' || !spec.seed) err(`${at}.seed`, 'seed 必填（字符串）');
-      if (typeof spec.max_age !== 'number' || spec.max_age < 0) err(`${at}.max_age`, 'max_age 要是非负数字');
-      if (typeof spec.age_prop !== 'string' || !spec.age_prop) err(`${at}.age_prop`, 'age_prop 必填（字符串）');
-      if (!Array.isArray(spec.soils) || spec.soils.length === 0) err(`${at}.soils`, 'soils 要是非空数组');
-      if (spec.kind !== undefined && !['age-property', 'stage-blocks'].includes(spec.kind)) {
-        err(`${at}.kind`, 'kind 只认 age-property / stage-blocks');
-      }
-      if (spec.kind === 'stage-blocks' && !isObject(spec.stages)) {
-        err(`${at}.stages`, 'stage-blocks 型作物要给 stages（级号 → 方块名）');
-      }
-    }
-  }
-
-  if (raw.stations !== undefined) {
-    if (!Array.isArray(raw.stations)) {
-      err('stations', 'stations 要是数组');
-    } else {
-      const seen = new Set();
-      raw.stations.forEach((s, i) => {
-        const at = `stations[${i}]`;
-        if (!isObject(s)) { err(at, '站点定义不是对象'); return; }
-        if (typeof s.id !== 'string' || !/^[a-z0-9_]+$/.test(s.id)) {
-          err(`${at}.id`, 'id 只能是小写字母、数字、下划线');
-        } else if (seen.has(s.id)) {
-          warn(`${at}.id`, `id「${s.id}」重复；按 id 点站点时会拿到第一条`);
-        } else {
-          seen.add(s.id);
-        }
-        if (!STATION_KINDS.includes(s.kind)) err(`${at}.kind`, `kind 只认 ${STATION_KINDS.join(' / ')}`);
-        if (typeof s.block !== 'string' || !s.block.includes(':')) {
-          err(`${at}.block`, 'block 必填且要带命名空间');
-        }
-        if (s.kind === 'two-step-use' && !s.toolSuffix) {
-          warn(`${at}.toolSuffix`, 'two-step-use 没写 toolSuffix，工具只能靠猜');
-        }
-        if (s.kind === 'sidecar-recipe') {
-          if (!s.command) err(`${at}.command`, 'sidecar-recipe 必填 command（如 /xxx cook {recipe}）');
-          else if (!String(s.command).includes('{recipe}')) err(`${at}.command`, 'command 里要有 {recipe}');
-          if (!s.recipeType) warn(`${at}.recipeType`, 'sidecar-recipe 没写 recipeType，配方类型只能靠猜');
-        }
-        if (s.heatTag !== undefined && (typeof s.heatTag !== 'string' || !s.heatTag.includes(':'))) {
-          err(`${at}.heatTag`, 'heatTag 要是带命名空间的 tag 名（ns:tag）');
-        }
-      });
-    }
-  } else {
-    warn('stations', '没有 stations：这个 mod 的方块只能靠 use 硬点');
-  }
-
-  if (raw.containers !== undefined) {
-    if (!Array.isArray(raw.containers)) {
-      err('containers', 'containers 要是数组');
-    } else {
-      for (const name of raw.containers) {
-        if (typeof name !== 'string' || !name.includes(':')) {
-          err('containers', `容器名要带命名空间：${String(name)}`);
-        } else if (isObject(raw.blocks) && !(name in raw.blocks)) {
-          warn('containers', `声明了容器 ${name}，但 blocks 里没有它`);
-        }
-      }
-    }
-  }
-
-  if (raw.candidates !== undefined) {
-    if (!isObject(raw.candidates)) {
-      err('candidates', 'candidates 要是对象（tag → 物品名数组）');
-    } else {
-      for (const [tag, list] of Object.entries(raw.candidates)) {
-        if (!Array.isArray(list) || list.some((x) => typeof x !== 'string')) {
-          err(`candidates.${tag}`, '候选要是字符串数组');
-        }
-      }
-    }
-  }
-
-  if (raw.prompt !== undefined) {
-    if (!isObject(raw.prompt)) {
-      err('prompt', 'prompt 要是对象（{zh, en}）');
-    } else {
-      for (const key of ['zh', 'en']) {
-        if (raw.prompt[key] !== undefined && typeof raw.prompt[key] !== 'string') {
-          err(`prompt.${key}`, 'prompt 的每种语言要是字符串');
-        }
-      }
-      if (raw.prompt.zh === undefined && raw.prompt.en === undefined) {
-        warn('prompt', 'prompt 里一种语言都没有');
-      }
-    }
-  } else {
-    warn('prompt', '没有 prompt：提示词里只会写「装了 X」');
-  }
-
-  if (raw.unsupported !== undefined && (!Array.isArray(raw.unsupported)
-    || raw.unsupported.some((x) => typeof x !== 'string'))) {
-    err('unsupported', 'unsupported 要是字符串数组');
-  }
-
-  // ---- 配方条目：两种形状（jar 的 pattern/key、服务端的 grid/候选）都放行，但结构要对 ----
-  // schema 里 file 已降为可选、required 是 id+type；这里做同一套的运行时版本，
-  // 因为生成端读的是 validate.mjs 而不是 schema 文件。
-  if (Array.isArray(raw.recipes)) {
-    raw.recipes.forEach((r, i) => {
-      const at = `recipes[${i}]`;
-      if (!isObject(r)) { err(at, '配方条目不是对象'); return; }
-      if (typeof r.id !== 'string' || !r.id) err(`${at}.id`, '配方缺 id');
-      if (typeof r.type !== 'string' || !r.type) err(`${at}.type`, '配方缺 type');
-      const t = String(r.type ?? '');
-      if (t === 'crafting_shaped' && !Array.isArray(r.pattern) && !Array.isArray(r.grid)) {
-        err(at, 'crafting_shaped 配方要有 pattern（jar 形状）或 grid（服务端形状）');
-      }
-      if (t === 'crafting_shapeless' && !Array.isArray(r.ingredients)) {
-        err(`${at}.ingredients`, 'crafting_shapeless 配方要有 ingredients 数组');
-      }
-      // result 允许多产物数组与 null（旧形状）；单产物必须是 {id, count?}
-      if (r.result !== undefined && r.result !== null && !Array.isArray(r.result)) {
-        if (!isObject(r.result) || typeof r.result.id !== 'string') {
-          err(`${at}.result`, 'result 要带 id');
-        } else if (r.result.count !== undefined
-          && (!Number.isInteger(r.result.count) || r.result.count < 1)) {
-          err(`${at}.result.count`, 'result.count 要是正整数');
-        }
-      }
-    });
-  }
-
-  return issues;
-}
-
-export const hasErrors = (issues) => issues.some((i) => i.level === 'error');
-
-export const describeIssues = (issues) =>
-  issues.map((i) => `${i.level === 'error' ? '✗' : '!'} ${i.path || '(根)'}: ${i.message}`);
-
-/** 校验通过后当成 manifest 用；错了给 null。 */
-export function parseManifest(raw) {
-  return hasErrors(validateManifest(raw)) ? null : raw;
-}
-
-/** 统计口径：声明了多少、实际可用多少。 */
-export function statsOf(manifest, ids = null) {
-  const declaredItems = Object.keys(manifest?.items ?? {}).length;
-  const usableItems = ids?.items ? Object.keys(ids.items).length : declaredItems;
-  const failed = Array.isArray(ids?.failed) ? ids.failed : [];
-  return {
-    blocks: Object.keys(manifest?.blocks ?? {}).length,
-    states: Object.values(manifest?.blocks ?? {}).reduce((n, b) => n + (b.states?.length ?? 0), 0),
-    recipes: (manifest?.recipes ?? []).length,
-    crops: Object.keys(manifest?.crops ?? {}).length,
-    stations: (manifest?.stations ?? []).length,
-    containers: (manifest?.containers ?? []).length,
-    declaredItems,
-    usableItems,
-    blockOnlyItems: failed.filter((f) => f.kind === 'block-only').length,
-    unknownItems: failed.filter((f) => f.kind === 'unknown-item').length,
-  };
-}
+/**
+ * Manifest 校验器 —— 和宿主侧 `mod-manifest.ts` 同一套规则，去掉 TS 类型。
+ *
+ * 为什么随包发这份：任何 mineflayer 项目只要读 `<pack>.json` + `<pack>-ids.json`
+ * 两个文件就能用，那么"这两个文件长什么样"的规范必须跟包一起走，不能只存在于
+ * 某个宿主项目的源码里。
+ *
+ * 分两级：
+ *   error —— 这份清单用不了（缺必填、类型错）
+ *   warn  —— 能用，但效果会打折（没站点、没提示词）
+ */
+
+const STATION_KINDS = ['two-step-use', 'place-and-wait', 'sidecar-recipe'];
+
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+/**
+ * @returns {Array<{level: 'error'|'warn', path: string, message: string}>}
+ */
+export function validateManifest(raw) {
+  const issues = [];
+  const err = (path, message) => issues.push({ level: 'error', path, message });
+  const warn = (path, message) => issues.push({ level: 'warn', path, message });
+
+  if (!isObject(raw)) {
+    err('', 'manifest 不是一个对象');
+    return issues;
+  }
+
+  for (const key of ['mod', 'version']) {
+    if (typeof raw[key] !== 'string' || !raw[key].trim()) err(key, `缺必填字段 ${key}（字符串）`);
+  }
+  for (const key of ['blocks', 'items', 'crops', 'names']) {
+    if (!isObject(raw[key])) err(key, `缺必填字段 ${key}（对象）`);
+  }
+  if (!Array.isArray(raw.recipes)) err('recipes', '缺必填字段 recipes（数组）');
+
+  if (raw.namespace !== undefined) {
+    if (typeof raw.namespace !== 'string' || !/^[a-z0-9_]+$/.test(raw.namespace)) {
+      err('namespace', 'namespace 只能是小写字母、数字、下划线');
+    }
+  } else {
+    warn('namespace', '没写 namespace，读取方会从方块名前缀推；生成时写死更稳');
+  }
+
+  if (isObject(raw.blocks)) {
+    for (const [name, spec] of Object.entries(raw.blocks)) {
+      if (!name.includes(':')) err(`blocks.${name}`, '方块名要带命名空间（ns:name）');
+      if (!isObject(spec)) { err(`blocks.${name}`, '方块规格不是对象'); continue; }
+      if (!Array.isArray(spec.states)) err(`blocks.${name}.states`, 'states 要是数组');
+      if (typeof spec.solid !== 'boolean') err(`blocks.${name}.solid`, 'solid 要是布尔值');
+      if (spec.solid && spec.box != null && (!Array.isArray(spec.box) || spec.box.length !== 6)) {
+        err(`blocks.${name}.box`, 'box 要是 6 个数字或 null');
+      }
+    }
+  }
+
+  if (isObject(raw.items)) {
+    for (const name of Object.keys(raw.items)) {
+      if (!name.includes(':')) err(`items.${name}`, '物品名要带命名空间（ns:name）');
+    }
+  }
+
+  if (isObject(raw.crops)) {
+    for (const [name, spec] of Object.entries(raw.crops)) {
+      const at = `crops.${name}`;
+      if (!isObject(spec)) { err(at, '作物规格不是对象'); continue; }
+      if (typeof spec.seed !== 'string' || !spec.seed) err(`${at}.seed`, 'seed 必填（字符串）');
+      if (typeof spec.max_age !== 'number' || spec.max_age < 0) err(`${at}.max_age`, 'max_age 要是非负数字');
+      if (typeof spec.age_prop !== 'string' || !spec.age_prop) err(`${at}.age_prop`, 'age_prop 必填（字符串）');
+      if (!Array.isArray(spec.soils) || spec.soils.length === 0) err(`${at}.soils`, 'soils 要是非空数组');
+      if (spec.kind !== undefined && !['age-property', 'stage-blocks'].includes(spec.kind)) {
+        err(`${at}.kind`, 'kind 只认 age-property / stage-blocks');
+      }
+      if (spec.kind === 'stage-blocks' && !isObject(spec.stages)) {
+        err(`${at}.stages`, 'stage-blocks 型作物要给 stages（级号 → 方块名）');
+      }
+    }
+  }
+
+  if (raw.stations !== undefined) {
+    if (!Array.isArray(raw.stations)) {
+      err('stations', 'stations 要是数组');
+    } else {
+      const seen = new Set();
+      raw.stations.forEach((s, i) => {
+        const at = `stations[${i}]`;
+        if (!isObject(s)) { err(at, '站点定义不是对象'); return; }
+        if (typeof s.id !== 'string' || !/^[a-z0-9_]+$/.test(s.id)) {
+          err(`${at}.id`, 'id 只能是小写字母、数字、下划线');
+        } else if (seen.has(s.id)) {
+          warn(`${at}.id`, `id「${s.id}」重复；按 id 点站点时会拿到第一条`);
+        } else {
+          seen.add(s.id);
+        }
+        if (!STATION_KINDS.includes(s.kind)) err(`${at}.kind`, `kind 只认 ${STATION_KINDS.join(' / ')}`);
+        if (typeof s.block !== 'string' || !s.block.includes(':')) {
+          err(`${at}.block`, 'block 必填且要带命名空间');
+        }
+        if (s.kind === 'two-step-use' && !s.toolSuffix) {
+          warn(`${at}.toolSuffix`, 'two-step-use 没写 toolSuffix，工具只能靠猜');
+        }
+        if (s.kind === 'sidecar-recipe') {
+          if (!s.command) err(`${at}.command`, 'sidecar-recipe 必填 command（如 /xxx cook {recipe}）');
+          else if (!String(s.command).includes('{recipe}')) err(`${at}.command`, 'command 里要有 {recipe}');
+          if (!s.recipeType) warn(`${at}.recipeType`, 'sidecar-recipe 没写 recipeType，配方类型只能靠猜');
+        }
+        if (s.heatTag !== undefined && (typeof s.heatTag !== 'string' || !s.heatTag.includes(':'))) {
+          err(`${at}.heatTag`, 'heatTag 要是带命名空间的 tag 名（ns:tag）');
+        }
+      });
+    }
+  } else {
+    warn('stations', '没有 stations：这个 mod 的方块只能靠 use 硬点');
+  }
+
+  if (raw.containers !== undefined) {
+    if (!Array.isArray(raw.containers)) {
+      err('containers', 'containers 要是数组');
+    } else {
+      for (const name of raw.containers) {
+        if (typeof name !== 'string' || !name.includes(':')) {
+          err('containers', `容器名要带命名空间：${String(name)}`);
+        } else if (isObject(raw.blocks) && !(name in raw.blocks)) {
+          warn('containers', `声明了容器 ${name}，但 blocks 里没有它`);
+        }
+      }
+    }
+  }
+
+  if (raw.candidates !== undefined) {
+    if (!isObject(raw.candidates)) {
+      err('candidates', 'candidates 要是对象（tag → 物品名数组）');
+    } else {
+      for (const [tag, list] of Object.entries(raw.candidates)) {
+        if (!Array.isArray(list) || list.some((x) => typeof x !== 'string')) {
+          err(`candidates.${tag}`, '候选要是字符串数组');
+        }
+      }
+    }
+  }
+
+  if (raw.prompt !== undefined) {
+    if (!isObject(raw.prompt)) {
+      err('prompt', 'prompt 要是对象（{zh, en}）');
+    } else {
+      for (const key of ['zh', 'en']) {
+        if (raw.prompt[key] !== undefined && typeof raw.prompt[key] !== 'string') {
+          err(`prompt.${key}`, 'prompt 的每种语言要是字符串');
+        }
+      }
+      if (raw.prompt.zh === undefined && raw.prompt.en === undefined) {
+        warn('prompt', 'prompt 里一种语言都没有');
+      }
+    }
+  } else {
+    warn('prompt', '没有 prompt：提示词里只会写「装了 X」');
+  }
+
+  if (raw.unsupported !== undefined && (!Array.isArray(raw.unsupported)
+    || raw.unsupported.some((x) => typeof x !== 'string'))) {
+    err('unsupported', 'unsupported 要是字符串数组');
+  }
+
+  // ---- 配方条目：两种形状（jar 的 pattern/key、服务端的 grid/候选）都放行，但结构要对 ----
+  // schema 里 file 已降为可选、required 是 id+type；这里做同一套的运行时版本，
+  // 因为生成端读的是 validate.mjs 而不是 schema 文件。
+  if (Array.isArray(raw.recipes)) {
+    raw.recipes.forEach((r, i) => {
+      const at = `recipes[${i}]`;
+      if (!isObject(r)) { err(at, '配方条目不是对象'); return; }
+      if (typeof r.id !== 'string' || !r.id) err(`${at}.id`, '配方缺 id');
+      if (typeof r.type !== 'string' || !r.type) err(`${at}.type`, '配方缺 type');
+      const t = String(r.type ?? '');
+      if (t === 'crafting_shaped' && !Array.isArray(r.pattern) && !Array.isArray(r.grid)) {
+        err(at, 'crafting_shaped 配方要有 pattern（jar 形状）或 grid（服务端形状）');
+      }
+      if (t === 'crafting_shapeless' && !Array.isArray(r.ingredients)) {
+        err(`${at}.ingredients`, 'crafting_shapeless 配方要有 ingredients 数组');
+      }
+      // 原版有明确产物形状的类型才强制 result.id；自定义序列化器（immersiveengineering:crusher
+      // 之类的 basePredicate、twilightforest 的自定义 result）可以有别的形状。
+      const RESULT_REQUIRED = new Set([
+        'crafting_shaped', 'crafting_shapeless',
+        'smelting', 'blasting', 'smoking', 'campfire_cooking',
+        'stonecutting', 'smithing_transform',
+      ]);
+      if (r.result !== undefined && r.result !== null && !Array.isArray(r.result)) {
+        if (RESULT_REQUIRED.has(t)) {
+          if (!isObject(r.result) || typeof r.result.id !== 'string') {
+            err(`${at}.result`, 'result 要带 id');
+          } else if (r.result.count !== undefined
+            && (!Number.isInteger(r.result.count) || r.result.count < 1)) {
+            err(`${at}.result.count`, 'result.count 要是正整数');
+          }
+        }
+      }
+    });
+  }
+
+  return issues;
+}
+
+export const hasErrors = (issues) => issues.some((i) => i.level === 'error');
+
+export const describeIssues = (issues) =>
+  issues.map((i) => `${i.level === 'error' ? '✗' : '!'} ${i.path || '(根)'}: ${i.message}`);
+
+/** 校验通过后当成 manifest 用；错了给 null。 */
+export function parseManifest(raw) {
+  return hasErrors(validateManifest(raw)) ? null : raw;
+}
+
+/** 统计口径：声明了多少、实际可用多少。 */
+export function statsOf(manifest, ids = null) {
+  const declaredItems = Object.keys(manifest?.items ?? {}).length;
+  const usableItems = ids?.items ? Object.keys(ids.items).length : declaredItems;
+  const failed = Array.isArray(ids?.failed) ? ids.failed : [];
+  return {
+    blocks: Object.keys(manifest?.blocks ?? {}).length,
+    states: Object.values(manifest?.blocks ?? {}).reduce((n, b) => n + (b.states?.length ?? 0), 0),
+    recipes: (manifest?.recipes ?? []).length,
+    crops: Object.keys(manifest?.crops ?? {}).length,
+    stations: (manifest?.stations ?? []).length,
+    containers: (manifest?.containers ?? []).length,
+    declaredItems,
+    usableItems,
+    blockOnlyItems: failed.filter((f) => f.kind === 'block-only').length,
+    unknownItems: failed.filter((f) => f.kind === 'unknown-item').length,
+  };
+}

package/src/verify.mjs

@@ -17,6 +17,7 @@ import { checkServerMods } from './server-fingerprint.mjs';
 import { makeRcon } from './rcon.mjs';
 import { fallbackTag } from './tag-fallback.mjs';
 import { vanillaItemTable } from './recipes-join.mjs';
+import { stationSkipReason } from './stations.mjs';
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
@@ -64,6 +65,8 @@ export default async function cmdVerify(args, io) {
 
   const results = [];
   const add = (kind, ok, detail) => results.push({ kind, ok, detail });
+  // 已知但未验：不是通过，也不是失败；回执里显式列出来。
+  const skip = (kind, detail) => results.push({ kind, ok: null, skipped: true, detail });
 
   const cmd = await makeRcon(host, rconPort, rconPassword);
   const bot = mineflayer.createBot({ host, port, username, version: mcVersion, auth: 'offline' });
@@ -175,17 +178,17 @@ export default async function cmdVerify(args, io) {
       else add('station', false, `包里有过 ${blocks} 种方块但没有站点声明（先跑 learn --infer）`);
     }
     // **不许静默跳过**：以前这个 filter 把 place-and-wait 直接丢掉，报告里看不到任何
-    // 痕迹——那正是"静默失败"。现在没有 recipeType 的、以及执行器还没覆盖的类型，
-    // 都要显式列出来。
-    const EXECUTABLE = new Set(['sidecar-recipe', 'two-step-use', 'place-and-wait']);
+    // 痕迹——那正是"静默失败"。现在缺 recipeType 的按失败报，机制没执行器、侧车命令
+    // 没写回的按"已知但未验"显式列出（不伪装成通过，也不冤枉数据）。
     for (const st of all) {
       if (!st?.recipeType) {
         add('station', false, `${st?.id ?? '(无 id)'}：站点缺 recipeType，没法挑配方执行`);
-      } else if (!EXECUTABLE.has(st.kind)) {
-        add('station', false, `${st.id}：机制 ${st.kind} 还没有执行器（已知但未验）`);
+        continue;
       }
+      const why = stationSkipReason(st);
+      if (why) skip('station', `${st.id}：${why}`);
     }
-    const stations = all.filter((st) => EXECUTABLE.has(st.kind) && st.recipeType);
+    const stations = all.filter((st) => st.recipeType && !stationSkipReason(st));
 
     // 两步式站点：需要把物品放上去、再手持工具右键。用真实交互而不是命令，
     // 这样验的是"机器人能不能做得到"，不是"服务端能不能代做"。
@@ -444,18 +447,23 @@ export default async function cmdVerify(args, io) {
   await cmd(`forceload remove ${bx - 8} ${bz - 8} ${bx + 8} ${bz + 8}`);
   await sleep(300);
   bot.quit();
+  cmd.close();
 
-  const failed = results.filter((r) => !r.ok);
+  const failed = results.filter((r) => r.ok === false);
+  const unverified = results.filter((r) => r.skipped === true);
   console.error(`\n=== verify ${manifest.mod} ===`);
-  for (const r of results) console.error(`  ${r.ok ? '✓' : '✗'} [${r.kind}] ${r.detail}`);
-  console.error(`\n${failed.length === 0 ? '全部通过' : `${failed.length} 项没过`}`);
+  for (const r of results) {
+    console.error(`  ${r.skipped ? '·' : r.ok ? '✓' : '✗'} [${r.kind}] ${r.detail}`);
+  }
+  console.error(`\n${failed.length === 0 ? '全部通过' : `${failed.length} 项没过`}`
+    + (unverified.length > 0 ? `；${unverified.length} 项已知但未验` : ''));
 
   if (typeof args.out === 'string') {
     const { writeIds } = await import('./manifest-io.mjs');
     writeIds(args.out, { mod: manifest.mod, verifiedAt: new Date().toISOString(), results });
   }
   if (failed.length > 0) process.exitCode = 1;
-  console.log(JSON.stringify({ mod: manifest.mod, failed: failed.length, results }, null, 2));
+  console.log(JSON.stringify({ mod: manifest.mod, failed: failed.length, unverified: unverified.length, results }, null, 2));
 }
 
 /**

package/templates/reference-bot/README.md

@@ -0,0 +1,22 @@
+# reference-bot
+
+最小的参考消费者：**不依赖 Cortico**，只证明一份 `manifest + ids` 能被普通
+mineflayer 机器人消费。
+
+```bash
+npm i modsmith mineflayer
+node index.mjs \
+  --host 127.0.0.1 --port 25565 \
+  --manifest ../../mods/<pack>.json \
+  --ids ../../mods/<pack>-ids.json \
+  --username ModReference
+```
+
+它做三件事：
+
+1. 在 `inject_allowed` 之前把 manifest + ids 注入 `bot.registry`；
+2. 丢掉只读验证不需要的大包（`declare_recipes` / `declare_commands` / `entity_metadata`）；
+3. 打印方块 state 数、实体显示名与 boss 标记，然后退出。
+
+它不 setblock、不召唤、不聊天，所以可以安全地指向生产服做一次只读验收。
+需要写世界抽样的完整 live 验收见仓库里的 `modsmith conformance --live`。