Communitygithub.com

shokunin (自動同步 GitHub 儲存庫到作品集網站)

自動掃描 GitHub 儲存庫,使用 Playwright 擷取螢幕截圖,產生專案條目,並更新 projects-data.js 或 Supabase 資料庫。當使用者要求「更新作品集」、「同步專案」、「將我的儲存庫加入作品集」或「重新整理作品集專案」時使用。請勿用於一次性專案新增——僅適用於批次同步。

shokunin (自動同步 GitHub 儲存庫到作品集網站) 是什麼?

「shokunin」是一項自動化技能,旨在將開發者的 GitHub 儲存庫批次同步至其個人作品集網站。它能自動從 GitHub API 擷取儲存庫清單,並根據上次同步狀態偵測新增或更新的專案。對於具有 `homepage` 或部署 URL 的儲存庫,它會使用 Playwright(一種無頭瀏覽器)自動擷取網頁截圖。支援兩種作品集類型:一種是使用本機 JavaScript 檔案 (`projects-data.js`) 的靜態網站,另一種是透過 HTTP POST 請求將資料寫入 Supabase 資料庫。該技能會在 `last-sync.json` 中維護一個本機快取,以實現增量更新,確保只處理有變更的儲存庫。它能妥善處理邊際案例,例如 GitHub API 速率限制、缺少螢幕截圖 URL、Playwright 啟動失敗,以及保護現有的自訂設定(例如 `featured: true` 標記)。其設計是與開發者工具(如 Claude Code、Cursor、Codex 等)整合,並提供全面的錯誤處理表和可選的 cron 定期同步功能。

相容平台~Claude Code~Codex CLI~Cursor✓OpenCode
npx skills add https://github.com/EliasOulkadi/shokunin/tree/HEAD/.pack/skills/portfolio-auto

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

注意: last-sync.json 狀態檔案會在首次成功同步時自動建立。首次執行時請忽略「找不到檔案」的警告。

作品集自動同步

自動將 GitHub 儲存庫同步至您的作品集網站。

工作流程

步驟 1:收集設定

詢問使用者:

  • GitHub 使用者名稱:(預設來自 git config)
  • 作品集類型:static (projects-data.js) 或 supabase (API)
  • 作品集目錄:作品集專案的路徑
  • 篩選條件:排除儲存庫(已封存、Fork、特定名稱)

步驟 2:透過 GitHub API 擷取儲存庫

GET /users/{username}/repos?per_page=100&sort=updated&direction=desc

擷取:name、description、html_url、homepage、language、topics、updated_at

篩選排除:

  • Fork(除非使用者選擇包含)
  • 個人檔案儲存庫({username}/{username})
  • 已封存的儲存庫

步驟 3:偵測變更

與 last-sync.json(儲存在技能目錄中)進行比對。

  • 新的儲存庫:不在上次同步清單中 → 完整處理
  • 已更新的儲存庫:updated_at 已變更 → 重新截圖
  • 未變更的儲存庫:跳過

步驟 4:擷取螢幕截圖

對於具有 homepage 或部署 URL 的儲存庫:

const { chromium } = require('playwright');
const browser = await chromium.launch({ headless: true });
const page = await browser.newPage();
await page.setViewportSize({ width: 1280, height: 800 });
await page.goto(process.env.URL, { waitUntil: 'networkidle', timeout: 15000 });
await page.screenshot({ path: `/tmp/portfolio-${name}.png`, fullPage: false });
await browser.close();

儲存至作品集的螢幕截圖目錄。

步驟 5:更新作品集資料

靜態 (projects-data.js)

{
  title: '{repo.name}',
  description: '自動產生: {description}',
  tech: '{language},{topics}',
  github_url: '{html_url}',
  live_url: '{homepage || ""}',
  featured: false
}

Supabase

const res = await fetch('https://your-site.com/api/projects', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer {token}' },
  body: JSON.stringify(projectData)
});

步驟 6:儲存同步狀態

