# soulsync-cpp

**Repository Path**: lotusisatk/soulsync-cpp

## Basic Information

- **Project Name**: soulsync-cpp
- **Description**: SoulSync Go Project - AI Team Collaboration Platform
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-12
- **Last Updated**: 2026-05-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SoulSync

**SoulSync** 是一个开源的 AI Agent 框架，解决了**模型切换失忆**问题——在切换 AI 模型时丢失所有对话上下文。

## 🎯 核心价值

| 问题 | Hermes/OpenClaw | SoulSync |
|------|----------------|---------|
| 模型切换 = 失忆 | ❌ | ✅ 内置同步 |
| 多设备会话同步 | 手动 | ✅ 自动同步 |
| 长期记忆 + 快速查找 | 有限 | ✅ FTS5 索引搜索 |
| 部署配置复杂度 | 复杂 | ✅ Web UI 一键管理 |
| 国内渠道支持 | 有限 | ✅ 微信/钉钉/飞书/企微/QQ/支付宝 |
| 海外渠道支持 | 一般 | ✅ Telegram/Discord/Slack/WhatsApp 等 |
| Skill 扩展 | ✅ | ✅ 兼容 Hermes/OpenClaw + 迁移工具 |

## ✨ 核心特性

- **内置同步协议** - 自研轻量级协议，无需 git/S3，支持 P2P 和中继模式
  - 开源版：局域网 P2P 直连同步
  - 闭源版：中继服务器突破 NAT
  - 增量同步 + 版本向量冲突处理
- **长期记忆 + 快速查找** - FTS5 全文索引，毫秒级搜索所有历史会话
- **模型无关** - 支持任何 LLM 提供商（OpenAI、Anthropic、Ollama、MiniMax 等）
  - 只需配置一次 API Key，选择渠道即可使用
  - 单模型/多模型自由切换
  - 支持自动切换（如主模型失败自动切换到备用）
- **内置 Skills** - 继承 Hermes/OpenClaw 所有基础技能，开箱即用
  - 文件/终端/代码执行
  - Web 搜索/浏览器
  - Git/数据库/MLOps
  - 日程/邮件/笔记
  - 一键从 Hermes/OpenClaw 导入
- **多设备支持** - 跨机器无缝同步
- **Web UI 管理** - 配置管理、服务启停、命令执行
  - 所有配置集中管理，图形化操作
  - 多渠道通讯统一接入（国内外全覆盖）
  - 安全权限控制（RBAC）
  - 中英双语界面
- **开放核心** - 核心框架开源，私有 skills 和 IM 渠道保持私密

## 🏗️ 架构设计

### 存储层

```
SoulSync Data/
├── sessions/           # 会话数据
│   └── {session_id}/
│       └── messages.json
├── memory/             # 长期记忆
│   └── {date}.md
├── index/              # FTS5 全文索引
│   └── soulsync.db
├── skills/             # Skills 配置
│   └── {skill}/
│       └── SKILL.md
└── config/             # 本地配置

### 安全与权限（RBAC）

```
角色体系：
├── 管理员 (Admin)
│   └── 全部权限
├── 开发者 (Developer)
│   └── 代码执行、文件操作、Web
├── 普通用户 (User)
│   └── 会话、基础技能
└── 只读 (ReadOnly)
    └── 会话查看

权限控制：
- API Key 加密存储
- 敏感操作需确认
- 操作日志审计

**审计模块：**

| 审计类型 | 记录内容 | 存储 |
|---------|---------|------|
| **操作审计** | 用户、时间、操作类型、目标、结果 | `audit/operations.log` |
| **会话审计** | 会话创建/切换/关闭、模型切换、消息统计 | `audit/sessions.log` |
| **权限审计** | 登录/登出、权限变更、API Key 访问 | `audit/auth.log` |
| **数据访问** | 文件读取/修改、敏感数据访问 | `audit/data_access.log` |
| **系统审计** | 服务启停、配置变更、技能安装 | `audit/system.log` |

