japanese-tutor

核心用法

Japanese Tutor 是一款面向日语学习者的交互式辅导工具，核心功能涵盖五大模块：词汇练习（每日单词、主题词汇组）、语法讲解（规则简化+例句）、学习材料解析（PDF/DOCX 上传后自动提取词汇语法并持久化存储）、OCR 翻译（图片/文字识别与翻译）以及测验模式。用户可通过自然语言指令如"Parsin ini dong"（解析这个）或"Bantuin PR ini"（辅导作业）快速触发功能，系统会调用 parse_pdf_gemini.py 或 parse_docx.py 处理文件，并将新知识追加至 references// 目录的词汇表和语法库中。

显著优点

1. 教学伦理设计：作业辅导坚持"引导而非代答"原则，解释概念后提供类似例题，培养用户自主解题能力。
2. 知识持久化：自动将新材料中的词汇语法保存至本地引用文件，形成可累积的个人知识库。
3. 多模态支持：结合 Gemini Vision 实现 PDF 布局分析与图片 OCR，降低日语学习者处理纸质/扫描材料的门槛。
4. 轻量化交互：支持印尼语混合指令（Jaksel 风格），降低非英语用户的使用门槛。

潜在缺点与局限性

• 网络强依赖：PDF 解析必须调用 Google Gemini API，离线环境完全不可用。
• 隐私边界模糊：用户上传的 PDF 内容会被传输至 Google 服务器，虽文档有说明但无二次确认机制。
• 权限声明缺失：SKILL.md 未明确列出文件读写、网络访问、环境变量读取等权限清单。
• 来源可信度有限：T3 级个人开发者账号，无组织背书或代码签名。

适合的目标群体

• 日语 N5-N4 级别初学者，需要结构化词汇语法积累
• 使用日语教材 PDF/Word 文档的自学者
• 需要作业辅导但希望理解解题思路的学生
• 需要快速翻译日语图片/菜单的旅行者

使用风险

• 数据外泄风险：敏感文档（含个人信息、商业机密）切勿通过 PDF 解析功能上传。
• API 可用性风险：Gemini API 服务中断或额度耗尽将导致核心功能失效。
• 文件修改风险：references// 目录文件会被追加写入，建议定期备份以防数据污染。
• 路径遍历隐患：脚本对输入文件路径的验证较基础，极端情况下可能存在安全风险。

核心功能

Japanese Tutor 是一款面向日语学习者的交互式AI辅导工具，核心能力覆盖五大模块：

1. 词汇与语法教学

• 采用「3-5词组块」教学法，配合每日一词推送，降低记忆负担
• 语法讲解必配2-3个例句，将抽象规则具象化
• 内置N5级词库和基础语法库作为知识锚点

2. 课件智能解析（PDF/DOCX）

• 调用Gemini Vision API进行OCR和版面分析，自动提取生词和语法点
• 关键设计：解析内容会持久化写入references/vocab.md和grammar.md，形成个人知识库
• 支持按课程创建独立文件（如lesson_X.md）保持学习体系

3. 作业辅导伦理

• 明确「引导不代劳」原则：解释概念→提供相似例题→引导用户自主解题
• 新出现的知识点自动归档，实现「做一题、积一知」

4. OCR与翻译

• 图片识别输出「原文-读音-释义」三要素
• 文本翻译附带语感/语境说明

5. 测验模式

• 支持对已知材料或新摄入内容生成测验

显著优点

• 学习闭环设计：从输入（课件解析）→处理（讲解/练习）→输出（知识库归档）形成完整闭环
• 教学伦理内置：作业辅导的「三步引导法」避免了AI沦为作弊工具
• 渐进式知识管理：自动持久化机制让学习成果可累积、可检索
• 轻量技术栈：Python脚本+Markdown知识库，无复杂依赖

潜在局限

• 云端依赖：PDF解析完全依赖Google Gemini API，需网络连接且产生数据出境
• T3可信度：个人开发者项目，长期维护和功能迭代存在不确定性
• 无许可证声明：当前未开源，使用和二次开发存在法律模糊地带
• 输入验证缺失：文件路径参数缺乏校验，极端情况下可能引发路径遍历风险（虽当前代码无恶意利用）

适合人群

• 日语初学者（N5-N4水平）需要结构化辅导
• 使用PDF/DOCX教材的自学用户
• 希望建立个人日语知识库的学习者
• 不适合：需要离线环境、处理敏感文档、或追求高阶商务日语的用户

常规风险

| 风险类型 | 说明 | 缓释建议 |

|---------|------|---------|

| 数据隐私 | PDF内容上传至Google云端 | 避免上传含个人敏感信息的文档 |

| API可用性 | Gemini服务中断影响核心功能 | 准备备选OCR方案 |

| 幻觉风险 | AI生成的语法解释可能存在偏差 | 关键知识点交叉验证权威教材 |

| 环境配置 | 需正确设置`GEMINI_API_KEY` | 按文档指引配置环境变量 |