VibeCraft Vibe Coding 实战指南
完整实战案例 FastAPI + SQLite + 静态前端 可直接复刻

全栈实战案例:打造《AI 知识库与书签助手》

把前几章的方法论串起来!下面演示如何用 4 轮精确对话,让 AI 协作完成一个支持“保存网页链接 → 自动提取摘要标签 → 全文检索筛选”的实用全栈小产品。

第 1 步:冻结一期边界与目录结构

knowledge-box/
├── AGENTS.md
├── .env.example          # ADMIN_PASS, OPENAI_API_KEY, DB_PATH
├── app.py                # FastAPI 后端(同时托管 static/ 前端文件,零跨域烦恼!)
├── db.py                 # SQLite WAL 初始化与 CRUD
└── static/
    ├── index.html
    ├── style.css
    └── app.js
工程技巧:轻量应用让后端直接托管静态前端

对于中小工具,把前端放进 static/ 由 FastAPI StaticFiles 同端口提供服务,不仅彻底消灭 CORS 跨域麻烦,上线部署也只需要 1 个进程 / 1 个 Docker 容器。

第 2 步:核心数据库与 CRUD 逻辑(db.py)

import sqlite3, json
from contextlib import contextmanager

DB_PATH = "./data/knowledge.db"

@contextmanager
def get_conn():
    conn = sqlite3.connect(DB_PATH)
    conn.row_factory = sqlite3.Row
    try:
        yield conn
        conn.commit()
    finally:
        conn.close()

def list_items(q: str = "", tag: str = ""):
    sql = "SELECT * FROM bookmarks WHERE is_archived = 0"
    params = []
    if q:
        sql += " AND (title LIKE ? OR summary LIKE ? OR url LIKE ?)"
        like = f"%{q}%"
        params.extend([like, like, like])
    if tag:
        sql += " AND tags LIKE ?"
        params.append(f'%"{tag}"%')
    sql += " ORDER BY id DESC LIMIT 100"
    with get_conn() as conn:
        rows = conn.execute(sql, params).fetchall()
    return [dict(r) for r in rows]

第 3 步:防卡顿关键设计——异步入库与超时保护

如果保存一个链接时要调用外网抓取标题和 LLM 总结,千万不要让前端死等 15 秒才保存成功:

  1. POST /api/bookmarks 先以 status='pending' 瞬间写入数据库并返回 200,前端列表立刻显示新卡片(带“AI 整理中…”徽章)。
  2. 后台用 BackgroundTasks 异步抓取网页正文与生成摘要(所有外部 HTTP 请求必须设置 timeout=10,并过滤内网 IP 防 SSRF 漏洞)。
  3. 前端每 2 秒轻量轮询或通过 SSE 收到更新后,自动把摘要和标签刷上去。

第 4 步:端到端验收命令清单

# 1. 启动服务
uvicorn app:app --host 127.0.0.1 --port 8000

# 2. 终端验证增删改查闭环
curl -s http://127.0.0.1:8000/api/health
curl -s -X POST http://127.0.0.1:8000/api/bookmarks   -H "Content-Type: application/json"   -d '{"url":"https://example.com","title":"测试资料","tags":["AI","工程"]}'
curl -s "http://127.0.0.1:8000/api/bookmarks?q=测试"