project-guide

Original source / Raw SKILL.md

---
name: "project-guide"
description: "引导用户填写项目开发指导模板。激活条件：用户想要开发新项目、表达项目需求、创建应用。"
---

# 项目开发指导助手

## 概述

这个 Skill 用于引导和帮助用户完成项目开发指导模板的填写。当用户想要开发新项目或对现有项目进行重大修改时，使用此 Skill 来收集必要的信息。

## 触发条件

在以下情况下应该激活此 Skill：
1. 用户表达想要开发一个新项目
2. 用户提到"帮我整理一下项目需求"
3. 用户想要使用 AI 开发应用但不知道如何描述需求
4. 用户说"我要做一个 XX 系统"
5. 用户询问如何开始一个项目开发

## 工作流程

### 阶段一：项目概览采集

**目标：** 收集项目的基本信息

需要询问用户以下问题：

1. **项目名称**
   - "你希望给项目起什么名字？"
   - 或者 "这个项目叫什么？"

2. **项目类型**
   - "这是一个什么类型的项目？Web应用、移动端、API服务还是桌面工具？"

3. **项目简介**
   - "能用一两句话描述一下这个项目吗？它是做什么的？"
   - "这个项目要解决什么问题？"

4. **核心目标**
   - "你做这个项目最主要想要达成什么目标？"
   - "除了主要目标，还有其他期望吗？"

### 阶段二：详细需求采集

**目标：** 收集详细的功能和业务需求

需要引导用户填写 `requirements.md`，询问：

1. **用户群体**
   - "谁会使用这个产品？"
   - "他们有什么特点和需求？"

2. **核心功能**
   - "这个产品最核心的功能是什么？"
   - "用户最常用的功能有哪些？"
   - "有没有必须有的功能（P0），重要但不是必须的功能（P1），以及可选功能（P2）？"

3. **业务流程**
   - "能描述一下典型的使用流程吗？"
   - "比如用户进来后第一步做什么，然后呢？"

4. **数据需求**
   - "需要存储什么类型的数据？"
   - "有没有用户账号体系？需要哪些信息？"

5. **非功能需求**
   - "对性能有要求吗？比如响应时间、并发数？"
   - "有安全或合规方面的要求吗？"
   - "需要支持哪些平台或浏览器？"

### 阶段三：技术约束采集

**目标：** 了解技术方面的限制和要求

1. **技术偏好**
   - "有没有偏好的技术栈？比如必须用某种语言或框架？"
   - "团队对哪些技术比较熟悉？"

2. **已有资源**
   - "有没有已经可以复用的组件或服务？"
   - "需要集成哪些第三方服务？"

3. **约束条件**
   - "预算或时间有限制吗？"
   - "有没有必须兼容的现有系统？"

### 阶段四：生成文档

**目标：** 将收集到的信息整理成完整的模板文档

1. 根据收集的信息，生成/更新 `main.md`
2. 根据收集的信息，生成/更新 `requirements.md`
3. 如果用户已确定技术选型，生成 `architecture.md`
4. 如果涉及接口，生成 `api.md`

## 输出格式

完成信息收集后，应该：

1. **总结确认**
   - 向用户确认理解是否正确
   - 询问是否有遗漏或需要补充的地方

2. **提供下一步建议**
   - "根据你提供的信息，我已经整理出项目模板。"
   - "接下来你可以："
     - "1. 查看并完善 templates 目录下的模板文件"
     - "2. 确认无误后告诉 AI '请从 main.md 开始阅读'"
     - "3. AI 将根据这些信息开始项目开发"

## 模板文件位置

项目模板位于 `templates/` 目录下：
- `templates/main.md` - 项目概览和索引
- `templates/requirements.md` - 详细需求文档
- `templates/architecture.md` - 技术架构设计
- `templates/api.md` - API 接口设计
- `templates/update.md` - 需求变更记录

## 注意事项

