Skip to content

项目结构 ​

本文档详细介绍 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
  1. Vite 启动 watch 模式
  2. 监听文件变化
  3. 自动重新构建
  4. 输出到 dist 目录

生产构建 ​

bash
npm run build
  1. TypeScript 类型检查
  2. Vite 构建主程序
  3. Vite 构建 content script
  4. 压缩优化代码
  5. 生成 dist 目录

打包发布 ​

bash
npm run zip

生成可发布的 ZIP 包。


🧪 测试 ​

调试方法 ​

Content Script:

  1. 在目标页面按 F12
  2. 在 Sources 面板找到 content.js
  3. 设置断点调试

Background Script:

  1. 在 chrome://extensions/ 找到扩展
  2. 点击「Service Worker」链接
  3. 打开 DevTools 调试

Popup/Options:

  1. 右键点击弹窗或设置页面
  2. 选择「检查」
  3. 打开 DevTools 调试

📚 代码规范 ​

TypeScript ​

  • 使用严格模式
  • 明确类型声明
  • 避免使用 any

React ​

  • 函数式组件
  • Hooks 优先
  • 组件拆分合理

命名规范 ​

  • 组件:PascalCase
  • 函数:camelCase
  • 常量:UPPER_SNAKE_CASE
  • 文件:kebab-case

下一步

了解 构建部署 流程。

Released under the MIT License.