remnote-bridge 0.1.11 → 0.1.13

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

@@ -8,16 +8,47 @@
 
 `connect` 以 fork 子进程方式启动后台守护进程（daemon），daemon 内部启动三个服务：
 
-| 服务 | 默认端口 | 用途 |
-|------|----------|------|
-| WS Server | 3002 | CLI 命令 ↔ daemon ↔ Plugin 的双向通信 |
-| Plugin 服务 | 8080 | 将 remnote-plugin 加载到 RemNote 浏览器（默认静态服务器，`--dev` 时为 webpack-dev-server） |
-| ConfigServer | 3003 | HTTP 配置管理界面 |
+| 服务 | 槽位 0 端口 | 用途 |
+|------|------------|------|
+| WS Server | 29100 | CLI 命令 ↔ daemon ↔ Plugin 的双向通信 |
+| Plugin 服务 | 29101 | 将 remnote-plugin 加载到 RemNote 浏览器（默认静态服务器，`--dev` 时为 webpack-dev-server） |
+| ConfigServer | 29102 | HTTP 配置管理界面 |
 
 daemon 启动后脱离父进程（detached），CLI 进程退出但 daemon 继续运行。
 
 ---
 
+## 多实例支持（`--instance`）
+
+`connect` 支持通过 `--instance <name>` 启动多个独立的 daemon 实例，每个实例连接不同的 RemNote 知识库。
+
+```bash
+# 默认实例
+remnote-bridge connect
+
+# 指定实例名
+remnote-bridge connect --instance work
+remnote-bridge connect --instance personal
+
+# JSON 模式
+remnote-bridge --json connect --instance work
+```
+
+**槽位机制**：系统最多支持 4 个并发实例，每个实例占用一个槽位（固定端口组）：
+
+| 槽位 | WS 端口 | Plugin 服务端口 | 配置端口 |
+|:-----|:--------|:---------------|:---------|
+| 0 | 29100 | 29101 | 29102 |
+| 1 | 29110 | 29111 | 29112 |
+| 2 | 29120 | 29121 | 29122 |
+| 3 | 29130 | 29131 | 29132 |
+
+**实例名解析优先级**：CLI `--instance` 参数 > 环境变量 `REMNOTE_BRIDGE_INSTANCE` > 默认值 `default`。Headless 模式下固定为 `headless`。
+
+**首次使用多实例时**，用户需在 RemNote 中为每个实例分别配置 dev plugin URL（对应各自的 Plugin 服务端口）。
+
+---
+
 ## 两种模式
 
 ### 标准模式（默认）
@@ -56,7 +87,7 @@ Headless 模式下 Plugin 可能需要 10-30 秒才能连接到 daemon，使用
 1. 打开 RemNote 桌面端或网页端
 2. 点击左侧边栏底部的插件图标（拼图形状）
 3. 点击「开发你的插件」（Develop Your Plugin）
-4. 在输入框中填入 `http://localhost:8080`（即 connect 输出的 Plugin 服务地址）
+4. 在输入框中填入 connect 输出的 Plugin 服务地址（如 `http://localhost:29101`）
 5. 等待插件加载完成
 
 ### 非首次使用（之前已加载过此插件）
@@ -82,10 +113,11 @@ remnote-bridge connect
 输出示例：
 
 ```
-守护进程已启动（PID: 12345）
-  WS Server:         ws://127.0.0.1:3002
-  Plugin 服务:       http://localhost:8080
-  配置页面:          http://127.0.0.1:3003
+正在启动守护进程（实例: default，槽位: 0）...
+守护进程已启动（PID: 12345，实例: default）
+  WS Server:         ws://127.0.0.1:29100
+  Plugin 服务:       http://localhost:29101
+  配置页面:          http://127.0.0.1:29102
   超时: 30 分钟无 CLI 交互后自动关闭
 ```
 
@@ -106,11 +138,15 @@ remnote-bridge --json connect
   "ok": true,
   "command": "connect",
   "alreadyRunning": false,
+  "instance": "default",
   "pid": 12345,
-  "wsPort": 3002,
-  "devServerPort": 8080,
-  "configPort": 3003,
+  "wsPort": 29100,
+  "devServerPort": 29101,
+  "configPort": 29102,
+  "slotIndex": 0,
   "timeoutMinutes": 30,
