feat(notes): 阶段二双向链接（[[ wiki-link 自动补全 + 反向链接面板 + noteLinks 索引 + React Flow 笔记图谱）

Author: Aparencia

client/package-lock.json

@@ -44,6 +44,7 @@
     "@tiptap/extension-color": "^3.27.3",
     "@tiptap/extension-highlight": "^3.27.3",
     "@tiptap/extension-image": "^3.27.3",
+    "@tiptap/extension-mention": "3.27.3",
     "@tiptap/extension-placeholder": "^3.27.3",
     "@tiptap/extension-table": "^3.27.3",
     "@tiptap/extension-table-cell": "^3.27.3",
@@ -57,6 +58,7 @@
     "@tiptap/pm": "^3.27.3",
     "@tiptap/react": "^3.27.3",
     "@tiptap/starter-kit": "^3.27.3",
+    "@tiptap/suggestion": "3.27.3",
     "@xyflow/react": "^12.11.2",
     "better-sqlite3": "^11.0.0",
     "class-variance-authority": "^0.7.1",

client/package.json

@@ -0,0 +1,68 @@
+/**
+ * 反向链接面板（笔记底部）
+ * Backlinks panel (bottom of note editor)
+ *
+ * @ai-context: 阶段二双向链接。查询 noteLinks 中 toId=当前笔记 的链接，
+ * 解析来源笔记标题（取自 useNoteStore.notes），去重后列出可点击跳转的 chip。
+ * 无反链时返回 null（不占位）。依赖 notes 变化自动刷新（新建链接后可见）。
+ * @ai-context: Queries noteLinks targeting the current note, resolves source
+ * titles from the notes store, renders clickable chips; null when no backlinks.
+ */
+import { useEffect, useState } from 'react';
+import { useNavigate } from 'react-router-dom';
+import { Link2 } from 'lucide-react';
+import { getBacklinks } from '../lib/links/noteLinkStore';
+import { useNoteStore } from '../store/useNoteStore';
+
+interface BacklinkEntry {
+  id: string;
+  title: string;
+}
+
+export function BacklinksPanel({ noteId }: { noteId: string }) {
+  const navigate = useNavigate();
+  const notes = useNoteStore((s) => s.notes);
+  const [backlinks, setBacklinks] = useState<BacklinkEntry[]>([]);
+
+  useEffect(() => {
+    let cancelled = false;
+    getBacklinks(noteId)
+      .then((links) => {
+        if (cancelled) return;
+        const seen = new Set<string>();
+        const entries: BacklinkEntry[] = [];
+        for (const link of links) {
+          if (seen.has(link.fromId)) continue;
+          const note = notes.find((n) => n.id === link.fromId);
+          if (!note) continue;
+          seen.add(link.fromId);
+          entries.push({ id: note.id, title: note.title });
+        }
+        setBacklinks(entries);
+      })
+      .catch(() => {});
+    return () => { cancelled = true; };
+  }, [noteId, notes]);
+
+  if (backlinks.length === 0) return null;
+
+  return (
+    <div className="mt-6 pt-4 border-t border-border/40">
+      <div className="flex items-center gap-1.5 text-c1 text-text-tertiary mb-2">
+        <Link2 className="w-3.5 h-3.5" strokeWidth={1.5} />
+        <span>{backlinks.length} 个反向链接</span>
+      </div>
+      <div className="flex flex-wrap gap-2">
+        {backlinks.map((b) => (
+          <button
+            key={b.id}
+            onClick={() => navigate(`/notes/${b.id}`)}
+            className="inline-flex items-center px-2.5 py-1 rounded-kb-sm bg-brand-50 text-brand-700 text-b3 font-medium hover:bg-brand-100 transition-colors"
+          >
+            {b.title || '未命名笔记'}
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+}

client/src/features/notes/components/BacklinksPanel.tsx

@@ -0,0 +1,107 @@
+/**
+ * WikiLink TipTap 扩展（双向链接的编辑侧）
+ * WikiLink TipTap extension (editing side of bidirectional links)
+ *
+ * @ai-context: 阶段二双向链接。基于 Mention.extend（name:'wikiLink'），输入
+ * `[[` 触发笔记标题自动补全：suggestion char='['，allow 要求 range 文本以 '[['
+ * 开头（即输入了第二个 '['），items 的 query 去掉前导 '[' 后按标题过滤
+ * useNoteStore.notes。选中后以 wikiLink 节点（attrs id/label）替换 `[[xxx`，
+ * 渲染为可识别 chip。弹窗经 ReactRenderer 手动定位（项目未装 tippy.js）。
+ * @ai-context: Mention-based wiki-link; `[[` triggers note-title autocomplete;
+ * selected note becomes a wikiLink node (attrs id/label) rendered as a chip.
+ */
+import Mention from '@tiptap/extension-mention';
+import { mergeAttributes } from '@tiptap/core';
+import { ReactRenderer } from '@tiptap/react';
+import type { SuggestionProps, SuggestionKeyDownProps } from '@tiptap/suggestion';
+import { useNoteStore } from '../../store/useNoteStore';
+import { WikiLinkSuggestions, type WikiLinkSuggestionsHandle, type WikiLinkItem } from './WikiLinkSuggestions';
+
+type RectGetter = (() => DOMRect | null) | null | undefined;
+
+/** suggestion 弹窗渲染器（ReactRenderer + 手动 fixed 定位，无 tippy 依赖） */
+function suggestionRender() {
+  let component: ReactRenderer<WikiLinkSuggestionsHandle, { items: WikiLinkItem[]; command: (item: { id: string; label: string }) => void }> | null = null;
+  let container: HTMLDivElement | null = null;
+
+  const updatePosition = (clientRect: RectGetter) => {
+    if (!container || !clientRect) return;
+    const rect = clientRect();
+    if (!rect) return;
+    container.style.left = `${rect.left}px`;
+    container.style.top = `${rect.bottom + 4}px`;
+  };
+
+  const cleanup = () => {
+    component?.destroy();
+    container?.remove();
+    component = null;
+    container = null;
+  };
+
+  return {
+    onStart: (props: SuggestionProps) => {
+      component = new ReactRenderer(WikiLinkSuggestions, { props, editor: props.editor });
+      container = document.createElement('div');
+      container.style.position = 'fixed';
+      container.style.zIndex = '9999';
+      container.appendChild(component.element);
+      document.body.appendChild(container);
+      updatePosition(props.clientRect);
+    },
+    onUpdate: (props: SuggestionProps) => {
+      component?.updateProps(props);
+      updatePosition(props.clientRect);
+    },
+    onKeyDown: (props: SuggestionKeyDownProps) => {
+      if (props.event.key === 'Escape') { cleanup(); return true; }
+      return component?.ref?.onKeyDown(props) ?? false;
+    },
+    onExit: cleanup,
+  };
+}
+
+export const WikiLink = Mention.extend({
+  name: 'wikiLink',
+
+  renderHTML({ node, HTMLAttributes }) {
+    return [
+      'span',
+      mergeAttributes(HTMLAttributes, { class: 'wiki-link', 'data-id': node.attrs.id }),
+      `${node.attrs.label ?? ''}`,
+    ];
+  },
+
+  renderText({ node }) {
+    return `[[${node.attrs.label ?? ''}]]`;
+  },
+}).configure({
+  HTMLAttributes: { class: 'wiki-link' },
+  suggestion: {
+    char: '[',
+    // 仅当输入了 `[[`（range 文本以 '[[' 开头）时才弹出 / only after `[[`
+    allow: ({ editor, range }) => {
+      const text = editor.state.doc.textBetween(range.from, range.to);
+      return text.startsWith('[[');
+    },
+    // query 含前导 '['（第二个括号），去掉后按标题过滤 / strip leading '[' then filter by title
+    items: ({ query }): WikiLinkItem[] => {
+      const realQuery = query.startsWith('[') ? query.slice(1) : query;
+      const q = realQuery.trim().toLowerCase();
+      return useNoteStore.getState().notes
+        .filter((n) => (n.title || '').toLowerCase().includes(q))
+        .slice(0, 8)
+        .map((n) => ({ id: n.id, label: n.title }));
+    },
+    command: ({ editor, range, props }) => {
+      const attrs = props as { id?: string | null; label?: string | null };
+      if (!attrs.id) return;
+      editor.chain().focus()
+        .deleteRange(range)
+        .insertContent({ type: 'wikiLink', attrs: { id: attrs.id, label: attrs.label ?? '' } })
+        .insertContent(' ')
+        .run();
+    },
+    render: suggestionRender,
+  },
+});

client/src/features/notes/components/editor/WikiLink.ts

@@ -0,0 +1,80 @@
+/**
+ * WikiLink 自动补全列表（suggestion 弹窗内容）
+ * WikiLink autocomplete list (suggestion popup content)
+ *
+ * @ai-context: 阶段二双向链接。由 WikiLink 扩展的 suggestion render 经
+ * ReactRenderer 挂载。键盘上下选择/回车插入（onKeyDown 经 ref 暴露给
+ * suggestion 插件）；无匹配项时返回 null 隐藏弹窗。
+ * @ai-context: Mounted via ReactRenderer from the WikiLink suggestion render.
+ * Exposes onKeyDown through ref; returns null (hidden) when no matches.
+ */
+import { forwardRef, useEffect, useImperativeHandle, useState } from 'react';
+import { Link2 } from 'lucide-react';
+import { cn } from '@/lib/utils';
+
+export interface WikiLinkItem {
+  id: string;
+  label: string;
+}
+
+interface WikiLinkSuggestionsProps {
+  items: WikiLinkItem[];
+  command: (item: { id: string; label: string }) => void;
+}
+
+export interface WikiLinkSuggestionsHandle {
+  onKeyDown: (props: { event: KeyboardEvent }) => boolean;
+}
+
+export const WikiLinkSuggestions = forwardRef<WikiLinkSuggestionsHandle, WikiLinkSuggestionsProps>(
+  function WikiLinkSuggestions({ items, command }, ref) {
+    const [selectedIndex, setSelectedIndex] = useState(0);
+
+    useEffect(() => setSelectedIndex(0), [items]);
+
+    const selectItem = (index: number) => {
+      const item = items[index];
+      if (item) command({ id: item.id, label: item.label });
+    };
+
+    useImperativeHandle(ref, () => ({
+      onKeyDown: ({ event }) => {
+        if (items.length === 0) return false;
+        if (event.key === 'ArrowUp') {
+          setSelectedIndex((i) => (i + items.length - 1) % items.length);
+          return true;
+        }
+        if (event.key === 'ArrowDown') {
+          setSelectedIndex((i) => (i + 1) % items.length);
+          return true;
+        }
+        if (event.key === 'Enter') {
+          selectItem(selectedIndex);
+          return true;
+        }
+        return false;
+      },
+    }));
+
+    if (items.length === 0) return null;
+
+    return (
+      <div className="w-60 max-h-64 overflow-y-auto rounded-kb-md border border-border/60 bg-bg-elevated shadow-kb-md py-1">
+        <div className="px-3 py-1.5 text-c1 text-text-tertiary border-b border-border/40">链接到笔记</div>
+        {items.map((item, i) => (
+          <button
+            key={item.id}
+            onClick={() => selectItem(i)}
+            className={cn(
+              'w-full flex items-center gap-2 px-3 py-1.5 text-left text-b2 transition-colors',
+              i === selectedIndex ? 'bg-brand-50 text-brand-700' : 'text-text-primary hover:bg-bg-tertiary',
+            )}
+          >
+            <Link2 className="w-3.5 h-3.5 flex-shrink-0 opacity-60" strokeWidth={1.5} />
+            <span className="truncate">{item.label || '未命名笔记'}</span>
+          </button>
+        ))}
+      </div>
+    );
+  },
+);

client/src/features/notes/components/editor/WikiLinkSuggestions.tsx

@@ -22,6 +22,7 @@ import { Image } from '@tiptap/extension-image';
 import { TextAlign } from '@tiptap/extension-text-align';
 import { Color } from '@tiptap/extension-color';
 import { TextStyle } from '@tiptap/extension-text-style';
+import { WikiLink } from '../components/editor/WikiLink';
 import { soundPlayer } from '@/lib/audio/SoundPlayer';
 import { compressImageForNote } from '../lib/imageCompress';
 import type { SaveStatus } from '../components/NoteEditHeader';
@@ -103,6 +104,7 @@ export function useNoteEditor({ noteId, rawContent, noteKey, updateNote }: UseNo
       TextAlign.configure({ types: ['heading', 'paragraph'] }),
       Color,
       TextStyle,
+      WikiLink,
     ],
     content: initialContent,
     // TipTap v3 不再自动给编辑元素加 tiptap 类（v2 会自动加），