REA：让 AI Agent 拥有二进制级逆向能力的
统一 MCP 操作系统

Evidence 溯源即一等公民

每条结论都是内容寻址（SHA-256）、防篡改、不可变封存的证据记录，显式区分 observed / derived / inferred 三级置信度与五种权威来源，并把「未知」当作需要被登记和追踪的一等数据，从数据模型层面抑制 Agent 幻觉。

24+ 目标类型 × 十余个引擎

原生二进制、JS/Electron、.NET、WASM、EVM、Go/Rust、Flutter、Android、固件、网站、抓包、SQLite、逻辑信号……通过 Hopper/Ghidra/IDA/Kuna/JADX/Frida/GDB 等适配器统一供给，CLI 与 MCP 共享同一套工作流。

Agent 工具链的「逆向插件」

一条 npx rea-agents setup 即可注册到 Claude Code、Codex、Cursor、Gemini、Grok 等 21 种 AI 编程客户端，并下发配套工作流技能。它卡位的是「Agent 看懂闭源软件」这一新兴刚需。

工作方式

Agent 通过 MCP 提出分析师问题（如「Notes 应用的搜索是怎么实现的」），REA 选择并驱动本地引擎、追踪相关代码，返回带证据的伪代码 / 汇编 / 模块图 / 调用关系；Agent 据此追问、解释、再实现与测试。所有分析在本地运行，不上传目标文件。

双形态：一个内核，两个入口

• MCP 服务器（长驻）：基于 stdio，src/main.ts 启动，持有一个不可变的二进制会话（BinarySession），v6.5.0 运行时向 Agent 暴露 207 个工具（经 mcp doctor 内容摘要核验）。
• CLI（一次性）：src/cli.ts 驱动，提供 153 个命令，可脚本化、可导出证据包。
• 共享工作流：两个适配器复用同一套 application 层与 Evidence 契约，不存在「两套逻辑」。
• 分发：npm 包 rea-agents，bin 为 rea / rea-agents，另有 install.sh 与 skills.sh 技能。

月度提交节奏：10 月的爆发

最近 2000 条提交的类型分布

会话路由：一个目标，一个不可变绑定

• BinarySession：每个分析目标建立一次「深度绑定」（deep binding），选定唯一深度引擎，生命周期内不可变。
• 确定性选择：AnalysisProviderRegistry 对候选排序，明确指定或唯一候选才绑定；多个候选同时可用时返回 ambiguous，绝不静默 fallback。
• 辅助路由分离：轻量能力（清单、格式读取）与深度引擎走 disjoint routing，避免误用。

桥接器：在宿主进程内说引擎的语言

内容寻址 + 身份自洽

证据 ID = 对其全部语义内容（含 raw_result、provider、置信度、局限）做规范化 SHA-256。解析时重算哈希，任何对已认证记录的篡改都会被立即拒绝。规范化哈希与显示路径解耦，换路径不破坏证据身份。

深度冻结 + WeakMap 封存

证据入库时 Object.freeze 递归冻结并记入 WeakMap；「已认证不可变」成为可识别的运行时事实，跨进程传递时用哈希而非引用判断一致性。

置信度 × 权威度

「观察到」与「推导」与「推断」严格分层；「来自出厂制品」与「分析师推断」权威不同。Agent 无法把一句猜测包装成与实测同等可信的结论。

残余未知（Residual Unknown）与证据账本

EvidenceLedger 是会话级的不可变证据集合，幂等记录、冲突内容拒绝、整个证据包（bundle）先校验再原子合并。与此同时，无法确定的事实以 ResidualUnknown 记录，带状态机与修订历史（提出 / 证据补全 / 关闭）。

工具契约反复强调一条原则：「缺失的覆盖度是 unknown，不是 absence」——没扫到某个调用方，不等于调用方不存在；空的 facet 必须由生产者显式声明「已观察到为空」才可用于等价性比较。

这套机制如何改变 Agent 行为

• 结论必须可追溯：比较类工具（compare_functions / compare_artifacts）直接吃 Evidence，只有覆盖度可比、图成员完整才允许判定「相同」。
• 静态 ≠ 运行时：制品静态一致也明确「不能证明运行时行为不变」。
• 部分失败可恢复：分析或清理失败时，已完成的证据与部分观察仍然保留，不丢结论。
• 溯源闭环：investigate_feature / trace_* 产出证据图，配合 verify_reconstruction 校验重构覆盖率。

所有权令牌：防 PID 复用误杀

逆向引擎要派生大量子进程，清理时必须能安全地终止自己派生的进程组。仅凭 PID + 可执行路径在进程退出 / PID 被复用后不足以证明所有权。REA 引入 Run Token（运行令牌）：启动子进程前注入令牌，清理时扫描全表验证令牌、启动者身份、父 PID、进程组，只有令牌证明通过才发信号。「观察到的候选」不自动授权 kill。

私有运行根 + 有界资源

每个提供者运行在私有 runtime root（POSIX 临时目录 / Windows 私有 NTFS），Ghidra 用临时项目 + 私有 home/cache，会话结束即删。所有外部进程有启动截止时间、消息大小上限、CPU/内存上限、有界文件读取（Linux prlimit、Windows Job Object），防止恶意 / 畸形文件拖垮宿主。

Result 错误代数 + fail-closed

边界值用 {ok,value}|{ok:false,error} 显式建模，无法识别的身份/适用性必须保持 unknown，而不是当成「缺失 / 外来 / 已对齐」。能力集成遵循 fail-closed：只要作用域、授权、副作用、验证方式存在未决问题，就拒绝接入。Zod 严格契约（strictObject）拒绝任何未声明字段。

性能优先级：先省 Agent 的 Token

