lang-migration · 证据驱动 AI 程序迁移

╔═══════════════════════════════════════════════════════════════╗
║                                                               ║
║          ██╗      █████╗ ███╗   ██╗ ██████╗                   ║
║          ██║     ██╔══██╗████╗  ██║██╔════╝                   ║
║          ██║     ███████║██╔██╗ ██║██║  ███╗                  ║
║          ██║     ██╔══██║██║╚██╗██║██║   ██║                  ║
║          ███████╗██║  ██║██║ ╚████║╚██████╔╝                  ║
║          ╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝ ╚═════╝   flynn           ║
║                   M I G R A T I O N                           ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

lang-migration

A Formal Methodology for AI-Driven, Evidence-Obligated Program Translation

[[图片] License: MIT](LICENSE) [[图片] Pairs: 14](#language-pairs) [[图片] Phase: P0–P6](#pipeline) [[图片] Anti-Cheating](#the-evidence-obligation-protocol) [[图片] Works With](#runtime-environments) [[图片] ClawHub](https://clawhub.ai/suifei/lang-migration) [[图片] Version: 1.4](#whats-new)

English | 中文

*Migrate any open-source codebase across programming languages — with structural fidelity, persistent state, and verifiable proof that the AI actually did the work.*

✨ What's New

v1.4 — AST Bridge (tree-sitter Machine Truth) + Invisible Runtime Dependency Detection A shipped toolchain (scripts/ast_bridge.py) extracts function boundaries, branch counts, call sites, and literals directly from source ASTs — structural claims are now verified against machine truth, not AI assertion. Stage 2 generates draft target skeletons with TODO(migrate) markers. Plus: a 3-layer defense (static pattern scan → dynamic runtime trace → P5 closure check) catches files loaded via directory traversal (glob, os.listdir) that static import analysis cannot see. Learn more →

v1.3 — Bug Triage Protocol + Real-World Validation Every P5 test failure now goes through a mandatory 3-step triage before any fix is attempted. Only 1 of 5 verdicts leads to modifying the translated function. Four new root cause categories. Validated against a real Python→Go migration (GenericAgent → go-GenericAgent). Learn more →

ClawHub: https://clawhub.ai/suifei/lang-migration

Skillhub:https://skillhub.cn/skills/lang-migration

The Problem Nobody Talks About

When developers ask an LLM to "migrate my Python project to Go," one of four things happens:

1. The LLM produces plausible-looking code that silently drops behavior. Type semantics, precision contracts, ordering invariants — gone. No one notices until production.

1. The LLM reports completion without doing the work. It marks tasks done, generates placeholder content, and moves on. This is not a bug — it is a rational response to vague completion criteria.

1. The context window collapses. A 50,000-line codebase cannot fit in any single prompt. The LLM loses coherence halfway through, and the migration becomes an archeological exercise in figuring out what was and wasn't translated.

1. The LLM fixes the wrong thing. When a test fails, the AI modifies the translated function — even when that function correctly mirrors the source. The real problem was in the test fixture, the caller, or an implicit model-capability assumption that was never written down. The fix introduces behavioral divergence that didn't exist before.

lang-migration is a structured response to all four failure modes — not through better prompting, but through formal methodology.

What This Is

lang-migration is an AI skill — a portable, agent-agnostic specification that tells any capable LLM exactly how to migrate a codebase, in what order, with what evidence, and how to prove it actually happened.

It is not a tool you run. It is a protocol you install into an AI coding agent.

Think of it as a research methodology that the AI follows, the way a graduate student follows a lab protocol — except the lab protocol has been designed specifically to detect and prevent the ways graduate students (and LLMs) tend to cut corners.

Core Insight: The Evidence Obligation

The central innovation of this methodology is what we call Evidence Obligation — the principle that no unit of work is complete until the AI produces an artifact that can only have been generated by actually doing the work.

This is different from asking the AI to "be thorough." Thoroughness is a moral appeal. Evidence Obligation is a structural constraint.

How It Works in Practice

Consider Phase 3 (IPO Analysis), where the AI must document every function before translating it. Under naive prompting, an LLM will generate plausible-sounding documentation for hundreds of functions in seconds — none of it verified against the actual source.

Under Evidence Obligation, the AI must produce a READ_EVIDENCE block before filling any entry:

READ_EVIDENCE for agent_loop.py::run_step:
  file_read: "agent_loop.py:42-89"
  first_statement: "outcome = self._dispatch_tool(tool_call)"
  last_statement:  "return StepOutcome(data=result, next_prompt=follow_up)"
  literal_count:   3
  call_count:      7
  branch_count:    4

These values — the exact text of the first and last executable statement, the precise count of numeric literals and branch points — cannot be fabricated without reading the file. A hallucinated block will produce wrong line numbers, wrong counts, wrong statement text. This becomes detectable during verification.

The AI must also produce a BEHAVIOR_PROOF for each function:

BEHAVIOR_PROOF for calculate_entropy:
  happy_path:    "Given data=[0.3,0.3,0.4], base=2 → returns 1.5710 (bits)"
  edge_case_1:   "Given data=[0.0, 1.0], filters 0.0 (epsilon=1e-10), returns 0.0"
  would_fail_if: "sum(data) >> 1.0 — inferred invariant violated, results meaningless"

Generic answers ("returns the expected result given valid input") are prohibited. Specific values require genuine understanding.

The Six-Phase Pipeline

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│  P0  Bootstrap      Detect language pair, initialize workspace  │
│   │                                                             │
│  P1  Asset Scan     Every file classified — nothing skipped     │
│   │                                                             │
│  P2  Ecosystem Map  Every import/type mapped with evidence      │
│   │                                                             │
│  P3  IPO Analysis   Every function: Inputs, Process, Outputs    │
│   │                 READ_EVIDENCE + BEHAVIOR_PROOF enforced     │
│   │                                                             │
│  P4  Translation    Translate from IPO spec, not source code    │
│   │                 target_lines mandatory per function         │
│   │                                                             │
│  P5  Verification   Real tests, real data — no mocks, ever      │
│   │                                                             │
│  P6  Gap Report     Invoke anytime: "what's still missing?"     │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Why Translate from IPO, Not Source?

Phase 4 has an unusual constraint: the AI translates from the IPO registry, not from the source code directly. The source may be consulted for clarification, but the IPO entry is the contract.

This separation is deliberate. When an AI reads source code and immediately writes target code, it produces a stylistic approximation — capturing surface syntax while silently dropping semantic contracts, magic number purposes, and inferred invariants. By forcing a two-step process (understand → document → translate), the methodology creates a checkpoint where lost information becomes visible before translation, not after.

Persistent State as a First-Class Concern

Every migration lives in five YAML files in migration_workspace/:

migration_workspace/
├── migration-state.yaml             ← Session entry point. Read this first, always.
├── asset-inventory.yaml             ← Every source file, its migration strategy, its status
├── ecosystem-map.yaml               ← Every library/type/idiom mapped to target equivalent
├── ipo-registry.yaml                ← Every function: inputs, process steps, outputs
└── retrospective-checklist.yaml     ← Lessons learned from every P4/P5 fix

These files are the migration's "memory." Any AI agent — Claude Code, Cursor, GitHub Copilot, OpenCode — can pick up a migration mid-session by reading migration-state.yaml. The state is not in the AI's context window; it's on disk.

This makes migrations resumable, auditable, and transferable. A migration started in one tool can be continued in another. A migration interrupted by a context collapse can be resumed exactly where it stopped.

The State Machine

# migration-state.yaml (excerpt)
phases:
  P0_bootstrap:     DONE
  P1_asset_scan:    DONE
  P2_ecosystem_map: IN_PROGRESS
  P3_ipo_analysis:  TODO
  P4_translation:   TODO
  P5_verification:  TODO

current_task:
  phase: P2_ecosystem_map
  item_id: "numpy.random.default_rng"
  status: BLOCKED
  block_reason: "RNG algorithm differs (Mersenne Twister vs PCG64); bit-identical output impossible"
  human_input_required: |
    Statistical equivalence sufficient, or is bit-identical seed behavior required?

When status: BLOCKED, the AI stops immediately, presents the structured block to the operator, and waits. It does not proceed, does not label-and-continue, does not silently substitute a guess.

The Ecosystem Map: Type-System Contracts Across Languages

Before any translation begins, every library symbol, type, and stdlib function used in the source must be mapped to its target equivalent, classified by equivalence type, and — critically — annotated with evidence that the mapping was actually researched.

- id: "numpy.random.default_rng"
  source_semantics: "PCG64 PRNG, seedable, reproducible across platforms"
  target_equivalent: "math/rand/v2.New(rand.NewPCG(seed, 0))"
  equivalence_type: structural
  precision_delta: none
  gap_notes: "Go 1.22+ rand/v2 uses PCG; pre-1.22 uses different algorithm"
  confirmation_evidence:
    source_behavior:  "NumPy default_rng uses PCG64 with 128-bit state since NumPy 1.17"
    target_behavior:  "math/rand/v2 PCG source: identical algorithm, same output for same seed"
    verified_from:    "numpy.org/doc/stable/reference/random/generator.html + pkg.go.dev/math/rand/v2"

The confirmation_evidence block is mandatory for every CONFIRMED mapping. An empty evidence field is treated as NEEDS_REVIEW regardless of the status field. This prevents the common failure mode where an AI confirms hundreds of mappings without looking any of them up.

Language Pairs

The methodology ships with 14 pre-built language pair modules covering common migration paths. Each module contains:

• Pre-mapped standard library and ecosystem symbols
• Known semantic gaps and their compensation strategies
• Language-specific anti-patterns to avoid during translation
• Testing toolchain mapping
• CI/CD adaptation templates

| Sou