CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

算法学习助手 (Code Learning Agent) - A comprehensive tool suite for algorithm learning that integrates problem scraping and learning statistics. The project consists of three main modules:

luogu_scraper: Scrapes Luogu problem sets, problems, and solutions
leetcode_scraper: Scrapes LeetCode problems and solutions
stats: Generates learning statistics and progress analysis

Commands

Luogu Scraper

cd luogu_scraper

# Install dependencies
pip install -r requirements.txt

# Scrape all official problem sets
python main.py

# Scrape specific problem set by ID
python main.py --training-id 1

# Scrape single problem
python main.py --problem P1001

# Scrape without solutions
python main.py --problem P1001 --no-solutions

# Adjust request delay (avoid rate limiting)
python main.py --training-id 1 --delay 2.0

# Get more solutions per problem
python main.py --problem P1001 --solutions-limit 5

LeetCode Scraper

cd leetcode_scraper

# Install dependencies
pip install -r requirements.txt

# List problems
python main.py --list

# List with limit
python main.py --list --list-limit 20

# Filter by difficulty
python main.py --list --difficulty medium

# Scrape specific problem by slug
python main.py --problem two-sum

# Scrape by problem ID
python main.py --problem-id 146

# Use China site (leetcode.cn)
python main.py --problem two-sum --cn

# NEW: List available problem sources
python main.py --list-sources

# NEW: Scrape problem lists for learning plans
python main.py --scrape-list study-plan:top-interview-150
python main.py --scrape-list company:google --limit 200
python main.py --scrape-list topic:dynamic-programming --limit 100
python main.py --scrape-list difficulty:easy --limit 50
python main.py --scrape-list high-frequency --limit 100

# Save to specific file
python main.py --scrape-list study-plan:leetcode-75 --output-list ../stats/data/leetcode75.json

Learning Plans (NEW)

cd stats

# Create a learning plan
python create_plan.py \
    --name "Interview Prep" \
    --source study-plan:top-interview-150 \
    --start 2026-02-01 \
    --end 2026-03-02 \
    --difficulty-progression \
    --topic-balancing

# List all learning plans
python view_plan.py --list

# View specific plan
python view_plan.py --plan plan_001

# View today's problems
python view_plan.py --plan plan_001 --today

# View progress
python view_plan.py --plan plan_001 --progress

# Export plan to Markdown
python view_plan.py --plan plan_001 --export my_plan.md

# Delete a plan
python view_plan.py --plan plan_001 --delete

# Mark problem as learned (auto-updates plan progress)
python mark_learned.py 1 "Two Sum - Hash table approach"

Learning Statistics

cd stats

# Generate statistics
python generate_stats.py

# View statistics summary
cat data/stats.json | jq '.summary'

# Mark problems as learned
python mark_learned.py

# Start web server to view stats
python serve.py

Architecture

Module Structure

The project follows a modular architecture with three independent scrapers:

luogu_scraper/

main.py: Entry point and orchestration
training_scraper.py: Handles problem set scraping
problem_scraper.py: Handles individual problem scraping
solution_scraper.py: Handles solution scraping
utils.py: Shared utilities (LuoguSession, file operations)
config.py: Configuration (API URLs, headers, delays, cookie)

leetcode_scraper/

main.py: Entry point and orchestration
problem_scraper.py: Handles problem scraping via GraphQL API
solution_scraper.py: Handles solution scraping
list_scraper.py: NEW - Scrapes problem lists (study plans, companies, topics, difficulty)
utils.py: Shared utilities (LeetCodeSession, file operations)
config.py: Configuration (API endpoints, delays, cookie, problem sources)

stats/

generate_stats.py: Main statistics generation script (includes learning plan stats)
mark_learned.py: Helper to mark problems as learned (auto-updates learning plans)
serve.py: Web server for viewing statistics
scheduler.py: NEW - Intelligent problem scheduling algorithm
plan_manager.py: NEW - Learning plan CRUD operations
create_plan.py: NEW - CLI tool to create learning plans
view_plan.py: NEW - CLI tool to view and manage learning plans
data/learning_record.json: Tracks learned problems and daily progress
data/learning_plan.json: NEW - Stores learning plans and schedules
data/stats.json: Generated statistics output (includes plan stats)
templates/plan_template.md: NEW - Markdown template for plan export

Data Flow

Scraping: Scrapers fetch data from Luogu/LeetCode APIs and save to output/ directories
Learning: User manually updates stats/data/learning_record.json after completing problems
Statistics: generate_stats.py scans problem files and merges with learning records to generate comprehensive statistics
Learning Plans (NEW):
- List Scraping: Use leetcode_scraper/list_scraper.py to fetch problem lists from various sources
- Plan Creation: create_plan.py uses scheduler.py to intelligently distribute problems across dates
- Progress Tracking: mark_learned.py automatically updates plan progress when problems are marked as learned
- Plan Management: plan_manager.py handles CRUD operations and progress calculations

Session Management

Both scrapers use session classes (LuoguSession, LeetCodeSession) that:

