DrunkOnJava/rvt-rs
GitHub: DrunkOnJava/rvt-rs
一个离线的、无需 Autodesk Revit 的 Revit 文件字节级读取与分析工具包。
Stars: 4 | Forks: 2
# rvt-rs
**Apache-2.0 净室开发的 Rust/Python 工具包，用于无需安装 Revit 即可检查 Autodesk Revit 文件（`.rvt`, `.rfa`, `.rte`, `.rft`）。** 它能打开 OLE/CFB 容器，解码 Revit 截断的 gzip 流，提取元数据和预览，解析内嵌的 `Formats/Latest` schema，并在涵盖 2016–2026 年 11 个发布的参考语料库中，对所有观察到的 schema 字段编码进行分类。
**这目前还不是一个完整的 Revit 模型读取器。** 基于/schema 驱动的实例遍历已在 Revit 2024–2026 上验证了 `ADocument` 的切入点（仅限文档级别的元数据——不包含每个元素），并且 `Formats/Latest` schema 分类覆盖了 100% 的观察字段编码。IFC4 STEP 导出生成了一个带有类型化元素的有效空间树**（当输入由测试夹具合成的 `DecodedElement` 时）** —— 参见 `tests/fixtures/synthetic-project.ifc`。
**在真实的 `.rvt` 项目文件上，元素提取管道目前无法生成类型化元素** —— 基于 schema 的扫描器在 `Revit_IFC5_Einhoven.rvt` 上仅命中了 405 个类中的 1 个（`HostObjAttr`，一个宽松的父类），而在 `2024_Core_Interior.rvt` 上命中了 0 个类。项目内置了 80 个按类划分的解码器（`elements::all_decoders()` —— Wall, Floor, Door, Window, Column, Beam, Stair, Railing, Rebar, Room/Area/Space, Furniture, DesignOption, Phase, Workset, Electrical/Mechanical/Plumbing FamilyInstance 子类型），但仅针对合成的测试输入进行了测试——它们并未接入到 `iter_elements` 的调度路径中。根本原因调查（`reports/element-framing/RE-01-synthesis.md`）发现，元素实例数据存在于 `Partitions/*` 流中，其传输封装格式尚未被逆向工程破解；当前的遍历器只扫描包含文档级元数据的 `Global/Latest`。Q-01 语料库验证已获得许可并编写了脚本（`tools/fetch-corpus.sh`），但尚未针对 `project_corpus_smoke` 执行。请参阅下方的[尚不可用的功能](#what-does-not-work-yet)。
**随库一起发布的还有一个零上传的客户端浏览器查看器**，已上线于 ` 标记，同时保留路径结构，以确保声明仍然可验证。在针对你自己的文件进行私下运行时，请省略此标志。
## 结果概览
针对一个 400 KB 的 RFA 夹具运行内置的 CLI：
- **元数据**：版本、构建标签、创建者路径、文件 GUID、区域设置 (`rvt-info`)
- **Atom XML**：标题、OmniClass 代码、分类体系（`rvt-info` 解析 `PartAtom`）
- **预览**：干净的 PNG 缩略图，去除了 300 字节的 Revit 封装（`rvt-info --extract-preview`）
- **Schema**：395 个类 + 1,114 个字段 + 每个字段的类型化编码（`rvt-schema`）
- **历史**：保存过此文件的每一个 Revit 版本（`rvt-history`）
- **批量字符串**：3,746 条来自 Partitions/NN 的长度前缀为 UTF-16LE 的记录 —— Autodesk 单位/规格/参数组标识符、OmniClass + Uniformat 代码、Revit 类别标签、本地化的格式字符串（`rvt-history --partitions`）
`rvt-schema` 提取的每一个类和字段名称都已与公开的 `RevitAPI.dll` NuGet 包导出的 C++ 符号列表进行了交叉核对。我们检查过的所有顶级带标签类名称（ADocument, DBView, HostObj, LoadBCBase, Symbol, APIAppInfo, APropertyDouble3, ElementId 等）均出现在该导出列表中，并带有修饰名特征码（例如 `__cdecl NotNull::NotNull(class ADocument *)`），这证实了磁盘上的 schema 名称与编译后的符号是一一对应的。
在同一个 DLL 内的 C++ 断言字符串中也出现了一个构建服务器路径；为了完整性在侦测报告中提到了它，但它并不代表读取器会从 .rvt / .rfa 文件中提取任何此类信息。
## Phase D 发现（本项目的与众不同之处）
六项可重现的发现，均记录在 [`docs/rvt-moat-break-reconnaissance.md`](docs/rvt-moat-break-reconnaissance.md) 中，并可从 `examples/` 重现：
1. **schema 为数据建立索引。** 类名不以 ASCII 形式出现在 `Global/Latest` 中；来自 `Formats/Latest` 的类标签（类名后的 u16，设置了 0x8000 标志）的出现频率是均匀随机率的约 340 倍。排在首位的标签 `AbsCurveGStep` 在 938 KB 的解压后 Global/Latest 中出现了 19,415 次。[`examples/link_schema.rs`]
2. **标签在不同版本间会发生漂移**，但是是通过稳定排序分配的。`ADocWarnings` = 0x001b（从 2016→2026 不变），因为在按字母顺序排在它前面的类从未被添加过。`AbsCurveGStep` 在这十年间随着插入了 19 个新的 A 类条目，从 0x0053 偏移到了 0x0066。完整的 122 个类 × 11 个版本的漂移表：[`docs/data/tag-drift-2016-2026.csv`](docs/data/tag-drift-2016-2026.csv)，在 [`docs/data/tag-drift-heatmap.svg`](docs/data/tag-drift-heatmap.svg) 中进行了可视化。此数据的首个公开可用版本。[`examples/tag_drift.rs`]
3. **Revit 2021 是一次重大的未记录格式过渡。** Global/Latest 增长了 27 倍（~26 KB → ~715 KB），同时 Forge Design Data Schema 命名空间（`autodesk.unit.*`, `autodesk.spec.*`）在 Partitions/NN 中首次亮相。两种症状，一个事件。任何为 2016-2020 构建的读取器在指向 2021+ 时都会无声无息地丢失 30 倍以上的数据。
4. **参数组命名空间在 Revit 2024 中单独发布。** `autodesk.parameter.group.*` 标识符仅出现在 2024 及以后版本中——比单位/规格晚了三个版本。从磁盘上的字节确定 Forge schema 推出的时间：[`examples/tag_drift.rs`](examples/tag_drift.rs)，[`src/object_graph.rs`](src/object_graph.rs)。
5. **族文件中有一个稳定的 Revit 格式标识符 GUID。** 在 `.rfa` 族文件中，解压后的 `Global/PartitionTable` 为 167 字节，并且**在所有 Revit 版本 2016-2026 中，这些字节中有 165 个是逐字节相同的**（98.8% 不变）。该不变区域包含一个前所未见的 UUIDv1：`3529342d-e51e-11d4-92d8-0000863f27ad`。MAC 后缀 `0000863f27ad` 与大约 2000 年已知的 Autodesk 开发工作站特征码相匹配。这对于族文件检测很有用。**范围更正（2026-04-21）：** 这个不变量是一个*族文件*锚点，而不是通用的 Revit 文件锚点。我们探测的三个真实的 `.rvt` 项目文件在一个较短的 87 字节 `PartitionTable` 中带有三个不同的 GUID（Revit 2023 上是 `6a6261fd-...`，2024 上是 `552368c6-...`，2025 上是全零）。使用族 GUID 的文件类型嗅探器能正确拒绝非族文件，但无法识别它们。参见 [`docs/project-file-corpus-probe-2026-04-21.md`](docs/project-file-corpus-probe-2026-04-21.md)。[`examples/partition_full.rs`]
6. **带标签的类记录结构已解码。** `Formats/Latest` 中的每个类声明都带有一个显式标签（带有 0x8000 标志的 u16）、可选的父类和声明的字段计数，随后是 N 个包含名称 + C++ 类型编码的字段记录。`HostObjAttr` 现在解析为 `{tag=107, parent=Symbol, declared_field_count=3}`，所有三个字段名（`m_symbolInfo`, `m_renderStyleId`, `m_previewElemId`）均被逐字节提取。[`examples/record_framing.rs`, `src/formats.rs`]
在 Autodesk 发布的参考内容中还发现了三种无意披露的模式——为了避免再次传播，本 README 中隐去了具体值；为了安全研究的可重现性，被记录在 [`docs/rvt-moat-break-reconnaissance.md`](docs/rvt-moat-break-reconnaissance.md) 中：
- 一个面向客户的 OneDrive 路径，泄露了 Autodesk 员工个人样本创作工作流的目录结构。
- 一个固化在公共 `RevitAPI.dll` 内 C++ 断言字符串中的构建服务器路径。
- `Contents` 流内的一个创建者名称字段，它会随着样本族的每个副本传播，保留了 Revit 1997 年最初开发人员之一的姓名。
**下游安全：** `rvt-analyze` CLI 自带 `--redact` 标志（在此 repo 中提交的任何演示输出中默认开启），它会将创建者路径、Autodesk 内部路径和构建服务器路径重写为 `` 标记，同时保留周围的结构。任何消费 rvt-rs 输出并对其进行公开展示的工具都应该这样做。
## 库接口
所有模块均在默认构建和 `wasm` 功能标志下进行编译。有关类型文档，请参见 `src/`：
| 模块 | 功能描述 |
|---|---|
| `reader` | 使用 `OpenLimits` 打开任何 Revit 文件，枚举每个 OLE 流，获取原始流字节，有界读取 |
| `compression` | 截断的 gzip 解码（`inflate_at`, `inflate_at_auto`, `inflate_at_with_limits`）+ 多块（`inflate_all_chunks_with_limits`）+ 用于回写的截断 gzip 编码器（`truncated_gzip_encode`） |
| `basic_file_info` | 版本、构建标签、GUID、创建者路径、区域设置 —— 读取路径 + 字节回写编码器（`BasicFileInfo::encode`） |
| `part_atom` | 带有 Autodesk `partatom` 命名空间的 Atom XML —— 标题、OmniClass、分类体系 —— 读取 + 编码 |
| `formats` | 使用 `FieldType` 分类解析 + 编码 `Formats/Latest`（在 11 个版本的语料库上达到 100%） |
| `walker` | 基于 schema 的实例遍历器 + 80 个解码器调度 + `detect_adocument_start` 入口点查找器 |
| `elements` | 80 个 `ElementDecoder` 实现（Wall, Floor, Door, Window, Column, Beam, Stair, Railing, Rebar, Room, Furniture, …） |
| `geometry` | 曲线 / 面 / 实体变体（Line, Arc, Ellipse, NURBS, Hermite, Ruled, Revolved, Extrusion, Sweep, Blend, SweptBlend, Boolean, Mesh, PointCloud） |
| `object_graph` | `DocumentHistory`，用于 Global/Latest + Partitions/NN 的字符串记录提取器 |
| `class_index` | 快速类名清单（BTreeSet） |
| `corpus` | 跨版本字节差异分类器 |
| `elem_table` | `Global/ElemTable` 头解析器 + 粗略的记录枚举 |
| `partitions` | Partitions/NN 44 字节头部解码器 + gzip 数据块拆分器 |
| `writer` | 字节保留的往返 `copy_file` + `write_with_patches`（原子临时文件重命名、流哈希验证）+ GUID + 历史记录保存 |
| `round_trip` | 按类划分的编码器往返验证（`verify_instance_round_trip`） |
| `ifc` | 完整的 IFC4 空间树 + 元素 + 材质 + 属性 + 洞口 + 拉伸几何 + glTF 2.0 二进制（`gltf::model_to_glb`）+ 平面图 SVG（`sheet::render_plan_svg`）+ 查看器数据模型（`scene_graph`, `camera`, `clipping`, `sheet`, `share`, `measure`, `annotation`, `pbr`） |
| `streams` | Revit 文件中每个不变的 OLE 流的命名常量 |
| `redact` | 为所有 CLI 提供的共享 PII 清洗器（`--redact` 标志） |
| `wasm` | `#[cfg(feature = "wasm")]` —— 支持浏览器查看器的 14 个可由 JS 调用的 wasm-bindgen 绑定 |
| `error` | 结构化错误类型（`Error` / `Result`） |
运行时能力：
- 从磁盘打开任何 Revit 文件（magic `D0 CF 11 E0 A1 B1 1A E1`）
- 枚举每个 OLE 流；查找特定版本的 `Partitions/NN`
- 解压任何流（截断的 gzip 格式——标准 gzip 标头，无尾部 CRC/ISIZE）
- 解析 `BasicFileInfo`、`PartAtom`，提取预览 PNG
- 从 `Formats/Latest` 中提取 **395 条类记录**，包含每个带标签类的标签 + 父类 + 祖先标签 + 声明的字段计数
- 解码 167 字节的 `Global/PartitionTable` 结构，包括稳定的 Revit 格式标识符 GUID
- 解码 307 字节的 `Contents` 流，包括内嵌的 UTF-16LE 元数据块
- 生成任何 `.rfa` / `.rvt` 文件的逐字节往返副本
- 每个文件在完整的 11 个版本的语料库上运行耗时 < 500 ms（release 构建）
内置 **14 个 CLI**：
```
cargo build --release
# 一次性取证分析 — 所有 subsystems 汇总于一份报告
./target/release/rvt-analyze --redact my-project.rvt
./target/release/rvt-analyze --redact --json my-project.rvt > report.json
# 快速提取 metadata + schema 摘要
./target/release/rvt-info --show-classes my-project.rvt
# 机器可读 (JSON)
./target/release/rvt-info -f json my-project.rvt > meta.json
# 提取嵌入的缩略图
./target/release/rvt-info --extract-preview preview.png my-project.rvt
# 通俗易懂的文件健康状况与 IFC export 准备度
./target/release/rvt-inspect my-project.rvt
./target/release/rvt-inspect my-project.rvt --json
# 比较同一文件的两个版本 (cross-version byte diff)
./target/release/rvt-diff --decompress 2018.rfa 2024.rfa
# 导出完整的 class schema (395 个 classes，13,570 个 fields)
./target/release/rvt-schema my-project.rvt
# 文档升级历史 (哪些 Revit 版本打开过此文件)
./target/release/rvt-history my-project.rvt
# 从 Partitions/NN 中提取所有 UTF-16LE string record
# (categories, OmniClass, Uniformat, Autodesk unit identifiers, …)
./target/release/rvt-history --partitions my-project.rvt
# 对每个 decompressed stream 进行 Hex-dump (用于 Phase D 工作)
./target/release/rvt-dump my-project.rvt
# IFC4 STEP export — 默认生成符合 spec-valid 的 scaffold，并附带如实客观的质量警告
./target/release/rvt-ifc my-project.rvt -o out.ifc
# 在写入 IFC 前要求更严格的质量门禁
./target/release/rvt-ifc my-project.rvt -o out.ifc --mode strict
# 附带可共享的 JSON readiness/support sidecar 的 IFC4 export
./target/release/rvt-ifc my-project.rvt -o out.ifc --diagnostics out.diagnostics.json
# 诊断性 IFC export — 包含带有 provenance 的低置信度 proxy candidates
./target/release/rvt-ifc my-project.rvt -o diagnostic.ifc --diagnostic-proxies
# glTF 2.0 binary export — 可加载至 Three.js / Blender / 任何 glTF viewer 中
./target/release/rvt-gltf my-project.rvt -o out.glb
# 2D plan-view SVG — 按 category 着色，可直接用于 plot/laser-cut/printing
./target/release/rvt-sheet my-project.rvt -o out.svg
# Global/ElemTable dump — 包含已声明的 element-ids + record layout (family 12B / project 28B/40B)
./target/release/rvt-elem-table my-project.rvt --limit 20
# Stream-level write path — 通过 JSON manifest 修补 named OLE streams
./target/release/rvt-write my-project.rvt --patches patches.json -o patched.rvt
# 单文件文档生成器 (为任意 RVT 提供 schema + sample-data render)
./target/release/rvt-doc my-project.rvt -o doc.md
# Cross-version corpus 分析 (一次性处理 11 个 releases)
./target/release/rvt-corpus /path/to/corpus-dir
```
`examples/` 中提供了三十六个可重现的探测程序——侦测报告中的每个 FACT 各一个：
```
cargo build --release --examples
# --- schema ↔ data linkage (Phase D) ---
./target/release/examples/probe_link # null-hypothesis: class names absent from Global/Latest
./target/release/examples/tag_bytes # hex around known class names in Formats/Latest
./target/release/examples/tag_dump # statistical sweep of post-name u16 patterns
./target/release/examples/link_schema # tag-frequency histogram in Global/Latest (340× non-uniformity)
./target/release/examples/tag_drift # per-class drift table 2016-2026
./target/release/examples/tag_drift_svg # render drift table as colour-coded SVG heatmap
# --- record framing (Phase 4c) ---
./target/release/examples/record_framing # dump bytes at tagged-class defs + first tag occurrence
./target/release/examples/elem_table_probe # Global/ElemTable structural sweep across releases
./target/release/examples/partitions_header_probe # 44-byte Partitions/NN header + chunk offsets
./target/release/examples/contents_probe # Contents stream decoder (creator name + build tag)
# --- stable anchors ---
./target/release/examples/partition_invariant # find 165-byte invariant in Global/PartitionTable
./target/release/examples/partition_diff # show the 2 varying bytes per release
./target/release/examples/partition_full # full annotated hex dump + UUID decode
# --- write path (Phase 6) ---
./target/release/examples/roundtrip # copy 2024 sample, verify all 13 streams identical
```
## 格式概述
每个 Revit 文件都是一个 Microsoft Compound File Binary (OLE2) 容器，具有
此流布局（在 Revit 发布的 11 年间保持不变）：
```
├── BasicFileInfo UTF-16LE metadata
├── Contents custom 4-byte header + DEFLATE body
├── Formats/Latest DEFLATE — class schema inventory
├── Global/
│ ├── ContentDocuments tiny document list
│ ├── DocumentIncrementTable DEFLATE — change tracking
│ ├── ElemTable DEFLATE — element ID index
│ ├── History DEFLATE — edit history (GUIDs)
│ ├── Latest DEFLATE — current object state (17:1 ratio)
│ └── PartitionTable DEFLATE — partition metadata
├── PartAtom plain XML (Atom + Autodesk partatom namespace)
├── Partitions/NN bulk data: 5-10 concatenated DEFLATE segments
│ NN = 58, 60-69 for Revit 2016-2026
├── RevitPreview4.0 custom header + PNG thumbnail
└── TransmissionData UTF-16LE transmission metadata
```
所有压缩流都使用“截断的 gzip”格式——标准的 10 字节
gzip 标头（magic `1F 8B 08 ...`）后跟原始的 DEFLATE 数据，但*没有*
合规的 gzip 写入器会生成的尾部 8 字节的 CRC32 + ISIZE。
Python 的 `gzip.GzipFile` 和 Rust 的 `flate2::read::GzDecoder` 都会拒绝
这些流。解决方法是手动跳过 10 字节的标头，并
在原始正文上使用 `flate2::read::DeflateDecoder`。
## 逆向工程状态
| 层级 | 描述 | 状态 |
|---|---|---|
| 1 · 容器 | OLE2 / Microsoft Compound File ([MS-CFB]) | **完成** |
| 2 · 压缩 | 截断的 gzip → 原始 DEFLATE | **完成** |
| 3 · 流框架 | 每个流的自定义标头，`Partitions/NN` 数据块布局，`Contents` / `Preview` / `PartitionTable` 封装 | **完成** —— `PartitionTable` 的 165/167 个字节保持不变；44 字节的 `Partitions/NN` 标头已解码；`62 19 22 05` 封装 magic 已在 `Contents` + `RevitPreview4.0` 上确认 |
| 4a · Schema 表 | 来自 `Formats/Latest` 的类名 + 字段 + C++ 类型特征码；按类划分的标签 + 父类 + 声明的字段计数；跨版本标签漂移图 | **完成** |
| 4b · Schema→数据链接 | 来自 `Formats/Latest` 的标签在 `Global/Latest` 中的出现频率约为噪音率的 340 倍；schema 正是对象图的实时类型字典 | **完成** |
| 4c.1 · 记录框架 | `Formats/Latest` 中带标签的类记录解析为结构化记录：`{tag, parent, ancestor_tag, declared_field_count}`；HostObjAttr → `{tag=107, parent=Symbol, ancestor_tag=0x0025 → APIVSTAMacroElem, declared_field_count=3}` | **完成** |
| 4c.2 · 字段正文解码 | `FieldType` 枚举对跨 8 种变体（Primitive, String, Guid, ElementId, ElementIdRef, Pointer, Vector, Container）的 **100%** 的 schema 字段进行了分类。映射了 11 个判别字节，包括广义的标量基 Vector/Container（`{kind} 0x10 ...` / `{kind} 0x50 ...`）以及 `0x0d` 点类型基。 | **完成（在跨 11 个版本的语料库的 13,570 个字段上达到 100.00%；无 `Unknown`）** |
| 4d · ElemTable | `Global/ElemTable` 头解析器 + 粗略记录枚举；由于等待每个元素的 schema 查找，记录语义仍未解决 | **部分完成** |
| 5 · IFC4 导出 | 完整的空间树 + 按元素划分的 IFC 实体 + `IfcLocalPlacement` + `IfcExtrudedAreaSolid` + 复合材质层 + 类型化属性集 + 用于门和窗的 `IfcOpeningElement`/`IfcRelVoidsElement`/`IfcRelFillsElement`。确定性的 ISO-10303-21 输出。经 IfcOpenShell + BlenderBIM 验证。 | **完成**（矩形轮廓；swept / revolved / BRep 回退已交付，但在默认发射路径中使用矩形——IFC-17/24 是待完善的部分） |
| 6 · 写入路径 | 对未更改文件的字节保留副本；对命名的 OLE 流进行流级补丁，带有原子临时文件重命名、按流验证、扩充/缩减/多流覆盖以及 GUID/历史记录保存检查。字段级语义补丁属于 Phase 7。 | **完成（流级）；字段级待定** |
| 7 · 浏览器查看器 | 核心库的 WebAssembly 构建 + Three.js + Vite + Pages 部署。零上传，标签页内解析，glTF/IFC/SVG 导出按钮，URL 状态分享。上线于
标签：Autodesk Revit, BIM, IFC, Rust, 云资产清单, 数据解析, 文件格式, 网络流量审计, 逆向工程, 通知系统