✨ feat(vscode): 代码阅读把说明里的 @param / @return / @throws 拆到参数表、输出、异常表

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

@@ -240,14 +240,14 @@
 
 卡片外观（折叠箭头、种类图标、底色、悬停高亮、「编辑 / 预览」切换）和其他块一样，只是内容换成一张属性表：左列属性名（界面字体、`descriptionForeground` 色，宽 76px，这张表里有更长的属性名时整列按最长的那个放宽，值照样对齐在同一处，属性名不折行：shell 的「管道里任一步失败都算失败」），右列是值（等宽字体，按词性着色，长了换行），两列间距 12px，行高 20px。「输入参数」「导入项」和值是字典 / 对象字面量的「值」「初始值」下面展开子行，属性名前带折叠箭头（图标、大小、颜色同块的折叠箭头；点箭头或属性名切换，默认展开，折叠后值「N 个」「字典 N 项」照常显示，只收起子行）；子行往右缩进 5px，左边一条 1px 竖线（`editorIndentGuide-background1`）；输入参数例外，是一张表格（见下）。字典 / 对象的子行分键 / 值两列，键列宽 150px（编辑区窄时按 28% 收），值列占剩下的。子行下面还能再展开一层（嵌套的字典 / 对象）：带下一层的子行第一列前面有折叠箭头（点箭头或第一列切换，默认展开），同一层里其余子行在同样的位置留空、第一列对齐；下一层同样往右缩进 5px、左边一条竖线，竖线对着上一层的箭头，每层自己的两列对齐。同一层里没有带下一层的子行时不留箭头的位置（和导入项的子行一样）。
 
-输入参数的表格（原型 `paramRows`）：往右缩进 5px，第一行是表头「名称 | 类型 | 默认值」，下面每个参数一行。列宽按整列的内容定，webview 不认是哪种表格（库规则的字段表同样排，见 `tableTemplate`）：整张表格一个网格、各行借用它的列，前几列宽裕时放到整列不换行，最后一列（默认值、说明）分剩下的、至少留 `min(20%, 8em)`；放不下时先让最后一列换行，编辑区再窄前几列平分剩下的宽度、在格子里换行（长名字从中间断开），不撑出卡片、不藏掉哪一列。格子左右留 8px、上下 2px，长类型、长默认值在格子里换行，不挤掉别的列。外框 1px、圆角 4px，格子之间、行之间 1px 分隔线，颜色都是主题的表格分隔色（`--vscode-tree-tableColumnsBorder`，主题没给时退到 `--vscode-editorWidget-border`）；表头垫主题的表头底色（`--vscode-keybindingTable-headerBackground`，比编辑区深一档或浅一档），列名界面字体 12px、`descriptionForeground` 色。没有默认值的格子留空。折叠「输入参数」那一行时整张表收起；子行 id、跳到定义闪「它那个参数」、高亮名字的各处出现都和列表一样，闪的是表格里那一行（行边框和相邻行共用，改在行里面描一圈聚焦色）。哪些子行排成表格由翻译插件定：给了列名（`PropertyRow.columns`）的排成表格，没给的（导入项、字典 / 对象的各项）照旧是列表，webview 只看有没有列名。
+输入参数的表格（原型 `paramRows`）：往右缩进 5px，第一行是表头「名称 | 类型 | 默认值」，下面每个参数一行。列宽按整列的内容定，webview 不认是哪种表格（库规则的字段表同样排，见 `tableTemplate`）：整张表格一个网格、各行借用它的列，前几列宽裕时放到整列不换行，最后一列（默认值、说明）分剩下的、至少留 `min(20%, 8em)`；放不下时先让最后一列换行，编辑区再窄前几列平分剩下的宽度、在格子里换行（长名字从中间断开），不撑出卡片、不藏掉哪一列。格子左右留 8px、上下 2px，长类型、长默认值在格子里换行，不挤掉别的列。外框 1px、圆角 4px，格子之间、行之间 1px 分隔线，颜色都是主题的表格分隔色（`--vscode-tree-tableColumnsBorder`，主题没给时退到 `--vscode-editorWidget-border`）；表头垫主题的表头底色（`--vscode-keybindingTable-headerBackground`，比编辑区深一档或浅一档），列名界面字体 12px、`descriptionForeground` 色。没有默认值的格子留空。格子可以是 Markdown（参数的「说明」、「异常」表的两列、对不上的参数的说明）：按「注释的 Markdown 排版」显示（界面字体、注释色），着色的词照旧排在等宽字体的段落里，差异逐词标。属性行跟着的说明（`PropertyRow.note`，输出参数的 `@return`）接在值后面，同一行放得下就并排，剩下的地方不到 12 个字宽时换到下一行。折叠「输入参数」那一行时整张表收起；子行 id、跳到定义闪「它那个参数」、高亮名字的各处出现都和列表一样，闪的是表格里那一行（行边框和相邻行共用，改在行里面描一圈聚焦色）。哪些子行排成表格由翻译插件定：给了列名（`PropertyRow.columns`）的排成表格，没给的（导入项、字典 / 对象的各项）照旧是列表，webview 只看有没有列名。
 
 | 种类 | 行 |
 | --- | --- |
