remnote-bridge 0.1.11 → 0.1.13

package/remnote-plugin/src/widgets/index.tsx

@@ -1,55 +1,59 @@
 import { declareIndexPlugin, type ReactRNPlugin, WidgetLocation } from '@remnote/plugin-sdk';
 import '../style.css';
 import '../index.css';
-import { SETTING_WS_URL, DEFAULT_WS_URL, DEFAULT_PLUGIN_VERSION } from '../settings';
-import { WebSocketClient } from '../bridge/websocket-client';
+import { DEFAULT_PLUGIN_VERSION } from '../settings';
+import { MultiConnectionManager } from '../bridge/multi-connection-manager';
 import { createMessageRouter } from '../bridge/message-router';
-// test-scripts 已完成数据收集，不再打包进生产代码
-// 如需重跑，取消注释对应 import 和 onActivate 调用
-// import { runActionTests } from '../test-scripts/test-actions';
-// import { runRichTextBuilderTest } from '../test-scripts/test-richtext-builder';
-// import { runRichTextRemainingTest } from '../test-scripts/test-richtext-remaining';
-// import { runRichTextMatrixTest } from '../test-scripts/test-richtext-matrix';
-// import { runPowerupRenderingTest } from '../test-scripts/test-powerup-rendering';
 
-let wsClient: WebSocketClient | null = null;
+let connectionManager: MultiConnectionManager | null = null;
 // 本地日志缓冲区：避免 onLog 并发读写 plugin.storage 的竞态
 const logBuffer: Array<{ time: number; message: string; level: string }> = [];
 let logFlushPending = false;
 
 async function onActivate(plugin: ReactRNPlugin) {
-  // 注册 WS Server URL 设置
-  await plugin.settings.registerStringSetting({
-    id: SETTING_WS_URL,
-    title: 'Bridge WS Server URL',
-    description: '守护进程 WebSocket Server 地址（默认 ws://127.0.0.1:3002）',
-    defaultValue: DEFAULT_WS_URL,
-  });
-
   // 注册 Bridge Widget（右侧边栏）
   await plugin.app.registerWidget('bridge_widget', WidgetLocation.RightSidebar, {
     dimensions: { height: 'auto', width: '100%' },
     widgetTabIcon: 'https://cdn.jsdelivr.net/npm/lucide-static@0.460.0/icons/globe.svg',
   });
 
-  // 读取 WS URL 设置
-  const wsUrl =
-    (await plugin.settings.getSetting<string>(SETTING_WS_URL)) || DEFAULT_WS_URL;
+  // 自动发现孪生槽位：Plugin 由 daemon 的 static-server 提供服务，
+  // fetch('/api/discovery') 是同源请求，返回 daemon 的 slotIndex 等信息
+  let twinSlotIndex = 0;
+  let instanceName = '';
+  let configPort = 29102;
+  try {
+    const resp = await fetch('/api/discovery');
+    if (resp.ok) {
+      const data = await resp.json();
+      if (typeof data.slotIndex === 'number') {
+        twinSlotIndex = data.slotIndex;
+      }
+      if (data.instance) {
+        instanceName = data.instance;
+      }
+      if (data.configPort) {
+        configPort = data.configPort;
+      }
+    }
+  } catch {
+    // discovery 失败（dev 模式 / 非 daemon 环境），使用默认值
+  }
+  // 存储实例名和配置端口，供 widget 显示
+  await plugin.storage.setSession('bridge-instance', instanceName);
+  await plugin.storage.setSession('bridge-config-port', configPort);
 
-  // 在 onActivate 中建立 WebSocket 连接（插件激活即连接，无需打开 widget）
-  wsClient = new WebSocketClient({
-    url: wsUrl,
+  // 创建 MultiConnectionManager
+  connectionManager = new MultiConnectionManager({
+    twinSlotIndex,
     pluginVersion: DEFAULT_PLUGIN_VERSION,
     sdkReady: true,
-    maxReconnectAttempts: 10,
-    initialReconnectDelay: 1000,
-    maxReconnectDelay: 30000,
-    onStatusChange: (status) => {
-      void plugin.storage.setSession('bridge-status', status);
+    onSlotsChange: (slots) => {
+      void plugin.storage.setSession('bridge-slots', slots);
     },
-    onLog: (message, level) => {
-      logBuffer.push({ time: Date.now(), message, level });
-      if (logBuffer.length > 30) logBuffer.splice(0, logBuffer.length - 30);
+    onLog: (slotIndex, message, level) => {
+      logBuffer.push({ time: Date.now(), message: `[${slotIndex}] ${message}`, level });
+      if (logBuffer.length > 50) logBuffer.splice(0, logBuffer.length - 50);
       // 合并写入：避免并发 read-modify-write 竞态
       if (!logFlushPending) {
         logFlushPending = true;
@@ -61,22 +65,15 @@ async function onActivate(plugin: ReactRNPlugin) {
     },
   });
 
-  // 路由守护进程转发的请求到 services 层
-  wsClient.setMessageHandler(createMessageRouter(plugin));
-
-  wsClient.connect();
+  // 路由守护进程转发的请求到 services 层（所有连接共享同一个 router）
+  connectionManager.setMessageHandler(createMessageRouter(plugin));
 
-  // test-scripts 已完成数据收集，不再自动运行
-  // runActionTests(plugin).catch((err) => console.error('[ACTION-TEST] 顶层错误:', err));
-  // runRichTextBuilderTest(plugin).catch((err) => console.error('[RICHTEXT-BUILDER-TEST] 顶层错误:', err));
-  // runRichTextRemainingTest(plugin).catch((err) => console.error('[RICHTEXT-REMAINING-TEST] 顶层错误:', err));
-  // runRichTextMatrixTest(plugin).catch((err) => console.error('[RICHTEXT-MATRIX-TEST] 顶层错误:', err));
-  // runPowerupRenderingTest(plugin).catch((err) => console.error('[POWERUP-RENDER] 顶层错误:', err));
+  connectionManager.start();
 }
 
 async function onDeactivate(_: ReactRNPlugin) {
-  wsClient?.disconnect();
-  wsClient = null;
+  connectionManager?.stop();
+  connectionManager = null;
 }
 
 declareIndexPlugin(onActivate, onDeactivate);

package/remnote-plugin/webpack.config.js

@@ -119,6 +119,41 @@ if (isProd) {
       'Access-Control-Allow-Origin': '*',
       'Access-Control-Allow-Headers': 'baggage, sentry-trace',
     },
+    // 劫持 /api/discovery 和 /manifest.json，与 StaticServer 行为一致
+    setupMiddlewares: (middlewares, devServer) => {
+      const instance = process.env.DISCOVERY_INSTANCE || 'default';
+
+      devServer.app.get('/api/discovery', (req, res) => {
+        res.json({
+          wsPort: parseInt(process.env.DISCOVERY_WS_PORT || '29100', 10),
+          configPort: parseInt(process.env.DISCOVERY_CONFIG_PORT || '29102', 10),
+          instance,
+          slotIndex: parseInt(process.env.DISCOVERY_SLOT_INDEX || '0', 10),
+        });
+      });
+
+      // 多实例支持：非 default 实例动态修改 manifest 的 id 和 name，
+      // 使 RemNote 能同时加载多个同源 Plugin（RemNote 按 id 去重）
+      if (instance !== 'default') {
+        devServer.app.get('/manifest.json', (req, res) => {
+          const fs = require('fs');
+          const manifestPath = path.resolve(__dirname, 'public', 'manifest.json');
+          try {
+            const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+            manifest.id = `${manifest.id}_${instance}`;
+            manifest.name = `${manifest.name} (${instance})`;
+            // webpack-dev-server 的 headers 配置不覆盖自定义路由，需手动设置 CORS
+            res.set('Access-Control-Allow-Origin', '*');
+            res.set('Cache-Control', 'no-cache, no-store, must-revalidate');
+            res.json(manifest);
+          } catch (err) {
+            res.status(500).send('manifest parse error');
+          }
+        });
+      }
+
+      return middlewares;
+    },
   };
 }
 

package/skills/remnote-bridge/SKILL.md

@@ -22,6 +22,9 @@ description: "RemNote 知识库操作指南。通过 remnote-bridge 命令行工
 | read-globe | `instructions/read-globe.md` |
 | read-context | `instructions/read-context.md` |
 | search | `instructions/search.md` |
+| addon | `instructions/addon.md` |
+| clean | `instructions/clean.md` |
+| install-skill | `instructions/install-skill.md` |
 | 全局概览 | `instructions/overall.md` |
 
 ---
@@ -89,7 +92,7 @@ RemNote 推荐的知识结构化方法：
 | **Tag** | `##` | Rem 的 tags 数组 | read-rem 的 `tags` 字段 |
 | **Portal** | `((` | 嵌入实时视图（**编辑同步**） | read-tree 标记 `type:portal refs:id1,id2` |
 
-Portal 的编辑同步意味着修改一处会影响另一处。Portal 引用的 Rem 不会被 read-tree 自动展开，需要对 refs 中的 ID 单独 read-tree。Portal 引用列表可通过 `edit-rem` 修改（str_replace 简化 JSON 中的 `portalDirectlyIncludedRem` 数组）。
+Portal 的编辑同步意味着修改一处会影响另一处。Portal 引用的 Rem 不会被 read-tree 自动展开，需要对 refs 中的 ID 单独 read-tree。Portal 引用列表可通过 `edit-rem` 修改（直接修改 changes 中的 `portalDirectlyIncludedRem` 数组）。
 
 #### Portal 操作速查
 
@@ -97,9 +100,9 @@ Portal 的编辑同步意味着修改一处会影响另一处。Portal 引用的
 |:-----|:-----|:-----|
 | 创建 Portal | `edit-tree` | 新增行 `<!--portal refs:id1,id2-->` |
 | 删除 Portal | `edit-tree` | 从大纲中移除 Portal 行（与删除普通行相同） |
-| 修改引用列表（增删引用的 Rem） | `edit-rem` | str_replace 简化 JSON 中的 `portalDirectlyIncludedRem` 数组 |
+| 修改引用列表（增删引用的 Rem） | `edit-rem` | 直接修改 changes 中的 `portalDirectlyIncludedRem` 数组 |
 | 移动 Portal（换父节点/位置） | `edit-tree` | 与移动普通行相同 |
-| 读取 Portal | `read-rem` | 自动输出 9 字段简化 JSON |
+| 读取 Portal | `read-rem` | 自动输出 8 字段简化 JSON |
 
 ### RichText 格式
 
@@ -181,7 +184,7 @@ Portal 的编辑同步意味着修改一处会影响另一处。Portal 引用的
 { "i": "a", "onlyAudio": true, "url": "https://example.com/audio.mp3" }
 ```
 
-> **注意**：在 RemObject 的格式化 JSON 中，数组内的对象会展开为多行（每个 key 一行，缩进 4+2 空格）。以上为简写——构造 edit-rem 的 oldStr/newStr 时必须使用实际的多行格式。
+> **注意**：在 RemObject 的格式化 JSON 中，数组内的对象会展开为多行（每个 key 一行，缩进 4+2 空格）。以上为简写——构造 edit-rem 的 changes 中 RichText 值时，直接传入数组即可。
 
 #### highlightColor（Rem 级别）vs h（RichText 行内）
 
@@ -192,7 +195,7 @@ Portal 的编辑同步意味着修改一处会影响另一处。Portal 引用的
 
 #### 序列化确定性
 
-RichText 对象内部按 **key 字母序排列**（`sortRichTextKeys()`），确保 JSON 始终一致。`_id` 中的 `_`（U+005F）排在所有小写字母（`a`=U+0061）之前。构造 edit-rem 的 oldStr 时必须保持相同的 key 顺序，否则匹配失败。
+RichText 对象内部按 **key 字母序排列**（`sortRichTextKeys()`），确保 JSON 始终一致。`_id` 中的 `_`（U+005F）排在所有小写字母（`a`=U+0061）之前。防线 2（乐观并发检测）依赖此确定性序列化来比较缓存与最新数据。
 
 ### Powerup 机制与噪音过滤
 
@@ -255,7 +258,7 @@ Rem 的属性（文本、类型、格式、标签）  → edit-rem   （前置
 1. 打开 RemNote 桌面端或网页端
 2. 点击左侧边栏底部的插件图标（拼图形状）
 3. 点击「开发你的插件」（Develop Your Plugin）
-4. 在输入框中填入 `http://localhost:8080`（即 connect 输出的 Plugin 服务地址）
+4. 在输入框中填入 connect 输出的 Plugin 服务地址（如 `http://localhost:29101`）
 5. 等待插件加载完成
 
 **非首次使用**（之前已加载过此插件）：
@@ -271,20 +274,15 @@ Rem 的属性（文本、类型、格式、标签）  → edit-rem   （前置
 
 #### 首次使用（setup）
 
-setup 会弹出 Chrome 窗口，用户需要完成两件事：
-1. **登录 RemNote**
-2. **配置 dev plugin**：插件图标 → 开发你的插件 → 填入 `http://localhost:8080`
+setup 会弹出 Chrome 窗口，用户只需 **登录 RemNote**，然后**彻底退出 Chrome**（macOS 必须 Cmd+Q，仅关窗口不够）。
 
-完成后**彻底退出 Chrome**（macOS 必须 Cmd+Q，仅关窗口不够）。
+setup 只负责保存登录凭证——配置 dev plugin 是 connect 之后的事（见标准模式说明）。
 
 **Agent 交互方式**：
 ```
 1. 调用 setup
 2. 立即告知用户：
-   "已打开 Chrome 浏览器。请完成以下操作：
-    1. 登录 RemNote
-    2. 在 RemNote 中配置开发插件：点击左下角插件图标 → 开发你的插件 → 输入 http://localhost:8080
-    3. 完成后彻底退出 Chrome（macOS 请按 Cmd+Q）"
+   "已打开 Chrome 浏览器。请登录 RemNote，完成后彻底退出 Chrome（macOS 请按 Cmd+Q）"
 3. 等待 setup 返回（阻塞，最长 10 分钟）
 4. 成功 → 进入下一步 connect --headless
 ```
@@ -334,14 +332,16 @@ Agent 应始终使用 JSON 模式调用命令。
 ```bash
 # 正确：位置参数 = JSON 字符串
 remnote-bridge read-rem --json '{"remId":"kLrIOHJLyMd8Y2lyA","fields":["text","type"]}'
-remnote-bridge search --json '{"query":"机器学习","numResults":10}'
+remnote-bridge search --json '{"query":"机器学习","limit":10}'
+remnote-bridge edit-rem --json '{"remId":"kLrIOHJLyMd8Y2lyA","changes":{"type":"concept"}}'
+
+# 人类模式：
+remnote-bridge edit-rem kLrIOHJLyMd8Y2lyA --changes '{"type":"concept"}'
 
 # 错误：禁止混用裸 remId + --json
 remnote-bridge read-rem kLrIOHJLyMd8Y2lyA --json   # 会失败！
 ```
 
-注意：search 的 JSON 参数名是 `numResults`（不是 `limit`）。
-
 ### 中文搜索限制（重要）
 
 search 调用 RemNote SDK 官方搜索方法，其分词基于空格分割。**中文、日文、韩文等无空格分词的语言搜索效果差**——SDK 将多字词拆为单字符 token 匹配，导致返回 0 结果或不相关结果。RemNote 本地桌面版已优化此问题，Web 版未优化。
@@ -361,7 +361,7 @@ search 调用 RemNote SDK 官方搜索方法，其分词基于空格分割。**
 
 ---
 
-## 5. 安全机制：三道防线
+## 5. 安全机制
 
 ### 防线 1：缓存存在性
 
@@ -371,9 +371,11 @@ search 调用 RemNote SDK 官方搜索方法，其分词基于空格分割。**
 
 edit 时从 SDK 重新读取最新数据，与缓存严格比较。被外部修改则拒绝编辑且**不更新缓存**——迫使 Agent 重新 read。
 
-### 防线 3：str_replace 精确匹配
+### 防线 3：str_replace 精确匹配（仅 edit-tree）
 
-`oldStr` 必须在目标文本中恰好匹配 1 次。
+`oldStr` 必须在大纲文本中恰好匹配 1 次。**仅适用于 edit-tree**。
+
+edit-rem 使用字段直接修改（changes 对象），不经过 str_replace，改为**字段白名单校验**（非法字段产生警告，枚举值非法则拒绝）。
 
 ### 缓存更新规则
 
@@ -381,7 +383,8 @@ edit 时从 SDK 重新读取最新数据，与缓存严格比较。被外部修
 |:-----|:---------|:-----------|
 | 写入成功 | 从 SDK 重新读取 → 更新缓存 | 可继续编辑 |
 | 防线 2 拒绝 / 部分写入失败 | **不更新缓存** | 必须重新 read |
-| 防线 3 拒绝 / JSON 语法错误 | 缓存保持不变 | 调整 oldStr/newStr 后**直接重试** |
+| 枚举值非法（edit-rem） | 缓存保持不变 | 检查允许的值范围后重试 |
+| 防线 3 拒绝 / JSON 语法错误（edit-tree） | 缓存保持不变 | 调整 oldStr/newStr 后**直接重试** |
 | 操作执行中异常（edit-tree） | 已执行的操作保留（**无回滚**），不更新缓存 | 必须重新 read-tree |
 
 ---
@@ -539,20 +542,21 @@ SDK bug 自动修复：移动行进入多行闪卡父节点时自动设 `isCardI
 
 ---
 
-## 8. edit-rem str_replace 要点
+## 8. edit-rem 字段修改要点
 
-操作对象是 `JSON.stringify(remObject, null, 2)` 的文本（缩进 2 空格的 JSON）。
+edit-rem 通过 `changes` 对象直接指定要修改的字段及其目标值，无需 str_replace。
 
-### 使用技巧
+### 使用方式
 
-1. **包含字段名**避免模糊匹配：`"\"type\": \"concept\""` 而非 `"concept"`
-2. 替换后必须是合法 JSON
-3. 修改 RichText 时注意 key 字母序：
+```bash
+# JSON 模式
+edit-rem --json '{"remId":"kLrIOHJLyMd8Y2lyA","changes":{"type":"concept","text":["新标题"]}}'
 
+# 人类模式
+edit-rem kLrIOHJLyMd8Y2lyA --changes '{"type":"concept","text":["新标题"]}'
 ```
-oldStr: "\"text\": [\n    \"Hello\"\n  ]"
-newStr: "\"text\": [\n    \"World\"\n  ]"
-```
+
+`changes` 对象中只需包含要修改的字段，未提及的字段保持不变。
 
 ### 21 个可编辑字段
 
@@ -573,9 +577,9 @@ tags, sources, positionAmongstSiblings, portalDirectlyIncludedRem
 | `fontSize` | `null` → 调用 `setFontSize(undefined)`（恢复普通大小） |
 | `todoStatus` | 依赖 `isTodo=true` 才生效；`null` 被跳过（清除 todo 应设 `isTodo=false`） |
 | `type` | 不可设为 `portal`（只能通过 SDK `createPortal()` 创建） |
-| `parent` + `positionAmongstSiblings` | 共享同一 SDK 调用 `setParent(parentId, position)`，**应在同一次 str_replace 中同时修改** |
+| `parent` + `positionAmongstSiblings` | 共享同一 SDK 调用 `setParent(parentId, position)`，**应在同一次 changes 中同时修改** |
 | `tags` / `sources` | **Diff 机制**：对比当前 vs 目标数组，逐项 add/remove。必须列出完整目标数组，缺少的会被删除 |
-| `portalDirectlyIncludedRem` | Portal 专用可写。**Diff 机制**：对比当前 vs 目标数组，逐项 addToPortal/removeFromPortal。仅 type=portal 时可修改。edit-rem 对 Portal 使用 9 字段简化 JSON |
+| `portalDirectlyIncludedRem` | Portal 专用可写。**Diff 机制**：对比当前 vs 目标数组，逐项 addToPortal/removeFromPortal。仅 type=portal 时可修改 |
 
 ### 常用只读字段（修改只产生警告，不生效）
 
@@ -588,8 +592,8 @@ aliases, descendants, siblingRem, isTable, portalType, propertyType
 
 | 模式 | 字段数 | 用法 |
 |:-----|:-------|:-----|
-| 默认 | 34（RW + R） | 常用场景 |
-| Portal 简化 | 9（id, type, portalType, portalDirectlyIncludedRem, parent, positionAmongstSiblings, children, createdAt, updatedAt） | type=portal 时自动切换，`--full` 和 `--fields` 可覆盖 |
+| 默认 | 33（RW + R） | 常用场景 |
+| Portal 简化 | 8（id, type, portalType, portalDirectlyIncludedRem, parent, positionAmongstSiblings, createdAt, updatedAt） | type=portal 时自动切换，`--full` 和 `--fields` 可覆盖 |
 | `--full` | 51（含低频 R-F） | 需要 Powerup 标识、时间戳等 |
 | `--fields` | 自选 + id | 精确获取特定字段 |
 
@@ -605,22 +609,23 @@ aliases, descendants, siblingRem, isTable, portalType, propertyType
 | Plugin 未连接 | RemNote 未打开 | 打开 RemNote（health 三层：daemon→Plugin→SDK 链式依赖） |
 | has not been read yet | 未先 read | 执行对应 read 命令（search 结果不算 read！） |
 | has been modified since last read | 被外部修改 | 重新 read（必须，不可直接重试） |
-| old_str not found | oldStr 不精确 | 检查引号、空格、换行、RichText key 顺序 |
-| old_str matches N locations | oldStr 不够具体 | 扩大 oldStr 范围，包含更多上下文 |
-| invalid JSON | newStr 破坏了 JSON 结构 | 检查引号、逗号、括号完整性（可直接重试） |
+| Invalid value for 'field' | 枚举字段值不合法（edit-rem） | 检查该字段允许的值范围 |
+| old_str not found | oldStr 不精确（edit-tree） | 检查引号、空格、换行 |
+| old_str matches N locations | oldStr 不够具体（edit-tree） | 扩大 oldStr 范围，包含更多上下文 |
 | content_modified | edit-tree 中改了行内容 | 用 edit-rem |
 | orphan_detected | 删了父但留了子 | 同时删除所有子行 |
 | folded_delete | 删了有隐藏子节点的行 | 用更大 depth 重新 read-tree |
 | elided_modified | 删/改了省略占位符 | 用更大 depth/maxSiblings 重新 read-tree |
 | indent_skip | 缩进跳级（如 0→4 空格） | 每级 2 空格，不可跳级 |
 | children_captured | 新行劫持已有子节点 | 把新行插到兄弟末尾 |
-| old_str not found in simplified Portal JSON | Portal 编辑时 oldStr 不匹配简化 JSON | 检查 Portal 简化 JSON 格式 |
 | Rem not found | remId 无效或已删除 | 用 search 重新定位 |
 
 ---
 
 ## 10. 配置
 
-配置文件：`.remnote-bridge.json`（项目根目录）
+配置文件：`~/.remnote-bridge/config.json`（全局目录，所有实例共享）
+
+端口由槽位自动分配（槽位 0: 29100/29101/29102，槽位 1: 29110/29111/29112，以此类推），最多 4 个并发实例。
 
-关键默认值：WS 端口 3002、dev-server 8080、config 3003、超时 30 分钟、maxNodes 200、maxSiblings 20、readTreeDepth 3、readGlobeDepth -1（无限）、缓存上限 200 条。
+关键默认值：超时 30 分钟、maxNodes 200、maxSiblings 20、readTreeDepth 3、readGlobeDepth -1（无限）、缓存上限 200 条。

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

@@ -0,0 +1,134 @@
+# addon
+
+> 管理增强项目（addon）：查看状态、安装、卸载。
+
+---
+
+## 功能
+
+`addon` 命令组管理 remnote-bridge 的增强项目（如 `remnote-rag` 语义搜索）。增强项目是独立安装的可选组件，扩展核心功能。
+
+三个子命令：
+
+| 子命令 | 功能 |
+|:-------|:-----|
+| `addon list` | 查看所有可用增强项目的状态 |
+| `addon install <name>` | 安装并启用指定增强项目 |
+| `addon uninstall <name>` | 卸载指定增强项目 |
+
+---
+
+## 用法
+
+### 人类模式
+
+```bash
+# 查看所有增强项目
+remnote-bridge addon list
+
+# 安装增强项目
+remnote-bridge addon install remnote-rag
+
+# 卸载增强项目
+remnote-bridge addon uninstall remnote-rag
+
+# 卸载并清理数据目录
+remnote-bridge addon uninstall remnote-rag --purge
+```
+
+### JSON 模式
+
+```bash
+remnote-bridge --json addon list
+remnote-bridge --json addon install remnote-rag
+remnote-bridge --json addon uninstall remnote-rag
+```
+
+---
+
+## JSON 输出
+
+### addon list
+
+```json
+{
+  "ok": true,
+  "command": "addon-list",
+  "addons": [
+    {
+      "name": "remnote-rag",
+      "enabled": true,
+      "installed": true,
+      "settingsValid": true,
+      "missingSettings": [],
+      "description": "语义搜索增强"
+    }
+  ]
+}
+```
+
+### addon install（成功）
+
+```json
+{
+  "ok": true,
+  "command": "addon-install",
+  "name": "remnote-rag",
+  "action": "installed"
+}
+```
+
+### addon install（已安装）
+
+```json
+{
+  "ok": true,
+  "command": "addon-install",
+  "name": "remnote-rag",
+  "action": "already-installed"
+}
+```
+
+### addon uninstall
+
+```json
+{
+  "ok": true,
+  "command": "addon-uninstall",
+  "name": "remnote-rag",
+  "purged": false
+}
+```
+
+### 失败
+
+```json
+{
+  "ok": false,
+  "command": "addon-install",
+  "name": "unknown-addon",
+  "error": "未知的增强项目: unknown-addon。可用项目: remnote-rag"
+}
+```
+
+---
+
+## 退出码
+
+| 退出码 | 含义 |
+|:-------|:-----|
+| 0 | 操作成功 |
+| 1 | 操作失败（未知名称、安装/卸载错误等） |
+
+---
+
+## 幂等性
+
+- `addon install`：已安装时返回 `action: "already-installed"`，自动标记为启用
+- `addon uninstall`：已卸载时安全返回
+
+---
+
+## 配置依赖
+
+增强项目的启用/禁用状态保存在全局配置 `~/.remnote-bridge/config.json` 中。每个 addon 的独立配置存储在 `~/.remnote-bridge/addons/<name>/config.json` 中。安装后需要在配置页面或配置文件中填写必需的配置项（如 API Key）。

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

@@ -0,0 +1,110 @@
+# clean
+
+> 清理所有 daemon 进程、PID 文件、日志、注册表和 addon 数据。
+
+---
+
+## 功能
+
+`clean` 执行全面清理，适用于系统状态异常或需要彻底重置的场景。
+
+按顺序执行以下清理步骤：
+
+1. **停止所有运行中的 daemon**（遍历注册表，SIGTERM → 5 秒后 SIGKILL）
+2. **清理实例文件**（`~/.remnote-bridge/instances/` 下的 PID 和日志文件）
+3. **清理注册表**（`~/.remnote-bridge/registry.json`）
+4. **清理旧版项目根文件**（`.remnote-bridge.pid`、`.remnote-bridge.log`、`.remnote-bridge.json`，向后兼容）
+5. **清理已安装的 Skill**（`~/.claude/skills/remnote-bridge/`）
+6. **清理 addon 数据目录**（如 remnote-rag 的索引数据）
+
+---
+
+## 用法
+
+### 人类模式
+
+```bash
+remnote-bridge clean
+```
+
+输出示例：
+
+```
+  已删除: /Users/xxx/.remnote-bridge/instances/0.pid
+  已删除: /Users/xxx/.remnote-bridge/instances/0.log
+  已删除: /Users/xxx/.remnote-bridge/registry.json
+
+清理完成，共删除 3 项
+```
+
+### JSON 模式
+
+```bash
+remnote-bridge --json clean
+```
+
+---
+
+## JSON 输出
+
+### 清理成功
+
+```json
+{
+  "ok": true,
+  "command": "clean",
+  "removed": [
+    "/Users/xxx/.remnote-bridge/instances/0.pid",
+    "/Users/xxx/.remnote-bridge/instances/0.log",
+    "/Users/xxx/.remnote-bridge/registry.json"
+  ]
+}
+```
+
+### 部分失败
+
+```json
+{
+  "ok": false,
+  "command": "clean",
+  "removed": ["/Users/xxx/.remnote-bridge/instances/0.pid"],
+  "errors": ["删除失败: /Users/xxx/.remnote-bridge/instances/0.log — EPERM"]
+}
+```
+
+### 无需清理
+
+```json
+{
+  "ok": true,
+  "command": "clean",
+  "removed": []
+}
+```
+
+---
+
+## 退出码
+
+| 退出码 | 含义 |
+|:-------|:-----|
+| 0 | 清理完成（包括无需清理的情况） |
+
+---
+
+## 适用场景
+
+| 场景 | 说明 |
+|:-----|:-----|
+| daemon 进程残留 | `disconnect` 无法正常停止时 |
+| 端口被占用 | 多次启动失败后的端口残留 |
+| 注册表损坏 | 注册表文件不一致时重置 |
+| 完整重装 | 清除所有状态从零开始 |
+
+---
+
+## AI Agent 注意事项
+
+- `clean` 是**破坏性操作**——会停止所有 daemon、清空所有缓存和注册表
+- 执行 `clean` 后需要重新 `connect` 才能继续操作
+- 通常只在排查问题或重置环境时使用，正常流程不需要