remnote-bridge 0.1.0

package/remnote-plugin/package.json

@@ -0,0 +1,48 @@
+{
+  "private": true,
+  "name": "unofficial-remnote-bridge-plugin",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "RemNote 桥接层：嵌入 RemNote 的 WebSocket 桥接插件",
+  "scripts": {
+    "check-types": "tsc",
+    "dev": "cross-env NODE_ENV=development webpack-dev-server --color --progress --no-open",
+    "build": "npx remnote-plugin validate && shx rm -rf dist && cross-env NODE_ENV=production webpack --color --progress && cd dist && bestzip ../PluginZip.zip ./*",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@remnote/plugin-sdk": "0.0.46",
+    "react": "^17.0.2",
+    "react-dom": "^17.0.2"
+  },
+  "devDependencies": {
+    "@pmmmwh/react-refresh-webpack-plugin": "^0.6.2",
+    "@types/node": "^20.11.0",
+    "@types/react": "^17.0.2",
+    "@types/react-dom": "^17.0.2",
+    "autoprefixer": "^10.4.20",
+    "bestzip": "^2.2.1",
+    "concurrently": "^9.1.0",
+    "copy-webpack-plugin": "^12.0.0",
+    "cross-env": "^7.0.3",
+    "css-loader": "^7.1.0",
+    "esbuild-loader": "^4.4.0",
+    "html-webpack-plugin": "^5.6.0",
+    "mini-css-extract-plugin": "^2.10.0",
+    "postcss": "^8.4.49",
+    "postcss-import": "^16.1.0",
+    "postcss-loader": "^8.2.0",
+    "react-refresh": "^0.14.2",
+    "shx": "^0.3.4",
+    "style-loader": "^4.0.0",
+    "tailwindcss": "^3.4.17",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.4.0",
+    "vitest": "^1.3.0",
+    "happy-dom": "^14.0.0",
+    "webpack": "^5.97.0",
+    "webpack-cli": "^5.1.4",
+    "webpack-dev-server": "^5.2.0"
+  }
+}

package/remnote-plugin/postcss.config.js

@@ -0,0 +1,5 @@
+module.exports = () => {
+  return {
+    plugins: [require('postcss-import'), require('tailwindcss'), require('autoprefixer')],
+  };
+};

package/remnote-plugin/public/bridge-icon.svg

@@ -0,0 +1,8 @@
+<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <!-- Bidirectional arrows -->
+  <path d="M3 8 L9 8 M7 6 L9 8 L7 10" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" fill="none"/>
+  <path d="M21 8 L15 8 M17 6 L15 8 L17 10" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" fill="none"/>
+
+  <!-- MCP text -->
+  <text x="12" y="19" text-anchor="middle" font-size="7" fill="currentColor" font-weight="700" font-family="system-ui, -apple-system, sans-serif">MCP</text>
+</svg>

package/remnote-plugin/public/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

@@ -0,0 +1,57 @@
+/**
+ * Message Router — 请求路由分发
+ *
+ * bridge 层的 API 控制器：接收守护进程转发的请求，
+ * 根据 action 路由到 services 层对应方法。
+ *
+ * 依赖方向：bridge/message-router → services（单向）
+ */
+
+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 { readGlobe } from '../services/read-globe';
+import { readContext } from '../services/read-context';
+import { writeRemFields } from '../services/write-rem-fields';
+import { createRem } from '../services/create-rem';
+import { deleteRem } from '../services/delete-rem';
+import { moveRem } from '../services/move-rem';
+import { reorderChildren } from '../services/reorder-children';
+import { search } from '../services/search';
+
+/**
+ * 创建消息路由处理器
+ *
+ * 返回一个函数供 WebSocketClient.setMessageHandler() 使用。
+ * 按 action 分发到 services 层对应方法（同态命名）。
+ */
+export function createMessageRouter(plugin: ReactRNPlugin): (request: BridgeRequest) => Promise<unknown> {
+  return async (request: BridgeRequest): Promise<unknown> => {
+    switch (request.action) {
+      case 'read_rem':
+        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 'write_rem_fields':
+        return writeRemFields(plugin, request.payload as { remId: string; changes: Record<string, unknown> });
+      case 'create_rem':
+        return createRem(plugin, request.payload as { content: string; parentId: string; position: number });
+      case 'delete_rem':
+        return deleteRem(plugin, request.payload as { remId: string });
+      case 'move_rem':
+        return moveRem(plugin, request.payload as { remId: string; newParentId: string; position: number });
+      case 'reorder_children':
+        return reorderChildren(plugin, request.payload as { parentId: string; order: string[] });
+      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 });
+      case 'search':
+        return search(plugin, request.payload as { query: string; numResults?: number });
+
+      default:
+        throw new Error(`未实现的 action: ${request.action}`);
+    }
+  };
+}

