remnote-bridge 0.1.0

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

@@ -0,0 +1,284 @@
+/**
+ * read-rem service — 从 SDK 组装完整 RemObject
+ *
+ * 按 RemObject 接口的字段声明顺序组装对象（确定性序列化）。
+ * RichText 元素内部按 key 字母序排列。
+ *
+ * 同态命名：read_rem (action) → read-rem.ts (文件) → readRem (函数)
+ */
+
+import type { ReactRNPlugin, PluginRem as Rem } from '@remnote/plugin-sdk';
+import type {
+  RemObject,
+  RichText,
+  RemTypeValue,
+  PortalType,
+  PropertyTypeValue,
+} from '../types';
+import { filterNoisyChildren, filterNoisyTags } from './powerup-filter';
+
+/**
+ * 读取单个 Rem，组装为完整 RemObject。
+ *
+ * @throws Error — Rem 不存在时抛 "Rem not found"
+ */
+export async function readRem(
+  plugin: ReactRNPlugin,
+  payload: { remId: string; includePowerup?: boolean },
+): Promise<RemObject & { powerupFiltered?: { tags: number; children: number } }> {
+  const { includePowerup = false } = payload;
+  const rem = await plugin.rem.findOne(payload.remId);
+  if (!rem) {
+    throw new Error(`Rem not found: ${payload.remId}`);
+  }
+
+  // 并行获取所有异步字段
+  const [
+    isDocument,
+    fontSize,
+    highlightColor,
+    isTodo,
+    todoStatus,
+    isCode,
+    isQuote,
+    isListItem,
+    isCardItem,
+    isTable,
+    isSlot,
+    isProperty,
+    enablePractice,
+    practiceDirection,
+    tagRems,
+    sourceRems,
+    aliasRems,
+    position,
+    // R-F boolean fields
+    isPowerup,
+    isPowerupEnum,
+    isPowerupProperty,
+    isPowerupPropertyListItem,
+    isPowerupSlot,
+    // Portal
+    portalType,
+    portalDirectlyIncludedRems,
+    // Property
+    propertyType,
+    // References
+    refsBeingReferenced,
+    deepRefsBeingReferenced,
+    refsReferencingThis,
+    // Tags hierarchy
+    taggedRems,
+    ancestorTagRems,
+    descendantTagRems,
+    // Hierarchy traversal
+    descendantRems,
+    siblingRems,
+    portalsAndDocsIn,
+    allRemInDocOrPortal,
+    allRemInFolderQ,
+    // Children (for powerup filtering)
+    childrenRems,
+    // Stats
+    timesSelected,
+    lastMovedTo,
+    schemaVer,
+    embeddedQueueView,
+    lastPracticed,
+  ] = await Promise.all([
+    rem.isDocument(),
+    rem.getFontSize(),
+    rem.getHighlightColor(),
+    rem.isTodo(),
+    rem.getTodoStatus(),
+    rem.isCode(),
+    rem.isQuote(),
+    rem.isListItem(),
+    rem.isCardItem(),
+    rem.isTable(),
+    rem.isSlot(),
+    rem.isProperty(),
+    rem.getEnablePractice(),
+    rem.getPracticeDirection(),
+    rem.getTagRems(),
+    rem.getSources(),
+    rem.getAliases(),
+    rem.positionAmongstSiblings(),
+    // R-F boolean fields
+    rem.isPowerup(),
+    rem.isPowerupEnum(),
+    rem.isPowerupProperty(),
+    rem.isPowerupPropertyListItem(),
+    rem.isPowerupSlot(),
+    // Portal
+    rem.getPortalType(),
+    rem.getPortalDirectlyIncludedRem(),
+    // Property
+    rem.getPropertyType(),
+    // References
+    rem.remsBeingReferenced(),
+    rem.deepRemsBeingReferenced(),
+    rem.remsReferencingThis(),
+    // Tags hierarchy
+    rem.taggedRem(),
+    rem.ancestorTagRem(),
+    rem.descendantTagRem(),
+    // Hierarchy traversal
+    rem.getDescendants(),
+    rem.siblingRem(),
+    rem.portalsAndDocumentsIn(),
+    rem.allRemInDocumentOrPortal(),
+    rem.allRemInFolderQueue(),
+    // Children (for powerup filtering)
+    rem.getChildrenRem(),
+    // Stats
+    rem.timesSelectedInSearch(),
+    rem.getLastTimeMovedTo(),
+    rem.getSchemaVersion(),
+    rem.embeddedQueueViewMode(),
+    rem.getLastPracticed(),
+  ]);
+
+  // Powerup 噪音过滤
+  let filteredTagRems = tagRems;
+  let filteredChildrenIds = rem.children ?? [];
+  let filteredTagCount = 0;
+  let filteredChildCount = 0;
+
+  if (!includePowerup) {
+    filteredTagRems = await filterNoisyTags(tagRems);
+    filteredTagCount = tagRems.length - filteredTagRems.length;
+
+    const filteredChildren = await filterNoisyChildren(childrenRems);
+    filteredChildCount = childrenRems.length - filteredChildren.length;
+    filteredChildrenIds = filteredChildren.map(r => r._id);
+  }
+
+  // 按 RemObject 接口字段声明顺序组装（确定性序列化）
+  const remObject: RemObject = {
+    // 核心标识
+    id: rem._id,
+
+    // 内容
+    text: sortRichTextKeys(rem.text ?? []),
+    backText: rem.backText ? sortRichTextKeys(rem.backText) : null,
+
+    // 类型系统
+    type: remTypeToString(rem.type as number),
+    isDocument,
+
+    // 结构
+    parent: rem.parent,
+    children: filteredChildrenIds,
+
+    // 格式 / 显示
+    fontSize: (fontSize as RemObject['fontSize']) ?? null,
+    highlightColor: (highlightColor as RemObject['highlightColor']) ?? null,
+
+    // 状态标记
+    isTodo,
+    todoStatus: (todoStatus as RemObject['todoStatus']) ?? null,
+    isCode,
+    isQuote,
+    isListItem,
+    isCardItem,
+    isTable: Boolean(isTable),
+    isSlot,
+    isProperty,
+    isPowerup,
+    isPowerupEnum,
+    isPowerupProperty,
+    isPowerupPropertyListItem,
+    isPowerupSlot,
+
+    // Portal 专用
+    portalType: remTypeToString(rem.type as number) === 'portal'
+      ? portalTypeToString(portalType as number)
+      : null,
+    portalDirectlyIncludedRem: portalDirectlyIncludedRems.map(r => r._id),
+
+    // 属性类型
+    propertyType: (propertyType as PropertyTypeValue | undefined) ?? null,
+
+    // 练习设置
+    enablePractice,
+    practiceDirection: practiceDirection as RemObject['practiceDirection'],
+
+    // 关联 — 直接关系
+    tags: filteredTagRems.map(r => r._id),
+    sources: sourceRems.map(r => r._id),
+    aliases: aliasRems.map(r => r._id),
+
+    // 关联 — 引用关系
+    remsBeingReferenced: refsBeingReferenced.map(r => r._id),
+    deepRemsBeingReferenced: deepRefsBeingReferenced.map(r => r._id),
+    remsReferencingThis: refsReferencingThis.map(r => r._id),
+
+    // 关联 — 标签体系
+    taggedRem: taggedRems.map(r => r._id),
+    ancestorTagRem: ancestorTagRems.map(r => r._id),
+    descendantTagRem: descendantTagRems.map(r => r._id),
+
+    // 关联 — 层级遍历
+    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),
+
+    // 位置 / 统计
+    positionAmongstSiblings: position ?? null,
+    timesSelectedInSearch: timesSelected,
+    lastTimeMovedTo: lastMovedTo,
+    schemaVersion: schemaVer,
+
+    // 队列视图
+    embeddedQueueViewMode: embeddedQueueView,
+
+    // 元数据 / 时间戳
+    createdAt: rem.createdAt,
+    updatedAt: rem.updatedAt,
+    localUpdatedAt: rem.localUpdatedAt,
+    lastPracticed,
+  };
+
+  if (!includePowerup && (filteredTagCount > 0 || filteredChildCount > 0)) {
+    return { ...remObject, powerupFiltered: { tags: filteredTagCount, children: filteredChildCount } };
+  }
+
+  return remObject;
+}
+
+// ── 辅助函数 ──
+
+/** 对 RichText 元素内部按 key 字母序排列（确定性序列化） */
+function sortRichTextKeys(rt: RichText): RichText {
+  return rt.map(el => {
+    if (typeof el === 'string') return el;
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(el).sort()) {
+      sorted[key] = el[key];
+    }
+    return sorted;
+  });
+}
+
+/** SDK RemType 枚举值 → 字符串 */
+function remTypeToString(type: number): RemTypeValue {
+  switch (type) {
+    case 1: return 'concept';
+    case 2: return 'descriptor';
+    case 6: return 'portal';
+    default: return 'default';
+  }
+}
+
+/** SDK PORTAL_TYPE 枚举值 → 字符串 */
+function portalTypeToString(pt: number): PortalType {
+  switch (pt) {
+    case 2: return 'embedded_queue';
+    case 3: return 'scaffold';
+    case 4: return 'search_portal';
+    default: return 'portal';
+  }
+}

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

