diff --git a/AGENTS.md b/AGENTS.md index 206edbc..1b4d176 100644 --- a/AGENTS.md +++ b/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. 完成和验收 diff --git a/dev_scripts/harness.py b/dev_scripts/harness.py index bea9576..a8d5fe3 100644 --- a/dev_scripts/harness.py +++ b/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`", diff --git a/docs/04-local-development-and-verification.md b/docs/04-local-development-and-verification.md index c0be8fe..2548940 100644 --- a/docs/04-local-development-and-verification.md +++ b/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 -synchronized_at: 2026-08-18T13:34:49Z +wiki_revision: a7f6ef9e0788065e5a81cfef5753a12b0f0bebc8 +synchronized_at: 2026-08-27T07:00:30Z # 本地开发与验证 @@ -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. 检查工作区 diff --git a/tests/test_harness_docs.py b/tests/test_harness_docs.py index 2b5b6ad..2923b2e 100644 --- a/tests/test_harness_docs.py +++ b/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)