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

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

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`	历史消息查询和清空

3.4 KiB Raw Blame History Unescape Escape