139 lines
4.3 KiB
Markdown
139 lines
4.3 KiB
Markdown
# 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 未授权等。
|
||
- 本机配置命令。
|
||
- 需要用户确认的仓库名或认证方式。
|
||
- 已完成的本地文件路径和下一步。
|