- 创建时间: 2026-07-11 13:10:00
- 更新时间: 2026-07-24 11:15:34
- 时区: Asia/Shanghai
个人自用的英文精读平台。把英文文献 / 推文 / 网页文章变成左英右中双栏对照来读，随时划词查词 + 读音，并可向内置的语言导师 agent 追问惯用表达的地道含义与类比例句。
本机 localhost 单用户运行，无鉴权，数据全部自持（SQLite 单文件）。 隐私级别 private。
 文库首页——已粘贴文档的阅读进度一览 |
 双栏段级对照阅读（暗色主题） |
 划词：ECDICT 词典义 + LLM 本句语境义 |
 语言导师：含义 / 为什么 / 中文类比 / 例句 |
 网页设置：按角色配置模型、思考强度、密钥 |
 浏览器插件：任意网页就地划词（Wikipedia 示例） |
 插件侧边栏：语言导师随页可用 |
| 界面 | 场景 | 入口 |
|---|---|---|
网页版（frontend/） |
把长文粘进来深读（论文、推文 thread） | http://localhost:5173 |
浏览器插件（extension/，MV3 Chrome/Edge） |
浏览时就地帮读任意英文网页：划词浮层 + 导师侧栏（整篇双栏精读为 P2） | chrome://extensions 加载已解压 |
两者共用同一个本机后端（FastAPI + SQLite + ECDICT 词典 + LLM 导师），各司其职、数据互通。插件是「瘦客户端」，重活全在后端。设计单一真相源：平台见 docs/plan.md，插件见 docs/extension/plan.md。
- 粘贴 → 清洗（网页版）：确定性规则管线修复 PDF 复制的断字 / 假换行 / 页眉页脚 / 引用编号（文献、推文两种模式）；清洗预览可视化段落边界，可手动拆 / 并段；原始粘贴文本永久保留。
- 双栏段级对照：文档以段落块（block）为原子单位，左右按块配对渲染，天然对齐；全文预翻、逐段渐进渲染；公式 / 代码 / 引用编号占位符保护不被翻译破坏。对齐粒度 = 段级（有意边界，句级不做）。
- 划词翻译 + 读音：本地 ECDICT 词典毫秒级第一屏（释义 + IPA 音标 + 词形还原），LLM 携带所在整句异步补「在本句语境中的含义」；speechSynthesis 发音（美 / 英音）。插件划词浮层粘性（滚动 / 拖拽 / 失焦都不丢，只在点空白 / Esc / ✕ 时关）且可拖动。
- 语言导师 agent：划词直达侧栏；网页版自动携带选中文本 + 所在段对 + 前后文，插件未建档页面携带选区并使用持久化全局线程支持多轮追问；固定输出「直译 vs 地道含义 → 母语者为什么这么用 → 中文类比 → 可迁移例句」；流式回答、可 Esc / ⏹ 中止、支持「新对话」清空。
- 网页版只收纯文本粘贴（不做 PDF 上传 / OCR）；插件覆盖「浏览时就地读网页」。
- 语言方向锁 EN→ZH；单用户、无鉴权（本机）；不自建背单词 / SRS（生词可导出）；对齐粒度段级。
- 明确不做：整篇朗读、虚拟滚动、云 TTS、PWA、多用户、上架商店。
全部仅本机、无公网。主力机 MacBook-M4。
| 组件 | 地址 | 进程 / 入口 |
|---|---|---|
| 后端 FastAPI | http://127.0.0.1:8730（仅本机） |
conda env jingdu；backend（app/main.py） |
| 网页版前端 (dev) | http://localhost:5173（仅本机） |
Vite dev server；.../language-Tian/frontend |
| 浏览器插件 | chrome-extension://<ID> |
unpacked 加载；产物 .../language-Tian/extension/.output/chrome-mv3 |
| 数据库 | — | .../language-Tian/data/jingdu.db（SQLite，user_version 顺序迁移，启动前 .backup 快照） |
| 词典 | — | .../language-Tian/data/ecdict.db（ECDICT，gitignored，首启自动下载） |
- 后端
backend/：Python FastAPI（conda envjingdu）+ SQLite（data/jingdu.db，user_version顺序迁移）。 - 网页版
frontend/：React + Vite（frontend-reactbits 设计系统，暗色默认 + 亮色覆盖双主题）。 - 共享层
shared/（npm 包@jingdu/shared）：网页版、浏览器插件与 macOS 桌面端复用的组件 / 传输层 / 主题 / i18n，单一真相源。 - 插件
extension/：WXT（MV3，Chrome/Edge），内容脚本 Shadow-DOM 隔离 + service worker 后端代理 + 侧边栏 + 设置页。 - LLM：llm-protocol-router（从 GitHub 安装，未上架 PyPI）双协议接入——代码只引角色名
fast（批量翻译 / 划词 / 标题）、translate（快捷翻译模型兜底）与reasoning（导师）。模型和运行参数只在backend/models.yaml，禁硬编码。 - 词典：ECDICT 本地离线（340 万词条 + 词形反查）。
./start-tian.sh自检 conda 环境 / 依赖 / 词典 → 起后端（:8730）+ 前端 dev（:5173）→ 输出核验结果。可安全重跑（幂等，先停旧进程再起）。
./start-tian.sh # 先起后端（插件依赖它）
npm run build -w extension # 产物 extension/.output/chrome-mv3chrome://extensions → 开「开发者模式」→「加载已解压」→ 选 extension/.output/chrome-mv3。更新 = 重新 build + 在该页点「重新加载」。详见 extension/README.md。
密钥、端点、各角色模型、思考强度、最大输出与温度都能在网页和 macOS 桌面控制面板的「模型与 API」中配置；保存即生效，无需重启后端。
- 密钥落
backend/.env（gitignored、chmod 600、永不入库）；模型 / provider 映射在backend/models.yaml。 - 也可手动编辑，模板见
backend/.env.example（含 OpenAI 兼容fast+ Anthropicreasoning+ 备选 provider 注释）。 - 凭据获取：OpenAI / Anthropic 等官方控制台申请，或指向自有网关；端点可自填。
language-Tian/
package.json workspace 根（jingdu-workspace；workspaces: shared / frontend / extension）
start-tian.sh 一键启动（后端 + 网页版 dev）
backend/ FastAPI 应用
app/main.py 入口；app/routers/ 各端点；app/migrations/ 数据库迁移(*.sql)
models.yaml 角色→模型与参数（fast / translate / reasoning）
.env API key（gitignored）；.env.example 为模板
frontend/ 网页版 SPA（React + Vite）；消费 @jingdu/shared
shared/ 跨表面共享层 @jingdu/shared
components/{MarkdownLite,TutorSidebar} lib/{api,cn,speech}
i18n/ theme/ThemeProvider styles/tokens.css tailwind-preset.js
extension/ 浏览器插件（WXT, MV3）；产物 .output/chrome-mv3（gitignored）
entrypoints/{background.js, content.jsx, sidepanel/, options/, style.css}
components/{ContentApp,LookupPopup} lib/{messaging,selection} wxt.config.ts
data/ SQLite 数据库 + ECDICT 词典（均 gitignored）
docs/ 设计与决策文档（plan.md 平台 / extension/plan.md 插件）
LESSONS.md 否决 / 删除设计的教训
CLAUDE.md / AGENTS.md 项目级 agent 规则
| 文档 | 内容 |
|---|---|
docs/plan.md |
网页平台实现计划与需求定稿（单一真相源） |
docs/extension/plan.md |
浏览器插件架构设计与分阶段落地（P0/P1 已落地，P2 整篇精读待做） |
extension/README.md |
插件开发 / 构建 / 加载说明 + 网络铁律 |
backend/.env.example |
LLM 密钥 / 端点配置模板 |
LESSONS.md |
设计教训（否决过什么、为什么） |