# 案例一：在对话中使用主智能体

## 场景说明

你已经安装并配置好了 EvoFlow，想要和默认的主智能体（Lead Agent）进行对话，让它帮你解答问题、分析内容或执行任务。

## 前置准备

- 已完成 [安装](../getting-started/installation.md)
- 已配置至少一个 AI 模型（API Key）
- 已启动 EvoPanel 并登录

## 操作步骤

### 步骤 1：打开对话页面

在 EvoPanel 左侧导航栏中，点击 **「对话」** 图标，进入对话页面。

<!-- 截图占位：use-main-agent-step1.png — 打开对话页面 -->

> **截图说明**：展示 EvoPanel 左侧导航栏，标注"对话"图标的位置。

### 步骤 2：选择对话模式

在对话页面上方，你会看到四种模式选择：

| 模式 | 适用场景 |
|------|----------|
| **聊天** | 快速问答、简单咨询 |
| **规划** | 需要深度分析、多步骤思考的问题 |
| **执行** | 需要调用工具或委托子智能体完成的任务 |
| **无限** | 全部能力开放，适合复杂场景 |

选择一个适合你当前需求的模式。

<!-- 截图占位：use-main-agent-step2.png — 选择对话模式 -->

> **截图说明**：展示对话模式选择区域，标注四种模式的切换按钮。

### 步骤 3：输入你的问题

在底部输入框中输入你的问题或指令，按回车发送。

**示例提示词：**

```
帮我分析一下目前 Python 项目中依赖管理的最佳实践，
有哪些主流方案？各自的优缺点是什么？
```

<!-- 截图占位：use-main-agent-step3.png — 输入问题 -->

> **截图说明**：展示输入框输入问题的界面，标注发送按钮。

### 步骤 4：查看流式响应

主智能体会以流式方式输出回答，支持 Markdown 渲染。如果智能体调用了工具（如搜索、文件读取），你可以在对话中看到工具调用的过程。

<!-- 截图占位：use-main-agent-step4.png — 查看流式响应 -->

> **截图说明**：展示智能体流式输出回答的界面，标注工具调用可视化区域。

### 步骤 5：多轮对话

你可以继续追问、要求补充或让智能体调整回答方向。主智能体会保持上下文连贯性。

**示例提示词：**

```
请帮我用表格的形式对比这几种方案，
并推荐一个最适合中型团队的选择。
```

<!-- 截图占位：use-main-agent-step5.png — 多轮对话 -->

> **截图说明**：展示多轮对话的完整界面，标注上下文保持的效果。

### 步骤 6：上传文件或多模态输入（可选）

你可以粘贴截图或拖拽图片到对话中，主智能体会进行图片识别和分析。

<!-- 截图占位：use-main-agent-step6.png — 上传图片 -->

> **截图说明**：展示上传图片后智能体识别和分析的界面。

## 小结

完成以上步骤后，你已经掌握了与主智能体对话的基本方式。主智能体是 EvoFlow 的核心交互入口，后续创建智能体、技能、定时任务等操作都可以在对话中通过自然语言指令完成。

<!-- ACCEPTANCE_RECORD_BEGIN -->

# 《案例一：在对话中使用主智能体》流式验收报告

| 元数据项 | 填写 |
|----------|------|
| **报告 ID** | `20260512-084430-case1-v1` |
| **关联案例 / 场景** | [案例一：在对话中使用主智能体](use-main-agent.md) |
| **关联仓库文档** | 本页正文上方「案例」章节 |
| **执行人** | 自动化 `case_doc_acceptance_append.py` |
| **执行时间（本地）** | `2026-05-12T08:45:27.583313+00:00` |
| **代码版本** | `a877c3b3` |
| **Gateway 基址** | `http://127.0.0.1:8070` |
| **LangGraph 端口（若已知）** | 2070（由 Gateway 代理） |
| **session_key** | `agent:main:case-doc-20260512-084430` |
| **默认 assistant_id** | `lead_agent` |

---

## 1. 测试范围与通过准则

**本报告覆盖：**与本案例文档对应的流式/API 验收（共 **2** 次用户发起）。

**功能通过准则：**以本案例文档操作步骤中「可经流式接口验证」的子目标为准；无未处理 SSE error；主答复可读。

