ArchSight Graphics 更新记录

当前正式版本：v1.3.0 · 同步发布 @archsight/graphics SDK v1.0.0

v1.3.0

2026-07-20
BIM+GIS 现场空间能力版

本轮正式发布收口

  • 新增审查记录 v0：记录稳定模型身份、相机、剖切、截图、说明和状态，随项目文件 v9 保存重开，并可导出自包含中文审查清单。
  • 新增 Revit/IFC 薄发布通道 POC：离线生成 server-model manifest 与 server-delta 重定位结果，稳定身份优先使用 GlobalId 或 authoring id。
  • 固化独立 Project、ModelVersion、ReviewItem、分享、IAM、审计、幂等重试和指针式回滚服务契约；这些业务职责不进入 graphics-api。
  • Workbench 与 graphics-api 按同一版本和 Git revision 成组发布；API 路由返回真实 JSON，后台停止时 Workbench 明确降级并继续支持公开来源和本地资产。
  • WebGPU 发布证据绑定物理 GPU Adapter 与浏览器设备信息；Windows Intel/NVIDIA 和 NVIDIA 真实 IFC、Bistro、Emerald 场景已完成验证，不以软件回退冒充硬件通过。

发布性质

  • v1.3.0 是 BIM+GIS 现场空间能力发布版，不定位为泛 GIS 平台，也不把 Cesium 画布引入核心编辑视窗。
  • 本次同步发布 @archsight/graphics SDK v1.0.0，作为承担语义化版本兼容承诺的正式二次开发包。
  • 本版本把 ArchSight Graphics 从 BIM/CAD 浏览和工程对象工作台，推进到工程模型 + 现场背景 + 图层管理 + 空间配准的可交付闭环。
  • 3D Tiles / GIS 背景层定位为只读现场参照，服务于倾斜摄影、园区实景、公开城市轮廓参照、地形和底图；前景 BIM / IFC / 自有构件仍由 ArchSight 工程工作台承担选择、编辑、测量、参数化和后续 WASM 几何计算。

新增

  • SDK v1.0.0 固定根入口和七个一级子路径，关闭源码文件级通配导入，并通过公共 API 快照阻止未审查的破坏性变化。
  • SDK tarball 自带 examples/basic 和 examples/vanilla-ts；自动验证会从真实发布包中提取示例后完成安装、构建和浏览器运行。
  • 现场背景 改为可关闭、可拖动的专业图层工作台；主视图只保留统一添加、可见性、透明度和图层菜单，详情页承载诊断、配准和预算。
  • 统一添加流程分别支持影像底图、3D Tiles 和地形；客户 tileset.json 会先检查 URL、版本、root 结构和 boundingVolume.region，再加入图层列表。
  • 内置 BIM+GIS 演示样板的本地 tileset.json 扩展为园区语义场景，包含道路、庭院、停车、步道、水体、绿地、树阵、围界、门岗、主体建筑、屋面和施工区，便于第一步就看到“工程模型 + 现场背景”的完整关系。
  • 生产环境通过可选的同源 graphics-api 访问天地图和 Cesium ion；长期共享 token 只存在于后台环境变量，不进入前端资产、界面或项目文件。
  • Python 3.12 + FastAPI graphics-api 只开放固定天地图瓦片路由和白名单 Cesium asset endpoint，具备参数校验、限流、响应体上限和有界缓存，不提供任意 URL 代理；API 缺失不会阻断 Workbench 启动。
  • 底图作为按当前现场图层裁剪的平面参照，提供覆盖半径扩展、重置和证据包记录，避免把 OSM / 天地图平面瓦片误理解成无限三维地球底图。
  • 图层列表直接显示可见性、透明度和运行状态；图层菜单提供定位、复制、排序、详情和删除，降低日常操作密度。
  • 公开城市参照层默认以 22% 透明度作为低干扰城市轮廓参照；城市轮廓视角会保持保护距离，避免把 LOD1/LOD2 低精度块体贴脸展示；“源数据诊断”可进入近看检查并继续滚轮放大，只用于检查外部源数据本貌，不作为宣传截图效果。公开城市白/灰块体通常本来就比较粗糙，不代表 ArchSight 建模质量，近景宣传应使用客户倾斜摄影、园区 tileset 或自建 BIM/FBX 前景模型。
  • 工作台支持导出当前现场背景截图和运行证据；底部状态栏汇总图层启用、可见和失败数量。
  • 项目重开会恢复图层 URL、provider、底图、地形、配准和预算，但不会保存 token 或瓦片。