1. **循序渐进**：不要一次性问所有问题，而是根据用户的回答逐步深入
2. **解释原因**：适时解释为什么需要这些信息，帮助用户理解
3. **提供示例**：如果用户不知道如何描述，可以提供示例
4. **记录不确定**：对于用户不确定的地方，先记录下来，后续再确认
5. **保持简洁**：问题要简洁明了，避免过度技术化的术语


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### templates/main.md

```markdown
# 项目开发指导模板

## 项目概览

### 项目名称
[填写项目名称]

### 项目类型
- [ ] Web 应用
- [ ] 移动应用
- [ ] API 服务
- [ ] 命令行工具
- [ ] 桌面应用
- [ ] 其他: _______

### 项目简介
[用 2-3 句话描述这个项目要解决什么问题，为谁解决]

### 核心目标
1. [最主要的业务目标]
2. [次要目标]
3. [辅助目标]

---

## 文件结构说明

本模板包含以下文件，请按顺序阅读和填写：

1. **[main.md](main.md)** - 本文件，项目概览和索引
2. **[requirements.md](requirements.md)** - 详细需求文档
3. **[architecture.md](architecture.md)** - 技术架构设计
4. **[api.md](api.md)** - API 接口设计
5. **[update.md](update.md)** - 需求变更记录

---

## 快速开始

### 首次使用
1. 完整填写 `main.md` 中的项目概览
2. 按照 `requirements.md` 的指引填写详细需求
3. 参考 `architecture.md` 确定技术选型
4. 在 `api.md` 中定义接口规范

### 已有项目更新
1. 在 `update.md` 中记录新的需求或修改
2. AI 会自动识别变更并更新相关文档

---

## 项目约束

### 预算限制
[如有预算限制请填写]

### 时间要求
[如有交付时间要求请填写]

### 技术约束
- [ ] 必须使用已有系统的某些组件
- [ ] 必须兼容某个现有系统
- [ ] 有特定的性能要求
- [ ] 有安全合规要求
- 其他: _______

---

## 已有资源

### 可复用的服务/组件
[列出项目中可以复用的已有服务、API、组件]

### 第三方服务
[列出项目中需要集成的第三方服务]

---

## 注意事项

1. **请务必完整填写所有模板字段**，信息越完整，开发结果越符合预期
2. 如有不确定的地方，可以先填写大致想法，后续再细化
3. 所有修改请记录在 `update.md` 中，便于追踪变更历史

---

*本模板由 AI 项目开发指导助手生成*

```

### templates/requirements.md

