免费开源MIT 许可证IntelliJ IDEA 2025.1–2026.2

给 SQL 和 HTTP 文件一份目录

Name: Code Comment Navigator
Availability: InStock
Author: Fuuqiu

把注释里的 Markdown 标题——SQL 的 -- # 标题、HTTP 的 // # 标题——变成 IntelliJ IDEA 右侧可折叠的 Comment Outline，点击标题就跳到对应注释行。项目文件和 Scratches 里越写越长的迭代脚本都适用。

从 JetBrains Marketplace 安装复制 AI Skill

版本 1.2.4 · MIT 许可证 · 本地运行，不含网络代码 · IntelliJ IDEA 2025.1–2026.2

Scratches and Consoles

orders.sql

-- # 订单分析
-- 统计口径：已支付订单，按下单日期。

-- ## 按日汇总
SELECT DATE(o.created_at) AS order_date,
       COUNT(*)           AS order_count,
       SUM(o.amount)      AS total_amount
FROM orders o
WHERE o.status = 'PAID'
GROUP BY DATE(o.created_at)
ORDER BY order_date DESC;

-- ## 按用户汇总
/*
 * ### 复购用户
 */
SELECT o.user_id, COUNT(*) AS order_count
FROM orders o
GROUP BY o.user_id
HAVING COUNT(*) > 1;

-- # 用户画像
-- ## 活跃用户

Comment Outline

orders.sql

订单分析
按日汇总
按用户汇总
复购用户
用户画像
活跃用户

Scratches

Scratches and Consoles › orders.sql 4:1 LFUTF-8SQL

一行命令，让你的 AI 写出自带大纲的文件

把这份 Skill 装进你常用的 AI 工具，它生成的 SQL 和 HTTP 文件会用简短的注释标题组织，打开就能在 Comment Outline 里点击跳转。

Claude Code

mkdir -p ~/.claude/skills/comment-navigator && curl -fsSL https://commentnavigation.plugins.topxup.com/skills/zh/comment-navigator/SKILL.md -o ~/.claude/skills/comment-navigator/SKILL.md

在终端执行，SKILL.md 会保存到 Claude Code 的个人 Skill 目录。

Codex

mkdir -p ~/.codex/skills/comment-navigator && curl -fsSL https://commentnavigation.plugins.topxup.com/skills/zh/comment-navigator/SKILL.md -o ~/.codex/skills/comment-navigator/SKILL.md

在终端执行，SKILL.md 会保存到 Codex 的 Skill 目录。

Cursor

mkdir -p .cursor/rules && curl -fsSL https://commentnavigation.plugins.topxup.com/skills/zh/comment-navigator/SKILL.md -o .cursor/rules/comment-navigator.mdc

在项目根目录执行，保存为 Cursor 的项目规则文件。

通用粘贴

下载 SKILL.md

粘贴到对话开头，再描述你的需求。

AI 默认写法 → 用 Skill 之后

AI 默认写法装饰横线、手写编号、逐句复述代码

-- ============================
-- 1. 查询订单
-- ============================
-- 这个查询用于查询订单表中的数据，
-- 按天统计订单数量和订单金额，
-- 只统计已经支付的订单。
SELECT DATE(created_at) AS day, COUNT(*), SUM(amount)
FROM orders
WHERE status = 'PAID'
GROUP BY DATE(created_at);

用 Skill 之后两行标题，就是 Comment Outline 里的两级节点

-- # 订单分析
-- ## 按日汇总已支付订单
SELECT DATE(created_at) AS day,
       COUNT(*)    AS order_count,
       SUM(amount) AS total_amount
FROM orders
WHERE status = 'PAID'
GROUP BY DATE(created_at);

查看完整 Skill

---
name: comment-navigator
description: Generate or organize SQL and JetBrains HTTP Client .http/.rest files with Markdown headings inside comments for Code Comment Navigator. Use when the user requests an outline-ready SQL script, API request file, or Scratch file. This skill does not execute SQL or send requests.
---

# Code Comment Navigator file conventions

