ai/opencode
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: 重构 OpenCode 命令和技能文档体系

Browse Source 
- 新增：统一的 git 命令文档（add/commit/push/pull 等）
- 新增：整合的 Gitea 技能文档（API、运行器、工作流等）
- 新增：工作流模板（Android、Go、Node.js 等）
- 移除：已弃用的旧命令脚本和发布脚本
- 改进：.gitignore 添加敏感文件保护规则
- 改进：AGENTS.md 完善了开发规范和示例

此次重组统一了命令和技能的文档结构，便于后续维护和扩展。
This commit is contained in:
Voson
2026-01-13 00:27:14 +08:00
parent 84a3b48d43
commit 5a05d5ab53
35 changed files with 9658 additions and 1609 deletions
Download Patch File Download Diff File Expand all files Collapse all files

603
skill/gitea/setup-guide.md Normal file
View File

@@ -0,0 +1,603 @@
# Gitea 环境配置指南
首次使用 Gitea skill 前的完整配置指南。
## 概述
Gitea skill 需要配置连接信息才能与你的 Gitea 实例交互。配置信息存储在：
```
~/.config/gitea/config.env
```
## 配置目录结构
```
~/.config/gitea/
├── config.env # 主配置文件（包含 URL、Token、默认组织等）
├── runners/ # Runner 配置目录
│ └── runner-*/ # 各个 runner 的独立目录
└── .gitignore # Git 忽略文件（保护敏感信息）
```
## 快速配置
### 方法 1: 使用交互式向导（推荐）
运行配置命令：
```bash
/gitea-reset
```
按照提示输入信息即可。
### 方法 2: 自然语言请求
直接告诉 AI：
```
用户: 配置 gitea
用户: 初始化 gitea 连接
用户: 设置 gitea 环境
```
AI 会自动启动配置向导。
### 方法 3: 手动创建配置文件
如果你熟悉配置格式，可以手动创建：
```bash
mkdir -p ~/.config/gitea/runners
cat > ~/.config/gitea/config.env << 'EOF'
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
EOF
chmod 600 ~/.config/gitea/config.env
```
## 交互式配置流程
### 步骤 1: 输入 Gitea 实例地址
```
请输入 Gitea 实例地址 (例如: https://git.digitevents.com):
```
**要求**：
- 必须以 `http://` 或 `https://` 开头
- 不要包含尾随斜杠
- 确保可以从当前网络访问
**示例**：
```
✓ https://git.digitevents.com
✓ https://gitea.example.com
✗ git.digitevents.com (缺少协议)
✗ https://gitea.com/ (包含尾随斜杠)
```
### 步骤 2: 输入 Personal Access Token
```
请输入 Personal Access Token:
```
**获取 Token 的步骤**：
1. 登录 Gitea
2. 点击右上角头像 → **设置**
3. 左侧菜单选择 **应用** → **访问令牌**
4. 点击 **生成新令牌**
5. 设置令牌名称（如 `opencode-cli`）
6. 选择权限（见下方推荐权限）
7. 点击 **生成令牌**
8. 复制生成的 Token（只显示一次！）
**推荐权限**：
| 权限 | 用途 | 是否必需 |
|------|------|---------|
| `repo` | 创建和管理仓库 | ✅ 必需 |
| `admin:org` | 创建组织级 Runner | ✅ 推荐 |
| `write:runner` | 管理 Runner | ✅ 推荐 |
| `write:user` | 创建用户级 Variables | ✅ 推荐 |
| `admin:repo_hook` | 配置 Webhooks | ⚠️ 可选 |
| `write:issue` | 创建 Release | ⚠️ 可选 |
**安全提示**：
- Token 等同于密码，请妥善保管
- 不要在公开场合分享 Token
- 定期轮换 Token（建议每 3-6 个月）
- 使用最小权限原则
### 步骤 3: 测试连接
```
正在测试连接...
✓ 连接成功！
```
系统会调用 Gitea API 验证：
- URL 是否可访问
- Token 是否有效
- 网络是否正常
**如果失败**：
- 检查 URL 是否正确
- 检查 Token 是否复制完整
- 检查网络连接
- 检查防火墙设置
### 步骤 4: 验证 Token 权限
```
正在检查 Token 权限...
✓ repo (仓库管理)
✓ admin:org (组织管理)
✓ write:runner (Runner 管理)
⚠ 缺少 admin:repo_hook 权限（可能影响 Webhook 配置）
```
系统会测试 Token 的实际权限，并给出建议。
**权限不足时**：
- 如果缺少必需权限，建议重新创建 Token
- 如果只缺少可选权限，可以继续使用
- 后续需要时可以更新 Token
### 步骤 5: 输入默认组织（可选）
```
请输入默认组织名称 (可选，回车跳过):
```
**作用**：
- 创建仓库时，如果不指定 owner，使用此默认组织
- 创建组织级 Runner 时使用
- 可以随时使用 `/gitea-switch-org` 切换
**示例**：
```
ai → 创建仓库时使用 ai/repo-name
my-team → 创建仓库时使用 my-team/repo-name
(留空) → 创建仓库时使用当前登录用户
```
**注意**：留空是完全可以的，系统会自动使用当前登录用户创建个人仓库。
### 步骤 6: 输入 Gitea 用户名（用于 Actions Variables）
```
请输入 Gitea 用户名 (将创建为用户级 variable):
```
**作用**：
- 此用户名将自动注册到 Gitea 用户级 variables（变量名：`USERNAME`）
- 可在所有个人仓库的 Actions workflow 中通过 `${{ vars.USERNAME }}` 使用
- 用于需要 Git 操作的 workflow（如推送代码、创建 tag 等）
**示例**：
```
your_username → 在 workflow 中可使用 ${{ vars.USERNAME }}
john → 你的 Gitea 登录用户名
```
**重要说明**：
- Gitea 不允许 variable 名称以 `GITEA_` 或 `GITHUB_` 开头
- 因此配置项 `GITEA_USERNAME` 会被注册为 `USERNAME` variable
- 如果此 variable 已存在于 Gitea 服务器，系统会自动更新为新值
### 步骤 7: 输入 Gitea 密码（用于 Actions）
```
请输入 Gitea 密码:
```
**作用**：
- 密码将存储在本地配置文件 `config.env` 中（权限 600）
- 用于需要认证的 Git 操作
- 也可以选择在 workflow 中使用 Secret 方式（需要手动创建）
**安全说明**：
- ✅ 配置文件权限为 600（仅所有者可读写）
- ✅ `.gitignore` 自动排除配置文件
- ⚠️ 不建议在公共环境使用明文密码
- 💡 建议使用 Personal Access Token 替代密码
**留空说明**：如果不需要在 workflow 中进行 Git 推送操作，可以留空。
### 步骤 8: 输入 Actions 通知 Webhook URL（可选）
```
请输入 Actions 通知 Webhook URL (可选，回车跳过):
```
**作用**：
- 用于 workflow 完成后发送通知到第三方平台（如飞书、钉钉、企业微信等）
- 此 URL 将自动注册到 Gitea 用户级 variables（变量名：`WEBHOOK_URL`）
- 可在 workflow 中通过 `${{ vars.WEBHOOK_URL }}` 使用
**示例**：
```
https://www.feishu.cn/flow/api/trigger-webhook/xxx (飞书)
https://oapi.dingtalk.com/robot/send?access_token=xxx (钉钉)
https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx (企业微信)
```
**使用方式**：
```yaml
- name: 发送通知
run: |
curl -X POST "${{ vars.WEBHOOK_URL }}" \
-H "Content-Type: application/json" \
-d '{"msg_type":"text","content":{"text":"构建完成"}}'
```
**说明**：
- 留空则不创建 `WEBHOOK_URL` variable
- 如果此 variable 已存在于 Gitea 服务器，系统会更新为新值
### 步骤 9: 注册用户级 Variables
```
正在检查并注册用户级 Variables...
检查 USERNAME...
✓ USERNAME 已创建
检查 WEBHOOK_URL...
✓ WEBHOOK_URL 已创建
```
系统会自动调用 Gitea API 创建以下用户级 variables：
| Variable 名称 | 来源配置 | 说明 |
|--------------|---------|------|
| `USERNAME` | `GITEA_USERNAME` | Gitea 用户名 |
| `WEBHOOK_URL` | `GITEA_WEBHOOK_URL` | Actions 通知 Webhook |
**重要**：Gitea 不允许 variable 名称以 `GITEA_` 或 `GITHUB_` 开头，所以 `GITEA_USERNAME` 配置项会被注册为 `USERNAME` variable。
**API 端点**：
```
POST /api/v1/user/actions/variables/{variable_name}
```
**在 Workflow 中使用**：
```yaml
steps:
- name: 使用 Variables
run: |
echo "用户名: ${{ vars.USERNAME }}"
echo "Webhook: ${{ vars.WEBHOOK_URL }}"
```
**查看已创建的 Variables**：
- 访问：`https://git.digitevents.com/user/settings/actions/variables`
- 或使用命令：`/gitea-list-variables`
### 步骤 10: 保存配置
```
✓ 配置已保存
配置文件: ~/.config/gitea/config.env
Runner 目录: ~/.config/gitea/runners
```
配置文件内容：
```bash
# Gitea Configuration
# Generated at 2026-01-12 22:30:00
GITEA_URL=https://git.digitevents.com
GITEA_TOKEN=git_xxxxxxxxxxxxxxxxxxxx
GITEA_DEFAULT_ORG=ai
# Gitea 仓库认证信息（用于 Actions）
GITEA_USERNAME=your_username
GITEA_PASSWORD=your_password_here
# Actions 通知 Webhook（可选）
GITEA_WEBHOOK_URL=https://www.feishu.cn/flow/api/trigger-webhook/xxx
# Runner Default Settings
GITEA_RUNNER_CAPACITY=2
GITEA_RUNNER_TIMEOUT=3h
# Optional: Override auto-detected labels
# GITEA_RUNNER_LABELS=custom-label-1:host,custom-label-2:host
```
## 配置验证
配置完成后，验证配置是否正确：
```bash
/gitea-config
```
应该看到：
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
当前 Gitea 配置
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
URL: https://git.digitevents.com
默认组织: ai
Token 状态: ✓ 有效 (用户: your_username)
配置文件: ~/.config/gitea/config.env
```
## 配置文件说明
### 必需配置项
| 配置项 | 说明 | 示例 |
|--------|------|------|
| `GITEA_URL` | Gitea 实例地址 | `https://git.digitevents.com` |
| `GITEA_TOKEN` | Personal Access Token | `git_xxxxxxxxxx` |
### 推荐配置项（用于 Actions）
| 配置项 | 说明 | 示例 | 自动创建为 Variable |
|--------|------|------|-------------------|
| `GITEA_USERNAME` | Gitea 用户名 | `your_username` | ✅ 是 → `USERNAME` |
| `GITEA_PASSWORD` | Gitea 密码 | `your_password` | ❌ 否（仅本地使用） |
| `GITEA_WEBHOOK_URL` | Actions 通知 Webhook | `https://...` | ✅ 是 → `WEBHOOK_URL` |
**说明**：
- 标记为 ✅ 的配置项会在初始化时自动创建为 Gitea 用户级 variables
- 这些 variables 可在所有个人仓库的 Actions workflow 中使用
- 使用方式：`${{ vars.USERNAME }}`、`${{ vars.WEBHOOK_URL }}`
- **注意**：Gitea 不允许 variable 名称以 `GITEA_` 或 `GITHUB_` 开头，所以会自动转换名称
### 可选配置项
| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `GITEA_DEFAULT_ORG` | 默认组织名称 | 无 |
| `GITEA_RUNNER_CAPACITY` | Runner 并发任务数 | `2` |
| `GITEA_RUNNER_TIMEOUT` | Runner 任务超时时间 | `3h` |
| `GITEA_RUNNER_LABELS` | 覆盖自动检测的 labels | 自动检测 |
### 自定义 Runner Labels
如果自动检测的 labels 不符合需求，可以手动覆盖：
```bash
# 编辑配置文件
vim ~/.config/gitea/config.env
# 取消注释并修改
GITEA_RUNNER_LABELS=self-hosted:host,linux:host,x64:host,custom:host
```
创建新 Runner 时会优先使用此配置。
## 配置管理
### 查看当前配置
```bash
/gitea-config
```
显示：
- Gitea URL
- 默认组织
- Token 状态和关联用户
- 已配置的 Runner 数量
- 配置文件路径
### 切换默认组织
```bash
/gitea-switch-org new-org-name
```
### 重置配置
```bash
/gitea-reset
```
会重新启动配置向导，覆盖现有配置。
**警告**：重置配置不会影响已创建的 Runner，但 Runner 会继续使用旧的注册信息。
### 更新配置
#### 方法 1: 使用命令（推荐）
```bash
/gitea-reset # 完整重置
/gitea-switch-org my-org # 只切换组织
```
#### 方法 2: 手动编辑
```bash
vim ~/.config/gitea/config.env
```
修改后无需重启，下次使用时自动生效。
## 多环境配置
如果需要管理多个 Gitea 实例，推荐做法：
### 方法 1: 使用不同的配置文件
```bash
# 开发环境
cp ~/.config/gitea/config.env ~/.config/gitea/config.dev.env
# 生产环境
cp ~/.config/gitea/config.env ~/.config/gitea/config.prod.env
# 使用时手动切换
cp ~/.config/gitea/config.prod.env ~/.config/gitea/config.env
```
### 方法 2: 创建切换脚本
```bash
# ~/.config/gitea/switch-env.sh
#!/bin/bash
case "$1" in
dev)
cp ~/.config/gitea/config.dev.env ~/.config/gitea/config.env
echo "✓ 切换到开发环境"
;;
prod)
cp ~/.config/gitea/config.prod.env ~/.config/gitea/config.env
echo "✓ 切换到生产环境"
;;
*)
echo "用法: $0 {dev|prod}"
exit 1
;;
esac
```
使用：
```bash
bash ~/.config/gitea/switch-env.sh dev
```
## 安全最佳实践
### 1. 文件权限
确保配置文件只有所有者可读写：
```bash
chmod 600 ~/.config/gitea/config.env
```
### 2. Token 安全
- ✅ 使用最小权限原则
- ✅ 定期轮换 Token
- ✅ 不要将 Token 提交到 Git
- ✅ 使用 `.gitignore` 排除配置文件
- ❌ 不要在公开场合分享 Token
- ❌ 不要使用永不过期的 Token
### 3. 配置备份
定期备份配置（移除 Token 后）：
```bash
# 创建备份（移除敏感信息）
grep -v "GITEA_TOKEN" ~/.config/gitea/config.env > ~/gitea-config-backup.env
```
### 4. .gitignore 配置
自动生成的 `.gitignore` 文件：
```
# ~/.config/gitea/.gitignore
config.env
runners/*/.runner
runners/*/.env
```
确保敏感文件不会被意外提交。
## 故障排查
### 连接失败
**症状**：
```
❌ 连接失败 (HTTP 404)
请检查 URL 和 Token 是否正确
```
**解决方案**：
1. 检查 URL 是否正确（不要包含 `/api/v1`）
2. 检查网络连接
3. 尝试在浏览器中访问 URL
4. 检查防火墙设置
### Token 无效
**症状**：
```
❌ 连接失败 (HTTP 401)
```
**解决方案**：
1. Token 可能已过期，重新生成
2. Token 可能被撤销，检查 Gitea 设置
3. Token 复制不完整，重新复制
4. 确认 Token 有足够的权限
### 权限不足
**症状**：
```
⚠ 缺少 admin:org 权限（可能影响组织 Runner 创建）
```
**解决方案**：
1. 重新创建 Token，选择更多权限
2. 联系 Gitea 管理员提升权限
3. 使用个人 Runner 而非组织 Runner
### 配置文件损坏
**症状**：
```
❌ 配置文件不完整，请运行 /gitea-reset 重新配置
```
**解决方案**：
```bash
/gitea-reset
```
## 下一步
配置完成后，你可以：
1. **创建第一个 Runner**（自动后台启动）：
```
用户: 创建一个 runner
```
- 默认创建全局 Runner（可用于所有组织和仓库）
- 如果 Token 没有管理员权限，自动降级到组织 Runner
- 创建后 Runner 会自动在后台运行
2. **创建仓库**：
```bash
/gitea-create-repo my-project
```
3. **生成 Workflow**：
```
用户: 为我的项目生成 workflow
```
4. **查看配置**：
```bash
/gitea-config
```
---
**相关文档**：
- [Runner 管理](./runner-management.md)
- [Workflow 生成器](./workflow-generator.md)
- [仓库操作](./repository-operations.md)
- [API 参考](./api-reference.md)