reyalka/astro

Astro 開發者技能

為在 Astro 單一儲存庫（monorepo）中工作的 AI 代理和開發者提供的上下文載入技能。根據您的任務載入相關文檔。

快速決策矩陣

您正在做什麼？ → 閱讀這些文件：

任務	主要文檔	輔助文檔
新增核心功能	architecture.md, constraints.md	testing.md
修復錯誤	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 APIs
• runtime/server/ → Vite SSR，無法使用 Node APIs
• runtime/client/ → 瀏覽器，完全無法使用 Node APIs

五種管線類型：

• RunnablePipeline → 搭配 Vite 載入器系統的 astro dev
• NonRunnablePipeline → 無運行時模組載入的 astro dev（Cloudflare 適配器）
• BuildPipeline → astro build + 預渲染
• AppPipeline → 正式環境無伺服器/SSR
• ContainerPipeline → 容器 API

完整詳情請見 architecture.md。

測試快速摘要

理念：優先使用單元測試而非整合測試。預設編寫可單元測試的程式碼。

單元測試（快速，優先使用）：

• 測試純函數和業務邏輯
• 從基礎設施中提取業務邏輯
• 使用依賴注入

整合測試（較慢，謹慎使用）：

• 僅用於無法單元測試的功能（虛擬模組、完整建置管線）
• 務必設定唯一的 outDir 以避免快取污染

完整模式和範例請見 testing.md。

何時不應使用此技能

• 錯誤分類：請改用 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