migrate-to-rust

将旧代码库迁移到安全 Rust

扮演系统架构师、性能工程师和 Rust 专家。你的目标是将旧代码库迁移到 100% 安全、经过 PGO 调优的 Rust，同时通过 scripts/telemetry.py 记录测量遥测数据和第一人称工程叙述。

执行约定与可移植性

迁移代码仓库或本地目录（{github_url} 或 {codebase_path}）时，请在各种 Agent 框架中遵循以下执行规则：

1. 阶段 0 外部代码确认关卡：克隆外部代码仓库并检查其构建文件后，向用户展示已解析的旧版构建命令、运行命令和目标目录，并在编译或执行克隆的代码前取得用户确认。（对于用户明确指示要运行的本地代码，或获得阶段 0 确认后，可直接继续。）
2. 阶段 1 -> 阶段 2 连续推进：阶段 0 基线采集完成后，在主机环境允许自主执行工具的情况下，直接从编写架构蓝图（阶段 1）继续推进到实现并验证 Rust 工作区（阶段 2），期间不要在里程碑之间暂停。
3. 有界自动自愈（最多 5 次迭代）：测试、clippy lint 或 A/B 一致性检查失败时，通过 scripts/telemetry.py 记录失败，诊断并修复根本原因，然后在预算允许的范围内自动重新测试，最多进行 5 次自愈迭代（或每个阶段 15 分钟）。如果预算耗尽后仍有任何测试或种子存在差异，请将部分状态记录到 migration_telemetry.json，并在最终报告中说明剩余差距，而不是无限循环。
4. 验证目标与完成定义：
   • #![forbid(unsafe_code)] Rust crate 编译，目标为 0 条 cargo clippy 警告（任何不可避免的例外都必须记录）。
   • 单元、集成、文档和基于属性（proptest）的测试均通过，目标是达到 >= 95% 的分支覆盖率（任何不可避免的例外都必须记录），并将每次运行记录到 migration_telemetry.json。
   • 在有据可查的数值 epsilon（--max-abs-error）范围内，验证 N 个确定性种子下的 A/B 差分输出一致性，并对任何浮点数/FMA/PRNG 差异查明根本原因并记录。
   • 测量并记录全部 4 个基准测试阶段（legacy_baseline、safe_rust、soa_simd、pgo_lto）（如果 llvm-profdata 等工具不可用，则应妥善省略）。
   • 通过 scripts/telemetry.py render-infographic 渲染交互式 HTML 信息图（migration_infographic.html）。

端到端工作流检查清单

复制此检查清单，以跟踪三个阶段的进度（详细的命令说明和架构规范请参阅 references/pgo_and_telemetry_guide.md）：

- [ ] Stage 0: Acquire repo, initialize `migration_telemetry.json` (`discovery` bucket), scan legacy codebase, confirm resolved build/run commands, and benchmark baseline
- [ ] Stage 1: Audit legacy code (`blueprint` bucket), log opportunities & latent legacy bugs, and generate 6-section Architectural Blueprint
- [ ] Stage 2.1: Scaffold `#![forbid(unsafe_code)]` Rust workspace & deterministic PRNG parity layer (`rewrite` bucket)
- [ ] Stage 2.2: Implement core domain types & SoA/SIMD kernels (<= 400 LOC/file target, full rustdoc) & benchmark `safe_rust` + `soa_simd`
- [ ] Stage 2.3: Run Verification Crucible (`test_heal` bucket, max 5 iterations) — log initial test failure % and each self-healing fix
- [ ] Stage 2.4: Run A/B differential parity harness (`parity` bucket, max 5 iterations) across N seeds within documented epsilon tolerance
- [ ] Stage 2.5: Run LLVM Profile-Guided Optimization (`pgo_bench` bucket), scan final Rust codebase, and render `migration_infographic.html`

---

阶段 0：获取仓库、初始化遥测并建立旧版基线

从仓库或目录中解析上下文参数：

