✨ feat(vscode): 代码阅读预览按住 ⌘ / Ctrl 点名字跳到定义

docs/superpowers/specs/code-reader/spec.md

@@ -20,6 +20,7 @@
 | 侧栏点文件 | 支持的语言默认打开成「预览」；不支持的语言用普通编辑器打开 |
 | 块内修改 | 改的就是文件本身：未保存标记、⌘S 保存、⌘Z 撤销都照常，切回「预览」按新代码重新翻译 |
 | 折叠 | 有子块的块、属性表里带子行的行能折叠，默认全部展开 |
+| 跳到定义 | 和普通编辑器一样 ⌘ / Ctrl + 点击名字跳到定义，定义由 VS Code 装的语言扩展（Pylance、TypeScript 语言服务……）查；目标语言有代码阅读就在预览里打开 |
 | 侧栏文件树 | 只看和打开：展开目录、打开文件、刷新、全部折叠；不做新建 / 重命名 / 删除 |
 | 译文用词 | 结构照抄原语言，只翻关键字、内置类型、运算符；用专业术语（`export` → 公共，`catch` → 捕获，`===` → 全等） |
 | 函数、导入、常量、变量块 | 预览不显示一行译文，显示树形属性表；属性值里的类型、表达式照常直译 |
@@ -71,6 +72,20 @@
 
 值里的表达式只翻落在块头部里的那一段：`const v = useMemo(() => { … })` 这种值带语句块主体回调的块，回调主体是子块，值只翻到 `useMemo(() =>`，和块头部一致。
 
+### 跳到定义
+
+- 能点的：预览里（属性表的名称、类型、来源、导入项、默认值、值，以及一行译文）照抄自源码的名字——标识符、属性名、类型名、点分模块名的每一节（`luffy_agent.core.db` 三节各自能点，和 VS Code 一样）、字符串（TypeScript 的模块路径 `'./x'` 就是字符串）。翻出来的关键字、运算符、说明词不能点。
+- 链接和编辑器里一样：只有按住修饰键（macOS ⌘，其余平台 Ctrl）、鼠标停在**查得到定义**的名字上时，名字加下划线、换成链接色（`--vscode-editorLink-activeForeground`）、光标变手形；松开修饰键或移开就恢复。有没有定义问扩展端（`vscode.executeDefinitionProvider`，文档 uri + 名字在源码里的位置），回答按文档版本缓存，同一版本里每个名字只问一次，旧版本的迟到回答丢掉。
+- ⌘ / Ctrl + 点击：
+  - 一处定义，在当前文件：原地滚过去；
+  - 一处定义，另一个文件，语言有代码阅读：在同一个编辑器组用预览打开（`vscode.openWith`），滚过去；这个文件的预览已经在这一组开着就切过去、发给它，不重新打开；
+  - 一处定义，语言没有代码阅读：在同一个编辑器组用普通编辑器打开，选中定义处的名字；
+  - 几处定义：先弹挑选框（每项「相对路径:行号」，下面一行是那行源码），挑一处再按上面跳；
+  - 没有定义：不动（本来也不显示链接）。
+  - 和普通编辑器里 ⌘ + 点击一样：目标是否按「预览标签」打开听 `workbench.editor.enablePreview`；`workbench.editor.enablePreviewFromCodeNavigation` 为假（默认）时先把当前预览标签固定住，免得被目标替掉。
+- 滚过去：目标块是显示着定义处那个名字的块（找不到就取包含定义那一行的块）；它的祖先块折叠着就展开，名字在折叠的属性行子行里（参数、导入项）就展开那一行。整块已在视口里不滚，否则滚到视口正中（比视口高就顶部对齐）。然后目标块的边框和底色往聚焦色（`--vscode-focusBorder`）闪三下，共约 1.5 秒后复原；同一块再跳一次从头闪；系统开了「减少动态效果」时改成静止高亮 1.5 秒。
+- 不按修饰键的点击照旧；⌘ / Ctrl + 点击名字不会触发块的编辑切换、折叠。
+
 ## 通用契约
 
 放在 `vscode/src/codeReader/contract.ts`，语法树类型用 `@vscode/tree-sitter-wasm` 自带的 web-tree-sitter 类型。
@@ -150,7 +165,12 @@ export type TokenRole =
   | 'hint'      // 属性表里的说明词：未标注 无 N 个 默认导出 …
   | 'variable' | 'function' | 'type' | 'string' | 'number' | 'literal' | 'comment' | 'plain'
 
-export interface Segment { text: string, role: TokenRole }
+/**
+ * offset：这段照抄自源码里的名字（标识符、属性名、类型名、点分模块名的一节）或字符串时，它在源码里的起始下标，
+ * 预览拿它向 VS Code 查定义、跳过去；译词、提示词没有。由从语法树叶子生成这段的一方填（模板直译引擎的译文和属性表）；
+ * 第三方翻译插件可以不填，不填就不能跳。
+ */
+export interface Segment { text: string, role: TokenRole, offset?: number }
 
 /** 属性表里展开的一个子行：几列对齐的格子。 */
 export interface PropertyItem { cells: Segment[][] }
