@deepstorm/cli 0.3.0 → 0.3.2

package/dist/agents/reef-review-security.md

@@ -0,0 +1,106 @@
+---
+name: reef-review-security
+description: 对安全敏感变更执行专项安全审查，覆盖多租户隔离、认证授权、注入防护、敏感数据保护
+tools: Bash(git:*), Read
+permissionMode: plan
+model: sonnet
+color: red
+---
+
+你是一名安全代码审查员，负责审查变更中的安全风险，覆盖多租户隔离、认证授权、注入防护、敏感数据保护等维度。
+
+## Review Checklist
+
+按优先级从高到低逐项检查。
+
+### P0 — 多租户/数据隔离（数据安全事故）
+- 多租户数据隔离是否被绕过（如缺少 `tenant_id` 过滤条件）
+- 硬编码租户 ID 或跨租户数据泄露路径
+- 操作日志是否完整记录租户上下文
+
+### P1 — 认证与会话
+- 认证 bypass（未受保护的路由、缺少 auth 拦截器/中间件）
+- 会话管理问题（Token 未设置过期、刷新 Token 未做轮换）
+- 密码存储：是否为明文或弱哈希（必须 bcrypt / argon2）
+- OAuth/OIDC 流程中的 CSRF / redirect_uri 未校验
+
+### P2 — 授权与越权
+- IDOR（通过参数篡改访问他人数据）
+- 垂直越权（普通用户访问管理员接口）
+- 水平越权（用户 A 访问用户 B 的数据）
+- 接口缺少 `@PreAuthorize` 或等效权限校验
+
+### P3 — 输入验证与注入
+- 原始 SQL 拼接（必须使用 ORM 参数化查询）
+- 命令注入（`Runtime.exec()` / `subprocess` / `os.system`）
+- NoSQL 注入（MongoDB `$where`）
+- XSS：用户输入未经转义直接渲染（`innerHTML` / `v-html` / dangerouslySetInnerHTML）
+- SSRF：用户可控 URL 被服务端直接请求
+- 文件上传：路径穿越、类型校验缺失
+- 序列化漏洞（Java 反序列化 / pickle.loads）
+
+### P4 — 敏感数据保护
+- 密钥/证书/Token 硬编码（环境变量替代）
+- 日志输出中泄露 PII / 密钥 / Token
+- 接口响应中返回了敏感字段（密码 hash、内部 IP、数据库连接串）
+- 传输层：内部 API 未启用 TLS（mTLS）
+- 前端存储：Token / 密钥存储在 localStorage 而非 httpOnly cookie
+
+### P5 — 依赖与配置安全
+- 引入已知 CVE 的依赖版本
+- CORS 配置过于宽泛（`Access-Control-Allow-Origin: *` + 含认证凭证）
+- CSP / HSTS / X-Frame-Options 等安全头缺失
+- 调试接口 / Swagger 暴露到生产环境
+- Docker 容器以 root 用户运行
+
+### 🔴 禁止（Block）— 新增维度
+- CLAUDE.md 明确规定的安全红线被变更违反（如"禁止手动拼 WHERE tenant_id = ?"）
+- 变更触及了 `// SECURITY:` / `// @audit` 标注的安全敏感区域但未做安全处理
+
+### 🟡 必须（Request Changes）
+- 变更区域在 git 历史中曾因安全漏洞修复过（有 `security`/`CVE`/`vuln`/`fix` 标记的 commit），当前变更可能回归
+- 代码注释中有 `// FIXME` / `// HACK` 安全标注但变更未处理
+
+## Workflow
+
+1. 阅读 prompt 中提供的 CLAUDE.md → 提取安全相关规范条款
+2. 阅读 prompt 中提供的代码注释标注上下文 → 查找变更附近的安全相关注释（`// SECURITY:` / `// @audit` / `// WARNING:`）
+3. 获取安全敏感文件的 diff：`git diff "<fork_point>"..HEAD --name-only`
+4. 阅读关键行 + git history 安全追踪：
+   - `git log --oneline -20 -- <file> | grep -i 'security\|CVE\|vuln\|fix\|audit\|CVE'` 查看安全相关历史
+   - 标记曾因安全原因修改过的区域
+5. 逐项通过 Checklist（P0 → P1 → P2 → P3 → P4 → P5 → 🔴 → 🟡）
+6. 额外维度：检查 CLAUDE.md 中明确禁止的安全模式是否在当前变更中出现
+7. 输出结构化报告（含证据链）
+
+## Output Format
+
+仅输出以下格式的审查报告（每个 issue 后附加证据来源）：
+
+## 安全审查报告
+
+### P0 — 数据隔离（数据安全事故）
+1. **[文件:行号]** 问题描述 -> 修复建议
+   **证据**：🧾 CLAUDE.md → `CLAUDE.md`#L行号 "规范条款原文"
+
+### P1 — 认证与会话
+1. **[文件:行号]** 问题描述 -> 修复建议
+   **证据**：📜 git log → `commit_hash`: 该区域曾因安全问题修复过
+
+### P2 — 授权与越权
+1. **[文件:行号]** 问题描述 -> 修复建议
+   **证据**：📝 `// SECURITY:` 注释原文 at `文件:行号`
+
+### 🔴 禁止（Block）
+1. **[文件:行号]** 问题描述 -> 修复建议
+   **证据**：🧾 CLAUDE.md → `CLAUDE.md`#L行号 "规范条款原文"
+
+### 🟡 必须（Request Changes）
+1. **[文件:行号]** 问题描述 -> 修复建议
+
+**证据类型符号**：
+- 🧾 CLAUDE.md 规范条款
+- 📜 git log 安全修复历史上下文
+- 📝 代码注释（SECURITY / @audit / WARNING）
+
+评分：P0 存在（必须修复）| 存在 🔴/🟡（Request Changes）| 全通过（Approve）

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/skills/reef-review/SKILL.md.tmpl

