项目架构与数据流

从整体架构到数据模型，全面展示 Replica 的系统设计。

整体架构 Overview

Frontend

React 19 + Vite 8

Tailwind CSS v4

:8780

⇄

Backend

FastAPI + SQLAlchemy

Python 3.13

:8790

⇄

Database

PostgreSQL 17

pgvector

:5432

⇄

LLM / Embedding

vLLM / OpenRouter

OpenAI-compatible

:8001 / :8002

目录结构 Structure

replica/ ├── src/replica/ # Python 后端 │ ├── main.py # FastAPI 入口，注册路由 │ ├── config.py # YAML + Pydantic 配置 │ ├── db/ # 数据库层 │ │ └── database.py # 引擎、会话工厂、Base │ ├── api/ # API 路由层 │ │ ├── schemas.py # Pydantic 请求/响应模型 │ │ ├── chat.py # SSE 流式聊天 │ │ ├── users.py # 用户 CRUD │ │ ├── sessions.py # 会话管理 + 手动提取/压缩 │ │ ├── messages.py # 消息 CRUD + 自动压缩 │ │ ├── memory.py # Evergreen + 知识搜索 + 上下文构建 │ │ ├── memorize.py # 记忆摄入管道 │ │ ├── admin.py # 数据库表查看 │ │ └── config.py # 运行时配置查看/修改 │ ├── models/ # SQLAlchemy ORM 模型 │ │ ├── user.py # User │ │ ├── session.py # Session │ │ ├── message.py # Message + ExtractionStatus │ │ ├── memcell.py # MemCell 原子记忆单元 │ │ ├── knowledge_entry.py # 统一知识表 (episode/event/foresight) │ │ ├── evergreen_memory.py # 长期事实记忆 │ │ └── user_profile.py # 用户画像模型 (deferred) │ ├── services/ # 业务逻辑层 │ │ ├── memorize_service.py # 记忆摄入管道编排 │ │ ├── memory_service.py # 混合检索 (向量+全文+MMR) │ │ ├── context_service.py # 三层上下文组装 │ │ ├── compaction_service.py # 简单 Token 压缩 │ │ ├── semantic_compaction_service.py # LLM 语义压缩 │ │ ├── extraction_service.py # 会话记忆提取 │ │ ├── auto_extraction_service.py # 定时自动提取 │ │ ├── embedding_service.py # 向量化 + Token 计数 │ │ ├── retrieval_utils.py # 检索工具函数 │ │ └── task_manager.py # 异步任务状态管理 │ ├── extractors/ # 记忆提取器 │ │ ├── __init__.py # 数据类型定义 (MemCellData, EpisodeMemory...) │ │ ├── memcell_extractor.py # 边界检测 → MemCell │ │ ├── episode_extractor.py # 情节记忆提取 │ │ ├── event_log_extractor.py # 事件日志提取 │ │ ├── foresight_extractor.py # 前瞻预测提取 │ │ └── profile_extractor.py # 用户画像提取 (deferred) │ ├── providers/ # 可插拔 Provider │ │ ├── llm_provider.py # LLM 工厂 (vLLM/OpenRouter) │ │ └── embedding_provider.py # Embedding 工厂 │ └── prompts/ # 提示词模板 │ ├── en/ # 英文 (conv, episode, event_log, foresight, profile, compaction) │ └── zh/ # 中文 (同结构镜像) ├── web/src/ # React 前端 │ ├── main.tsx # 应用入口 │ ├── router.tsx # 路由定义 (/ → ChatView, /admin → AdminView) │ ├── views/ # 页面视图 │ │ ├── ChatView.tsx # 主聊天界面 (三栏布局) │ │ └── AdminView.tsx # 数据库管理面板 │ ├── components/ # UI 组件 │ │ ├── ChatPanel.tsx # 聊天消息面板 + SSE 流式渲染 │ │ ├── SessionSidebar.tsx # 会话列表侧边栏 │ │ ├── MemoryPanel.tsx # 记忆上下文展示面板 │ │ ├── TokenProgress.tsx # Token 用量进度条 │ │ ├── ApiMonitor.tsx # API 状态监控 │ │ ├── JsonViewer.tsx # JSON 数据查看器 │ │ ├── KonamiCode.tsx # 彩蛋组件 │ │ └── ui/ # 基础 UI 组件 (button, card, dialog, input...) │ ├── api/ # API 客户端层 │ │ ├── client.ts # HTTP 客户端基础配置 │ │ ├── chat.ts # 聊天 API (SSE) │ │ ├── memory.ts # 记忆 API │ │ ├── sessions.ts # 会话 API │ │ ├── users.ts # 用户 API │ │ ├── messages.ts # 消息 API │ │ ├── memorize.ts # 记忆摄入 API │ │ ├── admin.ts # 管理 API │ │ └── health.ts # 健康检查 API │ ├── store/ # 状态管理 │ │ └── app.ts # Zustand store (用户/会话/消息状态) │ ├── lib/ # 工具库 │ │ ├── utils.ts # 通用工具 (cn 类名合并等) │ │ └── clipboard.ts # 剪贴板操作 │ └── types/ # TypeScript 类型定义 │ └── index.ts # 全局类型 (User, Session, Message...) ├── config/ # settings.yaml ├── alembic/ # 数据库迁移 └── docs/ # 文档 + 蓝图

