Communitygithub.com

GanderBite/relay

构建 Astro.build 网站的全面技能。当用户想要使用 Astro 创建网站、需要从 Astro 的免费主题集合中选择合适的主题、需要访问 Astro 文档或希望开发 Astro 组件和页面时使用。该技能处理主题选择、文档访问、项目设置和 Astro 特定的开发模式。

relay 是什么?

GanderBite/relay 是一个专门为使用 Astro.build 构建网站的开发者设计的 AI Agent 技能。它提供了一站式的网站构建引导,从需求分析、主题选择到项目初始化、组件开发和部署优化,覆盖 Astro 开发的全流程。该技能支持多种网站类型,如博客、作品集、文档、营销落地页和电子商务等,并能根据用户需求从 Astro 官方免费主题中推荐最合适的选项。此外,它还集成了 Astro 官方文档和高级 LLM 友好文档,可直接参考或实时获取,确保开发建议的准确性和时效性。技能兼容 React、Vue、Svelte 等前端框架的集成,并强调 Astro 的岛屿架构、静态优先和性能最佳实践。使用本技能可显著提升 Astro 项目的开发效率,降低主题选择、文档查阅和代码编写的复杂度。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/GanderBite/relay/tree/HEAD/.claude/skills/astro-builder

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Astro 网站构建器

此技能通过引导您完成主题选择、文档访问和开发最佳实践,帮助您使用 Astro.build 构建网站。当用户提到使用 Astro 构建、想要创建网站或需要 Astro 特定功能的帮助时,请使用此技能。

何时使用此技能

在以下情况下激活此技能:

  • 用户在请求中提到“Astro”或“astro.build”
  • 用户想要构建网站,且 Astro 是合适的选择(博客、文档、作品集、营销网站等)
  • 用户需要为其 Astro 项目选择主题
  • 用户需要 Astro 组件、路由或配置方面的帮助
  • 用户想要将 React、Vue 或其他框架与 Astro 集成
  • 用户需要访问 Astro 的文档或最佳实践

工作流程概述

构建 Astro 网站时,请遵循以下流程:

  1. 了解需求 - 确定网站类型和所需功能
  2. 选择合适的主题 - 根据需求从 Astro 的免费主题中选择
  3. 访问文档 - 参考 Astro 文档了解特定功能
  4. 初始化项目 - 设置项目结构
  5. 开发组件 - 使用 Astro 的组件架构进行构建
  6. 优化与部署 - 遵循性能最佳实践

步骤 1:了解需求

首先,确定网站的类型及其需求:

网站类型:

  • 博客/出版网站
  • 作品集/展示网站
  • 文档网站
  • 营销/着陆页
  • 电子商务网站
  • 公司/企业网站
  • 个人网站

需要询问的关键问题:

  • 网站的主要目的是什么?
  • 它将包含哪些内容类型?(博客文章、项目、产品等)
  • 是否需要交互性?(表单、搜索、动态内容)
  • 用户偏好哪些框架?(React、Vue、Svelte 等)
  • 是否需要特定功能?(深色模式、国际化、CMS 集成)

步骤 2:选择合适的主题

使用 web_fetch 浏览免费的 React 兼容主题:

URL: https://astro.build/themes/1/?search=&technology%5B%5D=react&price%5B%5D=free

主题选择标准:

对于博客/出版物:

  • 寻找排版优秀的主题
  • 必须支持 Markdown/MDX
  • 应具有标签/分类功能
  • RSS 源支持
  • 考虑:astro-paper、astro-blog-template

对于作品集:

  • 视觉项目展示
  • 关于/联系部分
  • 流畅的动画
  • 考虑:astro-portfolio、个人作品集主题

对于文档:

  • 使用 Starlight(Astro 官方文档框架)
  • 功能:搜索、侧边栏导航、深色模式、国际化
  • 适用于:技术文档、API 参考、指南

对于着陆页:

  • 带有行动号召的 Hero 部分
  • 功能/优势部分
  • 联系表单
  • 转化优化

对于电子商务:

  • 产品列表和筛选
  • 购物车功能
  • 支付集成就绪
  • 产品详情页

