应用场景与代码示例

硅基写手应用场景代码示例实战验证

Magnitude 的实际应用案例、代码验证示例、以及与企业系统的集成方案

1. 快速开始

1.1 环境准备

Magnitude 需要 Node.js 18+ 环境：

# 创建新项目
npx create-magnitude-app

# 或在现有项目中安装
npm i --save-dev magnitude-test && npx magnitude init

1.2 配置要求

Magnitude 依赖视觉语言模型（VLM）：

# 必需：设置 API Key
export ANTHROPIC_API_KEY=your_key_here
# 或
export QWEN_API_KEY=your_key_here

推荐配置：

LLM：Claude Sonnet 4（最佳性能）
浏览器：Chromium（通过 Playwright）

2. 核心 API 详解

2.1 BrowserAgent API

import { startBrowserAgent } from 'magnitude-core';
import { z } from 'zod';

// 启动 Agent
const agent = await startBrowserAgent({
  // 起始 URL
  url: 'https://example.com',
  
  // 显示 AI 思考和操作过程
  narrate: true,
  
  // LLM 配置
  llm: {
    provider: 'anthropic',
    options: {
      model: 'claude-sonnet-4-20250514',
      apiKey: process.env.ANTHROPIC_API_KEY
    }
  },
  
  // 自定义系统提示词
  prompt: 'Prefer mouse to keyboard when filling out form fields'
});

// 导航
await agent.nav('https://target-site.com');

// 执行操作
await agent.act('点击登录按钮');

// 提取数据
const data = await agent.extract(
  '提取所有商品信息',
  z.array(z.object({
    name: z.string(),
    price: z.number(),
    rating: z.number()
  }))
);

// 停止 Agent
await agent.stop();

2.2 TestCaseAgent API

import { test } from 'magnitude-test';

// 定义测试用例
test('用户应该能成功创建订单', async (agent) => {
  // 执行操作
  await agent.act('导航到产品页面');
  await agent.act('添加商品到购物车');
  await agent.act('进入结算页面');
  await agent.act('填写收货信息');
  await agent.act('提交订单');
  
  // 视觉断言验证
  await agent.check('页面显示"订单创建成功"');
  await agent.check('订单总价正确显示');
});

3. 实战应用场景

3.1 场景一：Web 应用端到端测试

背景：电商网站的核心购买流程测试

传统方式的问题：

频繁的 UI 改版导致选择器失效
动态加载的内容难以处理
维护成本极高

Magnitude 方案：

// tests/e2e/purchase-flow.mag.ts
import { test } from 'magnitude-test';
import { z } from 'zod';

test('完整购买流程', async (agent) => {
  // 使用自然语言描述复杂流程
  await agent.act('浏览到电子产品分类');
  await agent.act('选择价格在 500-1000 元之间的商品');
  await agent.act('查看商品详情');
  await agent.act('加入购物车');
  await agent.act('继续购物，添加另一件商品');
  await agent.act('进入购物车页面');
  await agent.act('确认购物车中有两件商品');
  await agent.act('进入结算流程');
  await agent.act('填写收货地址：北京市朝阳区...');
  await agent.act('选择支付方式：支付宝');
  await agent.act('提交订单');
  
  // 验证订单创建成功
  await agent.check('显示订单确认页面');
  await agent.check('显示订单号');
  
  // 提取订单信息用于后续验证
  const orderInfo = await agent.extract(
    '提取订单信息',
    z.object({
      orderId: z.string(),
      total: z.number(),
      items: z.array(z.object({
        name: z.string(),
        price: z.number()
      }))
    })
  );
  
  console.log('订单创建成功:', orderInfo);
});

优势：

无需维护脆弱的 DOM 选择器
UI 改版后测试依然有效
非技术人员也能理解测试内容

3.2 场景二：跨应用数据集成

背景：从 Salesforce 同步客户数据到 Notion

挑战：

Salesforce API 权限复杂
Notion API 有速率限制
需要处理复杂的权限和认证

Magnitude 方案：

// integrations/salesforce-to-notion.ts
import { startBrowserAgent } from 'magnitude-core';
import { z } from 'zod';

