Lite Astro Studio

一个轻量的 Astro + Svelte + Tailwind + FastAPI + Supabase 示例项目。

当前结构重点是两件事：

• 前端保留轻量的 Astro 页面和 Svelte islands。
• 多个第三方 API 统一经由 FastAPI -> Supabase api-hub 转发，避免把密钥和 provider 逻辑散在各处。

快速开始

安装前端依赖：

npm install

前端本地环境变量：

PUBLIC_API_BASE_URL=http://127.0.0.1:8000

后端依赖：

python -m venv backend\.venv
backend\.venv\Scripts\python.exe -m pip install --upgrade pip
backend\.venv\Scripts\python.exe -m pip install -r backend\requirements.txt

本地联调

推荐开 3 个终端：

npm run dev:web
npm run dev:api
npm run dev:supabase

本地地址：

• 前端：http://127.0.0.1:4321
• FastAPI：http://127.0.0.1:8000
• Supabase Edge Function：http://127.0.0.1:54321/functions/v1/api-hub

项目结构

src/
  components/
    chrome/      # 共享壳层
    docs/        # 文档页面相关组件
    islands/     # Svelte widgets
    ui/          # 共享 UI 组件
  data/          # 页面文案和示例数据
  layouts/       # 三种页面布局
  lib/           # 前端调用封装
  pages/         # Astro 页面入口
backend/
  app/           # FastAPI 路由、配置、服务
  scripts/       # 后端联调和烟测脚本
scripts/
  dev-api.ps1
  dev-supabase.ps1
  clean.ps1
supabase/
  functions/     # api-hub Edge Function 和 provider 分发
docs/
  api-interface.md
  api-design.md
  api-testing.md

API 文档

新增的接口相关文档放在 docs/：

• 接口文档：给前后端调用方看，重点是怎么调和返回什么。
• 设计文档：给维护者看，重点是内部实现、边界和扩展方式。
• 测试文档：给 QA 和开发者看，重点是怎么验证接口质量。

清理命令

为了避免过度工程化，当前只提供一套很轻的 PowerShell 清理脚本，用 scope 区分清理范围。

npm run clean
npm run clean:web
npm run clean:python
npm run clean:runtime
npm run clean:supabase

各命令职责：

• clean:web：清理前端构建和开发缓存，例如 .astro、dist、node_modules/.vite
• clean:python：清理 backend 下的 __pycache__、.pyc、.pyo、.pytest_cache
• clean:runtime：清理本地联调产生的日志和 pid 文件
• clean:supabase：清理项目目录下的 Supabase 本地临时目录
• clean：执行上面几类清理的全集

刻意没有清理这些内容：

• node_modules
• backend/.venv
• Supabase Docker 容器和卷

这些更接近“依赖和运行环境”，不是这个项目里日常构建产生的缓存。

质量检查

前端检查：

npm run check

后端烟测：

.\backend\.venv\Scripts\python.exe backend\scripts\smoke_repo_dispatch.py

Python 语法检查：

python -m compileall backend\app backend\scripts

当前闭环示例

RepoWidget 已经接成真实链路：

RepoWidget.svelte -> src/lib/github.ts -> POST /api/gateway/dispatch -> FastAPI -> Supabase api-hub -> GitHub API

如果后续要新增 API，优先继续复用这条链路，而不是给前端暴露新的第三方接口地址。