5.4 KiB

Raw Blame History

AGENTS.md — 帆幕（Fanmu）总览

面向 AI 编码代理的仓库导览。修改任何代码前，先读本文件与目标子包的 AGENTS.md。

项目是什么

帆幕（Fanmu）：私有影音库 · 弹幕观影 · 网盘挂载。本仓库为产品仓，业务代码进入既有分层。视觉基线见 DESIGN.md。

技术栈：Astro 7（SSR）+ React 19 islands · tRPC v11 · Drizzle ORM + Turso/libSQL · Tailwind CSS 4 · TypeScript 7 · Biome · Yarn 4 workspaces + Turbo。

模块地图

包	职责	依赖
`@app/types`	Zod 入参 schema + 共享输出类型	zod
`@app/models`	Drizzle 表定义（唯一 schema 源）	drizzle-orm
`@app/db`	libSQL/Turso 客户端单例 + drizzle-kit	models
`@app/dao`	数据访问层（`userDao` / `mountDao` / `mediaItemDao` 等）	db, models
`@app/trpc`	tRPC 路由 + service 业务逻辑（调用 DAO）	types, dao
`@app/web`	Astro 前端 + React islands + 本地 tRPC HTTP 适配	trpc, types, design-tokens, seo-geo, i18n, ui
`@app/ui`	shadcn 风格基础 UI 组件（源码直出 + Storybook）	design-tokens, react (peer)
`@app/design-tokens`	共享 CSS 设计令牌（`tokens.css`）	—
`@app/seo-geo`	SEO/GEO 纯函数（meta、sitemap、JSON-D、llms.txt）	zod, schema-dts, escape-html, fast-xml-builder, serialize-javascript, mdast-util-to-markdown
`@app/i18n`	文案与 locale 纯函数（zh-CN / en、t()、Accept-Language）	—
`@app/adsense`	AdSense 脚本加载 + `AdSlot` React 组件	react (peer)
`@app/docs`	产品文档站（VitePress，中文根路径 + 英文 `/en`）	—（仅 vitepress）

依赖方向（只允许向下）：

web ──► trpc ──► dao ──► db ──► models
 │        │                 │
 │        └─────────────────┴──► types
 ├──► design-tokens
 ├──► seo-geo
 ├──► i18n
 ├──► adsense
 └──► ui

docs（独立，不依赖上述业务包）

禁止循环依赖。跨包只通过 package.json 的 exports 入口引用，不要 deep import。

目录约定

源码在各包 src/；构建产物在 dist/（git 忽略，勿手改）。
环境变量模板见 .env.example：TURSO_DATABASE_URL、TURSO_AUTH_TOKEN、PUBLIC_SITE_URL。
根 .env 由 packages/db/drizzle.config.ts 与 packages/db/scripts/seed.ts 手动加载（monorepo 下工具不会自动读根 env）。
分层不跳层：业务实体按 types → models → dao → trpc → web 落地；领域逻辑进 service，SQL 进 dao。
e2e/：Playwright 端到端测试（配置在根 playwright.config.ts），不是 workspace 包。
app/docs/：VitePress 文档站源码（.vitepress/ 配置 + guide/ 中文 + en/guide/ 英文）。

常用命令

yarn install
yarn typecheck          # 全仓 typecheck
yarn lint               # Biome
yarn build              # 全仓 build（依赖拓扑）
yarn build:web          # 仅 @app/web + 上游依赖闭包（日常/CI 更快）
yarn dev:web            # Astro :4321
yarn dev:api            # 独立 tRPC :4000（web 内嵌 /api/trpc 时通常不需要）
yarn docs:dev           # VitePress 文档站
yarn docs:build
yarn test:e2e           # Playwright（自动起 webServer）
yarn db:generate        # Drizzle 迁移生成
yarn db:push            # 推 schema
yarn db:seed            # 初始化默认管理员（幂等）
yarn db:studio
yarn storybook          # @app/ui Storybook :6006

改某个包时可先 yarn workspace @app/<name> typecheck。

全局约定（必须遵守）

TypeScript 很严：strict + noUncheckedIndexedAccess + exactOptionalPropertyTypes + noPropertyAccessFromIndexSignature。可选属性传 undefined 时类型要写 ?: T | undefined。
ESM only（"type": "module"）。源码内相对 import 带 .js 后缀（TS bundler 解析）。
格式化/静态检查：Biome（2 空格、行宽 100）。不要引入 ESLint/Prettier。
校验：对外输入用 Zod 4，定义放在 @app/types，router/service 共用。
数据库模型只放 @app/models；查询/SQL 只放 @app/dao；@app/db 只建连接单例，不建表、不含业务规则。
UI：设计令牌从 @app/design-tokens 引入；组件优先用 @app/ui（shadcn 风格，源码在 packages/ui）+ cn()。视觉遵循 DESIGN.md。
构建顺序：改 types/models 后需先 build 上游，再让下游 typecheck（Turbo dependsOn: ["^build"] 已配置）。
注释：只写非显而易见的 WHY；默认不写注释。
新增业务实体：按 types → models → dao → trpc → web 分层落地，不要跳层。

各包入口

细节见各包 AGENTS.md：

5.4 KiB Raw Blame History Unescape Escape