pipexerp/ai-proj-helper
6
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity

refactor: 通用技能按类别拆分为独立目录

Browse Source 
skills/ → skills-dev(9), skills-req(10), skills-ops(4),
skills-integration(8), skills-biz(4), skills-workflow(7)

generate-marketplace.py 改为自动扫描所有 skills-* 目录。

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
John Qiu
2026-03-14 11:31:58 +10:30
parent ea266e9cce
commit 712063071c
170 changed files with 341 additions and 346 deletions
Download Patch File Download Diff File Expand all files Collapse all files

390
skills-dev/dev-arch-plugin/skills/SKILL.md Normal file
View File

@@ -0,0 +1,390 @@
---
name: dev-arch
description: 软件架构设计技能。用于系统设计、技术选型、架构评审、设计文档编写。当用户提到架构设计、系统设计、技术方案、API 设计相关任务时自动激活。
---
# 软件架构设计 Skill (dev-arch)
## 概述
本技能用于软件架构设计工作，包括：
- 系统架构设计与评审
- 技术选型与方案对比
- API 设计与文档
- 数据库设计
- 设计模式应用
---
## 架构设计流程
### 1. 需求分析
```
输入：
- 业务需求文档
- 非功能性需求（性能、安全、可用性）
- 技术约束条件
输出：
- 需求清单
- 约束条件列表
```
### 2. 概要设计
```
内容：
- 系统边界定义
- 模块划分
- 技术栈选择
- 部署架构
输出：
- 架构图
- 技术方案文档
```
### 3. 详细设计
```
内容：
- API 接口设计
- 数据模型设计
- 核心流程设计
- 异常处理设计
输出：
- API 文档
- ER 图
- 时序图
```
---
## 架构设计模板
### 系统设计文档模板
```markdown
# [系统名称] 技术设计文档
## 1. 概述
### 1.1 背景
[项目背景和目标]
### 1.2 范围
[系统边界和功能范围]
### 1.3 术语定义
| 术语 | 定义 |
|------|------|
| ... | ... |
## 2. 系统架构
### 2.1 整体架构图
[架构图]
### 2.2 模块说明
| 模块 | 职责 | 技术栈 |
|------|------|--------|
| ... | ... | ... |
### 2.3 部署架构
[部署图]
## 3. 技术选型
### 3.1 技术栈
| 类别 | 选择 | 理由 |
|------|------|------|
| 后端框架 | ... | ... |
| 数据库 | ... | ... |
| 缓存 | ... | ... |
| 消息队列 | ... | ... |
### 3.2 技术对比
[备选方案对比分析]
## 4. 数据设计
### 4.1 ER 图
[ER 图]
### 4.2 核心表设计
[表结构说明]
### 4.3 索引策略
[索引设计]
## 5. API 设计
### 5.1 API 规范
[RESTful 规范说明]
### 5.2 核心接口
[接口定义]
## 6. 非功能性设计
### 6.1 性能设计
- 响应时间目标
- 吞吐量目标
- 优化策略
### 6.2 安全设计
- 认证授权
- 数据安全
- 日志审计
### 6.3 可用性设计
- 容错机制
- 监控告警
- 备份恢复
## 7. 风险评估
| 风险 | 影响 | 概率 | 应对措施 |
|------|------|------|----------|
| ... | ... | ... | ... |
## 8. 附录
- 参考资料
- 变更历史
```
---
## 常用架构模式
### 分层架构
```
┌─────────────────────────────────┐
│ 表现层 (Presentation) │
├─────────────────────────────────┤
│ 业务层 (Business) │
├─────────────────────────────────┤
│ 数据层 (Data Access) │
├─────────────────────────────────┤
│ 基础设施 (Infrastructure) │
└─────────────────────────────────┘
```
### 微服务架构
```
┌─────┐ ┌─────┐ ┌─────┐
│ API │ │ API │ │ API │
│ GW │──│ SVC │──│ SVC │
└──┬──┘ └──┬──┘ └──┬──┘
│ │ │
└────────┴────────┘
│
┌────┴────┐
│ Message │
│ Queue │
└─────────┘
```
### 六边形架构 (端口-适配器)
```
┌─────────────────┐
┌──────│ Adapters │──────┐
│ │ (Inbound) │ │
│ └────────┬────────┘ │
│ │ │
┌───┴───┐ ┌──────┴──────┐ ┌────┴────┐
│ REST │ │ Core │ │ Repo │
│ API │────│ Business │───│ Impl │
└───────┘ │ Domain │ └─────────┘
└─────────────┘
```
---
## API 设计规范
### RESTful 规范
| 方法 | 用途 | 示例 |
|------|------|------|
| GET | 查询资源 | `GET /users/{id}` |
| POST | 创建资源 | `POST /users` |
| PUT | 全量更新 | `PUT /users/{id}` |
| PATCH | 部分更新 | `PATCH /users/{id}` |
| DELETE | 删除资源 | `DELETE /users/{id}` |
### 响应格式
```json
{
"code": 0,
"message": "success",
"data": {},
"meta": {
"page": 1,
"limit": 20,
"total": 100
}
}
```
### 错误码设计
| 范围 | 类型 | 示例 |
|------|------|------|
| 10000-19999 | 系统错误 | 10001 内部错误 |
| 20000-29999 | 参数错误 | 20001 参数缺失 |
| 30000-39999 | 业务错误 | 30001 用户不存在 |
| 40000-49999 | 权限错误 | 40001 未授权 |
---
## 数据库设计
### 命名规范
| 类型 | 规范 | 示例 |
|------|------|------|
| 表名 | 小写下划线，复数 | `user_accounts` |
| 字段 | 小写下划线 | `created_at` |
| 主键 | id | `id` |
| 外键 | 表名_id | `user_id` |
| 索引 | idx_表名_字段 | `idx_users_email` |
### 通用字段
```sql
-- 每个表必须包含的字段
id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
deleted_at DATETIME DEFAULT NULL -- 软删除
```
### 索引策略
- 主键索引：每表必须
- 唯一索引：业务唯一字段
- 普通索引：高频查询字段
- 联合索引：遵循最左前缀原则
---
## 技术选型参考
### 后端框架
| 语言 | 框架 | 适用场景 |
|------|------|----------|
| Go | Gin, Echo | 高并发 API |
| Java | Spring Boot | 企业应用 |
| Python | FastAPI, Django | 快速开发 |
| Node.js | NestJS, Express | 全栈/实时 |
### 数据库选型
| 类型 | 选项 | 适用场景 |
|------|------|----------|
| 关系型 | MySQL, PostgreSQL | 事务型业务 |
| 文档型 | MongoDB | 灵活结构 |
| 键值型 | Redis | 缓存/会话 |
| 时序 | InfluxDB | 监控/IoT |
| 搜索 | Elasticsearch | 全文检索 |
### 消息队列
| 选项 | 特点 | 适用场景 |
|------|------|----------|
| Redis | 简单快速 | 轻量级队列 |
| RabbitMQ | 可靠传递 | 企业集成 |
| Kafka | 高吞吐 | 日志/流处理 |
| NATS | 轻量级 | 微服务通信 |
---
## 架构评审检查清单
### 功能性检查
- [ ] 需求覆盖完整
- [ ] 边界条件处理
- [ ] 异常情况处理
- [ ] 数据一致性保证
### 非功能性检查
- [ ] 性能目标明确
- [ ] 安全措施到位
- [ ] 可扩展性设计
- [ ] 可维护性考虑
### 运维检查
- [ ] 监控指标定义
- [ ] 日志规范
- [ ] 部署方案
- [ ] 回滚机制
---
## 与 ai-proj 集成
### 创建架构设计任务
```bash
# 创建架构设计任务
ai-proj task create --title "[系统名称] 架构设计"
# 创建子任务
ai-proj task create --title "需求分析" --parent-id <parentId>
ai-proj task create --title "概要设计" --parent-id <parentId>
ai-proj task create --title "详细设计" --parent-id <parentId>
ai-proj task create --title "架构评审" --parent-id <parentId>
```
### 关联设计文档
```bash
# 附加设计文档到任务
ai-proj task append-doc --id <taskId> --content "设计文档内容 (Markdown)"
```
---
## 最佳实践
1. **KISS 原则** - 保持简单，避免过度设计
2. **YAGNI 原则** - 不要预测未来需求
3. **DRY 原则** - 避免重复代码
4. **SOLID 原则** - 面向对象设计原则
5. **关注点分离** - 模块职责单一
6. **高内聚低耦合** - 模块独立性
---
## 文档工具
### 架构图工具
- **draw.io** - 在线免费绘图
- **PlantUML** - 代码生成图
- **Mermaid** - Markdown 内嵌图
- **Excalidraw** - 手绘风格
### Mermaid 示例
```mermaid
sequenceDiagram
Client->>API Gateway: Request
API Gateway->>Auth Service: Validate Token
Auth Service-->>API Gateway: Valid
API Gateway->>Business Service: Forward Request
Business Service->>Database: Query
Database-->>Business Service: Result
Business Service-->>API Gateway: Response
API Gateway-->>Client: Response
```
---
## 参考资源
- [系统设计入门](https://github.com/donnemartin/system-design-primer)
- [微服务架构](https://microservices.io/)
- [RESTful API 设计指南](https://restfulapi.net/)
- [数据库设计范式](https://www.guru99.com/database-normalization.html)