@faicad/faijs 0.29.5 → 0.30.9

package/dist/node-host/cli.d.ts

@@ -18,8 +18,15 @@
  *   --sheet <front,top,right,iso>       — (view) 多视图图纸（projectSheet；与 --view 互斥）
  */
 import type { LibNamespace } from '../runtime-state.js';
-import type { ExecutionMode } from '../cad-runtime/ports.js';
+import type { ExecutionMode, HostPorts } from '../cad-runtime/ports.js';
+import type { BrepHandle, BrepSubShapeType } from '../brep/engine/types.js';
 import type { ViewSpec } from '../api/view/view-camera.js';
+/**
+ * 注入 libLoader 到 node ports（CLI 宿主白名单装载）。Exported for executeScript (B6).
+ * @param ports - Node host ports to augment with the CLI lib loader.
+ * @returns The augmented ports (`libLoader` set to the CLI scoped-package loader).
+ */
+export declare function withCliLibLoader(ports: HostPorts): HostPorts;
 /** Options accepted by the `check` command. */
 export interface CliCheckOptions {
     /** Asset directory used by the node ports. */
@@ -163,6 +170,47 @@ export declare function selectExportableTerminals<T extends {
     exportable: T[];
     hiddenCount: number;
 };
+/** 判据取 shapeType/getSubShapes 的最小接口面（用真 kernel 时即 BrepEngineApi 的这两个方法）。 */
+export interface ShapeTypeProbe {
+    shapeType(shape: BrepHandle): string;
+    getSubShapes(shape: BrepHandle, type: BrepSubShapeType): BrepHandle[];
+}
+/**
+ * 终端 BREP 句柄是否「可落成零件」——即含至少一个三维实体。
+ *
+ * **为什么需要它**：终端集合（`live-shapes.ts`）只回答「谁该被看见」，未消费的 2D 草图
+ * 同样是顶层未消费变量 ⇒ 也是终端 ⇒ 会走到导出层落一个 `.step`。而 2D 面片（实测厚度
+ * 2e-07、solids=0）一旦落盘，`fcstd-port` 的 `parity-judge.py merge_parts` 会把它的 area
+ * 加进真实件（5.04e+06 vs 5.50e+06 ⇒ ~91% 误差），parity 必 FAIL。所以「谁该被看见」与
+ * 「什么能落成零件」是两件事：本判据只管后者，不去动终端集合。
+ *
+ * **判决表**（实测标定，2026-10-06）：
+ * | shapeType | 判决 | 依据 |
+ * |---|---|---|
+ * | `SOLID` / `COMPSOLID` | 导出 | 真零件 |
+ * | `COMPOUND` | 含 ≥1 solid → 导出；否则跳过 | 装配体是 compound；`getSubShapes` 递归取子实体 |
+ * | `SHELL` | 含 ≥1 solid → 导出；否则跳过 | 旧栈基线 9/9 真实件皆 solid/compound；实测 8 个游离草图中 5 个顶层恰是 SHELL |
+ * | `FACE`/`WIRE`/`EDGE`/`VERTEX` | 跳过 | 无实体的 2D 片面 / 1D 线框 |
+ * | 其它（`SHAPE` 枚举兜底、空串） | 导出 | 保守，零回归 |
+ * | 无句柄（纯 mesh 终端） | 导出 | mesh 零件导出 STEP 是既有能力，不借本批收紧 |
+ *
+ * **`SHELL` 的裁决**：方案 §3 初稿把 shell 判为「导出（保留现状）」，理由是"面模型是合法
+ * 产物的先例存在"。但 2026-10-06 的 E-1 探针推翻了该前提：
+ * ① 旧栈 parity 基线（A 组 9 个真实件）顶层全为 `SOLID`/`COMPOUND`、`solids ≥ 1`，无一面模型；
+ * ② 新栈多出的 8 个游离草图中 **5 个顶层就是 `SHELL`** ⇒ 按初稿判决**根本拦不住**，方案失效；
+ * ③ `cli.ts` 改动前 0 处 shell 逻辑，不存在需要兼容的既有行为。
+ * ⇒ 改判为 **`SHELL` 且无子实体 → 跳过**。若日后语料真出现「合法的 2D 面模型产物」需求，
+ * 应由脚本侧或显式开关承接，而不是让导出层无法区分草图与零件（登记于相邻缺陷 D-2）。
+ *
+ * 实现上不分层递归：内核 `getSubShapes`（OCCT `TopExp_Explorer` 语义）对任意嵌套深度的
+ * compound **一次即可取到全部子实体**（E-1 探针：顶层 COMPOUND 的草图也能数出 solids=0）。
+ * 探针抛错 → **保守放行**（宁可多导一个，不可误删真零件）。
+ *
+ * @param shape - 终端 BREP 句柄（无句柄传 undefined）
+ * @param probe - shapeType/getSubShapes 提供者（生产用 `brepSolids` 条目的 kernel；测试可注入假 kernel）
+ * @returns 该句柄是否含至少一个实体（可落成零件）
+ */
+export declare function isExportableSolid(shape: BrepHandle | undefined, probe: ShapeTypeProbe | undefined): boolean;
 /**
  * Execute the `view` command: execute a .fai.js file and write view SVG(s).
  *

package/dist/node-host/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/node-host/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAOH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,KAAK,EAAE,aAAa,EAAwB,MAAM,sBAAsB,CAAA;AAgB/E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AA2FvD,+CAA+C;AAC/C,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC/B;AAED,6CAA6C;AAC7C,MAAM,WAAW,aAAa;IAC5B,iDAAiD;IACjD,IAAI,CAAC,EAAE,aAAa,CAAA;IACpB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,gDAAgD;IAChD,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,mJAAmJ;IACnJ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IACnC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC7B,qCAAqC;IACrC,EAAE,EAAE,OAAO,CAAA;IACX,8CAA8C;IAC9C,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACjF,qDAAqD;IACrD,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,gEAAgE;IAChE,MAAM,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAA;CACnD;AAED,wDAAwD;AACxD,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,EAAE,EAAE,OAAO,CAAA;IACX,oCAAoC;IACpC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,kDAAkD;IAClD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CACjB;AAED,8CAA8C;AAC9C,MAAM,WAAW,cAAc;IAC7B,iFAAiF;IACjF,IAAI,CAAC,EAAE,aAAa,CAAA;IACpB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,gDAAgD;IAChD,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IACnC,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,8EAA8E;IAC9E,IAAI,CAAC,EAAE,QAAQ,CAAA;IACf,0EAA0E;IAC1E,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAA;CACnB;AAED,8DAA8D;AAC9D,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,EAAE,EAAE,OAAO,CAAA;IACX,oCAAoC;IACpC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,eAAe,GAAG,cAAc,CA6ClF;AAED;;;;;;;GAOG;AACH,wBAAsB,MAAM,CAC1B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,aAAa,GACnB,OAAO,CAAC,YAAY,CAAC,CA0DvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,SAAS;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,EACtE,SAAS,EAAE,SAAS,CAAC,EAAE,EACvB,aAAa,UAAQ,GACpB;IAAE,UAAU,EAAE,CAAC,EAAE,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAI1C;AAwID;;;;;;;;;;;GAWG;AACH,wBAAsB,OAAO,CAC3B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,cAAc,GACpB,OAAO,CAAC,aAAa,CAAC,CAqExB;AAgJD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IACzC,OAAO,EAAE,OAAO,GAAG,KAAK,GAAG,MAAM,GAAG,IAAI,CAAA;IACxC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,aAAa,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB,CA+CA;AAED;;;;;;GAMG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CA4HlG"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/node-host/cli.ts"],"names":[],"mappings":"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"}

package/dist/node-host/cli.js

@@ -105,8 +105,12 @@ const cliPortsLibLoader = {
         },
     },
 };
-/** 注入 libLoader 到 node ports（CLI 宿主白名单装载）。 */
-function withCliLibLoader(ports) {
+/**
+ * 注入 libLoader 到 node ports（CLI 宿主白名单装载）。Exported for executeScript (B6).
+ * @param ports - Node host ports to augment with the CLI lib loader.
+ * @returns The augmented ports (`libLoader` set to the CLI scoped-package loader).
+ */
+export function withCliLibLoader(ports) {
     return { ...ports, libLoader: cliPortsLibLoader };
 }
 /**
@@ -188,7 +192,7 @@ export async function cliRun(filePath, outPath, opts) {
     // 否则入口在子目录时它的 `./parts/x.fai.js` 会以根为基准解析而错位。
     const projectRoot = opts?.projectRoot ? resolve(opts.projectRoot) : findProjectRoot(filePath);
     const entryKey = projectKeyOf(projectRoot, filePath);
-    // Initialize OCCT and bind the vendored brepjs kernel registry (D10) so that
+    // Initialize OCCT and bind the brep engine registry (D10) so that
     // cq-compat parts (which project ops through compatFn) run end-to-end under
     // the CLI. registerOcctBrepEngine is idempotent and itself boots initOcctWasm.
     await registerOcctBrepEngine();
@@ -250,6 +254,76 @@ export function selectExportableTerminals(terminals, includeHidden = false) {
     const exportable = includeHidden ? [...terminals] : terminals.filter((t) => !t.hidden);
     return { exportable, hiddenCount };
 }
+/**
+ * 终端 BREP 句柄是否「可落成零件」——即含至少一个三维实体。
+ *
+ * **为什么需要它**：终端集合（`live-shapes.ts`）只回答「谁该被看见」，未消费的 2D 草图
+ * 同样是顶层未消费变量 ⇒ 也是终端 ⇒ 会走到导出层落一个 `.step`。而 2D 面片（实测厚度
+ * 2e-07、solids=0）一旦落盘，`fcstd-port` 的 `parity-judge.py merge_parts` 会把它的 area
+ * 加进真实件（5.04e+06 vs 5.50e+06 ⇒ ~91% 误差），parity 必 FAIL。所以「谁该被看见」与
+ * 「什么能落成零件」是两件事：本判据只管后者，不去动终端集合。
+ *
+ * **判决表**（实测标定，2026-10-06）：
+ * | shapeType | 判决 | 依据 |
+ * |---|---|---|
+ * | `SOLID` / `COMPSOLID` | 导出 | 真零件 |
+ * | `COMPOUND` | 含 ≥1 solid → 导出；否则跳过 | 装配体是 compound；`getSubShapes` 递归取子实体 |
+ * | `SHELL` | 含 ≥1 solid → 导出；否则跳过 | 旧栈基线 9/9 真实件皆 solid/compound；实测 8 个游离草图中 5 个顶层恰是 SHELL |
+ * | `FACE`/`WIRE`/`EDGE`/`VERTEX` | 跳过 | 无实体的 2D 片面 / 1D 线框 |
+ * | 其它（`SHAPE` 枚举兜底、空串） | 导出 | 保守，零回归 |
+ * | 无句柄（纯 mesh 终端） | 导出 | mesh 零件导出 STEP 是既有能力，不借本批收紧 |
+ *
+ * **`SHELL` 的裁决**：方案 §3 初稿把 shell 判为「导出（保留现状）」，理由是"面模型是合法
+ * 产物的先例存在"。但 2026-10-06 的 E-1 探针推翻了该前提：
+ * ① 旧栈 parity 基线（A 组 9 个真实件）顶层全为 `SOLID`/`COMPOUND`、`solids ≥ 1`，无一面模型；
+ * ② 新栈多出的 8 个游离草图中 **5 个顶层就是 `SHELL`** ⇒ 按初稿判决**根本拦不住**，方案失效；
+ * ③ `cli.ts` 改动前 0 处 shell 逻辑，不存在需要兼容的既有行为。
+ * ⇒ 改判为 **`SHELL` 且无子实体 → 跳过**。若日后语料真出现「合法的 2D 面模型产物」需求，
+ * 应由脚本侧或显式开关承接，而不是让导出层无法区分草图与零件（登记于相邻缺陷 D-2）。
+ *
+ * 实现上不分层递归：内核 `getSubShapes`（OCCT `TopExp_Explorer` 语义）对任意嵌套深度的
+ * compound **一次即可取到全部子实体**（E-1 探针：顶层 COMPOUND 的草图也能数出 solids=0）。
+ * 探针抛错 → **保守放行**（宁可多导一个，不可误删真零件）。
+ *
+ * @param shape - 终端 BREP 句柄（无句柄传 undefined）
+ * @param probe - shapeType/getSubShapes 提供者（生产用 `brepSolids` 条目的 kernel；测试可注入假 kernel）
+ * @returns 该句柄是否含至少一个实体（可落成零件）
+ */
+export function isExportableSolid(shape, probe) {
+    // 无 BREP 句柄（纯 mesh 终端）→ 导出（既有能力，零回归）。
+    if (!shape || !probe)
+        return true;
+    let type;
+    try {
+        type = probe.shapeType(shape).toUpperCase();
+    }
+    catch {
+        // 探针抛错（异常句柄）→ 保守放行。
+        return true;
+    }
+    switch (type) {
+        case 'SOLID':
+        case 'COMPSOLID':
+            return true;
+        case 'COMPOUND':
+        case 'SHELL':
+            // 无实体的 compound / shell = 2D 面片（游离草图）。`getSubShapes('solid')` 递归取子实体。
+            try {
+                return probe.getSubShapes(shape, 'solid').length > 0;
+            }
+            catch {
+                return true;
+            }
+        case 'FACE':
+        case 'WIRE':
+        case 'EDGE':
+        case 'VERTEX':
+            return false;
+        default:
+            // 枚举兜底（'SHAPE' / 空串 / 未知方言）→ 保守导出。
+            return true;
+    }
+}
 /** Export an executed result to `outPath` (shared body of cliRun's export path). */
 async function exportExecutionResult(outPath, ext, execResult, terminals, includeHidden = false) {
     const { exportable, hiddenCount } = selectExportableTerminals(terminals, includeHidden);
@@ -264,7 +338,32 @@ async function exportExecutionResult(outPath, ext, execResult, terminals, includ
             error: `All ${hiddenCount} live terminal(s) are hidden — nothing to export (pass includeHidden to export them)`,
         };
     }
-    if (exportable.length === 0) {
+    // ── 二维终端过滤（G0-D）──：终端集合回答「谁该被看见」，导出层回答「什么能落成零件」。
+    // 未消费的 2D 草图同样是顶层未消费变量 ⇒ 也是终端，但落成 `.step` 会污染 parity 的 area。
+    // 过滤后**不得**回退到「最后一个 output」，否则等于把刚剔除的草图从后门写回去。
+    const skipped2d = [];
+    let solidExportable = exportable;
+    if (!includeHidden) {
+        solidExportable = [];
+        for (const t of exportable) {
+            const entry = execResult.brepSolids?.get(t.id);
+            if (isExportableSolid(entry?.solid, entry?.kernel)) {
+                solidExportable.push(t);
+            }
+            else {
+                skipped2d.push(String(t.meta?.name ?? t.id));
+            }
+        }
+        if (solidExportable.length === 0 && exportable.length > 0) {
+            return {
+                ok: false,
+                error: `All ${exportable.length} live terminal(s) are 2D (no solid) — nothing to export as a 3D part` +
+                    (skipped2d.length > 0 ? ` (skipped: ${skipped2d.join(', ')})` : ''),
+            };
+        }
+    }
+    const solidInfos = skipped2d.length > 0 ? [`Skipped ${skipped2d.length} 2D terminal(s): ${skipped2d.join(', ')}`] : [];
+    if (solidExportable.length === 0) {
         // No terminals — use last output
         const outputNames = [...execResult.outputs.keys()];
         if (outputNames.length === 0) {
@@ -276,11 +375,12 @@ async function exportExecutionResult(outPath, ext, execResult, terminals, includ
             return { ok: false, error: `No output for part "${lastPartName}"` };
         }
         const solidEntry = execResult.brepSolids?.get(asPartName(lastPartName));
-        return writeOutput(outPath, ext, shape, solidEntry ? { solid: solidEntry.solid, kernel: solidEntry.kernel } : undefined);
+        const r = writeOutput(outPath, ext, shape, solidEntry ? { solid: solidEntry.solid, kernel: solidEntry.kernel } : undefined);
+        return solidInfos.length > 0 ? { ...r, infos: [...(r.infos ?? []), ...solidInfos] } : r;
     }
     // Single terminal
-    if (exportable.length === 1) {
-        const terminal = exportable[0];
+    if (solidExportable.length === 1) {
+        const terminal = solidExportable[0];
         const shape = execResult.outputs.get(terminal.id);
         if (!shape) {
             return { ok: false, error: `No output for terminal "${terminal.id}"` };
@@ -288,29 +388,32 @@ async function exportExecutionResult(outPath, ext, execResult, terminals, includ
         // Assembly (compound with behavior) → expand members with colors
         if (!('positions' in shape) || !('indices' in shape)) {
             const asmResult = writeAssemblyStep(outPath, ext, shape, execResult, hiddenTerminals);
-            if (asmResult)
-                return asmResult;
+            if (asmResult) {
+                return solidInfos.length > 0 ? { ...asmResult, infos: [...(asmResult.infos ?? []), ...solidInfos] } : asmResult;
+            }
         }
         const solidEntry = execResult.brepSolids?.get(terminal.id);
-        return writeOutput(outPath, ext, shape, solidEntry ? { solid: solidEntry.solid, kernel: solidEntry.kernel } : undefined);
+        const r = writeOutput(outPath, ext, shape, solidEntry ? { solid: solidEntry.solid, kernel: solidEntry.kernel } : undefined);
+        return solidInfos.length > 0 ? { ...r, infos: [...(r.infos ?? []), ...solidInfos] } : r;
     }
     // Multiple terminals — write each to a separate file
     // First, check if any terminal is a compound (assembly) — export it as a single STEP
-    for (let i = 0; i < exportable.length; i++) {
-        const terminal = exportable[i];
+    for (let i = 0; i < solidExportable.length; i++) {
+        const terminal = solidExportable[i];
         const shape = execResult.outputs.get(terminal.id);
         if (!shape)
             continue;
         if (!('positions' in shape) || !('indices' in shape)) {
             // Compound terminal — try assembly STEP export
             const asmResult = writeAssemblyStep(outPath, ext, shape, execResult, hiddenTerminals);
-            if (asmResult)
-                return asmResult;
+            if (asmResult) {
+                return solidInfos.length > 0 ? { ...asmResult, infos: [...(asmResult.infos ?? []), ...solidInfos] } : asmResult;
+            }
         }
     }
     // Then export non-compound terminals
-    for (let i = 0; i < exportable.length; i++) {
-        const terminal = exportable[i];
+    for (let i = 0; i < solidExportable.length; i++) {
+        const terminal = solidExportable[i];
         const shape = execResult.outputs.get(terminal.id);
         if (!shape)
             continue;
@@ -324,7 +427,7 @@ async function exportExecutionResult(outPath, ext, execResult, terminals, includ
         if (!result.ok)
             return result;
     }
-    return { ok: true, outputFormat: ext };
+    return { ok: true, outputFormat: ext, ...(solidInfos.length > 0 ? { infos: solidInfos } : {}) };
 }
 /**
  * 解析 `--view` 参数：三数字逗号串 → 方向对象（"1,-1,1" → { dir: [1,-1,1] }），
@@ -386,8 +489,8 @@ export async function cliView(filePath, outPath, opts) {
     const projectRoot = opts?.projectRoot ? resolve(opts.projectRoot) : findProjectRoot(filePath);
     const entryKey = projectKeyOf(projectRoot, filePath);
     // Initialize OCCT（投影 HLR 依赖 brep 内核）。registerOcctBrepEngine is
-    // idempotent and itself boots initOcctWasm, and also binds the vendored
-    // brepjs kernel registry (D10) — same boot path as cliRun above.
+    // idempotent and itself boots initOcctWasm, and also binds the
+    // brep engine registry (D10) — same boot path as cliRun above.
     await registerOcctBrepEngine();
     const ports = withCliProjectLoader(withCliLibLoader(createNodePorts({
         assetsDir: opts?.assetsDir,
@@ -554,6 +657,9 @@ function writeAssemblyStep(outPath, ext, compound, execResult, hiddenTerminals)
             // 与主导出路径同一判据（includeHidden 时 hiddenTerminals 传 undefined，不过滤）。
             if (hiddenTerminals?.has(String(key)))
                 continue;
+            // 同一 3D 判据：兜底路径直接遍历全体 brepSolids，2D 草图句柄同样会进这里（G0-D I-4）。
+            if (!isExportableSolid(solidEntry.solid, solidEntry.kernel))
+                continue;
             if (!kernel)
                 kernel = solidEntry.kernel;
             entries.push({