review-powershell

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: Review PowerShell

技能：PowerShell代码审查

Purpose

用途

Review code in PowerShell for language and runtime conventions only. Do not define scope (diff vs codebase) or perform security/architecture analysis; those are handled by scope and cognitive skills. Emit a findings list in the standard format for aggregation. Focus on advanced function design, parameter validation and binding, error handling semantics, object pipeline behavior, module/export and naming conventions, compatibility (Windows PowerShell vs PowerShell 7+), and testability.

仅审查PowerShell代码是否符合语言和运行时约定。不要界定审查范围（差异对比vs全代码库），也不要执行安全/架构分析，这些由范围识别和认知技能处理。输出标准格式的问题发现列表用于汇总。重点关注高级函数设计、参数校验与绑定、错误处理语义、对象管道行为、模块/导出与命名规范、兼容性（Windows PowerShell vs PowerShell 7+）以及可测试性。

Core Objective

核心目标

Primary Goal: Produce a PowerShell language/runtime findings list covering function design, parameter contracts, error handling, pipeline behavior, state/scope, compatibility, and testability for the given code scope.

Success Criteria (ALL must be met):

✅ PowerShell-only scope: Only PowerShell language and runtime conventions are reviewed; no scope selection, security, or architecture analysis performed
✅ All seven PowerShell dimensions covered: Advanced functions/cmdlet conventions, parameter design/validation, error handling semantics, object pipeline behavior, state/scope/strictness, compatibility/portability, and testability are assessed where relevant
✅ Findings format compliant: Each finding includes Location, Category (
```
language-powershell
```
), Severity, Title, Description, and optional Suggestion
✅ File:line references: All findings reference specific file locations with line numbers
✅ Non-PowerShell code excluded: Non-PowerShell files are not analyzed for PowerShell-specific rules unless explicitly in scope

Acceptance Test: Does the output contain a PowerShell-focused findings list with file:line references covering all relevant language/runtime dimensions without performing security, architecture, or scope analysis?

首要目标：针对给定代码范围，输出覆盖函数设计、参数契约、错误处理、管道行为、状态/作用域、兼容性和可测试性的PowerShell语言/运行时问题发现列表。

成功标准（必须全部满足）：

✅ 仅审查PowerShell相关内容：仅审查PowerShell语言和运行时约定，不做范围选择、安全或架构分析
✅ 覆盖全部7个PowerShell评估维度：相关内容需评估高级函数/cmdlet约定、参数设计/校验、错误处理语义、对象管道行为、状态/作用域/严格性、兼容性/可移植性、可测试性
✅ 符合问题格式规范：每个问题包含位置、类别（
```
language-powershell
```
）、严重程度、标题、描述，以及可选的改进建议
✅ 包含文件:行号引用：所有问题都要关联具体的文件位置和行号
✅ 排除非PowerShell代码：除非明确纳入范围，否则不对非PowerShell文件执行PowerShell特定规则的分析

验收测试：输出是否包含聚焦PowerShell的问题发现列表，带有文件:行号引用，覆盖所有相关语言/运行时维度，且未执行安全、架构或范围分析？

Scope Boundaries

范围边界

This skill handles:

[CmdletBinding()]

Verb-Noun

naming, approved verbs,

begin/process/end

blocks

Parameter types,
```
Mandatory
```
,
```
ValueFromPipeline
```
, parameter sets, validation attributes
Terminating vs non-terminating errors,
```
-ErrorAction Stop
```
, silent failure prevention
Object pipeline behavior (prefer objects over formatted text,
```
Write-Host
```
vs
```
Write-Verbose
```
)
State, scope, strictness (global/stateful side effects, preference variable changes)
Windows PowerShell 5.1 vs PowerShell 7+ compatibility and portability
Performance and testability (Pester-friendly function design, DI seams)

This skill does NOT handle:

Scope selection — scope is provided by the caller
Security analysis — use
```
review-security
```
Architecture analysis — use
```
review-architecture
```
Full orchestrated review — use
```
review-code
```

Handoff point: When all PowerShell findings are emitted, hand off to

review-code

for aggregation. For security concerns (e.g. command injection, credential exposure), note them and suggest

review-security

本技能处理范围：

[CmdletBinding()]

、

Verb-Noun

命名、官方认可动词、

begin/process/end

代码块

