规范 Windows PowerShell UTF-8 与执行策略边界 #28

Closed
opened 2026-08-27 14:58:41 +08:00 by ila · 4 comments
Owner

基本信息

  • 类型:单元任务
  • 阶段:已完成
  • 原始需求来源:当前对话,2026-08-27
  • 关键需求摘要:为 Windows/PowerShell 增加经过修正的 UTF-8 使用规范,避免中文乱码和 Bash/PowerShell 语法混用,但不强制嵌套 PowerShell 或默认绕过执行策略。
  • 前置工单:无
  • 是否允许并行:是;本任务是独立开发环境规则。
  • 设计证据:无 UI;采用已确认的文档与命令规范。

目标

  • 在共享 Agent 规则中增加简短、可执行的 PowerShell UTF-8 约束。
  • 在 Local-Development-and-Verification 中说明 PowerShell 版本选择、文件编码、控制台编码、Python 输出编码及 ExecutionPolicy 边界。
  • 保持 Codex 和 Claude Code 行为一致,并避免无意义的嵌套 shell 和重复检查。

非目标

  • 不要求所有命令通过 powershell.exe 或 pwsh.exe嵌套调用。
  • 不默认使用 -ExecutionPolicy Bypass。
  • 不修改 CLAUDE.md 或 README;项目档案只记录当前 Windows 10 / pwsh7 环境。
  • 不新增编码包装脚本,不修改产品代码。
  • 不把 Select-String替代为默认搜索工具;仍遵循现有图工具和 rg优先级。

已确认方案

  1. Windows 环境优先使用当前已配置的 PowerShell;可选择时优先 PowerShell 7 pwsh.exe。
  2. 不得仅为设置编码重复启动一层 PowerShell。
  3. 文本文件读写在支持时显式指定 UTF-8,例如 Get-Content -Encoding utf8。
  4. 只有真实乱码或已知宿主非 UTF-8 时,才设置当前进程的 $OutputEncoding和[Console]::OutputEncoding。
  5. Python 输出乱码时,按需在当前进程设置 PYTHONUTF8=1和PYTHONIOENCODING=utf-8。
  6. 不默认使用 -ExecutionPolicy Bypass;只有可信 .ps1确实被策略阻止时才使用并记录原因。
  7. 长期详细说明先更新 Wiki,在线回读后同步 docs/04-local-development-and-verification.md。
  8. 严格检查固定关键边界,防止回退为“所有命令强制 Bypass”。
  9. Windows 默认使用当前 PowerShell 语法;只有明确调用 Bash、WSL 或 Git Bash并确认路径/编码边界时才使用 Bash 专用语法。
  10. PowerShell 中不需要变量展开的正则优先单引号;复杂引号使用变量、here-string、rg -e 或语义等价的简单查询,不强制拆成多次搜索。
  11. 多行 Python 使用单引号 PowerShell here-string 管道给 python -,并明确定界符换行规则。
  12. foreach、if 等语句块进入管道前使用 $()、@() 或变量;普通命令无需包装。
  13. rg 使用真实目录配合 -g/--glob;只有需要实体路径列表时才用 Get-ChildItem 和 .FullName。
  14. 当前环境版本写入 Project-Profile,通用规则不硬编码 Windows 10。

影响范围

  • AGENTS.md
  • Gitea Wiki:Local-Development-and-Verification、Project-Profile
  • 本地镜像:docs/04-local-development-and-verification.md、docs/00-project-profile.md
  • dev_scripts/harness.py与相关测试

风险与回退

  • 风险:PowerShell 5.1、PowerShell 7 和外部程序的编码行为不同;错误规则可能增加转义和启动成本。
  • 控制:按需设置编码,文件解码与控制台输出编码分别处理;保留兼容回退。
  • 回退:移除新增规则和 Wiki 章节;不涉及数据迁移或不可逆操作。

验证

  • python dev_scripts/harness.py check --strict
  • python -m unittest discover -s tests -v
  • python dev_scripts/harness.py sync --check
  • 文字与命令场景检查:PowerShell 7、Windows PowerShell 5.1、Bash 语法隔离、复杂正则、多行 Python、语句块管道、rg -g、UTF-8 输出和可信脚本受策略阻止。

文档影响

  • 更新 Local-Development-and-Verification 和 Project-Profile。
  • 同步核心 docs/04镜像。
  • 默认不创建任务快照。

