✨ feat(vscode): 代码阅读的词可以讲源码里别处的名字（Segment.refers）：FastAPI 路径里的 {user_id} 讲函数的参数，单击参数时跟着高亮，⌘ + 点击跳到参数

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

@@ -287,6 +287,7 @@
 
 - 能点的名字和「跳到定义」一样：带源码下标的段（属性表、一行译文、字典 / 对象各层子行的键和值，点分模块名每一节各算各的）。「编辑」状态的块里的源码、Markdown 里的名字不算，既不能点也不被高亮。
 - 单击名字：问扩展端（`vscode.executeDocumentHighlights`，文档 uri + 名字在源码里的位置），由语言扩展（Pylance、TypeScript 语言服务……）按语义答，同名的别的东西（例如同名的参数）不算。页面上源码范围和回答里任何一处重叠的段都高亮，一个名字被拆成几段（`luffy_agent.core.db`）时每段各按自己的范围认。
+- 讲别处名字的段（`Segment.refers`）：写在字符串里、语言扩展不认得的名字，库规则标出它讲的是源码里哪个名字（FastAPI 路径 `"/{user_id}"` 里的 `user_id` 讲的是函数的参数 `user_id`）。页面把这段当那个名字：单击问那个名字的各处出现，⌘ / Ctrl + 点击跳到那个名字的定义（参数本身），那个名字的某处出现盖住 `refers` 时这段也高亮（单击参数 `user_id` 时 URL、路由器接口表里的 `{user_id}` 一起亮）。只有一处认这件事：webview 的 `occurrences.ts` 的 `sourceOf`（段讲的是源码里哪一段名字：有 `refers` 取它，否则是照抄的位置），`data-offset`、高亮、当前那一处都按它；扩展端不用管。
 - 颜色和编辑器里一样：写入（定义、赋值，`DocumentHighlightKind.Write`）用 `--vscode-editor-wordHighlightStrongBackground`，读取和按文字认出的用 `--vscode-editor-wordHighlightBackground`；主题给了 `wordHighlightStrongBorder` / `wordHighlightBorder`（高对比主题）才描边，描边画在字框里面不挤动排版。同一段碰上两种按写入画。
 - 很多主题没配单词高亮色（例如 Gerry Oceanic），默认的灰底很淡，所以再用主题的 `--vscode-focusBorder` 补一笔（换什么主题都跟着主题走）：当前那一处（点中的、用键盘跳到的）在底色之外描一圈 1px 框；别的各处在底色下面画一条 1px 细线（内阴影，不占 `text-decoration`，⌘ 指着名字时的链接下划线照旧）。写入的那处照样是强高亮底色。框和线都画在字框里面，不挤动排版。
 - 看不见的出现（在折叠着的块、属性行、子行里，或块被筛掉）点的时候不自动展开；筛选栏右边、块数前面写「名字 · 2/5」（当前那一处是照源码先后排的第几处 / 回答里共几处，看不见的也算），名字取点中的那一段的文字；点中的名字不在回答里（没有当前那一处）时写「名字 · N 处」。之后自己展开，里面的出现照样亮着。
@@ -569,8 +570,10 @@ export type TokenRole =
  * 第三方翻译插件可以不填，不填就不能跳。
  * reference：只有库规则给的段有，这段讲的东西由规则自己查定义（LibraryRule.resolve），不问语言扩展；这样的段必须带 offset。
  * color：这段自己的颜色（暗色、亮色主题各一个），盖过词性的颜色：库规则按库自己的配色上色（FastAPI 的 HTTP 方法用 Swagger UI 的颜色）。
+ * refers：这段讲的是源码里别处的一个名字（那个名字的范围），语言扩展不认得这段自己的位置：写在字符串里的名字（FastAPI 路径里的参数名）。
+ * 预览把这段当那个名字：⌘ / Ctrl + 点击跳到它的定义，单击高亮它的各处出现，它的某处出现盖住 refers 时这段也高亮；offset 照旧是照抄的位置。
  */
-export interface Segment { text: string, role: TokenRole, offset?: number, reference?: RuleReference, color?: ThemeColor }
+export interface Segment { text: string, role: TokenRole, offset?: number, reference?: RuleReference, color?: ThemeColor, refers?: SourceRange }
 
 /** 框的样式，决定框头图标和框的颜色：'iteration' 是写在表达式里的遍历，图标、颜色同「循环」块。 */
 export type GroupStyle = 'iteration'
