remnote-bridge 0.1.13 → 0.1.15

package/remnote-plugin/dist/manifest.json

@@ -7,7 +7,7 @@
   "version": {
     "major": 0,
     "minor": 2,
-    "patch": 0
+    "patch": 1
   },
   "theme": [],
   "enableOnMobile": false,

package/remnote-plugin/package.json

@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "unofficial-remnote-bridge-plugin",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "license": "MIT",
   "description": "RemNote 桥接层：嵌入 RemNote 的 WebSocket 桥接插件",
   "scripts": {

package/remnote-plugin/public/manifest.json

@@ -7,7 +7,7 @@
   "version": {
     "major": 0,
     "minor": 2,
-    "patch": 0
+    "patch": 1
   },
   "theme": [],
   "enableOnMobile": false,

package/remnote-plugin/src/bridge/message-router.ts

@@ -11,6 +11,7 @@ import type { ReactRNPlugin } from '@remnote/plugin-sdk';
 import type { BridgeRequest } from './websocket-client';
 import { readRem } from '../services/read-rem';
 import { readTree } from '../services/read-tree';
+import { readRemInTree } from '../services/read-rem-in-tree';
 import { readGlobe } from '../services/read-globe';
 import { readContext } from '../services/read-context';
 import { writeRemFields } from '../services/write-rem-fields';
@@ -36,6 +37,8 @@ export function createMessageRouter(plugin: ReactRNPlugin): (request: BridgeRequ
         return readRem(plugin, request.payload as { remId: string; includePowerup?: boolean });
       case 'read_tree':
         return readTree(plugin, request.payload as { remId: string; depth?: number; maxNodes?: number; maxSiblings?: number; ancestorLevels?: number; includePowerup?: boolean });
+      case 'read_rem_in_tree':
+        return readRemInTree(plugin, request.payload as { remId: string; depth?: number; maxNodes?: number; maxSiblings?: number; ancestorLevels?: number; includePowerup?: boolean });
       case 'write_rem_fields':
         return writeRemFields(plugin, request.payload as { remId: string; changes: Record<string, unknown> });
       case 'create_rem':

package/remnote-plugin/src/services/read-rem-in-tree.ts

@@ -0,0 +1,43 @@
+/**
+ * read-rem-in-tree service — read_tree + 对每个节点 buildRemObject
+ *
+ * 同态命名：read_rem_in_tree (action) → read-rem-in-tree.ts (文件) → readRemInTree (函数)
+ */
+
+import type { ReactRNPlugin } from '@remnote/plugin-sdk';
+import type { RemObject } from '../types';
+import { readTree, type ReadTreePayload, type ReadTreeResult } from './read-tree';
+import { buildRemObject } from './read-rem';
+
+export interface ReadRemInTreePayload extends ReadTreePayload {}
+
+export interface ReadRemInTreeResult extends ReadTreeResult {
+  /** remId → RemObject 的扁平映射 */
+  remObjects: Record<string, RemObject & { powerupFiltered?: { tags: number; children: number } }>;
+}
+
+/**
+ * 读取 Rem 子树大纲 + 对树中每个节点构建完整 RemObject。
+ *
+ * @throws Error — Rem 不存在、节点数超限
+ */
+export async function readRemInTree(
+  plugin: ReactRNPlugin,
+  payload: ReadRemInTreePayload,
+): Promise<ReadRemInTreeResult> {
+  // 1. 获取 outline + nodeRemIds（复用 readTree）
+  const treeResult = await readTree(plugin, payload);
+
+  // 2. 用 readTree 遍历时收集的 nodeRemIds，直接并行 buildRemObject
+  const includePowerup = payload.includePowerup ?? false;
+  const remObjects: ReadRemInTreeResult['remObjects'] = {};
+
+  await Promise.all(treeResult.nodeRemIds.map(async (id) => {
+    const rem = await plugin.rem.findOne(id);
+    if (rem) {
+      remObjects[id] = await buildRemObject(plugin, rem, { includePowerup });
+    }
+  }));
+
+  return { ...treeResult, remObjects };
+}

package/remnote-plugin/src/services/read-rem.ts

@@ -33,6 +33,21 @@ export async function readRem(
     throw new Error(`Rem not found: ${payload.remId}`);
   }
 
+  return buildRemObject(plugin, rem, { includePowerup });
+}
+
+/**
+ * 从已有 Rem 对象组装完整 RemObject（跳过 findOne）。
+ *
+ * 供 readRem 和 readRemInTree 共享。
+ */
+export async function buildRemObject(
+  plugin: ReactRNPlugin,
+  rem: Rem,
+  options: { includePowerup?: boolean },
+): Promise<RemObject & { powerupFiltered?: { tags: number; children: number } }> {
+  const { includePowerup = false } = options;
+
   // 并行获取所有异步字段
   const [
     isDocument,
@@ -196,7 +211,7 @@ export async function readRem(
     portalType: remTypeToString(rem.type as number) === 'portal'
       ? portalTypeToString(portalType as number)
       : null,
-    portalDirectlyIncludedRem: portalDirectlyIncludedRems.map(r => r._id),
+    portalDirectlyIncludedRem: portalDirectlyIncludedRems.map(r => r._id).sort(),
 
     // 属性类型
     propertyType: (propertyType as PropertyTypeValue | undefined) ?? null,
@@ -205,27 +220,27 @@ export async function readRem(
     enablePractice,
     practiceDirection: practiceDirection as RemObject['practiceDirection'],
 
-    // 关联 — 直接关系
-    tags: filteredTagRems.map(r => r._id),
-    sources: sourceRems.map(r => r._id),
-    aliases: aliasRems.map(r => r._id),
+    // 关联 — 直接关系（排序保证确定性序列化）
+    tags: filteredTagRems.map(r => r._id).sort(),
+    sources: sourceRems.map(r => r._id).sort(),
+    aliases: aliasRems.map(r => r._id).sort(),
 
     // 关联 — 引用关系
-    remsBeingReferenced: refsBeingReferenced.map(r => r._id),
-    deepRemsBeingReferenced: deepRefsBeingReferenced.map(r => r._id),
-    remsReferencingThis: refsReferencingThis.map(r => r._id),
+    remsBeingReferenced: refsBeingReferenced.map(r => r._id).sort(),
+    deepRemsBeingReferenced: deepRefsBeingReferenced.map(r => r._id).sort(),
+    remsReferencingThis: refsReferencingThis.map(r => r._id).sort(),
 
     // 关联 — 标签体系
-    taggedRem: taggedRems.map(r => r._id),
-    ancestorTagRem: ancestorTagRems.map(r => r._id),
-    descendantTagRem: descendantTagRems.map(r => r._id),
+    taggedRem: taggedRems.map(r => r._id).sort(),
+    ancestorTagRem: ancestorTagRems.map(r => r._id).sort(),
+    descendantTagRem: descendantTagRems.map(r => r._id).sort(),
 
     // 关联 — 层级遍历
-    descendants: descendantRems.map(r => r._id),
-    siblingRem: siblingRems.map(r => r._id),
-    portalsAndDocumentsIn: portalsAndDocsIn.map(r => r._id),
-    allRemInDocumentOrPortal: allRemInDocOrPortal.map(r => r._id),
-    allRemInFolderQueue: allRemInFolderQ.map(r => r._id),
+    descendants: descendantRems.map(r => r._id).sort(),
+    siblingRem: siblingRems.map(r => r._id).sort(),
+    portalsAndDocumentsIn: portalsAndDocsIn.map(r => r._id).sort(),
+    allRemInDocumentOrPortal: allRemInDocOrPortal.map(r => r._id).sort(),
+    allRemInFolderQueue: allRemInFolderQ.map(r => r._id).sort(),
 
     // 位置 / 统计
     positionAmongstSiblings: position ?? null,

package/remnote-plugin/src/services/read-tree.ts

@@ -43,6 +43,8 @@ export interface ReadTreeResult {
   depth: number;
   nodeCount: number;
   outline: string;
+  /** 树中所有节点的 remId 列表（遍历顺序） */
+  nodeRemIds: string[];
   /** 祖先链（从直接父亲到最远祖先，由近及远） */
   ancestors?: AncestorInfo[];
   powerupFiltered?: { tags: number; children: number };
@@ -75,6 +77,7 @@ export async function readTree(
   let totalFilteredTags = 0;
   let totalFilteredChildren = 0;
   const budget = { remaining: maxNodes };
+  const nodeRemIds: string[] = [];
 
   /**
    * 递归构建 OutlineNode 树。
@@ -86,6 +89,7 @@ export async function readTree(
   async function buildNode(rem: Rem, currentDepth: number, maxDepth: number): Promise<OutlineNode> {
     nodeCount++;
     budget.remaining--;
+    nodeRemIds.push(rem._id);
 
     const allChildren = await rem.getChildrenRem();
     const children = includePowerup ? allChildren : await filterNoisyChildren(allChildren);
@@ -179,6 +183,7 @@ export async function readTree(
     depth,
     nodeCount,
     outline,
+    nodeRemIds,
   };
 
   // 祖先链构建

package/remnote-plugin/src/settings.ts

@@ -5,7 +5,7 @@
  * 多 daemon 连接：Plugin 同时连接 ALL_WS_PORTS 对应的 4 个槽位。
  */
 
-export const DEFAULT_PLUGIN_VERSION = '0.2.0';
+export const DEFAULT_PLUGIN_VERSION = '0.2.1';
 
 /** 4 个固定 WS 端口，对应 4 个 daemon 槽位 */
 export const ALL_WS_PORTS = [29100, 29110, 29120, 29130] as const;

package/skills/remnote-bridge/SKILL.md

@@ -18,6 +18,7 @@ description: "RemNote 知识库操作指南。通过 remnote-bridge 命令行工
 | read-rem | `instructions/read-rem.md` |
 | edit-rem | `instructions/edit-rem.md` |
 | read-tree | `instructions/read-tree.md` |
+| read-rem-in-tree | `instructions/read-rem-in-tree.md` |
 | edit-tree | `instructions/edit-tree.md` |
 | read-globe | `instructions/read-globe.md` |
 | read-context | `instructions/read-context.md` |
@@ -222,6 +223,7 @@ RemNote 格式设置（fontSize、highlightColor 等）底层通过 Powerup 机
 用户当前在看什么（"当前页面"）        → read-context
 某个 Rem 的子树（"展开这个主题"）     → read-tree <remId>
 某个 Rem 的详细属性（"详细信息"）     → read-rem <remId>
+子树 + 每个节点属性（"批量标注"）     → read-rem-in-tree <remId>
 按关键词搜索（"搜索 X"）            → search <query>（中文搜索有限制，见下方说明）
 ```
 
@@ -233,8 +235,9 @@ RemNote 格式设置（fontSize、highlightColor 等）底层通过 Powerup 机
 | 我在编辑什么 | `read-context --mode focus` | 鱼眼视图（焦点 depth=3，siblings depth=1，叔伯 depth=0），**无缓存** |
 | 当前页面内容 | `read-context --mode page` | 均匀展开，**无缓存** |
 | 展开某主题细节 | `read-tree <id>` | 完整子树，**有缓存**供 edit-tree |
+| 展开子树 + 每个节点属性 | `read-rem-in-tree <id>` | 大纲 + RemObject，**双重缓存**供 edit-tree 和 edit-rem |
 
-**重要**：read-globe、read-context、search 都**不写入缓存**，不能替代 read-tree/read-rem 作为 edit 的前置条件。read-context 需要用户在 RemNote 中有焦点（focus 模式）或打开页面（page 模式）。
+**重要**：read-globe、read-context、search 都**不写入缓存**，不能替代 read-tree/read-rem/read-rem-in-tree 作为 edit 的前置条件。read-context 需要用户在 RemNote 中有焦点（focus 模式）或打开页面（page 模式）。
 
 ### 修改：用户想改什么？
 
@@ -246,11 +249,43 @@ Rem 的属性（文本、类型、格式、标签）  → edit-rem   （前置
 
 **关键区分**：`edit-rem` 修改 Rem 的**属性**，`edit-tree` 修改 Rem 之间的**结构关系**。`edit-tree` **禁止修改行内容**。
 
+### read-rem-in-tree：何时用、怎么用
+
+`read-rem-in-tree` = `read-tree` + 批量 `read-rem` 的合体。一次调用同时获取子树大纲和每个节点的 RemObject（含完整 RichText），同时建立 `tree:` 和 `rem:` 双重缓存。
+
+**何时用**：当你需要对一棵子树中的**多个节点**做属性修改（edit-rem）时。典型场景：
+
+- 批量标注重点（给多个节点加高亮/粗体）
+- 批量修改类型（把多个普通 Rem 改为 concept）
+- 读取子树后需要检查多个节点的 RichText 再决定怎么改
+
+**何时不用**：只需要看大纲结构（用 `read-tree`），或只改 1-2 个节点属性（用 `read-tree` + `read-rem`）。
+
+**用法示例**（课本划重点场景）：
+
+```bash
+# 1. 一次获取大纲 + 所有节点属性（默认 maxNodes=50）
+read-rem-in-tree --json '{"remId":"kLr...","depth":3,"maxNodes":30}'
+
+# 返回：outline（大纲文本）+ remObjects（每个节点的 RemObject）
+
+# 2. 从 remObjects 中找到要标注的节点，直接 edit-rem（rem 缓存已就绪）
+edit-rem --json '{"remId":"ABC","changes":{"highlightColor":"Yellow"}}'
+edit-rem --json '{"remId":"DEF","changes":{"text":["关键词",{"b":true,"h":1,"i":"m","text":"重点"}]}}'
+
+# 3. 如需结构变更，直接 edit-tree（tree 缓存已就绪）
+edit-tree --json '{"remId":"kLr...","oldStr":"...","newStr":"..."}'
+```
+
+**对比效率**：修改 10 个节点时，`read-rem-in-tree` = 1 次调用；`read-tree` + 10×`read-rem` = 11 次调用。
+
 ---
 
 ## 3. 标准工作流
 
-### ⚠️ 标准模式：connect 后需要用户配合
+### ⚠️ 标准模式（推荐）：connect 后需要用户配合
+
+**标准模式是推荐的日常使用方式**。用户在自己的浏览器中操作 RemNote，Agent 可以通过 `read-context` 感知用户正在浏览的页面和焦点位置，实现真正的协作。
 
 `connect` 成功只意味着 daemon 和 Plugin 服务已启动，**Plugin 并未自动连接**。用户必须在 RemNote 中完成操作，Plugin 才能连接到 daemon：
 
@@ -266,11 +301,18 @@ Rem 的属性（文本、类型、格式、标签）  → edit-rem   （前置
 
 **你必须**：执行 `connect` 后，**立即告知用户需要完成上述操作**，不要直接调用业务命令。引导用户完成后，用 `health` 确认三层就绪再继续。
 
-### Headless 模式：自动连接
+### Headless 模式（特殊场景，不推荐日常使用）
+
+通过 setup（一次性）+ headless Chrome 实现自动连接，后续 connect 无需用户介入。
+
+**⚠️ 不推荐日常使用**。Headless Chrome 是后台独立实例，**会丢失用户上下文**——`read-context` 返回的是 headless Chrome 的上下文，不是用户浏览器的。Agent 无法感知用户正在浏览和操作的页面，协作体验大打折扣。
 
-标准模式每次 connect 后都需要用户手动操作 RemNote。Headless 模式通过 setup（一次性）+ headless Chrome 实现自动连接，后续 connect 无需用户介入。
+**仅在以下场景使用 headless**：
+- 用户明确要求在**服务器/无 GUI 环境**中运行
+- 用户明确表示**不想参与操作**，希望全自动化（CI/CD、定时任务、批量处理等）
+- 用户自己不在 RemNote 前面，不需要与 Agent 协作浏览
 
-**⚠️ 模式选择建议**：日常使用推荐**标准模式**。Headless 模式下 Chrome 在后台运行，**无法感知用户正在 RemNote 中浏览和操作的界面**（`read-context` 返回的是 headless Chrome 的上下文，而非用户的浏览器）。只有在全自动化场景（CI/CD、定时任务、批量操作等无需与用户界面交互的场景）才建议使用 Headless 模式。
+**默认始终使用标准模式**，除非用户主动要求 headless。
 
 #### 首次使用（setup）
 
@@ -315,9 +357,9 @@ setup 只需执行一次。之后每次连接直接用 `connect --headless`。
 4. read-globe           -- 了解知识库结构（首次探索）
    或 read-context      -- 了解用户当前上下文
 5. search "关键词"       -- 定位目标 Rem（结果不进缓存！）
-6. read-tree <id>       -- 展开子树 → 写入缓存（edit-tree 的前置）
-7. read-rem <id>        -- 读取属性 → 写入缓存（edit-rem 的前置）
-8. edit-rem / edit-tree -- 执行修改
+6a. [单节点] read-tree <id> + read-rem <id>  -- 各自建立缓存
+6b. [多节点] read-rem-in-tree <id>           -- 一次建立双重缓存（推荐 ≥3 个节点需修改时）
+7. edit-rem / edit-tree -- 执行修改
 9. disconnect           -- 结束会话（缓存全部清空，幂等）
 ```
 

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

@@ -43,7 +43,9 @@ remnote-bridge --json connect --instance work
 | 2 | 29120 | 29121 | 29122 |
 | 3 | 29130 | 29131 | 29132 |
 
-**实例名解析优先级**：CLI `--instance` 参数 > 环境变量 `REMNOTE_BRIDGE_INSTANCE` > 默认值 `default`。Headless 模式下固定为 `headless`。
+**实例名解析优先级**：CLI `--instance` 参数 > 环境变量 `REMNOTE_BRIDGE_INSTANCE` > 默认值 `default`。
+
+**⚠️ `headless` 是保留实例名**：`--instance headless` 会直接报错。headless 模式必须使用专用的 `--headless` 全局选项（见下方 Headless 模式章节）。
 
 **首次使用多实例时**，用户需在 RemNote 中为每个实例分别配置 dev plugin URL（对应各自的 Plugin 服务端口）。
 
@@ -51,13 +53,20 @@ remnote-bridge --json connect --instance work
 
 ## 两种模式
 
-### 标准模式（默认）
+### 标准模式（默认，推荐）
+
+**标准模式是推荐的日常使用方式**。启动 daemon 后用户在自己的浏览器中加载 Plugin。优势：Agent 可以通过 `read-context` 感知用户正在浏览的页面和焦点位置，实现真正的协作。
 
-启动 daemon 后需要用户手动在 RemNote 中加载 Plugin。适用于用户已打开 RemNote 的场景。
+### Headless 模式（`--headless`，特殊场景）
 
-### Headless 模式（`--headless`）
+自动启动 headless Chrome 加载 Plugin，无需用户操作。
 
-自动启动 headless Chrome 加载 Plugin，无需用户操作。适用于无 GUI 环境或全自动连接场景。
+**⚠️ 不推荐日常使用**。Headless Chrome 是后台独立实例，**会丢失用户上下文**——`read-context` 返回的是 headless Chrome 的上下文，不是用户浏览器的。
+
+**仅在以下场景使用 headless**：
+- 用户明确要求在**服务器/无 GUI 环境**中运行
+- 用户明确表示**不想参与操作**，希望全自动化（CI/CD、定时任务、批量处理等）
+- 用户自己不在 RemNote 前面，不需要与 Agent 协作浏览
 
 **前置条件**：必须先执行 `setup` 完成 RemNote 登录。
 
@@ -74,6 +83,15 @@ remnote-bridge --json connect --headless
 
 Headless 模式下 Plugin 可能需要 10-30 秒才能连接到 daemon，使用 `health` 确认就绪。
 
+`--headless` 是全局选项，headless 会话中**所有命令都需要带上**：
+
+```bash
+remnote-bridge --headless connect    # 启动
+remnote-bridge --headless health     # 检查
+remnote-bridge --headless read-rem --json '{"remId":"..."}'  # 业务命令
+remnote-bridge --headless disconnect # 结束
+```
+
 排查工具：`health --diagnose`（截图+状态+console 错误）、`health --reload`（重载 Chrome 页面）。
 
 ---
@@ -82,12 +100,17 @@ Headless 模式下 Plugin 可能需要 10-30 秒才能连接到 daemon，使用
 
 `connect`（不传 `--headless`）成功只意味着 daemon 和 Plugin 服务已启动，**Plugin 并未自动连接**。用户必须在 RemNote 中完成以下操作：
 
+> **⚠️ 防幻觉红线**：本插件是**开发者插件**，通过「开发你的插件」功能加载本地 URL。
+> - **禁止**告诉用户"去插件市场/商店搜索安装"——本插件**不在 RemNote 插件市场中**
+> - **禁止**告诉用户"Settings → Plugins"——这个路径不存在
+> - **禁止**编造不存在的安装流程——严格按照下方步骤引导用户
+
 ### 首次使用（RemNote 从未加载过此插件）
 
 1. 打开 RemNote 桌面端或网页端
-2. 点击左侧边栏底部的插件图标（拼图形状）
-3. 点击「开发你的插件」（Develop Your Plugin）
-4. 在输入框中填入 connect 输出的 Plugin 服务地址（如 `http://localhost:29101`）
+2. 点击左侧边栏底部的**插件图标**（拼图形状）
+3. 点击「**开发你的插件**」（Develop Your Plugin）
+4. 在输入框中填入 connect 输出的 **Plugin 服务地址**（如 `http://localhost:29101`）
 5. 等待插件加载完成
 
 ### 非首次使用（之前已加载过此插件）

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

@@ -18,12 +18,17 @@
 
 通过 `--instance <name>` 指定要停止的实例。不指定时停止 `default` 实例。
 
+`--headless` 是全局选项，用于停止 headless 模式启动的实例。
+
 ```bash
 # 停止默认实例
 remnote-bridge disconnect
 
 # 停止指定实例
 remnote-bridge disconnect --instance work
+
+# 停止 headless 实例
+remnote-bridge --headless disconnect
 ```
 
 ---