```markdown
# 详细需求文档

## 1. 业务需求

### 1.1 背景故事
[描述项目产生的背景，为什么需要这个项目]

### 1.2 用户画像
**主要用户群体：**
- [用户群体1]: [描述其特点、需求]
- [用户群体2]: [描述其特点、需求]

**用户痛点：**
1. [痛点1]
2. [痛点2]
3. [痛点3]

### 1.3 核心业务流程
[用文字或流程图描述核心业务是如何运作的]

```
[流程步骤1] → [流程步骤2] → [流程步骤3] → [流程步骤4]
```

### 1.4 关键业务指标 (KPI)
| 指标 | 目标值 | 优先级 |
|------|--------|--------|
| [指标1] | [目标值] | P0/P1/P2 |
| [指标2] | [目标值] | P0/P1/P2 |

---

## 2. 功能需求

### 2.1 功能列表

#### 功能模块 A
| 功能名称 | 功能描述 | 优先级 | 备注 |
|----------|----------|--------|------|
| [功能A1] | [描述] | P0 | 必做 |
| [功能A2] | [描述] | P1 | 重要 |
| [功能A3] | [描述] | P2 | 可选 |

#### 功能模块 B
| 功能名称 | 功能描述 | 优先级 | 备注 |
|----------|----------|--------|------|
| [功能B1] | [描述] | P0 | 必做 |
| [功能B2] | [描述] | P1 | 重要 |

### 2.2 详细功能说明

#### 功能 A1: [功能名称]
**功能描述：**
[详细描述这个功能做什么]

**用户交互流程：**
1. 用户进入 [页面/场景]
2. 用户执行 [操作]
3. 系统 [响应/反馈]
4. 完成 [结果]

**边界情况：**
- [情况1]：如何处理
- [情况2]：如何处理

**数据需求：**
- 输入：[字段列表]
- 输出：[字段列表]
- 存储：[表/存储方式]

---

## 3. 非功能需求

### 3.1 性能要求
| 指标 | 要求 | 说明 |
|------|------|------|
| 响应时间 | < [X]ms | 正常情况下 |
| 并发数 | 支持 [X] 用户 | 峰值时 |
| 可用性 | [99.X]% | 月度可用性 |

### 3.2 安全要求
- [ ] 用户认证
- [ ] 数据加密
- [ ] 权限控制
- [ ] 日志审计
- [ ] 其他: _______

### 3.3 兼容性要求
- 浏览器支持: [列表]
- 移动端支持: [列表]
- 第三方集成: [列表]

### 3.4 监控与运维
- [ ] 需要健康检查接口
- [ ] 需要性能监控
- [ ] 需要错误告警
- [ ] 需要日志收集
- [ ] 其他: _______

---

## 4. 数据模型

### 4.1 核心实体

#### 实体 A
| 字段名 | 类型 | 说明 | 必填 |
|--------|------|------|------|
| id | UUID | 主键 | 是 |
| name | string | 名称 | 是 |
| [字段3] | [类型] | [说明] | 是/否 |

#### 实体 B
| 字段名 | 类型 | 说明 | 必填 |
|--------|------|------|------|
| id | UUID | 主键 | 是 |
| [字段2] | [类型] | [说明] | 是/否 |

### 4.2 实体关系
[用文字描述实体之间的关系，或用 ER 图表示]

---

## 5. 验收标准

### 5.1 功能验收
| 功能 | 验收条件 | 测试方式 |
|------|----------|----------|
| [功能A1] | [条件] | [测试方法] |
| [功能A2] | [条件] | [测试方法] |

### 5.2 视觉/交互验收
[描述期望的界面风格、交互方式]

### 5.3 性能验收
- [ ] 页面加载时间 < [X]秒
- [ ] API 响应时间 < [X]ms
- [ ] 支持 [X] 并发用户

---

## 6. 风险与依赖

### 6.1 潜在风险
| 风险 | 影响 | 缓解措施 |
|------|------|----------|
| [风险1] | [影响描述] | [措施] |

### 6.2 外部依赖
| 依赖项 | 说明 | 状态 |
|--------|------|------|
| [依赖1] | [说明] | 已确认/待确认 |
| [依赖2] | [说明] | 已确认/待确认 |

---

*请完整填写以上内容，确保需求清晰完整*

```

### templates/architecture.md

```markdown
# 技术架构设计

## 1. 技术栈选择

### 1.1 前端技术
| 类别 | 技术选型 | 版本 | 选择理由 |
|------|----------|------|----------|
| 框架 | [React/Vue/Angular/其他] | [版本] | [理由] |
| 状态管理 | [Redux/Zustand/其他] | [版本] | [理由] |
| UI 组件库 | [AntD/Element/其他] | [版本] | [理由] |
| 路由 | [React Router/其他] | [版本] | [理由] |
| HTTP 客户端 | [Axios/其他] | [版本] | [理由] |
| 构建工具 | [Vite/Webpack/其他] | [版本] | [理由] |

### 1.2 后端技术
| 类别 | 技术选型 | 版本 | 选择理由 |
|------|----------|------|----------|
| 语言 | [Node.js/Python/Go/Java] | [版本] | [理由] |
| 框架 | [Express/FastAPI/Gin/Spring] | [版本] | [理由] |
| ORM | [Prisma/Sequelize/GORM/MyBatis] | [版本] | [理由] |
| 数据库 | [PostgreSQL/MySQL/MongoDB] | [版本] | [理由] |
| 缓存 | [Redis/Memcached] | [版本] | [理由] |
| 消息队列 | [RabbitMQ/Kafka/其他] | [版本] | [理由] |

### 1.3 基础设施
| 类别 | 技术选型 | 说明 |
|------|----------|------|
| 主机 | [云服务器/容器/Serverless] | |
| 存储 | [OSS/S3/本地存储] | |
| CDN | [阿里云CDN/Cloudflare/其他] | |
| CI/CD | [GitHub Actions/GitLab CI/Jenkins] | |

---

## 2. 系统架构

### 2.1 架构图
[在此绘制系统架构图或描述架构]

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   前端应用   │────▶│   API 网关   │────▶│   业务服务   │
└─────────────┘     └─────────────┘     └─────────────┘
                                                │
                   ┌─────────────┐              │
                   │   数据库     │◀─────────────┤
                   └─────────────┘
```

