175 lines
7.3 KiB
Markdown
175 lines
7.3 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: a94b4eaa509f351b77274f007ae882e9e696fc8b
|
||
synchronized_at: 2026-09-02T07:20:33Z
|
||
<!-- 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`。
|
||
|
||
### PowerShell 语法与外部命令
|
||
|
||
- Windows 环境默认使用当前 PowerShell 语法，不套用 Bash 的 heredoc、变量、路径、引号或反斜杠转义规则。只有明确调用 Bash、WSL 或 Git Bash，并确认路径与编码边界时，才使用 Bash 专用语法。
|
||
- 不需要变量展开的正则和字符串优先用单引号；单引号字符串内部的单引号写成两个单引号。需要变量展开时才使用双引号。
|
||
- 正则同时包含单双引号或转义复杂时，优先赋值给变量、使用 `rg -e`，或拆成语义等价的简单查询；不得为了避开转义改变 AND/OR 条件或重复执行无关搜索。
|
||
|
||
```powershell
|
||
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（`$`）等内容。起始标记后必须立即换行，结束标记必须单独占一行：
|
||
|
||
```powershell
|
||
@'
|
||
print("hello")
|
||
'@ | python -
|
||
```
|
||
|
||
`foreach`、`if` 等语句块不能裸放在管道左侧；需要管道输出时使用 `$()`、`@()` 或先赋值。普通命令输出无需包装：
|
||
|
||
```powershell
|
||
@(foreach ($number in 1..3) { $number }) |
|
||
Measure-Object
|
||
```
|
||
|
||
不要把含 `*` 的搜索路径直接作为 `rg` 路径参数。优先传入真实目录，并用 `-g/--glob` 让 ripgrep 筛选路径：
|
||
|
||
```powershell
|
||
rg -n -g '*.md' 'PowerShell' docs
|
||
```
|
||
|
||
只有确实需要把实体路径列表交给其他命令时，才使用 `Get-ChildItem` 展开并传递 `.FullName`；不要把 `Get-ChildItem -Filter` 设为所有 `rg` 搜索的固定前置。
|
||
|
||
### 文件编码
|
||
|
||
文件解码与控制台输出编码是不同问题。读取 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
|
||
```
|
||
|
||
无法执行的命令必须写入工单“未验证部分”。
|