Genarrative/docs/reference/RPG_SCRIPT_COMMENTARY_PROGRESS_2026-04-28.md

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. 后续每补完一批，建议同步更新本文件，保持可追踪。