验证

  • SDK 正式发布门禁覆盖公共 API 快照、外部 TypeScript 项目、真实 tarball 安装、包内 examples 构建和浏览器 viewer smoke。
  • npm run test:v1.3-gis-release-gates 串联项目文件 / tileset 解析、网关安全边界、provider runtime、公开 tileset URL 和部署契约验证。
  • npm run test:v1.3-gis-browser-gates 构建 viewer 后验证现场背景工作台、BIM+GIS 示例和 test:site-context-project-reopen 保存重开 e2e。
  • test:site-context-project-reopen 会在浏览器里打开、保存、重开 GIS 项目文件，验证 3D Tiles 图层、provider、天地图底图、地形、配准、预算和透明度可恢复，且 token 不写入 .egl.json。
  • npm run test:site-context-provider-production 要求经实际 graphics-api 完成 health、Cesium endpoint 和天地图瓦片验收，不允许以 skipped 通过。

已知边界

  • v1.3 不承诺完整 GIS 平台、完整 EPSG 自动识别、高程基准自动转换、矢量编辑、空间数据库、空间分析或多用户 GIS 数据治理。
  • v1.3 不承诺 Revit / DWG 服务端轻量化、RVT/DWG 转换流水线或客户级模型转换服务。
  • 现场背景不进入构件编辑、测距捕捉、图纸导出或 IFC 语义树；它是宏观空间参照，不是可编辑工程对象。

v1.2.0

2026-07-02
WebGPU 价值证据版

发布性质

  • v1.2.0 是 WebGPU 价值证据版与真实工程模型可用性版本，不定位为 WebGPU 终局版，也不承诺 WebGPU 全面替代 WebGL。
  • 本版本的发布重点是把 Auto/WebGL/WebGPU 的选择原因、WebGPU 材质模式和回退状态做成可解释、可验证、可复现的交付证据。
  • WebGPU 外部模型交互在 v1.2.0 中按包围盒级语义选择收口，优先保证树节点、属性面板和包围盒反馈一致；它不承诺与 WebGL 三角面 CPU raycast、像素级拾取、面级测量或精确捕捉完全等价。
  • 产品运行时不再接入 debugMemGroup / memoryDiagnosticGroups 这类通过 URL query 改变真实加载行为的诊断路径；诊断逻辑只保留在独立 smoke runner、脚本或测试夹具边界内。

新增

  • 性能 HUD 增加 v1.2 渲染证据区，直接展示当前后端、Auto 决策来源、WebGPU 材质模式、运行时回退信号和路线回退证据边界。
  • WebGPU FBX 材质路径明确分为高保真贴图、性能代理和基础安全降级三类口径，便于解释当前模型为什么进入对应渲染路径。
  • v1.2 发布矩阵脚本支持 IFC 单对象 JSON 与 FBX runner 的 cases[] JSON，并明确标注 FPS 来源为 idle、interaction 或 demo-tour。
  • WebGPU 外部模型选中反馈以包围盒线框为主，避免把代理命中误包装成真实网格轮廓或面级命中。

