✨ feat(vscode): 代码阅读认出 Python 数据类（@dataclass），整块换成「数据类」卡片，选项和字段的默认值、field 参数写成大白话

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

@@ -792,6 +792,49 @@ export interface CodeReaderApi {
   INVALID | "invalid" | 已失效
 ```
 
+### 内置：dataclasses 数据类（Python）
+
+`vscode/src/codeReader/rules/dataclass.ts`，`libraries: ['dataclasses']`（Python 自带的库）。样例是 luffy 的 `user/repositories.py`、`commerce/payments/_driver.py`、`core/sms/services.py`、`sandbox/runtime.py` 里的数据类（节选在 `fixtures/dataclassModels.py`）。种类 `dataclasses.dataclass`，标签「数据类」（暗 #ef7fb0 / 亮 #b3306c），和类块一样默认收起子块。
+
+- 认哪些类：装饰器是 `@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`、没注解的类属性、讲它们的注释照常是子块。
+
+属性表（有才显示；字段总有，一个都没有时写「0 个」、不画表格）：
+
+| 行 | 内容 |
+| --- | --- |
+| 名称 | 类名（type 色，带下标） |
+| 说明 | 类的 docstring；Markdown |
+| 访问级别 | 公共 / 私有 / 受保护（keyword 色） |
+| 继承 | 父类照写法（翻译插件翻） |
+| 装饰器 | dataclass 以外的装饰器（`@final`），有才显示 |
+| 选项 | dataclass 装饰器的参数，只讲写了、又不是默认值的，照写的顺序用 ` · ` 隔开（storage 色）：`frozen=True` 不可修改、`slots=True` 省内存（固定属性）、`order=True` 可比较大小、`kw_only=True` 只能按名字传参、`eq=False` 不按字段比较相等、`unsafe_hash=True` 可哈希、`init=False` 不生成构造函数、`repr=False` 不生成文字表示、`match_args=False` match 语句里不能按位置匹配、`weakref_slot=True` 可弱引用；写成默认值的（`frozen=False`）不讲；别的参数、值不是 True / False 的照写 `名=值`（值翻译插件翻），`**x` 照写 |
+| 字段 N 个 | 表格：字段 \| 类型 \| 默认值 \| 说明，每个字段一行，讲的定义是字段名 |
+
+字段表的格子：
+
+- 字段：字段名（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 色。
+
+样例（`fixtures/dataclassModels.py` 的 `SandboxAccess`，测试里逐字核对；说明的 Markdown 从略）：
+
+```
+名称: SandboxAccess
+说明: sandbox 类工具的最小资源集 (任何沙箱工具都需要). …
+访问级别: 公共
+选项: 不可修改 · 省内存（固定属性）
+字段: 5 个
+  sandbox | CodeSandbox |  | 
+  sandbox_id | 字符串 |  | 
+  app_id | 字符串 | 空 | 空 | 
+  session_id | 字符串 | 空 | 空 | 
+  binding | SandboxBinding | 不进构造函数 · 不参与比较 · 不显示 | 
+```
+
+`__post_init__` 照常是卡片的子块。
+
 ## 解析运行时
 
 - 依赖 `@vscode/tree-sitter-wasm`（VS Code 团队维护，包含 web-tree-sitter 运行时和 TypeScript / TSX / JavaScript / Python 语法包，版本配套）。
@@ -984,7 +1027,7 @@ type BlockView = BlockViewBase & ({ translation: PreviewText, doc?: Markdown } |
 
 属性表里：说明按 comment，访问级别（公共 / 私有 / 受保护）和「作为」按 keyword，是 / 否按 storage，函数名称按 function，类名称按 type，未标注、无、N 个、字典 N 项、对象 N 项、展开、默认导出、全部、整个模块、匿名按 hint；输入参数表格的列名是界面文字（`descriptionForeground`），不是着色的词。推导式框里的「遍历」「的每个」「仅当」「取」「异步遍历」按 keyword，框头按「循环」块的种类色。父类名（TypeScript `extends` 后面、JavaScript `class_heritage` 里、Python 类名后面括号里直接写的名字）源码着色和属性表里都按 type。
 
-种类（标签字色 + 标签底 18% + 块底 7% + 边框 35%；亮色主题同色系）：import 导入 #c586c0；function 函数 #dcdcaa；class 类、type 类型 #4ec9b0；enum 枚举 #b180d7（亮色 #652d90）；field 字段、const 常量、variable 变量 #9cdcfe；if 条件、else 否则 #ce9178；loop 循环 #8f9cff；try 尝试、catch 捕获、finally 最终 #f48771；return 返回 #89d185；statement 语句 #9d9d9d；comment 注释 #6a9955（虚线框）；库规则的种类用规则给的颜色（`badge.color` 的 dark / light，webview 写在块的 style 上按主题挑），内置 SQLAlchemy 数据表 #e8a860 / #a3590d，Celery 应用 #98c379 / #4d7f17，定时任务 #56b6c2 / #127f8c。编辑状态：底色 `--vscode-editor-background`，边框 `--vscode-focusBorder`。
+种类（标签字色 + 标签底 18% + 块底 7% + 边框 35%；亮色主题同色系）：import 导入 #c586c0；function 函数 #dcdcaa；class 类、type 类型 #4ec9b0；enum 枚举 #b180d7（亮色 #652d90）；field 字段、const 常量、variable 变量 #9cdcfe；if 条件、else 否则 #ce9178；loop 循环 #8f9cff；try 尝试、catch 捕获、finally 最终 #f48771；return 返回 #89d185；statement 语句 #9d9d9d；comment 注释 #6a9955（虚线框）；库规则的种类用规则给的颜色（`badge.color` 的 dark / light，webview 写在块的 style 上按主题挑），内置 SQLAlchemy 数据表 #e8a860 / #a3590d，Celery 应用 #98c379 / #4d7f17，定时任务 #56b6c2 / #127f8c，数据类 #ef7fb0 / #b3306c。编辑状态：底色 `--vscode-editor-background`，边框 `--vscode-focusBorder`。
 
 ## 代码位置
 
@@ -1002,9 +1045,10 @@ vscode/src/codeReader/
   rules/sqlalchemy.ts    内置 SQLAlchemy 库规则（只 import contract 和同目录的共用代码）
   rules/celery.ts        内置 Celery 库规则：两张卡片、频率换算、任务名索引
   rules/enum.ts          内置 enum 库规则（Python）：枚举类认成枚举块，成员照 Python 的规则认
-  rules/pythonTree.ts    Python 库规则共用的读语法树的办法（名字最后一节、字符串内容、调用的参数、别名）
+  rules/dataclass.ts     内置 dataclasses 库规则（Python）：数据类卡片，字段照 dataclasses 的规则认
+  rules/pythonTree.ts    Python 库规则共用的读语法树的办法（名字最后一节、字符串内容、调用的参数、别名、注解里的 X[...]、库里的名字）
   rules/segments.ts      库规则共用的拼属性表文字的办法
-  rules/children.ts      库规则共用的挑子块的办法（成员连同紧挨在它前面的注释块）
+  rules/children.ts      库规则共用的挑子块的办法（成员连同紧挨在它前面的注释块、成员的说明节点）
   languages/typescript.ts
   languages/python.ts    （iteration：推导式的结构）
   translators/zhTemplate.ts         模板直译引擎（按语言的表驱动，词性、遍历结构从 SourceDocument.language 取；推导式排进框见 iterationGroup）
@@ -1065,6 +1109,7 @@ vscode/webview-ui/code-reader.html + src/codeReader/  预览界面（React，Vit
 - 工作区索引（内存里的工作区，`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；没注解的类属性、字段中间的方法照源码顺序是子块，「编辑」写回整个类。
 - 筛选：块的属性（TS、TSX 有抽象、仅类型，JavaScript / JSX 没有这两个属性、属性表也没有这两行，Python 有访问级别、异步）；语言插件自己报的属性叠上去、盖过推出来的，kind 不变；文件里出现过的属性按契约顺序排、语言的排后面，值按第一次出现排、带所有层的块数，名字取翻译插件的、没有的显示 id，中文直译的名字和属性表一致；下拉框只给两种以上值的属性（或一种值正被去掉的），按钮上的字；全选 / 取消全选只动这份文件里的值、别的文件的去掉状态和别的属性不动、取消全选藏掉有这个属性的块（整棵子树）、再全选全回来；同一属性内「或」、不同属性「且」、没有这个属性不受影响、藏整棵子树、「已隐藏」只数直接筛掉的；筛选记在 `workspaceState`、新实例读得回来、所有订阅的预览收到、形状不对的当没有；跳到被筛掉的块临时露出路径、目标的子块照常筛、文档刷新只留正在编辑的。
 - 文件注释：键相对工作区文件夹、`/` 分隔，根和外面的路径没有键，手写的 `./`、结尾 `/` 规范掉；保存去空白、清空即删；文件改名、目录挪位置里面各层一起走、名字只是前缀相同的不动、跨工作区文件夹先取出再放进去；删目录连带里面的；读写：文件缺失 / 解析失败 / 不是对象返回空表、跳过不合法条目、建 `.spx`、键排序、删光留 `{}`；有注释 / 没注释的行的描述、悬停提示（Markdown 转义）、contextValue，和 `package.json` 里菜单的 when 子句对得上。
 - 侧栏行上的菜单（`explorer/rowMenus.test.ts`，读 `package.json`）：行尾按钮先「复制」子菜单再注释，有没有注释换「添加 / 编辑注释」，工作区根都没有；「复制」子菜单带 `$(copy)`，注释图标 `$(note)` / `$(edit)`；子菜单和右键菜单里文件四项、目录三项（有没有注释一样）、菜单上的字；复制命令都登记了、和代码里的命令表一致、命令面板里藏起来。