验收标准

  • 规则不包含错误的 PowerShel1或powershel1.exe拼写。
  • 不强制每条命令嵌套启动 PowerShell。
  • 不默认使用 -ExecutionPolicy Bypass。
  • 文件编码与控制台输出编码的处理边界明确。
  • 提供 PowerShell 和 Python 的最小 UTF-8 示例。
  • 不默认使用 Bash 专用语法,复杂正则不被强制拆成改变语义的多次搜索。
  • 多行 Python、语句块管道和 rg -g 有可复制示例。
  • Windows 10 / pwsh7 只记录为当前项目环境,不写成所有项目的永久前提。
  • Codex 与 Claude Code 通过共享规则获得一致行为。
  • 严格检查、单元测试和 Wiki 镜像一致性检查通过。
  • 提交推送并回写最终证据,工单保持待验收。
## 基本信息 - 类型:单元任务 - 阶段:已完成 - 原始需求来源:当前对话,2026-08-27 - 关键需求摘要:为 Windows/PowerShell 增加经过修正的 UTF-8 使用规范,避免中文乱码和 Bash/PowerShell 语法混用,但不强制嵌套 PowerShell 或默认绕过执行策略。 - 前置工单:无 - 是否允许并行:是;本任务是独立开发环境规则。 - 设计证据:无 UI;采用已确认的文档与命令规范。 ## 目标 - 在共享 Agent 规则中增加简短、可执行的 PowerShell UTF-8 约束。 - 在 Local-Development-and-Verification 中说明 PowerShell 版本选择、文件编码、控制台编码、Python 输出编码及 ExecutionPolicy 边界。 - 保持 Codex 和 Claude Code 行为一致,并避免无意义的嵌套 shell 和重复检查。 ## 非目标 - 不要求所有命令通过 `powershell.exe` 或 `pwsh.exe`嵌套调用。 - 不默认使用 `-ExecutionPolicy Bypass`。 - 不修改 `CLAUDE.md` 或 README;项目档案只记录当前 Windows 10 / pwsh7 环境。 - 不新增编码包装脚本,不修改产品代码。 - 不把 `Select-String`替代为默认搜索工具;仍遵循现有图工具和 `rg`优先级。 ## 已确认方案 1. Windows 环境优先使用当前已配置的 PowerShell;可选择时优先 PowerShell 7 `pwsh.exe`。 2. 不得仅为设置编码重复启动一层 PowerShell。 3. 文本文件读写在支持时显式指定 UTF-8,例如 `Get-Content -Encoding utf8`。 4. 只有真实乱码或已知宿主非 UTF-8 时,才设置当前进程的 `$OutputEncoding`和`[Console]::OutputEncoding`。 5. Python 输出乱码时,按需在当前进程设置 `PYTHONUTF8=1`和`PYTHONIOENCODING=utf-8`。 6. 不默认使用 `-ExecutionPolicy Bypass`;只有可信 `.ps1`确实被策略阻止时才使用并记录原因。 7. 长期详细说明先更新 Wiki,在线回读后同步 `docs/04-local-development-and-verification.md`。 8. 严格检查固定关键边界,防止回退为“所有命令强制 Bypass”。 9. Windows 默认使用当前 PowerShell 语法;只有明确调用 Bash、WSL 或 Git Bash并确认路径/编码边界时才使用 Bash 专用语法。 10. PowerShell 中不需要变量展开的正则优先单引号;复杂引号使用变量、here-string、`rg -e` 或语义等价的简单查询,不强制拆成多次搜索。 11. 多行 Python 使用单引号 PowerShell here-string 管道给 `python -`,并明确定界符换行规则。 12. `foreach`、`if` 等语句块进入管道前使用 `$()`、`@()` 或变量;普通命令无需包装。 13. `rg` 使用真实目录配合 `-g/--glob`;只有需要实体路径列表时才用 `Get-ChildItem` 和 `.FullName`。 14. 当前环境版本写入 Project-Profile,通用规则不硬编码 Windows 10。 ## 影响范围 - `AGENTS.md` - Gitea Wiki:Local-Development-and-Verification、Project-Profile - 本地镜像:`docs/04-local-development-and-verification.md`、`docs/00-project-profile.md` - `dev_scripts/harness.py`与相关测试 ## 风险与回退 - 风险:PowerShell 5.1、PowerShell 7 和外部程序的编码行为不同;错误规则可能增加转义和启动成本。 - 控制:按需设置编码,文件解码与控制台输出编码分别处理;保留兼容回退。 - 回退:移除新增规则和 Wiki 章节;不涉及数据迁移或不可逆操作。 ## 验证 - `python dev_scripts/harness.py check --strict` - `python -m unittest discover -s tests -v` - `python dev_scripts/harness.py sync --check` - 文字与命令场景检查:PowerShell 7、Windows PowerShell 5.1、Bash 语法隔离、复杂正则、多行 Python、语句块管道、`rg -g`、UTF-8 输出和可信脚本受策略阻止。 ## 文档影响 - 更新 Local-Development-and-Verification 和 Project-Profile。 - 同步核心 `docs/04`镜像。 - 默认不创建任务快照。 ## 验收标准 - [ ] 规则不包含错误的 `PowerShel1`或`powershel1.exe`拼写。 - [ ] 不强制每条命令嵌套启动 PowerShell。 - [ ] 不默认使用 `-ExecutionPolicy Bypass`。 - [ ] 文件编码与控制台输出编码的处理边界明确。 - [ ] 提供 PowerShell 和 Python 的最小 UTF-8 示例。 - [ ] 不默认使用 Bash 专用语法,复杂正则不被强制拆成改变语义的多次搜索。 - [ ] 多行 Python、语句块管道和 `rg -g` 有可复制示例。 - [ ] Windows 10 / pwsh7 只记录为当前项目环境,不写成所有项目的永久前提。 - [ ] Codex 与 Claude Code 通过共享规则获得一致行为。 - [ ] 严格检查、单元测试和 Wiki 镜像一致性检查通过。 - [ ] 提交推送并回写最终证据,工单保持待验收。
Author
Owner