操作: 获取主题页面,分析可用主题,并推荐 2-3 个最符合用户需求的选项。解释每个主题为何合适。

步骤 3:访问 Astro 文档

当您需要特定的 Astro 文档时,请参考:

  1. 内置参考:references/astro_docs.md - 包含核心 Astro 概念、语法和常见模式
  2. 完整文档:从 https://docs.astro.build/llms-full.txt 获取全面信息

何时参考文档:

  • 组件语法问题 → 参考 astro_docs.md
  • 路由和页面 → 参考 astro_docs.md
  • 样式选项 → 参考 astro_docs.md
  • 高级功能 → 从 docs.astro.build 获取
  • 集成设置 → 从 docs.astro.build 获取
  • API 详情 → 从 docs.astro.build 获取

步骤 4:初始化 Astro 项目

使用 Create Astro CLI

# 创建新项目
npm create astro@latest

# 或使用特定模板
npm create astro@latest -- --template <主题-GitHub-用户名>/<主题仓库>

项目结构设置

初始化后,确保正确的结构:

project/
├── src/
│   ├── components/     # 可复用组件
│   ├── layouts/        # 页面布局
│   ├── pages/          # 路由(必需)
│   │   └── index.astro # 首页
│   ├── content/        # 内容集合(可选)
│   └── assets/         # 优化后的图片
├── public/             # 静态资源
├── astro.config.mjs    # 配置
├── package.json
└── tsconfig.json

关键点: src/pages/ 目录是路由所必需的。

步骤 5:开发组件和页面

组件开发模式

  1. 在 src/components/ 中创建组件文件
  2. 定义 Props 接口(如果使用 TypeScript)
  3. 编写组件脚本(在构建时运行)
  4. 创建模板(使用 Astro 语法的 HTML)
  5. 添加作用域样式(可选)

示例:

---
interface Props {
  title: string;
  description?: string;
}
const { title, description } = Astro.props;
---

<article>
  <h2>{title}</h2>
  {description && <p>{description}</p>}
</article>

<style>
  article {
    padding: 1rem;
    border: 1px solid #ccc;
  }
</style>

页面开发模式

  1. 在 src/pages/ 中创建页面文件(决定路由)
  2. 导入必要的组件和布局
  3. 为动态路由定义 getStaticPaths()
  4. 使用组件组合页面

示例页面:

---
import Layout from '../layouts/Layout.astro';
import Hero from '../components/Hero.astro';

const title = "我的页面";
---

<Layout title={title}>
  <Hero />
  <!-- 更多内容 -->
</Layout>

添加交互性

当需要客户端交互时:

  1. 安装框架集成:npx astro add react
  2. 创建框架组件(.jsx、.vue、.svelte)
  3. 导入并使用客户端指令:
---
import ReactComponent from '../components/ReactComponent.jsx';
---

<!-- 静态(无 JS) -->
<ReactComponent />

<!-- 交互式 -->
<ReactComponent client:load />
<!-- 选项:client:idle、client:visible、client:media -->

步骤 6:根据需要参考文档

在编写代码之前,阅读 references/astro_docs.md 的相关部分:

  • 组件问题 → 阅读“组件语法”部分
  • 路由问题 → 阅读“路由”部分
  • 样式 → 阅读“样式”部分
  • 图片 → 阅读“图片和资源”部分
  • 配置 → 阅读“配置”部分

对于高级主题,获取完整文档:

web_fetch: https://docs.astro.build/llms-full.txt

最佳实践

性能优化

  1. 默认保持组件静态 - 仅在真正需要时添加 client:*
  2. 使用 Astro 的 Image 组件 - 自动优化
  3. 利用岛屿架构 - 默认最小化 JavaScript
  4. 代码分割 - Astro 按页面自动分割

开发工作流程

  1. 从结构开始 - 首先设置布局和基本页面
  2. 组件驱动 - 构建可复用组件
  3. 类型安全 - 使用 TypeScript 处理 Props,提升开发体验
  4. 内容集合 - 用于类型安全的内容管理
  5. 本地测试 - 频繁运行 npm run dev

