feat(viewer): 添加知乎数据展示标签页

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:8081/viewer/index.html
+- API 文档: http://localhost:8081/docs

README.md

@@ -161,13 +161,13 @@ MediaCrawler 提供了基于 Web 的可视化操作界面，无需命令行也
 
 ```shell
 # 启动 API 服务器（默认端口 8080）
-uv run uvicorn api.main:app --port 8080 --reload
+uv run uvicorn api.main:app --port 8081 --reload
 
 # 或者使用模块方式启动
 uv run python -m api.main
 ```
 
-启动成功后，访问 `http://localhost:8080` 即可打开 WebUI 界面。
+启动成功后，访问 `http://localhost:8081` 即可打开 WebUI 界面。
 
 #### WebUI 功能特性
 

README_en.md

@@ -142,14 +142,14 @@ MediaCrawler provides a web-based visual operation interface, allowing you to ea
 #### Start WebUI Service
 
 ```shell
-# Start API server (default port 8080)
-uv run uvicorn api.main:app --port 8080 --reload
+# Start API server (default port 8081)
+uv run uvicorn api.main:app --port 8081 --reload
 
 # Or start using module method
 uv run python -m api.main
 ```
 
-After successful startup, visit `http://localhost:8080` to open the WebUI interface.
+After successful startup, visit `http://localhost:8081` to open the WebUI interface.
 
 #### WebUI Features
 

README_es.md

@@ -143,13 +143,13 @@ MediaCrawler proporciona una interfaz de operación visual basada en web, permit
 
 ```shell
 # Iniciar servidor API (puerto predeterminado 8080)
-uv run uvicorn api.main:app --port 8080 --reload
+uv run uvicorn api.main:app --port 8081 --reload
 
 # O iniciar usando método de módulo
 uv run python -m api.main
 ```
 
-Después de iniciar exitosamente, visite `http://localhost:8080` para abrir la interfaz WebUI.
+Después de iniciar exitosamente, visite `http://localhost:8081` para abrir la interfaz WebUI.
 
 #### Características de WebUI
 

api/main.py

@@ -23,19 +23,78 @@
 """
 import asyncio
 import os
+import shutil
 import subprocess
+from contextlib import asynccontextmanager
+from pathlib import Path
+
 import uvicorn
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 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, zhihu_router, bilibili_router, douyin_router, subscriptions_router, trends_router, image_queue_router
+from .services import file_watcher, image_task_db, image_downloader, image_queue_service, image_scheduler
+from .services.file_watcher import PLATFORMS
+from .routers.websocket import broadcast_stats_update, broadcast_platform_update
+
+
+# Data directory for JSONL files
+DATA_DIR = Path(__file__).parent.parent / "data"
+
+
+async def on_file_change_callback(platform: str):
+    """
+    Callback for file watcher when a platform's data changes.
+    Broadcasts both platform-specific update and global stats update.
+
+    Args:
+        platform: The platform identifier (e.g., "xhs", "dy", "bili", "zhihu")
+    """
+    # Broadcast platform-specific update (for viewer components)
+    await broadcast_platform_update(platform)
+    # Broadcast global stats update (for WebUI compatibility)
+    await broadcast_stats_update(platform)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifespan manager - start/stop file watcher for all platforms."""
+    # Initialize task database
+    await image_task_db.init_db()
+
+    # Initialize image downloader
+    await image_downloader.init()
+
+    # Start queue service (launches consumers)
+    image_queue_service.start()
+
+    # Start scheduler (scans for timeout and retry tasks)
+    image_scheduler.start()
+
+    # Startup - watch all platform directories
+    file_watcher.start(
+        platforms=PLATFORMS,
+        base_callback=on_file_change_callback,
+        base_path=str(DATA_DIR)
+    )
+    app.state.file_watcher = file_watcher
+
+    yield
+
+    # Shutdown
+    image_scheduler.stop()
+    image_queue_service.stop()
+    await image_downloader.close()
+    file_watcher.stop()
+
 
 app = FastAPI(
     title="MediaCrawler WebUI API",
     description="API for controlling MediaCrawler from WebUI",
-    version="1.0.0"
+    version="1.0.0",
+    lifespan=lifespan
 )
 
 # Get webui static files directory
@@ -59,6 +118,13 @@
 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.include_router(zhihu_router, prefix="/api")
+app.include_router(bilibili_router, prefix="/api")
+app.include_router(douyin_router, prefix="/api")
+app.include_router(subscriptions_router, prefix="/api")
+app.include_router(trends_router, prefix="/api")
+app.include_router(image_queue_router, prefix="/api")
 
 
 @app.get("/")
@@ -83,50 +149,14 @@ async def health_check():
 @app.get("/api/env/check")
 async def check_environment():
     """Check if MediaCrawler environment is configured correctly"""
-    try:
-        # Run uv run main.py --help command to check environment
-        process = await asyncio.create_subprocess_exec(
-            "uv", "run", "main.py", "--help",
-            stdout=subprocess.PIPE,
-            stderr=subprocess.PIPE,
-            cwd="."  # Project root directory
-        )
-        stdout, stderr = await asyncio.wait_for(
-            process.communicate(),
-            timeout=30.0  # 30 seconds timeout
-        )
-
-        if process.returncode == 0:
-            return {
-                "success": True,
-                "message": "MediaCrawler environment configured correctly",
-                "output": stdout.decode("utf-8", errors="ignore")[:500]  # Truncate to first 500 characters
-            }
-        else:
-            error_msg = stderr.decode("utf-8", errors="ignore") or stdout.decode("utf-8", errors="ignore")
-            return {
-                "success": False,
-                "message": "Environment check failed",
-                "error": error_msg[:500]
-            }
-    except asyncio.TimeoutError:
-        return {
-            "success": False,
-            "message": "Environment check timeout",
-            "error": "Command execution exceeded 30 seconds"
-        }
-    except FileNotFoundError:
-        return {
-            "success": False,
-            "message": "uv command not found",
-            "error": "Please ensure uv is installed and configured in system PATH"
-        }
-    except Exception as e:
-        return {
-            "success": False,
-            "message": "Environment check error",
-            "error": str(e)
-        }
+    # Simple check - just verify uv is available
+    uv_path = shutil.which("uv")
+
+    return {
+        "success": uv_path is not None,
+        "message": "Environment ready" if uv_path else "uv not found",
+        "uv_path": uv_path
+    }
 
 
 @app.get("/api/config/platforms")
@@ -182,6 +212,21 @@ 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")
+
+# Mount data directory for local images (downloaded images with hash-based paths)
+LOCAL_DATA_DIR = os.path.join(os.path.dirname(__file__), "..", "data")
+if os.path.exists(LOCAL_DATA_DIR):
+    app.mount("/local-images", StaticFiles(directory=LOCAL_DATA_DIR), name="local-images")
+
 
 if __name__ == "__main__":
-    uvicorn.run(app, host="0.0.0.0", port=8080)
+    uvicorn.run(app, host="0.0.0.0", port=8081)

api/routers/__init__.py

@@ -19,5 +19,12 @@
 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
+from .zhihu import router as zhihu_router
+from .bilibili import router as bilibili_router
+from .douyin import router as douyin_router
+from .subscriptions import router as subscriptions_router
+from .trends import router as trends_router
+from .image_queue import router as image_queue_router
 
-__all__ = ["crawler_router", "data_router", "websocket_router"]
+__all__ = ["crawler_router", "data_router", "websocket_router", "notes_router", "zhihu_router", "bilibili_router", "douyin_router", "subscriptions_router", "trends_router", "image_queue_router"]