# geospec-engine 中文文档

规范地址：https://npmcn.com/package/geospec-engine/

版本：0\.5\.1
npm 元数据更新时间：2026-11-03T16:11:11.280Z
中文译文更新时间：2026-11-03T18:29:12.501Z
软件包许可：Apache-2\.0

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/geospec-engine
原文对照：https://npmcn.com/package/geospec-engine/?lang=original
项目主页：https://github.com/taucad/geospec/tree/main/packages/geospec-engine#readme
源码仓库：https://github.com/taucad/geospec

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：19.6 MB，183 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：0 个
- 首次发布：2026-10-12T04:05:43.627Z
- 最新版本发布：2026-11-03T16:11:10.758Z
- 已发布版本数：64（近 12 个月 64 个）

## 中文简介

便携式GeoSpec本机引擎

## 安装

```sh
npm install geospec-engine
```

也可以使用：`pnpm add geospec-engine`、`yarn add geospec-engine`、`bun add geospec-engine`

## README

# geospec-发动机

GeoSpec的单线程Rust分析引擎，带有自有的OCCT BRep桥和Rust歧管后端。

每个稳定版本都通过对其精确候选版本的发布资格认证 发布: 节点、CPython和浏览器矩阵、S10探测器和 回归运动。 `next` 预发行版不合格。结果是 可再生的。多线程，显式SIMD配置文件和GPU执行 延期。

## 公共接口

| 消费者 | 入口 | 执行 |
| --- | --- | --- |
| 节点 | `geospec-engine/node` | 达尔文arm64和Linux x64/arm64 glibc NAPI插件 |
| 浏览器或节点WASM | `geospec-engine` 或 `/wasm` | 一个结合Rust/OCCT的WASM模块 |
| Python | `geospec_engine_native` | CPython 3.13/3.14扩展 |
| 本地签名记录 | `geospec-engine/trust` | 在v1合同之外; 请参见 `trust/` |

JS出口 `Engine`， `canonicalize` 和 `ProtocolError`． WASM条目也是 出口异步 `initialize`;在构造热机之前调用它。它 接受附带的模块位置或显式WASM字节/URL。节点加载 没有WASM初始化的平台插件。

发动机操作包括 `ingestMesh`， `ingestSubject`， `subjectHandle`， `releaseSubject`， `processRequest`， `canonicalPlan`， `evaluatePlan` 和 `close`。 Python公开相应的snake\_case字节操作。主机发送普通 Uint8Arrays (Python: bytes)；Rust拥有验证，规范 计划、测量和结果序列化。资源伴随主要 对象按照摄取请求声明的顺序。

控制契约是协议 **3**,注册表 **5**， `geospec-jcs-v1`。 功能和允许的域来自引擎的初始化响应； 注册中心成员资格本身并不意味着每个主题/配置文件都支持查询。 支持的家族包括网格度量/完整性，STEP拓扑和事件， BRep特性和PMI，空间/CSG分析，以及单独的有界证明查询。 不支持或不充分的证据反而会产生明确的拒绝/错误 比一个几何过关，包括下否定。

进入和保留限制默认为入口配置文件 （`geospec-entry-config-v1`： 64 MiB的主题和资源，128 MiB的总二进制， 2 000 000个顶点，4 000 000个三角形，65 536次出现，256 MiB保留 分析，256个网格条目，256个可重复使用的CSG固体，32个保留的受试者)。一个 host在构造引擎时可以选择其他限制：Node `new Engine(cacheOptions, executionPermits, limits)`, WASM `new Engine(execution, limits)` 和Python `GeoSpecEngine(limits=...)` 接受 `maxSubjectBytes`， `maxResourceBytes`， `maxTotalBinaryBytes`， `maxVertices`， `maxTriangles`， `maxOccurrences`， `maxMeshBytes`， `maxMeshEntries`， `maxSolidEntries` 和 `maxRetainedSubjects` （Python中的snake\_case）。

每个限制必须是一个正整数，并且主题和资源限制必须 不超过总数的；其他的拒绝 `invalid-request`． 本地主机 可提高限制，以适应机器和任务。WASM默认值保持不变 条目配置文件，它适合wasm32地址空间。初始化响应 报告有效限制。除入口概要文件以外的任何配置 带有 `geospec-host-config-v1-…` 配置文件id从它的值派生，所以a 运行记录，限制它的使用。提高限制改变不了容忍或拒绝 规则。

