docs: 重构命令和技能文档体系，规范化文档格式和内容组织

2026-01-13 10:25:18 +08:00
parent 5a05d5ab53
commit f31f198407
19 changed files with 1055 additions and 2342 deletions
--- a/skill/gitea/SKILL.md
+++ b/skill/gitea/SKILL.md
@@ -7,6 +7,51 @@ description: Comprehensive Gitea management tool for creating runners, workflows

 完整的 Gitea 管理工具，提供 Runner、Workflow、仓库的创建和管理功能。

+## 工作目录
+
+**重要：该技能和所有相关命令的工作目录统一为：**
+
+### macOS / Linux
+```bash
+~/.config/gitea/
+```
+
+### Windows
+```powershell
+# PowerShell
+$env:USERPROFILE\.config\gitea\
+
+# CMD
+%USERPROFILE%\.config\gitea\
+
+# 完整路径示例
+C:\Users\YourUsername\.config\gitea\
+```
+
+所有配置文件、Runner 目录、日志文件都存储在此目录下。请确保该目录具有适当的读写权限。
+
+**目录结构（所有平台通用）：**
+```
+.config/gitea/
+├── config.env          # 主配置文件（Gitea URL、Token、默认组织等）
+├── runners/            # Runner 配置目录
+│   └── runner-*/       # 各个 runner 的独立目录
+└── .gitignore          # Git 忽略文件（保护敏感信息）
+```
+
+**平台兼容性：**
+- **macOS**: `~/.config/gitea/`（完全支持）
+- **Linux**: `~/.config/gitea/`（完全支持）
+- **Windows**: `%USERPROFILE%\.config\gitea\`（Act Runner 支持，但该技能的命令和脚本需要适配）
+
+**Windows 用户注意事项：**
+- Gitea Act Runner 官方支持 Windows 平台（包括 Host 模式）
+- 该技能文档中的命令和脚本主要基于 Bash，Windows 用户需要：
+  - 使用 PowerShell 或 Git Bash 执行命令
+  - 调整路径格式（如将 `~/.config/gitea` 改为 `%USERPROFILE%\.config\gitea`）
+  - 在 workflow 中指定 `shell: powershell`
+- Windows 安装 act_runner：从 [官方 Releases](https://gitea.com/gitea/act_runner/releases) 下载 Windows 二进制文件
+
 ## 功能概览

 | 功能模块 | 文档 | 说明 |
--- a/skill/gitea/runner-management.md
+++ b/skill/gitea/runner-management.md
@@ -20,17 +20,35 @@ Gitea Act Runner 是 Gitea Actions 的 CI/CD 执行器，兼容 GitHub Actions w

 ### 执行模式

-| 模式 | 环境 | 适用场景 | Android SDK |
-|------|------|---------|-------------|
-| **Host Mode** | Native macOS/Linux | Android/iOS 构建、原生工具链 | macOS ARM64 支持 |
-| Docker Mode | Linux 容器 | 跨平台构建 | Linux ARM64 不支持 |
+| 模式 | 环境 | 适用场景 | 平台支持 |
+|------|------|---------|---------|
+| **Host Mode** | Native OS（macOS/Linux/Windows） | Android/iOS 构建、原生工具链 | 全平台支持 |
+| Docker Mode | Linux 容器 | 跨平台构建 | Linux/macOS（不支持 ARM64 Android） |

-**推荐**：macOS ARM64 使用 **Host Mode** 以支持 Android SDK。
+**推荐**：
+- **macOS ARM64**: 使用 **Host Mode** 以支持 Android SDK
+- **Windows**: 使用 **Host Mode**（需在 workflow 中指定 `shell: powershell`）
+- **Linux**: 两种模式均可，Docker Mode 隔离性更好
+
+**Windows Host Mode 注意事项**：
+- Bash 默认不可用，需在 workflow 中指定 shell：
+  ```yaml
+  defaults:
+    run:
+      shell: powershell
+  ```
+- 或者安装 Git Bash 并指定：
+  ```yaml
+  defaults:
+    run:
+      shell: bash
+  ```

 ## Runner 目录结构

 所有 Runner 配置统一管理在：

+### macOS / Linux
 ```
 ~/.config/gitea/runners/
 ├── runner-macbook-pro/         # Runner 1