参数类型、
```
Mandatory
```
、
```
ValueFromPipeline
```
、参数集、校验属性
终止性vs非终止性错误、
```
-ErrorAction Stop
```
、静默失败预防
对象管道行为（优先返回对象而非格式化文本，
```
Write-Host
```
vs
```
Write-Verbose
```
）
状态、作用域、严格性（全局/有状态副作用、偏好变量修改）
Windows PowerShell 5.1 与 PowerShell 7+ 的兼容性和可移植性
性能与可测试性（适配Pester的函数设计、依赖注入接缝）

本技能不处理范围：

范围选择——范围由调用方提供
安全分析——使用
```
review-security
```
技能
架构分析——使用
```
review-architecture
```
技能
全流程编排审查——使用
```
review-code
```
技能

交接节点：输出所有PowerShell相关问题后，交接给

review-code

技能做汇总。如果发现安全问题（比如命令注入、凭证泄露），标注问题并建议使用

review-security

技能。

Use Cases

使用场景

Orchestrated review: Used as the language step when review-code runs scope -> language -> framework -> library -> cognitive for PowerShell projects.
PowerShell-only review: When the user wants only language/runtime conventions checked.
Pre-PR script quality check: Validate parameter contracts, pipeline behavior, and error semantics before merge.

When to use: When the code under review is PowerShell (

.ps1

.psm1

.psd1

) and the task includes language/runtime quality. Scope is determined by the caller or user.

编排式代码审查：当review-code对PowerShell项目执行「范围->语言->框架->库->认知」全流程审查时，作为语言审查环节使用
仅PowerShell审查：用户仅需要检查语言/运行时约定时使用
PR前脚本质量检查：合并前校验参数契约、管道行为和错误语义

适用时机：待审查代码为PowerShell代码（

.ps1

、

.psm1

、

.psd1

），且任务包含语言/运行时质量检查时使用。审查范围由调用方或用户确定。

Behavior

执行逻辑

Scope of this skill

本技能的范围

Analyze: PowerShell language and runtime conventions in the given code scope (files or diff provided by the caller). Do not decide scope; accept the code range as input.
Do not: Perform scope selection, security review, or architecture review; do not review non-PowerShell files for PowerShell-specific rules unless explicitly in scope.

分析内容：基于（调用方提供的文件或差异）给定代码范围内的PowerShell语言和运行时约定。不要自行决定审查范围，直接接收传入的代码范围作为输入。
禁止行为：不要执行范围选择、安全审查或架构审查；除非明确纳入范围，否则不对非PowerShell文件执行PowerShell特定规则的审查。

Review checklist (PowerShell dimension only)

审查检查清单（仅PowerShell维度）

Advanced function and cmdlet conventions: Use
```
[CmdletBinding()]
```
where appropriate,
```
Verb-Noun
```
naming with approved verbs, and
```
begin/process/end
```
blocks only when needed.
Parameter design and validation: Parameter types,
```
Mandatory
```
,
```
ValueFromPipeline
```
, parameter sets, and validation attributes (
```
ValidateSet
```
,
```
ValidatePattern
```
,
```
ValidateScript
```
) are coherent and not contradictory.
Error handling semantics: Distinguish terminating vs non-terminating errors; use
```
-ErrorAction Stop
```
where required; avoid silent failures and empty
```
catch
```
.
Object pipeline behavior: Prefer objects over formatted text for internal flow; avoid
```
Write-Host
```
for data output; ensure function output is predictable and pipeline-safe.
State, scope, and strictness: Avoid unintended global/stateful side effects, uncontrolled preference variable changes, and ambiguous variable initialization; use strict mode where appropriate.
Compatibility and portability: Account for differences between Windows PowerShell 5.1 and PowerShell 7+, platform-specific commands/modules, and path handling.
Performance and testability: Avoid expensive pipeline misuse and repeated array concatenation; structure functions for Pester-friendly testing and dependency isolation.

高级函数和cmdlet约定：合理使用
```
[CmdletBinding()]
```
，使用带官方认可动词的
```
Verb-Noun
```
命名，仅在必要时使用
```
begin/process/end
```
代码块。
参数设计与校验：参数类型、
```
Mandatory
```
、
```
ValueFromPipeline
```
、参数集、校验属性（
```
ValidateSet
```
、
```
ValidatePattern
```
、
```
ValidateScript
```
）逻辑一致，无冲突。
错误处理语义：区分终止性和非终止性错误；必要时使用
```
-ErrorAction Stop
```
；避免静默失败和空
```
catch
```
代码块。
对象管道行为：内部流程优先返回对象而非格式化文本；不要使用
```
Write-Host
```
输出数据；确保函数输出可预测、管道安全。
状态、作用域和严格性：避免非预期的全局/有状态副作用、不受控的偏好变量修改、歧义变量初始化；合理使用严格模式。
兼容性和可移植性：考虑Windows PowerShell 5.1和PowerShell 7+的差异、平台专属命令/模块、路径处理的兼容性。
性能和可测试性：避免低效的管道误用和重复的数组拼接；函数结构要适配Pester测试和依赖隔离。

