remnote-bridge 0.1.0

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

@@ -0,0 +1,56 @@
+/**
+ * search service — 知识库文本搜索
+ *
+ * 同态命名：search (action) → search.ts (文件) → search (函数)
+ *
+ * 职责：调用 plugin.search.search() 搜索 Rem，返回结果列表
+ */
+
+import type { ReactRNPlugin } from '@remnote/plugin-sdk';
+
+export interface SearchPayload {
+  query: string;
+  numResults?: number;
+}
+
+export interface SearchResultItem {
+  remId: string;
+  text: string;
+  isDocument: boolean;
+}
+
+export interface SearchResult {
+  query: string;
+  results: SearchResultItem[];
+  totalFound: number;
+}
+
+export async function search(
+  plugin: ReactRNPlugin,
+  payload: SearchPayload,
+): Promise<SearchResult> {
+  const { query, numResults = 20 } = payload;
+
+  if (!query || query.trim() === '') {
+    throw new Error('search query 不能为空');
+  }
+
+  const rems = await plugin.search.search([query], undefined, { numResults });
+
+  const results: SearchResultItem[] = [];
+  for (const rem of rems) {
+    const markdownText = await plugin.richText.toMarkdown(rem.text ?? []);
+    const isDocument = await rem.isDocument();
+    results.push({
+      remId: rem._id,
+      text: markdownText.replace(/\n/g, ' '),
+      isDocument,
+    });
+  }
+
+  return {
+    query,
+    results,
+    totalFound: results.length,
+  };
+}

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