package/remnote-plugin/src/bridge/websocket-client.ts

@@ -0,0 +1,245 @@
+/**
+ * WebSocket Client — Plugin 侧连接守护进程
+ *
+ * 职责：
+ * 1. 连接到 CLI 守护进程的 WS Server
+ * 2. 发送 hello 消息（携带版本 + SDK 状态）
+ * 3. 响应 ping 心跳返回 pong
+ * 4. 接收并执行来自守护进程转发的请求
+ * 5. 断线后指数退避自动重连
+ *
+ * 协议类型在 Plugin 层独立定义（与 CLI 层不共享代码）。
+ */
+
+// ── 协议类型（独立定义）──
+
+export type ConnectionStatus = 'disconnected' | 'connecting' | 'connected';
+
+export interface HelloMessage {
+  type: 'hello';
+  version: string;
+  sdkReady: boolean;
+}
+
+export interface PingMessage {
+  type: 'ping';
+}
+
+export interface PongMessage {
+  type: 'pong';
+}
+
+export interface BridgeRequest {
+  id: string;
+  action: string;
+  payload: Record<string, unknown>;
+}
+
+export interface BridgeResponse {
+  id: string;
+  result?: unknown;
+  error?: string;
+}
+
+// ── 配置 ──
+
+export interface WebSocketClientConfig {
+  url: string;
+  pluginVersion: string;
+  sdkReady: boolean;
+  maxReconnectAttempts?: number;
+  initialReconnectDelay?: number;
+  maxReconnectDelay?: number;
+  onStatusChange?: (status: ConnectionStatus) => void;
+  onLog?: (message: string, level: 'info' | 'warn' | 'error') => void;
+}
+
+// ── WebSocket Client 实现 ──
+
+export class WebSocketClient {
+  private ws: WebSocket | null = null;
+  private reconnectAttempts = 0;
+  private reconnectTimeout: ReturnType<typeof setTimeout> | null = null;
+  private messageHandler: ((request: BridgeRequest) => Promise<unknown>) | null = null;
+  private status: ConnectionStatus = 'disconnected';
+  private isShuttingDown = false;
+  private _sdkReady: boolean;
+
+  private config: Required<Omit<WebSocketClientConfig, 'onStatusChange' | 'onLog'>> & {
+    onStatusChange?: (status: ConnectionStatus) => void;
+    onLog?: (message: string, level: 'info' | 'warn' | 'error') => void;
+  };
+
+  constructor(config: WebSocketClientConfig) {
+    this._sdkReady = config.sdkReady;
+    this.config = {
+      url: config.url,
+      pluginVersion: config.pluginVersion,
+      sdkReady: config.sdkReady,
+      maxReconnectAttempts: config.maxReconnectAttempts ?? 10,
+      initialReconnectDelay: config.initialReconnectDelay ?? 1000,
+      maxReconnectDelay: config.maxReconnectDelay ?? 30000,
+      onStatusChange: config.onStatusChange,
+      onLog: config.onLog,
+    };
+  }
+
+  private log(message: string, level: 'info' | 'warn' | 'error' = 'info'): void {
+    this.config.onLog?.(message, level);
+  }
+
+  private setStatus(newStatus: ConnectionStatus): void {
+    if (this.status !== newStatus) {
+      this.status = newStatus;
+      this.config.onStatusChange?.(newStatus);
+    }
+  }
+
+  private sendHello(): void {
+    const hello: HelloMessage = {
+      type: 'hello',
+      version: this.config.pluginVersion,
+      sdkReady: this._sdkReady,
+    };
+    try {
+      this.ws?.send(JSON.stringify(hello));
+      this.log(`发送 hello（v${this.config.pluginVersion}, sdkReady=${this._sdkReady}）`);
+    } catch (error) {
+      this.log(`发送 hello 失败: ${error}`, 'warn');
+    }
+  }
+
+  connect(): void {
+    if (this.ws?.readyState === WebSocket.OPEN || this.ws?.readyState === WebSocket.CONNECTING) {
+      return;
+    }
+
+    this.isShuttingDown = false;
+    this.setStatus('connecting');
+    this.log(`正在连接 ${this.config.url}...`);
+
+    try {
+      this.ws = new WebSocket(this.config.url);
+
+      this.ws.onopen = () => {
+        this.log('已连接到守护进程');
+        this.reconnectAttempts = 0;
+        this.setStatus('connected');
+        this.sendHello();
+      };
+
+      this.ws.onmessage = async (event) => {
+        await this.handleMessage(typeof event.data === 'string' ? event.data : String(event.data));
+      };
+
+      this.ws.onclose = (event) => {
+        this.log(`连接断开: ${event.code} ${event.reason}`, 'warn');
+        this.setStatus('disconnected');
+
+        if (!this.isShuttingDown) {
+          this.scheduleReconnect();
+        }
+      };
+
+      this.ws.onerror = (error) => {
+        this.log(`WebSocket 错误: ${error}`, 'error');
+      };
+    } catch (error) {
+      this.log(`连接失败: ${error}`, 'error');
+      this.setStatus('disconnected');
+      this.scheduleReconnect();
+    }
+  }
+
+  private async handleMessage(data: string): Promise<void> {
+    try {
+      const message = JSON.parse(data);
+
+      // 心跳响应
+      if (message.type === 'ping') {
+        this.ws?.send(JSON.stringify({ type: 'pong' } as PongMessage));
+        return;
+      }
+
+      // 处理来自守护进程转发的请求
+      if (message.id && message.action && this.messageHandler) {
+        const request = message as BridgeRequest;
+        this.log(`收到请求: ${request.action}`);
+
+        try {
+          const result = await this.messageHandler(request);
+          const response: BridgeResponse = { id: request.id, result };
+          this.ws?.send(JSON.stringify(response));
+          this.log(`完成: ${request.action}`);
+        } catch (error) {
+          const errorMessage = error instanceof Error ? error.message : String(error);
+          const response: BridgeResponse = { id: request.id, error: errorMessage };
+          this.ws?.send(JSON.stringify(response));
+          this.log(`失败: ${request.action} - ${errorMessage}`, 'error');
+        }
+      }
+    } catch (error) {
+      this.log(`处理消息失败: ${error}`, 'error');
+    }
+  }
+
+  private scheduleReconnect(): void {
+    if (this.isShuttingDown) return;
+
+    if (this.reconnectAttempts >= this.config.maxReconnectAttempts) {
+      this.log('已达最大重连次数', 'error');
+      return;
+    }
+
+    // 指数退避 + 抖动
+    const baseDelay = Math.min(
+      this.config.initialReconnectDelay * Math.pow(2, this.reconnectAttempts),
+      this.config.maxReconnectDelay,
+    );
+    const jitter = Math.random() * 0.3 * baseDelay;
+    const delay = baseDelay + jitter;
+
+    this.reconnectAttempts++;
+    this.log(
+      `${Math.round(delay)}ms 后重连（第 ${this.reconnectAttempts}/${this.config.maxReconnectAttempts} 次）`,
+    );
+
+    this.reconnectTimeout = setTimeout(() => {
+      this.connect();
+    }, delay);
+  }
+
+  setMessageHandler(handler: (request: BridgeRequest) => Promise<unknown>): void {
+    this.messageHandler = handler;
+  }
+
+  setSdkReady(ready: boolean): void {
+    this._sdkReady = ready;
+  }
+
+  disconnect(): void {
+    this.isShuttingDown = true;
+
+    if (this.reconnectTimeout) {
+      clearTimeout(this.reconnectTimeout);
+      this.reconnectTimeout = null;
+    }
+
+    if (this.ws) {
+      this.ws.close(1000, 'Plugin disconnect');
+      this.ws = null;
+    }
+
+    this.setStatus('disconnected');
+  }
+
+  reconnect(): void {
+    this.reconnectAttempts = 0;
+    this.disconnect();
+    this.connect();
+  }
+
+  getStatus(): ConnectionStatus {
+    return this.status;
+  }
+}

