ReadAllandExplains 4.8.1

ReadAllandExplains 4.8.1

ReadAllandExplains 4.8.1 是 4.8.0 的确定性修复版本。它修复 Texture 可读文档分辨率和 Blueprint Pin 身份在重复导出、跨 UE 进程时可能漂移的问题，不增加新的资产类型或 MCP 接口。

运行环境

Unreal Engine   5.7
操作系统        Windows 64 位
插件模块类型    Editor
Python          3.9+（仅 CodeBuddy / MCP 需要）

发布包包含 UE 5.7 / Win64 编辑器二进制。其他 UE 5.x 版本需要针对对应引擎重新编译，并重新验证导出结果。

修复内容

Texture Resolution 使用导入源尺寸

Texture 可读文档不再使用异步平台数据编译期间可能返回占位尺寸的 UTexture2D::GetSizeX() / GetSizeY()，改为读取 GetImportedSize()。同一纹理不会再因加载时机不同而在 32 x 32 与真实 16 x 16 之间漂移。

Blueprint Pin 使用稳定身份

Blueprint 导出不再直接把可能随图重建变化的运行态 UEdGraphPin::PinId 当作稳定身份：

• 有效 PersistentGuid 优先作为 Pin 身份。
• 无持久 GUID 时使用 NodeId:pin:PinIndex 结构身份。
• Link 端点与 Pin 使用同一规则，保持引用闭包。
• Niagara 保留原有 Pin ID 路径，本次不扩大到已验证稳定的 Niagara 行为。

验证结果

• MCP 契约测试：58 项通过，1 项预期跳过。
• Golden 回归：22/22 通过。
• UE 5.7 CompileHost 与 UE 5.8 BuildPlugin 均编译通过。
• 两个独立 UE 5.7 进程各连续导出两次同条件 Waterfall Pack，共 4 份。
• 四次均为 complete、依赖深度 2、资产 39/39、失败 0、清单完整性错误 0。
• 同进程和跨进程规范化 Golden 均为 82/82。
• 跨进程除 context-pack.json 的 Pack 身份字段外，其余 81 个内容文件字节一致。
• 两张问题纹理四次均稳定为 16 x 16，文件 SHA1 一致。
• Blueprint 节点内重复 Pin ID 为 0，所有 Link 端点均可解析。
• 修复前 Pack 对新基线的阴性对照正确失败，证明检测门禁能够识别原缺陷。

升级与兼容性

从 4.8.0 升级时，请关闭 Unreal Editor 和 CodeBuddy，备份并完整替换 Plugins/ReadAllandExplains，不要把新文件覆盖进旧目录后保留陈旧文件。

本版会改变部分 Blueprint pin_id 的表示。旧 Pack 仍可读取，但不要在 4.8.0 与 4.8.1 Pack 之间复用 Pin ID 缓存；建议为关键资产重新生成 Context Pack。节点、参数与连线语义经归一化审计保持一致。

明确边界

• 本次 82/82 结论绑定所测 Waterfall 39 资产样本，不能外推为所有 UE 资产在所有引擎版本上绝对确定。
• 静态 Context Pack 不能证明 GPU 逐帧结果、PIE 时序或运行时参数最终值。
• UE 5.8 已通过编译，但本版正式二进制与真实导出验证仍以 UE 5.7 / Win64 为准。
• UE 5.8 的 GetObjectsWithOuter 弃用警告仍是独立技术债，须在 UE 5.9 前处理。

---

English

ReadAllandExplains 4.8.1 is a determinism patch for 4.8.0. It fixes Texture readable-resolution drift and Blueprint Pin identity drift across repeated exports and fresh UE processes. It adds no new asset type or MCP interface.

Fixes

• Texture readable documents now use GetImportedSize() instead of platform-data dimensions that may temporarily report a placeholder while asynchronous compilation is in progress.
• Blueprint Pins prefer UE's persistent PersistentGuid; Pins without one use deterministic NodeId:pin:PinIndex identities.
• Graph links use the same identity rule as their Pin endpoints.
• Niagara keeps its existing Pin ID path to avoid widening this behavioral change.

Verification

The MCP contract suite and 22 Golden tests pass. Two independent UE 5.7 processes produced four complete depth-2 Waterfall Packs at 39/39 assets. All normalized comparisons passed at 82/82; outside the manifest's per-Pack identity fields, all 81 content files were byte-identical across processes. The old implementation correctly fails the new baseline as a negative control.

Upgrade note