Tone and references

表述风格和引用要求

Professional and technical: Reference specific locations (file:line). Emit findings with Location, Category, Severity, Title, Description, Suggestion.

专业技术导向：引用具体位置（文件:行号）。输出的问题需要包含位置、类别、严重程度、标题、描述、改进建议。

Input & Output

输入与输出

Input

输入

Code scope: Files or directories (or diff) already selected by the user or by the scope skill. This skill does not decide scope; it reviews the provided PowerShell code for language conventions only.

代码范围：已由用户或范围识别技能筛选的文件、目录（或差异内容）。本技能不决定审查范围，仅针对提供的PowerShell代码审查语言约定。

Output

输出

Emit zero or more findings in the format defined in Appendix: Output contract.
Category for this skill is language-powershell.

输出0个或多个符合附录：输出契约定义格式的问题发现。
本技能的问题类别为language-powershell。

Restrictions

限制规则

Hard Boundaries

严格边界

Do not perform security, architecture, or scope selection. Stay within PowerShell language and runtime conventions.
Do not give conclusions without specific locations or actionable suggestions.
Do not review non-PowerShell code for PowerShell-specific rules unless explicitly in scope.

禁止执行安全、架构或范围选择工作，仅聚焦PowerShell语言和运行时约定。
禁止输出无具体位置或可落地建议的结论。
禁止除非明确纳入范围，否则不对非PowerShell代码执行PowerShell特定规则的审查。

Skill Boundaries

技能边界

Do NOT do these (other skills handle them):

Do NOT select or define the code scope — scope is determined by the caller or
```
review-code
```
Do NOT perform security analysis (credential handling, injection risks) — use
```
review-security
```
Do NOT perform architecture analysis — use
```
review-architecture
```

When to stop and hand off:

When all PowerShell findings are emitted, hand off to
```
review-code
```
for aggregation
When the user needs a full review (scope + language + cognitive), redirect to
```
review-code
```
When security concerns (credential exposure, command injection) are found, note them and suggest
```
review-security
```

禁止执行以下操作（由其他技能处理）：

不要选择或定义代码范围——范围由调用方或
```
review-code
```
技能决定
不要执行安全分析（凭证处理、注入风险）——使用
```
review-security
```
技能
不要执行架构分析——使用
```
review-architecture
```
技能

停止与交接时机：

输出所有PowerShell相关问题后，交接给
```
review-code
```
技能做汇总
用户需要全流程审查（范围+语言+认知）时，引导使用
```
review-code
```
技能
发现安全问题（凭证泄露、命令注入）时，标注问题并建议使用
```
review-security
```
技能

Self-Check

自检清单

Core Success Criteria

核心成功标准

PowerShell-only scope: Only PowerShell language and runtime conventions are reviewed; no scope selection, security, or architecture analysis performed
All seven PowerShell dimensions covered: Advanced functions/cmdlet conventions, parameter design/validation, error handling semantics, object pipeline behavior, state/scope/strictness, compatibility/portability, and testability are assessed where relevant
Findings format compliant: Each finding includes Location, Category (
```
language-powershell
```
), Severity, Title, Description, and optional Suggestion
File:line references: All findings reference specific file locations with line numbers
Non-PowerShell code excluded: Non-PowerShell files are not analyzed for PowerShell-specific rules unless explicitly in scope

仅审查PowerShell相关内容：仅审查PowerShell语言和运行时约定，不做范围选择、安全或架构分析
覆盖全部7个PowerShell评估维度：相关内容需评估高级函数/cmdlet约定、参数设计/校验、错误处理语义、对象管道行为、状态/作用域/严格性、兼容性/可移植性、可测试性
符合问题格式规范：每个问题包含位置、类别（
```
language-powershell
```
）、严重程度、标题、描述，以及可选的改进建议
包含文件:行号引用：所有问题都要关联具体的文件位置和行号
排除非PowerShell代码：除非明确纳入范围，否则不对非PowerShell文件执行PowerShell特定规则的分析

Process Quality Checks

