Add FastAPI backend with agent system

2026-03-21 10:13:29 +08:00
parent ed6bab59fe
commit 6ffa07adde
82 changed files with 11138 additions and 0 deletions
--- a/backend/app/routers/init.py
+++ b/backend/app/routers/init.py
@@ -0,0 +1,10 @@
+from app.routers.auth import router as auth_router
+from app.routers.conversation import router as conversation_router
+from app.routers.document import router as document_router
+from app.routers.task import router as task_router
+from app.routers.forum import router as forum_router
+from app.routers.graph import router as graph_router
+from app.routers.agent import router as agent_router
+from app.routers.todo import router as todo_router
+from app.routers.settings import router as settings_router
+from app.routers.folder import router as folder_router
--- a/backend/app/routers/agent.py
+++ b/backend/app/routers/agent.py
@@ -0,0 +1,240 @@
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select
+from app.database import get_db
+from app.models.agent import Agent
+from app.models.user import User
+from app.routers.auth import get_current_user
+from app.schemas.agent import AgentCreate, AgentOut, AgentStats, AgentConfigUpdate, AgentConfigOut
+
+router = APIRouter(prefix="/api/agents", tags=["Agent"])
+
+# 运行时调用统计（内存中，非持久化）
+_agent_call_counts: dict[str, int] = {}
+_agent_current_tasks: dict[str, str | None] = {}
+_agent_statuses: dict[str, str] = {}
+
+# 默认 Agent 角色列表
+DEFAULT_AGENT_ROLES = ["master", "planner", "executor", "librarian", "analyst"]
+
+
+def record_agent_call(agent_id: str):
+    _agent_call_counts[agent_id] = _agent_call_counts.get(agent_id, 0) + 1
+
+
+def set_agent_task(agent_id: str, task: str | None):
+    _agent_current_tasks[agent_id] = task
+    _agent_statuses[agent_id] = "active" if task else "idle"
+
+
+def set_agent_status(agent_id: str, status: str):
+    _agent_statuses[agent_id] = status
+
+
+@router.get("", response_model=list[AgentOut])
+async def list_agents(
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    result = await db.execute(
+        select(Agent).where(Agent.is_active == True).order_by(Agent.role)
+    )
+    return result.scalars().all()
+
+
+# ———— 运行时统计（必须在 /{agent_id} 之前）————
+@router.get("/stats", response_model=list[AgentStats])
+async def get_agent_stats(
+    current_user: User = Depends(get_current_user),
+):
+    """
+    获取各 Agent 的运行时统计（调用次数、当前任务、状态）
+    """
+    stats = []
+    for role in DEFAULT_AGENT_ROLES:
+        stats.append(AgentStats(
+            agent_id=role,
+            call_count=_agent_call_counts.get(role, 0),
+            current_task=_agent_current_tasks.get(role),
+            status=_agent_statuses.get(role, "idle"),
+        ))
+    return stats
+
+
+# ———— 配置管理（必须在 /{agent_id} 之前）————
+@router.get("/config/{agent_id}", response_model=AgentConfigOut)
+async def get_agent_config(
+    agent_id: str,
+    db: AsyncSession = Depends(get_db),
+):
+    """获取单个 Agent 完整配置"""
+    result = await db.execute(select(Agent).where(Agent.role == agent_id))
+    agent = result.scalar_one_or_none()
+
+    if not agent:
+        from app.agents.prompts import MASTER_SYSTEM_PROMPT, PLANNER_SYSTEM_PROMPT, EXECUTOR_SYSTEM_PROMPT, LIBRARIAN_SYSTEM_PROMPT, ANALYST_SYSTEM_PROMPT
+        defaults = {
+            "master": ("JARVIS", "主控制核心", MASTER_SYSTEM_PROMPT),
+            "planner": ("PLANNER", "规划专家", PLANNER_SYSTEM_PROMPT),
+            "executor": ("EXECUTOR", "执行专家", EXECUTOR_SYSTEM_PROMPT),
+            "librarian": ("LIBRARIAN", "知识管理员", LIBRARIAN_SYSTEM_PROMPT),
+            "analyst": ("ANALYST", "数据分析师", ANALYST_SYSTEM_PROMPT),
+        }
+        if agent_id not in defaults:
+            raise HTTPException(status_code=404, detail="Agent 不存在")
+        name, desc, prompt = defaults[agent_id]
+        return AgentConfigOut(
+            id=agent_id, name=name, role=agent_id,
+            description=desc, system_prompt=prompt, enabled=True, is_active=True,
+        )
+    return AgentConfigOut(
+        id=agent.role,
+        name=agent.name,
+        role=agent.role,
+        description=agent.description,
+        system_prompt=agent.system_prompt,
+        enabled=agent.is_active,
+        is_active=agent.is_active,
+    )
+
+
+@router.put("/config/{agent_id}", response_model=AgentConfigOut)
+async def update_agent_config(
+    agent_id: str,
+    data: AgentConfigUpdate,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """更新 Agent 配置（名称、描述、提示词、启用状态）"""
+    result = await db.execute(select(Agent).where(Agent.role == agent_id))
+    agent = result.scalar_one_or_none()
+
+    if not agent:
+        raise HTTPException(status_code=404, detail="Agent 不存在")
+
+    if data.name is not None:
+        agent.name = data.name
+    if data.description is not None:
+        agent.description = data.description
+    if data.system_prompt is not None:
+        agent.system_prompt = data.system_prompt
+    if data.enabled is not None:
+        agent.is_active = data.enabled
+        _agent_statuses[agent_id] = "disabled" if not data.enabled else "idle"
+
+    await db.commit()
+    await db.refresh(agent)
+    return AgentConfigOut(
+        id=agent.role,
+        name=agent.name,
+        role=agent.role,
+        description=agent.description,
+        system_prompt=agent.system_prompt,
+        enabled=agent.is_active,
+        is_active=agent.is_active,
+    )
+
+
+@router.post("", response_model=AgentOut, status_code=201)
+async def create_agent(
+    data: AgentCreate,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    agent = Agent(
+        name=data.name,
+        role=data.role,
+        description=data.description,
+        system_prompt=data.system_prompt,
+    )
+    db.add(agent)
+    await db.commit()
+    await db.refresh(agent)
+    return agent
+
+
+@router.get("/{agent_id}", response_model=AgentOut)
+async def get_agent(
+    agent_id: str,
+    db: AsyncSession = Depends(get_db),
+):
+    result = await db.execute(select(Agent).where(Agent.id == agent_id))
+    agent = result.scalar_one_or_none()
+    if not agent:
+        raise HTTPException(status_code=404, detail="Agent 不存在")
+    return agent
+
+
+
+# ———— 配置管理 ————
+@router.get("/config/{agent_id}", response_model=AgentConfigOut)
+async def get_agent_config(
+    agent_id: str,
+    db: AsyncSession = Depends(get_db),
+):
+    """获取单个 Agent 完整配置"""
+    result = await db.execute(select(Agent).where(Agent.role == agent_id))
+    agent = result.scalar_one_or_none()
+    if not agent:
+        # 如果数据库中没有，返回默认配置
+        from app.agents.prompts import MASTER_SYSTEM_PROMPT, PLANNER_SYSTEM_PROMPT, EXECUTOR_SYSTEM_PROMPT, LIBRARIAN_SYSTEM_PROMPT, ANALYST_SYSTEM_PROMPT
+        defaults = {
+            "master": ("JARVIS", "主控制核心", MASTER_SYSTEM_PROMPT),
+            "planner": ("PLANNER", "规划专家", PLANNER_SYSTEM_PROMPT),
+            "executor": ("EXECUTOR", "执行专家", EXECUTOR_SYSTEM_PROMPT),
+            "librarian": ("LIBRARIAN", "知识管理员", LIBRARIAN_SYSTEM_PROMPT),
+            "analyst": ("ANALYST", "数据分析师", ANALYST_SYSTEM_PROMPT),
+        }
+        if agent_id not in defaults:
+            raise HTTPException(status_code=404, detail="Agent 不存在")
+        name, desc, prompt = defaults[agent_id]
+        return AgentConfigOut(
+            id=agent_id, name=name, role=agent_id,
+            description=desc, system_prompt=prompt, enabled=True, is_active=True,
+        )
+    return AgentConfigOut(
+        id=agent.role,
+        name=agent.name,
+        role=agent.role,
+        description=agent.description,
+        system_prompt=agent.system_prompt,
+        enabled=agent.is_active,
+        is_active=agent.is_active,
+    )
+
+
+@router.put("/config/{agent_id}", response_model=AgentConfigOut)
+async def update_agent_config(
+    agent_id: str,
+    data: AgentConfigUpdate,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """更新 Agent 配置（名称、描述、提示词、启用状态）"""
+    result = await db.execute(select(Agent).where(Agent.role == agent_id))
+    agent = result.scalar_one_or_none()
+
+    if not agent:
+        raise HTTPException(status_code=404, detail="Agent 不存在")
+
+    if data.name is not None:
+        agent.name = data.name
+    if data.description is not None:
+        agent.description = data.description
+    if data.system_prompt is not None:
+        agent.system_prompt = data.system_prompt
+    if data.enabled is not None:
+        agent.is_active = data.enabled
+        _agent_statuses[agent_id] = "disabled" if not data.enabled else "idle"
+
+    await db.commit()
+    await db.refresh(agent)
+    return AgentConfigOut(
+        id=agent.role,
+        name=agent.name,
+        role=agent.role,
+        description=agent.description,
+        system_prompt=agent.system_prompt,
+        enabled=agent.is_active,
+        is_active=agent.is_active,
+    )
--- a/backend/app/routers/auth.py
+++ b/backend/app/routers/auth.py
@@ -0,0 +1,83 @@
+from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select
+from app.database import get_db
+from app.models.user import User
+from app.schemas.auth import UserCreate, UserOut, Token
+from app.services.auth_service import verify_password, get_password_hash, create_access_token, decode_token
+from app.config import settings
+
+router = APIRouter(prefix="/api/auth", tags=["认证"])
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/auth/login")
+
+
+async def get_current_user(
+    token: str = Depends(oauth2_scheme),
+    db: AsyncSession = Depends(get_db),
+) -> User:
+    payload = decode_token(token)
+    if payload is None:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="无效的认证令牌")
+    user_id = payload.get("sub")
+    if user_id is None:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="无效的认证令牌")
+    result = await db.execute(select(User).where(User.id == user_id))
+    user = result.scalar_one_or_none()
+    if user is None or not user.is_active:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="用户不存在或已禁用")
+    return user
+
+
+@router.post("/register", response_model=UserOut, status_code=status.HTTP_201_CREATED)
+async def register(user_data: UserCreate, db: AsyncSession = Depends(get_db)):
+    # 检查邮箱是否已存在
+    result = await db.execute(select(User).where(User.email == user_data.email))
+    if result.scalar_one_or_none():
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="邮箱已被注册")
+    # 创建用户
+    user = User(
+        email=user_data.email,
+        hashed_password=get_password_hash(user_data.password),
+        full_name=user_data.full_name,
+    )
+    db.add(user)
+    await db.commit()
+    await db.refresh(user)
+    return user
+
+
+@router.post("/login", response_model=Token)
+async def login(form_data: OAuth2PasswordRequestForm = Depends(), db: AsyncSession = Depends(get_db)):
+    identifier = form_data.username.strip()
+    # 支持：邮箱 / UUID / 用户名前缀
+    user = None
+
+    # 1. 尝试 UUID
+    import re
+    if re.match(r'^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$', identifier, re.I):
+        result = await db.execute(select(User).where(User.id == identifier))
+        user = result.scalar_one_or_none()
+
+    # 2. 尝试邮箱
+    if not user:
+        result = await db.execute(select(User).where(User.email == identifier))
+        user = result.scalar_one_or_none()
+
+    # 3. 尝试用户名前缀（email@ 前面的部分）
+    if not user and '@' not in identifier:
+        result = await db.execute(select(User).where(User.email.like(f"{identifier}@%")))
+        user = result.scalar_one_or_none()
+
+    if not user or not verify_password(form_data.password, user.hashed_password):
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="用户名、邮箱或密码错误")
+    if not user.is_active:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="用户已被禁用")
+    access_token = create_access_token(data={"sub": user.id})
+    return Token(access_token=access_token)
+
+
+@router.get("/me", response_model=UserOut)
+async def get_me(current_user: User = Depends(get_current_user)):
+    return current_user
--- a/backend/app/routers/conversation.py
+++ b/backend/app/routers/conversation.py
@@ -0,0 +1,217 @@
+from fastapi import APIRouter, Depends, HTTPException, WebSocket, WebSocketDisconnect
+from fastapi.responses import StreamingResponse
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, desc
+from app.database import get_db
+from app.models.conversation import Conversation, Message
+from app.models.user import User
+from app.routers.auth import get_current_user
+from app.schemas.conversation import ConversationCreate, ConversationOut, ChatRequest, ChatResponse
+from app.services.agent_service import AgentService
+import json
+
+router = APIRouter(prefix="/api/conversations", tags=["对话"])
+
+
+@router.get("", response_model=list[ConversationOut])
+async def list_conversations(
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    result = await db.execute(
+        select(Conversation)
+        .where(Conversation.user_id == current_user.id)
+        .order_by(desc(Conversation.updated_at))
+        .limit(50)
+    )
+    return result.scalars().all()
+
+
+@router.post("", response_model=ConversationOut, status_code=201)
+async def create_conversation(
+    data: ConversationCreate,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    conv = Conversation(user_id=current_user.id, title=data.title or "新对话")
+    db.add(conv)
+    await db.commit()
+    await db.refresh(conv)
+    return conv
+
+
+@router.get("/{conversation_id}/messages")
+async def get_conversation_messages(
+    conversation_id: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """获取对话的所有消息"""
+    result = await db.execute(
+        select(Conversation).where(
+            Conversation.id == conversation_id,
+            Conversation.user_id == current_user.id,
+        )
+    )
+    conv = result.scalar_one_or_none()
+    if not conv:
+        raise HTTPException(status_code=404, detail="对话不存在")
+
+    msgs = await db.execute(
+        select(Message)
+        .where(Message.conversation_id == conversation_id)
+        .order_by(Message.created_at)
+    )
+    return msgs.scalars().all()
+
+
+@router.delete("/{conversation_id}", status_code=204)
+async def delete_conversation(
+    conversation_id: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    result = await db.execute(
+        select(Conversation).where(
+            Conversation.id == conversation_id,
+            Conversation.user_id == current_user.id,
+        )
+    )
+    conv = result.scalar_one_or_none()
+    if not conv:
+        raise HTTPException(status_code=404, detail="对话不存在")
+    await db.delete(conv)
+    await db.commit()
+
+
+@router.post("/chat", response_model=ChatResponse)
+async def chat(
+    data: ChatRequest,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """简单版对话（非流式）"""
+    agent_svc = AgentService(db)
+    conv_id, msg_id, content = await agent_svc.chat_simple(
+        user_id=current_user.id,
+        message=data.message,
+        conversation_id=data.conversation_id,
+        file_ids=data.file_ids,
+    )
+
+    # 更新对话消息计数
+    result = await db.execute(select(Conversation).where(Conversation.id == conv_id))
+    conv = result.scalar_one_or_none()
+    if conv:
+        conv.message_count += 2
+        await db.commit()
+
+    return ChatResponse(
+        conversation_id=conv_id,
+        message_id=msg_id,
+        content=content,
+        agent_name="jarvis",
+    )
+
+
+@router.post("/chat/stream")
+async def chat_stream(
+    data: ChatRequest,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """流式对话"""
+    agent_svc = AgentService(db)
+
+    async def stream_generator():
+        conv_id, msg_id, stream = await agent_svc.chat(
+            user_id=current_user.id,
+            message=data.message,
+            conversation_id=data.conversation_id,
+        )
+
+        # 先发送元数据
+        yield f"event: metadata\ndata: {json.dumps({'conversation_id': conv_id, 'message_id': msg_id})}\n\n"
+
+        # 流式发送内容
+        collected = ""
+        try:
+            async for chunk in stream:
+                if chunk:
+                    collected += chunk
+                    yield f"event: chunk\ndata: {json.dumps({'content': chunk})}\n\n"
+
+            # 更新数据库中的消息
+            await agent_svc.save_response(msg_id, collected)
+
+        except Exception as e:
+            yield f"event: error\ndata: {json.dumps({'error': str(e)})}\n\n"
+        finally:
+            yield f"event: done\ndata: {json.dumps({'message_id': msg_id})}\n\n"
+
+    return StreamingResponse(
+        stream_generator(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+        },
+    )
+
+
+@router.websocket("/ws/{user_id}/{conversation_id}")
+async def websocket_chat(
+    websocket: WebSocket,
+    user_id: str,
+    conversation_id: str,
+):
+    """WebSocket 流式对话"""
+    await websocket.accept()
+    agent_svc = None
+
+    try:
+        async for message in websocket.iter_text():
+            data = json.loads(message)
+            user_message = data.get("message", "")
+
+            # 每个连接创建新的数据库会话
+            from app.database import async_session
+            async with async_session() as db:
+                agent_svc = AgentService(db)
+
+                if conversation_id == "new":
+                    # 新对话
+                    conv_id, msg_id, stream = await agent_svc.chat(
+                        user_id=user_id,
+                        message=user_message,
+                        conversation_id=None,
+                    )
+                    await websocket.send_json({
+                        "type": "metadata",
+                        "conversation_id": conv_id,
+                        "message_id": msg_id,
+                    })
+                else:
+                    conv_id, msg_id, stream = await agent_svc.chat(
+                        user_id=user_id,
+                        message=user_message,
+                        conversation_id=conversation_id,
+                    )
+
+                collected = ""
+                async for chunk in stream:
+                    if chunk:
+                        collected += chunk
+                        await websocket.send_json({"type": "chunk", "content": chunk})
+
+                await agent_svc.save_response(msg_id, collected)
+                await websocket.send_json({"type": "done", "message_id": msg_id})
+
+    except WebSocketDisconnect:
+        pass
+    except Exception as e:
+        try:
+            await websocket.send_json({"type": "error", "error": str(e)})
+        except Exception:
+            pass
--- a/backend/app/routers/document.py
+++ b/backend/app/routers/document.py
@@ -0,0 +1,154 @@
+from fastapi import APIRouter, Depends, HTTPException, UploadFile, File, BackgroundTasks, Form
+from typing import Optional
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select
+from app.database import get_db
+from app.models.document import Document, DocumentChunk
+from app.models.user import User
+from app.routers.auth import get_current_user
+from app.services.document_service import DocumentService
+from app.services.knowledge_service import KnowledgeService
+from dataclasses import asdict
+
+router = APIRouter(prefix="/api/documents", tags=["知识库"])
+
+
+@router.get("", response_model=list)
+async def list_documents(
+    folder_id: Optional[str] = None,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    query = select(Document).where(Document.user_id == current_user.id)
+    if folder_id:
+        query = query.where(Document.folder_id == folder_id)
+    result = await db.execute(query.order_by(Document.created_at.desc()))
+    return result.scalars().all()
+
+
+@router.post("/upload", status_code=201)
+async def upload_document(
+    background: BackgroundTasks,
+    file: UploadFile = File(...),
+    folder_id: Optional[str] = Form(None),
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """上传文档，自动分块并向量化"""
+    doc_svc = DocumentService(db)
+    doc = await doc_svc.upload_document(current_user.id, file, folder_id=folder_id)
+
+    # 后台索引到 ChromaDB
+    def index_task():
+        import asyncio
+        from app.database import async_session
+        from app.services.knowledge_service import KnowledgeService
+
+        async def _index():
+            async with async_session() as session:
+                kb_svc = KnowledgeService(session, user_id=current_user.id)
+                await kb_svc.index_document(doc.id, user_id=current_user.id)
+
+        asyncio.run(_index())
+
+    background.add_task(index_task)
+    return {"id": doc.id, "title": doc.title, "chunk_count": doc.chunk_count, "status": "上传成功，正在索引..."}
+
+
+@router.get("/{document_id}")
+async def get_document(
+    document_id: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    result = await db.execute(
+        select(Document).where(
+            Document.id == document_id,
+            Document.user_id == current_user.id,
+        )
+    )
+    doc = result.scalar_one_or_none()
+    if not doc:
+        raise HTTPException(status_code=404, detail="文档不存在")
+    return doc
+
+
+@router.get("/{document_id}/chunks")
+async def get_document_chunks(
+    document_id: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """获取文档的所有 chunks"""
+    result = await db.execute(
+        select(Document).where(
+            Document.id == document_id,
+            Document.user_id == current_user.id,
+        )
+    )
+    doc = result.scalar_one_or_none()
+    if not doc:
+        raise HTTPException(status_code=404, detail="文档不存在")
+
+    chunks_result = await db.execute(
+        select(DocumentChunk)
+        .where(DocumentChunk.document_id == document_id)
+        .order_by(DocumentChunk.chunk_index)
+    )
+    return chunks_result.scalars().all()
+
+
+@router.delete("/{document_id}", status_code=204)
+async def delete_document(
+    document_id: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """删除文档"""
+    doc_svc = DocumentService(db)
+    await doc_svc.delete_document(current_user.id, document_id)
+
+
+@router.post("/search")
+async def search_documents(
+    query: str,
+    top_k: int = 5,
+    mode: str = "hybrid",
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """
+    搜索知识库
+
+    - query: 搜索查询
+    - top_k: 返回数量，默认5
+    - mode: hybrid（混合）/ semantic（语义）/ keyword（关键词）
+    """
+    kb_svc = KnowledgeService(db, user_id=current_user.id)
+
+    if mode == "keyword":
+        results = await kb_svc._keyword_search(query, current_user.id, top_k)
+    elif mode == "semantic":
+        results = await kb_svc.retrieve(query, current_user.id, top_k, use_rerank=True)
+    else:
+        results = await kb_svc.hybrid_search(query, current_user.id, top_k)
+
+    return [asdict(r) for r in results]
+
+
+@router.get("/{document_id}/content")
+async def get_document_content(
+    document_id: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """获取文档的文本内容（用于AI理解）"""
+    from app.services.document_service import DocumentService
+
+    doc_svc = DocumentService(db)
+    content = await doc_svc.get_document_content(current_user.id, document_id)
+
+    if content is None:
+        raise HTTPException(status_code=404, detail="文档不存在或无内容")
+
+    return {"content": content}
--- a/backend/app/routers/folder.py
+++ b/backend/app/routers/folder.py
@@ -0,0 +1,143 @@
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, and_
+from typing import List
+from app.database import get_db
+from app.models.folder import Folder
+from app.models.user import User
+from app.schemas.folder import FolderCreate, FolderUpdate, FolderOut, FolderTreeOut
+from app.services.auth_service import get_current_user
+
+router = APIRouter(prefix="/api/folders", tags=["文件夹"])
+
+def build_folder_tree(folders: list[Folder], parent_id: str = None) -> List[FolderTreeOut]:
+    """递归构建文件夹树"""
+    tree = []
+    for folder in folders:
+        if folder.parent_id == parent_id:
+            children = build_folder_tree(folders, folder.id)
+            tree.append(FolderTreeOut(
+                id=folder.id,
+                name=folder.name,
+                parent_id=folder.parent_id,
+                children=children
+            ))
+    return tree
+
+@router.get("", response_model=List[FolderTreeOut])
+async def get_folders(
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    """获取用户的完整文件夹树"""
+    result = await db.execute(
+        select(Folder).where(Folder.user_id == current_user.id)
+    )
+    folders = result.scalars().all()
+    return build_folder_tree(list(folders))
+
+@router.post("", response_model=FolderOut, status_code=status.HTTP_201_CREATED)
+async def create_folder(
+    folder_data: FolderCreate,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    """创建文件夹"""
+    # 验证父文件夹存在且属于当前用户
+    if folder_data.parent_id:
+        result = await db.execute(
+            select(Folder).where(
+                and_(Folder.id == folder_data.parent_id, Folder.user_id == current_user.id)
+            )
+        )
+        if not result.scalar_one_or_none():
+            raise HTTPException(status_code=404, detail="父文件夹不存在")
+
+    # 检查同名文件夹
+    result = await db.execute(
+        select(Folder).where(
+            and_(
+                Folder.user_id == current_user.id,
+                Folder.parent_id == folder_data.parent_id,
+                Folder.name == folder_data.name
+            )
+        )
+    )
+    if result.scalar_one_or_none():
+        raise HTTPException(status_code=400, detail="同名文件夹已存在")
+
+    folder = Folder(
+        user_id=current_user.id,
+        name=folder_data.name,
+        parent_id=folder_data.parent_id
+    )
+    db.add(folder)
+    await db.commit()
+    await db.refresh(folder)
+    return folder
+
+@router.put("/{folder_id}", response_model=FolderOut)
+async def rename_folder(
+    folder_id: str,
+    folder_data: FolderUpdate,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    """重命名文件夹"""
+    result = await db.execute(
+        select(Folder).where(
+            and_(Folder.id == folder_id, Folder.user_id == current_user.id)
+        )
+    )
+    folder = result.scalar_one_or_none()
+    if not folder:
+        raise HTTPException(status_code=404, detail="文件夹不存在")
+
+    folder.name = folder_data.name
+    await db.commit()
+    await db.refresh(folder)
+    return folder
+
+@router.delete("/{folder_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_folder(
+    folder_id: str,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    """删除文件夹（级联删除文档）"""
+    from app.models.document import Document
+    from app.services.knowledge_service import KnowledgeService
+
+    result = await db.execute(
+        select(Folder).where(
+            and_(Folder.id == folder_id, Folder.user_id == current_user.id)
+        )
+    )
+    folder = result.scalar_one_or_none()
+    if not folder:
+        raise HTTPException(status_code=404, detail="文件夹不存在")
+
+    async def delete_recursive(fid: str):
+        # 删除子文件夹（先递归）
+        children = await db.execute(
+            select(Folder).where(Folder.parent_id == fid)
+        )
+        for child in children.scalars():
+            await delete_recursive(child.id)
+
+        # 删除文档
+        docs = await db.execute(
+            select(Document).where(Document.folder_id == fid)
+        )
+        for doc in docs.scalars():
+            knowledge_service = KnowledgeService(db, current_user.id)
+            await knowledge_service.delete_from_vectorstore(current_user.id, doc.id)
+            await db.delete(doc)
+
+        # 删除文件夹本身
+        folder_to_delete = await db.get(Folder, fid)
+        if folder_to_delete:
+            await db.delete(folder_to_delete)
+
+    await delete_recursive(folder_id)
+    await db.commit()
--- a/backend/app/routers/forum.py
+++ b/backend/app/routers/forum.py
@@ -0,0 +1,111 @@
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, desc
+from app.database import get_db
+from app.models.forum import ForumPost, ForumReply
+from app.models.user import User
+from app.routers.auth import get_current_user
+from app.schemas.forum import ForumPostCreate, ForumPostOut, ForumReplyCreate, ForumReplyOut
+
+router = APIRouter(prefix="/api/forum", tags=["论坛"])
+
+
+@router.get("/posts", response_model=list[ForumPostOut])
+async def list_posts(
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    result = await db.execute(
+        select(ForumPost)
+        .where(ForumPost.user_id == current_user.id)
+        .order_by(desc(ForumPost.created_at))
+    )
+    return result.scalars().all()
+
+
+@router.post("/posts", response_model=ForumPostOut, status_code=201)
+async def create_post(
+    data: ForumPostCreate,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    post = ForumPost(
+        user_id=current_user.id,
+        title=data.title,
+        content=data.content,
+        category=data.category,
+    )
+    db.add(post)
+    await db.commit()
+    await db.refresh(post)
+    return post
+
+
+@router.get("/posts/{post_id}", response_model=ForumPostOut)
+async def get_post(
+    post_id: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    result = await db.execute(
+        select(ForumPost).where(ForumPost.id == post_id)
+    )
+    post = result.scalar_one_or_none()
+    if not post:
+        raise HTTPException(status_code=404, detail="帖子不存在")
+    return post
+
+
+@router.delete("/posts/{post_id}", status_code=204)
+async def delete_post(
+    post_id: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    result = await db.execute(
+        select(ForumPost).where(
+            ForumPost.id == post_id,
+            ForumPost.user_id == current_user.id,
+        )
+    )
+    post = result.scalar_one_or_none()
+    if not post:
+        raise HTTPException(status_code=404, detail="帖子不存在")
+    await db.delete(post)
+    await db.commit()
+
+
+@router.get("/posts/{post_id}/replies", response_model=list[ForumReplyOut])
+async def list_replies(
+    post_id: str,
+    db: AsyncSession = Depends(get_db),
+):
+    result = await db.execute(
+        select(ForumReply)
+        .where(ForumReply.post_id == post_id)
+        .order_by(ForumReply.created_at)
+    )
+    return result.scalars().all()
+
+
+@router.post("/posts/{post_id}/replies", response_model=ForumReplyOut, status_code=201)
+async def create_reply(
+    post_id: str,
+    data: ForumReplyCreate,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    reply = ForumReply(
+        post_id=post_id,
+        user_id=current_user.id,
+        content=data.content,
+    )
+    db.add(reply)
+    # 更新帖子回复数
+    result = await db.execute(select(ForumPost).where(ForumPost.id == post_id))
+    post = result.scalar_one_or_none()
+    if post:
+        post.reply_count += 1
+    await db.commit()
+    await db.refresh(reply)
+    return reply
--- a/backend/app/routers/graph.py
+++ b/backend/app/routers/graph.py
@@ -0,0 +1,240 @@
+from fastapi import APIRouter, Depends, HTTPException, BackgroundTasks
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, or_
+from app.database import get_db
+from app.models.knowledge_graph import KGNode, KGEdge
+from app.models.user import User
+from app.routers.auth import get_current_user
+from app.services.graph_service import GraphService
+from app.schemas.graph import KGNodeOut, TagProperties, TagExtractRequest, TagExtractResponse, RelatedContentRequest
+
+router = APIRouter(prefix="/api/graph", tags=["知识图谱"])
+
+
+@router.get("")
+async def get_graph(
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """获取用户知识图谱"""
+    nodes_result = await db.execute(
+        select(KGNode)
+        .where(KGNode.user_id == current_user.id)
+        .order_by(KGNode.importance.desc())
+        .limit(200)
+    )
+    nodes = list(nodes_result.scalars().all())
+    node_ids = {n.id for n in nodes}
+
+    edges_result = await db.execute(select(KGEdge))
+    edges = [e for e in edges_result.scalars().all()
+             if e.source_id in node_ids or e.target_id in node_ids]
+
+    return {
+        "nodes": [{"id": n.id, "name": n.name, "type": n.entity_type,
+                   "description": n.description, "importance": n.importance,
+                   "created_at": str(n.created_at)}
+                  for n in nodes],
+        "edges": [{"id": e.id, "source": e.source_id, "target": e.target_id,
+                   "relation": e.relation_type, "weight": e.weight}
+                  for e in edges],
+        "stats": {
+            "node_count": len(nodes),
+            "edge_count": len(edges),
+        }
+    }
+
+
+@router.post("/build")
+async def build_graph(
+    background: BackgroundTasks,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """构建/重建知识图谱（后台异步执行）"""
+
+    def build_task():
+        import asyncio
+        from app.database import async_session
+        from app.services.graph_service import GraphService
+
+        async def _build():
+            async with async_session() as session:
+                svc = GraphService(session)
+                await svc.build_graph(user_id=current_user.id, document_ids=None)
+
+        asyncio.run(_build())
+
+    background.add_task(build_task)
+    return {"status": "started", "message": "图谱构建任务已启动，请稍后刷新查看"}
+
+
+@router.get("/entity/{entity}")
+async def get_entity_context(
+    entity: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """获取某个实体的详细上下文"""
+    svc = GraphService(db)
+    context = await svc.get_entity_context(entity, current_user.id)
+    return {"context": context}
+
+
+@router.get("/summary")
+async def get_graph_summary(
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """获取图谱摘要"""
+    svc = GraphService(db)
+    summary = await svc.get_graph_summary(current_user.id)
+    return {"summary": summary}
+
+
+@router.get("/neighbors/{node_id}")
+async def get_node_neighbors(
+    node_id: str,
+    depth: int = 1,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """获取节点的邻居节点（用于可视化点击展开）"""
+    svc = GraphService(db)
+    data = await svc.get_neighbors(node_id, depth)
+    return {
+        "nodes": [{"id": n.id, "name": n.name, "type": n.entity_type,
+                   "description": n.description} for n in data["nodes"]],
+        "edges": [{"id": e.id, "source": e.source_id, "target": e.target_id,
+                   "relation": e.relation_type} for e in data["edges"]],
+    }
+
+
+@router.delete("/nodes/{node_id}", status_code=204)
+async def delete_node(
+    node_id: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """删除图谱节点"""
+    result = await db.execute(
+        select(KGNode).where(KGNode.id == node_id, KGNode.user_id == current_user.id)
+    )
+    node = result.scalar_one_or_none()
+    if not node:
+        raise HTTPException(status_code=404, detail="节点不存在")
+    await db.delete(node)
+    await db.commit()
+
+
+@router.post("/tags/extract", response_model=TagExtractResponse)
+async def extract_tags(request: TagExtractRequest, db: AsyncSession = Depends(get_db)):
+    """从内容中提取标签（不保存到节点）"""
+    from app.services.tag_service import TagService
+    from app.core.llm import get_llm_client
+
+    llm_client = get_llm_client()
+    tag_service = TagService(db, llm_client)
+
+    tag_infos = tag_service.extract_tags_from_content(request.content, request.user_id)
+    tags = []
+    for t in tag_infos:
+        short_name, level, parent_path = tag_service.parse_tag_path(t["path"])
+        tags.append(TagProperties(
+            tag_path=t["path"],
+            short_name=short_name,
+            level=level,
+            parent_path=parent_path,
+            description=t.get("description")
+        ))
+
+    return TagExtractResponse(tags=tags, tag_count=len(tags))
+
+
+@router.post("/tags/content/{node_id}", response_model=TagExtractResponse)
+async def tag_content_node(
+    node_id: str,
+    request: TagExtractRequest,
+    db: AsyncSession = Depends(get_db)
+):
+    """为内容节点打标签"""
+    from app.services.tag_service import TagService
+    from app.core.llm import get_llm_client
+
+    result = await db.execute(select(KGNode).where(KGNode.id == node_id))
+    node = result.scalar_one_or_none()
+    if not node:
+        raise HTTPException(status_code=404, detail="Node not found")
+
+    llm_client = get_llm_client()
+    tag_service = TagService(db, llm_client)
+
+    tag_nodes = tag_service.tag_content(request.content, request.user_id, node)
+    tags = []
+    for n in tag_nodes:
+        props = n.properties_ or {}
+        tags.append(TagProperties(
+            tag_path=props.get("tag_path", n.name),
+            short_name=n.name,
+            level=props.get("level", 1),
+            parent_path=props.get("parent_path"),
+            description=n.description
+        ))
+
+    return TagExtractResponse(tags=tags, tag_count=len(tags))
+
+
+@router.get("/tags/{tag_id}/related", response_model=list[KGNodeOut])
+async def get_related_tags(tag_id: str, db: AsyncSession = Depends(get_db)):
+    """获取标签的关联标签"""
+    result = await db.execute(
+        select(KGEdge).where(
+            or_(KGEdge.source_id == tag_id, KGEdge.target_id == tag_id),
+            KGEdge.relation_type.in_(["related_to", "synonym_of"])
+        )
+    )
+    edges = list(result.scalars().all())
+
+    related_ids = set()
+    for e in edges:
+        if e.source_id == tag_id:
+            related_ids.add(e.target_id)
+        else:
+            related_ids.add(e.source_id)
+
+    if not related_ids:
+        return []
+
+    result = await db.execute(select(KGNode).where(KGNode.id.in_(related_ids)))
+    nodes = list(result.scalars().all())
+    return nodes
+
+
+@router.get("/tags/{user_id}", response_model=list[KGNodeOut])
+async def get_user_tags(user_id: str, db: AsyncSession = Depends(get_db)):
+    """获取用户的所有标签"""
+    result = await db.execute(
+        select(KGNode).where(
+            KGNode.user_id == user_id,
+            KGNode.entity_type == "tag"
+        ).order_by(KGNode.properties_["level"].astext)
+    )
+    nodes = list(result.scalars().all())
+    return nodes
+
+
+@router.post("/content/related", response_model=list[KGNodeOut])
+async def get_related_content(
+    request: RelatedContentRequest,
+    db: AsyncSession = Depends(get_db)
+):
+    """通过标签找相关内容"""
+    from app.services.tag_service import TagService
+    from app.core.llm import get_llm_client
+
+    llm_client = get_llm_client()
+    tag_service = TagService(db, llm_client)
+
+    results = tag_service.get_related_content(request.tag_ids, request.user_id, request.limit)
+    nodes = [r[0] for r in results]
+    return nodes
--- a/backend/app/routers/scheduler.py
+++ b/backend/app/routers/scheduler.py
@@ -0,0 +1,42 @@
+from fastapi import APIRouter, Depends
+from app.models.user import User
+from app.routers.auth import get_current_user
+from app.services.scheduler_service import (
+    get_scheduler_status,
+    scheduler,
+    daily_task_analysis,
+    forum_scan_task,
+    graph_rebuild_task,
+    tag_generation_task,
+)
+import logging
+
+router = APIRouter(prefix="/api/scheduler", tags=["定时任务"])
+logger = logging.getLogger(__name__)
+
+
+@router.get("/status")
+async def get_status(current_user: User = Depends(get_current_user)):
+    """获取调度器状态"""
+    return get_scheduler_status()
+
+
+@router.post("/trigger/{job_id}")
+async def trigger_job(job_id: str, current_user: User = Depends(get_current_user)):
+    """手动触发某个定时任务"""
+    job_map = {
+        "daily_task_analysis": daily_task_analysis,
+        "forum_scan": forum_scan_task,
+        "graph_rebuild": graph_rebuild_task,
+        "tag_generation": tag_generation_task,
+    }
+
+    if job_id not in job_map:
+        return {"error": f"未知任务: {job_id}"}
+
+    try:
+        await job_map[job_id]()
+        return {"status": "ok", "job": job_id, "message": "任务已触发执行"}
+    except Exception as e:
+        logger.error(f"手动触发任务失败 {job_id}: {e}")
+        return {"status": "error", "job": job_id, "error": str(e)}
--- a/backend/app/routers/settings.py
+++ b/backend/app/routers/settings.py
@@ -0,0 +1,87 @@
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.database import get_db
+from app.models.user import User
+from app.routers.auth import get_current_user
+from app.schemas.settings import (
+    SettingsOut, ProfileUpdateIn, LLMConfigIn, SchedulerConfigIn, LLMTestIn
+)
+from app.services.settings_service import (
+    get_user_settings, update_user_profile, update_llm_config,
+    update_scheduler_config, test_llm_connection
+)
+
+router = APIRouter(prefix="/api/settings", tags=["设置"])
+
+
+@router.get("", response_model=SettingsOut)
+async def get_settings(
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    settings = await get_user_settings(current_user.id, db)
+    if not settings:
+        raise HTTPException(status_code=404, detail="用户不存在")
+    return settings
+
+
+@router.put("/profile")
+async def update_profile(
+    data: ProfileUpdateIn,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    try:
+        user = await update_user_profile(
+            current_user.id, db,
+            full_name=data.full_name,
+            password=data.password,
+            current_password=data.current_password
+        )
+        return user
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.put("/llm")
+async def update_llm(
+    data: LLMConfigIn,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    try:
+        config = await update_llm_config(current_user.id, data.model_dump(exclude_none=True), db)
+        return {"llm_config": config}
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.post("/llm/test")
+async def test_llm(
+    data: LLMTestIn,
+    current_user: User = Depends(get_current_user),
+):
+    result = await test_llm_connection(
+        provider=data.provider,
+        model=data.model,
+        base_url=data.base_url,
+        api_key=data.api_key
+    )
+    return result
+
+
+@router.put("/scheduler")
+async def update_scheduler(
+    data: SchedulerConfigIn,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    try:
+        config = await update_scheduler_config(
+            current_user.id,
+            data.model_dump(exclude_none=True),
+            db
+        )
+        return {"scheduler_config": config}
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
--- a/backend/app/routers/stats.py
+++ b/backend/app/routers/stats.py
@@ -0,0 +1,77 @@
+from fastapi import APIRouter, Depends
+from sqlalchemy.orm import Session
+from app.database import get_db
+from app.models.user import User
+from app.routers.auth import get_current_user
+from app.schemas.stats import (
+    SystemHealth,
+    ConversationStats,
+    KnowledgeStats,
+    KanbanStats,
+    CommunityStats,
+    PersonalInsights,
+)
+from app.services.stats_service import StatsService
+
+router = APIRouter(prefix="/api/stats", tags=["统计"])
+
+
+@router.get("/system", response_model=SystemHealth)
+async def get_system_health(db: Session = Depends(get_db)):
+    """获取系统健康指标"""
+    svc = StatsService(db)
+    return svc.get_system_health()
+
+
+@router.get("/conversations", response_model=ConversationStats)
+async def get_conversation_stats(
+    days: int = 30,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    """获取对话统计数据"""
+    svc = StatsService(db)
+    return svc.get_conversation_stats(user_id=current_user.id, days=days)
+
+
+@router.get("/knowledge", response_model=KnowledgeStats)
+async def get_knowledge_stats(
+    days: int = 30,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    """获取知识库统计数据"""
+    svc = StatsService(db)
+    return svc.get_knowledge_stats(user_id=current_user.id, days=days)
+
+
+@router.get("/kanban", response_model=KanbanStats)
+async def get_kanban_stats(
+    days: int = 30,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    """获取看板统计数据"""
+    svc = StatsService(db)
+    return svc.get_kanban_stats(user_id=current_user.id, days=days)
+
+
+@router.get("/community", response_model=CommunityStats)
+async def get_community_stats(
+    days: int = 30,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    """获取社区统计数据"""
+    svc = StatsService(db)
+    return svc.get_community_stats(user_id=current_user.id, days=days)
+
+
+@router.get("/insights", response_model=PersonalInsights)
+async def get_personal_insights(
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    """获取个人洞察"""
+    svc = StatsService(db)
+    return svc.get_personal_insights(user_id=current_user.id)
--- a/backend/app/routers/task.py
+++ b/backend/app/routers/task.py
@@ -0,0 +1,91 @@
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, desc
+from app.database import get_db
+from app.models.task import Task, TaskStatus
+from app.models.user import User
+from app.routers.auth import get_current_user
+from app.schemas.task import TaskCreate, TaskUpdate, TaskOut
+
+router = APIRouter(prefix="/api/tasks", tags=["看板"])
+
+
+@router.get("", response_model=list[TaskOut])
+async def list_tasks(
+    status: TaskStatus | None = None,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    query = select(Task).where(Task.user_id == current_user.id)
+    if status:
+        query = query.where(Task.status == status)
+    query = query.order_by(desc(Task.created_at))
+    result = await db.execute(query)
+    return result.scalars().all()
+
+
+@router.post("", response_model=TaskOut, status_code=201)
+async def create_task(
+    data: TaskCreate,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    import json
+    task = Task(
+        user_id=current_user.id,
+        title=data.title,
+        description=data.description,
+        priority=data.priority,
+        due_date=data.due_date,
+        tags=json.dumps(data.tags) if data.tags else None,
+    )
+    db.add(task)
+    await db.commit()
+    await db.refresh(task)
+    return task
+
+
+@router.patch("/{task_id}", response_model=TaskOut)
+async def update_task(
+    task_id: str,
+    data: TaskUpdate,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    import json
+    result = await db.execute(
+        select(Task).where(Task.id == task_id, Task.user_id == current_user.id)
+    )
+    task = result.scalar_one_or_none()
+    if not task:
+        raise HTTPException(status_code=404, detail="任务不存在")
+
+    for field, value in data.model_dump(exclude_none=True).items():
+        if field == "tags":
+            setattr(task, field, json.dumps(value))
+        elif field == "status" and value == TaskStatus.DONE:
+            from datetime import datetime
+            task.completed_at = datetime.utcnow()
+            setattr(task, field, value)
+        else:
+            setattr(task, field, value)
+
+    await db.commit()
+    await db.refresh(task)
+    return task
+
+
+@router.delete("/{task_id}", status_code=204)
+async def delete_task(
+    task_id: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    result = await db.execute(
+        select(Task).where(Task.id == task_id, Task.user_id == current_user.id)
+    )
+    task = result.scalar_one_or_none()
+    if not task:
+        raise HTTPException(status_code=404, detail="任务不存在")
+    await db.delete(task)
+    await db.commit()
--- a/backend/app/routers/todo.py
+++ b/backend/app/routers/todo.py
@@ -0,0 +1,154 @@
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, func
+from datetime import date
+from app.database import get_db
+from app.models.todo import DailyTodo, TodoSource
+from app.models.user import User
+from app.routers.auth import get_current_user
+from app.schemas.todo import (
+    TodoCreate, TodoUpdate, TodoOut, TodoListOut, TodoSummaryOut
+)
+from app.services.todo_service import generate_daily_todos
+
+router = APIRouter(prefix="/api/todos", tags=["待办"])
+
+
+@router.get("", response_model=TodoListOut)
+async def list_todos(
+    date_str: str = Query(default=None),  # YYYY-MM-DD，默认当天
+    page: int = Query(default=1, ge=1),
+    page_size: int = Query(default=50, ge=1, le=100),
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    target_date = date_str or date.today().isoformat()
+    offset = (page - 1) * page_size
+
+    # 查询总数
+    count_q = select(func.count()).select_from(DailyTodo).where(
+        DailyTodo.user_id == current_user.id,
+        DailyTodo.todo_date == target_date,
+    )
+    total = (await db.execute(count_q)).scalar()
+
+    # 查询列表
+    q = select(DailyTodo).where(
+        DailyTodo.user_id == current_user.id,
+        DailyTodo.todo_date == target_date,
+    ).order_by(DailyTodo.created_at.desc()).offset(offset).limit(page_size)
+
+    items = (await db.execute(q)).scalars().all()
+    return TodoListOut(items=items, total=total, page=page, page_size=page_size)
+
+
+@router.post("", response_model=TodoOut, status_code=201)
+async def create_todo(
+    data: TodoCreate,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    todo = DailyTodo(
+        user_id=current_user.id,
+        title=data.title,
+        source=TodoSource.MANUAL,
+        todo_date=date.today().isoformat(),
+    )
+    db.add(todo)
+    await db.commit()
+    await db.refresh(todo)
+    return todo
+
+
+@router.patch("/{todo_id}", response_model=TodoOut)
+async def update_todo(
+    todo_id: str,
+    data: TodoUpdate,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    result = await db.execute(
+        select(DailyTodo).where(DailyTodo.id == todo_id, DailyTodo.user_id == current_user.id)
+    )
+    todo = result.scalar_one_or_none()
+    if not todo:
+        raise HTTPException(status_code=404, detail="待办不存在")
+
+    # 历史日期不允许修改
+    if todo.todo_date != date.today().isoformat():
+        raise HTTPException(status_code=403, detail="历史待办不可修改")
+
+    if data.title is not None:
+        todo.title = data.title
+    if data.is_completed is not None:
+        from datetime import datetime
+        todo.is_completed = data.is_completed
+        todo.completed_at = datetime.utcnow() if data.is_completed else None
+
+    await db.commit()
+    await db.refresh(todo)
+    return todo
+
+
+@router.delete("/{todo_id}", status_code=204)
+async def delete_todo(
+    todo_id: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    result = await db.execute(
+        select(DailyTodo).where(DailyTodo.id == todo_id, DailyTodo.user_id == current_user.id)
+    )
+    todo = result.scalar_one_or_none()
+    if not todo:
+        raise HTTPException(status_code=404, detail="待办不存在")
+    if todo.todo_date != date.today().isoformat():
+        raise HTTPException(status_code=403, detail="历史待办不可删除")
+
+    await db.delete(todo)
+    await db.commit()
+
+
+@router.post("/ai-generate", response_model=TodoListOut)
+async def ai_generate_todos(
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    target_date = date.today().isoformat()
+
+    # 幂等检查：是否已有AI生成记录
+    check_q = select(func.count()).select_from(DailyTodo).where(
+        DailyTodo.user_id == current_user.id,
+        DailyTodo.todo_date == target_date,
+        DailyTodo.source.in_([TodoSource.AI_KANBAN, TodoSource.AI_CHAT]),
+    )
+    count = (await db.execute(check_q)).scalar()
+
+    if count > 0:
+        # 已生成，返回现有记录
+        q = select(DailyTodo).where(
+            DailyTodo.user_id == current_user.id,
+            DailyTodo.todo_date == target_date,
+        ).order_by(DailyTodo.created_at.desc())
+        items = (await db.execute(q)).scalars().all()
+        return TodoListOut(items=items, total=len(items), page=1, page_size=50)
+
+    # 执行AI生成
+    todos = await generate_daily_todos(current_user.id, db)
+    return TodoListOut(items=todos, total=len(todos), page=1, page_size=50)
+
+
+@router.get("/summary", response_model=TodoSummaryOut)
+async def get_summary(
+    date_str: str = Query(default=None),
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    target_date = date_str or date.today().isoformat()
+    q = select(DailyTodo).where(
+        DailyTodo.user_id == current_user.id,
+        DailyTodo.todo_date == target_date,
+    )
+    todos = (await db.execute(q)).scalars().all()
+    completed = sum(1 for t in todos if t.is_completed)
+    return TodoSummaryOut(date=target_date, total=len(todos), completed=completed, pending=len(todos) - completed)