@@ -0,0 +1,222 @@
+/**
+ * read-tree service — 递归遍历子树并序列化为 Markdown 大纲
+ *
+ * 同态命名：read_tree (action) → read-tree.ts (文件) → readTree (函数)
+ *
+ * 职责：
+ * 1. 从根 Rem 递归遍历子树（受 depth 限制）
+ * 2. 对每个 Rem 调用 SDK API 获取序列化所需数据
+ * 3. 调用 utils/tree-serializer 纯函数拼接为大纲文本
+ */
+
+import type { ReactRNPlugin, PluginRem as Rem } from '@remnote/plugin-sdk';
+import {
+  type OutlineNode,
+  type TreeNode,
+  type ElidedNode,
+  buildOutline,
+} from '../utils/tree-serializer';
+import { filterNoisyChildren } from './powerup-filter';
+import { sliceSiblings } from '../utils/elision';
+import { buildFullSerializableRem, sanitizeNewlines } from './rem-builder';
+
+export interface ReadTreePayload {
+  remId: string;
+  depth?: number;
+  maxNodes?: number;
+  maxSiblings?: number;
+  ancestorLevels?: number;
+  includePowerup?: boolean;
+}
+
+/** 祖先节点信息（从直接父亲到最远祖先，由近及远） */
+export interface AncestorInfo {
+  id: string;
+  name: string;
+  childrenCount: number;
+  isDocument: boolean;
+  isTopLevel?: boolean;
+}
+
+export interface ReadTreeResult {
+  rootId: string;
+  depth: number;
+  nodeCount: number;
+  outline: string;
+  /** 祖先链（从直接父亲到最远祖先，由近及远） */
+  ancestors?: AncestorInfo[];
+  powerupFiltered?: { tags: number; children: number };
+}
+
+/**
+ * 读取 Rem 子树并序列化为 Markdown 大纲。
+ *
+ * @throws Error — Rem 不存在、节点数超限
+ */
+export async function readTree(
+  plugin: ReactRNPlugin,
+  payload: ReadTreePayload,
+): Promise<ReadTreeResult> {
+  const {
+    remId,
+    depth = 3,
+    maxNodes = 200,
+    maxSiblings = 20,
+    ancestorLevels = 0,
+    includePowerup = false,
+  } = payload;
+
+  const rootRem = await plugin.rem.findOne(remId);
+  if (!rootRem) {
+    throw new Error(`Rem not found: ${remId}`);
+  }
+
+  let nodeCount = 0;
+  let totalFilteredTags = 0;
+  let totalFilteredChildren = 0;
+  const budget = { remaining: maxNodes };
+
+  /**
+   * 递归构建 OutlineNode 树。
+   *
+   * @param rem SDK Rem 对象
+   * @param currentDepth 当前相对于根的深度（根 = 0）
+   * @param maxDepth 最大展开深度（-1 = 无限）
+   */
+  async function buildNode(rem: Rem, currentDepth: number, maxDepth: number): Promise<OutlineNode> {
+    nodeCount++;
+    budget.remaining--;
+
+    const allChildren = await rem.getChildrenRem();
+    const children = includePowerup ? allChildren : await filterNoisyChildren(allChildren);
+    if (!includePowerup) totalFilteredChildren += allChildren.length - children.length;
+    const shouldFold = maxDepth !== -1 && currentDepth >= maxDepth;
+    const folded = shouldFold && children.length > 0;
+
+    const serializable = await buildFullSerializableRem(plugin, rem, children, {
+      includePowerup,
+      onFilteredTags: (count) => { totalFilteredTags += count; },
+    });
+
+    // 折叠时无法确定 multiline，保守设为 false
+    if (folded) {
+      serializable.hasMultilineChildren = false;
+    }
+
+    // 递归处理子节点（带省略逻辑）
+    const childNodes: TreeNode[] = [];
+    if (!folded) {
+      // Sibling 省略
+      const { visibleIndices, elided } = sliceSiblings(children.length, maxSiblings, rem._id);
+
+      if (visibleIndices) {
+        // 有省略：展示前 head + 省略占位 + 后 tail
+        const { head, tail } = visibleIndices;
+
+        // 前 head 个
+        for (let i = 0; i < head && budget.remaining > 0; i++) {
+          childNodes.push(await buildNode(children[i], currentDepth + 1, maxDepth));
+        }
+
+        // 省略占位符
+        if (elided) {
+          // 判断 isExact：被省略的节点如果有子节点，则不精确
+          // 保守策略：只要 depth 未到底，就标记为非精确
+          const atMaxDepth = maxDepth !== -1 && currentDepth + 1 >= maxDepth;
+          childNodes.push({
+            type: 'elided',
+            count: elided.count,
+            isExact: atMaxDepth, // 到底了就是精确的（不会有更多后代）
+            parentId: elided.parentId,
+            rangeFrom: elided.rangeFrom,
+            rangeTo: elided.rangeTo,
+            totalSiblings: elided.totalSiblings,
+          } as ElidedNode);
+        }
+
+        // 后 tail 个
+        const tailStart = children.length - tail;
+        for (let i = tailStart; i < children.length && budget.remaining > 0; i++) {
+          childNodes.push(await buildNode(children[i], currentDepth + 1, maxDepth));
+        }
+      } else {
+        // 无 sibling 省略：正常遍历，但需检查全局预算
+        for (let i = 0; i < children.length; i++) {
+          if (budget.remaining <= 0) {
+            // 全局预算耗尽：剩余 children 生成一个省略占位符
+            const remainCount = children.length - i;
+            childNodes.push({
+              type: 'elided',
+              count: remainCount,
+              isExact: false, // 可能还有后代
+              parentId: rem._id,
+              rangeFrom: i,
+              rangeTo: children.length - 1,
+              totalSiblings: children.length,
+            } as ElidedNode);
+            break;
+          }
+          childNodes.push(await buildNode(children[i], currentDepth + 1, maxDepth));
+        }
+      }
+    }
+
+    return { rem: serializable, children: childNodes, folded };
+  }
+
+  const rootNode = await buildNode(rootRem, 0, depth);
+
+  // 检测根节点是否为顶级 Rem（无父节点）
+  const rootParent = await rootRem.getParentRem();
+  if (!rootParent) {
+    rootNode.rem.isTopLevel = true;
+  }
+
+  const outline = buildOutline(rootNode);
+
+  const result: ReadTreeResult = {
+    rootId: remId,
+    depth,
+    nodeCount,
+    outline,
+  };
+
+  // 祖先链构建
+  const clampedLevels = Math.min(Math.max(ancestorLevels, 0), 10);
+  if (clampedLevels > 0) {
+    const ancestors: AncestorInfo[] = [];
+    let current: Rem | undefined = rootRem;
+    for (let i = 0; i < clampedLevels; i++) {
+      const parent = await current.getParentRem();
+      if (!parent) break;
+      const [name, children, isDoc] = await Promise.all([
+        plugin.richText.toMarkdown(parent.text ?? []),
+        parent.getChildrenRem(),
+        parent.isDocument(),
+      ]);
+      ancestors.push({
+        id: parent._id,
+        name: sanitizeNewlines(name),
+        childrenCount: children.length,
+        isDocument: isDoc,
+      });
+      current = parent;
+    }
+    if (ancestors.length > 0) {
+      // 检测最远祖先是否为顶级 Rem
+      const furthestAncestor = ancestors[ancestors.length - 1];
+      const furthestParent = await current!.getParentRem();
+      if (!furthestParent) {
+        furthestAncestor.isTopLevel = true;
+      }
+      result.ancestors = ancestors;
+    }
+  }
+
+  if (!includePowerup && (totalFilteredTags > 0 || totalFilteredChildren > 0)) {
+    result.powerupFiltered = { tags: totalFilteredTags, children: totalFilteredChildren };
+  }
+
+  return result;
+}
+

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