@@ -42,23 +60,123 @@ Gitea Act Runner 是 Gitea Actions 的 CI/CD 执行器，兼容 GitHub Actions w
    └── ...
 ```

+### Windows
+```
+%USERPROFILE%\.config\gitea\runners\
+├── runner-desktop-pc\          # Runner 1
+│   ├── .runner                 # 注册信息（JSON）
+│   ├── config.yaml             # Runner 配置
+│   ├── cache\                  # Cache 目录
+│   └── workspace\              # 工作目录
+└── runner-laptop\              # Runner 2
+    └── ...
+```
+
+**Windows 用户提示**：
+- 完整路径示例：`C:\Users\YourUsername\.config\gitea\runners\`
+- 配置文件使用反斜杠路径：`workdir_parent: "C:\\Users\\YourUsername\\.config\\gitea\\runners\\runner-name\\workspace"`
+- 或在 YAML 中使用正斜杠（Windows 兼容）：`workdir_parent: "C:/Users/YourUsername/.config/gitea/runners/runner-name/workspace"`
+
 ## 前置要求

 ### 1. 安装 act_runner

+**macOS**:
 ```bash
 # 使用 Homebrew（推荐）
 brew install act_runner

-# 或手动下载
+# 或手动下载（ARM64）
 curl -sL https://gitea.com/gitea/act_runner/releases/download/v0.2.13/act_runner-0.2.13-darwin-arm64 \
  -o /usr/local/bin/act_runner
 chmod +x /usr/local/bin/act_runner

