1

2026-04-19 20:33:18 +08:00
parent 692643136f
commit 67c584b4df
123 changed files with 11898 additions and 4082 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,15 @@

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

+实现更新（`2026-04-19`）：
+
+- 当前仓库的 `image-to-video` 角色动作生成入口已切到火山方舟 `Seedance`
+- 采用双参考图首尾帧方案：图片 1 约束首帧，图片 2 约束尾帧
+- 当前请求体中的两张参考图角色分别固定为 `first_frame / last_frame`
+- 当前固定参数为 `1:1`、`480p`、`4 秒`、单次 `1` 个视频
+- 当前固定动作入口收敛为 `idle / run / attack / die`，不再内置固定 `hurt`
+- 提示词里传给视频模型的动作名统一使用英文动作名
+
 ## 5.3 补充路线：腾讯云相关能力

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

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

+`jump`、`hurt` 这类扩展动作不再作为当前编辑器固定按钮，改为后续扩展动作槽位或手动补齐。
+
 ### B. 视频驱动

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

 ### 角色视角要求

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

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

 推荐做法：
@@ -703,7 +724,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;
@@ -914,20 +942,26 @@ draft

 第一版要求以下基础动作槽位全部有内容：

-| 动作槽位 | 是否必填 | 建议来源 |
-| --- | --- | --- |
-| `idle` | 必填 | 模板生成 |
-| `acquire` | 必填 | 可由短持物 / 抬手动作生成 |
-| `attack` | 必填 | 模板生成 |
-| `run` | 必填 | 模板生成 |
-| `jump` | 必填 | 模板生成 |
-| `double_jump` | 必填 | 可由跳跃二次变体生成 |
-| `jump_attack` | 必填 | 跳跃攻击模板 |
-| `dash` | 必填 | 冲刺模板 |
-| `hurt` | 必填 | 受击模板 |
-| `die` | 必填 | 倒地 / 消散模板 |
-| `climb` | 必填 | 攀爬模板 |
-| `wall_slide` | 必填 | 可由攀爬或停滞帧变体生成 |
+当前编辑器固定生成入口补充说明（`2026-04-19`）：
+
+- 固定按钮只保留 `idle / run / attack / die`
+- `hurt` 不再作为固定生成按钮
+- 如果运行时仍需 `hurt` 资源，应通过后续扩展动作槽位或手动补齐
+
+| 动作槽位      | 是否必填 | 建议来源                  |
+| ------------- | -------- | ------------------------- |
+| `idle`        | 必填     | 模板生成                  |
+| `acquire`     | 必填     | 可由短持物 / 抬手动作生成 |
+| `attack`      | 必填     | 模板生成                  |
+| `run`         | 必填     | 模板生成                  |
+| `jump`        | 必填     | 模板生成                  |
+| `double_jump` | 必填     | 可由跳跃二次变体生成      |
+| `jump_attack` | 必填     | 跳跃攻击模板              |
+| `dash`        | 必填     | 冲刺模板                  |
+| `hurt`        | 必填     | 受击模板                  |
+| `die`         | 必填     | 倒地 / 消散模板           |
+| `climb`       | 必填     | 攀爬模板                  |
+| `wall_slide`  | 必填     | 可由攀爬或停滞帧变体生成  |

 这里“不能为空”指的是：

@@ -961,14 +995,13 @@ draft

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

-| 模板 | 推荐时长 | 是否循环 | 说明 |
-| --- | --- | --- | --- |
-| `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/PROMPT_DIRECTORY_MANAGEMENT_2026-04-19.md
+++ b/docs/technical/PROMPT_DIRECTORY_MANAGEMENT_2026-04-19.md
@@ -0,0 +1,143 @@
+# 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`
+
+问题主要有三类：
+
+1. 业务逻辑和 prompt 文本混写，改提示词时容易顺手改坏运行时逻辑。
+2. 同一类 prompt 缺少集中入口，排查系统 prompt / user prompt / repair prompt 成本高。
+3. 老桥接层、测试和新业务链路同时依赖时，迁移成本高，容易出现导出断裂。
+
+这次收口目标不是“重写全部 AI 链路”，而是先把当前后端主链 prompt 收到单独目录，业务模块退化成“准备上下文 + 调用 prompt 脚本”。
+
+## 2. 新目录
+
+本轮新增目录：
+
+```text
+server-node/src/prompts/
+├─ chatPromptBuilders.ts
+├─ customWorldAgentPrompts.ts
+├─ customWorldEntityPrompts.ts
+├─ customWorldOrchestratorPrompts.ts
+├─ customWorldSceneNpcPrompts.ts
+├─ questPrompts.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
+
+## 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 文件采取了兼容迁移：
+
+- `server-node/src/modules/ai/chatPromptBuilders.ts`
+- `server-node/src/modules/ai/storyPromptBuilders.ts`
+
+旧路径现在作为薄 re-export 保留，避免测试、桥接层和旧引用一次性全部断掉。
+
+对于 `runtimeQuestModule.ts`、`runtimeItemModule.ts` 这类被桥接层直接引用的模块，本轮保留原导出名，通过 re-export 指向新 prompt 文件，保证兼容性。
+
+## 4. 后续新增 prompt 的写法
+
+新增提示词时按下面顺序处理：
+
+1. 先判断是否属于已有领域。
+2. 如果属于已有领域，优先补到对应 `server-node/src/prompts/*.ts`。
+3. 如果是新领域，再新增一个独立 prompt 脚本文件。
+4. 业务模块只传入已经整理好的上下文字段，不在模块内部继续拼长文本。
+5. 至少补一条该 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 生成
+
+本轮尚未完全收口的内联 prompt 聚集区：
+
+- `server-node/src/modules/assets/characterAssetRoutes.ts`
+- `server-node/src/services/eightAnchorPromptBuilder.ts`
+
+这两块后续继续沿用同一规则：
+
+- 先抽出 prompt 文本与 builder
+- 再让业务文件只保留参数整理与调用
+
+## 6. 验证方式
+
+本轮调整后建议至少执行：
+
+- `npm run check:encoding`
+- `npm run server-node:test`
+- `npm --prefix server-node run build`
+
+说明：
+
+- 当前仓库里 `server-node/src/db.test.ts` 仍有一条与新增迁移版本号相关的既有失败，不属于本次 prompt 目录改造引入的问题。
--- a/docs/technical/README.md
+++ b/docs/technical/README.md
@@ -4,6 +4,7 @@

 ## 文档列表

+- [PROMPT_DIRECTORY_MANAGEMENT_2026-04-19.md](./PROMPT_DIRECTORY_MANAGEMENT_2026-04-19.md)：后端提示词收口到 `server-node/src/prompts/` 的目录方案、兼容策略与后续新增规则。
 - [NODE_SERVER_KNOWLEDGE_GRAPH_2026-04-08.md](./NODE_SERVER_KNOWLEDGE_GRAPH_2026-04-08.md)：当前 Node 运行时后端的技术栈、入口、鉴权、存储与接口知识图谱。
 - [EXPRESS_BACKEND_INTEGRATION_FREEZE_2026-04-09.md](./EXPRESS_BACKEND_INTEGRATION_FREEZE_2026-04-09.md)：Express 后端当前 contract 冻结版本、热点文件编辑规则与集成窗口清单。
 - [EXPRESS_BACKEND_WORKSTREAM_AUDIT_2026-04-09.md](./EXPRESS_BACKEND_WORKSTREAM_AUDIT_2026-04-09.md)：按并行工作流文档逐项核对后的完成度审计与剩余收口点。