项目结构
本文档详细介绍 SmartEdit AI 的项目结构和代码组织方式。
📂 目录结构
smartedit-ai/
├── src/ # 源代码目录
│ ├── background/ # Service Worker 后台脚本
│ ├── content/ # Content Script（注入到页面）
│ │ ├── components/ # React 组件
│ │ ├── styles/ # 样式模板数据
│ │ └── utils.ts # 工具函数
│ ├── options/ # 设置页面
│ ├── popup/ # 弹出窗口
│ └── sidepanel/ # 右侧智能助手
├── assets/ # 静态资源
│ └── icons/ # 扩展图标
├── scripts/ # 构建脚本
│ ├── build.js # 打包脚本
│ └── generate-icons.js # 图标生成脚本
├── dist/ # 构建输出目录
├── manifest.json # 扩展配置文件
├── package.json # 项目配置
├── tsconfig.json # TypeScript 配置
├── vite.config.ts # Vite 主配置
├── vite.content.config.ts # Content Script 配置
├── tailwind.config.js # TailwindCSS 配置
└── README.md # 项目说明🔍 核心目录详解
src/background/
Service Worker 后台脚本，负责：
- 扩展生命周期管理
- 右键菜单创建
- 消息通信中转
- Side Panel 管理
主要文件：
background.ts- 后台脚本入口
src/content/
Content Script，注入到网页中，负责：
- 侧边栏渲染
- 页面内容交互
- DOM 操作
- 样式插入
主要文件：
content.tsx- Content Script 入口components/- React 组件Sidebar.tsx- 左侧侧边栏主组件StyleLibrary.tsx- 样式库组件AIWriter.tsx- AI 写作组件ImageCenter.tsx- 配图中心组件
styles/- 样式模板数据titles.ts- 标题样式paragraphs.ts- 正文样式dividers.ts- 分割线样式
utils.ts- 工具函数
src/popup/
浏览器工具栏弹出窗口，提供：
- 快捷入口
- 设置入口
- 状态显示
主要文件：
index.html- 弹窗页面popup.tsx- 弹窗逻辑popup.css- 弹窗样式
src/options/
设置页面，提供：
- AI 服务配置
- 图片服务配置
- 主题设置
- 其他选项
主要文件：
index.html- 设置页面options.tsx- 设置逻辑options.css- 设置样式
src/sidepanel/
右侧智能助手（Side Panel），提供：
- 快捷工具
- 快速笔记
- AI 助手
- 页面信息
主要文件：
index.html- 侧边面板页面SidePanel.tsx- 侧边面板主组件sidepanel.css- 侧边面板样式
📄 配置文件
manifest.json
Chrome 扩展配置文件，定义：
- 扩展基本信息
- 权限声明
- 后台脚本
- Content Scripts
- 图标和资源
package.json
项目配置文件，包含：
- 依赖包列表
- 构建脚本
- 项目元信息
tsconfig.json
TypeScript 配置，设置：
- 编译选项
- 类型检查规则
- 路径映射
vite.config.ts
Vite 主配置，用于构建：
- popup
- options
- background
- sidepanel
vite.content.config.ts
Content Script 专用配置，单独构建 content script。
tailwind.config.js
TailwindCSS 配置，定义：
- 主题颜色
- 扩展样式
- 插件配置
🔄 数据流
消息通信
SmartEdit AI 使用 Chrome 消息 API 进行通信：
┌─────────────┐
│ Popup │
└──────┬──────┘
│
├──────────────┐
│ │
┌──────▼──────┐ ┌───▼────────┐
│ Background │◄─┤ Content │
└──────┬──────┘ └───┬────────┘
│ │
└──────────────┤
│
┌───────▼────────┐
│ SidePanel │
└────────────────┘存储管理
使用 Chrome Storage API 存储：
- API Keys（加密存储）
- 用户设置
- 历史记录
- 收藏内容
🎨 样式组织
TailwindCSS
主要使用 TailwindCSS 进行样式开发：
- 实用优先的 CSS 框架
- 响应式设计
- 深色模式支持
CSS Modules
部分组件使用 CSS Modules：
- 样式隔离
- 避免命名冲突
🧩 组件设计
组件层次
App
├── Sidebar (左侧侧边栏)
│ ├── StyleLibrary (样式库)
│ ├── AIWriter (AI 写作)
│ └── ImageCenter (配图中心)
├── Popup (弹出窗口)
└── SidePanel (右侧助手)
├── QuickTools (快捷工具)
├── QuickNotes (快速笔记)
├── AIAssistant (AI 助手)
└── PageInfo (页面信息)状态管理
使用 Zustand 进行状态管理：
- 轻量级状态库
- 简单易用
- TypeScript 友好
🔧 工具函数
src/content/utils.ts
提供常用工具函数：
- DOM 操作
- 样式插入
- 文本处理
- API 调用
📦 构建流程
开发模式
bash
npm run dev- Vite 启动 watch 模式
- 监听文件变化
- 自动重新构建
- 输出到 dist 目录
生产构建
bash
npm run build- TypeScript 类型检查
- Vite 构建主程序
- Vite 构建 content script
- 压缩优化代码
- 生成 dist 目录
打包发布
bash
npm run zip生成可发布的 ZIP 包。
🧪 测试
调试方法
Content Script:
- 在目标页面按 F12
- 在 Sources 面板找到 content.js
- 设置断点调试
Background Script:
- 在
chrome://extensions/找到扩展 - 点击「Service Worker」链接
- 打开 DevTools 调试
Popup/Options:
- 右键点击弹窗或设置页面
- 选择「检查」
- 打开 DevTools 调试
📚 代码规范
TypeScript
- 使用严格模式
- 明确类型声明
- 避免使用 any
React
- 函数式组件
- Hooks 优先
- 组件拆分合理
命名规范
- 组件：PascalCase
- 函数：camelCase
- 常量：UPPER_SNAKE_CASE
- 文件：kebab-case
下一步
了解 构建部署 流程。