捕获的网站源代码位置¶

trace_web_source_location 将 export_web_scripts 保留的脚本中的一个选定位置，通过一张显式配对的本地 source map 进行映射。共享的 CLI/MCP 工作流会验证实际的 manifest、脚本和 map 字节身份，并返回原始位置及内联的嵌入源代码。它不获取浏览器、不抓取任何 URL，也不执行任何应用代码。

rea trace-web-source-location \
  /analysis/scripts/manifest.json 0 \
  /analysis/app.js.map 'https://example.test/maps/app.js.map?v=7#context' \
  1 25 --json

六个位置参数分别选择：manifest、从零开始的脚本索引、绝对 map 路径、绝对 map URL 上下文、从一开始的生成行号以及从零开始的 UTF-16 列。MCP 参数如下：

{
  "manifest_path": "/analysis/scripts/manifest.json",
  "script_index": 0,
  "source_map": {
    "path": "/analysis/app.js.map",
    "url": "https://example.test/maps/app.js.map?v=7#context"
  },
  "generated_position": { "line": 1, "column": 25 }
}

该 URL 使用 ECMA-426 URL 解析规则为解析 sources 和 sourceRoot 提供上下文；它不是抓取指令。重复的路径分隔符仍是解析后 URL 身份的一部分。非 null 的 sourceRoot 会作为每个 source 的前缀，仅当根不以 / 结尾时才添加 /。因此，空根会添加 / 前缀；null 或省略的根不添加前缀。也可以选择绝对虚拟或文件上下文。map/脚本关联由调用方选择：声明或本地 map 并不能证明部署的真实性或执行情况。请使用 import tracing 检查向外的原生模块边。

证据的含义¶

查找会跨行遵循小于或等于所选位置的最大生成位置，并返回该位置处的所有分段。它包含仅生成的映射。这遵循 ECMA-426 GetOriginalPositions，在 REA 的公开契约中使用从一开始的行号。单个点结果并不建立对源代码范围的覆盖、执行或 UI 因果关系。

映射条目保留原始 source 名称/根、节路径、节内 source 索引和展平后的索引。重复的 URL 仍保持独立，包括具有不同嵌入内容的条目。缺失的 source 名称保留 null 解析 URL。位于嵌入文本之外的原始坐标保留报告的坐标和 null 偏移。

嵌入内容哈希标识解码后的 sourcesContent 字符串的 UTF-8 编码，包括其行尾。它们不标识独立捕获的原始文件。原始 map 文本保留在 Evidence 的 raw_result 中，包括未知扩展名；这些扩展名不会被解释。捕获上下文和源 Evidence 链接与经过独立验证的所选文件身份一起提供。

适配器与资源边界¶

该适配器使用锁定的上游 @jridgewell/trace-mapping 0.3.31，且不修改其代码。它会在分配之前验证 map/VLQ 结构，在上游展平之前规范化嵌套的索引偏移，检查节边界和索引，并保留原始声明身份。它支持常规 map 和内联索引节。根 map 和每个嵌入 map（包括索引祖先）都必须具有数字 version: 3。无效的嵌入头会报告其节路径，并且不能产生后代映射事实。这使用了 ECMA-426 允许的版本错误拒绝选项。当较早的节不贡献任何映射时，允许相等的节起始位置；实际解码的映射必须保持在下一节边界之前。外部节 URL 返回可操作的 unsupported-profile 错误。这是一个已定义的解码器配置，而不是声称实现当前每种 source-map 扩展。

