cursorrules

ZhiWei（知微）项目开发规范

基于项目最新架构文档（docs/ARCHITECTURE.md）和实际技术栈 最后更新：2026-03

---

一、项目技术栈总览

后端（Spring Boot）

• 语言: Java 22（优先使用 Record、Sealed Interface、Pattern Matching、Virtual Thread）
• 框架: Spring Boot 3.5.3
• AI 集成: Spring AI 1.1.2（Advisor 模式、MCP 支持、结构化输出）
• 构建: Maven 3.9.x
• 数据库: SQLite 3.49+（WAL 模式、FTS5 全文索引）+ sqlite-vec 0.1.x（向量存储）
• 迁移: Flyway 10.x

前端（Vue 3 SPA）

• 框架: Vue 3.5+（Composition API + <script setup lang="ts">）
• UI 组件库: Reka UI 2.x（不是 shadcn-vue）
• 样式系统: Tailwind CSS 4.x + CSS Variables
• 状态管理: Pinia 3.x
• 路由: Vue Router 4.x
• 图标库: lucide-vue-next
• 构建工具: Vite 6.x

---

二、后端开发规范

2.1 Java 代码风格

必须使用 Java 22 特性：

• Record：用于不可变数据传输对象（DTO）、事件封装
• Sealed Interface/Class：用于有限状态机、策略模式
• Pattern Matching：instanceof + switch 模式匹配
• Virtual Thread：IO 密集型操作优先使用

// ✅ 正确：使用 Record 作为 DTO
public record ChatRequest(String sessionId, List<Message> messages) {}

// ✅ 正确：Sealed Interface 限制实现
public sealed interface AgentState permits IdleState, RunningState, WaitingState {
    AgentState transition(Event event);
}

// ✅ 正确：Pattern Matching
public String describe(Object obj) {
    return switch (obj) {
        case String s -> "字符串: " + s;
        case Number n -> "数字: " + n;
        case null -> "空值";
        default -> "未知类型";
    };
}

禁止事项：

• 禁止使用 Lombok @Data（改用 Record 或手动定义 getter/setter）
• 禁止使用 public 字段暴露数据（使用封装）
• 禁止魔法数字/字符串（使用常量枚举或配置类）

2.2 包结构规范

com.lifepilot/
├── llm/              # 多模型路由、熔断器、故障转移
├── agent/            # Agent 控制循环、状态机、上下文组装
├── tool/             # 工具契约、动态注册、执行管道
├── guardrail/        # 安全护栏策略
├── mcp/              # Model Context Protocol 客户端/服务器
├── memory/           # 四层记忆（工作/情景/语义/程序）
├── knowledge/        # 知识库、文档解析、检索
├── skill/            # Skill 注册、热加载、自扩展
├── interaction/      # CLI/Web/Channel 适配器
├── conversation/     # 对话历史、会话管理
├── datastore/        # 通用数据存储（Schema-Free JSON）
├── workflow/         # YAML 声明式工作流
├── sandbox/          # 代码执行沙箱
├── media/            # 多模态处理
├── sync/             # 外部数据源同步
├── eval/             # Agentic Evals 评估框架
├── multiagent/       # 多 Agent 协作
├── a2a/              # A2A 协议实现
├── marketplace/      # 插件市场
├── meta/             # 元能力
├── prompt/           # Prompt 模板管理
├── notification/     # 统一通知系统
├── observability/    # 轨迹记录、可观测性
└── config/           # 全局配置