reyalka/astro

Astro 开发者技能

面向在 Astro 单仓库中工作的 AI 智能体和开发者的上下文加载技能。根据你的任务加载相关文档。

快速决策矩阵

你在做什么？ → 阅读以下文件：

任务	主要文档	辅助文档
添加核心功能	architecture.md, constraints.md	testing.md
修复 Bug	debugging.md	architecture.md
编写/修复测试	testing.md	constraints.md
创建集成	探索 packages/integrations/ 中的示例	testing.md
理解架构	architecture.md	-
处理错误	debugging.md, constraints.md	testing.md
理解约束	constraints.md	architecture.md

关键警告

开始之前，请注意以下常见陷阱：

1. 优先使用单元测试：默认编写可单元测试的代码。仅当必要时使用集成测试 → testing.md
2. Node.js API 限制：不能在 runtime/ 代码中使用 Node.js API → constraints.md
3. 测试隔离：必须为每个集成测试设置唯一的 outDir → testing.md
4. 运行时边界：核心 vs Vite vs 浏览器执行上下文 → architecture.md
5. 预发布模式：Changesets 以 origin/next 分支为目标（检查 .changeset/config.json）

快速命令参考

# 开发
pnpm install                                    # 安装（仅根目录）
pnpm run build                                  # 构建所有包
pnpm run dev                                    # 监视模式
pnpm run lint                                   # 检查代码

# 测试
pnpm -C packages/astro exec astro-scripts test "test/**/*.test.js"  # 所有测试
pnpm -C packages/astro exec astro-scripts test -m "pattern"         # 过滤测试
pnpm run test:e2e                               # 端到端测试
node --test test/file.test.js                   # 单个测试

# 示例
pnpm --filter @example/minimal run dev          # 运行示例

# Changesets
pnpm exec changeset --empty                     # 创建 changeset，无交互模式

关键文件路径

packages/astro/src/
├── core/              # Node.js 执行上下文（构建/开发命令）
├── runtime/
│   ├── server/        # Vite SSR 执行上下文
│   └── client/        # 浏览器执行上下文
├── virtual-modules/   # 虚拟模块入口点
├── content/           # 内容层系统
├── vite-plugin-*/     # Vite 插件
└── types/             # 集中式 TypeScript 类型

packages/integrations/  # 官方集成
examples/              # 在这里测试你的修改
test/fixtures/         # 测试夹具

注意：node_modules/ 中的错误堆栈跟踪映射到 packages/ 中的源文件。详见 architecture.md。

使用方式

此技能用于加载相关上下文——它不协调工作流。加载适当的文档后：

1. 阅读你任务的推荐文件
2. 应用描述的模式和约束
3. 使用提供的命令和文件路径
4. 如果遇到问题，搜索错误消息的文档

架构快速总结

三个执行上下文：

• core/ → Node.js，构建/开发命令，除了 Vite 插件外避免使用 Node API
• runtime/server/ → Vite SSR，不能使用 Node API
• runtime/client/ → 浏览器，完全不能使用 Node API

五种管道类型：

• RunnablePipeline → astro dev 与 Vite 加载器系统
• NonRunnablePipeline → astro dev 无运行时模块加载（Cloudflare 适配器）
• BuildPipeline → astro build + 预渲染
• AppPipeline → 生产环境无服务器/SSR
• ContainerPipeline → 容器 API

详见 architecture.md 获取完整细节。

测试快速总结

理念：优先编写单元测试而非集成测试。默认编写可单元测试的代码。

单元测试（快速，推荐）：

• 测试纯函数和业务逻辑
• 从基础设施中提取业务逻辑
• 使用依赖注入

集成测试（慢速，谨慎使用）：

• 仅用于无法进行单元测试的特性（虚拟模块、完整构建管道）
• 始终设置唯一的 outDir 以避免缓存污染

详见 testing.md 获取完整的模式和示例。

何时不使用此技能

• Bug 分类：使用 triage 技能
• GitHub Actions 分析：使用 analyze-github-action-logs 技能
• 简单问题：直接提问，无需加载此技能

相关文档

• 根目录：/AGENTS.md
• 根目录：/CONTRIBUTING.md
• Astro 文档：https://docs.astro.build/
• 包：packages/astro/src/core/README.md
• 构建插件：packages/astro/src/core/build/plugins/README.md