超过限制的输入拒绝使用 `limit-exceeded`． 这个错误还包含 `GEOSPEC_RESOURCE_LIMIT` 或 `GEOSPEC_ANALYSIS_LIMIT` 有了极限类，单位， 限制和要求： `capacity` 在JS, `capacity_code` 和 `capacity_details` 在Python中。

`maxMeshBytes` 还限定了网格的工作记忆水密性分析 （`toBeWatertight`我宣布 `watertight` 在 `toHaveMeshIntegrity`， `analyzeMesh` 并进行网格重叠观察)和材料分析 在连接的组件后面。这一要求的分析需要更多的拒绝 与 `GEOSPEC_ANALYSIS_LIMIT` 在它分配超过限制之前，命名什么 它需要: `Watertight scratch needs …; the analysis limit is 256 MiB (268435456 bytes).`

使用 `geospec/assertion-client` 对于独立的JS主机组成， `geospec/vitest` Vitest的积分和车轮的积分 `geospec` 外观 以及Python的pytest插件。这些客户端保留来自的规范声明/结果 同样的引擎。Jest集成被推迟。现有的虚拟机运行程序有 在合格的产品组合中自动编译绑定。普通的撰写 测试使用 `loadModel` 从 `geospec/model` 和 `expectGeo` 从 `geospec`,而不是 一种发动机选择方言。完整的聊天资格仍然与 engine-package资格。

## 恒等与数值策略

规范计划将有序的主题、要求、极性、预算和数字绑定在一起 概要文件。规范JSON使用UTF-16键排序和有限的binary64呈现。 `canonicalize` 将JSON编码;它没有使语义声明规范化。确切的字节 平等适用于演示引擎配置文件，而不是不分青红皂白 在不同的数字后端或遗留版本之间。

`mesh-buffer-v1` 包含ASCII `GSM1`，小端u32顶点/三角形计数， 然后是f64坐标和u32三角形索引。文件摄取另外承认 STEP和glTF/GLB，声明坐标帧和资源标识。所有 glTF网格承载的三角形基元 `EXT_mesh_manifold` 对其 声明的POSITION访问器形成一个材料分区；单独的网格, 实例化节点和未声明的原语保持独立的操作数。 坐标、单位和变换必须由摄取契约表示； 单独的内容散列不能建立几何正确性。

OCCT删除了一些没有模式绑定的STEP属性值，例如 a的定义 `PROPERTY_DEFINITION` 这就是a `CHARACTERIZED_ITEM_WITHIN_REPRESENTATION`． 这台发动机只允许有间隙 列表，每个都有一个属性，没有GeoSpec事实读取，以及每个声明 然后受试者携带一个 `GEOSPEC_STEP_SCHEMA_GAP` 信息诊断每一种差距，与 `details` 命名步骤 `entity`, `attribute` 和 `count` 的 受影响的实体。该通知不改变索赔状态、主题散列或许可 诊断。

近似测量使用每个匹配器声明的公差和阈值 语义。浮点数不能保证一个数学上精确的标量 几何学。精确证书仅适用于其声明的允许域。

## 已配置的BRep特性度量

的数字过滤器 `toHavePlanarFace`， `toHaveCylindricalFace` 和 `toHaveCircularHole` 下 `evidence.witnesses.measurementContract.profile = "geospec-feature-metric-nominal-v1"`。 这些过滤器比较后端标称binary64测量值。平等使用 `abs(measured - expected) <= tolerance`;零容忍意味着名义上的平等， 不是一个精确的几何证书。地区条件保存作者 `>`， `>=`， `<` 和 `<=` 操作符，而不通过容差扩展它们。独立的 精度校准不添加运行时误差框或隐式epsilon。

平面法线分量和偏移量保持它们的共享符号约定。 圆柱轴标号选择分量的最大绝对方向，用 X /y/z顺序；标签不建立精确的轴向对齐。分析平面 或气缸后端标识仍然需要相应的库存。

