全栈实战案例:打造《AI 知识库与书签助手》
把前几章的方法论串起来!下面演示如何用 4 轮精确对话,让 AI 协作完成一个支持“保存网页链接 → 自动提取摘要标签 → 全文检索筛选”的实用全栈小产品。
第 1 步:冻结一期边界与目录结构
- 一期必做:粘贴 URL 与标题保存、手动/AI 自动打标签、按关键词和标签筛选列表、归档/删除、简单密码访问保护。
- 一期不做:多团队协作、浏览器插件同步、付费订阅系统。
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 秒才保存成功:
POST /api/bookmarks先以status='pending'瞬间写入数据库并返回200,前端列表立刻显示新卡片(带“AI 整理中…”徽章)。- 后台用
BackgroundTasks异步抓取网页正文与生成摘要(所有外部 HTTP 请求必须设置timeout=10,并过滤内网 IP 防 SSRF 漏洞)。 - 前端每 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=测试"