API · SDK · MCP 参考PLW REST API 接入
版本 0.3.87。根路径为 /api/v1，请求与响应使用 JSON；文件上传和成果下载使用相应二进制传输。服务端以当前登录主体执行任务、资源及服务授权。
查看带 DGN 来源场景信息的兼容 GLB 时，可在同一视口查看配对实体与索引网格。点选实体面可核对元素、单元、面索引及实体内节点编号，并查看保留面或边归属的本地属性；点选网格面可核对原始元素内的面序号与带符号点索引。网格序号不作为 B-Rep 持久面编号，也不表示已解释原生业务属性。此类成果采用明确的诊断材质和显示比例，坐标不代表物理米；浏览器校验成果中的来源记录及显示几何，不重新读取原始 DGN，也不据此认定完整 DGN 导入或工程精度。任务继续使用现有上传、提交、查询和下载接口；DGN 源显示增加显式用途及未输出元素处理参数。
DGN 源显示兼容同时包含受验配对圆柱实体、索引网格的单模型 V8 CFB，并保留受验三维折线的原始顶点顺序，服务端需配置 Windows x64 独立读取运行时和受验组件。仅输出 GLB / DPEPack 的 LOD0 诊断场景，保留来源记录，不执行几何压缩、减面、焊接、轴向或物理单位覆盖。显示比例为原始 UOR 的 1/10000，坐标不代表物理米。折线保留线段来源及原始附属记录，未将这些记录认定为已解释的业务属性，原始线型外观须按兼容说明核对。当前配置、完整原生外观、V7、其它原生几何及完整 DGN 导入不在等价保证范围。未兼容的输入明确停止任务。
提交独立 .dgn 时，使用 targets: ["glb", "dpepack"] 及 options: {dgnProfile: "source-display", dgnRemainderPolicy: "report-unrendered", glbNodeMode: "preserve-scene", lod: 0, lods: false, compress: false}。report-unrendered 输出兼容几何并在 artifacts[].meta.sourceDGN.unrenderedRecords 逐项列出未输出元素；require-complete 遇未输出元素停止，以 PLW_DGN_TASK_INCOMPLETE_GEOMETRY 返回诊断。检查任务状态、警告及 sourceDGN，不能从任务完成状态推断整个原文件已完整导入。 服务端配置 PLW_DGN_PYTHON 和 PLW_DGN_PACKAGE_ROOT 为绝对路径；请求不能提供运行时或组件目录。
静态 GLB 场景保留支持原内嵌 PNG/JPEG 与 PBR/unlit 材质，保持原纹理引用、UV、采样器、属性及局部变换。此能力使用既有 glbNodeMode: 'preserve-scene'、LOD0 与 GLB/DPEPack 目标，请求与响应字段不变。
JT 源显示接受独立 .jt 的兼容 JT10.1/10.3 静态三角场景，仅接受单一内含根分区；无法解释的节点状态或嵌套分区停止任务。通过现有上传和任务接口提交，options 必须明确 jtProfile: 'source-display' 与 jtLodPolicy: 'first-source-child'；仅 glb / dpepack 目标、glbNodeMode: 'preserve-scene'、LOD0，无减面或坐标修改。jtMaterialMode 可为 source-coefficients（默认：源数值的 PBR 近似，未解决材质用明确诊断色）或 diagnostic。可设置布尔 compress，不接受其它编辑、执行路径或 ZIP 入口参数。Windows x64 服务通过 PLW_JT_PYTHON 配置独立 Python 读取运行时；/estimate 的 jtDisplay 返回运行时可用状态、版本及 64 MiB 源大小上限。未选择用途或分支、目标冲突及非法参数返回 400；运行时缺失返回 503，任务内不兼容源明确失败。
原始单位必须完整且一致，使用单一显示根矩阵归一为米并保留原局部矩阵。首个子分支仅依据原始顺序，不认定为原生当前配置或最高精度；源轴向按原数值方向保留，原生世界轴向、当前状态、完整外观、外部引用与 B-Rep 工程精度不在等价保证范围。GLB / DPEPack 的 asset.extras.plwOwnedJtDisplay 保留本地类型属性、原始发生路径和三角来源。共享几何发生项独立选择和显隐；浏览器核对已有记录与显示数组，不重新读取原始 JT；数组序号不作为 B-Rep 持久实体 ID。下载接口及其它格式请求不变。
3DXML XML Tessellation 的装配世界坐标在局部编码前使用双精度。同一包内的多个 ProductStructure 文档可通过文件名与局部 ID 建立引用，应用原装配矩阵，保留独立发生项、内联颜色及已有属性。资源按完整包内路径解析，缺失目录不按文件名补配；包外引用返回 PLW_3DXML_EXTERNAL_REFERENCE_UNSUPPORTED，目标 ID 缺失返回 PLW_3DXML_REFERENCE_MISSING，重复资源、循环及路径歧义均停止转换。二进制 CGR / V5_CFV3 继续返回 PLW_3DXML_BINARY_UNSUPPORTED。REST 请求与响应字段保持不变。
XML 网格支持同包内单层 Rendering 材质的漫反射、贴图和自发光，读取一维或二维 UV 通道 0，并将完整的 24 位 BI_RGB BMP（40 字节 BITMAPINFOHEADER，无 alpha） 图片无损编码为 PNG。支持显式原网格 UV 映射（IMPLICIT_MAPPING）、无额外变换的 MODULATE 纹理、CLAMP/REPEAT 和近邻/线性/三线性采样。材质原始属性及资源身份保存在 glTF 材质的 extras['3dxml-material']。同时有颜色与材质时采用 Rendering 材质显示，内联颜色另存于材质属性。Phong 高光、环境及反射与 PBR 的外观差异通过任务警告说明。未支持的材质层、图片编码、纹理变换、发生项材质或默认视图覆盖返回 PLW_3DXML_MATERIAL_UNSUPPORTED；缺失或损坏资源停止转换，不以无贴图模型交付。
构件业务属性 3dxml-attributes.OccurrenceTransforms 是 JSON 字符串，按根到表示发生项的顺序记录文档、局部 ID、发生项类型、矩阵声明位置、原始局部矩阵数值、实际局部矩阵与累积矩阵。矩阵使用 9 个按列排列的线性系数加 3 个毫米平移值；未声明矩阵的 declaredRelativeMatrix 为 null，其实际局部矩阵为单位矩阵。导出网格已应用这些变换，appliedToMeshWorldCoordinates 为 true，读取属性时不要重复施加。原始数值按解析后的双精度值保存，不承诺 XML 字面空白或数值文本逐字节相同。空值、重复或结构异常的已声明矩阵会停止转换。
静态 GLB 场景保留支持独立线段（glTF mode 1）和三角面（mode 4）。含线段时，成果 meta.lineSegments 记录发生项展开后的线段总数，meta.uniqueLineSegments 记录网格定义中的线段数；DPEPack 清单同时提供 scene.lineSegments、stats.expandedLineSegments 与 stats.uniqueLineSegments。三角数继续独立统计，原纯三角成果可省略线段字段。提交参数保持不变。
同一选项支持二进制 FBX 的静态三角网格与 Autodesk 材质代理引用：保留原节点、局部变换、实例、类型属性、逐面材质槽和原文件。当前该场景保留通道不接受动画、蒙皮、非三角面、标准材质或贴图；其他 FBX 可使用普通导入通道。代理引用未附颜色或贴图资源时，产物保留引用并报告外观未恢复，不能据材质名称推断颜色。REST 路径、请求字段和响应结构保持不变。
鉴权与能力查询
凭据由宿主传入 Authorization Bearer 或 X-Plw-Token 请求头。PiAdmin 部署复用漂视账号校验及租户身份。多个请求头应使用同一主体。健康检查返回当前版本和运行状态。
网页进入工作区时使用受保护的 /stats 确认当前凭据，成功后载入当前账号的数据；此步骤不主动轮换漂视令牌。/stats 只返回当前主体可见的统计并禁止缓存，未提供有效凭据时仍返回 401。令牌的定期刷新和显式退出沿用既有流程，REST、SDK 与 MCP 的请求签名不变。
Web 控制台在地址栏及本站会话缓存均无凭据时跳转到 https://piadmin.picimos.com/home，不附带 token 或 redirect，不建立登录后自动返回。此入口行为不改变 REST 路径、请求或响应结构。
| 方法 | 路由 | 内容 |
|---|---|---|
| GET | /health | 版本、运行状态、并发和鉴权模式 |
| GET | /stats | 已鉴权主体可见的任务统计，private/no-store |
| GET | /formats | outputs、inputSupport、upload 与转换参数 |
| GET | /sources | 当前主体可见的输入源 |
| POST | /uploads | multipart/form-data 文件上传，返回 path 与 uploadId |
转换与交付
| 方法 | 路由 | 内容 |
|---|---|---|
| POST | /tasks | 提交 sourcePath 或 uploadId、name、targets、options |
| GET | /tasks | 按 search、status、format 查询任务 |
| GET | /tasks/:id | 状态、转换报告与产物清单 |
| POST | /tasks/:id/cancel | 取消任务 |
| GET / HEAD | /tasks/:id/artifacts/:type/* | 读取所选文件或目录资源 |
| DELETE | /tasks/:id/artifacts/:aid | 删除单个产物：磁盘文件与清单条目一起移除，任务记录保留 |
| POST | /tasks/:id/deliver | 按 consumer、artifactId 登记并返回所选产物 |
{
"uploadId": "由上传响应取得",
"name": "工业模型",
"targets": ["glb", "dpepack"],
"options": {"glbNodeMode":"preserve-scene","lod":0,"lods":false,"compress":true}
}POST /tasks 可选传入 retryOf（旧任务 ID）。调用者须有该旧任务写权限，源路径、ZIP 入口、输出目标与当前共享重试方案的 options 必须一致；参数漂移返回 409，跨主体不可见来源返回 404。原任务不变，新任务的 request.retrySource 由服务端记录旧请求、错误和本次实际模式。省略 retryOf 继续使用原提交语义。
已知 RVM / ASCII REV 精度或原拓扑旧失败的兼容默认请求，可在网页点击“按保真模式重试 · LOD0”。这是一次明确的新模式选择；保留源局部坐标、层级与原拓扑，交付保真 LOD0。自定义高级设置和其它目标须先核对，不能通过此入口改变。此能力不声明普通 proto 简化消费者已支持这些源记录。
POST /tasks 成功返回任务 ID，随后查询该任务。产物 kind=file 时直接下载 uri；目录成果按清单中的相对路径逐个读取。交付请求中的 artifactId 应取自当前任务 artifacts[].id；省略时沿用整任务交付方式。交付响应保留产物摘要与 meta。
DELETE /tasks/:id/artifacts/:aid 需要任务写权限，并在一次请求内同时移除该产物的磁盘文件（目录产物为整个目录）与 artifacts 清单条目，随后写入 tasks-index.json。任务记录与状态保持 completed 不变，响应增加 purgedAt 供调用方区分「已完成」与「已完成、产物已清理」。任务处于 queued 或 running 时返回 409；产物不存在或已清理返回 404；artifactId 对应的目录已被外部删除时仍会收敛清单，不会残留幽灵条目。交付台账 deliveries 与属性变更审计 mutations 保留，属于历史记录。若该产物已被 GIS 私有服务版本引用，默认返回 409 并附带 references；服务版本保存的是发布时复制的独立副本，不受删除影响，调用方确认后以 ?force=1 重试。
任务状态包括 queued、running、completed、failed、cancelled。错误响应携带 error，相关转换错误可含 diagnosticCode。失败详情与转换报告按任务保存，调用方保留任务 ID 以便查询和取消。
普通 GLB 预览的构件投影以成果文件 SHA-256 和 glTF 节点编号标识当前文件的发生项；原节点 extras 与原父子关系供预览查询。此界面更新沿用现有 REST 请求和产物字节。
属性与 GIS
业务属性单行或批量编辑分别使用 PATCH /tasks/:id/artifacts/dpepack/attributes/biz/rows/:cid 与 PATCH /tasks/:id/artifacts/dpepack/attributes/biz/bulk。写入前由服务端检查任务权限与属性字段。
GIS 切片、服务发布、查询、暂停与资源访问沿用当前服务提供的 REST 路由；MCP 的 GIS 工具定义同步列出对应参数。私有下载及服务资源使用与任务相同的身份。
参数与数据
原型装配 GLB 未指定 options.glbNodeMode 时使用 source-hierarchy，并要求 lod=0。构件位置存放在普通 glTF 节点中。显式 instancing 支持相应 LOD，但目标读取器必须支持文件声明为必需的 EXT_mesh_gpu_instancing；未指定节点方式的高 LOD 请求会拒绝，不会自动切换到实例扩展。已有场景保留通道的源节点及压缩契约继续适用，请求字段和接口路径不变。
glbNodeMode=preserve-scene 使用源场景层级；linearDeflection、linearDeflectionType 和 angularDeflection 控制相应 CAD 通道的显示网格。具体请求参数、源身份和成果统计保存在任务报告及产物元数据中。读取字节数和 SHA-256 时使用服务器返回的原始值。
登录验证：401 表示需要重新登录；业务权限或配额的 402/403 不结束当前会话。上游登录验证暂时不可用时返回 503（PLW_PIADMIN_AUTH_UNAVAILABLE），客户端保留会话并重试。接口路径和请求格式保持不变。
显式离线显示减重
已转换的米制静态原型 DPEPack 可通过 node bin/optimize-model-pack.js model.dpepack display.glb --lod 2 --small-part-mm 30 --merge-materials 导出显示减重版。尺寸过滤按原 LOD0 构件包围盒的最大边长判断，单位毫米；原材质数值保留。同材质合并会改变单构件选择粒度，原 ID 和过滤清单保存在输出旁的 JSON。默认使用 meshopt 压缩，接收端须支持对应扩展；无压缩输出使用 --no-compress。材质合并仅兼容无贴图、无顶点色且有源法线的静态三角网格，未兼容属性明确停止。详见 docs/offline-mesh-reduction.md。
该能力为显式离线命令，不自动接入普通转换任务。现有 REST 路由/参数、MCP 工具名称/schema 和 JavaScript SDK 方法均保持不变；现有按三角数处理的小构件参数不等同于此尺寸阈值。
诊断场景的显示单位
诊断坐标显示产物在视口、测距和导航中使用显示单位，不能据此解释为米或原生物理尺寸。诊断材质不表示原生外观；查看器读取显示产物中的声明和属性，不重新读取原始工业文件，也不由预览推断整类原生导入完成。现有任务、REST、MCP及JavaScript SDK接口和原生输入兼容范围保持不变。
带有明确 RVT 原始属性档案声明的 GLB 可沿用“完整场景保留”通道。预览中选中构件后可只读查看源文件保存的参数、全部字段及原始 JSON，并沿类型、族、标高、管段及材质引用查阅关联记录，类型参数与管段材质保持各自的原始记录；属性档案随模型保存，不依赖源 RVT 路径。原始保存值不代表公式已重新计算，也不代表完整 RVT 几何、材质和外观已通过转换验收。REST、MCP 与 SDK 的方法、参数及返回字段保持不变；属性面板不新增远程文件读取接口。对明确声明为未放置类型定义的档案，原始几何记录随模型保留，且不计入项目实体的渲染和构件数量。此类记录的父级与放置字段仍属源数据，不能据此认定原生可编辑枢轴或完整实例范围已经通过验收。交付验收应区分实体实例、类型定义与目录容器，并逐项核对原始构件身份、父级、参数和外观，并在实际显示分辨率下检查旋转、缩放及选中时的帧率与表面稳定性。参数档案完整或转换任务成功，不能替代这些检查。RVT 导入对象所引用的外部图形、字体及材质资源应随原工程提供。仅保留引用、没有图形缓存的对象无法据此恢复其显示内容；原始属性档案仍可保留这些引用和参数。源构件的 UniqueId 与当前记录定位编号分别保留；两者编号不同时，按源索引对应关系核验，不能改写原始身份。
对已核验的原生曲面，模型保留构件及类型的原始图形记录、源材质引用、参数与层级。转换后按源面核对位置、法线及索引的一致性，有效阶段引用仍可查阅。无法完整解读边界的构件保持未通过状态。REST、MCP 与 JavaScript SDK 的公开方法、参数及返回字段保持不变。
对边界可完整核实的非等参直纹面交线，转换按两侧原始曲面和完整参数范围恢复显示边界，并逐面校验法线、覆盖及编码后的闭合性。原始双 UV、图形记录、实际材质引用和全部随包属性继续保留；无法唯一核实的交线仍报告兼容性限制。此项不表示整份原生模型或缺失的材质资源已通过验收，REST、MCP 与 JavaScript SDK 的公开方法、参数及返回字段保持不变。
对可唯一核实的原始平面墙体交点，转换保留完整原始图形与显式 UV 派生记录，并校验原始拓扑、交点范围、材质引用、法线及实际编码缓冲区；预览和再次压缩时执行相同的来源校验。楼层、阶段、类型和填充参数继续作为原始属性保留。该能力不替代缺失的外链或外部材质资源，无法完整核实的几何仍报告兼容性限制；REST、MCP 与 JavaScript SDK 的公开方法、参数和返回字段保持不变。
对已完整核实、但直接编码后会退化的窄小墙体，转换可使用独立的局部显示坐标节点，保留原始构件坐标、顶点、法线、索引和层级。加载与再次压缩时同时校验局部坐标、原始交点、完整面覆盖及实际显示缓冲区，并保持原有位置误差范围；不满足条件的几何仍报告兼容性限制。REST、MCP 与 JavaScript SDK 的公开方法、参数和返回字段保持不变。
兼容转换包可压缩保存解析校验记录，加载时校验并还原原值，源参数及材质绑定保持保留。受支持平面的显示三角形划分可在面内调整，并保留完整原始索引；面边界、三角形总数和法线须保持一致。此项不扩大原生格式或原始外观的兼容范围，REST、MCP 和 SDK 的既有方法签名不变。 材质来源记录随兼容包校验还原；档案不完整或校验失败时拒绝加载。源参数和材质来源中的数值保留负零符号，既有材质绑定与源记录引用保持不变。 对于已核验的幕墙宿主与面板引用，PLW 预览区分内部宿主几何与可见面板；宿主原始几何、身份、参数和父子关系仍随包保留。加载前核对随包原始记录，引用缺失或不一致时拒绝加载。此项不代表完整建筑几何和原始外观已经通过验收，既有 REST、MCP、SDK 方法签名保持不变。 已解析的源材质图形颜色或外观预览色，在 GLB 中按标准线性 RGB 编码，原始 RGB 字节与透明度记录保持保留。预览的不透明度范围为 0–100%，包含完全透明；此范围不改变原始参数，也不代替纹理与完整外观验收。REST、MCP 与 SDK 方法签名保持不变。 对同时包含原始平面和圆柱面的兼容构件，依据可唯一核实的原始共边坐标表达显示边界，并保留原始图形记录、参数和面样式引用。加载时校验原始身份、UV 历史及几何覆盖；不能唯一核实时仍报兼容性未通过。此项不代表完整 RVT 几何、材质外观或帧率验收，REST、MCP 与 SDK 既有方法签名保持不变。 对兼容曲面，预览可采用有来源校验的舍入退化处理：仅排除编码后已无面积且原始端点位于双精度舍入范围内的绘制项；完整原始索引、面引用、属性、材质和层级继续随模型保存。未满足条件时仍报告兼容性限制。 对具有可验证共面四边形的兼容网格，显示时可仅交换同一面内的内部对角线；保留原始索引存档、完整面边界、三角形总数、顶点、法线、材质及层级。局部显示原点可取自原始边界、顶点，或使用边界中心搭配单个原始坐标分量，并继续校验世界坐标误差、朝向和闭合性；不扩大原生几何或外观的验收范围。 对已编码为零面积的绘制项，还可采用独立的来源容差校验；仅在原有来源拼接预算内、完整源面仍被表示且非零线框边集合不变时优化绘制索引。原始索引、顶点、法线、属性和层级继续保留，校验不通过时仍拒绝兼容。 对受支持的共线退化绘制项，可在严格来源校验下验证同一源面的精确线段覆盖和相应法线，并将完整原始索引无损压缩随包保存。加载时按声明预算回读索引档案；超限、损坏或来源不符的档案拒绝加载，不据此省略原始构件或扩大原生几何验收范围。 对同一兼容构件中互不相交的原始面，可按声明顺序组合面内对角线调整与共线零面积绘制处理；各步骤独立回读校验，完整原始索引、源面、顶点、法线、材质、属性和层级继续保留。源面重叠、步骤次序或数据校验不符时拒绝加载。 对具有可核实重叠剖分的兼容不透明楼板，可逐步校验原始平面的覆盖关系及局部替换前后表面并集相等，并无损保存完整原始双精度顶点、法线和索引。每个原始面仍保留显示表示，材质绑定、参数及源层级不变；不支持的材质映射或不能核实的几何继续报告兼容性限制。 平面边界的兼容读取同时校验原始实体内的端点见证、源面范围及闭合关系，并保留原始 UV 和图形记录；不满足核验要求时仍报告兼容性限制。 构件目录支持按名称、构件编号及保留的原始元素 ID、源 UID 搜索，便于定位同名构件并查看源参数。
兼容 RVT 便携模型可使用无损压缩的原始属性档案，按构件读取时还原原始 JSON 字节，保留大整数及负零等保存值。属性档案随模型交付，不依赖源 RVT 路径或外部属性服务；旧版兼容档案仍可读取。无法识别的档案版本、压缩声明或校验失败会明确报错。此行为不表示缺失的外部资源、原始几何或材质外观已恢复；REST、MCP 与 JavaScript SDK 的公开方法、参数及返回字段保持不变。
同一模型无损重新封装后，可继续读取随包保存的原始属性。每次导入仍校验属性档案的完整性；档案声明或压缩内容不一致时拒绝加载。
兼容的柔性管解析结果可按原始曲面和封闭边界保留显示几何，并保留源面记录、材质引用及保存参数。曲面边界或显示状态无法核实时，构件仍标为未通过。几何恢复不表示源材质外观或整个原生模型已经完成转换验收；REST、MCP 与 JavaScript SDK 的公开方法、参数及返回字段保持不变。相邻圆柱段沿轴向连接的兼容圆弧边界，还须核对两侧原始曲面、参数范围及完整闭合构件；无法核实的边界继续保留未通过状态。兼容的复合封闭构件按原始边界连接关系分别核验各封闭部分，保留接触位置的全部原始面及构件身份；渲染坐标调整只作用于显示表示。重复导入同一源文件时，兼容的无损属性存储布局会核对全部原始记录及定义几何；原始内容不一致时拒绝复用属性缓存。DPE 中兼容的源构件批处理保留原始层级与属性，透明度后处理使用当前渲染表示；源构件的材质与编辑状态继续随工程保存。
普通 FBX 材质无法忠实转换时，任务以 PLW_FBX_MATERIAL_CONTRACT_UNSUPPORTED 停止，错误说明包含源材质、源贴图 ID 及具体缺项。程序贴图缺少可验证的 Mono/Output 设置，以及非零或未知强度的未支持渲染器反射，均不会自动退化为单文件贴图或常量颜色。REST 路径、提交参数和响应结构保持不变。
官网统计（外部接口）
官网向 https://api.picimos.com 发送 JSON 请求，产品类型固定为数字 type: 1（PLW）。匿名访问可上报，有本站 PiAdmin 登录态时通过 Authorization 头携带凭据；不发送离线管理员授权码或模型数据。以下接口不是 PLW /api/v1 路由，不修改现有下载清单、转换、任务及产物接口。
| 方法与路由 | 时机与参数 |
|---|---|
| POST /client/report/download | 点击下载列表中的安装包；type、clientType、platformCode、clientVersion、source=website、resourceId、downloadUrl、os |
| POST /client/report/online/heartbeat | 同一标签页会话首次打开官网时调用一次；type=1、sessionId、clientType=web、platformCode=web、clientVersion、status=1 |
下载版本、资源名和地址取自实际安装包链接。平台映射为 Windows 10/11 → windows/win10_win11，Windows 7 → win7/win7，macOS ARM64/Intel → macos/macos_arm64 或 macos/macos_intel，Linux x64/ARM64 → linux/linux_x64 或 linux/linux_arm64。下载接口记录点击而非下载完成；心跳统计在线会话和时长，并非独立 PV 接口。
官网仅进行单次打开上报，不执行定时心跳、离线上报或失败重试。通过 sessionStorage 记录当前标签页已尝试上报，刷新和同一标签页返回不重复调用；独立新标签页会话可再次上报。浏览器禁用会话存储时只能保证当前页面内不重复，刷新去重不可保证。此模式不用于持续在线人数或在线时长统计；服务端仍可能按其超时规则将会话置离线。成功响应为 {code:0,msg,data}，HTTP、业务或网络错误不阻断页面和下载，不修改下载列表。
脚本通过 GET /api/v1/health 获取实际服务版本并确认在线部署，离线客户端不启用官网统计。下载清单为空时不生成下载记录，也不影响单次打开上报。部署需要允许官网来源跨域调用上述接口及 Content-Type、Authorization 请求头。REST 转换接口、MCP 工具及 SDK 方法签名保持不变。
批量任务沿用现有 POST /api/v1/tasks 逐个提交，分别保存返回的任务 ID。REST、MCP 与 JavaScript SDK 方法、参数和响应字段保持不变。响应未确认时先查询已有任务，再决定是否重试。
原生 CAD 失败阶段观察
GET /tasks/:id 返回的可选 diagnostics.nativeCadProgress 使用 profile native-cad-completed-phases/1。completed 最多包含四条 {phase, elapsedMs}：phase 为 read、transferred、meshed 或 done，elapsedMs 是读取器自启动起报告的累计毫秒数，并非单阶段耗时。只返回已观察到的完整记录；字段或阶段缺省不表示耗时为零。
lastReportedCompletedPhase 是最后一条记录的阶段名；phaseOfFailureKnown 为 false，不能将其后续阶段认定为故障位置。done 仅表示读取器报告结束，随后产物统计或完整性检查仍可能拒绝任务。继续检查任务 status、error、diagnosticCode 和已验证产物。该阶段观察对象不包含原生 stdout、模型名称或源路径；请求参数及既有错误字段不变。
PLW JavaScript SDK 接入指南
版本 0.3.87。使用标准 fetch 将上传、提交、查询和交付接入现有应用。base、token、sourcePath 由宿主运行时传入；调用方保存 onSubmitted 返回的任务 ID，并通过 signal 取消等待。
查看带 DGN 来源场景信息的兼容 GLB 时，可在同一视口查看配对实体与索引网格。点选实体面可核对元素、单元、面索引及实体内节点编号，并查看保留面或边归属的本地属性；点选网格面可核对原始元素内的面序号与带符号点索引。网格序号不作为 B-Rep 持久面编号，也不表示已解释原生业务属性。此类成果采用明确的诊断材质和显示比例，坐标不代表物理米；浏览器校验成果中的来源记录及显示几何，不重新读取原始 DGN，也不据此认定完整 DGN 导入或工程精度。任务继续使用现有上传、提交、查询和下载接口；DGN 源显示增加显式用途及未输出元素处理参数。
DGN 源显示兼容同时包含受验配对圆柱实体、索引网格的单模型 V8 CFB，并保留受验三维折线的原始顶点顺序，服务端需配置 Windows x64 独立读取运行时和受验组件。仅输出 GLB / DPEPack 的 LOD0 诊断场景，保留来源记录，不执行几何压缩、减面、焊接、轴向或物理单位覆盖。显示比例为原始 UOR 的 1/10000，坐标不代表物理米。折线保留线段来源及原始附属记录，未将这些记录认定为已解释的业务属性，原始线型外观须按兼容说明核对。当前配置、完整原生外观、V7、其它原生几何及完整 DGN 导入不在等价保证范围。未兼容的输入明确停止任务。
提交独立 .dgn 时，使用 targets: ["glb", "dpepack"] 及 options: {dgnProfile: "source-display", dgnRemainderPolicy: "report-unrendered", glbNodeMode: "preserve-scene", lod: 0, lods: false, compress: false}。report-unrendered 输出兼容几何并在 artifacts[].meta.sourceDGN.unrenderedRecords 逐项列出未输出元素；require-complete 遇未输出元素停止，以 PLW_DGN_TASK_INCOMPLETE_GEOMETRY 返回诊断。检查任务状态、警告及 sourceDGN，不能从任务完成状态推断整个原文件已完整导入。 SDK 的函数签名保持不变，通过现有 options 传递上述显式字段。
直接 JT 源显示使用已有上传、提交与查询函数，将下列参数传给任务接口：targets: ['glb', 'dpepack']，options: {jtProfile: 'source-display', jtLodPolicy: 'first-source-child', jtMaterialMode: 'source-coefficients', glbNodeMode: 'preserve-scene', lod: 0, lods: false, compress: true}。只接受独立兼容 JT10.1/10.3 静态三角场景及单一内含根分区，无法解释的节点状态或嵌套分区停止任务。Windows x64 服务需配置独立读取运行时。源单位须完整一致；源分支按原始顺序选择，不认定为当前配置或最高精度。源轴向保持数值方向，完整原生外观、世界轴向、外部引用及 B-Rep 精度不在等价保证范围。jtMaterialMode: 'diagnostic' 可使用统一诊断色；源系数模式为 PBR 近似且未解决材质同样使用诊断色。检查任务状态与警告后再下载，不将失败任务作为部分成功交付。
源记录位于 asset.extras.plwOwnedJtDisplay，按原始发生路径关联类型属性，保留共享几何发生项的独立选择和显隐。三角来源的数组序号不作为 B-Rep 持久实体 ID。浏览器核对已下载的显示场景，不重新读取原始 JT。现有 SDK 函数签名和下载流程不变，增加 JT 的显式任务选项。
3DXML XML Tessellation 沿用现有提交参数；装配坐标在局部编码前保留双精度，支持同包内 ProductStructure 文档之间的明确引用。构件属性包含来源文档、表示文档、几何条目和发生项文档路径，可区分不同文档中相同的局部 ID。调用方应读取任务错误和警告：包外引用以 PLW_3DXML_EXTERNAL_REFERENCE_UNSUPPORTED 停止，目标 ID 缺失以 PLW_3DXML_REFERENCE_MISSING 停止，二进制 CGR / V5_CFV3 以 PLW_3DXML_BINARY_UNSUPPORTED 停止。JavaScript SDK 的函数签名和请求字段保持不变。
同包 XML 材质支持单层 Rendering 漫反射、贴图、自发光，以及 UV 通道 0 的一维和二维坐标；完整的 24 位 BI_RGB BMP（40 字节 BITMAPINFOHEADER，无 alpha） 图片无损转为 PNG。纹理限于显式原网格 UV 映射（IMPLICIT_MAPPING）、无额外变换的 MODULATE、CLAMP/REPEAT 与近邻/线性/三线性采样。可从 glTF 材质的 extras['3dxml-material'] 读取原始属性和资源身份。同时有颜色与材质时采用 Rendering 材质显示，内联颜色另存于材质属性。Phong 与 PBR 的高光、环境及反射差异保留任务警告；未支持的材质、编码、纹理变换和发生项覆盖以 PLW_3DXML_MATERIAL_UNSUPPORTED 停止，缺失或损坏资源也不会交付无贴图模型。
读取构件的 3dxml-attributes.OccurrenceTransforms JSON 字符串可核对各级原始局部矩阵和累积矩阵数值、所属文档与发生项 ID。每个矩阵为 9 个按列排列的线性系数加 3 个毫米平移值；未声明矩阵以 declaredRelativeMatrix: null 区别于显式单位矩阵。网格已应用变换（appliedToMeshWorldCoordinates: true），这些字段用于检查源装配，不应再作为 glTF 节点变换应用。空值和重复矩阵声明停止转换。
提交兼容的静态 GLB 时，场景保留沿用 glbNodeMode: 'preserve-scene'、LOD0 与 GLB / DPEPack 目标。线段数量从成果 meta.lineSegments 读取，网格定义线段数量从 meta.uniqueLineSegments 读取；字段缺省时不应从三角数推算线段。线段和三角面混合的成果分别核对两类计数，SDK 函数签名保持不变。
接入方可用带同一凭据的 GET /api/v1/stats 确认 PLW 会话，健康检查不作为登录证明。网页首次进入工作区进行该项校验；宿主继续负责定期刷新凭据。现有参数语义保持，SDK 新增可选 retryOf，MCP 新增可选 retry_of，用于显式关联旧任务。
查询能力并提交任务
async function convertWithPLW({ base, token, sourcePath, targets, options = {}, retryOf, signal, timeoutMs = 300000, onSubmitted }) {
if (onSubmitted !== undefined && typeof onSubmitted !== 'function') throw new TypeError('onSubmitted 必须是函数');
const origin = new URL(base).origin;
const started = Date.now();
async function request(route, body) {
const remaining = timeoutMs - (Date.now() - started);
if (remaining <= 0) throw new Error('转换等待超时，请保留任务 ID 后查询');
const timeout = AbortSignal.timeout(remaining);
const response = await fetch(origin + route, {
method: body === undefined ? 'GET' : 'POST', redirect: 'error',
signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
headers: { ...(token ? { Authorization: 'Bearer ' + token } : {}),
...(body === undefined ? {} : { 'Content-Type': 'application/json' }) },
...(body === undefined ? {} : { body: JSON.stringify(body) })
});
const value = await response.json();
if (!response.ok) throw new Error(value.error || ('HTTP ' + response.status));
return value;
}
let taskId;
try {
const capabilities = await request('/api/v1/formats');
// 宿主展示 capabilities.inputSupport 与 formats 中的 available/限制。
const task = await request('/api/v1/tasks', { sourcePath, targets, options, ...(retryOf===undefined?{}:{retryOf}) });
taskId = task.id;
await onSubmitted?.({ taskId }); // 宿主此时持久保存任务编号。
for (;;) {
const current = await request('/api/v1/tasks/' + encodeURIComponent(taskId));
if (current.status === 'completed') return { task: current, capabilities };
if (!['queued', 'running'].includes(current.status)) {
throw Object.assign(new Error('任务未完成：' + current.status), { task: current });
}
await new Promise(resolve => setTimeout(resolve, 1000));
}
} catch (error) {
const failure = error instanceof Error ? error : new Error(String(error));
if (taskId) failure.taskId = taskId;
throw failure;
}
}场景保留选项为 {glbNodeMode:'preserve-scene',lod:0,lods:false,compress:true}。界面先读取 formats.outputs、inputSupport 与 upload，再提供对应参数。
二进制 FBX 的静态三角网格可使用相同选项输出 GLB / DPEPack，保留局部变换、原节点、共享几何、类型属性及 Autodesk 逐面材质代理引用。此通道不接受动画、蒙皮、非三角面、标准材质或贴图。原文件未包含代理的颜色或贴图时，应检查任务说明中的外观缺失信息；代理 ID 和材质名称不代表颜色已经恢复。SDK 方法和参数名称不变。
原型装配 GLB 的默认选项为 {glbNodeMode:'source-hierarchy',lod:0}，以普通节点保存构件位置和装配目录。使用高 LOD 或显式 {glbNodeMode:'instancing'} 前，确认目标读取器支持 EXT_mesh_gpu_instancing；该模式的独立 GLB 将此扩展声明为必需。既有 SDK 调用保持兼容。
静态 GLB 的场景保留同时交付原内嵌 PNG/JPEG、PBR/unlit 材质与原纹理/UV/采样绑定；节点、属性、局部变换和几何视图保持原数据。请求与响应字段不变。
普通 GLB 预览按原场景节点提供构件目录及原 extras 查询，文件内共享几何的多个发生项独立选择和显隐。既有 SDK 调用保持兼容。
精确产物交付
从 completed 任务的 artifacts 中选择产物，向 POST /api/v1/tasks/:id/deliver 提交 {consumer:'dpe-editor',artifactId:artifact.id}。按响应下载成果并在目标编辑器中确认导入。目录成果依据 manifest 和相对资源路径读取。
产物清理
单个产物使用 DELETE /api/v1/tasks/:id/artifacts/:artifactId 删除。服务端在一次请求内同时移除磁盘文件与 artifacts 清单条目，任务记录保留并写入 purgedAt，宿主据此把「已完成」显示为「已完成、产物已清理」。任务处于 queued 或 running 时返回 409；产物不存在或已清理返回 404；被 GIS 私有服务版本引用时返回 409 并附带 references，确认后以 ?force=1 重试——服务版本是发布时复制的独立副本，不受影响。删除成功后重新拉取 GET /api/v1/tasks，不要沿用本地缓存的产物清单。任务删除、交付协议与 MCP 工具签名保持不变。
登录与资源访问
Web 控制台无地址栏凭据且无缓存会话时直接跳转 PiAdmin 首页，不设置登录回调。宿主从工作台打开 PLW 时仍可传入 token，已有会话继续复用。此变更不修改 REST、MCP 工具或 SDK 方法签名。
认证信息只在宿主运行时使用。切换账号或退出登录时取消当前请求并清空上一账号的界面数据；新的请求使用当前身份。在线上传的文件先保存至企业云盘，再由服务端按需拉取用于转换；离线客户端使用本地上传。
PiAdmin 登录刷新返回新凭据时，后续请求使用刷新后的凭据。业务 402/403 按权限或配额处理；登录验证临时 503 保留会话并重试，401 才重新登录。REST、MCP 和 SDK 的既有调用保持兼容；可选重试参数用于显式关联旧任务。
旧任务重试可选传入 retryOf；sourcePath、targets 和 options 必须来自当前重试方案。服务端验证旧任务写权限、固定来源与参数后保存 request.retrySource。网页共享模块 /task-retry-options.js（PLWTaskRetryOptions.plan）使用与后端相同的方案；SDK 不会自行改写普通提交参数。MCP convert_model 的 retry_of 可读取旧任务并使用共享方案，不能同时附加自定义覆盖参数。
显式离线显示减重
已转换的米制静态原型 DPEPack 可通过 node bin/optimize-model-pack.js model.dpepack display.glb --lod 2 --small-part-mm 30 --merge-materials 导出显示减重版。尺寸过滤按原 LOD0 构件包围盒的最大边长判断，单位毫米；原材质数值保留。同材质合并会改变单构件选择粒度，原 ID 和过滤清单保存在输出旁的 JSON。默认使用 meshopt 压缩，接收端须支持对应扩展；无压缩输出使用 --no-compress。材质合并仅兼容无贴图、无顶点色且有源法线的静态三角网格，未兼容属性明确停止。详见 docs/offline-mesh-reduction.md。
该能力为显式离线命令，不自动接入普通转换任务。现有 REST 路由/参数、MCP 工具名称/schema 和 JavaScript SDK 方法均保持不变；现有按三角数处理的小构件参数不等同于此尺寸阈值。
诊断场景的显示单位
诊断坐标显示产物在视口、测距和导航中使用显示单位，不能据此解释为米或原生物理尺寸。诊断材质不表示原生外观；查看器读取显示产物中的声明和属性，不重新读取原始工业文件，也不由预览推断整类原生导入完成。现有任务、REST、MCP及JavaScript SDK接口和原生输入兼容范围保持不变。
带有明确 RVT 原始属性档案声明的 GLB 可沿用“完整场景保留”通道。预览中选中构件后可只读查看源文件保存的参数、全部字段及原始 JSON，并沿类型、族、标高、管段及材质引用查阅关联记录，类型参数与管段材质保持各自的原始记录；属性档案随模型保存，不依赖源 RVT 路径。原始保存值不代表公式已重新计算，也不代表完整 RVT 几何、材质和外观已通过转换验收。REST、MCP 与 SDK 的方法、参数及返回字段保持不变；属性面板不新增远程文件读取接口。对明确声明为未放置类型定义的档案，原始几何记录随模型保留，且不计入项目实体的渲染和构件数量。此类记录的父级与放置字段仍属源数据，不能据此认定原生可编辑枢轴或完整实例范围已经通过验收。交付验收应区分实体实例、类型定义与目录容器，并逐项核对原始构件身份、父级、参数和外观，并在实际显示分辨率下检查旋转、缩放及选中时的帧率与表面稳定性。参数档案完整或转换任务成功，不能替代这些检查。RVT 导入对象所引用的外部图形、字体及材质资源应随原工程提供。仅保留引用、没有图形缓存的对象无法据此恢复其显示内容；原始属性档案仍可保留这些引用和参数。源构件的 UniqueId 与当前记录定位编号分别保留；两者编号不同时，按源索引对应关系核验，不能改写原始身份。
对已核验的原生曲面，模型保留构件及类型的原始图形记录、源材质引用、参数与层级。转换后按源面核对位置、法线及索引的一致性，有效阶段引用仍可查阅。无法完整解读边界的构件保持未通过状态。REST、MCP 与 JavaScript SDK 的公开方法、参数及返回字段保持不变。
对边界可完整核实的非等参直纹面交线，转换按两侧原始曲面和完整参数范围恢复显示边界，并逐面校验法线、覆盖及编码后的闭合性。原始双 UV、图形记录、实际材质引用和全部随包属性继续保留；无法唯一核实的交线仍报告兼容性限制。此项不表示整份原生模型或缺失的材质资源已通过验收，REST、MCP 与 JavaScript SDK 的公开方法、参数及返回字段保持不变。
对可唯一核实的原始平面墙体交点，转换保留完整原始图形与显式 UV 派生记录，并校验原始拓扑、交点范围、材质引用、法线及实际编码缓冲区；预览和再次压缩时执行相同的来源校验。楼层、阶段、类型和填充参数继续作为原始属性保留。该能力不替代缺失的外链或外部材质资源，无法完整核实的几何仍报告兼容性限制；REST、MCP 与 JavaScript SDK 的公开方法、参数和返回字段保持不变。
对已完整核实、但直接编码后会退化的窄小墙体，转换可使用独立的局部显示坐标节点，保留原始构件坐标、顶点、法线、索引和层级。加载与再次压缩时同时校验局部坐标、原始交点、完整面覆盖及实际显示缓冲区，并保持原有位置误差范围；不满足条件的几何仍报告兼容性限制。REST、MCP 与 JavaScript SDK 的公开方法、参数和返回字段保持不变。
兼容转换包可压缩保存解析校验记录，加载时校验并还原原值，源参数及材质绑定保持保留。受支持平面的显示三角形划分可在面内调整，并保留完整原始索引；面边界、三角形总数和法线须保持一致。此项不扩大原生格式或原始外观的兼容范围，REST、MCP 和 SDK 的既有方法签名不变。 材质来源记录随兼容包校验还原；档案不完整或校验失败时拒绝加载。源参数和材质来源中的数值保留负零符号，既有材质绑定与源记录引用保持不变。 对于已核验的幕墙宿主与面板引用，PLW 预览区分内部宿主几何与可见面板；宿主原始几何、身份、参数和父子关系仍随包保留。加载前核对随包原始记录，引用缺失或不一致时拒绝加载。此项不代表完整建筑几何和原始外观已经通过验收，既有 REST、MCP、SDK 方法签名保持不变。 已解析的源材质图形颜色或外观预览色，在 GLB 中按标准线性 RGB 编码，原始 RGB 字节与透明度记录保持保留。预览的不透明度范围为 0–100%，包含完全透明；此范围不改变原始参数，也不代替纹理与完整外观验收。REST、MCP 与 SDK 方法签名保持不变。 对同时包含原始平面和圆柱面的兼容构件，依据可唯一核实的原始共边坐标表达显示边界，并保留原始图形记录、参数和面样式引用。加载时校验原始身份、UV 历史及几何覆盖；不能唯一核实时仍报兼容性未通过。此项不代表完整 RVT 几何、材质外观或帧率验收，REST、MCP 与 SDK 既有方法签名保持不变。 对兼容曲面，预览可采用有来源校验的舍入退化处理：仅排除编码后已无面积且原始端点位于双精度舍入范围内的绘制项；完整原始索引、面引用、属性、材质和层级继续随模型保存。未满足条件时仍报告兼容性限制。 对具有可验证共面四边形的兼容网格，显示时可仅交换同一面内的内部对角线；保留原始索引存档、完整面边界、三角形总数、顶点、法线、材质及层级。局部显示原点可取自原始边界、顶点，或使用边界中心搭配单个原始坐标分量，并继续校验世界坐标误差、朝向和闭合性；不扩大原生几何或外观的验收范围。 对已编码为零面积的绘制项，还可采用独立的来源容差校验；仅在原有来源拼接预算内、完整源面仍被表示且非零线框边集合不变时优化绘制索引。原始索引、顶点、法线、属性和层级继续保留，校验不通过时仍拒绝兼容。 对受支持的共线退化绘制项，可在严格来源校验下验证同一源面的精确线段覆盖和相应法线，并将完整原始索引无损压缩随包保存。加载时按声明预算回读索引档案；超限、损坏或来源不符的档案拒绝加载，不据此省略原始构件或扩大原生几何验收范围。 对同一兼容构件中互不相交的原始面，可按声明顺序组合面内对角线调整与共线零面积绘制处理；各步骤独立回读校验，完整原始索引、源面、顶点、法线、材质、属性和层级继续保留。源面重叠、步骤次序或数据校验不符时拒绝加载。 对具有可核实重叠剖分的兼容不透明楼板，可逐步校验原始平面的覆盖关系及局部替换前后表面并集相等，并无损保存完整原始双精度顶点、法线和索引。每个原始面仍保留显示表示，材质绑定、参数及源层级不变；不支持的材质映射或不能核实的几何继续报告兼容性限制。 平面边界的兼容读取同时校验原始实体内的端点见证、源面范围及闭合关系，并保留原始 UV 和图形记录；不满足核验要求时仍报告兼容性限制。 构件目录支持按名称、构件编号及保留的原始元素 ID、源 UID 搜索，便于定位同名构件并查看源参数。
兼容 RVT 便携模型可使用无损压缩的原始属性档案，按构件读取时还原原始 JSON 字节，保留大整数及负零等保存值。属性档案随模型交付，不依赖源 RVT 路径或外部属性服务；旧版兼容档案仍可读取。无法识别的档案版本、压缩声明或校验失败会明确报错。此行为不表示缺失的外部资源、原始几何或材质外观已恢复；REST、MCP 与 JavaScript SDK 的公开方法、参数及返回字段保持不变。
同一模型无损重新封装后，可继续读取随包保存的原始属性。每次导入仍校验属性档案的完整性；档案声明或压缩内容不一致时拒绝加载。
兼容的柔性管解析结果可按原始曲面和封闭边界保留显示几何，并保留源面记录、材质引用及保存参数。曲面边界或显示状态无法核实时，构件仍标为未通过。几何恢复不表示源材质外观或整个原生模型已经完成转换验收；REST、MCP 与 JavaScript SDK 的公开方法、参数及返回字段保持不变。相邻圆柱段沿轴向连接的兼容圆弧边界，还须核对两侧原始曲面、参数范围及完整闭合构件；无法核实的边界继续保留未通过状态。兼容的复合封闭构件按原始边界连接关系分别核验各封闭部分，保留接触位置的全部原始面及构件身份；渲染坐标调整只作用于显示表示。重复导入同一源文件时，兼容的无损属性存储布局会核对全部原始记录及定义几何；原始内容不一致时拒绝复用属性缓存。DPE 中兼容的源构件批处理保留原始层级与属性，透明度后处理使用当前渲染表示；源构件的材质与编辑状态继续随工程保存。
普通 FBX 任务若以 PLW_FBX_MATERIAL_CONTRACT_UNSUPPORTED 失败，接入方应保留任务 ID，并展示错误中的源材质、源贴图 ID 及缺失设置。缺少可验证的 Mono/Output 设置的程序贴图，以及非零或未知强度的未支持渲染器反射，会停止转换；SDK 方法和参数保持不变。
官网统计集成
官网独立加载 /official/client-report.js，向 https://api.picimos.com/client/report/download 和 /client/report/online/heartbeat 上报，固定 type: 1。脚本监听下载列表中的安装包点击，不接管清单请求、卡片渲染或下载导航；包版本和平台取自实际链接，不固定为某一发布版本。
在线官网在同一标签页会话首次打开时发送一次 web 访问记录，sessionStorage 标记后刷新不重复；不做定时调用、离线上报或失败重试。离线客户端不启用该统计。有本站 PiAdmin 登录态时携带当前 Authorization，无登录态时匿名上报。统计失败只输出不含凭据的提示，宿主不需要重复上报。该模式不统计持续在线时长，浏览器禁用会话存储时无法保证刷新去重。字段和跨域要求见 REST 接入文档“官网统计”。现有转换 REST、MCP 参数和 JavaScript 方法签名保持不变。
批量任务沿用现有 POST /api/v1/tasks 逐个提交，分别保存返回的任务 ID。REST、MCP 与 JavaScript SDK 方法、参数和响应字段保持不变。响应未确认时先查询已有任务，再决定是否重试。
读取原生 CAD 失败阶段观察
需要定位 STEP / IGES 失败前进展时，以原凭据查询 GET /api/v1/tasks/:id，按可选 diagnostics.nativeCadProgress.completed 读取已报告阶段及累计 elapsedMs。字段可能缺省，不能补零，也不能用最后记录的下一阶段代替实际故障原因。phaseOfFailureKnown 为 false；即使最后记录为 done，任务仍须通过统计和完整性校验。SDK 函数签名、提交参数和超时设置保持不变；此诊断不触发重试。
PLW MCP 工具参考
适用版本 0.3.87。通过 tools/list 读取当前工具参数，通过 resources/list 查询可读资源。
MCP 与 REST 使用同一转换任务、身份和成果链路；提交后保存任务 ID，查询任务报告并选择具体产物交付。
3DXML XML Tessellation 使用既有提交参数，装配坐标在局部编码前保留双精度。支持同包内 ProductStructure 文档之间的明确引用，并保留发生项树和文档归属。构件属性 OccurrenceTransforms 保存各级局部与累积矩阵数值、声明位置和文档身份，未声明矩阵与显式单位矩阵分别记录；网格已应用变换，不应重复施加。空值或重复矩阵声明停止转换。包外引用以 PLW_3DXML_EXTERNAL_REFERENCE_UNSUPPORTED 停止，目标 ID 缺失以 PLW_3DXML_REFERENCE_MISSING 停止；二进制 CGR / V5_CFV3 以 PLW_3DXML_BINARY_UNSUPPORTED 停止；同包 XML 材质支持单层 Rendering 漫反射、贴图与自发光、一维或二维 UV 通道 0、完整的 24 位 BI_RGB BMP（40 字节 BITMAPINFOHEADER，无 alpha） 无损转 PNG。纹理限显式原网格 UV 映射（IMPLICIT_MAPPING）、无额外变换的 MODULATE、CLAMP/REPEAT 与近邻/线性/三线性采样。原始材质属性和资源身份保存在 glTF 材质 extras[3dxml-material] 中；同时有颜色与材质时采用 Rendering 材质显示，内联颜色另存于材质属性。Phong 高光、环境及反射与 PBR 的差异保留警告。未支持的材质层、图片编码、纹理变换和发生项或默认视图覆盖以 PLW_3DXML_MATERIAL_UNSUPPORTED 停止，缺失及损坏资源停止整个任务。MCP 工具名称和参数 schema 保持不变。
静态 GLB 场景保留支持独立线段和三角面。含线段时，成果 meta.lineSegments 提供发生项展开后的线段数，meta.uniqueLineSegments 提供网格定义线段数；三角数独立统计，工具参数保持不变。
工具共 15 项。
list_formats
查询当前平台的输入/输出格式及读取边界
{
"type": "object",
"properties": {}
}upload_model
上传单个模型或包含依赖资源的 ZIP（标准 base64，最多 64 MiB）；格式以 list_formats 为准。更大文件请通过平台 HTTP 上传接口传输。
{
"type": "object",
"properties": {
"filename": {
"type": "string",
"description": "文件名（含扩展名，如 model.ifc）"
},
"content_b64": {
"type": "string",
"description": "文件内容 base64 编码"
}
},
"required": [
"filename",
"content_b64"
]
}convert_model
提交转换任务；OBJ 必须明确 source_unit，ZIP 多入口用 entry 指定。独立 DGN 源显示须明确 dgn_profile=source-display 与 dgn_remainder_policy；使用诊断材质及显示比例，任务报告列出未输出元素。独立 JT 源显示须明确 jt_profile=source-display 与 jt_lod_policy=first-source-child，仅兼容静态 GLB/DPEPack；源轴向、当前配置与完整外观按兼容说明解释。.x_t 显示预览须明确 xt_profile=display-preview，仅 GLB/DPEPack LOD0，复杂曲面工程精度未核验且需要受控 Windows x64 组件。native-step-glb 需独占目标并明确源向上轴。返回任务 ID。
{
"type": "object",
"properties": {
"source_path": {
"type": "string",
"description": "源文件服务器路径（upload_model 返回的 path）"
},
"entry": {
"type": "string",
"description": "ZIP 内模型的完整相对路径；包含多个模型入口时必填"
},
"name": {
"type": "string",
"description": "任务名称（可选）"
},
"targets": {
"type": "array",
"items": {
"type": "string",
"enum": [
"dpepack",
"glb",
"3dtiles",
"fbx",
"gaussian",
"gaussian-3dtiles",
"native-step-glb",
"imagery-tiles",
"terrain-tiles",
"vector-tiles"
]
},
"description": "输出格式列表（普通 PLY 默认 glb+3dtiles，其他默认 dpepack+glb；PLY/ZIP 高斯自动保留源保真包，真高斯瓦片须显式选择）"
},
"retry_of": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$",
"description": "可选旧任务 ID。按当前共享重试方案提交同源、同 ZIP 入口和同输出目标；已知 RVM 精度/拓扑旧失败可显式转保真 LOD0，旧任务保留。此时只可同时指定 source_path、相同 name/targets；不接受其它覆盖参数。"
},
"source_unit": {
"type": "string",
"enum": [
"keep",
"m",
"mm",
"cm",
"inch"
],
"description": "源长度单位；直接 OBJ 和 ZIP 内 OBJ 必填。keep=保留源数值但单位未知，m/mm/cm/inch=依据已确认的源单位换算。"
},
"xt_profile": {
"type": "string",
"enum": [
"display-preview"
],
"description": "仅独立 .x_t 文件（不支持 ZIP 入口）：明确选择显示预览，固定 GLB / DPEPack、LOD0 及源局部坐标。名称使用源实体编号；复杂曲面工程精度未核验，不适用于精密测量、加工或尺寸验收。需要服务端已配置受控 Windows x64 组件和已核验的文本 XT 版本。"
},
"dgn_profile": {
"type": "string",
"enum": [
"source-display"
],
"description": "独立 DGN V8 CFB 受验配对圆柱实体、索引网格及三维折线的诊断显示；固定 GLB/DPEPack LOD0，不压缩。坐标不代表物理米，须同时明确 dgn_remainder_policy。Windows x64 服务需配置独立运行时及受验读取组件。"
},
"dgn_remainder_policy": {
"type": "string",
"enum": [
"report-unrendered",
"require-complete"
],
"description": "report-unrendered 输出受支持的几何并在任务报告逐项列出未输出原始元素；require-complete 遇未输出元素即停止。两种选择均不建立当前状态、原生外观或完整 DGN 导入保证。"
},
"jt_profile": {
"type": "string",
"enum": [
"source-display"
],
"description": "独立 .jt 的源静态三角场景显示；JT10.1/10.3 兼容输入，仅 GLB/DPEPack。须同时明确 jt_lod_policy；源单位必须完整一致，源轴向、当前配置和完整原生外观不在等价保证范围。Windows x64 服务需配置独立读取运行时。"
},
"jt_lod_policy": {
"type": "string",
"enum": [
"first-source-child"
],
"description": "按每个原始 RangeLOD 的源顺序选首个子分支，并记录实际选择；不推断原生当前配置或最高精度。"
},
"jt_material_mode": {
"type": "string",
"enum": [
"source-coefficients",
"diagnostic"
],
"description": "源数值的 PBR 近似，未解决材质使用明确诊断色；或统一诊断色。默认 source-coefficients，均不表示完整原生外观等价。"
},
"glb_node_mode": {
"type": "string",
"enum": [
"instancing",
"source-hierarchy",
"preserve-scene"
],
"description": "原型装配 GLB 默认 source-hierarchy、LOD0，用普通节点保留构件位置和装配目录，不保证原局部轴心。显式 instancing 重组节点与轴心，目标读取器必须支持 EXT_mesh_gpu_instancing；高 LOD 需显式选择该方式。preserve-scene 支持兼容静态内嵌 GLB，以及仅含 Autodesk 材质代理引用的二进制静态三角网格 FBX；保留原名称、局部变换、属性与逐面代理材质槽。FBX 代理缺少颜色或贴图时外观保持未恢复。仅 GLB / DPEPack、LOD0。"
},
"tiles_options": {
"type": "object",
"additionalProperties": false,
"description": "模型或普通点云 3D Tiles 的地理定位；局部坐标不设置锚点，ECEF 需经纬度和椭球高。",
"properties": {
"coordinate_system": {
"type": "string",
"enum": [
"local",
"ecef"
]
},
"anchor": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 3
}
}
},
"point_cloud_options": {
"type": "object",
"additionalProperties": false,
"description": "普通 PLY 点云参数；轴变换适用于 GLB/3D Tiles，分块仅用于 3D Tiles；深度 0 表示单瓦片。",
"properties": {
"up_axis": {
"type": "string",
"enum": [
"keep",
"zup2yup"
]
},
"tile_budget": {
"type": "integer",
"minimum": 1,
"maximum": 1000000
},
"max_depth": {
"type": "integer",
"minimum": 0,
"maximum": 10
}
}
},
"gaussian_up_axis": {
"type": "string",
"enum": [
"keep",
"zup2yup"
],
"description": "高斯源轴向；zup2yup 同步旋转位置、椭球与球谐，须同时选择 gaussian 和 gaussian-3dtiles。"
},
"gaussian_options": {
"type": "object",
"additionalProperties": false,
"description": "真高斯切片参数。PLY/SPLAT 默认完整点分块，可选择试验性远景粗层；LCC2 必须保留原生层级。",
"properties": {
"lod_policy": {
"type": "string",
"enum": [
"full-resolution",
"moment-matched",
"native"
]
},
"tile_budget": {
"type": "integer",
"minimum": 100,
"maximum": 100000
},
"coarse_budget": {
"type": "integer",
"minimum": 100,
"maximum": 100000
},
"max_depth": {
"type": "integer",
"minimum": 1,
"maximum": 10
},
"encoding": {
"type": "string",
"enum": [
"spz2",
"raw"
],
"description": "压缩或浮点属性；raw 保留解码及坐标变换后的浮点数，体积较大，不能同时指定 sh_precision。"
},
"sh_precision": {
"type": "string",
"enum": [
"balanced",
"high"
],
"description": "方向颜色精度；high 使用 8 位球谐量化，体积更大。几何量化和超范围系数钳制仍然存在。"
}
}
},
"gis_options": {
"type": "object",
"description": "GIS 切片参数：sourceCrs EPSG 编号、minZoom/maxZoom、bounds、bands；影像 tileSize:256/512/1024、resampling:nearest/bilinear/cubic；地形须明确 heightDatum:ellipsoid 或 egm96（EGM96 正高离线改正为 WGS84 椭球高），可 heightScale/heightOffset，terrainNoDataPolicy:reject(默认)/interpolate/constant；插值 terrainFillDistance:1–128 源像素，constant 必填 terrainFillHeight（源高程基准米制），terrainOutsideHeight 为范围外补面椭球高米制(默认0)，填充高程不再应用比例偏移；多图层用 layer；矢量 longitudeMode:preserve(默认)/shortest；DXF 等本地工程坐标可用 controlPoints:[{source:[x,y],geographic:[lon,lat]}] 的 2–8 个点和可选 controlPointToleranceMeters(0.001–100，默认2米)定位，不能同时设置 sourceCrs；DXF 必须二选一。"
},
"native_options": {
"type": "object",
"description": "仅 native-step-glb 使用；源向上轴和三角化参数",
"properties": {
"up_axis": {
"type": "string",
"enum": [
"keep",
"zup2yup"
]
},
"linear_deflection": {
"type": "number",
"minimum": 0.000001,
"maximum": 100
},
"angular_deflection": {
"type": "number",
"minimum": 0.01,
"maximum": 3.141592653589793
}
},
"required": [
"up_axis"
]
}
},
"required": [
"source_path"
]
}get_task
查询任务状态、产物和持久化警告；completed 不等于所有源特性均已保留，必须阅读 warnings 与产物 meta
{
"type": "object",
"properties": {
"task_id": {
"type": "string",
"description": "任务 ID"
}
},
"required": [
"task_id"
]
}list_tasks
列出最近的转换任务（默认 10 条）
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "返回条数（默认 10）"
}
}
}get_artifact_url
获取产物下载 URL；启用鉴权时下载请求仍须携带凭证，URL 不包含 token
{
"type": "object",
"properties": {
"task_id": {
"type": "string",
"description": "任务 ID"
},
"artifact_type": {
"type": "string",
"enum": [
"dpepack",
"glb",
"3dtiles",
"fbx",
"gaussian",
"gaussian-3dtiles",
"native-step-glb",
"imagery-tiles",
"terrain-tiles",
"vector-tiles"
],
"description": "产物类型"
}
},
"required": [
"task_id",
"artifact_type"
]
}estimate_model
读取真实服务器源资源体积及估算边界；网格产物 bytes 为 null，须转换后统计。高斯给出源资源下限，不含清单等开销。
{
"type": "object",
"properties": {
"source_path": {
"type": "string",
"description": "upload_model 返回的 path 或平台已授权源路径"
}
},
"required": [
"source_path"
]
}list_gis_services
按名称/编号、类型和状态筛选当前身份可访问的私有 GIS 服务
{
"type": "object",
"additionalProperties": false,
"properties": {
"search": {
"type": "string",
"maxLength": 200
},
"kind": {
"type": "string",
"enum": [
"tiles3d",
"gaussian",
"imagery",
"terrain",
"vector"
]
},
"status": {
"type": "string",
"enum": [
"draft",
"published",
"paused"
]
}
},
"required": []
}get_gis_service
查询私有 GIS 服务状态、版本和不含凭据的稳定地址
{
"type": "object",
"additionalProperties": false,
"properties": {
"service_id": {
"type": "string",
"pattern": "^[a-z0-9-]{1,80}$"
}
},
"required": [
"service_id"
]
}set_gis_vector_style
保存点线面、属性分类、数值分段及 label 属性标注样式，同步 PLW 预览和 WMS/WMTS 图片。classification.mode=range 时区间 min 包含、max 不包含，null 边界表示无界，按下限升序且不重叠；只匹配数值。未匹配值用默认样式；expected_revision 防止覆盖并发修改
{
"type": "object",
"additionalProperties": false,
"properties": {
"service_id": {
"type": "string",
"pattern": "^[a-z0-9-]{1,80}$"
},
"style": {
"type": "object",
"additionalProperties": false,
"required": [
"polygonColor",
"polygonOpacity",
"lineColor",
"lineWidth",
"pointColor",
"pointRadius",
"pointStrokeColor",
"pointStrokeWidth"
],
"properties": {
"polygonColor": {
"type": "string",
"pattern": "^#[a-fA-F0-9]{6}$"
},
"polygonOpacity": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"lineColor": {
"type": "string",
"pattern": "^#[a-fA-F0-9]{6}$"
},
"lineWidth": {
"type": "number",
"minimum": 0,
"maximum": 16
},
"pointColor": {
"type": "string",
"pattern": "^#[a-fA-F0-9]{6}$"
},
"pointRadius": {
"type": "number",
"minimum": 1,
"maximum": 32
},
"pointStrokeColor": {
"type": "string",
"pattern": "^#[a-fA-F0-9]{6}$"
},
"pointStrokeWidth": {
"type": "number",
"minimum": 0,
"maximum": 16
},
"classification": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"required": [
"field",
"classes"
],
"properties": {
"field": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"classes": {
"type": "array",
"minItems": 1,
"maxItems": 32,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"value",
"style"
],
"properties": {
"value": {
"anyOf": [
{
"type": "string",
"maxLength": 256
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"style": {
"type": "object",
"additionalProperties": false,
"minProperties": 1,
"properties": {
"polygonColor": {
"type": "string",
"pattern": "^#[a-fA-F0-9]{6}$"
},
"polygonOpacity": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"lineColor": {
"type": "string",
"pattern": "^#[a-fA-F0-9]{6}$"
},
"lineWidth": {
"type": "number",
"minimum": 0,
"maximum": 16
},
"pointColor": {
"type": "string",
"pattern": "^#[a-fA-F0-9]{6}$"
},
"pointRadius": {
"type": "number",
"minimum": 1,
"maximum": 32
},
"pointStrokeColor": {
"type": "string",
"pattern": "^#[a-fA-F0-9]{6}$"
},
"pointStrokeWidth": {
"type": "number",
"minimum": 0,
"maximum": 16
}
}
}
}
}
}
}
},
{
"type": "object",
"additionalProperties": false,
"required": [
"field",
"mode",
"classes"
],
"properties": {
"field": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"mode": {
"const": "range"
},
"classes": {
"type": "array",
"minItems": 1,
"maxItems": 32,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"min",
"max",
"style"
],
"properties": {
"min": {
"type": [
"number",
"null"
]
},
"max": {
"type": [
"number",
"null"
]
},
"style": {
"type": "object",
"additionalProperties": false,
"minProperties": 1,
"properties": {
"polygonColor": {
"type": "string",
"pattern": "^#[a-fA-F0-9]{6}$"
},
"polygonOpacity": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"lineColor": {
"type": "string",
"pattern": "^#[a-fA-F0-9]{6}$"
},
"lineWidth": {
"type": "number",
"minimum": 0,
"maximum": 16
},
"pointColor": {
"type": "string",
"pattern": "^#[a-fA-F0-9]{6}$"
},
"pointRadius": {
"type": "number",
"minimum": 1,
"maximum": 32
},
"pointStrokeColor": {
"type": "string",
"pattern": "^#[a-fA-F0-9]{6}$"
},
"pointStrokeWidth": {
"type": "number",
"minimum": 0,
"maximum": 16
}
}
}
}
}
}
}
}
]
},
"label": {
"type": "object",
"additionalProperties": false,
"required": [
"field"
],
"properties": {
"field": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"size": {
"type": "number",
"minimum": 8,
"maximum": 48
},
"color": {
"type": "string",
"pattern": "^#[a-fA-F0-9]{6}$"
},
"haloColor": {
"type": "string",
"pattern": "^#[a-fA-F0-9]{6}$"
},
"haloWidth": {
"type": "number",
"minimum": 0,
"maximum": 8
},
"offsetX": {
"type": "number",
"minimum": -64,
"maximum": 64
},
"offsetY": {
"type": "number",
"minimum": -64,
"maximum": 64
},
"minZoom": {
"type": "number",
"minimum": 0,
"maximum": 22
},
"maxZoom": {
"type": "number",
"minimum": 0,
"maximum": 22
},
"declutter": {
"type": "boolean"
}
}
}
}
},
"expected_revision": {
"type": "integer",
"minimum": 0
}
},
"required": [
"service_id",
"style",
"expected_revision"
]
}rename_gis_service
修改服务名称，保持固定地址、发布状态和所有版本不变；expected_name 用于防止覆盖并发改名
{
"type": "object",
"additionalProperties": false,
"properties": {
"service_id": {
"type": "string",
"pattern": "^[a-z0-9-]{1,80}$"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"expected_name": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
"required": [
"service_id",
"name"
]
}create_gis_service
从已完成 GIS 切片任务创建私有服务草稿；局部坐标需要地理锚点，已定位模型保留源定位
{
"type": "object",
"additionalProperties": false,
"properties": {
"task_id": {
"type": "string"
},
"artifact_type": {
"type": "string",
"enum": [
"3dtiles",
"gaussian-3dtiles",
"imagery-tiles",
"terrain-tiles",
"vector-tiles"
]
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"anchor": {
"type": "object",
"additionalProperties": false,
"properties": {
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
},
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"height": {
"type": "number",
"minimum": -12000,
"maximum": 100000,
"description": "WGS84 椭球高，米；锚点对应切片局部原点"
}
},
"required": [
"longitude",
"latitude",
"height"
]
}
},
"required": [
"task_id",
"name"
]
}add_gis_service_version
从已完成 GIS 切片任务创建独立不可变版本；不会自动切换已发布版本
{
"type": "object",
"additionalProperties": false,
"properties": {
"service_id": {
"type": "string",
"pattern": "^[a-z0-9-]{1,80}$"
},
"task_id": {
"type": "string"
},
"artifact_type": {
"type": "string",
"enum": [
"3dtiles",
"gaussian-3dtiles",
"imagery-tiles",
"terrain-tiles",
"vector-tiles"
]
},
"anchor": {
"type": "object",
"additionalProperties": false,
"properties": {
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
},
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"height": {
"type": "number",
"minimum": -12000,
"maximum": 100000,
"description": "WGS84 椭球高，米；锚点对应切片局部原点"
}
},
"required": [
"longitude",
"latitude",
"height"
]
}
},
"required": [
"service_id",
"task_id"
]
}publish_gis_service
发布、恢复或回滚到指定有锚点版本；未指定版本时恢复当前版本或首次发布最新版本
{
"type": "object",
"additionalProperties": false,
"properties": {
"service_id": {
"type": "string",
"pattern": "^[a-z0-9-]{1,80}$"
},
"version_id": {
"type": "string",
"pattern": "^[a-z0-9-]{1,80}$"
}
},
"required": [
"service_id"
]
}pause_gis_service
暂停服务；根清单和所有版本瓦片停止分发
{
"type": "object",
"additionalProperties": false,
"properties": {
"service_id": {
"type": "string",
"pattern": "^[a-z0-9-]{1,80}$"
}
},
"required": [
"service_id"
]
}可读资源
plw://health：平台健康状态plw://formats：支持的格式plw://tasks：最近任务
查看带 DGN 来源场景信息的兼容 GLB 时，可在同一视口查看配对实体与索引网格。点选实体面可核对元素、单元、面索引及实体内节点编号，并查看保留面或边归属的本地属性；点选网格面可核对原始元素内的面序号与带符号点索引。网格序号不作为 B-Rep 持久面编号，也不表示已解释原生业务属性。此类成果采用明确的诊断材质和显示比例，坐标不代表物理米；浏览器校验成果中的来源记录及显示几何，不重新读取原始 DGN，也不据此认定完整 DGN 导入或工程精度。任务继续使用现有上传、提交、查询和下载接口；DGN 源显示增加显式用途及未输出元素处理参数。
DGN 源显示与未输出元素
DGN 源显示兼容同时包含受验配对圆柱实体、索引网格的单模型 V8 CFB，并保留受验三维折线的原始顶点顺序，服务端需配置 Windows x64 独立读取运行时和受验组件。仅输出 GLB / DPEPack 的 LOD0 诊断场景，保留来源记录，不执行几何压缩、减面、焊接、轴向或物理单位覆盖。显示比例为原始 UOR 的 1/10000，坐标不代表物理米。折线保留线段来源及原始附属记录，未将这些记录认定为已解释的业务属性，原始线型外观须按兼容说明核对。当前配置、完整原生外观、V7、其它原生几何及完整 DGN 导入不在等价保证范围。未兼容的输入明确停止任务。 使用 convert_model 时明确 dgn_profile=source-display 和 dgn_remainder_policy=report-unrendered 或 require-complete，targets 仅 glb/dpepack。前者逐项报告未输出原始元素，后者遇未输出元素即停止。现有上传、查询、下载及工具数量保持不变。浏览器核对导出的来源记录与显示场景，不重新读取原始 CFB。
JT 源显示与保留记录
直接兼容 JT10.1/10.3 静态场景须明确 jt_profile=source-display 及 jt_lod_policy=first-source-child，仅 GLB / DPEPack，Windows x64 服务需配置独立读取运行时。仅单一内含根分区，无法解释的节点状态或嵌套分区停止任务。首个 LOD 子分支依据文件顺序，不代表当前配置或最高精度；源单位必须完整一致。源轴向保持原数值方向，原生世界轴向、完整外观、外部引用和 B-Rep 精度不在等价保证范围。jt_material_mode 选择源数值的 PBR 近似（未解决材质使用诊断色）或统一诊断色。查看器读取保留的本地类型属性、发生路径和三角来源；浏览器不重新读取原始 JT，数组序号不作为 B-Rep 持久实体 ID。工具数量、名称和其它格式参数保持不变。
对已完整核实、但直接编码后会退化的窄小墙体，转换可使用独立的局部显示坐标节点，保留原始构件坐标、顶点、法线、索引和层级。加载与再次压缩时同时校验局部坐标、原始交点、完整面覆盖及实际显示缓冲区，并保持原有位置误差范围；不满足条件的几何仍报告兼容性限制。REST、MCP 与 JavaScript SDK 的公开方法、参数和返回字段保持不变。
对可唯一核实的原始平面墙体交点，转换保留完整原始图形与显式 UV 派生记录，并校验原始拓扑、交点范围、材质引用、法线及实际编码缓冲区；预览和再次压缩时执行相同的来源校验。楼层、阶段、类型和填充参数继续作为原始属性保留。该能力不替代缺失的外链或外部材质资源，无法完整核实的几何仍报告兼容性限制；REST、MCP 与 JavaScript SDK 的公开方法、参数和返回字段保持不变。
对边界可完整核实的非等参直纹面交线，转换按两侧原始曲面和完整参数范围恢复显示边界，并逐面校验法线、覆盖及编码后的闭合性。原始双 UV、图形记录、实际材质引用和全部随包属性继续保留；无法唯一核实的交线仍报告兼容性限制。此项不表示整份原生模型或缺失的材质资源已通过验收，REST、MCP 与 JavaScript SDK 的公开方法、参数及返回字段保持不变。
对已核验的原生曲面，模型保留构件及类型的原始图形记录、源材质引用、参数与层级。转换后按源面核对位置、法线及索引的一致性，有效阶段引用仍可查阅。无法完整解读边界的构件保持未通过状态。REST、MCP 与 JavaScript SDK 的公开方法、参数及返回字段保持不变。
带有明确 RVT 原始属性档案声明的 GLB 可沿用“完整场景保留”通道。预览中选中构件后可只读查看源文件保存的参数、全部字段及原始 JSON，并沿类型、族、标高、管段及材质引用查阅关联记录，类型参数与管段材质保持各自的原始记录；属性档案随模型保存，不依赖源 RVT 路径。原始保存值不代表公式已重新计算，也不代表完整 RVT 几何、材质和外观已通过转换验收。REST、MCP 与 SDK 的方法、参数及返回字段保持不变；属性面板不新增远程文件读取接口。对明确声明为未放置类型定义的档案，原始几何记录随模型保留，且不计入项目实体的渲染和构件数量。此类记录的父级与放置字段仍属源数据，不能据此认定原生可编辑枢轴或完整实例范围已经通过验收。交付验收应区分实体实例、类型定义与目录容器，并逐项核对原始构件身份、父级、参数和外观，并在实际显示分辨率下检查旋转、缩放及选中时的帧率与表面稳定性。参数档案完整或转换任务成功，不能替代这些检查。RVT 导入对象所引用的外部图形、字体及材质资源应随原工程提供。仅保留引用、没有图形缓存的对象无法据此恢复其显示内容；原始属性档案仍可保留这些引用和参数。源构件的 UniqueId 与当前记录定位编号分别保留；两者编号不同时，按源索引对应关系核验，不能改写原始身份。
兼容转换包可压缩保存解析校验记录，加载时校验并还原原值，源参数及材质绑定保持保留。受支持平面的显示三角形划分可在面内调整，并保留完整原始索引；面边界、三角形总数和法线须保持一致。此项不扩大原生格式或原始外观的兼容范围，REST、MCP 和 SDK 的既有方法签名不变。 材质来源记录随兼容包校验还原；档案不完整或校验失败时拒绝加载。源参数和材质来源中的数值保留负零符号，既有材质绑定与源记录引用保持不变。 对于已核验的幕墙宿主与面板引用，PLW 预览区分内部宿主几何与可见面板；宿主原始几何、身份、参数和父子关系仍随包保留。加载前核对随包原始记录，引用缺失或不一致时拒绝加载。此项不代表完整建筑几何和原始外观已经通过验收，既有 REST、MCP、SDK 方法签名保持不变。 已解析的源材质图形颜色或外观预览色，在 GLB 中按标准线性 RGB 编码，原始 RGB 字节与透明度记录保持保留。预览的不透明度范围为 0–100%，包含完全透明；此范围不改变原始参数，也不代替纹理与完整外观验收。REST、MCP 与 SDK 方法签名保持不变。 对同时包含原始平面和圆柱面的兼容构件，依据可唯一核实的原始共边坐标表达显示边界，并保留原始图形记录、参数和面样式引用。加载时校验原始身份、UV 历史及几何覆盖；不能唯一核实时仍报兼容性未通过。此项不代表完整 RVT 几何、材质外观或帧率验收，REST、MCP 与 SDK 既有方法签名保持不变。 对兼容曲面，预览可采用有来源校验的舍入退化处理：仅排除编码后已无面积且原始端点位于双精度舍入范围内的绘制项；完整原始索引、面引用、属性、材质和层级继续随模型保存。未满足条件时仍报告兼容性限制。 对具有可验证共面四边形的兼容网格，显示时可仅交换同一面内的内部对角线；保留原始索引存档、完整面边界、三角形总数、顶点、法线、材质及层级。局部显示原点可取自原始边界、顶点，或使用边界中心搭配单个原始坐标分量，并继续校验世界坐标误差、朝向和闭合性；不扩大原生几何或外观的验收范围。 对已编码为零面积的绘制项，还可采用独立的来源容差校验；仅在原有来源拼接预算内、完整源面仍被表示且非零线框边集合不变时优化绘制索引。原始索引、顶点、法线、属性和层级继续保留，校验不通过时仍拒绝兼容。 对受支持的共线退化绘制项，可在严格来源校验下验证同一源面的精确线段覆盖和相应法线，并将完整原始索引无损压缩随包保存。加载时按声明预算回读索引档案；超限、损坏或来源不符的档案拒绝加载，不据此省略原始构件或扩大原生几何验收范围。 对同一兼容构件中互不相交的原始面，可按声明顺序组合面内对角线调整与共线零面积绘制处理；各步骤独立回读校验，完整原始索引、源面、顶点、法线、材质、属性和层级继续保留。源面重叠、步骤次序或数据校验不符时拒绝加载。 对具有可核实重叠剖分的兼容不透明楼板，可逐步校验原始平面的覆盖关系及局部替换前后表面并集相等，并无损保存完整原始双精度顶点、法线和索引。每个原始面仍保留显示表示，材质绑定、参数及源层级不变；不支持的材质映射或不能核实的几何继续报告兼容性限制。 平面边界的兼容读取同时校验原始实体内的端点见证、源面范围及闭合关系，并保留原始 UV 和图形记录；不满足核验要求时仍报告兼容性限制。 构件目录支持按名称、构件编号及保留的原始元素 ID、源 UID 搜索，便于定位同名构件并查看源参数。
兼容 RVT 便携模型可使用无损压缩的原始属性档案，按构件读取时还原原始 JSON 字节，保留大整数及负零等保存值。属性档案随模型交付，不依赖源 RVT 路径或外部属性服务；旧版兼容档案仍可读取。无法识别的档案版本、压缩声明或校验失败会明确报错。此行为不表示缺失的外部资源、原始几何或材质外观已恢复；REST、MCP 与 JavaScript SDK 的公开方法、参数及返回字段保持不变。
同一模型无损重新封装后，可继续读取随包保存的原始属性。每次导入仍校验属性档案的完整性；档案声明或压缩内容不一致时拒绝加载。
兼容的柔性管解析结果可按原始曲面和封闭边界保留显示几何，并保留源面记录、材质引用及保存参数。曲面边界或显示状态无法核实时，构件仍标为未通过。几何恢复不表示源材质外观或整个原生模型已经完成转换验收；REST、MCP 与 JavaScript SDK 的公开方法、参数及返回字段保持不变。相邻圆柱段沿轴向连接的兼容圆弧边界，还须核对两侧原始曲面、参数范围及完整闭合构件；无法核实的边界继续保留未通过状态。兼容的复合封闭构件按原始边界连接关系分别核验各封闭部分，保留接触位置的全部原始面及构件身份；渲染坐标调整只作用于显示表示。重复导入同一源文件时，兼容的无损属性存储布局会核对全部原始记录及定义几何；原始内容不一致时拒绝复用属性缓存。DPE 中兼容的源构件批处理保留原始层级与属性，透明度后处理使用当前渲染表示；源构件的材质与编辑状态继续随工程保存。
普通 FBX 材质无法忠实转换时以 PLW_FBX_MATERIAL_CONTRACT_UNSUPPORTED 停止，并说明源材质、源贴图 ID 及缺失的 Mono/Output 或反射渲染语义；不自动替换为猜测颜色或贴图。
显式离线显示减重
已转换的米制静态原型 DPEPack 可通过 node bin/optimize-model-pack.js model.dpepack display.glb --lod 2 --small-part-mm 30 --merge-materials 导出显示减重版。尺寸过滤按原 LOD0 构件包围盒的最大边长判断，单位毫米；原材质数值保留。同材质合并会改变单构件选择粒度，原 ID 和过滤清单保存在输出旁的 JSON。默认使用 meshopt 压缩，接收端须支持对应扩展；无压缩输出使用 --no-compress。材质合并仅兼容无贴图、无顶点色且有源法线的静态三角网格，未兼容属性明确停止。详见 docs/offline-mesh-reduction.md。
该能力为显式离线命令，不自动接入普通转换任务。现有 REST 路由/参数、MCP 工具名称/schema 和 JavaScript SDK 方法均保持不变；现有按三角数处理的小构件参数不等同于此尺寸阈值。
原生 CAD 失败阶段观察
STEP / IGES 的可选阶段记录通过带原凭据的 REST 任务查询 diagnostics.nativeCadProgress 读取，profile 为 native-cad-completed-phases/1。completed 最多四条，仅含白名单阶段及读取器报告的累计 elapsedMs；缺省不表示零耗时。lastReportedCompletedPhase 不定位故障阶段，phaseOfFailureKnown 为 false，done 也不替代任务统计和完整性校验。MCP 工具名称、输入 schema 及 get_task 现有状态/错误返回合同保持不变；此阶段观察对象不包含原生 stdout、模型名称或源路径。