remnote-bridge 0.1.11 → 0.1.13

package/skills/remnote-bridge/instructions/search.md

@@ -1,12 +1,26 @@
 # search
 
-> 在知识库中按文本搜索 Rem，返回匹配结果列表。
+> 在知识库中搜索 Rem，返回匹配结果列表。支持 SDK 全文搜索和 RAG 语义搜索。
 
 ---
 
 ## 功能
 
-`search` 调用 RemNote SDK 的全文搜索 API（`plugin.search.search()`），在当前知识库中搜索包含关键词的 Rem，返回匹配结果的 ID、文本和文档标记。
+`search` 在当前知识库中搜索包含关键词的 Rem。搜索方式由配置驱动：
+
+- **RAG 语义搜索**：在 `~/.remnote-bridge/config.json` 中启用 `addons.remnote-rag`（`enabled: true`），并在 `~/.remnote-bridge/addons/remnote-rag/config.json` 中配置 API Key，系统自动使用语义向量搜索（中文支持更好）
+- **SDK 全文搜索**：addon 未启用、未安装、或调用失败时自动降级
+
+安装与管理 addon：`remnote-bridge addon install remnote-rag` / `remnote-bridge addon list`。
+
+### 搜索来源（source 字段）
+
+| source | 说明 | 返回字段 |
+|--------|------|----------|
+| `"rag"` | 语义向量搜索（remnote-rag 已启用且可用） | remId, text, backText, ancestorPath, type, isDocument, tags, score |
+| `"sdk"` | SDK 全文搜索（默认降级） | remId, text, isDocument |
+
+降级场景：addon 未启用、remnote-rag 未安装、向量库未索引、子进程超时（10s）、返回异常。
 
 ---
 
@@ -42,7 +56,7 @@ remnote-bridge search <query> [--limit <N>]
 ### JSON 模式
 
 ```bash
-remnote-bridge search --json '{"query":"机器学习","numResults":10}'
+remnote-bridge search --json '{"query":"机器学习","limit":10}'
 ```
 
 ---
@@ -52,13 +66,39 @@ remnote-bridge search --json '{"query":"机器学习","numResults":10}'
 | 字段 | 类型 | 必需 | 说明 |
 |------|------|:----:|------|
 | `query` | string | 是 | 搜索关键词（不能为空） |
-| `numResults` | number | 否 | 结果数量上限（默认 20） |
+| `limit` | number | 否 | 结果数量上限（默认 20） |
 
 ---
 
 ## JSON 输出
 
-### 成功
+### 成功（RAG 模式）
+
+```json
+{
+  "ok": true,
+  "command": "search",
+  "data": {
+    "query": "机器学习",
+    "results": [
+      {
+        "remId": "kLrIOHJLyMd8Y2lyA",
+        "text": "支持向量机的核心思想",
+        "backText": "最大化分类间隔",
+        "ancestorPath": ["机器学习", "监督学习"],
+        "type": "concept",
+        "isDocument": false,
+        "tags": ["统计学习"],
+        "score": 0.87
+      }
+    ],
+    "totalFound": 1,
+    "source": "rag"
+  }
+}
+```
+
+### 成功（SDK 降级模式）
 
 ```json
 {
@@ -70,7 +110,8 @@ remnote-bridge search --json '{"query":"机器学习","numResults":10}'
       { "remId": "kLrIOHJLyMd8Y2lyA", "text": "机器学习笔记", "isDocument": true },
       { "remId": "abc123def456", "text": "监督学习与机器学习的关系", "isDocument": false }
     ],
-    "totalFound": 2
+    "totalFound": 2,
+    "source": "sdk"
   },
   "timestamp": "2026-03-06T10:00:00.000Z"
 }
@@ -118,30 +159,48 @@ remnote-bridge search --json '{"query":"机器学习","numResults":10}'
 ## 内部流程
 
 ```
