windowsfy

windowsfy

扫描 Node.js 项目，查找 package.json 脚本中仅适用于 Unix、会在 Windows 原生 shell（CMD 和 PowerShell 5.1）中失败的写法，然后在用户确认后应用可移植的修复。每个问题都可以采用推荐的跨平台方式（使用 cross-env、shx、glob）修复，也可以使用特定 shell 的备用写法（CMD、PowerShell 或 Bash 系原生语法）。

类别

类别	描述	参考
native-dep	需要 MS BuildTools 的 C++ 扩展包（tfjs-node、better-sqlite3）。	native-deps
inline-env	CMD 和 PowerShell 不支持 KEY=val node … 前缀。	inline-env-vars
single-quote	CMD 会将单引号按原样传递——--message 'text' 会出错。	single-quotes
unix-cmd	Windows shell 不支持 rm -rf、chmod、cp -r、mv、mkdir -p。	unix-commands
glob-expand	CMD/PS 不会展开 **/*.test.ts；二进制程序会收到原样字符串。	glob-patterns
ps5-ampamp	PowerShell 5.1 在交互模式下不支持 &&（但 npm 脚本仍可正常运行）。	powershell-5-operator

平台要求（严格）

此技能仅在 Windows 原生 shell 中运行：

• 支持：cmd.exe、powershell.exe（PS 5.1）、pwsh.exe（PS 7+）。
• 禁止：Linux、macOS、WSL、Git Bash / MSYS2 / Cygwin、mintty。

被禁止的环境本身已提供 POSIX shell 语义——troubleshooting/windows/commons.md 中的脚本可在这些环境中正确执行，因此运行 windowsfy 只会添加不必要的 devDependencies，或应用实际上并不需要的 shell 专用备用写法。没有可覆盖此限制的标志。

调用

/windowsfy [path]

• [path] 可以是目录、单个 package.json，也可以省略。
• 省略 → ./（当前工作目录，递归扫描）。
• 目录 → 从该目录开始递归扫描。
• package.json 文件 → 仅扫描该文件。
• 其他情况（路径不存在、文件不是 package.json）→ 中止并显示明确的错误。

步骤 0 — 环境检查（每次都要最先运行）

解析路径之前，运行：

node <skill-dir>/scripts/scan.mjs --check-env --json

解析 JSON 对象：{"env":"...","allowed":true|false,"reason":"..."}。

• 如果 allowed === false：打印检测到的 env 和 reason，然后停止。不要解析路径。不要调用扫描器。不要编辑文件。
• 如果 allowed === true：继续步骤 1。

扫描器也会在其他每种模式下于内部运行 detectEnv()，因此即使跳过此步骤，--root/--file 也会以状态码 2 退出并输出 stderr 消息。

步骤 0b — 询问用户使用哪种交互式 Shell

环境检查通过后，使用 AskUserQuestion 询问用户当前使用哪种 Shell。提供三个选项，不要自动检测：

1. CMD（cmd.exe）
2. Windows PowerShell 5.x（powershell.exe）—— Windows 10 和 11 上的默认选项
3. PowerShell 7+（pwsh.exe）

将答案存储为 $SHELL_CHOICE，取值为 cmd、ps5 或 ps7。后续每次调用 scan.mjs 时，都通过 --shell $SHELL_CHOICE 传入该值。

该选项决定以下两项：

1. 扫描器中的严重程度矩阵 — 仅当选项为 ps5 时，ps5-ampamp 才报告为 info；当选项为 cmd 或 ps7 时则静默处理，因为这两种环境都原生支持 &&。无论选项为何，其他所有类别均为 error，因为 Windows 上的 npm 默认通过 cmd.exe 启动脚本——即使用户的交互式 Shell 是 PowerShell，脚本运行时使用的仍是 CMD。
2. 步骤 6 中的回退选项排序 — 与 $SHELL_CHOICE 匹配的回退选项排在第二位（紧跟跨平台选项之后），并突出显示为自然的替代方案。

各 Shell 的严重程度矩阵

类别	cmd	ps5	ps7
native-dep	info	info	info
inline-env	error	error	error
single-quote	error	error	error
unix-cmd	error	error	error
glob-expand	error	error	error
ps5-ampamp	静默	info	静默

步骤 1 — 参数处理

1. 从用户的调用中提取 [path]。如果为空，则视为 ./。

2. 转换为绝对路径。使用 Bash 搭配 realpath，或使用 node -e "console.log(require('path').resolve(...))"。

3. 对路径进行分类：

   if [ -d "$P" ]; then echo dir
   elif [ -f "$P" ]; then echo file
   else echo missing
   fi
   

4. 应用以下处理（始终包含 --shell $SHELL_CHOICE）：

   • dir → node <skill-dir>/scripts/scan.mjs --root <abs-path> --shell $SHELL_CHOICE --json。
   • file → 文件名必须为 package.json。运行 node <skill-dir>/scripts/scan.mjs --file <abs-path> --shell $SHELL_CHOICE --json。
   • missing → 输出 windowsfy: path not found: <input> 并停止。

步骤 2 — 检测到的模式

#	类别	在 Windows 上的问题	严重程度
1	native-dep	带有 C++ 插件的包需要安装 MS BuildTools 才能安装（@tensorflow/tfjs-node、better-sqlite3、@huggingface/transformers、@xenova/transformers）。	info
2	inline-env	KEY=val node … — Windows 会将 KEY=val 视为命令名称。	error
3	single-quote	--message 'text' — CMD 会原样传递单引号。	error
4	unix-cmd	rm -rf、chmod、cp -r、mv、mkdir -p — Windows 上不存在这些命令。	error
5	glob-expand	tests/**/*.test.ts — CMD/PS 不会展开 glob；程序收到的是原始字符串。	error
6	ps5-ampamp	在 PS 5.1 中使用 && 会抛出 ParserError: The token '&&' is not a valid statement separator。	info

