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/

运行时：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