@@ -0,0 +1,254 @@
+/**
+ * write-rem-fields service — 按字段写入 SDK
+ *
+ * 内部 action（daemon 编排用），无对应 CLI 命令。
+ * 接收 { remId, changes } payload，按顺序逐字段调用 SDK setter。
+ * 首个失败即终止，返回已成功和失败的字段信息。
+ *
+ * 同态命名例外：write_rem_fields (action) → write-rem-fields.ts (文件) → writeRemFields (函数)
+ * 原因：edit-rem CLI 命令的编排逻辑在 daemon 层，Plugin 只负责原子写入。
+ */
+
+import type { ReactRNPlugin, PluginRem as Rem, RichTextInterface } from '@remnote/plugin-sdk';
+
+export interface WriteRemFieldsPayload {
+  remId: string;
+  changes: Record<string, unknown>;
+}
+
+export interface WriteRemFieldsResult {
+  applied: string[];
+  failed?: { field: string; error: string };
+}
+
+/**
+ * 逐字段写入 SDK。
+ *
+ * @throws Error — Rem 不存在时抛 "Rem not found"
+ */
+export async function writeRemFields(
+  plugin: ReactRNPlugin,
+  payload: WriteRemFieldsPayload,
+): Promise<WriteRemFieldsResult> {
+  const rem = await plugin.rem.findOne(payload.remId);
+  if (!rem) {
+    throw new Error(`Rem not found: ${payload.remId}`);
+  }
+
+  const applied: string[] = [];
+  const changes = payload.changes;
+
+  // parent 和 positionAmongstSiblings 联动处理
+  // 如果两者都在 changes 中，合并为一次 setParent 调用
+  const hasParent = 'parent' in changes;
+  const hasPosition = 'positionAmongstSiblings' in changes;
+
+  for (const field of Object.keys(changes)) {
+    // 跳过 positionAmongstSiblings（已与 parent 合并处理）
+    if (field === 'positionAmongstSiblings') {
+      continue;
+    }
+
+    try {
+      await applyField(rem, plugin, field, changes[field], {
+        // 当 parent 变更时，附带 position
+        position: field === 'parent' && hasPosition
+          ? changes.positionAmongstSiblings as number | undefined
+          : undefined,
+      });
+      applied.push(field);
+      // 如果 parent 变更时附带了 position，也标记 position 已 applied
+      if (field === 'parent' && hasPosition) {
+        applied.push('positionAmongstSiblings');
+      }
+    } catch (err) {
+      return {
+        applied,
+        failed: {
+          field,
+          error: err instanceof Error ? err.message : String(err),
+        },
+      };
+    }
+  }
+
+  // 如果只有 positionAmongstSiblings 没有 parent，单独处理
+  if (hasPosition && !hasParent) {
+    try {
+      const parent = rem.parent;
+      if (parent) {
+        await rem.setParent(parent, changes.positionAmongstSiblings as number);
+      }
+      applied.push('positionAmongstSiblings');
+    } catch (err) {
+      return {
+        applied,
+        failed: {
+          field: 'positionAmongstSiblings',
+          error: err instanceof Error ? err.message : String(err),
+        },
+      };
+    }
+  }
+
+  return { applied };
+}
+
+// ── 字段 → SDK setter 映射 ──
+
+async function applyField(
+  rem: Rem,
+  plugin: ReactRNPlugin,
+  field: string,
+  value: unknown,
+  opts: { position?: number | undefined },
+): Promise<void> {
+  // 值来自 JSON 反序列化，类型为 unknown，需要显式转型到 SDK 期望的字面量/接口类型
+  switch (field) {
+    // 内容
+    case 'text':
+      await rem.setText(value as RichTextInterface);
+      break;
+    case 'backText':
+      if (value === null) {
+        await rem.setBackText([]);
+      } else if (typeof value === 'string') {
+        // 从 edit-tree 箭头分隔符解析出的 backText 是纯文本字符串，
+        // 需要包装为 RichText 数组才能被 SDK 接受
+        await rem.setBackText([value]);
+      } else {
+        await rem.setBackText(value as RichTextInterface);
+      }
+      break;
+
+    // 类型系统
+    case 'type':
+      await rem.setType(remTypeStringToEnum(value as string) as any);
+      break;
+    case 'isDocument':
+      await rem.setIsDocument(value as boolean);
+      break;
+
+    // 结构
+    case 'parent':
+      await rem.setParent(value as string, opts.position);
+      break;
+
+    // 格式 / 显示
+    case 'fontSize':
+      await rem.setFontSize(value === null ? undefined : value as 'H1' | 'H2' | 'H3');
+      break;
+    case 'highlightColor':
+      if (value === null) {
+        // setHighlightColor(null) 被 SDK 拒绝，通过 removePowerup('h') 从底层移除高亮 Tag
+        await rem.removePowerup('h');
+      } else {
+        await rem.setHighlightColor(value as 'Red' | 'Orange' | 'Yellow' | 'Green' | 'Blue' | 'Purple');
+      }
+      break;
+
+    // 状态标记
+    case 'isTodo':
+      await rem.setIsTodo(value as boolean);
+      break;
+    case 'todoStatus':
+      if (value !== null) {
+        await rem.setTodoStatus(value as 'Finished' | 'Unfinished');
+      }
+      // null → 跳过：todoStatus=null 的语义是"非 todo"，应通过 isTodo=false 实现
+      break;
+    case 'isCode':
+      await rem.setIsCode(value as boolean);
+      break;
+    case 'isQuote':
+      await rem.setIsQuote(value as boolean);
+      break;
+    case 'isListItem':
+      await rem.setIsListItem(value as boolean);
+      break;
+    case 'isCardItem':
+      await rem.setIsCardItem(value as boolean);
+      break;
+    case 'isSlot':
+      await rem.setIsSlot(value as boolean);
+      break;
+    case 'isProperty':
+      await rem.setIsProperty(value as boolean);
+      break;
+
+    // 练习设置
+    case 'enablePractice':
+      await rem.setEnablePractice(value as boolean);
+      break;
+    case 'practiceDirection':
+      await rem.setPracticeDirection(value as 'forward' | 'backward' | 'both' | 'none');
+      break;
+
+    // 关联 — tags（diff based）
+    case 'tags':
+      await applyTagsDiff(rem, value as string[]);
+      break;
+
+    // 关联 — sources（diff based）
+    case 'sources':
+      await applySourcesDiff(rem, value as string[]);
+      break;
+
+    // Powerup 操作
+    case 'addPowerup':
+      await rem.addPowerup(value as string);
+      break;
+
+    default:
+      throw new Error(`不可写入的字段: ${field}`);
+  }
+}
+
+// ── 辅助函数 ──
+
+/** tags diff: 对比当前和目标，计算 add/remove */
+async function applyTagsDiff(rem: Rem, targetIds: string[]): Promise<void> {
+  const currentTags = await rem.getTagRems();
+  const currentIds = new Set(currentTags.map((r: Rem) => r._id));
+  const targetSet = new Set(targetIds);
+
+  for (const id of targetIds) {
+    if (!currentIds.has(id)) {
+      await rem.addTag(id as string);
+    }
+  }
+  for (const id of currentIds) {
+    if (!targetSet.has(id as string)) {
+      await rem.removeTag(id as string);
+    }
+  }
+}
+
+/** sources diff: 对比当前和目标，计算 add/remove */
+async function applySourcesDiff(rem: Rem, targetIds: string[]): Promise<void> {
+  const currentSources = await rem.getSources();
+  const currentIds = new Set(currentSources.map((r: Rem) => r._id));
+  const targetSet = new Set(targetIds);
+
+  for (const id of targetIds) {
+    if (!currentIds.has(id)) {
+      await rem.addSource(id as string);
+    }
+  }
+  for (const id of currentIds) {
+    if (!targetSet.has(id as string)) {
+      await rem.removeSource(id as string);
+    }
+  }
+}
+
+/** 字符串类型值 → SDK SetRemType 枚举数值。Portal 不可通过 setType() 设置。 */
+function remTypeStringToEnum(type: string): 1 | 2 | 'DEFAULT_TYPE' {
+  switch (type) {
+    case 'concept': return 1;
+    case 'descriptor': return 2;
+    case 'default': return 'DEFAULT_TYPE';
+    case 'portal': throw new Error('Portal 不可通过 setType() 设置，只能通过 createPortal() 创建');
+    default: throw new Error(`未知的 Rem 类型: ${type}`);
+  }
+}

