Pixellint

Pixellint

Pixellint 是一款以规范为先的验证器，用于验证像素、回传、转化 API 载荷以及其他衡量素材。它可在终端、CI 和 Agent 中运行，并且每项发现都包含一个稳定 ID、严重性、证据级别以及来源文档。

像素故障会造成归因损失、消耗 QA 时间并浪费广告系列预算。现有工具较为零散：供应商专用辅助工具、企业级标签审计工具，以及不了解广告技术的架构检查工具。Pixellint 是这些工具之下的开源验证层。

$ pixellint validate url 'https://www.facebook.com/tr?ev=Purchse&[email protected]'
rulepack: core
  ok
rulepack: vendor/meta (vendor: meta)
  error   vendor.meta.param.id.missing   `id` is required on Meta Pixel requests but is not present. It is the numeric Pixel ID from Events Manager.
    fix: Set `id` to the numeric Pixel ID shown in Events Manager.
    docs: https://developers.facebook.com/docs/meta-pixel/get-started
  warning vendor.meta.param.ev.invalid   `ev` is `Purchse`, which is not one of the documented values: PageView, AddPaymentInfo, ...
    fix: Use a standard event name, or confirm the custom event is registered in Events Manager.
    docs: https://developers.facebook.com/docs/meta-pixel/reference
  error   vendor.meta.pii.unhashed_email A parameter carries what looks like a raw email address. Meta requires customer information to be normalized and SHA-256 hashed before it is sent.
    fix: Normalize the value, hash it with SHA-256, and send the hex digest instead of the plain address.
    docs: https://developers.facebook.com/docs/meta-pixel/advanced/advanced-matching

2 error(s), 1 warning(s), 0 info message(s) across 2 rulepack(s).

服务端事件会在请求正文中逐个检查：

$ pixellint validate json '{"data":[{"event_name":"Purchase","event_time":1770000000000,
    "action_source":"website","user_data":{"em":"[email protected]"}}]}'
rulepack: vendor/meta-conversions-api (vendor: meta)
  error   vendor.meta-conversions-api.body.event_time.invalid `event_time` must be at most 10 digits, but `1770000000000` has 13. Meta documents it as a Unix timestamp in seconds...
    fix: Send seconds, not milliseconds: divide a JavaScript `Date.now()` by 1000 and floor it.
  error   vendor.meta-conversions-api.body.purchase_requires_value_and_currency A `Purchase` event is missing `custom_data.value` or `custom_data.currency`.
  error   vendor.meta-conversions-api.body.website_requires_source_url The event is marked `action_source: website` but carries no `event_source_url`.

安装

cargo install pixellint          # CLI
cargo install pixellint-mcp      # MCP server
npm install pixellint            # library, WASM-backed

也可以在 pixellint.org 的 Playground 中粘贴 URL，该页面会在浏览器中运行同一引擎。你测试的素材可能会被存储；请参阅隐私政策。供应商合同见 pixellint.org/packs/。像素、转化 API 和同意管理指南见 pixellint.org/docs/。

从大家经常遇到的合同问题入手：

• 转化 API 验证器
• 像素未触发
• Conversions API 无法正常工作
• 什么是转化 API
• Reddit CAPI
• DART Floodlight 标签
• Facebook Pixel Helper 与 Network 对比
• Pinterest 标准事件

使用方法

QA

验证内联素材、使用 @path 指定的文件，或使用 - 从标准输入读取：

pixellint validate url 'https://px.ads.linkedin.com/collect?pid=123456&fmt=gif'
pixellint validate postback @conversion-endpoint.txt --json
printf '%s\n' 'https://example.com/tracking?cb=[CACHEBUSTING]' | pixellint validate vast - --state template

已提取多个 URL 的调用方（如 Vastlint、HTML 适配器）可将其作为文档传入。相同的值只会验证一次：

pixellint validate-many @extracted.json --json

知道哪些素材属于每个广告会话的调用方，可以提供显式分组，并指定原始的零起始行索引：

pixellint validate-sessions @sessions.json --json

初始 IAS UVP 配置文件会检查每个组内外部 ID 的一致性，以及各组之间的唯一性。其报告会保留常规文档发现结果，并添加关系覆盖情况、原始跨度和来源信息。分组、带类型的跳过项和本地资源限制，请参阅 docs/SESSION_SCHEMA.md。

