@deepstorm/cli 0.3.1 → 0.3.3

package/dist/cli.js

@@ -7285,6 +7285,14 @@ function copyFragmentsForSkill(skillId, srcDir, config, registry2, targetDir) {
         );
       }
     }
+    const allFiles = fs10.readdirSync(srcPath);
+    for (const file of allFiles) {
+      if (file === ".DS_Store") continue;
+      if (file === "quick-reference.md") continue;
+      if (file === "examples") continue;
+      if (!file.endsWith(".md")) continue;
+      fs10.cpSync(path6.join(srcPath, file), path6.join(targetDir, file), { force: true });
+    }
   }
 }
 function copyReferencesForSkill(srcDir, targetDir) {

package/dist/hooks/reef-code-style-verify.sh.tmpl

@@ -0,0 +1,97 @@
+#!/bin/bash
+# reef-code-style-verify.sh.tmpl
+# PostToolUse: 在 Edit/Write 后自动验证代码风格
+#
+# 模板变量（安装时由 wizard 注入）：
+#   {{reef.backend.java.lintCmd}}    — Java lint 命令（默认 checkstyle）
+#   {{reef.backend.python.lintCmd}}  — Python lint 命令（默认 ruff check）
+#   {{reef.frontend.lintCmd}}        — 前端 lint 命令（默认 eslint）
+
+set -euo pipefail
+
+# ── 1. 获取文件路径 ──────────────────────────────────────────────────
+filepath=""
+
+if [ -p /dev/stdin ] && command -v jq &>/dev/null; then
+  filepath=$(jq -r '.tool_response.filePath // .tool_input.file_path // ""' 2>/dev/null || true)
+fi
+
+if [ -z "$filepath" ] || [ "$filepath" = "null" ]; then
+  filepath="${CLAUDE_CODE_TOOL_RESULT_FILEPATH:-}"
+fi
+
+[ -z "$filepath" ] && exit 0
+[ ! -f "$filepath" ] && exit 0
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+JAVA_LINT="{{reef.backend.java.lintCmd}}"
+PYTHON_LINT="{{reef.backend.python.lintCmd}}"
+TS_LINT="{{reef.frontend.lintCmd}}"
+
+# ── ESLint 配置检测 ───────────────────────────────────────────────────
+has_eslint_config() {
+  [ -f "$PROJECT_DIR/eslint.config.js" ] || \
+  [ -f "$PROJECT_DIR/eslint.config.mjs" ] || \
+  [ -f "$PROJECT_DIR/.eslintrc.js" ] || \
+  [ -f "$PROJECT_DIR/.eslintrc.json" ] || \
+  [ -f "$PROJECT_DIR/.eslintrc" ]
+}
+
+# ── 2. 按文件类型执行验证 ────────────────────────────────────────────
+
+case "$filepath" in
+  *.java)
+    # Java: checkstyle（如果项目配置了 checkstyle.xml）
+    if [ "$JAVA_LINT" != "none" ] && command -v "${JAVA_LINT%% *}" &>/dev/null; then
+      for conf in "$PROJECT_DIR/checkstyle.xml" "$PROJECT_DIR/config/checkstyle/checkstyle.xml"; do
+        if [ -f "$conf" ]; then
+          output=$($JAVA_LINT -c "$conf" "$filepath" 2>&1 | grep -iE "error|warning" | head -20 || true)
+          if [ -n "$output" ]; then
+            echo "[style-verify] ⚠ Java 代码风格问题："
+            echo "$output"
+            echo "[style-verify] 运行 $JAVA_LINT -c $conf $filepath 查看完整报告。"
+          fi
+        fi
+      done
+    fi
+    ;;
+
+  *.py)
+    # Python: ruff check
+    if [ "$PYTHON_LINT" != "none" ] && command -v "${PYTHON_LINT%% *}" &>/dev/null; then
+      output=$($PYTHON_LINT "$filepath" 2>/dev/null || true)
+      if [ -n "$output" ]; then
+        echo "[style-verify] ⚠ Python 代码风格问题："
+        echo "$output" | head -20
+        echo "[style-verify] 请使用 $PYTHON_LINT $filepath 查看完整报告。"
+      fi
+    fi
+    ;;
+
+  *.ts|*.tsx|*.js|*.jsx)
+    # TypeScript/JavaScript: eslint
+    if [ "$TS_LINT" != "none" ] && command -v npx &>/dev/null && has_eslint_config; then
+      output=$(cd "$PROJECT_DIR" && npx $TS_LINT "$filepath" 2>/dev/null || true)
+      if [ -n "$output" ]; then
+        echo "[style-verify] ⚠ TypeScript/JavaScript 代码风格问题："
+        echo "$output" | head -20
+        echo "[style-verify] 请运行 npx $TS_LINT $filepath 查看完整报告。"
+      fi
+    fi
+    ;;
+
+  *.html|*.css|*.scss|*.less)
+    # 前端模板/样式文件：eslint（如果项目已配置）
+    if [ "$TS_LINT" != "none" ] && command -v npx &>/dev/null && has_eslint_config; then
+      output=$(cd "$PROJECT_DIR" && npx $TS_LINT "$filepath" 2>/dev/null || true)
+      if [ -n "$output" ]; then
+        echo "[style-verify] ⚠ 前端文件代码风格问题："
+        echo "$output" | head -10
+        echo "[style-verify] 请运行 npx $TS_LINT $filepath 查看完整报告。"
+      fi
+    fi
+    ;;
+esac
+
+exit 0

