astro-developer

Astro 开发技能

为在 Astro monorepo 中工作的 AI Agent 和开发者加载上下文的技能。根据你的任务加载相关文档。

快速决策表

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

任务	主要文档	辅助文档
添加核心功能	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. 运行时边界：Core、Vite 和浏览器执行上下文 → architecture.md
5. 预发布模式：Changesets 以 origin/next 分支为目标（检查 .changeset/config.json）

快速命令参考

# Development
pnpm install                                    # Install (root only)
pnpm run build                                  # Build all packages
pnpm run dev                                    # Watch mode
pnpm run lint                                   # Lint codebase

# Testing
pnpm -C packages/astro exec astro-scripts test "test/**/*.test.js"  # All tests
pnpm -C packages/astro exec astro-scripts test -m "pattern"         # Filter tests
pnpm run test:e2e                               # E2E tests
node --test test/file.test.js                   # Single test

# Examples
pnpm --filter @example/minimal run dev          # Run example

# Changesets
pnpm exec changeset --empty                     # Create changeset, no interactive mode

关键文件路径

packages/astro/src/
├── core/              # Node.js execution context (build/dev commands)
├── runtime/
│   ├── server/        # Vite SSR execution context
│   └── client/        # Browser execution context
├── virtual-modules/   # Virtual module entry points
├── content/           # Content layer system
├── vite-plugin-*/     # Vite plugins
└── types/             # Centralized TypeScript types

packages/integrations/  # Official integrations
examples/              # Test your changes here
test/fixtures/         # 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 → 使用 Vite 加载器系统的 astro dev
• NonRunnablePipeline → 不加载运行时模块的 astro dev（Cloudflare 适配器）
• BuildPipeline → astro build + 预渲染
• AppPipeline → 生产环境无服务器/SSR
• ContainerPipeline → 容器 API

完整详情请参阅 architecture.md。

测试速览

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

单元测试（快速，优先使用）：

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

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

• 仅用于无法进行单元测试的功能（虚拟模块、完整构建流水线）
• 始终设置唯一的 outDir，以避免缓存污染

完整模式和示例请参阅 testing.md。

不要使用此技能的情况

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

Related Documentation

• Root: /AGENTS.md
• Root: /CONTRIBUTING.md
• Astro docs: https://docs.astro.build/
• Package: packages/astro/src/core/README.md
• Build plugins: packages/astro/src/core/build/plugins/README.md