rust-rebuilder

# Rust Rebuilder

## Overview

使用“分阶段、可验证、可回滚”的方式重写项目到 Rust。优先确保行为等价和可观测性，再做性能与架构优化。

## Dependency Preflight (Mandatory)

每次执行前先运行：

```bash
python3 scripts/check_dependencies.py
```

自动检测以下依赖是否可用：

- `grok-search` skill，或 `grok-search` MCP。
- `github-helper` skill。

若任一缺失，必须输出安装引导并暂停当前重写任务。安装引导顺序：

1. 优先使用 `$skill-installer` 安装缺失 skill。
2. 若无可用安装器，则给出手动安装地址：
   - grok-search skill: `https://github.com/Frankieli123/grok-skill`
   - grok-search MCP: `https://github.com/GuDaStudio/GrokSearch`
   - github-helper: 当前用户 GitHub 仓库中的 `github-helper` skill 仓库
3. 明确标记“依赖未满足，重写任务暂停”。

## Workflow

1. 定义范围：确认系统边界、关键路径、性能目标、上线约束。
2. 建立映射：将源项目的模块/接口/数据模型映射到 Rust crate 与模块结构。
3. 制定切片：按垂直功能切分迁移批次，每批必须可编译、可测试、可回归。
4. 执行重写：先保行为一致，再替换为更地道的 Rust 设计；若是后端代码，强制套用 `references/rust-backend-guidelines.md`。
5. 校验对齐：运行编译、测试、基准、回归对比，阻断行为漂移。
6. 跟踪上游：若源项目在 GitHub，持续同步 upstream 变更并更新重写 backlog。

## Backend Rust Guardrails

当目标是后端 Rust 代码（例如 API、作业系统、数据库访问、异步任务）时，必须先读取 `references/rust-backend-guidelines.md`，并在输出中显式说明以下检查点：

- 数据结构是否用 `enum`/newtype 表达状态和不变量；
- SQLx 查询是否显式列名且无 `SELECT *`；
- async 代码是否避免阻塞 runtime；
- 错误处理是否统一 `Result` 语义且无库级 `panic`；
- 可见性是否 `pub(crate)` 优先，模块边界是否收敛。

## Mandatory Output Contract

在每次执行中输出以下内容，避免“只给代码不讲迁移依据”：

- Rewrite Scope：本轮重写的模块、接口和非目标范围。
- Equivalence Strategy：行为对齐方式（黄金测试、对拍、协议回放）。
- Rust Design Decisions：所有权、生命周期、错误模型、并发模型选择。
- Risk Register：已识别陷阱、触发条件、监控指标、回退方案。
- Upstream Sync Notes：与原仓库分叉点、增量 co...