docs: add workflow authoring checklist to README

.gitea/workflows/build.yaml

@@ -10,8 +10,16 @@ jobs:
   build:
     runs-on: windows-latest
     steps:
+      # runner 到 github.com 网络不稳定，不使用 actions/checkout@v4，
+      # 改为直接从本 Gitea 实例克隆代码
       - name: Checkout
-        uses: actions/checkout@v4
+        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 }}
 
       - name: Install dependencies
         run: npm ci

README.md

@@ -0,0 +1,92 @@
+# Test_runner
+
+Gitea Actions 自托管 runner 的测试仓库，同时作为其他仓库编写 workflow 的参考。
+
+- 实例：https://gitea.docker.antior.cn/
+- 参考 workflow：[.gitea/workflows/build.yaml](.gitea/workflows/build.yaml)（push 到 main → esbuild 编译 → 打包 → 创建 Release 并上传产物）
+- runner 环境说明与人工部署手顺：[docs/add-runner.md](docs/add-runner.md)
+
+## 编写 workflow 注意点
+
+这台 runner 是一台 Windows 宿主机（host 模式），不是云端标准环境，写 workflow 时务必注意：
+
+1. **标签匹配**：`runs-on: windows-latest`（或 `windows` / `windows-amd64`）。写成 `ubuntu-latest` 等未注册标签，任务会永远排队。
+2. **不依赖 github.com**：runner 到 github.com 网络不稳定，禁止使用 `actions/checkout@v4` 等托管在 github.com 的 action。拉代码用实例克隆：
+   ```powershell
+   git clone https://x-access-token:${{ secrets.GITHUB_TOKEN }}@gitea.docker.antior.cn/${{ github.repository }}.git .
+   git checkout ${{ github.sha }}
+   ```
+   npm / pypi registry 目前可正常访问。
+3. **Windows 宿主机写法**：workflow 放 `.gitea/workflows/`（不是 `.github/`）；shell 是 PowerShell（建议显式 `shell: pwsh`），不要写 bash 语法；打包用 `Compress-Archive`。
+4. **工具链边界**：有 Node 22 / npm、Python 3.10–3.14（用 `py -X.Y` 显式指定版本，勿裸写 `python`）、pwsh、git、curl；没有 gcc / make / go / rust / docker。
+5. **发布方式**：用 Gitea API，token 用自动注入的 `${{ secrets.GITHUB_TOKEN }}`，地址用 `${{ gitea.server_url }}/api/v1`；tag 带 `${{ github.run_number }}` 保证唯一。
+
+完整约束见下面的 prompt 模板，可直接发给其他电脑的 agent 使用。
+
+## 给其他电脑 Agent 的 Prompt（复制即用）
+
+```text
+我的 Gitea 实例：https://gitea.docker.antior.cn/
+仓库已有一台在线的自托管 runner，请为本仓库编写 Gitea Actions workflow，
+实现：push 到 main 分支时自动编译/构建，并创建 Release、上传构建产物。
+
+【runner 环境约束 —— workflow 必须遵守】
+- runner 是 Windows 11 x64 宿主机模式（非 Docker），labels：windows-latest / windows / windows-amd64
+  → runs-on 必须用 windows-latest
+- 已安装工具链：
+  - 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 默认为 3.14）
+    → workflow 里必须用 py -X.Y 显式指定版本，不要只写 python（PATH 中的 python 是 3.12，可能与预期不符）
+  - PowerShell 7 (pwsh)、git、curl
+- 没有：gcc/make/go/rust/docker。不要引用依赖这些工具的步骤
+- workflow 文件放在 .gitea/workflows/ 目录（不是 .github/）
+- 默认 shell 是 PowerShell，写 run 步骤时用 PowerShell 语法，
+  或显式声明 shell: pwsh；不要写 bash 语法
+- 路径用 Windows 规则；产物打包用 Compress-Archive
+- runner 到 github.com 的网络不稳定，【禁止使用 actions/checkout@v4 等托管在 github.com 的 action】，
+  拉代码必须用下面的实例克隆步骤（npm/pypi registry 可正常访问）
+
+【拉取代码（代替 actions/checkout，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 }}
+
+【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 已创建。
+```

docs/add-runner.md

