以下是根据最新需求文档整理的开发提示词，用于指导后续代码实现。

开发提示词

一、项目初始化

任务：创建 Vite 项目骨架，配置构建工具与环境变量。

约束：

  • 使用 Vite ^5.0 作为构建工具
  • 配置 vite.config.js，支持环境变量注入（VITE_ 前缀）
  • 定义全局常量：__GITHUB_OWNER__、__GITHUB_REPO__、__GITHUB_TOKEN__、__GISCUS_REPO_ID__、__GISCUS_CATEGORY_ID__
  • 创建 .env 模板文件，列出所有必需环境变量
  • 配置构建输出目录为 dist/，启用 emptyOutDir

二、构建时 SSG 系统

任务：实现构建时静态站点生成脚本，预渲染所有页面为独立 HTML 文件。

输入：GitHub Discussions（通过 Octokit Core.js 拉取）

输出文件结构：

dist/
├── index.html              # 首页
├── categories.html         # 分类列表页
├── categories/
│   ├── {slug}.html        # 每个分类的详情页
├── tags.html               # 标签列表页
├── tags/
│   ├── {slug}.html        # 每个标签的详情页
├── posts/
│   ├── {number}.html      # 每篇文章的详情页
├── about.html              # 关于页
└── sitemap.xml             # 站点地图

页面生成要求：

  • 每个 HTML 文件包含完整的 <!DOCTYPE html> 结构
  • <head> 内注入完整的 SEO meta 标签（title、description、Open Graph、Twitter Card）
  • <body> 内包含完整的 Header 导航 + 页面内容 + Footer 页脚
  • 页面内容需预渲染 Markdown 为 HTML（使用 Marked.js）
  • 文章详情页预留 Giscus 评论容器的 data-* 属性
  • 所有内部链接使用相对路径或根路径（如 /posts/1）

数据拉取策略：

  • 一次性拉取全部 Discussions（上限 100 条，如超出需分页处理）
  • 并行拉取 Categories 和 Labels
  • 过滤掉 Category 为 About 和 Draft 的 Discussion

内容分类规则：

  • Category = Blog → 普通文章，纳入文章列表
  • Category = About → 关于页面内容，仅用于 /about 路由
  • Category = Draft → 草稿，不生成任何页面

辅助生成：

  • 自动生成 sitemap.xml，包含所有页面 URL 及优先级
  • 生成 robots.txt 允许全部抓取

三、SPA Router（客户端接管）

任务：实现原生 JavaScript SPA 路由系统，支持构建后 Hydration。

核心功能：

  • 基于 History API（pushState / popState）
  • 支持动态路由参数（如 /posts/:id、/categories/:slug）
  • 支持 404 回退
  • 路由切换时滚动到顶部
  • 路由切换时更新 document.title

Hydration 逻辑：

  • 检测页面是否为预渲染（检查 .site-main 是否有子元素）
  • 若是预渲染页面：绑定点击事件拦截，接管导航为 SPA 模式
  • 若是直接访问 SPA 路由（无预渲染内容）：客户端执行完整渲染

导航拦截规则：

  • 拦截所有内部链接点击（非 http://、非 # 锚点）
  • 阻止默认跳转，通过 router.navigate() 处理
  • 外部链接正常跳转，不拦截

四、页面组件开发

任务：实现所有一级和二级页面组件。

组件规范：

  • 每个组件文件导出一个 render(props) 函数
  • 返回原生 DOM 元素（document.createElement），非 HTML 字符串
  • 接受 props 对象作为参数，包含页面所需数据

页面清单：

页面 路径 功能
Home / 文章列表 + 分页
Categories /categories 分类卡片网格，显示文章数量
CategoryDetail /categories/:slug 面包屑 + 分类统计 + 分类简介 + 该分类文章列表
Tags /tags 标签云/列表，按文章数量调整字体大小
TagDetail /tags/:slug 面包屑 + 标签统计 + 标签简介 + 该标签文章列表
About /about 博客简介（渲染 About Discussion 的 Markdown）
PostDetail /posts/:id 面包屑 + 博文详情（Markdown 渲染）+ Giscus 评论

共用组件：

  • Layout：根布局，包含 Header + Footer 插槽
  • Header：导航栏，Logo（chunking）链接到首页，Categories / Tags / About 导航
  • Footer：页脚文本 © 2026 Vanilla JS Development - All rights reserved
  • PostCard：文章卡片，显示标题、发布时间、摘要
  • Breadcrumb：面包屑导航，格式 首页 > 父级 > 当前页
  • Pagination：分页组件，每页 10 条
  • Giscus：Giscus 评论封装，动态加载 giscus 脚本

五、GitHub API 封装与缓存层

任务：封装 GitHub API 调用，实现精简单层 localStorage 缓存。

API 封装要求：

  • 使用 Octokit Core.js 发起请求
  • 仅在运行时（客户端）使用，构建时 SSG 脚本独立使用 Octokit
  • 封装函数：getDiscussions(page, perPage)、getDiscussion(number)、getCategories()、getLabels()

缓存规范：

  • 仅使用 localStorage，无内存缓存层
  • 缓存键前缀：ck_
  • 默认 TTL：5 分钟
  • 分类/标签 TTL：30 分钟
  • 文章详情 TTL：10 分钟
  • 支持过期自动清理
  • 支持按模式批量清除

