内容
# OpenCompanion — 你的专属 AI 陪伴助手
[English](README_EN.md) | [简体中文](README.md)
<img width="3136" height="1344" alt="rmb20260806020137rfe" src="https://github.com/user-attachments/assets/8fc42ab1-c970-437f-b54a-ff025665e68b" />
一个开源的多平台 AI 陪伴聊天机器人：像朋友一样跟你聊天，记得你说过的话，偶尔主动找你搭话，也能记待办、设提醒。有性格、有情绪、有私密日记——既懂陪伴，也能干活。无论是男友 女友 闺蜜 都可胜任
一个真实的人格 绝不是AI能够代替的
> 💙 陪伴与能力从来不应该是对立面。
## 主要功能
- 💙 **角色扮演 & 情感陪伴** 有完整人设的 AI 伙伴，说话自然，有情绪、有性格，会撒娇也会傲娇。
- 🧠 **长期记忆** 内置长期情感记忆引擎：重要的事、你的喜好都会记下来，隔了很久没聊，它会"突然想起"跟你提。
- ✨ **主动式 Agent** 你很久没理它，它会自己来搭话；约定的事到点也会主动提醒、追催。
- 📔 **私密日记** 每天睡前它会把心里话写进只有自己看得见的日记和信里，慢慢消化。
- 🔧 **MCP 工具源** 可自由接入工具源：用户档案、事件记录、长期记忆……
- 🧩 **插件系统** 标准插件机制（manifest + 独立 MCP 服务 + 事件钩子），当前内置主动问候引擎插件。
- 🔄 **多平台适配器** 平台通讯抽象层，一套机器人核心可对接任意平台适配器；当前内置：**微信（iLink）**。
- 🛡️ **数据全在本地** 对话和记忆只存在你自己的电脑上；`/清除记忆` 二次确认后彻底删除所有记忆。
🆓 **免费 & 开源** 全项目开源，模型密钥用自己的。
所有工具均可自己选择接入还是不接入 可以最小化运行 即所有MCP都不加载
## 特色功能
- ✉️**写信** 每天晚上会自动写一封信给你 你可以登录后台查看日记内容和信内容 同时你也可以给她写信(感谢OmbreBrain提供该功能)
- 📓**日记** 每天定时记录今日生活
- ❤️**主动提醒功能** 当你需要她来提醒你做某事时 到时间自动提 醒你
- ⚙️**插件 MCP 多平台适配器功能** 支持自己开发插件 文档清晰 代码结构明了
## 快速浏览
##### 自动提醒&傲娇性格&后台写信&基于OmbreBrain开源项目的记忆系统
<img width="398" height="525" alt="屏幕截图 2026-08-04 035927" src="https://github.com/user-attachments/assets/188dd488-57b7-4911-9a4f-1b215d42a444" />
<img width="419" height="539" alt="屏幕截图 2026-08-04 035827" src="https://github.com/user-attachments/assets/3f89b316-150b-4d06-99b8-af832184a235" />
<img width="425" height="627" alt="屏幕截图 2026-08-04 040544" src="https://github.com/user-attachments/assets/d103727a-374a-4da0-93c8-e0324c5c237a" />
<img width="599" height="519" alt="屏幕截图 2026-08-06 021626" src="https://github.com/user-attachments/assets/4ba5f6ca-b038-43e4-a57c-1e0fe332b938" />
## 快速开始
演示视频及安装视频: https://www.bilibili.com/video/BV1BmM16jEGD
> 需要：Python 3 环境、一个 OpenAI 兼容的 API 密钥和服务器地址
> 默认使用微信官方ilink协议的机器人
>
> 注意 如果您要使用OmbreBrain的向量计算功能 需自备向量API HE
```powershell
# 1. 安装依赖
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
# 2. 填配置（config.ini 里写你的 API 密钥和模型）
# [llmapi] api_key = sk-xxx
# 3. 启动，按提示扫码登录
python main.py
```
启动后，在微信里跟它正常聊天即可。
### 网页控制台
> 在浏览器里管理机器人：启停/自动重启/实时日志（含微信扫码登录）、
> config.ini 与 OmbreBrain 配置编辑、数据管理、端口检测。
```bash
python webconsole.py # 打开 http://127.0.0.1:9000
```
> 控制台是 Vue 3 + Vite 工程（源码在 `botapp/webconsole/webui/`），构建产物不入库。
> 从源码运行时首次需先构建：`cd botapp/webconsole/webui && npm install && npm run build`。
> Docker 部署无需手动构建（镜像构建时自动编译前端）。
Docker 部署时容器主进程即是网页控制台，构建启动后直接访问 http://服务器IP:9000。
### Docker 部署
> 适合 Linux 服务器 / 长期稳定运行。数据与微信登录态全部持久化，扫码一次后重启免扫码。
```bash
docker compose up -d --build # 构建并启动
# 浏览器打开 http://服务器IP:9000，在网页控制台启动机器人并扫码登录
```
详细说明（数据目录/端口/免扫码机制/常见问题）见 [docs/Docker部署指南.md](docs/Docker部署指南.md)。
## 架构一览
| 系统 | 说明 |
| ------------- | ---------------------------------------------------------------------------------------------------- |
| 🤖 平台层 | `PlatformAdapter` 统一接口（收发/输入态/用户解析），注册表按配置创建实例；新增平台只需实现接口并注册 |
| 🧩 插件系统 | `plugins/` 下带 `manifest.json` 的插件：可挂独立 MCP 服务、后台调度器、消息钩子 |
| 🔧 MCP 工具源 | `config.ini [mcpsources]` 任意增删工具源（stdio/HTTP），命名空间隔离 |
| 🧠 记忆引擎 | 独立 MCP 服务，`breath/hold/trace/dream/plan/letter_*` 全套记忆工具 |
| 📦 数据层 | 对话存档 / 用户档案 / 事件库 / 记忆库 各自独立，支持按用户精确清除 |
## 常用指令
| 指令 | 作用 |
| --------------- | ---------------------------------------------------------- |
| `/help` | 查看全部可用指令 |
| `/清除记忆` | 彻底清除它记住的所有关于你的事（需二次确认） |
| `/缩减上下文` | 把旧对话总结压缩，腾出上下文 不用担心丢失数据 自带档案工具 |
| `/重置` | 撤回它上一轮说的话 |
| `/清空聊天记录` | 清空平台侧聊天记录 |
## 定制它
- **性格人设**：改 `prompt.txt`（热加载，改完不用重启）
- **行为习惯**：改 `prompt_extra.txt`（记忆习惯、消息格式等）
- **工具源**：`config.ini` 里加一行即可接入新的 MCP 源
- **插件**：按 `plugins/` 规范写一个带 `manifest.json` 的插件目录
- **平台**：实现 `PlatformAdapter` 接口并在注册表注册，即可换平台
## 数据与隐私
- 对话存档、记忆数据全部存在运行目录本地，不经过任何第三方服务器
- 记忆引擎数据在 `MCP/OB/buckets/`，可随时重置（`scripts/reset_ombre_memory.py`）
- 彻底清空请对机器人说 `/清除记忆`
## 写给用户
*真实的人格，从来不是算法能拼凑出来的产物。*
*它藏在十几年的成长轨迹里，藏在脱口而出的口头禅、不合时宜的笨拙、深夜没说出口的心事里；它有拧巴的软肋，有偏执的喜好，有想起某件事就泛红的眼眶，有见到某个人就加速的心跳。这些带着温度与瑕疵的细节，是代码永远写不出来的生命重量。*
**别把情绪错付虚拟，多去触碰现实里鲜活的人与温度**
MCP 市场