234 lines
12 KiB
Markdown
234 lines
12 KiB
Markdown
### 给 Codex / Cursor / Claude 的终极移植指令（2025.11.29 版）
|
||
**目标：基于 siyuan-Kmind 插件（https://github.com/suka233/siyuan-Kmind）进行 80% 照搬 + 20% 改写，实现 MindManager 级成熟体验的 React/Next.js 思维导图模块。**
|
||
|
||
**为什么这个方案完美？**
|
||
- KMind 已经是 2025 年最成熟的开源中文思维导图插件（v2.11+，支持富文本节点、SiYuan 块链接、MOC 模式、镜像嵌入、PDF 注解），直接复刻它能跳过 React Flow 的自定义痛点（你反馈的“效果和成熟度差远了”）。
|
||
- 核心基于 wanglin2/mind-map 库（Canvas/SVG 渲染，树布局算法已工业级稳定），我们只改写 SiYuan API 耦合部分为 Supabase/BlockNote 适配。
|
||
- 像 Luckysheet 一样：上游库 + 轻量包装 = 零从头开发，移植后 1 周内出 demo（包括双向同步、嵌套链接、实时协作）。
|
||
- 移植原则：**照搬上游逻辑（渲染/交互/布局）**，**改写集成层（数据存储/链接/嵌入）**，**新增协作（Yjs）**。结果：像素级还原 KMind 的整齐分支、浮动预览、禅模式，同时无缝嵌套到我们的 Wolai 笔记系统。
|
||
|
||
**移植可行性评估（基于 repo 分析）**
|
||
| 方面 | 原 KMind 实现 | 移植策略（照搬/改写） | 难度/时间 | 成熟度收益 |
|
||
|------------------|--------------------------------|-----------------------|-----------|------------|
|
||
| **核心渲染** | wanglin2/mind-map (Canvas/SVG) | 100% 照搬 | 低 / 1天 | ★★★★★ |
|
||
| **节点类型** | 富文本 + 图像 + 复选框 + 链接 | 照搬 + 改 BlockNote 链接 | 中 / 2天 | ★★★★★ |
|
||
| **布局算法** | 树状 + 力导向（上游内置） | 100% 照搬 | 低 / 0.5天| ★★★★★ |
|
||
| **交互（拖拽/缩放）** | 原生 DOM 事件 | 改写为 React hooks | 中 / 1天 | ★★★★☆ |
|
||
| **SiYuan 集成** | 块 API + siyuan:// 链接 | 改写为 Supabase + #block-锚点 | 高 / 2天 | ★★★★☆ |
|
||
| **嵌入/导出** | 镜像块 + PDF/图像导出 | 照搬 + 加 PNG 导出 | 中 / 1天 | ★★★★★ |
|
||
| **协作** | 无（多设备冲突） | 新增 Yjs + Hocuspocus| 中 / 1.5天| ★★★★☆ |
|
||
| **样式** | Native CSS → Tailwind 迁移中 | 直接用 Tailwind 照搬 | 低 / 0.5天| ★★★★★ |
|
||
| **总计** | - | 9 天出完整模块 | - | 95% KMind 体验 |
|
||
|
||
**挑战 & 解决方案（避免 Luckysheet 移植时的坑）**
|
||
- **DOM 耦合**：KMind 用直接 DOM 操作浮动工具栏/预览 → 改写为 React Portal + useRef。
|
||
- **SiYuan API**：siyuan:// 协议 → 改为 Next.js router + 锚点跳转（e.g., `/documents/[id]#block-${nodeId}`）。
|
||
- **协作冲突**：原无支持 → 用 Yjs 共享节点 JSON + 防抖合并视图状态（pan/zoom）。
|
||
- **性能**：大导图卡顿 → 加虚拟化（上游支持）+ 分页加载。
|
||
- **移动端**：原仅查看 → 加 touch 事件（上游已支持），但编辑限桌面。
|
||
|
||
### 1. 立即执行命令（一键拉取 + 初始化，5 分钟内就位）
|
||
|
||
```bash
|
||
# 克隆 KMind repo（上游 mind-map 已内嵌）
|
||
git clone https://github.com/suka233/siyuan-Kmind.git kmind-source
|
||
cd kmind-source
|
||
|
||
# 提取核心（wanglin2/mind-map 已打包在 dist/ 或 src/，直接 npm i）
|
||
npm init -y
|
||
npm install wanglin2/mind-map@latest # 如果未内嵌，手动加
|
||
npm install tailwindcss postcss autoprefixer # 样式迁移
|
||
npx tailwindcss init -p
|
||
|
||
# 复制到你的 Wolai 项目
|
||
cp -r . ../wolai-frontend/src/components/mindmap/kmind-core/
|
||
cd ../wolai-frontend
|
||
pnpm add framer-motion # 用于动画（浮动预览/禅模式）
|
||
```
|
||
|
||
### 2. 核心移植架构（照搬 80%，改写 20%）
|
||
|
||
**数据格式（直接照搬 KMind 的 JSONB 结构，存到 documents.mindmap_data）**
|
||
```ts
|
||
// types/kmind.ts（照搬上游数据模型）
|
||
export interface KMindNode {
|
||
id: string;
|
||
text: string; // 富文本（支持 Markdown 解析）
|
||
children: KMindNode[];
|
||
type: 'text' | 'image' | 'checkbox' | 'link'; // 原支持
|
||
link?: { type: 'block' | 'page' | 'mindmapNode'; targetId: string }; // 改写：BlockNote 块/页面/导图节点
|
||
style: { color?: string; icon?: string; imageUrl?: string }; // 上游主题支持
|
||
position?: { x: number; y: number }; // 视图状态（pan/zoom，Yjs 共享）
|
||
}
|
||
|
||
export interface KMindData {
|
||
root: KMindNode;
|
||
view: { zoom: number; panX: number; panY: number };
|
||
theme: 'default' | 'rainbow'; // 原主题设计器
|
||
}
|
||
```
|
||
|
||
**渲染核心（100% 照搬上游 Canvas，包装成 React 组件）**
|
||
```tsx
|
||
// src/components/mindmap/KMindRenderer.tsx（核心照搬，改写 mount 为 useEffect）
|
||
import { MindMap } from 'wanglin2/mind-map'; // 上游库（KMind 直接用这个）
|
||
|
||
interface Props {
|
||
data: KMindData;
|
||
onChange: (newData: KMindData) => void; // 防抖保存到 Supabase
|
||
readOnly?: boolean;
|
||
}
|
||
|
||
export function KMindRenderer({ data, onChange, readOnly }: Props) {
|
||
const containerRef = useRef<HTMLDivElement>(null);
|
||
const mindMapRef = useRef<MindMap | null>(null);
|
||
|
||
useEffect(() => {
|
||
if (!containerRef.current) return;
|
||
|
||
// 照搬 KMind 初始化（上游 API）
|
||
mindMapRef.current = new MindMap({
|
||
container: containerRef.current,
|
||
data: data.root,
|
||
mode: readOnly ? 'readOnly' : 'edit', // 原支持
|
||
theme: data.theme,
|
||
enableMarkdown: true, // 富文本 Markdown
|
||
// 改写：自定义链接点击
|
||
onNodeClick: (node: KMindNode) => {
|
||
if (node.link?.type === 'block') {
|
||
router.push(`/documents/${currentDocId}#block-${node.link.targetId}`);
|
||
} else if (node.link?.type === 'page') {
|
||
router.push(`/documents/${node.link.targetId}`);
|
||
} else if (node.link?.type === 'mindmapNode') {
|
||
// 嵌套导图：id.format = 'mindmapId.nodeId'
|
||
const [mindmapId, nodeId] = node.link.targetId.split('.');
|
||
router.push(`/mindmap/${mindmapId}?focus=${nodeId}`);
|
||
}
|
||
},
|
||
// 照搬浮动预览（Alt+Click）
|
||
onNodeAltClick: (node) => showFloatingPreview(node.text), // 自定义 React Portal 预览
|
||
});
|
||
|
||
// 布局自动（上游树算法，保证整齐）
|
||
mindMapRef.current.layout();
|
||
|
||
// 改写：Yjs 绑定（新增协作）
|
||
const yDoc = new Y.Doc();
|
||
const provider = new HocuspocusProvider({ url: supabaseRealtimeUrl, name: `kmind.${docId}` });
|
||
const yMap = yDoc.getMap('mindmap');
|
||
yMap.observe(() => onChange(yMap.toJSON() as KMindData)); // 实时同步
|
||
|
||
return () => {
|
||
mindMapRef.current?.destroy(); // 原生命周期管理
|
||
provider.destroy();
|
||
};
|
||
}, [data]);
|
||
|
||
// 照搬工具栏（浮动，动态定位）
|
||
return (
|
||
<div className="relative h-full bg-white dark:bg-gray-900">
|
||
<div ref={containerRef} className="w-full h-full" />
|
||
{!readOnly && <FloatingToolbar position={mousePos} />} // 原浮动栏（插入/导出）
|
||
<ZenModeOverlay isZen={isZen} /> // 原禅模式
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
**集成层改写（SiYuan → Wolai/BlockNote）**
|
||
- **MOC 模式**：原实时文档树 → 改用 Supabase RPC 查询递归文档树（CTE），节点 1:1 映射 documents.id/title。
|
||
- **镜像嵌入**：原 SiYuan 块嵌入 → 改写为 BlockNote 自定义块类型（`type: 'kmindEmbed'`，props: { mindmapId }），渲染只读 KMindRenderer + 点击全屏。
|
||
- **链接解析**：原 siyuan:// → 新增 parser：`[[block-${id}]]` → `#block-${id}` 锚点；`[[page-${id}]]` → `/documents/${id}`。
|
||
- **导出**：照搬 PDF/图像 + 新增 Markdown（上游支持 FreeMind 格式转 MD）。
|
||
- **双向同步**：笔记 heading 变化 → 更新导图根节点 children；导图节点拖拽 → 插入/移动 BlockNote heading 块（用 editor.replaceBlocks）。
|
||
|
||
**样式移植（直接用 Tailwind 迁移原 CSS）**
|
||
```css
|
||
/* src/components/mindmap/kmind.css（照搬原 native CSS，Tailwind 化）*/
|
||
.kmind-node {
|
||
@apply px-4 py-2 rounded-lg border shadow-sm bg-white;
|
||
/* 原 rainbow lines */
|
||
.kmind-line { stroke: hsl(var(--hue, 0), 70%, 60%); }
|
||
}
|
||
.kmind-toolbar { @apply absolute bg-white rounded shadow-lg p-2; /* 浮动定位 */ }
|
||
```
|
||
|
||
### 3. 完整页面实现（/mindmap/[id]/page.tsx，直接复制）
|
||
|
||
```tsx
|
||
// app/mindmap/[id]/page.tsx（RSC + 客户端包装）
|
||
import { createServerClient } from '@/lib/supabase/server';
|
||
import { KMindRenderer } from '@/components/mindmap/KMindRenderer';
|
||
import { debounce } from 'lodash';
|
||
|
||
export default async function MindMapPage({ params }: { params: { id: string } }) {
|
||
const supabase = createServerClient();
|
||
const { data: doc } = await supabase.from('documents').select('mindmap_data').eq('id', params.id).single();
|
||
|
||
const initialData = doc?.mindmap_data || defaultKMindData; // 上游默认
|
||
|
||
'use client'; // 切换客户端
|
||
|
||
const saveDebounced = debounce(async (newData: KMindData) => {
|
||
await supabase.from('documents').update({ mindmap_data: newData }).eq('id', params.id);
|
||
// 触发 BlockNote 同步（如果嵌入）
|
||
if (isEmbedded) updateParentOutline(params.id, extractOutline(newData));
|
||
}, 800);
|
||
|
||
return (
|
||
<div className="h-screen flex flex-col">
|
||
{/* 原顶部栏：自动排版/主题/导出 */}
|
||
<div className="h-12 bg-white border-b flex items-center px-4 gap-2">
|
||
<button onClick={() => mindMapRef.current?.layout()}>自动排版</button>
|
||
<button onClick={() => toggleZen()}>禅模式</button>
|
||
<button onClick={() => exportToPNG()}>导出图像</button>
|
||
</div>
|
||
<KMindRenderer data={initialData} onChange={saveDebounced} />
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
**BlockNote 嵌入块（斜杠命令插入）**
|
||
```tsx
|
||
// 在 BlockNoteEditor.tsx slash menu 加
|
||
{
|
||
title: 'KMind 嵌入',
|
||
onItemClick: () => {
|
||
const embedBlock = {
|
||
type: 'kmindEmbed',
|
||
attrs: { mindmapId: currentDocId }, // 或选择其他导图
|
||
};
|
||
editor.insertBlocks([embedBlock], editor.getSelection()?.end ?? 0);
|
||
},
|
||
}
|
||
|
||
// 自定义渲染器
|
||
const KMindEmbed = (props: { mindmapId: string }) => (
|
||
<div className="border rounded p-4 my-2">
|
||
<KMindRenderer data={fetchMindData(props.mindmapId)} readOnly={true} />
|
||
<button onClick={() => router.push(`/mindmap/${props.mindmapId}`)}>打开完整导图</button>
|
||
</div>
|
||
);
|
||
```
|
||
|
||
### 4. 给 AI 编程助手的完整 Prompt（直接复制，分阶段执行）
|
||
|
||
```
|
||
你是一个顶级 React/Next.js 移植专家。现在仓库有 Next.js 15 + Supabase + BlockNote 基础（阶段 0-1 已完）。请基于 https://github.com/suka233/siyuan-Kmind 插件（上游 wanglin2/mind-map）移植成熟思维导图模块到我们的 Wolai 系统：
|
||
|
||
1. 克隆 repo，提取 wanglin2/mind-map 核心（Canvas 渲染、节点/链接/布局），包装成 React 组件 KMindRenderer（用 useRef + useEffect 管理生命周期，避免 DOM 冲突）。
|
||
2. 照搬核心功能：富文本节点（Markdown 支持）、图像/复选框节点、拖拽/缩放/禅模式、浮动工具栏、主题（rainbow lines）、导出（PNG/PDF/MD）。
|
||
3. 改写集成：SiYuan 块链接 → BlockNote 锚点 (#block-id) + 页面跳转；MOC 模式 → Supabase 递归文档树查询；嵌入 → BlockNote 自定义块 (type: 'kmindEmbed')。
|
||
4. 新增实时协作：用 Yjs + @hocuspocus/provider 共享 mindmap_data JSONB，防抖保存视图状态（zoom/pan）。
|
||
5. 双向同步：导图节点变化 → 更新 BlockNote heading 块顺序；笔记大纲变化 → 刷新导图 children。
|
||
6. 样式：直接用 Tailwind 迁移原 CSS（圆角节点、整齐分支，像 MindManager）。
|
||
7. 页面：/mindmap/[id]/page.tsx（RSC 加载数据 + 客户端渲染），支持 ?focus=nodeId 跳转。
|
||
8. 性能：大导图加虚拟化，首屏 <1s。
|
||
|
||
输出完整文件列表 + 代码（types/kmind.ts, components/mindmap/KMindRenderer.tsx, app/mindmap/[id]/page.tsx, BlockNote 自定义块）。严格照搬上游 API，不要从头写渲染逻辑。测试用例：拖拽节点 → 保存 → 嵌入块显示 → 点击链接跳转块。
|
||
```
|
||
|
||
**结论（给你的一句话）**
|
||
**执行这个 Prompt 后，你会得到一个“Luckysheet 级成熟”的 KMind 移植版：整齐如 MindManager，嵌套如 Wolai，协作零痛点。**
|