sion/monisuo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(skills): 添加 monisuo 开发技能

Browse Source 
- 创建结构化开发流程技能 (monisuo-dev)
- 添加 Feature Spec 模板
- 添加 API 测试脚本模板
- 完整的 4 阶段开发流程：
  1. 需求结构化定义
  2. 模块化生成
  3. 测试与重构
  4. 构建与部署

文件清单：
- .agents/skills/monisuo-dev/SKILL.md (主技能文件)
- .agents/skills/monisuo-dev/README.md (使用指南)
- docs/features/FEATURE_TEMPLATE.md (Feature Spec 模板)
- tests/api/test-template.sh (API 测试模板)
This commit is contained in:
sion
2026-03-23 21:45:45 +08:00
parent ca34261d3f
commit e01f3330a2
4 changed files with 995 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

165
.agents/skills/monisuo-dev/README.md Normal file
View File

@@ -0,0 +1,165 @@
# Monisuo 开发技能使用指南
## 快速开始
### 1. 使用技能
在 OpenClaw 中提及 "monisuo 开发" 即可触发此技能。
### 2. 开发流程
```
需求分析 → 模块化开发 → 测试验证 → 构建部署
```
## 详细说明
### Phase 1: 需求结构化定义
**目标**: 将需求转化为结构化的 Feature Spec
**步骤**:
1. 收集需求信息
2. 创建 `docs/features/[功能名].md`
3. 填写 Feature Spec 模板
4. 评审并确认
**模板位置**: `docs/features/FEATURE_TEMPLATE.md`
### Phase 2: 模块化开发
**目标**: 按模块实现功能
**步骤**:
1. 根据设计文档实现代码
2. 遵循代码规范
3. 使用设计系统（AppSpacing, AppRadius, AppColorScheme）
4. 提交代码
**Flutter 开发**:
```bash
cd flutter_monisuo
flutter pub get
flutter run -d chrome
```
**Admin 开发**:
```bash
cd monisuo-admin
pnpm install
pnpm dev
```
### Phase 3: 测试与重构
**目标**: 确保代码质量和功能正确性
**步骤**:
1. 应用 clean-code 技能优化代码
2. 编写/更新 API 测试脚本
3. 运行测试脚本
4. 修复 Bug 直到全部通过
**运行 API 测试**:
```bash
cd tests/api
chmod +x test-template.sh
./test-template.sh
```
**Flutter 单元测试**:
```bash
cd flutter_monisuo
flutter test
```
### Phase 4: 构建与部署
**目标**: 构建生产版本并提交
**Flutter Web 构建**:
```bash
cd flutter_monisuo
flutter build web --release --dart-define=ENV=prod
```
**Admin 构建**:
```bash
cd monisuo-admin
pnpm build
```
**Git 提交**:
```bash
git add .
git commit -m "feat(模块): 功能描述
- 详细说明 1
- 详细说明 2"
git push origin main
```
## 目录结构
```
monisuo/
├── .agents/skills/monisuo-dev/ # 本技能
├── docs/
│ └── features/ # Feature Spec 文档
│ └── FEATURE_TEMPLATE.md # 模板
├── flutter_monisuo/ # Flutter 前端
├── monisuo-admin/ # Admin 后台
└── tests/
├── api/ # API 测试脚本
│ └── test-template.sh # 测试模板
└── e2e/ # 端到端测试
```
## 常用命令
### Flutter
```bash
flutter pub get # 安装依赖
flutter run -d chrome # 开发模式
flutter analyze # 代码检查
flutter test # 运行测试
flutter build web --release --dart-define=ENV=prod # 生产构建
```
### Admin
```bash
pnpm install # 安装依赖
pnpm dev # 开发模式
pnpm build # 生产构建
```
### 测试
```bash
./tests/api/test-template.sh # 运行 API 测试
```
## 环境配置
| 环境 | ENV | API 地址 |
|------|-----|----------|
| 开发 | dev | http://localhost:5010 |
| 生产 | prod | http://8.155.172.147:5010 |
## 最佳实践
1. **需求阶段**: 充分理解业务，明确验收标准
2. **开发阶段**: 小步迭代，频繁提交，遵循规范
3. **测试阶段**: 自动化测试优先，覆盖完整
4. **部署阶段**: 使用生产配置，灰度发布
## 参考资源
- [Flutter 文档](https://flutter.dev/docs)
- [Spring Boot 文档](https://spring.io/projects/spring-boot)
- [Conventional Commits](https://www.conventionalcommits.org/)
- [Clean Code 技能](~/.agents/skills/clean-code/SKILL.md)
---
**版本**: v1.0.0
**创建日期**: 2026-03-23

507
.agents/skills/monisuo-dev/SKILL.md Normal file
View File

@@ -0,0 +1,507 @@
---
name: monisuo-dev
description: Monisuo 项目结构化开发流程技能。用于需求分析、模块化开发、测试验证、构建部署的完整工作流。
version: 1.0.0
---
# Monisuo 开发技能
用于 Monisuo 项目的结构化开发流程，确保代码质量和开发效率。
## 工作流程
```
需求分析 → 模块化开发 → 测试验证 → 构建部署
```
## Phase 1: 需求结构化定义 (Prompt Engineering)
### 目标
将模糊的需求转化为结构化的 Feature Spec 文档。
### 输入
- 用户的需求描述（自然语言）
- 业务场景说明
- 技术约束条件
### 输出
- `docs/features/feature-name.md` - 结构化的功能规格文档
### Feature Spec 模板
```markdown
# [功能名称] 功能规格
## 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
# 与用户确认需求
# 识别关键业务场景
# 明确技术约束
```
2. **创建文档**
```bash
mkdir -p docs/features
touch docs/features/[feature-name].md
```
3. **填充模板**
- 完善用户故事
- 设计 API 接口
- 定义数据模型
- 编写测试用例
4. **评审确认**
- 与用户确认需求理解正确
- 调整优先级和范围
---
## 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 迭代开发顺序
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
```
### 代码规范
#### Flutter
- 使用 `flutter analyze` 检查代码
- 遵循 Effective Dart 规范
- 使用 Provider 进行状态管理
- 统一使用 AppSpacing, AppRadius, AppColorScheme
#### Spring Boot
- 遵循阿里巴巴 Java 开发手册
- 使用 Lombok 简化代码
- 统一异常处理
- RESTful API 设计
---
## Phase 3: 测试与重构 (Validation & Refactoring)
### 目标
确保代码质量和功能正确性。
### 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 修复循环
```
测试 → 发现 Bug → 修复 → 重新测试 → 通过
```
**修复流程**:
1. 运行测试脚本
2. 记录失败的用例
3. 修复代码
4. 重新运行测试
5. 直到全部通过
### 3.4 代码审查清单
- [ ] 代码符合规范
- [ ] 无硬编码值
- [ ] 错误处理完善
- [ ] 日志记录清晰
- [ ] 测试覆盖完整
- [ ] 性能达标
---
## Phase 4: 构建与部署 (Build & Deploy)
### 目标
构建生产版本并提交代码。
### 4.1 构建命令
#### 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 提交消息规范
**格式**:
```
<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
```bash
flutter pub get # 安装依赖
flutter run -d chrome # 开发模式
flutter analyze # 代码检查
flutter test # 运行测试
flutter build web --release --dart-define=ENV=prod # 生产构建
```
### Admin
```bash
pnpm install # 安装依赖
pnpm dev # 开发模式
pnpm build # 生产构建
```
### Git
```bash
git status # 查看状态
git add . # 添加所有
git commit -m "message" # 提交
git push origin main # 推送
```
---
## 环境配置
| 环境 | ENV | API 地址 |
|------|-----|----------|
| 开发 | dev | http://localhost:5010 |
| 生产 | prod | http://8.155.172.147:5010 |
---
## 最佳实践
### 1. 需求阶段
- ✅ 充分理解业务场景
- ✅ 与用户确认需求细节
- ✅ 明确验收标准
- ✅ 评估技术可行性
### 2. 开发阶段
- ✅ 先写测试用例（TDD）
- ✅ 小步迭代，频繁提交
- ✅ 保持代码简洁
- ✅ 及时重构
### 3. 测试阶段
- ✅ 自动化测试优先
- ✅ 覆盖正常和异常流程
- ✅ 性能测试
- ✅ 安全测试
### 4. 部署阶段
- ✅ 使用生产环境配置
- ✅ 备份数据库
- ✅ 灰度发布
- ✅ 监控告警
---
## 故障排查
### 常见问题
**Q: Flutter Web 构建失败**
```bash
# 清理缓存
flutter clean
flutter pub get
flutter build web --release --dart-define=ENV=prod
```
**Q: API 测试失败**
```bash
# 检查后端服务
curl http://localhost:5010/actuator/health
# 查看日志
tail -f logs/application.log
```
**Q: Git 推送失败**
```bash
# 拉取最新代码
git pull origin main --rebase
# 解决冲突后推送
git push origin main
```
---
## 参考资源
- [Flutter 官方文档](https://flutter.dev/docs)
- [Spring Boot 官方文档](https://spring.io/projects/spring-boot)
- [Conventional Commits](https://www.conventionalcommits.org/)
- [Clean Code 技能](~/.agents/skills/clean-code/SKILL.md)
---
## 版本历史
- **v1.0.0** (2026-03-23) - 初始版本
- 定义四阶段开发流程
- 添加 Feature Spec 模板
- 集成测试与构建流程

187
docs/features/FEATURE_TEMPLATE.md Normal file
View File

@@ -0,0 +1,187 @@
# [功能名称] 功能规格
## 1. 功能概述
- **功能名称**: 示例功能
- **优先级**: P1
- **负责人**: 开发团队
- **预计工期**: 3 天
## 2. 业务背景
### 当前痛点
- 描述当前存在的问题
- 用户痛点分析
### 解决方案
- 如何解决这些问题
- 技术方案概述
### 预期收益
- 提升用户体验
- 提高开发效率
- 其他收益
## 3. 功能详情
### 3.1 用户故事
作为 [用户角色]，我希望 [执行的操作]，以便 [达到的目的]
**示例**:
作为交易用户，我希望快速查看实时行情，以便及时做出交易决策
### 3.2 功能列表
- [ ] 功能点 1: 详细描述
- [ ] 功能点 2: 详细描述
- [ ] 功能点 3: 详细描述
### 3.3 UI/UX 设计
- 页面布局说明
- 交互流程图
- 原型链接 (如有)
## 4. 技术方案
### 4.1 架构设计
#### 前端方案 (Flutter)
- 状态管理: Provider
- UI 组件: shadcn_ui
- 路由管理: Navigator
#### 后端方案 (Spring Boot)
- API 设计: RESTful
- 数据库: MySQL
- 缓存: Redis
### 4.2 API 设计
#### 获取数据
```
GET /api/resource
Headers:
Authorization: Bearer {token}
Response:
{
"success": true,
"data": {
// 返回数据
}
}
```
#### 创建数据
```
POST /api/resource
Headers:
Authorization: Bearer {token}
Content-Type: application/json
Body:
{
"field1": "value1",
"field2": "value2"
}
Response:
{
"success": true,
"data": {
"id": "123"
}
}
```
### 4.3 数据模型
#### Dart Model
```dart
class ExampleModel {
final String id;
final String name;
final DateTime createdAt;
ExampleModel({
required this.id,
required this.name,
required this.createdAt,
});
factory ExampleModel.fromJson(Map<String, dynamic> json) {
return ExampleModel(
id: json['id'],
name: json['name'],
createdAt: DateTime.parse(json['createdAt']),
);
}
Map<String, dynamic> toJson() {
return {
'id': id,
'name': name,
'createdAt': createdAt.toIso8601String(),
};
}
}
```
## 5. 测试用例
### 5.1 正常流程测试
- [ ] 测试用例 1: 描述 + 预期结果
- [ ] 测试用例 2: 描述 + 预期结果
### 5.2 异常流程测试
- [ ] 测试用例 1: 异常场景 + 预期处理
- [ ] 测试用例 2: 异常场景 + 预期处理
### 5.3 边界条件测试
- [ ] 边界 1: 描述 + 预期结果
- [ ] 边界 2: 描述 + 预期结果
## 6. 验收标准
### 功能验收
- [ ] 所有功能点已实现
- [ ] UI 符合设计稿
- [ ] 交互流畅自然
### 质量验收
- [ ] 单元测试通过
- [ ] API 测试通过
- [ ] 代码审查通过
- [ ] 无明显性能问题
### 文档验收
- [ ] API 文档已更新
- [ ] 用户手册已更新
- [ ] CHANGELOG 已更新
## 7. 依赖与风险
### 依赖项
- 依赖 1: 描述 + 影响范围
- 依赖 2: 描述 + 影响范围
### 潜在风险
- 风险 1: 描述 + 缓解措施
- 风险 2: 描述 + 缓解措施
## 8. 时间规划
| 阶段 | 任务 | 预计时间 |
|------|------|----------|
| Phase 1 | 需求分析与设计 | 0.5 天 |
| Phase 2 | 开发实现 | 1.5 天 |
| Phase 3 | 测试与修复 | 0.5 天 |
| Phase 4 | 构建与部署 | 0.5 天 |
## 9. 参考资料
- 相关文档链接
- 技术文档
- 第三方库文档
---
**创建日期**: 2026-03-23
**最后更新**: 2026-03-23

136
tests/api/test-template.sh Normal file
View File

@@ -0,0 +1,136 @@
#!/bin/bash
# Monisuo API 测试脚本模板
# 用于验证 API 接口功能
set -e # 遇到错误立即退出
# ==================== 配置 ====================
BASE_URL="${API_BASE_URL:-http://localhost:5010}"
TOKEN=""
TEST_USER_PHONE="13800138000"
TEST_USER_PASSWORD="123456"
# 颜色输出
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color
# ==================== 工具函数 ====================
log_info() {
echo -e "${GREEN}[INFO]${NC} $1"
}
log_error() {
echo -e "${RED}[ERROR]${NC} $1"
}
log_warning() {
echo -e "${YELLOW}[WARNING]${NC} $1"
}
check_command() {
if ! command -v $1 &> /dev/null; then
log_error "需要安装 $1 命令"
exit 1
fi
}
# ==================== 前置检查 ====================
log_info "=== 前置检查 ==="
# 检查必要的命令
check_command curl
check_command jq
# 检查 API 服务是否运行
log_info "检查 API 服务状态..."
if ! curl -s -f "$BASE_URL/actuator/health" > /dev/null 2>&1; then
log_error "API 服务未运行或无法访问: $BASE_URL"
log_warning "请先启动后端服务"
exit 1
fi
log_info "✓ API 服务正常"
# ==================== 测试用例 ====================
log_info "=== 开始 API 测试 ==="
# 测试计数器
TOTAL_TESTS=0
PASSED_TESTS=0
FAILED_TESTS=0
run_test() {
local test_name="$1"
local test_command="$2"
TOTAL_TESTS=$((TOTAL_TESTS + 1))
log_info "测试 $TOTAL_TESTS: $test_name"
if eval "$test_command"; then
PASSED_TESTS=$((PASSED_TESTS + 1))
log_info "✓ 通过"
return 0
else
FAILED_TESTS=$((FAILED_TESTS + 1))
log_error "✗ 失败"
return 1
fi
}
# ==================== 测试 1: 健康检查 ====================
run_test "健康检查" "curl -s -f '$BASE_URL/actuator/health' | jq -e '.status == \"UP\"' > /dev/null"
# ==================== 测试 2: 用户登录 ====================
log_info "测试用户登录..."
RESPONSE=$(curl -s -X POST "$BASE_URL/api/auth/login" \
-H "Content-Type: application/json" \
-d "{\"phone\":\"$TEST_USER_PHONE\",\"password\":\"$TEST_USER_PASSWORD\"}")
if echo "$RESPONSE" | jq -e '.success == true' > /dev/null; then
TOKEN=$(echo "$RESPONSE" | jq -r '.data.token')
log_info "✓ 登录成功，Token: ${TOKEN:0:20}..."
PASSED_TESTS=$((PASSED_TESTS + 1))
else
log_error "✗ 登录失败"
log_error "响应: $RESPONSE"
FAILED_TESTS=$((FAILED_TESTS + 1))
fi
TOTAL_TESTS=$((TOTAL_TESTS + 1))
# ==================== 测试 3: 获取用户信息 ====================
if [ -n "$TOKEN" ]; then
log_info "测试获取用户信息..."
run_test "获取用户信息" "curl -s -f -X GET '$BASE_URL/api/user/info' -H 'Authorization: Bearer $TOKEN' | jq -e '.success == true' > /dev/null"
fi
# ==================== 测试 4: [根据具体功能添加更多测试] ====================
# TODO: 添加更多测试用例
# 示例：
# run_test "创建订单" "curl -s -f -X POST '$BASE_URL/api/orders' ..."
# run_test "查询订单列表" "curl -s -f -X GET '$BASE_URL/api/orders' ..."
# ==================== 测试结果汇总 ====================
echo ""
log_info "=== 测试结果汇总 ==="
log_info "总测试数: $TOTAL_TESTS"
log_info "通过: $PASSED_TESTS"
log_info "失败: $FAILED_TESTS"
if [ $FAILED_TESTS -eq 0 ]; then
log_info "✓ 所有测试通过！"
exit 0
else
log_error "✗ 有 $FAILED_TESTS 个测试失败"
exit 1
fi