Linux 上全绿、Windows 上挂 8 项：让 6 号机在合并前拦住代理的代码（中英切换）

Same three-person team as before. Machines 1, 2 and 3 are Macs and Linux boxes whose Claude Code and Codex sessions open a dozen-plus PRs a day. Machine 6 is the team's only Windows box, and most days nobody sits in front of it.

Picture a typical Monday. An agent on machine 1 submits a PR: log rotation for the internal CLI, a snapshot test on the side, and a change to the build script in package.json to NODE_ENV=production node scripts/build.mjs. Green locally, green on Linux CI, reviewed on machine 4, merged. On Wednesday a teammate on Chinese-locale Windows pulls, and the very first command fails with 'NODE_ENV' is not recognized as an internal or external command. He works around it and hits UnicodeDecodeError: 'gbk' codec can't decode. Reproducing on machine 6, the log-rotation step throws PermissionError: [WinError 32]. Three errors, one PR, but by now twenty-odd more PRs have landed on main, and nobody remembers which agent on which machine wrote it.

My position: Windows validation has to be a hard gate before merge, in two layers. The first runs on Linux in under a minute and uses static checks to reject code that will obviously break. The second has machine 6 actually run the tests, and machine 6 must be configured like your teammates' and users' Windows, rather than tuned into a CI box where everything goes smoothly. Both results feed one gate job, and the ruleset requires only that one.

Every conclusion here comes from a reproducible experiment. I wrote a small project seeded with ten Windows-incompatible patterns agents commonly produce, plus three file names Windows cannot check out. I ran it on GitHub Actions on ubuntu-latest and windows-latest, then again on Windows with Python 3.13 and 3.15. Then I wrote a fixed version and a set of checks you can drop into a repo. What ran on real machines and what was simulated is itemized at the end.

The experiment: same code, 10/10 on Ubuntu, 8 failures on Windows

Each row is something an agent will plausibly write, and that looks flawless on Mac and Linux. Some of the raw errors from Windows:

C2  path: 'D:\\D:\\a\\pages\\pages\\lab\\before\\config.json'
C3  'NODE_ENV' is not recognized as an internal or external command,
C4  pattern arrived with literal quotes: 'src/**/*.js'
C7  UnicodeDecodeError: 'charmap' codec can't decode byte 0x81 in position 34
C9  - dist/index.txt
    + dist\index.txt
C10 PermissionError: [WinError 32] The process cannot access the file because
    it is being used by another process: '...\\agent.log'
T1  error: invalid path 'snapshots/run-2026-10-21T10:00.json'
    fatal: unable to checkout working tree

Two results did not match my expectations, and they matter more than the failures.

First, rm -rf dist passed on windows-latest. GitHub's Windows image puts Git's bundled Unix tools on PATH, so cmd.exe finds rm. Your teammates' Windows may not: by default the Git for Windows installer only adds git itself to PATH. The hosted runner installs a lot for convenience, which makes it more forgiving than a real user's machine.

Second, the CRLF bash script also passed on Windows, because Git Bash tolerates a trailing \r. The same checked-out file copied into a Docker image or run under WSL is another story. On Linux I cloned the same repo with core.autocrlf=true and the script died on the spot with set: pipefail\r: invalid option name; even my own test harness run-checks.sh died with syntax error: unexpected end of file. A check that only looks at native Windows cannot see cross-environment breakage like this.

Together these two are why machine 6 is worth keeping: the hosted runner catches most of the problems, but its configuration differs from your users', and the rest fall exactly into those differences.

Why it breaks: four root causes

A dozen symptoms come down to four root causes. Knowing the cause tells you which ones static checks can stop and which only show up when the code runs.

Line endings: each machine decides, because the repo said nothing

The Windows runner's environment output contains this line: file:C:/Program Files/Git/etc/gitconfig true. That is Git for Windows' system-level default, core.autocrlf=true: convert to LF on commit, to CRLF on checkout. The blob in the repo is LF; in the working tree every line gains a \r.

git ls-files --eol shows it plainly. Same checkout, the file before and after the fix:

i/lf    w/crlf  attr/                       lab/before/scripts/release.sh
i/lf    w/lf    attr/text=auto eol=lf       lab/after/scripts/release.sh

i/ is the repo, w/ is the working tree, attr/ is whether the repo expressed an opinion. For the first file the repo said nothing, so each machine's autocrlf decides. For the second the repo says eol=lf, and every machine checks it out as LF. autocrlf lives on each person's computer; .gitattributes is committed to the repo and wins.

