Files

构建并部署 AI Agent 服务 / deploy (push) Failing after 5m36s

Details

- 添加 agent_subgraphs 目录，包含主图 README.md 和三个子图文档
- 通讯录子图：联系人 CRUD、邮件读取/发送、智能嗅探
- 智能词典子图：翻译、查词、每日一词、专业名词提炼
- 研究分析子图：联网搜索、报告生成、引用溯源
- 公共工具：意图理解、人工审核、格式化输出、检查点持久化、条件路由、LLM 调用、数据库工具、状态基类
- 配置调整：启用 DEBUG 日志级别
- 启动脚本：使用 python3 替代 python

2026-04-22 14:49:06 +08:00

README.md

feat: 添加 agent_subgraphs 子图架构文档和公共工具说明

2026-04-22 14:49:06 +08:00

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	格式输出	提供下载链接

README.md Unescape Escape

智能词典子图 (Dictionary Subgraph)

🎯 核心架构

技术栈

子图分层架构

数据流总览

📂 模块与文件结构

🎯 演进路线与核心机制

Level 1：基础翻译与查词

Level 2：联想记忆法

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

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

Level 5：智能词汇教练

🔧 核心组件详解

1. 意图理解节点

2. 翻译节点

3. 查词节点

4. 每日一词节点

5. 专业名词提炼节点

6. 生词本管理节点

7. 复习计划节点

8. 联想记忆节点

9. Anki 导出节点

🔀 条件路由详解

入口路由：意图分支

查词后续路由

📊 状态设计

状态结构概览

🔄 工作流程

查词+联想记忆流程

复习流程

Anki导出流程

README.md