改进

  • Auto 模式保留 WebGL 稳定基线，同时让 IFC 本地模型缓存场景可进入 WebGPU 路径；Auto reason 会在 HUD 和 smoke 证据中保留。
  • FBX material-proxy 路径保持真实几何与材质代理批处理，不再被普通空间切块放大 draw call；Bistro 验证场景稳定在 10 个有效 draw calls。
  • Emerald 级重型 FBX 的 texture-fidelity 路径保留贴图高保真证据，同时关闭 release smoke 中的移动贴图预转码，避免把移动缓存专项风险混入 v1.2 发布门禁。
  • 大体积 ZIP FBX 导入会把 ZIP 解压得到的源 ArrayBuffer 提供给 worker 使用，降低高内存压力下二次读取 Runtime Blob URL 失败导致的主线程回退风险。
  • FBX worker 材质重建中，单张 DDS 贴图读取失败会局部降级为兜底贴图，不再让整个 worker import 回退到主线程 FBXLoader。
  • 选中 FBX 子构件后，右侧材质修复项继续自动展开并滚动到对应材质；材质 flipU、forceFrontSide 和项目材质覆盖能力继续保留。
  • 自建模板、建筑骨架和行业样例加载后默认进入白模显示，避免暗色主题下组合构件被材质分类色压成黑色剪影。
  • 视口书签支持内联重命名；保存书签前会刷新一次画布，小图预览遇到黑屏捕获时会生成可读兜底预览。
  • 增强轮廓的语义构件标签改为统一标签层，覆盖 instanced batch，并在缩放后约束在视口安全区内。

验证

  • v1.2 release gate 已串联 IFC WebGPU Auto、Bistro WebGPU material-proxy tour、Emerald WebGPU texture-fidelity 和发布矩阵生成。
  • IFC 工程 MEP 样例：Auto 进入 WebGPU imported-model-cache，交互 FPS 约 22.0，draw calls 为 292，BVH 证据为 hidden=33、visible=1241、apply=12。
  • Bistro 重型 FBX：WebGPU imported-material-proxy，demo-tour FPS 约 78.0，draw calls 为 10，route fallback 为 none。
  • Emerald 重型 FBX：WebGPU imported-texture-fidelity，idle FPS 约 19.0，draw calls 为 456，runtime texture count 为 115，Runtime Blob payload 已释放约 1144.1 MB。
  • 已通过 npm run test:v1.2-release-gates、npm run test:ifc-webgpu-proxy-selection、npm run build、npx tsc -p apps\workbench\tsconfig.app.json --noEmit、npm run lint -- --format stylish 和 git diff --check；ESLint 当前为 0 errors，保留 11 个既有 React hooks warning。
  • 视口体验回归覆盖跨江斜拉桥白模显示、视口书签重命名和增强轮廓语义标签缩放锚定。

已知边界

  • WebGPU 仍是可解释、可验证的高性能路径之一，不是全部模型的唯一正式后端；WebGL 和 Auto 降级路径必须继续保留。
  • 需要精确到三角面、像素或面的拾取、测量和捕捉时，仍应使用 WebGL 或后续专门的 GPU picking / CPU BVH 同步方案；v1.2.0 不把 WebGPU 包围盒代理选择写成完全精确交互。
  • Emerald 级超大贴图模型仍可能出现 Chrome Private Memory 高峰；本版本已闭合 Runtime Blob payload 释放证据，但浏览器图像解码、GPU 纹理映射和进程级内存仍需继续专项观测。
  • 完整 Compute Shader 剔除、遮挡剔除、GPU LOD 和 GPU 碰撞检查不属于 v1.2.0 承诺范围。
  • route fallback 当前由 smoke runner 和 v1.2 发布矩阵记录，尚未写入 Viewer runtime store。

v1.1.1

2026-06-25
补丁发布