package/dist/hooks/reef-hooks.json

@@ -30,7 +30,7 @@
           {
             "type": "prompt",
             "timeout": 5,
-            "prompt": "You are about to write or edit a file. If the target file extension is .java, load reef-style-backend skill for coding standards. If the target is .ts, .html, .css, .scss, or .less, load reef-style-frontend skill for coding standards. Follow the loaded skill's rules in your output."
+            "prompt": "You are about to write or edit a source file. The following core rules apply based on the file extension. You MUST follow the relevant rules for your file type.\n\n## 🔴 Core Coding Rules (must follow)\n\n### Java\n1. Use @Getter @AllArgsConstructor for event/POJO classes; NEVER use @Data\n2. NEVER use @Autowired field injection; always use constructor injection (@RequiredArgsConstructor)\n3. Use abstract method instead of instanceof chain for type dispatch\n4. Use formatted() / Text Block for string formatting; never use + concatenation\n5. Use @RequiredArgsConstructor for Service/Controller; @Getter @NoArgsConstructor(access = PROTECTED) for Entity\n\n### Python\n1. Use f-strings; never use % or .format()\n2. snake_case for functions/variables; PascalCase for classes\n3. Always annotate return types and parameter types (mypy must pass)\n4. Use is / is not for None comparison; never use == None\n5. Use Enum / Protocol / abstract method instead of isinstance() chain\n\n### TypeScript\n1. Standalone + OnPush + inject() (Angular) / Function components + hooks (React) / <script setup lang=\"ts\"> (Vue)\n2. Use output() instead of @Output() (Angular) / custom hooks over lifecycle methods (React) / composables (Vue)\n3. Use signal() / computed() for reactive state management\n4. Use loadComponent for lazy-loaded routes\n5. Use interface for Props / Entity types\n\n## 📖 Full Reference\nLoad the reef-style-backend or reef-style-frontend skill for the complete coding standard.\n\n## ✅ Self-Verification\nBefore writing code, first output `✅ [STYLE] confirmed {language} rules` to acknowledge you have read and will follow the rules above."
           }
         ]
       }
@@ -45,6 +45,17 @@
           }
         ]
       },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/reef-code-style-verify.sh",
+            "async": true,
+            "statusMessage": "Verifying code style..."
+          }
+        ]
+      },
       {
         "matcher": "Edit|Write",
         "hooks": [

package/dist/registry.json

@@ -562,6 +562,20 @@
                   ]
                 }
               ]
+            },
+            {
+              "key": "reef.backend.java.formatTool",
+              "label": "Java 格式化工具",
+              "type": "static",
+              "value": "google-java-format",
+              "template": {
+                "formatCmd": "google-java-format -i",
+                "lintCmd": "checkstyle"
+              },
+              "affectedTemplates": [
+                "hooks/reef-auto-format.sh.tmpl",
+                "hooks/reef-code-style-verify.sh.tmpl"
+              ]
             }
           ]
         },
