面向书法学习者的 Web 书法助手 — 硬笔、软笔、兼修对话，支持本地私有部署。

目录

• 目录
• 简介
• 功能特性
• 技术栈
• 前后端边界
• 快速开始
• 文档
• 项目结构

简介

iTip 是面向学书者的 Web 书法助手：注册登录后可进行书法主题 AI 对话，支持多会话、附图与参考图生成。基于 Next.js 全栈 + SQLite，对接 OpenAI 兼容 API（文档示例为智谱 GLM），可本地或内网私有部署。

功能特性

类别	能力
账号	注册 / 登录、JWT（HttpOnly Cookie）、修改密码
对话	流式输出、领域 prompt + few-shot、中文分词优化
多会话	新建、搜索、重命名、置顶、删除；消息持久化
多模态	附图讨论（需视觉模型）
图片生成	OpenAI 兼容 /v1/images/generations（客户端展示，不入库）
体验	纸墨 UI、loading / error / 404、可访问性
SEO / PWA	robots、sitemap、Open Graph；Manifest 可安装（无离线缓存）
安全	Middleware 安全头、鉴权 API 内存限速

技术栈

Next.js 15（App Router）、React 19、TypeScript、Tailwind v4、Vercel AI SDK 6、SQLite（better-sqlite3）、JWT（jose）、Zod 4。版本以 web/package-lock.json 为准。

前后端边界

web/ 为 Next.js 全栈单体（非前后端分离仓库）：前端在浏览器运行 UI（components/、public/），后端在 Node 运行 API 与业务逻辑（app/api/、lib/）。app/ 内页面路由与 API 路由并存，属 App Router 约定。

详见 docs/ARCHITECTURE.md#前后端边界。

快速开始

要求：Node.js 20+、npm 9+、C++ 构建环境（better-sqlite3；Windows 需 VS Build Tools）。

git clone <repo-url> iTip
cd iTip/web
cp .env.example .env.local   # Windows: copy .env.example .env.local
# 至少配置 AUTH_SECRET 与 AI_* 三项
npm install && npm run dev

访问 http://localhost:3000。未配置 LLM 时对话接口返回 503。环境变量见 docs/DEV.md。

命令	说明
npm run dev	开发（Turbopack）
npm run build	生产构建（standalone）
npm run start	启动生产服务
npm run lint	ESLint

文档

文档	内容
REQUIREMENTS.md	产品范围、功能清单、限制与路线图
ARCHITECTURE.md	架构、前后端边界、数据模型、API
DEV.md	环境变量、开发、部署、故障排查
BADGES.md	Badge 与图标规范

项目结构

iTip/
├── web/              # Next.js 全栈应用
│   ├── app/          # 页面 + app/api/ 接口
│   ├── components/   # 客户端组件
│   ├── lib/          # 服务端逻辑（DB、鉴权、AI）
│   ├── public/       # 静态资源与 PWA 图标
│   └── data/         # SQLite（运行时，已 gitignore）
└── docs/

细节见 ARCHITECTURE.md。功能或 API 变更时请同步更新 docs/ 与本文档。