修复

  • 修复 IFC 模型在 Auto/WebGPU 渲染后端下通过本地模型缓存显示时，材质可能整体变黑的问题。
  • WebGPU 下 IFC 本地缓存材质改用不依赖光照的基础材质路径，保留 IFC base color、透明度、双面和顶点颜色；WebGL 仍保留原有标准材质路径。
  • 修复 FBX 模型在强制 WebGPU 或 IFC -> FBX 混合导入顺序下，direct / texture-fidelity 路径保留光照依赖材质而导致局部或整体黑色显示的问题。
  • WebGPU 下 FBX direct / texture-fidelity 路径在入场前增加基础材质兜底，保留 diffuse map、透明度、side、vertex color 和常用贴图引用；WebGL 与 Auto 的 FBX WebGL 稳定基线不受影响。
  • 底部渲染后端控件改为明确选择菜单，可直接选择自动、WebGPU 或 WebGL；FBX / IFC 导入后手动 WebGPU 不再被自动拦回 WebGL。

验证

  • 补充 IFC WebGPU smoke 的 near-black / dark material ratio 门禁，避免黑材质回归只被人工截图发现。
  • 已验证 Auto -> WebGPU 和强制 WebGPU 两条 IFC 本地模型缓存路径，材质 near-black ratio 均为 0。
  • 补充 FBX smoke 的 IFC 预加载参数和 near-black / dark material ratio 门禁，覆盖 IFC -> FBX 混合导入顺序；SpeedTree FBX WebGPU 目标路径验证 near-black ratio 为 0。
  • WebGPU 间接绘制门禁补充手动渲染后端选择断言，确保旧的 FBX 热切 WebGPU 拦截逻辑不会回归。

v1.1.0

2026-06-24
稳定发布

发布性质

  • 这是 v1.1.0 的正式稳定发布版本，覆盖从 v1.0.0 首个公开基座、v1.0.1 演示修复到 v1.1.0 性能与交互收口的完整变化。
  • 2026-06-17 的 beta 演示验证不再作为公开正式版本单列；相关性能、语义几何和大模型验证结果合并进入本次稳定发布说明。
  • 发布前完成依赖漏洞审计与逻辑评审：修复 DOMPurify 链路漏洞，升级主应用 Vite 链路，并用 VitePress override 关闭旧 Vite/esbuild 开发服务器 advisory。

从 v1.0.0 起保留的基础能力

  • 样例资源入口：提供 IFC 工程样例、GLB/FBX 材质和行业模型样例，以及自建土建/结构模型样例。
  • 模型导入：支持 .ifc、.glb、.gltf、.obj、.fbx，并支持多文件模型和依赖贴图选择流程。
  • IFC 浏览：支持 IFC 几何显示、空间树、构件选择、基础属性摘要和导入状态展示。
  • 项目文件：支持 .egl.json 保存、打开、另存为、撤销和重做；系统保存对话框需在 localhost、127.0.0.1 或 https 安全上下文中使用。
  • 工作台入口：更新记录、产品路线图、操作说明、版本号、关于面板和筑见实验室官网入口保持公开可访问。

v1.0.1 后续修复并入

  • 修复 IFC 资源释放逻辑，避免重复 dispose 和幽灵映射条目。
  • 修复移动端和低配环境下 FBX 材质、贴图缓存和纹理转码路径的稳定性问题。
  • 修复 OPFS 缓存清理、恢复和样例资源重复打开时的边界行为。
  • 修复窄屏工具栏、浮层和 V1 演示流程中的布局与交互问题。
  • 补强 V1 demo flow、项目重开和 release pack 验证，降低公开演示风险。

材质与贴图系统

  • 内置建筑材质库：加入混凝土、砖、墙面、屋面、地面、沥青、砂石、木板、金属等离线材质资产，并保留 Poly Haven 来源许可说明。
  • 自有构件材质：自建墙、板、洞口、基础、围护、场地和结构构件支持项目材质贴图，不再只依赖纯色分类显示。
  • 按面材质：自有构件支持按表面分配材质，项目文件能够保存和恢复表面材质关系。
  • 导入模型材质：FBX 大模型在 WebGPU 路径下保留贴图保真，避免为了稳定性直接退化成无贴图显示。
  • 子构件材质覆盖：导入网格子构件支持绑定项目材质，属性面板可连续替换材质并保持选择上下文。
  • 移动端与缓存：材质贴图转码、移动端材质缓存和 OPFS 资产引用做了失败清理与恢复约束，避免缓存写失败污染项目保存态。
  • 材质默认态：发布视口默认进入材质分类色模式，底部材质控件显示更清楚，白模仍作为可切换视图保留。
  • 选中高亮一致性：材质对象被选中时统一使用选中高亮色，避免项目材质覆盖选中状态。

