新增项目文档，包括开发指南（CLAUDE.md）和使用说明（README.md）。
This commit is contained in:
88
CLAUDE.md
Normal file
88
CLAUDE.md
Normal file
@@ -0,0 +1,88 @@
|
|||||||
|
# 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` | 历史消息查询和清空 |
|
||||||
69
README.md
Normal file
69
README.md
Normal file
@@ -0,0 +1,69 @@
|
|||||||
|
# Noval
|
||||||
|
|
||||||
|
小说创作应用，本地Web形式，集成AI Agent辅助创作。
|
||||||
|
|
||||||
|
## 功能
|
||||||
|
|
||||||
|
- **小说管理** — 创建、编辑、删除小说作品
|
||||||
|
- **大纲管理** — 卷轴时间线可视化展示，拖拽排序
|
||||||
|
- **AI对话** — 流式对话Agent，支持OpenAI兼容API和Anthropic原生API
|
||||||
|
- **上下文窗口** — Token用量统计进度条
|
||||||
|
|
||||||
|
## 技术栈
|
||||||
|
|
||||||
|
| 层 | 技术 |
|
||||||
|
|---|------|
|
||||||
|
| 后端 | Python + FastAPI + SQLModel + SQLite |
|
||||||
|
| 前端 | Vue 3 + Vite + TypeScript |
|
||||||
|
| AI | httpx直调OpenAI/Anthropic API（无SDK依赖） |
|
||||||
|
| UI | 纯手写组件，"墨韵书斋"设计风格 |
|
||||||
|
|
||||||
|
## 快速开始
|
||||||
|
|
||||||
|
### 后端
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd backend
|
||||||
|
py -3 -m venv .venv
|
||||||
|
.venv/Scripts/pip install -r requirements.txt
|
||||||
|
.venv/Scripts/uvicorn app.main:app --port 8000
|
||||||
|
```
|
||||||
|
|
||||||
|
### 前端
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd frontend
|
||||||
|
npm install
|
||||||
|
npm run dev
|
||||||
|
```
|
||||||
|
|
||||||
|
打开浏览器访问 http://localhost:5173
|
||||||
|
|
||||||
|
### AI配置
|
||||||
|
|
||||||
|
1. 点击右下角聊天按钮
|
||||||
|
2. 点击齿轮图标打开AI配置
|
||||||
|
3. 选择服务商（OpenAI兼容 / Anthropic）
|
||||||
|
4. 填入API地址、API Key、模型名称
|
||||||
|
5. 点击"测试连接"验证后保存
|
||||||
|
|
||||||
|
## 项目结构
|
||||||
|
|
||||||
|
```
|
||||||
|
noval/
|
||||||
|
├── backend/ # FastAPI后端
|
||||||
|
│ └── app/
|
||||||
|
│ ├── models.py # 数据模型
|
||||||
|
│ ├── routers/ # API路由
|
||||||
|
│ └── services/ # AI Provider
|
||||||
|
└── frontend/ # Vue 3前端
|
||||||
|
└── src/
|
||||||
|
├── components/ # UI组件
|
||||||
|
├── views/ # 页面
|
||||||
|
├── api/ # API调用
|
||||||
|
└── composables/ # 组合式函数
|
||||||
|
```
|
||||||
|
|
||||||
|
## 许可证
|
||||||
|
|
||||||
|
开源项目，欢迎贡献。
|
||||||
Reference in New Issue
Block a user