@zb2947244682/supernovel 1.1.0 → 1.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (94) hide show
  1. package/README.md +246 -199
  2. package/dist/adapters/storageAdapter.d.ts +28 -2
  3. package/dist/adapters/storageAdapter.d.ts.map +1 -1
  4. package/dist/adapters/storageAdapter.js +188 -10
  5. package/dist/adapters/storageAdapter.js.map +1 -1
  6. package/dist/bus/commands.d.ts +17 -5
  7. package/dist/bus/commands.d.ts.map +1 -1
  8. package/dist/bus/commands.js +10 -6
  9. package/dist/bus/commands.js.map +1 -1
  10. package/dist/bus/dispatcher.d.ts.map +1 -1
  11. package/dist/bus/dispatcher.js +392 -36
  12. package/dist/bus/dispatcher.js.map +1 -1
  13. package/dist/core/index.d.ts +7 -0
  14. package/dist/core/index.d.ts.map +1 -1
  15. package/dist/core/index.js +7 -0
  16. package/dist/core/index.js.map +1 -1
  17. package/dist/core/ports.d.ts +7 -2
  18. package/dist/core/ports.d.ts.map +1 -1
  19. package/dist/core/rag/consistency.d.ts +41 -0
  20. package/dist/core/rag/consistency.d.ts.map +1 -1
  21. package/dist/core/rag/consistency.js +565 -15
  22. package/dist/core/rag/consistency.js.map +1 -1
  23. package/dist/core/rag/contextAssembler.d.ts +2 -0
  24. package/dist/core/rag/contextAssembler.d.ts.map +1 -1
  25. package/dist/core/rag/contextAssembler.js +72 -61
  26. package/dist/core/rag/contextAssembler.js.map +1 -1
  27. package/dist/core/rag/fixApplier.d.ts +38 -0
  28. package/dist/core/rag/fixApplier.d.ts.map +1 -0
  29. package/dist/core/rag/fixApplier.js +154 -0
  30. package/dist/core/rag/fixApplier.js.map +1 -0
  31. package/dist/core/rag/index.d.ts +1 -0
  32. package/dist/core/rag/index.d.ts.map +1 -1
  33. package/dist/core/rag/index.js +1 -0
  34. package/dist/core/rag/index.js.map +1 -1
  35. package/dist/core/rag/types.d.ts +38 -0
  36. package/dist/core/rag/types.d.ts.map +1 -1
  37. package/dist/core/tokenBudget.d.ts +25 -0
  38. package/dist/core/tokenBudget.d.ts.map +1 -0
  39. package/dist/core/tokenBudget.js +89 -0
  40. package/dist/core/tokenBudget.js.map +1 -0
  41. package/dist/core/types.d.ts +102 -2
  42. package/dist/core/types.d.ts.map +1 -1
  43. package/dist/core/usecases/analyzeImpact.d.ts +15 -0
  44. package/dist/core/usecases/analyzeImpact.d.ts.map +1 -0
  45. package/dist/core/usecases/analyzeImpact.js +61 -0
  46. package/dist/core/usecases/analyzeImpact.js.map +1 -0
  47. package/dist/core/usecases/generateArtifacts.d.ts +6 -0
  48. package/dist/core/usecases/generateArtifacts.d.ts.map +1 -0
  49. package/dist/core/usecases/generateArtifacts.js +67 -0
  50. package/dist/core/usecases/generateArtifacts.js.map +1 -0
  51. package/dist/core/usecases/generateChapter.d.ts +4 -0
  52. package/dist/core/usecases/generateChapter.d.ts.map +1 -1
  53. package/dist/core/usecases/generateChapter.js +5 -4
  54. package/dist/core/usecases/generateChapter.js.map +1 -1
  55. package/dist/core/usecases/generateChapterRAG.d.ts +4 -0
  56. package/dist/core/usecases/generateChapterRAG.d.ts.map +1 -1
  57. package/dist/core/usecases/generateChapterRAG.js +5 -5
  58. package/dist/core/usecases/generateChapterRAG.js.map +1 -1
  59. package/dist/core/usecases/orchestrateChapterGeneration.d.ts +119 -0
  60. package/dist/core/usecases/orchestrateChapterGeneration.d.ts.map +1 -0
  61. package/dist/core/usecases/orchestrateChapterGeneration.js +235 -0
  62. package/dist/core/usecases/orchestrateChapterGeneration.js.map +1 -0
  63. package/dist/core/usecases/parseRequirements.d.ts.map +1 -1
  64. package/dist/core/usecases/parseRequirements.js +6 -0
  65. package/dist/core/usecases/parseRequirements.js.map +1 -1
  66. package/dist/core/usecases/polishStyle.d.ts +20 -0
  67. package/dist/core/usecases/polishStyle.d.ts.map +1 -0
  68. package/dist/core/usecases/polishStyle.js +251 -0
  69. package/dist/core/usecases/polishStyle.js.map +1 -0
  70. package/dist/core/usecases/validateNovel.d.ts +37 -1
  71. package/dist/core/usecases/validateNovel.d.ts.map +1 -1
  72. package/dist/core/usecases/validateNovel.js +95 -23
  73. package/dist/core/usecases/validateNovel.js.map +1 -1
  74. package/dist/core/usecases/validateOutline.d.ts +11 -0
  75. package/dist/core/usecases/validateOutline.d.ts.map +1 -0
  76. package/dist/core/usecases/validateOutline.js +64 -0
  77. package/dist/core/usecases/validateOutline.js.map +1 -0
  78. package/dist/core/usecases/validateWorld.d.ts +11 -0
  79. package/dist/core/usecases/validateWorld.d.ts.map +1 -0
  80. package/dist/core/usecases/validateWorld.js +74 -0
  81. package/dist/core/usecases/validateWorld.js.map +1 -0
  82. package/dist/shell/bin.d.ts +3 -0
  83. package/dist/shell/bin.d.ts.map +1 -0
  84. package/dist/shell/bin.js +20 -0
  85. package/dist/shell/bin.js.map +1 -0
  86. package/dist/shell/cli.d.ts +1 -1
  87. package/dist/shell/cli.d.ts.map +1 -1
  88. package/dist/shell/cli.js +75 -118
  89. package/dist/shell/cli.js.map +1 -1
  90. package/dist/shell/index.d.ts +1 -1
  91. package/dist/shell/index.d.ts.map +1 -1
  92. package/dist/shell/index.js +12 -6
  93. package/dist/shell/index.js.map +1 -1
  94. package/package.json +4 -3