{
  "lastSync": "2026-05-12T18:30:00Z",
  "repos": {
    "example-repo": { "updated_at": "2026-04-20T10:00:00Z", "screenshot": true }
  }
}

步驟 7:回報結果

同步完成:
+ 2 個新的(Cyberian, Image Enhancer)
+ 1 張螢幕截圖已擷取
+ 1 個已更新(Portfolio)
- 0 個錯誤

注意事項

  • 螢幕截圖需要 Playwright 和有效的 URL。如果沒有主頁則跳過。
  • 絕不變更現有專案的 featured: true — 只有使用者可以將其設為精選。
  • 可透過 cron/GitHub Actions 安排每週同步。

錯誤處理

原因修正方式
GitHub API 回傳 401 未授權沒有 token 或 token 已過期。設定 GITHUB_TOKEN 環境變數。在 github.com/settings/tokens 使用 public_repo 範圍產生新的個人存取權杖。
GitHub API 速率限制超標 (403)未驗證的請求限制為每小時 60 次。已驗證:每小時 5000 次。請加入 token。如果已驗證,請等待重置(檢查 X-RateLimit-Reset 標頭)。
儲存庫沒有 homepage 欄位且無部署 URL無法擷取螢幕截圖。在輸出中將該儲存庫標記為「無即時預覽」。使用 GitHub URL 作為備用連結。
Playwright 瀏覽器啟動失敗未安裝 Chromium。執行 npx playwright install chromium。在無頭伺服器上,加入 --no-sandbox 標記:chromium.launch({ headless: true, args: ['--no-sandbox'] })。
螢幕截圖 URL 回傳 404 或超過 15 秒逾時部署 URL 已過時或網站已關閉。為此儲存庫跳過螢幕截圖。將 URL 和錯誤記錄到 failed-screenshots.json 檔案以供手動檢閱。
projects-data.js 具有自訂格式,自動產生可能會破壞它使用正則表達式插入可能會損壞手寫程式碼。先讀取檔案以偵測非標準結構。如果偵測到,請加入一個包含新條目的註解區塊,並要求使用者手動合併。
Supabase API 因外部鍵或結構描述約束而插入失敗作品集結構描述可能與自動產生的承載形狀不同。請先讀取 Supabase 資料表結構描述。明確對應欄位(不使用展開運算子)。在提交之前,以回傳 200 的試行 POST 進行驗證。
last-sync.json 已損毀或手動編輯在 try-catch 中將其解析為 JSON。如果失敗,將其重新命名為 last-sync.json.bak 並從頭開始全新同步。警告使用者增量偵測已遺失。

GitHub API 模式

儲存庫發現

import requests, os

headers = {"Authorization": f"token {os.environ['GITHUB_TOKEN']}"}

# 擷取所有儲存庫(分頁)
repos = []
page = 1
while True:
    r = requests.get(f"https://api.github.com/user/repos?per_page=100&page={page}&sort=updated", headers=headers)
    batch = r.json()
    if not batch: break
    repos.extend(batch)
    page += 1

# 篩選:僅非 fork、非封存、有描述
candidates = [r for r in repos if not r["fork"] and not r["archived"] and r["description"]]

速率限制

  • GitHub API:每小時 5,000 個請求(已驗證)。檢查 X-RateLimit-Remaining 標頭。
  • 對於擁有 500 個以上儲存庫的儲存庫:使用條件式請求(使用 ETag 的 If-None-Match)
  • 在螢幕截圖擷取之間休眠 1 秒(避免 GitHub 對資產的速率限制)

Playwright 螢幕截圖模式

from playwright.sync_api import sync_playwright

def capture(url, output_path):
    with sync_playwright() as p:
        browser = p.chromium.launch()
        page = browser.new_page(viewport={"width": 1280, "height": 800})
        page.goto(url, timeout=15000, wait_until="networkidle")
        page.screenshot(path=output_path, full_page=False)
        browser.close()