### 2.2 模块划分

| 模块名称 | 职责 | 部署方式 | 备注 |
|----------|------|----------|------|
| [模块1] | [职责描述] | [部署方式] | |
| [模块2] | [职责描述] | [部署方式] | |
| [模块3] | [职责描述] | [部署方式] | |

---

## 3. 数据库设计

### 3.1 数据库清单
| 数据库名 | 类型 | 用途 | 字符集 |
|----------|------|------|--------|
| [db_main] | PostgreSQL | 核心业务数据 | utf8mb4 |
| [db_cache] | Redis | 缓存 | - |
| [db_log] | Elasticsearch | 日志存储 | - |

### 3.2 核心表设计

#### 表: [table_name]
```sql
CREATE TABLE [table_name] (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    [字段1] [类型] NOT NULL,
    [字段2] [类型],
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_[table_name]_[字段] ON [table_name]([字段]);
```

---

## 4. API 设计规范

### 4.1 RESTful 风格
| 规则 | 说明 |
|------|------|
| URL 命名 | /api/v1/{资源名} |
| HTTP 方法 | GET(查询) / POST(创建) / PUT(更新) / DELETE(删除) |
| 响应格式 | { code: number, data: any, message: string } |

### 4.2 认证方案
- [ ] JWT Token
- [ ] OAuth 2.0
- [ ] API Key
- [ ] Session
- 其他: _______

### 4.3 限流策略
[描述接口限流方案]

---

## 5. 安全设计

### 5.1 认证与授权
| 项目 | 方案 |
|------|------|
| 用户认证 | [方案描述] |
| 权限控制 | [方案描述] |
| 密码存储 | [方案描述] |

### 5.2 数据安全
- [ ] HTTPS 传输加密
- [ ] 敏感数据加密存储
- [ ] 数据备份策略
- [ ] 其他: _______

---

## 6. 部署架构

### 6.1 环境划分
| 环境 | 用途 | 配置 |
|------|------|------|
| dev | 开发调试 | [配置] |
| test | 测试验证 | [配置] |
| staging | 预发布 | [配置] |
| production | 生产环境 | [配置] |

### 6.2 扩缩容策略
[描述如何应对流量高峰]

---

## 7. 监控与告警

### 7.1 监控指标
| 指标类型 | 监控项 | 告警阈值 |
|----------|--------|----------|
| 基础设施 | CPU/内存/磁盘 | [阈值] |
| 应用 | QPS/响应时间/错误率 | [阈值] |
| 业务 | [业务指标] | [阈值] |

### 7.2 日志规范
- 日志格式: JSON
- 日志级别: DEBUG / INFO / WARN / ERROR
- 日志保留: [天数]

---

*请根据项目实际情况填写以上技术架构内容*

```

### templates/api.md

```markdown
# API 接口设计

## 1. 接口概览

### 1.1 基础信息
| 项目 | 值 |
|------|-----|
| Base URL | /api/v1 |
| 认证方式 | Bearer Token |
| 协议 | HTTPS |
| 数据格式 | JSON |

### 1.2 通用响应格式

#### 成功响应
```json
{
  "code": 0,
  "data": { ... },
  "message": "success"
}
```

#### 错误响应
```json
{
  "code": 1001,
  "data": null,
  "message": "错误描述"
}
```

