✨ feat(vscode): 代码阅读侧栏给目录、文件记注释

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

@@ -23,7 +23,8 @@
 | 函数、类的说明 | TypeScript 紧贴在函数、类前面的 JSDoc，Python 函数、类主体开头的 docstring 是它自己的说明：进属性表「说明」一行，不再单独成一块注释；它的源码行算在函数、类块的头部里，「编辑」时和签名一起改 |
 | 注释按 Markdown 显示 | 注释块和函数、类的「说明」按 Markdown 渲染，像 Kotlin 的 KDoc：去掉注释符号、引号和共同缩进后的原文原样交给 Markdown，不按语言转换（reStructuredText 的 `:func:`、JSDoc 的 `@param` 都照抄，注释以后慢慢改成 Markdown 写法）；段内单个换行是软换行，空行分段 |
 | 跳到定义 | 和普通编辑器一样 ⌘ / Ctrl + 点击名字跳到定义，定义由 VS Code 装的语言扩展（Pylance、TypeScript 语言服务……）查；目标语言有代码阅读就在预览里打开 |
-| 侧栏文件树 | 只看和打开：展开目录、打开文件、刷新、全部折叠；不做新建 / 重命名 / 删除 |
+| 侧栏文件树 | 只看和打开：展开目录、打开文件、刷新、全部折叠，外加给目录 / 文件记注释；不做新建 / 重命名 / 删除 |
+| 文件注释 | 读代码时给目录 / 文件随手记一句：存在各工作区文件夹的 `.spx/code-notes.json`，跟着仓库走；在 VS Code 里改名、挪位置、删除时注释跟着变 |
 | 译文用词 | 结构照抄原语言，只翻关键字、内置类型、运算符；用专业术语（`export` → 公共，`catch` → 捕获，`===` → 全等） |
 | 函数、类、导入、常量、变量块 | 预览不显示一行译文，显示树形属性表；属性值里的类型、表达式照常直译 |
 
@@ -37,6 +38,21 @@
 - 视图标题栏：刷新、全部折叠（`showCollapseAll`）。文件变化时自动刷新（防抖）。
 - 点文件：语言受支持 → 用「代码阅读预览」自定义编辑器打开；否则 `vscode.open`。
 
+### 文件注释
+
+读代码时给目录或文件随手记一句（原型画板「文件注释 · 悬停出按钮 / 填写 / 已保存」）。
+
+- 鼠标停在目录 / 文件行上，行尾出现按钮（`view/item/context` 的 `inline` 组）：没注释时「添加注释」（`$(comment)`），有注释时「编辑注释」（`$(edit)`）。右键菜单里也有同一个命令。工作区根节点没有。
+- 两个命令只挂在侧栏行上，命令面板里藏起来（`when: false`）：面板里没有「哪一行」可言，按当前文件记还得另判断它有没有注释，没有必要。
+- 点按钮弹 VS Code 顶部的单行输入框（`window.showInputBox`）：标题 `添加注释 · <名字>` / `编辑注释 · <名字>`，编辑时预填原注释（整段选中），提示 `按 Enter 保存，按 Esc 取消；清空后保存即删除注释`。回车保存（去掉首尾空白），Esc 或点别处不改，清空后保存即删除。VS Code 会在提示后面自己再补一句「(Press 'Enter' to confirm or 'Escape' to cancel)」，关不掉。
+- 显示：有注释的行名字后面灰字是注释（`TreeItem.description`，放不下 VS Code 自己截断）；悬停提示是 Markdown，第一行粗体的相对路径，下一行注释全文，注释里的 Markdown 符号原样显示。没注释的行和原来一样。
+- contextValue：工作区根 `root`，目录 `folder`，文件 `file`；有注释的后面加 ` noted`。菜单按 `viewItem =~ /^(file|folder)$/`（添加）和 `/^(file|folder) noted$/`（编辑）切换。
+- 存储：每个工作区文件夹一份 `<工作区文件夹>/.spx/code-notes.json`，`{ "相对路径": "注释" }`，路径用 `/` 分隔、相对这个工作区文件夹；和 `.spx` 里别的文件同一套写法：文件缺失或解析失败当作没有注释，写时按需建 `.spx`，两格缩进、键排好序、末尾换行。存第一条注释前不生成文件；注释删光后文件留着（`{}`）。
+- 在 VS Code 里改名、挪位置（资源管理器拖动、`WorkspaceEdit` 等，走 `workspace.onDidRenameFiles`）：注释跟着走，目录连带里面各层的注释一起走；挪到另一个工作区文件夹就搬到那边的文件里，挪出工作区就不要了。删除（`onDidDeleteFiles`）：连带目录里各层的注释一起删。在 VS Code 外面（终端、git）改名删除不跟。
+- 外部改了 `code-notes.json`（git pull、手改）：文件监听重读，树上跟着变。
+- 刷新：只重画注释变了的那几行（文件树按 Uri 记住交给 VS Code 的节点对象，VS Code 按对象认行）；还没展开过的行不用管。
+- 注释和代码阅读的解析、翻译无关，单独放在 `notes/`；文件树只留一个「给行添信息」的接口（`FileTreeDecorator`），由 `index.ts` 接上。
+
 ### 编辑器右上角切换
 
 - 受支持语言的文件：普通编辑器里标题栏显示「预览」，预览里显示「编辑」。点一下在**同一个标签页位置**换成另一种：用 VS Code 内部的 `reopenActiveEditorWith`（「重新打开编辑器的方式」背后的机制）原位替换。不能用「另开再关原标签」：文件有未保存改动时关原标签会弹保存框，选「不保存」会丢改动。