**审计事件格式：**
```json
{
  "timestamp": "2026-04-28T22:00:00Z",
  "user": "admin@soulsync",
  "action": "session.switch_model",
  "target": "session_id=abc123",
  "result": "success",
  "ip": "192.168.1.100"
}
```

**合规保留：**
- 默认保留 90 天
- 支持导出为 JSON/CSV
- 敏感操作二次确认
```

### 同步机制（内置协议）

```
SoulSync Sync Protocol
├── P2P 模式（开源）
│   ├── TCP/WebSocket 直连
│   ├── 局域网发现 (mDNS/Bonjour)
│   └── 增量同步 + 断点续传
│
├── Relay 模式（闭源可选）
│   ├── 中继服务器突破 NAT
│   └── 端到端加密
│
└── 存储
    ├── SQLite + FTS5 索引
    ├── 版本向量（冲突处理）
    └── AES-256-GCM 加密
```

**跨设备同步流程：**
```
Device A ──发现──▶ Device B
                        │
                   增量同步
                        │
                   版本向量比对
                        │
                   冲突解决（Last-Write-Wins）
                        │
                   双方一致
```

**同步模式对比：**

| 模式 | 需要外服 | NAT 穿透 | 适用场景 |
|------|---------|---------|----------|
| P2P (开源) | ❌ | ❌ | 同一局域网 |
| Relay (闭源) | ✅ | ✅ | 跨网络 |

### 四层记忆架构（Everything 理念）

| 层级 | 类型 | 特点 | 应用场景 |
|------|------|------|---------|
| **L1 短时** | in-memory | 最快，进程重启丢失 | 当前会话上下文 |
| **L2 向量** | FTS5 + Everything 理念 | 3 层本地索引，<1ms 响应 | 知识检索增强（RAG） |
| **L3 持久** | SQLite | 持久化，跨会话 | 重要信息存储，用户画像 |
| **L4 知识库** | Markdown | 结构化文档 | 规则/知识文档，技能定义 |

**Everything 3 层索引：**

| 索引 | 数据源 | 搜索方式 | 最大结果 |
|------|--------|---------|---------|
| 🧠 L1 记忆档案 | `soulsync/memory/*.md` | 全文搜索 | 15 |
| 💻 L2 文件索引 | `soulsync/file_index.json` | 路径关键词 | 30 |
| 💬 L3 通讯历史 | `soulsync/channels/{platform}/*.json` | 消息全文 | 20 |

**通讯渠道会话：**

| 渠道 | 路径 |
|------|------|
| 钉钉 | `channels/dingtalk/*.json` |
| 飞书 | `channels/feishu/*.json` |
| 企业微信 | `channels/wecom/*.json` |
| QQ | `channels/qq/*.json` |
| Telegram | `channels/telegram/*.json` |
| Discord | `channels/discord/*.json` |
| ... | `channels/{platform}/*.json` |

### 任务队列（优先级）

| 优先级 | 队列键 | 用途 |
|--------|--------|------|
| P0 | `queue:p0` | 紧急任务 |
| P1 | `queue:p1` | 高优任务 |
| P2 | `queue:p2` | 普通任务 |
| P3 | `queue:p3` | 低优任务 |

**任务状态**：`pending → running → success/failed/cancelled`

### Web UI 功能

- **仪表盘** - 运行状态、活跃会话、模型使用统计
- **会话管理** - 浏览、搜索、导出、删除会话
- **配置编辑** - 模型、Provider、API Keys
- **服务控制** - 启停 Agent 服务、重启 Gateway
- **渠道管理** - 多渠道统一接入（国内外全覆盖）
- **Skills 市场** - 浏览、安装、配置 Skills
- **安全权限** - RBAC 角色权限控制、API Key 管理
- **中英双语** - 简体中文/English 切换

### 渠道架构（全渠道覆盖）

```
┌─────────────────────────────────────────────────────────────────┐
│                      国内外全渠道支持                            │
├────────────────────────────┬────────────────────────────────────┤
│  国内渠道                 │  海外渠道                           │
│  ────────────────────   │  ───────────────────────────────   │
│  ✅ 微信（WeChat）        │  ✅ Telegram                      │
│  ✅ 钉钉（DingTalk）     │  ✅ Discord                      │
│  ✅ 飞书（Feishu/Lark）  │  ✅ Slack                        │
│  ✅ 企业微信（WeCom）     │  ✅ WhatsApp                     │
│  ✅ QQ                  │  ✅ Facebook Messenger            │
│  ✅ 支付宝（Alipay）      │  ✅ LINE                         │
│                          │  ✅ Signal                        │
│                          │  ✅ Microsoft Teams               │
├────────────────────────────┴────────────────────────────────────┤
│                     IM Router 统一接入层                        │
│                    （可选组件，闭源）                           │
└─────────────────────────────────────────────────────────────────┘
```

## 🚀 快速开始

```bash
# 克隆
git clone http://192.168.1.3:8091/isatk/soulsync.git
cd soulsync

# 构建
go build -o soulsync ./cmd/soulsync

# 运行 Web UI
./soulsync web --port 8080

# 或命令行模式
./soulsync agent --model gpt-4o-mini --provider openai
```

提供全平台 Release 一键安装。

## 📁 项目结构

```
soulsync/
├── cmd/soulsync/      # 主程序
│   ├── main.go        # 入口
│   ├── agent.go      # Agent 核心
│   ├── web.go        # Web 服务
│   └── cli.go        # CLI 命令
├── pkg/
│   ├── agent/        # Agent 核心接口
│   ├── storage/      # 存储层
│   │   ├── db.go     # SQLite 操作
│   │   ├── search.go # Everything 理念，3 层索引
│   │   └── sync.go   # P2P/Relay 同步
│   ├── skills/       # Skill 系统
│   ├── transport/    # 平台适配器
│   └── config/       # 配置管理
└── skills/           # 内置 Skills
```

## 🔧 核心概念

### Session（会话）
一次对话，包含多条消息，与特定模型/提供商关联。支持跨模型切换。

### Soul（灵魂）
在模型切换后仍然保留的持久上下文和记忆。包括：
- 会话历史
- 长期记忆 (memory/)
- 用户偏好

### Memory（记忆）
持久化的知识库，按日期存储。基于 **Everything 理念**——3层本地索引（记忆档案/文件索引/聊天历史），启动时预加载到内存，<1ms 查询，结果直接注入 LLM 上下文。

### Index（索引）
FTS5 全文索引，毫秒级搜索所有历史内容。

### Skill（技能）
可附加的能力模块，与 Hermes/OpenClaw SKILL.md 格式兼容。

**内置基础技能（开箱即用）：**

| 类别 | 技能 |
|------|------|
| 文件操作 | file_read, file_write, file_search, file_browser |
| 终端执行 | terminal, bash, process_control |
| 代码开发 | code_execution, git, database, docker |
| Web | web_search, browser_navigate, http_request |
| AI/ML | vision, speech_tts, embedding, llm_call |
| 数据 | jupyter, data_analysis, csv_tool |
| 效率 | email, calendar, notes, reminder |
| 系统 | apple_script, windows_control, clipboard |
| DevOps | cron_job, monitoring, deployment |

**从 Hermes/OpenClaw 导入：**
```bash
soulsync import --from hermes ~/.hermes/skills/
soulsync import --from openclaw ~/.openclaw/
```

### Transport（渠道）
消息接入层，支持国内外全平台：

**国内渠道：**
- 微信（WeChat）- 公众号/小程序/企业微信
- 钉钉（DingTalk）- 机器人
- 飞书（Feishu/Lark）- 机器人
- QQ - QQ 机器人
- 企业微信（WeCom）- 应用消息
- 支付宝（Alipay）- 小程序

**海外渠道：**
- Telegram
- Discord
- Slack
- WhatsApp
- Facebook Messenger
- LINE
- Signal
- Microsoft Teams

**私有渠道：**
- 专用 IM 渠道（不开源）

## 📜 协议

MIT License - 详见 [LICENSE](LICENSE)

## 🤝 贡献

欢迎贡献！详见 [CONTRIBUTING_zh-CN.md](CONTRIBUTING_zh-CN.md)

---

**Roadmap**: 详见 [PRD.md](PRD.md)