Test_runner/README.md

# Test_runner

Gitea Actions 自托管 runner 的测试仓库，同时作为其他仓库编写 workflow 的参考。

- 实例：https://gitea.docker.antior.cn/
- 参考 workflow：[.gitea/workflows/build.yaml](.gitea/workflows/build.yaml)（push 到 main → esbuild 编译 → 打包 → 创建 Release 并上传产物）
- Windows runner 人工部署手顺：[docs/add-runner.md](docs/add-runner.md)

## 现有 runner

同一台物理机上跑着两台 runner，写 workflow 先按需求选标签：

| 名称 | 模式 | labels | shell | 适用场景 |
|---|---|---|---|---|
| Lees-Desktop-windows | Windows 11 宿主机（host） | `windows-latest` / `windows` / `windows-amd64` | PowerShell | 需要 Windows 工具链、直接访问宿主机文件 |
| Lees-Desktop | WSL2 Ubuntu 22.04 + Docker（容器模式） | `ubuntu-latest` / `ubuntu-24.04` / `ubuntu-22.04` | bash（容器内） | 常规 Linux 构建，需要 root / apt / 干净一次性环境 |

## 编写 workflow 注意点（两台通用）

1. **标签匹配**：`runs-on` 必须是上表中的标签，写成未注册标签任务会永远排队。
2. **不依赖 github.com**：两台 runner 到 github.com 的网络都不稳定，禁止使用 `actions/checkout@v4` 等托管在 github.com 的 action。拉代码用实例克隆（见下文模板），npm / pypi registry 目前可正常访问。
3. **workflow 位置**：放 `.gitea/workflows/`（不是 `.github/`）。
4. **发布方式**：用 Gitea API，token 用自动注入的 `${{ secrets.GITHUB_TOKEN }}`，地址用 `${{ gitea.server_url }}/api/v1`；tag 带 `${{ github.run_number }}` 保证唯一。

### Windows runner（runs-on: windows-latest）

- shell 是 PowerShell（建议显式 `shell: pwsh`），不要写 bash 语法；路径用 Windows 规则；打包用 `Compress-Archive`。
- 工具链：Node 22 + npm 10、Python 3.10–3.14（用 `py -X.Y` 显式指定版本，勿裸写 `python`）、pwsh、git、curl。
- 没有 gcc / make / go / rust / docker。

### Linux runner（runs-on: ubuntu-latest）

- 作业运行在一次性 Docker 容器里（镜像 `docker.gitea.com/runner-images:ubuntu-*`，首次运行需拉取约 1GB+ 镜像），容器内是 root，可用 `apt` 安装依赖。
- 默认 shell 是 bash，写 Linux 语法即可。
- 镜像预装常用工具链（Node、Python、git 等），但**环境是一次性的**：不要在多个 job 之间依赖容器内的文件状态，产物传递用 Gitea Release 或上传 artifact。
- 容器里有 docker CLI 不可用（未挂载宿主机 docker.sock），不要在 job 里构建镜像。

完整约束见下面的 prompt 模板，可直接发给其他电脑的 agent 使用。

## 给其他电脑 Agent 的 Prompt（复制即用）

```text
我的 Gitea 实例：https://gitea.docker.antior.cn/
仓库有在线的自托管 runner（同一台机器上的两台，按需求二选一），
请为本仓库编写 Gitea Actions workflow，实现：push 到 main 分支时
自动编译/构建，并创建 Release、上传构建产物。

【runner 选择（runs-on 二选一）】
A. windows-latest：Windows 11 x64 宿主机模式（非 Docker），
   labels：windows-latest / windows / windows-amd64
B. ubuntu-latest：WSL2 + Docker 容器模式，
   labels：ubuntu-latest / ubuntu-24.04 / ubuntu-22.04，
   作业镜像 docker.gitea.com/runner-images:ubuntu-*

【共同约束 —— workflow 必须遵守】
- workflow 文件放在 .gitea/workflows/ 目录（不是 .github/）
- runner 到 github.com 的网络不稳定，【禁止使用 actions/checkout@v4 等
  托管在 github.com 的 action】，拉代码必须用下文实例克隆步骤
  （npm/pypi registry 可正常访问）
- 标签必须与所选 runner 匹配，否则任务永远排队

【A. Windows runner 环境约束】
- 已安装工具链：
  - Node.js v22 + npm 10（node/npm 直接在 PATH）
  - Python 3.10 / 3.11 / 3.12 / 3.13 / 3.14，通过 py launcher 调用
    （py -3.12 等）→ 必须用 py -X.Y 显式指定版本，不要只写 python
  - PowerShell 7 (pwsh)、git、curl
- 没有：gcc/make/go/rust/docker。不要引用依赖这些工具的步骤
- 默认 shell 是 PowerShell，run 步骤用 PowerShell 语法或显式 shell: pwsh，
  不要写 bash 语法；路径用 Windows 规则；产物打包用 Compress-Archive

【B. Linux runner 环境约束】
- 作业在一次性 Docker 容器中运行，容器内为 root，可 apt 安装依赖
- 默认 shell 是 bash；镜像预装 Node/Python/git 等常用工具
- 环境一次性：不要在 job 之间依赖容器内文件状态
- 容器内不能构建 docker 镜像（无 docker.sock）

【拉取代码（代替 actions/checkout）】
Windows（shell: pwsh）：

    - name: Checkout
      shell: pwsh
      env:
        GITEA_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      run: |
        $url = "${{ gitea.server_url }}/${{ github.repository }}.git" -replace '^https://', "https://x-access-token:$env:GITEA_TOKEN@"
        git clone $url .
        git checkout ${{ github.sha }}

Linux（bash）：

    - name: Checkout
      run: |
        git clone https://x-access-token:${{ secrets.GITHUB_TOKEN }}@gitea.docker.antior.cn/${{ github.repository }}.git .
        git checkout ${{ github.sha }}

【Release 发布方式】
用 Gitea API 发布，token 用自动注入的 ${{ secrets.GITHUB_TOKEN }}，
API 地址用 ${{ gitea.server_url }}/api/v1。参考步骤（shell: pwsh）：

    - name: Create Gitea release with artifact
      shell: pwsh
      env:
        GITEA_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      run: |
        $repo = "${{ github.repository }}"
        $tag = "v0.1.${{ github.run_number }}"
        $server = "${{ gitea.server_url }}"
        $headers = @{ Authorization = "token $env:GITEA_TOKEN" }
        $body = @{
          tag_name = $tag; name = "Build $tag"
          target_commitish = "${{ github.sha }}"
          draft = $false; prerelease = $true
        } | ConvertTo-Json
        $release = Invoke-RestMethod -Method Post -Uri "$server/api/v1/repos/$repo/releases" `
          -Headers $headers -Body $body -ContentType "application/json"
        Invoke-RestMethod -Method Post `
          -Uri "$server/api/v1/repos/$repo/releases/$($release.id)/assets?name=<产物文件名>" `
          -Headers $headers -Form @{ attachment = Get-Item "<产物文件路径>" }

tag 命名建议带 ${{ github.run_number }} 保证唯一，避免重复 tag 导致发布失败。
也可以直接参考本实例上 antior/Test_runner 仓库的 .gitea/workflows/build.yaml。

【本仓库信息】
- 项目类型：<比如 Node / Python / 纯静态文件>
- 构建命令：<比如 npm ci && npm run build，或 py -3.12 -m PyInstaller ...>
- 产物位置：<比如 dist/ 目录>
请生成 workflow 并提交 push，然后确认 Actions 运行成功、Release 已创建。
```