daotong/openclaw-memory
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 更新 CHANGELOG.md

Browse Source 
新增内容：
- 完整的版本发布说明（v1.0.0）
- 详细的新增功能列表（后端、前端、数据库）
- API 接口完整列表
- 依赖更新说明
- Git 提交记录
- 里程碑清单
- 致谢

记录所有重要的项目变更，便于追溯版本历史。
This commit is contained in:
道童
2026-04-05 14:39:32 +00:00
parent 5eb24ed3e2
commit 114c235a60
1 changed files with 186 additions and 370 deletions
Download Patch File Download Diff File Expand all files Collapse all files

556
CHANGELOG.md
View File

@@ -1,376 +1,192 @@
# 🎯 三个"补丁"更新日志
# 🦐 龙虾记忆同步系统 - 变更日志
## 更新时间
2026-04-05
所有重要的项目变更都会记录在此文件中。
## 更新说明
## [1.0.0] - 2026-04-05
根据逍遥子的建议，为龙虾记忆同步系统添加了三个重要功能补丁，提升系统性能、可用性和安全性。
### 🎉 首次发布
完整版本，包含所有核心功能。
### ✨ 新增功能
#### 后端
- ✅ **ChunkedReadStream**：流式文件读取器，内存限制 256MB
- 8KB 分块读取
- 最大缓存限制 256MB
- 流式哈希计算
- 自动内存清理
- ✅ **SmartDiffComparator**：智能差异对比器
- 大文件只对比头尾
- 中间部分计算哈希
- 内存占用不超过 256MB
- ✅ **MemoryMonitor**：内存监控器
- 监控当前内存使用
- 检查内存限制
- ✅ **FileAttribute 模型**：文件属性表
- 支持键值对存储
- 支持嵌套属性（点号分隔的路径）
- 支持属性类型（string/integer/float/boolean/json）
- 支持属性分类和元数据
- ✅ **SyncHistory 模型**：同步操作历史表
- 记录操作人、操作时间
- 记录数据源（local/database/manual）
- 记录变动行数
- 记录执行时间
- 记录属性变更
- ✅ **LobsterMemory 模型**：龙虾记忆表
- 新增 `summary` 字段（语义摘要）
- 新增 `has_attributes` 字段
- 新增 `hard_conflict` 状态
- 优化数据库索引
- ✅ **IgnorePattern**：.lobsterignore 模式匹配器
- 支持正则表达式匹配（`re:.*\.log$`）
- 支持通配符匹配（`*.pyc`, `node_modules/`）
- 支持目录递归匹配
- 默认忽略规则（`.git`, `__pycache__`, `.DS_Store`）
- ✅ **SemanticSummaryGenerator**：语义摘要生成器
- 预留本地模型接口
- 生成文件内容简短摘要
- ✅ **DiffChecker**：差异检查器
- 完善 status 接口
- 识别 HARD_CONFLICT 状态
- 计算变动行数
- 支持大文件限制
- ✅ **AuditLogger**：操作日志记录器
- 记录所有同步操作
- 支持历史查询
#### 前端
- ✅ **FileTree.js**：文件树组件
- Ant Design Tree 组件集成
- 文件状态标签显示（一致/冲突/本地更新/数据库更新）
- 统计信息展示（总文件数、总大小、冲突数）
- 刷新状态按钮
- 文件选择事件处理
- 文件夹和文件图标区分
- ✅ **FileDiff.js**：差异对比组件
- 使用 `diff` 库计算行级差异
- 颜色区分：绿色（新增）、红色（删除）
- 显示变动行数标签
- 支持大文件截断提示
- 刷新按钮
- 状态提示（Alert）
- 代码高亮（react-syntax-highlighter）
#### 数据库
- ✅ **迁移文件**
- `0001_initial.py`：初始表结构
- `0002_add_summary_and_audit_fields.py`：添加语义摘要和审计字段
- `0003_add_file_attribute.py`：添加文件属性表
### 🔧 API 接口
- `GET /api/scan/` - 扫描本地文件
- `GET /api/tree/` - 获取文件树
- `GET /api/status/` - 检查同步状态（包含 HARD_CONFLICT）
- `GET /api/diff/` - 获取文件差异（支持分块读取）
- `POST /api/sync/db/` - 同步到数据库（生成语义摘要）
- `POST /api/sync/local/` - 同步到本地
- `GET /api/versions/` - 获取文件的所有版本
- `GET /api/stats/` - 获取统计信息
- `GET /api/history/` - 获取操作历史（包含变动行数和数据源）
- `GET /api/ignore/patterns/` - 获取 .lobsterignore 模式列表
- `POST /api/ignore/reload/` - 重新加载 .lobsterignore 模式
### 📦 依赖更新
#### 后端
- Django 4.x
- Django REST Framework
- PostgreSQL 15
- Python 3.11
#### 前端
- React 18
- Ant Design 5.x
- diff ^5.1.0
- react-syntax-highlighter ^15.5.0
- Axios
### 🚀 部署
- Docker + Docker Compose
- Nginx 反向代理
- Let's Encrypt SSL
- 数据库自动备份
### 📝 文档
- README.md：项目文档
- DEPLOY.md：详细部署文档
- CHANGELOG.md：变更日志
- .lobsterignore.example：示例忽略文件
### 🧪 测试
- `test_simple.py`：简化功能测试
- .lobsterignore 匹配测试
- 分块读取测试
- 变动行数计算测试
- 冲突判定测试
### 🎯 核心特性
- ✅ 分块流式处理（内存限制 256MB）
- ✅ .lobsterignore 支持（正则表达式 + 通配符）
- ✅ 智能差异对比（行级差异，颜色区分）
- ✅ 属性目录结构（嵌套属性键值对）
- ✅ 完整审计日志（操作人、数据源、变动行数、执行时间）
- ✅ 语义摘要（自动生成文件内容摘要）
- ✅ 冲突判定（识别 HARD_CONFLICT 状态）
- ✅ 丝滑前端（Ant Design 树形控件，点选-对比-同步流程）
### 📊 Git 提交记录
```
5eb24ed - docs: 更新文档（README.md 和 DEPLOY.md）
1b06593 - feat: 前端 - 接好 Ant Design 树形控件和差异对比组件
b130f7a - feat: 完成 SyncHistory 和 FileAttribute 的迁移
0cb271a - feat: 完善 ChunkedReadStream 逻辑（内存限制 256MB）
3529c36 - fix: 修复 .lobsterignore 和变动行数计算
479d679 - feat: 完成所有功能模块并添加测试
7992ff0 - feat: 更新 API 视图和序列化器
a016335 - feat: 完善核心功能模块
```
### 🎉 里程碑
- [x] 项目初始化
- [x] 后端核心功能完成
- [x] 前端核心功能完成
- [x] 部署配置完成
- [x] 分块流式处理完成
- [x] .lobsterignore 支持完成
- [x] 审计日志完成
- [x] 语义摘要完成
- [x] 冲突判定完成
- [x] 前端丝滑体验完成
- [x] 数据库迁移完成
- [x] 文档更新完成
- [x] 推送到 Git 仓库
### 🌟 致谢
感谢逍遥子的宝贵建议和指导！
---
## 📦 补丁 1: 分块读取与流式传输
### 问题
- 如果龙虾的记忆文件（比如某些 Log 或向量快照）超过 50MB
- 一次性 GET /api/diff 会让后端内存瞬间飙升
### 解决方案
- **流式读取**：使用 8KB 分块读取大文件，避免一次性加载到内存
- **流式哈希计算**：直接从文件流计算哈希，无需加载完整内容
- **差异对比限制**：大文件只显示头尾各 500 行，中间省略
### 实现细节
```python
# services.py
class FileScanner:
chunk_size = 8192 # 8KB 分块读取
def read_file_chunked(self, file_path: Path) -> str:
"""分块读取文件"""
content_parts = []
with open(file_path, 'r', encoding='utf-8', errors='ignore') as f:
while True:
chunk = f.read(self.chunk_size)
if not chunk:
break
content_parts.append(chunk)
return ''.join(content_parts)
def read_file_stream(self, file_path: str) -> Iterator[str]:
"""流式读取文件（用于大文件传输）"""
with open(file_path, 'r', encoding='utf-8', errors='ignore') as f:
while True:
chunk = f.read(self.chunk_size)
if not chunk:
break
yield chunk
def compute_hash_stream(self, file_path: Path) -> str:
"""流式计算文件哈希（避免大文件内存问题）"""
hash_obj = hashlib.sha256()
with open(file_path, 'rb') as f:
while True:
chunk = f.read(self.chunk_size)
if not chunk:
break
hash_obj.update(chunk)
return hash_obj.hexdigest()
class DiffChecker:
def get_file_diff(self, local_content: str, db_content: str, max_lines: int = 1000) -> Dict:
"""获取文件差异（支持大文件限制）"""
local_lines = local_content.split('\n')
db_lines = db_content.split('\n')
# 限制行数（大文件只显示头尾）
if len(local_lines) > max_lines:
local_head = local_lines[:max_lines//2]
local_tail = local_lines[-max_lines//2:]
local_lines = local_head + ['... (中间省略 {}) 行 ...'.format(len(local_lines) - max_lines)] + local_tail
```
### API 更新
```http
# 获取文件差异（支持分块读取）
GET /api/diff/?lobster_id=daotong&file_path=large-file.log&chunked=true
```
---
## 📦 补丁 2: .lobsterignore 机制
### 问题
- 临时文件（如 .DS_Store、日志缓存）不需要进数据库
- 手动维护一个排除列表会更清爽
### 解决方案
- 创建 `.lobsterignore` 文件（类似 `.gitignore`）
- 扫描时自动跳过匹配的文件
- 提供默认忽略规则
### 实现细节
```python
# services.py
class IgnorePattern:
""".lobsterignore 模式匹配器"""
def __init__(self, base_dir: Path):
self.base_dir = base_dir
self.patterns = []
self.load_patterns()
def load_patterns(self):
"""加载 .lobsterignore 文件"""
ignore_file = self.base_dir / '.lobsterignore'
if ignore_file.exists():
with open(ignore_file, 'r', encoding='utf-8') as f:
for line in f:
line = line.strip()
# 跳过空行和注释
if line and not line.startswith('#'):
self.patterns.append(line)
# 添加默认忽略规则
default_patterns = [
'.DS_Store', '.git', '.gitignore', '__pycache__',
'node_modules', '*.pyc', '*.pyo', '*.log',
'*.tmp', '*.temp', '*.bak', '.vscode', '.idea'
]
for pattern in default_patterns:
if pattern not in self.patterns:
self.patterns.append(pattern)
def is_ignored(self, file_path: Path) -> bool:
"""判断文件是否被忽略"""
relative_path = file_path.relative_to(self.base_dir)
for pattern in self.patterns:
# 匹配文件名
if fnmatch.fnmatch(file_path.name, pattern):
return True
# 匹配相对路径
if fnmatch.fnmatch(str(relative_path), pattern):
return True
# 匹配目录
if pattern.endswith('/') and fnmatch.fnmatch(str(relative_path.parent), pattern.rstrip('/')):
return True
# 递归匹配子目录
if pattern.startswith('*/'):
parts = str(relative_path).split(os.sep)
for i, part in enumerate(parts):
if fnmatch.fnmatch(part, pattern[2:]):
return True
return False
```
### 示例文件
```bash
# .lobsterignore
# 系统文件
.DS_Store
.Thumbs.db
# IDE 和编辑器
.vscode/
.idea/
*.swp
# Python
__pycache__/
*.pyc
*.log
# Node.js
node_modules/
# 临时文件
*.tmp
*.bak
```
### API 更新
```http
# 获取忽略规则列表
GET /api/ignore/patterns/
# 重新加载忽略规则
POST /api/ignore/reload/
```
---
## 📦 补丁 3: 操作溯源（Audit Log）
### 问题
- 万一哪天点错了，无法查到是哪次操作导致的
- 需要记录操作历史，方便追溯问题
### 解决方案
- 新增 `SyncHistory` 模型
- 记录每次同步操作的详细信息
- 提供历史查询 API
### 实现细节
```python
# models.py
class SyncHistory(models.Model):
"""同步操作历史记录"""
ACTION_CHOICES = [
('sync_to_db', '同步到数据库'),
('sync_to_local', '同步到本地'),
('auto_sync', '自动同步'),
('manual_merge', '手动合并'),
]
STATUS_CHOICES = [
('success', '成功'),
('failed', '失败'),
('partial', '部分成功'),
]
lobster_id = models.CharField(max_length=50, help_text='龙虾ID')
file_path = models.CharField(max_length=500, help_text='文件相对路径')
action = models.CharField(max_length=20, choices=ACTION_CHOICES, help_text='操作类型')
status = models.CharField(max_length=20, choices=STATUS_CHOICES, help_text='操作状态')
old_version = models.IntegerField(null=True, blank=True, help_text='操作前版本')
new_version = models.IntegerField(null=True, blank=True, help_text='操作后版本')
old_hash = models.CharField(max_length=64, null=True, blank=True, help_text='操作前哈希')
new_hash = models.CharField(max_length=64, null=True, blank=True, help_text='操作后哈希')
file_size = models.IntegerField(default=0, help_text='文件大小（字节）')
operator = models.CharField(max_length=50, default='system', help_text='操作者')
error_message = models.TextField(null=True, blank=True, help_text='错误信息')
execution_time = models.FloatField(default=0, help_text='执行时间（秒）')
created_at = models.DateTimeField(auto_now_add=True, help_text='操作时间')
# services.py
class AuditLogger:
"""操作日志记录器"""
def log_sync_action(
self,
lobster_id: str,
file_path: str,
action: str,
old_version: int = None,
new_version: int = None,
old_hash: str = None,
new_hash: str = None,
file_size: int = 0,
operator: str = 'system',
status: str = 'success',
error_message: str = None,
execution_time: float = 0
):
"""记录同步操作"""
self.model.objects.create(...)
def get_history(
self,
lobster_id: str = None,
file_path: str = None,
action: str = None,
limit: int = 100
) -> List[Dict]:
"""获取操作历史"""
queryset = self.model.objects.all()
# 过滤和排序...
```
### 使用示例
```python
# views.py
@api_view(['POST'])
def sync_to_db(request):
"""同步到数据库（带操作日志）"""
audit_logger = AuditLogger()
start_time = time.time()
try:
# 执行同步操作...
execution_time = time.time() - start_time
# 记录成功日志
audit_logger.log_sync_action(
lobster_id=lobster_id,
file_path=file_path,
action='sync_to_db',
old_version=old_version,
new_version=new_version,
old_hash=old_hash,
new_hash=file_hash,
file_size=record.size,
operator=operator,
status='success',
execution_time=execution_time
)
except Exception as e:
# 记录失败日志
audit_logger.log_sync_action(
lobster_id=lobster_id,
file_path=file_path,
action='sync_to_db',
operator=operator,
status='failed',
error_message=str(e),
execution_time=execution_time
)
```
### API 更新
```http
# 获取操作历史
GET /api/history/?lobster_id=daotong&file_path=MEMORY.md&limit=50
```
### 历史记录示例
```json
{
"success": true,
"data": [
{
"id": 1,
"lobster_id": "daotong",
"file_path": "MEMORY.md",
"action": "sync_to_db",
"action_display": "同步到数据库",
"status": "success",
"status_display": "成功",
"old_version": 1,
"new_version": 2,
"old_hash": "abc123...",
"new_hash": "def456...",
"file_size": 1234,
"operator": "逍遥子",
"error_message": null,
"execution_time": 0.123,
"created_at": "2026-04-05T12:00:00Z"
}
]
}
```
---
## 📋 数据库迁移
需要执行数据库迁移以创建 `SyncHistory` 表：
```bash
# 进入后端容器
docker exec -it lobster-backend bash
# 创建迁移
python manage.py makemigrations memory_app
python manage.py migrate
```
---
## ✅ 完成检查清单
- [x] 分块读取与流式传输（services.py）
- [x] .lobsterignore 机制（services.py + .lobsterignore.example）
- [x] 操作溯源（models.py + services.py + views.py + serializers.py）
- [x] 新增 API 接口（urls.py）
- [x] 更新文档（CHANGELOG.md）
---
## 🚀 下一步
1. 执行数据库迁移
2. 推送代码到远程仓库
3. 更新前端界面（添加历史记录和忽略规则管理）
---
**感谢逍遥子的宝贵建议！** 🙏
**项目仓库**: http://10.2.0.100:8989/daotong/lobster-memory-sync.git
**维护者**: 道童
**版本**: 1.0.0
**发布日期**: 2026-04-05