Painless

把中文网页变成「英文主阅读 + 中文辅助理解」的学习输入

许可协议：本项目采用 Apache License 2.0。

这是什么

很多翻译工具追求的是“尽快看懂”，所以通常会把网页整体翻回中文。
Painless 的思路不一样，它更像一个面向英语学习的阅读辅助层：

• 非英文网页先转成英文，先把输入统一到英语。
• 再结合你的英语水平、词库和 AI 模型，只对不会的词或词组补充中文辅助。
• 页面回写时只改文本内容，不重写整块 DOM，尽量降低对原站点结构和交互的干扰。

如果你想把论坛、博客、教程站、知识社区变成更容易坚持阅读的英语材料，这个项目就是为这个场景做的。

适合谁

• 想把中文网页转成更适合练英语阅读的输入，而不是直接翻回中文的人。
• 想保留英文句子结构，只给陌生词一个“够用的提示”的人。
• 想按站点、词库、学习水平细调阅读体验的人。
• 想自己掌控 DeepLX、AI 模型和云同步后端的人。

界面预览

页面	你能做什么
通用设置	控制启用状态、英语水平、替换样式、运行网站白名单
模型设置	配置 AI 模型、Prompt、并发与批量请求
云同步	GitHub 登录后把配置推送到自己的云端

核心能力

• 英语学习导向的网页转换流程：中文网页先转英文，再做中文辅助，不直接把阅读目标变回中文。
• 词库驱动的 AI 标注：支持“我已经会的词”和“我明确不会的词/词组”两类控制。
• 站点级启停：可以给单个网站加白名单，不需要所有网页都启用。
• 快速控制 + 完整设置分离：Popup 只保留常用开关，复杂配置放在 Options 页面。
• DeepLX 和 AI 分阶段处理：英文页可以直接进入 AI 增强，非英文页先走 DeepLX。
• 可选云同步：支持 GitHub OAuth 登录、JWT 鉴权、CouchDB 持久化。
• Monorepo 工程组织：扩展、后端、共享设置 schema 分开维护。

它是怎么工作的

1. 中文网页

1. Content script 提取页面里的可读文本。
2. DeepLX 把原文转换成英文。
3. AI 根据你的词库、等级和 Prompt，对句子里的陌生词加中文辅助。
4. 扩展把结果写回页面文本节点。

2. 英文网页

1. 跳过 DeepLX。
2. 直接根据词库和 AI 配置，对英文句子做辅助标注。

3. 为什么相对稳

Painless 的页面回写策略不是粗暴替换整块 HTML，而是尽量只更新文本节点内容。
对动态网站来说，这种方式通常比直接改 DOM 结构更稳，也更不容易把原站点交互搞坏。

3 分钟上手

环境要求

• Node.js >= 20.10.0
• pnpm >= 10.12.1
• Chrome / Edge（需要支持 Manifest V3）

1. 安装依赖

pnpm install

2. 准备本地环境变量（推荐）

如果你希望本地构建时自动带上默认模型 / DeepLX 配置，可以先复制：

copy apps\extension\.env.example apps\extension\.env.local

然后按需修改：

• VITE_API_BASE_URL：云同步后端地址
• VITE_DEFAULT_MODEL_CONFIGS_JSON：本地默认模型配置
• VITE_DEFAULT_DEEPLX_CONFIGS_JSON：本地默认 DeepLX 配置

这两个默认配置只会在你本地构建扩展时注入；仓库源码不会再保存真实 key。

3. 构建扩展

推荐用这一组命令，构建结果更可控，而且不会自动改源码：

pnpm --filter @painless/shared build
pnpm --filter @painless/extension build:ui
pnpm --filter @painless/extension build:content
pnpm --filter @painless/extension verify:dist

4. 加载到浏览器

1. 打开 chrome://extensions
2. 开启“开发者模式”
3. 点击“加载已解压的扩展程序”
4. 选择 apps/extension/dist/

5. 首次配置

先打开扩展的 Options 页面，然后按下面的顺序配：

