GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions 4 Packages Projects Releases Wiki Activity

Prune obsolete docs and update navigation

Browse Source
This commit is contained in:
高物
2026-04-25 15:10:24 +08:00
parent 1c5f9303a2
commit 2ebfd1cf55
341 changed files with 1352 additions and 90709 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/audits/engineering/CURRENT_ENGINEERING_OPTIMIZATION_OPPORTUNITIES_2026-04-20.md
View File

@@ -349,7 +349,7 @@
文档依据：
1. `docs/audits/engineering/README.md`
2. `docs/audits/engineering/CURRENT_ENGINEERING_OPTIMIZATION_PRIORITIES_2026-04-10.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`

256
docs/audits/engineering/CURRENT_ENGINEERING_OPTIMIZATION_PRIORITIES_2026-04-10.md
View File

@@ -1,256 +0,0 @@
# 当前工程优化优先级汇总（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`

12
docs/audits/engineering/ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-19.md
View File

@@ -124,9 +124,8 @@
本次审计结合了四类证据：
1. 文档基线：
- `docs/audits/engineering/CURRENT_ENGINEERING_OPTIMIZATION_PRIORITIES_2026-04-10.md`
- `docs/planning/EXPRESS_BACKEND_REFACTOR_PLAN_2026-04-08.md`
- `docs/planning/EXPRESS_BACKEND_PARALLEL_WORKSTREAM_PLAN_2026-04-08.md`
- `docs/audits/engineering/README.md`
- `docs/technical/CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md`
- `scripts/dev-server/README.md`
2. 当前入口核对：
- `src/main.tsx`
@@ -591,10 +590,9 @@
文档依据：
1. `docs/audits/engineering/CURRENT_ENGINEERING_OPTIMIZATION_PRIORITIES_2026-04-10.md`
2. `docs/planning/EXPRESS_BACKEND_REFACTOR_PLAN_2026-04-08.md`
3. `docs/planning/EXPRESS_BACKEND_PARALLEL_WORKSTREAM_PLAN_2026-04-08.md`
4. `scripts/dev-server/README.md`
1. `docs/audits/engineering/README.md`
2. `docs/technical/CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md`
3. `scripts/dev-server/README.md`
当前仓库扫描依据：

6
docs/audits/engineering/ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-20.md
View File

@@ -366,9 +366,8 @@
文档依据：
1. `docs/audits/engineering/ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-19.md`
2. `docs/audits/engineering/CURRENT_ENGINEERING_OPTIMIZATION_PRIORITIES_2026-04-10.md`
3. `docs/planning/EXPRESS_BACKEND_REFACTOR_PLAN_2026-04-08.md`
4. `docs/planning/EXPRESS_BACKEND_PARALLEL_WORKSTREAM_PLAN_2026-04-08.md`
2. `docs/audits/engineering/README.md`
3. `docs/technical/CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md`
当前仓库复核依据：
@@ -381,4 +380,3 @@
7. `src/services/runtimeItemAiDirector.ts`
8. `src/services/apiClient.ts`
9. 当前依赖图扫描结果与当前大文件体量扫描结果

278
docs/audits/engineering/ENGINEERING_OPTIMIZATION_REVIEW_2026-03-29.md
View File

