English | 中文
DeepRolePlay 是一个基于原生智能体的深度角色扮演系统，通过自动化记忆管理彻底解决传统大语言模型的角色遗忘问题，记忆闪回处理 + 情景更新管理 + 主对话模型，让 AI 告别角色遗忘，实现真正连贯的角色扮演。
- 🤖 AI 突然忘记角色设定：明明是法师却拿起了剑
- 📖 剧情前后不一致：昨天的重要情节今天完全不记得
- 💸 Token 消耗巨大：长对话费用飞涨，体验中断
- 📚 LLM 背景知识不足：对特定小说、电影或自定义世界观缺乏了解
- 🧠 永不遗忘：自动化记忆管理系统，角色设定永久保持
- 🔄 剧情连贯：智能情景更新，千万轮对话依然逻辑清晰
- 💰 成本可控：情景压缩技术，长对话费用降低 80%
- 📚 智能联网：集成 Wikipedia 百科，自动补全角色背景和故事设定
- 📄 外部知识挂载：支持 txt 文档挂载，解决 LLM 对特定作品或自定义世界观知识不足的问题
- 🗂️ 结构化管理：JSON表格系统管理世界观、角色、道具等信息，支持动态增删改查
- ⚡ 即插即用：5分钟集成，SillyTavern 等平台直接使用
- 🚀 超高速响应：支持任何OpenAI style的模型，除了首次构建情景，正常对话时仅多10秒
-
📦 解压软件包
- 下载发布的软件包并解压到非中文路径下
- 解压后文件夹包含：
config.yaml配置文件 +DeepRolePlay.exe主程序
-
⚙️ 修改配置文件
编辑
config.yaml文件：配置文件已包含详细的初学者指南，主要需要修改以下配置：
# API代理配置 - 转发目标（你的主要聊天LLM） proxy: target_url: "https://api.your-provider.com/v1" # 修改为你的API地址 api_key: "Your-Main-LLM-API-key" # 修改为你的API密钥 # Agent配置 - 后台处理模型 agent: model: "deepseek-chat" # 任何OpenAI格式模型 base_url: "https://api.deepseek.com/v1" # API地址 api_key: "Your-Agent-API-Key" # 修改为你的API密钥 workflow_mode: "fast" # 工作流模式: fast=快速经济模式, drp=灵活但昂贵模式 external_knowledge_path: "knowledge/custom.txt" # 外部知识文档路径(可选)
-
🚀 启动程序
- 双击
DeepRolePlay.exe启动 - 看到终端里项目正常运行即可
- 🌟本项目会检查端口是否被占用。如果被占用会自动+1.所以最终真正的端口需要用户检查终端输出
- 双击
-
🔗 配置角色扮演前端
- 在 SillyTavern、OpenWebUI 等平台中
- 将
base_url改为：http://localhost:6666/v1 - 重要：关闭历史记录限制，务必发送全部历史记录给代理！（不用担心token爆炸，max_history_length会控制）
-
🎭 开始角色扮演
- 立即享受无遗忘的角色扮演体验！
- 智能场景管理：切换预设和角色卡时，系统会自动清理旧场景，无需手动操作
- 预设切换建议：更换了预设建议先执行一次
$reset来定位AI的真实回复索引，如果长期使用某预设建议手动设定last_ai_messages_index为$reset返回值。
DeepRolePlay 支持在聊天界面中直接输入命令来管理系统状态和数据，无需进入特殊模式。
| 命令 | 功能 | 说明 |
|---|---|---|
$drp 或 $help |
显示帮助信息 | 查看所有可用命令和使用说明 |
$show |
显示数据表格 | 查看当前所有内存表格（世界观、角色、道具等） |
$rm |
清空数据 | 重置所有内存表格和场景文件 |
$reset |
智能重置 | 智能分析对话历史，自动设置合适的AI消息索引来适配预设 |
-
查看帮助：在任何聊天界面中发送
$drp或$help用户: $drp 系统: 📚 DeepRolePlay 命令帮助 当前版本支持直接在对话中输入命令，无需进入特殊模式。 🔧 可用命令： • $help 或 $drp - 显示此帮助信息 • $reset - 智能适配AI消息索引，自动判断真实的角色扮演回复 • $rm - 清空所有表格数据和scenario文件 • $show - 显示当前所有表格数据 -
查看数据表格：发送
$show查看当前存储的所有角色信息用户: $show 系统: Current Memory Tables: [世界观表] (2 rows) [角色表] (1 rows) [道具表] (0 rows) ... -
清空角色数据：发送
$rm完全重置角色扮演状态用户: $rm 系统: Memory tables and scenarios directory have been reset successfully. -
智能重置：发送
$reset智能适配预设切换用户: $reset 系统: ✅ 内存中的 last_ai_messages_index 已成功更新为: 2 🔧 适配完成！系统已根据当前对话历史智能判断并设置了合适的AI消息索引。
DeepRolePlay 集成了 ComfyUI 后端，支持在角色扮演过程中自动生成符合场景的图片：
- 🖼️ 智能图片生成：基于对话内容和场景描述自动生成相关图片
- 🔧 自定义工作流：支持导入自定义的 ComfyUI 工作流 JSON 文件
- ⚡ 异步处理：图片生成与对话并行处理，不影响响应速度
- 📱 前端优化：自动调整图片尺寸，优化传输效率
配置示例：
comfyui:
enabled: true # 启用图片生成功能
comfy_url: "http://127.0.0.1:8188" # ComfyUI服务器地址
api_key: "YOUR_COMFYUI_API_KEY_HERE" # ComfyUI API密钥
workflow_path: "3rd/comfyui/wai.json" # 工作流配置文件路径传统单一模型的问题：角色遗忘 → 剧情断裂 → 体验崩坏
DeepRolePlay 的工作流解决方案：
- 🔍 记忆闪回处理：智能检索历史对话和外部知识，基于原生智能体自动化执行
- 📝 情景更新管理：实时维护角色状态和剧情连贯性，支持表格化数据管理
- 🗂️ 表格管理系统：结构化存储世界观、角色、道具等信息，支持动态增删改查
- 🎭 主对话模型：基于完整上下文生成角色回应
用户请求 -> HTTP代理服务
|
v
[检查是否为控制台命令]
/ \
是 / \ 否
v v
后台控制台处理 触发工作流执行
| |
命令解析 +------+------+
($drp/$show/ | |
$rm/$exit) v v
| 记忆闪回 情景更新
执行相应操作 处理节点 处理节点
- 显示表格 | |
- 重置数据 | 表格管理
- 模式切换 | (增删改查)
| | |
v +------+------+
返回命令结果 |
v
注入更新的情景
|
v
转发至目标LLM
|
v
返回增强响应
- Python 3.12
- UV 虚拟环境管理器（推荐）
git clone https://github.com/yourusername/deepRolePlay.git
cd deepRolePlay
uv venv --python 3.12
uv pip install -r requirements.txtuv run python main.py将你的 AI 应用（SillyTavern、OpenWebUI 等）的 API 端点改为：
http://localhost:6666/v1
🌟本项目会检查端口是否被占用。如果被占用会自动+1.所以最终真正的端口需要用户检查终端输出
系统将自动：
- 拦截对话请求
- 执行工作流
- 更新情景状态
- 将增强的上下文注入请求
- 返回更准确的角色扮演响应
使用 PyInstaller 打包为可执行文件：
pyinstaller --name DeepRolePlay --onefile --clean --console \
--add-data "src;src" --add-data "utils;utils" --add-data "config;config" \
--add-data "3rd;3rd" \
--hidden-import=locale --hidden-import=codecs \
main.py打包后在 dist/ 目录下会生成 DeepRolePlay.exe，连同配置文件一起发布给用户。
本项目采用标准 OpenAI API 格式，无论是后台处理模型（Agent）还是转发目标模型（Proxy）都支持任何 OpenAI Style 格式的模型：
- 🌟 OpenAI Style：所有支持OpenAI Style 的api
- 🔥 OpenRouter：聚合多家服务商，模型选择丰富
- 💻 本地 Ollama：完全私有化部署，数据安全
- 🚀 DeepSeek：高质量对话，成本低廉
- ⚡ Claude：通过 OpenRouter 或其他兼容服务使用
- 🧠 Gemini：通过兼容接口使用
- 🔧 自建模型：任何遵循 OpenAI API 格式的自部署模型
- Agent模型：用于后台记忆处理和情景更新，推荐使用成本较低的模型
- Proxy模型：用户实际对话的目标模型，可选择高质量对话模型
- 双重配置：两者可使用不同服务商，灵活优化成本和效果
本项目的设计理念受到以下研究的启发：
- Building effective agents - Anthropic
- LangGraph Documentation - LangChain
- st-memory-enhancement - muyoou
MIT License
