evoflow-debugging git:20260912.6c490fdA

Immutable. This exact content is served forever at /api/v1/blob/838e16a85f355d8b.

---
name: evoflow-debugging
description: EvoFlow 项目内 Bug / 行为不符 / 数据展示错误排查。先定验收与 ground truth，沿数据流找第一个错层，三条 Gate（真实证据、生产消费函数、最小复现）后再改代码。用户报功能异常、UI 与 API 不一致、测试失败、运维页数据不对时使用；深度方法论可读 superpowers-systematic-debugging。
---

# EvoFlow 问题排查

适用：功能异常、UI 与预期不符、API 字段不对、测试失败、性能/回归等**需要找根因并修复**的任务。

通用调试心法（四阶段、根因追踪等）可读 **superpowers-systematic-debugging**；本文聚焦 **EvoFlow 仓库 + 工具链**。

## 0. 先定验收（动手改代码前必做）

用一句话写清：

- **怎样算对**
- **ground truth** 是哪条数据（API 响应字段 / DB 行 / 日志 / 测试断言）
- **明确不做什么**（范围外的不顺手改）

## 1. 沿数据流定层（禁止盲改 UI）

沿链路找**第一个错的数据**：

`用户所见 → 前端渲染 → API 字段 → 后端聚合/摘要 → 存储/上游写入`

**API/存储已错 → 先修后端，不要先改前端映射。**

## 2. 三条 Gate（违反则禁止提交代码改动）

1. **一条真实证据**：贴出或读取错误态原始数据（curl/API JSON、日志、DB 字段、失败测试输出）。
2. **责任边界**：指出**谁生产、谁消费**该字段/行为（函数名或文件路径）。
3. **可复现**：最小输入复现「输入 A → 输出 B（错的）」——单元测试 mock、短脚本、或直接调责任函数。**读代码觉得对 ≠ 验证通过。**

## 3. 验证顺序

1. **标准路径**：文档/最常见格式 → 应通过
2. **真实路径**：生产或用户提供的 payload
3. **边界路径**：空值、旧格式、流式落库、fallback 字段（如 `additional_kwargs`、`{type, data}` wire format）

标准路径过、真实/边界挂 → 补解析/兼容，勿推翻整条链路。

## 4. 修复纪律

- **一次只动一层**；改完立刻跑验证（测试 / API / 复现脚本）
- **最小 diff**：只修根因，不顺手重构
- **禁止无证据回退**：未证明改错时，不要整片 revert
- **防再犯**：wire format / 摘要 / 序列化类问题加测**真实结构**的回归测试

## 5. 与本项目工具的配合

- **先** `scenario(activate, agent)`，再 `rg` / `search_code_index` / `read` / `worker`
- 跑验证：`terminal`（pytest、curl、短脚本）
- 可并行、边界清晰的子问题：`subagent` 委派，主会话汇总后再改

## 6. 交付说明

回复用户时：**根因（一句）· 改了哪一层 · 如何验证**（重启谁 / 看哪个字段 / 跑哪条测试）。