remnote-bridge 0.1.0

package/remnote-plugin/src/utils/tree-serializer.ts

@@ -0,0 +1,269 @@
+/**
+ * tree-serializer.ts — 树大纲序列化纯函数
+ *
+ * 职责：将 SerializableRem 数据拼接为带缩进和元数据注释的大纲行。
+ * 约束：纯函数、无副作用、不调用 SDK、不依赖其他层。
+ *
+ * SDK 调用（toMarkdown、getChildrenRem 等）在 services/read-tree.ts 中完成，
+ * 本文件只接收已转换好的字符串数据。
+ *
+ * ── 分隔符设计（v2）──
+ *
+ * 行内分隔符只表示 practiceDirection，不编码 type 信息。
+ * type（concept/descriptor）由元数据标记 `type:` 承载。
+ *
+ * | 箭头 | 含义                           |
+ * |:-----|:-------------------------------|
+ * | →    | 有 backText, forward           |
+ * | ←    | 有 backText, backward          |
+ * | ↔    | 有 backText, both              |
+ * | ↓    | multiline, forward（无 backText）|
+ * | ↑    | multiline, backward            |
+ * | ↕    | multiline, both                |
+ *
+ * ── 元数据标记 ──
+ *
+ * | 标记            | 含义                            |
+ * |:----------------|:--------------------------------|
+ * | type:concept    | Rem type = concept              |
+ * | type:descriptor | Rem type = descriptor           |
+ * | type:portal     | Rem type = portal               |
+ * | doc             | isDocument = true               |
+ * | role:card-item  | isCardItem = true（多行答案行）  |
+ * | children:N      | 折叠时的隐藏子节点数            |
+ * | tag:Name(id)    | 每个 tag 独立一个标记           |
+ * | top             | 知识库顶级 Rem                  |
+ */
+
+// ────────────────────────── 接口 ──────────────────────────
+
+/** Tag 信息 */
+export interface TagInfo {
+  id: string;
+  name: string;
+}
+
+/** services/read-tree.ts 准备好的单个 Rem 数据 */
+export interface SerializableRem {
+  id: string;
+  markdownText: string;
+  markdownBackText: string | null;
+  /** 'concept' | 'descriptor' | 'default' | 'portal' */
+  type: string;
+  hasMultilineChildren: boolean;
+  /** 'forward' | 'backward' | 'both' | 'none' */
+  practiceDirection: string;
+  isCardItem: boolean;
+  isDocument: boolean;
+  isPortal: boolean;
+  /** Portal 直接引用的 Rem ID 列表（仅 Portal 类型有值） */
+  portalRefs: string[];
+  childrenCount: number;
+  tags: TagInfo[];
+  // Markdown 语法映射
+  fontSize: 'H1' | 'H2' | 'H3' | null;
+  isTodo: boolean;
+  todoStatus: 'Finished' | 'Unfinished' | null;
+  isCode: boolean;
+  isDivider: boolean;
+  /** 是否为知识库顶级 Rem（无父节点） */
+  isTopLevel?: boolean;
+}
+
+/** 递归树节点，用于 buildOutline */
+export interface OutlineNode {
+  rem: SerializableRem;
+  children: TreeNode[];
+  /** true = 子树超过 depth 限制被折叠 */
+  folded: boolean;
+}
+
+/** 省略占位节点 */
+export interface ElidedNode {
+  type: 'elided';
+  /** 被省略的同级节点数 */
+  count: number;
+  /** 是否精确计数（false = ">=N"，表示省略的节点可能还有后代） */
+  isExact: boolean;
+  parentId: string;
+  rangeFrom: number;
+  rangeTo: number;
+  totalSiblings: number;
+}
+
+/** 树节点统一类型 */
+export type TreeNode = OutlineNode | ElidedNode;
+
+/** 类型守卫 */
+export function isElidedNode(node: TreeNode): node is ElidedNode {
+  return 'type' in node && node.type === 'elided';
+}
+
+// ────────────────────────── 行内容拼接 ──────────────────────────
+
+/**
+ * 根据 practiceDirection 选择方向箭头，拼接行内容（不含缩进和元数据标记）。
+ *
+ * 箭头只表示 direction，不编码 type。type 由元数据标记承载。
+ */
+function buildLineContent(rem: SerializableRem): string {
+  // Divider（最高优先）
+  if (rem.isDivider) return '---';
+
+  const { markdownText, markdownBackText, hasMultilineChildren, practiceDirection } = rem;
+
+  let baseContent: string;
+
+  if (markdownBackText !== null) {
+    // 有 backText：按 direction 选择水平/垂直箭头
+    const arrow = hasMultilineChildren
+      ? (practiceDirection === 'backward' ? ' ↑ ' : practiceDirection === 'both' ? ' ↕ ' : ' ↓ ')
+      : (practiceDirection === 'backward' ? ' ← ' : practiceDirection === 'both' ? ' ↔ ' : ' → ');
+    baseContent = markdownText + arrow + markdownBackText;
+  } else if (hasMultilineChildren) {
+    // 无 backText + multiline：尾部箭头
+    const arrow = practiceDirection === 'backward' ? ' ↑' : practiceDirection === 'both' ? ' ↕' : ' ↓';
+    baseContent = markdownText + arrow;
+  } else {
+    baseContent = markdownText;
+  }
+
+  // Code 包裹（最内层）
+  if (rem.isCode) baseContent = '`' + baseContent + '`';
+
+  // Todo 前缀
+  if (rem.isTodo) {
+    const cb = rem.todoStatus === 'Finished' ? '- [x] ' : '- [ ] ';
+    baseContent = cb + baseContent;
+  }
+
+  // Header 前缀（最外层）
+  if (rem.fontSize) {
+    const hd = rem.fontSize === 'H1' ? '# ' : rem.fontSize === 'H2' ? '## ' : '### ';
+    baseContent = hd + baseContent;
+  }
+
+  return baseContent;
+}
+
+// ────────────────────────── 元数据 ──────────────────────────
+
+/**
+ * 构建元数据标记列表。每个标记对应一个独立字段，不合并。
+ */
+function buildMetadata(rem: SerializableRem, folded: boolean): string[] {
+  const parts: string[] = [];
+
+  // type（default 不输出）
+  if (rem.type === 'concept') parts.push('type:concept');
+  else if (rem.type === 'descriptor') parts.push('type:descriptor');
+  else if (rem.type === 'portal') {
+    parts.push('type:portal');
+    if (rem.portalRefs.length > 0) parts.push('refs:' + rem.portalRefs.join(','));
+  }
+
+  // doc（独立于 type 的维度）
+  if (rem.isDocument) parts.push('doc');
+
+  // role
+  if (rem.isCardItem) parts.push('role:card-item');
+
+  // children（折叠时才输出）
+  if (folded && rem.childrenCount > 0) parts.push('children:' + rem.childrenCount);
+
+  // tags（每个 tag 独立一个标记）
+  for (const tag of rem.tags) {
+    parts.push('tag:' + tag.name + '(' + tag.id + ')');
+  }
+
+  // 顶级标记
+  if (rem.isTopLevel) parts.push('top');
+
+  return parts;
+}
+
+// ────────────────────────── 工厂函数 ──────────────────────────
+
+/**
+ * 创建一个带合理默认值的 SerializableRem。
+ *
+ * 用于 read-globe、read-context 等场景中只需基础字段的节点。
+ * 必须提供 id、markdownText、childrenCount，其余字段使用默认值。
+ */
+export function createMinimalSerializableRem(
+  overrides: Partial<SerializableRem> & Pick<SerializableRem, 'id' | 'markdownText' | 'childrenCount'>,
+): SerializableRem {
+  return {
+    markdownBackText: null,
+    type: 'default',
+    hasMultilineChildren: false,
+    practiceDirection: 'none',
+    isCardItem: false,
+    isDocument: false,
+    isPortal: false,
+    portalRefs: [],
+    tags: [],
+    fontSize: null,
+    isTodo: false,
+    todoStatus: null,
+    isCode: false,
+    isDivider: false,
+    ...overrides,
+  };
+}
+
+// ────────────────────────── 公开 API ──────────────────────────
+
+/**
+ * 序列化单个 Rem 为一行（不含缩进）。
+ *
+ * 格式：`{行内容} <!--{remId} {元数据}-->`
+ */
+export function serializeRemLine(rem: SerializableRem, folded: boolean = false): string {
+  const content = buildLineContent(rem);
+  const metadata = buildMetadata(rem, folded);
+  const metaStr = metadata.length > 0 ? ' ' + metadata.join(' ') : '';
+  return `${content} <!--${rem.id}${metaStr}-->`;
+}
+
+/**
+ * 序列化省略占位符行（不含缩进）。
+ *
+ * 精确：`<!--...elided {N} siblings (parent:{id} range:{from}-{to} total:{total})-->`
+ * 非精确：`<!--...elided >={N} nodes (parent:{id} range:{from}-{to} total:{total})-->`
+ */
+export function serializeElidedLine(node: ElidedNode): string {
+  const label = node.isExact ? 'siblings' : 'nodes';
+  const prefix = node.isExact ? '' : '>=';
+  return `<!--...elided ${prefix}${node.count} ${label} (parent:${node.parentId} range:${node.rangeFrom}-${node.rangeTo} total:${node.totalSiblings})-->`;
+}
+
+/**
+ * 将递归树结构序列化为完整的 Markdown 大纲文本。
+ *
+ * 每级缩进 2 个空格。
+ */
+export function buildOutline(root: OutlineNode): string {
+  const lines: string[] = [];
+
+  function walkNode(node: TreeNode, depth: number): void {
+    const indent = '  '.repeat(depth);
+
+    if (isElidedNode(node)) {
+      lines.push(indent + serializeElidedLine(node));
+      return;
+    }
+
+    const line = serializeRemLine(node.rem, node.folded);
+    lines.push(indent + line);
+
+    if (!node.folded) {
+      for (const child of node.children) {
+        walkNode(child, depth + 1);
+      }
+    }
+  }
+
+  walkNode(root, 0);
+  return lines.join('\n');
+}

