ruflo 生产环境验证 Agent：确保零 Mock、零占位实现的上线就绪实践

本文围绕 .claude/agents/testing/production-validator.md 这份 Agent 定义文档展开，介绍 ruflo 中"生产验证专家（Production Validation Specialist）"如何以真实系统为靶标，验证应用已完整实现、无 mock/fake/stub 残留、可在类生产环境部署运行。读者将获得一套可直接复用 Go 源码级与测试级佐证：如何用静态扫描发现未完成实现、如何对真实数据库/外部 API/基础设施做端到端校验、如何做负载与安全验证，以及 ruflo 自身的三层回归防护与 1000+ 测试容器化套件如何支撑这一角色落地。

ruflo（claude-flow 原仓库）以"agent meta-harness"自居，生态里同时存在两派测试哲学：tdd-london-swarm.md（London 学派，开发期用 mock 定义协作契约）与本文主角 production-validator（发布期"清剿"mock）。二者的交接点正是本 Agent 的核心命题：开发期允许的替身，在上线前必须一个不剩。

---

角色定位：从"功能写完"到"真的能上线"

文档开门见山给出角色定义：Production Validation Specialist（生产验证专家）负责确保应用被完整实现、能对真实系统做测试、并具备生产部署就绪度，最终校验最终代码库中不存在任何 mock、fake 或 stub 残留。

对照仓库结构可以看到，同一份 Agent 定义被分发到多个位置，形成"一处定义、多处生效"的形态：

• 主副本（.claude/agents/testing/ 目录，随 Claude Code 会话加载）
• CLI 包内副本
• MCP 包内副本

目录语义 .claude/agents/testing/ 表明：该文件是 Claude Code 子代理（subagent）的 YAML-frontmatter 定义——name 用于路由、description 用于自动选择。也就是说，"上线前校验"在 ruflo 中被沉淀成一个可被 Codex / Claude Code / swarm 按需唤起专业角色，而不是一次性的手工清单。

Core Responsibilities（核心职责）

#	职责	对应验证目标
1	Implementation Verification	所有组件必须真实实现，不得 mock
2	Production Readiness	应用须能在真实数据库、API、服务上运行
3	End-to-End Testing	对真实系统集成执行全链路测试
4	Deployment Validation	在类生产环境验证功能正确性
5	Performance Validation	确认真实负载下的表现达到需求

---

五大验证策略：从静态扫描到真实压测

文档把验证拆为 5 种可操作策略。ruflo 仓库中能找到与之对应的真实落地脚本，下面逐条结合实现讲透。

1. 实现完整性扫描（Implementation Completeness Check）

这是"零 Mock 上线"的第一道闸门——用正则在整个代码库中查找"看起来像替身实现"的痕迹。文档给出的核心模式表如下：

