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 # 本地开发与验证 ## 本页用途 让维护者能够安装、运行、检查和验证项目。所有命令默认在仓库根目录执行，示例以 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`。 ### 文件编码 文件解码与控制台输出编码是不同问题。读取 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. 检查工作区 - 目的：确认没有混入其他任务的修改。 - 命令：`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 不使用生产数据，也不需要固定业务测试数据。命令输出是主要诊断信息，不应包含令牌。如果复制到业务项目，应在本节写明： - 合成或脱敏测试数据的创建方式； - 日志路径和日志级别； - 请求或任务标识如何追踪； - 禁止使用的数据来源。 ## 完成修改前 依次执行： ```powershell 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 ``` 无法执行的命令必须写入工单“未验证部分”。