diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..b889a1e
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,70 @@
+# AGENTS.md
+
+This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
+
+## 项目概述
+
+yolo-web-frontend 是一个 Vue 3 Web 前端应用，主要作为 Electron 桌面应用的 UI 层运行，提供 TikTok 自动化管理功能。
+
+## 常用命令
+
+```bash
+npm run dev      # 启动开发服务器 (端口 5173)
+npm run build    # 生产环境构建 (输出到 dist/)
+npm run preview  # 预览生产构建
+```
+
+## 技术栈
+
+- **框架**: Vue 3 + Composition API (`<script setup>`)
+- **构建工具**: Vite 5
+- **UI 组件库**: Element Plus
+- **样式**: Tailwind CSS 3 + Less
+- **状态管理**: Pinia
+- **路由**: Vue Router 5 (Hash History 模式)
+- **国际化**: Vue I18n (中/英文)
+- **HTTP 请求**: Axios
+- **实时通信**: GoEasy
+
+## 架构说明
+
+### 路径别名
+`@` 映射到 `src/` 目录
+
+### 目录结构
+- `src/pages/` - 顶层页面组件 (LoginPage, ConfigPage, UpdateChecker)
+- `src/views/` - 业务视图页面
+- `src/views/tk/` - TikTok 相关主视图
+- `src/views/tk-mini/` - TikTok Mini 程序视图
+- `src/layout/` - 布局组件 (WorkbenchLayout, TkLayout)
+- `src/components/` - 可复用组件
+- `src/components/tk-mini/` - TikTok Mini 专用组件
+- `src/stores/` - Pinia 状态存储
+- `src/api/` - API 请求模块
+- `src/utils/` - 工具函数
+- `src/locales/` - 国际化翻译文件
+
+### 应用入口流程
+1. `main.js` 初始化 Vue 应用，注册 Pinia、Router、I18n、Element Plus
+2. `App.vue` 作为根组件，管理页面状态 (login → config → browser)
+3. 在 Electron 环境下会进行强制更新检查
+
+### Electron 集成
+应用通过 `window.electronAPI` 与 Electron 主进程通信，主要接口包括：
+- 视图管理: `showViews()`, `hideViews()`
+- 自动化控制: `startTikTokAutomation()`, `stopTikTokAutomation()`
+- 状态同步: `getRotationStatus()`, `getGreetingStats()`
+- 登录管理: `logout()`, `checkHealth()`
+
+使用 `src/utils/electronBridge.js` 中的 `isElectron()` 判断运行环境。
+
+### 本地存储键
+- `user_data` - 用户登录信息
+- `autoDm_runConfig` - 自动化运行配置
+
+## 代码规范
+
+- Vue 组件使用 `<script setup>` 语法
+- 组件文件使用 PascalCase 命名
+- 工具函数使用 camelCase 命名
+- 样式优先使用 Tailwind CSS 类，复杂样式使用 Less