Reversa: A Reverse Documentation Engineering Framework for Converting Legacy Software into Operational Specifications for AI Agents

想象一下，你拥有一座古老、布满灰尘的图书馆，里面藏有数千本手写书籍。这些书籍包含了运营银行的规则，但它们是用一种无人再使用的语言（如 COBOL）写成的，墨水正在褪色，而且没有目录或索引。原作者早已离世，唯一能读懂这些书籍的只有几位即将退休的年迈图书管理员。

现在，想象你想雇佣一支由超级聪明、速度极快的机器人（AI 智能体）组成的团队，将这些规则重写为现代语言（如 Go），以便银行能在新的计算机上运行。问题在于？如果你只是告诉机器人“去修复这个”，它们可能会猜错。它们可能认为某条规则意味着 A，而实际上它意味着 B，从而导致银行系统崩溃。

本文介绍了 Reversa，这是一个旨在解决这一确切问题的新框架。请将 Reversa 想象成并非一根能瞬间翻译代码的魔法棒，而是一个专门的“反向文档”工厂。

以下是其工作原理，使用简单的类比：

1. 问题： “沉默”的遗留系统

旧的软件系统就像一栋房主 20 年前离开的房子。灯还亮着，冰箱还在嗡嗡作响，但没人知道为什么厨房的灯会连接到前门，或者如果在洗衣机运行时打开烤箱会发生什么。规则隐藏在墙壁（代码）内部。如果你在不了解这些隐藏规则的情况下试图翻新，可能会意外切断整个街区的电力。

2. 解决方案：一支专门的机器人侦探团队

与其让一个机器人阅读整栋房子并猜测规则，Reversa 会派遣一支专门的智能体团队，每个智能体都有特定的工作，就像生产线一样：

• 侦察兵： 首先环顾房子。“好的，这里有 5 个房间、一个地下室，以及厨房里的一扇怪门。”（映射项目表面）。
• 考古学家： 挖掘墙壁。“我在这里发现了一张蓝图，显示这根管道连接到那个阀门。”（分析模块）。
• 侦探： 寻找线索。“为什么灯会连接到门？啊，笔记上说这是一个安全功能。”（提取隐藏的业务规则）。
• 建筑师： 根据发现绘制新地图。“所以，厨房是房子的核心，地下室存放着水。”（综合架构）。
• 撰写者： 清晰地写下规则。“规则 #1：如果门打开，灯就会亮起。”（编写规范）。
• 审查员： 这是最重要的角色。他们检查撰写者的工作。“等等，我们找到关于灯的笔记了吗？没有？那么我们就不能确定。让我们将其标记为'可能'或'需要人类检查'。”（审查置信度和缺口）。

3. 秘诀：“置信度”与“缺口”

大多数 AI 工具即使是在猜测时，也试图表现得 100% 确定。Reversa 则不同。它对发现的每一条规则都使用交通信号灯系统：

• 🟢 绿色（已确认）： 我们在代码中找到了这一点。这是事实。
• 🟡 黄色（推断）： 我们没有找到直接的笔记，但模式表明如此。这是一个聪明的猜测，但需谨慎。
• 🔴 红色（缺口）： 我们一无所知。代码缺少此信息。停止！ 需要人类来到这里告诉我们该怎么做。

这至关重要。它防止机器人自信地犯错。它告诉人类：“我们已知晓 97% 的规则，但这里有 3% 需要你们的帮助。”

4. 结果：机器人的“契约”

输出不仅仅是供人类阅读的枯燥手册。它是 AI 智能体的操作契约。它表明：

• “这是系统所做的事情。”
• “这是证据（我们在旧代码的哪个文件中找到了它）。”
• “这是我们目前还不知道的内容。”

这使得 AI 智能体能够安全地重写旧系统（从 COBOL 迁移到 Go），因为它们拥有清晰的地图，并且确切知道“战争迷雾”在哪里。

5. 现实世界测试：ATM 机

作者在真实（但简单）的项目上测试了这一点：一台用 COBOL 编写、需要重建为 Go 的旧 ATM 机。

• 过程： 他们运行了 Reversa 流程。
• 输出： 系统生成了 517 个“主张”（规则）。其中 490 个被标记为事实，24 个被标记为猜测，并发现了 3 个缺失部分（缺口）。
• 人类角色： 人类介入解决缺失部分和“猜测”。
• 结果： 他们制定了重建 ATM 的计划，并编写了 53 个测试场景（例如“如果我存入 20 美元，我应该取回 20 美元”）。他们成功启动了重建工作，完成了 11 项主要任务中的 9 项。

本文未声称的内容

了解本文未说明的内容很重要：

• 它不声称这是完美的，或者它目前适用于世界上每一个旧系统。
• 它不声称机器人可以在没有人类的情况下完成全部工作。人类仍然需要解决“红色”缺口。
• 它不声称这目前比用旧方法做更快或更便宜。他们仅证明了这是可行的，并且它创造了一个更安全、更有条理的过程。

总结

Reversa 是一个将旧软件视为犯罪现场的框架。它利用 AI 侦探团队仔细描绘系统所做的事情，明确标记它们确信的内容和猜测的内容。这创建了一份安全的“操作手册”，允许新的 AI 机器人在不破坏旧系统的情况下更新或重写它们，同时将人类保留在循环中，以解决机器人无法弄清的谜团。