WordFairy (词妆精灵) 技术文档

项目概述

WordFairy 是一款智能的 Chrome 浏览器扩展，专注于网页文本的智能分析和可视化高亮。该扩展利用 AI 技术自动识别和分类网页中的关键实体（人名、地名、时间、组织等），并通过不同颜色的高亮显示来提升用户的阅读体验。

核心功能

1. 智能实体识别

🧠 基于 AI 模型（默认：google/gemini-2.0-flash-lite-001）自动识别文本中的关键实体
📊 支持四大类别：人名、地名、时间、组织机构
🔢 统计每个词汇在文本中的出现频次
📋 生成结构化的词汇列表

2. 可视化高亮系统

🎨 为不同类别的词汇应用独特的高亮颜色
🔍 支持点击词汇在页面中循环定位
📋 一键复制词汇到剪贴板
⚡ 实时切换高亮开关

3. 用户界面

📱 固定侧边栏设计，提供持久化访问
⚙️ 支持自定义 API 密钥和模型配置
🔒 本地存储用户配置，保护隐私

技术架构

文件结构

WordFairy/
├── manifest.json          # Chrome扩展配置文件
├── background.js           # 后台脚本，处理扩展图标点击事件
├── content.js             # 内容脚本，核心功能实现
├── package.json           # 项目依赖配置
├── images/                # 扩展图标资源
│   ├── icon16.png
│   ├── icon48.png
│   └── icon128.png
├── styles/                # 样式文件
│   ├── highlight.css      # 高亮效果样式
│   ├── sidebar-isolated.css # 侧边栏隔离样式
│   ├── sidebar.css
│   ├── reader.css
│   └── tailwind.css
├── tailwind.config.js     # Tailwind CSS配置
├── postcss.config.js      # PostCSS配置
└── readme.md              # 项目说明文档

核心组件

1. 后台脚本 (background.js)

功能：监听扩展图标点击事件
职责：向当前标签页发送消息以切换侧边栏显示状态
错误处理：包含重新注入内容脚本的容错机制

2. 内容脚本 (content.js)

这是扩展的核心文件，包含以下主要功能模块：

侧边栏管理

createSidebar(): 动态创建侧边栏 DOM 结构
initializeSidebar(): 延迟加载侧边栏，优化性能
initializeEventListeners(): 初始化所有事件监听器

AI 词汇提取

extractWords(apiKey, modelName): 调用 OpenRouter API 进行词汇分析
支持自定义模型选择
实现词频统计和结果缓存

高亮系统

highlightWords(categories): 主高亮控制函数
applyHighlight(categories): 应用高亮效果
removeHighlights(container): 移除高亮效果
highlightAllWords(container, words, className): 递归处理文本节点
toggleHighlight(): 切换高亮显示状态

用户交互

displayWordCategories(): 渲染词汇分类列表
词汇点击事件：复制到剪贴板 + 页面定位
配置保存：API 密钥和模型名称的本地存储

3. 样式系统

高亮样式 (highlight.css)

/* 四种类别的高亮颜色 */
.wordFairy-highlight-person     { background: rgba(219, 68, 55, 0.2); }
.wordFairy-highlight-location   { background: rgba(66, 133, 244, 0.2); }
.wordFairy-highlight-time       { background: rgba(15, 157, 88, 0.2); }
.wordFairy-highlight-organization { background: rgba(244, 180, 0, 0.2); }

侧边栏样式 (sidebar-isolated.css)

使用 all: initial 重置样式，避免网页样式干扰
固定定位在页面右侧，宽度 320px
最高 z-index 确保显示优先级
响应式设计，支持滚动

API 集成

OpenRouter API

端点：https://openrouter.ai/api/v1/chat/completions
默认模型：google/gemini-2.0-flash-lite-001
请求格式：标准 OpenAI 兼容格式
提示词策略：结构化 JSON 输出要求

数据流程

用户点击"提取分类词汇"按钮
获取页面文本内容 (document.body.innerText)
构造提示词，要求返回 JSON 格式的分类结果
调用 OpenRouter API
解析返回结果，统计词频
缓存到 Chrome Storage
应用高亮效果

数据存储

Chrome Storage Local

// 存储结构
{
  openRouterApiKey: "用户的API密钥",
  modelName: "模型名称",
  wordCategories: {
    person: [{word: "张三", count: 3}],
    location: [{word: "北京", count: 2}],
    time: [{word: "2024年", count: 1}],
    organization: [{word: "清华大学", count: 2}]
  }
}

性能优化

1. 延迟加载

侧边栏仅在用户首次激活时创建
样式文件按需加载

2. 高效文本处理

递归处理 DOM 文本节点
避免重复处理已高亮的内容
跳过侧边栏内部节点

3. 状态管理

页面加载时清理之前状态
本地缓存提取结果，避免重复 API 调用

用户体验设计

1. 非侵入式设计

侧边栏不影响原页面布局
高亮效果可随时开关
样式隔离防止冲突

2. 交互反馈

实时状态提示
复制成功 Toast 提示
词汇点击的视觉反馈

3. 错误处理

API 调用失败的友好提示
配置验证和错误提示
容错机制确保扩展稳定性

开发工具链

构建工具

Tailwind CSS: 现代化 CSS 框架
PostCSS: CSS 后处理器
Autoprefixer: 自动添加浏览器前缀

开发依赖

{
  "autoprefixer": "^10.4.16",
  "postcss": "^8.4.31",
  "tailwindcss": "^3.3.0"
}

安全考虑

1. 数据隐私

API 密钥仅存储在本地
不收集用户浏览数据
文本处理完全在客户端进行

2. 权限控制

最小权限原则：仅请求必要的 activeTab、storage、scripting 权限
内容脚本仅在用户激活时运行

未来规划

即将实现的功能

自定义提取分类
- 用户可自定义词汇分类和描述
- 动态生成提示词
- 支持添加/删除分类

技术改进方向

支持更多 AI 模型提供商
优化大文档的处理性能
增加词汇导出功能
支持多语言界面

安装和部署

开发环境安装

# 克隆项目
git clone https://github.com/comoysha/WordFairy2.git
cd WordFairy2

# 安装依赖
npm install

# 构建样式（如需要）
npm run build-css

Chrome 扩展安装

打开 Chrome 浏览器
访问 chrome://extensions/
启用"开发者模式"
点击"加载已解压的扩展程序"
选择项目文件夹

配置使用

获取 OpenRouter API 密钥
点击扩展图标打开侧边栏
输入 API 密钥并保存
选择合适的 AI 模型
开始使用智能高亮功能

技术特色

AI 驱动：利用最新的大语言模型进行智能文本分析
实时处理：无需后端服务，完全在浏览器端实现
高性能：优化的 DOM 操作和文本处理算法
用户友好：直观的界面设计和流畅的交互体验
隐私保护：本地化处理，不上传用户数据

WordFairy 代表了现代浏览器扩展开发的最佳实践，结合了 AI 技术、现代前端框架和用户体验设计，为网页阅读带来了全新的智能化体验。

FilesExpand file tree

技术文档.md

Latest commit

History