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

AGENTS.md

@@ -176,6 +176,9 @@ Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明
 - 不为流程制造空提交。
 - 优先运行项目档案中记录的格式检查、静态检查、单元测试和必要的集成测试。
 - 不能验证的真机、生产、迁移或并发行为必须写入工单；存在明确要求的任务快照时再同步记录。
+- Windows 环境优先使用当前已配置的 PowerShell；可选择时优先 PowerShell 7 `pwsh.exe`，不得仅为设置编码重复启动一层 PowerShell。
+- 文本文件读写在命令支持时显式指定 UTF-8；文件解码和控制台输出分别处理，只有出现真实乱码或已知宿主非 UTF-8 时才设置当前进程的输出编码或 Python UTF-8 环境变量。
+- 不得默认使用 `-ExecutionPolicy Bypass`；只有可信 `.ps1`确实被执行策略阻止且没有更小替代方案时，才对该次进程使用并在工单记录原因。
 
 ## 7. 完成和验收
 

dev_scripts/harness.py

@@ -108,6 +108,7 @@ CORE_DOCUMENT_REQUIREMENTS = {
     ),
     "docs/04-local-development-and-verification.md": (
         "## 环境要求",
+        "## Windows PowerShell 与 UTF-8",
         "## 第一次运行",
         "## 常用调试方式",
         "## 完成修改前",
@@ -344,6 +345,9 @@ def check_agent_efficiency_rules(errors: list[str], root: Path = ROOT) -> None:
         "`Home` 不存在时必须先创建 `Home`",
         "不得把模板自带的本地 `docs/` 当作新项目 Wiki 已初始化的证据",
         "提交只包含当前工单相关文件",
+        "不得仅为设置编码重复启动一层 PowerShell",
+        "文件解码和控制台输出分别处理",
+        "不得默认使用 `-ExecutionPolicy Bypass`",
         "### 工单与设计证据双门禁",
         "新页面、独立用户功能、重大交互或导航变化",
         "`prototypes/<工单号>/<版本>/index.html`",

docs/04-local-development-and-verification.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Local-Development-and-Verification
 wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Local-Development-and-Verification.-
-wiki_revision: b519184a1f0aa4f104350e7eed43619e62a23b43
+wiki_revision: a7f6ef9e0788065e5a81cfef5753a12b0f0bebc8
-synchronized_at: 2026-08-18T13:34:49Z
+synchronized_at: 2026-08-27T07:00:30Z
 <!-- gitea-wiki-mirror:end -->
 
 # 本地开发与验证
@@ -23,6 +23,60 @@ synchronized_at: 2026-08-18T13:34:49Z
 
 不要打印或提交 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. 检查工作区

tests/test_harness_docs.py

@@ -129,6 +129,16 @@ class CoreDocumentTests(unittest.TestCase):
         self.assertIn("### 3. 识别子项目与交付单元", required)
         self.assertIn("#### 需求总览启用条件", required)
 
+    def test_local_development_requires_powershell_utf8_boundaries(self) -> None:
+        required = CORE_DOCUMENT_REQUIREMENTS[
+            "docs/04-local-development-and-verification.md"
+        ]
+        self.assertIn("## Windows PowerShell 与 UTF-8", required)
+
+        errors: list[str] = []
+        check_agent_efficiency_rules(errors)
+        self.assertEqual(errors, [])
+
     def test_deployment_template_is_required_and_mapped(self) -> None:
         path = "docs/templates/deployment.md"
         self.assertIn(path, REQUIRED_FILES)