Files

sion e81ff256a4 优化

2026-03-26 00:17:56 +08:00

15 KiB

Raw Blame History

name, description

name	description
monisuo-dev	Monisuo 项目结构化开发流程技能。用于需求分析、模块化开发、测试验证、构建部署的完整工作流。

Monisuo 开发技能

用于 Monisuo 项目的结构化开发流程，确保代码质量和开发效率。

工作流程

需求分析 → 模块化开发 → [启动独立Agent] → 测试验证 → 构建部署
   ↑                                          │
   └──────────── Bug 修复 ←───────────────────┘

⚠️ 多 Agent 执行策略

为避免上下文过长，Phase 3-4 必须启动独立 Agent 执行。

Agent 切换点

Phase 1-2: 主对话完成（需求 + 开发）
    ↓
    ↓ 开发完成后，启动独立 Agent
    ↓
Phase 3-4: 独立 Agent 完成（测试 + 构建）
    ↓
    ↓ 如发现 Bug，返回主对话修复
    ↓
重新启动 Agent 测试验证

Agent 通信协议

传递给测试 Agent 的信息:

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 模板

# [功能名称] 功能规格

## 1. 功能概述
- **功能名称**: 
- **优先级**: P0/P1/P2
- **负责人**: 
- **预计工期**: 

## 2. 业务背景
- 当前痛点
- 解决方案
- 预期收益

## 3. 功能详情

### 3.1 用户故事
作为 [角色]，我希望 [行为]，以便 [目的]

### 3.2 功能列表
- [ ] 功能点 1
- [ ] 功能点 2
- [ ] 功能点 3

### 3.3 UI/UX 设计
- 页面布局
- 交互流程
- 原型链接

## 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
   # 与用户确认需求
   # 识别关键业务场景
   # 明确技术约束

创建文档

mkdir -p docs/features
touch docs/features/[feature-name].md

填充模板
- 完善用户故事
- 设计 API 接口
- 定义数据模型
- 编写测试用例
评审确认
- 与用户确认需求理解正确
- 调整优先级和范围

Phase 2: 模块化生成 (Iterative Coding)

目标

根据 Feature Spec 分模块实现功能。

开发策略

2.1 按模块拆分

Feature
├── Frontend (Flutter)
│   ├── UI 组件
│   ├── 状态管理 (Provider)
│   └── API 调用 (Dio)
├── Backend (Spring Boot)
│   ├── Controller
│   ├── Service
│   └── Repository
└── Database
    └── Migration Scripts

2.2 迭代开发顺序

数据层优先
- 数据库表结构
- Entity 定义
- Repository 实现
后端 API
- Controller 接口
- Service 业务逻辑
- 单元测试
前端实现
- Model 定义
- API Service
- UI 组件
- 状态管理

开发命令

# Flutter 开发
cd flutter_monisuo
flutter pub get
flutter run -d chrome

# 后端开发
cd ../
mvn spring-boot:run

代码规范

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，列出详细信息和修复建议，返回给主对话修复。

Phase 3: 测试与重构 (Validation & Refactoring)

⚠️ 此阶段由独立 Agent 执行，主对话只负责接收结果和修复 Bug。

目标

确保代码质量和功能正确性。

3.1 使用 Clean Code 技能

# 应用 clean-code 技能进行代码优化
# 参考: ~/.agents/skills/clean-code/SKILL.md

优化重点:

代码可读性
函数复杂度
重复代码
命名规范

3.2 自动化测试

API 接口测试

测试脚本位置: tests/api/

测试脚本模板:

#!/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 测试完成 ==="

运行测试:

chmod +x tests/api/test-*.sh
./tests/api/test-feature.sh

Flutter 单元测试

cd flutter_monisuo
flutter test

3.3 Bug 修复循环

Agent 测试 → 发现 Bug → 主对话修复 → 重新启动 Agent → 通过

修复流程:

Agent 报告 Bug
主对话修复代码
重新启动 Agent 验证修复
直到全部通过

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)

