remnote-bridge 0.1.9 → 0.1.11

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

@@ -49,7 +49,7 @@ export function createMessageRouter(plugin: ReactRNPlugin): (request: BridgeRequ
       case 'read_globe':
         return readGlobe(plugin, request.payload as { depth?: number; maxNodes?: number; maxSiblings?: number });
       case 'read_context':
-        return readContext(plugin, request.payload as { mode?: 'focus' | 'page'; ancestorLevels?: number; maxNodes?: number; maxSiblings?: number; depth?: number });
+        return readContext(plugin, request.payload as { mode?: 'focus' | 'page'; ancestorLevels?: number; maxNodes?: number; maxSiblings?: number; depth?: number; focusRemId?: string });
       case 'search':
         return search(plugin, request.payload as { query: string; numResults?: number });
 

package/remnote-plugin/src/services/breadcrumb.ts

@@ -5,6 +5,7 @@
  */
 
 import type { ReactRNPlugin, PluginRem as Rem } from '@remnote/plugin-sdk';
+import { safeToMarkdown } from './rem-builder';
 
 /**
  * 从 rem 向上追溯到根，返回路径名称数组（从根到当前）。
@@ -17,7 +18,7 @@ export async function buildBreadcrumb(
   let current: Rem | undefined = rem;
 
   while (current) {
-    const text = await plugin.richText.toMarkdown(current.text ?? []);
+    const text = await safeToMarkdown(plugin, current.text ?? []);
     path.unshift(text.replace(/\n/g, ' ').trim() || current._id);
     current = await current.getParentRem();
   }

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

@@ -19,7 +19,7 @@ import {
 import { filterNoisyChildren } from './powerup-filter';
 import { sliceSiblings } from '../utils/elision';
 import { buildBreadcrumb } from './breadcrumb';
-import { buildFullSerializableRem as buildFullRem } from './rem-builder';
+import { buildFullSerializableRem as buildFullRem, safeToMarkdown } from './rem-builder';
 
 export interface ReadContextPayload {
   mode?: 'focus' | 'page';
@@ -27,6 +27,7 @@ export interface ReadContextPayload {
   maxNodes?: number;
   maxSiblings?: number;
   depth?: number;
+  focusRemId?: string;
 }
 
 export interface ReadContextResult {
@@ -46,12 +47,14 @@ export async function readContext(
     maxNodes = 200,
     maxSiblings = 20,
     depth = 3,
+    focusRemId,
   } = payload;
 
   if (mode === 'page') {
+    if (focusRemId) throw new Error('focusRemId 仅在 focus 模式下有效，page 模式下请勿指定');
     return readContextPage(plugin, { maxNodes, maxSiblings, depth });
   }
-  return readContextFocus(plugin, { ancestorLevels, maxNodes, maxSiblings });
+  return readContextFocus(plugin, { ancestorLevels, maxNodes, maxSiblings, focusRemId });
 }
 
 // ────────────────────────── Page 模式 ──────────────────────────
@@ -87,10 +90,16 @@ async function readContextPage(
 
 async function readContextFocus(
   plugin: ReactRNPlugin,
-  opts: { ancestorLevels: number; maxNodes: number; maxSiblings: number },
+  opts: { ancestorLevels: number; maxNodes: number; maxSiblings: number; focusRemId?: string },
 ): Promise<ReadContextResult> {
-  const focusRem = await plugin.focus.getFocusedRem();
-  if (!focusRem) throw new Error('当前没有聚焦的 Rem，请先在 RemNote 中点击一个 Rem');
+  let focusRem: Rem | undefined;
+  if (opts.focusRemId) {
+    focusRem = await plugin.rem.findOne(opts.focusRemId);
+    if (!focusRem) throw new Error(`指定的 Rem 不存在: ${opts.focusRemId}`);
+  } else {
+    focusRem = await plugin.focus.getFocusedRem();
+    if (!focusRem) throw new Error('当前没有聚焦的 Rem，请先在 RemNote 中点击一个 Rem');
+  }
 
   const breadcrumb = await buildBreadcrumb(plugin, focusRem);
 
@@ -350,7 +359,7 @@ async function buildMinimalSerializableRem(
 ) {
   const isPortal = rem.type === 6;
   const [markdownText, isDocument, portalIncludedRems] = await Promise.all([
-    plugin.richText.toMarkdown(rem.text ?? []),
+    safeToMarkdown(plugin, rem.text ?? []),
     rem.isDocument(),
     isPortal ? rem.getPortalDirectlyIncludedRem() : Promise.resolve([]),
   ]);

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

@@ -21,6 +21,7 @@ import {
 } from '../utils/tree-serializer';
 import { sliceSiblings } from '../utils/elision';
 import { filterNoisyChildren } from './powerup-filter';
+import { safeToMarkdown } from './rem-builder';
 
 export interface ReadGlobePayload {
   depth?: number;
@@ -75,7 +76,7 @@ export async function readGlobe(
 
     const isPortal = rem.type === 6;
     const [markdownText, portalIncludedRems] = await Promise.all([
-      plugin.richText.toMarkdown(rem.text ?? []),
+      safeToMarkdown(plugin, rem.text ?? []),
       isPortal ? rem.getPortalDirectlyIncludedRem() : Promise.resolve([]),
     ]);
 

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

@@ -18,7 +18,7 @@ import {
 } from '../utils/tree-serializer';
 import { filterNoisyChildren } from './powerup-filter';
 import { sliceSiblings } from '../utils/elision';
-import { buildFullSerializableRem, sanitizeNewlines } from './rem-builder';
+import { buildFullSerializableRem, sanitizeNewlines, safeToMarkdown } from './rem-builder';
 
 export interface ReadTreePayload {
   remId: string;
@@ -190,7 +190,7 @@ export async function readTree(
       const parent = await current.getParentRem();
       if (!parent) break;
       const [name, children, isDoc] = await Promise.all([
-        plugin.richText.toMarkdown(parent.text ?? []),
+        safeToMarkdown(plugin, parent.text ?? []),
         parent.getChildrenRem(),
         parent.isDocument(),
       ]);

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

@@ -11,6 +11,56 @@ import type { ReactRNPlugin, PluginRem as Rem } from '@remnote/plugin-sdk';
 import type { SerializableRem } from '../utils/tree-serializer';
 import { filterNoisyTags } from './powerup-filter';
 
+/**
+ * SDK richText.toMarkdown 的安全包装。
+ * SDK 不认识某些 RichText 类型（如 "i":"u" URL 链接），会抛 Invalid input。
+ * 失败时回退到本地解析。
+ */
+export async function safeToMarkdown(
+  plugin: ReactRNPlugin,
+  richText: unknown[],
+): Promise<string> {
+  try {
+    return await plugin.richText.toMarkdown(richText);
+  } catch {
+    return richTextFallback(richText);
+  }
+}
+
+/**
+ * 本地 RichText → 纯文本回退，处理 SDK 不支持的类型。
+ *
+ * 覆盖 RICH_TEXT_ELEMENT_TYPE 枚举全部 12 种类型 + 遗留 "u" 类型：
+ *   m=TEXT, q=REM, i=IMAGE, a=AUDIO, x=LATEX, p=PLUGIN,
+ *   g=GLOBAL_NAME, s=CARD_DELIMITER, n=ANNOTATION,
+ *   fi=FLASHCARD_ICON, ai=ADD_ICON, o=DEPRECATED_CODE, u=URL(遗留)
+ */
+function richTextFallback(richText: unknown[]): string {
+  return richText.map(item => {
+    if (typeof item === 'string') return item;
+    if (typeof item !== 'object' || item === null) return '';
+    const obj = item as Record<string, unknown>;
+    switch (obj.i) {
+      case 'm': return String(obj.text ?? '');
+      case 'q': return `[[${String(obj._id ?? '')}]]`;
+      case 'u': return obj.title
+        ? `[${String(obj.title)}](${String(obj.url)})`
+        : String(obj.url ?? '');
+      case 'x': return `$${String(obj.text ?? '')}$`;
+      case 'i': return `![image](${String(obj.url ?? '')})`;
+      case 'a': return `[audio](${String(obj.url ?? '')})`;
+      case 'p': return String(obj.text ?? '');           // PLUGIN
+      case 'g': return String(obj.text ?? '');           // GLOBAL_NAME
+      case 'n': return String(obj.text ?? '');           // ANNOTATION
+      case 'o': return String(obj.text ?? '');           // DEPRECATED_CODE
+      case 's':                                          // CARD_DELIMITER
+      case 'fi':                                         // FLASHCARD_ICON
+      case 'ai': return '';                              // ADD_ICON（纯视觉标记）
+      default: return String(obj.text ?? obj.url ?? '');
+    }
+  }).join('');
+}
+
 export interface BuildFullRemOptions {
   /** 是否保留 Powerup 系统 Tag（默认 false = 过滤掉） */
   includePowerup?: boolean;
@@ -46,8 +96,8 @@ export async function buildFullSerializableRem(
     hasDvPowerup,
     portalIncludedRems,
   ] = await Promise.all([
-    plugin.richText.toMarkdown(rem.text ?? []),
-    rem.backText ? plugin.richText.toMarkdown(rem.backText) : Promise.resolve(null),
+    safeToMarkdown(plugin, rem.text ?? []),
+    rem.backText ? safeToMarkdown(plugin, rem.backText) : Promise.resolve(null),
     rem.getType(),
     rem.isCardItem(),
     rem.isDocument(),
@@ -80,7 +130,7 @@ export async function buildFullSerializableRem(
   const tags = await Promise.all(
     tagRems.map(async (t) => ({
       id: t._id,
-      name: sanitizeNewlines(await plugin.richText.toMarkdown(t.text ?? [])),
+      name: sanitizeNewlines(await safeToMarkdown(plugin, t.text ?? [])),
     })),
   );
 

package/remnote-plugin/src/services/search.ts

@@ -7,6 +7,7 @@
  */
 
 import type { ReactRNPlugin } from '@remnote/plugin-sdk';
+import { safeToMarkdown } from './rem-builder';
 
 export interface SearchPayload {
   query: string;
@@ -39,7 +40,7 @@ export async function search(
 
   const results: SearchResultItem[] = [];
   for (const rem of rems) {
-    const markdownText = await plugin.richText.toMarkdown(rem.text ?? []);
+    const markdownText = await safeToMarkdown(plugin, rem.text ?? []);
     const isDocument = await rem.isDocument();
     results.push({
       remId: rem._id,

package/skills/remnote-bridge/instructions/read-context.md

@@ -27,7 +27,7 @@
 ### 人类模式
 
 ```bash
-remnote-bridge read-context [--mode <mode>] [--ancestor-levels <N>] [--depth <N>] [--max-nodes <N>] [--max-siblings <N>]
+remnote-bridge read-context [--mode <mode>] [--ancestor-levels <N>] [--depth <N>] [--max-nodes <N>] [--max-siblings <N>] [--focus-rem-id <remId>]
 ```
 
 | 参数/选项 | 类型 | 必需 | 说明 |
@@ -37,6 +37,7 @@ remnote-bridge read-context [--mode <mode>] [--ancestor-levels <N>] [--depth <N>
 | `--depth <N>` | integer | 否 | 展开深度（默认 3，仅 page 模式） |
 | `--max-nodes <N>` | integer | 否 | 全局节点上限（默认 200） |
 | `--max-siblings <N>` | integer | 否 | 每个父节点下展示的 children 上限（默认 20） |
+| `--focus-rem-id <remId>` | string | 否 | 指定鱼眼中心 Rem ID（仅 focus 模式，默认使用当前焦点） |
 
 Focus 模式输出示例：
 
@@ -73,6 +74,7 @@ Page 模式输出示例：
 
 ```bash
 remnote-bridge read-context --json '{"mode":"focus","ancestorLevels":3,"maxNodes":100}'
+remnote-bridge read-context --json '{"mode":"focus","focusRemId":"kLrIOHJLyMd8Y2lyA","ancestorLevels":2}'
 remnote-bridge read-context --json '{"mode":"page","depth":5,"maxSiblings":10}'
 ```
 
@@ -87,6 +89,7 @@ remnote-bridge read-context --json '{"mode":"page","depth":5,"maxSiblings":10}'
 | `depth` | number | 否 | 展开深度（默认 3，仅 page 模式） |
 | `maxNodes` | number | 否 | 全局节点上限（默认 200） |
 | `maxSiblings` | number | 否 | 每个父节点下展示的 children 上限（默认 20） |
+| `focusRemId` | string | 否 | 指定鱼眼中心 Rem ID（仅 focus 模式，默认使用当前焦点） |
 
 ---
 
@@ -124,7 +127,7 @@ remnote-bridge read-context --json '{"mode":"page","depth":5,"maxSiblings":10}'
 }
 ```
 
-### 无焦点 Rem（focus 模式）
+### 无焦点 Rem（focus 模式，未指定 focusRemId）
 
 ```json
 {
@@ -135,6 +138,28 @@ remnote-bridge read-context --json '{"mode":"page","depth":5,"maxSiblings":10}'
 }
 ```
 
+### focusRemId 指定的 Rem 不存在
+
+```json
+{
+  "ok": false,
+  "command": "read-context",
+  "error": "指定的 Rem 不存在: kLrIOHJLyMd8Y2lyA",
+  "timestamp": "2026-03-07T10:00:00.000Z"
+}
+```
+
+### page 模式下误传 focusRemId
+
+```json
+{
+  "ok": false,
+  "command": "read-context",
+  "error": "focusRemId 仅在 focus 模式下有效，page 模式下请勿指定",
+  "timestamp": "2026-03-07T10:00:00.000Z"
+}
+```
+
 ### 无打开的页面（page 模式）
 
 ```json
@@ -182,15 +207,15 @@ remnote-bridge read-context --json '{"mode":"page","depth":5,"maxSiblings":10}'
 ## 内部流程
 
 ```
-1. CLI 解析参数（mode, ancestorLevels, depth, maxNodes, maxSiblings）
+1. CLI 解析参数（mode, ancestorLevels, depth, maxNodes, maxSiblings, focusRemId）
 2. sendRequest → WS → daemon
 3. daemon ContextReadHandler:
    ├─ 合并配置默认值（config.ts）
-   └─ forwardToPlugin('read_context', { mode, ancestorLevels, depth, maxNodes, maxSiblings })
+   └─ forwardToPlugin('read_context', { mode, ancestorLevels, depth, maxNodes, maxSiblings, focusRemId })
 4. Plugin 端 readContext() 分支：
    │
    ├─ mode === 'focus' → readContextFocus():
-   │   ├─ plugin.focus.getFocusedRem() → 获取焦点 Rem
+   │   ├─ focusRemId ? plugin.rem.findOne(focusRemId) : plugin.focus.getFocusedRem() → 获取焦点 Rem
    │   ├─ 向上追溯 ancestorLevels 层 → ancestorPath[]
    │   ├─ buildBreadcrumb(plugin, focusRem) → 面包屑路径
    │   ├─ 从最顶层祖先开始递归 buildFisheyeNode()：
@@ -274,8 +299,8 @@ focus 模式的核心特点是**渐进式展开**——离焦点越近，展开
 
 | 维度 | focus 模式 | page 模式 |
 |:-----|:----------|:----------|
-| 触发点 | 当前焦点 Rem（光标位置） | 当前打开的页面 Rem |
-| SDK 入口 | `plugin.focus.getFocusedRem()` | `plugin.window.getFocusedPaneId()` → `getOpenPaneRemId()` |
+| 触发点 | 当前焦点 Rem 或指定 `focusRemId` | 当前打开的页面 Rem |
+| SDK 入口 | `focusRemId` ? `plugin.rem.findOne()` : `plugin.focus.getFocusedRem()` | `plugin.window.getFocusedPaneId()` → `getOpenPaneRemId()` |
 | 深度参数 | `ancestorLevels`（向上几层） | `depth`（向下几层） |
 | 展开策略 | 鱼眼（焦点完全展开，周围递减） | 均匀展开（全树同深度控制） |
 | 大纲头注释 | `<!-- path: ... -->` + `<!-- focus: Name (id) -->` | `<!-- page: Name -->` + `<!-- path: ... -->` |
@@ -345,7 +370,8 @@ focus 模式的核心特点是**渐进式展开**——离焦点越近，展开
 ## 注意事项
 
 - read-context **不缓存**结果——每次调用都重新从 SDK 获取最新数据
-- focus 模式需要用户在 RemNote 中有焦点 Rem（光标需在某个 Rem 上）
+- focus 模式需要用户在 RemNote 中有焦点 Rem（光标需在某个 Rem 上），或通过 `focusRemId` 指定任意 Rem 作为鱼眼中心
+- `focusRemId` 仅在 focus 模式下有效，page 模式下传入会报错
 - page 模式需要 RemNote 中有打开的页面
 - 输出使用 `createMinimalSerializableRem` 序列化，不包含 backText、practiceDirection 等详细信息
 - Powerup 过滤是硬编码的，无法通过参数关闭