Genarrative/docs/technical/SERVER_RS_GENERATION_PROMPT_SCRIPT_MIGRATION_2026-04-25.md

Rust 生成链路 Prompt 脚本迁移设计（2026-04-25）

1. 目标

把 server-rs 中四条现役生成链路的提示词从业务流程文件中抽离到独立 prompt 目录，后续迭代只修改 prompt 脚本，不在路由、任务、资产持久化代码中直接堆提示词。

2. 目录约定

新增目录：server-rs/crates/api-server/src/prompt/

模块划分：

1. scene_background.rs：场景背景图与幕背景图提示词。
2. character_visual.rs：角色主形象提示词与负向提示词。
3. character_animation.rs：角色动作、序列帧、图生视频、动作迁移提示词。
4. foundation_draft.rs：草稿生成各阶段 JSON 系统提示词、修复提示词、框架/角色/场景/档案分阶段 user prompt。
5. mod.rs：统一导出子模块。

3. 迁移边界

1. 只迁移 prompt 构造与 prompt 常量，不迁移 DashScope、OSS、SpacetimeDB、任务状态、并发控制和持久化逻辑。
2. custom_world.rs 只保留场景幕引用收集、校验和调用生成服务，不再承载幕背景图提示词正文。
3. custom_world_ai.rs 只保留图片生成、下载、入库、接口 payload 归一化；场景图 prompt builder 迁入 prompt::scene_background。
4. custom_world_asset_prompts.rs 作为兼容转发层保留，避免一次性改动角色资产调用点过大；真实提示词脚本迁入 prompt::character_visual 与 prompt::character_animation。
5. custom_world_foundation_draft.rs 只保留分阶段编排、JSON 解析、归一化和写回；所有阶段 prompt builder 迁入 prompt::foundation_draft。

4. 验收标准

1. cargo fmt -p api-server 通过。
2. cargo check -p api-server 通过。
3. 四条链路仍能从原调用点拿到相同语义的提示词。
4. 文档明确后续 prompt 修改主源在 src/prompt/。

5. 聊天类 Prompt 追加迁移

2026-04-25 追加迁移两类聊天提示词：

1. Agent 聊天创作：server-rs/crates/api-server/src/prompt/agent_chat.rs，承接原 custom_world_rpg_draft_prompts.rs 中的共创主系统提示词、状态识别提示词、输出契约、动态状态上下文、聊天历史上下文等脚本。
2. 游戏运行时与对方角色聊天：server-rs/crates/api-server/src/prompt/runtime_chat.rs，承接运行时剧情导演、NPC 对话导演、战斗结算叙事的 system prompt 与 user prompt 组装。

迁移后约束：

1. custom_world_rpg_draft_prompts.rs 只作为兼容 re-export，后续不要在该文件新增提示词正文。
2. runtime_story/compat/ai.rs 只负责读取状态、调用 LLM 和组装返回，不再内联 NPC 对话或剧情导演提示词。
3. 后续所有 Agent 共创聊天、运行时角色聊天的提示词调整统一进入 src/prompt/。

6. 运行时 NPC 聊天 Prompt 归并

2026-04-26 追加收口：

1. 删除 server-rs/crates/api-server/src/runtime_chat_prompt.rs 独立提示词脚本，避免 runtime_chat 相关提示词散落在 src/ 根目录。
2. server-rs/crates/api-server/src/prompt/runtime_chat.rs 统一承接：
   • 运行时剧情导演 system prompt 与 user prompt。
   • NPC 对话导演 system prompt 与 user prompt。
   • NPC 单轮聊天回复 system prompt 与 user prompt。
   • NPC 下一轮 suggestions / functionSuggestions 的 JSON 输出约束。
   • LLM 不可用时的聊天 reply、普通 choice、function choice 兜底生成。
3. server-rs/crates/api-server/src/runtime_chat.rs 只保留 Axum SSE、LLM 调用、解析、好感变化、结束聊天判断等流程编排，不再直接承载提示词正文或 choice 文案兜底。
4. 后续调整聊天 choice 语气、候选数量、functionOptions 描述方式、敌对聊天收束策略时，优先修改 prompt/runtime_chat.rs。

7. 拼图 Prompt 独立目录收口

2026-04-30 追加收口：

1. 拼图提示词参考 RPG 的目录组织，统一迁入 server-rs/crates/api-server/src/prompt/puzzle/。
2. prompt/puzzle/agent_chat.rs 承接拼图共创 Agent 的 system prompt、单轮 JSON 输出契约、用户提示词与 anchor pack / 聊天记录提示词组装。
3. prompt/puzzle/draft.rs 承接生成拼图作品草稿动作里的表单 seed prompt、草稿首图 prompt 来源选择、单关图片再生成 prompt 来源选择。
4. prompt/puzzle/image.rs 承接拼图图片生成正式提示词与默认反向提示词。
5. puzzle_agent_turn.rs 只保留 LLM 调用、结果解析、阶段判断和 SpacetimeDB 写回输入构造，不再内联拼图聊天提示词正文。
6. puzzle.rs 只保留拼图路由、计费、DashScope、OSS、候选图持久化和运行态编排，不再内联拼图草稿或图片提示词正文。
7. 后续调整拼图共创问法、输出契约、生成草稿 prompt 来源、图片画面约束或反向提示词时，优先修改 prompt/puzzle/，不要在 puzzle.rs 或 puzzle_agent_turn.rs 中新增提示词正文。