Merge branch 'master' into stdb

2026-04-20 05:40:04 +00:00
parent 2d0a267729 8a7bd90458
commit ef72fd156b
277 changed files with 35204 additions and 21510 deletions
--- a/docs/technical/AI_CHARACTER_ANIMATION_TECHNICAL_SOLUTION_2026-04-04.md
+++ b/docs/technical/AI_CHARACTER_ANIMATION_TECHNICAL_SOLUTION_2026-04-04.md
@@ -265,6 +265,23 @@

 但对“第一版角色动作资产生产”来说，它更适合作为增强通道，不建议先做成唯一主依赖。

+实现更新（`2026-04-19`）：
+
+- 当前仓库的 `image-to-video` 角色动作生成入口已切到火山方舟 `Seedance`
+- 采用双参考图首尾帧方案：图片 1 约束首帧，图片 2 约束尾帧
+- 当前请求体中的两张参考图角色分别固定为 `first_frame / last_frame`
+- 当前固定参数为 `1:1`、`480p`、`4 秒`、单次 `1` 个视频
+- 当前固定动作入口收敛为 `idle / run / attack / die`，不再内置固定 `hurt`
+- 提示词里传给视频模型的动作名统一使用英文动作名
+
+实现更新（`2026-04-20`）：
+
+- `run / attack` 是当前固定动作入口里的基础必生成动作
+- `idle / die` 改为可选增强动作，不再作为资产完成度硬门槛
+- `idle` 缺失时运行时默认使用主图静止
+- `die` 缺失时运行时默认播放一段基于主图的倒地过渡动画，并最终停在翻转倒地姿态
+- 技能动作不走固定按钮，但对当前角色 `skills` 中的每个技能都属于必生成动作
+
 ## 5.3 补充路线：腾讯云相关能力

 腾讯云相关接口里，`提交图片跳舞任务` 提供了：
@@ -422,12 +439,17 @@
 - `idle`
 - `run`
 - `attack`
- `jump`
- `hurt`
 - `die`

 系统自动选择对应参考视频模板。

+其中：
+
+- `run / attack` 属于固定必生成动作
+- `idle / die` 属于固定可选动作，未生成时走默认兜底
+
+`jump`、`hurt` 这类扩展动作不再作为当前编辑器固定按钮，改为后续扩展动作槽位或手动补齐。
+
 ### B. 视频驱动

 用户上传参考动作视频，系统抽姿态后再生成角色动作。
@@ -498,6 +520,8 @@ flowchart LR
 - 文生图时，优先生成与当前项目角色素材视角一致的单人全身图
 - 有参考图时，优先做“角色指定 + 风格收敛 + 视角纠偏”
 - 用户直接上传素材时，先做校验、裁切、背景清理和尺寸标准化
+- 编辑器未上传参考图时，主形象阶段默认附加一张由项目内可扮演角色 idle 帧拼成的风格参考板，用来锁定像素动作角色的轮廓语言、右朝向、体型比例与配色组织，避免模型只放大 Q 版比例却丢掉像素感
+- 风格约束优先级里，“像素动作角色感”高于“Q 版比例提示”；比例只允许轻度偏大头，不允许退化成普通软萌插画或儿童绘本风

 ### 角色视角要求

@@ -623,6 +647,16 @@ flowchart LR
 8. 生成 Sprite Sheet
 9. 输出动画元数据

+### 当前工程的抠像补充策略
+
+针对角色动作视频抽帧后常见的“后段帧出现白底”“角色轮廓残留绿幕像素点”问题，当前工程内的背景清理不再只依赖单一绿幕阈值，而是统一改为以下顺序：
+
+1. 先识别边界连通的可移除背景区域，同时覆盖纯绿色绿幕和高亮低色差白底。
+2. 再向主体边缘的半透明软边做一轮有限扩张，把压缩后残留的白边、绿边纳入透明化处理。
+3. 最后对贴近透明边缘的像素做去污，优先压掉绿色溢色，并把白边/绿边颜色拉回附近前景主体颜色，减少抽帧后的轮廓发白、发绿。
+
+这样可以避免把角色内部的白色高光、白色装备整体误删，同时能更稳定地清理视频模型在末段帧里偶发的白背景和压缩噪点。
+
 ### 像素化策略

 推荐做法：