-| 函数 | 名称（函数色；匿名函数写「匿名」）/ 说明（有说明才显示：JSDoc 去掉 `/**`、`*/` 和每行开头的 `*`，docstring 去掉引号；再去掉共同缩进和首尾空行，`@param` 这类标签行照抄；得到的原文按 Markdown 渲染，见「注释的 Markdown 排版」；里面的名字不能点）/ 访问级别 / 异步（是 / 否）/ 装饰器（有才显示，源码原样照抄、按源码着色，多个换行）/ 输入参数（`N 个` 或「无」，展开成表格，列名 名称 \| 类型 \| 默认值，每个参数一行：名称 \| 类型（没标注写「未标注」）\| 默认值（译文，没有留空））/ 输出参数（返回类型的译文，没标注写「未标注」） |
-| 类 | 名称（类型色；匿名类 `export default class {}` 写「匿名」；赋给变量、类字段的类表达式写变量名、字段名）/ 说明（有说明才显示，规则同函数）/ 访问级别 / 抽象（是 / 否，只有 TypeScript / TSX 有，看 `abstract class`，TypeScript 的类都有这一行；JavaScript / JSX 没有）/ 装饰器（同函数）/ 类型参数（有才显示：TypeScript `<K, T extends X = Y>` 每个参数的译文，逗号隔开，如 `K, T 限定为 X = Y`；Python 3.12 的 `class G[T]` 同样）/ 父类（有才显示：TypeScript `extends` 后面的表达式连着泛型实参的译文，如 `Base<字符串>`；Python 类名后面括号里的参数列表照写的顺序逐项翻，关键字参数、`*bases` 也在这一行，如 `Base, metaclass=ABCMeta`；逗号隔开）/ 实现的接口（有才显示：TypeScript `implements` 后面每个类型的译文，逗号隔开） |
+| 函数 | 名称（函数色；匿名函数写「匿名」）/ 说明（有正文才显示：JSDoc 去掉 `/**`、`*/` 和每行开头的 `*`，docstring 去掉引号；再去掉共同缩进和首尾空行，拆掉块标签（见「注释的 Markdown 排版」），剩下的正文按 Markdown 渲染）/ 对不上的参数（说明里有 `@param` 的名字在输入参数里没有时才显示：`N 个`，展开成表格「名称 \| 说明」，名称是 hint 色、悬停「没有这个参数」）/ 访问级别 / 异步（是 / 否）/ 装饰器（有才显示，源码原样照抄、按源码着色，多个换行）/ 输入参数（`N 个` 或「无」，展开成表格，列名 名称 \| 类型 \| 默认值，每个参数一行：名称 \| 类型（没标注写「未标注」）\| 默认值（译文，没有留空）；任何一个参数对上了 `@param` 时多一列「说明」（Markdown，没对上的格子留空），按名字对，`*args` / `**kwargs` / `...rest` 去掉前缀对）/ 输出参数（返回类型的译文，没标注写「未标注」；写了 `@return` 时类型后面跟着这段说明，Markdown、注释色）/ 异常（写了 `@throws` 才显示：`N 个`，展开成表格「异常 \| 触发条件」，一条一行，都是 Markdown，异常名能点，见「注释的 Markdown 排版」的引用） |
+| 类 | 名称（类型色；匿名类 `export default class {}` 写「匿名」；赋给变量、类字段的类表达式写变量名、字段名）/ 说明（有正文才显示，规则同函数）/ 访问级别 / 抽象（是 / 否，只有 TypeScript / TSX 有，看 `abstract class`，TypeScript 的类都有这一行；JavaScript / JSX 没有）/ 装饰器（同函数）/ 类型参数（有才显示：TypeScript `<K, T extends X = Y>` 每个参数的译文，逗号隔开，如 `K, T 限定为 X = Y`；Python 3.12 的 `class G[T]` 同样）/ 父类（有才显示：TypeScript `extends` 后面的表达式连着泛型实参的译文，如 `Base<字符串>`；Python 类名后面括号里的参数列表照写的顺序逐项翻，关键字参数、`*bases` 也在这一行，如 `Base, metaclass=ABCMeta`；逗号隔开）/ 实现的接口（有才显示：TypeScript `implements` 后面每个类型的译文，逗号隔开）/ 构造参数（说明里写了 `@param` 才显示：类卡片没有构造参数表可对，照写成「名称 \| 说明」表）/ 异常（同函数） |
 | 枚举 | 名称（类型色）/ 说明（有说明才显示，规则同函数）/ 访问级别（同类）/ 装饰器（有才显示，同函数）/ 继承（有才显示：Python 类名后面括号里照写的父类，如 `str, enum.Enum`；TypeScript 没有）/ 成员（`N 个` 或「无」，展开成表格，列名 成员 \| 值 \| 说明，每个成员一行：成员名（variable 色）\| 值（写了值是值的译文；没写值时是语言算出来的值，TypeScript 数值枚举自增的 0、1、2……，算不出来和 Python 的 `auto()` 写「自动」，这两种按 hint 着色）\| 说明（成员的注释、JSDoc、属性 docstring 的原文用空格连起来，comment 色；一个成员都没有说明时没有这一列）；讲的定义是成员名，跳到成员名只闪那一行）。原型「枚举」一节（`ENUM_SAMPLE`、`enumCard`） |
-| 异常 | 名称（类型色；匿名类写「匿名」）/ 说明（有说明才显示，规则同函数）/ 访问级别（同类）/ 装饰器（有才显示，同函数）/ 继承（有才显示：照写的父类，同类的「父类」，如 `Exception`、`errors.HttpException<字符串>`）/ 属性（有类属性才显示：`N 个`，展开成表格，列名 属性 \| 类型 \| 值 \| 说明，每个属性一行：属性名（variable 色）\| 类型（写了标注是它的译文，一个属性都没标注时没有这一列）\| 值（写了值是值的译文，没写留空）\| 说明（同枚举成员的说明，一个属性都没有说明时没有这一列）；讲的定义是属性名）/ 构造参数（写了构造函数才显示：表格同函数的「输入参数」，Python 去掉 self；讲的定义是参数名）。见「异常」 |
+| 异常 | 名称（类型色；匿名类写「匿名」）/ 说明（有说明才显示，规则同函数）/ 访问级别（同类）/ 装饰器（有才显示，同函数）/ 继承（有才显示：照写的父类，同类的「父类」，如 `Exception`、`errors.HttpException<字符串>`）/ 属性（有类属性才显示：`N 个`，展开成表格，列名 属性 \| 类型 \| 值 \| 说明，每个属性一行：属性名（variable 色）\| 类型（写了标注是它的译文，一个属性都没标注时没有这一列）\| 值（写了值是值的译文，没写留空）\| 说明（同枚举成员的说明，一个属性都没有说明时没有这一列）；讲的定义是属性名）/ 构造参数（写了构造函数才显示：表格同函数的「输入参数」，Python 去掉 self，类说明里的 `@param` 同函数对进「说明」列、对不上的排在说明下面；讲的定义是参数名；没写构造函数时同类，说明里的 `@param` 照写成表）/ 异常（同函数）。见「异常」 |
 | 导入 | 来源（TypeScript 是字符串字面量原样，如 `'node:fs'`，字符串色；Python 是点分模块名，如 `fastapi`、`.models`，类型色）/ 仅类型（是 / 否，只有 TypeScript / TSX 有，看 `import type`；JavaScript / JSX 没有）/ 导入项（`N 个` 或「无」，每项一行：`name`、`name 作为 alias`；默认导入写「默认导出 作为 x」，`* as x` 写「全部 作为 x」，Python `from m import *` 写「全部」，Python `import a.b as c` 写「整个模块 作为 c」，一条 `import a, b` 导入多个模块时写模块名） |
 | 常量 / 变量 | 名称（解构声明写整个模式，如 `{ p, q }`）/ 说明（有说明才显示：Python 的属性 docstring，规则同函数；一条语句一个，排在第一个名称后面）/ 访问级别 / 类型（写了标注才有）/ 值（常量）或初始值（变量）：初始化表达式的译文，没有写「无」；是字典 / 对象字面量时见下面「字典 / 对象字面量」。一条语句声明几个变量（`let a = 1, b = 2`）就重复几组 |
 
@@ -462,8 +462,14 @@
 
 ### 注释的 Markdown 排版
 
