文件备注助手

文件备注助手会在 VS Code 左侧 Activity Bar 增加独立入口，让文件、文件夹名称和备注显示在同一行：

src                  源码目录
  views              页面目录
    login.vue        登录页面
    home.vue         首页
  api                接口目录
    user.ts          用户接口

插件预览

文件与文件夹备注

可视化备注配置

功能

• 保留工作区真实目录结构，点击文件即可打开。
• 左侧提供独立的“文件备注”图标，不占用原生资源管理器空间。
• 在文件或文件夹名称右侧直接显示备注。
• 支持从原生资源管理器或“文件备注”视图右键设置、修改、删除文件及文件夹备注。
• 双击 .vscode/file-notes.json 默认打开可视化配置页，并可在页面与原生 JSON 编辑器之间切换。
• 支持多根工作区，每个工作区分别保存自己的备注。
• 手动修改备注配置后自动刷新。
• 在 VS Code 内重命名文件或目录时，自动迁移对应备注。
• 删除文件时自动删除对应备注；删除文件夹时同时清理其自身及所有子项备注。
• 递归发现工作区根目录及嵌套子项目中的 package.json，按项目路径显示 NPM 脚本。
• 点击可在对应子项目目录运行 NPM 脚本，右键可复制带项目路径的 NPM 命令。
• 使用 workspace.fs 读写，兼容 Remote SSH 和虚拟工作区。

VS Code 官方 API 不允许插件修改原生文件树的文件或文件夹名称文本，因此备注显示在插件提供的独立文件树中。文件备注助手不注入 DOM，也不会修改真实名称。

使用方法

1. 打开一个文件夹或工作区。
2. 在原生资源管理器中右键一个文件或文件夹。
3. 选择“文件/文件夹备注 > 设置备注…”。
4. 点击左侧 Activity Bar 的“文件备注”图标，在“工作区文件”视图中查看结果。

也可以在“文件备注”视图中右键文件或文件夹，设置或删除备注，并使用“在资源管理器中显示”定位原位置。

“npm”视图会递归读取工作区内的 package.json#scripts，并按“工作区名/package.json → 脚本”展示；嵌套项目显示为“工作区名/子项目路径/package.json”。脚本行保持简洁，悬浮时显示实际执行内容；点击脚本会自动在所属子项目目录运行。

复制嵌套项目的脚本时会生成类似 npm --prefix apps/web run dev 的命令，避免在工作区根目录执行到错误的同名脚本。 若脚本名或项目路径包含 Shell 特殊字符，插件不会生成复制命令，但仍可通过点击脚本安全运行。

运行脚本需要受信任且支持 Shell 执行的工作区；受限模式或虚拟工作区仍可查看脚本内容和复制 NPM 命令。

备注配置

备注保存在每个工作区根目录的：

.vscode/file-notes.json

文件内容是简单的“文件或文件夹相对路径 -> 备注”映射：

{
  "README.md": "项目说明",
  "src": "源码目录",
  "src/api": "接口目录",
  "src/api/user.ts": "用户接口",
  "src/views/login.vue": "登录页面"
}

双击 .vscode/file-notes.json 会默认进入可视化配置页。页面支持：

• 搜索、新增、编辑、删除和定位备注路径。
• 从工作区直接选择文件或文件夹，也可以手动填写相对路径。
• 未完成的新增草稿会临时保存在 VS Code 的工作区状态中（不写入项目文件），关闭配置标签后重新打开仍可继续填写。
• 修改后自动同步到当前 VS Code 文档，通过页面“保存”按钮或 Cmd/Ctrl+S 写入磁盘。
• 点击“JSON 源码”切换到原生 JSON 编辑器；在 JSON 编辑器标题栏点击“打开可视化配置”可以切回页面。
• JSON 内容损坏时停止页面写入，并提供“打开 JSON 修复”，避免覆盖原始内容。

规则：

• 文件和文件夹路径都相对于当前工作区根目录，并统一使用 / 分隔。
• 备注不能为空、不能换行，最多 120 个字符。
• 配置损坏时插件不会覆盖原文件，会提示先打开并修复。
• 若备注需要团队共享，可以提交该文件；若只供个人使用，可以自行加入 .gitignore。

命令

• 文件备注助手: 设置备注…
• 文件备注助手: 删除备注
• 文件备注助手: 打开备注配置
• 文件备注助手: 打开可视化配置
• 文件备注助手: 刷新
• 文件备注助手: 在资源管理器中显示
• 文件备注助手: 运行 NPM 脚本
• 文件备注助手: 复制 NPM 命令
• 文件备注助手: 刷新 NPM 脚本

设置

fileNotes.excludedNames 用于配置不在备注树中显示的文件或目录名称，默认隐藏：

• .git
• node_modules
• .DS_Store

fileNotes.npmScripts.excludedDirectoryNames 用于配置扫描嵌套 NPM 项目时忽略的目录名称，默认排除 node_modules、版本控制目录以及常见构建、缓存目录。

已知限制

• 原生资源管理器的文件或文件夹名称后不能直接追加备注，这是 VS Code API 的限制。
• 在 VS Code 外部重命名文件或文件夹时，插件无法可靠判断新旧路径的对应关系，可能会按“旧路径已删除”清理备注，需要为新路径重新设置。
• 删除资源后，对应备注也会被永久删除；恢复同一路径的文件或文件夹不会自动恢复原备注。
• 当前不支持为工作区根目录添加备注，但支持工作区内的所有普通文件夹。

本地开发

npm install
npm run compile

在 VS Code 中按 F5，即可启动 Extension Development Host 调试插件。

打包 VSIX

打包工具 @vscode/vsce 需要 Node.js 20 或更高版本。在项目根目录执行：

npm install
npm run package:list
npm run package

package:list 用于在打包前检查最终会被放入插件的文件。执行 npm run package 时会自动调用 vscode:prepublish，完成 TypeScript 编译，并根据 package.json 中的插件名称和版本，将安装包生成到 release/ 目录：

release/file-note-assistant-0.1.2.vsix

可以在 VS Code 的扩展面板中点击右上角 …，选择“从 VSIX 安装…”，也可以在命令行安装：

code --install-extension release/file-note-assistant-0.1.2.vsix --force

release/ 目录已预先创建。源码修改后必须重新打包并安装新生成的 VSIX，不要继续测试旧文件。正式发布新版本前，还需要先更新 package.json 中的 version；生成的 VSIX 文件名会随版本变化。

License

MIT