@@ -951,13 +965,13 @@
       "hooks": [
         "reef-auto-format.sh",
         "reef-block-dangerous.sh",
+        "reef-code-style-verify.sh",
         "reef-intent-detect.sh",
         "reef-protect-files.sh",
         "reef-run-tests.sh",
         "reef-scope-check.sh",
         "reef-scope-ci.sh",
         "reef-scope-gate.sh",
-        "reef-scope-pre-commit.sh",
         "reef-scope-setup.sh",
         "reef-scope-split.sh"
       ]

package/dist/skills/reef-style-backend/SKILL.md.tmpl

@@ -122,6 +122,7 @@ deepstorm:
 | `quick-reference.md` | **编码规范速查**。包含核心规则和约定 |
 | `{value}.md` | **维度规范**（如 `spring-boot.md`、`hibernate.md`）。按上方链接加载 |
 | `api-spec.md` | **API 规范**。RESTful 命名、统一响应体、版本策略、OpenAPI |
+| `jackson-polymorphism.md` | **DTO 多态序列化规范**。Jackson `@JsonTypeInfo` + TS Discriminated Union |
 | `dependency-management.md` | **依赖管理规范**。Version Catalog、版本一致性、CVE |
 | `exception-handling.md` | **异常处理深度规范**。异常层次、错误码、全局处理 |
 | `security-redlines.md` | **安全红线**。P0/P1 安全规则及代码示例 |

package/dist/skills/reef-style-backend/fragments/java/api-spec/jackson-polymorphism.md

