Genarrative/docs/audits/engineering/CURRENT_ENGINEERING_OPTIMIZATION_PRIORITIES_2026-04-10.md

当前工程优化优先级汇总（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/localApiPlugins.ts：1504 行

影响

• 复杂度并没有真正被消灭，而是从运行时 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，方向是对的。
• 但当前仓库里仍保留一个 1504 行的 scripts/dev-server/localApiPlugins.ts。
• 目录 temp-build-goal-check/ 当前包含 15099 个文件，已经开始干扰 lint 和本地开发信号。
• 相关日志里还出现了大量指向 temp-build-goal-check 的页面 reload 与 ENOENT 噪音。

影响

• 旧工具链虽然“不再是主入口”，但它们还在继续占据认知空间和仓库噪音预算。
• 新旧 editor/assets 路径长期并存，会导致维护者很难快速判断哪条链才是正式路径。

当前建议

1. 明确把旧 Vite 插件链标记为迁移参考，避免继续被误用。
2. 将临时构建目录、检查目录、导出目录统一移出主工程扫描面。
3. 对 editor/assets 正式入口补一份“唯一推荐入口”文档或 README 更新，减少后续回流。

---

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