---
belongs_to:
  - "[[INDEX · 铸渊·协作指令｜GitHub ↔ Notion 桥接协议]]"
---
# 🔧 Awen 仓库初始化指令 · GitHub Actions 模板方案

<aside>
🚨

**执行人：Awen（DEV-012）**

**签发人：冰朔（TCS-0002∞）**

**方案：GitHub Actions 替代 Copilot 方案**

**前提：Awen 已有 GitHub 账号 WENZHUOXI，需在该账号下创建仓库**

</aside>

---

## 📋 总流程（4步）

1. 创建仓库 `guanghu-awen`
2. 添加 `MAIN_REPO_TOKEN` 密钥
3. 创建 GitHub Actions 工作流文件
4. 推送触发测试

---

## Step 1 · 创建仓库

1. 打开 [https://github.com/new](https://github.com/new)
2. 仓库名：`guanghu-awen`
3. 可见性：**Private**（推荐）或 Public
4. ✅ 勾选 "Add a README file"
5. 点击 **Create repository**

---

## Step 2 · 添加 MAIN_REPO_TOKEN 密钥

<aside>
🔑

**MAIN_REPO_TOKEN 是什么？**

这是冰朔主仓库 `qinfendebingshuo/guanghulab` 的访问令牌，让 Awen 的 Actions 能把数据推送/同步到主仓库。

**冰朔需要提供这个 Token 给 Awen。**

</aside>

### 冰朔操作：

冰朔已在主仓库 `guanghulab` 配置过 Token，**不需要重新生成**。

直接把已有的 `MAIN_REPO_TOKEN` 值发给 Awen 即可。

<aside>
💡

如果忘记了之前的 Token 值（Classic Token 只在创建时显示一次），才需要去 [https://github.com/settings/tokens](https://github.com/settings/tokens) 重新生成一个，勾选 `repo` + `workflow` 权限。

</aside>

### Awen 操作（配置Secret）：

1. 打开你的仓库：`https://github.com/WENZHUOXI/guanghu-awen`
2. 点击 **Settings** → 左侧 **Secrets and variables** → **Actions**
3. 点击 **New repository secret**
4. Name 填：`MAIN_REPO_TOKEN`
5. Secret 填：冰朔给你的 Token
6. 点击 **Add secret**

---

## Step 3 · 创建 GitHub Actions 工作流

### 方法A：网页直接创建（推荐新手）

1. 打开你的仓库页面
2. 点击 **Add file** → **Create new file**
3. 文件名输入：`.github/workflows/bridge-sync.yml`
4. 粘贴以下内容：

```yaml
# 🌊 光湖桥接同步工作流
# Awen 仓库 → 主仓库 guanghulab 同步
# 触发条件：push 到 main 分支 / 手动触发 / 每天 09:00 UTC+8

name: "🌉 Bridge Sync to GuanghuLab"

on:
  push:
    branches: [main]
  workflow_dispatch:
  schedule:
    - cron: "0 1 * * *"  # UTC 01:00 = 北京时间 09:00

jobs:
  sync-to-main-repo:
    runs-on: ubuntu-latest
    steps:
      - name: "📥 Checkout Awen Repo"
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: "📋 Prepare Sync Payload"
        run: |
          echo "🌊 光湖桥接同步开始"
          echo "时间: $(TZ='Asia/Shanghai' date '+%Y-%m-%d %H:%M:%S CST')"
          echo "仓库: $GITHUB_REPOSITORY"
          echo "分支: $GITHUB_REF_NAME"
          echo "提交: $GITHUB_SHA"
          
          # 创建同步清单
          mkdir -p .sync-payload
          echo "{" > .sync-payload/manifest.json
          echo "  \"source\": \"$GITHUB_REPOSITORY\"," >> .sync-payload/manifest.json
          echo "  \"branch\": \"$GITHUB_REF_NAME\"," >> .sync-payload/manifest.json
          echo "  \"commit\": \"$GITHUB_SHA\"," >> .sync-payload/manifest.json
          echo "  \"timestamp\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"," >> .sync-payload/manifest.json
          echo "  \"developer\": \"awen\"" >> .sync-payload/manifest.json
          echo "}" >> .sync-payload/manifest.json
          
          cat .sync-payload/manifest.json

      - name: "🌉 Sync to GuanghuLab Main Repo"
        env:
          MAIN_REPO_TOKEN: $\{\{ secrets.MAIN_REPO_TOKEN \}\}
        run: |
          # 配置 Git
          git config --global user.name "guanghu-awen-bridge"
          git config --global user.email "awen-bridge@guanghu.dev"
          
          # 克隆主仓库
          git clone https://x-access-token:${MAIN_REPO_TOKEN}@github.com/qinfendebingshuo/guanghulab.git /tmp/main-repo
          
          # 创建 Awen 同步分支目录
          mkdir -p /tmp/main-repo/federation/awen
          
          # 复制同步清单
          cp .sync-payload/manifest.json /tmp/main-repo/federation/awen/latest-sync.json
          
          # 复制仓库内容（排除 .git 和 .sync-payload）
          rsync -av --exclude='.git' --exclude='.sync-payload' --exclude='.github' ./ /tmp/main-repo/federation/awen/workspace/
          
          # 提交推送
          cd /tmp/main-repo
          git add -A
          git diff --cached --quiet && echo "无变更，跳过推送" && exit 0
          git commit -m "🌉 [bridge-sync] Awen → GuanghuLab | $(TZ='Asia/Shanghai' date '+%Y-%m-%d %H:%M')"
          git push origin main
          
          echo "✅ 同步完成！"

      - name: "📝 Sync Result Summary"
        if: always()
        run: |
          echo "## 🌉 桥接同步结果" >> $GITHUB_STEP_SUMMARY
          echo "- 源仓库: $GITHUB_REPOSITORY" >> $GITHUB_STEP_SUMMARY
          echo "- 目标仓库: qinfendebingshuo/guanghulab" >> $GITHUB_STEP_SUMMARY
          echo "- 同步路径: federation/awen/" >> $GITHUB_STEP_SUMMARY
          echo "- 时间: $(TZ='Asia/Shanghai' date '+%Y-%m-%d %H:%M:%S CST')" >> $GITHUB_STEP_SUMMARY
```

1. 点击 **Commit changes** → 选择 "Commit directly to the main branch" → **Commit**

### 方法B：命令行创建（适合熟悉Git的）

```bash
# 克隆你的仓库
git clone https://github.com/WENZHUOXI/guanghu-awen.git
cd guanghu-awen

# 创建工作流目录
mkdir -p .github/workflows

# 创建工作流文件（把上面的 YAML 内容保存为这个文件）
nano .github/workflows/bridge-sync.yml

# 提交推送
git add -A
git commit -m "🌉 初始化桥接同步工作流"
git push origin main
```

---

## Step 4 · 测试验证

1. 推送后，Actions 会自动触发
2. 打开 `https://github.com/WENZHUOXI/guanghu-awen/actions`
3. 查看最新的工作流运行状态
4. ✅ 绿色 = 成功，数据已同步到 `guanghulab/federation/awen/`
5. ❌ 红色 = 失败，点进去看日志排查

### 常见报错及解决

| **报错** | **原因** | **解决** |
| --- | --- | --- |
| remote: Permission denied | MAIN_REPO_TOKEN 无效或过期 | 让冰朔重新生成 Token，重新配置 Secret |
| secret MAIN_REPO_TOKEN not found | Secret 名字打错 | 检查 Settings → Secrets，确认名字完全一致 |
| Repository not found | 主仓库地址错或 Token 没有 repo 权限 | 确认 Token 勾选了 repo 权限 |
| Nothing to commit | 仓库没有新内容 | 正常现象，不是错误 |

---

## 🔄 手动触发同步

不想等定时？随时手动触发：

1. 打开 Actions 页面
2. 左侧选 "🌉 Bridge Sync to GuanghuLab"
3. 点击 **Run workflow** → **Run workflow**

---

<aside>
✅

**完成后告诉冰朔：**

1. 仓库地址：`https://github.com/WENZHUOXI/guanghu-awen`
2. Actions 第一次运行结果（截图）
3. 主仓库 `federation/awen/` 目录是否出现文件
</aside>