ailine/backend/app/agent_subgraphs/dictionary/README.md

# 智能词典子图 (Dictionary Subgraph)

该子图负责处理翻译、查词、生词本管理等功能，基于 LangGraph 状态机编排多阶段学习流程，支持联想记忆法、艾宾浩斯遗忘曲线复习、Anki 导出等核心能力。子图设计遵循"高效学习、科学复习、持久记忆"原则。

> **使用公共工具**：意图理解、格式化输出、检查点持久化、条件路由、LLM 调用、数据库工具、状态基类

---

## 🎯 核心架构

### 技术栈

| 层级 | 组件 | 说明 |
|:-----|:-----|:-----|
| **编排框架** | LangGraph StateGraph | 状态机驱动的子图工作流编排 |
| **LLM 服务** | 智谱 AI / DeepSeek API | 翻译、释义生成、联想记忆、专业名词提炼（使用公共 LLM 工具） |
| **翻译服务** | DeepL / 有道 API | 高质量机器翻译 |
| **关系存储** | PostgreSQL | 生词本、复习记录持久化（使用公共数据库工具） |
| **导出工具** | csv / Anki APKG | 生词本导出格式 |

### 子图分层架构

```
┌─────────────────────────────────────────────────────────────────┐
│                        主图 (Main Graph)                         │
└──────────────────────────────┬──────────────────────────────────┘
                               │ 状态映射 / 结果聚合
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                    智能词典子图接口层                            │
│  - 状态转换：主状态 ↔ 子图状态（使用公共状态基类）               │
│  - 错误传播与优雅降级                                            │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                        工作流编排层                              │
│  - 节点调度与条件路由（使用公共路由工具）                        │
│  - 复习计划计算                                                  │
│  - 状态持久化与检查点（使用公共检查点工具）                        │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                          节点层                                  │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │
│  │意图理解  │ │翻译节点  │ │查词节点  │ │每日一词  │ │专业提炼│ │
│  │(公共工具)│ │          │ │          │ │          │ │        │ │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └────────┘ │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐          │
│  │生词管理  │ │复习计划  │ │联想记忆  │ │格式输出  │          │
│  │          │ │          │ │          │ │(公共)    │          │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘          │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                          工具层                                  │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐        │
│  │翻译API   │ │词典API   │ │数据库工具│ │艾宾浩斯  │        │
│  │          │ │          │ │(公共)    │ │          │        │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘        │
└─────────────────────────────────────────────────────────────────┘
```

### 数据流总览

智能词典子图根据学习意图分支执行，支持查词、翻译、复习等多种学习模式。

```
用户请求
     │
     ▼
┌─────────────┐
│  意图理解   │ ← 使用公共意图理解工具
└──────┬──────┘
       │
       ├──────────┬──────────┬──────────┬──────────┬──────────┐
       ▼          ▼          ▼          ▼          ▼          ▼
     翻译      查词      每日一词   专业提炼   生词管理    复习计划
       │          │          │          │          │          │
       ▼          ▼          ▼          ▼          ▼          ▼
   翻译API    词典API    每日推荐   术语提取   增删改查   复习计算
       │          │          │          │          │          │
       │          ▼          │          │          │          │
       │      联想记忆      │          │          │          │
       │          │          │          │          │          │
       └──────────┴──────────┴──────────┴──────────┴──────────┘
                  │
                  ▼
             格式输出 ← 使用公共格式化工具
                  │
                  ├──────────┐
                  │          │
                  ▼          ▼
            保存生词    Anki导出
                  │          │
                  └──────────┘
                  │
                  ▼
              返回主图
```

---

## 📂 模块与文件结构

```
app/dictionary/
├── __init__.py
├── graph.py              # 子图构建入口，定义状态图与路由
├── state.py              # 子图状态定义（继承公共状态基类）
├── nodes/                # 节点实现
│   ├── __init__.py
│   ├── translate.py      # 翻译节点
│   ├── lookup.py         # 查词节点
│   ├── daily_word.py     # 每日一词节点
│   ├── extract_terms.py  # 专业名词提炼节点
│   ├── vocab.py         # 生词本管理节点
│   ├── review.py        # 复习计划节点
│   ├── association.py   # 联想记忆节点
│   └── export.py        # Anki导出节点
├── tools/                # 子图特有工具集
│   ├── translate_api.py  # 翻译API工具
│   ├── dictionary_api.py # 词典API工具
│   ├── ebinghaus.py     # 艾宾浩斯遗忘曲线工具
│   └── anki.py          # Anki导出工具
└── persistence/          # （使用公共检查点工具，无需单独实现）
```