package/README.md CHANGED
@@ -1,253 +1,206 @@
1
1
  # SuperNovel 📚
2
2
 
3
- AI-powered novel generation system with Core-Shell architecture and RAG for long-form consistency.
3
+ AI-powered novel generation system with Core-Shell architecture, RAG for long-form consistency, and **automatic error correction**.
4
4
 
5
- 一个基于 Core-Shell 架构的 AI 长篇小说生成系统,支持向量检索和知识图谱,确保几百章长篇小说的一致性。
5
+ 基于 Core-Shell 架构的 AI 长篇小说生成系统,支持 RAG 长文本一致性保障,**自动检测并修复世界观冲突**,确保交付完整无错误的小说。
6
6
 
7
7
  ---
8
8
 
9
- ## 🚀 快速开始(小白教程)
9
+ ## 核心特性
10
10
 
11
- ### 第一步:安装 Node.js
11
+ | 特性 | 说明 |
12
+ |------|------|
13
+ | 🏗️ **Core-Shell 架构** | 纯函数 Core + Effect 模式 + Bus 协调,代码清晰可维护 |
14
+ | 🧠 **RAG 长文本一致性** | 向量存储 + 知识图谱 + 分层摘要,确保数百章长篇小说世界观一致 |
15
+ | 🔧 **强制自动修复** | 检测世界观违规 → 生成 TextEdit 修复 → 重新检查,直到无错误或抛出异常 |
16
+ | 📂 **分层存储** | project.json 轻量级元数据(<50KB)+ chapters/ 独立文件按需加载 |
17
+ | 🔄 **断点续传** | 支持中断后从上次位置继续生成 |
18
+ | 📊 **一致性检查** | 角色状态、世界观规则、时间线、情节连续性四重验证 |
12
19
 
