soulsync 1.0.0 → 1.0.4

package/TROUBLESHOOTING.md

@@ -0,0 +1,199 @@
+# SoulSync OpenClaw 插件故障排除指南
+
+## 常见问题及解决方案
+
+### 1. 安装时提示 "No module named 'src'"
+
+**原因**: Python 路径问题
+
+**解决**:
+```bash
+# 方法1: 在插件目录运行
+cd /path/to/openclaw/plugins/soulsync
+export PYTHONPATH="${PYTHONPATH}:$(pwd)/src"
+python3 src/main.py
+
+# 方法2: 使用修复版 main_fixed.py
+python3 src/main_fixed.py
+```
+
+### 2. OpenClaw 无法识别插件
+
+**原因**: 插件目录结构不正确
+
+**解决**:
+```bash
+# 检查插件目录结构
+ls -la ~/.openclaw/plugins/soulsync/
+
+# 应该包含:
+# - openclaw.plugin.json
+# - src/
+# - config.json
+
+# 如果结构不对，重新复制
+cp -r /path/to/soulsync/plugins/openclaw ~/.openclaw/plugins/soulsync
+```
+
+### 3. watchdog 安装失败
+
+**原因**: 缺少系统依赖
+
+**解决**:
+```bash
+# Ubuntu/Debian
+sudo apt-get update
+sudo apt-get install -y python3-dev python3-pip
+
+# 然后重新安装
+pip3 install watchdog --user
+```
+
+### 4. 权限错误 Permission Denied
+
+**解决**:
+```bash
+# 修复权限
+chmod -R 755 ~/.openclaw/plugins/soulsync
+
+# 确保当前用户有写入权限
+sudo chown -R $(whoami):$(whoami) ~/.openclaw/plugins/soulsync
+```
+
+### 5. WebSocket 连接失败
+
+**原因**: 服务器地址配置错误或网络问题
+
+**解决**:
+```bash
+# 检查 config.json
+cat ~/.openclaw/plugins/soulsync/config.json
+
+# 测试服务器连通性
+curl http://your-server:3000/health
+
+# 检查防火墙
+sudo ufw status
+```
+
+### 6. 文件监听不工作 (inotify 限制)
+
+**解决**:
+```bash
+# 增加 inotify 限制
+echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
+sudo sysctl -p
+
+# 验证
+cat /proc/sys/fs/inotify/max_user_watches
+```
+
+### 7. Python 版本过低
+
+**检查**:
+```bash
+python3 --version  # 需要 >= 3.7
+
+# 如果版本过低，安装新版本
+sudo apt-get install python3.8 python3.8-pip
+```
+
+## 调试步骤
+
+### Step 1: 运行诊断脚本
+```bash
+cd ~/.openclaw/plugins/soulsync
+python3 debug.py
+```
+
+### Step 2: 检查日志
+```bash
+# 如果有日志文件
+tail -f ~/.openclaw/logs/soulsync.log
+
+# 或者直接运行看输出
+python3 src/main_fixed.py 2>&1 | tee debug.log
+```
+
+### Step 3: 手动测试组件
+```bash
+# 测试客户端
+python3 -c "from src.client import OpenClawClient; print('Client OK')"
+
+# 测试监听器
+python3 -c "from src.watcher import OpenClawMultiWatcher; print('Watcher OK')"
+```
+
+## OpenClaw 特定问题
+
+### OpenClaw 插件加载失败
+
+1. **检查插件格式**:
+```bash
+cat ~/.openclaw/plugins/soulsync/openclaw.plugin.json
+```
+
+2. **验证 JSON 格式**:
+```bash
+python3 -m json.tool ~/.openclaw/plugins/soulsync/openclaw.plugin.json
+```
+
+3. **重启 OpenClaw**:
+```bash
+# 找到 OpenClaw 进程并重启
+pkill -f openclaw
+# 然后重新启动 OpenClaw
+```
+
+### 插件版本不匹配
+
+检查 OpenClaw 版本:
+```bash
+openclaw --version
+```
+
+查看插件兼容性:
+```bash
+cat ~/.openclaw/plugins/soulsync/openclaw.plugin.json | grep version
+```
+
+## 获取帮助
+
+如果以上方法都无法解决问题:
+
+1. 运行诊断脚本并保存输出:
+```bash
+python3 debug.py > diagnostic.log 2>&1
+```
+
+2. 收集以下信息:
+   - OpenClaw 版本
+   - Python 版本: `python3 --version`
+   - 操作系统: `uname -a`
+   - 插件目录结构: `tree ~/.openclaw/plugins/soulsync`
+   - 错误日志
+
+3. 提交 Issue 到 GitHub:
+https://github.com/alanliuc-a11y/soulsync/issues
+
+## 快速修复命令
+
+一键修复常见问题:
+```bash
+cd ~/.openclaw/plugins/soulsync
+
+# 修复权限
+chmod -R 755 .
+
+# 安装依赖
+pip3 install -r requirements.txt --user
+
+# 创建工作目录
+mkdir -p workspace/memory
+
+# 运行诊断
+python3 debug.py
+
+# 启动插件
+python3 src/main_fixed.py
+```

