Communitygithub.com

Shokunin:GitHub仓库自动同步到作品集网站

自动将GitHub仓库同步到作品集网站。扫描GitHub仓库,使用Playwright截取屏幕截图,生成项目条目,并更新projects-data.js或Supabase数据库。

Shokunin:GitHub仓库自动同步到作品集网站 是什么?

Shokunin 是一个AI Agent技能,旨在自动同步GitHub仓库到个人作品集网站。它通过GitHub API获取仓库列表,使用Playwright截取屏幕截图,并为每个仓库生成项目条目。该技能支持两种输出方式:更新静态的 `projects-data.js` 文件或通过Supabase API写入数据库。它特别适合批量同步操作,例如当用户说“更新作品集”、“同步项目”、“将我的仓库添加到作品集”或“刷新作品集项目”时触发。该技能包含智能变更检测(通过 `last-sync.json` 记录)、错误处理机制(如GitHub API限流、Playwright启动失败)和可配置的过滤选项(排除归档、派生仓库等)。它不适用于一次性添加单个项目。Shokunin 适用于 Claude Code、Cursor 和 Codex 等AI Agent平台,帮助开发者自动维护个人作品集的更新,减少手动维护的繁琐工作。

兼容平台~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)
  • 作品集目录:作品集项目的路径
  • 过滤器:排除的仓库(已归档、派生、特定名称)

步骤2:通过GitHub API获取仓库

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

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

过滤掉:

  • 派生仓库(除非用户选择包含)
  • 个人资料仓库({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 未授权没有令牌或令牌已过期。设置 GITHUB_TOKEN 环境变量。在 github.com/settings/tokens 生成一个新的个人访问令牌,作用域为 public_repo。
GitHub API 速率限制超出(403)未认证的请求限制为60次/小时。认证后:5000次/小时。添加令牌。如果已认证,等待重置(检查 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的dry-run 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个仓库的仓库:使用条件请求(If-None-Match 配合 ETag)
  • 截图捕获之间休眠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 令牌具有正确的作用域(repo, read:user)
  • 仅对具有有效主页 URL(先进行 HEAD 检查)的仓库运行截图
  • 在 finally 块中关闭 Playwright 浏览器,以防止孤儿进程
  • 在 upsert 新条目之前保留现有作品集自定义
  • 提供 dry-run 模式以预览更改而不执行

来源

  • 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 插入、upsert 和认证模式
  • 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)—— 每周同步自动化模式
  • “使用Python自动化繁琐的工作” by Al Sweigart(No Starch Press,第2版,2019年)—— 适用于JavaScript自动化任务的自动化可靠性模式

反模式

模式问题修复
在不检查现有自定义的情况下同步自动生成的条目可能会覆盖用户手工制作的项目描述、featured 标志或自定义排序。先读取目标文件。检测非标准结构。对于 featured: true 条目,保留所有字段。仅 upsert 新仓库或已更改的仓库。
对所有仓库不加区分地截图没有实时演示的仓库浪费 Playwright 启动时间(每个约3秒)。URL 损坏的仓库会产生无用的错误截图。预过滤:仅对 homepage 字段非空且 HEAD 请求返回200的仓库截图。
在计量或慢速连接上运行同步克隆或截取几十个仓库会消耗大量带宽和时间。每批10个运行。添加 --dry-run 标志,列出将更改的内容而不执行。
使用 Supabase anon 密钥而不是 service_role 密钥进行写入Anon 密钥具有行级安全限制,会阻止 upsert。谨慎使用 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.

相关技能