13
- 1. 访问 [nodejs.org](https://nodejs.org)
14
- 2. 下载 **LTS** 版本(推荐 20.x 或更高)
15
- 3. 双击安装,一直点"下一步"即可
16
- 4. 验证安装:打开命令提示符(CMD)或 PowerShell,输入:
17
- ```bash
18
- node --version
19
- npm --version
20
- ```
21
-
22
- ### 第二步:获取 AI API 密钥
23
-
24
- 本工具需要 AI 模型来生成小说,支持以下服务商:
25
-
26
- #### 选项 A:阿里云灵积(推荐国内用户)
27
- 1. 访问 [dashscope.aliyun.com](https://dashscope.aliyun.com)
28
- 2. 注册/登录账号
29
- 3. 创建 API Key
30
- 4. 推荐模型:`qwen3.5-flash`(速度快、价格便宜)
20
+ ---
31
21
 
32
- #### 选项 B:OpenAI(需要翻墙)
33
- 1. 访问 [platform.openai.com](https://platform.openai.com)
34
- 2. 创建 API Key
35
- 3. 推荐模型:`gpt-4o-mini` 或 `gpt-4o`
22
+ ## 🚀 快速开始
36
23
 
37
- #### 选项 C:其他平台
38
- - **OpenRouter**: 支持多种模型聚合
39
- - **Anthropic Claude**: 适合长文本生成
24
+ ### 环境要求
40
25
 
41
- ### 第三步:运行 SuperNovel
26
+ - **Node.js 20+**
27
+ - **AI API 密钥**(支持阿里云、OpenAI、OpenRouter 等)
42
28
 
43
- 打开命令提示符,输入以下命令:
29
+ ### 安装与初始化
44
30
 
45
31
  ```bash
46
32
  # 使用 npx 直接运行(无需安装)
47
- npx @zb2947244682/supernovel
48
- ```
33
+ npx @zb2947244682/supernovel init
49
34
 
50
- ### 第四步:初始化配置
35
+ # 或全局安装
36
+ npm install -g @zb2947244682/supernovel
37
+ supernovel init
38
+ ```
51
39
 
52
- 第一次运行会提示初始化,选择你的 AI 服务商并输入 API Key:
40
+ 初始化后编辑配置文件,添加你的 API 密钥:
53
41
 
54
42
  ```bash
55
- # 或者在 D:\Novel 目录下运行初始化
56
- mkdir D:\Novel
57
- cd D:\Novel
58
- npx @zb2947244682/supernovel init
43
+ # Windows: C:\Users\你的用户名\.supernovel\config.json
44
+ # 或项目目录下的 config.json
45
+ {
46
+ "ai": {
47
+ "provider": "custom",
48
+ "baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
49
+ "apiKey": "你的API密钥",
50
+ "model": "qwen3.5-flash",
51
+ "temperature": 0.7,
52
+ "maxTokens": 32000
53
+ }
54
+ }
59
55
  ```
60
56
 
61
- 这将创建:
62
- - `D:\Novel\config.json` - AI 配置
63
- - `D:\Novel\draft\` - 小说存放目录
64
- - `D:\Novel\logs\` - 日志目录
65
-
66
- ### 第五步:生成你的第一部小说
57
+ ### 生成小说
67
58
 
68
- #### 方式一:TUI 交互界面(推荐新手)
59
+ #### 方式一:TUI 交互界面(推荐)
69
60
 
70
61
  ```bash
71
62
  npx @zb2947244682/supernovel
72
63
  ```
73
64
 
74
- 然后按提示选择:
75
- 1. 🏗️ 生成小说框架 → 输入你的创意
76
- 2. 📝 生成章节内容 → 选择刚创建的项目
77
- 3. 等待 AI 生成完成
65
+ 按菜单提示:
66
+ 1. 🏗️ 生成小说框架 → 输入创意描述
67
+ 2. 📝 生成章节内容 → 选择项目开始生成
68
+ 3. 系统自动检查并修复世界观冲突
78
69
 
79
- #### 方式二:命令行(适合高级用户)
70
+ #### 方式二:CLI 命令行
80
71
 
81
72
  ```bash
82
73
  # 1. 生成小说框架
83
74
  cd D:\Novel
84
- npx @zb2947244682/supernovel framework "一个关于程序员穿越到异世界的故事" --name my-first-novel
85
-
86
- # 2. 生成所有章节
87
- npx @zb2947244682/supernovel chapters my-first-novel
88
- ```
75
+ npx @zb2947244682/supernovel framework "一个程序员穿越到魔法世界的故事" --name my-novel
89
76
 
90
- ### 第六步:查看成果
91
-
92
- 生成完成后,在 `D:\Novel\draft\你的项目名\` 目录下可以看到:
93
-
94
- ```
95
- my-first-novel/
96
- ├── project.json # 项目主文件(包含所有数据)
97
- ├── requirements.md # 需求文档
98
- ├── world.md # 世界观设定
99
- ├── outline.md # 小说大纲
100
- └── chapters/ # 章节文件
101
- ├── chapter-1-1.md
102
- ├── chapter-1-2.md
103
- ├── chapter-1-3.md
104
- └── ...
77
+ # 2. 生成所有章节(含自动一致性检查和修复)
78
+ npx @zb2947244682/supernovel chapters my-novel
105
79
  ```
106
80
 
107
- 用任何文本编辑器(如记事本、VS Code)打开 `.md` 文件即可阅读。
108
-
109
81
  ---
110
82
 
111
- ## 📖 完整命令参考
112
-
113
- ### 全局安装(可选)
83
+ ## 📂 项目结构
114
84
 
115
- 如果你不想每次都输入 `npx`,可以全局安装:
85
+ ### 分层存储架构
116
86
 
117
- ```bash
118
- npm install -g @zb2947244682/supernovel
119
-
120
- # 之后直接使用
121
- supernovel
122
- # 或简写
123
- sn
124
87
  ```
125
-
126
- ### 所有命令
127
-
128
- ```bash
129
- # 初始化配置
130
- supernovel init
131
-
132
- # 测试 AI 连接
133
- supernovel test
134
-
135
- # 生成小说框架
136
- supernovel framework "你的创意描述" --name 项目名称
137
-
138
- # 生成章节
139
- supernovel chapters 项目名称
140
-
141
- # 查看帮助
142
- supernovel --help
88
+ draft/my-novel/
89
+ ├── project.json # 轻量级元数据 (~20KB)
90
+ │ ├── requirements # 需求设定
91
+ │ ├── worldState # 世界观、角色、规则
92
+ │ ├── outline # 大纲结构
93
+ │ └── chapterMeta[] # 章节元数据索引
94
+ ├── chapters/ # 章节正文独立存储
95
+ │ ├── chapter-1-1.md
96
+ │ ├── chapter-1-2.md
97
+ │ └── ...
98
+ ├── requirements.md # 需求文档(导出用)
99
+ ├── world.md # 世界观文档(导出用)
100
+ └── outline.md # 大纲文档(导出用)
143
101
  ```
144
102
 
145
- ---
103
+ ### 章节文件格式
146
104
 
147
- ## ⚙️ 配置文件详解
105
+ ```markdown
106
+ ---
107
+ id: ch_1_1
108
+ volume: 1
109
+ number: 1
110
+ wordCount: 3256
111
+ ---
148
112
 
149
- 编辑 `D:\Novel\config.json`:
113
+ # 第一章标题
150
114
 
151
- ```json
152
- {
153
- "ai": {
154
- "provider": "custom",
155
- "baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
156
- "apiKey": "你的API密钥",
157
- "model": "qwen3.5-flash",
158
- "temperature": 0.7,
159
- "maxTokens": 8000
160
- }
161
- }
115
+ 章节正文内容...
162
116
  ```
163
117
 
164
- ### 参数说明
165
-
166
- | 参数 | 说明 | 推荐值 |
167
- |------|------|--------|
168
- | `provider` | AI 服务商类型 | `custom` / `openai` / `anthropic` |
169
- | `baseURL` | API 地址 | 根据服务商填写 |
170
- | `apiKey` | 你的 API 密钥 | 从服务商获取 |
171
- | `model` | 模型名称 | `qwen3.5-flash` / `gpt-4o` |
172
- | `temperature` | 创造性(0-2) | 0.7(平衡)|
173
- | `maxTokens` | 单次最大输出 | 8000(越大越不容易截断)|
174
-
175
118
  ---
176
119
 
177
- ## 🎯 创意描述技巧
120
+ ## 🔧 强制自动修复机制
178
121
 
179
- 好的创意描述会让 AI 生成更精彩的小说:
122
+ SuperNovel 的核心目标是**交付完整无错误的小说**。为此,系统实现了强制自动修复机制:
180
123
 
181
- ### ✅ 好的示例
124
+ ### 修复流程
182
125
 
183
126
  ```
184
- 异世界治愈奇幻小说,讲述一位现代医生穿越到魔法世界,
185
- 用医学知识解决魔法无法治愈的疾病。
186
- 主题是治愈与救赎,风格温暖治愈,适合全年龄阅读。
127
+ 生成章节 → 一致性检查 → 发现问题?
128
+
129
+ ┌─────────────────┴─────────────────┐
130
+ ↓ ↓
131
+ 无问题 有问题
132
+ ↓ ↓
133
+ 保存章节 生成 TextEdit 修复
134
+ ↓ ↓
135
+ 应用修复
136
+
137
+ 重新检查(最多3轮)
138
+
139
+ ┌─────────────────┴─────────────────┐
140
+ ↓ ↓
141
+ 无问题 仍有问题
142
+ ↓ ↓
143
+ 保存章节 不可修复?→ 抛出异常
144
+ 可修复?→ 继续修复
187
145
  ```
188
146
 
147
+ ### 世界观规则冲突自动修复示例
148
+
149
+ **原始内容(违规):**
189
150
  ```
190
- 科幻悬疑小说,主角发现自己生活在一个虚拟现实中,
191
- 每次死亡都会回到起点,但保留记忆。
192
- 需要解开这个世界的真相才能逃脱。
151
+ 凯伦感觉魔力已经完全耗尽,却依然举起法杖,强行释放了一个火球术。
193
152
  ```
194
153
 
195
- ### ❌ 避免的描述
196
-
154
+ **自动修复后:**
197
155
  ```
198
- 写个小说 # 太简单
199
- 玄幻小说 # 太笼统
200
- 类似斗破苍穹的小说 # 涉及版权作品
156
+ 凯伦感觉魔力已经完全耗尽,试图释放火球术却失败了,只能咬牙冲上去近身肉搏。
201
157
  ```
202
158
 
203
- ---
204
-
205
- ## 🔧 常见问题
206
-
207
- ### Q1: 提示 "未找到配置文件"
208
- **解决**: 先运行 `supernovel init` 初始化
159
+ ### 修复策略
209
160
 
210
- ### Q2: API 报错 401
211
- **解决**: API Key 不正确,检查 config.json 中的 apiKey
161
+ | 违规类型 | 修复策略 |
162
+ |----------|----------|
163
+ | 魔力/能量耗尽后施法 | 改为物理行动("只能咬牙冲上去近身肉搏") |
164
+ | 等级限制突破 | 弱化行为强度("强行"→"尝试","瞬间"→"艰难地") |
165
+ | 物理法则冲突(如无火药世界出现枪) | 替换为等价魔法元素("枪"→"弩箭","火药"→"炼金爆炸物") |
166
+ | 角色能力无解释 | 在章节开头添加能力获得的情节铺垫 |
212
167
 
213
- ### Q3: 生成的 JSON 解析失败
214
- **解决**: 增加 `maxTokens` 到 8000 或更高,避免响应被截断
168
+ ### 严格保证
215
169
 
216
- ### Q4: 章节的 volume 显示 undefined
217
- **解决**: 已修复,请更新到最新版本
218
-
219
- ### Q5: 如何修改已生成的大纲?
220
- **解决**: 直接编辑 `outline.md` 文件,然后重新生成章节
221
-
222
- ### Q6: 支持生成多少章?
223
- **解决**: 理论上无限制。3章后自动启用 RAG(检索增强生成),确保长文本一致性
170
+ - 所有可修复问题自动修复
171
+ - ✅ 修复后重新检查确认无错误
172
+ - ✅ 不可修复的错误抛出异常,不会交付错误内容
224
173
 
225
174
  ---
226
175
 
227
- ## 🏗️ 架构设计
176
+ ## 🏗️ 系统架构
228
177
 
229
- 项目采用 **Core-Shell 架构**:
178
+ ### Core-Shell 架构
230
179
 
231
180
  ```
232
181
  ┌─────────────────────────────────────────────────────────┐
233
182
  │ Shell 层 (CLI / TUI) │
234
- │ - 用户交互界面
183
+ │ - 用户交互界面、命令解析
235
184
  └─────────────────────────────────────────────────────────┘
236
185
 
237
186
  ┌─────────────────────────────────────────────────────────┐
238
- │ Bus 层 (Command Dispatcher)
187
+ │ Bus 层 (Command Dispatcher / Effect Runner)
239
188
  │ - 命令分发、Effect 执行、工作流协调 │
189
+ │ - 强制修复循环实现 │
240
190
  └─────────────────────────────────────────────────────────┘
241
191
 
242
192
  ┌─────────────────────────────────────────────────────────┐
243
193
  │ Core 层 (纯函数业务逻辑) │
244
- │ - UseCases: generateWorld, generateOutline, etc.
245
- │ - Effects: 声明式副作用
194
+ │ - UseCases: parseRequirements, generateWorld, etc.
195
+ │ - Effects: AI_CHAT, SAVE_FILE, VALIDATE_CHAPTER
196
+ │ - RAG: VectorStore, KnowledgeGraph, ConsistencyChecker │
246
197
  └─────────────────────────────────────────────────────────┘
247
198
 
248
199
  ┌─────────────────────────────────────────────────────────┐
249
200
  │ Adapters 层 (AI / Storage / Logger) │
250
- │ - AI 适配器、文件存储、日志系统
201
+ │ - AI 适配器(支持多提供商)
202
+ │ - 分层存储(project.json + chapters/) │
203
+ │ - 日志系统 │
251
204
  └─────────────────────────────────────────────────────────┘
252
205
  ```
253
206
 
@@ -259,57 +212,149 @@ supernovel --help
259
212
  ├─────────────────────────────────────────────────────────┤
260
213
  │ 1. 向量存储 (Vector Store) │
261
214
  │ - 章节语义嵌入、相似度检索 │
215
+ │ - 支持上下文召回 │
262
216
  ├─────────────────────────────────────────────────────────┤
263
217
  │ 2. 知识图谱 (Knowledge Graph) │
264
- │ - 实体、关系、事件追踪
218
+ │ - 实体追踪(角色、地点、物品)
219
+ │ - 关系网络、事件追踪 │
265
220
  ├─────────────────────────────────────────────────────────┤
266
221
  │ 3. 分层摘要 (Hierarchical Summaries) │
267
- │ - 全书章 三级摘要体系
222
+ │ - 全书摘要卷摘要章摘要
223
+ │ - 动态更新机制 │
268
224
  ├─────────────────────────────────────────────────────────┤
269
- │ 4. 一致性检查 (Consistency Checker)
270
- │ - 角色、世界观、时间线验证
225
+ │ 4. 一致性检查器 (Consistency Checker)
226
+ │ - 角色一致性:能力变化需有情节铺垫
227
+ │ - 世界观规则:强制修复所有冲突 │
228
+ │ - 时间线连续性:前置事件检查 │
229
+ │ - 情节连续性:伏笔回收、情节推进 │
271
230
  └─────────────────────────────────────────────────────────┘
272
231
  ```
273
232
 
274
233
  ---
275
234
 
276
- ## 💡 高级用法
235
+ ## 📖 命令参考
236
+
237
+ ```bash
238
+ # 初始化配置
239
+ supernovel init
277
240
 
278
- ### 自定义存储路径
241
+ # 测试 AI 连接
242
+ supernovel test
279
243
 
280
- 设置环境变量:
244
+ # 生成小说框架
245
+ supernovel framework "创意描述" --name <项目名称>
281
246
 
282
- ```bash
283
- # Windows PowerShell
284
- $env:SUPERNOVEL_HOME = "D:\MyNovels"
247
+ # 生成所有章节(含自动修复)
248
+ supernovel chapters <项目名称>
285
249
 
286
- # Windows CMD
287
- set SUPERNOVEL_HOME=D:\MyNovels
250
+ # 查看帮助
251
+ supernovel --help
288
252
  ```
289
253
 
290
- ### 批量生成多个项目
254
+ ### 配置参数
255
+
256
+ | 参数 | 说明 | 推荐值 |
257
+ |------|------|--------|
258
+ | `provider` | AI 服务商 | `custom` / `openai` / `anthropic` / `openrouter` |
259
+ | `baseURL` | API 基础地址 | 根据服务商填写 |
260
+ | `apiKey` | API 密钥 | 从服务商获取 |
261
+ | `model` | 模型名称 | `qwen3.5-flash` / `gpt-4o-mini` / `gpt-4o` |
262
+ | `temperature` | 创造性 (0-2) | 0.7 |
263
+ | `maxTokens` | 最大输出 token | 32000(避免截断) |
264
+
265
+ ---
266
+
267
+ ## 🧪 开发与测试
291
268
 
292
269
  ```bash
293
- # 创建批处理脚本 generate.bat
294
- @echo off
295
- supernovel framework "创意1" --name novel1
296
- supernovel framework "创意2" --name novel2
297
- supernovel chapters novel1
298
- supernovel chapters novel2
270
+ # 克隆项目
271
+ git clone https://github.com/username/supernovel.git
272
+ cd supernovel
273
+
274
+ # 安装依赖
275
+ npm install
276
+
277
+ # 构建
278
+ npm run build
279
+
280
+ # 开发模式
281
+ npm run dev
282
+
283
+ # 运行测试
284
+ npm test
285
+
286
+ # 运行核心测试
287
+ npm run test:core
288
+
289
+ # 运行端到端测试
290
+ npm run test:e2e
299
291
  ```
300
292
 
293
+ ### 测试覆盖
294
+
295
+ - ✅ 分层存储(project.json + chapters/)
296
+ - ✅ 按需加载(loadChapters with limit/offset)
297
+ - ✅ TextEdit 修复应用
298
+ - ✅ 多轮修复循环
299
+ - ✅ 世界观规则冲突检测与修复
300
+
301
+ ---
302
+
303
+ ## 🎯 创意描述技巧
304
+
305
+ ### 好的示例
306
+
307
+ ```
308
+ 异世界治愈奇幻小说,讲述一位现代医生穿越到魔法世界,
309
+ 用医学知识解决魔法无法治愈的疾病。
310
+ 主题是治愈与救赎,风格温暖治愈,适合全年龄阅读。
311
+ 世界观规则:魔力是有限的资源,耗尽后无法施法。
312
+ ```
313
+
314
+ ```
315
+ 科幻悬疑小说,主角发现自己生活在一个虚拟现实中,
316
+ 每次死亡都会回到起点,但保留记忆。
317
+ 需要解开这个世界的真相才能逃脱。
318
+ 禁止元素:超自然力量、系统外援助
319
+ ```
320
+
321
+ ### 避免的描述
322
+
323
+ ```
324
+ 写个小说 # 太简单
325
+ 玄幻小说 # 太笼统
326
+ 类似XX小说 # 涉及版权
327
+ ```
328
+
329
+ ---
330
+
331
+ ## 🔍 常见问题
332
+
333
+ ### Q: 生成的 JSON 解析失败?
334
+ **解决**: 增加 `maxTokens` 到 32000,避免响应被截断
335
+
336
+ ### Q: 世界观规则冲突是什么意思?
337
+ **解决**: 系统会自动检测并修复。例如规则设定"魔力耗尽后无法施法",如果AI生成了"魔力耗尽后依然施法",系统会自动修复为符合规则的描述。
338
+
339
+ ### Q: 支持生成多少章?
340
+ **解决**: 理论上无限制。3章后自动启用 RAG(检索增强生成),确保长文本一致性。每5章自动保存进度元数据。
341
+
342
+ ### Q: 如何修改已生成的大纲?
343
+ **解决**: 直接编辑 `outline.md` 文件,然后重新运行 `supernovel chapters <项目名>`
344
+
345
+ ### Q: 如何中断后继续生成?
346
+ **解决**: 系统支持断点续传。直接重新运行章节生成命令,会从上次中断的章节继续。
347
+
301
348
  ---
302
349
 
303
350
  ## 📄 导出格式
304
351
 
305
- 目前支持:
306
- - **Markdown** (`.md`) - 默认格式,适合阅读
307
- - **项目 JSON** (`.json`) - 包含完整数据,可重新导入
352
+ - **Markdown** (`.md`) - 默认格式,适合阅读和进一步编辑
353
+ - **项目 JSON** (`.json`) - 包含完整元数据
308
354
 
309
- 未来计划:
355
+ 计划中:
310
356
  - EPUB 电子书格式
311
357
  - PDF 格式
312
- - Word 文档
313
358
 
314
359
  ---
315
360
 
@@ -318,18 +363,20 @@ supernovel chapters novel2
318
363
  欢迎提交 Issue 和 PR!
319
364
 
320
365
  ```bash
321
- # 克隆项目
322
- git clone https://github.com/username/supernovel.git
366
+ # Fork 并克隆
367
+ git clone https://github.com/your-username/supernovel.git
323
368
  cd supernovel
324
369
 
325
- # 安装依赖
326
- npm install
370
+ # 创建分支
371
+ git checkout -b feature/your-feature
327
372
 
328
- # 开发模式
329
- npm run dev
373
+ # 提交更改
374
+ git commit -am "Add some feature"
330
375
 
331
- # 运行测试
332
- npm test
376
+ # 推送
377
+ git push origin feature/your-feature
378
+
379
+ # 创建 Pull Request
333
380
  ```
334
381
 
335
382
  ---
@@ -343,7 +390,7 @@ MIT License
343
390
  ## 🙏 致谢
344
391
 
345
392
  - 阿里云灵积平台提供的模型支持
346
- - 开源社区的贡献者们
393
+ - 开源社区贡献者
347
394
 
348
395
  ---
349
396
 
@@ -1,5 +1,5 @@
1
1
  import type { StoragePort, ProjectStoragePort } from '../core/ports.js';
2
- import type { NovelProject } from '../core/types.js';
2
+ import type { NovelProject, GeneratedChapter, ChapterMeta, ChapterLoadOptions } from '../core/types.js';
3
3
  export declare class StorageAdapter implements StoragePort {
4
4
  writeFile(filePath: string, content: string): Promise<void>;
5
5
  readFile(filePath: string): Promise<string>;
@@ -9,8 +9,34 @@ export declare class StorageAdapter implements StoragePort {
9
9
  }
10
10
  export declare class ProjectStorageAdapter implements ProjectStoragePort {
11
11
  private storage;
12
+ /**
13
+ * 保存项目元数据(轻量级,不含章节正文)
14
+ */
12
15
  saveProject(project: NovelProject, basePath: string): Promise<void>;
13
- loadProject(projectId: string, basePath: string): Promise<NovelProject | null>;
16
+ /**
17
+ * 增量保存单个章节
18
+ */
19
+ saveChapter(chapter: GeneratedChapter, basePath: string): Promise<void>;
20
+ /**
21
+ * 批量保存章节(用于首次生成)
22
+ */
23
+ saveChapters(chapters: GeneratedChapter[], basePath: string): Promise<void>;
24
+ /**
25
+ * 加载项目元数据(不含章节内容)
26
+ */
27
+ loadProject(basePath: string): Promise<NovelProject | null>;
28
+ /**
29
+ * 按需加载单个章节
30
+ */
31
+ loadChapter(basePath: string, volume: number, number: number): Promise<GeneratedChapter | null>;
32
+ /**
33
+ * 按需加载多个章节
34
+ */
35
+ loadChapters(basePath: string, options?: ChapterLoadOptions): Promise<GeneratedChapter[]>;
36
+ /**
37
+ * 从章节文件更新项目元数据
38
+ */
39
+ syncChapterMeta(basePath: string): Promise<ChapterMeta[]>;
14
40
  projectExists(projectId: string, basePath: string): Promise<boolean>;
15
41
  listProjects(basePath: string): Promise<string[]>;
16
42
  private generateRequirementsMarkdown;
@@ -1 +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"}
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,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"}