validpilot-oss 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,111 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.1.0] - 2026-06-28
+
+### Added
+
+#### New Tools (12)
+
+- **browser_find_element** - 智能元素定位基础版
+  - 7种匹配策略：精确文本、模糊文本、placeholder、aria-label、title/alt、role
+  - 置信度评分（1.0→0.6）
+  - 自动生成稳定CSS选择器
+  - 可见性过滤
+
+- **browser_diagnose** - 错误自动诊断
+  - 自动分析错误根因和置信度
+  - 支持 TypeError/500/404/CORS 等模式识别
+  - 返回 suggestedFixes 修复建议
+
+- **browser_element_status** - 元素状态诊断
+  - 可见性检查（isFullyVisible）
+  - 可交互性检查（isDisabled/isHidden）
+  - 遮挡检查（obscuredBy）
+  - 事件绑定检查
+
+- **browser_quick_fix** - 快速修复
+  - 8种修复策略：wait/scroll/force_visible/remove_obscuring/remove_disabled/force_click/inject_click_listener/trigger_event
+  - 自动尝试直到成功
+
+- **browser_verify_fix** - 修复验证闭环
+  - 记录 before/after 状态
+  - 验证修复效果
+  - 返回 FIXED/NOT_FIXED 状态
+
+- **browser_cookies** - Cookie管理
+  - 获取/设置/清除 Cookie
+  - 支持域名筛选
+  - 敏感值自动脱敏
+
+- **browser_traverse_menu** - 菜单遍历
+  - 自动遍历多级菜单发现功能
+  - 支持 maxDepth/maxItems 控制
+  - 每步错误检测
+
+- **validation_element** - 元素状态验证
+  - 8种断言：exists/visible/enabled/textContains/hasAttribute/valueEquals/countEquals
+  - 失败自动截图
+  - 与 validation_check 格式一致
+
+- **validation_flow** - 流程验证
+  - 7种步骤类型：click/type/wait/assert/goto/scroll
+  - 支持 continueOnFailure
+  - 返回每步结果和总通过率
+
+- **validation_quick_run** - 一键快速验证
+  - 7项自动检查：load_time/no_js_errors/no_5xx/no_404/not_blank/has_title/has_content
+  - 自动截图证据
+  - 快速返回 pass/fail
+
+- **error_fix_suggestion** - 错误修复建议
+  - 11种错误模式：404/401/403/500/TypeError/CORS/超时/元素未找到/不可见/disabled/网络失败
+  - 每条建议含 severity/confidence/verifyAction/relatedTool
+  - 与 browser_diagnose 形成闭环
+
+### Enhanced
+
+#### Enhanced Tools
+
+- **analyzeScreenshotForErrors** - 截图错误分析
+  - 30+ UI框架选择器（Ant Design/Element UI/Vuetify/PrimeNG等）
+  - RGB/HSL/颜色名红色检测
+  - toastLike 检测
+  - domErrorStats DOM统计
+
+- **postActionErrorCheck** - 操作后错误检查
+  - checkpoint时间戳过滤
+  - 300ms延迟等待
+
+- **browser_assert** - 断言验证
+  - autoScreenshot 参数
+  - 失败自动截图 + 错误分析
+
+- **buildDebugReport** - 调试报告
+  - 新增 domStats（11字段）
+  - totalElements/inputs/buttons/links/images/forms/tables/iframes/navs
+
+- **browser_snapshot** - 页面快照
+  - 新增 pageInfo/navElements/imageCount/tableCount/frameworks
+
+- **browser_click/type/press_key** - 交互工具
+  - 新增 suggestions 调试建议
+  - 按错误类型提供具体提示
+
+### Documentation
+
+- **README.md** - 全面更新
+  - 能力清单扩展为8分类
+  - 新增72工具总数说明
+  - 新增智能诊断与修复建议核心卖点
+  - 新增进阶使用示例
+
+## [1.0.0] - 2026-06-27
+
+### Added
+
+- Initial release
+- 73 MCP tools covering browser automation, validation, and debugging
+- MCP protocol native support (HTTP mode)
+- Playwright-based browser automation