最终实施证据(待验收)

完成内容

  • 在 AGENTS.md增加简短强制规则:Windows 优先当前 PowerShell,可选时优先 PowerShell 7,不为编码重复启动 shell。
  • 文件解码与控制台输出分别处理;文本读取按命令能力显式指定 UTF-8。
  • 只有出现真实乱码或已知宿主非 UTF-8 时,才设置当前进程的输出编码或 Python UTF-8 环境变量。
  • 明确禁止默认使用 -ExecutionPolicy Bypass;仅可信 .ps1确实被策略阻止且无更小方案时允许单次使用并记录原因。
  • Local-Development-and-Verification 新增 Shell 选择、文件编码、控制台/外部命令、Python 中文输出和 ExecutionPolicy 边界。
  • 保留代码图工具与 rg搜索优先级,不把 Select-String设为默认。
  • 未修改 CLAUDE.md、README、项目档案或产品代码,未新增包装脚本。

提交

  • 4bbacf4 — 规范 PowerShell UTF-8 与执行策略。

已推送到 origin/main。

验证

  • python dev_scripts/harness.py check --strict:通过。
  • python -m unittest discover -s tests -v:46/46 通过。
  • python dev_scripts/harness.py sync --check:15 个核心镜像一致。
  • 规则扫描:无 PowerShel1、powershel1.exe错误拼写;无强制每条命令嵌套 PowerShell;无默认 Bypass 规则。
  • 场景核对:PowerShell 7、Windows PowerShell 5.1、UTF-8 文件读取、控制台乱码、Python 中文输出、可信脚本被策略阻止均有明确边界。
  • 未验证:没有真实执行被策略阻止的脚本,因为当前任务没有此类脚本;没有为制造乱码而改变系统全局编码。

Wiki 证据

  • Local-Development-and-Verification:a7f6ef9e0788065e5a81cfef5753a12b0f0bebc8

文档和快照

  • 核心 Wiki 已在线回读并同步 docs/04-local-development-and-verification.md。
  • 未创建或导出任务快照。

当前阶段:待验收。工单保持开启,等待用户明确验收。

