ap-cli 1.18.1

一个帮助用户通过提问-生成-测验循环来学习新概念的命令行工具

AP CLI - 智能学习助手

一个基于AI的命令行学习工具，帮助用户通过"地图-解释-测验-追踪"的完整学习循环来掌握新概念。支持多主题管理和智能质量控制。

✨ 核心功能

🗺️ 多主题学习系统

• 📋 学习地图生成 (ap m): 为指定主题生成结构化的概念学习地图
• 🌳 进度可视化 (ap t): 显示全局或特定主题的学习进度树状图
• 🔄 多主题管理: 支持同时管理多个学习主题，数据隔离存储

🎓 智能学习循环

• 🤔 智能解释 (ap e): 使用DeepSeek AI生成概念的详细Markdown解释文档
• 📝 自动出题 (ap g): 基于解释文档智能生成高质量选择题测验
• 🎯 交互测验 (ap q): 命令行交互式测验，实时反馈和结果统计
• 🚀 一键学习 (ap s): 完整学习流程自动化，从解释到测验一步到位

🔧 质量保证与自动化

• ⚡ 智能质量检查: 自动检测测验题目质量，确保答案分布均匀
• 🔄 答案随机化: 智能重排选项顺序，避免答案位置偏向
• 🤖 Pre-commit Hook: AI驱动的版本管理，自动分析代码变更并更新版本号
• ⚙️ 配置管理 (ap i): 一键初始化和配置API密钥

🛠️ 技术栈

• Python 3.8+ - 核心开发语言
• Typer - 现代化CLI框架，支持类型提示
• OpenAI SDK - DeepSeek API集成
• python-dotenv - 环境变量安全管理
• PyYAML - YAML格式数据处理

🚀 快速开始

自动化安装（推荐）

Windows 用户：

# 双击运行或在命令行执行
init.bat

Linux/Mac 用户：

# 给脚本执行权限并运行
chmod +x init.sh
./init.sh

手动安装

1. 克隆项目并进入目录

   git clone <repository-url>
   cd ap
   

2. 创建虚拟环境

   python -m venv .venv
   

3. 激活虚拟环境

   # Windows
   .venv\Scripts\activate
   
   # Linux/Mac
   source .venv/bin/activate
   

4. 安装依赖

   pip install -r requirements.txt
   

5. 安装CLI工具

   pip install -e .
   

6. 配置API密钥

   # 复制环境变量示例文件
   cp .env.example .env
   
   # 编辑.env文件，填入您的DeepSeek API密钥
   # DEEPSEEK_API_KEY=your_actual_api_key_here
   

📖 使用指南

基础命令

# 查看帮助
ap --help

# 初始化配置（首次使用）
ap i

# 为主题生成学习地图
ap m "机器学习"

# 查看学习进度
ap t                    # 显示所有主题概览
ap t "机器学习"          # 显示特定主题详情

# 生成概念解释（支持多主题格式）
ap e "机器学习/监督学习"

# 基于解释生成测验题目
ap g "机器学习/监督学习"

# 开始交互式测验
ap q "机器学习/监督学习"

# 一键完成完整学习流程
ap s "机器学习/监督学习"

多主题学习工作流

1. 创建学习地图 (ap m)

ap m "深度学习"

这将：

• 调用DeepSeek AI生成该主题的结构化学习路径
• 创建概念层级关系和依赖图谱
• 自动创建主题相关的目录结构
• 保存学习地图到 workspace/concept_map.json

2. 查看学习进度 (ap t)

# 查看所有主题概览
ap t

# 查看特定主题详情
ap t "深度学习"

这将：

• 显示所有主题的学习统计和进度
• 树状结构展示概念层级关系
• 使用状态图标标识学习状态
• 提供学习建议和瓶颈分析

3. 学习特定概念

# 使用多主题路径格式
ap e "深度学习/卷积神经网络"
ap g "深度学习/卷积神经网络"  
ap q "深度学习/卷积神经网络"

# 或使用一键学习流程
ap s "深度学习/卷积神经网络"

替代使用方式

如果遇到Typer相关问题，可以使用简化版本：

# 使用简化版本生成解释
python main_simple.py e "概念名称"

# 使用完整版本（推荐）
python main.py e "概念名称"

📁 项目结构