package/{config.json → config.json.example}

@@ -1,7 +1,7 @@
 {
-  "cloud_url": "http://localhost:3000",
-  "email": "",
-  "password": "",
+  "cloud_url": "http://your-server:3000",
+  "email": "your-email@example.com",
+  "password": "your-password",
   "workspace": "./workspace",
   "memory_file": "MEMORY.md",
   "watch_files": [

package/debug.py

@@ -0,0 +1,221 @@
+#!/usr/bin/env python3
+"""
+SoulSync OpenClaw 插件调试工具
+用于检查安装环境和依赖
+"""
+
+import sys
+import os
+import json
+import importlib.util
+
+def check_python_version():
+    """检查 Python 版本"""
+    print("=" * 50)
+    print("Python 版本检查")
+    print("=" * 50)
+    version = sys.version_info
+    print(f"Python 版本: {version.major}.{version.minor}.{version.micro}")
+    if version.major < 3 or (version.major == 3 and version.minor < 7):
+        print("❌ 需要 Python 3.7 或更高版本")
+        return False
+    print("✅ Python 版本符合要求")
+    return True
+
+def check_dependencies():
+    """检查依赖包"""
+    print("\n" + "=" * 50)
+    print("依赖包检查")
+    print("=" * 50)
+    
+    required = {
+        'requests': 'requests>=2.28.0',
+        'watchdog': 'watchdog>=3.0.0',
+        'websocket': 'websocket-client>=1.6.0'
+    }
+    
+    all_ok = True
+    for module, package in required.items():
+        try:
+            if module == 'websocket':
+                importlib.import_module('websocket')
+            else:
+                importlib.import_module(module)
+            print(f"✅ {package}")
+        except ImportError:
+            print(f"❌ {package} - 未安装")
+            all_ok = False
+    
+    return all_ok
+
+def check_file_structure():
+    """检查文件结构"""
+    print("\n" + "=" * 50)
+    print("文件结构检查")
+    print("=" * 50)
+    
+    plugin_dir = os.path.dirname(os.path.abspath(__file__))
+    print(f"插件目录: {plugin_dir}")
+    
+    required_files = [
+        'openclaw.plugin.json',
+        'config.json',
+        'requirements.txt',
+        'src/main.py',
+        'src/__init__.py',
+        'src/client.py',
+        'src/watcher.py',
+        'src/sync.py',
+    ]
+    
+    all_ok = True
+    for file in required_files:
+        path = os.path.join(plugin_dir, file)
+        exists = os.path.exists(path)
+        status = "✅" if exists else "❌"
+        print(f"{status} {file}")
+        if not exists:
+            all_ok = False
+    
+    return all_ok
+
+def check_config():
+    """检查配置文件"""
+    print("\n" + "=" * 50)
+    print("配置文件检查")
+    print("=" * 50)
+    
+    config_path = os.path.join(os.path.dirname(__file__), 'config.json')
+    
+    if not os.path.exists(config_path):
+        print("❌ config.json 不存在")
+        return False
+    
+    try:
+        with open(config_path, 'r', encoding='utf-8') as f:
+            config = json.load(f)
+        
+        print("✅ config.json 格式正确")
+        
+        # 检查必要字段
+        required_fields = ['cloud_url', 'email', 'password', 'workspace']
+        for field in required_fields:
+            value = config.get(field)
+            if value:
+                if field in ['email', 'password']:
+                    print(f"✅ {field}: {'*' * len(str(value))}")
+                else:
+                    print(f"✅ {field}: {value}")
+            else:
+                print(f"⚠️  {field}: 未配置")
+        
+        return True
+    except json.JSONDecodeError as e:
+        print(f"❌ config.json 格式错误: {e}")
+        return False
+    except Exception as e:
+        print(f"❌ 读取 config.json 失败: {e}")
+        return False
+
+def check_workspace():
+    """检查工作目录"""
+    print("\n" + "=" * 50)
+    print("工作目录检查")
+    print("=" * 50)
+    
+    plugin_dir = os.path.dirname(os.path.abspath(__file__))
+    workspace = os.path.join(plugin_dir, 'workspace')
+    
+    if os.path.exists(workspace):
+        print(f"✅ workspace 目录存在: {workspace}")
+        
+        # 检查是否可写
+        if os.access(workspace, os.W_OK):
+            print("✅ workspace 目录可写")
+        else:
+            print("❌ workspace 目录不可写")
+            return False
+    else:
+        print(f"⚠️  workspace 目录不存在: {workspace}")
+        try:
+            os.makedirs(workspace, exist_ok=True)
+            print("✅ 已创建 workspace 目录")
+        except Exception as e:
+            print(f"❌ 创建 workspace 目录失败: {e}")
+            return False
+    
+    return True
+
+def test_import():
+    """测试导入主模块"""
+    print("\n" + "=" * 50)
+    print("模块导入测试")
+    print("=" * 50)
+    
+    plugin_dir = os.path.dirname(os.path.abspath(__file__))
+    src_dir = os.path.join(plugin_dir, 'src')
+    
+    if src_dir not in sys.path:
+        sys.path.insert(0, src_dir)
+    
+    try:
+        from main import SoulSyncPlugin
+        print("✅ 成功导入 SoulSyncPlugin")
+        return True
+    except Exception as e:
+        print(f"❌ 导入失败: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+def main():
+    """主函数"""
+    print("\n" + "=" * 50)
+    print("SoulSync OpenClaw 插件调试工具")
+    print("=" * 50 + "\n")
+    
+    checks = [
+        ("Python 版本", check_python_version),
+        ("依赖包", check_dependencies),
+        ("文件结构", check_file_structure),
+        ("配置文件", check_config),
+        ("工作目录", check_workspace),
+        ("模块导入", test_import),
+    ]
+    
+    results = []
+    for name, check_func in checks:
+        try:
+            result = check_func()
+            results.append((name, result))
+        except Exception as e:
+            print(f"\n❌ {name} 检查出错: {e}")
+            results.append((name, False))
+    
+    # 总结
+    print("\n" + "=" * 50)
+    print("检查结果总结")
+    print("=" * 50)
+    
+    for name, result in results:
+        status = "✅ 通过" if result else "❌ 失败"
+        print(f"{status} - {name}")
+    
+    all_passed = all(result for _, result in results)
+    
+    print("\n" + "=" * 50)
+    if all_passed:
+        print("🎉 所有检查通过！插件应该可以正常运行。")
+        print("\n运行命令: python3 src/main.py")
+    else:
+        print("⚠️  部分检查未通过，请根据上方提示修复问题。")
+        print("\n常见问题解决:")
+        print("1. 安装依赖: pip3 install -r requirements.txt")
+        print("2. 修复权限: chmod -R 755 .")
+        print("3. 创建目录: mkdir -p workspace/memory")
+    print("=" * 50)
+    
+    return 0 if all_passed else 1
+
+if __name__ == '__main__':
+    sys.exit(main())

package/index.js

@@ -0,0 +1,54 @@
+const { spawn } = require('child_process');
+const path = require('path');
+
+// 函数形式导出（推荐）
+module.exports = function register(api) {
+  console.log('[SoulSync] Registering plugin...');
+
+  // 注册CLI命令：启动 SoulSync
+  api.registerCli(
+    ({ program }) => {
+      program
+        .command('soulsync:start')
+        .description('启动 SoulSync 同步服务')
+        .action(() => {
+          const pluginDir = path.dirname(__filename);
+          const pythonScript = path.join(pluginDir, 'src', 'main.py');
+          const pythonPath = process.env.PYTHON_PATH || 'python3';
+        
+          console.log('[SoulSync] Starting Python service...');
+        
+          const pythonProcess = spawn(pythonPath, [pythonScript], {
+            cwd: pluginDir,
+            env: {
+              ...process.env,
+              OPENCLAW_PLUGIN: 'true',
+              PLUGIN_DIR: pluginDir
+            },
+            stdio: 'inherit'
+          });
+
+          pythonProcess.on('close', (code) => {
+            console.log(`[SoulSync] Python process exited with code ${code}`);
+          });
+        });
+    },
+    { commands: ['soulsync:start'] }
+  );
+
+  // 注册CLI命令：停止 SoulSync
+  api.registerCli(
+    ({ program }) => {
+      program
+        .command('soulsync:stop')
+        .description('停止 SoulSync 同步服务')
+        .action(() => {
+          console.log('[SoulSync] Stop command received');
+          // 这里可以实现停止逻辑
+        });
+    },
+    { commands: ['soulsync:stop'] }
+  );
+
+  console.log('[SoulSync] Plugin registered successfully');
+};

package/openclaw.plugin.json

@@ -0,0 +1,18 @@
+{
+  "id": "soulsync",
+  "name": "SoulSync",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "cloud_url": { "type": "string" },
+      "email": { "type": "string" },
+      "password": { "type": "string" }
+    }
+  },
+  "uiHints": {
+    "cloud_url": { "label": "服务器地址", "placeholder": "http://localhost:3000" },
+    "email": { "label": "邮箱" },
+    "password": { "label": "密码", "sensitive": true }
+  }
+}

package/package.json

@@ -1,29 +1,15 @@
 {
   "name": "soulsync",
-  "version": "1.0.0",
+  "version": "1.0.4",
   "description": "SoulSync plugin for OpenClaw - cross-bot memory synchronization",
   "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/alanliuc-a11y/soulsync.git"
-  },
-  "keywords": [
-    "openclaw",
-    "openclaw-plugin",
-    "bot-memory",
-    "bot-soulsync"
-  ],
-  "author": "Alan Liu",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/alanliuc-a11y/soulsync/issues"
+    "url": "https://github.com/alanliuc-a11y/soulsync"
   },
