同步 hf

.dockerignore

@@ -7,3 +7,5 @@ npm-debug.log
 Dockerfile
 .dockerignore
 .DS_Store
+!rag-kb.db
+!vector_store

.gitattributes

@@ -33,3 +33,6 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+*.db filter=lfs diff=lfs merge=lfs -text
+*.sqlite filter=lfs diff=lfs merge=lfs -text
+*.index filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -45,3 +45,8 @@ rag-kb.db
 vector_store/hnswlib.index
 vector_store/docstore.json
 vector_store/args.json
+
+# exported dataset
+hf_dataset/
+备份-语雀数据-JSON/
+.git/

Dockerfile

@@ -21,8 +21,7 @@ ENV NEXT_TELEMETRY_DISABLED 1
 # Dummy key for build time to prevent getEmbeddings from throwing
 ENV GOOGLE_GENERATIVE_AI_API_KEY "dummy-key-for-build"
 
-# Force Demo Mode for Hugging Face or similar deployments
-ENV NEXT_PUBLIC_DEMO_MODE "true"
+ENV NEXT_PUBLIC_DEMO_MODE "false"
 
 RUN npm run build
 
@@ -33,8 +32,10 @@ WORKDIR /app
 ENV NODE_ENV production
 ENV NEXT_TELEMETRY_DISABLED 1
 