ap/
├── .env                    # API密钥配置（需手动创建）
├── .env.example           # 环境变量示例
├── .gitignore             # Git忽略文件
├── README.md              # 项目说明文档
├── requirements.txt       # Python依赖包
├── setup.py              # 项目安装配置
├── init.sh               # Linux/Mac自动化安装脚本
├── install-hook.py       # Pre-commit Hook安装脚本
├── pre-commit-hook.py    # AI驱动的版本管理Hook
├── PRE_COMMIT_HOOK_README.md  # Hook使用说明
├── ap/                   # 核心包目录
│   ├── __init__.py
│   ├── __main__.py       # 程序入口点
│   ├── cli.py           # CLI命令注册
│   ├── cli_commands/    # 命令实现模块
│   │   ├── init_config.py    # 配置初始化
│   │   ├── generate_map.py   # 学习地图生成
│   │   ├── display_tree.py   # 进度树显示
│   │   ├── explain.py        # 概念解释
│   │   ├── generate_quiz.py  # 测验生成
│   │   ├── quiz.py          # 交互测验
│   │   └── study.py         # 完整学习流程
│   ├── core/            # 核心功能模块
│   │   ├── concept_map.py    # 多主题概念地图管理
│   │   ├── quiz_quality_checker.py  # 测验质量检查
│   │   ├── settings.py       # 配置管理
│   │   └── utils.py         # 工具函数
│   ├── docs/            # 文档目录
│   └── tests/           # 测试目录
├── dev/                 # 开发文档和规范
│   ├── 00-specs/        # 模板和规范
│   ├── 01-epics/        # Epic级别需求
│   └── README.md        # 开发指南
└── workspace/           # 生成内容存储目录
    ├── concept_map.json     # 多主题概念地图数据
    ├── explanation/         # 概念解释文档
    │   └── <topic>/        # 按主题分类
    ├── quizzes/            # 测验题目文件
    │   └── <topic>/        # 按主题分类
    └── results/            # 测验结果记录
        └── <topic>/        # 按主题分类

🔧 环境验证

运行环境检查脚本确保配置正确：

python setup_env.py

该脚本将检查：

• Python版本兼容性
• 虚拟环境状态
• 依赖包安装情况
• API密钥配置
• CLI命令可用性

📊 功能状态

✅ 已完成功能

• 多主题学习系统 - 完全实现
  • 学习地图生成 (ap m)
  • 进度可视化 (ap t)
  • 多主题数据管理和迁移
• 智能学习循环 - 完全实现
  • 概念解释生成 (ap e)
  • 测验题目生成 (ap g)
  • 交互式测验 (ap q)
  • 完整学习流程 (ap s)
• 质量保证系统 - 完全实现
  • 智能质量检查器
  • 答案分布均匀性验证
  • 自动答案随机化
• 开发工具 - 完全实现
  • AI驱动的Pre-commit Hook
  • 自动版本管理
  • 配置管理 (ap i)

🚧 开发中功能

• 云端同步 - 规划中
  • Cloudflare D1数据库集成
  • 多设备数据同步
  • 教师管理界面

🔧 高级功能

🤖 AI驱动的版本管理

项目集成了智能的Pre-commit Hook，能够：

• 自动分析Git提交内容
• 使用DeepSeek AI判断变更类型
• 智能更新版本号（MAJOR/MINOR/PATCH）
• 详细说明请参考 PRE_COMMIT_HOOK_README.md

⚡ 智能质量控制

测验生成包含质量检查机制：

• 答案分布检查: 确保正确答案在各选项位置均匀分布
• 质量评分: 基于统计学原理计算质量分数
• 自动优化: 智能重排选项顺序，消除位置偏向
• 详细报告: 生成质量分析报告和改进建议

🗺️ 多主题架构

支持复杂的学习场景：

• 主题隔离: 不同主题的数据完全隔离存储
• 路径格式: 使用 主题/概念 格式组织内容
• 数据迁移: 自动从旧格式迁移到多主题格式
• 向后兼容: 保持对旧命令格式的支持

🔍 故障排除

常见问题

1. 环境变量未找到

   # 确保.env文件存在且包含正确的API密钥
   cp .env.example .env
   # 编辑.env文件填入真实的API密钥
   

2. Typer相关错误

   # 使用简化版本
   python main_simple.py e "概念名称"
   

3. 依赖安装失败

   # 升级pip并重新安装
   python -m pip install --upgrade pip
   pip install -r requirements.txt
   

4. CLI命令不可用

   # 重新安装包
   pip install -e .
   

获取帮助

• 查看命令帮助：ap --help
• 查看特定命令帮助：ap e --help
• 运行环境检查：python setup_env.py

🤝 贡献指南

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情

👥 作者

• AP CLI Team - 初始开发 - [e-mail]

---

享受智能化的学习体验！ 🎓✨

🔗 相关文档

• Pre-commit Hook使用指南 - AI驱动的版本管理详细说明
• 开发文档 - 项目开发规范和Epic管理
• 概念图使用说明 - 多主题概念地图详细用法

Test