extracted.json 是 docs/MULTI_ARTIFACT_SCHEMA.md 中的包装格式，也可以是 URL 字符串数组。Pixellint 不会解析 VAST、HTML 或 GTM。

vast 表示从 VAST 中提取的一条跟踪 URL，而不是 VAST XML 文档。它会启用针对该 URL 的 IAB VAST 宏名称检查。

完整 HTTP 捕获请使用 request。它会关联端点、方法、标头、查询字段和请求正文，从而一并运行目标地址的传输规则和载荷规则：

pixellint validate request @captured-request.json --json

捕获内容包含字符串 url 和 method，以及一个 headers 对象，或由 { "name": "...", "value": "..." } 条目组成的列表。文本可使用可选的原始字符串 body；捕获的二进制字节则使用 body_base64。共享引擎会在明确的本地限制内解码 identity 和 gzip 实体。示例和验证限制请参阅 docs/HTTP_REQUEST_SCHEMA.md。作为 request 传入的普通 URL 会保留原有行为。

如果素材仍是尚未展开宏的模板，请说明这一点，这样宏规则就会相应调整：

pixellint validate url 'https://example.com/pixel?cb=[CACHEBUSTING]' --state template

CI

当制品干净或仅产生警告时，pixellint validate 以 0 退出；存在任何错误级别的问题时，以 1 退出；遇到用法或输入问题时，以 2 退出。

- uses: aleksUIX/[email protected]
  with:
    path: fixtures/conversion-pixel.txt
    kind: url

version 用于选择 CLI 版本（auto 会跟随此 Action 自身的 v* 标签）。 支持 Linux 和 macOS 运行器，以及 x86_64 和 aarch64。此 Action 会从 GitHub Releases 下载预构建的 tarball。

也可以安装 CLI：

- name: Validate tracking artifacts
  run: |
    cargo install pixellint
    pixellint validate url @fixtures/conversion-pixel.txt

Agent

cargo install pixellint-mcp

pixellint-mcp 通过 stdio 使用 MCP，并提供三个工具。它不会发送制品；pixellint.org 上没有托管的 MCP 服务。pixellint.org 上的 Playground 制品可能会被存储；请参阅 pixellint.org/privacy。

• MCP Registry 名称：mcp-name: io.github.aleksUIX/pixellint

• list_rulepacks

• list_vendors，可按 category 筛选，或指定单个 host

• validate_artifact，接收 artifact_kind、artifact，以及可选的 claimed_vendor、expansion_state、rulepacks、except_rulepacks

响应包含结构化的问题、检测到的厂商和严重性摘要，因此 Agent 无需解析文本即可根据结果采取行动。

Node

npm 封装包需要 Node.js 18 或更高版本。其 ESM 入口使用 node:module 加载面向 Node 的 WASM 构建版本。若要集成到浏览器中，请为浏览器目标构建 pixellint-wasm 并提供浏览器加载器，Playground 即采用了这种方式。

import { validate, isOk } from "pixellint";

const summary = validate("https://www.facebook.com/tr?ev=Purchase");
isOk(summary); // false, the pixel id is missing

库

use pixellint_core::{ArtifactKind, Engine, ExpansionState, ValidationOptions, ValidationRequest};

let engine = Engine::default();
let request = ValidationRequest {
    artifact_kind: ArtifactKind::Url,
    artifact: "https://www.facebook.com/tr?id=1234567890123456&ev=PageView".to_string(),
    claimed_vendor: None,
    expansion_state: ExpansionState::Unknown,
};

let summary = engine.validate(&request, &ValidationOptions::default())?;
assert!(summary.is_ok());

规则包

core 会针对每个类似 URL 的制品运行。只有当制品指向相应厂商的端点时，厂商规则包才会运行，因此无需请求即可获得厂商检查，而且不会在其无法识别的端点上触发检查。转换 API 请求体没有可供判断的端点，因此这些规则包会根据有效载荷的结构来认领它。

此表展示了部分内置规则包。运行 pixellint list-rulepacks --json 可查看已安装版本中的完整清单。

