中文文档

VSCode Bookmark Manager

An intuitive and easy-to-use VSCode bookmark management extension that supports folder categorization, drag-and-drop, search, and project management. All operations align with your intuitive expectations.

Features

✨ Core Features

• 💨 No complex configuration needed - works out of the box with zero setup, making bookmark organization effortless
• 💨 All operations align with your intuitive expectations.
• 💨 Quick bookmark search
• 💨 Customize colors and icons
• 💨 Team Collaboration - Support Git version control, share bookmarks with team
• 💨 Import/Export - Support JSON format import and export
• 💨 Multi-root Workspace - Bookmark files across every folder of a multi-root workspace (e.g. engine source), stored portably for the whole team

🎯 Use Cases

• 💨 Onboarding New Team Members - Add bookmarks with notes to key code sections, helping newcomers quickly locate core logic
• 💨 Reading Large Codebases - Mark important functions, class definitions, configuration entries in complex projects
• 💨 Team Collaboration - Share bookmarks.json via Git, enabling team members to sync important code locations
• 💨 Bug Tracking - Mark problematic code, pending fixes, known issues for easier troubleshooting
• 💨 Learning Open Source Projects - Mark learning paths and key code sections when reading React, Vue, etc.
• 💨 Code Review - Mark code segments that need attention and potential risk points during reviews
• 💨 Refactoring Planning - Mark modules to refactor, technical debt locations, plan refactoring roadmap
• 💨 Documentation Writing - Mark example code locations and API implementations for documentation

Search

Keyboard Shortcuts ( The Only Configuration You Need to Remember )

Multi-root Workspace ( Cross-Folder Bookmarks )

In a multi-root workspace (a .code-workspace containing several folders — e.g. your project plus the engine source), you can bookmark files in any of the folders; they are all recorded in the project's bookmarks.json, grouped by the folder they belong to, and stored portably so the whole team can share them. A typical case: an Unreal Engine project where everyone wants to bookmark spots in the UE source.

How to use ( UE project example )