步骤 3 — 检测工作流

1. 按 category 对扫描器 --json 输出中的发现项进行分组。
2. 构建汇总表：Category | Files affected | Severity。
3. 向用户打印汇总信息。
4. 对发现项数量为零的类别，跳过后续步骤。

Step 4 — 确认要修复的类别

使用 AskUserQuestion 询问用户想修复哪些类别。事先说明：

• native-dep（信息）→ 按照 references/native-deps.md 中的步骤手动安装 winget。不编辑 package.json。
• ps5-ampamp（信息）→ 安装 PowerShell 7。默认不编辑 package.json（另有仅适用于 PS 的备用方案）。
• 所有其他类别 → 可自动修复。

Step 5 — 选择修复方式

针对用户在第 4 步确认的类别，全局询问要采用哪种修复方式（单次 AskUserQuestion）。根据 $SHELL_CHOICE 的值排列选项，确保与用户所用 Shell 匹配的备用方案排在第二位：

$SHELL_CHOICE	选项顺序
cmd	1. 跨平台 · 2. CMD 备用方案 · 3. PowerShell 备用方案 · 4. 按发现项分别选择
ps5 或 ps7	1. 跨平台 · 2. PowerShell 备用方案 · 3. CMD 备用方案 · 4. 按发现项分别选择

选项描述：

1. 跨平台（推荐） — cross-env、shx、glob。适用于所有环境；会添加 devDependencies。
2. CMD 备用方案 — cmd /V:ON /C "set KEY=val & node …"、rmdir /S /Q。脚本将仅适用于 CMD。
3. PowerShell 备用方案 — $env:KEY='val'; node …、Remove-Item -Recurse -Force。脚本将仅适用于 PS。
4. 按发现项分别选择 — 针对每个发现项单独询问。

有意省略 Windows 原生环境下的 Bash 系备用方案（在这里没有意义——用户运行的是 CMD 或 PowerShell）。如果某个类别没有备用方案（例如 CMD 中的 glob-expand、chmod），则对此类别静默改用跨平台方案，并在输出中注明。

Step 6 — 修复方式选项表

#	类别	跨平台（首选）	CMD 备用方案	PowerShell 备用方案	Bash 系备用方案
2	inline-env	cross-env KEY=val node …	cmd /V:ON /C "set KEY=val & node …"	$env:KEY='val'; node …	保留 KEY=val node …
3	single-quote	转义 \"…\"	转义 \"…\"（CMD 要求如此）	保留 '…' 或转义	保留 '…'
4a	unix-cmd（rm -rf）	shx rm -rf folder	rmdir /S /Q folder	Remove-Item -Recurse -Force folder	保留 rm -rf folder
4b	unix-cmd（chmod）	shx chmod 755 file（在 Win 上无操作）	无原生命令等效项 — 改用跨平台方案	无原生命令等效项 — 改用跨平台方案	保留 chmod 755 file
5	glob-expand	dir（Node 22+）或 glob -c "…" "…**"	无备用方案 — 改用跨平台方案	无备用方案 — 改用跨平台方案	无备用方案 — 改用跨平台方案
6	ps5-ampamp	安装 PS 7（手动）	不适用 — && 在 CMD 中可用	PS 5.1：cmd1; if ($?) { cmd2 }	不适用 — && 可用