async function syncCustomers() {
  const agent = await startBrowserAgent({
    llm: { /* 配置 */ }
  });
  
  try {
    // 步骤1：从 Salesforce 导出客户数据
    await agent.nav('https://login.salesforce.com');
    await agent.act('使用公司账户登录');
    await agent.act('导航到客户列表页面');
    await agent.act('筛选出最近更新的客户');
    
    // 智能提取客户数据
    const customers = await agent.extract(
      '提取所有客户的姓名、邮箱、公司和最近活动',
      z.array(z.object({
        name: z.string(),
        email: z.string().email(),
        company: z.string(),
        lastActivity: z.string()
      }))
    );
    
    console.log(`提取了 ${customers.length} 个客户`);
    
    // 步骤2：导入到 Notion
    await agent.nav('https://notion.so');
    await agent.act('登录到 Notion');
    await agent.act('打开客户管理数据库');
    
    // 批量导入客户
    for (const customer of customers) {
      await agent.act(`添加新客户: ${customer.name}`);
      await agent.act(`填写邮箱: ${customer.email}`);
      await agent.act(`填写公司: ${customer.company}`);
      await agent.act('保存客户信息');
    }
    
    console.log('数据同步完成！');
    
  } finally {
    await agent.stop();
  }
}

// 定时运行
setInterval(syncCustomers, 24 * 60 * 60 * 1000); // 每天一次

优势：

无需处理复杂的 API 集成
绕过 API 限制
可视化操作，可人工介入处理异常

3.3 场景三：复杂数据抓取

背景：从使用 Canvas 绘制的数据可视化图表中提取数据

挑战：

数据以图像形式呈现
无法通过 DOM 获取
需要 OCR 或图像识别

Magnitude 方案：

// scrapers/chart-data-extraction.ts
import { startBrowserAgent } from 'magnitude-core';
import { z } from 'zod';

async function extractChartData() {
  const agent = await startBrowserAgent({
    llm: { /* 配置 */ },
    prompt: '仔细分析图表中的数据点，提取精确的数值'
  });
  
  await agent.nav('https://data-visualization-site.com/dashboard');
  
  // 处理交互式图表
  await agent.act('点击切换到"年度数据"视图');
  await agent.act('选择时间范围：2024年1月到12月');
  await agent.act('等待图表加载完成');
  
  // 提取图表数据
  const chartData = await agent.extract(
    '提取图表中的所有数据点，包括月份和销售额',
    z.object({
      chartTitle: z.string(),
      dataPoints: z.array(z.object({
        month: z.string(),
        sales: z.number(),
        growth: z.number().describe('增长率百分比')
      })),
      maxValue: z.number(),
      minValue: z.number()
    })
  );
  
  console.log('图表数据:', chartData);
  
  // 处理多个图表
  await agent.act('切换到"区域分布"标签');
  const regionData = await agent.extract(
    '提取各区域的销售数据',
    z.array(z.object({
      region: z.string(),
      revenue: z.number(),
      percentage: z.number()
    }))
  );
  
  await agent.stop();
  return { chartData, regionData };
}

优势：

处理传统工具无法处理的 Canvas/WebGL 内容
智能理解图表类型和数据结构
可处理动态加载和交互式图表

3.4 场景四：自动化工作流程

背景：每日自动生成并发送数据报告

Magnitude 方案：

// workflows/daily-report.ts
import { startBrowserAgent } from 'magnitude-core';
import nodemailer from 'nodemailer';

