Genarrative/docs/technical/CUSTOM_WORLD_AGENT_LLM_REPLY_RESTORE_2026-04-22.md

Custom World Agent 大模型对话恢复设计

日期：2026-04-22

1. 背景

当前 Rust server-rs 里的 Custom World Agent 聊天链路已经接上了会话、消息、operation 与 SSE 外壳，但并没有真正调用大模型生成聊天回复。

现状问题：

1. submit_custom_world_agent_message 在 spacetime-module 中直接写死 assistant 回复。
2. /api/runtime/custom-world/agent/sessions/:sessionId/messages/stream 只是把最后一条 assistant 文案一次性回放给前端。
3. 旧 server-node 已经实现过完整的大模型单轮推理链，包括：
   • 动态状态识别
   • 原样提示词拼装
   • 流式 replyText 截取
   • 回合结束后的 anchor / creator intent / readiness / clarification / suggested action 派生

用户本轮要求是：

1. 恢复 Agent 聊天对话使用大模型推理生成回复。
2. 把之前 Node 的提示词和后台流程恢复到 Rust 后端。
3. 禁止修改提示词正文。

2. 目标

本轮只恢复 Custom World Agent 聊天主链的真实推理闭环：

1. 用户发消息后，assistant 回复必须来自大模型。
2. SSE reply_delta 必须来自真实流式推理增量。
3. 回合结束后要把 session 派生状态一次性回写到 SpacetimeDB。
4. 旧 Node eightAnchorPrompts.ts 的提示词正文保持原样，不改中文文案。

3. 约束

3.1 SpacetimeDB 约束

SpacetimeDB reducer / procedure 必须保持确定性，因此：

1. 禁止在 spacetime-module 内直接发起 LLM 网络请求。
2. LLM 调用必须放在 api-server。
3. spacetime-module 只负责提交消息、记录 operation、回写最终结果。

3.2 提示词冻结约束

本轮严格复用旧 Node 的以下提示词内容：

1. server-node/src/prompts/eightAnchorPrompts.ts
2. BASE_SYSTEM_PROMPT
3. GLOBAL_HARD_RULES
4. MODE_RULES
5. USER_SIGNAL_RULES
6. QUICK_FILL_EXTRA_RULES
7. STATE_INFERENCE_SYSTEM_PROMPT
8. STATE_INFERENCE_OUTPUT_CONTRACT
9. OUTPUT_CONTRACT_REMINDER

允许做的只有：

1. Rust 字符串字面量搬运
2. Rust 函数式重组
3. Rust/Serde 语法等价改写

不允许：

1. 修改提示词正文
2. 调整规则措辞
3. 替换成新的 prompt 版本

4. 目标链路

恢复后的消息链路改成两阶段：

4.1 阶段 A：提交消息

submit_custom_world_agent_message

职责：

1. 校验 session / message / operation id。
2. 只写入 user message。
3. 创建 process_message operation。
4. operation 初始状态写为 running。
5. 不直接写 assistant message。
6. 不直接推进 progress / stage / current_turn。

4.2 阶段 B：完成单轮推理

finalize_custom_world_agent_message_turn

职责：

1. 校验 session 与 operation 所属关系。
2. 追加 assistant message。
3. 回写 session 聚合字段：
   • current_turn
   • progress_percent
   • stage
   • focus_card_id
   • anchor_content_json
   • creator_intent_json
   • creator_intent_readiness_json
   • anchor_pack_json
   • draft_profile_json
   • last_assistant_reply
   • pending_clarifications_json
   • suggested_actions_json
   • recommended_replies_json
   • quality_findings_json
   • asset_coverage_json
4. 更新对应 operation 为 completed 或 failed。

5. api-server 责任

api-server 新增 Custom World Agent turn service，负责：

1. 读取当前 session 快照。
2. 按旧 Node 逻辑构造 chat history。
3. 先走“动态状态识别”推理。
4. 再走“正式单轮输出”推理。
5. 流式阶段从 JSON 片段里增量截取 replyText，持续往 SSE 发 reply_delta。
6. 回合结束后派生：
   • creator intent
   • readiness
   • pending clarifications
   • suggested actions
   • anchor pack
   • draft profile
   • quality findings
   • asset coverage
7. 最后调用 SpacetimeDB finalize procedure 回写真相。

6. 旧 Node 逻辑恢复范围

本轮恢复以下旧 Node 行为：

1. eightAnchorPrompts.ts
2. eightAnchorSingleTurnService.ts
3. customWorldAgentMessageTurnService.ts
4. customWorldAgentClarificationService.ts
5. customWorldAgentIntentExtractionService.ts
6. customWorldAgentSuggestedActionService.ts
7. eightAnchorCompatibilityService.ts 中聊天链需要的 anchor / progress 派生

本轮不强制一比一恢复整条结果页重编译链，只恢复聊天链真正依赖的最小派生结果。

7. SSE 口径

恢复后 /messages/stream 必须按以下顺序输出：

1. 多个 reply_delta
2. 一个 session
3. 一个 done

错误时输出：

1. error

要求：

1. reply_delta.text 来源于 platform-llm.stream_text(...) 的真实增量。
2. session 必须来自 finalize 完成后的最新 session 真相。

8. 验收

1. 用户发一条 Agent 消息后，assistant 回复不再是固定文案。
2. quickFillRequested=true 时，推理结果仍遵循旧 Node 的 force_complete 逻辑。
3. SSE 能先看到逐步增长的 reply_delta，而不是一次性整段返回。
4. finalize 完成后，前端拿到的 session 中：
   • lastAssistantReply
   • messages
   • currentTurn
   • progressPercent
   • stage
   • pendingClarifications
   • suggestedActions 已被真实更新。
5. 提示词正文未被改写。

9. 当前实现状态

截至 2026-04-22，本方案已在 server-rs 完成以下落地：

1. submit_custom_world_agent_message 已改为只提交 user message 与 running operation，不再写死 assistant 回复。
2. api-server 的 Custom World Agent turn service 已恢复：
   • 动态状态识别
   • 正式单轮推理
   • replyText/progressPercent/nextAnchorContent JSON 解析
   • creator intent / readiness / clarification / suggested action 等最小派生
3. /api/runtime/custom-world/agent/sessions/:sessionId/messages/stream 已改为真实 SSE 流：
   • 推理进行中实时输出累计 reply_delta
   • finalize 后输出最新 session
   • 最后输出 done
4. 普通提交接口在 finalize 完成后返回最终 operation 快照，而不是 submit 阶段的 running 快照。
5. finalize_custom_world_agent_message_turn 已负责把 assistant message、session 聚合字段与 operation 最终状态一次性回写到 SpacetimeDB。