遵循的常见模式

  • 使用布局保持一致的页面结构
  • 创建 SEO 组件处理元标签
  • 设置正确的 TypeScript 接口
  • 实现正确的错误页面(404、500)
  • 为图片添加正确的 alt 文本
  • 使用语义化 HTML

故障排除

常见问题

“模块未找到”

  • 确保导入路径正确
  • 检查集成是否已安装
  • 验证 astro.config.mjs 是否包含正确的集成设置

“页面未渲染”

  • 确认文件位于 src/pages/ 目录中
  • 检查 frontmatter 中是否有语法错误
  • 确保文件扩展名正确(.astro、.md、.mdx)

“样式未应用”

  • 作用域样式仅应用于组件自身的 HTML
  • 使用 is:global 定义全局样式
  • 如果使用 Tailwind,检查配置

“组件无交互”

  • 为框架组件添加 client:* 指令
  • 确保集成已安装(例如 @astrojs/react)
  • 检查浏览器控制台是否有 JavaScript 错误

资源

脚本

  • scripts/theme_analyzer.py - 帮助从官方主题页面获取和分析 Astro 主题。使用此脚本可基于技术和价格筛选器以编程方式探索主题选项。

参考

  • references/astro_docs.md - 请先阅读此文件,了解核心 Astro 概念、组件语法、路由、样式和常见模式。这是您进行 Astro 开发的主要参考。

外部资源

示例工作流程

示例 1:构建博客

用户:“我想用 Astro 和 React 构建一个博客”

工作流程:

  1. 确定需求:博客网站,需要 React 支持,想要免费主题
  2. 获取主题:web_fetch https://astro.build/themes/1/?technology%5B%5D=react&price%5B%5D=free
  3. 推荐主题:推荐 2-3 个面向博客的主题并附上说明
  4. 阅读 references/astro_docs.md 参考组件模式
  5. 指导设置:提供安装命令和结构
  6. 帮助构建:创建博客文章布局、列表页、单篇文章页
  7. 添加交互性:展示如何使用 client:load 添加 React 组件,如评论功能

示例 2:作品集网站

用户:“使用 https://astro.build/ 为我创建一个作品集网站”

工作流程:

  1. 明确需求:展示什么内容?(项目、技能、经验?)
  2. 从 Astro 主题页面获取作品集主题
  3. 根据用户领域(开发者、设计师等)推荐最佳匹配
  4. 从 references/astro_docs.md 阅读组件语法
  5. 使用所选主题设置项目结构
  6. 创建/自定义组件(Hero、项目网格、关于、联系)
  7. 如果需要,添加流畅的过渡效果
  8. 使用 Astro 的 Image 组件优化图片

示例 3:文档网站

用户:“我需要一个带有搜索和深色模式的文档网站”

工作流程:

  1. 确定需求:文档网站,需要搜索和深色模式
  2. 推荐 Starlight(Astro 官方文档框架)
  3. 展示设置:npm create astro@latest -- --template starlight
  4. 从完整 Astro 文档中参考 Starlight 文档
  5. 配置侧边栏导航结构
  6. 设置内容结构
  7. 启用深色模式(内置)
  8. 配置搜索(内置,使用 Pagefind)

关键提醒

  1. 回答组件或语法问题前,始终先阅读 references/astro_docs.md
  2. 当用户需要一个起点时,从 Astro 主题页面获取主题
  3. 需要时使用 web_fetch 获取完整文档
  4. 保持简单 - Astro 设计为直接易用;不要过度复杂化
  5. 岛屿架构 - 记住组件默认是静态的
  6. 类型安全 - 鼓励使用 TypeScript 以获得更好的开发体验

成功标准

Astro 项目在以下情况下设置正确:

  • ✅ 项目结构遵循 Astro 约定
  • ✅ src/pages/ 目录存在,且至少包含 index.astro
  • ✅ 根据需求选择了合适的主题
  • ✅ 组件遵循 Astro 语法模式
  • ✅ 仅在需要时添加客户端交互性
  • ✅ 为组件 Props 定义了 TypeScript 接口
  • ✅ 使用 Astro 的 Image 组件优化图片
  • ✅ 使用 npm run dev 成功运行网站

相关技能