fumingyang2004 / Tulpa

# Tulpa
**把 QQ / 微信资料接入几乎所有的桌面版 Agent，也让它在 QQ 里成为群友。**
Linux 终端版 · 下载 · 快速开始 · Agent 配置教程 · 使用场景 · 完整文档
Tulpa 在本机整理聊天、图片和文件，让 Agent 按你授权的范围查资料、追溯消息，或带着自定义人格参与 QQ 群聊。已有 Agent 选 MCP 轻量版；想直接在 Tulpa 里提问，选完整版。
**桌面发行版：Windows 10 / 11 x64；Linux：x86_64 / ARM64 终端源码版。** 微信支持读取、回复草稿与复制，不能发送。QQ 持续群聊需要独立运行的 OneBot 服务、相应授权，以及持续执行的外部 Agent。
## Linux 终端版
在 Linux 安装 Python 3.13 或 `uv` 后，进入源码目录运行：
 [code] 
首次自动安装依赖、启动后台并打开 TUI；退出界面后后台继续运行。
提供 CLI / TUI、原有业务 API、MCP、Linux 原生读取器、可选 OCR / 语音 / Office 组件、
用户级 systemd 服务，以及 SL 本地托管和 Docker 托管。没有桌面时可用浏览器中的 noVNC 扫码。
多实例各有独立端口、账号数据、SL 容器和 MCP 授权；新增私聊、图片导入、SL 扩展工具及授权编辑。
安装与限制见 Linux 教程、使用说明；
开发分工见 模型贡献记录。下方桌面下载和启动教程继续适用于 Windows。
## 使用场景
下面是可以交给 Agent 的请求示例，实际能力取决于资料、授权、模型和客户端。
### 让小鲸鱼来水群
> 先列出可用人格和允许的 QQ 群，核对“我的测试群”后，用小鲸鱼持续聊天，直到我停止。接得上话再说，不必每条都回复。
随包提供小鲸鱼（`little_whale`）、小鲸鱼2号（`little_whale_v2`）和龙娘（`dragon_girl`，测试版），也能用 Markdown 写自己的角色。支持按语境接话、原生 @ 与引用；授权后可看图、发送和收藏表情、给消息贴表情回应，保留理解笔记供后续会话选用。
持续聊天会在当前已授权的机器人账号和群里积累群友表达与黑话，潜水时也能学习；同账号同群重开可接续积累。人物卡与学习参考分开，模型可以选择本轮不用。聊天节奏 · 实时学习
人格卡只改变表达，不会替换底层模型；发言和表情使用由 Agent 决定。详见 人格教程与表情链路。
视频链接：点击这里查看哔哩哔哩视频
### 找回聊过的资料和文件
> 帮我找我的群里的一些我需要的附件，核对时间，并标出消息来源。
按关键词、人物、会话和日期检索，再展开上下文。图片、语音和文件按需读取；轻量版可经 OneBot 下载 QQ 群原文件，交给同机 Agent 自己的文件工具阅读。
### 把消息整理成有出处的总结
> 总结项目群这周确定的分工和待确认事项，把每项对应的原话列出来。
从消息和文件中整理结论，保留可回查的来源。完整版还提供回复草稿、会话记忆、关注卡和持续调查工作区；完整能力见功能清单。
## 为什么用 Tulpa
- **复用熟悉的 Agent**：Tulpa 负责资料读取、检索和授权，外部 Agent 负责理解与任务执行；只用 MCP 无需在 Tulpa 另配模型 API Key。
- **范围由你决定**：按平台、会话、日期开放资料，写操作另行授权，每个客户端的连接可单独撤销。
- **查得到，也能回头核对**：从结论展开上下文、查看原文，按需取图片和文件，不必反复复制聊天。
已接入以下客户端：
 Codex ·
 Claude Code ·
 DeepSeek Harness ·
 Antigravity ·
 WorkBuddy
 客户端实测范围 
- **Codex / DeepSeek Harness**：已验证聊天查询、图片和文件读取，以及授权测试群发言、修改群名并恢复。
- **Claude Code**：已接入并由用户在本机确认功能正常，使用原生 HTTP MCP 与 Bearer Token。
- **Antigravity**：已验证消息查询和图片理解；验收仅开放只读权限，尚未实测持续群聊、发送与群管理。
- **WorkBuddy**：已接入并由用户确认跑通；调用记录覆盖消息、图片、文件、群资料及人格发现。
客户端的识图、工具审批与持续运行机制不同。详见 Agent 教程和验证记录。
## 下载
| 版本 | 适合你，如果你想… | 下载 |
| --- | --- | --- |
| **MCP 轻量版** | 使用已有 Agent 查资料或参与 QQ 群聊 | 0.5.6 ZIP |
| **Linux 终端版** | Linux x86_64 / ARM64，CLI/TUI、MCP 及可选内置模型 | 0.5.6 tar.gz |
| **完整版（上一版）** | 在 Tulpa 内提问，使用回复、记忆和工作区；也能接外部 Agent | 0.5.5 ZIP |
**0.5.6 本次发布 MCP 轻量版与 Linux 终端版，Windows 完整版维持 0.5.5。** Windows 发行包自带 Python；完整版内置 Harness、本地 OCR / 语音 / Office 解析与固定 WebView2，轻量版使用系统 WebView2 Evergreen Runtime，语音模型按需安装。版本区别 · 最新发布 · 0.5.6 更新说明
需要 **.NET Framework 4.8**。下载 ZIP 后完整解压到可写目录，打开 `Tulpa/Tulpa.exe`；不要从压缩包直接运行。**`Source code` 不是安装包，两版不要混装。** QQ / 微信客户端、模型服务及可选 OneBot 服务需自行准备。
**老用户升级：** 按保留数据升级教程检查、备份并更新原目录，无需重新导入。自改的同名随包人格先另存；升级后仍打开原目录 EXE，并重连 MCP。
## 快速开始
### SnowLuma 自动配置
自行下载并解压 SnowLuma v1.14.22 Windows x64 完整版，在 Tulpa 输入文件夹路径，勾选授权，点击 **载入并配置**。文件检查和配置一次完成，已有连接自动检测并导入；新目录自动初始化、选择空闲端口、配置 HTTP/WS 并核对 QQ。多 QQ 时选择目标即可，无需终端、手填 Token 或设置管理密码。
已有可用节点会自动检测并导入，保留原配置。Tulpa 不下载、复制或附带 SnowLuma，不扩大 MCP 授权。操作与恢复 · 验证范围
### 我要 QQ 水群
**无需先导入整库历史。** 这条路径直接接收 OneBot 实时事件。
1. 启动 QQ 和 Tulpa；载入自行下载的 SnowLuma 文件夹并同意自动配置，或导入已有 OneBot 连接。持续群聊需要 **HTTP + 正向 WebSocket**。连接教程
2. 在 **连接外部 Agent**（或 **外部