docs: add workflow authoring checklist to README

2026-07-20 15:02:58 +08:00
1 changed files with 17 additions and 0 deletions
@@ -6,6 +6,23 @@ Gitea Actions 自托管 runner 的测试仓库，同时作为其他仓库编写
 - 参考 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