package/remnote-plugin/src/index.css

@@ -0,0 +1 @@
+/* Add your plugin styles here. This file is named <widget-name>.css; in this case, index.css*/

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

@@ -0,0 +1,26 @@
+/**
+ * breadcrumb.ts — 面包屑路径构建
+ *
+ * SDK 辅助函数。被 read-globe、read-context 共享。
+ */
+
+import type { ReactRNPlugin, PluginRem as Rem } from '@remnote/plugin-sdk';
+
+/**
+ * 从 rem 向上追溯到根，返回路径名称数组（从根到当前）。
+ */
+export async function buildBreadcrumb(
+  plugin: ReactRNPlugin,
+  rem: Rem,
+): Promise<string[]> {
+  const path: string[] = [];
+  let current: Rem | undefined = rem;
+
+  while (current) {
+    const text = await plugin.richText.toMarkdown(current.text ?? []);
+    path.unshift(text.replace(/\n/g, ' ').trim() || current._id);
+    current = await current.getParentRem();
+  }
+
+  return path;
+}

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

@@ -0,0 +1,59 @@
+/**
+ * create-rem service — 创建新 Rem
+ *
+ * 内部原子操作：create_rem (action) → create-rem.ts (文件) → createRem (函数)
+ *
+ * 使用 createSingleRemWithMarkdown 一步到位创建：
+ * - 自动解析 Markdown 中的闪卡语法（::, >>, <<, <>, ;;, >>>, {{}} 等）
+ * - 自动设置 type、backText、practiceDirection 等属性
+ * - 自动设置父节点
+ */
+
+import type { ReactRNPlugin } from '@remnote/plugin-sdk';
+
+export interface CreateRemPayload {
+  /** RemNote Markdown 格式的内容 */
+  content: string;
+  /** 父节点 Rem ID */
+  parentId: string;
+  /** 在兄弟中的位置（0-based） */
+  position: number;
+}
+
+export interface CreateRemResult {
+  remId: string;
+}
+
+/**
+ * 创建新 Rem。
+ *
+ * @throws Error — 父节点不存在、创建失败
+ */
+export async function createRem(
+  plugin: ReactRNPlugin,
+  payload: CreateRemPayload,
+): Promise<CreateRemResult> {
+  const { content, parentId, position } = payload;
+
+  // 验证父节点存在
+  const parent = await plugin.rem.findOne(parentId);
+  if (!parent) {
+    throw new Error(`Parent Rem not found: ${parentId}`);
+  }
+
+  // 使用 createSingleRemWithMarkdown 创建（自动解析闪卡语法）
+  const newRem = await plugin.rem.createSingleRemWithMarkdown(content, parentId);
+  if (!newRem) {
+    throw new Error(`Failed to create Rem with content: ${content.slice(0, 50)}`);
+  }
+
+  // 设置位置（createSingleRemWithMarkdown 默认追加到末尾）
+  // 如果 position 不是末尾，需要用 setParent 调整
+  const siblings = await parent.getChildrenRem();
+  const currentIndex = siblings.findIndex(r => r._id === newRem._id);
+  if (currentIndex !== -1 && currentIndex !== position && position < siblings.length) {
+    await newRem.setParent(parent, position);
+  }
+
+  return { remId: newRem._id };
+}

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

