remnote-bridge 0.1.7 → 0.1.8

package/remnote-plugin/dist/manifest.json

@@ -0,0 +1,22 @@
+{
+  "manifestVersion": 1,
+  "id": "unofficial_remnote_bridge",
+  "name": "Unofficial RemNote Bridge",
+  "author": "baobao700508",
+  "repoUrl": "https://github.com/baobao700508/unofficial-remnote-bridge-cli",
+  "version": {
+    "major": 0,
+    "minor": 1,
+    "patch": 0
+  },
+  "theme": [],
+  "enableOnMobile": false,
+  "description": "Unofficial RemNote Bridge 桥接插件：通过 WebSocket 将 RemNote API 暴露给外部 CLI/MCP 调用",
+  "requestNative": false,
+  "requiredScopes": [
+    {
+      "type": "All",
+      "level": "ReadCreateModifyDelete"
+    }
+  ]
+}

package/skills/remnote-bridge/SKILL.md

@@ -11,6 +11,7 @@ description: "RemNote 知识库操作指南。通过 remnote-bridge 命令行工
 
 | 命令 | 文档路径 |
 |:-----|:---------|
+| setup | `instructions/setup.md` |
 | connect | `instructions/connect.md` |
 | disconnect | `instructions/disconnect.md` |
 | health | `instructions/health.md` |
@@ -246,15 +247,15 @@ Rem 的属性（文本、类型、格式、标签）  → edit-rem   （前置
 
 ## 3. 标准工作流
 
-### ⚠️ connect 后需要用户配合（重要）
+### ⚠️ 标准模式：connect 后需要用户配合
 
-`connect` 成功只意味着 daemon 和 webpack-dev-server 已启动，**Plugin 并未自动连接**。用户必须在 RemNote 中完成操作，Plugin 才能连接到 daemon：
+`connect` 成功只意味着 daemon 和 Plugin 服务已启动，**Plugin 并未自动连接**。用户必须在 RemNote 中完成操作，Plugin 才能连接到 daemon：
 
 **首次使用**（RemNote 从未加载过此插件）：
 1. 打开 RemNote 桌面端或网页端
 2. 点击左侧边栏底部的插件图标（拼图形状）
 3. 点击「开发你的插件」（Develop Your Plugin）
-4. 在输入框中填入 `http://localhost:8080`（即 connect 输出的 webpack-dev-server 地址）
+4. 在输入框中填入 `http://localhost:8080`（即 connect 输出的 Plugin 服务地址）
 5. 等待插件加载完成
 
 **非首次使用**（之前已加载过此插件）：
@@ -262,7 +263,50 @@ Rem 的属性（文本、类型、格式、标签）  → edit-rem   （前置
 
 **你必须**：执行 `connect` 后，**立即告知用户需要完成上述操作**，不要直接调用业务命令。引导用户完成后，用 `health` 确认三层就绪再继续。
 