Manage HTTP requests with proper headers
Handle rate limiting with configurable delays
Support cookie-based authentication
Implement retry logic for failed requests

Output Format

Problems are saved in dual format:

JSON: Structured data for programmatic access
Markdown: Human-readable format for review

Directory structure:

output/
├── trainings/
│   └── {id}_{title}/
│       ├── training_info.json
│       └── problems/
│           └── {pid}/
│               ├── problem.json
│               ├── problem.md
│               ├── solutions.json
│               ├── solution_1.md
│               ├── solution_2.md
│               └── solution_3.md
└── problems/
    └── {id}_{slug}/
        ├── problem.json
        ├── problem.md
        ├── solutions.json
        └── solution_*.md

Configuration

Luogu Cookie Setup

Luogu requires authentication for most content. To configure:

Login to https://www.luogu.com.cn
Open browser DevTools (F12) → Network tab
Refresh page and select any request
Copy the Cookie header value

Edit luogu_scraper/config.py:

COOKIE = '_uid=xxx; __client_id=xxx; ...'

LeetCode Cookie (Optional)

Only needed for premium problems. Same process as Luogu but for leetcode.com or leetcode.cn.

Learning Record Format

The stats/data/learning_record.json file tracks progress:

{
  "learned_problems": {
    "P1001": {
      "learned_at": "2024-01-15",
      "notes": "简单的A+B问题"
    }
  },
  "daily_learning": {
    "2024-01-15": ["P1001"],
    "2024-01-16": ["P1002", "P1003"]
  }
}

Claude Code Skills

This project includes Claude Code skills in .claude/skills/:

code-learning-agent.md: Main skill that orchestrates all functionality
luogu-scraper.md: Luogu-specific operations
leetcode-scraper.md: LeetCode-specific operations
learning-stats.md: Statistics generation

Users can invoke these with natural language like:

"爬取洛谷题单1"
"获取LeetCode的two-sum题目"
"生成学习统计"

Important Notes

Rate Limiting

Both scrapers implement delays to avoid overwhelming servers:

Default delay: 1.5s for Luogu, 1.0s for LeetCode
Adjust with --delay parameter if encountering 403 errors
Respect website terms of service

Error Handling

403 errors usually indicate: expired cookie, rate limiting, or IP ban
Scrapers continue on individual failures and report errors in summary
Check DEBUG = True in config.py for detailed logging

Data Usage

All scraped data is for personal learning only. Do not use for commercial purposes or redistribute.

Statistics Generation

The stats module:

Scans luogu_scraper/examples/categories/ for problem files
Reads learning_record.json for completion status
Generates comprehensive statistics including:
- Overall progress (total/learned/percentage)
- Per-category breakdown
- Tag distribution
- Difficulty distribution
- Daily learning trends

Workflow

Typical Learning Session

Scrape problems: cd luogu_scraper && python main.py --training-id 1
Study problems: Review generated markdown files
Complete problems: Write and test solutions
Record progress: Update stats/data/learning_record.json
View progress: cd stats && python generate_stats.py

Periodic Review

Generate statistics to identify weak areas
Focus on underrepresented tags or difficulties
Review previously completed problems
Update learning records

Learning Plan Feature (NEW)

Overview

The learning plan feature allows users to create personalized study schedules from LeetCode problem lists with intelligent problem distribution.

Supported Problem Sources

Official Study Plans: Top Interview 150, LeetCode 75, SQL 50, etc.
Company Lists: Google, Amazon, Microsoft, Facebook, Apple, etc.
Topic Collections: Dynamic Programming, Trees, Graphs, Arrays, etc.
Difficulty-Based: Easy, Medium, Hard
High-Frequency: Problems sorted by likes/popularity

Creating a Learning Plan

Step 1: Scrape Problem List

cd leetcode_scraper

# List available sources
python main.py --list-sources

# Scrape a study plan
python main.py --scrape-list study-plan:top-interview-150

# Scrape company problems
python main.py --scrape-list company:google --limit 200

# Scrape topic problems
python main.py --scrape-list topic:dynamic-programming --limit 100

Step 2: Create Learning Plan

cd stats

python create_plan.py \
    --name "Interview Prep" \
    --source study-plan:top-interview-150 \
    --start 2026-02-01 \
    --end 2026-03-02 \
    --difficulty-progression \
    --topic-balancing \
    --skip-learned \
    --prioritize-frequency

Configuration Options:

--difficulty-progression: Easy → Medium → Hard progression (default: enabled)
--topic-balancing: Avoid consecutive same-topic problems (default: enabled)
--skip-learned: Skip already completed problems (default: enabled)
--prioritize-frequency: Prioritize high-frequency problems (default: enabled)
--problems-per-day N: Set specific daily problem count (default: auto-calculated)

Scheduling Algorithm

The intelligent scheduler uses a composite scoring system:

Scoring Weights:

Frequency Score (40%): Based on problem likes count
Difficulty Score (30%): Prioritizes easier problems first
Topic Diversity (30%): Ensures varied problem types

Distribution Strategy:

