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编码环境（简单命令）
```bash
# 基本格式
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编码文件
```bash
# 使用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编码文件
```bash
ssh user@host "powershell -Command \"Get-Content 'config.yaml' -Encoding UTF8\""
```

### 方案4：执行多行PowerShell脚本
```bash
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：实用函数封装
```bash
# 保存为 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
```bash
# 创建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：安装软件包
```bash
# 安装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：系统信息检查
```bash
ssh_ps_utf8 "hp@192.168.0.111" "Get-ComputerInfo | Select-Object WindowsProductName, WindowsVersion, OsHardwareAbstractionLayer | Format-List"
```

## 故障排除

### 问题1：base64命令不可用
**解决方案**：使用Python替代
```bash
# 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
```bash
ssh user@host "powershell -Command \"\$PSVersionTable.PSVersion\""
# 如果版本低于5.1，考虑升级
```

### 问题3：SSH连接超时
**解决方案**：增加超时时间
```bash
ssh -o ConnectTimeout=30 -o ServerAliveInterval=60 user@host "command"
```

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

## 相关资源
- [PowerShell编码设置文档](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_character_encoding)
- [Windows代码页说明](https://learn.microsoft.com/en-us/windows/win32/intl/code-page-identifiers)
- [SSH配置选项](https://man.openbsd.org/ssh_config)

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