smy-skills/gitea-tea-skill/SKILL.md

---
name: gitea-tea-skill
description: 使用 `tea` CLI 或直接调用 Gitea API 与 https://git.shumengya.top 交互。支持仓库、Issue、PR、Release 管理。默认脚本语言为 Python，辅助脚本零外部依赖。
---

# 萌芽 Gitea 操作指南

`tea` 是 Gitea 官方 CLI，同时本技能提供纯 Python 辅助脚本（零依赖），两者互补使用。

---

## 萌芽 Gitea 服务器信息

| 项目 | 值 |
|------|-----|
| **地址** | https://git.shumengya.top |
| **用户名** | `shumengya` |
| **默认令牌** | `dbc5dfe55b19e9a32f685a97f126cafc2ef76449` |
| **仓库基础路径** | `https://git.shumengya.top/shumengya` |
| **SSH 地址** | `git@git.shumengya.top:shumengya/<仓库名>.git` |
| **SSH 端口** | `8022` |
| **API 基础路径** | `https://git.shumengya.top/api/v1` |

---

## 方式一：tea CLI

### 前置检查

1. **检查 tea 是否已安装**：`tea --version`
   - 不存在则安装最新版：
     - Linux：`wget -qO- https://gitea.com/gitea/tea/releases/latest/download/tea-linux-amd64.tar.gz | tar -xz -C /usr/local/bin/ tea`
     - macOS：`brew install tea`
   - 如果 tea 版本太旧（如 0.1.0-dev），建议升级：
     ```bash
     # 备份旧 config
     cp ~/.tea/tea.yml ~/.tea/tea.yml.bak
     # 下载新版覆盖
     wget -qO- https://gitea.com/gitea/tea/releases/latest/download/tea-linux-amd64.tar.gz | tar -xz -C /usr/local/bin/ tea
     ```

2. **登录**
   ```bash
   tea login add --url https://git.shumengya.top --token dbc5dfe55b19e9a32f685a97f126cafc2ef76449 --name gitea-shumengya
   ```
   配置文件路径：`~/.tea/tea.yml`（Linux/macOS）

3. **已知问题与解决方案**
   - 旧版 tea（0.1.0-dev）的 `-l` flag 可能无效
   - **如果 tea 命令异常，直接改用方式二（API）或方式三（Python 脚本）**

### 常用命令

```bash
# 仓库
tea repos ls                           # 列出仓库
tea repos create --name <仓库名>        # 创建仓库
tea repos delete shumengya/<仓库名>     # 删除仓库

# Issue
tea issues list --state all -o json    # 列出所有 Issue（JSON 格式）
tea issues create -t "标题" -d "描述"
tea issues close <编号>
tea issues reopen <编号>

# Pull Request
tea pulls list                         # 列出 PR
tea pulls create -t "标题" -b main -d "描述"
tea pulls approve <编号>
tea pulls merge <编号>
tea pulls close <编号>

# Release
tea releases list
tea releases create --tag v1.0.0 --title "v1.0.0" --note "更新说明"
```

---

## 方式二：Gitea REST API（curl）

当 tea 不可用时，直接用 curl 操作。令牌已配置：

```bash
TOKEN="dbc5dfe55b19e9a32f685a97f126cafc2ef76449"
API="https://git.shumengya.top/api/v1"
```

### 仓库操作

```bash
# 列出所有仓库
curl -s -H "Authorization: token $TOKEN" "$API/user/repos" | python3 -m json.tool

# 列出指定用户的仓库
curl -s -H "Authorization: token $TOKEN" "$API/users/shumengya/repos" \
  | python3 -c "import sys,json; [print(r['name'], r['html_url']) for r in json.load(sys.stdin)]"

# 创建仓库（公开）
curl -s -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
  -X POST "$API/user/repos" \
  -d '{"name":"<仓库名>","description":"描述","private":false}'

# 创建仓库（私有）
curl -s -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
  -X POST "$API/user/repos" \
  -d '{"name":"<仓库名>","description":"描述","private":true}'

# 删除仓库
curl -s -H "Authorization: token $TOKEN" -X DELETE "$API/repos/shumengya/<仓库名>"

# 检查仓库是否存在
curl -s -o /dev/null -w "%{http_code}" -H "Authorization: token $TOKEN" \
  "$API/repos/shumengya/<仓库名>"
# 200=存在, 404=不存在
```

