soulsync 1.0.0 → 1.0.4

package/CHANGES.md

@@ -0,0 +1,120 @@
+\# SoulSync 插件修改记录
+
+
+
+\## 版本 1.0.2 → 1.0.3
+
+
+
+\### 修复问题
+
+1\. \*\*Python 模块导入问题\*\*
+
+   - 修复 `src/main.py`、`src/sync.py` 中的 `from src.xxx` 导入错误
+
+   - 改为相对导入 `from xxx` 或绝对导入 `from profiles import xxx`
+
+
+
+2\. \*\*OpenClaw 插件格式问题\*\*
+
+   - 添加 `index.js` 作为 JavaScript 入口文件
+
+   - 修改 `package.json` 的 `openclaw.extensions` 格式
+
+   - 添加 `openclaw.plugin.json` 文件
+
+
+
+3\. \*\*配置文件路径问题\*\*
+
+   - 修复 `main\_fixed.py` 中的路径处理
+
+   - 支持跨平台路径（Windows/Linux）
+
+
+
+\### 新增文件
+
+\- `index.js` - OpenClaw JavaScript 入口
+
+\- `src/main\_fixed.py` - 修复版主程序
+
+\- `src/\_\_init\_\_.py` - Python 包标识
+
+\- `debug.py` - 调试诊断工具
+
+\- `setup.sh` - Linux 自动安装脚本
+
+\- `INSTALL.md` - 安装文档
+
+\- `TROUBLESHOOTING.md` - 故障排除指南
+
+\- `DEPLOY\_CHECKLIST.md` - 部署检查清单
+
+\- `.gitignore` - Git 忽略文件
+
+\- `CHANGES.md` - 本文件
+
+
+
+\### 修改的文件
+
+\- `package.json` - 更新版本号、main 入口、openclaw.extensions 格式
+
+\- `openclaw.plugin.json` - 更新版本号和配置
+
+\- `src/main.py` - 修复导入语句
+
+\- `src/sync.py` - 修复导入语句
+
+
+
+\### 待实现功能
+
+\- \[ ] 首次启动交互式登录（输入邮箱密码）
+
+\- \[ ] 自动检测 Python 环境
+
+\- \[ ] 自动安装 Python 依赖
+
+\- \[ ] Windows 安装脚本（setup.bat）
+
+
+
+\## 测试记录
+
+
+
+\### Ubuntu 测试环境
+
+\- OpenClaw 版本: 2026.2.15
+
+\- Python 版本: 3.12.3
+
+\- 安装方式: 本地路径安装
+
+\- 测试结果: ✅ 插件注册成功、启动成功、文件同步成功
+
+
+
+\### 测试命令
+
+```bash
+
+\# 安装
+
+openclaw plugins install ~/.openclaw/extensions/soulsync
+
+
+
+\# 启动
+
+openclaw soulsync:start
+
+
+
+\# 查看日志
+
+openclaw plugins logs soulsync
+

package/DEPLOY_CHECKLIST.md

@@ -0,0 +1,151 @@
+# SoulSync OpenClaw 插件部署检查清单
+
+## 本地 Ubuntu 部署步骤
+
+### ✅ 第1步：准备环境
+- [ ] Ubuntu 系统已更新: `sudo apt-get update`
+- [ ] Python 3.7+ 已安装: `python3 --version`
+- [ ] pip3 已安装: `pip3 --version`
+
+### ✅ 第2步：复制插件文件
+```bash
+# 创建插件目录
+mkdir -p ~/.openclaw/plugins/soulsync
+
+# 复制文件（根据你的实际路径调整）
+cp -r /path/to/soulsync/plugins/openclaw/* ~/.openclaw/plugins/soulsync/
+```
+
+### ✅ 第3步：安装依赖
+```bash
+cd ~/.openclaw/plugins/soulsync
+pip3 install -r requirements.txt --user
+```
+
+### ✅ 第4步：配置插件
+```bash
+# 编辑配置文件
+nano ~/.openclaw/plugins/soulsync/config.json
+```
+
+填写以下信息:
+```json
+{
+  "cloud_url": "http://你的服务器IP:3000",
+  "email": "你的邮箱",
+  "password": "你的密码",
+  "workspace": "./workspace",
+  "watch_files": ["MEMORY.md", "memory/"]
+}
+```
+
+### ✅ 第5步：运行诊断
+```bash
+cd ~/.openclaw/plugins/soulsync
+python3 debug.py
+```
+
+**期望结果**: 所有检查项显示 ✅
+
+### ✅ 第6步：测试运行
+```bash
+python3 src/main_fixed.py
+```
+
+**期望结果**:
+- 成功加载配置
+- 成功连接服务器（如果配置了账号）
+- 文件监听器启动
+- 显示 "Plugin Running"
+
+### ✅ 第7步：集成到 OpenClaw
+1. 确保 `openclaw.plugin.json` 格式正确
+2. 重启 OpenClaw
+3. 在 OpenClaw 中启用 SoulSync 插件
+
+---
+
+## 常见问题速查
+
+| 问题 | 快速解决 |
+|------|---------|
+| ModuleNotFoundError | `export PYTHONPATH="${PYTHONPATH}:$(pwd)/src"` |
+| Permission Denied | `chmod -R 755 ~/.openclaw/plugins/soulsync` |
+| 依赖安装失败 | `sudo apt-get install python3-dev` |
+| WebSocket 失败 | 检查 config.json 中的 cloud_url |
+| 文件监听失败 | `echo fs.inotify.max_user_watches=524288 \| sudo tee -a /etc/sysctl.conf && sudo sysctl -p` |
+
+---
+
+## 验证部署成功
+
+运行以下命令验证:
+```bash
+cd ~/.openclaw/plugins/soulsync
+
+# 1. 检查文件结构
+ls -la
+
+# 2. 检查依赖
+pip3 list | grep -E "requests|watchdog|websocket"
+
+# 3. 运行诊断
+python3 debug.py
+
+# 4. 测试启动（按 Ctrl+C 退出）
+python3 src/main_fixed.py
+```
+
+---
+
+## 同步到 GitHub
+
+调试完成后，提交到 GitHub:
+
+```bash
+cd /path/to/soulsync
+
+# 查看修改的文件
+git status
+
+# 添加新文件
+git add plugins/openclaw/debug.py
+git add plugins/openclaw/setup.sh
+git add plugins/openclaw/INSTALL.md
+git add plugins/openclaw/TROUBLESHOOTING.md
+git add plugins/openclaw/src/__init__.py
+git add plugins/openclaw/src/main_fixed.py
+git add plugins/openclaw/DEPLOY_CHECKLIST.md
+
+# 提交修改
+git commit -m "fix: 修复 Ubuntu 安装问题
+
+- 添加 __init__.py 解决 Python 模块导入问题
+- 创建 main_fixed.py 修复跨平台路径问题
+- 添加 debug.py 诊断工具
+- 添加 setup.sh 自动安装脚本
+- 添加完整文档（INSTALL, TROUBLESHOOTING, DEPLOY_CHECKLIST）
+- 更新版本号到 1.0.2"
+
+# 推送到 GitHub
+git push origin main
+```
+
+---
+
+## NPM 发布（如果适用）
+
+```bash
+cd plugins/openclaw
+
+# 更新版本号
+npm version patch  # 或 minor/major
+
+# 发布到 NPM
+npm publish
+```
+
+---
+
+**最后更新**: 2026-02-26
+**版本**: 1.0.2

package/INSTALL.md

@@ -0,0 +1,103 @@
+# SoulSync OpenClaw 插件安装指南
+
+## Ubuntu/Linux 安装步骤
+
+### 1. 安装系统依赖
+```bash
+sudo apt-get update
+sudo apt-get install -y python3-pip python3-venv
+```
+
+### 2. 安装 Python 依赖
+```bash
+cd /path/to/openclaw/plugins/soulsync
+pip3 install -r requirements.txt
+```
+
+### 3. 配置文件
+复制配置模板并修改：
+```bash
+cp config.json config.json.backup
+```
+
+编辑 `config.json`：
+```json
+{
+  "cloud_url": "http://你的服务器IP:3000",
+  "email": "你的邮箱",
+  "password": "你的密码",
+  "workspace": "./workspace",
+  "memory_file": "MEMORY.md",
+  "watch_files": [
+    "SOUL.md",
+    "IDENTITY.md",
+    "USER.md",
+    "AGENTS.md",
+    "TOOLS.md",
+    "skills.json",
+    "memory/",
+    "MEMORY.md"
+  ]
+}
+```
+
+### 4. 创建工作目录
+```bash
+mkdir -p workspace/memory
+```
+
+### 5. 测试运行
+```bash
+python3 src/main.py
+```
+
+## 常见问题排查
+
+### 问题1：ModuleNotFoundError
+**错误**：`No module named 'src'`
+
+**解决**：
+```bash
+export PYTHONPATH="${PYTHONPATH}:$(pwd)"
+```
+
+### 问题2：Permission Denied
+**错误**：无法写入文件
+
+**解决**：
+```bash
+chmod -R 755 /path/to/plugin
+```
+
+### 问题3：Watchdog 错误
+**错误**：`inotify` 限制
+
+**解决**：
+```bash
+echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
+sudo sysctl -p
+```
+
+## 调试模式
+
+启用详细日志：
+```bash
+DEBUG=1 python3 src/main.py
+```
+
+## 手动安装到 OpenClaw
+
+1. 找到 OpenClaw 插件目录：
+   ```bash
+   # 通常在用户目录下
+   ~/.openclaw/plugins/
+   # 或
+   /usr/share/openclaw/plugins/
+   ```
+
+2. 复制插件：
+   ```bash
+   cp -r /path/to/soulsync/plugins/openclaw ~/.openclaw/plugins/
+   ```
+
+3. 重启 OpenClaw

package/SPEC.md

@@ -0,0 +1,170 @@
+# SoulSync 插件端同步逻辑开发规范
+
+## 目标
+
+补全 `plugins/openclaw/src/sync.py`，实现完整的文件同步逻辑，使插件能与云端服务器双向同步文件。
+
+---
+
+## 现有代码概览
+
+以下模块已完成，sync.py 需要调用它们：
+
+### 1. ProfilesClient (profiles.py) - 已完成
+```python
+# 可用方法：
+profiles_client.get_profiles(path=None)      # 获取云端文件列表
+profiles_client.upload_profile(file_path, content, version)  # 上传文件
+profiles_client.download_profile(file_path)   # 下载单个文件（如有）
+```
+- upload_profile 冲突时抛出 ConflictError(server_version, server_content)
+
+### 2. VersionManager (version_manager.py) - 已完成
+```python
+# 可用方法：
+version_manager.get_version(file_path)        # 获取本地版本号
+version_manager.set_version(file_path, ver)   # 设置版本号
+version_manager.get_all_versions()            # 获取所有版本
+```
+
+### 3. OpenClawMultiWatcher (watcher.py) - 已完成
+- 监听 workspace 目录下的文件变化
+- 变化时调用 callback(file_path)
+
+### 4. OpenClawClient (client.py) - 已完成
+- WebSocket 连接已实现
+- 收到 ws 消息时调用 on_message_callback
+
+### 5. 服务端 API (soulsync-server)
+- `GET /api/profiles` → 返回 `{files: [{file_path, content, version, updated_at}]}`
+- `GET /api/profiles?path=xxx` → 返回单个文件
+- `POST /api/profiles` → 上传文件，body: `{file_path, content, version}`
+  - 成功返回 `{file_path, version, updated_at}`
+  - 冲突返回 409: `{error, server_version, server_content}`
+- WebSocket 事件 `file_updated`: `{file_path, version, updated_at}`
+
+---
+
+## 开发任务
+
+### 任务 1：实现 sync.py 的 pull_all 方法
+
+启动时从云端拉取所有文件到本地：
+
+```
+流程：
+1. 调用 profiles_client.get_profiles() 获取云端所有文件
+2. 遍历每个文件：
+   a. 读取本地文件内容（如果存在）
+   b. 比较云端 version 和本地 version_manager 中的版本
+   c. 如果云端版本更新 → 写入本地文件，更新 version_manager
+   d. 如果本地版本更新（本地有修改但未推送）→ 调用 push_file
+   e. 如果版本相同 → 跳过
+3. 打印同步结果摘要
+```
+
+**注意**：写入本地文件时，watcher 会触发 callback，需要有机制避免"写入触发再次上传"的死循环。建议在 sync 中维护一个 `_syncing_files` 集合，watcher callback 中检查该集合来跳过。
+
+### 任务 2：实现 sync.py 的 push_file 方法
+
+本地文件变更时推送到云端：
+
+```
+流程：
+1. 检查 file_path 是否在 _syncing_files 中，如果是则跳过（避免死循环）
+2. 读取本地文件内容
+3. 获取本地版本号 version_manager.get_version(file_path)
+4. 调用 profiles_client.upload_profile(file_path, content, version)
+5. 成功 → 更新 version_manager 为返回的新版本号
+6. 冲突 → 处理冲突（见任务 4）
+```
+
+### 任务 3：实现 sync.py 的 on_remote_change 方法
+
+收到 WebSocket 通知时拉取远程变更：
+
+```
+流程：
+1. 收到 {file_path, version} 事件
+2. 比较 version 和本地 version_manager 中的版本
+3. 如果远程版本更新 → 下载文件内容，写入本地，更新 version_manager
+4. 写入本地时加入 _syncing_files 避免触发 push
+```
+
+### 任务 4：冲突处理
+
+当 push_file 遇到 ConflictError 时：
+
+```
+策略（第一阶段简单处理）：
+1. 打印冲突警告信息
+2. 保存本地版本为 .conflict 备份文件
+3. 用云端版本覆盖本地文件
+4. 更新 version_manager
+5. 提示用户手动合并
+```
+
+### 任务 5：在 main.py 中连接 sync 与 watcher/websocket
+
+确保以下联动正常：
+
+```python
+# watcher 的 callback 应调用 sync.push_file
+def on_file_changed(file_path):
+    sync.push_file(file_path)
+
+# websocket 的 on_message 应调用 sync.on_remote_change
+def on_ws_message(data):
+    if data.get('event') == 'file_updated':
+        sync.on_remote_change(data['file_path'], data['version'])
+
+# 启动时应调用 sync.pull_all
+sync.pull_all()
+```
+
+---
+
+## 防死循环机制（关键）
+
+```python
+class ProfileSync:
+    def __init__(self, ...):
+        self._syncing_files = set()  # 正在同步的文件
+        self._sync_lock = threading.Lock()
+    
+    def _is_syncing(self, file_path):
+        return file_path in self._syncing_files
+    
+    def _mark_syncing(self, file_path):
+        self._syncing_files.add(file_path)
+    
+    def _unmark_syncing(self, file_path):
+        # 延迟移除，给 watcher 时间忽略事件
+        import threading
+        def remove():
+            time.sleep(2)
+            self._syncing_files.discard(file_path)
+        threading.Thread(target=remove, daemon=True).start()
+```
+
+---
+
+## 测试验证
+
+完成后需要通过以下测试：
+
+1. **启动同步**：插件启动 → pull_all 拉取云端文件到本地
+2. **本地推送**：修改本地 MEMORY.md → 自动推送到云端
+3. **远程拉取**：另一设备修改文件 → WebSocket 通知 → 本地自动更新
+4. **冲突处理**：两端同时修改 → 生成 .conflict 文件 + 提示用户
+5. **防死循环**：拉取写入本地时不触发再次推送
+
+---
+
+## 技术约束
+
+1. 使用现有的 ProfilesClient、VersionManager，不要重写
+2. 文件路径使用相对于 workspace 的路径（如 "MEMORY.md"、"memory/xxx.md"）
+3. 所有文件读写使用 UTF-8 编码
+4. 打印日志格式统一为 `[Sync] 操作描述`
+5. 异常要捕获并打印，不能让插件崩溃