# 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`
3. 更新对应 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。