package/remnote-plugin/src/widgets/bridge_widget.tsx

@@ -0,0 +1,170 @@
+/**
+ * Bridge Widget — 显示守护进程连接状态（纯展示）
+ *
+ * WebSocket 连接在 index.tsx 的 onActivate 中建立，
+ * 此 widget 每秒从 plugin.storage 读取并显示状态和日志。
+ */
+
+import { renderWidget, usePlugin } from '@remnote/plugin-sdk';
+import React, { useEffect, useState } from 'react';
+import type { ConnectionStatus } from '../bridge/websocket-client';
+
+interface StoredLog {
+  time: number;
+  message: string;
+  level: string;
+}
+
+function BridgeWidget() {
+  const plugin = usePlugin();
+  const [status, setStatus] = useState<ConnectionStatus>('disconnected');
+  const [logs, setLogs] = useState<StoredLog[]>([]);
+
+  // 每秒轮询 plugin.storage 获取最新状态
+  useEffect(() => {
+    let active = true;
+
+    async function poll() {
+      if (!active) return;
+      const s = await plugin.storage.getSession('bridge-status');
+      const l = await plugin.storage.getSession('bridge-logs');
+      if (active) {
+        setStatus((s as ConnectionStatus) ?? 'disconnected');
+        setLogs((l as StoredLog[]) ?? []);
+      }
+    }
+
+    poll();
+    const timer = setInterval(poll, 1000);
+    return () => {
+      active = false;
+      clearInterval(timer);
+    };
+  }, [plugin]);
+
+  const statusConfig = {
+    connected: { color: '#22c55e', bg: '#dcfce7', icon: '\u25cf', text: '已连接' },
+    connecting: { color: '#f59e0b', bg: '#fef3c7', icon: '\u25d0', text: '连接中...' },
+    disconnected: { color: '#ef4444', bg: '#fee2e2', icon: '\u25cb', text: '未连接' },
+  };
+
+  const currentStatus = statusConfig[status];
+
+  return (
+    <div style={{ padding: '12px', fontFamily: 'system-ui, sans-serif', fontSize: '13px' }}>
+      {/* 头部 */}
+      <div
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'space-between',
+          marginBottom: '12px',
+        }}
+      >
+        <h3 style={{ margin: 0, fontSize: '14px', fontWeight: 600 }}>RemNote Bridge</h3>
+        <div
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: '6px',
+            padding: '4px 8px',
+            borderRadius: '12px',
+            backgroundColor: currentStatus.bg,
+            color: currentStatus.color,
+            fontSize: '12px',
+            fontWeight: 500,
+          }}
+        >
+          <span>{currentStatus.icon}</span>
+          <span>{currentStatus.text}</span>
+        </div>
+      </div>
+
+      {/* 日志 */}
+      <div
+        style={{
+          border: '1px solid #e5e7eb',
+          borderRadius: '6px',
+          backgroundColor: '#f9fafb',
+        }}
+      >
+        <div
+          style={{
+            fontSize: '11px',
+            fontWeight: 600,
+            padding: '8px 10px',
+            borderBottom: '1px solid #e5e7eb',
+            color: '#6b7280',
+          }}
+        >
+          日志
+        </div>
+        <div style={{ maxHeight: '150px', overflowY: 'auto' }}>
+          {logs.length === 0 ? (
+            <div style={{ padding: '12px', color: '#9ca3af', textAlign: 'center' }}>暂无日志</div>
+          ) : (
+            logs
+              .slice()
+              .reverse()
+              .map((log, index) => (
+                <div
+                  key={index}
+                  style={{
+                    padding: '6px 10px',
+                    borderBottom: index < logs.length - 1 ? '1px solid #e5e7eb' : 'none',
+                    fontSize: '11px',
+                  }}
+                >
+                  <span style={{ color: '#9ca3af' }}>
+                    {new Date(log.time).toLocaleTimeString([], {
+                      hour: '2-digit',
+                      minute: '2-digit',
+                      second: '2-digit',
+                    })}
+                  </span>
+                  <span
+                    style={{
+                      marginLeft: '8px',
+                      color:
+                        log.level === 'error'
+                          ? '#ef4444'
+                          : log.level === 'warn'
+                            ? '#f59e0b'
+                            : '#374151',
+                    }}
+                  >
+                    {log.message}
+                  </span>
+                </div>
+              ))
+          )}
+        </div>
+      </div>
+
+      {/* 配置按钮 */}
+      <button
+        onClick={() => window.open('http://127.0.0.1:3003', '_blank')}
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          gap: '6px',
+          width: '100%',
+          marginTop: '12px',
+          padding: '8px 0',
+          background: '#f9fafb',
+          border: '1px solid #e5e7eb',
+          borderRadius: '6px',
+          cursor: 'pointer',
+          fontSize: '13px',
+          color: '#374151',
+        }}
+      >
+        <span style={{ fontSize: '16px' }}>⚙</span>
+        <span>打开配置页面</span>
+      </button>
+    </div>
+  );
+}
+
+renderWidget(BridgeWidget);