package/remnote-plugin/src/settings.ts

@@ -0,0 +1,12 @@
+/**
+ * Plugin 设置常量
+ *
+ * 定义 RemNote 设置面板中的设置项 ID 和默认值。
+ */
+
+// 设置项 ID
+export const SETTING_WS_URL = 'bridge-ws-url';
+
+// 默认值
+export const DEFAULT_WS_URL = 'ws://127.0.0.1:3002';
+export const DEFAULT_PLUGIN_VERSION = '0.1.0';

package/remnote-plugin/src/style.css

@@ -0,0 +1,45 @@
+/*
+ * This file contains the tailwind directives and equivalent styles
+ * to replicate the behavior inside the Shadow DOM of native plugins.
+ */
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/*
+1. Use a consistent sensible line-height in all browsers.
+2. Prevent adjustments of font size after orientation changes in iOS.
+3. Use a more readable tab size.
+*/
+
+html,
+:host-context(div) {
+  line-height: 1.5; /* 1 */
+  -webkit-text-size-adjust: 100%; /* 2 */
+  -moz-tab-size: 4; /* 3 */
+  tab-size: 4; /* 3 */
+}
+
+/*
+1. Remove the margin in all browsers.
+2. Inherit line-height from `html` so users can set them as a class directly on the `html` element.
+*/
+
+body,
+:host {
+  margin: 0; /* 1 */
+  line-height: inherit; /* 2 */
+}
+
+/**
+*/
+
+body,
+:host {
+  margin: 0;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu',
+    'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}

package/remnote-plugin/src/test-scripts/AGENTS.md

@@ -0,0 +1,46 @@
+# test-scripts — RemNote Plugin SDK 探测脚本
+
+## 这是什么
+
+一次性探测脚本，用于在 RemNote Plugin 运行时环境中验证 SDK 行为。
+脚本运行后将结果写入 RemNote 知识库（"mcp 测试" 文档下），供人工或 CLI 读取。
+
+## 为什么在 src/ 下
+
+这些脚本**必须**在 RemNote Plugin 沙箱内执行（依赖 `plugin: ReactRNPlugin` 对象调用 SDK API），
+所以必须被 webpack 打包。但它们**不是生产代码**——数据收集完毕后，应从 `widgets/index.tsx` 中注释掉 import 和调用，避免打包进生产 bundle。
+
+## 当前状态
+
+所有脚本已完成数据收集，`widgets/index.tsx` 中的 import 和调用**已注释掉**。
+
+## 运行机制
+
+1. 脚本通过 `widgets/index.tsx` 的 `onActivate()` 调用
+2. 每个脚本用 `plugin.storage.getSession(key)` 做防重跑检查（同一会话只跑一次）
+3. 执行流程：找到 "mcp 测试" 文档 → 创建隔离 wrapper Rem → 逐项测试 → 结果写入子 Rem
+4. 刷新 RemNote 页面即触发运行（session storage 随页面刷新重置）
+
+## 如何重跑
+
+1. 在 `widgets/index.tsx` 中取消对应 import 和调用的注释
+2. 启动 dev server：`cd remnote-plugin && npm run dev`
+3. 刷新 RemNote 页面
+
+## 脚本清单
+
+| 文件 | 探测内容 | 产出 |
+|:--|:--|:--|
+| `test-actions.ts` | Rem CRUD 操作（create/remove/merge/collapse 等） | 各操作成功/失败记录 |
+| `test-rw-fields.ts` | Rem 字段读写（highlightColor、backText 等） | 字段读写兼容性 |
+| `test-richtext-builder.ts` | RichText Builder API 输出结构（video/audio） | Builder 产出的 JSON 对照 |
+| `test-richtext-remaining.ts` | RichText 剩余未测字段（cId、qId、block、title、i:"g" 等） | 各字段写入+回读结果 |
+| `test-richtext-matrix.ts` | 7 种元素类型 × 12 种格式化字段交叉兼容性 | 84 格矩阵（72✅ 12❌ 0⚠️） |
+
+## 编写新脚本的约定
+
+- 导出一个 `async function run...(plugin: ReactRNPlugin): Promise<void>`
+- 用 `plugin.storage.getSession/setSession` 做防重跑
+- 创建 wrapper Rem 隔离测试数据，避免污染其他测试
+- 每个测试项单独 try/catch，不要因一项失败中断全部
+- 最终汇总写入一个 JSON Rem，方便 CLI `read-rem` 机器读取

package/remnote-plugin/src/test-scripts/test-actions.ts

@@ -0,0 +1,230 @@
+/**
+ * 纯动作方法 (W) 行为观察测试
+ *
+ * 测试流程：创建初态 → 暂停（截图初态）→ 执行动作 → 暂停（截图终态）
+ * 测试的动作方法：remove / indent / outdent / merge / collapse / expand / addToPortal
+ */
+import type { ReactRNPlugin, PluginRem as Rem } from '@remnote/plugin-sdk';
+
+async function delay(ms: number) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+export async function runActionTests(plugin: ReactRNPlugin): Promise<void> {
+  const alreadyRan = await plugin.storage.getSession('action-test-v1-ran');
+  if (alreadyRan) {
+    console.log('[ACTION-TEST] 已运行过，跳过');
+    return;
+  }
+  await plugin.storage.setSession('action-test-v1-ran', true);
+
+  console.log('[ACTION-TEST] ========== 开始纯动作行为观察 ==========');
+
+  try {
+    // ── 找到 "mcp 测试" 文档 ──
+    const allRem = await plugin.rem.getAll();
+    let parentDoc: Rem | undefined;
+    for (const r of allRem) {
+      const t = r.text ? await plugin.richText.toString(r.text) : '';
+      if (t.trim() === 'mcp 测试') { parentDoc = r; break; }
+    }
+    if (!parentDoc) { console.error('[ACTION-TEST] 找不到 "mcp 测试"'); return; }
+
+    // ── 状态指示 Rem ──
+    const statusRem = await plugin.rem.createRem();
+    if (!statusRem) return;
+    await statusRem.setParent(parentDoc._id, 0);
+    await statusRem.setHighlightColor('Yellow');
+    await statusRem.setText(['⏳ 动作测试：正在创建初态...']);
+    await delay(300);
+
+    let pos = 1;
+
+    // ═══════════════════════════════════════════════════
+    //  创建所有初态 Rem
+    // ═══════════════════════════════════════════════════
+
+    // --- 1. remove() 测试 ---
+    const removeLabel = await plugin.rem.createRem();
+    if (!removeLabel) return;
+    await removeLabel.setParent(parentDoc._id, pos++);
+    await removeLabel.setText(['── 1. remove() 测试 ──']);
+    await delay(200);
+
+    const removeTarget = await plugin.rem.createRem();
+    if (!removeTarget) return;
+    await removeTarget.setParent(parentDoc._id, pos++);
+    await removeTarget.setHighlightColor('Red');
+    await removeTarget.setText(['❌ 这个 Rem 将被 remove() 删除']);
+    await delay(200);
+
+    // --- 2. indent() 测试 ---
+    const indentLabel = await plugin.rem.createRem();
+    if (!indentLabel) return;
+    await indentLabel.setParent(parentDoc._id, pos++);
+    await indentLabel.setText(['── 2. indent() 测试 ──']);
+    await delay(200);
+
+    const indentParent = await plugin.rem.createRem();
+    if (!indentParent) return;
+    await indentParent.setParent(parentDoc._id, pos++);
+    await indentParent.setText(['indent 的上方兄弟（将变成父级）']);
+    await delay(200);
+
+    const indentTarget = await plugin.rem.createRem();
+    if (!indentTarget) return;
+    await indentTarget.setParent(parentDoc._id, pos++);
+    await indentTarget.setHighlightColor('Orange');
+    await indentTarget.setText(['→ 这个 Rem 将被 indent()（向右缩进）']);
+    await delay(200);
+
+    // --- 3. outdent() 测试 ---
+    const outdentLabel = await plugin.rem.createRem();
+    if (!outdentLabel) return;
+    await outdentLabel.setParent(parentDoc._id, pos++);
+    await outdentLabel.setText(['── 3. outdent() 测试 ──']);
+    await delay(200);
+
+    const outdentWrapper = await plugin.rem.createRem();
+    if (!outdentWrapper) return;
+    await outdentWrapper.setParent(parentDoc._id, pos++);
+    await outdentWrapper.setText(['outdent 的当前父级']);
+    await delay(200);
+
+    const outdentTarget = await plugin.rem.createRem();
+    if (!outdentTarget) return;
+    await outdentTarget.setParent(outdentWrapper._id, 0); // 作为子级
+    await outdentTarget.setHighlightColor('Orange');
+    await outdentTarget.setText(['← 这个子 Rem 将被 outdent()（向左提升）']);
+    await delay(200);
+
+    // --- 4. merge() 测试 ---
+    const mergeLabel = await plugin.rem.createRem();
+    if (!mergeLabel) return;
+    await mergeLabel.setParent(parentDoc._id, pos++);
+    await mergeLabel.setText(['── 4. merge() 测试 ──']);
+    await delay(200);
+
+    const mergeKeep = await plugin.rem.createRem();
+    if (!mergeKeep) return;
+    await mergeKeep.setParent(parentDoc._id, pos++);
+    await mergeKeep.setHighlightColor('Green');
+    await mergeKeep.setText(['保留的 Rem（merge 目标）']);
+    await delay(200);
+
+    const mergeDisappear = await plugin.rem.createRem();
+    if (!mergeDisappear) return;
+    await mergeDisappear.setParent(parentDoc._id, pos++);
+    await mergeDisappear.setHighlightColor('Red');
+    await mergeDisappear.setText(['将被合并消失的 Rem']);
+    await delay(200);
+
+    // --- 5. collapse() / expand() 测试 ---
+    const collapseLabel = await plugin.rem.createRem();
+    if (!collapseLabel) return;
+    await collapseLabel.setParent(parentDoc._id, pos++);
+    await collapseLabel.setText(['── 5. collapse()/expand() 测试 ──']);
+    await delay(200);
+
+    const collapseParent = await plugin.rem.createRem();
+    if (!collapseParent) return;
+    await collapseParent.setParent(parentDoc._id, pos++);
+    await collapseParent.setHighlightColor('Blue');
+    await collapseParent.setText(['将被 collapse() 的父 Rem']);
+    await delay(200);
+
+    // 给它创建 3 个子级
+    for (let i = 1; i <= 3; i++) {
+      const child = await plugin.rem.createRem();
+      if (child) {
+        await child.setParent(collapseParent._id, i - 1);
+        await child.setText([`子级 ${i}（collapse 后应隐藏）`]);
+        await delay(150);
+      }
+    }
+
+    // --- 6. addToPortal() 测试 ---
+    const portalLabel = await plugin.rem.createRem();
+    if (!portalLabel) return;
+    await portalLabel.setParent(parentDoc._id, pos++);
+    await portalLabel.setText(['── 6. addToPortal() 测试 ──']);
+    await delay(200);
+
+    const portalTarget = await plugin.rem.createRem();
+    if (!portalTarget) return;
+    await portalTarget.setParent(parentDoc._id, pos++);
+    await portalTarget.setHighlightColor('Purple');
+    await portalTarget.setText(['将被添加到 Portal 的 Rem']);
+    await delay(200);
+
+    // 创建一个 Portal
+    const portal = await plugin.rem.createPortal();
+    if (portal) {
+      await portal.setParent(parentDoc._id, pos++);
+      await delay(200);
+    }
+
+    // ═══════════════════════════════════════════════════
+    //  初态就绪，暂停 15 秒供截图
+    // ═══════════════════════════════════════════════════
+    await statusRem.setText(['📸 初态就绪！请截图（15 秒后执行动作）']);
+    console.log('[ACTION-TEST] ===== 初态就绪，等待 15 秒截图 =====');
+    await delay(15000);
+
+    // ═══════════════════════════════════════════════════
+    //  逐个执行动作
+    // ═══════════════════════════════════════════════════
+    await statusRem.setText(['⚡ 正在执行动作...']);
+
+    // 1. remove()
+    console.log('[ACTION-TEST] 执行 remove()');
+    await removeTarget.remove();
+    await delay(500);
+
+    // 2. indent()
+    console.log('[ACTION-TEST] 执行 indent()');
+    await indentTarget.indent();
+    await delay(500);
+
+    // 3. outdent()
+    console.log('[ACTION-TEST] 执行 outdent()');
+    await outdentTarget.outdent();
+    await delay(500);
+
+    // 4. merge() — 把 mergeDisappear 合并到 mergeKeep
+    console.log('[ACTION-TEST] 执行 merge()');
+    await mergeKeep.merge(mergeDisappear._id);
+    await delay(500);
+
+    // 5. collapse()
+    console.log('[ACTION-TEST] 执行 collapse()');
+    await collapseParent.collapse();
+    await delay(500);
+
+    // 6. addToPortal()
+    if (portal) {
+      console.log('[ACTION-TEST] 执行 addToPortal()');
+      await portalTarget.addToPortal(portal);
+      await delay(500);
+    }
+
+    // ═══════════════════════════════════════════════════
+    //  动作执行完毕，暂停供截图
+    // ═══════════════════════════════════════════════════
+    await statusRem.setText(['📸 全部动作已执行！请截图观察终态']);
+    await statusRem.setHighlightColor('Green');
+    console.log('[ACTION-TEST] ===== 全部动作已执行，请截图终态 =====');
+
+    // 20 秒后执行 expand() 让 collapse 的效果能对比
+    await delay(20000);
+    console.log('[ACTION-TEST] 执行 expand()（恢复折叠）');
+    const refetchCollapse = await plugin.rem.findOne(collapseParent._id);
+    if (refetchCollapse) {
+      await refetchCollapse.expand();
+    }
+    await statusRem.setText(['📸 expand() 已执行，子级应重新可见']);
+
+  } catch (err) {
+    console.error('[ACTION-TEST] 出错:', err);
+  }
+}