powershell-master

PowerShell 大师

关键指南

Windows 文件路径要求

强制要求：在 Windows 上始终使用反斜杠表示文件路径

在 Windows 上使用 Edit 或 Write 工具时，必须在文件路径中使用反斜杠（\），而不是正斜杠（/）。

示例：

• 错误：D:/repos/project/file.tsx
• 正确：D:\repos\project\file.tsx

适用于：

• Edit 工具的 file_path 参数
• Write 工具的 file_path 参数
• Windows 系统上的所有文件操作

文档指南

除非用户明确要求，否则绝不创建新的文档文件。

• 优先事项：更新现有的 README.md 文件，而不是创建新文档
• 保持仓库整洁：保持仓库根目录整洁——除非用户另有要求，否则只保留 README.md
• 风格：文档应简洁、直接、专业，避免 AI 生成的语气
• 用户偏好：只有用户明确要求编写文档时，才创建其他 .md 文件

---

全面掌握各平台上的 PowerShell，涵盖脚本编写、自动化、CI/CD 和云管理。

---

适用场景

遇到任何 PowerShell 相关任务时，主动启用：

• PowerShell 脚本 - 创建、审查或优化任何 .ps1 文件
• Cmdlet 和模块 - 查找、安装或使用任何 PowerShell 模块
• 跨平台 - Windows、Linux、macOS 上的 PowerShell 任务
• CI/CD 集成 - GitHub Actions、Azure DevOps、Bitbucket Pipelines
• 云自动化 - Azure (Az)、AWS、Microsoft 365 (Microsoft.Graph)
• 模块管理 - 在 PSGallery 中搜索、安装和更新
• 脚本调试 - 故障排除、性能优化、安全性
• 最佳实践 - 代码质量、标准和可用于生产环境的脚本

---

参考资料索引

详细资料位于 references/。仅加载当前任务所需的内容。

主题	文件	加载时机
跨平台模式（路径、平台检测、编码、Shell 检测）	references/cross-platform-patterns.md	编写可在 Windows + Linux/macOS 上运行的脚本，或区分 PowerShell 与 Git Bash 时
模块管理（PSResourceGet、PSGallery、热门模块）	references/modules-and-gallery.md	安装或查找模块、Az 14.5.0、Microsoft.Graph 2.32.0、PnP、AWS Tools、离线安装时
CI/CD 管道（GitHub Actions、Azure DevOps、Bitbucket）	references/cicd-integration.md	使用多平台矩阵设置自动化 PowerShell 构建和测试时
语法和 cmdlet 参考（变量、运算符、流程、函数、管道、错误处理、Pester、性能、REST）	references/syntax-reference.md	编写脚本、查找 cmdlet、编写 Pester 测试或优化性能时
安全性（JEA、WDAC、受限语言模式、脚本块日志记录、凭据、代码签名）	references/security-2025.md	加固生产环境安全、管理凭据或审计日志时

---

PowerShell 概述

PowerShell 版本和平台

PowerShell 7+（推荐）

• 跨平台：Windows、Linux、macOS
• 开源，持续开发
• 性能优于 PowerShell 5.1
• 默认使用 UTF-8
• 支持并行执行
• 支持三元运算符和空值合并运算符

Windows PowerShell 5.1（旧版）

• 仅适用于 Windows
• 随 Windows 一同提供
• 默认编码为 UTF-16LE
• 某些 Windows 专属模块要求使用此版本

安装位置：

• Windows： C:\Program Files\PowerShell\7\（PS7）或 C:\Windows\System32\WindowsPowerShell\v1.0\（5.1）
• Linux： /opt/microsoft/powershell/7/ 或 /usr/bin/pwsh
• macOS： /usr/local/microsoft/powershell/7/ 或 /usr/local/bin/pwsh

---

核心工作流

1. 确定范围 — 这是脚本、模块、自动化管道，还是一次性命令？注明目标平台。
2. 检查版本和模块 — $PSVersionTable.PSVersion、Get-Module -ListAvailable。除非需要兼容旧版，否则请确认使用 PowerShell 7+。
3. 从上方的参考资料索引中加载相关参考资料。避免加载不需要的内容。
4. 在编写或运行生产脚本前，应用预检清单（见下文）。
5. 验证 — 使用 Invoke-ScriptAnalyzer 进行 lint 检查，使用 Invoke-Pester 运行测试，并对可能造成破坏的 cmdlet 使用 -WhatIf。

---

脚本预检清单

运行任何 PowerShell 脚本前，请确保：

1. 平台检测 — 使用 $IsWindows、$IsLinux、$IsMacOS（参见 references/cross-platform-patterns.md）
2. 版本检查 — 如有需要，使用 #Requires -Version 7.0
3. 模块要求 — 指定 #Requires -Modules
4. 错误处理 — 设置 try/catch 块
5. 输入验证 — 使用参数验证属性（参见 references/syntax-reference.md）
6. 不使用别名 — 脚本中使用完整的 cmdlet 名称
7. 路径处理 — 使用 Join-Path 或 [IO.Path]::Combine()
8. 指定编码 — 使用 UTF-8 以实现跨平台兼容
9. 保护凭据 — 绝不硬编码（参见 references/security-2025.md）
10. 详细日志记录 — 使用 Write-Verbose 进行调试

---

快速决策指南

在以下情况下使用 PowerShell 7+：

• 需要跨平台兼容性
• 新建项目或脚本
• 重视性能
• 需要现代语言功能

在以下情况下使用 Windows PowerShell 5.1：

• 需要 Windows 专用模块（WSUS、GroupPolicy legacy）
• 企业环境对版本有严格要求
• 需要兼容旧版脚本

在以下情况下选择 Azure CLI：

• 需要简单的单行命令
• 更倾向于 JSON 输出
• 需要集成 Bash 脚本

在以下情况下选择 PowerShell Az 模块：

• 需要复杂自动化
• 需要操作对象
• 具备 PowerShell 脚本编写经验
• 需要可复用的脚本和模块

---

最简脚本框架

#Requires -Version 7.0

<#
.SYNOPSIS
    Brief description
.DESCRIPTION
    Detailed description
.PARAMETER Name
    Parameter description
.EXAMPLE
    PS> .\script.ps1 -Name "John"
#>

[CmdletBinding()]
param(
    [Parameter(Mandatory=$true)]
    [ValidateNotNullOrEmpty()]
    [string]$Name
)

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

try {
    Write-Verbose "Starting script"
    # ... main logic ...
    Write-Verbose "Script completed successfully"
}
catch {
    Write-Error "Script failed: $_"
    exit 1
}
finally {
    # Cleanup
}

使用 references/syntax-reference.md（高级函数、管道、错误处理）和 references/security-2025.md（输入验证、凭据处理）中的模式扩展此框架。

---

更多资源

• PowerShell 文档：https://learn.microsoft.com/powershell
• PowerShell Gallery：https://www.powershellgallery.com
• Az 模块文档：https://learn.microsoft.com/powershell/azure
• Microsoft Graph 文档：https://learn.microsoft.com/graph/powershell

如需在 Windows 上检测 shell（PowerShell 与 Git Bash），请参阅 powershell-shell-detection 技能。

---

请记住：在实施解决方案前，务必查阅最新的 PowerShell 文档和模块版本。PowerShell 生态系统发展迅速，最佳实践也在频繁更新。