# Etymology-Rag

**Repository Path**: williamsucas/etymology-rag

## Basic Information

- **Project Name**: Etymology-Rag
- **Description**: Etymology Intelligent RAG Project - English Vocabulary Knowledge Graph Visualization System
词源智能RAG项目 - 英语词汇知识图谱可视化系统 英
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: feature/morphology-databases
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-11
- **Last Updated**: 2026-11-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 玩转英语词汇, 智能体, AI

## README

# EtymologyRAG · 词源智能 RAG

**输入一个英文单词，把它的词源链、同源词族、语义关系、搭配与真实语料一起摊开。**
后端是一个只读的 SQLite 词库 + Flask API，前端是一份不需要构建的静态页面。

> 当前版本：**V11.121**（`frontend/vue_latest/js/app.js` 里的 `APP_VERSION` 是唯一版本源）
> 许可：**AGPL-3.0-or-later** —— 见 [LICENSE](LICENSE)
> 🧊 **已冻结（2026-10-24）**：自 V11.121 起不再开发。这份是桌面主项目代码；后续要做安卓版时另立工程，不改这里的任何一行。

| | |
|---|---|
| 词条 | 2,380,743 行（`words`） |
| 语义关系 | 4,940,254 条（`relations`）+ 5,156,540 条分类（`relation_categories`） |
| 主库体积 | 4.32 GiB（`data/unified_db/vocabulary.db`） |
| 后端 | Python 3 + Flask（37 个 `.py`（含 `ai/` 包 3 个）/ 31 个路由） |
| 前端 | 23 个 `window.createXxxModule` 模块 + `app.js` + `api.js` / `constants.js` / `utils.js`，**无打包器** |
| 前端依赖 | Vue **3.5.44** / Cytoscape **3.28.1**，**本地固定副本**（`frontend/vue_latest/vendor/`）—— 断网可用 |
| 守卫脚本 | 43 个 `tests/check_*.py` + 3 个 `tests/check_*.js`（无头 `vm` 门）+ 8 个 `tests/test_*.py` + 1 个无头前端 harness |
| 交付加密 | 九个只读库可用 SQLCipher 页级加密（`build/windows/encrypt_data.py`），密钥**不在仓库** |

---

## 1. 运行环境

| 项 | 要求 |
|---|---|
| 操作系统 | Windows 10 1809+ / 11 x64（打包目标）；Linux / macOS 源码可跑，未做安装包 |
| Python | **3.10+**；开发与打包实测 **3.12.10 x64** |
| 依赖 | 见 `requirements.txt`（Flask / flask-cors / requests / networkx） |
| 词库 | **不在仓库里**，见第 2 节 |

```bat
python -m venv venv
venv\Scripts\python.exe -m pip install -r requirements.txt
```

> `requirements.txt` 只列**运行时**依赖。`data_processing/` 下重建词库需要
> `nltk` / `wiktextract` / `lupa` / `joblib` 等重包，**不建议**装进同一个 venv
> —— PyInstaller 会把它们一起拖进安装包（`.spec` 里已列进 `excludes`）。

---

## 2. 词库：这是跑起来的前提

仓库**只放代码**，不放数据。`data/` 已被 `.gitignore` 忽略，主库一个文件就 4.32 GiB。

```
data\
├─ unified_db\vocabulary.db    主库（4.32 GiB，词条 / 关系 / 义项标签）
├─ ecdict.db                   英汉词典（74.8 MB）
├─ collocations.db             搭配与语料统计（145 MB）
├─ word_family.db              词族与词频（81.2 MB）
├─ oewn.db                     Open English WordNet（41.8 MB）
├─ wordfreq.db                 词频排序（9.6 MB）
├─ cmudict.db                  美式音标（5.2 MB）
├─ polarity.db                 情感极性（1.8 MB）
└─ degree_scale.db             程度量级（84 KB）
```

三条取数据的路：

