docs: 规范 PowerShell UTF-8 与执行策略边界 (#28)

Local-Development-and-Verification.-.md

@@ -15,6 +15,60 @@
 
 不要打印或提交 PAT。
 
+## Windows PowerShell 与 UTF-8
+
+### Shell 选择
+
+- 优先使用当前已经配置的 PowerShell；可选择时优先 PowerShell 7 `pwsh.exe`。
+- 只有 PowerShell 7 不可用或命令明确依赖 Windows PowerShell 5.1 时才使用 `powershell.exe`。
+- 不得仅为设置编码重复启动一层 PowerShell；嵌套进程会增加启动时间、转义复杂度和错误定位成本。
+- 代码搜索仍优先使用代码图工具；非代码文本或图工具不足时优先使用 `rg`，不因本节改用 `Select-String`。
+
+### 文件编码
+
+文件解码与控制台输出编码是不同问题。读取 UTF-8 文本时，在命令支持的情况下显式指定编码和字面路径：
+
+```powershell
+Get-Content -LiteralPath "path\to\file.md" -Encoding utf8
+```
+
+仓库文件修改仍使用项目规定的编辑工具；不要为了指定编码改用 shell 拼接、重定向或临时写文件。PowerShell 5.1 与 PowerShell 7 对无 BOM UTF-8 和写入默认值存在差异，不能只凭控制台显示判断文件编码。
+
+### 控制台与外部命令输出
+
+PowerShell 7 默认通常已满足 UTF-8 场景。只有出现真实乱码，或已知宿主/外部程序没有使用 UTF-8 时，才在当前进程设置：
+
+```powershell
+$OutputEncoding = [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+```
+
+确实需要显式启动 PowerShell 7 时使用：
+
+```powershell
+pwsh.exe -NoLogo -NoProfile -NonInteractive -Command '$OutputEncoding = [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false); <命令>'
+```
+
+不要把这个包装应用到每条命令；同一会话中已经生效且环境未变化时不重复设置。
+
+### Python 中文输出
+
+只有 Python 命令已经出现乱码，或运行宿主已知不是 UTF-8 时，才在当前 PowerShell 进程设置：
+
+```powershell
+$env:PYTHONUTF8 = "1"
+$env:PYTHONIOENCODING = "utf-8"
+python dev_scripts/harness.py check --strict
+```
+
+这些变量只影响当前进程及其子进程，不写入仓库或全局用户配置。乱码仍存在时，先判断问题来自文件解码、控制台、管道还是外部程序，再处理首个真实原因。
+
+### ExecutionPolicy 边界
+
+- `Get-Content`、`rg`、Git、Python 和普通 PowerShell cmdlet 不需要 `-ExecutionPolicy Bypass`。
+- 不得默认添加 `-ExecutionPolicy Bypass`，也不得把它写入所有命令的统一包装。
+- 只有已确认可信的 `.ps1`确实被执行策略阻止、任务范围允许执行且没有更小替代方案时，才可对该次进程使用 Bypass，并在工单记录脚本路径、阻止信息和使用原因。
+- Bypass 只解决执行策略阻止，不解决文件编码、控制台编码、权限或脚本自身错误。
+
 ## 第一次运行
 
 ### 1. 检查工作区