Prune stale docs and update .hermes content
Delete a large set of outdated documentation (many files under docs/ and .hermes/plans/, including audits, design, prd, technical, planning, assets, and todos). Update and consolidate .hermes content: refresh shared-memory pages (decision-log, development-workflow, document-map, pitfalls, project-overview, team-conventions) and several skills/references under .hermes/skills. Also modify AGENTS.md, README.md, UI_CODING_STANDARD.md, docs/README.md and .encoding-check-ignore. Purpose: clean up stale planning/audit material and keep current hermes documentation and related top-level docs in sync.
This commit is contained in:
@@ -1,332 +0,0 @@
|
||||
# 角色资产 Prompt 链路审计（2026-04-20）
|
||||
|
||||
更新时间：`2026-04-20`
|
||||
|
||||
## 0. 本次审计回答什么问题
|
||||
|
||||
本次只回答角色资产相关的 4 个问题：
|
||||
|
||||
1. `characterAssetPrompts.ts` 里的 `visualPromptText` 和 `animationPromptText`，是不是“生成角色形象 / 动作形象的默认描述”。
|
||||
2. 生成角色形象的系统提示词在哪个文件，生成默认角色形象描述文本的提示词在哪个文件。
|
||||
3. 生成角色动作的系统提示词在哪个文件，生成默认角色动作描述文本的提示词在哪个文件。
|
||||
4. 当前链路里是否存在冗余流程、保留接口或无效代码。
|
||||
|
||||
---
|
||||
|
||||
## 1. 先说结论
|
||||
|
||||
结论不是“只有一套 prompt”，而是：
|
||||
|
||||
**当前角色资产链路仍然有两层 prompt，但“默认描述文本”已经统一成单一主源。**
|
||||
|
||||
### 1.1 默认描述文本层
|
||||
|
||||
这层的目标是：
|
||||
|
||||
**先给资产工坊里的输入框一个默认可编辑文本。**
|
||||
|
||||
这层不直接拿去生成图片或动作视频。
|
||||
|
||||
当前实际主链来源：
|
||||
|
||||
- `src/prompts/customWorldRolePromptDefaults.ts`
|
||||
|
||||
它会把角色已有字段映射成：
|
||||
|
||||
- `visualPromptText`
|
||||
- `animationPromptText`
|
||||
- `scenePromptText`
|
||||
|
||||
其中：
|
||||
|
||||
- `visualPromptText` 优先取 `visualDescription`
|
||||
- `animationPromptText` 优先取 `actionDescription`
|
||||
- `scenePromptText` 优先取 `sceneVisualDescription`
|
||||
|
||||
这层是**默认描述文本**，不是正式图像模型 prompt。
|
||||
|
||||
### 1.2 正式模型 prompt 层
|
||||
|
||||
这层的目标是：
|
||||
|
||||
**把“默认描述文本”进一步编译成正式给图像模型 / 动作模型的完整 prompt。**
|
||||
|
||||
当前主链来源：
|
||||
|
||||
- `server-node/src/prompts/characterAssetPrompts.ts`
|
||||
- `packages/shared/src/prompts/qwenSprite.ts`
|
||||
|
||||
也就是说：
|
||||
|
||||
1. 前端先有一段短文本
|
||||
2. 后端再用正式 prompt builder 把它扩成模型真正使用的完整 prompt
|
||||
|
||||
---
|
||||
|
||||
## 2. 角色形象生成链路
|
||||
|
||||
## 2.1 生成角色形象的系统提示词在哪
|
||||
|
||||
如果这里问的是“正式生成角色主图时，真正控制模型输出方向的 prompt 主源在哪”，答案是：
|
||||
|
||||
- `server-node/src/prompts/characterAssetPrompts.ts`
|
||||
- `packages/shared/src/prompts/qwenSprite.ts`
|
||||
|
||||
更准确说：
|
||||
|
||||
1. `buildNpcVisualPrompt`
|
||||
- 文件：`server-node/src/prompts/characterAssetPrompts.ts`
|
||||
- 作用：把短描述文本和角色摘要合并
|
||||
2. `buildMasterPrompt`
|
||||
- 文件：`packages/shared/src/prompts/qwenSprite.ts`
|
||||
- 作用：提供正式的角色主图 prompt 骨架
|
||||
|
||||
最终角色形象正式生成请求使用的是：
|
||||
|
||||
- `buildNpcVisualPrompt(...)`
|
||||
|
||||
调用位置：
|
||||
|
||||
- `server-node/src/modules/assets/characterAssetRoutes.ts`
|
||||
|
||||
即：
|
||||
|
||||
**角色主图正式生成的系统提示词主链，不在前端默认值文件，而在后端 `characterAssetPrompts.ts` + 共享 `qwenSprite.ts`。**
|
||||
|
||||
## 2.2 生成默认角色形象描述文本的提示词在哪
|
||||
|
||||
当前资产工坊默认输入框实际使用：
|
||||
|
||||
- `src/prompts/customWorldRolePromptDefaults.ts`
|
||||
|
||||
这不是 LLM system prompt，而是本地字段映射规则。
|
||||
|
||||
换句话说，当前页面上的默认“形象描述”主要来自：
|
||||
|
||||
- `role.visualDescription`
|
||||
- 或回退到 `role.description`
|
||||
|
||||
---
|
||||
|
||||
## 3. 角色动作生成链路
|
||||
|
||||
## 3.1 生成角色动作的系统提示词在哪
|
||||
|
||||
当前正式动作生成主链在：
|
||||
|
||||
- `server-node/src/prompts/characterAssetPrompts.ts`
|
||||
- `packages/shared/src/prompts/qwenSprite.ts`
|
||||
|
||||
其中分两类：
|
||||
|
||||
1. `buildArkCharacterAnimationPrompt`
|
||||
- 当前图生视频动作链路主入口
|
||||
2. `buildNpcAnimationPrompt`
|
||||
- 通用动作视频 prompt builder
|
||||
3. `buildImageSequencePrompt`
|
||||
- 连续帧方案动作 prompt builder
|
||||
4. `buildVideoActionPrompt`
|
||||
- 共享动作模板骨架，在 `packages/shared/src/prompts/qwenSprite.ts`
|
||||
|
||||
当前主动作链路更偏向：
|
||||
|
||||
- `buildArkCharacterAnimationPrompt`
|
||||
|
||||
调用位置：
|
||||
|
||||
- `server-node/src/modules/assets/characterAssetRoutes.ts`
|
||||
|
||||
## 3.2 生成默认角色动作描述文本的提示词在哪
|
||||
|
||||
当前资产工坊真实默认“动作描述”来源：
|
||||
|
||||
- `src/prompts/customWorldRolePromptDefaults.ts`
|
||||
|
||||
规则是：
|
||||
|
||||
- 优先 `actionDescription`
|
||||
- 回退 `combatStyle`
|
||||
|
||||
这仍然是**默认描述文本层**，不是最终动作模型 prompt。
|
||||
|
||||
---
|
||||
|
||||
## 4. `characterAssetPrompts.ts` 里的 `visualPromptText` / `animationPromptText` 到底是什么
|
||||
|
||||
这两个字段容易混淆，因为它们名字里带 `Prompt`。
|
||||
|
||||
但当前工程里它们更准确的定位是：
|
||||
|
||||
**“默认描述文本 bundle 字段名”，不是最终图像模型请求体里的最终 prompt 名称。**
|
||||
|
||||
也就是：
|
||||
|
||||
- `visualPromptText`
|
||||
- 在 UI 里更像“角色形象描述默认文本”
|
||||
- 之后会再被编译进正式图像 prompt
|
||||
- `animationPromptText`
|
||||
- 在 UI 里更像“角色动作描述默认文本”
|
||||
- 之后会再被编译进正式动作 prompt
|
||||
|
||||
所以对你的问题可以直接回答为：
|
||||
|
||||
**是，它们在当前语义上确实可以看作“默认角色形象 / 动作描述文本”。**
|
||||
|
||||
但需要补一句：
|
||||
|
||||
**它们不是最终一步的正式模型系统提示词，而是正式模型 prompt 的上游输入。**
|
||||
|
||||
---
|
||||
|
||||
## 5. 当前真实调用链
|
||||
|
||||
## 5.1 当前资产工坊页面初始默认值主链
|
||||
|
||||
当前真实主链：
|
||||
|
||||
1. 角色对象已有字段进入前端
|
||||
2. `src/prompts/customWorldRolePromptDefaults.ts`
|
||||
3. `CustomWorldRoleAssetStudioModal.tsx`
|
||||
4. 输入框初始值：
|
||||
- `visualPromptText`
|
||||
- `animationPromptText`
|
||||
|
||||
这条链：
|
||||
|
||||
- 快
|
||||
- 本地可控
|
||||
- 不依赖额外一次 LLM 调用
|
||||
|
||||
## 5.2 当前正式角色主图生成主链
|
||||
|
||||
1. 前端把输入框里的 `visualPromptText` 提交到后端
|
||||
2. `server-node/src/prompts/characterAssetPrompts.ts`
|
||||
- `buildNpcVisualPrompt`
|
||||
3. `packages/shared/src/prompts/qwenSprite.ts`
|
||||
- `buildMasterPrompt`
|
||||
4. 图像模型正式生成
|
||||
|
||||
## 5.3 当前正式角色动作生成主链
|
||||
|
||||
1. 前端把输入框里的 `animationPromptText` 提交到后端
|
||||
2. `server-node/src/prompts/characterAssetPrompts.ts`
|
||||
- `buildArkCharacterAnimationPrompt`
|
||||
- 或 `buildNpcAnimationPrompt`
|
||||
- 或 `buildImageSequencePrompt`
|
||||
3. `packages/shared/src/prompts/qwenSprite.ts`
|
||||
- `buildVideoActionPrompt`
|
||||
4. 动作模型正式生成
|
||||
|
||||
---
|
||||
|
||||
## 6. 冗余流程与当前问题
|
||||
|
||||
## 6.1 默认描述文本双链已收口
|
||||
|
||||
此前默认描述文本同时存在：
|
||||
|
||||
1. 前端本地字段映射
|
||||
2. 后端 bundle 编译接口
|
||||
|
||||
本轮已经统一为：
|
||||
|
||||
- `src/prompts/customWorldRolePromptDefaults.ts`
|
||||
|
||||
也就是：
|
||||
|
||||
**默认描述文本现在只有一条真实主源。**
|
||||
|
||||
对应变化：
|
||||
|
||||
1. 不再保留后端独立的默认 bundle 编译接口。
|
||||
2. 不再保留前端对应的 bundle 生成 API 壳层。
|
||||
3. `server-node/src/prompts/characterAssetPrompts.ts` 只保留正式模型 prompt builder。
|
||||
|
||||
判断：
|
||||
|
||||
**默认描述文本层的双份真相已经被消除。**
|
||||
|
||||
## 6.2 `scenePromptText` 结构存在，但当前资产工坊没有完整承接
|
||||
|
||||
当前这套链路里：
|
||||
|
||||
- `customWorldRolePromptDefaults.ts` 会返回 `scenePromptText`
|
||||
- `characterAssetPrompts.ts` 也会返回 `scenePromptText`
|
||||
|
||||
但当前资产工坊 UI 里并没有完整对应输入框链路。
|
||||
|
||||
这说明：
|
||||
|
||||
**场景描述文本在结构层存在，但在当前角色资产工坊里没有形成完整的用户可编辑闭环。**
|
||||
|
||||
## 6.3 共享模板与工具模板存在相似实现，但职责不同
|
||||
|
||||
仓库里同时有：
|
||||
|
||||
- `packages/shared/src/prompts/qwenSprite.ts`
|
||||
- `src/prompts/qwenSpriteSheetToolPrompts.ts`
|
||||
|
||||
它们都提供类似的主图 / 动作模板能力。
|
||||
|
||||
但当前定位不同：
|
||||
|
||||
- `packages/shared/src/prompts/qwenSprite.ts`
|
||||
- 正式角色资产主链共享模板
|
||||
- `src/prompts/qwenSpriteSheetToolPrompts.ts`
|
||||
- Qwen 工具链 prompt
|
||||
|
||||
它们不是同一条业务主链里的重复实现，但确实容易让人误读为“双份正式模板”。
|
||||
|
||||
判断：
|
||||
|
||||
**这是“职责上可解释，但认知上高混淆”的并行模板，不建议现在直接删，但需要文档明确边界。**
|
||||
|
||||
## 6.4 当前没有证据说明正式主图 / 动作 prompt builder 是无效代码
|
||||
|
||||
以下 builder 当前都有正式调用点：
|
||||
|
||||
- `buildNpcVisualPrompt`
|
||||
- `buildNpcVisualNegativePrompt`
|
||||
- `buildArkCharacterAnimationPrompt`
|
||||
- `buildNpcAnimationPrompt`
|
||||
- `buildImageSequencePrompt`
|
||||
|
||||
因此它们不能算“无效代码”。
|
||||
|
||||
真正已经被清理掉的保留链路，是此前未接入主 UI 的默认 bundle 接口：
|
||||
|
||||
- `CHARACTER_PROMPT_BUNDLE_SYSTEM_PROMPT`
|
||||
- `buildCharacterPromptBundleUserPrompt`
|
||||
- `/api/assets/character-prompts/generate`
|
||||
|
||||
这套链路已经不再保留在当前仓库主线中。
|
||||
|
||||
---
|
||||
|
||||
## 7. 本次建议
|
||||
|
||||
如果后续要继续收口，建议按顺序处理：
|
||||
|
||||
1. 继续以前端本地映射作为默认描述文本唯一主源。
|
||||
2. 对 `scenePromptText` 做完整承接，不要继续停留在结构存在但 UI 不消费的状态。
|
||||
3. 继续保留 `packages/shared/src/prompts/qwenSprite.ts` 与工具链 prompt 分层，但在文档里强制写清“正式主链 / 工具链”边界。
|
||||
|
||||
---
|
||||
|
||||
## 8. 本次审计覆盖文件
|
||||
|
||||
- `server-node/src/prompts/characterAssetPrompts.ts`
|
||||
- `packages/shared/src/prompts/qwenSprite.ts`
|
||||
- `server-node/src/modules/assets/characterAssetRoutes.ts`
|
||||
- `src/prompts/customWorldRolePromptDefaults.ts`
|
||||
- `src/components/CustomWorldRoleAssetStudioModal.tsx`
|
||||
- `src/components/asset-studio/characterAssetWorkflowPersistence.ts`
|
||||
- `src/prompts/qwenSpriteSheetToolPrompts.ts`
|
||||
|
||||
---
|
||||
|
||||
## 9. 一句话版结论
|
||||
|
||||
一句话总结就是：
|
||||
|
||||
**当前角色资产系统把“默认描述文本”和“正式模型 prompt”拆成了两层，这是合理的；默认描述文本层已经统一为前端本地映射单一主源，当前剩余主要问题不再是双主源，而是 `scenePromptText` 仍未形成完整 UI 闭环。**
|
||||
Reference in New Issue
Block a user