参数	占位符	解析策略
源输入	{codebase_path} 或 {github_url}	接受 GitHub URL（https://github.com/...）或本地文件系统路径
原始语言 / 框架	{legacy_language}	根据文件扩展名和构建文件（CMakeLists.txt、Makefile、meson.build、pyproject.toml、pom.xml、*.f90、*.cpp）自动检测
基线运行命令	{baseline_run_command}	从 README.md、CI 工作流（.github/workflows/*.yml）、Makefile 或测试脚本中识别
遥测台账	{workspace_dir}/migration_telemetry.json	在阶段 0 开始时通过 scripts/telemetry.py init 初始化

阶段 0 执行步骤

1. 克隆仓库（如果是 GitHub URL）：选择一个干净的本地目录 （默认使用 ~/rust_migrations/{repo_name}，或按要求放在当前工作区 内），并运行 git clone {github_url} ~/rust_migrations/{repo_name}。
2. 初始化遥测并扫描旧版代码库：运行 scripts/telemetry.py init --telemetry "{workspace_dir}/migration_telemetry.json" --project-name "{project_name}" --legacy-lang "{legacy_language}"。启动 discovery 计时桶，并对旧版源代码目录运行 scripts/telemetry.py scan-codebase --phase before，记录基线文件数、代码行数、注释密度 %、最大文件行数、嵌套深度、平均函数长度，以及原始指针 / 内存风险。
3. 确认并基准测试旧版基线：在执行克隆的外部仓库中的构建或运行 命令之前，向用户展示已解析的构建命令、{baseline_run_command} 和 工作目录，以供确认。确认后，以发布模式编译旧版项目（-O3 / Release），使用确定性种子捕获黄金参考输出，测量基线墙钟运行时间 （ms）和峰值 RSS（MB），并通过 scripts/telemetry.py log-benchmark --stage legacy_baseline 记录阶段 1。

---

阶段 1：深入审计、发现改进机会并制定架构蓝图

启动 blueprint 计时桶（scripts/telemetry.py start-bucket --bucket blueprint），检查仓库，记录发现的每项改进机会和潜在的旧版漏洞 （scripts/telemetry.py log-opportunity），并生成 references/pgo_and_telemetry_guide.md 第 2 节中定义的 6 部分 Markdown 蓝图。

阶段 1 -> 阶段 2 转换：保存蓝图并直接进入阶段 2 （除非用户明确要求仅制定蓝图）。

---

阶段 2：分阶段安全 Rust 实现、自愈、PGO 和信息图

每一步均遵循 references/pgo_and_telemetry_guide.md 中的命令示例和核心工程标准：

步骤 1：搭建安全 Rust 工作区并移植模块（rewrite 计时桶）

1. 启动 rewrite 计时桶（scripts/telemetry.py start-bucket --bucket rewrite）。
2. 初始化 Rust 工作区，在 src/lib.rs 和 src/main.rs 中加入 #![forbid(unsafe_code)]。
3. 按依赖顺序实现确定性 PRNG 包装器、领域类型和模块（每个文件目标 不超过 400 行），并编写完整的 //! 和 /// Rustdoc，以及可运行的文档测试。
4. 通过 scripts/telemetry.py log-benchmark 对阶段 2（safe_rust）和 阶段 3（soa_simd）进行基准测试并记录。

Step 2：验证熔炉——测试、失败、诊断与修复（test_heal 桶）

1. 启动 test_heal 计时桶（scripts/telemetry.py start-bucket --bucket test_heal）。
2. 编写单元测试、可运行的文档测试和 proptest 边界测试。
3. 运行 cargo test --all-targets、cargo test --doc 和 cargo clippy --all-targets。
4. 记录每次迭代（最多 5 次）：在第 1 次运行及之后的每次运行后，调用 scripts/telemetry.py log-test-run，记录测试总数、通过数、失败数、覆盖率 %、Clippy 警告数、诊断摘要和已应用的修复。持续迭代，直至失败数和警告数均为 0（或达到 5 次迭代的上限，并记录任何无法避免的例外情况）。

Step 3：A/B 差分输出一致性（parity 桶）

1. 启动 parity 计时桶（scripts/telemetry.py start-bucket --bucket parity）。
2. 在 N 个确定性种子上运行自动化 A/B 差分测试工具，在文档规定的 epsilon 容差内比较 {baseline_run_command} 和 Rust 二进制文件。
3. 通过 scripts/telemetry.py log-parity-run 记录每次一致性迭代。如果任何种子的偏差超出 epsilon，则对首次偏差的步骤进行二分定位，修复差异并重新运行（最多迭代 5 次）。

Step 4：性能引导优化（PGO）与最终基准测试（pgo_bench 桶）

1. 启动 pgo_bench 计时桶（scripts/telemetry.py start-bucket --bucket pgo_bench）。
2. 按照 references/pgo_and_telemetry_guide.md 执行 LLVM PGO 工作流：使用 RUSTFLAGS="-Cprofile-generate=./pgo-data" 构建、运行有代表性的工作负载、通过 llvm-profdata 合并性能分析数据，然后使用 RUSTFLAGS="-Cprofile-use=./pgo-data/merged.profdata" 和 lto = "fat" 重新构建（如果无法使用 llvm-profdata，则采用文档说明的 -Ctarget-cpu=native 替代方案）。
3. 验证测试和 A/B 一致性检查在 PGO 二进制文件上仍然通过，然后测量墙钟运行时间和峰值 RSS，并通过 scripts/telemetry.py log-benchmark --stage pgo_lto 记录第 4 阶段（pgo_lto）。

Step 5：最终统计、第一人称 AI 故事与可视化信息图

1. 在 src/ 上运行 scripts/telemetry.py scan-codebase --phase after，统计最终代码行数（LOC）、是否符合 <= 400 LOC 限制、注释/rustdoc 密度、可运行的文档测试、嵌套深度和 unsafe 代码块数量。

2. 记录优化前后代码聚焦展示（scripts/telemetry.py log-spotlight），并填写第一人称 AI 故事章节（scripts/telemetry.py set-story）。

3. 结束 pgo_bench 计时桶并生成交互式 HTML 信息图（{skill_dir} 为包含此 SKILL.md 的目录）：

   python3 "{skill_dir}/scripts/telemetry.py" render-infographic \
     --telemetry "{workspace_dir}/migration_telemetry.json" \
     --out "{output_dir}/migration_infographic.html" \
     --scope-summary "{short_summary_of_ported_modules}"
   

4. 输出简洁的执行摘要，引用生成的 migration_infographic.html 报告和关键的前后测量指标。

---

随附资源

• 遥测与信息图 CLI： scripts/telemetry.py
• 工程标准、蓝图规范、PGO 与遥测操作指南： references/pgo_and_telemetry_guide.md
• 交互式 HTML 信息图模板： references/infographic_template.html