> **注意**：以下模块使用公共工具，无需单独实现：
> - 意图理解节点 → 使用 `agent_subgraphs.common.intent`
> - 格式输出节点 → 使用 `agent_subgraphs.common.format`
> - 检查点持久化 → 使用 `agent_subgraphs.common.checkpoint`
> - 条件路由 → 使用 `agent_subgraphs.common.routing`
> - LLM 调用 → 使用 `agent_subgraphs.common.llm`
> - 数据库操作 → 使用 `agent_subgraphs.common.db`

---

## 🎯 演进路线与核心机制

### Level 1：基础翻译与查词

**核心机制**：调用翻译/词典 API，展示基础释义。

- 支持中↔英、中↔日等多语言互译。
- 提供单词词性、释义、例句。
- 基础生词本功能（添加、查询）。

**适用场景**：快速翻译、单词查询。

**实现指引**：意图理解节点识别翻译/查词意图，路由到对应节点。

### Level 2：联想记忆法

**核心机制**：利用 LLM 生成联想记忆法，帮助记忆单词。

- 词根词缀分析。
- 词源故事/文化背景。
- 趣味联想（谐音、画面感）。
- 同根词/近义词/反义词扩展。

**适用场景**：深度单词学习、高效记忆。

**实现指引**：查词后自动生成联想记忆内容，可选是否保存到生词本。

### Level 3：艾宾浩斯遗忘曲线复习

**核心机制**：基于遗忘曲线科学安排复习时间。

- 首次学习后按 1天、2天、4天、7天、15天、30天 间隔复习。
- 根据用户记忆反馈动态调整复习间隔。
- 每日复习提醒。

**适用场景**：长期词汇积累、抗遗忘学习。

**实现指引**：复习计划节点计算下次复习时间，存入数据库。

### Level 4：专业名词提炼与管理

**核心机制**：从文本中自动提取专业名词，建立术语库。

- 支持从任意文本中提取专业术语。
- 自动生成术语释义。
- 按领域分类管理术语库。

**适用场景**：专业文档阅读、学术学习。

**实现指引**：使用 LLM 进行 NER 和术语识别。

### Level 5：智能词汇教练

**核心机制**：个性化学习路径、多模态记忆、学习进度追踪。

- 根据用户水平推荐学习内容。
- 图片、音频等多模态记忆辅助。
- 学习统计与进度可视化。
- 自适应难度调整。

**适用场景**：系统化语言学习、个性化辅导。

---

## 🔧 核心组件详解

### 1. 意图理解节点

**职责**：接收用户请求，区分翻译、查词、每日一词、专业提炼、生词管理、复习等意图。

**输入**：用户自然语言请求。

**输出**：
- `intent_type`：意图类别（translate / lookup / daily / extract / vocab / review / export）。
- `target_word`：目标单词/文本。
- `source_lang`：源语言。
- `target_lang`：目标语言。

**实现要点**：
- 使用 LLM 分类意图，输出结构化 JSON。
- 关键词匹配兜底（如"翻译"、"查一下"）。

### 2. 翻译节点

**职责**：调用翻译 API，返回高质量翻译结果。

**输入**：待翻译文本、源语言、目标语言。

**输出**：
- `translation`：翻译结果。
- `alternative_translations`：备选翻译（如有）。

**实现要点**：
- 优先使用 DeepL，降级到有道或 LLM 翻译。
- 支持长文本分段翻译。

### 3. 查词节点

**职责**：查询单词详细释义、词性、例句等信息。

**输入**：目标单词。

**输出**：
- `word_info`：单词信息（词性、释义、音标）。
- `examples`：例句列表。

**实现要点**：
- 调用词典 API，缺失时使用 LLM 生成。
- 支持英英、英汉双解。

### 4. 每日一词节点

**职责**：根据用户水平和历史，推荐今日学习单词。

**输入**：用户学习偏好。

**输出**：
- `daily_word`：今日推荐单词。
- `word_detail`：单词详情。
- `learning_tip`：学习建议。

**实现要点**：
- 结合用户历史生词和复习进度推荐。
- 难度适中递进。

### 5. 专业名词提炼节点

**职责**：从文本中提取专业名词，生成释义。

**输入**：待分析文本、领域（可选）。

**输出**：
- `extracted_terms`：提取的专业名词列表。
- `term_definitions`：名词释义。

**实现要点**：
- 使用 LLM 进行术语识别和定义生成。
- 支持按领域过滤。

### 6. 生词本管理节点

**职责**：生词本的增删改查操作。

**输入**：操作类型、生词数据。

**输出**：
- `operation_result`：操作结果。
- `vocab_list`：更新后的生词列表。

**实现要点**：
- 支持批量添加。
- 按标签/难度/复习时间筛选。

### 7. 复习计划节点

**职责**：基于艾宾浩斯遗忘曲线计算复习计划。

