114c235a60
新增内容： - 完整的版本发布说明（v1.0.0） - 详细的新增功能列表（后端、前端、数据库） - API 接口完整列表 - 依赖更新说明 - Git 提交记录 - 里程碑清单 - 致谢 记录所有重要的项目变更，便于追溯版本历史。
🦐 龙虾记忆同步系统
一个专为 OpenClaw 龙虾设计的记忆文件管理系统，提供文件树展示、差异对比、双向同步和属性管理功能。
✨ 核心特性
- ✅ 分块流式处理：8KB 分块读取，内存限制 256MB，支持大文件处理
- ✅ .lobsterignore 支持：正则表达式匹配，过滤不需要同步的文件
- ✅ 智能差异对比：行级差异，颜色区分，支持大文件截断
- ✅ 属性目录结构：支持嵌套属性键值对（如
author.name,metadata.tags） - ✅ 完整审计日志：记录操作人、数据源、变动行数、执行时间
- ✅ 语义摘要：自动生成文件内容摘要
- ✅ 冲突判定：识别 HARD_CONFLICT 状态，智能判断严重冲突
- ✅ 丝滑前端：Ant Design 树形控件，点选-对比-同步流程
📋 目录
🚀 快速开始
前置条件
- Docker 20.10+
- Docker Compose 2.0+
- 端口：8086（前端）、8087（后端）、5432（数据库）
一键启动
# 克隆项目
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 文档
文件扫描
GET /api/scan/?lobster_id=daotong
响应示例：
{
"success": true,
"data": [
{
"file_path": "MEMORY.md",
"full_path": "/app/memory_files/MEMORY.md",
"hash": "abc123...",
"size": 1234,
"lobster_id": "daotong"
}
],
"total": 1
}
检查同步状态
GET /api/status/?lobster_id=daotong
响应示例：
{
"success": true,
"data": {
"consistent": [],
"local_newer": [],
"db_newer": [],
"conflict": [],
"hard_conflict": [],
"local_only": [{"file_path": "MEMORY.md", "status": "local_only", "hash": "abc123"}],
"db_only": []
}
}
获取文件差异
GET /api/diff/?lobster_id=daotong&file_path=MEMORY.md&chunked=true
响应示例：
{
"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
}
}
}
同步到数据库
POST /api/sync/db/
Content-Type: application/json
{
"lobster_id": "daotong",
"file_path": "MEMORY.md",
"operator": "逍遥子"
}
响应示例：
{
"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"
}
}
获取操作历史
GET /api/history/?lobster_id=daotong&limit=10
响应示例：
{
"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 管理
# 获取忽略规则
GET /api/ignore/patterns/
# 重新加载忽略规则
POST /api/ignore/reload/
📘 详细部署指南
详细的部署文档请查看 DEPLOY.md，包含：
- 系统要求
- Docker 安装
- 环境配置
- 数据库迁移
- 生产环境部署（Nginx + HTTPS）
- 数据库备份
- 监控与维护
- 故障排查
- 常见问题 FAQ
🛠️ 开发指南
后端开发
# 进入后端容器
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
前端开发
# 本地开发（不使用 Docker）
cd frontend
npm install
npm start
# 构建生产版本
npm run build
❓ 常见问题
Q: 如何修改龙虾记忆目录？
A: 修改 docker-compose.yml 中的挂载路径：
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！