remnote-bridge 0.1.6 → 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/remnote-plugin/src/bridge/message-router.ts

@@ -19,6 +19,9 @@ import { deleteRem } from '../services/delete-rem';
 import { moveRem } from '../services/move-rem';
 import { reorderChildren } from '../services/reorder-children';
 import { search } from '../services/search';
+import { createPortal } from '../services/create-portal';
+import { addToPortal } from '../services/add-to-portal';
+import { removeFromPortal } from '../services/remove-from-portal';
 
 /**
  * 创建消息路由处理器
@@ -50,6 +53,14 @@ export function createMessageRouter(plugin: ReactRNPlugin): (request: BridgeRequ
       case 'search':
         return search(plugin, request.payload as { query: string; numResults?: number });
 
+      // Portal 操作
+      case 'create_portal':
+        return createPortal(plugin, request.payload as { parentId: string; position?: number });
+      case 'add_to_portal':
+        return addToPortal(plugin, request.payload as { portalId: string; remId: string });
+      case 'remove_from_portal':
+        return removeFromPortal(plugin, request.payload as { portalId: string; remId: string });
+
       default:
         throw new Error(`未实现的 action: ${request.action}`);
     }

package/remnote-plugin/src/services/add-to-portal.ts

@@ -0,0 +1,40 @@
+/**
+ * add-to-portal service — 向 Portal 添加引用
+ *
+ * 同态命名：add_to_portal (action) → add-to-portal.ts (文件) → addToPortal (函数)
+ *
+ * 注意调用方向：addToPortal() 是在被引用的 Rem 上调用，参数是 Portal Rem。
+ */
+
+import type { ReactRNPlugin } from '@remnote/plugin-sdk';
+
+export interface AddToPortalPayload {
+  /** Portal Rem ID */
+  portalId: string;
+  /** 要添加到 Portal 的 Rem ID */
+  remId: string;
+}
+
+/**
+ * 将指定 Rem 添加到 Portal 的引用列表。
+ *
+ * @throws Error — Portal 不存在、Rem 不存在
+ */
+export async function addToPortal(
+  plugin: ReactRNPlugin,
+  payload: AddToPortalPayload,
+): Promise<void> {
+  const { portalId, remId } = payload;
+
+  const portal = await plugin.rem.findOne(portalId);
+  if (!portal) {
+    throw new Error(`Portal not found: ${portalId}`);
+  }
+
+  const rem = await plugin.rem.findOne(remId);
+  if (!rem) {
+    throw new Error(`Rem not found: ${remId}`);
+  }
+
+  await rem.addToPortal(portal);
+}

package/remnote-plugin/src/services/create-portal.ts

@@ -0,0 +1,47 @@
+/**
+ * create-portal service — 创建 Portal Rem
+ *
+ * 同态命名：create_portal (action) → create-portal.ts (文件) → createPortal (函数)
+ *
+ * Portal 只能通过 plugin.rem.createPortal() 创建，不能通过 setType() 将已有 Rem 转为 Portal。
+ */
+
+import type { ReactRNPlugin } from '@remnote/plugin-sdk';
+
+export interface CreatePortalPayload {
+  /** 父节点 Rem ID */
+  parentId: string;
+  /** 在兄弟中的位置（0-based），可选 */
+  position?: number;
+}
+
+export interface CreatePortalResult {
+  remId: string;
+}
+
+/**
+ * 创建空 Portal 并设置父节点。
+ *
+ * @throws Error — 创建失败、父节点不存在
+ */
+export async function createPortal(
+  plugin: ReactRNPlugin,
+  payload: CreatePortalPayload,
+): Promise<CreatePortalResult> {
+  const { parentId, position } = payload;
+
+  // 创建空 Portal
+  const portal = await plugin.rem.createPortal();
+  if (!portal) {
+    throw new Error('Failed to create portal');
+  }
+
+  // 设置父节点和位置
+  const parent = await plugin.rem.findOne(parentId);
+  if (!parent) {
+    throw new Error(`Parent Rem not found: ${parentId}`);
+  }
+  await portal.setParent(parent, position);
+
+  return { remId: portal._id };
+}

package/remnote-plugin/src/services/remove-from-portal.ts