@@ -1,278 +0,0 @@
# 工程优化审查报告（2026-03-29）
## 说明
- 扫描范围：`src/`、`scripts/`、`docs/`、`package.json`、`vite.config.ts`、`tsconfig.json`
- 已执行校验：`npm run lint`、`npm run build`、`npm run check:content`
- 本报告只从工程角度讨论结构、边界、质量门禁、可维护性与可扩展性
- 按仓库说明，暂不讨论中文乱码本身
## 当前结论
项目当前**可构建、可运行、内容校验可通过**，说明基础功能链路是通的；但从工程视角看，已经出现明显的“单点过重、边界混杂、质量门禁偏弱、编辑器与运行时耦合”问题。继续叠需求会越来越依赖人工记忆和局部经验，回归风险会持续上升。
当前最值得优先处理的不是单个 UI 细节，而是以下四个工程主题：
1. 运行时主链路的职责拆分还不够，核心 hook / 组件已经过载
2. 缺少真正的工程质量门禁，`lint` 目前本质上只是 `tsc`
3. 编辑器、运行时、类后端能力都混在同一个 Vite 配置里
4. 持久化、AI 调用、编辑器保存等基础设施仍然是“分散手写”
## 运行状态快照
- `npm run lint` 通过
- `npm run build` 通过
- `npm run check:content` 通过
- 应用代码下未发现测试文件：`src/`、`scripts/`、`docs/` 内没有 `*.test.*` / `*.spec.*`
- 构建产物已出现较大 chunk
- `dist/assets/App-*.js` 约 `407 KB`
- `dist/assets/itemCatalog-*.js` 约 `414 KB`
- `dist/assets/PresetEditor-*.js` 约 `109 KB`
## 代码体征
下列文件已经明显进入“超大模块”区间：
| 文件 | 行数 | 观察 |
| --- | ---: | --- |
| `src/hooks/useStoryGeneration.ts` | 3304 | 同时管理剧情、NPC 交互、交易、送礼、招募、任务、角色聊天、道具/锻造接入 |
| `src/components/PresetEditor.tsx` | 2244 | 多编辑器入口聚合在一个巨型组件中 |
| `src/hooks/useCombatFlow.ts` | 1791 | 同时承担战斗推演、动画时序、逃跑演出、状态落地 |
| `src/components/GameShell.tsx` | 1592 | 入口 UI、选角、世界选择、自定义世界、场景切换、浮层控制全部集中 |
| `src/types.ts` | 663 | 运行时、AI、编辑器、自定义世界、背包、任务类型集中在一个总文件 |
补充信号：
- `src/components/GameShell.tsx` 内有 16 个 `useState`、10 个 `useEffect`、13 个 `useMemo`
- `src/hooks/useStoryGeneration.ts` 虽然只有少量 React state，但内部累计 40+ 个函数，已经是“巨型流程控制器”
- `src/hooks/useCombatFlow.ts` 内有大量时间常量、动画常量、`sleep + setGameState` 过程式循环，测试成本很高
## 优先级问题
## P0：运行时主链路职责过度集中
证据：
- `src/hooks/useStoryGeneration.ts:868-930` 进入 hook 后立即开始定义交易、送礼、招募、角色聊天等子流程
- `src/hooks/useStoryGeneration.ts:3191-3303` 返回对象同时暴露剧情、任务、NPC UI、角色聊天 UI、背包/锻造 UI
- `src/components/GameShell.tsx:293-360` 组件 props 很多，内部 state 也很多，承担“壳层 + 流程 + 浮层 + 自定义世界生成 + 场景切换”
- `src/hooks/useCombatFlow.ts:559-1787` 将战斗计算和战斗演出揉在同一层里
影响：
- 任何一个新需求都容易同时碰到剧情、UI、战斗、背包、NPC 关系四五条链路
- 代码 review 很难聚焦，改动一处时往往需要脑内跟完整条大流程
- 单元测试难写，因为逻辑不是纯函数，而是大量闭包 + 过程式状态推进
- 长期会形成“只有熟悉历史上下文的人才能安全修改”的隐性门槛
建议：
- 将 `useStoryGeneration` 拆为“剧情推进”“NPC 交互”“角色聊天”“任务结算”“模态框控制”几个子域
- 将 `useCombatFlow` 拆成“纯战斗结算引擎”和“战斗播放适配层”
- 让 `GameShell` 回到壳层职责，只负责路由态、页面态、模态挂载与 props 编排
- 以“领域职责”拆分，而不是按“文件太长了随便切一刀”拆分
## P0：缺少真正的工程质量门禁
证据：
- `package.json:11` 的 `lint` 实际只有 `tsc --noEmit`
- `package.json` 中没有 `test`、`format`、`lint:fix` 等基础脚本
- 根目录未发现 `.eslintrc*`、`.prettierrc*`、`.editorconfig`
- 代码目录下没有测试文件
影响：
- 当前项目的“能过 lint”只代表类型没炸，不代表风格一致、依赖正确、Hooks 规则正确、死代码已清理
- 大型 hook / 大型组件的重构几乎没有自动回归保护
- 运行时行为、编辑器行为、AI fallback 行为主要依赖人工回归
建议：
- 补齐 ESLint、Prettier、EditorConfig，至少覆盖 React Hooks、import、unused code、复杂度基线
- 引入 Vitest，先覆盖纯数据层与纯规则层
- 为 `useCombatFlow`、`stateFunctions`、`npcInteractions`、`questFlow` 增加单元测试
- 为“开局 -> 选世界 -> 选角色 -> 进入剧情 -> 战斗 -> 存档恢复”补最小 E2E smoke
- CI 中至少串联：类型检查 + 单测 + build + 内容校验
## P1：编辑器、运行时、类后端能力全部耦合在 Vite 配置里
证据：
- `vite.config.ts:151-203` 在 Vite 插件里实现了 LLM 代理
- `vite.config.ts:206-269` 在 Vite 插件里实现了通用 JSON 文件读写 API
- `vite.config.ts:253` 直接写回 `src/data/*.json`
- `vite.config.ts:265-266` 和 `vite.config.ts:400-401` 在 `preview` 阶段也挂了这些接口
- `vite.config.ts:425-434` 启动时默认把这些“编辑器后端能力”全部注册进去
影响：
- 本地编辑器能力与运行时能力没有清晰边界
- `preview` 环境仍可写源码文件，发布边界不清晰
- 未来如果要做独立部署、多人协作、远程编辑、权限控制，会非常难迁移
- Vite 配置同时扮演构建配置、代理层、文件服务层、编辑器后端，职责失衡
建议：
- 将编辑器读写 API 从 `vite.config.ts` 抽到独立的本地工具服务或独立脚本
- 至少区分 `dev-only write api` 与 `preview/prod read-only api`
- 对编辑器保存接口建立统一客户端 SDK，避免组件直接散落 `fetch('/api/...')`
- LLM 代理也建议独立成 `server/` 或 `scripts/dev-server/`，不要继续长在构建配置里
## P1：持久化策略分散，且直接序列化大状态对象
证据：
- `src/hooks/useGamePersistence.ts:152-167` 会在状态变化时自动把完整快照写入 `localStorage`
- `src/hooks/useGamePersistence.ts:157-163` 快照包含 `gameState + bottomTab + currentStory`
- `src/hooks/useGamePersistence.ts:68-116` 恢复逻辑已经开始承担大量 schema 纠偏职责
- `src/data/customWorldLibrary.ts:1-282` 自定义世界库单独维护一套 `localStorage` 读写与 normalize
- `src/hooks/useGameSettings.ts` 也单独维护一套本地设置持久化
影响：
- 状态结构一旦继续膨胀，快照写入频率和反序列化成本都会增加
- schema 迁移会越来越依赖手工 normalize 补丁
- 不同持久化入口各写一套 parser / normalizer，风格和鲁棒性难统一
- 当前保存的是“运行中大对象”，而不是“稳定领域快照”，长期会放大兼容成本
建议：
- 建立统一的 persistence 层，集中管理 key、version、migration、节流、序列化策略
- 对 `GameState` 做“可持久化切片”和“运行时临时切片”分层
- 自动保存增加节流/去抖，避免每次状态波动都全量落盘
- 如果继续扩展角色聊天、自定义世界、编辑器草稿，建议评估 IndexedDB 替代 `localStorage`
## P1：运行时与编辑器仍在同一个前端入口体系中，包体继续膨胀
证据：
- `src/main.tsx:21-34` 通过 `window.location.pathname` 手写分发页面
- `src/main.tsx:60` 只有“游戏”和“PresetEditor”两个大入口
- `PresetEditor`、`ItemCatalogEditor`、`StateFunctionEditor` 都属于重型模块
- 构建产物已经出现 `App` 约 `407 KB`、`itemCatalog` 约 `414 KB` 的 chunk
影响：
- 游戏端与编辑器端的演进节奏被绑定在一个 SPA 入口上
- 编辑器相关数据和静态资源容易继续抬高构建体积
- 未来增加更多编辑器页、更多世界模板、更多资源目录后，冷启动成本会更明显
建议：
- 将编辑器拆成独立入口，至少做成独立 route module，而不是单个 `PresetEditor`
- 继续下钻按 tab 做懒加载，尤其是 `items/functions/npcs`
- 将静态大数据、资源目录索引、编辑器专用预览逻辑做更细的 chunk 拆分
- 如果项目后续会长期保留编辑器，建议直接分成 game app / editor app 两个 entry
## P2：编辑器基础设施重复实现较多
证据：
- `src/components/PresetEditor.tsx:111-181` 自己实现 `cloneValue`、`saveJsonObject`
- `src/components/StateFunctionEditor.tsx:113-130` 再次实现 `cloneValue`、`SectionCard`
- `src/components/ItemCatalogEditor.tsx:94` 再次实现保存请求
- `src/hooks/useInventoryFlow.ts:8`、`src/hooks/useEquipmentFlow.ts:10`、`src/hooks/useForgeFlow.ts:12`、`src/hooks/useTreasureFlow.ts:10` 重复声明 `CommitGeneratedState`
影响：
- 修改保存行为、错误处理、深拷贝策略时需要多处同步
- 编辑器 UI 风格与交互行为容易逐步漂移
- 公共契约没有收拢到共享层，维护成本会逐步抬高
建议：
- 抽 `editor/shared/` 层，集中放保存 SDK、表单字段、卡片容器、克隆工具、错误处理
- 抽通用的 `CommitGeneratedState` 类型定义
- 将编辑器请求和覆盖保存逻辑统一走一个 client
## P2：类型系统已经出现“总文件过载”
证据：
- `src/types.ts` 共 663 行
- `src/types.ts:1-260` 同时包含世界、动画、技能、对话、自定义世界、物品等类型
- `src/types.ts:536-663` 又继续承接剧情、聊天、任务、`GameState`、AI 响应
影响：
- 任一领域类型变化都会增加总文件冲突概率
- 新人理解类型边界成本高
- 编辑器类型、运行时类型、AI 传输类型被放在一起，不利于演化
建议：
- 按领域拆分：`types/combat.ts`、`types/story.ts`、`types/item.ts`、`types/customWorld.ts`、`types/persistence.ts`
- `GameState` 相关类型与 editor override 类型分开
- AI request/response contract 单独收口，避免继续堆进总类型文件
## P2：AI 客户端层过厚，且重复了多套请求与解析逻辑
证据：
- `src/services/ai.ts` 共 1153 行
- `src/services/ai.ts:540-605`、`608-678`、`745-790` 分别手写了 JSON completion、纯文本 completion、流式 completion
- `src/services/ai.ts:680-697` 手写了多段 JSON 解析兜底
- `src/services/ai.ts:76-78`、`591-594`、`662-666` 主要依赖 `console.*` 打日志
影响：
- LLM 行为扩展时容易继续复制请求模板、错误处理、超时逻辑
- 错误分类不够稳定，观测主要停留在 console 层
- prompt、transport、fallback、parse 被放在一起，后续测试和替换模型都不够轻
建议：
- 抽 `llmClient`，统一 transport、timeout、stream、error taxonomy
- 抽 `llmParsers`，将 JSON parse / plain text parse / suggestion parse 独立
- 为关键 prompt 输出建立 fixture 测试，至少覆盖 fallback 与异常响应
- 如果后续要接多个模型，尽早把 provider 层和 prompt 层解耦
## P2：手写路由与死代码开始累积
证据：
- `src/main.tsx:21-34` 采用手写 `pathname.startsWith(...)`
- `src/components/GameShell.tsx:1511` 存在 `false && showTeamModal`
影响：
- 路由能力不具备可扩展性，也不利于后续加 404、重定向、权限判断、嵌套路由
- 死代码继续堆积后，会误导维护者对真实入口和真实 UI 状态的判断
建议：
- 引入正式路由层，哪怕只做轻量路由也比手写分发更清晰
- 清理已经废弃的 UI 分支和不可达逻辑
- 对“临时下线的功能”改为 feature flag 或明确注释，不要用 `false &&`
## 建议落地顺序
### 第一阶段：先补工程底座
- 增加 ESLint / Prettier / EditorConfig
- 增加 `test` 脚本与 Vitest
- 把 CI 最小闭环搭起来：类型检查、单测、build、内容校验
### 第二阶段：先拆边界，再拆大文件
- 先把 Vite 中的编辑器写文件接口、LLM 代理抽走
- 再把 `GameShell`、`useStoryGeneration`、`useCombatFlow` 按职责拆域
- 拆分时优先保持外部接口稳定，避免一次性全仓大改
### 第三阶段：收敛基础设施
- 统一 persistence 层
- 统一 editor shared 层
- 统一 AI client 层
- 拆分 `types.ts`
### 第四阶段：降低发布成本
- 将 editor 与 game 做更明确的入口拆分
- 优化 chunk 边界
- 评估是否把编辑器做成独立 app
## 一句话结论
这个仓库当前最需要优化的不是“再补几个功能”，而是**把已经验证有效的玩法与工具链，从“靠大文件和经验串起来”升级为“靠清晰边界、统一基础设施和自动化门禁支撑起来”**。只要这一步不做，后续每次加内容、加编辑器能力、加 AI 流程，工程成本都会持续上升。