@@ -0,0 +1,29 @@
+/**
+ * delete-rem service — 删除 Rem
+ *
+ * 内部原子操作：delete_rem (action) → delete-rem.ts (文件) → deleteRem (函数)
+ */
+
+import type { ReactRNPlugin } from '@remnote/plugin-sdk';
+
+export interface DeleteRemPayload {
+  remId: string;
+}
+
+/**
+ * 删除指定 Rem。
+ *
+ * @throws Error — Rem 不存在
+ */
+export async function deleteRem(
+  plugin: ReactRNPlugin,
+  payload: DeleteRemPayload,
+): Promise<{ ok: true }> {
+  const rem = await plugin.rem.findOne(payload.remId);
+  if (!rem) {
+    throw new Error(`Rem not found: ${payload.remId}`);
+  }
+
+  await rem.remove();
+  return { ok: true };
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Services 层 — 业务操作（与 CLI 命令同态命名）
+ *
+ * 每个文件对应一个 CLI 命令，封装完整的 RemNote SDK 操作链。
+ * 由 bridge 层调用，不直接暴露给 widgets。
+ *
+ * 依赖方向：services → utils（单向）
+ *
+ * 待实现：
+ * - read-note.ts    → readNote()
+ * - create-note.ts  → createNote()
+ * - update-note.ts  → updateNote()
+ * - search.ts       → search()
+ * - search-by-tag.ts → searchByTag()
+ * - append-journal.ts → appendJournal()
+ */

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

@@ -0,0 +1,39 @@
+/**
+ * move-rem service — 移动 Rem（改变父节点）
+ *
+ * 内部原子操作：move_rem (action) → move-rem.ts (文件) → moveRem (函数)
+ */
+
+import type { ReactRNPlugin } from '@remnote/plugin-sdk';
+
+export interface MoveRemPayload {
+  remId: string;
+  newParentId: string;
+  /** 在新父节点 children 中的位置（0-based） */
+  position: number;
+}
+
+/**
+ * 将 Rem 移动到新的父节点下。
+ *
+ * @throws Error — Rem 或新父节点不存在
+ */
+export async function moveRem(
+  plugin: ReactRNPlugin,
+  payload: MoveRemPayload,
+): Promise<{ ok: true }> {
+  const { remId, newParentId, position } = payload;
+
+  const rem = await plugin.rem.findOne(remId);
+  if (!rem) {
+    throw new Error(`Rem not found: ${remId}`);
+  }
+
+  const newParent = await plugin.rem.findOne(newParentId);
+  if (!newParent) {
+    throw new Error(`New parent Rem not found: ${newParentId}`);
+  }
+
+  await rem.setParent(newParent, position);
+  return { ok: true };
+}

package/remnote-plugin/src/services/powerup-filter.ts

@@ -0,0 +1,31 @@
+/**
+ * powerup-filter — Powerup 噪音过滤工具
+ *
+ * RemNote 的格式设置（fontSize、highlightColor、isCode 等）底层通过 Powerup 机制实现，
+ * 会向 Rem 注入隐藏的 Tag 和 descriptor 子 Rem。这些在 UI 中不可见，对 AI Agent 是噪音。
+ */
+
+import type { PluginRem as Rem } from '@remnote/plugin-sdk';
+
+/** 判断 Rem 是否为 Powerup 产生的隐藏子 Rem */
+export async function isNoisyPowerupChild(rem: Rem): Promise<boolean> {
+  const [a, b, c, d] = await Promise.all([
+    rem.isPowerupProperty(),
+    rem.isPowerupSlot(),
+    rem.isPowerupPropertyListItem(),
+    rem.isPowerupEnum(),
+  ]);
+  return a || b || c || d;
+}
+
+/** 批量过滤：返回非 Powerup 隐藏子 Rem */
+export async function filterNoisyChildren(rems: Rem[]): Promise<Rem[]> {
+  const flags = await Promise.all(rems.map(isNoisyPowerupChild));
+  return rems.filter((_, i) => !flags[i]);
+}
+
+/** 过滤 Tag：去掉 isPowerup=true 的系统 Tag */
+export async function filterNoisyTags(tagRems: Rem[]): Promise<Rem[]> {
+  const flags = await Promise.all(tagRems.map(t => t.isPowerup()));
+  return tagRems.filter((_, i) => !flags[i]);
+}