281 lines
13 KiB
Markdown
281 lines
13 KiB
Markdown
# 5-38 双向链接系统（Bidirectional Links）v1
|
||
|
||
> 状态：process（调研完成，待分阶段落地）
|
||
> 日期：2026-07-29
|
||
> 目标：避免「多处引用同一知识却各写一份」的多真源问题；在 local-first + tree-first kernel 下建立**单真源引用边 + 反链投影**。
|
||
|
||
---
|
||
|
||
## 0. 一句话结论
|
||
|
||
**正向链接写在正文（Markdown / block 语义）→ 保存/索引时抽出 `references` 边 → 反链只是该边的反向投影。**
|
||
TipTap 只负责插入/渲染；**不**在前端维护第二套链接图。
|
||
|
||
---
|
||
|
||
## 1. TipTap 更新检查（2026-07-29）
|
||
|
||
| 位置 | 版本 | 说明 |
|
||
| --- | --- | --- |
|
||
| `reference-code/leptos-tiptap/tiptap` | **@tiptap/\* 2.27.2** | 当前主链 bridge 依赖 |
|
||
| npm `v2-latest` | **2.27.2** | v2 线已停在此点 |
|
||
| npm `latest` | **3.29.2**（2026-07-28） | 主线已进 v3 很久 |
|
||
| `reference-code/tiptap-main` 快照 | packages 约 **3.23.4**，git ~2026-05 | 参考仓库偏旧于 npm latest |
|
||
| `@tiptap/extension-mention` | 3.29.2 与 core 对齐 | v3 线 mention；v2 仍有独立包 |
|
||
|
||
### 1.1 对双向链接的含义
|
||
|
||
- **双向链接不依赖 TipTap 3**。核心是 kernel 边 + Markdown 持久化 + 索引投影。
|
||
- **本阶段不建议为双向链接单独升 v3**。v2→v3 是独立迁移（schema/API/extension 打包方式变化），成本远高于「补 page mention + 反链面板」。
|
||
- 可继续参考：
|
||
- `reference-code/leptos-tiptap`（当前 bridge / link extension）
|
||
- `reference-code/tiptap-notion-like-registry` 的 `mention-dropdown-menu` / `link-popover`（**UI 交互**，不是用户 mention 语义）
|
||
- `reference-code/tiptap-main` 仅作 API 对照；升 v3 时再同步拉取
|
||
|
||
### 1.2 可选后续（非本系统阻塞）
|
||
|
||
- 独立 checklist：评估 leptos-tiptap bridge 升 `@tiptap/*@3` 的 breaking 面。
|
||
- 升版前冻结：现有 `page_reference` ↔ link mark round-trip 测试。
|
||
|
||
---
|
||
|
||
## 2. 现状盘点（已有资产 / 缺口）
|
||
|
||
### 2.1 已有（可复用，勿重造）
|
||
|
||
| 层 | 资产 | 路径/入口 |
|
||
| --- | --- | --- |
|
||
| 语法 | `[[page\|label]]` / `((block\|label))` | `mnote-editor-core/src/markdown.rs` |
|
||
| 块类型 | `page_reference` / `PageReference` | core-protocol、bridge、editor actor |
|
||
| 编辑投影 | page_ref → 段落 + `link` mark（class `mnote-page-block-link`） | `document-tiptap-conversion-runtime.js`、`block_transform.rs` |
|
||
| 索引反链 | 扫 `](*.md)` + `[[…]]`，API 可读 | `local_search_index.rs` → `GET /api/search/local-index/backlinks` |
|
||
| Kernel 类型 | `KernelEdgeType::References` / `BacklinksTo` | `core-protocol/src/kernel.rs` |
|
||
| 页面选项 | `collapseBacklinks` / `showBlockRefCount` | page aggregate + UI preferences |
|
||
| 证据边 | markdown 链接 → deterministic edges | document evidence / LightRAG 旁路（勿与笔记反链混为同一产品入口） |
|
||
| 思源边界 | 借产品闭环，不借 `.sy` / SQL 真相 | `design/09-siyuan-reference/...` |
|
||
|
||
### 2.2 缺口（多真源风险点）
|
||
|
||
1. **编辑器层**：page_ref 降级为普通 link mark，无独立 inline atom；`[[` 输入规则 / 页面搜索插入不完整（legacy editor 仅插 `[[page]]` 占位）。
|
||
2. **索引层**：`extract_backlinks` 存的是**字符串目标**（路径 / wikilink 文本），未统一解析为稳定 `documentId` / ObjectIdentity；重命名后易漂。
|
||
3. **Kernel 层**：`References` / `BacklinksTo` 已声明，**未**成为 page_aggregate / 反链 UI 的正式 query 面。
|
||
4. **UI 层**：`collapseBacklinks` 明确 **「待接线：当前 Rust 壳未挂回链面板」**；旧 local-index 反链 DOM 已故意不复活（避免与 LightRAG 资料库入口混淆）。
|
||
5. **语义层**：E28 `@mention` 已暂停且纠偏为「人/会议」，**不是**页面引用；页面引用应走 `[[` / slash「页面」/ 转 page_reference，勿与 `@` 混用。
|
||
6. **块引用**：`((block))` 语法与类型有，主编辑岛与稳定 blockId 持久化尚未闭环。
|
||
|
||
---
|
||
|
||
## 3. 产品语义（对齐思源 / Wolai，落 MNote 边界）
|
||
|
||
### 3.1 三种引用（必须分开）
|
||
|
||
| 种类 | 用户形态 | 持久化 | 索引边 | 优先级 |
|
||
| --- | --- | --- | --- | --- |
|
||
| **页面引用** | `[[Title]]` / `[[path\|显示名]]` / page_reference 块 | Markdown 或 block props | `references` → page | **P0** |
|
||
| **块引用** | `((blockId))` | 需稳定 blockId | `references` → block | P1 |
|
||
| **外链 / 附件** | `[x](url)` / 资源 path | 普通 link / resource_ref | 不进「笔记反链」主列表（可进 resourceRefs） | 已有，保持 |
|
||
|
||
### 3.2 「双向」的真正含义
|
||
|
||
- 用户只写**正向**引用。
|
||
- 系统维护 `source → target` 边。
|
||
- **反链** = `target ← sources` 的投影查询，不是第二份手写列表。
|
||
- 图谱 / 搜索 / AI 上下文 / 导图挂件 **只读同一套边**，禁止各自扫一遍 Markdown 各存一份。
|
||
|
||
### 3.3 真源顺序（硬规则）
|
||
|
||
```
|
||
本地 .md（+ 将来稳定 block 元数据）
|
||
↓ 解析 / 保存
|
||
Page Aggregate blocks（含 page_reference / 将来 inline ref）
|
||
↓ 抽出
|
||
Reference edges（kernel 或 local-index 统一表，单一实现）
|
||
↓ 投影
|
||
反链面板 / search / AI tools / 可选图谱
|
||
```
|
||
|
||
**禁止**：
|
||
|
||
- 浏览器 localStorage 存链接图
|
||
- TipTap JSON 与 Markdown 各维护一套「官方」反链
|
||
- LightRAG entity 边冒充笔记 page backlink（可并列展示，须分入口）
|
||
|
||
---
|
||
|
||
## 4. 目标架构
|
||
|
||
### 4.1 引用边最小模型
|
||
|
||
```text
|
||
ReferenceEdge {
|
||
source_document_id: String, // local-md:… 或稳定 id
|
||
source_block_id: Option<String>,
|
||
target_kind: page | block | resource | external,
|
||
target_document_id: Option<String>, // 解析成功时
|
||
target_raw: String, // 原文 token / path，解析失败仍可展示
|
||
anchor_text: Option<String>,
|
||
locator: Option<String>, // 行号 / offset，便于跳转
|
||
}
|
||
```
|
||
|
||
- **写入**：文档保存成功、local-index refresh、watcher 变更后 **整页替换**该 source 的出边（思源式：按 root 删再插，避免脏边）。
|
||
- **读取**：
|
||
- `query.backlinks_to(documentId)` → 谁链到我
|
||
- `query.references_from(documentId)` → 我链向谁
|
||
- 与已有 API 对齐：先让 `GET /api/search/local-index/backlinks` **成为**上述 query 的 HTTP 面，再视需要升为 kernel query 名 `search.local_index.backlinks` → 最终 `kernel.backlinks_to`。
|
||
|
||
### 4.2 目标解析（消灭字符串多真源）
|
||
|
||
解析顺序建议：
|
||
|
||
1. 已是 `local-md:…` / 已知 documentId
|
||
2. 相对路径相对**当前文件** resolve → 规范化相对 root → `local-md:{encode}`
|
||
3. wikilink `[[Title]]`：按标题 / 文件名 stem 在索引内消歧（多命中则 raw 保留 + UI 标黄）
|
||
4. 失败：`target_document_id = null`，`target_raw` 保留，反链仍可按 raw 弱匹配（可选）
|
||
|
||
重命名 / 移动：走现有 tree command；索引 rebuild 时重算边（P0 可全量 rebuild；P1 增量 + transferBlockRef 类迁移可参考思源 `transferBlockRef`，**不**照搬 SQL）。
|
||
|
||
### 4.3 TipTap 显示层（v2 即可）
|
||
|
||
**不要**把 Notion registry 的「用户 Mention」直接当页面引用。
|
||
|
||
推荐两档：
|
||
|
||
| 档 | 形态 | 说明 |
|
||
| --- | --- | --- |
|
||
| **A（最小，先做）** | 保持 `paragraph` + `link` mark + `mnote-page-block-link`，补强 round-trip 与点击打开 | 已有主链，改动小 |
|
||
| **B（产品完整）** | 新增 inline atom：`pageMention` / 或专用 mark attrs：`data-mnote-ref="page"` + `data-target-id` | 便于样式、未解析态、禁止拆字 |
|
||
|
||
输入：
|
||
|
||
- InputRule：`[[` 打开页面搜索（复用 local search / tree query，**不是** `@`）
|
||
- Slash：插入「页面引用」
|
||
- 块菜单：段落 ↔ page_reference 转换（已有 `replace_block_with_page_reference` 可扩）
|
||
|
||
Markdown 导出：
|
||
|
||
- 优先 `[[target|label]]` 或 `[label](rel/path.md)`（**工作区内统一一种**；建议 **wikilink 作规范、md link 作兼容导入**）
|
||
- `mnote-editor-core` 已用 `[[id|label]]`，local-folder 路径型文档应导出 **相对路径** 以便 Git 可读：`[[docs/child|子页]]` 或 `[子页](docs/child.md)` — **实现前定一种 SSOT 写进本文件 §6**。
|
||
|
||
### 4.4 反链 UI
|
||
|
||
- 挂在**页面底部或右侧信息区**（Wolai/思源心智），**不要**塞回已移除的 local-index 设置页。
|
||
- 消费：`backlinks` API + Page Aggregate 选项 `collapseBacklinks`。
|
||
- 每条：来源标题、路径、可选 snippet、点击 `open document`（带 sourceKind/rootUri）。
|
||
- `showBlockRefCount`：有块引用后再接线。
|
||
|
||
### 4.5 与 AI / LightRAG
|
||
|
||
| 需求 | 入口 |
|
||
| --- | --- |
|
||
| 「哪些笔记链到这篇」 | 笔记反链 API / kernel edges |
|
||
| 「资料库里实体/PDF 证据」 | LightRAG / knowledge-rag |
|
||
| Agent 写引用 | 必须写 Markdown/block 合法引用，再走同一抽取器 |
|
||
|
||
---
|
||
|
||
## 5. 分阶段落地（可执行）
|
||
|
||
### Phase 0 — 契约冻结（0.5–1d）
|
||
|
||
- [ ] 选定工作区持久化规范：`[[rel/path|label]]` **或** `[label](rel.md)` 为写出 SSOT（导入两者都认）。
|
||
- [ ] 固定 `ReferenceEdge` 字段与 `documentId` 解析顺序（§4.2）。
|
||
- [ ] 明确 `@` ≠ 页面引用（文档 + slash 文案）。
|
||
|
||
### Phase 1 — 索引单真源（1–2d）**【优先】**
|
||
|
||
- [ ] 强化 `extract_backlinks`：输出结构化 edge（含 resolved id），不只是字符串列表。
|
||
- [ ] `query_local_backlinks` 按 **resolved documentId** 聚合；兼容旧字符串。
|
||
- [ ] 单测：A→B 的 `[[B]]` 与 `[B](b.md)` 反链一致；重命名后 refresh 更新。
|
||
- [ ] 保持 `task452` 语义：API 可用；不恢复旧 settings DOM。
|
||
|
||
### Phase 2 — 反链面板（1–2d）
|
||
|
||
- [ ] 文档页挂载 backlinks panel（读 Phase 1 API）。
|
||
- [ ] 接通 `collapseBacklinks`。
|
||
- [ ] Smoke：两篇本地 md 互链，B 页可见 A。
|
||
|
||
### Phase 3 — 编辑器插入体验（2–3d）
|
||
|
||
- [ ] `[[` 触发页面搜索 + 插入规范 token / page_reference。
|
||
- [ ] 保存后索引增量/全量更新边。
|
||
- [ ] 未解析目标的视觉态（可选）。
|
||
- [ ] **仍用 TipTap 2.27.2**；不夹带 v3。
|
||
|
||
### Phase 4 — Kernel 边对齐（按主线空档）
|
||
|
||
- [ ] local-index 实现升为 `KernelEdgeType::References` 的唯一写入路径（或薄封装）。
|
||
- [ ] `BacklinksTo` 作为派生查询，不双写。
|
||
- [ ] Page Aggregate 可附带 `backlinks` 摘要（注意体积与权限）。
|
||
|
||
### Phase 5 — 块引用（后置）
|
||
|
||
- [ ] 稳定 blockId（与 UniqueID / 导出策略一起设计）。
|
||
- [ ] `((id))` 解析、预览、transfer on move。
|
||
- [ ] `showBlockRefCount`。
|
||
|
||
### 明确不做（本 v1）
|
||
|
||
- 为双向链接升级 TipTap 3
|
||
- 复制思源 `refs` SQL 表为产品真相
|
||
- 用 LightRAG 替代笔记反链
|
||
- 恢复旧 local-index 设置页反链 DOM
|
||
- 把 `@` 改成页面引用
|
||
|
||
---
|
||
|
||
## 6. 待决事项（实现前二选一写死）
|
||
|
||
1. **写出格式 SSOT**
|
||
- 方案 W：wikilink `[[rel/path|label]]`（贴近思源/Obsidian，editor-core 已有）
|
||
- 方案 M：标准 md link `[label](rel.md)`（Git 友好、通用）
|
||
- **建议**：索引与解析两者都认；**新插入默认 W**，导出可配置（默认 W）。
|
||
|
||
2. **page_reference 块 vs inline**
|
||
- 块级：独占一段（当前）
|
||
- 行内：段落中的 mention atom
|
||
- **建议**：P0 块级 + link mark；P1 行内 atom（真正「文中引用」）。
|
||
|
||
3. **反链面板位置**
|
||
- 页底固定区 vs 右侧 drawer
|
||
- **建议**：页底折叠区（`collapseBacklinks` 已存在语义）。
|
||
|
||
---
|
||
|
||
## 7. 参考索引
|
||
|
||
| 来源 | 用途 |
|
||
| --- | --- |
|
||
| 思源 `kernel/sql` `refs` 表 / `block_ref_query.go` | 边模型、按 root 重建、反链查询形状 |
|
||
| 思源 conf `Backlink*` / `VirtualBlockRef` | 产品选项；虚拟引用可后置 |
|
||
| `design/09-siyuan-reference/...` | 借鉴边界 |
|
||
| `design/01-tree-first-graph-kernel/...` | tree + references 边 |
|
||
| leptos-tiptap `tiptap_link.ts` | link mark bridge |
|
||
| notion-like `mention-dropdown-menu` | 仅 suggestion UI 模式 |
|
||
| `local_search_index.rs` `extract_backlinks` | 现抽取实现 |
|
||
| `sidebar-page-settings-runtime.js` | collapseBacklinks 待接线文案 |
|
||
|
||
---
|
||
|
||
## 8. 验收标准（Phase 1–2 最小闭环）
|
||
|
||
1. 在 root 下创建 `A.md`，正文写入指向 `B.md` 的规范引用并保存。
|
||
2. 打开 `B`：反链面板出现 `A`（标题可点，带 local source 参数）。
|
||
3. 删除 A 中引用并保存 / 刷新索引后，B 反链消失。
|
||
4. 同一套数据：`GET .../local-index/backlinks` 与面板一致。
|
||
5. 无第二套前端链接缓存；无 TipTap 3 升级。
|
||
|
||
---
|
||
|
||
## 9. 与主线关系
|
||
|
||
当前主线仍是 Page Aggregate / tree / local-first。双向链接应：
|
||
|
||
- **先**吃透已有 local-index + page_reference（Phase 1–2）
|
||
- **再**编辑体验（Phase 3）
|
||
- Kernel 图边与块引用跟 tree-first 空档合并，避免另起存储
|
||
|
||
---
|
||
|
||
*本文是 process 设计；落地时按 Phase 开 checklist / smoke，完成后迁 `done/`。*
|