-- 用在：注释块（`#`、`//`、`/* */`、不挂在函数、类上的 JSDoc、Python 模块开头的 docstring 和别的当注释用的单独字符串）的预览，函数、类、常量、变量属性表的「说明」，字段译文下面的说明。视图数据里它们是 `{ markdown }`（见「通用契约」的 `Markdown`），webview 按数据决定怎么渲染，不猜。
+- 用在：注释块（`#`、`//`、`/* */`、不挂在函数、类上的 JSDoc、Python 模块开头的 docstring 和别的当注释用的单独字符串）的预览，函数、类、常量、变量属性表的「说明」，参数表的「说明」列、「异常」表、输出参数后面的 `@return`，字段译文下面的说明。视图数据里它们是 `{ markdown }`（见「通用契约」的 `Markdown`），webview 按数据决定怎么渲染，不猜。
 - 原文：翻译插件去掉注释符号（`#`、`//`、`/*` `*/` 和每行开头的 `*`）、引号和中文名记号（`SourceDocument.markers`，见「中文名」），再去掉行尾空白、首尾空行和共同缩进，保留换行，不做别的转换。一个注释节点（块注释、docstring）的第一行紧跟在注释符号 / 引号后面，不参与算共同缩进（同 PEP 257）；几条行注释连成的一块每行地位相同，第一行也算，缩进四格的代码块才留得住。
+- 块标签：说明（`Translator.doc` 读的：函数、类这些定义的说明，字段、成员的说明，库规则取的说明）的原文按 KDoc 拆成正文和块标签（`Doc`，解析在 `docTags.ts`，各卡片共用）；单独成块的注释照原文显示，不拆。
+  - 认 `@param`、`@return`（`@returns` 同义）、`@throws`（`@exception` 同义）。一行（去掉开头空白）以标签开头算一条；后面接着的行（不是空行、不以 `@` 开头）续在这条后面（去掉开头空白、换行留着）；空行结束这条，以 `@` 开头的行也结束上一条。围栏代码块里的行不认标签。
+  - `@param 名字 说明`；JSDoc 的 `@param {类型} 名字 - 说明`、`@param [名字] 说明`、`@param [名字=默认值] 说明` 也认（类型、横杠、默认值去掉）。`@return 说明`、`@returns {类型} 说明` 同样去掉类型。`@throws 异常 触发条件`：异常是一个名字、`[Foo]`、`[说法](路径#Foo)` 或 JSDoc 的 `{Foo}`，只是名字的写成不带路径的引用 `[Foo]`。几条 `@return` 用空行连成一段。
+  - 正文是拿掉这几种标签后剩下的行（标签前后的正文都留着），去掉首尾空行，连着的几个空行并成一个；只写了标签时没有正文。别的标签（`@see`、`@since`）留在正文里。
+  - 放到哪见「属性表」和各库规则：`@param` 对到参数表多出的「说明」列（按名字对，`*args` / `**kwargs` / `...rest` 去掉前缀），对不上的在说明下面列成「对不上的参数」；`@return` 跟在输出参数 / 返回那一行的值后面（`PropertyRow.note`）；`@throws` 是「异常」一行。卡片共用的几行在 `rules/docRows.ts`。
+  - 中文名的兜底（`languages/typescriptNames.ts`、`pythonNames.ts` 从 `@param` / `Args:` 取参数的中文名）是另一回事，照旧读源码。
 - 渲染：webview 用 markdown-it（`html: false`、`linkify: true`），CommonMark 加 GFM 的表格、删除线：段落、强调、行内代码（含双反引号）、代码块（围栏、缩进四格）、列表、链接、标题、引用、表格。段内单个换行是软换行，空行分段。同一段文字只渲染一次（缓存最近 500 段）。
 - 安全：源码里的 HTML 当文字显示；链接认 http / https / mailto，带协议的网址和邮箱自动成链接（`sample.py` 这种不带协议的不算），别的写法（`javascript:`、`command:`、`./`、`..`、绝对路径、盘符）照原文显示。http / https / mailto 由 VS Code 的 webview 自己拦下、交给宿主在外部打开，不用另发消息。http / https 图片不渲染（webview 的 CSP 不放行外部图片），`![alt](url)` 显示成 `!` 加链接。仓库内图片按原图比例显示，点了打开原图，没有就写「找不到图片」和路径。
 - 仓库路径链接（`[名字](从仓库根起的路径)`，可带 `#类名` 或 `#类名.成员`）能点，点了打开文件并跳到符号。指到目录的在代码阅读侧栏的树上定位（展开并选中，和侧栏跟着当前文件走是同一个定位；侧栏没露着时亮出来），不切到 VS Code 资源管理器；树上没有（开着筛选时没摆它）时提示「侧栏的树上没有 …」，不退出筛选。
@@ -847,8 +853,9 @@ export type TokenRole =
  * color：这段自己的颜色（暗色、亮色主题各一个），盖过词性的颜色：库规则按库自己的配色上色（FastAPI 的 HTTP 方法用 Swagger UI 的颜色）。
  * refers：这段讲的是源码里别处的一个名字（那个名字的范围），语言扩展不认得这段自己的位置：写在字符串里的名字（FastAPI 路径里的参数名）。
  * 预览把这段当那个名字：⌘ / Ctrl + 点击跳到它的定义，单击高亮它的各处出现，它的某处出现盖住 refers 时这段也高亮；offset 照旧是照抄的位置。
+ * tooltip：悬停这段时看的字（说明里写了、参数表里没有的参数名：「没有这个参数」）。
  */
-export interface Segment { text: string, role: TokenRole, offset?: number, reference?: RuleReference, color?: ThemeColor, refers?: SourceRange }
+export interface Segment { text: string, role: TokenRole, offset?: number, reference?: RuleReference, color?: ThemeColor, refers?: SourceRange, tooltip?: string }
 
 /**
  * 框的样式，决定框头图标和框的颜色：iteration 写在表达式里的遍历（渲染大纲的「对 … 的每一项」也是），图标、颜色同「循环」块；
@@ -873,6 +880,18 @@ export type Inline = Segment | SegmentGroup
  */
 export interface Markdown { markdown: string }
 
+/** 说明里讲的一个参数（`@param 名字 说明`）：名字照写（`*args`、`...rest` 带着前缀），说明是 Markdown。 */
+export interface DocParam { name: string, text: Markdown }
+
+/** 说明里讲的一种异常（`@throws 异常 什么时候抛`）：只写了名字的（`ValueError`、JSDoc 的 `{ValueError}`）写成 `[ValueError]`，`[Foo]`、`[说法](路径#Foo)` 照写。 */
+export interface DocThrows { exception: Markdown, when: Markdown }
+
+/**
+ * 一段说明（Translator.doc 读出来的）：原文按 KDoc 拆成正文和块标签（规则见「注释的 Markdown 排版」的块标签）。
+ * 只写了标签、没有正文时没有 body。
+ */
+export interface Doc { body?: Markdown, params: DocParam[], returns?: Markdown, throws: DocThrows[] }
+
 /** 预览里显示的一段文字：着色的词（一行译文、属性值），或整段 Markdown 说明（注释块、函数和类的说明）。 */
 export type PreviewText = Inline[] | Markdown
 