流程质量检查

Was only the PowerShell language/runtime dimension reviewed (no scope/security/architecture)?
Are function/parameter conventions, error handling, pipeline behavior, compatibility, and testability covered where relevant?
Is each finding emitted with Location, Category=language-powershell, Severity, Title, Description, and optional Suggestion?
Are issues referenced with file:line?

是否仅审查了PowerShell语言/运行时维度（没有处理范围/安全/架构内容）？
相关内容是否覆盖了函数/参数约定、错误处理、管道行为、兼容性和可测试性？
每个输出的问题是否都包含位置、类别=language-powershell、严重程度、标题、描述，以及可选的改进建议？
问题是否都关联了文件:行号？

Acceptance Test

验收测试

Does the output contain a PowerShell-focused findings list with file:line references covering all relevant language/runtime dimensions without performing security, architecture, or scope analysis?

输出是否包含聚焦PowerShell的问题发现列表，带有文件:行号引用，覆盖所有相关语言/运行时维度，且未执行安全、架构或范围分析？

Examples

示例

Example 1: Pipeline contract mismatch

示例1：管道契约不匹配

Input: Function claims pipeline input but does not declare
```
ValueFromPipeline
```
and processes only full arrays in
```
end
```
.
Expected: Emit a finding for pipeline contract mismatch and suggest parameter attribute +
```
process
```
usage. Category = language-powershell.

输入：函数声明支持管道输入，但没有声明
```
ValueFromPipeline
```
，且仅在
```
end
```
代码块中处理完整数组。
预期输出：输出管道契约不匹配的问题，建议添加参数属性+使用
```
process
```
代码块。类别=language-powershell。

Example 2: Error handling

示例2：错误处理问题

Input: Script wraps risky command in
```
try/catch
```
but does not set
```
-ErrorAction Stop
```
, so non-terminating errors bypass
```
catch
```
.
Expected: Emit a finding for ineffective error handling; suggest explicit terminating behavior. Category = language-powershell.

输入：脚本将高风险命令包裹在
```
try/catch
```
中，但没有设置
```
-ErrorAction Stop
```
，导致非终止性错误不会被
```
catch
```
捕获。
预期输出：输出错误处理无效的问题，建议显式声明终止性行为。类别=language-powershell。

Edge case: Data output polluted by host writes

边缘案例：主机输出污染数据返回

Input: Function returns objects but also uses
```
Write-Host
```
within processing loops.
Expected: Emit finding for mixed presentation/data output that harms automation and composability; suggest
```
Write-Verbose
```
/
```
Write-Information
```
for diagnostics and clean object output for pipeline consumers.

输入：函数会返回对象，但在处理循环中使用了
```
Write-Host
```
。
预期输出：输出展示层/数据层输出混合的问题，该问题会影响自动化和可组合性；建议使用
```
Write-Verbose
```
/
```
Write-Information
```
输出诊断信息，仅返回干净的对象供管道消费者使用。

Appendix: Output contract

附录：输出契约

Each finding MUST follow the standard findings format:

Element	Requirement
Location	`path/to/file.ext` (optional line or range).
Category	`language-powershell` .
Severity	`critical` \| `major` \| `minor` \| `suggestion` .
Title	Short one-line summary.
Description	1-3 sentences.
Suggestion	Concrete fix or improvement (optional).

Example:

markdown

- **Location**: `scripts/Build.ps1:34`
- **Category**: language-powershell
- **Severity**: major
- **Title**: Function output mixes objects and host-formatted text
- **Description**: The function emits `Write-Host` output in the data path, which makes automation output unstable.
- **Suggestion**: Return structured objects only and move diagnostics to `Write-Verbose` or `Write-Information`.

每个问题必须遵循标准问题格式：

元素	要求
位置	`path/to/file.ext` （可选行号或行范围）。
类别	`language-powershell` 。
严重程度	`critical` \| `major` \| `minor` \| `suggestion` 。
标题	简短的单行摘要。
描述	1-3句话说明问题。
改进建议	具体的修复或优化方案（可选）。

示例：

markdown

- **位置**: `scripts/Build.ps1:34`
- **类别**: language-powershell
- **严重程度**: major
- **标题**: 函数输出混合了对象和主机格式化文本
- **描述**: 该函数在数据返回路径中输出`Write-Host`内容，会导致自动化输出不稳定。
- **改进建议**: 仅返回结构化对象，将诊断信息迁移到`Write-Verbose`或`Write-Information`输出。