@@ -0,0 +1,40 @@
+/**
+ * remove-from-portal service — 从 Portal 移除引用
+ *
+ * 同态命名：remove_from_portal (action) → remove-from-portal.ts (文件) → removeFromPortal (函数)
+ *
+ * 注意调用方向：removeFromPortal() 是在被引用的 Rem 上调用，参数是 Portal Rem。
+ */
+
+import type { ReactRNPlugin } from '@remnote/plugin-sdk';
+
+export interface RemoveFromPortalPayload {
+  /** Portal Rem ID */
+  portalId: string;
+  /** 要从 Portal 移除的 Rem ID */
+  remId: string;
+}
+
+/**
+ * 将指定 Rem 从 Portal 的引用列表中移除。
+ *
+ * @throws Error — Portal 不存在、Rem 不存在
+ */
+export async function removeFromPortal(
+  plugin: ReactRNPlugin,
+  payload: RemoveFromPortalPayload,
+): Promise<void> {
+  const { portalId, remId } = payload;
+
+  const portal = await plugin.rem.findOne(portalId);
+  if (!portal) {
+    throw new Error(`Portal not found: ${portalId}`);
+  }
+
+  const rem = await plugin.rem.findOne(remId);
+  if (!rem) {
+    throw new Error(`Rem not found: ${remId}`);
+  }
+
+  await rem.removeFromPortal(portal);
+}

package/remnote-plugin/src/services/write-rem-fields.ts

@@ -194,6 +194,11 @@ async function applyField(
       await applySourcesDiff(rem, value as string[]);
       break;
 
+    // Portal 引用（diff based）
+    case 'portalDirectlyIncludedRem':
+      await applyPortalRefsDiff(rem, plugin, value as string[]);
+      break;
+
     // Powerup 操作
     case 'addPowerup':
       await rem.addPowerup(value as string);
@@ -242,6 +247,40 @@ async function applySourcesDiff(rem: Rem, targetIds: string[]): Promise<void> {
   }
 }
 
