Genarrative/docs/audits/engineering/CURRENT_ENGINEERING_OPTIMIZATION_OPPORTUNITIES_2026-04-20.md

当前工程优化点盘点（2026-04-20）

更新时间：2026-04-20

0. 盘点目标

这份文档用于回答一个更直接的问题：

基于当前仓库状态，接下来最值得投入工程时间的优化点是什么。

本轮只做文档盘点，不直接修改业务代码；结论同时参考了当前工作区现状。
需要注意，仓库当前存在一批未提交改动，尤其集中在 custom world、assets、platform shell 相关模块，所以本文更强调“优先级与切入方式”，而不是要求做大范围整仓改写。

---

1. 当前快照

1.1 本轮复核方式

本轮主要复核了以下内容：

1. 现有工程优化审计文档与目录索引
2. package.json、vite.config.ts、.eslintrc.cjs 等门禁脚本
3. 当前前端、后端、脚本目录的大文件热点
4. 运行时、鉴权、自定义世界、资产链路的边界实现
5. 当前 typecheck / lint / build 状态

---

1.2 当前门禁结果

项目	结果	当前判断
npm run typecheck	失败	当前第一优先级问题，类型基线已失真
npm run lint:eslint	失败	136 个 error、4 个 warning，且 95 个可自动修复
npm run build	通过	发布链路未红，但体积压力仍明显存在

关键说明

当前状态和 2026-04-10 那轮“build warning 直接拦截”的状态不同：

1. 构建现在可以通过。
2. 真正变成第一阻塞项的是 typecheck 与 lint。
3. 构建虽然通过，但主包、功能包、CSS 体积依然偏重，说明性能类优化仍然值得做。

---

1.3 当前热点文件快照

本轮按源码目录统计的大文件热点如下：

文件	当前行数	判断
src/components/CustomWorldEntityEditorModal.tsx	6122	当前前端最大热点
server-node/src/app.test.ts	3568	后端测试聚合度过高
server-node/src/modules/assets/characterAssetRoutes.ts	2802	资产路由职责过重
src/services/ai.ts	2432	浏览器侧 AI 编排仍然偏重
server-node/src/modules/story/storyActionRoutes.test.ts	2402	运行时路由测试聚合度过高
src/data/npcInteractions.ts	2274	NPC 规则数据仍然集中
src/prompts/storyPromptBuilders.ts	1728	prompt 构造成为新的复杂度中心
server-node/src/modules/custom-world/runtimeProfile.ts	1623	custom world runtime 编译热点
src/hooks/story/npcEncounterActions.ts	1582	NPC 行动流仍然偏重
src/components/game-shell/PlatformHomeView.tsx	1474	平台首页壳层继续膨胀
src/components/game-shell/PreGameSelectionFlow.tsx	1418	前置选择流程职责过多
src/services/customWorld.ts	1383	自定义世界服务虽然收缩，但仍偏大

---

2. 结论先行

当前仓库的优化重点，已经不是“继续清旧 Vite 插件链路”或者“继续讨论前后端是否要分离”。

更准确地说，当前最值得做的优化点已经收敛成四类：

1. 先恢复可信的工程基线。
   typecheck 与 lint 当前都是红线，继续扩功能会放大返工成本。
2. 拆掉正在持续膨胀的新热点。
   热点已经从早期运行时主链，迁移到 custom world、asset routes、platform shell、prompt builders。
3. 继续把前端退出“运行时真相”和“鉴权真相”。
   当前前端仍保留本地快照镜像与自动登录凭证持久化。
4. 补一轮入口归档，减少疑似孤岛模块和大测试聚合文件。
   这部分不一定最急，但会持续拉低仓库可维护性。

一句话判断：

当前最值得投入的不是横向加功能，而是把质量门禁重新拉绿，再把 custom world / asset / platform 这批新复杂度中心拆开。

---

3. 优化点清单

3.1 P0：先恢复类型基线

这是当前最优先的工程优化点。

证据

npm run typecheck 当前失败，主要问题集中在两类：

1. CustomWorldCampScene 结构漂移
   • src/components/CustomWorldEntityEditorModal.test.tsx
   • src/data/customWorldLibrary.ts
   • src/services/customWorld.ts
   • src/services/customWorldCamp.ts
2. 局部实现与类型定义不同步
   • src/components/auth/AccountModal.test.tsx 的测试数据缺少新增字段
   • src/components/game-canvas/GameCanvasShared.tsx 引用了未定义的 DEFAULT_IMAGE_STYLE

影响

