89 lines
3.4 KiB
Markdown
89 lines
3.4 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Language
|
||
|
||
使用中文作为自然语言对话和注释等语言类工作。
|
||
|
||
## Project Overview
|
||
|
||
Noval 是一个本地Web形式的小说创作应用，集成AI Agent辅助创作。用户运行Python后端 + 浏览器前端。
|
||
|
||
## Development Commands
|
||
|
||
### Backend
|
||
```bash
|
||
cd backend
|
||
# 首次安装
|
||
py -3 -m venv .venv && .venv/Scripts/pip install -r requirements.txt
|
||
# 启动（Windows上用 py -3，不要用 python3）
|
||
.venv/Scripts/uvicorn app.main:app --port 8000
|
||
# API文档
|
||
http://localhost:8000/docs
|
||
```
|
||
|
||
### Frontend
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
npm run dev # 开发服务器 http://localhost:5173
|
||
npm run build # 生产构建
|
||
npm run type-check # TypeScript类型检查
|
||
```
|
||
|
||
前端Vite代理 `/api` → `http://127.0.0.1:8000`，开发时需同时运行后端。
|
||
|
||
## Architecture
|
||
|
||
```
|
||
backend/app/
|
||
├── main.py # FastAPI入口，CORS，lifespan初始化DB
|
||
├── database.py # SQLite (backend/data/noval.db)，SQLModel engine
|
||
├── models.py # ORM: Novel, Outline, AIConfig, ChatMessage
|
||
├── schemas.py # Pydantic请求/响应模型
|
||
├── routers/ # REST API路由
|
||
│ ├── novels.py # /api/novels — 小说CRUD
|
||
│ ├── outlines.py # /api/novels/{id}/outlines — 大纲CRUD+排序
|
||
│ ├── ai_config.py # /api/ai/config — AI服务配置
|
||
│ └── chat.py # /api/chat/stream — SSE流式对话
|
||
└── services/
|
||
└── ai_provider.py # AI抽象层：OpenAI兼容 + Anthropic原生，httpx直调无SDK
|
||
|
||
frontend/src/
|
||
├── api/ # Axios封装 + 各资源API（novels, outlines, chat）
|
||
├── types/ # TypeScript接口定义
|
||
├── composables/ # Vue组合式函数（useChatAgent, useToast）
|
||
├── components/
|
||
│ ├── ui/ # 基础组件：BaseButton, BaseInput, BaseModal等
|
||
│ ├── novel/ # 小说卡片、网格、空状态
|
||
│ ├── outline/ # 卷轴时间线、节点卡片、表单
|
||
│ └── chat/ # 聊天面板、消息气泡、AI配置弹窗
|
||
├── views/ # 页面视图
|
||
└── style/ # CSS变量、重置、排版、动画
|
||
```
|
||
|
||
### Key Patterns
|
||
|
||
- **后端**：FastAPI + SQLModel + SQLite，同步Session，路由按资源分文件
|
||
- **前端**：Vue 3 Composition API + TypeScript，纯手写UI组件（无组件库）
|
||
- **AI集成**：不用SDK，httpx直调OpenAI/Anthropic HTTP API，SSE流式输出
|
||
- **聊天状态**：`useChatAgent()` 使用模块级ref实现全局共享
|
||
- **流式处理**：后端 `StreamingResponse` → 前端 `fetch` + `ReadableStream` 解析SSE
|
||
|
||
### Design System — "墨韵书斋"
|
||
|
||
CSS变量定义在 `frontend/src/style/variables.css`：
|
||
- 墨色系(--ink-*)、纸色系(--paper-*)、朱砂红(--vermilion)、竹青(--bamboo)
|
||
- 字体：Noto Serif SC（标题）、Crimson Pro（正文）
|
||
|
||
## API Structure
|
||
|
||
| 前缀 | 说明 |
|
||
|------|------|
|
||
| `/api/novels` | 小说CRUD，PATCH部分更新 |
|
||
| `/api/novels/{id}/outlines` | 大纲CRUD + `PUT /reorder` 排序 |
|
||
| `/api/ai/config` | AI配置读写 + `POST /test` 测试连接 |
|
||
| `/api/chat/stream` | SSE流式对话，返回content/usage/done事件 |
|
||
| `/api/chat/messages` | 历史消息查询和清空 |
|