Add gitea-repo-sync skill

gitea-repo-sync/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: gitea-repo-sync
+description: 在自建或托管 Gitea 上自动创建仓库、初始化或复用本地 Git 项目、配置远程并安全推送分支/标签。适用于“给当前目录建 Gitea 仓库”“同步本地项目到 Gitea”“给组织创建仓库再推送代码”这类请求。
+metadata:
+  short-description: Create Gitea repositories and sync local projects safely
+---
+# Gitea Repo Sync
+
+在 Gitea 上建仓、连远程、推送代码的标准化技能。
+
+优先使用打包好的 `scripts/gitea_repo_sync.py`，不要重复手写零散 `curl` + `git` 命令。脚本会先探测仓库是否已存在，再按需要创建仓库、初始化本地 Git、配置远程并执行 push。
+
+## 什么时候用
+
+- 用户要把当前目录项目同步到 Gitea
+- 用户要在某个 owner 或 organization 下创建新仓库
+- 本地目录还不是 Git 仓库，但需要初始化后推送
+- 需要复用已有远程仓库，而不是盲目重复创建
+- 需要在自动化里稳定处理 token、remote 和 push 顺序
+
+## 需要的输入
+
+- `GITEA_URL`：例如 `https://git.hk.hao.work`
+- `GITEA_TOKEN`：具备建仓和推送权限的 token
+- `owner`：用户名或组织名，例如 `hao`
+- `repo`：仓库名，例如 `demo-project`
+- `source_dir`：要同步的本地目录
+- 可选 `branch`：默认推送的分支名，常见为 `main`
+- 可选 `description` / `private` / `tags`
+
+优先使用环境变量：
+
+```bash
+export GITEA_URL='https://git.hk.hao.work'
+export GITEA_TOKEN='<your_token>'
+```
+
+## 标准流程
+
+1. 先确认本地目录路径、目标 owner 和 repo 名。
+2. 调 Gitea API 查询仓库是否已存在。
+3. 若不存在，则按 owner 类型创建：
+   - 当前登录用户自己的仓库：`POST /api/v1/user/repos`
+   - 组织仓库：`POST /api/v1/orgs/{org}/repos`
+4. 进入本地目录检查是否为 Git 仓库：
+   - 不是 Git 仓库时，只有在明确需要时才初始化
+   - 已经是 Git 仓库时，优先复用现有提交历史
+5. 配置或校验远程：
+   - 无 remote 时新增
+   - remote 已存在但 URL 不同，默认停止并提示；只有明确允许时才替换
+6. 按请求推送：
+   - 单分支：`push --set-upstream`
+   - 全部分支：`push --all`
+   - 标签：`push --tags`
+7. 输出最终仓库 URL、remote URL、本地分支和 push 结果。
+
+## 安全默认值
+
+- 不强制覆盖现有 remote，除非明确传 `--replace-remote`
+- 不自动 `git add` / `git commit`，除非明确传 `--stage-all` 和 `--commit-message`
+- 不自动 `force push`
+- 不把 token 写进 git remote URL
+- 仓库已存在时优先复用，不重复创建
+
+## 推荐脚本
+
+使用 `scripts/gitea_repo_sync.py`。
+
+### 常见用法
+
+```bash
+python3 scripts/gitea_repo_sync.py \
+  --server-url "$GITEA_URL" \
+  --token "$GITEA_TOKEN" \
+  --owner hao \
+  --repo demo-project \
+  --source-dir /path/to/project \
+  --init-git \
+  --branch main \
+  --stage-all \
+  --commit-message 'Initial import'
+```
+
+如果仓库已存在，只同步当前分支：
+
+```bash
+python3 scripts/gitea_repo_sync.py \
+  --server-url "$GITEA_URL" \
+  --token "$GITEA_TOKEN" \
+  --owner hao \
+  --repo demo-project \
+  --source-dir /path/to/project \
+  --branch main
+```
+
+推送全部分支和标签：
+
+```bash
+python3 scripts/gitea_repo_sync.py \
+  --server-url "$GITEA_URL" \
+  --token "$GITEA_TOKEN" \
+  --owner hao \
+  --repo demo-project \
+  --source-dir /path/to/project \
+  --push-all \
+  --tags
+```
+
+## 常见坑
+
+- 不要把 `GITEA_TOKEN` 提交进仓库。
+- 不要在 remote URL 里长期保存带 token 的认证串。
+- 不要在 remote 已存在时静默改写 URL。
+- 不要在工作区有未确认修改时自动提交；先确认是否需要 `--stage-all`。
+- 不要默认 `--push-all`；很多场景只需要当前分支。
+
+## 参考资料
+
+- `references/gitea-api-notes.md`