ai_novel/USAGE.md

# AI Novel Writer 使用指南

## 项目已完成！

我已经成功为您创建了一个完整的AI小说编写器agent，具备以下功能：

### ✅ 已实现的功能

1. **多LLM供应商支持**
   - OpenAI (GPT-3.5, GPT-4)
   - OpenAI兼容接口 (OpenRouter等)
   - Ollama (本地模型)

2. **核心功能**
   - 按小章节逐步生成小说内容
   - 自动生成章节总结
   - 更新章节目录结构
   - 编译完整小说

3. **项目结构**
   - 配置管理系统
   - 命令行界面 (CLI)
   - 测试用例
   - 完整文档

### 📁 项目文件结构

```
ai-novel/
├── ai_novel/                    # 主要代码
│   ├── core/                    # 核心模块
│   │   ├── __init__.py
│   │   ├── project.py           # 项目管理
│   │   ├── generator.py         # 内容生成
│   │   ├── summarizer.py        # 内容总结
│   │   └── compiler.py          # 小说编译
│   ├── __init__.py
│   ├── main.py                  # CLI入口
│   ├── config.py                # 配置管理
│   ├── llm_providers.py         # LLM供应商工厂
│   └── writer.py                # 主要编写器
├── tests/                       # 测试文件
├── novel1/                      # 示例项目目录
│   ├── 梗概大纲.md              # 小说梗概
│   └── 章节目录.yaml            # 章节结构
├── pyproject.toml               # 项目配置
├── README.md                    # 项目说明
├── example_config.yaml          # 示例配置
└── test_config.yaml             # 测试配置
```

### 🚀 使用方法

#### 1. 安装依赖
```bash
cd ai-novel
uv sync
```

#### 2. 创建配置文件
```bash
# 复制示例配置
cp example_config.yaml config.yaml

# 编辑配置文件，设置API密钥
# 或设置环境变量：
export OPENAI_API_KEY="your-api-key"
```

#### 3. 生成小说
```bash
# 生成完整小说
uv run ai-novel generate --config config.yaml

# 生成特定部分
uv run ai-novel generate --config config.yaml --part 1

# 生成特定章节
uv run ai-novel generate --config config.yaml --part 1 --chapter 1

# 生成特定小节
uv run ai-novel generate --config config.yaml --part 1 --chapter 1 --section 1
```

#### 4. 其他命令
```bash
# 查看帮助
uv run ai-novel --help

# 创建新项目
uv run ai-novel init-project my-novel

# 创建示例配置
uv run ai-novel init-config config.yaml
```

### ⚠️ 注意事项

1. **路径问题**: 由于当前路径包含中文字符，可能会遇到编码问题。建议：
   - 将项目复制到英文路径下使用
   - 或者在英文路径下重新创建项目

2. **API密钥**: 请确保设置正确的API密钥：
   - OpenAI: 设置 `OPENAI_API_KEY` 环境变量
   - OpenRouter: 设置 `OPENROUTER_API_KEY` 环境变量
   - Ollama: 确保Ollama服务正在运行

3. **模型选择**: 
   - 推荐使用GPT-4进行小说创作以获得更好的质量
   - 可以使用GPT-3.5进行章节总结以节省成本

### 🔧 配置示例

#### OpenAI配置
```yaml
project_dir: "novel1"

novelist_llm:
  type: "openai"
  model: "gpt-4"
  temperature: 0.7
  max_tokens: 3000
  api_key: "your-openai-key"

summarizer_llm:
  type: "openai"
  model: "gpt-3.5-turbo"
  temperature: 0.3
  max_tokens: 500
  api_key: "your-openai-key"
```

#### Ollama配置
```yaml
project_dir: "novel1"

novelist_llm:
  type: "ollama"
  model: "llama3.1"
  temperature: 0.7
  base_url: "http://localhost:11434"

summarizer_llm:
  type: "ollama"
  model: "llama3.1"
  temperature: 0.3
  base_url: "http://localhost:11434"
```

### 📝 工作流程

1. **读取项目文件**: 加载`梗概大纲.md`和`章节目录.yaml`
2. **构建提示词**: 包含系统提示、故事梗概、章节目录、前文内容
3. **生成章节**: LLM按小节生成内容
4. **生成总结**: 另一个LLM生成章节总结
5. **更新目录**: 将总结添加到章节目录中
6. **编译小说**: 将所有章节合并为完整小说

### 🎯 下一步

您现在可以：
1. 将项目复制到英文路径下
2. 设置API密钥
3. 开始生成您的科幻小说《光锥牢笼——从聚变之火到热寂回响》

项目已经完全按照您的要求实现，支持多种LLM供应商，具备完整的小说生成流程！