diff --git a/docs/superpowers/specs/code-reader/spec.md b/docs/superpowers/specs/code-reader/spec.md
index 4fa4889..ee83cf2 100644
--- a/docs/superpowers/specs/code-reader/spec.md
+++ b/docs/superpowers/specs/code-reader/spec.md
@@ -25,7 +25,8 @@
 | 折叠 | 有子块的块、属性表里带子行的行、带下一层的子行（字典 / 对象里嵌套的字典 / 对象）能折叠；函数块（含方法、嵌套函数）、类块、枚举块、异常块和库规则的卡片默认收起主体、属性表照常显示，其余块、属性行和子行默认展开；用户点过的按他点的记住 |
 | 函数、类的说明 | TypeScript 紧贴在函数、类前面的 JSDoc，Python 函数、类主体开头的 docstring 是它自己的说明：进属性表「说明」一行，不再单独成一块注释；它的源码行算在函数、类块的头部里，「编辑」时和签名一起改 |
 | 变量、字段的说明 | Python 模块、类主体里紧跟在一条赋值后面的字符串（属性 docstring，PEP 257 / Sphinx 的写法）是这个变量的说明：常量、变量块进属性表「说明」一行（紧跟名称），字段块排在一行译文下面；不再单独成块，它的源码行算在这一块里，「编辑」时和赋值一起改 |
-| 注释按 Markdown 显示 | 注释块和函数、类、变量、字段的「说明」按 Markdown 渲染，像 Kotlin 的 KDoc：去掉注释符号、引号和共同缩进后的原文原样交给 Markdown，不按语言转换（reStructuredText 的 `:func:`、JSDoc 的 `@param` 都照抄，注释以后慢慢改成 Markdown 写法）；段内单个换行是软换行，空行分段；仓库内图片按原图比例显示，点了打开原图，没有就写「找不到图片」 |
+| 注释挂在它讲的块上 | 注释一定是讲某块代码的：普通注释（`#`、`//`、`/* */`、没挂成说明的文档注释、Python 当注释用的字符串）不单独成块，挂到它讲的那块上，是那张卡片的「注释」一行（排在名称、说明后面）；同一层里挂到后面最近的那块（中间隔空行也算），后面没有就挂到前面那块，这一层一块代码都没有就挂到父块。单独成块的只有文件开头的说明：第一块代码之前、和它隔着空行的注释，以及本来就讲整个文件的（Python 模块开头的 docstring、Rust 的 `//!`、JSDoc 的 `@file`）。块的编辑范围连同挂在它上面的注释。见「注释挂到它讲的块上」 |
+| 注释按 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」；⌘↓ / ⌘↑（可改绑的命令）在各处之间跳，跳到折叠着的地方会展开 |
@@ -152,7 +153,7 @@
 
 ### 预览（代码块树）
 
-- 每一句是一块：导入、函数、类、枚举、异常、类型、字段、常量、变量、条件、否则、循环、尝试、捕获、最终、返回、语句、注释；Shell 脚本另有解释器、选项、分情况、命令、管道（见「Shell 脚本」）；Dockerfile 另有解析指令、阶段、执行、复制、设置、标签、健康检查、启动（见「Dockerfile」）。
+- 每一句是一块：导入、函数、类、枚举、异常、类型、字段、常量、变量、条件、否则、循环、尝试、捕获、最终、返回、语句、文件开头的说明（种类「注释」）；Shell 脚本另有解释器、选项、分情况、命令、管道（见「Shell 脚本」）；Dockerfile 另有解析指令、阶段、执行、复制、设置、标签、健康检查、启动（见「Dockerfile」）。
 - 嵌套的块放在父块下面、往右缩进；每一层左边一条竖线（颜色 `--vscode-editorIndentGuide-background`）。
 - 块的组成（从左到右）：折叠箭头（只有有子块的块才显示，其余占位对齐）、概念图标、内容、右上角一排图标按钮。
 - 概念图标（原型 `kindBadge`、画板「Prototype / 块种类图标」）：块左边横排这块认出来的概念，各一个图标、不带字，和一行字等高（20px 的框，图形 16px，lucide 的线宽 2.2），间距紧。每个图标悬停自己的名字（`data-tooltip`，见下「悬停提示」）；整排是一个 `role="img"`，读屏把名字用顿号连起来念。和折叠箭头、内容同一行顶对齐。webview 不自己用种类查图标：图标名由宿主放进预览数据的概念列表（`BlockView.concepts`），webview 只按名字画（`kindIcons.tsx` 的 `KIND_ICON_COMPONENTS`）。
@@ -185,13 +186,14 @@
   这组图标由插件自己定义，是一个封闭的集合：契约里的 `KIND_ICON_NAMES`（上表 26 个——命令、管道、执行共用一个，解释器、解析指令共用一个，选项、设置、编译属性共用一个，字段、标签共用一个——加库规则用的 14 个（React 的组件、状态、引用、数据源、派生值、副作用、事件处理函数、渲染输出的 8 个也在里面），lucide 的 kebab-case 名字），类型 `KindIconName` 是它们的联合，概念的 `icon` 只能写其中一个，写别的是类型错误。内置种类 → 图标名在 `contract.ts` 的 `KIND_ICONS`（宿主写进概念列表）。webview 给每个名字配一个逐个 import 的 lucide 图标组件（`kindIcons.tsx` 的 `KIND_ICON_COMPONENTS`，打包只带这些，预览脚本约 157 kB）；webview 的 `KindIconName` 照契约手抄，`kindIconNames.test.ts` 核对两边一样。规则要新图标就把名字加进这组、在 webview 配上图标，没有按任意名字找图标的路。
 - 右上角的图标按钮（原型组件 `Reader / BlockTools`，普通块、属性表块、库规则的卡片共用）：只有图标、不带字，名字写在悬停提示和 `aria-label` 里；整排是 `role="group"`（`aria-label="块操作"`）。先是「问 AI」（sparkles 图标，点开 / 收起块下面的问答区，展开时带按下的底色、`aria-expanded`；文件不在工作区文件夹里时没有，见「问 AI」），再是「编辑 / 预览」切换：预览时铅笔「编辑」，编辑时眼睛「预览」、带按下的底色（`--vscode-toolbar-activeBackground`）。按钮宽 24px、高 20px（和种类图标同高），图标 14px、`descriptionForeground` 色；悬停 `--vscode-toolbar-hoverBackground`，键盘聚焦描 1px `--vscode-focusBorder`；Tab 能走到，回车 / 空格切换。
 - 悬停提示（整个插件的网页只走这一条路，预览和看板共用同一个组件）：带提示的元素只写 `data-tooltip="提示"`（名字照旧写在 `aria-label` 里，只有图标的按钮必须有 `aria-label`），页面根上挂一个 `TooltipHost`（`webview-ui/src/components/ui/tooltip.tsx`）统一弹，不用原生 `title`；提示里的换行照样换行（看板摘修复弹框里「迁移」列出的几个文件一行一个）；注释、回答里 Markdown 链接的标题（`[文字](网址 "标题")`）也写成 `data-tooltip`。网页的 TSX 里写原生 `title` 属性是 lint 错误（`vscode/eslint.config.mjs`），只有 `iframe` 这种必须带标题的元素例外，组件自己叫 `title` 的属性不算。原因：macOS 上 VS Code 带的 Electron（1.139 是 Electron 43）只在鼠标压着带 `title` 的元素自身边缘时才弹原生提示，停在它里面的图标、文字上不弹（electron/electron#49843，Electron 38 起），种类图标 20px 的框几乎被 16px 的图形占满，基本弹不出来；样子也是系统的。样子照 VS Code 的悬停框：`--vscode-editorHoverWidget-background` 底、`--vscode-editorHoverWidget-border` 边框、`--vscode-editorHoverWidget-foreground` 字、`0 2px 8px --vscode-widget-shadow` 阴影，11px 字，圆角 4px，最宽 22rem；优先在元素上方，上方放不下翻到下方，水平对着元素中间，贴边留 8px，不接鼠标。鼠标停 500ms 才弹，在同一个元素里移动不重新计时，已经弹着时移到另一个带提示的元素上立刻换；移开、移出页面、按下鼠标、按任意键（含 Esc）、滚动就收，收了之后鼠标不离开这个元素不再弹。键盘把焦点移到带提示的元素上（`:focus-visible`）立刻弹，焦点离开就收；提示不是元素自己的名字（`aria-label` 或它的字）时用 `aria-describedby` 挂到元素上，读屏当描述念。
-- 种类图标和底色按种类区分（颜色见「颜色」）；注释块虚线框。
+- 种类图标和底色按种类区分（颜色见「颜色」）；文件开头的说明（种类「注释」）虚线框。
+- 「注释」一行：讲这块的普通注释不单独成块，是这张卡片上的一行（见「注释挂到它讲的块上」）。属性表卡片（语言的、翻译插件排的、库规则的卡片都一样，宿主统一插，规则、翻译插件不用管）插在第一行（名称这类讲它是谁的一行）后面，有说明（值是 Markdown 的那一行）时插在说明后面，所以是「名称、说明、注释、别的」；一行译文的卡片（条件、循环、语句、调用、返回……）排在译文、摊开实参的表、说明的下面，同属性表的一行（左边「注释」、右边 Markdown）。名字是翻译插件给种类 comment 起的名字（中文直译「注释」）。几段注释（中间隔着空行、或前后两处）各是一段 Markdown，照源码顺序，空行隔开。按「注释的 Markdown 排版」显示（仓库路径链接、不带路径的引用、仓库图片都照常能点），标差异时同属性表的行逐词标。行上右边是「按注释规范重写」按钮（见「重写注释」）。
 - 内容两种状态，每块单独切：
-  - 预览：函数、类、枚举、异常、导入、常量、变量、解释器、选项、解析指令、阶段、健康检查、启动块是属性表（见下节），注释块是 Markdown 说明（见「注释的 Markdown 排版」），其余块是一行译文；按词着色，等宽字体（中文部分用系统中文字体回退）。一行译文里有跨几行写的调用时，摊开实参的表排在译文下面（见「调用与构造」）；块带说明（Python 字段的属性 docstring）时，说明按 Markdown 再排在下面。
-  - 编辑：这一块在源码里的完整代码（按语法树着色）：头部连同各子孙块、收尾括号，可以直接改，改完按这整段写回；蓝色边框。按钮换成眼睛「预览」；Esc 也回到预览。
-- 复合语句（函数、条件、循环……）块的预览只讲它自己的头部那几行（主体交给子块）；收尾括号、空行不成块。函数、类的说明（JSDoc / docstring）也算在函数、类块的头部里；Python 常量、变量、字段的属性 docstring 算在它那一块里（中间隔着的空行也是）。
-- 编辑范围是块的完整范围（`blockView.ts` 的 `blockSpans`，和语言无关）：从头部开头，到头部、整条语句、各子孙块里最靠后的那个字符。else、elif、catch 这类展平成兄弟块的子句，整条 if / try 按各块的开头切开：每块到下一块开头之前，最后一块到语句结尾（Shell 的 `fi` 归它）；`} else {` 写在一行时两块都含这一行。
-- 库规则认领的块（数据表卡片等，见「库规则」）：种类的图标、颜色和名字由规则给，内容是规则给的属性表；编辑范围同别的块，是原块整条语句（类就是整个类），「编辑」时整段一起改。规则没并进卡片的子块（方法、别的成员）不管写在类主体哪儿（两个字段中间也算），都照源码顺序是卡片的子块，点它们的「编辑」只改它们自己连同子孙那几行。
+  - 预览：函数、类、枚举、异常、导入、常量、变量、解释器、选项、解析指令、阶段、健康检查、启动块是属性表（见下节），文件开头的说明是 Markdown（见「注释的 Markdown 排版」），其余块是一行译文；按词着色，等宽字体（中文部分用系统中文字体回退）。一行译文里有跨几行写的调用时，摊开实参的表排在译文下面（见「调用与构造」）；块带说明（Python 字段的属性 docstring）时，说明按 Markdown 再排在下面；块挂着注释时「注释」一行排在最下面。
+  - 编辑：这一块在源码里的完整代码（按语法树着色）：挂在它上面的注释、头部连同各子孙块、收尾括号，可以直接改，改完按这整段写回；蓝色边框。按钮换成眼睛「预览」；Esc 也回到预览。
+- 复合语句（函数、条件、循环……）块的预览只讲它自己的头部那几行（主体交给子块）；收尾括号、空行不成块。挂在块上的注释算在块的完整范围里（写在块上面的从注释开头算起，挂在这一层最后一块上的、子块交上来的到注释结尾）：差异、跳过去、钉住卡片、总览条、「只看改动」、按行找块都按它，注释那几行改了标的是它挂着的那块。函数、类的说明（JSDoc / docstring）也算在函数、类块的头部里；Python 常量、变量、字段的属性 docstring 算在它那一块里（中间隔着的空行也是）。
+- 编辑范围是块的完整范围（`blockView.ts` 的 `blockSpans`，和语言无关）：从头部和挂在它上面的注释里最靠前的开头，到头部、整条语句、挂在它上面的注释、各子孙块（连同它们的注释）里最靠后的那个字符。else、elif、catch 这类展平成兄弟块的子句，整条 if / try 按各块的开头（连同挂在它上面的注释）切开：每块到下一块开头之前，最后一块到语句结尾（Shell 的 `fi` 归它）；`} else {` 写在一行时两块都含这一行。
+- 库规则认领的块（数据表卡片等，见「库规则」）：种类的图标、颜色和名字由规则给，内容是规则给的属性表（宿主再插「注释」一行）；编辑范围同别的块，是原块整条语句（类就是整个类）连同挂在它上面的注释，「编辑」时整段一起改。规则没并进卡片的子块（方法、别的成员）不管写在类主体哪儿（两个字段中间也算），都照源码顺序是卡片的子块，点它们的「编辑」只改它们自己连同子孙那几行。
 - 同一行不会同时在两处能改：一块在编辑时它的子孙都不画（代码都在它的编辑框里），回到预览就照原样出来；点一块的「编辑」时，编辑范围和它重叠的别的块（祖先、子孙、共用一行的兄弟块）退出编辑。跳到定义的目标块正被盖住时闪盖住它的那块。
 - 折叠：函数、类、枚举、异常块和库规则的卡片打开时默认收起子块（属性表照常显示），其余块默认展开；用户点过折叠箭头的块按他点的，记在视图状态里（见「预览数据与消息」）。
 - 顶部筛选栏：见「筛选」；翻译下拉框（多于一种翻译时才显示）也在栏里。
@@ -207,6 +209,7 @@
   3. webview 只按属性 id / 值 id 筛，显示翻译插件给的名字。
 - 下拉框：这份文件里有两种以上值的属性各一个（只有一种值的不给——筛它等于按种类筛）；只有一种值、但这个值正被去掉的也给，不然藏起来的块在栏上找不到原因。排列：通用属性按契约的顺序（种类、访问级别、异步、抽象、仅类型），语言自己的属性按在文件里第一次出现的先后排在后面。下拉菜单顶上一行「全选 · 取消全选」，分隔线下面是勾选列表，列出这份文件里出现的值（按第一次出现的先后）和各有几块（所有层的块都算，例如「私有 3 / 公共 3」）。
 - 全选 / 取消全选：把这份文件里这个属性出现的值一起勾上 / 去掉，和逐个勾一样记下来；别的文件才有的值记着的去掉状态不动（筛选整个工作区共用）。取消全选后有这个属性的块全藏起来，没有这个属性的照常显示；菜单不关，可以接着勾。
+- 种类「注释」只剩文件开头的说明：挂在块上的注释跟着它的块显示、藏起来，按种类去掉「注释」只藏文件开头的说明（文件里没有时这个值不出现）。
 - 规则：同一属性里勾着的值满足一个就显示，不同属性要同时满足；块没有某个属性就不受那个属性的筛选影响（条件、返回块没有访问级别，按访问级别筛时照常显示）；块被筛掉，连同它的子块一起藏，不留空位，层级竖线跟着变短；子块都被筛掉的块不给折叠箭头。
 - 汇总：什么都没筛掉时右边写「共 N 块」（N 是整份文件所有层的块数）；筛掉了写「已隐藏 N 块 · 清除」，N 只数直接被筛掉的块，跟着藏起来的子块不算；点「清除」整份筛选清空。页面上一块都不剩时写「所有块都被筛选隐藏了。」
 - 下拉框上的字：没去掉值时是属性名；去掉了（边框换 `--vscode-focusBorder`）勾着一种写「访问级别：公共」，几种写「种类：已选 11 种」，一种都不勾写「种类：未选」。
@@ -286,9 +289,9 @@
   - TypeScript / JavaScript：`extends` 后面的类名（`X`、`ns.X` 取 X，泛型实参不看；`Mixin(Base)` 这类调用不看）以 `Error` 或 `Exception` 结尾。自带的 `Error`、`TypeError`、`RangeError`、`AggregateError`……都以 Error 结尾，`DOMException` 以 Exception 结尾，不用另列。
   - 两种语言都算：父类是同一文件里认出来的异常类，按名字认，不论写在前面还是后面、嵌套在哪，一层层往下传（`class Deeper(Late)`、`class Late(Base)`、`class Base(Exception)` 三个都是）。
 - 按命名习惯认的部分和它的限制：父类从别的文件导入时语言插件看不到那个文件，只能按名字认（PEP 8 要求异常类名以 Error 结尾，`AppException` 这种以 Exception 结尾的也常见）。所以父类名不合习惯（从别处导入的 `NotFound`、`Forbidden` 当父类）的认不出来，照常是类块；名字合习惯却不是异常的父类（普通类起名 `RenderError`）会被当成异常。同一文件里按名字认，不看作用域（同名的两个类当成一个）。
-- 类属性（进「属性」表）：Python 是类主体里给一个名字赋值的语句（`x = 1`、`x: int = 1`、只写注解的 `x: int`），连着赋值（`a = b = 1`）、解构赋值不算；TypeScript / JavaScript 是类字段（`public_field_definition` / `field_definition`，含 static；值是带语句块主体的函数、类表达式的照常是方法、类块）。说明同枚举成员：紧挨在上面的注释块、这一行行尾的注释、Python 紧跟在后面的属性 docstring，原文用空格连起来。类 docstring 里谷歌写法的 `Attributes:` 一节照原文留在「说明」里，不拆到各属性的说明格子。
+- 类属性（进「属性」表）：Python 是类主体里给一个名字赋值的语句（`x = 1`、`x: int = 1`、只写注解的 `x: int`），连着赋值（`a = b = 1`）、解构赋值不算；TypeScript / JavaScript 是类字段（`public_field_definition` / `field_definition`，含 static；值是带语句块主体的函数、类表达式的照常是方法、类块）。说明同枚举成员：讲它的注释（挂在它上面的）、这一行行尾的注释、Python 紧跟在后面的属性 docstring，原文用空格连起来。类 docstring 里谷歌写法的 `Attributes:` 一节照原文留在「说明」里，不拆到各属性的说明格子。
 - 构造参数：Python 是 `__init__` 的参数去掉第一个（self；第一个是 `*args` 这类时不去），TypeScript / JavaScript 是 `constructor(...)` 的参数（参数属性 `public code?: string` 也是一个参数）；写了几个取最后一个（重载的实现写在最后）。`*`、`/` 分隔符同函数的输入参数，不算参数。类里没写构造函数（继承父类的）时没有这一行。
-- 并进属性表的子块：各个类属性连同紧挨在它前面的注释块；构造函数、方法、别的语句、讲方法的注释、最后面的注释照常是子块（不管写在哪），默认收起。异常块的头部（编辑范围）是整个类：从说明、装饰器开始，到类连同各子块的最后一行，「编辑」时整段一起改，盖住留下的子块（同库规则的卡片）。
+- 并进属性表的子块：各个类属性（讲它的注释挂在它上面，跟着并进来，是这个属性的说明）；构造函数、方法、别的语句照常是子块（不管写在哪，讲它们的注释是它们卡片的「注释」一行），默认收起。异常块的头部（编辑范围）是整个类：从说明、装饰器开始，到类连同各子块的最后一行，「编辑」时整段一起改，盖住留下的子块（同库规则的卡片）。
 - 语言插件报的已经是异常块，库规则只认类块，所以异常类不交给库规则：`@dataclass` 装饰的异常类照样是异常卡片，`@dataclass` 写在「装饰器」一行，注解的字段在「属性」表里。
 - 跳到定义：类名是块自己的名字（闪整块），属性名只闪「属性」表里那一行，构造函数的参数只闪「构造参数」表里那一行（构造函数自己的「输入参数」也标了同一个参数，页面上先找到的是卡片里这一行）；中文名（`Annotated[…, Comment("…")]`、行尾 `# @Comment …`）照常换属性格子里的名字，行尾记号不进说明。
 
@@ -470,9 +473,9 @@
 
 ### 注释的 Markdown 排版
 
-- 用在：注释块（`#`、`//`、`/* */`、不挂在函数、类上的 JSDoc、Python 模块开头的 docstring 和别的当注释用的单独字符串）的预览，函数、类、常量、变量属性表的「说明」，参数表的「说明」列、「异常」表、输出参数后面的 `@return`，字段译文下面的说明。视图数据里它们是 `{ markdown }`（见「通用契约」的 `Markdown`），webview 按数据决定怎么渲染，不猜。
+- 用在：卡片的「注释」一行（`#`、`//`、`/* */`、没挂成说明的 JSDoc、Python 当注释用的单独字符串）、文件开头的说明（同样的注释，和 Python 模块开头的 docstring、Rust 的 `//!`）的预览，函数、类、常量、变量属性表的「说明」，参数表的「说明」列、「异常」表、输出参数后面的 `@return`，字段译文下面的说明。视图数据里它们是 `{ markdown }`（见「通用契约」的 `Markdown`），webview 按数据决定怎么渲染，不猜。
 - 原文：翻译插件去掉注释符号（`#`、`//`、`/*` `*/` 和每行开头的 `*`）、引号和中文名记号（`SourceDocument.markers`，见「中文名」），再去掉行尾空白、首尾空行和共同缩进，保留换行，不做别的转换。一个注释节点（块注释、docstring）的第一行紧跟在注释符号 / 引号后面，不参与算共同缩进（同 PEP 257）；几条行注释连成的一块每行地位相同，第一行也算，缩进四格的代码块才留得住。
-- 块标签：说明（`Translator.doc` 读的：函数、类这些定义的说明，字段、成员的说明，库规则取的说明）的原文按 KDoc 拆成正文和块标签（`Doc`，解析在 `docTags.ts`，各卡片共用）；单独成块的注释照原文显示，不拆。
+- 块标签：说明（`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`）留在正文里。
@@ -482,7 +485,7 @@
 - 安全：源码里的 HTML 当文字显示；链接认 http / https / mailto，带协议的网址和邮箱自动成链接（`sample.py` 这种不带协议的不算），别的写法（`javascript:`、`command:`、`./`、`..`、绝对路径、盘符）照原文显示。http / https / mailto 由 VS Code 的 webview 自己拦下、交给宿主在外部打开，不用另发消息。http / https 图片不渲染（webview 的 CSP 不放行外部图片），`![alt](url)` 显示成 `!` 加链接。仓库内图片按原图比例显示，点了打开原图，没有就写「找不到图片」和路径。
 - 仓库路径链接（`[名字](从仓库根起的路径)`，可带 `#类名` 或 `#类名.成员`）能点，点了打开文件并跳到符号，和 ⌘ / Ctrl + 点击跳到别的文件里的定义是同一条路（`editor/openTarget.ts` 的 `openingFor`，见「跳到定义」）：语言有代码阅读的在预览所在的编辑器组用预览打开、滚过去、闪符号那处（不带符号的只打开预览），没有代码阅读的用 VS Code 默认的打开方式（普通编辑器选中符号的名字，图片看图）；指到这份文件里的符号时在本预览里滚过去、闪一下（同下面的引用）。指到目录的在代码阅读侧栏的树上定位（展开并选中，和侧栏跟着当前文件走是同一个定位；侧栏没露着时亮出来），不切到 VS Code 资源管理器；树上没有（开着筛选时没摆它）时提示「侧栏的树上没有 …」，不退出筛选。
 - 不带路径的引用（KDoc 的 `[Name]`、`[Class.member]`）能点：
-  - 认哪些：只在注释的 Markdown 里认（说明正文、参数说明、`@return`、「异常」表、单独成块的注释，连带增删的；问 AI 的回答不认）。方括号里是标识符（ASCII 字母、数字、下划线、`$`，点分开的几段）；中文这类不是标识符的（`[会话进展]`）照原样是文字。反引号里的是代码；紧跟在名字、`]`、`)` 后面的方括号是下标（`items[i]`、`a[0][1]`、`f()[k]`）；后面紧跟 `(…)` 的是完整链接、紧跟 `[` 的是参考式链接，都不算。webview 在 `markdown.ts` 加一条行内规则（排在 markdown-it 的 link 后面，渲染时 `env.symbolLinks` 为真才认），写成地址为 `symbol:名字` 的链接（作者写不出这种地址，`validateLink` 不放行）。
+  - 认哪些：只在注释的 Markdown 里认（说明正文、参数说明、`@return`、「异常」表、「注释」一行、文件开头的说明，连带增删的；问 AI 的回答不认）。方括号里是标识符（ASCII 字母、数字、下划线、`$`，点分开的几段）；中文这类不是标识符的（`[会话进展]`）照原样是文字。反引号里的是代码；紧跟在名字、`]`、`)` 后面的方括号是下标（`items[i]`、`a[0][1]`、`f()[k]`）；后面紧跟 `(…)` 的是完整链接、紧跟 `[` 的是参考式链接，都不算。webview 在 `markdown.ts` 加一条行内规则（排在 markdown-it 的 link 后面，渲染时 `env.symbolLinks` 为真才认），写成地址为 `symbol:名字` 的链接（作者写不出这种地址，`validateLink` 不放行）。
   - 指到哪（扩展端，`symbolLinks.ts` 的 `resolveReference`，按 KDoc 的规矩）：① 本文件定义的：文档符号（`vscode.executeDocumentSymbolProvider`，同仓库链接找符号那一套）顶层名字对上的（类、函数、常量、变量；落在导入语句里的名字不算），`Class.member` 在它底下找成员；② 本文件导入进来的：名字（`Class.member` 的第一段）是某条导入引进来的（预览已有的导入块 facts，`ImportFacts.items`：起了别名的按别名认，问原来那个名字；整模块导入按第一节认，起了别名的问最后一节），在导入语句里这个名字的位置上问语言扩展定义在哪（`vscode.executeDefinitionProvider`，同跳到定义，几处取第一处），`Class.member` 再在目标文件的文档符号里找：定义落在哪个符号里就在它底下找，落在文件开头（导入的是模块）就从顶层找；③ 都没有就找不到。本文件定义了这个名字、却没有这个成员时也算找不到，不再去导入里找。
   - 问答同仓库路径链接（`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 细线。
@@ -618,7 +621,7 @@
 
 块的位置记号（`BlockView.anchor`，`qa/anchor.ts`）：
 
-- 扩展端生成视图数据时按源码先后逐块给：有名字的块（`defines` 的来源：函数名、类名、枚举名、单个变量名，库规则卡片取规则给的定义范围）是外层各个有名字的块加自己的「种类 名字」，例如 `class ReferralRelation > function display`；没名字的块（条件、语句、返回、注释、导入、多变量声明……）是外层最近的有名字的块加「种类 @源码哈希」，哈希是这块头部那几行（库规则认领的块是整条语句）去掉所有空白后的 SHA-1 前 8 位，改它的子块不影响它的记号，例如 `function display > if @3fa1c2d0`。同一层里记号相同的（同名的两个函数、一模一样的两行语句）按源码先后在后面补 `[1]`、`[2]`。
+- 扩展端生成视图数据时按源码先后逐块给：有名字的块（`defines` 的来源：函数名、类名、枚举名、单个变量名，库规则卡片取规则给的定义范围）是外层各个有名字的块加自己的「种类 名字」，例如 `class ReferralRelation > function display`；没名字的块（条件、语句、返回、文件开头的说明、导入、多变量声明……）是外层最近的有名字的块加「种类 @源码哈希」，哈希是这块头部那几行（库规则认领的块是整条语句）去掉所有空白后的 SHA-1 前 8 位，改它的子块不影响它的记号，例如 `function display > if @3fa1c2d0`。同一层里记号相同的（同名的两个函数、一模一样的两行语句）按源码先后在后面补 `[1]`、`[2]`。
 - 所以：上面插几行、改缩进空白、改别的函数的名字，记号都不变；有名字的块改了主体、签名还认得；没名字的块自己的源码改了，记号就变了，旧问答成了「找不到原来位置的」（不显示）。种类用视图数据的种类（库规则的卡片是规则的种类 id）。
 - webview 只拿记号比相等，不拆开看。
 
@@ -630,6 +633,17 @@
 - 预览要能读到 `.spx/code-qa/`：打开预览时把这份文件所在工作区文件夹的这个目录加进 webview 的 `localResourceRoots`，发给预览的问答里图片换成 `webview.asWebviewUri` 的地址。
 - 在 VS Code 里改名、挪位置、删除文件 / 目录时问答跟着走（同文件注释）；外部改了 `code-qa.json`（git pull、手改）文件监听重读，开着的预览跟着变。
 
+### 重写注释
+
+按写注释的技能（`/ecc:writing-code-comments`）给一块代码重写讲它的普通注释，没有就新写一段。
+
+- 按钮（`MessageSquareText` 图标，只有图标，悬停 / 读屏「按注释规范重写」，块还没有注释时是「按注释规范写注释」）：每块代码都有。卡片有「注释」一行时画在这一行右边，没有时排在右上角那排按钮里（「问 AI」左边）；文件开头的说明卡片排在右上角。正在重写时不能再点。定义卡片浮窗里、删掉的块没有；嵌着的代码里的块（Dockerfile RUN 里的 shell）、语言没给行注释记号（`LanguageAdapter.lineComment`）又还没有注释的块没有（`BlockView.commentTarget` 没有）。
+- 改哪儿（`BlockView.commentTarget`，扩展端 `blockView.ts` 算）：块前面挂着普通注释时换掉它们（从第一段开头到最后一段结尾，几段中间隔着的空行一起换掉，写成一段）；文件开头的说明卡片换掉它自己；块还没有前面的注释时新写一段，插在块的第一行（连同它的说明、装饰器）上面。说明（docstring、JSDoc、`///`）不动；挂在块后面、子块交上来的注释不动。
+- 问模型：同「问 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），失败另弹一条错误提示。
+
 ## 通用契约
 
 放在 `vscode/src/codeReader/contract.ts`，语法树类型用 `@vscode/tree-sitter-wasm` 自带的 web-tree-sitter 类型。
@@ -839,6 +853,8 @@ export interface BlockShape {
   /** 块自己显示 / 编辑的那一段：复合语句只到主体开始之前，其余是整条语句；块自己的说明（facts.doc、TextBlock.doc）也算在里面。 */
   header: SourceSpan
   children: CodeBlock[]
+  /** 讲这块的普通注释（不是说明），照源码顺序；由 attachComments（languages/shared.ts）挂上，预览排成卡片的「注释」一行，块的编辑范围连同它们。见「注释挂到它讲的块上」。 */
+  comments?: CommentBlock[]
   /** 语言自己报的筛选属性：通用词表以外的（Rust unsafe: 'true'），或 facts 表达不了的通用属性值（Kotlin access: 'internal'，盖过推出来的）；kind 填了不算。 */
   attributes?: BlockAttributes
 }
@@ -861,7 +877,7 @@ export type DocumentedBlock = FunctionBlock | ClassBlock | EnumBlock | Exception
 export type BlockFacts = FactBlock extends infer B ? B extends FactBlock ? Pick<B, 'kind' | 'facts'> : never : never
 
 export type TextKind = Exclude<BlockKind, FactBlock['kind']>
-/** 预览成一行译文的块（注释块是 Markdown 说明）。 */
+/** 预览成一行译文的块（文件开头的说明是 Markdown）。 */
 export interface TextBlock extends BlockShape {
   kind: TextKind
   doc?: Node            // 同 VariableFacts.doc：Python 字段后面紧跟的属性 docstring；预览在译文下面按 Markdown 显示（Translator.doc）
@@ -871,6 +887,9 @@ export interface TextBlock extends BlockShape {
 
 export type CodeBlock = TextBlock | FactBlock
 
+/** 一段注释：相邻行同一写法的行注释合成的一段（node 是第一条，头部盖住全部）、一条块注释或 Python 当注释用的字符串。文件开头的说明单独成块，别的挂在讲的块上（BlockShape.comments）。 */
+export interface CommentBlock extends TextBlock { kind: 'comment' }
+
 /** 着色用的词性，源码着色和译文着色共用。 */
 export type TokenRole =
   | 'keyword'   // 流程关键字：import from export if else for return try catch await …
@@ -927,7 +946,7 @@ export interface DocThrows { exception: Markdown, when: Markdown }
  */
 export interface Doc { body?: Markdown, params: DocParam[], returns?: Markdown, throws: DocThrows[] }
 
-/** 预览里显示的一段文字：着色的词（一行译文、属性值），或整段 Markdown 说明（注释块、函数和类的说明）。 */
+/** 预览里显示的一段文字：着色的词（一行译文、属性值），或整段 Markdown 说明（注释、函数和类的说明）。 */
 export type PreviewText = Inline[] | Markdown
 
 /**
@@ -957,7 +976,7 @@ export interface PropertyRow extends Defines { label: string, value: PreviewText
 /** 一张带表头和边框的表：列名，每行几列对齐的格子，同 PropertyRow 给了 columns 的子行。 */
 export interface PreviewTable { columns: string[], items: PropertyItem[] }
 
-/** 一行译文的块翻出来的：一行译文（注释块是 Markdown 说明）；跨几行写的调用还有摊开各个实参的表，预览排在这一行下面。 */
+/** 一行译文的块翻出来的：一行译文（注释块——文件开头的说明、挂在块上的注释——是 Markdown 原文）；跨几行写的调用还有摊开各个实参的表，预览排在这一行下面。 */
 export interface TextTranslation { text: PreviewText, table?: PreviewTable }
 
 /** 语言插件：语法树 → 代码块树，外加只有它懂、翻译插件翻表达式时要用的信息（叶子的词性、写在表达式里的遍历的结构）。 */
@@ -971,6 +990,8 @@ export interface LanguageAdapter {
   toBlocks: (root: Node, source: string, languageId: string) => CodeBlock[]
   /** 给叶子节点定词性：源码着色用它，译文里照抄的词也按它着色、按它认出能查定义的名字。 */
   tokenRole: (leaf: Node) => TokenRole
+  /** 行注释的记号（`#`、`//`）：「重写注释」给还没有注释的块新写一段时用它；不填就不能新写。 */
+  lineComment?: string
   /** node 是写在表达式里的遍历（推导式、生成器表达式）时给出它的结构，别的节点没有；没有这种写法的语言不填。 */
   iteration?: (node: Node) => IterationFacts | undefined
   /** node 是一次调用（含新建对象）时给出它的结构，别的节点没有；没给的语言不展开调用，照常一行译文。 */
@@ -1036,7 +1057,7 @@ export interface Translator {
   label: string           // '中文直译'
   languageIds: string[]
   displayLanguage: string // 译文用的语言（'zh'）：库规则按它挑自己的词表
-  translate: (block: TextBlock, document: SourceDocument) => TextTranslation  // 只翻 header 那一段；注释块给 Markdown 原文；跨几行写的调用带实参表
+  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) => Doc | undefined          // 说明文字（注释、docstring、当说明用的字符串）→ 正文和块标签（Doc）；正文同属性表的「说明」；连着几行的行文档注释（Rust 的 `///`）node 是第一条，翻译插件自己往下连
@@ -1064,10 +1085,10 @@ export interface KindBadge { label: string, color: ThemeColor, icon: KindIconNam
 /** 库规则认领一块后给出的替身，下面挂着原块留下的子块：规则自己的卡片，或认成的现成属性表块；这块讲在了别的卡片里时是略去它。 */
 export type RuleBlock = RuleCard | RuleFacts | RuleOmit
 
-/** 这块讲在了别的卡片里，不再单独成块（React 的 "use client" 讲成组件卡片的「客户端组件」标签）；不能有子块。 */
+/** 这块讲在了别的卡片里，不再单独成块（React 的 "use client" 讲成组件卡片的「客户端组件」标签）；不能有子块，也不能挂着注释（注释没地方放）。 */
 export interface RuleOmit { omit: true }
 
-/** 规则自己的卡片：一张属性表。种类（badge）决定筛选和边框色；卡片左边的图标是语言的概念再加这个种类、以及 concepts。 */
+/** 规则自己的卡片：一张属性表。种类（badge）决定筛选和边框色；卡片左边的图标是语言的概念再加这个种类、以及 concepts。原块的「注释」一行由宿主插进 rows，规则不管。 */
 export interface RuleCard {
   kind: string                // 种类 id，「规则 id.名字」（sqlalchemy.table）：筛选的 kind 值，要稳定
   badge: KindBadge            // 种类的名字、颜色、图标；筛选栏里这个种类也叫这个名字，卡片边框用这个颜色
@@ -1075,7 +1096,7 @@ export interface RuleCard {
   rows: PropertyRow[]
   defines?: SourceRange       // 块自己的名字（类名）：跳到的定义是它时闪整块
   attributes?: BlockAttributes // 规则自己的筛选属性，叠在宿主从原块推出的上面；kind 填了不算；名字由 LibraryRule.attributeNames 给
-  absorbs: CodeBlock[]        // 并进来的子块（原块 children 里的对象本身），不再单独成块；没并的照源码顺序留作子块，编辑范围同别的块，是原块整条语句
+  absorbs: CodeBlock[]        // 并进来的子块（原块 children 里的对象本身，讲它的注释在它的 comments 里，跟着并进来），不再单独成块；没并的照源码顺序留作子块，编辑范围同别的块，是原块整条语句
   slots?: RuleSlot[]          // 挂在卡片某一行的子行上、点子行才展开的子块，一块只能放一处
 }
 
@@ -1196,7 +1217,7 @@ export interface CommandRule {
 - 注册：`CodeReaderApi.registerLibraryRule(rule)`，返回 `Disposable`；内置规则走同一个 API。
 - 必须给：`id`、`label`、`languageIds`、`libraries`（关心的库）、`claim`（看一块，认领就返回替身 `RuleBlock`，不认返回 `undefined`）。
 - 替身（`RuleBlock`）三种，按有没有 `omit`、`as` 分：
-  - 略去（`RuleOmit`，`{ omit: true }`）：这块讲在了别的卡片里（React 文件开头的 `"use client"` 讲成组件卡片的「客户端组件」标签，组件上面没并进块头部的 JSDoc 讲成「说明」），预览不画它、不占块的位置（后面的块 id 接着往下数）。它不能有子块，有子块时宿主当替身不合约定。
+  - 略去（`RuleOmit`，`{ omit: true }`）：这块讲在了别的卡片里（React 文件开头的 `"use client"` 讲成组件卡片的「客户端组件」标签），预览不画它、不占块的位置（后面的块 id 接着往下数）。它不能有子块、不能挂着注释（注释没地方放），有时宿主当替身不合约定。
   - 认成现成的属性表块（`RuleFacts`）：`as` 是种类和 facts（`BlockFacts`，例如 `{ kind: 'enum', facts: EnumFacts }`），`absorbs` 同卡片。宿主把原块换成这种块（节点不变，头部是原块整条语句，子块是留下的），此后和语言插件报的这种块完全一样：翻译插件的 `describe` 排属性表、种类名取翻译插件的、颜色取这个种类的、筛选属性从 facts 推、块自己的名字从 facts 取。规则不给用词，也不给标签和颜色。只要检查并进来的是不是这块的子块。
   - 规则自己的卡片（`RuleCard`），下面几条都说的是它。
 - 卡片必须给：`kind`（写成「规则 id.名字」，宿主核对前缀；筛选记住的就是它，要稳定）、`badge`（种类的名字、暗 / 亮两种颜色和 lucide 图标名）、`rows`（用现成的 `PropertyRow`：属性名 + 着色的值或 Markdown，表格就是带 `columns` 的子行）、`absorbs`（并进来的子块）。可以给：`defines`（块自己的名字，跳到定义是它时闪整块）、`attributes`（自己的筛选属性）、`concepts`（额外认出的概念，排在种类图标后面）、`slots`（挂在卡片某一行的子行上、点子行才展开的子块，见下）；表格子行填 `PropertyItem.defines`（字段名），跳到这个定义时只闪那一行。
@@ -1209,7 +1230,7 @@ export interface CommandRule {
 - 启用：宿主收集这份源码里各层导入块的 `ImportFacts.sources`（去掉引号），有一个等于规则的某个库、或以「库.」「库/」「库::」开头（子模块；Rust 的路径用 `::`，`use axum::routing::get` 的来源是 `axum::routing`），规则才对这份源码启用。规则不用自己读导入语句。`libraries` 是空数组的规则不看导入，`languageIds` 里这几种语言的源码都启用（React：新的 JSX 写法不用导入 react。Pydantic：子类文件常常只导入父模型、不再导入 pydantic，见「内置：Pydantic 数据模型」）。
 - 认领：宿主从顶层往下每块问一遍启用的规则，按注册顺序，第一个认领的算（先注册的优先）；被认领的块留下的子块照样问。
 - 出错：规则抛错、或替身不合约定（种类 id 没带规则 id 前缀、并进来的不是这块的子块、属性表里的引用标的不是自己 / 规则没给 `resolve` / 引用的段没带下标、挂在子行上的块不是留下的子块 / 放了几处 / 没有那一行或子行、要略去的块还有子块）时，宿主记一条警告日志（输出面板「Superpowers」），当它没认、接着问下一个规则；都没认这块照常显示。预览不会因为规则出错而失败。
-- 并进来的子块：不再单独成块，由规则挑（`absorbs`），宿主不替规则多并。没并进来的子块（方法、规则不讲的注释）不管写在哪（字段中间也算），都照源码顺序是替身的子块，预览里照常看得见。替身的编辑范围同别的块，是原块整条语句（从头部开始，到原块连同各子块的最后一行，类就是整个类），盖住留下的子块的行：替身编辑时预览不画这些子块，同一行不会同时在两处能改（见「预览（代码块树）」）。内置规则并成员时连同紧挨在它前面的注释块一起并（讲的是这个成员），讲方法的注释、最后面的注释照常留下。
+- 并进来的子块：不再单独成块，由规则挑（`absorbs`），宿主不替规则多并。没并进来的子块（方法、别的成员）不管写在哪（字段中间也算），都照源码顺序是替身的子块，预览里照常看得见。替身的编辑范围同别的块，是原块整条语句（从头部开始，到原块连同各子块的最后一行，类就是整个类），盖住留下的子块的行：替身编辑时预览不画这些子块，同一行不会同时在两处能改（见「预览（代码块树）」）。讲成员的注释挂在成员上（`BlockShape.comments`），成员并进来时跟着并进来，内置规则拿它当成员的说明；讲方法的注释挂在方法上，照常是方法卡片的「注释」一行。
 - 卡片在预览里：左边的图标是语言的概念（原来的类、函数……）再加 `badge` 这一个、以及 `concepts`（同一个 id 只留第一个），悬停各自的名字；卡片边框色取 `badge.color`（暗色、亮色主题各取一个），内容是 `rows`，挂在子行上的子块展开时画在它那一行下面（收起这一行时它们跟着收起；画成一层块，同块树），不算卡片的子块（卡片的折叠箭头只管后面留下的子块）；筛选的 `kind` 是替身的种类 id，其余属性从原块推出（原来的类是公共的，数据表也是公共的），叠上规则给的（规则自己的属性叫 `LibraryRule.attributeNames` 给的名字，规则起名时抛错记日志、照写 id）；筛选栏里这个种类叫 `badge.label`；和类块一样默认收起子块。多了图标不改筛选、不改边框色。
 
 ### 规则自己查定义
@@ -1287,7 +1308,7 @@ export interface CommandRule {
 
 说明：`comment=` 的字符串（comment 色）；没写 `comment=` 时用字段的属性 docstring（`context.doc` 给的原文，comment 色；它随字段并进卡片）。关系的目标取第一个位置参数（字符串去掉引号），没写就用 `Mapped[...]` 里的类型；说明写「对方字段 X」（`back_populates` / `backref`）、「单个对象」（`uselist=False`）、「中间表 X」（`secondary`），用 ` · ` 隔开。
 
-并进卡片的子块：`__tablename__`、`__table_args__`、每个字段和关系的赋值，连同紧挨在它们前面的注释块；`__mapper_args__`、普通属性、方法（写在两个字段中间也算）和讲它们的注释照常是子块。
+并进卡片的子块：`__tablename__`、`__table_args__`、每个字段和关系的赋值（讲它们的注释跟着并进来）；`__mapper_args__`、普通属性、方法（写在两个字段中间也算）照常是子块，讲它们的注释是它们卡片的「注释」一行。
 
 样例（luffy `referral/models.py` 的 `ReferralRelation`，测试里逐字核对）：
 
@@ -1393,8 +1414,8 @@ export interface CommandRule {
 - facts：名称、说明（docstring）、访问级别、装饰器（`@enum.unique`）、父类照原来的类；成员照源码顺序。
 - 成员照 Python 的规则认：类主体里给一个名字赋值的语句（`A = 1`、`A: int = 1`），名字不是 `__x__`、`_x_`（enum 保留的，如 `_ignore_`、`_order_`）、`__x`（私有），不在 `_ignore_` 列的名字里（空格隔开的字符串，或字符串的列表 / 元组），值不是 `lambda`、`property(...)` / `classmethod(...)` / `staticmethod(...)`、`nonmember(...)`、连着赋值（`A = B = 1`）；解构赋值（`A, B = 1, 2`）不认。只写注解的（`_value_: int`）不是成员。
 - 值：`auto()`（`enum.auto()` 也算）交给库自动取，没有 `value`（表里写「自动」）；`member(x)` 的值是 `x`；别的是写的值。
-- 说明（`docs`）：从上一个子块之后起紧挨在它上面的注释块（几条行注释连成的一块是几条）、它这一行行尾的注释、紧跟在它后面的属性 docstring，照源码顺序（同 Celery 定时任务的「说明」取法）。
-- 并进来的子块：各个成员连同紧挨在它前面的注释块；方法、嵌套类、不是成员的属性、讲方法的注释、最后面的注释照常是子块（不管写在哪），枚举块默认收起它们。
+- 说明（`docs`）：讲它的注释（挂在成员上的 `BlockShape.comments`：它上面的，类主体最后一个子块是它时后面的也算；几条行注释连成的一段是几条）、它这一行行尾的注释、紧跟在它后面的属性 docstring，照源码顺序。
+- 并进来的子块：各个成员（讲它的注释跟着并进来）；方法、嵌套类、不是成员的属性照常是子块（不管写在哪），讲它们的注释是它们卡片的「注释」一行，枚举块默认收起它们。
 
 样例（`fixtures/enumModels.py` 的 `CommissionStatus`，测试里逐字核对）：
 
@@ -1416,7 +1437,7 @@ export interface CommandRule {
 
 - 认哪些类：装饰器是 `@dataclass`、`@dataclass(...)`、`@dataclasses.dataclass(...)`（`import dataclasses as dc` 的 `dc.dataclass`、`from dataclasses import dataclass as data` 的 `data` 也算，别名按 `context.imports` 换回）。同名的别处的东西不算（`from pydantic.dataclasses import dataclass`、`@other.dataclass`）。
 - 字段照 dataclasses 的规则认：类主体里带注解的名字（`x: int`、`x: int = 1`），照源码顺序。`ClassVar[...]`（`typing.ClassVar`、只写 `ClassVar` 也算）是类变量，不是字段，照常是子块；`InitVar[...]` 是字段，类型写方括号里的，说明前面写「仅初始化时使用」；`_: KW_ONLY` 是记号，不是字段，它后面的字段（没单独写 `kw_only=` 的）在默认值一格写「只能按名字传参」。
-- 并进卡片的子块：各个字段连同紧挨在它前面的注释块、`KW_ONLY` 记号；方法（写在字段中间也算）、`ClassVar`、没注解的类属性、讲它们的注释照常是子块。
+- 并进卡片的子块：各个字段（讲它的注释跟着并进来）、`KW_ONLY` 记号；方法（写在字段中间也算）、`ClassVar`、没注解的类属性照常是子块，讲它们的注释是它们卡片的「注释」一行。
 
 属性表（有才显示；字段总有，一个都没有时写「0 个」、不画表格）：
 
@@ -1434,7 +1455,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 色；都没有时是类说明里讲它的 `@param`（字段就是构造参数，Markdown）。类说明里 `@param` 的名字不是哪个字段时，在卡片的「说明」下面列成「对不上的参数」；`@throws` 是卡片最后的「异常」表。
+- 说明：`field(doc="…")` 的字符串；没写时同枚举成员的说明取法（讲它的注释、这一行行尾的注释、紧跟在后面的属性 docstring，原文用空格连起来），comment 色；都没有时是类说明里讲它的 `@param`（字段就是构造参数，Markdown）。类说明里 `@param` 的名字不是哪个字段时，在卡片的「说明」下面列成「对不上的参数」；`@throws` 是卡片最后的「异常」表。
 
 样例（`fixtures/dataclassModels.py` 的 `SandboxAccess`，测试里逐字核对；说明的 Markdown 从略）：
 
@@ -1460,7 +1481,7 @@ export interface CommandRule {
 - 认哪些类：模块顶层的类，父类链上有 pydantic 的 `BaseModel`。`from pydantic import BaseModel`、`BaseModel as Model`、`import pydantic` 的 `pydantic.BaseModel`、`from pydantic.main import BaseModel` 都算，别名按 `context.imports` 换回。同一文件里继承另一个已经是模型的类也算（`class Child(AIGCMetadata)`，父类写在后面也认）。不认 `TypedDict`、`NamedTuple`、普通类、没导入 pydantic 时同名的 `BaseModel`，也不认 pydantic 的 `@dataclass`（那不是这张卡片，数据类规则也不认它）。
 - 别的文件里的父类：父类是一个名字、又不是本文件里的类时，问索引 `pydantic.models`（`context.lookup`，见「规则认领时查别的文件里的定义」）。索引只扫源码里写了 `BaseModel` 的 `**/*.py`，记下本文件里能确定的模型（父类是 BaseModel，或本文件里另一个模型），值是 `"model"`。查到是模型就换成这张卡片；还没查到（或确定不是）就先按普通类画，查到后再重排。再往下跨一层、中间那个类自己的文件里写不出 `BaseModel` 的，索引不收，认不出来。
 - 字段：类主体里带注解的赋值（`x: str`、`x: str | None = None`、`x: str = Field(...)`），照源码顺序。`ClassVar[...]` 不是字段。`model_config = ConfigDict(...)`（写成带注解的赋值也算）不是字段，是「选项」。
-- 并进卡片的子块：各个字段连同紧挨在它前面的注释块、`model_config` 那一行；方法、`@field_validator`、`ClassVar`、没注解的类属性（`model_config` 除外）、讲它们的注释照常是子块。字段并进来之后不再单独画成变量块。
+- 并进卡片的子块：各个字段（讲它的注释跟着并进来）、`model_config` 那一行；方法、`@field_validator`、`ClassVar`、没注解的类属性（`model_config` 除外）照常是子块，讲它们的注释是它们卡片的「注释」一行。字段并进来之后不再单独画成变量块。
 
 属性表（有才显示；一个字段都没有时不画「字段」这一行）：
 
@@ -1631,7 +1652,7 @@ export interface CommandRule {
 
 `vscode/src/codeReader/rules/react.ts`（读语法树的办法在 `rules/reactTree.ts`，都是纯函数），`languageIds: ['typescriptreact', 'javascriptreact']`，`libraries: []`（新的 JSX 写法不用导入 react，TSX / JSX 文件都启用）。原型：`docs/prototype/code-reader/openpencil/react.js` 的三张画板「编辑器全貌」「卡片种类」「对照」（导出图 `exports/react-main.png`、`react-kinds.png`、`react-compare.png`）；样例是 luffy 的 `chat/code/bubbles/QueuedBubble.tsx`（`fixtures/queuedBubble.tsx.txt`）和 `chat/code/PlanChecklist.tsx` 第 91–226 行（`fixtures/planChecklist.tsx.txt`，前面带上文件开头的导入），以前的 `DesktopTitlebar`、`LegalDocPage`、`DeleteAppDialog`、`DesktopSettingsDialog`、`AppVaultSummary`、`ShareButton`、`PosterDialog`、`OverviewSection` 也在 `fixtures/`。
 
-TSX 和 Python 一样，从上往下一块语法一张卡片，嵌套的块排在父卡片下面，缩进、竖线、折叠同函数体。规则只换掉 React 的几种写法，别的块（导入、接口、类型、常量、普通变量、if、注释、尝试……）照语言默认的卡片。组件卡片不把组件体并进来：组件体的语句照源码顺序是它的子块，照常交给各规则看。表格的格子里只写名字和位置，函数体只出现在子卡片里。
+TSX 和 Python 一样，从上往下一块语法一张卡片，嵌套的块排在父卡片下面，缩进、竖线、折叠同函数体。规则只换掉 React 的几种写法，别的块（导入、接口、类型、常量、普通变量、if、尝试……）照语言默认的卡片，注释照常挂在它讲的卡片上。组件卡片不把组件体并进来：组件体的语句照源码顺序是它的子块，照常交给各规则看。表格的格子里只写名字和位置，函数体只出现在子卡片里。
 
 卡片种类（颜色写暗 / 亮）：
 
@@ -1652,10 +1673,10 @@ TSX 和 Python 一样，从上往下一块语法一张卡片，嵌套的块排
 
 认领（`LibraryRule.claim` 一块一块看，组件卡片的 `absorbs` 是空的）：
 
-- 组件块（函数块、只声明一个变量的常量 / 变量块）是组件时换成组件卡片。文件开头的 `"use client"`（文件里有组件时）和组件上面没并进块头部的 JSDoc（值是 `memo(…)`、直接返回 JSX 的常量块）略去（`RuleOmit`），讲成卡片上的「客户端组件」标签和「说明」。
+- 组件块（函数块、只声明一个变量的常量 / 变量块）是组件时换成组件卡片。文件开头的 `"use client"`（文件里有组件时）略去（`RuleOmit`），讲成卡片上的「客户端组件」标签；它挂着注释时不略去（注释没地方放），照常是一张语句卡片。组件上面的 JSDoc 是组件块自己的说明（TypeScript 的 JSDoc 能当常量、变量块的说明，`memo(…)`、直接返回 JSX 的常量块也是），讲成卡片的「说明」。
 - 组件体里的块：语法树往上找，块的语句直接是某个组件函数主体（语句块）的子语句才认（`enclosingComponent`：所在的函数经 `componentOfFunction` 找回它的声明，再用认组件的 `componentAt` 核对），按组件体的归类（`bodyOf`）认成状态、引用、数据源、派生值、副作用、事件处理函数。
 - `return` 块：所在的最内层函数（`enclosingFunction`）是组件函数、返回的是 JSX 时认成渲染输出；写在 `if` 里的提前返回 JSX 也算，它是如果卡片下面的子块。返回 `null` 这类的照常是返回块。
-- 别的照语言默认：组件体里普通的 `const x = 表达式` 是变量卡片，`if (…) return null` 是如果卡片、下面是返回卡片，注释照常成块（不再并进卡片）。
+- 别的照语言默认：组件体里普通的 `const x = 表达式` 是变量卡片，`if (…) return null` 是如果卡片、下面是返回卡片，注释是它讲的那张卡片的「注释」一行。
 - 回调、函数里的语句来自 TypeScript 语言插件本来给的子块：调用的实参是带语句块的函数时（任何调用都一样），那句语句、那个变量的子块就是函数里的语句，所以 `useEffect(() => {…})`、`useCallback(() => {…})`、`useMemo(() => {…})` 的语句排在副作用、派生值卡片下面；事件处理函数是函数块，函数体照常是子块。
 
 组件卡片：
@@ -1685,7 +1706,7 @@ TSX 和 Python 一样，从上往下一块语法一张卡片，嵌套的块排
 
 副作用：触发时机按依赖数组读，`[a, b]` 是「a、b 变化时」，`[]` 是「仅挂载时」，没写是「每次渲染后」（keyword 色），依赖写成别的表达式时「deps 变化时」；useLayoutEffect 后面加「，浏览器绘制前」。最后返回清理函数时那句 return 并进来，多一行「清理函数」：`() => …` 翻它的主体，语句块一句句翻、「；」隔开。副作用函数里别的语句是子块。
 
-事件处理函数：名称是函数名（function 色，带下标）；参数照常翻（`e: KeyboardEvent<HTMLDivElement>`），几个「, 」隔开，没有写「无」；绑定事件从 JSX 属性反查：「<div>（修改排队消息） 的 onKeyDown」，在属性值里调用时写传入的实参「（传入 h.id）」，在列表里一项项渲染的写「每个 <button>」，几处「、」隔开；没绑在 JSX 上时写由谁调用「由 download、share 调用」，都没有「—」。函数里的语句是子块（如果、返回、调用、变量、注释、尝试……）。
+事件处理函数：名称是函数名（function 色，带下标）；参数照常翻（`e: KeyboardEvent<HTMLDivElement>`），几个「, 」隔开，没有写「无」；绑定事件从 JSX 属性反查：「<div>（修改排队消息） 的 onKeyDown」，在属性值里调用时写传入的实参「（传入 h.id）」，在列表里一项项渲染的写「每个 <button>」，几处「、」隔开；没绑在 JSX 上时写由谁调用「由 download、share 调用」，都没有「—」。函数里的语句是子块（如果、返回、调用、变量、尝试……），注释挂在它讲的那块上。
 
 渲染输出（「JSX 结构大纲」一行下面的子行，一行一个元素，下一层缩进；带下一层的行有折叠箭头）：
 
@@ -1716,7 +1737,7 @@ react.component 23
       if 39: 如果 (localStorage.getItem(PLAN_CHECKLIST_COLLAPSED_KEY) 全等 "1")
         statement 40: queueMicrotask(() => setCollapsed(真));
     catch 42: 捕获
-      comment 43: localStorage 不可用 (隐私模式等) 时静默用默认
+      注释: localStorage 不可用 (隐私模式等) 时静默用默认
   react.derived 47
     名称: toggle
     计算表达式: 函数（3 条语句）
@@ -1728,13 +1749,13 @@ react.component 23
     try 50: 尝试
       statement 51: localStorage.setItem(PLAN_CHECKLIST_COLLAPSED_KEY, 如果 next 则 "1" 否则 "0");
     catch 52: 捕获
-      comment 53: 忽略写入失败
+      注释: 忽略写入失败
   if 57: 如果 (todos.length 全等 0)
     return 57: 返回 空;
   variable 58
     名称: whole
     初始值: wholeStatusOf(todos, active)
-  …（doneCount、counter、current 三张变量卡片，一张注释卡片，headline 变量卡片）
+  …（doneCount、counter、current、headline 四张变量卡片，headline 那张带「注释」一行）
   react.render 65
     JSX 结构大纲:
       Collapsible ⟦样式 1 个类 · 取决于 CARD_SURFACE⟧ open=非 collapsed  onOpenChange=toggle
@@ -1743,7 +1764,7 @@ react.component 23
           …
 ```
 
-和原型不一样的地方：接口 `PlanChecklistProps` 照 TypeScript 的接口块（一行译文，字段、注释是子块），原型「对照」里画成的字段表（名称 / 类型 / 必填 / 说明）这次没做；渲染输出的大纲挂在「JSX 结构大纲」这一行下面，不是直接画在卡片里；更新位置、使用位置里的「副作用」是副作用色的字，不能跳（副作用没有名字可查定义），原生标签（`<textarea>`）也不能跳，组件标签能跳到组件定义。
+和原型不一样的地方：接口 `PlanChecklistProps` 照 TypeScript 的接口块（一行译文，字段是子块，注释挂在讲的字段上），原型「对照」里画成的字段表（名称 / 类型 / 必填 / 说明）这次没做；渲染输出的大纲挂在「JSX 结构大纲」这一行下面，不是直接画在卡片里；更新位置、使用位置里的「副作用」是副作用色的字，不能跳（副作用没有名字可查定义），原生标签（`<textarea>`）也不能跳，组件标签能跳到组件定义。
 
 ### 内置：Rust 的库
 
@@ -1752,7 +1773,7 @@ react.component 23
 - 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`）、参数（说明里写了 `@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!` 的返回类型是「—」。
+- sqlx（`rules/sqlx.ts`，`libraries: ['sqlx']`）：`query!` / `query_as!` / `query_scalar!`。种类 `sqlx.query`，标签「查询」，图标 `database`，颜色暗 #ce9178 / 亮 #a31515。前面的注释同别的块，是卡片的「注释」一行（宿主插在第一行 SQL 后面）。SQL 原文等宽，参数 `$1` 对上传入的表达式，`query_as!` / `query_scalar!` 的第一个实参是返回类型，`query!` 的返回类型是「—」。
 - tauri（`rules/tauri.ts`，`libraries: ['tauri']`）：`#[tauri::command]` 的函数。种类 `tauri.command`，标签「桌面命令」，图标 `square-function`，颜色暗 #e5c07b / 亮 #9a6a00。名称后面再标「桌面命令」。参数表「名称 | 类型 | 来源」：`State<…>` 是「窗口状态」，其余是「调用方传入」；说明里的 `@param` 对上时多一列「说明」，`@return` 跟在「返回」后面，`@throws` 成「异常」表。
 
 ## 命令规则
@@ -1811,17 +1832,31 @@ shell 脚本大半是一条条命令，一条命令读成什么取决于命令
 
 ## 代码块树规则
 
+### 注释挂到它讲的块上
+
+注释一定是讲某块代码的，和语言无关，各语言插件建好整棵树后调一次 `languages/shared.ts` 的 `attachComments`（Python、TypeScript 在认异常类之前调，异常类并类属性时拿到的是挂好注释的块）：
+
+- 先照各语言的规矩分好注释块（`listBlocks`：相邻行同一写法的行注释合成一段，和上一条语句同一行的是行尾注释、不成块，文档注释能当说明的进 `facts.doc`；Python 当注释用的字符串也是注释块）。
+- 再把每段注释挂到它讲的块上（`BlockShape.comments`，照源码顺序），不再单独成块：
+  1. 同一层（同一个父块的子块，文件顶层也算一层）里它后面最近的一块代码，中间隔着空行也算；挂在同一块前面的几段各是一段。
+  2. 后面没有代码了（主体、文件最后的注释）挂到同一层前面最近的那块；这一层一块代码都没有（主体里只有注释）挂到父块。
+  3. 文件开头的说明单独成块（种类 comment）：第一块代码之前的注释（`#!` 解释器、Dockerfile 的解析指令不算代码，Python 第一行的 `#!`、头两行写编码的 `# -*- coding: … -*-` 也是文件的），和第一块代码之间隔着空行的那几段；紧挨着第一块代码（中间没空行）的那几段照第 1 条挂到它上面。本来就讲整个文件的总是文件开头的说明：Python 模块开头的 docstring、Rust 的 `//!` / `/*!`、写了 `@file` / `@fileoverview` / `@overview` 的 JSDoc；Rust 的 `//!` 写在 `mod` 身体里时交给那个模块。
+  4. 嵌在别的语言里的代码（Dockerfile 的 RUN 里的 shell）没有文件开头的说明，一块代码都没有时注释照旧单独成块（读成步骤时不算一步）。
+- 文档注释是块的「说明」（照旧进 `facts.doc`、带块标签），普通注释是块的「注释」，一块可以两样都有。行尾注释照旧跟着那一行。
+- 块的完整范围（编辑范围）连同挂在它上面的注释（见「预览（代码块树）」）；块的记号（问答挂的地方）只看块自己，改注释不丢问答。
+- 库规则拿到的块已经挂好注释：并成员时讲成员的注释跟着成员（内置规则拿它当成员的说明）；规则略去的块不能挂着注释。
+
 ### TypeScript / JavaScript
 
-- 顶层与语句块内的每条语句一块；连续的行注释合成一块注释。
-- JSDoc（以 `/**` 开头的块注释，`/**/` 不算）和下一条语句之间只有空白（空行也算，中间隔着装饰器也算）、那条语句是函数、类或枚举块时，它是这个函数、类、枚举的说明：进 `facts.doc`，头部往上延到注释开头，不单独成块。其余情况（后面不是函数、类、枚举块，中间隔着别的注释，在上一条语句的行尾）照旧是注释块。`//` 行注释和普通 `/* */` 块注释不变。
+- 顶层与语句块内的每条语句一块；连续的行注释合成一段注释，挂到它讲的块上（见「注释挂到它讲的块上」）。
+- JSDoc（以 `/**` 开头的块注释，`/**/` 不算）和下一条语句之间只有空白（空行也算，中间隔着装饰器也算）、那条语句是函数、类、枚举、常量或变量块时，它是这一块的说明：进 `facts.doc`，头部往上延到注释开头。其余情况（后面不是这几种块，中间隔着别的注释）是普通注释，挂到它讲的块上；在上一条语句的行尾的是行尾注释。`//` 行注释和普通 `/* */` 块注释是普通注释。
 - `import_statement` → import。
 - `export_statement` 包着声明 → 按声明定种类，节点取整个 `export_statement`（头部包含 `export`）。
 - `function_declaration` / `generator_function_declaration` / `method_definition` → function，子块来自主体语句。
 - 变量声明的唯一声明值是带语句块主体的箭头函数 / 函数表达式 → function（React 组件、回调常见写法），子块来自主体；是类表达式（`const A = class {}`）→ class。
 - `lexical_declaration` / `variable_declaration`：模块顶层的 `const` → const，其余 → variable。
-- `class_declaration` / `abstract_class_declaration`、`export default class {}` → class，子块：方法 → function，字段 → field（值是带语句块主体的函数 → function，值是类表达式 → class），注释 → comment。
-- 类（含类表达式）的父类是异常类时（见「异常」）→ exception：头部是整个类，字段连同前面的注释并进属性表，方法（含 constructor）、别的成员照常是子块。整棵树建好后按整份文件认（同一文件里的异常类写在后面也算）。
+- `class_declaration` / `abstract_class_declaration`、`export default class {}` → class，子块：方法 → function，字段 → field（值是带语句块主体的函数 → function，值是类表达式 → class），注释挂到讲的成员上。
+- 类（含类表达式）的父类是异常类时（见「异常」）→ exception：头部是整个类，字段连同讲它的注释并进属性表，方法（含 constructor）、别的成员照常是子块。整棵树建好后按整份文件认（同一文件里的异常类写在后面也算）。
 - `interface_declaration` → type，子块：属性 / 方法签名 → field；`type_alias_declaration` → type；`enum_declaration`（含 `const enum`、`declare enum` 的 `ambient_declaration`、`export` 包着的）→ enum，头部是整条声明，成员在属性表里讲、不成子块。
 - `if_statement` → if，子块来自 consequence；`else` / `else if` 展平成紧跟其后的兄弟块 else（`else if` 的头部是 `else if (...)`，子块来自它的 consequence）。
 - `for` / `for…in` / `for…of` / `while` / `do` → loop。
@@ -1835,11 +1870,11 @@ shell 脚本大半是一条条命令，一条命令读成什么取决于命令
 - `import_statement` / `import_from_statement` / `future_import_statement` → import。
 - `function_definition` → function；`decorated_definition` 按内部定义定种类，头部包含装饰器。
 - `class_definition` → class；类体里的带注解赋值 → field。
-- 父类是异常类的类（见「异常」）→ exception：头部是整个类，类属性连同前面的注释并进属性表，方法（含 `__init__`）、别的语句照常是子块。整棵树建好后按整份文件认（同一文件里的异常类写在后面也算）。
+- 父类是异常类的类（见「异常」）→ exception：头部是整个类，类属性连同讲它的注释并进属性表，方法（含 `__init__`）、别的语句照常是子块。整棵树建好后按整份文件认（同一文件里的异常类写在后面也算）。
 - 字符串语句：单独一个普通字符串字面量的表达式语句（`string`，或隐式拼接的 `concatenated_string`，每段的前缀只有 r / u 或没有；f-string、t-string、字节串不算，照旧是 statement）。
 - 函数、类主体的第一条语句（注释不算）是字符串语句时，它是这个函数、类的 docstring：进 `facts.doc`，头部往下延到字符串结尾（它和冒号之间的注释也在头部里），子块从它后面开始，不单独成块。
 - 属性 docstring：模块、类主体里（条件、函数等语句块里的不算）紧跟在一条赋值后面的字符串语句是这个常量、变量、字段的说明：常量、变量进 `facts.doc`，字段进块的 `doc`，头部往下延到字符串结尾，不单独成块。「紧跟」同 JSDoc：中间可以隔空行和赋值的行尾注释，隔着别的注释、语句就不算；只挂一个，后面再来的字符串照下一条规则。
-- 其余字符串语句（模块开头的 docstring、写在语句中间当注释用的字符串）和 `comment` → comment。
+- 其余字符串语句（模块开头的 docstring、写在语句中间当注释用的字符串）和 `comment` → 注释：模块开头的 docstring、第一行的 `#!`、头两行写编码的注释是文件开头的说明，别的挂到它讲的块上（见「注释挂到它讲的块上」）。`#!` 和写编码的那两行不和后面的 `#` 注释连成一段。
 - 赋值：模块顶层且变量名全大写 → const，其余 → variable。
 - `if_statement` → if；`elif_clause` / `else_clause` → 兄弟块 else；`for` / `while` → loop（循环的 `else` → 兄弟块 else）。
 - `try_statement` → try；`except_clause` → catch；`finally_clause` → finally。
@@ -1849,7 +1884,7 @@ shell 脚本大半是一条条命令，一条命令读成什么取决于命令
 
 ### Shell
 
-- 首行 `#!` → interpreter；别的 `comment` 连着的几行合成一块注释；紧贴在函数定义上面（中间没空行）的注释是函数的说明，进 `facts.doc`、头部往上延，不单独成块。
+- 首行 `#!` → interpreter；别的 `comment` 连着的几行合成一段注释，挂到它讲的块上（见「注释挂到它讲的块上」）；紧贴在函数定义上面（中间没空行）的注释是函数的说明，进 `facts.doc`、头部往上延。
 - `set` 后面全是开关（`-euo pipefail`、`+x`、`-o nounset`）→ options；有不是开关的词（`set -- a b`）→ command。
 - `variable_assignment`、`declaration_command`（local / export / readonly / declare 声明了变量的）→ variable；readonly 的、脚本顶层名字全大写且值里没有展开的 → const。一句声明几个变量是一块（`DeclaratorFacts` 各一项）。
 - `function_definition` → function，子块来自主体各句。
@@ -1864,7 +1899,7 @@ shell 脚本大半是一条条命令，一条命令读成什么取决于命令
 
 - 文件最开头连着的 `# syntax=` / `# escape=` / `# check=`（从第一行起、中间没空行）→ directive。
 - 每个 `from_instruction` 开一个 stage，头部是 FROM 那一行，紧贴在上面（中间没空行）的几行注释是它的说明、头部往上延；到下一个阶段（连同它上面的说明）之前的指令、注释是子块；第一个 FROM 之前的照常是顶层的块。
-- 相邻行的注释合成一块注释；只写了中文名记号、紧挨着下一条指令的注释算在那条指令的块里。
+- 相邻行的注释合成一段注释，挂到它讲的块上（见「注释挂到它讲的块上」：阶段里的挂到后面那条指令，阶段最后的挂到前面那条）；只写了中文名记号、紧挨着下一条指令的注释算在那条指令的块里。
 - `run_instruction` → run（整条指令，shell 写法的带 `embedded`）；`copy_instruction`、`add_instruction` → copy；`label_instruction` → label；`env_instruction`、`arg_instruction` → variable（facts 的 scope 分构建参数、环境变量）；WORKDIR / USER / EXPOSE / VOLUME / STOPSIGNAL / SHELL / MAINTAINER → setting；`healthcheck_instruction` → health；`cmd_instruction`、`entrypoint_instruction` → start；`onbuild_instruction` → setting，包着的指令照这些规则是它的子块；别的（语法错误）→ statement。
 - 连着写的同种指令（紧挨着下一行）并成一块：ENV、ARG 并成一个变量块（declarators 是各条的全部），LABEL 和从同一个地方复制的 COPY 并成一块（`TextBlock.group`，头部盖住全部）；ADD、带 heredoc 的 COPY 不并。
 
@@ -1876,10 +1911,10 @@ shell 脚本大半是一条条命令，一条命令读成什么取决于命令
 
 注释和别的语言走同一条路（`listBlocks`，Rust 的 `CommentRules` 在 `languages/rust.ts`），文件顶层、`mod` 身体、`impl` 身体都一样：
 
-- 连续的行注释合成一块注释：相邻行、写法相同才合，`//`、讲所在模块或 crate 的 `//!`、讲下一项的 `///` 各是一种写法，不混着合。中间空的 `//` 不打断，是 Markdown 里的空行、分段；隔着空行、隔着别的语句就断开。
+- 连续的行注释合成一段注释：相邻行、写法相同才合，`//`、讲所在模块或 crate 的 `//!`、讲下一项的 `///` 各是一种写法，不混着合。中间空的 `//` 不打断，是 Markdown 里的空行、分段；隔着空行、隔着别的语句就断开。合好的注释挂到它讲的项上（见「注释挂到它讲的块上」）；`//!` 写在文件开头是文件的说明，写在 `mod` 身体里交给那个模块。函数体不拆，函数体里的注释留在函数的源码里。
 - 和上一条语句同一行的 `//` 是行尾注释，不单独成块。
-- `///`（和 `/**` 开头的块注释）后面紧跟的是函数、结构体、枚举、特质、实现、模块、常量、`static` 时，是这一项的说明：进 `facts.doc`（第一条注释节点），头部往上延到它开头，不单独成块；后面是 `use`、宏调用、`let` 这类不带说明的项，或隔着别的注释时，照旧是注释块。
-- 注释块的预览是去掉 `//`（`///`、`//!` 连那个 `/`、`!`）和后面一个空格的原文，按「注释的 Markdown 排版」显示。语法包把 `///`、`//!` 行尾的换行算进注释节点，块的范围不算这个换行。
+- `///`（和 `/**` 开头的块注释）后面紧跟的是函数、结构体、枚举、特质、实现、模块、常量、`static` 时，是这一项的说明：进 `facts.doc`（第一条注释节点），头部往上延到它开头；后面是 `use`、宏调用、`let` 这类不带说明的项，或隔着别的注释时，是普通注释，挂到它讲的项上。
+- 注释的预览（「注释」一行、文件开头的说明）是去掉 `//`（`///`、`//!` 连那个 `/`、`!`）和后面一个空格的原文，按「注释的 Markdown 排版」显示。语法包把 `///`、`//!` 行尾的换行算进注释节点，块的范围不算这个换行。
 
 - `use` → import。来源是路径去掉最后一节（`std::sync::Arc` 的来源是 `std::sync`）。导入项表「名字 | 别名」，没起别名是「—」，`*` 是「*」。
 - `struct` → class（中文直译把这个种类叫「结构体」）。字段不单独成块，表「字段 | 类型 | 可见性」。元组结构体没有这张表。
@@ -1924,7 +1959,7 @@ shell 脚本大半是一条条命令，一条命令读成什么取决于命令
 
 同一套表和节点模板也用来翻属性表里的值：引擎能翻任意一个节点（只取它落在块头部里的那一段），参数类型、默认值、返回类型、变量类型和初始值、字典 / 对象各项的键和值都走这条路。
 
-其他规则：空数组字面量 → 空数组、空对象字面量 → 空对象（Python 空列表 → 空列表、空字典 → 空字典）；复合语句头部去掉结尾的 `{` 或 `:`；多行合成一行（连续空白压成一个空格，右括号前的尾逗号去掉）；注释块给去掉注释符号的 Markdown 原文（见「注释的 Markdown 排版」）。关键字与前后内容之间保留源码里的空格（`!` 翻成「非」后补一个空格）。
+其他规则：空数组字面量 → 空数组、空对象字面量 → 空对象（Python 空列表 → 空列表、空字典 → 空字典）；复合语句头部去掉结尾的 `{` 或 `:`；多行合成一行（连续空白压成一个空格，右括号前的尾逗号去掉）；注释（文件开头的说明、挂在块上的注释）给去掉注释符号的 Markdown 原文（见「注释的 Markdown 排版」）。关键字与前后内容之间保留源码里的空格（`!` 翻成「非」后补一个空格）。
 
 关键字按所在语法节点选择译法：同一个关键字在不同语法结构里意思不同时，表里写一个默认译法，再加若干「语境 → 译法」。语境是从关键字节点往上的节点类型链，外层在前：`raise_statement` 指父节点是 raise_statement，`for_statement > else_clause` 指父节点是 else_clause、祖父节点是 for_statement（关键字包在一层子句节点里时要看到祖父节点）。几条语境同时匹配时取最长的，都不匹配用默认译法。节点类型以 tree-sitter 语法为准。下面两张表里写成「（语境）译法 / （语境）译法」的关键字就是按这条规则区分的，排第一个的是默认译法。
 
@@ -2003,15 +2038,20 @@ interface BlockViewBase {
   concepts: BlockConcept[] // 认出来的概念，从左到右；webview 按图标名画，不自己用种类查
   badge?: KindBadge        // 库规则的卡片才有：筛选栏里这个种类的名字，卡片边框的颜色；图标在 concepts 里。和类块一样默认折叠
   slot?: { row: number, item: number } // 库规则挂在父卡片子行上的子块才有（RuleSlot）：挂在父卡片第 row 行的第 item 个子行上，点它才在这一行下面展开（它的块 id 记成折叠着就是收着）
+  commentRow?: number      // 「注释」一行排第几行，0 起：属性表卡片是 properties 的下标，一行译文的卡片是 rows 的下标；没有注释就没有。「重写注释」按钮画在这一行上
+  commentTarget?: CommentTarget // 「重写注释」写到哪（见「重写注释」）；嵌着的代码里的块、语言没给行注释记号又还没有注释的块没有，不给按钮
   children: BlockView[]
 }
 
+/** 「重写注释」写到哪，行号 0 起：换掉块前面那几段普通注释（文件开头的说明卡片是它自己），或块还没有注释时新写在 line 这一行上面。 */
+type CommentTarget = { kind: 'replace', startLine: number, endLine: number } | { kind: 'insert', line: number }
+
 /**
- * 属性表块（有 facts）和库规则认领的块只带 properties，其余块只带 translation（注释块是 `{ markdown }`）；没有翻译插件时是空数组。
+ * 属性表块（有 facts）和库规则认领的块只带 properties（「注释」一行由宿主插在里面），其余块只带 translation（文件开头的说明是 `{ markdown }`）；没有翻译插件时是空数组。
  * 一行译文里有跨几行写的调用时 table 是摊开实参的表（TextTranslation.table），块带说明（TextBlock.doc）时 doc 是翻译插件读出的说明正文（Translator.doc 的 body），
- * webview 依次排在译文下面。
+ * 挂着注释时 rows 是「注释」一行，webview 依次排在译文下面。差异的标记里一行译文的卡片的 rows 同属性表逐行标。
  */
-type BlockView = BlockViewBase & ({ translation: PreviewText, table?: PreviewTable, doc?: Markdown } | { properties: PropertyRow[] })
+type BlockView = BlockViewBase & ({ translation: PreviewText, table?: PreviewTable, doc?: Markdown, rows?: PropertyRow[] } | { properties: PropertyRow[] })
 ```
 
 - 扩展 → webview：
@@ -2030,6 +2070,7 @@ type BlockView = BlockViewBase & ({ translation: PreviewText, table?: PreviewTab
   - `{ type: 'askProfiles', options: { id, label }[], selected }`：「问 AI」的 profile 下拉（`id` 是 profile 名，「默认」的 `id` 是 `''`、`label` 是「默认」）。`ready` 后发一次（每次现读 profile 目录），任何一个预览选了都发给所有开着的预览（包括选的那个）。
   - `{ type: 'answer', askId, text, activity? }`：`askId` 那个问题的回答长了（`text` 是到现在为止的全文）或换了在做的事。webview 攒着、最多每 80ms 画一次。
   - `{ type: 'answerEnd', askId, status: 'done' | 'failed' | 'stopped', text?, error?, entryId? }`：答完了。`done` 带最终回答和存下的那条的 id（历史里不再重复显示它），`failed` 带给人看的原因，`stopped` 是被叫停、没存。
+  - `{ type: 'rewriteProgress', anchor, question, text, activity? }`：`anchor` 那块正在重写注释：`question` 是发给模型的那一句，`text` 是正文到现在为止写出来的，`activity` 是正在读什么。`{ type: 'rewriteEnd', anchor, status: 'done' | 'failed' | 'stopped', error? }`：重写完了（见「重写注释」）。
   - `{ type: 'repoLinksChecked', id, missing, unresolved }`：回答第 `id` 次 `checkRepoLinks`，`missing` 是仓库里没有的路径，`unresolved` 是找不到的不带路径的引用。`{ type: 'repoLinkBroken' | 'repoLinkOpened', path?, symbol? }`：点了以后打不开 / 打开了；没有 `path` 的是不带路径的引用。见「注释的 Markdown 排版」。
 - webview → 扩展：
   - `{ type: 'probeDefinition', id, version, offset }`：按住修饰键指到带 `offset` 的名字上时问有没有定义，`id` 每问一次加一；`version` 不是当前文档版本就不答。
@@ -2040,6 +2081,7 @@ type BlockView = BlockViewBase & ({ translation: PreviewText, table?: PreviewTab
   - `{ type: 'checkRepoLinks', id, paths, symbols }`：页面上的仓库路径问哪些没有，不带路径的引用问哪些找不到（`id` 每问一次加一）。`{ type: 'openRepoLink', path?, symbol? }`：点了注释里的仓库链接（带 `path`）或不带路径的引用（只带 `symbol`）。见「注释的 Markdown 排版」。
   - `{ type: 'ready' }`
   - `{ type: 'edit', startLine, endLine, text }`：用 `WorkspaceEdit` 把这几行整行替换成 `text`（每行补回原来第一行的缩进）。
+  - `{ type: 'rewriteComment', anchor }`：给 `anchor` 那块重写注释（见「重写注释」）；`{ type: 'stopRewrite', anchor }`：叫停，不写文件。
   - `{ type: 'selectTranslator', id }`：按 `languageId` 记到 `globalState`，重发文档。
   - `{ type: 'setFilter', excluded }`：改块筛选（整份替换）；扩展端逐项核对后记进 `workspaceState`，再发 `filter` 给所有预览。webview 不在本地先改，只按扩展端发来的显示。
   - `{ type: 'setOnlyChanges', on }`：打开 / 关掉「只看改动」；扩展端记进 `workspaceState`（`superpowers.codeReader.onlyChanges`），再发 `filter` 给所有预览。
@@ -2106,11 +2148,12 @@ vscode/src/codeReader/
   （blockView.ts 的 readDefinitionKind：定义处落在哪块自己的名字上；editor/definitions.ts 的 definitionKind：打开定义所在的文件交给它）
   rules/pythonTree.ts    Python 库规则共用的读语法树的办法（名字最后一节、字符串内容、调用的参数、别名、注解里的 X[...]、库里的名字）
   rules/segments.ts      库规则共用的拼属性表文字的办法
-  rules/children.ts      库规则共用的挑子块的办法（成员连同紧挨在它前面的注释块、成员的说明节点）
+  rules/children.ts      库规则共用的挑子块的办法（类主体里带注解的赋值、成员的说明节点：挂在成员上的注释、行尾注释、属性 docstring）
   docTags.ts             说明的原文按 KDoc 拆成正文和块标签（Doc：@param / @return / @throws），翻译插件的 doc 用它（纯函数）
   rules/docRows.ts       讲说明的几行，中文直译和库规则共用：正文、对不上的参数、参数按名字对说明（paramDocs）、输出后面的 @return、异常表
   symbolLinks.ts         注释里不带路径的引用指到哪：导入引进来的名字（importedNames，readBlockViews 交出）、本文件定义的优先再是导入的（resolveReference，符号和定义由预览去问）（不碰 VS Code）
-  languages/shared.ts    语言插件共用的建树工具；异常类（withExceptions：按整份文件认异常类，类块换成异常块，并类属性、取构造参数）
+  languages/shared.ts    语言插件共用的建树工具：一串语句分块（listBlocks）、注释挂到它讲的块上（attachComments）；异常类（withExceptions：按整份文件认异常类，类块换成异常块，并类属性、取构造参数）
+  commentRewrite.ts      重写注释：发给模型的那一句、读结构化结果（含逐字的进度）、新正文套回定界符 / 新写一段、核对后写回（不碰 VS Code）
   languages/typescript.ts  （call：调用的结构，new 是新建；TYPESCRIPT_EXCEPTIONS：认异常类的父类名、类字段、constructor）
   languages/python.ts    （iteration：推导式的结构；call：调用的结构；PYTHON_EXCEPTIONS：自带的异常类、类属性、__init__）
   languages/rust.ts      Rust：代码块树
@@ -2170,7 +2213,7 @@ vscode/src/codeReader/
   qa/qaMap.ts            .spx/code-qa.json 的形状、每条怎么认、记一次 / 删一次、再问时接着哪个会话（纯函数）
   qa/prompt.ts           问 AI 的话：找到那块、外层块的开头、带行号的代码、追问
   qa/answerStream.ts     stream-json 的每行 → 会话 id、逐字的回答、在做的事、最终回答 / 失败
-  qa/claudeAsk.ts        命令行参数（只读、选的 profile）、问一次（问题连同图片从 stdin 发，追问找不到会话时重新问）、失败给人看的话
+  qa/claudeAsk.ts        命令行参数（只读、选的 profile、要结构化结果时的 --json-schema）、问一次（问题连同图片从 stdin 发，追问找不到会话时重新问）、重写注释问一次（askCommentBody）、失败给人看的话
   qa/qaImages.ts         问题带的图片：认哪些格式、存到 .spx/code-qa/ 叫什么名字、写文件（不碰 VS Code）
   qa/askProfiles.ts      AskProfiles：问 AI 用哪个 profile，下拉的选项、记在 globalState、通知所有预览（不碰 VS Code）
   qa/asks.ts             QaAsks：正在答的问题，一块一个、最多 3 个、能叫停（不碰 VS Code）
@@ -2204,7 +2247,9 @@ 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`）。
-- 注释的 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` 的导入）。
+- 注释挂到它讲的块上（各语言的 `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 不动）；没交回正文、出错、重写期间代码变了 → 失败不写，叫停 → 不写；套回壳的几种写法（三引号、`#`、`/** */`、`//`）。
+- 注释的 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` → 整块（照样展开属性行）；翻译插件给参数、导入项、声明的变量、泛型参数标的范围指回源码原文；块自己的名字只有函数、类和单变量声明有。
 - 高亮各处出现：段的源码范围和出现重叠才亮、边界相接不算、没下标的不亮，讲别处名字的段（`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` 或又按键、点鼠标不守。
@@ -2220,7 +2265,7 @@ vscode/webview-ui/code-reader.html + src/codeReader/  预览界面（React，Vit
   - 语言插件（`languages/bash.test.ts`，真实解析）：`fixtures/fetchRuntime.sh` 的代码块树（种类、行号、层级，同原型 `SHELL_BLOCKS`，原型略去的行也在）；elif / else 展平、while / for 的主体是子块、条件串和命令串；解释器（env、写死的路径）、选项（连写拆开、`-o`、`+`、`set --` 不是）、变量（local 一句几个、没值的、readonly 和顶层全大写写死的是常量）、函数（按位置的参数和名字、打印的几句、被 `$(…)` 拿去用、写了的 return）；命令的词（写死的文字、有展开的没有）和重定向；同一文件里的名字（函数、赋值、local、for、read、展开，第几个参数不算）；行尾 `# @Comment`。
   - 中文直译（`translators/bashZh.test.ts`，走 `readBlockViews`）：`fetchRuntime.sh` 整份逐行同 `FETCH_READING`（即上面「Shell 脚本」的样例）；展开（长度、去头去尾、截取、没设时、替换、特殊变量）、条件、重定向、命令规则（不认识的选项照抄、没有规则的照抄）、`&&` / `||`、遍历、`$(dirname "$0")`、常量；字符串色 / 变量色 / 常量色；规则出错照抄命令并报告。
   - 宿主：命令规则按语言、注册顺序给（`registry.test.ts`），shellscript 的 document 消息带命令规则读的译文、shell 的种类名、同一文件里的名字（`editor/documentMessage.test.ts`），跳到之前最近的定义、定义处算写入（`localSymbols.test.ts`）。
-- Rust（`languages/rust.test.ts`、`rules/rustLibs.test.ts`，真实解析）：`fixtures/rustLang.rs` 的导入、结构体、枚举、实现（方法挂在方法表的子行上）、函数（异步、分情况）、特质逐行同预览；给结构体加一个字段，字段表那一行标成新增。`fixtures/rustComments.rs` 开头连着写的 `//` 合成一块注释，预览是去掉 `//` 的三段 Markdown；隔着空行、语句的注释各是一块，行尾 `//` 不单独成块，`//!` 连着几行合成一块，`///` 并进下一个函数当说明，`mod`、`impl` 身体里同一套。编译属性：Tauri `main.rs` 的 `cfg_attr` 卡片逐行（属性的着色、「非 调试构建」、「整个 crate」、windows 子系统的说明），别的文件顶层的 `allow` 是本模块、列出 lint 名，认不得的属性没有说明、不知道文件名时是所在模块，`cfg_attr` 里几个属性是一张表、套着的条件加括号，`isCrateRoot` 的几种路径。`fixtures/rustLibs.rs` 的 serde（改名、不输出、字段名改驼峰）、thiserror（展示、透传来源）、axum（方法、路径、路径参数）、sqlx、tauri 逐行同预览；没导入 serde 时 derive 仍是结构体；改 axum 的路径，路径那一格标成改过。`axum::routing` 这种来源算导入了 axum。
+- Rust（`languages/rust.test.ts`、`rules/rustLibs.test.ts`，真实解析）：`fixtures/rustLang.rs` 的导入、结构体、枚举、实现（方法挂在方法表的子行上）、函数（异步、分情况）、特质逐行同预览；给结构体加一个字段，字段表那一行标成新增。`fixtures/rustComments.rs` 开头连着写的 `//` 合成一段，是文件的说明，预览是去掉 `//` 的三段 Markdown；别的注释挂到后面那一项（「注释」一行），行尾 `//` 不单独成块，`//!` 连着几行合成一段、是文件的说明，`///` 并进下一个函数当说明、普通注释同时是它的「注释」，`mod`、`impl` 身体里同一套。编译属性：Tauri `main.rs` 的 `cfg_attr` 卡片逐行（属性的着色、「非 调试构建」、「整个 crate」、windows 子系统的说明），别的文件顶层的 `allow` 是本模块、列出 lint 名，认不得的属性没有说明、不知道文件名时是所在模块，`cfg_attr` 里几个属性是一张表、套着的条件加括号，`isCrateRoot` 的几种路径。`fixtures/rustLibs.rs` 的 serde（改名、不输出、字段名改驼峰）、thiserror（展示、透传来源）、axum（方法、路径、路径参数）、sqlx、tauri 逐行同预览；没导入 serde 时 derive 仍是结构体；改 axum 的路径，路径那一格标成改过。`axum::routing` 这种来源算导入了 axum。
 - Dockerfile：
   - 语言插件（`languages/dockerfile.test.ts`，真实解析）：两份 luffy 的 Dockerfile 的代码块树（同原型，后端的三行注释是阶段说明）；并块（紧挨着才并，空行、注释、别的指令隔开，COPY 要从同一个地方，ADD、heredoc 的 COPY 不并，第一个 FROM 之前的是顶层）；ONBUILD 和各种设置；facts（解析指令、阶段的名称 / 序号 / 说明 / 标签 / 摘要 / 平台 / 接着前面的阶段、构建参数和环境变量并块、健康检查两种写法和 NONE、启动）；嵌着的 shell 的几段（续行去掉、heredoc 正文）；数组写法的命令（VOLUME、SHELL 的数组不算）；同一文件里的名字（阶段名在 --from、--mount 的 from、FROM 里，变量）；中文名；着色。
   - 中文直译（`translators/dockerfileZh.test.ts`，走 `readBlockViews`，RUN 交给 bash 的插件）：两份 luffy 的 Dockerfile 整份逐行同 `NEXT_READING`、`BACKEND_READING`；阶段的各种写法、变量的展开和注解、RUN 的选项 / 数组写法 / heredoc / 一条循环 / 带重定向的一串、没有 shell 插件时照抄、复制和 ADD、设置、健康检查、启动；阶段名和表里变量名的源码下标、RUN 的源码按 shell 着色。
@@ -2234,14 +2279,14 @@ vscode/webview-ui/code-reader.html + src/codeReader/  预览界面（React，Vit
 - 库规则的引用：引用标的不是自己、规则没给 `resolve`、段没带下标时当替身不合约定；查引用交给标它的规则，规则不在、没给 `resolve`、出错时记下来、当作没有定义；视图数据里的引用（下标 → 引用）只从规则认领的块的属性表里取，查定义时是引用的问规则、其余问语言扩展，只对记下它的那个文档版本有效（`editor/definitionSources.test.ts`）。
 - 工作区索引（内存里的工作区，`MemoryIndexHost`）：第一次查才建、同一个 id 只建一份；查到的是名字的行列（列按 UTF-16）、照文件和行排好；预筛不过的不解析；改了只重看那一份、新建加进来、删目录连里面的去掉；新建 / 删掉问过在不在的文件（`__init__.py`）时问过它的文件重看；建索引期间的改动建好后补上；读不了、规则出错的记下来、别的照常；dispose 后不再盯着。还要跳过的文件（`workspaceScope.test.ts`，内存里的文件夹）：子目录里 `.git` 是文件的 git worktree、`.git` 是目录的子仓库整个跳过，工作区自己的 `.git` 不算；`.gitignore` 忽略的目录跳过，每层规则相对那一层、取反照 gitignore 写法，`.ignore` 也读；`search.useIgnoreFiles` 关着时不读忽略文件、嵌套的 checkout 照样跳过；同一个目录只查一次。
 - 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；没注解的类属性、字段中间的方法照源码顺序是子块，「编辑」写回整个类。
+- 枚举（`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；没注解的类属性、字段中间的方法照源码顺序是子块，「编辑」写回整个类。
 - Pydantic 数据模型（`rules/pydantic.test.ts`）：`fixtures/aigcMetadata.py` 的 `AIGCMetadata` 逐字同上面的样例（7 个无默认值字段、选项「严格 · 禁止多余字段」、`model_config` 不单成一块），`TextTrace` 的可空字段默认值是「空」；`fixtures/createShareRequest.py` 的 `CreateShareRequest` 逐字核对字段、说明、长度约束，`@field_validator` 仍是子块；种类 `pydantic.model`、叫「数据模型」、颜色、图标 `braces`；同一文件里继承模型的也算，`TypedDict`、`NamedTuple`、普通类、没导入 pydantic 的不是；别名、`Field` 的默认值 / `default_factory` / 约束、说明优先于注释，`ClassVar` 和没注解的类属性留下；类型里的名字带源码下标；索引只收本文件里能确定的模型、没写 `BaseModel` 的文件不解析，别的文件里的父类查不到先当普通类、查到再换成卡片；差异：加一个字段标新增，改一个默认值标那一格。
 - 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` 类型别名，普通类不认。路由器卡片：`fixtures/routes.py` 的 `router` 逐字同上面的样例，名字、颜色、图标、列名、编辑范围、定义范围；接口表的函数名带下标、路径里的 `{user_id}` 各 `refers` 到各自函数的参数、方法的颜色；接口卡片的「路由器」行排在说明后面、名字带下标指回路由器；写了依赖、默认响应才有这两行，`FastAPI()` 没有前缀，属性 docstring 是说明，没挂接口时「0 个」、不画表格。
-- React 组件（`rules/reactTree.test.ts`、`rules/react.test.ts`，luffy 的九个真实组件）：认组件（七个文件里的组件、小写工具函数和不渲染 JSX 的不认；memo / forwardRef 包着的、默认导出、文件末尾 export 的、null 和 JSX 混着返回的；组件体里的语句、提前返回的 if 里的 return 认得出在哪个组件里）；构造参数（行内类型字面量、同文件接口带 JSDoc、回调、children、默认值、改名、其余属性、方法签名、`FC<Props>`、`forwardRef<R, Props>`、导入的类型查不到和查到了）；组件体的归类、名字用在哪（副作用、渲染时重置、挂在 `<main>` 的 ref、处理函数绑在每个按钮上）；渲染大纲（原生标签、组件、类、条件、三元、列表、片段、注释、几处返回）和 className 的写法。卡片：组件卡片只有名称 / 说明 / 构造参数，组件体照源码顺序是子块，`"use client"` 和 JSDoc 不单独成块（文件里没组件时 `"use client"` 照常成块）；`fixtures/planChecklist.tsx.txt` 逐字同上面的样例；QueuedBubble 的状态、引用、变量、副作用、两个事件处理函数、渲染输出照源码顺序、函数体是子卡片，提前 `return null` 是如果卡片；状态的更新位置、引用的使用位置只写名字和位置；数据源的几种说明；useMemo / useCallback 的派生值、带清理的副作用、触发时机的几种写法、没绑在 JSX 上的处理函数写由谁调用；直接返回 JSX 的组件把大纲写在卡片里；九个文件认领下来都合约定；差异：加一个属性、改一个副作用的依赖，组件卡片属性表那一行新加、副作用卡片「触发时机」逐截标。宿主：`libraries` 空的规则都启用；略去的块不出块、有子块的不能略去。webview：小标签、条件小框、类名小标的样子（`SegmentText.test.tsx`）。
+- React 组件（`rules/reactTree.test.ts`、`rules/react.test.ts`，luffy 的九个真实组件）：认组件（七个文件里的组件、小写工具函数和不渲染 JSX 的不认；memo / forwardRef 包着的、默认导出、文件末尾 export 的、null 和 JSX 混着返回的；组件体里的语句、提前返回的 if 里的 return 认得出在哪个组件里）；构造参数（行内类型字面量、同文件接口带 JSDoc、回调、children、默认值、改名、其余属性、方法签名、`FC<Props>`、`forwardRef<R, Props>`、导入的类型查不到和查到了）；组件体的归类、名字用在哪（副作用、渲染时重置、挂在 `<main>` 的 ref、处理函数绑在每个按钮上）；渲染大纲（原生标签、组件、类、条件、三元、列表、片段、注释、几处返回）和 className 的写法。卡片：组件卡片只有名称 / 说明 / 构造参数，组件体照源码顺序是子块，`"use client"` 不单独成块（文件里没组件时、它挂着注释时照常成块），JSDoc 是组件块的说明；`fixtures/planChecklist.tsx.txt` 逐字同上面的样例；QueuedBubble 的状态、引用、变量、副作用、两个事件处理函数、渲染输出照源码顺序、函数体是子卡片，提前 `return null` 是如果卡片；状态的更新位置、引用的使用位置只写名字和位置；数据源的几种说明；useMemo / useCallback 的派生值、带清理的副作用、触发时机的几种写法、没绑在 JSX 上的处理函数写由谁调用；直接返回 JSX 的组件把大纲写在卡片里；九个文件认领下来都合约定；差异：加一个属性、改一个副作用的依赖，组件卡片属性表那一行新加、副作用卡片「触发时机」逐截标。宿主：`libraries` 空的规则都启用；略去的块不出块、有子块的不能略去。webview：小标签、条件小框、类名小标的样子（`SegmentText.test.tsx`）。
 - 规则查别的文件里的定义（`ruleLookups.test.ts`）：第一遍当没查到、记下问了什么（同一索引同名的只记一处）；查到后叫重排，交出定义处正是的那一项；同一版本不再查；索引里没有同名的不问语言扩展，定义处不是索引里的项算没有，没变不叫重排；新版本先用上一版的、再查、变了才叫重排；语言扩展没答时已知的不动、隔一会儿再查。
 - 带自己颜色的词（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`）。
+- 异常（`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 子句对得上。
 - 侧栏行上的菜单（`explorer/rowMenus.test.ts`，读 `package.json`）：行尾按钮先「复制」子菜单再注释，有没有注释换「添加 / 编辑注释」，工作区根都没有；「复制」子菜单带 `$(copy)`，注释图标 `$(note)` / `$(edit)`；子菜单和右键菜单里文件四项、目录三项（有没有注释一样）、菜单上的字；复制命令都登记了、和代码里的命令表一致、命令面板里藏起来；「在系统文件管理器中显示」文件和目录（含未提交、有注释）都有、工作区根和分组行没有、审查时也有，三个系统各只出自己那一项、字和 VS Code 自带的一样，自成一组排在复制和注释中间，不挂行尾按钮、命令面板里藏起来。
diff --git a/vscode/src/codeReader/blockView.test.ts b/vscode/src/codeReader/blockView.test.ts
index f3d9473..e46a4f5 100644
--- a/vscode/src/codeReader/blockView.test.ts
+++ b/vscode/src/codeReader/blockView.test.ts
@@ -4,9 +4,12 @@ import { describe, expect, it } from 'vitest'
 import { readBlockViews, readDefinitionKind, toBlockViews } from './blockView'
 import { replaceLines } from './editText'
 import { createBashAdapter } from './languages/bash'
+import { createDockerfileAdapter } from './languages/dockerfile'
 import { createPythonAdapter } from './languages/python'
 import { createTypeScriptAdapter } from './languages/typescript'
-import { previewText, propertyLines, readFixture, runtime, WASM_DIR, withBlocks } from './testSupport'
+import { commentText, DOCKERFILE_WASM_DIR, previewText, propertyLines, readFixture, runtime, WASM_DIR, withBlocks } from './testSupport'
+import { bashZhTranslator } from './translators/bashZh'
+import { dockerfileZhTranslator } from './translators/dockerfileZh'
 import { pythonZhTranslator } from './translators/pythonZh'
 import { typescriptZhTranslator } from './translators/typescriptZh'
 
@@ -159,7 +162,8 @@ describe('blockView', () => {
       '    管理员可查看任意用户，普通用户只能查看自己。',
       '    """',
     ])
-    expect(getUser?.children[0]).toMatchObject({ kind: 'comment', startLine: 38, endLine: 38 })
+    expect(getUser?.children[0]).toMatchObject({ kind: 'if', startLine: 38, endLine: 40, headerEndLine: 39 })
+    expect(commentText(getUser?.children[0])).toBe('非管理员只能查看自己')
   })
 
   it('类的说明同样算在类块的头部里：JSDoc 连着中间的装饰器，docstring 连着它前面的注释', async () => {
@@ -385,3 +389,68 @@ describe('blockView', () => {
     expect(await kind('pass')).toBeUndefined()
   })
 })
+
+describe('卡片上的「注释」一行', () => {
+  it('luffy 的 acquisition/repository.py：讲类的注释是类卡片的「注释」一行（排在名称后面），类的编辑范围、源码连着这几行', async () => {
+    const source = readFixture('acquisitionRepository.py')
+    const list = await views(py, 'python', pythonZhTranslator, source)
+    expect(list.some(view => view.kind === 'comment')).toBe(false)
+    const repo = list.find(view => view.kind === 'class')
+    expect(repo).toMatchObject({ startLine: 12, headerEndLine: 20, commentRow: 1, commentTarget: { kind: 'replace', startLine: 12, endLine: 15 } })
+    expect('properties' in repo! && repo.properties.map(row => row.label).slice(0, 3)).toEqual(['名称', '注释', '访问级别'])
+    expect(commentText(repo)).toBe([
+      'luffy_agent.user.models.User 在各方法体内按需局部导入 (非模块顶层):',
+      'user 包 __init__ 会级联加载到 acquisition.service, 而 acquisition 是整个',
+      '应用最早被 import 的域之一 (见 api_routers.py 的 include 顺序), 顶层导入',
+      '会与该级联互相等待, 构成循环导入。',
+    ].join('\n'))
+    expect(repo?.code.split('\n').slice(0, 7)).toEqual([
+      '# luffy_agent.user.models.User 在各方法体内按需局部导入 (非模块顶层):',
+      '# user 包 __init__ 会级联加载到 acquisition.service, 而 acquisition 是整个',
+      '# 应用最早被 import 的域之一 (见 api_routers.py 的 include 顺序), 顶层导入',
+      '# 会与该级联互相等待, 构成循环导入。',
+      '',
+      '',
+      'class AcquisitionChannelRepository(',
+    ])
+    expect(replaceLines(source, repo!.startLine, repo!.endLine, repo!.code)).toBe(source)
+  })
+
+  it('说明和注释都有时排成 名称、说明、注释；几段注释是几段 Markdown；一行译文的卡片「注释」一行排在译文下面', async () => {
+    const source = [
+      'import { readFile } from \'node:fs/promises\'',
+      '',
+      '// 讲 load',
+      '',
+      '// 第二段',
+      '/** 读出配置。 */',
+      'export async function load(path: string) {',
+      '  // 先检查',
+      '  if (!path) {',
+      '    return null',
+      '  }',
+      '  return readFile(path)',
+      '}',
+    ].join('\n')
+    const [, load] = await views(ts, 'typescript', typescriptZhTranslator, source)
+    expect('properties' in load && load.properties.map(row => row.label).slice(0, 4)).toEqual(['名称', '说明', '注释', '访问级别'])
+    expect(commentText(load)).toBe('讲 load\n\n第二段')
+    expect(load).toMatchObject({ startLine: 2, commentRow: 2, commentTarget: { kind: 'replace', startLine: 2, endLine: 4 } })
+    const [check, returned] = load.children
+    expect(check).toMatchObject({ kind: 'if', startLine: 7, commentRow: 0, rows: [{ label: '注释', value: { markdown: '先检查' } }] })
+    expect(returned).toMatchObject({ kind: 'return', commentTarget: { kind: 'insert', line: 11 } })
+    expect(returned).not.toHaveProperty('commentRow')
+  })
+
+  it('嵌着的代码里的块不能写注释：没有 commentTarget', async () => {
+    const shell = createBashAdapter(WASM_DIR)
+    const source = 'FROM node:22\nRUN npm ci && npm run build\n'
+    const { blocks } = await readBlockViews(runtime, createDockerfileAdapter(DOCKERFILE_WASM_DIR), dockerfileZhTranslator, 'dockerfile', source, {
+      embedded: languageId => languageId === 'shellscript' ? { adapter: shell, translator: bashZhTranslator } : undefined,
+    })
+    const run = flatten(blocks).find(view => view.kind === 'run')
+    expect(run?.commentTarget).toEqual({ kind: 'insert', line: 1 })
+    expect(run?.children.length).toBeGreaterThan(0)
+    expect(run?.children.every(step => step.commentTarget === undefined)).toBe(true)
+  })
+})
diff --git a/vscode/src/codeReader/blockView.ts b/vscode/src/codeReader/blockView.ts
index b0e2d2b..d66982f 100644
--- a/vscode/src/codeReader/blockView.ts
+++ b/vscode/src/codeReader/blockView.ts
@@ -5,7 +5,7 @@ import type { ImportedName } from './symbolLinks'
 import { blockAttributes } from './attributes'
 import { KIND_ICONS } from './contract'
 import { commonIndent, splitLines } from './editText'
-import { commentSpan } from './languages/shared'
+import { isCommentBlock } from './languages/shared'
 import { activeRules, claimBlock, importsIn } from './libraryRules'
 import { BlockAnchors } from './qa/anchor'
 import { importedNames } from './symbolLinks'
@@ -38,9 +38,13 @@ interface BlockViewBase {
    * 同一个 id 只留第一个。项目入口那一块的第一个换成入口（见 entries/entryMarks.ts）。webview 按这个画图标，不自己用种类查。
    */
   concepts: BlockConcept[]
-  /** 能重写的那段注释的起止行，0 起。注释块是整块；函数、类等是它的说明。没有说明就没有，不显示重写按钮。 */
-  commentStartLine?: number
-  commentEndLine?: number
+  /**
+   * 「注释」一行（讲这块的普通注释，BlockShape.comments）排在第几行，0 起：属性表卡片是 properties 里的下标，
+   * 一行译文的卡片是 rows 里的下标。没有注释就没有。
+   */
+  commentRow?: number
+  /** 「重写注释」写到哪（见 CommentTarget）；不能写注释的块（嵌着的代码里的、语言没说行注释怎么写又还没有注释的）没有。 */
+  commentTarget?: CommentTarget
   /** 库规则的卡片才有：筛选栏里这个种类的名字，卡片边框的颜色（RuleCard.badge）。图标在 concepts 里。预览同类块一样默认收起它的子块。 */
   badge?: KindBadge
   /** 库规则挂在父卡片子行上的子块才有（见 RuleSlot）：展开时画在父卡片属性表第 row 行下面，不排在父卡片的子块里。 */
@@ -55,10 +59,19 @@ export interface BlockSlot {
 }
 
 /**
- * 发给 webview 的一块（可序列化）：函数、类、枚举、异常、导入、常量、变量块和库规则的卡片预览时是属性表，注释块是 Markdown 说明，其余是一行译文。
- * 一行译文下面依次是：跨几行写的调用摊开各个实参的表（TextTranslation.table），块的说明（TextBlock.doc，翻译插件给的 Markdown 原文）。
+ * 「重写注释」写到哪，行号 0 起：replace 是换掉 startLine..endLine 这几行（块前面那几段普通注释；文件开头的说明卡片是它自己），
+ * insert 是块还没有注释，新写一段插在 line 这一行上面（块的第一行），缩进同这一行。
  */
-export type BlockView = BlockViewBase & ({ translation: PreviewText, table?: PreviewTable, doc?: Markdown } | { properties: PropertyRow[] })
+export type CommentTarget
+  = | { kind: 'replace', startLine: number, endLine: number }
+    | { kind: 'insert', line: number }
+
+/**
+ * 发给 webview 的一块（可序列化）：函数、类、枚举、异常、导入、常量、变量块和库规则的卡片预览时是属性表，文件开头的说明是 Markdown，其余是一行译文。
+ * 一行译文下面依次是：跨几行写的调用摊开各个实参的表（TextTranslation.table），块的说明（TextBlock.doc，翻译插件给的 Markdown 原文），
+ * 几行属性（rows：「注释」一行）。
+ */
+export type BlockView = BlockViewBase & ({ translation: PreviewText, table?: PreviewTable, doc?: Markdown, rows?: PropertyRow[] } | { properties: PropertyRow[] })
 
 interface Line { start: number, end: number }
 
@@ -211,9 +224,20 @@ function later(a: SpanEnd, b: SpanEnd): SpanEnd {
   return b.endIndex > a.endIndex ? b : a
 }
 
-/** 各子孙块的头部、节点里最靠后的结尾，和 end 比取靠后的：子孙一般写在块的节点里，Dockerfile 阶段的指令写在 FROM 后面。 */
+/** 讲这块的注释（BlockShape.comments）里最靠后的结尾，和 end 比取靠后的：这一层最后一块代码后面的注释挂在它上面。 */
+function commentsEnd(block: CodeBlock, end: SpanEnd): SpanEnd {
+  return (block.comments ?? []).reduce((acc, comment) => later(acc, comment.header), end)
+}
+
+/** 块的完整范围从哪起：头部和讲它的注释里最靠前的那个开头（注释写在块上面）。 */
+function blockStart(block: CodeBlock): Pick<SourceSpan, 'startIndex' | 'startRow'> {
+  const first = block.comments?.[0]?.header
+  return first && first.startIndex < block.header.startIndex ? first : block.header
+}
+
+/** 各子孙块的头部、节点、讲它的注释里最靠后的结尾，和 end 比取靠后的：子孙一般写在块的节点里，Dockerfile 阶段的指令写在 FROM 后面。 */
 function descendantsEnd(blocks: readonly CodeBlock[], end: SpanEnd): SpanEnd {
-  return blocks.reduce((acc, child) => descendantsEnd(child.children, later(later(acc, child.header), nodeEnd(child.node))), end)
+  return blocks.reduce((acc, child) => descendantsEnd(child.children, commentsEnd(child, later(later(acc, child.header), nodeEnd(child.node)))), end)
 }
 
 /** index 之前最后一个非空白字符的结尾，不早于头部开头。 */
@@ -224,28 +248,49 @@ function lastCharBefore(source: string, header: SourceSpan, index: number): Span
   return { endIndex: end, endRow: header.startRow + splitLines(source.slice(header.startIndex, end)).length - 1 }
 }
 
+/** 一块在源码里的完整范围（whole，编辑范围），和不算讲它的注释时这条语句的范围（statement）。 */
+interface BlockSpan {
+  whole: SourceSpan
+  statement: SourceSpan
+}
+
 /**
- * 一串兄弟块各自在源码里的完整范围：从头部开头，到头部、所在语句、各子孙块里最靠后的那个字符。
+ * 一串兄弟块各自在源码里的范围：语句从头部开头，到头部、所在语句、各子孙块里最靠后的那个字符；完整范围再连同讲它的注释。
  * 语言插件把 else、catch 这类子句展平成紧跟着的兄弟块，它们的节点都落在打头那块的节点（整条 if / try）里：
- * 这条语句按各块的开头切开，每块到下一块开头之前最后一个非空白字符为止，最后一块到语句结尾（Shell 的 fi 归它）。
+ * 这条语句按各块的开头切开，每块到下一块开头（连同讲它的注释）之前最后一个非空白字符为止，最后一块到语句结尾（Shell 的 fi 归它）。
  */
-function blockSpans(list: readonly CodeBlock[], source: string): SourceSpan[] {
+function blockSpans(list: readonly CodeBlock[], source: string): BlockSpan[] {
   let statement: Node | undefined
   return list.map((block, i) => {
     if (!statement || block.node.startIndex < statement.startIndex || block.node.endIndex > statement.endIndex)
       statement = block.node
     const next = list[i + 1]
-    const nextStart = next && Math.min(next.header.startIndex, next.node.startIndex)
+    const nextStart = next && Math.min(blockStart(next).startIndex, next.node.startIndex)
     const until = nextStart !== undefined && nextStart < statement.endIndex ? lastCharBefore(source, block.header, nextStart) : nodeEnd(statement)
-    const { endIndex, endRow } = descendantsEnd(block.children, later(block.header, until))
-    return { startIndex: block.header.startIndex, endIndex, startRow: block.header.startRow, endRow }
+    const end = descendantsEnd(block.children, later(block.header, until))
+    const wholeEnd = commentsEnd(block, end)
+    const start = blockStart(block)
+    return {
+      whole: { startIndex: start.startIndex, startRow: start.startRow, endIndex: wholeEnd.endIndex, endRow: wholeEnd.endRow },
+      statement: { startIndex: block.header.startIndex, startRow: block.header.startRow, endIndex: end.endIndex, endRow: end.endRow },
+    }
   })
 }
 
+/**
+ * 「注释」一行插进属性表：排在第一行（名称这类讲它是谁的一行）后面，有说明（值是 Markdown 的一行）时排在说明后面。
+ * 返回新的属性表和「注释」一行的下标。
+ */
+function withCommentRow(rows: readonly PropertyRow[], row: PropertyRow): { rows: PropertyRow[], at: number } {
+  const doc = rows.findIndex(item => 'markdown' in item.value)
+  const at = doc >= 0 ? doc + 1 : Math.min(1, rows.length)
+  return { rows: [...rows.slice(0, at), row, ...rows.slice(at)], at }
+}
+
 /**
  * 代码块树 → 视图数据：块的完整范围整行源码去共同缩进、按语法树着色，调用翻译插件。
  * 每块先问启用的库规则，认领了就换成规则给的替身（见 RuleBlock）：规则的卡片，或认成的属性表块（交给翻译插件排，同语言插件报的这种块），
- * 并进去的子块不再单独成块。
+ * 并进去的子块不再单独成块。讲块的注释（BlockShape.comments）排成卡片上的「注释」一行（见 withCommentRow）。
  */
 export function toBlockViews(
   blocks: CodeBlock[],
@@ -281,8 +326,9 @@ export function toBlockViews(
   /**
    * 一种语言的块怎么转：用这种语言的源码、翻译插件和库规则（嵌着的代码没有库规则）。
    * 转的是一串兄弟块：各块的完整范围（编辑范围）按这一串算（见 blockSpans），id 是 prefix 接上它在这一串里的位置（从 from 数起）。
+   * writable 为假时（嵌着的代码）块不能写注释：新写的行注释会写进外层语言的那几行里。
    */
-  function layer(layerBlocks: readonly CodeBlock[], layerDocument: SourceDocument, layerTranslator: Translator | undefined, layerRules: RuleRun): (list: readonly CodeBlock[], prefix: string, scope: string, from?: number) => BlockView[] {
+  function layer(layerBlocks: readonly CodeBlock[], layerDocument: SourceDocument, layerTranslator: Translator | undefined, layerRules: RuleRun, writable: boolean): (list: readonly CodeBlock[], prefix: string, scope: string, from?: number) => BlockView[] {
     const imports = importsIn(layerBlocks)
     const active = activeRules(layerRules.rules, imports)
     const context: RuleContext = {
@@ -308,7 +354,7 @@ export function toBlockViews(
         return []
       const steps = part.steps.blocks
       const [only] = steps
-      return layer(steps, part.document, part.translator, NO_RULES)(steps.length === 1 && only ? only.children : steps, `${id}.`, scope, from)
+      return layer(steps, part.document, part.translator, NO_RULES, false)(steps.length === 1 && only ? only.children : steps, `${id}.`, scope, from)
     }
     /**
      * 这块的概念，从左到右，同一个 id 只留第一个：语言的种类（图标、名字用内置种类和翻译插件起的种类名），
@@ -337,9 +383,42 @@ export function toBlockViews(
       }
       return concepts
     }
-    function commentLines(block: CodeBlock): { commentStartLine: number, commentEndLine: number } | undefined {
-      const span = commentSpan(block)
-      return span && { commentStartLine: span.startLine, commentEndLine: span.endLine }
+    /** 「注释」一行：讲这块的几段注释（BlockShape.comments）各读成一段 Markdown，空行隔开；名字是翻译插件给种类 comment 起的。没有注释、没有翻译插件时没有。 */
+    function commentRow(block: CodeBlock): PropertyRow | undefined {
+      if (!layerTranslator || !block.comments)
+        return undefined
+      const parts = block.comments.flatMap((comment) => {
+        const { text } = layerTranslator.translate(comment, layerDocument)
+        return 'markdown' in text && text.markdown !== '' ? [text.markdown] : []
+      })
+      const label = layerTranslator.attributeNames?.values.kind?.comment ?? 'comment'
+      return parts.length > 0 ? { label, value: { markdown: parts.join('\n\n') } } : undefined
+    }
+    /** 属性表卡片的属性表连同「注释」一行（见 withCommentRow）。 */
+    function cardRows(block: CodeBlock, rows: PropertyRow[]): Pick<BlockView, 'commentRow'> & { properties: PropertyRow[] } {
+      const row = commentRow(block)
+      if (!row)
+        return { properties: rows }
+      const { rows: properties, at } = withCommentRow(rows, row)
+      return { properties, commentRow: at }
+    }
+    /** 「重写注释」写到哪（见 CommentTarget）：块前面的普通注释换掉，没有就新写在块上面。 */
+    function commentTarget(block: CodeBlock): Pick<BlockView, 'commentTarget'> {
+      if (!writable)
+        return {}
+      if (isCommentBlock(block))
+        return { commentTarget: { kind: 'replace', startLine: block.header.startRow, endLine: block.header.endRow } }
+      const leading = (block.comments ?? []).filter(comment => comment.header.startIndex < block.header.startIndex)
+      const [first] = leading
+      const last = leading.at(-1)
+      if (first && last)
+        return { commentTarget: { kind: 'replace', startLine: first.header.startRow, endLine: last.header.endRow } }
+      return layerDocument.language.lineComment ? { commentTarget: { kind: 'insert', line: block.header.startRow } } : {}
+    }
+    /** 一行译文的卡片：译文、实参表、说明，有注释时下面再排「注释」一行。 */
+    function textCard(block: TextBlock): Pick<BlockView, 'commentRow'> & ReturnType<typeof textView> & { rows?: PropertyRow[] } {
+      const row = commentRow(block)
+      return { ...textView(block), ...(row && { rows: [row], commentRow: 0 }) }
     }
 
     /** 块照它自己的样子（语言插件报的，或库规则认成的属性表块）：编辑范围是 span，头部是块自己那部分，子块照常交给各规则看。scope 见 BlockAnchors.place */
@@ -355,19 +434,19 @@ export function toBlockViews(
         ...(name && { defines: { startIndex: name.startIndex, endIndex: name.endIndex } }),
         attributes: blockAttributes(block),
         concepts: blockConcepts(block),
-        ...commentLines(block),
+        ...commentTarget(block),
         children: [
           ...list(block.children, `${id}.`, inner),
           ...embeddedChildren(block, id, inner, block.children.length),
         ],
-        ...('facts' in block ? { properties: layerTranslator ? layerTranslator.describe(block, layerDocument) : [] } : textView(block)),
+        ...('facts' in block ? cardRows(block, layerTranslator ? layerTranslator.describe(block, layerDocument) : []) : textCard(block)),
       }
     }
     /**
      * 块先问启用的库规则，没认领就照它自己的样子。认领了的：规则讲的是整条语句，头部就是整个范围；
      * 规则没并进来的子块（方法、别的成员）不管写在哪，都照源码顺序留作它的子块。规则略去的块（讲在了别的卡片里）不出块。
      */
-    function build(block: CodeBlock, span: SourceSpan, id: string, scope: string): BlockView | undefined {
+    function build(block: CodeBlock, { whole: span, statement }: BlockSpan, id: string, scope: string): BlockView | undefined {
       const claim = active.length > 0 ? claimBlock(block, active, context, layerRules.report) : undefined
       if (!claim)
         return plain(block, span, id, scope)
@@ -376,25 +455,25 @@ export function toBlockViews(
         return undefined
       const kept = block.children.filter(child => !replacement.absorbs.includes(child))
       if ('as' in replacement) {
-        const { attributes } = block
-        return plain({ ...replacement.as, node: block.node, header: span, children: kept, ...(attributes && { attributes }) }, span, id, scope)
+        const { attributes, comments } = block
+        return plain({ ...replacement.as, node: block.node, header: statement, children: kept, ...(attributes && { attributes }), ...(comments && { comments }) }, span, id, scope)
       }
       const { kind, badge, rows, defines, attributes } = replacement
       const slots = new Map((replacement.slots ?? []).map(({ block: child, row, item }): [CodeBlock, BlockSlot] => [child, { row, item }]))
-      const { anchor, inner } = anchors.place(scope, kind, defines && source.slice(defines.startIndex, defines.endIndex), rowsText(span))
+      const { anchor, inner } = anchors.place(scope, kind, defines && source.slice(defines.startIndex, defines.endIndex), rowsText(statement))
       return {
         id,
         anchor,
         kind,
         ...sourceRows(span),
-        headerEndLine: span.endRow,
+        headerEndLine: statement.endRow,
         ...(defines && { defines: { startIndex: defines.startIndex, endIndex: defines.endIndex } }),
         attributes: { ...blockAttributes(block), ...attributes, kind },
         concepts: blockConcepts(block, replacement),
-        ...commentLines(block),
+        ...commentTarget(block),
         badge,
         children: list(kept, `${id}.`, inner, 0, slots),
-        properties: rows,
+        ...cardRows(block, rows),
       }
     }
     /** 一串兄弟块转成视图数据；略去的块不占位置，id 按出了块的往下数。slots 是父卡片挂在它属性表子行上的那几块（见 BlockSlot）。 */
@@ -412,7 +491,7 @@ export function toBlockViews(
     return list
   }
 
-  return layer(blocks, document, translator, rules)(blocks, '', '')
+  return layer(blocks, document, translator, rules, true)(blocks, '', '')
 }
 
 /**
diff --git a/vscode/src/codeReader/commentRewrite.test.ts b/vscode/src/codeReader/commentRewrite.test.ts
index 97d683e..46e3437 100644
--- a/vscode/src/codeReader/commentRewrite.test.ts
+++ b/vscode/src/codeReader/commentRewrite.test.ts
@@ -1,6 +1,14 @@
+import type { BlockView, CommentTarget } from './blockView'
+import type { CommentEdit, CommentRewriteDeps, CommentRewriteJob, WriteResult } from './commentRewrite'
 import { describe, expect, it } from 'vitest'
-import { COMMENT_SKILL, commentProse, commentRewritePrompt, commentSource, isModuleComment, modelCommentBody, refillComment } from './commentRewrite'
-import { commonIndent, replaceLines } from './editText'
+import { toBlockViews } from './blockView'
+import { COMMENT_SKILL, commentEdit, commentRewritePrompt, commentSource, createCommentParser, findBlock, refillComment, rewriteBlockComment } from './commentRewrite'
+import { commonIndent, replaceLines, splitLines } from './editText'
+import { createPythonAdapter } from './languages/python'
+import { createTypeScriptAdapter } from './languages/typescript'
+import { WASM_DIR, withBlocks } from './testSupport'
+import { pythonZhTranslator } from './translators/pythonZh'
+import { typescriptZhTranslator } from './translators/typescriptZh'
 
 /** 和预览写回同一条路：正文套回壳，再按原来的缩进替换这几行。 */
 function rewrite(file: string, start: number, end: number, body: string): string {
@@ -103,66 +111,193 @@ describe('重写注释后套回原来的壳', () => {
     expect(refillComment('const x = 1', '新')).toBeUndefined()
     expect(refillComment('# 旧', '   ')).toBeUndefined()
   })
-
-  it('给模型的正文不带定界符', () => {
-    expect(commentProse('"""旧说明"""')).toBe('旧说明')
-    expect(commentProse('# 旧说明\n# 第二行')).toBe('旧说明\n第二行')
-    expect(commentProse('/**\n * 旧说明\n */')).toBe('旧说明')
-    expect(commentProse('// 旧说明')).toBe('旧说明')
-  })
 })
 
+const line = (value: unknown): string => JSON.stringify(value)
+/** 模型调 StructuredOutput 交结果：工具输入逐段来，再是整条消息 */
+function structuredLines(body: string): string[] {
+  const json = JSON.stringify({ body })
+  return [
+    line({ type: 'stream_event', event: { type: 'content_block_start', content_block: { type: 'tool_use', name: 'StructuredOutput', input: {} } } }),
+    line({ type: 'stream_event', event: { type: 'content_block_delta', delta: { type: 'input_json_delta', partial_json: json.slice(0, 12) } } }),
+    line({ type: 'stream_event', event: { type: 'content_block_delta', delta: { type: 'input_json_delta', partial_json: json.slice(12) } } }),
+    line({ type: 'stream_event', event: { type: 'content_block_stop' } }),
+    line({ type: 'assistant', message: { content: [{ type: 'tool_use', name: 'StructuredOutput', input: { body } }] } }),
+  ]
+}
+const resultLine = (fields: Record<string, unknown>): string => line({ type: 'result', subtype: 'success', is_error: false, ...fields })
+
 describe('重写注释的提示', () => {
-  it('文件顶上的三引号：上下文是去掉这段之后的文件，太长会截掉并说明', () => {
-    const rest = Array.from({ length: 130 }, (_, index) => `line ${index}`).join('\n')
-    const prompt = commentRewritePrompt({
-      comment: '"""旧"""',
-      source: `"""旧"""\n${rest}`,
-      startLine: 0,
-      endLine: 0,
-      earlierKinds: [],
+  it('只有技能命令和代码块在哪：路径:起-止，行号 1 起', () => {
+    expect(commentRewritePrompt('src/acquisition/repository.py', 12, 20)).toBe(`${COMMENT_SKILL} src/acquisition/repository.py:13-21`)
+    expect(commentRewritePrompt('a.ts', 0, 0)).toBe('/ecc:writing-code-comments a.ts:1-1')
+  })
+})
+
+describe('读模型交回的结构化结果', () => {
+  it('正文跟着 StructuredOutput 的输入逐段长出来，读文件是正在做的事；结果以 structured_output 为准', () => {
+    const parse = createCommentParser()
+    const events = [
+      line({ type: 'assistant', message: { content: [{ type: 'tool_use', name: 'Read', input: { file_path: '/w/src/a.py' } }] } }),
+      ...structuredLines('把 `a` 和 `b` 相加。'),
+      resultLine({ result: '{"body":"把 `a` 和 `b` 相加。"}', structured_output: { body: '把 `a` 和 `b` 相加。' } }),
+    ].flatMap(parse)
+    expect(events[0]).toEqual({ kind: 'activity', label: '读取 a.py' })
+    expect(events.filter(event => event.kind === 'text').map(event => 'text' in event && event.text)).toEqual(['把 `', '把 `a` 和 `b` 相加。'])
+    expect(events.at(-1)).toEqual({ kind: 'result', body: '把 `a` 和 `b` 相加。' })
+  })
+
+  it('模型只回了一段话、structured_output 是空的：结果里没有正文；Claude Code 报错时是失败', () => {
+    expect(createCommentParser()(resultLine({ result: '我改好了：把 a 和 b 相加。' }))).toEqual([{ kind: 'result' }])
+    expect(createCommentParser()(resultLine({ result: '', structured_output: { body: '  ' } }))).toEqual([{ kind: 'result' }])
+    expect(createCommentParser()(line({ type: 'result', is_error: true, result: '额度用完了' }))).toEqual([{ kind: 'error', message: '额度用完了' }])
+  })
+})
+
+/** 内存里的一份文件：按行读，写回时同预览一样换掉几行（补回缩进）或在某行上面插几行。 */
+function memoryFile(text: string): { deps: (ask: CommentRewriteDeps['ask']) => CommentRewriteDeps, text: () => string, writes: CommentEdit[] } {
+  let current = text
+  const writes: CommentEdit[] = []
+  const lines = (): string[] => splitLines(current)
+  return {
+    text: () => current,
+    writes,
+    deps: ask => ({
+      lineAt: index => lines()[index],
+      lineCount: () => lines().length,
+      ask,
+      failure: err => `没答成：${err instanceof Error ? err.message : String(err)}`,
+      write: async (edit): Promise<WriteResult> => {
+        writes.push(edit)
+        if (edit.kind === 'replace') {
+          current = replaceLines(current, edit.startLine, edit.endLine, edit.text)
+        }
+        else {
+          const all = lines()
+          current = [...all.slice(0, edit.line), ...edit.text.split('\n'), ...all.slice(edit.line)].join('\n')
+        }
+        return 'written'
+      },
+      signal: new AbortController().signal,
+    }),
+  }
+}
+
+/** 用 Python 语言插件、中文直译把源码读成视图数据，按块的第一行（1 起，含讲它的注释）找到那块。 */
+async function pythonBlock(source: string, line: number): Promise<BlockView> {
+  const py = createPythonAdapter(WASM_DIR)
+  const views = await withBlocks(py, 'python', source, blocks => toBlockViews(blocks, { source, language: py, markers: [] }, pythonZhTranslator))
+  const all = (list: BlockView[]): BlockView[] => list.flatMap(view => [view, ...all(view.children)])
+  const found = all(views).find(view => view.startLine + 1 === line)
+  if (!found)
+    throw new Error(`第 ${line} 行没有块`)
+  return found
+}
+
+function job(block: BlockView, path = 'src/a.py', lineComment = '#'): CommentRewriteJob {
+  if (!block.commentTarget)
+    throw new Error('这块不能写注释')
+  return { target: block.commentTarget, startLine: block.startLine, endLine: block.endLine, path, lineComment }
+}
+
+const SOURCE = [
+  'import os',
+  '',
+  '# 旧的说明',
+  '',
+  '# 第二段',
+  'class Repo:',
+  '    def find(self):',
+  '        return os.sep',
+  '',
+].join('\n')
+
+describe('重写一块代码的注释', () => {
+  it('块前面的注释（几段隔着空行的也算）换成模型交回的正文，套回 # 和缩进；提示只有技能命令和块的范围', async () => {
+    const repo = await pythonBlock(SOURCE, 3)
+    expect(repo.commentTarget).toEqual({ kind: 'replace', startLine: 2, endLine: 4 })
+    const file = memoryFile(SOURCE)
+    const prompts: string[] = []
+    const outcome = await rewriteBlockComment(job(repo), file.deps(async (prompt) => {
+      prompts.push(prompt)
+      return '仓库：按名字找文件。'
+    }))
+    expect(outcome).toEqual({ status: 'done' })
+    expect(prompts).toEqual(['/ecc:writing-code-comments src/a.py:3-8'])
+    expect(file.text()).toBe(SOURCE.replace('# 旧的说明\n\n# 第二段', '# 仓库：按名字找文件。'))
+  })
+
+  it('还没有注释的块：用行注释记号新写一段，插在块上面，缩进同块的第一行；说明（docstring）不动', async () => {
+    const source = 'class Repo:\n    def find(self):\n        """找。"""\n        return 1\n'
+    const find = await pythonBlock(source, 2)
+    expect(find.commentTarget).toEqual({ kind: 'insert', line: 1 })
+    const file = memoryFile(source)
+    expect(await rewriteBlockComment(job(find), file.deps(async () => '按名字找\n\n找不到时返回 1'))).toEqual({ status: 'done' })
+    expect(file.text()).toBe('class Repo:\n    # 按名字找\n    #\n    # 找不到时返回 1\n    def find(self):\n        """找。"""\n        return 1\n')
+  })
+
+  it('文件开头的说明卡片换的是它自己：范围就是这段注释', async () => {
+    const source = '"""旧的模块说明。"""\n\nimport os\n'
+    const header = await pythonBlock(source, 1)
+    expect(header).toMatchObject({ kind: 'comment', commentTarget: { kind: 'replace', startLine: 0, endLine: 0 } })
+    const file = memoryFile(source)
+    const prompts: string[] = []
+    await rewriteBlockComment(job(header), file.deps(async (prompt) => {
+      prompts.push(prompt)
+      return '新的模块说明。'
+    }))
+    expect(prompts).toEqual(['/ecc:writing-code-comments src/a.py:1-1'])
+    expect(file.text()).toBe('"""新的模块说明。"""\n\nimport os\n')
+  })
+
+  it('没交回结构化的正文、模型出错：失败，文件不动', async () => {
+    const repo = await pythonBlock(SOURCE, 3)
+    const silent = memoryFile(SOURCE)
+    expect(await rewriteBlockComment(job(repo), silent.deps(async () => undefined))).toEqual({ status: 'failed', error: '模型没有按要求交回注释正文，没有改文件。' })
+    expect(silent.writes).toEqual([])
+    const broken = memoryFile(SOURCE)
+    expect(await rewriteBlockComment(job(repo), broken.deps(async () => {
+      throw new Error('额度用完了')
+    }))).toEqual({ status: 'failed', error: '没答成：额度用完了' })
+    expect(broken.writes).toEqual([])
+  })
+
+  it('重写期间这块代码变了：失败，不写；被叫停：stopped，不写', async () => {
+    const repo = await pythonBlock(SOURCE, 3)
+    const file = memoryFile(SOURCE)
+    let edited = SOURCE
+    const deps = file.deps(async () => {
+      edited = SOURCE.replace('return os.sep', 'return "/"')
+      return '新说明'
     })
-    expect(prompt?.startsWith(`${COMMENT_SKILL}\n`)).toBe(true)
-    expect(prompt).toContain('只按这个技能重写这一段注释')
-    expect(prompt).toContain('这段注释现在的正文：\n旧')
-    expect(prompt).not.toContain('"""')
-    expect(prompt).toContain('截断了')
-    expect(prompt).toContain('line 0')
-    expect(prompt).not.toContain('line 129')
-  })
-
-  it('普通注释只带后面紧挨着的那一块，不带整份文件', () => {
-    const prompt = commentRewritePrompt({
-      comment: '# 旧',
-      source: '整份文件不该出现',
-      startLine: 4,
-      endLine: 4,
-      earlierKinds: ['function'],
-      following: 'def stay():\n    return 1',
-    })
-    expect(prompt).toContain('def stay():')
-    expect(prompt).not.toContain('整份文件不该出现')
-    expect(isModuleComment('# 旧', [])).toBe(false)
-    expect(isModuleComment('"""旧"""', [])).toBe(true)
-    expect(isModuleComment('"""旧"""', ['function'])).toBe(false)
-  })
-
-  it('函数上的说明用这块代码当上下文，不当成文件顶上的说明', () => {
-    const prompt = commentRewritePrompt({
-      comment: '"""旧说明"""',
-      source: 'def run():\n    """旧说明"""\n    return 1\n\ndef other():\n    return 2',
-      startLine: 1,
-      endLine: 1,
-      earlierKinds: [],
-      attached: 'def run():\n    return 1',
-    })
-    expect(prompt).toContain('def run():')
-    expect(prompt).toContain('return 1')
-    expect(prompt).not.toContain('def other()')
+    const changing: CommentRewriteDeps = { ...deps, lineAt: index => splitLines(edited)[index] }
+    expect(await rewriteBlockComment(job(repo), changing)).toEqual({ status: 'failed', error: '这块代码在重写期间变了，没有写回。' })
+    expect(file.writes).toEqual([])
+
+    const stop = new AbortController()
+    const stopped = memoryFile(SOURCE)
+    const result = await rewriteBlockComment(job(repo), { ...stopped.deps(async () => {
+      stop.abort()
+      return '新说明'
+    }), signal: stop.signal })
+    expect(result).toEqual({ status: 'stopped' })
+    expect(stopped.writes).toEqual([])
+  })
+
+  it('用 // 写 TypeScript 的块：JSDoc 是说明，不当成要换掉的注释', async () => {
+    const ts = createTypeScriptAdapter(WASM_DIR)
+    const source = '/** 读配置。 */\nexport function load() {}\n'
+    const [view] = await withBlocks(ts, 'typescript', source, blocks => toBlockViews(blocks, { source, language: ts, markers: [] }, typescriptZhTranslator))
+    expect(view.commentTarget).toEqual({ kind: 'insert', line: 0 })
+    const edit = commentEdit(view.commentTarget as CommentTarget, index => splitLines(source)[index], '启动时读一次', ts.lineComment)
+    expect(edit).toEqual({ kind: 'insert', line: 0, text: '// 启动时读一次' })
   })
+})
 
-  it('模型套了代码围栏时只留里面的正文', () => {
-    expect(modelCommentBody('```\n新说明\n```')).toBe('新说明')
-    expect(modelCommentBody('   ')).toBeUndefined()
+describe('按记号找块', () => {
+  it('先序找，找不到是 undefined', () => {
+    const tree = [{ anchor: 'a', children: [{ anchor: 'b', children: [] }] }, { anchor: 'c', children: [] }]
+    expect(findBlock(tree, 'b')?.anchor).toBe('b')
+    expect(findBlock(tree, 'x')).toBeUndefined()
   })
 })
diff --git a/vscode/src/codeReader/commentRewrite.ts b/vscode/src/codeReader/commentRewrite.ts
index 8577b6d..526b1b5 100644
--- a/vscode/src/codeReader/commentRewrite.ts
+++ b/vscode/src/codeReader/commentRewrite.ts
@@ -1,16 +1,27 @@
 /**
- * 按注释规范重写一段注释：模型只给新正文，这里套回原来的定界符和缩进。
+ * 「重写注释」：用写注释的技能给一块代码重写（没有就新写）讲它的普通注释。模型只读文件、按 JSON Schema 交回注释正文，
+ * 这里套回原来的定界符和缩进（没有注释时用语言的行注释记号），由扩展写回文件。
  * 认 Python 的三引号、井号行注释，以及块注释和双斜杠行注释。认不出就不改。
  */
 
-import { commonIndent, splitLines } from './editText'
-
-/** 贴给模型的代码最多这么多行，再长就截断并在提示里说明。 */
-export const COMMENT_CONTEXT_LINES = 120
+import type { CommentTarget } from './blockView'
+import { describeToolUse } from '../cc/claudeProgress'
+import { commonIndent } from './editText'
 
 /** 跟在对话框里输入这个命令一样，由 Claude Code 自己加载写注释的技能。 */
 export const COMMENT_SKILL = '/ecc:writing-code-comments'
 
+/** 模型交回的结构（`--json-schema`）：body 是注释正文，不带注释符号。 */
+export const COMMENT_SCHEMA = JSON.stringify({
+  type: 'object',
+  properties: { body: { type: 'string' } },
+  required: ['body'],
+  additionalProperties: false,
+})
+
+/** Claude Code 交结构化结果时调的工具：它的输入就是按 COMMENT_SCHEMA 写的结果。 */
+const STRUCTURED_TOOL = 'StructuredOutput'
+
 const DOUBLE_DOC = '"""'
 const SINGLE_DOC = '\'' + '\'' + '\''
 /** 写在三引号前面的字符串前缀，长的排前面，免得 `r` 吃掉 `rf`。 */
@@ -49,18 +60,6 @@ function docShell(comment: string): DocShell | undefined {
   return { prefix, quote, inner: rest.slice(quote.length, -quote.length) }
 }
 
-/** 三引号里的正文：去掉包着正文的那一层换行，再去掉各行共同多出来的缩进。 */
-function docProse(shell: DocShell): string {
-  let inner = shell.inner
-  if (inner.startsWith('\n'))
-    inner = inner.slice(1)
-  if (inner.endsWith('\n'))
-    inner = inner.slice(0, -1)
-  const lines = inner.split('\n')
-  const extra = commonIndent(lines)
-  return lines.map(line => line.startsWith(extra) ? line.slice(extra.length) : line).join('\n').trim()
-}
-
 /** 收尾那一行、引号前面的空白。正文和引号写在同一行时没有。 */
 function closerIndent(comment: string, quote: string): string {
   const nl = comment.lastIndexOf('\n')
@@ -101,11 +100,10 @@ function refillDoc(comment: string, body: string): string | undefined {
 interface LineShell {
   token: string
   spaced: boolean
-  prose: string
 }
 
-/** 一行 `#` 或 `//` 注释：记号、记号后面有没有空格、空格后面的字。 */
-function lineParts(line: string): { token: string, spaced: boolean, text: string } | undefined {
+/** 一行 `#` 或 `//` 注释：记号、记号后面有没有空格。 */
+function lineParts(line: string): LineShell | undefined {
   let end = 0
   if (line.startsWith('//')) {
     end = 2
@@ -118,8 +116,7 @@ function lineParts(line: string): { token: string, spaced: boolean, text: string
     return undefined
   }
   const gap = line[end]
-  const spaced = gap === ' ' || gap === '\t'
-  return { token: line.slice(0, end), spaced, text: line.slice(spaced ? end + 1 : end) }
+  return { token: line.slice(0, end), spaced: gap === ' ' || gap === '\t' }
 }
 
 function lineShell(comment: string): LineShell | undefined {
@@ -133,7 +130,7 @@ function lineShell(comment: string): LineShell | undefined {
   const token = rows[0]?.token
   if (!token || rows.some(item => item.token !== token))
     return undefined
-  return { token, spaced: rows.some(item => item.spaced), prose: rows.map(item => item.text).join('\n') }
+  return { token, spaced: rows.some(item => item.spaced) }
 }
 
 function refillLine(comment: string, body: string): string | undefined {
@@ -214,14 +211,6 @@ function refillBlock(comment: string, body: string): string | undefined {
   return `${open}\n${rendered.join('\n')}\n${closeIndent}*/`
 }
 
-/** 去掉定界符之后的正文。认不出这种注释就是 undefined。 */
-export function commentProse(comment: string): string | undefined {
-  const doc = docShell(comment)
-  if (doc)
-    return docProse(doc)
-  return lineShell(comment)?.prose ?? blockProse(comment)
-}
-
 /**
  * 把新正文套回这段注释原来的壳。comment 是去掉共同缩进的原文。
  * 认不出定界符，或新正文是空的，就返回 undefined，调用方不写文件。
@@ -233,92 +222,204 @@ export function refillComment(comment: string, body: string): string | undefined
   return refillDoc(comment, text) ?? refillLine(comment, text) ?? refillBlock(comment, text)
 }
 
+/** 发给模型的整句话：技能命令后面跟代码块在哪，`路径:起-止`（路径相对 claude 的工作目录，行号 1 起，连同讲它的注释），别的不说。startLine、endLine 0 起。 */
+export function commentRewritePrompt(path: string, startLine: number, endLine: number): string {
+  return `${COMMENT_SKILL} ${path}:${startLine + 1}-${endLine + 1}`
+}
+
 /**
- * 文件顶上的模块说明：前面没有别的代码（可以有别的注释），而且是三引号，或没挂到声明上的 `/**`。
- * `#`、`//`、普通块注释不算，它们讲的是后面那一块。
+ * 从 claude 的 stream-json 输出里读出来的：text 是注释正文到现在为止写出来的（结构化结果逐字长出来），activity 是正在做的事（「读取 routes.py」），
+ * result 是答完了（body 是结构化结果里的正文，没按 COMMENT_SCHEMA 交回、正文是空的时没有），error 是 Claude Code 自己报的失败。
  */
-export function isModuleComment(comment: string, earlierKinds: readonly string[]): boolean {
-  if (earlierKinds.some(kind => kind !== 'comment'))
-    return false
-  if (comment.trimStart().startsWith('/**'))
-    return true
-  return docShell(comment) !== undefined
+export type CommentEvent
+  = | { kind: 'text', text: string }
+    | { kind: 'activity', label: string }
+    | { kind: 'result', body?: string }
+    | { kind: 'error', message: string }
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
 
-export interface CommentPlace<T extends { anchor: string, children: readonly T[] }> {
-  block: T
-  siblings: readonly T[]
-  index: number
+function str(value: unknown): string {
+  return typeof value === 'string' ? value : ''
 }
 
-/** 按记号在块树里找到这块，以及它和哪些块排在同一层。 */
-export function findPlaced<T extends { anchor: string, children: readonly T[] }>(blocks: readonly T[], anchor: string): CommentPlace<T> | undefined {
-  const index = blocks.findIndex(block => block.anchor === anchor)
-  const found = index >= 0 ? blocks[index] : undefined
-  if (found)
-    return { block: found, siblings: blocks, index }
+/** 写到一半的结构化结果（`{"body": "…`）里已经写出来的正文；还没写到正文、转义写到一半解不开时没有。 */
+const PARTIAL_BODY = /^\s*\{\s*"body"\s*:\s*"((?:[^"\\]|\\.)*)/
+
+function partialBody(json: string): string | undefined {
+  const match = PARTIAL_BODY.exec(json)
+  if (!match)
+    return undefined
+  try {
+    return JSON.parse(`"${match[1].replace(/\\u[0-9a-f]{0,3}$/i, '')}"`) as string
+  }
+  catch {
+    return undefined
+  }
+}
+
+/** 正文：结构化结果里的 body，去掉首尾空白是空的不算。 */
+function bodyOf(output: unknown): string | undefined {
+  return isRecord(output) && typeof output.body === 'string' && output.body.trim() !== '' ? output.body : undefined
+}
+
+/**
+ * 一次重写一个解析器（它记着结构化结果写到哪了）：`claude -p --output-format stream-json --verbose --include-partial-messages --json-schema`
+ * 的每行 → CommentEvent。结构化结果是模型调 StructuredOutput 工具交的，它的输入逐段（input_json_delta）来，读出正文给进度；
+ * 读文件、搜索这些工具调用是 activity；结果以 result 行的 structured_output 为准，模型只回了一段话（没调这个工具）就没有正文。
+ */
+export function createCommentParser(): (line: string) => CommentEvent[] {
+  /** 正在写的结构化结果（工具输入的 JSON 原文）；不在写时没有 */
+  let json: string | undefined
+  let text = ''
+  const grow = (body: string | undefined): CommentEvent[] => {
+    if (body === undefined || body === text)
+      return []
+    text = body
+    return [{ kind: 'text', text }]
+  }
+  const streamEvent = (event: Record<string, unknown>): CommentEvent[] => {
+    if (event.type === 'content_block_start' && isRecord(event.content_block)) {
+      json = event.content_block.type === 'tool_use' && event.content_block.name === STRUCTURED_TOOL ? '' : undefined
+      return []
+    }
+    if (event.type === 'content_block_delta' && json !== undefined && isRecord(event.delta) && event.delta.type === 'input_json_delta') {
+      json += str(event.delta.partial_json)
+      return grow(partialBody(json))
+    }
+    if (event.type === 'content_block_stop')
+      json = undefined
+    return []
+  }
+  const assistant = (content: unknown[]): CommentEvent[] => content.flatMap((block): CommentEvent[] => {
+    if (!isRecord(block) || block.type !== 'tool_use' || typeof block.name !== 'string')
+      return []
+    const input = isRecord(block.input) ? block.input : {}
+    return block.name === STRUCTURED_TOOL ? grow(bodyOf(input)) : [{ kind: 'activity', label: describeToolUse(block.name, input) }]
+  })
+  return (raw) => {
+    let line: unknown
+    try {
+      line = JSON.parse(raw)
+    }
+    catch {
+      return []
+    }
+    // 子代理的消息（parent_tool_use_id 不空）不是这次的结果
+    if (!isRecord(line) || (line.parent_tool_use_id !== undefined && line.parent_tool_use_id !== null))
+      return []
+    if (line.type === 'stream_event')
+      return isRecord(line.event) ? streamEvent(line.event) : []
+    if (line.type === 'assistant')
+      return isRecord(line.message) && Array.isArray(line.message.content) ? assistant(line.message.content) : []
+    if (line.type !== 'result')
+      return []
+    if (line.is_error === true) {
+      const errors = Array.isArray(line.errors) ? line.errors.filter(item => typeof item === 'string').join('；') : ''
+      return [{ kind: 'error', message: str(line.result).trim() || errors || str(line.subtype) || '没说原因' }]
+    }
+    const body = bodyOf(line.structured_output)
+    return [{ kind: 'result', ...(body !== undefined && { body }) }]
+  }
+}
+
+/**
+ * 要改文件的哪儿（行号 0 起）：replace 换掉 startLine..endLine 这几行，text 去掉了共同缩进（写回时每行补回第一行的缩进，同块编辑）；
+ * insert 在 line 这一行上面插进几行，text 已经带着缩进、不带结尾的换行。
+ */
+export type CommentEdit
+  = | { kind: 'replace', startLine: number, endLine: number, text: string }
+    | { kind: 'insert', line: number, text: string }
+
+/**
+ * 新正文落到文件里的样子：换掉原来那段注释时套回它的定界符（几段注释中间隔着空行时照第一段的写法写成一段）；
+ * 块还没有注释时用语言的行注释记号新写一段，缩进同块的第一行。认不出定界符、没有行注释记号、正文是空的时没有。
+ */
+export function commentEdit(target: CommentTarget, lineAt: (line: number) => string, body: string, lineComment: string | undefined): CommentEdit | undefined {
+  if (target.kind === 'replace') {
+    const comment = commentSource(Array.from({ length: target.endLine - target.startLine + 1 }, (_, i) => lineAt(target.startLine + i)))
+    const text = refillComment(comment, body) ?? refillComment(comment.split(/\n[ \t]*\n/)[0], body)
+    return text === undefined ? undefined : { kind: 'replace', startLine: target.startLine, endLine: target.endLine, text }
+  }
+  if (!lineComment)
+    return undefined
+  const indent = /^[ \t]*/.exec(lineAt(target.line))?.[0] ?? ''
+  const text = refillComment(`${lineComment} _`, body)
+  return text === undefined ? undefined : { kind: 'insert', line: target.line, text: text.split('\n').map(line => indent + line).join('\n') }
+}
+
+/** 写回文件的结果：written 写进去了，unchanged 和文件里一样不用写，missing 行号已经不在，rejected 编辑器没接受。 */
+export type WriteResult = 'written' | 'unchanged' | 'missing' | 'rejected'
+
+/** 一次重写的结果：done 已经写进文件，failed 没写并带给人看的原因，stopped 是被叫停、没写。 */
+export type RewriteOutcome
+  = | { status: 'done' }
+    | { status: 'stopped' }
+    | { status: 'failed', error: string }
+
+/** 给哪块代码重写注释：「重写注释」写到哪，块的起止行（0 起，连同讲它的注释），文件相对 claude 工作目录的路径（`/` 分隔），语言的行注释记号。 */
+export interface CommentRewriteJob {
+  target: CommentTarget
+  startLine: number
+  endLine: number
+  path: string
+  lineComment?: string
+}
+
+/** 重写时要用的：读文件现在的行，问模型（拿到结构化结果里的正文，没有正文时 undefined；失败时抛错），出错时给人看的话，写回文件。 */
+export interface CommentRewriteDeps {
+  lineAt: (line: number) => string
+  lineCount: () => number
+  ask: (prompt: string) => Promise<string | undefined>
+  failure: (err: unknown) => string
+  write: (edit: CommentEdit) => Promise<WriteResult>
+  signal: AbortSignal
+}
+
+/**
+ * 重写一块代码的注释：问模型（提示只有技能命令和代码块在哪，见 commentRewritePrompt），拿结构化结果里的正文套回去写进文件。
+ * 没交回结构化的正文、这块代码在重写期间变了、写不回去都算失败，文件不动。
+ */
+export async function rewriteBlockComment(job: CommentRewriteJob, deps: CommentRewriteDeps): Promise<RewriteOutcome> {
+  const failed = (error: string): RewriteOutcome => ({ status: 'failed', error })
+  const rangeText = (): string | undefined => job.endLine < deps.lineCount()
+    ? Array.from({ length: job.endLine - job.startLine + 1 }, (_, i) => deps.lineAt(job.startLine + i)).join('\n')
+    : undefined
+  const snapshot = job.startLine >= 0 && job.endLine >= job.startLine ? rangeText() : undefined
+  if (snapshot === undefined)
+    return failed('这块代码的位置已经变了，没有写回。')
+  let body: string | undefined
+  try {
+    body = await deps.ask(commentRewritePrompt(job.path, job.startLine, job.endLine))
+  }
+  catch (err) {
+    return deps.signal.aborted ? { status: 'stopped' } : failed(deps.failure(err))
+  }
+  if (deps.signal.aborted)
+    return { status: 'stopped' }
+  if (body === undefined)
+    return failed('模型没有按要求交回注释正文，没有改文件。')
+  if (rangeText() !== snapshot)
+    return failed('这块代码在重写期间变了，没有写回。')
+  const edit = commentEdit(job.target, deps.lineAt, body, job.lineComment)
+  if (!edit)
+    return failed('这段注释的定界符认不出来，没有改文件。')
+  const wrote = await deps.write(edit)
+  if (wrote === 'written' || wrote === 'unchanged')
+    return { status: 'done' }
+  return failed(wrote === 'rejected' ? '编辑器没接受这次修改，没有写回。' : '这块代码在重写期间变了，没有写回。')
+}
+
+/** 按记号在块树里找到这块。 */
+export function findBlock<T extends { anchor: string, children: readonly T[] }>(blocks: readonly T[], anchor: string): T | undefined {
   for (const block of blocks) {
-    const inner = findPlaced(block.children, anchor)
+    if (block.anchor === anchor)
+      return block
+    const inner = findBlock(block.children, anchor)
     if (inner)
       return inner
   }
   return undefined
 }
-
-function clip(text: string, what: string): { text: string, note: string } {
-  const lines = splitLines(text)
-  if (lines.length <= COMMENT_CONTEXT_LINES)
-    return { text, note: '' }
-  return {
-    text: lines.slice(0, COMMENT_CONTEXT_LINES).join('\n'),
-    note: `\n（${what}一共 ${lines.length} 行，这里只贴了前 ${COMMENT_CONTEXT_LINES} 行，后面截断了）`,
-  }
-}
-
-export interface CommentRewriteInput {
-  /** 去掉共同缩进的注释原文 */
-  comment: string
-  /** 整份文件，用来在是模块说明时拿掉这段注释 */
-  source: string
-  startLine: number
-  endLine: number
-  earlierKinds: readonly string[]
-  /** 普通注释后面紧挨着的那一块的原文；没有就不填 */
-  following?: string
-  /** 说明挂在这块代码上（函数、类的 docstring）。有它就不当成文件顶上的说明，上下文用这块。 */
-  attached?: string
-}
-
-/** 发给模型的整段话。开头是技能命令，Claude Code 自己加载技能。注释认不出就不组。 */
-export function commentRewritePrompt(input: CommentRewriteInput): string | undefined {
-  const body = commentProse(input.comment)
-  if (body === undefined)
-    return undefined
-  const fileComment = input.attached === undefined && isModuleComment(input.comment, input.earlierKinds)
-  const context = input.attached !== undefined
-    ? clip(input.attached, '这块代码')
-    : fileComment
-      ? clip(splitLines(input.source).filter((_, index) => index < input.startLine || index > input.endLine).join('\n').trim(), '文件其余部分')
-      : input.following
-        ? clip(input.following, '这块代码')
-        : { text: '（后面没有紧挨着的代码）', note: '' }
-  return [
-    COMMENT_SKILL,
-    '只按这个技能重写这一段注释。用中文。不要改代码，不要加技能没要求的中文名记号。只输出新注释的正文，不要定界符，不要解释。',
-    `这段注释现在的正文：\n${body}`,
-    `它说明的代码：\n${context.text}${context.note}`,
-  ].join('\n\n')
-}
-
-/** 模型偶尔会套一层代码围栏。剥掉；剥完是空的就当没给。 */
-export function modelCommentBody(text: string): string | undefined {
-  let body = text.trim()
-  if (body.startsWith('```') && body.endsWith('```')) {
-    const nl = body.indexOf('\n')
-    if (nl >= 0)
-      body = body.slice(nl + 1, -3).trim()
-  }
-  if (!body)
-    return undefined
-  return body
-}
diff --git a/vscode/src/codeReader/contract.ts b/vscode/src/codeReader/contract.ts
index 86bdc7c..adeecfc 100644
--- a/vscode/src/codeReader/contract.ts
+++ b/vscode/src/codeReader/contract.ts
@@ -9,6 +9,7 @@ export type { Node }
  * directive 往后给构建文件（Dockerfile）：directive 文件开头给构建工具看的解析指令（`# syntax=…`），stage 一个构建阶段（FROM 和它后面的指令），
  * run 构建时执行的命令，copy 往镜像里复制文件，setting 一条设置（工作目录、运行身份、端口……），label 镜像的标签，
  * health 健康检查，start 容器启动时执行的命令。
+ * comment 是讲整个文件的注释（文件开头的说明）；别的注释不单独成块，挂在它讲的块上（见 BlockShape.comments）。
  */
 export type BlockKind
   = | 'import' | 'function' | 'class' | 'enum' | 'exception' | 'type' | 'field' | 'const' | 'variable'
@@ -489,11 +490,17 @@ export interface BlockShape {
   /** 这一块对应的语法树节点（整条语句）。 */
   node: Node
   /**
-   * 块自己那一段（预览讲的就是它）：复合语句只到主体开始之前，其余是整条语句。编辑时宿主给的是整块：头部连同各子块、结尾。
+   * 块自己那一段（预览讲的就是它）：复合语句只到主体开始之前，其余是整条语句。编辑时宿主给的是整块：头部连同各子块、讲它的注释、结尾。
    * 块自己的说明（facts.doc、TextBlock.doc）也算在里面：JSDoc 往上延到注释开头，docstring、属性 docstring 往下延到字符串结尾。
    */
   header: SourceSpan
   children: CodeBlock[]
+  /**
+   * 讲这块的普通注释（不是说明），照源码顺序：同一层里它前面的注释（中间隔空行也算），这一层最后一块代码后面的注释，
+   * 子块一块代码都没有时子块里的注释。由 attachComments（languages/shared.ts）挂上；预览排成卡片上的「注释」一行，
+   * 块的编辑范围连同这几段注释。只有文件开头的说明单独成块（kind 'comment'）。
+   */
+  comments?: CommentBlock[]
   /**
    * 语言自己报的筛选属性，和宿主推出的通用属性（见 COMMON_ATTRIBUTES）合在一起：通用词表以外的属性（Rust 的 unsafe: 'true'），
    * 或 facts 表达不了的通用属性值（Kotlin 的 access: 'internal'，盖过从 facts 推出的）。kind 总是块的种类，这里填了不算。
@@ -562,6 +569,12 @@ export interface TextBlock extends BlockShape {
 
 export type CodeBlock = TextBlock | FactBlock
 
+/**
+ * 一段注释：相邻行同一写法的行注释合成的一段（node 是第一条，头部盖住全部），一条块注释，或 Python 当注释用的字符串。
+ * 文件开头的说明是单独的一块；别的挂在它讲的块上（BlockShape.comments）。
+ */
+export interface CommentBlock extends TextBlock { kind: 'comment' }
+
 /** 着色用的词性，源码着色和译文着色共用。 */
 export type TokenRole
   = | 'keyword' // 流程关键字：import from export if else for return try catch await …
@@ -707,6 +720,8 @@ export interface LanguageAdapter {
   toBlocks: (root: Node, source: string, languageId: string) => CodeBlock[]
   /** 给语法树叶子节点定词性：源码着色用它，译文里照抄的词也按它着色、按它认出能查定义的名字。 */
   tokenRole: (leaf: Node) => TokenRole
+  /** 行注释的记号（`#`、`//`）：「重写注释」给还没有注释的块新写一段时用它；不填就不能新写。 */
+  lineComment?: string
   /** node 是写在表达式里的遍历（推导式、生成器表达式）时给出它的结构，别的节点没有；没有这种写法的语言不填。 */
   iteration?: (node: Node) => IterationFacts | undefined
   /** node 是一次调用（含新建对象）时给出它的结构，别的节点没有；没给的语言不展开调用，照常一行译文。 */
@@ -792,7 +807,10 @@ export interface Translator {
   languageIds: string[]
   /** 译文用的语言（BCP 47 的语言部分，例如 'zh'）：库规则按它挑自己的词表。 */
   displayLanguage: string
-  /** 只翻 header 那一段；注释块给去掉注释符号的 Markdown 原文，跨几行写的调用连着摊开实参的表。 */
+  /**
+   * 只翻 header 那一段；注释块（文件开头的说明、挂在块上的注释 BlockShape.comments）给去掉注释符号的 Markdown 原文，
+   * 跨几行写的调用连着摊开实参的表。
+   */
   translate: (block: TextBlock, document: SourceDocument) => TextTranslation
   /** 函数、类、枚举、导入、常量、变量块 → 属性表。 */
   describe: (block: FactBlock, document: SourceDocument) => PropertyRow[]
@@ -929,12 +947,15 @@ export interface KindBadge { label: string, color: ThemeColor, icon: KindIconNam
 export type RuleBlock = RuleCard | RuleFacts | RuleOmit
 
 /**
- * 这块讲在了别的卡片里，不再单独成块：React 文件开头的 "use client" 讲成了组件卡片上的「客户端组件」标签，
- * 组件上面的 JSDoc 讲成了卡片的「说明」。预览不画它；它不能有子块（有子块时宿主当规则没认）。
+ * 这块讲在了别的卡片里，不再单独成块：React 文件开头的 "use client" 讲成了组件卡片上的「客户端组件」标签。
+ * 预览不画它；它不能有子块，也不能挂着注释（BlockShape.comments，注释没地方放），有时宿主当规则没认。
  */
 export interface RuleOmit { omit: true }
 
-/** 规则自己的卡片：一张属性表。种类（badge）决定筛选和边框色；卡片左边的图标是语言的概念再加这个种类、以及 concepts。用词归规则。 */
+/**
+ * 规则自己的卡片：一张属性表。种类（badge）决定筛选和边框色；卡片左边的图标是语言的概念再加这个种类、以及 concepts。用词归规则。
+ * 原块的「注释」一行（BlockShape.comments）由宿主插进 rows，规则不用管。
+ */
 export interface RuleCard {
   /** 种类 id，写成「规则 id.名字」（sqlalchemy.table）：筛选的 kind 属性值就是它，筛选记住的也是它，要稳定。 */
   kind: string
@@ -954,8 +975,8 @@ export interface RuleCard {
    */
   attributes?: BlockAttributes
   /**
-   * 并进这一块的子块（原块 children 里的对象本身）：不再单独成块，内容由 rows 讲。
-   * 没并进来的子块（方法、别的成员、规则不讲的注释）不管写在哪，都照源码顺序照常是这一块的子块，也照常交给各规则看。
+   * 并进这一块的子块（原块 children 里的对象本身）：不再单独成块，内容由 rows 讲（讲子块的注释在子块的 comments 里，跟着并进来）。
+   * 没并进来的子块（方法、别的成员）不管写在哪，都照源码顺序照常是这一块的子块，也照常交给各规则看。
    * 这一块的编辑范围同别的块，是原块整条语句（类就是整个类），盖住留下的子块：它编辑时预览不画这些子块，同一行不会同时在两处能改。
    */
   absorbs: CodeBlock[]
diff --git a/vscode/src/codeReader/diff/blockDiff.test.ts b/vscode/src/codeReader/diff/blockDiff.test.ts
index b3a2396..9d99ebd 100644
--- a/vscode/src/codeReader/diff/blockDiff.test.ts
+++ b/vscode/src/codeReader/diff/blockDiff.test.ts
@@ -232,3 +232,17 @@ describe('diffBlockTrees', () => {
     expect(diff.removed[0].after).toBeUndefined()
   })
 })
+
+describe('改了挂在块上的注释', () => {
+  it('改的是讲这块的注释：这块算修改、自己改了，「注释」一行逐词标；一行译文的卡片标在它下面那几行（rows）上', async () => {
+    const before = await python('import os\n\n# 讲 load\ndef load(path):\n    # 先检查\n    return path\n')
+    const after = await python('import os\n\n# 讲 load，改过\ndef load(path):\n    # 先检查一下\n    return path\n')
+    const diff = diffBlockTrees(before, after)
+    const [, load] = after.blocks
+    const [returned] = load.children
+    expect(diff.stats).toEqual({ add: 0, mod: 1, del: 0 })
+    expect(diff.blocks[load.anchor]).toMatchObject({ change: 'mod', own: true, marks: { rows: { changed: { 1: { value: { markdown: expect.any(Array) } } } } } })
+    expect(diff.blocks[returned.anchor]).toMatchObject({ change: 'mod', own: true, marks: { rows: { changed: { 0: { value: { markdown: expect.any(Array) } } } } } })
+    expect(diff.blocks[returned.anchor].marks).not.toHaveProperty('translation')
+  })
+})
diff --git a/vscode/src/codeReader/diff/viewDiff.ts b/vscode/src/codeReader/diff/viewDiff.ts
index b75bec9..8a1d5e8 100644
--- a/vscode/src/codeReader/diff/viewDiff.ts
+++ b/vscode/src/codeReader/diff/viewDiff.ts
@@ -54,7 +54,7 @@ export interface RowDiff {
   items?: ItemsDiff
 }
 
-/** 一块自己的内容（不算子块）改了哪些：属性表逐行，一行译文逐截，摊开实参的表逐行，说明逐词。 */
+/** 一块自己的内容（不算子块）改了哪些：属性表（一行译文的卡片是下面那几行 rows，「注释」一行）逐行，一行译文逐截，摊开实参的表逐行，说明逐词。 */
 export interface BlockMarks {
   rows?: RowsDiff
   translation?: TextDiff
@@ -114,6 +114,7 @@ export function removedView(view: BlockView): BlockView {
     translation: textWithoutSource(view.translation),
     ...(view.table && { table: tableWithoutSource(view.table) }),
     ...(view.doc && { doc: view.doc }),
+    ...(view.rows && { rows: view.rows.map(rowWithoutSource) }),
   }
 }
 
@@ -315,6 +316,7 @@ export function blockMarks(before: BlockView, after: BlockView): BlockMarks | un
   const translation = textDiff(before.translation, after.translation)
   const table = itemsDiff(before.table?.items, after.table?.items)
   const doc = textDiff(before.doc ?? { markdown: '' }, after.doc ?? { markdown: '' })
-  const marks: BlockMarks = { ...(translation && { translation }), ...(table && { table }), ...(doc && { doc }) }
+  const rows = rowsDiff(before.rows ?? [], after.rows ?? [])
+  const marks: BlockMarks = { ...(translation && { translation }), ...(table && { table }), ...(doc && { doc }), ...(rows && { rows }) }
   return Object.keys(marks).length > 0 ? marks : undefined
 }
diff --git a/vscode/src/codeReader/editor/messages.ts b/vscode/src/codeReader/editor/messages.ts
index 704f7c5..9816cbf 100644
--- a/vscode/src/codeReader/editor/messages.ts
+++ b/vscode/src/codeReader/editor/messages.ts
@@ -119,7 +119,7 @@ export interface StickyScrollSettings {
  * askProfiles：「问 AI」输入框旁边的 profile 下拉：选项和选中的那项；ready 后发一次，任何一个预览改了都发给所有预览
  * answer：askId 那个问题的回答长了（text 是到现在为止的全文）、或换了在做的事
  * answerEnd：askId 那个问题答完了：done 带最终的回答和存下的那条的 id，failed 带给人看的原因，stopped 是被叫停
- * rewriteProgress：anchor 这段注释正在按规范重写。question 是发给模型的要求，text 是到现在为止的全文，activity 是正在读什么
+ * rewriteProgress：anchor 那块的注释正在按规范重写。question 是发给模型的那一句（技能命令和块在哪），text 是注释正文到现在为止写出来的，activity 是正在读什么
  * rewriteEnd：这段重写结束了。done 是正文已经写进文件；failed 带给人看的原因，文件没改；stopped 是被叫停，文件没改
  * moveOccurrence：跳到高亮着的名字的下一处（step 1）/ 上一处（step -1）出现，由这两条命令发给活动的预览
  * displayNames：version 这份文档里显示成中文名的名字，查到一步发一步（先本文件定义的，再别的文件定义的）；不是页面上这个版本的不理
@@ -167,7 +167,7 @@ export type ExtensionToWebview
  * setOnlyChanges：打开 / 关掉「只看改动」，扩展端记下后发 filter 给所有预览
  * ask：问 anchor 那块代码；askId 由 webview 起，回答的消息带回去；扩展端接着这块最近一次问答的会话问，用眼下选的 profile；
  *   images 是贴进输入框的图片（没贴是空的），随问题发给 Claude Code，答成了跟这条一起存
- * rewriteComment：按注释规范重写 anchor 这段注释。过程用 rewriteProgress / rewriteEnd 发回页面，不写入问答
+ * rewriteComment：按注释规范重写 anchor 那块的注释（还没有就新写一段）。过程用 rewriteProgress / rewriteEnd 发回页面，不写入问答
  * stopRewrite：叫停 anchor 这段正在进行的重写，不写文件
  * stopAsk：叫停 askId 那个问题，这次不存
  * deleteQa：删掉 anchor 那块下面的一次问答（已经理解了）
diff --git a/vscode/src/codeReader/editor/previewEditor.ts b/vscode/src/codeReader/editor/previewEditor.ts
index ff47db6..9cc848f 100644
--- a/vscode/src/codeReader/editor/previewEditor.ts
+++ b/vscode/src/codeReader/editor/previewEditor.ts
@@ -1,5 +1,6 @@
 import type { CustomTextEditorProvider, Disposable, DocumentSymbol, Event, TextDocument, TextDocumentShowOptions, WebviewPanel } from 'vscode'
 import type { ClaudeImage } from '../../cc/spawnClaude'
+import type { CommentEdit, RewriteOutcome, WriteResult } from '../commentRewrite'
 import type { BlockKind, LocalSymbol, RuleLocation, RuleReference, SourceRange, WorkspaceIndex } from '../contract'
 import type { DiffBase } from '../diff/diffBase'
 import type { OldDocument, SentDocument } from '../diff/previewDiff'
@@ -16,18 +17,18 @@ import type { FoundLocation } from './definitions'
 import type { DefinitionPeek, ExtensionToWebview, Occurrence, Reveal, WebviewToExtension } from './messages'
 import type { TargetSpot } from './openTarget'
 import { realpath } from 'node:fs/promises'
-import { dirname } from 'node:path'
-import { commands, Range, Uri, window, workspace, WorkspaceEdit } from 'vscode'
+import { dirname, relative, sep } from 'node:path'
+import { commands, EndOfLine, Position, Range, Uri, window, workspace, WorkspaceEdit } from 'vscode'
 import { logger } from '../../logging/logger'
 import { webviewHtml, webviewUiRoot } from '../../webview/html'
 import { DocumentCallees } from '../calleeKinds'
-import { commentRewritePrompt, commentSource, findPlaced, modelCommentBody, refillComment } from '../commentRewrite'
+import { findBlock, rewriteBlockComment } from '../commentRewrite'
 import { PreviewDiff } from '../diff/previewDiff'
 import { blockReplacement } from '../editText'
 import { locate } from '../folderStore'
 import { definitionFor, symbolAt, symbolOccurrences } from '../localSymbols'
 import { DocumentNames, resolveNames } from '../nameResolution'
-import { askClaude, askFailure } from '../qa/claudeAsk'
+import { askCommentBody, askFailure } from '../qa/claudeAsk'
 import { PATH_ASK_ANCHOR } from '../qa/pathQa'
 import { askPrompt, followUpPrompt } from '../qa/prompt'
 import { DocumentLookups } from '../ruleLookups'
@@ -164,12 +165,6 @@ export class PreviewEditorProvider implements CustomTextEditorProvider {
   }
 }
 
-/** 一段注释重写的结果：`done` 已经写进文件，`failed` 没写并带给人看的原因，`stopped` 是被叫停、没写。 */
-type RewriteOutcome
-  = | { status: 'done' }
-    | { status: 'stopped' }
-    | { status: 'failed', error: string }
-
 class Preview {
   /** webview 发过 ready 之后才发消息；标签页切走时页面被销毁，切回来重新加载、再发 ready，这期间也不发 */
   private ready = false
@@ -962,113 +957,83 @@ class Preview {
       this.failRewrite(message)
       return { status: 'failed', error: message }
     }
-    const found = this.sent && findPlaced(this.sent.blocks, anchor)
-    if (!found)
-      return failed('这块注释刚改过，找不到了。等预览刷新后再重写。')
-    const { block, siblings, index } = found
-    const startLine = block.commentStartLine
-    const endLine = block.commentEndLine
-    if (startLine === undefined || endLine === undefined)
-      return failed('这块没有能重写的注释。')
+    const block = this.sent && findBlock(this.sent.blocks, anchor)
+    if (!block)
+      return failed('这块代码刚改过，找不到了。等预览刷新后再重写。')
+    const target = block.commentTarget
+    if (!target)
+      return failed('这块不能写注释。')
     const { document } = this
-    if (startLine < 0 || endLine < startLine || endLine >= document.lineCount)
-      return failed('这块注释的位置已经变了，没有写回。')
-    const linesOf = (from: number, to: number): string => Array.from({ length: to - from + 1 }, (_, i) => document.lineAt(from + i).text).join('\n')
-    const raw = linesOf(startLine, endLine).split('\n')
-    const snapshot = raw.join('\n')
-    const comment = commentSource(raw)
-    const source = document.getText()
-    const attached = startLine !== block.startLine || endLine !== block.endLine
-      ? [
-          ...(startLine > block.startLine ? [linesOf(block.startLine, startLine - 1)] : []),
-          ...(endLine < block.endLine ? [linesOf(endLine + 1, block.endLine)] : []),
-        ].filter(part => part !== '').join('\n')
-      : undefined
-    const next = siblings[index + 1]
-    const following = attached === undefined && next && next.startLine >= 0 && next.endLine >= next.startLine && next.endLine < document.lineCount
-      ? linesOf(next.startLine, next.endLine)
-      : undefined
-    const prompt = commentRewritePrompt({
-      comment,
-      source,
-      startLine,
-      endLine,
-      earlierKinds: siblings.slice(0, index).map(item => item.kind),
-      ...(following !== undefined && { following }),
-      ...(attached !== undefined && attached !== '' && { attached }),
-    })
-    if (!prompt)
-      return failed('这段注释的定界符认不出来，没有改文件。')
+    if (document.isDirty)
+      return failed('文件还有没保存的修改，模型读的是磁盘上的文件：先保存再重写注释。')
     const at = locate(document.uri)
-    let text = ''
-    let activity: string | undefined
-    const publish = (): void => {
-      this.post({
-        type: 'rewriteProgress',
-        anchor,
-        question: prompt,
-        text,
-        ...(activity !== undefined && { activity }),
-      })
-    }
-    publish()
+    const cwd = at?.folder.uri.fsPath ?? dirname(document.uri.fsPath)
     const profile = await this.owner.qa.profiles.current()
     if (signal.aborted)
       return { status: 'stopped' }
-    let answerText: string
-    try {
-      const answer = await askClaude({
-        prompt,
-        images: [],
-        ...(profile && { profilePath: profile.path }),
-        cwd: at?.folder.uri.fsPath ?? dirname(document.uri.fsPath),
-        signal,
-        onEvent: (event) => {
-          if (event.kind === 'text') {
-            text = event.text
-            activity = undefined
-          }
-          else if (event.kind === 'activity') {
-            activity = event.label
-          }
-          else {
-            return
-          }
-          publish()
-        },
-      })
-      answerText = answer.text
+    let question = ''
+    let text = ''
+    let activity: string | undefined
+    const publish = (): void => {
+      this.post({ type: 'rewriteProgress', anchor, question, text, ...(activity !== undefined && { activity }) })
     }
-    catch (err) {
-      if (signal.aborted)
-        return { status: 'stopped' }
-      return failed(askFailure(err))
-    }
-    if (signal.aborted)
-      return { status: 'stopped' }
-    const body = modelCommentBody(answerText)
-    if (!body)
-      return failed('模型没有给出注释正文，没有改文件。')
-    if (endLine >= document.lineCount)
-      return failed('这段注释在重写期间变了，没有写回。')
-    const current = linesOf(startLine, endLine)
-    if (current !== snapshot)
-      return failed('这段注释在重写期间变了，没有写回。')
-    const filled = refillComment(comment, body)
-    if (!filled)
-      return failed('这段注释的定界符认不出来，没有改文件。')
-    if (signal.aborted)
-      return { status: 'stopped' }
-    const wrote = await this.applyEdit(startLine, endLine, filled)
-    if (wrote === 'written' || wrote === 'unchanged')
-      return { status: 'done' }
-    if (wrote === 'rejected')
-      return { status: 'failed', error: `没能把修改写回 ${workspace.asRelativePath(document.uri)}` }
-    return failed('这段注释在重写期间变了，没有写回。')
+    const outcome = await rewriteBlockComment({
+      target,
+      startLine: block.startLine,
+      endLine: block.endLine,
+      path: relative(cwd, document.uri.fsPath).split(sep).join('/'),
+      lineComment: this.registry.languageFor(this.languageId)?.lineComment,
+    }, {
+      lineAt: line => document.lineAt(line).text,
+      lineCount: () => document.lineCount,
+      ask: (prompt) => {
+        question = prompt
+        publish()
+        return askCommentBody({
+          prompt,
+          ...(profile && { profilePath: profile.path }),
+          cwd,
+          signal,
+          onEvent: (event) => {
+            if (event.kind === 'text') {
+              text = event.text
+              activity = undefined
+            }
+            else {
+              activity = event.label
+            }
+            publish()
+          },
+        })
+      },
+      failure: askFailure,
+      write: edit => this.applyCommentEdit(edit),
+      signal,
+    })
+    if (outcome.status === 'failed')
+      this.failRewrite(outcome.error)
+    return outcome
   }
 
-  /** 把这几行换成 [text]。`written` 写进去了，`unchanged` 跟文件里一样不用写，`missing` 行号已经不在，`rejected` 编辑器没接受。 */
-  private async applyEdit(startLine: number, endLine: number, text: string): Promise<'written' | 'unchanged' | 'missing' | 'rejected'> {
+  /** 写回重写好的注释：换掉原来那几行（同块编辑），或在块上面插进新写的几行。 */
+  private async applyCommentEdit(edit: CommentEdit): Promise<WriteResult> {
+    if (edit.kind === 'replace')
+      return this.applyEdit(edit.startLine, edit.endLine, edit.text)
+    const { document } = this
+    if (edit.line >= document.lineCount)
+      return 'missing'
+    const eol = document.eol === EndOfLine.CRLF ? '\r\n' : '\n'
+    const change = new WorkspaceEdit()
+    change.insert(document.uri, new Position(edit.line, 0), edit.text.split('\n').join(eol) + eol)
+    if (!await workspace.applyEdit(change)) {
+      void window.showErrorMessage(`代码阅读：没能把修改写回 ${workspace.asRelativePath(document.uri)}`)
+      return 'rejected'
+    }
+    return 'written'
+  }
+
+  /** 把这几行换成 [text]（见 WriteResult）。 */
+  private async applyEdit(startLine: number, endLine: number, text: string): Promise<WriteResult> {
     const { document } = this
     const replacement = blockReplacement(line => document.lineAt(line).text, document.lineCount, startLine, endLine, text)
     if (!replacement) {
diff --git a/vscode/src/codeReader/fixtures/acquisitionRepository.py b/vscode/src/codeReader/fixtures/acquisitionRepository.py
new file mode 100644
index 0000000..d0e0ba1
--- /dev/null
+++ b/vscode/src/codeReader/fixtures/acquisitionRepository.py
@@ -0,0 +1,139 @@
+from collections import Counter
+from collections.abc import Sequence
+from datetime import date, datetime
+
+from sqlalchemy import exists, func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from luffy_agent.acquisition.models import AcquisitionChannel
+from luffy_agent.core.filter.repository import FilterableRepository
+from luffy_agent.core.time import to_shanghai_date
+from luffy_agent.referral.models import ReferralRelation
+
+# luffy_agent.user.models.User 在各方法体内按需局部导入 (非模块顶层):
+# user 包 __init__ 会级联加载到 acquisition.service, 而 acquisition 是整个
+# 应用最早被 import 的域之一 (见 api_routers.py 的 include 顺序), 顶层导入
+# 会与该级联互相等待, 构成循环导入。
+
+
+class AcquisitionChannelRepository(
+    FilterableRepository[AcquisitionChannel, dict[str, object], dict[str, object], int]
+):
+    def __init__(self) -> None:
+        super().__init__(AcquisitionChannel)
+        self._filter_config = {"field_mapping": {}, "search_fields": ["code", "name"]}
+
+    async def get_by_code(
+        self, db: AsyncSession, *, code: str
+    ) -> AcquisitionChannel | None:
+        result = await db.execute(
+            select(AcquisitionChannel).where(AcquisitionChannel.code == code)
+        )
+        return result.scalar_one_or_none()
+
+    async def get_required_system(
+        self, db: AsyncSession, *, code: str
+    ) -> AcquisitionChannel:
+        channel = await self.get_by_code(db, code=code)
+        if channel is None or not channel.is_system:
+            raise RuntimeError(f"system acquisition channel missing: {code}")
+        return channel
+
+    async def list_all(self, db: AsyncSession) -> Sequence[AcquisitionChannel]:
+        """全量渠道列表, 按 id 升序, 无 limit。
+
+        渠道基数小 (系统内置 + 管理员自建), 不做分页; 不可复用
+        ``list_filtered`` 的默认 ``limit=100``, 否则超过 100 个渠道时
+        管理后台列表与来源分析 report 会被静默截断。
+        """
+        result = await db.execute(
+            select(AcquisitionChannel).order_by(AcquisitionChannel.id.asc())
+        )
+        return result.scalars().all()
+
+    async def count_users_by_channel(
+        self, db: AsyncSession, *, start_at: datetime, end_at: datetime
+    ) -> list[tuple[AcquisitionChannel, int]]:
+        """窗口内 (半开区间) 各渠道用户数, 仅含窗口内有用户的渠道。"""
+        from luffy_agent.user.models import User
+        from luffy_agent.user.repositories import customer_user_predicate
+
+        stmt = (
+            select(AcquisitionChannel, func.count(User.id))
+            .join(User, User.acquisition_channel_id == AcquisitionChannel.id)
+            .where(
+                User.created_at >= start_at,
+                User.created_at < end_at,
+                customer_user_predicate(),
+            )
+            .group_by(AcquisitionChannel.id)
+        )
+        result = await db.execute(stmt)
+        return [(channel, count) for channel, count in result.all()]
+
+    async def count_daily_by_channel(
+        self, db: AsyncSession, *, start_at: datetime, end_at: datetime
+    ) -> list[tuple[int, date, int]]:
+        """窗口内各渠道逐日 (沪时区自然日) 用户数。"""
+        from luffy_agent.user.models import User
+        from luffy_agent.user.repositories import customer_user_predicate
+
+        stmt = select(User.acquisition_channel_id, User.created_at).where(
+            User.created_at >= start_at,
+            User.created_at < end_at,
+            customer_user_predicate(),
+        )
+        result = await db.execute(stmt)
+        counter: Counter[tuple[int, date]] = Counter(
+            (channel_id, to_shanghai_date(created_at))
+            for channel_id, created_at in result.all()
+        )
+        return [
+            (channel_id, day, count) for (channel_id, day), count in counter.items()
+        ]
+
+    async def count_referred_users(
+        self, db: AsyncSession, *, start_at: datetime, end_at: datetime
+    ) -> int:
+        """窗口内曾被邀请过的用户数 (不看邀请关系 status/expire_time)。"""
+        from luffy_agent.user.models import User
+        from luffy_agent.user.repositories import customer_user_predicate
+
+        stmt = select(func.count(User.id)).where(
+            User.created_at >= start_at,
+            User.created_at < end_at,
+            customer_user_predicate(),
+            exists(
+                select(ReferralRelation.id).where(
+                    ReferralRelation.invitee_user_id == User.id
+                )
+            ),
+        )
+        result = await db.execute(stmt)
+        return result.scalar_one()
+
+    async def count_referred_daily(
+        self, db: AsyncSession, *, start_at: datetime, end_at: datetime
+    ) -> list[tuple[date, int]]:
+        """窗口内被邀请用户逐日 (沪时区自然日) 数量。"""
+        from luffy_agent.user.models import User
+        from luffy_agent.user.repositories import customer_user_predicate
+
+        stmt = select(User.created_at).where(
+            User.created_at >= start_at,
+            User.created_at < end_at,
+            customer_user_predicate(),
+            exists(
+                select(ReferralRelation.id).where(
+                    ReferralRelation.invitee_user_id == User.id
+                )
+            ),
+        )
+        result = await db.execute(stmt)
+        counter = Counter(
+            to_shanghai_date(created_at) for (created_at,) in result.all()
+        )
+        return list(counter.items())
+
+
+acquisition_channel_repository = AcquisitionChannelRepository()
diff --git a/vscode/src/codeReader/languages/bash.test.ts b/vscode/src/codeReader/languages/bash.test.ts
index 9a3935b..65a6d93 100644
--- a/vscode/src/codeReader/languages/bash.test.ts
+++ b/vscode/src/codeReader/languages/bash.test.ts
@@ -17,8 +17,7 @@ function facts(source: string): Promise<Record<number, unknown>> {
 /** luffy 桌面端 fetch-runtime.sh 的代码块树（同原型 SHELL_BLOCKS，原型略去的 95-100、116-121 行也在）。 */
 const FETCH_TREE: Outline[] = [
   { at: 1, kind: 'interpreter' },
-  { at: [2, 13], kind: 'comment' },
-  { at: 14, kind: 'options' },
+  { at: 14, kind: 'options', notes: [[2, 13]] },
   { at: 16, kind: 'variable' },
   { at: 17, kind: 'variable' },
   { at: 18, kind: 'variable' },
@@ -41,35 +40,28 @@ const FETCH_TREE: Outline[] = [
   { at: 66, kind: 'command' },
   { at: 67, kind: 'command' },
   { at: [68, 71], kind: 'case' },
-  { at: 72, kind: 'comment' },
-  { at: 73, kind: 'command' },
-  { at: [75, 77], kind: 'comment' },
-  { at: 78, kind: 'case', kids: [
-    { at: 79, kind: 'case', kids: [{ at: 80, kind: 'variable' }, { at: [81, 82], kind: 'command' }, { at: 83, kind: 'comment' }, { at: 84, kind: 'command' }] },
-    { at: 86, kind: 'case', kids: [{ at: [87, 88], kind: 'comment' }, { at: 89, kind: 'variable' }, { at: 90, kind: 'command' }, { at: 91, kind: 'command' }] },
+  { at: 73, kind: 'command', notes: [72] },
+  { at: 78, kind: 'case', notes: [[75, 77]], kids: [
+    { at: 79, kind: 'case', kids: [{ at: 80, kind: 'variable' }, { at: [81, 82], kind: 'command' }, { at: 84, kind: 'command', notes: [83] }] },
+    { at: 86, kind: 'case', kids: [{ at: 89, kind: 'variable', notes: [[87, 88]] }, { at: 90, kind: 'command' }, { at: 91, kind: 'command' }] },
   ] },
-  { at: [95, 97], kind: 'comment' },
-  { at: 98, kind: 'if', kids: [{ at: 99, kind: 'command' }] },
-  { at: [102, 104], kind: 'comment' },
-  { at: 105, kind: 'if', kids: [
+  { at: 98, kind: 'if', notes: [[95, 97]], kids: [{ at: 99, kind: 'command' }] },
+  { at: 105, kind: 'if', notes: [[102, 104]], kids: [
     { at: 106, kind: 'variable' },
-    { at: [107, 108], kind: 'comment' },
-    { at: 109, kind: 'loop', kids: [{ at: 110, kind: 'if' }, { at: [111, 114], kind: 'case' }] },
-    { at: 116, kind: 'comment' },
-    { at: 117, kind: 'variable' },
+    { at: 109, kind: 'loop', notes: [[107, 108]], kids: [{ at: 110, kind: 'if' }, { at: [111, 114], kind: 'case' }] },
+    { at: 117, kind: 'variable', notes: [116] },
     { at: 118, kind: 'variable' },
     { at: 119, kind: 'command' },
     { at: 120, kind: 'command' },
     { at: 121, kind: 'command' },
-    { at: 122, kind: 'comment' },
-    { at: 123, kind: 'pipeline', kids: [{ at: 124, kind: 'command' }, { at: 125, kind: 'command' }] },
+    { at: 123, kind: 'pipeline', notes: [122], kids: [{ at: 124, kind: 'command' }, { at: 125, kind: 'command' }] },
   ] },
   { at: 129, kind: 'command' },
   { at: 130, kind: 'command' },
 ]
 
 describe('shell 代码块树', () => {
-  it('fetch-runtime.sh：解释器、选项、变量 / 常量、分情况（短的整条一块，长的每个情况一块子块）、函数（紧贴的注释算进头部）、命令、管道后面的循环主体是子块', async () => {
+  it('fetch-runtime.sh：解释器、选项、变量 / 常量、分情况（短的整条一块，长的每个情况一块子块）、函数（紧贴的注释算进头部）、命令、管道后面的循环主体是子块；注释挂到后面那块上', async () => {
     expect(await tree(FETCH)).toEqual(FETCH_TREE)
   })
 
@@ -218,3 +210,43 @@ describe('shell 命令、名字', () => {
     }
   })
 })
+
+describe('shell 注释挂到它讲的块上', () => {
+  it('#! 后面隔着空行的是文件的说明；同一层后面最近的那块（隔着空行也算），和函数的说明并存；主体最后的挂到前面那块；文件最后的挂到最后一块', async () => {
+    const source = [
+      '#!/usr/bin/env bash',
+      '# 文件的说明',
+      '',
+      'set -e',
+      '',
+      '# 讲 fetch：隔着空行',
+      '',
+      '# 下载一个文件',
+      'fetch() {',
+      '  # 先检查',
+      '  if [ -z "$1" ]; then',
+      '    # 只有注释的分支',
+      '    :',
+      '  fi',
+      '  curl -fsSL "$1"',
+      '  # 函数体最后的注释',
+      '}',
+      '',
+      '# 文件最后的注释',
+    ].join('\n')
+    expect(await tree(source)).toEqual([
+      { at: 1, kind: 'interpreter' },
+      { at: 2, kind: 'comment' },
+      { at: 4, kind: 'options' },
+      { at: [8, 9], kind: 'function', notes: [6, 19], kids: [
+        { at: 11, kind: 'if', notes: [10], kids: [{ at: 13, kind: 'command', notes: [12] }] },
+        { at: 15, kind: 'command', notes: [16] },
+      ] },
+    ])
+    expect((await facts(source))[8]).toMatchObject({ doc: '# 下载一个文件' })
+  })
+
+  it('#! 后面紧挨着第一块代码的注释挂到它上面', async () => {
+    expect(await tree('#!/bin/sh\n# 出错就停\nset -e\n')).toEqual([{ at: 1, kind: 'interpreter' }, { at: 3, kind: 'options', notes: [2] }])
+  })
+})
diff --git a/vscode/src/codeReader/languages/bash.ts b/vscode/src/codeReader/languages/bash.ts
index b86b670..8a09452 100644
--- a/vscode/src/codeReader/languages/bash.ts
+++ b/vscode/src/codeReader/languages/bash.ts
@@ -2,7 +2,7 @@ import type { BlockShape, CodeBlock, CommandFacts, CommandWord, DeclaratorFacts,
 import type { CommentRules, ListBlocks } from './shared'
 import * as path from 'node:path'
 import { bashNameReader } from './bashNames'
-import { children, compoundShape, leafBlock, leafShape, listBlocks, named } from './shared'
+import { attachComments, children, compoundShape, leafBlock, leafShape, listBlocks, named } from './shared'
 
 /** 按习惯当常量用的名字：全大写（可带数字、下划线）。 */
 const CONSTANT_NAME = /^[A-Z][A-Z0-9_]*$/
@@ -627,7 +627,7 @@ function bashSteps(root: Node): StepBlocks {
   const [only, ...more] = items.filter(item => item.type !== 'comment')
   if (only && more.length === 0 && andChain(only))
     return { blocks: chainOperands(only).flatMap(stepBlocks), chained: true }
-  return { blocks: statements(items, -1, true), chained: false }
+  return { blocks: attachComments(statements(items, -1, true), undefined, false), chained: false }
 }
 
 /** bash / sh / zsh 脚本（VS Code 的 languageId 是 shellscript）的语言插件。@param wasmDir 语法包 .wasm 所在目录 */
@@ -636,9 +636,10 @@ export function createBashAdapter(wasmDir: string): LanguageAdapter {
     id: 'bash',
     languageIds: ['shellscript'],
     grammarPath: () => path.join(wasmDir, 'tree-sitter-bash.wasm'),
-    toBlocks: root => programBlocks(root),
+    toBlocks: root => attachComments(programBlocks(root)),
     steps: root => bashSteps(root),
     tokenRole: bashTokenRole,
+    lineComment: '#',
     command: bashCommand,
     symbols: root => bashSymbols(root),
     displayNames: bashNameReader,
diff --git a/vscode/src/codeReader/languages/dockerfile.test.ts b/vscode/src/codeReader/languages/dockerfile.test.ts
index 36199d0..b4f958b 100644
--- a/vscode/src/codeReader/languages/dockerfile.test.ts
+++ b/vscode/src/codeReader/languages/dockerfile.test.ts
@@ -30,8 +30,7 @@ const NEXT_TREE: Outline[] = [
     { at: 12, kind: 'copy' },
     { at: 13, kind: 'copy' },
     { at: 14, kind: 'variable' },
-    { at: [15, 16], kind: 'comment' },
-    { at: 17, kind: 'variable' },
+    { at: 17, kind: 'variable', notes: [[15, 16]] },
     { at: 18, kind: 'variable' },
     { at: 19, kind: 'run' },
   ] },
@@ -42,8 +41,7 @@ const NEXT_TREE: Outline[] = [
     { at: 28, kind: 'variable' },
     { at: [30, 31], kind: 'run' },
     { at: [33, 34], kind: 'copy' },
-    { at: 35, kind: 'comment' },
-    { at: 36, kind: 'copy' },
+    { at: 36, kind: 'copy', notes: [35] },
     { at: 38, kind: 'setting' },
     { at: 39, kind: 'setting' },
     { at: 41, kind: 'start' },
@@ -54,36 +52,25 @@ const NEXT_TREE: Outline[] = [
 const BACKEND_TREE: Outline[] = [
   { at: [1, 4], kind: 'stage', kids: [
     { at: [6, 7], kind: 'label' },
-    { at: [9, 12], kind: 'comment' },
-    { at: [13, 25], kind: 'run' },
-    { at: [27, 31], kind: 'comment' },
-    { at: [32, 33], kind: 'copy' },
+    { at: [13, 25], kind: 'run', notes: [[9, 12]] },
+    { at: [32, 33], kind: 'copy', notes: [[27, 31]] },
     { at: [34, 35], kind: 'run' },
     { at: 37, kind: 'copy' },
-    { at: [39, 41], kind: 'comment' },
-    { at: [42, 44], kind: 'run' },
+    { at: [42, 44], kind: 'run', notes: [[39, 41]] },
     { at: 45, kind: 'setting' },
     { at: 46, kind: 'variable' },
     { at: 48, kind: 'setting' },
-    { at: [50, 53], kind: 'comment' },
-    { at: [54, 65], kind: 'copy' },
-    { at: 67, kind: 'comment' },
-    { at: [68, 79], kind: 'run' },
-    { at: 81, kind: 'comment' },
-    { at: 82, kind: 'copy' },
-    { at: [83, 84], kind: 'comment' },
-    { at: [85, 89], kind: 'copy' },
-    { at: 91, kind: 'comment' },
-    { at: 92, kind: 'run' },
-    { at: [94, 95], kind: 'comment' },
-    { at: 96, kind: 'run' },
+    { at: [54, 65], kind: 'copy', notes: [[50, 53]] },
+    { at: [68, 79], kind: 'run', notes: [67] },
+    { at: 82, kind: 'copy', notes: [81] },
+    { at: [85, 89], kind: 'copy', notes: [[83, 84]] },
+    { at: 92, kind: 'run', notes: [91] },
+    { at: 96, kind: 'run', notes: [[94, 95]] },
     { at: 98, kind: 'variable' },
-    { at: 100, kind: 'comment' },
-    { at: 101, kind: 'variable' },
+    { at: 101, kind: 'variable', notes: [100] },
     { at: 102, kind: 'variable' },
     { at: 104, kind: 'setting' },
-    { at: 106, kind: 'comment' },
-    { at: [107, 108], kind: 'health' },
+    { at: [107, 108], kind: 'health', notes: [106] },
     { at: 110, kind: 'start' },
   ] },
 ]
@@ -238,3 +225,29 @@ describe('dockerfile 嵌着的 shell、命令、名字', () => {
     expect(roles).toEqual(expect.arrayContaining(['FROM:keyword', 'node:type', 'AS:keyword', 'deps:variable', 'COPY:keyword', 'a:string', '/b:string', 'PORT:constant', 'X:constant']))
   })
 })
+
+describe('dockerfile 注释挂到它讲的块上', () => {
+  it('解析指令后面隔着空行的是文件的说明；阶段里挂到后面那条指令，阶段最后的挂到前面那条；FROM 上面紧贴的照旧是阶段的说明', async () => {
+    const source = [
+      '# syntax=docker/dockerfile:1.7',
+      '',
+      '# 文件的说明',
+      '',
+      '# 基础镜像',
+      'FROM node:22 AS base',
+      '# 讲 WORKDIR',
+      '',
+      'WORKDIR /app',
+      'RUN npm ci',
+      '# 阶段最后的注释',
+    ].join('\n')
+    expect(await tree(source)).toEqual([
+      { at: 1, kind: 'directive' },
+      { at: 3, kind: 'comment' },
+      { at: [5, 6], kind: 'stage', kids: [
+        { at: 9, kind: 'setting', notes: [7] },
+        { at: 10, kind: 'run', notes: [11] },
+      ] },
+    ])
+  })
+})
diff --git a/vscode/src/codeReader/languages/dockerfile.ts b/vscode/src/codeReader/languages/dockerfile.ts
index 18c4daf..1636beb 100644
--- a/vscode/src/codeReader/languages/dockerfile.ts
+++ b/vscode/src/codeReader/languages/dockerfile.ts
@@ -1,7 +1,7 @@
 import type { CodeBlock, CommandFacts, CommandForm, CommandWord, DeclaratorFacts, DirectiveFacts, DisplayName, DisplayNameReader, EmbeddedCode, InstructionFlag, LanguageAdapter, LocalSymbol, Node, ParserDirective, SourceRange, SourceSpan, StageFacts, TextBlock, TokenRole } from '../contract'
 import * as path from 'node:path'
 import { COMMENT_MARK, commentTag } from './displayNames'
-import { children, leafBlock, leafShape, named } from './shared'
+import { attachComments, children, leafBlock, leafShape, named } from './shared'
 
 /** RUN、shell 写法的 CMD / ENTRYPOINT、HEALTHCHECK 的检查命令交给 shell 的语言插件读。 */
 const SHELL = 'shellscript'
@@ -422,8 +422,9 @@ export function createDockerfileAdapter(wasmDir: string): LanguageAdapter {
     id: 'dockerfile',
     languageIds: ['dockerfile'],
     grammarPath: () => path.join(wasmDir, 'tree-sitter-dockerfile.wasm'),
-    toBlocks: root => dockerBlocks(root),
+    toBlocks: root => attachComments(dockerBlocks(root)),
     tokenRole: dockerTokenRole,
+    lineComment: '#',
     command: dockerCommand,
     symbols: root => dockerSymbols(root),
     embedded: root => root.descendantsOfType('shell_command').flatMap((node) => {
diff --git a/vscode/src/codeReader/languages/exceptions.test.ts b/vscode/src/codeReader/languages/exceptions.test.ts
index e2a4945..ab6454d 100644
--- a/vscode/src/codeReader/languages/exceptions.test.ts
+++ b/vscode/src/codeReader/languages/exceptions.test.ts
@@ -8,7 +8,7 @@ import { celeryRule } from '../rules/celery'
 import { dataclassRule } from '../rules/dataclass'
 import { enumRule } from '../rules/enum'
 import { sqlalchemyRule } from '../rules/sqlalchemy'
-import { flatSegments, inlineOf, outline, propertyLines, readFixture, runtime, WASM_DIR, withBlocks } from '../testSupport'
+import { commentText, flatSegments, inlineOf, outline, propertyLines, readFixture, runtime, WASM_DIR, withBlocks } from '../testSupport'
 import { pythonZhTranslator } from '../translators/pythonZh'
 import { typescriptZhTranslator } from '../translators/typescriptZh'
 import { createPythonAdapter } from './python'
@@ -197,7 +197,7 @@ describe('异常卡片（Python）', () => {
     })
   })
 
-  it('类属性：给一个名字赋值（带不带注解、有没有值），说明取上面的注释块、行尾注释、属性 docstring；连着赋值、解构赋值、方法照常是子块；构造参数去掉 self', async () => {
+  it('类属性：给一个名字赋值（带不带注解、有没有值），说明取讲它的注释、行尾注释、属性 docstring；连着赋值、解构赋值、方法照常是子块，讲方法的注释挂在方法上；构造参数去掉 self', async () => {
     const list = await pyViews(PY_CASES)
     expect(lines(list, 'Base')).toEqual([
       '名称: Base',
@@ -217,12 +217,11 @@ describe('异常卡片（Python）', () => {
     const base = named(list, 'Base')
     expect(base.children.map(child => source[child.startLine].trim())).toEqual([
       '# 讲方法的注释',
-      'def describe(self) -> str:',
       'a = b = 2',
       'x, y = 1, 2',
       'def __init__(self, message: str, *, level: int = 1, **extra) -> None:',
-      '# 收尾',
     ])
+    expect(base.children.map(commentText)).toEqual(['讲方法的注释', undefined, undefined, '收尾'])
     expect(lines(list, 'Loose').slice(-2)).toEqual(['构造参数: 1 个', '  *args | 未标注 | '])
     expect(lines(list, 'Payload')).toEqual(['名称: Payload', '访问级别: 公共', '装饰器: @dataclass', '继承: ValueError', '属性: 1 个', '  field | 整数 | 0'])
     expect(named(list, 'Local').attributes).toEqual({ kind: 'exception' })
diff --git a/vscode/src/codeReader/languages/python.test.ts b/vscode/src/codeReader/languages/python.test.ts
index 3231910..ddd4209 100644
--- a/vscode/src/codeReader/languages/python.test.ts
+++ b/vscode/src/codeReader/languages/python.test.ts
@@ -22,8 +22,7 @@ const SAMPLE: Outline[] = [
   { at: 6, kind: 'const' },
   { at: 7, kind: 'variable' },
   { at: [10, 11], kind: 'function', kids: [
-    { at: 12, kind: 'comment' },
-    { at: 13, kind: 'variable' },
+    { at: 13, kind: 'variable', notes: [12] },
     { at: 14, kind: 'if', kids: [{ at: 15, kind: 'return' }] },
     { at: 16, kind: 'else', kids: [{ at: 17, kind: 'variable' }] },
     { at: 18, kind: 'else', kids: [{ at: 19, kind: 'statement' }] },
@@ -51,7 +50,7 @@ describe('python 代码块树', () => {
     expect(await tree(readFixture('sample.py'))).toEqual(SAMPLE)
   })
 
-  it('装饰器算进头部；冒号后、主体前的注释归子块；循环的 else 是兄弟块；match 的 case 是子块 if', async () => {
+  it('装饰器算进头部；冒号后、主体前的注释挂到主体第一条语句上；循环的 else 是兄弟块；match 的 case 是子块 if', async () => {
     const source = [
       '@cache',
       'def load(key):',
@@ -68,8 +67,7 @@ describe('python 代码块树', () => {
     ].join('\n')
     expect(await tree(source)).toEqual([
       { at: [1, 2], kind: 'function', kids: [
-        { at: 3, kind: 'comment' },
-        { at: 4, kind: 'loop', kids: [{ at: 5, kind: 'variable' }] },
+        { at: 4, kind: 'loop', notes: [3], kids: [{ at: 5, kind: 'variable' }] },
         { at: 6, kind: 'else', kids: [{ at: 7, kind: 'statement' }] },
         { at: 8, kind: 'if', kids: [
           { at: 9, kind: 'if', kids: [{ at: 10, kind: 'return' }] },
@@ -79,7 +77,7 @@ describe('python 代码块树', () => {
     ])
   })
 
-  it('docstring 只认主体开头；不是开头、也没挂到赋值上的字符串是注释块，f-string、字节串照旧是语句', async () => {
+  it('docstring 只认主体开头；不是开头、也没挂到赋值上的字符串是注释，挂到后面那条语句上，f-string、字节串照旧是语句', async () => {
     const source = [
       'def f():',
       '    x = 1',
@@ -92,9 +90,7 @@ describe('python 代码块树', () => {
     expect(await tree(source)).toEqual([
       { at: 1, kind: 'function', kids: [
         { at: 2, kind: 'variable' },
-        { at: 3, kind: 'comment' },
-        { at: 4, kind: 'comment' },
-        { at: 5, kind: 'statement' },
+        { at: 5, kind: 'statement', notes: [3, 4] },
         { at: 6, kind: 'statement' },
         { at: 7, kind: 'statement' },
       ] },
@@ -116,21 +112,18 @@ describe('python 属性 docstring', () => {
     })
   }
 
-  it('attributeDocs.py：模块、类主体里紧跟在赋值后面的字符串并进那块，头部延到字符串结尾；隔着注释、不跟在赋值后面的是注释块', async () => {
+  it('attributeDocs.py：模块、类主体里紧跟在赋值后面的字符串并进那块，头部延到字符串结尾；隔着注释、不跟在赋值后面的是注释，挂到讲的块上', async () => {
     expect(await tree(readFixture('attributeDocs.py'))).toEqual([
       { at: 1, kind: 'comment' },
       { at: [3, 4], kind: 'const' },
       { at: [6, 8], kind: 'variable' },
       { at: [11, 12], kind: 'class', kids: [
         { at: [14, 15], kind: 'variable' },
-        { at: [17, 19], kind: 'field' },
-        { at: 21, kind: 'comment' },
-        { at: 22, kind: 'comment' },
+        { at: [17, 19], kind: 'field', notes: [21, 22] },
       ] },
       { at: 25, kind: 'function', kids: [
         { at: 26, kind: 'variable' },
-        { at: [27, 30], kind: 'comment' },
-        { at: 31, kind: 'statement' },
+        { at: 31, kind: 'statement', notes: [[27, 30]] },
         { at: 32, kind: 'statement' },
         { at: 33, kind: 'return' },
       ] },
@@ -158,8 +151,8 @@ describe('python 属性 docstring', () => {
       '    """不算"""',
     ].join('\n')
     expect(await tree(source)).toEqual([
-      { at: 1, kind: 'class', kids: [{ at: [2, 3], kind: 'field' }, { at: 4, kind: 'comment' }] },
-      { at: 5, kind: 'if', kids: [{ at: 6, kind: 'variable' }, { at: 7, kind: 'comment' }] },
+      { at: 1, kind: 'class', kids: [{ at: [2, 3], kind: 'field', notes: [4] }] },
+      { at: 5, kind: 'if', kids: [{ at: 6, kind: 'variable', notes: [7] }] },
     ])
     expect(await fieldDocs(source)).toEqual({ 2: '"A" "B"' })
   })
@@ -180,12 +173,11 @@ describe('python 函数、类的 docstring', () => {
     'def g(): "单行"',
   ].join('\n')
 
-  it('算进函数、类头部、不单独成块，它前面的注释也在头部里；后面的注释照旧成块', async () => {
+  it('算进函数、类头部、不单独成块，它前面的注释也在头部里；后面的注释挂到后面那条语句上', async () => {
     expect(await tree(source)).toEqual([
       { at: [1, 2], kind: 'class', kids: [
         { at: [3, 8], kind: 'function', kids: [
-          { at: 9, kind: 'comment' },
-          { at: 10, kind: 'return' },
+          { at: 10, kind: 'return', notes: [9] },
         ] },
       ] },
       { at: 11, kind: 'function' },
@@ -513,3 +505,55 @@ describe('python 调用', () => {
     expect(await calls('@cache\nclass A(Base):\n    pass')).toEqual([])
   })
 })
+
+describe('python 注释挂到它讲的块上', () => {
+  it('同一层后面最近的那块（隔着空行也算）；主体最后的挂到前面那块；主体里只有注释时挂到父块；文件最后的挂到最后一块', async () => {
+    const source = [
+      '"""模块说明。"""',
+      '',
+      'import os',
+      '',
+      '',
+      '# 讲 load：隔着空行',
+      'def load(path):',
+      '    """读出来。"""',
+      '    # 先检查',
+      '    if not path:',
+      '        return None',
+      '    return path',
+      '    # 函数体最后的注释',
+      '',
+      '',
+      'class Empty:',
+      '    """只有说明。"""',
+      '    # 只有注释的主体',
+      '',
+      '',
+      '# 文件最后的注释',
+    ].join('\n')
+    expect(await tree(source)).toEqual([
+      { at: 1, kind: 'comment' },
+      { at: 3, kind: 'import' },
+      { at: [7, 8], kind: 'function', notes: [6], kids: [
+        { at: 10, kind: 'if', notes: [9], kids: [{ at: 11, kind: 'return' }] },
+        { at: 12, kind: 'return', notes: [13] },
+      ] },
+      { at: [16, 17], kind: 'class', notes: [18, 21] },
+    ])
+  })
+
+  it('文件开头的注释和第一块代码隔着空行是文件的说明，紧挨着就挂到它上面；#! 和写编码的那行总是文件的', async () => {
+    expect(await tree('# 文件的说明\n\nimport os\n')).toEqual([{ at: 1, kind: 'comment' }, { at: 3, kind: 'import' }])
+    expect(await tree('# 讲导入\nimport os\n')).toEqual([{ at: 2, kind: 'import', notes: [1] }])
+    expect(await tree('#!/usr/bin/env python3\n# -*- coding: utf-8 -*-\n# 讲导入\nimport os\n')).toEqual([
+      { at: [1, 2], kind: 'comment' },
+      { at: 4, kind: 'import', notes: [3] },
+    ])
+  })
+
+  it('luffy 的 acquisition/repository.py：导入后面隔着两个空行的注释挂到类上，是类卡片的「注释」一行，类的编辑范围连着这几行', async () => {
+    const source = readFixture('acquisitionRepository.py')
+    const [klass] = (await tree(source)).filter(block => block.kind === 'class')
+    expect(klass).toMatchObject({ at: [19, 21], notes: [[13, 16]] })
+  })
+})
diff --git a/vscode/src/codeReader/languages/python.ts b/vscode/src/codeReader/languages/python.ts
index a90dd8f..df47b3a 100644
--- a/vscode/src/codeReader/languages/python.ts
+++ b/vscode/src/codeReader/languages/python.ts
@@ -1,8 +1,8 @@
-import type { Access, BlockShape, CallArgument, CallFacts, ClassFacts, CodeBlock, EntryFacts, FunctionFacts, ImportFacts, ImportItem, IterationClause, IterationFacts, IterationResult, LanguageAdapter, Node, ParameterFacts, TextKind, TokenRole } from '../contract'
+import type { Access, BlockShape, CallArgument, CallFacts, ClassFacts, CodeBlock, CommentBlock, EntryFacts, FunctionFacts, ImportFacts, ImportItem, IterationClause, IterationFacts, IterationResult, LanguageAdapter, Node, ParameterFacts, TextKind, TokenRole } from '../contract'
 import type { CommentRules, ExceptionRules } from './shared'
 import * as path from 'node:path'
 import { pythonNameReader } from './pythonNames'
-import { children, compoundShape, leafBlock, leafShape, listBlocks, named, sameNode, syntaxChildren, withExceptions } from './shared'
+import { attachComments, children, compoundShape, leafBlock, leafShape, listBlocks, named, sameNode, syntaxChildren, withExceptions } from './shared'
 
 /** 常量、类字段只认直接写在模块 / 类主体里的赋值；这两处的声明也才有访问级别。 */
 type Scope = 'module' | 'class' | 'other'
@@ -12,8 +12,25 @@ const PARAMETER_SEPARATORS = new Set(['keyword_separator', 'positional_separator
 const PATTERNS = new Set(['pattern_list', 'tuple_pattern', 'list_pattern'])
 /** 字符串开头（string_start）：普通字符串的前缀只有 r / u 或没有；f、t、b 开头的不是。 */
 const STRING_PREFIX = /^[ru]?["']/i
-// 只有 # 行注释；函数、类的说明是主体开头的 docstring，不是写在前面的注释
-const COMMENTS: CommentRules = { lineStyle: () => '#', isDoc: () => false, documents: new Set() }
+/** PEP 263 写编码的注释：`# -*- coding: utf-8 -*-`、`# vim: set fileencoding=utf-8 :`。 */
+const CODING = /^#.*?coding[:=]\s*[-\w.]+/
+
+/** 文件头两行里写给解释器看的注释：第一行的 `#!`，头两行里写编码的。 */
+function isPragma(comment: Node): boolean {
+  const row = comment.startPosition.row
+  return (row === 0 && comment.text.startsWith('#!')) || (row <= 1 && CODING.test(comment.text))
+}
+
+// 只有 # 行注释；函数、类的说明是主体开头的 docstring，不是写在前面的注释。写给解释器的那两行不和后面的注释连成一块
+const COMMENTS: CommentRules = { lineStyle: comment => isPragma(comment) ? '#!' : '#', isDoc: () => false, documents: new Set() }
+
+/** 讲整个文件的注释：模块开头的 docstring（第一条语句，注释不算），写给解释器的那两行。 */
+function aboutModule(comment: CommentBlock): boolean {
+  const { node } = comment
+  if (node.type === 'comment')
+    return isPragma(node)
+  return node.parent?.type === 'module' && sameNode(named(node.parent).find(child => child.type !== 'comment'), node)
+}
 
 function statements(items: Node[], scope: Scope, afterRow: number): CodeBlock[] {
   const docs = attributeDocs(items, scope)
@@ -636,8 +653,9 @@ export function createPythonAdapter(wasmDir: string): LanguageAdapter {
     id: 'python',
     languageIds: ['python'],
     grammarPath: () => path.join(wasmDir, 'tree-sitter-python.wasm'),
-    toBlocks: root => withExceptions(statements(named(root), 'module', -1), PYTHON_EXCEPTIONS),
+    toBlocks: root => withExceptions(attachComments(statements(named(root), 'module', -1), aboutModule), PYTHON_EXCEPTIONS),
     tokenRole: pythonTokenRole,
+    lineComment: '#',
     iteration: pythonIteration,
     call: pythonCall,
     displayNames: pythonNameReader,
diff --git a/vscode/src/codeReader/languages/rust.test.ts b/vscode/src/codeReader/languages/rust.test.ts
index 020e4c6..1d00f51 100644
--- a/vscode/src/codeReader/languages/rust.test.ts
+++ b/vscode/src/codeReader/languages/rust.test.ts
@@ -1,10 +1,11 @@
 import type { BlockView } from '../blockView'
+import type { Outline } from '../testSupport'
 import { describe, expect, it } from 'vitest'
 import { toBlockViews } from '../blockView'
 import { blockMarks } from '../diff/viewDiff'
 import { rustImplRule } from '../rules/rustImpl'
 import { isCrateRoot } from '../rules/rustTree'
-import { propertyLines, readFixture, viewLines, WASM_DIR, withBlocks } from '../testSupport'
+import { commentText, outline, propertyLines, readFixture, viewLines, WASM_DIR, withBlocks } from '../testSupport'
 import { rustZhTranslator } from '../translators/rustZh'
 import { createRustAdapter } from './rust'
 
@@ -144,15 +145,15 @@ describe('rust 语言卡片', () => {
     expect(mod?.kind).toBe('module')
     expect(list.some(block => block.kind === 'statement' && block.code.includes('const LIMIT'))).toBe(false)
     expect(list.filter(block => block.kind === 'statement').map(block => block.code)).toEqual(['mod other;'])
-    expect(mod?.children.map(block => block.kind)).toEqual(['comment', 'import', 'const', 'variable', 'function', 'function', 'statement', 'statement'])
+    expect(mod?.children.map(block => block.kind)).toEqual(['import', 'const', 'variable', 'function', 'function', 'statement', 'statement'])
     expect(viewLines(mod ? [mod] : [])).toEqual([
       'module 1',
       '  名称: platform',
       '  说明: 平台相关。',
       '  可见性: 公开',
-      '  comment 3: 读入。',
-      '  import 4',
+      '  import 3',
       '    来源: std::io',
+      '    注释: 读入。',
       '    导入项: 1 个',
       '      Read | —',
       '  const 5',
@@ -204,7 +205,7 @@ describe('rust 注释', () => {
     ].join('\n'))
   })
 
-  it('隔着空行、隔着语句的注释各是一块，行尾的 // 不单独成块', async () => {
+  it('文件开头隔着空行的注释是文件的说明，别的挂到后面那一项上（中间隔着空行也算），行尾的 // 不单独成块', async () => {
     const source = [
       '// 第一段',
       '//     缩进四格的代码',
@@ -218,15 +219,14 @@ describe('rust 注释', () => {
     const list = await views(source)
     expect(list.map(block => [block.kind, block.startLine + 1, block.endLine + 1])).toEqual([
       ['comment', 1, 2],
-      ['comment', 4, 4],
-      ['import', 5, 5],
-      ['comment', 6, 6],
-      ['const', 7, 7],
+      ['import', 4, 5],
+      ['const', 6, 7],
     ])
     expect(markdown(list[0])).toBe('第一段\n    缩进四格的代码')
+    expect(list.map(commentText)).toEqual([undefined, '第二段', '第三段'])
   })
 
-  it('/// 并进下一个函数当说明，//! 连着几行合成一块，// 和 /// 不合在一起', async () => {
+  it('/// 并进下一个函数当说明，//! 连着几行合成一块、是文件的说明，// 和 /// 不合在一起', async () => {
     const source = [
       '//! 本模块管凭证。',
       '//!',
@@ -242,11 +242,10 @@ describe('rust 注释', () => {
     const list = await views(source)
     expect(list.map(block => [block.kind, block.startLine + 1, block.endLine + 1])).toEqual([
       ['comment', 1, 3],
-      ['comment', 5, 5],
-      ['function', 6, 9],
+      ['function', 5, 9],
     ])
     expect(markdown(list[0])).toBe('本模块管凭证。\n\n第二段。')
-    expect(viewLines([list[2]!])).toContain('  说明: 读出这个账号的凭证。')
+    expect(viewLines([list[1]!])).toEqual(expect.arrayContaining(['  说明: 读出这个账号的凭证。', '  注释: 普通注释']))
   })
 
   it('连着几行的 /// 是一段说明，块标签拆开放：@param 进参数表、@return 跟在返回后面、@throws 成异常表；结构体的 @param 对到字段', async () => {
@@ -306,8 +305,8 @@ describe('rust 注释', () => {
     const list = await views(source)
     const mod = list.find(block => block.kind === 'module')
     const impl = list.find(block => block.kind === 'rust.impl')
-    expect(markdown(mod?.children[0])).toBe('一\n二')
-    expect(markdown(impl?.children.find(block => block.kind === 'comment'))).toBe('三\n\n四')
+    expect(commentText(mod?.children[0])).toBe('一\n二')
+    expect(commentText(impl?.children[0])).toBe('三\n\n四')
   })
 })
 
@@ -321,10 +320,11 @@ describe('rust 编译属性', () => {
       '',
     ].join('\n')
     const list = await views(source, '/repo/apps/desktop/src-tauri/src/main.rs')
-    expect(list.map(block => block.kind)).toEqual(['comment', 'attribute', 'function'])
+    expect(list.map(block => block.kind)).toEqual(['attribute', 'function'])
     expect(viewLines([card(list, 'attribute')])).toEqual([
-      'attribute 2',
+      'attribute 1',
       '  属性: windows_subsystem = "windows"',
+      '  注释: Prevents additional console window on Windows in release, DO NOT REMOVE!!',
       '  生效条件: 非 调试构建',
       '  作用范围: 整个 crate',
       '  说明: 在 Windows 上编译为图形界面程序（windows 子系统），启动时不弹出控制台窗口',
@@ -375,3 +375,46 @@ describe('rust 编译属性', () => {
     expect(['/p/src/credentials.rs', '/p/src/tests/helpers.rs', '/p/src/bin/tool/args.rs'].map(isCrateRoot)).toEqual([false, false, false])
   })
 })
+
+describe('rust 注释挂到它讲的项上', () => {
+  const tree = (source: string): Promise<Outline[]> => withBlocks(adapter, 'rust', source, outline)
+
+  it('同一层后面最近的那项（隔着空行也算），和 /// 说明并存；只有注释的 mod 挂到 mod 上；impl 最后的挂到前面那项；文件最后的挂到最后一项；//! 是文件的说明', async () => {
+    const source = [
+      '//! 凭证存储。',
+      '',
+      'use std::io;',
+      '',
+      '// 讲 load：隔着空行',
+      '',
+      '/// 读出凭证。',
+      'pub fn load() -> Option<String> { None }',
+      '',
+      'mod empty {',
+      '    // 只有注释的模块',
+      '}',
+      '',
+      'impl Store {',
+      '    // 讲 get',
+      '    fn get(&self) {}',
+      '    // impl 最后的注释',
+      '}',
+      '',
+      '// 文件最后的注释',
+    ].join('\n')
+    expect(await tree(source)).toEqual([
+      { at: 1, kind: 'comment' },
+      { at: 3, kind: 'import' },
+      { at: [7, 8], kind: 'function', notes: [5] },
+      { at: 10, kind: 'module', notes: [11] },
+      { at: 14, kind: 'impl', notes: [20], kids: [{ at: 16, kind: 'function', notes: [15, 17] }] },
+    ])
+  })
+
+  it('紧挨着第一项的注释挂到它上面；mod 里的 //! 交给那个 mod', async () => {
+    expect(await tree('// 讲导入\nuse std::io;\n\nmod inner {\n    //! 模块自己的\n    fn a() {}\n}\n')).toEqual([
+      { at: 2, kind: 'import', notes: [1] },
+      { at: 4, kind: 'module', notes: [5], kids: [{ at: 6, kind: 'function' }] },
+    ])
+  })
+})
diff --git a/vscode/src/codeReader/languages/rust.ts b/vscode/src/codeReader/languages/rust.ts
index 695008e..0908f81 100644
--- a/vscode/src/codeReader/languages/rust.ts
+++ b/vscode/src/codeReader/languages/rust.ts
@@ -1,8 +1,8 @@
-import type { Access, AttributeFacts, AttributeItem, CfgPredicate, ClassFacts, CodeBlock, EnumBlock, FunctionBlock, ImplBlock, ImportBlock, ImportItem, LanguageAdapter, Node, ParameterFacts, SourceSpan, TokenRole, TraitBlock } from '../contract'
+import type { Access, AttributeFacts, AttributeItem, CfgPredicate, ClassFacts, CodeBlock, CommentBlock, EnumBlock, FunctionBlock, ImplBlock, ImportBlock, ImportItem, LanguageAdapter, Node, ParameterFacts, SourceSpan, TokenRole, TraitBlock } from '../contract'
 import type { CommentRules } from './shared'
 import * as path from 'node:path'
 import { leadingAttributes, visibilityFacts } from '../rules/rustTree'
-import { children, compoundShape, extendHeader, headerSpan, isCommentNode, leafBlock, leafShape, listBlocks, named } from './shared'
+import { attachComments, children, compoundShape, extendHeader, headerSpan, isCommentNode, leafBlock, leafShape, listBlocks, named } from './shared'
 
 const STORAGE = new Set(['pub', 'async', 'const', 'static', 'mut', 'let'])
 
@@ -11,8 +11,9 @@ export function createRustAdapter(wasmDir: string): LanguageAdapter {
     id: 'rust',
     languageIds: ['rust'],
     grammarPath: () => path.join(wasmDir, 'tree-sitter-rust.wasm'),
-    toBlocks: root => topBlocks(named(root), -1),
+    toBlocks: root => attachComments(topBlocks(named(root), -1), aboutModule),
     tokenRole: rustTokenRole,
+    lineComment: '//',
   }
 }
 
@@ -34,6 +35,11 @@ const COMMENTS: CommentRules = {
   documents: new Set(['function', 'class', 'trait', 'impl', 'module', 'enum', 'const', 'variable']),
 }
 
+/** 讲所在模块或 crate 的内部文档注释（`//!`、`/*!`）：写在文件开头是文件的说明，写在 `mod` 身体里交给那个模块。 */
+function aboutModule(comment: CommentBlock): boolean {
+  return named(comment.node).some(child => child.type === 'inner_doc_comment_marker')
+}
+
 /** 文档注释记号：外部的 `/`（块注释是 `*`）、内部的 `!`；普通注释没有。 */
 function docMarker(comment: Node): string {
   return named(comment).find(child => child.type === 'outer_doc_comment_marker' || child.type === 'inner_doc_comment_marker')?.text ?? ''
diff --git a/vscode/src/codeReader/languages/shared.ts b/vscode/src/codeReader/languages/shared.ts
index 75b9aae..82eeb8d 100644
--- a/vscode/src/codeReader/languages/shared.ts
+++ b/vscode/src/codeReader/languages/shared.ts
@@ -1,4 +1,4 @@
-import type { BaseFacts, BlockShape, ClassBlock, ClassFacts, CodeBlock, DocumentedBlock, ExceptionBlock, FieldFacts, Node, ParameterFacts, SourceSpan, TextKind } from '../contract'
+import type { BaseFacts, BlockShape, ClassBlock, ClassFacts, CodeBlock, CommentBlock, DocumentedBlock, ExceptionBlock, FieldFacts, Node, ParameterFacts, SourceSpan, TextKind } from '../contract'
 
 /** 语言插件共用的建树工具：取子节点、算头部、把一串语句切成块。 */
 
@@ -125,7 +125,7 @@ function documentable(block: CodeBlock, kinds: ReadonlySet<string>): block is Do
 }
 
 /**
- * 一串语句 → 块。注释单独成块，相邻行同一写法的行注释合成一块（见 CommentRules.lineStyle）；
+ * 一串语句 → 块。注释先成注释块（建好整棵树后由 attachComments 挂到它讲的块上），相邻行同一写法的行注释合成一块（见 CommentRules.lineStyle）；
  * 和前一条语句（或头部）同一行的注释是行尾注释，跟着那一行显示，不单独成块。
  * 文档注释（连着几行的算一段）和下一条语句之间只有空白、下一条语句是 CommentRules.documents 里的块时，它是这一块的说明，不单独成块；
  * 中间隔着的装饰器（不出块的语句）不算隔开。
@@ -193,6 +193,88 @@ export function listBlocks(
   return out
 }
 
+// ─── 注释挂到它讲的块上 ───────────────────────────────────────────────────────
+
+export function isCommentBlock(block: CodeBlock): block is CommentBlock {
+  return block.kind === 'comment'
+}
+
+/** 文件开头算不上「第一块代码」的块：`#!` 写的解释器、Dockerfile 的解析指令。 */
+const PREAMBLE_KINDS = new Set<string>(['interpreter', 'directive'])
+
+/** 块挂上注释，和它已有的（子块交上来的）合在一起照源码顺序排。 */
+function withComments(block: CodeBlock, comments: readonly CommentBlock[]): CodeBlock {
+  if (comments.length === 0)
+    return block
+  const all = [...(block.comments ?? []), ...comments].sort((a, b) => a.header.startIndex - b.header.startIndex)
+  return { ...block, comments: all }
+}
+
+/**
+ * 一层兄弟块里的注释块挂到它讲的块上：同一层里它后面最近的一块代码（中间隔空行也算），后面没有代码就挂到前面最近的一块；
+ * 这一层一块代码都没有时交给父块（up）。aboutScope 认出的（讲所在模块的，Rust 的 `//!`）也交给父块。先挂好各块的子块。
+ */
+function attachIn(list: readonly CodeBlock[], aboutScope: (comment: CommentBlock) => boolean): { blocks: CodeBlock[], up: CommentBlock[] } {
+  const up: CommentBlock[] = []
+  const done: CodeBlock[] = []
+  for (const block of list) {
+    if (isCommentBlock(block)) {
+      if (aboutScope(block))
+        up.push(block)
+      else
+        done.push(block)
+      continue
+    }
+    const inner = attachIn(block.children, aboutScope)
+    const changed = inner.blocks.length !== block.children.length || inner.blocks.some((child, i) => child !== block.children[i])
+    done.push(withComments(changed ? { ...block, children: inner.blocks } : block, inner.up))
+  }
+  if (!done.some(block => !isCommentBlock(block)))
+    return { blocks: [], up: [...up, ...done.filter(isCommentBlock)] }
+  const out: CodeBlock[] = []
+  let pending: CommentBlock[] = []
+  for (const block of done) {
+    if (isCommentBlock(block)) {
+      pending.push(block)
+      continue
+    }
+    out.push(withComments(block, pending))
+    pending = []
+  }
+  out[out.length - 1] = withComments(out[out.length - 1], pending)
+  return { blocks: out, up }
+}
+
+/**
+ * 注释挂到它讲的块上（BlockShape.comments），不再单独成块；语言插件建好整棵树后调一次。见 attachIn。
+ * 单独成块的只有文件开头的说明：第一块代码（`#!` 解释器、解析指令不算）之前的注释，和第一块代码之间隔着空行的；
+ * 紧挨着第一块代码（中间没空行）的那几段照常挂到它上面。aboutScope 认出的讲整个文件的注释（Python 模块开头的 docstring、
+ * Rust 的 `//!`、JSDoc 的 `@file`）写在文件开头时总是文件的说明，写在模块里时交给那个模块。
+ * file 为假时（嵌在别的语言里的一段代码）没有文件开头的说明，一块代码都没有时注释照旧单独成块。
+ */
+export function attachComments(blocks: readonly CodeBlock[], aboutScope: (comment: CommentBlock) => boolean = () => false, file = true): CodeBlock[] {
+  const first = blocks.findIndex(block => !isCommentBlock(block) && !PREAMBLE_KINDS.has(block.kind))
+  if (first < 0)
+    return [...blocks]
+  let header = file ? first : 0
+  for (let start = blocks[first].header.startRow; header > 0; header--) {
+    const block = blocks[header - 1]
+    if (!isCommentBlock(block) || aboutScope(block) || block.header.endRow + 1 < start)
+      break
+    start = block.header.startRow
+  }
+  const { blocks: rest, up } = attachIn(blocks.slice(header), aboutScope)
+  return [...blocks.slice(0, header), ...withScopeComments(rest, up)]
+}
+
+/** 文件这一层交上来的讲所在模块的注释（不在文件开头的）挂到第一块代码上。 */
+function withScopeComments(blocks: CodeBlock[], up: readonly CommentBlock[]): CodeBlock[] {
+  if (up.length === 0)
+    return blocks
+  const at = blocks.findIndex(block => !isCommentBlock(block))
+  return at < 0 ? [...up, ...blocks] : blocks.map((block, i) => i === at ? withComments(block, up) : block)
+}
+
 /** 同一个节点：web-tree-sitter 每次取子节点都会新建对象，只能按位置和类型比。 */
 export function sameNode(a: Node | null | undefined, b: Node): boolean {
   return !!a && a.startIndex === b.startIndex && a.endIndex === b.endIndex && a.type === b.type
@@ -216,15 +298,6 @@ function classBlocks(blocks: readonly CodeBlock[]): ClassBlock[] {
   return blocks.flatMap(block => [...(block.kind === 'class' ? [block] : []), ...classBlocks(block.children)])
 }
 
-/** 紧挨在 child 前面的注释块（连着几块都算，中间没隔别的子块），照源码顺序：讲的是它下面的这个 child。 */
-function leadingComments(children: readonly CodeBlock[], child: CodeBlock): CodeBlock[] {
-  const at = children.indexOf(child)
-  let from = at
-  while (from > 0 && children[from - 1].kind === 'comment')
-    from--
-  return children.slice(from, at)
-}
-
 /** 注释块里的各条注释（几条行注释连成的一块是好几个节点）；Python 当注释用的字符串是那个字符串。 */
 function commentNodes(block: CodeBlock): Node[] {
   if (!isCommentNode(block.node))
@@ -255,29 +328,24 @@ function ownDoc(block: CodeBlock): Node | undefined {
   }
 }
 
-/** 能重写的那段注释：注释块是整块；函数、类、枚举、异常、常量、变量是它的说明。没有说明就没有。 */
-export function commentSpan(block: CodeBlock): { startLine: number, endLine: number } | undefined {
-  if (block.kind === 'comment')
-    return { startLine: block.header.startRow, endLine: block.header.endRow }
-  const doc = ownDoc(block)
-  if (!doc)
-    return undefined
-  return { startLine: doc.startPosition.row, endLine: doc.endPosition.row }
-}
-
-/** 类属性的说明，照源码顺序：紧挨在它上面的注释块、它这一行行尾的注释、Python 紧跟在后面的属性 docstring。 */
-function fieldDocs(children: readonly CodeBlock[], block: CodeBlock): Node[] {
+/** 类属性的说明，照源码顺序：讲它的注释（BlockShape.comments）、它这一行行尾的注释、Python 紧跟在后面的属性 docstring。 */
+function fieldDocs(block: CodeBlock): Node[] {
   const trailing = block.node.nextNamedSibling
   const doc = ownDoc(block)
   return [
-    ...leadingComments(children, block).flatMap(commentNodes),
+    ...(block.comments ?? []).flatMap(commentNodes),
     ...(trailing && isCommentNode(trailing) && trailing.startPosition.row === block.node.endPosition.row ? [trailing] : []),
     ...(doc ? [doc] : []),
-  ]
+  ].sort((a, b) => a.startIndex - b.startIndex)
+}
+
+/** 块连同讲它的注释各段的范围。 */
+function spansOf(block: CodeBlock): SourceSpan[] {
+  return [block.header, nodeSpan(block.node), ...(block.comments ?? []).map(comment => comment.header)]
 }
 
 /**
- * 类块换成异常块：类属性连同紧挨在它前面的注释块并进属性表，构造函数（写了几个取最后一个，重载的实现写在最后）的参数进属性表，
+ * 类块换成异常块：类属性连同讲它的注释并进属性表，构造函数（写了几个取最后一个，重载的实现写在最后）的参数进属性表，
  * 留下的子块（方法、构造函数本身、别的语句）不管写在哪都照源码顺序留作子块；头部是整个类（到它连同各子块的最后一行），
  * 「编辑」时整段一起改，webview 在它编辑时不画留下的子块。
  */
@@ -289,19 +357,19 @@ function exceptionBlock(block: ClassBlock, rules: ExceptionRules): ExceptionBloc
   for (const child of children) {
     const field = rules.field(child)
     if (field) {
-      fields.push({ ...field, docs: fieldDocs(children, child) })
+      fields.push({ ...field, docs: fieldDocs(child) })
       members.push(child)
     }
     parameters = rules.constructorParameters(child) ?? parameters
   }
-  const absorbed = new Set(members.flatMap(member => [...leadingComments(children, member), member]))
-  const ends = [block.header, nodeSpan(block.node), ...children.flatMap(child => [child.header, nodeSpan(child.node)])]
+  const ends = [block.header, nodeSpan(block.node), ...children.flatMap(spansOf)]
   const last = ends.reduce((end, span) => span.endIndex > end.endIndex ? span : end)
   return {
     kind: 'exception',
     node: block.node,
     header: { ...block.header, endIndex: last.endIndex, endRow: last.endRow },
-    children: children.filter(child => !absorbed.has(child)),
+    children: children.filter(child => !members.includes(child)),
+    ...(block.comments && { comments: block.comments }),
     ...(block.attributes && { attributes: block.attributes }),
     facts: {
       name: facts.name,
diff --git a/vscode/src/codeReader/languages/typescript.test.ts b/vscode/src/codeReader/languages/typescript.test.ts
index 5217fef..f876ebb 100644
--- a/vscode/src/codeReader/languages/typescript.test.ts
+++ b/vscode/src/codeReader/languages/typescript.test.ts
@@ -131,7 +131,7 @@ describe('typeScript 代码块树', () => {
     ])
   })
 
-  it('类：方法 → function、字段 → field、注释 → comment，装饰器算进成员头部', async () => {
+  it('类：方法 → function、字段 → field，注释挂到它讲的成员上，装饰器算进成员头部', async () => {
     const source = [
       'export class Store extends Base {',
       '  // 缓存',
@@ -147,8 +147,7 @@ describe('typeScript 代码块树', () => {
     ].join('\n')
     expect(await tree(source)).toEqual([
       { at: 1, kind: 'class', kids: [
-        { at: 2, kind: 'comment' },
-        { at: 3, kind: 'field' },
+        { at: 3, kind: 'field', notes: [2] },
         { at: [4, 5], kind: 'function', kids: [{ at: 6, kind: 'return' }] },
         { at: 8, kind: 'function', kids: [{ at: 9, kind: 'statement' }] },
       ] },
@@ -208,7 +207,7 @@ describe('typeScript 代码块树', () => {
     ])
   })
 
-  it('相邻行的行注释合成一块，空行隔开的分开；行尾注释不单独成块', async () => {
+  it('相邻行的行注释合成一段，空行隔开的分开；文件开头隔着空行的是文件的说明，紧挨着代码的挂到代码上；行尾注释不单独成块', async () => {
     const source = [
       '// a',
       '// b',
@@ -219,8 +218,7 @@ describe('typeScript 代码块树', () => {
     ].join('\n')
     expect(await tree(source, 'javascript')).toEqual([
       { at: [1, 2], kind: 'comment' },
-      { at: 4, kind: 'comment' },
-      { at: 5, kind: 'const' },
+      { at: 5, kind: 'const', notes: [4] },
       { at: 6, kind: 'statement' },
     ])
   })
@@ -279,7 +277,7 @@ describe('typeScript 函数的 JSDoc', () => {
     'function i() {}',
   ].join('\n')
 
-  it('紧贴在函数块前面的算进函数头部、不单独成块；前面不是函数块、没紧贴、不是 JSDoc 的照旧是注释块', async () => {
+  it('紧贴在函数、常量块前面的算进它的头部、不单独成块；前面不是能带说明的块、没紧贴、不是 JSDoc 的是普通注释，挂到后面那块上', async () => {
     expect(await tree(source)).toEqual([
       { at: [1, 2], kind: 'function' },
       { at: [3, 5], kind: 'function' },
@@ -287,22 +285,15 @@ describe('typeScript 函数的 JSDoc', () => {
       { at: [8, 9], kind: 'function', kids: [{ at: [10, 11], kind: 'function' }] },
       { at: 13, kind: 'class', kids: [
         { at: [14, 16], kind: 'function' },
-        { at: 17, kind: 'comment' },
-        { at: 18, kind: 'field' },
+        { at: 18, kind: 'field', notes: [17] },
       ] },
-      { at: 20, kind: 'comment' },
-      { at: 21, kind: 'const' },
-      { at: 22, kind: 'comment' },
-      { at: 23, kind: 'function' },
-      { at: 24, kind: 'comment' },
-      { at: 25, kind: 'function' },
-      { at: 26, kind: 'comment' },
-      { at: 27, kind: 'comment' },
-      { at: 28, kind: 'function' },
+      { at: [20, 21], kind: 'const' },
+      { at: 23, kind: 'function', notes: [22] },
+      { at: 25, kind: 'function', notes: [24] },
+      { at: 28, kind: 'function', notes: [26, 27] },
       { at: 29, kind: 'statement' },
       { at: 30, kind: 'function' },
-      { at: 31, kind: 'comment' },
-      { at: 32, kind: 'function' },
+      { at: 32, kind: 'function', notes: [31] },
     ])
   })
 
@@ -314,6 +305,7 @@ describe('typeScript 函数的 JSDoc', () => {
     expect(found[8]).toMatchObject({ name: 'c', doc: '/** 函数值的变量 */' })
     expect(found[10]).toMatchObject({ name: 'd', doc: '/** 嵌套 */' })
     expect(found[14]).toMatchObject({ name: 'm', doc: '/** 方法，隔着装饰器 */', decorators: ['@memo()'] })
+    expect(found[20]).toMatchObject({ doc: '/** 常量 */', declarators: [{ name: 'y' }] })
     for (const line of [23, 25, 28, 30, 32])
       expect(found[line], `L${line}`).not.toHaveProperty('doc')
   })
@@ -498,8 +490,7 @@ describe('typeScript 类', () => {
     expect(await tree(readFixture('classes.ts.txt'))).toEqual([
       { at: 1, kind: 'import' },
       { at: [3, 9], kind: 'class', kids: [
-        { at: 10, kind: 'comment' },
-        { at: 11, kind: 'field' },
+        { at: 11, kind: 'field', notes: [10] },
         { at: 13, kind: 'function' },
         { at: 15, kind: 'class', kids: [{ at: 16, kind: 'function' }] },
       ] },
@@ -632,3 +623,48 @@ describe('typeScript 调用', () => {
     expect(await calls('new Date')).toEqual([])
   })
 })
+
+describe('typeScript 注释挂到它讲的块上', () => {
+  it('同一层后面最近的那块（隔着空行也算），和 JSDoc 说明并存；主体最后的挂到前面那块；主体里只有注释时挂到父块；文件最后的挂到最后一块；@file 是文件的说明', async () => {
+    const source = [
+      '/**',
+      ' * @file 读配置的工具。',
+      ' */',
+      'import { readFile } from \'node:fs/promises\'',
+      '',
+      '// 讲 load：隔着空行',
+      '',
+      '/** 读出配置。 */',
+      'export async function load(path: string) {',
+      '  // 先检查',
+      '  if (!path) {',
+      '    // 只有注释的分支',
+      '  }',
+      '  return readFile(path)',
+      '  // 函数体最后的注释',
+      '}',
+      '',
+      'class Empty {',
+      '  // 只有注释的类',
+      '}',
+      '',
+      '// 文件最后的注释',
+    ].join('\n')
+    expect(await tree(source)).toEqual([
+      { at: [1, 3], kind: 'comment' },
+      { at: 4, kind: 'import' },
+      { at: [8, 9], kind: 'function', notes: [6], kids: [
+        { at: 11, kind: 'if', notes: [10, 12] },
+        { at: 14, kind: 'return', notes: [15] },
+      ] },
+      { at: 18, kind: 'class', notes: [19, 22] },
+    ])
+  })
+
+  it('文件开头的注释和第一块代码隔着空行是文件的说明，紧挨着就挂到它上面', async () => {
+    expect(await tree('// 文件的说明\n\n// 紧挨着第一块代码\nconst x = 1\n')).toEqual([
+      { at: 1, kind: 'comment' },
+      { at: 4, kind: 'const', notes: [3] },
+    ])
+  })
+})
diff --git a/vscode/src/codeReader/languages/typescript.ts b/vscode/src/codeReader/languages/typescript.ts
index 6542591..a5e8aca 100644
--- a/vscode/src/codeReader/languages/typescript.ts
+++ b/vscode/src/codeReader/languages/typescript.ts
@@ -1,7 +1,7 @@
-import type { Access, BaseFacts, BlockShape, CallArgument, CallFacts, ClassFacts, CodeBlock, DeclaratorFacts, EntryFacts, EnumMemberFacts, FunctionFacts, ImportFacts, ImportItem, LanguageAdapter, Node, ParameterFacts, TextKind, TokenRole } from '../contract'
+import type { Access, BaseFacts, BlockShape, CallArgument, CallFacts, ClassFacts, CodeBlock, CommentBlock, DeclaratorFacts, EntryFacts, EnumMemberFacts, FunctionFacts, ImportFacts, ImportItem, LanguageAdapter, Node, ParameterFacts, TextKind, TokenRole } from '../contract'
 import type { CommentRules, ExceptionRules } from './shared'
 import * as path from 'node:path'
-import { children, compoundShape, extendHeader, headerSpan, leafBlock, leafShape, listBlocks, named, nodeSpan, sameNode, syntaxChildren, withExceptions } from './shared'
+import { attachComments, children, compoundShape, extendHeader, headerSpan, leafBlock, leafShape, listBlocks, named, nodeSpan, sameNode, syntaxChildren, withExceptions } from './shared'
 import { typescriptNameReader } from './typescriptNames'
 
 const GRAMMARS: Record<string, string> = {
@@ -22,7 +22,14 @@ const COMMENTS: CommentRules = {
   lineStyle: comment => comment.text.startsWith('//') ? '//' : undefined,
   // `/**/` 是空的块注释，不是 JSDoc
   isDoc: comment => comment.text.startsWith('/**') && !comment.text.startsWith('/**/'),
-  documents: new Set(['function', 'class', 'enum']),
+  documents: new Set(['function', 'class', 'enum', 'const', 'variable']),
+}
+
+/** 讲整个文件的 JSDoc：写了 `@file`、`@fileoverview` 或 `@overview`。 */
+const FILE_TAG = /^\/\*\*[\s\S]*@(?:file|fileoverview|overview)\b/
+
+function aboutFile(comment: CommentBlock): boolean {
+  return FILE_TAG.test(comment.node.text)
 }
 
 /** 带语句块主体的函数值（箭头函数 / 函数表达式）的主体。 */
@@ -639,8 +646,9 @@ export function createTypeScriptAdapter(wasmDir: string): LanguageAdapter {
         throw new Error(`TypeScript 语言插件不支持 ${languageId}`)
       return path.join(wasmDir, file)
     },
-    toBlocks: (root, _source, languageId) => withExceptions(blockReader(TYPED_LANGUAGES.has(languageId))(root), TYPESCRIPT_EXCEPTIONS),
+    toBlocks: (root, _source, languageId) => withExceptions(attachComments(blockReader(TYPED_LANGUAGES.has(languageId))(root), aboutFile), TYPESCRIPT_EXCEPTIONS),
     tokenRole: typescriptTokenRole,
+    lineComment: '//',
     call: typescriptCall,
     displayNames: typescriptNameReader,
   }
diff --git a/vscode/src/codeReader/libraryRules.test.ts b/vscode/src/codeReader/libraryRules.test.ts
index 0fa90ad..b6f6dde 100644
--- a/vscode/src/codeReader/libraryRules.test.ts
+++ b/vscode/src/codeReader/libraryRules.test.ts
@@ -97,13 +97,13 @@ describe('库规则：启用', () => {
 })
 
 describe('库规则：认领', () => {
-  it('认领的块换成替身：种类、badge、编辑范围是整个类；规则没并进来的子块（夹在中间的注释、方法）照源码顺序留下', async () => {
+  it('认领的块换成替身：种类、badge、编辑范围是整个类；规则没并进来的子块（方法）照源码顺序留下，讲并进来的子块的注释跟着并进来', async () => {
     const rule: LibraryRule = {
       ...cardRule('orm'),
       claim: (block) => {
         if (block.kind !== 'class')
           return undefined
-        const [table, , column] = block.children
+        const [table, column] = block.children
         return { kind: 'orm.card', badge: { label: '卡片', color: { dark: '#fff', light: '#000' }, icon: 'box' }, rows: [{ label: '名称', value: [{ text: 'User', role: 'type' }] }], absorbs: [table, column] }
       },
     }
@@ -117,7 +117,7 @@ describe('库规则：认领', () => {
       attributes: { kind: 'orm.card', access: 'public' },
       properties: [{ label: '名称' }],
     })
-    expect(card.children.map(child => [child.id, child.kind, child.startLine])).toEqual([['1.0', 'comment', 4], ['1.1', 'function', 7]])
+    expect(card.children.map(child => [child.id, child.kind, child.startLine])).toEqual([['1.0', 'function', 7]])
   })
 
   it('两个字段中间写着的方法：预览里照常是卡片的子块；卡片「编辑」写回整个类', async () => {
@@ -166,7 +166,7 @@ describe('库规则：认领', () => {
 
     const alone = await views(MODEL, [throwing])
     expect(alone[1]).toMatchObject({ kind: 'class', startLine: 2, headerEndLine: 2, endLine: 8 })
-    expect(alone[1].children.map(child => child.kind)).toEqual(['variable', 'comment', 'variable', 'function'])
+    expect(alone[1].children.map(child => child.kind)).toEqual(['variable', 'variable', 'function'])
   })
 
   it('替身不合约定（种类 id 没带规则 id、并进来的不是子块）：记下来，照常显示', async () => {
@@ -183,15 +183,20 @@ describe('库规则：认领', () => {
     ])
   })
 
-  it('略去的块不出块，后面的块 id 接着往下数；还有子块的块不能略去，记下来、照常显示', async () => {
+  it('略去的块不出块，后面的块 id 接着往下数；还有子块、挂着注释的块不能略去，记下来、照常显示', async () => {
     const omitting = (kind: string): LibraryRule => ({ ...cardRule('omit'), claim: block => block.kind === kind ? { omit: true } : undefined })
     const list = await views(MODEL, [omitting('import')])
     expect(list.map(view => [view.id, view.kind])).toEqual([['0', 'class']])
-    expect(list[0].children.map(child => child.id)).toEqual(['0.0', '0.1', '0.2', '0.3'])
+    expect(list[0].children.map(child => child.id)).toEqual(['0.0', '0.1', '0.2'])
 
     const reports: string[] = []
     expect((await views(MODEL, [omitting('class')], reports)).map(view => view.kind)).toEqual(['import', 'class'])
     expect(reports).toEqual(['库规则 omit 给第 3 行的 class 块的替身不合约定，这块照常显示：要略去的块还有子块'])
+
+    const commented: string[] = []
+    const [, kept] = await views(MODEL, [omitting('variable')], commented)
+    expect(kept.children.map(child => [child.kind, child.startLine])).toEqual([['variable', 4], ['function', 7]])
+    expect(commented).toEqual(['库规则 omit 给第 6 行的 variable 块的替身不合约定，这块照常显示：要略去的块挂着注释'])
   })
 
   it('挂在卡片子行上的子块：照常转成块，记下挂在哪一行的哪个子行；不是留下的子块、没有那一行 / 子行、放了两处的不合约定', async () => {
@@ -205,15 +210,15 @@ describe('库规则：认领', () => {
         ? { kind: `${id}.card`, badge: { label: '卡片', color: { dark: '#fff', light: '#000' }, icon: 'box' }, rows, absorbs: block.children.slice(0, 1), slots: slots(block) }
         : undefined,
     })
-    const [, card] = await views(MODEL, [slotting(block => [{ block: block.children[2], row: 0, item: 0 }, { block: block.children[3], row: 1, item: 0 }])])
-    expect(card.children.map(child => [child.kind, child.slot])).toEqual([['comment', undefined], ['variable', { row: 0, item: 0 }], ['function', { row: 1, item: 0 }]])
+    const [, card] = await views(MODEL, [slotting(block => [{ block: block.children[1], row: 0, item: 0 }, { block: block.children[2], row: 1, item: 0 }])])
+    expect(card.children.map(child => [child.kind, child.slot])).toEqual([['variable', { row: 0, item: 0 }], ['function', { row: 1, item: 0 }]])
 
     const reports: string[] = []
     const bad = await views(MODEL, [
       slotting(block => [{ block: block.children[0], row: 1, item: 0 }], 'absorbed'),
-      slotting(block => [{ block: block.children[3], row: 5, item: 0 }], 'row'),
-      slotting(block => [{ block: block.children[3], row: 1, item: 1 }], 'item'),
-      slotting(block => [{ block: block.children[3], row: 1, item: 0 }, { block: block.children[3], row: 0, item: 0 }], 'twice'),
+      slotting(block => [{ block: block.children[2], row: 5, item: 0 }], 'row'),
+      slotting(block => [{ block: block.children[2], row: 1, item: 1 }], 'item'),
+      slotting(block => [{ block: block.children[2], row: 1, item: 0 }, { block: block.children[2], row: 0, item: 0 }], 'twice'),
     ], reports)
     expect(bad[1].kind).toBe('class')
     expect(reports.map(report => report.replace(/^.*照常显示：/, ''))).toEqual([
@@ -235,7 +240,7 @@ describe('库规则：认领', () => {
     expect(recognized).toMatchObject({ kind: 'enum', startLine: 2, endLine: 8, attributes: { kind: 'enum', access: 'public' } })
     expect(recognized.badge).toBeUndefined()
     expect(propertyLines('properties' in recognized ? recognized.properties : [])).toEqual(['名称: User', '访问级别: 公共', '成员: 无'])
-    expect(recognized.children.map(child => child.kind)).toEqual(['comment', 'variable', 'function'])
+    expect(recognized.children.map(child => child.kind)).toEqual(['variable', 'function'])
 
     const reports: string[] = []
     const stranger: CodeBlock[] = []
@@ -250,7 +255,6 @@ describe('库规则：认领', () => {
     expect(fileAttributes(list, pythonZhTranslator.attributeNames).find(attribute => attribute.id === 'kind')?.values).toEqual([
       { id: 'import', name: '导入', count: 1 },
       { id: 'orm.card', name: 'orm 卡片', count: 1 },
-      { id: 'comment', name: '注释', count: 1 },
       { id: 'variable', name: '变量', count: 1 },
       { id: 'function', name: '函数', count: 1 },
       { id: 'return', name: '返回', count: 1 },
diff --git a/vscode/src/codeReader/libraryRules.ts b/vscode/src/codeReader/libraryRules.ts
index 27047d2..e0fa575 100644
--- a/vscode/src/codeReader/libraryRules.ts
+++ b/vscode/src/codeReader/libraryRules.ts
@@ -41,7 +41,7 @@ export interface Claim {
 /** 替身不合 RuleBlock 的约定时说哪儿不对。 */
 function problemOf(rule: LibraryRule, block: CodeBlock, claimed: RuleBlock): string | undefined {
   if ('omit' in claimed)
-    return block.children.length > 0 ? '要略去的块还有子块' : undefined
+    return block.children.length > 0 ? '要略去的块还有子块' : block.comments ? '要略去的块挂着注释' : undefined
   if (claimed.absorbs.some(child => !block.children.includes(child)))
     return '要并进来的块不是这块的子块'
   if ('as' in claimed)
diff --git a/vscode/src/codeReader/qa/claudeAsk.test.ts b/vscode/src/codeReader/qa/claudeAsk.test.ts
index 67b07f2..5b72e05 100644
--- a/vscode/src/codeReader/qa/claudeAsk.test.ts
+++ b/vscode/src/codeReader/qa/claudeAsk.test.ts
@@ -2,7 +2,8 @@ import type { runClaudeLines } from '../../cc/spawnClaude'
 import type { AskDeps, AskRun } from './claudeAsk'
 import { describe, expect, it } from 'vitest'
 import { CLAUDE_MISSING_MSG, ClaudeCancelledError, ClaudeError, ClaudeTimeoutError } from '../../cc/spawnClaude'
-import { askArgs, askClaude, askFailure } from './claudeAsk'
+import { COMMENT_SCHEMA } from '../commentRewrite'
+import { askArgs, askClaude, askCommentBody, askFailure } from './claudeAsk'
 
 type RunLinesOptions = Parameters<typeof runClaudeLines>[0]
 
@@ -168,3 +169,28 @@ describe('失败了给人看的话', () => {
     expect(askFailure(new ClaudeCancelledError(''))).toBe('Claude Code 没答成：Claude 调用已停止')
   })
 })
+
+describe('重写注释问一次', () => {
+  const structured = (body: string): string => line({ type: 'result', subtype: 'success', is_error: false, result: JSON.stringify({ body }), structured_output: { body }, session_id: 's1' })
+
+  it('只读、按 JSON Schema 交结构化结果：参数在只读那套后面加 --json-schema，stdin 里只有那一句提示；返回结构化结果里的正文', async () => {
+    const { deps, calls } = fakeClaude([{ lines: [structured('按名字找文件。')] }])
+    const events: unknown[] = []
+    const body = await askCommentBody({ prompt: '/ecc:writing-code-comments src/a.py:3-8', profilePath: '/p/sonnet.json', cwd: '/work', signal: new AbortController().signal, onEvent: event => events.push(event) }, deps)
+    expect(body).toBe('按名字找文件。')
+    expect(calls[0].args).toEqual([...askArgs({ profilePath: '/p/sonnet.json' }), '--json-schema', COMMENT_SCHEMA])
+    expect(calls[0].args).toEqual(expect.arrayContaining(['--tools', 'Read,Grep,Glob', '--permission-mode', 'dontAsk']))
+    expect(JSON.parse(COMMENT_SCHEMA)).toEqual({ type: 'object', properties: { body: { type: 'string' } }, required: ['body'], additionalProperties: false })
+    expect(sent(calls[0])).toEqual({ text: '/ecc:writing-code-comments src/a.py:3-8', images: [] })
+    expect(calls[0].cwd).toBe('/work')
+  })
+
+  it('只回了一段话、没交结构化结果：没有正文；Claude Code 报错、没给结果：抛错', async () => {
+    const free = fakeClaude([{ lines: [result('我改好了。', 's1')] }])
+    expect(await askCommentBody({ prompt: 'p', cwd: '/w', signal: new AbortController().signal, onEvent: () => {} }, free.deps)).toBeUndefined()
+    const failing = fakeClaude([{ lines: [line({ type: 'result', is_error: true, result: '额度用完了' })] }])
+    await expect(askCommentBody({ prompt: 'p', cwd: '/w', signal: new AbortController().signal, onEvent: () => {} }, failing.deps)).rejects.toThrow('额度用完了')
+    const empty = fakeClaude([{ lines: [] }])
+    await expect(askCommentBody({ prompt: 'p', cwd: '/w', signal: new AbortController().signal, onEvent: () => {} }, empty.deps)).rejects.toThrow('没给出结果')
+  })
+})
diff --git a/vscode/src/codeReader/qa/claudeAsk.ts b/vscode/src/codeReader/qa/claudeAsk.ts
index eae71ac..2d08f16 100644
--- a/vscode/src/codeReader/qa/claudeAsk.ts
+++ b/vscode/src/codeReader/qa/claudeAsk.ts
@@ -4,8 +4,10 @@
  */
 
 import type { ClaudeImage } from '../../cc/spawnClaude'
+import type { CommentEvent } from '../commentRewrite'
 import type { AnswerEvent } from './answerStream'
 import { buildStreamJsonLine, CLAUDE_MISSING_MSG, ClaudeCancelledError, ClaudeError, ClaudeTimeoutError, runClaudeLines } from '../../cc/spawnClaude'
+import { COMMENT_SCHEMA, createCommentParser } from '../commentRewrite'
 import { createAnswerParser } from './answerStream'
 
 /** 只给读、搜文件的工具。 */
@@ -17,8 +19,9 @@ export const ASK_TIMEOUT_MS = 5 * 60_000
  * 一次提问的命令行参数；问题连同贴的图片从 stdin 按 stream-json 发（见 askClaude），没贴图也一样。只读靠三层：可用的内置工具只剩读、搜（`--tools`）；这几个不用再批（`--allowedTools`），
  * 别的一律拒绝、不等人批（`--permission-mode dontAsk`，盖过 profile 里的 bypassPermissions）；
  * 不加载任何 MCP 服务（`--strict-mcp-config` 又不给 `--mcp-config`），免得 MCP 工具能改东西。
+ * jsonSchema：要模型按这个 JSON Schema 交结构化结果（`--json-schema`，结果在 result 行的 structured_output 里）。
  */
-export function askArgs(options: { profilePath?: string, resume?: string } = {}): string[] {
+export function askArgs(options: { profilePath?: string, resume?: string, jsonSchema?: string } = {}): string[] {
   return [
     ...(options.profilePath ? ['--settings', options.profilePath] : []),
     '--tools',
@@ -36,6 +39,7 @@ export function askArgs(options: { profilePath?: string, resume?: string } = {})
     'stream-json',
     '--verbose',
     '--include-partial-messages',
+    ...(options.jsonSchema ? ['--json-schema', options.jsonSchema] : []),
   ]
 }
 
@@ -112,6 +116,48 @@ export async function askClaude(run: AskRun, deps: AskDeps = DEFAULT_DEPS): Prom
   return once(run.prompt)
 }
 
+export interface CommentAsk {
+  /** 只有技能命令和代码块在哪的一句话（commentRewritePrompt） */
+  prompt: string
+  profilePath?: string
+  cwd: string
+  signal: AbortSignal
+  /** 重写的过程中：正文写出来的字、正在读什么 */
+  onEvent: (event: Extract<CommentEvent, { kind: 'text' | 'activity' }>) => void
+}
+
+/**
+ * 「重写注释」问一次：同问 AI 一样只读（模型能读那个文件，改不了，写回归扩展），按 COMMENT_SCHEMA 交结构化结果。
+ * 返回结果里的注释正文；只回了一段话、没交结构化结果时是 undefined。失败、超时、被叫停时抛 ClaudeError（及其子类），用 askFailure 换成给人看的话。
+ */
+export async function askCommentBody(ask: CommentAsk, deps: AskDeps = DEFAULT_DEPS): Promise<string | undefined> {
+  const parse = createCommentParser()
+  let result: { body?: string } | undefined
+  let failure: string | undefined
+  await deps.runLines({
+    args: askArgs({ profilePath: ask.profilePath, jsonSchema: COMMENT_SCHEMA }),
+    input: buildStreamJsonLine(ask.prompt, []),
+    cwd: ask.cwd,
+    signal: ask.signal,
+    timeoutMs: ASK_TIMEOUT_MS,
+    onLine: (line) => {
+      for (const event of parse(line)) {
+        if (event.kind === 'result')
+          result = event
+        else if (event.kind === 'error')
+          failure = event.message
+        else
+          ask.onEvent(event)
+      }
+    },
+  })
+  if (failure !== undefined)
+    throw new ClaudeError(failure, '')
+  if (!result)
+    throw new ClaudeError('Claude Code 结束了，但没给出结果', '')
+  return result.body
+}
+
 const AUTH_HINT = /\/login|log ?in|auth|401|403|api key|unauthori[sz]ed|credential|oauth/i
 
 /** 问失败了，给人看的一句话。 */
diff --git a/vscode/src/codeReader/rules/children.ts b/vscode/src/codeReader/rules/children.ts
index 0ca9de5..52191b1 100644
--- a/vscode/src/codeReader/rules/children.ts
+++ b/vscode/src/codeReader/rules/children.ts
@@ -27,24 +27,6 @@ export function annotatedAssignments(children: readonly CodeBlock[]): AnnotatedA
   return found
 }
 
-/** 紧挨在 child 前面的注释块（连着几块都算，中间没隔别的子块），照源码顺序：讲的是它下面的这个 child。 */
-export function leadingComments(children: readonly CodeBlock[], child: CodeBlock): CodeBlock[] {
-  const at = children.indexOf(child)
-  let from = at
-  while (from > 0 && children[from - 1].kind === 'comment')
-    from--
-  return children.slice(from, at)
-}
-
-/**
- * 要并进卡片的子块：成员连同各自前面紧挨着的注释块，照源码顺序。成员并进来了，讲它的注释跟着并，不在卡片下面单独留一块；
- * 讲别的子块（方法）的注释、最后一个子块后面的注释照常留下。
- */
-export function withLeadingComments(children: readonly CodeBlock[], members: readonly CodeBlock[]): CodeBlock[] {
-  return children.filter(child => members.includes(child))
-    .flatMap(member => [...leadingComments(children, member), member])
-}
-
 /** 注释块里的各条注释（几条行注释连成的一块是好几个节点）；当注释用的字符串是那个字符串。 */
 function commentNodes(block: CodeBlock): Node[] {
   if (block.node.type !== 'comment')
@@ -56,15 +38,15 @@ function commentNodes(block: CodeBlock): Node[] {
 }
 
 /**
- * Python 类主体里一个成员（赋值、只写注解的字段）的说明，照源码顺序：紧挨在它上面的注释块、它这一行行尾的注释、
- * 紧跟在它后面的属性 docstring。
+ * Python 类主体里一个成员（赋值、只写注解的字段）的说明，照源码顺序：讲它的注释（BlockShape.comments，它上面的、
+ * 类主体最后一个成员后面的）、它这一行行尾的注释、紧跟在它后面的属性 docstring。
  */
-export function memberDocs(children: readonly CodeBlock[], block: CodeBlock): Node[] {
+export function memberDocs(block: CodeBlock): Node[] {
   const trailing = block.node.nextSibling
   const doc = block.kind === 'variable' ? block.facts.doc : block.kind === 'field' ? block.doc : undefined
   return [
-    ...leadingComments(children, block).flatMap(commentNodes),
+    ...(block.comments ?? []).flatMap(commentNodes),
     ...(trailing?.type === 'comment' && trailing.startPosition.row === block.node.endPosition.row ? [trailing] : []),
     ...(doc ? [doc] : []),
-  ]
+  ].sort((a, b) => a.startIndex - b.startIndex)
 }
diff --git a/vscode/src/codeReader/rules/dataclass.test.ts b/vscode/src/codeReader/rules/dataclass.test.ts
index d860536..546c51a 100644
--- a/vscode/src/codeReader/rules/dataclass.test.ts
+++ b/vscode/src/codeReader/rules/dataclass.test.ts
@@ -91,7 +91,7 @@ const RULE_CASES = [
 describe('dataclasses 库规则（Python）', () => {
   it('luffy 的数据类：「数据类」卡片，选项写成大白话，字段表是 字段 | 类型 | 默认值 | 说明，方法照常是子块', async () => {
     const list = await views(SNAPSHOT)
-    expect(list.map(view => view.kind)).toEqual(['comment', 'import', 'import', 'import', ...Array.from({ length: 4 }, () => 'dataclasses.dataclass')])
+    expect(list.map(view => view.kind)).toEqual(['import', 'import', 'import', ...Array.from({ length: 4 }, () => 'dataclasses.dataclass')])
     expect(propertyLines(properties(named(list, 'AdminUserRow')))).toEqual([
       '名称: AdminUserRow',
       '说明: admin 用户列表单行: 用户 + 归属渠道 + 是否曾被邀请。',
diff --git a/vscode/src/codeReader/rules/dataclass.ts b/vscode/src/codeReader/rules/dataclass.ts
index c415e12..f622447 100644
--- a/vscode/src/codeReader/rules/dataclass.ts
+++ b/vscode/src/codeReader/rules/dataclass.ts
@@ -1,7 +1,7 @@
 import type { Access, BlockConcept, ClassBlock, CodeBlock, Inline, KindIconName, LibraryRule, Node, PreviewText, PropertyItem, PropertyRow, RuleCard, RuleContext, ThemeColor } from '../contract'
 import type { ParamDocs } from './docRows'
 import type { Call, LibraryNames } from './pythonTree'
-import { annotatedAssignments, memberDocs, withLeadingComments } from './children'
+import { annotatedAssignments, memberDocs } from './children'
 import { docBodyRows, paramDocs, throwsRows, unmatchedParamRows } from './docRows'
 import { aliasesOf, callOf, canonicalName, genericOf, libraryName, libraryNames, stringValue, syntaxChildren, unwrapType } from './pythonTree'
 import { hint, joined, name, plain, range, word } from './segments'
@@ -217,7 +217,7 @@ function defaultCell(field: Field, call: Call | undefined, env: Env): Inline[] {
  */
 function docCell(field: Field, children: readonly CodeBlock[], call: Call | undefined, initOnly: boolean, docs: ParamDocs, env: Env): PreviewText {
   const explicit = stringValue(call?.keywords.get('doc'))
-  const text = explicit ?? memberDocs(children, field.block).map(node => env.context.doc(node)?.body?.markdown).filter(Boolean).join(' ')
+  const text = explicit ?? memberDocs(field.block).map(node => env.context.doc(node)?.body?.markdown).filter(Boolean).join(' ')
   const written = text ? undefined : docs.of(field.name.text)
   if (written)
     return initOnly ? { markdown: `${env.words.initOnly} · ${written.markdown}` } : written
@@ -280,7 +280,7 @@ function dataclassCard(block: ClassBlock, decorator: Node, call: Call | undefine
     ...(concepts.length > 0 && { concepts }),
     rows,
     ...(facts.name && { defines: range(facts.name) }),
-    absorbs: withLeadingComments(children, [...fields.map(field => field.block), ...markers]),
+    absorbs: [...fields.map(field => field.block), ...markers],
   }
 }
 
diff --git a/vscode/src/codeReader/rules/enum.test.ts b/vscode/src/codeReader/rules/enum.test.ts
index 94f35a4..04db764 100644
--- a/vscode/src/codeReader/rules/enum.test.ts
+++ b/vscode/src/codeReader/rules/enum.test.ts
@@ -6,7 +6,7 @@ import { toBlockViews } from '../blockView'
 import { replaceLines } from '../editText'
 import { createPythonAdapter } from '../languages/python'
 import { createTypeScriptAdapter } from '../languages/typescript'
-import { flatSegments, inlineOf, propertyLines, readFixture, WASM_DIR, withBlocks } from '../testSupport'
+import { commentText, flatSegments, inlineOf, propertyLines, readFixture, WASM_DIR, withBlocks } from '../testSupport'
 import { pythonZhTranslator } from '../translators/pythonZh'
 import { typescriptZhTranslator } from '../translators/typescriptZh'
 import { celeryRule } from './celery'
@@ -96,7 +96,7 @@ const RULE_CASES = [
 describe('enum 库规则（Python）', () => {
   it('luffy 的枚举：和原型一样的枚举卡片，说明取行尾注释，类的 docstring 当说明', async () => {
     const list = await views(SNAPSHOT)
-    expect(list.map(view => view.kind)).toEqual(['comment', 'import', 'import', 'import', 'enum', 'enum', 'enum', 'enum', 'enum'])
+    expect(list.map(view => view.kind)).toEqual(['import', 'import', 'import', 'enum', 'enum', 'enum', 'enum', 'enum'])
     const commission = named(list, 'CommissionStatus')
     expect(commission.badge).toBeUndefined()
     expect(propertyLines(properties(commission))).toEqual([
@@ -162,7 +162,7 @@ describe('enum 库规则（Python）', () => {
     ])
   })
 
-  it('方法、嵌套类、不是成员的属性不管写在哪都照常是子块；成员前面的注释并进卡片，最后面的注释留下；卡片「编辑」写回整个类', async () => {
+  it('方法、嵌套类、不是成员的属性不管写在哪都照常是子块；成员前面的注释并进卡片，最后面的注释挂在最后一块上；卡片「编辑」写回整个类', async () => {
     const list = await views(RULE_CASES)
     const color = named(list, 'Color')
     const lines = RULE_CASES.split('\n')
@@ -178,8 +178,8 @@ describe('enum 库规则（Python）', () => {
       'def describe(self) -> str:',
       '_value_: int',
       'class Meta:',
-      '# 收尾',
     ])
+    expect(commentText(color.children.at(-1))).toBe('收尾')
     expect([lines[color.startLine], lines[color.endLine]]).toEqual(['class Color(E):', '    # 收尾'])
     expect(replaceLines(RULE_CASES, color.startLine, color.endLine, color.code)).toBe(RULE_CASES)
     const edited = replaceLines(RULE_CASES, color.startLine, color.endLine, color.code.replace('GREEN = 2', 'GREEN = 20'))
diff --git a/vscode/src/codeReader/rules/enum.ts b/vscode/src/codeReader/rules/enum.ts
index 76a3a2e..1fe4a9c 100644
--- a/vscode/src/codeReader/rules/enum.ts
+++ b/vscode/src/codeReader/rules/enum.ts
@@ -1,6 +1,6 @@
 import type { ClassBlock, CodeBlock, EnumMemberFacts, LibraryRule, Node, RuleFacts } from '../contract'
 import type { LibraryNames } from './pythonTree'
-import { memberDocs, withLeadingComments } from './children'
+import { memberDocs } from './children'
 import { libraryName, libraryNames, stringValue, syntaxChildren } from './pythonTree'
 
 /**
@@ -86,12 +86,12 @@ function enumBlock(block: ClassBlock, names: LibraryNames): RuleFacts | undefine
     const member = memberOf(child, ignored, names)
     if (!member)
       continue
-    members.push({ ...member, docs: memberDocs(children, child) })
+    members.push({ ...member, docs: memberDocs(child) })
     blocks.push(child)
   }
   return {
     as: { kind: 'enum', facts: { name: facts.name, doc: facts.doc, access: facts.access, decorators: facts.decorators, bases: facts.bases, members } },
-    absorbs: withLeadingComments(children, blocks),
+    absorbs: blocks,
   }
 }
 
diff --git a/vscode/src/codeReader/rules/pydantic.ts b/vscode/src/codeReader/rules/pydantic.ts
index ecdccb8..1bd3886 100644
--- a/vscode/src/codeReader/rules/pydantic.ts
+++ b/vscode/src/codeReader/rules/pydantic.ts
@@ -1,7 +1,7 @@
 import type { Access, ClassBlock, CodeBlock, ImportFacts, IndexEntry, Inline, KindIconName, LibraryRule, Node, PreviewText, PropertyItem, PropertyRow, RuleCard, RuleContext, ThemeColor, WorkspaceIndex } from '../contract'
 import type { ParamDocs } from './docRows'
 import type { Call, LibraryNames } from './pythonTree'
-import { annotatedAssignments, memberDocs, withLeadingComments } from './children'
+import { annotatedAssignments, memberDocs } from './children'
 import { docBodyRows, paramDocs, throwsRows, unmatchedParamRows } from './docRows'
 import { aliasesOf, callOf, canonicalName, genericOf, libraryName, libraryNames, stringValue, syntaxChildren, unwrapType } from './pythonTree'
 import { hint, joined, name, plain, range, word } from './segments'
@@ -338,7 +338,7 @@ function docCell(field: Field, children: readonly CodeBlock[], call: Call | unde
     return [{ text: literal, role: 'comment' }]
   if (description)
     return env.context.translate(description)
-  const text = memberDocs(children, field.block).map(node => env.context.doc(node)?.body?.markdown).filter(Boolean).join(' ')
+  const text = memberDocs(field.block).map(node => env.context.doc(node)?.body?.markdown).filter(Boolean).join(' ')
   return text ? [{ text, role: 'comment' }] : docs.of(field.name.text) ?? []
 }
 
@@ -386,7 +386,7 @@ function modelCard(block: ClassBlock, env: Env): RuleCard {
     badge: { label: words.kind, color: COLOR, icon: ICON },
     rows,
     ...(facts.name && { defines: range(facts.name) }),
-    absorbs: withLeadingComments(children, [...fields.map(field => field.block), ...(config ? [config.block] : [])]),
+    absorbs: [...fields.map(field => field.block), ...(config ? [config.block] : [])],
   }
 }
 
diff --git a/vscode/src/codeReader/rules/react.test.ts b/vscode/src/codeReader/rules/react.test.ts
index 1895131..fd1fbbc 100644
--- a/vscode/src/codeReader/rules/react.test.ts
+++ b/vscode/src/codeReader/rules/react.test.ts
@@ -55,7 +55,7 @@ async function card(source: string, name: string, lookup?: RuleContext['lookup']
 
 /** 卡片下面从第 line 行（1 起）开始的那一块子块。 */
 function childAt(view: BlockView, line: number): BlockView {
-  const found = view.children.find(child => child.startLine + 1 === line && child.kind !== 'comment')
+  const found = view.children.find(child => child.startLine + 1 === line)
   if (!found)
     throw new Error(`第 ${line} 行没有子块`)
   return found
@@ -265,8 +265,7 @@ describe('react 库规则：组件体一块一张卡片（luffy 的 PlanChecklis
       'variable 59',
       'variable 60',
       'variable 61',
-      'comment 62',
-      'variable 63',
+      'variable 62',
       'react.render 65',
     ])
   })
@@ -295,7 +294,7 @@ describe('react 库规则：组件体一块一张卡片（luffy 的 PlanChecklis
       '    if 39: 如果 (localStorage.getItem(PLAN_CHECKLIST_COLLAPSED_KEY) 全等 "1")',
       '      statement 40: queueMicrotask(() => setCollapsed(真));',
       '  catch 42: 捕获',
-      '    comment 43: localStorage 不可用 (隐私模式等) 时静默用默认',
+      '    注释: localStorage 不可用 (隐私模式等) 时静默用默认',
     ])
     const toggle = childAt(view, 47)
     expect(toggle.badge).toEqual({ label: '派生值', color: DATA, icon: 'sigma' })
@@ -311,7 +310,7 @@ describe('react 库规则：组件体一块一张卡片（luffy 的 PlanChecklis
       '  try 50: 尝试',
       '    statement 51: localStorage.setItem(PLAN_CHECKLIST_COLLAPSED_KEY, 如果 next 则 "1" 否则 "0");',
       '  catch 52: 捕获',
-      '    comment 53: 忽略写入失败',
+      '    注释: 忽略写入失败',
     ])
     expect(PLAN.slice(toggle.defines?.startIndex, toggle.defines?.endIndex)).toBe('toggle')
   })
@@ -369,8 +368,8 @@ describe('react 库规则：luffy 的 QueuedBubble（原型「编辑器全貌」
       '  if 187: 如果 (e.nativeEvent.isComposing)',
       '    return 187: 返回;',
       '  if 188: 如果 (e.key 全等 "Escape")',
-      '    comment 189: 修改框里的 Esc 只用来取消修改, 不再往外传: 页面上「连按两次 Esc 停止这一轮」不该把它算进去',
-      '    statement 190: e.preventDefault();',
+      '    statement 189: e.preventDefault();',
+      '      注释: 修改框里的 Esc 只用来取消修改, 不再往外传: 页面上「连按两次 Esc 停止这一轮」不该把它算进去',
       '    statement 191: e.stopPropagation();',
       '    statement 192: onCancel?.();',
       '  else 193: 否则 如果 (e.key 全等 "Enter" 并且 (e.metaKey 或者 e.ctrlKey))',
@@ -427,7 +426,7 @@ describe('react 库规则：数据源、派生值、副作用、事件处理函
     expect(rowLines(childAt(await card(SETTINGS, 'WorkspaceRootRow'), 90), '说明')).toEqual(['说明: 基于 desktop store 计算 displayPath(s.workspace_root, s.home)'])
   })
 
-  it('luffy 的 LegalDocPage：useMemo、渲染期间按条件重置写进更新位置、引用的使用位置、清理函数并进副作用、处理函数绑在每个按钮上，注释照常成块', async () => {
+  it('luffy 的 LegalDocPage：useMemo、渲染期间按条件重置写进更新位置、引用的使用位置、清理函数并进副作用、处理函数绑在每个按钮上，注释是讲的那张卡片的「注释」一行', async () => {
     const view = await card(LEGAL, 'LegalDocPage')
     expect(kinds(view)).toEqual([
       'react.source 58',
@@ -436,13 +435,10 @@ describe('react 库规则：数据源、派生值、副作用、事件处理函
       'react.derived 61',
       'react.ref 63',
       'react.state 64',
-      'comment 68',
-      'react.state 69',
+      'react.state 68',
       'if 70',
-      'comment 75',
-      'react.effect 76',
-      'comment 80',
-      'react.effect 81',
+      'react.effect 75',
+      'react.effect 80',
       'react.handler 104',
       'react.handler 112',
       'react.handler 116',
@@ -451,8 +447,8 @@ describe('react 库规则：数据源、派生值、副作用、事件处理函
     expect(lines(childAt(view, 61))).toEqual(['名称: headings', '计算表达式: extractHeadings(markdown)', '依赖项: markdown（useMemo）'])
     expect(lines(childAt(view, 63))).toEqual(['名称: scrollRef', '初始值: 空', '使用位置: <main> 的 ref 属性；副作用 1、副作用 2、handleSectionClick'])
     expect(lines(childAt(view, 64))).toEqual(['名称: activeSection', '初始值: headings[0]?.id ?? ""', '更新位置: 渲染期间，当 doc 不全等 prevDoc 时、副作用 2'])
-    const effect = childAt(view, 81)
-    expect(lines(effect)).toEqual(['触发时机: doc、headings 变化时', '清理函数: container.removeEventListener("scroll", handleScroll)'])
+    const effect = childAt(view, 80)
+    expect(lines(effect)).toEqual(['触发时机: doc、headings 变化时', '注释: 滚动时按 heading.top 计算当前高亮章节.', '清理函数: container.removeEventListener("scroll", handleScroll)'])
     expect(kinds(effect)).toEqual(['variable 82', 'if 83', 'function 84', 'statement 100'])
     expect(lines(childAt(view, 104))).toEqual(['名称: handleSectionClick', '参数: id: 字符串', '绑定事件: 每个 <button> 的 onClick（传入 h.id）'])
     expect(kinds(childAt(view, 104))).toEqual(['variable 105', 'variable 106', 'if 107'])
diff --git a/vscode/src/codeReader/rules/react.ts b/vscode/src/codeReader/rules/react.ts
index 3deea41..a538279 100644
--- a/vscode/src/codeReader/rules/react.ts
+++ b/vscode/src/codeReader/rules/react.ts
@@ -2,7 +2,7 @@ import type { CodeBlock, Doc, Inline, KindIconName, LibraryRule, Markdown, Node,
 import type { ParamDocs } from './docRows'
 import type { BindingFacts, BodyFacts, ClassFacts, ComponentFacts, DerivedFacts, EffectFacts, FieldFacts, FieldText, HandlerFacts, OutlineNode, Place, PropsFacts, ReadFacts, RefFacts, StateFacts } from './reactTree'
 import { docBodyRows, paramDocCell, paramDocs, returnNote, throwsRows, unmatchedParamRows } from './docRows'
-import { argumentsOf, attributeName, attributeValue, bodyOf, clientDirective, commentText, componentAt, componentOf, componentOfFunction, componentsIn, declaredTypes, enclosingComponent, enclosingFunction, isComponentTag, isFunction, isJsx, named, outlineOf, parametersOf, placesOf, propsOf, sameNode, statementsOf, stringContent, unwrap } from './reactTree'
+import { argumentsOf, attributeName, attributeValue, bodyOf, clientDirective, commentText, componentOf, componentOfFunction, componentsIn, declaredTypes, enclosingComponent, enclosingFunction, isComponentTag, isFunction, isJsx, named, outlineOf, parametersOf, placesOf, propsOf, sameNode, statementsOf, stringContent, unwrap } from './reactTree'
 import { hint, joined, name, plain, range } from './segments'
 
 /**
@@ -1044,19 +1044,12 @@ function bodyCard(block: CodeBlock, env: Env): RuleCard | undefined {
 }
 
 /**
- * 讲在了组件卡片里、不再单独成块的：文件开头的 "use client"（文件里有组件时，讲成「客户端组件」标签），
- * 紧贴在组件前面、没并进组件块头部的 JSDoc（值是 memo(…)、直接返回 JSX 的箭头函数这类常量块，讲成「说明」）。
+ * 讲在了组件卡片里、不再单独成块的：文件开头的 "use client"（文件里有组件时，讲成「客户端组件」标签）。
+ * 挂着注释的不略去，注释照常在它的「注释」一行里。
  */
 function omitted(block: CodeBlock): boolean {
   const root = block.node.tree.rootNode
-  if (block.kind === 'statement')
-    return sameNode(clientDirective(root), block.node) && componentsIn(root).length > 0
-  if (block.kind === 'comment') {
-    const next = block.node.nextSibling
-    const component = next ? componentAt(next) : undefined
-    return !!component?.doc && sameNode(component.doc, block.node)
-  }
-  return false
+  return block.kind === 'statement' && !block.comments && sameNode(clientDirective(root), block.node) && componentsIn(root).length > 0
 }
 
 export const reactRule: LibraryRule = {
diff --git a/vscode/src/codeReader/rules/rustLibs.test.ts b/vscode/src/codeReader/rules/rustLibs.test.ts
index f000c64..69838a9 100644
--- a/vscode/src/codeReader/rules/rustLibs.test.ts
+++ b/vscode/src/codeReader/rules/rustLibs.test.ts
@@ -75,9 +75,9 @@ describe('serde 与 thiserror', () => {
       '  来源: sqlx',
       '  导入项: 1 个',
       '    query_as | —',
-      'sqlx.query 40',
-      '  说明: 按 id 取一行。',
+      'sqlx.query 39',
       '  SQL: SELECT id, name FROM agents WHERE id = $1',
+      '  注释: 按 id 取一行。',
       '  参数: $1 = id',
       '  返回类型: AgentRow',
       'import 42',
diff --git a/vscode/src/codeReader/rules/sqlalchemy.test.ts b/vscode/src/codeReader/rules/sqlalchemy.test.ts
index 6048608..343e6fd 100644
--- a/vscode/src/codeReader/rules/sqlalchemy.test.ts
+++ b/vscode/src/codeReader/rules/sqlalchemy.test.ts
@@ -4,7 +4,7 @@ import { describe, expect, it } from 'vitest'
 import { toBlockViews } from '../blockView'
 import { replaceLines } from '../editText'
 import { createPythonAdapter } from '../languages/python'
-import { flatSegments, inlineOf, propertyLines, readFixture, WASM_DIR, withBlocks } from '../testSupport'
+import { commentText, flatSegments, inlineOf, propertyLines, readFixture, WASM_DIR, withBlocks } from '../testSupport'
 import { pythonZhTranslator } from '../translators/pythonZh'
 import { sqlalchemyRule } from './sqlalchemy'
 
@@ -108,7 +108,6 @@ describe('sqlAlchemy 库规则', () => {
   it('只认模型类：枚举类、函数照常显示；模型类的赋值都并进卡片，不再单独成块', async () => {
     const list = await views(SNAPSHOT)
     expect(list.map(view => view.kind)).toEqual([
-      'comment',
       ...Array.from({ length: 9 }, () => 'import'),
       'function',
       'class',
@@ -159,7 +158,8 @@ describe('sqlAlchemy 库规则', () => {
     ].join('\n')
     const [, order] = await views(source)
     expect(propertyLines(properties(order)).slice(-3)).toEqual(['字段: 2 个', '  amount | 整数 |  | ', '  note | 长文本 |  | '])
-    expect(order.children.map(child => [child.kind, child.startLine])).toEqual([['comment', 9], ['function', 10]])
+    expect(order.children.map(child => [child.kind, child.startLine])).toEqual([['function', 9]])
+    expect(commentText(order.children[0])).toBe('算税')
     expect([order.startLine, order.endLine]).toEqual([3, 13])
     expect(replaceLines(source, order.startLine, order.endLine, order.code)).toBe(source)
     expect(replaceLines(source, order.startLine, order.endLine, order.code.replace('// 10', '// 8'))).toBe(source.replace('// 10', '// 8'))
diff --git a/vscode/src/codeReader/rules/sqlalchemy.ts b/vscode/src/codeReader/rules/sqlalchemy.ts
index 30c227a..ea9eaac 100644
--- a/vscode/src/codeReader/rules/sqlalchemy.ts
+++ b/vscode/src/codeReader/rules/sqlalchemy.ts
@@ -1,6 +1,5 @@
 import type { ClassBlock, CodeBlock, Inline, KindIconName, LibraryRule, Node, PropertyItem, PropertyRow, RuleCard, RuleContext, ThemeColor, TokenRole } from '../contract'
 import type { Call } from './pythonTree'
-import { withLeadingComments } from './children'
 import { aliasesOf, callOf, canonicalName, genericOf, lastName, stringValue, syntaxChildren, unwrapType } from './pythonTree'
 import { hint, joined, name, plain, range, word } from './segments'
 
@@ -439,7 +438,7 @@ function tableBlock(block: ClassBlock, model: Model, env: Env): RuleCard {
     badge: { label: words.kind, color: TABLE_COLOR, icon: TABLE_ICON },
     rows,
     ...(facts.name && { defines: range(facts.name) }),
-    absorbs: withLeadingComments(block.children, members.filter((member): member is Member => member !== undefined).map(member => member.block)),
+    absorbs: members.filter((member): member is Member => member !== undefined).map(member => member.block),
   }
 }
 
diff --git a/vscode/src/codeReader/rules/sqlx.ts b/vscode/src/codeReader/rules/sqlx.ts
index d01c5e6..ebbd566 100644
--- a/vscode/src/codeReader/rules/sqlx.ts
+++ b/vscode/src/codeReader/rules/sqlx.ts
@@ -1,5 +1,5 @@
-import type { CodeBlock, Inline, KindBadge, LibraryRule, Node, PropertyRow, RuleCard, RuleContext, ThemeColor } from '../contract'
-import { docSummary, macroInvocation, named, oneLine, stringContent } from './rustTree'
+import type { Inline, KindBadge, LibraryRule, Node, PropertyRow, RuleCard, ThemeColor } from '../contract'
+import { macroInvocation, named, oneLine, stringContent } from './rustTree'
 
 /** 查询卡用字符串那种橙。 */
 const COLOR: ThemeColor = { dark: '#ce9178', light: '#a31515' }
@@ -7,7 +7,7 @@ const BADGE: KindBadge = { label: '查询', color: COLOR, icon: 'database' }
 const MACROS = new Set(['query', 'query_as', 'query_scalar'])
 
 /**
- * sqlx::query! / query_as! 这类宏。一句说明、等宽 SQL、参数、返回类型。
+ * sqlx::query! / query_as! 这类宏。等宽 SQL、参数、返回类型；前面的注释同别的块，是卡片的「注释」一行。
  * 文件里导入了 sqlx 才启用。
  */
 export const sqlxRule: LibraryRule = {
@@ -15,16 +15,14 @@ export const sqlxRule: LibraryRule = {
   label: 'sqlx 查询',
   languageIds: ['rust'],
   libraries: ['sqlx'],
-  claim: (block, context) => {
-    if (block.kind === 'comment')
-      return nextQuery(block.node) ? { omit: true } : undefined
+  claim: (block) => {
     const macro = block.kind === 'statement' ? findQuery(block.node) : undefined
-    return macro ? card(block, macro, context) : undefined
+    return macro ? card(macro) : undefined
   },
   attributeNames: () => ({ attributes: {}, values: { kind: { 'sqlx.query': '查询' } } }),
 }
 
-function card(block: CodeBlock, macro: Node, context: RuleContext): RuleCard {
+function card(macro: Node): RuleCard {
   const call = macroInvocation(macro)
   const args = call?.args ?? []
   const typed = call?.name.split('::').pop() !== 'query'
@@ -32,9 +30,7 @@ function card(block: CodeBlock, macro: Node, context: RuleContext): RuleCard {
   const sql = stringContent(sqlNode) ?? ''
   const params = args.slice(typed ? 2 : 1)
   const returned = typed ? args[0] : undefined
-  const note = precedingNote(block.node, context)
   const rows: PropertyRow[] = [
-    ...(note ? [{ label: '说明', value: { markdown: note } }] : []),
     { label: 'SQL', value: [{ text: sql, role: 'string', ...(sqlNode && { offset: sqlNode.startIndex }) }] },
     ...(params.length > 0
       ? [{ label: '参数', value: [{ text: params.map((param, index) => `$${index + 1} = ${oneLine(param.text)}`).join('、'), role: 'plain' as const }] }]
@@ -58,22 +54,6 @@ function findQuery(node: Node): Node | undefined {
   return undefined
 }
 
-function nextQuery(comment: Node): Node | undefined {
-  let next = comment.nextNamedSibling
-  while (next?.type === 'attribute_item')
-    next = next.nextNamedSibling
-  return next ? findQuery(next) : undefined
-}
-
-function precedingNote(node: Node, context: RuleContext): string | undefined {
-  let prev = node.previousNamedSibling
-  while (prev?.type === 'attribute_item')
-    prev = prev.previousNamedSibling
-  if (!prev || (prev.type !== 'line_comment' && prev.type !== 'block_comment'))
-    return undefined
-  return docSummary(context.doc(prev))
-}
-
 function hint(text: string): Inline {
   return { text, role: 'hint' }
 }
diff --git a/vscode/src/codeReader/testSupport.ts b/vscode/src/codeReader/testSupport.ts
index bb09f5b..4245d8d 100644
--- a/vscode/src/codeReader/testSupport.ts
+++ b/vscode/src/codeReader/testSupport.ts
@@ -30,14 +30,18 @@ export async function withBlocks<T>(adapter: LanguageAdapter, languageId: string
   }
 }
 
-/** 和原型 CODE_TREE 同样的写法：at 是 1 起的行号（单行，或 [起, 止]）。 */
-export interface Outline { at: number | [number, number], kind: BlockKind, kids?: Outline[] }
+/** 和原型 CODE_TREE 同样的写法：at 是 1 起的行号（单行，或 [起, 止]）；notes 是挂在这块上的各段注释（BlockShape.comments）在哪。 */
+export interface Outline { at: number | [number, number], kind: BlockKind, notes?: Outline['at'][], kids?: Outline[] }
+
+function rowsAt({ startRow, endRow }: { startRow: number, endRow: number }): Outline['at'] {
+  return startRow === endRow ? startRow + 1 : [startRow + 1, endRow + 1]
+}
 
 export function outline(blocks: CodeBlock[]): Outline[] {
   return blocks.map((block) => {
-    const from = block.header.startRow + 1
-    const to = block.header.endRow + 1
-    const item: Outline = { at: from === to ? from : [from, to], kind: block.kind }
+    const item: Outline = { at: rowsAt(block.header), kind: block.kind }
+    if (block.comments)
+      item.notes = block.comments.map(comment => rowsAt(comment.header))
     if (block.children.length > 0)
       item.kids = outline(block.children)
     return item
@@ -91,7 +95,7 @@ export function tableLines(table: PreviewTable | undefined): string[] {
 }
 
 /**
- * 视图数据写成文字（整份源码读出来的样子）：一行译文的块是「种类 行号: 译文」，属性表块是「种类 行号」下面每行「属性: 值」，
+ * 视图数据写成文字（整份源码读出来的样子）：一行译文的块是「种类 行号: 译文」（下面的「注释」一行写成「注释: 第一行」），属性表块是「种类 行号」下面每行「属性: 值」，
  * 子块比上一层多缩进两格；Markdown 只取第一行。表（属性行展开的、译文下面的、格子里套的）每行比上一层多缩进，
  * 格子用 | 隔开，格子里的换行写成 ⏎。
  */
@@ -105,11 +109,23 @@ export function viewLines(blocks: readonly BlockView[], indent = ''): string[] {
   return blocks.flatMap((block) => {
     const head = 'properties' in block
       ? [`${indent}${block.kind} ${block.startLine + 1}`, ...block.properties.flatMap(row => [`${indent}  ${row.label}: ${value(row.value)}`, ...items(row.items, `${indent}    `)])]
-      : [`${indent}${block.kind} ${block.startLine + 1}: ${value(block.translation)}`, ...items(block.table?.items, `${indent}    `)]
+      : [
+          `${indent}${block.kind} ${block.startLine + 1}: ${value(block.translation)}`,
+          ...items(block.table?.items, `${indent}    `),
+          ...(block.rows ?? []).map(row => `${indent}  ${row.label}: ${value(row.value)}`),
+        ]
     return [...head, ...viewLines(block.children, `${indent}  `)]
   })
 }
 
+/** 卡片上「注释」一行的 Markdown 原文（BlockView.commentRow）；没有就是 undefined。 */
+export function commentText(view: BlockView | undefined): string | undefined {
+  if (!view || view.commentRow === undefined)
+    return undefined
+  const row = 'properties' in view ? view.properties[view.commentRow] : view.rows?.[view.commentRow]
+  return row && 'markdown' in row.value ? row.value.markdown : undefined
+}
+
 /** 语法树节点换成它的源码，没填的可选字段去掉。 */
 export function nodesToText(value: unknown): unknown {
   if (value instanceof Node)
diff --git a/vscode/src/codeReader/translators/bashZh.test.ts b/vscode/src/codeReader/translators/bashZh.test.ts
index 4cbe40b..ac1450d 100644
--- a/vscode/src/codeReader/translators/bashZh.test.ts
+++ b/vscode/src/codeReader/translators/bashZh.test.ts
@@ -27,9 +27,9 @@ const FETCH_READING = [
   'interpreter 1',
   '  解释器: bash',
   '  怎么找: 按 PATH 去找（/usr/bin/env bash）',
-  'comment 2: 下载执行器自带的 git 与 python, 放到 src-tauri/resources/runtime/<target>/{git,python}。',
-  'options 14',
+  'options 2',
   '  出错就停: 是　-e',
+  '  注释: 下载执行器自带的 git 与 python, 放到 src-tauri/resources/runtime/<target>/{git,python}。',
   '  用到没设的变量就报错: 是　-u',
   '  管道里任一步失败都算失败: 是　-o pipefail',
   'variable 16',
@@ -101,41 +101,41 @@ const FETCH_READING = [
   'case 68: 按 git_pkg 分情况',
   '    以 .zip 结尾 | 解压 zip git_pkg 到 dest/git（不打印过程）',
   '    其他 | 解压 tar.gz git_pkg 到 dest/git',
-  'comment 72: python-build-standalone 的包里顶层目录就叫 python',
-  'command 73: 解压 tar.gz py_pkg 到 dest',
-  'comment 75: ── 去掉 Git Credential Manager ──────────────────────────────────────────────',
-  'case 78: 按 target 分情况',
+  'command 72: 解压 tar.gz py_pkg 到 dest',
+  '  注释: python-build-standalone 的包里顶层目录就叫 python',
+  'case 75: 按 target 分情况',
+  '  注释: ── 去掉 Git Credential Manager ──────────────────────────────────────────────',
   '  case 79: 情况：以 -apple-darwin 结尾',
   '    variable 80',
   '      名称: gc',
   '      初始值: dest/git/libexec/git-core',
   '    command 81: 删除 gc/git-credential-manager*、gc/*.dll、gc/*.dylib、gc/createdump、gc/NOTICE、gc/uninstall.sh（连同里面的东西、不提示）',
-  '    comment 83: .NET 的各语言资源目录; git 自己的子目录只有 mergetools',
-  '    command 84: 找出 gc 下一层的目录，除了 mergetools，逐个 删除（连同里面的东西、不提示）',
+  '    command 83: 找出 gc 下一层的目录，除了 mergetools，逐个 删除（连同里面的东西、不提示）',
+  '      注释: .NET 的各语言资源目录; git 自己的子目录只有 mergetools',
   '  case 86: 情况：以 -windows-msvc 结尾',
-  '    comment 87: mingw64/bin 里 git 自己依赖的 DLL 都以 lib 开头 (外加 zlib1.dll), 其余 DLL 都属于 GCM;',
-  '    variable 89',
+  '    variable 87',
   '      名称: mb',
+  '      注释: mingw64/bin 里 git 自己依赖的 DLL 都以 lib 开头 (外加 zlib1.dll), 其余 DLL 都属于 GCM;',
   '      初始值: dest/git/mingw64/bin',
   '    command 90: 删除 mb/git-credential-manager.exe*、mb/libHarfBuzzSharp.dll、mb/libSkiaSharp.dll（不提示）',
   '    command 91: 找出 mb 这一层的 *.dll，除了 lib* 和 zlib1.dll，逐个 删除',
-  'comment 95: Windows 版 python 只有 python.exe; 平台脚本按 python3 这个名字再调起它时 (它的目录前置在',
-  'if 98: 如果 target 以 -windows-msvc 结尾',
+  'if 95: 如果 target 以 -windows-msvc 结尾',
+  '  注释: Windows 版 python 只有 python.exe; 平台脚本按 python3 这个名字再调起它时 (它的目录前置在',
   '  command 99: 复制 dest/python/python.exe 到 dest/python/python3.exe',
-  'comment 102: ── 去掉符号链接 ─────────────────────────────────────────────────────────────',
-  'if 105: 如果 target 以 -apple-darwin 结尾',
+  'if 102: 如果 target 以 -apple-darwin 结尾',
+  '  注释: ── 去掉符号链接 ─────────────────────────────────────────────────────────────',
   '  variable 106',
   '    名称: gc',
   '    初始值: dest/git/libexec/git-core',
-  '  comment 107: 内建命令的短横线别名 (git-add -> git …): git 自己调内建命令不走它们。同 git 构建选项',
-  '  loop 109: 遍历 gc/git-* 匹配到的每个文件 f',
+  '  loop 107: 遍历 gc/git-* 匹配到的每个文件 f',
+  '    注释: 内建命令的短横线别名 (git-add -> git …): git 自己调内建命令不走它们。同 git 构建选项',
   '    if 110: 如果不是 〔f 是符号链接 并且 〔读出 f 指向的路径〕 等于 git〕，跳过这一个',
   '    case 111: 按 〔取文件名 f〕 分情况',
   '        git-upload-pack 或 git-receive-pack 或 git-upload-archive | 什么也不做',
   '        其他 | 删除 f',
-  '  comment 116: python 只留 bin/python3 这一个入口 (执行器按它找), 版本号命名的本体挪过来',
-  '  variable 117',
+  '  variable 116',
   '    名称: pybin',
+  '    注释: python 只留 bin/python3 这一个入口 (执行器按它找), 版本号命名的本体挪过来',
   '    初始值: dest/python/bin',
   '  variable 118',
   '    名称: real',
@@ -143,8 +143,8 @@ const FETCH_READING = [
   '  command 119: 删除 pybin/python3',
   '  command 120: 改名 pybin/real → pybin/python3',
   '  command 121: 找出 dest/python 下面所有符号链接，逐个 删除',
-  '  comment 122: 剩下的 (传输程序、git-remote-https 之类) 换成实体文件',
-  '  pipeline 123: 找出 dest 下面所有符号链接 → 逐行读进 link',
+  '  pipeline 122: 找出 dest 下面所有符号链接 → 逐行读进 link',
+  '    注释: 剩下的 (传输程序、git-remote-https 之类) 换成实体文件',
   '    command 124: 复制 link 指向的实体文件 到 link.tmp',
   '    command 125: 改名 link.tmp → link',
   'command 129: 打印 "自带运行时就绪: dest"（打印到错误输出）',
diff --git a/vscode/src/codeReader/translators/dockerfileZh.test.ts b/vscode/src/codeReader/translators/dockerfileZh.test.ts
index b9dcd3a..07b9722 100644
--- a/vscode/src/codeReader/translators/dockerfileZh.test.ts
+++ b/vscode/src/codeReader/translators/dockerfileZh.test.ts
@@ -54,9 +54,9 @@ const NEXT_READING = [
   '  variable 14',
   '    环境变量: NEXT_TELEMETRY_DISABLED',
   '    值: 1',
-  '  comment 15: 部署 ID 烙进本次构建: Next 据此给静态资源加 ?dpl=、页内跳转时比对版本;',
-  '  variable 17',
+  '  variable 15',
   '    构建参数: DEPLOYMENT_ID',
+  '    注释: 部署 ID 烙进本次构建: Next 据此给静态资源加 ?dpl=、页内跳转时比对版本;',
   '    默认值: 没写，构建时传',
   '  variable 18',
   '    环境变量: NEXT_DEPLOYMENT_ID',
@@ -84,8 +84,8 @@ const NEXT_READING = [
   '  copy 33: 复制（2 条连着写，属主都是 nextjs:nodejs）',
   '      阶段 builder | /app/.next/standalone | ./',
   '      阶段 builder | /app/.next/static | ./.next/static',
-  '  comment 35: standalone 输出不含 public/, 必须显式拷贝 (字体等静态资源)',
-  '  copy 36: 从阶段 builder 复制 /app/public → ./public（属主 nextjs:nodejs）',
+  '  copy 35: 从阶段 builder 复制 /app/public → ./public（属主 nextjs:nodejs）',
+  '    注释: standalone 输出不含 public/, 必须显式拷贝 (字体等静态资源)',
   '  setting 38: 之后以 nextjs 身份运行',
   '  setting 39: 开放端口 3000',
   '  start 41',
@@ -102,8 +102,8 @@ const BACKEND_READING = [
   '  label 6: 标签',
   '      maintainer | Cruldra',
   '      description | luffy-agent-platform - 统一 Backend 镜像 (API/Worker/Beat/Flower)',
-  '  comment 9: git: deployment 模块创建 bare repo；postgresql-client: alembic / psql 运维；curl: healthcheck',
-  '  run 13: 执行（10 条命令，一条失败就停）',
+  '  run 9: 执行（10 条命令，一条失败就停）',
+  '    注释: git: deployment 模块创建 bare repo；postgresql-client: alembic / psql 运维；curl: healthcheck',
   '    command 13: 更新软件包列表',
   '    command 14: 安装 ca-certificates、curl、gnupg、postgresql-client、git（不装推荐的包、不用确认）',
   '    command 16: 建目录 /usr/share/keyrings',
@@ -114,16 +114,16 @@ const BACKEND_READING = [
   '    command 23: 安装 postgresql-16-repack（不装推荐的包、不用确认）',
   '    command 24: 打印 pg_repack 的版本',
   '    command 25: 删除 /var/lib/apt/lists/*（连同里面的东西、不提示）',
-  '  comment 27: Node.js：agent MCP 节点 (如 context7) 用 stdio + npx 拉子进程, api 容器必须有 npx。',
-  '  copy 32: 复制（2 条连着写）',
+  '  copy 27: 复制（2 条连着写）',
   '      镜像 node:22-slim | /usr/local/bin/node | /usr/local/bin/node',
   '      镜像 node:22-slim | /usr/local/lib/node_modules | /usr/local/lib/node_modules',
+  '    注释: Node.js：agent MCP 节点 (如 context7) 用 stdio + npx 拉子进程, api 容器必须有 npx。',
   '  run 34: 执行',
   '    command 34: 建符号链接 /usr/local/bin/npm → /usr/local/lib/node_modules/npm/bin/npm-cli.js（已有就替换）',
   '    command 35: 建符号链接 /usr/local/bin/npx → /usr/local/lib/node_modules/npm/bin/npx-cli.js（已有就替换）',
   '  copy 37: 从镜像 ghcr.io/astral-sh/uv:latest 复制 /uv、/uvx → /bin/',
-  '  comment 39: appuser 先建、/app /lib 先归属：.venv 由 appuser 直接创建，末尾无需 chown -R',
-  '  run 42: 执行（3 条命令，一条失败就停）',
+  '  run 39: 执行（3 条命令，一条失败就停）',
+  '    注释: appuser 先建、/app /lib 先归属：.venv 由 appuser 直接创建，末尾无需 chown -R',
   '    command 42: 新建用户 appuser（建主目录、不能登录）',
   '    command 43: 建目录 /app、/lib（连同上级目录）',
   '    command 44: 把 /app、/lib 的属主改成 appuser:appuser',
@@ -132,8 +132,7 @@ const BACKEND_READING = [
   '    环境变量: UV_CACHE_DIR',
   '    值: /home/appuser/.cache/uv',
   '  setting 48: 工作目录 /app',
-  '  comment 50: ── 依赖层（仅随 pyproject/uv.lock 变化重建）───────────────────────────',
-  '  copy 54: 复制（12 条连着写，属主都是 appuser:appuser）',
+  '  copy 50: 复制（12 条连着写，属主都是 appuser:appuser）',
   '      backend/pyproject.toml、backend/uv.lock | ./',
   '      lib/agent-dsl/pyproject.toml | /lib/agent-dsl/',
   '      lib/agent-compiler-deepagents/pyproject.toml | /lib/agent-compiler-deepagents/',
@@ -146,39 +145,40 @@ const BACKEND_READING = [
   '      lib/code-publish-compose-runner/pyproject.toml | /lib/code-publish-compose-runner/',
   '      lib/luffy-billing-sdk/pyproject.toml | /lib/luffy-billing-sdk/',
   '      lib/luffy-observability/pyproject.toml | /lib/luffy-observability/',
-  '  comment 67: 三方依赖先装；本项目与 lib editable 包此时无源码，跳过安装留给第二次 sync',
-  '  run 68: uv 按 lock 同步依赖 · 4 个选项',
+  '    注释: ── 依赖层（仅随 pyproject/uv.lock 变化重建）───────────────────────────',
+  '  run 67: uv 按 lock 同步依赖 · 4 个选项',
   '      --frozen | 严格按 lock 文件，不改它',
   '      --no-dev | 不装开发依赖',
   '      --no-install-project | 不装本项目',
   '      --no-install-package × 11 | 不装这些包：agent-dsl、agent-compiler-deepagents、vendor-tools、code-sandbox-core、code-sandbox-daytona、code-sandbox-e2b、code-sandbox-local、code-publish-core、code-publish-compose-runner、luffy-billing-sdk、luffy-observability',
-  '  comment 81: ── 源码层（每次代码变更只重建这里往下）────────────────────────────────',
-  '  copy 82: 复制 lib → /lib（属主 appuser:appuser）',
-  '  comment 83: agent 定义 (vendor/agents/*/agent.yaml + nodes/*.py) 与代码是同一个版本, 必须随镜像原子切换;',
-  '  copy 85: 复制（5 条连着写，属主都是 appuser:appuser）',
+  '    注释: 三方依赖先装；本项目与 lib editable 包此时无源码，跳过安装留给第二次 sync',
+  '  copy 81: 复制 lib → /lib（属主 appuser:appuser）',
+  '    注释: ── 源码层（每次代码变更只重建这里往下）────────────────────────────────',
+  '  copy 83: 复制（5 条连着写，属主都是 appuser:appuser）',
   '      vendor | /vendor',
   '      backend/src/ | ./src/',
   '      backend/alembic/ | ./alembic/',
   '      backend/alembic.ini | ./',
   '      backend/scripts/ | ./scripts/',
-  '  comment 91: 补装本项目 + lib editable 包（三方依赖已就位，秒级）',
-  '  run 92: uv 按 lock 同步依赖（严格按 lock 文件，不改它、不装开发依赖）',
-  '  comment 94: 远程调试支持：装入 uv 创建的 venv，按需通过 DEBUGPY_ENABLE=1 开启。',
-  '  run 96: uv 安装 debugpy',
+  '    注释: agent 定义 (vendor/agents/*/agent.yaml + nodes/*.py) 与代码是同一个版本, 必须随镜像原子切换;',
+  '  run 91: uv 按 lock 同步依赖（严格按 lock 文件，不改它、不装开发依赖）',
+  '    注释: 补装本项目 + lib editable 包（三方依赖已就位，秒级）',
+  '  run 94: uv 安装 debugpy',
+  '    注释: 远程调试支持：装入 uv 创建的 venv，按需通过 DEBUGPY_ENABLE=1 开启。',
   '  variable 98',
   '    环境变量: UV_NO_SYNC',
   '    值: 1',
-  '  comment 100: 部署 ID (Jenkins IMAGE_TAG): /health 回显、日志定位后端出自哪次构建. 选择性发布时 api 与 client 镜像 tag 可不同, 客户端是否过期以 client 镜像 (浏览器包 vs BFF) 为准.',
-  '  variable 101',
+  '  variable 100',
   '    构建参数: DEPLOYMENT_ID',
+  '    注释: 部署 ID (Jenkins IMAGE_TAG): /health 回显、日志定位后端出自哪次构建. 选择性发布时 api 与 client 镜像 tag 可不同, 客户端是否过期以 client 镜像 (浏览器包 vs BFF) 为准.',
   '    默认值: 没写，构建时传',
   '  variable 102',
   '    环境变量: DEPLOYMENT_ID',
   '    值: DEPLOYMENT_ID（构建参数）',
   '  setting 104: 开放端口 8000',
-  '  comment 106: 默认 CMD 走 api，celery worker/beat/flower 由 compose 覆盖 command',
-  '  health 107',
+  '  health 106',
   '    间隔: 30 秒',
+  '    注释: 默认 CMD 走 api，celery worker/beat/flower 由 compose 覆盖 command',
   '    超时: 5 秒',
   '    启动后宽限: 10 秒',
   '    失败几次算不健康: 3 次',
diff --git a/vscode/src/codeReader/translators/zhTemplate.test.ts b/vscode/src/codeReader/translators/zhTemplate.test.ts
index a6f056c..a435803 100644
--- a/vscode/src/codeReader/translators/zhTemplate.test.ts
+++ b/vscode/src/codeReader/translators/zhTemplate.test.ts
@@ -15,21 +15,22 @@ const py = createPythonAdapter(WASM_DIR)
 interface Translated { kind: string, segments: Inline[], markdown?: string, table?: PreviewTable }
 
 /**
- * 一行译文块、注释块的译文，按 header 起始行（1 起）索引；同一行有多块时取外层那块。属性表块见 describeAll。
+ * 一行译文块、注释块（单独成块的、挂在块上的）的译文，按 header 起始行（1 起）索引；同一行有多块时取外层那块。属性表块见 describeAll。
  * calleeKind 同 SourceDocument.calleeKind（调用的名字定义成哪种块），不给就是宿主不查。
  */
 function translateAll(adapter: LanguageAdapter, languageId: string, translator: Translator, source: string, calleeKind?: SourceDocument['calleeKind']): Promise<Map<number, Translated>> {
   return withBlocks(adapter, languageId, source, (blocks) => {
     const byLine = new Map<number, Translated>()
-    walk(blocks, (block) => {
-      const line = block.header.startRow + 1
-      if (byLine.has(line) || 'facts' in block)
+    // 挂在块上的注释（BlockShape.comments）同样按它自己的起始行翻
+    walk(blocks, block => [...(block.comments ?? []), block].forEach((item) => {
+      const line = item.header.startRow + 1
+      if (byLine.has(line) || 'facts' in item)
         return
-      const { text: translation, table } = translator.translate(block, { source, language: adapter, markers: [], ...(calleeKind && { calleeKind }) })
+      const { text: translation, table } = translator.translate(item, { source, language: adapter, markers: [], ...(calleeKind && { calleeKind }) })
       byLine.set(line, 'markdown' in translation
-        ? { kind: block.kind, segments: [], markdown: translation.markdown }
-        : { kind: block.kind, segments: translation, ...(table && { table }) })
-    })
+        ? { kind: item.kind, segments: [], markdown: translation.markdown }
+        : { kind: item.kind, segments: translation, ...(table && { table }) })
+    }))
     return byLine
   })
 }
diff --git a/vscode/webview-ui/src/codeReader/BlockTools.test.tsx b/vscode/webview-ui/src/codeReader/BlockTools.test.tsx
index 7397336..976615f 100644
--- a/vscode/webview-ui/src/codeReader/BlockTools.test.tsx
+++ b/vscode/webview-ui/src/codeReader/BlockTools.test.tsx
@@ -1,14 +1,14 @@
 import { renderToStaticMarkup } from 'react-dom/server'
 import { describe, expect, it } from 'vitest'
-import { BlockTools } from './BlockTools'
+import { BlockTools, RewriteButton } from './BlockTools'
 
-function render(editing: boolean, ask?: { asking: boolean }, rewrite?: { rewriting: boolean }): string {
+function render(editing: boolean, ask?: { asking: boolean }, rewrite?: { rewriting: boolean, fresh?: boolean }): string {
   return renderToStaticMarkup(
     <BlockTools
       editing={editing}
       onToggleEdit={() => {}}
       {...(ask && { asking: ask.asking, onToggleAsk: () => {} })}
-      {...(rewrite && { rewriting: rewrite.rewriting, onRewrite: () => {} })}
+      {...(rewrite && { rewrite: { rewriting: rewrite.rewriting, fresh: rewrite.fresh ?? false, onRewrite: () => {} } })}
     />,
   )
 }
@@ -54,4 +54,12 @@ describe('块右上角的图标按钮', () => {
     expect(busy).toContain('aria-busy="true"')
     expect(busy).not.toContain('cr-qa-spin')
   })
+
+  it('块还没有注释时按钮叫「按注释规范写注释」；「注释」一行上的按钮是同一个，只有图标', () => {
+    const fresh = render(false, undefined, { rewriting: false, fresh: true })
+    expect(fresh).toContain('data-tooltip="按注释规范写注释" aria-label="按注释规范写注释"')
+    const onRow = renderToStaticMarkup(<RewriteButton tool={{ rewriting: false, fresh: false, onRewrite: () => {} }} />)
+    expect(onRow).toMatch(/^<button[^>]*data-tooltip="按注释规范重写" aria-label="按注释规范重写"[^>]*><svg/)
+    expect(visibleText(onRow)).toBe('')
+  })
 })
diff --git a/vscode/webview-ui/src/codeReader/BlockTools.tsx b/vscode/webview-ui/src/codeReader/BlockTools.tsx
index 3e6e82e..0be5aeb 100644
--- a/vscode/webview-ui/src/codeReader/BlockTools.tsx
+++ b/vscode/webview-ui/src/codeReader/BlockTools.tsx
@@ -1,41 +1,55 @@
 import type { ReactElement } from 'react'
 import { Eye, MessageSquareText, Pencil, Sparkles } from 'lucide-react'
 
+/** 「重写注释」按钮的样子和动作：fresh 是块还没有注释、点了新写一段；正在重写时不能再点。 */
+export interface RewriteTool {
+  fresh: boolean
+  rewriting: boolean
+  onRewrite: () => void
+}
+
+/**
+ * 「按注释规范重写」：用写注释的技能重写这块代码的注释并写回文件（块还没有注释时是「按注释规范写注释」，新写一段）；正在重写时不能再点。
+ * 只有图标（注释），名字在悬停提示和 aria-label 里。卡片有「注释」一行时画在那一行上，没有时排在右上角那排按钮里。
+ */
+export function RewriteButton({ tool }: { tool: RewriteTool }): ReactElement {
+  const label = tool.fresh ? '按注释规范写注释' : '按注释规范重写'
+  return (
+    <button
+      type="button"
+      className="cr-tool flex h-5 w-6 shrink-0 items-center justify-center rounded"
+      data-tooltip={label}
+      aria-label={label}
+      aria-busy={tool.rewriting}
+      disabled={tool.rewriting}
+      onClick={tool.onRewrite}
+    >
+      <MessageSquareText size={14} strokeWidth={1.8} aria-hidden />
+    </button>
+  )
+}
+
 /**
  * 块右上角的一排图标按钮（普通块、属性表、库规则的卡片共用）：只放图标，名字写在悬停提示（data-tooltip）和读屏用的 aria-label 里。
- * 「按注释规范重写」：只给注释块。点了用写注释的技能重写这一段并写回文件；正在重写时不能再点。图标是注释。
+ * 「按注释规范重写」（见 RewriteButton）：卡片没有「注释」一行时排在这里。
  * 「问 AI」：点开 / 收起块下面的问答区，展开时带按下的底色。
  * 「编辑 / 预览」切换：预览时是铅笔「编辑」，编辑时是眼睛「预览」、带按下的底色。
  */
-export function BlockTools({ editing, onToggleEdit, asking, onToggleAsk, rewriting, onRewrite }: {
+export function BlockTools({ editing, onToggleEdit, asking, onToggleAsk, rewrite }: {
   editing: boolean
   onToggleEdit: () => void
   /** 块下面的问答区展开着 */
   asking?: boolean
   /** 没给就不显示「问 AI」（文件不在工作区文件夹里，问答没地方存） */
   onToggleAsk?: () => void
-  /** 这段注释正在重写 */
-  rewriting?: boolean
-  /** 没给就不显示「按注释规范重写」（不是注释块） */
-  onRewrite?: () => void
+  /** 没给就不显示「按注释规范重写」（不能写注释，或按钮画在「注释」一行上） */
+  rewrite?: RewriteTool
 }): ReactElement {
   const label = editing ? '预览' : '编辑'
   const Icon = editing ? Eye : Pencil
   return (
     <div className="flex h-5 shrink-0 items-center gap-0.5" role="group" aria-label="块操作">
-      {onRewrite && (
-        <button
-          type="button"
-          className="cr-tool flex h-5 w-6 items-center justify-center rounded"
-          data-tooltip="按注释规范重写"
-          aria-label="按注释规范重写"
-          aria-busy={rewriting === true}
-          disabled={rewriting === true}
-          onClick={onRewrite}
-        >
-          <MessageSquareText size={14} strokeWidth={1.8} aria-hidden />
-        </button>
-      )}
+      {rewrite && <RewriteButton tool={rewrite} />}
       {onToggleAsk && (
         <button
           type="button"
diff --git a/vscode/webview-ui/src/codeReader/BlockTree.test.tsx b/vscode/webview-ui/src/codeReader/BlockTree.test.tsx
index 3d791fb..a8092c6 100644
--- a/vscode/webview-ui/src/codeReader/BlockTree.test.tsx
+++ b/vscode/webview-ui/src/codeReader/BlockTree.test.tsx
@@ -32,7 +32,7 @@ function view(id: string, kind: string, text: string, extra: Partial<BlockView>
   } as BlockView
 }
 
-/** 一张卡片：第 1 行的两个子行各挂一张子卡片，后面还有一个留下的注释块。 */
+/** 一张卡片：第 1 行的两个子行各挂一张子卡片，后面还有一块留下的语句。 */
 const CARD: BlockView = {
   ...view('0', 'demo.card', ''),
   badge: BADGE,
@@ -46,13 +46,12 @@ const CARD: BlockView = {
   children: [
     view('0.0', 'demo.method', '启动服务', { slot: { row: 1, item: 0 }, badge: { ...BADGE, label: '方法', icon: 'square-function' } }),
     view('0.1', 'demo.method', '停止服务', { slot: { row: 1, item: 1 }, badge: { ...BADGE, label: '方法', icon: 'square-function' } }),
-    view('0.2', 'comment', '留下的注释'),
+    view('0.2', 'statement', '留下的语句'),
   ],
 }
 
-function render(folds: Record<string, boolean>): string {
-  const collapsed = collapsedIds([CARD], folds)
-  const tree: BlockTreeState = {
+function state(collapsed: ReadonlySet<string>): BlockTreeState {
+  return {
     edit: {
       version: 1,
       editing: new Set(),
@@ -72,7 +71,10 @@ function render(folds: Record<string, boolean>): string {
     onSetFolds: () => {},
     onOpenRun: () => {},
   }
-  return renderToStaticMarkup(<BlockLevel blocks={[CARD]} tree={tree} />)
+}
+
+function render(folds: Record<string, boolean>): string {
+  return renderToStaticMarkup(<BlockLevel blocks={[CARD]} tree={state(collapsedIds([CARD], folds))} />)
 }
 
 describe('挂在卡片子行上的子块', () => {
@@ -80,7 +82,7 @@ describe('挂在卡片子行上的子块', () => {
     const html = render({})
     expect(html).not.toContain('启动服务')
     expect(html).not.toContain('停止服务')
-    expect(html).not.toContain('留下的注释')
+    expect(html).not.toContain('留下的语句')
     expect(html).toContain('<button type="button" class="cr-item-toggle" aria-expanded="false" aria-label="展开start">')
   })
 
@@ -90,7 +92,7 @@ describe('挂在卡片子行上的子块', () => {
     expect(html).not.toContain('停止服务')
     expect(html).toContain('data-open="" data-badge="" style="--kind-dark:#61dafb;--kind-light:#0a7ea4"')
     expect(html).toContain('aria-label="收起"')
-    expect(html).toContain('留下的注释')
+    expect(html).toContain('留下的语句')
     // 子卡片画在「方法」那一行后面
     expect(html.indexOf('启动服务')).toBeGreaterThan(html.indexOf('方法</button>'))
   })
@@ -105,3 +107,33 @@ describe('挂在卡片子行上的子块', () => {
     expect(render({ '0.0': false, '0': false }).match(/data-owner="0"/g)).toHaveLength(2)
   })
 })
+
+describe('「注释」一行和「重写注释」按钮', () => {
+  const comment = { label: '注释', value: { markdown: '按名字找' } }
+  const html = (block: BlockView): string => renderToStaticMarkup(<BlockLevel blocks={[block]} tree={state(new Set())} />)
+  /** 「注释」那一行（cr-prop-row）里的 HTML */
+  const commentRowHtml = (markup: string): string => markup.split('cr-prop-row').find(part => part.includes('按名字找')) ?? ''
+
+  it('属性表卡片：「注释」一行照属性表画，按钮画在这一行上，右上角那排不再有', () => {
+    const card = view('1', 'function', '', {
+      properties: [{ label: '名称', value: [{ text: 'find', role: 'function' }] }, comment, { label: '异步', value: [{ text: '否', role: 'storage' }] }],
+      commentRow: 1,
+      commentTarget: { kind: 'replace', startLine: 0, endLine: 0 },
+    })
+    const markup = html(card)
+    expect(commentRowHtml(markup)).toContain('aria-label="按注释规范重写"')
+    expect(markup.match(/aria-label="按注释规范重写"/g)).toHaveLength(1)
+    expect(markup.indexOf('按名字找')).toBeLessThan(markup.indexOf('异步'))
+  })
+
+  it('一行译文的卡片：「注释」一行排在译文下面，按钮同样在这一行上', () => {
+    const markup = html(view('2', 'statement', 'save()', { rows: [comment], commentRow: 0, commentTarget: { kind: 'replace', startLine: 0, endLine: 0 } }))
+    expect(markup.indexOf('save()')).toBeLessThan(markup.indexOf('按名字找'))
+    expect(commentRowHtml(markup)).toContain('aria-label="按注释规范重写"')
+  })
+
+  it('还没有注释的块：按钮在右上角那排，叫「按注释规范写注释」；不能写注释的块没有按钮', () => {
+    expect(html(view('3', 'statement', 'save()', { commentTarget: { kind: 'insert', line: 0 } }))).toMatch(/role="group" aria-label="块操作"><button[^>]*aria-label="按注释规范写注释"/)
+    expect(html(view('4', 'statement', 'save()'))).not.toContain('按注释规范')
+  })
+})
diff --git a/vscode/webview-ui/src/codeReader/BlockTree.tsx b/vscode/webview-ui/src/codeReader/BlockTree.tsx
index f2e3233..23c5718 100644
--- a/vscode/webview-ui/src/codeReader/BlockTree.tsx
+++ b/vscode/webview-ui/src/codeReader/BlockTree.tsx
@@ -1,4 +1,5 @@
 import type { CSSProperties, ReactElement, ReactNode } from 'react'
+import type { RewriteTool } from './BlockTools'
 import type { DiffTree, FoldedRuns, PlacedRemoved } from './diffView'
 import type { GridSlots } from './PropertyGrid'
 import type { QaState } from './qa'
@@ -8,7 +9,7 @@ import type { BlockMarks, BlockView } from './types'
 import { ChevronDown, ChevronRight, ChevronsUpDown, EyeOff } from 'lucide-react'
 import { Fragment, useState } from 'react'
 import { AskThread, RewriteThread } from './AskThread'
-import { BlockTools } from './BlockTools'
+import { BlockTools, RewriteButton } from './BlockTools'
 import { CodeEditor } from './CodeEditor'
 import { DiffText } from './DiffText'
 import { removedTitle } from './diffView'
@@ -202,11 +203,13 @@ function BlockRewrite({ anchor, edit }: { anchor: string, edit: EditTree }): Rea
 
 /**
  * 预览状态的内容：函数、类、枚举、导入、常量、变量块和库规则的卡片是属性表，其余是一行译文；
- * 译文下面依次接着摊开实参的表（跨几行写的调用）、说明。标差异时 marks 是这块自己的内容改了哪些（页面上正是差异算的那一版才给）。
+ * 译文下面依次接着摊开实参的表（跨几行写的调用）、说明、几行属性（「注释」一行）。标差异时 marks 是这块自己的内容改了哪些（页面上正是差异算的那一版才给）。
+ * rewrite 是「重写注释」按钮，画在「注释」一行上（commentRow）；只读的块树（定义卡片浮窗）、删掉的块没有。
  */
-function BlockPreview({ block, tree, marks }: { block: BlockView, tree: BlockTreeState, marks?: BlockMarks }): ReactElement {
+function BlockPreview({ block, tree, marks, rewrite }: { block: BlockView, tree: BlockTreeState, marks?: BlockMarks, rewrite?: RewriteTool }): ReactElement {
+  const rowTools = rewrite && block.commentRow !== undefined ? new Map([[block.commentRow, <RewriteButton key="rewrite" tool={rewrite} />]]) : undefined
   if ('properties' in block)
-    return <PropertyGrid blockId={block.id} rows={block.properties} collapsed={tree.collapsed} onToggleFold={tree.onToggleFold} marks={marks?.rows} slots={cardSlots(block, tree)} />
+    return <PropertyGrid blockId={block.id} rows={block.properties} collapsed={tree.collapsed} onToggleFold={tree.onToggleFold} marks={marks?.rows} slots={cardSlots(block, tree)} rowTools={rowTools} />
   return (
     <>
       {marks?.translation ? <DiffText diff={marks.translation} /> : <TextPreview text={block.translation} />}
@@ -216,10 +219,26 @@ function BlockPreview({ block, tree, marks }: { block: BlockView, tree: BlockTre
         </div>
       )}
       {marks?.doc ? <DiffText diff={marks.doc} className="mt-0.5" /> : block.doc && <TextPreview text={block.doc} className="mt-0.5" />}
+      {block.rows && (
+        <div className="mt-[3px]">
+          <PropertyGrid blockId={block.id} rows={block.rows} collapsed={tree.collapsed} onToggleFold={tree.onToggleFold} marks={marks?.rows} rowTools={rowTools} />
+        </div>
+      )}
     </>
   )
 }
 
+/** 这块的「重写注释」按钮：能写注释（commentTarget）、页面上能改代码时才有。 */
+function rewriteTool(block: BlockView, edit: EditTree | undefined): RewriteTool | undefined {
+  if (!edit || !block.commentTarget)
+    return undefined
+  return {
+    fresh: block.commentTarget.kind === 'insert',
+    rewriting: edit.rewrites.get(block.anchor)?.status === 'running',
+    onRewrite: () => edit.onRewriteComment(block.anchor),
+  }
+}
+
 /**
  * 挂在卡片子行上的子块（BlockSlot）怎么画：一行下面展开着的几块画成一层块（同块树）；点那个子行的第一格展开它、
  * 同一行里别的收起，展开着的再点收起。卡片没有挂在子行上的子块时没有。
@@ -252,6 +271,7 @@ function BlockCard({ block, tree }: { block: BlockView, tree: BlockTreeState }):
   const hasChildren = toggled || hasShownChildren(block, tree)
   const Chevron = collapsed && !toggled ? ChevronRight : ChevronDown
   const change = tree.diff?.changes.get(block.id)
+  const rewrite = rewriteTool(block, edit)
   return (
     <div
       className="cr-block relative flex items-start gap-2.5 rounded-lg py-2 pr-2.5 pl-2"
@@ -287,7 +307,7 @@ function BlockCard({ block, tree }: { block: BlockView, tree: BlockTreeState }):
                 onExit={() => edit.onToggleEdit(block.id)}
               />
             )
-          : <BlockPreview block={block} tree={tree} marks={tree.diff?.current ? change?.marks : undefined} />}
+          : <BlockPreview block={block} tree={tree} marks={tree.diff?.current ? change?.marks : undefined} rewrite={rewrite} />}
       </div>
       {tree.temporary.has(block.id) && (
         <span className="cr-temporary flex h-5 shrink-0 items-center gap-1 rounded px-1.5 text-[11px] whitespace-nowrap">
@@ -301,8 +321,7 @@ function BlockCard({ block, tree }: { block: BlockView, tree: BlockTreeState }):
           onToggleEdit={() => edit.onToggleEdit(block.id)}
           asking={tree.qa?.state.open.includes(block.anchor)}
           onToggleAsk={tree.qa && (() => tree.qa?.onToggle(block.anchor))}
-          rewriting={edit.rewrites.get(block.anchor)?.status === 'running'}
-          onRewrite={block.commentStartLine !== undefined ? () => edit.onRewriteComment(block.anchor) : undefined}
+          {...(rewrite && block.commentRow === undefined && { rewrite })}
         />
       )}
     </div>
diff --git a/vscode/webview-ui/src/codeReader/PropertyGrid.tsx b/vscode/webview-ui/src/codeReader/PropertyGrid.tsx
index 70b0d6b..02a5025 100644
--- a/vscode/webview-ui/src/codeReader/PropertyGrid.tsx
+++ b/vscode/webview-ui/src/codeReader/PropertyGrid.tsx
@@ -252,7 +252,7 @@ export function PropertyTable({ parentId, columns, items, marks, toggles }: {
  * 给了列名的（输入参数、数据表的字段）排成表格，没给的排成列表。
  * 标差异时（marks）新加的行淡绿底、左边 +，删掉的行放回原来的位置、淡红底划掉、左边 −，值改了的按旧值 → 新值或逐词标。
  */
-export function PropertyGrid({ blockId, rows, collapsed, onToggleFold, marks, slots }: {
+export function PropertyGrid({ blockId, rows, collapsed, onToggleFold, marks, slots, rowTools }: {
   blockId: string
   rows: PropertyRow[]
   collapsed: ReadonlySet<string>
@@ -261,6 +261,8 @@ export function PropertyGrid({ blockId, rows, collapsed, onToggleFold, marks, sl
   marks?: RowsDiff
   /** 挂在这张属性表子行上的子块（库规则的卡片），见 GridSlots */
   slots?: GridSlots
+  /** 排在某一行值右边的按钮（「注释」一行的「重写注释」），按行的下标 */
+  rowTools?: ReadonlyMap<number, ReactNode>
 }): ReactElement {
   const removed = (after: number): ReactElement[] => removedAt(marks?.removed, after)
     .map(({ value, index }) => <RemovedRow key={`removed-${index}`} id={`${blockId}/x${index}`} row={value} />)
@@ -296,7 +298,14 @@ export function PropertyGrid({ blockId, rows, collapsed, onToggleFold, marks, sl
                     </button>
                   )
                 : <span className="cr-prop-label flex h-5 items-center">{row.label}</span>}
-              <RowValue row={row} mark={mark} />
+              {rowTools?.has(index)
+                ? (
+                    <div className="flex min-w-0 items-start gap-1">
+                      <div className="min-w-0 flex-1"><RowValue row={row} mark={mark} /></div>
+                      {rowTools.get(index)}
+                    </div>
+                  )
+                : <RowValue row={row} mark={mark} />}
             </div>
             {!folded && layout === 'table' && <PropertyTable parentId={id} columns={row.columns ?? []} items={row.items ?? []} marks={mark?.items} toggles={toggles} />}
             {!folded && layout === 'list' && <PropertyItems parentId={id} items={row.items ?? []} folding={{ collapsed, onToggleFold }} marks={mark?.items} />}
diff --git a/vscode/webview-ui/src/codeReader/types.ts b/vscode/webview-ui/src/codeReader/types.ts
index 385ddb2..a460cf3 100644
--- a/vscode/webview-ui/src/codeReader/types.ts
+++ b/vscode/webview-ui/src/codeReader/types.ts
@@ -143,9 +143,10 @@ interface BlockViewBase {
   attributes: Record<string, string>
   /** 这块认出来的概念，从左到右。webview 按图标名画，不自己用种类查 */
   concepts: BlockConcept[]
-  /** 能重写的那段注释的起止行。注释块是整块；函数、类等是它的说明。没有就不显示重写按钮。 */
-  commentStartLine?: number
-  commentEndLine?: number
+  /** 「注释」一行（讲这块的普通注释）排在第几行，0 起：属性表卡片是 properties 里的下标，一行译文的卡片是 rows 里的下标。「重写注释」按钮画在这一行上 */
+  commentRow?: number
+  /** 「重写注释」写到哪（扩展端用，这边只看有没有、是换掉还是新写）；没有就不显示按钮 */
+  commentTarget?: CommentTarget
   /** 库规则的卡片才有：卡片边框的颜色，筛选栏里这个种类的名字。和类块一样默认收起子块 */
   badge?: KindBadge
   /** 库规则挂在父卡片子行上的子块才有：展开时画在父卡片属性表第 row 行下面，不排在父卡片的子块里；见 BlockSlot */
@@ -163,10 +164,18 @@ export interface BlockSlot {
 }
 
 /**
- * 函数、类、枚举、导入、常量、变量块和库规则的卡片预览时是属性表，注释块是 Markdown 说明，其余是一行译文；
- * 一行译文下面依次是：跨几行写的调用摊开各个实参的表（table），块的说明（doc，Markdown 原文）
+ * 「重写注释」写到哪，行号 0 起：replace 换掉 startLine..endLine 这几行（块前面的普通注释；文件开头的说明卡片是它自己），
+ * insert 是块还没有注释，新写一段插在 line 这一行上面
  */
-export type BlockView = BlockViewBase & ({ translation: PreviewText, table?: PreviewTable, doc?: Markdown } | { properties: PropertyRow[] })
+export type CommentTarget
+  = | { kind: 'replace', startLine: number, endLine: number }
+    | { kind: 'insert', line: number }
+
+/**
+ * 函数、类、枚举、导入、常量、变量块和库规则的卡片预览时是属性表，文件开头的说明是 Markdown，其余是一行译文；
+ * 一行译文下面依次是：跨几行写的调用摊开各个实参的表（table），块的说明（doc，Markdown 原文），几行属性（rows：「注释」一行）
+ */
+export type BlockView = BlockViewBase & ({ translation: PreviewText, table?: PreviewTable, doc?: Markdown, rows?: PropertyRow[] } | { properties: PropertyRow[] })
 
 export interface TranslatorOption { id: string, label: string }
 
@@ -360,7 +369,7 @@ export interface RowDiff {
   items?: ItemsDiff
 }
 
-/** 一块自己的内容（不算子块）改了哪些：属性表逐行，一行译文逐截，摊开实参的表逐行，说明逐词 */
+/** 一块自己的内容（不算子块）改了哪些：属性表（一行译文的卡片是下面那几行 rows）逐行，一行译文逐截，摊开实参的表逐行，说明逐词 */
 export interface BlockMarks {
   rows?: RowsDiff
   translation?: TextDiff
@@ -429,7 +438,7 @@ export interface StickyScrollSettings {
  * askProfiles：「问 AI」的 profile 下拉；ready 后来一次，任何一个预览改了都会来
  * answer：askId 那个问题的回答长了（text 是到现在为止的全文）、或换了在做的事
  * answerEnd：askId 那个问题答完了，见 AnswerEnd
- * rewriteProgress：anchor 这段注释正在按规范重写。question 是发给模型的要求，text 是到现在为止的全文，activity 是正在读什么
+ * rewriteProgress：anchor 那块的注释正在按规范重写。question 是发给模型的那一句（技能命令和块在哪），text 是注释正文到现在为止写出来的，activity 是正在读什么
  * rewriteEnd：这段重写结束了。done 是正文已经写进文件；failed 带给人看的原因，文件没改；stopped 是被叫停，文件没改
  * moveOccurrence：跳到高亮着的名字的下一处（step 1）/ 上一处（step -1）出现
  * displayNames：version 这份文档里显示成中文名的名字，查到一步来一步；不是页面上这个版本的不理
@@ -476,7 +485,7 @@ export type ExtensionToWebview
  * setOnlyChanges：打开 / 关掉「只看改动」；同样等扩展端发回 filter 再按它显示
  * ask：问 anchor 那块代码；askId 由这边起，回答的消息带回来；扩展端接着这块最近一次问答的会话问，用眼下选的 profile；
  *   images 是贴进输入框的图片（没贴是空的），随问题发给 Claude Code，答成了跟这条一起存
- * rewriteComment：按注释规范重写 anchor 这段注释。过程用 rewriteProgress / rewriteEnd 回来，不写入问答
+ * rewriteComment：按注释规范重写 anchor 那块的注释（还没有就新写一段）。过程用 rewriteProgress / rewriteEnd 回来，不写入问答
  * stopRewrite：叫停 anchor 这段正在进行的重写，不写文件
  * stopAsk：叫停 askId 那个问题，这次不存
  * deleteQa：删掉 anchor 那块下面的一次问答（已经理解了）