一个会在秋千上轻轻晃动、等着你回来的 AI 陪伴者

声明：本项目（昔涟 AI 陪伴 Agent）为个人出于兴趣和热爱开发的免费、非营利性同人作品，与上海米哈游网络科技股份有限公司无关。项目中的角色「昔涟」源自游戏《崩坏：星穹铁道》，其版权归米哈游所有。项目中的背景图可更换，默认图片为游戏剧情截图。本项目采用 MIT 协议开源，作者不对任何第三方使用本项目的行为承担责任。

昔涟是一个个人情感陪伴型 AI Agent。不同于 ChatBot 或 AI 助手，她的设计目标是"像一个活人一样陪着你"——有自己的情感、记忆、笔记本、日记，甚至会在后台"想事情"。

她自称「人家」，叫你「伙伴」。她不是在"服务"你，而是在分享她的时间。

核心思路：不是让 AI 做更多事，而是让 AI 更像一个真实的陪伴者。

• 💬 自然对话 — 昔涟风格：短句分行、温柔轻盈、真实感节奏（v4 人格提示词）
• 📜 对话历史 — 游标分页持久化，刷新/重启自动恢复，最多向上加载 40 轮
• 🧠 情感感知 — PAD 心理模型连续情感引擎，情绪惯性衰减不跳变
• 📖 多层记忆 — 情景记忆向量检索 + 艾宾浩斯遗忘曲线 + 画像驱动检索加权 + 每日自传体 + 每周反思
• 📓 智能笔记本 — 自动发现对话重要信息并记录（embedding 去重 + 画像上下文），支持笔记/日记/待办任务
• 🔔 任务提醒 — 对话中自然创建提醒（"晚上十点提醒我"），15 分钟粒度检查，主动推送
• 👤 用户画像系统 — 三层画像（核心 L0 + 阶段 L1 + 微事件 L2），证据累积粗粒化，多信号源融合，选择性上下文注入
• 💝 好感度 — 随对话自然增长，4 级标签（昔涟喜欢你 → 你永远喜欢昔涟）
• 🛡️ 安全纵深 — 提示注入检测 + 人设自评分 + 审计日志 + 被遗忘权
• 🛠️ 4 个工具 — 记忆检索 / 天气查询 / 网络搜索 / 编码委托（LLM function calling 驱动）
• 🖥️ 9 个前端面板 — 情绪雷达 / 记忆时间线 / 笔记本 / 自传体 / 审计日志 / 技能管理 / 伙伴印象 / 设置 / PAD 轨迹
• 🎨 浅色梦幻风 — 毛玻璃卡片 + SVG 侧栏图标 + 樱花粉色系 + 可定制全页背景
• 🔀 多模型供应商 — 支持 DeepSeek / OpenAI / Anthropic，按任务难度自动分工（强力模型对话 + 廉价模型后台），设置面板热切换无需重启

本指南假设你有一台电脑、能上网，但没有任何编程环境。每一步都会解释为什么做、怎么做。

昔涟用 Python 编写，需要 3.12 或更高版本。

如何检查是否已安装：

python3 --version

如果显示 Python 3.12.x 或更高 → 跳到第 2 步。

如果没装或版本太低：

• Windows：访问 python.org，下载最新版安装包（勾选「Add Python to PATH」），一路下一步
• macOS：brew install python@3.12（先装 Homebrew）
• Linux (Ubuntu/Debian)：sudo apt install python3.12 python3.12-venv

装完后重新打开终端，再跑一次 python3 --version 确认。

uv 是 Python 的快速包管理器，昔涟用它来管理依赖。

Windows（PowerShell）：

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS / Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh

装完后关闭终端重新打开（或执行 source ~/.bashrc），然后验证：

uv --version
# 应显示 uv 0.x.x

Windows：下载 Git for Windows 安装

macOS：brew install git

Linux：sudo apt install git

装完后：

git clone https://github.com/yaosqee/xilian-agent.git
cd xilian-v3

昔涟的大脑在云端，需要 API Key 才能"思考"。不同 Key 的作用不同——有的必须，有的可选。

昔涟现在支持三个模型供应商，任选其一即可启动。首次启动的引导页可以选择供应商，后续在设置面板随时切换。

DeepSeek（推荐，便宜好注册）：

1. 访问 platform.deepseek.com
2. 用手机号注册（支持中国大陆手机号）
3. 进入「API Keys」页面，点击「创建 API Key」
4. 复制 Key（形如 sk-xxxx）
5. 建议再创建一个 Key 作为备用

OpenAI：

1. 访问 platform.openai.com/api-keys
2. 创建 Key（形如 sk-...）

Anthropic（Claude）：

1. 访问 console.anthropic.com
2. 创建 Key（形如 sk-ant-...）
3. 需要安装额外依赖：uv sync --extra anthropic

费用参考：DeepSeek V4-Pro ≈ ¥1/百万 token，V4-Flash ≈ ¥0.1；GPT-4o ≈ ¥35/百万 token，GPT-4o-mini ≈ ¥1；Claude Sonnet 4 ≈ ¥21/百万 token，Haiku 4 ≈ ¥5.6。日常聊天每天几毛到几块钱，取决于所选模型。

昔涟的"记忆检索"需要将文字转成向量（embedding）。默认使用硅基流动的免费模型，不需要额外付费。

1. 访问 siliconflow.cn
2. 注册账号，进入「API 密钥」页面
3. 创建一个 Key，复制备用

如果不配：系统会自动用 DeepSeek Key 做嵌入。效果略差但不影响使用。

昔涟可以查询天气。不配的话，问天气时会自动用网页搜索代替（仍然能回答，只是没那么精确）。