+  "headless": false,
+  "portChanged": false,
   "timestamp": "2026-03-06T10:00:00.000Z"
 }
 ```
@@ -122,9 +158,12 @@ remnote-bridge --json connect
   "ok": true,
   "command": "connect",
   "alreadyRunning": true,
+  "instance": "default",
   "pid": 12345,
-  "wsPort": 3002,
-  "devServerPort": 8080,
+  "wsPort": 29100,
+  "devServerPort": 29101,
+  "configPort": 29102,
+  "slotIndex": 0,
   "timestamp": "2026-03-06T10:00:00.000Z"
 }
 ```
@@ -135,8 +174,7 @@ remnote-bridge --json connect
 {
   "ok": false,
   "command": "connect",
-  "error": "守护进程启动超时（60 秒）",
-  "timestamp": "2026-03-06T10:00:00.000Z"
+  "error": "已达最大实例数上限（4），无可用槽位"
 }
 ```
 
@@ -145,24 +183,28 @@ remnote-bridge --json connect
 ## 启动流程
 
 ```
-1. 检查 PID 文件 (.remnote-bridge.pid)
-   ├─ 已在运行 → 返回 ok + alreadyRunning: true
-   └─ 未运行 / stale PID → 继续
+1. 解析实例名（--instance / 环境变量 / 默认 'default'）
+
+2. 加载注册表，清理过期槽位
+   ├─ 实例已在运行 → 返回 ok + alreadyRunning: true
+   └─ 未运行 → 继续
+
+3. 分配槽位（第一个空闲槽位）
+   ├─ 无空闲 → 报错 "已达最大实例数上限（4）"
+   └─ 有空闲 → 占位
 
-2. fork 守护进程（detached, stdio 全部 ignore）
+4. fork 守护进程（detached, 传入 SLOT_INDEX / SLOT_WS_PORT 等环境变量）
 
-3. daemon 内部按顺序启动：
+5. daemon 内部按顺序启动：
    ├─ WS Server（必须成功，否则 daemon 退出）
    ├─ ConfigServer（非关键，失败不阻塞）
-   └─ Plugin 服务（默认静态服务器；--dev 时为 webpack-dev-server + 依赖自动安装 + 崩溃重试）
+   └─ Plugin 服务（默认静态服务器；--dev 时为 webpack-dev-server）
 
-4. daemon 写入 PID 文件
+6. daemon 通过 IPC 发送 ready 信号给父进程
 
