# RPG 脚本中文注释补充进度（2026-04-28）

## 1. 文档目的

这份文档用于记录当前仓库里 RPG 相关脚本的中文注释补充进度，避免后续“挨个补充”时重复扫描、重复改同一批文件，或者遗漏运行时主链上的关键脚本。

当前原则：

1. 先补职责最核心、状态流最复杂、后续最常被继续修改的脚本。
2. 每一批都尽量按完整链路补，不只补单点文件。
3. 注释以解释“为什么这样编排”“这一层负责什么边界”为主，不堆砌逐行翻译式废话。

---

## 2. 本轮已补充的脚本

### 2.1 RPG 运行时 session 主链

1. `src/hooks/rpg-session/useRpgRuntimeSession.ts`
2. `src/hooks/rpg-session/useRpgSessionBootstrap.ts`
3. `src/hooks/rpg-session/useRpgSessionPersistence.ts`

本轮重点：

1. 说明 session 装配器如何组合 bootstrap、story、combat、persistence。
2. 说明自定义世界开局场景、首遇 NPC、初始装备与初始物品的装配原因。
3. 说明自动存档、继续游戏、手动保存退出的状态边界。

### 2.2 RPG 运行时 story 主链

1. `src/hooks/rpg-runtime-story/useRpgRuntimeStory.ts`
2. `src/hooks/rpg-runtime-story/useRpgRuntimeStoryController.ts`
3. `src/hooks/rpg-runtime-story/useRpgRuntimeStoryFlow.ts`
4. `src/hooks/rpg-runtime-story/useRpgRuntimeInteractionFlow.ts`
5. `src/hooks/rpg-runtime-story/useRpgRuntimeStoryState.ts`
6. `src/hooks/rpg-runtime-story/storyInteractionCoordinator.ts`
7. `src/hooks/rpg-runtime-story/rpgRuntimeStoryGateway.ts`

本轮重点：

1. 说明 controller、flow、interaction、state 四层的职责切分。
2. 说明 NPC 遭遇自动进入交互态、NPC 战斗快照桥接、地图旅行桥接的原因。
3. 说明 story reset、story hydration、服务端动作结算的编排边界。

### 2.3 RPG 运行时 service / client 主链

1. `src/services/rpg-runtime/rpgRuntimeRequest.ts`
2. `src/services/rpg-runtime/rpgRuntimeStoryClient.ts`
3. `src/services/rpg-runtime/rpgSnapshotClient.ts`

本轮重点：

1. 说明 runtime 请求的统一重试策略。
2. 说明服务端 `RuntimeStoryOptionView` 到前端 `StoryOption` 的适配原因。
3. 说明远端快照读取、写入后为什么要先 rehydrate。

---

## 3. 建议的后续补充顺序

为了保持“按链路读得通”，下一轮建议继续按下面顺序推进：

### 3.1 运行时 story 子模块

1. `src/hooks/rpg-runtime-story/storyChoiceCoordinator.ts`
2. `src/hooks/rpg-runtime-story/storyChoiceRuntime.ts`
3. `src/hooks/rpg-runtime-story/storyRequestCoordinator.ts`
4. `src/hooks/rpg-runtime-story/storyRequestRuntime.ts`
5. `src/hooks/rpg-runtime-story/storyGenerationState.ts`
6. `src/hooks/rpg-runtime-story/storyEncounterState.ts`
7. `src/hooks/rpg-runtime-story/storyPresentation.ts`
8. `src/hooks/rpg-runtime-story/sessionActions.ts`
9. `src/hooks/rpg-runtime-story/progressionActions.ts`
10. `src/hooks/rpg-runtime-story/npcInteraction.ts`
11. `src/hooks/rpg-runtime-story/inventoryActions.ts`
12. `src/hooks/rpg-runtime-story/goalFlow.ts`

原因：

1. 这些文件已经紧贴本轮完成的主编排层。
2. 它们包含大量“局部规则 + 状态迁移 + UI 结果”的细节，最需要注释解释。

### 3.2 运行时 UI 与入口层

1. `src/components/rpg-runtime-shell/RpgRuntimeShell.tsx`
2. `src/components/rpg-runtime-shell/RpgRuntimeStageRouter.tsx`
3. `src/components/rpg-runtime-panels/RpgRuntimePanelRouter.tsx`
4. `src/components/rpg-runtime-panels/RpgAdventurePanel.tsx`
5. `src/hooks/rpg-session/useRpgSessionBootstrap.ts` 周边引用组件
6. `src/components/rpg-entry/` 目录里的 RPG 运行时入口桥接脚本

原因：

1. 主链编排层补完后，再补表现层会更容易写出真正有用的注释。
2. 入口层里有兼容 façade，需要明确标出“不要继续堆复杂逻辑”的边界。

### 3.3 RPG 创作链

1. `src/services/rpg-creation/` 目录主 client
2. `src/components/rpg-creation-result/` 主动作脚本
3. `src/components/rpg-creation-editor/` 主编辑链
4. `src/components/rpg-creation-asset-studio/` 角色资产工坊链

原因：

1. 创作链文件也很多，但当前运行时主链更核心、更常改。
2. 等运行时链注释连续后，再切创作链更不容易打断理解。

---

## 4. 本轮备注

1. 本轮以局部补丁方式补注释，没有整文件重写。
2. 本轮没有改业务逻辑，只补中文注释和进度文档。
3. 后续每补完一批，建议同步更新本文件，保持可追踪。