+# 或手动下载（x64）
+curl -sL https://gitea.com/gitea/act_runner/releases/download/v0.2.13/act_runner-0.2.13-darwin-amd64 \
+  -o /usr/local/bin/act_runner
+chmod +x /usr/local/bin/act_runner
+
 # 验证安装
 act_runner --version
 ```

+**Linux**:
+```bash
+# 手动下载（x64）
+curl -sL https://gitea.com/gitea/act_runner/releases/download/v0.2.13/act_runner-0.2.13-linux-amd64 \
+  -o /usr/local/bin/act_runner
+chmod +x /usr/local/bin/act_runner
+
+# 或（ARM64）
+curl -sL https://gitea.com/gitea/act_runner/releases/download/v0.2.13/act_runner-0.2.13-linux-arm64 \
+  -o /usr/local/bin/act_runner
+chmod +x /usr/local/bin/act_runner
+
+# 验证安装
+act_runner --version
+```
+
+**Windows**:
+
+**方法 1: 使用 Scoop（推荐）**
+```powershell
+# 安装 Scoop（如果尚未安装）
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression
+
+# 添加 extras bucket
+scoop bucket add extras
+
+# 安装 act_runner（如果 Scoop 仓库中有）
+# 注意：截至目前可能需要手动下载
+
+# 验证安装
+act_runner --version
+```
+
+**方法 2: 手动下载（推荐）**
+```powershell
+# 下载最新版本（x64）
+$version = "v0.2.13"
+$arch = "amd64"
+$url = "https://gitea.com/gitea/act_runner/releases/download/$version/act_runner-$version-windows-$arch.exe"
+
+# 创建安装目录
+New-Item -Path "$env:USERPROFILE\bin" -ItemType Directory -Force
+
+# 下载
+Invoke-WebRequest -Uri $url -OutFile "$env:USERPROFILE\bin\act_runner.exe"
+
+# 添加到 PATH（永久）
+[Environment]::SetEnvironmentVariable(
+    "Path",
+    [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:USERPROFILE\bin",
+    "User"
+)
+
+# 刷新当前会话的 PATH
+$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")
+
+# 验证安装
+act_runner --version
+```
+
+**方法 3: 使用 Chocolatey**
+```powershell
+# 安装 Chocolatey（如果尚未安装）
+Set-ExecutionPolicy Bypass -Scope Process -Force
+[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
+iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
+
+# 注意：act_runner 可能尚未在 Chocolatey 仓库中，需要手动下载
+```
+
+**通用验证**:
+```bash
+# 所有平台
+act_runner --version
+```
+
 ### 2. 安装开发工具（可选，根据需要）

 ```bash
--- a/skill/gitea/setup-guide.md
+++ b/skill/gitea/setup-guide.md
@@ -12,6 +12,7 @@ Gitea skill 需要配置连接信息才能与你的 Gitea 实例交互。配置

 ## 配置目录结构

+### macOS / Linux
 ```
 ~/.config/gitea/
 ├── config.env          # 主配置文件（包含 URL、Token、默认组织等）
@@ -20,6 +21,20 @@ Gitea skill 需要配置连接信息才能与你的 Gitea 实例交互。配置
 └── .gitignore          # Git 忽略文件（保护敏感信息）
 ```

+### Windows
+```
+%USERPROFILE%\.config\gitea\
+├── config.env          # 主配置文件（包含 URL、Token、默认组织等）
+├── runners\            # Runner 配置目录
+│   └── runner-*\       # 各个 runner 的独立目录
+└── .gitignore          # Git 忽略文件（保护敏感信息）
+```
+
+**Windows 用户提示**：
+- 配置文件路径示例：`C:\Users\YourUsername\.config\gitea\config.env`
+- 可以在 PowerShell 中使用 `$env:USERPROFILE` 变量
+- 在 CMD 中使用 `%USERPROFILE%` 环境变量
+
 ## 快速配置

 ### 方法 1: 使用交互式向导（推荐）
@@ -48,6 +63,7 @@ AI 会自动启动配置向导。

 如果你熟悉配置格式，可以手动创建：

+**macOS / Linux**:
 ```bash
 mkdir -p ~/.config/gitea/runners
 cat > ~/.config/gitea/config.env << 'EOF'
@@ -62,6 +78,45 @@ EOF
 chmod 600 ~/.config/gitea/config.env
 ```

+**Windows PowerShell**:
+```powershell
+# 创建目录
+New-Item -Path "$env:USERPROFILE\.config\gitea\runners" -ItemType Directory -Force
+
+# 创建配置文件
+@"
+GITEA_URL=https://git.digitevents.com
+GITEA_TOKEN=your_personal_access_token
+GITEA_DEFAULT_ORG=your_org_name
+
+GITEA_RUNNER_CAPACITY=2
+GITEA_RUNNER_TIMEOUT=3h
+"@ | Out-File -FilePath "$env:USERPROFILE\.config\gitea\config.env" -Encoding utf8
+
+# 设置文件权限（仅所有者可读）
+$acl = Get-Acl "$env:USERPROFILE\.config\gitea\config.env"
+$acl.SetAccessRuleProtection($true, $false)
+$rule = New-Object System.Security.AccessControl.FileSystemAccessRule($env:USERNAME, "Read,Write", "Allow")
+$acl.SetAccessRule($rule)
+Set-Acl "$env:USERPROFILE\.config\gitea\config.env" $acl
+```
+
+**Windows CMD**:
+```cmd
+:: 创建目录
+mkdir "%USERPROFILE%\.config\gitea\runners"
+
+:: 创建配置文件
+(
+echo GITEA_URL=https://git.digitevents.com
+echo GITEA_TOKEN=your_personal_access_token
+echo GITEA_DEFAULT_ORG=your_org_name
+echo.
+echo GITEA_RUNNER_CAPACITY=2
+echo GITEA_RUNNER_TIMEOUT=3h
+) > "%USERPROFILE%\.config\gitea\config.env"
+```
+
 ## 交互式配置流程

 ### 步骤 1: 输入 Gitea 实例地址