@hzttt/multimodal-rag 0.1.1 → 0.2.0

package/README.md

@@ -11,6 +11,7 @@ OpenClaw 多模态 RAG 插件 — 使用本地 AI 模型对图像和音频进行
 - **自动监听**：实时监听文件夹变化，自动索引新增文件
 - **向量存储**：使用 LanceDB 高效存储和检索
 - **智能去重**：基于文件 SHA256 哈希去重
+- **索引通知**：批次聚合索引事件，通过 agent 自动通知到所有聊天渠道
 
 ## 前置条件
 
@@ -30,7 +31,7 @@ ollama pull qwen3-embedding:latest
 ### 方式一：从 npm 安装（推荐）
 
 ```bash
-openclaw plugins install @hzttt/multimodal-rag
+openclaw plugins install @hzttt/multimodal-rag@latest
 ```
 
 插件会自动安装到 `~/.openclaw/extensions/multimodal-rag/`，并自动安装所有运行时依赖。
@@ -64,11 +65,55 @@ openclaw multimodal-rag setup
 - **视觉模型**: `qwen3-vl:2b` (图像描述)
 - **嵌入模型**: `qwen3-embedding:latest` (向量生成)
 - **嵌入提供者**: `ollama` (本地)
-- **数据库路径**: `/home/lucy/.openclaw/multimodal-rag.lance`
+- **数据库路径**: `~/.openclaw/multimodal-rag.lance`
 - **启动时索引**: `true` (自动索引已有文件)
 
 你只需要指定要监听的文件夹路径即可。
 
+### 非交互式配置（适合脚本/远程部署）
+
+通过命令行参数一次性完成配置，无需交互输入，适用于 SSH 远程部署、CI/CD 脚本等场景：
+
+```bash
+# 最简用法：只指定监听路径（其他使用默认值）
+openclaw multimodal-rag setup --non-interactive --watch ~/photos --watch ~/audio
+
+# 简写形式
+openclaw multimodal-rag setup -n -w ~/photos -w ~/audio
+
+# 逗号分隔多个路径
+openclaw multimodal-rag setup -n --watch ~/photos,~/mic-recordings,~/usb_data
+
+# 自定义所有参数
+openclaw multimodal-rag setup -n \
+  --watch ~/photos --watch ~/audio \
+  --ollama-url http://192.168.0.100:11434 \
+  --vision-model qwen3-vl:2b \
+  --embed-model qwen3-embedding:latest \
+  --db-path ~/.openclaw/my-rag.lance \
+  --no-index-on-start
+
+# 使用 OpenAI 嵌入
+openclaw multimodal-rag setup -n \
+  --watch ~/photos \
+  --embedding-provider openai \
+  --openai-api-key sk-xxx \
+  --openai-model text-embedding-3-small
+```
+
+| 选项 | 简写 | 说明 | 默认值 |
+| --- | --- | --- | --- |
+| `--non-interactive` | `-n` | 启用非交互式模式 | - |
+| `--watch <paths...>` | `-w` | 监听路径（可多次指定或逗号分隔） | 必填 |
+| `--ollama-url <url>` | - | Ollama 服务地址 | `http://127.0.0.1:11434` |
+| `--vision-model <model>` | - | 视觉模型 | `qwen3-vl:2b` |
+| `--embed-model <model>` | - | 嵌入模型 | `qwen3-embedding:latest` |
+| `--embedding-provider <p>` | - | 嵌入提供者: `ollama` / `openai` | `ollama` |
+| `--openai-api-key <key>` | - | OpenAI API Key | - |
+| `--openai-model <model>` | - | OpenAI 嵌入模型 | `text-embedding-3-small` |
+| `--db-path <path>` | - | LanceDB 数据库路径 | `~/.openclaw/multimodal-rag.lance` |
+| `--no-index-on-start` | - | 启动时不索引已有文件 | `false` |
+
 ### 手动配置
 
 如需自定义配置，编辑 `~/.openclaw/openclaw.json`：