规则包	覆盖范围	依据
core	URL 有效性、传输、凭据、片段、广告技术宏处理、IAB 同意信号	规范性
vendor/meta	facebook.com/tr 像素请求	官方供应商
vendor/meta-conversions-api	Graph API events 边缘端点、URL 和 JSON 事件载荷	官方供应商
vendor/google-analytics	GA4 Measurement Protocol、URL 和 JSON 事件载荷	官方供应商
vendor/google-analytics-collect	Google tag 在浏览器中使用的 /g/collect 传输方式	生态参考
vendor/google-tag-manager	gtm.js、gtag/js 和 ns.html 加载器请求	官方供应商
vendor/google-ads-conversion	Google Ads 转化和展示后转化像素	官方供应商
vendor/google-ads-click-conversions	Google Ads UploadClickConversions JSON	官方供应商
vendor/floodlight	Campaign Manager Floodlight 活动标签	官方供应商
vendor/cm360-tracking-ad	CM360 跟踪广告、dc_trk_aid 和 dc_trk_cid	官方供应商
vendor/cm360-vast-event	CM360 VAST 事件像素、googlesyndication 上的 dc_oe	生态参考
vendor/google-ad-manager	Ad Manager /gampad/ads、iu sz output env gdfp_req correlator	官方供应商
vendor/adobe-analytics	Adobe Analytics 数据收集信标	官方供应商
vendor/pinterest	Pinterest 标签请求和 noscript 回退方案	官方供应商
vendor/pinterest-conversions-api	Conversions API 事件、URL 和 JSON 事件载荷	官方供应商
vendor/snapchat	Snap Conversions API v3、URL 和 JSON 事件载荷	官方供应商
vendor/tiktok	TikTok Pixel 加载器 events.js?sdkid=	生态参考
vendor/tiktok-events-api	Events API 像素跟踪和批处理、URL 和 JSON 事件载荷	官方供应商
vendor/linkedin	LinkedIn 转化图像像素	生态参考
vendor/linkedin-conversions-api	LinkedIn 转化事件，单个和批量	官方供应商
vendor/microsoft-uet	Microsoft Advertising Universal Event Tracking	生态参考
vendor/microsoft-conversions-api	Microsoft Advertising CAPI、URL 和 JSON 事件载荷	官方供应商
vendor/microsoft-clarity	Microsoft Clarity 标签加载器，路径中的项目 ID	官方模板
vendor/reddit	Reddit Pixel 转化请求	生态参考
vendor/reddit-conversions-api	Conversions API v3 事件、URL 和 JSON 事件载荷	官方供应商
vendor/quora-conversions-api	/ads/v0/conversion 上的 Quora Conversion API JSON	官方供应商
vendor/nextdoor-conversions-api	/v2/api/conversions/track 上的 Nextdoor Conversions API JSON	官方供应商
vendor/x-conversions-api	X conversion API 衡量事件、URL 和 JSON 载荷	官方供应商
vendor/x	analytics.twitter.com、analytics.x.com 和 t.co /adsct 上的 X 网站标签图像像素	生态参考
vendor/the-trade-desk	insight.adsrvr.org/track/up 上的 The Trade Desk 通用像素 iframe	官方供应商
vendor/criteo	Criteo OneTag 加载器 ld.js?a=	官方供应商
vendor/criteo-retail-media	/delivery/retailmedia 上的 Criteo Retail Media Delivery API	官方供应商
vendor/taboola	Taboola Pixel 加载器，路径中的账号 ID	官方供应商
vendor/hotjar	Hotjar 跟踪代码，路径中的站点 ID	官方模板
vendor/hubspot	HubSpot 跟踪代码，路径中的 Hub ID	官方模板
vendor/awin	Awin 回退转化像素和 S2S 读取，包括产品级 bd[n]	官方供应商
vendor/awin-basket	Awin 产品级 basket.php product_line 行	官方供应商
vendor/partnerize	Partnerize 转化 URL、路径中的 campaign、clickref 和 currency	官方供应商
vendor/amazon-ads	Amazon Ad Tag 转化加载器，路径中的 Tag ID	生态参考
vendor/amazon-vfw	Amazon DSP Firefly DV 衡量、/dv/ 上的 vstevt 和 dvparams	生态参考
vendor/doubleverify	DoubleVerify visit.jpg 信标、ctx cmp plc sid	生态参考
vendor/doubleverify-event	DoubleVerify event.png 四分位事件、vstevt	生态参考
vendor/freewheel	FreeWheel GET /ad/g/ 广告请求、nw 和 csid 或 ssid	官方供应商
vendor/outbrain	/pixel 和 /unifiedPixel 上的 Outbrain 转化像素	生态参考
vendor/baidu	Baidu Tongji 收集端点 hm.gif?si=	生态参考
vendor/kwai	Kwai Pixel 加载器，s1.kwai.net 上的 sdkid	生态参考
vendor/hubspot-pixel	HubSpot __ptq.gif 收集像素	生态参考
vendor/cj	emjcd.com/u 上的 CJ Affiliate 转化像素	官方供应商
vendor/impact	impact.com Universal Tracking Tag，路径中的 UUID	官方模板
vendor/rakuten	/ep 上的 Rakuten Advertising 转化像素	生态参考
vendor/brevo-js	Brevo JavaScript 跟踪器 sa.js?key=	官方模板
vendor/yahoo-dot	Yahoo DSP Dot 图像像素	官方供应商
vendor/yandex-metrica	Yandex Metrica Measurement Protocol	官方供应商
vendor/openai	OpenAI Ads 图像标签	官方供应商
vendor/openai-conversions-api	OpenAI Ads Conversions API、URL 和 JSON 载荷	官方供应商
vendor/kochava	Kochava S2S 事件、JSON 载荷	官方供应商
vendor/singular	Singular S2S EVENT、查询参数	官方供应商
vendor/amplitude	Amplitude HTTP V2 事件上传	官方供应商
vendor/mixpanel	Mixpanel 跟踪数据接收	官方供应商
vendor/posthog	PostHog capture，单个和批量	官方供应商
vendor/klaviyo	Klaviyo 事件创建	官方供应商
vendor/braze	Braze 用户跟踪：事件、购买、属性	官方供应商
vendor/brevo	Brevo Tracker REST trackEvent	官方供应商
vendor/segment	Segment HTTP Tracking API，单个和批量	官方供应商
vendor/rudderstack	RudderStack HTTP Tracking API 和 Pixel API	官方供应商
vendor/adjust	s2s.adjust.com 上的 Adjust S2S 事件	官方供应商
vendor/appsflyer	AppsFlyer S2S 应用内事件、URL 和 JSON 载荷	官方供应商
vendor/appsflyer-onelink-impression	AppsFlyer OneLink 展示 URL、模板 ID 和 pid	官方供应商
vendor/branch	Branch Events API 标准事件和自定义事件	官方供应商
vendor/adform	区域域名上的 Adform 视频和点击标签、横幅编号 bn	官方供应商
vendor/ispot	iSpot OTT 展示像素、路径中的 TC-####-#	官方供应商
vendor/comscore	Comscore Direct 收集端点 c1、c2、c7	官方供应商
vendor/quantcast	Quantcast Measure 像素、p-code a	官方供应商
vendor/plausible	Plausible Events API JSON	官方供应商
vendor/matomo	Matomo Cloud matomo.php、idsite 和 rec	官方供应商
vendor/parsely	Parse.ly 跟踪器加载器，路径中的 Site ID	官方供应商
vendor/crazyegg	Crazy Egg 跟踪脚本，路径中的账号和脚本 ID	官方模板
vendor/chartbeat	Chartbeat ping、站点 ID h 和账号 UID g	官方供应商
vendor/heap	Heap.js 5 配置加载器，路径中的环境 ID	官方供应商
vendor/heap-track	Heap 服务器端事件跟踪	官方供应商
vendor/heap-user-properties	Heap 服务器端用户属性更新	官方供应商
vendor/heap-account-properties	Heap 服务器端账号属性更新	官方供应商
vendor/mouseflow	Mouseflow 项目脚本，路径中的网站 ID	官方供应商
vendor/intercom	Intercom Messenger 加载器，路径中的工作区 ID	官方供应商