-### 完整流程
+### Headless 模式：自动连接
+
+标准模式每次 connect 后都需要用户手动操作 RemNote。Headless 模式通过 setup（一次性）+ headless Chrome 实现自动连接，后续 connect 无需用户介入。
+
+#### 首次使用（setup）
+
+setup 会弹出 Chrome 窗口，用户需要完成两件事：
+1. **登录 RemNote**
+2. **配置 dev plugin**：插件图标 → 开发你的插件 → 填入 `http://localhost:8080`
+
+完成后**彻底退出 Chrome**（macOS 必须 Cmd+Q，仅关窗口不够）。
+
+**Agent 交互方式**：
+```
+1. 调用 setup
+2. 立即告知用户：
+   "已打开 Chrome 浏览器。请完成以下操作：
+    1. 登录 RemNote
+    2. 在 RemNote 中配置开发插件：点击左下角插件图标 → 开发你的插件 → 输入 http://localhost:8080
+    3. 完成后彻底退出 Chrome（macOS 请按 Cmd+Q）"
+3. 等待 setup 返回（阻塞，最长 10 分钟）
+4. 成功 → 进入下一步 connect --headless
+```
+
+setup 只需执行一次。之后每次连接直接用 `connect --headless`。
+
+#### 后续使用（connect --headless）
+
+```
+1. connect --headless   -- 启动 daemon + headless Chrome 自动加载 RemNote 和 Plugin
+2. health               -- 等待三层就绪（Plugin 需要 10-30 秒连接，可多次轮询）
+3. 业务操作
+4. disconnect           -- 结束会话
+```
+
+**无需任何用户操作**——headless Chrome 在后台自动完成登录和 Plugin 加载。
+
+#### 排查
+
+- `health --diagnose`：截图 + Chrome 状态 + console 错误（确认页面是否正常加载）
+- `health --reload`：重载 headless Chrome 页面（Plugin 未连接时尝试）
+- 如果 Plugin 始终不连接，可能是 RemNote 登录 session 过期，需重新 setup
+
+### 完整流程（标准模式）
 
 ```
 1. connect              -- 启动会话（幂等，重复调用安全）

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

@@ -11,23 +11,52 @@
 | 服务 | 默认端口 | 用途 |
 |------|----------|------|
 | WS Server | 3002 | CLI 命令 ↔ daemon ↔ Plugin 的双向通信 |
-| webpack-dev-server | 8080 | 将 remnote-plugin 热加载到 RemNote 浏览器 |
+| Plugin 服务 | 8080 | 将 remnote-plugin 加载到 RemNote 浏览器（默认静态服务器，`--dev` 时为 webpack-dev-server） |
 | ConfigServer | 3003 | HTTP 配置管理界面 |
 
 daemon 启动后脱离父进程（detached），CLI 进程退出但 daemon 继续运行。
 
 ---
 
-## ⚠️ connect 后需要用户配合
+## 两种模式
 
-`connect` 成功只意味着 daemon 和 webpack-dev-server 已启动，**Plugin 并未自动连接**。用户必须在 RemNote 中完成以下操作：
+### 标准模式（默认）
+
+启动 daemon 后需要用户手动在 RemNote 中加载 Plugin。适用于用户已打开 RemNote 的场景。
+
+### Headless 模式（`--headless`）
+
+自动启动 headless Chrome 加载 Plugin，无需用户操作。适用于无 GUI 环境或全自动连接场景。
+
+**前置条件**：必须先执行 `setup` 完成 RemNote 登录。
+
+```bash
+# 首次：先 setup 登录
+remnote-bridge setup
+
+# 然后启动 headless 连接
+remnote-bridge connect --headless
+
+# JSON 模式
+remnote-bridge --json connect --headless
+```
+
+Headless 模式下 Plugin 可能需要 10-30 秒才能连接到 daemon，使用 `health` 确认就绪。
+
+排查工具：`health --diagnose`（截图+状态+console 错误）、`health --reload`（重载 Chrome 页面）。
+
+---
+
+## ⚠️ 标准模式：connect 后需要用户配合
+
+`connect`（不传 `--headless`）成功只意味着 daemon 和 Plugin 服务已启动，**Plugin 并未自动连接**。用户必须在 RemNote 中完成以下操作：
 
 ### 首次使用（RemNote 从未加载过此插件）
 
 1. 打开 RemNote 桌面端或网页端
 2. 点击左侧边栏底部的插件图标（拼图形状）
 3. 点击「开发你的插件」（Develop Your Plugin）
-4. 在输入框中填入 `http://localhost:8080`（即 connect 输出的 webpack-dev-server 地址）
+4. 在输入框中填入 `http://localhost:8080`（即 connect 输出的 Plugin 服务地址）
 5. 等待插件加载完成
 
 ### 非首次使用（之前已加载过此插件）
@@ -55,7 +84,7 @@ remnote-bridge connect
 ```
 守护进程已启动（PID: 12345）
   WS Server:         ws://127.0.0.1:3002
-  webpack-dev-server: http://localhost:8080
+  Plugin 服务:       http://localhost:8080
   配置页面:          http://127.0.0.1:3003
   超时: 30 分钟无 CLI 交互后自动关闭
 ```
@@ -125,7 +154,7 @@ remnote-bridge --json connect
 3. daemon 内部按顺序启动：
    ├─ WS Server（必须成功，否则 daemon 退出）
    ├─ ConfigServer（非关键，失败不阻塞）
-   └─ webpack-dev-server（含依赖自动安装 + 崩溃重试）
+   └─ Plugin 服务（默认静态服务器；--dev 时为 webpack-dev-server + 依赖自动安装 + 崩溃重试）
 
 4. daemon 写入 PID 文件
 
@@ -140,8 +169,9 @@ remnote-bridge --json connect
 
 ## Windows 注意事项
 