Blueprint pin_id representation changes for affected Pins. Existing Packs remain readable, but do not reuse Pin ID caches across 4.8.0 and 4.8.1 Packs. Regenerate important Context Packs after upgrading.

The published binary targets Unreal Engine 5.7 on Windows 64-bit. UE 5.8 compilation passes, but UE 5.7 remains the validated runtime-export target for this release.

ReadAllandExplains 4.8.0

ReadAllandExplains 4.8.0

UE 资产证据编译器。把蓝图、材质和 Niagara 资产编译成可被 AI 渐进式查询的静态证据快照，每条结论都能回指到快照中的确切位置。

本版本的主线变化

原生索引由导出器写入

4.7 及之前，图索引是 MCP 在内存中派生的：每次读取都要重新枚举一遍全部图、节点和引脚，并发出 GRAPH_INDEX_DERIVED 警告说明这份索引不是 UE 原生字段。

4.8 把索引构建移进导出器。metadata.graphIndex 现在是落盘的一等字段，包含根级汇总与每图的 entryPoints / searchIndex，每项携带 jsonPointer。MCP 读取时先校验它与所描述的图是否一致，一致则报 native_metadata_graph_index 且不再发出派生警告。

索引与实际图数据不一致时自动回退到派生路径。一份过期的索引比没有索引更危险，因为调用方会把它当证据引用。

Niagara Custom HLSL 正文成为一等证据

此前 Custom HLSL 节点只导出结构，不导出源码，分析时必须回到编辑器打开节点才能看到正文。现在 sourceCode 随节点一起落盘，可直接被引用和检索。

渐进式查询

get_asset_outline 先给规模概览，locate_graph_target 定位目标，get_graph_subgraph 按预算切片，get_readable_sections 按稳定 section_id 取正文。大型资产不需要整包读入。

本次验证的 Niagara 系统有 20 张图、767 节点、2951 引脚，其中单张模块图 238 节点；蓝图侧 UserConstructionScript 单图 225 节点，是同资产其余六张图总和的七倍多。这类资产整图读入会直接耗尽上下文预算，定位再切片是唯一可行路径。

验证情况

契约与回归

契约测试 57 项、Golden 回归 22 项全部通过。

原生索引覆盖度

对实际导出的 Pack 全量审计：84 个 metadata 文件中 63 个带图，63 个全部携带经校验的原生索引，覆盖度 100%。审计逐项比对落盘 graphIndex 与同文件 graphs 的图标识、节点数、引脚数、连线数、jsonPointer 与根级汇总。

审计器本身做了阴性对照：篡改计数与指针后必须失败并指名问题字段。一个不会失败的检查不构成证据。

双部署读取确定性

同一份不可变 Pack，由两个独立部署、独立进程、独立工作目录分别读取，比对 5 组查询的 63 个叶字段，零分歧。

A  工作区部署        C:\...\ReadAllandExplains_4.8.0_mvp\...
B  UE 项目安装部署   D:\UE5\Trans\plugins\ReadAllandExplains\...

比对器同样有阴性对照：篡改两个字段后精确命中两处并返回 FAIL。

详见 CP7_DUAL_ENDPOINT_RESULT.md，原始采集结果在 docs/evidence/。

本版本明确不主张的结论

以下边界如实列出，以免被误读为更强的保证。

双部署一致不等于两套独立实现互相印证。 两个端点运行同一份源码，SHA256 已确认相同。这轮排除的是部署漂移、进程状态残留和配置相关行为差异，不构成跨实现的交叉验证。真正的交叉验证需要第二套独立实现，本项目没有。

读取一致不等于导出正确。 若导出阶段漏采了某个节点，两个端点会一致地漏掉同一个。本版本验证读取确定性与索引自洽性，不证明导出对 UE 内部状态的完整覆盖。

静态快照不能证明运行时行为。 GPU 逐帧结果、动态 Render Target 内容、PIE 时序、参数运行时最终值均不在快照能力范围内，须在编辑器中验证。

覆盖度数字绑定具体 Pack。 100% 是对本次审计的 84 资产 Pack 而言。更大规模或含异常资产的 Pack 需要重新实跑审计，不能沿用此结论。

一个值得记录的缺陷

locate_graph_target 曾硬编码 graph_index_source 为 derived_metadata_graphs，从未做过实际判断。结果是同一份原生索引 Pack 上，get_asset_outline 报原生而 locate_graph_target 报派生，两个工具自相矛盾。

契约 54 项、Golden 22 项、parity 1619 资产全绿都没有发现它，因为没有任何一条测试断言过该字段。它是在双端比对中被暴露的。