@@ -445,7 +461,12 @@ vscode/src/codeReader/
   translators/zhTemplate.ts         模板直译引擎（按语言的表驱动）
   translators/typescriptZh.ts       TS 表
   translators/pythonZh.ts           Python 表
-  explorer/fileTree.ts   侧栏文件树
+  explorer/fileTree.ts   侧栏文件树（FileTreeDecorator：给行添信息的接口）
+  notes/noteMap.ts       注释的键、保存 / 改名 / 删除时怎么改（纯函数）
+  notes/store.ts         .spx/code-notes.json 读写
+  notes/noteItem.ts      有注释的行怎么显示：描述、悬停提示、contextValue（纯函数）
+  notes/fileNotes.ts     FileNotes：内存里的注释、文件监听、跟着改名 / 删除走、给树画行
+  notes/commands.ts      「添加注释 / 编辑注释」输入框
   editor/previewEditor.ts  CustomTextEditorProvider
   editor/messages.ts     消息类型
   editor/definitions.ts  查定义（vscode.executeDefinitionProvider）、几处定义的挑选框
@@ -466,6 +487,7 @@ vscode/webview-ui/code-reader.html + src/codeReader/  预览界面（React，Vit
 - 行替换：多行块替换后缩进正确。
 - 跳到定义：TS / Python 译文和属性表里的名字、点分模块名每一节、模块字符串带下标且指回源码原文，关键字、运算符、说明词不带（前面有中文注释也对得上）；查到的定义 → 不动 / 原地 / 预览 / 普通编辑器 / 挑选框；webview 里按下标找目标块、要展开的祖先块和属性行，滚动位置。闪哪一处（TS、Python 源码走完整的语言插件 + 翻译插件 + 视图数据）：参数 → 它那个子行，导入项 → 它那一项，多变量声明里的一个 → 它的名称行，类的泛型参数 → 「类型参数」那一行，函数名 / 类名 / 单个变量名（含解构模式）→ 整块，循环变量 → 所在的块，翻译插件没填 `defines` → 整块（照样展开属性行）；翻译插件给参数、导入项、声明的变量、泛型参数标的范围指回源码原文；块自己的名字只有函数、类和单变量声明有。
 - 注册表：注册 / 注销后 `languageIds` 与可选翻译正确；同一语言多个翻译时按 `globalState` 选中。
+- 文件注释：键相对工作区文件夹、`/` 分隔，根和外面的路径没有键，手写的 `./`、结尾 `/` 规范掉；保存去空白、清空即删；文件改名、目录挪位置里面各层一起走、名字只是前缀相同的不动、跨工作区文件夹先取出再放进去；删目录连带里面的；读写：文件缺失 / 解析失败 / 不是对象返回空表、跳过不合法条目、建 `.spx`、键排序、删光留 `{}`；有注释 / 没注释的行的描述、悬停提示（Markdown 转义）、contextValue，和 `package.json` 里菜单的 when 子句对得上。
 
 ## 收尾