天文开发者
- 作者仓库星标 59,805
- 作者仓库 astro
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @withastro · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS · Linux · Windows
- 运行环境要求
- Node.js
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# Astro Developer Skill
Context-loading skill for AI agents and developers working in the Astro monorepo. Loads relevant documentation based on your task.
## Quick Decision Matrix
**What are you doing?** → **Read these files:**
| Task | Primary Docs | Supporting Docs |
| -------------------------- | -------------------------------------------------------------------- | ---------------------------------- |
| Adding a core feature | [architecture.md](architecture.md), [constraints.md](constraints.md) | [testing.md](testing.md) |
| Fixing a bug | [debugging.md](debugging.md) | [architecture.md](architecture.md) |
| Writing/fixing tests | [testing.md](testing.md) | [constraints.md](constraints.md) |
| Creating an integration | Explore `packages/integrations/` for examples | [testing.md](testing.md) |
| Understanding architecture | [architecture.md](architecture.md) | - |
| Dealing with errors | [debugging.md](debugging.md), [constraints.md](constraints.md) | [testing.md](testing.md) |
| Understanding constraints | [constraints.md](constraints.md) | [architecture.md](architecture.md) |
## Critical Warnings
**Before you start, be aware of these common pitfalls:**
1. **Prefer Unit Tests**: Write unit-testable code by default. Use integration tests only when necessary → [testing.md](testing.md)
2. **Node.js API Restrictions**: Cannot use Node.js APIs in `runtime/` code → [constraints.md](constraints.md)
3. **Test Isolation**: Must set unique `outDir` for each integration test → [testing.md](testing.md)
4. **Runtime Boundaries**: Core vs Vite vs Browser execution contexts → [architecture.md](architecture.md)
5. **Prerelease Mode**: Changesets target `origin/next` branch (check `.changeset/config.json`)
## Quick Command Reference
```bash
# 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
```
## Key File Paths
```
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
```
**Note**: Error stack traces in `node_modules/` map to source in `packages/`. See [architecture.md](architecture.md) for details.
## Usage
This skill loads relevant context—it doesn't orchestrate workflows. After loading appropriate docs:
1. Read the recommended files for your task
2. Apply the patterns and constraints described
3. Use the commands and file paths provided
4. Search docs for error messages if you encounter issues
## Architecture Quick Summary
**Three Execution Contexts:**
- **core/** → Node.js, build/dev commands, avoid Node APIs except in Vite plugins
- **runtime/server/** → Vite SSR, CANNOT use Node APIs
- **runtime/client/** → Browser, CANNOT use Node APIs at all
**Five Pipeline Types:**
- **RunnablePipeline** → `astro dev` with Vite loader system
- **NonRunnablePipeline** → `astro dev` without runtime module loading (Cloudflare adapter)
- **BuildPipeline** → `astro build` + prerendering
- **AppPipeline** → Production serverless/SSR
- **ContainerPipeline** → Container API
See [architecture.md](architecture.md) for complete details.
## Testing Quick Summary
**Philosophy**: Prefer unit tests over integration tests. Write unit-testable code by default.
**Unit tests** (fast, preferred):
- Test pure functions and business logic
- Extract business logic from infrastructure
- Use dependency injection
**Integration tests** (slow, use sparingly):
- Only for features that cannot be unit tested (virtual modules, full build pipeline)
- Always set unique `outDir` to avoid cache pollution
See [testing.md](testing.md) for complete patterns and examples.
## When NOT to Use This Skill
- **Bug triage**: Use the `triage` skill instead
- **GitHub Actions analysis**: Use the `analyze-github-action-logs` skill
- **Simple questions**: Just ask directly, don't load this skill
## Related Documentation
- Root: [/AGENTS.md](../../../AGENTS.md)
- Root: [/CONTRIBUTING.md](../../../CONTRIBUTING.md)
- Astro docs: https://docs.astro.build/llms.txt
- Package: packages/astro/src/core/README.md
- Build plugins: packages/astro/src/core/build/plugins/README.md
章节与文件索引
按说明文件中的顺序排列。
快速决策矩阵
严重警告
关键文件路径
用途
架构快速总结
文件/命令 -> packages/integrations/ · runtime/ · outDir · origin/next · .changeset/config.json · node_modules/ · packages/ · astro dev
内容校验值 -> acc6acff9bb8
当前原文的自动摘译,尚未人工审校。
快速决策矩阵
你在做什么? → 阅读这些文件:任务·主要文档·支持文档添加核心功能·architecture.md、constraints.md·testing.md 修复错误·debugging.md·architecture.md 编写/修复测试·testing.md·constraints.md
严重警告
在开始之前,请注意以下常见陷阱: 首选单元测试:默认编写可单元测试的代码。仅在必要时使用集成测试→testing.md Node.js API 限制:不能在
runtime/代码中使用 Node.js API→constraints.md 测试隔离:必须为每个集成测试设置唯一的outDir→testing.md 运行时边界:Core、Vite 与浏览器执行上下文→architecture.md关键文件路径
注意:
node_modules/中的错误堆栈跟踪映射到packages/中的源。详细信息请参见architecture.md。用途
此技能加载相关上下文 - 它不会编排工作流程。加载适当的文档后: 阅读为您的任务推荐的文件 应用所描述的模式和约束 使用提供的命令和文件路径 如果遇到问题,请在文档中搜索错误消息
架构快速总结
三个执行上下文: core/ → Node.js、build/dev 命令、避免使用除 Vite 插件之外的 Node API 运行时/服务器/ → Vite SSR,不能使用 Node API 运行时/客户端/ → 浏览器,不能在所有五种管道类型中使用 Node API: