eve-verification-plans

Eve 验证计划

编写智能体验证计划——以 Markdown 文档完整说明验证 Eve 兼容应用是否正常工作并符合 Eve 平台规范的步骤。人类或智能体均可按计划执行。

适用场景

• 为新的 Eve 兼容应用构建验证流程
• 审核现有应用是否符合 Eve 平台规范
• 完成需要结构化验证的重要功能开发后
• 交接前——端到端证明应用按 Eve 的方式正常工作
• 帮助新团队了解“在 Eve 上正确构建”是什么样的

快速开始

# 1. Create the verification directory in your project
mkdir -p e2e-verification/00-smoke

# 2. Copy the smoke template
cp templates/00-smoke-test-plan.md e2e-verification/00-smoke/

# 3. Customize for your app (endpoints, services, agents)
# 4. Run it

六个验证维度

每个 Eve 应用最多有六个需要验证的维度。涵盖所有适用维度。

维度	工具	适用时机	合规性检查
平台合规性	Eve CLI + 清单检查	始终	CLI 一致性、清单规范、密钥管理模型
服务层	Eve CLI + REST API	始终	每个端点都可通过 CLI 访问；无需使用 kubectl
输入 / 摄取	仓库测试夹具 + 上传命令	应用接受文件时	确定性测试夹具、真实解析流程
数据层	Eve CLI + 数据库迁移	应用有数据库时	通过 Eve 流水线运行迁移，而非手动执行 SQL
UI / 视觉	agent-browser 或 Playwright	有前端时	SSO 登录、深色 / 浅色模式、可由智能体测试
智能体行为	eve job follow + 优化	有智能体时	高效完成任务，不走入死胡同

验证计划格式

每个场景都是一份独立的 Markdown 文档：

# Scenario NN: <Name>

**Time:** ~Nm
**Environment:** staging | local | both
**Parallel Safe:** Yes/No
**Requires:** LLM | Browser | None

<one-paragraph description>

## Prerequisites

- What must be true before running
- Required secrets, auth, prior scenarios

## Fixtures

- File paths used by this scenario
- Provenance or generation command for each
- Why these files are representative

## Setup

