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

- 新增：统一的 git 命令文档（add/commit/push/pull 等） - 新增：整合的 Gitea 技能文档（API、运行器、工作流等） - 新增：工作流模板（Android、Go、Node.js 等） - 移除：已弃用的旧命令脚本和发布脚本 - 改进：.gitignore 添加敏感文件保护规则 - 改进：AGENTS.md 完善了开发规范和示例此次重组统一了命令和技能的文档结构，便于后续维护和扩展。
2026-01-13 00:27:14 +08:00
parent 84a3b48d43
commit 5a05d5ab53
35 changed files with 9658 additions and 1609 deletions
--- a/skill/gitea/troubleshooting.md
+++ b/skill/gitea/troubleshooting.md
@@ -0,0 +1,692 @@
+# Gitea 故障排查
+
+常见问题的诊断和解决方案。
+
+## 配置问题
+
+### 1. 配置文件不存在
+
+**症状**：
+```
+❌ Gitea 未配置，请运行 /gitea-reset
+```
+
+**原因**：
+- 首次使用，未进行配置
+- 配置文件被删除或移动
+
+**解决方案**：
+```bash
+/gitea-reset
+```
+
+按照提示完成配置。
+
+---
+
+### 2. Token 无效或已过期
+
+**症状**：
+```
+Token 状态: ✗ 无效或已过期
+```
+
+**原因**：
+- Token 已过期
+- Token 被撤销
+- Token 复制不完整
+
+**解决方案**：
+
+1. 重新生成 Token：
+   - 登录 Gitea → 设置 → 应用 → 访问令牌
+   - 生成新 Token（权限：repo, admin:org, write:runner）
+   
+2. 更新配置：
+   ```bash
+   /gitea-reset
+   ```
+
+3. 或手动编辑配置文件：
+   ```bash
+   vim ~/.config/gitea/config.env
+   # 更新 GITEA_TOKEN=new_token
+   ```
+
+---
+
+### 3. 连接 Gitea 失败
+
+**症状**：
+```
+❌ 连接失败 (HTTP 404)
+❌ 连接失败 (HTTP 500)
+```
+
+**原因**：
+- URL 错误
+- 网络问题
+- Gitea 服务器宕机
+
+**诊断步骤**：
+
+1. 检查 URL：
+   ```bash
+   source ~/.config/gitea/config.env
+   echo $GITEA_URL
+   ```
+
+2. 测试网络连接：
+   ```bash
+   curl -s "$GITEA_URL/api/v1/version"
+   ```
+
+3. 在浏览器中访问 URL
+
+**解决方案**：
+- 修正 URL（不要包含 `/api/v1`）
+- 检查网络连接
+- 联系 Gitea 管理员
+
+---
+
+### 4. 权限不足
+
+**症状**：
+```
+❌ 权限不足 (HTTP 403)
+⚠ 缺少 admin:org 权限
+```
+
+**原因**：
+- Token 权限不足
+- 不是组织成员
+
+**解决方案**：
+
+1. 重新创建 Token，选择更多权限
+2. 联系组织管理员添加为成员
+3. 使用个人仓库/Runner 代替组织级别
+
+---
+
+## Runner 问题
+
+### 1. Runner 创建失败
+
+**症状**：
+```
+❌ 获取注册 Token 失败
+❌ Runner 注册失败
+```
+
+**原因**：
+- Token 缺少 `write:runner` 权限
+- 组织不存在
+- 网络问题
+
+**诊断步骤**：
+
+1. 检查 Token 权限：
+   ```bash
+   /gitea-config
+   ```
+
+2. 验证组织存在：
+   ```bash
+   source ~/.config/gitea/config.env
+   curl -s -H "Authorization: token $GITEA_TOKEN" \
+     "$GITEA_URL/api/v1/orgs/$GITEA_DEFAULT_ORG"
+   ```
+
+**解决方案**：
+- 更新 Token 权限
+- 设置正确的组织：`/gitea-switch-org <org>`
+
+---
+
+### 2. Runner 无法启动
+
+**症状**：
+```bash
+act_runner daemon --config ...
+# 进程立即退出或报错
+```
+
+**原因**：
+- `act_runner` 未安装
+- 配置文件错误
+- 端口被占用（cache service）
+
+**诊断步骤**：
+
+1. 检查 act_runner：
+   ```bash
+   which act_runner
+   act_runner --version
+   ```
+
+2. 验证配置文件：
+   ```bash
+   cat ~/.config/gitea/runners/runner-name/config.yaml
+   ```
+
+3. 检查端口占用：
+   ```bash
+   lsof -i :9000
+   ```
+
+**解决方案**：
+
+1. 安装 act_runner：
+   ```bash
+   brew install act_runner
+   ```
+
+2. 修复配置文件（确保路径正确）
+
+3. 更改端口（如果 9000 被占用）：
+   ```bash
+   vim ~/.config/gitea/runners/runner-name/config.yaml
+   # 修改 port: 9001
+   ```
+
+---
+
+### 3. Runner 已注册但不在线
+
+**症状**：
+- Gitea 中看不到 Runner
+- Workflow 无法分配到 Runner
+
+**原因**：
+- Runner 进程未运行
+- 网络连接问题
+- Labels 不匹配
+
+**诊断步骤**：
+
+1. 检查 Runner 进程：
+   ```bash
+   /gitea-list-runners
+   ```
+
+2. 查看 Runner 日志：
+   ```bash
+   tail -f ~/.config/gitea/runners/runner-name/runner.log
+   ```
+
+3. 测试 Gitea 连接：
+   ```bash
+   source ~/.config/gitea/config.env
+   curl -s "$GITEA_URL/api/v1/version"
+   ```
+
+**解决方案**：
+
+1. 启动 Runner：
+   ```bash
+   act_runner daemon --config ~/.config/gitea/runners/runner-name/config.yaml
+   ```
+
+2. 检查网络和防火墙设置
+
+3. 验证 Labels 匹配
+
+---
+
+### 4. Labels 不匹配
+
+**症状**：
+```
+Workflow 一直 pending，不执行
+```
+
+**原因**：
+- Workflow 的 `runs-on` 与 Runner labels 不匹配
+
+**诊断步骤**：
+
+1. 检查 Runner labels：
+   ```bash
+   /gitea-list-runners
+   # 或
+   cat ~/.config/gitea/runners/runner-name/.runner | jq '.labels'
+   ```
+
+2. 检查 Workflow：
+   ```yaml
+   jobs:
+     build:
+       runs-on: darwin-arm64  # 这个 label 必须存在
+   ```
+
+**解决方案**：
+
+1. 修改 Workflow 的 `runs-on` 匹配 Runner labels
+2. 或重新创建 Runner 使用正确的 labels
+
+---
+
+## Workflow 问题
+
+### 1. Workflow 不触发
+
+**症状**：
+- 推送代码后 Workflow 不执行
+
+**原因**：
+- 路径过滤不匹配
+- 分支不匹配
+- Runner 不在线
+
+**诊断步骤**：
+
+1. 检查触发条件：
+   ```yaml
+   on:
+     push:
+       paths:
+         - 'backend/**'  # 确保修改的文件在此路径下
+   ```
+
+2. 检查 Runner 状态：
+   ```bash
+   /gitea-list-runners
+   ```
+
+**解决方案**：
+- 修改触发条件（删除或调整 `paths`）
+- 确保 Runner 在线
+- 检查 Gitea Actions 是否启用
+
+---
+
+### 2. Workflow 执行失败
+
+**症状**：
+```
+Job failed
+```
+
+**原因**：
+- 构建命令错误
+- 依赖缺失
+- Secret 未配置
+
+**诊断步骤**：
+
+1. 查看 Workflow 运行日志（在 Gitea UI 中）
+2. 检查 Secrets 配置
+3. 在本地手动执行构建命令
+
+**解决方案**：
+- 修复构建命令
+- 安装缺失的依赖
+- 配置必需的 Secrets
+
+---
+
+### 3. Cache 不生效
+
+**症状**：
+- 每次构建都重新下载依赖
+- 构建时间没有减少
+
+**原因**：
+- Cache key 每次都变化
+- Cache 目录不正确
+- Runner cache service 未启动
+
+**诊断步骤**：
+
+1. 检查 cache key：
+   ```yaml
+   key: cache-${{ hashFiles('**/lockfile') }}
+   # 确保 lockfile 路径正确
+   ```
+
+2. 检查 Runner 配置：
+   ```yaml
+   cache:
+     enabled: true
+     dir: "..."
+   ```
+
+**解决方案**：
+- 修正 cache key 的 hash 文件路径
+- 确保 Runner cache service 启用
+- 检查 cache 目录权限
+
+---
+
+## 仓库操作问题
+
+### 1. 创建仓库失败
+
+**症状**：
+```
+❌ 仓库已存在
+❌ Owner 不存在或无权限
+```
+
+**原因**：
+- 仓库名冲突
+- 组织不存在
+- Token 权限不足
+
+**诊断步骤**：
+
+1. 检查仓库是否存在：
+   ```bash
+   source ~/.config/gitea/config.env
+   curl -s -H "Authorization: token $GITEA_TOKEN" \
+     "$GITEA_URL/api/v1/repos/owner/repo"
+   ```
+
+2. 列出组织的所有仓库：
+   ```bash
+   curl -s -H "Authorization: token $GITEA_TOKEN" \
+     "$GITEA_URL/api/v1/orgs/owner/repos" | jq -r '.[].name'
+   ```
+
+**解决方案**：
+- 使用不同的仓库名
+- 验证组织名正确
+- 确保 Token 有 `repo` 权限
+
+---
+
+### 2. Git Remote 添加失败
+
+**症状**：
+```
+❌ origin remote 已存在
+```
+
+**原因**：
+- 已经配置了 origin remote
+
+**解决方案**：
+
+1. 查看现有 remote：
+   ```bash
+   git remote -v
+   ```
+
+2. 更新 remote URL：
+   ```bash
+   git remote set-url origin <new-url>
+   ```
+
+3. 或删除后重新添加：
+   ```bash
+   git remote remove origin
+   git remote add origin <new-url>
+   ```
+
+---
+
+## 开发环境问题
+
+### 1. Android SDK 未找到
+
+**症状**：
+```
+ANDROID_HOME not set
+SDK location not found
+```
+
+**原因**：
+- 未安装 Android SDK
+- 环境变量未配置
+- Runner 用户不同
+
+**诊断步骤**：
+
+1. 检查环境变量：
+   ```bash
+   echo $ANDROID_HOME
+   ls $ANDROID_HOME
+   ```
+
+2. 检查 Runner 用户：
+   ```bash
+   ps aux | grep act_runner
+   ```
+
+**解决方案**：
+
+1. 安装 Android SDK：
+   ```bash
+   brew install --cask android-commandlinetools
+   ```
+
+2. 配置环境变量（在 `~/.zshrc`）：
+   ```bash
+   export ANDROID_HOME=~/android-sdk
+   export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin
+   ```
+
+3. 确保 Runner 以正确用户运行
+
+---
+
+### 2. JDK 版本错误
+
+**症状**：
+```
+Android Gradle Plugin requires Java 17
+```
+
+**原因**：
+- JDK 版本过低
+- JAVA_HOME 指向错误版本
+
+**诊断步骤**：
+
+```bash
+java -version
+echo $JAVA_HOME
+```
+
+**解决方案**：
+
+1. 安装 JDK 17：
+   ```bash
+   brew install openjdk@17
+   ```
+
+2. 更新 JAVA_HOME：
+   ```bash
+   export JAVA_HOME=/opt/homebrew/opt/openjdk@17
+   export PATH=$PATH:$JAVA_HOME/bin
+   ```
+
+---
+
+## API 调用问题
+
+### 1. API 返回 404
+
+**原因**：
+- Endpoint 错误
+- 资源不存在
+- 组织/仓库名错误
+
+**解决方案**：
+- 检查 API 路径
+- 验证资源存在
+- 参考 [API 文档](./api-reference.md)
+
+---
+
+### 2. API 返回 401
+
+**原因**：
+- Token 无效
+- 未提供 Authorization header
+
+**解决方案**：
+- 检查 Token
+- 确保 header 格式正确：`Authorization: token YOUR_TOKEN`
+
+---
+
+### 3. API 返回 403
+
+**原因**：
+- 权限不足
+- Token 缺少必要权限
+
+**解决方案**：
+- 重新创建 Token，选择更多权限
+- 联系管理员提升权限
+
+---
+
+## 性能问题
+
+### 1. 构建速度慢
+
+**原因**：
+- 未使用缓存
+- 依赖下载慢
+- Runner 性能不足
+
+**解决方案**：
+
+1. 启用缓存：
+   ```yaml
+   - uses: https://github.com/actions/cache@v3
+     with:
+       path: ~/.cache
+       key: cache-${{ hashFiles('**/lockfile') }}
+   ```
+
+2. 使用镜像源（如 Go proxy、npm registry）
+
+3. 升级 Runner 硬件
+
+---
+
+### 2. Cache 占用空间大
+
+**原因**：
+- 长时间未清理
+- 多个 Runner 共享 cache
+
+**解决方案**：
+
+1. 定期清理：
+   ```bash
+   ~/.config/gitea/cleanup-cache.sh
+   ```
+
+2. 设置 crontab 自动清理：
+   ```bash
+   crontab -e
+   # 添加: 0 3 * * 0 ~/.config/gitea/cleanup-cache.sh
+   ```
+
+---
+
+## 诊断工具
+
+### 快速诊断脚本
+
+```bash
+#!/bin/bash
+echo "=== Gitea 环境诊断 ==="
+echo ""
+
+# 1. 配置文件
+echo "1. 配置文件:"
+config_file="$HOME/.config/gitea/config.env"
+if [ -f "$config_file" ]; then
+  echo "  ✓ 存在: $config_file"
+  source "$config_file"
+  echo "  URL: $GITEA_URL"
+else
+  echo "  ✗ 不存在"
+fi
+echo ""
+
+# 2. Token 验证
+if [ -n "$GITEA_TOKEN" ]; then
+  echo "2. Token 验证:"
+  response=$(curl -s -w "\n%{http_code}" \
+    -H "Authorization: token $GITEA_TOKEN" \
+    "${GITEA_URL}/api/v1/user")
+  http_code=$(echo "$response" | tail -n1)
+  if [ "$http_code" = "200" ]; then
+    echo "  ✓ 有效"
+  else
+    echo "  ✗ 无效 (HTTP $http_code)"
+  fi
+  echo ""
+fi
+
+# 3. Runner 状态
+echo "3. Runner 状态:"
+runners_dir="$HOME/.config/gitea/runners"
+if [ -d "$runners_dir" ]; then
+  runner_count=$(ls -1 "$runners_dir" 2>/dev/null | wc -l | tr -d ' ')
+  echo "  配置数量: $runner_count"
+  
+  for runner in $(ls -1 "$runners_dir" 2>/dev/null); do
+    config_file="$runners_dir/$runner/config.yaml"
+    if pgrep -f "act_runner daemon --config $config_file" > /dev/null; then
+      echo "  ✓ $runner (运行中)"
+    else
+      echo "  ✗ $runner (已停止)"
+    fi
+  done
+else
+  echo "  未配置 Runner"
+fi
+echo ""
+
+# 4. 工具检查
+echo "4. 工具检查:"
+for tool in act_runner jq curl git; do
+  if command -v $tool &> /dev/null; then
+    echo "  ✓ $tool"
+  else
+    echo "  ✗ $tool (未安装)"
+  fi
+done
+```
+
+保存为 `~/.config/gitea/diagnose.sh` 并执行：
+
+```bash
+chmod +x ~/.config/gitea/diagnose.sh
+~/.config/gitea/diagnose.sh
+```
+
+---
+
+## 获取帮助
+
+如果问题仍未解决：
+
+1. **查看日志**：
+   - Runner 日志：`~/.config/gitea/runners/runner-name/runner.log`
+   - Gitea UI 中的 Workflow 运行日志
+
+2. **检查文档**：
+   - [环境配置](./setup-guide.md)
+   - [Runner 管理](./runner-management.md)
+   - [API 参考](./api-reference.md)
+
+3. **联系支持**：
+   - Gitea 官方文档：https://docs.gitea.com/
+   - Gitea 社区论坛：https://discourse.gitea.io/
+
+---
+
+## 版本
+
+- **文档版本**: 1.0
+- **最后更新**: 2026-01-12