WebTrace

# WebTrace [![npm][badge-version]][npm] [![license][badge-license]][license] [![npm downloads][badge-downloads]][npm] [![github stars][badge-stars]][repo] > 真实的浏览器指标 → 因果关系图 → 可行性报告。为 AI 代理而建，对人类也很有用。 WebTrace 启动了一个无头 Chromium 浏览器，通过 Chrome DevTools 协议捕获性能数据，经过 5 阶段的分析管道，输出一个结构化的 JSON 报告，问题按严重程度、因果链和优先修复排序。 ```bash npx @gmod.one/webtrace run --url https://example.com --pretty ``` ## 为什么 Lighthouse 给你一个分数。WebTrace 告诉你 _为什么_ 情况不好以及首先要修复什么。 与其深入研究 10,000 行的 trace.json 或一堆 Lighthouse 审计，不如得到一个专注的报告，根源与影响相连。输出设计为 AI 代理（或你）无需解码环即可阅读。 ## 管道  ``` collect → normalize → extract → analyze → report ``` | 步骤 | 它做了什么 | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **收集** | 启动无头 Chromium，捕获网络、跟踪、性能 API、JS 覆盖率、控制台日志、DOM 快照和 Lighthouse 审计 | | **标准化** | 通过 Zod 模式验证原始数据为统一的中间表示（IRBundle）。所有时间戳标准化，数据清理 | | **提取** | 从 IR 中计算 7 个诊断特征集：LCP 分解、关键网络链、主线程阻塞时间、JS 热点、布局偏移、第三方开销、渲染阻塞分数 | | **分析** | 对特征运行 30 多个因果规则，构建有向图，其中边代表具有置信度（强/中/弱）的已知因果关系 | | **报告** | 生成一个自包含的 JSON 报告，问题按严重性排序，因果链从根本原因到用户影响，以及具有预期影响估计的优先建议 | ## 安装 ```bash npm install -g @gmod.one/webtrace ``` 或跳过安装： ```bash npx @gmod.one/webtrace --help ``` **要求：** Node.js ≥ 22，Chromium（Playwright 在首次运行自动安装）。 ## 快速开始 完整管道，一条命令： ```bash webtrace run --url https://example.com --pretty ``` 逐步： ```bash # 1. 收集数据 webtrace collect --url https://example.com --output ./results # 2. 标准化 → 提取 → 报告 webtrace normalize ./results/webtrace_example_20260609_120000 --output ir.json webtrace extract ir.json --output features.json webtrace report features.json --output report.json --pretty ``` ## 命令 ### `webtrace run` 一次性完成整个管道。 ``` --url <url> 必需。分析的目标 URL。 --output <dir> 输出目录（默认：./webtrace-output）。 --runs <n> 收集运行次数（默认：1）。 --pretty 美化最终报告 JSON。 --device <name> 移动设备模拟（例如 "iPhone 13"）。 --no-lighthouse 跳过 Lighthouse 收集。 --no-coverage 跳过 JS/CSS 覆盖率。 --no-console 跳过控制台日志捕获。 --no-dom 跳过 DOM 快照。 ``` ### `webtrace collect` 从 URL 捕获性能数据。参见 `run` 选项 — 相同的标志适用。 ### `webtrace normalize <input>` 将原始收集的数据转换为验证的 IRBundle。接受运行目录或父目录（自动检测最新运行）。 ``` --output, -o <file> 写入文件（默认：stdout）。 --pretty 美化 JSON。 ``` ### `webtrace extract <ir-file>` 从标准化的 IR 包中计算诊断特征。 ``` --input, -i <file> IR JSON 的路径（替代位置参数）。 --output, -o <file> 写入文件（默认：stdout）。 --pretty 美化 JSON。 ``` ### `webtrace analyze <features-file>` 应用因果规则并构建降级图。 ``` --input, -i <file> FeatureSet JSON 的路径（替代位置参数）。 --output, -o <file> 写入文件（默认：stdout）。 --pretty 美化 JSON。 ``` ### `webtrace report <features-file>` 生成最终性能报告。接受 FeatureSet JSON（来自 `extract`）— 内部运行因果引擎，无需单独调用 `analyze`。 ``` --input, -i <file> FeatureSet JSON 的路径（替代位置参数）。 --output, -o <file> 写入文件（默认：stdout）。 --pretty 美化 JSON。 ``` ### `webtrace mcp` 为 AI 代理集成启动 MCP stdio 服务器。无标志。详见 [AGENTS.md](AGENTS.md)。 ## 报告格式 报告是一个单一的 JSON 文件。主要部分： ```jsonc { "meta": { "url": "https://example.com", "analyzedAt": "2026-06-09T19:15:19.000Z", "reportVersion": "1.0.0", "featureCount": 7, "graphNodeCount": 24, "graphEdgeCount": 31, "ruleCount": 32, }, "summary": { "score": "moderate", // "good" | "moderate" | "poor" "criticalIssues": 2, "warnings": 5, "infos": 3, "topIssues": [ { "id": "js-long-task", "label": "长任务", "severity": "critical", "confidence": "strong", }, ], }, "issues": [ { "id": "lcp-slow", "label": "LCP 超过 2.5s 阈值", "severity": "critical", "value": 4320, "unit": "ms", "threshold": 2500, "confidence": "strong", "remediation": "优化最大内容绘制元素...", "chainId": "lcp:3", }, ], "chains": [ { "id": "lcp:3", "rootCause": "LCP > 2.5s", "impact": "糟糕的用户体验", "path": [ "TTFB 因服务器响应延迟", "渲染阻塞样式表", "LCP 元素渲染延迟", ], "length": 3, }, ], "recommendations": [ { "priority": "critical", "category": "LCP", "title": "优化最大内容绘制", "action": "内联关键样式，延迟非关键 CSS", "expectedImpact": "减少 LCP 约 40%", "relatedIssues": ["lcp-slow"], }, ], "features": { /* 原始提取的特征用于交叉引用 */ }, } ``` ## 它检测什么 | 类别 | 问题 | | --------------- | ----------------------------------------------------------------------------------- | | **LCP** | 慢 LCP，高 TTFB，渲染阻塞资源，LCP 资源延迟链 | | **JavaScript** | 长任务，高 TBT，繁重执行，未使用代码，主线程瓶颈 | | **网络** | 深度请求链，带宽瓶颈，瀑布深度，关键路径分析 | | **布局** | 布局偏移（CLS），大 DOM 尺寸，强制重流 | | **第三方** | 第三方脚本开销，跟踪像素，嵌入式小部件影响 | ## 架构 ``` src/ ├── index.ts CLI 入口 — 延迟加载命令 ├── collect/ 通过 Playwright 进行 CDP 数据收集 │ ├── browser.ts 浏览器启动器 │ ├── collector.ts 协调器 │ ├── coverage.ts JS/CSS 覆盖率 │ ├── network.ts 网络请求捕获 │ ├── performance.ts 性能 API 指标 │ ├── runtime.ts 运行时元数据 │ ├── dom.ts DOM 快照 │ └── lighthouse.ts Lighthouse 审计 ├── normalize/ 数据标准化 & IR 验证 ├── extract/ 7 个诊断特征提取器 ├── causal/ 因果规则引擎（30 多条规则） │ ├── builder.ts 图构造 │ ├── rules/ 按类别划分的单个因果规则 │ └── types.ts 图数据类型 ├── report/ 报告生成 & 评分 │ ├── analyzer.ts 报告构建器 │ ├── scorer.ts 评分计算 │ ├── remediations.ts 修复模板 │ └── types.ts 报告模式 ├── distill/ 代理优化的摘要层（insights.json） ├── mcp/ MCP stdio 服务器 ├── cli/ CLI 命令处理程序 └── shared/ 共享实用程序 & 类型 ``` ## 开发 ```bash npm install npm run build # 编译 TypeScript npm run typecheck # 仅检查类型 npm test # 运行测试 npm run test:watch # 监视模式下的测试 npm run dev # tsx 监视 — 无构建步骤 ``` ## 技术 | 事物 | 内容 | | ------------------ | --------------------------------------------- | | 运行时 | Node.js ≥ 22 | | 语言 | TypeScript（严格，无 uncheckedIndexedAccess） | | 浏览器 | Playwright（Chromium） | | 验证 | 每个数据边界的 Zod | | 图引擎 | @dagrejs/graphlib | | 性能审计 | Lighthouse | | 测试 | Vitest | ## 许可证 MIT [badge-version]: https://img.shields.io/npm/v/@gmod.one/webtrace.svg [badge-license]: https://img.shields.io/npm/l/@gmod.one/webtrace.svg [badge-downloads]: https://img.shields.io/npm/dm/@gmod.one/webtrace.svg [badge-stars]: https://img.shields.io/github/stars/Be1zebub/WebTracer.svg?style=flat&logo=github [npm]: https://www.npmjs.com/package/@gmod.one/webtrace [license]: https://github.com/Be1zebub/WebTracer/blob/master/LICENSE [repo]: https://github.com/Be1zebub/WebTracer