@@ -90,7 +135,12 @@ openclaw multimodal-rag setup
             "provider": "ollama"
           },
           "dbPath": "/home/lucy/.openclaw/multimodal-rag.lance",
-          "indexExistingOnStart": true
+          "indexExistingOnStart": true,
+          "notifications": {
+            "enabled": true,
+            "quietWindowMs": 30000,
+            "batchTimeoutMs": 600000
+          }
         }
       }
     }
@@ -100,23 +150,76 @@ openclaw multimodal-rag setup
 
 ### 配置项说明
 
-| 配置项 | 类型 | 默认值 | 说明 |
-|--------|------|--------|------|
-| `watchPaths` | string[] | `[]` | 监听的文件夹路径（支持 `~` 展开） |
-| `ollama.baseUrl` | string | `http://127.0.0.1:11434` | Ollama 服务地址 |
-| `ollama.visionModel` | string | `qwen3-vl:2b` | 用于图像描述的视觉模型 |
-| `ollama.embedModel` | string | `qwen3-embedding:latest` | 用于生成嵌入向量的模型 |
-| `embedding.provider` | string | `ollama` | 嵌入提供者: `ollama` 或 `openai` |
-| `embedding.openaiApiKey` | string | - | OpenAI API Key（仅 openai 时需要） |
-| `embedding.openaiModel` | string | `text-embedding-3-small` | OpenAI 嵌入模型 |
-| `dbPath` | string | `~/.openclaw/multimodal-rag.lance` | LanceDB 数据库路径 |
-| `watchDebounceMs` | number | `1000` | 文件监听去抖延迟（毫秒） |
-| `indexExistingOnStart` | boolean | `true` | 启动时是否索引已有文件 |
+
+| 配置项                          | 类型       | 默认值                                | 说明                                     |
+| ---------------------------- | -------- | ---------------------------------- | -------------------------------------- |
+| `watchPaths`                 | string[] | `[]`                               | 监听的文件夹路径（支持 `~` 展开）                    |
+| `ollama.baseUrl`             | string   | `http://127.0.0.1:11434`           | Ollama 服务地址                            |
+| `ollama.visionModel`         | string   | `qwen3-vl:2b`                      | 用于图像描述的视觉模型                            |
+| `ollama.embedModel`          | string   | `qwen3-embedding:latest`           | 用于生成嵌入向量的模型                            |
+| `embedding.provider`         | string   | `ollama`                           | 嵌入提供者: `ollama` 或 `openai`             |
+| `embedding.openaiApiKey`     | string   | -                                  | OpenAI API Key（仅 openai 时需要）           |
+| `embedding.openaiModel`      | string   | `text-embedding-3-small`           | OpenAI 嵌入模型                            |
+| `dbPath`                     | string   | `~/.openclaw/multimodal-rag.lance` | LanceDB 数据库路径                          |
+| `watchDebounceMs`            | number   | `1000`                             | 文件监听去抖延迟（毫秒）                           |
+| `indexExistingOnStart`       | boolean  | `true`                             | 启动时是否索引已有文件                            |
+| `notifications.enabled`      | boolean  | `false`                            | 启用索引完成通知（通过 agent 发送到所有渠道）            |
+| `notifications.quietWindowMs` | number   | `30000`                            | 静默窗口：最后一个文件处理完后等待多久再发送总结（毫秒）         |
+| `notifications.batchTimeoutMs` | number   | `600000`                           | 批次最大超时：超过此时间强制发送总结（毫秒），防止大批量索引时等太久 |
+
 
 配置完成后，重启 OpenClaw Gateway 使配置生效。
 
 ## 使用方法
 