渲染与大模型性能

  • 大场景性能路径：worker 侧实例化编译、视锥剔除、性能场景加载器和性能快速面板进入稳定发布口径。
  • WebGPU 路径：建立 WebGPU indirect、compute 控制绘制预算、矩阵压缩和真实模型渲染后端对比证据链。
  • 自动渲染策略：自动后端选择开始结合运行时健康状态和大模型实测结果，降低 FBX 后端切换导致的稳定性风险。
  • WASM 空间查询：50 万级空间索引查询基准和降级验证继续支撑拾取、可见性、剖切候选集和交互查询复用。
  • IFC 本地缓存可见性：IFC 缓存可见性接入 WASM BVH 后端，并补充 WebGPU cache 与 proxy hydration 门禁。
  • 大 FBX ZIP 导入：降低完整导入内存峰值，补齐重型源模型指标和导入门禁。
  • 漫游体验：大模型浏览速度按相机上下文适配，避免为了“快”牺牲近距离操作舒适性。
  • 性能诊断：补充加载耗时、FPS、长任务、heap、可见对象、worker culling、实例化编译模式和结构化 Benchmark 报告。

工程语义与自建模

  • 建筑语义几何：墙、板、洞口、管线具备可审计的参数、几何输入、BRep 输出和降级契约。
  • 几何内核：补齐自有几何内核能力清单、profile 契约、几何容差契约和 contract matrix 验证。
  • 自建模入口：补齐工程语义构件、OpenPlans 对照基础组件、命令式参数入口和工具栏语义图标。
  • 构件工程量：提前接入构件工程量摘要，为后续工程量、审查和 AI 解释预留对象级数据基础。
  • 工程视图快照：标准化工程视图快照导出，便于把当前视角、对象状态和审查上下文转成可交付材料。
  • 项目文件兼容：保留语义几何 profile / path、材质分配、网格捕捉、项目树交互和参数化工作台等扩展字段的保存、恢复和边界验证。

交互、UI 与发布体验

  • 底部状态控件：收紧轮廓、视口策略、渲染后端和材质显示按钮的窄屏布局，避免状态区挤压与标签重复。
  • 项目对象定位：项目树中的模型、标高和轴网定位按钮统一触发视口聚焦，并给出明确状态反馈。
  • 选择工具：右侧定位按钮能区分选中对象和导入子对象，选择工具可在工作区内移动，项目选择更容易发现。
  • 工程视口策略：产品化工程视口稳定策略，支持网格捕捉状态契约、清晰的状态栏反馈和更低噪音的轴网线。
  • 样例入口：样例资源入口面板进一步说明导入边界，减少重型样例、缓存命中和依赖恢复时的误解。
  • 自动演示：演示路线支持现场调速，演示速度可到 5x，便于课堂、路演和受控体验。
  • 图标语义：调整场景动作图标，并新增工具栏图标语义验证脚本，降低相似图标误用风险。
  • 发布口径：应用版本、知识面板、更新记录、路线图和操作说明统一收口为 v1.1.0 稳定发布。