1. **拿现成的词库包**（推荐）：项目的 Release 里提供 `EtymologyRAG-Data-*.exe`
   （Inno 安装包，**2026.11 版实测 833 MiB**，装的是 9 个库、不是整棵 `data\`）。
   它**默认装到 `%LOCALAPPDATA%\EtymologyRAG\data`** —— 便携版（exe 旁边）、
   Inno 版、MSIX 版三条路都从这个位置读库，所以先装程序还是先装词库都可以。
   例外：如果程序是用 Inno 包**装到自定义目录**的（比如为了省 C 盘选 `D:\RAG`），
   词库包会跟随过去，装成 `<程序目录>\data`（`launcher` 的候选第 1 条）；
   老位置已有词库时**不会搬**，避免一份 4.57 GB 变两份。
   手动版也行：把这 9 个库按同样结构拷到那个目录即可。
2. **自己重建**：`data_processing/` 下的脚本 + 原始语料（Brown / OANC / ECDICT /
   Open English WordNet 等，见 `docs/EXTERNAL_DATA_SOURCES.md`）。**需要几十 GB 磁盘
   与数小时算力**，普通使用者不要走这条。
3. **只跑前端看界面**：没有词库时服务会以 503 回应查询接口，但页面本身能打开。

> 程序如何找到词库：`launcher.py` 按 **① exe 旁边的 `data\` → ② `%LOCALAPPDATA%\EtymologyRAG\data`
> → ③ `%LOCALAPPDATA%\Programs\EtymologyRAG\data`（老路径）** 依次探测，谁有主库接谁；
> `--data-dir` / `ETYMOLOGY_DATA_DIR` 仍然优先。`--selftest` 会打出 `data_source` 与
> `data_candidates` 两行，回答「我词库到底装哪了」。
> 装了词库包的话，`data\DATA_VERSION.json` 记着 9 个库的字节数与 sha256 ——
> 报障时先看它（`make_data_version.py --check` 可核对有没有被换过）。

> ⚠️ **`data\vocab_user.db` 与 `data\translation_tm.db` 是「用户可写数据」**
> （单词本、翻译记忆）。程序运行时会自动接管到 `%LOCALAPPDATA%\EtymologyRAG`。
> 发布词库时**绝不能**把它们打进去 —— 那等于把自己的单词本发给所有用户。

### 词库可以是密文（V11.83 起）

交付层的九个只读库可以选择用 **SQLCipher 页级加密**（`build/windows/encrypt_data.py`）。
程序**按文件头判**，不看配置：头 16 字节是 `SQLite format 3\0` 就是明文，否则走 sqlcipher3。
所以明文库与密文库可以同时存在，同一个 exe 都能读。

密文库需要一把密钥，三级查找（**顺序固定**）：
`ETYMOLOGY_DB_KEY` 环境变量 → 程序目录的 `dbkey.hex`（打包版在 `_internal\`）→
用户目录 `%LOCALAPPDATA%\EtymologyRAG\dbkey.hex`。密钥本身**永远不进仓库**
（`.gitignore` 已挡 `dbkey.hex` / `build/private/`），丢了就只能重新发一份词库。

排障看 `--selftest` 的三行：`db_kind`（plain / encrypted）/ `db_key`（present + 来源）/
`db_driver`（sqlite3 / sqlcipher3）。细节见 `docs/DB_ENCRYPTION.md`。

---

## 3. 从源码直接运行

```bat
:: ① 常规启动（需要显式给 --db 与 --port）
venv\Scripts\python.exe web_service\web_api.py --db data\unified_db\vocabulary.db --port 5099

:: ② 桌面入口（推荐）：自动把 data\ 接到词库、自动挑空闲端口、就绪后开浏览器
venv\Scripts\python.exe web_service\launcher.py

:: ③ 自检：打印四根路径出口 + 主库是否可读（打包后排查"数据到底在哪"）
venv\Scripts\python.exe web_service\launcher.py --selftest
```

浏览器打开 <http://127.0.0.1:5099/> 即可。

页面**不依赖外网**：Vue 与 Cytoscape 是仓库里的固定副本（`frontend/vue_latest/vendor/`），
断网、CDN 被墙、公司防火墙拦 CDN 都能打开。**不要再往 `index.html` 里加 `http(s)://` 的
`<script src>`** —— 守卫 `tests/check_offline_assets.py` §1 会立刻红（V11.80 修的就是这个：
断网整站白屏，而无头测试全都照不出来，因为它们根本不加载那两个文件）。

`launcher.py` 支持的开关：