@@ -0,0 +1,205 @@
+# Jackson 多态序列化与 TypeScript 联合类型
+
+> 适用于后端枚举驱动的图表类型分发 → Jackson `@JsonTypeInfo` 多态 + 前端 discriminated union 的模式。
+> 目标：删除后端 `enum` + `chartType` 字段，改用抽象基类 + `@JsonProperty("type")` 实现自动分发。
+
+```mermaid
+flowchart LR
+    A["后端 Java<br/>@JsonTypeInfo(property = &quot;type&quot;)<br/>@JsonSubTypes"] -->|"JSON 携带<br/>type 判别值"| B["前端 TypeScript<br/>Discriminated Union"]
+    B --> C["@switch(answer.chartView.type)<br/>类型自动窄化"]
+```
+
+---
+
+## 一、问题场景
+
+后端接口返回 JSON 中包含一个"类型"字段，前端根据该类型渲染不同的组件：
+
+```java
+// ❌ 旧模式：枚举 + switch
+public record MetricAnswer(ChartType chartType, ...) {}
+public enum ChartType { METRIC_CARD, LINE_CHART, BAR_CHART, PIE_CHART }
+
+// 前端每次新增类型都需要：
+// 1. 加 enum 值
+// 2. 改 switch
+// 3. 不在同一个地方维护
+```
+
+## 二、推荐模式：Jackson 多态序列化
+
+### 2.1 后端
+
+**步骤 1：定义抽象基类**
+
+```java
+@JsonTypeInfo(use = JsonTypeInfo.Id.SIMPLE_NAME, property = "type")
+@JsonSubTypes({
+    @JsonSubTypes.Type(value = MetricCardView.class, name = "MetricCardView"),
+    @JsonSubTypes.Type(value = LineChartView.class, name = "LineChartView"),
+    @JsonSubTypes.Type(value = BarChartView.class, name = "BarChartView"),
+    @JsonSubTypes.Type(value = PieChartView.class, name = "PieChartView"),
+})
+public abstract class ChartView {}
+```
+
+- `property = "type"` — 序列化时自动在 JSON 中写入 `"type": "MetricCardView"` 等 discriminator
+- `name = "..."` — discriminator 的值，应与 TypeScript 端 literal type 保持一致
+- 新增类型只需：新建子类 + 注册到 `@JsonSubTypes`
+
+**步骤 2：定义子类**
+
+```java
+@JsonInclude(Include.NON_NULL)
+public class MetricCardView extends ChartView {
+    private final String title;
+    private final Object value;
+    private final String unit;
+
+    public MetricCardView(String title, Object value, String unit) {
+        this.title = title;
+        this.value = value;
+        this.unit = unit;
+    }
+    // getters ...
+}
+```
+
+```java
+public class LineChartView extends ChartView {
+    private final String title;
+    @JsonProperty("xAxisName") private final String categoryAxisLabel;
+    @JsonProperty("yAxisName") private final String valueAxisLabel;
+    private final String seriesName;
+    private final List<ChartDataPoint> dataPoints;
+    // constructor + getters ...
+}
+```
+
+> **💡 Import 说明：**
+> - `@JsonTypeInfo`、`@JsonSubTypes`、`@JsonInclude` 来自 `com.fasterxml.jackson.annotation.*`
+> - `@JsonInclude(Include.NON_NULL)` 需导入 `com.fasterxml.jackson.annotation.JsonInclude.Include`
+> - 或在注解中写全路径 `@JsonInclude(JsonInclude.Include.NON_NULL)`，无需额外 import
+
+**步骤 3：替换枚举字段**
+
+```java
+// ❌ 旧
+public record MetricAnswer(ChartType chartType, ...) {}
+
+// ✅ 新
+public record MetricAnswer(ChartView chartView, ...) {}
+```
+
+- 业务逻辑构建时直接 `return new PieChartView(...)` 而非 `return ChartType.PIE_CHART`
+- 删除 `ChartType` 枚举文件
+
+### 2.2 前端（TypeScript）
+
+**步骤 1：定义 Discriminated Union**
+
+```typescript
+interface BaseChartView {
+  type: string;
+}
+
+export interface MetricCardView extends BaseChartView {
+  type: 'MetricCardView';
+  title: string;
+  value: unknown;
+  unit: string | null;
+}
+
+export interface LineChartView extends BaseChartView {
+  type: 'LineChartView';
+  title: string;
+  xAxisName: string;
+  yAxisName: string;
+  seriesName: string;
+  dataPoints: ChartDataPoint[];
+}
+
+export type ChartView = MetricCardView | LineChartView | BarChartView | PieChartView;
+```
+
+**步骤 2：MetricAnswer 中使用联合类型**
+
+```typescript
+export interface MetricAnswer {
+  // ...
+  chartView: ChartView | null;  // ✅ 联合类型自动窄化
+}
+```
+
+**步骤 3：模板中使用 @switch**
+
+```html
+@if (answer.chartView) {
+  @switch (answer.chartView.type) {
+    @case ('MetricCardView') {
+      <app-metric-card [answer]="answer" />
+    }
+    @case ('LineChartView') {
+      <app-line-chart [chartData]="answer.chartData" />
+    }
+  }
+}
+```
+
+## 三、最佳实践
+
+| 要点 | 说明 |
+|------|------|
+| `property = "type"` | discriminator 字段名使用 `"type"`（简短、通用），而非 `"chartType"` |
+| 前后端 value 一致 | `@JsonSubTypes.Type(name = "MetricCardView")` 与 TS `type: 'MetricCardView'` 的值必须一致 |
+| Checkstyle 兼容 | Jackson 字段名与 getter 名可以不同：`@JsonProperty("xAxisName") private String categoryAxisLabel` |
+| 共享 DTO | 子类共享的嵌套类型（如 `ChartDataPoint`）定义为独立 `record` 或类 |
+| 判空安全 | 模板中 `@if (answer.chartView)` 保护空值（如错误响应时 chartView 为 null） |
+| 不删除旧 DTO 层 | `ChartData`、`gridResults`、`singleResults` 等依然存在，chartView 是新增的视图抽象，并非替代所有响应字段 |
+| 删除前确认引用 | 删除旧枚举前 MUST 搜索全项目 Java + TypeScript 引用，确认 0 引用后方可删除 |
+
+## 四、效果对比
+
+| 维度 | 旧模式（Enum） | 新模式（Polymorphism） |
+|------|---------------|----------------------|
+| 新增图表类型 | 枚举 + switch + 前端分支 | 新建子类 + 注册 `@JsonSubTypes` + TS 类型 |
+| JSON 结构 | `{"chartType": "METRIC_CARD", ...}` | `{"chartView": {"type": "MetricCardView", ...}}` |
+| TS 类型安全 | 手动维护 | 自动通过 discriminated union 窄化 |
+| 后端字段数 | chartType + 具体数据各自校验 | chartView 自包含 |
+
+## 五、设计决策说明
+
+### 5.1 `property` 选择 `"type"` 而非 `"chartType"`
+
+| 候选 | 理由 | 结论 |
+|------|------|------|
+| `"type"` | 简短通用，多态基类职责就是描述"是什么类型"，与低代码项目 (`DatasetDto`) 一致 | ✅ |
+| `"chartType"` | 业务含义明确，但限制了基类的可复用性。未来其他多态场景（如 `DataSourceConnector`）需要不同字段名 | ❌ |
+| `"kind"` | Jackson 社区惯例使用 `"type"`，不应引入不必要的差异 | ❌ |
+
+### 5.2 discriminator 策略使用 `SIMPLE_NAME`
+
+| 候选 | 理由 | 结论 |
+|------|------|------|
+| `SIMPLE_NAME` | 子类简名自描述，无需额外常量文件 | ✅ |
+| `CLASS_NAME` | 全限定名过长，JSON 中不可读且暴露包结构 | ❌ |
+| `CUSTOM` | 需要 `@JsonTypeIdResolver`，增加复杂度 | ❌ |
+
+### 5.3 使用 `@JsonSubTypes` 而非自定义序列化器
+
+`@JsonSubTypes` 是 Jackson 原生支持，注解式声明最直观。`@JsonTypeIdResolver` 或自定义 `JsonSerializer` 提供更灵活的控制但需要大量模板代码，适用于更复杂的动态注册场景而非当前已知类型场景。
+
+### 5.4 前端 Discriminated Union 而非 Enum
+
+TypeScript union type + `type` literal 可直接利用 `@switch` 的类型窄化能力，无需手动编写类型守卫函数。这与后端 enum 模式的维护成本形成鲜明对比。
+
+### 5.5 Checkstyle 冲突：`@JsonProperty` 解耦而非禁用规则
+
+| 候选 | 理由 | 结论 |
+|------|------|------|
+| `@JsonProperty("xAxisName") private String categoryAxisLabel` | 字段名合规，getter 合规，JSON 输出保留 `xAxisName` | ✅ |
+| 禁用 Checkstyle `ParameterNameCheck` | 全局禁用降低代码规范性 | ❌ |
+
+### 5.6 Decoder 对象保持 record
+
+如 `MetricAnswer` 是 Java record，不能继承。改造方案为直接替换字段类型（`ChartType chartType` → `ChartView chartView`），record 紧凑语法不受影响。构建逻辑从 `determineChartType()` 改为 `buildChartView()` 并返回具体子类。

