# 当前工程优化优先级汇总（2026-04-10）

## 结论先说

和 `2026-04-01` 那轮工程审查相比，当前仓库的主问题已经发生了明显迁移：

- 运行时主链拆分已经有进展，`useStoryGeneration.ts` 不再是最高复杂度热点。
- `typecheck`、前后端测试、内容校验、编码校验都已经回到可通过状态。
- 当前真正卡住工程节奏的，已经变成：
  - 绿色门禁不可信
  - 构建 warning 仍然会直接打断发布门禁
  - 自定义世界 / 编辑器 / 资产链路出现了新的巨型模块热点
  - 生成产物与旧工具链残留开始反向污染 lint、watch 和本地开发信号

一句话判断：

**现在最该优先做的，不是继续扩功能，而是先把门禁重新拉回可信状态，再拆 editor / custom world / assets 这批新的复杂度中心。**

---

## 2026-04-10 当前校验快照

本次汇总不是只复述旧文档，额外执行了当前仓库校验命令。

| 项目 | 结果 | 说明 |
| --- | --- | --- |
| `npm run check:encoding` | 通过 | 编码基线正常 |
| `npm run typecheck` | 通过 | 当前严格类型门禁可通过 |
| `npm run test` | 通过 | `92` 个测试文件、`228` 个测试通过 |
| `npm run server-node:test:baseline` | 通过 | 观测基线正常 |
| `npm run server-node:test` | 通过 | `72` 个后端测试通过 |
| `npm run check:content` | 通过 | 内容与覆盖校验正常 |
| `npm run lint:eslint` | 失败 | `330` 个 error、`4` 个 warning |
| `npm run build` | 失败 | 构建完成，但因 warning 被 `build-gate` 拦截 |

当前状态说明：

- 仓库不是“完全不可用”，而是已经进入“测试绿，但门禁信号不一致”的阶段。
- 这类状态比纯红线更危险，因为团队会误以为主链已经稳定。

---

## P0：先恢复可信的绿色门禁

### P0-1：修复 lint 失真，重新建立可信基线

这是当前第一优先级。

#### 证据

- `npm run lint:eslint` 当前失败，报出 `330` 个 error、`4` 个 warning。
- 问题既有真实源码问题，也有明显的门禁污染：
  - `src/`、`server-node/`、`scripts/` 中存在 import 排序、未使用导入、少量 hook 规则问题。
  - `temp-build-goal-check/` 这类生成产物目录也被 ESLint 扫描进来，放大了噪音。
- `.eslintrc.cjs` 当前忽略了 `dist`、`media` 等目录，但没有忽略 `temp-build-goal-check`。
- `vite.config.ts` 的 `server.watch.ignored` 已经忽略了 `**/temp*build*/**`，说明当前 watch 口径和 lint 口径并不一致。

#### 影响

- 团队无法快速判断“现在是源码真问题，还是产物目录噪音”。
- lint 失真会直接削弱 review、回归和集成效率。
- 在这种状态下继续加功能，只会让真实错误被更多噪音淹没。

#### 当前建议

1. 先清理或迁出 `temp-build-goal-check/` 这类生成产物目录，至少不要再让它进入 lint 扫描范围。
2. 统一 `watch / lint / build` 对临时目录和生成目录的忽略口径。
3. 再集中清当前源码层 lint 问题，优先处理：
   - import 排序
   - 未使用导入
   - 少量真实规则错误，例如 hook 误用和 `ban-types`

---

### P0-2：修复构建 warning，恢复可发布构建

这是和 P0-1 同级的阻塞项。

#### 证据

- `npm run build` 当前会被 `scripts/build-gate.mjs` 拦截。
- 当前构建输出里最关键的 warning 有两类：
  - `src/services/ai.ts` 虽然尝试走动态加载，但又被 `src/components/CustomWorldEntityEditorModal.tsx` 静态引入，导致拆包失效。
  - `AuthenticatedApp-*.js` 达到 `1078.61 kB`，超过当前 `750 kB` 的 chunk warning 门槛。
- 同轮构建里，`index-*.css` 也已经达到 `157.56 kB`，说明不仅 JS 主块重，样式也在继续膨胀。

#### 影响

- 当前不是“构建有一点 warning 可以先带着走”，而是发布门禁已经被 warning 直接打断。
- editor / custom world / asset 工具能力正在把非主链代码重新带回主包路径。
- 后续如果继续叠加这条链路，首屏、缓存和回归都会继续变差。

#### 当前建议

1. 先切断 `CustomWorldEntityEditorModal.tsx -> ../services/ai` 的静态依赖，让 `ai.ts` 真正留在懒加载路径。
2. 把自定义世界编辑器、资产工作台、非首屏工具能力继续从 `AuthenticatedApp` 主块中拆出。
3. 保持 `build warning = 失败` 的策略，不建议通过放宽阈值掩盖问题。

---

## P1：拆掉新的复杂度中心

### P1-1：优先拆 editor / custom world / assets 新热点

旧的运行时主链热点已经有所缓解，但复杂度并没有消失，而是转移到了新的模块上。

#### 当前大文件热点

前端：

- `src/components/CustomWorldEntityEditorModal.tsx`：`2778` 行
- `src/services/ai.ts`：`2454` 行
- `src/services/customWorld.ts`：`2217` 行
- `src/data/npcInteractions.ts`：`2103` 行
- `src/data/characterPresets.ts`：`1953` 行
- `src/services/prompt.ts`：`1725` 行

后端：

- `server-node/src/modules/assets/characterAssetRoutes.ts`：`2295` 行
- `server-node/src/app.test.ts`：`1527` 行
- `server-node/src/auth/authService.ts`：`1243` 行
- `server-node/src/modules/quest/runtimeQuestModule.ts`：`1137` 行

