memory-gateway-sync 0.2.0

package/README.md

@@ -0,0 +1,113 @@
+# OpenClaw 插件侧方案
+
+## 插件信息
+
+| 项目 | 值 |
+|------|----|
+| 插件 ID | `memory-gateway-sync` |
+| kind | `generic`（不替换 memory slot） |
+| 安装路径 | `/home/node/.openclaw/extensions/memory-gateway-sync/` |
+| 作用 | 监听 MEMORY.md / memory/*.md 变化，POST 到 Gateway |
+
+## 目录结构（部署到容器内）
+
+```
+memory-gateway-sync/
+├── openclaw.plugin.json
+├── package.json
+└── src/
+    └── index.ts
+```
+
+## openclaw.plugin.json
+
+```json
+{
+  "id": "memory-gateway-sync",
+  "name": "Memory Gateway Sync",
+  "description": "fs.watch 监听 MEMORY 文件变化，双写到外部 Gateway",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "gatewayUrl": {
+        "type": "string",
+        "description": "Gateway POST 地址"
+      },
+      "gatewayToken": {
+        "type": "string",
+        "description": "Bearer Token"
+      },
+      "debounceMs": {
+        "type": "number",
+        "default": 1500,
+        "description": "防抖延迟毫秒数"
+      },
+      "agentId": {
+        "type": "string",
+        "description": "当前 agent 标识，写入 Gateway 时携带"
+      }
+    }
+  }
+}
+```
+
+## package.json
+
+```json
+{
+  "name": "@openclaw/memory-gateway-sync",
+  "version": "0.1.0",
+  "type": "module",
+  "openclaw": {
+    "extensions": ["./src/index.ts"]
+  }
+}
+```
+
+## openclaw.json 配置（在容器内 /home/node/.openclaw/openclaw.json 中添加）
+
+```json
+"plugins": {
+  "entries": {
+    "memory-gateway-sync": {
+      "enabled": true,
+      "config": {
+        "gatewayUrl": "http://172.22.39.89:8765/api/memory/ingest",
+        "gatewayToken": "your-secret-token",
+        "debounceMs": 1500,
+        "agentId": "main"
+      }
+    }
+  }
+}
+```
+
+## 核心逻辑说明（src/index.ts）
+
+### 启动时
+
+1. 从插件配置读取 `gatewayUrl`、`gatewayToken`、`debounceMs`
+2. 计算 workspace 路径：`~/.openclaw/workspace/`
+3. 确保 `MEMORY.md` 和 `memory/` 目录存在
+4. 分别挂载 `fs.watch`
+
+### 文件变化时
+
+1. 记录文件路径，启动防抖计时（同一文件 debounceMs 内只处理一次）
+2. 计时结束后：读取文件完整内容
+3. 构造 payload：`{ path, content, agentId, syncedAt }`
+4. `fetch POST` 到 Gateway
+5. 成功：打 info 日志；失败：打 warn 日志，**不抛异常**
+
+### 不处理的情况
+
+- 非 `.md` 文件的变化
+- `memory/` 二级子目录（暂不递归，可后续扩展）
+- 文件删除事件（只关心写入）
+
+## 关键约束
+
+- Gateway 失败不能影响 OpenClaw 正常运行（所有 Gateway 调用都 try/catch）
+- 不替换 memory-core，不干预读取链路
+- 只监听两个位置：`MEMORY.md` 和 `memory/`，不监听其他文件

package/openclaw.plugin.json

@@ -0,0 +1,29 @@
+{
+  "id": "memory-gateway-sync",
+  "name": "Memory Gateway Sync",
+  "description": "监听 MEMORY.md / memory/*.md 文件变化，双写到外部 Gateway",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "gatewayUrl": {
+        "type": "string",
+        "description": "Gateway POST 地址，如 http://172.22.39.89:8765/api/memory/ingest"
+      },
+      "gatewayToken": {
+        "type": "string",
+        "description": "Bearer Token，与 Gateway 的 GATEWAY_TOKEN 环境变量一致"
+      },
+      "debounceMs": {
+        "type": "number",
+        "default": 1500,
+        "description": "防抖延迟毫秒数，同一文件在此时间内多次变化只触发一次同步"
+      },
+      "agentId": {
+        "type": "string",
+        "description": "当前 agent 标识，写入 Gateway 时携带，用于后续多 agent 隔离"
+      }
+    },
+    "required": ["gatewayUrl", "gatewayToken"]
+  }
+}

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "memory-gateway-sync",
+  "version": "0.2.0",
+  "description": "Memory 双写插件：fs.watch 感知变化后同步到外部 Gateway",
+  "type": "module",
+  "openclaw": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,361 @@
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+// ── 类型 ──────────────────────────────────��───────────────────────────────────
+
+interface PluginConfig {
+  gatewayUrl: string;
+  gatewayToken: string;
+  debounceMs?: number;
+  agentId?: string;
+}
+
+interface IngestPayload {
+  path: string;
+  content: string;
+  agentId: string;
+  workspaceDir: string;
+  eventType: string;
+  syncedAt: string;
+}
+
+interface WorkspaceContext {
+  dir: string;
+  agentId: string;
+}
+
+// ── 插件入口 ──────────────────────────────────────────────────────────────────
+
+export default definePluginEntry({
+  id: "memory-gateway-sync",
+  name: "Memory Gateway Sync",
+  description:
+    "fs.watch 监听多 workspace 的 MEMORY 文件变化，双写到外部 Gateway（支持 peers/groups/knowledge 子目录）",
+  kind: "generic",
+
+  register(api) {
+    const cfg = (api.pluginConfig ?? {}) as PluginConfig;
+    const gatewayUrl = cfg.gatewayUrl;
+    const gatewayToken = cfg.gatewayToken;
+    const debounceMs = cfg.debounceMs ?? 1500;
+    const defaultAgentId = cfg.agentId ?? "default";
+
+    if (!gatewayUrl || !gatewayToken) {
+      api.logger.warn(
+        "memory-gateway-sync: gatewayUrl 或 gatewayToken 未配置，插件不启动"
+      );
+      return;
+    }
+
+    api.registerService({
+      id: "memory-gateway-sync",
+
+      start: async () => {
+        const openclawDir = path.join(os.homedir(), ".openclaw");
+
+        // 防抖 Map：key=文件绝对路径，value=setTimeout 句柄
+        const debounceTimers = new Map<
+          string,
+          ReturnType<typeof setTimeout>
+        >();
+
+        // 已注册 watcher 的目录集合（避免重复监听）
+        const watchedDirs = new Set<string>();
+
+        // 已注册的 workspace 集合（避免重复注册）
+        const registeredWorkspaces = new Map<string, WorkspaceContext>();
+
+        // ── 根据文件路径找到所属 workspace ────────────────────────────────
+
+        const findWorkspace = (absPath: string): WorkspaceContext | null => {
+          for (const [wsDir, ctx] of registeredWorkspaces) {
+            if (absPath.startsWith(wsDir + path.sep) || absPath === wsDir) {
+              return ctx;
+            }
+          }
+          return null;
+        };
+
+        // ── 从目录名解析 agentId ─────────────────────────────────────────
+
+        const resolveAgentId = (dirName: string): string => {
+          if (dirName === "workspace") {
+            return defaultAgentId;
+          }
+          if (dirName.startsWith("workspace-")) {
+            return dirName.substring("workspace-".length);
+          }
+          return defaultAgentId;
+        };
+
+        // ── 核心：同步单个文件到 Gateway ──────────────────────────────────
+
+        const syncFile = async (
+          absPath: string,
+          eventType: string
+        ): Promise<void> => {
+          const ws = findWorkspace(absPath);
+          if (!ws) {
+            api.logger.warn(
+              `memory-gateway-sync: 找不到所属 workspace: ${absPath}`
+            );
+            return;
+          }
+
+          let content: string;
+          try {
+            content = await fs.promises.readFile(absPath, "utf-8");
+          } catch (err) {
+            api.logger.warn(
+              `memory-gateway-sync: 读取文件失败 ${absPath}: ${String(err)}`
+            );
+            return;
+          }
+
+          const relativePath = path.relative(ws.dir, absPath);
+          const payload: IngestPayload = {
+            path: relativePath,
+            content,
+            agentId: ws.agentId,
+            workspaceDir: ws.dir,
+            eventType,
+            syncedAt: new Date().toISOString(),
+          };
+
+          try {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 5000);
+
+            const res = await fetch(gatewayUrl, {
+              method: "POST",
+              headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${gatewayToken}`,
+              },
+              body: JSON.stringify(payload),
+              signal: controller.signal,
+            });
+
+            clearTimeout(timeout);
+
+            if (res.ok) {
+              api.logger.info?.(
+                `memory-gateway-sync: [${ws.agentId}] 同步成功 ${relativePath} (${content.length} chars)`
+              );
+            } else {
+              const body = await res.text().catch(() => "");
+              api.logger.warn(
+                `memory-gateway-sync: [${ws.agentId}] Gateway 返回 ${res.status} for ${relativePath}: ${body}`
+              );
+            }
+          } catch (err) {
+            api.logger.warn(
+              `memory-gateway-sync: [${ws.agentId}] POST 失败 ${relativePath}: ${String(err)}`
+            );
+          }
+        };
+
+        // ── 防抖调度 ─────────────────────────────────────────────────────
+
+        const scheduleSync = (absPath: string, eventType: string): void => {
+          const existing = debounceTimers.get(absPath);
+          if (existing) clearTimeout(existing);
+
+          debounceTimers.set(
+            absPath,
+            setTimeout(() => {
+              debounceTimers.delete(absPath);
+              syncFile(absPath, eventType);
+            }, debounceMs)
+          );
+        };
+
+        // ── 递归监听目录中的 .md 文件 ────────────────────────────────────
+
+        const watchDirectory = (dirPath: string, wsDir: string): void => {
+          if (watchedDirs.has(dirPath)) return;
+          watchedDirs.add(dirPath);
+
+          try {
+            fs.watch(dirPath, async (eventType, filename) => {
+              if (!filename) return;
+
+              const absFilePath = path.join(dirPath, filename);
+
+              try {
+                const stat = await fs.promises.stat(absFilePath);
+
+                if (stat.isDirectory()) {
+                  scanAndWatch(absFilePath, wsDir, true);
+                  return;
+                }
+
+                if (stat.isFile() && filename.endsWith(".md")) {
+                  scheduleSync(absFilePath, eventType ?? "change");
+                }
+              } catch {
+                // stat 失败说明文件已删除，跳过
+              }
+            });
+
+            const ws = registeredWorkspaces.get(wsDir);
+            const label = ws ? ws.agentId : "?";
+            api.logger.info?.(
+              `memory-gateway-sync: [${label}] 监听目录 ${path.relative(wsDir, dirPath) || "memory/"}`
+            );
+          } catch (err) {
+            api.logger.warn(
+              `memory-gateway-sync: 无法监听目录 ${dirPath}: ${String(err)}`
+            );
+          }
+        };
+
+        // ── 递归扫描已存在的子目录并注册 watcher ─────────────────────────
+
+        const scanAndWatch = async (
+          dirPath: string,
+          wsDir: string,
+          syncExisting = false
+        ): Promise<void> => {
+          try {
+            await fs.promises.mkdir(dirPath, { recursive: true });
+          } catch {
+            // ignore
+          }
+
+          watchDirectory(dirPath, wsDir);
+
+          try {
+            const entries = await fs.promises.readdir(dirPath, {
+              withFileTypes: true,
+            });
+            for (const entry of entries) {
+              if (entry.isDirectory()) {
+                await scanAndWatch(
+                  path.join(dirPath, entry.name),
+                  wsDir,
+                  syncExisting
+                );
+              } else if (
+                syncExisting &&
+                entry.isFile() &&
+                entry.name.endsWith(".md")
+              ) {
+                scheduleSync(path.join(dirPath, entry.name), "change");
+              }
+            }
+          } catch {
+            // ignore
+          }
+        };
+
+        // ── 注册单个 workspace ───────────────────────────────────────────
+
+        const registerWorkspace = async (wsDir: string, wsAgentId: string): Promise<void> => {
+          if (registeredWorkspaces.has(wsDir)) return;
+
+          registeredWorkspaces.set(wsDir, { dir: wsDir, agentId: wsAgentId });
+
+          // 监听 MEMORY.md
+          const memoryMdPath = path.join(wsDir, "MEMORY.md");
+          try {
+            await fs.promises.writeFile(memoryMdPath, "", { flag: "a" });
+            fs.watch(memoryMdPath, (eventType) => {
+              scheduleSync(memoryMdPath, eventType ?? "change");
+            });
+            api.logger.info?.(
+              `memory-gateway-sync: [${wsAgentId}] 开始监听 MEMORY.md`
+            );
+          } catch (err) {
+            api.logger.warn(
+              `memory-gateway-sync: [${wsAgentId}] 无法监听 MEMORY.md: ${String(err)}`
+            );
+          }
+
+          // 递归监听 memory/ 目录
+          const memoryDirPath = path.join(wsDir, "memory");
+          await scanAndWatch(memoryDirPath, wsDir);
+
+          api.logger.info(
+            `memory-gateway-sync: [${wsAgentId}] workspace 注册完成 → ${wsDir}`
+          );
+        };
+
+        // ── 扫描所有 workspace 目录 ──────────────────────────────────────
+
+        const scanWorkspaces = async (): Promise<void> => {
+          try {
+            const entries = await fs.promises.readdir(openclawDir, {
+              withFileTypes: true,
+            });
+            for (const entry of entries) {
+              if (!entry.isDirectory()) continue;
+              const name = entry.name;
+
+              if (name === "workspace" || name.startsWith("workspace-")) {
+                const wsDir = path.join(openclawDir, name);
+                const wsAgentId = resolveAgentId(name);
+                await registerWorkspace(wsDir, wsAgentId);
+              }
+            }
+          } catch (err) {
+            api.logger.warn(
+              `memory-gateway-sync: 扫描 workspace 失败: ${String(err)}`
+            );
+          }
+        };
+
+        // ── 监听 .openclaw/ 目录，动态感知新 workspace ──────────────────
+
+        try {
+          fs.watch(openclawDir, async (eventType, filename) => {
+            if (!filename) return;
+            if (
+              filename !== "workspace" &&
+              !filename.startsWith("workspace-")
+            ) {
+              return;
+            }
+
+            const wsDir = path.join(openclawDir, filename);
+
+            try {
+              const stat = await fs.promises.stat(wsDir);
+              if (stat.isDirectory() && !registeredWorkspaces.has(wsDir)) {
+                const wsAgentId = resolveAgentId(filename);
+                api.logger.info(
+                  `memory-gateway-sync: 发现新 workspace → ${filename} (agentId=${wsAgentId})`
+                );
+                await registerWorkspace(wsDir, wsAgentId);
+              }
+            } catch {
+              // 目录不存在或已删除，忽略
+            }
+          });
+        } catch (err) {
+          api.logger.warn(
+            `memory-gateway-sync: 无法监听 ${openclawDir}: ${String(err)}`
+          );
+        }
+
+        // ── 启动：扫描所有已有 workspace ─────────────────────────────────
+
+        await scanWorkspaces();
+
+        const wsCount = registeredWorkspaces.size;
+        const wsIds = Array.from(registeredWorkspaces.values())
+          .map((w) => w.agentId)
+          .join(", ");
+        api.logger.info(
+          `memory-gateway-sync: 启动完成 → ${gatewayUrl} (防抖 ${debounceMs}ms, ${wsCount} 个 workspace: ${wsIds})`
+        );
+      },
+
+      stop: () => {
+        api.logger.info("memory-gateway-sync: 停止");
+      },
+    });
+  },
+});