package/dist/skills/reef-style-backend/fragments/java/api-spec/quick-reference.md

@@ -146,3 +146,11 @@ MODULE: 2-4 个大写字母标识模块
 - `_100`-`_199`：资源状态错误（不存在、已存在、冲突）
 - `_200`-`_299`：权限错误
 - `_300`-`_399`：系统内部错误
+
+## DTO 多态序列化
+
+当接口中的 DTO 需要根据类型字段分发到不同子类时（如多种图表类型、多种数据源类型），参考 [DTO 多态序列化规范](jackson-polymorphism.md)：
+
+- 后端使用 Jackson `@JsonTypeInfo` + `@JsonSubTypes` 实现多态序列化
+- 前端使用 TypeScript Discriminated Union 对应消费
+- discriminator value 前后端严格一致

package/dist/skills/reef-style-backend/fragments/java/framework/spring-boot/quick-reference.md

@@ -53,31 +53,8 @@ DTO 继承基类，写请求用独立 CreateRequest/UpdateRequest record。MapSt
 
 ### 异常处理
 
-| 异常 | HTTP | 场景 |
-| --- | --- | --- |
-| `NotFoundException` | 404 | 资源不存在 |
-| `AlreadyExistsException` | 409 | 重复创建 |
-| `InvalidArgumentException` | 400 | 参数校验失败 |
-| `PermissionDeniedException` | 403 | 无权限 |
-| `FailedPreconditionException` | 400 | 前置条件不满足 |
-
-所有自定义异常通过 `@RestControllerAdvice` `GlobalExceptionHandler` 统一处理，返回 AIP-193 兼容的 `CustomError` 结构：
-
-```java
-@RestControllerAdvice
-public class GlobalExceptionHandler {
-  @ExceptionHandler(ResourceNotFoundException.class)
-  public ResponseEntity<ErrorResponse> handleNotFound(ResourceNotFoundException ex) {
-    return ResponseEntity.status(NOT_FOUND).body(new ErrorResponse(ex.getMessage()));
-  }
-}
-```
+> 异常处理规范（异常继承层次、ErrorCode 枚举、GlobalExceptionHandler）参见 [异常处理规范](../exception-handling/quick-reference.md)。
 
 ### 安全编码规范
 