1. 通用
   • 开启扩展
   • 选择你的英语水平
   • 配置“运行网站”
   • 仓库默认白名单比较保守，第一次体验建议填你的目标网站，或者直接改成 *
2. DeepLX
   • 如果你要处理中文网页，这一步是必须的
   • 配置可用的 DeepLX endpoint 和 API Key
3. 模型
   • 如果你想让陌生词自动补中文提示，再配置 AI 模型
   • 当前走 OpenAI 风格接口，支持多个模型轮询/容灾
4. 词库
   • 把你已会的词、不会的词补进去
   • 这样 AI 更容易做到“只提示你真正需要的部分”

6. 开始使用

• 通过 Popup 快速启停扩展或给当前网站加白名单
• 在设置页里调整等级、词库、模型和替换样式
• 默认快捷键是 Alt+W，用于切换当前页面的翻译/还原

首次使用建议

• 想处理中文网页：至少先把 DeepLX 配好。
• 想处理英文网页里的陌生词：优先把词库和 AI 模型配好。
• 如果发现某个网站没有生效，先检查“运行网站”规则，而不是先怀疑扩展坏了。
• chrome://*、Chrome Web Store 这类页面属于浏览器受限页面，扩展本身就不能注入。

可选：启用云同步

云同步不是公共 SaaS，而是一个“你可以自己跑起来”的后端能力。
如果你只想本地使用扩展，这一节可以跳过。

云同步提供什么

• GitHub 登录
• 本地 settings 推送到云端
• 云端 settings 拉回本地
• 基于 updatedAt 的冲突检测和覆盖策略

最短配置步骤

1. 复制后端环境变量模板

copy apps\server\.env.example apps\server\.env.local

2. 配好以下信息

• JWT_SECRET
• GITHUB_CLIENT_ID
• GITHUB_CLIENT_SECRET
• GITHUB_REDIRECT_URI
• COUCHDB_URL
• COUCHDB_USERNAME
• COUCHDB_PASSWORD
• COUCHDB_DATABASE

3. 启动后端

pnpm --filter @painless/server dev

4. 健康检查

打开 http://localhost:3001/health，返回 { "ok": true } 就说明后端起来了。

5. 告诉扩展后端地址

在 apps/extension/.env.local 写入：

VITE_API_BASE_URL=http://localhost:3001

然后重新执行：

pnpm --filter @painless/extension build:ui

6. 在扩展里完成登录

• 打开 Options -> 云同步
• 点击“开始 GitHub 登录”
• 登录成功后即可推送、拉取或一键同步

更完整的说明见 docs/server/BACKEND_SYNC.md。

项目结构

Painless/
├─ apps/
│  ├─ extension/   # Chrome 扩展（MV3 + React + Vite）
│  └─ server/      # 云同步后端（Express + GitHub OAuth + CouchDB）
├─ packages/
│  └─ shared/      # 前后端共享的 Settings 类型、默认值、normalize
├─ docs/           # 工作流、架构、后端同步、manifest 等文档
└─ img/            # README 使用的真实运行截图

开发者入口

如果你不仅是用户，还想继续开发或二次定制，推荐从下面这些文档开始：

• docs/WORKFLOW.md：怎么跑、怎么构建、怎么调试
• docs/ARCHITECTURE.md：系统分层和数据流
• docs/server/BACKEND_SYNC.md：GitHub 登录和 CouchDB 同步
• docs/INDEX.md：完整文档索引

当前状态

项目目前仍处于 MVP 阶段，但核心链路已经具备：

• Chrome 扩展可本地加载并运行
• DeepLX + AI 双阶段文本增强已落地
• Settings 单一事实来源与 normalize 已落地
• 云同步 MVP 已跑通

如果你准备把它作为公开产品继续推进，建议优先补齐：

• 表单校验与错误提示
• 更细粒度的性能预算
• 云同步的生产化安全项（HTTPS、CORS 白名单、refresh token、限流、审计）

一句话总结

Painless 适合这样的用户：
你不想把网页“翻译完就关掉”，而是想把网页持续变成可读、可学、可调的英语输入材料。