From 40b99387adc184274c43fda5f7efb3746642e27a Mon Sep 17 00:00:00 2001 From: ila Date: Wed, 2 Sep 2026 15:20:27 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=20Windows=20PowerShe?= =?UTF-8?q?ll=20=E5=91=BD=E4=BB=A4=E7=BA=A6=E6=9D=9F=20(#28)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 5 +++ dev_scripts/harness.py | 6 +++ docs/00-project-profile.md | 6 +-- docs/04-local-development-and-verification.md | 39 ++++++++++++++++++- tests/test_harness_docs.py | 16 ++++++++ 5 files changed, 67 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4cc0c49..887971c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -181,6 +181,11 @@ - 优先运行项目档案中记录的格式检查、静态检查、单元测试和必要的集成测试。 - 不能验证的真机、生产、迁移或并发行为必须写入工单；存在明确要求的任务快照时再同步记录。 - Windows 环境优先使用当前已配置的 PowerShell；可选择时优先 PowerShell 7 `pwsh.exe`，不得仅为设置编码重复启动一层 PowerShell。 +- Windows 命令不得默认套用 Bash 的 heredoc、变量、路径、引号或转义语法；只有明确调用 Bash、WSL 或 Git Bash，并确认路径与编码边界时才使用。 +- PowerShell 中不需要变量展开的正则优先使用单引号；复杂正则优先使用变量或 `rg -e`，不得为了避开转义而改变查询语义或堆叠重复搜索。 +- 多行 Python 使用单引号 PowerShell here-string 管道给 `python -`；起始标记后立即换行，结束标记单独占一行，不使用 Bash heredoc。 +- `foreach`、`if` 等语句块的输出进入管道前使用 `$()`、`@()` 或变量；普通命令输出直接进入管道。 +- `rg` 使用真实目录配合 `-g/--glob` 筛选路径；只有确实需要实体路径列表时才用 `Get-ChildItem` 展开并传递 `.FullName`。 - 文本文件读写在命令支持时显式指定 UTF-8；文件解码和控制台输出分别处理，只有出现真实乱码或已知宿主非 UTF-8 时才设置当前进程的输出编码或 Python UTF-8 环境变量。 - 不得默认使用 `-ExecutionPolicy Bypass`；只有可信 `.ps1`确实被执行策略阻止且没有更小替代方案时，才对该次进程使用并在工单记录原因。 diff --git a/dev_scripts/harness.py b/dev_scripts/harness.py index fad1233..dc8a7b8 100644 --- a/dev_scripts/harness.py +++ b/dev_scripts/harness.py @@ -111,6 +111,7 @@ CORE_DOCUMENT_REQUIREMENTS = { "docs/04-local-development-and-verification.md": ( "## 环境要求", "## Windows PowerShell 与 UTF-8", + "### PowerShell 语法与外部命令", "## 第一次运行", "## 常用调试方式", "## 完成修改前", @@ -349,6 +350,11 @@ def check_agent_efficiency_rules(errors: list[str], root: Path = ROOT) -> None: "不得把模板自带的本地 `docs/` 当作新项目 Wiki 已初始化的证据", "提交只包含当前任务相关文件", "不得仅为设置编码重复启动一层 PowerShell", + "不得默认套用 Bash", + "复杂正则优先使用变量或 `rg -e`", + "单引号 PowerShell here-string", + "`foreach`、`if` 等语句块", + "使用真实目录配合 `-g/--glob`", "文件解码和控制台输出分别处理", "不得默认使用 `-ExecutionPolicy Bypass`", "### 按治理模式选择最小设计证据", diff --git a/docs/00-project-profile.md b/docs/00-project-profile.md index e50dd41..01398ab 100644 --- a/docs/00-project-profile.md +++ b/docs/00-project-profile.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Project-Profile wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Project-Profile.- -wiki_revision: 5323a382fc19433c19441587120d5a0ee6447a24 -synchronized_at: 2026-09-02T02:08:46Z +wiki_revision: 54598b0fed91a852385386bd6fd920245f5dc1dd +synchronized_at: 2026-09-02T07:17:36Z # 项目档案 @@ -65,7 +65,7 @@ synchronized_at: 2026-09-02T02:08:46Z |---|---|---| | Harness 规则和模板 | Markdown、Gitea 1.25 | `AGENTS.md` | | Wiki 镜像与结构检查 | Python 3 标准库 | `AGENTS.md` | -| 主要开发环境 | Windows、PowerShell、Git | `AGENTS.md` | +| 主要开发环境 | Windows 10、PowerShell 7 `pwsh`（当前验证 7.3.12）、Git | `AGENTS.md` | 本项目不需要安装第三方 Python 包。复制到业务项目后，必须把真实语言、框架、版本和支持平台写入本节。 diff --git a/docs/04-local-development-and-verification.md b/docs/04-local-development-and-verification.md index 2548940..b3aac3d 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: a7f6ef9e0788065e5a81cfef5753a12b0f0bebc8 -synchronized_at: 2026-08-27T07:00:30Z +wiki_revision: a94b4eaa509f351b77274f007ae882e9e696fc8b +synchronized_at: 2026-09-02T07:20:33Z # 本地开发与验证 @@ -32,6 +32,41 @@ synchronized_at: 2026-08-27T07:00:30Z - 不得仅为设置编码重复启动一层 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 中的 dollar sign（`$`）等内容。起始标记后必须立即换行，结束标记必须单独占一行： + +```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 文本时，在命令支持的情况下显式指定编码和字面路径： diff --git a/tests/test_harness_docs.py b/tests/test_harness_docs.py index 25b4404..dbae729 100644 --- a/tests/test_harness_docs.py +++ b/tests/test_harness_docs.py @@ -168,6 +168,22 @@ class CoreDocumentTests(unittest.TestCase): check_agent_efficiency_rules(errors) self.assertEqual(errors, []) + def test_windows_shell_rules_avoid_bash_and_ripgrep_traps(self) -> None: + agents = (ROOT / "AGENTS.md").read_text(encoding="utf-8") + profile = (ROOT / "docs/00-project-profile.md").read_text(encoding="utf-8") + local = ( + ROOT / "docs/04-local-development-and-verification.md" + ).read_text(encoding="utf-8") + self.assertIn("Windows 10", profile) + self.assertIn("PowerShell 7 `pwsh`", profile) + self.assertIn("不得默认套用 Bash", agents) + self.assertIn("复杂正则优先使用变量或 `rg -e`", agents) + self.assertIn("@'\nprint", local) + self.assertIn("@(foreach", local) + self.assertIn("rg -n -g '*.md'", local) + self.assertNotIn("通配目录必须先用 `Get-ChildItem -Filter`", local) + self.assertNotIn("正则本身同时包含单引号和双引号，优先拆成多个", local) + def test_deployment_template_is_required_and_mapped(self) -> None: path = "docs/templates/deployment.md" self.assertIn(path, REQUIRED_FILES)