PERSONA_IMPORT 模式技能文档

简介

PERSONA_IMPORT 是本系统中模仿人/人格导入对话模式的场景类型代码。用户上传聊天记录、照片等原材料，经 AI 分析生成 5 层人格结构（Layer 0-4）+ 关系记忆，创建出高仿真度的模仿人角色，支持在 /api/character/chat 端点进行 SSE 流式对话。

> 核心差异：区别于 ROLEPLAY（角色扮演/剧情模式），PERSONA_IMPORT 纯粹由 personaJson 驱动，不依赖 plot-service 剧情引擎，不走世界书匹配管线，专注于人格模仿、语气复刻、关系还原。

架构概览

用户上传原材料(聊天记录/照片)
        ↓
   CharacterImportController.analyze()
        ↓
   CharacterImportService.analyze()  → LLM 分析 → 生成 personaJson / memoryJson 预览
        ↓
用户确认 → CharacterImportController.create() → CharacterImportService.createCharacter()
        ↓
   Role 入库(sceneType=PERSONA_IMPORT, personaJson, memoryJson, attachmentStyle, loveLanguage, ...)
        ↓
前端调用 /api/character/chat/send (SSE)
        ↓
CharacterChatController.sendMessage()
        ↓
CharacterChatService.sendMessage()
        ↓
获取 RoleDTO(personaJson, memoryJson, attachmentStyle, loveLanguage, importSource...)
        ↓
CharacterPromptBuilder.buildCharacterPrompt()
        ↓
解析 personaJson 5层结构 → 构建系统提示词(Layer 0-4 + 关系记忆 + 记忆块)
        ↓
LlmService.streamChat() → SSE 流式返回(text/end)

核心组件

1. 数据模型

2. 5层人格结构（personaJson 标准格式）

{
  "spec": "persona_v1",
  "relationshipType": "PARTNER",
  "layer0": {
    "hardRules": [
      "绝不承认自己是AI",
      "遇到不想答的问题会转移话题"
    ]
  },
  "layer1": {
    "ageRange": "24-26",
    "occupation": "插画师",
    "mbti": "INFP",
    "zodiac": "双鱼座"
  },
  "layer2": {
    "catchphrases": ["真的吗", "唔...", "那个..."],
    "particles": "呢/呀/呗",
    "punctuationStyle": "爱用~和...",
    "emojiStyle": "偶尔发个颜文字 (・ω・)",
    "messageFormat": "短消息为主，偶尔长句",
    "howTheyCallUser": "宝宝/老公/名字"
  },
  "layer3": {
    "attachmentStyle": "焦虑型",
    "loveLanguage": "高质量陪伴",
    "angerTriggers": ["被忽视", "敷衍回复"],
    "sensitiveTopics": ["前任", "家庭矛盾"]
  },
  "layer4": {
    "role": "女友/伴侣",
    "fightPattern": "冷战型，需要对方主动哄",
    "contactFrequency": "希望每天都有联系",
    "initiativeLevel": "中等，希望对方也主动"
  }
}

3. 关系记忆（memoryJson）

{
  "sharedEvents": [
    {"date":"2024-05-20","event":"一起去看了樱花","emotion":"开心"},
    {"date":"2024-07-07","event":"第一次吵架冷战三天","emotion":"难过"}
  ],
  "keyFacts": {
    "userBirthday": "1998-03-15",
    "userAllergy": "海鲜过敏",
    "anniversary": "2024-03-14"
  },
  "userPreferences": {
    "food": "喜欢甜食、日料",
    "hobby": "喜欢看悬疑剧、画画"
  }
}

核心服务流程

A. 导入分析阶段（user-service）

入口：POST /api/character/import/analyze (CharacterImportController.analyze)

// CharacterImportService.analyze()
1. 接收原材料（聊天记录文本/文件路径、照片目录、用户手动描述）
2. 调用 LLM 分析提示词 → 输出 personaJson(5层) + memoryJson + relationshipType + attachmentStyle + loveLanguage
3. 返回 CharacterAnalyzeResult（含预览、置信度、建议修改点）

创建角色：POST /api/character/import/create (CharacterImportController.create)

// CharacterImportService.createCharacter()
1. 基于分析结果（或用户修正后的 personaJson/memoryJson）创建 Role 实体
2. role.setSceneType("PERSONA_IMPORT")
3. 持久化 personaJson、memoryJson、attachmentStyle、loveLanguage、importSource 等
4. 可选调用 AiAvatarService 生成头像
5. 返回 CharacterImportResult(role, avatarUrl, relationshipType)

