feishu-portfolio-launch

name	feishu-portfolio-launch
description	从飞书多维表格链接出发，生成并上线作品集网站到 GitHub Pages，并用 GitHub Actions 定时刷新飞书临时媒体链接。适用于视频/图片附件存在飞书、需要对外展示的创作者（AI 视频、摄影、设计、样片库等）。不适合博客、电商、需要后端写入的场景。

Feishu Portfolio Launch

这个 Skill 做什么

一句话：给我飞书多维表格链接，我把作品集网站搭出来，并把“飞书临时链接会过期”这件事自动化处理掉。

默认交付物：

• index.html 或静态前端页面
• api/videos.json
• api/covers.json
• api/portfolio.json
• refresh.py
• .github/workflows/refresh.yml
• 带动效的前端交互层（CSS / JS / Canvas / Three.js 均可）

内置模板资源：

• assets/refresh.py
• assets/refresh.yml
• assets/portfolio.sample.json

目标结果：

• 网站部署在 GitHub Pages
• 飞书媒体链接由 GitHub Actions 每 12 小时自动刷新
• 用户不用保持自己的电脑开机
• 页面不是纯静态排版，至少具备一套完整的入场 / 滚动 / 悬停 / 切页动效

---

适用场景

✅ 适合：

• AI 视频 / 图片作品集
• 摄影、设计、创意样片库
• 客户案例展示站
• 任何「内容在飞书附件里，前台只负责展示」的场景

❌ 不适合：

• 图文博客
• 电商、支付、登录系统
• 需要数据库写入和后端业务逻辑的网站

---

核心原则

不要把飞书临时 URL 当成永久资源。

飞书附件的播放 / 下载地址会过期。正确做法不是让用户在本地电脑上定时跑脚本，而是：