AI agents make this messier. Claude Code's issue tracker has several reports this year: the Edit tool on Windows converting untouched lines from CRLF to LF (#62713), and an agent using sed -i that silently changed line endings, broke an XML manifest and cost four hours of debugging (#63715). The second reporter also noted that the platform instructions already warn about this and the model does not consistently follow them. With different agents and different tools on three dev machines, line-ending rules have to live in the repo; you cannot count on each agent to behave.

The fix is a .gitattributes, followed once by git add --renormalize . to normalize existing files:

.gitattributes

# 仓库里一律存 LF；工作区也一律 LF，不管谁的 core.autocrlf 是什么
* text=auto eol=lf
# 只给 Windows 原生脚本 CRLF
*.ps1 text eol=crlf
*.cmd text eol=crlf
*.bat text eol=crlf
# 二进制别碰
*.png binary
*.jpg binary
*.zip binary

.ps1, .cmd and .bat get CRLF on their own lines because they only run on Windows anyway, and cmd.exe has known problems with goto labels under LF. Some Windows-native toolchains (Delphi project files, for example) also require CRLF; list them by extension the same way.

Encoding: before Python 3.15, open() follows the system

open(path) without encoding uses the system locale encoding. Linux and Mac are nearly always UTF-8, so the dev machines never notice. windows-latest is an English system with code page 1252, and in my experiment it raised 'charmap' codec can't decode byte 0x81. Chinese Windows uses code page 936, which is GBK. I had no Chinese Windows at hand, so I generated a zh_CN.GBK locale on Linux and reproduced the same mechanism; it raised the 'gbk' codec can't decode the teammate in the opening saw.

There is one new development. Python 3.15 shipped on October 9 and, per PEP 686, made UTF-8 the default encoding. In the experiment, the same broken code on Windows under 3.15 passed C7 and C8. That does not make the problem go away: you do not decide when your users and teammates upgrade to 3.15. What it really means is that whether the same bug shows up depends on the Python version on the user's machine. Machine 6 has to run the version users actually run, and the code still needs encoding="utf-8".

Static checks catch most of these: ruff's PLW1514 rule flags open() calls without encoding. I hit a trap running it: with plain --select PLW1514, ruff 0.17 printed Selection PLW1514 has no effect because preview is not enabled and then reported that everything passed. It only actually checks with --preview.

Paths and the shell: npm uses cmd.exe on Windows

The next three are the most common in Node projects. On Windows npm runs scripts with cmd.exe by default; in the experiment npm config get script-shell printed null, the default. cmd.exe does not understand the VAR=value command prefix and does not treat single quotes as quotes, so 'src/**/*.js' reaches the program with the quotes attached.

new URL('../config.json', import.meta.url).pathname gives /home/.../config.json on Linux and /D:/a/.../config.json on Windows, which Node then resolves to D:\D:\a\.... The correct call is fileURLToPath(). The Python counterpart is comparing str(path) in tests: on Windows str(Path("dist") / "index.txt") is dist\index.txt.

The file system: locks, reserved names, case

The remaining items have nothing to do with code style; the file system itself behaves differently.

On Windows a file that is open cannot be renamed or deleted. The experiment's log-rotation function calls os.replace while its FileHandler is still open: fine on Linux, WinError 32 on Windows. Static checks basically cannot catch this; only running the code can.

Three kinds of file names can be committed freely on Linux and cause trouble on Windows. I built a repo on Linux containing snapshots/run-2026-10-21T10:00.json (agents love naming snapshots with ISO timestamps), tools/aux.py, and docs/README.md alongside docs/readme.md, then cloned it on Windows. The colon file made the whole checkout fail: fatal: unable to checkout working tree, clone exited 128, not a single file in the working tree, and git status showed all four files as deleted. In a separate test, the case pair checked out, but only one file survived, and git status permanently shows M docs/README.md. Mac's default APFS is case-insensitive too, so this one bites Mac dev machines as well.

Why agent-written code breaks this way more often

People make these mistakes too, but three traits of agents raise the odds.

An agent validates on whatever machine it runs on. It writes code on a Mac, runs the tests, sees green, and considers itself done. It has no reason to think about Windows unless a check on the PR stops it.

POSIX idioms dominate agents' training data. rm -rf, VAR=value cmd and open(path) are what come most naturally, and they are exactly what never fails on Linux.

Speed amplifies the cost of finding out late. Three people merging twenty or thirty PRs a day who discover a Windows problem two days later have to bisect through forty or fifty commits. Caught before merge, the cost is one more round for that agent; caught after, it is half a day of a person's time.