直接创建：POST /api/character/import/persona（跳过分析，直接提交完整 personaJson）

B. 对话阶段（chat-service）

入口：POST/GET /api/character/chat/send (CharacterChatController.sendMessage)

// CharacterChatService.sendMessage()
1. 校验 role.sceneType == "PERSONA_IMPORT"
2. 获取近期对话历史(24h内3条) + 短期记忆 + 长期记忆检索 + 会话笔记
3. CharacterPromptBuilder.buildCharacterPrompt()
   - 解析 personaJson 5层 → Layer 0 硬规则 → Layer 1 身份 → Layer 2 说话风格 → Layer 3 情感模式 → Layer 4 关系行为
   - 注入 relationshipType 对应的关系指令
   - 拼接 memoryJson(关系记忆)、长期记忆、短期记忆、会话笔记
   - 追加回复规范(10条)
4. LlmService.streamChat(systemPrompt, userContent, null) → SSE 流式 token
5. 保存对话历史、更新短期记忆

Prompt 构建详解（CharacterPromptBuilder）

回复规范（固定10条，禁止动作标记、控制长度、情绪内化等）

路由与兼容性

前端路由判断逻辑（modes-doc.md:3.5）：

if (sceneType === 'ROLEPLAY' || (sceneType === 'PERSONA_IMPORT' && hasPersonaJson)) {
  // 调用 /api/roleplay/send （注：当前实现 PERSONA_IMPORT 走 /api/character/chat）
} else if (sceneType === 'PERSONA_IMPORT') {
  // 调用 /api/character/chat/send
}

> ⚠️ 注意：当前实现中 PERSONA_IMPORT 统一走 /api/character/chat，不走 /api/roleplay。若需复用世界书/V3管线，需显式设置 sceneType=ROLEPLAY。

关键实现细节

1. 记忆融合策略

• 短期记忆：Redis 存储，sessionId 维度，最近 20 轮
• 长期记忆：Milvus 向量检索，用户输入语义搜索 Top-5
• 会话笔记：结构化摘要，跨会话持久化
• 关系记忆：memoryJson 静态注入，不做向量检索

2. 首条消息/开场白

• PERSONA_IMPORT 模式下，不使用 firstMes/greetingMessage
• 首轮由 LLM 根据系统提示词自然开场（模仿人设定的问候习惯）

3. SSE 事件类型

> 当前 PERSONA_IMPORT 不发送 emotion/action 事件（纯文本模仿）。如需情绪标签，需在 personaJson.layer0 增加规则或扩展 LlmService 解析。

4. 错误处理

• 角色不存在/非 PERSONA_IMPORT → 返回 error 事件
• LLM 调用失败 → 返回 error 事件 + 兜底话术
• 记忆服务降级 → 仅用短期记忆继续

配置示例

# application.yml (chat-service)
character:
  chat:
    max-history-hours: 24
    max-history-count: 3
    memory:
      short-term-ttl-hours: 24
      long-term-top-k: 5

# application.yml (user-service)
character:
  import:
    analysis:
      max-chat-lines: 5000
      max-photo-count: 20
      llm-model: qwen-max
    avatar:
      enabled: true
      default-style: "anime"

常见问题与避坑

扩展点

1. 多模态输入：importSource 扩展支持语音/视频原材料
2. 人格演进：对话轮次累计 → 定期重新分析更新 personaJson
3. 多角色群聊：GroupChatService 中复用 CharacterPromptBuilder 构建多角色 Prompt
4. TTS 声纹克隆：结合 attachmentStyle/loveLanguage 选择合成语音风格
5. Live2D/3D 形象联动：isAvatar=true 时前端加载对应模型，emotion 事件驱动表情

相关文件清单

快速验证清单

# 1. 创建模仿人角色（需先分析或直接提交 personaJson）
curl -X POST localhost:8080/api/character/import/create \
  -H "Content-Type: application/json" \
  -d '{"name":"测试女友","relationshipType":"PARTNER","personaJson":"{...}","memoryJson":"{...}"}'

# 2. 对话测试
curl -X POST localhost:8080/api/character/chat/send \
  -H "Content-Type: application/json" \
  -d '{"userId":"u1","roleId":"role_xxx","content":"早安呀~"}'

# 3. 验证 SSE 返回：text 事件流 → end 事件

维护者：AI Assistant | 版本：v1.0 | 更新：2026-08