# 案例七：Claude Code 持续对话

## 场景说明

EvoFlow 可以调用外部 Claude Code 实例来完成编码、调试和代码库修改任务。智能体作为"指挥官"，Claude Code 作为"执行者"，两者配合实现 AI 辅助开发。

## 前置准备

- 已完成 [安装](../getting-started/installation.md)
- 已安装并配置 Claude Code CLI
- 已配置 ACP（Agent Communication Protocol）包装器

## 操作步骤

### 步骤 1：确保 Claude Code 可用

在终端中确认 Claude Code 已正确安装：

```bash
codex --version
```

同时确认 ACP 包装器已安装：

```bash
npx -y @zed-industries/codex-acp --version
```

<!-- 截图占位：claude-code-step1.png — 确认 Claude Code -->

> **截图说明**：展示终端中运行版本检查命令的输出结果。

### 步骤 2：打开对话并进入执行模式

在 EvoPanel 中打开对话页面，选择 **「执行」** 或 **「无限」** 模式。

<!-- 截图占位：claude-code-step2.png — 选择执行模式 -->

> **截图说明**：展示对话模式选择，标注"执行"模式。

### 步骤 3：输入编码任务

向智能体描述你需要完成的开发任务。

**示例提示词：**

```
请帮我在当前项目中添加一个 REST API 端点 /api/health，
返回服务的健康状态（JSON 格式），
包括版本号、运行时间和依赖连接状态。
```

<!-- 截图占位：claude-code-step3.png — 输入编码任务 -->

> **截图说明**：展示输入框中输入编码任务的界面。

### 步骤 4：智能体委托 Claude Code

智能体会分析任务，判断需要调用 Claude Code 来完成，然后通过 ACP 协议将任务委托出去。

<!-- 截图占位：claude-code-step4.png — 委托 Claude Code -->

> **截图说明**：展示智能体委托 Claude Code 的过程，标注任务传递的信息。

### 步骤 5：查看 Claude Code 执行过程

Claude Code 会读取项目代码、理解上下文、编写代码并进行测试。执行过程会实时回传到 EvoPanel。

<!-- 截图占位：claude-code-step5.png — 执行过程 -->

> **截图说明**：展示 Claude Code 执行编码任务的实时输出。

### 步骤 6：审查代码变更

Claude Code 完成后，智能体会将代码变更展示给你审查。你可以查看修改的文件、新增的代码和测试结果。

<!-- 截图占位：claude-code-step6.png — 审查变更 -->

> **截图说明**：展示代码变更的对比视图，标注新增/修改的内容。

### 步骤 7：确认或要求修改

如果代码符合预期，确认接受变更。如果需要调整，继续对话：

**示例提示词：**

```
请在 health 接口中增加数据库连接池的状态信息。
```

智能体会将修改意见再次委托给 Claude Code 执行。

### 步骤 8：持续迭代

重复步骤 4-7，与智能体和 Claude Code 进行多轮对话，逐步完善代码。这种"对话式开发"让你可以边想边写，无需离开对话界面。

<!-- 截图占位：claude-code-step7.png — 持续迭代 -->

> **截图说明**：展示多轮对话后代码逐步完善的整个过程。

## 小结

通过 Claude Code 集成，EvoFlow 不仅能"说"，还能"做"。智能体理解你的意图，Claude Code 执行具体编码工作，两者配合实现高效的 AI 辅助开发流程。

<!-- ACCEPTANCE_RECORD_BEGIN -->

# 《案例七：Claude Code 持续对话》流式验收报告

| 元数据项 | 填写 |
|----------|------|
| **报告 ID** | `20260512-085718-case7-v1` |
| **关联案例 / 场景** | [案例七：Claude Code 持续对话](claude-code-continuous.md) |
| **关联仓库文档** | 本页正文上方「案例」章节 |
| **执行人** | 自动化 `case_doc_acceptance_append.py` |
| **执行时间（本地）** | `2026-05-12T08:57:43.420870+00:00` |
| **代码版本** | `a877c3b3` |
| **Gateway 基址** | `http://127.0.0.1:8070` |
| **LangGraph 端口（若已知）** | 2070（由 Gateway 代理） |
| **session_key** | `agent:main:case-doc-20260512-085718` |
| **默认 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-7-20260512-085718.json`

---

## 3. 交互总览

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

**thread 与时间线：**

| 序号 | thread_id | 用途说明 |
|------|-----------|----------|
| 1 | `d68de02a-3727-4b63-b869-20f87847c20c` | 见下节分轮 |

---

## 4. 分轮交互记录

### 4.1 轮次 1

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

| 字段 | 内容 |
|------|------|
| **thread_id** | `d68de02a-3727-4b63-b869-20f87847c20c` |
| **本轮在用户界面的序号** | 1 / 2 |
| **activated_scenarios** | `["execute"]` |
| **collab_phase** | `idle` |
| **is_plan_mode / subagent_enabled / thinking_enabled** | `False` / `True` / `True` |
| **recursion_limit** | `400` |
| **用户输入（原文，完整）** | `我在维护 EvoFlow 的 Python 后端，如果只想给运维同事加一个「看一眼就知道服务活着」的说明，你会建议从哪几个文件或目录入手？先给简短建议，不要直接改仓库。` |

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

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

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

| — | （无） |  |  |  |  |

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

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

```text
用户询问关于EvoFlow Python后端的健康检查/服务状态监控的建议。这是一个闲聊/问答场景，不需要调用工具。用户要求简短建议，不要直接改仓库。

