✨ feat(vscode): 代码阅读鼠标停在名字和注释链接上弹出定义所在那块的卡片，别的文件的也行
This commit is contained in:
cruldra committed
1 parent
bc7380c716
commit
a48b016d73
20 files changed
+1145
-89
No files matched your search
@@ -27,6 +27,7 @@
|
||||
| 变量、字段的说明 | Python 模块、类主体里紧跟在一条赋值后面的字符串（属性 docstring，PEP 257 / Sphinx 的写法）是这个变量的说明：常量、变量块进属性表「说明」一行（紧跟名称），字段块排在一行译文下面；不再单独成块，它的源码行算在这一块里，「编辑」时和赋值一起改 |
|
||||
| 注释按 Markdown 显示 | 注释块和函数、类、变量、字段的「说明」按 Markdown 渲染，像 Kotlin 的 KDoc：去掉注释符号、引号和共同缩进后的原文原样交给 Markdown，不按语言转换（reStructuredText 的 `:func:`、JSDoc 的 `@param` 都照抄，注释以后慢慢改成 Markdown 写法）；段内单个换行是软换行，空行分段；仓库内图片按原图比例显示，点了打开原图，没有就写「找不到图片」 |
|
||||
| 跳到定义 | 和普通编辑器一样 ⌘ / Ctrl + 点击名字跳到定义，定义由 VS Code 装的语言扩展（Pylance、TypeScript 语言服务……）查；目标语言有代码阅读就在预览里打开 |
|
||||
| 悬停看定义 | 和普通编辑器里的悬停一样：鼠标停在名字、注释里指到符号的链接上一会儿（VS Code 的 `editor.hover.delay`），弹出定义所在那块的卡片（别的文件的也行，和那个文件的预览画的是同一张），点卡片标题跳过去 |
|
||||
| 高亮名字的各处出现 | 和普通编辑器一样单击名字就高亮它在这个文件里的各处出现，由语言扩展按语义认（同名的别的东西不算），颜色用 VS Code 的单词高亮色，再用 focusBorder 色补一笔（当前那一处描框、别的画细线）；看不见的（折叠、筛掉的）点的时候不自动展开，筛选栏上写「名字 · 2/5」；⌘↓ / ⌘↑（可改绑的命令）在各处之间跳，跳到折叠着的地方会展开 |
|
||||
| 侧栏文件树 | 只看和打开：展开目录、打开文件、刷新、全部折叠，外加给目录 / 文件记注释、按审查工单只看 PR 改过的文件；不做新建 / 重命名 / 删除 |
|
||||
| 审查工单 | 标题栏第一个按钮「选工单」列出看板「审查」列的工单和「进行中」列里已经有 PR 的工单（按列分组），选中后树里只剩这张工单的 PR 改过的文件（目录层级照留、全部展开，按 M / A / D 着色，删掉的列出来但打不开）；点开的是本机这张工单的工作副本里 PR 最新的代码，不标差异、不开 diff；本机没有工作副本就拉 PR 分支建一个。弹框列的是看板上现在摆着的工单（不再加载一遍），选中后重读那张工单和它的 PR。见「审查工单」 |
|
||||
@@ -479,6 +480,7 @@
|
||||
- 问答同仓库路径链接（`useRepoLinks`、`RepoLinks`）：画出来后把页面上的仓库路径和引用一起发去问（`checkRepoLinks { paths, symbols }` → `repoLinksChecked { missing, unresolved }`），问到之前是普通链接，找不到的画成坏链接（红色波浪线，悬停「找不到」）；文档换了版本（收到 `document`）再问一次，引用跟着源码变。点了发 `openRepoLink`（不带 `path`，只带 `symbol`）：找到了同完整链接的后半段打开目标（语言有代码阅读的用预览、滚过去、闪，没有的用默认的打开方式选中名字），目标在这份文件里时在本预览里滚过去、闪一下（同跳到定义的闪）；找不到就标坏。
|
||||
- 样子：正文用界面字体（`--vscode-font-family`、`--vscode-font-size`）、comment 色、行高 20px，一行注释和一行译文一样高；行内代码用编辑器字体、`--vscode-textCodeBlock-background` 底；围栏代码块用编辑器字体和字号、同样的底，长行折行；段落、列表、代码块、表格之间 6px；标题只比正文稍大（h1 1.15em、h2 1.08em，其余同正文，加粗）；链接 `--vscode-textLink-foreground`；引用左边 3px `--vscode-textBlockQuote-border` 竖线、`--vscode-textBlockQuote-background` 底；表格 1px 细线。
|
||||
- 「编辑」状态照旧是源码，编辑写回不变；Markdown 里的名字（反引号里的代码）不能点，不参与跳到定义，能点的只有上面的链接和引用。
|
||||
- 定义卡片浮窗里的注释（别的文件的）按 `peek` 渲染（`TextPreview` 读 `MarkdownKindContext`）：不认不带路径的引用，别的同注释。
|
||||
|
||||
### 跳到定义
|
||||
|
||||
@@ -501,6 +503,17 @@
|
||||
- VS Code 里没有这种语言的定义提供者（shell）：语言扩展答不上时，同一文件里的名字由语言插件认（`LanguageAdapter.symbols`，见「Shell 脚本」），跳到用到的那处之前最近的定义。
|
||||
- 不按修饰键单击名字是高亮它的各处出现（见下一节）；⌘ / Ctrl + 点击名字不会触发块的编辑切换、折叠，也不动高亮。
|
||||
|
||||
### 悬停看定义卡片
|
||||
|
||||
- 能弹的：带源码下标的名字（同「跳到定义」能点的那些），和注释里指到符号的链接（带 `#类名` / `#类名.成员` 的仓库路径链接、不带路径的引用 `[Name]`、`[Class.member]`）；只指到文件、目录的链接不弹。不用按修饰键。
|
||||
- 什么时候弹（同 VS Code 编辑器里的悬停）：鼠标停在上面 `editor.hover.delay` 毫秒后问扩展端要卡片（扩展端按这份文件读 VS Code 的设置，语言自己的设置优先；`ready` 后发给页面，设置改了再发，页面不写死），没到时间就移开的作罢；回答带卡片才弹，没有就什么都不显示。同一时刻只有一个浮窗：指针在浮窗里时不弹别的，移到另一个名字、它有卡片时换成它的。只认最近一次询问的回答，迟到的丢掉。
|
||||
- 什么时候收：移开名字和浮窗两者 `editor.hover.hidingDelay` 毫秒后收（期间移进浮窗、移回名字就不收；从名字移向浮窗时扫过别的名字不把时间往后推）；Esc、滚动（页面或页面里能滚的框，浮窗自己里面滚不算）、在浮窗外按下鼠标、换了文档版本、跳到某处（`reveal`）立刻收；收了之后指针不离开这一处不再弹。
|
||||
- 卡片是哪块（扩展端，`editor/definitionPeek.ts` 的 `peekBlock`）：名字的定义同 ⌘ / Ctrl + 点击查的（规则标了引用的问规则，其余问语言扩展），几处定义取第一处；链接的符号同点这个链接时找的（`symbolTarget`：不带路径的引用按这份文件找，仓库链接在那个文件的文档符号里找）。定义处是哪块自己的名字（`defines`）就取那块，否则取编辑范围盖住定义那一行的最里层那块（参数、导入项、字段落在它们所在的块里），连同子块；挂在父卡片子行上的子块去掉 `slot`，在浮窗里是最外层那张。定义在这份文件里用最近发出去的那份文档的块（版本对不上就没有）；在别的文件就打开它，按它的语言、选中的翻译插件、库规则、项目入口排视图数据（同 `documentMessage`；规则查名字的定义、调用的种类不等，规则出的错不记，由那个文件自己的预览记）。没有卡片：查不到定义、目标语言没有代码阅读、解析失败、没有块盖住定义处、指着的名字就是定义本身（同一文件、定义处下标就是这个名字的）。
|
||||
- 中文名：同一文件的带上这个版本眼下已知的；别的文件只认起了中文名的定义本身（定义处标 `definition`，后面淡淡写原名），用到它们的各处要问语言扩展，浮窗不等。都只带卡片上画出来的名字（`namesOnCard`）。
|
||||
- 样子（`DefinitionPeekPopup.tsx`）：portal 到页面根上的浮窗，外框用 VS Code 悬停框的边框、底色、阴影（`--vscode-editorHoverWidget-*`）；标题一行「相对路径:行号」（路径从工作区文件夹算起，同挑选框），垫悬停框状态栏的底色、链接色，点了跳到定义（名字的同 ⌘ / Ctrl + 点击，发 `goToDefinition`；链接的同点链接，发 `openRepoLink`），浮窗跟着收。下面是卡片，卡片区最宽 640px、最高 420px，再大在里面滚。默认放在名字下方、左边对齐名字；下方放不下、上方空间更大就放上方，底边贴着名字往上长（卡片展开时不盖住名字）；宽高再限到那边剩下的空间，钳在视口内。层级低于悬停提示，浮窗里名字的提示照样盖在它上面。
|
||||
- 卡片只读：同页面上那张卡片（类、函数默认收起子块，能在浮窗里折叠展开，只记在浮窗里），块树不带编辑那部分（`BlockTreeState.edit`），没有编辑、问 AI、重写注释的按钮，不标差异、不筛选。浮窗里的名字下标是那个文件的，页面上管名字的几处都不认它们（浮窗根上标 `data-peek`）：不按 ⌘ / Ctrl 变链接、不能跳，单击不高亮也不清页面上的高亮，不画页面上的高亮，不再弹卡片；注释里不带路径的引用不成链接（引用按注释所在的文件找，页面只替自己这份文件问），仓库路径链接照样能点。
|
||||
- 按住 ⌘ / Ctrl 变链接、⌘ / Ctrl + 点击跳转、单击高亮各处出现都照旧；在浮窗外按下鼠标（单击名字、⌘ + 点击）先收起浮窗。
|
||||
|
||||
### 高亮名字的各处出现
|
||||
|
||||
- 能点的名字和「跳到定义」一样：带源码下标的段（属性表、一行译文、字典 / 对象各层子行的键和值，点分模块名每一节各算各的）。「编辑」状态的块里的源码、Markdown 里的名字不算，既不能点也不被高亮。
|
||||
@@ -1187,7 +1200,7 @@ export interface CommandRule {
|
||||
有些名字语言扩展查不到定义，只有懂这个库的规则知道它指向哪儿（Celery 任务表里的 `"commerce.cancel_timeout_pending_orders"` 是个字符串，指向工作区里某个 `@celery_app.task(name=…)` 装饰的函数）。规则可以把自己给的这种名字标成引用，自己查。别的库（路由名 → 处理函数、配置键 → 定义处……）照同样的办法用。
|
||||
|
||||
- 标：规则在属性表的段上填 `reference: { rule: 自己的 id, key: 规则自己认的键 }`，段照常带 `offset`（名字在源码里的位置，高亮各处出现、webview 认名字都用它）；规则要给 `resolve(key, workspace)`，异步返回各处定义（`RuleLocation`：文件 uri 和定义处那个名字的起止行列）。不合这几条时宿主当替身不合约定（见上面「出错」）。
|
||||
- 查：webview 不认引用，⌘ / Ctrl 悬停、点击照旧只报名字的下标（`probeDefinition` / `goToDefinition`）。扩展端记着最近发出去的那份文档里哪些下标是引用（只对那个文档版本有效），是引用的交给标它的规则的 `resolve`，其余照旧问语言扩展（`vscode.executeDefinitionProvider`）；两边查到的位置走同一条路：链接样子、一处原地滚 / 在预览里打开 / 普通编辑器打开、几处弹挑选框、闪「就是这处定义」的那块或那一行，都和「跳到定义」一节一样。规则注销了、`resolve` 出错时记日志，当作没有定义。
|
||||
- 查：webview 不认引用，⌘ / Ctrl 悬停、点击、悬停看定义卡片照旧只报名字的下标（`probeDefinition` / `goToDefinition` / `peekDefinition`）。扩展端记着最近发出去的那份文档里哪些下标是引用（只对那个文档版本有效），是引用的交给标它的规则的 `resolve`，其余照旧问语言扩展（`vscode.executeDefinitionProvider`）；两边查到的位置走同一条路：链接样子、一处原地滚 / 在预览里打开 / 普通编辑器打开、几处弹挑选框、闪「就是这处定义」的那块或那一行，都和「跳到定义」一节一样。规则注销了、`resolve` 出错时记日志，当作没有定义。
|
||||
- 在整个工作区里找：规则不能碰 VS Code，只描述一个 `WorkspaceIndex`（看哪些文件、便宜的文字预筛、从一份语法树里认出「键 → 定义处名字」），`resolve` 里调 `workspace.lookup(索引, 键)`。宿主（`workspaceIndex.ts`，VS Code 那一层在 `workspaceFiles.ts`）：
|
||||
- 第一次查时才建，同一个 id 只建一份，建的时候不挡预览（查的那一下等它建好）；
|
||||
- 按 `include` 在各工作区文件夹里找文件，`files.exclude`、`search.exclude` 里开着的和 `.venv`、`node_modules`、`__pycache__` 不看；自己是一份 checkout 的子目录（带 `.git` 文件或目录：子仓库、git worktree，例如 `.claude/worktrees/…` 里的副本，不然同一个任务会查到两处）整个不看，工作区文件夹自己的 `.git` 不算；`search.useIgnoreFiles` 开着时（默认开，和 VS Code 搜索一样）路上各层目录的 `.gitignore`、`.ignore` 忽略的不看——每层的规则相对那一层判断，哪一层忽略了就不看，下层不能把上层忽略的加回来；工作区文件夹上面的、全局的忽略文件和 `.git/info/exclude` 不读（VS Code 的 `search.useParentIgnoreFiles`、`search.useGlobalIgnoreFiles` 默认也不读）。插件声明的引擎版本（^1.97）的正式 API 里 `findFiles` 不能按忽略文件筛，所以忽略文件由宿主自己读（`workspaceScope.ts`）；文件改动时新建、改了的文件照同样的规则筛，改了忽略文件不会重扫已经建好的索引。每次读 32 份，预筛不过的不解析，用 `languageId` 的语言插件解析，语法树用完释放；
|
||||
@@ -1988,6 +2001,8 @@ type BlockView = BlockViewBase & ({ translation: PreviewText, table?: PreviewTab
|
||||
- `{ type: 'document', version, languageId, blocks: BlockView[], attributes: FileAttribute[], translators: { id, label }[], translatorId, error?: string, reveal?: Reveal, names: ShownName[] }`，文档每次变化（防抖 150ms）重发。`names` 是这个版本眼下已知的中文名（`{ offset, length, name, definition? }`：源码下标 [offset, offset + length) 的名字显示成 name，definition 是定义处本身），见「中文名」。`attributes` 是这份文件里出现过的筛选属性，按筛选栏的先后排：`{ id, name, values: { id, name, count }[] }`，名字取翻译插件的 `attributeNames`，没有的用 id。`reveal = { line, definition? }` 只随新预览的第一份文档走：从文本编辑器切过来时是它顶部那一行（滚到包含这行的块、顶到顶部，折叠的不展开）；跳到定义时还带 `definition`（定义处名字在源码里的下标），按「跳到定义」一节展开、滚动、闪。
|
||||
- `{ type: 'reveal', line, definition? }`：同上，发给已经开着的预览。页面正在重新加载（标签页切回来）时收不到，扩展端改成随它 `ready` 后的第一份文档带过去。
|
||||
- `{ type: 'definitionProbed', id, found }`：回答第 `id` 次 `probeDefinition`。
|
||||
- `{ type: 'definitionPeeked', id, peek? }`：回答第 `id` 次 `peekDefinition` / `peekLink`。`peek` 是 `{ path, line, block: BlockView, names: ShownName[] }`：定义所在的文件（从工作区文件夹算起）、定义处那一行（0 起）、那块卡片连同子块、卡片上显示成中文名的名字（下标是那个文件的）；没有卡片时不带。见「悬停看定义卡片」。
|
||||
- `{ type: 'hoverDelay', delay, hidingDelay }`：VS Code 的 `editor.hover.delay` / `editor.hover.hidingDelay`（毫秒，按这份文件读），`ready` 后发一次，设置改了再发。
|
||||
- `{ type: 'occurrencesFound', id, occurrences: { start, end, kind: 'text' | 'read' | 'write' }[] }`：回答第 `id` 次 `findOccurrences`，`[start, end)` 是源码下标，`kind` 同 `DocumentHighlightKind`；语言扩展没答就是空数组。
|
||||
- `{ type: 'moveOccurrence', step: 1 | -1 }`：两条命令发来，跳到下一处 / 上一处出现。
|
||||
- `{ type: 'displayNames', version, names: ShownName[] }`：version 这份文档里显示成中文名的名字，查到一步发一步；页面只收自己眼下这个版本的。
|
||||
@@ -2001,6 +2016,7 @@ type BlockView = BlockViewBase & ({ translation: PreviewText, table?: PreviewTab
|
||||
- webview → 扩展：
|
||||
- `{ type: 'probeDefinition', id, version, offset }`：按住修饰键指到带 `offset` 的名字上时问有没有定义，`id` 每问一次加一；`version` 不是当前文档版本就不答。
|
||||
- `{ type: 'goToDefinition', version, offset }`：修饰键 + 点击，按「跳到定义」一节跳。这两条都只带下标：扩展端按发出去的文档认出规则标了引用的下标交给规则查（见「规则自己查定义」），其余问语言扩展。
|
||||
- `{ type: 'peekDefinition', id, version, offset }`：鼠标停在带 `offset` 的名字上，要它的定义卡片；`id` 每问一次加一，`version` 不是当前文档版本就不答。`{ type: 'peekLink', id, path?, symbol }`：鼠标停在注释里指到符号的链接上，要那个符号的定义卡片（`path`、`symbol` 同 `openRepoLink`）。见「悬停看定义卡片」。
|
||||
- `{ type: 'findOccurrences', id, version, offset }`：单击带 `offset` 的名字，问它在这份文档里的各处出现；`id` 每问一次加一，`version` 不是当前文档版本就不答。
|
||||
- `{ type: 'occurrenceNavigation', available }`：眼下能不能用键盘在各处出现之间跳，页面加载后报一次、之后变了才报；扩展端按它设 `superpowers.codeReader.hasOccurrences`。
|
||||
- `{ type: 'checkRepoLinks', id, paths, symbols }`：页面上的仓库路径问哪些没有，不带路径的引用问哪些找不到（`id` 每问一次加一）。`{ type: 'openRepoLink', path?, symbol? }`：点了注释里的仓库链接（带 `path`）或不带路径的引用（只带 `symbol`）。见「注释的 Markdown 排版」。
|
||||
@@ -2147,11 +2163,12 @@ vscode/src/codeReader/
|
||||
editor/definitions.ts 查定义（vscode.executeDefinitionProvider）、规则查到的位置换成 VS Code 的、几处定义的挑选框
|
||||
editor/definitionSources.ts 名字的定义去哪儿查：文档里规则标的引用问规则，其余问语言扩展
|
||||
editor/definitionAction.ts 查到的定义 → 怎么跳（纯函数）
|
||||
editor/definitionPeek.ts 定义卡片取哪块（peekBlock）、卡片上带哪些中文名（namesOnCard、definitionSiteNames）
|
||||
editor/openTarget.ts 打开别的文件用哪种编辑器：语言有代码阅读的用预览（滚到定义处），其余用默认的打开方式（选中名字）；侧栏点文件、跳到定义、注释里的链接共用
|
||||
editor/occurrences.ts 查名字的各处出现（vscode.executeDocumentHighlights）
|
||||
editor/occurrenceNavigation.ts 跳到下一处 / 上一处高亮：命令、上下文键
|
||||
index.ts registerCodeReader(context): CodeReaderApi
|
||||
vscode/webview-ui/code-reader.html + src/codeReader/ 预览界面（React，Vite 第二个入口；块右上角的图标按钮在 BlockTools.tsx，悬停提示在 src/components/ui/tooltip.tsx（和看板共用，页面根上挂一次），块的概念图标（图标名 → 图标组件只在 kindIcons.tsx；内置种类 → 图标名在 contract.ts 的 KIND_ICONS，宿主写进概念列表）在 kindIcons.tsx，属性表在 PropertyGrid.tsx，子行排成表格还是列表在 subRows.ts，着色的词和框在 SegmentText.tsx，中文名换字在 displayNames.ts，Markdown 渲染在 markdown.ts / TextPreview.tsx（不带路径的引用的行内规则也在 markdown.ts），仓库链接和引用的点击、问坏没坏在 repoLink.ts / useRepoLinks.ts，筛选栏在 FilterBar.tsx，筛选规则在 filter.ts，编辑时盖住哪些块、点「编辑」退出哪些块在 editing.ts，高亮各处出现的规则在 occurrences.ts、接到页面上在 useOccurrences.ts，问 AI 的问答区在 AskThread.tsx、状态和规则在 qa.ts、贴图拖图的规则在 qaImages.ts、收发在 useQa.ts；代码差异：页面上怎么标（块 id、删掉的块挂哪、只看改动折哪几段、各处改动、上一处 / 下一处跳到哪）在 diffView.ts，筛选栏第二行和新文件横幅在 DiffBar.tsx，卡片里的增删在 DiffText.tsx（Markdown 的增删在 markdown.ts 的 renderMarkdownDiff），总览条在 OverviewRuler.tsx，跳到一处改动在 useChangeNav.ts）
|
||||
vscode/webview-ui/code-reader.html + src/codeReader/ 预览界面（React，Vite 第二个入口；块右上角的图标按钮在 BlockTools.tsx，悬停提示在 src/components/ui/tooltip.tsx（和看板共用，页面根上挂一次），块的概念图标（图标名 → 图标组件只在 kindIcons.tsx；内置种类 → 图标名在 contract.ts 的 KIND_ICONS，宿主写进概念列表）在 kindIcons.tsx，属性表在 PropertyGrid.tsx，子行排成表格还是列表在 subRows.ts，着色的词和框在 SegmentText.tsx，中文名换字在 displayNames.ts，Markdown 渲染在 markdown.ts / TextPreview.tsx（不带路径的引用的行内规则也在 markdown.ts），仓库链接和引用的点击、问坏没坏在 repoLink.ts / useRepoLinks.ts，悬停看定义卡片什么时候弹、收、放在哪在 definitionPeek.ts、接到页面上在 useDefinitionPeek.ts、浮窗和只读的卡片在 DefinitionPeekPopup.tsx，筛选栏在 FilterBar.tsx，筛选规则在 filter.ts，编辑时盖住哪些块、点「编辑」退出哪些块在 editing.ts，高亮各处出现的规则在 occurrences.ts、接到页面上在 useOccurrences.ts，问 AI 的问答区在 AskThread.tsx、状态和规则在 qa.ts、贴图拖图的规则在 qaImages.ts、收发在 useQa.ts；代码差异：页面上怎么标（块 id、删掉的块挂哪、只看改动折哪几段、各处改动、上一处 / 下一处跳到哪）在 diffView.ts，筛选栏第二行和新文件横幅在 DiffBar.tsx，卡片里的增删在 DiffText.tsx（Markdown 的增删在 markdown.ts 的 renderMarkdownDiff），总览条在 OverviewRuler.tsx，跳到一处改动在 useChangeNav.ts）
|
||||
```
|
||||
|
||||
## 测试
|
||||
@@ -2170,7 +2187,7 @@ vscode/webview-ui/code-reader.html + src/codeReader/ 预览界面（React，Vit
|
||||
- 块标签：拆法（`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 里的名字。不带路径的引用：行内规则（`webview-ui/.../markdown.test.ts`：`[Name]`、`[A.b]` 是 `symbol:` 链接，`` `[x]` ``、`items[i]`、`[会话进展]`、`[名字](路径)`、`[Agent](javascript:x)` 各自的结果，问 AI 的回答不认、带增删的注释照样认）；问答（`repoLink.test.ts`：`symbol:` 地址只认标识符、点了发不带 `path` 的 `openRepoLink`、和仓库路径一起问、找不到的标坏、打开成功不再标、同样的链接不再问、文档换了版本再问）；扩展端（`symbolLinks.test.ts`：本文件优先于导入且不问语言扩展、本文件的 `Class.member`、类有成员没有就是找不到、导入的名字问定义再在那个类底下找成员、整模块导入从顶层找、找不到；Python / TypeScript 各种导入写法引进来的名字和问定义的位置，`gate.py` 的导入）。
|
||||
- 行替换：多行块替换后缩进正确。
|
||||
- 跳到定义：TS / Python 译文和属性表里的名字、点分模块名每一节、模块字符串带下标且指回源码原文，关键字、运算符、说明词不带（前面有中文注释也对得上）；查到的定义 → 不动 / 原地 / 别的文件 / 挑选框，别的文件用哪种编辑器（`editor/openTarget.test.ts`：有代码阅读的用预览、带位置时滚到那一行闪定义处，没有的用默认的打开方式选中名字，打不开成文本的用默认的打开方式）；webview 里按下标找目标块、要展开的祖先块和属性行，滚动位置。闪哪一处（TS、Python 源码走完整的语言插件 + 翻译插件 + 视图数据）：参数 → 它那个子行，导入项 → 它那一项，多变量声明里的一个 → 它的名称行，类的泛型参数 → 「类型参数」那一行，函数名 / 类名 / 单个变量名（含解构模式）→ 整块，循环变量 → 所在的块，翻译插件没填 `defines` → 整块（照样展开属性行）；翻译插件给参数、导入项、声明的变量、泛型参数标的范围指回源码原文；块自己的名字只有函数、类和单变量声明有。
|
||||
- 跳到定义：TS / Python 译文和属性表里的名字、点分模块名每一节、模块字符串带下标且指回源码原文，关键字、运算符、说明词不带（前面有中文注释也对得上）；查到的定义 → 不动 / 原地 / 别的文件 / 挑选框，别的文件用哪种编辑器（`editor/openTarget.test.ts`：有代码阅读的用预览、带位置时滚到那一行闪定义处，没有的用默认的打开方式选中名字，打不开成文本的用默认的打开方式）；webview 里按下标找目标块、要展开的祖先块和属性行，滚动位置。悬停看定义卡片：取哪块（`editor/definitionPeek.test.ts`：Python 源码走完整的语言插件 + 翻译插件，类名 → 类那块连同子块，参数 → 所在的函数，变量 → 变量那块，块外面 → 没有，挂在子行上的子块去掉 `slot`；卡片上的中文名只带画出来的、长度对得上的，别的文件只认定义本身），什么时候弹、收（`definitionPeek.test.ts`：停够延迟才问、没到时间移开不问、没有卡片不弹、迟到的回答丢掉、链接问 `peekLink` 点标题发 `openRepoLink`、没收到延迟不弹、移开过 `hidingDelay` 才收、移进浮窗不收、扫过别的名字不往后推、浮窗里不弹别的、换成新名字的卡片、Esc / 滚动后不再弹、换文档版本收起；指到符号的链接才弹；放在下方 / 上方 / 空间大的那边、钳在视口内），只读的卡片（`DefinitionPeekPopup.test.tsx`：类收起子块、没有编辑 / 问 AI / 重写按钮、中文名用卡片带的、引用不成链接；`markdown.test.ts` 的 `peek`）。闪哪一处（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` 或又按键、点鼠标不守。
|
||||
- 中文名：
|
||||
- 语言插件认写法（`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 默认值参数；预筛和各方言的文件。
|
||||
|
||||
Reference in new issue
Block a user