Skip to content

Commit a28ffe8

Browse files
oneMuggleoneMuggle
committed
refactor(hooks): 拆分 useGame 子模块以降低复杂度
根据大文件重构计划（`large-files-refactor-plan.md`），将多个超过500行的 God-Object 文件拆分为更小、职责更单一的模块。 本次提交实现了重构计划的第一阶段，主要包括： - **campusNSFW**: 将 `campusNSFWEngine.ts` 拆分为包含 desireStateMachine, bdsmSystem, exposureSystem 等多个子系统文件的 `campusNSFW/` 目录。 - **stateTransforms**: 将 `stateTransforms.ts` 中的纯函数提取到 `transforms/` 目录，包括 `npcNormalization`、`itemContainerMapping` 等。 - **storyState**: 将 `storyState.ts` 中的工厂和工具函数提取到 `state/` 目录。 - **eventTrigger**: 将 `eventTrigger.ts` 的实现拆分到 `eventTrigger/` 目录中。 - **narrativeGrammar**: 将 `narrativeGrammar.ts` 的实现拆分到 `narrativeGrammar/` 目录中。 旧的入口文件现在仅作为索引，重新导出新模块的接口，以确保向后兼容性。此举旨在提高代码的可维护性、可测试性，并为后续并行开发奠定基础。
1 parent 84cafbc commit a28ffe8

37 files changed

Lines changed: 4149 additions & 4938 deletions

‎docs/plans/2026-05-06_large-files-refactor-plan.md‎