-- Controller 写操作接口必须加 `@PreAuthorize("hasAuthority('PERMISSION_NAME')")`，禁止在方法内硬编码权限字符串
-- 请求体参数加 `@Valid`，嵌套对象加 `@Valid`
-- DTO 中密码/token 用 `@JsonIgnore` 或从响应 DTO 中排除
-- 密码使用 `BCryptPasswordEncoder`
-- 禁止 `createNativeQuery`（绕过多租户 + SQL 注入风险）
-- `@Query` 始终使用命名参数（`:paramName`），不用 `?1` 位置参数
+> 安全红线（密码存储、SQL 注入、敏感信息脱敏、文件上传等）参见 [安全红线](../security-redlines/quick-reference.md)。

package/dist/skills/reef-style-backend/variants/java/examples/code-wrapping.md

@@ -185,7 +185,8 @@ Java 15+ 的 Text Block 用于嵌入 JSON / SQL / XML / 模板等 DSL。缩进
 ```java
 // ✅ opening """ 后直接换行，内容相对 opening 行缩进 4 格
 // ✅ closing """ 决定 stripIndent() 的公共缩进基线
-var json = """
+var json = 
+    """
     {
       "name": "example",
       "value": 42,
@@ -194,7 +195,8 @@ var json = """
     """;
 
 // ✅ 嵌入 SQL：closing """ 与 SQL 内容的公共缩进最左列对齐
-var sql = """
+var sql = 
+    """
     SELECT u.id, u.name, r.role_name
     FROM users u
     JOIN user_roles r ON r.user_id = u.id
@@ -209,7 +211,8 @@ var message = """
     """.formatted(userName, orderId);
 
 // ✅ 空行可用 \s 占位避免 stripIndent 清空：
-var json = """
+var json = 
+    """
     {
       "title": "test",
     \s
@@ -219,9 +222,10 @@ var json = """
 ```
 
 **规范：**
-- `"""` 必须后跟换行，**禁止在同行放内容**
-- `closing """` 的缩进决定公共缩进基线，放在最后一行内容之下，与之缩进对齐
+
+- `"""` **独立占一行**，后跟换行，禁止在同行放内容
+- `closing """` **独立占一行**，其缩进决定公共缩进基线，放在最后一行内容之下与之对齐
 - 禁止 text block 与 `+` 拼接混用；需要变量替换统一用 `formatted()`
 - 短字符串（≤ 100 列单行）不使用 text block，直接使用普通字符串
 - `\s` 用于显式保留 text block 中的空行（避免 `stripIndent()` 把空行清空）
