跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
其他技能

port-to-rust

Run a port into Rust without losing behaviour — define the parity contract, sequence the phases, migrate incrementally behind a stable boundary, and prove parity differentially. Use when moving, porting, rewriting, or migrating an existing codebase into Rust from any language, when deciding how to sequence or scope a rewrite, when a port needs to prove it matches its source, or when a partially-ported system needs both implementations running side by side.

rewrite-rs · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add rewrite-rs/skills --skill port-to-rust

技能说明


name: port-to-rust description: Run a port into Rust without losing behaviour — define the parity contract, sequence the phases, migrate incrementally behind a stable boundary, and prove parity differentially. Use when moving, porting, rewriting, or migrating an existing codebase into Rust from any language, when deciding how to sequence or scope a rewrite, when a port needs to prove it matches its source, or when a partially-ported system needs both implementations running side by side.

Port to Rust

A port is a behaviour-preserving move, and nothing else

The one rule this skill exists to enforce: during a port, behaviour changes and code improvements are separate commits, separate reviews, and preferably separate weeks. A port that also fixes bugs cannot be validated — every difference is ambiguous between the fix and the regression, and the differential harness reports both identically. Improvements are written down as a follow-up list and shipped after parity is proven.

Start from the parity contract, not from the code

Before any Rust is written, the contract answers four questions: what the unit of parity is (a CLI invocation, a library function, an HTTP response, a file artifact); which differences are acceptable (log wording, timing, map iteration order, float formatting); which are not (any observable output a caller can branch on); and how parity is measured — the full form in PARITY-CONTRACT.md. A port without a written contract does not have a definition of done, so it finishes when someone gets tired.

Five phases, in order

PhaseEnds when
1. Inventory and seamThe boundary the Rust will live behind is named, and the call sites crossing it are counted
2. CharacterizeThe existing behaviour is captured as executable tests — against the source implementation, not the intended one
3. Port leaf-firstThe lowest-dependency module is in Rust, called through the seam, with both implementations still present
4. Run bothEvery input reaching the seam goes through both implementations and the outputs are compared
5. Cut over and deleteTraffic goes to Rust only, and the source implementation is deleted rather than left as a dead fallback

Phase 2 characterizes the behaviour that exists, bugs included — a test that asserts the intended behaviour is a bug report disguised as a test. Phase 5 is not optional: a source implementation left in place stops being maintained and starts being a lie about what runs; the depth on each phase is in PHASES.md.

Decide the end state before the seam

Three end states; the choice governs everything downstream — the seam, the contract, the verification, whether bindings are deliverable or scaffold:

End stateWhat shipsBindings
A. ReplacementA standalone Rust binary or crate; the source implementation is deletedNone, ever. The seam is a process, CLI, or network boundary
B. Rust core with a language binding as the productA Rust engine plus a binding layer that stays — the package the existing consumers import is the deliverablePermanent. The binding surface is public API: it gets semver, error-type mapping, packaging per platform, and its own docs
C. Bindings as scaffoldA standalone Rust binary or crate, reached through a binding layer that is deleted at cut-overTemporary. Built to be thrown away, and phase 5 is not done until it is gone

B and C are not the same work, and conflating them is the most expensive mistake here. Scaffold bindings may be crude because they die; product bindings are a public surface that outlives the port. Ask which one is wanted — a user porting a CLI to Rust usually wants A, and handing them a native extension module answers a question nobody asked. The answer goes in the parity contract, because it changes what the unit of parity is: for A the unit is an invocation or a request; for B it is the binding signature the existing callers already call.

Pick the incremental strategy from the seam, not from taste

StrategyReach for it when
In-place FFI — Rust compiled into the existing build and called across a language boundaryThe source language has a cheap, stable FFI story and the seam is a function call
Strangler at a process boundary — the Rust binary takes traffic for one route, endpoint, or subcommand at a timeThe seam is already a process, socket, or CLI boundary; the languages do not interoperate cheaply
Whole-unit replacementThe unit is small enough to port and validate in one sitting — a single CLI tool, one library with a narrow surface

The FFI mechanics — which crate, which build integration, which header generator — sit in the per-language skills.

Parity is proven, not asserted

The evidence is both implementations running over the same inputs and agreeing. Building that harness is /rust-testing; this skill decides what it has to cover — every input class the contract names, including the error paths, which are the ones a port silently narrows — and the harness runs in CI from phase 3 onward, not once at the end, because a difference found six modules later cannot be attributed.

What is deliberately not ported

Dead code, workarounds for limitations the source language had and Rust does not, and abstraction layers that existed to work around the source type system — each a judgment call written down in the contract, not made silently mid-file. The inverse error is worse and more common: porting the abstraction rather than the behaviour, so a five-layer class hierarchy becomes five Rust traits nobody needs.

Where the target-side judgment goes

This skill never decides what the Rust should look like. Expression shape is /idiomatic-rust; a clone added to satisfy the borrow checker mid-port is /ownership-not-clone; what a fallible path returns is /rust-errors; whether a state should be constructible at all is /type-driven-design;

阅读完整来源 ↗