-  "homepage": "https://github.com/alanliuc-a11y/soulsync#readme",
- 	"openclaw": {
-   		 "plugin": true,
-  		  "type": "python"
-	}
+  "openclaw": {
+    "extensions": [
+      "./index.js"
+    ]
+  }
 }

package/setup.sh

@@ -0,0 +1,91 @@
+#!/bin/bash
+# SoulSync OpenClaw 插件 Linux 安装脚本
+
+set -e  # 遇到错误立即退出
+
+echo "======================================"
+echo "SoulSync OpenClaw 插件安装脚本"
+echo "======================================"
+echo ""
+
+# 获取脚本所在目录
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+echo "插件目录: $SCRIPT_DIR"
+echo ""
+
+# 检查 Python
+if ! command -v python3 &> /dev/null; then
+    echo "❌ 未找到 Python3"
+    echo "请安装 Python3: sudo apt-get install python3"
+    exit 1
+fi
+
+echo "✅ Python3 已安装: $(python3 --version)"
+
+# 检查 pip
+if ! command -v pip3 &> /dev/null; then
+    echo "❌ 未找到 pip3"
+    echo "请安装 pip3: sudo apt-get install python3-pip"
+    exit 1
+fi
+
+echo "✅ pip3 已安装"
+
+# 安装依赖
+echo ""
+echo "正在安装 Python 依赖..."
+pip3 install -r requirements.txt --user
+
+echo "✅ 依赖安装完成"
+
+# 创建必要的目录
+echo ""
+echo "创建工作目录..."
+mkdir -p workspace/memory
+echo "✅ 工作目录创建完成"
+
+# 检查配置文件
+echo ""
+if [ ! -f "config.json" ]; then
+    echo "⚠️  config.json 不存在"
+    if [ -f "config.json.example" ]; then
+        cp config.json.example config.json
+        echo "✅ 已从模板创建 config.json"
+        echo "⚠️  请编辑 config.json 配置你的账号信息"
+    else
+        echo "❌ 未找到配置文件模板"
+        exit 1
+    fi
+else
+    echo "✅ config.json 已存在"
+fi
+
+# 检查权限
+echo ""
+echo "检查文件权限..."
+chmod -R 755 "$SCRIPT_DIR"
+chmod +x debug.py
+if [ -f "setup.sh" ]; then
+    chmod +x setup.sh
+fi
+echo "✅ 权限设置完成"
+
+# 运行调试检查
+echo ""
+echo "运行安装检查..."
+python3 debug.py
+
+echo ""
+echo "======================================"
+echo "安装完成！"
+echo "======================================"
+echo ""
+echo "使用方法:"
+echo "1. 编辑 config.json 配置你的账号"
+echo "2. 运行插件: python3 src/main.py"
+echo "3. 或使用修复版: python3 src/main_fixed.py"
+echo ""
+echo "调试命令: python3 debug.py"
+echo ""

package/src/__init__.py

@@ -0,0 +1 @@
+# SoulSync OpenClaw Plugin