AGENTS.md 把优化顺序写得很明确：① Agent token 与上下文（返回最小充分答案，用任务选择 / 摘要 / 分页 / 留存 Evidence）；② 分析时间（复用已验证结果、缓存键覆盖所有影响因素、上报前校验新鲜度）；③ CPU 与内存。这与传统工具优先考虑「跑得快」截然不同——它优化的是整个 LLM 任务的总成本。

工具设计：从分析师问题出发的动词体系

207 个工具（v6.5.0 运行时目录，见第 11 节实测）按 inspect / list·search / trace / compare / workflow / observe·capture 六类形态组织，不堆无关执行模式。源码动词分布印证了这一取向：inspect 35 个、list 13、compare 11、trace 8、project 7，生命周期 start/close 成对出现。命名保持 provider 中立，能力差异通过「每个 provider 的实际覆盖度」精确回报。

通道与传输安全

• 每会话随机能力令牌认证 Hopper / Ghidra 桥接，令牌通过私有会话描述符传递，不走命令行参数或环境变量。
• POSIX 用当前用户 Unix domain socket；Windows Ghidra 用认证过的 loopback TCP + 私有 NTFS 运行时，DACL 仅放行当前用户与 SYSTEM。
• Ghidra 用打包的 HeadlessScript、隔离临时项目、私有 home/cache，只导入目标、限制消息与资源，关闭即删。

安装与供应链安全

• 配置变更必须幂等、可加、带备份，setup 先展示计划、获批后才写入。
• Hopper 安装仅信任其 HTTPS 端点、限定下载源、限制包大小、比对官方校验和；依赖安装直接调 apt/dnf/pacman，无 shell 求值、从不 sudo。
• 绝不安装 / 升级无关软件（Homebrew、Node、Java、Ghidra 等）；商业引擎一律 BYO。
• install.sh 内置截断保护：curl|bash 下载不完整时直接语法报错，绝不执行半截脚本。

多层测试金字塔

合计 7,259 个 it/test 用例；另有 Python/Java/Swift 桥接器的契约测试。

真实引擎验证 lane（CI）

30 个 GitHub Actions 工作流中，有一整套 real-* 任务在真实工具链上跑：real-ghidra（含 Windows）、real-hopper（macOS/Linux）、real-cutter、real-browser、real-go-binary、real-evm、real-packet-capture、real-signal、real-javascript-recovery、real-termux（Android） 等。

Changelog 中每条能力都标注「已在哪个平台 / 哪个版本验证」「哪些仍未验证」，例如 Frida 仅记录了 Linux 本地标记工作流，macOS/Windows/远程均标注未验证。模拟提供者不被承认为真实行为证据。

TypeScript 拉满

strict + exactOptionalPropertyTypes + noUncheckedIndexedAccess + noImplicitReturns + verbatimModuleSyntax，配合 oxlint 限制圈复杂度（≤20）、嵌套深度（≤4）、函数行数（≤100）、参数数（≤4）。

变异测试

用 Stryker 对 reverse-tools 做变异测试（perTest 覆盖分析、TS checker），不仅验证「测试能过」，还验证「测试是否真能抓住缺陷」。

其他质量门

knip 死代码检测、jscpd 重复代码检测、JSON Schema 方言校验、架构守卫、元数据校验、PR readiness 人工归属、PR 标题 Conventional Commits、Turborepo 增量编排。

测试代码 vs 生产代码

多语言桥接代码（含宿主进程内脚本）

Agent 客户端覆盖

setup 自动注册并下发配套工作流技能（含备份与 dry-run）：

未列出的客户端可用手动 stdio MCP 注册；同一份能力也可纯 CLI 使用，不依赖任何 Agent。

社区与分发数据

• GitHub：256,763 stars / 64,533 forks / 932 open issues（截至 2026-10-15）。
• npm：rea-agents 周下载约 23.2 万；32 次发布。
• 贡献者：git 统计约 230 人（GitHub API 219 页），核心维护者 morluto 主导（1638 提交），另有 Kaoru0822、N0zoM1z0、Ysopwnable 等高频贡献者。
• 治理：5 类 issue 模板、PR 模板、Trendshift 徽章、Discord 社区、官网 rea.tools（含指南与三个标杆案例）。

Node 版本是硬门槛

需要 Node 22.19+ / 24.11+ / 26+ 与 npm。无需 clone 仓库、无需编译。本机 v22.23.2 通过

分析引擎分层供给

静态 JS/Electron、.NET、Go/Rust 元数据、SQLite 零引擎即可跑；原生二进制反汇编才需自备 Hopper / Ghidra / IDA / Kuna。setup 不会代装这些引擎。

目标不上传，首次需联网

所有分析在本地进行，目标字节不出机器。仅 npx 首次拉包与 setup 联网；Linux 上部分能力需 procps 兼容的 ps。

更新与卸载

• npx 用户：始终用 @latest 即最新；重跑 setup 可刷新已注册版本与技能。
• 全局用户：用 rea update 更新。
• 卸载：setup 提供卸载流程，会保留无法安全删除的文件并报告归属清单；首个 .rea.backup 备份不被覆盖。

常用环境变量

• REA_ANALYSIS_PROVIDER：常驻 provider 偏好（被 --provider 覆盖）。
• REA_GHIDRA_STARTUP_TIMEOUT_MS / REA_HOPPER_STARTUP_TIMEOUT_MS：大二进制导入慢时调大启动超时。
• REA_KUNA_COMMAND、REA_JADX_MCP_JAR：指定 Kuna 可执行文件 / jadx-headless-mcp 的 JAR。
• REA_MCP_MAX_RESPONSE_BYTES、NO_COLOR=1、--accessible：限响应体、关色、无障碍提示。