# 场景 6：一键生成论文引用格式

## 目标

从 GitLink 仓库提取元数据，自动生成学术论文引用格式（BibTeX / APA / MLA / GB/T 7714 / CITATION.cff）。

## 参数

| 参数 | 必需 | 说明 |
|------|------|------|
| `--owner` | 是 | 仓库所有者 |
| `--repo` | 是 | 仓库名称 |
| `--format` | 否 | bibtex / apa / mla / gbt7714 / cff / all（默认 all） |
| `--output` | 否 | 输出文件路径（默认 stdout） |

## 数据收集步骤

### Step 1: 获取仓库基本信息
```bash
gitlink-cli repo +info --owner $OWNER --repo $REPO --format json
```
提取字段：
- `.data.name` → 项目名称
- `.data.description` → 描述
- `.data.owner.login` → 所有者用户名
- `.data.updated_at` / `.data.created_at` → 日期

### Step 2: 获取最新 Release
```bash
gitlink-cli release +list --owner $OWNER --repo $REPO --limit 1 --format json
```
提取字段：
- `.data[0].tag_name` → 版本号
- `.data[0].created_at` → 发布日期

### Step 3: 获取贡献者列表
```bash
gitlink-cli repo +members --owner $OWNER --repo $REPO --limit 20 --format json
```
提取 `.data[].login` 和 `.data[].name` 组装作者列表。

### Step 4: 检测 DOI（可选）
在仓库描述和 README 中扫描 DOI 模式 `10.\d{4,}/[\w.\-/]+`：
```bash
gitlink-cli api GET "raw/$OWNER/$REPO/master/README.md" --format json 2>/dev/null
```
用 grep 提取 DOI。

### Step 5: 获取仓库 URL
```bash
git remote get-url origin
```

## 格式模板

### BibTeX
```bibtex
@software{${REPO_SHORTNAME},
  author = {${AUTHOR_LIST_BIBTEX}},
  title = {${REPO_NAME}},
  version = {${VERSION}},
  date = {${RELEASE_DATE}},
  publisher = {GitLink},
  url = {${REPO_URL}},
  note = {${DESCRIPTION}}
}
```

### APA 7th
```
${AUTHOR_LIST_APA} (${YEAR}). ${REPO_NAME} (Version ${VERSION}) [Computer software].
  GitLink. ${REPO_URL}
```

### MLA 9th
```
${AUTHOR_LIST_MLA}. ${REPO_NAME}. Version ${VERSION}, GitLink,
  ${RELEASE_DATE}, ${REPO_URL}.
```

### GB/T 7714-2015
```
[1] ${AUTHOR_LIST_GB}. ${REPO_NAME}[CP/OL]. ${VERSION}. GitLink,
  ${RELEASE_DATE}[${CITE_DATE}]. ${REPO_URL}.
```

### CITATION.cff
```yaml
cff-version: 1.2.0
message: "If you use this software, please cite it as below."
authors:
  - family-names: ${FAMILY_NAME}
    given-names: ${GIVEN_NAME}
title: ${REPO_NAME}
version: ${VERSION}
date-released: ${RELEASE_DATE}
url: ${REPO_URL}
repository-code: ${REPO_GIT_URL}
```

## 作者列表格式化规则

- **BibTeX**: `Last1, First1 and Last2, First2`
- **APA**: `Last1, F., & Last2, F. (YYYY)`
- **MLA**: `Last1, First1, et al.`（超过 2 人用 et al.）
- **GB/T 7714**: `作者1, 作者2`（英文名保留原名，中文名用中文）

## 注意事项

- 如果仓库没有 Release，版本号用 "v0.0.0-dev"，日期用仓库最后更新时间
- 作者列表优先使用 `name` 字段，回退到 `login`
- 超过 10 个贡献者时，只取前 5 个 + "et al."
- DOI 不存在时，BibTeX 省略 `doi` 字段
- 确保生成的 `.cff` 文件是合法 YAML
