✨ feat(vscode): 代码阅读认出代码里起的中文名（Annotated[…, Comment("…")]、@Comment 装饰器、行尾 # @Comment、docstring / JSDoc 的参数说明），预览里定义和用到它的各处都写中文名，悬停看原名，定义处后面淡淡写原名

vscode/src/codeReader/contract.ts

@@ -312,12 +312,43 @@ export interface LanguageAdapter {
   tokenRole: (leaf: Node) => TokenRole
   /** node 是写在表达式里的遍历（推导式、生成器表达式）时给出它的结构，别的节点没有；没有这种写法的语言不填。 */
   iteration?: (node: Node) => IterationFacts | undefined
+  /** 认代码里给定义起的中文名（见「中文名」）；不填就没有中文名。 */
+  displayNames?: DisplayNameReader
+}
+
+// ── 中文名（见「中文名」）──
+
+/** 代码里给一个定义起的中文名：预览里这个定义和用到它的各处都显示中文名，悬停看原名。 */
+export interface DisplayName {
+  /** 定义处那个名字（函数名、类名、参数名、变量名、字段名、枚举成员名……） */
+  name: SourceRange
+  /** 中文名 */
+  text: string
+}
+
+/** 一份源码里认出的中文名。 */
+export interface DisplayNameFacts {
+  /** 起了中文名的定义，照源码顺序；一个定义几处都写了时语言插件定取哪个（明写的记号优先于说明文字） */
+  names: DisplayName[]
+  /** 写在注释里给代码阅读看的记号（`# @Comment 当前用户` 里的 `@Comment 当前用户`）：宿主交给翻译插件，翻注释、说明时去掉 */
+  markers: SourceRange[]
+}
+
+/** 语言插件认中文名：写法（记号、说明文字里的哪一句）归语言插件；找用到它的各处、显示归宿主和预览。 */
+export interface DisplayNameReader {
+  /** languageId → 工作区里这种语言的文件（glob，Python 是所有 .py 文件）：宿主建工作区索引，认出别的文件里定义的中文名 */
+  files: Record<string, string>
+  /** 便宜的文字预筛：可能写了中文名的源码才解析 */
+  mentions: (source: string) => boolean
+  find: (root: Node, source: string, languageId: string) => DisplayNameFacts
 }
 
 /** 翻译插件翻一块时拿到的这份源码：源码字符串，和解析它的语言插件。 */
 export interface SourceDocument {
   source: string
   language: LanguageAdapter
+  /** 写在注释里给代码阅读看的记号（中文名记号，见 DisplayNameFacts.markers）：不是说明文字，翻注释、说明时去掉 */
+  markers: SourceRange[]
 }
 
 /** 筛选属性和值的显示名，筛选栏、种类标签用它；没给名字的显示 id。 */