openclaw-memory/README.md

# 🦐 龙虾记忆同步系统

一个专为 OpenClaw 龙虾设计的记忆文件管理系统，提供文件树展示、差异对比、双向同步和属性管理功能。

## ✨ 核心特性

- ✅ **分块流式处理**：8KB 分块读取，内存限制 256MB，支持大文件处理
- ✅ **.lobsterignore 支持**：正则表达式匹配，过滤不需要同步的文件
- ✅ **智能差异对比**：行级差异，颜色区分，支持大文件截断
- ✅ **属性目录结构**：支持嵌套属性键值对（如 `author.name`, `metadata.tags`）
- ✅ **完整审计日志**：记录操作人、数据源、变动行数、执行时间
- ✅ **语义摘要**：自动生成文件内容摘要
- ✅ **冲突判定**：识别 HARD_CONFLICT 状态，智能判断严重冲突
- ✅ **丝滑前端**：Ant Design 树形控件，点选-对比-同步流程

## 📋 目录

- [快速开始](#快速开始)
- [功能特性](#功能特性)
- [技术架构](#技术架构)
- [项目结构](#项目结构)
- [API 文档](#api-文档)
- [部署指南](#部署指南)
- [开发指南](#开发指南)
- [常见问题](#常见问题)

## 🚀 快速开始

### 前置条件

- Docker 20.10+
- Docker Compose 2.0+
- 端口：8086（前端）、8087（后端）、5432（数据库）

### 一键启动

```bash
# 克隆项目
git clone http://10.2.0.100:8989/daotong/lobster-memory-sync.git
cd lobster-memory-sync

# 启动服务
docker-compose up -d

# 执行数据库迁移
docker-compose exec backend python manage.py migrate

# 查看日志
docker-compose logs -f
```

### 访问应用

- 📱 前端：http://localhost:8086
- 📡 后端 API：http://localhost:8087/api/
- 🗄️ PostgreSQL：localhost:5432

## 🎯 功能特性

### 1. 分块流式处理
- **ChunkedReadStream**：8KB 分块读取，避免大文件内存问题
- **内存限制**：最大 256MB 缓存，自动清理
- **流式哈希**：无需加载完整内容即可计算哈希
- **智能对比**：大文件只对比头尾，中间部分计算哈希

### 2. .lobsterignore 支持
- **正则表达式**：`re:.*\.log$` 匹配日志文件
- **通配符**：`*.pyc`, `node_modules/` 匹配目录和文件
- **默认规则**：自动过滤 `.git`, `__pycache__`, `.DS_Store` 等

### 3. 属性目录结构
- **嵌套属性**：使用点号分隔的键名（`author.name`, `metadata.tags`）
- **类型支持**：string, integer, float, boolean, json
- **分类管理**：支持属性分类和元数据
- **索引优化**：快速查询属性

### 4. 审计日志
- **完整记录**：操作人、操作时间、数据源、变动行数
- **变更追踪**：属性变更记录
- **执行时间**：精确到毫秒
- **历史查询**：支持按文件、操作类型查询

### 5. 冲突判定
- **7 种状态**：consistent, local_newer, db_newer, conflict, hard_conflict, local_only, db_only
- **HARD_CONFLICT**：版本 > 1 且 1 小时内更新
- **智能判断**：基于版本号和时间戳

### 6. 丝滑前端
- **Ant Design**：现代化 UI 组件库
- **文件树**：直观的树形控件，状态标签
- **差异对比**：绿色（新增）、红色（删除），行级差异
- **一键同步**：同步到本地 / 同步到数据库

## 🏗️ 技术架构

### 后端
- **框架**：Django 4.x + Django REST Framework
- **数据库**：PostgreSQL 15
- **内存管理**：ChunkedReadStream（256MB 限制）
- **Python**：3.11

### 前端
- **框架**：React 18
- **UI 库**：Ant Design 5.x
- **差异对比**：diff + react-syntax-highlighter
- **HTTP 客户端**：Axios

### 部署
- **容器**：Docker + Docker Compose
- **反向代理**：Nginx
- **SSL**：Let's Encrypt

## 📁 项目结构

```
lobster-memory-sync/
├── backend/                          # Django 后端
│   ├── memory_app/
│   │   ├── chunked_stream.py        # 流式读取器（内存限制 256MB）
│   │   ├── models.py                # 数据模型（LobsterMemory, FileAttribute, SyncHistory）
│   │   ├── services.py              # 业务逻辑
│   │   ├── views.py                 # API 视图
│   │   ├── serializers.py           # 序列化器
│   │   └── migrations/              # 数据库迁移
│   │       ├── 0001_initial.py
│   │       ├── 0002_add_summary_and_audit_fields.py
│   │       └── 0003_add_file_attribute.py
│   ├── memory_sync/
│   │   ├── settings.py              # Django 配置
│   │   ├── urls.py                  # 主路由
│   │   └── wsgi.py                  # WSGI 配置
│   ├── requirements.txt             # Python 依赖
│   ├── Dockerfile                   # 后端 Docker 配置
│   ├── manage.py                    # Django 管理脚本
│   └── test_simple.py               # 功能测试脚本
├── frontend/                         # React 前端
│   ├── src/
│   │   ├── components/
│   │   │   ├── FileTree.js          # 文件树组件
│   │   │   └── FileDiff.js          # 差异对比组件
│   │   ├── api/
│   │   │   └── index.js             # API 客户端
│   │   ├── App.js                   # 主应用
│   │   └── index.js                 # 入口文件
│   ├── package.json                 # Node 依赖
│   └── Dockerfile                   # 前端 Docker 配置
├── docker-compose.yml               # Docker Compose 配置
├── .lobsterignore.example           # .lobsterignore 示例
├── README.md                        # 项目文档
├── DEPLOY.md                        # 详细部署文档
├── CHANGELOG.md                     # 变更日志
└── .gitignore                       # Git 忽略规则
```

## 📡 API 文档

### 文件扫描

```http
GET /api/scan/?lobster_id=daotong
```

**响应示例：**
```json
{
  "success": true,
  "data": [
    {
      "file_path": "MEMORY.md",
      "full_path": "/app/memory_files/MEMORY.md",
      "hash": "abc123...",
      "size": 1234,
      "lobster_id": "daotong"
    }
  ],
  "total": 1
}
```

### 检查同步状态

```http
GET /api/status/?lobster_id=daotong
```

**响应示例：**
```json
{
  "success": true,
  "data": {
    "consistent": [],
    "local_newer": [],
    "db_newer": [],
    "conflict": [],
    "hard_conflict": [],
    "local_only": [{"file_path": "MEMORY.md", "status": "local_only", "hash": "abc123"}],
    "db_only": []
  }
}
```

### 获取文件差异

```http
GET /api/diff/?lobster_id=daotong&file_path=MEMORY.md&chunked=true
```

**响应示例：**
```json
{
  "success": true,
  "data": {
    "file_path": "MEMORY.md",
    "lobster_id": "daotong",
    "local_content": "本地内容",
    "db_content": "数据库内容",
    "local_hash": "abc123",
    "db_hash": "def456",
    "status": "conflict",
    "diff": {
      "local_lines": ["line1", "line2"],
      "db_lines": ["line1", "line3"],
      "has_diff": true,
      "is_truncated": false,
      "lines_changed": 1
    }
  }
}
```

### 同步到数据库

```http
POST /api/sync/db/
Content-Type: application/json

{
  "lobster_id": "daotong",
  "file_path": "MEMORY.md",
  "operator": "逍遥子"
}
```

**响应示例：**
```json
{
  "success": true,
  "message": "已同步到数据库",
  "data": {
    "id": 1,
    "lobster_id": "daotong",
    "file_path": "MEMORY.md",
    "content": "...",
    "hash": "abc123",
    "status": "consistent",
    "version": 1,
    "size": 1234,
    "summary": "文件摘要",
    "created_at": "2026-04-05T12:00:00Z",
    "updated_at": "2026-04-05T12:00:00Z"
  }
}
```

### 获取操作历史

```http
GET /api/history/?lobster_id=daotong&limit=10
```

**响应示例：**
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "lobster_id": "daotong",
      "file_path": "MEMORY.md",
      "action": "sync_to_db",
      "status": "success",
      "source": "local",
      "old_version": null,
      "new_version": 1,
      "lines_changed": 10,
      "operator": "逍遥子",
      "execution_time": 0.123,
      "created_at": "2026-04-05T12:00:00Z"
    }
  ],
  "total": 1
}
```

### .lobsterignore 管理

```http
# 获取忽略规则
GET /api/ignore/patterns/

# 重新加载忽略规则
POST /api/ignore/reload/
```

## 📘 详细部署指南

详细的部署文档请查看 [DEPLOY.md](DEPLOY.md)，包含：
- 系统要求
- Docker 安装
- 环境配置
- 数据库迁移
- 生产环境部署（Nginx + HTTPS）
- 数据库备份
- 监控与维护
- 故障排查
- 常见问题 FAQ

## 🛠️ 开发指南

### 后端开发

```bash
# 进入后端容器
docker exec -it lobster-backend bash

# 创建迁移
python manage.py makemigrations memory_app
python manage.py migrate

# 运行测试
python test_simple.py

# 运行开发服务器
python manage.py runserver 0.0.0.0:8087
```

### 前端开发

```bash
# 本地开发（不使用 Docker）
cd frontend
npm install
npm start

# 构建生产版本
npm run build
```

## ❓ 常见问题

**Q: 如何修改龙虾记忆目录？**
A: 修改 `docker-compose.yml` 中的挂载路径：
```yaml
backend:
  volumes:
    - /your/path/to/lobster/memory:/app/memory_files:ro
```

**Q: 如何配置 .lobsterignore？**
A: 在龙虾记忆目录创建 `.lobsterignore` 文件，参考 `.lobsterignore.example`

**Q: 内存占用过高怎么办？**
A: 系统已限制最大内存 256MB，自动清理缓存。如仍有问题，检查是否有大文件正在处理。

**Q: 如何查看操作日志？**
A: 访问 `GET /api/history/` 接口，支持按文件、操作类型筛选。

## 📝 License

MIT

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

**项目仓库**：http://10.2.0.100:8989/daotong/lobster-memory-sync.git