diff --git a/.agents/skills/monisuo-dev/SKILL.md b/.agents/skills/monisuo-dev/SKILL.md index e655bf9..c00ac5b 100644 --- a/.agents/skills/monisuo-dev/SKILL.md +++ b/.agents/skills/monisuo-dev/SKILL.md @@ -1,756 +1,140 @@ --- name: monisuo-dev -description: Monisuo 项目结构化开发流程技能。用于需求分析、模块化开发、测试验证、构建部署的完整工作流。 +description: Monisuo 项目结构化开发流程。需求分析 → 架构设计 → 开发 → 测试构建。 --- -# Monisuo 开发技能 +# Monisuo 开发工作流 -用于 Monisuo 项目的结构化开发流程，确保代码质量和开发效率。 - -## 工作流程 +## 流程概览 ``` -需求分析 → 模块化开发 → [启动独立Agent] → 测试验证 → 构建部署 - ↑ │ - └──────────── Bug 修复 ←───────────────────┘ +Phase 1: 需求定义 → Phase 1.5: 架构设计 → Phase 2: 模块化开发 → [启动 Agent] → Phase 3-4: 测试+构建 + ↑ │ + └──────────────────────── Bug 修复 ←─────────────────────────────────────────┘ ``` -## ⚠️ 多 Agent 执行策略 +**Phase 1-1.5-2 在主对话完成，Phase 3-4 启动独立 Agent。** -为避免上下文过长，**Phase 3-4 必须启动独立 Agent 执行**。 +--- -### Agent 切换点 +## Phase 1: 需求定义 -``` -Phase 1-2: 主对话完成（需求 + 开发） - ↓ - ↓ 开发完成后，启动独立 Agent - ↓ -Phase 3-4: 独立 Agent 完成（测试 + 构建） - ↓ - ↓ 如发现 Bug，返回主对话修复 - ↓ -重新启动 Agent 测试验证 -``` +将用户需求结构化为 Feature Spec，输出到 `docs/features/[feature-name].md`。 -### Agent 通信协议 - -**传递给测试 Agent 的信息**: -```yaml -feature_spec: docs/features/[feature-name].md # Feature Spec 路径 -changed_files: # 变更的文件列表 - - src/main/java/com/example/... - - flutter_monisuo/lib/... -test_requirements: # 测试要求 - - API 测试 - - Flutter 单元测试 - - 代码审查 -build_targets: # 构建目标 - - spring-boot - - flutter-web -``` - -## Phase 1: 需求结构化定义 (Prompt Engineering) - -### 目标 -将模糊的需求转化为结构化的 Feature Spec 文档。 - -### 输入 -- 用户的需求描述（自然语言） -- 业务场景说明 -- 技术约束条件 - -### 输出 -- `docs/features/feature-name.md` - 结构化的功能规格文档 - -### Feature Spec 模板 +### Feature Spec 结构 ```markdown -# [功能名称] 功能规格 +# [功能名称] -## 1. 功能概述 -- **功能名称**: -- **优先级**: P0/P1/P2 -- **负责人**: -- **预计工期**: +## 概述 +功能名称 / 优先级(P0-P2) / 业务背景(痛点→方案→收益) -## 2. 业务背景 -- 当前痛点 -- 解决方案 -- 预期收益 - -## 3. 功能详情 - -### 3.1 用户故事 +## 用户故事 作为 [角色]，我希望 [行为]，以便 [目的] -### 3.2 功能列表 -- [ ] 功能点 1 -- [ ] 功能点 2 -- [ ] 功能点 3 +## 功能列表 +- [ ] 功能点1 +- [ ] 功能点2 -### 3.3 UI/UX 设计 -- 页面布局 -- 交互流程 -- 原型链接 +## 技术方案（Phase 1.5 填充） +### API 设计 +### 数据模型 +### 技术决策 -## 4. 技术方案 +## 测试用例 +- [ ] 正常 / 异常 / 边界 -### 4.1 架构设计 -- 前端方案 (Flutter) -- 后端方案 (Spring Boot) -- 数据库设计 - -### 4.2 API 设计 -``` -GET /api/endpoint -POST /api/endpoint -``` - -### 4.3 数据模型 -```dart -class Model { - final String id; - // ... -} -``` - -## 5. 测试用例 -- [ ] 正常流程测试 -- [ ] 异常流程测试 -- [ ] 边界条件测试 - -## 6. 验收标准 -- [ ] 功能完整 -- [ ] 测试通过 -- [ ] 代码审查 -- [ ] 性能达标 - -## 7. 依赖与风险 -- 依赖项 -- 潜在风险 -- 缓解措施 +## 验收标准 ``` ### 执行步骤 - -1. **需求收集** - ```bash - # 与用户确认需求 - # 识别关键业务场景 - # 明确技术约束 - ``` - -2. **创建文档** - ```bash - mkdir -p docs/features - touch docs/features/[feature-name].md - ``` - -3. **填充模板** - - 完善用户故事 - - 设计 API 接口 - - 定义数据模型 - - 编写测试用例 - -4. **评审确认** - - 与用户确认需求理解正确 - - 调整优先级和范围 +1. 与用户确认需求，识别关键场景和约束 +2. 创建 `docs/features/[feature-name].md`，填充概述、用户故事、功能列表、测试用例 +3. 与用户评审确认 --- -## Phase 2: 模块化生成 (Iterative Coding) +## Phase 1.5: 架构设计 -### 目标 -根据 Feature Spec 分模块实现功能。 +编码前确定技术方案。**必须先探索代码库再设计。** -### 开发策略 +### 执行步骤 + +1. **探索现有代码库** + - Glob/Grep/Read 扫描相关模块，理解现有模式和架构 + - 识别可复用的组件、Service、工具类 + - 确认集成点 + +2. **定义 API 契约** — 方法、路径、请求/响应体，写入 Spec 的「API 设计」 + +3. **设计数据模型** — 表结构、Entity/DTO/VO 映射，写入 Spec 的「数据模型」 + +4. **记录技术决策** — 选型理由、模块职责、关键约束，写入 Spec 的「技术决策」 + +### 完成标准 +- 已扫描现有代码，无重复造轮子 +- API 契约完整，前后端可并行开发 +- 数据模型与现有表结构兼容 + +--- + +## Phase 2: 模块化开发 + +依据 Spec 中的 API 契约和数据模型，自底向上开发： -#### 2.1 按模块拆分 ``` -Feature -├── Frontend (Flutter) -│ ├── UI 组件 -│ ├── 状态管理 (Provider) -│ └── API 调用 (Dio) -├── Backend (Spring Boot) -│ ├── Controller -│ ├── Service -│ └── Repository -└── Database - └── Migration Scripts -``` - -#### 2.2 迭代开发顺序 - -1. **数据层优先** - - 数据库表结构 - - Entity 定义 - - Repository 实现 - -2. **后端 API** - - Controller 接口 - - Service 业务逻辑 - - 单元测试 - -3. **前端实现** - - Model 定义 - - API Service - - UI 组件 - - 状态管理 - -### 开发命令 - -```bash -# Flutter 开发 -cd flutter_monisuo -flutter pub get -flutter run -d chrome - -# 后端开发 -cd ../ -mvn spring-boot:run +1. 数据层 → 2. 后端 API → 3. 前端实现 + DDL/Entity Controller/Service Model/Provider/UI ``` ### 代码规范 - -#### Flutter -- 使用 `flutter analyze` 检查代码 -- 遵循 Effective Dart 规范 -- 使用 Provider 进行状态管理 -- 统一使用 AppSpacing, AppRadius, AppColorScheme - -#### Spring Boot -- 遵循阿里巴巴 Java 开发手册 -- 使用 Lombok 简化代码 -- 统一异常处理 -- RESTful API 设计 - -### 🔄 Phase 2 完成后：启动测试 Agent - -**当开发完成后，立即启动独立 Agent 执行测试和构建**。 - -使用 Agent tool 启动： - -``` -subagent_type: general-purpose -description: 测试验证与构建 -prompt: | - 你是 Monisuo 项目的测试 Agent。请执行以下任务： - - ## 1. 读取 Feature Spec - - 文件路径: docs/features/[feature-name].md - - 理解功能需求和验收标准 - - ## 2. 代码审查 - - 检查变更的文件（见 git diff） - - 验证代码规范 - - 检查错误处理 - - ## 3. 执行测试 - - API 测试: ./tests/api/test-[feature].sh - - Flutter 测试: cd flutter_monisuo && flutter test - - 后端测试: mvn test - - ## 4. 构建 - - 后端: mvn clean package -DskipTests - - Flutter: flutter build web --release --dart-define=ENV=prod - - ## 5. 输出结果 - - 测试通过/失败 - - Bug 列表（如有） - - 构建产物路径 - - 如果发现 Bug，列出详细信息和修复建议，返回给主对话修复。 -``` +- Flutter: `flutter analyze` 无错，用 AppSpacing/AppRadius/AppColorScheme，禁止硬编码颜色 +- Java: Lombok 简化，资金变动方法加 `@Transactional(rollbackFor = Exception.class)`，RESTful 设计 --- -## Phase 3: 测试与重构 (Validation & Refactoring) +## Phase 3-4: 测试与构建（独立 Agent） -> ⚠️ **此阶段由独立 Agent 执行**，主对话只负责接收结果和修复 Bug。 +Phase 2 完成后，启动独立 Agent 执行测试和构建。 -### 目标 -确保代码质量和功能正确性。 - -### 3.1 使用 Clean Code 技能 - -```bash -# 应用 clean-code 技能进行代码优化 -# 参考: ~/.agents/skills/clean-code/SKILL.md -``` - -**优化重点**: -- 代码可读性 -- 函数复杂度 -- 重复代码 -- 命名规范 - -### 3.2 自动化测试 - -#### API 接口测试 - -**测试脚本位置**: `tests/api/` - -**测试脚本模板**: -```bash -#!/bin/bash -# API 测试脚本 - -BASE_URL="http://localhost:5010" -TOKEN="" - -echo "=== API 测试开始 ===" - -# 1. 登录测试 -echo "1. 测试登录接口..." -RESPONSE=$(curl -s -X POST "$BASE_URL/api/auth/login" \ - -H "Content-Type: application/json" \ - -d '{"phone":"13800138000","password":"123456"}') - -TOKEN=$(echo $RESPONSE | jq -r '.data.token') -echo "✓ 登录成功，Token: ${TOKEN:0:20}..." - -# 2. 获取用户信息 -echo "2. 测试获取用户信息..." -curl -s -X GET "$BASE_URL/api/user/info" \ - -H "Authorization: Bearer $TOKEN" | jq '.' -echo "✓ 获取用户信息成功" - -# 3. 更多测试用例... -# TODO: 根据具体功能添加 - -echo "=== API 测试完成 ===" -``` - -**运行测试**: -```bash -chmod +x tests/api/test-*.sh -./tests/api/test-feature.sh -``` - -#### Flutter 单元测试 - -```bash -cd flutter_monisuo -flutter test -``` - -### 3.3 Bug 修复循环 +### 启动 Agent ``` -Agent 测试 → 发现 Bug → 主对话修复 → 重新启动 Agent → 通过 +Agent( + description: "测试验证与构建", + prompt: | + 你是 Monisuo 项目测试 Agent，独立完成以下任务，不要询问用户。 + + ## 1. 读取 Spec + - 路径: docs/features/[feature-name].md + - 理解验收标准 + + ## 2. 代码审查 + - git diff 查看变更 + - Flutter: flutter analyze, AppSpacing/AppRadius/AppColorScheme 规范 + - Java: @Transactional 资金方法, 统一异常处理, RESTful 设计 + + ## 3. 测试 + - 后端: mvn test + - Flutter: cd flutter_monisuo && flutter test + - API: ./tests/api/test-[feature].sh（如存在） + + ## 4. 构建 + - 后端: mvn clean package -DskipTests → target/monisuo-*.jar + - Flutter: cd flutter_monisuo && flutter build web --release --dart-define=ENV=prod → build/web/ + + ## 5. 输出报告 + | 项目 | 状态 | 备注 | + |------|------|------| + | 代码审查 | ✅/❌ | | + | 后端测试 | ✅/❌ | | + | Flutter 测试 | ✅/❌ | | + | 后端构建 | ✅/❌ | | + | Flutter 构建 | ✅/❌ | | + + 如有 Bug，列出：文件、原因、修复建议。返回主对话修复后重新验证。 +) ``` -**修复流程**: -1. Agent 报告 Bug -2. **主对话**修复代码 -3. **重新启动 Agent** 验证修复 -4. 直到全部通过 - -### 3.4 重新启动测试 Agent - -Bug 修复后，再次启动 Agent 验证： - -``` -subagent_type: general-purpose -description: 验证 Bug 修复 -prompt: | - 验证以下 Bug 是否已修复： - - ## Bug 列表 - [从上次 Agent 结果中获取] - - ## 验证步骤 - 1. 重新运行相关测试 - 2. 确认 Bug 已修复 - 3. 检查是否有回归问题 - - 输出：修复确认 / 仍需修复 -``` - -### 3.4 代码审查清单 - -- [ ] 代码符合规范 -- [ ] 无硬编码值 -- [ ] 错误处理完善 -- [ ] 日志记录清晰 -- [ ] 测试覆盖完整 -- [ ] 性能达标 - ---- - -## Phase 4: 构建与部署 (Build & Deploy) - -> ⚠️ **此阶段由独立 Agent 执行**，与 Phase 3 合并在同一个 Agent 中。 - -### 目标 -构建生产版本并提交代码。 - -### 4.1 构建命令 - -#### 后端 (Spring Boot) -```bash -# 清理并打包（跳过测试） -mvn clean package -DskipTests - -# 完整构建（包含测试） -mvn clean package - -# 只编译检查 -mvn compile -``` - -**输出**: `target/monisuo-*.jar` - -**验证构建**: -```bash -# 检查 JAR 文件是否生成 -ls -la target/*.jar - -# 测试 JAR 可执行性 -java -jar target/monisuo-*.jar --spring.profiles.active=dev -``` - -#### Flutter Web -```bash -cd flutter_monisuo -flutter build web --release --dart-define=ENV=prod -``` - -**输出**: `flutter_monisuo/build/web/` - -#### Admin 后台 -```bash -cd monisuo-admin -pnpm install -pnpm build -``` - -**输出**: `monisuo-admin/dist/` - -### 4.2 Git 提交流程 - -```bash -# 1. 检查变更 -git status -git diff - -# 2. 添加文件 -git add . - -# 3. 提交（遵循 Conventional Commits） -git commit -m "feat(module): 简短描述 - -- 详细说明 1 -- 详细说明 2 -- 详细说明 3 - -Closes #issue-number" - -# 4. 推送到远程 -git push origin main -``` - -### 4.3 提交消息规范 - -**格式**: -``` -(): - - - -