1. 类型系统已经不能提供可信回归信号。
2. 自定义世界链路当前正在迭代，如果继续在红线状态叠加修改，后续会反复出现“改 A 崩 B”的情况。
3. 测试 fixture 与正式类型脱节，会让测试文件逐渐失去文档价值。

建议

1. 先补一个统一的 CustomWorldCampScene 构造/归一化入口，禁止在多个文件里手写不完整字面量。
2. 把 auth、custom world 的测试 fixture 改成工厂函数，避免字段新增后多处漏改。
3. 单独清掉 GameCanvasShared.tsx 这类“编译即失败”的确定性问题，优先恢复 typecheck 绿色基线。

---

3.2 P0：恢复 lint 可信度，区分机械问题和真实问题

这项和类型基线同级。

证据

npm run lint:eslint 当前结果是：

• 136 个 error
• 4 个 warning
• 其中 95 个问题可自动修复

当前 lint 问题明显分成两层：

1. 机械问题
   • import 排序
   • export 排序
   • 未使用导入
2. 真实问题
   • server-node/src/modules/inventory/inventoryStoryActionService.ts 出现 React Hook 规则错误
   • server-node/src/migrate.ts 仍触发 no-console
   • packages/shared/src/http.ts 触发 @typescript-eslint/ban-types
   • 若干文件存在真正未使用变量、转义和规则误配问题

影响

1. 当前 lint 信号噪音仍然较高，不利于 review。
2. 真实问题会被大量机械问题掩盖。
3. 团队会更倾向于跳过 lint，而不是信任 lint。

建议

1. 先跑一轮仅机械修复的清理批次，优先吃掉 import sort、unused imports 这类低风险项。
2. 再单独处理 Hook 误用、共享契约类型、脚本规则豁免这类语义问题。
3. 之后把“自动可修复问题”与“必须人工处理的问题”拆成两个门禁视角，减少下次再次堆积。

---

3.3 P1：拆 custom world / asset / platform 新热点

这是当前最有性价比的结构性优化点。

证据

当前复杂度最高的业务热点，已经集中在这些模块：

1. src/components/CustomWorldEntityEditorModal.tsx
2. server-node/src/modules/assets/characterAssetRoutes.ts
3. src/services/ai.ts
4. src/prompts/storyPromptBuilders.ts
5. server-node/src/modules/custom-world/runtimeProfile.ts
6. src/components/game-shell/PlatformHomeView.tsx
7. src/components/game-shell/PreGameSelectionFlow.tsx
8. src/hooks/story/npcEncounterActions.ts

问题本质

这些文件并不是单纯“代码多”，而是同时承载了多类职责：

1. UI 状态
2. 领域规则
3. 请求编排
4. 文本构造
5. 运行时映射
6. 面板切换与流程控制

建议

1. CustomWorldEntityEditorModal.tsx
   • 先按“实体列表/表单区/资源区/高级设置/预览区”拆组件
   • 再把数据准备与提交编排抽成 hook
2. characterAssetRoutes.ts
   • 拆成 route、prompt payload、job orchestration、产物发布、错误响应五层
3. PlatformHomeView.tsx 与 PreGameSelectionFlow.tsx
   • 把页面壳层、数据加载、卡片渲染、弹层控制拆开
4. storyPromptBuilders.ts 与 runtimeProfile.ts
   • 把“模板片段”“上下文归一化”“规则裁剪”“最终拼接”分层

---

3.4 P1：继续控制构建产物体积

构建虽通过，但体积已经给出明显信号。

当前证据

本轮 npm run build 输出里，几个值得关注的点是：

1. dist/assets/AuthenticatedApp-*.js：794.77 kB
2. dist/assets/index-*.js：197.44 kB
3. dist/assets/CustomWorldResultView-*.js：163.38 kB
4. dist/assets/ai-*.js：131.73 kB
5. dist/assets/PreGameSelectionFlow-*.js：96.39 kB
6. dist/assets/index-*.css：201.44 kB

影响

1. 虽然还没触发新的 build gate 红线，但首屏、缓存和移动端体验会继续承压。
2. AuthenticatedApp 主包偏大，说明平台壳层仍然装入了过多首屏不必需能力。
3. CSS 体积继续上涨，说明样式正在跨模块相互堆叠。

建议

1. 继续把 custom world、asset studio、平台详情页、角色资产工具从主壳层路径中抽离。
2. 审查 ai.ts、custom world result view、pregame selection 是否还能再延迟加载。
3. 对全局样式做一次按模块归属清理，减少公共样式无限增长。

---

3.5 P1：继续收紧前端与后端边界

这项已经不是“要不要做”的问题，而是“还剩多少尾巴没收完”。

当前证据

