文件备注 (File Notes)

给文件和文件夹添加备注标签，在资源管理器文件列表中直接显示。支持自动推断、自定义规则、树视图浏览。

功能特性

基本功能

添加备注 — 右键文件/文件夹 → 添加备注 → 输入文字 → 回车确认
删除备注 — 右键 → 删除备注 → 二次确认
清除所有备注 — 右键 → 清除所有备注 → 二次确认
重新推断 — 右键 → 重新执行自动推断

显示方式

方式	位置	说明
徽章	文件名右侧	备注文字直接显示在文件名后面，悬停查看完整内容
树视图	资源管理器下方「备注列表」	按目录层级排列，完整显示所有备注
颜色	徽章 / 图标	可跟随 Git 文件状态变色（新增=绿，修改=黄，冲突=红，未跟踪=棕）

自动推断

首次打开项目时，插件根据 rules.json 中的规则自动添加备注。规则文件位于插件目录下，可自由编辑。

规则格式：

{
  "rules": [
    { "patterns": ["stores", "store"], "note": "状态管理", "match": "dir" },
    { "patterns": [".env"], "note": "环境配置", "match": "file_exact" },
    { "patterns": ["vite.config."], "note": "构建配置", "match": "file_prefix" }
  ]
}

match: "dir" — 匹配目录名
match: "file_exact" — 文件名精确匹配
match: "file_prefix" — 文件名前缀匹配

修改 rules.json 后，运行 「重新执行自动推断」 生效。

自定义规则路径

在 VS Code 设置中配置 fileNotes.rulesPath，指向自定义规则文件（支持绝对路径或相对工作区的路径）。留空使用内置 rules.json。

项目隔离

不同项目的备注独立存储（基于 VS Code workspaceState），切换项目不会互相影响。

绕过 .gitignore

自动推断时会直接扫描文件系统，捕获被 .gitignore 排除的文件（如 .env 文件）。

Windows 路径兼容

Windows 下路径比较不区分大小写，避免因 C:\Project vs c:\project 导致备注找不到。

配置项

打开 VS Code 设置 → 搜索「文件备注」：

配置项	类型	默认值	说明
`fileNotes.autoInfer`	boolean	true	启用自动推断
`fileNotes.autoInferOnStartup`	boolean	true	首次加载时自动推断
`fileNotes.useGitColors`	boolean	true	Git 状态联动颜色
`fileNotes.rulesPath`	string	""	自定义规则文件路径（留空使用内置）

开发

# 在 VSCode 中按 F5 启动调试
# 或打包
npx @vscode/vsce package

项目结构

├── extension.js        # 主入口
├── rules.json          # 自动推断规则（可编辑）
├── package.json        # 扩展配置
└── README.md           # 本文档

文件备注

chendragon