已修复，并补充 3 条回归测试锁定该契约。教训是既有的那条：测试未覆盖的契约变更是静默回归的常见来源。

原先的 parity 脚本也存在同类问题——它用 Python 重建一份索引再与图自比，导出器真正写入磁盘的内容从未被读取，因此在导出器写错时不会失败。本版本已替换为直接校验落盘 graphIndex 的审计器。

版本序列

v4.8.0-preview.1   渐进式证据查询 MVP
v4.8.0-preview.2   编码修正
v4.8.0-preview.3   CP7 原生索引与 Custom HLSL 正文
v4.8.0             正式版

v4.8.0-preview.3 的标签于 2026-08-12 补打在其原始发布提交上，此前该版本已发布但未打标签。标签指向当时的发布提交而非后续状态，以使序列反映实际发布内容。

ReadAllandExplains 4.7.0

ReadAllandExplains 4.7.0

ReadAllandExplains 4.7.0 moves the project from a feature-complete prototype toward a release-grade UE asset context compiler. It adds Blueprint CDO values, UEnum and DataAsset export, readable Material Custom HLSL, deterministic Golden Pack regression, and strict Context Pack integrity rules.

ReadAllandExplains 4.7.0 将项目从功能型原型推进到可正式交付的 UE 资产上下文编译器：新增 Blueprint CDO 值、UEnum、DataAsset、Material Custom HLSL，并建立 Golden Pack 回归与严格的 Context Pack 完整性事务。

Highlights / 核心提升

• Blueprint variables declared by the current generated class now export their Class Default Object values instead of only C++ type names.

• UEnum assets export entry display names and full 64-bit values.

• DataAsset assets have dedicated readable documents and structured Metadata.

• Root-reachable Material Custom nodes export readable pseudo HLSL with code, primary output type, and named inputs.

• Five real UE asset classes are covered by repeatable Golden Pack regression: Blueprint CDO, Material Custom HLSL, Niagara Renderer/Curve, UEnum, and DataAsset.

• Blueprint 当前生成类声明的变量现在导出 CDO 默认值，不再只显示 C++ 类型。

• UEnum 导出条目显示名和完整 64 位值。

• DataAsset 获得专用可读文档与结构化 Metadata。

• 普通 Material 中根属性可达的 Custom 节点可导出代码、主输出类型和命名输入的伪 HLSL。

• Blueprint CDO、Material Custom HLSL、Niagara Renderer/Curve、UEnum、DataAsset 五类真实资产纳入可重复 Golden Pack 回归。

Context Pack Integrity / 数据完整性

• Assets with the same short name but different object paths no longer silently overwrite one another. Collision groups receive deterministic object-path-based suffixes.

• exportFile and metadataFile are mapped consistently in both Index and Manifest.

• Metadata write failure is now an asset export failure.

• A Pack is published as complete only when every attempted asset succeeds, failed/skipped counts are zero, README and both indexes are written, required asset documents and Metadata exist, the Manifest can enumerate every file, and the final directory publish succeeds.

• Failed Packs remain in .tmp with state: failed and diagnostic error codes when failure handling can run. Abrupt interruption may leave writing or complete inside a .tmp directory; MCP, Golden tests, and default Pack discovery reject every .tmp directory regardless of its state.

• SyncLive reports complete only after a Pack is formally published, archives requests only after the result JSON is persisted, and can recover a published Pack by originRequestId after an interrupted result write.

• 不同对象路径下的同名资产不再静默覆盖；碰撞组使用基于对象路径的稳定后缀消歧。

• Index 与 Manifest 同时一致记录 exportFile 和 metadataFile。

• Metadata 写入失败会使该资产导出失败。

• 只有全部资产成功、失败/跳过均为零、README 与双索引写入成功、正文和 Metadata 完整、Manifest 可枚举全部文件且最终目录发布成功时，Pack 才能成为 complete。

• 正常失败处理会在 .tmp 写入 state: failed 和诊断错误；突然中断可能留下 writing 或 complete 状态的 .tmp，但 MCP、Golden 与默认发现流程无条件拒绝所有 .tmp。

• SyncLive 仅在 Pack 正式发布后返回 complete，结果 JSON 落盘成功后才归档请求，并可按 originRequestId 恢复已发布但结果写入中断的 Pack。

Golden Pack Quality Gate / Golden 回归门禁

• Deterministic normalization and semantic comparison for Pack, Index, readable documents, and Metadata.

• Managed baselines, explicit update controls, machine-readable reports, and provenance containing project, UE version, Git HEAD/dirty state, plugin descriptor hash, and loaded DLL hash.