Writing Windows rules into AGENTS.md does help, and the kit includes a version, but the issue above already shows that a written rule is not a rule followed every time. Rules lower the error rate; the check is what actually stops the PR.

The solution: two layers of checks, one gate

Layer one: a portability check on Linux

scripts/win-portability-check.py looks only at files tracked by git, needs no Windows, and finishes in under a second. It checks five kinds of problems: file names (reserved names, illegal characters, trailing dots and spaces, over-long paths), paths differing only in case, line-ending attributes, package.json scripts that only work under a POSIX shell, and URL.pathname and string-concatenated paths in JS. It prints GitHub Actions annotations, so problems are marked directly on the PR's files. Run against the unfixed project, the real output is (the script prints Chinese; translated here):

::error file=config.json::no eol attribute: line endings on checkout depend on each machine's core.autocrlf. Add '* text=auto eol=lf' to .gitattributes
::error file=scripts/release.sh::shell script lacks eol=lf; checked out as CRLF on Windows, bash fails with $'\r': command not found
::error file=package.json::scripts.clean = 'rm -rf dist && mkdir dist': POSIX commands; npm runs scripts with cmd.exe on Windows
::error file=package.json::scripts.stamp = 'NODE_ENV=production node scripts/stamp.mjs': the VAR=value prefix is sh syntax; cmd.exe does not understand it
::error file=package.json::scripts.lint = "node scripts/count.mjs 'src/**/*.js'": single quotes are not quotes in cmd.exe and reach the program verbatim
::error file=scripts/build.mjs,line=3::URL.pathname is /C:/... on Windows; use fileURLToPath()

On the fixed version it prints win-portability-check: OK. On the repo with the colon, aux.py and the case collision, it reports all three. Together with ruff's PLW1514, static checks catch ten of the thirteen problems early. What they miss are the str(Path) comparison, the file lock and console output encoding, which only show up when the code runs on Windows.

The value of this layer is that it is cheap and fast. It runs on Linux and does not occupy machine 6; it marks the exact line, so an agent can read the annotation and fix it without waiting for a person.

Layer two: configure machine 6 like your users' computers

Register machine 6 as a self-hosted runner for the repo with the label m6. Run this script once on machine 6 in an elevated PowerShell:

scripts/setup-m6-runner.ps1

<#
在 6 号机（Windows）上用管理员 PowerShell 跑一次，把它注册成本仓库的自建 runner。
Token 在 仓库 Settings → Actions → Runners → New self-hosted runner 页面里拿，一小时内有效。
用法：.\setup-m6-runner.ps1 -Repo https://github.com/OWNER/REPO -Token XXXXX
#>
param(
  [Parameter(Mandatory)][string]$Repo,
  [Parameter(Mandatory)][string]$Token,
  [string]$Dir = 'C:\actions-runner'   # 短路径：工作目录越深，越早撞上 260 字符
)
$ErrorActionPreference = 'Stop'

# 1. 让 git 的行为和组员的 Windows 一样。Git for Windows 安装器默认 autocrlf=true；
#    用 --system 是因为服务账户读不到你个人的 ~/.gitconfig。
git config --system core.autocrlf true
# 长路径保持默认（关）：组员的机器没开，6 号机开了就会把问题藏起来。
Write-Host "core.longpaths =" (git config --system --get core.longpaths)

# 2. 代码页：中文 Windows 是 936（GBK）。65001 说明开了"Beta: 使用 UTF-8 提供全球语言支持"，
#    那样 open() 不写 encoding 的 bug 在这台机器上就测不出来。
$acp = (Get-ItemProperty 'HKLM:\SYSTEM\CurrentControlSet\Control\Nls\CodePage').ACP
Write-Host "ANSI code page = $acp"
if ($acp -ne '936') { Write-Warning "ACP 不是 936。若你的用户主要是中文 Windows，请在 区域 → 管理 → 更改系统区域设置 里改成中文(简体)，并取消 UTF-8 beta。" }