@@ -1038,7 +1041,7 @@ export interface CodeReaderApi {
 
 请求表：
 
-- URL：路由对象的 `prefix` 加装饰器的路径；`{参数}` 按 variable 色，其余按 string 色，都带源码下标；写的不是字符串（`prefix=settings.X`）交给翻译插件翻。
+- URL：路由对象的 `prefix` 加装饰器的路径；`{参数}` 按 variable 色（拆成 `{`、名字、`}` 三段），其余按 string 色，都带源码下标；花括号里的名字是函数的同名参数时标 `refers`（参数名的范围）：单击参数 `user_id` 时 URL 里的 `user_id` 跟着亮，⌘ + 点击 URL 里的 `user_id` 跳到参数；写的不是字符串（`prefix=settings.X`）交给翻译插件翻。
 - 方法：大写，颜色用 Swagger UI 的配色（段的 `color`）：GET #61affe、POST #49cc90、PUT #fca130、PATCH #50e3c2、DELETE #f93e3e（暗色）；白底上照原色看不清，亮色主题取同色相深一些的 #1b6ac9、#18834f、#b35f00、#0f8a70、#cf2020；HEAD #b36bff / #9012fe、OPTIONS #4b92e0 / #0d5aa7（Swagger UI 的 #9012fe、#0d5aa7 在暗底上看不清，暗色调亮了）；TRACE 没有配色，按 keyword 色。
 - 路径参数、查询参数、请求头、Cookie：`名称: 类型`，逗号隔开，名称 variable 色带下标，类型交给翻译插件翻（`Annotated[T, …]` 写 T）；没标注的只写名称。
 - 请求体：只有一个时写它的类型（模型名），几个时（表单的几个字段）写 `名称: 类型` 一串。
@@ -1379,7 +1382,7 @@ vscode/webview-ui/code-reader.html + src/codeReader/  预览界面（React，Vit
 - 注释的 Markdown：注释块、函数和类「说明」的视图数据是 `{ markdown }`，原文照抄（reST 角色、双反引号、JSDoc 标签、HTML 都不转换），行注释连成的块留得住缩进四格的代码块；渲染时 HTML 当文字、带协议的网址和邮箱成链接、不带协议的文件名不成链接，`javascript:` / `command:` / 相对路径的链接和图片不渲染；跳到定义不认 Markdown 里的名字。
 - 行替换：多行块替换后缩进正确。
 - 跳到定义：TS / Python 译文和属性表里的名字、点分模块名每一节、模块字符串带下标且指回源码原文，关键字、运算符、说明词不带（前面有中文注释也对得上）；查到的定义 → 不动 / 原地 / 预览 / 普通编辑器 / 挑选框；webview 里按下标找目标块、要展开的祖先块和属性行，滚动位置。闪哪一处（TS、Python 源码走完整的语言插件 + 翻译插件 + 视图数据）：参数 → 它那个子行，导入项 → 它那一项，多变量声明里的一个 → 它的名称行，类的泛型参数 → 「类型参数」那一行，函数名 / 类名 / 单个变量名（含解构模式）→ 整块，循环变量 → 所在的块，翻译插件没填 `defines` → 整块（照样展开属性行）；翻译插件给参数、导入项、声明的变量、泛型参数标的范围指回源码原文；块自己的名字只有函数、类和单变量声明有。
-- 高亮各处出现：段的源码范围和出现重叠才亮、边界相接不算、没下标的不亮，点分模块名每一节各按自己的范围认（真实的 Python 译文和属性表：定义处按写入、用到处按读取）；写入 → 强高亮色，读取、按文字 → 普通高亮色，同时碰上按写入；单击名字问、点空白处清、点按钮 / 链接 / 筛选栏不动、名字在按钮里照样问，拖选、双击第二下、带修饰键的点击不动，⌘ / Ctrl + 点击照旧发跳到定义、不问出现处；回答连同名字显示、空回答不亮、换名字时回答到前旧的留着、迟到的回答丢掉、答过「没有」再点照样再问、清掉后才到的回答丢掉、换文档版本或翻译清掉而同版本同翻译重发不清、没有文档时不问。键盘跳（`occurrences.test.ts`、`reveal.test.ts`、`editor/occurrenceNavigation.test.ts`）：回答照源码先后排、点中的那处是当前那一处、「2/5」和「N 处」；往后 / 往前、到头接着跳，找不到的跳过、总数照旧、一处都找不到不动，点中的不在回答里从点中的地方数起；只有当前那一处描框；能不能跳（高亮、焦点、输入框）第一次必报、之后变了才报；页面上找第一处显示着它的地方、要展开的块 / 属性行 / 子行、跳过筛掉 / 编辑 / 盖住的块、Markdown 不算；`package.json` 的两条命令、默认键、`when`、命令面板，扩展和页面的代码里不写键、不拦键，上下文键有一个预览能跳就真、变了才设，命令发给能跳的预览、没有就发给活动的；按键那一刻的位置跳转时回一次、隔太久 / 点过鼠标 / 没按过键不回，跳完守住跳到的位置、过了 `KEY_SCROLL_MS` 或又按键、点鼠标不守。
+- 高亮各处出现：段的源码范围和出现重叠才亮、边界相接不算、没下标的不亮，讲别处名字的段（`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` 或又按键、点鼠标不守。
 - 中文名：
   - 语言插件认写法（`languages/pythonNames.test.ts`、`languages/typescriptNames.test.ts`，真实解析）：Python 注解 `Annotated`（`typing.Annotated`、`t.Comment`，f-string、别的调用不算）、装饰器（函数、类）、行尾记号（多行参数表、`*args`、`self.x`、变量、字段、枚举成员，记号前面有别的字，记号的范围）、单独成行 / 那一行没有定义的不算、函数那一行给参数、docstring 的谷歌写法和 Sphinx 写法（带类型、星号、续行、别的段落不算）、第一小句和 12 个字的限制、明写的记号盖过说明文字、没取的记号照样去掉；TypeScript 装饰器（类、`@d export class`、字段、构造函数和方法的参数、方法隔着别的装饰器、名字最后一节）、行尾 `//` 记号（参数、变量、枚举成员、类字段、接口属性，块注释不算）、JSDoc `@param`（类型、短横、可选、属性不算、export 函数、方法、箭头函数变量、类字段）、JavaScript 默认值参数；预筛和各方言的文件。
   - 记号不是说明（`nameResolution.test.ts`，走 `readBlockViews`）：Python、TypeScript 枚举成员的行尾记号去掉、前面的字照留、只有记号的没有说明列。
@@ -1396,9 +1399,9 @@ vscode/webview-ui/code-reader.html + src/codeReader/  预览界面（React，Vit
 - Celery 规则：`fixtures/celeryApp.py` 的应用卡片和定时任务卡片逐字同上面的样例（列名、「12 条，另有展开 1 处」、行尾注释、条目里单独成行的注释、跨行的 `10⏎ * 60`、`每 get_settings().… 秒`、展开一行）；任务名是引用、下标指回源码原文；应用卡片的位置参数按参数顺序认、别的参数各一行、展开、属性 docstring、别名；没导入 celery、不是 `Celery(...)` 的不认；频率换算（秒数算式、`timedelta`、`crontab` 各种写法、`schedule`、换算不了的「每 X 秒」和照写法）；说明取哪些注释；条目名和任务名不同、没写任务名、任务名不是字符串、值不是字典、选项一列有才有；`conf.update(beat_schedule=…)`、不带 `beat_schedule` 的 `conf.update` 和 `autodiscover_tasks` 照常。任务名索引：显式 `name=`、默认「模块路径.函数名」（包、`src` 下的命名空间包、没有包）、`@shared_task` / `@shared_task()` / `@app.task` 不带括号 / 老写法 `@task`、`async def`、函数里的只认显式名字、`name=` 不是字符串的不认、同名几处都给、文件改了和新建 `__init__.py` 后跟着变、没有任务装饰器的文件不解析。
 - 枚举（`rules/enum.test.ts`、`languages/typescript.test.ts`）：`fixtures/enumModels.py` 的 `CommissionStatus` 逐字同上面的样例，`SecretScope` 的 docstring 当说明、没有说明列；种类 enum、叫「枚举」、访问级别同原来的类、没有标签（badge），编辑范围是整个类；Python 成员规则（dunder、sunder、私有名、`_ignore_`、lambda、`property`、`nonmember`、只写注解的不是成员，`auto()` 写「自动」，`member(x)` 取 x，说明取上面的注释块、行尾注释、属性 docstring，装饰器）；方法、嵌套类、不是成员的属性照源码顺序是子块，成员前面的注释并进来、最后面的留下，「编辑」写回整个类；类名、成员名的定义范围和带下标的词指回源码原文；没导入 enum、SQLAlchemy 的 `Enum`、不是枚举类型的父类不认，`import enum as e` 的 `e.IntEnum` 认。TypeScript：`enums.ts` 里 export / const / declare / 函数里的 enum 都是枚举块、JSDoc 进头部，写的值、自增算出的值（接不上数字就没有）、说明（上面的注释和 JSDoc、行尾注释，同一行的 JSDoc 讲下一个），访问级别；自增的值和「自动」按 hint。TypeScript 和 Python 同样的成员得到一样的种类、属性表行、列名和格子着色（除了 Python 多的「继承」）。宿主：规则认成现成属性表块时照语言插件报的这种块显示、并进来的不是子块时照常显示；webview 枚举块默认折叠。
 - 数据类（`rules/dataclass.test.ts`）：`fixtures/dataclassModels.py` 的 `SandboxAccess` 逐字同上面的样例，`AdminUserRow`、`RedirectPayResult`（`field(init=False, default=…)`）、`SmsSent`（`default_factory=dict`）的行；种类 `dataclasses.dataclass`、叫「数据类」、颜色、访问级别同原来的类；编辑范围是整个类、写回原样，`__post_init__` 是子块；类名、字段名的定义范围和带下标的词指回源码原文；装饰器的写法（别名、`dataclasses.dataclass`、`dc.dataclass`）认，pydantic 的、`other.dataclass` 不认，没导入 dataclasses 不认；每个选项的译法、默认值不讲、别的照写、`**x`、别的装饰器一行；字段规则（`ClassVar`、`typing.ClassVar` 留作子块，`InitVar` 的类型和「仅初始化时使用」，`KW_ONLY` 记号并进来、后面的字段「只能按名字传参」、单独写 `kw_only=False` 的「可按位置传参」），`field(...)` 的默认值、`default_factory`（名字、lambda）、各参数、`metadata` 照写、`doc=`，说明取上面的注释块、行尾注释、属性 docstring；没注解的类属性、字段中间的方法照源码顺序是子块，「编辑」写回整个类。
-- FastAPI 接口（`rules/fastapi.test.ts`）：`fixtures/routes.py` 的 `update_user` 逐字同上面的样例（查到 `Forbidden` 是 403 时四条消息写在一行，没查到时不列），名字、颜色、图标、列名、筛选属性、定义范围、编辑范围是整个函数、函数体是子块；着色（URL 的 `{参数}` / 路径、方法的 Swagger 颜色、成功的状态码绿色、自动带的 422 淡色，带下标的词指回源码原文）；`fixtures/skillHubRoutes.py` 的 `list_skills`（Annotated 里的 Query、`_` 的依赖）、`get_skill`（HTTPException 的 status_code / detail）、`install`（Request 不算、`-> None` 没有内容）；`fixtures/consoleRoutes.py` 的 `create_user`（`status_code=201`、Pydantic 模型、调别的函数间接抛的不算）、`list_users`（查到的类型别名 `FilterQuery` 是依赖、Literal 是简单类型）；参数放在哪儿的各条（路径里的名字含 `{x:path}`、各种标记两种写法、上传文件、枚举和类型别名查到的、Pydantic 模型、`Security`、`Depends()`）；标签、依赖、`responses=` 叠上路由对象的，`status.HTTP_…` 常量、`response_model=None`、`response_description`、`raise … from`、只写 `raise`、嵌套函数里的；`FastAPI()` 上的接口、别的装饰器一行；不认的（没导入、路由对象在别的文件、不是路由对象、`websocket`、不带括号）。跨文件（工作区索引 + 假的语言扩展）：`update_user` 的 `Forbidden` 按定义处查到 `core/exceptions/schemas.py` 的 403，同名的别处的类不算；索引认的类上的 `status_code`（带注解、常量）、枚举类、`Annotated` 类型别名，普通类不认。
+- FastAPI 接口（`rules/fastapi.test.ts`）：`fixtures/routes.py` 的 `update_user` 逐字同上面的样例（查到 `Forbidden` 是 403 时四条消息写在一行，没查到时不列），名字、颜色、图标、列名、筛选属性、定义范围、编辑范围是整个函数、函数体是子块；着色（URL 的 `{参数}` / 路径，花括号里的参数名 `refers` 到函数的参数，方法的 Swagger 颜色、成功的状态码绿色、自动带的 422 淡色，带下标的词指回源码原文）；`fixtures/skillHubRoutes.py` 的 `list_skills`（Annotated 里的 Query、`_` 的依赖）、`get_skill`（HTTPException 的 status_code / detail）、`install`（Request 不算、`-> None` 没有内容）；`fixtures/consoleRoutes.py` 的 `create_user`（`status_code=201`、Pydantic 模型、调别的函数间接抛的不算）、`list_users`（查到的类型别名 `FilterQuery` 是依赖、Literal 是简单类型）；参数放在哪儿的各条（路径里的名字含 `{x:path}`、各种标记两种写法、上传文件、枚举和类型别名查到的、Pydantic 模型、`Security`、`Depends()`）；标签、依赖、`responses=` 叠上路由对象的，`status.HTTP_…` 常量、`response_model=None`、`response_description`、`raise … from`、只写 `raise`、嵌套函数里的；`FastAPI()` 上的接口、别的装饰器一行；不认的（没导入、路由对象在别的文件、不是路由对象、`websocket`、不带括号）。跨文件（工作区索引 + 假的语言扩展）：`update_user` 的 `Forbidden` 按定义处查到 `core/exceptions/schemas.py` 的 403，同名的别处的类不算；索引认的类上的 `status_code`（带注解、常量）、枚举类、`Annotated` 类型别名，普通类不认。
 - 规则查别的文件里的定义（`ruleLookups.test.ts`）：第一遍当没查到、记下问了什么（同一索引同名的只记一处）；查到后叫重排，交出定义处正是的那一项；同一版本不再查；索引里没有同名的不问语言扩展，定义处不是索引里的项算没有，没变不叫重排；新版本先用上一版的、再查、变了才叫重排；语言扩展没答时已知的不动、隔一会儿再查。
-- 带自己颜色的词（webview `SegmentText.test.tsx`）：`cr-colored`，暗色、亮色写在 style 上。
+- 带自己颜色的词（webview `SegmentText.test.tsx`）：`cr-colored`，暗色、亮色写在 style 上；讲别处名字的段 `data-offset` 记那个名字的下标。
 - 异常（`languages/exceptions.test.ts`，真实解析 + 中文直译 + 视图数据）：`fixtures/appExceptions.py` 的 `AppException`、`NotFound` 逐字同「异常」的样例（列名随有没有类型、说明变），`GatewayTimeout` 的多段说明，方法是子块；`fixtures/commerceExceptions.py` 16 个类都是异常、只有说明的四行、写了 `__init__` 的构造参数；认哪些类（自带的异常类、`Warning`、不合后缀的自带类 `StopIteration` / `KeyboardInterrupt`、`pkg.errors.AppException`、同一文件里写在后面的父类一层层往下传、泛型和别的父类混写，关键字参数、`Mapping[...]`、`*bases` 不算，函数里的类也认）；类属性（带不带注解、只写注解、说明取上面的注释块 / 行尾注释 / 属性 docstring，连着赋值、解构赋值、方法、讲方法的注释、最后面的注释留作子块），构造参数去掉 self、`*args` 开头的不去；`@dataclass` 的异常类照样是异常卡片；编辑范围是整个类、改卡片写回整个类，类名、属性名、参数名的定义范围和带下标的词指回源码原文；TypeScript `fixtures/exceptions.ts.txt`（`extends Error`、类字段含 static、参数属性、JSDoc、写在后面的父类、类表达式、`ns.X<T>`，父类名不合习惯的照常是类）、JavaScript 的类字段；TypeScript 和 Python 同样的异常得到一样的行和列名；筛选的种类叫「异常」、没有 badge；属性的中文名和去掉行尾记号。webview：异常块默认折叠（`viewState.test.ts`），跳到类名闪整块、属性名 / 构造参数名只闪表里那一行（`reveal.test.ts`）。
 - 筛选：块的属性（TS、TSX 有抽象、仅类型，JavaScript / JSX 没有这两个属性、属性表也没有这两行，Python 有访问级别、异步）；语言插件自己报的属性叠上去、盖过推出来的，kind 不变；文件里出现过的属性按契约顺序排、语言的排后面，值按第一次出现排、带所有层的块数，名字取翻译插件的、没有的显示 id，中文直译的名字和属性表一致；下拉框只给两种以上值的属性（或一种值正被去掉的），按钮上的字；全选 / 取消全选只动这份文件里的值、别的文件的去掉状态和别的属性不动、取消全选藏掉有这个属性的块（整棵子树）、再全选全回来；同一属性内「或」、不同属性「且」、没有这个属性不受影响、藏整棵子树、「已隐藏」只数直接筛掉的；筛选记在 `workspaceState`、新实例读得回来、所有订阅的预览收到、形状不对的当没有；跳到被筛掉的块临时露出路径、目标的子块照常筛、文档刷新只留正在编辑的。
 - 文件注释：键相对工作区文件夹、`/` 分隔，根和外面的路径没有键，手写的 `./`、结尾 `/` 规范掉；保存去空白、清空即删；文件改名、目录挪位置里面各层一起走、名字只是前缀相同的不动、跨工作区文件夹先取出再放进去；删目录连带里面的；读写：文件缺失 / 解析失败 / 不是对象返回空表、跳过不合法条目、建 `.spx`、键排序、删光留 `{}`；有注释 / 没注释的行的描述、悬停提示（Markdown 转义）、contextValue，和 `package.json` 里菜单的 when 子句对得上。