-5. daemon 通过 IPC 发送 ready 信号给父进程
-
-6. 父进程（CLI）收到 ready → 输出结果 → 退出
-   ├─ 60 秒内未收到 → 超时失败
-   └─ 收到 error → 启动失败
+7. 父进程（CLI）收到 ready → 更新注册表 → 输出结果 → 退出
+   ├─ 60 秒内未收到 → 超时失败，释放槽位
+   └─ 收到 error → 启动失败，释放槽位
 ```
 
 ---
@@ -172,7 +214,7 @@ remnote-bridge --json connect
 - **默认模式秒级启动**：使用预构建 plugin，无需安装依赖
 - **`--dev` 模式首次较慢**：会自动安装 remnote-plugin 的依赖（约 600+ 个包），在 Windows 上可能需要 30-60 秒。connect 命令的超时为 60 秒
 - **`--dev` 依赖自动修复**：如果 webpack-dev-server 因依赖损坏而崩溃，daemon 会自动执行清洁重装（删除 node_modules + package-lock.json 后重新安装）并重试，最多重试 2 次，无需手动干预
-- **端口残留**：多次 connect 失败后可能出现端口被占用（`EADDRINUSE`），先执行 `remnote-bridge disconnect`，如仍有残留可通过 `netstat -ano | findstr 3002` 定位 PID 后 `taskkill /F /PID <pid>` 强制终止
+- **端口残留**：多次 connect 失败后可能出现端口被占用（`EADDRINUSE`），先执行 `remnote-bridge disconnect`（或 `remnote-bridge clean` 清理所有实例），如仍有残留可通过 `netstat -ano | findstr 29100` 定位 PID 后 `taskkill /F /PID <pid>` 强制终止
 
 ---
 
@@ -180,7 +222,7 @@ remnote-bridge --json connect
 
 daemon 启动后开始计时，默认 **30 分钟无 CLI 交互**自动关闭（执行优雅 shutdown）。每次收到 CLI 请求时重置计时器。
 
-超时时间可通过配置文件 `.remnote-bridge.json` 的 `daemonTimeoutMinutes` 字段调整。
+超时时间可通过配置文件 `~/.remnote-bridge/config.json` 的 `daemonTimeoutMinutes` 字段调整。
 
 ---
 
@@ -203,12 +245,11 @@ daemon 启动后开始计时，默认 **30 分钟无 CLI 交互**自动关闭（
 
 | 配置项 | 默认值 | 说明 |
 |--------|--------|------|
-| wsPort | 3002 | WS Server 监听端口 |
-| devServerPort | 8080 | Plugin 服务端口 |
-| configPort | 3003 | ConfigServer 端口 |
 | daemonTimeoutMinutes | 30 | 无活动自动关闭的分钟数 |
 
-三个端口不允许冲突（配置加载时校验）。
+端口由槽位自动分配（29100/29110/29120/29130 系列），通过 `~/.remnote-bridge/slots.json` 自定义。
+
+配置文件位置：`~/.remnote-bridge/config.json`（全局配置，所有实例共享）。
 
 ---
 
@@ -216,5 +257,7 @@ daemon 启动后开始计时，默认 **30 分钟无 CLI 交互**自动关闭（
 
 | 文件 | 位置 | 生命周期 |
 |------|------|----------|
-| `.remnote-bridge.pid` | 项目根目录 | daemon 运行期间存在，关闭时删除 |
-| `.remnote-bridge.log` | 项目根目录 | 追加写入，跨会话保留 |
+| `{slotIndex}.pid` | `~/.remnote-bridge/instances/` | daemon 运行期间存在，关闭时删除 |
+| `{slotIndex}.log` | `~/.remnote-bridge/instances/` | 追加写入，跨会话保留 |
+| `registry.json` | `~/.remnote-bridge/` | 记录实例→槽位映射，进程退出后自动清理 |
+| `slots.json` | `~/.remnote-bridge/` | 槽位端口定义，不存在时自动生成默认值 |

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

@@ -6,14 +6,26 @@
 
 ## 功能
 
-`disconnect` 向守护进程发送 SIGTERM 信号，触发优雅关闭：
+`disconnect` 向指定实例的守护进程发送 SIGTERM 信号，触发优雅关闭：
 
 1. 关闭 WS Server（断开所有连接）
 2. 关闭 ConfigServer
 3. 停止 Plugin 服务（静态文件服务器 或 webpack-dev-server）
-4. 删除 PID 文件
+4. 删除 PID 文件，释放注册表槽位
 5. 内存缓存随进程退出自动消失
 
+### 多实例支持
+
+通过 `--instance <name>` 指定要停止的实例。不指定时停止 `default` 实例。
+
+```bash
+# 停止默认实例
+remnote-bridge disconnect
+
+# 停止指定实例
+remnote-bridge disconnect --instance work
+```
+
 ---
 
 ## 用法
@@ -48,9 +60,9 @@ remnote-bridge --json disconnect
   "ok": true,
   "command": "disconnect",
   "wasRunning": true,
+  "instance": "default",
   "pid": 12345,
-  "forced": false,
-  "timestamp": "2026-03-06T10:00:00.000Z"
+  "forced": false
 }
 ```
 
@@ -61,9 +73,9 @@ remnote-bridge --json disconnect
   "ok": true,
   "command": "disconnect",
   "wasRunning": true,
+  "instance": "work",
   "pid": 12345,
-  "forced": true,
-  "timestamp": "2026-03-06T10:00:00.000Z"
+  "forced": true
 }
 ```
 
@@ -74,7 +86,7 @@ remnote-bridge --json disconnect
   "ok": true,
   "command": "disconnect",
   "wasRunning": false,
-  "timestamp": "2026-03-06T10:00:00.000Z"
+  "instance": "default"
 }
 ```
 
@@ -116,8 +128,9 @@ daemon 收到 SIGTERM 后依次执行：
 | **缓存清空** | 所有 `rem:*` 和 `tree:*` 缓存随 daemon 进程退出消失 |
 | **Plugin 断开** | WS 连接关闭，Plugin 进入重连循环（指数退避） |
 | **端口释放** | wsPort / devServerPort / configPort 全部释放 |
-| **PID 文件删除** | `.remnote-bridge.pid` 被删除 |
-| **日志保留** | `.remnote-bridge.log` 保留（追加写入，不删除） |
+| **PID 文件删除** | `~/.remnote-bridge/instances/{slotIndex}.pid` 被删除 |
+| **注册表释放** | 实例对应的槽位在 `registry.json` 中释放 |
+| **日志保留** | `~/.remnote-bridge/instances/{slotIndex}.log` 保留 |
 
 ---