Preserve the requested SQL dialect, API contract, variables, business logic, and content language. When reorganizing a file, preserve query semantics, request order, and pre/post-request scripts. Verify missing schema or API details; use explicit placeholders in examples and never invent real credentials.

## Outline structure

- Use 1–6 hashes for heading levels, followed by a space and a non-empty title.
- Use business domain, operation/query, and scenario groups only as needed. Prefer consecutive levels and short, distinguishable titles. Siblings keep file order.
- Add headings to meaningful sections, not every explanatory line. Use ordinary comments for ordinary notes.
- With explicit headings, ordinary comments stay out of the outline. Without headings, the plugin falls back to a flat comment list. Skipped levels attach to the preceding shallower heading.

## Keep files concise

- Replace decoration with headings. Do not generate `====`, `----`, asterisk borders, ASCII banners, or a hand-written table of contents. Preserve HTTP `###` request separators.
- Give each independently useful query or request scenario one short heading. Add shared groups only where useful; 1–3 levels usually suffice. Do not stack synonymous domain/operation/scenario headings or annotate every statement, field, or step.
- Titles name the query, operation, or scenario. Keep lengthy explanations, line numbers, and section numbering out of headings. At the top, include only necessary purpose and prerequisites, not the full requirements, API documentation, change history, or business specification.
- Ordinary comments explain what code cannot: business definitions, units, time zones, dependencies, significant side effects, or expected results. Prefer 1–2 nearby lines. Do not narrate obvious code; use clear parameter names and column aliases.
- Put detailed procedures, formula derivations, and verification reports in the conversation or existing user documentation. Create companion documentation only when needed by the user. Preserve constraints, transaction/request dependencies, and warnings needed for correct use.
- When organizing old files, replace numbered chapter banners with explicit headings and remove repetitive prose. Retain at least one meaningful explicit heading so ordinary comments do not all become fallback outline entries. Preserve execution order, parameters, and semantics.

## SQL

Prefer standalone `-- # Heading`, `-- ## Heading`, and `-- ### Heading` lines. Headings inside `/* ... */` comments also work, including lines prefixed with `*`. Do not put headings after a SQL statement on the same line. MySQL `#` line comments are also supported: `# Plain note` appears in the fallback outline when no explicit headings exist. Use `# # Level one` and `# ## Level two` for headings: the first hash is the comment marker, and the remaining hashes define the Markdown level. When explicit headings exist, ordinary notes stay out of the outline. Hashes inside strings are not headings. Prefer `--` for other SQL dialects; do not change dialect syntax just to standardize formatting.

```sql
-- # Order analytics
-- ## Daily paid orders
SELECT CAST(paid_at AS DATE) AS paid_date,
       COUNT(*) AS order_count,
       SUM(total_amount) AS paid_amount
FROM orders
WHERE status = 'PAID'
GROUP BY CAST(paid_at AS DATE)
ORDER BY paid_date;

-- ## Missing payment timestamps
SELECT id FROM orders WHERE status = 'PAID' AND paid_at IS NULL;
```

For long scripts, use relevant sections such as schema, indexes, seed data, migrations, and analytical queries. Do not add unrelated SQL to inflate length. Preserve transaction boundaries and dependency order.

## JetBrains HTTP Client (.http / .rest)

Prefer an empty `###` request separator, followed by `// # Heading` through `// ###### Heading`, then the request line. The `# # Heading` form is also supported.

**After a JSON or other request body, place the next section's headings AFTER the next `###` separator.** Never place the next request's comments between the previous body and its following separator: the IDE can interpret them as part of that body. Separate headers from the body with a blank line. JSON must contain no comments or trailing commas.

```http
@host = https://example.invalid

###
// # Orders API
// ## Create order
POST {{host}}/orders
Content-Type: application/json

{
  "skuId": 1001,
  "quantity": 2
}

###
// ## Find order by ID
GET {{host}}/orders/example-order-id
Accept: application/json
```

