feat: 更新嵌入式文件系统逻辑，支持路径清理和静态资源请求处理，增强前端主题切换能力

docs/development-guidelines.md

@@ -220,6 +220,7 @@ V3 新增行为：
 * API 请求统一收敛到 `atsf_server/web/lib/api/`
 * 页面路由与布局放在 `app/`，业务逻辑放在 `features/`
 * 构建产物必须保持可被 Go Server 静态托管
+* 新前端必须支持亮色 / 暗色模式切换，且主题能力不得只停留在局部页面或单个组件
 
 如果第三版要新增页面，优先原则：
 

docs/frontend-development-guidelines.md

@@ -30,7 +30,7 @@
 * TanStack Query
 * React Hook Form + Zod
 * Zustand（仅限轻量客户端状态）
-* Vitest + Testing Library + Playwright
+* Vitest + Testing Library
 
 要求：
 
@@ -39,6 +39,7 @@
 * 默认使用 App Router，不新建 Pages Router 结构
 * 默认使用 Tailwind CSS，不再引入新的大型样式框架
 * 默认使用 NextUI 作为统一视觉组件基础
+* 前端必须支持亮色 / 暗色模式切换，且主题切换能力应作为基础能力贯穿布局、组件与页面实现
 
 禁止：
 
@@ -310,6 +311,8 @@ tests/
 * Tailwind CSS 为布局、间距、响应式与业务样式扩展的基础方案
 * 样式通过设计 token、NextUI 主题能力与语义类组合实现
 * 页面视觉风格统一、留白一致、层级清晰
+* 所有新页面与基础组件必须同时兼容亮色与暗色主题，禁止只实现单一主题
+* 主题切换必须可由用户主动触发，并在路由切换和刷新后保持一致
 
 ### 9.2 设计 token
 
@@ -318,6 +321,7 @@ tests/
 * 主色、成功色、警告色、危险色
 * 边框色、背景色、弱文本色、强文本色
 * 圆角、阴影、间距、层级
+* 亮色 / 暗色两套语义 token 映射，以及主题切换所需的前景色、表面色、分隔色
 
 ### 9.3 组件外观要求
 
@@ -330,6 +334,7 @@ tests/
 * 大量硬编码颜色值
 * 在 JSX 中堆砌不可读的超长类名且不抽组件
 * 同一个状态在不同页面使用不同颜色语义
+* 仅在暗色或仅在亮色模式下校验视觉效果后直接交付
 
 ---
 

docs/frontend-revamp-plan.md

@@ -59,6 +59,7 @@
 * 使用 TypeScript 建立明确类型边界
 * 建立可维护的目录结构、组件分层与请求层规范
 * 提升首屏体验、构建质量、代码可测试性与长期可演进性
+* 建立统一的亮色 / 暗色主题体系，并支持用户切换
 
 ### 3.3 约束目标
 
@@ -255,12 +256,29 @@ atsf_server/web/
 2. 接入 ESLint、Prettier、基础测试框架
 3. 建立 `app/`、`features/`、`components/`、`lib/` 基础结构
 4. 完成全局布局、主题变量、基础 UI 组件骨架
+5. 建立亮色 / 暗色主题 token 与主题切换基础设施
+
+模式切换补充要求：
+
+* 阶段 1 即完成全局主题模式基础设施，不将模式切换延后到业务页面迁移阶段
+* 默认支持“跟随系统”与“用户手动切换”两种模式来源
+* 至少支持 `light`、`dark`、`system` 三种主题状态
+* 用户手动选择后必须持久化，并在刷新、重新进入页面、路由切换后保持一致
+* 首屏渲染应尽量避免主题闪烁，不能出现明显的先亮后暗或先暗后亮跳变
+* 布局层、导航层、页面容器、基础卡片、按钮、表单容器等基础骨架必须率先接入双主题 token
+* 主题切换实现应基于统一主题上下文或全局主题状态，不允许页面各自维护一套切换逻辑
+* 所有新增颜色变量应优先落在语义 token 层，不直接把亮暗配色散落在业务组件中
 
 验收：
 
 * 可本地启动开发环境
 * 可生成静态构建产物
 * Go Server 可正确托管构建结果
+* 亮色 / 暗色主题可切换，且基础布局在两种主题下均可正常显示
+* 首次进入页面时可正确应用默认主题策略
+* 用户切换主题后刷新页面仍保持所选模式
+* 首页、公共布局、后台主框架在 `light` / `dark` 下均无明显可读性问题
+* 阶段 1 交付的基础组件不依赖单一暗色样式前提
 
 ### 阶段 2：认证与框架层迁移