⚡ perf(vscode): 代码阅读预览发给页面的块只记相对位置：块在源码里占的地方记成离前一块多远、自己多长，块里名字的下标从块的开头算，页面从文件开头累加回文件里的位置、和扩展端打交道的地方都在一处换算；靠前改了代码，后面内容没变的块发过去一模一样，扩展端自己的块和发给页面的块分成两种类型

vscode/src/codeReader/editor/messages.ts

@@ -4,9 +4,10 @@
 
 import type { ClaudeImage } from '../../cc/spawnClaude'
 import type { FileAttribute } from '../attributes'
-import type { BlockView, SourceColors } from '../blockView'
+import type { BlockSlot, CallTreeTarget, CommentTarget, SourceColors } from '../blockView'
 import type { ContractMiss } from '../callTree/endpoint'
 import type { CallTree } from '../callTree/model'
+import type { BlockAttributes, BlockConcept, KindBadge, Markdown, PreviewTable, PreviewText, PropertyItem, PropertyRow, SourceRange } from '../contract'
 import type { OpenedFrom } from '../diff/diffBase'
 import type { DocumentDiff } from '../diff/previewDiff'
 import type { ShownName } from '../nameResolution'
@@ -48,14 +49,52 @@ export interface Occurrence {
   kind: 'text' | 'read' | 'write'
 }
 
+/**
+ * 块在源码里占的地方，按相对的量记，前面的块变长变短、挪了位置它都不跟着变：
+ * 离前一个兄弟块的结尾（第一个子块从父块的开头算，顶层第一块从文件开头算）隔几行（lineGap）、几个字符（gap），
+ * 自己占几行（lines，首尾两行的行号差）、几个字符（length，第一行行首到最后一行行尾）。块的开头是它第一行的行首。
+ */
+export interface BlockSpan {
+  lineGap: number
+  gap: number
+  lines: number
+  length: number
+}
+
+/**
+ * 页面上一张卡片画的内容（发给页面的样子，见 pageCard）：同 BlockView 的这几样，块里的下标（名字的 offset、refers、defines）
+ * 都从块的开头算；不带行号、头部的最后一行（扩展端自己用），「重写注释」只带是换掉还是新写。
+ */
+interface PageCardBase {
+  id: string
+  anchor: string
+  kind: string
+  defines?: SourceRange
+  attributes: BlockAttributes
+  concepts: BlockConcept[]
+  commentTarget?: CommentTarget['kind']
+  badge?: KindBadge
+  slot?: BlockSlot
+  callTree?: CallTreeTarget
+}
+
+export type PageCard = PageCardBase & ({ translation: PreviewText, items?: PropertyItem[], table?: PreviewTable, doc?: Markdown, rows?: PropertyRow[] } | { properties: PropertyRow[] })
+
+/** 发给页面的一块（见 pageBlocks）：卡片的内容，在源码里占的地方（相对的，见 BlockSpan），子块。内容没变、只是挪了位置的块，发出去一模一样。 */
+export type PageBlock = PageCard & {
+  span: BlockSpan
+  children: PageBlock[]
+}
+
 /**
  * 悬停名字、注释里的链接时浮窗里的定义卡片：定义所在的文件（从工作区文件夹算起的相对路径，同挑选框）、定义处那一行（0 起），
- * 盖住定义处的那块（连同子块，和那个文件的预览画的是同一张卡片），显示成中文名的名字（下标是那个文件里的）。
+ * 盖住定义处的那块（连同子块，和那个文件的预览画的是同一张卡片；它自己当那个文件的顶层第一块，span 从文件开头算），
+ * 显示成中文名的名字（下标是那个文件里的）。
  */
 export interface DefinitionPeek {
   path: string
   line: number
-  block: BlockView
+  block: PageBlock
   names: ShownName[]
 }
 
@@ -64,7 +103,7 @@ export interface DocumentMessage {
   /** TextDocument.version：webview 靠它判断是不是新一份文档 */
   version: number
   languageId: string
-  blocks: BlockView[]
+  blocks: PageBlock[]
   /** 整份源码和它的着色，只这一份：编辑框里一块的源码、着色按它的编辑范围取；解析失败、语言不支持时是空的（没有块） */
   source: string
   colors: SourceColors