review-powershell

技能：审查 PowerShell

目的

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

---

核心目标

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

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

1. ✅ 仅限 PowerShell 范围：只审查 PowerShell 语言和运行时约定；不执行范围选择、安全分析或架构分析
2. ✅ 覆盖 PowerShell 的全部七个维度：在相关时评估高级函数/cmdlet 约定、参数设计/验证、错误处理语义、对象管道行为、状态/作用域/严格性、兼容性/可移植性以及可测试性
3. ✅ 符合发现格式：每条发现都包含 findings-list §5.1 要求的所有元素，类别为 language-powershell
4. ✅ 文件:行号引用：所有发现都引用带行号的具体文件位置
5. ✅ 排除非 PowerShell 代码：除非明确纳入范围，否则不根据 PowerShell 专属规则分析非 PowerShell 文件

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

---

范围边界

此技能负责：

• [CmdletBinding()]、Verb-Noun 命名、已批准的动词、begin/process/end 块
• 参数类型、Mandatory、ValueFromPipeline、参数集、验证特性
• 终止错误与非终止错误、-ErrorAction Stop、防止静默失败
• 对象管道行为（优先使用对象而非格式化文本、Write-Host 与 Write-Verbose）
• 状态、作用域、严格性（全局/有状态副作用、首选项变量变更）
• Windows PowerShell 5.1 与 PowerShell 7+ 的兼容性和可移植性
• 性能和可测试性（便于使用 Pester 测试的函数设计、依赖注入切入点）

此技能不负责：

• 范围选择——范围由调用方提供
• 安全分析——使用 review-security
• 架构分析——使用 review-architecture
• 完整的编排式审查——使用 orchestrate-code-review

交接点：输出所有 PowerShell 发现后，交由 orchestrate-code-review 汇总。对于安全问题（例如命令注入、凭据暴露），请记录问题并建议使用 review-security。

---

使用场景

• 编排式审查：当 orchestrate-code-review 按照范围 -> 语言 -> 框架 -> 库 -> 认知的流程审查 PowerShell 项目时，作为语言步骤使用。
• 仅限 PowerShell 的审查：用户只要求检查语言/运行时约定时使用。
• PR 前脚本质量检查：合并前验证参数契约、管道行为和错误语义。

使用时机：待审查代码为 PowerShell（.ps1、.psm1、.psd1），且任务涉及语言/运行时质量时使用。审查范围由调用方或用户确定。

---

行为

此技能的范围

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

审查清单（仅限 PowerShell 维度）

1. 高级函数和 cmdlet 约定：在适当情况下使用 [CmdletBinding()]，采用经批准的动词进行 Verb-Noun 命名，并且仅在需要时使用 begin/process/end 块。
2. 参数设计与验证：参数类型、Mandatory、ValueFromPipeline、参数集和验证属性（ValidateSet、ValidatePattern、ValidateScript）应协调一致，不能互相矛盾。
3. 错误处理语义：区分终止错误和非终止错误；在必要时使用 -ErrorAction Stop；避免静默失败和空的 catch。
4. 对象管道行为：内部处理优先使用对象，而不是格式化文本；避免使用 Write-Host 输出数据；确保函数输出可预测且适用于管道。
5. 状态、作用域和严格性：避免非预期的全局／有状态副作用、不受控地更改首选项变量以及含义模糊的变量初始化；在适当情况下使用严格模式。
6. 兼容性与可移植性：考虑 Windows PowerShell 5.1 与 PowerShell 7+ 之间的差异、特定平台的命令／模块以及路径处理。
7. 性能与可测试性：避免低效使用管道和重复拼接数组；以便于使用 Pester 测试并隔离依赖的方式构建函数。

语气与参考资料

• 专业且技术性：引用具体位置（文件:行号）。输出的每条发现都必须包含 findings-list §5.1 要求的所有要素。

---

输入与输出

输入

• 代码范围：用户或范围技能已选定的文件、目录或差异。此技能不负责确定范围；它仅审查所提供 PowerShell 代码的语言约定。

输出

• 按 specs/findings-list.md 中定义的格式，输出零条或多条 发现，并将 Category 设为 language-powershell。
• 此技能的类别为 language-powershell。

---

限制

硬性边界

• 不要执行安全、架构或范围选择审查。仅关注 PowerShell 语言和运行时约定。
• 不要在没有具体位置或可执行建议的情况下给出结论。
• 除非明确纳入范围，否则不要针对 PowerShell 特定规则审查非 PowerShell 代码。

技能边界

不要执行以下事项（由其他技能处理）：

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

何时停止并移交：

• 输出所有 PowerShell 发现后，移交给 orchestrate-code-review 进行汇总
• 用户需要完整审查（范围 + 语言 + 认知）时，将其转交给 orchestrate-code-review
• 发现安全问题（凭据泄露、命令注入）时，注明问题并建议使用 review-security

---

自检

核心成功标准

• 仅限 PowerShell 范围：仅审查 PowerShell 语言和运行时约定；不进行范围选择、安全或架构分析
• 涵盖 PowerShell 的全部七个维度：在相关情况下，评估高级函数/cmdlet 约定、参数设计/验证、错误处理语义、对象管道行为、状态/作用域/严格性、兼容性/可移植性和可测试性
• 符合发现项格式：每条发现项都包含 发现项列表 §5.1 要求的全部要素，且类别为 language-powershell
• 文件:行号引用：所有发现项都引用带行号的具体文件位置
• 排除非 PowerShell 代码：除非明确纳入范围，否则不依据 PowerShell 特定规则分析非 PowerShell 文件

流程质量检查

• 是否仅审查了 PowerShell 语言/运行时维度（未涉及范围/安全/架构）？
• 是否在相关情况下涵盖了函数/参数约定、错误处理、管道行为、兼容性和可测试性？
• 每条发现项是否都包含 发现项列表 §5.1 要求的全部要素，且 category=language-powershell？
• 问题是否均以文件:行号的形式引用？

验收测试

输出是否包含一份以 PowerShell 为重点的发现项列表，带有文件:行号引用，并涵盖所有相关语言/运行时维度，且未进行安全、架构或范围分析？

---

示例

示例 1：管道契约不匹配

• 输入：函数声称支持管道输入，却未声明 ValueFromPipeline，并且只在 end 中处理完整数组。
• 预期：针对管道契约不匹配提出一条发现项，并建议使用参数属性和 process。类别 = language-powershell。

示例 2：错误处理

• 输入：脚本使用 try/catch 包裹可能出错的命令，却未设置 -ErrorAction Stop，因此非终止错误会绕过 catch。
• 预期：针对无效的错误处理提出一条发现项；建议显式启用终止行为。类别 = language-powershell。

边缘情况：数据输出被主机写入污染

• 输入：函数返回对象，但也在处理循环中使用 Write-Host。
• 预期：针对混合呈现输出和数据输出提出一条发现项，指出这会损害自动化和可组合性；建议使用 Write-Verbose/Write-Information 输出诊断信息，并为管道使用者提供纯净的对象输出。