# 建仓库方法（Gitea API + token 推送完整流程）

本仓库由云端沙箱通过 Gitea API 创建并推送，以下为实际执行并验证成功的操作记录，可复用于其他仓库。

## 前置条件

- Gitea 实例端点：`http://far.net.cn/git/`（API 前缀 `http://far.net.cn/git/api`）
- 一个具有建仓权限的 Access Token（Settings → Applications → Generate New Token，勾选 `repo` 权限）
- 本地安装 git 与 curl

```bash
export GITEA_TOKEN="<你的token>"
```

## 第 1 步：验证 token 与确认账号

```bash
curl -s -H "Authorization: token ${GITEA_TOKEN}" \
  "http://far.net.cn/git/api/v1/user"
```

返回 JSON 中 `login` 字段即当前账号（本例为 `admin`）。若返回 401 则 token 无效或过期。

## 第 2 步：创建仓库（API 方式）

```bash
curl -s -X POST -H "Authorization: token ${GITEA_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "riscv-ulp-survey",
    "description": "低功耗 RISC-V 开源芯片综述：参考实现、ISA 扩展、硅实现、商业化生态与 9 个开源仓库完整性实测评估",
    "private": false,
    "auto_init": true,
    "default_branch": "main"
  }' \
  "http://far.net.cn/git/api/v1/user/repos"
```

关键参数说明：

- `name`：仓库名（URL 中使用）
- `auto_init: true`：自动生成 README 并初始化 main 分支（便于直接 clone）
- `private`：`false` 公开 / `true` 私有
- 成功返回 201 与仓库 JSON（含 `html_url`）；仓库名已存在时返回 409

也可以用网页方式：Gitea 界面右上角 `+` → New Repository，填写后创建。

## 第 3 步：克隆新仓库到本地

```bash
git clone "http://oauth2:${GITEA_TOKEN}@far.net.cn/git/admin/riscv-ulp-survey.git"
cd riscv-ulp-survey
```

认证格式为 `http://oauth2:<token>@<host>/<owner>/<repo>.git`，用户名固定写 `oauth2`，密码位置放 token。

> 提示：`git clone` 对链路质量敏感，超时/断流时不要反复重试，可改用 Gitea Contents API 逐个上传文件（见第 5 步备选方案）。

## 第 4 步：添加文件并推送

```bash
# 放入文件（示例）
cp /path/to/低功耗RISC-V开源芯片综述.md  .
cp /path/to/低功耗RISC-V开源芯片综述.docx .
# 编辑 README.md …

git add README.md 低功耗RISC-V开源芯片综述.md 低功耗RISC-V开源芯片综述.docx docs/
git commit -m "添加低功耗 RISC-V 开源芯片综述及建仓方法文档"
git push origin main
```

## 第 5 步（备选）：Contents API 直传单文件

git 不可用时，可用 Contents API 直接创建/更新单文件（base64 编码内容）：

```bash
CONTENT=$(base64 -w0 "低功耗RISC-V开源芯片综述.md")
python3 - "$CONTENT" <<'EOF'
import sys, json, urllib.request
token = os.environ["GITEA_TOKEN"]
body = json.dumps({
    "content": sys.argv[1],
    "message": "添加综述 Markdown",
    "branch": "main"
}).encode()
req = urllib.request.Request(
    "http://far.net.cn/git/api/v1/repos/admin/riscv-ulp-survey/contents/低功耗RISC-V开源芯片综述.md",
    data=body, method="POST",
    headers={"Authorization": f"token {token}", "Content-Type": "application/json"})
print(urllib.request.urlopen(req).status)
EOF
```

说明：新建文件用 `POST`；更新已有文件需先 `GET` 拿到原文件 SHA，再在 body 中带上 `"sha"` 字段用 `PUT`。中文文件名在 URL 中需百分号编码（`urllib.parse.quote`）。

## 本次执行结果

- 仓库：`admin/riscv-ulp-survey`
- 地址：http://far.net.cn/git/admin/riscv-ulp-survey
- 创建方式：API `POST /api/v1/user/repos`（2026-09-06）
- 推送内容：README.md、综述 md/docx、本方法文档