@zb2947244682/supernovel 1.0.0 → 1.1.1

package/README.md

@@ -1,122 +1,397 @@
-# SuperNovel - AI小说生成器
+# SuperNovel 📚
 
-基于 Core-Shell 架构的 AI 长篇小说生成系统。
+AI-powered novel generation system with Core-Shell architecture, RAG for long-form consistency, and **automatic error correction**.
 
-## 架构设计
+基于 Core-Shell 架构的 AI 长篇小说生成系统，支持 RAG 长文本一致性保障，**自动检测并修复世界观冲突**，确保交付完整无错误的小说。
 
-项目采用 **Core-Shell 架构**，分为三层：
+---
 
-### 1. Core 层（核心层）
-- **纯函数**：所有业务逻辑都是纯函数，无副作用
-- **Effects 模式**：UseCase 返回 Effect 声明而非直接执行 I/O
-- **类型安全**：完整的 TypeScript 类型定义
+## ✨ 核心特性
 
-### 2. Bus 层（总线层）
-- **命令分发**：Command 到 UseCase 的路由
-- **Effect 执行**：执行 Core 层声明的 Effects
-- **工作流协调**：管理生成流程的状态流转
+| 特性 | 说明 |
+|------|------|
+| 🏗️ **Core-Shell 架构** | 纯函数 Core + Effect 模式 + Bus 协调，代码清晰可维护 |
+| 🧠 **RAG 长文本一致性** | 向量存储 + 知识图谱 + 分层摘要，确保数百章长篇小说世界观一致 |
+| 🔧 **强制自动修复** | 检测世界观违规 → 生成 TextEdit 修复 → 重新检查，直到无错误或抛出异常 |
+| 📂 **分层存储** | project.json 轻量级元数据（<50KB）+ chapters/ 独立文件按需加载 |
+| 🔄 **断点续传** | 支持中断后从上次位置继续生成 |
+| 📊 **一致性检查** | 角色状态、世界观规则、时间线、情节连续性四重验证 |
 
-### 3. Shell 层（外壳层）
-- **TUI 界面**：基于 @inquirer/prompts 的交互式界面
-- **CLI 支持**：命令行接口
-- **配置管理**：用户配置和项目存储
+---
 
-### 4. Adapters 层（适配器层）
-- **AI 适配器**：支持 OpenAI、Anthropic、OpenRouter 等
-- **存储适配器**：文件系统操作
-- **校验适配器**：AI 辅助的内容校验
+## 🚀 快速开始
 
-## 安装
+### 环境要求
+
+- **Node.js 20+**
+- **AI API 密钥**（支持阿里云、OpenAI、OpenRouter 等）
+
+### 安装与初始化
 
 ```bash
-npm install
-npm run build
+# 使用 npx 直接运行（无需安装）
+npx @zb2947244682/supernovel init
+
+# 或全局安装
+npm install -g @zb2947244682/supernovel
+supernovel init
+```
+
+初始化后编辑配置文件，添加你的 API 密钥：
+
+```bash
+# Windows: C:\Users\你的用户名\.supernovel\config.json
+# 或项目目录下的 config.json
+{
+  "ai": {
+    "provider": "custom",
+    "baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+    "apiKey": "你的API密钥",
+    "model": "qwen3.5-flash",
+    "temperature": 0.7,
+    "maxTokens": 32000
+  }
+}
+```
+
+### 生成小说
+
+#### 方式一：TUI 交互界面（推荐）
+
+```bash
+npx @zb2947244682/supernovel
 ```
 
-## 使用
+按菜单提示：
+1. 🏗️ 生成小说框架 → 输入创意描述
+2. 📝 生成章节内容 → 选择项目开始生成
+3. ✅ 系统自动检查并修复世界观冲突
 
