LearnFlow

个人知识与效率协作中枢 — 面向开发者与技术学习者的 AI 知识行动平台。

输入一个学习主题（例如「我要学 MCP」），系统自动聚合资料、提炼知识卡片、生成知识图谱、规划学习路径，并将可执行事项转化为待办计划。

输入主题 / 链接 / RSS
  → 内容发现与抓取
  → AI 摘要与知识融合
  → 知识卡片与知识图谱
  → 学习路径与项目建议
  → 行动任务与日程计划

功能特性

模块	说明
主题研究	输入技术主题、URL 或 RSS，一键生成结构化学习报告
内容发现	推荐高质量资料来源（文档、教程、开源项目等），带质量分
知识卡片	摘要、要点、标签、难度、阅读时长，可收藏
知识图谱	概念 / 工具 / 实践 三层节点关系可视化
学习路径	分阶段学习路线与资源推荐
行动任务	从知识中提取可执行待办与今日计划，支持日历导出
历史记录	最近研究会话持久化到 SQLite，支持回顾

技术栈

层级	技术
前端	React 19 + Vite 7 + TypeScript 5.8（严格模式）
UI 图标	lucide-react
样式	自定义 CSS（frontend/src/styles.css），无 Tailwind
图谱	自定义 SVG + 定位 HTML 按钮（KnowledgeGraph.tsx）
测试	Vitest + jsdom + @testing-library/react
后端	Python FastAPI 0.111 + Pydantic 2 + SQLAlchemy 2（async） + aiosqlite
AI	OpenAI 兼容 chat completions（httpx + JSON mode，默认 StepFun）
数据库	SQLite（backend/hub.db）
接口文档	FastAPI Swagger（/docs）

项目结构

LearnFlow/
├── backend/                # FastAPI 后端
│   ├── app/
│   │   ├── main.py         # 应用入口、CORS、SPA 路由
│   │   ├── config.py       # pydantic-settings
│   │   ├── routers/        # health / research / cards / tasks
│   │   ├── services/       # orchestrator + 6 个 agent 模块 + llm_client
│   │   ├── schemas/        # Pydantic 请求/响应模型
│   │   └── models/         # SQLAlchemy 数据模型与持久化辅助
│   ├── tests/
│   │   └── fixtures/
│   │       └── sample_research_response.json
│   ├── requirements.txt
│   └── .env.example
├── frontend/               # React 前端
│   ├── src/
│   │   ├── App.tsx         # 顶层 state、hash 路由、tab 调度
│   │   ├── components/     # AppHeader / SourcePanel / KnowledgeGraph / InsightPanel / ParticleField
│   │   ├── lib/            # knowledgeModel / mapResearchResponse / graphUtils（含测试）
│   │   ├── api/research.ts
│   │   ├── types/research.ts
│   │   └── styles.css
│   ├── vite.config.ts      # 含 Vitest 配置与 /api 代理
│   └── package.json
├── PRD-个人知识与效率协作中枢.md
└── CLAUDE.md               # 开发说明（AI 协作用）

快速开始

环境要求

• Python 3.10+
• Node.js 18+

1. 启动后端

cd backend
python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt
cp .env.example .env       # Windows: copy .env.example .env
# LLM_API_KEY 必填；留空时研究接口会明确返回 503
uvicorn app.main:app --reload --port 8000

启动后访问 Swagger 文档：http://localhost:8000/docs

2. 启动前端

cd frontend
npm install
npm run dev

前端默认运行在：http://127.0.0.1:5173（已配置 /api 代理到 http://127.0.0.1:8000）。

3. 验证后端

curl http://localhost:8000/api/health

curl -X POST http://localhost:8000/api/research \
  -H "Content-Type: application/json" \
  -d '{"query":"我要学 MCP","mode":"topic","userLevel":"beginner","timeBudgetHours":6}'

环境变量

在 backend/.env 中配置（参考 .env.example）：

变量	说明	默认值
LLM_API_KEY	大模型 API 密钥	空（使用 mock 数据）
LLM_BASE_URL	API 地址	https://api.stepfun.com/step_plan/v1
LLM_MODEL	模型名称	step-3.7-flash
LLM_TIMEOUT	请求超时（秒）	60

可选 TAVILY_API_KEY 启用 content_discovery 的真实网页搜索（默认走 mock）。

未配置 LLM_API_KEY 时，系统自动返回基于关键词的 mock 数据，保证演示可用。

API 概览

方法	路径	说明
GET	/api/health	健康检查
POST	/api/research	主题研究（核心接口）
GET	/api/research/history	最近研究记录（limit 查询参数，上限 50）
POST	/api/cards/{id}/favorite	收藏知识卡片（不存在的 ID 返回 404）
PATCH	/api/tasks/{id}	更新任务状态（todo / doing / done，不存在的 ID 返回 404）

研究请求示例

{
  "query": "我要学 MCP",
  "mode": "topic",
  "userLevel": "beginner",
  "timeBudgetHours": 6
}

研究响应结构

{
  "topic": "MCP",
  "brief": {
    "oneLineSummary": "...",
    "whyLearn": "...",
    "keyTakeaways": ["..."],
    "estimatedTime": "6 小时",
    "nextAction": "..."
  },
  "sources": [],
  "cards": [],
  "graph": { "nodes": [], "edges": [] },
  "learningPath": [],
  "tasks": []
}

开发说明

• 前后端通过 Vite 代理联调（/api → http://127.0.0.1:8000），后端 CORS 已允许 localhost:5173、127.0.0.1:5173、localhost:4173、127.0.0.1:4173、localhost:3000。
• 删除 backend/hub.db 可重置 SQLite 数据库。

一键启动（开发模式）

# macOS / Linux
./scripts/run-dev.sh

# Windows (PowerShell)
.\scripts\run-dev.ps1

会同时拉起后端 8000 + 前端 5173，Ctrl-C 一起停。

Docker（评审 / 演示模式）

cp .env.example .env   # 可选：填入 LLM_API_KEY 启用真实模型
docker compose up --build

打开 http://localhost:5173。后端日志在容器内，前端通过 nginx 反代 /api/* 到 backend 服务。

测试

# 后端（pytest，23 测试）
cd backend && pytest

# 前端（vitest + jsdom，22 测试）
cd frontend && npm test

CI 跑全套测试：.github/workflows/ci.yml。

文档

文件	内容
PRD-个人知识与效率协作中枢.md	产品需求与验收标准
CLAUDE.md	架构决策、扩展清单、踩坑指南
docs/ARCHITECTURE.md	技术选型理由 + 数据流向
docs/API.md	REST 契约（前后端联调参考）
docs/DEMO-SCRIPT.md	5 分钟演示脚本与兜底话术
docs/KNOWN-LIMITATIONS.md	PRD 差距清单 + 实现偏差

License

MIT