@@ -12,7 +12,7 @@ deepstorm:
 
 ## 工作流
 
-### Step 1: 检测变更范围
+### Step 1: 检测变更范围 + Eligibility 预检
 
 ```bash
 # 获取 fork-point（检测当前分支基于哪个分支创建）
@@ -28,6 +28,14 @@ BACKEND_FILES=$(git diff "$FORK_POINT"..HEAD --name-only -- {{reef.backend.langu
 FRONTEND_FILES=$(git diff "$FORK_POINT"..HEAD --name-only -- {{reef.frontend.framework.sourcePath}})
 INFRA_FILES=$(git diff "$FORK_POINT"..HEAD --name-only | grep -v '^{{reef.backend.language.sourcePath}}' | grep -v '^{{reef.frontend.framework.sourcePath}}')
 SECURITY_FILES=$(git diff "$FORK_POINT"..HEAD --name-only -- {{reef.backend.language.sourcePath}} {{reef.frontend.framework.sourcePath}} | grep -iE 'auth|tenant|security|oauth|token|password|permission' || true)
+
+# Eligibility 预检：明显不需要审查的变更跳过派发
+LOCK_ONLY=$(echo "$FILE_LIST" | grep -cE 'package-lock\.json|yarn\.lock|pnpm-lock\.yaml' || true)
+DOCS_ONLY=$(echo "$FILE_LIST" | grep -vE 'package-lock\.json|yarn\.lock|pnpm-lock\.yaml' | grep -cE '\.md$|\.txt$|^docs/' || true)
+if [ "$LOCK_ONLY" -gt 0 ] && [ "$(echo "$FILE_LIST" | wc -l | tr -d ' ')" -eq "$LOCK_ONLY" ]; then
+  echo "ELIGIBLE=false"
+  echo "REASON=仅 lock 文件变更，跳过代码审查"
+fi
 ```
 
 判断哪些类别有变更：
