| name | pwsh |
| description | 在 Windows PowerShell 5.1 与 PowerShell 7 中编写和执行稳定命令，重点处理引号、管道符、原生命令参数传递与跨版本兼容。遇到 `--jq`/过滤表达式被 PowerShell 误解析、同一命令在 pwsh5 与 pwsh7 行为不一致、或需要为 pwsh7.3+ 增加参数传递适配时使用此 skill。 |
Pwsh
Overview
以“先兼容、后增强”为原则生成 PowerShell 命令。默认先满足 pwsh5 可运行，再按需启用 pwsh7 专属能力。
Workflow
- 确认目标解释器：先读取
$PSVersionTable.PSVersion，判断是 5.1 还是 7.x。
- 选兼容级别：默认按 pwsh5 语法生成；仅在确认 7.x 时使用 7 专属语法。
- 组装参数：优先用变量或数组传参，避免在命令行内堆叠转义。
- 处理原生命令：当参数被误解析时，先改写引号；必要时使用
--% 或 pwsh7 参数传递设置。
- 输出结果：明确命令、兼容前提、以及可能影响行为的版本差异。
Baseline Rules
- 将 pwsh5 视为最低兼容基线。
- 在 PowerShell 中向
--jq 或类似参数传入含 | 的表达式时，必须使用单引号字符串。
- 需要变量拼接时，先构造变量再传参，不在命令行直接拼复杂引号。
- 文件读写显式指定编码，避免依赖不同版本默认值。
pwsh7 Adaptation
- 仅在确认
PowerShell 7.3+ 时考虑 $PSNativeCommandArgumentPassing 影响。
- 旧脚本因参数传递行为变化失败时，按需临时切换
Legacy，任务完成后恢复原值。
- 使用 pwsh7 专属语法（如
??、||、&&、ForEach-Object -Parallel）前先做版本判断。
Failure Handling
- 出现
| 被吃掉：检查表达式是否被单引号包裹。
- 原生命令参数异常：先改为变量传参，再评估
--% 或 $PSNativeCommandArgumentPassing。
- 跨版本结果不同：回显版本号与关键变量值后，再给出兼容改写命令。
Output Format
Plan: 要解决的 PowerShell 兼容问题。Commands: 可直接执行的命令（必要时分 5.1 与 7.x 两套）。Result: 关键输出与版本信息。Compat: 是否依赖 pwsh7 特性，及回退方案。
Reference
按需加载，不要一次性读取全部细节：
- 通用兼容基线：
references/pwsh5-baseline.md
--jq 与引号规则：references/quoting-jq.md- pwsh7 增量适配：
references/pwsh7-adaptation.md
