multi-agent-e2e-validation

多 Agent 端到端验证

自我演进的技能：此技能会在使用过程中不断改进。如果说明有误、参数发生偏移，或需要采用变通方案，请立即修复此文件，不要拖延。仅针对真实且可复现的问题进行更新。

概述

一套规范化工作流，用于启动并行验证 Agent，全面测试数据库重构。在 QuestDB 迁移中，该流程成功发现了 5 个关键 Bug（系统故障率达 100%），避免这些 Bug 随产品发布到生产环境。

何时使用此技能

在以下情况下使用此技能：

• 数据库重构（例如，从基于文件的 v3.x 迁移到 v4.x QuestDB）
• 需要验证的架构迁移
• 批量数据摄取管道测试
• 具有多个验证层的系统迁移
• 以数据库为核心的系统发布前验证

主要成果：

• 并行执行 Agent，全面覆盖验证范围
• 结构化验证报告（VALIDATION_FINDINGS.md）
• 发现并按严重程度分类 Bug（严重／中等／低）
• 发布就绪情况评估

核心方法

1. 验证架构（三层模型）

第 1 层：环境设置

• 容器编排（Colima/Docker）
• 数据库部署和架构应用
• 连通性验证（ILP、PostgreSQL、HTTP 端口）
• 配置文件创建和验证

第 2 层：数据流验证

• 批量摄取测试（CloudFront → QuestDB）
• 对照 SLO 进行性能基准测试
• 多月数据摄取
• 去重测试（重新摄取场景）
• 类型转换验证（FLOAT→LONG 转换）

第 3 层：查询接口验证

• 高级查询方法（get_latest、get_range、execute_sql）
• 边界情况（limit=1、跨月边界）
• 错误处理（无效的符号、日期、参数）
• 缺口检测 SQL 兼容性

2. Agent 编排模式

顺序执行与并行执行：

Agent 1 (Environment) → [SEQUENTIAL - prerequisite]
  ↓
Agent 2 (Bulk Loader) → [PARALLEL with Agent 3]
Agent 3 (Query Interface) → [PARALLEL with Agent 2]

依赖规则：必须先通过环境验证，才能进行数据流／查询验证

动态 Todo 管理：

• 从高级计划开始（由 ADR 定义阶段）
• 从 Todo 列表中移除已完成的 Agent
• 发现 Bug 时扩展 Todo 列表（例如，Agent 3 发现 Bug #5）
• 逐步更新 VALIDATION_FINDINGS.md

3. 验证脚本结构

每个 Agent 都会生成：

1. 测试脚本（例如，test_bulk_loader.py）
   • 至少 5 个测试函数，具有明确的通过／失败标准
   • 结构化输出（测试名称、结果、详情）
   • 末尾附带摘要报告
2. 产物（日志、配置文件、证据）
3. 发现报告（Bug、严重程度、修复提案）

测试结构示例：

def test_feature(conn):
    """Test 1: Feature description"""
    print("=" * 80)
    print("TEST 1: Feature description")
    print("=" * 80)

    results = {}

    # Test 1a: Subtest name
    print("\n1a. Testing subtest:")
    result_1a = perform_test()
    print(f"   Result: {result_1a}")
    results["subtest_1a"] = result_1a == expected_1a

    # Summary
    print("\n" + "-" * 80)
    all_passed = all(results.values())
    print(f"Test 1 Results: {'✓ PASS' if all_passed else '✗ FAIL'}")
    for test_name, passed in results.items():
        print(f"  - {test_name}: {'✓' if passed else '✗'}")

    return {"success": all_passed, "details": results}

4. Bug 分类和跟踪

严重程度级别：

• 🔴 严重：系统完全故障（例如，API 不匹配、时间戳损坏）
• 🟡 中等：功能降级（例如，性能低于 SLO）
• 🟢 低：轻微问题、边界情况

Bug 报告格式：

#### Bug N: Descriptive Name (**SEVERITY** - Status)

**Location**: `file/path.py:line`

**Issue**: One-sentence description

**Impact**: Quantified impact (e.g., "100% ingestion failure")

**Root Cause**: Technical explanation

**Fix Applied**: Code changes with before/after

**Verification**: Test results proving fix