This example demonstrates formatting; the host and resource ID are placeholders. Use existing project environment variables, authentication, and API contracts for actual output.

- `### Request name` is a native request separator and always produces a level-2 outline node, not a level-3 Markdown heading. For precise nesting, use an empty `###` plus `// ### Heading`; mixing the forms can change parent relationships.
- An empty `###` does not create an outline node. Do not change request boundaries just to create outline entries.
- Comments inside `< {% ... %}` pre-request and `> {% ... %}` response-handler scripts are excluded from the outline. Keep scripts attached to their requests and put the next section's headings after the next separator.
- Use existing variables or placeholders for authentication; never embed tokens or passwords in examples.

## Before delivery

1. Check that SQL headings occupy standalone comment lines and HTTP headings follow the corresponding separator. Each heading needs a space and a title.
2. Check every HTTP request boundary, especially after bodies. Validate JSON and preserve script-to-request associations.
3. Remove decorative banners, duplicate tables of contents, obvious narration, and synonymous heading stacks. Preserve necessary business definitions and warnings.
4. Check the intended business hierarchy, SQL dialect, statement semantics, transactions, and API contracts.
5. Return the complete requested files or requested edits. Do not claim SQL or requests were executed unless they were; this skill itself does not authorize execution.

Open the files with the plugin, inspect the right-hand **Comment Outline**, and click headings to verify navigation. If the environment cannot operate the IDE, say this check remains unperformed.