Filter out already learned problems (if enabled)
Calculate composite score for each problem
Sort by score (high-frequency, easy problems first)
Distribute across dates with topic balancing
Avoid consecutive problems with overlapping tags

Managing Learning Plans

View All Plans:

python view_plan.py --list
python view_plan.py --list --status active

View Plan Details:

python view_plan.py --plan plan_001

View Today's Problems:

python view_plan.py --plan plan_001 --today

View Progress:

python view_plan.py --plan plan_001 --progress

Export to Markdown:

python view_plan.py --plan plan_001 --export my_plan.md

Delete Plan:

python view_plan.py --plan plan_001 --delete

Progress Tracking

When you mark a problem as learned, the system automatically updates all active learning plans:

python mark_learned.py 1 "Two Sum - Hash table approach"

Output:

✅ 已标记 1 为已学习
   日期: 2026-01-29
   笔记: Two Sum - Hash table approach

📋 已更新学习计划:
   - Interview Prep

Progress Metrics

The system tracks:

Completion Rate: Percentage of problems completed
Days Elapsed/Remaining: Time tracking
On-Track Status: Whether you're ahead or behind schedule
Expected vs Actual: Comparison of expected and actual progress
Ahead/Behind: Number of problems ahead or behind schedule

Example Workflows

Workflow 1: Interview Preparation (30 days)

# 1. Scrape Top Interview 150
cd leetcode_scraper
python main.py --scrape-list study-plan:top-interview-150

# 2. Create 30-day plan
cd ../stats
python create_plan.py \
    --name "Interview Prep - 30 Days" \
    --source study-plan:top-interview-150 \
    --start 2026-02-01 \
    --end 2026-03-02 \
    --difficulty-progression \
    --topic-balancing

# 3. Daily routine
python view_plan.py --plan plan_001 --today  # View today's problems
# ... solve problems ...
python mark_learned.py 1 "Completed"         # Mark as learned
python view_plan.py --plan plan_001 --progress  # Check progress

# 4. Weekly review
python view_plan.py --plan plan_001 --export week1.md
python generate_stats.py  # Generate overall statistics

Workflow 2: Company-Specific Preparation

# 1. Scrape Google problems
cd leetcode_scraper
python main.py --scrape-list company:google --limit 200

# 2. Create plan with high-frequency priority
cd ../stats
python create_plan.py \
    --name "Google Interview Prep" \
    --source company:google \
    --start 2026-02-01 \
    --end 2026-03-15 \
    --prioritize-frequency \
    --limit 200

# 3. Focus on high-frequency problems first
python view_plan.py --plan plan_002 --today

Workflow 3: Topic Mastery

# 1. Scrape Dynamic Programming problems
cd leetcode_scraper
python main.py --scrape-list topic:dynamic-programming --limit 100

# 2. Create focused plan
cd ../stats
python create_plan.py \
    --name "DP Mastery" \
    --source topic:dynamic-programming \
    --start 2026-02-01 \
    --end 2026-02-28 \
    --difficulty-progression \
    --limit 100

# 3. Systematic learning
python view_plan.py --plan plan_003 --today

Data Files

learning_plan.json Structure:

{
  "plans": {
    "plan_001": {
      "id": "plan_001",
      "name": "Interview Prep",
      "source": "top-interview-150",
      "start_date": "2026-02-01",
      "end_date": "2026-03-02",
      "total_problems": 150,
      "problem_list": [...],
      "schedule": {
        "2026-02-01": {
          "problem_ids": ["1", "20", "21"],
          "completed_count": 0,
          "total_count": 3
        }
      },
      "progress": {
        "completed_problems": 0,
        "completion_rate": 0.0,
        "on_track": true
      }
    }
  }
}

Integration with Existing Features

Automatic Progress Updates: mark_learned.py updates plan progress
Statistics Integration: generate_stats.py includes plan statistics
Learning Records: Plans respect existing learning_record.json
Skip Learned: Plans automatically filter out completed problems

Tips

Start with Easy Plans: Begin with smaller problem sets (50-75 problems) to build momentum
Adjust Daily Load: Use --problems-per-day to match your schedule
Review Regularly: Check progress weekly to stay on track
Export Plans: Use --export to create printable study guides
Multiple Plans: You can have multiple active plans for different goals
Flexible Scheduling: Plans adapt to your actual completion rate

FilesExpand file tree

CLAUDE.md

Latest commit

History

CLAUDE.md

File metadata and controls

CLAUDE.md

Project Overview

Commands

Luogu Scraper

LeetCode Scraper

Learning Plans (NEW)

Learning Statistics

Architecture

Module Structure

Data Flow

Session Management

Output Format

Configuration

Luogu Cookie Setup

LeetCode Cookie (Optional)

Learning Record Format

Claude Code Skills

Important Notes

Rate Limiting

Error Handling

Data Usage

Statistics Generation

Workflow

Typical Learning Session

Periodic Review

Learning Plan Feature (NEW)

Overview

Supported Problem Sources

Creating a Learning Plan

Scheduling Algorithm

Managing Learning Plans

Progress Tracking

Progress Metrics

Example Workflows

Data Files

Integration with Existing Features

Tips