**性能与可观测性准则：**记录 `request_total_ms`、TTFT（`first_ai_visible_ms`）及侧载耗时，供与历史 JSON 对比。

---

## 2. 环境与前置条件

| 检查项 | 状态（是/否/不适用） | 说明 |
|--------|----------------------|------|
| 模型与 API Key | 是 | 以本机已配置为准 |
| 技能 / MCP / 渠道 | 未逐项核对 | 见案例前置说明 |
| 沙箱与写盘范围 | 未逐项核对 | 见网关配置 |
| 与本场景相关的配置项 | 未逐项核对 |  |

**原始机器产物：** `docs/cases/reports/raw/case-doc-1-20260512-084430.json`

---

## 3. 交互总览

| 指标 | 值 |
|------|-----|
| **用户发起流式交互总次数** | 2 |
| **涉及 thread_id 数量** | 1 |
| **是否出现 SSE error / HTTP 非 2xx** | 否 |
| **工具调用总次数（含重复 tool_call_id 刷新）** | 0 |

**thread 与时间线：**

| 序号 | thread_id | 用途说明 |
|------|-----------|----------|
| 1 | `7f72c750-5958-46b5-a6f0-ce81e5688841` | 见下节分轮 |

---

## 4. 分轮交互记录

### 4.1 轮次 1

#### 4.1.1 请求与用户输入

| 字段 | 内容 |
|------|------|
| **thread_id** | `7f72c750-5958-46b5-a6f0-ce81e5688841` |
| **本轮在用户界面的序号** | 1 / 2 |
| **activated_scenarios** | `["chat"]` |
| **collab_phase** | `idle` |
| **is_plan_mode / subagent_enabled / thinking_enabled** | `False` / `False` / `False` |
| **recursion_limit** | `200` |
| **用户输入（原文，完整）** | `帮我分析一下目前 Python 项目中依赖管理的最佳实践，有哪些主流方案？各自的优缺点是什么？` |

#### 4.1.2 流式与模型侧时序（本轮）

| 指标 | 值（ms） | 说明 |
|------|----------|------|
| **request_total_ms** | 28968.239 | 自 POST 起至流读完 |
| **first_sse_payload_ms** | 1458.306 | 至首条有效 data: |
| **first_ai_visible_ms（TTFT）** | 27033.125 | 至首段可见助手正文 |
| **assistant_visible_stream_ms** | 1644.101 | 首末次可见正文时间差 |
| **本轮是否出现 error 事件** | 否 |  |

#### 4.1.3 工具调用明细（本轮，按发生顺序）

| — | （无） |  |  |  |  |

#### 4.1.4 模型输出（本轮）

- [x] **正文粘贴**（完整或截断说明见上）