290
docs/audits/engineering/ENGINEERING_OPTIMIZATION_REVIEW_2026-03-30.md
View File

@@ -1,290 +0,0 @@
# 工程优化审查报告（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 门禁变硬、再顺手压缩运行时大模块。只要这一步补上，后续加剧情、加编辑器能力、加自定义世界都会轻很多。

200
docs/audits/engineering/ENGINEERING_OPTIMIZATION_REVIEW_2026-04-01.md
View File

@@ -1,200 +0,0 @@
# 工程优化审查报告（2026-04-01）
## 审查范围
- 扫描范围：`src/`、`scripts/`、`docs/`、`.github/`、`package.json`、`tsconfig*.json`、`vite.config.ts`、`vitest.config.ts`
- 审查方式：阅读当前工作区代码结构，抽查核心运行时、编辑器、服务层与开发脚本，并执行工程命令验证现状
- 当前快照说明：仓库存在大量未提交改动，本报告基于当前工作区状态，不假定这些改动都已经合入主分支
- 说明：按仓库要求，不把中文乱码本身当成本次审查重点；只讨论工程结构、门禁、可维护性、可测试性和扩展成本
## 已执行检查
- `npm run lint:eslint`
结果：失败。`src/components/ItemCatalogEditor.tsx:167` 存在未使用的 `isSearchPending` 和 `startTransition`
- `npm run typecheck`
结果：通过
- `npm run test`
结果：通过，默认套件实际执行 10 个测试文件、28 个测试
- `npm run build`
结果：通过，但 `src/services/customWorldPresentation.ts:163-169` 出现 duplicate key 警告
- `npm run check:content`
结果：通过
## 当前结论
这轮代码库已经明显比前几版更有工程骨架了，至少有这些积极变化：
- `src/main.tsx` + `src/routing/appRoutes.tsx` 已经承担了入口路由分发
- `src/App.tsx` 已经比过去瘦很多，主流程开始交给 hook 和壳组件
- `src/components/PresetEditor.tsx` 已经成为较薄的 lazy shell，而不是继续堆成巨型入口
- `src/editor/shared/jsonClient.ts`、`src/persistence/`、`src/hooks/combat/`、`src/hooks/story/` 这些目录说明仓库已经开始做分层
- CI、Vitest、ESLint、内容校验脚本都已经接上，不再是完全裸奔状态
但从工程角度看，当前最值得优先优化的，不是继续加功能，而是把“半完成的工程化”补齐。核心问题集中在 6 个方面。
## P0：质量门禁和真实风险点仍然脱节
### 现状
仓库已经引入了 lint、typecheck、test、build 和 content checks，但关键热区并没有真正纳入统一门禁。
### 证据
- `.eslintrc.cjs:47-63` 的 `ignorePatterns` 直接跳过了多个高复杂度核心文件：
`src/components/AdventurePanel.tsx`、`src/components/NpcVisualEditor.tsx`、`src/components/preset-editor/PresetEditorPanels.tsx`、`src/hooks/useStoryGeneration.ts`、`src/services/customWorldPresentation.ts`
- `tsconfig.typecheck-guardrails.json:6-15` 只对非常有限的一小组文件开启严格类型检查，远没有覆盖主运行时链路
- `vitest.config.ts:8-10` 把 `customWorldPresentation` 映射到 stub，`vitest.config.ts:20` 还排除了真实存在的 `src/services/ai.test.ts`
- 当前 `src/` 下共有 161 个文件，测试文件共有 11 个，但默认套件只执行其中 10 个
- `npm run build` 已经能暴露 `src/services/customWorldPresentation.ts:163-169` 的 duplicate key 警告，但这块文件同时被 ESLint ignore、被 Vitest stub 掉，说明真实风险没有被完整看见
### 影响
- 工程信号不一致：`test` 绿、`build` 过，不代表关键模块真的健康
- 复杂模块越是难测，越容易被长期豁免，最后演变成“最关键的地方最不受控”
- 后续重构会缺乏可靠的回归保护，review 只能更多依赖人工记忆
### 建议
- 先缩小 `.eslintrc.cjs` 的 ignore 范围，优先把 `useStoryGeneration.ts`、`customWorldPresentation.ts`、`PresetEditorPanels.tsx` 拉回 lint
- 把 `src/services/ai.test.ts` 重新纳入默认测试套件，除非有明确且短期的阻塞原因
- 不要长期依赖 `tsconfig.typecheck-guardrails.json` 的 allowlist，至少把 `src/hooks/`、`src/services/`、`src/components/game-shell/` 逐步纳入 strict 范围
- 对 build warning 建立明确策略：要么在 CI 中失败，要么把 warning 收敛到零
## P0：当前工作区不在真正的绿色基线
### 现状
当前代码不是“纯优化空间”问题，而是已经存在直接可见的门禁破口。
### 证据
- `package.json:11-15` 把 `lint:eslint` 和 `typecheck` 定义成正式脚本，说明它们本来就属于项目基线
- 实际执行 `npm run lint:eslint` 时，`src/components/ItemCatalogEditor.tsx:167` 报出未使用变量错误
- `src/components/ItemCatalogEditor.tsx:167` 引入了 `useTransition()` 返回值，但当前组件没有消费它
- `npm run build` 虽然成功，但 `src/services/customWorldPresentation.ts:163-169` 仍然有重复 object key 警告
### 影响
- 团队会越来越难区分“可接受的技术债”和“已经破坏基线的问题”
- 继续叠加功能会把问题扩散到更多文件，后面补起来成本更高
### 建议
- 先恢复工作区绿色基线，再继续推进大功能
- 把“lint 零错误、build 零 warning”作为下一轮工程整理的硬目标
## P1：运行时主链路仍然被少数超级模块吸住
### 现状
入口已经变薄，但主复杂度仍集中在少数大文件里，尤其是故事推进、战斗同步和界面编排三层。
### 证据
- `src/hooks/useStoryGeneration.ts` 当前约 2210 行
- `src/hooks/useStoryGeneration.ts:694` 导出主 hook，`src/hooks/useStoryGeneration.ts:1416` 接入 `useTreasureFlow`，后面还继续承接 NPC 互动、库存、打字机、AI、历史推进和故事回写
- `src/hooks/useCombatFlow.ts:134` 是主战斗 hook，`src/hooks/useCombatFlow.ts:796-832` 仍然负责逃跑流程与 story sync 的耦合
- `src/components/GameShell.tsx` 当前约 791 行，`src/components/GameShell.tsx:260-269` 管理一组本地 UI 状态，`src/components/GameShell.tsx:482` 继续处理场景切换时的选择编排
- 构建产物里 `dist/assets/App-*.js` 约 389 kB，`dist/assets/index-*.js` 约 198 kB，说明主运行时 chunk 仍然偏重
### 影响
- 任何一个功能变化都容易跨 story、combat、transition、panel 几条链一起改
- hook 单测越来越难写，因为副作用、异步和 UI 编排仍然混在一起
- App 主 chunk 偏重，会继续拖累首屏和回归速度
### 建议
- 继续把 `useStoryGeneration` 收敛成 orchestration 层，把 treasure、NPC、inventory、chat、typewriter、AI 回写拆成更纯的领域 action
- 让 `useCombatFlow` 更明确地区分“战斗结算”和“播放同步”
- 把 `GameShell` 进一步下沉为 scene transition、selection flow、overlay panel 三类 view-model
## P1：编辑器共享层只迁移了一半，重复基础设施还在
### 现状
编辑器入口已经做了 shell 化，但真正的复杂度仍然堆在大型面板组件里，而且共享层没有吃干净。
### 证据
- `src/components/PresetEditor.tsx:41` 的入口已经很薄，说明方向是对的
- 但 `src/components/preset-editor/PresetEditorPanels.tsx` 仍然约 2163 行
- `src/components/preset-editor/PresetEditorPanels.tsx:55` 仍然自带 `cloneValue`
- `src/components/preset-editor/PresetEditorPanels.tsx:117` 仍然自带 `saveJsonObject`
- `src/components/preset-editor/PresetEditorPanels.tsx:189` 仍然自带 `SectionCard`
- 与之对应，`src/editor/shared/jsonClient.ts:29-40` 已经提供了共享版 `fetchJson` / `saveJsonObject`
- `src/components/preset-editor/PresetEditorPanels.tsx:364`、`:1128`、`:1500`、`:1806` 仍然把四个大型 panel 放在同一个文件里
### 影响
- 编辑器的保存、错误处理、基础 UI 容器会继续多处复制，后续很难统一行为
- 迁移看起来开始了，但没有真正收尾，维护者仍然需要在“大文件 + 共享层”之间来回切换
### 建议
- 继续把 `PresetEditorPanels.tsx` 拆成按 tab 或按领域分文件
- 统一复用 `src/editor/shared/` 下的保存客户端、基础容器、表单片段
- 对编辑器做一次“小型迁移收尾”，目标是消灭重复的基础 helper
## P1：本地开发 API 层与构建工具耦合过深
### 现状
本地 API 插件已经把很多临时逻辑吸收进项目内部，这是好事；但它现在承担的职责太多，且全部挂在 Vite 插件层。
### 证据
- `vite.config.ts:7-18` 直接把 `createLocalApiPlugins(__dirname, env)` 注入到 Vite config
- `scripts/dev-server/localApiPlugins.ts` 当前约 394 行
- `scripts/dev-server/localApiPlugins.ts:150` 定义 LLM proxy 插件
- `scripts/dev-server/localApiPlugins.ts:216` 定义通用 JSON 文件编辑插件
- `scripts/dev-server/localApiPlugins.ts:265` 直接把编辑器保存结果写回 `src/data/*.json`
- `scripts/dev-server/localApiPlugins.ts:429` 再统一把所有插件拼到一起
### 影响
- dev server、preview server、编辑器持久化和 LLM 代理被绑在一个文件里，测试与替换成本都偏高
- 随着编辑器继续扩张，这个文件会继续演化成“隐形后端”
- 生产与开发环境的边界容易模糊，问题排查也更依赖熟悉 Vite 插件机制的人
### 建议
- 至少先按职责把 `localApiPlugins.ts` 拆成 `llm-proxy`、`json-editor-api`、`asset-catalog` 三块
- 下一阶段可以考虑把编辑器 API 抽成独立本地服务层，而不是继续塞在 Vite 插件里
- 给 JSON 写入接口补 schema 校验，而不只是“是 object 就写入”
## P2：构建体积仍有继续优化空间
### 现状
路由 lazy load 和部分 modal lazy load 已经做了，但主游戏运行时包仍然偏大。
### 证据
- `dist/assets/App-*.js` 约 389 kB
- `dist/assets/index-*.js` 约 198 kB
- `dist/assets/index-*.css` 约 117 kB
- `src/components/GameShell.tsx`、`src/hooks/useStoryGeneration.ts`、`src/services/prompt.ts` 仍然是较大的主链路文件
### 影响
- 新人本地启动、构建和回归阅读成本仍然偏高
- 主运行时模块越重，越不利于后续继续做场景扩展和编辑器共存
### 建议
- 优先沿着“运行时 orchestration 拆分”去减主 chunk，而不是单纯追求更多 lazy import
- 对 `prompt`、自定义世界、编辑器预览等非首屏关键代码继续做边界拆分
- 每轮重构后用真实构建产物复测，而不是只凭代码体感判断
## 建议的落地顺序
1. 先恢复绿色基线：修掉 `ItemCatalogEditor` lint 错误，处理 `customWorldPresentation` 的 duplicate key warning
2. 再补齐门禁：缩小 ESLint ignore、把 `ai.test.ts` 拉回默认测试、扩大 strict typecheck 覆盖
3. 然后拆主链：优先处理 `useStoryGeneration`、`useCombatFlow`、`GameShell`
4. 再做编辑器迁移收尾：拆 `PresetEditorPanels.tsx`，统一共享层
5. 最后处理 dev API 分层和 bundle 体积
## 一句话结论
这个仓库已经从“功能堆叠期”进入“工程收尾期”了。当前最值得做的不是再加一层玩法，而是把门禁补齐、把超级模块拆开、把半迁移状态收尾；只要这一步做稳，后续继续扩展剧情、编辑器和自定义世界的成本都会明显下降。

