Rework story engine flow and reorganize project docs

docs/audits/engineering/ENGINEERING_OPTIMIZATION_REVIEW_2026-03-30.md

@@ -0,0 +1,290 @@
+# 工程优化审查报告（2026-03-30）
+
+## 审查范围
+
+- 扫描范围：`src/`、`scripts/`、`docs/`、`.github/`、`package.json`、`tsconfig.json`、`vite.config.ts`
+- 实际执行：`npm run lint`、`npm run test`、`npm run build`、`npm run check:content`
+- 说明：按仓库要求，本报告不讨论中文乱码问题，只讨论工程结构、边界、质量门禁、可维护性和后续扩展成本
+
+## 先说结论
+
+这轮代码库相较 `docs/audits/engineering/ENGINEERING_OPTIMIZATION_REVIEW_2026-03-29.md` 已经有明显进展，项目不再是“所有能力都糊在一个入口文件里”的状态了，但整体仍然处于“重构过渡期”。
+
+已经落地的积极变化：
+
+- 入口路由已经从手写 `pathname` 分发，收敛到 `src/main.tsx` + `src/routing/appRoutes.tsx`
+- 持久化能力已经抽到 `src/persistence/`
+- 编辑器公共能力已经出现 `src/editor/shared/`
+- `CI + ESLint + Prettier + Vitest` 已经接入
+- 本地 API 插件已经从 `vite.config.ts` 抽走，落到 `scripts/dev-server/localApiPlugins.ts`
+- `preview` 环境里的 JSON 写入接口已经改成只读，这一点比上轮更安全
+
+但当前仍然存在 5 个值得优先处理的工程问题：
+
+1. 运行时主链仍然过于集中，`story/combat` 的真实边界还没有彻底拆开
+2. `src/services/ai.ts` 仍处于迁移中间态，存在重复实现和旧逻辑残留
+3. 编辑器主入口仍是大型聚合组件，迁移残留没有清干净
+4. 质量门禁已经有框架，但还不够“硬”，warning 和测试覆盖缺口仍然明显
+5. 运行时渲染层和构建体积仍偏重，重 UI 模块还没拆到合适粒度
+
+## 当前运行状态
+
+- `npm run test` 通过，6 个测试文件共 18 个测试全部通过
+- `npm run build` 通过
+- `npm run check:content` 通过
+- `npm run lint` 通过，但仍有 76 条 warning
+
+当前构建产物里仍然存在较重 chunk：
+
+- `dist/assets/GameCanvas-*.js` 约 `346.58 kB`
+- `dist/assets/App-*.js` 约 `326.89 kB`
+- `dist/assets/index-*.js` 约 `197.80 kB`
+- `dist/assets/index-*.css` 约 `117.37 kB`
+
+## P0：运行时主链仍然过于集中，Story/Combat 边界还没有拆透
+
+### 现状
+
+虽然 `App.tsx` 已经明显瘦身，`GameShell` 也比之前更像壳层，但真正决定游戏推进的主逻辑仍然高度集中在两个大 hook 里：
+
+- `src/hooks/useStoryGeneration.ts:824`
+- `src/hooks/useCombatFlow.ts:382`
+
+### 证据
+
+`useStoryGeneration` 仍然同时编排了多个本应继续拆开的子领域：
+
+- `src/hooks/useStoryGeneration.ts:852` 接入 `useCharacterChatFlow`
+- `src/hooks/useStoryGeneration.ts:1583` 接入 `useTreasureFlow`
+- `src/hooks/useStoryGeneration.ts:1588` 接入 `useInventoryFlow`
+- `src/hooks/useStoryGeneration.ts:1593` 接入 `useEquipmentFlow`
+- `src/hooks/useStoryGeneration.ts:1597` 接入 `useForgeFlow`
+- 文件总长仍有约 `3240` 行
+- 结尾返回对象同时暴露剧情推进、地图旅行、NPC 交易/送礼/招募、角色聊天、背包与锻造 UI 能力，典型位置在 `src/hooks/useStoryGeneration.ts:3171-3219`
+
+`useCombatFlow` 也不是纯计算层，它仍然同时承担：
+
+- 战斗前后状态推导
+- 动画播放与时间推进
+- `setGameState` 驱动的可视化编排
+- 逃跑流程与 story 响应同步
+
+关键位置：
+
+- `src/hooks/useCombatFlow.ts:382` `useCombatFlow`
+- `src/hooks/useCombatFlow.ts:1195` `playEscapeSequenceWithStorySync`
+
+### 影响
+
+- 任何一个“剧情选项新增”都很容易同时碰到 battle、npc、quest、inventory、chat 五条链路
+- review 成本高，回归范围判断依赖人脑上下文
+- 单测很难往 hook 级别补，因为副作用、异步节奏和 UI 状态混在一起
+- 后续想继续做 camp、custom world、更多 companion 玩法时，改动会继续集中到这两个入口
+
+### 建议
+
+- 把 `useStoryGeneration` 继续下钻成“剧情推进 orchestrator + 领域 action service”
+- `useStoryGeneration` 自己只保留编排，不再直接维护 trade/gift/recruit/chat/inventory/forge 的全部细节
+- `useCombatFlow` 继续向“纯战斗结算”和“播放适配层”分离
+- 先稳定公开接口，再做内部拆分，避免一次性大改
+
+## P1：AI 服务迁移只完成了一半，`src/services/ai.ts` 仍然存在双轨实现
+
+### 现状
+
+仓库已经新增了：
+
+- `src/services/llmClient.ts`
+- `src/services/llmParsers.ts`
+- `src/services/aiFallbacks.ts`
+- `src/services/aiTypes.ts`
+
+这说明拆层方向是对的。但 `src/services/ai.ts` 还没有真正变成“纯 orchestration 层”，里面仍然保留着一整套旧 transport / parse / fallback 逻辑。
+
+### 证据
+
+- `src/services/ai.ts:64-66` 已经开始导入 `llmClient`
+- `src/services/ai.ts:89-95` 仍然保留本地 `resolveTimeoutMs` 和超时常量
+- `src/services/ai.ts:647` 仍然保留 `_requestPlainTextCompletion`
+- `src/services/ai.ts:719` 仍然保留 `_parseJsonResponseText`
+- `src/services/ai.ts:739` 仍然保留 `_parseLineListContent`
+- `src/services/ai.ts:784` 仍然保留 `_streamPlainTextCompletion`
+- `src/services/ai.ts:885-904` 仍然保留一批旧的 `_buildOffline...` helper
+
+与之对应，新的实现已经在下面这些文件里存在：
+
+- `src/services/llmClient.ts`
+- `src/services/llmParsers.ts`
+
+### 影响
+
+- 同一类能力现在有两套真相源，后续改错误分类、超时策略、SSE 行为时容易漏改
+- 新同学读代码时很难判断应该继续改 `ai.ts`，还是应该去改 `llmClient.ts`
+- 迁移残留会拉高维护成本，也会让测试边界变得模糊
+
+### 建议
+
+- 把 `src/services/ai.ts` 收敛成“业务 prompt 编排 + fallback 选择”层
+- 彻底删掉未再需要的 `_requestPlainTextCompletion`、`_streamPlainTextCompletion`、`_parse*` 等旧 helper
+- 所有 transport / timeout / connectivity error / SSE 解析都只保留在 `llmClient.ts` 和 `llmParsers.ts`
+- 迁移完成后，给 `ai.ts` 增加一组 orchestration 级测试，防止 fallback 分支回归
+
+## P1：编辑器主入口仍然太重，而且过渡态残留还在
+
+### 现状
+
+编辑器公共能力已经开始沉淀到 `src/editor/shared/`，这是好事；但主编辑器入口仍然比较重，且部分文件还保留着迁移过程里的死代码和注释块。
+
+### 证据
+
+`PresetEditor` 仍然是一个大型聚合组件：
+
+- `src/components/PresetEditor.tsx:402` `CharacterPresetPanel`
+- `src/components/PresetEditor.tsx:1174` `SceneNpcPresetPanel`
+- `src/components/PresetEditor.tsx:1547` `ScenePresetPanel`
+- `src/components/PresetEditor.tsx:1852` `MonsterPresetPanel`
+- `src/components/PresetEditor.tsx:2218` `PresetEditor`
+- 文件总长仍有约 `2279` 行
+
+同时，文件里还留着明显的过渡态残留：
+
+- `src/components/PresetEditor.tsx:227` 仍然保留未使用的 `_SectionCard`
+- `src/components/NpcVisualEditor.tsx:684` 保留 `if (false)` 的旧保存路径
+- `src/components/NpcVisualEditor.tsx:685` 明确写着 “Deprecated inline save path kept only until the shared client migration is cleaned up.”
+- `src/components/NpcVisualEditor.tsx:724` 还有第二处 `if (false)` 残留
+
+### 影响
+
+- 编辑器后续继续扩展时，容易重新长回“大一统文件”
+- 过渡代码会误导维护者，以为旧保存链路仍然有效
+- 公共层虽然建起来了，但如果不清理旧代码，长期会形成“共享层 + 本地特例”并存
+
+### 建议
+
+- 以“一个 tab 一个容器”的方式，把 `PresetEditor` 再拆一层
+- 清理 `NpcVisualEditor` 里的废弃代码块，不要再保留 `if (false)` 分支
+- 对编辑器共享层设定明确规则：保存请求、克隆、Section 容器、错误提示都必须走 shared
+- 对编辑器做一次“小型迁移完成清扫”，优先删掉已经废弃但还挂在文件里的旧路径
+
+## P1：质量门禁已经接上，但还不够硬
+
+### 现状
+
+基础设施已经比上轮完整很多，但当前门禁仍然偏“有检查，不够严格”。
+
+### 证据
+
+当前 lint 结果：
+
+- 本次 `npm run lint` 实际输出 `76` 条 warning，虽然命令返回成功
+
+脚本和规则层面的原因也很明确：
+
+- `package.json:12` 的 `lint` 仍然是 `eslint . ... && tsc --noEmit`，没有 `--max-warnings 0`
+- `package.json:11` 的 `lint:guardrails` 虽然加了 `--max-warnings 0`，但它只覆盖一组显式 allowlist 文件
+- `package.json:18` 的 `check` 会先跑 `lint:guardrails`，再跑宽松版 `lint`
+- `.eslintrc.cjs:45-61` 里大量规则仍然是 `warn`
+- `.github/workflows/ci.yml:28-40` 已经把 `lint / guardrails / test / build / check:content` 都接到 CI，但 warning 仍能稳定进主干
+
+测试覆盖也还是偏薄：
+
+- `src/` 当前共有 `126` 个文件
+- 其中测试文件只有 `6` 个
+- 现有测试主要覆盖 `routing`、`persistence`、`jsonClient`、`llmParsers`、`battlePlan`
+- 关键主链如 `useStoryGeneration`、`useCombatFlow` 播放层、`GameShell` 集成链路、编辑器保存流程仍然没有直接测试
+
+### 影响
+
+- 代码库会持续积累“已知 warning，但先不处理”的债务
+- 工程信号会逐渐失真，lint 通过不代表代码足够干净
+- 大 hook 和大组件的重构依然主要依赖人工回归
+
+### 建议
+
+- 先把 warning 收敛到一个可控范围，再把全仓 `lint` 切成 `--max-warnings 0`
+- `lint:guardrails` 不要长期靠 allowlist，应该逐步扩大到全仓
+- 优先补三类测试：
+  - `useStoryGeneration` 的状态推进和 modal 决策
+  - `useCombatFlow` 播放层的关键分支
+  - 编辑器保存链路和覆盖数据回写
+
+## P2：运行时渲染层仍然偏重，chunk 也还没有拆到理想粒度
+
+### 现状
+
+入口已经有了 route lazy load，模态框也做了一部分懒加载，但核心运行时渲染层仍然比较重。
+
+### 证据
+
+- `src/components/AdventurePanel.tsx:470` 导出主组件，文件总长约 `1538` 行
+- `src/components/GameCanvas.tsx:472` 导出主组件，文件总长约 `1131` 行
+- `src/components/GameCanvas.tsx:768` 仍然存在 `false && companions.map(...)` 的死分支
+- 本次构建里 `GameCanvas` 和 `App` 仍然是最大 chunk 之一
+
+### 影响
+
+- 运行时页面的首屏与热区模块仍然偏重
+- 渲染逻辑、场景动画逻辑、实体选中逻辑继续堆在同一层，review 和测试都偏吃力
+- 清理死分支前，维护者对“哪些渲染路径是真实生效的”判断成本更高
+
+### 建议
+
+- `GameCanvas` 继续拆成 scene layer、entity layer、effect layer、overlay layer
+- `AdventurePanel` 继续下沉 quest/stats/settings/reward 子面板
+- 清理 `false &&` 与未使用辅助组件，避免假分支继续留在主路径文件中
+- 结合真实 chunk 数据做一次 route 内部分包，而不是只靠入口级 lazy
+
+## P2：TypeScript 安全基线仍然偏宽松
+
+### 现状
+
+当前类型拆分方向是好的，`src/types.ts` 已经退化成 barrel，真实类型开始向 `src/types/` 下沉。但 TypeScript 编译配置还比较保守，类型系统还没有真正变成强约束。
+
+### 证据
+
+- `tsconfig.json:12` `skipLibCheck: true`
+- `tsconfig.json:16` `allowJs: true`
+- 当前没有启用 `strict`
+- 当前没有启用 `noUncheckedIndexedAccess`
+
+### 影响
+
+- 对大对象和字典访问的保护仍然偏弱
+- 新模块迁移到更细类型后，收益会被宽松编译选项部分抵消
+- “代码能过类型检查”并不等于边界足够安全
+
+### 建议
+
+- 不建议一次性全仓开严格模式
+- 可以先从 `src/services/`、`src/persistence/`、`src/hooks/combat/` 这些相对纯的目录启更严格约束
+- 至少先评估开启 `noUncheckedIndexedAccess` 和减少 `allowJs` 的必要性
+
+## 建议的落地顺序
+
+### 第一阶段：先把过渡态清干净
+
+- 清理 `ai.ts` 的旧 transport / parser / fallback 实现
+- 清理 `NpcVisualEditor`、`GameCanvas`、`PresetEditor` 等文件里的 `if (false)`、未使用 helper、废弃注释块
+- 把 lint warning 数量先打下来
+
+### 第二阶段：拆主链，不再让大 hook 继续膨胀
+
+- 继续拆 `useStoryGeneration`
+- 继续拆 `useCombatFlow`
+- 优先把“领域动作”和“播放/展示编排”分开
+
+### 第三阶段：补门禁
+
+- 给主链补单测和少量集成 smoke
+- 让全仓 lint 朝 `--max-warnings 0` 收敛
+- 把 warning 从“长期存在”变成“短周期清零”
+
+### 第四阶段：优化运行时体积
+
+- 细化 `GameCanvas` 和 `AdventurePanel` 的模块边界
+- 按实际交互热区做 chunk 继续拆分
+- 用真实构建产物持续追踪是否降重
+
+## 一句话结论
+
+这轮仓库已经从“完全依赖大文件硬扛”进步到“基础设施开始成形”，但当前最需要做的已经不是继续加功能，而是把这轮重构收尾做完整：继续拆主链、删掉迁移残留、把 lint/test 门禁变硬、再顺手压缩运行时大模块。只要这一步补上，后续加剧情、加编辑器能力、加自定义世界都会轻很多。