<div align="center">

Nonlinear Learner

任务驱动的非线性学习导师 | Task-Driven Nonlinear Learning Tutor

先了解你的背景和任务，从你提出的知识点出发，拆开整个领域所需的知识

Understand your background and task, unpack the knowledge you need from your starting point

</div>

---

核心理念 | Core Philosophy

传统学习工具假设你有一张完整的知识地图，然后规划从 A 到 B 的路径。但现实中，当你对一个领域一无所知或只有片面了解时，你往往是从一个具体的小知识点出发的——一篇文章里看到的一个术语、一个项目里用到的一个概念。

Nonlinear Learner 先了解你的背景和任务，从你提出的那个点出发，非线性地把完成任务所需的知识"拆开"：

• 非线性离散：可以跳跃到任务需要的任意知识点，不按拓扑顺序
• 逻辑保证：每次跳跃都说明为什么，知识点之间有清晰关联
• 应用导向：优先学能立即用于完成任务的知识，跳过暂时用不到的
• 背景感知：根据你的背景跳过已知的，补充缺失的

Traditional tools plan A-to-B paths on a complete map. But in reality, you start from one small concept. This tool understands your background and task, then unpacks the knowledge you need — non-linearly but logically, application-oriented.

用户: "我想用 React 做仪表盘，会 HTML/CSS，看到别人用 useEffect"
                              │
                    ┌─────────▼──────────┐
                    │  导师拆解知识轨迹     │
                    └─────────┬──────────┘
                              │
  [1] 组件 ← 你看到的 useEffect 就在组件里
       │
  [2] JSX ← 组件用 JSX 写（跳到这里因为你不了解）
       │
  [3] useEffect ← 回到你的起始点，现在理解了上下文
       │
  [4] useState ← 仪表盘需要交互状态（跳跃，但应用需要）
       │
  [5] 数据获取 ← 仪表盘要从 API 拉数据（跳跃，任务驱动）
       │
  [6] 列表渲染 ← 展示多个数据卡片
       │
  ✗ 不学 Redux（暂时不需要）  ✗ 不学 SSR（任务用不到）

---

✨ 特性 | Features

中文	English
任务驱动导师：先问背景和任务，再拆解知识	Task-driven tutor: ask background first, then unpack
非线性跳跃，但每步有逻辑关联	Non-linear jumps with logical connections
应用导向，跳过暂时用不到的	Application-oriented, skip unnecessary
对话式交互，可提问/跳过/调整	Conversational, ask/skip/adjust anytime
MCP Server，接入 Claude/Cursor	MCP Server for AI tool integration
辐射式探索 + 路径规划两种补充模式	Radiative exploration + path planning modes
SQLite 持久化，进度自动保存	SQLite persistence, auto-save

---

🚀 快速开始 | Quick Start

1. 安装 | Install

pip install -e .

2. 一键配置 | One-Click Setup

nonlinear-learner setup

3. 对话式导师（核心功能） | Guided Tutor (Core)

nonlinear-learner guide

导师会引导你完成三步：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  对话式学习导师 | Guided Learning
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

第一步：告诉我你的学习目标
例如：用 React 做一个仪表盘、理解 Transformer 原理
> 用 React 做一个数据仪表盘

第二步：告诉我你的知识背景
例如：会 HTML/CSS 和一些 JS
> 会 HTML/CSS，JS 基础薄弱

第三步：你从哪里开始？
你看到了什么、遇到了什么、对什么好奇？
> 看到别人代码里有 useEffect，不懂是什么

正在拆解知识...
✓ 学习轨迹已生成（6 个知识点）

领域概述: React 是用于构建用户界面的库...

学习轨迹:
  → [1] 组件 (难度3/5)
       你看到的 useEffect 就在组件内部使用
    [2] JSX (难度2/5) ← 组件
       组件用 JSX 语法编写，需要先理解
    [3] useEffect (难度3/5) ← 组件, JSX
       回到你的起始点，现在有了上下文
    [4] useState (难度3/5) ← useEffect
       仪表盘需要交互状态
    [5] 数据获取 (难度3/5) ← useEffect
       仪表盘需要从 API 拉数据
    [6] 列表渲染 (难度2/5) ← useState
       展示多个数据卡片

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  步骤 1/6: 组件
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  📌 React 组件是可复用的 UI 单元
  ❓ 为什么学: 你看到的 useEffect 就在组件内部
  🔗 关联: 起始点
  ⏱  预计 30 分钟

  [AI 生成结合你任务的讲解...]