-### 方式一：TUI 界面（推荐）
+#### 方式二：CLI 命令行
 
 ```bash
-npm start
-# 或
-npx supernovel
+# 1. 生成小说框架
+cd D:\Novel
+npx @zb2947244682/supernovel framework "一个程序员穿越到魔法世界的故事" --name my-novel
+
+# 2. 生成所有章节（含自动一致性检查和修复）
+npx @zb2947244682/supernovel chapters my-novel
+```
+
+---
+
+## 📂 项目结构
+
+### 分层存储架构
+
+```
+draft/my-novel/
+├── project.json          # 轻量级元数据 (~20KB)
+│   ├── requirements      # 需求设定
+│   ├── worldState        # 世界观、角色、规则
+│   ├── outline           # 大纲结构
+│   └── chapterMeta[]     # 章节元数据索引
+├── chapters/             # 章节正文独立存储
+│   ├── chapter-1-1.md
+│   ├── chapter-1-2.md
+│   └── ...
+├── requirements.md       # 需求文档（导出用）
+├── world.md             # 世界观文档（导出用）
+└── outline.md           # 大纲文档（导出用）
+```
+
+### 章节文件格式
+
+```markdown
+---
+id: ch_1_1
+volume: 1
+number: 1
+wordCount: 3256
+---
+
+# 第一章标题
+
+章节正文内容...
+```
+
+---
+
+## 🔧 强制自动修复机制
+
+SuperNovel 的核心目标是**交付完整无错误的小说**。为此，系统实现了强制自动修复机制：
+
+### 修复流程
+
+```
+生成章节 → 一致性检查 → 发现问题？
+                              ↓
+            ┌─────────────────┴─────────────────┐
+            ↓                                   ↓
+        无问题                              有问题
+            ↓                                   ↓
+        保存章节                        生成 TextEdit 修复
+            ↓                                   ↓
+                                             应用修复
+                                                  ↓
+                                            重新检查（最多3轮）
+                                                  ↓
+                              ┌─────────────────┴─────────────────┐
+                              ↓                                   ↓
+                          无问题                               仍有问题
+                              ↓                                   ↓
+                          保存章节                    不可修复？→ 抛出异常
+                                                              可修复？→ 继续修复
+```
+
+### 世界观规则冲突自动修复示例
+
+**原始内容（违规）：**
+```
+凯伦感觉魔力已经完全耗尽，却依然举起法杖，强行释放了一个火球术。
+```
+
+**自动修复后：**
+```
+凯伦感觉魔力已经完全耗尽，试图释放火球术却失败了，只能咬牙冲上去近身肉搏。
+```
+
+### 修复策略
+
+| 违规类型 | 修复策略 |
+|----------|----------|
+| 魔力/能量耗尽后施法 | 改为物理行动（"只能咬牙冲上去近身肉搏"） |
+| 等级限制突破 | 弱化行为强度（"强行"→"尝试"，"瞬间"→"艰难地"） |
+| 物理法则冲突（如无火药世界出现枪） | 替换为等价魔法元素（"枪"→"弩箭"，"火药"→"炼金爆炸物"） |
+| 角色能力无解释 | 在章节开头添加能力获得的情节铺垫 |
+
+### 严格保证
+
+- ✅ 所有可修复问题自动修复
+- ✅ 修复后重新检查确认无错误
+- ✅ 不可修复的错误抛出异常，不会交付错误内容
+
+---
+
+## 🏗️ 系统架构
+
+### Core-Shell 架构
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Shell 层  (CLI / TUI)                                   │
+│  - 用户交互界面、命令解析                                 │
+└─────────────────────────────────────────────────────────┘
+                           ↓
+┌─────────────────────────────────────────────────────────┐
+│  Bus 层   (Command Dispatcher / Effect Runner)           │
+│  - 命令分发、Effect 执行、工作流协调                      │
+│  - 强制修复循环实现                                       │
+└─────────────────────────────────────────────────────────┘
+                           ↓
+┌─────────────────────────────────────────────────────────┐
+│  Core 层  (纯函数业务逻辑)                                │
+│  - UseCases: parseRequirements, generateWorld, etc.     │
+│  - Effects: AI_CHAT, SAVE_FILE, VALIDATE_CHAPTER        │
+│  - RAG: VectorStore, KnowledgeGraph, ConsistencyChecker │
+└─────────────────────────────────────────────────────────┘
+                           ↓
+┌─────────────────────────────────────────────────────────┐
+│  Adapters 层 (AI / Storage / Logger)                     │
+│  - AI 适配器（支持多提供商）                              │
+│  - 分层存储（project.json + chapters/）                  │
+│  - 日志系统                                              │
+└─────────────────────────────────────────────────────────┘
+```
+
+### RAG 长文本一致性系统
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  RAG Layer                                               │
+├─────────────────────────────────────────────────────────┤
+│  1. 向量存储 (Vector Store)                              │
+│     - 章节语义嵌入、相似度检索                            │
+│     - 支持上下文召回                                    │
+├─────────────────────────────────────────────────────────┤
+│  2. 知识图谱 (Knowledge Graph)                           │
+│     - 实体追踪（角色、地点、物品）                        │
+│     - 关系网络、事件追踪                                  │
+├─────────────────────────────────────────────────────────┤
+│  3. 分层摘要 (Hierarchical Summaries)                    │
+│     - 全书摘要 → 卷摘要 → 章摘要                         │
+│     - 动态更新机制                                      │
+├─────────────────────────────────────────────────────────┤
+│  4. 一致性检查器 (Consistency Checker)                   │
+│     - 角色一致性：能力变化需有情节铺垫                    │
+│     - 世界观规则：强制修复所有冲突                        │
+│     - 时间线连续性：前置事件检查                          │
+│     - 情节连续性：伏笔回收、情节推进                      │
+└─────────────────────────────────────────────────────────┘
 ```
 
