docs: 重构 README 文档，整理已实现和待实现功能
All checks were successful
构建并部署 AI Agent 服务 / deploy (push) Successful in 5m37s
All checks were successful
构建并部署 AI Agent 服务 / deploy (push) Successful in 5m37s
- 创建 backend/app/README.md 主文档 - 整理已实现功能（带 ✅ 标记） - 列出待实现功能（带 🚧 标记） - 删除 agent_subgraphs/ 下的旧 README 文件
This commit is contained in:
@@ -1,428 +0,0 @@
|
||||
# 智能词典子图 (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 | 格式输出 | 提供下载链接 |
|
||||
Reference in New Issue
Block a user