```text
Python 项目依赖管理确实是个值得深入讨论的话题。让我为你系统梳理一下主流方案及其优缺点。

## 主流方案概览

### 1. **pip + requirements.txt**（传统方案）

**优点：**
- 简单直观，入门门槛低
- 几乎所有 Python 开发者都熟悉
- 工具链成熟，生态支持完善

**缺点：**
- 无法锁定依赖的确切版本（transitive dependencies）
- 不同环境可能产生不同的依赖树
- 手动维护繁琐，容易遗漏

---

### 2. **pipenv**（Pip + Virtualenv 的整合）

**优点：**
- 自动创建和管理虚拟环境
- 生成 `Pipfile` 和 `Pipfile.lock` 锁定依赖
- 安全性检查（`pipenv check`）

**缺点：**
- 性能较慢，大型项目体验差
- 锁定文件有时难以解析
- 社区热度有所下降

---

### 3. **poetry**（当前最推荐）

**优点：**
- 统一的 `pyproject.toml` 配置
- 精准的依赖锁定（`poetry.lock`）
- 内置虚拟环境管理
- 支持打包和发布到 PyPI
- 依赖解析算法更优

**缺点：**
- 学习曲线略陡
- 部分边缘场景（如 C 扩展）配置复杂
- 与某些 CI/CD 工具集成需适配

---

### 4. **conda**（数据科学首选）

**优点：**
- 不仅管理 Python 包，还管理非 Python 依赖（C/C++ 库）
- 预编译二进制包，安装快
- 环境隔离彻底

**缺点：**
- 包仓库相对 PyPI 较小
- 与 pip 混用容易出问题
- 体积较大

---

### 5. **uv**（新兴高性能工具）

**优点：**
- Rust 编写，速度极快（比 pip 快 10-100 倍）
- 兼容 pip/requirements.txt 生态
- 内置虚拟环境管理
- 支持锁定文件

**缺点：**
- 相对较新，生态仍在成熟
- 部分高级功能还在开发中

---

### 6. **pdm**（PEP 582 倡导者）

**优点：**
- 遵循现代 PEP 标准
- 支持 `__pypackages__` 本地安装（无需虚拟环境）
- 类似 poetry 的体验

**缺点：**
- 社区规模相对较小
- `__pypackages__` 模式尚未广泛支持

---

## 选择建议

| 场景 | 推荐工具 |
|------|---------|
| 通用 Web/工具项目 | **Poetry** |
| 数据科学/ML | **Conda** 或 **Poetry** |
| 追求极致性能 | **uv** |
| 简单脚本/学习 | **pip + venv** |
| 遗留项目维护 | **pip-tools** |

---

## 最佳实践要点

1. **始终使用锁定文件**（lock file）确保可复现构建
2. **区分依赖类型**：生产依赖 vs 开发依赖 vs 测试依赖
3. **定期更新依赖**：关注安全漏洞和版本兼容性
4. **CI/CD 中缓存依赖**：加速构建流程
5. **考虑使用工具链组合**：如 `uv` + `ruff` + `mypy`

目前我个人最推荐 **Poetry** 作为通用方案，**uv** 作为性能敏感场景的选择。你目前项目是什么类型？我可以给更具体的建议。
```

#### 4.1.5 本轮结论（非总评）

| 项 | 内容 |
|----|------|
| **对照准则条目** | 案例一 §步骤 3 |
| **子目标是否达成** | 符合 |
| **证据** | `ai_text_seen=True`；侧载种类数 `0` |

### 4.2 轮次 2

#### 4.2.1 请求与用户输入

| 字段 | 内容 |
|------|------|
| **thread_id** | `7f72c750-5958-46b5-a6f0-ce81e5688841` |
| **本轮在用户界面的序号** | 2 / 2 |
| **activated_scenarios** | `["chat"]` |
| **collab_phase** | `idle` |
| **is_plan_mode / subagent_enabled / thinking_enabled** | `False` / `False` / `False` |
| **recursion_limit** | `200` |
| **用户输入（原文，完整）** | `请帮我用表格的形式对比这几种方案，并推荐一个最适合中型团队的选择。` |

#### 4.2.2 流式与模型侧时序（本轮）

| 指标 | 值（ms） | 说明 |
|------|----------|------|
| **request_total_ms** | 26977.932 | 自 POST 起至流读完 |
| **first_sse_payload_ms** | 1170.998 | 至首条有效 data: |
| **first_ai_visible_ms（TTFT）** | 1185.42 | 至首段可见助手正文 |
| **assistant_visible_stream_ms** | 23878.914 | 首末次可见正文时间差 |
| **本轮是否出现 error 事件** | 否 |  |

#### 4.2.3 工具调用明细（本轮，按发生顺序）

| — | （无） |  |  |  |  |

#### 4.2.4 模型输出（本轮）

- [x] **正文粘贴**（完整或截断说明见上）