# 清理并打包（跳过测试）
mvn clean package -DskipTests

# 完整构建（包含测试）
mvn clean package

# 只编译检查
mvn compile

输出: target/monisuo-*.jar

验证构建:

# 检查 JAR 文件是否生成
ls -la target/*.jar

# 测试 JAR 可执行性
java -jar target/monisuo-*.jar --spring.profiles.active=dev

Flutter Web

cd flutter_monisuo
flutter build web --release --dart-define=ENV=prod

输出: flutter_monisuo/build/web/

Admin 后台

cd monisuo-admin
pnpm install
pnpm build

输出: monisuo-admin/dist/

4.2 Git 提交流程

# 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 提交消息规范

格式:

<type>(<scope>): <subject>

<body>

<footer>

Type 类型:

feat: 新功能
fix: Bug 修复
docs: 文档更新
style: 代码格式
refactor: 重构
test: 测试相关
chore: 构建/工具

示例:

feat(auth): 添加用户登录功能

- 实现手机号+密码登录
- 添加 JWT Token 验证
- 实现自动刷新 Token

Closes #123

项目结构

monisuo/
├── .agents/
│   └── skills/
│       └── monisuo-dev/
│           └── SKILL.md          # 本文件
├── docs/
│   └── features/                 # Feature Specs
│       ├── user-auth.md
│       └── trade-system.md
├── flutter_monisuo/              # Flutter 前端
│   ├── lib/
│   ├── build/web/                # Web 构建产物
│   └── BUILD.md
├── monisuo-admin/                # Vue 管理后台
│   ├── src/
│   └── dist/                     # 构建产物
├── src/                          # Spring Boot 后端
│   └── main/
├── tests/
│   ├── api/                      # API 测试脚本
│   └── e2e/                      # 端到端测试
└── README.md

常用命令速查

Flutter

flutter pub get                  # 安装依赖
flutter run -d chrome            # 开发模式
flutter analyze                  # 代码检查
flutter test                     # 运行测试
flutter build web --release --dart-define=ENV=prod  # 生产构建

Admin

pnpm install                     # 安装依赖
pnpm dev                         # 开发模式
pnpm build                       # 生产构建

Maven

mvn compile                      # 编译
mvn test                         # 运行测试
mvn clean package -DskipTests    # 打包（跳过测试）
mvn clean package                # 完整打包
mvn spring-boot:run              # 运行开发服务

Git

git status                       # 查看状态
git add .                        # 添加所有
git commit -m "message"          # 提交
git push origin main             # 推送

环境配置

环境	ENV	API 地址
生产	prod	http://8.155.172.147:5010

最佳实践

1. 需求阶段

✅ 充分理解业务场景
✅ 与用户确认需求细节
✅ 明确验收标准
✅ 评估技术可行性

2. 开发阶段

✅ 先写测试用例（TDD）
✅ 小步迭代，频繁提交
✅ 保持代码简洁
✅ 及时重构

3. 测试阶段

✅ 自动化测试优先
✅ 覆盖正常和异常流程
✅ 性能测试
✅ 安全测试

4. 部署阶段

✅ 使用生产环境配置
✅ 备份数据库
✅ 灰度发布
✅ 监控告警

故障排查

常见问题

Q: Flutter Web 构建失败

# 清理缓存
flutter clean
flutter pub get
flutter build web --release --dart-define=ENV=prod

Q: API 测试失败

# 检查后端服务
curl http://localhost:5010/actuator/health

# 查看日志
tail -f logs/application.log

Q: Git 推送失败

# 拉取最新代码
git pull origin main --rebase

# 解决冲突后推送
git push origin main

参考资源

版本历史

v1.1.0 (2026-03-26) - 多 Agent 支持
- 添加 Phase 3-4 独立 Agent 执行策略
- 定义 Agent 通信协议
- 添加 Bug 修复循环流程
v1.0.0 (2026-03-23) - 初始版本
- 定义四阶段开发流程
- 添加 Feature Spec 模板
- 集成测试与构建流程

📋 测试 Agent 完整 Prompt 模板

复制以下内容启动测试 Agent：

你是 Monisuo 项目的测试 Agent。你需要独立完成测试验证和构建任务。

## 项目信息
- 后端: Spring Boot (Maven)
- 前端: Flutter Web
- 管理后台: Vue (pnpm)

## 你的任务

### 1. 读取 Feature Spec
首先读取功能规格文档：
- 路径: docs/features/[feature-name].md
- 理解功能需求和验收标准

### 2. 代码审查
- 使用 git diff 查看变更
- 检查代码规范（见下方规范清单）
- 检查错误处理是否完善

### 3. 执行测试

#### API 测试
```bash
# 如果后端服务未启动，先启动
mvn spring-boot:run &

# 运行 API 测试脚本
chmod +x tests/api/test-*.sh
./tests/api/test-[feature].sh

Flutter 测试

cd flutter_monisuo
flutter test

后端单元测试

mvn test

4. 构建

后端构建

mvn clean package -DskipTests
# 输出: target/monisuo-*.jar

Flutter Web 构建

cd flutter_monisuo
flutter build web --release --dart-define=ENV=prod
# 输出: build/web/

5. 输出报告

请输出以下格式的报告：

# 测试与构建报告

## Feature: [功能名称]

## 测试结果
| 测试类型 | 状态 | 备注 |
|---------|------|------|
| API 测试 | ✅/❌ | |
| Flutter 测试 | ✅/❌ | |
| 后端测试 | ✅/❌ | |

## Bug 列表（如有）
1. [Bug 描述]
   - 文件: [文件路径]
   - 原因: [原因分析]
   - 建议: [修复建议]

## 构建结果
| 构建目标 | 状态 | 产物路径 |
|---------|------|---------|
| Spring Boot | ✅/❌ | target/xxx.jar |
| Flutter Web | ✅/❌ | build/web/ |

## 结论
- [ ] 通过，可以提交
- [ ] 有 Bug，需要修复

代码规范清单

Flutter

flutter analyze 无错误
遵循 Effective Dart 规范
使用 AppSpacing, AppRadius, AppColorScheme

Spring Boot

遵循阿里巴巴 Java 开发手册
统一异常处理
RESTful API 设计

注意事项

你是独立 Agent，不要询问用户，自主完成测试
如果测试失败，详细记录失败原因
构建失败时，记录错误日志
最后输出完整报告

15 KiB Raw Blame History Unescape Escape

Monisuo 开发技能

工作流程

⚠️ 多 Agent 执行策略

Agent 切换点

Agent 通信协议

Phase 1: 需求结构化定义 (Prompt Engineering)

目标

输入

输出

Feature Spec 模板

5. 测试用例

6. 验收标准

7. 依赖与风险

Phase 2: 模块化生成 (Iterative Coding)

目标

开发策略

2.1 按模块拆分

2.2 迭代开发顺序

开发命令

代码规范

Flutter

Spring Boot

🔄 Phase 2 完成后：启动测试 Agent

Phase 3: 测试与重构 (Validation & Refactoring)

目标

3.1 使用 Clean Code 技能

3.2 自动化测试

API 接口测试

Flutter 单元测试

3.3 Bug 修复循环

3.4 重新启动测试 Agent

3.4 代码审查清单

Phase 4: 构建与部署 (Build & Deploy)

目标

4.1 构建命令

后端 (Spring Boot)

Flutter Web

Admin 后台

4.2 Git 提交流程

4.3 提交消息规范

项目结构

常用命令速查

Flutter

Admin

Maven

Git

环境配置

最佳实践

1. 需求阶段

2. 开发阶段

3. 测试阶段

4. 部署阶段

故障排查

常见问题

参考资源

版本历史

📋 测试 Agent 完整 Prompt 模板

Flutter 测试

后端单元测试

4. 构建

后端构建

Flutter Web 构建

5. 输出报告

代码规范清单

Flutter

Spring Boot

注意事项

15 KiB

Raw Blame History