缓存策略：

  • 读取时先查缓存，命中且未过期则直接返回
  • 未命中或已过期则发起 API 请求，成功后写入缓存
  • 缓存数据结构：{ data, exp }

六、Markdown 渲染系统

任务：配置 Marked.js + highlight.js，实现 Markdown 到 HTML 的渲染。

功能要求：

  • 支持标准 Markdown 语法（标题、列表、链接、图片、代码块等）
  • 代码块语法高亮（highlight.js）
  • 构建时 SSG 脚本与运行时客户端共用同一套渲染逻辑
  • 安全处理：对 HTML 内容进行必要转义，防止 XSS

辅助功能：

  • 提取文章摘要（去除 Markdown 标记，截取前 160 字符）
  • 提取文章首图 URL（用于 Open Graph image）

七、SEO 与 Meta 标签

任务：确保所有页面具备完整的 SEO 支持。

构建时（预渲染）：

  • 每个静态 HTML 文件 <head> 内预注入完整 meta 标签
  • title 格式：页面标题 | Chunking
  • description 为文章摘要或页面描述

运行时（备用）：

  • 提供 setPageMeta() 工具函数，用于动态更新 meta（客户端路由切换时）
  • 更新内容：title、description、Open Graph 标签

Meta 标签清单：

  • <title>
  • <meta name="description">
  • <meta property="og:title">
  • <meta property="og:description">
  • <meta property="og:type">（website / article）
  • <meta property="og:url">
  • <meta property="og:image">
  • <meta name="twitter:card">

八、Giscus 评论集成

任务：在文章详情页集成 Giscus 评论系统。

集成方式：

  • 通过 Giscus Web Component 或脚本动态加载
  • 配置属性：
    • data-repo / data-repo-id
    • data-category = Comments
    • data-category-id
    • data-mapping = specific
    • data-term = 文章 Discussion number
    • data-reactions-enabled = 1
    • data-emit-metadata = 0
    • data-input-position = bottom
    • data-theme = preferred_color_scheme
    • data-lang = zh-CN

行为要求：

  • 预渲染 HTML 中预留 Giscus 容器及 data-* 属性
  • Hydration 后由 Giscus 脚本自动初始化
  • 路由切换离开文章页时，清理 Giscus 实例（如需要）

九、样式系统

任务：使用原生 CSS 实现完整样式。

文件组织：

  • variables.css：CSS 变量（颜色、间距、字体、断点）
  • base.css：CSS 重置、基础样式
  • layout.css：布局相关（Header、Footer、网格系统）
  • components.css：组件样式（PostCard、Breadcrumb、Pagination 等）
  • pages.css：页面特定样式

设计约束：

  • 使用 CSS 变量定义设计系统
  • BEM 命名规范
  • 响应式三档断点：移动端、平板、桌面
  • 无 CSS 预处理器
  • 无 CSS-in-JS

十、部署与 CI/CD

任务：配置 GitHub Actions 自动构建与部署。

触发条件：

  • Push 到 main 分支
  • 定时触发：每 6 小时一次（同步新发布的 Discussion）

构建流程：

  1. Checkout 代码
  2. 安装依赖（npm ci）
  3. 执行构建（npm run build），注入环境变量
  4. 部署 dist/ 目录到 GitHub Pages

环境变量来源：

  • GitHub Secrets（secrets.OWNER、secrets.REPO、secrets.TOKEN 等）

十一、开发顺序建议

  1. 项目初始化（Vite 配置、环境变量）
  2. 构建时 SSG 脚本（数据拉取、HTML 生成）
  3. 基础样式系统（variables、base、layout）
  4. 共用组件（Header、Footer、Layout）
  5. SPA Router 核心实现
  6. 页面组件（Home、About、Categories、Tags 等）
  7. Markdown 渲染 + 代码高亮
  8. GitHub API 封装 + 缓存层
  9. Giscus 集成
  10. SEO meta 完善
  11. CI/CD 配置
  12. 测试与优化

附：8个模块

模块 名称 包含内容 对应文件
模块1 项目初始化 Vite 配置、环境变量、入口 HTML、robots.txt vite.config.js、.env、index.html、public/robots.txt
模块2 构建时 SSG 系统 数据拉取、HTML 模板、页面渲染、sitemap 生成 build-ssg.js
模块3 SPA Router History API、动态路由、Hydration、导航拦截 src/router.js
模块4 页面组件开发 Layout、Header、Footer、PostCard、Breadcrumb、Pagination、Giscus、7个页面 src/components/*.js、src/pages/*.js
模块5 GitHub API 与缓存 Octokit 封装、localStorage 单层缓存 src/api/github.js、src/utils/cache.js
模块6 Markdown 渲染与工具 Marked + highlight、日期格式化、摘要提取、slugify src/utils/markdown.js、src/utils/helpers.js
模块7 样式系统 CSS 变量、重置、布局、组件、页面样式 src/styles/*.css
模块8 部署配置 GitHub Actions、gitignore、package.json .github/workflows/deploy.yml、.gitignore、package.json

以上为完整开发提示词。如需开始输出代码，请指定从哪个模块开始。