• Windows GitHub Actions quality gate runs Golden and MCP test suites.

• Validation rejects temporary or partial Packs, duplicate case-insensitive paths, missing required files, duplicate asset mappings, and Metadata identity mismatches.

• 对 Pack、Index、可读文档和 Metadata 提供确定性规范化与语义比较。

• 受管 Baseline、显式更新许可、机器可读报告，以及项目、UE 版本、Git、描述符和实际 DLL 哈希来源追踪。

• Windows GitHub Actions 自动执行 Golden 与 MCP 测试。

• 验证器拒绝临时/部分 Pack、大小写等价重复路径、必要文件缺失、资产映射重复和 Metadata 身份串线。

Compatibility / 兼容性

• Target: Unreal Engine 5.7, Windows 64-bit, Editor plugin.

• Existing 4.6 Context Packs remain readable through legacy Metadata object-path fallback.

• Legacy console command GetTheMeaning.ExportAssets remains available.

• CodeBuddy integration still uses the bundled standard-library-only Python MCP; npm is not required.

• 目标平台：Unreal Engine 5.7、Windows 64 位、Editor 插件。

• 通过旧 Metadata objectPath 回退继续读取 4.6 Context Pack。

• 保留旧控制台命令 GetTheMeaning.ExportAssets。

• CodeBuddy 继续使用随插件提供、仅依赖 Python 标准库的 MCP；无需 npm。

Verification / 验证

• Golden unit tests: 22/22 passed.
• MCP contract tests: 32/32 passed.
• UE 5.7 Win64 plugin compilation and DLL link: passed.
• Real UE regression: five asset classes, two runs each, 10/10 passed.
• No unexpected changes in asset readable documents or Metadata during the integrity-contract migration.

Final release artifacts are rebuilt after version stamping. The GitHub Release records the ZIP SHA-256 and final verification provenance.

Installation / 安装

1. Close Unreal Editor.
2. Download ReadAllandExplains_4.7.0_UE5.7_Win64.zip.
3. Extract to <YourProject>/Plugins/ReadAllandExplains.
4. Open the project in UE 5.7, enable the plugin, and restart if requested.
5. For CodeBuddy, add the repository marketplace and install readallandexplains@readallandexplains-marketplace.

完整安装、升级、验证、卸载和故障排查见 docs/INSTALLATION.md。

Known Limitations / 已知限制

• Only UE 5.7 / Win64 is packaged and verified in this release.
• Blueprint export covers Class Default Object values for variables declared by the current generated class; placed Actor/component instance overrides are not exported.
• Custom HLSL code is available in readable Material Markdown, while .meta.json retains generic node/Pin/Link topology; Define, Include, additional-output semantics, and Material Function Custom HLSL are not yet structured.
• SyncLive supplemental Packs remain independent snapshots. Base + Delta overlay queries are planned for a later release.
• Coverage dependencies originating as package paths may require a canonical /Game/Package.Asset object path for targeted snapshot submission.
• Runtime observation, AnimBP state machines, reverse import, and Marketplace publication are not part of 4.7.0.

Upgrade / 升级

Upgrade from 4.6 by replacing the complete plugin directory while UE is closed, then reload CodeBuddy plugins. Do not overlay individual files onto the old directory. Existing exported Packs may be retained; regenerate important snapshots to receive the stricter 4.7 integrity contract.

从 4.6 升级时请在 UE 关闭状态下完整替换插件目录，再重载 CodeBuddy 插件；不要只覆盖部分文件。旧 Pack 可以保留，但建议重新生成关键快照以获得 4.7 的严格完整性契约。

Release Artifact / 发布产物

• File: ReadAllandExplains_4.7.0_UE5.7_Win64.zip
• ZIP SHA-256: 85dabcc8021b78ad8d10a86f3eeefed762e5a5a31ab306e6098d210d87607d3f
• DLL SHA-256: b68eeb4b05ac02b8149122763e7d45db0e92a8b0fd52736ece75dcaca686eb5b
• Source commit: df82485ed260cd25862a006681df757cf477e400
• Verification: Golden 22/22, MCP 32/32, real UE regression 10/10.

ReadAllandExplains 4.6.0

Official 4.6.0 release: trustworthy MCP, progressive analysis, SyncLive Lite, CodeBuddy native integration, UTF-8 stdio fix, bilingual README.

ReadAllandExplains 4.2.0-preview.1

ReadAllandExplains 4.2.0-preview.1

