docs: 增加 Windows PowerShell 命令语法边界 (#28)

Local-Development-and-Verification.-.md

@@ -24,6 +24,67 @@
 - 不得仅为设置编码重复启动一层 PowerShell；嵌套进程会增加启动时间、转义复杂度和错误定位成本。
 - 代码搜索仍优先使用代码图工具；非代码文本或图工具不足时优先使用 `rg`，不因本节改用 `Select-String`。
 
+### PowerShell 语法与外部命令
+
+- Windows 环境默认使用当前 PowerShell 语法，不套用 Bash 的 heredoc、变量、路径、引号或反斜杠转义规则。只有明确调用 Bash、WSL 或 Git Bash，并确认路径与编码边界时，才使用 Bash 专用语法。
+- 不需要变量展开的正则和字符串优先用单引号；单引号字符串内部的单引号写成两个单引号。需要变量展开时才使用双引号。
+- 正则同时包含单双引号或转义复杂时，优先赋值给变量、使用 `rg -e`，或拆成语义等价的简单查询；不得为了避开转义改变 AND/OR 条件或重复执行无关搜索。
+
+```powershell
+rg -n 'error|warning' docs
+$pattern = 'can''t match "value"'
+rg -n -e $pattern docs
+```
+
+PowerShell 不支持 Bash heredoc。需要把多行 Python 送入标准输入时，使用单引号 here-string，避免 PowerShell 展开 Python 中的 `# 本地开发与验证
+
+## 本页用途
+
+让维护者能够安装、运行、检查和验证项目。所有命令默认在仓库根目录执行，示例以 Windows PowerShell 为主。
+
+## 环境要求
+
+| 工具 | 用途 | 检查命令 |
+|---|---|---|
+| Git | 版本管理和脏文件保护 | `git --version` |
+| Python 3 | Harness 脚本和测试 | `python --version` |
+| Gitea 连接 | 工单和 Wiki | 浏览仓库或调用 MCP |
+| Gitea PAT | 写 Wiki 时使用 | 仅通过 MCP 安全配置或 `GITEA_TOKEN` 提供 |
+
+不要打印或提交 PAT。
+
+## Windows PowerShell 与 UTF-8
+
+### Shell 选择
+
+- 优先使用当前已经配置的 PowerShell；可选择时优先 PowerShell 7 `pwsh.exe`。
+- 只有 PowerShell 7 不可用或命令明确依赖 Windows PowerShell 5.1 时才使用 `powershell.exe`。
+- 不得仅为设置编码重复启动一层 PowerShell；嵌套进程会增加启动时间、转义复杂度和错误定位成本。
+- 代码搜索仍优先使用代码图工具；非代码文本或图工具不足时优先使用 `rg`，不因本节改用 `Select-String`。
+
+ 等内容。起始标记后必须立即换行，结束标记必须单独占一行：
+
+```powershell
+@'
+print("hello")
+'@ | python -
+```
+
+`foreach`、`if` 等语句块不能裸放在管道左侧；需要管道输出时使用 `$()`、`@()` 或先赋值。普通命令输出无需包装：
+
+```powershell
+@(foreach ($number in 1..3) { $number }) |
+    Measure-Object
+```
+
+不要把含 `*` 的搜索路径直接作为 `rg` 路径参数。优先传入真实目录，并用 `-g/--glob` 让 ripgrep 筛选路径：
+
+```powershell
+rg -n -g '*.md' 'PowerShell' docs
+```
+
+只有确实需要把实体路径列表交给其他命令时，才使用 `Get-ChildItem` 展开并传递 `.FullName`；不要把 `Get-ChildItem -Filter` 设为所有 `rg` 搜索的固定前置。
+
 ### 文件编码
 
 文件解码与控制台输出编码是不同问题。读取 UTF-8 文本时，在命令支持的情况下显式指定编码和字面路径：