**Status**: ✅ FIXED / ⚠️ PARTIAL / ❌ OPEN

5. 发布就绪决策框架

发布／不发布标准：

BLOCKER = Any Critical bug unfixed
SHIP = All Critical bugs fixed + (Medium bugs acceptable OR fixed)
DEFER = >3 Medium bugs unfixed OR any High-severity bug

决策示例：

• 发现 5 个严重 Bug → 全部修复 ✅
• 1 个中等 Bug（性能比 SLO 低 55%）→ 可接受 ✅
• 结论：可发布

工作流：分步指南

第 1 步：制定验证计划（由 ADR 驱动）

输入：ADR 文档（例如，ADR-0002 QuestDB 重构） 输出：包含 3–7 个 Agent 的验证计划

计划结构：

## Validation Agents

### Agent 1: Environment Setup

- Deploy QuestDB via Docker
- Apply schema.sql
- Validate connectivity (ILP, PG, HTTP)
- Create .env configuration

### Agent 2: Bulk Loader Validation

- Test CloudFront → QuestDB ingestion
- Benchmark performance (target: >100K rows/sec)
- Validate deduplication (re-ingestion test)
- Multi-month ingestion test

### Agent 3: Query Interface Validation

- Test get_latest() with various limits
- Test get_range() with date boundaries
- Test execute_sql() with parameterized queries
- Test detect_gaps() SQL compatibility
- Test error handling (invalid inputs)

第 2 步：执行 Agent 1（环境）

目录结构：

tmp/e2e-validation/
  agent-1-env/
    test_environment_setup.py
    questdb.log
    config.env
    schema-check.txt

验证清单：

• ✅ 容器正在运行
• ✅ 端口可访问（9009 ILP、8812 PG、9000 HTTP）
• ✅ 架构已成功应用
• ✅ 已创建 .env 文件

第 3 步：并行执行 Agent 2–3

Agent 2：批量加载器

tmp/e2e-validation/
  agent-2-bulk/
    test_bulk_loader.py
    ingestion_benchmark.txt
    deduplication_test.txt

Agent 3：查询接口

tmp/e2e-validation/
  agent-3-query/
    test_query_interface.py
    gap_detection_test.txt

执行方式：

# Terminal 1
cd tmp/e2e-validation/agent-2-bulk
uv run python test_bulk_loader.py

# Terminal 2
cd tmp/e2e-validation/agent-3-query
uv run python test_query_interface.py

第 4 步：在 VALIDATION_FINDINGS.md 中记录发现

模板：

# E2E Validation Findings Report

**Validation ID**: ADR-XXXX
**Branch**: feat/database-refactor
**Date**: YYYY-MM-DD
**Target Release**: vX.Y.Z
**Status**: [BLOCKED / READY / IN_PROGRESS]

## Executive Summary

E2E validation discovered **N critical bugs** that would have caused [impact]:

| Finding | Severity | Status | Impact       | Agent   |
| ------- | -------- | ------ | ------------ | ------- |
| Bug 1   | Critical | Fixed  | 100% failure | Agent 2 |

**Recommendation**: [RELEASE READY / BLOCKED / DEFER]

## Agent 1: Environment Setup - [STATUS]

...

## Agent 2: [Name] - [STATUS]

...

步骤 5：迭代修复

对于每个 Bug：

1. 在 VALIDATION_FINDINGS.md 中记录，并标注 🔴/🟡/🟢 严重程度
2. 修复源代码
3. 重新运行失败的测试
4. 将 Bug 状态更新为 ✅ FIXED
5. 使用语义化消息提交（例如：fix: correct timestamp parsing in CSV ingestion）

修复提交示例：

git add src/gapless_crypto_clickhouse/collectors/questdb_bulk_loader.py
git commit -m "fix: prevent pandas from treating first CSV column as index

BREAKING CHANGE: All timestamps were defaulting to epoch 0 (1970-01)
due to pandas read_csv() auto-indexing. Added index_col=False to
preserve first column as data.

Fixes #ABC-123"

步骤 6：最终验证与发布决策

运行所有测试：

/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
cd tmp/e2e-validation
for agent in agent-*; do
    echo "=== Running $agent ==="
    cd $agent
    uv run python test_*.py
    cd ..
