Block Reference Interpreter(块引用解读工具)Parses Tine / Logseq English | 简体中文
Part 1 · What it does1.1 The problemTine and Logseq render
Opening that file in VS Code leaves both you and the AI staring at a meaningless ID. Two things break:
This extension indexes the whole graph locally, mapping every UUID to its block and all child blocks, and exposes that to the editor UI and to AI tools. 1.2 BacklinksVS Code also lacks backlinks — where a block is referenced from. Tine and Logseq both ship a backlinks panel; this extension reproduces it, including the reference count badge, hover list, a full panel with restored indentation and expanded subtrees, collapsible branches, and click-to-jump. See 4.5 Backlinks. 1.3 Supported reference forms
All four behave identically in inline rendering, hover preview, AI tools and expanded views. Inline rendering replaces the entire expression, including the 1.4 Feature overview
Part 2 · InstallationTwo steps, both required:
Step 2 is easy to skip, and skipping it is the single most common reason the extension appears to "do nothing". 2.1 Step 1: install the extensionFrom the Marketplace (recommended) — search for "Block Reference Interpreter" in the Extensions view, or:
Extension page: https://marketplace.visualstudio.com/items?itemName=louis-15.block-reference-interpreter From a VSIX — download the From source:
2.2 Step 2: add the vault instructionsRequired. Without it, the AI has no reason to call the tools. VS Code extensions cannot intercept Copilot's built-in file reading. A plain read of a Download
Three things must be right:
The instructions impose five rules: always call Part 3 · Verifying the installationWork through these six checks in order. 3.1 Extension installed — 3.2 Index built — open your vault folder. You should see a notification such as 3.3 Instructions loaded — 3.4 Inline rendering — open a note with a 3.5 AI calls the tools — ask "what does the block reference on line 33 point to?". A tool-call card should appear. If the model answers directly, see 5.1. 3.6 Backlinks — find a block with Part 4 · Usage4.1 AI tools
4.2 Inline rendering
Two modes: 4.3 Hover previewHovering a reference shows the source file and line, subtree size, the block title and its first six lines, plus an Expand full text link. The line count is deliberately short ( 4.4 Expanded view"Expand full text" opens a webview panel, not a read-only text document, so every block's source is clickable. Clicking the source path opens that note and selects the block's first line — selecting the whole line rather than placing a bare cursor, because a thin caret is invisible against a wall of text. Content uses small grey bullets rather than Markdown dashes, matching Tine / Logseq, with indentation restored level by level. Why a webview: links inside a text editor always require Ctrl+Click (clicking means "place the cursor" in an editor). Webview links respond to a plain left click, which is what makes the panel feel like Tine. Set 4.5 Backlinks
Two differences are unavoidable: the count sits at the end of the line rather than floating at the block's top-right, and the panel opens as a tab beside the editor rather than in a right-hand dock. Both are consequences of the VS Code extension model. 4.6 Language
4.7 CommandsAll nine commands live under "Block Reference:" in the command palette: expand current note, expand reference at cursor, expand block by UUID, show backlinks for reference at cursor, show backlinks for block, open backlinks panel, rebuild index, select Tine graph directory, show log. "Rebuild index" and "Select Tine graph directory" are fallbacks, not daily steps. 4.8 Graph detection and index maintenanceOpening a folder that contains both The index updates automatically on: vault open, edits in Tine, saves in VS Code, unsaved edits (250 ms after you stop typing), file creation/deletion, external changes such as a git checkout, and setting changes. Part 5 · Notes5.1 The AI does not call the toolsCheck in order: the instructions file is loaded (3.3); you are in a new chat (instructions load per conversation); name the tool explicitly ("use #blockNote to read this note"); the tools are enabled in the chat tool picker; or the output was truncated (switch to 5.2 Backlinks do not appearIf the badge is missing: 5.3 The index is emptyCheck the 5.4 Data safetyThe extension is read-only. All output goes to webview panels, read-only virtual documents, the output channel, or tool return values. No file is created in your vault. 5.5 Known limitationsOnly 5.6 SettingsSee the settings page (search Appendix · Development
Parsing logic lives in English | 简体中文 在 VS Code 中解析 Tine / Logseq 笔记的
第一部分 · 功能说明1.1 待解决的问题Tine 与 Logseq 使用
在 VS Code 中直接打开该文件时,编辑器与 AI 都只能看到这一串 UUID,无法得知它指向哪个块、该块包含哪些内容。由此产生两类问题:
本插件在本地解析整个笔记图谱,建立「UUID → 被引用块及其全部子块」的映射,并将该能力同时提供给编辑器界面与 AI。 1.2 补齐反向链接能力VS Code 中另有一项基础能力的缺失:反向链接,即某个块被哪些位置引用。 Tine 与 Logseq 均提供反链面板,VS Code 原生不具备。本插件的反链模块以 Tine 的表现作为设计基准,涵盖:块行尾引用计数、悬停列出引用页面、完整面板还原缩进并展开全部子块、子块折叠、单击跳转。详细说明见 4.5 反向链接。 1.3 支持的引用形式
四种形式在行内渲染、悬停预览、AI 工具、展开全文四处行为保持一致:
1.4 功能一览
第二部分 · 安装安装包含两个步骤,两步均需完成:
第二步容易被忽略,但若跳过,AI 通常不会主动调用工具,表现为「已安装但无效果」。这是本插件最常见的使用障碍。 2.1 步骤一:安装扩展方式一:从扩展市场安装(推荐)在 VS Code 扩展面板中搜索「块引用解读工具」并安装,或执行:
扩展主页:https://marketplace.visualstudio.com/items?itemName=louis-15.block-reference-interpreter 方式二:从 VSIX 安装适用于扩展市场不可用、或需要安装特定版本的情形。
或使用命令行:
方式三:从源码构建
2.2 步骤二:配置笔记库指令此步骤为必需项。 若跳过,AI 通常不会主动调用工具。 原因在于 VS Code 扩展无法拦截 Copilot 内置的文件读取行为。AI 读取 因此需要在笔记库中放置一份指令文件,将「遇到块引用必须调用工具」确立为强制规则。 文件来源Release 页面提供独立的压缩包 下载直链(始终指向最新版本):
也可从仓库的 目标位置
按操作系统举例:
三项必须核对的内容
文件开头应当为:
指令文件的核心约束
第三部分 · 验证安装按顺序完成以下 6 项检查,全部通过即表示安装完整。 3.1 扩展是否安装成功
或通过命令行确认:
预期输出形如 3.2 索引是否建立无需手动操作。 打开笔记库文件夹时,插件会自动识别并建立索引,完成后在右下角显示提示:
出现该提示即表示索引正常。 若未出现提示,按顺序排查:
3.3 指令文件是否生效
预期结果:列表中显示一条名为「块引用必须展开」的指令。 若该处为空,说明路径或文件名不正确,请回到 2.2 步骤二逐项核对。 3.4 行内渲染是否生效打开任意一篇包含 预期结果: 若仍显示为裸 UUID,请检查设置 3.5 AI 是否会调用工具在 Chat 中提问:
预期结果:Chat 中出现工具调用卡片,显示正在读取块引用的内容。 若 AI 直接作答而未调用工具,请参阅 5.1 排查:AI 不调用工具。 3.6 反向链接是否生效打开一篇笔记,找到包含 预期结果:该块所在行行尾出现 点击悬停框最下方的「查看完整反链面板」,预期结果:在编辑器旁打开面板,按页面分组列出全部引用,每条包含面包屑、块标题与缩进的子块,标题左侧带有 若看不到徽章,请参阅 5.2 排查:反链不显示。 第四部分 · 使用说明4.1 AI 工具安装插件并重载窗口后,Copilot Chat 的 agent 模式会自动获得三个工具。这些工具仅在内存中计算,不会创建或修改任何文件。
|
| mode | 输出内容 | 适用场景 |
|---|---|---|
list |
仅返回清单(行号 + UUID + 目标块首行) | 引用较多时优先使用,输出通常仅数 KB |
expand(默认) |
完整展开 | 引用较少、需要完整上下文 |
both |
清单与展开内容 | 两者均需 |
引用超过 8 处时,expand 模式会自动附加清单;超出输出预算的部分不会被展开,并在末尾列出未展开的行号。
调用示例
用 #blockNote 读取 pages/项目说明.md,说明第 8 行的块引用指向什么内容
#blockRef 3f7a1c2e-5b9d-4a11-8c3e-1d2f4b6a8c01
4.2 行内渲染
默认启用。编辑器中的 ((uuid)) 会直接显示为目标块的首行文本:
原文: 具体实现参见 ((3f7a1c2e-5b9d-4a11-8c3e-1d2f4b6a8c01))
显示: 具体实现参见 增量索引
具体行为:
- 子块不在行内显示,避免单行内容过长;鼠标悬停时才展开块及其子块。
- 标题的
#/##标记默认去除(tineBlockRef.render.stripHeadingMarks),视觉更整洁。 - 目标块不存在时显示
⚠ 块不存在,便于及时发现失效引用。 - 同一 UUID 重复定义时显示
标题(N 处重复)。 - 行内文字为纯展示内容,不可点击;查看完整内容请悬停后点击「展开全文」。
两种渲染模式
| 模式 | 效果 | 适用场景 |
|---|---|---|
replace(默认) |
隐藏原文,仅显示标题 | 最接近笔记软件的原生观感 |
append |
保留原文,在其后追加 〔标题〕 |
光标行为完全正常,编辑时更便利 |
replace 模式存在固有代价:原文字符宽度被压缩为 0,光标经过引用位置时不可见。复制粘贴得到的仍是原文 ((uuid)),这一点是正确的。若需频繁直接编辑引用本身,建议改用 append 模式。
切换方式:在设置中搜索 tineBlockRef.inlineRender.mode,或直接关闭 tineBlockRef.inlineRender.enabled 恢复显示裸 UUID。
关于 embed 的显示:Tine 原生的 embed 会展开显示整个块的内容。本插件的行内渲染仅显示首行标题,因为多行内容压入单行会破坏笔记排版。需要查看完整内容时,悬停即可看到块及其全部子块。
4.3 悬停预览
将鼠标悬停在任意块引用上,会显示:
- 目标块的来源文件与行号
- 子树规模(行数、字符数)
- 块首行标题与前 6 行内容(含子块层级)
- 【展开全文】链接,点击后打开完整内容
预览行数经过刻意压缩(tineBlockRef.hoverPreviewLines,默认 6):VS Code 的悬停框高度有限,内容过长会将底部按钮挤出可视区域。缩短行数可确保按钮始终可见。
悬空引用会显示「未找到该块」,重复 ID 会列出全部候选位置,不会静默失败。
4.4 展开全文
「展开全文」打开的是网页面板,位于编辑器旁侧,而非只读文本文档。这样设计的核心目的是使每个块的来源均可点击跳转。
单块展开
从悬停框点击「展开全文」,或在命令面板中按 UUID 展开:
块 3f7a1c2e-5b9d-4a11-8c3e-1d2f4b6a8c01
pages/术语表.md · 第 12–15 行
4 行 / 52 字符
点击块上方的「来源」链接,可打开对应笔记并跳转到该块。
┃ 增量索引 来源 pages/术语表.md 第 12–15 行 4 行 / 52 字符
┃ ┌──────────────────────────────────────┐
┃ │ · 只重新解析发生变化的文件 │
┃ │ · 未变化的文件复用上次解析结果 │
┃ └──────────────────────────────────────┘
点击「来源」后的蓝色路径,将打开对应笔记的 Markdown 标签页,并跳转到块的首行(整行会被选中)。
内容以小灰点列表呈现,与 Tine / Logseq 一致,不显示 Markdown 的减号标记——源码记号不属于阅读时应看到的内容。缩进层级逐级还原,子块的子块会再深一层。
整篇展开
通过命令面板「块引用:展开当前笔记为可读版」触发,或在笔记中执行:
笔记展开
pages/项目说明.md
共 3 处块引用
1 │ tags: 性能
2 │
3 │ - # 3 性能优化
…
7 │ - 索引采用增量策略,细节参见 ((3f7a1c2e-5b9d-4a11-8c3e-1d2f4b6a8c01))
8 │
9 │ - 缓存失效条件另见 ((9c4d2b7a-1e83-4f56-b902-7a5c3d8e1f42))
┃ 增量索引 来源 pages/术语表.md 第 12–15 行 4 行 / 52 字符
┃ ┌──────────────────────────────┐
┃ │ · 只重新解析发生变化的文件 │
┃ │ · 未变化的文件复用上次结果 │
┃ └──────────────────────────────┘
原文按行号逐行列出,包含块引用的行会高亮;该行下方紧跟展开的块内容。
跳转时自动选中整行
反链面板的块标题、悬停列表的页面名、展开面板的「来源」链接,三者跳转行为一致:
打开目标笔记的 Markdown 标签页 → 将光标定位到对应行 → 选中整行并滚动至视野中央。
选择整行选中而非仅放置光标的原因:笔记正文通常为满屏文字,光标仅是一条细竖线,落入其中难以辨识。整行选中会显示整行背景色,可明确确认跳转位置是否正确。
采用网页面板的原因
只读文本文档有其优点(支持 Ctrl+F 查找、自由复制),但存在一项无法绕过的限制:
文本编辑器中的链接必须使用 Ctrl + 单击才能响应。
而「点击来源跳回原文」是该面板的主要操作,每次都需要按 Ctrl 才生效,操作成本过高。网页中的链接是标准 <a> 元素,左键单击即可触发。
若更看重文本编辑器的查找与复制能力,反链面板仍保留 tineBlockRef.backlinks.panel = text 开关,可切回文本版;展开全文目前仅提供网页版。
4.5 反向链接
块引用是「从当前语句跳转到目标块」,反向链接方向相反:目标块被哪些位置引用。
Tine 与 Logseq 均提供该功能,VS Code 原生不具备。本插件的反链模块以 Tine 的表现作为设计基准:
| 能力 | Tine | 本插件 |
|---|---|---|
| 被引用块旁显示引用数 | 块右上角数字 | 行尾 🔗 N 徽章 |
| 悬停查看引用页面 | 支持 | 支持,每行附带面包屑 |
| 按页面分组列出全部引用 | 支持 | 支持,按引用条目数降序 |
| 显示引用所在小节 | 3 性能优化 › 3.2 索引策略 |
相同的面包屑路径 |
| 完整展示引用块及其子块 | 支持 | 子树全展开,层级缩进还原 |
| 折叠 / 展开子块 | 小三角 | ▾ / ▸ 三角 + 全部折叠按钮 |
| 单击标题跳转到引用处 | 支持 | 左键单击直接跳转,无需 Ctrl |
| 记住折叠状态 | 支持 | 切换标签页后返回仍保持 |
| AI 可查询反链 | 不支持 | 支持 #blockBacklinks(本插件独有) |
最后一项是 Tine 不具备的能力:Tine 不接入 AI,而本插件的主要目标正是让 AI 读懂笔记。
按场景选择入口
| 需求 | 入口 |
|---|---|
| 快速确认块的被引用次数 | 块行尾的 🔗 N 徽章 |
| 查看引用该块的页面 | 鼠标悬停在徽章上 |
| 跳转到某一处引用 | 悬停框中点击页面名(Ctrl + 单击) |
| 通读全部引用及其上下文 | 悬停框最下方「查看完整反链面板」,或命令面板「块引用:打开反链面板」 |
| 由 AI 分析引用关系 | 直接提问,AI 会调用 #blockBacklinks |
编辑器内:行尾徽章
每个被引用过的块,其所在行行尾会显示一个徽章:
- 增量索引 🔗 2
id:: 3f7a1c2e-5b9d-4a11-8c3e-1d2f4b6a8c01
collapsed:: true
仅显示真正被引用过的块。多数笔记不会出现任何徽章,只有包含被引用块的笔记才会多出这一标记。
徽章位于块首行行尾,而非 id:: 所在行。因为 id:: 只是属性声明,块的身份由其首行内容确定。
徽章使用 VS Code 的 InlayHint 机制,受全局设置
editor.inlayHints.enabled控制。 若该设置为off,徽章将不再显示。此时可将tineBlockRef.backlinks.style改为lens, 改用「块上方独立一行」的方式显示。三个可选值:
inline(行尾徽章,默认)、lens(上方一行)、off(不显示)。
悬停:引用页面列表
鼠标悬停在徽章上时显示:
引用此块的页面(2 个引用块)
- 项目说明 · 3 性能优化 › 3.2 索引策略
- 架构决策 · 2 背景 › 2.1 选型依据
查看完整反链面板
每个页面一行,后接引用发生的具体位置。这一层信息用于在打开完整面板之前,先行判断是否存在目标条目。
一次最多列出 8 个页面,超出的部分显示为「还有 N 个页面未列出」,此时应打开完整面板查看。
点击页面名将直接打开对应笔记并跳转到引用所在行。 悬停框中的链接遵循 VS Code 的统一规则,需要 Ctrl + 单击,以避免鼠标划过时误触发跳转。
徽章本身不可点击。面板入口位于悬停框最下方,与鼠标位置距离极近,无需再增加一个需要 Ctrl 修饰的点击区域。
完整面板
点击「查看完整反链面板」,在旁侧打开独立标签页:
块 3f7a1c2e-5b9d-4a11-8c3e-1d2f4b6a8c01 的反向链接
定义位置:pages/术语表.md 第 12 行
块内容:增量索引
引用统计:2 个页面 / 2 个引用块
单击蓝色文字跳转到引用位置;点击左侧小三角可折叠或展开子块。
[全部折叠]
项目说明
pages/项目说明.md · 1 处引用
3 性能优化 › 3.2 索引策略 ← ① 面包屑:引用所在小节
▾ 增量索引 ← ② 三角 + 块标题(可点击跳转)
· 只重新解析发生变化的文件 ← ③ 该块的子块
· 未变化的文件复用上次解析结果 ← ③ 该块的子块
架构决策
pages/架构决策.md · 1 处引用
2 背景 › 2.1 选型依据
▸ 增量索引
三层信息分别对应不同的判断需求:
| 层级 | 内容 | 回答的问题 |
|---|---|---|
| ① 面包屑 | 3 性能优化 › 3.2 索引策略 |
引用出现在哪个小节。同一块被引用在「3.2 索引策略」与「5.1 历史遗留问题」下,含义完全不同 |
| ② 块标题 | 增量索引 |
被引用的是这个块。左键单击直接跳转到引用所在行(整行会被选中) |
| ③ 缩进子块 | 带圆点的若干行 | 引用处可见的完整内容。无需打开笔记即可了解该处上下文 |
第三层是对齐 Tine 的关键:子树完整展开,缩进层级逐级还原,子块的子块会再深一级。
折叠子块
标题左侧的 ▾ / ▸ 控制子块显示:
- 点击三角折叠或展开该条目的子块。
- 仅确有子块的引用才显示三角;无子块的条目保留等宽空位,确保标题左边缘对齐,不会左右错开。
- 顶部提供「全部折叠 / 全部展开」按钮,文案随当前状态切换。
- 折叠状态保存在面板内,切换到其他标签页后返回仍然保持。
三角为标准按钮元素,可通过 Tab 聚焦、回车触发,屏幕阅读器能够读取其展开/折叠状态。
跳转与排序
点击蓝色块标题将打开引用所在笔记,选中引用所在行并滚动至视野中央。面板不会关闭,可继续点击下一条。
面板按引用条目数降序排列,引用最多的页面位于最前(通常为主题页或索引页)。同一页面内按行号升序排列,符合阅读顺序。
两个上限可调整:
| 配置 | 默认值 | 作用 |
|---|---|---|
tineBlockRef.backlinks.subtreeLines |
0(不限) |
每个引用块最多展开多少行子树 |
tineBlockRef.backlinks.itemsPerPage |
20 |
每个页面最多列出几条引用 |
关于子树上限:多数被引用块的子树规模在 20 行以内,因此默认不限制。但确实存在少数体量较大的块。若遇到显示过长的情况,将 subtreeLines 设为 30 即可截断,并在末尾提示剩余行数。
与 Tine 的两处差异
以下两处无法做到完全一致,此处如实说明:
| 项目 | Tine | 本插件 | 原因 |
|---|---|---|---|
| 引用数显示位置 | 块的右上角浮动数字 | 块首行行尾的徽章 | VS Code 的 InlayHint 只能插入行内文字流,不存在「块」这一布局概念 |
| 面板位置 | 页面右侧栏内嵌 | 编辑器旁的标签页 | VS Code 扩展没有合法的「在主编辑器右侧插入自有 UI」接口 |
功能层面一致,位置层面的差异由 VS Code 扩展模型决定,无法照搬。
由 AI 查询反向链接
这个块被哪些位置引用了?
AI 会调用 #blockBacklinks,获得与面板完全相同的分组、排序与面包屑路径(两者共用同一套数据整理逻辑,不会出现「面板显示 3 条、AI 显示 4 条」的不一致)。
面包屑对该用途尤为关键:AI 获得「引用出现在 3.2 索引策略 下」这一信息后,才能说明该块被用于哪些具体语境,而不只是罗列文件名。
另外两个查询入口
除面板外,命令面板还提供两个以跳转为目标的入口:
| 命令 | 用途 |
|---|---|
| 块引用:查看光标处块引用的反向链接 | 光标位于某个 ((uuid)) 上时,直接列出引用它的位置,选中即跳转 |
| 块引用:查看块的反向链接 | 手动输入 UUID 查询,同样选中即跳转 |
这两个入口使用 QuickPick 列表,与面板的分工为:QuickPick 用于跳转到某一处,面板用于通读全部。
4.6 界面语言
tineBlockRef.language 控制本扩展的运行时文案,取值 auto(跟随 VS Code 界面语言,默认)、en、zh-cn。切换后建议重载窗口,让已经渲染出来的内容一并更新。
适用范围:提示消息、悬停预览、反链面板、展开网页、AI 工具的返回内容。
命令标题与设置项名称不在其列——它们由 VS Code 在渲染命令面板与设置页时读取 package.nls,扩展没有运行时改写它们的接口。需要整界面统一时,请切换 VS Code 自身的显示语言。
另注:AI 工具的描述(modelDescription 与参数说明)固定为英文,因为模型对英文工具描述的理解更稳定;工具返回内容则跟随上述设置。
4.7 命令一览
| 命令 | 使用场景 |
|---|---|
| 块引用:展开当前笔记为可读版 | 需要将整篇笔记提供给 AI 阅读 |
| 块引用:展开光标处的块引用 | 只需查看某一个引用 |
| 块引用:按 UUID 展开单个块 | 已知 UUID,直接查询 |
| 块引用:查看光标处块引用的反向链接 | 确认某条内容的引用位置并跳转 |
| 块引用:查看块的反向链接 | 手动输入 UUID 查询并跳转 |
| 块引用:打开反链面板 | 通读完整反链(亦可从行尾徽章的悬停框进入) |
| 块引用:重建索引 | 兜底手段。日常无需使用,索引会自动维护 |
| 块引用:选择 Tine 图谱目录 | 自动探测失败时,或需要在多个笔记库间切换 |
| 块引用:显示日志 | 排查问题 |
「重建索引」与「选择 Tine 图谱目录」均为兜底手段,不属于日常步骤。正常情况下安装完成并打开笔记库后,无需再操作这两项。
4.8 图谱目录识别
打开同时包含 pages/ 与 logseq/ 的文件夹,插件会自动识别并建立索引,无需任何配置。
判定依据(满足任一即认定):
- 同时存在
pages/与logseq/—— Logseq / Tine 的标准布局 - 存在
logseq/config.edn - 存在
.tine-trash/—— Tine 特有目录
向上查找最多 10 层,因此从 pages/某个子目录/ 打开同样能够定位到根目录。
需要手动指定的情形
仅限以下两种:
- 只打开了单个
.md文件而未打开文件夹 —— VS Code 不会触发工作区变更事件,插件无法感知。 - 需要临时切换到另一个笔记库 —— 自动识别的是「当前文件所属的图谱」,如需更换则手动指定。
手动指定一次后写入用户级配置,跨工作区保留:
Ctrl+Shift+P → 块引用:选择 Tine 图谱目录 → 选择同时包含 pages/ 与 logseq/ 的文件夹。
同时打开多个笔记库
仅索引一个:优先当前打开文件所属的图谱,其次为第一个工作区文件夹。需要更换时使用手动指定命令。
4.9 索引更新时机
全自动维护,无需记住任何操作:
| 时机 | 行为 |
|---|---|
| 打开 VS Code / 打开新的笔记库文件夹 | 全量建立,完成后右下角提示 |
| 在 Tine 中修改笔记 | 自动增量更新(Tine 保存即写盘,插件监听磁盘变化) |
| 在 VS Code 中保存 | 自动增量更新 |
| 在 VS Code 中编辑但尚未保存 | 自动增量更新,停止输入 0.25 秒后生效 |
新建 / 删除 .md 文件 |
自动增量更新 |
| 外部工具修改文件(git 切换分支、其他编辑器) | 自动增量更新 |
修改 include / exclude / graphRoot 设置 |
自动重建 |
| 关闭文件且放弃保存 | 回滚到磁盘内容 |
「编辑但未保存」这一项是刻意支持的:新增带 id:: 的块或新增 ((uuid)) 引用后,无需先保存即可悬停查看展开结果。
第五部分 · 注意事项
5.1 排查:AI 不调用工具
按顺序排查:
- 指令文件未生效 —— 回到 3.3,确认 Workspace 下存在 1 条指令。
- 会话未刷新 —— 指令按会话加载,修改文件后需要新建会话。
- 模型调用工具不积极 —— 在提问中直接指明工具名,例如:
用 #blockNote 读取这篇笔记。 - 工具被禁用 —— 点击 Chat 输入框上方的工具图标,确认
blockRef/blockNote/blockBacklinks三项均已勾选。 - 引用过多导致截断 —— 改用
#blockNote的mode: "list"获取清单,再用#blockRef逐个读取。
5.2 排查:反链不显示
反链徽章不可见,或面板为空。
徽章完全不可见,按顺序排查:
- VS Code 全局关闭了行内提示 —— 设置中搜索
editor.inlayHints.enabled,若为off,徽章必然消失且不会有任何提示。请开启该项,或将tineBlockRef.backlinks.style改为lens。 - 该块确实未被引用 —— 多数笔记中不存在被引用过的块,这类笔记不会显示任何徽章。可在其他笔记中搜索该 UUID 进行验证。
- 相关设置被关闭 —— 检查
tineBlockRef.backlinks.style不为off。 - 索引尚未建立 —— 打开「块引用:显示日志」,确认索引已完成。
徽章存在但悬停列表为空 —— 索引已过期。执行「块引用:重建索引」,或在其他文件中做一次修改以触发增量更新。
面板无法打开 —— 查看输出面板日志。若为 webview 相关错误,可临时将 tineBlockRef.backlinks.panel 改为 text 验证;若文本版可正常打开,说明问题出在网页面板。
面板内点击链接无响应 —— 该文件可能已被移动或删除。面板内容是打开时的快照,不会自动跟随磁盘变化;重新打开面板即可。
5.3 排查:索引为空
出现「图谱目录里没有找到笔记」警告,或工具持续返回「未找到块」时:
- 打开「块引用:显示日志」,确认
[索引] 图谱根目录:后显示的是哪个路径。 - 该路径下必须确实存在
pages/,且其中包含.md文件。 - 路径为空或不正确 —— 执行 块引用:选择 Tine 图谱目录 重新指定。
- 日志中出现「没有匹配到任何 Markdown 文件」 —— 检查
tineBlockRef.include是否被误改(默认应为pages/**/*.md与journals/**/*.md)。
不要依赖「重建索引」修复此问题。该命令仅重新扫描当前目录;目录本身未正确识别时,重建不会改变任何结果。
5.4 数据安全
本插件全程只读:不修改、不格式化、不重写任何笔记文件。所有输出均指向以下位置:
- 网页面板(反链、展开全文;关闭时不会提示保存,也不产生磁盘文件)
- 只读虚拟文档(仅供
backlinks.panel = text的文本版反链使用) - 输出面板日志
- 工具返回值与悬停提示
5.5 已知限制
- 仅索引
pages/与journals/;logseq/下的回收站与备份不参与索引。 - 反链的引用数显示位置为块首行行尾,而非 Tine 那样的块右上角浮动数字;面板位置为编辑器旁的标签页,而非 Tine 的右侧内嵌栏。功能一致,位置受 VS Code 扩展模型限制。
- 反链徽章依赖
editor.inlayHints.enabled;关闭后徽章消失且无提示(将backlinks.style改为lens可绕过)。 - 展开全文仅提供网页版,不支持 Ctrl+F 查找(网页内可使用浏览器自带的查找功能)。反链面板可通过
backlinks.panel = text切回可查找的文本版。 - 同时打开多个笔记库时仅索引其中一个(当前文件所属者优先,其次为第一个工作区文件夹)。需要切换时使用「块引用:选择 Tine 图谱目录」。
- 悬空引用(目标块已被删除)会明确标注为「未找到」,不会静默失败。
- 重复 ID(同一 UUID 出现在多个文件)会列出全部候选并提示歧义。
- Tine 自带的
tine block show命令在 Windows 上不可用(报错cannot reach a graph's owner),因此本插件自行实现解析,不依赖该 CLI。 - 行内渲染在
replace模式下会将原文 UUID 的字符宽度压缩为 0,光标经过引用时不可见原文。如需频繁直接编辑引用,请切换至append模式。
5.6 配置参考
| 配置 | 默认值 | 说明 |
|---|---|---|
tineBlockRef.language |
auto |
运行时文案语言:auto 跟随 VS Code / en 英文 / zh-cn 简体中文。命令标题与设置项名称始终跟随 VS Code 界面语言 |
tineBlockRef.graphRoot |
自动探测 | 图谱根目录 |
tineBlockRef.include |
pages/**/*.md, journals/**/*.md |
参与索引的文件 |
tineBlockRef.exclude |
logseq/**, .tine-trash/** 等 |
排除的路径 |
tineBlockRef.maxDepth |
3 |
嵌套引用展开层数 |
tineBlockRef.maxOutputChars |
20000 |
单次输出字符预算 |
tineBlockRef.hideProperties |
id, collapsed |
渲染时隐藏的属性 |
tineBlockRef.inlineRender.enabled |
true |
是否将 ((uuid)) 显示为块标题 |
tineBlockRef.inlineRender.mode |
replace |
replace 隐藏原文 / append 追加标题 |
tineBlockRef.inlineRender.maxTitleLength |
60 |
行内标题最大长度 |
tineBlockRef.inlineRender.showMissing |
true |
悬空引用显示 ⚠ 块不存在 |
tineBlockRef.render.stripHeadingMarks |
true |
渲染时去除标题的 # 标记 |
tineBlockRef.hoverPreviewLines |
6 |
悬停预览行数 |
tineBlockRef.showIndexNotification |
true |
索引建立完成后显示提示 |
tineBlockRef.backlinks.style |
inline |
反链标记呈现方式:inline 行尾徽章 / lens 上方一行 / off 不显示 |
tineBlockRef.backlinks.panel |
html |
反链面板形式:html 左键单击跳转 / text 只读文本(Ctrl+单击,可 Ctrl+F) |
tineBlockRef.backlinks.subtreeLines |
0(不限) |
反链面板中每个引用块最多展开的行数 |
tineBlockRef.backlinks.itemsPerPage |
20 |
反链面板中每个页面最多显示的引用条数 |
tineBlockRef.backlinks.pathDepth |
3 |
反链面板中面包屑保留的祖先层级数 |
附录 · 开发说明
npm install
npm run build # 打包到 dist/
npm test # 单元测试 + 真实笔记库冒烟测试
npm run typecheck # 类型检查
核心解析逻辑位于 src/core/,刻意不依赖 vscode 模块,可在普通 Node 环境中直接测试。
架构约定、发布流程与平台限制的细节见仓库根目录的 AGENTS.md。
目录结构
src/core/ 纯解析层(块树、引用扫描、索引、反链报告、渲染、图谱探测与路径匹配),不依赖 vscode
src/vscode/ VS Code 适配层(工具、命令、悬停、行内渲染、反链徽章与面板)
src/test/ 单元测试与真实笔记库冒烟测试
templates/ 分发给用户的模板文件(笔记库指令)
docs/ 开发者内部文档(已 gitignore,不对外发布)
笔记库指令模板
指令文件的唯一来源为:
templates/github/instructions/block-reference.instructions.md
发布 Release 时需单独打包一个压缩包,内部结构必须为:
notebook-instructions.zip
└── .github/
└── instructions/
└── block-reference.instructions.md
该压缩包由 CI 自动生成,无需本地打包。工作流 .github/workflows/release.yml
会在发布前从 templates/ 现场构建,并打印压缩包内容以便核对层级。
需要在本地手动生成时(例如调试工作流),使用下述 PowerShell 脚本。显式写入 条目名可以规避不同平台间的路径分隔符差异:
Add-Type -AssemblyName System.IO.Compression.FileSystem
$zip = [System.IO.Compression.ZipFile]::Open('notebook-instructions.zip','Create')
$entry = $zip.CreateEntry('.github/instructions/block-reference.instructions.md')
$stream = $entry.Open()
$bytes = [System.IO.File]::ReadAllBytes('templates/github/instructions/block-reference.instructions.md')
$stream.Write($bytes, 0, $bytes.Length)
$stream.Dispose(); $zip.Dispose()
打包后必须解压验证:压缩包内必须是三层路径 .github/instructions/文件名,
多一层目录会导致用户解压后指令不生效。
关于行尾符:CI 在 Linux 上检出代码,生成的压缩包内文件为 LF 行尾; Windows 本地生成的为 CRLF。两者内容一致,功能无差异,因此无需强制统一。
发版流程
版本号变更已全部自动化。发版只需三步:
- 修改
package.json的version,并在CHANGELOG.md补充对应条目 - 提交并推送到
main - 创建并推送标签:
git tag -a v0.4.0 -m "v0.4.0"; git push origin refs/tags/v0.4.0
标签推送后,工作流会依次执行:校验标签与版本一致 → 类型检查 → 单元测试 → 构建 → 打包 → 发布扩展市场 → 创建 GitHub Release 并上传两个附件。
认证使用 Trusted Publishing(OIDC 联邦身份),仓库中不存储任何长期凭据。
首次配置需在扩展市场发布者页面的 Trusted Publishing 中创建政策,填入仓库
owner、仓库名与工作流文件名(release.yml),三者须精确匹配。
微软已于 2026 年 12 月 1 日退役 Azure DevOps 全局 PAT,因此本项目不采用 PAT 方案。若需了解背景,参见 Visual Studio Marketplace Trusted Publishing 文档。
工具内部名与引用名
两者容易混淆,此处单独说明:
registerTool 内部名 |
toolReferenceName(用户与模型可见) |
|---|---|
tineBlockRef_readBlock |
blockRef |
tineBlockRef_readNote |
blockNote |
tineBlockRef_findBacklinks |
blockBacklinks |
编写文档、指令或让 AI 引用时必须使用右列。 左列仅出现在扩展源码中,模型完全不可见。