```text
## Python 依赖管理方案对比

| 维度 | pip+req.txt | pipenv | poetry | conda | uv | pdm |
|:---|:---|:---|:---|:---|:---|:---|
| **学习曲线** | ⭐⭐ 极低 | ⭐⭐⭐ 中等 | ⭐⭐⭐ 中等 | ⭐⭐⭐ 中等 | ⭐⭐ 低 | ⭐⭐⭐ 中等 |
| **锁定依赖** | ❌ 手动 | ✅ 自动 | ✅ 自动 | ⚠️ 有限 | ✅ 自动 | ✅ 自动 |
| **虚拟环境** | 手动管理 | 自动 | 自动 | 自动 | 自动 | 可选 `__pypackages__` |
| **安装速度** | ⭐⭐⭐ 慢 | ⭐⭐ 很慢 | ⭐⭐⭐ 中等 | ⭐⭐⭐⭐ 快 | ⭐⭐⭐⭐⭐ 极快 | ⭐⭐⭐⭐ 快 |
| **打包发布** | ❌ 需额外工具 | ❌ 需额外工具 | ✅ 内置 | ⚠️ 需配置 | ⚠️ 开发中 | ✅ 内置 |
| **非Python依赖** | ❌ 不支持 | ❌ 不支持 | ❌ 不支持 | ✅ 支持 | ❌ 不支持 | ❌ 不支持 |
| **IDE支持** | ⭐⭐⭐⭐⭐ 完美 | ⭐⭐⭐⭐ 良好 | ⭐⭐⭐⭐⭐ 完美 | ⭐⭐⭐⭐ 良好 | ⭐⭐⭐⭐ 良好 | ⭐⭐⭐⭐ 良好 |
| **社区活跃度** | ⭐⭐⭐⭐⭐ 极高 | ⭐⭐⭐ 下降 | ⭐⭐⭐⭐⭐ 极高 | ⭐⭐⭐⭐⭐ 极高 | ⭐⭐⭐⭐⭐ 快速上升 | ⭐⭐⭐⭐ 稳定 |
| **CI/CD兼容** | ⭐⭐⭐⭐⭐ 完美 | ⭐⭐⭐⭐ 良好 | ⭐⭐⭐⭐⭐ 完美 | ⭐⭐⭐⭐ 良好 | ⭐⭐⭐⭐⭐ 完美 | ⭐⭐⭐⭐ 良好 |
| **Windows支持** | ⭐⭐⭐⭐⭐ 完美 | ⭐⭐⭐⭐ 良好 | ⭐⭐⭐⭐⭐ 完美 | ⭐⭐⭐⭐⭐ 完美 | ⭐⭐⭐⭐⭐ 完美 | ⭐⭐⭐⭐⭐ 完美 |

---

## 关键指标雷达图（文字版）

`​``
                    易用性
                      ⬆️
           pip ─────🟢───── uv
            ↓               ↓
    兼容性 ←── poetry ──→ 性能
            ↓               ↓
         conda ─────🔴───── pdm
                      ⬇️
                   功能丰富
`​``

- 🟢 **Poetry**：各项指标均衡，无明显短板
- 🔴 **pipenv**：逐渐边缘化，不推荐新项目

---

## 🏆 中型团队推荐：**Poetry**

### 推荐理由

| 考量因素 | Poetry 优势 |
|:---|:---|
| **团队协作** | `pyproject.toml` 单文件配置，版本控制友好 |
| **新人 onboarding** | 文档完善，社区案例丰富 |
| **可复现构建** | `poetry.lock` 精确锁定所有依赖树 |
| **发布流程** | 内置 `poetry build` + `poetry publish`，简化 CI/CD |
| **依赖冲突解决** | 智能解析算法，比 pipenv 更可靠 |
| **生态兼容** | 完全兼容 PyPI，与现有工具链无缝集成 |

### 典型工作流

`​``bash
# 初始化项目
poetry new my-project && cd my-project

# 添加依赖
poetry add fastapi sqlalchemy
poetry add --group dev pytest black ruff

# 安装（自动创建虚拟环境）
poetry install

# 锁定并导出（CI/CD 用）
poetry lock && poetry export -f requirements.txt -o requirements.txt
`​``

### 备选方案

- 若团队**极度追求构建速度** → **uv**（未来趋势，但生态仍在成熟）
- 若涉及**大量科学计算/ML库** → **Conda**（管理 CUDA 等非 Python 依赖更方便）

---

需要我提供 Poetry 的详细迁移指南，或者针对你们团队的具体技术栈做进一步分析吗？
```

#### 4.2.5 本轮结论（非总评）

| 项 | 内容 |
|----|------|
| **对照准则条目** | 案例一 §步骤 5 |
| **子目标是否达成** | 符合 |
| **证据** | `ai_text_seen=True`；侧载种类数 `0` |

---

## 5. 测试意见（文档末尾总评）

### 5.1 结论摘要

- **总体结果：**通过
- **阻塞项：**无
- **非阻塞问题：**无


### 5.2 风险与影响

无额外结论；以本案例业务风险为准。

### 5.3 后续建议

若发布前 gate：可对比 `docs/cases/reports/raw` 中历史 JSON 做基线回归。

<!-- ACCEPTANCE_RECORD_END -->