@@ -0,0 +1,124 @@
+/**
+ * rem-builder.ts — 共享的 SerializableRem 构建函数
+ *
+ * 从 read-tree.ts 和 read-context.ts 中提取的重复逻辑。
+ * 放在 services/ 目录（因为调用 SDK），不放 utils/。
+ *
+ * 依赖方向：services/rem-builder → utils/tree-serializer（单向）
+ */
+
+import type { ReactRNPlugin, PluginRem as Rem } from '@remnote/plugin-sdk';
+import type { SerializableRem } from '../utils/tree-serializer';
+import { filterNoisyTags } from './powerup-filter';
+
+export interface BuildFullRemOptions {
+  /** 是否保留 Powerup 系统 Tag（默认 false = 过滤掉） */
+  includePowerup?: boolean;
+  /** 过滤掉的 Tag 数量回调（用于 read-tree 统计） */
+  onFilteredTags?: (count: number) => void;
+}
+
+/**
+ * 构建完整的 SerializableRem（并行获取所有 SDK 字段）。
+ *
+ * 被 read-tree 和 read-context 共享。
+ */
+export async function buildFullSerializableRem(
+  plugin: ReactRNPlugin,
+  rem: Rem,
+  children: Rem[],
+  options?: BuildFullRemOptions,
+): Promise<SerializableRem> {
+  const includePowerup = options?.includePowerup ?? false;
+
+  const [
+    markdownText,
+    markdownBackText,
+    remType,
+    isCardItem,
+    isDocument,
+    tagRems,
+    practiceDirection,
+    fontSize,
+    isTodo,
+    todoStatus,
+    isCode,
+    hasDvPowerup,
+    portalIncludedRems,
+  ] = await Promise.all([
+    plugin.richText.toMarkdown(rem.text ?? []),
+    rem.backText ? plugin.richText.toMarkdown(rem.backText) : Promise.resolve(null),
+    rem.getType(),
+    rem.isCardItem(),
+    rem.isDocument(),
+    rem.getTagRems().then(tags => {
+      if (includePowerup) return tags;
+      return filterNoisyTags(tags).then(filtered => {
+        const filteredCount = tags.length - filtered.length;
+        if (filteredCount > 0) options?.onFilteredTags?.(filteredCount);
+        return filtered;
+      });
+    }),
+    rem.getPracticeDirection(),
+    rem.getFontSize(),
+    rem.isTodo(),
+    rem.getTodoStatus(),
+    rem.isCode(),
+    rem.hasPowerup('dv'),
+    rem.type === 6 ? rem.getPortalDirectlyIncludedRem() : Promise.resolve([]),
+  ]);
+
+  let hasMultilineChildren = false;
+  if (children.length > 0) {
+    const cardItemFlags = await Promise.all(children.map(c => c.isCardItem()));
+    hasMultilineChildren = cardItemFlags.some(Boolean);
+  }
+
+  const isDivider = hasDvPowerup && (rem.text ?? []).length === 0;
+
+  // 获取每个 tag 的 name（并行）
+  const tags = await Promise.all(
+    tagRems.map(async (t) => ({
+      id: t._id,
+      name: sanitizeNewlines(await plugin.richText.toMarkdown(t.text ?? [])),
+    })),
+  );
+
+  return {
+    id: rem._id,
+    markdownText: sanitizeNewlines(markdownText),
+    markdownBackText: markdownBackText !== null ? sanitizeNewlines(markdownBackText) : null,
+    type: remTypeToString(remType as number),
+    hasMultilineChildren,
+    practiceDirection: (practiceDirection as string) ?? 'none',
+    isCardItem,
+    isDocument,
+    isPortal: rem.type === 6,
+    portalRefs: portalIncludedRems.map((r: Rem) => r._id),
+    childrenCount: children.length,
+    tags,
+    fontSize: (fontSize as 'H1' | 'H2' | 'H3' | null) ?? null,
+    isTodo,
+    todoStatus: (todoStatus as 'Finished' | 'Unfinished' | null) ?? null,
+    isCode,
+    isDivider,
+    isTopLevel: rem.parent === null,
+  };
+}
+
+// ── 辅助函数 ──
+
+/** toMarkdown 可能返回多行，替换为空格以保持"每 Rem 一行" */
+export function sanitizeNewlines(text: string): string {
+  return text.replace(/\n/g, ' ');
+}
+
+/** SDK RemType 枚举值 → 字符串 */
+export function remTypeToString(type: number): string {
+  switch (type) {
+    case 1: return 'concept';
+    case 2: return 'descriptor';
+    case 6: return 'portal';
+    default: return 'default';
+  }
+}