-### 方式二：CLI 命令
+---
+
+## 📖 命令参考
 
 ```bash
+# 初始化配置
+supernovel init
+
+# 测试 AI 连接
+supernovel test
+
 # 生成小说框架
-npx supernovel framework "你的小说创意描述" --name my-novel
+supernovel framework "创意描述" --name <项目名称>
+
+# 生成所有章节（含自动修复）
+supernovel chapters <项目名称>
+
+# 查看帮助
+supernovel --help
+```
+
+### 配置参数
+
+| 参数 | 说明 | 推荐值 |
+|------|------|--------|
+| `provider` | AI 服务商 | `custom` / `openai` / `anthropic` / `openrouter` |
+| `baseURL` | API 基础地址 | 根据服务商填写 |
+| `apiKey` | API 密钥 | 从服务商获取 |
+| `model` | 模型名称 | `qwen3.5-flash` / `gpt-4o-mini` / `gpt-4o` |
+| `temperature` | 创造性 (0-2) | 0.7 |
+| `maxTokens` | 最大输出 token | 32000（避免截断） |
+
+---
+
+## 🧪 开发与测试
+
+```bash
+# 克隆项目
+git clone https://github.com/username/supernovel.git
+cd supernovel
+
+# 安装依赖
+npm install
+
+# 构建
+npm run build
+
+# 开发模式
+npm run dev
+
+# 运行测试
+npm test
 
-# 生成章节
-npx supernovel chapters ./my-novel
+# 运行核心测试
+npm run test:core
 
-# 测试 AI 模型
-npx supernovel test
+# 运行端到端测试
+npm run test:e2e
 ```
 
-## 工作流程
+### 测试覆盖
 
-1. **生成框架**
-   - 输入自然语言需求描述
-   - AI 生成需求文档、世界观、大纲
-   - 保存为项目文件
+- ✅ 分层存储（project.json + chapters/）
+- ✅ 按需加载（loadChapters with limit/offset）
+- ✅ TextEdit 修复应用
+- ✅ 多轮修复循环
+- ✅ 世界观规则冲突检测与修复
 
