基于上下文的 AI 外语阅读助手 Chrome 插件
Contextify 帮助中文母语用户阅读英文网页时，直接在当前页面选中单词、短语、句子或段落，结合前后文获得更贴合语境的中文解释，并可保存为本地学习笔记。
当前状态：个人开源学习项目；V0.1 本地 MVP 已完成，V0.2 正在迭代产品体验。暂未上架 Chrome Web Store。
- 嵌入阅读流：用户不需要复制文本、切换窗口、手写 prompt，直接在当前网页选中并解释。
- 上下文解释：解释不只翻译选中文本，而是结合前后文判断当前语境下的含义。
- 模式化输出：支持普通、简洁、科研、文学 4 种解释模式，面向不同阅读场景。
- 本地优先：配置和笔记保存在浏览器本地，不依赖项目自建后端。
- 低复杂度技术栈：使用 Manifest V3 + 原生 HTML/CSS/JS，避免在 MVP 阶段引入不必要的框架和构建系统。
截图目录已预留在 docs/assets/。后续可补充：
docs/assets/
screenshot-explain-panel.png
screenshot-notes-page.png
screenshot-options-page.png
| 功能 | 说明 |
|---|---|
| 选中解释 | 在网页中选中文本后，通过页面按钮触发解释 |
| 上下文感知 | 提取选中文本前后约 500 字符上下文 |
| 页面浮窗 | 在当前网页内展示加载状态、解释结果和错误提示 |
| 解释模式 | 支持普通、简洁、科研、文学 4 种解释模式 |
| 模型配置 | 用户自行填写 API Key、Base URL、Model |
| 本地笔记 | 保存解释记录，并在笔记页搜索、查看、删除和批量管理 |
- Base URL 预设与 API 连通性测试
- 深入解释与继续追问
- 首次使用引导
- 解释内容一键复制
- 错误提示与失败恢复
- 加载状态优化与可取消请求
- UI 整体优化与 Logo
- Chrome Extension Manifest V3
- 原生 HTML / CSS / JavaScript
- Shadow DOM（页面按钮和浮窗样式隔离）
chrome.storage.local- OpenAI-compatible API
项目当前不引入 React、TypeScript、Vite、Webpack、后端、数据库或账号系统。
| 决策 | 原因 |
|---|---|
| LLM 请求由 background service worker 发起 | 避免 content script 直接请求外部 API，减少宿主网页 CSP 影响 |
| 页面按钮和浮窗使用 Shadow DOM | 隔离宿主网页样式，降低 UI 被污染的概率 |
Prompt 逻辑集中在 src/shared/promptTemplates.js |
便于维护解释模式和输出结构 |
存储逻辑集中在 src/shared/storage.js |
避免各模块散落调用 chrome.storage.local |
| 初期不引入框架和构建工具 | 降低本地 MVP 复杂度，保持插件目录可直接加载 |
- 打开 Chrome，地址栏输入
chrome://extensions/ - 右上角开启「开发者模式」
- 点击「加载已解压的扩展程序」
- 选择本项目根目录（含
manifest.json的这一层） - 打开插件 Options 页，填写 API Key、Base URL 和 Model
- 在英文网页中选中文本，点击页面上的解释按钮
Contextify 使用用户自己的 OpenAI-compatible API 配置。
| 配置项 | 说明 |
|---|---|
| API Key | 用户自己的模型服务密钥 |
| Base URL | 兼容 OpenAI Chat Completions 的接口地址 |
| Model | 要调用的模型名称 |
API Key 仅保存在本地浏览器的 chrome.storage.local 中。本项目不包含后端服务，也不会把配置同步到云端。
更多说明见 PRIVACY.md。
manifest.json
src/
background.js
content.js
popup/
options/
notes/
shared/
docs/
assets/
v0.1/
v0.2/
| 文档 | 用途 |
|---|---|
docs/v0.2/README.md |
V0.2 文档入口与当前方向 |
docs/v0.2/requirements.md |
V0.2 需求列表、优先级和状态 |
docs/v0.2/prd/ |
V0.2 单项需求 spec |
docs/v0.1/prd/v0.1/prd_v0.1.md |
V0.1 产品范围存档 |
docs/v0.1/TECH_PLAN.md |
V0.1 技术方案存档 |
AGENTS.md |
多 agent 协作规则 |
CLAUDE.md |
Claude Code 主开发规则 |
PRIVACY.md |
隐私与数据处理说明 |
TEMP_PROMPT.md、个人面试材料、本地 agent 运行文件等不属于正式项目内容，已通过 .gitignore 排除。
这是一个独立产品与开发项目。我负责：
- 产品定位、用户场景、MVP 边界设计
- V0.2 需求拆分、优先级管理和 spec 编写
- Chrome 插件架构设计与功能实现协作
- Prompt 输出结构设计与解释模式验收
- README、PRD、handoff、测试清单等项目文档维护
- 暂未上架 Chrome Web Store
- 暂无后端、账号、云同步
- 暂未支持 PDF / EPUB
- 暂无自动化测试体系
This project is open-sourced under the MIT License.