requirements-analysis/docs/AI_AGENT_USAGE_GUIDE.md

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

# 🤖 AI智能体使用指南

## ✅ **针对AI智能体的优化**

我已经针对AI智能体的使用方式进行了优化，现在支持：

### 1. **文档保存状态确认**
每次执行`execute_step`后，返回结果会包含文档保存确认信息：
```
📁 文档保存状态: 步骤X的结果已保存为MD文档到 outputs/项目名称/stepX-*.md
```

### 2. **新增文档状态检查工具**
添加了`check_document_status`工具，可以随时检查文档保存状态。

## 🛠️ **AI智能体正确使用流程**

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

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

**重要**：执行后检查返回结果中的文档保存确认信息！

### 第三步：检查文档状态（可选）
```
使用工具: check_document_status
参数:
{
  "projectName": "你的项目名称"
}
```

## 🔍 **问题诊断步骤**

### 如果没有看到文档保存确认
1. **检查返回结果**：查看`execute_step`的返回结果是否包含"📁 文档保存状态"
2. **使用检查工具**：调用`check_document_status`工具确认文档状态
3. **查看错误信息**：如果有错误，会在返回结果中显示

### 如果文档检查显示"未找到文档"
可能的原因：
1. **项目名称不匹配**：确保使用相同的项目名称
2. **权限问题**：检查文件写入权限
3. **路径问题**：确认outputs目录可访问

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

### 示例1：启动项目
```
AI智能体调用：
工具: start_requirements_analysis
参数: {
  "projectName": "智能客服系统",
  "projectType": "new", 
  "industry": "金融科技",
  "background": "当前客服响应时间过长，需要智能化客服系统提升服务效率",
  "objectives": "提升客服响应速度50%，降低人工成本，提高客户满意度"
}

预期返回：包含sessionId的JSON响应
```

### 示例2：执行第1步
```
AI智能体调用：
工具: execute_step
参数: {
  "sessionId": "从上一步获得的ID",
  "stepNumber": 1,
  "result": "=== 标准化项目信息 ===\n【项目基本信息】\n..."
}

预期返回：包含"📁 文档保存状态"确认的响应
```

### 示例3：检查文档状态
```
AI智能体调用：
工具: check_document_status
参数: {
  "projectName": "智能客服系统"
}

预期返回：显示所有已保存文档的详细信息
```

## ⚠️ **AI智能体使用注意事项**

### 1. **等待异步操作完成**
AI智能体调用MCP工具时，确保等待工具完全执行完成再进行下一步。

### 2. **检查返回结果**
每次调用`execute_step`后，检查返回结果中是否包含文档保存确认信息。

### 3. **使用正确的项目名称**
在整个流程中使用一致的项目名称，避免中文字符可能导致的路径问题。

### 4. **错误处理**
如果工具调用失败，检查错误信息并根据提示进行修正。

## 🎯 **成功标志**

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

### execute_step返回结果包含：
```
[AI执行的步骤结果]

📁 文档保存状态: 步骤1的结果已保存为MD文档到 outputs/智能客服系统/step1-*.md
```

### check_document_status返回结果包含：
```
📁 项目文档状态检查

项目名称: 智能客服系统
文档目录: outputs/智能客服系统

已保存的步骤文档:
✅ 第1步
✅ 第2步

文档详情:
📄 step1-项目信息.md (1447字节, 修改时间: 2025-01-15 10:30:25)
📄 step2-AI分析.md (2156字节, 修改时间: 2025-01-15 10:35:42)

总计: 2个文档文件
✅ 文档保存正常
```

## 🔧 **故障排除**

### 问题1：AI智能体调用工具但没有文档
**解决方案**：
1. 检查`execute_step`返回结果中的文档保存确认
2. 使用`check_document_status`工具验证
3. 确认项目名称一致性

### 问题2：文档保存确认显示但找不到文件
**解决方案**：
1. 检查outputs目录权限
2. 确认项目名称中没有特殊字符
3. 查看系统日志获取详细错误信息

### 问题3：工具调用超时或失败
**解决方案**：
1. 确保MCP服务正常运行
2. 检查网络连接和权限
3. 重启MCP服务

## 📞 **技术支持**

如果按照以上步骤仍然有问题：

1. **收集信息**：
   - AI智能体的具体调用方式
   - 返回的错误信息
   - `check_document_status`的结果

2. **提供日志**：
   - MCP服务的启动日志
   - 工具调用的返回结果
   - 系统错误信息

3. **环境信息**：
   - 操作系统版本
   - Node.js版本
   - AI智能体类型和版本

---

**总结**：现在的MCP服务已经针对AI智能体进行了优化，每次执行步骤后都会明确确认文档保存状态。请按照上述流程使用，并检查返回结果中的确认信息。