-2. **生成章节**
-   - 选择已创建的项目
-   - AI 自动按大纲生成章节
-   - 自动校验并保存
+---
 
-3. **导出小说**
-   - 导出为 Markdown 格式
-   - 后续支持 EPUB 格式
+## 🎯 创意描述技巧
 
-## 项目结构
+### 好的示例
 
 ```
-~/novel/                    # 默认小说存储目录
-  └── my-novel/             # 项目目录
-      ├── project.json      # 项目主文件
-      ├── requirements.md   # 需求文档
-      ├── world.md          # 世界观设定
-      ├── outline.md        # 小说大纲
-      └── chapters/         # 章节文件
-          ├── chapter-1.md
-          ├── chapter-2.md
-          └── ...
+异世界治愈奇幻小说，讲述一位现代医生穿越到魔法世界，
+用医学知识解决魔法无法治愈的疾病。
+主题是治愈与救赎，风格温暖治愈，适合全年龄阅读。
+世界观规则：魔力是有限的资源，耗尽后无法施法。
 ```
 
-## 配置
+```
+科幻悬疑小说，主角发现自己生活在一个虚拟现实中，
+每次死亡都会回到起点，但保留记忆。
+需要解开这个世界的真相才能逃脱。
+禁止元素：超自然力量、系统外援助
+```
 
-首次运行会自动创建配置文件：
+### 避免的描述
 
 ```
-~/.supernovel/config.json
+写个小说               # 太简单
+玄幻小说              # 太笼统
+类似XX小说            # 涉及版权
+```
+
+---
+
+## 🔍 常见问题
+
+### Q: 生成的 JSON 解析失败？
+**解决**: 增加 `maxTokens` 到 32000，避免响应被截断
+
+### Q: 世界观规则冲突是什么意思？
+**解决**: 系统会自动检测并修复。例如规则设定"魔力耗尽后无法施法"，如果AI生成了"魔力耗尽后依然施法"，系统会自动修复为符合规则的描述。
+
+### Q: 支持生成多少章？
+**解决**: 理论上无限制。3章后自动启用 RAG（检索增强生成），确保长文本一致性。每5章自动保存进度元数据。
+
+### Q: 如何修改已生成的大纲？
+**解决**: 直接编辑 `outline.md` 文件，然后重新运行 `supernovel chapters <项目名>`
+
+### Q: 如何中断后继续生成？
+**解决**: 系统支持断点续传。直接重新运行章节生成命令，会从上次中断的章节继续。
+
+---
+
+## 📄 导出格式
+
+- **Markdown** (`.md`) - 默认格式，适合阅读和进一步编辑
+- **项目 JSON** (`.json`) - 包含完整元数据
+
+计划中：
+- EPUB 电子书格式
+- PDF 格式
+
+---
+
+## 🤝 参与贡献
+
+欢迎提交 Issue 和 PR！
+
+```bash
+# Fork 并克隆
+git clone https://github.com/your-username/supernovel.git
+cd supernovel
+
+# 创建分支
+git checkout -b feature/your-feature
+
+# 提交更改
+git commit -am "Add some feature"
+
+# 推送
+git push origin feature/your-feature
+
+# 创建 Pull Request
 ```
 
-支持的 AI 提供商：
-- OpenAI (GPT-4, GPT-3.5)
-- Anthropic (Claude)
-- OpenRouter (多种模型)
-- 自定义 API
+---
+
+## 📜 许可证
 
-## 特性
+MIT License
 
-- 全自动小说生成，无需人工干预
-- 智能校验：字数、角色一致性、禁用元素等
-- 两阶段生成：先框架后章节，确保质量
-- 纯函数架构，易于测试和维护
-- 模块化设计，易于扩展
+---
 
-## 技术栈
+## 🙏 致谢
 