每个类别的完整差异和边缘情况见 references/<topic>.md。

Step 7 — 应用修复

对于每个受影响的 package.json，按以下顺序修复各类别，以避免重新排版已修改的字符串：

1. unix-cmd
2. inline-env
3. single-quote
4. glob-expand

规则：

• 使用 Edit，每个脚本值只进行一次有针对性的编辑。不要重写整个文件。
• 如果选择了跨平台方式，且编辑引入了新工具，则在对应 package.json 所在目录中运行 npm install --save-dev <pkg>，但仅限于该工具尚未列入 dependencies/devDependencies 的情况：
  • inline-env 跨平台方案 → cross-env
  • unix-cmd 跨平台方案 → shx
  • glob-expand 选项 B → glob
• Shell 专用备用方案不会添加 devDependency。

第 8 步 — 验证

使用相同的路径/模式（--root 或 --file）重新运行扫描器。已修复的类别不应再出现。剩余的发现很可能是误报（例如，sed 被 unix-cmd 匹配）；请将其交由人工审核。

直接使用检测脚本

node scan.mjs --check-env [--json]
node scan.mjs [--root <dir> | --file <path/to/package.json>] [--shell <cmd|ps5|ps7>] [--json]

--shell 默认为 cmd（最严格）。无效值会以代码 64 退出。

退出代码：

• 0 成功 / 环境允许
• 2 环境不是 Windows 原生环境，或未找到路径
• 64 CLI 参数无效

人类可读的输出格式：

<rel-path>/package.json:<script-name>: [category] <snippet>
<rel-path>/package.json: [native-dep] @tensorflow/tfjs-node

JSON 输出：{file, script, category, severity, snippet, fix} 数组（使用 --check-env 时则为 env 对象）。

示例差异

• examples/cross-env-before-after.json
• examples/shx-rm-rf-before-after.json
• examples/shx-chmod-before-after.json
• examples/single-quotes-before-after.json
• examples/glob-directory-before-after.json
• examples/native-deps-flag.json

警告和边缘情况

• 在 Windows 上，shx chmod 不会执行任何操作，也不会报错。 Windows 文件系统没有可执行位。如果 Linux CI/部署需要可执行位，请改用通过 process.platform 进行条件判断的 Node 脚本，并调用 fs.chmodSync。
• @tensorflow/tfjs-node 在 Windows 上需要 Node 24。 根据 troubleshooting/windows/commons.md，Node 22 不受支持。迁移说明：https://nodejs.org/en/blog/migrations/v22-to-v24
• package.json 中的 && 在 PS 5.1 下无法自动修复。 扫描器将其标记为 info，而非 error。不要将 && 改写为 ;——这会导致 Unix 执行失败。PS 锁定式改写（cmd1; if ($?) { cmd2 }）仅作为备用方案。
• 误报。 sed、包含单引号的 URL，以及有意仅用于 Unix 的脚本。--json 的 snippet 字段允许用户在应用修复前取消选择相关发现。
• cross-env 双重包装保护。 如果 cross-env 出现在 KEY=value 标记之前，扫描器会跳过该值。链式命令 && cross-env KEY=val node … 会被识别为已处理。
• 锁定 Shell 的备用方案会改变可移植性。 如果用户选择 CMD 或 PS 备用方案，package.json 就会绑定到该 Shell——脚本在其他 Shell 中将无法运行。建议在项目 README 中说明所选的 Shell。
• 混合风格的项目。 除非用户明确选择“per-finding”，否则避免在同一个 package.json 中混用主要风格和备用风格。
• 环境检查不支持覆盖。 此技能无法通过强制手段在 Linux、macOS、WSL、Git Bash、MSYS2 或 Cygwin 上运行。如需在这些环境中操作，请通过 references/*.md 手动应用差异。
• 在 Windows 上，npm 的 script-shell 默认值为 cmd.exe。 即使用户在第 0b 步选择了 ps5 或 ps7，single-quote 和 unix-cmd 仍会标记为 error——这些错误发生在脚本运行时（即 npm run 启动的 cmd.exe 中），而非交互式 Shell 中。受 Shell 选择影响的唯一类别是 ps5-ampamp：对于 cmd 和原生支持 && 的 ps7，该类别不会报错。执行过 npm config set script-shell powershell.exe（这种情况并不常见）的用户会看到不同的运行时行为；此技能不会检测这一设置。