跳转至

JavaScript 源代码恢复

recover_javascript_sources / recover-javascript-sources 从显式选择的 UTF-8 JavaScript 文件或包中推导出可读模块。可将它用于 export_web_scripts 或其他本地脚本返回的文件。该操作从不执行所选或恢复的应用程序代码。

调用方提供的引擎

REA 在 Linux x64 上接受 Wakaru ^1.13.0。报告解析器已针对 Wakaru 1.14.0 验证。该范围内的其他版本也会被接受，观测到的版本会被报告，并记录一条限制：解析器尚未针对该版本进行验证。Wakaru 在一个主版本内只会通过新增方式更改 --version、--json 和 provenance.json（兼容性策略），因此解析器会保留未知的报告字段和已报告的模块状态。

将 REA_WAKARU_COMMAND 设置为调用方提供的可执行文件的绝对路径。适配器使用 util-linux 的 prlimit（默认为 /usr/bin/prlimit；可通过绝对路径的 REA_JAVASCRIPT_PRLIMIT_COMMAND 覆盖）。REA 不会安装这两个工具。仅当请求恢复时才会检查引擎配置；没有它，REA 的其他功能仍然可用。

未修改的上游源代码保留在 third_party/wakaru 中，固定到 8219bf5016a063d7fb215101a8c45d5959ec733f（v1.14.0，Apache-2.0）。结果报告所执行二进制的确切路径、SHA-256 和观测到的版本。经审计的源代码修订版不同于 executed_source_revision: null：版本字符串无法证明调用方提供的二进制文件是由哪个源代码生成的。

安装 Wakaru

使用官方发布二进制文件，也就是 CI 验证的那个：

curl -fL https://github.com/pionxzh/wakaru/releases/download/v1.14.0/wakaru-linux-x64.tar.gz | tar -xz wakaru
export REA_WAKARU_COMMAND="$PWD/wakaru"

或者通过 npm 安装。请指向平台二进制文件，而不是 node_modules/.bin 中的 Node.js 垫片：

npm install wakaru@1.14.0
export REA_WAKARU_COMMAND="$(realpath node_modules/@wakaru/cli-linux-x64/wakaru)"

两种方式得到的二进制文件相同（SHA-256 664fa06782a61eda7ed15885134b52525fd565dd77607e642062ceb6cd927c38）。

恢复与分析

rea recover-javascript-sources /tmp/web-scripts/app.js /tmp/recovered-app --json
rea analyze-javascript-application /tmp/recovered-app/modules --json

# Recover related code-split chunks together; repeat --additional-path.
rea recover-javascript-sources /tmp/web-scripts/main.js /tmp/recovered-chunks \
  --additional-path /tmp/web-scripts/runtime.js \
  --additional-path /tmp/web-scripts/shared.js \
  --additional-path /tmp/web-scripts/checkout.chunk.js --json

MCP 输入：

{
  "path": "/tmp/web-scripts/main.js",
  "additional_paths": [
    "/tmp/web-scripts/runtime.js",
    "/tmp/web-scripts/shared.js",
    "/tmp/web-scripts/checkout.chunk.js"
  ],
  "output_directory": "/tmp/recovered-chunks"
}

输出目录必须不存在、为绝对路径，并且其父目录必须已存在。每个源都在私有工作区中单独快照。多个输入保留其相对目录布局，并一起传给一次 Wakaru 调用，从而让跨块模块 ID 能够解析。输入必须互不相同；additional_paths 最多接受 16 个附加文件。引擎只写入自己的暂存目录。被报告的模块路径、输入身份、UTF-8 字节范围、常规文件和生成的地图表示会在发布前得到验证。REA 将验证过的字节写入独占的输出树，并在失败时回滚。它还会在提交前检查原始源代码和引擎字节是否保持不变。现有输出永远不会被覆盖。

被拒绝的所选输入读取会报告 access_denied，并带有观测到的 OS 代码和路径。源代码或引擎身份变更会报告 artifact_changed；这两种失败都不是格式错误的恢复请求。取消操作会在准入、命令启动和完成过程中保留调用方的原因。

多输入相对文件名必须能够原样表示为产物路径：使用 NFC Unicode 拼写，且不含字面反斜杠。不支持的布局会在调用引擎之前失败，而不是静默重命名被源映射引用的输入。

发布的内容：

  • inputs/bundle.js：单个输入的确切原始快照。多个输入在 inputs/ 下保留相对于其共同父目录的路径。
  • modules/：推导出的模块以及任何上游生成的源映射。
  • reports/stdout.json 和 reports/provenance.json：确切的生产者报告。
  • manifest.json：身份、模块、转换选择、警告和限制。

内联结果包含完整的文件路径/摘要/大小、提取范围、警告和 analysis_input，可直接用作 analyze_javascript_application 的参数。source 标识主输入并绑定 Evidence 主题；additional_sources 在其他快照被选中时记录这些快照及其已发布的副本。每个模块都会指明其所属快照、原始路径和原始摘要；所有提取和上下文范围都指向该输入。原始 Evidence 保留选中的命令行参数、被报告的输入路径、退出状态、stderr 和报告；临时路径在其工作区被移除后记录为历史执行坐标。

转换选择与解读

extraction_mode 默认为 structural（Wakaru --unpack=strict）。heuristic 使用 --unpack=auto；inspection 使用 --unpack=inspect，并可以返回更细粒度的、不可执行的区域。rewrite_level 接受 minimal、standard（默认）和 aggressive。每次操作都会请求源映射和 provenance。

结构化提取可以回退为单个文件。在真实测试样本中，webpack 5 产生两个模块；esbuild 作用域提升的样本仍然是单个未知格式的脚本。返回的模块数量和检测到的格式会报告这些实际结果。报告有效但转换失败时，返回 partial，并带有原始警告和文件。不可用的报告、不一致的 provenance、越界路径、符号链接或缺失模块都会导致错误，并执行相应的清理。

证据置信度为 derived。提取范围是原始快照中半开的 UTF-8 字节偏移，而非改写后的行位置或覆盖断言。源映射得以保留，但并不声称其映射精度已获独立验证。原始变量名以及任意运行时等价性仍然未知。不会进行任何网络获取。

资源策略与验证

每次操作使用一个工作进程、1 GiB 地址空间上限和 120000 毫秒截止时间。该截止时间没有运行时覆盖机制：提高 analysis_timeout_ms 或 max_heap_mb 并不会提高它。未更改的重试可能会再次触及该截止时间。该操作在所有选定文件中最多接受 64 MiB 的总输入，以及 128 MiB/10000 条暂存输出，诊断/报告流各为 8 MiB。超过该报告配额的 provenance.json 会指明固定限制：此版本没有运行时覆盖机制，提高 max_heap_mb 或 analysis_timeout_ms 并不会提高它。格式错误的报告与因大小超限而拒绝是两种不同的情况。超过限制属于显式失败并附带回滚。超出总输入配额的已选输入会返回不可重试的 resource_constraint，其中包含 resource: "file-size" 以及 reported_limits.maximum_input_bytes/remaining_input_bytes；不是有效 UTF-8 的输入则属于 invalid_format 请求问题。这些限制按操作适用，并不声称对并发调用者进行聚合主机资源约束。

针对真实 Wakaru CLI/MCP 的专项测试通道及其源码自带的编译器测试夹具，请参阅 testing.md。其他宿主平台以及 Bun/Vue 的恢复不在本适配器的声称范围内。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 rea2/rea