@@ -315,8 +335,13 @@ interface BlockViewBase {
 type BlockView = BlockViewBase & ({ translation: Segment[] } | { properties: PropertyRow[] })
 ```
 
-- 扩展 → webview：`{ type: 'document', version, languageId, blocks: BlockView[], translators: { id, label }[], translatorId, error?: string }`，文档每次变化（防抖 150ms）重发。
+- 扩展 → webview：
+  - `{ type: 'document', version, languageId, blocks: BlockView[], translators: { id, label }[], translatorId, error?: string, reveal?: Reveal }`，文档每次变化（防抖 150ms）重发。`reveal = { line, definition? }` 只随新预览的第一份文档走：从文本编辑器切过来时是它顶部那一行（滚到包含这行的块、顶到顶部，折叠的不展开）；跳到定义时还带 `definition`（定义处名字在源码里的下标），按「跳到定义」一节展开、滚动、闪。
+  - `{ type: 'reveal', line, definition? }`：同上，发给已经开着的预览。页面正在重新加载（标签页切回来）时收不到，扩展端改成随它 `ready` 后的第一份文档带过去。
+  - `{ type: 'definitionProbed', version, offset, found }`：回答 `probeDefinition`。
 - webview → 扩展：
+  - `{ type: 'probeDefinition', version, offset }`：按住修饰键悬停到带 `offset` 的名字上时问有没有定义；`version` 不是当前文档版本就不答。
+  - `{ type: 'goToDefinition', version, offset }`：修饰键 + 点击，按「跳到定义」一节跳。
   - `{ type: 'ready' }`
   - `{ type: 'edit', startLine, endLine, text }`：用 `WorkspaceEdit` 把这几行整行替换成 `text`（每行补回原来第一行的缩进）。
   - `{ type: 'selectTranslator', id }`：按 `languageId` 记到 `globalState`，重发文档。
@@ -359,6 +384,8 @@ vscode/src/codeReader/
   explorer/fileTree.ts   侧栏文件树
   editor/previewEditor.ts  CustomTextEditorProvider
   editor/messages.ts     消息类型
+  editor/definitions.ts  查定义（vscode.executeDefinitionProvider）、几处定义的挑选框
+  editor/definitionAction.ts  查到的定义 → 怎么跳（纯函数）
   index.ts               registerCodeReader(context): CodeReaderApi
 vscode/webview-ui/code-reader.html + src/codeReader/  预览界面（React，Vite 第二个入口；属性表在 PropertyGrid.tsx）
 ```
@@ -370,6 +397,7 @@ vscode/webview-ui/code-reader.html + src/codeReader/  预览界面（React，Vit
 - 翻译：上面两张样例表逐字一致；属性名不被翻；每个被翻的词单独成段；节点模板嵌套时正确、槽位里照样翻、没命中模板的节点照抄；属性表里的值和一行译文用同一套表和模板。
 - `blockView`：`codeTokens` 拼起来等于 `code`；去缩进正确；函数、导入、常量、变量块只带属性表，其余块只带译文。
 - 行替换：多行块替换后缩进正确。
+- 跳到定义：TS / Python 译文和属性表里的名字、点分模块名每一节、模块字符串带下标且指回源码原文，关键字、运算符、说明词不带（前面有中文注释也对得上）；查到的定义 → 不动 / 原地 / 预览 / 普通编辑器 / 挑选框；webview 里按下标找目标块、要展开的祖先块和属性行，滚动位置。
 - 注册表：注册 / 注销后 `languageIds` 与可选翻译正确；同一语言多个翻译时按 `globalState` 选中。
 
 ## 收尾

vscode/src/codeReader/contract.ts

@@ -93,7 +93,11 @@ export type TokenRole
     | 'hint' // 属性表里的说明词：未标注 无 N 个 默认导出 …
     | 'variable' | 'function' | 'type' | 'string' | 'number' | 'literal' | 'comment' | 'plain'
 
-export interface Segment { text: string, role: TokenRole }
+/**
+ * 一段着色的文字。offset：这段照抄自源码里的名字（标识符、属性名、类型名、点分模块名的一节）或字符串时，
+ * 它在源码里的起始下标（同 SourceSpan 的下标），预览拿它向 VS Code 查定义、跳过去；译词、提示词没有。
+ */
+export interface Segment { text: string, role: TokenRole, offset?: number }
 
 /** 属性表里展开的一个子行：几列对齐的格子，例如参数的名称 / 类型 / 默认值。 */
 export interface PropertyItem { cells: Segment[][] }

vscode/src/codeReader/editor/definitionAction.test.ts

@@ -0,0 +1,44 @@
+import type { DefinitionTarget } from './definitionAction'
+import { describe, expect, it } from 'vitest'
+import { definitionAction } from './definitionAction'
+
+const CURRENT = 'file:///ws/app/routes.py'
+
+function at(uri: string, line: number, supported = true, character = 4): DefinitionTarget {
+  return { uri, line, character, supported }
+}
+
+describe('⌘ + 点击查到定义之后怎么跳', () => {
+  it('没有定义：不动', () => {
+    expect(definitionAction([], CURRENT)).toEqual({ kind: 'none' })
+  })
+
+  it('定义在当前文件：预览原地滚过去', () => {
+    const target = at(CURRENT, 12)
+    expect(definitionAction([target], CURRENT)).toEqual({ kind: 'here', target })
+  })
+
+  it('另一个文件、语言有代码阅读：用预览打开', () => {
+    const target = at('file:///ws/luffy_agent/core/db.py', 30)
+    expect(definitionAction([target], CURRENT)).toEqual({ kind: 'preview', target })
+  })
+
+  it('另一个文件、语言没有代码阅读：用普通文本编辑器打开', () => {
+    const target = at('file:///ws/native/ext.c', 7, false)
+    expect(definitionAction([target], CURRENT)).toEqual({ kind: 'text', target })
+  })
+
+  it('几处定义：让用户挑，挑好的一处再按上面的规则跳', () => {
+    const stub = at('file:///ws/typings/db.pyi', 3)
+    const source = at('file:///ws/luffy_agent/core/db.py', 30)
+    expect(definitionAction([stub, source], CURRENT)).toEqual({ kind: 'pick', targets: [stub, source] })
+    expect(definitionAction([source], CURRENT)).toEqual({ kind: 'preview', target: source })
+  })
+
+  it('同一处报了几遍算一处；同一行不同列算两处', () => {
+    const target = at('file:///ws/luffy_agent/core/db.py', 30)
+    expect(definitionAction([target, { ...target }], CURRENT)).toEqual({ kind: 'preview', target })
+    const other = at(target.uri, 30, true, 20)
+    expect(definitionAction([target, other], CURRENT)).toEqual({ kind: 'pick', targets: [target, other] })
+  })
+})

vscode/src/codeReader/editor/definitionAction.ts

@@ -0,0 +1,31 @@
+/** 一处定义。uri 是 Uri.toString()，用来和当前文件比、去重；supported：目标文件的语言有代码阅读。 */
+export interface DefinitionTarget {
+  uri: string
+  line: number
+  character: number
+  supported: boolean
+}
+
+/**
+ * ⌘ / Ctrl + 点击查到定义之后怎么做：
+ * none 不动；pick 让用户从几处里挑一处，挑好的那处再交给 definitionAction 决定；
+ * here 定义就在当前文件，预览原地滚过去；preview 用代码阅读预览打开目标文件；text 目标语言没有代码阅读，用普通文本编辑器打开。
+ */
+export type DefinitionAction<T extends DefinitionTarget>
+  = | { kind: 'none' }
+    | { kind: 'pick', targets: T[] }
+    | { kind: 'here' | 'preview' | 'text', target: T }
+
+/** 定义提供者查到的几处（可能重复）→ 怎么跳。current 是当前文件的 Uri.toString()。 */
+export function definitionAction<T extends DefinitionTarget>(targets: readonly T[], current: string): DefinitionAction<T> {
+  const unique = targets.filter((target, i) =>
+    targets.findIndex(other => other.uri === target.uri && other.line === target.line && other.character === target.character) === i)
+  if (unique.length === 0)
+    return { kind: 'none' }
+  if (unique.length > 1)
+    return { kind: 'pick', targets: unique }
+  const [target] = unique
+  if (target.uri === current)
+    return { kind: 'here', target }
+  return { kind: target.supported ? 'preview' : 'text', target }
+}

vscode/src/codeReader/editor/definitions.ts

@@ -0,0 +1,68 @@
+import type { Location, LocationLink, Position, Range, Uri } from 'vscode'
+import type { DefinitionTarget } from './definitionAction'
+import { commands, window, workspace } from 'vscode'
+import { logger } from '../../logging/logger'
+
+/** VS Code 查到的一处定义，加上打开目标文件才知道的信息。 */
+export interface Definition extends DefinitionTarget {
+  location: { uri: Uri, range: Range }
+  /** 定义处在目标文件里的下标，预览靠它找到是哪块、哪一行属性 */
+  offset: number
+  /** 定义所在那一行的源码，列在挑选框里 */
+  lineText: string
+}
+
+/** 交给 VS Code 注册的定义提供者（Pylance、TypeScript 语言服务……），和普通编辑器里 ⌘ + 点击查的是同一套。 */
+async function provided(uri: Uri, position: Position): Promise<(Location | LocationLink)[]> {
+  try {
+    return await commands.executeCommand<(Location | LocationLink)[] | undefined>('vscode.executeDefinitionProvider', uri, position) ?? []
+  }
+  catch (err) {
+    logger.add({ level: 'warn', source: 'codeReader', message: `查定义失败 ${uri.toString()}:${position.line + 1}：${err instanceof Error ? err.message : String(err)}` })
+    return []
+  }
+}
+
+export async function hasDefinition(uri: Uri, position: Position): Promise<boolean> {
+  return (await provided(uri, position)).length > 0
+}
+
+/** uri 里 position 处名字的所有定义；目标打不开成文本的（例如 Python 命名空间包指向的目录）略过。 */
+export async function findDefinitions(uri: Uri, position: Position, supports: (languageId: string) => boolean): Promise<Definition[]> {
+  const found = await Promise.all((await provided(uri, position)).map(async (item): Promise<Definition[]> => {
+    const location = 'targetUri' in item
+      ? { uri: item.targetUri, range: item.targetSelectionRange ?? item.targetRange }
+      : { uri: item.uri, range: item.range }
+    const { start } = location.range
+    try {
+      const document = await workspace.openTextDocument(location.uri)
+      return [{
+        uri: location.uri.toString(),
+        line: start.line,
+        character: start.character,
+        supported: supports(document.languageId),
+        location,
+        offset: document.offsetAt(start),
+        lineText: document.lineAt(start.line).text,
+      }]
+    }
+    catch (err) {
+      logger.add({ level: 'warn', source: 'codeReader', message: `定义所在的 ${location.uri.toString()} 打不开：${err instanceof Error ? err.message : String(err)}` })
+      return []
+    }
+  }))
+  return found.flat()
+}
+
+/** 几处定义里挑一处：每项是「相对路径:行号」，下面一行是那行源码。 */
+export async function pickDefinition<T extends Definition>(definitions: T[]): Promise<T | undefined> {
+  const picked = await window.showQuickPick(
+    definitions.map(definition => ({
+      label: `${workspace.asRelativePath(definition.location.uri)}:${definition.line + 1}`,
+      detail: definition.lineText.trim(),
+      definition,
+    })),
+    { placeHolder: '跳到哪一处定义', matchOnDetail: true },
+  )
+  return picked?.definition
+}

vscode/src/codeReader/editor/messages.ts

@@ -6,6 +6,15 @@ import type { BlockView } from '../blockView'
 
 export interface TranslatorOption { id: string, label: string }
 
+/**
+ * 让预览滚到包含 line 的块。definition 只在跳到定义时有：定义处那个名字在源码里的下标（Segment.offset），
+ * 预览展开把它折叠住的块和属性行，再让那块闪几下。
+ */
+export interface Reveal {
+  line: number
+  definition?: number
+}
+
 export interface DocumentMessage {
   type: 'document'
   /** TextDocument.version：webview 靠它判断是不是新一份文档 */
@@ -15,18 +24,29 @@ export interface DocumentMessage {
   translators: TranslatorOption[]
   translatorId: string
   error?: string
-  /** 从文本编辑器切过来时它顶部那一行：新预览只在第一份 document 里带，webview 滚到包含这行的块 */
-  revealLine?: number
+  /** 新预览只在第一份 document 里带：从文本编辑器切过来时是它顶部那一行，跳到定义时是定义处 */
+  reveal?: Reveal
 }
 
-export type ExtensionToWebview = DocumentMessage
+/**
+ * reveal：已经开着的预览滚到某处（同 DocumentMessage.reveal）
+ * definitionProbed：probeDefinition 的回答，found 表示 VS Code 查得到定义
+ */
+export type ExtensionToWebview
+  = | DocumentMessage
+    | ({ type: 'reveal' } & Reveal)
+    | { type: 'definitionProbed', version: number, offset: number, found: boolean }
 
 /**
  * edit：把 startLine..endLine 这几行整行替换成 text（扩展端给每行补回原来的缩进）
  * visibleLine：预览视口顶部那块的起始行，切回文本编辑器时把这行放到顶部
+ * probeDefinition：按住 ⌘ / Ctrl 悬停到带下标的名字上，问源码 offset 处有没有定义；version 是这份下标所属的文档版本
+ * goToDefinition：⌘ / Ctrl + 点击，跳到 offset 处名字的定义
  */
 export type WebviewToExtension
   = | { type: 'ready' }
     | { type: 'edit', startLine: number, endLine: number, text: string }
     | { type: 'selectTranslator', id: string }
     | { type: 'visibleLine', line: number }
+    | { type: 'probeDefinition', version: number, offset: number }
+    | { type: 'goToDefinition', version: number, offset: number }

vscode/src/codeReader/editor/previewEditor.ts

@@ -1,11 +1,14 @@
-import type { CustomTextEditorProvider, Disposable, TextDocument, Uri, WebviewPanel } from 'vscode'
+import type { CustomTextEditorProvider, Disposable, TextDocument, TextDocumentShowOptions, Uri, WebviewPanel } from 'vscode'
 import type { CodeReaderRegistry } from '../registry'
 import type { TreeSitterRuntime } from '../runtime'
-import type { ExtensionToWebview, WebviewToExtension } from './messages'
-import { Range, window, workspace, WorkspaceEdit } from 'vscode'
+import type { Definition } from './definitions'
+import type { ExtensionToWebview, Reveal, WebviewToExtension } from './messages'
+import { commands, Range, window, workspace, WorkspaceEdit } from 'vscode'
 import { logger } from '../../logging/logger'
 import { webviewHtml, webviewUiRoot } from '../../webview/html'
 import { blockReplacement } from '../editText'
+import { definitionAction } from './definitionAction'
+import { findDefinitions, hasDefinition, pickDefinition } from './definitions'
 import { documentMessage } from './documentMessage'
 
 export const PREVIEW_VIEW_TYPE = 'superpowers.codeReader.preview'
@@ -19,8 +22,8 @@ const REFRESH_DELAY_MS = 150
  */
 export class PreviewEditorProvider implements CustomTextEditorProvider {
   private readonly previews = new Set<Preview>()
-  /** 按文档 uri：从文本编辑器切过来时它顶部那一行，等着交给马上要打开的新预览 */
-  private readonly revealLines = new Map<string, number>()
+  /** 按文档 uri：等着交给马上要打开的新预览的位置（从文本编辑器切过来时它顶部那一行，或跳到的定义） */
+  private readonly reveals = new Map<string, Reveal>()
 
   constructor(
     private readonly extensionUri: Uri,
@@ -32,8 +35,8 @@ export class PreviewEditorProvider implements CustomTextEditorProvider {
     panel.webview.options = { enableScripts: true, localResourceRoots: [webviewUiRoot(this.extensionUri)] }
     panel.webview.html = webviewHtml(panel.webview, this.extensionUri, 'code-reader.html')
     const key = document.uri.toString()
-    const preview = new Preview(document, panel, this.registry, this.runtime, this.revealLines.get(key), languageId => this.refresh(languageId))
-    this.revealLines.delete(key)
+    const preview = new Preview(document, panel, this, this.registry, this.runtime, this.reveals.get(key))
+    this.reveals.delete(key)
     this.previews.add(preview)
     panel.onDidDispose(() => {
       this.previews.delete(preview)
@@ -49,17 +52,24 @@ export class PreviewEditorProvider implements CustomTextEditorProvider {
     }
   }
 
-  /** 用 open 打开 uri 的预览，新预览先滚到包含 line 的块。 */
-  async openAtLine(uri: Uri, line: number, open: () => Thenable<unknown>): Promise<void> {
+  /**
+   * 用 open 打开 uri 的预览并滚到 reveal：新建的预览随第一份文档带过去；
+   * open 只是切到了已经开着的预览（没有新建）时，直接发给这个预览，不重新打开。
+   */
+  async openAt(uri: Uri, reveal: Reveal, open: () => Thenable<unknown>): Promise<void> {
     const key = uri.toString()
-    this.revealLines.set(key, line)
+    this.reveals.set(key, reveal)
+    let claimed: boolean
     try {
       await open()
+      claimed = this.reveals.get(key) !== reveal
     }
     finally {
-      // 切换命令等新预览解析完才返回；切换没成时也不能把这行留给以后别处的打开
-      this.revealLines.delete(key)
+      // 打开命令等新预览解析完才返回；没打开成时也不能把这一处留给以后别处的打开
+      this.reveals.delete(key)
     }
+    if (!claimed)
+      [...this.previews].find(p => p.uri.toString() === key && p.active)?.reveal(reveal)
   }
 
   /** uri 的预览视口顶部那块的起始行；几个编辑器组里都开着这个文件的预览时取活动的那个。 */
@@ -71,7 +81,7 @@ export class PreviewEditorProvider implements CustomTextEditorProvider {
 }
 
 class Preview {
-  /** webview 发过 ready 之后才发文档，避免脚本还没起来时消息丢掉 */
+  /** webview 发过 ready 之后才发消息；标签页切走时页面被销毁，切回来重新加载、再发 ready，这期间也不发 */
   private ready = false
   /** 解析是异步的：只发最后一次请求的结果，慢的旧结果不能盖掉新的 */
   private latest = 0
@@ -83,14 +93,21 @@ class Preview {
   constructor(
     private readonly document: TextDocument,
     private readonly panel: WebviewPanel,
+    private readonly owner: PreviewEditorProvider,
     private readonly registry: CodeReaderRegistry,
     private readonly runtime: TreeSitterRuntime,
-    /** 只随第一份真正发出去的文档走：之后页面因标签页切走重新加载，要按 webview 自己记的位置恢复 */
-    private revealLine: number | undefined,
-    private readonly onTranslatorSelected: (languageId: string) => void,
+    /**
+     * 随下一份真正发出去的文档走、只走一次：新预览第一份文档要滚到的位置，或页面正在重新加载时收不到的 reveal。
+     * 之后页面因标签页切走重新加载，按 webview 自己记的位置恢复
+     */
+    private pendingReveal: Reveal | undefined,
   ) {
     this.disposables = [
       panel.webview.onDidReceiveMessage((msg: WebviewToExtension) => this.handleMessage(msg)),
+      panel.onDidChangeViewState(() => {
+        if (!panel.visible)
+          this.ready = false
+      }),
       workspace.onDidChangeTextDocument((e) => {
         if (e.document === document && e.contentChanges.length > 0)
           this.schedulePush()
@@ -116,11 +133,19 @@ class Preview {
       return
     const request = ++this.latest
     const message: ExtensionToWebview = await documentMessage(this.document, this.registry, this.runtime)
-    if (request !== this.latest)
+    if (request !== this.latest || !this.ready)
       return
-    const { revealLine } = this
-    this.revealLine = undefined
-    void this.panel.webview.postMessage(revealLine === undefined ? message : { ...message, revealLine })
+    const reveal = this.pendingReveal
+    this.pendingReveal = undefined
+    this.post(reveal === undefined ? message : { ...message, reveal })
+  }
+
+  /** 滚到 reveal：页面在就直接发，正在重新加载就等它发 ready 后随文档带过去。 */
+  reveal(reveal: Reveal): void {
+    if (this.ready)
+      this.post({ type: 'reveal', ...reveal })
+    else
+      this.pendingReveal = reveal
   }
 
   dispose(): void {
@@ -129,6 +154,10 @@ class Preview {
       disposable.dispose()
   }
 
+  private post(message: ExtensionToWebview): void {
+    void this.panel.webview.postMessage(message)
+  }
+
   private schedulePush(): void {
     clearTimeout(this.timer)
     this.timer = setTimeout(() => void this.push(), REFRESH_DELAY_MS)
@@ -145,13 +174,74 @@ class Preview {
         return
       case 'selectTranslator':
         await this.registry.selectTranslator(this.languageId, msg.id)
-        this.onTranslatorSelected(this.languageId)
+        this.owner.refresh(this.languageId)
         return
       case 'visibleLine':
         this.visibleLine = msg.line
+        return
+      case 'probeDefinition':
+        await this.probeDefinition(msg.version, msg.offset)
+        return
+      case 'goToDefinition':
+        await this.goToDefinition(msg.version, msg.offset)
     }
   }
 
+  /** 回答 webview：offset 处的名字有没有定义。下标属于别的文档版本时不答，webview 收到新文档后会重新问 */
+  private async probeDefinition(version: number, offset: number): Promise<void> {
+    const { document } = this
+    if (version !== document.version)
+      return
+    const found = await hasDefinition(document.uri, document.positionAt(offset))
+    if (version === document.version && this.ready)
+      this.post({ type: 'definitionProbed', version, offset, found })
+  }
+
+  /** ⌘ / Ctrl + 点击：跳到 offset 处名字的定义，几处时先让用户挑。 */
+  private async goToDefinition(version: number, offset: number): Promise<void> {
+    const { document } = this
+    if (version !== document.version)
+      return
+    const current = document.uri.toString()
+    const supports = (languageId: string): boolean => this.registry.languageFor(languageId) !== undefined
+    let action = definitionAction(await findDefinitions(document.uri, document.positionAt(offset), supports), current)
+    if (action.kind === 'pick') {
+      const picked = await pickDefinition(action.targets)
+      action = definitionAction(picked ? [picked] : [], current)
+    }
+    if (action.kind === 'none' || action.kind === 'pick')
+      return
+    const { target } = action
+    const reveal: Reveal = { line: target.line, definition: target.offset }
+    if (action.kind === 'here') {
+      this.reveal(reveal)
+      return
+    }
+    try {
+      await this.openDefinition(action.kind, target, reveal)
+    }
+    catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      logger.add({ level: 'warn', source: 'codeReader', message: `没能打开定义 ${target.uri}：${message}` })
+      void window.showErrorMessage(`代码阅读：没能打开定义所在的 ${workspace.asRelativePath(target.location.uri)}`)
+    }
+  }
+
+  /**
+   * 和普通编辑器里 ⌘ + 点击一样：在同一个编辑器组打开目标（是否按「预览标签」打开听 VS Code 的设置），
+   * 并按 workbench.editor.enablePreviewFromCodeNavigation 把当前这个预览标签固定住，免得被目标替掉。
+   */
+  private async openDefinition(kind: 'preview' | 'text', target: Definition, reveal: Reveal): Promise<void> {
+    if (this.panel.active && !workspace.getConfiguration('workbench.editor').get<boolean>('enablePreviewFromCodeNavigation', false))
+      await commands.executeCommand('workbench.action.keepEditor')
+    const options: TextDocumentShowOptions = { viewColumn: this.panel.viewColumn }
+    const { uri, range } = target.location
+    if (kind === 'text')
+      await window.showTextDocument(uri, { ...options, selection: range })
+    else
+      await this.owner.openAt(uri, reveal, () => commands.executeCommand('vscode.openWith', uri, PREVIEW_VIEW_TYPE, options))
+  }
+
   private async applyEdit(startLine: number, endLine: number, text: string): Promise<void> {
     const { document } = this
     const replacement = blockReplacement(line => document.lineAt(line).text, document.lineCount, startLine, endLine, text)

vscode/src/codeReader/editor/switchEditor.ts

@@ -57,7 +57,7 @@ export async function showPreview(previews: PreviewEditorProvider, args: unknown
   const topLine = uri ? textEditorOf(uri)?.visibleRanges[0]?.start.line : undefined
   const reopen = (): Thenable<unknown> => commands.executeCommand(REOPEN_WITH, PREVIEW_VIEW_TYPE, ...args)
   if (uri && topLine !== undefined)
-    await previews.openAtLine(uri, topLine, reopen)
+    await previews.openAt(uri, { line: topLine }, reopen)
   else
     await reopen()
 }

vscode/src/codeReader/translators/zhTemplate.test.ts

@@ -55,6 +55,11 @@ function texts(map: Map<number, Translated>): Record<number, string> {
   return Object.fromEntries([...map].map(([line, { segments }]) => [line, text(segments)]))
 }
 
+/** 只看文字和着色：去掉各段的源码下标（下标另有用例）。 */
+function colors<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value, (key, field: unknown) => key === 'offset' ? undefined : field)) as T
+}
+
 const CJK = /\p{Script=Han}/u
 const CJK_ONLY = /^\p{Script=Han}+$/u
 const WORD_CHAR = /[\p{Script=Han}\w]/u
@@ -105,7 +110,7 @@ describe('typeScript 中文直译', () => {
   it('每个被翻的词单独成段，着色取语法树词性', async () => {
     const env = await translateAll(ts, 'typescript', typescriptZhTranslator, readFixture('envLock.ts.txt'))
     const issue = await translateAll(ts, 'typescript', typescriptZhTranslator, readFixture('issueLock.ts.txt'))
-    expect(env.get(32)?.segments.filter(segment => segment.role !== 'plain')).toEqual([
+    expect(colors(env.get(32)?.segments.filter(segment => segment.role !== 'plain'))).toEqual([
       { text: '公共', role: 'keyword' },
       { text: '接口', role: 'storage' },
       { text: 'EnvLockResult', role: 'type' },
@@ -375,7 +380,7 @@ describe('属性表', () => {
 
   it('属性名是纯文字；值按词性着色，说明词（未标注、N 个、默认）用 hint', async () => {
     const env = await describeAll(ts, 'typescript', typescriptZhTranslator, readFixture('envLock.ts.txt'))
-    const rows = env.get(23) ?? []
+    const rows = colors(env.get(23) ?? [])
     expect(rows.map(row => row.label)).toEqual(['名称', '访问级别', '异步', '输入参数', '输出参数'])
     expect(rows[0].value).toEqual([{ text: 'findEnvFiles', role: 'function' }])
     expect(rows[1].value).toEqual([{ text: '公共', role: 'keyword' }])
@@ -388,8 +393,8 @@ describe('属性表', () => {
       { text: '字符串', role: 'type' },
       { text: '[]>', role: 'plain' },
     ])
-    expect(valueOf(env.get(12), '来源')).toEqual([{ text: '\'node:fs\'', role: 'string' }])
-    expect(env.get(12)?.at(-1)?.items?.[0].cells[0]).toEqual([
+    expect(colors(valueOf(env.get(12), '来源'))).toEqual([{ text: '\'node:fs\'', role: 'string' }])
+    expect(colors(env.get(12)?.at(-1)?.items?.[0].cells[0])).toEqual([
       { text: 'promises', role: 'variable' },
       { text: ' ', role: 'plain' },
       { text: '作为', role: 'keyword' },
@@ -398,8 +403,8 @@ describe('属性表', () => {
     ])
 
     const sample = await describeAll(py, 'python', pythonZhTranslator, readFixture('sample.py'))
-    expect(valueOf(sample.get(3), '来源')).toEqual([{ text: 'os', role: 'type' }])
-    expect(sample.get(39)?.find(row => row.label === '输入参数')?.items).toEqual([
+    expect(colors(valueOf(sample.get(3), '来源'))).toEqual([{ text: 'os', role: 'type' }])
+    expect(colors(sample.get(39)?.find(row => row.label === '输入参数')?.items)).toEqual([
       { cells: [[{ text: 'self', role: 'variable' }], [{ text: '未标注', role: 'hint' }], []] },
       { cells: [[{ text: 'verbose', role: 'variable' }], [{ text: '布尔', role: 'type' }], [{ text: '默认 ', role: 'hint' }, { text: '假', role: 'storage' }]] },
     ])
@@ -464,6 +469,107 @@ describe('属性表', () => {
   })
 })
 
+describe('源码下标（跳到定义用）', () => {
+  /** 带下标的段，按出现顺序写成 [文字, 下标]。 */
+  function linked(segments: Segment[] | undefined): [string, number][] {
+    return (segments ?? []).flatMap(segment => segment.offset === undefined ? [] : [[segment.text, segment.offset] as [string, number]])
+  }
+
+  function itemCells(rows: PropertyRow[] | undefined, label: string): Segment[][] {
+    return rows?.find(row => row.label === label)?.items?.flatMap(item => item.cells) ?? []
+  }
+
+  function propertySegments(rows: PropertyRow[]): Segment[] {
+    return rows.flatMap(row => [...row.value, ...(row.items ?? []).flatMap(item => item.cells.flat())])
+  }
+
+  it('python：点分模块名每一节、导入项、别名各自带下标，点号不带；前面有中文注释也对得上', async () => {
+    const source = [
+      '# 数据库连接',
+      'from luffy_agent.core.db import get_db as conn',
+      'import os.path',
+      'from . import x',
+    ].join('\n')
+    const at = (word: string): number => source.indexOf(word)
+    const rows = await describeAll(py, 'python', pythonZhTranslator, source)
+    expect(text(valueOf(rows.get(2), '来源'))).toBe('luffy_agent.core.db')
+    expect(linked(valueOf(rows.get(2), '来源'))).toEqual([['luffy_agent', at('luffy_agent')], ['core', at('core')], ['db', at('db')]])
+    expect(itemCells(rows.get(2), '导入项').map(linked)).toEqual([[['get_db', at('get_db')], ['conn', at('conn')]]])
+    expect(linked(valueOf(rows.get(3), '来源'))).toEqual([['os', at('os')], ['path', at('path')]])
+    expect(linked(valueOf(rows.get(4), '来源'))).toEqual([])
+    expect(itemCells(rows.get(4), '导入项').map(linked)).toEqual([[['x', at('x')]]])
+  })
+
+  it('python：一行译文里的名字带下标，关键字、运算符、字面量译词不带', async () => {
+    const source = [
+      'def f(user):',
+      '    if not user.active and user is not None:',
+      '        raise HTTPException(status_code=404)',
+    ].join('\n')
+    const at = (word: string, from = 0): number => source.indexOf(word, from)
+    const map = await translateAll(py, 'python', pythonZhTranslator, source)
+    const ifLine = at('if')
+    expect(text(map.get(2)?.segments)).toBe('如果 非 user.active 并且 user 不是 空')
+    expect(linked(map.get(2)?.segments)).toEqual([['user', at('user', ifLine)], ['active', at('active')], ['user', at('user is')]])
+    expect(linked(map.get(3)?.segments)).toEqual([['HTTPException', at('HTTPException')], ['status_code', at('status_code')]])
+  })
+
+  it('typeScript：模块字符串、导入项、函数名称、参数名和类型、返回类型、译文里的名字带下标', async () => {
+    const source = [
+      '// 读取配置',
+      'import { readFile as rf } from \'./fs\'',
+      'export async function load(path: string, opts?: Options): Promise<Result> {',
+      '  if (opts === undefined) return rf(path)',
+      '}',
+    ].join('\n')
+    const at = (word: string): number => source.indexOf(word)
+    const rows = await describeAll(ts, 'typescript', typescriptZhTranslator, source)
+    expect(linked(valueOf(rows.get(2), '来源'))).toEqual([['\'./fs\'', at('\'./fs\'')]])
+    expect(itemCells(rows.get(2), '导入项').map(linked)).toEqual([[['readFile', at('readFile')], ['rf', at('rf }')]]])
+    expect(linked(valueOf(rows.get(3), '名称'))).toEqual([['load', at('load')]])
+    expect(itemCells(rows.get(3), '输入参数').map(linked)).toEqual([
+      [['path', at('path:')]],
+      [],
+      [],
+      [['opts', at('opts?')]],
+      [['Options', at('Options')]],
+      [],
+    ])
+    expect(linked(valueOf(rows.get(3), '输出参数'))).toEqual([['Promise', at('Promise')], ['Result', at('Result')]])
+    const map = await translateAll(ts, 'typescript', typescriptZhTranslator, source)
+    expect(text(map.get(4)?.segments)).toBe('如果 (opts 全等 未定义)')
+    expect(linked(map.get(4)?.segments)).toEqual([['opts', at('opts ===')]])
+  })
+
+  it('样例全文：带下标的只有照抄的名字和字符串，下标处的源码就是这段；变量名、函数名都带，译词、说明词都不带', async () => {
+    const samples: [LanguageAdapter, string, Translator, string][] = [
+      [ts, 'typescript', typescriptZhTranslator, 'envLock.ts.txt'],
+      [ts, 'typescript', typescriptZhTranslator, 'issueLock.ts.txt'],
+      [py, 'python', pythonZhTranslator, 'sample.py'],
+      [py, 'python', pythonZhTranslator, 'routes.py'],
+    ]
+    for (const [adapter, languageId, translator, name] of samples) {
+      const source = readFixture(name)
+      const translated = [...(await translateAll(adapter, languageId, translator, source)).values()].flatMap(block => block.segments)
+      const described = [...(await describeAll(adapter, languageId, translator, source)).values()].flatMap(propertySegments)
+      const segments = [...translated, ...described]
+      expect(linked(segments).length, name).toBeGreaterThan(10)
+      for (const segment of segments) {
+        const where = `${name} 「${segment.text}」`
+        if (segment.role === 'variable' || segment.role === 'function')
+          expect(segment.offset, where).toBeTypeOf('number')
+        if (segment.offset === undefined)
+          continue
+        expect(['variable', 'function', 'type', 'string'], where).toContain(segment.role)
+        if (segment.role === 'string')
+          expect(source[segment.offset], where).toBe(segment.text[0])
+        else
+          expect(source.startsWith(segment.text, segment.offset), where).toBe(true)
+      }
+    }
+  })
+})
+
 describe('中文模板引擎', () => {
   function testTranslator(table: Partial<ZhTable>): Translator {
     return createZhTemplateTranslator({

vscode/src/codeReader/translators/zhTemplate.ts

@@ -56,6 +56,8 @@ interface Token {
   raw: string
   /** 前面要空一格：源码里它前面有空白，或者模板在它前面插了别的项。 */
   gap: boolean
+  /** 照抄的名字、字符串在源码里的起始下标，见 Segment.offset。 */
+  offset?: number
 }
 
 /** 按译文顺序收集词：cursor 是上一个词在源码里的结尾，gap 是下一个词前面要不要空一格。 */
@@ -69,6 +71,8 @@ interface Collector {
 const CONTEXT_SEPARATOR = ' > '
 const CLOSING = new Set([')', ']', '}'])
 const HEADER_OPENERS = new Set(['{', ':'])
+/** 源码着色里代表名字的词性：着这几种色的具名叶子是标识符、属性名、类型名，能查定义。 */
+const NAME_ROLES = new Set<TokenRole>(['variable', 'function', 'type'])
 
 function firstLeaf(node: Node): Node {
   const first = node.child(0)
@@ -123,6 +127,12 @@ export function createZhTemplateTranslator(table: ZhTable): Translator {
     return text
   }
 
+  /** 照抄这个节点时带不带源码下标：名字（按名字着色的具名叶子）和整段字符串带，标点、数字、关键字不带。 */
+  function offsetOf(node: Node): number | undefined {
+    const linkable = stringNodes.has(node.type) || (node.childCount === 0 && node.isNamed && NAME_ROLES.has(table.tokenRole(node)))
+    return linkable ? node.startIndex : undefined
+  }
+
   /** 能整个换成中文的节点 → 译文和词性。 */
   function translateNode(node: Node): { text: string, role: TokenRole } | undefined {
     if (node.childCount === 0 && table.isTypePosition(node)) {
@@ -201,7 +211,7 @@ export function createZhTemplateTranslator(table: ZhTable): Translator {
     }
     if (node.childCount === 0 || stringNodes.has(node.type)) {
       const role = stringNodes.has(node.type) ? 'string' : table.tokenRole(node)
-      emitSource(out, node, { text: oneLine(node.text), role, translated: false })
+      emitSource(out, node, { text: oneLine(node.text), role, translated: false, offset: offsetOf(node) })
       return
     }
     for (const child of node.children) {
@@ -217,8 +227,8 @@ export function createZhTemplateTranslator(table: ZhTable): Translator {
     return out.tokens
   }
 
-  /** node 的源码原样照抄：叶子按源码着色，叶子之间的空白、标点照抄。 */
-  function verbatim(node: Node, source: string): Segment[] {
+  /** node 的源码原样照抄：叶子按源码着色（给了 role 就都按它），叶子之间的空白、标点照抄。 */
+  function verbatim(node: Node, source: string, role?: TokenRole): Segment[] {
     const segments: Segment[] = []
     let cursor = node.startIndex
     const visit = (current: Node): void => {
@@ -232,7 +242,7 @@ export function createZhTemplateTranslator(table: ZhTable): Translator {
         return
       }
       pushSegment(segments, source.slice(cursor, current.startIndex), 'plain')
-      pushSegment(segments, current.text, table.tokenRole(current))
+      pushSegment(segments, current.text, role ?? table.tokenRole(current), offsetOf(current))
       cursor = current.endIndex
     }
     visit(node)
@@ -274,7 +284,9 @@ export function createZhTemplateTranslator(table: ZhTable): Translator {
         return joinTokens(tokensIn(node, span, source))
       },
       verbatim: node => verbatim(node, source),
-      module: node => [{ text: node.text, role: stringNodes.has(node.type) ? 'string' : 'type' }],
+      // 点分模块名逐节照抄，每一节各自能跳到定义，和 VS Code 里一样
+      module: node => stringNodes.has(node.type) ? [segment(node.text, 'string', offsetOf(node))] : verbatim(node, source, 'type'),
+      name: (node, role) => [segment(node.text, role, offsetOf(node))],
     }
     switch (block.kind) {
       case 'function':
@@ -289,14 +301,18 @@ export function createZhTemplateTranslator(table: ZhTable): Translator {
   return { id: table.id, label: table.label, languageIds: table.languageIds, translate, describe }
 }
 
-function pushSegment(segments: Segment[], text: string, role: TokenRole): void {
+function segment(text: string, role: TokenRole, offset: number | undefined): Segment {
+  return offset === undefined ? { text, role } : { text, role, offset }
+}
+
+function pushSegment(segments: Segment[], text: string, role: TokenRole, offset?: number): void {
   if (!text)
     return
   const prev = segments.at(-1)
   if (role === 'plain' && prev?.role === 'plain')
     prev.text += text
   else
-    segments.push({ text, role })
+    segments.push(segment(text, role, offset))
 }
 
 /** 词连成译文：源码里隔着空白的词之间空一格，注释不进译文，右括号前的尾逗号去掉。 */
@@ -312,7 +328,7 @@ function joinTokens(tokens: Token[]): Segment[] {
     }
     if (gap && segments.length > 0)
       pushSegment(segments, ' ', 'plain')
-    pushSegment(segments, token.text, token.role)
+    pushSegment(segments, token.text, token.role, token.offset)
     // 「非」是个词，后面补一个空格，不和操作数粘在一起
     gap = token.translated && token.raw === '!'
   })
@@ -329,6 +345,8 @@ interface Phrases {
   verbatim: (node: Node) => Segment[]
   /** 导入来源：字符串字面量按字符串着色，模块名按类型着色。 */
   module: (node: Node) => Segment[]
+  /** 源码里的一个名字原样照抄、按 role 着色（函数名称）。 */
+  name: (node: Node, role: TokenRole) => Segment[]
 }
 
 const ACCESS_ZH: Record<Access, string> = { public: '公共', private: '私有', protected: '受保护' }
@@ -363,7 +381,7 @@ function aliased(item: Segment[], alias: Node | undefined, say: Phrases): Segmen
 function functionRows(facts: FunctionFacts, say: Phrases): PropertyRow[] {
   const decorators = facts.decorators.map(say.verbatim)
   return [
-    { label: '名称', value: facts.name ? [{ text: facts.name.text, role: 'function' }] : [hint('匿名')] },
+    { label: '名称', value: facts.name ? say.name(facts.name, 'function') : [hint('匿名')] },
     ...accessRows(facts.access),
     { label: '异步', value: yesNo(facts.async) },
     ...(decorators.length > 0 ? [{ label: '装饰器', value: joined(decorators, '\n') }] : []),

vscode/webview-ui/src/codeReader/App.tsx

@@ -1,11 +1,13 @@
 import type { ReactElement } from 'react'
 import type { BlockTreeState } from './BlockTree'
-import type { DocumentMessage } from './types'
+import type { DocumentMessage, Reveal } from './types'
 import type { ViewState } from './viewState'
 import { TriangleAlert } from 'lucide-react'
 import { useCallback, useEffect, useMemo, useState } from 'react'
 import { SelectMenu } from '@/components/ui/select-menu'
 import { BlockLevel } from './BlockTree'
+import { useDefinitionLinks } from './useDefinitionLinks'
+import { useReveal } from './useReveal'
 import { useScrollPosition } from './useScrollPosition'
 import { onMessage, postMessage, viewState } from './vscode'
 
@@ -24,12 +26,25 @@ export function App(): ReactElement | null {
   const [doc, setDoc] = useState<DocumentMessage | null>(null)
   const [view, setView] = useState<BlockModes>(savedBlockModes)
   const [focusId, setFocusId] = useState<string | null>(null)
+  /** 等着滚过去的位置：新预览第一份文档带的，或已开着的预览收到的 reveal */
+  const [reveal, setReveal] = useState<Reveal | null>(null)
+  const expand = useCallback((ids: string[]) => setView(prev => ({ ...prev, collapsed: prev.collapsed.filter(id => !ids.includes(id)) })), [])
+  const revealed = useCallback(() => setReveal(null), [])
   useScrollPosition(doc)
+  useReveal(doc, reveal, view.collapsed, expand, revealed)
+  useDefinitionLinks(doc?.version)
 
   useEffect(() => {
     const off = onMessage((msg) => {
-      if (msg.type === 'document')
-        setDoc(msg)
+      switch (msg.type) {
+        case 'document':
+          setDoc(msg)
+          if (msg.reveal)
+            setReveal(msg.reveal)
+          return
+        case 'reveal':
+          setReveal({ line: msg.line, definition: msg.definition })
+      }
     })
     postMessage({ type: 'ready' })
     return off

vscode/webview-ui/src/codeReader/BlockTree.tsx

@@ -83,6 +83,7 @@ function BlockCard({ block, tree }: { block: BlockView, tree: BlockTreeState }):
     <div
       className="cr-block flex items-start gap-2.5 rounded-lg py-2 pr-2.5 pl-2"
       data-kind={block.kind}
+      data-id={block.id}
       data-line={block.startLine}
       data-editing={editing ? '' : undefined}
     >

vscode/webview-ui/src/codeReader/SegmentText.tsx

@@ -1,12 +1,12 @@
 import type { ReactElement } from 'react'
 import type { Segment } from './types'
 
-/** 按词性给每一段上色，颜色在 codeReader.css 的 .cr-role-* 里按主题切换。 */
+/** 按词性给每一段上色，颜色在 codeReader.css 的 .cr-role-* 里按主题切换；带源码下标的名字记在 data-offset 上，跳到定义用。 */
 export function SegmentText({ segments }: { segments: Segment[] }): ReactElement {
   return (
     <>
       {segments.map((segment, index) => (
-        <span key={index} className={`cr-role-${segment.role}`}>{segment.text}</span>
+        <span key={index} className={`cr-role-${segment.role}`} data-offset={segment.offset}>{segment.text}</span>
       ))}
     </>
   )

vscode/webview-ui/src/codeReader/codeReader.css

@@ -94,11 +94,31 @@ body.vscode-high-contrast-light {
   background: var(--kind);
 }
 
+/* 跳到定义的目标块：边框和底色往聚焦色闪三下（共 1.5 秒）再复原；减少动态效果时改成静止高亮同样长的时间 */
+@keyframes cr-flash {
+  50% {
+    background: color-mix(in srgb, var(--vscode-focusBorder) 25%, transparent);
+    border-color: var(--vscode-focusBorder);
+  }
+}
+@keyframes cr-flash-still {
+  from, to {
+    background: color-mix(in srgb, var(--vscode-focusBorder) 25%, transparent);
+    border-color: var(--vscode-focusBorder);
+  }
+}
+.cr-block[data-flash] {
+  animation: cr-flash 500ms ease-in-out 3;
+}
+
 @media (prefers-reduced-motion: reduce) {
   .cr-block,
   .cr-guide {
     transition: none;
   }
+  .cr-block[data-flash] {
+    animation: cr-flash-still 1500ms;
+  }
 }
 
 .cr-badge {
@@ -134,6 +154,13 @@ body.vscode-high-contrast-light {
 .cr-role-comment { color: var(--cr-comment); }
 .cr-role-hint { color: var(--vscode-descriptionForeground); }
 
+/* 按住 ⌘ / Ctrl 停在查得到定义的名字上：和编辑器里的链接一样 */
+.cr-code [data-link] {
+  color: var(--vscode-editorLink-activeForeground);
+  text-decoration: underline;
+  cursor: pointer;
+}
+
 /* 属性表的属性名：界面字体，和值一样的行高，两边逐行对齐 */
 .cr-prop-label {
   font-size: 12.5px;

vscode/webview-ui/src/codeReader/reveal.test.ts

@@ -0,0 +1,88 @@
+import type { BlockKind, BlockView, PropertyRow, Segment } from './types'
+import { describe, expect, it } from 'vitest'
+import { revealPlan, scrollTopToShow } from './reveal'
+
+function name(text: string, offset: number): Segment {
+  return { text, role: 'variable', offset }
+}
+
+function word(text: string): Segment {
+  return { text, role: 'keyword' }
+}
+
+function textBlock(id: string, kind: BlockKind, startLine: number, translation: Segment[], children: BlockView[] = []): BlockView {
+  return { id, kind, startLine, endLine: startLine, code: '', codeTokens: [], children, translation }
+}
+
+function factBlock(id: string, kind: BlockKind, startLine: number, properties: PropertyRow[], children: BlockView[] = []): BlockView {
+  return { id, kind, startLine, endLine: startLine, code: '', codeTokens: [], children, properties }
+}
+
+/**
+ * 0  from luffy_agent.core.db import get_db
+ * 2  def load(path, user):
+ * 3      if not user:
+ * 4          return get_db(path)
+ * 8  LIMIT = 3
+ */
+const BLOCKS: BlockView[] = [
+  factBlock('0', 'import', 0, [
+    { label: '来源', value: [name('luffy_agent', 5), { text: '.', role: 'type' }, name('core', 17)] },
+    { label: '导入项', value: [{ text: '1 个', role: 'hint' }], items: [{ cells: [[name('get_db', 34)]] }] },
+  ]),
+  factBlock('1', 'function', 2, [
+    { label: '名称', value: [{ text: 'load', role: 'function', offset: 46 }] },
+    { label: '异步', value: [{ text: '否', role: 'storage' }] },
+    { label: '输入参数', value: [{ text: '2 个', role: 'hint' }], items: [{ cells: [[name('path', 51)], []] }, { cells: [[name('user', 57)], []] }] },
+  ], [
+    textBlock('1.0', 'if', 3, [word('如果'), word('非'), name('user', 78)], [
+      textBlock('1.0.0', 'return', 4, [word('返回'), name('get_db', 102), name('path', 109)]),
+    ]),
+  ]),
+  factBlock('2', 'const', 8, [{ label: '名称', value: [name('LIMIT', 130)] }]),
+]
+
+describe('跳到定义：滚到哪块、展开哪些', () => {
+  it('名字在嵌套块的译文里：目标是那块，展开它所有的祖先块', () => {
+    expect(revealPlan(BLOCKS, 4, 102)).toEqual({ id: '1.0.0', expand: ['1', '1.0'] })
+  })
+
+  it('名字在属性行展开的子行里（参数）：连那一行一起展开', () => {
+    expect(revealPlan(BLOCKS, 2, 57)).toEqual({ id: '1', expand: ['1/p2'] })
+    expect(revealPlan(BLOCKS, 0, 34)).toEqual({ id: '0', expand: ['0/p1'] })
+  })
+
+  it('名字在属性行的值里：不用展开属性行', () => {
+    expect(revealPlan(BLOCKS, 2, 46)).toEqual({ id: '1', expand: [] })
+    expect(revealPlan(BLOCKS, 8, 130)).toEqual({ id: '2', expand: [] })
+  })
+
+  it('页面上没有这个名字：按行找包含它的块，也展开祖先', () => {
+    expect(revealPlan(BLOCKS, 3, 999)).toEqual({ id: '1.0', expand: ['1'] })
+    expect(revealPlan(BLOCKS, 6, 999)).toEqual({ id: '1.0.0', expand: ['1', '1.0'] })
+    expect(revealPlan(BLOCKS, 20, 999)).toEqual({ id: '2', expand: [] })
+  })
+
+  it('按行找：同一行有几块取外层那块；行在所有块之前取第一块；没有块时没有目标', () => {
+    const sameLine = [textBlock('0', 'if', 1, [word('如果')], [textBlock('0.0', 'return', 1, [word('返回')])])]
+    expect(revealPlan(sameLine, 1, 999)).toEqual({ id: '0', expand: [] })
+    expect(revealPlan(sameLine, 0, 999)).toEqual({ id: '0', expand: [] })
+    expect(revealPlan([], 0, 0)).toBeUndefined()
+  })
+})
+
+describe('把目标块滚进视口', () => {
+  it('整块已经在视口里：不滚', () => {
+    expect(scrollTopToShow({ top: 120, bottom: 160 }, 100, 500)).toBeUndefined()
+  })
+
+  it('在视口外：放到视口正中', () => {
+    expect(scrollTopToShow({ top: 1000, bottom: 1040 }, 0, 500)).toBe(770)
+    expect(scrollTopToShow({ top: 80, bottom: 120 }, 400, 500)).toBe(0)
+  })
+
+  it('露了一半也算在视口外；比视口还高就顶部对齐', () => {
+    expect(scrollTopToShow({ top: 580, bottom: 620 }, 100, 500)).toBe(350)
+    expect(scrollTopToShow({ top: 900, bottom: 1600 }, 0, 500)).toBe(900)
+  })
+})

vscode/webview-ui/src/codeReader/reveal.ts

@@ -0,0 +1,65 @@
+import type { BlockView, Segment } from './types'
+import { propertyRowId } from './viewState'
+
+/** 跳到定义时要滚到的块，以及要展开的块和属性行：它们折叠着，目标就不在页面上。 */
+export interface RevealPlan {
+  id: string
+  expand: string[]
+}
+
+interface Placed {
+  block: BlockView
+  /** 从顶层到父块的块 id */
+  ancestors: string[]
+}
+
+/** 按页面上的先后（先父块、再子块）列出所有块。 */
+function* placed(blocks: BlockView[], ancestors: string[] = []): Generator<Placed> {
+  for (const block of blocks) {
+    yield { block, ancestors }
+    yield* placed(block.children, [...ancestors, block.id])
+  }
+}
+
+function shows(segments: Segment[], offset: number): boolean {
+  return segments.some(segment => segment.offset === offset)
+}
+
+/** 块里哪儿显示着 offset 处的名字：'value' 是一行译文或属性行的值，数字是带子行的属性行序号（名字在它展开的子行里），不在这块里是 undefined。 */
+function locate(block: BlockView, offset: number): 'value' | number | undefined {
+  if ('translation' in block)
+    return shows(block.translation, offset) ? 'value' : undefined
+  for (const [index, row] of block.properties.entries()) {
+    if (shows(row.value, offset))
+      return 'value'
+    if (row.items?.some(item => item.cells.some(cell => shows(cell, offset))))
+      return index
+  }
+  return undefined
+}
+
+/**
+ * 跳到定义：目标是显示着定义处那个名字的块，名字在属性行的子行里时连这一行一起展开；
+ * 页面上找不到这个名字（例如定义是整个模块，落在文件开头）就取包含 line 的块，规则同 blockForLine。
+ * 目标的祖先块都要展开。
+ */
+export function revealPlan(blocks: BlockView[], line: number, definition: number): RevealPlan | undefined {
+  let byLine: Placed | undefined
+  for (const item of placed(blocks)) {
+    const where = locate(item.block, definition)
+    if (where !== undefined)
+      return { id: item.block.id, expand: typeof where === 'number' ? [...item.ancestors, propertyRowId(item.block.id, where)] : item.ancestors }
+    if (item.block.startLine <= line && (!byLine || item.block.startLine > byLine.block.startLine))
+      byLine = item
+  }
+  const target = byLine ?? (blocks.length > 0 ? { block: blocks[0], ancestors: [] } : undefined)
+  return target && { id: target.block.id, expand: target.ancestors }
+}
+
+/** 让一块露出来要滚到的 scrollTop，和 VS Code 跳到定义一样：整块已经在视口里就不滚；否则放到视口正中，比视口还高就顶部对齐。 */
+export function scrollTopToShow(box: { top: number, bottom: number }, viewTop: number, viewHeight: number): number | undefined {
+  if (box.top >= viewTop && box.bottom <= viewTop + viewHeight)
+    return undefined
+  const height = box.bottom - box.top
+  return Math.max(0, height >= viewHeight ? box.top : box.top - (viewHeight - height) / 2)
+}

vscode/webview-ui/src/codeReader/types.ts

@@ -14,7 +14,8 @@ export type TokenRole
     | 'hint' // 属性表里的说明词：未标注 无 N 个 默认导出 …
     | 'variable' | 'function' | 'type' | 'string' | 'number' | 'literal' | 'comment' | 'plain'
 
-export interface Segment { text: string, role: TokenRole }
+/** offset：照抄自源码里的名字、字符串时它在源码里的起始下标，⌘ / Ctrl 悬停、点击时拿它查定义；译词、提示词没有 */
+export interface Segment { text: string, role: TokenRole, offset?: number }
 
 /** 属性表里展开的一个子行：几列对齐的格子，例如参数的名称 / 类型 / 默认值 */
 export interface PropertyItem { cells: Segment[][] }
@@ -45,6 +46,15 @@ export type BlockView = BlockViewBase & ({ translation: Segment[] } | { properti
 
 export interface TranslatorOption { id: string, label: string }
 
+/**
+ * 滚到包含 line 的块。definition 只在跳到定义时有：定义处那个名字在源码里的下标（Segment.offset），
+ * 要展开把它折叠住的块和属性行，再让那块闪几下
+ */
+export interface Reveal {
+  line: number
+  definition?: number
+}
+
 export interface DocumentMessage {
   type: 'document'
   version: number
@@ -53,18 +63,29 @@ export interface DocumentMessage {
   translators: TranslatorOption[]
   translatorId: string
   error?: string
-  /** 从文本编辑器切过来时它顶部那一行：只在新预览的第一份 document 里带，滚到包含这行的块 */
-  revealLine?: number
+  /** 只在新预览的第一份 document 里带：从文本编辑器切过来时是它顶部那一行，跳到定义时是定义处 */
+  reveal?: Reveal
 }
 
-export type ExtensionToWebview = DocumentMessage
+/**
+ * reveal：已经开着的预览滚到某处（同 DocumentMessage.reveal）
+ * definitionProbed：probeDefinition 的回答，found 表示查得到定义
+ */
+export type ExtensionToWebview
+  = | DocumentMessage
+    | ({ type: 'reveal' } & Reveal)
+    | { type: 'definitionProbed', version: number, offset: number, found: boolean }
 
 /**
  * edit：把 startLine..endLine 这几行整行替换成 text（扩展端给每行补回原来第一行的缩进）
  * visibleLine：视口顶部那块的起始行，切回文本编辑器时扩展端把这行放到顶部
+ * probeDefinition：按住 ⌘ / Ctrl 悬停到带下标的名字上，问 offset 处有没有定义；version 是这份下标所属的文档版本
+ * goToDefinition：⌘ / Ctrl + 点击，跳到 offset 处名字的定义
  */
 export type WebviewToExtension
   = | { type: 'ready' }
     | { type: 'edit', startLine: number, endLine: number, text: string }
     | { type: 'selectTranslator', id: string }
     | { type: 'visibleLine', line: number }
+    | { type: 'probeDefinition', version: number, offset: number }
+    | { type: 'goToDefinition', version: number, offset: number }

vscode/webview-ui/src/codeReader/useDefinitionLinks.ts

@@ -0,0 +1,124 @@
+import type { WebviewToExtension } from './types'
+import { useEffect, useState } from 'react'
+import { onMessage, postMessage } from './vscode'
+
+/** 跳到定义用的修饰键，按平台习惯：macOS 是 ⌘，其余是 Ctrl。 */
+const IS_MAC = /Mac|iPhone|iPad/.test(navigator.userAgent)
+
+function modifierHeld(event: MouseEvent | KeyboardEvent): boolean {
+  return IS_MAC ? event.metaKey : event.ctrlKey
+}
+
+/** 事件落在的那个带源码下标的名字（SegmentText 渲染的 data-offset）。 */
+function nameAt(target: EventTarget | null): HTMLElement | null {
+  return target instanceof Element ? target.closest<HTMLElement>('[data-offset]') : null
+}
+
+function offsetOf(el: HTMLElement | null): number | undefined {
+  return el?.dataset.offset === undefined ? undefined : Number(el.dataset.offset)
+}
+
+/**
+ * 和 VS Code 编辑器里一样：按住 ⌘ / Ctrl、鼠标停在查得到定义的名字上时，名字显示成链接（data-link），点一下跳到定义。
+ * 有没有定义问扩展端，回答按文档版本缓存：同一版本里每个名字只问一次，换了版本清空，迟到的旧版本回答丢掉。
+ */
+class DefinitionLinks {
+  private version: number | undefined
+  /** 这个版本里问过的下标：true / false 是回答，undefined 是问了还没回 */
+  private readonly answers = new Map<number, boolean | undefined>()
+  private hovered: HTMLElement | null = null
+  private held = false
+  private linked: HTMLElement | null = null
+
+  constructor(private readonly post: (msg: WebviewToExtension) => void) {}
+
+  setVersion(version: number | undefined): void {
+    if (version === this.version)
+      return
+    this.version = version
+    this.answers.clear()
+    this.update()
+  }
+
+  point(target: EventTarget | null, held: boolean): void {
+    this.hovered = nameAt(target)
+    this.held = held
+    this.update()
+  }
+
+  hold(held: boolean): void {
+    this.held = held
+    this.update()
+  }
+
+  answer(version: number, offset: number, found: boolean): void {
+    if (version !== this.version)
+      return
+    this.answers.set(offset, found)
+    this.update()
+  }
+
+  /** ⌘ / Ctrl + 点击名字：跳到定义，并拦下这次点击，不让它再触发块上的切换。已知没有定义的名字照常点。 */
+  click(event: MouseEvent): void {
+    const offset = modifierHeld(event) ? offsetOf(nameAt(event.target)) : undefined
+    if (offset === undefined || this.version === undefined || this.answers.get(offset) === false)
+      return
+    event.preventDefault()
+    event.stopPropagation()
+    this.post({ type: 'goToDefinition', version: this.version, offset })
+  }
+
+  private update(): void {
+    const offset = this.held ? offsetOf(this.hovered) : undefined
+    if (offset !== undefined && this.version !== undefined && !this.answers.has(offset)) {
+      this.answers.set(offset, undefined)
+      this.post({ type: 'probeDefinition', version: this.version, offset })
+    }
+    const link = offset !== undefined && this.answers.get(offset) === true ? this.hovered : null
+    if (link === this.linked)
+      return
+    this.linked?.removeAttribute('data-link')
+    link?.setAttribute('data-link', '')
+    this.linked = link
+  }
+}
+
+/** 预览里的名字能 ⌘ / Ctrl + 点击跳到定义；version 是当前显示的文档版本，名字的下标属于它。 */
+export function useDefinitionLinks(version: number | undefined): void {
+  const [links] = useState(() => new DefinitionLinks(postMessage))
+
+  useEffect(() => {
+    links.setVersion(version)
+  }, [links, version])
+
+  useEffect(() => {
+    const onMove = (event: MouseEvent): void => links.point(event.target, modifierHeld(event))
+    const onOut = (event: MouseEvent): void => {
+      if (event.relatedTarget === null)
+        links.point(null, false)
+    }
+    const onKey = (event: KeyboardEvent): void => links.hold(modifierHeld(event))
+    const onBlur = (): void => links.hold(false)
+    const onClick = (event: MouseEvent): void => links.click(event)
+    const off = onMessage((msg) => {
+      if (msg.type === 'definitionProbed')
+        links.answer(msg.version, msg.offset, msg.found)
+    })
+    document.addEventListener('mousemove', onMove)
+    document.addEventListener('mouseout', onOut)
+    // 捕获阶段：先于块里的按钮、折叠箭头拿到点击
+    document.addEventListener('click', onClick, true)
+    window.addEventListener('keydown', onKey)
+    window.addEventListener('keyup', onKey)
+    window.addEventListener('blur', onBlur)
+    return () => {
+      off()
+      document.removeEventListener('mousemove', onMove)
+      document.removeEventListener('mouseout', onOut)
+      document.removeEventListener('click', onClick, true)
+      window.removeEventListener('keydown', onKey)
+      window.removeEventListener('keyup', onKey)
+      window.removeEventListener('blur', onBlur)
+    }
+  }, [links])
+}

vscode/webview-ui/src/codeReader/useReveal.ts

@@ -0,0 +1,63 @@
+import type { DocumentMessage, Reveal } from './types'
+import { useLayoutEffect } from 'react'
+import { revealPlan, scrollTopToShow } from './reveal'
+import { blockForLine } from './scrollPosition'
+import { measureBlocks } from './useScrollPosition'
+
+/** 让一块闪几下（codeReader.css 的 [data-flash]）；正在闪的同一块再跳一次时从头闪。 */
+function flash(el: HTMLElement): void {
+  const running = el.getAnimations().filter(animation => animation instanceof CSSAnimation)
+  if (running.length > 0) {
+    for (const animation of running)
+      animation.currentTime = 0
+    return
+  }
+  const onEnd = (event: AnimationEvent): void => {
+    if (event.target !== el)
+      return
+    el.removeAttribute('data-flash')
+    el.removeEventListener('animationend', onEnd)
+  }
+  el.addEventListener('animationend', onEnd)
+  el.setAttribute('data-flash', '')
+}
+
+/**
+ * 滚到 reveal 指的位置，处理完调 done：
+ * ① 从文本编辑器切过来（没有 definition）：包含那一行的块顶到视口顶部，折叠着的不展开；
+ * ② 跳到定义：先展开把目标藏起来的块和属性行（expand 之后重新渲染，再进来一次），再把目标块滚进视口、闪几下。
+ */
+export function useReveal(
+  doc: DocumentMessage | null,
+  reveal: Reveal | null,
+  collapsed: readonly string[],
+  expand: (ids: string[]) => void,
+  done: () => void,
+): void {
+  useLayoutEffect(() => {
+    if (!doc || !reveal)
+      return
+    if (reveal.definition === undefined) {
+      const top = blockForLine(measureBlocks(), reveal.line)?.top
+      if (top !== undefined)
+        window.scrollTo(0, top)
+      done()
+      return
+    }
+    const plan = revealPlan(doc.blocks, reveal.line, reveal.definition)
+    const hidden = plan?.expand.filter(id => collapsed.includes(id)) ?? []
+    if (hidden.length > 0) {
+      expand(hidden)
+      return
+    }
+    const el = plan && document.querySelector<HTMLElement>(`.cr-block[data-id="${plan.id}"]`)
+    if (el) {
+      const rect = el.getBoundingClientRect()
+      const top = scrollTopToShow({ top: rect.top + window.scrollY, bottom: rect.bottom + window.scrollY }, window.scrollY, window.innerHeight)
+      if (top !== undefined)
+        window.scrollTo(0, top)
+      flash(el)
+    }
+    done()
+  }, [doc, reveal, collapsed, expand, done])
+}

vscode/webview-ui/src/codeReader/useScrollPosition.ts

@@ -1,14 +1,14 @@
 import type { BlockBox } from './scrollPosition'
 import type { DocumentMessage } from './types'
 import { useEffect, useLayoutEffect, useRef } from 'react'
-import { anchorAt, blockForLine, scrollTopFor } from './scrollPosition'
+import { anchorAt, scrollTopFor } from './scrollPosition'
 import { postMessage, viewState } from './vscode'
 
 /** 滚动时最多这么久记一次位置 */
 const RECORD_INTERVAL_MS = 100
 
 /** 页面上每块（BlockCard 带 data-line）的位置，按页面上的先后。 */
-function measureBlocks(): BlockBox[] {
+export function measureBlocks(): BlockBox[] {
   const y = window.scrollY
   return Array.from(document.querySelectorAll<HTMLElement>('.cr-block[data-line]'), (el) => {
     const rect = el.getBoundingClientRect()
@@ -31,8 +31,8 @@ function record(reportedLine: { current: number | undefined }): void {
 /**
  * 记住并恢复预览看到的位置：
  * ① 滚动时把视口顶部那块记进 webview 状态，页面因标签页切走被重新加载后照着滚回去；
- * ② 同时把那块的起始行报给扩展端，切回文本编辑器时把这行放到顶部；
- * ③ 第一份文档带 revealLine（刚从文本编辑器切过来）时优先滚到包含这行的块。
+ * ② 同时把那块的起始行报给扩展端，切回文本编辑器时把这行放到顶部。
+ * 第一份文档带 reveal（刚从文本编辑器切过来、跳到定义）时不恢复，交给 useReveal 滚。
  */
 export function useScrollPosition(doc: DocumentMessage | null): void {
   const restored = useRef(false)
@@ -43,11 +43,8 @@ export function useScrollPosition(doc: DocumentMessage | null): void {
     if (!doc || restored.current)
       return
     restored.current = true
-    const boxes = measureBlocks()
     const saved = viewState.get().scroll
-    const top = doc.revealLine !== undefined
-      ? blockForLine(boxes, doc.revealLine)?.top
-      : saved && scrollTopFor(boxes, saved)
+    const top = doc.reveal === undefined && saved ? scrollTopFor(measureBlocks(), saved) : undefined
     if (top !== undefined)
       window.scrollTo(0, top)
     record(reportedLine)