WSL Runner 三层验证体系Orca 如何测试 W1–W3 的 Windows/WSL 执行边界【免费下载链接】orcaOrca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.项目地址: https://gitcode.com/GitHub_Trending/orca48/orcaW1–W3 是 Orca面向并行 Agent 舰队的多平台 ADE在 Windows 上打通 WSL 调用链的三层改造W1 收敛所有 WSL 调用只经过同一个 spawn 入口、W2 负责 Windows 子进程的所有权与清理、W3 将在 WSL 发行版里运行程序收敛为唯一一个 runner即 wsl-runner.ts。围绕这套改造Orca 在 wsl-runner-verification.md 中沉淀了一套单元测试 静态守卫ratchet 真二进制测试的三层验证体系因为每一层都能捕获其它层在结构上无法捕获的问题。读完本文你将掌握 Orca 为这条跨进程边界设计的完整回归防线每个测试套件盯住什么、每条守卫如何做到只降不升、真实的 ConPTY 与真实 WSL 发行版测试如何运行以及守卫自身已知的盲区该如何应对。为什么是三层一次 WSL 调用在结构上容易漏掉的三种错误src/main/wsl/wsl-runner.ts 的文件头注释写得很直白Orca 在 WSL 内运行程序的唯一地点而每次调用都有五件事需要决定——分隔符--execvs--、shell、stdout 围栏fencing、WSLENV、payload 传输方式——这五件事每一项都曾以错误形态发布过对应缺陷号 #12964、#14288 / #9768 / #9725、#11327、#12557、#14292。而 wsl-w1-w3-contract.test.ts 的注释进一步点明三层验证的由来一次 WSL 调用 一次 Windows spawn 一个子进程W1–W3 各自修复了同一次调用的一个层面失败会叠加因此必须组合验证。换句话说单元测试能在纯逻辑层面逐条锁定契约守卫ratchet能在仓库尺度上持续拦截新写的违规代码而只有真二进制测试才能在真实 Windows 进程树与真实发行版上断言那些模拟永远无法给出的结论。这就是文档第一句三种覆盖层次因为每一种都能捕获其它层在结构上无法捕获的东西的含义。第一层单元测试——每次 PR、所有平台都跑套件钉死的内容Pinssrc/main/wsl/wsl-runner.test.ts分隔符、lane 选择、fencing、WSLENV、guest cwd、脚本解释器、预算拆分、拒绝未解析的 PATHsrc/main/wsl/wsl-guest-environment.test.tsburst 坍缩、按发行版隔离、畸形 payload 拒绝、transient 与 permanent 区分、重试窗口、joiner 预算src/main/wsl/wsl-w1-w3-contract.test.tsW1→W3 链端到端绝对路径wsl.exe、argv 数组、有界调用、不使用--、脚本字节级一致、WSLENV、探测 lane 不跑 shell、login PATH 仍被应用src/shared/source-scan/source-tree-scan.test.ts守卫辅助函数guard helpers。一个漏报的守卫比没有更糟这套件划分体现了责任边界runner 的决策正确性每调用五件事怎么选由wsl-runner.test.ts负责guest 环境的缓存与容错语义由wsl-guest-environment.test.ts负责而 W1–W3 是横切整个调用链的契约所以单设wsl-w1-w3-contract.test.ts做端到端断言。从源码看 runner 测试锁住的四个关键决策打开 src/main/wsl/wsl-runner.ts 可以看到这四个Pins分别对应真实的防御代码分隔符与 argv 数组。runner 永远用buildWslExecArgs拼出wsl.exe ... --exec形态测试则断言args是数组、a b这样的带空格参数原样保留wsl-w1-w3-contract.test.ts。注释写明命令字符串会把引号责任交回给调用方这正是 W1 想消灭的整类问题。不使用--。契约测试不是简单断言没有--而是检查wsl.exe自身分隔符的位置——因为sh -s --中属于 guest shell 的--是合法 end-of-optionswsl-w1-w3-contract.test.ts对应仓库里独立的 wsl-exec-mode-separator.test.ts。原因在源码注释--会让$name之类在宿主机侧先被展开。脚本字节级一致。曾经存在 base64 eval 包装因为宿主机 shell 会重新解析引号#14292现在脚本原样进入 argv、stdin 留给命令本身wsl-w1-w3-contract.test.ts。测试用的 payload 同时包含单引号嵌套与case语法这类历史雷区。探测 lane 不跑 shell但 login PATH 仍被应用。探测 lane 必须无 shell否则~/.profile里一行sleep就能吃掉整个超时即 #14288可 nvm 这类装在用户 PATH 里的二进制又必须找得到#9725、#7563、#8366。于是代码用env二进制做PATH... HOME... program前缀wsl-runner.ts测试同时断言argv 中不含_orca_wsl_shell且包含PATH/home/u/.nvm/bin:/usr/binwsl-w1-w3-contract.test.ts。从源码看 guest 环境测试锁住的缓存语义src/main/wsl/wsl-guest-environment.ts 是整个登录环境探测与缓存的实现单元测试锁定的每条语义都能在源码里找到对应物畸形 payload 拒绝探测脚本以 NUL 分隔输出PATH\0HOME\0env三个值解析器要求三个都是干净的绝对路径以/开头、无换行、PATH 不超 32768 字节否则判定探测失败wsl-guest-environment.ts。transient vs permanentexit 127找不到可用 env才是永久性拒绝超时、非 0 但非 127 的退出码、甚至无法解析的 payload 都被归类为 transient——因为畸形 payload 通常只是 chatty 的 rc 文件在 64 KiB 输出上限处截断了围栏会自行恢复wsl-guest-environment.ts。两类重试窗口transient 失败 5 秒后可重试TRANSIENT_RETRY_MS 5_000permanent 拒绝则 10 分钟后才解禁REJECTED_RETRY_MS 10 * 60_000——因为apt升级窗口也会短暂表现为没有可用 env若无过期时间一次此类事件会在进程生命周期内禁掉该发行版上所有 WSL 功能wsl-guest-environment.ts。burst 坍缩与 joiner 预算inFlightMap 让同一瞬间的并发请求坍缩成一次探测joiner 不再傻等发起者用完整个预算而是与自己的budgetMs做Promise.race避免发起者耗尽预算导致 joiner 到自己命令时只剩 1mswsl-guest-environment.ts。测试还覆盖 1.5× 预算差触发重新探测、显式all标志区分刷新全部发行版与只刷默认发行版等边界wsl-guest-environment.ts。runProcess 的 rejection 必须被吞掉子进程无法启动宿主机没有System32\wsl.exe的 ENOENT、内存压力下的 EAGAIN时 runProcess 会 reject若不 catch这个 rejected promise 会一直驻留在inFlight里让进程生命周期内所有后续 WSL 调用全部抛错直到重启wsl-guest-environment.ts。值得一提的还有 runner 的预算拆分与拒绝未解析 PATH。runWslProcess把探测预算压到剩余预算的一半且上限 4 秒wsl-runner.ts防止 5 秒的调用方把 3333ms 花在探测上、只剩 1667ms 给自己缺失 login PATH 时调用照常运行于发行版默认 PATH只在WslResult.environmentResolved上如实报告falsewsl-runner.ts把装了 nvm 却查不到二进制这类问题显式暴露给调用方而不是默默吞掉。第二层守卫Ratchets——持续强制推进的球门柱单元测试只能验证被写出来的用例无法阻止未来在 runner 之外新开wsl.exe调用。第二层是仓库级的静态守卫守卫度量内容src/main/wsl/wsl-invocation-boundary.test.ts在 runner 之外产生wsl.exe的文件以及声明了shell: bash之外的 bash-only payloadsrc/shared/child-process/windows-console-visibility.test.ts缺少windowsHide的直接子进程调用src/shared/child-process/child-process-import-boundary.test.ts在 chokepoint 之外 importchild_process的文件src/shared/wsl-exec-mode-separator.test.ts被禁用的--分隔符src/main/pty-descendant-termination-job-coverage.test.ts每次进程清扫sweep都经过terminateOwnedTree守卫的底层辅助逻辑集中在 src/shared/source-scan/source-tree-scan.ts其自身由 source-tree-scan.test.ts 测试这也是为什么文档强调一个漏报的守卫比没有更糟——守卫本身是扫描器扫描器出错就会放过真违规。守卫能只降不升的机制这些守卫并非一次性审计而是可度量的门槛它们统计的违规数被固定进基线每一个守卫都会在新违规者身上失败也会在过期条目上失败守卫在修复代码后仍会指向旧记录因此计数只可能下降、不可能回升。文档特意给出验证方法种植一个违规看它是否被点名——这个步骤已经三次发现了守卫自身的 bug。失败模式保持可区分单元层同样覆盖失败必须可区分非零退出码是数据而非异常——runProcess在非零退出时正常 resolve调用方必须能看到code而不是被异常甩过wsl-w1-w3-contract.test.ts超时则显式上报timedOut: true绝不伪装成空答案wsl-w1-w3-contract.test.ts。这是探测失败 ≠ 工具不存在语义的根基调用方拿不到 PATH 时应当报无法验证而不是误报未安装。第三层真二进制测试——其它任何断言都无法给出的结论Windows CI真实 ConPTY 上的进程树验证文档指明Windows CI.github/workflows/pr.yml 中的package (windows)job会从打了补丁的源码重建 node-pty并针对真实 ConPTY 运行win32套件验证三件事一个真实脱离的孙进程detached grandchild能被创建一次真实的 Job kill能真正杀掉它反过来——一次干净的exit必须把后台工作留在原处不能误杀。这层覆盖的是 node-pty 这类原生依赖在补丁后的真实行为模拟层无法替代。仓库中相关补丁脚本可在 config/scripts/rebuild-native-deps.mjsnative 依赖重建与 config/relay-assets/node-pty-1.1.0-console-list-agent-patch.cjs 等补丁中追溯而pty-descendant-termination-job-coverage守卫则从静态侧保证清扫路径全部经过terminateOwnedTree。真实 WSL 发行版不在 CI 中必须手动跑WSL 在托管 runner 上不可用因此这层不在 CI 中需要开发者本机执行wsl-runner.wsl.test.tsORCA_REAL_WSL_RUNNER_TEST1 ORCA_WSL_TEST_DISTROUbuntu-24.04 \ pnpm vitest run src/main/wsl/wsl-runner.wsl.test.ts测试通过两个环境变量门控且仅在win32平台生效非 Windows 或未设变量时整组describe被跳过见 wsl-runner.wsl.test.ts。它做的事比看起来更危险复现 #14288而不是模拟先备份发行版的~/.profile再向其中追加一行sleep 60然后断言探测 lane 仍能在自己的预算内应答wsl-runner.wsl.test.ts——60 秒阻塞远超探测预算而调用必须带着orca-probe-ok的输出、在 20 秒内完成证明失败的探测不致命、调用走降级路径照常应答。afterAll会还原 profile 并删除备份。断言第二次调用不再支付 login shell 的开销缓存生效应快于 5 秒。banner 剥离stock Ubuntu 会把 rc 提示写进 stdout任何解析该流的代码都会把 banner 当数据读进去#11327、#11823因此断言stdout恰为ORCA_PAYLOAD。携带引号与$的脚本字节级到达payload 同时包含printf %s\n $1、单引号嵌套echo it\s fine与awk {print $1}断言三段输出逐一还原对应 #12964、#14292。WSLENV 跨边界传递宿主机env中的ORCA_WSLENV_PROBE在 guest 内原样读到crossed。guest cwd以 guestPOSIX路径进入工作目录后执行。文档对它的定位很明确在改动src/main/wsl/之前运行它——这是探测 lane 真的如工作流所宣称的那样工作的唯一证据而且它已经在 CI 全绿的情况下、因 CI 跳过它而对一次 runner 改动过期失效过一次。windowsHide 守卫的已知缺口记录而非掩盖文档专门用一节记录守卫的已知边界理由是看起来完整的守卫比一个有据可查的缺口更糟。三条缺口如下fork不被扫描。Node 运行时会把windowsHide转发给spawn但ForkOptions类型并未声明该字段因此现存两个使用位点daemon 与 plugin host 的子进程在不做类型断言cast的情况下无法修复——而这两个位点都是 Windows 上的 console-subsystem 子进程。allowlist 是文件粒度的被放行的文件等于失明。其中约 18 个条目是误报RegExp.prototype.exec、provider.exec以及 lexer 失步的文件每一条都等于给该文件里的真实回归发了一张长期预批准。这些条目无法靠修代码退役因此该清单永远无法归零——改为调用粒度call-granular才是正解。stripComments没有失步报告。失败关闭fail-closed检查作用在已剥离注释的文本上因此含/ *的正则字面量仍可能悄悄吞掉代码。目前src/中尚无实例但守卫自身无法发现这种失步。这三条记录的共同点是诚实它们既写清了影响也给出了演进方向让后来者知道当前防线到哪为止。如何验证一次守卫修改本节给出守卫开发的方法论且来自真实教训本工作流中每一个只靠读代码验证的守卫修复都是错的——连续三次对精确 lexer 的尝试每次发布的失步都降低了违规计数看起来像进步。因此必须种植违规并看着它失败。文档要求至少种植以下六种形态一次普通调用一个 template-literal 密集文件中的调用一个正则密集文件中的调用windowsHide: false三目运算符作第一参数的调用重命名过的 import。只有这六种形态全被点名才能确认守卫改动真的守住了边界而不是在 lexer 失步后自我感觉良好地通过。如何把这套验证用起来如果你在为本仓库贡献 WSL 相关改动落地顺序建议是每次提交前让第一层单元测试在本地跑通——它们无平台依赖任何环境都能运行。改动src/main/wsl/前按上文命令运行真实发行版测试需 Windows 已安装目标发行版测试会临时改动其~/.profile务必让afterAll完成还原同时留意其CI 会跳过、可能悄悄过期的教训——它过期时不会有人替你发现。改动任何 spawn/子进程代码时确保第二层守卫windowsHide、child_processimport 边界、--分隔符、terminateOwnedTree覆盖在你的 diff 上全绿并主动检查是否触碰了三个已记录缺口之一fork位点、文件粒度 allowlist、stripComments失步。守卫自身有改动时不要只读代码按上节的六种形态种植违规逐一验证。这套体系的价值在于把WSL 调用正确性从一次性人工审计变成了可持续的多层防线单元测试守住决策逻辑静态守卫守住仓库尺度的蔓延真二进制测试守住模拟永远够不到的真实进程树与真实发行版语义——而文档与源码中随处可见的缺陷号#14288、#9725、#14292……时刻提醒着这三层中的每一层背后都是一次真实到达过用户的线上故障。【免费下载链接】orcaOrca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.项目地址: https://gitcode.com/GitHub_Trending/orca48/orca创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考