---
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)