| 开关 | 作用 |
|---|---|
| `--port 5100` | 指定端口（默认从 5099 起扫到 5199，**已被自己占用就直接开浏览器**，不启动第二份） |
| `--no-browser` | 起服务但不开浏览器 |
| `--data-dir D:\x` | 临时改用别的词库目录（覆盖程序旁的 `data\`） |
| `--selftest` | 只打印路径、主库状态、词库完整性后退出（售后第一步） |
| `--selftest --deep` | 再多算一遍 9 个库的 sha256（4.56 GB 约 96 秒），验内容而不只是字节数 |

### AI 三种模式（V11.78 起）

```bat
--ai off       一个模型都不调用（默认；查词/搭配/词源全部照常，只是没有 AI 分析）
--ai local     本地 Ollama（默认 http://127.0.0.1:11434，推荐 qwen2.5）
--ai online    OpenAI 兼容服务（DeepSeek / 通义 / Kimi / 智谱 / OpenAI …）
--ai auto      有本地用本地，没有则用在线，都没有就降级为 off（并在响应里说明原因）
```

在线模式的 **API Key 只从服务端配置读**，三条来源优先级从低到高：
`ai.json`（用户目录）→ 环境变量 → 命令行。**代码里没有任何硬编码 Key**，
前端也拿不到 Key（`/api/ai/status` 只回 `key_set: true/false`，连长度都不给）。
界面上改配置走「AI 设置」按钮，只调本地后端接口。

---

## 4. Windows 打包

产物形态：**onedir**（不追 onefile —— 每次启动解压 4.9 GB 会让用户以为程序没反应）。

```bat
:: ① 装打包工具（进同一个 venv，不要 -g）
venv\Scripts\python.exe -m pip install pyinstaller

:: ② 打包（在仓库根目录执行；引导使用项目内的 .spec，不要手敲一堆 --add-data）
venv\Scripts\python.exe -m PyInstaller --noconfirm --clean ^
    --distpath build\windows\_out ^
    --workpath build\windows\_work ^
    build\windows\etymology_rag.spec

:: ③ 验一下打包版把数据认在哪（这条是"打包成功但打不开"的照妖镜）
build\windows\_out\EtymologyRAG\EtymologyRAG.exe --selftest
```

产物结构：

```
build\windows\_out\EtymologyRAG\
├─ EtymologyRAG.exe        ← 引导器（无控制台，版本号来自 app.js 的 APP_VERSION）
└─ _internal\              ← Python 运行时 + Flask + 前端 + rules（20 MB / 110 个文件）
```

**词库不在这里面**。程序启动时把 `ETYMOLOGY_DATA_DIR` 指向 `<exe目录>\data`，
所以词库要单独放到 `EtymologyRAG.exe` 旁边的 `data\`（见第 5 节的词库包）。
这样做的好处是：**换库不用重打 exe，换程序不用重下 4.9 GB**。

`_internal\frontend\vue_latest\vendor\` 里带着 Vue / Cytoscape 的固定副本 ——
**打包版断网也能打开**（V11.80 之前这两行从 unpkg 引，断网就是整站白屏）。

`--selftest` 正常输出（打包版）：

```
frozen                     True
resource_root              ...\EtymologyRAG\_internal
data_root                  ...\EtymologyRAG\data            ← 必须在 _internal 之外
main_db_exists             True
DATA_DIR_OK                OK
```

> 想让打包版临时读仓库里的词库（调试用，不必拷 4.9 GB）：
> `set ETYMOLOGY_DATA_DIR=F:\path\to\repo\data` 再启动 exe。

---

## 5. 安装包制作（Inno Setup 6）

需要 [Inno Setup 6](https://jrsoftware.org/isdl.php)（约 5 MB）。
两个安装包，**先程序、后词库**：

```bat
:: 装给"所有用户"时在 Program Files (x86)，选"仅为我安装"时在 %LOCALAPPDATA%\Programs
:: （本机实测是后者；上面那条报"不是内部或外部命令"，就换下面这条）
set ISCC="%ProgramFiles(x86)%\Inno Setup 6\ISCC.exe"
:: set ISCC="%LOCALAPPDATA%\Programs\Inno Setup 6\ISCC.exe"

:: ① 程序包（11.85 实测 16.6 MB）：exe + _internal，装到 %LOCALAPPDATA%\Programs\EtymologyRAG
%ISCC% build\windows\etymology_rag.iss

