技术摘要：RustPrint——基于文档引导的代理式 C 到 Rust 代码库迁移

问题陈述

将遗留 C 语言代码库迁移至 Rust 对于解决 C 语言指针模型固有的内存安全漏洞至关重要，但这仍然是一项重大的工程挑战。现有的翻译工具（例如 C2Rust）通常在文件或函数级别进行操作，保留了 C 风格的结构，导致大量使用 unsafe 块，或者未能捕捉原始系统的架构意图、数据流和设计原理。此外，当前基于大语言模型（LLM）的方法在处理仓库级任务时往往力不从心，由于缺乏跨模块的整体理解和协调，无法为大型代码库（11K–84K 行代码）生成可编译的输出。核心问题在于，迁移本质上是一项代码库理解任务，需要建立关于共享数据结构、模块边界和跨文件不变性的心理模型，而孤立的翻译策略无法恢复这些模型。

方法论：RustPrint 框架

RustPrint 是一个专为仓库级 C 到 Rust 迁移设计的多代理框架。它引入了一种文档驱动范式，其中自动生成的文档作为中间表示（IR），用于指导规划、翻译和细化。该框架通过一个五阶段流水线运行：

1. 文档引导的代码翻译

RustPrint 并非逐单元翻译代码，而是首先使用专用的 DocGen 模块生成源 C 代码库的整体文档。

• 流程：源仓库在文件级别进行聚类，然后提升为更高层级的组件抽象。DocGen 模块生成结构化文档（$S_{doc}$），捕捉抽象特性、模块交互和设计原理，而不仅仅是语法描述。
• 代理：
  • Planner（规划器）：将 $S_{doc}$ 转换为 crate 级别的实现计划（IMPLEMENTATION_PLAN.md），解决架构细节并定义组件职责。
  • Translator（翻译器）：实现每个计划的 crate，通过 cargo_check 迭代以确保可编译性，并通过 detect_unsafe 最小化 unsafe 块的使用。
  • Synthesizer（合成器）：执行仓库级别的集成，解决跨 crate 依赖并生成统一的 README.md。

2. 需求驱动的代码细化

为确保语义完整性，RustPrint 采用一种迭代细化机制，将生成的 Rust 代码库的文档（$T_{doc}$）与源文档（$S_{doc}$）进行比较。

• 机制：系统通过文档等价性来近似功能保留：$CodeEquiv(S, T) \approx DocEquiv(S_{doc}, T_{doc})$。
• 代理：RequirementRefiner（需求细化器） 识别 $T_{doc}$ 未能匹配 $S_{doc}$ 的差距（例如，遗漏的功能、不匹配的 API）。它使用 str_replace_editor 编辑翻译后的代码，检查编译情况，并迭代修复缺失或不对齐的功能。

3. 执行感知的代码修订

认识到文档比较无法暴露所有运行时错误，该框架增加了一个测试驱动的反馈循环。

• 流程：源测试套件由 TestTranslator（测试翻译器） 翻译为 Rust。
• 代理：ExecutionRevisor（执行修订器） 使用 cargo_single_test 分析失败的测试。它仅更新翻译后的生产代码（而非测试），以修复那些通过静态对齐但未能通过具体执行的边缘情况、状态更新或协议不匹配等行为不一致问题。

主要贡献

1. 文档驱动的迁移范式：本文提出使用自动生成的代码库文档作为仓库级翻译的中间表示。这种方法在翻译之前编码了整个代码库的理解，使得生成的 Rust 代码能够保留架构意图，而不仅仅是复制语法结构。
2. 文档引导的迭代细化：一种通过比较生成代码的文档与源文档来评估和改进生成的 Rust 代码的机制，系统地识别覆盖差距并促进结构对齐。
3. 执行感知的修订：测试驱动反馈的集成允许系统通过动态测试执行迭代地纠正行为不一致，实现了超越静态翻译保证的功能正确性。
4. 大规模评估：该框架在八个现实世界的 C 语言仓库上进行了评估，代码量从 11K 到 84K 行不等，解决了以往工作仅关注小型基准测试的局限性。

实验结果

评估在八个仓库上使用两个模型骨干进行：一个开源权重模型（Kimi-K2-Instruct）和一个闭源权重模型（GPT-5.4）。基线包括传统工具（C2Rust）和基于 LLM 的代理（Self-Repair、EvoC2Rust 以及代理式 Claude Code 基线）。

• 项目可编译性：RustPrint 在两种模型骨干下均成功编译了所有目标仓库。相比之下，基线 LLM 翻译器（Self-Repair、EvoC2Rust）未能在此规模下生成端到端可编译的仓库。C2Rust 虽然可以编译，但保留了大量的 unsafe 使用。
• 功能保留：通过 CodeWikiBench 分数衡量，RustPrint 显著优于 Claude Code 基线。
  • 使用 Kimi-K2-Instruct：RustPrint 达到 93.26%，而 Claude Code 为 52.52%。
  • 使用 GPT-5.4：RustPrint 达到 97.76%，而 Claude Code 为 48.87%。
• 功能正确性：使用交叉评估协议（使用 Claude Code 的测试测试 RustPrint 的输出，反之亦然），RustPrint 表现出卓越的鲁棒性。
  • Kimi-K2-Instruct：测试通过率（TPR）为 95.17%，而 Claude Code 为 79.85%。
  • GPT-5.4：TPR 为 98.70%，而 Claude Code 为 79.85%。
• 安全性：RustPrint 实现了高安全率，最小化了 unsafe 块的使用。使用 GPT-5.4 时，其 API 级别安全率达到 99.41%，文件级别安全率达到 98.47%，优于其他方法。

意义与主张

本文主张文档引导的协调是可扩展代码库迁移的一个可行且有效的方向。结果表明，将迁移视为跨文件、接口和修复步骤的协调问题，而非原始代码生成任务，对于仓库级成功至关重要。

作者强调：

• 规划与细化比一次性翻译更重要：生成文档、将其与源文档进行比较、并根据执行反馈进行细化的迭代循环，对于处理复杂的跨模块依赖至关重要。
• 文档充当操作指南：它不仅仅是背景上下文，而是驱动缺失需求恢复和结构对齐的功能蓝图。
• 行为正确性是可以实现的：跨套件测试结果表明，这些收益不仅仅是文档层面的；翻译后的仓库保留了实际的运行时行为。

本文结论指出，虽然当前研究代表了在现实仓库上的强有力初步结果，但该途径为未来的改进留下了清晰的路径，例如处理混合语言仓库、更深层的外部依赖以及标准化程度较低的构建系统。作者将 RustPrint 定位为一种实用方法，可将基于 LLM 的翻译从孤立文件扩展到完整的仓库级工程任务。