测量合同只涵盖数字过滤器。圆孔会员 而通/盲拓扑需要单独的限定条件：电流 反向圆柱体和边界派生的库存不是合格的拓扑结构 证明。这种限制也阻止了将这些测量视为连续的 密封，间隙，插入，壁或无效保证。F1和F2证书 保留它们单独声明的允许域和验证契约。

## 开发和包装

使用工作区固定的pnpm/Nx工具链。原生Rust版本使用1.88.0； 混合构建需要其单独固定的Rust/Emscripten/OCCT工具闭包。 从工作区根目录：

```bash
pnpm nx run geospec-engine:build-node
# Set GEOSPEC_MIXED_INPUTS to a verified geospec-mixed-build-inputs-v1 manifest.
pnpm nx run geospec-engine:build-wasm
pnpm nx build geospec-engine
pnpm nx run geospec-engine:assemble-package
pnpm nx run geospec-engine:build-python
pnpm nx run geospec-engine:build-python314
```

`build-wasm` 和 `build-mixed-wasm` 选择相同的组合引擎构建驱动程序。 它检查声明的工具/输入哈希值，并写入构建收据。便携 `wasm32-unknown-unknown` 核心编译检查对于可移植性仍然很有用，但是 它的旧wasm- binding工件不是由这个包裹运送的。

Assembly生成带有精确版本可选的本地根/平台tarball 平台的依赖;它不发表。轮子包括Python断言 和pytest入口点。单独的构建收据不能建立已安装的包 正确性，支持平台或性能提升。

每个产品都建立在自己的主机上： `ci-native` 构建Darwin ARM64插件 在macOS, `ci-wasm` 在x86\_64 Linux上构建WASM模块，并且 `build` 包 放置于 `out/ci/`． 根包包含两个入口点。

源和重链接套件来自相同的主机： `scripts/ci-artifacts.mjs` `native-part` 在macOS和 `mixed-part` 在Linux上，在 `ci-wasm`，每个写 他们的份额，以及 `merge-parts` 将它们连接成 `out/relink/`． 综合达尔文 `prepare` 和 `ensure-delivery` 路线拒绝。一个显式的 `TAU_GEOSPEC_NATIVE_ASSEMBLY_ROOT` 可以选择合格的总成；它的包 布局和许可证关闭仍然有效。一个松散的工作区插件不是 一个组装。

所拥有的SDK安装是只读的，其字节码缓存被阻塞，因此 编译器字节码不能更改其记录的输入，即使作为根运行也是如此。 Emscripten选择的构建缓存保留在该SDK之外。

相关的Nx检查包括 `typecheck`， `lint`， `clippy-rust`， `format-rust`， `check-wasm` 中明确的一致性/基准目标 `project.json`。 严格的Clippy是静态正确性检查，而不是覆盖率度量。 当前一致性输入连接保留原始语料库并应用a 哈希固定，通过记录ID独立批准当前配置文件权限。

## 可信记录和剩余资格

`describeTrustedInputs` 派生权威机构可以独立确定的身份； `evaluateTrustedPlan` 运行经批准的声明性计划并签署其完整 通过呼叫者拥有的签名者验证记录。 `trust/verify.py` 验证 记录独立提供的政策和新的挑战。 执行记录的身份验证不是任意设计意图的证明 或者是关于敌对评估宿主的保证。

所需的首次发布目标是Darwin ARM64 with Node 24/26， CPython 3.13/3.14和Chromium/Firefox/WebKit。完全符合当前产品，至关重要 覆盖范围、安全/隔离资格、可重复的包封闭、 噪声感知性能门和UI/桌面集成仍然是发布门。 这里没有要求全引擎加速或完全释放资格。

## 常见问题

### geospec-engine 是什么？

便携式GeoSpec本机引擎

### 如何安装 geospec-engine？

在项目目录运行 npm install geospec-engine，或使用 pnpm add / yarn add / bun add。

### geospec-engine 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### geospec-engine 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### geospec-engine 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### geospec-engine 可以商用吗？

geospec-engine 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### geospec-engine 还在维护吗？

最新版本 0\.5\.1 发布于 2026/11/04（今天）；至今共发布 64 个版本，其中过去 12 个月发布了 64 个；首次发布于 2026/10/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。