package/README.md

@@ -0,0 +1,196 @@
+# ValidPilot Open Source 🚀
+
+> 浏览器自动化与验证框架，MCP 协议原生支持
+
+---
+
+## ✨ 核心卖点
+
+### 🤖 MCP 协议原生支持
+AI Agent 直接调用，无需写代码，让你的智能体瞬间拥有浏览器操作能力
+
+### 💬 自然语言操作浏览器
+描述你想做什么，AI 帮你操作。点击、输入、滚动、截图... 一句话搞定
+
+### 🎯 智能元素定位
+用自然语言描述元素，自动查找。支持文本匹配、占位符、ARIA 标签、角色等多策略 fallback，不用再写复杂的 CSS 选择器
+
+### 🔍 智能诊断与修复建议
+自动诊断错误根因，给出具体修复建议。从发现问题到解决问题，形成完整闭环
+
+### ✅ 基础验证框架
+元素验证、流程验证、快速验证、视觉对比，开箱即用
+
+### 📊 自动错误收集
+Console 错误、网络错误、页面异常... 自动聚合，一目了然
+
+---
+
+## 📋 能力清单
+
+| 分类 | 能力 | 工具 | 说明 |
+|------|------|------|------|
+| 🌐 **浏览器操作** | 页面导航 | browser_open / browser_navigate | 打开 URL、前进、后退、刷新 |
+| | 元素交互 | browser_click / browser_type / browser_hover / browser_select_option | 点击、输入、悬停、选择 |
+| | 键盘操作 | browser_press_key | 按键、组合键、文本输入 |
+| | 页面滚动 | browser_scroll | 滚动到指定位置、元素、底部/顶部 |
+| | 截图功能 | browser_screenshot / browser_screenshot_element | 全屏截图、元素截图、可视区域截图 |
+| | Cookie 管理 | browser_cookies | 获取、设置、清除 Cookie |
+| | 存储操作 | browser_storage | localStorage、sessionStorage 读写 |
+| | 网络控制 | browser_network | 网络请求诊断、失败分析 |
+| | JavaScript 执行 | browser_eval | 注入并执行自定义 JS 代码 |
+| | 等待机制 | browser_wait | 等待元素、等待导航、等待网络空闲 |
+| | 内容提取 | browser_dom / browser_snapshot | 获取 DOM、页面快照、元素属性 |
+| | 批量操作 | browser_batch | 批量执行操作序列 |
+| | 表单操作 | browser_type / browser_select_option | 填充表单、选择选项 |
+| | 窗口管理 | browser_sessions / browser_session_create | 多标签页、会话管理 |
+| | 事件监听 | browser_events | 捕获页面事件 |
+| 🎯 **智能定位** | 按文本查找元素 | **browser_find_element** | 用描述找到页面元素（新增） |
+| | 选择器建议 | browser_locator_suggest | 生成更稳定的选择器 |
+| | 选择器验证 | browser_locator_validate | 验证选择器稳定性和匹配数 |
+| | 多策略 fallback | — | 文本、占位符、ARIA、role 智能匹配 |
+| 🔍 **调试诊断** | 错误自动诊断 | **browser_diagnose** | 自动分析错误根因和置信度 |
+| | 元素状态诊断 | **browser_element_status** | 可见性、可交互性、遮挡、事件检查 |
+| | 快速修复 | **browser_quick_fix** | 8种策略自动尝试修复 |
+| | 修复验证闭环 | **browser_verify_fix** | 记录前后状态，验证修复效果 |
+| | 控制台日志 | browser_console | 获取浏览器控制台日志 |
+| | 错误聚合 | browser_errors_aggregate | 按类型/严重度聚合错误 |
+| | 调试报告 | browser_debug_report | 生成完整调试报告 |
+| ✅ **基础验证** | 元素验证 | **validation_element** | 元素存在/可见/启用/文本等断言（增强） |
+| | 流程验证 | **validation_flow** | 多步骤流程验证（增强） |
+| | 快速验证 | **validation_quick_run** | 一键URL健康检查（增强） |
+| | 检查点验证 | validation_check | 灵活的自定义验证 |
+| | 验证运行 | validation_run | 执行验证计划 |
+| | 断言验证 | browser_assert | 页面级断言 |
+| | 视觉回归 | screenshot_diff | 截图对比，发现 UI 变化 |
+| | 元素验证工具 | validation_element | 元素状态验证 |
+| 🔍 **错误收集** | Console 错误 | browser_errors | 自动捕获 JS 错误和警告 |
+| | 网络错误 | browser_network | 失败请求自动记录 |
+| | 页面错误 | — | 资源加载、运行时异常聚合 |
+| | 错误分类 | error_aggregate | 按类型、严重程度自动归类 |
+| | 修复建议 | **error_fix_suggestion** | 基于规则的修复建议（增强） |
+| 📝 **验证报告** | 基础报告 | validation_report | HTML/JSON/Markdown 格式报告 |
+| | 报告导出 | validation_report_export | 导出验证报告 |
+| | 步骤记录 | — | 操作步骤自动留存 |
+| | 截图证据 | browser_screenshot | 关键节点自动截图 |
+| | 工件管理 | browser_artifacts | 截图、日志等工件管理 |
+| 🧪 **快速修复能力** | 截图错误分析 | — | 截图后自动分析页面错误 |
+| | 断言证据链 | — | 断言失败自动截图+错误分析 |
+| | 交互错误提示 | — | 点击/输入失败给出调试建议 |
+| | 菜单遍历 | browser_traverse_menu | 自动遍历多级菜单发现功能 |
+| | 页面发现 | browser_find_page | 自动识别登录页/首页等页面类型 |
+
+---
+
+## � 工具总数
+
+**72 个工具** — 覆盖浏览器操作、智能定位、调试诊断、验证框架、错误分析、报告导出全流程
+
+---
+
+## �🚀 快速开始
+
+### 第 1 步：安装
+
+```bash
+npm install -g validpilot
+```
+
+### 第 2 步：配置 MCP Server
+
+在你的 MCP 配置文件中添加：
+
+```json
+{
+  "mcpServers": {
+    "validpilot": {
+      "command": "npx",
+      "args": ["-y", "validpilot", "mcp"]
+    }
+  }
+}
+```
+
+### 第 3 步：第一个操作
+
+重启你的 AI 客户端，然后试试说：
+
+> "打开百度，搜索 'MCP 协议'，然后截图"
+
+就这么简单！🎉
+
+### 💡 进阶：智能定位试试这个
+
+> "找到页面上的登录按钮并点击"
+
+无需写选择器，ValidPilot 会自动帮你找到元素。
+
+### 💡 进阶：快速验证试试这个
+
+> "用 validation_quick_run 检查 https://example.com 是否正常"
+
+一键检查页面加载、JS错误、白屏等问题。
+
+---
+
+## 💎 开源版 vs 付费版
+
+| 功能 | 开源版 | 付费版 |
+|------|--------|--------|
+| 🌐 浏览器操作（20+工具） | ✅ | ✅ |
+| 🎯 智能元素定位（基础版） | ✅ 文本/属性匹配 | ✅ 多模态视觉定位 |
+| 🔍 错误诊断与修复建议 | ✅ 基于规则 | ✅ AI 智能分析 |
+| ✅ 基础验证框架 | ✅ | ✅ |
+| 🔍 错误自动收集 | ✅ | ✅ |
+| 📝 基础验证报告 | ✅ | ✅ |
+| 🤖 AI 自动探索验证 | ❌ | ✅ |
+| 🔬 AI 深度根因分析 | ❌ | ✅ |
+| 💡 AI 智能修复建议 | ❌ | ✅ |
+| 📦 批量验证执行 | ❌ | ✅ |
+| 🔒 安全扫描 | ❌ | ✅ |
+| 👥 团队协作 | ❌ | ✅ |
+| 📈 高级分析仪表盘 | ❌ | ✅ |
+| 🎧 优先技术支持 | ❌ | ✅ |
+
+> 💡 想体验更强大的 AI 能力？了解 [ValidPilot Pro](https://validpilot.com/pro)
+
+---
+
+## 🌟 社区与贡献
+
+我们欢迎各种形式的贡献！
+
+- 🐛 [提交 Bug](https://github.com/validpilot/validpilot/issues)
+- 💡 [功能建议](https://github.com/validpilot/validpilot/discussions)
+- 📖 [改进文档](https://github.com/validpilot/validpilot/pulls)
+- 🔧 [提交代码](https://github.com/validpilot/validpilot/blob/main/CONTRIBUTING.md)
+
+### 开发环境
+
+```bash
+# 克隆项目
+git clone https://github.com/validpilot/validpilot.git
+
+# 安装依赖
+cd validpilot
+npm install
+
+# 启动开发模式
+npm run dev
+```
+
+---
+
+## 📄 License
+
+[MIT](LICENSE) © ValidPilot Team
+
+---
+
+<div align="center">
+
+如果这个项目对你有帮助，别忘了给个 ⭐ Star！
+
+[官网](https://validpilot.com) · [文档](https://docs.validpilot.com) · [社区](https://github.com/validpilot/validpilot/discussions)
+
+</div>

package/bin/validpilot.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { validationQuickRun } = require('../hands/verification_runner');
+const browserOperator = require('../hands/browser_operator');
+
+const PKG = require('../package.json');
+
+function printHelp() {
+  const cmd = 'validpilot';
+  const version = PKG.version || '0.1.0';
+  console.log(`${cmd} ${version} — AI 编程的最后一公里验证平台
+
+Usage:
+  ${cmd} health                       检查 Playwright 可用性 (exit 0=ok / exit 1=unavailable)
+  ${cmd} run     --flow <file>        执行轻量 flow JSON，逐 action 输出结果
+  ${cmd} validate --url <url>         快速验证 URL，输出 pass/fail / Top errors / artifact 路径
+  ${cmd} --version                    输出版本号
+  ${cmd} --help                       显示此帮助
+
+AI 配置选项:
+  --ai-provider <provider>           设置 AI 提供商 (openai/deepseek/qwen)
+  --ai-api-key <key>                 设置 AI API Key
+
+Examples:
+  ${cmd} health
+  ${cmd} validate --url examples/demo/index.html
+  ${cmd} run     --flow examples/demo/flow.json
+  ${cmd} validate --url examples/demo/index.html --ai-provider openai --ai-api-key sk-xxx
+`);
+}
+
+function parseArgs(argv) {
+  const result = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const item = argv[i];
+    if (item.startsWith('--')) {
+      const key = item.slice(2);
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith('--')) {
+        result[key] = next;
+        i += 1;
+      } else {
+        result[key] = true;
+      }
+    } else if (item.startsWith('-') && item.length === 2 && item !== '--') {
+      const key = item.slice(1);
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith('-')) {
+        result[key] = next;
+        i += 1;
+      } else {
+        result[key] = true;
+      }
+    } else {
+      result._.push(item);
+    }
+  }
+  return result;
+}
+
+function printLowToken(result) {
+  console.log(JSON.stringify({
+    pass: result.pass,
+    mode: result.mode,
+    summary: result.summary,
+    topErrors: (result.topErrors || []).slice(0, 5),
+    artifacts: result.artifacts || []
+  }, null, 2));
+}
+
+async function cmdHealth() {
+  let chromium;
+  try {
+    chromium = require('playwright').chromium;
+  } catch (error) {
+    console.log(JSON.stringify({ ok: false, name: PKG.name || 'validpilot', version: PKG.version || '0.1.0', error: `Playwright module unavailable: ${error.message}` }, null, 2));
+    process.exit(1);
+  }
+
+  let browser;
+  try {
+    browser = await chromium.launch({ headless: true, timeout: 15000 });
+    await browser.close();
+    console.log(JSON.stringify({ ok: true, name: PKG.name || 'validpilot', version: PKG.version || '0.1.0', message: 'Playwright browser is available' }, null, 2));
+    process.exit(0);
+  } catch (error) {
+    console.log(JSON.stringify({ ok: false, name: PKG.name || 'validpilot', version: PKG.version || '0.1.0', error: `Playwright browser failed to launch: ${error.message}` }, null, 2));
+    process.exit(1);
+  }
+}
+
+async function cmdRun(flowPath) {
+  if (!flowPath) throw new Error('run requires --flow <file>');
+
+  const resolved = path.resolve(flowPath);
+  const raw = JSON.parse(fs.readFileSync(resolved, 'utf8'));
+
+  // Support both array-format and {steps, goal, stopOnError} format
+  let steps, goal, stopOnError;
+  if (Array.isArray(raw)) {
+    // Array format: [{action: "open", args: {url: "..."}}, ...]
+    steps = raw.map(item => {
+      const step = { action: item.action };
+      if (item.args && typeof item.args === 'object') {
+        Object.assign(step, item.args);
+      }
+      return step;
+    });
+    goal = 'CLI low-token flow';
+    stopOnError = true;
+  } else {
+    steps = Array.isArray(raw.steps) ? raw.steps : [];
+    goal = raw.goal || 'CLI low-token flow';
+    stopOnError = raw.stopOnError !== false;
+  }
+
+  const result = await browserOperator.batch({ goal, steps, stopOnError });
+  console.log(JSON.stringify({
+    pass: result.ok,
+    summary: `flow steps=${steps.length}`,
+    results: result.results,
+    topErrors: [],
+    artifacts: (result.results || []).map(item => item.artifactPath).filter(Boolean)
+  }, null, 2));
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const command = args._[0];
+
+  if (args['ai-provider']) {
+    process.env.AI_PROVIDER = args['ai-provider'];
+  }
+  if (args['ai-api-key']) {
+    process.env.AI_API_KEY = args['ai-api-key'];
+  }
+
+  if (args.version || command === '--version' || command === '-v') {
+    console.log(PKG.version || '0.1.0');
+    return;
+  }
+  if (args.help || command === '--help' || command === '-h' || !command) {
+    printHelp();
+    return;
+  }
+
+  if (command === 'health') {
+    await cmdHealth();
+    return;
+  }
+
+  if (command === 'validate') {
+    if (!args.url) throw new Error('validate requires --url <url>');
+    const result = await validationQuickRun({ url: args.url, headless: true });
+    printLowToken(result);
+    return;
+  }
+
+  if (command === 'run') {
+    await cmdRun(args.flow);
+    return;
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}
+
+main().catch(error => {
+  console.error(JSON.stringify({ pass: false, error: error.message }, null, 2));
+  process.exitCode = 1;
+});

package/brain/error_aggregator.js

@@ -0,0 +1,203 @@
+'use strict';
+
+const { truncate } = require('../engines/playwright_adapter');
+
+function collectRawErrors(input = {}) {
+  const sources = [];
+  const push = (source, records = []) => {
+    if (!Array.isArray(records)) return;
+    for (const item of records) sources.push({ source, ...item });
+  };
+
+  push('console', input.console?.recent || input.consoleErrors || input.consoleLogs || input.console || []);
+  push('network', input.network?.recent || input.networkErrors || input.networkLogs || input.network || []);
+  push('pageerror', input.pageerror?.recent || input.pageErrors || input.pageerror || []);
+  push('mcp', input.mcpErrors || []);
+
+  if (input.evidence) sources.push(...collectRawErrors(input.evidence));
+  if (input.errors) sources.push(...collectRawErrors(input.errors));
+  return sources;
+}
+
+function severityOf(item = {}) {
+  // CRITICAL: Page-level runtime errors (blocks everything)
+  if (item.source === 'pageerror') return 4;
+  if (item.failed || Number(item.status || 0) >= 500) return 3;
+  
+  // HIGH: 404 on critical resources (JS/CSS that app needs)
+  if (Number(item.status || 0) >= 400 && 
+      (item.url || '').match(/\.(js|css|jsx|tsx|wasm)($|\?)/i)) {
+    return 2;
+  }
+  
+  // MEDIUM: Other 404s (images, fonts, optional resources)
+  if (Number(item.status || 0) >= 400) return 1;
+  
+  if (['error', 'assert'].includes(String(item.type || '').toLowerCase())) return 2;
+  if (['warning', 'warn'].includes(String(item.type || '').toLowerCase())) return 1;
+  return 0;
+}
+
+function pageFunctionalStatus(input = {}) {
+  const raw = collectRawErrors(input);
+  
+  // Check if page-level errors exist
+  const pageErrors = raw.filter(item => item.source === 'pageerror');
+  const criticalJsErrors = raw.filter(item => 
+    item.source === 'console' && 
+    (item.url || '').match(/\.js($|\?)/i) &&
+    item.text && item.text.includes('Failed to load resource')
+  );
+  const criticalCssErrors = raw.filter(item => 
+    item.source === 'console' && 
+    (item.url || '').match(/\.css($|\?)/i) &&
+    item.text && item.text.includes('Failed to load resource')
+  );
+  
+  // Calculate page health score (0-100)
+  let healthScore = 100;
+  const criticalErrorCount = pageErrors.length + criticalJsErrors.length + criticalCssErrors.length;
+  
+  // Deduct points for critical errors
+  healthScore -= pageErrors.length * 30; // Each page error costs 30 points
+  healthScore -= criticalJsErrors.length * 3; // Each JS 404 costs 3 points
+  healthScore -= criticalCssErrors.length * 2; // Each CSS 404 costs 2 points
+  healthScore = Math.max(0, Math.min(100, healthScore));
+  
+  if (pageErrors.length > 0) {
+    return {
+      status: 'blocked',
+      message: `检测到 ${pageErrors.length} 个页面运行时错误，页面功能被阻塞，不能执行真实业务验证。`,
+      canTestBusiness: false,
+      recommendation: '优先修复页面运行时错误，然后重新验证业务闭环。',
+      healthScore,
+      criticalErrorCount,
+      details: {
+        pageErrorCount: pageErrors.length,
+        criticalJsErrors: criticalJsErrors.length,
+        criticalCssErrors: criticalCssErrors.length
+      }
+    };
+  }
+  
+  if (criticalJsErrors.length > 10 || criticalCssErrors.length > 10) {
+    return {
+      status: 'degraded',
+      message: `检测到 ${criticalJsErrors.length} 个关键 JS 资源和 ${criticalCssErrors.length} 个 CSS 资源 404 错误，页面功能降级，业务验证结果可能不可靠。`,
+      canTestBusiness: false,
+      recommendation: '修复关键资源加载问题后重新验证。',
+      healthScore,
+      criticalErrorCount,
+      details: {
+        pageErrorCount: pageErrors.length,
+        criticalJsErrors: criticalJsErrors.length,
+        criticalCssErrors: criticalCssErrors.length
+      }
+    };
+  }
+  
+  // Check for noisy 404s (images, fonts, etc.)
+  const noisy404s = raw.filter(item => 
+    item.source === 'console' &&
+    (item.url || '').match(/\.(png|jpg|jpeg|gif|svg|ico|woff|woff2|ttf|eot)($|\?)/i) &&
+    item.text && item.text.includes('Failed to load resource')
+  );
+  
+  if (noisy404s.length > 20) {
+    return {
+      status: 'noisy',
+      message: `检测到 ${noisy404s.length} 个图片/字体资源 404 错误，页面可运行但用户体验可能受影响。`,
+      canTestBusiness: true,
+      recommendation: '建议修复资源 404 以提升用户体验，但不影响核心业务验证。',
+      healthScore,
+      criticalErrorCount,
+      details: {
+        pageErrorCount: pageErrors.length,
+        criticalJsErrors: criticalJsErrors.length,
+        criticalCssErrors: criticalCssErrors.length,
+        noisy404s: noisy404s.length
+      }
+    };
+  }
+  
+  return {
+    status: 'functional',
+    message: `页面功能正常 (健康度 ${healthScore}/100)，可执行真实业务验证。`,
+    canTestBusiness: true,
+    recommendation: healthScore >= 90 ? '继续业务动作验证。' : '建议修复部分资源 404 后验证以提升结果可信度。',
+    healthScore,
+    criticalErrorCount,
+    details: {
+      pageErrorCount: pageErrors.length,
+      criticalJsErrors: criticalJsErrors.length,
+      criticalCssErrors: criticalCssErrors.length,
+      noisy404s: noisy404s.length
+    }
+  };
+}
+
+function signatureOf(item = {}) {
+  const status = item.status ? ` ${item.status}` : '';
+  const url = item.url ? ` ${String(item.url).replace(/[?#].*$/, '')}` : '';
+  const text = item.text || item.message || item.errorText || item.stack || '';
+  return `${item.source || 'unknown'}${status}${url} ${String(text).replace(/\d{3,}/g, '#').slice(0, 180)}`.trim();
+}
+
+function aggregateErrors(input = {}, options = {}) {
+  const raw = collectRawErrors(input).filter(item => severityOf(item) > 0 || item.failed || item.status >= 400);
+  const grouped = new Map();
+  for (const item of raw) {
+    const sig = signatureOf(item);
+    const existing = grouped.get(sig) || { signature: sig, count: 0, severity: 0, examples: [] };
+    existing.count += 1;
+    existing.severity = Math.max(existing.severity, severityOf(item));
+    if (existing.examples.length < 2) existing.examples.push({
+      source: item.source,
+      type: item.type,
+      status: item.status,
+      method: item.method,
+      url: item.url,
+      text: truncate(item.text || item.message || item.errorText || item.stack || '', 260),
+      timestamp: item.timestamp
+    });
+    grouped.set(sig, existing);
+  }
+
+  const topErrors = Array.from(grouped.values())
+    .sort((a, b) => (b.severity - a.severity) || (b.count - a.count))
+    .slice(0, options.limit || 5);
+
+  const totalCount = raw.length;
+  const uniqueCount = grouped.size;
+  const summary = buildSummary(topErrors, uniqueCount, totalCount);
+
+  return { topErrors, summary, uniqueCount, totalCount };
+}
+
+function buildSummary(topErrors, uniqueCount, totalCount) {
+  const lines = [
+    '## Error Summary',
+    `- Status: ${topErrors.length ? 'fail' : 'pass'}`,
+    `- Errors: total=${totalCount}, unique=${uniqueCount}`,
+    '- Top errors:'
+  ];
+  if (!topErrors.length) lines.push('  - none');
+  for (const error of topErrors.slice(0, 5)) {
+    const example = error.examples?.[0] || {};
+    lines.push(`  - [${error.count}x/S${error.severity}] ${truncate(error.signature, 160)}`);
+    if (example.url) lines.push(`    - url: ${truncate(example.url, 120)}`);
+  }
+  const md = lines.join('\n');
+  return md.length > 500 ? `${md.slice(0, 497)}...` : md;
+}
+
+function errorSummaryMd(input = {}, options = {}) {
+  const aggregated = input.topErrors ? input : aggregateErrors(input, options);
+  return aggregated.summary || buildSummary(aggregated.topErrors || [], aggregated.uniqueCount || 0, aggregated.totalCount || 0);
+}
+
+module.exports = {
+  aggregateErrors,
+  errorSummaryMd,
+  collectRawErrors
+};