本地开发与验证
本页用途
让维护者能够安装、运行、检查和验证项目。所有命令默认在仓库根目录执行，示例以 Windows PowerShell 为主。
环境要求
| 工具 | 用途 | 检查命令 |
|---|---|---|
| Git | 版本管理和脏文件保护 | git --version |
| Python 3 | Harness 脚本和测试 | python --version |
| Gitea 连接 | 工单和 Wiki | 浏览仓库或调用 MCP |
| Gitea PAT | 写 Wiki 时使用 | 仅通过 MCP 安全配置或 GITEA_TOKEN 提供 |
不要打印或提交 PAT。
Windows PowerShell 与 UTF-8
Shell 选择
- 优先使用当前已经配置的 PowerShell；可选择时优先 PowerShell 7
pwsh.exe。 - 只有 PowerShell 7 不可用或命令明确依赖 Windows PowerShell 5.1 时才使用
powershell.exe。 - 不得仅为设置编码重复启动一层 PowerShell；嵌套进程会增加启动时间、转义复杂度和错误定位成本。
- 代码搜索仍优先使用代码图工具；非代码文本或图工具不足时优先使用
rg，不因本节改用Select-String。
PowerShell 语法与外部命令
- Windows 环境默认使用当前 PowerShell 语法，不套用 Bash 的 heredoc、变量、路径、引号或反斜杠转义规则。只有明确调用 Bash、WSL 或 Git Bash，并确认路径与编码边界时，才使用 Bash 专用语法。
- 不需要变量展开的正则和字符串优先用单引号；单引号字符串内部的单引号写成两个单引号。需要变量展开时才使用双引号。
- 正则同时包含单双引号或转义复杂时，优先赋值给变量、使用
rg -e，或拆成语义等价的简单查询；不得为了避开转义改变 AND/OR 条件或重复执行无关搜索。
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（$）等内容。起始标记后必须立即换行，结束标记必须单独占一行：
@'
print("hello")
'@ | python -
foreach、if 等语句块不能裸放在管道左侧；需要管道输出时使用 $()、@() 或先赋值。普通命令输出无需包装：
@(foreach ($number in 1..3) { $number }) |
Measure-Object
不要把含 * 的搜索路径直接作为 rg 路径参数。优先传入真实目录，并用 -g/--glob 让 ripgrep 筛选路径：
rg -n -g '*.md' 'PowerShell' docs
只有确实需要把实体路径列表交给其他命令时，才使用 Get-ChildItem 展开并传递 .FullName；不要把 Get-ChildItem -Filter 设为所有 rg 搜索的固定前置。
文件编码
文件解码与控制台输出编码是不同问题。读取 UTF-8 文本时，在命令支持的情况下显式指定编码和字面路径：
Get-Content -LiteralPath "path\to\file.md" -Encoding utf8
仓库文件修改仍使用项目规定的编辑工具；不要为了指定编码改用 shell 拼接、重定向或临时写文件。PowerShell 5.1 与 PowerShell 7 对无 BOM UTF-8 和写入默认值存在差异，不能只凭控制台显示判断文件编码。
控制台与外部命令输出
PowerShell 7 默认通常已满足 UTF-8 场景。只有出现真实乱码，或已知宿主/外部程序没有使用 UTF-8 时，才在当前进程设置：
$OutputEncoding = [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
确实需要显式启动 PowerShell 7 时使用：
pwsh.exe -NoLogo -NoProfile -NonInteractive -Command '$OutputEncoding = [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false); <命令>'
不要把这个包装应用到每条命令；同一会话中已经生效且环境未变化时不重复设置。
Python 中文输出
只有 Python 命令已经出现乱码，或运行宿主已知不是 UTF-8 时，才在当前 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. 检查工作区
- 目的：确认没有混入其他任务的修改。
- 命令：
git status --short --branch - 预期：显示当前分支；开始新任务时没有无关文件。
- 失败检查：确认变更归属，不要擅自重置或覆盖。
2. 检查 Harness
- 目的：验证必需文件、项目档案、Wiki 映射和归档结构。
- 命令：
python dev_scripts/harness.py check --strict - 预期：输出“DevHarness 检查通过”。
- 失败检查：按错误提示检查缺失页面、未填占位符或损坏的镜像头。
3. 运行测试
- 目的：验证同步、路径和安全保护。
- 命令：
python -m unittest discover -s tests -v - 预期：所有测试显示
ok。 - 失败检查：先单独运行失败测试，再查看最近修改的对应脚本。
4. 对照线上 Wiki
- 目的：确认本地 docs 是最新镜像。
- 命令：
python dev_scripts/harness.py sync --check - 预期：所有映射显示“一致”。
- 失败检查：先读取线上页面；确认页面名、revision、网络和
GITEA_URL。
常用调试方式
- 只检查 Python 语法：
python -m compileall -q dev_scripts tests。 - 查看一个脚本帮助：
python dev_scripts/harness.py sync --help。 - 查看未提交差异：
git diff --check和git diff。 - 查看最近提交：
git log -5 --oneline。 - 调试失败测试时优先运行单个测试文件，不要先修改多个模块。
测试数据与日志
DevHarness 不使用生产数据，也不需要固定业务测试数据。命令输出是主要诊断信息，不应包含令牌。如果复制到业务项目，应在本节写明：
- 合成或脱敏测试数据的创建方式；
- 日志路径和日志级别；
- 请求或任务标识如何追踪；
- 禁止使用的数据来源。
完成修改前
依次执行：
python -m unittest discover -s tests -v
python dev_scripts/harness.py check --strict
python dev_scripts/harness.py sync --check
git diff --check
git status --short
无法执行的命令必须写入工单“未验证部分”。