# File Remark **Repository Path**: Li-jinhu/file-remark ## Basic Information - **Project Name**: File Remark - **Description**: 为 IntelliJ IDEA 中的文件、目录和 Java 方法添加中文备注，通过分组管理，让大型项目一目了然。 - **Primary Language**: Unknown - **License**: CC-BY-SA-4.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-07-01 - **Last Updated**: 2026-07-01 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # File Remark Plugin - 文件/方法备注插件 ## 简介 为 IntelliJ IDEA / JetBrains IDE 开发的备注管理插件，支持对项目中的**文件、目录、甚至具体方法**添加中文备注，并通过分组进行组织管理。 ### 功能特性 | 功能 | 说明 | |------|------| | 📝 右键添加备注 | 项目视图中右键文件/目录即可添加备注；编辑器内可添加方法备注 | | 🌲 三级树侧边栏 | 分组 → 文件 → 方法，层级化展示所有备注，方法备注显示「类名-方法名」两行格式 | | 🔬 方法级备注 | 支持对 Java 方法添加备注，编辑器内 **inline 显示在方法上方** | | 🏷️ 自动识别类型 | 备注类型（文件/方法）由插件自动检测，只读展示，无需手动选择 | | 📁 分组管理 | 创建/重命名/删除分组，备注可在分组间移动（仅文件/文件夹备注） | | ✏️ 统一对话框 | 左侧项目树和右侧侧边栏使用相同的编辑对话框，均支持分组选择 | | 💾 数据持久化 | 备注保存到项目 `.remark/DirectoryV3.xml`，自动迁移旧数据 | | 🔍 搜索过滤 | 顶部搜索框实时过滤备注、路径、方法名 | | 🚀 双击跳转 | 双击备注自动定位到对应文件或方法定义行 | | 📌 置顶高亮 | 重要备注置顶显示，橙色背景凸显 | | 🌳 项目树提示 | 文件节点后显示备注内容和方法备注数量 | | ☑️ 完全兼容 | 兼容已有的 `DirectoryV3.xml` 内容；兼容 IntelliJ IDEA **2024 / 2025 / 2026** | --- ## 快速开始 ### 环境要求 - **JDK**: 17 - **IDE**: IntelliJ IDEA 2024+ / WebStorm / PyCharm 等 JetBrains IDE ### 构建插件 ```bash cd d:\project\project_ide # Windows .\gradlew.bat buildPlugin # Linux/macOS ./gradlew buildPlugin ``` 默认构建产物位于: `build/distributions/file-remark-plugin(2025+)-3.2.6.zip` ### 安装插件 1. 打开 IntelliJ IDEA 2. 进入 **Settings → Plugins → ⚙️ → Install Plugin from Disk...** 3. 按 IDEA 版本选择安装包：2025 之前版本选择 `build/distributions/file-remark-plugin(2025-)-3.2.6.zip`，2025 之后版本选择 `build/distributions/file-remark-plugin(2025+)-3.2.6.zip` 4. 重启 IDE ### 打包发布 提供两种打包方式： **方式一：使用打包脚本（推荐，Windows 一键打包）** 双击 `build.bat`，脚本会自动清理旧构建 → 连续编译两个版本 → 输出 ZIP 路径和文件大小。 **方式二：手动 Gradle 命令** ```bash # 一次生成两份安装包（推荐） .\gradlew.bat buildAll --no-daemon # 只打包 2025 之后版本（IDEA 2025+ ~ 2026.x+） .\gradlew.bat clean buildPlugin --no-daemon -Ptarget=2025+ # 只打包 2025 之前版本（IDEA 2024.x） .\gradlew.bat clean buildPlugin --no-daemon -Ptarget=2025- # 产物路径 # build/distributions/file-remark-plugin(2025+)-3.2.6.zip # build/distributions/file-remark-plugin(2025-)-3.2.6.zip ``` **发布到 JetBrains Marketplace（可选）** ```bash # 1. 先验证插件配置是否合法 .\gradlew.bat verifyPlugin # 2. 打包并上传到 Marketplace（需配置 PUBLISH_TOKEN） .\gradlew.bat publishPlugin ``` > **提示**：打包前确认 `build.gradle` 中的 `version`、`plugin.xml` 中的 `` 保持一致。 ### 调试运行（开发时） ```bash # 调试 IDEA 2024.2 环境 .\gradlew.bat runIde2024_2 # 调试 IDEA 2026 环境 .\gradlew.bat runIde2026 # 如果 IDEA 2026 安装目录不同，可以显式指定 .\gradlew.bat runIde2026 -Pidea2026Home=D:\path\to\idea-2026 ``` 两个调试命令使用独立 sandbox，避免不同 IDEA 调试环境共用配置、缓存和已安装插件。项目默认仍使用 2024.2 SDK 编译插件，`runIde2026` 会先准备插件 sandbox，再直接启动本机 IDEA 2026 安装目录，避开旧版 Gradle IntelliJ Plugin 对 IDEA 2026 启动参数的兼容问题。 --- ## 使用指南 ### 添加备注 #### 文件/文件夹备注 1. 在左侧 **Project** 面板中，右键点击文件或目录 2. 选择 **「添加备注」** 或 **「修改备注」** 3. 弹窗自动识别类型为「文件/文件夹备注」（只读展示） 4. 选择所属分组（默认「未分组」） 5. 输入备注内容，点击 **OK** 保存 #### 方法备注 1. 在编辑器中，将光标置于目标方法内，或选中方法名 2. 右键 → 选择 **「添加方法备注」** 3. 弹窗自动识别类型为「方法备注」，显示方法名（只读） 4. 输入备注内容，点击 **OK** 保存 5. 备注 **立即以灰色文字 inline 显示在方法上方** > **注意**：方法备注跟随所属文件/类，不参与独立分组选择。 ### 编辑器内联展示（Inlay） - 方法备注在编辑器中以 **Block Inlay** 形式显示在方法声明（或其注解）上方 - 字体与编辑器一致，普通样式（非斜体），缩进与方法对齐 - 支持多行备注自动换行，不会与代码重叠 - 左侧 gutter 区域显示备注图标 ### 三级树侧边栏 - **打开侧边栏**: 右侧边栏找到 **FileRemark** 图标 - **树结构**: - 分组节点：加粗显示分组名称 - 文件节点：`文件名 - 备注摘要` 格式（取第一行，按面板宽度自动截断） - 方法节点：第一行 `类名-方法名`，第二行 `备注摘要`（灰色） - **分组管理**: 右键分组节点 → 重命名/删除分组 - **备注操作**: 右键备注节点 → 跳转/编辑/置顶/移动到分组/删除 - **搜索**: 顶部搜索框输入关键词，实时过滤 - **刷新**: 点击右上角刷新按钮重新加载；刷新后可选择检查失效备注（文件/方法不存在时批量清理） ### 右键菜单操作 | 操作 | 说明 | |------|------| | 跳转到文件 | 在项目树中定位并选中文件，同时在编辑器中打开；方法备注进一步跳转到方法定义行 | | 编辑备注 | 弹出统一编辑对话框（含分组选择） | | 置顶/取消置顶 | 重要备注置顶显示（仅文件/文件夹备注支持） | | 移动到分组 | 将备注移动到指定分组（支持新建分组） | | 删除备注 | 移除备注（同时从 XML 中删除） | > **智能逻辑**： > - 备注内容为空时，自动视为 **删除操作** > - 已有备注时，标题自动变为 **"修改备注"** ### 分组管理 - **新建分组**: 侧边栏顶部「+」图标按钮，或弹窗中「＋ 新建分组…」选项 - **重命名分组**: 右键分组节点 → 「重命名分组」 - **删除分组**: 右键分组节点 → 「删除分组」（分组下的备注自动移回「未分组」） ### 置顶备注显示 - 置顶备注显示在分组最顶部 - 使用橙色背景高亮 + 加粗文字 - 树节点后缀显示 `[置顶]` --- ## 数据格式 `DirectoryV3.xml` 完全兼容以下格式，并扩展支持方法备注和分组： ```xml ``` ### 字段说明 | 属性 | 必填 | 说明 | |------|------|------| | `path` | 是 | 相对于项目根目录的路径（以 `/` 开头）；`type=group` 时为分组名称 | | `title` | 是 | 备注文本（支持 `\n` 换行） | | `type` | 否 | 类型：`file`（默认）/ `method` / `group` | | `method` | 否 | `type=method` 时有效，方法签名（如 `getUserById(String)`） | | `group` | 否 | 所属分组名称，空或省略表示「未分组」（方法备注通常不设置） | | `pinned` | 否 | 是否置顶（仅 `type=file` 有效），`true` 时显示在列表最顶部，橙色高亮 | | `textColor` | 否 | 文本颜色（十六进制，如 `#FF6600`） | | `backgroundColor` | 否 | 背景颜色（十六进制，如 `#FFF3E0`） | | `extension` | 否 | 扩展信息 | | `presentableText` | 否 | 展示文本 | | `tooltipTitle` | 否 | 悬浮提示 | | `icon` | 否 | 图标 | --- ## 项目结构 ``` file-remark-plugin/ ├── build.gradle # Gradle 构建配置 ├── settings.gradle ├── gradle/ │ └── wrapper/ ├── gradlew.bat / gradlew # 构建脚本 └── src/main/ ├── java/com/ideplugin/remark/ │ ├── action/ │ │ └── AddRemarkAction.java # 右键菜单 Action + 统一编辑对话框 + 方法参数自动检测 │ ├── model/ │ │ └── RemarkItem.java # 数据模型（file/method/group） │ ├── service/ │ │ ├── RemarkService.java # 服务接口 │ │ └── impl/RemarkServiceImpl.java # XML 读写实现 │ ├── panel/ │ │ ├── RemarkPanel.java # 侧边栏主面板（三级 JTree + 跳转/编辑/删除） │ │ ├── RemarkTreeCellRenderer.java # 树节点渲染器（文件/方法摘要展示） │ │ ├── RemarkListCellRenderer.java # 列表单元格渲染器 │ │ └── RemarkToolWindowFactory.java # 工具窗口工厂 │ ├── decorator/ │ │ ├── FileRemarkNodeDecorator.java # 项目树装饰器（显示备注提示） │ │ └── FileRemarkDecorator.java # 装饰器工具类 │ ├── marker/ │ │ ├── MethodRemarkLineMarkerProvider.java # 方法 gutter 图标 │ │ └── MethodRemarkInlayRenderer.java # 方法 Inlay 渲染（核心，支持 /** */ 格式 + 行间距） │ ├── provider/ │ │ └── FileRemarkTreeStructureProvider.java # 树结构提供者 │ ├── listener/ │ │ ├── RemarkStartupActivity.java # 启动活动（初始化渲染器） │ │ └── XmlFileChangeListener.java # XML 文件变更监听 │ └── util/ │ └── RemarkNotifier.java # 消息总线通知 └── resources/ ├── META-INF/plugin.xml # 插件配置 ├── inlay-style.properties # Inlay 样式配置（颜色/字体/行间距） └── icons/ # 图标资源 ``` --- ## 常见问题 - **Q: 方法备注如何跳转？** A: 双击侧边栏中的方法备注，会同时打开文件 **并定位到方法定义行**。 - **Q: 方法备注为什么没有分组选项？** A: 方法备注跟随其所属文件/类的分组，不需要单独设置分组。 - **Q: 如何区分文件备注和方法备注？** A: 插件会根据上下文自动判断：在项目树中右键 → 文件备注；在编辑器中光标在方法内 → 方法备注。弹窗顶部会只读显示当前类型。 - **Q: 备注内容清空会发生什么？** A: 点击 OK 后自动执行删除操作，无需额外步骤。 - **Q: 分组数据存在哪里？** A: 分组以 `type="group"` 的形式保存在 `DirectoryV3.xml` 中，与文件备注共存。 - **Q: 插件支持哪些 IDE 版本？** A: 兼容 IntelliJ IDEA **2024、2025 和 2026** 版本。 --- ## 更新日志 ### v3.2.6 (2026-07-01) - **新增**：设置页改为左侧页签 + 右侧内容布局，包含「Gitee 设置」和「其他功能」。 - **新增**：「其他功能」中增加 `.remark` 文件夹排除开关，默认不排除，保存到当前项目 `.remark/config.properties`。 - **新增**：「其他功能」中增加调试日志开关，默认关闭，开启后才写入 `.remark/file-remark-yyyy-MM-dd.log`。 - **优化**：右侧 FileRemark 面板顶部改为靠左图标工具条，移除标题文字和文件夹图标，「+分组」改为「+」图标按钮并增加悬浮提示。 - **修复**：`runIde2026` 改为准备独立 sandbox 后直接启动本机 IDEA 2026，避开旧版 Gradle IntelliJ Plugin 对 IDEA 2026 启动参数的兼容问题。 ### v3.2.5 (2026-06-30) - **修复**：Gitee `getFile` 接口返回 JSON 数组时不再按文件对象强制解析，避免 IDEA 报 `Not a JSON Object: []` - **优化**：Gitee 文件读取响应增加 JSON 类型判断和截断日志，远端路径不是文件时按“远端文件不存在”处理，后续可继续首次推送/创建流程 ### v3.2.4 (2026-06-15) - **修复**：IDEA 2026 打开备注工具窗口时偶发 `Write-unsafe context` 异常，移除 XML 加载/查找链路中的隐式 VFS refresh - **修复**：备注树跳转文件时找不到目标后再次触发 VFS refresh 的潜在写安全风险 - **优化**：XML 读取增加磁盘兜底逻辑，VFS 暂未看到 `.remark/DirectoryV3.xml` 时仍可加载备注数据 - **优化**：调试日志改为 `.remark/file-remark-yyyy-MM-dd.log`，只写当天日志，并自动清理历史日志 ### v3.2.3 (2026-06-15) - **新增**：项目内调试日志，记录启动、XML 查找/加载、刷新按钮、树刷新和 XML 文件监听关键链路，方便排查偶发问题 - **新增**：`skills/directoryv3-xml-writer/SKILL.md`，沉淀 DirectoryV3.xml 写入规范，便于交给其他 AI 安全写入备注 - **修复**：多 Project 窗口下偶发不加载 XML、刷新按钮无效的问题，项目级服务改为按 `Project` 对象隔离 - **修复**：方法备注保存完整签名并兼容旧方法名数据，降低重载方法备注串号风险 - **修复**：XML 属性读取增加反转义，避免 `&` 等内容重复转义 - **修复**：注册 DirectoryV3.xml 文件变化监听，外部修改后可触发缓存和界面刷新 - **修复**：Gitee 仓库未初始化错误不再被吞掉，便于给出明确提示 - **优化**：项目树右键备注入口上移到菜单顶部 - **优化**：Gitee 默认分支统一为 `master` ### v3.2.1 (2026-05-15) - **修复**：兼容 IntelliJ IDEA 2025（IC-252+）版本，扩展 `untilBuild` 至 253.* ### v3.2.0 (2026-05-12) - **新增**：刷新按钮增加失效备注检查 — 刷新后可选择检测文件/文件夹/方法是否仍存在，确认后批量清理失效备注 ### v3.1.0 (2026-05-12) - **新增**：同步脏标记（`.remark/.sync-pending`）— 推送成功自动删除，文件在=脏数据，文件不在=已同步 - **新增**：网络失败 3 次重试（指数退避 1s/2s/4s）+ 补偿冷却机制（5分钟冷却期） - **新增**：面板底部同步状态小字 — ✅同步完成 / 🔄同步中... / ⚠️同步冲突 / ❌同步失败 - **新增**：v2→v3 迁移成功通知 - **新增**：ask 冲突策略在启动拉取时弹出 IDE Notification 引导处理 - **优化**：JSON 解析从正则改为 gson，避免特殊字符解析失败 - **优化**：同步操作线程安全 — schedulePush/init 使用线程池，状态更新回到 EDT ### v3.0.0 (2026-05-12) - **新增**：Gitee 云同步 — 本地优先 + 异步推送，多设备共享备注数据 - **新增**：右侧面板 ⚙ 设置按钮，点击即可配置云同步参数（Token、仓库、项目名等） - **新增**：项目名标识仓库隔离 — Gitee 按 `remarks/项目名/子项目.xml` 组织，同一项目的不同端在同一文件夹下 - **新增**：项目迁移支持 — 基于项目名标识而非路径hash，搬家后重新配置同名即可复用远端数据 - **新增**：冲突解决策略 — 支持"每次询问/自动合并/本地优先/远端优先"四种策略 - **新增**：v2.x 自动迁移 — 首次启动自动将根目录 `DirectoryV3.xml` 迁移到 `.remark/` 目录 - **新增**：防抖推送 — 本地保存后延迟 3 秒异步推送，避免频繁 API 调用 - **优化**：备注数据统一存储到 `.remark/DirectoryV3.xml`，与项目文件隔离 - **优化**：Token 使用 PasswordSafe 加密存储，不明文写入配置文件 - **优化**：设置对话框支持"选择已有项目"（从 Gitee 列出已有目录） - **优化**：远端路径预览，配置时实时显示数据在 Gitee 上的存储位置 ### v2.0.6 (2026-05-12) - **优化**：方法备注在侧边栏中显示为两行格式 — 第一行 `类名-方法名`，第二行灰色备注摘要 - **优化**：备注文本根据面板宽度动态截断，超出部分用 `...` 显示（替代原先固定字符数截断） - **优化**：方法备注鼠标悬浮提示显示「类名/方法/备注」三行，备注内容保留折行 - **修复**：双击跳转经常失效的问题 — 将双击检测从 `mouseClicked` 改为 `mousePressed`，避免鼠标微动导致事件丢失 - **新增**：导航跳转相关逻辑添加详细日志（通过 IDEA 日志系统查看），方便排查跳转问题 ### v2.0.5 (2026-04-28) - **新增**：双击跳转时，文件或方法找不到 → 弹窗提示是否删除，支持勾选"不再提示"后自动删除 - **优化**：右键菜单"添加备注"按钮位置上移至第二位（紧随 New 菜单组之后） - **修复**：方法备注参数自动填充在 PSI 不可用时失效的问题（增加文本正则降级方案） ### v2.0.4 (2026-04-28) - **新增**：方法备注自动填充 `@param` / `@return` 模板，根据方法参数自动生成 - **新增**：Inlay 显示自动包裹 `/** */` 注释格式 - **新增**：备注输入框支持 Tab 键插入 4 空格 - **优化**：Inlay 备注颜色改为橙色（Light: `#CC7A30`，Dark: `#D99B60`） - **新增**：`inlay-style.properties` 支持行间距配置（`line.spacing`） ### v2.0.3 (2026-04-25) - **优化**：侧边栏树节点图标区分 — 分组（ModuleGroup）、文件夹（Folder）、文件（Text）、方法（Method）四种不同图标 - **修复**：修复调试模式下侧边栏工具窗口图标异常巨大问题（SVG width/height 从 200px 修正为 13px） - **优化**：简化 ToolWindowFactory 图标逻辑，去掉版本分支判断 ### v2.0.2 (2026-04-25) - **重构**：对话框去掉文件/方法 RadioButton 选择，改为自动检测类型、只读展示 - **优化**：左侧项目树和右侧侧边栏使用统一的编辑对话框（均支持分组选择） - **优化**：侧边栏树中文件节点显示 `文件名 - 备注摘要` 格式（不再只显示文件名） - **修复**：修复 IntelliJ 2023 版本刷新按钮图标显示为文件夹的问题（改用 AllIcons.Actions.Refresh） ### v2.0.1 (2026-04-24) - **新增**：方法备注编辑器内 **inline 显示**（Block Inlay），显示在方法/注解上方 - **新增**：方法 gutter 图标（LineMarker），双击可快速定位 - **优化**：Inlay 渲染支持字体大小对齐、缩进对齐、多行换行不重叠 - **优化**：已有备注再次编辑自动进入修改模式（预填内容和分组） - **修复**：修复方法备注添加后 Inlay 不显示的问题（改为项目单例 + 消息总线通知） - **修复**：修复方法 gutter 双图标问题（清理重复 LineMarker 创建） - **修复**：备注内容为空时自动执行删除操作 ### v1.0.2 (2026-04-24) - **新增**：三级树侧边栏（分组 → 文件 → 方法） - **新增**：方法级备注功能（右键添加，自动识别光标所在方法） - **新增**：备注分组管理（新建/重命名/删除分组，备注跨分组移动） - **新增**：项目树文件节点显示方法备注数量提示 - **新增**：搜索支持方法名过滤 - **优化**：侧边栏 UI 改为 JTree，支持折叠/展开 ### v1.0.1 (2026-04-24) - 修复插件 logo 不显示的问题（插件管理页面和侧边栏按钮） - 清理所有调试日志，只保留异常打印 - 修正文档中文件名错误 ### v1.0.0 (2026-04-24) - 初始版本发布 - 右键添加备注 - 右侧侧边栏管理 - 搜索、置顶、删除 - 双击跳转定位 - 兼容 `DirectoryV3.xml` 格式 --- ## 联系作者 有问题可以评论，或者与我联系 邮箱：LiJH_0424@163.com