Lines changed: 298 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,298 @@
1+
# 大文件重构计划
2+
3+
> 创建时间: 2026-05-06
4+
> 状态: 待审批
5+
6+
## 目标
7+
8+
找出项目中所有超过 500 行的大文件，提出具体的拆分重构方案，降低耦合度、提升可维护性。
9+
10+
---
11+
12+
## 1. 大文件清单（按行数排序）
13+
14+
### Tier 0: 严重（>2000 行）
15+
16+
| # | 文件 | 行数 | 职责 |
17+
|---|------|------|------|
18+
| 1 | `hooks/useGame.ts` | 2952 | 中央游戏状态管理 hook，231+ 内部函数，管理所有游戏子系统 |
19+
| 2 | `App.tsx` | 2115 | 根组件，50+ lazy 组件声明，30+ 模态状态，大量 inline callback |
20+
21+
### Tier 1: 重度（1000-2000 行）
22+
23+
| # | 文件 | 行数 | 职责 |
24+
|---|------|------|------|
25+
| 3 | `hooks/useGame/systemPromptBuilder.ts` | 1733 | AI 故事生成系统提示词组装 |
26+
| 4 | `hooks/useGame/campusNSFWEngine.ts` | 1601 | 校园 NSFW 引擎（欲望/后果/曝光/BDSM/小游戏/节日） |
27+
| 5 | `hooks/useGame/openingStoryWorkflow.ts` | 1466 | 开局故事生成流程 |
28+
| 6 | `hooks/useGame/stateTransforms.ts` | 1234 | 游戏状态归一化（NPC/环境/物品/装备/社交） |
29+
30+
### Tier 2: 显著（700-1000 行）
31+
32+
| # | 文件 | 行数 | 职责 |
33+
|---|------|------|------|
34+
| 7 | `hooks/useGame/storyState.ts` | 941 | 空白状态工厂函数 + 归一化函数 |
35+
| 8 | `hooks/useGame/sendWorkflow/index.ts` | 899 | 故事发送流程入口 |
36+
| 9 | `hooks/useGame/promptRuntime.ts` | 751 | Tavern 模式运行时提示词池 |
37+
| 10 | `hooks/useGame/sendWorkflow/responseProcessingPhase.ts` | 731 | 响应解析/变量生成/BDSM 集成/记忆写入 |
38+
| 11 | `hooks/useGame/npcContext.ts` | 690 | NPC 图片数据提取 + 系统提示词 NPC 上下文 |
39+
| 12 | `hooks/useGame/imagePresetWorkflow.ts` | 618 | 图片预设工作流 |
40+
41+
### Tier 3: 中度（500-600 行）
42+
43+
| # | 文件 | 行数 | 职责 |
44+
|---|------|------|------|
45+
| 13 | `hooks/useGame/narrativeGrammar.ts` | 584 | 叙事语法引擎 |
46+
| 14 | `hooks/useGame/eventTrigger.ts` | 578 | 事件触发引擎 |
47+
| 15 | `hooks/useGame/npcImageStateWorkflow.ts` | 551 | NPC 图片状态工作流 |
48+
49+
### Tier 4: 大型组件（>500 行，UI）
50+
51+
| # | 文件 | 行数 | 职责 |
52+
|---|------|------|------|
53+
| 16 | `components/features/Social/ImageManagerModal.tsx` | 3521 | **最大组件**：图片管理器模态 |
54+
| 17 | `components/features/Social/mobile/MobileImageManagerModal.tsx` | 3097 | 图片管理器移动端 |
55+
| 18 | `components/features/Settings/NovelDecompositionSettings.tsx` | 3038 | 小说分解设置 |
56+
| 19 | `components/features/Settings/ImageGenerationSettings.tsx` | 2205 | 图片生成设置 |
57+
| 20 | `components/features/NewGame/NewGameWizardContent.tsx` | 1809 | 新建游戏向导 |
58+
| 21 | `components/features/NewGame/useNewGameWizardState.ts` | 1156 | 新建游戏向导状态 |
59+
| 22 | `components/features/Settings/IntegratedModelSettings.tsx` | 1316 | AI 模型配置 |
60+
| 23 | `components/features/Chat/InputArea.tsx` | 930 | 聊天输入区 |
61+
| 24 | `components/features/Social/SocialModal.tsx` | 897 | 社交模态 |
62+
| 25 | `components/features/Social/MobileSocial.tsx` | 859 | 社交移动端 |
63+
| 26 | `components/features/Character/MobileCharacter.tsx` | 834 | 角色移动端 |
64+
| 27 | `components/features/Settings/ApiSettings.tsx` | 780 | API 设置 |
65+
| 28 | `components/features/Social/ImageManager/tabs/PresetsTab.tsx` | 770 | 预设标签页 |
66+
| 29 | `components/features/Settings/StorageManager.tsx` | 704 | 存储管理 |
67+
| 30 | `components/features/Settings/VisualSettings.tsx` | 699 | 视觉设置 |
68+
| 31 | `components/features/Memory/MemoryModal.tsx` | 698 | 记忆模态 |
69+
| 32 | `components/features/Character/CharacterModal.tsx` | 612 | 角色模态 |
70+
| 33 | `components/features/Settings/GameSettings.tsx` | 611 | 游戏设置 |
71+
| 34 | `components/layout/TopBar.tsx` | 568 | 顶部栏 |
72+
| 35 | `components/features/Chat/MessageRenderers.tsx` | 562 | 消息渲染器 |
73+
| 36 | `components/ui/Icons.tsx` | 557 | 图标库 |
74+
| 37 | `components/features/Chat/TurnItem.tsx` | 536 | 回合项 |
75+
| 38 | `components/features/Settings/TavernPresetSettings.tsx` | 535 | 酒馆预设设置 |
76+
| 39 | `components/features/Settings/NpcManager.tsx` | 520 | NPC 管理器 |
77+
78+
---
79+
80+
## 2. 具体拆分方案
81+
82+
### P1: `hooks/useGame.ts` (2952 → ~600 行) | 复杂度: 高
83+
84+
**提取方案：**
85+
86+
| 新文件 | 提取内容 | 预估行数 |
87+
|--------|----------|----------|
88+
| `hooks/useGame/tradeAndTravel.ts` | 旅行/交易相关 state 和 handler | ~150 |
89+
| `hooks/useGame/deviceSubsystem.ts` | 设备系统全部 state 和操作 | ~200 |
90+
| `hooks/useGame/memoryManagement.ts` | 记忆总结任务/队列/NPC 记忆 | ~250 |
91+
| `hooks/useGame/imageGenerationState.ts` | 图片生成队列/状态/懒加载 | ~300 |
92+
| `hooks/useGame/worldEvolutionState.ts` | 世界演变状态/refs | ~200 |
93+
| `hooks/useGame/callbacks.ts` | return 对象组装 | ~400 |
94+
95+
### P2: `App.tsx` (2115 → ~300 行) | 复杂度: 高
96+
97+
**提取方案：**
98+
99+
| 新文件 | 提取内容 | 预估行数 |
100+
|--------|----------|----------|
101+
| `components/app/ModalOrchestrator.tsx` | 模态状态 + 开关 handlers | ~200 |
102+
| `components/app/useAppCallbacks.ts` | inline callbacks 提取为 hook | ~350 |
103+
| `components/app/DesktopLayout.tsx` | 桌面端布局 JSX | ~400 |
104+
| `components/app/MobileLayout.tsx` | 移动端布局 JSX | ~350 |
105+
| `components/app/LazyComponents.ts` | 50+ lazy 组件声明 | ~80 |
106+
107+
### P3: `hooks/useGame/systemPromptBuilder.ts` (1733 → ~200 行) | 复杂度: 高
108+
109+
**提取方案：**
110+
111+
| 新文件 | 提取内容 |
112+
|--------|----------|
113+
| `hooks/useGame/promptAssembly/characterContext.ts` | 角色卡片、身份、人设 |
114+
| `hooks/useGame/promptAssembly/worldContext.ts` | 世界状态、环境、地图建筑 |
115+
| `hooks/useGame/promptAssembly/npcContextAssembly.ts` | NPC 上下文（在场/不在场、NSFW 卡片） |
116+
| `hooks/useGame/promptAssembly/memoryContext.ts` | 长/中期记忆组装 |
117+
| `hooks/useGame/promptAssembly/protocolDirectives.ts` | 输出协议、字数、免责声明、COT |
118+
| `hooks/useGame/promptAssembly/fandomContext.ts` | 境界/修炼体系、同人摘要 |
119+
120+
### P4: `hooks/useGame/campusNSFWEngine.ts` (1601 → ~200 行) | 复杂度: 中
121+
122+
**提取方案：**
123+
124+
| 新文件 | 提取内容 |
125+
|--------|----------|
126+
| `hooks/useGame/campusNSFW/desireStateMachine.ts` | 欲望状态机、关系轨道、亲密里程碑 |
127+
| `hooks/useGame/campusNSFW/consequenceSystem.ts` | 后果记录/应用/回滚 |
128+
| `hooks/useGame/campusNSFW/exposureSystem.ts` | 曝光状态、旁观者反应 |
129+
| `hooks/useGame/campusNSFW/bdsmSystem.ts` | BDSM 关系追踪、契约、阶段推进 |
130+
| `hooks/useGame/campusNSFW/boardGameSystem.ts` | 小游戏状态/机制 |
131+
| `hooks/useGame/campusNSFW/festivalSystem.ts` | 校园节日系统 |
132+
| `hooks/useGame/campusNSFW/types.ts` | 统一类型导出 |
133+
134+
### P5: `hooks/useGame/openingStoryWorkflow.ts` (1466 → ~200 行) | 复杂度: 中
135+
136+
**提取方案：**
137+
138+
| 新文件 | 提取内容 |
139+
|--------|----------|
140+
| `hooks/useGame/opening/worldEvolutionInit.ts` | 开局世界演变初始化 |
141+
| `hooks/useGame/opening/variableGenerationInit.ts` | 开局变量生成初始化 |
142+
| `hooks/useGame/opening/planningInit.ts` | 开局规划初始化 |
143+
| `hooks/useGame/opening/storyGeneration.ts` | 故事生成管线（流式/非流式） |
144+
145+
### P6: `hooks/useGame/stateTransforms.ts` (1234 → ~300 行) | 复杂度: 中
146+
147+
**提取方案：**
148+
149+
| 新文件 | 提取内容 |
150+
|--------|----------|
151+
| `hooks/useGame/transforms/npcNormalization.ts` | NPC 归一化 + 去重合并 (~600) |
152+
| `hooks/useGame/transforms/environmentNormalization.ts` | 环境归一化 |
153+
| `hooks/useGame/transforms/itemContainerMapping.ts` | 物品容器映射 |
154+
| `hooks/useGame/transforms/socialListNormalization.ts` | 社交列表归一化 |
155+
156+
### P7: `hooks/useGame/storyState.ts` (941 → ~200 行) | 复杂度: 低
157+
158+
**提取方案：**
159+
160+
| 新文件 | 提取内容 |
161+
|--------|----------|
162+
| `hooks/useGame/state/factoryFunctions.ts` | 空白状态工厂函数 |
163+
| `hooks/useGame/state/normalizationFunctions.ts` | 各类型归一化函数 |
164+
| `hooks/useGame/state/historyUtils.ts` | 历史裁剪/战斗清空 |
165+
166+
### P8: 组件拆分（3000+ 行）| 复杂度: 高
167+
168+
**ImageManagerModal.tsx (3521 行)：**
169+
170+
| 新文件 | 提取内容 |
171+
|--------|----------|
172+
| `hooks/useImageManagerModalState.ts` | 100+ state 声明提取为 hook |
173+
| `ImageManagerModal/TabsSection.tsx` | 6 个标签页内容 |
174+
| `ImageManagerModal/Overlays.tsx` | 图片查看器/手动确认/提示词展示 |
175+
| `ImageManagerModal/FilterSection.tsx` | 筛选/搜索栏 |
176+
177+
**NovelDecompositionSettings.tsx (3038 行)：**
178+
179+
已有 `@todo-replace` 注释，按计划拆分为：
180+
- `ApiConfigPanel.tsx` / `InjectionPanel.tsx` / `PreviewPanel.tsx` / `ImportExportPanel.tsx` / `SchedulerPanel.tsx` / `SplitPanel.tsx` / `DatasetManagerPanel.tsx`
181+
182+
**其他大型组件：**
183+
184+
每个设置类组件按 tab/panel 拆分子文件：
185+
- `ImageGenerationSettings.tsx` → `ModelPanel.tsx` / `ArtistPanel.tsx` / `AutomationPanel.tsx`
186+
- `IntegratedModelSettings.tsx` → 每个子配置一个 Panel
187+
- `NewGameWizardContent.tsx` → `CharacterCreation.tsx` / `WorldConfig.tsx` / `EraSelection.tsx` / `OpeningConfig.tsx`
188+
189+
---
190+
191+
## 3. 优先级排序
192+
193+
| 优先级 | 阶段 | 文件 | 原因 |
194+
|--------|------|------|------|
195+
| 1 | Phase 1 | campusNSFWEngine.ts | 独立领域，低风险，可并行 |
196+
| 2 | Phase 1 | stateTransforms.ts | 纯函数，无副作用，易测试 |
197+
| 3 | Phase 1 | storyState.ts | 工厂函数天然可分离 |
198+
| 4 | Phase 1 | narrativeGrammar.ts | 独立语法解析拆分 |
199+
| 5 | Phase 1 | eventTrigger.ts | 触发检查与生命周期分离 |
200+
| 6 | Phase 2 | openingStoryWorkflow.ts | 子阶段清晰 |
201+
| 7 | Phase 2 | systemPromptBuilder.ts | 最多被引用，拆分后解锁提示词相关开发 |
202+
| 8 | Phase 2 | promptRuntime.ts | 酒馆模式逻辑自包含 |
203+
| 9 | Phase 2 | responseProcessingPhase.ts | 子阶段提取 |
204+
| 10 | Phase 2 | npcContext.ts | 两个清晰职责 |
205+
| 11 | Phase 3 | 大型组件 (ImageManagerModal 等) | UI tab/panel 边界清晰 |
206+
| 12 | Phase 4 | App.tsx | 依赖 hook API 稳定 |
207+
| 13 | Phase 4 | hooks/useGame.ts | **最后做**，依赖所有子模块稳定 |
208+
209+
---
210+
211+
## 4. 阶段依赖关系
212+
213+
```
214+
Phase 1 (可并行):
215+
├── campusNSFWEngine.ts → campusNSFW/
216+
├── stateTransforms.ts → transforms/
217+
├── storyState.ts → state/
218+
├── narrativeGrammar.ts (独立拆分)
219+
└── eventTrigger.ts (独立拆分)
220+
221+
Phase 2 (依赖 Phase 1 稳定):
222+
├── openingStoryWorkflow.ts → opening/
223+
├── systemPromptBuilder.ts → promptAssembly/
224+
├── promptRuntime.ts → promptRuntime/
225+
├── responseProcessingPhase.ts 子提取
226+
└── npcContext.ts 拆分
227+
228+
Phase 3 (组件重构，与 hook 并行):
229+
├── ImageManagerModal.tsx → ImageManagerModal/
230+
├── NovelDecompositionSettings.tsx → NovelDecompositionSettings/
231+
├── ImageGenerationSettings.tsx → ImageGenerationSettings/
232+
├── IntegratedModelSettings.tsx 子面板
233+
├── NewGameWizardContent.tsx 子区域
234+
└── useNewGameWizardState.ts 子 hook
235+
236+
Phase 4 (最终，依赖 Phase 1-3):
237+
├── App.tsx → app/ (需稳定 hook API)
238+
└── hooks/useGame.ts → 子 hook (需所有 Phase 1-2 模块稳定)
239+
```
240+
241+
---
242+
243+
## 5. 风险评估
244+
245+
| 风险等级 | 文件 | 说明 |
246+
|----------|------|------|
247+
| **高** | `hooks/useGame.ts` | 200+ action 方法暴露给外部，提取需保证接口不变 |
248+
| **高** | `App.tsx` | callback 签名变化会导致所有模态运行时错误 |
249+
| **中** | `systemPromptBuilder.ts` | 返回结构变化影响 sendWorkflow，需保持类型一致 |
250+
| **中** | `openingStoryWorkflow.ts` | 影响新游戏流程，高可见性但边界清晰 |
251+
| **低** | `storyState.ts` | 纯工厂函数，零副作用 |
252+
| **低** | `stateTransforms.ts` | 纯归一化函数 |
253+
| **低** | 设置面板组件 | 纯 UI，不影响游戏逻辑 |
254+
255+
---
256+
257+
## 6. 实施步骤
258+
259+
- [ ] Phase 1: 独立模块拆分（5 个文件）
260+
- [ ] Phase 2: 提示词/工作流模块拆分（5 个文件）
261+
- [ ] Phase 3: 大型组件拆分（6+ 个组件）
262+
- [ ] Phase 4: 核心骨架精简（App.tsx + useGame.ts）
263+
264+
---
265+
266+
## 实施进度
267+
268+
> 每完成一个阶段后在此标注 `[x]` 并记录实际产出的文件和行数变化。
269+
270+
### Phase 1: 独立模块拆分
271+
272+
- [x] **campusNSFWEngine.ts** (1601 → 81 行 re-export)
273+
- 拆分为 `campusNSFW/` 子目录，7 个模块 + 1 个 barrel + 1 个 re-export 入口
274+
- 文件：constants.ts(90), desireStateMachine.ts(110), exposureSystem.ts(115), bdsmSystem.ts(90), boardGameSystem.ts(75), festivalSystem.ts(145), factoryFunctions.ts(77), convenienceFunctions.ts(42), forumIntegration.ts(23), bdsmTaskEngine.ts(38), index.ts(81)
275+
- 总代码行数：~886 行（原 1601 行，减少 44%）
276+
- TypeScript 编译：零新增错误
277+
278+
- [x] **stateTransforms.ts** (1234 → 8 行 re-export)
279+
- 拆分为 `transforms/` 子目录，4 个模块
280+
- 文件：environmentNormalization.ts(92), itemContainerMapping.ts(320), npcNormalization.ts(494), socialListNormalization.ts(8)
281+
- 总代码行数：~914 行（原 1234 行，减少 26%）
282+
- TypeScript 编译：零新增错误
283+
284+
- [x] **storyState.ts** (941 → 20 行 re-export)
285+
- 拆分为 `state/` 子目录，3 个模块
286+
- 文件：factories.ts(221), planningNormalizers.ts(142), historyUtils.ts(101)
287+
- 总代码行数：~464 行（原 941 行，减少 51%）
288+
- TypeScript 编译：零新增错误
289+
290+
- [x] **narrativeGrammar.ts** (585 → 6 行 re-export)
291+
- 拆分为 `narrativeGrammar/` 子目录，4 个模块
292+
- 文件：parsers.ts(提取/解析), extractors.ts(提取), validators.ts(验证), normalizers.ts(规范化)
293+
- TypeScript 编译：零新增错误
294+
295+
- [x] **eventTrigger.ts** (579 → 8 行 re-export)
296+
- 拆分为 `eventTrigger/` 子目录，6 个模块
297+
- 文件：core.ts(核心), promptAndParse.ts(提示词与解析), stateManagement.ts(状态管理), factories.ts(工厂), v2Enhanced.ts(增强), utilities.ts(工具)
298+
- TypeScript 编译：零新增错误（eventTrigger.test.ts 缺少 Jest 类型为已有问题）

0 commit comments

Comments
 (0)