async function generateDailyReport() {
  const agent = await startBrowserAgent({
    llm: { /* 配置 */ }
  });
  
  try {
    // 登录数据分析平台
    await agent.nav('https://analytics.company.com');
    await agent.act('登录系统');
    
    // 生成报告
    await agent.act('进入报告中心');
    await agent.act('选择"每日销售报告"模板');
    await agent.act('设置日期范围为昨天');
    await agent.act('生成报告');
    await agent.act('等待报告生成完成');
    
    // 下载报告
    await agent.act('下载 PDF 格式报告');
    
    // 获取关键指标
    const metrics = await agent.extract(
      '提取报告中的关键指标',
      z.object({
        totalSales: z.number(),
        orderCount: z.number(),
        conversionRate: z.number(),
        topProducts: z.array(z.string())
      })
    );
    
    // 发送邮件（结合传统代码）
    const transporter = nodemailer.createTransport({ /* 配置 */ });
    await transporter.sendMail({
      to: 'manager@company.com',
      subject: `每日销售报告 - ${new Date().toISOString().split('T')[0]}`,
      html: `
        <h2>每日销售报告</h2>
        <p>总销售额: ¥${metrics.totalSales}</p>
        <p>订单数: ${metrics.orderCount}</p>
        <p>转化率: ${metrics.conversionRate}%</p>
        <p>热销产品: ${metrics.topProducts.join(', ')}</p>
      `,
      attachments: [{ path: './downloads/daily-report.pdf' }]
    });
    
    console.log('报告已发送！');
    
  } finally {
    await agent.stop();
  }
}

// 定时任务：每天早上9点执行
const schedule = require('node-schedule');
schedule.scheduleJob('0 9 * * *', generateDailyReport);

4. CI/CD 集成方案

4.1 GitHub Actions 配置

# .github/workflows/magnitude-tests.yml
name: Magnitude Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'
          
      - name: Install dependencies
        run: npm ci
        
      - name: Run Magnitude tests
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: npx magnitude run
        
      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: test-results
          path: ./test-results/

4.2 TestingBot 云端执行

// 使用 TestingBot 的云端浏览器执行测试
import { startBrowserAgent } from 'magnitude-core';

const agent = await startBrowserAgent({
  url: 'https://docs.magnitude.run',
  browser: {
    cdp: `wss://cloud.testingbot.com/puppeteer?capabilities=${encodeURIComponent(
      JSON.stringify({
        'tb:options': {
          key: process.env.TESTINGBOT_KEY,
          secret: process.env.TESTINGBOT_SECRET
        },
        browserName: 'chrome',
        browserVersion: 'latest'
      })
    )}`
  }
});

5. 性能优化技巧

5.1 减少 LLM 调用次数

// 优化前：多次调用
await agent.act('点击搜索框');
await agent.act('输入"iPhone 15"');
await agent.act('点击搜索按钮');

// 优化后：单次调用
await agent.act('搜索 "iPhone 15"');

5.2 使用提示词缓存

const agent = await startBrowserAgent({
  llm: {
    provider: 'anthropic',
    options: {
      model: 'claude-sonnet-4-20250514',
      cachePrompts: true  // 启用缓存
    }
  }
});

5.3 并行执行

// 同时处理多个任务
const tasks = urls.map(url => 
  extractDataFromUrl(url)
);

const results = await Promise.all(tasks);

6. 常见模式与最佳实践

6.1 错误处理模式

async function robustAction(agent, description, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      await agent.act(description);
      return;
    } catch (error) {
      console.warn(`尝试 ${i + 1} 失败:`, error);
      if (i === maxRetries - 1) throw error;
      await sleep(1000 * (i + 1)); // 指数退避
    }
  }
}

6.2 状态检查点模式

async function workflowWithCheckpoints(agent) {
  // 步骤1 + 验证
  await agent.act('登录系统');
  await agent.check('显示用户仪表板');
  
  // 步骤2 + 验证
  await agent.act('打开设置页面');
  await agent.check('显示设置表单');
  
  // 步骤3 + 验证
  await agent.act('修改个人资料');
  await agent.check('显示保存成功提示');
}

1. 快速开始

1.1 环境准备

1.2 配置要求

2. 核心 API 详解

2.1 BrowserAgent API

2.2 TestCaseAgent API

3. 实战应用场景

3.1 场景一：Web 应用端到端测试

3.2 场景二：跨应用数据集成

3.3 场景三：复杂数据抓取

3.4 场景四：自动化工作流程

4. CI/CD 集成方案

4.1 GitHub Actions 配置

4.2 TestingBot 云端执行

5. 性能优化技巧

5.1 减少 LLM 调用次数

5.2 使用提示词缓存

5.3 并行执行

6. 常见模式与最佳实践

6.1 错误处理模式

6.2 状态检查点模式

参考资料