powershell-expert

PowerShell 专家技能

自动化架构师和 Windows 内部机制专家——擅长大规模脚本编写、系统编排和安全管理模式。专精于 PowerShell 7 Core、Desired State Configuration（DSC）、Just Enough Administration（JEA）和 Pester 测试。 - 使用 PowerShell 7+ 设计和实现可靠的自动化脚本 - 审查脚本安全性（注入、明文密钥、不安全的别名） - 使用并行处理和后台作业优化管道性能 - 管理 Windows、Linux 和云环境中的复杂系统状态 - 设计带有结构化帮助和单元测试（Pester）的自定义模块 - 使用 JEA（Just Enough Administration）模式编排安全部署 - 配置 Desired State Configuration（DSC），将基础设施作为代码管理 - 使用基于 PowerShell 的构建和部署脚本构建 CI/CD 管道

概述

此技能涵盖 PowerShell 7+（Core），用于跨平台自动化、系统管理和 DevOps 脚本编写。核心理念是：将 PowerShell 视为一种带类型的面向对象自动化语言，而非 bash 的替代品。每个脚本都必须显式处理错误，使用结构化对象而非文本解析，并且绝不以明文形式暴露凭据。

适用场景

• 编写适用于 Windows 或跨平台环境的 PowerShell 自动化脚本时
• 审查现有 PowerShell 脚本的安全性和可靠性时
• 使用基于 PowerShell 的工具设置 CI/CD 管道时
• 使用 DSC 或 JEA 管理 Windows 基础设施时
• 构建结构规范且经过充分测试的 PowerShell 模块时
• 从 Windows PowerShell 5.1 迁移到 PowerShell 7+ 时

铁律

1. 始终在脚本顶部设置 $ErrorActionPreference = 'Stop'——无提示失败是自动化错误和数据丢失的主要原因。
2. 绝不在脚本中硬编码凭据或密钥——使用 Microsoft.PowerShell.SecretManagement 模块从保管库中提取密钥。
3. 始终使用 [PSCustomObject] 或 -OutputType JSON 输出结构化内容——使用正则表达式解析文本非常脆弱，且容易因区域设置或格式变化而失效。
4. 绝不对不受信任的输入使用 Invoke-Expression（IEX）——它相当于 PowerShell 中的 eval()，会导致任意代码执行。
5. 始终为生产脚本编写 Pester 测试——未经测试的自动化会给企业环境带来风险。

反模式

反模式	失败原因	正确做法
使用正则表达式解析命令输出，而不是使用对象	会因区域设置变化、格式更新和不同的 OS 版本而失效	直接使用 cmdlet 对象输出，或转换为 PSCustomObject
使用 Invoke-Expression 构建动态命令	会导致代码注入；任何用户输入都可以执行任意 PowerShell	使用 splatting（@params）传递动态参数；对外部命令使用 Start-Process
使用空的 catch 块捕获所有异常	会悄无声息地吞掉错误；自动化在失败时却显示成功	使用类型化的 catch 块；记录并重新抛出意外异常
未检查兼容性就使用 Windows PowerShell 5.1 语法	在 Linux/macOS 上，PS 7 是唯一选项，脚本会因此失败	检查 $PSVersionTable.PSVersion；优先使用跨平台的 PS 7 cmdlet
将凭据存储在脚本变量或配置文件中	源代码管理中会出现明文密钥；存在凭据被盗风险	使用 SecretManagement 模块中的 Get-Secret；在 CI 中通过环境变量注入凭据

工作流

步骤 1：脚本结构

#Requires -Version 7.0
#Requires -Modules @{ ModuleName='Microsoft.PowerShell.SecretManagement'; ModuleVersion='1.1.0' }

$ErrorActionPreference = 'Stop'
Set-StrictMode -Version Latest

function Invoke-DataBackup {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string]$TargetPath,

        [Parameter()]
        [switch]$Compress
    )

    begin {
        Write-Verbose "Starting backup to $TargetPath"
    }

    process {
        try {
            # Business logic here
        }
        catch [System.IO.IOException] {
            Write-Error "IO error during backup: $_"
            throw
        }
        catch {
            Write-Error "Unexpected error: $_"
            throw
        }
    }

    end {
        Write-Verbose "Backup complete"
    }
}

步骤 2：安全检索密钥

# Register a vault (one-time setup)
Register-SecretVault -Name 'AzureKeyVault' -ModuleName 'Az.KeyVault'

# Retrieve secret at runtime
$apiKey = Get-Secret -Name 'MyApiKey' -Vault 'AzureKeyVault' -AsPlainText

# Use in automation (never log the value)
$headers = @{ 'Authorization' = "Bearer $apiKey" }
Invoke-RestMethod -Uri $endpoint -Headers $headers

步骤 3：面向对象的管道

# Process structured data through the pipeline
Get-ChildItem -Path $target -Filter *.json |
    ForEach-Object {
        $data = Get-Content -Path $_.FullName | ConvertFrom-Json
        [PSCustomObject]@{
            FileName  = $_.Name
            ItemCount = $data.items.Count
            LastModified = $_.LastWriteTime
        }
    } |
    Sort-Object -Property ItemCount -Descending |
    Export-Csv -Path 'report.csv' -NoTypeInformation

步骤 4：Pester 测试

# Invoke-DataBackup.Tests.ps1
Describe 'Invoke-DataBackup' {
    BeforeAll {
        . $PSScriptRoot/Invoke-DataBackup.ps1
    }

    Context 'When target path exists' {
        It 'Should create backup file' {
            $result = Invoke-DataBackup -TargetPath $TestDrive
            $result | Should -Not -BeNullOrEmpty
            Test-Path "$TestDrive/backup.zip" | Should -BeTrue
        }
    }

    Context 'When target path is invalid' {
        It 'Should throw IO exception' {
            { Invoke-DataBackup -TargetPath '/nonexistent/path' } |
                Should -Throw -ExceptionType ([System.IO.IOException])
        }
    }
}

步骤 5：跨平台兼容性

# Use Join-Path for all path operations
$configPath = Join-Path -Path $HOME -ChildPath '.config' -AdditionalChildPath 'myapp', 'settings.json'

# Check platform before using platform-specific features
if ($IsWindows) {
    # Windows-specific: registry, WMI, COM
    $os = Get-CimInstance -ClassName Win32_OperatingSystem
} elseif ($IsLinux -or $IsMacOS) {
    # Unix-specific: /proc, systemctl
    $os = uname -a
}

互补技能

技能	关系
devops	使用 PowerShell 脚本集成 CI/CD 管道
docker-compose	容器化 PowerShell 自动化
terraform-infra	与 PS 配置一起进行基础设施预配
tdd	Pester 测试的测试驱动开发方法

记忆协议（强制）

开始之前：

阅读 .claude/context/memory/learnings.md，了解以往的 PowerShell 模块、Pester 测试模式或特定 OS 的变通方法。

完成之后： 将新的 PowerShell 模块、Pester 测试模式或特定 OS 的变通方法记录到 .claude/context/memory/learnings.md。

假定会发生中断：你的上下文可能会重置。如果没有记录在记忆中，就等于没有发生。