Win 转 Linux 开发环境 — Intent Router

What this skill is

This file is a thin wrapper: an intent-recognition and routing layer
that sends the user's request to the correct deterministic pipeline. It
contains ONLY routing and judgment logic.

• Deterministic operations (probe, install, configure, undo) live in
  scripts/ — execute them, do not reimplement them.
• Judgment support (decision trees, compatibility matrices,
  troubleshooting playbooks, user-facing templates) lives in
  references/ — load the listed document when the route says so.

The skill's purpose: move the user's development pipeline from
PowerShell into a standard Linux environment — with local WSL as the
default provider — atomically, reversibly, and without fighting the
desktop client's own sandbox.

Two governing principles (read before routing)

Principle 1 — Respect the client's sandbox (execution planes)

Every command runs on exactly one of three planes:

If the client's sandbox blocks a Plane H/L command (e.g. wsl.exe on a
program blacklist): STOP. Never bypass — no alternate shell, no
encoded command, no copying binaries. Surface the block to the user and
offer the manual path. Full rules R1–R6, conflict analysis, and the
hand-off message template: load references/sandbox_coexistence.md.

Principle 2 — WSL is one Linux provider, not the only one

The user's goal is a standard Linux environment. WSL is the default
local provider (zero infrastructure), but an existing SSH remote VM
or dev container is an equally valid target. When detection reports
linuxProviders.hasNonWslProvider=true and WSL is absent, do NOT
install WSL by default — ask the user whether to keep the remote
provider or add local WSL. Provider selection rules P1–P5 and the
per-provider differences: load references/linux_environment_providers.md.

Intent recognition

Identify the intent from the user's message. Signals are examples, not
an exhaustive list — judge by meaning.

Judgment rules:
1. Explicit provider mention beats everything (rule P1): "用我的远程
服务器" → provider = SSH remote; adapt-only pipelines, skip install.
2. State unknown → INT-DETECT first. Detection is read-only and
cheap; never install on a guess.
3. Compound requests run in canonical order:
INT-DETECT → INT-INSTALL → INT-INIT → INT-EXPLORER → INT-ADAPT.
INT-ROLLBACK and INT-REPAIR are always standalone.
4. Ambiguous after detection → present the recommendation summary
and ask the user (Chinese). Never infer consent for Plane H.

Pipelines (routing table)

Each pipeline lists: steps → verification. Script details and decision
trees: references/agent_execution_guide.md.

P-DETECT (INT-DETECT)

1. Run scripts/detect_env.ps1 (no admin) → parse the single JSON stdout.
2. Interpret with references/detection_guide.md; honor
   recommendation.wslQueryBlocked and providerHint.
3. Report to the user in Chinese (template: references/onboarding_flow.md).

Verify: valid JSON, schemaVersion present, recommendation fields populated.

P-INSTALL (INT-INSTALL) — Plane H, elevated

1. Fresh detection (reuse if < 15 min old). Apply Principle 2 first:
   if providerHint is set, ASK before installing.
2. scripts/install_wsl.ps1 -DryRun → review the plan JSON.
3. scripts/install_wsl.ps1 (elevated). If needsReboot=true: tell the
   user in Chinese; steps auto-resume at next logon (or -Resume).
4. Re-run detection to confirm the state transition.

Verify: final JSON success=true; state.jsonl contains
distro-install succeeded; detection shows the distro.

P-INIT (INT-INIT) — Plane L

1. Confirm the distro exists (detection or wsl -l -q).
2. Get-Content -Raw scripts/init_wsl_env.sh | wsl -d <distro> -- bash -s
3. Spot-check: wsl -d <distro> -- bash -lc "node -v; python3 --version; git --version".

Verify: stdout JSON success=true; ~/.win-to-linux-dev/manifest.json exists.

P-EXPLORER (INT-EXPLORER)

1. scripts/create_explorer_shortcuts.ps1 -Distro <distro>.
2. Optionally open Explorer at the resolved wslHome for visual proof.

Verify: JSON shortcutsCreated > 0; wslHome non-empty.

P-ADAPT (INT-ADAPT)

1. Choose provider (Principle 2, rule P1). WSL is the default; for an
   explicit remote choice use -Provider ssh-remote -SshHost <host> or
   -Provider devcontainer — the adapter then installs the matching
   remote extension and skips all WSL-specific config.
2. scripts/setup_ai_client.ps1 -Provider <provider> -Distro <distro>
   (no admin). For the WSL provider this also generates a filled
   WSL-Dev-<distro>.code-workspace on the Desktop — hand it to the user
   as the one-click IDE-to-WSL entry point (Chinese template:
   references/onboarding_flow.md). The workspace-file template is
   inlined in the adapter (no .code-workspace asset is bundled, since
   some platforms filter non-standard file types). Adapter internals:
   references/ai_client_adapter.md.

Verify: stdout JSON provider matches the choice; adapter.json
records provider (rule P5); for WSL: IDE settings.json contains the
WSL terminal profile AND workspaceFile is non-null; CLI wrappers exist
for detected CLI clients.

P-ROLLBACK (INT-ROLLBACK) — Plane H where flagged

1. scripts/rollback.ps1 -DryRun → show the plan JSON to the user.
2. On consent: scripts/rollback.ps1 -SkipConfirmation
   (-RemoveDistro / -RemoveWSLFeatures ONLY if the user explicitly
   approved those destructive scopes).

Verify: JSON executed list; failed empty; re-run detection if a
distro was removed.

P-REPAIR (INT-REPAIR)

1. Run detection; read wsl.queryBlocked, blockedActionHint,
   providerHint, plus state.jsonl for the last failed step.
2. Match the symptom in references/troubleshooting.md; apply the fix
   or hand off per Principle 1.
3. Re-run detection to confirm recovery.

Verify: symptom's acceptance check in the troubleshooting playbook.

Result verification contract

Applies to every pipeline — use these before declaring success:
1. stdout JSON: every script emits exactly ONE JSON document; check
success and any error code. Nothing else is on stdout.
2. Event stream: state.jsonl (Windows: %USERPROFILE%\.win-to-linux-dev\;
WSL: ~/.win-to-linux-dev/) — one JSON event per line
{ts, step, status, level, detail}; the last event for each step
must be succeeded or an explained skipped.
3. State re-probe: for state-changing pipelines, re-run
detect_env.ps1 and diff the relevant fields.
4. Language: report outcomes to the user in Chinese; keep all
machine-facing artifacts (JSON, logs, manifests) in English.

Troubleshooting (route first, details in references)

Resource map

scripts/ — deterministic operations (execute, never reimplement)

references/ — judgment support (load per route)

assets/ — templates handed to the user (never loaded into context)

The IDE-to-WSL workspace-file template is inlined inside
setup_ai_client.ps1 (no .code-workspace asset is bundled, since some
platforms filter non-standard file types).