+### 索引通知（可选功能）
+
+插件支持在索引新文件时自动发送通知到所有已配置的聊天渠道。通知采用批次聚合机制，避免逐文件通知造成的消息轰炸。
+
+#### 工作原理
+
+1. **开始通知**：检测到第一个新文件时，agent 会收到"开始索引"事件并通知用户
+2. **批次聚合**：持续聚合多个文件的索引状态，避免频繁通知
+3. **完成通知**：所有文件处理完成后（静默窗口到期），agent 会发送索引总结通知
+
+#### 通知示例
+
+**开始通知**：
+```
+[Multimodal RAG] 检测到 3 个新的媒体文件正在被索引...
+```
+
+**完成通知**：
+```
+[Multimodal RAG] 索引完成
+共处理 5 个文件，成功 4 个 (2 张图片, 2 个音频)，失败 1 个
+耗时 2 分 30 秒
+```
+
+#### 启用通知
+
+在配置中设置 `notifications.enabled: true`：
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "multimodal-rag": {
+        "config": {
+          "notifications": {
+            "enabled": true,
+            "quietWindowMs": 30000,
+            "batchTimeoutMs": 600000
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**注意**：通知功能需要配置 heartbeat 才能保证 agent 及时响应。参考 [Heartbeat 文档](https://docs.openclaw.ai/configuration#heartbeat)。
+
 ### Agent 工具
 
 插件注册 4 个 Agent 工具，可以在对话中自然地调用：
@@ -155,6 +258,9 @@ Agent：[调用 media_stats] → 总计 120 个文件，图片 80，音频 40
 # 交互式配置
 openclaw multimodal-rag setup
 
+# 非交互式配置
+openclaw multimodal-rag setup -n --watch ~/photos --watch ~/audio
+
 # 手动索引文件或文件夹
 openclaw multimodal-rag index ~/Pictures/photo.jpg
 
@@ -205,4 +311,4 @@ openclaw plugins list | grep multimodal-rag
 
 ## 许可证
 
-MIT
+MIT

package/index.ts

@@ -9,14 +9,15 @@ import { MediaStorage } from "./src/storage.js";
 import { createEmbeddingProvider } from "./src/embeddings.js";
 import { createMediaProcessor } from "./src/processor.js";
 import { MediaWatcher } from "./src/watcher.js";
+import { IndexNotifier } from "./src/notifier.js";
 import {
   createMediaSearchTool,
   createMediaDescribeTool,
   createMediaListTool,
   createMediaStatsTool,
 } from "./src/tools.js";
-import { runSetup } from "./src/setup.js";
-import type { PluginConfig } from "./src/types.js";
+import { runSetup, runNonInteractiveSetup } from "./src/setup.js";
+import type { PluginConfig, NotificationConfig } from "./src/types.js";
 
 const multimodalRagPlugin = {
   id: "multimodal-rag",
@@ -48,6 +49,11 @@ const multimodalRagPlugin = {
       dbPath: userConfig.dbPath || "~/.openclaw/multimodal-rag.lance",
       watchDebounceMs: userConfig.watchDebounceMs || 1000,
       indexExistingOnStart: userConfig.indexExistingOnStart !== false,
+      notifications: {
+        enabled: userConfig.notifications?.enabled ?? false,
+        quietWindowMs: userConfig.notifications?.quietWindowMs ?? 30000,
+        batchTimeoutMs: userConfig.notifications?.batchTimeoutMs ?? 600000,
+      },
     };
 
     // 解析数据库路径
@@ -76,8 +82,20 @@ const multimodalRagPlugin = {
       visionModel: cfg.ollama.visionModel,
     });
 
+    // 创建通知器（如果启用）
+    let notifier: IndexNotifier | undefined;
+    if (cfg.notifications?.enabled) {
+      notifier = new IndexNotifier(
+        cfg.notifications,
+        api.runtime,
+        api.config,
+        api.logger,
+      );
+      api.logger.info?.("multimodal-rag: Notifications enabled");
+    }
+
     // 创建文件监听器
-    const watcher = new MediaWatcher(cfg, storage, embeddings, processor, api.logger);
+    const watcher = new MediaWatcher(cfg, storage, embeddings, processor, api.logger, notifier);
 
     // ========================================================================
     // 注册工具
@@ -288,11 +306,51 @@ const multimodalRagPlugin = {
         });
 
       // openclaw multimodal-rag setup
+      // 支持交互式和非交互式两种模式：
+      //   交互式: openclaw multimodal-rag setup
+      //   非交互式: openclaw multimodal-rag setup -n --watch ~/photos --watch ~/audio
       rag
         .command("setup")
-        .description("交互式引导配置插件")
-        .action(async () => {
-          await runSetup();
+        .description("配置插件（支持交互式和非交互式模式）")
+        .option("-n, --non-interactive", "非交互式模式（需配合 --watch 使用）")
+        .option("-w, --watch <paths...>", "监听路径（可多次指定或逗号分隔）")
+        .option("--ollama-url <url>", "Ollama 服务地址", "http://127.0.0.1:11434")
+        .option("--vision-model <model>", "视觉模型名称", "qwen3-vl:2b")
+        .option("--embed-model <model>", "嵌入模型名称", "qwen3-embedding:latest")
+        .option("--embedding-provider <provider>", "嵌入提供者: ollama 或 openai", "ollama")
+        .option("--openai-api-key <key>", "OpenAI API Key（仅 openai 时需要）")
+        .option("--openai-model <model>", "OpenAI 嵌入模型")
+        .option("--db-path <path>", "LanceDB 数据库路径")
+        .option("--no-index-on-start", "启动时不索引已有文件")
+        .action(async (opts: {
+          nonInteractive?: boolean;
+          watch?: string[];
+          ollamaUrl?: string;
+          visionModel?: string;
+          embedModel?: string;
+          embeddingProvider?: string;
+          openaiApiKey?: string;
+          openaiModel?: string;
+          dbPath?: string;
+          noIndexOnStart?: boolean;
+        }) => {
+          if (opts.nonInteractive) {
+            // 非交互式模式：展开逗号分隔的路径
+            const watchPaths = (opts.watch || []).flatMap((p) => p.split(",").map((s) => s.trim()).filter(Boolean));
+            await runNonInteractiveSetup({
+              watch: watchPaths,
+              ollamaUrl: opts.ollamaUrl,
+              visionModel: opts.visionModel,
+              embedModel: opts.embedModel,
+              embeddingProvider: opts.embeddingProvider as "ollama" | "openai" | undefined,
+              openaiApiKey: opts.openaiApiKey,
+              openaiModel: opts.openaiModel,
+              dbPath: opts.dbPath,
+              noIndexOnStart: opts.noIndexOnStart,
+            });
+          } else {
+            await runSetup();
+          }
         });
     }, { commands: ["multimodal-rag"] });
 

package/openclaw.plugin.json

@@ -82,6 +82,27 @@
         "type": "boolean",
         "default": true,
         "description": "启动时是否索引现有文件"
+      },
+      "notifications": {
+        "type": "object",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "启用索引完成通知（通过 agent 发送到所有渠道）"
+          },
+          "quietWindowMs": {
+            "type": "number",
+            "default": 30000,
+            "description": "静默窗口：最后一个文件处理完后等待多久再发送总结（毫秒）"
+          },
+          "batchTimeoutMs": {
+            "type": "number",
+            "default": 600000,
+            "description": "批次最大超时：超过此时间强制发送总结（毫秒）"
+          }
+        },
+        "default": {}
       }
     }
   },