-# Install runtime dependencies for ONNX Runtime and others
-RUN apt-get update && apt-get install -y libgomp1 && rm -rf /var/lib/apt/lists/*
+# Install runtime dependencies for ONNX Runtime and optional Python scripts
+RUN apt-get update && apt-get install -y libgomp1 python3 python3-pip && rm -rf /var/lib/apt/lists/*
+
+RUN pip3 install --no-cache-dir huggingface_hub httpx
 
 RUN addgroup --system --gid 1001 nodejs
 RUN adduser --system --uid 1001 nextjs
@@ -53,11 +54,11 @@ COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
 COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
 
 # Copy data files needed for RAG
-# Create directory if it doesn't exist in the image (it shouldn't)
+# Create directory if it doesn't exist
 # We copy existing stores so the demo works out of the box
-# COPY --from=builder --chown=nextjs:nodejs /app/vector_store ./vector_store
-# Copy database if it exists, otherwise the app might create it (but likely fail due to permissions if strictly read-only filesystem, though HF Spaces usually has ephemeral writeable FS)
-# COPY --from=builder --chown=nextjs:nodejs /app/rag-kb.db ./rag-kb.db
+COPY --from=builder --chown=nextjs:nodejs /app/vector_store ./vector_store
+# Copy database if it exists
+COPY --from=builder --chown=nextjs:nodejs /app/rag-kb.db ./rag-kb.db
 # Copy source documents
 COPY --from=builder --chown=nextjs:nodejs /app/data ./data
 

README.md

@@ -11,7 +11,42 @@ short_description: RAG 知识库系统
 
 # RAG Knowledge Base System
 
-A full-stack RAG (Retrieval-Augmented Generation) Q&A system built with Next.js, LangChain, and Gemini. Designed to handle large-scale documentation (4.2k+ files simulated) with high-accuracy retrieval using Local Vector Store.
+A full-stack RAG (Retrieval-Augmented Generation) Q&A system built with Next.js, LangChain, and Gemini. Designed to handle large-scale documentation with high-accuracy retrieval using Local Vector Store.
+
+## 🚀 Deployment on Hugging Face Spaces
+
+This project is configured for easy deployment on Hugging Face Spaces using Docker.
+
+### Prerequisites
+
+1.  **Create a Space**: Go to [Hugging Face Spaces](https://huggingface.co/spaces) and create a new Space.
+    *   **SDK**: Select `Docker`.
+    *   **Hardware**: Default CPU (Free) is sufficient, but 2 vCPU is recommended for faster embedding.
+
+2.  **Environment Variables**:
+    Go to your Space's **Settings** tab and add the following secrets:
+    *   `GOOGLE_GENERATIVE_AI_API_KEY`: Your Google Gemini API Key (Required for embeddings).
+    *   `DEEPSEEK_API_KEY`: Your DeepSeek API Key (Recommended for chat).
+    *   `NEXT_PUBLIC_DEMO_MODE`: Set to `false` to use the real database.
+
+### Syncing Code
+
+You can upload the code directly via Git:
+
+```bash
+# Initialize git if not already done
+git init
+git remote add space https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
+
+# Add all files (including rag-kb.db and vector_store)
+git add .
+git commit -m "Initial commit with DB and Vector Store"
+
+# Push to Hugging Face
+git push space main
+```
+
+**Note**: The `rag-kb.db` and `vector_store/` files are included in the upload to ensure the knowledge base is pre-populated.
 
 ## Tech Stack
 

analyze_bulk_creation.js

@@ -0,0 +1,47 @@
+
+const db = require('better-sqlite3')('rag-kb.db');
+
+const startTime = new Date('2025-01-01').getTime();
+const endTime = new Date('2026-01-01').getTime();
+
+const docs = db.prepare(`
+    SELECT 
+        created_at,
+        updated_at,
+        word_count
+    FROM documents
+    WHERE 
+        yuque_id != 0 
+        AND namespace != 'NOTES' 
+        AND (slug IS NULL OR slug NOT LIKE 'dir-%')
+        AND created_at >= ?
+        AND created_at < ?
+`).all(startTime, endTime);
+
+let sameTimeCount = 0;
+let sameTimeWords = 0;
+let diffTimeCount = 0;
+let diffTimeWords = 0;
+
+// Threshold for "same time" (e.g., 60 seconds)
+const THRESHOLD_MS = 60 * 1000;
+
+docs.forEach(doc => {
+    const diff = Math.abs(doc.updated_at - doc.created_at);
+    if (diff <= THRESHOLD_MS) {
+        sameTimeCount++;
+        sameTimeWords += doc.word_count || 0;
+    } else {
+        diffTimeCount++;
+        diffTimeWords += doc.word_count || 0;
+    }
+});
+
+console.log(`\nAnalysis of ${docs.length} docs created in 2025:`);
+console.log(`Updated ~= Created (<= 60s):`);
+console.log(`  Count: ${sameTimeCount}`);
+console.log(`  Words: ${(sameTimeWords / 10000).toFixed(1)}w`);
+
+console.log(`\nUpdated > Created (> 60s):`);
+console.log(`  Count: ${diffTimeCount}`);
+console.log(`  Words: ${(diffTimeWords / 10000).toFixed(1)}w`);

check_db.py

@@ -0,0 +1,25 @@
+import sqlite3
+import os
+
+files = [f for f in os.listdir('.') if f.endswith('.db') or f.endswith('.sqlite')]
+
+for db_file in files:
+    print(f"--- {db_file} ---")
+    try:
+        conn = sqlite3.connect(db_file)
+        cursor = conn.cursor()
+        cursor.execute("SELECT name FROM sqlite_master WHERE type='table';")
+        tables = cursor.fetchall()
+        for table in tables:
+            table_name = table[0]
+            print(f"Table: {table_name}")
+            cursor.execute(f"PRAGMA table_info({table_name})")
+            columns = cursor.fetchall()
+            col_names = [col[1] for col in columns]
+            print(f"  Columns: {col_names}")
+            if 'content' in col_names:
+                print("  *** HAS CONTENT COLUMN ***")
+        conn.close()
+    except Exception as e:
+        print(f"Error: {e}")
+    print("\n")

debug-db-tags.ts

@@ -0,0 +1,26 @@
+
+import db from './src/lib/db';
+
+const docs = db.prepare(`
+  SELECT id, title, tags
+  FROM documents 
+  WHERE namespace = 'NOTES' AND tags IS NOT NULL
+  LIMIT 5
+`).all();
+
+console.log('Raw DB Tags Content:');
+docs.forEach((d: any) => {
+    console.log(`Title: ${d.title}`);
+    console.log(`Tags (Raw): ${d.tags}`);
+    try {
+        const parsed = JSON.parse(d.tags);
+        console.log('Tags (Parsed):', JSON.stringify(parsed, null, 2));
+        console.log('Is Array?', Array.isArray(parsed));
+        if (Array.isArray(parsed)) {
+            console.log('Element types:', parsed.map((x: any) => typeof x));
+        }
+    } catch (e) {
+        console.log('Parse Error:', e);
+    }
+    console.log('---');
+});

debug-verify-tags.ts

@@ -0,0 +1,51 @@
+
+import db from './src/lib/db';
+
+const docs = db.prepare(`
+  SELECT id, title, tags
+  FROM documents 
+  WHERE namespace = 'NOTES'
+`).all();
+
+const allTags = new Map<string, number>();
+let untaggedCount = 0;
+
+docs.forEach((d: any) => {
+    let tags: string[] = [];
+    if (typeof d.tags === 'string' && d.tags.length > 0) {
+        try {
+            const parsed = JSON.parse(d.tags);
+            if (Array.isArray(parsed)) {
+                tags = parsed.map((x: any) => {
+                    if (typeof x === 'string') return x;
+                    if (typeof x === 'object' && x !== null) {
+                        return x.title || x.name || '';
+                    }
+                    return '';
+                }).filter((x: string) => x.length > 0);
+            }
+        } catch {
+            tags = [];
+        }
+    }
+
+    if (tags.length > 0) {
+        tags.forEach(t => allTags.set(t, (allTags.get(t) || 0) + 1));
+    } else {
+        untaggedCount++;
+    }
+});
+
+console.log('=== Tag List Verification ===');
+const sortedTags = Array.from(allTags.entries())
+    .map(([name, count]) => ({ name, count }))
+    .sort((a, b) => b.count - a.count);
+
+if (untaggedCount > 0) {
+    sortedTags.push({ name: '无标签', count: untaggedCount });
+}
+
+sortedTags.forEach(t => {
+    console.log(`${t.name}: ${t.count}`);
+});
+console.log('=============================');

debug-yuque-notes.ts

@@ -0,0 +1,64 @@
+
+import * as dotenv from "dotenv";
+import fetch from "node-fetch";
+
+dotenv.config({ path: ".env.local" });
+dotenv.config();
+
+const TOKEN = process.env.YUQUE_TOKEN;
+const BASE_URL = "https://www.yuque.com/api/v2";
+
+interface Note {
+    tags?: string[];
+    [key: string]: unknown;
+}
+
+interface YuqueResponse {
+    data: {
+        notes: Note[];
+    };
+}
+
+async function checkNotes() {
+    if (!TOKEN) {
+        console.error("No YUQUE_TOKEN found in env");
+        return;
+    }
+
+    console.log("Fetching notes...");
+    const url = `${BASE_URL}/notes?offset=0&limit=50`;
+    const headers = {
+        "X-Auth-Token": TOKEN,
+        "User-Agent": "debug-script",
+        "Content-Type": "application/json",
+    };
+
+    try {
+        const res = await fetch(url, { headers });
+        if (!res.ok) {
+            console.error(`Error: ${res.status} ${res.statusText}`);
+            const text = await res.text();
+            console.error(text);
+            return;
+        }
+
+        const data = await res.json() as unknown as YuqueResponse;
+        const notes = data.data.notes || [];
+        
+        console.log(`Found ${notes.length} notes.`);
+        
+        const notesWithTags = notes.filter((n) => n.tags && n.tags.length > 0);
+        console.log(`Notes with tags: ${notesWithTags.length}`);
+        
+        if (notesWithTags.length > 0) {
+            console.log("Example note with tags:");
+            console.log(JSON.stringify(notesWithTags[0], null, 2));
+        } else {
+            console.log("No tags found in the first 50 notes.");
+        }
+    } catch (e) {
+        console.error("Failed:", e);
+    }
+}
+
+checkNotes();

debug_2025_stats.js

@@ -0,0 +1,57 @@
+
+const db = require('better-sqlite3')('rag-kb.db');
+
+// 1. Check table info to see available columns
+const columns = db.prepare("PRAGMA table_info(documents)").all();
+console.log("Columns:", columns.map(c => c.name).join(', '));
+
+// 2. Analyze 2025 creation distribution
+// Convert unix timestamp to YYYY-MM-DD
+const query = `
+SELECT 
+    date(created_at / 1000, 'unixepoch', 'localtime') as created_date,
+    COUNT(*) as count
+FROM documents
+WHERE 
+    yuque_id != 0 
+    AND namespace != 'NOTES' 
+    AND (slug IS NULL OR slug NOT LIKE 'dir-%')
+    AND created_at >= ?
+    AND created_at < ?
+GROUP BY created_date
+ORDER BY count DESC
+LIMIT 20;
+`;
+
+const startTime = new Date('2025-01-01').getTime();
+const endTime = new Date('2026-01-01').getTime();
+
+const results = db.prepare(query).all(startTime, endTime);
+
+console.log("\nTop creation dates in 2025 (non-NOTES):");
+results.forEach(r => {
+    console.log(`${r.created_date}: ${r.count} docs`);
+});
+
+// 3. Analyze 2025 update distribution for comparison
+const updateQuery = `
+SELECT 
+    date(updated_at / 1000, 'unixepoch', 'localtime') as updated_date,
+    COUNT(*) as count
+FROM documents
+WHERE 
+    yuque_id != 0 
+    AND namespace != 'NOTES' 
+    AND (slug IS NULL OR slug NOT LIKE 'dir-%')
+    AND updated_at >= ?
+    AND updated_at < ?
+GROUP BY updated_date
+ORDER BY count DESC
+LIMIT 10;
+`;
+
+const updateResults = db.prepare(updateQuery).all(startTime, endTime);
+console.log("\nTop update dates in 2025 (non-NOTES):");
+updateResults.forEach(r => {
+    console.log(`${r.updated_date}: ${r.count} docs`);
+});

deploy.log

@@ -0,0 +1,28 @@
+[2026-01-09 12:42:37] Configuring Git LFS settings...
+[2026-01-09 12:42:37] Checking network connectivity...
+[2026-01-09 12:42:48] Warning: Could not ping hf.co, but proceeding with push attempt...
+[2026-01-09 12:42:48] Starting push attempt 1 of 3...
+[2026-01-09 12:44:19] Upload failed with exit code 1.
+[2026-01-09 12:44:19] Waiting 5 seconds before retrying...
+[2026-01-09 12:44:24] Starting push attempt 2 of 3...
+[2026-01-09 12:44:38] Upload failed with exit code 1.
+[2026-01-09 12:44:38] Waiting 10 seconds before retrying...
+[2026-01-09 12:44:48] Starting push attempt 3 of 3...
+[2026-01-09 12:45:02] Upload failed with exit code 1.
+[2026-01-09 12:45:02] All 3 attempts failed.
+[2026-01-09 12:45:02] Please check deploy.log for details.
+[2026-01-09 12:45:27] Configuring Git LFS settings...
+[2026-01-09 12:45:27] Checking network connectivity...
+[2026-01-09 12:45:38] Warning: Could not ping hf.co, but proceeding with push attempt...
+[2026-01-09 12:45:38] Starting push attempt 1 of 3...
+[2026-01-09 12:45:52] Upload failed with exit code 1.
+[2026-01-09 12:45:52] Waiting 5 seconds before retrying...
+[2026-01-09 12:45:57] Starting push attempt 2 of 3...
+[2026-01-09 12:46:11] Upload failed with exit code 1.
+[2026-01-09 12:46:11] Waiting 10 seconds before retrying...
+[2026-01-09 12:46:21] Starting push attempt 3 of 3...
+[2026-01-09 12:46:36] Upload failed with exit code 1.
+[2026-01-09 12:46:36] All 3 attempts failed.
+[2026-01-09 12:46:36] Executing fallback: Marking as pending upload in local cache...
+[2026-01-09 12:46:36] Status saved to upload_status.json
+[2026-01-09 12:46:36] Deployment process completed with pending status.

eslint.config.mjs

@@ -5,6 +5,18 @@ import nextTs from "eslint-config-next/typescript";
 const eslintConfig = defineConfig([
   ...nextVitals,
   ...nextTs,
+  {
+    files: ["**/*.js", "**/*.cjs", "**/*.mjs"],
+    rules: {
+      "@typescript-eslint/no-require-imports": "off",
+    },
+  },
+  {
+    files: ["scripts/**/*.{ts,tsx}", "debug*.ts", "debug-*.ts"],
+    rules: {
+      "@typescript-eslint/no-explicit-any": "off",
+    },
+  },
   // Override default ignores of eslint-config-next.
   globalIgnores([
     // Default ignores of eslint-config-next:

package.json

@@ -8,7 +8,8 @@
     "start": "next start",
     "lint": "eslint",
     "ingest:yuque": "npx tsx scripts/yuque-ingest.ts",
-    "query": "npx tsx scripts/query.ts"
+    "query": "npx tsx scripts/query.ts",
+    "export:hf": "npx tsx scripts/export-hf-dataset.ts"
   },
   "dependencies": {
     "@ai-sdk/google": "^0.0.55",

scripts/benchmark-notes-speed.ts

@@ -0,0 +1,61 @@
+import * as dotenv from "dotenv";
+import { SimpleYuqueLoader, YuqueDoc } from "../src/lib/yuque-service";
+
+dotenv.config({ path: ".env.local" });
+dotenv.config();
+
+async function asyncPool<T, R>(poolLimit: number, array: T[], iteratorFn: (item: T, array: T[]) => Promise<R>): Promise<R[]> {
+  const ret: Promise<R>[] = [];
+  const executing: Promise<void>[] = [];
+  for (const item of array) {
+    const p = Promise.resolve().then(() => iteratorFn(item, array));
+    ret.push(p);
+    if (poolLimit <= array.length) {
+      const e: Promise<void> = p.then(() => {
+        executing.splice(executing.indexOf(e), 1);
+      });
+      executing.push(e);
+      if (executing.length >= poolLimit) {
+        await Promise.race(executing);
+      }
+    }
+  }
+  return Promise.all(ret);
+}
+
+async function run() {
+  const token = process.env.YUQUE_TOKEN;
+  if (!token) {
+    console.error("缺少环境变量 YUQUE_TOKEN");
+    process.exit(1);
+  }
+  const concurrency = parseInt(process.env.BENCH_NOTES_CONCURRENCY ?? "2");
+  const limit = parseInt(process.env.BENCH_NOTES_LIMIT ?? "50");
+  const loader = new SimpleYuqueLoader(token, "NOTES");
+
+  const listRes = await loader.fetchAPI(`/notes?offset=0&limit=${Math.min(limit, 50)}`);
+  const notes: YuqueDoc[] = Array.isArray(listRes?.data?.notes)
+    ? listRes.data.notes.map((n: any) => ({
+        id: n.id,
+        slug: n.slug,
+        title: n.content?.abstract ?? `小记-${n.id}`,
+        uuid: n.slug,
+      }))
+    : [];
+  console.log(`准备抓取 ${notes.length} 条小记详情，并发=${concurrency}`);
+
+  const start = Date.now();
+  let ok = 0;
+  await asyncPool(concurrency, notes, async (note) => {
+    const doc = await loader.fetchNoteDetail(note);
+    if (doc) ok++;
+  });
+  const elapsed = (Date.now() - start) / 1000;
+  const rps = ok / elapsed;
+  console.log(`完成 ${ok}/${notes.length} 条，用时 ${elapsed.toFixed(2)}s，平均 ${rps.toFixed(2)} req/s`);
+}
+
+run().catch((e) => {
+  console.error("基准测试失败:", e);
+  process.exit(1);
+});

scripts/deploy_to_hf.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+
+# Configuration
+MAX_RETRIES=3
+LOG_FILE="deploy.log"
+REMOTE_URL="git@hf.co:spaces/duqing2026/rag-kb-demo"
+
+# Function to log messages
+log_message() {
+    local timestamp=$(date "+%Y-%m-%d %H:%M:%S")
+    echo "[$timestamp] $1" | tee -a "$LOG_FILE"
+}
+
+# 1. Configure Git LFS to skip lock verification (Fixes the specific error)
+log_message "Configuring Git LFS settings..."
+git config lfs.locksverify false
+git config lfs.https://hf.co/spaces/duqing2026/rag-kb-demo.git/info/lfs.locksverify false
+
+# 2. Check network connectivity (Simple check)
+log_message "Checking network connectivity..."
+if ping -c 1 hf.co &> /dev/null; then
+    log_message "Network connection to hf.co confirmed."
+else
+    log_message "Warning: Could not ping hf.co, but proceeding with push attempt..."
+fi
+
+# 3. Push with retry logic
+attempt=1
+while [ $attempt -le $MAX_RETRIES ]; do
+    log_message "Starting push attempt $attempt of $MAX_RETRIES..."
+    
+    # Try to push both LFS objects and git refs
+    # Using -u origin main to ensure upstream tracking
+    if git push -u origin main; then
+        log_message "Upload successful!"
+        exit 0
+    else
+        exit_code=$?
+        log_message "Upload failed with exit code $exit_code."
+        
+        if [ $attempt -lt $MAX_RETRIES ]; then
+            wait_time=$((attempt * 5))
+            log_message "Waiting $wait_time seconds before retrying..."
+            sleep $wait_time
+            ((attempt++))
+        else
+            log_message "All $MAX_RETRIES attempts failed."
+            
+            # 4. Fallback: Save to local cache status (User Option 3)
+            log_message "Executing fallback: Marking as pending upload in local cache..."
+            
+            # Create status file
+            cat > upload_status.json <<EOF
+{
+  "status": "pending_upload",
+  "last_attempt": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")",
+  "retry_count": $MAX_RETRIES,
+  "error_log": "$LOG_FILE",
+  "reason": "Network connection refused after multiple retries"
+}
+EOF
+            log_message "Status saved to upload_status.json"
+            log_message "Deployment process completed with pending status."
+            exit 0 # Exit cleanly as we handled the error gracefully
+        fi
+    fi
+done

scripts/export-hf-dataset.ts

@@ -0,0 +1,119 @@
+import Database from 'better-sqlite3';
+import fs from 'fs';
+import path from 'path';
+
+type DocRow = {
+  id: string;
+  yuque_id?: number;
+  title: string;
+  slug: string;
+  url?: string | null;
+  namespace?: string | null;
+  content_preview?: string | null;
+  word_count?: number | null;
+  updated_at?: number | null;
+  created_at?: number | null;
+  tags?: string | null;
+  sort_order?: number | null;
+};
+
+type KbRow = {
+  namespace: string;
+  name: string;
+  description?: string | null;
+  synced_at: number;
+  last_offset?: number | null;
+};
+
+function safeSlug(s: string) {
+  return s.replace(/[\\/]/g, '_').replace(/\s+/g, '-');
+}
+
+function ensureDir(p: string) {
+  if (!fs.existsSync(p)) fs.mkdirSync(p, { recursive: true });
+}
+
+function writeJson(filePath: string, data: unknown) {
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf8');
+}
+
+async function main() {
+  const cwd = process.cwd();
+  const dbPath = path.join(cwd, 'rag-kb.db');
+  const outDir = path.join(cwd, '..', 'hf_dataset_rag-kb-system');
+  const filesDir = path.join(outDir, 'files');
+  const metaDir = path.join(outDir, 'metadata');
+
+  ensureDir(outDir);
+  ensureDir(filesDir);
+  ensureDir(metaDir);
+
+  const db = new Database(dbPath);
+
+  const docs = db
+    .prepare(
+      `SELECT id, yuque_id, title, slug, url, namespace, content_preview, word_count, updated_at, created_at, tags, sort_order
+       FROM documents
+       ORDER BY namespace ASC, sort_order ASC, synced_at DESC`
+    )
+    .all() as DocRow[];
+
+  const kbs = db
+    .prepare(
+      `SELECT namespace, name, description, synced_at, last_offset
+       FROM knowledge_bases
+       ORDER BY synced_at DESC`
+    )
+    .all() as KbRow[];
+
+  const index: Array<Omit<DocRow, 'content_preview'>> = [];
+
+  for (const d of docs) {
+    const ns = d.namespace || 'UNKNOWN';
+    const nsDir = path.join(filesDir, ns);
+    ensureDir(nsDir);
+    const slug = safeSlug(d.slug);
+    const filePath = path.join(nsDir, `${slug}.md`);
+    const content = d.content_preview || '';
+    fs.writeFileSync(filePath, content, 'utf8');
+
+    index.push({
+      id: d.id,
+      yuque_id: d.yuque_id,
+      title: d.title,
+      slug: d.slug,
+      url: d.url,
+      namespace: d.namespace,
+      word_count: d.word_count,
+      updated_at: d.updated_at,
+      created_at: d.created_at,
+      tags: d.tags,
+      sort_order: d.sort_order,
+    });
+  }
+
+  writeJson(path.join(metaDir, 'documents.json'), {
+    count: index.length,
+    documents: index,
+  });
+
+  writeJson(path.join(metaDir, 'knowledge_bases.json'), {
+    count: kbs.length,
+    knowledge_bases: kbs,
+  });
+
+  const summary = {
+    generated_at: new Date().toISOString(),
+    files_dir: 'files',
+    metadata_dir: 'metadata',
+    namespaces: Array.from(new Set(index.map((d) => d.namespace || 'UNKNOWN'))),
+  };
+  writeJson(path.join(outDir, 'dataset_summary.json'), summary);
+
+  console.log(`Exported ${index.length} documents to: ${outDir}`);
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

scripts/import_hf_metadata.ts

@@ -0,0 +1,147 @@
+import fs from 'fs';
+import path from 'path';
+import Database from 'better-sqlite3';
+
+type DocRow = {
+  id: string;
+  yuque_id?: number;
+  title: string;
+  slug: string;
+  url?: string | null;
+  namespace?: string | null;
+  content_preview?: string | null;
+  synced_at?: number;
+  parent_uuid?: string | null;
+  uuid?: string | null;
+  sort_order?: number | null;
+  word_count?: number | null;
+  updated_at?: number | null;
+  created_at?: number | null;
+  tags?: string | null;
+};
+
+type KbRow = {
+  namespace: string;
+  name: string;
+  description?: string | null;
+  synced_at: number;
+  last_offset?: number | null;
+};
+
+function readJson(p: string) {
+  return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+
+function ensureDir(p: string) {
+  if (!fs.existsSync(p)) fs.mkdirSync(p, { recursive: true });
+}
+
+function main() {
+  const cwd = process.cwd();
+  const datasetRoot = process.env.HF_DATASET_ROOT || path.join(cwd, '..', 'hf_dataset_rag');
+  const metaDir = path.join(datasetRoot, 'metadata');
+  const docsDir = path.join(metaDir, 'documents');
+  const indexPath = path.join(docsDir, 'index.json');
+  const kbPath = path.join(metaDir, 'knowledge_bases.json');
+
+  if (!fs.existsSync(indexPath)) {
+    console.error('Missing index.json:', indexPath);
+    process.exit(1);
+  }
+  if (!fs.existsSync(kbPath)) {
+    console.error('Missing knowledge_bases.json:', kbPath);
+    process.exit(1);
+  }
+
+  const dbPath = path.join(cwd, 'rag-kb.db');
+  ensureDir(cwd);
+  const db = new Database(dbPath);
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS sessions (
+      id TEXT PRIMARY KEY,
+      title TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      type TEXT DEFAULT 'chat'
+    );
+
+    CREATE TABLE IF NOT EXISTS messages (
+      id TEXT PRIMARY KEY,
+      session_id TEXT NOT NULL,
+      role TEXT NOT NULL,
+      content TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      FOREIGN KEY (session_id) REFERENCES sessions (id) ON DELETE CASCADE
+    );
+
+    CREATE TABLE IF NOT EXISTS documents (
+      id TEXT PRIMARY KEY,
+      yuque_id INTEGER,
+      title TEXT NOT NULL,
+      slug TEXT NOT NULL,
+      url TEXT,
+      namespace TEXT,
+      content_preview TEXT,
+      synced_at INTEGER NOT NULL,
+      parent_uuid TEXT,
+      uuid TEXT,
+      sort_order INTEGER DEFAULT 0,
+      word_count INTEGER DEFAULT 0,
+      updated_at INTEGER,
+      created_at INTEGER,
+      tags TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS knowledge_bases (
+      namespace TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      description TEXT,
+      synced_at INTEGER NOT NULL,
+      last_offset INTEGER DEFAULT 0
+    );
+  `);
+
+  const reset = (process.env.IMPORT_RESET || '').toLowerCase();
+  if (reset === '1' || reset === 'true') {
+    db.exec('DELETE FROM documents; DELETE FROM knowledge_bases;');
+  }
+
+  const kbData = readJson(kbPath) as { knowledge_bases?: KbRow[] };
+  const kbInsert = db.prepare(`
+    INSERT OR REPLACE INTO knowledge_bases (namespace, name, description, synced_at, last_offset)
+    VALUES (@namespace, @name, @description, @synced_at, COALESCE(@last_offset, 0))
+  `);
+  for (const kb of kbData.knowledge_bases || []) {
+    kbInsert.run(kb);
+  }
+
+  const index = readJson(indexPath) as { parts?: string[] };
+  const docInsert = db.prepare(`
+    INSERT OR REPLACE INTO documents
+    (id, yuque_id, title, slug, url, namespace, content_preview, synced_at, parent_uuid, uuid, sort_order, word_count, updated_at, created_at, tags)
+    VALUES (@id, @yuque_id, @title, @slug, @url, @namespace, '', COALESCE(@updated_at, strftime('%s','now')*1000), @parent_uuid, @uuid, COALESCE(@sort_order, 0), COALESCE(@word_count, 0), @updated_at, @created_at, @tags)
+  `);
+
+  let total = 0;
+  for (const part of index.parts || []) {
+    const partPath = path.join(docsDir, part);
+    const arr = readJson(partPath) as DocRow[];
+    for (const d of arr) {
+      docInsert.run(d);
+      total += 1;
+    }
+  }
+
+  console.log(JSON.stringify({
+    inserted_documents: total,
+    inserted_kbs: (kbData.knowledge_bases || []).length,
+    db_path: dbPath
+  }, null, 2));
+}
+
+try {
+  main();
+} catch (e) {
+  console.error(e);
+  process.exit(1);
+}

scripts/push_hf_dataset.py

@@ -0,0 +1,105 @@
+import os
+import sys
+import json
+import pathlib
+from typing import List
+import httpx
+from contextlib import suppress
+
+def _is_ascii(s: str) -> bool:
+    try:
+        s.encode("ascii")
+        return True
+    except Exception:
+        return False
+
+def list_initial_files(root: pathlib.Path, start: int, limit: int, include_license: bool, include_readme: bool) -> List[pathlib.Path]:
+    meta = root / "metadata"
+    docs_dir = meta / "documents"
+    files = [
+        docs_dir / "index.json",
+        meta / "knowledge_bases.json",
+    ]
+    if include_license and (root / "LICENSE").exists():
+        files.append(root / "LICENSE")
+    if include_readme and (root / "README.md").exists():
+        files.append(root / "README.md")
+    index = json.loads((docs_dir / "index.json").read_text("utf8"))
+    parts = index.get("parts", [])
+    slice_parts = parts[start:start + limit]
+    for p in slice_parts:
+        files.append(docs_dir / p)
+    return files
+
+def create_commit(repo_id: str, token: str, root: pathlib.Path, paths: List[pathlib.Path], message: str):
+    from huggingface_hub import HfApi, CommitOperationAdd
+    api = HfApi(token=token)
+    api.create_repo(repo_id=repo_id, repo_type="dataset", private=True, exist_ok=True)
+    ops = []
+    for p in paths:
+        rel = p.relative_to(root)
+        ops.append(CommitOperationAdd(path_in_repo=str(rel), path_or_fileobj=str(p)))
+    def _commit(ops_slice: List[CommitOperationAdd], msg: str):
+        try:
+            api.create_commit(repo_id=repo_id, repo_type="dataset", operations=ops_slice, commit_message=msg)
+        except Exception as e:
+            s = str(e)
+            timeout_like = isinstance(e, httpx.ReadTimeout) or "ReadTimeout" in s or "Timeout" in s
+            if timeout_like and len(ops_slice) > 1:
+                mid = len(ops_slice) // 2
+                left = ops_slice[:mid]
+                right = ops_slice[mid:]
+                _commit(left, msg + " [chunk A]")
+                _commit(right, msg + " [chunk B]")
+            else:
+                raise
+    chunk_size_env = os.getenv("HF_COMMIT_CHUNK_SIZE", "")
+    chunk_size = int(chunk_size_env) if chunk_size_env.isdigit() else 0
+    if chunk_size and chunk_size > 0:
+        for i in range(0, len(ops), chunk_size):
+            _commit(ops[i:i + chunk_size], message + f" [batch {i//chunk_size}]")
+    else:
+        _commit(ops, message)
+
+def dry_run_summary(paths: List[pathlib.Path]):
+    total = 0
+    items = []
+    for p in paths:
+        size = p.stat().st_size
+        total += size
+        items.append((str(p), size))
+    print(json.dumps({"files": [{"path": i[0], "size": i[1]} for i in items], "total_bytes": total}, ensure_ascii=False, indent=2))
+
+def main():
+    root_env = os.getenv("HF_DATASET_ROOT", "")
+    repo_id = os.getenv("HF_REPO_ID", "")
+    token = os.getenv("HF_TOKEN", "") or os.getenv("HUGGINGFACE_TOKEN", "")
+    offset_env = os.getenv("HF_PARTS_OFFSET", "")
+    limit_env = os.getenv("HF_PARTS_LIMIT", "") or os.getenv("HF_INITIAL_PARTS", "")
+    include_license = os.getenv("HF_INCLUDE_LICENSE", "1") not in ("0", "false", "False")
+    include_readme = os.getenv("HF_INCLUDE_README", "1") not in ("0", "false", "False")
+    offset = int(offset_env) if offset_env.isdigit() else 0
+    limit = int(limit_env) if limit_env.isdigit() else 2
+
+    root = pathlib.Path(root_env or pathlib.Path(__file__).resolve().parents[2] / "hf_dataset_rag")
+    paths = list_initial_files(root, offset, limit, include_license, include_readme)
+
+    if not repo_id or not token:
+        print("Missing HF_REPO_ID or HF_TOKEN; performing dry-run")
+        dry_run_summary(paths)
+        sys.exit(0)
+    if not _is_ascii(token) or not _is_ascii(repo_id):
+        print("HF_TOKEN or HF_REPO_ID contains non-ASCII characters")
+        sys.exit(2)
+    os.environ["HF_HUB_USER_AGENT"] = "rag-kb-uploader"
+    os.environ.setdefault("HF_HUB_TIMEOUT", "60")
+    os.environ.setdefault("HF_HUB_READ_TIMEOUT", "60")
+    with suppress(Exception):
+        from huggingface_hub import HfApi
+        HfApi(token=token).whoami()
+
+    create_commit(repo_id, token, root, paths, f"Upload: metadata + parts [{offset}, {offset + limit})")
+    print("Commit completed")
+
+if __name__ == "__main__":
+    main()

scripts/test-notes-pagination.ts

@@ -0,0 +1,33 @@
+import * as dotenv from "dotenv";
+import { SimpleYuqueLoader } from "../src/lib/yuque-service";
+
+dotenv.config({ path: ".env.local" });
+dotenv.config();
+
+async function test() {
+  const token = process.env.YUQUE_TOKEN;
+  if (!token) {
+    console.error("缺少环境变量 YUQUE_TOKEN");
+    process.exit(1);
+  }
+  const loader = new SimpleYuqueLoader(token, "NOTES");
+
+  const limits = [30, 50];
+  for (const limit of limits) {
+    try {
+      const res = await loader.fetchAPI(`/notes?offset=0&limit=${limit}`);
+      const list = Array.isArray(res?.data?.notes) ? res.data.notes : [];
+      console.log(`请求 limit=${limit} -> 返回 ${list.length} 条`);
+      if (list.length > 0) {
+        console.log(`示例ID范围: ${list[0]?.id} ... ${list[list.length - 1]?.id}`);
+      }
+    } catch (e) {
+      console.error(`请求 limit=${limit} 失败:`, e instanceof Error ? e.message : String(e));
+    }
+  }
+}
+
+test().catch((e) => {
+  console.error("测试失败:", e);
+  process.exit(1);
+});

src/app/api/backup/route.ts

@@ -0,0 +1,139 @@
+import { NextResponse } from 'next/server';
+import fs from 'fs';
+import path from 'path';
+import Database from 'better-sqlite3';
+
+export async function POST() {
+  try {
+    const cwd = process.cwd();
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const backupDirName = '备份-语雀数据-JSON';
+    const backupDir = path.join(cwd, backupDirName);
+    
+    if (!fs.existsSync(backupDir)) {
+      fs.mkdirSync(backupDir, { recursive: true });
+    } else {
+      // Clear existing files
+      const files = fs.readdirSync(backupDir);
+      for (const file of files) {
+        fs.unlinkSync(path.join(backupDir, file));
+      }
+    }
+
+    // Connect to the main database
+    const dbPath = path.join(cwd, 'rag-kb.db');
+    if (!fs.existsSync(dbPath)) {
+        return NextResponse.json(
+            { message: 'Main database (rag-kb.db) not found', success: false },
+            { status: 404 }
+        );
+    }
+
+    const db = new Database(dbPath, { readonly: true });
+
+    // Get all namespaces (knowledge bases)
+    // Try to get from knowledge_bases table first, if not, distinct from documents
+    let kbs: { namespace: string, name: string }[] = [];
+    try {
+        const rows = db.prepare('SELECT namespace, name FROM knowledge_bases').all() as { namespace: string, name: string }[];
+        kbs = rows;
+    } catch (e) {
+        console.warn('Could not read knowledge_bases table, falling back to documents', e);
+        const rows = db.prepare('SELECT DISTINCT namespace FROM documents WHERE namespace IS NOT NULL').all() as { namespace: string }[];
+        kbs = rows.map(r => ({ namespace: r.namespace, name: r.namespace }));
+    }
+
+    if (kbs.length === 0) {
+        return NextResponse.json(
+            { message: 'No knowledge bases found to backup', success: false },
+            { status: 404 }
+        );
+    }
+
+    const backupsCreated: string[] = [];
+    
+    // Dataset root for reading content files
+    const hfDatasetRoot = process.env.HF_DATASET_ROOT || path.join(cwd, '..', 'hf_dataset_rag');
+
+    for (const kb of kbs) {
+        const ns = kb.namespace;
+        // Query documents for this namespace
+        const docs = db.prepare(`
+            SELECT title, slug, created_at, updated_at, tags 
+            FROM documents 
+            WHERE namespace = ?
+        `).all(ns) as { title: string, slug: string, created_at: number, updated_at: number, tags: string }[];
+
+        const filteredDocs = docs.filter(doc => {
+            if (!doc.tags) return true;
+            try {
+                const tags = JSON.parse(doc.tags);
+                if (Array.isArray(tags)) {
+                    return !tags.includes('个人资料');
+                }
+            } catch (e) {
+                // If tags is not JSON, check as string (fallback)
+                return !doc.tags.includes('个人资料');
+            }
+            return true;
+        });
+
+        const exportData = filteredDocs.map(doc => {
+            // Try to read content from file
+            let content = '';
+            try {
+                // Construct path: hf_dataset_rag/files/namespace/slug.md
+                // Note: slug might contain subdirectories? usually slug is just filename base.
+                // Based on grep: files/lianmt/jm/ehzgn5-624997.md
+                // So structure is files/namespace/slug.md
+                
+                // Handle namespace with slashes? e.g. lianmt/cq
+                // The grep showed: files/lianmt/jm/...
+                // So if ns is "lianmt/jm", then path is files/lianmt/jm/...
+                
+                const filePath = path.join(hfDatasetRoot, 'files', ns, `${doc.slug}.md`);
+                if (fs.existsSync(filePath)) {
+                    content = fs.readFileSync(filePath, 'utf8');
+                } else {
+                    // Try looking for it without namespace structure if simple?
+                    // But grep confirmed structure.
+                    // content = `(File not found: ${filePath})`;
+                }
+            } catch (err) {
+                console.error(`Error reading file for ${doc.slug}:`, err);
+            }
+
+            return {
+                title: doc.title,
+                content: content,
+                created_at: new Date(doc.created_at).toISOString(),
+                updated_at: doc.updated_at ? new Date(doc.updated_at).toISOString() : null,
+                tags: doc.tags
+            };
+        });
+
+        // Create sanitized filename
+        // Use kb.name (Chinese name) for filename
+        const safeName = (kb.name || ns).replace(/[\/\\:]/g, '_');
+        const fileName = `${safeName}_${timestamp}.json`;
+        const filePath = path.join(backupDir, fileName);
+
+        fs.writeFileSync(filePath, JSON.stringify(exportData));
+        backupsCreated.push(fileName);
+    }
+    
+    db.close();
+
+    return NextResponse.json({
+      message: `JSON export created successfully in folder: ${backupDirName}`,
+      files: backupsCreated,
+      success: true
+    });
+  } catch (error) {
+    console.error('Export failed:', error);
+    return NextResponse.json(
+      { message: 'Export failed', error: String(error), success: false },
+      { status: 500 }
+    );
+  }
+}

src/app/api/chat/route.ts

@@ -40,9 +40,30 @@ const google = createGoogleGenerativeAI({
 // Allow streaming responses up to 300 seconds
 export const maxDuration = 300;
 
+const QUIZ_GENERATION_PROMPT = `请基于知识库内容生成 5 道单选题。**直接返回 JSON 代码块，不要废话。**
+
+要求：
+1. 结果必须封装在 \`\`\`quiz 代码块中。
+2. 选项数组 options 中只包含内容，不要 A/B/C/D 前缀。
+3. explanation 解析需简练（50字以内）。
+
+格式：
+\`\`\`quiz
+[
+  {
+    "id": 1,
+    "question": "...",
+    "options": ["A", "B", "C", "D"],
+    "correctAnswer": 0,
+    "explanation": "..."
+  }
+]
+\`\`\``;
+
 export async function POST(req: Request) {
   try {
-    const { messages, model, useRAG } = await req.json();
+    const body = await req.json();
+    const { messages, model, useRAG, fileInfo } = body;
     
     // Log the incoming request details for debugging
     console.log(`[API] Received chat request. Model: ${model}, useRAG: ${useRAG}`);
@@ -50,6 +71,12 @@ export async function POST(req: Request) {
     // Get the last message to use as the query for RAG
     const lastMessage = messages[messages.length - 1];
     const query = lastMessage.content;
+    
+    // For quiz generation, use a broader query to retrieve relevant context
+    let ragQuery = query;
+    if (query.trim() === '对话试题' || query.trim() === 'Generate Quiz') {
+        ragQuery = "summary 摘要 concept 概念 main point 核心观点";
+    }
 
     // Mock Streaming Response for testing
     // Trigger if query is exactly 'mock-test' OR contains keywords for test generation
@@ -152,18 +179,31 @@ Here is a test quiz to verify the rendering:
     try {
         const docCount = db.prepare('SELECT COUNT(*) as count FROM documents').get() as { count: number };
         const totalWords = db.prepare('SELECT SUM(word_count) as total FROM documents').get() as { total: number };
-        const kbs = db.prepare('SELECT name, namespace FROM knowledge_bases').all() as { name: string, namespace: string }[];
         const lastSync = db.prepare('SELECT MAX(synced_at) as last_sync FROM documents').get() as { last_sync: number };
 
-        const kbList = kbs.map(k => `${k.name} (${k.namespace})`).join(', ');
+        // Get per-KB stats
+        const kbStatsDetails = db.prepare(`
+            SELECT 
+                kb.name, 
+                kb.namespace,
+                COUNT(d.id) as doc_count,
+                SUM(d.word_count) as word_count
+            FROM knowledge_bases kb
+            LEFT JOIN documents d ON kb.namespace = d.namespace
+            GROUP BY kb.namespace
+        `).all() as { name: string, namespace: string, doc_count: number, word_count: number }[];
+
+        const kbList = kbStatsDetails.map(k => `- ${k.name} (${k.namespace}): ${k.doc_count} documents, ${k.word_count || 0} characters`).join('\n');
         const lastSyncDate = lastSync.last_sync ? new Date(lastSync.last_sync).toLocaleString('zh-CN') : 'Never';
 
         kbStats = `
 Knowledge Base Statistics:
 - Total Documents: ${docCount.count}
 - Total Word Count: ${totalWords.total || 0}
-- Knowledge Bases: ${kbList}
 - Last Synced: ${lastSyncDate}
+
+Knowledge Base Distribution:
+${kbList}
 `;
     } catch (e) {
         console.warn("Failed to fetch KB stats:", e);
@@ -179,8 +219,20 @@ Knowledge Base Statistics:
         const vectorStore = await getVectorStore();
         
         // Perform similarity search
-        console.log(`[RAG] Searching for context: "${query.substring(0, 50)}..."`);
-        const results = await vectorStore.similaritySearch(query, 5); // Retrieve top 5 chunks
+        // We fetch more results (k=20) and filter in memory to avoid HNSWLib filter crashes
+        console.log(`[RAG] Searching for context: "${ragQuery.substring(0, 50)}..."${fileInfo?.name ? ` (Raw search for file: ${fileInfo.name})` : ''}`);
+        
+        // Retrieve more candidates if we need to filter by file
+        const searchK = fileInfo?.name ? 20 : 5;
+        let results = await vectorStore.similaritySearch(ragQuery, searchK);
+        
+        // Post-filtering in memory
+         if (fileInfo?.name) {
+              // eslint-disable-next-line @typescript-eslint/no-explicit-any
+              results = results.filter((doc: any) => doc?.metadata?.source === fileInfo.name);
+              // Take top 5 after filtering
+              results = results.slice(0, 5);
+         }
         
         if (results.length > 0) {
           console.log(`[RAG] Found ${results.length} relevant context chunks.`);
@@ -200,21 +252,41 @@ Knowledge Base Statistics:
     // Construct the system prompt with the retrieved context
     let systemPrompt = "";
     
+    // Check if we are in file-specific mode
+    const isFileMode = !!fileInfo?.name;
+
     if (useRAG !== false) {
-      systemPrompt = `You are an intelligent knowledge base assistant.
-      
-      ${kbStats}
+      if (isFileMode) {
+        // File-specific mode system prompt
+        systemPrompt = `You are a helpful assistant analyzing a specific file named "${fileInfo.name}".
+        
+        Context from the file "${fileInfo.name}":
+        ${context ? context : "(No relevant content found in this file for the current query)"}
+        
+        Instructions:
+        1. Answer the user's question ONLY based on the provided context from the file "${fileInfo.name}".
+        2. If the context is empty or does not contain the answer, explicitly state that you cannot find the information in the file "${fileInfo.name}".
+        3. Do NOT use outside knowledge or information about other files/knowledge bases unless explicitly asked.
+        4. Do NOT mention "Knowledge Base Statistics" or other documents.
+        5. Provide clear, accurate responses based strictly on the file content.
+        `;
+      } else {
+        // General Knowledge Base mode system prompt
+        systemPrompt = `You are an intelligent knowledge base assistant.
+        
+        ${kbStats}
 
-      Context from the knowledge base:
-      ${context}
-      
-      Instructions:
-      1. Answer the user's question based on the provided context if relevant.
-      2. If the user asks about the knowledge base itself (e.g., how many documents, statistics), use the "Knowledge Base Statistics" provided above.
-      3. If the context is empty or not relevant, use your general knowledge to answer the question helpfully.
-      4. You can engage in general conversation, creative writing, or coding tasks if requested.
-      5. Provide clear, accurate, and friendly responses.
-      `;
+        Context from the knowledge base:
+        ${context}
+        
+        Instructions:
+        1. Answer the user's question based on the provided context if relevant.
+        2. If the user asks about the knowledge base itself (e.g., how many documents, statistics), use the "Knowledge Base Statistics" provided above.
+        3. If the context is empty or not relevant, use your general knowledge to answer the question helpfully.
+        4. You can engage in general conversation, creative writing, or coding tasks if requested.
+        5. Provide clear, accurate, and friendly responses.
+        `;
+      }
     } else {
       systemPrompt = `You are a helpful AI assistant.
       
@@ -227,6 +299,11 @@ Knowledge Base Statistics:
       `;
     }
 
+    // Check for quiz generation request
+    if (query.trim() === '对话试题' || query.trim() === 'Generate Quiz') {
+        systemPrompt += `\n\nIMPORTANT INSTRUCTION: ${QUIZ_GENERATION_PROMPT}`;
+    }
+
     // Define available models and fallback strategy
     // We prioritize the user-selected model, then fall back to others if it fails
     

src/app/api/documents/route.ts

@@ -1,7 +1,29 @@
 
 import { NextRequest, NextResponse } from 'next/server';
 import db from '@/lib/db';
-import { startYuqueSync, getSyncStatus } from '@/lib/yuque-service';
+import { startYuqueSync, getSyncStatus, stopYuqueSync, backfillNoteTags } from '@/lib/yuque-service';
+
+export async function POST() {
+  try {
+    const status = getSyncStatus();
+    
+    if (status.status === 'running') {
+        return NextResponse.json({ message: 'Sync already running', status });
+    }
+
+    // Start background sync
+    startYuqueSync();
+    
+    return NextResponse.json({ 
+        message: 'Sync started', 
+        status: getSyncStatus() 
+    });
+
+  } catch (error) {
+    console.error('Failed to start sync:', error);
+    return NextResponse.json({ error: 'Failed to start sync' }, { status: 500 });
+  }
+}
 
 export async function GET(req: NextRequest) {
   try {
@@ -11,11 +33,60 @@ export async function GET(req: NextRequest) {
 
     // Select all columns EXCEPT content_preview to reduce payload size, but include length for stats
     // Use word_count if available (more accurate), otherwise fallback to 0 (will be updated on next sync)
+    type DocRow = {
+      id: string;
+      yuque_id: number;
+      title: string;
+      slug: string;
+      url: string;
+      namespace: string;
+      synced_at: number;
+      parent_uuid?: string | null;
+      uuid?: string | null;
+      sort_order?: number | null;
+      content_length?: number | null;
+      updated_at?: number | null;
+      tags?: string | string[] | null;
+    };
+    
     const docs = db.prepare(`
-      SELECT id, yuque_id, title, slug, url, namespace, synced_at, parent_uuid, uuid, sort_order, word_count as content_length, updated_at
+      SELECT id, yuque_id, title, slug, url, namespace, synced_at, parent_uuid, uuid, sort_order, word_count as content_length, updated_at, tags
       FROM documents 
       ORDER BY namespace ASC, sort_order ASC, synced_at DESC
-    `).all();
+    `).all() as DocRow[];
+    
+    const normalizedDocs = docs.map((d: DocRow) => {
+      let tags: string[] = [];
+      if (typeof d.tags === 'string' && d.tags.length > 0) {
+        try {
+          const parsed = JSON.parse(d.tags);
+          if (Array.isArray(parsed)) {
+            tags = parsed.map((x: unknown) => {
+                if (typeof x === 'string') return x;
+                if (typeof x === 'object' && x !== null) {
+                    const obj = x as Record<string, unknown>;
+                    const val = obj.title || obj.name;
+                    return typeof val === 'string' ? val : '';
+                }
+                return '';
+            }).filter((x: string) => x.length > 0);
+          }
+        } catch {
+          tags = [];
+        }
+      } else if (Array.isArray(d.tags)) {
+        tags = d.tags.map((x: unknown) => {
+             if (typeof x === 'string') return x;
+             if (typeof x === 'object' && x !== null) {
+                 const obj = x as Record<string, unknown>;
+                 const val = obj.title || obj.name;
+                 return typeof val === 'string' ? val : '';
+             }
+             return '';
+        }).filter((x: string) => x.length > 0);
+      }
+      return { ...d, tags };
+    });
 
     const kbs = db.prepare(`
       SELECT * FROM knowledge_bases ORDER BY synced_at DESC
@@ -27,7 +98,7 @@ export async function GET(req: NextRequest) {
     // If database is empty or connection fails, return static demo data for HuggingFace/Demo purposes
     // We check docs.length === 0 because even if KBs exist (e.g. from partial sync), if there are no documents,
     // we should show demo data to provide a better initial experience (especially for HF deployments where sync might fail).
-    if (isDemoMode || docs.length === 0) {
+    if (isDemoMode) {
         return NextResponse.json({
             documents: [
                 {
@@ -95,8 +166,13 @@ export async function GET(req: NextRequest) {
         });
     }
 
+    const notesDocs = normalizedDocs.filter((d) => d.namespace === 'NOTES');
+    const hasNoteTags = notesDocs.some((d) => d.tags && d.tags.length > 0);
+    if (!hasNoteTags && process.env.YUQUE_TOKEN) {
+      backfillNoteTags(200, 3).catch(() => {});
+    }
     return NextResponse.json({
-      documents: docs,
+      documents: normalizedDocs,
       knowledgeBases: kbs,
       status: status,
       isDemo: false
@@ -172,24 +248,24 @@ export async function GET(req: NextRequest) {
   }
 }
 
-export async function POST() {
+export async function DELETE() {
   try {
     const status = getSyncStatus();
     
-    if (status.status === 'running') {
-        return NextResponse.json({ message: 'Sync already in progress', status });
+    if (status.status !== 'running') {
+        return NextResponse.json({ message: 'Sync not running', status });
     }
 
-    // Start background sync
-    startYuqueSync();
+    // Stop background sync
+    stopYuqueSync();
     
     return NextResponse.json({ 
-        message: 'Sync started', 
+        message: 'Sync stop requested', 
         status: getSyncStatus() 
     });
 
   } catch (error) {
-    console.error('Failed to start sync:', error);
-    return NextResponse.json({ error: 'Failed to start sync' }, { status: 500 });
+    console.error('Failed to stop sync:', error);
+    return NextResponse.json({ error: 'Failed to stop sync' }, { status: 500 });
   }
 }

src/app/api/health/route.ts

@@ -0,0 +1,43 @@
+import { NextResponse } from 'next/server';
+import db from '@/lib/db';
+import { indexExists } from '@/lib/vector-store';
+
+export async function GET() {
+  const startedAt = Date.now();
+  try {
+    const docCountRow = db.prepare('SELECT COUNT(*) as count FROM documents').get() as { count: number };
+    const kbCountRow = db.prepare('SELECT COUNT(*) as count FROM knowledge_bases').get() as { count: number };
+
+    return NextResponse.json({
+      ok: true,
+      db: {
+        ok: true,
+        documents: docCountRow.count,
+        knowledgeBases: kbCountRow.count,
+      },
+      vectorStore: {
+        ok: indexExists(),
+      },
+      meta: {
+        durationMs: Date.now() - startedAt,
+        timestamp: new Date().toISOString(),
+        uptimeSeconds: Math.floor(process.uptime()),
+      },
+    });
+  } catch (error) {
+    console.error('[Health] Failed:', error);
+    return NextResponse.json(
+      {
+        ok: false,
+        db: { ok: false },
+        vectorStore: { ok: indexExists() },
+        meta: {
+          durationMs: Date.now() - startedAt,
+          timestamp: new Date().toISOString(),
+          uptimeSeconds: Math.floor(process.uptime()),
+        },
+      },
+      { status: 500 }
+    );
+  }
+}

src/app/api/history/sessions/route.ts

@@ -65,10 +65,10 @@ export async function GET(req: NextRequest) {
 // POST: Create a new session
 export async function POST(req: NextRequest) {
   try {
-    const { id, title, createdAt } = await req.json();
+    const { id, title, createdAt, type = 'chat' } = await req.json();
     
-    const stmt = db.prepare('INSERT INTO sessions (id, title, created_at) VALUES (?, ?, ?)');
-    stmt.run(id, title, createdAt);
+    const stmt = db.prepare('INSERT INTO sessions (id, title, created_at, type) VALUES (?, ?, ?, ?)');
+    stmt.run(id, title, createdAt, type);
     
     return NextResponse.json({ success: true });
   } catch (error) {

src/app/api/stats/route.ts

@@ -0,0 +1,248 @@
+
+import { NextRequest, NextResponse } from 'next/server';
+import db from '@/lib/db';
+
+export const dynamic = 'force-dynamic';
+
+export async function GET(req: NextRequest) {
+  try {
+    const { searchParams } = new URL(req.url);
+    const yearParam = searchParams.get('year');
+    
+    // 1. Get available years (Union of created and updated years)
+    const yearsResult = db.prepare(`
+      SELECT DISTINCT strftime('%Y', datetime(ts / 1000, 'unixepoch', 'localtime')) as year 
+      FROM (
+        SELECT updated_at as ts FROM documents WHERE yuque_id != 0 AND updated_at IS NOT NULL
+        UNION
+        SELECT created_at as ts FROM documents WHERE yuque_id != 0 AND created_at IS NOT NULL
+      )
+      ORDER BY year DESC
+    `).all() as { year: string }[];
+    
+    const years = yearsResult.map(y => parseInt(y.year)).filter(y => !isNaN(y));
+
+    // 2. Prepare filter
+    let unionTimeFilterClause = '';
+    let createdTimeFilterClause = '';
+    const paramsUnion: (number | string)[] = [];
+    const paramsCreated: (number | string)[] = [];
+    
+    let startTime = 0;
+    let endTime = 0;
+    let isYearFilter = false;
+
+    if (yearParam && yearParam !== 'all') {
+      const year = parseInt(yearParam);
+      if (!isNaN(year)) {
+          startTime = new Date(year, 0, 1).getTime();
+          endTime = new Date(year + 1, 0, 1).getTime();
+          isYearFilter = true;
+          
+          // Union filter for activity heatmap (Created OR Updated)
+          unionTimeFilterClause = `AND (
+            (updated_at >= ? AND updated_at < ?) 
+            OR 
+            (created_at >= ? AND created_at < ?)
+          )`;
+          paramsUnion.push(startTime, endTime, startTime, endTime);
+          // Created-only filter for annual totals
+          createdTimeFilterClause = `AND (created_at >= ? AND created_at < ?)`;
+          paramsCreated.push(startTime, endTime);
+        }
+    }
+
+    // 3. Get Totals
+    // Get all-time total documents count for context
+    // If specific year selected, count accumulated docs up to the end of that year
+    let allTimeQuery = `
+      SELECT COUNT(*) as count FROM documents 
+      WHERE yuque_id != 0 AND (slug IS NULL OR slug NOT LIKE 'dir-%')
+    `;
+    const allTimeParams: (number | string)[] = [];
+
+    if (isYearFilter) {
+       allTimeQuery += ` AND created_at < ?`;
+       allTimeParams.push(endTime);
+    }
+
+    const allTimeStats = db.prepare(allTimeQuery).get(...allTimeParams) as { count: number };
+
+    // 定义：年度字数仅统计「小记」在该年份内创建或更新过的内容的字数之和（去重）
+    // 这样更贴近“今年写了多少字”的直觉，不把历史长文的字数一次性算入当年。
+    let totalStats: { count: number; words: number } = { count: 0, words: 0 };
+    let docsStats: { count: number; words: number } = { count: 0, words: 0 };
+    let notesStats: { count: number; words: number } = { count: 0, words: 0 };
+    if (isYearFilter) {
+      // 年份视图下，“新增文档数/小记数”遵循“新增”语义：以 created_at 计算
+      const docsCreated = db.prepare(`
+        SELECT COUNT(*) as count, SUM(word_count) as words 
+        FROM documents 
+        WHERE yuque_id != 0 AND namespace != 'NOTES' AND (slug IS NULL OR slug NOT LIKE 'dir-%') ${createdTimeFilterClause}
+      `).get(...paramsCreated) as { count: number, words: number };
+      
+      // 小记按“创建或更新”的活跃口径，满足“小记数应最多”的运营预期
+      // 小记通常短小，且更新代表补充，适合算入年度产出
+      const notesActive = db.prepare(`
+        SELECT COUNT(DISTINCT id) as count, SUM(word_count) as words 
+        FROM documents 
+        WHERE yuque_id != 0 AND namespace = 'NOTES' AND (slug IS NULL OR slug NOT LIKE 'dir-%') ${unionTimeFilterClause}
+      `).get(...paramsUnion) as { count: number, words: number };
+      
+      docsStats = docsCreated;
+      notesStats = notesActive;
+      
+      // 年度字数：
+      // - 小记：统计活跃字数（创建或更新）
+      // - 其他：统计新增字数（仅创建），避免长文修改导致字数统计虚高
+      // 注意：这里仍然使用 created_at。因为语雀 API 的 first_published_at 经常与 created_at 非常接近（仅差几秒），
+      // 无法有效区分“搬运”和“原创”。搬运的文档在语雀系统中确实被视为“在搬运时刻创建”。
+      // 
+      // 针对“过往”和“旧码”两个库在 2025 年有大量“新建”记录（实为搬运）的情况，
+      // 目前最稳妥的逻辑依然是：只算 Created，不算 Updated。
+      // 这样至少剔除了 1500 万字的“旧文修改”水分。
+      // 剩下的 1400 万字“搬运/整理”数据，客观上确实是 2025 年“进入”语雀系统的，
+      // 程序无法区分“我 2025 年写的 3 万字”和“我 2025 年搬运进来的 3 万字”。
+      totalStats = {
+        count: (docsStats.count || 0) + (notesStats.count || 0),
+        words: (docsStats.words || 0) + (notesStats.words || 0),
+      };
+    } else {
+      // 所有年份视图：总字数为所有文档的字数之和
+      const allWords = db.prepare(`
+        SELECT SUM(word_count) as words FROM documents 
+        WHERE yuque_id != 0 AND (slug IS NULL OR slug NOT LIKE 'dir-%')
+      `).get() as { words: number };
+      const docsAll = db.prepare(`
+        SELECT COUNT(*) as count, SUM(word_count) as words FROM documents 
+        WHERE yuque_id != 0 AND namespace != 'NOTES' AND (slug IS NULL OR slug NOT LIKE 'dir-%')
+      `).get() as { count: number, words: number };
+      const notesAll = db.prepare(`
+        SELECT COUNT(*) as count, SUM(word_count) as words FROM documents 
+        WHERE yuque_id != 0 AND namespace = 'NOTES' AND (slug IS NULL OR slug NOT LIKE 'dir-%')
+      `).get() as { count: number, words: number };
+      docsStats = docsAll;
+      notesStats = notesAll;
+      totalStats = {
+        count: (docsStats.count || 0) + (notesStats.count || 0),
+        words: allWords.words || 0
+      };
+    }
+
+    // 4. Get Per-KB Stats
+    // 年份筛选下：小记使用“创建或更新”，其他使用“创建”
+    const kbStats = isYearFilter
+      ? (db.prepare(`
+          SELECT 
+            namespace,
+            SUM(CASE 
+              WHEN namespace = 'NOTES' THEN 1 
+              WHEN created_at >= ? AND created_at < ? THEN 1 
+              ELSE 0 
+            END) as count,
+            SUM(CASE 
+              WHEN namespace = 'NOTES' THEN word_count
+              WHEN created_at >= ? AND created_at < ? THEN word_count
+              ELSE 0 
+            END) as words
+          FROM documents
+          WHERE yuque_id != 0 
+            AND (slug IS NULL OR slug NOT LIKE 'dir-%')
+            ${unionTimeFilterClause}
+          GROUP BY namespace
+        `).all(startTime, endTime, startTime, endTime, ...paramsUnion) as { namespace: string, count: number, words: number }[])
+      : (db.prepare(`
+          SELECT 
+            namespace,
+            COUNT(*) as count,
+            SUM(word_count) as words
+          FROM documents
+          WHERE yuque_id != 0 AND (slug IS NULL OR slug NOT LIKE 'dir-%')
+          GROUP BY namespace
+        `).all() as { namespace: string, count: number, words: number }[]);
+
+    // Get KB Names
+    const kbs = db.prepare('SELECT namespace, name FROM knowledge_bases').all() as { namespace: string, name: string }[];
+    const kbNameMap = new Map(kbs.map(k => [k.namespace, k.name]));
+    
+    const kbStatsWithNames = kbStats.map(s => ({
+      ...s,
+      name: kbNameMap.get(s.namespace) || s.namespace
+    }));
+
+    // 5. Get Heatmap Data (Daily counts of Creation AND Update events)
+    // We want to show activity dots for both creation and updates.
+    
+    let heatmapQuery = '';
+    const heatmapParams: (number | string)[] = [];
+
+    if (isYearFilter) {
+        // Filtered by year，排除目录节点
+        heatmapQuery = `
+          SELECT date, COUNT(*) as count FROM (
+            SELECT strftime('%Y-%m-%d', datetime(updated_at / 1000, 'unixepoch', 'localtime')) as date 
+            FROM documents 
+            WHERE yuque_id != 0 AND updated_at >= ? AND updated_at < ? AND (slug IS NULL OR slug NOT LIKE 'dir-%')
+            
+            UNION ALL
+            
+            SELECT strftime('%Y-%m-%d', datetime(created_at / 1000, 'unixepoch', 'localtime')) as date 
+            FROM documents 
+            WHERE yuque_id != 0 AND created_at >= ? AND created_at < ? AND (slug IS NULL OR slug NOT LIKE 'dir-%')
+          )
+          GROUP BY date
+        `;
+        heatmapParams.push(startTime, endTime, startTime, endTime);
+    } else {
+        // All years - Union all events，排除目录节点
+        heatmapQuery = `
+          SELECT date, COUNT(*) as count FROM (
+            SELECT strftime('%Y-%m-%d', datetime(updated_at / 1000, 'unixepoch', 'localtime')) as date 
+            FROM documents 
+            WHERE yuque_id != 0 AND updated_at IS NOT NULL AND (slug IS NULL OR slug NOT LIKE 'dir-%')
+            
+            UNION ALL
+            
+            SELECT strftime('%Y-%m-%d', datetime(created_at / 1000, 'unixepoch', 'localtime')) as date 
+            FROM documents 
+            WHERE yuque_id != 0 AND created_at IS NOT NULL AND (slug IS NULL OR slug NOT LIKE 'dir-%')
+          )
+          GROUP BY date
+        `;
+    }
+
+    const heatmapData = db.prepare(heatmapQuery).all(...heatmapParams) as { date: string, count: number }[];
+
+    // 6. Annual Stats (For the bottom table verification)
+    // Strictly group by Created At to ensure Sum of Parts == Whole
+    const annualStats = db.prepare(`
+      SELECT 
+        strftime('%Y', datetime(COALESCE(created_at, updated_at) / 1000, 'unixepoch', 'localtime')) as year,
+        COUNT(*) as count,
+        SUM(CASE WHEN namespace = 'NOTES' THEN 1 ELSE 0 END) as notes_count,
+        SUM(word_count) as words
+      FROM documents
+      WHERE yuque_id != 0 AND (slug IS NULL OR slug NOT LIKE 'dir-%')
+      GROUP BY year
+      ORDER BY year DESC
+    `).all() as { year: string; count: number; notes_count: number; words: number }[];
+
+    return NextResponse.json({
+      years,
+      stats: {
+        totalDocs: totalStats.count || 0,
+        totalWords: totalStats.words || 0,
+        allTimeDocs: allTimeStats.count,
+        docsCount: docsStats.count || 0,
+        notesCount: notesStats.count || 0,
+        kbStats: kbStatsWithNames,
+        heatmap: heatmapData,
+        annualStats // Add this field
+      }
+    });
+
+  } catch (error) {
+    console.error('Failed to fetch stats:', error);
+    return NextResponse.json({ error: 'Failed to fetch statistics' }, { status: 500 });
+  }
+}

src/app/knowledge/page.tsx

@@ -3,7 +3,7 @@
 
 import { useState, useEffect, useMemo, Suspense, ReactNode, useRef } from 'react';
 import { useLanguage } from '@/contexts/LanguageContext';
-import { ArrowLeft, RefreshCw, Search, Database, ExternalLink, ChevronRight, ChevronDown, Home, Palette, List } from 'lucide-react';
+import { ArrowLeft, RefreshCw, Search, Database, ExternalLink, ChevronRight, ChevronDown, Home, List, Square, ArrowUp, MoreVertical, BarChart2, Save, Tag, X } from 'lucide-react';
 import ReactMarkdown from 'react-markdown';
 import rehypeRaw from 'rehype-raw';
 import remarkGfm from 'remark-gfm';
@@ -129,6 +129,7 @@ interface Document {
   sort_order?: number;
   content_length?: number;
   updated_at?: number;
+  tags?: string[];
 }
 
 interface TreeNode {
@@ -178,17 +179,26 @@ const TreeNodeView = ({
     node, 
     level = 0, 
     onSelect, 
-    selectedUuid 
+    selectedUuid,
+    variant
 }: { 
     node: TreeNode, 
     level?: number, 
     onSelect: (node: TreeNode) => void,
-    selectedUuid?: string
+    selectedUuid?: string,
+    variant?: 'sidebar' | 'main'
 }) => {
   const [isOpen, setIsOpen] = useState(false);
   const hasChildren = node.children.length > 0;
   const isSelected = node.doc.uuid === selectedUuid;
 
+  // Helper to format date
+  const formatDate = (timestamp?: number) => {
+    if (!timestamp) return '';
+    const date = new Date(timestamp);
+    return `${date.getFullYear()}-${(date.getMonth()+1).toString().padStart(2, '0')}-${date.getDate().toString().padStart(2, '0')} ${date.getHours().toString().padStart(2, '0')}:${date.getMinutes().toString().padStart(2, '0')}`;
+  };
+
   // Use refs to track mounted state and last processed selection
   // This prevents auto-expansion when data refreshes but selection hasn't changed
   const isMounted = useRef(false);
@@ -252,9 +262,18 @@ const TreeNodeView = ({
             {isOpen ? <ChevronDown className="w-3 h-3" /> : <ChevronRight className="w-3 h-3" />}
         </div>
         
-        <div className="flex-1 flex items-center gap-2 min-w-0">
-            <span className="truncate">{node.doc.title}</span>
+        <div className={`flex items-center gap-2 min-w-0 ${variant === 'main' ? '' : 'flex-1'}`}>
+            <span className={variant === 'main' ? 'truncate text-sm/relaxed' : 'truncate'} title={node.doc.title}>{node.doc.title}</span>
         </div>
+        
+        {variant === 'main' && node.doc.yuque_id !== 0 && (
+            <>
+                <div className="flex-1 min-w-[1rem] mx-2 border-b border-dotted border-gray-300 dark:border-gray-700 h-[1px] relative top-[2px] opacity-50" />
+                <span className="text-xs text-gray-400 shrink-0 font-mono">
+                    {formatDate(node.doc.updated_at || node.doc.synced_at)}
+                </span>
+            </>
+        )}
       </div>
       
       {isOpen && hasChildren && (
@@ -266,6 +285,7 @@ const TreeNodeView = ({
                 level={level + 1} 
                 onSelect={onSelect}
                 selectedUuid={selectedUuid}
+                variant={variant}
             />
           ))}
         </div>
@@ -318,7 +338,40 @@ function KnowledgePageContent() {
   // State initialization flag
   const [isInitialized, setIsInitialized] = useState(false);
   const isManualNav = useRef(false);
+  const mainContentRef = useRef<HTMLDivElement>(null);
+    const tagInputRef = useRef<HTMLInputElement>(null);
+  const [showScrollTop, setShowScrollTop] = useState(false);
   const [treeVersion, setTreeVersion] = useState(0);
+  const [visibleCount, setVisibleCount] = useState(30);
+  const [sidebarVisibleCount, setSidebarVisibleCount] = useState(30);
+  const [isHoveringSync, setIsHoveringSync] = useState(false);
+  const [isStatsMenuOpen, setIsStatsMenuOpen] = useState(false);
+  const [isBackingUp, setIsBackingUp] = useState(false);
+  
+  const handleBackup = async () => {
+     if (isBackingUp) return;
+     setIsBackingUp(true);
+     try {
+       const res = await fetch('/api/backup', { method: 'POST' });
+       const data = await res.json();
+       if (res.ok) {
+         alert(`导出 JSON 成功！\n文件已保存到「备份-语雀数据-JSON」文件夹:\n${data.files.join('\n')}`);
+       } else {
+         alert(`导出失败: ${data.message}`);
+       }
+     } catch (error) {
+       console.error('Export failed:', error);
+      alert('导出请求失败，请检查控制台。');
+    } finally {
+      setIsBackingUp(false);
+    }
+  };
+
+  useEffect(() => {
+    setVisibleCount(30);
+    setSidebarVisibleCount(30);
+  }, [currentKbNamespace]);
+
 
   const handleCollapseAll = (e: React.MouseEvent) => {
     e.stopPropagation();
@@ -340,17 +393,22 @@ function KnowledgePageContent() {
           setIsDemoMode(data.isDemo);
       }
       
-      // Initial KB selection logic
-      if (data.knowledgeBases && data.knowledgeBases.length > 0) {
-        // Check URL first
-        const kbParam = searchParams.get('kb');
-        // Verify if the kbParam actually exists in the fetched knowledge bases
-        const kbExists = kbParam && data.knowledgeBases.some((k: KnowledgeBase) => k.namespace === kbParam);
-        
-        if (kbExists) {
-          if (!currentKbNamespace) setCurrentKbNamespace(kbParam);
-        } else {
-          // If no KB selected, or selected KB doesn't exist (e.g. switching modes), select the first one
+      // Knowledge base selection logic
+      // Stabilize current selection during sync or after initialization to prevent flicker
+      if (!isInitialized) {
+        if (data.knowledgeBases && data.knowledgeBases.length > 0) {
+          const kbParam = searchParams.get('kb');
+          const kbExists = kbParam && data.knowledgeBases.some((k: KnowledgeBase) => k.namespace === kbParam);
+          if (kbExists) {
+            if (!currentKbNamespace) setCurrentKbNamespace(kbParam);
+          } else if (!currentKbNamespace) {
+            setCurrentKbNamespace(data.knowledgeBases[0].namespace);
+          }
+        }
+      } else {
+        // Do not auto-switch KB while syncing even if current is temporarily missing
+        // Only set default if nothing is selected and we have KBs
+        if (!currentKbNamespace && data.knowledgeBases && data.knowledgeBases.length > 0) {
           setCurrentKbNamespace(data.knowledgeBases[0].namespace);
         }
       }
@@ -368,6 +426,65 @@ function KnowledgePageContent() {
 
   const treeRoots = useMemo(() => buildTree(filteredDocuments), [filteredDocuments]);
 
+  // Tag filter state
+  const [selectedTag, setSelectedTag] = useState<string>('');
+  const [isTagDropdownOpen, setIsTagDropdownOpen] = useState(false);
+  const [isInputFocused, setIsInputFocused] = useState(false);
+  const [tagSearchTerm, setTagSearchTerm] = useState('');
+
+  const allTags = useMemo(() => {
+    if (!documents || documents.length === 0) return [];
+    
+    const tagMap = new Map<string, number>();
+    let untaggedCount = 0;
+
+    // Use filteredDocuments to only show tags relevant to current KB
+    filteredDocuments.forEach(doc => {
+      if (doc.tags && Array.isArray(doc.tags) && doc.tags.length > 0) {
+        doc.tags.forEach(t => {
+          if (t) tagMap.set(t, (tagMap.get(t) || 0) + 1);
+        });
+      } else {
+        untaggedCount++;
+      }
+    });
+
+    const tagsList = Array.from(tagMap.entries())
+        .map(([name, count]) => ({ name, count }));
+
+    if (untaggedCount > 0) {
+        tagsList.push({ name: '无标签', count: untaggedCount });
+    }
+
+    return tagsList.sort((a, b) => b.count - a.count);
+  }, [filteredDocuments, documents]);
+
+  const mainAreaRoots = useMemo(() => {
+    if (!selectedTag) return treeRoots;
+    
+    let taggedDocs;
+    if (selectedTag === '无标签') {
+        taggedDocs = filteredDocuments.filter(doc => 
+            !doc.tags || !Array.isArray(doc.tags) || doc.tags.length === 0
+        );
+    } else {
+        taggedDocs = filteredDocuments.filter(doc => 
+            doc.tags && Array.isArray(doc.tags) && doc.tags.includes(selectedTag)
+        );
+    }
+    
+    // Rebuild tree for the filtered view
+    // Note: If a child matches but parent doesn't, it becomes a root in this new tree
+    return buildTree(taggedDocs);
+  }, [treeRoots, filteredDocuments, selectedTag]);
+
+  useEffect(() => {
+    setSelectedTag('');
+    setIsTagDropdownOpen(false);
+    setTagSearchTerm('');
+  }, [currentKbNamespace]);
+ 
+
   // Restore state from URL on load and when documents are ready
   useEffect(() => {
     if (documents.length > 0 && !isInitialized) {
@@ -480,6 +597,16 @@ function KnowledgePageContent() {
     return () => clearInterval(interval);
   }, [syncStatus.status, searchParams.get('demo')]);
 
+  const handleStopSync = async () => {
+    try {
+      await fetch('/api/documents', { method: 'DELETE' });
+      // Trigger immediate refresh to get updated status
+      fetchDocuments();
+    } catch (error) {
+      console.error('Failed to stop sync:', error);
+    }
+  };
+
   const handleSync = async () => {
     try {
       await fetch('/api/documents', { method: 'POST' });
@@ -517,28 +644,58 @@ function KnowledgePageContent() {
                         </div>
                     )}
                     <button
-                        onClick={handleSync}
-                        disabled={syncStatus.status === 'running'}
+                        onClick={handleBackup}
+                        disabled={isBackingUp}
+                        className="flex items-center gap-2 px-3 py-1.5 text-sm rounded-md font-medium transition-all hover:bg-gray-100 dark:hover:bg-gray-800 text-gray-500 hover:text-gray-900 dark:text-gray-400 dark:hover:text-gray-100 disabled:opacity-50 disabled:cursor-not-allowed"
+                        title="备份语雀数据到本地"
+                    >
+                        {isBackingUp ? (
+                             <RefreshCw className="w-4 h-4 animate-spin" />
+                        ) : (
+                             <Save className="w-4 h-4" />
+                        )}
+                        <span>导出 JSON</span>
+                    </button>
+                    <button
+                        onClick={syncStatus.status === 'running' ? handleStopSync : handleSync}
+                        onMouseEnter={() => setIsHoveringSync(true)}
+                        onMouseLeave={() => setIsHoveringSync(false)}
                         className={`flex items-center gap-2 px-3 py-1.5 text-sm rounded-md font-medium transition-all
                         ${syncStatus.status === 'running' 
-                            ? 'text-gray-400 cursor-not-allowed' 
+                            ? (isHoveringSync ? 'bg-red-50 text-red-600 dark:bg-red-900/20 dark:text-red-400' : 'text-primary-600 dark:text-primary-400 bg-primary-50 dark:bg-primary-900/20')
                             : 'hover:bg-gray-100 dark:hover:bg-gray-800 text-gray-500 hover:text-gray-900 dark:text-gray-400 dark:hover:text-gray-100'
                         }`}
                     >
-                        <RefreshCw className={`w-4 h-4 ${syncStatus.status === 'running' ? 'animate-spin' : ''}`} />
-                        {syncStatus.status === 'running' ? '同步中' : '同步'}
+                        {syncStatus.status === 'running' ? (
+                            isHoveringSync ? (
+                                <>
+                                    <Square className="w-4 h-4 fill-current" />
+                                    <span>停止同步</span>
+                                </>
+                            ) : (
+                                <>
+                                    <RefreshCw className="w-4 h-4 animate-spin" />
+                                    <span>同步中</span>
+                                </>
+                            )
+                        ) : (
+                            <>
+                                <RefreshCw className="w-4 h-4" />
+                                <span>{syncStatus.message?.includes('停止') ? '继续同步' : '同步'}</span>
+                            </>
+                        )}
                     </button>
                 </div>
             </div>
             
             {/* Sync Progress Bar (Slim) and Status Message */}
-            {syncStatus.status === 'running' && (
+            {(syncStatus.status === 'running' || syncStatus.message?.includes('停止') || syncStatus.status === 'error') && (
                 <div className="w-full border-t border-gray-100 dark:border-gray-800">
-                    <div className="px-4 py-2 bg-primary-50/50 dark:bg-primary-900/10">
-                        <div className="flex items-center justify-center text-xs text-primary-700 dark:text-primary-300 mb-1.5 gap-2">
+                    <div className={`px-4 py-2 ${syncStatus.status === 'error' ? 'bg-red-50/50 dark:bg-red-900/10' : 'bg-primary-50/50 dark:bg-primary-900/10'}`}>
+                        <div className={`flex items-center justify-center text-xs ${syncStatus.status === 'error' ? 'text-red-700 dark:text-red-300' : 'text-primary-700 dark:text-primary-300'} mb-1.5 gap-2`}>
                             <span className="relative flex h-2 w-2">
-                              <span className="animate-ping absolute inline-flex h-full w-full rounded-full bg-primary-400 opacity-75"></span>
-                              <span className="relative inline-flex rounded-full h-2 w-2 bg-primary-500"></span>
+                              <span className={`animate-ping absolute inline-flex h-full w-full rounded-full opacity-75 ${syncStatus.status === 'error' ? 'bg-red-400' : 'bg-primary-400'}`}></span>
+                              <span className={`relative inline-flex rounded-full h-2 w-2 ${syncStatus.status === 'error' ? 'bg-red-500' : 'bg-primary-500'}`}></span>
                             </span>
                             <span className="font-medium">{syncStatus.message || '正在同步...'}</span>
                             <span className="mx-1 opacity-50">|</span>
@@ -549,7 +706,7 @@ function KnowledgePageContent() {
                         
                         <div className="h-2 w-full bg-gray-200 dark:bg-gray-700 rounded-full overflow-hidden">
                             <div 
-                                className="h-full bg-primary-600 transition-all duration-500 ease-out rounded-full"
+                                className={`h-full transition-all duration-500 ease-out rounded-full ${syncStatus.status === 'error' ? 'bg-red-600' : 'bg-primary-600'}`}
                                 style={{ width: `${(syncStatus.processed / (syncStatus.total || 1)) * 100}%` }}
                             />
                         </div>
@@ -561,7 +718,7 @@ function KnowledgePageContent() {
         {/* Main Content Area */}
         <div className="flex flex-1 overflow-hidden">
             {/* Sidebar */}
-            <div className="w-64 border-r border-gray-200 dark:border-gray-800 bg-gray-50/50 dark:bg-gray-900/50 flex flex-col overflow-hidden shrink-0">
+            <div className="w-64 border-r border-gray-200 dark:border-gray-800 bg-gray-50/50 dark:bg-gray-900/50 flex flex-col z-20 shrink-0">
                 <div className="px-3 pt-3 pb-1">
                     {/* Knowledge Base Switcher */}
                     <div className="relative mb-2 px-3">
@@ -578,7 +735,40 @@ function KnowledgePageContent() {
                                  }}
                              >
                                  <ChevronDown className="w-4 h-4 text-gray-500" />
-                             </div>
+                            </div>
+                            
+                            <div className="relative ml-auto">
+                                <div 
+                                    className="p-1 rounded-sm hover:bg-gray-200 dark:hover:bg-gray-700 cursor-pointer transition-colors"
+                                    onClick={(e) => {
+                                        e.stopPropagation();
+                                        setIsStatsMenuOpen(!isStatsMenuOpen);
+                                    }}
+                                >
+                                    <MoreVertical className="w-4 h-4 text-gray-500" />
+                                </div>
+                                {isStatsMenuOpen && (
+                                    <>
+                                        <div 
+                                            className="fixed inset-0 z-10" 
+                                            onClick={(e) => {
+                                                e.stopPropagation();
+                                                setIsStatsMenuOpen(false);
+                                            }}
+                                        />
+                                        <div className="absolute left-full top-0 ml-2 w-32 bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-700 rounded-lg shadow-lg z-20 py-1">
+                                            <Link 
+                                                href="/knowledge/stats"
+                                                className="flex items-center gap-2 px-3 py-2 text-sm text-gray-700 dark:text-gray-300 hover:bg-gray-50 dark:hover:bg-gray-700/50 w-full"
+                                                onClick={() => setIsStatsMenuOpen(false)}
+                                            >
+                                                <BarChart2 className="w-4 h-4" />
+                                                <span>统计</span>
+                                            </Link>
+                                        </div>
+                                    </>
+                                )}
+                            </div>
                         </div>
 
                         {isKbDropdownOpen && (
@@ -655,12 +845,22 @@ function KnowledgePageContent() {
                         <span className="font-medium">{t('outline')}</span>
                     </div>
                 </div>
-                <div className="flex-1 overflow-y-auto px-3 pb-4 scrollbar-thin">
+                <div 
+                    className="flex-1 overflow-y-auto px-3 pb-4 scrollbar-thin"
+                    onScroll={(e) => {
+                        const { scrollTop, scrollHeight, clientHeight } = e.currentTarget;
+                        if (scrollHeight - scrollTop - clientHeight < 100) {
+                            if (sidebarVisibleCount < treeRoots.length) {
+                                setSidebarVisibleCount(prev => Math.min(prev + 30, treeRoots.length));
+                            }
+                        }
+                    }}
+                >
                     {isLoading ? (
                         <div className="p-4 text-center text-sm text-gray-500">{t('loading')}</div>
                     ) : (
                         <div className="flex flex-col gap-0.5">
-                            {treeRoots.map(node => (
+                            {(currentKbNamespace === 'NOTES' ? treeRoots.slice(0, sidebarVisibleCount) : treeRoots).map(node => (
                                 <TreeNodeView 
                                     key={`${node.doc.uuid}-${treeVersion}`}
                                     node={node} 
@@ -668,13 +868,39 @@ function KnowledgePageContent() {
                                     selectedUuid={selectedNode?.doc.uuid}
                                 />
                             ))}
+                            {currentKbNamespace === 'NOTES' && sidebarVisibleCount < treeRoots.length && (
+                                <div className="py-2 text-center text-xs text-gray-400">
+                                    ...
+                                </div>
+                            )}
                         </div>
                     )}
                 </div>
             </div>
 
             {/* Right Panel */}
-            <div className="flex-1 overflow-y-auto bg-white dark:bg-gray-900 p-8">
+            <div 
+                ref={mainContentRef}
+                className="flex-1 overflow-y-auto bg-white dark:bg-gray-900 p-8 scroll-smooth"
+                onScroll={(e) => {
+                    const { scrollTop, scrollHeight, clientHeight } = e.currentTarget;
+                    
+                    // Toggle Back to Top button
+                    if (scrollTop > 300) {
+                        if (!showScrollTop) setShowScrollTop(true);
+                    } else {
+                        if (showScrollTop) setShowScrollTop(false);
+                    }
+
+                    if (scrollHeight - scrollTop - clientHeight < 100) {
+                        const targetRoots = currentKbNamespace === 'NOTES' ? mainAreaRoots : treeRoots;
+                        if (visibleCount < targetRoots.length) {
+                            setVisibleCount(prev => Math.min(prev + 30, targetRoots.length));
+                        }
+                    }
+                }}
+            >
+                
                 {searchTerm ? (
                      <div className="max-w-4xl mx-auto">
                         <h2 className="text-xl font-bold mb-6">搜索结果: &quot;{searchTerm}&quot;</h2>
@@ -715,13 +941,15 @@ function KnowledgePageContent() {
                         <div className="flex-1 min-w-0 max-w-3xl">
                         {/* Breadcrumb / Header */}
                         <div className="mb-8 pb-6 border-b border-gray-100 dark:border-gray-800">
-                             <div className="flex items-center gap-3 mb-10">
-                                <div>
-                                    <h1 className="text-4xl font-bold text-gray-900 dark:text-gray-100">
-                                        {selectedNode.doc.title}
-                                    </h1>
+                             {selectedNode.doc.namespace !== 'NOTES' && (
+                                <div className="flex items-center gap-3 mb-10">
+                                    <div>
+                                        <h1 className="text-4xl font-bold text-gray-900 dark:text-gray-100">
+                                            {selectedNode.doc.title}
+                                        </h1>
+                                    </div>
                                 </div>
-                             </div>
+                             )}
                              
                              {/* Content */}
                             {isLoadingContent ? (
@@ -750,6 +978,19 @@ function KnowledgePageContent() {
                                                 <ExternalLink className="w-3 h-3" /> 语雀链接
                                             </a>
                                         )}
+                                        {Array.isArray(selectedNode.doc.tags) && selectedNode.doc.tags.length > 0 && (
+                                            <div className="flex items-center gap-2">
+                                                <Tag className="w-3 h-3" />
+                                                {selectedNode.doc.tags.map(tag => (
+                                                    <span
+                                                        key={tag}
+                                                        className="px-1.5 py-0.5 text-[11px] rounded bg-gray-100 dark:bg-gray-800 text-gray-600 dark:text-gray-300 border border-gray-200 dark:border-gray-700"
+                                                    >
+                                                        #{tag}
+                                                    </span>
+                                                ))}
+                                            </div>
+                                        )}
                                     </div>
                                 </>
                             ) : (
@@ -796,12 +1037,125 @@ function KnowledgePageContent() {
                     </div>
                 ) : (
                     /* Home View */
-                    <div className="max-w-4xl mx-auto pt-2">
+                    <div className="max-w-5xl mx-auto px-4 pt-2">
                         <div className="mb-8">
-                            <h1 className="text-2xl font-bold text-gray-900 dark:text-gray-100 mb-3">
-                                {knowledgeBases.find(kb => kb.namespace === currentKbNamespace)?.name || '知识库'}
-                            </h1>
-                            <div className="flex items-center gap-4 text-sm text-gray-500">
+                            <div className="flex items-center justify-between">
+                                <h1 className="text-2xl font-bold text-gray-900 dark:text-gray-100">
+                                    {knowledgeBases.find(kb => kb.namespace === currentKbNamespace)?.name || '知识库'}
+                                </h1>
+                                {currentKbNamespace === 'NOTES' && (
+                                    <div className="relative w-64">
+                                        <Tag className="absolute left-3 top-1/2 -translate-y-1/2 w-4 h-4 text-gray-400 z-10 pointer-events-none" />
+                                        <input
+                                            ref={tagInputRef}
+                                            type="text"
+                                            className={`w-full pl-9 pr-10 py-1.5 text-sm rounded-md border transition-colors outline-none
+                                                ${isTagDropdownOpen 
+                                                    ? 'border-primary-500 ring-1 ring-primary-500 bg-white dark:bg-gray-800' 
+                                                    : 'border-gray-200 dark:border-gray-700 bg-white dark:bg-gray-800 hover:bg-gray-50 dark:hover:bg-gray-700'}
+                                                ${selectedTag ? 'text-primary-600 dark:text-primary-400 font-medium' : 'text-gray-700 dark:text-gray-300'}
+                                            `}
+                                            placeholder={allTags.length > 0 ? "输入筛选标签..." : "暂无标签"}
+                                            value={tagSearchTerm}
+                                            onChange={(e) => {
+                                                setTagSearchTerm(e.target.value);
+                                                setIsTagDropdownOpen(true);
+                                            }}
+                                            onFocus={() => {
+                                                setIsTagDropdownOpen(true);
+                                                setIsInputFocused(true);
+                                            }}
+                                            onBlur={() => setIsInputFocused(false)}
+                                            onClick={(e) => {
+                                                e.stopPropagation();
+                                                setIsTagDropdownOpen(true);
+                                            }}
+                                            disabled={allTags.length === 0}
+                                        />
+                                        <div 
+                                            className="absolute right-1 top-1/2 -translate-y-1/2 p-2 cursor-pointer hover:bg-gray-100 dark:hover:bg-gray-700 rounded-md text-gray-400 hover:text-gray-600 transition-colors z-10"
+                                            onMouseDown={(e) => e.preventDefault()}
+                                            onClick={(e) => {
+                                                e.stopPropagation();
+                                                if (tagSearchTerm) {
+                                                    setTagSearchTerm('');
+                                                    setSelectedTag('');
+                                                    setIsTagDropdownOpen(true);
+                                                    tagInputRef.current?.focus();
+                                                } else {
+                                                    if (isTagDropdownOpen) {
+                                                        setIsTagDropdownOpen(false);
+                                                    } else {
+                                                        setIsTagDropdownOpen(true);
+                                                        tagInputRef.current?.focus();
+                                                    }
+                                                }
+                                            }}
+                                        >
+                                            {tagSearchTerm ? (
+                                                <X className="w-3 h-3" />
+                                            ) : (
+                                                <ChevronDown className={`w-3 h-3 transition-transform ${isTagDropdownOpen ? 'rotate-180' : ''}`} />
+                                            )}
+                                        </div>
+
+                                        {isTagDropdownOpen && (
+                                            <>
+                                                <div 
+                                                    className="fixed inset-0 z-0" 
+                                                    onClick={(e) => {
+                                                        e.stopPropagation();
+                                                        setIsTagDropdownOpen(false);
+                                                        setTagSearchTerm(selectedTag || '');
+                                                    }}
+                                                />
+                                                <div className="absolute left-0 right-0 top-full mt-1 bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-700 rounded-lg shadow-lg z-20 py-1 max-h-60 overflow-y-auto">
+                                                    {(!tagSearchTerm || '全部标签'.includes(tagSearchTerm)) && (
+                                                        <button
+                                                            className={`w-full text-left px-3 py-2 text-sm hover:bg-gray-50 dark:hover:bg-gray-700/50 flex items-center justify-between
+                                                                ${!selectedTag ? 'text-primary-600 bg-primary-50 dark:bg-primary-900/20' : 'text-gray-700 dark:text-gray-300'}
+                                                            `}
+                                                            onClick={() => {
+                                                                setSelectedTag('');
+                                                                setTagSearchTerm('');
+                                                                setIsTagDropdownOpen(false);
+                                                            }}
+                                                        >
+                                                            <span>全部标签</span>
+                                                            {!selectedTag && <div className="w-2 h-2 rounded-full bg-primary-600" />}
+                                                        </button>
+                                                    )}
+                                                    {allTags
+                                                        .filter(tag => tag.name.toLowerCase().includes(tagSearchTerm.toLowerCase()))
+                                                        .map(tag => (
+                                                        <button
+                                                            key={tag.name}
+                                                            className={`w-full text-left px-3 py-2 text-sm hover:bg-gray-50 dark:hover:bg-gray-700/50 flex items-center justify-between gap-2
+                                                                ${selectedTag === tag.name ? 'text-primary-600 bg-primary-50 dark:bg-primary-900/20' : 'text-gray-700 dark:text-gray-300'}
+                                                            `}
+                                                            onClick={() => {
+                                                                setSelectedTag(tag.name);
+                                                                setTagSearchTerm(tag.name);
+                                                                setIsTagDropdownOpen(false);
+                                                            }}
+                                                        >
+                                                            <span className="truncate flex-1">{tag.name}</span>
+                                                            <span className="text-xs text-gray-400 shrink-0 tabular-nums">{tag.count}</span>
+                                                            {selectedTag === tag.name && <div className="w-2 h-2 rounded-full bg-primary-600 shrink-0" />}
+                                                        </button>
+                                                    ))}
+                                                    {allTags.filter(tag => tag.name.toLowerCase().includes(tagSearchTerm.toLowerCase())).length === 0 && !('全部标签'.includes(tagSearchTerm)) && (
+                                                        <div className="px-3 py-2 text-xs text-gray-400 text-center">
+                                                            未找到相关标签
+                                                        </div>
+                                                    )}
+                                                </div>
+                                            </>
+                                        )}
+                                    </div>
+                                )}
+                            </div>
+                            <div className="mt-3 flex items-center gap-4 text-sm text-gray-500">
                                 <span>{filteredDocuments.filter(d => d.yuque_id !== 0).length} {t('documents')}</span>
                                 <span className="text-gray-300 dark:text-gray-700">|</span>
                                 <span>{(filteredDocuments.filter(d => d.yuque_id !== 0).reduce((acc, d) => acc + (d.content_length || 0), 0) / 10000).toFixed(1)} {language === 'zh' ? '万字' : '0k chars'}</span>
@@ -809,16 +1163,31 @@ function KnowledgePageContent() {
                         </div>
                         
                         <div className="flex flex-col gap-0.5 mt-6">
-                            {treeRoots.map(node => (
+                            {(currentKbNamespace === 'NOTES' ? mainAreaRoots.slice(0, visibleCount) : mainAreaRoots).map(node => (
                                 <TreeNodeView 
                                     key={`${node.doc.uuid}-${treeVersion}`}
                                     node={node} 
                                     onSelect={setSelectedNode}
+                                    variant="main"
                                 />
                             ))}
+                            {currentKbNamespace === 'NOTES' && visibleCount < mainAreaRoots.length && (
+                                <div className="py-4 text-center text-sm text-gray-400">
+                                    加载更多...
+                                </div>
+                            )}
                         </div>
                     </div>
                 )}
+
+                {/* Back to Top Button */}
+                <button
+                    onClick={() => mainContentRef.current?.scrollTo({ top: 0, behavior: 'smooth' })}
+                    className={`fixed bottom-8 right-8 p-3 bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-700 shadow-lg rounded-full text-gray-500 hover:text-primary-600 dark:text-gray-400 dark:hover:text-primary-400 transition-all z-50 duration-300 ${showScrollTop ? 'opacity-100 translate-y-0' : 'opacity-0 translate-y-10 pointer-events-none'}`}
+                    title="回到顶部"
+                >
+                    <ArrowUp className="w-5 h-5" />
+                </button>
             </div>
         </div>
     </div>

src/app/knowledge/stats/page.tsx

@@ -0,0 +1,1104 @@
+
+"use client";
+
+import { useState, useEffect, useRef, useCallback } from 'react';
+import { ArrowLeft, Calendar, FileText, Type, BarChart2, X, Sparkles, Share2, Download, Copy } from 'lucide-react';
+import { useRouter } from 'next/navigation';
+
+interface HeatmapData {
+  date: string;
+  count: number;
+}
+
+interface KbStat {
+  namespace: string;
+  name: string;
+  count: number;
+  words: number;
+}
+
+interface StatsData {
+  years: number[];
+  stats: {
+    totalDocs: number;
+    totalWords: number;
+    allTimeDocs?: number;
+    docsCount?: number;
+    notesCount?: number;
+    kbStats: KbStat[];
+    heatmap: HeatmapData[];
+    annualStats?: { year: string; count: number; notes_count: number; words: number }[];
+  };
+}
+
+const AnnualReportModal = ({ 
+    isOpen, 
+    onClose, 
+    year, 
+    data 
+}: { 
+    isOpen: boolean; 
+    onClose: () => void; 
+    year: number | 'all';
+    data: StatsData['stats'];
+}) => {
+    const [sharePreviewOpen, setSharePreviewOpen] = useState(false);
+    const [shareImageUrl, setShareImageUrl] = useState<string | null>(null);
+    const [generating, setGenerating] = useState(false);
+    const [copyStatus, setCopyStatus] = useState<'idle' | 'success' | 'error'>('idle');
+
+    // Calculate insights
+    const totalDocs = data.totalDocs;
+    const totalWords = data.totalWords;
+    
+    // Sort heatmap data by date
+    const sortedHeatmap = [...data.heatmap].sort((a, b) => new Date(a.date).getTime() - new Date(b.date).getTime());
+    
+    // 1. Active Days
+    const activeDays = sortedHeatmap.length;
+    const isLeapYear = (y: number) => (y % 4 === 0 && y % 100 !== 0) || (y % 400 === 0);
+    const daysInYear = year === 'all' ? 365 : (typeof year === 'number' && isLeapYear(year) ? 366 : 365);
+    const isFullAttendance = year !== 'all' && activeDays >= daysInYear;
+
+    // 3. Day of Week (removed cards below no longer use this)
+    
+    const displayYear = year === 'all' ? '全部年份' : `${year}年`;
+    if (!isOpen) return null;
+
+    const generateSvg = () => {
+        const w = 1080;
+        const topKb = [...data.kbStats]
+            .sort((a, b) => b.words - a.words)
+            .slice(0, 6);
+        const totalWordsW = (totalWords / 10000).toFixed(1) + '万';
+        const headerTitle = `${displayYear} 年度报告`;
+        const subTitle = '知识库年度回顾';
+        const activeDaysText = `${activeDays} 天`;
+        const totalDocsText = String(totalDocs);
+        const bg = `
+            <defs>
+                <linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
+                    <stop offset="0%" stop-color="#7c3aed"/>
+                    <stop offset="100%" stop-color="#2563eb"/>
+                </linearGradient>
+                <linearGradient id="card" x1="0" y1="0" x2="0" y2="1">
+                    <stop offset="0%" stop-color="#ffffff"/>
+                    <stop offset="100%" stop-color="#f8fafc"/>
+                </linearGradient>
+            </defs>
+        `;
+        const kbBars = topKb.map((kb, i) => {
+            const barMax = 740;
+            const percent = totalWords > 0 ? Math.max(2, Math.round((kb.words / totalWords) * barMax)) : 2;
+            const y = 820 + i * 90;
+            const name = kb.name.replace(/&/g, '&amp;').replace(/</g, '&lt;');
+            const words = (kb.words / 10000).toFixed(1) + '万';
+            return `
+                <g>
+                    <text x="120" y="${y - 26}" font-size="36" fill="#334155" font-weight="700">${name}</text>
+                    <rect x="120" y="${y}" width="${barMax}" height="32" rx="16" fill="#e5e7eb"/>
+                    <rect x="120" y="${y}" width="${percent}" height="32" rx="16" fill="#22c55e"/>
+                    <text x="${w - 160}" y="${y + 26}" font-size="30" fill="#64748b" text-anchor="end">${words}</text>
+                </g>
+            `;
+        }).join('');
+        const lastBarY = 820 + Math.max(0, topKb.length - 1) * 90 + 32;
+        const h = lastBarY + 160;
+        const footerText = 'RAG Knowledge Base';
+        const svg = `
+            <svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}">
+                ${bg}
+                <rect x="0" y="0" width="${w}" height="${h}" fill="url(#g)"/>
+                <rect x="40" y="40" width="${w - 80}" height="${h - 80}" rx="40" fill="url(#card)"/>
+                <text x="${w / 2}" y="200" font-size="64" font-weight="700" fill="#111827" text-anchor="middle">${headerTitle}</text>
+                <text x="${w / 2}" y="260" font-size="32" fill="#6b7280" text-anchor="middle">${subTitle}</text>
+
+                <g>
+                    <rect x="120" y="320" width="${w - 240}" height="140" rx="24" fill="#eef2ff" />
+                    <text x="180" y="370" font-size="28" fill="#6366f1" font-weight="600">年度活跃天数</text>
+                    <text x="${w - 180}" y="390" font-size="56" fill="#4f46e5" font-weight="800" text-anchor="end">${activeDaysText}</text>
+                    ${isFullAttendance ? `<text x="${w - 180}" y="430" font-size="22" fill="#f59e0b" font-weight="700" text-anchor="end">全勤达成</text>` : ''}
+                </g>
+
+                <g>
+                    <rect x="120" y="500" width="${(w - 300) / 2}" height="160" rx="24" fill="#ecfeff" />
+                    <text x="180" y="570" font-size="56" fill="#0ea5e9" font-weight="800">${totalDocsText}</text>
+                    <text x="180" y="620" font-size="28" fill="#14b8a6" font-weight="600">总文档数</text>
+                </g>
+
+                <g>
+                    <rect x="${120 + (w - 300) / 2 + 60}" y="500" width="${(w - 300) / 2}" height="160" rx="24" fill="#f0fdf4" />
+                    <text x="${120 + (w - 300) / 2 + 120}" y="570" font-size="56" fill="#16a34a" font-weight="800">${totalWordsW}</text>
+                    <text x="${120 + (w - 300) / 2 + 120}" y="620" font-size="28" fill="#22c55e" font-weight="600">总字数</text>
+                </g>
+
+                <text x="120" y="730" font-size="40" fill="#111827" font-weight="700">知识库贡献</text>
+                ${kbBars}
+                <text x="${w - 120}" y="${h - 60}" font-size="24" fill="#9ca3af" text-anchor="end">${footerText}</text>
+            </svg>
+        `;
+        return { svg, w, h };
+    };
+
+    const svgToPngDataUrl = async (svg: string, w: number, h: number) => {
+        return new Promise<string>((resolve, reject) => {
+            try {
+                const blob = new Blob([svg], { type: 'image/svg+xml;charset=utf-8' });
+                const url = URL.createObjectURL(blob);
+                const img = new Image();
+                img.onload = () => {
+                    const canvas = document.createElement('canvas');
+                    const scale = 2;
+                    canvas.width = w * scale;
+                    canvas.height = h * scale;
+                    const ctx = canvas.getContext('2d');
+                    if (!ctx) {
+                        URL.revokeObjectURL(url);
+                        reject(new Error('Canvas not supported'));
+                        return;
+                    }
+                    ctx.scale(scale, scale);
+                    ctx.fillStyle = '#ffffff';
+                    ctx.fillRect(0, 0, w, h);
+                    ctx.drawImage(img, 0, 0, w, h);
+                    URL.revokeObjectURL(url);
+                    resolve(canvas.toDataURL('image/png'));
+                };
+                img.onerror = () => {
+                    URL.revokeObjectURL(url);
+                    reject(new Error('Failed to load SVG'));
+                };
+                img.src = url;
+            } catch (e) {
+                reject(e as Error);
+            }
+        });
+    };
+
+    const handleGenerateShare = async () => {
+        if (generating) return;
+        setGenerating(true);
+        setCopyStatus('idle');
+        try {
+            const { svg, w, h } = generateSvg();
+            const url = await svgToPngDataUrl(svg, w, h);
+            setShareImageUrl(url);
+            setSharePreviewOpen(true);
+        } finally {
+            setGenerating(false);
+        }
+    };
+
+    const handleDownload = () => {
+        if (!shareImageUrl) return;
+        const a = document.createElement('a');
+        a.href = shareImageUrl;
+        const filename = `年度报告_${displayYear.replace('年', '')}.png`;
+        a.download = filename;
+        document.body.appendChild(a);
+        a.click();
+        document.body.removeChild(a);
+    };
+
+    const handleCopy = async () => {
+        if (!shareImageUrl) return;
+        setCopyStatus('idle');
+        try {
+            const res = await fetch(shareImageUrl);
+            const blob = await res.blob();
+            const item = new ClipboardItem({ [blob.type]: blob });
+            await navigator.clipboard.write([item]);
+            setCopyStatus('success');
+        } catch {
+            setCopyStatus('error');
+        }
+    };
+
+    return (
+        <div className="fixed inset-0 z-50 flex items-center justify-center p-4 bg-black/50 backdrop-blur-sm">
+            <div className="bg-white dark:bg-gray-800 rounded-2xl shadow-2xl max-w-md w-full overflow-hidden relative animate-in fade-in zoom-in duration-300">
+                {/* Header with gradient */}
+                <div className="bg-gradient-to-r from-primary-600 to-purple-600 p-6 text-white text-center relative overflow-hidden">
+                    <div className="absolute top-0 left-0 w-full h-full opacity-10 bg-[url('https://www.transparenttextures.com/patterns/cubes.png')]"></div>
+                    <Sparkles className="w-8 h-8 mx-auto mb-2 text-yellow-300 animate-pulse" />
+                    <h2 className="text-2xl font-bold tracking-tight">{displayYear} 年度报告</h2>
+                    <p className="text-primary-100 text-sm mt-1">您的知识库回顾</p>
+                    
+                    <button onClick={onClose} className="absolute top-4 right-4 text-white/70 hover:text-white transition-colors">
+                        <X className="w-5 h-5" />
+                    </button>
+                    <div className="absolute top-4 right-14">
+                        <button 
+                            onClick={handleGenerateShare} 
+                            className="flex items-center gap-1.5 px-2.5 py-1.5 bg-white/20 hover:bg-white/30 text-white rounded-md text-xs font-medium transition"
+                        >
+                            <Share2 className="w-4 h-4" />
+                            {generating ? '生成中' : '分享图片'}
+                        </button>
+                    </div>
+                </div>
+
+                <div className="p-6 space-y-6">
+                    {/* Active Days Highlight */}
+                    <div className="text-center space-y-2">
+                        <div className="text-sm text-gray-500 dark:text-gray-400 uppercase tracking-wider">年度活跃天数</div>
+                        <div className="text-4xl font-black text-gray-900 dark:text-white flex items-center justify-center gap-2">
+                            {activeDays}
+                            <span className="text-lg font-medium text-gray-500">天</span>
+                        </div>
+                        {isFullAttendance && (
+                            <div className="inline-block px-3 py-1 rounded-full bg-yellow-100 text-yellow-700 text-xs font-bold animate-bounce">
+                                🏆 全勤达成！太强了！
+                            </div>
+                        )}
+                        {!isFullAttendance && year !== 'all' && (
+                             <div className="text-xs text-gray-400">
+                                距离全勤还差 {daysInYear - activeDays} 天
+                             </div>
+                        )}
+                    </div>
+
+                    {/* Insights Grid */}
+                    <div className="grid grid-cols-2 gap-4">
+
+                        {/* Top Month */}
+                        <div className="bg-blue-50 dark:bg-blue-900/20 p-4 rounded-xl text-center">
+                            <div className="text-2xl font-bold text-blue-600 dark:text-blue-400 mb-0.5">{totalDocs}</div>
+                            <div className="text-xs text-gray-500 dark:text-gray-400">总文档数</div>
+                        </div>
+
+                        
+
+                         {/* Total Words */}
+                        <div className="bg-green-50 dark:bg-green-900/20 p-4 rounded-xl text-center">
+                            <div className="text-2xl font-bold text-green-600 dark:text-green-400 mb-0.5">{(totalWords / 10000).toFixed(1)}w</div>
+                            <div className="text-xs text-gray-500 dark:text-gray-400">总字数</div>
+                        </div>
+                    </div>
+
+                    {/* Detailed Stats */}
+                     <div className="space-y-3">
+
+                        <div className="bg-gray-50 dark:bg-gray-800/50 rounded-lg border border-gray-100 dark:border-gray-700 overflow-hidden">
+                            <div className="px-4 py-2 bg-gray-100/50 dark:bg-gray-800 border-b border-gray-100 dark:border-gray-700 flex justify-between text-xs font-medium text-gray-500">
+                                <span>知识库</span>
+                                <div className="flex gap-4">
+                                    <span className="w-12 text-right">文档</span>
+                                    <span className="w-16 text-right">字数</span>
+                                </div>
+                            </div>
+                            <div className="divide-y divide-gray-100 dark:divide-gray-700 max-h-48 overflow-y-auto">
+                                {data.kbStats.map((kb) => (
+                                    <div key={kb.namespace} className="px-4 py-2 flex items-center justify-between text-sm hover:bg-white dark:hover:bg-gray-700/50 transition-colors">
+                                        <span className="font-medium text-gray-700 dark:text-gray-300 truncate pr-2 flex-1" title={kb.name}>{kb.name}</span>
+                                        <div className="flex gap-4 text-gray-600 dark:text-gray-400 text-xs tabular-nums">
+                                            <span className="w-12 text-right">{kb.count}</span>
+                                            <span className="w-16 text-right">{(kb.words / 10000).toFixed(1)}w</span>
+                                        </div>
+                                    </div>
+                                ))}
+                            </div>
+                        </div>
+                    </div>
+
+                    
+                </div>
+            </div>
+            {sharePreviewOpen && shareImageUrl && (
+                <div className="fixed inset-0 z-50 flex items-center justify-center p-2 sm:p-4 bg-black/60">
+                    <div className="bg-white dark:bg-gray-900 rounded-2xl shadow-2xl max-w-[92vw] w-auto overflow-hidden relative">
+                        <div className="px-4 sm:px-6 py-4 border-b border-gray-100 dark:border-gray-800 flex items-center justify-between">
+                            <div className="flex items-center gap-2 text-gray-800 dark:text-gray-100 font-semibold">
+                                <Share2 className="w-5 h-5" />
+                                分享图片预览
+                            </div>
+                            <button onClick={() => setSharePreviewOpen(false)} className="text-gray-500 hover:text-gray-800 dark:hover:text-gray-200">
+                                <X className="w-5 h-5" />
+                            </button>
+                        </div>
+                        <div className="p-3 sm:p-4 overflow-auto max-h-[82vh] flex justify-center">
+                            <img src={shareImageUrl} alt="年度报告分享图片" className="rounded-xl shadow-md w-[320px] sm:w-[420px] h-auto object-contain" />
+                        </div>
+                        <div className="px-4 sm:px-6 py-3 sm:py-4 border-t border-gray-100 dark:border-gray-800 flex items-center justify-end gap-3">
+                            <button 
+                                onClick={handleCopy} 
+                                className="flex items-center gap-2 px-4 py-2 rounded-md bg-gray-100 hover:bg-gray-200 dark:bg-gray-800 dark:hover:bg-gray-700 text-gray-800 dark:text-gray-100 text-sm"
+                            >
+                                <Copy className="w-4 h-4" />
+                                复制到剪贴板
+                            </button>
+                            <button 
+                                onClick={handleDownload} 
+                                className="flex items-center gap-2 px-4 py-2 rounded-md bg-primary-600 hover:bg-primary-700 text-white text-sm"
+                            >
+                                <Download className="w-4 h-4" />
+                                下载 PNG
+                            </button>
+                            {copyStatus === 'success' && <span className="text-green-600 text-sm">已复制</span>}
+                            {copyStatus === 'error' && <span className="text-red-600 text-sm">复制失败，请下载保存</span>}
+                        </div>
+                    </div>
+                </div>
+            )}
+        </div>
+    );
+};
+
+// Custom Icon to avoid import error if lucide-react version mismatch
+const DatabaseIcon = ({ className }: { className?: string }) => (
+    <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className={className}><ellipse cx="12" cy="5" rx="9" ry="3"/><path d="M21 12c0 1.66-4 3-9 3s-9-1.34-9-3"/><path d="M3 5v14c0 1.66 4 3 9 3s 9-1.34 9-3V5"/></svg>
+);
+
+const Heatmap = ({ data, year, range }: { data: HeatmapData[]; year?: number; range?: { start: Date; end: Date } }) => {
+    const containerRef = useRef<HTMLDivElement>(null);
+    const [hoverInfo, setHoverInfo] = useState<{ date: string; count: number; x: number; y: number; cw: number } | null>(null);
+    const tipRef = useRef<HTMLDivElement>(null);
+    const [tipW, setTipW] = useState(120);
+    useEffect(() => {
+        if (tipRef.current) {
+            const w = tipRef.current.offsetWidth;
+            if (w && Math.abs(w - tipW) > 2) setTipW(w);
+        }
+    }, [hoverInfo, tipW]);
+    // Determine start and end dates
+    let startDate: Date;
+    let endDate: Date;
+
+    if (range) {
+        startDate = new Date(range.start);
+        endDate = new Date(range.end);
+    } else {
+        const targetYear = year || new Date().getFullYear();
+        startDate = new Date(targetYear, 0, 1);
+        endDate = new Date(targetYear, 11, 31);
+    }
+    
+    // Create map for fast lookup
+    const dataMap = new Map(data.map(d => [d.date, d.count]));
+    
+    // Helper to get color
+    const getColor = (count: number) => {
+        if (count === 0) return 'bg-gray-100 dark:bg-gray-800';
+        if (count <= 2) return 'bg-green-100 dark:bg-green-900/40';
+        if (count <= 5) return 'bg-green-300 dark:bg-green-800/60';
+        if (count <= 10) return 'bg-green-500 dark:bg-green-700';
+        return 'bg-green-700 dark:bg-green-600';
+    };
+
+    // Build weeks array
+    const weeks = [];
+    const currentDate = new Date(startDate);
+    
+    while (currentDate.getDay() !== 1) {
+        currentDate.setDate(currentDate.getDate() - 1);
+    }
+
+    // Helper to check if date is within target range
+    const isDateWithinRange = (d: Date) => {
+        // Reset time part for comparison
+        const checkDate = new Date(d);
+        checkDate.setHours(0, 0, 0, 0);
+        const s = new Date(startDate);
+        s.setHours(0, 0, 0, 0);
+        const e = new Date(endDate);
+        e.setHours(0, 0, 0, 0);
+        return checkDate >= s && checkDate <= e;
+    };
+
+    // Loop until we cover the end date
+    // We also add a safety break to avoid infinite loops
+    let safetyCounter = 0;
+    while (true) {
+        const week = [];
+        for (let i = 0; i < 7; i++) {
+            const dateStr = currentDate.toISOString().split('T')[0];
+            const isWithin = isDateWithinRange(currentDate);
+            
+            week.push({
+                date: dateStr,
+                count: isWithin ? (dataMap.get(dateStr) || 0) : -1, 
+                isWithinRange: isWithin
+            });
+            currentDate.setDate(currentDate.getDate() + 1);
+        }
+        weeks.push(week);
+        
+        // Break if the start of the next week is beyond endDate
+        if (currentDate > endDate) break;
+        
+        // Safety break (approx 2 years)
+        if (safetyCounter++ > 110) break;
+    }
+
+    // Limit to 53 weeks max to fit layout if not custom range
+    const displayWeeks = weeks.slice(0, 54);
+
+    // Generate month labels aligned with weeks
+    const monthLabels = displayWeeks.map((week) => {
+        const firstDayOfMonth = week.find(d => d.date.endsWith('-01'));
+        if (firstDayOfMonth && firstDayOfMonth.isWithinRange) {
+            const month = parseInt(firstDayOfMonth.date.slice(5, 7));
+            return `${month}月`;
+        }
+        return null;
+    });
+
+    return (
+        <div className="w-full overflow-x-auto">
+            <div ref={containerRef} className="min-w-[900px] w-full flex flex-col relative">
+                <div className="flex justify-between w-full">
+                    {displayWeeks.map((week, wIdx) => (
+                        <div key={wIdx} className="flex flex-col gap-[3px]">
+                            {week.map((day, dIdx) => (
+                                <div 
+                                    key={dIdx}
+                                    className={`w-3.5 h-3.5 rounded-sm transition-colors ${day.isWithinRange ? getColor(day.count) : 'bg-gray-50 dark:bg-gray-800/30 border border-gray-200 dark:border-gray-700'}`}
+                                    onMouseEnter={(e) => {
+                                        const rect = (e.currentTarget as HTMLDivElement).getBoundingClientRect();
+                                        const contRect = containerRef.current?.getBoundingClientRect();
+                                        if (!contRect) return;
+                                        const x = rect.left - contRect.left + rect.width / 2;
+                                        const y = rect.top - contRect.top - 8;
+                                        setHoverInfo({
+                                            date: day.date,
+                                            count: Math.max(0, day.count),
+                                            x,
+                                            y,
+                                            cw: contRect.width
+                                        });
+                                    }}
+                                    onMouseLeave={() => setHoverInfo(null)}
+                                />
+                            ))}
+                        </div>
+                    ))}
+                </div>
+                <div className="flex justify-between mt-2 w-full">
+                    {monthLabels.map((label, idx) => (
+                        <div key={idx} className="w-3.5 relative h-4">
+                            {label && (
+                                <span className="absolute left-0 top-0 text-xs text-gray-400 whitespace-nowrap">
+                                    {label}
+                                </span>
+                            )}
+                        </div>
+                    ))}
+                </div>
+                {hoverInfo && (
+                    <div
+                        ref={tipRef}
+                        className="absolute z-50 px-2 py-1 rounded-md bg-black/80 text-white text-[11px] shadow pointer-events-none"
+                        style={{
+                            left: Math.min(Math.max(8, hoverInfo.x - tipW / 2), hoverInfo.cw - tipW - 8),
+                            top: Math.max(0, hoverInfo.y - 28)
+                        }}
+                    >
+                        <div className="tabular-nums">{hoverInfo.date}</div>
+                        <div className="opacity-80">创建/更新 {hoverInfo.count}</div>
+                    </div>
+                )}
+            </div>
+        </div>
+    );
+};
+
+export default function StatsPage() {
+    const router = useRouter();
+    const [statsData, setStatsData] = useState<StatsData | null>(null);
+    const [loading, setLoading] = useState(true);
+    const [selectedYear, setSelectedYear] = useState<number | 'all'>('all');
+    const [displayYear, setDisplayYear] = useState<number | 'all'>('all');
+    const [debouncedYear, setDebouncedYear] = useState<number | 'all'>('all');
+    const [isRefreshing, setIsRefreshing] = useState(false);
+    const [errorMessage, setErrorMessage] = useState<string | null>(null);
+    const [forceRefresh, setForceRefresh] = useState(false);
+    const [showReport, setShowReport] = useState(false);
+    const [showAllYears, setShowAllYears] = useState(false);
+
+    const cacheRef = useRef(new Map<string, { data: StatsData; ts: number }>());
+    const inflightRef = useRef<Map<string, AbortController>>(new Map());
+    const scrollYRef = useRef<number | null>(null);
+
+    useEffect(() => {
+        const handle = setTimeout(() => setDebouncedYear(selectedYear), 160);
+        return () => clearTimeout(handle);
+    }, [selectedYear]);
+
+    const fetchStatsFromApi = useCallback(async (year: number | 'all', signal: AbortSignal) => {
+        const res = await fetch(`/api/stats?year=${year}&t=${Date.now()}`, {
+            cache: 'no-store',
+            headers: {
+                'Pragma': 'no-cache',
+                'Cache-Control': 'no-cache, no-store, must-revalidate'
+            },
+            signal
+        });
+        if (!res.ok) {
+            throw new Error(`HTTP ${res.status}`);
+        }
+        return (await res.json()) as StatsData;
+    }, []);
+
+    const fetchWithRetry = useCallback(async (year: number | 'all', signal: AbortSignal) => {
+        const maxRetries = 2;
+        const baseDelayMs = 300;
+
+        let lastError: unknown = null;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            if (signal.aborted) throw new DOMException('Aborted', 'AbortError');
+            try {
+                return await fetchStatsFromApi(year, signal);
+            } catch (err) {
+                lastError = err;
+                if (signal.aborted) throw err;
+                if (attempt === maxRetries) break;
+                const delayMs = baseDelayMs * Math.pow(2, attempt);
+                await new Promise<void>((resolve) => {
+                    const t = setTimeout(resolve, delayMs);
+                    signal.addEventListener('abort', () => {
+                        clearTimeout(t);
+                        resolve();
+                    }, { once: true });
+                });
+            }
+        }
+        throw lastError;
+    }, [fetchStatsFromApi]);
+
+    const applyDataForYear = useCallback((year: number | 'all', data: StatsData) => {
+        setStatsData(data);
+        setDisplayYear(year);
+    }, []);
+
+    const loadYear = useCallback(async (year: number | 'all', options?: { forceRefresh?: boolean }) => {
+        const forceRefresh = options?.forceRefresh ?? false;
+        const key = String(year);
+        const now = Date.now();
+        const ttlMs = 5 * 60 * 1000;
+
+        const cached = cacheRef.current.get(key);
+        const isFresh = cached ? (now - cached.ts) < ttlMs : false;
+
+        if (cached && !forceRefresh) {
+            applyDataForYear(year, cached.data);
+            setLoading(false);
+            setErrorMessage(null);
+            if (isFresh) return;
+        }
+
+        inflightRef.current.forEach((controller) => controller.abort());
+        inflightRef.current.clear();
+
+        const controller = new AbortController();
+        inflightRef.current.set(key, controller);
+
+        if (typeof window !== 'undefined') {
+            scrollYRef.current = window.scrollY;
+        }
+
+        setIsRefreshing(true);
+        setErrorMessage(null);
+        if (!statsData && !cached) setLoading(true);
+
+        try {
+            const data = await fetchWithRetry(year, controller.signal);
+            if (controller.signal.aborted) return;
+            cacheRef.current.set(key, { data, ts: Date.now() });
+            applyDataForYear(year, data);
+        } catch (err) {
+            if ((err as { name?: string } | null)?.name === 'AbortError') return;
+            setErrorMessage('加载失败');
+        } finally {
+            inflightRef.current.delete(key);
+            setIsRefreshing(false);
+            setLoading(false);
+            if (typeof window !== 'undefined' && scrollYRef.current !== null) {
+                const y = scrollYRef.current;
+                scrollYRef.current = null;
+                requestAnimationFrame(() => window.scrollTo({ top: y }));
+            }
+        }
+    }, [applyDataForYear, fetchWithRetry, statsData]);
+
+    const prefetchYear = useCallback(async (year: number) => {
+        const key = String(year);
+        const now = Date.now();
+        const ttlMs = 5 * 60 * 1000;
+
+        const cached = cacheRef.current.get(key);
+        if (cached && (now - cached.ts) < ttlMs) return;
+        if (inflightRef.current.has(key)) return;
+
+        const controller = new AbortController();
+        inflightRef.current.set(key, controller);
+        try {
+            const data = await fetchWithRetry(year, controller.signal);
+            if (controller.signal.aborted) return;
+            cacheRef.current.set(key, { data, ts: Date.now() });
+        } catch (err) {
+            if ((err as { name?: string } | null)?.name === 'AbortError') return;
+        } finally {
+            inflightRef.current.delete(key);
+        }
+    }, [fetchWithRetry]);
+
+    useEffect(() => {
+        const inflightMap = inflightRef.current;
+        let disposed = false;
+
+        void (async () => {
+            await loadYear(debouncedYear, { forceRefresh });
+            if (!disposed && forceRefresh) setForceRefresh(false);
+        })();
+
+        return () => {
+            disposed = true;
+            inflightMap.forEach((controller) => controller.abort());
+            inflightMap.clear();
+        };
+    }, [debouncedYear, forceRefresh, loadYear]);
+
+    useEffect(() => {
+        if (!statsData?.years?.length) return;
+        if (displayYear === 'all') {
+            const nowYear = new Date().getFullYear();
+            const candidates = statsData.years.filter((y) => y !== nowYear).slice(0, 1);
+            void prefetchYear(nowYear);
+            if (candidates[0]) void prefetchYear(candidates[0]);
+            return;
+        }
+        if (typeof displayYear !== 'number') return;
+        const years = statsData.years;
+        const idx = years.indexOf(displayYear);
+        if (idx > 0) void prefetchYear(years[idx - 1]);
+        if (idx >= 0 && idx < years.length - 1) void prefetchYear(years[idx + 1]);
+    }, [displayYear, prefetchYear, statsData?.years, statsData?.years?.length]);
+
+    const heatmapProps = displayYear === 'all' 
+        ? { 
+            range: { 
+                start: new Date(new Date().setFullYear(new Date().getFullYear() - 1)), 
+                end: new Date() 
+            } 
+        }
+        : { year: typeof displayYear === 'number' ? displayYear : new Date().getFullYear() };
+
+    const heatmapTitle = displayYear === 'all'
+        ? "活跃度 (近一年)"
+        : `活跃度 (${displayYear}年)`;
+
+    const formatWords = (words: number | undefined) => {
+        if (typeof words !== 'number') return '-';
+        return (words / 10000).toFixed(1);
+    };
+
+    if (loading && !statsData) {
+        return (
+            <div className="min-h-screen bg-white dark:bg-gray-900 flex items-center justify-center">
+                <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-primary-600"></div>
+            </div>
+        );
+    }
+
+    if (errorMessage && !statsData) {
+        return (
+            <div className="min-h-screen bg-white dark:bg-gray-900 flex flex-col items-center justify-center gap-4">
+                <div className="text-red-500 font-medium">{errorMessage}</div>
+                <button 
+                    onClick={() => setForceRefresh(true)}
+                    className="px-4 py-2 bg-primary-600 text-white rounded-lg hover:bg-primary-700 transition-colors"
+                >
+                    重试
+                </button>
+            </div>
+        );
+    }
+
+    if (!statsData) return null;
+
+    return (
+        <div className="min-h-screen bg-gray-50 dark:bg-gray-900 text-gray-900 dark:text-gray-100">
+            {/* Header */}
+            <div className="bg-white dark:bg-gray-900 border-b border-gray-200 dark:border-gray-800 sticky top-0 z-10">
+                <div className="max-w-6xl mx-auto px-4 sm:px-6 lg:px-8">
+                    <div className="flex items-center justify-between h-16">
+                        <div className="flex items-center gap-4">
+                            <button onClick={() => router.back()} className="p-2 hover:bg-gray-100 dark:hover:bg-gray-800 rounded-lg transition text-gray-500">
+                                <ArrowLeft className="w-5 h-5" />
+                            </button>
+                            <h1 className="text-xl font-bold flex items-center gap-2">
+                                <BarChart2 className="w-6 h-6 text-primary-600" />
+                                知识库统计
+                            </h1>
+                        </div>
+                        
+                        <div className="flex items-center gap-3">
+                            <div className="flex items-center gap-2">
+                                <select 
+                                    value={selectedYear}
+                                    onChange={(e) => setSelectedYear(e.target.value === 'all' ? 'all' : parseInt(e.target.value))}
+                                    className="bg-gray-100 dark:bg-gray-800 border-none rounded-lg py-1.5 px-3 text-sm font-medium focus:ring-2 focus:ring-primary-500 cursor-pointer"
+                                >
+                                    <option value="all">所有年份</option>
+                                    {statsData?.years.map(y => (
+                                        <option key={y} value={y}>{y}年</option>
+                                    ))}
+                                </select>
+                                {isRefreshing && (
+                                    <div className="animate-spin rounded-full h-4 w-4 border-b-2 border-primary-600" />
+                                )}
+                            </div>
+                            {errorMessage && (
+                                <button
+                                    type="button"
+                                    onClick={() => setForceRefresh(true)}
+                                    className="text-xs font-medium text-red-600 dark:text-red-400 hover:underline"
+                                >
+                                    {errorMessage}，重试
+                                </button>
+                            )}
+
+                            <button 
+                                onClick={() => setShowReport(true)}
+                                className="flex items-center gap-2 px-3 py-1.5 bg-gradient-to-r from-primary-600 to-purple-600 text-white text-sm font-medium rounded-lg hover:shadow-lg transition-all active:scale-95"
+                            >
+                                <Sparkles className="w-4 h-4" />
+                                年度报告
+                            </button>
+                        </div>
+                    </div>
+                </div>
+            </div>
+
+            <main className="max-w-6xl mx-auto px-4 sm:px-6 lg:px-8 py-8 space-y-8">
+                <div className={`transition-opacity duration-200 ${isRefreshing ? 'opacity-70' : 'opacity-100'}`}>
+                    <>
+                        {/* Summary Cards */}
+                        <div key={displayYear} className="grid grid-cols-1 md:grid-cols-2 gap-6">
+                    <div className="bg-white dark:bg-gray-800 p-6 rounded-2xl shadow-sm border border-gray-100 dark:border-gray-800 flex items-center gap-6">
+                        <div className="p-4 bg-blue-50 dark:bg-blue-900/20 rounded-xl text-blue-600 dark:text-blue-400">
+                            <FileText className="w-8 h-8" />
+                        </div>
+                        <div>
+                            <p className="text-sm text-gray-500 dark:text-gray-400 font-medium">新增文档数</p>
+                            <h3 className="text-3xl font-bold mt-1">{statsData?.stats.docsCount ?? statsData?.stats.totalDocs}</h3>
+                        </div>
+                    </div>
+                    
+                    <div className="bg-white dark:bg-gray-800 p-6 rounded-2xl shadow-sm border border-gray-100 dark:border-gray-800 flex items-center gap-6">
+                        <div className="p-4 bg-green-50 dark:bg-green-900/20 rounded-xl text-green-600 dark:text-green-400">
+                            <Type className="w-8 h-8" />
+                        </div>
+                        <div>
+                            <p className="text-sm text-gray-500 dark:text-gray-400 font-medium">{displayYear === 'all' ? '总字数' : '年度字数（创建或更新）'}</p>
+                            <h3 className="text-3xl font-bold mt-1">{formatWords(statsData?.stats.totalWords)} <span className="text-sm text-gray-400 font-normal">万字</span></h3>
+                        </div>
+                    </div>
+                    
+                    <div className="bg-white dark:bg-gray-800 p-6 rounded-2xl shadow-sm border border-gray-100 dark:border-gray-800 flex items-center gap-6">
+                        <div className="p-4 bg-purple-50 dark:bg-purple-900/20 rounded-xl text-purple-600 dark:text-purple-400">
+                            <FileText className="w-8 h-8" />
+                        </div>
+                        <div>
+                            <p className="text-sm text-gray-500 dark:text-gray-400 font-medium">新增小记数</p>
+                            <h3 className="text-3xl font-bold mt-1">{statsData?.stats.notesCount ?? 0}</h3>
+                        </div>
+                    </div>
+
+                    <div className="bg-white dark:bg-gray-800 p-6 rounded-2xl shadow-sm border border-gray-100 dark:border-gray-800 flex items-center gap-6">
+                        <div className="p-4 bg-orange-50 dark:bg-orange-900/20 rounded-xl text-orange-600 dark:text-orange-400">
+                            <DatabaseIcon className="w-8 h-8" />
+                        </div>
+                        <div>
+                            <p className="text-sm text-gray-500 dark:text-gray-400 font-medium">{displayYear === 'all' ? '总文档数' : '年度总文档数'}</p>
+                            <h3 className="text-3xl font-bold mt-1">{statsData?.stats.totalDocs ?? 0}</h3>
+                        </div>
+                    </div>
+                </div>
+
+                {/* Heatmap Card */}
+                <div className="bg-white dark:bg-gray-800 rounded-2xl shadow-sm border border-gray-100 dark:border-gray-700 p-6">
+                    <div className="mb-4 flex items-center justify-between">
+                        <h2 className="text-lg font-bold flex items-center gap-2">
+                            <Calendar className="w-5 h-5 text-primary-600" />
+                            {heatmapTitle}
+                        </h2>
+                        <div className="flex items-center gap-2">
+                            <span className="text-xs text-gray-400">少</span>
+                            <div className="flex items-center gap-[3px]">
+                                <div className="w-3.5 h-3.5 rounded-sm bg-gray-100 dark:bg-gray-800" />
+                                <div className="w-3.5 h-3.5 rounded-sm bg-green-100 dark:bg-green-900/40" />
+                                <div className="w-3.5 h-3.5 rounded-sm bg-green-300 dark:bg-green-800/60" />
+                                <div className="w-3.5 h-3.5 rounded-sm bg-green-500 dark:bg-green-700" />
+                                <div className="w-3.5 h-3.5 rounded-sm bg-green-700 dark:bg-green-600" />
+                            </div>
+                            <span className="text-xs text-gray-400">多</span>
+                        </div>
+                    </div>
+                    {statsData?.stats.heatmap && (
+                        <Heatmap data={statsData.stats.heatmap} {...heatmapProps} />
+                    )}
+                </div>
+
+                {/* KB Breakdown */}
+                <div className="bg-white dark:bg-gray-800 rounded-2xl shadow-sm border border-gray-100 dark:border-gray-800 overflow-hidden">
+                    <div className="px-6 py-4 border-b border-gray-100 dark:border-gray-800">
+                        <h3 className="text-lg font-bold">知识库明细</h3>
+                    </div>
+                    <div className="overflow-x-auto">
+                        {(() => {
+                          const totalDocs = statsData?.stats.totalDocs || 1;
+                          const totalWords = statsData?.stats.totalWords || 1;
+                          
+                          return (
+                        <table className="w-full text-left text-sm">
+                            <thead className="bg-gray-50 dark:bg-gray-900/50">
+                                <tr>
+                                    <th className="px-6 py-3 font-medium text-gray-500 dark:text-gray-400">知识库名称</th>
+                                    <th className="px-6 py-3 font-medium text-gray-500 dark:text-gray-400 text-right">文档数</th>
+                                    <th className="px-6 py-3 font-medium text-gray-500 dark:text-gray-400 text-right">字数</th>
+                                    <th className="px-6 py-3 font-medium text-gray-500 dark:text-gray-400 text-right">占比 (文档)</th>
+                                    <th className="px-6 py-3 font-medium text-gray-500 dark:text-gray-400 text-right">占比 (字数)</th>
+                                </tr>
+                            </thead>
+                            <tbody className="divide-y divide-gray-100 dark:divide-gray-800">
+                                {statsData?.stats.kbStats.map((kb) => {
+                                    const docPercent = Math.round((kb.count / totalDocs) * 100);
+                                    const wordPercent = Math.round((kb.words / totalWords) * 100);
+                                    
+                                    return (
+                                    <tr key={kb.namespace} className="hover:bg-gray-50 dark:hover:bg-gray-800/50 transition-colors">
+                                        <td className="px-6 py-4 font-medium">{kb.name}</td>
+                                        <td className="px-6 py-4 text-right text-gray-600 dark:text-gray-300">{kb.count}</td>
+                                        <td className="px-6 py-4 text-right text-gray-600 dark:text-gray-300">{(kb.words / 10000).toFixed(1)}万</td>
+                                        <td className="px-6 py-4 text-right">
+                                            <div className="flex items-center justify-end gap-2">
+                                                <span className="text-gray-500">{docPercent}%</span>
+                                                <div className="w-16 h-1.5 bg-gray-100 dark:bg-gray-700 rounded-full overflow-hidden">
+                                                    <div 
+                                                        className="h-full bg-blue-500 rounded-full"
+                                                        style={{ width: `${docPercent}%` }}
+                                                    />
+                                                </div>
+                                            </div>
+                                        </td>
+                                        <td className="px-6 py-4 text-right">
+                                            <div className="flex items-center justify-end gap-2">
+                                                <span className="text-gray-500">{wordPercent}%</span>
+                                                <div className="w-16 h-1.5 bg-gray-100 dark:bg-gray-700 rounded-full overflow-hidden">
+                                                    <div 
+                                                        className="h-full bg-green-500 rounded-full"
+                                                        style={{ width: `${wordPercent}%` }}
+                                                    />
+                                                </div>
+                                            </div>
+                                        </td>
+                                    </tr>
+                                    );
+                                })}
+                            </tbody>
+                        </table>
+                          );
+                        })()}
+                    </div>
+                </div>
+
+                {/* Annual Stats Table (History) */}
+                {displayYear === 'all' && statsData?.stats.annualStats && (
+                    <div className="bg-white dark:bg-gray-800 rounded-2xl shadow-sm border border-gray-100 dark:border-gray-700 p-6">
+                        <div className="mb-4 flex items-center justify-between">
+                            <h2 className="text-lg font-bold flex items-center gap-2">
+                                <FileText className="w-5 h-5 text-primary-600" />
+                                历年新增统计
+                            </h2>
+                            <button 
+                                onClick={() => setShowAllYears(v => !v)} 
+                                className="px-3 py-1.5 text-sm rounded-lg border border-gray-200 dark:border-gray-700 bg-white dark:bg-gray-800 text-gray-700 dark:text-gray-300"
+                            >
+                                {showAllYears ? '收起旧年份' : '展开旧年份'}
+                            </button>
+                        </div>
+                        <div className="overflow-x-auto">
+                            <table className="min-w-full divide-y divide-gray-200 dark:divide-gray-700">
+                                <thead>
+                                    <tr>
+                                        <th className="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">年份</th>
+                                        <th className="px-4 py-3 text-right text-xs font-medium text-gray-500 uppercase tracking-wider">文档数</th>
+                                        <th className="px-4 py-3 text-right text-xs font-medium text-gray-500 uppercase tracking-wider">
+                                            <div className="flex items-center justify-end gap-2">
+                                                <span className="w-12 text-right">占比</span>
+                                                <div className="w-16 h-1.5 rounded-full overflow-hidden opacity-0">
+                                                    <div className="h-full bg-primary-600 rounded-full w-full" />
+                                                </div>
+                                            </div>
+                                        </th>
+                                        <th className="px-4 py-3 text-right text-xs font-medium text-gray-500 uppercase tracking-wider">小记数</th>
+                                        <th className="px-4 py-3 text-right text-xs font-medium text-gray-500 uppercase tracking-wider">
+                                            <div className="flex items-center justify-end gap-2">
+                                                <span className="w-12 text-right">占比</span>
+                                                <div className="w-16 h-1.5 rounded-full overflow-hidden opacity-0">
+                                                    <div className="h-full bg-purple-500 rounded-full w-full" />
+                                                </div>
+                                            </div>
+                                        </th>
+                                        <th className="px-4 py-3 text-right text-xs font-medium text-gray-500 uppercase tracking-wider">总文档数</th>
+                                        <th className="px-4 py-3 text-right text-xs font-medium text-gray-500 uppercase tracking-wider">
+                                            <div className="flex items-center justify-end gap-2">
+                                                <span className="w-12 text-right">占比</span>
+                                                <div className="w-16 h-1.5 rounded-full overflow-hidden opacity-0">
+                                                    <div className="h-full bg-blue-500 rounded-full w-full" />
+                                                </div>
+                                            </div>
+                                        </th>
+                                        <th className="px-4 py-3 text-right text-xs font-medium text-gray-500 uppercase tracking-wider">总字数</th>
+                                        <th className="px-4 py-3 text-right text-xs font-medium text-gray-500 uppercase tracking-wider">
+                                            <div className="flex items-center justify-end gap-2">
+                                                <span className="w-12 text-right">占比</span>
+                                                <div className="w-16 h-1.5 rounded-full overflow-hidden opacity-0">
+                                                    <div className="h-full bg-green-500 rounded-full w-full" />
+                                                </div>
+                                            </div>
+                                        </th>
+                                    </tr>
+                                </thead>
+                                <tbody className="divide-y divide-gray-200 dark:divide-gray-700">
+                                    {(() => {
+                                        const annualStats = statsData.stats.annualStats || [];
+                                        const totalCount = annualStats.reduce((sum, s) => sum + s.count, 0);
+                                        const totalNotes = annualStats.reduce((sum, s) => sum + (s.notes_count || 0), 0);
+                                        const totalPureDocs = totalCount - totalNotes;
+                                        const totalWords = annualStats.reduce((sum, s) => sum + s.words, 0);
+                                        const displayStats = showAllYears ? annualStats : annualStats.slice(0, 10);
+
+                                        return (
+                                            <>
+                                                {/* Total Row */}
+                                                <tr className="bg-gray-50 dark:bg-gray-700/30 font-bold">
+                                                    <td className="px-4 py-3 whitespace-nowrap text-sm text-gray-900 dark:text-gray-100">总计</td>
+                                                    <td className="px-4 py-3 whitespace-nowrap text-sm text-right text-gray-900 dark:text-gray-100">
+                                                        {totalPureDocs}
+                                                    </td>
+                                                    <td className="px-4 py-3 whitespace-nowrap text-sm text-right text-gray-900 dark:text-gray-100">
+                                                        <div className="flex items-center justify-end gap-2">
+                                                            <span className="w-12 text-right">100%</span>
+                                                            <div className="w-16 h-1.5 rounded-full overflow-hidden opacity-0">
+                                                                <div className="h-full bg-primary-600 rounded-full w-full" />
+                                                            </div>
+                                                        </div>
+                                                    </td>
+                                                    <td className="px-4 py-3 whitespace-nowrap text-sm text-right text-gray-900 dark:text-gray-100">
+                                                        {totalNotes}
+                                                    </td>
+                                                    <td className="px-4 py-3 whitespace-nowrap text-sm text-right text-gray-900 dark:text-gray-100">
+                                                        <div className="flex items-center justify-end gap-2">
+                                                            <span className="w-12 text-right">100%</span>
+                                                            <div className="w-16 h-1.5 rounded-full overflow-hidden opacity-0">
+                                                                <div className="h-full bg-purple-500 rounded-full w-full" />
+                                                            </div>
+                                                        </div>
+                                                    </td>
+                                                    <td className="px-4 py-3 whitespace-nowrap text-sm text-right text-gray-900 dark:text-gray-100">
+                                                        {totalCount}
+                                                    </td>
+                                                    <td className="px-4 py-3 whitespace-nowrap text-sm text-right text-gray-900 dark:text-gray-100">
+                                                        <div className="flex items-center justify-end gap-2">
+                                                            <span className="w-12 text-right">100%</span>
+                                                            <div className="w-16 h-1.5 rounded-full overflow-hidden opacity-0">
+                                                                <div className="h-full bg-blue-500 rounded-full w-full" />
+                                                            </div>
+                                                        </div>
+                                                    </td>
+                                                    <td className="px-4 py-3 whitespace-nowrap text-sm text-right text-gray-900 dark:text-gray-100">
+                                                        {(totalWords / 10000).toFixed(1)}w
+                                                    </td>
+                                                    <td className="px-4 py-3 whitespace-nowrap text-sm text-right text-gray-900 dark:text-gray-100">
+                                                        <div className="flex items-center justify-end gap-2">
+                                                            <span className="w-12 text-right">100%</span>
+                                                            <div className="w-16 h-1.5 rounded-full overflow-hidden opacity-0">
+                                                                <div className="h-full bg-green-500 rounded-full w-full" />
+                                                            </div>
+                                                        </div>
+                                                    </td>
+                                                </tr>
+                                                {displayStats.map((stat) => {
+                                                    const pureDocsCount = stat.count - (stat.notes_count || 0);
+                                                    const countPercent = totalPureDocs > 0 ? (pureDocsCount / totalPureDocs) * 100 : 0;
+                                                    const notePercent = totalNotes > 0 ? ((stat.notes_count || 0) / totalNotes) * 100 : 0;
+                                                    const wordPercent = totalWords > 0 ? (stat.words / totalWords) * 100 : 0;
+                                                    const docTotalPercent = totalCount > 0 ? (stat.count / totalCount) * 100 : 0;
+                                                    
+                                                    return (
+                                                        <tr key={stat.year} className="hover:bg-gray-50 dark:hover:bg-gray-700/50">
+                                                            <td className="px-4 py-3 whitespace-nowrap text-sm font-medium text-gray-900 dark:text-gray-100">{stat.year}</td>
+                                                            <td className="px-4 py-3 whitespace-nowrap text-sm text-right text-gray-500 dark:text-gray-400">{pureDocsCount}</td>
+                                                            <td className="px-4 py-3 whitespace-nowrap text-sm text-right text-gray-500 dark:text-gray-400">
+                                                                <div className="flex items-center justify-end gap-2">
+                                                                    <span className="w-12 text-right">{countPercent.toFixed(1)}%</span>
+                                                                    <div className="w-16 h-1.5 bg-gray-100 dark:bg-gray-700 rounded-full overflow-hidden">
+                                                                        <div 
+                                                                            className="h-full bg-primary-500/60 rounded-full"
+                                                                            style={{ width: `${countPercent}%` }}
+                                                                        />
+                                                                    </div>
+                                                                </div>
+                                                            </td>
+                                                            <td className="px-4 py-3 whitespace-nowrap text-sm text-right text-gray-500 dark:text-gray-400">{stat.notes_count || 0}</td>
+                                                            <td className="px-4 py-3 whitespace-nowrap text-sm text-right text-gray-500 dark:text-gray-400">
+                                                                <div className="flex items-center justify-end gap-2">
+                                                                    <span className="w-12 text-right">{notePercent.toFixed(1)}%</span>
+                                                                    <div className="w-16 h-1.5 bg-gray-100 dark:bg-gray-700 rounded-full overflow-hidden">
+                                                                        <div 
+                                                                            className="h-full bg-purple-500/60 rounded-full"
+                                                                            style={{ width: `${notePercent}%` }}
+                                                                        />
+                                                                    </div>
+                                                                </div>
+                                                            </td>
+                                                            <td className="px-4 py-3 whitespace-nowrap text-sm text-right text-gray-500 dark:text-gray-400">{stat.count}</td>
+                                                            <td className="px-4 py-3 whitespace-nowrap text-sm text-right text-gray-500 dark:text-gray-400">
+                                                                <div className="flex items-center justify-end gap-2">
+                                                                    <span className="w-12 text-right">{docTotalPercent.toFixed(1)}%</span>
+                                                                    <div className="w-16 h-1.5 bg-gray-100 dark:bg-gray-700 rounded-full overflow-hidden">
+                                                                        <div 
+                                                                            className="h-full bg-blue-500/60 rounded-full"
+                                                                            style={{ width: `${docTotalPercent}%` }}
+                                                                        />
+                                                                    </div>
+                                                                </div>
+                                                            </td>
+                                                            <td className="px-4 py-3 whitespace-nowrap text-sm text-right text-gray-500 dark:text-gray-400">{(stat.words / 10000).toFixed(1)}w</td>
+                                                            <td className="px-4 py-3 whitespace-nowrap text-sm text-right text-gray-500 dark:text-gray-400">
+                                                                <div className="flex items-center justify-end gap-2">
+                                                                    <span className="w-12 text-right">{wordPercent.toFixed(1)}%</span>
+                                                                    <div className="w-16 h-1.5 bg-gray-100 dark:bg-gray-700 rounded-full overflow-hidden">
+                                                                        <div 
+                                                                            className="h-full bg-green-500/60 rounded-full"
+                                                                            style={{ width: `${wordPercent}%` }}
+                                                                        />
+                                                                    </div>
+                                                                </div>
+                                                            </td>
+                                                        </tr>
+                                                    );
+                                                })}
+                                            </>
+                                        );
+                                    })()}
+                                </tbody>
+                            </table>
+                        </div>
+                    </div>
+                )}
+                    </>
+                </div>
+            </main>
+
+            <AnnualReportModal 
+                isOpen={showReport} 
+                onClose={() => setShowReport(false)} 
+                year={displayYear}
+                data={statsData?.stats || { totalDocs: 0, totalWords: 0, kbStats: [], heatmap: [] }}
+            />
+        </div>
+    );
+}

src/app/login/page.tsx

@@ -0,0 +1,214 @@
+'use client'
+
+import { useState, useRef, useEffect } from 'react'
+import { useRouter } from 'next/navigation'
+import { ChevronDown, Lock, User, X } from 'lucide-react'
+
+export default function LoginPage() {
+  const router = useRouter()
+  const [username, setUsername] = useState('duqing')
+  const [password, setPassword] = useState('')
+  const [isDropdownOpen, setIsDropdownOpen] = useState(false)
+  const [isInputFocused, setIsInputFocused] = useState(false)
+  const [error, setError] = useState('')
+  const dropdownRef = useRef<HTMLDivElement>(null)
+  const inputRef = useRef<HTMLInputElement>(null)
+
+  const users = ['duqing', 'admin', 'guest']
+
+  useEffect(() => {
+    function handleClickOutside(event: MouseEvent) {
+      if (dropdownRef.current && !dropdownRef.current.contains(event.target as Node)) {
+        setIsDropdownOpen(false)
+      }
+    }
+    document.addEventListener("mousedown", handleClickOutside)
+    return () => {
+      document.removeEventListener("mousedown", handleClickOutside)
+    }
+  }, [])
+
+  const handleLogin = async (e: React.FormEvent) => {
+    e.preventDefault()
+    setError('')
+
+    // Validation
+    // Check for length 8
+    if (password.length !== 8) {
+      setError('密码长度必须为8位')
+      return
+    }
+
+    // Check characters (Chinese, English, Numbers)
+    if (!/^[\u4e00-\u9fa5a-zA-Z0-9]+$/.test(password)) {
+      setError('密码只能包含中英文或数字')
+      return
+    }
+
+    // Check for "correct" credentials
+    // Correct password for "duqing" is "1234qwer"
+    if (username === 'duqing' && password === '1234qwer') {
+      // Set cookie
+      document.cookie = `auth_token=valid_token; path=/; max-age=${60 * 60 * 24}` // 1 day
+      // Clear last session ID to ensure we start with a new chat
+      localStorage.removeItem('rag_kb_current_session_id');
+      router.push('/')
+    } else {
+      setError('账号或密码错误')
+    }
+  }
+
+  const handleSelectUser = (user: string) => {
+    setUsername(user)
+    setIsDropdownOpen(false)
+  }
+
+  return (
+    <div className="min-h-screen flex items-center justify-center bg-gray-50 dark:bg-gray-900 transition-colors duration-200">
+      <div className="max-w-md w-full space-y-8 p-10 bg-white dark:bg-gray-800 rounded-2xl shadow-xl border border-gray-100 dark:border-gray-700">
+        <div className="text-center">
+          <h1 className="text-4xl font-extrabold text-transparent bg-clip-text bg-gradient-to-r from-primary-600 to-primary-400">
+            RAG 知识库系统
+          </h1>
+          <h2 className="mt-4 text-xl font-medium text-gray-900 dark:text-gray-100">
+            欢迎回来
+          </h2>
+          <p className="mt-2 text-sm text-gray-500 dark:text-gray-400">
+            请登录您的账户以继续
+          </p>
+        </div>
+        
+        <form className="mt-8 space-y-6" onSubmit={handleLogin}>
+          <div className="space-y-5">
+            
+            {/* Username Field with Custom Select */}
+            <div className="relative" ref={dropdownRef}>
+              <label htmlFor="username" className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-1.5">
+                账号
+              </label>
+              <div className="relative flex items-center group">
+                <div className="absolute inset-y-0 left-0 pl-3 flex items-center pointer-events-none z-10">
+                  <User className="h-5 w-5 text-gray-400 group-focus-within:text-primary-500 transition-colors" />
+                </div>
+                <input
+                  ref={inputRef}
+                  id="username"
+                  name="username"
+                  type="text"
+                  required
+                  className="appearance-none rounded-xl relative block w-full pl-10 pr-10 py-3 border border-gray-300 dark:border-gray-600 placeholder-gray-400 text-gray-900 dark:text-white focus:outline-none focus:ring-2 focus:ring-primary-500/20 focus:border-primary-500 sm:text-sm bg-white dark:bg-gray-700 transition-all duration-200"
+                  placeholder="请输入账号"
+                  value={username}
+                  onChange={(e) => {
+                    setUsername(e.target.value)
+                    setIsDropdownOpen(true)
+                  }}
+                  onFocus={() => {
+                    setIsDropdownOpen(true)
+                    setIsInputFocused(true)
+                  }}
+                  onBlur={() => setIsInputFocused(false)}
+                  autoComplete="off"
+                />
+                <div
+                  className="absolute inset-y-0 right-0 pr-3 flex items-center cursor-pointer hover:text-gray-600 dark:hover:text-gray-200 transition-colors z-10"
+                  onMouseDown={(e) => e.preventDefault()}
+                  onClick={(e) => {
+                    e.stopPropagation()
+                    if (isInputFocused && username) {
+                      setUsername('')
+                      setIsDropdownOpen(true)
+                      inputRef.current?.focus()
+                    } else {
+                      setIsDropdownOpen(!isDropdownOpen)
+                      if (!isDropdownOpen) {
+                        inputRef.current?.focus()
+                      }
+                    }
+                  }}
+                >
+                  {isInputFocused && username ? (
+                    <X className="h-5 w-5 text-gray-400" />
+                  ) : (
+                    <ChevronDown className={`h-5 w-5 text-gray-400 transition-transform duration-200 ${isDropdownOpen ? 'rotate-180' : ''}`} />
+                  )}
+                </div>
+              </div>
+
+              {/* Dropdown Menu */}
+              {isDropdownOpen && (
+                <div className="absolute z-20 mt-2 w-full bg-white dark:bg-gray-700 shadow-lg max-h-60 rounded-xl py-1 text-base ring-1 ring-black ring-opacity-5 overflow-auto focus:outline-none sm:text-sm border border-gray-100 dark:border-gray-600 animate-in fade-in zoom-in-95 duration-100">
+                  {users.filter(u => u.toLowerCase().includes(username.toLowerCase())).length > 0 ? (
+                    users.filter(u => u.toLowerCase().includes(username.toLowerCase())).map((user) => (
+                    <div
+                      key={user}
+                      className="cursor-pointer select-none relative py-3 pl-4 pr-9 hover:bg-gray-50 dark:hover:bg-gray-600/50 text-gray-900 dark:text-white transition-colors"
+                      onMouseDown={(e) => e.preventDefault()}
+                      onClick={() => handleSelectUser(user)}
+                    >
+                      <span className={`block truncate ${username === user ? 'font-semibold text-primary-600 dark:text-primary-400' : 'font-normal'}`}>
+                        {user}
+                      </span>
+                    </div>
+                  ))) : (
+                    <div className="py-3 pl-4 pr-9 text-gray-500 dark:text-gray-400">
+                      无匹配用户
+                    </div>
+                  )}
+                </div>
+              )}
+            </div>
+
+            {/* Password Field */}
+            <div>
+              <label htmlFor="password" className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-1.5">
+                密码
+              </label>
+              <div className="relative flex items-center group">
+                <div className="absolute inset-y-0 left-0 pl-3 flex items-center pointer-events-none z-10">
+                  <Lock className="h-5 w-5 text-gray-400 group-focus-within:text-primary-500 transition-colors" />
+                </div>
+                <input
+                  id="password"
+                  name="password"
+                  type="password"
+                  required
+                  className="appearance-none rounded-xl relative block w-full pl-10 px-3 py-3 border border-gray-300 dark:border-gray-600 placeholder-gray-400 text-gray-900 dark:text-white focus:outline-none focus:ring-2 focus:ring-primary-500/20 focus:border-primary-500 sm:text-sm bg-white dark:bg-gray-700 transition-all duration-200"
+                  placeholder="请输入8位密码"
+                  value={password}
+                  onChange={(e) => setPassword(e.target.value)}
+                />
+              </div>
+              <p className="mt-2 text-xs text-gray-500 dark:text-gray-400 ml-1">
+                密码长度必须为8位（支持中英文）
+              </p>
+            </div>
+          </div>
+
+          <div className="flex items-center justify-between">
+            <div className="text-sm">
+              <a href="#" className="font-medium text-primary-600 hover:text-primary-500 transition-colors">
+                忘记密码？
+              </a>
+            </div>
+          </div>
+
+          <div className="h-5 flex items-center justify-center">
+            <p className={`text-sm text-red-500 font-medium transition-opacity duration-200 ${error ? 'opacity-100' : 'opacity-0'}`}>
+              {error}
+            </p>
+          </div>
+
+          <div>
+            <button
+              type="submit"
+              className="group relative w-full flex justify-center py-3 px-4 border border-transparent text-sm font-medium rounded-xl text-white bg-primary-600 hover:bg-primary-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-primary-500 dark:focus:ring-offset-gray-800 transition-all duration-200 shadow-md hover:shadow-lg active:scale-[0.98]"
+            >
+              登录
+            </button>
+          </div>
+        </form>
+      </div>
+    </div>
+  )
+}

src/app/page.tsx

@@ -6,7 +6,7 @@ import { LanguageProvider, useLanguage } from "@/contexts/LanguageContext";
 import { ThemeProvider } from "@/contexts/ThemeContext";
 import { ThemeSwitcher } from "@/components/ThemeSwitcher";
 import { useChatHistory } from "@/hooks/useChatHistory";
-import { Globe, MessageSquare, Plus, Trash2, BookOpenCheck, PanelLeftClose, PanelLeftOpen, User, Palette, Database } from "lucide-react";
+import { Globe, MessageSquare, Plus, Trash2, BookOpenCheck, PanelLeftClose, PanelLeftOpen, User, Palette, Database, BarChart2, LogOut, ChevronUp } from "lucide-react";
 import { useCallback, useState, useEffect } from "react";
 import { Message } from "ai";
 import Link from "next/link";
@@ -35,6 +35,7 @@ function HomeContent() {
   // It will expand on desktop after mount.
   const [isSidebarOpen, setIsSidebarOpen] = useState(false);
   const [isTransitionEnabled, setIsTransitionEnabled] = useState(false);
+  const [useRAG, setUseRAG] = useState(true);
 
   // Helper to update state and localStorage
   const setSidebarState = useCallback((isOpen: boolean) => {
@@ -111,12 +112,19 @@ function HomeContent() {
     }
   }, [currentSessionId, updateSessionMessages]);
 
+  const handleLogout = () => {
+    document.cookie = "auth_token=; path=/; expires=Thu, 01 Jan 1970 00:00:01 GMT";
+    localStorage.removeItem('rag_kb_current_session_id');
+    window.location.href = "/login";
+  };
+
   // Better approach: 
   // We use a separate state to track "pending auto prompt" for a specific session ID.
   const [pendingAutoPrompts, setPendingAutoPrompts] = useState<Record<string, string>>({});
 
   const triggerQuiz = useCallback(async () => {
-      const newSessionId = await createNewSession();
+      setUseRAG(false);
+      const newSessionId = await createNewSession('quiz');
       if (newSessionId) {
           setPendingAutoPrompts(prev => ({
               ...prev,
@@ -192,6 +200,7 @@ function HomeContent() {
           <div className="flex flex-col gap-1">
             <button 
               onClick={() => {
+                setUseRAG(true);
                 createNewSession();
               }}
               className="flex items-center px-2 py-2.5 rounded-lg transition-colors hover:bg-gray-100 text-gray-700 overflow-hidden w-full group"
@@ -217,8 +226,31 @@ function HomeContent() {
                 {t('knowledgeManagement')}
               </span>
             </Link>
+            
+            <Link 
+              href="/knowledge/stats"
+              className="flex items-center px-2 py-2.5 rounded-lg transition-colors hover:bg-gray-100 text-gray-700 overflow-hidden w-full group"
+              title="数据统计"
+            >
+              <div className="w-8 h-5 flex justify-center items-center shrink-0">
+                <BarChart2 className="w-5 h-5 text-gray-500 group-hover:text-gray-900" />
+              </div>
+              <span className={`text-sm font-medium whitespace-nowrap overflow-hidden transition-all duration-200 ease-in-out ${isSidebarOpen ? 'max-w-[200px] opacity-100 ml-3' : 'max-w-0 opacity-0 ml-0'}`}>
+                数据统计
+              </span>
+            </Link>
 
-            <Upload collapsed={!isSidebarOpen} className="px-2 py-2.5" iconContainerClass="w-8 h-5 flex justify-center items-center shrink-0" />
+            <Upload 
+              collapsed={!isSidebarOpen} 
+              className="px-2 py-2.5" 
+              iconContainerClass="w-8 h-5 flex justify-center items-center shrink-0" 
+              onUploadComplete={async (fileName) => {
+                setUseRAG(false); // Disable global RAG when chatting with a file
+                // If fileName is provided, we can pass it to the session.
+                // Note: backend needs to support filtering by file.
+                await createNewSession('file', undefined, fileName ? { name: fileName } : undefined);
+              }}
+            />
             
             <button 
               onClick={() => {
@@ -280,7 +312,7 @@ function HomeContent() {
         {/* User Profile / Bottom Section */}
         <div className={`p-2 bg-gray-50 mt-auto ${isSidebarOpen ? 'border-t border-gray-200' : ''}`}>
            <div className="group relative">
-             <div className={`flex items-center px-2 py-2.5 rounded-lg transition-colors w-full relative ${!isSidebarOpen ? 'hover:bg-gray-100 cursor-pointer' : ''}`}>
+             <div className="flex items-center px-2 py-2.5 rounded-lg transition-colors w-full relative hover:bg-gray-100 cursor-pointer">
                 <div className="w-8 h-8 flex justify-center items-center shrink-0">
                   <div className="w-8 h-8 rounded-full bg-gray-200 flex items-center justify-center text-gray-600">
                     <User className="w-4 h-4" />
@@ -292,64 +324,60 @@ function HomeContent() {
                 </div>
                 
                 {isSidebarOpen && (
-                  <div className="flex items-center gap-1 ml-auto shrink-0 z-10">
-                    <ThemeSwitcher />
-                    <button
-                      onClick={(e) => {
-                        e.stopPropagation();
-                        setLanguage(language === 'en' ? 'zh' : 'en');
-                      }}
-                      className="w-8 h-8 flex items-center justify-center text-primary-600 hover:text-primary-700 hover:bg-gray-200 rounded-lg transition-colors cursor-pointer group/lang"
-                      title={language === 'en' ? 'Switch to Chinese' : '切换到英文'}
-                    >
-                      <span className="text-xs font-medium">
-                          {language === 'en' ? '中' : 'En'}
-                      </span>
-                    </button>
+                  <div className="flex items-center gap-1 ml-auto shrink-0 z-10 text-gray-400">
+                    <ChevronUp className="w-4 h-4" />
                   </div>
                 )}
              </div>
 
-             {/* Hover Popover - Only when collapsed */}
-             {!isSidebarOpen && (
-               <div className="absolute left-full bottom-0 ml-3 w-64 bg-white rounded-xl shadow-xl border border-gray-100 p-4 invisible opacity-0 group-hover:visible group-hover:opacity-100 transition-all duration-200 z-50">
-                 <div className="flex items-center gap-3 mb-4">
-                    <div className="w-10 h-10 rounded-full bg-gray-100 flex items-center justify-center text-gray-600 shrink-0">
-                      <User className="w-5 h-5" />
-                    </div>
-                    <div className="flex-1 min-w-0">
-                      <p className="text-sm font-semibold text-gray-900 truncate">{t('userAccount')}</p>
-                      <p className="text-xs text-gray-500 truncate">{t('freePlan')}</p>
-                    </div>
-                 </div>
-                 
-                 <div className="h-px bg-gray-100 -mx-4 mb-2"></div>
-
-                 <ThemeSwitcher 
-                   customTrigger={
-                     <div className="flex items-center gap-3 w-full p-2 hover:bg-gray-100 rounded-lg text-sm text-primary-600 hover:text-primary-700 transition-colors cursor-pointer">
-                        <div className="w-6 h-6 flex items-center justify-center shrink-0">
-                            <Palette className="w-5 h-5" />
-                        </div>
-                        <span>主题风格</span>
-                     </div>
-                   }
-                 />
-                 
-                 <button 
-                   onClick={(e) => {
-                     e.stopPropagation();
-                     setLanguage(language === 'en' ? 'zh' : 'en');
-                   }}
-                   className="flex items-center gap-3 w-full p-2 hover:bg-gray-100 rounded-lg text-sm text-primary-600 hover:text-primary-700 transition-colors cursor-pointer"
-                >
-                   <span className="w-6 h-6 flex items-center justify-center bg-gray-100 rounded text-xs font-medium text-primary-600 shrink-0">
-                       {language === 'en' ? '中' : 'En'}
-                   </span>
-                   <span>{language === 'en' ? 'Switch to Chinese' : '切换到英文'}</span>
-                </button>
+             {/* Unified Hover Popover - For both Expanded and Collapsed states */}
+             <div className={`absolute bottom-0 mb-2 bg-white rounded-xl shadow-xl border border-gray-100 p-4 invisible opacity-0 group-hover:visible group-hover:opacity-100 transition-all duration-200 z-50 left-full ml-3 w-64`}>
+               <div className="flex items-center gap-3 mb-4">
+                  <div className="w-10 h-10 rounded-full bg-gray-100 flex items-center justify-center text-gray-600 shrink-0">
+                    <User className="w-5 h-5" />
+                  </div>
+                  <div className="flex-1 min-w-0">
+                    <p className="text-sm font-medium text-gray-900 truncate">{t('userAccount')}</p>
+                    <p className="text-xs text-gray-500 truncate">{t('freePlan')}</p>
+                  </div>
                </div>
-             )}
+
+               <div className="h-px bg-gray-100 -mx-4 mb-2"></div>
+
+               <ThemeSwitcher 
+                  isPopover 
+                  label={t('theme')}
+                  className="w-full flex items-center justify-between px-2 py-2 text-sm text-gray-700 hover:bg-gray-50 rounded-lg cursor-pointer"
+                />
+               
+               <button 
+                 onClick={(e) => {
+                   e.stopPropagation();
+                   setLanguage(language === 'en' ? 'zh' : 'en');
+                 }}
+                 className="flex items-center gap-3 w-full p-2 hover:bg-gray-100 rounded-lg text-sm text-primary-600 hover:text-primary-700 transition-colors cursor-pointer"
+              >
+                 <span className="w-6 h-6 flex items-center justify-center bg-gray-100 rounded text-xs font-medium text-primary-600 shrink-0">
+                     {language === 'en' ? '中' : 'En'}
+                 </span>
+                 <span>{language === 'en' ? 'Switch to Chinese' : '切换到英文'}</span>
+              </button>
+
+              <div className="h-px bg-gray-100 -mx-4 my-2"></div>
+
+              <button 
+                 onClick={(e) => {
+                   e.stopPropagation();
+                   handleLogout();
+                 }}
+                 className="flex items-center gap-3 w-full p-2 hover:bg-red-50 rounded-lg text-sm text-red-600 hover:text-red-700 transition-colors cursor-pointer"
+              >
+                 <span className="w-6 h-6 flex items-center justify-center shrink-0">
+                     <LogOut className="w-5 h-5" />
+                 </span>
+                 <span>退出登录</span>
+              </button>
+             </div>
            </div>
         </div>
 
@@ -384,6 +412,10 @@ function HomeContent() {
              initialMessages={currentSession?.messages || []}
              onMessagesUpdate={handleMessagesUpdate}
              autoSubmitPrompt={currentSessionId ? pendingAutoPrompts[currentSessionId] : undefined}
+             useRAG={useRAG}
+             onUseRAGChange={setUseRAG}
+             showRAGToggle={!currentSession || (currentSession.type !== 'quiz' && currentSession.type !== 'file')}
+             fileInfo={currentSession?.fileInfo}
            />
         </div>
       </div>

src/components/Chat.tsx

@@ -2,16 +2,20 @@
 
 import { useChat } from "@ai-sdk/react";
 import { Message } from "ai";
-import { Send, User, Bot, ChevronDown, ChevronUp, Database, MessageSquare } from "lucide-react";
+import { Send, User, Bot, ChevronDown, ChevronUp, Database, MessageSquare, ArrowUp, Square, FileText } from "lucide-react";
 import ReactMarkdown from "react-markdown";
 import { useEffect, useRef, useState, useMemo } from "react";
 import { useLanguage } from "@/contexts/LanguageContext";
 import { InteractiveQuiz, QuizQuestion } from "./InteractiveQuiz";
 
-interface ChatProps {
+export interface ChatProps {
   initialMessages?: Message[];
   onMessagesUpdate?: (messages: Message[]) => void;
   autoSubmitPrompt?: string;
+  useRAG: boolean;
+  onUseRAGChange: (useRAG: boolean) => void;
+  showRAGToggle?: boolean;
+  fileInfo?: { name: string };
 }
 
 // Helper to process think tags
@@ -23,15 +27,19 @@ const processThinkTags = (content: string) => {
   });
 };
 
-const QuizLoadingSkeleton = () => (
+const QuizLoadingSkeleton = ({ language }: { language: string }) => (
   <div className="bg-white rounded-xl shadow-sm border border-gray-200 my-4 w-full max-w-xl overflow-hidden animate-pulse">
     <div className="p-6 border-b border-gray-100 flex items-center justify-between bg-white">
       <div className="h-7 bg-gray-100 rounded-md w-40"></div>
       <div className="h-8 bg-gray-100 rounded-md w-20"></div>
     </div>
     <div className="p-6 space-y-8">
+      <div className="flex items-center justify-center py-8 text-gray-400 gap-2">
+         <span className="animate-spin text-xl">⏳</span>
+         <span className="font-medium">{language === 'zh' ? "正在生成试题..." : "Generating Quiz..."}</span>
+      </div>
       {[1, 2].map((i) => (
-        <div key={i} className="space-y-4">
+        <div key={i} className="space-y-4 opacity-50">
           <div className="h-5 bg-gray-100 rounded w-3/4"></div>
           <div className="space-y-3">
             {[1, 2, 3, 4].map((j) => (
@@ -63,7 +71,7 @@ const ThinkBlock = ({ children, isThinkingFinished }: { children: React.ReactNod
     );
 };
 
-const getMarkdownComponents = (isStreaming: boolean, isThinkingFinished: boolean = true) => ({
+const getMarkdownComponents = (isStreaming: boolean, isThinkingFinished: boolean = true, language: string = 'en') => ({
   pre: ({ children }: React.ComponentPropsWithoutRef<'pre'>) => <>{children}</>,
   p: ({ children, node, ...props }: React.ComponentPropsWithoutRef<'p'> & { node?: unknown }) => (
     <div {...props} className="!mb-3 last:!mb-0 !leading-relaxed text-gray-800">
@@ -139,7 +147,7 @@ const getMarkdownComponents = (isStreaming: boolean, isThinkingFinished: boolean
       } catch {
         // If it's explicitly a quiz tag but parsing failed (likely streaming), show loading skeleton
         if (isQuizTag && isStreaming) {
-            return <QuizLoadingSkeleton />;
+            return <QuizLoadingSkeleton language={language} />;
         }
         // For json tag or non-streaming quiz tag, we fall back to code block because it might be regular JSON or broken
       }
@@ -156,7 +164,7 @@ const getMarkdownComponents = (isStreaming: boolean, isThinkingFinished: boolean
     }
 
     return (
-      <pre className="!whitespace-pre-wrap !break-words !overflow-x-hidden !my-4 !rounded-xl !bg-gray-50 !border !border-gray-100">
+      <pre className="!whitespace-pre-wrap !break-words !overflow-x-hidden !my-4 !rounded-xl">
         {codeElement}
       </pre>
     );
@@ -164,7 +172,7 @@ const getMarkdownComponents = (isStreaming: boolean, isThinkingFinished: boolean
 });
 
 const UserMarkdownComponents = {
-  ...getMarkdownComponents(false),
+  ...getMarkdownComponents(false, true, 'en'), // Default to en for user messages as language context isn't critical there
   p: ({ children, node, ...props }: React.ComponentPropsWithoutRef<'p'> & { node?: unknown }) => (
     <div {...props} className="!mb-2 last:!mb-0 !leading-relaxed">
       {children}
@@ -217,7 +225,7 @@ const CollapsibleUserMessage = ({ content }: { content: string }) => {
 
 
 
-const SmoothMarkdown = ({ content, isStreaming, onContentUpdate }: { content: string, isStreaming: boolean, onContentUpdate?: () => void }) => {
+const SmoothMarkdown = ({ content, isStreaming, onContentUpdate, language }: { content: string, isStreaming: boolean, onContentUpdate?: () => void, language: string }) => {
   const [displayed, setDisplayed] = useState(isStreaming ? '' : content);
   const targetRef = useRef(content);
   const displayedRef = useRef(displayed);
@@ -286,7 +294,7 @@ const SmoothMarkdown = ({ content, isStreaming, onContentUpdate }: { content: st
   // The raw 'displayed' text contains <think>...</think> if the stream has delivered it.
   const isThinkingFinished = useMemo(() => displayed.includes('</think>'), [displayed]);
 
-  const components = useMemo(() => getMarkdownComponents(isStreaming, isThinkingFinished), [isStreaming, isThinkingFinished]);
+  const components = useMemo(() => getMarkdownComponents(isStreaming, isThinkingFinished, language), [isStreaming, isThinkingFinished, language]);
   
   // Pre-process content to handle <think> tags
   const processedContent = useMemo(() => processThinkTags(displayed), [displayed]);
@@ -300,18 +308,26 @@ const SmoothMarkdown = ({ content, isStreaming, onContentUpdate }: { content: st
   );
 };
 
-export function Chat({ initialMessages = [], onMessagesUpdate, autoSubmitPrompt }: ChatProps) {
-  const [useRAG, setUseRAG] = useState(true);
+export function Chat({ 
+  initialMessages = [], 
+  onMessagesUpdate, 
+  autoSubmitPrompt,
+  useRAG,
+  onUseRAGChange,
+  showRAGToggle = true,
+  fileInfo
+}: ChatProps) {
   const { t, language } = useLanguage();
   
-  const { messages, input, handleInputChange, handleSubmit, isLoading, error, append } = useChat({
+  const { messages, input, handleInputChange, handleSubmit, isLoading, error, append, stop } = useChat({
     initialMessages,
-    body: { useRAG },
+    body: { useRAG: fileInfo ? true : useRAG, fileInfo },
   });
   const scrollContainerRef = useRef<HTMLDivElement>(null);
   const inputRef = useRef<HTMLInputElement>(null);
   const hasAutoSubmitted = useRef(false);
   const isAtBottomRef = useRef(true);
+  const [showScrollTop, setShowScrollTop] = useState(false);
 
   useEffect(() => {
     // Auto-focus input on mount (new chat or switching history)
@@ -351,6 +367,14 @@ export function Chat({ initialMessages = [], onMessagesUpdate, autoSubmitPrompt
     // User is considered "at bottom" if they are within 50px of the bottom
     const isAtBottom = scrollHeight - scrollTop - clientHeight < 50;
     isAtBottomRef.current = isAtBottom;
+    setShowScrollTop(scrollTop > 400);
+  };
+
+  const scrollToTop = () => {
+    scrollContainerRef.current?.scrollTo({
+      top: 0,
+      behavior: 'smooth'
+    });
   };
 
   const scrollToBottom = (smooth = false) => {
@@ -445,10 +469,11 @@ export function Chat({ initialMessages = [], onMessagesUpdate, autoSubmitPrompt
                             <SmoothMarkdown 
                               content={m.content} 
                               isStreaming={true}
+                              language={language}
                               // onContentUpdate={() => isAtBottomRef.current && scrollToBottom(false)}
                             />
                          ) : (
-                            <ReactMarkdown components={getMarkdownComponents(false)}>
+                            <ReactMarkdown components={getMarkdownComponents(false, true, language)}>
                               {m.content}
                             </ReactMarkdown>
                          )}
@@ -471,38 +496,67 @@ export function Chat({ initialMessages = [], onMessagesUpdate, autoSubmitPrompt
         </div>
       </div>
 
+      {showScrollTop && (
+        <button
+          onClick={scrollToTop}
+          className="absolute bottom-32 right-6 p-3 bg-white border border-gray-200 shadow-lg rounded-full text-gray-500 hover:bg-gray-50 hover:text-gray-900 transition-all z-10 opacity-90 hover:opacity-100"
+          title={language === 'zh' ? "回到顶部" : "Scroll to Top"}
+        >
+          <ArrowUp className="w-5 h-5" />
+        </button>
+      )}
+
       <div className="p-4 bg-white/80 backdrop-blur-sm border-t border-gray-100">
         <div className="max-w-3xl mx-auto">
             <form onSubmit={handleSubmit} className="relative flex items-center gap-2">
-                <button
-                    type="button"
-                    onClick={() => setUseRAG(!useRAG)}
-                    className={`p-2.5 rounded-xl transition-all flex items-center justify-center shrink-0 border ${
-                        useRAG 
-                        ? "bg-primary-50 text-primary-600 border-primary-200 hover:bg-primary-100" 
-                        : "bg-white text-gray-400 border-gray-200 hover:bg-gray-50 hover:text-gray-600"
-                    }`}
-                    title={useRAG ? (language === 'zh' ? "已开启知识库对话" : "RAG Enabled") : (language === 'zh' ? "已切换为普通对话" : "Normal Chat")}
-                >
-                    {useRAG ? <Database className="w-5 h-5" /> : <MessageSquare className="w-5 h-5" />}
-                </button>
-                
                 <div className="relative flex-1">
+                    {fileInfo ? (
+                        <div 
+                            className="absolute left-2 top-1/2 -translate-y-1/2 p-2 text-gray-500 hover:text-primary-600 cursor-default z-10 transition-colors"
+                            title={fileInfo.name}
+                        >
+                            <FileText className="w-5 h-5" />
+                        </div>
+                    ) : showRAGToggle && (
+                        <button
+                            type="button"
+                            onClick={() => onUseRAGChange(!useRAG)}
+                            className={`absolute left-2 top-1/2 -translate-y-1/2 p-2 rounded-full transition-all z-10 ${
+                                useRAG 
+                                ? "text-primary-600 hover:bg-primary-50" 
+                                : "text-gray-400 hover:text-gray-600 hover:bg-gray-100"
+                            }`}
+                            title={useRAG ? (language === 'zh' ? "普通对话" : "Normal Chat") : (language === 'zh' ? "对话知识库" : "Chat with Knowledge Base")}
+                        >
+                            {useRAG ? <Database className="w-5 h-5" /> : <MessageSquare className="w-5 h-5" />}
+                        </button>
+                    )}
                     <input
                     ref={inputRef}
-                    className="w-full pl-5 pr-12 py-3.5 bg-gray-50 rounded-full focus:outline-none transition-all text-gray-700 placeholder-gray-400 focus:bg-white focus:ring-2 focus:ring-primary-100 focus:border-primary-200 border border-transparent"
+                    className={`w-full ${fileInfo || showRAGToggle ? 'pl-12' : 'pl-5'} pr-12 py-3.5 bg-gray-50 rounded-full focus:outline-none transition-all text-gray-700 placeholder-gray-400 focus:bg-white focus:ring-2 focus:ring-primary-100 focus:border-primary-200 border border-transparent`}
                     value={input}
-                    placeholder={useRAG ? (language === 'zh' ? "对话知识库..." : "Chat with Knowledge Base...") : t('inputPlaceholder')}
+                    placeholder={fileInfo ? (language === 'zh' ? `与 ${fileInfo.name} 对话...` : `Chat with ${fileInfo.name}...`) : (useRAG ? (language === 'zh' ? "对话知识库..." : "Chat with Knowledge Base...") : t('inputPlaceholder'))}
                     onChange={handleInputChange}
                     disabled={isLoading}
                     />
-                    <button
-                    type="submit"
-                    disabled={isLoading || !input.trim()}
-                    className="absolute right-2 top-1/2 -translate-y-1/2 p-2 bg-gray-900 text-white rounded-full hover:bg-gray-700 disabled:opacity-50 disabled:cursor-not-allowed transition-all shadow-sm hover:shadow-md"
-                    >
-                    <Send className="w-4 h-4" />
-                    </button>
+                    {isLoading ? (
+                      <button
+                        type="button"
+                        onClick={() => stop()}
+                        className="absolute right-2 top-1/2 -translate-y-1/2 p-2 bg-red-500 text-white rounded-full hover:bg-red-600 transition-all shadow-sm hover:shadow-md animate-in fade-in zoom-in duration-200"
+                        title={language === 'zh' ? "停止生成" : "Stop generating"}
+                      >
+                        <Square className="w-4 h-4 fill-current" />
+                      </button>
+                    ) : (
+                      <button
+                        type="submit"
+                        disabled={!input.trim()}
+                        className="absolute right-2 top-1/2 -translate-y-1/2 p-2 bg-gray-900 text-white rounded-full hover:bg-gray-700 disabled:opacity-50 disabled:cursor-not-allowed transition-all shadow-sm hover:shadow-md"
+                      >
+                        <Send className="w-4 h-4" />
+                      </button>
+                    )}
                 </div>
             </form>
             <p className="text-center text-xs text-gray-400 mt-3">

src/components/ThemeSwitcher.tsx

@@ -6,10 +6,13 @@ import { useState, useRef, useEffect, ReactNode } from "react";
 
 interface ThemeSwitcherProps {
   customTrigger?: ReactNode;
-  position?: 'top' | 'bottom';
+  position?: 'top' | 'bottom' | 'right';
+  isPopover?: boolean;
+  label?: string;
+  className?: string;
 }
 
-export function ThemeSwitcher({ customTrigger, position = 'top' }: ThemeSwitcherProps) {
+export function ThemeSwitcher({ customTrigger, position = 'top', isPopover, label, className }: ThemeSwitcherProps) {
   const { theme, setTheme } = useTheme();
   const [isOpen, setIsOpen] = useState(false);
   const containerRef = useRef<HTMLDivElement>(null);
@@ -41,6 +44,21 @@ export function ThemeSwitcher({ customTrigger, position = 'top' }: ThemeSwitcher
         }}>
           {customTrigger}
         </div>
+      ) : isPopover ? (
+         <div 
+           onClick={(e) => {
+             e.stopPropagation();
+             setIsOpen(!isOpen);
+           }}
+           className={className}
+         >
+            <div className="flex items-center gap-3">
+              <span className="w-6 h-6 flex items-center justify-center shrink-0">
+                 <Palette className="w-5 h-5" />
+              </span>
+              <span>{label || '主题风格'}</span>
+           </div>
+         </div>
       ) : (
         <button
           onClick={(e) => {
@@ -56,12 +74,14 @@ export function ThemeSwitcher({ customTrigger, position = 'top' }: ThemeSwitcher
 
       {isOpen && (
         <div 
-            className={`absolute left-1/2 -translate-x-1/2 p-3 bg-white rounded-xl shadow-xl border border-gray-100 flex flex-col gap-2 z-50 min-w-[160px]
-                ${position === 'top' ? 'bottom-full mb-2' : 'top-full mt-2'}
+            className={`absolute bg-white rounded-xl shadow-xl border border-gray-100 flex flex-col gap-2 z-50 min-w-[160px] p-3
+                ${position === 'top' ? 'left-1/2 -translate-x-1/2 bottom-full mb-2' : ''}
+                ${position === 'bottom' ? 'left-1/2 -translate-x-1/2 top-full mt-2' : ''}
+                ${position === 'right' ? 'left-full top-0 ml-2' : ''}
             `}
             onClick={(e) => e.stopPropagation()}
         >
-          <div className="text-xs font-medium text-gray-500 px-1">主题风格</div>
+          <div className="text-xs font-medium text-gray-500 px-1">{label || '主题风格'}</div>
           <div className="flex justify-between items-center gap-1">
             {themes.map((t) => (
                 <button

src/components/Upload.tsx

@@ -4,7 +4,7 @@ import { useState } from "react";
 import { UploadCloud, Loader2 } from "lucide-react";
 import { useLanguage } from "@/contexts/LanguageContext";
 
-export function Upload({ className, collapsed = false, iconContainerClass }: { className?: string; collapsed?: boolean; iconContainerClass?: string }) {
+export function Upload({ className, collapsed = false, iconContainerClass, onUploadComplete }: { className?: string; collapsed?: boolean; iconContainerClass?: string; onUploadComplete?: (fileName?: string) => void }) {
   const [uploading, setUploading] = useState(false);
   const [message, setMessage] = useState("");
   const { t } = useLanguage();
@@ -26,9 +26,8 @@ export function Upload({ className, collapsed = false, iconContainerClass }: { c
       });
       const data = await res.json();
       if (res.ok) {
-        setMessage(`${t('uploadSuccess')}: ${data.message} (${data.chunks} ${t('chunks')})`);
-        // Clear message after 3 seconds
-        setTimeout(() => setMessage(""), 3000);
+        // Immediately trigger complete without showing success message in UI
+        if (onUploadComplete) onUploadComplete(file.name);
       } else {
         setMessage(`${t('uploadError')}: ${data.error}`);
       }

src/contexts/LanguageContext.tsx

@@ -37,9 +37,9 @@ const translations: Record<Language, Translations> = {
     disclaimer: "AI generated content may be inaccurate. Please verify important information.",
     generateQuiz: "Generate Quiz",
     knowledgeManagement: "Knowledge Base Management",
-    userAccount: "User Account",
-    freePlan: "Free Plan",
-    quizPrompt: "Please generate 5 multiple-choice questions based on the uploaded knowledge base content.\n\nRequirements:\n1. If no relevant documents are found in the knowledge base, please label the questions as '(Demo Questions)'.\n2. Strict Formatting Rules:\n   - Use a number for the question (e.g., 1. Question...).\n   - FORCE A NEW LINE for each option (A, B, C, D).\n   - Format: \n     1. Question Text\n     A. Option 1\n     B. Option 2\n     C. Option 3\n     D. Option 4\n3. Answer Key:\n   - Display answers at the bottom.\n   - Format: 1. A  2. B  3. C...",
+    userAccount: "duqing",
+    freePlan: "Super Admin",
+    quizPrompt: "Generate Quiz",
     sync: "Sync",
     syncing: "Syncing...",
     outline: "Outline",
@@ -51,7 +51,8 @@ const translations: Record<Language, Translations> = {
     noKb: "No Knowledge Base, please sync",
     searchResults: "Search Results",
     noDocs: "No matching documents",
-    demoMode: "Demo Mode"
+    demoMode: "Demo Mode",
+    theme: "Theme"
   },
   zh: {
     title: "RAG 知识库系统",
@@ -62,7 +63,7 @@ const translations: Record<Language, Translations> = {
     tech3: "流式响应",
     tech4: "本地向量库 (HNSWLib)",
     uploadTitle: "知识库上传",
-    uploadButton: "选择文件 (MD/Txt)",
+    uploadButton: "选择文件",
     uploading: "上传中...",
     uploadSupport: "支持 .md 和 .txt 文件。数据将被分块并建立本地索引。",
     uploadSuccess: "成功",
@@ -76,14 +77,14 @@ const translations: Record<Language, Translations> = {
     chunks: "个分块",
     send: "发送",
     history: "历史记录",
-    newChat: "新对话",
+    newChat: "新建对话",
     deleteChat: "删除",
     disclaimer: "AI 生成的内容可能不准确，请核实重要信息。",
     generateQuiz: "生成试题",
     knowledgeManagement: "知识库管理",
-    userAccount: "用户账号",
-    freePlan: "免费计划",
-    quizPrompt: "请基于已上传的知识库内容生成 5 道单项选择题。\n\n**重要：请务必将生成结果封装在 JSON 代码块中，并使用 `quiz` 作为语言标签（即 ```quiz）。**\n\nJSON 数据结构要求：\n一个包含 5 个对象的数组，每个对象包含以下字段：\n- id: 数字序号\n- question: 题目文本\n- options: 包含 4 个选项内容的字符串数组（**注意：请绝对不要在选项内容前加 A. B. C. D. 等前缀，只保留选项内容本身**）\n- correctAnswer: 正确选项的索引（数字 0-3，0代表A，1代表B，以此类推）\n- explanation: 答案解析\n\n示例格式：\n```quiz\n[\n  {\n    \"id\": 1,\n    \"question\": \"题目内容...\",\n    \"options\": [\"内容1\", \"内容2\", \"内容3\", \"内容4\"],\n    \"correctAnswer\": 0,\n    \"explanation\": \"解析内容...\"\n  }\n]\n```",
+    userAccount: "duqing",
+    freePlan: "超级管理员",
+    quizPrompt: "对话试题",
     sync: "同步",
     syncing: "同步中",
     outline: "大纲",
@@ -95,7 +96,8 @@ const translations: Record<Language, Translations> = {
     noKb: "暂无知识库，请点击同步",
     searchResults: "搜索结果",
     noDocs: "未找到匹配文档",
-    demoMode: "演示模式"
+    demoMode: "演示模式",
+    theme: "主题风格"
   }
 };
 

src/hooks/useChatHistory.ts

@@ -9,6 +9,10 @@ export interface ChatSession {
   messages: Message[];
   createdAt: number;
   isTemp?: boolean;
+  type?: 'chat' | 'quiz' | 'file';
+  fileInfo?: {
+    name: string;
+  };
 }
 
 // Simple debounce implementation if lodash is not available or to avoid dependency
@@ -80,20 +84,23 @@ export function useChatHistory() {
       }
   }, [currentSessionId, sessions]);
 
-  const createNewSession = useCallback(async () => {
-    // Check if we already have an empty temp session to reuse
-    const existingTemp = sessionsRef.current.find(s => s.isTemp && s.messages.length === 0);
-    if (existingTemp) {
+  const createNewSession = useCallback(async (type: 'chat' | 'quiz' | 'file' = 'chat', title?: string, fileInfo?: { name: string }) => {
+    // Check if we already have an empty temp session to reuse (only if type matches)
+    const existingTemp = sessionsRef.current.find(s => s.isTemp && s.messages.length === 0 && (s.type === type || (!s.type && type === 'chat')));
+    // For file type, we must also match the file name, or just create new one to be safe
+    if (existingTemp && type !== 'file') {
         setCurrentSessionId(existingTemp.id);
         return existingTemp.id;
     }
 
     const newSession: ChatSession = {
       id: crypto.randomUUID(),
-      title: 'New Chat',
+      title: title || (type === 'quiz' ? 'Quiz Generation' : (type === 'file' && fileInfo ? `Chat with ${fileInfo.name}` : 'New Chat')),
       messages: [],
       createdAt: Date.now(),
       isTemp: true, // Mark as temporary, don't persist yet
+      type,
+      fileInfo
     };
     
     // Optimistic update
@@ -167,8 +174,8 @@ export function useChatHistory() {
     setSessions(prev => prev.map(session => {
       if (session.id === id) {
         let title = session.title;
-        // Update title if it's the first message
-        if ((session.isTemp || title === 'New Chat') && messages.length > 0) {
+        // Update title if it's the first message AND it's a regular chat
+        if ((session.isTemp || title === 'New Chat') && messages.length > 0 && (!session.type || session.type === 'chat')) {
             const firstUserMsg = messages.find(m => m.role === 'user');
             if (firstUserMsg) {
                 title = firstUserMsg.content.slice(0, 30) + (firstUserMsg.content.length > 30 ? '...' : '');
@@ -190,9 +197,12 @@ export function useChatHistory() {
             // We can recalculate it here to be safe or grab from state later?
             // Recalculating is safer for the async call.
             let title = session?.title || 'New Chat';
-            const firstUserMsg = messages.find(m => m.role === 'user');
-            if (firstUserMsg) {
-                title = firstUserMsg.content.slice(0, 30) + (firstUserMsg.content.length > 30 ? '...' : '');
+            // Only update title from message content if it is a regular chat
+            if (!session?.type || session.type === 'chat') {
+                const firstUserMsg = messages.find(m => m.role === 'user');
+                if (firstUserMsg) {
+                    title = firstUserMsg.content.slice(0, 30) + (firstUserMsg.content.length > 30 ? '...' : '');
+                }
             }
 
             await fetch('/api/history/sessions', {
@@ -201,7 +211,8 @@ export function useChatHistory() {
                 body: JSON.stringify({
                     id: id,
                     title: title,
-                    createdAt: session?.createdAt || Date.now()
+                    createdAt: session?.createdAt || Date.now(),
+                    type: session?.type || 'chat'
                 })
             });
         } catch (e) {

src/lib/db.ts

@@ -7,7 +7,10 @@ function getDb() {
   if (!db) {
     // Try to open the database file
     try {
-        const dbPath = path.join(process.cwd(), 'rag-kb.db');
+        const configuredPath = process.env.RAG_KB_DB_PATH?.trim();
+        const dbPath = configuredPath
+          ? (path.isAbsolute(configuredPath) ? configuredPath : path.join(process.cwd(), configuredPath))
+          : path.join(process.cwd(), 'rag-kb.db');
         db = new Database(dbPath);
     } catch (error) {
         console.warn('Failed to open persistent database, falling back to in-memory database:', error);
@@ -19,7 +22,8 @@ function getDb() {
       CREATE TABLE IF NOT EXISTS sessions (
         id TEXT PRIMARY KEY,
         title TEXT NOT NULL,
-        created_at INTEGER NOT NULL
+        created_at INTEGER NOT NULL,
+        type TEXT DEFAULT 'chat'
       );
 
       CREATE TABLE IF NOT EXISTS messages (
@@ -48,9 +52,21 @@ function getDb() {
         synced_at INTEGER NOT NULL,
         parent_uuid TEXT,
         uuid TEXT,
-        sort_order INTEGER DEFAULT 0
+        sort_order INTEGER DEFAULT 0,
+        word_count INTEGER DEFAULT 0,
+        updated_at INTEGER,
+        created_at INTEGER
       );
+    `);
+
+    // Migration: Add created_at column if it doesn't exist
+    try {
+      db.prepare('ALTER TABLE documents ADD COLUMN created_at INTEGER').run();
+    } catch (error) {
+      // Column likely already exists
+    }
 
+    db.exec(`
       CREATE TABLE IF NOT EXISTS knowledge_bases (
         namespace TEXT PRIMARY KEY,
         name TEXT NOT NULL,
@@ -59,6 +75,8 @@ function getDb() {
       );
     `);
 
+    // Create indexes
+
     // Migration: Add missing columns for documents table if they don't exist
     try {
         const columns = db.prepare("PRAGMA table_info(documents)").all() as { name: string }[];
@@ -79,9 +97,30 @@ function getDb() {
         if (!columnNames.includes('updated_at')) {
             db.exec('ALTER TABLE documents ADD COLUMN updated_at INTEGER');
         }
+        if (!columnNames.includes('tags')) {
+            db.exec('ALTER TABLE documents ADD COLUMN tags TEXT');
+        }
+
+        // Migration: Add last_offset to knowledge_bases
+        const kbColumns = db.prepare("PRAGMA table_info(knowledge_bases)").all() as { name: string }[];
+        const kbColumnNames = kbColumns.map(c => c.name);
+        if (!kbColumnNames.includes('last_offset')) {
+            db.exec('ALTER TABLE knowledge_bases ADD COLUMN last_offset INTEGER DEFAULT 0');
+        }
+
+        // Migration: Add type to sessions
+        const sessionColumns = db.prepare("PRAGMA table_info(sessions)").all() as { name: string }[];
+        const sessionColumnNames = sessionColumns.map(c => c.name);
+        if (!sessionColumnNames.includes('type')) {
+            db.exec("ALTER TABLE sessions ADD COLUMN type TEXT DEFAULT 'chat'");
+        }
     } catch (error) {
         console.error('Database migration failed:', error);
     }
+    
+    try {
+      db.prepare("UPDATE knowledge_bases SET name = ? WHERE namespace = ? AND name = ?").run('小记', 'NOTES', '我的小记');
+    } catch {}
   }
   return db;
 }

src/lib/local-embeddings.ts

@@ -45,6 +45,9 @@ class LocalEmbeddings extends Embeddings {
       const text = doc.replace(/\n/g, " ");
       const output = await pipe(text, { pooling: "mean", normalize: true });
       embeddings.push(Array.from(output.data));
+      
+      // Yield to event loop to prevent blocking server during large batch processing
+      await new Promise(resolve => setTimeout(resolve, 0));
     }
 
     return embeddings;

src/lib/yuque-service.ts

@@ -1,5 +1,6 @@
 
 import { Document } from "@langchain/core/documents";
+import { Embeddings } from "@langchain/core/embeddings";
 import { RecursiveCharacterTextSplitter } from "@langchain/textsplitters";
 import { getEmbeddings } from "./vector-store";
 import { HNSWLib } from "@langchain/community/vectorstores/hnswlib";
@@ -23,6 +24,7 @@ export interface YuqueDoc {
   parent_uuid?: string;
   uuid: string;
   type?: string;
+  tags?: string[];
 }
 
 export interface SyncStatus {
@@ -45,6 +47,53 @@ let currentSyncStatus: SyncStatus = {
     message: ''
 };
 
+// === RATE LIMITER GLOBALS ===
+const MIN_REQUEST_DELAY = Number(process.env.SYNC_MIN_DELAY ?? 100);
+// Timestamp of the last request dispatched
+let lastRequestTime = 0;
+// If we hit a 429, we set this timestamp. All requests must wait until this time.
+let globalRateLimitResetTime = 0;
+const SYNC_RPS = parseInt(process.env.SYNC_RPS ?? '3');
+const SYNC_BURST = parseInt(process.env.SYNC_BURST ?? '6');
+let bucketTokens = SYNC_BURST;
+let lastRefillTime = Date.now();
+let rateLimitHits = 0;
+function refillTokens() {
+  const now = Date.now();
+  const elapsed = now - lastRefillTime;
+  if (elapsed > 0) {
+    const add = (elapsed * SYNC_RPS) / 1000;
+    bucketTokens = Math.min(bucketTokens + add, SYNC_BURST);
+    lastRefillTime = now;
+  }
+}
+async function waitForToken() {
+  while (true) {
+    refillTokens();
+    if (bucketTokens >= 1) {
+      bucketTokens -= 1;
+      return;
+    }
+    const need = 1 - bucketTokens;
+    const waitMs = Math.ceil((need * 1000) / SYNC_RPS);
+    await new Promise((r) => setTimeout(r, Math.max(waitMs, 1)));
+  }
+}
+function consumeRateLimitHits() {
+  const c = rateLimitHits;
+  rateLimitHits = 0;
+  return c;
+}
+
+let isStopRequested = false;
+
+export const stopYuqueSync = () => {
+    if (currentSyncStatus.status === 'running') {
+        isStopRequested = true;
+        currentSyncStatus.message = '正在停止同步...';
+    }
+};
+
 async function asyncPool<T, R>(poolLimit: number, array: T[], iteratorFn: (item: T, array: T[]) => Promise<R>): Promise<R[]> {
   const ret: Promise<R>[] = [];
   const executing: Promise<void>[] = [];
@@ -65,10 +114,10 @@ async function asyncPool<T, R>(poolLimit: number, array: T[], iteratorFn: (item:
   return Promise.all(ret);
 }
 
-class SimpleYuqueLoader {
+export class SimpleYuqueLoader {
   constructor(private token: string, private namespace: string) {}
 
-  private async fetchAPI(endpoint: string) {
+  public async fetchAPI(endpoint: string) {
     const url = `${YUQUE_BASE_URL}${endpoint}`;
     const headers = {
       "X-Auth-Token": this.token,
@@ -76,18 +125,48 @@ class SimpleYuqueLoader {
       "Content-Type": "application/json",
     };
 
-    const maxRetries = 5;
+    const MAX_RETRIES = 3; // Reduced from 5 to fail faster
     let attempt = 0;
+    let lastError: Error | null = null;
 
-    while (attempt < maxRetries) {
+    while (attempt < MAX_RETRIES) {
+      if (isStopRequested) {
+          throw new Error('Sync stopped by user');
+      }
+
+      // === GLOBAL RATE LIMITER CHECK ===
+      const now = Date.now();
+      
+      // 1. Check if we are in a "Cool Down" period from a previous 429
+      if (globalRateLimitResetTime > now) {
+          const waitTime = globalRateLimitResetTime - now;
+          if (waitTime > 1000) {
+            console.log(`[Rate Limit] Global Pause active. Waiting ${Math.round(waitTime/1000)}s...`);
+            currentSyncStatus.message = `触发限流，全局暂停 ${Math.round(waitTime/1000)}秒...`;
+          }
+          await new Promise(resolve => setTimeout(resolve, waitTime));
+      }
+
+      await waitForToken();
+      // 2. Enforce minimum interval between requests (Throttle)
+      const timeSinceLastRequest = Date.now() - lastRequestTime;
+      if (timeSinceLastRequest < MIN_REQUEST_DELAY) {
+          await new Promise(resolve => setTimeout(resolve, MIN_REQUEST_DELAY - timeSinceLastRequest));
+      }
+      lastRequestTime = Date.now();
+      
       let response;
       try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 60000); // Increased to 60s timeout for large docs
+
         if (process.env.HTTPS_PROXY) {
           const agent = new HttpsProxyAgent(process.env.HTTPS_PROXY);
-          response = await nodeFetch(url, { headers, agent });
+          response = await nodeFetch(url, { headers, agent, signal: controller.signal });
         } else {
-          response = await fetch(url, { headers });
+          response = await fetch(url, { headers, signal: controller.signal });
         }
+        clearTimeout(timeoutId);
 
         if (response.ok) {
           return await response.json();
@@ -105,16 +184,22 @@ class SimpleYuqueLoader {
         if (response.status === 429) {
           const retryAfter = response.headers.get('retry-after');
           // Default to exponential backoff if no retry-after header
-          // Aggressively increase base delay: 10s base
-          let delay = retryAfter ? parseInt(retryAfter) * 1000 : 10000 * Math.pow(1.5, attempt);
+          // Aggressively increase base delay: 10s base for 429
+          let delay = retryAfter ? parseInt(retryAfter) * 1000 : 10000 * Math.pow(2, attempt);
           
           // Add larger jitter (random delay between 1000-3000ms)
           delay += 1000 + Math.random() * 2000;
           
-          // Cap at 300s (5 minutes)
-          if (delay > 300000) delay = 300000;
+          // Cap at 60s (1 minute) to avoid "hanging" appearance
+          if (delay > 60000) delay = 60000;
           
-          const msg = `语雀 API 触发速率限制，${Math.round(delay/1000)}秒后重试... (Attempt ${attempt + 1}/${maxRetries})`;
+          // === SET GLOBAL PAUSE ===
+          // If one request hits 429, ALL requests should pause.
+          // We set the global reset time to now + delay.
+          globalRateLimitResetTime = Date.now() + delay;
+          rateLimitHits++;
+
+          const msg = `语雀 API 触发速率限制，${Math.round(delay/1000)}秒后重试... (Attempt ${attempt + 1}/${MAX_RETRIES})`;
           console.warn(msg);
           currentSyncStatus.message = msg;
           
@@ -127,6 +212,7 @@ class SimpleYuqueLoader {
         throw new Error(`Yuque API Error: ${response.status} ${response.statusText} - ${errorText.substring(0, 200)} - ${url}`);
       } catch (error: unknown) {
         const errorMessage = error instanceof Error ? error.message : String(error);
+        lastError = error instanceof Error ? error : new Error(errorMessage);
 
         // If it's an Auth error or 404, stop immediately (re-throw)
         if (errorMessage.includes("Yuque API Auth Error") || errorMessage.includes("Yuque API 404 Not Found")) {
@@ -137,19 +223,25 @@ class SimpleYuqueLoader {
         // If it's a "Yuque API Error" (thrown above), check status inside message if possible, 
         // but we already handled 429.
         
-        console.warn(`Yuque API Request Failed: ${errorMessage}. Retrying... (Attempt ${attempt + 1}/${maxRetries})`);
+        console.warn(`Yuque API Request Failed: ${errorMessage}. Retrying... (Attempt ${attempt + 1}/${MAX_RETRIES})`);
         
-        // General error backoff: 3s * 1.5^attempt
-        const backoff = 3000 * Math.pow(1.5, attempt) + Math.random() * 1000;
+        // General error backoff: 5s * 1.5^attempt
+        const backoff = 5000 * Math.pow(1.5, attempt) + Math.random() * 1000;
         await new Promise(resolve => setTimeout(resolve, backoff));
         attempt++;
       }
     }
     
-    throw new Error(`Yuque API Failed after ${maxRetries} retries: ${url}`);
+    // Ensure lastError is captured even if it wasn't set (e.g. timeout)
+    const errorMsg = lastError ? lastError.message : 'Unknown Error';
+    throw new Error(`Yuque API Failed after ${MAX_RETRIES} retries: ${url}. Last Error: ${errorMsg}`);
   }
 
-  async loadDocList(): Promise<YuqueDoc[]> {
+  async loadDocList(totalCount?: number): Promise<YuqueDoc[]> {
+    if (this.namespace === 'NOTES') {
+        // NOTES are handled separately via streaming/paging now
+        return [];
+    }
     try {
         currentSyncStatus.message = `正在获取目录结构：${this.namespace}...`;
         
@@ -164,7 +256,14 @@ class SimpleYuqueLoader {
         }
 
         // Fetch all docs metadata (including updated_at) to merge
-        const docsMap = await this.fetchAllDocsMetadata();
+        // We pass the TOC count as a loose reference, but we really need the Repo Detail count (which we don't have here easily unless passed in)
+        // But fetchAllDocsMetadata will try to fetch EVERYTHING via paging.
+        const docsMap = await this.fetchAllDocsMetadata(totalCount);
+        
+        // --- INTEGRITY CHECK ---
+        // If we have a TOC, the docsMap size should be roughly similar or larger (TOC includes empty nodes, but docsMap includes orphans)
+        // A better check is usually against the repo info.
+        // We will do a stricter check in the main sync loop.
         
         // Merge Strategy:
         // 1. Start with TOC items (they contain structure info like parent_uuid)
@@ -210,19 +309,74 @@ class SimpleYuqueLoader {
 
     } catch (e: unknown) {
         console.error(`Failed to fetch doc list for ${this.namespace}:`, e);
-        const message = e instanceof Error ? e.message : String(e);
-        if (message.includes("Yuque API Auth Error")) throw e;
-        return [];
+        throw e;
     }
   }
 
-  private async fetchAllDocsMetadata(): Promise<Map<number, YuqueDoc>> {
+  private async fetchAllDocsMetadata(totalCount?: number): Promise<Map<number, YuqueDoc>> {
     const map = new Map<number, YuqueDoc>();
-    let offset = 0;
-    const limit = 100;
+    const limit = 100; // Increased to 100 (max) to reduce requests
     
+    // === OPTIMIZATION: Parallel Fetching if Total Count is Known ===
+    if (totalCount && totalCount > 0) {
+        const totalPages = Math.ceil(totalCount / limit);
+        // Add a safety buffer of 1 extra page just in case count is slightly off
+        const offsets: number[] = [];
+        for (let i = 0; i < totalPages + 1; i++) {
+            offsets.push(i * limit);
+        }
+
+        console.log(`[Metadata Sync] Parallel fetching ${offsets.length} pages for ${this.namespace} (Total: ${totalCount})...`);
+
+        // Use asyncPool to limit concurrency to avoid aggressive rate limiting
+        // Reduced from 5 to 3 to be safer
+        const metaConcurrency = parseInt(process.env.SYNC_METADATA_CONCURRENCY ?? '5');
+        await asyncPool(metaConcurrency, offsets, async (offset) => {
+             try {
+                if (isStopRequested) return;
+
+                const res = await this.fetchAPI(`/repos/${this.namespace}/docs?offset=${offset}&limit=${limit}`);
+                const list = res.data as YuqueDoc[];
+                
+                if (list && list.length > 0) {
+                    list.forEach(d => map.set(d.id, d));
+                    // Update progress message periodically
+                    if (map.size % 500 === 0) {
+                        currentSyncStatus.message = `正在并行获取元数据：${this.namespace} (已获取 ${map.size}/${totalCount})...`;
+                    }
+                }
+             } catch (e: unknown) {
+                 const message = e instanceof Error ? e.message : String(e);
+                 // If we hit 404/Auth, we stop.
+                 // If we hit Rate Limit, fetchAPI already retries.
+                 // If we still fail, we log but continue other pages? 
+                 // No, for metadata, if we miss a page, we miss docs. We should throw.
+                 if (message.includes("Yuque API Auth Error") || message.includes("Sync stopped by user")) {
+                     throw e;
+                 }
+                 console.warn(`[Metadata Sync] Warning: Failed to fetch page at offset ${offset}: ${message}`);
+                 // We rely on Integrity Check later to catch missing docs.
+             }
+        });
+
+        if (map.size > 0) {
+            return map;
+        }
+        // If map is empty or something failed silently, fallback to sequential?
+        // No, if totalCount was > 0 and we got 0, something is wrong.
+        if (totalCount > 0 && map.size === 0) {
+             console.warn(`[Metadata Sync] Parallel fetch returned 0 items but expected ${totalCount}. Falling back to sequential.`);
+        } else {
+             return map;
+        }
+    }
+
+    // === FALLBACK: Sequential Fetching (Old Logic) ===
+    let offset = 0;
     while (true) {
         try {
+            if (isStopRequested) throw new Error('Sync stopped by user');
+
             currentSyncStatus.message = `正在获取元数据：${this.namespace} (已获取 ${map.size})...`;
             const res = await this.fetchAPI(`/repos/${this.namespace}/docs?offset=${offset}&limit=${limit}`);
             const list = res.data as YuqueDoc[];
@@ -233,24 +387,40 @@ class SimpleYuqueLoader {
             
             if (list.length < limit) break;
             // Increased delay to prevent rate limiting
-            await new Promise(resolve => setTimeout(resolve, 1000));
+            await new Promise(resolve => setTimeout(resolve, 500));
         } catch (e: unknown) {
-            console.error(`Error fetching docs list page for ${this.namespace}:`, e);
+            console.error(`Error fetching docs list page for ${this.namespace} at offset ${offset}:`, e);
             const message = e instanceof Error ? e.message : String(e);
-            if (message.includes("Yuque API Auth Error")) throw e;
-            break;
+            
+            // Critical errors that should stop the process
+            if (message.includes("Yuque API Auth Error") || message.includes("Sync stopped by user")) {
+                throw e;
+            }
+            
+            // For other errors (like network timeout after retries), we should ALSO throw to avoid partial sync.
+            // Previously we used 'break', which caused the "incomplete sync marked as success" issue.
+            throw new Error(`Failed to fetch complete doc list at offset ${offset}. Sync aborted to ensure data integrity. Error: ${message}`);
         }
     }
     return map;
   }
 
-  async fetchRepoDetail(): Promise<{ name: string; description: string; updated_at: string } | null> {
+  async fetchRepoDetail(): Promise<{ name: string; description: string; updated_at: string; items_count: number } | null> {
+    if (this.namespace === 'NOTES') {
+        return {
+            name: '小记',
+            description: '来自语雀小记的内容',
+            updated_at: new Date().toISOString(),
+            items_count: 0 // Notes count is dynamic
+        };
+    }
     try {
         const data = await this.fetchAPI(`/repos/${this.namespace}`);
         return {
             name: data.data.name,
             description: data.data.description || '',
-            updated_at: data.data.updated_at
+            updated_at: data.data.updated_at,
+            items_count: data.data.items_count || 0
         };
     } catch (e: unknown) {
         console.error(`Failed to fetch repo detail for ${this.namespace}:`, e);
@@ -261,6 +431,9 @@ class SimpleYuqueLoader {
   }
 
   async fetchDocDetail(docInfo: YuqueDoc): Promise<Document | null> {
+      if (this.namespace === 'NOTES') {
+          return this.fetchNoteDetail(docInfo);
+      }
       try {
         const detailData = await this.fetchAPI(`/repos/${this.namespace}/docs/${docInfo.id}`);
         const docDetail = detailData.data;
@@ -281,11 +454,58 @@ class SimpleYuqueLoader {
         }
       } catch (e: unknown) {
         const message = e instanceof Error ? e.message : String(e);
-        if (message.includes("Yuque API Auth Error")) throw e;
+        if (message.includes("Yuque API Auth Error") || message.includes("Sync stopped by user")) throw e;
         console.error(`Failed to fetch doc ${docInfo.title}:`, e);
       }
       return null;
   }
+ 
+   public extractNoteTitle(abstract?: string): string {
+     if (!abstract) return '无标题小记';
+     // Remove HTML tags and take first 200 chars (increased from 100)
+     const text = abstract.replace(/<[^>]+>/g, '').trim();
+     return text.substring(0, 200) + (text.length > 200 ? '...' : '');
+   }
+ 
+   async fetchNoteDetail(docInfo: YuqueDoc): Promise<Document | null> {
+     try {
+         const res = await this.fetchAPI(`/notes/${docInfo.id}`);
+         const noteData = res.data;
+         // Prefer HTML content, fallback to abstract
+         const htmlContent = noteData.content?.html || noteData.content?.abstract || "";
+        
+        // Simple HTML to Text conversion (very basic)
+        // For RAG, we prefer text. 
+        // We can use a regex to strip tags, but keep line breaks.
+        let textContent = htmlContent
+            .replace(/<br\s*\/?>/gi, '\n')
+            .replace(/<\/p>/gi, '\n')
+            .replace(/<\/div>/gi, '\n')
+            .replace(/<[^>]+>/g, '');
+        
+        textContent = textContent.replace(/&nbsp;/g, ' ').trim();
+
+        if (textContent) {
+            return new Document({
+                pageContent: textContent,
+                metadata: {
+                    source: `yuque://NOTES/${docInfo.slug}`,
+                    title: docInfo.title,
+                    id: docInfo.id,
+                    yuque_slug: docInfo.slug,
+                    namespace: 'NOTES',
+                    type: 'NOTE',
+                    url: `https://www.yuque.com/dashboard/notes` // Notes don't have public URLs usually
+                }
+            });
+        }
+    } catch (e: unknown) {
+        const message = e instanceof Error ? e.message : String(e);
+        if (message.includes("Sync stopped by user")) throw e;
+        console.error("Failed to fetch note detail", e);
+    }
+    return null;
+  }
 }
 
 export const getSyncStatus = () => currentSyncStatus;
@@ -297,7 +517,14 @@ export const startYuqueSync = async () => {
 
     const token = process.env.YUQUE_TOKEN;
     const namespacesEnv = process.env.YUQUE_NAMESPACE;
-    const apiKey = process.env.GOOGLE_GENERATIVE_AI_API_KEY;
+    
+    // Check initial DB state
+    try {
+        const count = db.prepare('SELECT COUNT(*) as c FROM documents').get() as { c: number };
+        console.log(`[Start Sync] Current DB document count: ${count.c}`);
+    } catch (e) {
+        console.log(`[Start Sync] Could not check DB count (DB might be new): ${e}`);
+    }
 
     if (!token || !namespacesEnv) {
         currentSyncStatus = { ...currentSyncStatus, status: 'error', error: '缺少环境变量配置' };
@@ -312,22 +539,26 @@ export const startYuqueSync = async () => {
         totalBatches: 0,
         status: 'running'
     };
+    isStopRequested = false;
 
     // Run in background (don't await this promise in the API handler)
     (async () => {
         try {
             const namespaces = namespacesEnv.split(",").map(s => s.trim()).filter(Boolean);
             const embeddings = getEmbeddings();
+            let hasError = false;
 
             const splitter = new RecursiveCharacterTextSplitter({
                 chunkSize: 1000,
                 chunkOverlap: 200,
             });
 
-            const BATCH_SIZE = 50;
-            const CONCURRENCY = 5; // Increased concurrency for faster sync
+            const BATCH_SIZE = parseInt(process.env.SYNC_BATCH_SIZE ?? '100');
+            const CONCURRENCY = parseInt(process.env.SYNC_CONCURRENCY ?? '3');
 
             for (const ns of namespaces) {
+                if (isStopRequested) break;
+
                 // Reset progress for the new namespace to avoid UI confusion
                 currentSyncStatus.total = 0;
                 currentSyncStatus.processed = 0;
@@ -338,28 +569,47 @@ export const startYuqueSync = async () => {
                     // Fetch and save KB info
                     currentSyncStatus.message = `正在获取知识库信息：${ns}...`;
                     const repoInfo = await loader.fetchRepoDetail();
+                    
+                    if (ns === 'NOTES') {
+                        // === SPECIAL HANDLING FOR NOTES (PAGED/STREAMED SYNC) ===
+                        console.log(`[Sync] Starting Paged Sync for NOTES...`);
+                        const notesConcurrency = parseInt(process.env.NOTES_CONCURRENCY ?? '2');
+                        await syncNotesWithPaging(loader, splitter, embeddings, BATCH_SIZE, notesConcurrency);
+                        continue; // Skip the standard flow
+                    }
+
+                    if (!repoInfo) {
+                        console.error(`[Sync] Skipping ${ns}: Could not fetch repository details (404 or access denied). Check your namespace configuration.`);
+                        currentSyncStatus.message = `无法访问知识库：${ns} (请检查配置)`;
+                        hasError = true;
+                        continue;
+                    }
+
                     if (repoInfo) {
-                        // SMART SYNC CHECK
+                        // SMART SYNC CHECK (Standard KB)
                         const forceFullSync = process.env.FORCE_FULL_SYNC === 'true';
                         
                         // Check local DB for last sync time
                         const localKb = db.prepare('SELECT synced_at FROM knowledge_bases WHERE namespace = ?').get(ns) as { synced_at: number } | undefined;
+                        const docCount = db.prepare('SELECT COUNT(*) as c FROM documents WHERE namespace = ?').get(ns) as { c: number };
                         
                         const repoUpdatedAt = new Date(repoInfo.updated_at).getTime();
                         
-                        // If local sync time >= repo update time, we are up to date.
-                        if (!forceFullSync && localKb && localKb.synced_at >= repoUpdatedAt) {
-                             console.log(`[Smart Sync] Skipping ${ns} (Up to date). Repo Updated: ${repoInfo.updated_at}, Last Sync: ${new Date(localKb.synced_at).toISOString()}`);
-                             currentSyncStatus.message = `知识库【${repoInfo.name}】已是最新，跳过同步。`;
+                        // If local sync time >= repo update time AND we have documents AND document count matches roughly, we are up to date.
+                        // We use a threshold of 5% difference or 10 docs to allow for small discrepancies (drafts, etc)
+                        // But if user reports large diff (4000 vs 8000), this check will fail and force sync.
+                        const isCountMatch = Math.abs(docCount.c - repoInfo.items_count) < 5 || (repoInfo.items_count > 0 && Math.abs(docCount.c - repoInfo.items_count) / repoInfo.items_count < 0.05);
+
+                        if (!forceFullSync && localKb && localKb.synced_at >= repoUpdatedAt && docCount.c > 0 && isCountMatch) {
+                             console.log(`[Smart Sync] Skipping ${ns} (Up to date). Repo Updated: ${repoInfo.updated_at}, Last Sync: ${new Date(localKb.synced_at).toISOString()}, Docs: ${docCount.c} (Remote: ${repoInfo.items_count})`);
+                             currentSyncStatus.message = `知识库【${repoInfo.name}】已是最新 (本地:${docCount.c}/云端:${repoInfo.items_count})，跳过同步。`;
                              await new Promise(resolve => setTimeout(resolve, 1500)); 
                              continue;
+                        } else if (!forceFullSync && localKb && localKb.synced_at >= repoUpdatedAt && !isCountMatch) {
+                            console.log(`[Smart Sync] Force Syncing ${ns} due to document count mismatch. Local: ${docCount.c}, Remote: ${repoInfo.items_count}`);
+                            currentSyncStatus.message = `发现数量不一致 (本地:${docCount.c}/云端:${repoInfo.items_count})，强制同步【${repoInfo.name}】...`;
+                            await new Promise(resolve => setTimeout(resolve, 1500));
                         }
-
-                        const stmt = db.prepare(`
-                            INSERT OR REPLACE INTO knowledge_bases (namespace, name, description, synced_at)
-                            VALUES (?, ?, ?, ?)
-                        `);
-                        stmt.run(ns, repoInfo.name, repoInfo.description, Date.now());
                     }
 
                     // Minimal delay between requests
@@ -367,7 +617,24 @@ export const startYuqueSync = async () => {
 
                     // Fetch List
                     currentSyncStatus.message = `正在获取文档列表：${ns}...`;
-                    const docs = await loader.loadDocList();
+                    const docs = await loader.loadDocList(repoInfo ? repoInfo.items_count : undefined);
+
+                    // --- INTEGRITY CHECK ---
+                    // Verify if we fetched a reasonable amount of docs compared to repo info
+                    if (repoInfo && repoInfo.items_count > 0) {
+                        const fetchedCount = docs.filter(d => d.type === 'DOC' || !d.type).length; // Filter out titles/dirs
+                        // Allow 10% deviation or 20 docs diff (whichever is larger)
+                        const diff = Math.abs(fetchedCount - repoInfo.items_count);
+                        const allowedDiff = Math.max(20, repoInfo.items_count * 0.1);
+                        
+                        if (diff > allowedDiff) {
+                             console.warn(`[Integrity Check Failed] ${ns}: Fetched ${fetchedCount} docs, but Repo says ${repoInfo.items_count}. Deviation: ${diff}`);
+                             // We should probably NOT stop, but we MUST mark this as a "Partial Sync" so we don't update the 'synced_at' timestamp
+                             hasError = true; 
+                             currentSyncStatus.message = `警告：文档数量差异大 (获取 ${fetchedCount} / 预期 ${repoInfo.items_count})，本次同步将不标记为完成。`;
+                             // Allow to proceed to try and sync what we have, but ensure we don't mark KB as fully synced.
+                        }
+                    }
                     
                     type DocItem = { namespace: string; doc: YuqueDoc; index: number };
                     const docsWithIndex: DocItem[] = docs.map((d, i) => ({ namespace: ns, doc: d, index: i }));
@@ -375,10 +642,6 @@ export const startYuqueSync = async () => {
                     currentSyncStatus.total += docsWithIndex.length;
                     
                     // --- INCREMENTAL SYNC OPTIMIZATION ---
-                    // Separate documents into two queues:
-                    // 1. downloadQueue: Needs full content fetch (New or Updated)
-                    // 2. metadataQueue: Only needs metadata update (Skipped content fetch)
-                    
                     const downloadQueue: DocItem[] = [];
                     const metadataQueue: DocItem[] = [];
                     const titleNodeQueue: DocItem[] = [];
@@ -427,44 +690,21 @@ export const startYuqueSync = async () => {
                          currentSyncStatus.message = `正在快速更新 ${metadataQueue.length} 篇无变更文档的元数据：${ns}...`;
                          const updateStmt = db.prepare(`
                             UPDATE documents 
-                            SET word_count = ?, updated_at = ?, sort_order = ?, title = ?, parent_uuid = ?
+                            SET word_count = ?, updated_at = ?, sort_order = ?, title = ?, parent_uuid = ?, created_at = ?
                             WHERE id = ?
                          `);
                          
-                         const insertTitleStmt = db.prepare(`
-                            INSERT OR REPLACE INTO documents (id, yuque_id, title, slug, url, namespace, content_preview, synced_at, parent_uuid, uuid, sort_order, word_count, updated_at)
-                            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-                         `);
-
                          const transaction = db.transaction(() => {
-                             // Process Metadata Queue
                              for (const item of metadataQueue) {
                                  const docId = `${item.namespace}/${item.doc.slug}`;
                                  const updatedAt = item.doc.updated_at ? new Date(item.doc.updated_at).getTime() : Date.now();
+                                 const createdAt = item.doc.created_at ? new Date(item.doc.created_at).getTime() : updatedAt;
                                  const wordCount = item.doc.word_count || 0;
-                                 updateStmt.run(wordCount, updatedAt, item.index, item.doc.title, item.doc.parent_uuid || null, docId);
+                                 updateStmt.run(wordCount, updatedAt, item.index, item.doc.title, item.doc.parent_uuid || null, createdAt, docId);
                              }
                              // Process Title Nodes (Always fast)
                              for (const item of titleNodeQueue) {
-                                 const uniqueId = `${item.namespace}/dir-${item.doc.uuid}`;
-                                 const uniqueSlug = `dir-${item.doc.uuid}`;
-                                 const updatedAt = item.doc.updated_at ? new Date(item.doc.updated_at).getTime() : Date.now();
-                                 
-                                 insertTitleStmt.run(
-                                    uniqueId,
-                                    item.doc.id || 0,
-                                    item.doc.title,
-                                    uniqueSlug,
-                                    `https://www.yuque.com/${item.namespace}/#${uniqueSlug}`,
-                                    item.namespace,
-                                    '', 
-                                    Date.now(),
-                                    item.doc.parent_uuid || null,
-                                    item.doc.uuid,
-                                    item.index,
-                                    0,
-                                    updatedAt
-                                 );
+                                 processTitleNode(item);
                              }
                          });
                          
@@ -474,107 +714,390 @@ export const startYuqueSync = async () => {
 
                     // 2. Slow Process: Download Content (Only for new/updated docs)
                     if (downloadQueue.length > 0) {
-                        const nsTotalBatches = Math.ceil(downloadQueue.length / BATCH_SIZE);
-                        currentSyncStatus.totalBatches += nsTotalBatches;
-
-                        const nsDocsForVectorStore: Document[] = [];
-
-                        for (let i = 0; i < downloadQueue.length; i += BATCH_SIZE) {
-                            currentSyncStatus.currentBatch++; 
-                            const batchInfos = downloadQueue.slice(i, i + BATCH_SIZE);
-                            currentSyncStatus.message = `正在下载文档内容：${ns} (批次 ${Math.floor(i / BATCH_SIZE) + 1}/${nsTotalBatches})...`;
-
-                            await asyncPool(CONCURRENCY, batchInfos, async (item) => {
-                                try {
-                                    // Removed artificial delay to improve speed. 
-                                    // We rely on fetchAPI's 429 handling for rate limits.
-                                    
-                                    const docId = `${item.namespace}/${item.doc.slug}`;
-                                    const updatedAt = item.doc.updated_at ? new Date(item.doc.updated_at).getTime() : Date.now();
-                                    
-                                    const loader = new SimpleYuqueLoader(token, item.namespace);
-                                    const doc = await loader.fetchDocDetail(item.doc);
-                                    if (doc) {
-                                        nsDocsForVectorStore.push(doc);
-                                        
-                                        const wordCount = item.doc.word_count || (doc.pageContent ? doc.pageContent.length : 0);
-                                        
-                                        try {
-                                            const stmt = db.prepare(`
-                                                INSERT OR REPLACE INTO documents (id, yuque_id, title, slug, url, namespace, content_preview, synced_at, parent_uuid, uuid, sort_order, word_count, updated_at)
-                                                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-                                            `);
-                                            
-                                            stmt.run(
-                                                docId,
-                                                item.doc.id,
-                                                item.doc.title,
-                                                item.doc.slug,
-                                                doc.metadata.url,
-                                                item.namespace,
-                                                doc.pageContent, // Save full content
-                                                Date.now(),
-                                                item.doc.parent_uuid || null,
-                                                item.doc.uuid,
-                                                item.index, // Use index as sort_order
-                                                wordCount,
-                                                updatedAt
-                                            );
-                                        } catch (e) {
-                                            console.error(`Failed to save document ${docId} to DB:`, e);
-                                        }
-                                    }
-                                    currentSyncStatus.processed++;
-                                } catch (docError) {
-                                    console.error(`Failed to process document ${item.doc.title} (${item.doc.slug}):`, docError);
-                                    // Don't throw here, so other docs can continue
-                                }
-                            });
-                        }
-                        
-                        // Update Vector Store per namespace to save progress
-                        if (nsDocsForVectorStore.length > 0) {
-                            currentSyncStatus.message = `正在更新 ${ns} 的向量索引 (${nsDocsForVectorStore.length} 篇文档)...`;
-                            console.log(`Updating vector store with ${nsDocsForVectorStore.length} new/updated documents for ${ns}...`);
-                            const chunks = await splitter.splitDocuments(nsDocsForVectorStore);
-                            
-                            let vectorStore: HNSWLib | null = null;
-                            const indexFile = path.join(VECTOR_STORE_PATH, "hnswlib.index");
-
-                            if (fs.existsSync(indexFile)) {
-                                try {
-                                    const loadedStore = await HNSWLib.load(VECTOR_STORE_PATH, embeddings);
-                                    await loadedStore.addDocuments(chunks);
-                                    vectorStore = loadedStore;
-                                } catch (err) {
-                                    console.error("Failed to load vector store (corruption detected), resetting:", err);
-                                }
-                            } 
-                            
-                            if (!vectorStore) {
-                                vectorStore = await HNSWLib.fromDocuments(chunks, embeddings);
-                            }
-                            await vectorStore.save(VECTOR_STORE_PATH);
-                            
-                            // Clear memory
-                            nsDocsForVectorStore.length = 0;
-                        }
+                        await processDownloadQueue(downloadQueue, loader, splitter, embeddings, BATCH_SIZE, CONCURRENCY);
+                    }
+
+                    // Update KB info (Success) - Only update if not stopped AND no error occurred
+                    // Note: hasError might be set by the integrity check above
+                    if (repoInfo && !isStopRequested && !hasError) {
+                        const stmt = db.prepare(`
+                            INSERT OR REPLACE INTO knowledge_bases (namespace, name, description, synced_at)
+                            VALUES (?, ?, ?, ?)
+                        `);
+                        stmt.run(ns, repoInfo.name, repoInfo.description, Date.now());
+                    } else if (hasError) {
+                        console.log(`[Sync] Skipping KB timestamp update for ${ns} due to errors/integrity check failure.`);
                     }
 
                 } catch (e: unknown) {
                     console.error(`Failed to sync namespace ${ns}:`, e);
+                    hasError = true;
                     const message = e instanceof Error ? e.message : String(e);
-                    if (message.includes("Yuque API Auth Error")) throw e;
+                    if (message.includes("Yuque API Auth Error") || message.includes("Sync stopped by user")) throw e;
                 }
             }
             
-            currentSyncStatus.status = 'completed';
-            currentSyncStatus.message = '同步已完成';
+            if (isStopRequested) {
+                currentSyncStatus.status = 'idle';
+                currentSyncStatus.message = '同步已停止';
+            } else if (hasError) {
+                currentSyncStatus.status = 'error';
+                currentSyncStatus.message = '同步完成，但部分知识库失败，请查看后台日志';
+            } else {
+                currentSyncStatus.status = 'completed';
+                currentSyncStatus.message = '同步已完成';
+            }
+            
+            // Log final count
+            try {
+                const count = db.prepare('SELECT COUNT(*) as c FROM documents').get() as { c: number };
+                console.log(`[End Sync] Final DB document count: ${count.c}`);
+            } catch (e) {}
 
         } catch (error) {
-            console.error("Sync failed:", error);
-            currentSyncStatus.status = 'error';
-            currentSyncStatus.error = error instanceof Error ? error.message : String(error);
-        }
+            const msg = error instanceof Error ? error.message : String(error);
+            if (msg.includes("Sync stopped by user")) {
+                 console.log("Sync process stopped by user.");
+                 currentSyncStatus.status = 'idle';
+                 currentSyncStatus.message = '同步已停止';
+            } else {
+                 console.error("Sync failed:", error);
+                 currentSyncStatus.status = 'error';
+                 currentSyncStatus.error = msg;
+            }
+    }
     })();
 };
+
+let lastTagsBackfillAt = 0;
+export const backfillNoteTags = async (pageLimit = 200, pages = 3) => {
+  try {
+    const token = process.env.YUQUE_TOKEN;
+    if (!token) return;
+    const now = Date.now();
+    if (now - lastTagsBackfillAt < 30000) return;
+    lastTagsBackfillAt = now;
+    const loader = new SimpleYuqueLoader(token, 'NOTES');
+    let offset = 0;
+    for (let i = 0; i < pages; i++) {
+      const res = await loader.fetchAPI(`/notes?offset=${offset}&limit=${pageLimit}`);
+      const rawNotes = (res && res.data && Array.isArray(res.data.notes)) ? res.data.notes : [];
+      if (!rawNotes || rawNotes.length === 0) break;
+      const items = rawNotes.map((n: { slug: string; tags?: unknown }) => ({
+        slug: n.slug,
+        tags: Array.isArray(n.tags) ? (n.tags as unknown[]).map((t: unknown) => {
+          if (typeof t === 'string') return t;
+          if (t && typeof t === 'object') {
+             const record = t as Record<string, unknown>;
+             // Check for 'title' (standard docs) or 'name' (notes)
+             const v = record['title'] || record['name'];
+             return typeof v === 'string' ? v : '';
+          }
+          return '';
+        }).filter((s: string) => s.length > 0) : []
+      }));
+      const tx = db.transaction(() => {
+        const stmt = db.prepare('UPDATE documents SET tags = ? WHERE id = ?');
+        for (const it of items) {
+          const id = `NOTES/${it.slug}`;
+          stmt.run(JSON.stringify(it.tags || []), id);
+        }
+      });
+      tx();
+      offset += pageLimit;
+      if (rawNotes.length < pageLimit) break;
+    }
+  } catch {}
+};
+
+
+// === HELPER FUNCTIONS ===
+
+function processTitleNode(item: { namespace: string; doc: YuqueDoc; index: number }) {
+    const insertTitleStmt = db.prepare(`
+        INSERT OR REPLACE INTO documents (id, yuque_id, title, slug, url, namespace, content_preview, synced_at, parent_uuid, uuid, sort_order, word_count, updated_at, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+    
+    const uniqueId = `${item.namespace}/dir-${item.doc.uuid}`;
+    const uniqueSlug = `dir-${item.doc.uuid}`;
+    const updatedAt = item.doc.updated_at ? new Date(item.doc.updated_at).getTime() : Date.now();
+    const createdAt = item.doc.created_at ? new Date(item.doc.created_at).getTime() : updatedAt;
+    
+    insertTitleStmt.run(
+       uniqueId,
+       item.doc.id || 0,
+       item.doc.title,
+       uniqueSlug,
+       `https://www.yuque.com/${item.namespace}/#${uniqueSlug}`,
+       item.namespace,
+       '', 
+       Date.now(),
+       item.doc.parent_uuid || null,
+       item.doc.uuid,
+       item.index,
+       0,
+       updatedAt,
+       createdAt
+    );
+}
+
+async function syncNotesWithPaging(loader: SimpleYuqueLoader, splitter: RecursiveCharacterTextSplitter, embeddings: Embeddings, batchSize: number, concurrency: number) {
+    let offset = 0;
+    const rawLimit = parseInt(process.env.YUQUE_NOTES_LIMIT ?? '50');
+    const maxLimitEnv = parseInt(process.env.YUQUE_NOTES_MAX ?? '50');
+    const safeMax = Number.isFinite(maxLimitEnv) && maxLimitEnv > 0 ? maxLimitEnv : 50;
+    const limit = Math.min(Number.isFinite(rawLimit) ? rawLimit : safeMax, safeMax);
+    const ns = 'NOTES';
+    let hasMore = true;
+    const forceFullSync = process.env.FORCE_FULL_SYNC === 'true';
+
+    // Get existing sync state
+    const kbInfo = db.prepare('SELECT last_offset FROM knowledge_bases WHERE namespace = ?').get(ns) as { last_offset: number } | undefined;
+    
+    if (forceFullSync) {
+        console.log(`[NOTES Sync] Force Full Sync enabled. Resetting offset to 0.`);
+        offset = 0;
+        // Reset offset in DB
+        db.prepare('UPDATE knowledge_bases SET last_offset = 0 WHERE namespace = ?').run(ns);
+    } else if (kbInfo && kbInfo.last_offset) {
+        offset = kbInfo.last_offset;
+        console.log(`[NOTES Sync] Resuming from offset ${offset}...`);
+    }
+
+    // Save initial KB info (preserve existing offset)
+    const insertKbStmt = db.prepare(`
+        INSERT OR REPLACE INTO knowledge_bases (namespace, name, description, synced_at, last_offset)
+        VALUES (?, ?, ?, ?, ?)
+    `);
+    insertKbStmt.run('NOTES', '小记', '来自语雀小记的内容', Date.now(), offset);
+
+    while (hasMore) {
+        currentSyncStatus.message = `正在同步小记 (Offset: ${offset})...`;
+        console.log(`[NOTES Sync] Fetching batch offset ${offset}...`);
+
+        let notesBatch: YuqueDoc[] = [];
+        try {
+            const res = await loader.fetchAPI(`/notes?offset=${offset}&limit=${limit}`);
+            const rawNotes = res.data.notes || [];
+            console.log(`[NOTES Sync] Requested limit=${limit}, received=${rawNotes.length} items at offset=${offset}`);
+            
+            if (rawNotes.length === 0) {
+                hasMore = false;
+                // Sync complete, reset offset for next time? 
+                // Or keep it to indicate we reached the end?
+                // Usually for paging APIs, if we finish, next time we might want to start from 0 to check for new items 
+                // OR we rely on the "incremental" check within the first few pages.
+                // But since new notes appear at the TOP (offset 0), resuming from 28000 doesn't help find NEW notes.
+                // "Resumable" is useful for the INITIAL sync or if it crashes in the middle.
+                // Once completed, we should probably reset offset to 0 so next run checks from start.
+                console.log(`[NOTES Sync] No more notes found. Sync complete.`);
+                
+                // Reset offset to 0 for next run (so we check from beginning next time)
+                db.prepare('UPDATE knowledge_bases SET last_offset = 0 WHERE namespace = ?').run(ns);
+                break;
+            }
+
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            notesBatch = rawNotes.map((n: any) => ({
+                id: n.id,
+                slug: n.slug,
+                title: loader.extractNoteTitle(n.content?.abstract) || `小记-${n.id}`,
+                created_at: n.created_at,
+                updated_at: n.updated_at,
+                uuid: n.slug, 
+                type: 'NOTE',
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                tags: Array.isArray(n.tags) ? n.tags.map((t: any) => t.title || t.name || t) : []
+            }));
+
+            if (rawNotes.length < limit) {
+                hasMore = false;
+                // We reached the end
+                console.log(`[NOTES Sync] Reached last page.`);
+                db.prepare('UPDATE knowledge_bases SET last_offset = 0 WHERE namespace = ?').run(ns);
+            }
+        } catch (e) {
+            console.error(`[NOTES Sync] Failed to fetch batch at offset ${offset}:`, e);
+            throw e; // Stop sync on API error
+        }
+
+        // Identify which notes need download (Incremental check)
+        // Since we are paging, we process this batch immediately
+        const downloadQueue: { namespace: string; doc: YuqueDoc; index: number }[] = [];
+        const metadataQueue: { namespace: string; doc: YuqueDoc; index: number }[] = [];
+
+        const existingDocs = db.prepare(`SELECT id, synced_at FROM documents WHERE namespace = 'NOTES' AND id IN (${notesBatch.map(n => `'NOTES/${n.slug}'`).join(',')})`).all() as { id: string, synced_at: number }[];
+        const existingDocsMap = new Map(existingDocs.map(d => [d.id, d]));
+
+        // Check forced sync again (already checked at start, but good to keep variable scope)
+        // const forceFullSync = process.env.FORCE_FULL_SYNC === 'true'; 
+
+        notesBatch.forEach((note, idx) => {
+            const docId = `NOTES/${note.slug}`;
+            const existing = existingDocsMap.get(docId);
+            const yuqueTime = note.updated_at ? new Date(note.updated_at).getTime() : Date.now();
+            const index = offset + idx;
+
+            if (forceFullSync) {
+                downloadQueue.push({ namespace: 'NOTES', doc: note, index });
+            } else if (existing && existing.synced_at >= yuqueTime) {
+                metadataQueue.push({ namespace: 'NOTES', doc: note, index });
+            } else {
+                downloadQueue.push({ namespace: 'NOTES', doc: note, index });
+            }
+        });
+
+        // Update Metadata
+        if (metadataQueue.length > 0) {
+            const updateStmt = db.prepare(`
+               UPDATE documents 
+               SET updated_at = ?, sort_order = ?, title = ?, tags = ?
+               WHERE id = ?
+            `);
+            const transaction = db.transaction(() => {
+                for (const item of metadataQueue) {
+                    const docId = `NOTES/${item.doc.slug}`;
+                    const updatedAt = item.doc.updated_at ? new Date(item.doc.updated_at).getTime() : Date.now();
+                    updateStmt.run(updatedAt, item.index, item.doc.title, JSON.stringify(item.doc.tags || []), docId);
+                }
+            });
+            transaction();
+            currentSyncStatus.processed += metadataQueue.length;
+        }
+
+        // Download & Save Content
+        if (downloadQueue.length > 0) {
+            await processDownloadQueue(downloadQueue, loader, splitter, embeddings, batchSize, concurrency);
+        }
+
+        // Advance offset and Save Progress
+        offset += limit;
+        if (hasMore) {
+             // Only save offset if we are NOT done yet. 
+             // If we are done, we reset to 0 (handled above).
+             db.prepare('UPDATE knowledge_bases SET last_offset = ? WHERE namespace = ?').run(offset, ns);
+        }
+        
+    currentSyncStatus.total = offset; // Approx total for progress bar
+        
+        // Anti-rate-limit delay
+        const pageDelay = parseInt(process.env.NOTES_PAGE_DELAY_MS ?? '500');
+        await new Promise(resolve => setTimeout(resolve, Math.max(0, pageDelay)));
+    }
+}
+
+async function processDownloadQueue(
+    downloadQueue: { namespace: string; doc: YuqueDoc; index: number }[],
+    loader: SimpleYuqueLoader,
+    splitter: RecursiveCharacterTextSplitter,
+    embeddings: Embeddings,
+    batchSize: number,
+    concurrency: number
+) {
+    const nsTotalBatches = Math.ceil(downloadQueue.length / batchSize);
+    currentSyncStatus.totalBatches += nsTotalBatches;
+
+    const nsDocsForVectorStore: Document[] = [];
+    let currentConcurrency = Math.max(1, Math.floor(concurrency / 2));
+    const maxConcurrency = Math.max(1, concurrency);
+
+    for (let i = 0; i < downloadQueue.length; i += batchSize) {
+        if (isStopRequested) break;
+        currentSyncStatus.currentBatch++; 
+        const batchInfos = downloadQueue.slice(i, i + batchSize);
+        const ns = batchInfos[0].namespace;
+        currentSyncStatus.message = `正在下载文档内容：${ns} (批次 ${Math.floor(i / batchSize) + 1}/${nsTotalBatches})...`;
+
+        // Clear previous batch docs
+        nsDocsForVectorStore.length = 0;
+
+        await asyncPool(currentConcurrency, batchInfos, async (item) => {
+            try {
+                const docId = `${item.namespace}/${item.doc.slug}`;
+                const updatedAt = item.doc.updated_at ? new Date(item.doc.updated_at).getTime() : Date.now();
+                const createdAt = item.doc.created_at ? new Date(item.doc.created_at).getTime() : updatedAt;
+                
+                const doc = await loader.fetchDocDetail(item.doc);
+                if (doc) {
+                    nsDocsForVectorStore.push(doc);
+                    
+                    const wordCount = item.doc.word_count || (doc.pageContent ? doc.pageContent.length : 0);
+                    
+                    try {
+                        const stmt = db.prepare(`
+                            INSERT OR REPLACE INTO documents (id, yuque_id, title, slug, url, namespace, content_preview, synced_at, parent_uuid, uuid, sort_order, word_count, updated_at, created_at, tags)
+                            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                        `);
+                        
+                        stmt.run(
+                            docId,
+                            item.doc.id,
+                            item.doc.title,
+                            item.doc.slug,
+                            doc.metadata.url,
+                            item.namespace,
+                            doc.pageContent, // Save full content
+                            Date.now(),
+                            item.doc.parent_uuid || null,
+                            item.doc.uuid,
+                            item.index, // Use index as sort_order
+                            wordCount,
+                            updatedAt,
+                            createdAt,
+                            JSON.stringify(item.doc.tags || [])
+                        );
+                    } catch (e) {
+                        console.error(`Failed to save document ${docId} to DB:`, e);
+                    }
+                }
+                currentSyncStatus.processed++;
+            } catch (docError: unknown) {
+                const message = docError instanceof Error ? docError.message : String(docError);
+                if (message.includes("Sync stopped by user")) throw docError;
+                console.error(`Failed to process document ${item.doc.title} (${item.doc.slug}):`, docError);
+            }
+        });
+
+        // Update Vector Store per batch immediately
+        if (nsDocsForVectorStore.length > 0) {
+            currentSyncStatus.message = `正在更新向量索引 (批次 ${Math.floor(i / batchSize) + 1}/${nsTotalBatches})...`;
+            console.log(`Updating vector store with ${nsDocsForVectorStore.length} docs (Batch ${Math.floor(i / batchSize) + 1})...`);
+            
+            try {
+                const chunks = await splitter.splitDocuments(nsDocsForVectorStore);
+                
+                let vectorStore: HNSWLib | null = null;
+                if (fs.existsSync(path.join(VECTOR_STORE_PATH, "hnswlib.index"))) {
+                    try {
+                        const loadedStore = await HNSWLib.load(VECTOR_STORE_PATH, embeddings);
+                        await loadedStore.addDocuments(chunks);
+                        vectorStore = loadedStore;
+                    } catch (err) {
+                        console.error("Failed to load vector store, creating new one:", err);
+                    }
+                } 
+                
+                if (!vectorStore) {
+                    vectorStore = await HNSWLib.fromDocuments(chunks, embeddings);
+                }
+                await vectorStore.save(VECTOR_STORE_PATH);
+            } catch (e) {
+                console.error("Failed to update vector store for batch:", e);
+                // Continue despite vector store error to ensure at least DB is updated?
+                // Or stop? Probably continue, but log error.
+            }
+        }
+
+        {
+            const hits = consumeRateLimitHits();
+            if (hits > 0) {
+                currentConcurrency = Math.max(1, Math.ceil(currentConcurrency / 2));
+            } else if (currentConcurrency < maxConcurrency) {
+                currentConcurrency = currentConcurrency + 1;
+            }
+        }
+    }
+    
+    // Final cleanup not needed as we processed in loop
+}

src/middleware.ts

@@ -0,0 +1,47 @@
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+
+export function middleware(request: NextRequest) {
+  const token = request.cookies.get('auth_token')?.value
+  const { pathname } = request.nextUrl
+
+  // Allow access to login page
+  if (pathname === '/login') {
+    // If already authenticated, redirect to home
+    if (token) {
+      return NextResponse.redirect(new URL('/', request.url))
+    }
+    return NextResponse.next()
+  }
+
+  // Allow access to public assets and API for now (unless strictly required to protect)
+  // We strictly protect pages.
+  if (
+    pathname.startsWith('/_next') || 
+    pathname.startsWith('/static') || 
+    pathname.includes('.') // file extensions like .svg, .ico
+  ) {
+    return NextResponse.next()
+  }
+
+  // If not authenticated, redirect to login
+  if (!token) {
+    const url = new URL('/login', request.url)
+    return NextResponse.redirect(url)
+  }
+
+  return NextResponse.next()
+}
+
+export const config = {
+  matcher: [
+    /*
+     * Match all request paths except for the ones starting with:
+     * - api (API routes)
+     * - _next/static (static files)
+     * - _next/image (image optimization files)
+     * - favicon.ico (favicon file)
+     */
+    '/((?!api|_next/static|_next/image|favicon.ico).*)',
+  ],
+}

test-db-logic.js

@@ -0,0 +1,26 @@
+
+const { spawn } = require('child_process');
+const http = require('http');
+
+// Helper to fetch URL
+function fetchUrl(url) {
+  return new Promise((resolve, reject) => {
+    http.get(url, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => resolve(JSON.parse(data)));
+      res.on('error', reject);
+    });
+  });
+}
+
+// We cannot easily start the Next.js server from here as it takes time and resources.
+// Instead, I will assume the server is running or I can run a standalone node script that imports the logic?
+// No, importing Next.js app logic in a standalone script is hard.
+
+// Since I cannot run the server, I will simulate the DB logic directly using better-sqlite3.
+// I need to know where the DB is.
+// Usually in `prisma` or `data.db`.
+// Let's check `src/lib/db.ts`.
+
+console.log("Checking DB logic...");

test_spam_filter.js

@@ -0,0 +1,51 @@
+
+const db = require('better-sqlite3')('rag-kb.db');
+
+const startTime = new Date('2025-01-01').getTime();
+const endTime = new Date('2026-01-01').getTime();
+
+// 1. Get raw count
+const rawStats = db.prepare(`
+    SELECT COUNT(*) as count, SUM(word_count) as words
+    FROM documents
+    WHERE 
+        yuque_id != 0 
+        AND namespace != 'NOTES' 
+        AND (slug IS NULL OR slug NOT LIKE 'dir-%')
+        AND created_at >= ?
+        AND created_at < ?
+`).get(startTime, endTime);
+
+console.log("Raw Stats:");
+console.log(`  Count: ${rawStats.count}`);
+console.log(`  Words: ${(rawStats.words / 10000).toFixed(1)}w`);
+
+// 2. Get filtered count (Anti-Migration Logic)
+// Exclude docs created on days where that Namespace had > 15 creations
+const threshold = 5;
+
+const filteredQuery = `
+    SELECT COUNT(*) as count, SUM(word_count) as words
+    FROM documents d
+    WHERE 
+        d.yuque_id != 0 
+        AND d.namespace != 'NOTES' 
+        AND (d.slug IS NULL OR d.slug NOT LIKE 'dir-%')
+        AND d.created_at >= ?
+        AND d.created_at < ?
+        AND NOT EXISTS (
+            SELECT 1
+            FROM documents d2
+            WHERE 
+                d2.namespace = d.namespace
+                AND date(d2.created_at / 1000, 'unixepoch', 'localtime') = date(d.created_at / 1000, 'unixepoch', 'localtime')
+            GROUP BY date(d2.created_at / 1000, 'unixepoch', 'localtime')
+            HAVING COUNT(*) > ?
+        )
+`;
+
+const filteredStats = db.prepare(filteredQuery).get(startTime, endTime, threshold);
+
+console.log(`\nFiltered Stats (Threshold ${threshold}):`);
+console.log(`  Count: ${filteredStats.count}`);
+console.log(`  Words: ${(filteredStats.words / 10000).toFixed(1)}w`);

upload_status.json

@@ -0,0 +1,7 @@
+{
+  "status": "pending_upload",
+  "last_attempt": "2026-01-09T04:46:36Z",
+  "retry_count": 3,
+  "error_log": "deploy.log",
+  "reason": "Network connection refused after multiple retries"
+}

verify_backup_logic.js

@@ -0,0 +1,36 @@
+import fs from 'fs';
+import path from 'path';
+
+const cwd = process.cwd();
+const dbFiles = ['rag-kb.db', 'yuque-rag.db', 'documents.db', 'yuque_rag.db', 'yuque_db.sqlite'];
+
+console.log('Checking for database files in:', cwd);
+
+let found = false;
+for (const dbFile of dbFiles) {
+  const sourcePath = path.join(cwd, dbFile);
+  if (fs.existsSync(sourcePath)) {
+    console.log(`Found: ${dbFile}`);
+    found = true;
+    
+    // Simulate backup
+    const backupName = `test_backup_${path.parse(dbFile).name}.db`;
+    const destPath = path.join(cwd, backupName);
+    console.log(`Copying to ${backupName}...`);
+    try {
+        fs.copyFileSync(sourcePath, destPath);
+        console.log('Success!');
+        // Clean up
+        fs.unlinkSync(destPath);
+        console.log('Cleaned up test backup.');
+    } catch (e) {
+        console.error('Copy failed:', e);
+    }
+  } else {
+      console.log(`Not found: ${dbFile}`);
+  }
+}
+
+if (!found) {
+    console.log('No database files found!');
+}

verify_stats_api.mjs

@@ -0,0 +1,71 @@
+
+import http from 'http';
+
+function fetchStats(year) {
+  return new Promise((resolve, reject) => {
+    const options = {
+      hostname: 'localhost',
+      port: 3000,
+      path: `/api/stats?year=${year}&t=${Date.now()}`,
+      method: 'GET',
+      headers: {
+        'Pragma': 'no-cache',
+        'Cache-Control': 'no-cache'
+      }
+    };
+
+    const req = http.request(options, (res) => {
+      let data = '';
+      res.on('data', (chunk) => {
+        data += chunk;
+      });
+      res.on('end', () => {
+        try {
+            if (res.statusCode !== 200) {
+                reject(new Error(`Status Code: ${res.statusCode}`));
+                return;
+            }
+            const json = JSON.parse(data);
+            resolve(json);
+        } catch (e) {
+            reject(e);
+        }
+      });
+    });
+
+    req.on('error', (e) => {
+      reject(e);
+    });
+
+    req.end();
+  });
+}
+
+async function run() {
+    try {
+        console.log('Fetching 2025...');
+        const data2025 = await fetchStats('2025');
+        console.log('2025 Total Words:', data2025.stats.totalWords);
+        console.log('2025 Docs Count:', data2025.stats.totalDocs);
+
+        console.log('\nFetching 2024...');
+        const data2024 = await fetchStats('2024');
+        console.log('2024 Total Words:', data2024.stats.totalWords);
+        console.log('2024 Docs Count:', data2024.stats.totalDocs);
+
+        console.log('\nFetching All...');
+        const dataAll = await fetchStats('all');
+        console.log('All Total Words:', dataAll.stats.totalWords);
+        
+        if (data2025.stats.totalWords === data2024.stats.totalWords) {
+            console.error('\nERROR: Total Words are identical for 2025 and 2024!');
+        } else {
+            console.log('\nSUCCESS: Total Words are different.');
+        }
+
+    } catch (err) {
+        console.error('Test failed:', err);
+    }
+}
+
+run();

备注.md

@@ -0,0 +1,4 @@
+大文件上传，超 10m 单独上传：
+huggingface-cli upload duqing2026/rag-kb-demo ./你的文件名.db ./你的文件名.db --repo-type 
+export HF_ENDPOINT="https://hf-mirror.com"
+huggingface-cli upload duqing2026/rag-kb-demo /Users/by/code/rag-kb-system/rag-kb.db