# 当前工程优化点盘点（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`