1. 从飞书多维表格读取最新记录
2. 调飞书 API 把附件 file_token 解析成临时 URL
3. 生成 api/*.json
4. 提交回 GitHub 仓库
5. 让 GitHub Pages 自动重新部署

也就是：

Feishu Bitable -> refresh.py -> api/*.json -> GitHub Pages

---

执行流程

Step 0：环境检查

先检查本地是否具备初始化所需工具：

for cmd in node python3 gh git; do
  which "$cmd" >/dev/null 2>&1 && echo "OK  $cmd" || echo "MISS $cmd"
done
lark-cli --version >/dev/null 2>&1 && echo "OK  lark-cli" || echo "MISS lark-cli"
gh auth status >/dev/null 2>&1 && echo "OK  GitHub auth" || echo "MISS GitHub auth"

如果缺少工具，再让用户安装。
如果 gh 没登录，先完成 GitHub 登录。

---

Step 1：拿到飞书 Base 和正确的数据表

向用户要飞书多维表格链接，例如：

https://my.feishu.cn/base/AbCdEfGhIjk

从 URL 里解析出 app_token。

然后列出所有表：

lark-cli api GET "/open-apis/bitable/v1/apps/${APP_TOKEN}/tables"

不要默认选第一张表。
很多 Base 里会同时存在“空模板表”和“真正有作品的素材表”。要继续读取记录并验证：

• 哪张表有真实附件字段
• 哪张表记录数正确
• 哪张表里字段名是用户要展示的内容

优先找这些字段：

• 视频字段：样片 / 视频 / 附件
• 封面字段：封面 / 封面图 / 海报 / 图片
• 标题字段：内容 / 标题 / 作品名称
• 分类字段：类型 / 分类
• 时长字段：时长
• 工具字段：AI工具 / 工具
• 排序字段：序号

如果一张表只有 文本 / 单选 / 日期 / 附件 这种空模板字段，继续换表，不要生成网站。

---

Step 2：验证飞书权限

要让 GitHub Actions 能自动刷新，飞书应用必须至少能：

• 读取多维表记录
• 读取附件媒体链接

执行方案里要显式依赖这 4 个 secrets：

• LARK_APP_ID
• LARK_APP_SECRET
• LARK_BASE_TOKEN
• LARK_TABLE_ID

如果用户本机已经有可用的飞书应用配置，可以复用。否则要明确告诉用户去飞书开放平台补权限和密钥。

---

Step 3：导出结构化作品数据

不要只提取 file_token 列表。
应构建一份前端可直接消费的结构化数据，至少包含：

• title
• categories
• duration
• tools
• order
• video_token
• cover_token

推荐输出：

• api/portfolio.json：完整作品数组
• api/videos.json：video_token -> tmp_download_url
• api/covers.json：cover_token -> tmp_download_url

结构样例可直接参考仓库内的 assets/portfolio.sample.json。

前端可以继续用静态 HTML + JS，也可以完全由 portfolio.json 渲染。

---

Step 4：生成前端页面

默认生成静态页面，要求：

• 响应式作品网格
• 分类筛选
• 点击卡片播放
• 全屏放大播放
• 只允许一个视频同时播放
• 封面优先使用飞书封面字段，没有封面时允许退化为无 poster

动效要求默认一起交付，不要只做“能打开”的静态页：

• 首屏至少有一组入场动画，例如标题、说明、统计数字逐段 fade-up
• 导航在滚动后允许出现 blur / background / border 变化
• 卡片 hover 至少有一层轻量反馈，例如上浮、缩放、遮罩、标题变色
• 页面切换或 section 切换应有过渡，不要突兀闪切
• About / 联系方式 / 能力模块这类信息区，优先加 scroll reveal
• 如果用户希望更强视觉表现，可以增加 Canvas 或 Three.js 背景动画

实现边界：

• 优先用原生 CSS transition / keyframes / IntersectionObserver
• 需要持续运动背景时再用 requestAnimationFrame
• 如果用了 Three.js，必须确保移动端不会空白、卡死或遮挡主要内容
• 动画不能影响视频播放、筛选、弹窗、移动端滚动和首屏可读性
• 默认提供降级路径，脚本失败时文字和内容仍然可见

数据绑定原则：

• HTML 不要写死过期 URL
• 页面运行时拉取 /api/videos.json 和 /api/covers.json
• 或者直接拉 /api/portfolio.json 渲染卡片

如果用户已有站点，优先保留现有视觉样式，只替换数据来源和刷新机制。

如果用户明确提到参考现有站点风格，优先复用这些动画类型：

• hero 文案入场
• sticky filter / nav 的滚动状态过渡
• masonry 卡片 hover 动效
• 页面淡入淡出切换
• About 页的 stagger reveal
• 可选的 Three.js / Canvas 背景运动

---

Step 5：创建仓库并部署 GitHub Pages

标准流程：

gh repo create <repo-name> --public --source=. --remote=origin --push

然后确认 Pages 来源是：

• branch: main
• path: /

检查：

gh api repos/<owner>/<repo>/pages

必须确认：

• Pages 已启用
• cname 正常（如果有自定义域名）
• source 指向 main 和根目录

---

Step 6：生成自动刷新脚本

刷新脚本应采用下面这条路线：

1. 用 app_id + app_secret 换 tenant_access_token
2. 读取 Bitable records
3. 从记录里提取视频和封面附件 token
4. 批量调用 batch_get_tmp_download_url
5. 写入 api/videos.json、api/covers.json、api/portfolio.json

关键要求：

• 支持分页读取 records
• 批量请求按 5 个 token 一组
• 不要把 token 列表硬编码在脚本里
• 优先从真实表记录动态生成
• 允许多种字段名候选

推荐文件名：

• refresh.py

优先直接复制 skill 自带模板：

cp ~/.claude/skills/feishu-portfolio-launch/assets/refresh.py ./refresh.py

然后只修改字段候选数组，不要把具体 token 或具体 URL 硬编码进去。

---

Step 7：生成 GitHub Actions Workflow

不要再使用本地 launchd 作为默认方案。
默认方案必须是 GitHub Actions。

工作流要求：

• 支持 workflow_dispatch
• 支持 schedule，默认每 12 小时执行一次
• 执行 python refresh.py
• 自动提交 api/videos.json、api/covers.json、api/portfolio.json

标准 secrets：

• LARK_APP_ID
• LARK_APP_SECRET
• LARK_BASE_TOKEN
• LARK_TABLE_ID

标准文件：

• .github/workflows/refresh.yml

优先直接复制 skill 自带模板：

mkdir -p .github/workflows
cp ~/.claude/skills/feishu-portfolio-launch/assets/refresh.yml .github/workflows/refresh.yml

---

Step 8：把 Secrets 配进仓库

如果当前环境已经有这些值，并且用户明确让你落地，就直接配置：

gh secret set LARK_APP_ID -R <owner>/<repo>
gh secret set LARK_APP_SECRET -R <owner>/<repo>
gh secret set LARK_BASE_TOKEN -R <owner>/<repo>
gh secret set LARK_TABLE_ID -R <owner>/<repo>

然后验证：

gh secret list -R <owner>/<repo>

如果缺值，就停在这里，明确告诉用户缺哪个，不要伪造。

---

Step 9：手动触发并验证整条链路

完成配置后，立刻手动跑一次 workflow：

gh workflow run refresh.yml -R <owner>/<repo>
gh run list -R <owner>/<repo> --limit 3
gh run watch <run-id> -R <owner>/<repo> --exit-status

再检查线上结果：

python3 - <<'PY'
import json, urllib.request, time
url = f'https://<domain-or-pages-url>/api/videos.json?t={int(time.time())}'
with urllib.request.urlopen(url, timeout=20) as r:
    data = json.load(r)
print(data.get('_refreshed_at'))
print(data.get('_count'))
PY

然后抽测 1 条视频：

• 状态码应为 206 或 200
• content-type 应为 video/mp4 或可播放媒体类型

如果线上 api/videos.json 还是旧时间：

• 先看 Pages 部署是否完成
• 再看 workflow 是否真的提交了新 JSON
• 再确认 Pages source 是否指向正确分支和目录

---

Step 10：域名绑定

如果用户要自定义域名，再做：

• CNAME 文件
• GitHub Pages custom domain 设置
• DNS 配置引导

这部分沿用 GitHub Pages 标准流程，不需要和飞书逻辑耦合。

---

对用户的默认解释

遇到“网站能打开但视频播不了”，优先判断：

1. api/videos.json 是否还是旧的
2. 里面的飞书 URL 是否已过期
3. 自动刷新 workflow 是否失败
4. Pages 是否还没重新部署

默认不要先怀疑播放器，也不要先怀疑前端样式。

如果用户说“页面太死”或者“想要像作品集一样更有呼吸感”，默认增加动画层，而不是只改颜色和排版。

---

成功标准

这个 Skill 完成后，至少要满足：

• 网站已上线
• GitHub Pages 可访问
• 视频可播放
• 仓库里有自动刷新 workflow
• 仓库里已有 4 个 LARK_* secrets
• 手动触发 workflow 成功
• 线上 api/videos.json 的 _refreshed_at 是新时间

---

不要再默认做的事

• 不要默认生成本地 launchd
• 不要默认依赖用户 Mac 长期开机
• 不要硬编码所有 file_token
• 不要只凭第一张表就继续
• 不要只生成 videos.json，忽略封面和结构化记录

---

参考实现

如果需要一个已经验证过的做法，先直接复用 skill 仓库自带模板：

• assets/refresh.py
• assets/refresh.yml
• assets/portfolio.sample.json

实际项目里最终会生成这些文件：

• refresh.py
• .github/workflows/refresh.yml
• api/videos.json
• api/covers.json
• api/portfolio.json

优先复用现成仓库模式，再按用户站点样式做适配。