package/remnote-plugin/src/widgets/index.tsx

@@ -0,0 +1,82 @@
+import { declareIndexPlugin, type ReactRNPlugin, WidgetLocation } from '@remnote/plugin-sdk';
+import '../style.css';
+import '../index.css';
+import { SETTING_WS_URL, DEFAULT_WS_URL, DEFAULT_PLUGIN_VERSION } from '../settings';
+import { WebSocketClient } from '../bridge/websocket-client';
+import { createMessageRouter } from '../bridge/message-router';
+// test-scripts 已完成数据收集，不再打包进生产代码
+// 如需重跑，取消注释对应 import 和 onActivate 调用
+// import { runActionTests } from '../test-scripts/test-actions';
+// import { runRichTextBuilderTest } from '../test-scripts/test-richtext-builder';
+// import { runRichTextRemainingTest } from '../test-scripts/test-richtext-remaining';
+// import { runRichTextMatrixTest } from '../test-scripts/test-richtext-matrix';
+// import { runPowerupRenderingTest } from '../test-scripts/test-powerup-rendering';
+
+let wsClient: WebSocketClient | null = null;
+// 本地日志缓冲区：避免 onLog 并发读写 plugin.storage 的竞态
+const logBuffer: Array<{ time: number; message: string; level: string }> = [];
+let logFlushPending = false;
+
+async function onActivate(plugin: ReactRNPlugin) {
+  // 注册 WS Server URL 设置
+  await plugin.settings.registerStringSetting({
+    id: SETTING_WS_URL,
+    title: 'Bridge WS Server URL',
+    description: '守护进程 WebSocket Server 地址（默认 ws://127.0.0.1:3002）',
+    defaultValue: DEFAULT_WS_URL,
+  });
+
+  // 注册 Bridge Widget（右侧边栏）
+  await plugin.app.registerWidget('bridge_widget', WidgetLocation.RightSidebar, {
+    dimensions: { height: 'auto', width: '100%' },
+    widgetTabIcon: 'https://cdn.jsdelivr.net/npm/lucide-static@0.460.0/icons/globe.svg',
+  });
+
+  // 读取 WS URL 设置
+  const wsUrl =
+    (await plugin.settings.getSetting<string>(SETTING_WS_URL)) || DEFAULT_WS_URL;
+
+  // 在 onActivate 中建立 WebSocket 连接（插件激活即连接，无需打开 widget）
+  wsClient = new WebSocketClient({
+    url: wsUrl,
+    pluginVersion: DEFAULT_PLUGIN_VERSION,
+    sdkReady: true,
+    maxReconnectAttempts: 10,
+    initialReconnectDelay: 1000,
+    maxReconnectDelay: 30000,
+    onStatusChange: (status) => {
+      void plugin.storage.setSession('bridge-status', status);
+    },
+    onLog: (message, level) => {
+      logBuffer.push({ time: Date.now(), message, level });
+      if (logBuffer.length > 30) logBuffer.splice(0, logBuffer.length - 30);
+      // 合并写入：避免并发 read-modify-write 竞态
+      if (!logFlushPending) {
+        logFlushPending = true;
+        queueMicrotask(async () => {
+          logFlushPending = false;
+          await plugin.storage.setSession('bridge-logs', logBuffer.slice());
+        });
+      }
+    },
+  });
+
+  // 路由守护进程转发的请求到 services 层
+  wsClient.setMessageHandler(createMessageRouter(plugin));
+
+  wsClient.connect();
+
+  // test-scripts 已完成数据收集，不再自动运行
+  // runActionTests(plugin).catch((err) => console.error('[ACTION-TEST] 顶层错误:', err));
+  // runRichTextBuilderTest(plugin).catch((err) => console.error('[RICHTEXT-BUILDER-TEST] 顶层错误:', err));
+  // runRichTextRemainingTest(plugin).catch((err) => console.error('[RICHTEXT-REMAINING-TEST] 顶层错误:', err));
+  // runRichTextMatrixTest(plugin).catch((err) => console.error('[RICHTEXT-MATRIX-TEST] 顶层错误:', err));
+  // runPowerupRenderingTest(plugin).catch((err) => console.error('[POWERUP-RENDER] 顶层错误:', err));
+}
+
+async function onDeactivate(_: ReactRNPlugin) {
+  wsClient?.disconnect();
+  wsClient = null;
+}
+
+declareIndexPlugin(onActivate, onDeactivate);

