chore: 重构 OpenCode 命令和技能文档体系
- 新增：统一的 git 命令文档（add/commit/push/pull 等） - 新增：整合的 Gitea 技能文档（API、运行器、工作流等） - 新增：工作流模板（Android、Go、Node.js 等） - 移除：已弃用的旧命令脚本和发布脚本 - 改进：.gitignore 添加敏感文件保护规则 - 改进：AGENTS.md 完善了开发规范和示例 此次重组统一了命令和技能的文档结构，便于后续维护和扩展。
This commit is contained in:
Voson
343
skill/gitea/SKILL.md
Normal file
343
skill/gitea/SKILL.md
Normal file
@@ -0,0 +1,343 @@
|
||||
---
|
||||
name: gitea
|
||||
description: Comprehensive Gitea management tool for creating runners, workflows, and repositories with interactive setup
|
||||
---
|
||||
|
||||
# Gitea Management Skill
|
||||
|
||||
完整的 Gitea 管理工具，提供 Runner、Workflow、仓库的创建和管理功能。
|
||||
|
||||
## 功能概览
|
||||
|
||||
| 功能模块 | 文档 | 说明 |
|
||||
|---------|------|------|
|
||||
| 环境配置 | [setup-guide.md](./setup-guide.md) | 首次使用引导，配置 Gitea URL 和 Token |
|
||||
| Runner 管理 | [runner-management.md](./runner-management.md) | 创建、注册、管理 Gitea Act Runner |
|
||||
| Workflow 生成 | [workflow-generator.md](./workflow-generator.md) | 根据项目类型生成 CI/CD workflow |
|
||||
| 仓库操作 | [repository-operations.md](./repository-operations.md) | 创建和配置 Gitea 仓库 |
|
||||
| API 参考 | [api-reference.md](./api-reference.md) | Gitea API 常用接口 |
|
||||
| 故障排查 | [troubleshooting.md](./troubleshooting.md) | 常见问题解决方案 |
|
||||
|
||||
## 触发条件
|
||||
|
||||
当用户提到以下关键词时自动加载此 skill：
|
||||
- "gitea"、"runner"、"workflow"
|
||||
- "创建 runner"、"配置 runner"、"注册 runner"
|
||||
- "生成 workflow"、"CI/CD"
|
||||
- "创建仓库"、"gitea 仓库"
|
||||
- "gitea 配置"、"gitea token"
|
||||
|
||||
## 首次使用
|
||||
|
||||
**重要：** 首次使用前需要配置 Gitea 连接信息。
|
||||
|
||||
- 配置文件：`~/.config/gitea/config.env`
|
||||
- 如果文件不存在，自动启动交互式配置向导
|
||||
- 使用 `/gitea-config` 命令查看当前配置
|
||||
- 使用 `/gitea-reset` 命令重置配置
|
||||
|
||||
**新增：Actions Variables 自动注册**
|
||||
- 初始化时会自动将配置注册为用户级 variables
|
||||
- `GITEA_USERNAME` → `USERNAME` variable
|
||||
- `GITEA_WEBHOOK_URL` → `WEBHOOK_URL` variable
|
||||
- 可在所有个人仓库的 Actions workflow 中使用
|
||||
- 使用方式：`${{ vars.USERNAME }}`、`${{ vars.WEBHOOK_URL }}`
|
||||
|
||||
**重要**：Gitea 不允许 variable 名称以 `GITEA_` 或 `GITHUB_` 开头
|
||||
|
||||
详见：[环境配置指南](./setup-guide.md)
|
||||
|
||||
## 快速命令
|
||||
|
||||
| 命令 | 说明 |
|
||||
|------|------|
|
||||
| `/gitea-config` | 查看当前 Gitea 配置和 Runner 状态 |
|
||||
| `/gitea-reset` | 重置 Gitea 配置（交互式向导） |
|
||||
| `/gitea-switch-org` | 切换默认组织 |
|
||||
| `/gitea-create-runner` | 创建并启动新 Runner（默认 host 模式） |
|
||||
| `/gitea-list-runners` | 列出所有 Runner 及其状态 |
|
||||
| `/gitea-delete-runner` | 删除指定 Runner |
|
||||
| `/gitea-list-variables` | 列出用户级 Variables |
|
||||
| `/gitea-sync-variables` | 同步本地配置到 Gitea Variables |
|
||||
| `/gitea-create-repo` | 创建新仓库 |
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 配置 Gitea 连接
|
||||
|
||||
首次使用时，系统会自动引导你完成配置：
|
||||
|
||||
```
|
||||
请输入 Gitea 实例地址: https://git.digitevents.com
|
||||
请输入 Personal Access Token: ****************
|
||||
请输入默认组织名称（可选）: ai
|
||||
请输入 Gitea 用户名（用于 Actions）: your_username
|
||||
请输入 Gitea 密码: ********
|
||||
请输入 Actions 通知 Webhook URL（可选）: https://...
|
||||
|
||||
✓ 配置已保存到: ~/.config/gitea/config.env
|
||||
|
||||
正在注册用户级 Variables...
|
||||
✓ USERNAME 已创建 (来自 GITEA_USERNAME)
|
||||
✓ WEBHOOK_URL 已创建
|
||||
```
|
||||
|
||||
或使用命令：
|
||||
```bash
|
||||
/gitea-reset
|
||||
```
|
||||
|
||||
### 2. 创建 Runner
|
||||
|
||||
```bash
|
||||
/gitea-create-runner
|
||||
```
|
||||
|
||||
输出示例：
|
||||
```
|
||||
检查 act_runner 安装状态...
|
||||
✓ act_runner 已安装: act_runner version 0.2.13
|
||||
|
||||
✓ 已加载 Gitea 配置
|
||||
URL: https://git.digitevents.com
|
||||
|
||||
生成 Runner 名称: runner-macbook-pro
|
||||
|
||||
检测系统环境...
|
||||
✓ 系统信息
|
||||
操作系统: Darwin (macOS)
|
||||
架构: arm64 (ARM64)
|
||||
|
||||
✓ Runner Labels (Host Mode)
|
||||
self-hosted:host,macOS:host,ARM64:host,darwin-arm64:host
|
||||
|
||||
[自动创建目录、生成配置、注册并启动]
|
||||
|
||||
✅ Runner 创建完成！
|
||||
名称: runner-macbook-pro
|
||||
级别: global
|
||||
状态: 🟢 运行中
|
||||
PID: 12345
|
||||
```
|
||||
|
||||
**说明**：
|
||||
- 默认使用 Host Mode（支持 Android SDK、iOS 构建等）
|
||||
- 自动检查并安装 act_runner（如未安装）
|
||||
- 自动检测系统环境并生成合适的 labels
|
||||
- 优先创建全局 Runner（需要管理员 Token）
|
||||
- 权限不足时自动降级到组织 Runner
|
||||
- 自动后台启动
|
||||
|
||||
### 3. 生成 Workflow
|
||||
|
||||
```
|
||||
用户: 为我的 Go 项目生成 workflow
|
||||
AI: 检测到 Go 项目，服务目录: ./backend
|
||||
是否需要构建 Docker 镜像？[Y/n]
|
||||
[自动生成 .gitea/workflows/backend.yml]
|
||||
```
|
||||
|
||||
### 4. 创建仓库
|
||||
|
||||
```
|
||||
用户: /gitea-create-repo my-project
|
||||
AI: [使用配置的 Gitea URL 和默认组织创建仓库]
|
||||
✓ 仓库创建成功: ai/my-project
|
||||
```
|
||||
|
||||
## 配置管理
|
||||
|
||||
### 查看配置
|
||||
|
||||
```bash
|
||||
/gitea-config
|
||||
```
|
||||
|
||||
输出示例：
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
当前 Gitea 配置
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
URL: https://git.digitevents.com
|
||||
默认组织: ai
|
||||
Token 状态: ✓ 有效 (用户: your_username)
|
||||
配置文件: ~/.config/gitea/config.env
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Runner 信息
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
已配置 Runner 数量: 2
|
||||
Runner 目录: ~/.config/gitea/runners
|
||||
```
|
||||
|
||||
### 列出 Runners
|
||||
|
||||
```bash
|
||||
/gitea-list-runners
|
||||
```
|
||||
|
||||
### 切换组织
|
||||
|
||||
```bash
|
||||
/gitea-switch-org my-org
|
||||
```
|
||||
|
||||
### 重置配置
|
||||
|
||||
```bash
|
||||
/gitea-reset
|
||||
```
|
||||
|
||||
## 配置文件结构
|
||||
|
||||
```
|
||||
~/.config/gitea/
|
||||
├── config.env # 主配置文件（含认证信息和 Webhook）
|
||||
├── runners/ # Runner 配置目录
|
||||
│ ├── runner-macbook-pro/
|
||||
│ │ ├── .runner # Runner 注册信息
|
||||
│ │ ├── config.yaml # Runner 配置
|
||||
│ │ ├── cache/ # Cache 目录
|
||||
│ │ └── workspace/ # 工作目录
|
||||
│ └── runner-mac-mini/
|
||||
│ └── ...
|
||||
└── .gitignore # 忽略敏感文件
|
||||
```
|
||||
|
||||
**config.env 包含的配置项**：
|
||||
- `GITEA_URL`: Gitea 实例地址
|
||||
- `GITEA_TOKEN`: Personal Access Token
|
||||
- `GITEA_DEFAULT_ORG`: 默认组织
|
||||
- `GITEA_USERNAME`: Gitea 用户名（自动注册为 `USERNAME` variable）
|
||||
- `GITEA_PASSWORD`: Gitea 密码（仅本地使用）
|
||||
- `GITEA_WEBHOOK_URL`: Actions 通知 Webhook（自动注册为 `WEBHOOK_URL` variable）
|
||||
|
||||
## 使用流程
|
||||
|
||||
### 典型的 Gitea 项目设置流程
|
||||
|
||||
1. **初始化配置**（仅首次）
|
||||
```bash
|
||||
/gitea-reset
|
||||
```
|
||||
|
||||
2. **创建仓库**
|
||||
```bash
|
||||
/gitea-create-repo myorg/myproject
|
||||
```
|
||||
|
||||
3. **创建 Runner**（如果需要自托管 CI/CD）
|
||||
```bash
|
||||
/gitea-create-runner
|
||||
```
|
||||
|
||||
4. **生成 Workflow**
|
||||
```
|
||||
用户: 为这个项目生成 workflow
|
||||
```
|
||||
|
||||
5. **推送代码并触发 CI/CD**
|
||||
```bash
|
||||
git push origin main
|
||||
```
|
||||
|
||||
## Runner 管理
|
||||
|
||||
### 创建 Runner
|
||||
|
||||
使用命令快速创建：
|
||||
```bash
|
||||
/gitea-create-runner
|
||||
```
|
||||
|
||||
特性：
|
||||
- 自动检查并安装 act_runner
|
||||
- 自动检测系统环境（OS、架构）
|
||||
- 默认使用 Host Mode（支持原生工具）
|
||||
- 自动生成配置并启动
|
||||
- 优先创建全局 Runner
|
||||
|
||||
详见：[Runner 管理](./runner-management.md)
|
||||
|
||||
### 查看 Runner 状态
|
||||
|
||||
```bash
|
||||
/gitea-list-runners
|
||||
```
|
||||
|
||||
显示：
|
||||
- 运行状态（运行中/已停止）
|
||||
- PID
|
||||
- 配置信息（容量、超时、labels）
|
||||
- 启动命令
|
||||
|
||||
### 删除 Runner
|
||||
|
||||
```bash
|
||||
/gitea-delete-runner runner-macbook-pro
|
||||
```
|
||||
|
||||
会自动：
|
||||
- 停止运行中的进程
|
||||
- 可选从 Gitea 服务器注销
|
||||
- 删除所有相关文件（配置、cache、workspace）
|
||||
|
||||
## Workflow 模板
|
||||
|
||||
支持以下项目类型的 workflow 模板：
|
||||
|
||||
| 类型 | 模板文档 | 适用场景 |
|
||||
|------|---------|---------|
|
||||
| Go 后端 | [go-backend.md](./workflow-templates/go-backend.md) | API 服务、微服务、CLI 工具 |
|
||||
| Node.js 前端 | [nodejs-frontend.md](./workflow-templates/nodejs-frontend.md) | React/Vue/Vite/Next.js |
|
||||
| Android 应用 | [android-app.md](./workflow-templates/android-app.md) | Kotlin/Java/Jetpack Compose |
|
||||
| 微信小程序 | [wechat-miniprogram.md](./workflow-templates/wechat-miniprogram.md) | 微信小程序 CI/CD |
|
||||
|
||||
AI 会自动：
|
||||
- 检测项目类型
|
||||
- 选择合适的模板
|
||||
- 填充项目特定的变量（路径、服务名等）
|
||||
- 生成完整的 workflow 文件
|
||||
|
||||
详见：[Workflow 生成器](./workflow-generator.md)
|
||||
|
||||
## API 调用
|
||||
|
||||
所有与 Gitea 服务器的交互都通过 API 完成，使用配置文件中的：
|
||||
- `GITEA_URL`: Gitea 实例地址
|
||||
- `GITEA_TOKEN`: Personal Access Token
|
||||
|
||||
详见：[API 参考](./api-reference.md)
|
||||
|
||||
## 安全性
|
||||
|
||||
- 配置文件权限：`600`（仅所有者可读写）
|
||||
- Token 不会在日志中显示
|
||||
- `.gitignore` 自动排除敏感文件
|
||||
- 删除 runner 时可选择从服务器注销
|
||||
|
||||
## 故障排查
|
||||
|
||||
常见问题：
|
||||
- 连接失败：检查 URL 和网络
|
||||
- Token 无效：检查 Token 权限和有效期
|
||||
- Runner 无法启动：检查端口占用和权限
|
||||
- Workflow 无法触发：检查 labels 匹配
|
||||
|
||||
详见：[故障排查](./troubleshooting.md)
|
||||
|
||||
## 版本
|
||||
|
||||
- **Skill Version**: 1.0
|
||||
- **Last Updated**: 2026-01-12
|
||||
- **整合内容**: gitea-runner + gitea-workflow
|
||||
- **新增功能**: 统一配置管理、Runner CRUD、智能 labels 检测
|
||||
|
||||
## 相关资源
|
||||
|
||||
- [Gitea 官方文档](https://docs.gitea.com/)
|
||||
- [Gitea Actions 文档](https://docs.gitea.com/usage/actions/overview)
|
||||
- [Gitea API 文档](https://docs.gitea.com/api/1.20/)
|
||||
- [Act Runner 文档](https://docs.gitea.com/usage/actions/act-runner)
|
||||
Reference in New Issue
Block a user