>>> next    ← 继续下一步
>>> ask     ← 提问（系统会调整轨迹）
>>> skip    ← 跳过这步
>>> info    ← 查看完整轨迹
>>> quit    ← 退出保存

---

📖 使用方式 | Usage

CLI 命令 | CLI Commands

命令	说明	Description
guide	任务驱动导师（核心）	Task-driven tutor (core)
explore	辐射式探索	Radiative exploration
learn	交互式学习	Interactive learning
serve	启动 MCP Server	Start MCP Server
setup	一键配置	One-click setup
generate	生成完整图谱	Generate full graph
plan	规划路径	Plan path
explain	AI 讲解	AI explain
ask	对话式学习	Conversational Q&A
info	图谱信息	Graph info
config	生成 MCP 配置	Generate MCP config

接入 AI 工具 | Connect to AI Tools

nonlinear-learner serve

AI 工具	配置文件位置
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json
Cursor	~/.cursor/mcp.json

Python 库 | Python Library

import asyncio
from nonlinear_learner import NonlinearLearner

async def main():
    engine = NonlinearLearner(llm_config={
        "endpoint": "https://api.openai.com/v1",
        "api_key": "sk-...",
        "model": "gpt-4o-mini",
    })

    # 启动学习会话 | Start learning session
    session = await engine.start_session(
        task="用 React 做一个仪表盘",
        background="会 HTML/CSS，JS 基础薄弱",
        starting_point="看到别人用 useEffect",
    )
    print(f"轨迹: {len(session.trajectory)} 步")
    for i, step in enumerate(session.trajectory):
        print(f"  {i+1}. {step.label} — {step.why_needed}")

    # 逐步讲解 | Guide step by step
    explanation = await engine.guide_current(session)
    print(explanation)

    # 推进 | Advance
    engine.advance_session(session)

    # 用户提问，调整轨迹 | Adjust trajectory
    result = await engine.adjust_session(session, "什么是闭包？")
    print(result["message"])

asyncio.run(main())

---

🔧 MCP 工具 | MCP Tools

20 个工具，其中 3 个为任务驱动学习核心工具： 20 tools, 3 core tools for guided learning:

工具 Tool	说明 Description
start_guided_learning	启动任务驱动学习会话
guide_next_concept	讲解当前知识点并推进
adjust_learning_path	根据反馈调整轨迹
radiate_concept	辐射式探索
get_unexplored_concepts	获取未探索知识点
generate_knowledge_graph	生成完整图谱
plan_learning_path	规划路径
get_prerequisites	获取前置
get_suggested_next	推荐下一步
get_knowledge_gaps	知识缺口
mark_concept_mastered	标记掌握
add_concept / add_dependency	添加知识点/依赖
explain_concept	AI 讲解
ask_question	对话学习
get_graph_info / get_graph_json	图谱信息/导出
load_graph_json	加载图谱
save_state / load_state	保存/加载状态

---

🏗️ 架构 | Architecture

src/nonlinear_learner/
├── cli.py                # CLI + guide 对话导师 + explore 辐射探索
├── core/
│   ├── models.py         # 数据模型 (含 TrajectoryStep, LearningSession)
│   ├── graph.py          # networkx DAG 操作
│   ├── pathfinder.py     # 路径规划 (3 种模式)
│   └── engine.py         # 引擎 + 会话管理 + 辐射 + SQLite
├── llm/
│   └── client.py         # LLM (unpack + guide + adjust + radiate + graph)
└── mcp_server/
    └── server.py         # FastMCP Server (20 工具)

技术栈 | Tech Stack: FastMCP + networkx + pydantic v2 + OpenAI SDK + click + SQLite

---

🧪 测试 | Tests

pip install -e ".[dev]"
pytest tests/ -v

137 个测试覆盖会话管理、辐射学习、数据模型、DAG、路径规划、引擎、LLM 客户端。

---

⚙️ 配置 | Configuration

配置文件 ~/.nonlinear_learner/config.json（由 setup 自动生成）： Config at ~/.nonlinear_learner/config.json (auto-generated by setup):

{
  "endpoint": "https://api.openai.com/v1",
  "api_key": "sk-...",
  "model": "gpt-4o-mini"
}

也支持环境变量 | Also supports env vars: OPENAI_API_KEY, OPENAI_ENDPOINT, OPENAI_MODEL

---

📄 License

MIT