requirements-analysis/docs/CORRECT_USAGE_GUIDE.md

简化的需求分析MCP服务 - 基于AI软件工程（优化版）6步流程

# 📖 正确使用指南 - 确保文档保存

## ⚠️ **重要提醒**

如果你发现步骤执行后没有保存MD文档，请检查以下几点：

## 🔍 **问题诊断清单**

### 1. **确认使用了正确的MCP工具**
你必须使用我们提供的MCP工具，而不是直接对话：

#### ❌ 错误方式（不会保存文档）
```
直接在Claude Desktop中说：
"请帮我分析这个项目的需求..."
```

#### ✅ 正确方式（会保存文档）
```
1. 先使用start_requirements_analysis工具
2. 然后使用execute_step工具执行每个步骤
```

### 2. **正确的MCP工具调用流程**

#### 第一步：启动需求分析
```
工具名称: start_requirements_analysis
参数:
{
  "projectName": "你的项目名称",
  "projectType": "new",
  "industry": "你的行业",
  "background": "项目背景（至少20字符）",
  "objectives": "项目目标（至少20字符）"
}
```

#### 第二步：执行步骤
```
工具名称: execute_step
参数:
{
  "sessionId": "从第一步获得的会话ID",
  "stepNumber": 1,
  "result": "AI执行第1步的完整结果"
}
```

### 3. **检查输出目录**
文档会保存在以下位置：
```
outputs/[项目名称]/
├── README.md
├── step1-项目信息.md
├── step2-AI分析.md
├── step3-需求文档初版.md
├── step4-质量分析.md
├── step5-改进建议.md
└── step6-最终文档.md
```

### 4. **查看日志确认**
正确执行时，你应该看到这些日志：
```
[INFO] 步骤1结果已保存
[INFO] Successfully loaded step 1 document: step1-项目信息.md
```

## 🛠️ **故障排查步骤**

### 步骤1：检查MCP服务是否正常启动
```bash
cd requirements-analysis-simple
npm start
```
应该看到：
```
需求分析MCP服务已启动
```

### 步骤2：检查Claude Desktop配置
确保在Claude Desktop配置文件中正确配置了MCP服务器：
```json
{
  "mcpServers": {
    "requirements-analysis-simple": {
      "command": "npx",
      "args": ["requirements-analysis-simple"]
    }
  }
}
```

### 步骤3：重启Claude Desktop
修改配置后需要重启Claude Desktop。

### 步骤4：使用正确的工具调用方式
在Claude Desktop中，确保你看到了可用的MCP工具列表，包括：
- start_requirements_analysis
- execute_step
- get_step_result
- list_projects
- get_project_summary

### 步骤5：检查文件权限
确保当前用户有写入权限到项目目录。

## 🎯 **完整使用示例**

### 示例1：启动需求分析
在Claude Desktop中输入：
```
请使用start_requirements_analysis工具启动需求分析，项目信息如下：
- 项目名称：智能客服系统
- 项目类型：new
- 所属行业：金融科技
- 项目背景：当前客服响应时间过长，客户满意度下降，人工成本高昂，需要智能化客服系统提升服务效率和用户体验
- 核心目标：提升客服响应速度50%，降低人工成本30万/年，客户满意度提升至95%以上，支持7x24小时服务
```

### 示例2：执行第1步
```
请使用execute_step工具执行第1步，参数如下：
- sessionId: [从上一步获得的会话ID]
- stepNumber: 1
- result: [AI分析后的完整结果]
```

## 🔧 **调试模式**

如果仍然有问题，可以启用调试模式：

### 1. 查看详细日志
```bash
DEBUG=* npm start
```

### 2. 手动测试
运行我们提供的测试脚本：
```bash
node test-mcp-flow.js
```

### 3. 检查文件系统
手动检查outputs目录是否存在和可写：
```bash
ls -la outputs/
```

## 📞 **常见问题解答**

### Q: 为什么我看不到MCP工具？
A: 检查Claude Desktop配置和服务启动状态。

### Q: 工具调用成功但没有文档？
A: 检查文件权限和路径，查看错误日志。

### Q: 文档保存了但内容不对？
A: 检查execute_step的result参数是否完整。

### Q: 如何确认文档引用正常工作？
A: 查看日志中的"Successfully loaded step X document"消息。

## ✅ **成功标志**

当一切正常工作时，你应该看到：

1. **启动成功**：
```
需求分析MCP服务已启动
```

2. **工具可见**：
在Claude Desktop中可以看到MCP工具列表

3. **执行成功**：
```
[INFO] 步骤X结果已保存
[INFO] Successfully loaded step X document
```

4. **文档存在**：
在outputs/[项目名称]/目录下有对应的MD文件

5. **内容正确**：
文档只包含AI执行结果，不包含提示词

---

**如果按照以上步骤仍然有问题，请提供具体的错误信息和日志，我们可以进一步诊断。**