-- TypeScript 5.x
-- Node.js 20+
-- @inquirer/prompts (TUI)
-- Commander.js (CLI)
-- Vitest (测试)
+- 阿里云灵积平台提供的模型支持
+- 开源社区贡献者
 
-## 许可证
+---
 
-MIT
+**Happy Writing! 🎉**

package/dist/adapters/storageAdapter.d.ts

@@ -1,5 +1,5 @@
 import type { StoragePort, ProjectStoragePort } from '../core/ports.js';
-import type { NovelProject } from '../core/types.js';
+import type { NovelProject, GeneratedChapter, ChapterMeta, ChapterLoadOptions } from '../core/types.js';
 export declare class StorageAdapter implements StoragePort {
     writeFile(filePath: string, content: string): Promise<void>;
     readFile(filePath: string): Promise<string>;
@@ -9,8 +9,34 @@ export declare class StorageAdapter implements StoragePort {
 }
 export declare class ProjectStorageAdapter implements ProjectStoragePort {
     private storage;
+    /**
+     * 保存项目元数据（轻量级，不含章节正文）
+     */
     saveProject(project: NovelProject, basePath: string): Promise<void>;
-    loadProject(projectId: string, basePath: string): Promise<NovelProject | null>;
+    /**
+     * 增量保存单个章节
+     */
+    saveChapter(chapter: GeneratedChapter, basePath: string): Promise<void>;
+    /**
+     * 批量保存章节（用于首次生成）
+     */
+    saveChapters(chapters: GeneratedChapter[], basePath: string): Promise<void>;
+    /**
+     * 加载项目元数据（不含章节内容）
+     */
+    loadProject(basePath: string): Promise<NovelProject | null>;
+    /**
+     * 按需加载单个章节
+     */
+    loadChapter(basePath: string, volume: number, number: number): Promise<GeneratedChapter | null>;
+    /**
+     * 按需加载多个章节
+     */
+    loadChapters(basePath: string, options?: ChapterLoadOptions): Promise<GeneratedChapter[]>;
+    /**
+     * 从章节文件更新项目元数据
+     */
+    syncChapterMeta(basePath: string): Promise<ChapterMeta[]>;
     projectExists(projectId: string, basePath: string): Promise<boolean>;
     listProjects(basePath: string): Promise<string[]>;
     private generateRequirementsMarkdown;

package/dist/adapters/storageAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storageAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/storageAdapter.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAIrD,qBAAa,cAAe,YAAW,WAAW;IAC1C,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM3D,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI3C,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAS9C,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzC,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CASlE;AAED,qBAAa,qBAAsB,YAAW,kBAAkB;IAC9D,OAAO,CAAC,OAAO,CAAwB;IAEjC,WAAW,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BnE,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAU9E,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIpE,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAsBvD,OAAO,CAAC,4BAA4B;IAkCpC,OAAO,CAAC,qBAAqB;IAwC7B,OAAO,CAAC,uBAAuB;CA8BhC"}
+{"version":3,"file":"storageAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/storageAdapter.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAIxG,qBAAa,cAAe,YAAW,WAAW;IAC1C,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM3D,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI3C,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAS9C,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzC,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CASlE;AAiED,qBAAa,qBAAsB,YAAW,kBAAkB;IAC9D,OAAO,CAAC,OAAO,CAAwB;IAEvC;;OAEG;IACG,WAAW,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBzE;;OAEG;IACG,WAAW,CAAC,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM7E;;OAEG;IACG,YAAY,CAAC,QAAQ,EAAE,gBAAgB,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjF;;OAEG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAUjE;;OAEG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAUrG;;OAEG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IA6D/F;;OAEG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAsCzD,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIpE,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAsBvD,OAAO,CAAC,4BAA4B;IAkCpC,OAAO,CAAC,qBAAqB;IAwC7B,OAAO,CAAC,uBAAuB;CA8BhC"}