厂商目录

96 家厂商共有 189 个厂商规则包。厂商目录通过归属信息涵盖了更多主机：149 条厂商记录和 348 个主机，因此即使遇到无法识别的像素，也能为其命名。完整清单：docs/STANDARDS.md。

各规则包深度审计记录了已审查的来源、已实现的检查以及尚待满足的要求。规则包数量和通过的测试样例并不能证明已完整覆盖厂商规范。私有协议、不支持的请求表示形式、账户设置和请求历史仍是明确的覆盖限制。

$ pixellint validate url 'https://trc.taboola.com/actions?a=1'
rulepack: directory (vendor: taboola)
  info  directory.no_rulepack_coverage  This endpoint belongs to Taboola (native). No selected endpoint rulepack checked this request. Core checks ran. The directory lists `vendor/taboola` for Taboola. It was not evaluated for this request.

目录条目只声明一件事：某个主机属于某家厂商。条目不包含参数契约，发现结果始终为 info，归属信息也不会改变退出代码。请参阅 docs/VENDOR_DIRECTORY.md。

验证结果还会提供 coverage.status：vendor_checked、recognized_uncontracted 或 unrecognized，并注明是否运行了核心检查以及评估的端点规则包 ID。请将覆盖情况与发现结果一并展示。仅运行核心检查且无错误的结果，并不能证明已完成厂商验证。

