Skill / Blog 内容管理流程

Frontend DesignSkill

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

概述

本文档描述了从 Web Admin 创建内容到 Cloudflare Pages 发布的完整流程。

流程图

sequenceDiagram
    participant Admin as 管理员<br/>(Web Admin)
    participant API as Backend API<br/>(cueboard/backend)
    participant PG as PostgreSQL
    participant R2 as Cloudflare R2
    participant GH as GitHub Actions
    participant CF as Cloudflare Pages

    rect rgb(225, 245, 254)
        Note over Admin,R2: 1. 内容创建与存储
        Admin->>Admin: 填写基本信息<br/>(标题、描述、分类)
        Admin->>API: 上传封面图/视频
        API->>R2: 存储媒体文件
        R2-->>API: 返回 signed URL
        Admin->>Admin: 编写 MDX 内容<br/>(支持 /command 插入)
        Admin->>Admin: 配置 SEO 元数据<br/>(OG title, description, image)
        Admin->>API: POST/PUT 保存内容
        API->>PG: 存储 Skill/Blog 数据
        API->>PG: 存储 Blog-Skill 关联
        PG-->>Admin: 保存成功 ✓
    end

    rect rgb(243, 229, 245)
        Note over Admin,GH: 2. 同步到 GitHub 仓库
        Admin->>GH: 手动触发 sync workflow<br/>(workflow_dispatch)
        GH->>GH: yarn install
        GH->>API: GET /api/v1/skills<br/>(获取已发布 Skills)
        API-->>GH: 返回 Skills 列表 + 详情
        GH->>API: GET /api/v1/blogs<br/>(获取已发布 Blogs)
        API-->>GH: 返回 Blogs 列表 + 详情
        GH->>R2: 下载媒体资源
        R2-->>GH: 图片/视频文件
        GH->>GH: 保存到 public/skills/[name]/assets/
        GH->>GH: 保存到 public/blog/[slug]/assets/
        GH->>GH: 解析 MDX 中的 SkillCard<br/>计算双向关联
        GH->>GH: 生成 frontmatter + MDX<br/>写入 content/skills/[name]/index.mdx
        GH->>GH: 生成 frontmatter + MDX<br/>写入 content/blog/[slug]/index.mdx
        GH->>GH: git add && 检测变更
        GH->>GH: 创建 PR (sync-content 分支)
    end

    rect rgb(255, 243, 224)
        Note over Admin,GH: 3. 代码审核
        GH-->>Admin: PR 通知
        Admin->>GH: Review PR<br/>(预览变更内容)
        Admin->>GH: Approve & Merge PR
    end

    rect rgb(232, 245, 233)
        Note over GH,CF: 4. 自动部署到 Cloudflare
        GH-->>CF: Push to main 触发构建
        CF->>CF: yarn install
        CF->>CF: next build<br/>(SSG 静态生成)
        CF->>CF: 生成 /skills/[slug] 页面
        CF->>CF: 生成 /blog/[slug] 页面
        CF->>CF: 优化图片 (next/image)
        CF->>CF: 部署到全球 Edge 节点
        CF-->>Admin: 部署完成通知
    end

    Note over Admin,CF: ✅ 内容上线，用户可访问

关键步骤

阶段	操作	说明
创建	Web Admin 编辑	管理员通过 admin 页面创建/编辑 Skill 或 Blog
存储	后端保存	内容存 PostgreSQL，资源存 R2
同步	触发 workflow	GitHub 手动运行 Sync Content from Cueboard
生成	静态文件	yarn sync 拉取数据，下载资源，生成 MDX
审核	创建 PR	自动创建包含变更的 Pull Request
发布	合并部署	合并后 Cloudflare Pages 自动构建部署

相关文件

cueweb/
├── .github/workflows/sync.yml    # GitHub Actions workflow
├── scripts/
│   ├── sync-skills.ts            # Skill 同步脚本
│   ├── sync-blogs.ts             # Blog 同步脚本
│   └── utils/sync-utils.ts       # 共享工具函数
├── content/
│   ├── skills/[name]/index.mdx   # Skill MDX 内容
│   └── blog/[slug]/index.mdx     # Blog MDX 内容
└── public/
    ├── skills/[name]/assets/     # Skill 静态资源
    └── blog/[slug]/assets/       # Blog 静态资源

命令参考

# 本地同步测试
yarn sync-skills    # 只同步 Skills
yarn sync-blogs     # 只同步 Blogs
yarn sync           # 同步全部

# 环境变量
API_URL=https://api.cue.surf yarn sync