# 3. 下载并注册 runner（标签 m6、win-verify，以服务方式运行）
$tag = (Invoke-RestMethod https://api.github.com/repos/actions/runner/releases/latest).tag_name
$ver = $tag.TrimStart('v')
New-Item -ItemType Directory -Force -Path $Dir | Out-Null
Set-Location $Dir
$zip = "actions-runner-win-x64-$ver.zip"
Invoke-WebRequest "https://github.com/actions/runner/releases/download/$tag/$zip" -OutFile $zip
Expand-Archive $zip -DestinationPath . -Force
.\config.cmd --unattended --url $Repo --token $Token --name m6 --labels 'm6,win-verify' --work _work --runasservice
Write-Host "完成。去仓库 Settings → Actions → Runners 确认 m6 显示为 Idle。"

Every setting in the script answers the same question: how does this machine differ from users' machines, and which class of bug would that difference hide?

core.autocrlf is set to true because that is the Git for Windows default your teammates have, and machine 6 should check out the same way. It is written with --system because the runner runs as a service account and cannot read your personal ~/.gitconfig. Long-path support stays off for the same reason: your teammates do not have it enabled, and if machine 6 did, paths over 260 characters would go untested.

The code page should be 936. Windows has a "Beta: Use Unicode UTF-8 for worldwide language support" option; turn it on and the code page becomes 65001, and the open()-without-encoding bug disappears on that machine. Most users do not turn that option on.

The runner lives in C:\actions-runner, a short path that leaves characters to spare for the working directory.

Here is the workflow: three jobs, and only the last one is required. It assumes the repo has .nvmrc, .python-version and requirements-dev.txt to pin the Node and Python versions users actually run; if not, put concrete version numbers in.

.github/workflows/win-verify.yml

name: win-verify
on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
  merge_group:
permissions:
  contents: read
concurrency:
  group: win-verify-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true
jobs:
  # 第一道：Linux 上 1 分钟以内，挡掉不用跑也知道会炸的
  portability-lint:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@v4
      - run: python3 scripts/win-portability-check.py
      - name: open() 没写 encoding（PLW1514 目前要 --preview 才生效）
        run: pipx run ruff check --preview --select PLW1514 --output-format github .

  # 第二道：6 号机真跑。草稿 PR 不占 6 号机
  windows-m6:
    needs: portability-lint
    if: github.event_name == 'merge_group' || github.event.pull_request.draft == false
    runs-on: [self-hosted, Windows, m6]
    timeout-minutes: 30
    defaults:
      run:
        shell: pwsh
    steps:
      - name: 清掉上一轮残留的进程（它们会锁住工作区里的文件）
        run: |
          $work = Split-Path $env:GITHUB_WORKSPACE -Parent
          Get-CimInstance Win32_Process -Filter "Name='node.exe' OR Name='python.exe'" |
            Where-Object { $_.CommandLine -like "*$work*" } |
            ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }
      - uses: actions/checkout@v4
        with:
          clean: true
      - name: 记录这台机器的真实环境（排查时第一眼要看的）
        run: |
          git config --show-origin --get-all core.autocrlf
          python -c "import locale,sys; print(sys.version.split()[0], locale.getencoding(), sys.stdout.encoding)"
          node -p "process.version"
          git ls-files --eol | Select-String 'w/crlf' | Select-Object -First 20
      - uses: actions/setup-node@v4
        with:
          node-version-file: .nvmrc
      - uses: actions/setup-python@v5
        with:
          python-version-file: .python-version
      - run: npm ci
      - run: npm test
      # 故意不设 PYTHONUTF8：6 号机要像用户的电脑，不像一台被调教过的 CI
      - run: python -m pip install -r requirements-dev.txt
      - run: python -m pytest -q

  # 规则集里只把这一个设成 required check
  gate:
    if: always()
    needs: [portability-lint, windows-m6]
    runs-on: ubuntu-latest
    steps:
      - env:
          LINT: ${{ needs.portability-lint.result }}
          WIN: ${{ needs.windows-m6.result }}
          DRAFT: ${{ github.event.pull_request.draft }}
        run: |
          echo "portability-lint=$LINT windows-m6=$WIN draft=$DRAFT"
          [ "$LINT" = success ] || exit 1
          # 草稿 PR 允许跳过 Windows；其余情况 skipped 一律当失败
          if [ "$WIN" = success ]; then exit 0; fi
          if [ "$WIN" = skipped ] && [ "$DRAFT" = true ]; then exit 0; fi
          exit 1

Three details are there on purpose.

gate is the only required check. GitHub's documentation is explicit: a job skipped by a condition reports Success and does not block merging even if it is a required check. If you required windows-m6 directly and an if condition skipped it, the PR could still merge; and when layer one fails, windows-m6, which depends on it, is skipped too. gate uses if: always() so it always runs, and treats skipped as failure, with draft PRs as the only exception. I ran all five combinations locally: both lint and Windows succeed, it passes; Windows skipped on a non-draft PR, it blocks; on a draft, it passes; lint fails, it blocks; Windows fails, it blocks.

