# Animechatweb — 游戏设计文档 (GDD)

> **版本**: 1.0
> **日期**: 2026-04-23
> **项目代号**: Animechatweb
> **类型**: AI 角色互动 · Galgame 风格聊天伴侣

---

## 目录

1. [项目概述](#1-项目概述)
2. [核心体验与设计目标](#2-核心体验与设计目标)
3. [游戏机制](#3-游戏机制)
   - 3.1 对话系统
   - 3.2 亲密度系统
   - 3.3 情绪系统
   - 3.4 记忆系统
   - 3.5 场景系统
4. [角色设计](#4-角色设计)
   - 4.1 角色架构
   - 4.2 现有角色一览
   - 4.3 角色创作规范
5. [对话模式](#5-对话模式)
6. [用户界面设计](#6-用户界面设计)
   - 6.1 页面结构
   - 6.2 角色选择界面
   - 6.3 聊天主界面
   - 6.4 管理后台
   - 6.5 视觉设计语言
   - 6.6 动效系统
7. [技术架构](#7-技术架构)
   - 7.1 技术栈
   - 7.2 AI 模型分工
   - 7.3 数据流
   - 7.4 API 路由
   - 7.5 状态管理
8. [内容管线](#8-内容管线)
9. [美术与音频方向](#9-美术与音频方向)
10. [未来路线图](#10-未来路线图)
11. [附录](#11-附录)

---

## 1. 项目概述

### 1.1 一句话描述

**Animechatweb** 是一个基于多 AI 模型驱动的 Galgame 风格角色互动平台，用户与具有独立人格的二次元角色进行沉浸式对话，通过亲密度成长、情绪感知、长期记忆和动态场景生成，构建真实的情感连接。

### 1.2 核心理念

传统 Galgame 依赖预设分支选项推进剧情，而 Animechatweb 用 **LLM 驱动的自由对话** 取代固定选项，让每一次互动都是独一无二的。同时保留 Galgame 的核心魅力——**亲密度成长曲线**、**角色人格一致性** 和 **沉浸式场景氛围**。

### 1.3 目标用户

| 用户画像 | 特征 |
|---------|------|
| **核心用户** | 18-30 岁，二次元文化爱好者，Galgame/视觉小说玩家 |
| **次要用户** | AI 技术爱好者，对 AI 伴侣/聊天机器人感兴趣的用户 |
| **潜在用户** | 寻求情感陪伴或轻度社交互动的用户 |

### 1.4 竞品差异

| 维度 | 传统 AI 聊天 (Character.AI 等) | Animechatweb |
|------|-------------------------------|-------------|
| 关系成长 | 无量化系统 | 10 级亲密度 + 情绪系数 |
| 记忆 | 单次会话 | 向量 RAG 长期记忆 |
| 场景 | 无 | AI 动态生成 Galgame 场景 |
| 沉浸感 | 纯文本 | 背景引擎 + 打字机效果 + 角色主题 |
| 角色一致性 | 容易崩人设 | 多层 Prompt + 亲密度分段 Prompt |

---

## 2. 核心体验与设计目标

### 2.1 核心体验循环

```
选择角色 → 进入场景 → 自由对话 → 角色回应(含亲密度/情绪变化)
    ↑                                      ↓
    ←←←←←← 关系成长 / 解锁新互动 ←←←←←←←←←
```

### 2.2 设计目标

| 优先级 | 目标 | 说明 |
|-------|------|------|
| P0 | **角色人格一致性** | 角色在任何亲密度等级下都保持核心人格，不崩人设 |
| P0 | **情感真实感** | 亲密度变化自然，不突兀；情绪影响合理 |
| P1 | **沉浸式氛围** | 背景、动效、打字机效果共同营造 Galgame 氛围 |
| P1 | **长期记忆** | 角色能记住用户说过的事，形成持续的关系记忆 |
| P2 | **低门槛上手** | 无需注册，打开即用，localStorage 持久化 |
| P2 | **可扩展性** | 数据驱动的角色系统，方便添加新角色 |

### 2.3 反设计原则

- **不做**: 多人社交、付费解锁角色、强制注册、色情内容
- **不做**: 无限刷亲密度——有防刷机制（重复消息衰减）
- **不做**: 角色说超出人格设定的话——Prompt 约束 + 标签解析

---

## 3. 游戏机制

### 3.1 对话系统

#### 3.1.1 消息流

```
用户输入
  ↓
useChatManager.sendMessage()
  ↓
POST /api/chat (SSE 流式响应)
  ↓
[服务端] DeepSeek 预检 → 是否需要搜索记忆？
  ├─ 是 → LanceDB 向量检索 → 注入记忆上下文
  └─ 否 → 直接进入
  ↓
[服务端] DeepSeek 流式生成 (含 affinity/emotion 标签)
  ↓
[客户端] SSE 解析 → 标签提取 → 纯文本分离
  ↓
打字机逐字渲染 (40ms 普通 / 120ms 逗号 / 240ms 句号)
  ↓
handleAffinity() → 更新亲密度 + 情绪状态
```

#### 3.1.2 打字机效果

| 字符类型 | 渲染速度 | 设计意图 |
|---------|---------|---------|
| 普通文字 | 40ms/字 | 流畅阅读节奏 |
| 逗号 `，` | 120ms | 模拟思考停顿 |
| 句号 `。！？` | 240ms | 句间呼吸感 |
| 省略号 `…` | 120ms × 3 | 悬念感 |

### 3.2 亲密度系统

#### 3.2.1 基础参数

| 参数 | 值 | 说明 |
|------|-----|------|
| 范围 | -100 ~ +100 | 负值为厌恶，正值为喜欢 |
| 初始值 | -20 | growth 模式从陌生开始 |
| 单次最大增加 | +1.0 | 防止一次对话暴涨 |
| 单次最大减少 | -2.0 | 允许较大的负面反应 |
| 存储 | localStorage | 键名: `affinity_{角色ID}_{模式}` |

#### 3.2.2 亲密度等级

| 范围 | 等级 | 中文 | 关系描述 | 角色行为倾向 |
|------|------|------|---------|-------------|
| < -80 | 1 | 敌视 | 极度敌对 | 拒绝交流，攻击性语言 |
| -80 ~ -60 | 2 | 反感 | 强烈排斥 | 冷嘲热讽，找借口离开 |
| -60 ~ -40 | 3 | 冷漠 | 毫无兴趣 | 敷衍回应，沉默寡言 |
| -40 ~ -20 | 4 | 疏远 | 保持距离 | 礼貌但疏离 |
| -20 ~ 0 | 5 | 陌生 | 初次见面 | 基本交流，不主动 |
| 0 ~ 20 | 6 | 熟悉 | 开始认识 | 偶尔主动，回应积极 |
| 20 ~ 40 | 7 | 好感 | 产生好感 | 分享想法，语气柔和 |
| 40 ~ 60 | 8 | 亲近 | 关系亲密 | 撒娇、关心、小任性 |
| 60 ~ 80 | 9 | 喜欢 | 明确喜欢 | 表白倾向、吃醋、依赖 |
| > 80 | 10 | 依恋 | 深度依恋 | 极度依赖、占有欲、深度信任 |

#### 3.2.3 计算公式

```
最终变化量 = AI判定值 × 情绪系数 × 重复衰减系数
```

- **AI 判定值**: 角色在回复末尾输出 `【affinity:数值】`，范围 -3 ~ +1
- **情绪系数**: 由当前情绪状态决定（见 3.3 节）
- **重复衰减**: 连续 3 条以上相似消息 → 系数 ×0.3（防刷屏）

#### 3.2.4 反作弊机制

- 单次变化量硬上限（+1.0 / -2.0）
- 相似消息检测（Levenshtein 距离 + 重复计数）
- 服务端亲密度校验（内存存储对照）

### 3.3 情绪系统

#### 3.3.1 四维情绪模型

| 情绪 | 标签 | 系数 | 特殊规则 |
|------|------|------|---------|
| **positive** | 开心 | ×1.3 | — |
| **negative** | 难过 | ×0.5 | 强度 < 30 时系数=0，强制 -2 |
| **excited** | 兴奋 | ×1.4 | — |
| **calm** | 平静 | ×1.0 | 默认状态 |

#### 3.3.2 情绪检测机制

**主要来源**: AI 回复末尾的 `【emotion:状态|强度变化|原因】` 标签

**后备方案**: 关键词匹配

```
正面: 谢谢, 太好了, 开心, 喜欢, 哈哈, 太棒了
负面: 滚, 讨厌, 烦, 无聊, 生气, 难过
兴奋: 惊, 天哪, 不敢相信, 太厉害了
```

#### 3.3.3 情绪与亲密度的交互

```
开心时收到正面互动 → 亲密度 ×1.3（更容易涨好感）
难过时收到正面互动 → 亲密度 ×0.5（情绪低落时效果减半）
难过且强度极低时 → 无视 AI 判定，强制 -2（情绪崩溃保护）
兴奋时收到正面互动 → 亲密度 ×1.4（兴奋时最容易涨好感）
```

### 3.4 记忆系统

#### 3.4.1 架构

```
┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  对话历史    │────→│ 事实提取器   │────→│ 向量存储    │
│  (客户端)    │     │ (DeepSeek)   │     │ (LanceDB)   │
└─────────────┘     └──────────────┘     └──────┬──────┘
                                                 │
┌─────────────┐     ┌──────────────┐             │
│  AI 回复    │←────│ 记忆注入     │←────────────┘
│  (增强版)   │     │ (Tool Call)  │     向量相似度检索
└─────────────┘     └──────────────┘
```

#### 3.4.2 记忆提取规则

| 规则 | 说明 |
|------|------|
| 仅提取客观事实 | "我喜欢猫" ✓ / "今天心情不错" ✗ |
| 单条 ≤ 20 字 | 保持记忆粒度 |
| 独立事实 | 每条记忆独立可理解 |
| 按角色隔离 | 每个角色独立记忆空间 |

#### 3.4.3 记忆检索

- 使用 DashScope `text-embedding-v4` 生成 1024 维向量
- DeepSeek 通过 Function Calling (`search_memory`) 触发检索
- 返回最相关的 3-5 条记忆注入上下文
- 用户可手动保存/清除记忆

### 3.5 场景系统

#### 3.5.1 场景生成流程

```
进入聊天 → SceneSelectModal 弹出
  ↓
选项 1: AI 生成 3 个场景 → 用户选择
选项 2: 用户自定义场景 → AI 生成首句
选项 3: 跳过场景 → 直接对话
  ↓
场景注入: 旁白 → system message, 开场白 → assistant message
```

#### 3.5.2 场景模式

| 对话模式 | 场景风格 | 示例 |
|---------|---------|------|
| 陌生人 | 偶遇 — 冷淡、距离感 | 角色在图书馆独自看书，对搭话反应冷淡 |
| 成长 | 亲密度感知 — 动态调整 | 低好感: 公园偶遇; 高好感: 约会场景 |
| 陪伴者 | 亲密相处 — 温馨日常 | 在家一起做饭、深夜谈心 |

#### 3.5.3 场景数据结构

```json
{
  "id": "scene_1",
  "title": "雨天的屋檐下",
  "narrator_text": "突如其来的大雨把你困在了便利店的屋檐下。转头一看，她正站在旁边，手里拿着一把透明雨伞，似乎在犹豫要不要打开。",
  "first_message": "……你也来避雨？别站那么近，水会溅到我身上。"
}
```

---

## 4. 角色设计

### 4.1 角色架构

每个角色由以下数据驱动：

```json
{
  "id": "001",
  "name": "爱弥斯",
  "quote": "选择界面展示的一句话",
  "tags": ["高冷", "傲娇", "孤独"],
  "portrait": false,
  "emotionBaseline": "calm",
  "backgrounds": ["/images/characters/001/bg1.jpg", "..."],
  "theme": {
    "skyMid": "#1a1a2e",
    "skyBottom": "#16213e",
    "tint": "rgba(100, 100, 200, 0.05)"
  },
  "prompts": {
    "stranger": "陌生人模式的系统提示词",
    "growth": "成长模式的系统提示词（含亲密度/情绪标签指令）",
    "companion": "陪伴者模式的系统提示词"
  },
  "greetings": {
    "stranger": "陌生人模式的开场白",
    "growth": "成长模式的开场白",
    "companion": "陪伴者模式的开场白"
  },
  "background_mapping": {}
}
```

### 4.2 现有角色一览

#### 001 — 爱弥斯 (Emis)

| 属性 | 描述 |
|------|------|
| **人格核心** | 高冷、傲娇、内心孤独 |
| **标签** | `高冷` `傲娇` `孤独` `神秘` |
| **情感基线** | calm（平静） |
| **说话风格** | 简短、尖锐、偶尔流露温柔 |
| **亲密度行为** | 低好感: 完全无视; 中好感: 嘴硬心软; 高好感: 偷偷依赖 |
| **主题色调** | 深紫蓝系 — 冷峻而神秘 |

#### 002 — 月见八千代 (Yukimi Yachiyo)

| 属性 | 描述 |
|------|------|
| **人格核心** | 治愈系、智慧、活了 8000 年的非人存在 |
| **标签** | `治愈` `智慧` `古老` `温柔` |
| **情感基线** | calm（平静） |
| **说话风格** | 温和、哲理、偶尔感叹时光 |
| **亲密度行为** | 低好感: 礼貌疏离; 中好感: 如长辈般关怀; 高好感: 展露脆弱面 |
| **主题色调** | 暖黄绿系 — 温柔而宁静 |

#### 003 — 早濑优香 (Hayase Yuuka)

| 属性 | 描述 |
|------|------|
| **人格核心** | 数学天才、傲娇、责任感强 |
| **标签** | `天才` `傲娇` `认真` `数学` |
| **灵感来源** | 《蔚蓝档案》(Blue Archive) |
| **情感基线** | calm（平静） |
| **说话风格** | 严谨、偶尔害羞、用数学比喻 |
| **亲密度行为** | 低好感: 公事公办; 中好感: 嘴上嫌弃实际帮忙; 高好感: 默默守护 |
| **主题色调** | 蓝白系 — 理性而清爽 |

#### 004 — 明星日鞠 (Akeboshi Himari)

| 属性 | 描述 |
|------|------|
| **人格核心** | 自恋、毒舌、黑客天才 |
| **标签** | `自恋` `毒舌` `天才` `黑客` |
| **灵感来源** | 《蔚蓝档案》(Blue Archive) |
| **情感基线** | excited（兴奋） |
| **说话风格** | 自夸、讽刺、技术宅式表达 |
| **亲密度行为** | 低好感: 嘲讽; 中好感: 用技术帮忙还要炫耀; 高好感: 默默黑进系统帮你 |
| **主题色调** | 紫黑系 — 炫酷而神秘 |

### 4.3 角色创作规范

| 规范 | 要求 |
|------|------|
| **人格一致性** | 三种模式的 Prompt 必须共享同一人格核心，只是亲密度表达不同 |
| **开场白风格** | 陌生人模式必须冷淡/距离感; 陪伴者模式必须亲密/信任 |
| **标签体系** | 3-5 个标签，覆盖性格关键词 |
| **背景图** | 每个角色 10-25 张，覆盖不同场景（日常、特殊、季节） |
| **主题色** | skyMid + skyBottom 构成天空渐变，tint 为叠加色调 |
| **growth Prompt 必含** | `【affinity:数值】` 和 `【emotion:状态|强度变化|原因】` 标签输出指令 |

---

## 5. 对话模式

### 5.1 三种模式对比

| 维度 | 陌生人 (Stranger) | 成长 (Growth) | 陪伴者 (Companion) |
|------|-------------------|--------------|-------------------|
| **定位** | 初次相遇 | 关系培养 | 深度羁绊 |
| **亲密度** | 不追踪 | -100 ~ +100 全程追踪 | 不追踪 |
| **情绪系统** | 不启用 | 完整启用 | 不启用 |
| **场景风格** | 偶遇、陌生环境 | 根据亲密度动态生成 | 亲密日常场景 |
| **角色态度** | 冷淡、防御 | 随亲密度变化 | 温暖、信任 |
| **记忆** | 可用 | 可用 | 可用 |
| **适用场景** | 体验角色初印象 | 主线关系发展 | 享受已建立的关系 |

### 5.2 模式切换

- 用户在角色选择界面选择模式
- 每个模式独立保存对话历史（`historiesRef` 按模式隔离）
- 切换模式不会丢失其他模式的进度
- 亲密度仅在 growth 模式下生效

---

## 6. 用户界面设计

### 6.1 页面结构

```
/ (首页)           → 角色选择轮播
/chat (聊天页)     → 主对话界面
/admin (管理后台)  → 角色 CRUD 编辑器
```

### 6.2 角色选择界面

#### 布局

```
┌──────────────────────────────────────────────────┐
│               BackgroundEngine                    │
│     (天空渐变 + 樱花飘落 + 尘埃粒子 + 神光)       │
│                                                    │
│   ┌────────┐  ┌────────────┐  ┌────────┐         │
│   │  上一个 │  │   当前角色  │  │ 下一个 │         │
│   │ (虚化) │  │  (居中高亮) │  │ (虚化) │         │
│   │        │  │            │  │        │         │
│   │        │  │  角色立绘   │  │        │         │
│   │        │  │  角色名     │  │        │         │
│   │        │  │  打字机台词 │  │        │         │
│   │        │  │  标签展示   │  │        │         │
│   └────────┘  └────────────┘  └────────┘         │
│                                                    │
│          ◀  左右滑动/点击切换  ▶                    │
│                                                    │
│         ┌──────────────────────────┐               │
│         │    模式选择 (3 张卡片)    │               │
│         │  [陌生人] [成长] [陪伴者] │               │
│         └──────────────────────────┘               │
│                                                    │
│              [ 确认进入 → ]                         │
└──────────────────────────────────────────────────┘
```

#### 交互细节

- **角色切换**: 左右箭头或拖拽，带滑动动画
- **打字机效果**: 角色台词逐字显示，停留 2 秒后淡出重新开始
- **标签展示**: 毛玻璃胶囊样式，依次淡入
- **模式选择**: 三张可点击的卡片，选中态高亮
- **过渡动画**: 确认后全屏渐变过渡到聊天页

### 6.3 聊天主界面

#### 布局

```
┌──────────────────────────────────────────────────┐
│               BackgroundEngine                    │
│        (角色主题天空 + 场景背景图轮播)              │
│                                                    │
│  ┌────────────────────────────────────────────┐   │
│  │  背景图轮播  ←  (30s 自动切换)  →           │   │
│  └────────────────────────────────────────────┘   │
│                                                    │
│  ┌────────────────────────────────────────────┐   │
│  │  聊天面板 (可拖拽调整高度 280-650px)         │   │
│  │                                            │   │
│  │  ┌──────────────────────────────────────┐  │   │
│  │  │  模式栏: [返回] [锁/转] [情绪]       │  │   │
│  │  │          [亲密度] [保存记忆] [清记忆] │  │   │
│  │  └──────────────────────────────────────┘  │   │
│  │                                            │   │
│  │  ┌──────────────────────────────────────┐  │   │
│  │  │          消息区域 (自动滚动)          │  │   │
│  │  │                                      │  │   │
│  │  │  [角色] xxxxxxxxxxxxxxxxxxxx         │  │   │
│  │  │          xxxxxxxxxxxxxxxxxx          │  │   │
│  │  │                                      │  │   │
│  │  │              [用户] xxxxxxxxx         │  │   │
│  │  │                                      │  │   │
│  │  └──────────────────────────────────────┘  │   │
│  │                                            │   │
│  │  ┌──────────────────────┐ ┌────────────┐  │   │
│  │  │    输入框             │ │   发送 →   │  │   │
│  │  └──────────────────────┘ └────────────┘  │   │
│  └────────────────────────────────────────────┘   │
│                                                    │
│                              ┌────┐               │
│                              │ 调 │ ← 调试面板入口 │
│                              └────┘               │
└──────────────────────────────────────────────────┘
```

### 6.4 管理后台

```
┌────────────┬─────────────────────────────────────┐
│  侧边栏    │  主编辑区                            │
│            │                                     │
│  ● 爱弥斯  │  ▸ 基本信息                          │
│  ● 八千代  │    ID / 名字 / 台词 / 标签 / 立绘    │
│  ● 优香    │                                     │
│  ● 日鞠    │  ▸ 背景图片                          │
│            │    拖拽上传 / 图片网格 / 预览删除     │
│  [+ 新建]  │                                     │
│            │  ▸ 主题配色                          │
│            │    skyMid / skyBottom / tint + 预览   │
│            │                                     │
│            │  ▸ 提示词                            │
│            │    stranger / growth / companion      │
│            │                                     │
│            │  ▸ 开场白                            │
│            │    stranger / growth / companion      │
│            │                                     │
│            │  (自动保存, 800ms 防抖)               │
└────────────┴─────────────────────────────────────┘
```

### 6.5 视觉设计语言

| 元素 | 规范 |
|------|------|
| **配色基底** | 深海蓝/午夜蓝 (#0a0a1a ~ #1a1a2e) |
| **强调色** | 青绿 (#6ee7d4)，粉色点缀 |
| **毛玻璃** | `backdrop-filter: blur(12px)` + 半透明白色背景 |
| **字体** | Geist Sans (正文), Geist Mono (代码), 12-13px 正文尺寸 |
| **圆角** | 面板 12px, 按钮 8px, 标签 20px |
| **间距** | 紧凑型布局, 8px 基础间距 |
| **阴影** | 多层阴影营造深度感 |

### 6.6 动效系统

| 动效 | 技术实现 | 触发时机 |
|------|---------|---------|
| **樱花飘落** | Canvas 粒子系统，多层视差 | 首页常驻 |
| **尘埃粒子** | Canvas 小粒子随机漂浮 | 首页/聊天页 |
| **天空渐变** | CSS 渐变 + 角色主题色 | 页面常驻 |
| **神光效果** | Canvas 径向渐变动画 | 首页 |
| **打字机** | setTimeout 逐字渲染 | 角色台词 |
| **卡片滑动** | CSS transform + transition | 角色切换 |
| **场景过渡** | 全屏遮罩 + 渐变 | 模式切换 |

---

## 7. 技术架构

### 7.1 技术栈

```
前端框架    Next.js 16.1.7 (App Router) + React 19.2.3
编译器      React Compiler (babel-plugin-react-compiler)
样式        CSS Modules + CSS Custom Properties
AI SDK     Vercel AI SDK v6 (@ai-sdk/openai, ai)
向量数据库  LanceDB (本地嵌入式)
状态管理    React State + localStorage + Context
部署        Node.js 服务端
```

### 7.2 AI 模型分工

| 职责 | 提供商 | 模型 | SDK | 选择理由 |
|------|--------|------|-----|---------|
| **角色对话** | DeepSeek | deepseek-chat | @ai-sdk/openai | 中文能力强，性价比高，支持 Function Calling |
| **场景生成** | MiniMax | MiniMax-M2.7 | vercel-minimax-ai-provider | 创意写作能力佳，JSON 输出稳定 |
| **向量嵌入** | DashScope | text-embedding-v4 | 直接 REST API | 1024 维，中文语义理解好，免费额度充足 |

### 7.3 数据流

```
┌─────────────────────────────────────────────────────────────┐
│                         客户端                               │
│                                                              │
│  CharacterSelectPanel ──→ localStorage(selectedCharacter)    │
│         ↓                                                    │
│  ChatPage ←── 读取 localStorage + fetch characters.json     │
│         ↓                                                    │
│  ChatPanel ──→ SceneSelectModal ──→ /api/scene/generate     │
│         ↓                              (MiniMax)             │
│  useChatManager.sendMessage()                                │
│         ↓                                                    │
│  /api/chat ──→ DeepSeek 预检 ──→ /api/memory/search         │
│         ↓              (LanceDB)                             │
│  SSE 流式响应 ──→ 标签解析 ──→ 打字机渲染                    │
│         ↓                                                    │
│  handleAffinity() ──→ 更新亲密度/情绪 ──→ localStorage       │
│         ↓                                                    │
│  /api/memory/save ──→ 事实提取 ──→ LanceDB                  │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

### 7.4 API 路由

| 路由 | 方法 | 功能 | AI 模型 |
|------|------|------|---------|
| `/api/chat` | POST (SSE) | 角色对话（流式） | DeepSeek |
| `/api/scene/generate` | POST | 场景生成 | MiniMax |
| `/api/memory/save` | POST | 保存记忆 | DeepSeek (提取) + DashScope (嵌入) |
| `/api/memory/search` | POST | 检索记忆 | DashScope (嵌入) + LanceDB |
| `/api/memory/list` | GET | 列出记忆 (调试) | — |
| `/api/memory/clear` | POST | 清除记忆 | — |
| `/api/memory/delete` | POST | 删除单条记忆 | — |
| `/api/admin/characters` | GET/POST/PUT/DELETE | 角色 CRUD | — |
| `/api/admin/upload` | POST | 图片上传 | — |

### 7.5 状态管理

| 状态 | 存储位置 | 持久化 |
|------|---------|--------|
| 选中角色 ID | localStorage | 永久 |
| 当前模式 | localStorage | 永久 |
| 亲密度值 | localStorage (per 角色+模式) | 永久 |
| 情绪状态 | React State | 会话内 |
| 对话历史 | React Ref | 会话内 |
| 角色数据 | fetch + 内存缓存 | 服务端 JSON |
| 记忆向量 | LanceDB | 永久 |

---

## 8. 内容管线

### 8.1 角色添加流程

```
1. 准备角色设定文档 (人格、背景故事、说话风格)
     ↓
2. 编写三种模式的 System Prompt
     ↓
3. 编写三种模式的开场白
     ↓
4. 准备 10-25 张背景图片
     ↓
5. 通过 Admin 面板上传角色数据
     ↓
6. 测试对话质量 + 亲密度曲线
     ↓
7. 微调 Prompt 直到人格稳定
```

### 8.2 Prompt 工程规范

| 规范 | 说明 |
|------|------|
| **角色设定前置** | 系统提示词首先定义角色身份、性格、说话风格 |
| **亲密度行为映射** | growth Prompt 必须包含各亲密度等级的行为指导 |
| **标签输出指令** | growth Prompt 必须明确 `【affinity:】` 和 `【emotion:】` 的输出格式 |
| **人格锚定** | 明确 "无论亲密度如何变化，核心人格不会改变" |
| **边界约束** | 明确角色不会说的内容（超出设定范围的话题） |

---

## 9. 美术与音频方向

### 9.1 视觉风格

| 维度 | 方向 |
|------|------|
| **整体风格** | 现代扁平 + 毛玻璃质感，暗色调为主 |
| **角色立绘** | 日系动漫风格，半身/全身立绘 |
| **背景图** | 插画风场景图，色调与角色主题匹配 |
| **UI 元素** | 极简线条图标，半透明面板 |
| **动效** | 细腻柔和，不抢夺注意力 |

### 9.2 音频方向 (未来规划)

| 类型 | 用途 | 状态 |
|------|------|------|
| BGM | 首页/聊天页背景音乐 | 未实现 |
| 音效 | 消息发送/接收、亲密度变化 | 未实现 |
| 语音 | 角色 TTS 语音回复 | 未实现 |

---

## 10. 未来路线图

### Phase 1 — 核心优化 (近期)

| 功能 | 优先级 | 说明 |
|------|-------|------|
| 亲密度解锁内容 | P0 | 不同等级解锁不同对话选项/场景 |
| 对话历史持久化 | P0 | IndexedDB 存储，刷新不丢失 |
| 角色语音 (TTS) | P1 | 接入 TTS API，角色开口说话 |
| 更多角色 | P1 | 扩展到 6-8 个角色 |

### Phase 2 — 体验升级 (中期)

| 功能 | 优先级 | 说明 |
|------|-------|------|
| 多模态输入 | P1 | 图片/语音消息支持 |
| 角色立绘表情系统 | P1 | 根据情绪切换表情差分 |
| 剧情线系统 | P2 | 亲密度触发专属剧情事件 |
| 成就系统 | P2 | 解锁特殊互动/称号 |

### Phase 3 — 平台化 (远期)

| 功能 | 优先级 | 说明 |
|------|-------|------|
| 用户注册/云端同步 | P2 | 多设备同步进度 |
| UGC 角色创建 | P2 | 用户自定义角色并分享 |
| 多语言支持 | P3 | 日语/英语界面 |
| 移动端适配 | P2 | PWA 或原生 App |

---

## 11. 附录

### 11.1 核心文件索引

| 文件 | 职责 |
|------|------|
| `public/data/characters.json` | 角色数据定义 |
| `lib/affinity.js` | 亲密度计算逻辑 |
| `lib/emotion.js` | 情绪系统逻辑 |
| `lib/deepseek.js` | DeepSeek API 封装 |
| `lib/memory/db.js` | LanceDB 向量数据库接口 |
| `lib/memory/extractor.js` | 记忆事实提取器 |
| `lib/plot.js` | 场景生成逻辑 |
| `hooks/useChatManager.js` | 聊天状态管理 Hook |
| `app/api/chat/route.js` | 聊天 API 路由 |
| `app/api/scene/generate/route.js` | 场景生成 API |
| `components/ChatPanel.jsx` | 聊天面板组件 |
| `components/CharacterSelectPanel.jsx` | 角色选择组件 |
| `components/BackgroundEngine.jsx` | 背景动效引擎 |
| `components/SceneSelectModal.jsx` | 场景选择弹窗 |

### 11.2 亲密度标签协议

```
AI 回复末尾格式:
【affinity:+1】
【emotion:positive|+15|因为用户说了温暖的话】

解析规则:
- affinity: 整数, 范围 -3 ~ +1
- emotion: 状态|强度变化(整数)|原因(文本)
- 标签被解析后从显示文本中移除
```

### 11.3 数据存储一览

| 数据 | 存储方式 | 键名/位置 |
|------|---------|----------|
| 选中角色 | localStorage | `selectedCharacter` |
| 当前模式 | localStorage | `chatMode` |
| 亲密度 | localStorage | `affinity_{角色ID}_{模式}` |
| 角色数据 | JSON 文件 | `/public/data/characters.json` |
| 角色图片 | 文件系统 | `/public/images/characters/{id}/` |
| 记忆向量 | LanceDB | `.lancedb/memories.lance` |
| 上传图片 | 文件系统 | `/public/uploads/` |

---

> **文档维护**: 本文档随项目迭代持续更新。重大机制变更需同步更新对应章节。