✨ feat(vscode): 代码阅读加 Celery 库规则，定时任务表里的任务名能跳到任务函数

vscode/src/codeReader/contract.ts

@@ -206,8 +206,9 @@ export type TokenRole
 /**
  * 一段着色的文字。offset：这段照抄自源码里的名字（标识符、属性名、类型名、点分模块名的一节）或字符串时，
  * 它在源码里的起始下标（同 SourceSpan 的下标），预览拿它向 VS Code 查定义、跳过去；译词、提示词没有。
+ * reference：只有库规则给的段有，这段讲的东西由规则自己查定义（LibraryRule.resolve），不问语言扩展；这样的段必须带 offset。
  */
-export interface Segment { text: string, role: TokenRole, offset?: number }
+export interface Segment { text: string, role: TokenRole, offset?: number, reference?: RuleReference }
 
 /** 框的样式，决定框头的图标和框的颜色：'iteration' 是写在表达式里的遍历，图标、颜色同「循环」块。 */
 export type GroupStyle = 'iteration'
@@ -350,6 +351,50 @@ export interface RuleContext {
   doc: (node: Node) => Markdown | undefined
 }
 
+/** 规则自己查得到定义的一个名字：哪个规则（LibraryRule.id），和规则自己认的键（Celery 的任务名）。 */
+export interface RuleReference { rule: string, key: string }
+
+/** 文件里的一个位置：行、列从 0 起，列按 UTF-16 计（同 VS Code）。 */
+export interface RulePosition { line: number, character: number }
+
+/** 规则查到的一处定义：文件（uri 字符串）和定义处那个名字的起止位置。 */
+export interface RuleLocation { uri: string, start: RulePosition, end: RulePosition }
+
+/** 建索引时交给规则的一份文件。 */
+export interface IndexedFile {
+  /** 相对它所在的工作区文件夹的路径，用 / 分隔。 */
+  path: string
+  source: string
+  /** 同一个工作区文件夹里有没有这个文件（相对路径）；只认按 WorkspaceIndex.include 找到的文件。算 Python 包路径时问 `__init__.py` 用。 */
+  exists: (path: string) => boolean
+}
+
+/** 规则从一份文件里认出的一项：键，和定义处那个名字在源码里的范围。 */
+export interface IndexEntry { key: string, name: SourceRange }
+
+/**
+ * 规则在整个工作区里建的索引（键 → 定义处）：规则只说看哪些文件、从一份源码里认出什么；
+ * 找文件、预筛、解析、缓存、跟着文件改动更新都归宿主。第一次查时才建，之后只重看改了的文件。
+ */
+export interface WorkspaceIndex {
+  /** 同一个 id 宿主只建一份，写成「规则 id.名字」（celery.tasks）。 */
+  id: string
+  /** 按哪种语言解析：宿主用这个 languageId 的语言插件。 */
+  languageId: string
+  /** 看哪些文件：相对各工作区文件夹的 glob（'**\/*.py'）；files.exclude、search.exclude 排除的，和 .venv、node_modules、__pycache__ 里的不看。 */
+  include: string
+  /** 便宜的文字预筛：源码里不可能有要找的东西就不解析。 */
+  mentions: (source: string) => boolean
+  /** 从一份文件的语法树里认出的各项；语法树只在调用期间有效。 */
+  entries: (root: Node, file: IndexedFile) => IndexEntry[]
+}
+
+/** 宿主给规则查定义用的工作区。 */
+export interface RuleWorkspace {
+  /** 在 index 建的索引里查 key 的各处定义，照文件、行排好。 */
+  lookup: (index: WorkspaceIndex, key: string) => Promise<RuleLocation[]>
+}
+
 /**
  * 库规则：认出某个库的一种写法（SQLAlchemy 的模型类），把那块整个换成一张专门的卡片；文件导入了它关心的库才启用。
  * 规则只经契约拿信息：块（kind、node、header、children、facts）和 RuleContext；用词（属性名、种类名、类型的译名）属于规则自己。
@@ -368,6 +413,11 @@ export interface LibraryRule {
    * 几个规则都认同一块时先注册的算；规则抛错、或替身不合上面的约定时，宿主记日志、当它没认，接着问下一个规则。
    */
   claim: (block: CodeBlock, context: RuleContext) => RuleBlock | undefined
+  /**
+   * 查规则自己标的引用（Segment.reference 里 rule 是这个规则的）的定义：预览里 ⌘ / Ctrl 悬停、点击这样的名字时宿主问它，不问语言扩展；
+   * 查到几处就跳、挑，和语言扩展查到的一样。没给就不能在段上标引用。
+   */
+  resolve?: (key: string, workspace: RuleWorkspace) => Promise<RuleLocation[]>
 }
 
 export interface CodeReaderApi {