✨ feat(vscode): 代码阅读函数块默认折叠，函数说明进属性表「说明」行

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

@@ -19,7 +19,8 @@
 | 多种翻译怎么选 | 预览顶部下拉框，整个文件一起换，按语言记住选择；只有一种时不显示 |
 | 侧栏点文件 | 支持的语言默认打开成「预览」；不支持的语言用普通编辑器打开 |
 | 块内修改 | 改的就是文件本身：未保存标记、⌘S 保存、⌘Z 撤销都照常，切回「预览」按新代码重新翻译 |
-| 折叠 | 有子块的块、属性表里带子行的行能折叠，默认全部展开 |
+| 折叠 | 有子块的块、属性表里带子行的行能折叠；函数块（含方法、嵌套函数）默认收起主体、属性表照常显示，其余块和属性行默认展开；用户点过的按他点的记住 |
+| 函数的说明 | TypeScript 紧贴在函数前面的 JSDoc、Python 函数主体开头的 docstring 是函数自己的说明：进属性表「说明」一行，不再单独成一块注释；它的源码行算在函数块的头部里，「编辑」时和签名一起改 |
 | 跳到定义 | 和普通编辑器一样 ⌘ / Ctrl + 点击名字跳到定义，定义由 VS Code 装的语言扩展（Pylance、TypeScript 语言服务……）查；目标语言有代码阅读就在预览里打开 |
 | 侧栏文件树 | 只看和打开：展开目录、打开文件、刷新、全部折叠；不做新建 / 重命名 / 删除 |
 | 译文用词 | 结构照抄原语言，只翻关键字、内置类型、运算符；用专业术语（`export` → 公共，`catch` → 捕获，`===` → 全等） |
@@ -50,7 +51,8 @@
 - 内容两种状态，每块单独切：
   - 预览：函数、导入、常量、变量块是属性表（见下节），其余块是一行译文；按词着色，等宽字体（中文部分用系统中文字体回退）。
   - 编辑：这一块的源码（按语法树着色），可以直接改；蓝色边框。按钮文字「预览」；Esc 也回到预览。
-- 复合语句（函数、条件、循环……）块里只放它自己的头部那几行（主体交给子块）；收尾括号、空行不成块。
+- 复合语句（函数、条件、循环……）块里只放它自己的头部那几行（主体交给子块）；收尾括号、空行不成块。函数的说明（JSDoc / docstring）也算在函数块的头部里。
+- 折叠：函数块打开时默认收起子块（属性表照常显示），其余块默认展开；用户点过折叠箭头的块按他点的，记在视图状态里（见「预览数据与消息」）。
 - 顶部工具栏：翻译下拉框（多于一种翻译时才显示）。
 - 解析失败：显示错误原因，并提示用「编辑」查看源码。
 
@@ -60,7 +62,7 @@
 
 | 种类 | 行 |
 | --- | --- |
-| 函数 | 名称（函数色；匿名函数写「匿名」）/ 访问级别 / 异步（是 / 否）/ 装饰器（有才显示，源码原样照抄、按源码着色，多个换行）/ 输入参数（`N 个` 或「无」，每个参数一行：名称 \| 类型（没标注写「未标注」）\| 默认值（`默认 ` + 译文，没有留空））/ 输出参数（返回类型的译文，没标注写「未标注」） |
+| 函数 | 名称（函数色；匿名函数写「匿名」）/ 说明（有说明才显示：JSDoc 去掉 `/**`、`*/` 和每行开头的 `*`，docstring 去掉引号；再去掉共同缩进和首尾空行，保留换行和 `@param` 这类标签行；按 comment 着色，多行照原样换行、长了折行；里面的名字不能点）/ 访问级别 / 异步（是 / 否）/ 装饰器（有才显示，源码原样照抄、按源码着色，多个换行）/ 输入参数（`N 个` 或「无」，每个参数一行：名称 \| 类型（没标注写「未标注」）\| 默认值（`默认 ` + 译文，没有留空））/ 输出参数（返回类型的译文，没标注写「未标注」） |
 | 导入 | 来源（TypeScript 是字符串字面量原样，如 `'node:fs'`，字符串色；Python 是点分模块名，如 `fastapi`、`.models`，类型色）/ 仅类型（是 / 否，只有 TypeScript 有，看 `import type`）/ 导入项（`N 个` 或「无」，每项一行：`name`、`name 作为 alias`；默认导入写「默认导出 作为 x」，`* as x` 写「全部 作为 x」，Python `from m import *` 写「全部」，Python `import a.b as c` 写「整个模块 作为 c」，一条 `import a, b` 导入多个模块时写模块名） |
 | 常量 / 变量 | 名称（解构声明写整个模式，如 `{ p, q }`）/ 访问级别 / 类型（写了标注才有）/ 值（常量）或初始值（变量）：初始化表达式的译文，没有写「无」。一条语句声明几个变量（`let a = 1, b = 2`）就重复几组 |
 
