requirements-analysis/docs/AI_AGENT_INSTRUCTIONS.md

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

# 🤖 AI智能体专用指令

## 🔥 **核心要求**

**重要**：本MCP服务的核心功能是将每个步骤的AI执行结果保存为独立的MD文档。

### 必须遵循的流程：
1. **启动项目**：使用 `start_requirements_analysis` 工具
2. **执行步骤**：使用 `execute_step` 工具（这是保存文档的唯一方式）
3. **检查状态**：使用 `check_document_status` 工具验证文档保存

## 📋 **详细操作指令**

### 第一步：项目启动
```
工具名称: start_requirements_analysis
目的: 创建项目会话并获取sessionId
参数要求:
- projectName: 项目名称（避免特殊字符）
- projectType: new/upgrade/integration/other
- industry: 所属行业
- background: 项目背景（至少20字符）
- objectives: 项目目标（至少20字符）
```

### 第二步：执行步骤（关键）
```
工具名称: execute_step
目的: 执行AI分析并自动保存为MD文档
重要性: 🔥 这是保存文档的唯一方式！
参数要求:
- sessionId: 从第一步获得的会话ID
- stepNumber: 当前步骤编号(1-6)
- result: AI执行的完整结果内容
```

### 第三步：验证保存
```
工具名称: check_document_status
目的: 确认文档是否成功保存
参数要求:
- projectName: 项目名称（与第一步一致）
```

## ⚠️ **AI智能体常见错误**

### 错误1：直接回复而不使用工具
❌ **错误做法**：
```
AI直接回复："根据您的需求，我分析如下..."
```

✅ **正确做法**：
```
AI使用execute_step工具提交分析结果
```

### 错误2：跳过execute_step工具
❌ **错误做法**：
```
AI执行分析后直接进入下一步
```

✅ **正确做法**：
```
AI执行分析后必须调用execute_step工具保存结果
```

### 错误3：不检查保存状态
❌ **错误做法**：
```
AI调用execute_step后不确认保存状态
```

✅ **正确做法**：
```
AI调用execute_step后检查返回结果中的文档保存确认
```

## 🎯 **成功标志**

### execute_step调用成功后应该看到：
```
[AI执行的步骤结果]

📁 文档保存状态: 步骤X的结果已保存为MD文档到 outputs/项目名称/stepX-*.md
```

### check_document_status调用成功后应该看到：
```
📁 项目文档状态检查

项目名称: [项目名称]
文档目录: outputs/[项目名称]

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

文档详情:
📄 step1-项目信息.md (XXX字节, 修改时间: XXXX)
📄 step2-AI分析.md (XXX字节, 修改时间: XXXX)
...

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

## 🔧 **AI智能体调试指南**

### 如果没有看到文档保存确认：
1. **检查工具调用**：确认使用了 `execute_step` 工具
2. **检查参数**：确认sessionId、stepNumber、result参数正确
3. **检查返回结果**：查看是否包含"📁 文档保存状态"信息

### 如果文档保存确认显示但找不到文件：
1. **使用检查工具**：调用 `check_document_status` 工具
2. **检查项目名称**：确保项目名称一致且无特殊字符
3. **检查权限**：确认文件系统写入权限

### 如果工具调用失败：
1. **检查MCP服务**：确认服务正常运行
2. **检查参数格式**：确认JSON格式正确
3. **查看错误信息**：根据错误提示进行修正

## 📝 **完整示例流程**

### 示例对话流程：

**用户**："请帮我分析一个智能客服系统项目"

**AI智能体正确响应**：
```
我将帮您进行需求分析。首先启动需求分析流程：

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

[获得sessionId后]
现在执行第1步分析：

[执行AI分析]
=== 标准化项目信息 ===
[详细分析内容...]

[调用execute_step工具保存结果]
参数: {
  "sessionId": "[获得的sessionId]",
  "stepNumber": 1,
  "result": "[上述分析内容]"
}

[确认文档保存]
✅ 第1步分析完成并已保存为MD文档
```

## 🎯 **关键提醒**

1. **每个步骤都必须使用execute_step工具**
2. **检查返回结果中的文档保存确认**
3. **使用check_document_status工具验证保存状态**
4. **保持项目名称的一致性**
5. **确保AI执行结果的完整性**

---

**总结**：AI智能体必须理解并遵循"分析→调用execute_step→确认保存"的流程，这是保存过程文档的唯一正确方式。