专为德语学习者与歌德（A1–C1）/ 德福（TestDaF）/ DSH 备考打造的学术级伴读与句法剖析系统。
一键拆解拓扑五场域（VF/LK/MF/RK/NF）与 AST 从句语法树，内置歌德 A1 全真考场与 FSRS 记忆排程。
普通用户（免装 Python，开箱即用）：
- 🪟 Windows：前往下方 多平台下载 取得 ZIP，解压后双击
DeLector.exe即可运行独立桌面客户端（无需配环境，数据保存在本地用户目录）。- 📱 Android：下载 APK 安装包，内嵌 Python 与 spaCy 离线模型，单机脱网可用。
开发者 / 源码运行：
pip install -r requirements.txt # 安装 Python 依赖（推荐 Python 3.11）
python -m spacy download de_core_news_md # 下载德语 NLP 模型
python start.py # 一键启动并自动打开浏览器 http://localhost:8000
python desktop.py # Windows 桌面壳（原生窗口 + 托盘 + 启动 splash）
docker compose up -d --build # 或 Docker 容器化一键部署开发者首次启用提交前密钥扫描（每个克隆都要做一次）：
git config core.hooksPath .githooks📖 Windows 分支 / Docker 细节 / 环境变量 / 打包 / 安全守卫等完整说明见 docs/agents/ops.md。
🚀 v5.21.1 最新版本亮点（2026-11-03）：
- 伴学 SSE 跨 chunk 分帧修复：修复网络分片导致的 assistant 消息与 proposal 静默丢失、不落库问题，完整帧闭合后才解析。
- 传输与持久化守恒：覆盖逐字节、随机分片、CRLF 与多行
data；原始字节转发不变，每轮只落库一次，proposal 不丢不重。- 内部重构行为不变：Go helper 全面接线并拆分
RunLoop，submitPrompt收敛为事件控制器；七类事件、请求字段与 DOM/消息状态保持既有契约。- 探针与变异验证：伴学探针最终 274 checks / 34 场景，本分支全量 2720 passed / 2 skipped；Go 与 JS 变异均实测变红，还原后复绿。
📱 Android 用户注意：含
static/改动的版本需覆盖安装才生效。 📜 完整版本变更细节见 CHANGELOG.md。
| 平台 | 版本 | 说明 | 下载通道 |
|---|---|---|---|
| 🪟 Windows x64 | v5.21.1 |
原生桌面窗口 + 系统托盘，免装 Python，解压双击 DeLector.exe；需 Win10+ 与 WebView2 运行时（Win11 自带；Win10 装不上时的表现见「已知限制」）；首次启动把数据放到 %LOCALAPPDATA%\DeLector |
下载 ZIP 包 (GitHub Releases) |
| 🍎 macOS | v5.21.1 |
解压运行 start 脚本，全自动启动服务与默认浏览器 |
下载 TAR.GZ 包 (GitHub Releases) |
| 🐧 Linux x64 | v5.21.1 |
全发行版通用，解压运行 start 即可使用 |
下载 TAR.GZ 包 (GitHub Releases) |
| 📱 Android | v5.21.1 |
内嵌 Python 运行时与 spaCy 离线模型，单机独立运行；支持 arm64-v8a，CI 钉死签名 keystore 并验签（可覆盖升级）。 | 下载 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 词阶热力图 + 0ms 歌德离线词库 + 荧光便签、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 静默同步。
- 内联 IDE 写作工坊 & 伴读宠物：行内实时语法诊断 + VSCode 级 Inlay Hints；Eule & 伙伴混合双模伴读。
完整功能清单见 FEATURES.md。
💬 用着顺手或别扭，都欢迎说一声：开一条零门槛反馈——不用懂技术、不用建分支、不用写
bug(scope):前缀，三道判断题点一下就行，想吐槽什么随手写（留空也完全 OK）。你的反馈直接决定下一个版本做什么。
| 领域 | 核心技术 | 说明 |
|---|---|---|
| 后端框架 | FastAPI + Uvicorn |
异步高性能 REST API |
| 自然语言处理 | spaCy (de_core_news_md / sm) |
本地高精德语分词、词性标注、形态分析与五场域句法依存 |
| 形态学引擎 | 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 |
全套单元与集成测试用例（数量见顶部 Tests 徽章，100% Green），CI 覆盖 md 加载路径与 Android 构建验签 |
桌面端默认把数据放在用户目录、不随程序目录：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/(34 模块) + german/(工作台) + css/(视觉 tokens)
├── android/ # Android 独立离线单机版工程 (Chaquopy + Gradle)
├── agent/ # Phase 2 Go Agent Runtime（CLI + DAG + 工具注册，预览通道）
├── tests/ # 自动化测试套件：153 个测试文件 (2,438 passed) + 行为探针与迁移哨兵
├── tools/ # 架构守卫工具链：六道机械闸 (分层契约/层序/Mock漂移/禁止静默降级/API契约/HTML同步) + 构建装配工具
├── 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.21.1 | 2026-11-03 | 伴学 SSE 跨 chunk 分帧修复 · Go RunLoop 与 submitPrompt 行为不变重构 · 274 checks / 34 场景 |
| v5.21.0 | 2026-11-03 | 伴学 Agent 页面级能力与 HITL 生词提议 · 跨页历史恢复 · 卡盒缺释义统一 · PWA 位图图标 · 桌宠眨眼原点修复 |
| v5.20.2 | 2026-11-01 | 阅读器连续段落排版重塑 (ADR-0026) · CEFR 词阶视觉降噪与三档透视胶囊 · 单词点击/切句句法抽屉实时联动同步 (DFS-DEBUG) · CI 6 路并行矩阵极限提速 |
| v5.20.1 | 2026-11-01 | Android 移动端桌宠拖拽手势修复 · 句法默认显示清除（收敛至选区悬浮胶囊工具条）· CI Pytest Matrix 双分片并发提速 · Apache License 2.0 正式生效 |
| v5.20.0 | 2026-11-01 | 伴学导学 Agent 运行时（Go 编排 · 原生 Tool Calling · Pi 式动态 60% 压缩 · TurnPipeline 中间件 · 物理 trace）· SQLite 会话持久化与画像探针（FSRS 负荷 · 离线词典）· 前端纯 DOM 解耦 · 移动端抽屉上下拖拽可调尺寸与三档预设 · 2670+ passed |
| v5.19.0 | 2026-10-22 | 桌面单实例锁（OS 文件锁判据，双击第二次不再起第二个进程）· 端口自动顺延 8000→8002–8010（8001 留给 supervisor）· lan-info 上报真实端口 · 前端 reader.js/cards.js 继续解耦（rd-syntax/rd-api/cd-state）· 2584 passed |
| v5.18.0 | 2026-10-19 | 单体架构与前端视图全面解耦（database/routes 拆解 · index.html/writer.js/reader.js 模块化）· 交互式智能体循环（ADR-0023 / 裁判终审 / AI 润色）· 裁判集扩充与真题回测（ADR-0024）· 六道自动化机械闸矩阵落地 · 2438 passed（净增 670 用例） |
| v5.17.0 | 2026-10-11 | 首个原生桌面壳（pywebview + 系统托盘 + 统一退出收尸）· 数据落点外置 %LOCALAPPDATA%\DeLector · 更新可见性（顶栏 chip + /api/update/check）· 发版门守卫（tag == v+APP_VERSION）· 真启产物闸 / 前端跨边界契约闸 · spaCy 惰性加载 |
| v5.16.0 | 2026-10-06 | 惰性迁移性能缺陷根治（消除单篇 GET spaCy N+1 重算）· CI 必需运行时清单显式化 · localhost 守卫加固 |
| v5.15.0 | 2026-10-05 | 降级标记并发串味修复 · 工作台单点化来源判据 · localhost 受保护路由集合与探针 --json 契约冻结守卫 |
| v5.14.0 | 2026-10-05 | 卡盒去复习化（修复「白复习」P0）· 听力微训与长难句精读工坊 · 5 维难度评分与 CEFR 估算 |
📜 历史更多版本记录（v1.0 ~ v5.13）请回溯 CHANGELOG.md。
- Win10 需先装 WebView2 运行时（Win11 自带）：缺运行时双击
DeLector.exe会提示安装后退出，不会白屏。 - 冷启动的数字必须带「路径 × 冷/暖」两个标签（同一个包能测出两个数，差 ≈0.67s）：源码路径（
python desktop.py）暖 ≈ 5.4s / 冷 ≈ 6s；便携产物（你下载的 ZIP 里的DeLector.exe）实测冷 ≈ 8.5s / 暖 ≈ 6.9s。其中约 2s 是「建服前的端口/身份校验」（防旧进程冒充新构建）——它是新引入的显式校验，不是提速指标；数据面已优化（文章列表 918ms → 8.9ms）。 launch.log有已知的整行丢失（Windows 上多个句柄并发追加同一文件，实测约 3% 的行整行消失、不是半行）：排查启动问题时若日志缺行，先按此排除；tools/first_screen_from_log.py报退出码 3/5（缺锚行）不必然等于日志损坏。- Android 覆盖安装才生效：含
static/改动的版本必须覆盖安装（应用按versionCode判定重解包）。 - Android 端「检查更新」暂未验证：桌面端可用；Android 上两条假设（Chaquopy 能否完成到公网的 HTTPS、WebView 点外链是否交给系统浏览器）从未验证 ⇒ 手机上请以本页/Releases 的版本号为准。
- Android 装不回旧版：
versionCode只升不降 ⇒ 装错版本只能卸载重装（会清应用私有数据，请先导出备份）。
本项目采用 Apache License 2.0 开源许可证。欢迎提 PR 或 Issue 参与共建！