\```bash
# Environment detection + auth
# Project/org setup
# Fixture validation or generation
\```

## Phases

### Phase 1: <Name>

\```bash
# Commands to execute
\```

**Expected:**
- Bullet list of assertions
- Each assertion is pass/fail verifiable

### Phase 2: ...

## Success Criteria

- [ ] Checkboxes for every pass/fail assertion
- [ ] Grouped by phase

## Debugging

| Symptom | Diagnostic | Fix |
|---------|-----------|-----|
| ... | ... | ... |

## Cleanup

\```bash
# Teardown commands
\```

格式规则

• 感知环境：每份计划都从环境检测开始——EVE_API_URL 用于判断云端还是本地环境
• 独立完整：除文档说明的前置条件外，不假设任何状态
• 明确测试夹具：每个上传 / 导入的文件都已检入代码库，或可通过文档中的命令生成
• 分阶段：拆分为可独立运行的阶段（安全时可并行运行）
• 基于断言：每个步骤都包含明确的 Expected:，并规定通过 / 失败的判定标准
• 便于调试：包含故障排除部分，说明症状 → 诊断 → 修复

平台合规性验证

测试功能前，先确认应用是按 Eve 的方式构建的。每套验证流程都从以下清单开始：

• .eve/manifest.yaml 存在，且通过 eve project sync --dry-run 检查
• 清单遵循当前规范（优先使用 name，而非旧版 project）
• 所有服务都有可通过 Eve 入口访问的健康检查端点
• CLI 可与每个 API 端点交互（没有仅限 UI 的功能）
• 通过 eve secrets 管理密钥，不硬编码，也不通过 env 文件管理
• 数据库迁移作为流水线步骤运行，而非通过手动脚本运行
• 智能体（如有）在 agents.yaml 中定义，并配置运行框架配置文件
• 流水线（如有）在清单中定义，且可通过 eve pipeline run 运行
• 前端（如有）通过 Eve SSO 进行身份验证，而非使用自定义身份验证
• 上传 / 导入流程（如有）有已检入代码库的确定性测试夹具，或可在本地生成的测试夹具

完整清单及其理由请参见 references/eve-conformance-checks.md。

服务层验证

优先通过 CLI 测试所有 API 接口：

TOKEN=$(eve auth token --raw)

# Health check (always first)
curl -sf "${APP_SCHEME}://api.${APP_DOMAIN}/health" | jq '.'

# App API via auth token
curl -sf -H "Authorization: Bearer $TOKEN" \
  "${APP_SCHEME}://api.${APP_DOMAIN}/endpoint" | jq '.field'

CLI 一致性断言：对于测试计划中的每个 curl 调用，都要问：“这也能通过 CLI 命令完成吗？”如果不能，就提交问题——不要接受这种情况。

模式：

1. 在适用时使用 Eve CLI 命令（deploy、env、job、secrets）
2. 如果应用遵循 eve-app-cli 模式，则使用 应用 CLI
3. 对于自定义端点，通过带身份验证令牌的 curl 使用 REST API
4. 身份验证：通过 eve auth mint 或 eve auth token --raw 创建令牌

输入 / 摄取验证

当应用接受上传文件、导入内容或文档包时，验证必须包含测试夹具计划。

固定样例选择顺序

1. 如果现有仓库固定样例符合已接受的文件类型且结果确定，则优先复用
2. 使用已提交的脚本在本地生成合成固定样例
3. 仅当本地生成会降低真实度时，才选用小型公有领域固定样例

固定样例矩阵

• 最小有效样例 — 可接受的最小文件，用于测试成功路径
• 典型真实场景 — 有代表性的文档／媒体／导入文件
• 边界／无效样例 — 错误类型、格式错误的结构或大小边界
• 跨格式 — 如果应用接受多种类型（PDF + Markdown + CSV），则逐一验证

检查内容

• 通过应用的真实入口（CLI、REST 端点或浏览器上传）接受文件
• MIME／类型检测和元数据正确
• 存储／持久化路径正确
• 下游处理产生预期结果
• 对被拒绝或格式错误的固定样例进行明确的错误处理

规则：如果计划写着“上传一个 PDF 样例”，就必须包含实际文件路径或生成步骤。“在网上找个 PDF”不可接受。

详细指南请参阅 references/fixture-patterns.md。

UI 验证

当应用有前端时，请验证视觉质量和交互流程。

SSO 令牌注入

# Mint an SSO token via CLI
SSO_TOKEN=$(eve auth mint --email [email protected] --org $ORG_ID --format sso-jwt)

# Use agent-browser with the token
agent-browser --session verify open "${APP_URL}/auth/callback?token=${SSO_TOKEN}"
agent-browser --session verify wait --url "**/dashboard"
agent-browser --session verify screenshot ./e2e-verification/artifacts/dashboard.png

检查内容

• 页面渲染时没有控制台错误
• 深色模式和浅色模式均可正常使用（两种模式都截图）
• 关键用户流程顺利完成（登录 → 仪表板 → 操作 → 结果）
• 在标准断点下布局响应正常
• 表单正确提交并触发验证

有关工具选择指南和模式，请参阅 references/ui-verification-patterns.md。

Agent 验证

当应用包含 Eve Agent 时，验证范围还包括行为质量。

1. 创建一个任务，以测试 Agent 的主要工作流
2. 跟踪执行情况：eve job follow <job-id>
3. 检查回执：eve job receipt <job-id>（令牌数、成本、时长）
4. 应用 eve-agent-optimisation 诊断工作流
5. 在测试计划中记录基线指标，以便检测回归

检查内容

• Agent 完成任务（输出正确）
• 令牌用量在可接受范围内
• 没有不必要的工具调用或无效路径
• 对错误情况进行妥善处理（输入错误、缺少密钥）
• 多 Agent 协作正常（任务按依赖顺序完成）

有关与优化的集成，请参阅 references/agent-verification-patterns.md。

部署周期模式

验证通常会发现问题。修复／部署循环如下：

云端（暂存环境）— 默认

discover bug → fix code → commit → tag release-v* → push tag →
  wait for CI (publish-images → infra dispatch → deploy) →
  re-run failed scenario

本地（k3d）

discover bug → fix code → pnpm build →
  ./bin/eh k8s-image push → ./bin/eh k8s deploy →
  re-run failed scenario

有关环境检测和等待模式，请参阅 references/deploy-cycle-patterns.md。

场景发现

如何确定给定应用需要创建哪些场景：

1. 阅读清单 — 每个服务都是验证目标
2. 阅读 Agent 配置 — 每个 Agent 都需要行为测试
3. 阅读 API 规范 — 每组端点都可能成为一个场景
4. 检查上传／导入入口 — 每种已接受的文件类别都需要固定样例
5. 检查流水线 — 构建／部署／工作流流水线需要端到端验证
6. 检查 UI — 每个页面／路由都需要视觉验证
7. 检查集成 — Webhook、聊天网关、外部 API

最小场景集

场景	必需	覆盖内容
00-smoke	始终	健康状态、身份验证、连通性 + Eve 一致性检查清单
01-deploy	始终	通过流水线构建、发布、部署，并验证端点
02-core-flow	始终	端到端的主要用户旅程（CLI + API）
03-ui-visual	有前端时	截图验证、SSO 登录、深色/浅色模式
04-input-ingestion	有上传/导入功能时	上传 fixture、解析、存储、错误处理
05-data-layer	有数据库时	通过流水线执行迁移、验证架构正确、数据完整性
06-agent-execution	有 Agent 时	验证 Agent 能正确完成主要任务
07-agent-optimization	有 Agent 时	基线指标 + 优化轮次
08-pipeline-flows	有流水线时	每条流水线均端到端运行，步骤按顺序成功执行

运行验证计划

顺序执行

# Run scenarios in order
for plan in e2e-verification/*/; do
  echo "=== Running: $plan ==="
  # Agent reads and executes the plan document
done

并行执行

标记为 Parallel Safe: Yes 的场景可以并发运行。通常：

• 00-smoke 首先运行（验证前置条件）
• 01-deploy 至 03-ui-visual 可以并行
• Agent 场景（06-07）依赖部署完成

CI 集成

# In CI, set environment and run
export EVE_API_URL=https://api.eve.example.com
eve auth login --email $CI_EMAIL --ssh-key $CI_SSH_KEY

# Run all scenarios, collect artifacts
mkdir -p e2e-verification/artifacts
# Agent executes each plan, screenshots/logs go to artifacts/

文件结构

<project-root>/
  e2e-verification/
    README.md                    # Index of all scenarios
    00-smoke/
      00-smoke-test-plan.md
    01-deploy/
      01-deploy-test-plan.md
    02-core-flow/
      02-core-flow-test-plan.md
      fixtures/
        README.md
        test-data.json
    03-ui-visual/
      03-ui-visual-test-plan.md
    04-input-ingestion/
      04-input-ingestion-test-plan.md
      fixtures/
        README.md
        sample-document.pdf
        sample-import.csv
        scripts/
          make-fixtures.sh
    artifacts/                   # Generated during runs (gitignored)

编号：使用 NN-kebab-name/ 目录，并配有同名的 NN-kebab-name-test-plan.md。编号表示执行顺序。编号可以不连续，便于插入新项而无需重命名。

Fixtures：每个依赖上传或导入输入的场景都应有一个同级的 fixtures/ 目录。fixtures/README.md 记录来源、生成步骤和敏感性说明。

参考资料

• references/test-plan-format.md — 完整的格式规范及带注释的示例
• references/eve-conformance-checks.md — Eve 的方式：验证内容及原因
• references/fixture-patterns.md — Fixture 的来源、制作和文档记录
• references/deploy-cycle-patterns.md — 云端和本地的修复/部署循环
• references/ui-verification-patterns.md — 浏览器自动化和 SSO 身份验证模式
• references/agent-verification-patterns.md — Agent 测试与优化集成
• references/deploy-cycle-patterns.md — 云端和本地的修复/部署循环
• references/ui-verification-patterns.md — 浏览器自动化和 SSO 身份验证模式
• references/agent-verification-patterns.md — Agent 测试与优化集成

模板

• templates/00-smoke-test-plan.md — 入门级冒烟测试 + 一致性模板
• templates/scenario-test-plan.md — 通用场景骨架
• templates/upload-ingest-test-plan.md — 包含 Fixture 矩阵的输入密集型场景

相关技能

技能	关系
eve-agent-optimisation	由 Agent 验证场景调用
eve-web-ui-testing-agent-browser	UI 验证工具
eve-deploy-debugging	部署循环故障排查
eve-cli-primitives	服务层测试中使用的 CLI 命令
eve-manifest-authoring	一致性检查验证的 Manifest 约定
eve-app-cli	App CLI 模式 — 验证断言 CLI 与其他接口保持一致
eve-pipelines-workflows	流水线场景测试的流水线约定
eve-auth-and-secrets	一致性检查验证的身份验证 + 密钥模型
eve-troubleshooting	验证失败时的一般调试
eve-read-eve-docs	当前 CLI/Manifest/身份验证行为的参考来源
eve-agent-native-design	一致性检查中体现的设计原则