:: ② 词库包（2026.11 实测 833 MiB / 575.5 s，编译约 10 分钟）：9 个库装到 %LOCALAPPDATA%\EtymologyRAG\data
::    编译前先跑一次清单脚本（约 100 秒，4.56 GB 要算 sha256），否则包里没有 DATA_VERSION.json
python build\windows\make_data_version.py
%ISCC% build\windows\etymology_rag_data.iss
```

产物都在 `build\windows\_out\installer\`：

```
EtymologyRAG-Setup-<APP_VERSION>.exe
EtymologyRAG-Data-<数据版本>.exe
```

两个 `.iss` 里已经处理好的事（改动前请读 `docs/WINDOWS_PACKAGING_PLAN.md`）：

| 事 | 怎么做的 |
|---|---|
| 不要管理员权限 | `PrivilegesRequired=lowest`，装 `%LOCALAPPDATA%\Programs`（可写数据本来就在 `%LOCALAPPDATA%\EtymologyRAG`） |
| 词库不进程序包 | 程序包 `[Files]` 带 `Excludes: "data\*"`；词库包按**白名单**列 9 个 `.db` |
| 卸载不误删词库 | 程序包不写通配 `{app}` 的 `[UninstallDelete]`；词库包卸载时**询问**后再删，且只删 `{app}\data` |
| 两条渠道同一份词库 | 词库包**固定**装到 `%LOCALAPPDATA%\EtymologyRAG\data`（= `launcher` 候选表第 2 条），Inno 版 / MSIX 版 / 便携版都从这读 |
| 安装顺序 | 不检查程序是否已装：先装程序还是先装词库都成立。以前「查注册表找程序目录」那套会把 MSIX 用户直接拒掉 |
| 4 GB 单文件上限 | 拆成两个包（16.6 MB + 831 MiB），两个都远低于上限；真超了再加 `DiskSpanning` |
| 用户装的是哪版库 | `make_data_version.py` 写 `data\DATA_VERSION.json`（9 个库的字节数 + sha256），进词库包；`--check` 可核对有没有被换过 |
| 词库要不要加密 | `python build\windows\encrypt_data.py --genkey` 生成 `build\private\dbkey.hex`（**先备份**），再 `--encrypt data`（4.53 GB ≈ 145 s）；产物进词库包，`dbkey.hex` 随程序包落到 `_internal\` |

**没有代码签名证书**，所以首次运行会被 SmartScreen 拦一次
（"更多信息 → 仍要运行"）。这是现实，不是 bug。

### 5.1 另一个选择：MSIX（V11.85 起，**必须签名**）

```bat
:: 本机验证：自签证书（需管理员装一次公钥到「受信任人」）
venv\Scripts\python.exe build\windows\make_msix.py --dev-cert