## 最终实施证据(待验收) ### 完成内容 - 在 `AGENTS.md`增加简短强制规则:Windows 优先当前 PowerShell,可选时优先 PowerShell 7,不为编码重复启动 shell。 - 文件解码与控制台输出分别处理;文本读取按命令能力显式指定 UTF-8。 - 只有出现真实乱码或已知宿主非 UTF-8 时,才设置当前进程的输出编码或 Python UTF-8 环境变量。 - 明确禁止默认使用 `-ExecutionPolicy Bypass`;仅可信 `.ps1`确实被策略阻止且无更小方案时允许单次使用并记录原因。 - Local-Development-and-Verification 新增 Shell 选择、文件编码、控制台/外部命令、Python 中文输出和 ExecutionPolicy 边界。 - 保留代码图工具与 `rg`搜索优先级,不把 `Select-String`设为默认。 - 未修改 `CLAUDE.md`、README、项目档案或产品代码,未新增包装脚本。 ### 提交 - `4bbacf4` — 规范 PowerShell UTF-8 与执行策略。 已推送到 `origin/main`。 ### 验证 - `python dev_scripts/harness.py check --strict`:通过。 - `python -m unittest discover -s tests -v`:46/46 通过。 - `python dev_scripts/harness.py sync --check`:15 个核心镜像一致。 - 规则扫描:无 `PowerShel1`、`powershel1.exe`错误拼写;无强制每条命令嵌套 PowerShell;无默认 Bypass 规则。 - 场景核对:PowerShell 7、Windows PowerShell 5.1、UTF-8 文件读取、控制台乱码、Python 中文输出、可信脚本被策略阻止均有明确边界。 - 未验证:没有真实执行被策略阻止的脚本,因为当前任务没有此类脚本;没有为制造乱码而改变系统全局编码。 ### Wiki 证据 - Local-Development-and-Verification:`a7f6ef9e0788065e5a81cfef5753a12b0f0bebc8` ### 文档和快照 - 核心 Wiki 已在线回读并同步 `docs/04-local-development-and-verification.md`。 - 未创建或导出任务快照。 当前阶段:**待验收**。工单保持开启,等待用户明确验收。
Author
Owner

需求变化(2026-09-02)

用户在原待验收范围上补充 Windows/pwsh7 命令约束并确认采用优化版本。#28 恢复为“进行中”。

新增范围:Bash 与 PowerShell 语法隔离、正则引号、多行 Python here-string、语句块管道、ripgrep glob,以及在 Project-Profile 记录当前 Windows 10 / pwsh7 环境。

两项原规则已修正:

  • 不强制复杂正则拆成多个 rg,避免改变查询语义和重复扫描;
  • 不强制通配路径先走 Get-ChildItem -Filter,优先真实目录配合 rg -g/--glob。

本地已确认当前 PowerShell 为 7.3.12、ripgrep 为 15.2.0;裸 foreach (...) { ... } | ... 会产生 ParserError,使用 @(...) 可进入管道。

## 需求变化(2026-09-02) 用户在原待验收范围上补充 Windows/pwsh7 命令约束并确认采用优化版本。#28 恢复为“进行中”。 新增范围:Bash 与 PowerShell 语法隔离、正则引号、多行 Python here-string、语句块管道、ripgrep glob,以及在 Project-Profile 记录当前 Windows 10 / pwsh7 环境。 两项原规则已修正: - 不强制复杂正则拆成多个 `rg`,避免改变查询语义和重复扫描; - 不强制通配路径先走 `Get-ChildItem -Filter`,优先真实目录配合 `rg -g/--glob`。 本地已确认当前 PowerShell 为 7.3.12、ripgrep 为 15.2.0;裸 `foreach (...) { ... } | ...` 会产生 ParserError,使用 `@(...)` 可进入管道。
Author
Owner

补充实施最终证据(待验收)

本评论取代此前仅覆盖 UTF-8/ExecutionPolicy 的待验收证据,包含 2026-09-02 新增的 Windows 命令语法范围。

  • 新增提交:40b99387adc184274c43fda5f7efb3746642e27a,已推送到 origin/main。
  • 原实现提交:4bbacf4;两次提交共同构成 #28 当前验收版本。
  • 新增规则:
    • Windows 默认使用当前 PowerShell 语法,不默认套用 Bash heredoc、变量、路径、引号或转义;
    • 正则优先 PowerShell 单引号,复杂正则使用变量或 rg -e,不强制拆成改变语义的多次搜索;
    • 多行 Python 使用单引号 PowerShell here-string;
    • foreach、if 等语句块进入管道前使用 $()、@() 或变量;
    • ripgrep 使用真实目录配合 -g/--glob,不强制 Get-ChildItem -Filter;
    • Windows 10、PowerShell 7 pwsh(本地验证 7.3.12)记录到 Project-Profile,不作为所有项目的硬编码前提。
  • 本地实测:
    • 裸 foreach (...) { ... } | Measure-Object 返回 ParserError;
    • @(foreach (...)) | Measure-Object 成功;
    • PowerShell here-string 可传入 python -;
    • rg -g '*.md' 可按 glob 搜索。
  • 实施中发现并修复一次 Wiki replacement token 导致的章节重复;错误版本未推送到 Git。线上回读确认最终页面只有一个标题、一个“文件编码”章节。
  • 单元测试:55 项全部通过。
  • python dev_scripts/harness.py check --strict:通过。
  • python dev_scripts/harness.py sync --check:15 个核心页面一致。
  • Wiki revisions:
    • Project-Profile:54598b0fed91a852385386bd6fd920245f5dc1dd
    • Local-Development-and-Verification:a94b4eaa509f351b77274f007ae882e9e696fc8b
  • 工作区干净,HEAD、origin/main、远端 main 均为 40b9938。
  • 未验证:未实际启动 WSL/Git Bash;规则要求只有明确调用并确认边界时才使用。
  • 未创建或导出任务归档。

