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

command/gitea-create-runner.md

@@ -1,52 +1,160 @@
 ---
 description: Create and start a Gitea Actions runner (default host mode)
+agent: general
+subtask: true
 ---
 
-# gitea-create-runner
+# 创建并启动 Gitea Actions Runner
 
-创建并启动 Gitea Actions Runner（默认 host 模式）。
+你的任务是创建并启动一个 Gitea Actions Runner（默认使用 host 模式）。
 
-## 命令说明
+## 工作目录
 
-此命令用于快速创建和启动一个 Gitea Actions Runner。默认使用 host 模式，自动检测系统环境并配置。
-
-**重要**：这是一个可执行命令，AI 应该按照以下步骤执行操作。
-
-## Features
-
-- 自动检查并安装 act_runner（如果未安装）
-- 自动加载 Gitea 配置（如果不存在则提示初始化）
-- 默认使用 host 模式（支持 Android SDK、iOS 构建等原生工具）
-- 智能检测系统环境（OS、架构）并生成合适的 labels
-- 自动注册并后台启动 runner
-- 优先尝试创建全局 runner（需要管理员权限）
-- 权限不足时自动降级到组织 runner
-
-## User Input Format
-
-无需参数，运行后自动创建。可选提供 runner 名称。
-
-```bash
-/gitea-create-runner
-# 或
-/gitea-create-runner my-runner-name
+**macOS / Linux:**
+```
+~/.config/gitea/
 ```
 
-## AI 执行指导
+**Windows:**
+```
+%USERPROFILE%\.config\gitea\
+```
 
-当用户调用此命令时，AI 应该：
+所有 Runner 配置、缓存、工作区都存储在该目录的 `runners/` 子目录下。
 
-1. **检查 act_runner 安装**：如果未安装，自动安装
-2. **加载 Gitea 配置**：如果不存在，提示用户先初始化
-3. **生成 runner 名称**：基于主机名或用户输入
-4. **检测系统环境**：自动生成 labels
-5. **创建 runner 目录**：在 `~/.config/gitea/runners/` 下创建
-6. **生成配置文件**：默认 host 模式配置
-7. **获取注册 token**：优先全局，失败则降级到组织
-8. **注册 runner**：使用 act_runner register
-9. **启动 runner**：后台启动并显示状态
+## 核心功能要求
 
-## Implementation Steps
+请按照以下步骤执行：
+
+1. **检查 act_runner 安装**
+   - 检查 act_runner 是否已安装（使用 `command -v act_runner`）
+   - 如果未安装，使用 Homebrew 自动安装：`brew install act_runner`
+   - 如果 Homebrew 不存在，提示用户安装 Homebrew
+   - 验证安装成功后显示版本信息
+
+2. **加载 Gitea 配置**
+   - 从配置文件加载配置：
+     - macOS/Linux: `~/.config/gitea/config.env`
+     - Windows: `%USERPROFILE%\.config\gitea\config.env`
+   - 如果配置文件不存在，提示用户运行 `/gitea-reset` 初始化
+   - 验证必需的配置项：`GITEA_URL` 和 `GITEA_TOKEN`
+   - 显示加载成功的配置信息
+
+3. **生成 Runner 名称**
+   - 如果用户提供了参数 `$ARGUMENTS`，使用该名称
+   - 否则默认基于主机名生成：`runner-$(hostname -s)`
+   - 验证名称只包含字母、数字、下划线和连字符
+
+4. **检查 Runner 是否已存在**
+   - 检查 Runner 目录：
+     - macOS/Linux: `~/.config/gitea/runners/$runner_name`
+     - Windows: `%USERPROFILE%\.config\gitea\runners\$runner_name`
+   - 如果已存在，提示用户可选操作：
+     - 使用其他名称
+     - 删除现有 runner（使用 `/gitea-delete-runner`）
+     - 查看所有 runners（使用 `/gitea-list-runners`）
+
+5. **检测系统环境**
+   - 检测操作系统（macOS/Linux）
+   - 检测架构（ARM64/x64）
+   - 生成 host 模式的 labels：
+     - `self-hosted:host`
+     - `{os_label}:host`（如 `macOS:host`）
+     - `{arch_label}:host`（如 `ARM64:host`）
+     - `{combined}:host`（如 `darwin-arm64:host`）
+
+6. **创建 Runner 目录结构**
+   - 创建目录结构：
+     - macOS/Linux: `~/.config/gitea/runners/$runner_name/{cache,workspace}`
+     - Windows: `%USERPROFILE%\.config\gitea\runners\$runner_name\{cache,workspace}`
+   - 验证目录创建成功
+
+7. **生成配置文件**
+   - 创建 `config.yaml`，使用 host 模式配置
+   - 从环境变量读取可选配置：
+     - `GITEA_RUNNER_CAPACITY`（默认 2）
+     - `GITEA_RUNNER_TIMEOUT`（默认 3h）
+   - 配置要点：
+     - log level: info
+     - runner.capacity: 并发任务数
+     - runner.timeout: 任务超时
+     - cache: 启用缓存
+     - host.workdir_parent: 工作目录路径
+     - labels: 使用检测到的系统 labels
+
+8. **获取注册 Token**
+   - 优先尝试创建全局 Runner（需要管理员权限）
+     - API: `GET ${GITEA_URL}/api/v1/admin/runners/registration-token`
+     - Header: `Authorization: token ${GITEA_TOKEN}`
+   - 如果返回 403/权限不足，自动降级到组织 Runner
+     - 使用 `GITEA_DEFAULT_ORG` 作为组织名
+     - API: `POST ${GITEA_URL}/api/v1/orgs/${org_name}/actions/runners/registration-token`
+   - 从响应中提取 token（JSON 格式）
+   - 记录使用的 runner 级别（global 或 organization）
+
+9. **注册 Runner**
+   - 执行命令：
+     ```bash
+     act_runner register \
+       --config "$runner_dir/config.yaml" \
+       --instance "$GITEA_URL" \
+       --token "$registration_token" \
+       --name "$runner_name" \
+       --labels "$labels" \
+       --no-interactive
+     ```
+   - 验证 `.runner` 文件是否创建
+   - 如果失败，提供诊断建议
+
+10. **后台启动 Runner**
+    - 使用 nohup 后台启动：
+      ```bash
+      nohup act_runner daemon --config "$runner_dir/config.yaml" \
+        > "$runner_dir/runner.log" 2>&1 &
+      ```
+    - 记录进程 PID
+    - 等待 3 秒初始化
+    - 验证进程仍在运行
+    - 如果失败，显示日志的最后 20 行
+
+11. **显示创建摘要**
+    - Runner 信息：名称、级别、模式、状态、PID
+    - 如果是组织级别，显示组织名
+    - 配置信息：容量、超时、labels
+    - 目录信息：配置文件、工作目录、缓存目录、日志文件
+    - 管理命令：查看日志、停止 Runner、查看所有、删除
+    - 使用示例：workflow 中的 runs-on 配置
+
+## 重要配置说明
+
+- **默认模式**：Host Mode（直接在宿主机执行，支持 Android SDK、iOS 构建等原生工具）
+- **目录结构**：
+  - macOS/Linux: 所有 runners 位于 `~/.config/gitea/runners/`
+  - Windows: 所有 runners 位于 `%USERPROFILE%\.config\gitea\runners\`
+- **优雅降级**：全局 runner 权限不足时自动降级到组织 runner
+- **后台运行**：使用 nohup 后台启动（Unix），或 Start-Process（Windows），日志输出到文件
+- **进程管理**：需要手动管理进程（系统重启后需重新启动）
+
+## 可选参数
+
+- `$ARGUMENTS`: Runner 名称（可选，默认基于主机名生成）
+
+使用示例：
+```
+/gitea-create-runner
+/gitea-create-runner my-custom-runner
+```
+
+## 相关命令
+
+- `/gitea-config`: 查看 Gitea 配置
+- `/gitea-reset`: 重置/初始化 Gitea 配置
+- `/gitea-list-runners`: 列出所有 runners
+- `/gitea-delete-runner`: 删除指定 runner
+
+---
+
+## 详细实现步骤（供 AI 参考）
 
 ### 1. Check act_runner Installation