@zb2947244682/supernovel 1.0.0 → 1.1.0

package/README.md

@@ -1,122 +1,350 @@
-# SuperNovel - AI小说生成器
+# SuperNovel 📚
 
-基于 Core-Shell 架构的 AI 长篇小说生成系统。
+AI-powered novel generation system with Core-Shell architecture and RAG for long-form consistency.
 
-## 架构设计
+一个基于 Core-Shell 架构的 AI 长篇小说生成系统，支持向量检索和知识图谱，确保几百章长篇小说的一致性。
 
-项目采用 **Core-Shell 架构**，分为三层：
+---
 
-### 1. Core 层（核心层）
-- **纯函数**：所有业务逻辑都是纯函数，无副作用
-- **Effects 模式**：UseCase 返回 Effect 声明而非直接执行 I/O
-- **类型安全**：完整的 TypeScript 类型定义
+## 🚀 快速开始（小白教程）
 
-### 2. Bus 层（总线层）
-- **命令分发**：Command 到 UseCase 的路由
-- **Effect 执行**：执行 Core 层声明的 Effects
-- **工作流协调**：管理生成流程的状态流转
+### 第一步：安装 Node.js
 
-### 3. Shell 层（外壳层）
-- **TUI 界面**：基于 @inquirer/prompts 的交互式界面
-- **CLI 支持**：命令行接口
-- **配置管理**：用户配置和项目存储
+1. 访问 [nodejs.org](https://nodejs.org)
+2. 下载 **LTS** 版本（推荐 20.x 或更高）
+3. 双击安装，一直点"下一步"即可
+4. 验证安装：打开命令提示符（CMD）或 PowerShell，输入：
+   ```bash
+   node --version
+   npm --version
+   ```
 
-### 4. Adapters 层（适配器层）
-- **AI 适配器**：支持 OpenAI、Anthropic、OpenRouter 等
-- **存储适配器**：文件系统操作
-- **校验适配器**：AI 辅助的内容校验
+### 第二步：获取 AI API 密钥
 
-## 安装
+本工具需要 AI 模型来生成小说，支持以下服务商：
+
+#### 选项 A：阿里云灵积（推荐国内用户）
+1. 访问 [dashscope.aliyun.com](https://dashscope.aliyun.com)
+2. 注册/登录账号
+3. 创建 API Key
+4. 推荐模型：`qwen3.5-flash`（速度快、价格便宜）
+
+#### 选项 B：OpenAI（需要翻墙）
+1. 访问 [platform.openai.com](https://platform.openai.com)
+2. 创建 API Key
+3. 推荐模型：`gpt-4o-mini` 或 `gpt-4o`
+
+#### 选项 C：其他平台
+- **OpenRouter**: 支持多种模型聚合
+- **Anthropic Claude**: 适合长文本生成
+
+### 第三步：运行 SuperNovel
+
+打开命令提示符，输入以下命令：
 
 ```bash
-npm install
-npm run build
+# 使用 npx 直接运行（无需安装）
+npx @zb2947244682/supernovel
+```
+
+### 第四步：初始化配置
+
+第一次运行会提示初始化，选择你的 AI 服务商并输入 API Key：
+
+```bash
+# 或者在 D:\Novel 目录下运行初始化
+mkdir D:\Novel
+cd D:\Novel
+npx @zb2947244682/supernovel init
+```
+
+这将创建：
+- `D:\Novel\config.json` - AI 配置
+- `D:\Novel\draft\` - 小说存放目录
+- `D:\Novel\logs\` - 日志目录
+
+### 第五步：生成你的第一部小说
+
+#### 方式一：TUI 交互界面（推荐新手）
+
+```bash
+npx @zb2947244682/supernovel
+```
+
+然后按提示选择：
+1. 🏗️ 生成小说框架 → 输入你的创意
+2. 📝 生成章节内容 → 选择刚创建的项目
+3. 等待 AI 生成完成
+
+#### 方式二：命令行（适合高级用户）
+
+```bash
+# 1. 生成小说框架
+cd D:\Novel
+npx @zb2947244682/supernovel framework "一个关于程序员穿越到异世界的故事" --name my-first-novel
+
+# 2. 生成所有章节
+npx @zb2947244682/supernovel chapters my-first-novel
+```
+
+### 第六步：查看成果
+
+生成完成后，在 `D:\Novel\draft\你的项目名\` 目录下可以看到：
+
+```
+my-first-novel/
+├── project.json      # 项目主文件（包含所有数据）
+├── requirements.md   # 需求文档
+├── world.md          # 世界观设定
+├── outline.md        # 小说大纲
+└── chapters/         # 章节文件
+    ├── chapter-1-1.md
+    ├── chapter-1-2.md
+    ├── chapter-1-3.md
+    └── ...
 ```
 
-## 使用
+用任何文本编辑器（如记事本、VS Code）打开 `.md` 文件即可阅读。
 
-### 方式一：TUI 界面（推荐）
+---
+
+## 📖 完整命令参考
+
+### 全局安装（可选）
+
+如果你不想每次都输入 `npx`，可以全局安装：
 
 ```bash
-npm start
-# 或
-npx supernovel
+npm install -g @zb2947244682/supernovel
+
+# 之后直接使用
+supernovel
+# 或简写
+sn
 ```
 
-### 方式二：CLI 命令
+### 所有命令
 
 ```bash
+# 初始化配置
+supernovel init
+
+# 测试 AI 连接
+supernovel test
+
 # 生成小说框架
-npx supernovel framework "你的小说创意描述" --name my-novel
+supernovel framework "你的创意描述" --name 项目名称
 
 # 生成章节
-npx supernovel chapters ./my-novel
+supernovel chapters 项目名称
+
+# 查看帮助
+supernovel --help
+```
+
+---
+
+## ⚙️ 配置文件详解
+
+编辑 `D:\Novel\config.json`：
 
-# 测试 AI 模型
-npx supernovel test
+```json
+{
+  "ai": {
+    "provider": "custom",
+    "baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+    "apiKey": "你的API密钥",
+    "model": "qwen3.5-flash",
+    "temperature": 0.7,
+    "maxTokens": 8000
+  }
+}
 ```
 
-## 工作流程
+### 参数说明
 
-1. **生成框架**
-   - 输入自然语言需求描述
-   - AI 生成需求文档、世界观、大纲
-   - 保存为项目文件
+| 参数 | 说明 | 推荐值 |
+|------|------|--------|
+| `provider` | AI 服务商类型 | `custom` / `openai` / `anthropic` |
+| `baseURL` | API 地址 | 根据服务商填写 |
+| `apiKey` | 你的 API 密钥 | 从服务商获取 |
+| `model` | 模型名称 | `qwen3.5-flash` / `gpt-4o` |
+| `temperature` | 创造性（0-2） | 0.7（平衡）|
+| `maxTokens` | 单次最大输出 | 8000（越大越不容易截断）|
 
-2. **生成章节**
-   - 选择已创建的项目
-   - AI 自动按大纲生成章节
-   - 自动校验并保存
+---
 
-3. **导出小说**
-   - 导出为 Markdown 格式
-   - 后续支持 EPUB 格式
+## 🎯 创意描述技巧
 
-## 项目结构
+好的创意描述会让 AI 生成更精彩的小说：
+
+### ✅ 好的示例
 
 ```
-~/novel/                    # 默认小说存储目录
-  └── my-novel/             # 项目目录
-      ├── project.json      # 项目主文件
-      ├── requirements.md   # 需求文档
-      ├── world.md          # 世界观设定
-      ├── outline.md        # 小说大纲
-      └── chapters/         # 章节文件
-          ├── chapter-1.md
-          ├── chapter-2.md
-          └── ...
+异世界治愈奇幻小说，讲述一位现代医生穿越到魔法世界，
+用医学知识解决魔法无法治愈的疾病。
+主题是治愈与救赎，风格温暖治愈，适合全年龄阅读。
 ```
 
-## 配置
+```
+科幻悬疑小说，主角发现自己生活在一个虚拟现实中，
+每次死亡都会回到起点，但保留记忆。
+需要解开这个世界的真相才能逃脱。
+```
 
-首次运行会自动创建配置文件：
+### ❌ 避免的描述
 
 ```
-~/.supernovel/config.json
+写个小说               # 太简单
+玄幻小说              # 太笼统
+类似斗破苍穹的小说     # 涉及版权作品
 ```
 
-支持的 AI 提供商：
-- OpenAI (GPT-4, GPT-3.5)
-- Anthropic (Claude)
-- OpenRouter (多种模型)
-- 自定义 API
+---
+
+## 🔧 常见问题
+
+### Q1: 提示 "未找到配置文件"
+**解决**: 先运行 `supernovel init` 初始化
+
+### Q2: API 报错 401
+**解决**: API Key 不正确，检查 config.json 中的 apiKey
+
+### Q3: 生成的 JSON 解析失败
+**解决**: 增加 `maxTokens` 到 8000 或更高，避免响应被截断
+
+### Q4: 章节的 volume 显示 undefined
+**解决**: 已修复，请更新到最新版本
+
+### Q5: 如何修改已生成的大纲？
+**解决**: 直接编辑 `outline.md` 文件，然后重新生成章节
+
+### Q6: 支持生成多少章？
+**解决**: 理论上无限制。3章后自动启用 RAG（检索增强生成），确保长文本一致性
+
+---
+
+## 🏗️ 架构设计
+
+项目采用 **Core-Shell 架构**：
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Shell 层  (CLI / TUI)                                   │
+│  - 用户交互界面                                          │
+└─────────────────────────────────────────────────────────┘
+                           ↓
+┌─────────────────────────────────────────────────────────┐
+│  Bus 层   (Command Dispatcher)                           │
+│  - 命令分发、Effect 执行、工作流协调                      │
+└─────────────────────────────────────────────────────────┘
+                           ↓
+┌─────────────────────────────────────────────────────────┐
+│  Core 层  (纯函数业务逻辑)                                │
+│  - UseCases: generateWorld, generateOutline, etc.       │
+│  - Effects: 声明式副作用                                 │
+└─────────────────────────────────────────────────────────┘
+                           ↓
+┌─────────────────────────────────────────────────────────┐
+│  Adapters 层 (AI / Storage / Logger)                     │
+│  - AI 适配器、文件存储、日志系统                          │
+└─────────────────────────────────────────────────────────┘
+```
+
+### RAG 长文本一致性系统
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  RAG Layer                                               │
+├─────────────────────────────────────────────────────────┤
+│  1. 向量存储 (Vector Store)                              │
+│     - 章节语义嵌入、相似度检索                            │
+├─────────────────────────────────────────────────────────┤
+│  2. 知识图谱 (Knowledge Graph)                           │
+│     - 实体、关系、事件追踪                                │
+├─────────────────────────────────────────────────────────┤
+│  3. 分层摘要 (Hierarchical Summaries)                    │
+│     - 全书 → 卷 → 章 三级摘要体系                        │
+├─────────────────────────────────────────────────────────┤
+│  4. 一致性检查 (Consistency Checker)                     │
+│     - 角色、世界观、时间线验证                            │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 💡 高级用法
+
+### 自定义存储路径
+
+设置环境变量：
+
+```bash
+# Windows PowerShell
+$env:SUPERNOVEL_HOME = "D:\MyNovels"
+
+# Windows CMD
+set SUPERNOVEL_HOME=D:\MyNovels
+```
+
+### 批量生成多个项目
+
+```bash
+# 创建批处理脚本 generate.bat
+@echo off
+supernovel framework "创意1" --name novel1
+supernovel framework "创意2" --name novel2
+supernovel chapters novel1
+supernovel chapters novel2
+```
+
+---
+
+## 📄 导出格式
+
+目前支持：
+- **Markdown** (`.md`) - 默认格式，适合阅读
+- **项目 JSON** (`.json`) - 包含完整数据，可重新导入
+
+未来计划：
+- EPUB 电子书格式
+- PDF 格式
+- Word 文档
+
+---
+
+## 🤝 参与贡献
+
+欢迎提交 Issue 和 PR！
+
+```bash
+# 克隆项目
+git clone https://github.com/username/supernovel.git
+cd supernovel
+
+# 安装依赖
+npm install
+
+# 开发模式
+npm run dev
+
+# 运行测试
+npm test
+```
+
+---
+
+## 📜 许可证
 
-## 特性
+MIT License
 
-- 全自动小说生成，无需人工干预
-- 智能校验：字数、角色一致性、禁用元素等
-- 两阶段生成：先框架后章节，确保质量
-- 纯函数架构，易于测试和维护
-- 模块化设计，易于扩展
+---
 
-## 技术栈
+## 🙏 致谢
 
-- TypeScript 5.x
-- Node.js 20+
-- @inquirer/prompts (TUI)
-- Commander.js (CLI)
-- Vitest (测试)
+- 阿里云灵积平台提供的模型支持
+- 开源社区的贡献者们
 
-## 许可证
+---
 
-MIT
+**Happy Writing! 🎉**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zb2947244682/supernovel",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "AI长篇小说生成系统 - Core-Shell架构 + RAG长文本一致性",
   "main": "dist/core/index.js",
   "types": "dist/core/index.d.ts",