From c0a00b647e4ee4c78b9f67c1a03c5d70fc83181b Mon Sep 17 00:00:00 2001
From: J1anYi <pp517462915@gmail.com>
Date: Mon, 20 Apr 2026 10:31:42 +0800
Subject: [PATCH 1/2] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=E5=B0=8F?=
 =?UTF-8?q?=E7=BA=A2=E4=B9=A6=E6=95=B0=E6=8D=AE=E6=9F=A5=E7=9C=8B=E5=99=A8?=
 =?UTF-8?q?=E5=89=8D=E7=AB=AF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

实现了一个简洁的数据查看器前端，用于展示爬取的小红书笔记数据。

功能特性:
- 瀑布流卡片布局（CSS columns 真瀑布流）
- 关键词筛选和标题搜索
- 图片懒加载（Intersection Observer）
- 笔记详情模态框（图片画廊导航）
- 统计面板（笔记数、图片数、关键词分布）
- 实时监控（WebSocket + 5秒轮询）
- 视频类型标识和播放器支持

后端 API:
- GET /api/notes - 获取笔记列表（支持分页、关键词筛选、搜索）
- GET /api/notes/stats - 获取统计数据
- GET /api/notes/{note_id} - 获取笔记详情
- GET /api/notes/keywords - 获取关键词列表

安全改进:
- 添加 note_id 验证防止路径遍历攻击
- 添加输入参数验证（Query validators）
- 改进异常处理（使用更精确的异常类型）
- 添加类型注解
- 支持更多中文数字格式（亿、万、w、k）
---
 api/main.py                 |  13 +-
 api/routers/__init__.py     |   3 +-
 api/routers/notes.py        | 292 +++++++++++++++++
 viewer/static/css/style.css | 602 ++++++++++++++++++++++++++++++++++++
 viewer/static/index.html    | 110 +++++++
 viewer/static/js/api.js     |  46 +++
 viewer/static/js/app.js     | 268 ++++++++++++++++
 viewer/static/js/modal.js   | 209 +++++++++++++
 viewer/static/js/monitor.js | 209 +++++++++++++
 9 files changed, 1750 insertions(+), 2 deletions(-)
 create mode 100644 api/routers/notes.py
 create mode 100644 viewer/static/css/style.css
 create mode 100644 viewer/static/index.html
 create mode 100644 viewer/static/js/api.js
 create mode 100644 viewer/static/js/app.js
 create mode 100644 viewer/static/js/modal.js
 create mode 100644 viewer/static/js/monitor.js

diff --git a/api/main.py b/api/main.py
index 23e90f26b..e7e4af433 100644
--- a/api/main.py
+++ b/api/main.py
@@ -30,7 +30,7 @@
 from fastapi.staticfiles import StaticFiles
 from fastapi.responses import FileResponse
 