基于记忆，EvoFlow项目路径是 D:\github\EvoFlow，是一个基于LangGraph的AI超级代理系统，采用FastAPI后端+Next.js前端。

对于"看一眼就知道服务活着"的需求，通常需要：
1. 健康检查端点 (health check endpoint)
2. 服务状态监控
3. 简单的状态页面或接口

对于FastAPI后端，常见的做法：
- /health 或 /status 端点
- 返回服务状态、版本、依赖服务状态等
- 可能涉及主应用文件、路由配置、配置管理等

我不需要调用工具，先给简短建议即可。</think>对于 FastAPI 后端，建议从这几个位置入手：

**1. 主应用入口**（通常是 `main.py` / `app.py` 或 `api/` 目录下的入口文件）
   - 加一个裸的 `/health` 或 `/status` 路由，返回 `{"status": "ok", "version": "x.x"}` 即可

**2. 路由注册处**（`routers/`、`routes/` 或 `api/v1/` 等目录）
   - 如果已有路由拆分，可以单独建一个 `health.py` 路由模块，保持关注点分离

**3. 配置/元信息文件**（`config.py`、`settings.py` 或 `pyproject.toml`）
   - 从这儿读取版本号、启动时间戳，让健康接口返回的信息更有价值

**4. 依赖服务检查（可选）**
   - 如果后端依赖数据库/Redis/外部API，可以在健康接口里加轻量探针（如 `SELECT 1`），但保持超时极短（<2s），避免变成"重操作"

**最简单的做法**：直接在现有主应用文件里加两行，10 分钟搞定，运维同事 `curl http://localhost:8000/health` 就能看到 `{"status":"alive"}`。需要时再拆成独立模块或加依赖检查。

需要我进仓库看看具体结构，再指出来改哪一行吗？
```

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

| 项 | 内容 |
|----|------|
| **对照准则条目** | 案例七：持续对话第一轮 |
| **子目标是否达成** | 符合 |
| **证据** | `ai_text_seen=True`；侧载种类数 `0` |

### 4.2 轮次 2

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

| 字段 | 内容 |
|------|------|
| **thread_id** | `d68de02a-3727-4b63-b869-20f87847c20c` |
| **本轮在用户界面的序号** | 2 / 2 |
| **activated_scenarios** | `["execute"]` |
| **collab_phase** | `idle` |
| **is_plan_mode / subagent_enabled / thinking_enabled** | `False` / `True` / `True` |
| **recursion_limit** | `400` |
| **用户输入（原文，完整）** | `接上条：如果只动一处，你更推荐先改 README 里加 health 说明，还是加一个 HTTP health 路由？两三句话定优先级即可。` |

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

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

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

| — | （无） |  |  |  |  |

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

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

```text
用户询问关于EvoFlow Python后端的健康检查/服务状态监控的建议。这是一个闲聊/问答场景，不需要调用工具。用户要求简短建议，不要直接改仓库。

基于记忆，EvoFlow项目路径是 D:\github\EvoFlow，是一个基于LangGraph的AI超级代理系统，采用FastAPI后端+Next.js前端。

对于"看一眼就知道服务活着"的需求，通常需要：
1. 健康检查端点 (health check endpoint)
2. 服务状态监控
3. 简单的状态页面或接口

对于FastAPI后端，常见的做法：
- /health 或 /status 端点
- 返回服务状态、版本、依赖服务状态等
- 可能涉及主应用文件、路由配置、配置管理等

我不需要调用工具，先给简短建议即可。</think>对于 FastAPI 后端，建议从这几个位置入手：

**1. 主应用入口**（通常是 `main.py` / `app.py` 或 `api/` 目录下的入口文件）
   - 加一个裸的 `/health` 或 `/status` 路由，返回 `{"status": "ok", "version": "x.x"}` 即可

**2. 路由注册处**（`routers/`、`routes/` 或 `api/v1/` 等目录）
   - 如果已有路由拆分，可以单独建一个 `health.py` 路由模块，保持关注点分离

**3. 配置/元信息文件**（`config.py`、`settings.py` 或 `pyproject.toml`）
   - 从这儿读取版本号、启动时间戳，让健康接口返回的信息更有价值

**4. 依赖服务检查（可选）**
   - 如果后端依赖数据库/Redis/外部API，可以在健康接口里加轻量探针（如 `SELECT 1`），但保持超时极短（<2s），避免变成"重操作"

**最简单的做法**：直接在现有主应用文件里加两行，10 分钟搞定，运维同事 `curl http://localhost:8000/health` 就能看到 `{"status":"alive"}`。需要时再拆成独立模块或加依赖检查。

需要我进仓库看看具体结构，再指出来改哪一行吗？
```

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

| 项 | 内容 |
|----|------|
| **对照准则条目** | 案例七：持续对话第二轮承接 |
| **子目标是否达成** | 符合 |
| **证据** | `ai_text_seen=True`；侧载种类数 `0` |

---

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

### 5.1 结论摘要

- **总体结果：**通过
- **阻塞项：**无
- **非阻塞问题：**是否调用编码侧载取决于 ACP/环境配置。


### 5.2 风险与影响

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

### 5.3 后续建议

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

<!-- ACCEPTANCE_RECORD_END -->
