新增项目文档，包括开发指南（CLAUDE.md）和使用说明（README.md）。

2026-03-19 01:39:23 +08:00
parent ba6ceb94c8
commit c13adaa0fc
2 changed files with 157 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -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` | 历史消息查询和清空 |