:: 正式分发：真证书 + 时间戳
venv\Scripts\python.exe build\windows\make_msix.py --pfx cert.pfx --pfx-password *** --timestamp http://timestamp.digicert.com
```

两个内容变体（V11.91 起）：

| 命令 | 产物 | 体积 | 词库在哪 |
|---|---|---|---|
| `--dev-cert` | `EtymologyRAG_<ver>_x64.msix` | **18.7 MiB** | 另装（`%LOCALAPPDATA%\EtymologyRAG\data`） |
| `--dev-cert --with-data` | `..._x64-withdata.msix` | **891.6 MiB** | **在包内**（`<程序目录>\data`，卸载跟着走） |

MSIX 与 Inno 的取舍只有一条：**包绑签名**——`Publisher` 与证书 `Subject` 必须逐字符相同，
改一个字节签名就失效，所以「改个名当成自己的」这条路被堵住。代价是安装目录
`C:\Program Files\WindowsApps` **只读**、且**必须签名才能装**（旁加载也一样）。
词库进不进包是这个只读目录逼出来的取舍：进包则开箱即用、卸载干净，代价是词库每变一次
要重发整个包（商店渠道**只用这一种**，见 `docs/MSIX_PACKAGING.md` §9.6）；
不进包则换库不用重下 900 MB。两种情况都由 `launcher.data_candidates()` 按候选探测
（`<exe 旁>\data` → `%LOCALAPPDATA%\EtymologyRAG\data` → 老路径，有
`unified_db\vocabulary.db` 才算数）。

用户视角的安装步骤见 [`docs/INSTALL_AND_USAGE.md`](docs/INSTALL_AND_USAGE.md)；
**没碰过命令行的人**看 [`docs/MSIX_INSTALL_WALKTHROUGH.md`](docs/MSIX_INSTALL_WALKTHROUGH.md)
（假设你连命令行都没开过：以"包在 `D:\RAG`"为例，先讲路径/终端/证书三个词，
再给**两条双击路线**和**两句命令**，每句逐字拆、每条报错按原话查）；
安装/卸载脚本与九个踩过的坑见 `docs/MSIX_PACKAGING.md`。

上架材料：[`docs/store/STORE_LISTING.md`](docs/store/STORE_LISTING.md)（商店文案，中英双语）·
[`docs/PRIVACY.md`](docs/PRIVACY.md)（隐私政策，英文版 `PRIVACY.en.md`）·
[`docs/DISCLAIMER.md`](docs/DISCLAIMER.md)（首启免责声明弹窗文案）。
⚠️ 隐私政策里的联系邮箱还是占位符，**提交商店前必须填真实地址**。

---

## 6. 目录结构

```
etymology-rag\
├─ web_service\              Flask API（37 个 .py / 31 个路由）
│  ├─ web_api.py             主服务与全部路由
│  ├─ launcher.py            桌面入口（打包后的 exe 就是它）
│  ├─ _stream_shim.py        windowed 下 stdout/stderr 为 None 的兜底
│  ├─ paths.py               全工程**唯一**允许读 __file__ 的地方（路径四根出口）
│  └─ ai\                    三种 AI 模式的 provider 抽象（V11.78）
├─ frontend\vue_latest\      静态前端（Vue 3，无构建、无 npm）
│  └─ vendor\                Vue / Cytoscape 的**本地固定副本**（离线可用；版本与 sha256 见 MANIFEST.json）
├─ data\                     词库（**不进仓库**，见第 2 节）
├─ data_processing\          建库脚本（需要原始语料，普通使用者不需要）
├─ morpheme_processing\      词素切分
├─ rules\                    词素变体规则（只读资源）
├─ build\windows\            .spec / .iss / app.ico / make_msix.py + msix\（第 4、5 节用）
├─ tests\                    44 个 check_*.py + 3 个 check_*.js + 8 个 test_*.py + 无头前端 harness
└─ docs\                     架构、版本历史、交接板、数据源说明
```

关键约定（改代码前值得知道）：

- **前端没有打包器**：每个模块是 `window.createXxxModule(ctx)`，由 `app.js` 调度，
  模块之间不互相 import；`<script>` 顺序 = 依赖顺序（错一个就白屏）。
- **`data_root()` 是唯一的数据入口**：`web_service/**` 里没有任何一处自己拼 `data` 路径。
- **主库只读**：一律走 `db_guard.connect_ro()`，`vocabulary.db` 永远不写。

---

## 7. 开发与测试

```bat
:: 路径铁律 / 启动闸门 / AI 三模式 / 翻译账本 …（每套都能单独跑）
venv\Scripts\python.exe tests\check_paths.py
venv\Scripts\python.exe tests\check_startup_guards.py
venv\Scripts\python.exe tests\check_ai_modes.py

:: 前端必须离线自足（0 外链 + vendor 哈希 + 加载顺序），打包之前一定要绿
venv\Scripts\python.exe tests\check_offline_assets.py
venv\Scripts\python.exe tests\check_version_sync.py

:: 契约测试
venv\Scripts\python.exe tests\test_translate_contract.py

:: 无头前端回归（需要 Node 18+；23 个模块 / 31 个路由的接口面全过一遍）
node tests\verify_frontend_headless.js
```

守卫的写法有一条硬规矩：**每套守卫都要配「假绿检验」** ——
把被测代码改坏，守卫必须变红；改不红就说明断言是恒真的，等于没写。
`tests/_falsify_v11xx.py` 就是这个用途。

---

## 8. 许可

本项目以 **GNU Affero General Public License v3.0 or later（AGPL-3.0-or-later）** 发布，
全文见 [LICENSE](LICENSE)。

简单说：你可以自由使用、修改、再分发；但**如果你把它改成网络服务对外提供**，
你必须把修改后的源码一并开放。分发二进制时也要附上许可与源码获取方式。

> **不熟悉命令行构建的普通用户，建议前往微软商店购买一键安装版。**

词库中引用的第三方数据（ECDICT、Open English WordNet、CMUdict、Brown / OANC 语料等）
各自遵循其原始许可，详见 `docs/EXTERNAL_DATA_SOURCES.md`。