专为德语学习者与歌德（A1–C1）/ 德福（TestDaF）/ DSH 备考打造的学术级伴读与句法剖析系统。
一键拆解拓扑五场域（VF/LK/MF/RK/NF）与 AST 从句语法树，内置歌德 A1 全真考场与 FSRS 记忆排程。
普通用户（免装 Python，开箱即用）：
开发者 / 源码运行：
uv venv --python 3.11 # 创建项目级 .venv（依赖不再装进全局解释器）
uv pip install -r requirements.lock.txt # 按锁定清单安装依赖（含桌面壳依赖）
uv run --no-project python -m spacy download de_core_news_sm # 德语 NLP 模型（唯一档位；缺省自动下载 sm）
uv run --no-project python start.py # 一键启动并自动打开浏览器 http://localhost:8000
uv run --no-project python desktop.py # Windows 桌面壳（原生窗口 + 托盘 + 启动 splash）
docker compose up -d --build # 或 Docker 容器化一键部署开发者首次启用提交前密钥扫描（每个克隆都要做一次）：
git config core.hooksPath .githooksWindows 分支 / Docker 细节 / 环境变量 / 打包 / 安全守卫等完整说明见 docs/agents/ops.md。
v5.23.4 最新版本亮点（2026-11-11）：
- 桌面版导出不再「假成功」：以前点导出会弹「已导出」但磁盘上没有文件（WebView2 默认不放行下载、请求被静默取消）。现在由 Python 显式落盘并回传真实路径与字节数，只有真正写成功才提示成功。
- 修复依赖锁文件装不上的问题：
requirements.lock.txt里 numpy 被升到只支持 Python 3.12 的版本、pydantic-core 与 pydantic 精确版本冲突；已回退到与 Python 3.11 兼容的组合。- 依赖批量升级：fastapi 0.162.2、click 8.5.1、typer 0.28.0、typing-inspection 0.4.5，CI 缓存动作升到 v6。
- v5.23.3 的阅读页修复仍在本版（阅读页状态模板、Android 退出重进自动补载）；若你装了 v5.23.1 / v5.23.2，请直接升级本版。
Android 用户注意：含
static/改动的版本需覆盖安装才生效。 完整版本变更细节见 CHANGELOG.md。
| 平台 | 版本 | 说明 | 下载通道 |
|---|---|---|---|
| Windows x64 | v5.23.4 |
原生桌面窗口 + 系统托盘，免装 Python，解压双击 DeLector.exe；需 Win10+ 与 WebView2 运行时（Win11 自带；Win10 缺运行时的表现见已知限制）；首次启动把数据放到 %LOCALAPPDATA%\DeLector |
下载 ZIP 包 (GitHub Releases) |
| macOS | v5.23.4 |
解压后进入 DeLector-v5.23.4-macOS/，运行其中的裸可执行文件 ./DeLector（不是 .app 包）。正常 tar -xzf 解压会保留可执行位，若权限丢失先 chmod +x DeLector。包未做代码签名与公证，若被 Gatekeeper 拦截请右键「打开」，或在终端执行 xattr -d com.apple.quarantine DeLector。 |
下载 TAR.GZ 包 (GitHub Releases) |
| Linux x64 | v5.23.4 |
解压后进入 DeLector-v5.23.4-Linux-x64/，运行 ./DeLector（正常 tar -xzf 解压会保留可执行位，若权限丢失先 chmod +x DeLector）。包在 CI 的 Ubuntu 环境构建，未在其他发行版验证。 |
下载 TAR.GZ 包 (GitHub Releases) |
| Android | v5.23.4 |
内嵌 Python 运行时与 spaCy 离线模型，单机独立运行；正式包只出 arm64-v8a，CI 用 keytool 校验 APK 与 keystore 的 SHA256 证书指纹一致。arm64 真机未验证（仅 x86_64 模拟器）。 |
下载 APK 安装包 (GitHub Releases) |
| 需要什么 | 去哪 |
|---|---|
| 项目状态 / 红线 / 待办 | WORKMEMORY/PROJECT_OVERVIEW.md |
| AI Agent 入口（纯路由） | AGENTS.md |
| 产品特性全览 | FEATURES.md |
| 架构细节（技术栈 / NLP / DB / API / 前端拓扑） | docs/agents/architecture.md |
| 安全守卫 / 本机环境 / 打包 / 工作惯例 | docs/agents/ops.md |
| 设计系统 / 视觉 Token / 组件蓝图 | docs/design-system.md（token 现值以 static/css/tokens.css 为准） |
| 设计与实施计划 | docs/specs/、docs/plans/ |
| 版本历史 | CHANGELOG.md |
| 贡献指南 | CONTRIBUTING.md |
| 行为准则 | CODE_OF_CONDUCT.md |
| 安全策略 | SECURITY.md |
| 架构决策记录（ADR） | docs/adr/ |
- 德语精读工作台：CEFR 词阶热力图 + 歌德离线词库 + 荧光便签、AI 导读与打印级《精读指南》导出。
- 句法拓扑与 AST：经典五场域（VF/LK/MF/RK/NF）色谱条切分 + 5 大从句抽象语法树 + 一键制 Anki 语法卡。
- FSRS 卡盒与背词工作台：3D 拟真翻牌 + FSRS 现代自适应排程（消解 Ease Hell）；A1/A2/B1 多档背词台（
VOKABELN）与介词矩阵视图。 - 备考域 A1–B1：歌德全真听说读写考场工坊（写作 / 听力 / 阅读 / 口语 / 词表）+ 德福 C-Test + 听力微训 / 长难句精读工坊。
- 遇见区分级阅读：i+1 阅读桥 + 逐词注解 + 生词一键进卡，配套桌面→手机局域网 P2P 同步（WebRTC Stage B；真机双端尚未验证）。
- 内联 IDE 写作工坊与伴读宠物：行内实时语法诊断 + VSCode 级 Inlay Hints；Eule 与伙伴混合双模伴读。
完整功能清单见 FEATURES.md。
- 列表成本量到毫秒：文章列表 918 ms → 8.9 ms（约 103×）；同批修复还包括首屏少 383.4 KB。出处：ADR-0022。
- CI 只删重复、不删检查：Ruff/mypy 从六个分片各跑一次收敛为只在
unit-2跑，静态检查累计 92 s → 14 s（-78 s runner 时间）；墙钟未因此下降，所以不拿它宣传「变快」。出处：CI 速度预算 1.3。 - 分片必须真互斥：旧写法
glob + --ignore对显式文件无效，一次 run 重复执行 356 个用例；改为tools/ci_shards.py显式清单后，2026-11-04 本地六分片基线为 2749 passed / 4 skipped（当前总数见顶部徽章），并新增 4 条守卫。出处：CI 速度预算 1.4。 - 模型档位用数据定：111 句真实语料里 md 仅 3/111（约 2.7%） 句判定更合理，体积却是 sm 的 2.82×（21.16 → 59.61 MB），因此只保留 sm。出处：ADR-0027。
- 发版可验证：Android 正式包只出 arm64-v8a，发布前用
keytool校验 APK 与 keystore 的 SHA256 证书指纹一致，不一致即阻断。该指纹校验只在 CI 执行，未在真机上复验。出处：build-release.yml。
用着顺手或别扭，都欢迎说一声：开一条零门槛反馈——不用懂技术、不用建分支、不用写
bug(scope):前缀，三道判断题点一下就行，想吐槽什么随手写（留空也完全 OK）。你的反馈直接决定下一个版本做什么。
| 领域 | 核心技术 | 说明 |
|---|---|---|
| 后端框架 | FastAPI + Uvicorn |
异步高性能 REST API |
| 自然语言处理 | spaCy (de_core_news_sm) |
本地德语分词、词性标注、形态分析与五场域句法依存（唯一档位，ADR-0027） |
| 形态学引擎 | delector/nlp_engine/linguistics.py |
556+ 不规则动词三态表 + 复合词动态规划递归拆解 |
| 拓扑句法树 | delector/nlp_engine/syntax_tree.py |
Vorfeld/LK/MF/RK/NF 五场域切分 + 5 大从句 AST 抽象语法树 |
| 持久化存储 | SQLite 3 (delector.db + progress.db) |
核心文库与时序台账双库解耦存储 |
| 语音合成 | Edge-TTS (Microsoft Neural Voice) |
在线神经语音合成 + 本地缓存；不可用时回落 Web Speech |
| 前端架构 | ES Modules / Modern CSS / Vanilla JS |
零 Node 构建依赖、模块化架构、原生 3D CSS 渲染 |
| 记忆同步 | genanki |
离线生成标准 .apkg 记忆库 |
| 自动化测试 | pytest + httpx |
7 路 pytest 分片（unit-1..4 / integration-heavy / cost-guards / cost-cold-start）跑全量用例；Ruff、mypy、前端契约、模板/样式同步、分层不变量、gitleaks 密钥扫描、Go 格式化/vet/race、Windows 便携包冒烟组成 CI 闸门；Android 构建与签名指纹校验在发布链路执行（NLP 只装 de_core_news_sm） |
桌面端默认把数据放在用户目录、不随程序目录：Windows 为 %LOCALAPPDATA%\DeLector，
macOS / Linux 为 ~/.local/share/DeLector；文件是 delector.db 与 progress.db。两个开关：
DELECTOR_PORTABLE=1⇒ 数据回到程序目录（U 盘 / 多机场景）；DELECTOR_DATA_DIR=<目录>⇒ 显式指定落点（优先级最高）。
首次从「数据随程序目录」的旧版升级时会自动搬一次：新位置复制成功后，旧文件改名为
delector.db.bak-<时间戳>（永不删除，确认无误后可自行清理）。
Docker 部署的数据落在 ./data 目录（DELECTOR_DATA_DIR=/app/data）。挂目录而非单文件，
是因为 WAL 会在库旁生成 -wal/-shm，单文件挂载会在 docker compose down 后丢尾写。
从旧版单文件挂载（./delector.db:/app/delector.db）升级的用户：直接
docker compose up -d --build 会得到一个功能正常但数据全空的应用——旧库还在仓库根，
而容器现在去读 ./data。数据文件没有被删除，只差一次复制：
mkdir -p data && cp delector.db data/delector.db # progress.db 同理为杜绝「静默空库」（空库一旦建出，用户的诊断直觉是「数据丢了」，进而可能做不可逆的
恢复出厂操作），应用启动时会自检：新位置无库 + 旧位置有非空库 ⇒ 拒绝启动，并在日志里
打印两个绝对路径和一条可直接复制的 cp 命令。照做后重启即可。（日志里的 cp 给的是
容器内路径，要在容器里执行，或用 docker compose cp。）
同一条迁移规则对桌面端手工设 DELECTOR_DATA_DIR 同样适用：把 DELECTOR_DATA_DIR
指向一个新目录、而旧位置的 delector.db 还在仓库根时，闸会以同样理由拒绝启动，直到你把
库复制到新目录为止。
DeLector/
├── delector/ # 后端核心包：server.py + core/(DB·安全·版本) + nlp_engine/(spaCy·拓扑·AST) + routes/(领域路由) + services/(LLM·TTS) + tools/ + data/
├── static/ # 前端零构建体系：index.html + layout/ + views/ + modals/ + js/(47 模块) + css/(视觉 tokens)
├── android/ # Android 独立离线单机版工程 (Chaquopy + Gradle；device / emulator 两个 flavor)
├── agent/ # Go Agent Runtime（CLI + DAG + 工具注册）
├── tests/ # 自动化测试套件：194 个 test_*.py + 行为探针与迁移哨兵
├── tools/ # 架构与视觉守卫工具链（契约/分层/同步/静默降级/视觉/工作台闸）+ 构建装配工具
├── docs/ # 仓库文档中枢：agents/(架构·运维) · specs/(设计) · plans/archive/(已归档计划) · adr/ · reviews/
├── WORKMEMORY/ # 共享工作记忆系统：PROJECT_OVERVIEW.md · work.log · PROTOCOL.md
├── start.py # 跨平台智能启动脚本（Android 回环 / 桌面 0.0.0.0）
├── desktop.py # Windows 原生桌面壳（pywebview + 托盘 + splash）
├── package_windows.py # Windows 绿色免安装便携版打包脚本
├── Dockerfile # 容器化构建
├── docker-compose.yml # Compose 编排
└── requirements.txt # Python 依赖清单
逐目录 / 逐模块详情（含 js 模块清单、后端子包分层）见 docs/agents/architecture.md。
本项目遵循语义化版本规范。完整版本历史、发版演进与回滚方案见 CHANGELOG.md。
| 版本 | 发布日期 | 里程碑概要 |
|---|---|---|
| v5.23.4 | 2026-11-11 | 桌面导出改为 Python 显式落盘（不再假成功）· 修复 requirements.lock.txt 不可解（numpy / pydantic-core 与 Python 3.11 冲突）· 依赖批量升级与 CI 缓存动作 v6 |
| v5.23.3 | 2026-11-11 | 修复「点开文章无反应」（阅读页模板引用已删除变量）· 修复 Android 退出重进停在 Webpage not available（就绪后补载一次）· x86_64 模拟器实测通过 |
| v5.23.2 | 2026-11-10 | 修复 v5.23.1 全平台白屏（前端模块图重复导出导致解析期崩溃）· 新增「node 真链接整张模块图」守卫；阅读页不可用，请用 v5.23.4 |
更早的版本（v5.14.0–v5.21.1 等）已完整迁入 CHANGELOG.md，本页只保留最近三版。
- Win10 需先装 WebView2 运行时（Win11 自带）：缺运行时的表现为启动阶段报错退出（历史记录；本版未在 Win10 上复验具体提示文案）。
- 冷启动时间未在 v5.22.0 重测：历史实测（v5.17 时代）源码路径暖启动约 5.4s、便携产物冷启动约 8.5s，其中约 2s 是建服前的端口/身份校验；当前版本的具体数字以本机实测为准，本页不沿用旧值。
launch.log有已知的整行丢失（Windows 上多个句柄并发追加同一文件，历史实测约 3% 的行整行消失、不是半行）：排查启动问题时若日志缺行，先按此排除；tools/first_screen_from_log.py报退出码 3/5（缺锚行）不必然等于日志损坏。- Android 覆盖安装才生效：含
static/改动的版本必须覆盖安装（应用按versionCode判定重解包）。 - Android 端「检查更新」暂未验证：桌面端可用；Android 上两条假设（Chaquopy 能否完成到公网的 HTTPS、WebView 点外链是否交给系统浏览器）尚未在设备上验证，请以本页 / Releases 的版本号为准。
- Android 装不回旧版：
versionCode只升不降，装错版本只能卸载重装（会清应用私有数据，请先导出备份）。 - Android 主路径已统一到 spaCy：按 ADR-0028 删除平台硬编码的纯 Python 降级；模型缺失/加载失败时句法专线硬失败，不返回近似结果。
- 存量文章按需惰性重算（3.6.0 起）：升级前落库的旧结果会在首次打开该篇时按需重算并回写；启动路径不扫全表、不批量重算。重算在单篇 GET 内同步执行，10 万字符上限级文章约 4–5s，期间只有该篇请求等待。重算失败会保留旧结果并返回 200（日志 warning，响应带
processed_upgrade_failed: true），raw_text/ 生词卡 / 批注从不被改动。旧结果快照在processed_json_backup，可用python tools/recompute_processed.py --restore逐字回退。 - 生词卡重复卡只做部分修复：写入侧已改为幂等 upsert（同词重复提交不再新增），但未建 UNIQUE 索引、存量重复未合并；读侧按「共 N 张」去重显示。存量合并要等真实重复统计后再定策略。
- Android 真机、低端机与 iOS 均未覆盖：本版仅完成 x86_64 模拟器（API 37）覆盖安装与
versionCode检查，未启动点检；arm64 真机未安装点检，低端机内存峰值与 OOM 未测量，iOS Safari 键盘态未验证。真机与低端机不是发版前置，但不得把模拟器结果当作真机结论。
本项目采用 Apache License 2.0 开源许可证。欢迎提 PR 或 Issue 参与共建。