package/remnote-plugin/src/services/reorder-children.ts

@@ -0,0 +1,61 @@
+/**
+ * reorder-children service — 重排 children 顺序
+ *
+ * 内部原子操作：reorder_children (action) → reorder-children.ts (文件) → reorderChildren (函数)
+ *
+ * SDK 没有 setChildrenOrder API，使用逐个 setParent(parent, position) 实现。
+ */
+
+import type { ReactRNPlugin } from '@remnote/plugin-sdk';
+
+export interface ReorderChildrenPayload {
+  parentId: string;
+  /** 期望的 children 顺序（remId 数组） */
+  order: string[];
+}
+
+/**
+ * 重排父节点下 children 的顺序。
+ *
+ * 策略：按目标顺序逐个调用 setParent(parent, position) 进行定位。
+ * 只移动位置需要变化的 children。
+ *
+ * @throws Error — 父节点不存在
+ */
+export async function reorderChildren(
+  plugin: ReactRNPlugin,
+  payload: ReorderChildrenPayload,
+): Promise<{ ok: true }> {
+  const { parentId, order } = payload;
+
+  const parent = await plugin.rem.findOne(parentId);
+  if (!parent) {
+    throw new Error(`Parent Rem not found: ${parentId}`);
+  }
+
+  // 获取当前 children 顺序
+  const currentChildren = await parent.getChildrenRem();
+  const currentOrder = currentChildren.map(r => r._id);
+
+  // 检测实际需要移动的项
+  // 按目标顺序逐个放置
+  for (let targetPos = 0; targetPos < order.length; targetPos++) {
+    const remId = order[targetPos];
+
+    // 重新获取最新顺序（因为每次 setParent 会改变顺序）
+    const freshChildren = await parent.getChildrenRem();
+    const currentPos = freshChildren.findIndex(r => r._id === remId);
+
+    if (currentPos === -1) {
+      // 这个 remId 不在当前 children 中（可能已被移动或删除），跳过
+      continue;
+    }
+
+    if (currentPos !== targetPos) {
+      const rem = freshChildren[currentPos];
+      await rem.setParent(parent, targetPos);
+    }
+  }
+
+  return { ok: true };
+}