一个受管的 Node 子进程解码该 map。其私有请求目录在返回成功之前会被移除。只有该子进程继承的 NODE_OPTIONS 会被移除；显式 V8 标志会设置 192 MiB 旧生代预算、8 MiB 半空间预算、一个 V8 worker；decode_timeout_ms 默认值为 20000。编解码器堆、map 预算和回复预算没有运行时覆盖机制。会检查所报告的实际 V8 堆限制。这些是堆限制，不是聚合的进程 RSS 限制。当 REA 在 Bun 上运行时，子进程也是 Bun，它会忽略这些 V8 标志：runtime 记录 id: "bun"、Bun 版本、其 Node.js 兼容版本，以及 null 的 v8_heap_limit_bytes。在 Windows 上，编解码器所属的 Job Object 会将其提交内存限制为 704 MiB，即 192 MiB 预算加上为 Bun 自身预留的 512 MiB；process_memory_limit_bytes 记录该限制，限制信息中会说明该限制，达到该限制时返回带有 codec_process_memory_limit_bytes 的 resource_constraint。在其他平台上，Bun 没有强制性的编解码器限制：process_memory_limit_bytes 为 null，限制信息中说明未建立编解码器堆限制。清理可能会延长截止时间；未确认的清理会以 cleanup_incomplete 以及所属操作/资源覆盖成功结果。

解码器在移除私有请求目录之前先释放其拥有的编解码器进程。清理失败只报告仍处于待处理状态的所有者：当进程释放未确认时，是进程运行令牌；在目录移除成功之前，是目录。稍后成功的重试会了结绑定到该命令的每个错误；历史失败诊断仍然可用。

完整证据受以下限制约束：4 MiB map、32 MiB 编解码器回复、262144 个解码行/段，以及 64 层嵌套节。这些结构性预算和 192 MiB 编解码器堆没有运行时覆盖机制。超出预算会返回明确的失败，且不包含部分结果。现有的 32 MiB manifest 和 16 MiB 所选脚本边界同样适用。不会修改任何全局工具链或浏览器配置。

验证¶

浏览器 bundle 采集对嵌套内联映射使用绝对节偏移。仅当嵌套节起始于其外层节的第一个生成行时，外层列偏移才会被计入。当嵌套节以间隙开始或没有子叶节点时，父边界仍会裁剪先前的浏览器映射。原始映射文本、原始源标识和专用解码器配置均被保留。

浏览器采集对每次检查最多接受 64 MiB 的映射响应，并在上游扁平化之前，针对 262144 条记录的解码预算预检索引节、源、名称、生成行和映射段。索引映射限制为 64 层嵌套。这些结构限制约束解码对象的增长，同时在响应字节预算内保留大型内嵌 sourcesContent 字符串。它还将整个检查过程中展开的内联证据限制为 32 MiB，在发布之前检查已解析的源标识和映射行，并在上游物化其数组之前将原始已解析源标识限制为 64 MiB。超出任一解码器预算将返回 fetch_failed 条目，同时保留其他映射。每个映射都会验证解码坐标和源/名称索引；格式错误的映射将报告为 invalid，而不会丢弃之前或之后的映射。

采集在获取每个请求的映射之前，为其保留失败上下文。当聚合内联结果预算无法再预留条目时，其余请求将保持未处理状态，并通过顶层 limitation 报告为未知；requested 保留完整计数，processed 计算返回的条目数。格式错误的 UTF-8 映射响应将报告为无效，而不会使用替换字符进行修复。

针对性测试涵盖重复映射、索引偏移/重叠/本地索引、32 位 VLQ 溢出、可空内容、UTF-16/CRLF 位置、不可变工件标识、取消、延迟输出关闭、清理失败、SDK 模式以及公开 CLI 行为。实际编解码过程会在测试主机上运行。

可选的 verify:browser:source-maps 通道使用隔离的 esbuild 0.25.10 编译源代码自带的 TypeScript 测试夹具，将其提供给真实 Chromium，捕获并导出实际响应，然后通过 CLI 和 stdio MCP 检查原始编译器位置和精确保留的内容。它可以针对已安装的包。只有此通道需要 Chromium 和测试夹具编译器。Linux x64 是专用 CI 任务覆盖的真实工作流；其他主机工作流仍未验证。