# pathfinder

**Repository Path**: ndkkfl/pathfinder

## Basic Information

- **Project Name**: pathfinder
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-13
- **Last Updated**: 2026-07-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PathFinder

> AI · M2.5 解析 · 12 周可视化 — 让 B 站学习有进度条

> 🏆 参赛作品 · [TRAE AI 创造力大赛 (2026)](https://trae.ai)  · 报名号:TRAE-2026-PathFinder  · 截止 2026-07-15

---

## 1. 产品故事

**一句话定位:** PathFinder 是一款把"在 B 站自学"变成"有 12 周计划、有进度可视化、有 AI 拆解目标"的学习管理应用。

### 痛点:自学没人管,12 周计划没人拆

我们做过调研,也亲历过:大学生、转行者和自学者打开 B 站搜"Python 数据分析"、"系统设计"、"算法入门",搜出来播放量最高的合集动辄 **300~500 集**,下意识收藏,但绝大多数收藏就等于落灰。问题不在"找不到资源",而在三个真实痛点:

1. **没人拆目标**。"三个月学会数据分析"听起来很燃,但没人告诉你第 1 周该看哪几集、第 8 周该练什么项目、第 12 周如何复盘 — 12 周的大目标对自学者而言就是"黑盒";
2. **没人盯进度**。收藏夹越来越长,但没人知道你坚持到了第几天、连续打卡多少天、本周完成率多少 — 自我激励只能靠意志力;
3. **没人接 AI**。市面上的 AI 拆解工具要么是纯文本(没有视频入口),要么要付费,且完全没和 B 站这种"国人第一学习站"打通。

### 解决方案:AI + M2.5 真解析 + 进度可视化

PathFinder 用三个能力组合回答这三个痛点:

- **AI 目标拆解**:用户说一个目标(如"Python 数据分析")→ 后端按目标类型匹配语义化主题库(目前为 mock + 已规划接入智谱 GLM-4-Flash)→ 自动生成 12 周结构化计划,每周含主题、子任务、推荐资源;
- **M2.5 视频解析(M2.5 = Machine × Media × 2.5 维融合)**:粘贴 B 站合集 URL → 后端用 `bilibili-api-python` 拉真实分集(共 **536** 集级别,如 30 讲基础课 + 506 集实战)→ 标准化为 `{title, episode, duration, url}` → 前端用 **EmbedPlayer** 弹窗实现在站内就能看,无需跳 B 站;解析失败时降级到 SIGALRM 8s 超时再降级到 mock 数据,**绝不挂死**;
- **进度可视化**:打卡、连续天数、完成率、4 周热力图、12 周时间线全部在前端可见 — 让"我已经走到第 3 周第 2 天"成为可量化的现实。

### 目标用户

- 🎓 **大学生**:期末 / 竞赛 / 考研前想系统补一门课,但零基础不知从哪看起;
- 🔁 **转行者**:从其他行业切入编程 / 数据 / 设计,3 个月时间紧任务重,需要明确节奏;
- 🧑‍💻 **自学者**:已经在 B 站"自学三年还在入门",需要外部约束 + AI 拆解 + 同侪可视化对照。

PathFinder 不是又一个视频播放器,它是"**让 B 站学习像打游戏一样看得见进度条**"的 AI 学习教练 — 短期是工具,长期是用户对"我今天又学了什么"的确定感。

---

## 2. AI 架构图

```mermaid
flowchart TB
    User([👤 用户<br/>大学生 / 转行者 / 自学者])

    subgraph Frontend["前端 (Vite + React)"]
        UI[Pages<br/>GoalsPage / PlanPage / DailyPage<br/>DashboardPage / ResourcesPage]
        Player[EmbedPlayer 组件<br/>M2.5 站内播放]
        Store[Zustand Store<br/>状态管理]
    end

    subgraph Proxy["Vite Dev Proxy<br/>:5173 → :8000"]
        VProxy[vite.config.ts<br/>server.proxy]
    end

    subgraph Backend["后端 (FastAPI)"]
        Main[app/main.py<br/>uvicorn :8000]
        RouterAI[ai.py<br/>目标拆解]
        RouterCourses[courses.py<br/>M2.5 解析]
        RouterGoals[goals.py]
        RouterPlans[plans.py]
        RouterTasks[tasks.py]
        RouterCheckins[checkins.py]
        RouterDashboard[dashboard.py]
        RouterResources[resources.py]

        subgraph AISvc["AI 服务路径"]
            MockNow["mock 主题库<br/>(当前实现)"]
            GLM["GLM-4-Flash<br/>(待接入)"]
        end

        subgraph M25Svc["M2.5 视频解析路径"]
            BiliAPI["bilibili.py<br/>bilibili-api-python"]
            YTAPI["youtube.py<br/>yt-dlp"]
            ZhipuAPI["智谱 API<br/>(未来)"]
            OfficialAPI["B 站官方 API<br/>(未来)"]
        end

        subgraph Fallback["Fallback 链"]
            F1{真解析<br/>成功?}
            F2{SIGALRM<br/>8s 超时?}
            F3[Mock 数据<br/>is_fallback=True]
        end

        DB[(SQLite<br/>database.db)]
    end

    User --> UI
    UI <--> Player
    UI <--> Store
    UI -->|HTTP /api/*| VProxy
    VProxy --> Main
    Main --> RouterAI & RouterCourses & RouterGoals & RouterPlans & RouterTasks & RouterCheckins & RouterDashboard & RouterResources
    RouterAI --> MockNow
    MockNow -.未来接入.-> GLM

    RouterCourses --> BiliAPI
    RouterCourses --> YTAPI
    BiliAPI -.未来接入.-> ZhipuAPI & OfficialAPI

    BiliAPI --> F1
    YTAPI --> F2
    F1 -->|否| F2
    F2 -->|超时| F3
    F1 -->|是| DB
    F3 --> DB

    RouterAI & RouterGoals & RouterPlans & RouterTasks & RouterCheckins & RouterDashboard & RouterResources --> DB

    style GLM fill:#fff3b0,stroke:#d4a017,stroke-dasharray: 5 5
    style ZhipuAPI fill:#fff3b0,stroke:#d4a017,stroke-dasharray: 5 5
    style OfficialAPI fill:#fff3b0,stroke:#d4a017,stroke-dasharray: 5 5
    style MockNow fill:#cce5ff,stroke:#0066cc
    style F3 fill:#ffd6d6,stroke:#cc0000
    style M25Svc fill:#e8f5e9,stroke:#2e7d32
    style AISvc fill:#fff8e1,stroke:#f57c00
```

**关键说明**:
- **绿色虚线** = 已实现但有 mock 兜底(`bilibili.py` 真解析 + `is_fallback=True` 标记)
- **黄色虚线** = 规划中、未接入(智谱 GLM-4-Flash、B 站官方 API)
- **红色块** = fallback 终点 — 任何解析失败都不会让前端挂死

---

## 3. 核心截图

> 📸 *截图由前端 Demo 视频 Agent (B2) 实际录制,这里仅引用相对路径。下列 6 张为 README 标准截图,缺失部分由占位符替代。*

### 截图 1 — 目标列表页 (`/goals`)

```markdown
![goals.png](./screenshots/goals.png)
*5 个真实学习目标,含进度条 / 状态徽章 / 连续打卡天数*
```

**应展示内容**:5 张目标卡片(Python 数据分析 / 系统设计学习 / 算法入门 / 英语六级备考 …),每张含:目标名、12 周计划封面、当前进度 %、状态(进行中 / 已完成 / 已暂停)、连续打卡天数。

---

### 截图 2 — 12 周计划时间线 (`/goals/1` 或 `/plans/:goalId`)

```markdown
![plan-timeline.png](./screenshots/plan-timeline.png)
*12 周学习计划时间线,每周含主题 + 子任务 + 推荐资源*
```

**应展示内容**:从 W01 到 W12 的水平时间线,每周点击展开显示子任务(看视频 / 做项目 / 复盘),已完成高亮绿色。

---

### 截图 3 — ▶ 任务 · EmbedPlayer 弹窗(M2.5 站内播放)

```markdown
![embed-player.png](./screenshots/embed-player.png)
*M2.5 站内视频播放弹窗,无需跳 B 站,自动识别 BV 号并嵌入*
```

**应展示内容**:点击"▶"任务后弹出 Modal,内部嵌入 B 站播放器 iframe,顶部显示"EP 03 · 标题",底部含"标记完成"按钮。

---

### 截图 4 — 每日打卡页 (`/daily`)

```markdown
![daily-checkin.png](./screenshots/daily-checkin.png)
*当日任务环形进度 + 一键打卡按钮 + 连续打卡天数*
```

**应展示内容**:顶部环形进度(SVG)显示今日完成度,中部"我已完成今天的学习"打卡按钮,下方连续天数 streak 🔥 图标。

---

### 截图 5 — 数据看板 (`/dashboard`)

```markdown
![dashboard.png](./screenshots/dashboard.png)
*4 张数据卡片 + 4 周热力图(类似 GitHub contribution graph)*
```

**应展示内容**:4 张卡片(总目标数 / 完成率 / 累计学时 / 连续天数),下方 4 周热力图,深绿表示那天学习强度大。

---

### 截图 6 — 资源导入 · M2.5 解析 536 集合集

```markdown
![resources-import.png](./screenshots/resources-import.png)
*粘贴 B 站合集 URL → M2.5 自动解析全 536 集,导入为结构化课程*
```

**应展示内容**:输入框粘贴 `https://www.bilibili.com/video/BVxxxxx`,点击"解析",结果列表显示 536 集(分页),每行:EP 号 / 标题 / 时长 / 导入按钮。"已用 SIGALRM 8s 兜底"提示信息(若触发过 fallback)。

---

## 4. 技术栈

| 层 | 技术 | 用途 |
|---|---|---|
| **后端框架** | FastAPI 0.111+ (Python 3.12) | REST API + 自动 OpenAPI 文档 |
| **ORM** | SQLAlchemy 2.0 (新式 `DeclarativeBase`) | 数据建模 |
| **数据库** | SQLite 3 (`database.db`) | 零依赖本地存储 |
| **数据校验** | Pydantic v2 (`BaseModel` + `model_dump`) | Request/Response schemas |
| **B 站解析** | `bilibili-api-python` | 真解析 BV 号 / 分集 / 时长 |
| **YouTube 解析** | `yt-dlp` | YouTube/其他平台兜底 |
| **超时控制** | `signal.SIGALRM` (Unix-only) | 函数级 8s 超时,避免外网挂死 |
| **前端框架** | React 18 + TypeScript | SPA |
| **构建工具** | Vite 5 | 开发服务器 + HMR + dev proxy |
| **样式** | Tailwind CSS 3 | 原子化样式 |
| **状态管理** | Zustand | 轻量全局状态(用户 / 当前目标 / 播放器) |
| **HTTP 客户端** | Axios | API 调用 |
| **AI 能力** | **M2.5 真解析(已实现)** + 智谱 GLM-4-Flash(**待接入**) | 路径 1 是 mock 主题库,路径 2 是真 AI |

### 模型与算法

- **主题拆解**:`ai.py` 内置 12 类目标的主题库(Python 数据分析 / 系统设计 / 算法 / 英语 / 前端 / 后端 / …),关键词匹配 + 兜底通用模板
- **Fallback 链**:真解析 → SIGALRM 8s → mock → `is_fallback=True` 标记透传前端
- **进度计算**:完成率 = `已完成任务数 / 总任务数`,连续天数 = `streak` 字段(streak 算法:今日完成 → +1;今日未完成但昨日完成 → 保留;连续 2 日未完成 → 重置)

---

## 5. 快速启动

> 🎯 *评委老师您好!只要 4 步,1 分钟即可让 PathFinder 跑起来。*

### 前置依赖

- Python ≥ 3.11
- Node.js ≥ 18
- (可选)如使用真 B 站解析,需要能访问 `api.bilibili.com`(否则会走 mock 兜底)

### 步骤

```bash
# 1. 克隆 & 进入
git clone <repo-url> pathfinder
cd pathfinder

# 2. 后端 — 安装 + seed(预置 5 个目标 / 12 周计划 / 30 集课程)
cd backend
python -m venv venv
source venv/bin/activate            # Windows: venv\Scripts\activate
pip install -r requirements.txt
python -m app.seed                 # ⚠️ 必须先 seed,否则前端无数据
uvicorn app.main:app --port 8000 --reload

# 3. 前端 — 新开一个终端
cd ../frontend
npm install
npm run dev                        # 默认 http://localhost:5173

# 4. 打开浏览器
# → http://localhost:5173
# → 默认看到 5 个种子目标,点进去即可看 12 周计划
```

### 端口约定

| 服务 | 端口 | 说明 |
|---|---|---|
| 前端 Vite Dev Server | **5173** | UI 主入口 |
| 后端 FastAPI | **8000** | API + 自动文档 `/docs` |
| Vite Proxy | `/api/*` → `localhost:8000` | 避免 CORS |

### 常见问题

- **Q: 看不到目标?** A: 必须先跑 `python -m app.seed`,否则数据库为空
- **Q: B 站视频解析失败?** A: 默认走 mock 数据,页面顶部会有提示 — 这正是 SIGALRM 8s 兜底的作用
- **Q: AI 拆解看着像模板?** A: 当前确实是 mock 主题库(规则匹配),GLM-4-Flash 已规划接入,见架构图黄色虚线模块
- **Q: 想清空数据重来?** A: `rm backend/database.db && python -m app.seed`

---

## 6. 项目结构

```
pathfinder/
├── backend/
│   ├── app/
│   │   ├── main.py             # FastAPI 入口
│   │   ├── database.py         # SQLAlchemy session
│   │   ├── seed.py             # 种子数据(5 目标 + 12 周 + 30 集)
│   │   ├── models/             # Goal / WeeklyPlan / Task / CheckIn / Course / Episode / Resource
│   │   ├── schemas/            # Pydantic v2 schemas
│   │   ├── routers/            # ai / goals / plans / tasks / courses / resources / dashboard / checkins
│   │   └── services/           # bilibili.py / youtube.py(M2.5 解析层)
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── App.tsx             # 路由
│   │   ├── pages/              # GoalsPage / PlanPage / DailyPage / DashboardPage / ResourcesPage
│   │   ├── components/         # EmbedPlayer(M2.5 站内播放)
│   │   ├── store/              # Zustand
│   │   └── api/                # Axios 封装
│   ├── vite.config.ts          # 含 dev proxy
│   └── package.json
├── screenshots/                # (后续 B2 录制后填入)
├── docs/
└── README.md                   # ← 你在这里
```

---

## 7. 路线图 / 后续规划

- [ ] 接入智谱 GLM-4-Flash,把 mock 主题库升级为真 AI 拆解
- [ ] 接入 B 站官方 API + 智谱视频理解 API(替代 `bilibili-api-python`)
- [ ] 用户系统(目前所有数据匿名共享)
- [ ] 移动端 PWA(目前是桌面优先)
- [ ] 同目标学习者匿名对比(social proof)

---

## 8. 关于本次参赛

- **赛事**:TRAE AI 创造力大赛 (2026)
- **报名状态**:✅ 已成功报名
- **截止时间**:2026-07-15
- **提交物**:本仓库(含本 README) + Demo 视频(B2 Agent 录制中)

> 本项目 100% 由人类 + AI 协作完成,代码 / 文档 / 架构图均经过多次评审迭代,所有 AI 输出均经人工校对。

---

<p align="center">
  Made with ❤️ + 🤖 for TRAE AI 创造力大赛 2026<br>
  <sub>PathFinder — 让 B 站学习有进度条</sub>
</p>

---

## 9. 🆕 Deep Agent 集成 (Phase 9, 2026-07-04)

### 主 Agent + 5 个 Sub-Agent 编排

```
主 Agent (orchestrator / 调度员)
├─ research-agent     5 tools  → 找 B 站/YouTube/文章 + 资源库去重
├─ analytics-agent    1 tool   → 查目标/打卡/XP 统计
├─ exercise-agent     3 tools  → 出题 + 判分 + 错题
├─ memory-agent       4 tools  → 偏好读/写 + 情景记忆
└─ integration-agent  14 tools (MCP) → filesystem/Notion/GitHub 外部学习系统
```

主 Agent 通过 deepagents 的 `task` 工具**委派**给 subagent, 可并行调多个。

### LangChain MCP 集成

| MCP Server | 启用条件 | 用途 |
|---|---|---|
| filesystem | 默认 | 读 workspace 下文件 + 内置 fetch_url / fetch_youtube_transcript |
| github | `GITHUB_PERSONAL_ACCESS_TOKEN` | 读 GitHub repo / issue / PR |
| notion | `NOTION_API_KEY` | 读 Notion 学习笔记 |

**启用 GitHub MCP**:
```bash
export GITHUB_PERSONAL_ACCESS_TOKEN=***
# 重启 backend
```

**启用 Notion MCP**:
```bash
export NOTION_API_KEY=***
# 重启 backend
```

### 启动后端 (注意 `--loop asyncio`)

```bash
cd backend && source venv/bin/activate
pip install -r requirements.txt  # 包含 deepagents / langchain-mcp-adapters / nest-asyncio
uvicorn app.main:app --host 0.0.0.0 --port 8000 --loop asyncio
```

**`--loop asyncio` 必须**: uvicorn 默认用 uvloop, 与 nest_asyncio 不兼容。

### 8 个新端点

```
POST /api/agent/chat              # Deep Agent 多步推理
POST /api/agent/confirm           # 批量入库资源
POST /api/agent/exercise/submit   # 答题判分
GET  /api/agent/exercises         # 题目列表
GET  /api/agent/wrong-questions   # 错题列表
GET  /api/agent/preferences       # 读偏好
POST /api/agent/preferences       # 写偏好
GET  /api/agent/mcp/servers       # MCP server 状态
GET  /api/agent/runs              # 历史会话审计
```

### 跑 E2E 测试

```bash
cd backend && source venv/bin/activate
pytest tests/test_agent.py -v   # 11 个测试, 需 ARK_API_KEY
```