@@ -111,6 +113,7 @@ export interface ParameterFacts {
 
 export interface FunctionFacts {
   name?: Node           // 匿名函数没有
+  doc?: Node            // 函数的说明：紧贴在前面的 JSDoc 注释节点（TS）、主体开头的 docstring 字符串节点（Python）
   access?: Access       // 嵌套在语句块里的函数没有
   async: boolean
   decorators: Node[]
@@ -140,7 +143,7 @@ export interface VariableFacts {
 export interface BlockShape {
   /** 这一块对应的语法树节点（整条语句）。 */
   node: Node
-  /** 块自己显示 / 编辑的那一段：复合语句只到主体开始之前，其余是整条语句。 */
+  /** 块自己显示 / 编辑的那一段：复合语句只到主体开始之前，其余是整条语句；函数的说明（doc）也算在里面。 */
   header: SourceSpan
   children: CodeBlock[]
 }
@@ -222,6 +225,7 @@ export interface CodeReaderApi {
 ### TypeScript / JavaScript
 
 - 顶层与语句块内的每条语句一块；连续的行注释合成一块注释。
+- JSDoc（以 `/**` 开头的块注释，`/**/` 不算）和下一条语句之间只有空白（空行也算，中间隔着装饰器也算）、那条语句是函数块时，它是这个函数的说明：进 `facts.doc`，头部往上延到注释开头，不单独成块。其余情况（后面不是函数块、中间隔着别的注释、在上一条语句的行尾）照旧是注释块。`//` 行注释和普通 `/* */` 块注释不变。
 - `import_statement` → import。
 - `export_statement` 包着声明 → 按声明定种类，节点取整个 `export_statement`（头部包含 `export`）。
 - `function_declaration` / `generator_function_declaration` / `method_definition` → function，子块来自主体语句。
@@ -241,7 +245,8 @@ export interface CodeReaderApi {
 - `import_statement` / `import_from_statement` / `future_import_statement` → import。
 - `function_definition` → function；`decorated_definition` 按内部定义定种类，头部包含装饰器。
 - `class_definition` → class；类体里的带注解赋值 → field。
-- 模块 / 函数 / 类主体开头的字符串表达式（docstring）和 `comment` → comment。
+- 模块 / 类主体开头的字符串表达式（docstring）和 `comment` → comment。
+- 函数主体的第一条语句（注释不算）是单独一个字符串表达式时，它是函数的 docstring：进 `facts.doc`，头部往下延到字符串结尾（它和冒号之间的注释也在头部里），子块从它后面开始，不单独成块。
 - 赋值：模块顶层且变量名全大写 → const，其余 → variable。
 - `if_statement` → if；`elif_clause` / `else_clause` → 兄弟块 else；`for` / `while` → loop（循环的 `else` → 兄弟块 else）。
 - `try_statement` → try；`except_clause` → catch；`finally_clause` → finally。
@@ -251,10 +256,10 @@ export interface CodeReaderApi {
 
 ### 属性表信息（facts）从哪来
 
-- TypeScript 函数：`function_declaration` / `generator_function_declaration` / `function_signature`、类里的 `method_definition` / 方法签名、值是带语句块主体函数的变量和类字段、`export default` 的函数值。名称取声明名 / 变量名 / 字段名；参数来自 `formal_parameters`（`required_parameter` / `optional_parameter` 的 pattern、type、value，JavaScript 的 `assignment_pattern`），不带括号的单参数箭头函数取 `parameter`；返回类型取 `return_type` 里的类型；异步看有没有 `async`；类成员的装饰器是类主体里排在它前面的 `decorator` 兄弟节点。
+- TypeScript 函数：`function_declaration` / `generator_function_declaration` / `function_signature`、类里的 `method_definition` / 方法签名、值是带语句块主体函数的变量和类字段、`export default` 的函数值。名称取声明名 / 变量名 / 字段名；说明取紧贴在前面的 JSDoc 注释节点（见上面代码块树规则）；参数来自 `formal_parameters`（`required_parameter` / `optional_parameter` 的 pattern、type、value，JavaScript 的 `assignment_pattern`），不带括号的单参数箭头函数取 `parameter`；返回类型取 `return_type` 里的类型；异步看有没有 `async`；类成员的装饰器是类主体里排在它前面的 `decorator` 兄弟节点。
 - TypeScript 导入：`import_statement` 的 `source`（`import x = require()` 取 `import_require_clause` 里的）；`import_clause` 里的标识符是默认导入，`namespace_import` 是 `* as`，`named_imports` 里每个 `import_specifier` 的 name / alias；语句本身带 `type` 是仅类型。
 - TypeScript 变量：每个 `variable_declarator` 的 name / type / value。
-- Python 函数：`function_definition` 的 name / parameters / return_type，`async` 子节点；装饰器是 `decorated_definition` 里的 `decorator`；参数 `identifier`、`typed_parameter`（名字是第一个具名子节点）、`default_parameter`、`typed_default_parameter`、`*args` / `**kwargs`，`*` 和 `/` 分隔符不算参数。
+- Python 函数：`function_definition` 的 name / parameters / return_type，`async` 子节点；说明是主体开头 docstring 的字符串节点（`string` / `concatenated_string`）；装饰器是 `decorated_definition` 里的 `decorator`；参数 `identifier`、`typed_parameter`（名字是第一个具名子节点）、`default_parameter`、`typed_default_parameter`、`*args` / `**kwargs`，`*` 和 `/` 分隔符不算参数。
 - Python 导入：`import_statement` 每个 name 一个来源、导入项是整个模块；`import_from_statement` 的 module_name 和各 name（`aliased_import` 拆出 alias），`wildcard_import` 是全部；`future_import_statement` 的来源是 `__future__`。
 - Python 变量：`assignment` 的 left / type / right。
 
@@ -306,12 +311,12 @@ Python 内置类型（仅注解里）：str 字符串、int 整数、float 浮
 
 | 源码 | 属性表 |
 | --- | --- |
-| `export async function findEnvFiles(workspaceRoot: string): Promise<string[]> {` | 名称 findEnvFiles / 访问级别 公共 / 异步 是 / 输入参数 1 个：`workspaceRoot \| 字符串 \|` / 输出参数 `Promise<字符串[]>` |
+| `export async function findEnvFiles(workspaceRoot: string): Promise<string[]> {`（envLock.ts 18–23 行，连同前面的 JSDoc） | 名称 findEnvFiles / 说明 `Scan the workspace folder rooted at …`（三行，照原样换行）/ 访问级别 公共 / 异步 是 / 输入参数 1 个：`workspaceRoot \| 字符串 \|` / 输出参数 `Promise<字符串[]>` |
 | `async function chmodAll(workspaceRoot: string, mode: number): Promise<EnvLockResult> {` | 名称 chmodAll / 访问级别 私有 / 异步 是 / 输入参数 2 个：`workspaceRoot \| 字符串`、`mode \| 数值` / 输出参数 `Promise<EnvLockResult>` |
 | `import { promises as fsp } from 'node:fs'` | 来源 `'node:fs'` / 仅类型 否 / 导入项 1 个：`promises 作为 fsp` |
 | `const ENV_PATTERN = '**/.env*'` | 名称 ENV_PATTERN / 访问级别 私有 / 值 `'**/.env*'` |
 | `const issue = issues.find(i => i.number === issueNumber)` | 名称 issue / 初始值 `issues.find(i => i.number 全等 issueNumber)` |
-| `def find_env_files(root: str) -> list[str]:` | 名称 find_env_files / 访问级别 公共 / 异步 否 / 输入参数 1 个：`root \| 字符串` / 输出参数 `列表[字符串]` |
+| `def find_env_files(root: str) -> list[str]:`（sample.py，连同下一行的 docstring） | 名称 find_env_files / 说明 `Return every .env file under root.` / 访问级别 公共 / 异步 否 / 输入参数 1 个：`root \| 字符串` / 输出参数 `列表[字符串]` |
 | `from .schemas import (⏎ UserAvatarUploadResponse, … )`（routes.py 19–23 行） | 来源 `.schemas` / 导入项 3 个：UserAvatarUploadResponse、UserDetailResponse、UserUpdateRequest |
 | `payload = await file.read()`（routes.py，函数体里） | 名称 payload / 初始值 `等待 file.read()` |
 | `_default_port = 5680 if _role == "beat" else 5679` | 名称 _default_port / 访问级别 私有 / 初始值 `如果 _role 等于 "beat" 则 5680 否则 5679` |
@@ -345,7 +350,7 @@ type BlockView = BlockViewBase & ({ translation: Segment[] } | { properties: Pro
   - `{ type: 'ready' }`
   - `{ type: 'edit', startLine, endLine, text }`：用 `WorkspaceEdit` 把这几行整行替换成 `text`（每行补回原来第一行的缩进）。
   - `{ type: 'selectTranslator', id }`：按 `languageId` 记到 `globalState`，重发文档。
-- 块的编辑 / 折叠状态在 webview 里按块 id 记（`vscode.setState`），属性行的折叠状态记在同一份折叠集合里，id 是 `<块 id>/p<行序号>`（例如 `6.1.0/p3`）；文档刷新后保留；正在编辑且有焦点的块，刷新时不覆盖输入框内容。
+- 块的编辑状态和用户的折叠选择在 webview 里按块 id 记（`vscode.setState`）：`{ editing: string[], folds: Record<id, boolean>, scroll? }`。`folds` 只记用户点过的（id → 折叠着没有），属性行也记在里面，id 是 `<块 id>/p<行序号>`（例如 `6.1.0/p3`）；没记的按默认：函数块折叠，其余块和属性行展开。眼下折叠着哪些由「默认 + folds」算出来，界面、跳到定义的展开都只看这一份。跳到定义展开祖先块、属性行时也记进 `folds`（记成展开）。读回来的状态逐项核对，旧版本存的、形状不对的项当没存过。文档刷新后保留；正在编辑且有焦点的块，刷新时不覆盖输入框内容。
 
 ## 颜色
 
@@ -364,7 +369,7 @@ type BlockView = BlockViewBase & ({ translation: Segment[] } | { properties: Pro
 | hint | `--vscode-descriptionForeground` | 同左 |
 | plain | `--vscode-editor-foreground` | 同左 |
 
-属性表里：访问级别（公共 / 私有 / 受保护）和「作为」按 keyword，是 / 否按 storage，函数名称按 function，未标注、无、N 个、默认、默认导出、全部、整个模块、匿名按 hint。
+属性表里：说明按 comment，访问级别（公共 / 私有 / 受保护）和「作为」按 keyword，是 / 否按 storage，函数名称按 function，未标注、无、N 个、默认、默认导出、全部、整个模块、匿名按 hint。
 
 种类（标签字色 + 标签底 18% + 块底 7% + 边框 35%；亮色主题同色系）：import 导入 #c586c0；function 函数 #dcdcaa；class 类、type 类型 #4ec9b0；field 字段、const 常量、variable 变量 #9cdcfe；if 条件、else 否则 #ce9178；loop 循环 #8f9cff；try 尝试、catch 捕获、finally 最终 #f48771；return 返回 #89d185；statement 语句 #9d9d9d；comment 注释 #6a9955（虚线框）。编辑状态：底色 `--vscode-editor-background`，边框 `--vscode-focusBorder`。
 
@@ -392,7 +397,9 @@ vscode/webview-ui/code-reader.html + src/codeReader/  预览界面（React，Vit
 
 ## 测试
 
-- 语言插件：`envLock.ts`、`issueLock.ts` 的代码块树（种类、header 行号、层级）与原型 `CODE_TREE` 一致；Python 样例覆盖 import / def / docstring / if-elif-else / for / try-except / with / 推导式。
+- 语言插件：`envLock.ts`、`issueLock.ts` 的代码块树（种类、header 行号、层级）与原型 `CODE_TREE` 一致，只是紧贴函数的 JSDoc 算进了函数头部；Python 样例覆盖 import / def / docstring / if-elif-else / for / try-except / with / 推导式；函数的说明：JSDoc 各种挂法（export、默认导出、方法隔着装饰器、函数值的变量、嵌套函数）和不挂的情况，docstring 连同它前面的注释进头部。
+- 块头部：各样例里块的头部行互不重叠；函数说明所在的行在函数块里，「编辑」写回原样不变。
+- 折叠：默认函数块折叠、其余展开；用户的选择盖过默认、重新加载后还在；旧版本存的状态不报错；跳到定义时默认折叠的函数也会展开。
 - 属性表信息：`envLock.ts`、`sample.py`、`routes.py`（原型里的 FastAPI 路由）加内联片段，覆盖各种导入写法、形参写法、类成员访问修饰符、解构和多变量声明、Python 下划线规则。
 - 翻译：上面两张样例表逐字一致；属性名不被翻；每个被翻的词单独成段；节点模板嵌套时正确、槽位里照样翻、没命中模板的节点照抄；属性表里的值和一行译文用同一套表和模板。
 - `blockView`：`codeTokens` 拼起来等于 `code`；去缩进正确；函数、导入、常量、变量块只带属性表，其余块只带译文。