chore: 清理冗余注释，保留字段/业务含义注释

skills/comment-cleanup/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: comment-cleanup
+description: 提交代码前优化 Java 注释，移除冗余描述性注释，保留功能性注释和业务上下文注释。
+metadata:
+  short-description: 清理 Java 代码中的冗余注释
+---
+
+# Comment Cleanup
+
+在代码提交前，扫描变更的 Java 文件，清理冗余注释，保留有价值的注释。
+
+## 触发条件
+
+用户要求清理注释、优化注释、提交前检查注释时使用。
+
+## 工作流程
+
+1. 定位待清理的 Java 文件（通常是 `git diff` 中变更的文件）
+2. 逐文件扫描注释，按规则分类处理
+3. 执行清理（删除或改造）
+4. 输出清理报告
+
+## 注释分类规则
+
+### 移除：类型 A — 代码语义重复注释
+
+代码本身已经清晰表达意图时，删除多余的行内注释。
+
+```java
+// ❌ 移除：代码已经说清楚了
+// 转换报告
+List<ReviewFeedItem> reportItems = reports.stream().map(r -> toFeedItem(r)).collect(Collectors.toList());
+
+// ❌ 移除：合并逻辑一眼就能看出
+// 合并并按创建时间倒序
+return Stream.concat(reportItems.stream(), fragmentItems.stream())
+        .sorted(Comparator.comparing(ReviewFeedItem::getCreatedTime).reversed())
+        .collect(Collectors.toList());
+
+// ❌ 移除：查询目的从变量名已可知
+// 先查该任务下的所有 sessionNum
+List<String> sessionNums = studySessionsMapper.selectList(...)
+```
+
+**判断标准：** 如果删掉注释后，一个熟悉 Java/Spring 的开发者看代码没有任何困惑，就该移除。
+
+**例外：** 方法级的 Javadoc（`/** ... */`）即使与代码重复，也保留，因为它服务于 IDE 提示和文档生成。
+
+### 移除：类型 B — 框架机制注释
+
+框架隐式行为（拦截器、MetaObjectHandler、AOP 等）的说明不在代码中重复标注，而是在 `AGENTS.md` 的"框架机制"章节集中描述。代码中的此类注释一律移除。
+
+```java
+// ❌ 移除：框架机制已在 AGENTS.md 中说明
+// created_by 条件由 TenantLineInnerInterceptor 自动注入
+List<StudyReportsEntity> reports = studyReportsMapper.selectList(...)
+
+// ❌ 移除
+// 拦截器自动校验归属
+return Optional.ofNullable(studyReportsMapper.selectById(id)) ...
+
+// ❌ 移除
+// created_by 由 MetaObjectHandler 自动填充
+studySessionsServiceImpl.save(...)
+```
+
+### 移除：类型 D — 空注释 / 无信息量注释
+
+```java
+// ❌ 空 Javadoc
+/**
+ * 
+ */
+@TableField(value = "created_time")
+private LocalDateTime createdTime;
+
+// ❌ 纯标注作者（无版本/日期等有价值信息时）
+/**
+ * @author guo
+ */
+public class GlobalExceptionHandler { ... }
+
+// ❌ 重复 HTTP 状态码（CommonResult.error 已隐含 400）
+//code:400  
+return CommonResult.error(ex.getMessage());
+```
+
+### 保留：类型 C — 字段/类 Javadoc
+
+字段 Javadoc 描述数据含义，类 Javadoc 描述模块职能。
+
+**字段 Javadoc：** 保留，说明字段的业务含义。
+
+```java
+// ✅ 保留：字段含义对理解数据模型有帮助
+/**
+ * 账号-登录用
+ */
+@TableField(value = "user_name")
+private String userName;
+```
+
+**类 Javadoc：** 保留，但只描述类的职能，不包含实现技术细节。
+
+```java
+// ❌ 移除：实现技术属于实现细节，不属于类描述
+/** 复习模块 Service 实现（纯 MyBatis-Plus Java API） */
+
+// ✅ 保留：只描述职能
+/** 复习模块 Service 实现 */
+```
+
+### 改造：类型 E — 枚举注释
+
+枚举中的中文含义注释应迁移到枚举类的专用字段中，而非用注释标注。
+
+```java
+// ❌ 改造前：用注释标注含义
+public enum Strategy {
+    // 创建组
+    CREATE("C"),
+    // 更新组
+    UPDATE("U");
+}
+
+// ✅ 改造后：用字段存储含义
+public enum Strategy {
+    CREATE("C", "创建组"),
+    UPDATE("U", "更新组");
+
+    private final String code;
+    private final String label;
+
+    Strategy(String code, String label) {
+        this.code = code;
+        this.label = label;
+    }
+
+    public String getCode() { return code; }
+    public String getLabel() { return label; }
+}
+```
+
+如果枚举已有 `label`/`desc` 等字段，则直接删除注释。
+
+**常量注释保留不变：**
+```java
+// ✅ 常量注释保留
+// 最大重试次数
+private static final int MAX_RETRY = 3;
+```
+
+### 保留：类型 F — TODO / FIXME 注释
+
+```java
+// ✅ 保留
+//todo 参数传递未加密
+```
+
+## 执行命令
+
+```bash
+# 获取变更的 Java 文件
+git diff --cached --name-only --diff-filter=ACMR -- '*.java'
+
+# 对每个文件逐行扫描，按上述规则处理
+```
+
+## 输出格式
+
+清理完成后，输出简要报告：
+
+```
+✅ 清理完成，共处理 N 个文件：
+  - 移除冗余注释 X 处
+  - 改造枚举注释 Y 处（需人工确认新增字段）
+  - 保留注释 Z 处（字段Javadoc/TODO）
+```

skills/comment-cleanup/agents/openai.yaml

@@ -0,0 +1,6 @@
+schema_version: v1
+interface:
+  display_name: Java 注释清理
+  short_description: 清理 Java 代码中的冗余注释，保留功能性注释
+  default_prompt: |
+    使用 $comment-cleanup 扫描变更的 Java 文件，移除冗余的描述性注释，保留框架机制注释、字段 Javadoc 和 TODO 注释。