Architecture

Architecture

给改代码的人看的短地图。决策与 Agent 纪律仍在主仓，不在此展开。

分层

src/config          开关与文案（优先改这里）
src/content         posts / dynamic / spec / _draftbox
src/pages           文件路由 + 少量 api
src/layouts         Layout + MainGridLayout（高风险）
src/components      layout / widget / features / controls / …
src/plugins         remark/rehype
scripts/            LQIP · 字体子集 · new-post
docs/official/      出厂说明书（本地，gitignore）
docs/adr · AGENTS   本站决策与协作

高风险文件

文件	为什么
src/layouts/Layout.astro	Swup、banner、桌宠、音乐、curtain 等钩子集中
src/layouts/MainGridLayout.astro	网格壳、侧栏、横幅高度
gift-lifecycle.ts 等	礼盒状态与侧栏高度同步

非必要不拆、不顺手重构。

配置驱动

改站路径：config → content → public。
组件 type 与 sidebarConfig 必须对齐。

构建链

pnpm build = LQIP → Astro → 字体子集 → Pagefind → dist/

Adapter 由环境决定：默认 Vercel；EDGEONE=1 走 EdgeOne Pages 历史适配；CF_WORKERS=1 走 Cloudflare adapter。当前生产仍以 Vercel 为源站。

生产拓扑

www.threetwoa.live → EdgeOne CDN → Vercel SSR / API origin
img.threetwoa.live → Cloudflare R2

Cloudflare 管权威 DNS 与 R2，不代理主站；EdgeOne Pages 配置保留但不是当前主托管。详见 Deploy-and-CDN。

Ask 边界

/ask 是 React island，浏览器只访问 /api/ask；服务端代理读取 MaxKB token、做站内检索并透传 SSE。当前 siteConfig.pages.ask 在生产为 false，页面、API、桌宠浮窗一起关闭。

运行时：page-lifecycle（防 Swup 泄漏）

Swup 多跳会累积监听器 / observer / timer。src/lib/page-lifecycle.ts 提供 per-page epoch，换页（astro:before-swap）统一清理：组件用 onPage / observePage / setPageTimeout / requestPageFrame 替代裸注册，先 bootPageLifecycle()（幂等）。详见 Performance。

更多

• Official-Docs-Map
• CONTEXT.md
• AGENTS.md
• Contributing