skills/ssh-windows-encoding/SKILL.md

Skill: ssh-windows-encoding

技能概述

解决Windows SSH连接中的中文编码和PowerShell语法问题，特别是处理中文内容、here-string语法错误和文件传输编码问题。

触发规则

当遇到以下情况时使用此技能：

• SSH连接到Windows系统出现中文乱码
• PowerShell命令包含中文或特殊字符失败
• here-string语法在SSH中解析错误
• 需要传输包含中文的文件到Windows系统

问题诊断

常见症状

1. 中文乱码：'�������ı���'
2. 语法错误：here-string ����������β֮ǰ�����������κ��ַ���
3. 文件编码错误：创建的文件内容乱码

根本原因

• SSH客户端默认使用UTF-8编码
• Windows PowerShell默认使用GBK编码（代码页936）
• here-string语法在SSH命令中解析异常

解决方案

方案1：设置PowerShell编码环境（简单命令）

# 基本格式
ssh user@windows-host "powershell -Command \"[System.Console]::OutputEncoding = [System.Text.Encoding]::UTF8; Your-Command\""

# 示例：显示中文
ssh hp@192.168.0.111 "powershell -Command \"[System.Console]::OutputEncoding = [System.Text.Encoding]::UTF8; Write-Host '中文测试成功！'\""

方案2：创建UTF-8编码文件

# 使用base64传输文件内容
content='# 配置文件
app:
  name: 测试应用
  version: 1.0.0'

encoded=$(echo "$content" | base64 -w 0)
ssh user@host "powershell -Command \"[System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String('$encoded')) | Out-File -FilePath 'config.yaml' -Encoding UTF8\""

方案3：读取UTF-8编码文件

ssh user@host "powershell -Command \"Get-Content 'config.yaml' -Encoding UTF8\""

方案4：执行多行PowerShell脚本

script='Write-Host "第一行"
Write-Host "第二行"
Get-Date'

encoded=$(echo "$script" | base64 -w 0)
ssh user@host "powershell -Command \"[System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String('$encoded')) | Invoke-Expression\""

方案5：实用函数封装

# 保存为 ssh-win-helper.sh
ssh_ps_utf8() {
    local host="$1"
    local command="$2"
    ssh "$host" "powershell -Command \"[System.Console]::OutputEncoding = [System.Text.Encoding]::UTF8; [System.Console]::InputEncoding = [System.Text.Encoding]::UTF8; $command\""
}

ssh_create_file_utf8() {
    local host="$1"
    local filepath="$2"
    local content="$3"
    local encoded=$(echo "$content" | base64 -w 0)
    ssh "$host" "powershell -Command \"[System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String('$encoded')) | Out-File -FilePath '$filepath' -Encoding UTF8\""
}

ssh_read_file_utf8() {
    local host="$1"
    local filepath="$2"
    ssh "$host" "powershell -Command \"Get-Content '$filepath' -Encoding UTF8\""
}

使用示例

示例1：配置MicroClaw

# 创建MicroClaw配置文件
config_content='# MicroClaw 基础配置
app:
  data_dir: ./microclaw.data
  timezone: Asia/Shanghai
model:
  provider: anthropic
  api_key: ${ANTHROPIC_API_KEY}
  model: claude-sonnet-4-5-20250929'

ssh_create_file_utf8 "hp@192.168.0.111" "microclaw.config.yaml" "$config_content"

# 验证配置文件
ssh_read_file_utf8 "hp@192.168.0.111" "microclaw.config.yaml"

示例2：安装软件包

# 安装Chocolatey（Windows包管理器）
install_script='Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString("https://community.chocolatey.org/install.ps1"))'

encoded=$(echo "$install_script" | base64 -w 0)
ssh hp@192.168.0.111 "powershell -Command \"[System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String('$encoded')) | Invoke-Expression\""

示例3：系统信息检查

ssh_ps_utf8 "hp@192.168.0.111" "Get-ComputerInfo | Select-Object WindowsProductName, WindowsVersion, OsHardwareAbstractionLayer | Format-List"

故障排除

问题1：base64命令不可用

解决方案：使用Python替代

# Linux/Mac
encoded=$(echo "内容" | base64 -w 0)

# 通用方案（使用Python）
encoded=$(python3 -c "import base64, sys; print(base64.b64encode(sys.stdin.buffer.read()).decode())" <<< "内容")

问题2：PowerShell版本过低

解决方案：检查并升级PowerShell

ssh user@host "powershell -Command \"\$PSVersionTable.PSVersion\""
# 如果版本低于5.1，考虑升级

问题3：SSH连接超时

解决方案：增加超时时间

ssh -o ConnectTimeout=30 -o ServerAliveInterval=60 user@host "command"

最佳实践

1. 始终指定编码：在PowerShell命令中明确使用-Encoding UTF8
2. 测试简单命令：先用简单中文命令测试编码设置
3. 使用base64传输：对于复杂内容或脚本，使用base64编码传输
4. 验证文件内容：创建文件后立即读取验证
5. 记录成功案例：将有效的命令模式保存为模板

相关资源

• PowerShell编码设置文档
• Windows代码页说明
• SSH配置选项

---

技能创建时间：2026-02-18 适用环境：Windows 10/11 + OpenSSH + PowerShell 5.1+ 已验证方案：✅ 生产环境可用