工具链：

- `scripts/dev-server/*.ts`：已于 `2026-04-19` 删除，旧 Vite 本地 API 链路不再保留实现代码

#### 影响

- 复杂度并没有真正被消灭，而是从运行时 story hook 转移到了自定义世界、资产编辑、提示词和数据装配链。
- 这些文件大多同时承载了：
  - 领域规则
  - API 调用
  - 文本拼装
  - UI 状态
  - 工具流程
- 后续任何一个小改动，都容易牵动整条大链，回归成本会再次上升。

#### 当前建议

1. 前端优先拆 `CustomWorldEntityEditorModal.tsx`，按“世界锚点 / 角色 / 地点 / 资产 / 高级设置”分段。
2. 后端优先拆 `characterAssetRoutes.ts`，把 route、job orchestration、文件发布、模板读取拆开。
3. 把 `src/services/ai.ts` 和 `src/services/customWorld.ts` 继续按运行时 / 编辑器 / 资产工具三条职责分层。

---

### P1-2：继续收口 editor / assets 工具链边界（旧链路已删除）

这项的重要性正在上升。

#### 证据

- `docs/technical/EDITOR_ASSET_API_MIGRATION_2026-04-08.md` 已说明 editor/assets API 已经迁到 `server-node`，方向是对的。
- `scripts/dev-server/*.ts` 旧 Vite 本地 API 实现代码已于 `2026-04-19` 删除，仓库里不再保留并行实现。
- 目录 `temp-build-goal-check/` 当前包含 `15099` 个文件，已经开始干扰 lint 和本地开发信号。
- 相关日志里还出现了大量指向 `temp-build-goal-check` 的页面 reload 与 `ENOENT` 噪音。

#### 影响

- editor/assets 正式入口已经收口到 `server-node`，这部分双链路问题已解除。
- 当前更大的噪音来源已经转移到临时构建目录、检查目录和历史日志残留。

#### 当前建议

1. 保持 `scripts/dev-server/README.md` 作为迁移结果标记，不要恢复旧 Vite `/api/*` 本地插件链。
2. 将临时构建目录、检查目录、导出目录统一移出主工程扫描面。
3. 继续以 `server-node/src/modules/editor/**`、`server-node/src/modules/assets/**` 与 `src/editor/shared/editorApiClient.ts` 作为唯一推荐入口，减少后续回流。

---

## P2：继续做架构收口，但不必抢在 P0 前面

### P2-1：继续压缩前端遗留 AI / 自定义世界实现

这一项仍然值得做，但当前不再是最前面的阻塞。

#### 原因

- `docs/technical/EXPRESS_BACKEND_WORKSTREAM_AUDIT_2026-04-09.md` 显示正式运行时主链已经大幅回收到后端。
- 当前更明显的遗留，已经集中到编辑器、自定义世界工作台和资产工具，而不是正式运行时 story 主链。

#### 当前建议

1. 继续让正式运行时保持“后端为真相源”。
2. 对仍留在前端的大 AI / prompt / custom world 实现，优先做职责收缩，而不是继续在原文件上堆逻辑。

---

### P2-2：继续优化自定义世界工作台，但以“减负”和“分层”为主

这一项更适合作为 P0、P1 稳住后的下一轮重点。

#### 依据

- `docs/audits/CUSTOM_WORLD_CREATOR_TOOL_AUDIT_2026-04-08.md` 已经明确指出：
  - 自定义世界入口、澄清、锁定、局部重生成、结果工作台仍是半收口状态。
- 当前最大的前端热点文件也集中在这条链路上，说明它已经不仅是产品问题，也是工程复杂度问题。

#### 当前建议

1. 优先减少“大一统编辑弹窗”的职责，把高杠杆编辑和高级编辑分层。
2. 让自定义世界生成、锁定、局部重生成规则继续向后端收口。
3. 移动端优先，避免长表单和重弹窗继续吞掉维护成本。

---

## 推荐执行顺序

### 第一阶段：先把门禁拉回可信

1. 修 lint 口径失真
2. 清生成产物扫描污染
3. 修 build warning

### 第二阶段：再拆新的复杂度中心

1. 拆 `CustomWorldEntityEditorModal.tsx`
2. 拆 `characterAssetRoutes.ts`
3. 收缩 `src/services/ai.ts` / `src/services/customWorld.ts`

### 第三阶段：最后收 editor / custom world 架构尾巴

1. 清理旧 Vite 工具链残留
2. 继续把自定义世界和资产工具收回正式后端边界

---

## 当前不建议优先做的事

- 不建议在当前 lint 与 build 仍然是红线时继续横向扩 editor / custom world 功能。
- 不建议通过放宽 chunk warning 阈值来“修复”构建。
- 不建议继续在 `CustomWorldEntityEditorModal.tsx`、`src/services/ai.ts`、`characterAssetRoutes.ts` 这类巨型文件中直接堆新逻辑。

---

## 本文依据

文档依据：

- `docs/audits/engineering/ENGINEERING_OPTIMIZATION_REVIEW_2026-04-01.md`
- `docs/technical/EXPRESS_BACKEND_WORKSTREAM_AUDIT_2026-04-09.md`
- `docs/technical/EDITOR_ASSET_API_MIGRATION_2026-04-08.md`
- `docs/audits/CUSTOM_WORLD_CREATOR_TOOL_AUDIT_2026-04-08.md`
- `docs/planning/CURRENT_GAME_ITERATION_PRIORITIES_2026-04-03.md`

当前仓库校验依据：

- `npm run check:encoding`
- `npm run typecheck`
- `npm run test`
- `npm run server-node:test:baseline`
- `npm run server-node:test`
- `npm run check:content`
- `npm run lint:eslint`
- `npm run build`