**输入**：生词 ID、上次复习时间、记忆强度。

**输出**：
- `next_review`：下次复习时间。
- `review_schedule`：完整复习计划。

**实现要点**：
- 使用标准艾宾浩斯间隔（1天、2天、4天、7天、15天、30天）。
- 根据用户反馈动态调整。

### 8. 联想记忆节点

**职责**：为单词生成联想记忆法，帮助记忆。

**输入**：目标单词。

**输出**：
- `root_analysis`：词根词缀分析。
- `etymology`：词源故事。
- `association`：趣味联想。
- `word_family`：同根词/近义词/反义词。

**实现要点**：
- 使用 LLM 生成富有创意的记忆法。
- 支持用户自定义联想。

### 9. Anki 导出节点

**职责**：导出生词本为 Anki 可导入格式。

**输入**：导出范围（全部/按标签/按时间）。

**输出**：
- `export_file`：导出文件路径。
- `export_count`：导出单词数量。

**实现要点**：
- 支持 CSV 和 APKG 两种格式。
- 包含联想记忆内容。

---

## 🔀 条件路由详解

### 入口路由：意图分支

- **位置**：意图理解节点之后。
- **条件**：
  - `intent_type == "translate"` → 翻译节点。
  - `intent_type == "lookup"` → 查词节点。
  - `intent_type == "daily"` → 每日一词节点。
  - `intent_type == "extract"` → 专业提炼节点。
  - `intent_type == "vocab"` → 生词管理节点。
  - `intent_type == "review"` → 复习计划节点。
  - `intent_type == "export"` → Anki导出节点。

### 查词后续路由

- **位置**：查词节点之后。
- **条件**：
  - 用户询问"怎么记" → 联想记忆节点。
  - 用户说"保存" → 生词管理节点（添加）。
  - 无后续 → 格式输出。

---

## 📊 状态设计

### 状态结构概览

| 分组 | 字段 | 类型 | 说明 |
|:-----|:-----|:-----|:-----|
| **输入** | `user_input` | `str` | 用户原始请求 |
| **意图** | `intent_type` | `str` | 意图类别 |
| | `target_word` | `str` | 目标单词/文本 |
| | `source_lang` | `str` | 源语言 |
| | `target_lang` | `str` | 目标语言 |
| **翻译** | `translation` | `str` | 翻译结果 |
| | `alternative_translations` | `list[str]` | 备选翻译 |
| **查词** | `word_info` | `dict` | 单词信息 |
| | `examples` | `list[str]` | 例句 |
| **联想** | `root_analysis` | `str` | 词根分析 |
| | `etymology` | `str` | 词源 |
| | `association` | `str` | 联想记忆 |
| | `word_family` | `list[str]` | 词族 |
| **每日一词** | `daily_word` | `str` | 今日单词 |
| | `word_detail` | `dict` | 单词详情 |
| | `learning_tip` | `str` | 学习建议 |
| **专业提炼** | `extracted_terms` | `list[dict]` | 提取的术语 |
| | `term_definitions` | `dict` | 术语释义 |
| **生词本** | `vocab_list` | `list[dict]` | 生词列表 |
| | `operation_result` | `str` | 操作结果 |
| **复习** | `next_review` | `datetime` | 下次复习时间 |
| | `review_schedule` | `list[dict]` | 复习计划 |
| **导出** | `export_file` | `str` | 导出文件路径 |
| | `export_count` | `int` | 导出数量 |
| **控制流** | `current_phase` | `str` | 当前阶段 |
| | `next_node` | `str` | 下一节点 |
| **输出** | `final_result` | `str` | 最终结果 |

---

## 🔄 工作流程

### 查词+联想记忆流程

| 步骤 | 节点 | 说明 |
|:-----|:-----|:-----|
| 1 | 意图理解 | 识别查词意图 |
| 2 | 查词 | 查询单词释义 |
| 3 | 联想记忆 | 生成记忆法 |
| 4 | 询问保存 | 可选保存到生词本 |
| 5 | 格式输出 | 展示结果 |

### 复习流程

| 步骤 | 节点 | 说明 |
|:-----|:-----|:-----|
| 1 | 意图理解 | 识别复习意图 |
| 2 | 复习计划 | 获取今日需复习单词 |
| 3 | 复习交互 | 逐个复习，记录记忆强度 |
| 4 | 更新计划 | 计算下次复习时间 |
| 5 | 格式输出 | 展示复习结果 |

### Anki导出流程

| 步骤 | 节点 | 说明 |
|:-----|:-----|:-----|
| 1 | 意图理解 | 识别导出意图 |
| 2 | Anki导出 | 生成导出文件 |
| 3 | 格式输出 | 提供下载链接 |