140 lines
5.6 KiB
Markdown
140 lines
5.6 KiB
Markdown
<!-- gitea-wiki-mirror:start -->
|
|
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
|
|
<!-- gitea-wiki-mirror:end -->
|
|
|
|
# 本地开发与验证
|
|
|
|
## 本页用途
|
|
|
|
让维护者能够安装、运行、检查和验证项目。所有命令默认在仓库根目录执行，示例以 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
|
|
```
|
|
|
|
无法执行的命令必须写入工单“未验证部分”。
|