@deepstorm/cli 0.1.0

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

@@ -0,0 +1,134 @@
+---
+name: reef-style-backend
+description: 后端编码规范（{{reef.backend.language.label}}）。包含实体层次、DTO、Service/Controller/Repository 模式、MapStruct、多租户安全等完整规范。创建/修改后端代码时必须按本技能输出。
+user-invocable: false
+allowed-tools: Bash(git:*), Bash({{reef.backend.language.buildTool}})
+deepstorm:
+  tool: reef
+  configKey: reef.backend.language
+---
+
+# 后端编码规范
+
+## ⚠️ 触发条件（必须遵守）
+
+创建或修改任何后端文件时，必须通过 Skill tool 加载本技能，并按本技能中所有规范输出代码。对应技术栈：{{reef.backend.language.label}}。
+
+> **仅对本次新增/修改的代码应用规范，不格式化已有代码。** 已有的、本次未修改的代码行保持原样。
+
+## 维度规范
+
+{{#if reef.backend.language.styleRef}}
+### 语言/平台规范
+{{reef.backend.language.styleRef}}
+{{/if}}
+
+{{#if reef.backend.java.framework.styleRef}}
+### Java 框架规范
+{{reef.backend.java.framework.styleRef}}
+{{/if}}
+
+{{#if reef.backend.java.orm.styleRef}}
+### ORM 框架规范
+{{reef.backend.java.orm.styleRef}}
+{{/if}}
+
+{{#if reef.backend.java.dbMigration.styleRef}}
+### 数据库迁移规范
+{{reef.backend.java.dbMigration.styleRef}}
+{{/if}}
+
+{{#if reef.backend.java.ai.styleRef}}
+### AI 框架规范
+{{reef.backend.java.ai.styleRef}}
+{{/if}}
+
+{{#if reef.backend.java.test.styleRef}}
+### 🧪 测试规范
+
+#### 通用原则
+- **测试金字塔**：Unit（单元测试）→ Integration（集成测试）→ E2E（端到端测试）。越底层测试越多，运行速度越快
+- **FIRST 原则**：Fast（快速）、Independent（独立）、Repeatable（可重复）、Self-validating（自验证）、Timely（及时）
+- **AAA 模式**：Arrange（准备测试数据）→ Act（执行被测方法）→ Assert（验证结果）
+
+#### 框架规范
+{{reef.backend.java.test.styleRef}}
+{{/if}}
+
+{{#if reef.backend.java.framework.styleRef}}
+### 📐 API 规范
+→ 参考 [API 规范](api-spec.md)
+
+包括：RESTful 资源命名、统一响应体 `ApiResponse<T>` / `PageResponse<T>` / `ErrorResponse`、版本策略、OpenAPI 文档注解、分页约定、错误码命名规范。
+{{/if}}
+
+{{#if reef.backend.java.framework.styleRef}}
+### 📦 依赖管理规范
+→ 参考 [依赖管理规范](dependency-management.md)
+
+包括：Gradle Version Catalog（`libs.versions.toml`）、禁止硬编码版本号、版本一致性规则、Gradle Versions Plugin、CVE 管理、禁止使用的依赖。
+{{/if}}
+
+{{#if reef.backend.java.framework.styleRef}}
+### 🚨 异常处理深度规范
+→ 参考 [异常处理规范](exception-handling.md)
+
+包括：业务异常继承层次、错误码枚举约定（`{MODULE}_{NNN}`）、`@RestControllerAdvice` 全局处理、`ErrorResponse` 结构、异常与 HTTP Status 映射。
+{{/if}}
+
+{{#if reef.backend.java.framework.styleRef}}
+### 🔒 安全红线
+→ 参考 [安全红线](security-redlines.md)
+
+包括：密码存储（BCrypt）、SQL 注入防范、危险初始化（`@PostConstruct`）、硬编码密钥、敏感信息脱敏、文件上传验证。**所有 P0 红线不得违反。**
+{{/if}}
+
+{{#if reef.backend.python.framework.styleRef}}
+### 📐 API 规范（Python）
+→ 参考 [API 规范](api-spec.md)
+
+包括：RESTful 资源命名、统一响应体 `ApiResponse` / `PageResponse` / `ErrorResponse`、版本策略、FastAPI OpenAPI 配置、分页约定。
+{{/if}}
+
+{{#if reef.backend.python.framework.styleRef}}
+### 📦 依赖管理规范（Python）
+→ 参考 [依赖管理规范](dependency-management.md)
+
+包括：`pyproject.toml` 结构、禁止通配符版本、`uv` 命令速查、依赖分组（运行/开发）、CVE 审计（`uv audit`）。
+{{/if}}
+
+{{#if reef.backend.python.framework.styleRef}}
+### 🚨 异常处理深度规范（Python）
+→ 参考 [异常处理规范](exception-handling.md)
+
+包括：`AppError(HTTPException)` 继承层次、错误码枚举、FastAPI `@app.exception_handler` 全局处理、兜底 500 处理。
+{{/if}}
+
+{{#if reef.backend.python.framework.styleRef}}
+### 🔒 安全红线（Python）
+→ 参考 [安全红线](security-redlines.md)
+
+包括：密码哈希（bcrypt/passlib）、SQL 注入防范、硬编码密钥、敏感信息脱敏、Pydantic 输入验证红线、CORS 配置、生产环境禁用调试接口。**所有 P0 红线不得违反。**
+{{/if}}
+
+## 知识文件
+
+以下文件位于本技能目录，安装时自动复制。内容按所选维度定制。
+
+加载本技能时先用 `Read` 读取 `quick-reference.md` 了解核心规范，再按照上方「维度规范」中的链接选择对应文件加载（如 `spring-boot.md`、`hibernate.md`），最后根据当前变更类型在 `examples/` 目录中选择示例文件：
+
+| 文件 | 说明 |
+|------|------|
+| `quick-reference.md` | **编码规范速查**。包含核心规则和约定 |
+| `{value}.md` | **维度规范**（如 `spring-boot.md`、`hibernate.md`）。按上方链接加载 |
+| `api-spec.md` | **API 规范**。RESTful 命名、统一响应体、版本策略、OpenAPI |
+| `dependency-management.md` | **依赖管理规范**。Version Catalog、版本一致性、CVE |
+| `exception-handling.md` | **异常处理深度规范**。异常层次、错误码、全局处理 |
+| `security-redlines.md` | **安全红线**。P0/P1 安全规则及代码示例 |
+| `examples/{文件}` | 按需加载示例文件（仅读与当前变更相关的） |
+
+## 使用方式
+
+- **创建/修改后端代码时**：Skill tool 自动加载（见触发条件）
+- `reef:reef-gen-backend` — 编写后端代码时自动加载
+- `reef:reef-review-backend` — 审查后端代码时自动加载

package/dist/skills/reef-style-backend/fragments/java/ai/spring-ai/examples/chat-client.md

@@ -0,0 +1,96 @@
+# Spring AI ChatClient 示例
+
+## 基础用法
+
+```java
+@Configuration
+public class AiConfig {
+
+  @Bean
+  ChatClient chatClient(ChatClient.Builder builder) {
+    return builder
+      .defaultSystem("你是一个专业的 Java 后端开发助手")
+      .defaultFunctions("getCurrentTime")  // 注册默认工具
+      .build();
+  }
+}
+```
+
+## Service 层集成
+
+```java
+@Service
+public class AiAssistantService {
+
+  private final ChatClient chatClient;
+
+  public AiAssistantService(ChatClient.Builder builder) {
+    this.chatClient = builder
+      .defaultSystem("""
+        你是企业应用开发助手。
+        回答问题时：
+        1. 引用代码规范
+        2. 提供完整的代码示例
+        3. 说明设计理由
+        """)
+      .build();
+  }
+
+  /**
+   * 生成代码建议
+   */
+  public String generateSuggestion(String question) {
+    return chatClient.prompt()
+      .user(u -> u.text("""
+        问题是: {question}
+        请用 Java + Spring Boot 实现。
+        """)
+        .param("question", question))
+      .call()
+      .content();
+  }
+}
+```
+
+## 多轮对话
+
+```java
+@Service
+public class ConversationService {
+
+  private final ChatClient chatClient;
+
+  public ConversationService(ChatClient.Builder builder) {
+    this.chatClient = builder.build();
+  }
+
+  public ChatResponse chat(String sessionId, String message) {
+    return chatClient.prompt()
+      .user(message)
+      .advisors(new MessageChatMemoryAdvisor(
+        new InMemoryChatMemory(), sessionId, 10  // 保留最近 10 轮
+      ))
+      .call()
+      .chatResponse();
+  }
+}
+```
+
+## 流式响应
+
+```java
+@RestController
+@RequestMapping("/api/ai")
+public class AiController {
+
+  private final ChatClient chatClient;
+
+  @PostMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
+  public Flux<String> streamResponse(@RequestBody @Valid ChatRequest request) {
+    return chatClient.prompt()
+      .user(request.message())
+      .stream()
+      .content();  // 返回 Flux<String>
+  }
+}
+```

package/dist/skills/reef-style-backend/fragments/java/ai/spring-ai/examples/rag.md

@@ -0,0 +1,94 @@
+# Spring AI RAG 示例
+
+## 向量存储配置
+
+```java
+@Configuration
+public class VectorStoreConfig {
+
+  @Bean
+  VectorStore pgVectorStore(JdbcTemplate jdbcTemplate) {
+    return new PgVectorStore(jdbcTemplate, new VectorStoreConfig());
+  }
+}
+```
+
+## 文档入库
+
+```java
+@Service
+public class DocumentIngestionService {
+
+  private final VectorStore vectorStore;
+
+  @PostConstruct
+  public void init() {
+    // 应用启动时加载知识库
+    loadDocuments("classpath:/docs/coding-standards/");
+  }
+
+  public void loadDocuments(String path) {
+    var reader = new JsonReader(new FileSystemResource(path));
+    List<Document> documents = reader.get();
+
+    // 添加元数据
+    documents.forEach(doc -> {
+      doc.getMetadata().put("source", "coding-standards");
+      doc.getMetadata().put("version", "1.0");
+    });
+
+    vectorStore.accept(documents);
+    log.info("已加载 {} 份规范文档", documents.size());
+  }
+}
+```
+
+## RAG 查询
+
+```java
+@Service
+public class RagQueryService {
+
+  private final ChatClient chatClient;
+  private final VectorStore vectorStore;
+
+  public String query(String question) {
+    return chatClient.prompt()
+      .user(question)
+      .advisors(new QuestionAnswerAdvisor(
+        vectorStore,
+        SearchRequest.defaults().withTopK(3)  // 检索 top-3 文档
+      ))
+      .call()
+      .content();
+  }
+}
+```
+
+## 自定义 Advisor
+
+```java
+@Component
+public class ContextFilterAdvisor implements CallAroundAdvisor {
+
+  @Override
+  public String getName() {
+    return "ContextFilterAdvisor";
+  }
+
+  @Override
+  public int getOrder() {
+    return 0;
+  }
+
+  @Override
+  public ChatClientResponse aroundCall(AdvisedRequest request, CallAroundAdvisorChain chain) {
+    // 在调用前过滤或增强上下文
+    AdvisedRequest filtered = AdvisedRequest.from(request)
+      .withSystemText(request.systemText() + "\n注意：仅基于现有文档回答问题，不要编造信息。")
+      .build();
+
+    return chain.nextAroundCall(filtered);
+  }
+}
+```

package/dist/skills/reef-style-backend/fragments/java/ai/spring-ai/examples/structured-output.md

@@ -0,0 +1,62 @@
+# Spring AI 结构化输出示例
+
+## 简单 Record
+
+```java
+public record WeatherResponse(String city, double temperature, String unit) {}
+
+// 使用
+WeatherResponse weather = chatClient.prompt()
+  .user("北京今天天气怎么样？")
+  .call()
+  .entity(WeatherResponse.class);
+
+log.info("城市: {}, 温度: {}{}", weather.city(), weather.temperature(), weather.unit());
+```
+
+## 嵌套结构
+
+```java
+public record CodeReviewResult(
+  String file,
+  List<Issue> issues,
+  int score
+) {
+  public record Issue(
+    int line,
+    Severity severity,
+    String message,
+    String suggestion
+  ) {
+    enum Severity { CRITICAL, WARNING, SUGGESTION }
+  }
+}
+
+// 使用
+CodeReviewResult result = chatClient.prompt()
+  .user("""
+    审查以下代码:
+    ```java
+    public class Test {
+      public void run() { }
+    }
+    ```
+    """)
+  .call()
+  .entity(CodeReviewResult.class);
+```
+
+## 列表输出
+
+```java
+public record TaskList(List<TaskItem> tasks) {
+  public record TaskItem(String title, String description, Priority priority) {
+    enum Priority { HIGH, MEDIUM, LOW }
+  }
+}
+
+TaskList tasks = chatClient.prompt()
+  .user("将用户需求拆解为开发任务")
+  .call()
+  .entity(TaskList.class);
+```

package/dist/skills/reef-style-backend/fragments/java/ai/spring-ai/examples/tool-calling.md

@@ -0,0 +1,68 @@
+# Spring AI Tool 调用示例
+
+## 基本 Tool
+
+```java
+@Service
+public class OrderTools {
+
+  /**
+   * 查询用户订单列表
+   */
+  @Tool(description = "根据用户 ID 查询订单列表")
+  public List<OrderDTO> getOrdersByUser(
+      @ToolParam(description = "用户 ID，数字格式") Long userId) {
+    // 实际调用 OrderService
+    return orderService.findByUserId(userId);
+  }
+
+  /**
+   * 获取订单详情
+   */
+  @Tool(description = "根据订单 ID 查询订单详情")
+  public OrderDTO getOrderDetail(
+      @ToolParam(description = "订单 ID") Long orderId) {
+    return orderService.findById(orderId);
+  }
+}
+```
+
+## 带权限校验的 Tool
+
+```java
+@Service
+public class SecureTools {
+
+  private final SecurityContext securityContext;
+
+  @Tool(description = "创建新订单")
+  public OrderDTO createOrder(
+      @ToolParam(description = "订单创建请求") CreateOrderRequest request) {
+    // 权限校验
+    User currentUser = securityContext.getCurrentUser();
+    if (!currentUser.hasPermission("order:create")) {
+      throw new SecurityException("无创建订单权限");
+    }
+    return orderService.create(request, currentUser.getId());
+  }
+}
+```
+
+## Tool 注册
+
+```java
+@Configuration
+public class ToolConfig {
+
+  private final OrderTools orderTools;
+  private final UserTools userTools;
+
+  @Bean
+  ChatClient assistantChatClient(ChatClient.Builder builder) {
+    return builder
+      .defaultSystem("你是订单管理助手")
+      .defaultTools(orderTools, userTools)  // 注册所有 Tool
+      .build();
+  }
+}
+```

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

@@ -0,0 +1,220 @@
+# Spring AI 开发规范
+
+## 概述
+
+Spring AI 是 Spring 生态中的 AI 集成框架，提供统一的 API 来调用 LLM、管理对话、构建 RAG 应用。
+
+## 核心概念
+
+### ChatClient
+Spring AI 的中央 API，用于与大语言模型交互。
+
+```java
+@Bean
+ChatClient chatClient(ChatClient.Builder builder) {
+    return builder.defaultSystem("你是一个专业的 Java 开发者助手").build();
+}
+```
+
+**最佳实践：**
+- `ChatClient` 声明为 `@Bean` 并注入使用，不直接创建实例
+- `defaultSystem()` 设置默认系统提示词
+- `builder.clone()` 创建独立的客户端实例（需要不同配置时）
+
+### Tool（函数调用）
+
+AI 模型调用外部工具的能力。
+
+```java
+@Tool(description = "获取用户订单信息")
+public List<Order> getOrders(@ToolParam(description = "用户 ID") String userId) {
+    return orderRepository.findByUserId(userId);
+}
+```
+
+**最佳实践：**
+- 每个 `@Tool` 方法加 `description` 描述，帮助模型选择正确的工具
+- `@ToolParam` 的 `description` 帮助模型理解参数含义
+- 工具方法放在 `@Service` 类中，统一管理
+- 返回值类型明确，避免 `Object` 或泛型丢失
+
+### Advisor（对话链）
+
+构建多步骤的 AI 处理流程。
+
+```java
+ChatClientResponse response = chatClient.prompt()
+    .advisors(new QuestionAnswerAdvisor(vectorStore, SearchRequest.defaults()))
+    .user("查询文档")
+    .call()
+    .content();
+```
+
+**常见 Advisor：**
+- `QuestionAnswerAdvisor` — RAG 支持
+- `MessageChatMemoryAdvisor` — 对话记忆
+- `LoggingAdvisor` — 日志记录
+
+### VectorStore
+
+向量数据库抽象，用于 RAG（检索增强生成）。
+
+```java
+@Service
+public class DocumentService {
+    private final VectorStore vectorStore;
+
+    public DocumentService(VectorStore vectorStore) {
+        this.vectorStore = vectorStore;
+    }
+
+    public void storeDocuments(List<Document> documents) {
+        vectorStore.accept(documents);
+    }
+
+    public List<Document> searchSimilar(String query) {
+        return vectorStore.similaritySearch(SearchRequest.query(query)
+            .withTopK(5));
+    }
+}
+```
+
+**最佳实践：**
+- VectorStore 通过 Spring DI 注入，不同实现（PGVector、Redis、Chroma）切换只需改配置
+- 文档入库时保留 metadata（来源、更新时间、权限）
+
+### Structured Output（结构化输出）
+
+将 AI 响应映射为 Java 对象。
+
+```java
+record WeatherResponse(String city, double temperature, String unit) {}
+
+WeatherResponse weather = chatClient.prompt()
+    .user("北京今天天气怎么样？")
+    .call()
+    .entity(WeatherResponse.class);
+```
+
+**最佳实践：**
+- 使用 `record` 而非 class 定义输出结构
+- 字段类型明确，避免 `String` 滥用
+
+## 配置
+
+```yaml
+spring:
+  ai:
+    openai:
+      api-key: ${OPENAI_API_KEY}
+      chat:
+        options:
+          model: gpt-4o
+          temperature: 0.7
+```
+
+**最佳实践：**
+- API Key 始终通过 `${}` 环境变量引用，不硬编码
+- 敏感配置放在 `.env` 文件中，不提交到 Git
+
+## DeepSeek
+
+DeepSeek 是一个高性能的国产大语言模型，通过 `spring-ai-starter-model-deepseek` 集成。
+
+### 配置
+
+```yaml
+spring:
+  ai:
+    deepseek:
+      api-key: ${DEEPSEEK_API_KEY}
+      chat:
+        options:
+          model: deepseek-chat
+          temperature: 0.7
+          max-tokens: 2048
+```
+
+**可用模型：**
+- `deepseek-chat` — 通用对话模型，适用于日常问答、代码生成、内容创作
+- `deepseek-reasoner` — 推理模型，适用于复杂推理、数学问题、逻辑分析（通过 API 调用，Spring AI Starter 暂未直接封装）
+
+### 使用示例
+
+```java
+@Service
+public class AiService {
+    private final ChatClient chatClient;
+
+    public AiService(ChatClient.Builder builder) {
+        this.chatClient = builder
+            .defaultSystem("你是一个专业的 Java 开发者助手")
+            .build();
+    }
+
+    public String chat(String message) {
+        try {
+            return chatClient.prompt()
+                .user(message)
+                .call()
+                .content();
+        } catch (Exception e) {
+            log.error("DeepSeek 调用失败", e);
+            return "抱歉，服务暂时不可用";
+        }
+    }
+}
+```
+
+### 依赖
+
+```groovy
+// build.gradle
+implementation 'org.springframework.ai:spring-ai-starter-model-deepseek'
+```
+
+或 Maven：
+```xml
+<dependency>
+    <groupId>org.springframework.ai</groupId>
+    <artifactId>spring-ai-starter-model-deepseek</artifactId>
+</dependency>
+```
+
+## 依赖管理
+
+```groovy
+// build.gradle
+implementation 'org.springframework.ai:spring-ai-openai-spring-boot-starter'
+// 如需 RAG
+implementation 'org.springframework.ai:spring-ai-pgvector-store-spring-boot-starter'
+```
+
+或 Maven：
+```xml
+<dependency>
+    <groupId>org.springframework.ai</groupId>
+    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
+</dependency>
+```
+
+## 错误处理
+
+```java
+try {
+    String response = chatClient.prompt().user("查询数据").call().content();
+    // 处理响应
+} catch (AiException e) {
+    log.error("AI 调用失败", e);
+    // 降级处理
+}
+```
+
+**注意事项：**
+- AI 调用可能失败或超时，必须有降级逻辑
+- 记录 AI 调用的输入和输出，便于调试和审计
+
+## 参考资料
+
+- [Spring AI 官方文档](https://docs.spring.io/spring-ai/reference/)
+- 示例文件见 `examples/` 目录