@@ -883,9 +902,12 @@ export type PreviewText = Inline[] | Markdown
  */
 export interface Defines { defines?: SourceRange }
 
-/** 属性表里展开的一个子行：几列对齐的格子；items 是展开在它下面的下一层子行（嵌套的字典 / 对象），一层层可以一直往下套。 */
+/**
+ * 属性表里展开的一个子行：几列对齐的格子，格子是着色的词或一段 Markdown（参数的说明、异常的触发条件）；
+ * items 是展开在它下面的下一层子行（嵌套的字典 / 对象），一层层可以一直往下套。
+ */
 export interface PropertyItem extends Defines {
-  cells: Inline[][]
+  cells: PreviewText[]
   items?: PropertyItem[]
   table?: PreviewTable // 排在最后一格里、文字下面的表：实参的值里跨几行写的调用的实参表，一层层往下套，总是展开
 }
@@ -893,8 +915,9 @@ export interface PropertyItem extends Defines {
 /**
  * 属性表的一行：属性名、着色的值或 Markdown 说明（函数、类的「说明」）、展开在下面的子行（输入参数、导入项、字典 / 对象的各项）。
  * columns 是子行各列的列名（输入参数的名称 / 类型 / 默认值）：给了的子行排成带表头的表格（只有一层），没给的排成列表。
+ * note 是跟在值后面的一段说明（Markdown，注释色）：输出参数那一行，返回类型后面是说明里的 `@return`。
  */
-export interface PropertyRow extends Defines { label: string, value: PreviewText, items?: PropertyItem[], columns?: string[] }
+export interface PropertyRow extends Defines { label: string, value: PreviewText, note?: Markdown, items?: PropertyItem[], columns?: string[] }
 
 /** 一张带表头和边框的表：列名，每行几列对齐的格子，同 PropertyRow 给了 columns 的子行。 */
 export interface PreviewTable { columns: string[], items: PropertyItem[] }
@@ -981,7 +1004,7 @@ export interface Translator {
   translate: (block: TextBlock, document: SourceDocument) => TextTranslation  // 只翻 header 那一段；注释块给 Markdown 原文；跨几行写的调用带实参表
   describe: (block: FactBlock, document: SourceDocument) => PropertyRow[] // 函数、类、枚举、异常、导入、常量、变量块 → 属性表
   expression: (node: Node, document: SourceDocument) => Inline[]          // 一个表达式 / 类型节点整个翻成一行译文，译法同属性表的值；库规则借它
-  doc: (node: Node, document: SourceDocument) => Markdown | undefined     // 说明文字（注释、docstring、当说明用的字符串）→ Markdown 原文，同属性表的「说明」
+  doc: (node: Node, document: SourceDocument) => Doc | undefined          // 说明文字（注释、docstring、当说明用的字符串）→ 正文和块标签（Doc）；正文同属性表的「说明」；连着几行的行文档注释（Rust 的 `///`）node 是第一条，翻译插件自己往下连
   attributeNames?: AttributeNames // 筛选属性和值叫什么，和属性表的叫法一致；筛选栏、种类图标的悬停提示用它
 }
 
@@ -1039,7 +1062,7 @@ export interface RuleContext {
   imports: ImportFacts[]      // 这份源码里各处导入，照源码顺序：认别名用
   displayLanguage?: string    // 当前翻译插件的 displayLanguage；没有翻译插件时没有
   translate: (node: Node) => Inline[]            // 借当前翻译插件的 expression；没有翻译插件时照抄源码
-  doc: (node: Node) => Markdown | undefined      // 借当前翻译插件的 doc
+  doc: (node: Node) => Doc | undefined           // 借当前翻译插件的 doc：正文和块标签，规则按自己的卡片把标签放到对应的行
   lookup: (index: WorkspaceIndex, name: Node) => IndexEntry | undefined // name 指的定义在 index 里认出的那一项（见「规则认领时查别的文件里的定义」）；还没查到是 undefined
 }
 
@@ -1143,7 +1166,7 @@ export interface CommandRule {
   - 规则自己的卡片（`RuleCard`），下面几条都说的是它。
 - 卡片必须给：`kind`（写成「规则 id.名字」，宿主核对前缀；筛选记住的就是它，要稳定）、`badge`（种类的名字、暗 / 亮两种颜色和 lucide 图标名）、`rows`（用现成的 `PropertyRow`：属性名 + 着色的值或 Markdown，表格就是带 `columns` 的子行）、`absorbs`（并进来的子块）。可以给：`defines`（块自己的名字，跳到定义是它时闪整块）、`attributes`（自己的筛选属性）、`concepts`（额外认出的概念，排在种类图标后面）、`slots`（挂在卡片某一行的子行上、点子行才展开的子块，见下）；表格子行填 `PropertyItem.defines`（字段名），跳到这个定义时只闪那一行。
 - 挂在卡片子行上的子块（`RuleSlot`）：留下的子块（没并进来的）可以不排在卡片后面，挂在卡片第 `row` 行的第 `item` 个子行上（讲它的那一个子行）；它默认收着，点那个子行的第一格才在这一行下面展开当子卡片、同一行里别的收起（Rust 实现块的方法表点方法名）。它照常转成块，照样问各规则，编辑、问 AI、差异、筛选都照常。一块只能放一处，不能同时并进来；`row` 要有这一行、`item` 要有这个子行。只有这一种放法：子块要么挂在讲它的子行上，要么照常排在卡片后面。
-- 只经契约：规则拿到的是块（kind、node、header、children、facts）和 `RuleContext`；源码里的名字照抄时自己带下标（`Segment.offset`），表达式、类型交给 `context.translate`（当前翻译插件的 `expression`，名字带下标，⌘ + 点击、高亮各处出现照常），说明文字交给 `context.doc`（当前翻译插件的 `doc`，和别的「说明」一样按 Markdown 显示），别的文件里定义的名字交给 `context.lookup`（见「规则认领时查别的文件里的定义」）；库自己的配色（HTTP 方法）写在段的 `color` 上。规则可以读自己那门语言的语法树（规则声明了 `languageIds`），但不 import 语言插件、翻译插件和宿主模块（`rules/contractOnly.test.ts` 检查 `rules/` 下非测试文件只 import `../contract` 和同目录的文件）。
+- 只经契约：规则拿到的是块（kind、node、header、children、facts）和 `RuleContext`；源码里的名字照抄时自己带下标（`Segment.offset`），表达式、类型交给 `context.translate`（当前翻译插件的 `expression`，名字带下标，⌘ + 点击、高亮各处出现照常），说明文字交给 `context.doc`（当前翻译插件的 `doc`，给正文和块标签：正文和别的「说明」一样按 Markdown 显示，标签放到规则自己卡片对应的行，共用的几行在同目录的 `docRows.ts`），别的文件里定义的名字交给 `context.lookup`（见「规则认领时查别的文件里的定义」）；库自己的配色（HTTP 方法）写在段的 `color` 上。规则可以读自己那门语言的语法树（规则声明了 `languageIds`），但不 import 语言插件、翻译插件和宿主模块（`rules/contractOnly.test.ts` 检查 `rules/` 下非测试文件只 import `../contract` 和同目录的文件）。
 - 用词归规则：属性名、表头、种类名、类型译名都在规则自己的词表里，按 `context.displayLanguage`（翻译插件的 `displayLanguage`）挑，没有这种语言的词表就用规则默认的那份；加一种显示语言就是给规则加一份词表。webview 只画结构，不认识「数据表」这些字。
 
 ### 启用、认领、优先
@@ -1376,7 +1399,7 @@ export interface CommandRule {
 
 - 字段：字段名（variable 色，带下标）。类型：注解照写法翻（翻译插件翻，`str` → 字符串），`InitVar[X]` 写 X。
 - 默认值：`= x` 写 x（翻译插件翻，`None` → 空）；`field(default=x)` 写 x；`field(default_factory=f)` 写「每次新建 f()」（`list` → 每次新建 list()；不带参数的 `lambda` 写它返回的东西：`lambda: {"a": 1}` → 每次新建 {"a": 1}）；没写默认值时空着。后面接 `field(...)` 的别的参数，照写的顺序：`init=False` 不进构造函数、`repr=False` 不显示、`compare=False` 不参与比较、`hash=True` 参与哈希、`hash=False` 不参与哈希、`kw_only=True` 只能按名字传参、`kw_only=False` 可按位置传参，写成默认值的不讲，别的照写 `名=值`（`metadata={"unit": "px"}`）；最后是 `KW_ONLY` 带来的「只能按名字传参」。各项用 ` · ` 隔开。
-- 说明：`field(doc="…")` 的字符串；没写时同枚举成员的说明取法（紧挨在上面的注释块、这一行行尾的注释、紧跟在后面的属性 docstring，原文用空格连起来），comment 色。
+- 说明：`field(doc="…")` 的字符串；没写时同枚举成员的说明取法（紧挨在上面的注释块、这一行行尾的注释、紧跟在后面的属性 docstring，原文用空格连起来），comment 色；都没有时是类说明里讲它的 `@param`（字段就是构造参数，Markdown）。类说明里 `@param` 的名字不是哪个字段时，在卡片的「说明」下面列成「对不上的参数」；`@throws` 是卡片最后的「异常」表。
 
 样例（`fixtures/dataclassModels.py` 的 `SandboxAccess`，测试里逐字核对；说明的 Markdown 从略）：
 
@@ -1435,7 +1458,7 @@ export interface CommandRule {
 
 - 字段：字段名（variable 色，带下标）。类型：注解照写法翻（翻译插件翻，`str` → 字符串，`str \| None` → 字符串 \| 空）；类型里的名字带源码下标，能点。
 - 默认值：`= x` 写 x（`None` → 空）；`Field(default=x)` 或第一个位置参数写 x（`Field(...)` 的 `...` 是必填，不算默认值）；`Field(default_factory=f)` 写「每次新建 f()」，和数据类同一个说法。后面接 `Field(...)` 的约束，照写的顺序用 ` · ` 隔开：`min_length=1` 至少 1 个字符、`max_length=255` 最长 255、`ge=0` ≥ 0、`le` ≤、`gt` >、`lt` <、`multiple_of=3` 3 的倍数、`pattern` 匹配、`min_items` / `max_items` 至少 / 最多 N 项、`max_digits` 最多 N 位数字、`decimal_places` 小数 N 位。`default`、`default_factory`、`description` 不在这里重复。不认得的照写 `名=值`，不丢掉。
-- 说明：`Field(description="…")` 的字符串优先（不是字符串就照写法翻）；没有就用字段上方的注释、这一行行尾的注释、紧跟在后面的属性 docstring，原文用空格连起来，comment 色。
+- 说明：`Field(description="…")` 的字符串优先（不是字符串就照写法翻）；没有就用字段上方的注释、这一行行尾的注释、紧跟在后面的属性 docstring，原文用空格连起来，comment 色；都没有时是类说明里讲它的 `@param`（同数据类）。对不上的 `@param`、`@throws` 同数据类。
 
 样例（`fixtures/aigcMetadata.py` 的 `AIGCMetadata`，从 luffy `model/aigc.py` 摘的，测试里逐字核对）：
 
@@ -1504,14 +1527,16 @@ export interface CommandRule {
 | 行 | 内容 |
 | --- | --- |
 | 名称 | 函数名（function 色，带下标） |
-| 说明 | 函数的 docstring，同函数块；Markdown |
+| 说明 | 函数的 docstring 的正文，同函数块；Markdown |
+| 对不上的参数 | 说明里 `@param` 的名字不是这个函数的参数时才有，同函数块（依赖、FastAPI 自己填的参数是函数的参数，不算对不上） |
 | 路由器 | 挂在哪个路由对象上：它的名字（variable 色，带下标，⌘ + 点击跳到路由器卡片） |
 | 标签 | 路由对象的 `tags=` 加装饰器的 `tags=`，字符串不带引号（string 色，带下标），「、」隔开 |
 | 异步 | 是 / 否（storage 色） |
 | 装饰器 | 路由装饰器以外的装饰器（`@cache(60)`），有才显示 |
 | 依赖 | 路由对象、装饰器的 `dependencies=[Depends(x)]` 写 `x`，参数上的 `Depends(x)` / `Security(x)` 写 `x（参数名）`，参数名是 `_` 的只写 `x`；`Depends()` 不带参数时 x 是参数的类型；照这个顺序，「、」隔开。x 是一个名字时按 function 色、带下标，别的写法交给翻译插件翻 |
-| 请求 | 值是 `方法 URL`（hint），下面一张表格「项 \| 值」，一项一行，没有的项不列：URL、方法、路径参数、查询参数、请求头、Cookie、请求体 |
-| 响应 | 值是各状态码用 ` / ` 连起来（hint），下面一张表格「状态码 \| 内容 \| 说明」，一个状态码一行，按状态码从小到大，不是三位数字的（`"5XX"`）排在最后 |
+| 请求 | 值是 `方法 URL`（hint），下面一张表格「项 \| 值」，一项一行，没有的项不列：URL、方法、路径参数、查询参数、请求头、Cookie、请求体。说明里有请求参数对上了 `@param` 时多一列「说明」（Markdown），这几种参数改成一个参数一行、各带它的说明，URL、方法和没写说明的格子留空 |
+| 响应 | 值是各状态码用 ` / ` 连起来（hint），下面一张表格「状态码 \| 内容 \| 说明」，一个状态码一行，按状态码从小到大，不是三位数字的（`"5XX"`）排在最后；说明里写了 `@return` 时跟在值后面 |
+| 异常 | 说明里写了 `@throws` 才有，同函数块的「异常」表 |
 
 请求表：
 
@@ -1583,7 +1608,7 @@ TSX 和 Python 一样，从上往下一块语法一张卡片，嵌套的块排
 | `react.source` | 数据源 | `download` | #9cdcfe / #001080 | 别的钩子赋给变量（`useQuery`、`usePathname`、`useRouter`、自定义 `useXxx`） | 变量 / 钩子 / 说明 |
 | `react.derived` | 派生值 | `sigma` | #9cdcfe / #001080 | `useMemo`、`useCallback` | 名称 / 计算表达式 / 依赖项 |
 | `react.effect` | 副作用 | `zap` | #e5c07b / #9a6a00 | `useEffect`、`useLayoutEffect`、`useInsertionEffect` | 触发时机 / 清理函数 |
-| `react.handler` | 事件处理函数 | `mouse-pointer-click` | #dcdcaa / #795e26 | 组件体里定义的函数（函数声明、值是函数的常量） | 名称 / 参数 / 绑定事件 |
+| `react.handler` | 事件处理函数 | `mouse-pointer-click` | #dcdcaa / #795e26 | 组件体里定义的函数（函数声明、值是函数的常量） | 名称 / 说明 / 参数 / 绑定事件（说明里的块标签另有几行，见下） |
 | `react.render` | 渲染输出 | `layout-template` | #89d185 / #388a34 | 组件函数自己返回 JSX 的 return | JSX 结构大纲 |
 
 组件色同时用在渲染大纲里的组件、「客户端组件」标签上；状态、引用、数据源、派生值都是数据，共用变量块的浅蓝，靠图标区分；副作用同「选项」块的黄，事件处理函数同「函数」块，渲染输出同「返回」块的绿。筛选栏的「种类」按这几个 id 筛，叫上表的名字。
@@ -1603,8 +1628,14 @@ TSX 和 Python 一样，从上往下一块语法一张卡片，嵌套的块排
 | 行 | 内容 |
 | --- | --- |
 | 名称 | 组件名（组件色，带下标）；后面跟小标签（`tag` 框）：「具名导出」「默认导出」（同 import / export 关键字的颜色；`export default X`、`export { X }` 写在文件别处也算）、「客户端组件」（组件色）、「记忆化」「转发 ref」（同 const 关键字的颜色，memo / forwardRef 包着） |
-| 说明 | 组件上面的 JSDoc，Markdown |
-| 构造参数 | `N 个`（hint）；属性类型写的是一个名字（接口、类型别名、导入的类型）时后面写「 · 类型 XxxProps」，名字带下标（⌘ + 点击跳到类型）。下面一张表格「名称 \| 类型 \| 默认值 \| 必填」，有属性带说明时多一列「说明」。没写参数时写「无」 |
+| 说明 | 组件上面的 JSDoc 的正文，Markdown（块标签拆开放，见下） |
+| 对不上的参数 | 说明里 `@param` 的名字不是哪个属性时才有，同函数块 |
+| 构造参数 | `N 个`（hint）；属性类型写的是一个名字（接口、类型别名、导入的类型）时后面写「 · 类型 XxxProps」，名字带下标（⌘ + 点击跳到类型）。下面一张表格「名称 \| 类型 \| 默认值 \| 必填」，有属性带说明时多一列「说明」。没写参数时写「无」。说明里讲整个属性参数的 `@param props` 跟在这一行的值后面 |
+| 异常 | 说明里写了 `@throws` 才有，同函数块 |
+
+组件说明里的 `@param`：属性名对上的进「说明」一格（字段自己有注释的照旧用注释，没注释时才用它，Markdown）；写成 `props.title`（属性参数名.属性名）的也算，属性参数是解构写的时点号前面写的那个名字当它的名字。
+
+事件处理函数卡片：名称 / 说明（函数上面 JSDoc 的正文）/ 对不上的参数 / 参数（逗号隔开写在一行；说明里有参数对上了 `@param` 时排成「名称 \| 类型 \| 默认值 \| 说明」表）/ 返回（写了 `@return` 才有，值空着、后面跟说明）/ 异常 / 绑定事件。
 
 直接返回 JSX 的箭头函数组件（`const Tag = ({ text }) => <span>{text}</span>`）没有子块可放，它渲染的大纲作为第四行「JSX 结构大纲」写在组件卡片里。
 
@@ -1683,11 +1714,11 @@ react.component 23
 
 文件导入了对应 crate 才启用（来源等于 crate 名，或以 `crate::` 开头）。tokio 不单独做卡片，异步已经写在函数上。样例 `fixtures/rustLibs.rs`。
 
-- serde（`rules/serde.ts`，`libraries: ['serde']`）：`derive` 了 `Serialize` 或 `Deserialize` 的结构体。种类 `serde.struct`，标签「可序列化」，图标 `braces`，颜色同结构体（暗 #4ec9b0 / 亮 #267f99）。名称后面再标一个「可序列化」。`rename_all = "camelCase"` 收成选项「字段名改驼峰」。字段表多一列「序列化」：`rename` 写「改名 xxx」，`skip` / `skip_serializing` 写「不输出」，没标是「—」。
+- serde（`rules/serde.ts`，`libraries: ['serde']`）：`derive` 了 `Serialize` 或 `Deserialize` 的结构体。种类 `serde.struct`，标签「可序列化」，图标 `braces`，颜色同结构体（暗 #4ec9b0 / 亮 #267f99）。名称后面再标一个「可序列化」。`rename_all = "camelCase"` 收成选项「字段名改驼峰」。字段表多一列「序列化」：`rename` 写「改名 xxx」，`skip` / `skip_serializing` 写「不输出」，没标是「—」。说明里的 `@param` 同结构体对到字段表的「说明」列。
 - thiserror（`rules/thiserror.ts`，`libraries: ['thiserror']`）：`derive` 了 `Error` 的枚举。种类 `thiserror.error`，标签「错误」，图标 `triangle-alert`，颜色同异常（暗 #f14c4c / 亮 #cd3131）。变体表「变体 | 何时 | 展示」：何时是变体上面的文档注释，展示是 `#[error("…")]` 的文案。变体上的 `#[from]` 或 `#[source]` 在展示后面标「透传来源」。
-- axum（`rules/axum.ts`，`libraries: ['axum']`）：处理函数上的 `#[get("/path")]`、`#[axum::post(…)]` 等（get / post / put / delete / patch / head / options / trace），或顶层语句里 `Router` 的 `.route(路径, get(函数))`。函数已经标了路由属性时，这句 `route` 不再单独成卡。种类 `axum.route`，标签「接口」，图标 `globe`，颜色同 FastAPI 接口（暗 #61afef / 亮 #1a6fb5）。属性表：名称、说明、异步（是）、请求（一项「方法」、一项「路径」、路径里的 `{名字}` 对上参数写成「路径参数」，`Path(id): Path<Uuid>` 写 `id: Uuid`）、返回。
+- axum（`rules/axum.ts`，`libraries: ['axum']`）：处理函数上的 `#[get("/path")]`、`#[axum::post(…)]` 等（get / post / put / delete / patch / head / options / trace），或顶层语句里 `Router` 的 `.route(路径, get(函数))`。函数已经标了路由属性时，这句 `route` 不再单独成卡。种类 `axum.route`，标签「接口」，图标 `globe`，颜色同 FastAPI 接口（暗 #61afef / 亮 #1a6fb5）。属性表：名称、说明、异步（是）、请求（一项「方法」、一项「路径」、路径里的 `{名字}` 对上参数写成「路径参数」，`Path(id): Path<Uuid>` 写 `id: Uuid`）、参数（说明里写了 `@param` 才有：参数是 `Path(id)` 这类模式，不对名字，照写成「名称 \| 说明」表）、返回（`@return` 跟在后面）、异常（`@throws`）。
 - sqlx（`rules/sqlx.ts`，`libraries: ['sqlx']`）：`query!` / `query_as!` / `query_scalar!`。种类 `sqlx.query`，标签「查询」，图标 `database`，颜色暗 #ce9178 / 亮 #a31515。紧挨在前面的注释收成「说明」，不再单独成块。SQL 原文等宽，参数 `$1` 对上传入的表达式，`query_as!` / `query_scalar!` 的第一个实参是返回类型，`query!` 的返回类型是「—」。
-- tauri（`rules/tauri.ts`，`libraries: ['tauri']`）：`#[tauri::command]` 的函数。种类 `tauri.command`，标签「桌面命令」，图标 `square-function`，颜色暗 #e5c07b / 亮 #9a6a00。名称后面再标「桌面命令」。参数表「名称 | 类型 | 来源」：`State<…>` 是「窗口状态」，其余是「调用方传入」。
+- tauri（`rules/tauri.ts`，`libraries: ['tauri']`）：`#[tauri::command]` 的函数。种类 `tauri.command`，标签「桌面命令」，图标 `square-function`，颜色暗 #e5c07b / 亮 #9a6a00。名称后面再标「桌面命令」。参数表「名称 | 类型 | 来源」：`State<…>` 是「窗口状态」，其余是「调用方传入」；说明里的 `@param` 对上时多一列「说明」，`@return` 跟在「返回」后面，`@throws` 成「异常」表。
 
 ## 命令规则
 
@@ -1806,7 +1837,7 @@ shell 脚本大半是一条条命令，一条命令读成什么取决于命令
 
 语法包是 `@vscode/tree-sitter-wasm` 里的 `tree-sitter-rust.wasm`（和 python 的 wasm 同一层：包入口就在 `wasm/`）。`languageIds: ['rust']`。样例 `fixtures/rustLang.rs`、`fixtures/rustLibs.rs`、`fixtures/rustComments.rs`。原型是 `docs/prototype/code-reader/openpencil/exports/` 的 `rust-lang.png`、`rust-lib.png`、`rust-notes.png`。中文直译 `translators/rustZh.ts`：结构体不叫「类」，可见性不叫「访问级别」，`pub` 是「公开」。
 
-可见性：`pub` 公开，没写是本模块，`pub(super)` 父模块，`pub(crate)` 和 `pub(in …)` 本 crate。公开写在 `facts.access`，其余写在块的 `access` 属性上（筛选值 `module` / `super` / `crate`）。说明是紧挨在前面的文档注释（`///`、`/**`）的第一句，句号留着；连着几行的 `///` 算一段，中间可以隔着 `#[…]`。
+可见性：`pub` 公开，没写是本模块，`pub(super)` 父模块，`pub(crate)` 和 `pub(in …)` 本 crate。公开写在 `facts.access`，其余写在块的 `access` 属性上（筛选值 `module` / `super` / `crate`）。说明是紧挨在前面的文档注释（`///`、`/**`）正文的第一句，句号留着；连着几行的 `///` 算一段（`facts.doc` 是第一条，中文直译的 `docNodes` 往下连），中间可以隔着 `#[…]`。卡片（含 Rust 库规则的）都经翻译插件的 `doc`（规则经 `context.doc`）读说明，块标签拆开放：函数的 `@param` 进参数表的「说明」列、`@return` 跟在「返回」后面、`@throws` 成「异常」表，结构体的 `@param` 对到字段表的「说明」列，对不上的列成「对不上的参数」。
 
 注释和别的语言走同一条路（`listBlocks`，Rust 的 `CommentRules` 在 `languages/rust.ts`），文件顶层、`mod` 身体、`impl` 身体都一样：
 
@@ -1942,7 +1973,7 @@ interface BlockViewBase {
 
 /**
  * 属性表块（有 facts）和库规则认领的块只带 properties，其余块只带 translation（注释块是 `{ markdown }`）；没有翻译插件时是空数组。
- * 一行译文里有跨几行写的调用时 table 是摊开实参的表（TextTranslation.table），块带说明（TextBlock.doc）时 doc 是翻译插件给的 Markdown 原文（Translator.doc），
+ * 一行译文里有跨几行写的调用时 table 是摊开实参的表（TextTranslation.table），块带说明（TextBlock.doc）时 doc 是翻译插件读出的说明正文（Translator.doc 的 body），
  * webview 依次排在译文下面。
  */
 type BlockView = BlockViewBase & ({ translation: PreviewText, table?: PreviewTable, doc?: Markdown } | { properties: PropertyRow[] })
@@ -2035,6 +2066,8 @@ vscode/src/codeReader/
   rules/pythonTree.ts    Python 库规则共用的读语法树的办法（名字最后一节、字符串内容、调用的参数、别名、注解里的 X[...]、库里的名字）
   rules/segments.ts      库规则共用的拼属性表文字的办法
   rules/children.ts      库规则共用的挑子块的办法（成员连同紧挨在它前面的注释块、成员的说明节点）
+  docTags.ts             说明的原文按 KDoc 拆成正文和块标签（Doc：@param / @return / @throws），翻译插件的 doc 用它（纯函数）
+  rules/docRows.ts       讲说明的几行，中文直译和库规则共用：正文、对不上的参数、参数按名字对说明（paramDocs）、输出后面的 @return、异常表
   languages/shared.ts    语言插件共用的建树工具；异常类（withExceptions：按整份文件认异常类，类块换成异常块，并类属性、取构造参数）
   languages/typescript.ts  （call：调用的结构，new 是新建；TYPESCRIPT_EXCEPTIONS：认异常类的父类名、类字段、constructor）
   languages/python.ts    （iteration：推导式的结构；call：调用的结构；PYTHON_EXCEPTIONS：自带的异常类、类属性、__init__）
@@ -2125,7 +2158,8 @@ vscode/webview-ui/code-reader.html + src/codeReader/  预览界面（React，Vit
 - 输入参数表格：函数的「输入参数」行带列名 名称 / 类型 / 默认值（TS、Python 一样），默认值格子只有译文、没有就是空格子，别的行没有列名；webview 按有没有列名选表格还是列表，表格的格子按列数取，列宽模板（`tableTemplate`）只看列数。
 - 翻译：上面两张样例表逐字一致；属性名不被翻；每个被翻的词单独成段；节点模板嵌套时正确、槽位里照样翻、没命中模板的节点照抄；属性表里的值和一行译文用同一套表和模板。
 - `blockView`：`codeTokens` 拼起来等于 `code`；去缩进正确；函数、类、导入、常量、变量块只带属性表，其余块只带译文。
-- 注释的 Markdown：注释块、函数和类「说明」的视图数据是 `{ markdown }`，原文照抄（reST 角色、双反引号、JSDoc 标签、HTML 都不转换），行注释连成的块留得住缩进四格的代码块；渲染时 HTML 当文字、带协议的网址和邮箱成链接、不带协议的文件名不成链接，`javascript:` / `command:` / `./` / `..` / 绝对路径的链接和 http 图片不渲染，仓库内图片按原图比例显示，点了打开原图，没有就写「找不到图片」，仓库路径链接能点、点了打开文件并跳到符号；跳到定义不认 Markdown 里的名字。
+- 块标签：拆法（`docTags.test.ts`：多行续写、空行结束、`@returns` / `@exception` 同义、JSDoc 的 `{类型}`、`[名字=默认值]`、横杠、标签前后的正文、没有标签时原样、别的标签和围栏代码块里的行留在正文、异常名写成引用）；卡片（`translators/zhTemplate.test.ts` 的「说明里的块标签」）：`fixtures/conversationBrief.py`（luffy 的 `render_conversation_brief`）说明里没有 `@param` / `@return`，输入参数表「说明」列四个参数的原文，输出参数后面跟 `@return`；`fixtures/localRuntimeGate.py`（luffy 的 `gate.py`）「异常」表两行，第一行是完整链接、第二行是不带路径的引用；对不上的 `@param` 排在说明下面、提示色、悬停「没有这个参数」；类的 `@param` 照写成表、异常类的对到构造参数（`*args` 去掉星号对）。React 组件（字段没注释时用 `@param`、`props.x`、讲整个参数的跟在构造参数后面、对不上的、异常表）和事件处理函数（`rules/react.test.ts`）、FastAPI 请求表的说明列和响应后面的 `@return`（`rules/fastapi.test.ts`）、Rust 函数和结构体（`languages/rust.test.ts`）、数据类字段（`rules/dataclass.test.ts`）。
+- 注释的 Markdown：注释块、函数和类「说明」的视图数据是 `{ markdown }`，原文照抄（reST 角色、双反引号、`{@link}`、HTML 都不转换，块标签拆出去），行注释连成的块留得住缩进四格的代码块；渲染时 HTML 当文字、带协议的网址和邮箱成链接、不带协议的文件名不成链接，`javascript:` / `command:` / `./` / `..` / 绝对路径的链接和 http 图片不渲染，仓库内图片按原图比例显示，点了打开原图，没有就写「找不到图片」，仓库路径链接能点、点了打开文件并跳到符号；跳到定义不认 Markdown 里的名字。
 - 行替换：多行块替换后缩进正确。
 - 跳到定义：TS / Python 译文和属性表里的名字、点分模块名每一节、模块字符串带下标且指回源码原文，关键字、运算符、说明词不带（前面有中文注释也对得上）；查到的定义 → 不动 / 原地 / 预览 / 普通编辑器 / 挑选框；webview 里按下标找目标块、要展开的祖先块和属性行，滚动位置。闪哪一处（TS、Python 源码走完整的语言插件 + 翻译插件 + 视图数据）：参数 → 它那个子行，导入项 → 它那一项，多变量声明里的一个 → 它的名称行，类的泛型参数 → 「类型参数」那一行，函数名 / 类名 / 单个变量名（含解构模式）→ 整块，循环变量 → 所在的块，翻译插件没填 `defines` → 整块（照样展开属性行）；翻译插件给参数、导入项、声明的变量、泛型参数标的范围指回源码原文；块自己的名字只有函数、类和单变量声明有。
 - 高亮各处出现：段的源码范围和出现重叠才亮、边界相接不算、没下标的不亮，讲别处名字的段（`refers`）按那个名字算、自己照抄的位置不算（`occurrences.test.ts` 的 `sourceOf`），点分模块名每一节各按自己的范围认（真实的 Python 译文和属性表：定义处按写入、用到处按读取）；写入 → 强高亮色，读取、按文字 → 普通高亮色，同时碰上按写入；单击名字问、点空白处清、点按钮 / 链接 / 筛选栏不动、名字在按钮里照样问，拖选、双击第二下、带修饰键的点击不动，⌘ / Ctrl + 点击照旧发跳到定义、不问出现处；回答连同名字显示、空回答不亮、换名字时回答到前旧的留着、迟到的回答丢掉、答过「没有」再点照样再问、清掉后才到的回答丢掉、换文档版本或翻译清掉而同版本同翻译重发不清、没有文档时不问。键盘跳（`occurrences.test.ts`、`reveal.test.ts`、`editor/occurrenceNavigation.test.ts`）：回答照源码先后排、点中的那处是当前那一处、「2/5」和「N 处」；往后 / 往前、到头接着跳，找不到的跳过、总数照旧、一处都找不到不动，点中的不在回答里从点中的地方数起；只有当前那一处描框；能不能跳（高亮、焦点、输入框）第一次必报、之后变了才报；页面上找第一处显示着它的地方、要展开的块 / 属性行 / 子行、跳过筛掉 / 编辑 / 盖住的块、Markdown 不算；`package.json` 的两条命令、默认键、`when`、命令面板，扩展和页面的代码里不写键、不拦键，上下文键有一个预览能跳就真、变了才设，命令发给能跳的预览、没有就发给活动的；按键那一刻的位置跳转时回一次、隔太久 / 点过鼠标 / 没按过键不回，跳完守住跳到的位置、过了 `KEY_SCROLL_MS` 或又按键、点鼠标不守。