安全与发布工程

  • 依赖漏洞：DOMPurify 升级到修复版本，主应用 Vite 升级到 8.1.0，VitePress 内部 Vite 通过 override 覆盖到 6.4.3。
  • 依赖树：重建 package-lock，修复 npm audit 与 npm ls 中的 invalid tree / vulnerable transitive dependency 问题。
  • 发布验证：补充 release pack、bundle boundary、graphics platform gates、项目文件兼容、材质回归、WebGPU/IFC/FBX smoke 和性能预算类验证入口。
  • 运行边界：加入 _headers、跨源隔离下 IFC WASM 初始化修复和 Vite define 隔离状态修复，降低发布环境差异带来的运行风险。

已知边界

  • WebGPU 仍保留为预览路径；正式体验必须继续支持 WebGL 和自动降级路径。
  • VitePress 1.6.4 目前仍是上游最新稳定版本，本仓库通过 npm override 覆盖其内部 Vite 到 6.4.3，并已通过 docs build 验证。
  • 复杂楼板洞口、路径管线自动生成、完整 Revit/CAD 替代、完整 MEP 建模、复杂族库、施工图体系和 IFC 写回仍不属于本版本承诺。

v1.0.1

2026-06-15

修复

  • 修复 IFC 资源释放逻辑，避免重复 dispose 和幽灵映射条目。
  • 修复移动端和低配环境下 FBX 材质、贴图缓存和纹理转码路径的稳定性问题。
  • 修复 OPFS 缓存清理、恢复和样例资源重复打开时的边界行为。
  • 修复窄屏工具栏、浮层和 V1 演示流程中的布局与交互问题。

改进

  • 补强 V1 demo flow、项目重开和 release pack 验证，降低 v1.0.0 发布后第二天反馈中的演示风险。
  • 收敛更新记录、产品路线图、操作说明和关于面板的公开入口。

v1.0.0

2026-06-14

新增

  • 样例资源入口：加入 IFC 工程样例、GLB/FBX 材质和行业模型样例，以及自建土建/结构模型样例，体验者可以直接选择导入，不需要自己找模型文件。
  • 模型导入：支持 .ifc、.glb、.gltf、.obj、.fbx，并支持多文件模型和依赖贴图选择流程；v1 样例资源入口不单独提供 .gltf 或 .obj 样例。
  • IFC 浏览：支持 IFC 几何显示、空间树、构件选择、基础属性摘要和导入方式展示。
  • 项目文件：继续支持 .egl.json 保存、打开、另存为、撤销和重做。
  • 用户入口：更新记录、产品路线图、操作说明、版本号和关于面板统一指向稳定公开路径，并提供筑见实验室官网入口。

改进

  • 项目面板：合并项目对象、IFC 层级和属性查看主路径，语义树降为可选入口，减少无关按钮和视觉噪音。
  • 性能观察：默认只保留 FPS、渲染面、原始面、对象、调用和材质/贴图等日常指标。
  • 高级诊断：质量模式、几何内核、缓存、实例化、BVH 和问题日志统一收敛到高级诊断入口。
  • 紧凑面板：项目面板、缓存和性能信息默认使用更低噪音的紧凑面板。

性能与加载

  • 大模型体验：围绕 700 万级原始面工程项目型模拟建立 realProjectM 发布门禁。
  • 交互口径：区分按需渲染唤醒样本和真实交互 FPS，不把唤醒样本伪装成持续帧率。
  • 本地缓存：大体量模型的解析与缓存尽量在浏览器本地完成，降低重复加载成本。
  • 按需加载：IFC、贴图和大模型相关能力按使用场景加载，不在首屏一次性加载全部能力。

已知边界

  • IFC 当前定位是解析、浏览、基础属性查看和空间树/构件选择，不是完整编辑写回。
  • 当前不是成熟 Revit/CAD 替代品，也不承诺完整 MEP 建模、复杂族库、施工图体系或 IFC 写回。
  • 图纸导出当前是工程图纸数据结构验证，不等同于最终 DWG/PDF 出图。
  • BRep、布尔扣洞、复杂曲面和更完整的几何内核能力仍在持续推进。
  • 超大模型、复杂贴图和长时间内存行为仍需要继续用真实样例验证。