app-template/app/web/AGENTS.md

AGENTS.md — @app/web

职责

Astro SSR 前端（Node standalone）：页面、布局、React islands、tRPC HTTP 适配、SEO 文本端点、i18n 路由。

脚手架基线页面：首页、鉴权、仪表盘（user 列表示例）、设置。视觉遵循仓库根 DESIGN.md 与 @app/design-tokens。

i18n

• 语言：zh-CN（/zh-CN/...）、en（/en/...）。中文也带前缀，不把中文留在裸 /。
• 单套路由：src/pages/[locale]/index.astro、[locale]/dashboard.astro + src/views/*；禁止再复制 pages/zh-CN、pages/en 目录。
• 文案：@app/i18n 的 t(locale, key)；React island 传 locale prop，不引入 i18next。
• 裸 /：src/middleware.ts 按 cookie app-lang → Accept-Language 跳 /zh-CN 或 /en；响应 Vary: Accept-Language；非法/大小写 zh-cn 规范化。
• 手动切换：header 语言链接写 cookie 后跳转（布局内联脚本）。
• 设计说明：docs/superpowers/specs/2026-09-24-i18n-design.md。

结构

src/
  pages/
    [locale]/index.astro | dashboard.astro | auth/* | settings.astro
    api/trpc/[...trpc].ts | api/users.ts
    sitemap.xml.ts | robots.txt.ts | llms.txt.ts | llms-full.txt.ts
  views/
    home.astro | dashboard.astro | auth.astro | error.astro
  middleware.ts       # 裸 / 语言检测跳转 + locale 规范化
  layouts/AppLayout.astro
  components/
    UserList.tsx | UserMenu.tsx | ThemeSwitch.tsx | AuthForm.tsx | errors/*
  lib/
    trpc.ts | seo.ts（getSiteSeo(locale)）| theme.ts | utils.ts（cn re-export）
  styles/globals.css
astro.config.ts

路径别名

• ~/*、@/* → src/*
• @app/i18n / @app/trpc / @app/types / @app/db / @app/seo-geo → 各包 dist（astro.config.ts）
• @app/ui → packages/ui/src（源码直出）
• typecheck 时 tsconfig paths 指向各包 src——改上游后先 build 再 dev/build web

页面与 SEO

• 布局统一走 AppLayout.astro，必传 locale，通过 seo prop 传 PageSeoInput。
• 站点 SEO：lib/seo.ts 的 getSiteSeo(locale)；sitemap 双语 URL + hreflang alternates。
• 新公开页面：登记 PUBLIC_PATHS / views，并同步 getSiteSeo 的 llms.pages 与 sitemap。

React islands

• 需要交互才加 client:load / client:visible。
• 文案：import { t } from "@app/i18n" + locale prop；不要绑 i18next Provider。
• tRPC：组件内 QueryClientProvider + trpc Provider（参考 UserList.tsx）。
• UI：@app/ui（通用基础组件）+ cn()（~/lib/utils re-export）；颜色用 CSS 变量。

修改指南

• 加文案：先改 packages/i18n/src/messages/zh-CN.ts，再补 en.ts。
• 加业务页面：在下游仓库扩展，勿把产品业务写回模板。
• 调 API：优先 tRPC；api/users.ts 仅演示。
• 主题：localStorage key app-theme；语言 cookie app-lang。
• Astro 保留字：组件 props 避免 slot。

命令

yarn workspace @app/web typecheck
yarn workspace @app/web lint
yarn workspace @app/web dev       # :4321
yarn workspace @app/web build
yarn dev:web