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

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: 8348baeb75e77dcc0f8a6321e87bd3d60eb501a7 synchronized_at: 2026-10-06T03:47:21Z

本地开发与验证

本页用途

让维护者能够安装、运行、检查和验证项目。所有命令默认在仓库根目录执行，示例以 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。
• 调试失败测试时优先运行单个测试文件，不要先修改多个模块。

临时 worktree 收尾

适用于本任务创建的临时 worktree。目标是任务成果合并、推送且完成必要验证后及时清理；仍需用于验收或预览时记录保留原因。创建目录的 Agent 负责收尾，交接任务时移交路径与责任。

1. 核对目标与本地内容

从主工作树或其他不会被删除的目录执行。把示例路径替换为本任务的真实路径，确认与 git worktree list 登记一致，并且不是主工作树或其他任务目录。

git worktree list --porcelain
$taskWorktree = (Resolve-Path -LiteralPath 'D:\Projects\example-worktrees\task-123' -ErrorAction Stop).Path
git -C "$taskWorktree" rev-parse HEAD
git -C "$taskWorktree" status --short --untracked-files=all --ignored

结合本任务合并与推送记录，确认最后版本的成果已进入 main 或约定目标分支。普通合并可用提交包含关系核对；squash/rebase 会改变提交哈希，应核对对应合并记录及最终变更，不能因哈希不同就强制清理，也不能仅凭分支名称判断已合并。

检查本地需保留的内容，包括未提交修改、未跟踪文件，以及被忽略的本地配置、数据库、验收材料等。忽略文件中的可再生依赖和构建缓存可随目录清理，但不能据此认为所有忽略文件均可丢弃。无需为了清理重复运行已经通过且仍有效的测试。

确认其他 Agent、服务、预览和验收不再使用该目录，并将当前终端移到目录之外；不要自动终止其他任务的进程或解除 worktree 锁定。

2. 移除并确认

只有上一步条件满足时才执行；以下命令使用上一步已核对的准确路径：

git worktree remove "$taskWorktree"
if ($LASTEXITCODE -ne 0) { throw 'worktree 移除失败；保留现状，记录原因，不自动强制删除。' }
git worktree list --porcelain
Test-Path -LiteralPath "$taskWorktree"

预期：列表中不再出现目标登记，Test-Path 返回 False。出现锁定、子模块、未提交内容、文件占用等错误时，按真实错误处理并记录保留原因，不自动追加 --force、解锁或改用递归删除。

git worktree prune 只清理目录已经缺失的失效登记，不会删除仍存在的目录，也不需要在每次成功 remove 后执行。本地或远端分支删除不包含在本流程中，另按项目规则处理。

3. 记录清理或保留结果

有工单时在最终证据评论记录结果；无工单的直接实施项在结果报告记录即可：

• 已清理：记录目标路径及清理结果。
• 保留：记录路径、原因、负责清理的 Agent 或接手者和清理时机，例如“验收仍使用本目录预览，验收结束且停止预览后清理”。
• 验收在主分支进行时，可先清理临时目录，工单保持“待验收”；因验收保留的目录在验收结束、保留条件解除后清理并补记结果。

已合并、已推送的代码可从保留的提交重新建立 worktree；本地独有文件不因此自动可恢复，必须在移除前妥善处理。

测试数据与日志

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

无法执行的命令必须写入工单“未验证部分”。