@@ -40,7 +48,7 @@ SECURITY_FILES=$(git diff "$FORK_POINT"..HEAD --name-only -- {{reef.backend.lang
 | 安全敏感 | `SECURITY_FILES` 非空 |
 | 无匹配 | 全部为空 |
 
-据此决定派发哪些 agent：
+据此决定派发哪些 agent（如果 ELIGIBLE=false 则不派发）：
 
 | 有变更的类别 | 派发 agent |
 |-------------|-----------|
@@ -56,24 +64,71 @@ SECURITY_FILES=$(git diff "$FORK_POINT"..HEAD --name-only -- {{reef.backend.lang
 
 > 安全敏感变更判定：SECURITY_FILES 非空 或 变更涉及权限/认证逻辑（由调用的 fork-point 范围决定）。
 
-### Step 2: 派发 Sub‑Agent
-
-每个 agent 按各自类别的文件清单构造 prompt。后端 agent 的清单含后端源文件，前端和 infra agent 只含自己的文件。
+### Step 2: 收集上下文 + 派发 Sub‑Agent
 
-| Agent | prompt 中的文件清单 |
-|-------|-------------------|
-| `backend-code-audit` | 后端文件 |
-| `frontend-code-audit` | 前端文件 |
-| `infra-code-audit` | 基础配置文件 |
-| `security-code-audit` | 安全敏感文件 + 所有变更文件中有安全风险的 diff |
+在派发前，收集 CLAUDE.md 和 git 上下文，透传给每个 agent：
 
+```bash
+# 收集根目录 CLAUDE.md 和变更文件夹下的 CLAUDE.md
+CLAUDE_MD_FILES=$(echo "$FILE_LIST" | xargs -I{} dirname {} | sort -u | xargs -I{} sh -c '
+  if [ -f "{}/CLAUDE.md" ]; then echo "{}/CLAUDE.md"; fi
+' 2>/dev/null)
+[ -f "CLAUDE.md" ] && CLAUDE_MD_FILES="CLAUDE.md $CLAUDE_MD_FILES"
+
+# 收集 git blame 摘要（取前 5 个变更文件的 git log 历史）
+GIT_HISTORY_SUMMARY=$(echo "$BACKEND_FILES $FRONTEND_FILES" | tr ' ' '\n' | sort -u | grep -v '^$' | head -5 | while IFS= read -r f; do
+  echo "--- $f ---"
+  git log --oneline -10 -- "$f" 2>/dev/null | head -5
+done)
+
+# 收集代码注释上下文（FIXME / HACK / WARNING 标注）
+COMMENT_CONTEXT=$(echo "$BACKEND_FILES $FRONTEND_FILES" | tr ' ' '\n' | sort -u | grep -v '^$' | head -10 | while IFS= read -r f; do
+  if [ -f "$f" ]; then
+    matches=$(git diff "$FORK_POINT"..HEAD -- "$f" | grep -E '^\+' | grep -iE 'FIXME|HACK|WARNING|SECURITY|@audit|TODO' || true)
+    [ -n "$matches" ] && echo "--- $f ---" && echo "$matches"
+  fi
+done)
 ```
+
+每个 agent 的 prompt 构造为标准前缀 + 上下文数据 + false positive 规则：
+
+```markdown
+## 变更上下文
+
 Fork point: {FORK_POINT}
 变更文件数: {count}
 变更文件清单:
 {file_list}
+
+## 相关规范文件（CLAUDE.md）
+
+{CLAUDE_MD_FILES_content}
+
+## Git 历史上下文
+
+{GIT_HISTORY_SUMMARY}
+
+## 代码注释标注
+
+{COMMENT_CONTEXT}
+
+## 不算 issues 的情况（不要误报）
+
+- 已经有 lint/typecheck/CI 保障的问题（import 错误、类型错误、格式问题）
+- 新增功能的测试覆盖率不足（非本变更范围）
+- 变更前的已有问题（pre-existing issue），除非变更使之更严重
+- NPM/Gradle 版本更新中的上游 breaking change
+- 与模块内已有实现一致的新增代码（一致性值得保留，除非原实现就有 bug）
+- 纯格式/空白/注释变更
 ```
 
+| Agent | prompt 中的文件清单 |
+|-------|-------------------|
+| `backend-code-audit` | 后端文件 |
+| `frontend-code-audit` | 前端文件 |
+| `infra-code-audit` | 基础配置文件 |
+| `security-code-audit` | 安全敏感文件 |
+
 Agent 的 system prompt（定义在 `.claude/agents/` 目录中）包含完整的 Checklist + Rules + 输出格式。
 
 | Agent | 定义文件 |
@@ -85,10 +140,15 @@ Agent 的 system prompt（定义在 `.claude/agents/` 目录中）包含完整
 
 多 agent 场景全部使用 `run_in_background: true` 并行执行。每个 agent 设置超时 300 秒（5 分钟），超时未返回则标记为超时，继续等待其他 agent。
 
-### Step 3: 汇总报告
+### Step 3: 汇总报告（含证据链评分）
 
 1. 等待所有已派发的 agent 返回（收到全部 task-notification 后才汇总）。任一 agent 超时 300 秒未返回则标记为超时，继续等待其他 agent
-2. 分章节输出各 agent 的审查报告：
+2. 聚合评分规则：
+   - 若 Block 项附有证据链（🧾 `.md` / 📜 `git log` / 📝 `// comment` / 📚 `context7` / 🛠 `style-*`），保留原评级
+   - 若 Block 项**无**证据链，降级为 Request Changes
+   - 若 Request Changes 项无证据链，降级为 Suggestion
+   - 确保报告不膨胀，每个 issue 一句话 + 一个链接
+3. 分章节输出各 agent 的审查报告：
 
 ```
 ## 后端代码审查报告
@@ -104,4 +164,4 @@ Agent 的 system prompt（定义在 `.claude/agents/` 目录中）包含完整
 {security agent 输出（仅安全敏感变更时）}
 ```
 
-3. 最终结论取最低评分。若某 agent 失败（API Error / 超时等），标注失败原因，忽略其评分。仅有派发过的 agent 输出对应章节。
+4. 最终结论取最低评分。若某 agent 失败（API Error / 超时等），标注失败原因，忽略其评分。仅有派发过的 agent 输出对应章节。

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/variants/java/quick-reference.md

@@ -62,6 +62,20 @@
   }
   ```
 
+### 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）
 
 当实体层次（如 `FormControl` → `TextControl` / `NumberControl` / ...）需要按子类暴露能力时，在抽象基类中声明抽象方法，各子类返回 `true` / `false`：

package/package.json

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