Do not add a paths filter to this workflow. When the whole workflow does not trigger because of a path filter, the required check sits at "Waiting for status to be reported" and the PR can never merge. It is the opposite trap from the previous one, and you have to avoid both.

Kill leftover processes at the start of every run. A hosted runner is a fresh VM each time; a self-hosted one is not. If the previous run left a node.exe behind, the files it locks make the next run's checkout fail while cleaning the workspace, and you get a red X that has nothing to do with the code. The workflow's first step finds those processes by the workspace path in their command line and kills them.

Finally, make gate required in a ruleset. The kit's ruleset-require-gate.json can be created directly with gh api repos/OWNER/REPO/rulesets -X POST --input ruleset-require-gate.json; integration_id: 15368 is the GitHub Actions app ID, which ensures only Actions can report that status.

Layer three: rules for the agents

The kit's AGENTS.windows.md is a block you can paste into AGENTS.md or CLAUDE.md, covering each failure above. Its job is to get the agent to write it right the first time and save one round of bouncing. It does not replace the first two layers.

Costs, and when this does not fit

There is only one machine 6, so it queues. Three people, twenty or thirty PRs a day, tests under five minutes: one machine is enough. If the tests take half an hour, machine 6 becomes the new bottleneck. Then you can run windows-m6 only after a PR is approved, or put the fast tests on hosted windows-latest and keep the full suite for machine 6.

Hosted Windows runners are cleaner, but cost money and do not look like your users. Hosted runners are free on public repos; on private repos you pay per minute beyond the free quota, and on GitHub's current price list Windows is $0.010 a minute against $0.006 for Linux. A hosted runner is a fresh machine every time, with no leftover processes or locked files, but it is an English system with rm on PATH and Python encoding cp1252. If your users are mostly on Chinese Windows, being unable to catch GBK bugs is reason enough to keep machine 6.

On a public repo, never let fork PRs run on machine 6. A self-hosted runner executes whatever code the PR contains. For a private repo with three members the risk is manageable; once the repo goes public, PRs from forks must not reach machine 6.

The static check has false positives. The single-quote rule flags some legitimate cases, such as an argument passed to node's -e. I wrote the rule table for common cases; change it if it does not suit your project. It is a script of just over 100 lines and easy to edit.

If nobody runs your code on Windows, do not build machine 6. For a service that only runs in Docker on Linux servers, the .gitattributes line is still worth adding, because a teammate on Windows copying a CRLF script into the image breaks it just the same. Machine 6 and the rest of this workflow would be superfluous.

Five things you can do tomorrow

1. Add .gitattributes (the one above) at the repo root, then git add --renormalize . && git commit -m "normalize line endings". Ten minutes, the biggest payoff.
2. Put scripts/win-portability-check.py in the repo and run it once on main to see how many problems already exist. Then run ruff check --preview --select PLW1514 ., and remember the --preview.
3. Run setup-m6-runner.ps1 on machine 6. Look at the code page it prints first; if it is not 936, change the system locale before anything else.
4. Add win-verify.yml and make only gate required in the ruleset. Open a deliberately broken PR and confirm it is actually blocked; open a draft PR and confirm it does not occupy machine 6.
5. Paste AGENTS.windows.md into your agents' rules file.

The whole set (check script, workflow, runner install script, ruleset, agent rules, plus the experiment's before and after projects and test harness) is packed here: win-verify-kit.tar.gz.

What ran and what did not

Ran on real machines: the before and after projects on GitHub Actions ubuntu-latest and windows-latest, and on Windows again with Python 3.13 and 3.15 separately; the repo with the colon, reserved name and case collision was really cloned on Windows. Every Windows error in this post is copied verbatim from those runs' logs.

Simulated on Linux: the CRLF script failing under bash came from cloning with core.autocrlf=true and running on Linux; the GBK decode failure came from a zh_CN.GBK locale generated on Linux. The mechanism is the same as on Chinese Windows, but it did not run on Chinese Windows.

Only statically validated, not run on a real machine 6: win-verify.yml passes actionlint, and the gate decision logic was run locally for five combinations; setup-m6-runner.ps1 was syntax-checked with the PowerShell 7.6 parser but has not registered a runner on real Windows; the leftover-process cleanup step has not been verified against a real locked-file scenario. The check scripts and test harness pass shellcheck.

My position stands: stop Windows problems before merge, because after merge every one of them has to be traced back through dozens of agent commits. The cheapest step is that .gitattributes line, which you can add today; the most valuable one is configuring machine 6 like your users' machines and letting gate guard the merge button for you.