pixellint list-vendors
pixellint list-vendors --json

为每次运行选择规则包：

pixellint validate url "$ARTIFACT" --rulepack core
pixellint validate url "$ARTIFACT" --except vendor/meta
pixellint list-rulepacks --json

包含引用的完整规则清单：docs/STANDARDS.md。

证据级别

发现结果会说明其依据来源，你可以据此采用不同标准来要求规则包：

• normative：正式标准，例如 WHATWG URL Standard 或 RFC
• official_vendor：厂商发布的参数契约，并附有 URL
• official_template：厂商发布的模板或 SDK 行为
• ecosystem_reference：厂商在其自有 UI 中生成的一致真实行为，但未形成文档
• heuristic：Pixellint 的判断，并明确标注为启发式

清单加载器会拒绝编译声称属于 official_vendor 却未引用文档的规则包。

自定义规则包

规则包是数据，而非代码。第一方厂商规则包采用与内部端点相同的 JSON 格式编写：

{
  "id": "custom/acme",
  "display_name": "Acme internal pixel",
  "description": "Contract for the internal conversion endpoint.",
  "vendor": "acme",
  "source_level": "heuristic",
  "match": { "hosts": ["px.acme.example"], "path_prefixes": ["/collect"] },
  "params": [
    { "name": "aid", "requirement": "required", "format": { "kind": "integer" } },
    { "name": "ev", "requirement": "required", "format": { "kind": "enum", "values": ["view", "purchase"] } }
  ]
}

pixellint validate url 'https://px.acme.example/collect?ev=purchase' --rulepack-file acme.json

格式说明见 docs/RULEPACK_SCHEMA.md。

只需命名、不需要参数契约的私有像素，应放入目录覆盖文件：

pixellint validate url 'https://px.acme.example/collect' --directory-file extra.json

覆盖文件采用与内置目录相同的条目结构。只能添加新主机，不能抢占第一方主机。请通过 PR 提交上游主机：CONTRIBUTING.md。

Pixellint 不会做什么

• 它不会从文档中提取数据。vast 接受跟踪 URL，而非 XML。html、js 和 gtm 不是验证类型；如果传入这些类型，CLI 会以 2 退出。Vastlint 等调用方会解析 VAST、HTML 或 GTM 容器，并将找到的 URL 交给 Pixellint。pixellint validate-many 可处理这些提取出的 URL。文档结果模型见 docs/MULTI_ARTIFACT_SCHEMA.md。
• 它不会发送请求，也不会检查端点是否有响应。
• 它不会自动修复。发现结果会附带修复提示；是否应用由你决定。

证据

每条规则都有测试作为依据：crates/pixellint-core/src/ 中的单元测试、fixtures/ 中按规则包分别存放的黄金测试集，以及驱动真实 CLI 二进制文件和真实 MCP stdio 传输的集成测试。

cargo test --workspace

基准测试

进程内引擎在黄金测试集、D1 风格的合成像素以及大型 validate-many 批次上的速度：

cargo run -p pixellint-bench --release -- --quick
cargo run -p pixellint-bench --release
cargo run -p pixellint-bench --release -- --mode load --heavy

请参阅 bench/README.md。

文档

• 标准与规则清单
• 厂商目录
• npm 包
• 规则包清单架构
• 架构
• 路线图
• 多工件输出模型
• 显式广告会话输入与输出

许可证

Apache-2.0。Pixellint 与其规则包中提及的任何供应商均无关联，也未获得其认可；请参阅 NOTICE。

本地 HAR 1.2 请求捕获导入和离线重放可通过 pixellint import-har、pixellint validate-har、Rust、npm 和 WASM 使用。有关标头策略、忽略正文的处理方式和记录时钟验证，请参阅 HAR 请求重放与捕获可用性。