@@ -109,6 +130,20 @@
     "watchDebounceMs": {
       "label": "去抖延迟（毫秒）",
       "advanced": true
+    },
+    "notifications.enabled": {
+      "label": "启用通知",
+      "help": "索引完成后通过 agent 发送通知到所有渠道"
+    },
+    "notifications.quietWindowMs": {
+      "label": "静默窗口（毫秒）",
+      "advanced": true,
+      "help": "最后一个文件处理完后等待多久再发送总结"
+    },
+    "notifications.batchTimeoutMs": {
+      "label": "批次超时（毫秒）",
+      "advanced": true,
+      "help": "超过此时间强制发送总结，防止大批量索引时等太久"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hzttt/multimodal-rag",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "OpenClaw plugin for multimodal RAG - semantic indexing and time-aware search for images and audio using local AI models",
   "type": "module",
   "repository": {

package/src/notifier.ts

@@ -0,0 +1,189 @@
+/**
+ * 索引通知器 - 批次聚合 + Agent 触发
+ */
+
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+import type { MediaType, NotificationConfig, IndexEventCallbacks } from "./types.js";
+
+type BatchFileStatus = "queued" | "indexed" | "failed";
+type BatchFile = { status: BatchFileStatus; fileType?: MediaType; error?: string };
+
+/**
+ * IndexNotifier 负责聚合索引事件并触发 agent 通知
+ * 
+ * 工作流程:
+ * 1. 首个文件入队 -> 发送"开始索引"系统事件 -> 唤醒 agent
+ * 2. 持续聚合文件状态，重置静默计时器
+ * 3. 静默窗口到期且无待处理文件 -> 发送"索引完成总结"系统事件 -> 唤醒 agent
+ */
+export class IndexNotifier implements IndexEventCallbacks {
+  private state: "idle" | "batching" = "idle";
+  private batch: Map<string, BatchFile> = new Map();
+  private batchStartTime = 0;
+  private quietTimer: NodeJS.Timeout | null = null;
+  private batchTimeoutTimer: NodeJS.Timeout | null = null;
+
+  constructor(
+    private readonly config: NotificationConfig,
+    private readonly runtime: PluginRuntime,
+    private readonly openclawConfig: {
+      session?: { mainKey?: string };
+      agents?: { list?: Array<{ id?: string; default?: boolean }> };
+    },
+    private readonly logger: { info?: (msg: string) => void; warn?: (msg: string) => void },
+  ) {}
+
+  /**
+   * 文件入队事件
+   */
+  onFileQueued(filePath: string): void {
+    this.batch.set(filePath, { status: "queued" });
+
+    if (this.state === "idle") {
+      // 首个文件，开始批次
+      this.state = "batching";
+      this.batchStartTime = Date.now();
+
+      // 发送"开始索引"系统事件，唤醒 agent
+      this.triggerAgent(this.buildStartMessage());
+
+      // 设置批次最大超时
+      this.batchTimeoutTimer = setTimeout(() => {
+        this.finalizeBatch();
+      }, this.config.batchTimeoutMs);
+    }
+
+    this.resetQuietTimer();
+  }
+
+  /**
+   * 文件索引成功事件
+   */
+  onFileIndexed(filePath: string, fileType: MediaType): void {
+    this.batch.set(filePath, { status: "indexed", fileType });
+    this.resetQuietTimer();
+  }
+
+  /**
+   * 文件索引失败事件
+   */
+  onFileFailed(filePath: string, error: string): void {
+    this.batch.set(filePath, { status: "failed", error });
+    this.resetQuietTimer();
+  }
+
+  /**
+   * 重置静默窗口计时器
+   */
+  private resetQuietTimer(): void {
+    if (this.quietTimer) {
+      clearTimeout(this.quietTimer);
+    }
+
+    this.quietTimer = setTimeout(() => {
+      // 检查是否还有文件在处理中
+      const hasQueued = [...this.batch.values()].some((f) => f.status === "queued");
+
+      if (!hasQueued) {
+        // 所有文件都处理完了，发送总结
+        this.finalizeBatch();
+      } else {
+        // 还有文件在排队，继续等
+        this.resetQuietTimer();
+      }
+    }, this.config.quietWindowMs);
+  }
+
+  /**
+   * 批次完成，发送总结
+   */
+  private finalizeBatch(): void {
+    if (this.state !== "batching") {
+      return;
+    }
+
+    this.clearTimers();
+    this.triggerAgent(this.buildSummaryMessage());
+
+    // 重置状态
+    this.batch.clear();
+    this.state = "idle";
+  }
+
+  /**
+   * 清理所有计时器
+   */
+  private clearTimers(): void {
+    if (this.quietTimer) {
+      clearTimeout(this.quietTimer);
+      this.quietTimer = null;
+    }
+    if (this.batchTimeoutTimer) {
+      clearTimeout(this.batchTimeoutTimer);
+      this.batchTimeoutTimer = null;
+    }
+  }
+
+  /**
+   * 触发 agent: enqueueSystemEvent + requestHeartbeatNow
+   */
+  private triggerAgent(text: string): void {
+    try {
+      const sessionKey = this.runtime.system.resolveMainSessionKey(this.openclawConfig);
+      this.runtime.system.enqueueSystemEvent(text, { sessionKey });
+      this.runtime.system.requestHeartbeatNow({ reason: "multimodal-rag:notification" });
+      this.logger.info?.(`Notification triggered: ${text.slice(0, 80)}...`);
+    } catch (err) {
+      this.logger.warn?.(`Failed to trigger agent notification: ${String(err)}`);
+    }
+  }
+
+  /**
+   * 构建"开始索引"消息
+   */
+  private buildStartMessage(): string {
+    const count = this.batch.size;
+    return `[Multimodal RAG] 新文件索引通知: 检测到 ${count} 个新的媒体文件正在被索引，请通知用户。`;
+  }
+
+  /**
+   * 构建"索引完成总结"消息
+   */
+  private buildSummaryMessage(): string {
+    const files = [...this.batch.values()];
+    const total = files.length;
+    const succeeded = files.filter((f) => f.status === "indexed");
+    const failed = files.filter((f) => f.status === "failed");
+
+    // 统计成功文件的类型
+    const images = succeeded.filter((f) => f.fileType === "image").length;
+    const audios = succeeded.filter((f) => f.fileType === "audio").length;
+
+    // 计算耗时
+    const durationMs = Date.now() - this.batchStartTime;
+    const durationSec = Math.floor(durationMs / 1000);
+    const minutes = Math.floor(durationSec / 60);
+    const seconds = durationSec % 60;
+    const durationStr =
+      minutes > 0 ? `${minutes} 分 ${seconds} 秒` : `${seconds} 秒`;
+
+    // 构建消息
+    let message = `[Multimodal RAG] 索引完成通知: 共处理 ${total} 个文件，`;
+    message += `成功 ${succeeded.length} 个`;
+
+    if (images > 0 || audios > 0) {
+      const parts: string[] = [];
+      if (images > 0) parts.push(`${images} 张图片`);
+      if (audios > 0) parts.push(`${audios} 个音频`);
+      message += ` (${parts.join(", ")})`;
+    }
+
+    if (failed.length > 0) {
+      message += `，失败 ${failed.length} 个`;
+    }
+
+    message += `。耗时 ${durationStr}。请发送索引完成总结通知给用户。`;
+
+    return message;
+  }
+}

package/src/setup.ts

@@ -1,8 +1,8 @@
 /**
- * 交互式引导配置
+ * 引导配置（交互式 & 非交互式）
  *
- * 运行 `openclaw multimodal-rag setup` 时调用，
- * 引导用户完成必要配置并写入 openclaw 配置文件。
+ * 交互式: `openclaw multimodal-rag setup`
+ * 非交互式: `openclaw multimodal-rag setup --watch ~/photos,~/audio --non-interactive`
  */
 
 import * as readline from "node:readline/promises";
@@ -31,6 +31,19 @@ type PluginConfigPartial = {
   indexExistingOnStart?: boolean;
 };
 
+/** 非交互式 setup 的选项 */
+export type NonInteractiveSetupOpts = {
+  watch: string[];
+  ollamaUrl?: string;
+  visionModel?: string;
+  embedModel?: string;
+  embeddingProvider?: "ollama" | "openai";
+  openaiApiKey?: string;
+  openaiModel?: string;
+  dbPath?: string;
+  noIndexOnStart?: boolean;
+};
+
 function loadOpenClawConfig(): Record<string, unknown> {
   if (!fs.existsSync(CONFIG_FILE)) {
     return {};
@@ -54,6 +67,75 @@ function getExistingPluginConfig(config: Record<string, unknown>): PluginConfigP
   return (entry?.config as PluginConfigPartial) || {};
 }
 
+/**
+ * 将插件配置写入 openclaw.json
+ */
+function writePluginConfig(pluginConfig: PluginConfigPartial): void {
+  const config = loadOpenClawConfig();
+  const plugins = (config.plugins || {}) as Record<string, unknown>;
+  const entries = (plugins.entries || {}) as Record<string, unknown>;
+  const pluginEntry = (entries["multimodal-rag"] || {}) as Record<string, unknown>;
+
+  pluginEntry.enabled = true;
+  pluginEntry.config = pluginConfig;
+
+  entries["multimodal-rag"] = pluginEntry;
+  plugins.entries = entries;
+  config.plugins = plugins;
+
+  saveOpenClawConfig(config);
+}
+
+/**
+ * 非交互式配置
+ *
+ * 适用于脚本自动化、SSH 远程部署等场景。
+ * 所有参数通过命令行选项传入，不读取 stdin。
+ *
+ * 用法:
+ *   openclaw multimodal-rag setup --non-interactive --watch ~/photos,~/audio
+ *   openclaw multimodal-rag setup -n -w ~/photos -w ~/audio --ollama-url http://host:11434
+ */
+export async function runNonInteractiveSetup(opts: NonInteractiveSetupOpts): Promise<void> {
+  if (opts.watch.length === 0) {
+    console.error("✗ 非交互式模式必须通过 --watch 指定至少一个监听路径");
+    console.error("  示例: openclaw multimodal-rag setup --non-interactive --watch ~/photos");
+    process.exit(1);
+  }
+
+  const existing = getExistingPluginConfig(loadOpenClawConfig());
+
+  const pluginConfig: PluginConfigPartial = {
+    watchPaths: opts.watch,
+    ollama: {
+      baseUrl: opts.ollamaUrl || existing.ollama?.baseUrl || "http://127.0.0.1:11434",
+      visionModel: opts.visionModel || existing.ollama?.visionModel || "qwen3-vl:2b",
+      embedModel: opts.embedModel || existing.ollama?.embedModel || "qwen3-embedding:latest",
+    },
+    embedding: {
+      provider: opts.embeddingProvider || existing.embedding?.provider || "ollama",
+      ...(opts.openaiApiKey && { openaiApiKey: opts.openaiApiKey }),
+      ...(opts.openaiModel && { openaiModel: opts.openaiModel }),
+    },
+    dbPath: opts.dbPath || existing.dbPath || "~/.openclaw/multimodal-rag.lance",
+    indexExistingOnStart: opts.noIndexOnStart ? false : (existing.indexExistingOnStart !== false),
+  };
+
+  writePluginConfig(pluginConfig);
+
+  console.log("✓ 配置已保存到 ~/.openclaw/openclaw.json\n");
+  console.log("配置摘要:");
+  console.log(`  监听路径:     ${pluginConfig.watchPaths!.join(", ")}`);
+  console.log(`  Ollama 地址:  ${pluginConfig.ollama!.baseUrl}`);
+  console.log(`  视觉模型:     ${pluginConfig.ollama!.visionModel}`);
+  console.log(`  嵌入模型:     ${pluginConfig.ollama!.embedModel}`);
+  console.log(`  嵌入提供者:   ${pluginConfig.embedding!.provider}`);
+  console.log(`  数据库路径:   ${pluginConfig.dbPath}`);
+  console.log(`  启动时索引:   ${pluginConfig.indexExistingOnStart ? "是" : "否"}`);
+  console.log();
+  console.log("提示: 重启 OpenClaw Gateway 以加载新配置");
+}
+
 async function checkOllamaHealth(baseUrl: string): Promise<boolean> {
   try {
     const res = await fetch(`${baseUrl}/api/tags`, { signal: AbortSignal.timeout(5000) });
@@ -148,19 +230,7 @@ export async function runSetup(): Promise<void> {
   // ================================================================
   console.log("\n── 保存配置 ──\n");
 
-  // 深合并到 openclaw 配置
-  const plugins = (config.plugins || {}) as Record<string, unknown>;
-  const entries = (plugins.entries || {}) as Record<string, unknown>;
-  const pluginEntry = (entries["multimodal-rag"] || {}) as Record<string, unknown>;
-
-  pluginEntry.enabled = true;
-  pluginEntry.config = pluginConfig;
-
-  entries["multimodal-rag"] = pluginEntry;
-  plugins.entries = entries;
-  config.plugins = plugins;
-
-  saveOpenClawConfig(config);
+  writePluginConfig(pluginConfig);
 
   console.log("✓ 配置已保存到 ~/.openclaw/openclaw.json\n");
 

package/src/types.ts

@@ -30,6 +30,24 @@ export type MediaSearchResult = {
   score: number; // 相似度分数 (0-1)
 };
 
+/**
+ * 通知配置
+ */
+export type NotificationConfig = {
+  enabled: boolean; // 是否启用通知，默认 false
+  quietWindowMs: number; // 静默窗口（毫秒），默认 30000
+  batchTimeoutMs: number; // 批次最大超时（毫秒），默认 600000
+};
+
+/**
+ * 索引事件回调接口（用于 watcher -> notifier 通信）
+ */
+export type IndexEventCallbacks = {
+  onFileQueued: (filePath: string) => void;
+  onFileIndexed: (filePath: string, fileType: MediaType) => void;
+  onFileFailed: (filePath: string, error: string) => void;
+};
+
 /**
  * 插件配置
  */
@@ -52,6 +70,7 @@ export type PluginConfig = {
   dbPath: string;
   watchDebounceMs: number;
   indexExistingOnStart: boolean;
+  notifications?: NotificationConfig;
 };
 
 /**

package/src/watcher.ts

@@ -8,7 +8,7 @@ import { basename, extname, resolve, join } from "node:path";
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import type { MediaType, PluginConfig } from "./types.js";
+import type { MediaType, PluginConfig, IndexEventCallbacks } from "./types.js";
 import type { MediaStorage } from "./storage.js";
 import type { IEmbeddingProvider } from "./types.js";
 import type { IMediaProcessor } from "./types.js";
@@ -45,6 +45,7 @@ export class MediaWatcher {
     private readonly embeddings: IEmbeddingProvider,
     private readonly processor: IMediaProcessor,
     private readonly logger: { info?: (msg: string) => void; warn?: (msg: string) => void },
+    private readonly callbacks?: IndexEventCallbacks,
   ) {}
 
   /**
@@ -156,6 +157,8 @@ export class MediaWatcher {
    */
   private enqueueFile(filePath: string): void {
     this.processQueue.add(filePath);
+    // 通知回调：文件已入队
+    this.callbacks?.onFileQueued(filePath);
     this.processNextFile();
   }
 
@@ -278,6 +281,9 @@ export class MediaWatcher {
       
       // 索引成功，清除失败记录
       this.failedFiles.delete(filePath);
+      
+      // 通知回调：文件索引成功
+      this.callbacks?.onFileIndexed(filePath, fileType);
     } catch (error) {
       const errorMsg = String(error);
       this.logger.warn?.(`Failed to index ${filePath}: ${errorMsg}`);
@@ -301,6 +307,9 @@ export class MediaWatcher {
         setTimeout(() => {
           this.enqueueFile(filePath);
         }, 60000);
+      } else {
+        // 达到最大重试次数或非临时错误，通知回调：文件索引失败
+        this.callbacks?.onFileFailed(filePath, errorMsg);
       }
     }
   }