-- **首次 connect 较慢**：daemon 启动时会自动安装 remnote-plugin 的依赖（约 600+ 个包），在 Windows 上可能需要 30-60 秒。connect 命令的超时为 60 秒
-- **依赖自动修复**：如果 webpack-dev-server 因依赖损坏而崩溃，daemon 会自动执行清洁重装（删除 node_modules + package-lock.json 后重新安装）并重试，最多重试 2 次，无需手动干预
+- **默认模式秒级启动**：使用预构建 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>` 强制终止
 
 ---
@@ -165,7 +195,7 @@ daemon 启动后开始计时，默认 **30 分钟无 CLI 交互**自动关闭（
 | 退出码 | 含义 |
 |--------|------|
 | 0 | 启动成功，或已在运行 |
-| 1 | 启动失败（超时、端口冲突、webpack-dev-server 异常等） |
+| 1 | 启动失败（超时、端口冲突、Plugin 服务异常等） |
 
 ---
 
@@ -174,7 +204,7 @@ daemon 启动后开始计时，默认 **30 分钟无 CLI 交互**自动关闭（
 | 配置项 | 默认值 | 说明 |
 |--------|--------|------|
 | wsPort | 3002 | WS Server 监听端口 |
-| devServerPort | 8080 | webpack-dev-server 端口 |
+| devServerPort | 8080 | Plugin 服务端口 |
 | configPort | 3003 | ConfigServer 端口 |
 | daemonTimeoutMinutes | 30 | 无活动自动关闭的分钟数 |
 

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

@@ -10,7 +10,7 @@
 
 1. 关闭 WS Server（断开所有连接）
 2. 关闭 ConfigServer
-3. 停止 webpack-dev-server 子进程
+3. 停止 Plugin 服务（静态文件服务器 或 webpack-dev-server）
 4. 删除 PID 文件
 5. 内存缓存随进程退出自动消失
 

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

@@ -57,6 +57,18 @@ remnote-bridge health
 remnote-bridge --json health
 ```
 
+### Headless 诊断模式
+
+```bash
+# 截图 + 详细状态 + console 错误 + 排查建议
+remnote-bridge health --diagnose
+
+# 重载 headless Chrome 页面
+remnote-bridge health --reload
+```
+
+`--diagnose` 和 `--reload` 不能同时使用，仅在 headless 模式下可用。
+
 ---
 
 ## JSON 输出
@@ -149,11 +161,65 @@ daemon 运行 → Plugin 连接 → SDK 就绪
 
 ---
 
+## Headless 模式附加输出
+
+### health 基础输出（headless 模式下额外字段）
+
+headless 模式下 `health` 基础输出额外包含 `headless` 对象：
+
+```json
+{
+  "ok": true,
+  "command": "health",
+  "exitCode": 0,
+  "daemon": { "running": true, "pid": 12345, "reachable": true, "uptime": 300 },
+  "plugin": { "connected": true },
+  "sdk": { "ready": true },
+  "timeoutRemaining": 1500,
+  "headless": {
+    "status": "running",
+    "chromeConnected": true,
+    "pageUrl": "http://localhost:8080",
+    "reloadCount": 0,
+    "lastError": null,
+    "recentConsoleErrors": []
+  }
+}
+```
+
+### --diagnose 输出
+
+```json
+{
+  "ok": true,
+  "command": "health",
+  "mode": "diagnose",
+  "headless": { "status": "running", "chromeConnected": true, "pageUrl": "...", "reloadCount": 0, "lastError": null, "recentConsoleErrors": [] },
+  "screenshotPath": "/Users/xxx/.remnote-bridge/headless-screenshot-1234567890.png",
+  "pluginConnected": true,
+  "sdkReady": true
+}
+```
+
+### --reload 输出
+
+```json
+{
+  "ok": true,
+  "command": "health",
+  "mode": "reload"
+}
+```
+
+---
+
 ## 常见问题诊断
 
 | 症状 | 可能原因 | 解决方案 |
 |------|----------|----------|
 | daemon 未运行 | 未执行 connect / 已超时关闭 | 执行 `connect` |
 | daemon 运行但不可达 | WS 端口被占用或配置不匹配 | 检查 `.remnote-bridge.json` 中的 `wsPort` |
-| Plugin 未连接 | RemNote 未打开 / Plugin 未安装 / URL 不匹配 | 打开 RemNote，确认 Plugin 中的 WS URL 设置 |
+| Plugin 未连接（标准模式） | RemNote 未打开 / Plugin 未安装 / URL 不匹配 | 打开 RemNote，确认 Plugin 中的 WS URL 设置 |
+| Plugin 未连接（headless 模式） | Chrome 页面加载异常 | `health --diagnose` 查看截图和状态，`health --reload` 重载页面 |
 | SDK 未就绪 | 知识库加载中 / Plugin 异常 | 等待几秒后重试，或刷新 RemNote 页面 |
+| Chrome 状态 crashed | headless Chrome 崩溃或断开 | `health --reload` 尝试恢复，或 disconnect + connect --headless 重启 |

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

@@ -206,7 +206,7 @@ disconnect → daemon 关闭 → 会话结束，缓存清空
 | 服务 | 默认端口 | 用途 |
 |:-----|:---------|:-----|
 | WS Server | 3002 | CLI ↔ daemon ↔ Plugin 通信 |