1. Add the extra directory as a folder in your workspace — File → Add Folder to Workspace — e.g. add UE5 next to your project. (This is VSCode's native multi-root workspace; no plugin-specific setup.)
2. Open any file inside that folder and press Ctrl/Cmd+Shift+B. The bookmark is automatically grouped under a node named after that folder (e.g. UE5).
3. Bookmarks in the first (primary) folder stay at the top level as before; bookmarks in other folders appear under their folder's node, where you can still create subfolders and drag to organize (drag never crosses folder boundaries).

Team-portable — a bookmark in another folder is stored as { "root": "UE5", "file": "Engine/Source/..." }: the folder name plus a relative path, never an absolute machine path. As long as each teammate's .code-workspace uses the same folder name (the actual path may differ per machine / OS), the shared bookmarks.json resolves on everyone's machine.

If you open only the primary folder (not the full .code-workspace), bookmarks that belong to other folders are shown under a ⚠️ node and can't be opened until you open a workspace that includes that folder.

The multi-root workspace

The bookmark view

Use it with your AI assistant

bookmarks.json is a plain, structured text file in your project — your AI coding assistant (Claude Code, Cursor, Copilot, etc.) can read and write it directly, and the extension watches the file so the view refreshes the moment the AI edits it. So there's no built-in AI to configure: just hand this "code map" to the assistant you already use.

Below is the prompt for your AI (it already contains the full schema, every field's meaning, the grounding rules, and an example) — copy the whole thing, then write your request right after it:

You are my coding assistant. I use the VSCode Bookmark Manager extension; its data is a file named bookmarks.json at the root of the PRIMARY workspace folder. Follow the spec below: read the real code first, then generate or update this file.

[How the file is used]
The extension reads bookmarks.json from the primary workspace folder (the first folder in a multi-root workspace) and renders the bookmarks as a tree grouped by folder and by workspace root. Clicking a bookmark opens the file and jumps to the line; if the line has shifted, it re-locates by lineContent. So fields must be accurate and come from the real file.

[Top-level shape]
{ "version": "3.1.0", "folders": [...], "bookmarks": [...] }

[folders[] item]
- id: unique string (you generate it; must not collide)
- name: folder name
- parentId: optional, parent folder id; omit for top level
- sortOrder: number, order within the same level (from 0)
- color: optional, one of red/orange/yellow/green/blue/purple
- icon: optional, a VSCode codicon name (e.g. folder, symbol-namespace, package)
- root: optional, see [Multi-root]

[bookmarks[] item]
- id: unique string
- name: bookmark name (concise; says what it is)
- file: path relative to its root, forward slashes /
- line: line number, 0-based (editor line 1 is 0 here)
- character: column, usually 0
- lineContent: the exact trimmed text of that line (see [Iron rules])
- folderId: optional, the folder it belongs to; omit if not in a folder
- sortOrder: number, order within its container
- color / icon: optional, as above
- root: optional, see [Multi-root]

[Multi-root (root)]
- File in the primary workspace folder: omit root; file is relative to that folder.
- File in another workspace folder (e.g. an engine folder named UE5): set "root": "UE5"; file is relative to the UE5 folder. root stores the WORKSPACE FOLDER NAME, not an absolute path, so it resolves on other machines too.

[Iron rules — most important]
1. Every bookmark must point to a real, existing code location — read the file to confirm, then write it.
2. lineContent must be the exact trimmed text of that line, copied verbatim, never invented or rewritten: the extension re-locates by it, so a wrong value jumps to the wrong line.
3. line must match the line that lineContent came from (0-based).
4. If you can't locate something, leave it out — never pad.
5. Output strict JSON: no comments, no trailing commas.

[When updating an existing file]
- Keep entries you weren't asked to change; only touch what must change.
- Re-check whether lineContent still matches the current code; clean up bookmarks pointing to deleted files/lines as requested.
- folderId/parentId must reference ids that actually exist.

[Example]
{
  "version": "3.1.0",
  "folders": [
    { "id": "f1", "name": "Auth", "sortOrder": 0, "color": "blue" }
  ],
  "bookmarks": [
    { "id": "b1", "name": "Login entry", "file": "src/auth/login.ts", "line": 41, "character": 0, "lineContent": "export async function login() {", "folderId": "f1", "sortOrder": 0 },
    { "id": "b2", "name": "FVector::Length", "root": "UE5", "file": "Engine/Source/Runtime/Core/Math/Vector.h", "line": 12, "character": 0, "lineContent": "float Length() const", "sortOrder": 0 }
  ]
}

[Output]
Write the final content to bookmarks.json at the root of the primary workspace folder.

Reorganizing, cleaning up dead bookmarks, re-anchoring after a refactor — all use the same prompt; just write a different request after it. Shared via Git, this lets the AI maintain a code map for the whole team.

vscode 书签 (Bookmark Manager)

一个零配置的 VSCode 书签管理插件，支持文件夹分类、拖拽、搜索、团队协作、项目管理。 所有的操作，都符合你的直觉预期。

功能特性

✨ 核心功能

• 💨 告别繁琐的配置，开箱即用，零配置，轻松分类书签
• 💨 所有的操作，都符合你的直觉预期。
• 💨 快速搜索书签
• 💨 自定义颜色和图标
• 💨 团队协作 - 支持 Git 版本控制，团队共享书签
• 💨 导入导出 - 支持 JSON 格式导入导出
• 💨 多根工作区 - 跨多根工作区的所有目录（如引擎源码）做书签，以可移植方式保存、全团队共享

🎯 应用场景

• 💨 指导新人快速了解项目 - 为关键代码添加书签和注释，新成员可通过书签快速定位核心逻辑
• 💨 阅读大型项目源码 - 在复杂代码库中标记重要函数、类定义、配置入口等关键位置
• 💨 团队协作标记 - 通过 Git 共享 bookmarks.json，团队成员同步查看重要代码位置
• 💨 Bug 追踪定位 - 标记问题代码、待修复位置、已知缺陷等，方便后续排查
• 💨 学习开源项目 - 阅读 React、Vue 等开源框架时，标记学习路径和重点代码
• 💨 代码审查 - Code Review 时标记需要关注的代码段、潜在风险点
• 💨 重构标记 - 标记待重构模块、技术债务位置，规划重构路线
• 💨 文档编写 - 为文档编写标记示例代码位置、API 实现等

搜索功能

快捷键 ( 唯一需要记住的配置 )

多根工作区（跨目录书签）

在多根工作区里（一个 .code-workspace 同时包含多个目录——比如你的项目 + 引擎源码），你可以给任意目录里的文件做书签，它们都会记录进项目的 bookmarks.json，按所在目录分组，并以可移植的方式保存，方便全团队共享。典型场景：UE（虚幻引擎）项目里，大家都想给 UE 源码里的位置做书签。

怎么用（以 UE 项目为例）

1. 把引擎目录作为文件夹加入工作区 —— 文件 → 将文件夹添加到工作区 —— 例如在项目旁边加上 UE5。（这是 VSCode 原生的多根工作区，无需插件额外设置。）
2. 打开该目录里的任意文件，按 Ctrl/Cmd+Shift+B。书签会自动归到一个以该文件夹名命名的节点下（如 UE5）。
3. 主目录（第一个工作区文件夹）里的书签照旧显示在顶层；其他目录的书签显示在各自的文件夹节点下，依然可以在其中新建子文件夹、拖拽整理（拖拽不会跨目录边界）。

团队可移植 —— 其他目录里的书签存成 { "root": "UE5", "file": "Engine/Source/..." }：文件夹名 + 相对路径，绝不含机器绝对路径。只要每个队友的 .code-workspace 用相同的文件夹名（实际路径可因机器 / 系统而异），共享的 bookmarks.json 就能在所有人机器上正确解析。

如果你只打开了主目录（而非完整的 .code-workspace），属于其他目录的书签会显示在一个 ⚠️ 节点下，需打开包含该目录的工作区后才能跳转。

多根工作区

书签界面

搭配 AI 助手使用

bookmarks.json 是项目里的一份纯文本结构化文件，你的 AI 编程助手（Claude Code / Cursor / Copilot 等）能直接读写它；插件监听该文件，AI 一改完视图就即时刷新。所以你不需要任何内置 AI —— 把这份"代码地图"交给你已有的助手来生成和维护就行。

下面是给你 AI 的提示词（已含完整 schema、每个字段的含义、grounding 铁律和示例）—— 整段复制给你的 AI，再在后面写上你的需求即可：

你是我的代码助手。我在用 VSCode 的 Bookmark Manager 插件，它的书签数据是「主工作区目录」根下的文件 bookmarks.json。请严格按下面的规范，先读取真实代码，再生成或更新这个文件。

【这个文件怎么被使用】
插件读取主工作区目录（多根工作区里的第一个文件夹）下的 bookmarks.json，把书签按文件夹和工作区根渲染成一棵树；点击书签会打开对应文件并跳到指定行——若该行位置变了，会用 lineContent 在附近重新定位。所以字段必须准确、且来自真实文件。

【顶层结构】
{ "version": "3.1.0", "folders": [...], "bookmarks": [...] }

【folders[] 每项】
- id: 唯一字符串（你生成，保证不重复）
- name: 文件夹名
- parentId: 可选，父文件夹 id；顶层不填
- sortOrder: 数字，同层级排序（从 0 起）
- color: 可选，取值之一 red/orange/yellow/green/blue/purple
- icon: 可选，VSCode codicon 名（如 folder、symbol-namespace、package）
- root: 可选，见【多根工作区】

【bookmarks[] 每项】
- id: 唯一字符串
- name: 书签名（简洁，说明这是什么）
- file: 文件路径，相对「所属根」，用正斜杠 /
- line: 行号，0 基（编辑器第 1 行在这里是 0）
- character: 列号，一般填 0
- lineContent: 该行去掉首尾空格后的真实文本（见【铁律】）
- folderId: 可选，所属文件夹 id；不放进文件夹就不填
- sortOrder: 数字，同容器内排序
- color / icon: 可选，同上
- root: 可选，见【多根工作区】

【多根工作区(root)】
- 文件在主工作区目录里：不写 root，file 相对该目录。
- 文件在另一个工作区目录里（如名为 UE5 的引擎目录）：写 "root": "UE5"，file 相对 UE5 目录。root 存的是「工作区文件夹名」而非绝对路径，这样别人机器上也能解析。

【铁律（最重要）】
1. 每个书签必须对应真实存在的代码位置——先读文件确认，再写。
2. lineContent 必须是该行的真实文本（去首尾空格），逐字照抄，绝不编造或改写：插件靠它重新定位，写错会跳到错误的行。
3. line 必须与 lineContent 所在那一行一致（0 基）。
4. 定位不到的就不写，不要为了凑数编一个。
5. 输出严格 JSON：不能有注释，不能有多余逗号。

【更新已有文件时】
- 没让你改的条目原样保留，只动需要变的部分。
- 重新核对 lineContent 是否还匹配当前代码；指向已删文件/已删行的按需求清理。
- folderId/parentId 必须引用真实存在的 id。

【示例】
{
  "version": "3.1.0",
  "folders": [
    { "id": "f1", "name": "认证", "sortOrder": 0, "color": "blue" }
  ],
  "bookmarks": [
    { "id": "b1", "name": "登录入口", "file": "src/auth/login.ts", "line": 41, "character": 0, "lineContent": "export async function login() {", "folderId": "f1", "sortOrder": 0 },
    { "id": "b2", "name": "FVector::Length", "root": "UE5", "file": "Engine/Source/Runtime/Core/Math/Vector.h", "line": 12, "character": 0, "lineContent": "float Length() const", "sortOrder": 0 }
  ]
}

【输出】
把最终内容写入主工作区目录根下的 bookmarks.json。

整理、清理失效书签、重构后重锚——都用同一段 prompt，在后面换成对应的需求即可。配合 Git 共享，等于让 AI 维护一份全队通用的代码地图。