-from .routers import crawler_router, data_router, websocket_router
+from .routers import crawler_router, data_router, websocket_router, notes_router
 
 app = FastAPI(
     title="MediaCrawler WebUI API",
@@ -59,6 +59,7 @@
 app.include_router(crawler_router, prefix="/api")
 app.include_router(data_router, prefix="/api")
 app.include_router(websocket_router, prefix="/api")
+app.include_router(notes_router, prefix="/api")
 
 
 @app.get("/")
@@ -182,6 +183,16 @@ async def get_config_options():
     # Mount other static files (e.g., vite.svg)
     app.mount("/static", StaticFiles(directory=WEBUI_DIR), name="webui-static")
 
+# Mount viewer static files
+VIEWER_DIR = os.path.join(os.path.dirname(__file__), "..", "viewer", "static")
+if os.path.exists(VIEWER_DIR):
+    app.mount("/viewer", StaticFiles(directory=VIEWER_DIR, html=True), name="viewer")
+
+# Mount images directory for note images
+IMAGES_DIR = os.path.join(os.path.dirname(__file__), "..", "data", "xhs", "images")
+if os.path.exists(IMAGES_DIR):
+    app.mount("/images", StaticFiles(directory=IMAGES_DIR), name="images")
+
 
 if __name__ == "__main__":
     uvicorn.run(app, host="0.0.0.0", port=8080)
diff --git a/api/routers/__init__.py b/api/routers/__init__.py
index 123cbc066..fb0fc92d4 100644
--- a/api/routers/__init__.py
+++ b/api/routers/__init__.py
@@ -19,5 +19,6 @@
 from .crawler import router as crawler_router
 from .data import router as data_router
 from .websocket import router as websocket_router
+from .notes import router as notes_router
 
-__all__ = ["crawler_router", "data_router", "websocket_router"]
+__all__ = ["crawler_router", "data_router", "websocket_router", "notes_router"]
diff --git a/api/routers/notes.py b/api/routers/notes.py
new file mode 100644
index 000000000..79eff1b94
--- /dev/null
+++ b/api/routers/notes.py
@@ -0,0 +1,292 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) 2025 relakkes@gmail.com
+#
+# This file is part of MediaCrawler project.
+# Repository: https://github.com/NanmiCoder/MediaCrawler/blob/main/api/routers/notes.py
+# GitHub: https://github.com/NanmiCoder
+# Licensed under NON-COMMERCIAL LEARNING LICENSE 1.1
+#
+# 声明：本代码仅供学习和研究目的使用。使用者应遵守以下原则：
+# 1. 不得用于任何商业用途。
+# 2. 使用时应遵守目标平台的使用条款和robots.txt规则。
+# 3. 不得进行大规模爬取或对平台造成运营干扰。
+# 4. 应合理控制请求频率，避免给目标平台带来不必要的负担。
+# 5. 不得用于任何非法或不当的用途。
+#
+# 详细许可条款请参阅项目根目录下的LICENSE文件。
+# 使用本代码即表示您同意遵守上述原则和LICENSE中的所有条款。
+
+import os
+import re
+import json
+import glob
+from pathlib import Path
+from typing import Optional, List, Dict, Any
+from datetime import datetime
+
+from fastapi import APIRouter, HTTPException, Query
+
+router = APIRouter(prefix="/notes", tags=["notes"])
+
+# Data directories
+DATA_DIR = Path(__file__).parent.parent.parent / "data"
+XHS_DATA_DIR = DATA_DIR / "xhs"
+JSONL_DIR = XHS_DATA_DIR / "jsonl"
+IMAGES_DIR = XHS_DATA_DIR / "images"
+
+
+def parse_interaction_count(count_str: str) -> int:
+    """Parse Chinese interaction count format like '1.1万' to integer.
+
+    Supports formats:
+    - Plain numbers: "1234", "1,234"
+    - Chinese units: "1.5万" (15,000), "2亿" (200,000,000)
+    - English units: "1.5w" (15,000), "2k" (2,000)
+    """
+    if not count_str:
+        return 0
+    count_str = str(count_str).strip()
+    try:
+        # Handle Chinese units
+        if "亿" in count_str:
+            num = float(count_str.replace("亿", ""))
+            return int(num * 100_000_000)
+        if "万" in count_str:
+            num = float(count_str.replace("万", ""))
+            return int(num * 10000)
+        # Handle English units
+        lower_str = count_str.lower()
+        if "w" in lower_str:
+            num = float(lower_str.replace("w", ""))
+            return int(num * 10000)
+        if "k" in lower_str:
+            num = float(lower_str.replace("k", ""))
+            return int(num * 1000)
+        # Plain number
+        clean_str = count_str.replace("+", "").replace(",", "")
+        return int(float(clean_str))
+    except (ValueError, AttributeError, TypeError):
+        return 0
+
+
+# Valid note_id pattern: alphanumeric with underscores and hyphens
+NOTE_ID_PATTERN = re.compile(r'^[a-zA-Z0-9_-]+$')
+
+
+def validate_note_id(note_id: str) -> bool:
+    """Validate note_id to prevent path traversal attacks."""
+    if not note_id or len(note_id) > 64:
+        return False
+    return bool(NOTE_ID_PATTERN.match(note_id))
+
+
+def get_local_image_count(note_id: str) -> int:
+    """Get the count of local images for a note.
+
+    Args:
+        note_id: The note identifier (validated before use)
+
+    Returns:
+        Number of image files found, or 0 if directory doesn't exist
+    """
+    # Validate note_id to prevent path traversal
+    if not validate_note_id(note_id):
+        return 0
+
+    note_image_dir = IMAGES_DIR / note_id
+
+    # Ensure path is within IMAGES_DIR (additional safety check)
+    try:
+        note_image_dir.resolve().relative_to(IMAGES_DIR.resolve())
+    except (ValueError, OSError):
+        return 0
+
+    if not note_image_dir.exists():
+        return 0
+
+    # Count image files using a single iteration
+    count = 0
+    try:
+        for f in note_image_dir.iterdir():
+            if f.suffix.lower() in ('.jpg', '.jpeg', '.webp', '.png'):
+                count += 1
+    except OSError:
+        return 0
+    return count
+
+
+def read_jsonl_files() -> List[Dict[str, Any]]:
+    """Read all JSONL files and return list of notes.
+
+    Returns:
+        List of note dictionaries sorted by time (newest first)
+    """
+    notes: List[Dict[str, Any]] = []
+
+    if not JSONL_DIR.exists():
+        return notes
+
+    # Find all JSONL files
+    try:
+        jsonl_files = list(JSONL_DIR.glob("*.jsonl"))
+    except OSError:
+        return notes
+
+    for jsonl_file in jsonl_files:
+        try:
+            with open(jsonl_file, "r", encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        note = json.loads(line)
+                        # Add local image count
+                        note["local_image_count"] = get_local_image_count(note.get("note_id", ""))
+                        notes.append(note)
+                    except json.JSONDecodeError:
+                        # Skip malformed JSON lines
+                        continue
+        except (OSError, IOError):
+            # Skip files that cannot be read
+            continue
+
+    # Sort by time (newest first), handle None/0 values explicitly
+    notes.sort(key=lambda x: x.get("time") or 0, reverse=True)
+
+    return notes
+
+
+def format_note_for_response(note: Dict[str, Any]) -> Dict[str, Any]:
+    """Format a note for API response"""
+    note_id = note.get("note_id", "")
+    local_image_count = note.get("local_image_count", 0)
+
+    return {
+        "note_id": note_id,
+        "type": note.get("type", "normal"),
+        "title": note.get("title", ""),
+        "desc": note.get("desc", ""),
+        "nickname": note.get("nickname", ""),
+        "avatar": note.get("avatar", ""),
+        "liked_count": note.get("liked_count", "0"),
+        "liked_count_num": parse_interaction_count(note.get("liked_count", "0")),
+        "collected_count": note.get("collected_count", "0"),
+        "collected_count_num": parse_interaction_count(note.get("collected_count", "0")),
+        "comment_count": note.get("comment_count", "0"),
+        "share_count": note.get("share_count", "0"),
+        "tag_list": note.get("tag_list", "").split(",") if note.get("tag_list") else [],
+        "source_keyword": note.get("source_keyword", ""),
+        "note_url": note.get("note_url", ""),
+        "time": note.get("time", 0),
+        "image_count": local_image_count,
+        "first_image_url": f"/images/{note_id}/0.jpg" if local_image_count > 0 else None,
+        "video_url": note.get("video_url", ""),
+    }
+
+
+@router.get("")
+async def list_notes(
+    keyword: Optional[str] = Query(None, max_length=50, description="Filter by source keyword"),
+    search: Optional[str] = Query(None, max_length=100, description="Search in title"),
+    offset: int = Query(0, ge=0, le=10000, description="Pagination offset"),
+    limit: int = Query(100, ge=1, le=500, description="Number of results")
+) -> Dict[str, Any]:
+    """Get list of notes with optional filtering"""
+    notes = read_jsonl_files()
+
+    # Filter by keyword (source_keyword)
+    if keyword:
+        keyword_lower = keyword.lower()
+        notes = [n for n in notes if keyword_lower in (n.get("source_keyword", "") or "").lower()]
+
+    # Filter by search text (title)
+    if search:
+        search_lower = search.lower()
+        notes = [n for n in notes if search_lower in (n.get("title", "") or "").lower()]
+
+    # Apply pagination
+    total = len(notes)
+    notes = notes[offset:offset + limit]
+
+    # Format response
+    formatted_notes = [format_note_for_response(n) for n in notes]
+
+    return {
+        "notes": formatted_notes,
+        "total": total,
+        "offset": offset,
+        "limit": limit
+    }
+
+
+@router.get("/stats")
+async def get_notes_stats() -> Dict[str, Any]:
+    """Get notes statistics"""
+    notes = read_jsonl_files()
+
+    # Calculate statistics
+    total_notes = len(notes)
+    total_images = 0
+    keywords_stats = {}
+
+    for note in notes:
+        # Count images
+        total_images += note.get("local_image_count", 0)
+
+        # Count by keyword
+        keyword = note.get("source_keyword", "unknown")
+        if keyword:
+            keywords_stats[keyword] = keywords_stats.get(keyword, 0) + 1
+
+    # Get recent notes (last 5)
+    recent_notes = [format_note_for_response(n) for n in notes[:5]]
+
+    return {
+        "total_notes": total_notes,
+        "total_images": total_images,
+        "keywords_stats": keywords_stats,
+        "recent_notes": recent_notes,
+        "last_updated": datetime.now().isoformat()
+    }
+
+
+@router.get("/{note_id}")
+async def get_note_detail(note_id: str) -> Dict[str, Any]:
+    """Get single note detail by ID."""
+    # Validate note_id to prevent path traversal
+    if not validate_note_id(note_id):
+        raise HTTPException(status_code=400, detail="Invalid note ID format")
+
+    notes = read_jsonl_files()
+
+    for note in notes:
+        if note.get("note_id") == note_id:
+            formatted = format_note_for_response(note)
+
+            # Add all local image URLs
+            local_image_count = note.get("local_image_count", 0)
+            formatted["image_urls"] = [
+                f"/images/{note_id}/{i}.jpg"
+                for i in range(local_image_count)
+            ]
+
+            return formatted
+
+    raise HTTPException(status_code=404, detail="Note not found")
+
+
+@router.get("/keywords")
+async def get_keywords() -> Dict[str, Any]:
+    """Get list of unique keywords"""
+    notes = read_jsonl_files()
+
+    keywords = set()
+    for note in notes:
+        keyword = note.get("source_keyword")
+        if keyword:
+            keywords.add(keyword)
+
+    return {
+        "keywords": sorted(list(keywords))
+    }
diff --git a/viewer/static/css/style.css b/viewer/static/css/style.css
new file mode 100644
index 000000000..f1d718ade
--- /dev/null
+++ b/viewer/static/css/style.css
@@ -0,0 +1,602 @@
+/* 小红书数据查看器样式 */
+
+:root {
+    --primary-color: #ff2442;
+    --primary-light: #ff6b81;
+    --bg-color: #f5f5f5;
+    --card-bg: #ffffff;
+    --text-primary: #333333;
+    --text-secondary: #666666;
+    --text-muted: #999999;
+    --border-color: #eee;
+    --shadow: 0 2px 12px rgba(0, 0, 0, 0.1);
+    --shadow-hover: 0 4px 20px rgba(0, 0, 0, 0.15);
+}
+
+* {
+    margin: 0;
+    padding: 0;
+    box-sizing: border-box;
+}
+
+body {
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+    background-color: var(--bg-color);
+    color: var(--text-primary);
+    min-height: 100vh;
+}
+
+/* 头部导航 */
+.header {
+    position: sticky;
+    top: 0;
+    z-index: 100;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 12px 24px;
+    background: var(--card-bg);
+    border-bottom: 1px solid var(--border-color);
+    box-shadow: var(--shadow);
+}
+
+.header-left {
+    flex: 0 0 auto;
+}
+
+.logo {
+    font-size: 20px;
+    font-weight: 600;
+    color: var(--primary-color);
+}
+
+.header-center {
+    flex: 1;
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    max-width: 500px;
+    margin: 0 24px;
+}
+
+.filter-select {
+    padding: 8px 12px;
+    border: 1px solid var(--border-color);
+    border-radius: 8px;
+    font-size: 14px;
+    background: var(--card-bg);
+    cursor: pointer;
+    min-width: 140px;
+}
+
+.search-input {
+    flex: 1;
+    padding: 8px 16px;
+    border: 1px solid var(--border-color);
+    border-radius: 20px;
+    font-size: 14px;
+    outline: none;
+    transition: border-color 0.2s;
+}
+
+.search-input:focus {
+    border-color: var(--primary-color);
+}
+
+.header-right {
+    flex: 0 0 auto;
+    display: flex;
+    align-items: center;
+    gap: 16px;
+}
+
+.refresh-btn {
+    display: flex;
+    align-items: center;
+    gap: 4px;
+    padding: 8px 16px;
+    background: var(--primary-color);
+    color: white;
+    border: none;
+    border-radius: 8px;
+    cursor: pointer;
+    font-size: 14px;
+    transition: background 0.2s;
+}
+
+.refresh-btn:hover {
+    background: var(--primary-light);
+}
+
+.refresh-btn.loading .refresh-icon {
+    animation: spin 1s linear infinite;
+}
+
+@keyframes spin {
+    from { transform: rotate(0deg); }
+    to { transform: rotate(360deg); }
+}
+
+.last-update {
+    font-size: 12px;
+    color: var(--text-muted);
+}
+
+/* 监控面板 */
+.monitor-panel {
+    display: flex;
+    align-items: center;
+    gap: 24px;
+    padding: 12px 24px;
+    background: var(--card-bg);
+    border-bottom: 1px solid var(--border-color);
+}
+
+.status-card {
+    display: flex;
+    align-items: center;
+}
+
+.status-indicator {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    padding: 6px 12px;
+    border-radius: 20px;
+    background: #f0f0f0;
+}
+
+.status-indicator.running {
+    background: #e8f5e9;
+}
+
+.status-indicator.running .status-dot {
+    background: #4caf50;
+    animation: pulse 2s infinite;
+}
+
+.status-indicator.stopped .status-dot {
+    background: #9e9e9e;
+}
+
+.status-dot {
+    width: 10px;
+    height: 10px;
+    border-radius: 50%;
+    background: #ccc;
+}
+
+@keyframes pulse {
+    0%, 100% { opacity: 1; }
+    50% { opacity: 0.5; }
+}
+
+.status-text {
+    font-size: 14px;
+    font-weight: 500;
+}
+
+.stats-cards {
+    display: flex;
+    gap: 16px;
+}
+
+.stat-card {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    padding: 8px 20px;
+    background: linear-gradient(135deg, #fff5f5 0%, #fff 100%);
+    border-radius: 12px;
+    min-width: 80px;
+}
+
+.stat-value {
+    font-size: 24px;
+    font-weight: 700;
+    color: var(--primary-color);
+}
+
+.stat-label {
+    font-size: 12px;
+    color: var(--text-muted);
+}
+
+.keywords-stats {
+    flex: 1;
+    display: flex;
+    gap: 8px;
+    flex-wrap: wrap;
+}
+
+.keyword-tag {
+    padding: 4px 12px;
+    background: #f5f5f5;
+    border-radius: 16px;
+    font-size: 12px;
+    color: var(--text-secondary);
+}
+
+.keyword-tag span {
+    font-weight: 600;
+    color: var(--primary-color);
+}
+
+/* 主内容区 */
+.main-content {
+    padding: 24px;
+    min-height: calc(100vh - 200px);
+}
+
+/* 瀑布流布局 */
+.note-grid {
+    column-count: 4;
+    column-gap: 16px;
+}
+
+@media (max-width: 1400px) {
+    .note-grid { column-count: 3; }
+}
+
+@media (max-width: 1000px) {
+    .note-grid { column-count: 2; }
+    .header-center { max-width: 300px; }
+}
+
+@media (max-width: 700px) {
+    .note-grid { column-count: 1; }
+    .header {
+        flex-wrap: wrap;
+        gap: 12px;
+    }
+    .header-center {
+        order: 3;
+        width: 100%;
+        max-width: none;
+        margin: 0;
+    }
+    .monitor-panel {
+        flex-wrap: wrap;
+    }
+}
+
+/* 笔记卡片 */
+.note-card {
+    break-inside: avoid;
+    margin-bottom: 16px;
+    background: var(--card-bg);
+    border-radius: 12px;
+    overflow: hidden;
+    box-shadow: var(--shadow);
+    cursor: pointer;
+    transition: transform 0.2s, box-shadow 0.2s;
+}
+
+.note-card:hover {
+    transform: translateY(-4px);
+    box-shadow: var(--shadow-hover);
+}
+
+.note-card-image {
+    width: 100%;
+    aspect-ratio: 3/4;
+    object-fit: cover;
+    background: #f5f5f5;
+}
+
+.note-card-image.lazy {
+    opacity: 0;
+    transition: opacity 0.3s;
+}
+
+.note-card-image.loaded {
+    opacity: 1;
+}
+
+.note-card-placeholder {
+    width: 100%;
+    aspect-ratio: 3/4;
+    background: linear-gradient(135deg, #f5f5f5 0%, #e0e0e0 100%);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    color: var(--text-muted);
+    font-size: 48px;
+}
+
+.note-card-content {
+    padding: 12px;
+}
+
+.note-card-title {
+    font-size: 14px;
+    font-weight: 500;
+    line-height: 1.4;
+    color: var(--text-primary);
+    display: -webkit-box;
+    -webkit-line-clamp: 2;
+    -webkit-box-orient: vertical;
+    overflow: hidden;
+    margin-bottom: 8px;
+}
+
+.note-card-meta {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    font-size: 12px;
+    color: var(--text-muted);
+}
+
+.note-card-author {
+    display: flex;
+    align-items: center;
+    gap: 4px;
+    overflow: hidden;
+}
+
+.note-card-author img {
+    width: 20px;
+    height: 20px;
+    border-radius: 50%;
+    object-fit: cover;
+}
+
+.note-card-author span {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+.note-card-stats {
+    display: flex;
+    gap: 8px;
+}
+
+.note-card-stats span {
+    display: flex;
+    align-items: center;
+    gap: 2px;
+}
+
+/* 空状态 */
+.empty-state {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    padding: 80px 20px;
+    text-align: center;
+}
+
+.empty-icon {
+    font-size: 64px;
+    margin-bottom: 16px;
+}
+
+.empty-text {
+    font-size: 18px;
+    color: var(--text-secondary);
+    margin-bottom: 8px;
+}
+
+.empty-hint {
+    font-size: 14px;
+    color: var(--text-muted);
+}
+
+/* 加载状态 */
+.loading-state {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    padding: 80px 20px;
+}
+
+.loading-spinner {
+    width: 40px;
+    height: 40px;
+    border: 3px solid var(--border-color);
+    border-top-color: var(--primary-color);
+    border-radius: 50%;
+    animation: spin 1s linear infinite;
+    margin-bottom: 16px;
+}
+
+/* 模态框 */
+.modal {
+    position: fixed;
+    top: 0;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    z-index: 1000;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+
+.modal-overlay {
+    position: absolute;
+    top: 0;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    background: rgba(0, 0, 0, 0.6);
+}
+
+.modal-content {
+    position: relative;
+    width: 90%;
+    max-width: 800px;
+    max-height: 90vh;
+    background: var(--card-bg);
+    border-radius: 16px;
+    overflow: hidden;
+    display: flex;
+    flex-direction: column;
+}
+
+.modal-close {
+    position: absolute;
+    top: 12px;
+    right: 12px;
+    width: 32px;
+    height: 32px;
+    border: none;
+    background: rgba(0, 0, 0, 0.5);
+    color: white;
+    font-size: 24px;
+    border-radius: 50%;
+    cursor: pointer;
+    z-index: 10;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+
+.modal-body {
+    display: flex;
+    flex-direction: column;
+    overflow-y: auto;
+}
+
+/* 图片画廊 */
+.image-gallery {
+    position: relative;
+    background: #000;
+}
+
+.gallery-main {
+    position: relative;
+    width: 100%;
+    aspect-ratio: 4/3;
+}
+
+.gallery-main img {
+    width: 100%;
+    height: 100%;
+    object-fit: contain;
+}
+
+.gallery-nav {
+    position: absolute;
+    top: 50%;
+    transform: translateY(-50%);
+    width: 40px;
+    height: 40px;
+    border: none;
+    background: rgba(255, 255, 255, 0.8);
+    color: #333;
+    font-size: 24px;
+    border-radius: 50%;
+    cursor: pointer;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+
+.gallery-prev {
+    left: 12px;
+}
+
+.gallery-next {
+    right: 12px;
+}
+
+.gallery-info {
+    padding: 8px;
+    text-align: center;
+    color: white;
+    font-size: 14px;
+    background: rgba(0, 0, 0, 0.5);
+}
+
+/* 笔记内容 */
+.note-content {
+    padding: 20px;
+}
+
+.note-content .note-title {
+    font-size: 18px;
+    font-weight: 600;
+    margin-bottom: 12px;
+    line-height: 1.4;
+}
+
+.note-meta {
+    display: flex;
+    gap: 16px;
+    margin-bottom: 12px;
+    font-size: 14px;
+    color: var(--text-muted);
+}
+
+.note-stats {
+    display: flex;
+    gap: 16px;
+    margin-bottom: 16px;
+    padding-bottom: 16px;
+    border-bottom: 1px solid var(--border-color);
+}
+
+.stat-item {
+    font-size: 14px;
+    color: var(--text-secondary);
+}
+
+.note-tags {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 8px;
+    margin-bottom: 16px;
+}
+
+.note-tag {
+    padding: 4px 12px;
+    background: #fff5f5;
+    color: var(--primary-color);
+    border-radius: 16px;
+    font-size: 12px;
+    cursor: pointer;
+    transition: background 0.2s;
+}
+
+.note-tag:hover {
+    background: #ffe0e0;
+}
+
+.note-desc {
+    font-size: 14px;
+    line-height: 1.6;
+    color: var(--text-secondary);
+    white-space: pre-wrap;
+    word-break: break-word;
+    margin-bottom: 16px;
+    max-height: 200px;
+    overflow-y: auto;
+}
+
+.note-link {
+    display: inline-block;
+    color: var(--primary-color);
+    text-decoration: none;
+    font-size: 14px;
+}
+
+.note-link:hover {
+    text-decoration: underline;
+}
+
+/* 视频标识 */
+.video-badge {
+    position: absolute;
+    top: 8px;
+    right: 8px;
+    background: rgba(0, 0, 0, 0.7);
+    color: white;
+    padding: 4px 8px;
+    border-radius: 4px;
+    font-size: 12px;
+}
diff --git a/viewer/static/index.html b/viewer/static/index.html
new file mode 100644
index 000000000..34e5d9a41
--- /dev/null
+++ b/viewer/static/index.html
@@ -0,0 +1,110 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>小红书数据查看器</title>
+    <link rel="stylesheet" href="/viewer/css/style.css">
+</head>
+<body>
+    <!-- 顶部导航栏 -->
+    <header class="header">
+        <div class="header-left">
+            <h1 class="logo">📚 小红书数据查看器</h1>
+        </div>
+        <div class="header-center">
+            <select id="keywordFilter" class="filter-select">
+                <option value="">全部关键词</option>
+            </select>
+            <input type="text" id="searchInput" class="search-input" placeholder="搜索笔记标题...">
+        </div>
+        <div class="header-right">
+            <button id="refreshBtn" class="refresh-btn" title="刷新数据">
+                <span class="refresh-icon">🔄</span>
+                <span class="refresh-text">刷新</span>
+            </button>
+            <span id="lastUpdate" class="last-update"></span>
+        </div>
+    </header>
+
+    <!-- 监控面板 -->
+    <div class="monitor-panel">
+        <div class="status-card">
+            <div class="status-indicator" id="statusIndicator">
+                <span class="status-dot"></span>
+                <span class="status-text">加载中...</span>
+            </div>
+        </div>
+        <div class="stats-cards">
+            <div class="stat-card">
+                <span class="stat-value" id="totalNotes">0</span>
+                <span class="stat-label">笔记总数</span>
+            </div>
+            <div class="stat-card">
+                <span class="stat-value" id="totalImages">0</span>
+                <span class="stat-label">图片总数</span>
+            </div>
+        </div>
+        <div class="keywords-stats" id="keywordsStats"></div>
+    </div>
+
+    <!-- 笔记列表 -->
+    <main class="main-content">
+        <div id="notesGrid" class="note-grid">
+            <!-- 笔记卡片将通过 JS 动态插入 -->
+        </div>
+        <div id="emptyState" class="empty-state" style="display: none;">
+            <div class="empty-icon">📭</div>
+            <p class="empty-text">暂无数据</p>
+            <p class="empty-hint">请先运行爬虫获取数据</p>
+        </div>
+        <div id="loadingState" class="loading-state">
+            <div class="loading-spinner"></div>
+            <p>加载中...</p>
+        </div>
+    </main>
+
+    <!-- 详情模态框 -->
+    <div id="noteModal" class="modal" style="display: none;">
+        <div class="modal-overlay"></div>
+        <div class="modal-content">
+            <button class="modal-close" id="modalClose">&times;</button>
+            <div class="modal-body">
+                <!-- 图片画廊 -->
+                <div class="image-gallery" id="imageGallery">
+                    <div class="gallery-main">
+                        <img id="galleryImage" src="" alt="">
+                        <button class="gallery-nav gallery-prev" id="galleryPrev" style="display: none;">‹</button>
+                        <button class="gallery-nav gallery-next" id="galleryNext" style="display: none;">›</button>
+                    </div>
+                    <div class="gallery-info">
+                        <span id="galleryIndex">1/1</span>
+                    </div>
+                </div>
+                <!-- 笔记内容 -->
+                <div class="note-content">
+                    <h2 class="note-title" id="modalTitle"></h2>
+                    <div class="note-meta">
+                        <span class="note-author" id="modalAuthor"></span>
+                        <span class="note-time" id="modalTime"></span>
+                    </div>
+                    <div class="note-stats">
+                        <span class="stat-item">👍 <span id="modalLikes">0</span></span>
+                        <span class="stat-item">⭐ <span id="modalCollects">0</span></span>
+                        <span class="stat-item">💬 <span id="modalComments">0</span></span>
+                        <span class="stat-item">🔗 <span id="modalShares">0</span></span>
+                    </div>
+                    <div class="note-tags" id="modalTags"></div>
+                    <div class="note-desc" id="modalDesc"></div>
+                    <a class="note-link" id="modalLink" href="" target="_blank">查看原笔记 →</a>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <script src="/viewer/js/api.js"></script>
+    <script src="/viewer/js/app.js"></script>
+    <script src="/viewer/js/modal.js"></script>
+    <script src="/viewer/js/monitor.js"></script>
+</body>
+</html>
diff --git a/viewer/static/js/api.js b/viewer/static/js/api.js
new file mode 100644
index 000000000..3ef894ff4
--- /dev/null
+++ b/viewer/static/js/api.js
@@ -0,0 +1,46 @@
+// API 调用封装
+
+const API = {
+    baseUrl: '/api',
+
+    // 获取笔记列表
+    async getNotes(params = {}) {
+        const query = new URLSearchParams();
+        if (params.keyword) query.append('keyword', params.keyword);
+        if (params.search) query.append('search', params.search);
+        if (params.offset) query.append('offset', params.offset);
+        if (params.limit) query.append('limit', params.limit);
+
+        const response = await fetch(`${this.baseUrl}/notes?${query}`);
+        if (!response.ok) throw new Error('Failed to fetch notes');
+        return response.json();
+    },
+
+    // 获取笔记统计
+    async getStats() {
+        const response = await fetch(`${this.baseUrl}/notes/stats`);
+        if (!response.ok) throw new Error('Failed to fetch stats');
+        return response.json();
+    },
+
+    // 获取笔记详情
+    async getNoteDetail(noteId) {
+        const response = await fetch(`${this.baseUrl}/notes/${noteId}`);
+        if (!response.ok) throw new Error('Failed to fetch note detail');
+        return response.json();
+    },
+
+    // 获取关键词列表
+    async getKeywords() {
+        const response = await fetch(`${this.baseUrl}/notes/keywords`);
+        if (!response.ok) throw new Error('Failed to fetch keywords');
+        return response.json();
+    },
+
+    // 获取爬虫状态
+    async getCrawlerStatus() {
+        const response = await fetch(`${this.baseUrl}/crawler/status`);
+        if (!response.ok) throw new Error('Failed to fetch crawler status');
+        return response.json();
+    }
+};
diff --git a/viewer/static/js/app.js b/viewer/static/js/app.js
new file mode 100644
index 000000000..06f199dd6
--- /dev/null
+++ b/viewer/static/js/app.js
@@ -0,0 +1,268 @@
+// 主应用逻辑
+
+let allNotes = [];
+let currentKeyword = '';
+let currentSearch = '';
+let refreshTimeout = null;
+
+// DOM 元素
+const notesGrid = document.getElementById('notesGrid');
+const emptyState = document.getElementById('emptyState');
+const loadingState = document.getElementById('loadingState');
+const keywordFilter = document.getElementById('keywordFilter');
+const searchInput = document.getElementById('searchInput');
+const refreshBtn = document.getElementById('refreshBtn');
+const lastUpdate = document.getElementById('lastUpdate');
+
+// 初始化
+document.addEventListener('DOMContentLoaded', async () => {
+    try {
+        await loadKeywords();
+        await loadNotes();
+        setupEventListeners();
+        setupLazyLoading();
+    } catch (error) {
+        console.error('初始化失败:', error);
+        showError('加载数据失败，请刷新页面重试');
+    }
+});
+
+// 加载关键词列表
+async function loadKeywords() {
+    try {
+        const data = await API.getKeywords();
+        keywordFilter.innerHTML = '<option value="">全部关键词</option>';
+        data.keywords.forEach(keyword => {
+            const option = document.createElement('option');
+            option.value = keyword;
+            option.textContent = keyword;
+            keywordFilter.appendChild(option);
+        });
+    } catch (error) {
+        console.error('加载关键词失败:', error);
+    }
+}
+
+// 加载笔记数据
+async function loadNotes() {
+    showLoading(true);
+
+    try {
+        const params = {};
+        if (currentKeyword) params.keyword = currentKeyword;
+        if (currentSearch) params.search = currentSearch;
+
+        const data = await API.getNotes(params);
+        allNotes = data.notes;
+
+        renderNotes(allNotes);
+        updateLastUpdate();
+    } catch (error) {
+        console.error('加载笔记失败:', error);
+        showError('加载笔记数据失败');
+    } finally {
+        showLoading(false);
+    }
+}
+
+// 渲染笔记列表
+function renderNotes(notes) {
+    notesGrid.innerHTML = '';
+
+    if (notes.length === 0) {
+        emptyState.style.display = 'flex';
+        return;
+    }
+
+    emptyState.style.display = 'none';
+
+    notes.forEach(note => {
+        const card = createNoteCard(note);
+        notesGrid.appendChild(card);
+    });
+
+    // 触发懒加载
+    triggerLazyLoad();
+}
+
+// 创建笔记卡片
+function createNoteCard(note) {
+    const card = document.createElement('div');
+    card.className = 'note-card';
+    card.dataset.noteId = note.note_id;
+
+    // 图片区域
+    const imageContainer = document.createElement('div');
+    imageContainer.style.position = 'relative';
+
+    if (note.first_image_url) {
+        const img = document.createElement('img');
+        img.className = 'note-card-image lazy';
+        img.dataset.src = note.first_image_url;
+        img.alt = note.title;
+        img.onerror = () => {
+            img.style.display = 'none';
+            const placeholder = document.createElement('div');
+            placeholder.className = 'note-card-placeholder';
+            placeholder.textContent = '🖼️';
+            imageContainer.appendChild(placeholder);
+        };
+        imageContainer.appendChild(img);
+    } else {
+        const placeholder = document.createElement('div');
+        placeholder.className = 'note-card-placeholder';
+        placeholder.textContent = note.type === 'video' ? '🎬' : '📝';
+        imageContainer.appendChild(placeholder);
+    }
+
+    // 视频标识
+    if (note.type === 'video') {
+        const badge = document.createElement('span');
+        badge.className = 'video-badge';
+        badge.textContent = '🎬 视频';
+        imageContainer.appendChild(badge);
+    }
+
+    card.appendChild(imageContainer);
+
+    // 内容区域
+    const content = document.createElement('div');
+    content.className = 'note-card-content';
+
+    const title = document.createElement('h3');
+    title.className = 'note-card-title';
+    title.textContent = note.title || '无标题';
+    content.appendChild(title);
+
+    const meta = document.createElement('div');
+    meta.className = 'note-card-meta';
+
+    const author = document.createElement('div');
+    author.className = 'note-card-author';
+    if (note.avatar) {
+        const avatar = document.createElement('img');
+        avatar.src = note.avatar;
+        avatar.onerror = () => avatar.style.display = 'none';
+        author.appendChild(avatar);
+    }
+    const authorName = document.createElement('span');
+    authorName.textContent = note.nickname || '匿名用户';
+    author.appendChild(authorName);
+    meta.appendChild(author);
+
+    const stats = document.createElement('div');
+    stats.className = 'note-card-stats';
+
+    const likes = document.createElement('span');
+    likes.textContent = `👍 ${formatCount(note.liked_count)}`;
+    stats.appendChild(likes);
+
+    const collects = document.createElement('span');
+    collects.textContent = `⭐ ${formatCount(note.collected_count)}`;
+    stats.appendChild(collects);
+
+    meta.appendChild(stats);
+    content.appendChild(meta);
+    card.appendChild(content);
+
+    // 点击事件
+    card.addEventListener('click', () => openNoteModal(note));
+
+    return card;
+}
+
+// 格式化数量显示
+function formatCount(count) {
+    if (!count) return '0';
+    return count;
+}
+
+// 设置事件监听
+function setupEventListeners() {
+    // 关键词筛选
+    keywordFilter.addEventListener('change', (e) => {
+        currentKeyword = e.target.value;
+        loadNotes();
+    });
+
+    // 搜索（防抖）
+    let searchTimeout;
+    searchInput.addEventListener('input', (e) => {
+        clearTimeout(searchTimeout);
+        searchTimeout = setTimeout(() => {
+            currentSearch = e.target.value.trim();
+            loadNotes();
+        }, 300);
+    });
+
+    // 刷新按钮
+    refreshBtn.addEventListener('click', async () => {
+        refreshBtn.classList.add('loading');
+        await loadNotes();
+        refreshBtn.classList.remove('loading');
+    });
+}
+
+// 设置懒加载
+function setupLazyLoading() {
+    if ('IntersectionObserver' in window) {
+        window.lazyObserver = new IntersectionObserver((entries) => {
+            entries.forEach(entry => {
+                if (entry.isIntersecting) {
+                    const img = entry.target;
+                    if (img.dataset.src) {
+                        img.src = img.dataset.src;
+                        img.onload = () => img.classList.add('loaded');
+                        window.lazyObserver.unobserve(img);
+                    }
+                }
+            });
+        }, {
+            rootMargin: '100px'
+        });
+    }
+}
+
+// 触发懒加载
+function triggerLazyLoad() {
+    const images = notesGrid.querySelectorAll('.note-card-image.lazy');
+    images.forEach(img => {
+        if (window.lazyObserver) {
+            window.lazyObserver.observe(img);
+        } else {
+            // 降级处理
+            if (img.dataset.src) {
+                img.src = img.dataset.src;
+                img.onload = () => img.classList.add('loaded');
+            }
+        }
+    });
+}
+
+// 显示/隐藏加载状态
+function showLoading(show) {
+    loadingState.style.display = show ? 'flex' : 'none';
+    if (show) {
+        emptyState.style.display = 'none';
+    }
+}
+
+// 显示错误
+function showError(message) {
+    emptyState.style.display = 'flex';
+    emptyState.querySelector('.empty-text').textContent = message;
+    emptyState.querySelector('.empty-hint').textContent = '请检查网络连接或刷新页面';
+}
+
+// 更新最后更新时间
+function updateLastUpdate() {
+    const now = new Date();
+    const timeStr = now.toLocaleTimeString('zh-CN', { hour: '2-digit', minute: '2-digit' });
+    lastUpdate.textContent = `更新于 ${timeStr}`;
+}
+
+// 导出函数供其他模块使用
+window.app = {
+    loadNotes,
+    updateLastUpdate
+};
diff --git a/viewer/static/js/modal.js b/viewer/static/js/modal.js
new file mode 100644
index 000000000..9cd6ce1e6
--- /dev/null
+++ b/viewer/static/js/modal.js
@@ -0,0 +1,209 @@
+// 笔记详情模态框
+
+let currentNote = null;
+let currentImageIndex = 0;
+let currentImages = [];
+
+// DOM 元素
+const noteModal = document.getElementById('noteModal');
+const modalClose = document.getElementById('modalClose');
+const modalOverlay = noteModal.querySelector('.modal-overlay');
+const galleryImage = document.getElementById('galleryImage');
+const galleryPrev = document.getElementById('galleryPrev');
+const galleryNext = document.getElementById('galleryNext');
+const galleryIndex = document.getElementById('galleryIndex');
+const imageGallery = document.getElementById('imageGallery');
+const modalTitle = document.getElementById('modalTitle');
+const modalAuthor = document.getElementById('modalAuthor');
+const modalTime = document.getElementById('modalTime');
+const modalLikes = document.getElementById('modalLikes');
+const modalCollects = document.getElementById('modalCollects');
+const modalComments = document.getElementById('modalComments');
+const modalShares = document.getElementById('modalShares');
+const modalTags = document.getElementById('modalTags');
+const modalDesc = document.getElementById('modalDesc');
+const modalLink = document.getElementById('modalLink');
+
+// 初始化
+document.addEventListener('DOMContentLoaded', () => {
+    setupModalEvents();
+});
+
+// 设置模态框事件
+function setupModalEvents() {
+    // 关闭按钮
+    modalClose.addEventListener('click', closeNoteModal);
+
+    // 点击遮罩关闭
+    modalOverlay.addEventListener('click', closeNoteModal);
+
+    // ESC 键关闭
+    document.addEventListener('keydown', (e) => {
+        if (e.key === 'Escape' && noteModal.style.display === 'flex') {
+            closeNoteModal();
+        }
+        // 图片导航
+        if (noteModal.style.display === 'flex') {
+            if (e.key === 'ArrowLeft') navigateGallery(-1);
+            if (e.key === 'ArrowRight') navigateGallery(1);
+        }
+    });
+
+    // 图片导航按钮
+    galleryPrev.addEventListener('click', () => navigateGallery(-1));
+    galleryNext.addEventListener('click', () => navigateGallery(1));
+}
+
+// 打开笔记详情模态框
+async function openNoteModal(note) {
+    currentNote = note;
+    currentImageIndex = 0;
+
+    // 设置基本信息
+    modalTitle.textContent = note.title || '无标题';
+    modalAuthor.textContent = `作者: ${note.nickname || '匿名用户'}`;
+    modalTime.textContent = note.time || '';
+
+    // 设置统计数据
+    modalLikes.textContent = formatCount(note.liked_count);
+    modalCollects.textContent = formatCount(note.collected_count);
+    modalComments.textContent = formatCount(note.comment_count);
+    modalShares.textContent = formatCount(note.share_count);
+
+    // 设置标签
+    modalTags.innerHTML = '';
+    if (note.keywords && note.keywords.length > 0) {
+        note.keywords.forEach(keyword => {
+            const tag = document.createElement('span');
+            tag.className = 'note-tag';
+            tag.textContent = `#${keyword}`;
+            tag.addEventListener('click', () => {
+                closeNoteModal();
+                // 点击标签筛选该关键词
+                keywordFilter.value = keyword;
+                currentKeyword = keyword;
+                loadNotes();
+            });
+            modalTags.appendChild(tag);
+        });
+    }
+
+    // 设置描述
+    modalDesc.textContent = note.desc || '暂无描述';
+
+    // 设置原笔记链接
+    if (note.note_url) {
+        modalLink.href = note.note_url;
+        modalLink.style.display = 'inline-block';
+    } else {
+        modalLink.style.display = 'none';
+    }
+
+    // 设置图片画廊
+    currentImages = note.image_list || [];
+    if (currentImages.length > 0) {
+        imageGallery.style.display = 'block';
+        updateGallery();
+    } else if (note.video_url) {
+        // 视频内容
+        imageGallery.style.display = 'block';
+        galleryImage.src = '';
+        galleryImage.style.display = 'none';
+        galleryPrev.style.display = 'none';
+        galleryNext.style.display = 'none';
+        galleryIndex.textContent = '🎬 视频内容';
+
+        // 创建视频播放器
+        const videoContainer = document.createElement('div');
+        videoContainer.className = 'video-container';
+        videoContainer.innerHTML = `
+            <video controls style="width: 100%; max-height: 400px;">
+                <source src="${note.video_url}" type="video/mp4">
+                您的浏览器不支持视频播放
+            </video>
+        `;
+        const galleryMain = document.querySelector('.gallery-main');
+        const existingVideo = galleryMain.querySelector('.video-container');
+        if (existingVideo) existingVideo.remove();
+        galleryMain.appendChild(videoContainer);
+    } else {
+        imageGallery.style.display = 'none';
+    }
+
+    // 显示模态框
+    noteModal.style.display = 'flex';
+    document.body.style.overflow = 'hidden';
+}
+
+// 关闭模态框
+function closeNoteModal() {
+    noteModal.style.display = 'none';
+    document.body.style.overflow = '';
+
+    // 清理视频
+    const videoContainer = document.querySelector('.gallery-main .video-container');
+    if (videoContainer) {
+        videoContainer.remove();
+    }
+    galleryImage.style.display = 'block';
+
+    currentNote = null;
+    currentImages = [];
+}
+
+// 更新图片画廊
+function updateGallery() {
+    if (currentImages.length === 0) return;
+
+    // 移除视频容器
+    const videoContainer = document.querySelector('.gallery-main .video-container');
+    if (videoContainer) videoContainer.remove();
+    galleryImage.style.display = 'block';
+
+    galleryImage.src = currentImages[currentImageIndex];
+    galleryImage.alt = currentNote?.title || '笔记图片';
+
+    // 更新索引显示
+    galleryIndex.textContent = `${currentImageIndex + 1}/${currentImages.length}`;
+
+    // 更新导航按钮
+    galleryPrev.style.display = currentImages.length > 1 ? 'flex' : 'none';
+    galleryNext.style.display = currentImages.length > 1 ? 'flex' : 'none';
+
+    // 更新按钮状态
+    galleryPrev.style.opacity = currentImageIndex === 0 ? '0.5' : '1';
+    galleryNext.style.opacity = currentImageIndex === currentImages.length - 1 ? '0.5' : '1';
+}
+
+// 图片导航
+function navigateGallery(direction) {
+    if (currentImages.length <= 1) return;
+
+    currentImageIndex += direction;
+
+    // 循环导航
+    if (currentImageIndex < 0) currentImageIndex = currentImages.length - 1;
+    if (currentImageIndex >= currentImages.length) currentImageIndex = 0;
+
+    updateGallery();
+}
+
+// 格式化数量
+function formatCount(count) {
+    if (!count) return '0';
+    const num = parseInt(count);
+    if (isNaN(num)) return count;
+    if (num >= 10000) {
+        return (num / 10000).toFixed(1) + 'w';
+    }
+    if (num >= 1000) {
+        return (num / 1000).toFixed(1) + 'k';
+    }
+    return num.toString();
+}
+
+// 导出函数
+window.modal = {
+    openNoteModal,
+    closeNoteModal
+};
diff --git a/viewer/static/js/monitor.js b/viewer/static/js/monitor.js
new file mode 100644
index 000000000..4f4dad797
--- /dev/null
+++ b/viewer/static/js/monitor.js
@@ -0,0 +1,209 @@
+// 监控面板
+
+let statsInterval = null;
+let ws = null;
+let reconnectAttempts = 0;
+const MAX_RECONNECT = 5;
+
+// DOM 元素
+const statusIndicator = document.getElementById('statusIndicator');
+const statusDot = statusIndicator.querySelector('.status-dot');
+const statusText = statusIndicator.querySelector('.status-text');
+const totalNotes = document.getElementById('totalNotes');
+const totalImages = document.getElementById('totalImages');
+const keywordsStats = document.getElementById('keywordsStats');
+
+// 初始化
+document.addEventListener('DOMContentLoaded', () => {
+    loadStats();
+    startPolling();
+    connectWebSocket();
+});
+
+// 加载统计数据
+async function loadStats() {
+    try {
+        const data = await API.getStats();
+        updateStats(data);
+    } catch (error) {
+        console.error('加载统计失败:', error);
+    }
+}
+
+// 更新统计显示
+function updateStats(data) {
+    // 更新笔记总数
+    if (data.total_notes !== undefined) {
+        totalNotes.textContent = formatNumber(data.total_notes);
+    }
+
+    // 更新图片总数
+    if (data.total_images !== undefined) {
+        totalImages.textContent = formatNumber(data.total_images);
+    }
+
+    // 更新关键词统计
+    if (data.keyword_stats) {
+        keywordsStats.innerHTML = '';
+        Object.entries(data.keyword_stats).forEach(([keyword, count]) => {
+            const tag = document.createElement('span');
+            tag.className = 'keyword-tag';
+            tag.innerHTML = `${keyword}: <span>${formatNumber(count)}</span>`;
+            keywordsStats.appendChild(tag);
+        });
+    }
+}
+
+// 开始轮询
+function startPolling() {
+    // 每 5 秒刷新一次统计
+    statsInterval = setInterval(loadStats, 5000);
+}
+
+// 停止轮询
+function stopPolling() {
+    if (statsInterval) {
+        clearInterval(statsInterval);
+        statsInterval = null;
+    }
+}
+
+// 连接 WebSocket
+function connectWebSocket() {
+    // 检查浏览器支持
+    if (!window.WebSocket) {
+        console.warn('浏览器不支持 WebSocket');
+        return;
+    }
+
+    const wsUrl = `${window.location.protocol === 'https:' ? 'wss:' : 'ws:'}//${window.location.host}/api/ws/status`;
+
+    try {
+        ws = new WebSocket(wsUrl);
+
+        ws.onopen = () => {
+            console.log('WebSocket 连接成功');
+            reconnectAttempts = 0;
+            updateCrawlerStatus({ status: 'connected' });
+        };
+
+        ws.onmessage = (event) => {
+            try {
+                const data = JSON.parse(event.data);
+                handleWebSocketMessage(data);
+            } catch (error) {
+                console.error('解析 WebSocket 消息失败:', error);
+            }
+        };
+
+        ws.onclose = (event) => {
+            console.log('WebSocket 连接关闭:', event.code, event.reason);
+            updateCrawlerStatus({ status: 'disconnected' });
+
+            // 自动重连
+            if (reconnectAttempts < MAX_RECONNECT) {
+                reconnectAttempts++;
+                const delay = Math.min(1000 * Math.pow(2, reconnectAttempts), 30000);
+                console.log(`${delay / 1000}秒后尝试重连...`);
+                setTimeout(connectWebSocket, delay);
+            }
+        };
+
+        ws.onerror = (error) => {
+            console.error('WebSocket 错误:', error);
+            updateCrawlerStatus({ status: 'error' });
+        };
+    } catch (error) {
+        console.error('创建 WebSocket 失败:', error);
+    }
+}
+
+// 处理 WebSocket 消息
+function handleWebSocketMessage(data) {
+    switch (data.type) {
+        case 'crawler_status':
+            updateCrawlerStatus(data);
+            break;
+        case 'stats_update':
+            updateStats(data);
+            // 同时刷新笔记列表
+            if (window.app && window.app.loadNotes) {
+                window.app.loadNotes();
+            }
+            break;
+        case 'new_note':
+            // 有新笔记，刷新列表
+            if (window.app && window.app.loadNotes) {
+                window.app.loadNotes();
+            }
+            loadStats();
+            break;
+        default:
+            console.log('未知消息类型:', data.type);
+    }
+}
+
+// 更新爬虫状态显示
+function updateCrawlerStatus(data) {
+    // 移除所有状态类
+    statusIndicator.classList.remove('running', 'stopped');
+
+    switch (data.status) {
+        case 'running':
+            statusIndicator.classList.add('running');
+            statusText.textContent = `爬虫运行中 (${data.platform || ''})`;
+            break;
+        case 'stopped':
+            statusIndicator.classList.add('stopped');
+            statusText.textContent = '爬虫已停止';
+            break;
+        case 'connected':
+            statusText.textContent = '监控已连接';
+            break;
+        case 'disconnected':
+            statusText.textContent = '监控断开';
+            break;
+        case 'error':
+            statusText.textContent = '监控错误';
+            break;
+        default:
+            statusText.textContent = data.status || '未知状态';
+    }
+}
+
+// 格式化数字
+function formatNumber(num) {
+    if (!num) return '0';
+    const n = parseInt(num);
+    if (isNaN(n)) return num;
+    if (n >= 10000) {
+        return (n / 10000).toFixed(1) + 'w';
+    }
+    if (n >= 1000) {
+        return (n / 1000).toFixed(1) + 'k';
+    }
+    return n.toString();
+}
+
+// 手动刷新
+async function manualRefresh() {
+    await loadStats();
+    if (window.app && window.app.loadNotes) {
+        await window.app.loadNotes();
+    }
+}
+
+// 页面卸载时清理
+window.addEventListener('beforeunload', () => {
+    stopPolling();
+    if (ws) {
+        ws.close();
+    }
+});
+
+// 导出函数
+window.monitor = {
+    loadStats,
+    manualRefresh,
+    connectWebSocket
+};

From c5644c42edab356a882dc0199e9a6b3680e15ca7 Mon Sep 17 00:00:00 2001
From: J1anYi <pp517462915@gmail.com>
Date: Mon, 20 Apr 2026 10:44:03 +0800
Subject: [PATCH 2/2] docs: add AGENTS.md with git and PR guidelines

---
 AGENTS.md | 118 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 118 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..88e45a7bf
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,118 @@
+# MediaCrawler 项目指南
+
+## 项目概述
+
+MediaCrawler 是一个小红书爬虫项目，支持爬取笔记数据并提供 Web 可视化界面。
+
+## 技术栈
+
+- **后端**: Python + FastAPI
+- **前端**: 纯 HTML/CSS/JavaScript（无框架）
+- **数据存储**: JSONL 文件
+
+## 开发规范
+
+### Git 分支与 PR 规范
+
+#### 分支命名
+
+- `feat/xxx` - 新功能开发
+- `fix/xxx` - Bug 修复
+- `refactor/xxx` - 代码重构
+- `docs/xxx` - 文档更新
+
+#### PR 目标分支
+
+**重要**: 所有 PR 必须提交到 `main` 分支，而非其他特性分支。
+
+```
+正确: feature/xxx → main
+错误: feature/xxx → feat/xxx
+```
+
+#### 远程仓库配置
+
+项目有两个远程仓库：
+
+| 名称 | 地址 | 用途 |
+|------|------|------|
+| `origin` | git@github.com:NanmiCoder/MediaCrawler.git | 上游原始仓库 |
+| `myfork` | git@github.com:J1anYi/MediaCrawler.git | 个人 Fork 仓库 |
+
+推送代码到 Fork 仓库：
+```bash
+git push myfork feat/xxx:feat/xxx
+```
+
+创建 PR 时，确保：
+- **Base 仓库**: J1anYi/MediaCrawler
+- **Base 分支**: main
+- **Head 分支**: feat/xxx
+
+### 代码风格
+
+#### Python
+
+- 使用 4 空格缩进
+- 遵循 PEP 8 规范
+- 函数必须有类型注解
+- 安全相关的输入验证必须完善
+
+#### JavaScript
+
+- 使用 2 空格缩进
+- 使用 ES6+ 语法
+- 避免全局变量污染，使用 `window.xxx` 导出
+
+#### CSS
+
+- 使用 BEM 命名规范
+- 响应式设计优先
+
+### 安全规范
+
+1. **路径遍历防护**: 所有文件路径相关的用户输入必须验证
+2. **输入验证**: 使用 FastAPI Query/Path 验证器
+3. **类型注解**: 函数必须有返回类型注解
+
+## 目录结构
+
+```
+MediaCrawler/
+├── api/                    # FastAPI 后端
+│   └── routers/
+│       └── notes.py        # 笔记 API
+├── viewer/                 # 前端可视化界面
+│   ├── index.html
+│   └── static/
+│       ├── css/
+│       └── js/
+│           ├── app.js      # 主应用逻辑
+│           ├── api.js      # API 封装
+│           ├── modal.js    # 模态框组件
+│           └── monitor.js  # 监控组件
+├── data/                   # 数据目录
+│   └── xhs/
+│       ├── jsonl/          # 笔记数据
+│       └── images/         # 图片资源
+└── docs/                   # 文档
+```
+
+## 开发流程
+
+1. 从 `main` 分支创建特性分支
+2. 开发并测试
+3. 运行代码审查
+4. 推送到 Fork 仓库
+5. 创建 PR 到 `main` 分支
+
+## 本地开发
+
+启动开发服务器：
+```bash
+python api/main.py
+```
+
+访问：
+- 可视化界面: http://localhost:8080/viewer/index.html
+- API 文档: http://localhost:8080/docs