diff --git a/README.md b/README.md index e69de29..6ec40ef 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,238 @@ +# 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 创作的乐趣!** ✨ \ No newline at end of file diff --git a/TESTING.md b/TESTING.md new file mode 100644 index 0000000..8ca0348 --- /dev/null +++ b/TESTING.md @@ -0,0 +1,194 @@ +# AI 小说创作平台 - 测试指南 + +## 🧪 边界情况测试 + +### 1. 首次启动测试(无配置) + +**预期结果:** +- ✅ 底部状态栏显示:Ollama 状态: 未连接 | 模型数量: 0 个 | 当前模型: 未配置模型 +- ✅ 当前模型文字显示为红色 +- ✅ 显示"前往配置"按钮 +- ✅ 侧边栏状态显示:服务未连接 + +### 2. Ollama 服务未启动测试 + +**步骤:** +1. 确保 Ollama 服务未运行 +2. 启动应用 + +**预期结果:** +- ✅ 底部状态栏显示:Ollama 状态: 未连接(红色) +- ✅ 显示警告提示:Ollama 服务未连接 +- ✅ 提示信息:请确保 Ollama 服务正在运行 +- ✅ 侧边栏显示服务未连接图标 + +### 3. 有服务但无模型测试 + +**步骤:** +1. 启动 Ollama 服务 +2. 不安装任何模型 +3. 启动应用 + +**预期结果:** +- ✅ 底部状态栏显示:Ollama 状态: 已连接(绿色)| 模型数量: 0 个(黄色) +- ✅ 当前模型: 未配置模型(红色) +- ✅ 显示警告提示:未检测到 AI 模型 +- ✅ 提示信息:请先安装 AI 模型 + +### 4. 配置了模型但未安装测试 + +**步骤:** +1. 在设置中选择一个模型(如 qwen2.5:7b) +2. 但本地实际没有安装这个模型 +3. 启动应用 + +**预期结果:** +- ✅ 底部状态栏显示:Ollama 状态: 已连接 | 模型数量: 0 个 +- ✅ 当前模型: qwen2.5:7b (未安装)(黄色) +- ✅ 显示警告提示:当前配置的模型未安装 +- ✅ 提示前往配置页面重新选择 + +### 5. 正常配置测试 + +**步骤:** +1. 启动 Ollama 服务 +2. 安装模型:ollama pull qwen2.5:7b +3. 在设置中选择该模型 +4. 启动应用 + +**预期结果:** +- ✅ 底部状态栏显示:Ollama 状态: 已连接(绿色)| 模型数量: 1 个(绿色) +- ✅ 当前模型: qwen2.5:7b (4.XX GB)(绿色) +- ✅ 不显示任何警告提示 +- ✅ 侧边栏显示正常状态 + +### 6. 多个模型测试 + +**步骤:** +1. 安装多个模型:qwen2.5:7b, llama3:8b +2. 启动应用 + +**预期结果:** +- ✅ 底部状态栏显示:模型数量: 2 个 +- ✅ 当前模型显示实际选中的模型信息 +- ✅ 模型配置页面显示所有可用模型 + +### 7. 配置变更测试 + +**步骤:** +1. 从一个模型切换到另一个模型 +2. 观察底部状态栏变化 + +**预期结果:** +- ✅ 切换后底部状态栏立即更新 +- ✅ 如果新模型未安装,显示警告状态 +- ✅ 如果新模型已安装,显示正常状态 + +## 🔄 状态刷新测试 + +### 手动刷新测试 +**步骤:** +1. 点击底部"刷新状态"按钮 +2. 观察 loading 状态 + +**预期结果:** +- ✅ 按钮显示加载动画 +- ✅ 状态信息更新 +- ✅ 如果期间状态变化,及时反映 + +### 自动刷新测试 +**步骤:** +1. 启动应用后等待30秒 +2. 观察 auto-refresh 机制 + +**预期结果:** +- ✅ 每30秒自动检查状态 +- ✅ 状态变化时自动更新界面 +- ✅ 无需手动操作 + +## 🎯 模型配置页面测试 + +### 页面加载测试 +**步骤:** +1. 进入设置 > 模型页面 +2. 观察初始状态 + +**预期结果:** +- ✅ 页面顶部显示服务状态卡片 +- ✅ 如果已连接,自动显示已安装模型 +- ✅ 表单自动加载当前配置 + +### 检测模型测试 +**步骤:** +1. 点击"检测模型"按钮 +2. 观察 loading 和结果 + +**预期结果:** +- ✅ 显示加载状态 +- ✅ 检测完成后显示模型列表 +- ✅ 如果当前模型未安装,自动清空选择 +- ✅ 全局状态同步更新 + +### 保存配置测试 +**步骤:** +1. 修改模型选择 +2. 点击"保存配置" +3. 观察底部状态栏 + +**预期结果:** +- ✅ 配置保存成功提示 +- ✅ 底部状态栏立即更新 +- ✅ 全局状态同步更新 +- ✅ 新配置生效 + +## 🚨 异常情况测试 + +### 网络断开测试 +**步骤:** +1. 正常运行时断开网络 +2. 尝试刷新状态 + +**预期结果:** +- ✅ 显示连接错误 +- ✅ 不显示崩溃或白屏 +- ✅ 提供重试机制 + +### 模型损坏测试 +**步骤:** +1. 使用损坏的模型 +2. 启动应用 + +**预期结果:** +- ✅ 系统识别模型问题 +- ✅ 提示重新选择模型 +- ✅ 不影响其他功能使用 + +## ✅ 功能完整性检查 + +- [ ] 启动时自动检查 Ollama 状态 +- [ ] 启动时自动检查模型安装情况 +- [ ] 底部状态栏实时显示准确信息 +- [ ] 模型未配置时显示明确提示 +- [ ] 模型未安装时显示警告状态 +- [ ] 配置无效模型时提示用户 +- [ ] 提供"前往配置"快捷入口 +- [ ] 手动刷新状态功能正常 +- [ ] 自动刷新状态机制工作 +- [ ] 配置变更立即生效 +- [ ] 错误处理用户友好 + +## 🎨 界面显示规则 + +### 状态颜色规则 +- **绿色**: 状态正常,已配置且已安装 +- **黄色**: 有问题但可用,如未安装模型 +- **红色**: 严重问题,如未配置或服务未连接 +- **灰色**: 服务未连接时的模型信息 + +### 文字提示规则 +- **未配置模型**: "未配置模型" + 红色 + 前往配置按钮 +- **未安装模型**: "模型名 (未安装)" + 黄色 +- **服务未连接**: "模型名 (服务未连接)" + 灰色 +- **正常状态**: "模型名 (大小)" + 绿色 + +通过以上测试,确保系统在各种边界情况下都能正确显示状态信息并提供用户友好的提示。 \ No newline at end of file diff --git a/build/asset-manifest.json b/build/asset-manifest.json new file mode 100644 index 0000000..e3505d9 --- /dev/null +++ b/build/asset-manifest.json @@ -0,0 +1,15 @@ +{ + "files": { + "main.css": "/static/css/main.18111be9.css", + "main.js": "/static/js/main.907ae9a2.js", + "static/js/453.d0dce72f.chunk.js": "/static/js/453.d0dce72f.chunk.js", + "index.html": "/index.html", + "main.18111be9.css.map": "/static/css/main.18111be9.css.map", + "main.907ae9a2.js.map": "/static/js/main.907ae9a2.js.map", + "453.d0dce72f.chunk.js.map": "/static/js/453.d0dce72f.chunk.js.map" + }, + "entrypoints": [ + "static/css/main.18111be9.css", + "static/js/main.907ae9a2.js" + ] +} \ No newline at end of file diff --git a/build/favicon.ico b/build/favicon.ico new file mode 100644 index 0000000..a11777c Binary files /dev/null and b/build/favicon.ico differ diff --git a/build/index.html b/build/index.html new file mode 100644 index 0000000..c926f0e --- /dev/null +++ b/build/index.html @@ -0,0 +1 @@ +