-1. CLI 解析参数（query, numResults）
-2. sendRequest → WS → daemon → forwardToPlugin('search', { query, numResults })
-3. Plugin 端：
-   ├─ plugin.search.search([query], undefined, { numResults })
-   ├─ 遍历结果 Rem：
-   │   ├─ plugin.richText.toMarkdown(rem.text) → 转 Markdown 文本
-   │   ├─ 换行符替换为空格（保持单行）
-   │   └─ rem.isDocument() → 是否文档
-   └─ 返回 { query, results, totalFound }
-4. CLI 格式化输出
+1. CLI 解析参数（query, limit）
+2. 检查配置：addons.remnote-rag.enabled
+   ├─ 未启用 → 跳到步骤 4
+   └─ 已启用 → 继续步骤 3
+3. 尝试 RAG 搜索：
+   ├─ execFile('remnote-rag', ['search', '--json', payload])
+   ├─ remnote-rag 从 ~/.remnote-bridge/addons/remnote-rag/config.json 读取配置
+   ├─ 超时 10s
+   ├─ 成功 → 返回 RAG 结果（source: "rag"）
+   └─ 失败 → 继续到步骤 4（静默降级）
+4. 降级到 SDK 搜索：
+   ├─ sendRequest → WS → daemon → forwardToPlugin('search', ...)
+   ├─ Plugin 端调用 plugin.search.search()
+   └─ 返回 SDK 结果（source: "sdk"）
+5. CLI 格式化输出
 ```
 
 ---
 
 ## 结果字段说明
 
+### 通用字段（两种模式都有）
+
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `query` | string | 原始搜索关键词 |
 | `results` | array | 结果数组 |
 | `results[].remId` | string | 匹配 Rem 的 ID |
-| `results[].text` | string | Rem 正面文本（Markdown 格式，单行） |
+| `results[].text` | string | Rem 正面文本 |
 | `results[].isDocument` | boolean | 是否为文档页面 |
 | `totalFound` | number | 返回的结果数量 |
+| `source` | string | 搜索来源：`"rag"` 或 `"sdk"` |
+
+### RAG 模式额外字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `results[].backText` | string \| null | Rem 背面文本 |
+| `results[].ancestorPath` | string[] | 祖先路径名称数组（从根到父级） |
+| `results[].type` | string | Rem 类型：`"concept"` / `"descriptor"` / `"default"` |
+| `results[].tags` | string[] | 标签名称数组 |
+| `results[].score` | number | 语义相关性分数（0-1，越高越相关） |
 
 ---
 
@@ -191,6 +250,6 @@ RemNote 的 Web 版搜索索引按单字符拆分非空格语言的文本。搜
 ## 注意事项
 
 - 搜索结果的 `text` 字段是 Markdown 格式的单行文本（多行换行符已替换为空格）
-- `totalFound` 等于 `results.length`，即实际返回的数量（受 `numResults` 限制）
+- `totalFound` 等于 `results.length`，即实际返回的数量（受 `limit` 限制）
 - 搜索不会触发缓存写入——search 结果不进入 RemCache
 - 如需获取某个搜索结果的完整属性，需对其 `remId` 执行 `read-rem`

package/skills/remnote-bridge/instructions/setup.md

@@ -83,22 +83,21 @@ remnote-bridge --json setup
 
 ## AI Agent 使用流程
 
-setup 会弹出 Chrome 窗口，用户需要完成两件事：登录 RemNote + 配置 dev plugin。
+setup 会弹出 Chrome 窗口，用户只需**登录 RemNote**，然后彻底退出 Chrome。
+
+setup 只负责保存登录凭证——配置 dev plugin 是 connect 之后的事（见 `connect.md` 标准模式说明）。
 
 ### 交互步骤
 
 1. 调用 `setup`
 2. **立即告知用户**：
-   > 已打开 Chrome 浏览器。请完成以下操作：
-   > 1. 登录 RemNote
-   > 2. 在 RemNote 中配置开发插件：点击左下角插件图标 → 开发你的插件 → 输入 `http://localhost:8080`
-   > 3. 完成后彻底退出 Chrome（macOS 请按 Cmd+Q，仅关窗口不够）
+   > 已打开 Chrome 浏览器。请登录 RemNote，完成后彻底退出 Chrome（macOS 请按 Cmd+Q，仅关窗口不够）
 3. 等待 `setup` 命令返回（阻塞式，超时 600 秒）
 4. 收到成功 → 继续执行 `connect --headless`
 
 ### setup 之后
 
-`setup` 只需执行一次。登录凭证和 plugin 配置都已保存，之后每次只需 `connect --headless` 即可自动连接，无需用户操作。
+`setup` 只需执行一次。登录凭证已保存，之后每次只需 `connect --headless` 即可自动连接，无需用户操作。
 
 如果后续 headless 模式下 Plugin 始终不连接，可能是 RemNote 登录 session 过期，需重新 setup（删除 `~/.remnote-bridge/chrome-profile/.setup-done` 后重新执行）。