Pwsh Encoding Fix

Fix PowerShell file encoding corruption (backtick, dollar sign, Chinese char mangling) when writing Node.js files on Windows.

PowerShell 文件编码修复

在 Windows PowerShell 中写入含特殊字符的 Node.js/JS 文件时，PowerShell 会破坏文件内容。此 Skill 提供诊断和修复方法。

现象

问题	表现	原因
反引号被吞	模板字符串 `hello ${name}` → "hello ${name}"	PowerShell 把 ` 当转义符
$ 变量被展开	${var} 变空字符串	PowerShell 展开 $var 变量
中文变乱码	汉字变垃圾字符（如 已查到）	UTF-8 被 GBK 重编码
文件体积暴增	13KB → 20MB	乱码字符被反复替换

根本原因

PowerShell 管道命令会修改文件编码：

# ❌ 这些命令会破坏文件：
Set-Content file.js "content"         # 吞反引号
Out-File file.js                       # 吞反引号
Get-Content | Set-Content             # 管道 → 重编码
Write-Output "`$var" > file.js        # 展开 $ 变量

使用诊断修复工具

本 Skill 附带一个可执行脚本 pwsh-encoding-fix.js，可以在任何有 Node.js 的 Windows 机器上运行：

# 诊断文件编码问题
node pwsh-encoding-fix.js <文件路径>

# 诊断并自动修复（仅 GBK 乱码可自动修复）
node pwsh-encoding-fix.js <文件路径> --fix

工具的诊断能力

严重度	检测类型	说明
!! CRITICAL	BACKTICK_LOST	模板字符串反引号被 PowerShell 吞掉
!! CRITICAL	DOLLAR_EXPANDED	${var} 变量被展开为空
!! CRITICAL	GBK_CORRUPT	中文 UTF-8 被 GBK 重编码损坏（可自动修复）
!! CRITICAL	SYNTAX_ERROR	JS 语法检查失败，可能是编码损坏导致
WW WARNING	BACKTICK_PARTIAL	部分模板可能受损
WW WARNING	GBK_CORRUPT (mild)	部分中文可能受损
II LOW	BOM	文件含 UTF-8 BOM 头（不影响运行但不够干净）

工具输出示例

========================================================
  PowerShell Encoding Damage Report
========================================================
  File:    C:\project\server.js
  Size:    17.9 KB  (408 lines)
  Backtick: 0
  Dollar{}: 15 total
  Suspicious lines: 12 / 12
  Chinese: 1257 valid / 242 GBK residual
  Syntax:  FAIL
--------------------------------------------------------
  Found 3 issue(s):

  !! [CRITICAL] BACKTICK_LOST
     12 lines use ${} without backticks. Template literals stripped.
  !! [CRITICAL] GBK_CORRUPT
     GBK residual: 242 chars / valid Chinese: 1257 (ratio 0.2)
  !! [CRITICAL] SYNTAX_ERROR
     Unexpected token ...
--------------------------------------------------------
  Critical issues found. Use --fix to attempt repair.

安全写入方法

方法 1：Node.js writeFileSync（最安全）

node -e "fs.writeFileSync('file.js', 'content', 'utf8')"

注意：-e 字符串中的 $ 仍会被 PowerShell 展开，需要用单引号包裹或转义。

方法 2：OpenClaw write 工具（推荐）

直接使用 write 工具创建文件，不走 PowerShell 管道。

方法 3：hex 编码写入（万无一失）

在干净机器上生成 hex：

node -e "const fs=require('fs');const h=fs.readFileSync('file.js').toString('hex');console.log(h)" > file.hex

在目标机器上恢复：

node -e "const fs=require('fs');fs.writeFileSync('file.js',Buffer.from(fs.readFileSync('file.hex','utf8').trim(),'hex'))"

诊断命令（手动）

# 检查语法
node --check file.js

# 检查 BOM 头（正确的文件头应是 63 6f 6e = "con"）
node -e "const fs=require('fs');const b=fs.readFileSync('file.js');console.log(b[0].toString(16),b[1].toString(16),b[2].toString(16))"

# 检查反引号数量
node -e "const fs=require('fs');const c=fs.readFileSync('file.js','utf8');const bt=String.fromCharCode(96);console.log('Backtick count:',c.split(bt).length-1)"

修复步骤

1. 不要用 PowerShell 管道修复！ 不要 Get-Content | Set-Content
2. 用 Node.js 读取原文件：fs.readFileSync('file.js', 'utf8')
3. 检查编码损坏类型（反引号缺失 / 中文乱码 / 体积暴增）
4. 如果只是中文乱码：用 --fix 模式自动修复，或用 find/replace 映射
5. 如果反引号也被吃了：必须从原始源码重写
6. 最稳妥：用 write 工具直接从原始源码完整重写

预防措施

• 用 OpenClaw write 工具代替 PowerShell 写文件
• 改完文件后立刻 node --check 验证语法
• 复杂 JS 文件用 Node.js writeFileSync 或 hex 编码写入

文件

路径	说明
SKILL.md	本文档
pwsh-encoding-fix.js	可执行诊断修复工具（Node.js脚本）

在其他机器上部署

只需将 pwsh-encoding-fix.js 拷贝到目标机器（任何 Windows 系统），确保已安装 Node.js：

# 从本目录复制到目标机器
# 然后在目标机器上运行
node pwsh-encoding-fix.js 需要检查的文件.js
node pwsh-encoding-fix.js 需要检查的文件.js --fix

无需安装任何 npm 包。GBK 修复需要 iconv-lite（自动检测，无则回退到内置 TextDecoder）。