References: [Plugin source and examples](https://github.com/fuuqiu/CommentNavigation) · [JetBrains HTTP syntax](https://www.jetbrains.com/help/idea/exploring-http-syntax.html)

---
name: comment-navigator
description: 当用户要求生成或整理适配 Code Comment Navigator 的 SQL、JetBrains HTTP Client .http/.rest 文件时，使用注释中的 Markdown 标题组织可导航的大纲。适用于长 SQL 脚本、接口调试文件和 Scratches；不用于执行 SQL 或发送请求。
---

# Code Comment Navigator 文件规范

生成或整理文件时，保留用户要求的 SQL 方言、接口协议、变量和业务逻辑，采用用户指定的内容语言。只调整组织方式时，不改变查询语义、请求顺序或前后置脚本。缺少表结构或接口定义时先核实；示例使用明确的占位值，不编造真实凭据。

## 大纲组织

- 用 1–6 个 `#` 表示层级，标记后必须有空格和非空标题。
- 按需要选择业务域、操作/查询或场景分组，优先连续层级，标题简短且可区分。同级按文件顺序展示。
- 只给有意义的章节加标题，不把每行说明变成大纲节点。普通说明使用普通注释。
- 有显式标题时，普通注释不进入大纲；没有标题时才回退到普通注释列表。跳级标题会挂在前一个更浅的标题下。

## 保持文件简洁

- 用标题替代装饰：不生成 `====`、`----`、星号边框、ASCII 横幅或手写目录；HTTP 的 `###` 请求分隔符必须保留。
- 每个可独立定位的查询或请求场景只写一个简短标题；按需要增加共享分组，通常 1–3 级足够。不要为了凑齐“业务域 → 操作 → 场景”连续写同义标题，也不要为每条 SQL、每个字段或每行操作加注释。
- 标题写“查什么 / 做什么 / 哪种场景”，不在标题中堆放长解释、行号或章节编号。文件开头最多保留必要的用途与执行前提，不复制整份需求、接口文档、变更历史或完整业务说明。
- 普通注释只解释代码看不出的业务口径、单位、时区、前置依赖、重要副作用或预期结果，尽量就近用 1–2 行说明。代码已表达的步骤不再复述，参数名和列别名优先做到自解释。
- 详细使用步骤、公式推导、验证报告等放在对话回复或用户已有文档中；只有用户需要时再创建配套文档。精简时保留影响正确使用的约束、事务/请求依赖与风险提示。
- 整理旧文件时，将原来的编号章节或分隔线替换成显式标题，删除重复叙述；至少保留一个真实的显式标题，避免无标题时全部普通注释回退为大纲。保留执行顺序、参数和业务语义。

## SQL

优先使用独立行的 `-- # 标题`、`-- ## 标题`、`-- ### 标题`。也支持 `/* ... */` 内的标题（允许行首 `*`），但不要把标题放在 SQL 语句末尾。MySQL 方言也支持 `#` 行注释：`# 普通说明` 在无显式标题时参与普通注释大纲；层级标题写成 `# # 一级标题`、`# ## 二级标题`，第一个 `#` 是注释符，后面才是 Markdown 层级。有显式标题时仍只展示标题。字符串中的 `#` 不作为标题；其他 SQL 方言优先沿用 `--`，不为统一格式更换方言语法。

```sql
-- # 订单分析
-- ## 按日汇总已支付订单
SELECT CAST(paid_at AS DATE) AS paid_date,
       COUNT(*) AS order_count,
       SUM(total_amount) AS paid_amount
FROM orders
WHERE status = 'PAID'
GROUP BY CAST(paid_at AS DATE)
ORDER BY paid_date;

-- ## 缺失支付时间的订单
SELECT id FROM orders WHERE status = 'PAID' AND paid_at IS NULL;
```

长脚本可按建表、索引、种子数据、迁移、分析查询组织，按实际任务取舍，不为凑长度添加无关 SQL。保持原有事务边界和依赖顺序。

## JetBrains HTTP Client（.http / .rest）

优先采用独立的空 `###` 请求分隔符，再写 `// # 标题` 到 `// ###### 标题`，最后写请求行。`# # 标题` 形式也支持。

**前一个请求有 JSON 或其他请求体时，下一组标题必须放在下一个 `###` 分隔符之后。** 不要把下一请求的注释放在请求体与分隔符之间，否则 IDE 可能把注释当成请求体。请求头和请求体之间留空行，JSON 内不写注释或尾随逗号。

```http
@host = https://example.invalid

###
// # 订单接口
// ## 创建订单
POST {{host}}/orders
Content-Type: application/json

{
  "skuId": 1001,
  "quantity": 2
}

###
// ## 按编号查询订单
GET {{host}}/orders/example-order-id
Accept: application/json
```

上例仅演示格式，域名与资源编号是占位值。实际输出使用项目现有环境变量、鉴权方式和接口契约。

- `### 请求名称` 是原生请求分隔符，插件固定将它视为二级节点，并不是三级 Markdown 标题。需要精确层级时用空 `###` 配合 `// ### 标题`，避免混用导致父子关系变化。
- 空 `###` 不产生大纲节点。不要为了增加节点而改变请求边界。
- `< {% ... %}` 前置脚本和 `> {% ... %}` 响应处理脚本内的注释不进入大纲。保留脚本与其所属请求的关联，将下一组标题放在下一分隔符后。
- 鉴权信息使用项目已有变量或占位符，不把令牌、密码写进示例。

## 交付前自检

1. SQL 标题在独立注释行，HTTP 标题在对应请求分隔符之后；各级标题包含空格和正文。
2. 每个 HTTP 请求边界明确，尤其检查所有带请求体的请求；JSON 有效，脚本没有被移到其他请求。
3. 无装饰分隔线、重复目录、逐句解说和同义标题堆叠；必要业务口径与风险仍保留。
4. 大纲按预期呈现业务层级；SQL 方言、语句语义、事务与请求契约保持正确。
5. 输出用户所需的完整文件或指定修改。若未实际执行，不声称已执行 SQL 或请求；本规范本身不授权执行。

使用插件打开文件后，在右侧 **Comment Outline** 检查层级，点击标题跳转。若当前环境不能操作 IDE，明确说明这项检查尚未完成。

参考：[插件源码与示例](https://github.com/fuuqiu/CommentNavigation) · [JetBrains HTTP 语法](https://www.jetbrains.com/help/idea/exploring-http-syntax.html)

命令、复制与下载取的是同一份文件，无需注册。

怎么用

在注释里写标题

在普通注释行里用 # 到 ###### 标记层级：SQL 写 -- # 标题，HTTP 写 // # 标题。井号后必须留一个空格，文件的其他部分什么都不用改。
打开 Comment Outline

点右侧的 Comment Outline 标签，或走 View → Tool Windows → Comment Outline。编辑器右键菜单和 Edit 菜单里的 Comment Structure 也能打开（默认键位 Shift+Cmd+F12）。
点击跳转，输入搜索

点击标题，或用上下键选中后按 Enter，跳到对应注释行。直接在树里输入就能搜索标题。

Scratches 里的迭代脚本会一路变长：几百行 SQL，没有结构，也很难回到刚才在看的那一段。注释大纲不改变你的书写习惯，只是把这份文件变成一份目录。

功能

大纲能做的事，以及它不做的事。

跟随编辑器，约 250 ms 更新

面板跟随当前选中的编辑器，修改后约 250 ms 自动重建大纲，不需要先保存。空文件和不支持的文件会清空目录。
大纲搜索

点击顶部灰色的文件名切换成搜索框，输入关键词即时过滤，不区分大小写，并保留匹配标题的父级路径；上下键选择、Enter 跳转、Esc 清空。
Scratches 目录树与文件搜索

点击面板底部的 Scratches 标题栏，展开 Scratches 里 .sql 和 .http 文件的目录树和文件名搜索框。上下两个区域独立滚动，可拖动分隔线调整高度。
新建、拖拽、重命名 Scratch 文件

点＋在面板内新建 orders.sql、api.http 或文件夹，新文件自带注释标题模板。把文件拖到文件夹即实际移动，同名冲突会提示、不覆盖。右键使用 IDEA 的重命名、剪切、复制、粘贴和删除。
折叠状态记忆

可逐个节点展开或折叠，也能全部展开、全部折叠。同一文件编辑时保留折叠状态，切换文件后默认展开。
跟随 IDE，只在本地

界面语言跟随 IDEA 的显示语言（中文或英文，其他语言用英文），颜色和图标跟随明亮 / 暗黑主题。目录在 IDE 本地生成，不上传文档内容，无遥测、无广告。

解析使用平台 Document API，不依赖 SQL / Database 或 HTTP Client 语言插件。
原有的 Java / Kotlin 注释弹窗保留，仍通过同一个 Comment Structure 动作（Shift+Cmd+F12）打开。

标题写法

标题就是普通注释。数据库控制台和 HTTP Client 看到的仍然是注释，文件照样能直接执行。

SQL

-- # 角色与权限核对
-- ## 角色本体
-- ### 系统模板
SELECT 'system role';

-- ### 商户角色
SELECT 'merchant role';

-- ## 授权明细
/*
 * ### 页面权限
 * #### PRO 页面
 */
SELECT 'page permission';

Comment Outline

角色与权限核对
角色本体
系统模板
商户角色
授权明细
页面权限
PRO 页面

支持 -- 行注释、MySQL # 行注释和 /* … */ 块注释。
标题必须独占一整行注释。
不会把 SQL 语句行尾注释、字符串或引用标识符里的内容误认成标题。

HTTP

@host = https://example.invalid

###
// # 订单接口
// ## 创建订单
// ### 正常场景
POST {{host}}/orders
Content-Type: application/json

{ "skuId": 1001, "quantity": 2 }

###
// ## 查询订单
// ### 按订单编号查询
GET {{host}}/orders/example-order-id

Comment Outline

订单接口
创建订单
正常场景
查询订单
按订单编号查询

推荐用 // # 标题；# # 标题（# 注释后再加 Markdown 标记）同样支持。
### 请求名称 固定是二级节点，因此不要用它表达三级标题；需要明确层级时写 // ### 标题。
空的 ### 不进入目录；请求前置和响应处理脚本里的注释也不进入目录。

HTTP 标题层级对照
写法	大纲层级
`// # 标题` 或 `# # 标题`	一级
`// ## 标题` 或 `# ## 标题`	二级
`// ### 标题` 或 `# ### 标题`	三级
`### 请求名称`	二级 —— HTTP Client 原有的请求分隔符

规则

标题标记后必须留一个空格，支持 1–6 级。
跳级时挂在前一个层级更浅的标题下；同级标题保持文件顺序。
有显式标题时只展示标题，普通说明和纯装饰分隔线都不进入大纲。
没有显式标题时，优先提取 0. 参数区、1. 接口说明 这类编号章节；没有编号章节才回退到普通注释的平级列表。
MySQL 方言里层级标题写成 # # 角色核对、# ## 权限明细：第一个 # 是 SQL 注释符，后面的 # 才表示标题级别。
HTTP 请求体之后，先写新的 ### 分隔符，再写下一组标题，否则它们会被当成请求体。

安装

两分钟、一条命令，IDE 提示时重启一次即可。

JetBrains Marketplace

已上线

打开 Marketplace 条目安装到 IntelliJ IDEA 2025.1–2026.2，或在 Settings → Plugins → Marketplace 里搜索 Code Comment Navigator。

从 JetBrains Marketplace 安装

从源码安装

构建

克隆仓库，用 JDK 21 执行 ./gradlew test buildPlugin。安装包输出在 build/distributions/comment-navigation-1.2.4.zip。
Install Plugin from Disk

在 IDE 里打开 Settings → Plugins → 齿轮菜单 → Install Plugin from Disk…，选择该 ZIP，按 IDE 提示完成安装。
打开 SQL 或 HTTP 文件

打开 .sql、.http 或 .rest 文件，点右侧的 Comment Outline 标签，或走 View → Tool Windows → Comment Outline。

兼容 IntelliJ IDEA 2025.1–2026.2（251–262.*），基于 2025.1 SDK 构建并输出 Java 21 字节码。从源码构建需要 JDK 21。

想先看看效果？仓库里带了两个示例文件： SQL 示例 · HTTP 示例

常见问题

Code Comment Navigator 是免费的吗？

支持哪些版本的 IntelliJ IDEA？

兼容 IntelliJ IDEA 2025.1–2026.2（251–262.*），基于 2025.1 SDK 构建并输出 Java 21 字节码。从源码构建插件需要 JDK 21。

需要额外装 Database 或 HTTP Client 插件吗？

不需要。解析使用平台 Document API，不依赖 SQL / Database 或 HTTP Client 语言插件，.sql、.http、.rest 文件都能自己读。

它会把我的代码传到外部吗？

不会。插件不含任何网络代码，只读取你当前打开的编辑器文本，并在 IDE 本地生成大纲。

为什么 ### 请求名称 是二级节点？

因为它是 HTTP Client 原有的请求分隔符，为了让既有 .http 文件保持可用，它固定映射为二级节点；空的 ### 会被跳过。需要明确的三级标题时，改写成 // ### 标题。

在 Scratches 里能用吗？

能。项目文件和 Scratches 都支持——Scratches 里越写越长的迭代脚本正是这个大纲存在的理由。打开 scratch 的 SQL 或 HTTP 文件，面板照常跟随编辑器。

许可与联系

Code Comment Navigator 采用 MIT 许可证，版权归 Fuuqiu (Tinyue) 所有（2024–2026）。个人和企业均可免费使用，包括商业用途，无需购买、订阅或激活码。

给 SQL 和 HTTP 文件一份目录

一行命令，让你的 AI 写出自带大纲的文件

Claude Code

Codex

Cursor

通用粘贴

AI 默认写法 → 用 Skill 之后

怎么用

在注释里写标题

打开 Comment Outline

点击跳转，输入搜索

功能

跟随编辑器，约 250 ms 更新

大纲搜索

Scratches 目录树与文件搜索

新建、拖拽、重命名 Scratch 文件

折叠状态记忆

跟随 IDE，只在本地

标题写法

SQL

HTTP

规则

安装

JetBrains Marketplace

从源码安装

构建

Install Plugin from Disk

打开 SQL 或 HTTP 文件

常见问题

许可与联系

相关链接