錯誤復原

  • 頁面載入逾時 -> 重試一次,如果仍然失敗則跳過(在輸出中標記)
  • 私人儲存庫 -> 跳過(未經授權無法截圖)
  • 頁面崩潰 -> 將錯誤狀態擷取為螢幕截圖
  • DNS 失敗 -> 跳過並記錄訊息

快取策略

import hashlib, json, os
cache_file = ".sync-cache.json"
cache = json.load(open(cache_file)) if os.path.exists(cache_file) else {}

for repo in repos:
    key = hashlib.md5(f"{repo['full_name']}:{repo['pushed_at']}".encode()).hexdigest()
    if cache.get(repo['full_name']) == key:
        continue  # 跳過:自上次同步後無變更
    # ... 擷取螢幕截圖,更新條目 ...
    cache[repo['full_name']] = key

json.dump(cache, open(cache_file, 'w'))

檢查清單

  • GitHub token 在擷取儲存庫前具有正確的範圍(repo, read:user)
  • 僅對具有有效 homepage URL 的儲存庫執行螢幕截圖(先進行 HEAD 檢查)
  • Playwright 瀏覽器在 finally 區塊中關閉,以防止孤立程序
  • 在插入新條目前,保留現有作品集的自訂設定
  • 提供試行模式以在不執行情況下預覽變更

來源

  • GitHub REST API v3 文件 (docs.github.com/en/rest/repos/repos) — 儲存庫清單、篩選和分頁
  • Playwright 文件 (playwright.dev/docs/api/class-playwright) — 無頭瀏覽器啟動、螢幕截圖和檢視區設定
  • Supabase JavaScript 客戶端文件 (supabase.com/docs/reference/javascript) — API 插入、更新和驗證模式
  • Node.js fs 模組文件 (nodejs.org/api/fs.html) — 使用原子重新命名進行同步狀態安全的檔案讀取/寫入
  • 個人存取權杖最佳實踐 (docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) — 範圍、過期和安全儲存
  • GitHub Actions cron 排程 (docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule) — 每週同步自動化模式
  • 「Automate the Boring Stuff with Python」作者 Al Sweigart (No Starch Press, 第 2 版, 2019) — 適用於 JavaScript 自動化任務的自動化可靠性模式

反模式

模式問題修正方式
未檢查現有自訂設定就進行同步自動產生的條目可能會覆蓋使用者手動製作的專案描述、精選標記或自訂排序。先讀取目標檔案。偵測非標準結構。對於 featured: true 的條目,保留所有欄位。僅插入或更新新的或已變更的儲存庫。
不加區別地為每個儲存庫擷取螢幕截圖沒有即時示範的儲存庫會浪費 Playwright 啟動時間(每次約 3 秒)。具有損壞 URL 的儲存庫會產生無用的錯誤螢幕截圖。預先篩選:僅對 homepage 欄位非空且在 HEAD 請求時回傳 200 的儲存庫進行截圖。
在使用計量或慢速連線時執行同步複製或截取數十個儲存庫的螢幕截圖可能會消耗大量頻寬和時間。以 10 個一批次執行。加入 --dry-run 標記,列出將變更的內容而不執行。
使用 Supabase anon 金鑰代替 service_role 金鑰進行寫入Anon 金鑰具有列級安全性限制,會封鎖更新。謹慎使用 service_role 金鑰。儲存在環境變數中,絕不放在程式碼中。為同步功能加入資料表層級的 RLS 政策。
同步後未清理 Playwright 瀏覽器程序每個 chromium.launch() 都會產生一個程序。孤立程序會累積記憶體,並可能耗盡系統資源。始終在 finally 區塊中呼叫 browser.close()。在陣列中追蹤已啟動的瀏覽器,並在收到 SIGINT/SIGTERM 時強制關閉。
將作品集資料路徑硬編碼而不是從設定讀取路徑在不同專案之間會變更。硬編碼的路徑在第一次於不同機器上使用時會失敗。在步驟 1 中詢問作品集目錄。從該基礎路徑推導出 projects-data.js 的路徑。儲存在同步狀態中以供重複使用。

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

相關技能