# AGENTS.md — 博客前端项目

Vue 3 + TypeScript + Vite 7 博客前端（后端 API 为 `https://www.hxyouzi.com/api`）。UI：naive-ui + UnoCSS + vue-devui(Tag) + md-editor-v3。风格为暖色玻璃拟态（主色 `#ec66ab`）。

## 常用命令

| 命令                 | 用途                                                      |
| -------------------- | --------------------------------------------------------- |
| `npm run dev`        | 开发服务器（端口 8989，路径 base `/blog/`，首页 `/home`） |
| `npm run type-check` | vue-tsc 类型检查（**改完代码必跑**）                      |
| `npm run b`          | type-check + build                                        |
| `npm run build-only` | 仅构建                                                    |

## 全局约定（勿重复 import / 注册）

- 全局变量直接使用、**无需 import**（类型在 `env.d.ts`）：`$http`（API）、`$msg`（naive message）、`$store`（pinia）、`$cookies`、`$modal`（弹窗，参数 `{title, content, contType: 'text'|'input', ...}`）。
- 组合式 API 已自动导入（`ref/computed/watch/useRoute/defineStore/useMessage` 等，见 `auto-imports.d.ts`），**不要重复 import**。
- `src/components/` 下组件与 naive-ui `<n-xxx>` 自动注册（`components.d.ts`），模板直接用。
- 图标：`src/icon/` 顶层 svg 注册为 `<icon-<name> />`；`icon/menu/`、`icon/plink/` 子目录**不自动注册**，需手动 import（vite-svg-loader）。
- API 模块：新建 `src/api/<name>/index.ts` 即自动挂到 `$http.<name>`（`import.meta.glob`）。**新增 icon/api/store 文件后需重启 dev server**（glob 构建时静态分析）。

## 架构速览

- **路由**：unplugin-vue-router 文件系统路由（`src/views/`），视图用 `definePage()`；`src/router/index.ts` 中 `/` 重定向到 `/home`，带 NProgress 守卫。
- **API 调用**：`$http.<模块>.<函数>()` → 请求层 `src/util/request.ts`（baseURL `https://www.hxyouzi.com/api`，token 从 cookie 自动带 Bearer，响应拦截直接返回 `response.data`）。
- **Stores**：`src/stores/` setup 风格；`nav.ts` 提供 `navH`（导航栏高度，页面布局需减它）、`log.ts` 提供 `isLogin`。访问：`$store.nav.useNavStore()`。
- **UnoCSS**：重度使用 arbitrary values（`bg-[...]`、`shadow-[...]`）；卡片类优先用 `uno.config.ts` 的 shortcuts（`blog-list-panel`、`blog-detail-card`、`blog-detail-card-soft`、`home-glass-surface` 等）。
- **Less**：vite 已全局注入 `@primary: #ec66ab` 等变量，less 块内直接用。字体：霞鹜文楷（正文）+ Fira Code（代码）。
- **页面背景模板**：所有视图沿用统一背景 — 暖色径向渐变 + 两个 blur 圆 + 网格 overlay（参考 `src/views/Home.vue` 顶部）。

## 常见陷阱

- `console.log` 在 build 时会被 esbuild 删除（`pure: ["console.log"]`），调试用 dev 模式。
- 登录态：cookie `userinfo` 存在即视为已登录。
- `$http.mix.getHoli()` 后端 500 不可用，必须 try/catch 防御式处理（失败静默隐藏）。
- 内部滚动容器用 naive-ui `n-scrollbar` 时监听 `@scroll`，**不要监听 window scroll**（内部滚动不冒泡）。
- `Waterfall` 组件需传 `row-key="filepath"`（GalleryItem 无 id 字段）。
- 阴影规范：三层体系（接触 `rgba(97,121,146,0.05)` + 主体 `0.08-0.13` + 暖色 `rgba(178,128,88,*)` + `inset 0 1px 0 rgba(255,255,255,0.7)` 高光），避免纯冷灰 `rgba(86,111,137,*)`。
- 修改 `Home.vue` 导航卡片动画时先阅读 `/memories/repo/blog-nav.md`（FLIP 动画有特殊约束）。

## 相关资料

- 导航首页细节（FLIP 动画、侧边栏、画廊约定）：仓库记忆 `/memories/repo/blog-nav.md`
- UI 截图批量转 Vue 组件：技能 `.agents/skills/ui/SKILL.md`