核心数据流 Data Flow

聊天流 — Chat Flow

用户消息

POST /chat

→

保存消息

Message → DB

→

构建上下文

3-layer context

→

调用 LLM

SSE streaming

→

保存回复

assistant msg

→

压缩检查

auto compact

记忆提取流 — Extraction Pipeline

对话消息

raw messages

→

边界检测

topic boundary

→

MemCell

原子记忆单元

→

Episode 提取

情节记忆

EventLog 提取

原子事实

Foresight 提取

前瞻预测

→

向量化

embedding

→

KnowledgeEntry

统一知识库

语义压缩流 — Semantic Compaction

Token 超阈值

≥ 64000 tokens

→

获取锁

FOR UPDATE

→

消息分段

20 msgs/segment

→

LLM 摘要

并行 summarize

→

创建摘要消息

compaction_summary

→

标记已压缩

is_compacted=true

数据模型 ER Diagram

User users
idUUID PK
external_idVARCHAR
nameVARCHAR
metadataJSONB
created_atTIMESTAMPTZ
Session sessions
idUUID PK
user_idUUID FK→users
statusENUM active|deleted
token_countINT
compaction_countINT
Message messages
idUUID PK
session_idUUID FK→sessions
roleENUM user|assistant|system
contentTEXT
token_countINT
message_typeENUM message|summary
is_compactedBOOL
extraction_statusENUM pending|extracted
MemCell memcells
idUUID PK
user_idVARCHAR
timestampTIMESTAMPTZ
summaryTEXT
original_dataJSONB
episodeTEXT
participantsARRAY
KnowledgeEntry knowledge_entries
idUUID PK
user_idVARCHAR
entry_typeENUM episode|event|foresight
titleTEXT
contentTEXT
embeddingVECTOR(1024)
memcell_idUUID FK→memcells
metadataJSONB
EvergreenMemory evergreen_memories
idUUID PK
user_idUUID FK→users
categoryENUM fact|preference|...
contentTEXT
sourceENUM manual|extract
confidenceFLOAT

实体关系

User 1 ──→ N Session 1 ──→ N Message
User 1 ──→ N EvergreenMemory
MemCell 1 ──→ N KnowledgeEntry
Message ──→ Message (parent_id 自引用，用于压缩摘要链接)

API 路由总览 REST API

方法路径说明模块
GET/health健康检查main
GET/v1/users用户列表users
POST/v1/users创建用户users
GET/v1/users/{id}获取用户users
DEL/v1/users/{id}删除用户及所有关联数据users
POST/v1/users/{id}/sessions创建会话sessions
GET/v1/users/{id}/sessions会话列表sessions
DEL/v1/sessions/{id}删除会话sessions
POST/v1/sessions/{id}/chatSSE 流式聊天chat
POST/v1/sessions/{id}/messages添加消息messages
GET/v1/sessions/{id}/messages消息列表messages
POST/v1/sessions/{id}/extract-memory手动提取记忆sessions
POST/v1/sessions/{id}/compact手动语义压缩sessions
GET/v1/tasks/{id}异步任务状态sessions
POST/v1/memories记忆摄入管道memorize
GET/v1/users/{id}/evergreen常青记忆列表memory
POST/v1/users/{id}/evergreen创建常青记忆memory
POST/v1/knowledge/search知识搜索memory
GET/v1/users/{id}/knowledge知识条目列表memory
POST/v1/context/build构建上下文memory
GET/v1/admin/tables数据库表列表admin
GET/v1/admin/tables/{name}表数据查看admin