@@ -0,0 +1,119 @@
+# 添加 Gitea Actions Runner 人工手顺
+
+在 Windows 机器上手工部署一台宿主机模式（host）的 act_runner，注册到
+<https://gitea.docker.antior.cn/>。全程约 10 分钟。
+
+## 0. 前置条件
+
+- Windows 10/11 x64
+- 能访问 `https://gitea.docker.antior.cn/`（浏览器打开确认）
+- 一个 Gitea 账号：
+  - 注册**实例级** runner 需要管理员权限
+  - 只给某个仓库/组织用，仓库 Owner 也可以（在仓库 `设置 → Actions → Runners` 页面操作）
+- 本手顺以安装目录 `C:\Users\<用户名>\Gitea_worker` 为例，可按需替换
+
+## 1. 获取注册令牌（二选一）
+
+**方式 A：Web 页面**
+
+- 实例级：右上角头像 → 站点管理 → Actions → Runners → 创建新 Runner，复制注册令牌
+- 仓库级：仓库 → 设置 → Actions → Runners，同样位置复制
+
+**方式 B：管理员 API**
+
+```bash
+curl -X POST -H "Authorization: token <你的PAT>" \
+  https://gitea.docker.antior.cn/api/v1/admin/actions/runners/registration-token
+# 返回 {"token":"..."}
+```
+
+> 注册令牌一次性、有时效，注册时用掉即可，不需要保存。
+
+## 2. 下载 act_runner
+
+到 <https://gitea.com/gitea/runner/releases> 找最新版本，下载
+`gitea-runner-<版本>-windows-amd64.exe`，放入安装目录并重命名为 `act_runner.exe`：
+
+```bash
+mkdir -p /c/Users/$USER/Gitea_worker && cd /c/Users/$USER/Gitea_worker
+curl -sSL -o act_runner.exe \
+  https://gitea.com/gitea/runner/releases/download/v2.1.0/gitea-runner-2.1.0-windows-amd64.exe
+./act_runner.exe --version
+```
+
+## 3. 注册 runner
+
+```bash
+./act_runner.exe register --no-interactive \
+  --instance https://gitea.docker.antior.cn/ \
+  --token <注册令牌> \
+  --name "$(hostname)-windows" \
+  --labels "windows-latest:host,windows:host,windows-amd64:host"
+```
+
+- 看到 `Runner registered successfully.` 即成功，目录下会生成 `.runner` 凭证文件
+- **labels 说明**：`xxx:host` 表示直接在 Windows 宿主机上执行，不经过 Docker
+  - 本机没装 Docker，workflow 里 `runs-on` 只能用这几个自定义标签
+  - 若之后装了 Docker Desktop，可追加 `ubuntu-latest:docker://node:22` 之类的容器标签（需重新注册）
+
+## 4. 启动并验证
+
+```bash
+./act_runner.exe daemon
+# 看到 "declare successfully" 说明已连上实例，Ctrl+C 先停掉
+```
+
+再到 Web 页面（站点管理 → Actions → Runners）确认状态为**在线**。
+
+## 5. 配置开机自启（二选一）
+
+**方式 A：计划任务（首选）**
+
+```powershell
+schtasks /create /tn "GiteaActRunner" /sc onlogon /f `
+  /tr "wscript.exe \"C:\Users\<用户名>\Gitea_worker\run_hidden.vbs\""
+```
+
+**方式 B：启动文件夹（方式 A 提示"拒绝访问"时用）**
+
+在安装目录新建 `run_hidden.vbs`（隐藏窗口后台运行，日志写入 runner.log）：
+
+```vb
+Dim shell
+Set shell = CreateObject("WScript.Shell")
+shell.CurrentDirectory = "C:\Users\<用户名>\Gitea_worker"
+shell.Run "cmd /c act_runner.exe daemon >> runner.log 2>&1", 0, False
+```
+
+然后把它复制到启动文件夹（`Win+R` 输入 `shell:startup` 打开）：
+
+```
+%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\GiteaActRunner.vbs
+```
+
+立即启动一次（双击 vbs，或 `wscript run_hidden.vbs`），确认任务管理器里出现
+`act_runner.exe` 进程、Web 页面上 runner 在线。
+
+## 6. 日常使用
+
+- **日志**：`<安装目录>\runner.log`
+- **任务工作目录**：默认在安装目录下自动创建（`work/`、`.cache/`），首个任务运行后出现
+- **workflow 写法**：参考本仓库根目录 README 中的 prompt 模板和
+  [.gitea/workflows/build.yaml](../.gitea/workflows/build.yaml)
+
+## 7. 卸载
+
+1. 结束 `act_runner.exe` 进程
+2. 删除自启项：计划任务 `GiteaActRunner` 或启动文件夹里的 `GiteaActRunner.vbs`
+3. 删除安装目录
+4. Web 页面（站点管理 → Actions → Runners）删除该 runner 记录
+
+## 常见问题
+
+| 现象 | 原因 / 处理 |
+|---|---|
+| `schtasks` 提示"拒绝访问" | 组策略限制，改用方式 B（启动文件夹） |
+| workflow 一直排队不执行 | `runs-on` 标签与 runner labels 不匹配，改成 `windows-latest` |
+| 任务里 `docker`/`gcc`/`make` 找不到 | host 模式没有这些工具，见 README 的工具链清单 |
+| 注册时报令牌错误 | 注册令牌已过期或被用掉，重新生成一个 |
+| `actions/checkout` 步骤报 `github.com ... wsarecv` 连接失败 | runner 到 github.com 的网络不稳定（偶发）。处理：① 在 Actions 页面重跑该任务，多数情况重跑即成功；② 管理员可在服务端 `app.ini` 设 `[actions] DEFAULT_ACTIONS_URL` 指向可达镜像；③ workflow 里改用 `git clone https://x-access-token:${{ secrets.GITHUB_TOKEN }}@<实例域名>/${{ github.repository }}.git` 从实例拉代码，完全不依赖 github.com |