### 推送代码到新仓库

```bash
# 添加远程仓库
git remote add gitea https://git.shumengya.top/shumengya/<仓库名>.git
# 或使用 SSH（推荐，免输令牌）
git remote add gitea ssh://git@git.shumengya.top:8022/shumengya/<仓库名>.git

# 推送到 Gitea
git push gitea main
```

### Issue & PR 操作

```bash
# 列出仓库的所有 Issue
curl -s -H "Authorization: token $TOKEN" "$API/repos/shumengya/<仓库名>/issues"

# 创建 Issue
curl -s -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
  -X POST "$API/repos/shumengya/<仓库名>/issues" \
  -d '{"title":"标题","body":"描述内容"}'

# 关闭 Issue（编号 42）
curl -s -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
  -X PATCH "$API/repos/shumengya/<仓库名>/issues/42" \
  -d '{"state":"closed"}'

# 创建 PR
curl -s -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
  -X POST "$API/repos/shumengya/<仓库名>/pulls" \
  -d '{"title":"标题","head":"feature-branch","base":"main","body":"描述"}'
```

---

## 方式三：Python 辅助脚本（零依赖）

纯 Python 标准库，无需 `pip install`，直接运行。

### gitea_api.py — API 直连脚本

```bash
# 列出仓库
python scripts/gitea_api.py repos list

# 创建仓库
python scripts/gitea_api.py repos create sproutclaw --desc "项目描述"

# 删除仓库
python scripts/gitea_api.py repos delete sproutclaw

# 列出 Issue
python scripts/gitea_api.py issues list --repo shumengya/sproutclaw

# 创建 Issue
python scripts/gitea_api.py issues create --repo shumengya/sproutclaw --title "标题" --body "描述"
```

### tea_helper.py — tea CLI 包装脚本

```bash
# 依赖 tea CLI 本身
python scripts/tea_helper.py issues           # 列出 Issue
python scripts/tea_helper.py prs              # 列出 PR
python scripts/tea_helper.py releases         # 列出 Release
python scripts/tea_helper.py close-issue 42   # 关闭 Issue
python scripts/tea_helper.py triage           # 按标签分组 Issue
```

---

## 快速工作流示例

### 场景：将本地项目上传到 Gitea（基于 sproutclaw 实战）

```bash
# 1. 在 Gitea 上创建仓库
curl -s -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
  -X POST "$API/user/repos" \
  -d '{"name":"sproutclaw","description":"项目描述","private":false}'

# 2. 添加 Gitea 远程（SSH 方式）
git remote add gitea ssh://git@git.shumengya.top:8022/shumengya/sproutclaw.git

# 3. 提交本地变更并推送
git add -A
git commit -m "chore: sync to gitea"
git push gitea main
```

### 场景：从零创建并推送

```bash
# 使用 Python 脚本一键创建仓库
python scripts/gitea_api.py repos create <仓库名> --desc "<描述>"

# 添加远程
git remote add gitea ssh://git@git.shumengya.top:8022/shumengya/<仓库名>.git

# 推送
git push -u gitea main
```

---

## 补充说明

- **令牌变更**：更新令牌时只需修改 `~/.tea/tea.yml` 中的 `token` 字段，或重新执行 `tea login add`
- **双远程工作流**：项目同时有 GitHub（`origin`）和 Gitea（`gitea`）远程时，推送时需指定：
  ```bash
  git push origin main      # 推送到 GitHub
  git push gitea main       # 推送到 Gitea
  ```
- **参考文档**：[reference.md](reference.md) | [Gitea API 官方文档](https://docs.gitea.com/api/1.20/)