@@ -703,7 +737,14 @@ export interface GeneratedCharacterAnimationAsset {
  id: string;
  characterId: string;
  visualAssetId: string;
-  action: BaseAnimationSlot | 'cast' | 'talk' | 'skill1' | 'skill2' | 'skill3' | 'skill4';
+  action:
+    | BaseAnimationSlot
+    | 'cast'
+    | 'talk'
+    | 'skill1'
+    | 'skill2'
+    | 'skill3'
+    | 'skill4';
  sourceProvider: 'aliyun-wan' | 'volc-seedance' | 'tencent' | 'local';
  sourceMode: 'template' | 'video-drive' | 'audio-drive';
  frameCount: number;
@@ -826,7 +867,8 @@ generatedAnimationOverrides?: Partial<Record<AnimationState, string>>;

 ## 10.3 本地 API 层

-当前项目已经有 `scripts/dev-server/localApiPlugins.ts` 这种本地 API 插件机制，应该复用。
+自 `2026-04-19` 起，旧 `scripts/dev-server/localApiPlugins.ts` 已从仓库删除。  
+当前角色视觉与动画相关 `/api/*` 能力应统一落到 `server-node/src/modules/assets/**` 与 `server-node/src/modules/ai/**`，不再复用旧 Vite 本地插件链路。

 建议新增：

@@ -912,63 +954,54 @@ draft

 ### 12.1 基础动作槽位必须非空

-第一版要求以下基础动作槽位全部有内容：
+第一版要求以下动作能力按“必生成 / 可选兜底”拆开：

-| 动作槽位 | 是否必填 | 建议来源 |
-| --- | --- | --- |
-| `idle` | 必填 | 模板生成 |
-| `acquire` | 必填 | 可由短持物 / 抬手动作生成 |
-| `attack` | 必填 | 模板生成 |
-| `run` | 必填 | 模板生成 |
-| `jump` | 必填 | 模板生成 |
-| `double_jump` | 必填 | 可由跳跃二次变体生成 |
-| `jump_attack` | 必填 | 跳跃攻击模板 |
-| `dash` | 必填 | 冲刺模板 |
-| `hurt` | 必填 | 受击模板 |
-| `die` | 必填 | 倒地 / 消散模板 |
-| `climb` | 必填 | 攀爬模板 |
-| `wall_slide` | 必填 | 可由攀爬或停滞帧变体生成 |
+当前编辑器固定生成入口补充说明（`2026-04-19`）：

-这里“不能为空”指的是：
+- 固定按钮只保留 `idle / run / attack / die`
+- `hurt` 不再作为固定生成按钮
+- 如果运行时仍需 `hurt` 资源，应通过后续扩展动作槽位或手动补齐

- 每个基础动作槽位必须能挂到一套可播放资产
- 不允许在运行时出现 `null` 或空映射
- 个别低优先动作允许由近似动作衍生，但槽位本身必须有有效资源
+| 动作能力                        | 是否必填 | 建议来源                                                   |
+| ------------------------------- | -------- | ---------------------------------------------------------- |
+| `run`                           | 必填     | 模板生成                                                   |
+| `attack`                        | 必填     | 模板生成                                                   |
+| `skills[*].actionPreviewConfig` | 必填     | 技能编辑面板逐个生成                                       |
+| `idle`                          | 可选     | 模板生成；缺失时默认主图静止                               |
+| `die`                           | 可选     | 模板生成；缺失时默认主图倒地过渡动画，最终停在翻转倒地姿态 |

-### 12.2 技能动作不是第一版强制项
+这里“必填”指的是：

-第一版可选：
+- `run / attack` 必须能挂到一套可播放资产
+- 角色当前每个技能都必须有可播放的 `actionPreviewConfig`
+- `idle / die` 不再进入“缺失即阻塞发布”的判断
+- 运行时表现仍然不能空白；`idle / die` 的缺口由默认兜底承接

- `skill1`
- `skill1_jump`
- `skill1_bullet`
- `skill1_bullet_fx`
- `skill2`
- `skill2_jump`
- `skill3`
- `skill3_jump`
- `skill3_bullet`
- `skill3_bullet_fx`
- `skill4`
+### 12.2 技能动作改为“按角色已配技能强制”
+
+第一版不再要求预留整套固定技能枚举，但要求：
+
+- 当前角色 `skills` 数组里的每个技能都要补出 `actionPreviewConfig`
+- 技能动作继续在技能编辑面板逐个生成，不并入固定四按钮

 策略建议：

- 基础动作先全量补齐
- 技能动作后续按角色职业差异再补
+- 先补 `run / attack`
+- 再逐个补当前角色已有技能动作
+- `idle / die` 作为可选增强按需要补
 - 投射物与特效优先继续复用当前项目已有素材与技能特效系统

 ### 12.3 第一阶段优先模板

 先优先做这些高价值模板：

-| 模板 | 推荐时长 | 是否循环 | 说明 |
-| --- | --- | --- | --- |
-| `idle` | 2s-4s | 是 | 微动作、呼吸 |
-| `run` | 2s-3s | 是 | 固定侧向 |
-| `attack` | 2s-4s | 否 | 近战基础攻击 |
-| `jump` | 1s-2s | 否 | 起跳与空中姿态 |
-| `hurt` | 1s-2s | 否 | 受击短动作 |
-| `die` | 2s-4s | 否 | 倒下或消散 |
+| 模板     | 推荐时长 | 是否循环 | 说明           |
+| -------- | -------- | -------- | -------------- |
+| `idle`   | 2s-4s    | 是       | 微动作、呼吸   |
+| `run`    | 2s-3s    | 是       | 固定侧向       |
+| `attack` | 2s-4s    | 否       | 近战基础攻击   |
+| `jump`   | 1s-2s    | 否       | 起跳与空中姿态 |
+| `die`    | 2s-4s    | 否       | 倒下或消散     |

 ### 12.4 不建议第一阶段就重投入的动作

--- a/docs/technical/ALIYUN_NPC_IMAGE_ANIMATION_EXPERIMENT_2026-04-07.md
+++ b/docs/technical/ALIYUN_NPC_IMAGE_ANIMATION_EXPERIMENT_2026-04-07.md
@@ -82,7 +82,8 @@

 ### 2.3 本地 API 插件里已经有 DashScope 接入样板

-`scripts/dev-server/localApiPlugins.ts` 里已经接了自定义世界场景图：
+本文撰写时，旧 `scripts/dev-server/localApiPlugins.ts` 里已经接了自定义世界场景图。  
+截至 `2026-04-19`，该文件已从仓库删除，对应样板能力应改为参考 `server-node/src/modules/assets/**` 与 `server-node/src/modules/ai/**`：

 - 默认 DashScope base URL 已经存在
 - 已经有异步任务创建、轮询、下载、落盘、写 manifest 的完整样板
@@ -480,7 +481,7 @@

 - 最少改 UI
 - 最快复用当前 `CharacterAssetPanel`
- 最容易复用 `localApiPlugins.ts` 里现有 DashScope 异步任务模式
+- 最容易复用现已迁入 `server-node` 的 DashScope 异步任务模式

 ## 9.2 第二轮

@@ -641,5 +642,6 @@
 - `src/components/preset-editor/characterAssetStudioPersistence.ts`
 - `src/routing/appRoutes.tsx`
 - `src/services/ai.ts`
- `scripts/dev-server/localApiPlugins.ts`
+- `server-node/src/modules/assets/**`
+- `server-node/src/modules/ai/**`
 - `docs/technical/AI_CHARACTER_ANIMATION_TECHNICAL_SOLUTION_2026-04-04.md`
--- a/docs/technical/EDITOR_ASSET_API_MIGRATION_2026-04-08.md
+++ b/docs/technical/EDITOR_ASSET_API_MIGRATION_2026-04-08.md
@@ -73,12 +73,12 @@

 ## 5. 旧工具链隔离状态

-`scripts/dev-server/**` 中的旧 Vite 本地插件已经不再由 `vite.config.ts` 注入，也不再作为当前开发入口使用。
+自 `2026-04-19` 起，`scripts/dev-server/**` 中的旧 Vite 本地插件实现代码已经从仓库删除，也不再作为当前开发入口使用。

-旧文件保留用途：
+当前保留状态：

- 作为历史迁移参考。
- 对照旧 DashScope 调用与文件写入逻辑。
+- `scripts/dev-server/` 目录只保留迁移说明 README。
+- 旧链路的历史背景由 `docs/audits/engineering/ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-19.md` 等审计文档承接。

 新增编辑器或资产能力时，应优先写入：

@@ -103,4 +103,4 @@
 - 前端编辑器组件已通过统一 SDK 或资源 ID 访问编辑器 API。
 - Vite 已代理 `/api/editor` 与 `/api/assets` 到 Node 后端。
 - 写接口已经有环境门禁。
- 旧 Vite 本地插件不再是当前工具链入口。
+- 旧 Vite 本地插件代码已删除，不再保留并行实现。
--- a/docs/technical/NODE_SERVER_KNOWLEDGE_GRAPH_2026-04-08.md
+++ b/docs/technical/NODE_SERVER_KNOWLEDGE_GRAPH_2026-04-08.md
@@ -16,7 +16,7 @@

 当前不再使用：

- Vite 本地 API 插件 `scripts/dev-server/` 作为当前接口入口
+- 已删除的旧 Vite 本地 API 插件链路 `scripts/dev-server/*.ts`

 ## 2. 技术栈

@@ -162,6 +162,11 @@ JWT 现状：
 - `POST /api/runtime/items/runtime-intent`
 - `POST /api/runtime/quests/generate`

+补充说明（`2026-04-19`）：
+
+- `POST /api/custom-world/scene-image` 现在支持前端仅提交 `profile + landmark + userPrompt` 上下文，由后端统一补齐场景图 prompt 与默认 negative prompt。
+- runtime story option 的 `interaction` 元数据现在由后端随 option 一并返回，前端不再本地按 `functionId` 重建 NPC / treasure 交互语义。
+
 编辑器工具：

 - `GET /api/editor/catalog/items`
@@ -198,7 +203,11 @@ Story：

 Custom World：

- Node 后端直接复用前端现有多阶段生成编排
+- Node 后端当前已自持 `server-node/src/modules/custom-world/**` 运行时模块
+- 已承接 `creator intent` 归一化、`anchorPack / lockState` 推导、framework normalize、runtime profile compile
+- `customWorldOrchestrator` 与 `customWorldAgentFoundationDraftService` 已不再运行时 import 前端 `src/services/customWorld*.ts` 与 `src/types.js`
+- `server-node/src/prompts/customWorldPrompts.ts` 已承接 foundation draft 与 scene image 使用的 custom world prompt source
+- 上述 prompt 迁移只改变源码归属位置，没有改动提示词正文
 - 当前保留 `session + answers + SSE progress/result/error` 协议
 - 前端已支持接收真实阶段进度对象

@@ -238,4 +247,4 @@ Vite 当前只负责代理，不再提供本地 API 插件。

 全部转发到 Node 后端。

-旧 `scripts/dev-server/**` 文件仅保留为迁移参考，不再由 `vite.config.ts` 注入。
+`scripts/dev-server/` 目录现仅保留 README 作为迁移说明，旧本地 API 实现代码已于 `2026-04-19` 删除。
--- a/docs/technical/PROMPT_DIRECTORY_MANAGEMENT_2026-04-19.md
+++ b/docs/technical/PROMPT_DIRECTORY_MANAGEMENT_2026-04-19.md
@@ -0,0 +1,190 @@
+# Prompt 目录收口方案（2026-04-19）
+
+## 1. 这次调整解决什么问题
+
+此前提示词分散在多个后端、前端和工具文件里：
+
+- `server-node/src/modules/ai/**`
+- `server-node/src/modules/quest/**`
+- `server-node/src/modules/runtime-item/**`
+- `server-node/src/services/customWorld*.ts`
+- `server-node/src/services/eightAnchorPromptBuilder.ts`
+- `server-node/src/modules/assets/characterAssetRoutes.ts`
+- `src/services/**`
+- `src/tools/qwenSpriteSheetToolModel.ts`
+- `src/components/**`
+
+问题主要有三类：
+
+1. 业务逻辑和 prompt 文本混写，改提示词时容易顺手改坏运行时逻辑。
+2. 同一类 prompt 缺少集中入口，排查系统 prompt / user prompt / repair prompt 成本高。
+3. 老桥接层、测试和新业务链路同时依赖时，迁移成本高，容易出现导出断裂。
+
+这次收口目标不是“重写全部 AI 链路”，而是把当前正式业务 prompt 主源收到独立目录，业务模块退化成“准备上下文 + 调用 prompt 脚本”。
+
+## 2. 新目录
+
+本轮落地后的目录：
+
+```text
+packages/shared/src/prompts/
+└─ qwenSprite.ts
+
+server-node/src/prompts/
+├─ characterAssetPrompts.ts
+├─ chatPromptBuilders.ts
+├─ customWorldAgentPrompts.ts
+├─ customWorldEntityPrompts.ts
+├─ customWorldOrchestratorPrompts.ts
+├─ customWorldSceneNpcPrompts.ts
+├─ eightAnchorPrompts.ts
+├─ questPrompts.ts
+├─ runtimeItemPrompts.ts
+├─ storyOrchestratorPrompts.ts
+└─ storyPromptBuilders.ts
+
+src/prompts/
+├─ characterChatPrompts.ts
+├─ customWorldEntityActionPrompts.ts
+├─ customWorldOrchestratorPrompts.ts
+├─ customWorldPrompts.ts
+├─ customWorldRolePromptDefaults.ts
+├─ questPrompts.ts
+├─ qwenSpriteSheetToolPrompts.ts
+├─ runtimeItemPrompts.ts
+├─ storyOrchestratorPrompts.ts
+└─ storyPromptBuilders.ts
+```
+
+当前职责划分：
+
+- `chatPromptBuilders.ts`
+  - 角色私聊 / NPC 聊天 / 招募对话 prompt
+- `storyPromptBuilders.ts`
+  - 主剧情 system prompt 与 user prompt builder
+- `storyOrchestratorPrompts.ts`
+  - 剧情语言修复 prompt
+- `questPrompts.ts`
+  - 任务意图 system prompt 与 user prompt builder
+- `runtimeItemPrompts.ts`
+  - 运行时物品意图 system prompt 与 user prompt 文本装配
+- `customWorldOrchestratorPrompts.ts`
+  - 自定义世界主编排 JSON 生成与 repair prompt
+- `customWorldAgentPrompts.ts`
+  - 世界草稿 JSON prompt、补角色 / 补地点 prompt
+- `customWorldEntityPrompts.ts`
+  - 世界编辑器角色 / 场景实体生成 prompt
+- `customWorldSceneNpcPrompts.ts`
+  - 世界编辑器场景 NPC 生成 prompt
+- `characterAssetPrompts.ts`
+  - 角色主图 / 动作试片 / 角色关联场景 prompt
+- `eightAnchorPrompts.ts`
+  - 八锚点状态推断、模式规则与正式单轮共创 prompt
+- `src/prompts/customWorldPrompts.ts`
+  - 自定义世界分阶段生成 prompt 与场景背景图 prompt
+- `src/prompts/qwenSpriteSheetToolPrompts.ts`
+  - 精灵图工具主词 / 分镜词 / 修帧词 / 负面词
+- `src/prompts/customWorldRolePromptDefaults.ts`
+  - 角色资产工作台默认 prompt 种子
+- `src/prompts/customWorldEntityActionPrompts.ts`
+  - 编辑器技能动作 prompt
+- `packages/shared/src/prompts/qwenSprite.ts`
+  - 共享资产层的基础角色 prompt 模板
+
+## 3. 落地规则
+
+### 3.1 业务模块只做两件事
+
+1. 整理运行时上下文
+2. 调用 `server-node/src/prompts/**` 下的脚本输出 prompt
+
+不要在业务模块里继续直接内联大段 system prompt / repair prompt / user prompt 模板文本。
+
+### 3.2 Prompt 文件只放文本相关职责
+
+允许放：
+
+- system prompt 常量
+- user prompt builder
+- repair prompt builder
+- prompt 专用的文本摘要函数
+
+不建议放：
+
+- 运行时状态 mutation
+- 仓储读写
+- HTTP 处理
+- 与 prompt 无关的领域推导
+
+### 3.3 兼容层保留旧导出
+
+本轮对已有纯 prompt builder 文件采取了兼容迁移，旧路径保留为薄 re-export：
+
+- `server-node/src/modules/ai/chatPromptBuilders.ts`
+- `server-node/src/modules/ai/storyPromptBuilders.ts`
+- `server-node/src/services/eightAnchorPromptBuilder.ts`
+- `src/services/prompt.ts`
+- `src/services/characterChatPrompt.ts`
+- `src/services/questPrompt.ts`
+- `src/services/runtimeItemAiPrompt.ts`
+- `src/tools/qwenSpriteSheetToolModel.ts`
+- `src/components/asset-studio/customWorldRolePromptDefaults.ts`
+- `packages/shared/src/assets/qwenSprite.ts`
+
+对于 `runtimeQuestModule.ts`、`runtimeItemModule.ts` 这类被桥接层直接引用的模块，本轮保留原导出名，通过 re-export 指向新 prompt 文件，保证兼容性。
+
+## 4. 后续新增 prompt 的写法
+
+新增提示词时按下面顺序处理：
+
+1. 先判断属于后端、前端/编辑器还是共享工具层。
+2. 后端正式业务优先补到 `server-node/src/prompts/*.ts`。
+3. 前端/编辑器 prompt 优先补到 `src/prompts/*.ts`。
+4. 可复用的共享资产 prompt 优先补到 `packages/shared/src/prompts/*.ts`。
+5. 业务模块只传入已经整理好的上下文字段，不在模块内部继续拼长文本。
+6. 至少补一条该 prompt 的调用链测试或现有测试断言。
+
+建议命名：
+
+- system prompt：`XXX_SYSTEM_PROMPT`
+- repair prompt：`buildXXXRepairPrompt`
+- user prompt：`buildXXXPrompt`
+- 纯文本装配：`buildXXXPromptText`
+
+## 5. 本轮范围与当前状态
+
+本轮已经收口：
+
+- Story
+- Chat
+- Quest
+- Runtime Item
+- Custom World 主编排
+- Custom World Agent 草稿增补
+- Custom World 编辑器角色 / 场景 / 场景 NPC 生成
+- Character Asset
+- Eight Anchor
+- Scene Image
+- 前端剧情 / 私聊 / 任务 / 物品 prompt 兼容层
+- 编辑器与工具链 prompt 种子
+
+当前状态：
+
+- 正式业务 prompt 主源已经集中到 prompt 目录。
+- 旧 `services/`、`tools/`、`components/` 下保留的相关文件主要是兼容层或调用方。
+- 当前没有再发现需要优先继续抽离的大块业务 prompt 正文。
+
+## 6. 验证方式
+
+本轮调整后建议至少执行：
+
+- `npm run check:encoding`
+- `npm run server-node:test`
+- `npm --prefix server-node run build`
+
+本轮实测结果：
+
+- `npm run check:encoding` 通过
+- `npm --prefix server-node run build` 通过
+- `npm run build` 通过
+- `npm run server-node:test` 143 项全部通过
--- a/docs/technical/README.md
+++ b/docs/technical/README.md
@@ -4,6 +4,8 @@

 ## 文档列表

+- [REPO_NOISE_CLEANUP_BASELINE_2026-04-19.md](./REPO_NOISE_CLEANUP_BASELINE_2026-04-19.md)：落实工程清理审计第一阶段后的仓库噪音清理范围、忽略规则闭合点与后续约束。
+- [PROMPT_DIRECTORY_MANAGEMENT_2026-04-19.md](./PROMPT_DIRECTORY_MANAGEMENT_2026-04-19.md)：后端提示词收口到 `server-node/src/prompts/` 的目录方案、兼容策略与后续新增规则。
 - [SPACETIME_DEV_URI_HOTFIX_2026-04-20.md](./SPACETIME_DEV_URI_HOTFIX_2026-04-20.md)：修复开发默认配置把 Spacetime 连接误指向 Vite `3000` 端口的问题。
 - [SPACETIME_AUTH_TOKEN_FALLBACK_HOTFIX_2026-04-20.md](./SPACETIME_AUTH_TOKEN_FALLBACK_HOTFIX_2026-04-20.md)：本地 token 失效时自动降级匿名连接，并提示“登录已过期”的热修记录。
 - [NODE_DEV_STARTUP_HOTFIX_2026-04-20.md](./NODE_DEV_STARTUP_HOTFIX_2026-04-20.md)：`npm run dev` 启动失败的热修记录、根因与验证结果。
--- a/docs/technical/REPO_NOISE_CLEANUP_BASELINE_2026-04-19.md
+++ b/docs/technical/REPO_NOISE_CLEANUP_BASELINE_2026-04-19.md
@@ -0,0 +1,53 @@
+# 仓库噪音清理基线（2026-04-19）
+
+更新时间：`2026-04-19`
+
+## 1. 背景
+
+本次清理落实以下审计结论：
+
+- `docs/audits/engineering/ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-19.md`
+
+目标只覆盖审计文档推荐执行顺序中的第一阶段，也就是先把仓库噪音产物和本地检查残留从主工程面清掉，不在这一轮同时推进前后端边界迁移或无入口模块归档。
+
+## 2. 本次已执行的清理
+
+本轮已从仓库中移除以下高置信度噪音产物：
+
+- 根目录的 `.codex-*` 日志、`.preview.*` 输出、`tmp_*` 扫描文本与 HTML、`npc-editor-*` 截图和调试文件、`temp-write-check.txt`
+- 根目录 `temp-build-goal-check/` 大体量检查产物目录
+- `scripts/__pycache__/` Python 缓存目录与 `.pyc` 文件
+- `.codex-logs/` 中遗留的旧日志与 restore backup 文件
+
+这些文件都不属于正式运行时代码、PRD、设计稿或生产资源，继续保留只会污染根目录视野、拖慢扫描和 review，并增加误判成本。
+
+## 3. 规则闭合
+
+为避免相同问题反复回流，本次同步补齐了两层规则：
+
+1. `.gitignore`
+   - 新增 `/.codex-logs/`
+   - 新增 `*.py[cod]`
+   - 保持 `.preview.*`、`tmp_*`、`tmp/`、`npc-editor-*`、`temp-write-check.txt`、`temp-build-goal-check/`、`**/__pycache__/` 为忽略项
+2. `.eslintrc.cjs`
+   - 保持 `temp-build-goal-check/**`
+   - 保持 `.preview.*`、`tmp_*`、`tmp/**`、`npc-editor-*`、`temp-write-check.txt`
+   - 保持 `**/__pycache__/**`
+
+这样 Git 与 ESLint 对临时产物的忽略口径保持一致，不会再出现某个目录虽然被 Git 忽略，但仍被 lint 扫进去的情况。
+
+## 4. 后续约束
+
+- 以后所有临时扫描结果、调试截图、HTML 导出、一次性日志，不要直接落在仓库根目录。
+- 如需保留本地临时产物，统一放到本地忽略目录，例如 `tmp/` 或 `.codex-logs/`。
+- `temp-build-goal-check/` 仍视为本地检查产物，不作为主工程目录的一部分长期保留。
+- Python 脚本执行后产生的 `__pycache__` 不应进入仓库。
+
+## 5. 本轮未处理范围
+
+以下内容仍按审计原计划留待后续阶段处理：
+
+- `scripts/dev-server/localApiPlugins.ts` 及旧 Vite 本地 API 链路的归档
+- 无运行时入口或仅测试引用的孤岛模块处置
+- 前后端双份真相收口与 `server-node -> src/**` 反向依赖治理
+- 巨型热点文件拆分
--- a/docs/technical/RUNTIME_STORY_BACKEND_BOUNDARY_MIGRATION_2026-04-19.md
+++ b/docs/technical/RUNTIME_STORY_BACKEND_BOUNDARY_MIGRATION_2026-04-19.md
@@ -0,0 +1,174 @@
+# Runtime Story 后端边界迁移记录（2026-04-19）
+
+更新时间：`2026-04-20`
+
+## 1. 本轮目标
+
+本轮只处理 `docs/audits/engineering/ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-19.md` 中已经明确、且可以无需求漂移落地的两类问题：
+
+1. `RuntimeStoryOptionView` 的 `interaction` 语义不能再由前端根据 `functionId + currentEncounter` 本地重建。
+2. `src/hooks/story/npcEncounterActions.ts` 中 `help / leave / fight / spar / quest_turn_in` 等运行时动作不能继续在浏览器里保留旧本地结算分支。
+
+本轮**没有**做以下事情：
+
+1. 没有修改任何功能需求。
+2. 没有修改任何业务提示词。
+3. 没有扩展新的动作能力面。
+4. 没有处理 custom-world 领域规则从 `server-node -> src/services/**` 反向 import 的剩余问题。
+
+## 2. 已落地收口
+
+### 2.1 runtime option interaction 改为后端唯一构建
+
+已完成：
+
+1. `server-node/src/modules/story/runtimeSession.ts`
+   - `buildOptionView(...)` 直接输出 `interaction`
+   - `buildAvailableOptions(...)` 直接返回带 `interaction` 的 runtime option
+   - 删除前一版补丁式附加逻辑，避免后续再出现“双份映射”
+2. `server-node/src/modules/story/storyActionService.ts`
+   - story option view model 直接透传 `option.interaction`
+3. `src/services/runtimeStoryService.ts`
+   - 前端不再根据 `currentEncounter` 重建一份 `interaction`
+   - 只消费服务端返回的 `option.interaction`
+
+这意味着：
+
+1. `npc_chat / npc_help / npc_fight / npc_leave / npc_trade / npc_gift / npc_quest_*`
+2. `treasure_secure / treasure_inspect / treasure_leave`
+
+这些交互语义以后都以后端 runtime session 为准。
+
+### 2.2 npcEncounterActions 收缩为前端壳层
+
+已完成：
+
+1. `src/hooks/story/npcEncounterActions.ts`
+   - `help`
+   - `leave`
+   - `fight`
+   - `spar`
+   - `quest_accept`
+   - `quest_turn_in`
+
+   以上动作已统一改为走 `resolveServerRuntimeChoice(...)`
+2. 删除本轮迁移后已无消费方的本地 helper / import / 常量残留，避免误以为本地仍承担这部分结算职责。
+
+当前前端在这条链路上只保留：
+
+1. 选项点击分发
+2. trade / gift / recruit 的 UI modal 打开
+3. NPC 对话壳层与流式展示
+4. 服务端返回结果的状态落地与 story 刷新
+
+### 2.3 待接委托正式接取改为后端收口
+
+已完成：
+
+1. `server-node/src/modules/quest/questStoryActionService.ts`
+   - `npc_quest_accept` 会优先读取服务端快照里 `currentStory.npcChatState.pendingQuestOffer.quest`
+   - 如果当前聊天态里已经存在待接委托，就按这份已展示给玩家的委托正式接取，不再在后端临时重建另一份任务
+2. `server-node/src/modules/story/storyActionService.ts`
+   - `npc_quest_accept` 在存在待接委托聊天态时，会继续输出 `displayMode: 'dialogue'` 的 current story
+   - 会清空 `pendingQuestOffer`
+   - 会恢复既有的三条自由追问建议，避免接任务后 UI 退回普通 story 文本态
+3. `src/hooks/story/npcEncounterActions.ts`
+   - `acceptPendingNpcQuestOffer()` 不再本地直接修改 `quests / runtimeStats / storyHistory`
+   - 现在只负责触发 `resolveServerRuntimeChoice(...)`，由后端统一落地正式接取结果
+
+这意味着：
+
+1. “NPC 聊天里弹出的待接委托”不再是一份只存在于前端内存里的临时结果
+2. 前端不会再一边展示待接委托、一边本地把正式 quest log 写出来
+3. 正式接取后的 quest 真相源、聊天态投影与快照持久化统一以后端为准
+
+### 2.4 NPC 聊天待接委托生成与浏览器 LLM fallback 继续后移
+
+已完成：
+
+1. `server-node/src/modules/ai/chatOrchestrator.ts`
+   - `streamNpcChatTurnFromOrchestrator(...)` 现在会基于前端提交的 `questOfferContext`
+   - 由后端判断是否应该生成 `pendingQuestOffer`
+   - quest draft 与引导文案 `introText` 由服务端一并回填到 `complete` 事件
+2. `src/services/aiService.ts`
+   - `streamNpcChatTurn(...)` 已支持把 `questOfferContext` 送入后端
+3. `src/hooks/story/npcEncounterActions.ts`
+   - NPC 单轮聊天结束后不再本地调用 `generateQuestForNpcEncounter(...)`
+   - 前端改为只消费服务端回填的 `pendingQuestOffer + introText`
+4. `src/services/questDirector.ts`
+   - 浏览器端 quest draft 失败时，不再退回本地 LLM 调用
+   - 当前改为直接走 deterministic fallback quest compile
+5. `src/services/runtimeItemAiDirector.ts`
+   - 浏览器端 runtime item intent 失败时，不再退回本地 LLM 调用
+   - 当前改为直接返回 deterministic fallback intents
+
+这意味着：
+
+1. NPC 聊天里“是否触发待接委托”的判定不再由前端依据 `turnCount / affinity / quests` 本地重跑
+2. 浏览器不再保留 quest draft 与 runtime item intent 的正式 LLM fallback orchestration
+3. 前端在这两条链路上继续退化为服务端结果消费层
+
+## 3. 本轮涉及文件
+
+代码：
+
+1. `server-node/src/modules/story/runtimeSession.ts`
+2. `server-node/src/modules/story/storyActionService.ts`
+3. `server-node/src/modules/story/storyActionRoutes.test.ts`
+4. `src/services/runtimeStoryService.ts`
+5. `src/services/runtimeStoryService.test.ts`
+6. `src/hooks/story/npcEncounterActions.ts`
+7. `src/hooks/story/npcEncounterActions.test.ts`
+8. `server-node/src/modules/quest/questStoryActionService.ts`
+9. `server-node/src/modules/ai/chatOrchestrator.ts`
+10. `server-node/src/modules/ai/orchestrator.test.ts`
+11. `src/services/aiService.ts`
+12. `src/services/questDirector.ts`
+13. `src/services/runtimeItemAiDirector.ts`
+
+说明：
+
+1. 本轮没有改 prompt 文本。
+2. 本轮没有新增或删减 runtime functionId。
+3. 本轮只是把既有交互语义和动作结算职责收回到后端。
+
+## 4. 验证结果
+
+已执行并通过：
+
+1. `npm run check:encoding`
+2. `npx vitest run src/services/runtimeStoryService.test.ts src/hooks/story/npcEncounterActions.test.ts`
+3. `npx tsx --test server-node/src/modules/story/runtimeSession.test.ts`
+
+新增的防回退验证包括：
+
+1. 前端 `runtimeStoryService` 会保留并消费服务端返回的 `interaction`
+2. `npcEncounterActions` 的 `help / leave / fight / spar` 明确走服务端 resolver
+3. `npc_quest_turn_in` 会把 `questId` 原样透传到后端
+4. 后端 `runtimeSession` 明确直接构建并透传 NPC option interaction
+5. 待接委托正式接取会复用快照中的 pending quest，而不是在接取瞬间重新造一份 quest
+6. 待接委托接取后仍保持 NPC 聊天展示态，并清空 `pendingQuestOffer`
+7. NPC chat turn 的 pending quest offer 现在由后端直接产出，前端不再本地二次决定
+8. 浏览器端 quest / runtime item 已不再保留直接调用本地 LLM 的 fallback orchestration
+
+补充说明：
+
+1. `server-node/src/modules/story/storyActionRoutes.test.ts` 已补充路由级 interaction 断言。
+2. `2026-04-20` 的补充收口改为以 `storyActionRoutes.test.ts` 直接覆盖待接委托正式接取链路，验证快照输入与快照输出是否都以后端为准。
+3. 本轮没有改 prompt 文本，也没有新增函数能力面，只是继续把现有 runtime story 结算权后移。
+
+## 5. 暂未处理的后续边界项
+
+这轮故意没有继续扩大的点：
+
+1. `server-node/src/modules/ai/customWorldOrchestrator.ts` 仍直接依赖 `src/services/customWorld*.ts`
+2. `server-node/src/services/customWorldAgentFoundationDraftService.ts` 仍直接依赖 `src/services/customWorld*.ts` 与 `src/types.ts`
+3. `pending quest offer` 的 replace / abandon 仍由前端 UI 壳层协调
+4. 浏览历史、本地快照真相源、custom-world 领域规则共享化仍需后续阶段继续推进
+
+原因：
+
+1. 这些点会牵涉 shared contract 抽取与较大范围重组
+2. 若与本轮 runtime story 收口混做，容易把“边界迁移”误做成“需求改造”
+
+因此本轮把范围锁在 runtime story 主链，优先交付一条可验证、可继续扩展的后端边界基线。
--- a/docs/technical/SCENE_MULTI_ACT_CREATOR_IMPLEMENTATION_PROGRESS_2026-04-20.md
+++ b/docs/technical/SCENE_MULTI_ACT_CREATOR_IMPLEMENTATION_PROGRESS_2026-04-20.md
@@ -0,0 +1,97 @@
+# 场景多幕创作与流程改造实施进度 2026-04-20
+
+更新时间：`2026-04-20`
+
+## 1. 本轮落地范围
+
+本轮先完成 `scene_chapter` 的第一批基础链路，让“场景章节 -> 多幕 -> 主角色 -> 幕背景/相遇 NPC”真正进入现有创作工具和草稿系统。
+
+本轮目标不是一次性做完 PRD 全量能力，而是先把下面这条主干打通：
+
+1. 草稿层可以承载 `scene chapter / scene act`
+2. 草稿编译器可以把 `scene_chapter` 编译成正式卡片
+3. 创作页可以看到、打开、编辑 `scene_chapter`
+4. 编辑后的幕信息可以正确写回草稿
+5. 运行时共享层先具备读取幕背景、主角色、相遇 NPC 池的基础能力
+
+## 2. 本轮已落地
+
+## 2.1 草稿与运行时结构
+
+已补齐多幕相关结构：
+
+1. `CustomWorldFoundationDraftProfile.sceneChapters`
+2. `CustomWorldFoundationDraftSceneChapter`
+3. `CustomWorldFoundationDraftSceneAct`
+4. `CustomWorldProfile.sceneChapterBlueprints`
+5. `StoryEngineMemoryState.currentSceneActState`
+
+同时补齐了地点/营地草稿里的 `imageSrc`，避免幕背景回落时丢失现有场景图资产引用。
+
+## 2.2 scene_chapter 草稿编译
+
+`server-node/src/services/customWorldAgentDraftCompiler.ts` 已完成第一批接入：
+
+1. `scene_chapter` 正式进入草稿编译结果
+2. 支持从显式 `sceneChapters` 或地点/章节数据回退生成场景章节卡
+3. 每张卡会编译出场景摘要、幕结构总览、每幕背景图、主角色、辅助 NPC、幕目标、过渡钩子
+4. 每幕生成动态可编辑 section id
+5. 已增加基础警告：
+   - 幕数不足
+   - 缺背景图
+   - 缺相遇 NPC
+   - 主角色不在第一位
+   - 缺线程挂钩
+   - NPC 或线程引用失配
+
+## 2.3 scene_chapter 草稿编辑
+
+`server-node/src/services/customWorldAgentDraftEditService.ts` 已支持：
+
+1. 编辑场景章节标题、摘要
+2. 编辑每幕标题、摘要、背景图链接、相遇 NPC、幕目标、过渡钩子
+3. `encounterNpcIds` 支持用角色 id 或角色名回写
+4. 回写后自动用第一位 NPC 覆盖 `primaryNpcId`
+
+`server-node/src/services/customWorldAgentChangeSummaryService.ts` 也已支持解析 `scene_chapter` 标题。
+
+## 2.4 创作页展示
+
+前端已完成第一批接入：
+
+1. 草稿抽屉正式加入 `scene_chapter` 分组
+2. `scene_chapter` 分组顺序位于 `chapter` 后、`thread` 前
+3. 详情面板已支持 `场景章节` 类型标签
+4. 幕背景 section 在详情面板里会直接渲染图片预览
+5. 编辑面板已支持幕摘要 / 相遇 NPC / 幕目标 / 过渡钩子等动态多行字段
+
+## 2.5 运行时基础层
+
+本轮同步补齐了幕运行的基础读取能力，便于下一轮继续接游戏流程：
+
+1. 当前幕背景图优先覆盖场景默认背景
+2. 当前幕相遇 NPC 池可参与场景相遇过滤
+3. 当前幕主角色与负好感有限聊天的判定 helper 已建立
+4. 场景预览层已能识别“负好感主角色不直接自动开战”的基础分支
+
+## 3. 当前仍未完成
+
+下面这些仍属于 PRD 未完项，需要下一轮继续：
+
+1. 创作页里的“新增幕 / 删除幕 / 调整幕顺序”交互
+2. 背景图配置与 NPC 配置的独立面板化交互
+3. 发布期 `qualityFindings` / blocker 的正式接入
+4. `SceneActRuntimeState` 的完整推进与持久化
+5. 当前幕主角色负好感 `5` 轮聊天限制的前后端完整闭环
+6. 第 `5` 轮“铺垫式收束”提示与强制退出聊天态
+7. 幕切换后的系统提示与 Adventure 面板状态展示
+
+## 4. 下一轮建议顺序
+
+建议下一轮按下面顺序继续：
+
+1. 先补 `SceneActRuntimeState` 初始化与幕推进
+2. 再接 `npcEncounterActions / aiService / chatOrchestrator` 的负好感有限聊天闭环
+3. 最后补创作页的幕增删改序和独立配置面板
+
+这样可以先把“能跑”补齐，再把“编辑体验”补完整。
--- a/docs/technical/SERVER_DEPLOYMENT_AND_CORS_TECHNICAL_SOLUTION_2026-04-05.md
+++ b/docs/technical/SERVER_DEPLOYMENT_AND_CORS_TECHNICAL_SOLUTION_2026-04-05.md
@@ -42,7 +42,8 @@

 ### 2.2 当前 API 层还只是开发期能力

-这些接口现在主要由 [scripts/dev-server/localApiPlugins.ts](/E:/Repos/Genarrative/scripts/dev-server/localApiPlugins.ts) 挂在 Vite dev/preview 服务器里。
+本文撰写时，这些接口主要由旧 `scripts/dev-server/localApiPlugins.ts` 挂在 Vite dev/preview 服务器里。  
+截至 `2026-04-19`，这条旧链路已经从仓库删除，当前统一由 `server-node` 承接。

 这在本地开发阶段很方便，但生产环境存在几个明显问题：

@@ -500,7 +501,14 @@ flowchart LR

 ## 11.1 第一优先级：把 Vite 里的 API 能力抽出来

-当前 [scripts/dev-server/localApiPlugins.ts](/E:/Repos/Genarrative/scripts/dev-server/localApiPlugins.ts) 里的能力，建议分三类迁移：
+该迁移建议已完成，原 `scripts/dev-server/localApiPlugins.ts` 已于 `2026-04-19` 删除。  
+对应能力现统一收口到以下正式模块：
+
+- `server-node/src/modules/editor/**`
+- `server-node/src/modules/assets/**`
+- `server-node/src/modules/ai/**`
+
+原旧链路中的能力，可按以下三类理解其迁移归属：

 ### A. 运行时代理接口