2
docs/audits/engineering/FRONTEND_LOGIC_BACKEND_MIGRATION_AUDIT_2026-04-21.md
View File

@@ -40,7 +40,7 @@
### 2.1 文档依据
1. `docs/experience/PROJECT_WORK_EXPERIENCE_PLAYBOOK.md`
2. `docs/planning/EXPRESS_BACKEND_REFACTOR_PLAN_2026-04-08.md`
2. `docs/technical/CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md`
3. `docs/technical/RUNTIME_STORY_BACKEND_BOUNDARY_MIGRATION_2026-04-19.md`
4. `docs/audits/engineering/ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-20.md`
5. `docs/audits/engineering/CURRENT_ENGINEERING_OPTIMIZATION_OPPORTUNITIES_2026-04-20.md`

39
docs/audits/engineering/README.md
View File

@@ -1,36 +1,31 @@
# 工程优化审查总览
这一组是同主题的连续审查记录，建议不要把它们当作三份彼此独立的文档来看。
这一组只保留仍能指导当前 Rust / SpacetimeDB 主线的工程审查入口。早期连续扫描的有效结论已经合并到本 README 的“融合结论”，不再保留逐日旧稿。
## 当前推荐入口
1. [ENGINEERING_DEAD_CODE_CLEANUP_BATCH_F_2026-04-21.md](./ENGINEERING_DEAD_CODE_CLEANUP_BATCH_F_2026-04-21.md)
1. [SERVER_NODE_FREEZE_AND_DEPRECATION_2026-04-24.md](./SERVER_NODE_FREEZE_AND_DEPRECATION_2026-04-24.md)
这一版是旧 Node 后端冻结、第一批物理删除与后续批次边界记录，明确当前工程只保留 Rust / SpacetimeDB 主线入口。
2. [ENGINEERING_DEAD_CODE_CLEANUP_BATCH_F_2026-04-21.md](./ENGINEERING_DEAD_CODE_CLEANUP_BATCH_F_2026-04-21.md)
这一版是第六批落地记录，聚焦删除无入口 `questDirector`、旧观察文案 helper、一次性硬编码同步脚本，并补齐后端运行时 function catalog 契约覆盖。
2. [ENGINEERING_DEAD_CODE_CLEANUP_BATCH_E_2026-04-21.md](./ENGINEERING_DEAD_CODE_CLEANUP_BATCH_E_2026-04-21.md)
3. [ENGINEERING_DEAD_CODE_CLEANUP_BATCH_E_2026-04-21.md](./ENGINEERING_DEAD_CODE_CLEANUP_BATCH_E_2026-04-21.md)
这一版是第五批落地记录，聚焦旧命名 re-export、空路由骨架、旧发布服务、前端 prompt 镜像与无入口编辑器壳层的物理删除。
3. [FRONTEND_LOGIC_BACKEND_MIGRATION_AUDIT_2026-04-21.md](./FRONTEND_LOGIC_BACKEND_MIGRATION_AUDIT_2026-04-21.md)
这一版是本轮前端越界逻辑专项审计，专门汇总当前仍应继续迁到 Express 后端的运行时、鉴权、生成编排与本地真相残留。
4. [ENGINEERING_DEAD_CODE_CLEANUP_BATCH_D_2026-04-21.md](./ENGINEERING_DEAD_CODE_CLEANUP_BATCH_D_2026-04-21.md)
4. [FRONTEND_LOGIC_BACKEND_MIGRATION_AUDIT_2026-04-21.md](./FRONTEND_LOGIC_BACKEND_MIGRATION_AUDIT_2026-04-21.md)
这一版是本轮前端越界逻辑专项审计，专门汇总当前仍应继续迁到 `server-rs` 的运行时、鉴权、生成编排与本地真相残留。
5. [ENGINEERING_DEAD_CODE_CLEANUP_BATCH_D_2026-04-21.md](./ENGINEERING_DEAD_CODE_CLEANUP_BATCH_D_2026-04-21.md)
这一版是第四批落地记录，聚焦未接入业务的数据生成产物、测试专用 stub 与对应配置残留出清。
5. [ENGINEERING_DEAD_CODE_CLEANUP_BATCH_C_2026-04-21.md](./ENGINEERING_DEAD_CODE_CLEANUP_BATCH_C_2026-04-21.md)
6. [ENGINEERING_DEAD_CODE_CLEANUP_BATCH_C_2026-04-21.md](./ENGINEERING_DEAD_CODE_CLEANUP_BATCH_C_2026-04-21.md)
这一版是第三批落地记录，聚焦鉴权真相收口，先移除前端保存自动登录用户名/密码的本地真相，并明确运行时快照前置写入为什么当前还不能硬砍。
6. [ENGINEERING_DEAD_CODE_CLEANUP_BATCH_B_2026-04-21.md](./ENGINEERING_DEAD_CODE_CLEANUP_BATCH_B_2026-04-21.md)
7. [ENGINEERING_DEAD_CODE_CLEANUP_BATCH_B_2026-04-21.md](./ENGINEERING_DEAD_CODE_CLEANUP_BATCH_B_2026-04-21.md)
这一版是第二批落地记录，聚焦旧主流程壳层、旧 bootstrap 和旧 inventory / forge / equipment flow Hook 的正式出清。
7. [ENGINEERING_DEAD_CODE_CLEANUP_BATCH_A_2026-04-21.md](./ENGINEERING_DEAD_CODE_CLEANUP_BATCH_A_2026-04-21.md)
8. [ENGINEERING_DEAD_CODE_CLEANUP_BATCH_A_2026-04-21.md](./ENGINEERING_DEAD_CODE_CLEANUP_BATCH_A_2026-04-21.md)
这一版是第一批落地记录，聚焦高置信度小型孤岛、prompt 壳子、stub 和无入口 modal 的首轮清理。
8. [CURRENT_ENGINEERING_OPTIMIZATION_OPPORTUNITIES_2026-04-20.md](./CURRENT_ENGINEERING_OPTIMIZATION_OPPORTUNITIES_2026-04-20.md)
9. [CURRENT_ENGINEERING_OPTIMIZATION_OPPORTUNITIES_2026-04-20.md](./CURRENT_ENGINEERING_OPTIMIZATION_OPPORTUNITIES_2026-04-20.md)
这一版是面向当前仓库状态的优化点盘点，适合直接拿来排优先级和拆执行批次。
9. [ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-20.md](./ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-20.md)
10. [ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-20.md](./ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-20.md)
这一版是对 `2026-04-19` 基线的当前仓库复核，明确哪些问题已经处理、哪些表述需要纠正、热点又迁移到了哪里。
10. [ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-19.md](./ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-19.md)
11. [ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-19.md](./ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-19.md)
这一版保留原始问题快照和执行回填，适合回看“为什么会有这轮清理与边界收口”。
11. [ENGINEERING_OPTIMIZATION_REVIEW_2026-04-01.md](./ENGINEERING_OPTIMIZATION_REVIEW_2026-04-01.md)
这一版最适合作为当前工程基线，重点从“是否真正绿色”“门禁有没有覆盖真实风险”来判断仓库状态。
12. [ENGINEERING_OPTIMIZATION_REVIEW_2026-03-30.md](./ENGINEERING_OPTIMIZATION_REVIEW_2026-03-30.md)
适合回看运行时主链路、Story/Combat 边界、分层过渡期问题。
13. [ENGINEERING_OPTIMIZATION_REVIEW_2026-03-29.md](./ENGINEERING_OPTIMIZATION_REVIEW_2026-03-29.md)
适合看第一轮系统性工程扫描，了解最早的问题基线。
## 融合结论
- 最新专项审计已经把“前端哪些逻辑还该后移到后端”收敛到 6 类：运行时快照、本地 token、本地浏览历史、NPC 委托换单、quest/runtime item 混合编排、浏览器 AI orchestration。
@@ -43,11 +38,9 @@
- 当前仓库已经完成“旧 dev 插件链路删除、根目录噪音清理、`server-node -> src/**` 反向依赖切断”这批第一阶段任务。
- 当前如果想直接判断“今天先优化什么”，优先看 `CURRENT_ENGINEERING_OPTIMIZATION_OPPORTUNITIES_2026-04-20.md`。
- 当前的新重点已经进一步收敛到三类：未接线孤岛模块、前端残留的运行时/鉴权真相、热点向 prompt/runtime profile/平台入口壳层迁移。
- 三轮结论是一致收敛的：问题不在“有没有开始工程化”，而在“工程化是否真正覆盖了最危险的主链路”。
- 最新一轮已经把关注点集中到质量门禁、真实绿色基线、关键模块豁免和 build warning 上。
- 早期三轮工程扫描的结论已经聚合为一条长期规则：工程化不能只看目录和拆分动作，必须覆盖真实主链、质量门禁、绿色基线、关键模块豁免和 build warning。
- `2026-04-19` 这一轮把问题压实到了四类：仓库噪音、旧 dev 入口残留、前端越界运行时逻辑、巨型热点文件。
- `2026-04-20` 这一轮进一步确认：前两类已经阶段性完成，当前真正剩下的是边界尾巴和新热点迁移。
- 如果只是为了判断现在先做什么，直接从 `2026-04-01` 开始即可。
- 如果是要看当前清理和边界收口的最新状态，优先看 `ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-20.md`。
- 如果是要看“当前可执行的优化点清单”，优先看 `CURRENT_ENGINEERING_OPTIMIZATION_OPPORTUNITIES_2026-04-20.md`。
- 如果是要做长期重构方案，再按 `2026-03-29 -> 2026-03-30 -> 2026-04-01 -> 2026-04-19 -> 2026-04-20` 的顺序回看演进。
- 如果是要做长期重构方案，从 `2026-04-19`、`2026-04-20` 与当前 dead-code batch 记录开始即可。