done
SKILL_SCRIPT_EOF

更新 VALIDATION_FINDINGS.md 状态：

• 统计严重 Bug：X 个已修复，Y 个未解决
• 统计中等 Bug：X 个已修复，Y 个未解决
• 应用决策框架
• 将 Status 字段更新为 ✅ RELEASE READY 或 ❌ BLOCKED

真实案例：QuestDB 重构验证

背景：从基于文件的存储（v3.x）迁移到 QuestDB（v4.0.0）

发现的 Bug：

1. 🔴 Sender API 不匹配 - 使用了不存在的 Sender.from_uri()，而不是 Sender.from_conf()
2. 🔴 类型转换 - number_of_trades 以 FLOAT 类型发送，而架构要求 LONG
3. 🔴 时间戳解析 - pandas 将第一列视为索引 → 时间戳变为 epoch 0
4. 🔴 去重 - WAL 模式不提供 UPSERT 语义（需要 DEDUP ENABLE UPSERT KEYS）
5. 🔴 SQL 不兼容 - detect_gaps() 使用了 QuestDB 不支持的嵌套窗口函数

影响：如果没有这次验证，v4.0.0 发布时将出现 100% 数据损坏和 100% 写入失败

结果：5 个 Bug 全部修复，系统验证通过，v4.0.0 成功发布

常见误区

1. 跳过环境验证

❌ 不妥：假设 Docker/数据库运行正常，直接开始数据写入测试
✅ 推荐：Agent 1 先验证环境，及早发现端口冲突和架构错误

2. 按顺序执行 Agent

❌ 不妥：运行 Agent 2，等待完成后再运行 Agent 3
✅ 推荐：并行运行 Agent 2 和 Agent 3（两者之间没有依赖关系）

3. 手动报告测试结果

❌ 不妥：将测试输出复制并粘贴到 Slack/电子邮件中
✅ 推荐：使用结构化的 VALIDATION_FINDINGS.md，记录严重程度、状态和修复进度

4. 忽略中等 Bug

❌ 不妥：“性能比 SLO 低 55%，但我们以后再修复。” ✅ 推荐：在 VALIDATION_FINDINGS.md 中记录，并明确做出发布/不发布的决定

5. 修复后不重新验证

❌ 不妥：应用修复，假设问题已解决，然后继续
✅ 推荐：重新运行失败的测试，并在 VALIDATION_FINDINGS.md 中更新状态

资源

scripts/

不适用 - 验证脚本因项目而异（存储在 tmp/e2e-validation/ 中）

references/

• example_validation_findings.md - 完整的 VALIDATION_FINDINGS.md 模板
• agent_test_template.py - 用于创建验证测试脚本的模板
• bug_severity_classification.md - 详细的严重程度标准和示例

assets/

不适用 - 验证产物因项目而异

---

故障排查

问题	原因	解决方案
容器无法启动	Colima/Docker 未运行	在 Agent 1 之前运行 colima start
端口冲突	端口已被占用	停止冲突的容器或使用其他端口
架构应用失败	SQL 语法无效	检查 schema.sql 是否兼容特定数据库
Agent 1 未运行时 Agent 2/3 失败	环境未验证	确保 Agent 1 完成后再启动 Agent 2/3
测试脚本导入错误	缺少依赖	在 Agent 目录中运行 uv pip install
Bug 状态未更新	VALIDATION_FINDINGS.md 内容过时	每次修复后手动刷新状态
并行 Agent 相互干扰	共享资源冲突	确保 Agent 使用隔离目录
决策不明确	严重级别混有 Critical/Medium	严格按照文档应用 Go/No-Go 标准

执行后反思

此技能完成后，在关闭任务前进行反思：

0. 定位自身。 — 找到此 SKILL.md 的规范路径，然后再编辑。
1. 哪里失败了？ — 修复导致问题的指令。
2. 哪些地方比预期更有效？ — 将其提升为推荐实践。
3. 有哪些偏离？ — 修复任何与实际情况不符的脚本、参考资料或依赖项。
4. 记录下来。 — 添加演进日志条目，注明触发原因、修复内容和证据。

切勿推迟。下一次调用将继承你留下的一切。