-```
+

package/dist/skills/reef-style-backend/variants/java/quick-reference.md

@@ -22,45 +22,31 @@
 | 字段注释 | Model/Entity/Event 加 `/** */`，DTO/Record 不加 |
 | 日志实体 | 继承 `LogEntry`（SINGLE_TABLE），不直接继承基类 |
 | 弃用 API | 编译警告中的 `@Deprecated` API 在同一次 PR 中替换为新 API |
-| 多行字符串 | 用 Text Block `"""..."""` + `formatted()` 嵌入 JSON/SQL/XML，禁止 `+` 拼接；详见 [code-wrapping.md](examples/code-wrapping.md) |
+| 多行字符串 | 用 Text Block `"""..."""` + `formatted()` 嵌入 JSON/SQL/XML，禁止 `+` 拼接 |
 
 ## 代码风格
 
-### 通用约定
-
-- 变量命名有意义，禁止单字母（循环计数器 `i`/`j`/`k` 除外）
-- 局部变量用 `var`
-- 字符串格式化用 `formatted()`，不用 `+` 拼接
-- 多态替代 `instanceof` 链做类型分发
-- 100 列折行，运算符/`.`/`::` 放行首。适用范围如下：
-  - **代码结构**（方法调用、签名、表达式）严格执行 100 列
-  - **Javadoc / 注释文本**以可读性优先，不硬断中文句子；仅单行 `/** ... */` 标记超长时拆成多行
-- **方法调用参数换行**：所有参数能在列宽内一行放完则一行，放不完则每个参数独立一行（不混合分组）；详见 [code-wrapping.md](examples/code-wrapping.md)「方法调用参数换行」
-- 类内字段按用途逻辑分组，组间空行分隔，**禁止使用 `// ======`（或其他重复符号装饰）做视觉分隔线注释**。例如应避免 `// ========== 维度信息 ==========` 这种写法
-- 注释与代码逻辑块之间：相邻的两个 `// 注释 + 代码块` 之间用空行分隔，使每个逻辑块保持独立。
-  ```java
-  // ✅ 正确：逻辑块之间有空行
-  // PROPORTION → 饼图
-  if (queryIntent == QueryIntent.PROPORTION) {
-    return ChartType.PIE_CHART;
-  }
-
-  // GROUP_BY → 柱状图
-  if (queryIntent == QueryIntent.GROUP_BY) {
-    return ChartType.BAR_CHART;
-  }
-  ```
-  ```java
-  // ❌ 错误：缺少分隔空行，两个逻辑块粘连
-  // PROPORTION → 饼图
-  if (queryIntent == QueryIntent.PROPORTION) {
-    return ChartType.PIE_CHART;
-  }
-  // GROUP_BY → 柱状图
-  if (queryIntent == QueryIntent.GROUP_BY) {
-    return ChartType.BAR_CHART;
-  }
-  ```
+### LLM 常犯错误
+
+> 📌 以下规则仅约束 LLM 容易跑偏的地方。LLM 天然写对的内容（命名、代码空行分隔等）不再列出。
+
+- 局部变量优先用 `var`，避免冗余的类型声明
+- 字符串格式化用 `formatted()` / Text Block，不用 `+` 拼接
+- 用多态 / Abstract Method 替代 `instanceof` 链做类型分发
+
+### Lombok 使用规范
+
+| 组件类型 | 必用注解 | 说明 |
+|---------|---------|------|
+| 领域事件 / POJO | `@Getter @AllArgsConstructor` | `private final` 不可变，不手写 getter/constructor（见下方示例） |
+| JPA Entity | `@Getter @NoArgsConstructor(access = PROTECTED)` + `@SuperBuilder`（按需） | 详见 [Hibernate 规范](hibernate.md) |
+| Service / Controller | `@AllArgsConstructor` / `@RequiredArgsConstructor` | 构造函数注入，不用 `@Autowired` 字段注入 |
+| 只读 DTO / Record 替代 | `@Value` | 不可变对象，自动生成 equals/hashCode/toString。Record 更简洁时优先用 record |
+
+**禁止事项：**
+- `@Data` — 自动生成 `@Setter` 破坏不可变性，且 `@EqualsAndHashCode` 在有 JPA 代理时行为不可预期
+- `@Setter` on Entity — 破坏封装，业务状态变更应通过行为方法表达
+- `@Autowired` 字段注入 — 必须用构造函数注入
 
 ### 控件能力声明模式（Capability Pattern）
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepstorm/cli",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "DeepStorm CLI — 一键配置项目开发环境",
   "license": "MIT",
   "author": "billkang",