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

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

Browse Source
This commit is contained in:
voson
2026-01-13 10:25:18 +08:00
parent 5a05d5ab53
commit f31f198407
19 changed files with 1055 additions and 2342 deletions
Download Patch File Download Diff File Expand all files Collapse all files

338
command/gitea-reset.md
View File

@@ -1,70 +1,47 @@
---
description: Reset Gitea configuration with interactive setup wizard
agent: general
subtask: true
---
# gitea-reset
Launch an interactive configuration wizard to set up or reset Gitea configuration.
重置 Gitea 配置，启动交互式配置向导。
## 工作目录
## Features
- 交互式引导配置
- 验证 URL 和 Token
- 检查 Token 权限
- 自动保存配置到 `~/.config/gitea/config.env`
- 创建必要的目录结构
## Steps
### 1. Create Configuration Directory
```bash
config_dir="$HOME/.config/gitea"
config_file="$config_dir/config.env"
# Create directories
mkdir -p "$config_dir/runners"
echo "开始 Gitea 配置向导..."
echo ""
**macOS / Linux:**
```
~/.config/gitea/
```
### 2. Input Gitea URL
```bash
read -p "请输入 Gitea 实例地址 (例如: https://git.digitevents.com): " gitea_url
# Validate URL format
if ! [[ "$gitea_url" =~ ^https?:// ]]; then
echo "❌ URL 必须以 http:// 或 https:// 开头"
exit 1
fi
# Remove trailing slash
gitea_url="${gitea_url%/}"
echo "✓ URL: $gitea_url"
**Windows:**
```
%USERPROFILE%\.config\gitea\
```
### 3. Input Personal Access Token
配置文件和 Runner 目录都将存储在此位置。
Please perform the following:
1. **Create configuration directory:**
**macOS / Linux:**
```bash
echo ""
read -sp "请输入 Personal Access Token: " gitea_token
echo ""
if [ -z "$gitea_token" ]; then
echo "❌ Token 不能为空"
exit 1
fi
echo "✓ Token 已输入"
mkdir -p ~/.config/gitea/runners
```
**Token 获取提示**：
**Windows PowerShell:**
```powershell
New-Item -Path "$env:USERPROFILE\.config\gitea\runners" -ItemType Directory -Force
```
在用户输入 Token 前，可以显示帮助信息：
2. **Interactive input - Gitea URL:**
- Prompt: "请输入 Gitea 实例地址 (例如: https://git.digitevents.com):"
- Validate: Must start with http:// or https://
- Remove trailing slash
3. **Interactive input - Personal Access Token:**
- Prompt: "请输入 Personal Access Token:"
- Before input, show help:
```
提示：获取 Personal Access Token 的步骤：
1. 登录 Gitea
@@ -75,221 +52,58 @@ echo "✓ Token 已输入"
6. 点击 "生成令牌"
7. 复制生成的 Token
```
- Validate: Not empty
- Use `read -sp` for secure input (password style)
### 4. Test Connection
4. **Test connection:**
- API: `GET ${GITEA_URL}/api/v1/user`
- If fails: Show error and possible reasons
- If success: Show username
5. **Validate token permissions:**
- Check `repo`: `GET /api/v1/user/repos` (required)
- Check `admin:org`: `GET /api/v1/user/orgs` (optional, for org runners)
- Check `write:runner`: Try to get registration token (optional, for runners)
- Warn if missing required permissions
6. **Input default organization (optional):**
- Prompt: "请输入默认组织名称 (回车跳过):"
- If provided, validate it exists: `GET /api/v1/orgs/${org_name}`
7. **Save configuration:**
**macOS / Linux** - Save to `~/.config/gitea/config.env`:
```bash
echo ""
echo "正在测试连接..."
response=$(curl -s -w "\n%{http_code}" \
-H "Authorization: token $gitea_token" \
"${gitea_url}/api/v1/user")
http_code=$(echo "$response" | tail -n1)
body=$(echo "$response" | sed '$d')
if [ "$http_code" != "200" ]; then
echo "❌ 连接失败 (HTTP $http_code)"
echo "请检查："
echo " - URL 是否正确"
echo " - Token 是否有效"
echo " - 网络连接是否正常"
exit 1
fi
username=$(echo "$body" | jq -r '.login')
echo "✓ 连接成功！"
echo "✓ 登录用户: $username"
```
### 5. Validate Token Permissions
```bash
echo ""
echo "正在检查 Token 权限..."
# Check repo permission
if curl -s -o /dev/null -w "%{http_code}" \
-H "Authorization: token $gitea_token" \
"${gitea_url}/api/v1/user/repos" | grep -q "200"; then
echo " ✓ repo (仓库管理)"
has_repo=true
else
echo " ✗ repo (仓库管理) - 缺少"
has_repo=false
fi
# Check org permission
if curl -s -o /dev/null -w "%{http_code}" \
-H "Authorization: token $gitea_token" \
"${gitea_url}/api/v1/user/orgs" | grep -q "200"; then
echo " ✓ admin:org (组织管理)"
has_org=true
else
echo " ⚠ admin:org (组织管理) - 缺少（创建组织 Runner 时需要）"
has_org=false
fi
# Check runner permission (try to get a registration token)
if curl -s -o /dev/null -w "%{http_code}" \
-H "Authorization: token $gitea_token" \
"${gitea_url}/api/v1/user/actions/runners/registration-token" 2>/dev/null | grep -q "200"; then
echo " ✓ write:runner (Runner 管理)"
has_runner=true
else
echo " ⚠ write:runner (Runner 管理) - 缺少（创建 Runner 时需要）"
has_runner=false
fi
# Warning if missing critical permissions
if [ "$has_repo" = false ]; then
echo ""
echo "❌ 缺少必需的 repo 权限"
read -p "是否继续? [y/N] " continue_anyway
if [[ ! "$continue_anyway" =~ ^[Yy]$ ]]; then
echo "已取消，请重新创建具有足够权限的 Token"
exit 1
fi
fi
```
### 6. Input Default Organization (Optional)
```bash
echo ""
echo "设置默认组织（可选）："
echo " - 创建仓库时，如果不指定 owner，将使用默认组织"
echo " - 创建组织级 Runner 时使用"
echo ""
read -p "请输入默认组织名称 (回车跳过): " default_org
if [ -n "$default_org" ]; then
# Validate organization exists
echo "正在验证组织..."
org_response=$(curl -s -w "\n%{http_code}" \
-H "Authorization: token $gitea_token" \
"${gitea_url}/api/v1/orgs/${default_org}")
org_http_code=$(echo "$org_response" | tail -n1)
if [ "$org_http_code" = "200" ]; then
echo "✓ 组织验证成功: $default_org"
else
echo "⚠️ 组织 '$default_org' 不存在或无权限访问"
read -p "仍然设置为默认组织? [Y/n] " set_anyway
if [[ "$set_anyway" =~ ^[Nn]$ ]]; then
default_org=""
fi
fi
fi
```
### 7. Save Configuration
```bash
echo ""
echo "正在保存配置..."
cat > "$config_file" << EOF
# Gitea Configuration
# Generated at $(date '+%Y-%m-%d %H:%M:%S')
GITEA_URL=$gitea_url
GITEA_TOKEN=$gitea_token
${default_org:+GITEA_DEFAULT_ORG=$default_org}
# Runner Default Settings
GITEA_URL=...
GITEA_TOKEN=...
GITEA_DEFAULT_ORG=... (if set)
GITEA_RUNNER_CAPACITY=2
GITEA_RUNNER_TIMEOUT=3h
# Optional: Override auto-detected labels
# GITEA_RUNNER_LABELS=custom-label-1:host,custom-label-2:host
EOF
# Set restrictive permissions
chmod 600 "$config_file"
# Create .gitignore
cat > "$config_dir/.gitignore" << EOF
config.env
runners/*/.runner
runners/*/.env
EOF
echo "✓ 配置已保存"
echo ""
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "配置完成"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
echo " 配置文件: $config_file"
echo " Runner 目录: $config_dir/runners"
echo ""
echo "下一步："
echo " - 查看配置: /gitea-config"
echo " - 创建 Runner: 告诉 AI '创建一个 runner'"
echo " - 创建仓库: /create-gitea-repo <repo-name>"
echo ""
```
- Set permissions: `chmod 600 ~/.config/gitea/config.env`
- Create `.gitignore` to exclude sensitive files
## Configuration File Format
生成的 `~/.config/gitea/config.env` 文件格式：
**Windows** - Save to `%USERPROFILE%\.config\gitea\config.env`:
```bash
# Gitea Configuration
# Generated at 2026-01-12 22:00:00
GITEA_URL=https://git.digitevents.com
GITEA_TOKEN=git_xxxxxxxxxxxxxxxxxxxx
GITEA_DEFAULT_ORG=ai
# Runner Default Settings
GITEA_URL=...
GITEA_TOKEN=...
GITEA_DEFAULT_ORG=... (if set)
GITEA_RUNNER_CAPACITY=2
GITEA_RUNNER_TIMEOUT=3h
# Optional: Override auto-detected labels
# GITEA_RUNNER_LABELS=custom-label-1:host,custom-label-2:host
```
- Set file permissions to restrict access (see setup-guide.md for PowerShell script)
- Create `.gitignore` to exclude sensitive files
## Output Example
8. **Display completion summary in Chinese:**
**macOS / Linux:**
```
开始 Gitea 配置向导...
请输入 Gitea 实例地址 (例如: https://git.digitevents.com): https://git.digitevents.com
✓ URL: https://git.digitevents.com
请输入 Personal Access Token: ****************
✓ Token 已输入
正在测试连接...
✓ 连接成功！
✓ 登录用户: your_username
正在检查 Token 权限...
✓ repo (仓库管理)
✓ admin:org (组织管理)
✓ write:runner (Runner 管理)
设置默认组织（可选）：
- 创建仓库时，如果不指定 owner，将使用默认组织
- 创建组织级 Runner 时使用
请输入默认组织名称 (回车跳过): ai
正在验证组织...
✓ 组织验证成功: ai
正在保存配置...
✓ 配置已保存
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
配置完成
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
配置文件: /Users/voson/.config/gitea/config.env
Runner 目录: /Users/voson/.config/gitea/runners
配置文件: ~/.config/gitea/config.env
Runner 目录: ~/.config/gitea/runners
下一步：
- 查看配置: /gitea-config
@@ -297,18 +111,22 @@ GITEA_RUNNER_TIMEOUT=3h
- 创建仓库: /create-gitea-repo <repo-name>
```
## Security Notes
**Windows:**
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
配置完成
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- 配置文件权限设置为 `600`（仅所有者可读写）
- Token 不会在日志中显示
- 创建 `.gitignore` 文件排除敏感信息
- 建议定期轮换 Token（每 3-6 个月）
配置文件: %USERPROFILE%\.config\gitea\config.env
Runner 目录: %USERPROFILE%\.config\gitea\runners
## Notes
下一步：
- 查看配置: /gitea-config
- 创建 Runner: 告诉 AI '创建一个 runner'
- 创建仓库: /create-gitea-repo <repo-name>
```
- **必需权限**: `repo` - 创建和管理仓库
- **推荐权限**: `admin:org` - 创建组织级 Runner
- **推荐权限**: `write:runner` - 管理 Runner
- **可选权限**: `admin:repo_hook` - 配置 Webhooks
- Token 只显示一次，请妥善保管
- 重置配置不会影响已创建的 Runner，但 Runner 会继续使用旧的注册信息
**Security notes:**
- Config file permissions: 600 (owner read/write only)
- Token is never displayed after initial input
- Sensitive files excluded in .gitignore