ai-novel/README.md

# AI 小说创作平台

基于 React、ProComponents、Ollama 和 Qwen3:8B 构建的本地化 AI 小说创作平台。

## 🚀 功能特点

### 核心功能
- **模型设置** - 二级菜单结构，专门配置本地 Ollama 模型
- **智能检测** - 自动检测本地 Ollama 服务状态和已安装模型
- **小说卡片管理** - 以卡片形式展示小说列表，支持新增、编辑、删除
- **AI 章节生成** - 集成 Ollama API 进行智能章节生成，支持自定义提示词
- **内容管理** - 自动保存到浏览器 IndexedDB，支持查看、编辑、导出
- **Markdown 导出** - 支持单章或整本小说导出为 Markdown 格式

### 最新优化
- ✅ **二级菜单** - 设置 > 模型的层级结构
- ✅ **IndexedDB 存储** - 替代 localStorage，支持更大存储容量
- ✅ **智能模型检测** - 自动检测本地 Ollama 已安装的模型
- ✅ **模型验证** - 限制只能选择本地已安装的模型
- ✅ **连接状态监控** - 实时显示 Ollama 服务连接状态
- ✅ **现代化 UI** - 干净整洁的界面设计

## 🛠️ 技术栈

- **前端**: React + TypeScript + Ant Design
- **路由**: React Router v6
- **AI 集成**: Ollama REST API
- **数据存储**: IndexedDB
- **文档处理**: ReactMarkdown

## 📋 前置要求

### 必需软件
1. **Node.js** (v14 或更高版本)
2. **Ollama** - 本地 AI 模型运行环境

### Ollama 安装
```bash
# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# Windows
# 从 https://ollama.com/download 下载安装
```

### 推荐模型
```bash
# Qwen2.5 系列（推荐）
ollama pull qwen2.5:7b
ollama pull qwen2.5:14b

# Llama3 系列
ollama pull llama3:8b

# 其他中文模型
ollama pull qwen2:7b
```

## 🚀 快速开始

### 1. 安装依赖
```bash
npm install
```

### 2. 启动 Ollama 服务
```bash
ollama serve
```

### 3. 启动开发服务器
```bash
npm start
```

### 4. 访问应用
打开浏览器访问 http://localhost:3000

## 📖 使用指南

### 首次配置

1. **启动 Ollama 服务**
   ```bash
   ollama serve
   ```

2. **进入模型设置**
   - 点击左侧菜单的"设置" > "模型"
   - 默认 Ollama 地址：`http://localhost:11434`

3. **测试连接**
   - 点击"测试连接"按钮验证 Ollama 服务状态

4. **检测模型**
   - 点击"检测模型"按钮获取本地已安装模型
   - 系统会显示模型名称和大小信息

5. **选择模型**
   - 从下拉列表中选择本地已安装的模型
   - 如需新模型，先使用 `ollama pull 模型名` 安装

6. **调整参数**
   - **Temperature**: 0.7（控制随机性，0-2）
   - **Top P**: 0.9（控制多样性，0-1）
   - **最大 Tokens**: 2000（生成长度）

### 创作流程

1. **创建小说**
   - 进入"小说管理"
   - 点击"新建小说"
   - 填写书名、题材、大纲、人物设定

2. **生成章节**
   - 点击小说卡片进入详情页
   - 点击"生成新章节"
   - 输入章节标题和可选的提示词
   - 等待 AI 生成内容

3. **管理内容**
   - **查看**: 点击"查看"按钮预览 Markdown 格式内容
   - **编辑**: 点击"编辑"按钮修改章节内容
   - **导出**: 点击"导出"按钮下载单章或整本小说

## 🔧 高级配置

### 自定义 Ollama 地址
如果 Ollama 运行在其他地址：
```
http://your-server:11434
```

### 模型选择建议
- **轻量级**: qwen2.5:3b (4GB 内存)
- **平衡**: qwen2.5:7b (8GB 内存) 
- **高质量**: qwen2.5:14b (16GB 内存)
- **英文**: llama3:8b (8GB 内存)

### 生成参数调优
- **创意写作**: Temperature 0.8-1.0
- **技术内容**: Temperature 0.3-0.5
- **平衡**: Temperature 0.7（默认）

## 📁 项目结构

```
src/
├── components/          # React 组件
│   └── MainLayout.tsx  # 主布局（左侧菜单+右侧内容）
├── pages/              # 页面组件
│   ├── NovelList.tsx   # 小说列表
│   ├── NovelDetail.tsx # 小说详情
│   └── ModelSettings.tsx # 模型设置
├── utils/              # 工具函数
│   ├── indexedDB.ts    # IndexedDB 数据存储
│   ├── ollama.ts       # AI 服务集成
│   └── fileManager.ts  # 文件导出
└── types/              # TypeScript 类型定义
    └── index.ts
```

## 🐛 常见问题

### Q: 无法连接 Ollama 服务
**A**: 
1. 确保 Ollama 服务正在运行：`ollama serve`
2. 检查服务地址是否正确
3. 确认端口 11434 未被占用

### Q: 检测不到模型
**A**:
1. 使用 `ollama list` 查看已安装模型
2. 使用 `ollama pull 模型名` 安装新模型
3. 点击"检测模型"按钮刷新列表

### Q: 数据存储在哪里？
**A**: 
- 所有数据存储在浏览器的 IndexedDB 中
- 数据库名称：AINovelDB
- 建议定期导出重要作品进行备份

### Q: 章节生成失败
**A**:
1. 检查 Ollama 服务是否正常
2. 确认选择的模型已正确安装
3. 尝试降低 `maxTokens` 参数
4. 查看浏览器控制台错误信息

### Q: 生成内容质量不佳
**A**:
1. 尝试调整 Temperature 参数
2. 在提示词中提供更详细的要求
3. 完善小说的大纲和人物设定
4. 使用更大参数量的模型

## 🔐 安全说明

- 所有数据存储在浏览器 IndexedDB 中，不会上传到云端
- Ollama 服务完全运行在本地，确保隐私安全
- 支持更大容量的数据存储（相比 localStorage）
- 建议定期导出重要作品进行备份

## 📝 开发说明

### 构建生产版本
```bash
npm run build
```

### 运行测试
```bash
npm test
```

### 代码规范
- 使用 TypeScript 编写
- 遵循 React Hooks 最佳实践
- 组件式开发，便于维护和扩展

## 📄 许可证

MIT License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📮 联系方式

如有问题请提交 Issue 或联系开发者。

---

**享受 AI 创作的乐趣！** ✨