在 VS Code、TRAE 和 JetBrains IDE 中，为仓库文件与目录添加可共享、可版本控制的代码备注。
- 两端读取同一份
.codebase-notes.json - 支持文件、目录、搜索、路径迁移和六种代码地图样式
- 备注可以随 Git 提交，团队切换编辑器也不会丢失上下文
- 界面支持英文和简体中文
当前版本：0.1.30
VS Code / TRAE：在扩展视图右上角菜单中选择 Install from VSIX...。
JetBrains IDE：打开 Settings / Preferences → Plugins，从齿轮菜单选择 Install Plugin from Disk...，直接选择 ZIP，无需解压。
运行要求：VS Code 1.107.0+，IntelliJ IDEA 2025.3+（build 253+）。
Project 视图直接在文件和目录后显示备注。
“代码备注”视图保留原生资源树交互，并单独渲染备注颜色；系统资源管理器的文件颜色不会被修改。
在项目树中右键文件或目录，打开“代码备注”菜单即可：
- 编辑或清除文字备注
- 设置备注样式
- 在系统资源管理器与“代码备注”之间切换定位
- 搜索备注或重新关联已移动的路径
选中文件或目录后，也可以用快捷键直接操作：
- VS Code / TRAE：
Option+R/Alt+R编辑备注，Shift+Option+R/Shift+Alt+R设置样式。 - JetBrains：
Option+R/Alt+R编辑备注，Shift+Option+R/Shift+Alt+R设置样式；如与 IDE 原生操作冲突，可在 Keymap 中删除或修改其中一个快捷键。
第一次保存备注时，插件会在项目根目录创建 .codebase-notes.json：
{
"version": 3,
"notes": {
"src": {
"_text": "源代码",
"App.ts": "前端主入口"
},
"scripts": { "_text": "双端工程入口", "_meta": { "style": "important" } }
}
}普通文件或没有已备注子项的目录直接使用字符串；目录同时有自身备注和子项时用 _text。样式和扩展属性按需放在 _meta 中，不增加普通备注的冗余字段。根目录备注写在 notes._text。
真实文件名以 _ 开头时，配置中额外加一个 _，例如 _text 文件写为 __text。_meta 必须与 _text 同时出现，不能在 _meta 中再写 text。
保存时采用紧凑排版：叶子备注保持单行，节点自身的 _text 与简单 _meta 合并一行，下级路径逐项展开；复杂元数据按需展开，不因文字长短自动折行。
当前只支持 v3 配置，不读取或迁移 v1/v2。两端使用相同格式；高于 3 的未来版本只读保护。
没有自身备注、且实际目录只含一个子目录的中间层会自动压缩，例如：
"src/test/java": {
"cn/geekyspace/springaidashscope": {
"integration": "集成测试",
"unit": "单元测试"
}
}/ 表示多级真实路径，. 仍是名称的一部分。各段独立进行下划线转义，例如 _private/_text 写为 __private/__text。新增中间备注或目录分支时拆开，删除后满足条件会重新合并；修改文字、样式以及重命名、移动时都重新维护结构。未备注的实际文件也会阻止合并，删除实体路径不会自动删除其失联备注。
在 .codebase-notes.json 的路径 key 上使用 Ctrl/Cmd＋点击，可以在 IDEA 项目树或 VS Code 资源管理器中定位；压缩 key 定位到末端目录，子项定位到对应的完整路径。IDEA 仅选中/展开目标，不打开源文件。配置有未保存编辑时，自动维护不会覆盖用户内容。
_meta.style |
用途 |
|---|---|
default |
普通：一般职责说明；保存时省略 style |
important |
重要（蓝色）：重要模块或工程入口 |
focus |
关注（黄色）：容易忽略的关系、约束或细节 |
core |
核心（红色）：项目主干，应该优先掌握 |
stable |
稳定（绿色）：唯一事实来源或可靠基准 |
extension |
扩展（紫色）：新增能力的接入位置 |
颜色用于构建代码地图，不表示错误或运行状态：红色看主干，黄色看细节，蓝色看重点，绿色找基准，紫色找扩展。 字符串备注或 _text 长度为 1～2000 个字符。
需要让 AI 初始化项目备注时，直接把 AI 初始化规范 交给它执行。
.codebase-notes.json 是唯一事实来源，建议提交到 Git。以下运行时文件应保持忽略：
.codebase-notes.json.lock
.codebase-notes.json.tmp.*| 工具 | 版本 |
|---|---|
| Node.js | 22 |
| npm | 随 Node.js 安装 |
| JDK | 21 |
| Git | 近期版本 |
git clone https://github.com/joeljhou/codebase-notes.git
cd codebase-notes
./deploy.sh init
./deploy.sh test首次构建 JetBrains 插件会下载 Gradle、IntelliJ Platform SDK 和 Maven 依赖，耗时会明显更长。
直接执行 ./deploy.sh 可以使用方向键菜单；自动化场景使用英文命令：
| 命令 | 作用 |
|---|---|
./deploy.sh init [all|vscode|jetbrains] |
初始化依赖与工程 |
./deploy.sh test [all|vscode|jetbrains] |
运行共享协议和平台测试 |
./deploy.sh build [all|vscode|jetbrains] |
构建插件 |
./deploy.sh package [all|vscode|jetbrains] |
将安装包汇总到 artifacts/ |
./deploy.sh clean [all|vscode|jetbrains] |
清理生成物 |
./deploy.sh version [新版本] |
查看或更新全局版本 |
根目录 VERSION 是双端唯一版本源。不要分别修改 VS Code 与 JetBrains 的插件版本。
VS Code：
cd src/vscode
npm run typecheck
npm test
npm run test:integration
npm run compile编译后可以用命令行启动 Extension Development Host：
code --new-window --extensionDevelopmentPath="$PWD" /absolute/path/to/test-projectTypeScript 修改后需要重新执行 npm run compile，再在测试窗口运行 Developer: Reload Window。
JetBrains：
cd src/jetbrains
./gradlew test
./gradlew runIde
./gradlew buildPlugin开发 Kotlin 时可以直接用 IntelliJ IDEA 打开 src/jetbrains，并将 Gradle JVM 设置为 JDK 21。
VERSION 双端唯一版本源
deploy.sh 初始化、测试、构建和打包入口
spec/ JSON Schema 与跨语言一致性用例
src/vscode/ TypeScript + VS Code 扩展
src/jetbrains/ Kotlin + JetBrains 插件
scripts/ 跨平台公共工程脚本
docs/platform/ 协议、实现、测试计划与设计评审
两个插件不共享运行时二进制，而是共享 Schema 与 spec/conformance 测试用例。修改跨编辑器行为时，推荐按以下顺序进行：
- 更新 Schema、协议或一致性 fixture。
- 分别实现 VS Code 与 JetBrains 行为。
- 运行
./deploy.sh test。 - UI 或宿主集成有变化时，再运行对应的集成测试。
- 使用
./deploy.sh version更新版本并重新打包。
源码修改后没有生效：VS Code 重新执行 npm run compile 并 Reload Window；JetBrains 停止后重新执行 ./gradlew runIde。
插件已安装但没有配置文件：只有第一次保存备注时才会创建 .codebase-notes.json。
看不到完整备注文字：VS Code 的完整备注显示在“代码备注”视图；系统资源管理器保持原生显示。
项目采用 MIT License。产品思路参考 Link-Kou/intellij-treeInfotip，跨编辑器协议、并发写入、路径事件与 UI 适配为独立实现。