锦麟 王
220 lines
4.4 KiB
Markdown
220 lines
4.4 KiB
Markdown
---
|
||
name: dev-deliver
|
||
description: 开发流程 - 交付阶段，生成接口文档、使用文档、部署文档等交付物
|
||
---
|
||
|
||
# 交付
|
||
|
||
> 开发流程第六阶段：基于实际代码和文档生成交付文档。
|
||
|
||
## 调用方式
|
||
|
||
`/dev-deliver`，也可说"生成交付文档"或"准备交付"。
|
||
|
||
## 产出目录
|
||
|
||
`docs/deliverables/`
|
||
|
||
## 执行流程
|
||
|
||
### Checklist
|
||
|
||
- [ ] 前置检查：读取所有前序产出物
|
||
- [ ] 生成接口文档
|
||
- [ ] 生成使用文档
|
||
- [ ] 生成部署文档
|
||
- [ ] 生成变更摘要
|
||
- [ ] 用户审阅并保存
|
||
|
||
### 1. 前置检查
|
||
|
||
读取所有前序阶段的产出物：
|
||
- `docs/requirements/` — 需求文档
|
||
- `docs/design/` — 设计文档
|
||
- `docs/plans/` — 步骤计划
|
||
- `docs/dev-logs/` — 开发日志
|
||
- `docs/test-reports/` — 测试报告
|
||
|
||
如果某些阶段缺失，提示用户但不阻止执行。基于已有信息生成交付文档。
|
||
|
||
### 2. 生成接口文档
|
||
|
||
**基于实际代码扫描：**
|
||
- 读取项目源代码文件
|
||
- 识别 API 端点、路由定义
|
||
- 提取函数签名和参数
|
||
- 识别请求/响应格式
|
||
- 提取错误码定义
|
||
|
||
**生成格式：**
|
||
|
||
```markdown
|
||
## 接口文档
|
||
|
||
### API 接口 N：<名称>
|
||
|
||
**方法**：POST
|
||
**路径**：/api/xxx
|
||
**描述**：xxx
|
||
|
||
**请求参数**：
|
||
| 参数 | 类型 | 必填 | 描述 |
|
||
|------|------|------|------|
|
||
|
||
**响应格式**：
|
||
[实际响应结构]
|
||
|
||
**错误码**：
|
||
| 错误码 | 描述 |
|
||
|--------|------|
|
||
```
|
||
|
||
如果项目不是 API/库类型，调整为文档对应的接口形式（函数接口、模块接口等）。
|
||
|
||
### 3. 生成使用文档
|
||
|
||
**基于项目配置文件：**
|
||
- 读取 package.json / pyproject.toml / Makefile 等
|
||
- 识别依赖和版本要求
|
||
- 提取安装/构建命令
|
||
- 读取配置文件示例
|
||
|
||
**生成格式：**
|
||
|
||
```markdown
|
||
## 使用文档
|
||
|
||
### 环境要求
|
||
- Node.js >= 18
|
||
- npm >= 9
|
||
|
||
### 安装
|
||
[实际安装命令]
|
||
|
||
### 配置
|
||
[实际配置说明]
|
||
|
||
### 基本用法
|
||
[使用示例]
|
||
```
|
||
|
||
### 4. 生成部署文档
|
||
|
||
**基于项目结构和配置：**
|
||
- 识别部署相关文件（Dockerfile、docker-compose.yml 等）
|
||
- 提取环境变量定义
|
||
- 识别外部依赖服务
|
||
- 提取构建和部署命令
|
||
|
||
**生成格式：**
|
||
|
||
```markdown
|
||
## 部署文档
|
||
|
||
### 环境变量
|
||
| 变量名 | 必填 | 描述 | 默认值 |
|
||
|--------|------|------|--------|
|
||
|
||
### 部署步骤
|
||
1. xxx
|
||
2. yyy
|
||
|
||
### 依赖服务
|
||
- 数据库：xxx
|
||
- 缓存：xxx
|
||
```
|
||
|
||
### 5. 生成变更摘要
|
||
|
||
**基于需求文档和开发日志：**
|
||
|
||
```markdown
|
||
## 变更摘要
|
||
|
||
### 新增
|
||
- 功能 A（涉及文件：src/xxx.ts）
|
||
|
||
### 修改
|
||
- 功能 B 优化（涉及文件：src/yyy.ts）
|
||
|
||
### 已知问题
|
||
- [问题 1]：描述及临时解决方案
|
||
```
|
||
|
||
### 6. 用户审阅
|
||
|
||
- 将完整交付文档展示给用户
|
||
- 分段确认：接口文档 → 使用文档 → 部署文档 → 变更摘要
|
||
- 收集反馈并修改
|
||
- 循环直到用户确认
|
||
|
||
### 7. 保存文档
|
||
|
||
按以下格式保存完整交付文档：
|
||
|
||
```markdown
|
||
# 交付文档：<项目名称>
|
||
|
||
> 创建日期：YYYY-MM-DD
|
||
> 版本：1.0.0
|
||
> 状态：已交付
|
||
|
||
## 1. 项目概览
|
||
## 2. 接口文档
|
||
## 3. 使用文档
|
||
## 4. 部署文档
|
||
## 5. 变更摘要
|
||
```
|
||
|
||
保存到 `docs/deliverables/YYYY-MM-DD-<项目名>.md`
|
||
|
||
### 8. 发布执行（可选）
|
||
|
||
根据项目类型，询问用户是否需要执行发布操作：
|
||
|
||
```
|
||
是否执行发布操作？
|
||
[1] git tag + push
|
||
[2] npm publish / docker push
|
||
[3] 跳过，仅保留文档
|
||
```
|
||
|
||
如选择发布，协助用户执行对应的命令（通过 Bash tool），并记录操作日志。
|
||
|
||
### 9. 反馈收集（闭环）
|
||
|
||
交付完成后，收集本轮开发的反馈：
|
||
|
||
```markdown
|
||
## 反馈记录
|
||
|
||
> 对应交付：docs/deliverables/xxx.md
|
||
> 反馈日期：YYYY-MM-DD
|
||
|
||
### 评分（1-5）
|
||
- 需求理解准确度：
|
||
- 实现符合预期度：
|
||
- 整体满意度：
|
||
|
||
### 问题与优化点
|
||
- [ ] 问题 1
|
||
- [ ] 问题 2
|
||
|
||
### 是否启动新一轮迭代
|
||
- [ ] 是 → 更新 workflow-status.md 为"需求分析"阶段
|
||
- [ ] 否 → 标记流程结束
|
||
```
|
||
|
||
保存到 `docs/feedback/YYYY-MM-DD-<项目名>.md`。
|
||
|
||
更新 `docs/workflow-status.md`：
|
||
- 如用户选择迭代：当前阶段 = "需求分析"，提示 `/dev-requirement`
|
||
- 如用户结束：状态 = "已完成"
|
||
|
||
## 关键行为
|
||
|
||
- 接口文档必须基于实际代码，不凭空编造
|
||
- 环境变量从代码中实际提取（搜索 process.env、os.environ 等）
|
||
- 部署步骤基于项目实际配置（Dockerfile、CI/CD 等）
|
||
- 如无法从代码提取，明确标注"需手动补充"
|