### 1.3 错误码表
| 错误码 | 说明 |
|--------|------|
| 0 | 成功 |
| 1001 | 参数错误 |
| 1002 | 认证失败 |
| 1003 | 权限不足 |
| 1004 | 资源不存在 |
| 1005 | 服务器内部错误 |

---

## 2. 用户模块

### 2.1 用户登录
**POST** `/auth/login`

**请求参数：**
```json
{
  "username": "string",
  "password": "string"
}
```

**响应：**
```json
{
  "code": 0,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "uuid",
      "username": "string",
      "email": "string"
    }
  },
  "message": "success"
}
```

---

### 2.2 用户注册
**POST** `/auth/register`

**请求参数：**
```json
{
  "username": "string",
  "email": "string",
  "password": "string"
}
```

**响应：**
```json
{
  "code": 0,
  "data": {
    "id": "uuid",
    "username": "string",
    "email": "string"
  },
  "message": "success"
}
```

---

### 2.3 获取当前用户信息
**GET** `/users/me`

**请求头：**
```
Authorization: Bearer <token>
```

**响应：**
```json
{
  "code": 0,
  "data": {
    "id": "uuid",
    "username": "string",
    "email": "string",
    "createdAt": "2024-01-01T00:00:00Z"
  },
  "message": "success"
}
```

---

## 3. 业务模块

### 3.1 [业务接口名称]
**[METHOD]** `/resource/{id}`

**请求参数：**
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | string | 是 | 资源ID |

**请求体：**
```json
{
  "field1": "string",
  "field2": 0
}
```

**响应：**
```json
{
  "code": 0,
  "data": {
    "id": "uuid",
    "field1": "string",
    "field2": 0,
    "createdAt": "2024-01-01T00:00:00Z"
  },
  "message": "success"
}
```

---

## 4. 接口清单

### 4.1 接口列表
| 模块 | 方法 | 路径 | 说明 | 优先级 |
|------|------|------|------|--------|
| 认证 | POST | /auth/login | 用户登录 | P0 |
| 认证 | POST | /auth/register | 用户注册 | P0 |
| 认证 | POST | /auth/logout | 用户登出 | P1 |
| 用户 | GET | /users/me | 获取当前用户 | P0 |
| 用户 | PUT | /users/me | 更新用户信息 | P1 |
| 业务 | GET | /resources | 资源列表 | P0 |
| 业务 | POST | /resources | 创建资源 | P0 |
| 业务 | GET | /resources/{id} | 获取资源详情 | P0 |
| 业务 | PUT | /resources/{id} | 更新资源 | P0 |
| 业务 | DELETE | /resources/{id} | 删除资源 | P1 |

---

## 5. WebSocket 接口

### 5.1 连接信息
| 项目 | 值 |
|------|-----|
| URL | wss://domain/ws |
| 协议 | ws |

### 5.2 消息格式
```json
{
  "type": "event_type",
  "data": { ... }
}
```

---

*请根据实际业务需求补充完整的 API 设计*

```

### templates/update.md

```markdown
# 需求变更记录

## 更新日志

### 2024-01-01

#### 变更类型: [新功能/优化/修复]

**变更描述：**
[描述变更内容]

**变更原因：**
[描述变更原因]

**影响范围：**
- [影响的模块/功能]
- [其他影响]

**变更前：**
[描述变更前的状态]

**变更后：**
[描述变更后的状态]

**状态：**
- [ ] 待开发
- [ ] 开发中
- [ ] 已完成
- [ ] 已验证

---

### 历史变更

| 日期 | 变更类型 | 变更内容 | 状态 |
|------|----------|----------|------|
| | | | |
| | | | |
| | | | |

---

*请在每次需求变更时更新此文件*

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### _meta.json

```json
{
  "owner": "2907555270",
  "slug": "project-guide",
  "displayName": "project-guide",
  "latest": {
    "version": "1.0.1",
    "publishedAt": 1773425820175,
    "commit": "https://github.com/openclaw/skills/commit/bcd91e90e27e94365265cdc4025f8ee0540f6661"
  },
  "history": []
}

```