ps-ops-kit · Windows PowerShell 自动化避坑集

AI 助手 / 开发者在 Windows + PowerShell 环境跑自动化任务的实战避坑手册与可执行资产。 所有结论均来自真实踩坑 + 本机（Windows 11 · PowerShell 5.1）实测验证。

为什么有这个东西

AI 助手（Claude/OpenClaw 等）默认用 bash 心智模型执行命令，但 Windows 默认 shell 是 PowerShell： \" 转义、&&、curl -d、grep 这些 bash 习惯在 PowerShell 里全部不通用， 而且 PowerShell 5.1 存在官方承认的原生参数传递 bug（内嵌引号传给外部程序会被破坏）。 于是大量任务时间浪费在「转义 → 报错 → 换写法 → 再报错」上。

本仓库把这些问题系统化：根因 → 正确解法 → 可复制命令 → 封装函数。

问题索引（速查表）

#	问题	一句话解法	详情
1	curl 是 Invoke-WebRequest 别名	用 curl.exe，或直接 Invoke-RestMethod	01-quoting-escape
2	JSON 传给 curl.exe 转义地狱	首选 Invoke-RestMethod -Body (ConvertTo-Json)；必须 curl 时用 --data-binary @file	01-quoting-escape
3	单引号包 JSON 一定安全？错（PS 5.1 参数传递 bug）	见上；实测 curl.exe -d '{"a":1}' 在 5.1 上坏	01-quoting-escape
4	$ 在双引号内被当变量展开	单引号 / here-string @'...'@ / --%	01-quoting-escape
5	{} | ; 裸写被解析	不裸写 JSON；写脚本文件执行	01-quoting-escape
6	&& 不可用	PS 5.1 用 ; 或 if ($LASTEXITCODE -eq 0)	01-quoting-escape
7	多进程/容器套娃引号	写脚本文件传进去执行，不拼命令行	01-quoting-escape
8	Set-Content 写中文乱码（GBK）	-Encoding UTF8；PS 5.1 脚本文件要 UTF-8 带 BOM	02-encoding
9	控制台/管道乱码、rich 进度条崩	[Console]::OutputEncoding + PYTHONIOENCODING=utf-8	02-encoding
10	bash 命令不存在（grep/ls/cat…）	对照表：Select-String/Get-ChildItem/Get-Content	03-command-mapping
11	非交互 SSH 不加载 .bashrc	bash -lc / BASH_ENV / SendEnv+AcceptEnv	04-ssh-remote
12	setx 改环境变量当前进程不生效	$env:VAR=... 同步当前会话	05-process-env
13	进程名带空格杀不掉	Get-Process | Where-Object Name -match	05-process-env
14	huggingface/PyPI 网络问题	HF_ENDPOINT=https://hf-mirror.com；发布走官方源	06-network-mirror
15	聊天传 token 被脱敏	凭据走本地文件，不进聊天	06-network-mirror
16	长任务假死/超时	后台运行 + 日志文件 + 轮询	05-process-env
17	Ollama keep_alive:"-1" 报 400	传整数 -1 或带单位 "5m"	07-ollama-tools
18	配置改了不生效（热加载假象）	改完重启服务/进程	05-process-env

快速开始

PowerShell 模块

Import-Module .\module\SafeShell.psm1 -Force

# 安全 POST JSON
Invoke-Json -Uri http://localhost:11434/api/generate -Body @{model="llama3"; input="test"}

# 安全设环境变量（当前会话 + 持久化）
Set-PersistEnv -Name OLLAMA_HOST -Value "127.0.0.1:11434"

# UTF-8 写文件
Write-Utf8 -Path script.ps1 -Text '# 中文注释' -WithBom

# 按正则匹配进程
Get-ProcLike -Pattern "ollama"
Stop-ProcLike -Pattern "ollama" -WhatIf

Python CLI 工具

cd tools/psfix
pip install -e .

# 跑诊断（JSON 输出给 AI Agent）
python -m psfix.cli doctor --json

# 翻译 bash 命令
python -m psfix.cli sanitize "grep -r TODO src/"

# 加固 PS profile
python -m psfix.cli install

可执行资产

资产	说明
module/SafeShell.psm1	PS 模块：Invoke-Json、Write-Utf8、Get/Stop-ProcLike、Set/Get-PersistEnv、ConvertTo-Utf8Bom
tools/psfix/	Python CLI：doctor(诊断)、sanitize(翻译)、curl/setx(安全包装)
scripts/profile-hardening.ps1	一键加固 PS profile：删 curl 别名、设 UTF-8、加 alias
scripts/utf8-bom-convert.py	.ps1/.psm1/.psd1 批量转 UTF-8 BOM
tests/SafeShell.Tests.ps1	Pester 自动化测试（26 条断言）
tests/compare-json-post.ps1	四种 JSON POST 对比（实测 A/C/D 通过，B 失败）
tests/verify-safeshell.ps1	SafeShell 函数冒烟
.github/workflows/ci.yml	CI：PS 5.1 + 7 矩阵 + Python 测试

测试

# 1. 安装 Pester（需要 4.10 或更高版本）
Install-Module -Name Pester -MinimumVersion 4.10 -Force -Scope CurrentUser -SkipPublisherCheck

# 2. 运行 PowerShell Pester 测试
Import-Module Pester -Force
Invoke-Pester tests/SafeShell.Tests.ps1 -Output Detailed

# 3. 运行 Python 测试
cd tools/psfix
pip install -e ".[dev]"
pytest tests/ -v

实测环境

• Windows 11 · PowerShell 5.1（原生参数传递 bug 存在，主测环境）+ PowerShell 7（CI 覆盖）

License

Apache-2.0