工单恢复为待验收并保持开启。

## 补充实施最终证据(待验收) 本评论取代此前仅覆盖 UTF-8/ExecutionPolicy 的待验收证据,包含 2026-09-02 新增的 Windows 命令语法范围。 - 新增提交:`40b99387adc184274c43fda5f7efb3746642e27a`,已推送到 `origin/main`。 - 原实现提交:`4bbacf4`;两次提交共同构成 #28 当前验收版本。 - 新增规则: - Windows 默认使用当前 PowerShell 语法,不默认套用 Bash heredoc、变量、路径、引号或转义; - 正则优先 PowerShell 单引号,复杂正则使用变量或 `rg -e`,不强制拆成改变语义的多次搜索; - 多行 Python 使用单引号 PowerShell here-string; - `foreach`、`if` 等语句块进入管道前使用 `$()`、`@()` 或变量; - ripgrep 使用真实目录配合 `-g/--glob`,不强制 `Get-ChildItem -Filter`; - Windows 10、PowerShell 7 `pwsh`(本地验证 7.3.12)记录到 Project-Profile,不作为所有项目的硬编码前提。 - 本地实测: - 裸 `foreach (...) { ... } | Measure-Object` 返回 ParserError; - `@(foreach (...)) | Measure-Object` 成功; - PowerShell here-string 可传入 `python -`; - `rg -g '*.md'` 可按 glob 搜索。 - 实施中发现并修复一次 Wiki replacement token 导致的章节重复;错误版本未推送到 Git。线上回读确认最终页面只有一个标题、一个“文件编码”章节。 - 单元测试:55 项全部通过。 - `python dev_scripts/harness.py check --strict`:通过。 - `python dev_scripts/harness.py sync --check`:15 个核心页面一致。 - Wiki revisions: - Project-Profile:`54598b0fed91a852385386bd6fd920245f5dc1dd` - Local-Development-and-Verification:`a94b4eaa509f351b77274f007ae882e9e696fc8b` - 工作区干净,HEAD、origin/main、远端 main 均为 `40b9938`。 - 未验证:未实际启动 WSL/Git Bash;规则要求只有明确调用并确认边界时才使用。 - 未创建或导出任务归档。 工单恢复为待验收并保持开启。
Author
Owner

验收结论

  • 验收时间:2026-09-02(Asia/Shanghai)
  • 结论:用户明确表示 #28 验收通过。
  • 验收版本:4bbacf4 与补充提交 40b99387adc184274c43fda5f7efb3746642e27a,均已推送到 origin/main。
  • 验证证据:55 项单元测试全部通过;严格结构检查通过;15 个核心 Wiki 镜像一致。
  • Wiki revisions:Project-Profile 54598b0fed91a852385386bd6fd920245f5dc1dd;Local-Development-and-Verification a94b4eaa509f351b77274f007ae882e9e696fc8b。
  • 文档影响:长期规则和本地核心镜像已在实施阶段完成更新,本次验收没有新的长期事实变化,因此不重复更新 Wiki。
  • 父工单:无。
  • 任务快照:未创建、未导出。

验收闭环完成,关闭工单。

## 验收结论 - 验收时间:2026-09-02(Asia/Shanghai) - 结论:用户明确表示 #28 验收通过。 - 验收版本:`4bbacf4` 与补充提交 `40b99387adc184274c43fda5f7efb3746642e27a`,均已推送到 `origin/main`。 - 验证证据:55 项单元测试全部通过;严格结构检查通过;15 个核心 Wiki 镜像一致。 - Wiki revisions:Project-Profile `54598b0fed91a852385386bd6fd920245f5dc1dd`;Local-Development-and-Verification `a94b4eaa509f351b77274f007ae882e9e696fc8b`。 - 文档影响:长期规则和本地核心镜像已在实施阶段完成更新,本次验收没有新的长期事实变化,因此不重复更新 Wiki。 - 父工单:无。 - 任务快照:未创建、未导出。 验收闭环完成,关闭工单。
ila closed this issue 2026-09-02 15:37:39 +08:00
Sign in to join this conversation.
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: OPC/dev_harness#28