1. src/services/apiClient.ts
   • 当前仍把 access token
   • 自动登录用户名
   • 自动登录密码 写入 window.localStorage
2. src/hooks/story/runtimeStoryCoordinator.ts
   • 当前仍会在调用后端运行时前先 putSaveSnapshot(...)
   • 响应后继续 rehydrateSavedSnapshot(...)
3. src/hooks/story/npcEncounterActions.ts
   • 当前仍从前端动作流触发 generateQuestForNpcEncounter(...)
   • 说明 NPC 任务“换单/重抽”分支尚未完全后端化

影响

1. 前端仍保留了一部分运行时真相与鉴权真相。
2. 自动登录凭证持久化在边界和安全上都不理想。
3. 运行时快照前置写入，会让“前端镜像状态”和“后端会话状态”继续纠缠。

建议

1. 优先移除自动登录用户名/密码本地持久化，收敛到服务端 session / refresh 机制。
2. 把运行时快照改为“展示缓存”而不是“提交前真相源”。
3. 把 NPC 任务更换动作补齐到后端 runtime/session 边界，不再由前端直接发起生成决策。

---

3.6 P2：做一次疑似孤岛模块与旧入口归档

这项不一定最紧急，但现在做会明显降低后续维护噪音。

当前现象

从当前入口关系看，以下模块值得做一次正式复核：

1. src/components/GameShell.tsx
2. src/components/custom-world-home/CustomWorldCreationHub.tsx
3. src/components/custom-world-home/CustomWorldCreationLauncherModal.tsx
4. src/components/custom-world-agent/CustomWorldAgentLauncherModal.tsx
5. src/components/custom-world-agent/CustomWorldAgentDraftDrawer.tsx
6. src/hooks/story/storyBootstrap.ts
7. src/hooks/useEquipmentFlow.ts
8. src/hooks/useForgeFlow.ts
9. src/hooks/useInventoryFlow.ts
10. src/services/typewriter.ts

当前判断

这批模块不一定全部是垃圾代码，但至少说明一件事：

仓库里仍然存在一批“不是正式入口、也没有清晰归档标签”的过渡实现。

建议

把这类模块统一分成三类：

1. 正式保留并接回入口
2. 明确标记为实验稿
3. 直接归档或删除

这样可以减少后续开发时的误判成本。

---

3.7 P2：拆测试聚合文件，恢复测试的定位能力

当前测试文件也已经出现“大一统热点”。

证据

1. server-node/src/app.test.ts：3568 行
2. server-node/src/modules/story/storyActionRoutes.test.ts：2402 行
3. server-node/src/modules/assets/characterAssetRoutes.test.ts：1235 行
4. src/hooks/story/npcEncounterActions.test.ts：1199 行

影响

1. 失败定位成本高。
2. fixture 复用差，字段一变容易整片测试跟着漂移。
3. 测试文件本身开始变成新的维护热点。

建议

1. 按领域动作拆测试文件，而不是继续堆到单一总测文件中。
2. 补 fixture builder / factory，减少字面量散落。
3. 对 runtime / auth / custom world / assets 这几条链路增加更明确的契约测试分层。

---

4. 推荐执行顺序

如果只按工程收益排序，建议按下面的顺序推进：

1. 先修 typecheck
2. 再把 lint 分成机械修复和语义修复两轮
3. 然后拆 custom world / asset / platform 热点
4. 再继续收前端运行时与鉴权边界
5. 最后处理孤岛模块归档和测试拆分

---

5. 当前不建议优先做的事

1. 不建议在 typecheck 和 lint 仍为红线时继续横向扩功能。
2. 不建议直接在 CustomWorldEntityEditorModal.tsx、characterAssetRoutes.ts、PlatformHomeView.tsx 里继续堆新逻辑。
3. 不建议把 bundle 体积问题简单理解为“先放宽阈值”，当前更适合继续拆职责和延迟加载。
4. 不建议在未确认入口关系前随手删除可疑旧模块，先做归档分类更稳。

---

6. 本文依据

文档依据：

1. docs/audits/engineering/README.md
2. docs/technical/CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md
3. docs/audits/engineering/ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-20.md
4. docs/experience/PROJECT_WORK_EXPERIENCE_PLAYBOOK.md

当前仓库复核依据：

1. package.json
2. .eslintrc.cjs
3. vite.config.ts
4. scripts/build-gate.mjs
5. src/App.tsx
6. src/services/apiClient.ts
7. src/hooks/story/runtimeStoryCoordinator.ts
8. src/hooks/story/npcEncounterActions.ts
9. 当前源码大文件体量扫描结果
10. npm run typecheck
11. npm run lint:eslint
12. npm run build