本版本以“不破坏当前可用 Niagara 导出”为首要原则，将 Niagara 图数据增量接入现有 Schema 2 统一 IR。

主要更新

1. 新增 Niagara System、Emitter、Script 源图的统一 IR 采集。
2. 导出 Graph、Node、Pin、Link、节点位置、默认值、函数名与脚本引用。
3. Parameter Map 连线标记为 parameter-map，普通数据连线标记为 data。
4. 按源图路径去重，避免 System、Emitter 与 Script 共享图被重复写入。
5. 原 _ReadableNiagara.md 文本导出器零改动，现有使用入口与详细内容保持兼容。

累积优化

1. 插件定位从资产文字翻译器升级为 UE 资产 AI 上下文编译器。
2. 使用 Compact Markdown + JSON IR 双产物，显著降低文本体量和 Token 噪声。
3. Blueprint 与 Material 已使用 Schema 2 节点、Pin、连线统一结构；本版扩展到 Niagara。
4. 材质函数短名与 Named Reroute 穿透，改善伪 HLSL 与真实依赖追踪。
5. 自动生成 Feature Tags、美术速读、参数线索、直接依赖图与 AI 提示词。
6. 支持 Unreal Engine 5.7，并保留无界面批量导出命令。

兼容性

• 引擎：Unreal Engine 5.7
• 平台：Win64 Editor
• 旧命令：GetTheMeaning.ExportAssets 继续兼容
• 新命令：ReadAllandExplains.ExportAssets
• 旧 Niagara Markdown：保持不变

验证

• UnrealHeaderTool：通过
• C++ 编译：通过
• DLL 链接：通过
• 当前 Trans 部署目录未在编辑器运行期间覆盖

后续计划

• Niagara 参数级 DAG
• 递归依赖导出
• Live Sync
• 反向导入与正式发布流程

ReadAllandExplains v4.1.0-preview.1

English

ReadAllandExplains 4.1.0-preview.1 expands the plugin from graph text export into a compact, artist-friendly asset documentation workflow for Unreal Engine 5.7.

Highlights

• Added a consistent intermediate document model for readable Markdown and structured metadata.
• Added artist-oriented summaries, feature tags, dependencies, referencers, and AI hand-off prompts.
• Added Static Mesh, Texture, Data Table, and Curve Table exporters.
• Added Artist, Compact, Full, and Reconstruction export modes.
• Added Explain, Review, Optimize, Trace, and custom prompt modes.
• Added Content Browser, Window menu, Reference Viewer, console, and unattended batch workflows.
• Expanded Material graph capture and improved output structure.

Compatibility and installation

• Unreal Engine 5.7 editor plugin.
• The attached ZIP includes Win64 editor binaries and full source.
• Extract ReadAllandExplains to <YourProject>/Plugins/ and restart Unreal Editor.
• Full English and Chinese documentation is included in README.md.

Validation

• Loaded successfully in the UE 5.7 Trans project.
• Unattended export test completed with success=2, failed=0, skipped=0.

Package checksum

SHA-256: 26AFE26461A87A4DDFEB201DD978355CA540964ECF8878EDC1FCFE43EF04FC13

---

中文

ReadAllandExplains 4.1.0-preview.1 将原有的图表文本导出能力扩展成一套适用于 Unreal Engine 5.7 的精简型、美术友好的资产文档工作流。

主要更新

• 新增统一的中间文档结构，用于生成易读 Markdown 和结构化元数据。
• 新增面向美术的概览、特征标签、依赖项、引用项和 AI 交接提示词。
• 新增 Static Mesh、Texture、Data Table 和 Curve Table 导出器。
• 新增 Artist、Compact、Full 和 Reconstruction 导出模式。
• 新增 Explain、Review、Optimize、Trace 和自定义提示词模式。
• 新增内容浏览器、Window 菜单、Reference Viewer、控制台及无人值守批量工作流。
• 扩展材质图捕获信息，并改善输出文档结构。

兼容性与安装

• Unreal Engine 5.7 编辑器插件。
• 附带 ZIP 包含 Win64 编辑器二进制文件及完整源码。
• 将 ReadAllandExplains 解压到 <你的项目>/Plugins/，然后重启 Unreal Editor。
• 完整的英文和中文说明已包含在 README.md 中。

验证结果

• 已在 UE 5.7 的 Trans 项目中成功加载。
• 无人值守导出测试结果：success=2、failed=0、skipped=0。

安装包校验值

SHA-256: 26AFE26461A87A4DDFEB201DD978355CA540964ECF8878EDC1FCFE43EF04FC13