🐛 fix(vscode): 写注释时改已有说明，不再在声明上面另插一行
This commit is contained in:
cruldra committed
1 parent
63dfb658e9
commit
7f39345d03
11 files changed
+196
-36
No files matched your search
@@ -635,14 +635,14 @@
|
||||
|
||||
### 重写注释
|
||||
|
||||
按写注释的技能（`/ecc:writing-code-comments`）给一块代码重写讲它的普通注释，没有就新写一段。
|
||||
按写注释的技能（`/ecc:writing-code-comments`）给一块代码重写它的说明。没有说明、但块前面有普通注释时换掉那段；都没有就按这门语言的说明新写一段。
|
||||
|
||||
- 按钮（`MessageSquareText` 图标，只有图标，悬停 / 读屏「按注释规范重写」，块还没有注释时是「按注释规范写注释」）：每块代码都有，不管卡片有没有「注释」一行都排在右上角那排按钮的最前面，依次是它、「问 AI」、「编辑」；文件开头的说明卡片也一样。正在重写时不能再点。定义卡片浮窗里、删掉的块没有；嵌着的代码里的块（Dockerfile RUN 里的 shell）、语言没给行注释记号（`LanguageAdapter.lineComment`）又还没有注释的块没有（`BlockView.commentTarget` 没有）。
|
||||
- 改哪儿（`BlockView.commentTarget`，扩展端 `blockView.ts` 算）：块前面挂着普通注释时换掉它们（从第一段开头到最后一段结尾，几段中间隔着的空行一起换掉，写成一段）；文件开头的说明卡片换掉它自己；块还没有前面的注释时新写一段，插在块的第一行（连同它的说明、装饰器）上面。说明（docstring、JSDoc、`///`）不动；挂在块后面、子块交上来的注释不动。
|
||||
- 按钮（`MessageSquareText` 图标，只有图标，悬停 / 读屏「按注释规范重写」，块还没有说明、也没有前面的普通注释时是「按注释规范写注释」）：每块代码都有，不管卡片有没有「注释」一行都排在右上角那排按钮的最前面，依次是它、「问 AI」、「编辑」；文件开头的说明卡片也一样。正在重写时不能再点。定义卡片浮窗里、删掉的块没有；嵌着的代码里的块（Dockerfile RUN 里的 shell）、语言既没有说明的写法（`LanguageAdapter.freshDoc`）也没给行注释记号（`LanguageAdapter.lineComment`）、又还没有可换的注释的块没有（`BlockView.commentTarget` 没有）。
|
||||
- 改哪儿（`BlockView.commentTarget`，扩展端 `blockView.ts` 算）：块已经有说明（Python 函数 / 类主体里第一条语句的 docstring、紧贴声明的 JSDoc、Rust 的 `///` / `//!`，以及别的语言记在块上的说明）时换掉这段说明的那几行，正文填回原来的定界符（`"""`、`/** */`、`///`），不在声明上面再插一行行注释；说明和块前面的普通注释都有时只换说明，普通注释留着。没有说明、块前面挂着普通注释时换掉它们（从第一段开头到最后一段结尾，几段中间隔着的空行一起换掉，写成一段）；文件开头的说明卡片换掉它自己。都没有时新写：Python 的函数或类在主体里插一段 docstring（缩进同主体，作为第一条语句；声明和主体写在同一行时从主体那一列拆开）；JavaScript / TypeScript 在声明紧上面插 `/** */`；Rust 在项紧上面插 `///`；只有行注释的语言（shell、Dockerfile）仍在块的第一行上面插一行行注释。挂在块后面、子块交上来的注释不动。
|
||||
- 问模型：同「问 AI」用 Claude Code 命令行、在这份文件所在的工作区文件夹里跑、用选的 profile、只读（`--tools Read,Grep,Glob`、`--allowedTools Read,Grep,Glob`、`--permission-mode dontAsk`、`--strict-mcp-config`：它能读那个文件，改不了，写回归扩展），从 stdin 发的只有一句：`/ecc:writing-code-comments <路径>:<起>-<止>`，路径相对 claude 的工作目录、用 `/` 分隔，行号 1 起，是这块代码的完整范围（连同挂在它上面的注释；文件开头的说明卡片是它自己那几行），别的不说（`commentRewrite.ts` 的 `commentRewritePrompt`）。文件有没保存的修改时不问（模型读的是磁盘上的文件），直接失败「先保存再重写注释」。
|
||||
- 结果按 JSON Schema 交（`--json-schema '{"type":"object","properties":{"body":{"type":"string"}},"required":["body"],"additionalProperties":false}'`）：模型调 Claude Code 的 `StructuredOutput` 工具交结果，result 行的 `structured_output.body` 是注释正文（不带注释符号）。不读模型的自由文字：只回了一段话、`structured_output` 没有或 `body` 是空的，都算失败，文件不动。
|
||||
- 过程（`rewriteProgress`）：问的那一句、正文逐字长出来（`--include-partial-messages` 时 `StructuredOutput` 的输入逐段来，按写到一半的 JSON 读出已经写出来的正文）、正在读什么（「读取 a.py」）；块下面同问答区的样子显示（`RewriteThread`），能叫停。
|
||||
- 写回（扩展端，`WorkspaceEdit`，能撤销）：换掉时套回原来那段注释的定界符和缩进（Python 三引号、`#` / `//` 行注释、`/* */` 块注释，`refillComment`；几段隔着空行的照第一段的写法）；新写时用语言的行注释记号（`#`、`//`）一行一行写，缩进同块的第一行，空行写成只有记号的一行。写之前核对这块代码的那几行和问的时候一样，变了就不写（「这块代码在重写期间变了」）；定界符认不出、编辑器没接受也不写。结束发 `rewriteEnd`（done / failed 带原因 / stopped），失败另弹一条错误提示。
|
||||
- 写回（扩展端，`WorkspaceEdit`，能撤销）：换掉时套回原来那段的定界符和缩进（Python 三引号、`#` / `//` / `///` / `//!` 行注释、`/* */` 块注释，`refillComment`；几段隔着空行的照第一段的写法）；新写时用这块说明的壳（docstring、`/** */`、`///`，或只有行注释的语言用 `#` / `//`）一行一行写，缩进同插入的那一行，空行写成只有记号的一行（docstring 的空行仍是空行）。写之前核对这块代码的那几行和问的时候一样，变了就不写（「这块代码在重写期间变了」）；定界符认不出、编辑器没接受也不写。结束发 `rewriteEnd`（done / failed 带原因 / stopped），失败另弹一条错误提示。
|
||||
|
||||
## 通用契约
|
||||
|
||||
@@ -990,8 +990,10 @@ export interface LanguageAdapter {
|
||||
toBlocks: (root: Node, source: string, languageId: string) => CodeBlock[]
|
||||
/** 给叶子节点定词性：源码着色用它，译文里照抄的词也按它着色、按它认出能查定义的名字。 */
|
||||
tokenRole: (leaf: Node) => TokenRole
|
||||
/** 行注释的记号（`#`、`//`）：「重写注释」给还没有注释的块新写一段时用它；不填就不能新写。 */
|
||||
/** 行注释的记号（`#`、`//`）：还没有说明、而这门语言的说明就是行注释时（shell、Dockerfile），「重写注释」用它新写一段；不填、又没有 freshDoc，就不能新写。 */
|
||||
lineComment?: string
|
||||
/** 还没有说明时新写的说明插在哪、用什么壳（正文占位 `_`）。不填就用 lineComment 写在块上面。 */
|
||||
freshDoc?: (block: CodeBlock) => { line: number, shell: string, breakAt?: number } | undefined
|
||||
/** node 是写在表达式里的遍历（推导式、生成器表达式）时给出它的结构，别的节点没有；没有这种写法的语言不填。 */
|
||||
iteration?: (node: Node) => IterationFacts | undefined
|
||||
/** node 是一次调用（含新建对象）时给出它的结构，别的节点没有；没给的语言不展开调用，照常一行译文。 */
|
||||
@@ -2038,12 +2040,12 @@ interface BlockViewBase {
|
||||
concepts: BlockConcept[] // 认出来的概念，从左到右；webview 按图标名画，不自己用种类查
|
||||
badge?: KindBadge // 库规则的卡片才有：筛选栏里这个种类的名字，卡片边框的颜色；图标在 concepts 里。和类块一样默认折叠
|
||||
slot?: { row: number, item: number } // 库规则挂在父卡片子行上的子块才有（RuleSlot）：挂在父卡片第 row 行的第 item 个子行上，点它才在这一行下面展开（它的块 id 记成折叠着就是收着）
|
||||
commentTarget?: CommentTarget // 「重写注释」写到哪（见「重写注释」）；嵌着的代码里的块、语言没给行注释记号又还没有注释的块没有，不给按钮
|
||||
commentTarget?: CommentTarget // 「重写注释」写到哪（见「重写注释」）；嵌着的代码里的块、语言没给出新写的办法又还没有注释的块没有，不给按钮
|
||||
children: BlockView[]
|
||||
}
|
||||
|
||||
/** 「重写注释」写到哪，行号 0 起：换掉块前面那几段普通注释（文件开头的说明卡片是它自己），或块还没有注释时新写在 line 这一行上面。 */
|
||||
type CommentTarget = { kind: 'replace', startLine: number, endLine: number } | { kind: 'insert', line: number }
|
||||
/** 「重写注释」写到哪，行号 0 起：换掉说明或块前面的普通注释（文件开头的说明卡片是它自己），或都没有时按 shell 新写在 line 这一行上面。 */
|
||||
type CommentTarget = { kind: 'replace', startLine: number, endLine: number } | { kind: 'insert', line: number, shell: string, breakAt?: number }
|
||||
|
||||
/**
|
||||
* 属性表块（有 facts）和库规则认领的块只带 properties（「注释」一行由宿主插在里面），其余块只带 translation（文件开头的说明是 `{ markdown }`）；没有翻译插件时是空数组。
|
||||
@@ -2247,7 +2249,7 @@ vscode/webview-ui/code-reader.html + src/codeReader/ 预览界面（React，Vit
|
||||
- `blockView`：`codeTokens` 拼起来等于 `code`；去缩进正确；函数、类、导入、常量、变量块只带属性表，其余块只带译文。
|
||||
- 块标签：拆法（`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`）。
|
||||
- 注释挂到它讲的块上（各语言的 `languages/*.test.ts`「注释挂到它讲的块上」，`outline` 的 `notes` 是挂着的各段注释在哪）：Python、TypeScript、Rust、Shell、Dockerfile 各一份，覆盖隔着空行的注释挂到后面那块、主体最后的挂到前面那块、主体里只有注释时挂到父块、文件最后的挂到最后一块、文件开头隔着空行的是文件的说明而紧挨着第一块代码的挂到它上面、`#!` / 写编码的 / `//!` / `@file` / 模块 docstring 是文件的、说明和注释并存、函数体里语句前面的注释；luffy 的 `fixtures/acquisitionRepository.py` 导入后面的注释挂到类上（`blockView.test.ts`：类卡片「名称、注释、访问级别」、编辑范围连着注释、写回原样）；TypeScript 的「名称、说明、注释」、几段注释是几段 Markdown、一行译文的卡片的 `rows`；嵌着的代码里的块没有 `commentTarget`；改了注释那块算修改、「注释」一行逐词标（`diff/blockDiff.test.ts`）；规则略去挂着注释的块不合约定（`libraryRules.test.ts`）。webview（`BlockTree.test.tsx`）：「注释」一行照属性表画，一行译文的卡片排在译文下面，有没有「注释」一行按钮都只有一个、排在右上角那排最前面，没有注释时叫「按注释规范写注释」，不能写注释的块没有按钮。
|
||||
- 重写注释（`commentRewrite.test.ts`、`qa/claudeAsk.test.ts`）：发给模型的就是 `/ecc:writing-code-comments 路径:起-止` 一句；读结构化结果（正文逐字长出来、读文件是在做的事、只回一段话没有正文、报错）；命令行在只读那套后面加 `--json-schema`、stdin 里只有那一句；交回结构化正文 → 换掉块前面几段注释（套回 `#` 和缩进）、文件开头的说明换它自己；没有注释的块新写一段插在上面（缩进同块，docstring 不动）；没交回正文、出错、重写期间代码变了 → 失败不写，叫停 → 不写；套回壳的几种写法（三引号、`#`、`/** */`、`//`）。
|
||||
- 重写注释（`commentRewrite.test.ts`、`qa/claudeAsk.test.ts`）：发给模型的就是 `/ecc:writing-code-comments 路径:起-止` 一句；读结构化结果（正文逐字长出来、读文件是在做的事、只回一段话没有正文、报错）；命令行在只读那套后面加 `--json-schema`、stdin 里只有那一句；交回结构化正文 → 已有说明换说明（Python docstring 填回三引号、JSDoc 填回 `/** */`，不在声明上面再插一行）、只有前面的普通注释时换掉那几段（套回 `#` 和缩进）、文件开头的说明换它自己、说明和普通注释都有时只换说明；都没有时 Python 函数在主体里插 docstring、TypeScript 在声明上面插 `/** */`、Rust 在项上面插 `///`、只有行注释的语言仍插在块上面；没交回正文、出错、重写期间代码变了 → 失败不写，叫停 → 不写；套回壳的几种写法（三引号、`#`、`/** */`、`//`、`///`）。
|
||||
- 注释的 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 里按下标找目标块、要展开的祖先块和属性行，滚动位置。悬停看定义卡片：取哪块（`editor/definitionPeek.test.ts`：Python 源码走完整的语言插件 + 翻译插件，类名 → 类那块连同子块，参数 → 所在的函数，变量 → 变量那块，块外面 → 没有，挂在子行上的子块去掉 `slot`；卡片上的中文名只带画出来的、长度对得上的，别的文件只认定义本身），什么时候弹、收（`definitionPeek.test.ts`：停够延迟才问、没到时间移开不问、没有卡片不弹、迟到的回答丢掉、链接问 `peekLink` 点标题发 `openRepoLink`、没收到延迟不弹、移开过 `hidingDelay` 才收、移进浮窗不收、扫过别的名字不往后推、浮窗里不弹别的、换成新名字的卡片、Esc / 滚动后不再弹、换文档版本收起；指到符号的链接才弹；放在下方 / 上方 / 空间大的那边、钳在视口内），只读的卡片（`DefinitionPeekPopup.test.tsx`：类收起子块、没有编辑 / 问 AI / 重写按钮、中文名用卡片带的、引用不成链接；`markdown.test.ts` 的 `peek`）。闪哪一处（TS、Python 源码走完整的语言插件 + 翻译插件 + 视图数据）：参数 → 它那个子行，导入项 → 它那一项，多变量声明里的一个 → 它的名称行，类的泛型参数 → 「类型参数」那一行，函数名 / 类名 / 单个变量名（含解构模式）→ 整块，循环变量 → 所在的块，翻译插件没填 `defines` → 整块（照样展开属性行）；翻译插件给参数、导入项、声明的变量、泛型参数标的范围指回源码原文；块自己的名字只有函数、类和单变量声明有。
|
||||
|
||||
Reference in new issue
Block a user