-| webpack-dev-server | 8080 | 热加载 Plugin 到 RemNote |
+| Plugin 服务 | 8080 | 加载 Plugin 到 RemNote（默认静态服务器，`--dev` 时为 webpack-dev-server） |
 | ConfigServer | 3003 | HTTP 配置界面 |
 
 超时机制：daemon 默认 **30 分钟无活动**自动关闭。每次收到 CLI 请求时重置计时器。

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

@@ -0,0 +1,130 @@
+# setup
+
+> 启动 Chrome 浏览器让用户登录 RemNote，保存登录凭证到本地 profile。这是 headless 模式（`connect --headless`）的前置步骤。
+
+---
+
+## 功能
+
+`setup` 启动一个有界面的 Chrome 窗口（使用独立 profile 目录 `~/.remnote-bridge/chrome-profile`），打开 RemNote 登录页面。用户在浏览器中完成登录后关闭 Chrome，命令写入 `.setup-done` 标记并返回。
+
+后续 `connect --headless` 使用相同 profile 目录，复用已保存的登录凭证，实现免登录的 headless 连接。
+
+---
+
+## 前置条件
+
+- 需要**桌面环境（GUI）**，无 GUI 环境会报错
+- 需要系统安装 Chrome/Chromium
+
+---
+
+## 用法
+
+### 人类模式
+
+```bash
+remnote-bridge setup
+```
+
+输出示例：
+
+```
+正在启动 Chrome...
+请在浏览器中登录 RemNote，完成后关闭浏览器窗口。
+setup 完成！
+  profile 目录: /Users/xxx/.remnote-bridge/chrome-profile
+现在可以使用 `remnote-bridge connect --headless` 启动无头连接。
+```
+
+### JSON 模式
+
+```bash
+remnote-bridge --json setup
+```
+
+---
+
+## JSON 输出
+
+### 首次 setup
+
+```json
+{
+  "ok": true,
+  "command": "setup",
+  "profileDir": "/Users/xxx/.remnote-bridge/chrome-profile",
+  "alreadyDone": false
+}
+```
+
+### 已完成 setup
+
+```json
+{
+  "ok": true,
+  "command": "setup",
+  "profileDir": "/Users/xxx/.remnote-bridge/chrome-profile",
+  "alreadyDone": true
+}
+```
+
+### 失败
+
+```json
+{
+  "ok": false,
+  "command": "setup",
+  "error": "未检测到桌面环境（无 DISPLAY/WAYLAND_DISPLAY），setup 需要 GUI 才能登录"
+}
+```
+
+---
+
+## AI Agent 使用流程
+
+setup 会弹出 Chrome 窗口，用户需要完成两件事：登录 RemNote + 配置 dev plugin。
+
+### 交互步骤
+
+1. 调用 `setup`
+2. **立即告知用户**：
+   > 已打开 Chrome 浏览器。请完成以下操作：
+   > 1. 登录 RemNote
+   > 2. 在 RemNote 中配置开发插件：点击左下角插件图标 → 开发你的插件 → 输入 `http://localhost:8080`
+   > 3. 完成后彻底退出 Chrome（macOS 请按 Cmd+Q，仅关窗口不够）
+3. 等待 `setup` 命令返回（阻塞式，超时 600 秒）
+4. 收到成功 → 继续执行 `connect --headless`
+
+### setup 之后
+
+`setup` 只需执行一次。登录凭证和 plugin 配置都已保存，之后每次只需 `connect --headless` 即可自动连接，无需用户操作。
+
+如果后续 headless 模式下 Plugin 始终不连接，可能是 RemNote 登录 session 过期，需重新 setup（删除 `~/.remnote-bridge/chrome-profile/.setup-done` 后重新执行）。
+
+---
+
+## 幂等性
+
+已完成 setup 后重复调用返回 `ok: true, alreadyDone: true`，不会再次打开 Chrome。
+
+如需重新登录（切换账号），删除 `~/.remnote-bridge/chrome-profile/.setup-done` 文件后重新执行。
+
+---
+
+## 退出码
+
+| 退出码 | 含义 |
+|--------|------|
+| 0 | 成功（首次完成或已完成） |
+| 1 | 失败（无 GUI、无 Chrome、超时等） |
+
+---
+
+## 产生的文件
+
+| 文件 | 位置 | 说明 |
+|------|------|------|
+| Chrome profile | `~/.remnote-bridge/chrome-profile/` | Chrome 用户数据（含登录凭证） |
+| `.setup-done` | `~/.remnote-bridge/chrome-profile/.setup-done` | setup 完成标记（JSON，含时间戳） |
+