# GitHub 交付配置

本文件用于 GitHub 分批交付前的仓库和专用凭据配置。只要任务需要 GitHub push、release、下载链接，或用户提到 GitHub 仓库、专用 KEY、token、PAT、deploy key，先读本文件。

## 目标

- 使用专门的交付仓库，不和源码仓库混放。
- 默认使用私有仓库，除非用户明确要求公开交付。
- 使用专用、最小权限凭据；不要复用高权限个人 token。
- 不在聊天、prompt、manifest、状态文件、README、日志或提交记录里暴露完整 token / 私钥。

## 推荐配置

推荐环境变量：

```bash
export MAOMOMO_GITHUB_REPO="OWNER/maomomo-delivery"
export MAOMOMO_GITHUB_BRANCH="main"
export MAOMOMO_GITHUB_BASE_PATH="deliveries"
```

认证方式任选其一：

1. GitHub CLI 登录，适合本机交互使用：

```bash
gh auth login --web --git-protocol https
gh auth status
```

2. Fine-grained PAT，适合脚本或无头环境：

- Repository access：只选交付仓库。
- Repository permissions：只给 `Contents: Read and write`。
- 过期时间：建议 30-90 天。
- 本机设置为环境变量，不要发到聊天里：

```bash
export GH_TOKEN="只在本机 shell 中设置，不写入项目文件"
gh auth status
```

3. SSH deploy key，适合只给单仓库写权限：

```bash
ssh-keygen -t ed25519 -f "$HOME/.ssh/maomomo_delivery_ed25519" -C "maomomo-delivery"
```

把 `.pub` 公钥加入 GitHub 仓库 Settings -> Deploy keys，并勾选 write access。私钥只留本机，推送时使用：

```bash
export GIT_SSH_COMMAND="ssh -i $HOME/.ssh/maomomo_delivery_ed25519 -o IdentitiesOnly=yes"
```

## 首次仓库准备

如果用户还没有交付仓库，先引导其创建或确认仓库名。不要擅自创建公开仓库。

```bash
gh repo create "$MAOMOMO_GITHUB_REPO" --private --clone=false
```

检查仓库：

```bash
gh repo view "$MAOMOMO_GITHUB_REPO" --json nameWithOwner,visibility,defaultBranchRef
```

如果 `visibility` 不是 `PRIVATE`，先提醒用户可能公开图片、prompt、状态文件和活动信息；除非用户明确确认，否则不要继续推送。

## 本地工作目录

GitHub 交付工作目录默认放在 `$HOME/dev` 下，避免散落到桌面、下载目录或系统目录：

```bash
mkdir -p "$HOME/dev/maomomo-delivery-work"
cd "$HOME/dev/maomomo-delivery-work"
```

如果仓库尚未 clone：

```bash
gh repo clone "$MAOMOMO_GITHUB_REPO" repo
```

目标路径建议：

```text
deliveries/{project_slug}/
├── batch-01-cover/
├── batch-02-content-cards/
├── batch-03-final-assets/
├── final_manifest.json
├── github_batches.json
└── slide_run_state.json
```

## 推送前检查

推送前必须确认：

- `MAOMOMO_GITHUB_REPO` 已设置，或用户已明确给出目标仓库。
- 已通过 `gh auth status`，或 SSH deploy key 已能写入目标仓库。
- 仓库默认为私有；公开仓库必须经用户明确确认。
- `final_manifest.json` 已生成，最终文件只从 manifest 或状态文件里的 final assets 读取。
- 本批文件不包含 token、私钥、账号、真实个人信息或未确认敏感素材。
- `github_batches.json` 只记录 batch、路径、commit、release / url，不记录任何密钥。

## 分批推送流程

每批只复制本批需要交付的文件，不扫描整个项目目录。提交信息优先中文：

```bash
git add deliveries/{project_slug}/batch-01-cover deliveries/{project_slug}/github_batches.json
git commit -m "交付：{project_slug} batch-01-cover"
git push origin "$MAOMOMO_GITHUB_BRANCH"
```

推送后用状态脚本记录：

```bash
uv run python scripts/maomomo_job_state.py github-batch article \
  --batch batch-01-cover \
  --commit "<commit sha>" \
  --url "https://github.com/OWNER/REPO/commit/<commit sha>" \
  --paths assets/example-01-cover.png prompts/example_01.json final_manifest.json
```

每批推送后回复用户：GitHub 文件路径、commit、release 或下载链接，并说明下一批状态。

## 阻塞处理

如果缺少仓库或凭据，不要继续生成假链接，也不要要求用户把 token 粘贴到聊天里。回复应包含：

- 当前阻塞：缺少交付仓库、未登录 GitHub CLI、token 权限不足、deploy key 未授权等。
- 本机配置命令。
- 需要用户确认的仓库名或认证方式。
- 已完成的本地文件路径和下一步。