正则	命中的典型	含义
/mock[A-Z]\w+/g	mockService、mockRepository	mock 对象渗透进生产代码
/fake[A-Z]\w+/g	fakeDatabase、fakeAPI	fake 替身被留在生产路径
/stub[A-Z]\w+/g	stubMethod、stubService	stub 占位实现
/TODO.*implementation/gi	// TODO: implement this	明确未完成标记
/FIXME.*mock/gi	// FIXME: replace mock	已知待替换的 mock
/throw new Error\(['"]not implemented/gi	throw new Error("not implemented")	显式未实现抛错

扫描逻辑对每个文件、每个模式做一次匹配，命中即记录一条违规项 { file, issue, pattern }。这类"按错误模式搜索整个代码库"的思路，在 ruflo 里被大量固化成独立审计脚本，最典型的是 scripts/audit-exit-bypass-antipattern.mjs：它用花括号深度追踪扫描 plugins/*/scripts/ 下所有 .mjs 文件，检测同一函数内 return console.log(...) 早退与 process.exit(1) 非零退出并存的反模式——这正是文档所述"上线前把隐藏缺陷扫地出门"的工程化表达。

2. 真实数据库集成（Real Database Integration）

文档强调：连接真实的测试数据库，而不是内存替代品。示例用 beforeAll 读取 TEST_DB_HOST / TEST_DB_NAME 建立真实连接，随后在 UserRepository 上执行完整 CRUD 往返：

• create → 断言 id 存在、createdAt 为 Date
• findById → 断言读回的对象与写入一致（持久化被验证）
• update → 断言字段确实更新
• delete → 断言再查询返回 null

这套"写到真实存储再读回来对账"的断言结构，与 ruflo 仓库中 tests/ 下基于真实 RVF 文件的测试理念一致（如 tests/rvf-integration.test.ts 等会真实读写 .rvf/.ledger 数据而非内存假象），也与 tests/docker-regression/README.md 描述的"docker 内跑真实集成测试"对齐。

3. 外部 API 集成（External API Integration）

以支付服务为例，文档展示两类关键断言：

1. 真实调用成功路径：用 STRIPE_TEST_KEY 打到 Stripe 测试环境，断言返回 paymentIntent.id 匹配 /^pi_/、status === 'requires_payment_method'、金额正确——验证的是真实网络往返与真实响应结构；
2. 真实错误路径：故意传 invalid_key，断言请求 rejects.toThrow('Invalid API key')——验证外部服务对坏凭据的真实反应，而非本地模拟器。

实操提示：外部 API 验证应使用提供方自己的测试沙箱（Test API Key / Sandbox 环境），既拿到真实返回又不动生产数据。这正是"零 mock、零假数据依赖"对第三方集成的正确姿势。

4. 基础设施验证（Infrastructure Validation）

文档给出 Redis 缓存与 SMTP 两个典型场景：

// Validate real infrastructure components
describe('Infrastructure Validation', () => {
  it('should connect to real Redis cache', async () => {
    const cache = new RedisCache({
      host: process.env.REDIS_HOST,
      port: parseInt(process.env.REDIS_PORT),
      password: process.env.REDIS_PASSWORD
    });

    await cache.connect();

    // Test cache operations
    await cache.set('test-key', 'test-value', 300);
    const value = await cache.get('test-key');
    expect(value).toBe('test-value');

    await cache.delete('test-key');
    const deleted = await cache.get('test-key');
    expect(deleted).toBeNull();

    await cache.disconnect();
  });

  it('should send real emails via SMTP', async () => {
    const emailService = new EmailService({
      host: process.env.SMTP_HOST,
      port: parseInt(process.env.SMTP_PORT),
      auth: {
        user: process.env.SMTP_USER,
        pass: process.env.SMTP_PASS
      }
    });

    const result = await emailService.send({
      to: '[e-mail]',
      subject: 'Production Validation Test',
      body: 'This is a real email sent during validation'
    });

    expect(result.messageId).toBeDefined();
    expect(result.accepted).toContain('[e-mail]');
  });
});

关键信息全部来自环境变量（host/port/password/凭据），测试代码里不硬编码任何环境信息——这与文档后续"Environment Validation"一节的理念闭环。ruflo 中这类"连接真实中间件"的验证同样有容器化载体：tests/docker-regression/docker-compose.yml 提供 MCP server 等真实组件，MCP_SERVER_HOST/MCP_SERVER_PORT（默认 3000）等环境变量以表驱动方式注入容器。

5. 负载下的性能验证（Performance Under Load）

文档提供两种压测形态，目标阈值清晰：

形态 A — 瞬时并发：Promise.all 同时发出 100 个请求打 /health，断言：

• 全部返回 200；
• 总耗时 < 5000ms（100 请求 5 秒内）；
• 平均响应时间 < 50ms。

形态 B — 持续负载：1 分钟内以 10 req/s 稳定施压 /api/users（失败的请求用 .catch(() => null) 兜住，避免单点拖垮统计），最终断言成功率 > 0.95，即 95% 以上的请求成功。其"按秒节流"写法（等待剩余时间凑满 1s）非常适合在真实服务上做可控的稳定性冒烟。

注意文档中阈值（5s/50ms/95%）只是模板化的断言示例，实际项目应依据自身 SLO 调整，避免拍脑袋写死性能目标。

---

Validation Checklist：上线前的四道检查门

1. 代码质量扫描（CLI 一把梭）

文档给出一组可直接复制到 CI 的 grep 命令，注意其精心设计的排除规则——--exclude-dir=__tests__、--exclude="*.test.*"、--exclude="*.spec.*"，确保只扫生产代码：

# No mock implementations in production code
grep -r "mock\|fake\|stub" src/ --exclude-dir=__tests__ --exclude="*.test.*" --exclude="*.spec.*"

# No TODO/FIXME in critical paths
grep -r "TODO\|FIXME" src/ --exclude-dir=__tests__

# No hardcoded test data
grep -r "test@\|example\|localhost" src/ --exclude-dir=__tests__

# No console.log statements
grep -r "console\." src/ --exclude-dir=__tests__

ruflo 将这一层自动化成了"行为冒烟测试（behavioral smoke）"——docs/validation/README.md 记录的 2026-05-08 三个回归（#1859/#1862/#1867）全部通过了单元测试但用户侧崩坏，原因正是单测验证代码路径、不验证用户可见的失败模式。典型的真实落地是 scripts/smoke-cli-npx-install.mjs：它用 pnpm pack 真实打 CLI 包、在临时目录 npm install <tarball>、再运行 cli --version，断言 stderr/stdout 不出现 Invalid Version——把一个"装不上"的用户失败，变成可在 CI 复现的断言。

2. 环境配置校验（缺一不可的变量白名单）

// Validate environment configuration
const validateEnvironment = () => {
  const required = [
    'DATABASE_URL',
    'REDIS_URL',
    'API_KEY',
    'SMTP_HOST',
    'JWT_SECRET'
  ];

  const missing = required.filter(key => !process.env[key]);

  if (missing.length > 0) {
    throw new Error(`Missing required environment variables: ${missing.join(', ')}`);
  }
};

启动即失败（fail-fast）是最小可用性保障：一旦有必需变量缺失，立即抛错，而非让应用带着残缺配置"半活"到用户手里。字段名单应随项目裁剪——数据库、缓存、对外 API 凭据、邮件、JWT 密钥是 Web 应用的典型五件套。在 ruflo 的容器化回归套件里，同样的思路体现为 tests/docker-regression/README.md 的环境变量表：TEST_REPORT_PATH、CLAUDE_FLOW_MEMORY_PATH、MCP_SERVER_HOST/PORT 等均有默认值，测试环境缺省即可跑通。

3. 安全验证（鉴权、注入、传输三连）

// Validate security measures
describe('Security Validation', () => {
  it('should enforce authentication', async () => {
    const response = await request(app)
      .get('/api/protected')
      .expect(401);

    expect(response.body.error).toBe('Authentication required');
  });

  it('should validate input sanitization', async () => {
    const maliciousInput = '<script>alert("xss")</script>';

    const response = await request(app)
      .post('/api/users')
      .send({ name: maliciousInput })
      .set('Authorization', `Bearer ${validToken}`)
      .expect(400);

    expect(response.body.error).toContain('Invalid input');
  });

  it('should use HTTPS in production', () => {
    if (process.env.NODE_ENV === 'production') {
      expect(process.env.FORCE_HTTPS).toBe('true');
    }
  });
});

三层防线分别对应：未授权请求必须 401、XSS 载荷必须被拒绝（400）、生产模式必须强制 HTTPS。注意这里的 Bearer ${validToken} 暗示鉴权用例应配合真实可用的测试令牌（文档"Best Practices"进一步强调用真实身份提供方做鉴权测试）。

4. 部署就绪度（健康检查 + 优雅停机）

// Validate deployment configuration
describe('Deployment Validation', () => {
  it('should have proper health check endpoint', async () => {
    const response = await request(app)
      .get('/health')
      .expect(200);

    expect(response.body).toMatchObject({
      status: 'healthy',
      timestamp: expect.any(String),
      uptime: expect.any(Number),
      dependencies: {
        database: 'connected',
        cache: 'connected',
        external_api: 'reachable'
      }
    });
  });

  it('should handle graceful shutdown', async () => {
    const server = app.listen(0);

    // Simulate shutdown signal
    process.emit('SIGTERM');

    // Verify server closes gracefully
    await new Promise(resolve => {
      server.close(resolve);
    });
  });
});

健康检查不止返回 200，还要求把依赖状态（数据库、缓存、外部 API）透出——这样负载均衡器与 K8s readiness probe 才能真正感知依赖故障；优雅停机用例则模拟 SIGTERM 后确认连接能干净关闭、不丢在途请求。这正是文档末尾"生产环境怎么测，就怎么活"哲学的可执行载体。

---

Best Practices：让"上线零惊吓"成为默认状态

文档最后给出四组最佳实践，浓缩为"真数据、真基础设施、真负载、真安全"：

1. 真实数据（Real Data Usage）：用接近生产的测试数据而非占位值；用真实文件上传而非假文件；覆盖真实用户场景与边界情况。
2. 基础设施测试（Infrastructure Testing）：打真实数据库而非内存版；验证网络连通性与超时；用真实服务故障演练失败场景。
3. 性能验证（Performance Validation）：测量真实负载下的响应时间；用真实数据量测内存；用生产级数据集验证扩展行为。
4. 安全测试（Security Testing）：用真实身份提供方测鉴权；用真实证书验证加密；用真实角色与权限测授权。

文末那句话是整个角色的价值观锚点（原文照录）："当应用到达生产环境时，它必须与测试时表现完全一致——没有意外、没有 mock 实现、没有假数据依赖。"

---

ruflo 如何为这名 Agent 提供弹药：三层回归防护体系

production-validator 的核心（清剿 mock、验证真实）在 ruflo 里并非孤军作战，仓库自建了一套三层回归防护体系（见 docs/validation/README.md 架构图）：

Layer 1: Behavioral smoke tests  —— 真实安装/真实子进程/断言用户可见信号
Layer 2: Cryptographic witness   —— SHA-256 + marker 子串 + Ed25519 签名
Layer 3: Append-only temporal    —— 每条 fix 的状态时间线 (JSONL)

• Layer 1 行为冒烟：对应"真实系统集成验证"。典型如 scripts/smoke-cli-npx-install.mjs（真实打包+安装 CLI）与 plugins/ruflo-core/scripts/test-hooks.mjs（真实子进程喂 JSON 断言 hook 行为），把一个"用户装不上/用不对"的失败模式变成 CI 断言。
• Layer 2 密码学见证：每个已修复缺陷记录"文件 SHA-256 + 语义 marker 子串"，由 verification/README.md 说明的确定性种子 sha256(gitCommit + ':ruflo-witness/v1') 派生 Ed25519 密钥签名——任何持有同一 commit 的人都能重导公钥独立验证，无需提交私钥。每次生成调用 scripts/regen-witness.mjs 封装。
• Layer 3 时间线历史：verification/{linux,macos,windows}/history.jsonl 以 JSONL 追加每条快照，history.mjs regressions 可定位某回归首次出现的 commit 窗口，把"git bisect 扫全量"收敛为"只 diff 这个小窗口"。

这套体系的动机与本文档一脉相承：单测通过 ≠ 用户不受伤。ruflo 因而把验证堆栈做成与项目无关的工具包，全量脚本落在 plugins/ruflo-core/scripts/witness/，任何项目拷贝即可用——这恰好是 production-validator 角色想要达到的效果的工程化注脚。

此外，tests/docker-regression/README.md 展示了 1000+ 用例的 Docker 化回归套件：docker-compose up --build test-runner 一键跑全量，覆盖 CLI/MCP/Agents/Swarm/Hooks/Plugins/Security/Memory/Workers/Performance 十余个类别，并给出 GitHub Actions 与 GitLab CI 的接入 YAML——为"类生产环境端到端验证"提供了可复制的编排范例。

---

上手：如何让这名验证 Agent 与现有测试协作

综合文档职责与仓库实践，落地 production-validator 的最小闭环可分四步：

1. 静态清零：先在 CI 挂上"生产代码零 mock/TODO"的 grep 或 audit 脚本（如文档的 grep 四连），把硬性红线前置到每次提交。
2. 真实集成：将数据库/缓存/SMTP/外部 API 用例连到真实测试环境，环境信息全部走 env（参照本文第 2、4 策略代码），确保 CI 有真实的 DB/Redis/Sandbox 凭据可注入。
3. 压力与安全门：加一档并发+持续压测（阈值按项目 SLO 定），并把鉴权/注入/HTTPS 三个安全用例纳入发布门禁。
4. 发布见证：借鉴 ruflo 的做法，把每个已修复缺陷登记为"文件 + marker"，发布前 regen 生成签名清单、verify 校验——marker 选择是承重技能，宜用 diff 中独特子串（如 (await import('better-sqlite3')).default），忌用 function/TODO 这类泛词。

与 London 学派的分工提醒：开发期 .claude/agents/testing/tdd-london-swarm.md 通过 mock 定义对象间协作契约、驱动设计（这是 TDD 该做的事）；而上线前由 production-validator 出面，确保那些 mock 只存在于 __tests__ 里、测试环境里，绝不出现在生产代码与真实依赖路径上。两派合起来，才构成"先靠 mock 快速收敛设计、再以真实系统兜底验证"的完整质量闭环。