+/**
+ * portalDirectlyIncludedRem diff: 对比当前和目标，通过 addToPortal/removeFromPortal 增删。
+ * 注意调用方向：addToPortal/removeFromPortal 是在被引用 Rem 上调用，参数是 Portal Rem。
+ */
+async function applyPortalRefsDiff(portalRem: Rem, plugin: ReactRNPlugin, targetIds: string[]): Promise<void> {
+  // 防御：非 Portal Rem 不可修改此字段
+  // 使用 rem.type === 6（portal 类型的枚举值），而非 getPortalType()
+  // 因为 getPortalType() 可能对新创建的 Portal 返回 undefined
+  if ((portalRem as unknown as { type: number }).type !== 6) {
+    throw new Error('portalDirectlyIncludedRem can only be modified on Portal Rem');
+  }
+
+  const currentRefs = await portalRem.getPortalDirectlyIncludedRem();
+  const currentIds = new Set(currentRefs.map((r: Rem) => r._id));
+  const targetSet = new Set(targetIds);
+
+  // 添加缺少的
+  for (const id of targetIds) {
+    if (!currentIds.has(id)) {
+      const remToAdd = await plugin.rem.findOne(id);
+      if (!remToAdd) throw new Error(`Rem not found: ${id}`);
+      await remToAdd.addToPortal(portalRem);
+    }
+  }
+  // 删除多余的
+  for (const id of currentIds) {
+    if (!targetSet.has(id as string)) {
+      const remToRemove = await plugin.rem.findOne(id as string);
+      if (!remToRemove) throw new Error(`Rem not found: ${id}`);
+      await remToRemove.removeFromPortal(portalRem);
+    }
+  }
+}
+
 /** 字符串类型值 → SDK SetRemType 枚举数值。Portal 不可通过 setType() 设置。 */
 function remTypeStringToEnum(type: string): 1 | 2 | 'DEFAULT_TYPE' {
   switch (type) {

package/remnote-plugin/src/types.ts

@@ -21,13 +21,16 @@
  * 以下每个 [RW] 字段的注释标注了其底层是 Powerup 机制还是纯字段修改
  *
  * 读写标注：
- * - [RW]   = 可读可写（SDK 有对应的 setter/add/remove 方法）
- * - [R]    = 只读，默认输出（SDK 仅有 getter）
- * - [R-F]  = 只读，仅 --full 模式输出（低频 / 细粒度 / 可由其他字段推导）
+ * - [RW]       = 可读可写（SDK 有对应的 setter/add/remove 方法）
+ * - [Portal-W] = Portal 专用可写（仅 Portal Rem 可通过 addToPortal/removeFromPortal 修改）
+ * - [R]        = 只读，默认输出（SDK 仅有 getter）
+ * - [R-F]      = 只读，仅 --full 模式输出（低频 / 细粒度 / 可由其他字段推导）
  *
  * 输出模式（CLI --full 选项）：
  * - 默认模式：输出 [RW] + [R] 字段（34 个），覆盖 Agent 常用场景
  * - --full 模式：额外输出 [R-F] 字段（+17 个），用于调试或深度分析
+ * - Portal 模式：type === 'portal' 时自动输出 9 个关键字段（id、type、portalType、
+ *   portalDirectlyIncludedRem、parent、positionAmongstSiblings、children、createdAt、updatedAt）
  *
  * 实测标注（2026-03-03 在 RemNote UI 中逐字段截图观察）：
  * - ✅ 已实测 = 在真实 RemNote 环境中创建独立 Rem 并截图观察视觉行为
@@ -254,7 +257,7 @@ export interface RemObject {
 
   /** [R] Portal 子类型。仅 type === 'portal' 时有值。SDK: getPortalType() */
   portalType: PortalType | null;
-  /** [R] Portal 直接包含的 Rem ID 数组。SDK: getPortalDirectlyIncludedRem() */
+  /** [Portal-W] Portal 直接包含的 Rem ID 数组。SDK: getPortalDirectlyIncludedRem() / addToPortal() / removeFromPortal()。写入时使用 diff 机制。仅 type === 'portal' 时可修改 */
   portalDirectlyIncludedRem: string[];
 
   // ══════════════════════════════════════════════════════════

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` |
@@ -42,7 +43,7 @@ RemNote 中所有内容的基本单元都是 **Rem**。文档、文件夹、闪
 
 两个独立维度：
 
-- **type**（闪卡语义）：`concept`（加粗）、`descriptor`（正常字重）、`default`（普通）、`portal`（只读）
+- **type**（闪卡语义）：`concept`（加粗）、`descriptor`（正常字重）、`default`（普通）、`portal`（嵌入引用容器）
 - **isDocument**（页面语义）：与 type 完全独立
 
 ### CDF 框架（Concept-Descriptor Framework）
@@ -88,7 +89,17 @@ 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 的编辑同步意味着修改一处会影响另一处。Portal 引用的 Rem 不会被 read-tree 自动展开，需要对 refs 中的 ID 单独 read-tree。Portal 引用列表可通过 `edit-rem` 修改（str_replace 简化 JSON 中的 `portalDirectlyIncludedRem` 数组）。
+
+#### Portal 操作速查
+
+| 操作 | 命令 | 方式 |
+|:-----|:-----|:-----|
+| 创建 Portal | `edit-tree` | 新增行 `<!--portal refs:id1,id2-->` |
+| 删除 Portal | `edit-tree` | 从大纲中移除 Portal 行（与删除普通行相同） |
+| 修改引用列表（增删引用的 Rem） | `edit-rem` | str_replace 简化 JSON 中的 `portalDirectlyIncludedRem` 数组 |
+| 移动 Portal（换父节点/位置） | `edit-tree` | 与移动普通行相同 |
+| 读取 Portal | `read-rem` | 自动输出 9 字段简化 JSON |
 
 ### RichText 格式
 
@@ -236,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. 等待插件加载完成
 
 **非首次使用**（之前已加载过此插件）：
@@ -252,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              -- 启动会话（幂等，重复调用安全）
@@ -423,6 +477,30 @@ read-tree / read-globe / read-context 输出 Markdown 大纲，edit-tree 基于
   `代码块`
 ```
 
+### 新增行指定类型/属性（metadata-only 注释）
+
+新增行可在行尾添加 HTML 注释来指定 type、isDocument、tag，格式中不含 remId：
+
+```markdown
+  新概念 <!--type:concept-->
+  新文档页 <!--type:concept doc-->
+  带标签的描述 <!--type:descriptor tag:数学(tag01)-->
+  多标记组合 <!--type:concept doc tag:基础(tag02) tag:数学(tag01)-->
+```
+
+支持的标记：`type:concept`、`type:descriptor`、`doc`、`tag:Name(id)`（可多个，空格分隔）。
+
+### 新增 Portal
+
+在 newStr 中用特殊格式创建 Portal：
+
+```markdown
+  <!--portal refs:id1,id2-->      创建 Portal 并引用 id1、id2
+  <!--portal-->                   创建空 Portal
+```
+
+注意：与已有 Portal 行（`<!--remId type:portal refs:id1,id2-->`）不同，新增 Portal 以 `<!--portal` 开头，无 remId。Portal 不能通过 `edit-rem` 设 `type: "portal"` 创建，只能用此格式或 SDK `createPortal()`。
+
 ### 嵌套新增（一次创建父+子结构）
 
 新增行下面可以再嵌套新增行，缩进表示父子关系：
@@ -474,14 +552,14 @@ oldStr: "\"text\": [\n    \"Hello\"\n  ]"
 newStr: "\"text\": [\n    \"World\"\n  ]"
 ```
 
-### 20 个可编辑字段
+### 21 个可编辑字段
 
 ```
 text, backText, type, isDocument, parent,
 fontSize, highlightColor,
 isTodo, todoStatus, isCode, isQuote, isListItem, isCardItem, isSlot, isProperty,
 enablePractice, practiceDirection,
-tags, sources, positionAmongstSiblings
+tags, sources, positionAmongstSiblings, portalDirectlyIncludedRem
 ```
 
 ### 特殊字段处理规则
@@ -495,6 +573,7 @@ tags, sources, positionAmongstSiblings
 | `type` | 不可设为 `portal`（只能通过 SDK `createPortal()` 创建） |
 | `parent` + `positionAmongstSiblings` | 共享同一 SDK 调用 `setParent(parentId, position)`，**应在同一次 str_replace 中同时修改** |
 | `tags` / `sources` | **Diff 机制**：对比当前 vs 目标数组，逐项 add/remove。必须列出完整目标数组，缺少的会被删除 |
+| `portalDirectlyIncludedRem` | Portal 专用可写。**Diff 机制**：对比当前 vs 目标数组，逐项 addToPortal/removeFromPortal。仅 type=portal 时可修改。edit-rem 对 Portal 使用 9 字段简化 JSON |
 
 ### 常用只读字段（修改只产生警告，不生效）
 
@@ -508,6 +587,7 @@ aliases, descendants, siblingRem, isTable, portalType, propertyType
 | 模式 | 字段数 | 用法 |
 |:-----|:-------|:-----|
 | 默认 | 34（RW + R） | 常用场景 |
+| Portal 简化 | 9（id, type, portalType, portalDirectlyIncludedRem, parent, positionAmongstSiblings, children, createdAt, updatedAt） | type=portal 时自动切换，`--full` 和 `--fields` 可覆盖 |
 | `--full` | 51（含低频 R-F） | 需要 Powerup 标识、时间戳等 |
 | `--fields` | 自选 + id | 精确获取特定字段 |
 
@@ -531,6 +611,8 @@ aliases, descendants, siblingRem, isTable, portalType, propertyType
 | 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 重新定位 |
 
 ---

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 交互后自动关闭
 ```
@@ -106,7 +135,7 @@ remnote-bridge --json connect
 {
   "ok": false,
   "command": "connect",
-  "error": "守护进程启动超时（10 秒）",
+  "error": "守护进程启动超时（60 秒）",
   "timestamp": "2026-03-06T10:00:00.000Z"
 }
 ```
@@ -125,19 +154,28 @@ remnote-bridge --json connect
 3. daemon 内部按顺序启动：
    ├─ WS Server（必须成功，否则 daemon 退出）
    ├─ ConfigServer（非关键，失败不阻塞）
-   └─ webpack-dev-server（必须成功，否则 daemon 退出）
+   └─ Plugin 服务（默认静态服务器；--dev 时为 webpack-dev-server + 依赖自动安装 + 崩溃重试）
 
 4. daemon 写入 PID 文件
 
 5. daemon 通过 IPC 发送 ready 信号给父进程
 
 6. 父进程（CLI）收到 ready → 输出结果 → 退出
-   ├─ 10 秒内未收到 → 超时失败
+   ├─ 60 秒内未收到 → 超时失败
    └─ 收到 error → 启动失败
 ```
 
 ---
 
+## Windows 注意事项
+
+- **默认模式秒级启动**：使用预构建 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>` 强制终止
+
+---
+
 ## 超时机制
 
 daemon 启动后开始计时，默认 **30 分钟无 CLI 交互**自动关闭（执行优雅 shutdown）。每次收到 CLI 请求时重置计时器。
@@ -157,7 +195,7 @@ daemon 启动后开始计时，默认 **30 分钟无 CLI 交互**自动关闭（
 | 退出码 | 含义 |
 |--------|------|
 | 0 | 启动成功，或已在运行 |
-| 1 | 启动失败（超时、端口冲突、webpack-dev-server 异常等） |
+| 1 | 启动失败（超时、端口冲突、Plugin 服务异常等） |
 
 ---
 
@@ -166,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. 内存缓存随进程退出自动消失