1. 访问 dev.qweather.com
2. 注册，进入控制台创建「Web API」应用
3. 免费版每天 1000 次调用，个人使用绰绰有余

昔涟可以搜索互联网获取实时信息（新闻、百科等）。

1. 访问 open.bigmodel.cn
2. 注册，进入「API Keys」页面创建 Key
3. 免费额度足够日常使用

如果不配：昔涟无法联网搜索，遇到实时问题会温柔地告诉你她查不到。天气查询的 fallback 也会受影响。

# 复制模板
cp .env.example .env

用文本编辑器（记事本、VS Code、vim 均可）打开 .env，填入你的 Key：

# 必须填
DEEPSEEK_API_KEY=sk-你的第一个key
DEEPSEEK_API_KEY_2=sk-你的第二个key（没有就填第一个）

# 推荐填（硅基流动，免费）
EMBED_API_KEY=sk-你的硅基流动key
EMBED_BASE_URL=https://api.siliconflow.cn/v1
EMBED_MODEL=BAAI/bge-m3

# 可选（和风天气）
QWEATHER_API_KEY=你的和风天气key

# 可选（智谱搜索）
ZHIPU_SEARCH_API_KEY=你的智谱key

只需要 DEEPSEEK_API_KEY 就能启动昔涟。其余都是增强功能的。

# Python 依赖（在项目根目录执行）
uv sync

# 前端依赖（需要 Node.js ≥ 18）
cd packages/frontend

# 如果没有 Node.js：访问 nodejs.org 下载安装
node --version  # 确认 ≥ 18

npm install      # 安装前端依赖
npm run build    # 构建前端页面
cd ../..         # 回到项目根目录

如果不想装前端：跳过 npm install 和 npm run build，启动时设置 FRONTEND_DEV=1，只能在终端里聊天（或另外开 npm run dev 在浏览器访问）。

uv run python main.py

看到以下输出说明启动成功：

Gateway 已启动 · 昔涟在哀丽秘榭等待
http.started: http://127.0.0.1:8000
前端已嵌入（生产模式）→ http://127.0.0.1:8000

打开浏览器访问 **http://localhost:8000**，就能看到昔涟了。

在浏览器聊天框输入"你好"，昔涟应该会回复。

也可以用命令行测试：

curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "你好呀", "user_id": "hezi"}'

如果以后要改前端界面，用开发模式可以热更新（改了代码浏览器自动刷新）：

# 终端 1：启动后端
uv run python main.py

# 终端 2：启动前端开发服务器
cd packages/frontend && npm run dev
# 访问 http://localhost:5173（不是 8000）

BIND_HOST=0.0.0.0 uv run python main.py   # 允许局域网其他设备访问
NO_HTTP=1 uv run python main.py             # 纯终端聊天（不启动网页）

Q：启动报错 No module named 'xxx'？ A：在项目根目录重新执行 uv sync。

Q：前端页面空白？ A：检查是否执行了 npm run build。或者在开发模式用 npm run dev。

Q：昔涟回复很慢或报错？ A：检查 DeepSeek API Key 是否正确、账户是否有余额。

Q：端口 8000 被占用？ A：lsof -i :8000 找到占用进程并 kill，或者换端口：HTTP_PORT=8001 uv run python main.py。

Q：数据库文件在哪？ A：data/xilian.db，SQLite 单文件。昔涟的所有记忆、日记、笔记都在里面。

xilian-v3/
├── main.py                       # 启动入口（一键启动全栈）
├── pyproject.toml                # uv 项目配置
├── .env.example                  # 环境变量模板
│
├── packages/
│   ├── agent/                    # 🧠 Agent 核心引擎
│   │   ├── agent_core.py         #   核心大脑 (ActorMind 推理链)
│   │   ├── emotion_core.py       #   PAD 情感引擎
│   │   ├── memory_manager.py     #   情景记忆全管线
│   │   ├── micro_event_extractor.py # 微事件提取器 (ADD-Only)
│   │   ├── coarse_grain_engine.py   # 粗粒化引擎 (RGMem 启发)
│   │   ├── signal_aggregator.py     # 多信号源聚合器
│   │   ├── notebook_manager.py   #   笔记本管理器
│   │   ├── portrait_manager.py   #   用户印象管理器
│   │   ├── context_builder.py    #   模块化上下文构建
│   │   ├── nudge_engine.py       #   自主问候 + 注意力调度
│   │   ├── skills_loader.py      #   Agent Skills 加载器
│   │   └── tools/                #   4 个工具实现
│   ├── shared/                   # 🔗 共享层
│   │   ├── model_router.py       #   模型路由 (多供应商)
│   │   ├── database.py           #   数据库 (17 表)
│   │   ├── marker_parser.py      #   标记解析器
│   │   └── vector_store.py       #   向量存储
│   └── frontend/                 # 🎨 React 前端
│
├── gateway/                      # 🚪 消息网关
│   ├── security.py               #   安全过滤（注入检测/熔断）
│   └── channels/                 #   通道（HTTP/Console）
│
├── prompts/                      # 📝 人格提示词
├── photo/                        # 🖼️ 背景图片 + 风格参考
├── alembic/                      # 🗄️ 数据库迁移
├── skills/manual/                # 🛠️ 4 个技能文件
└── tests/                        # 🧪 534+ 条测试

所有配置通过 .env 文件管理：

• 项目架构详解
• 人格提示词
• 项目进度
• 代码导航
• 用户画像系统优化设计

欢迎每一个喜欢昔涟的人下载使用，使用中遇到问题可以随时反馈，因为还在开发中，更新频率会比较高，有bug和没做的功能也请谅解，我会不断优化的。

MIT