Erlang BEAM 文件¶

inspect_erlang_beam / inspect-erlang-beam 用于回答以下问题：所选的单个本地文件是否为 FOR1/BEAM IFF 容器；该格式存储了哪些 chunk；这些 chunk 携带哪些 atom、export、import、lambda 和 Code 头部字段。它只读取文件而不执行字节码，也无需安装 Erlang 或 BEAM 模拟器。

rea inspect-erlang-beam /absolute/path/to/app.beam --json

CLI 会相对于调用者的工作目录解析相对路径。MCP 要求提供绝对文件系统路径，并保留该精确选择：

{
  "name": "inspect_erlang_beam",
  "arguments": { "path": "/artifacts/app.beam" }
}

观察结果¶

内联 Evidence 结果包含工件路径、SHA-256 和字节长度。chunks 列出每个 IFF chunk 名称、文件范围以及负载的 SHA-256。重复的名称会保留各自独立的 chunk 出现项。解码后的表和 Code 头部使用每个名称的最后一次出现，这与 OTP 的加载器一致；chunk 清单仍会列出更早的负载及其来源范围。BEAM 的 form 大小限定了所解析的 chunk 范围。声明 form 之后的字节会被解析器忽略，但仍计入所选工件的字节长度和 SHA-256。

当所选 AtU8 或 Atom 表被解码时，atoms 是从 1 开始的名称表，module 是 atom 1。OTP 28 之前的表以及 OTP 28+ 的紧凑表（取负的计数、紧凑编码的名称长度）都会被读取。当表存在时，exports、imports 和 lambdas 会将 atom 索引解析为对应名称；无法解析的索引会保持 function 或 module 为 null。

code 报告 Code chunk 的指令集、最大操作码、标签数量、函数数量以及指令流的文件范围。缺失的可选表为 null，而不会处处为空。

零字节的 AtU8 会回退到可用的旧版 Atom 表，遵循 OTP 20.3 的 atom 选择。非空的 AtU8 保持 UTF-8 优先，包括显式的零 atom 计数；格式错误的非空数据会失败，而不会回退。没有备用表时，空的 atom chunk 仍会因其必需的计数头部而失败。缺失的以及零字节的可选 FunT chunk 会产生 lambdas: null，而四字节零行数则产生 lambdas: []。这遵循 OTP 29 的正尺寸 lambda 解析规则。空负载在 chunk 清单中保留其范围和 SHA-256。这些规则适用于每个 chunk 名称的最后一次出现；空的最后出现不会复活该名称更早的负载。非空的截断表仍属于格式失败。

选取需要保留的事实¶

默认仍为完整输出。如需在首次调用中读取少量事实，同时保留完整的检查结果，可使用 beam 视图请求摘要：

{
  "name": "inspect_erlang_beam",
  "arguments": {
    "path": "/artifacts/app.beam",
    "detail": "summary",
    "view": {
      "kind": "beam",
      "collection": "exports",
      "names": ["module_info"],
      "fields": ["function_index", "function", "arity", "label"],
      "limit": 20
    }
  }
}

normalized_result.page.items 包含匹配的行。source_index 在原始集合中从 0 开始，并限定在 parent_evidence_id 与该集合范围内。它不会取代原始的从 1 开始的 atom index，也不会取代 lambda 自身的 index。每个匹配的函数名都会被保留，包括不同的 arity。名称是精确保留的显示字符串；当名称无法解析或显示名称发生冲突时，原始索引仍然可用。

集合包括 atoms、exports、imports、lambdas 和 chunks。names 选择 atom/chunk 名称或函数名；imports 还额外支持精确匹配的 modules。过滤器之间取交集。indices 选择原始集合索引；fields 选择该集合自身的字段。空的选择器数组不匹配任何内容，fields: [] 只返回 source_index。Offset/limit 按原始顺序对匹配行进行分页（默认为 0/64）。未过滤的分页是对已保留集合的切片；查询不会重新解码文件。

对于 chunks，names 匹配四个字符的 IFF chunk 标签（例如 "AtU8"、"Code"、"ExpT"）；可用的 fields 为 index、name、location 和 payload。对于 lambdas，names 匹配从 atom 表解析出的函数名；null 名称（未解析的 atom 索引）永远不会被名称过滤器选中。对于 atoms，names 匹配解码后的 atom 名称字符串。

beam 保留模块、form/Code 边界、原始源码覆盖范围以及表计数。null 计数表示没有解码出任何表；0 表示解码出一个空表。缺失的表和未解析的 atom 名称仍然明确显示，空页并不能证明运行时不存在。分页覆盖范围与源码中已检查的 chunk 及解析器预算相互独立。

CLI 的摘要交付需要一个用于存放完整 Evidence 包的目的地：

rea inspect-erlang-beam /artifacts/app.beam --detail summary \
  --view '{"kind":"beam","collection":"exports","names":["module_info"],"fields":["function","arity"]}' \
  --evidence_output /reports/app-beam.evidence.json --json
rea inspect-analysis-view '{"source":{"kind":"evidence-file","path":"/reports/app-beam.evidence.json"},"view":{"kind":"beam","collection":"imports","modules":["erlang"]}}' --json

该包保留完整报告。后续 MCP 查询可以使用 source: {kind: "retained-evidence", evidence_id: parent_evidence_id} 或 Evidence 文件。删除原始 BEAM 文件后，保留视图和离线视图仍然有效。提供 view 时必须同时设置 detail: "summary"；省略 view 则只返回结构摘要。选择只改变交付方式，不改变解析或覆盖范围，也不会执行任何字节码。

限制与失败¶

所选文件默认限制为 64 MiB（最大 512 MiB）。默认最多检查 64 个 chunk 和 4096 个 atom，export、import 和 lambda 行合计最多 65536 行。格式错误的 FOR1/BEAM 头部、被截断的 chunk，以及不是有效 UTF-8 的 AtU8 名称，都会失败且不会返回部分成功的结果。

该工作流不会执行字节码、解压 LitT 字面量，或解码 Attr/CInf 外部术语载荷。完整覆盖描述的是此静态块和表报告；它并不表明 Erlang 运行时能够加载或执行该模块。