✨ feat(vscode): 代码阅读加 FastAPI 接口卡片：请求表（URL、方法、路径 / 查询参数、请求头、Cookie、请求体）、按状态码的响应表（成功、responses、函数里抛的异常、自动带的 422）；别的文件里的异常状态码、类型别名经工作区索引和语言扩展查

vscode/src/codeReader/contract.ts

@@ -274,8 +274,9 @@ export type TokenRole
  * 一段着色的文字。offset：这段照抄自源码里的名字（标识符、属性名、类型名、点分模块名的一节）或字符串时，
  * 它在源码里的起始下标（同 SourceSpan 的下标），预览拿它向 VS Code 查定义、跳过去；译词、提示词没有。
  * reference：只有库规则给的段有，这段讲的东西由规则自己查定义（LibraryRule.resolve），不问语言扩展；这样的段必须带 offset。
+ * color：这段自己的颜色（暗色、亮色主题各一个），盖过词性的颜色：库规则按库自己的配色上色（FastAPI 的 HTTP 方法用 Swagger UI 的颜色）。
  */
-export interface Segment { text: string, role: TokenRole, offset?: number, reference?: RuleReference }
+export interface Segment { text: string, role: TokenRole, offset?: number, reference?: RuleReference, color?: ThemeColor }
 
 /** 框的样式，决定框头的图标和框的颜色：'iteration' 是写在表达式里的遍历，图标、颜色同「循环」块。 */
 export type GroupStyle = 'iteration'
@@ -453,7 +454,7 @@ export interface RuleFacts {
   absorbs: CodeBlock[]
 }
 
-/** 库规则看一块时宿主给的：这份源码、它的导入，以及借当前翻译插件翻表达式、取说明的办法。 */
+/** 库规则看一块时宿主给的：这份源码、它的导入，借当前翻译插件翻表达式、取说明的办法，和查名字的定义在工作区索引里是哪一项的办法。 */
 export interface RuleContext {
   document: SourceDocument
   /** 这份源码里各处导入的 facts，照源码顺序：规则拿它认出库里名字的别名（`from sqlalchemy import Enum as SQLEnum`）。 */
@@ -464,6 +465,13 @@ export interface RuleContext {
   translate: (node: Node) => Inline[]
   /** 用当前翻译插件取一段说明文字（Translator.doc）；没有翻译插件、没有文字时没有。 */
   doc: (node: Node) => Markdown | undefined
+  /**
+   * 源码里 name 这个名字（例如 raise 后面的异常类名）指的定义在 index 里认出的那一项，规则从定义处读出的值在 IndexEntry.value 里：
+   * 定义由语言扩展查（同 ⌘ + 点击），落在 index 认出的某一项的名字上才算；同一份源码里同名的名字按一处查。
+   * 认领是同步的，查要等工作区索引建好、语言扩展答话：宿主先当没查到（undefined）交给规则排，发出预览后再查，
+   * 查到的和上次不一样就按新结果重排一遍、重发；文档改了先用上次查到的，再重查。没有工作区时（单元测试）总是 undefined。
+   */
+  lookup: (index: WorkspaceIndex, name: Node) => IndexEntry | undefined
 }
 
 /** 规则自己查得到定义的一个名字：哪个规则（LibraryRule.id），和规则自己认的键（Celery 的任务名）。 */
@@ -484,8 +492,11 @@ export interface IndexedFile {
   exists: (path: string) => boolean
 }
 
-/** 规则从一份文件里认出的一项：键，和定义处那个名字在源码里的范围。 */
-export interface IndexEntry { key: string, name: SourceRange }
+/**
+ * 规则从一份文件里认出的一项：键，定义处那个名字在源码里的范围，和规则从定义处读出、认领别的文件时要用的值
+ * （FastAPI 规则：异常类的 status_code；见 RuleContext.lookup）。
+ */
+export interface IndexEntry { key: string, name: SourceRange, value?: string }
 
 /**
  * 规则在整个工作区里建的索引（键 → 定义处）：规则只说看哪些文件、从一份源码里认出什么；