rust-anything
作者:erKam Yaman
English · Türkçe · 简体中文 · 繁體中文 · Deutsch · Français · Русский · Українська · 日本語 · 한국어 · Azərbaycanca · Oʻzbekcha · Қазақша · Кыргызча · Türkmençe · Татарча · ئۇيغۇرچە · Português
本譯文由社群維護,可能落後於英文 README。
用 Rust 重寫你的整個應用程式,並在每一步都保持正常運作。
無論是命令列工具(CLI)、伺服器還是函式庫,都能逐塊重寫,每一步都與原版實作進行比對驗證。
Node.js 與 TypeScript · Python · C · Go · Ruby · Java · PHP 與 C# 搶先預覽中
最高提速 20 倍 · 重播 38,251 筆錄製案例 · 0 筆差異 · 一條指令搞定
**用 Rust 逐塊重寫你的整個應用程式。** rust-anything 會先錄製你現有的
Node.js(TypeScript/JavaScript)、Python、C、Go、Ruby 或 Java 應用程式的行為,然後針對每一塊
Rust 重寫程式碼對照該錄製紀錄進行驗證,確認無誤後再繼續下一步,直到整個應用程式成為純 Rust。CLI、HTTP
伺服器與函式庫皆適用;由你的程式開發代理程式(或你本人)來撰寫 Rust 程式碼。它只能偵測到錄製內容所涵蓋的行為:請參閱[它偵測不到什麼](#它偵測不到什麼)。如果只需要加速慢的部分,
也可以只針對該熱點路徑逐一移植:
| 真實工作負載(結果與原版完全一致) | 原版 | 使用 rust-anything |
| --- | ---: | ---: |
| x18n 的側邊欄搜尋,50,000 個鍵(TypeScript,Node) | 每次查詢 10 ms | **0.5 ms:提速 20 倍** |
| 瀏覽器端執行相同搜尋(wasm,單執行緒) | 10 ms | **0.95 ms:提速 11.5 倍** |
| 對 20,000 個字串執行 `slugify`(Python) | 98 ms | **提速 17 倍** |
| Ruby 標準函式庫 `Shellwords.shellescape`,50,000 個值 | 88 ms | **提速 11.8 倍** |
| 對 50,000 個字串執行 `Slugify`(Go) | 49 ms | **提速 4 倍** |
| 對 50,000 個字串執行 `slugify`(Java) | 43 ms | **提速 3 倍** |
以上數據均在 4 核心環境下測得;每組數字在 [`demo/`](../demo) 中都有對應的基準測試,且都會先驗證結果完全一致。每個小函式呼叫一次 Rust 通常比 JIT 更*慢*;
rust-anything 會找出真正值得搬移的迴圈,並將整個迴圈移過去。
> rust-anything 是一個獨立專案,與 Rust Project 或 Rust Foundation 無關,亦未獲其背書。「Rust」為 Rust Foundation 之商標。
## 快速開始
將這段話貼給 Claude Code、Codex、Cursor 或 Gemini CLI,讓你的代理程式自動安裝:
```text
安裝 rust-anything:執行 `cargo install rust-anything`,接著執行 `rust-anything setup`。
告訴我什麼時候需要重新啟動你。
```
或是自行安裝:
```sh
cargo install rust-anything # 從 crates.io 安裝
rust-anything setup # 向 Claude Code、Codex、Cursor 與 Gemini CLI 註冊
```
還沒有安裝 Rust 工具鏈?每個 [GitHub release](https://github.com/erkamyaman/rust-anything/releases) 都附帶了 macOS、Linux 與 Windows 的預先編譯執行檔;針對 JavaScript
專案,執行 `npm install -g rust-anything` 也能安裝相同的執行檔。
在 Claude Code 中你也可以將它安裝為外掛(包含 MCP 伺服器與工作流程技能;上述 CLI
必須位於你的 `PATH` 中):
```text
/plugin install rust-anything --marketplace erkamyaman/rust-anything
```
`setup` 會將 MCP 伺服器加入它所偵測到的每個代理程式中,並將工作流程技能安裝至各代理程式讀取技能的目錄。它會保留你的其他設定、可安全重複執行,且可用 `--remove` 移除這些設定項目(不會還原先前被 `setup` 更新過的同名既有項目)。
接著你就可以直接請你的代理程式協助,例如:
- *「用 rust-anything 將這個 CLI 端到端重寫為 Rust,並證明其行為完全相同。」*
- *「這個搜尋感覺很慢。用 rust-anything 做效能分析,並將熱點迴圈搬移到 Rust。」*
- *「用 rust-anything 規劃將 `src/parser/` 遷移至 Rust;先移植第一個單元並進行驗證。」*
- *「將 `rust/text-rs` 中的 Rust 移植版與原版進行基準測試比對,告訴我是否適合上線。」*
### 支援的代理程式
| 代理程式 | `rust-anything setup` 會加入的設定 |
| --- | --- |
| Claude Code | `~/.claude.json` 中的 MCP 伺服器、`~/.claude/skills/` 中的技能 |
| Codex | `~/.codex/config.toml` 中的 MCP 伺服器、`~/.codex/skills/` 中的技能 |
| Cursor | `~/.cursor/mcp.json` 中的 MCP 伺服器 |
| Gemini CLI | `~/.gemini/settings.json` 中的 MCP 伺服器 |
| 其他任意 MCP 用戶端 | 手動將 `rust-anything mcp` 新增為 stdio 伺服器(見[安裝](#安裝)) |
修改任何已存在的設定檔前,`setup` 都會在同目錄旁留存一份備份(`.rust-anything.bak`)。
你也可以自行執行這些步驟:
```sh
rust-anything profile . -- node bench.mjs # 找出耗時熱點以及誰呼叫了它
rust-anything bridge . src/fuzzy.ts --batch fuzzyScore:text
# 撰寫 src/port.rs(或交由代理程式撰寫),接著執行:
rust-anything record rust/fuzzy-rs && rust-anything build rust/fuzzy-rs
rust-anything diff rust/fuzzy-rs # 每筆錄製案例都必須吻合
rust-anything bench rust/fuzzy-rs # 真的更快嗎?讓評估結論說話
rust-anything gate rust/fuzzy-rs # 通過此門禁才算完成
```
rust-anything 並不直接翻譯程式碼:Rust 程式碼是由你的程式開發代理程式(Claude Code、Codex、Cursor 等)或你本人所撰寫。rust-anything 提供的是代理程式無法可靠猜測的資訊:時間花在哪裡、該先移植什麼
以及依何種順序移植、讓其餘程式碼無需改變 API 即可呼叫 Rust 的橋接層、
移植版必須完全吻合的精確行為、安全上線的方式,以及判定移植是否達標的門禁。
## 支援語言
| 語言 | 遷移單元 | 橋接層 | 錄製與重播方式 |
| --- | --- | --- | --- |
| TypeScript/JavaScript | 資料夾或單檔 | napi-rs 或 wasm-bindgen 搭配自動產生的二進位傳輸協定;支援類別與非同步 | Node,直接執行 `.ts` 原始碼 |
| Python | 套件或模組 | PyO3(abi3),直接型別轉換,支援型別化例外 | Python,匯入原版模組 |
| C | `.c` 檔案 | 與原函式同名的 `extern "C"` 函式與標頭檔 | 將原版編譯為共享函式庫,透過 ctypes 呼叫,每筆案例獨立 fork |
| Go | 套件(package) | 型別化 cgo 呼叫與自動產生的二進位傳輸協定,封裝於維持原 API 的套件內 | 自動產生的 Go 驅動程式,作為獨立模組建置執行 |
| Ruby | 包含模組函式的檔案或資料夾 | 掛載於原模組名稱下的 magnus 擴充套件 | 自動產生的 Ruby 驅動程式 |
| Java | 包含 `public static` 方法的套件 | 型別化 JNI 與自動產生的二進位傳輸協定,置於維持原方法的包裝類別中 | 自動產生的反射(reflection)驅動程式 |
| PHP(預覽) | 包含函式與 `public static` 方法的資料夾 | 下一步推出:透過 C ABI 運作的 PHP FFI | 目前支援整套應用程式:`app record`、`app replay` 與前門代理,適用於 CLI 與伺服器(`php -S`) |
| C#(預覽) | 包含 `public static` 方法的資料夾 | 下一步推出:透過 C ABI 運作的 P/Invoke | 目前支援整套應用程式:`app record`、`app replay` 與前門代理,適用於 CLI 與 ASP.NET 伺服器(`dotnet .dll`) |
除了 C 語言外,每種語言皆可產生批次處理類別(`--batch`):所有資料只需跨邊界傳入一次並留在
Rust 中,每次呼叫便會在所有 CPU 核心上平行運算全部項目。
系統會根據儲存庫內容自動偵測語言(依序檢查 `go.mod`、`pom.xml`、`.csproj` 或 `.sln`、
`pyproject.toml`、`Gemfile`、`composer.json`、`package.json`,否則依最常見的原始碼檔案判斷);
也可以透過 `--lang` 手動覆寫。型別資訊直接來自原始碼:TS 型別、Python 型別提示、C、Go、Java 與 C#
函式簽章、Ruby YARD 標籤、PHP 型別與 phpdoc;未標註型別但當作數值使用的參數,會被自動推斷
為數值型別。
PHP 目前為搶先預覽階段:`analyze` 可為 PHP 應用程式規劃遷移(支援 Composer 套件與 PSR-4 自動載入,偵測
寬鬆比較與整數溢位轉浮點數等風險,並將 Composer 套件對應至 crate),
且支援對 PHP CLI 或伺服器進行錄製、重播與套用 Rust 前門代理。透過 PHP FFI 將各個
單元移植到 Rust 是下一步規劃([issue #2](https://github.com/erkamyaman/rust-anything/issues/2))。
C# 同樣處於搶先預覽階段:`analyze` 會讀取 `.csproj` 專案與其 NuGet 套件
(對應至 crate)、將 `using` 指示詞解析至對應資料夾,並標記 C# 的特殊差異
(`decimal`、`dynamic`、LINQ 的延遲查詢、`Task`、`lock`、反射)。目前可對 C# CLI 或 ASP.NET
伺服器進行錄製、重播與套用 Rust 前門代理;透過 P/Invoke 移植個別單元則為下一步支援項目。
## 運作原理
```
profile ──> analyze ──> bridge ──> record ──> port.rs ──> diff ──> bench ──> shadow ──> gate
時間花 該先移植 Rust 原版程式 由你或 每筆 更快嗎? 在正式環境 通過此門禁
在哪裡 哪個部分 crate 與 的真實 代理程式 錄製 評估結論 雙軌並跑 才算完成
包裝層 行為 撰寫 案例
```
原版實作始終作為唯一事實來源(Source of Truth):`record` 會在邊界案例(以及你提供的輸入)上執行原版程式,並
儲存其回傳值或拋出的例外;`diff` 會對 Rust 實作重播每筆案例;在所有案例完全吻合且
`gate` 通過之前,絕不會上線。整個過程中,呼叫端始終維持原有的 API。
整個應用程式會以單元為單位走完相同的循環,外層則由一個證明整體程式行為的框架包覆(見[遷移整個應用程式](#遷移整個應用程式)):
```
analyze --whole-app ──> app record ──> app front-door ──> 逐單元執行上述循環,再接 app wire ──> app lift
專案架構、所有相依 從外部觀察 Rust 接管程式 單元通過門禁後改由 Rust 回應: 純 Rust,
套件、需要敲定的決策 應用的行為 進入點;原版負責 重播 100% 通過、回退率下降 由重播驗證
實際回應
```
## 核心流程
| 步驟 | 指令 | 說明 |
| --- | --- | --- |
| 0. 效能分析 | `rust-anything profile -- node bench.mjs` | 在該語言的效能分析器下執行真實工作負載(node、cProfile、`go test` pprof、JFR、Ruby 追蹤器):依總耗時(inclusive time)列出熱點函式、其呼叫端,以及適合批次處理的迴圈;標記已經編譯加速的程式碼(numba、Cython、JAX),提示遷移至 Rust 收益有限 |
| 1. 規劃 | `rust-anything analyze ` | 盤點單元、移植順序、附帶 `file:line` 的風險評估、各單元的橋接方式、相依套件與 crate 的適配度、最佳首批移植對象;加上 `--whole-app` 還會列出進入點與架構形態、所有(匯入或宣告的)相依套件及其對應 crate、區塊分群(互相匯入的單元會一起搬移),以及附帶推薦答案的編號決策清單 |
| 2. 橋接 | `rust-anything bridge ` | 建立包含繫結程式碼(`lib.rs` 以及供原語言載入的包裝層)與待移植佔位實作(`port.rs`)的 crate;`--batch fn:param` 會額外產生一個將大量 `param` 值常駐保留在 Rust 中的類別 |
| 3. 錄製 | `rust-anything record ` | 在自動產生的邊界案例(非 ASCII 字元、emoji、`-0`、`NaN`、預期浮點數卻傳入整數等)與覆蓋每個參數語意陷阱的測試值(字串長度與大小寫、有號除法、溢位邊界、浮點數格式化、Map 與排序順序)上執行原版程式,並儲存為 `cases.jsonl`;數值程式碼可使用 `--float-tolerance 1e-9` 允許浮點數在該誤差比例內比對通過 |
| 3. 建置 | `rust-anything build ` | 建置 Rust 端產物:`.node`、wasm 套件、Python 擴充模組或共享函式庫 |
| 3. 比對 | `rust-anything diff ` | 以原版呼叫端實際呼叫的方式,對 Rust 重播所有已錄製案例,並列出不一致處 |
| 3. 基準測試 | `rust-anything bench ` | 分別測量原版與 Rust(含橋接層開銷)執行已錄製案例的耗時 |
| 4. 影子模式 | `rust-anything shadow ` | 無痛替換模組,同時執行兩邊實作、回傳原版結果並回報差異;透過 `RUST_ANYTHING_MODE=old\|shadow\|new` 切換 |
| 5. 門禁 | `rust-anything gate ` | 檢查 fmt、clippy `-D warnings`、測試、`unsafe` 稽核、無未完成移植的函式、原版每條錯誤路徑皆有對應的錄製失敗案例、在原版回傳錯誤之處不得使用 `unwrap`/`expect`/`panic!`(除非標記 `// INFALLIBLE: <原因>`)、建置、API 與行為一致性 |
| 代理程式 | `rust-anything setup` | 向你的程式開發代理程式註冊 MCP 伺服器(`rust-anything mcp`,將每個步驟包裝為工具)與工作流程技能([`skills/rust-anything/SKILL.md`](../skills/rust-anything/SKILL.md)) |
## 遷移整個應用程式
目標是打造出一個行為與原版完全一致的純 Rust 應用程式,同時保留原版作為參考基準。
Rust 程式碼由你的代理程式撰寫;rust-anything 負責排定作業順序、搭建骨架並驗證每一個步驟。
[整套應用程式遷移技能(whole-app skill)](../skills/rust-anything/whole-app.md) 會引導代理程式完成全流程,從只有你能拍板的決策開始:
- **深度詰問(Grilling)**:代理程式會分輪提問,每題皆附有推薦答案,直到移植所依賴的每項決策都確定為止,並將每項決策以 ADR 格式寫入 `rust/DECISIONS.md`,同時建立 `rust/GLOSSARY.md` 將原版術語對應至 Rust 命名。
- **深入調研(Research)**:背景代理程式會閱讀每個相依套件的第一手原始碼,並撰寫 `rust/research/.md`,記錄所發現的每一個語意陷阱。
- **跨工作階段接力(Across sessions)**:`rust/MAP.md` 列出每個單元的狀態;每個工作階段在開始前會先認領一個單元,並在每個檢查點留下 `rust/HANDOFF.md` 交接給下一個工作階段。同一波次中的單元可由子代理程式平行移植。
- **切換上線(Cutover)**:代理程式會完成它能執行的部分,並撰寫互動式腳本 `rust/cutover.sh` 來處理只有你能執行的步驟(部署、DNS、機密金鑰),且每一步都備有復原方案。
深度詰問、原始碼調研等實務做法改編自 [Matt Pocock's skills](https://github.com/mattpocock/skills)。
先做規劃:`rust-anything analyze . --whole-app` 會補充應用程式的架構形態(CLI、伺服器或函式庫)
與進入點、每個外部相依套件(匯入或宣告)及其對應的 Rust crate 與適配度、
依區塊(互相匯入的單元會一併搬移)編排的移植順序,以及附帶推薦答案的編號決策清單:包含保留原樣的單元、受阻單元、缺乏替代或僅有部分替代 crate 的相依套件。
接著從外部驗證整個程式。`record` 與 `diff` 用於驗證單一單元;`app record`
與 `app replay` 則針對六種語言的 CLI 與伺服器驗證整個應用程式(把應用程式視為一個黑盒子):
```sh
rust-anything app record . -- python3 cli.py # 執行原版應用程式的指令
rust-anything app replay . # 原版必須 100% 通過
rust-anything app replay . --build "target/release/mytool"
```
- `app record` 會在以下輸入上執行原版應用程式:專案文件內自帶的範例(Markdown 與 shell 檔案中的 `$ mytool ...` 指令列及其指名的檔案)、透過 `--inputs` 傳入的 JSONL 檔案(`{"name", "args", "stdin", "env", "files"}`),以及從這些案例衍生出的語意陷阱(非 ASCII 與 emoji 字串、負數除法與取餘數、溢位、極大與極小浮點數、Map 順序、遺失檔案)。每筆案例皆會執行兩次;兩次輸出不同的部分會自動轉為 `[..]` 萬用字元。`--normalize timestamps|uuids|key-order` 或 `--normalize name=regex` 可加入正規化規則,並與案例一併儲存。
- 案例以 [trycmd](https://docs.rs/trycmd) 檔案格式存放於 `rust/app-cases/`:`.toml`(argv、env、結束代碼)、`.stdin`、`.stdout`、`.stderr`、`.in/`(輸入檔案)與 `.out/`(寫出的檔案)。你可以直接閱讀並手動編輯這些檔案;一旦有了 Rust 執行檔,就能在 Rust 測試中直接透過 `trycmd` 執行它們。
- `app replay` 會針對這些案例執行任意建置產物、印出 `passed/total`、在 `rust/app-cases/replay-report.md` 為每筆失敗案例寫出差異比對,並在出現任何不一致時以非零狀態碼結束。如果建置產物像下方的「前門」程式一樣,會將回退至原版的事件附加寫入 `RUST_ANYTHING_FALLBACK_LOG` 指定的檔案(每次回退一行),系統也會一併回報回退率。
- `app replay --case ` 可依報告中的案例名稱單獨重跑某一筆案例:這是在全量重跑前,快速且可重現的除錯與修正迴圈。
接著將程式進入點移至 Rust,並一次一個單元把指令交給 Rust 處理:
```sh
rust-anything app front-door . # rust/app:每個指令都會執行原版程式
rust-anything app wire . textkit --command upper # 在 textkit-rs 通過 gate 之後
# 在 rust/app/src/units/textkit.rs 撰寫銜接程式碼,接著執行:
rust-anything app wire . textkit # 再次 100% 通過,且回退率下降
```
- `app front-door` 會建立以應用程式命名的 Rust 二進位專案骨架 `rust/app`:內含根據錄製案例的指令與旗標產生的 clap 解析器,每條指令都會以相同的 argv、stdin 與環境變數執行原版程式,並將其輸出與結束代碼原封不動傳回。每次回退都會被計數,因此剛建立的前門程式重播時會得到 100% 通過、100% 回退(它會實際建置並重播以證明這點)。它絕不會覆蓋已存在的 `rust/app`:從那刻起程式碼完全歸你所有。
- `app wire --command ` 會對該單元的 crate 執行 `gate`(若剛通過可加 `--skip-gate`),將其作為函式庫加入 `rust/app`,初次建立 `src/units/.rs` 供你或你的代理程式填入邏輯(解析參數、呼叫 `::port`、印出與原版相同的輸出),將對應指令導向至該處,接著重新建置並重播。在最後收尾(lift)前,設定 `RUST_ANYTHING_UNIT_=original` 即可將已接線的單元切換回原版實作。
對於未指定指令名稱的 argv(無參數、未知指令、用法錯誤),請將應用程式自身的名稱作為指令接線(`--command mytool`)。
當重播通過且回退率為 0、所有單元也都通過 `gate` 時,就可以將它轉為純 Rust 應用程式:
```sh
rust-anything app lift .
```
- 在這兩項條件都達成前,`app lift` 會拒絕執行,並明確指出受阻原因:哪些案例仍在回退、哪些銜接程式碼仍是佔位實作、哪些單元未通過 gate。
- 它會先在複本上執行操作:移除回退路徑與緊急切換開關、將每個單元 crate 轉為 `rust/app` 的一般函式庫(不再需要 `cdylib`、繫結或自動產生的包裝層),並新增 `rust/app/tests/app_cases.rs`,讓 `cargo test` 透過 trycmd 執行 `rust/app-cases`,從此 CI 只需要 cargo 即可運作。
- 接著它會執行收尾檢查清單:對每個單元與 `rust/app` 執行 fmt、clippy `-D warnings` 與測試,建置或檢查 `rust/DECISIONS.md` 中列出的所有已安裝目標平台,檢查執行期讀取的檔案與未嵌入的資源資料夾,並對純 Rust 執行檔執行重播。只有當這一切全部通過後,變更才會寫回工作區。原版檔案自始至終絕不會被修改。
### 伺服器
相同的指令也能用來驗證 HTTP 伺服器。`--http` 表示該指令會啟動一個伺服器;它會從環境變數 `PORT` 或指令中的 `{port}` 取得連接埠號(若伺服器總是監聽固定連接埠,可使用 `--port`):
```sh
rust-anything app record . --http -- node server.js
rust-anything app replay .
rust-anything app front-door . # axum:將所有路由反向代理給原版伺服器
rust-anything app wire . api --route 'GET /users/{id}' --route '*'
rust-anything app lift .
```
- 請求來源包含專案文件中的 `curl` 指令(`curl -X POST -d ... http://localhost:8080/x`)、`--inputs`(`{"name", "method", "path", "headers", "body"}`)與語意陷阱:路徑區段與查詢參數會套用與 CLI 參數相同的陷阱替換,請求主體則套用文字與 JSON 陷阱,並額外包含一個未知路由。每次執行都會全新啟動伺服器,並依名稱順序送出請求,因此請求之間的狀態得以保留。
- 案例儲存為 `rust/app-cases/http/.toml`(請求內容、狀態碼與重要標頭)與 `.body`(回應主體,兩次執行不同處標記為 `[..]`)。`Date`、`Server` 等每次回應都會變動的標頭會自動略過;你也可以刪除任何不在乎的標頭行。
- 前門是一個 axum 伺服器,它會在獨立連接埠啟動原版伺服器,並將所有尚未由 Rust 單元回應的路由代理過去。`wire --route` 接受 axum 路由語法:`METHOD /path/{param}`、不指定方法的 `/path`(匹配任意方法)、以及代表其餘全部的 `*`;銜接程式碼會取得該路由、其參數與請求物件。`lift` 會移除代理;之後 HTTP 案例便可在 CI 中透過 `app replay` 執行。
### 函式庫
函式庫沒有獨立行程可供重播:它的公開 API 就是前門,而每個單元的錄製案例就是驗證依據。
```sh
rust-anything app front-door . # rust/app:包含公開 API 的 Rust crate
# 每個單元走完循環:bridge、record、port.rs、build、diff、gate;接著:
rust-anything app wire . textkit-rs # 從 rust/app 重新匯出;原版改為匯入其影子模組
rust-anything app replay . # 執行每個已接線單元的案例;回退率 = 仍由原版處理的匯出項目比例
rust-anything app lift .
```
- 當儲存庫沒有 `main` 也沒有伺服器時(否則可加上 `--library`),`app front-door` 會找出公開 API(每個單元的匯出項目),並將 `rust/app` 建立為函式庫 crate 骨架。每個已接線的單元都會成為它的一個模組:`pub use textkit_rs::port as textkit;`。
- `app wire` 會接收由 `bridge` 建立的 crate、執行 `gate`,並寫出該單元的影子替換模組:原版套件會改為匯入該影子模組以取代原單元,讓呼叫端保持原有 API 卻實際執行 Rust。設定 `RUST_ANYTHING_UNIT_=original` 可將該單元切回原版(C 語言則在建置時不帶入影子模組的旗標即可)。
- `app replay` 會透過繫結執行每個已接線單元的錄製案例。回退率代表尚未由 Rust 回應的公開匯出項目佔比:包含未接線的單元,以及被 `bridge` 保留在原語言中的匯出項目。
- `app lift` 要求回退率為 0 且每個單元都通過 `gate`;它會從各單元剝除繫結、包裝層與影子模組,只留下 `rust/app` 作為一個純 Rust 函式庫。它不會更動任何 `port.rs`,因此先前透過繫結驗證吻合的案例依然適用;檢查清單也會提醒原版程式中是否還有檔案仍在匯入影子模組。
這五個指令同樣提供對應的 MCP 工具:`app_record`、`app_replay`、`app_front_door`、`app_wire` 與 `app_lift`。
## 案例研究:x18n 核心
x18n 核心中所有無需改變 API 即可搬移的 29 個函式,已全部透過 rust-anything 完成移植:
每項門禁皆通過,且 7,925 筆錄製案例完全吻合。但接著 `rust-anything bench` 顯示,從 JS 呼叫這些移植版
反而比原版 TS 更慢,因為跨橋接層的成本高於運算本身的工作量。完整報告請見
[`demo/x18n-core`](../demo/x18n-core/README.md)。這個教訓已內建於流程之中:上線移植版之前,務必先用 `bench` 實測。
## 熱點路徑:把資料留在 Rust 中
每處理一個項目就跨橋接呼叫一次 Rust,等於每個項目都要付一次橋接成本,往往會輸給 JIT。真正能勝出的方法是
搬移整個迴圈:`profile` 會找出熱點迴圈,而 `--batch` 會產生一個類別,只需傳入項目一次,
每次呼叫便可在所有核心上對全部項目進行運算,並回傳型別陣列(TypedArray)結果。
```sh
rust-anything profile ../x18n -- node --experimental-strip-types $PWD/demo/x18n-search/search.ts .
# -> fuzzyScore:佔整體執行時間四分之一,被 `matched` 按每個鍵逐一呼叫:將它批次化
rust-anything bridge ../x18n packages/core/src/fuzzy.ts --batch fuzzyScore:text
```
```js
const search = new FuzzyScoreBatch(keys) // 初始化一次
const order = search.rank(query, 0) // 每次按鍵呼叫:依最佳匹配排序的索引
```
`port.rs` 中的 `FuzzyScoreIndex` 結構體會取代預設迴圈,改為先預處理項目一次,
並能自行完成排序(`rank`):它保存轉為小寫的鍵值與各自的字元遮罩、
一張記錄每個鍵中常見字元首次出現位置的對照表(單字元查詢只需讀取一欄),
以及上一次查詢的命中結果(輸入 `s` 後再輸入 `se` 時,僅針對 `s` 命中的項目重新評分)。在
x18n 側邊欄針對 50,000 個鍵逐字輸入的搜尋測試中,結果完全一致:
| 實作方式 | 每次查詢耗時 | 對比 TS |
| --- | ---: | ---: |
| TS:`map(fuzzyScore)`、過濾、排序 | 10 ms | 1x |
| 採用相同索引縮小範圍策略的 TS | 4.1-5.4 ms | 2x |
| 同一份移植版,按鍵逐次呼叫 | - | 0.2-0.4x |
| `FuzzyScoreBatch`,預設索引(4 核心) | 5.1 ms | 1.7x |
| `FuzzyScoreBatch` 搭配 `FuzzyScoreIndex`(napi,4 核心) | 0.45-0.56 ms | **18-22x** |
| 同上,改用 wasm(單執行緒) | 0.95 ms | **11.5x** |
即使與採用相同縮小範圍策略的 TS 相比,Rust 依然快上 7-12 倍(wasm 快 5 倍)。將回傳的
索引轉回鍵值字串時請使用一般迴圈:`Array.from(order, i => keys[i])` 會多花 20 倍的時間(0.4 ms)。
每種語言皆支援批次處理,甚至在單次呼叫輸給原版的場景下也能反敗為勝。在 4 核心上執行
相同的工作負載,結果與錯誤完全一致(各示範資料夾內皆附有基準測試):
| 語言 | 工作負載 | 原版 | 單次呼叫移植版 vs 原版 | 批次處理 vs 原版 |
| --- | --- | ---: | ---: | ---: |
| TS | x18n 搜尋,50,000 個鍵 | 10 ms | 0.2-0.4x | **20x** |
| Python | `slugify`,20,000 個字串 | 98 ms | - | **17x** |
| Ruby | `slugify`,20,000 個字串 | 110 ms | - | **12.7x** |
| Ruby | `shellescape`(標準函式庫),50,000 個混合值 | 88 ms | - | **11.8x** |
| Go | `Slugify`,50,000 個字串 | 49 ms | 0.93x | **4x** |
| Java | `slugify`,50,000 個字串 | 43 ms | 0.68x | **3x** |
原版若是編譯型語言,提速幅度會較小:單項處理本來就已經很快,因此批次處理主要靠多核心數量取勝。
批次 crate 預設採用 mimalloc 進行記憶體配置:若改用系統配置器,Go 批次處理甚至比單執行緒還要慢。示範專案:[`demo/x18n-search`](../demo/x18n-search/README.md)。
## 六種語言的真實程式碼實測
Go 的 `path`、Ruby 的 `shellwords`、Python 的 `colorsys`,以及輕量外觀模式背後的 JDK 與 glibc 行為:
每個移植專案皆通過門禁,總計驗證 13,010 筆錄製案例。這些實測也發現並修復了
rust-anything 自身的問題(浮點數經過 `serde_json` 時產生 1 個 ULP 誤差、C 語言在錄製期間當機、
無型別程式碼收到垃圾輸入)。按函式單次呼叫時,Ruby 移植版比 Ruby 快 4.4 倍,
Python 移植版比 CPython 快 1.35 倍,而 Go 與 Java 的葉節點函式在各自原語言中依然較快;
一旦轉為批次處理,所有語言全面勝出(見上方表格)。
實測報告:[`docs/real-world-languages.md`](./real-world-languages.md)。
## 範例:來自 x18n 的真實模組
來自 [x18n](https://github.com/x18n-dev/x18n) 的 `packages/core/src/fuzzy.ts`,已透過兩種方式移植於
[`demo/`](../demo):
```sh
rust-anything analyze ../x18n # fuzzy.ts:已就緒,wasm-bindgen(核心會在瀏覽器中執行)
rust-anything bridge ../x18n packages/core/src/fuzzy.ts --out demo/fuzzy-rs
rust-anything record demo/fuzzy-rs --count 2000
# 撰寫 src/port.rs
rust-anything gate demo/fuzzy-rs
```
第一版移植採用 Rust 的 `char` 作為索引,雖然通過了簡單測試,卻在 `diff` 失敗了:
```
198/200 cases match
- fuzzyScore("b😀", "a😀b😀c"): expected {"ok":1997}, got {"ok":1998}
```
JS 的 `indexOf` 是以 UTF-16 編碼單元(code unit)計數,因此一個 emoji 會佔用兩個位置。位於
`demo/*/src/port.rs` 中的移植版使用了自動產生的 `utf16` 輔助函式,並分別以 napi-rs(`demo/fuzzy-napi`)與 wasm-bindgen(`demo/fuzzy-rs`)兩種形式
通過了 2000/2000 筆案例與門禁檢查。
rust-anything 為整個 x18n 產生的遷移計畫:[`docs/examples/x18n.md`](./examples/x18n.md)。
## 安裝
```sh
cargo install --path .
```
`record`、`diff` 與 `bench` 會在原語言各自的執行時期環境中執行原版程式碼:TS 需要 Node 22.6+(可直接執行 `.ts`
原始碼),Python 與 C(ctypes)需要 Python 3.9+,其餘為 Go 1.21+、Ruby 3+、JDK 17+
(`javac` 與 `java`)。C 語言另需 C 編譯器。wasm 橋接層則需安裝 `rustup target add wasm32-unknown-unknown` 與
`cargo install wasm-bindgen-cli --version <該 crate 的 wasm-bindgen 版本> --locked`;執行 `build` 時會列出
所需的確切版本號。
針對代理程式環境,`rust-anything setup` 會一次註冊所有項目(見快速開始)。若要手動將 MCP 伺服器
加入單一專案中(`.mcp.json`):
```json
{ "mcpServers": { "rust-anything": { "command": "rust-anything", "args": ["mcp"] } } }
```
## `bridge` 如何決策
- 無法跨過橋接層的匯出項目會保留在原語言中並附註原因,影子模組則會重新匯出原版實作。以 TS 為例:
接收或回傳函式的函式、產生器與疊代器、RegExp、`instanceof` 檢查、
泛型,以及沿著匯入、重新匯出與 `extends` 追蹤後型別內含函式的值。
`--keep "name: reason"` 可保留更多項目,例如相依於 `Intl` 資料的程式碼。
- TS 型別會對應至 Rust 型別,型別別名會跨匯入解析,參數型別則從預設值推斷;
結構化值會透過自動產生的二進位傳輸協定傳遞(僅在該協定無法表達的型別結構時退回 JSON)。
- JSON 無法表達 `undefined`、NaN、Infinity、-0 或孤立代理字元(lone surrogates):結構化值會攜帶
特殊標記(`{"$undefined": true}`、`{"$num": "NaN"}`、`{"$utf16": [...]}`),由自動產生的
`index.cjs` 負責轉換,並搭配 crate 中的 `js.rs` 輔助函式處理。
`record` 會直接執行原樣 TS 原始碼:內建的 Node 解析掛鉤(resolve hook)會處理打包工具風格的匯入
(例如將 `./errors` 解析至 `./errors.ts`);當儲存庫尚未安裝套件時,`--resolve-from` 可指定 npm 套件來源;
而需要轉譯的 TS 語法(如 enum、參數屬性)則會自動改以 `--experimental-transform-types` 重試。
## `analyze` 檢查哪些內容
- 掃描套件(`package.json`)與原始碼檔案;自動略過 `node_modules`、建置產物、測試治具(fixtures)、
演練場(playgrounds)與工具設定檔。支援從 Vue/Svelte/Astro 的 `