package/remnote-plugin/tailwind.config.js

@@ -0,0 +1,7 @@
+module.exports = {
+  content: ['./src/**/*.{vue,js,ts,jsx,tsx}'],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+};

package/remnote-plugin/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "esnext",
+    "jsx": "react-jsx",
+    "moduleResolution": "node",
+    "strict": true,
+    "strictNullChecks": true,
+    "noEmit": true,
+    "allowJs": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "esModuleInterop": true
+  },
+  "ts-node": {
+    "compilerOptions": {
+      "module": "CommonJS"
+    }
+  },
+  "include": ["src"]
+}

package/remnote-plugin/webpack.config.js

@@ -0,0 +1,125 @@
+const { resolve } = require('path');
+var glob = require('glob');
+var path = require('path');
+
+const HtmlWebpackPlugin = require('html-webpack-plugin');
+const { EsbuildPlugin } = require('esbuild-loader');
+const { ProvidePlugin, BannerPlugin } = require('webpack');
+const MiniCssExtractPlugin = require('mini-css-extract-plugin');
+const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin');
+
+const CopyPlugin = require('copy-webpack-plugin');
+
+const isProd = process.env.NODE_ENV === 'production';
+const isDevelopment = !isProd;
+
+const fastRefresh = isDevelopment ? new ReactRefreshWebpackPlugin() : null;
+
+const SANDBOX_SUFFIX = '-sandbox';
+
+const config = {
+  mode: isProd ? 'production' : 'development',
+  entry: glob.sync('./src/widgets/**/*.tsx').reduce((obj, el) => {
+    const rel = path
+      .relative('src/widgets', el)
+      .replace(/\.[tj]sx?$/, '')
+      .replace(/\\/g, '/');
+
+    obj[rel] = el;
+    obj[`${rel}${SANDBOX_SUFFIX}`] = el;
+    return obj;
+  }, {}),
+
+  output: {
+    path: resolve(__dirname, 'dist'),
+    filename: `[name].js`,
+    publicPath: '',
+  },
+  resolve: {
+    extensions: ['.js', '.jsx', '.ts', '.tsx'],
+  },
+  module: {
+    rules: [
+      {
+        test: /\.(ts|tsx|jsx|js)?$/,
+        loader: 'esbuild-loader',
+        options: {
+          loader: 'tsx',
+          target: 'es2020',
+          minify: false,
+        },
+      },
+      {
+        test: /\.css$/i,
+        use: [
+          isDevelopment ? 'style-loader' : MiniCssExtractPlugin.loader,
+          { loader: 'css-loader', options: { url: false } },
+          'postcss-loader',
+        ],
+      },
+    ],
+  },
+  plugins: [
+    isDevelopment
+      ? undefined
+      : new MiniCssExtractPlugin({
+          filename: '[name].css',
+        }),
+    new HtmlWebpackPlugin({
+      templateContent: `
+      <body></body>
+      <script type="text/javascript">
+      const urlSearchParams = new URLSearchParams(window.location.search);
+      const queryParams = Object.fromEntries(urlSearchParams.entries());
+      const widgetName = queryParams["widgetName"];
+      if (widgetName == undefined) {document.body.innerHTML+="Widget ID not specified."}
+
+      const s = document.createElement('script');
+      s.type = "module";
+      s.src = widgetName+"${SANDBOX_SUFFIX}.js";
+      document.body.appendChild(s);
+      </script>
+    `,
+      filename: 'index.html',
+      inject: false,
+    }),
+    new ProvidePlugin({
+      React: 'react',
+      reactDOM: 'react-dom',
+    }),
+    new BannerPlugin({
+      banner: (file) => {
+        return !file.chunk.name.includes(SANDBOX_SUFFIX) ? 'const IMPORT_META=import.meta;' : '';
+      },
+      raw: true,
+    }),
+    new CopyPlugin({
+      patterns: [
+        { from: 'public', to: '' },
+      ],
+    }),
+    fastRefresh,
+  ].filter(Boolean),
+};
+
+if (isProd) {
+  config.optimization = {
+    minimize: isProd,
+    minimizer: [new EsbuildPlugin()],
+  };
+} else {
+  // for more information, see https://webpack.js.org/configuration/dev-server
+  config.devServer = {
+    port: process.env.PORT ? parseInt(process.env.PORT, 10) : 8080,
+    open: true,
+    hot: true,
+    compress: true,
+    watchFiles: ['src/*'],
+    headers: {
+      'Access-Control-Allow-Origin': '*',
+      'Access-Control-Allow-Headers': 'baggage, sentry-trace',
+    },
+  };
+}
+
+module.exports = config;