65
docs/audits/engineering/SERVER_NODE_FREEZE_AND_DEPRECATION_2026-04-24.md
View File

@@ -12,11 +12,11 @@
2. 禁止新增从前端、Rust 后端、脚本或配置主动调用 `server-node/` 的逻辑。
3. 禁止在 `server-node/` 内继续新增业务能力；后续能力必须落到 `server-rs/` 对应 crate。
4. 历史文档、审计文档、迁移基线中允许保留 `server-node/` 作为旧系统来源说明，但不得把它描述成当前推荐实现。
5. 删除 `server-node/` 前，必须先完成提示词资产与提示词相关工作流的最终迁移确认。
5. 第一批物理删除后，提示词资产与提示词相关工作流继续按迁移核对项追踪，不再恢复旧工程目录。
## 3. 删除前阻断项
## 3. 删除前迁移核对项
以下资产仍需要在删除目录前逐项确认迁移或废弃：
以下资产曾作为删除前核对项。第一批物理删除后，旧实现不再从工作区直接读取；如需继续核对能力缺口，只允许通过历史提交、迁移文档或 `server-rs/` 已迁移实现追溯：
1. `server-node/src/prompts/customWorldEntityPrompts.ts`：自定义世界实体生成 prompt。
2. `server-node/src/prompts/customWorldSceneNpcPrompts.ts`：自定义世界场景 NPC prompt。
@@ -27,17 +27,17 @@
## 4. 工程防线
1. 根目录 `package.json` 中的 `server-node:*` 脚本统一改为冻结失败入口。
2. 新增 `npm run check:server-node-freeze`，用于阻止新增 `server-node` 引用。
3. 新增 `scripts/server-node-frozen.mjs`，任何旧 `server-node:*` 入口被误执行时都会直接失败并提示迁移到 `server-rs/`。
4. 新增 `scripts/server-node-freeze-baseline.json`，只允许冻结前已经存在的引用继续作为迁移基线存在。
1. 第一批物理删除后，根目录 `package.json` 不再保留 `server-node:*`、`dev:node`、`check:server-node-freeze` 等旧入口。
2. Vite、Caddy 与本地开发脚本默认只指向 Rust `api-server`，不再保留 Node/Rust 后端切换开关。
3. 历史文档允许保留旧 `server-node` 字样，但新增工程入口、脚本、依赖、运行说明不得再指向旧 Node 后端。
4. 若后续需要恢复旧能力，只能迁移到 `server-rs/` 对应 crate 或 Axum facade，不恢复 `server-node/` 工程目录。
## 5. 后续处理顺序
1. 优先迁移或废弃提示词资产与 prompt 工作流。
2. 确认前端不再通过任何路径调用 Node 后端能力。
3. 删除旧脚本、旧 smoke、旧 manifest 与 `server-node/` 目录。
4. 删除冻结基线检查中对历史引用的豁免。
1. 继续核对提示词资产与 prompt 工作流是否已完整落到 Rust 主线。
2. 继续把前端残留业务编排迁入 `server-rs/`。
3. 清理技术索引中容易误导当前入口的 Node / Express 文案。
4. 保留历史审计材料，但不得把旧 Node 后端描述为当前推荐实现。
## 6. 已确认迁移项
@@ -50,3 +50,46 @@
3. 使用位置：`generate_draft_foundation_act_backgrounds(...)` 收集 `sceneChapterBlueprints[].acts[]` 后，先构造幕背景图专用提示词，再调用 `generate_custom_world_scene_image_for_profile(...)`。
4. 保留语义：世界名、场景名、幕标题、幕摘要、幕目标、过渡钩子、主角色、辅助角色、世界气质、背景描述，以及“只生成环境背景，不出现角色立绘、站位 UI、对白框、按钮或文字”的约束。
5. 迁移边界：`server-node/` 仅作为历史来源说明，不再参与运行；后续调整统一修改 Rust 主源。
## 7. 第一批安全删除记录（2026-04-25）
本批次开始把冻结隔离升级为物理删除。执行依据是项目后端主线已固定为 `server-rs/` 的 Rust + SpacetimeDB 多 crate 方案，旧 `server-node/` 不再作为可运行、可扩展、可引用的工程目录保留。
### 7.1 删除范围
1. 删除 `server-node/` 目录本体，旧实现只允许通过历史提交、迁移文档和已迁移到 `server-rs/` 的代码追溯。
2. 删除旧 Node 后端专用入口：`scripts/dev-node.mjs`、`scripts/server-node-frozen.mjs`、`scripts/check-server-node-freeze.mjs`、`scripts/server-node-freeze-baseline.json`、`scripts/smoke-server-node.ts`、`scripts/smoke-same-origin-stack.ts`、`scripts/m7-api-compare.ts`、`scripts/deploy.sh`、`scripts/update.sh`、`view-llm-logs.ps1`。
3. 根目录 `package.json` 删除 `server-node:*`、`dev:node`、`m7:api-compare` 与 `check:server-node-freeze` 等旧入口，并移除 `express`、`@types/express` 依赖。
4. `npm run dev` 改为启动 Rust 本地栈；Vite 和 Caddy 默认只代理到 Rust `api-server`，不再保留 `GENARRATIVE_BACKEND_STACK` 的 Node/Rust 双栈切换口。
5. 清理 `.gitignore` 中只服务 `server-node/` 的忽略规则，并同步 `README.md`、`.env.example`、`server-rs/README.md` 与 `scripts/dev-server/README.md`。
### 7.2 暂不处理范围
1. 历史 PRD、审计、迁移基线中的 `server-node` 文案暂时保留为历史记录，不在第一批中大规模改写。
2. `backend-rewrite-tasklist/` 中以旧 Node 后端为对照的迁移材料暂时保留，作为后续核对 Rust 主线能力缺口的历史审计输入。
3. `src/services/ai.ts` 与 `src/prompts/customWorldPrompts.ts` 的前端残留编排不属于本批 Node 后端删除范围；后续继续按“前端只负责表现，业务逻辑进入 `server-rs/`”单独收口。
### 7.3 后续批次建议
1. 技术文档索引中的 Node / Express 后端条目只保留为历史资料，不再作为当前入口或推荐方案。
2. 后续如继续整理历史文档，只把仍描述 `Express / PostgreSQL` 为当前目标架构的文字修正为“历史阶段口径”。
3. 继续把前端残留业务逻辑迁入 `server-rs`；涉及 SpacetimeDB 的设计、实现、脚本和绑定继续显式使用相关 skill。
### 7.4 本轮安全核对结果
2026-04-25 本轮开始分批删除时，已确认第一批工程入口层面满足以下条件：
1. 工作区根目录下已不存在 `server-node/` 物理目录。
2. `scripts/` 下已不存在旧 Node 后端专用运行、冻结、smoke、API 对比脚本。
3. 根目录 `package.json` 不再包含 `server-node:*`、`dev:node`、`m7:api-compare` 与 `check:server-node-freeze` 入口。
4. `package.json` 与 `package-lock.json` 不再包含 `express`、`@types/express`、`pg`、`postgres` 依赖包。
5. `README.md`、`scripts/dev-server/README.md`、`server-rs/README.md`、`vite.config.ts`、`scripts/*.mjs`、`src/`、`packages/` 与 `server-rs/` 未发现仍主动启动或调用 `server-node` 的当前工程入口。
### 7.5 第二批删除边界
第二批不再删除可运行工程代码，而是清理“容易误导当前实现口径”的历史文档索引：
1. 只修正文档中仍把 `server-node`、Express 或 PostgreSQL 描述为当前推荐后端的句子。
2. 保留审计、PRD、迁移基线中作为历史事实、旧实现来源、能力对照的 `server-node` 引用。
3. 不大规模重写包含中文剧情、需求、审计结论的历史文档，避免把真实历史上下文抹平。
4. 若发现某个历史文档仍指导新开发继续写 Node 后端，先把该文档改为“历史阶段口径”，再继续工程处理。