渐进式披露重构实战Cloudflare Zaraz 参考文档 5 文件分层体系在 Codex Skills 目录中的设计与落地【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本篇围绕 skills/.curated/cloudflare-deploy/references/zaraz/IMPLEMENTATION_SUMMARY.md 展开解析该仓库如何把一份 366 行的 Cloudflare Zaraz 单体参考文档重构为 README、api、configuration、patterns、gotchas 五文件渐进式披露体系并逐文件拆解其承载的 API、配置、模式与排障内容。读完你将掌握面向 AI Agent / LLM 消费场景组织参考文档的方法论同时获得 Zaraz 从埋点、配置到调试的完整实战链路。一、文档定位一份重构总结而非使用教程在 Codex Skills 目录Skills Catalog for Codex中IMPLEMENTATION_SUMMARY.md是一份典型的元文档meta-document它不直接教你怎么用 Zaraz而是记录了一次文档重构工程的背景、动作与收益。其价值在于回答三个问题为什么要重构、拆成了什么、效果如何。该文档位于 references/zaraz/ 目录下与该目录的 5 份参考文档平级。其核心动机来自 Agent 场景的上下文经济性参考文档由 AI 代理按需加载单体文档会强制每次任务加载全部内容原文记录为 366 行浪费 token 且增加无关干扰。重构后形成的 5 文件体系按职责切分让跟踪事件调试问题配置工具SPA 埋点等任务各自只需加载必要文件。需要说明的数据口径总结文档记录的篇幅为 README 111 行、api 287 行、configuration 307 行、patterns 430 行、gotchas 317 行合计 1,452 行vs 原 366 行。但当前仓库快照中这些文件的实际行数分别为 111、112、90、75、81 行合计 469 行——除 README 外均与记录值存在差异推测是后续对参考文档做过精简。因此本文在转述文件职责与设计意图时采用总结文档口径在做行号级引用时一律以当前仓库文件为准。二、核心设计5 文件渐进式披露Progressive Disclosure体系总结文档开篇用一张文件清单表定义了整个体系的骨架文件记录的篇幅用途README.md111 行导航、决策树、快速开始api.md287 行Web API 参考、Zaraz Contextconfiguration.md307 行控制台配置、触发器、工具、同意管理patterns.md430 行SPA、电商、Worker 集成gotchas.md317 行排障、限制、工具特有坑总计1,452 行vs 366 行原文这套体系遵循先导航、后深入、按任务取用的原则README 是入口与路由表api/configuration 是两种操作面代码埋点 vs 控制台配置patterns 是跨模块的组合实战gotchas 是经验与边界。文件之间通过交叉引用cross-reference串联而非重复拷贝。2.1 渐进式披露的量化收益总结文档给出了重构前后的按任务加载量对比任务重构前单体重构后按需加载变化跟踪事件366 行README(111) api(287) 398 行内容更聚焦API 类任务调试问题366 行gotchas(317)减少约 13%配置工具366 行configuration(307)减少约 16%SPA 跟踪366 行README patterns 的 SPA 小节约 180 行减少约 51%结论是按任务加载可将无关内容削减 13%51%按总结文档口径。需要补充的是跟踪事件场景在文档记录口径下 398 行略多于原 366 行其收益体现为每一行都与手头任务强相关若按当前快照的实际行数README 111 api 112 223 行计算则连体积也一并下降。无论哪种口径按需加载、去噪提纯都是渐进式披露的核心价值。三、逐文件详解File Summary3.1 README.md —— 导航中枢111 行README.md 承担 6 项职责总体概览与核心概念、快速开始、Zaraz 与 Workers 的选型判断、导航表、按任务阅读顺序、决策树。核心概念部分明确了 Zaraz 的四条主线服务端执行脚本运行在 Cloudflare 边缘而非浏览器、单次 HTTP 请求所有工具经一个端点加载、隐私优先控制发送给第三方的数据、零客户端 JS 开销。快速开始给出可直接落地的埋点代码README.md#L23-L32// Track page view zaraz.track(page_view); // Track custom event zaraz.track(button_click, { button_id: cta }); // Set user properties zaraz.set(userId, user_123);按任务阅读顺序表README.md#L57-L67是渐进式披露最直接的落地体现任务需要阅读的文件为站点添加分析README → configuration.md跟踪自定义事件README → api.md调试跟踪问题gotchas.mdSPA 跟踪api.md → patterns.mdSPA 小节电商跟踪api.md#ecommerce → patterns.md#ecommerceWorker 集成patterns.md#worker-integrationGDPR 合规api.md#consent → configuration.md#consent同文件内置的决策树README.md#L71-L92把需求 → 文件映射固化下来浏览器埋点 → api.md配置 Zaraz → configuration.md与 Workers 集成 → patterns.md 的 Worker 小节调试 → gotchas.md。这份决策树正是 Agent 读取该技能时的路由依据。3.2 api.md —— Web API 与 Zaraz Context记录 287 行api.md 覆盖zaraz.track()、zaraz.set()、zaraz.ecommerce()、Zaraz Context系统/客户端属性、zaraz.consentAPI、zaraz.debug、Cookie 方法、TypeScript 类型定义。事件跟踪api.md#L5-L13zaraz.track(button_click); zaraz.track(purchase, { value: 99.99, currency: USD, item_id: 12345 }); zaraz.track(pageview, { page_path: /products, page_title: Products }); // SPA参数为eventNamestring与propertiesobject可选fire-and-forget。用户属性api.md#L15-L20zaraz.set()支持单键与批量对象两种入参属性在页面会话内持久用于用户识别与分群。电商事件api.md#L26-L38zaraz.ecommerce()支持Product Viewed、Product Added、Product Removed、Cart Viewed、Checkout Started、Order Completed六个标准事件工具会自动映射到 GA4、Facebook CAPI 等zaraz.ecommerce(Order Completed, { order_id: ORD-789, total: 149.98, currency: USD, products: [{ product_id: SKU123, quantity: 2, price: 49.99 }] });Zaraz Context 系统属性{{system.page.url}}、{{system.page.title}}、{{system.page.referrer}}、{{system.device.ip}}、{{system.device.userAgent}}、{{system.device.language}}、{{system.cookies.name}}、{{client.__zarazTrack.userId}}可直接用于触发器条件与工具映射。同意管理api.md#L47-L62zaraz.consent.getAll()查询、setAll()/set()设置、modal属性控制弹窗、addEventListener(consentChanged, ...)监听变更标准流程是控制台配置用途 → 工具映射用途 → 弹窗/编程授权 → 允许后工具才触发。调试与 Cookiezaraz.debug true开启实时检查并可通过zaraz.tools查看已加载工具zaraz.getCookie()读 Zaraz 命名空间 Cookie、zaraz.readCookie()读任意 Cookie。文件末尾还给出了完整的Zaraz接口 TypeScript 定义api.md#L91-L112方便类型安全的工程接入。3.3 configuration.md —— 控制台配置、触发器与工具记录 307 行configuration.md 覆盖控制台配置流程、触发器类型含 History Change、工具配置GA4、Facebook、Google Ads、动作与动作规则、选择性加载、同意管理配置、隐私特性、测试工作流。触发器类型表configuration.md#L13-L19是本文档的骨架类型触发时机典型用途Pageview页面加载页面浏览跟踪Click元素被点击按钮跟踪Form Submission表单提交线索捕获History ChangeURL 变化SPAReact/Vue 路由Variable Match自定义条件条件触发其中History Change触发器configuration.md#L21-L28监听pushState、replaceState与 hash 变化配置Type: History Change, Event: pageview即可让 SPA 路由变化自动产生 pageview无需手写埋点代码——这是 SPA 场景推荐的首选方案。Click 触发器示例CSS 选择器.buy-button触发purchase_intent事件并通过{{system.clickElement.text}}携带按钮文案。工具配置要点GA4 填Measurement ID: G-XXXXXXXXXXFacebook Pixel 只接受纯数字 Pixel ID不能带fbpx_前缀Google Ads 需同时配置Conversion ID: AW-XXXXXXXXX与Conversion Label。同意管理配置流configuration.md#L60-L69设置 → Consent → 创建用途如 analytics、marketing→ 将工具映射到用途 → 行为设为未获同意前不加载也可用zaraz.consent.setAll({ analytics: true, marketing: true })编程授权。隐私特性默认值IP 匿名化默认开启Cookie 控制经由同意用途GDPR/CCPA 通过同意弹窗满足。测试工作流三步Preview Mode不发布先验证→ Debug Modezaraz.debug true→ 浏览器 Network 面板过滤 zaraz 关键字。文末给出两份关键限制事件属性 100KB、同意用途最多 20 个。3.4 patterns.md —— SPA、电商与 Worker 集成记录 430 行patterns.md 是体积最大的实战文件覆盖 SPA 跟踪React/Vue/Next.js、用户识别流程、完整电商漏斗、A/B 测试、Worker 集成Context Enrichers、Worker Variables、HTML 注入、多工具协同、GTM 迁移、最佳实践。SPA 跟踪优先推荐控制台配置 History Change 触发器零代码需要手动埋点时在路由变化处调用patterns.md#L3-L11// On route change zaraz.track(pageview, { page_path: pathname, page_title: document.title });用户识别登录时zaraz.set({ userId, email, plan })并 tracklogin事件登出时zaraz.set(userId, null)注意属性只能置空、无法清除。完整电商漏斗patterns.md#L24-L32环节方法浏览zaraz.ecommerce(Product Viewed, { product_id, name, price })加购zaraz.ecommerce(Product Added, { product_id, quantity })结算zaraz.ecommerce(Checkout Started, { cart_id, products: [...] })购买zaraz.ecommerce(Order Completed, { order_id, total, products })A/B 测试zaraz.set(experiment_checkout, variant)记录分组experiment_viewed/experiment_conversion事件上报曝光与转化。Worker 集成是本文件的重头戏。Context Enricherpatterns.md#L42-L56在工具执行前修改上下文例如注入用户地域export default { async fetch(request, env) { const body await request.json(); body.system.userRegion request.cf?.region; return Response.json(body); } };在 Zaraz Settings Context Enrichers 中配置启用Worker Variables则在服务端计算动态值以{{worker.variable_name}}形式被引用。GTM 迁移对照表patterns.md#L58-L67dataLayer.push({event:purchase})→zaraz.ecommerce(Order Completed, {...}){{Page URL}}→{{system.page.url}}{{Page Title}}→{{system.page.title}}Page View/Click 触发器一一对应。文末的 5 条最佳实践优先控制台触发器而非内联代码、SPA 启用 History Change、用zaraz.debug true调试、尽早落地同意机制、敏感/服务端数据走 Context Enrichers。3.5 gotchas.md —— 排障、限制与工具特有陷阱记录 317 行gotchas.md 采用问题 → 原因 → 方案结构组织事件不触发、同意问题、SPA 跟踪坑、性能问题、工具特有怪癖、数据层问题、限制表、何时不该用 Zaraz、调试清单。事件不触发的 5 步排查gotchas.md#L3-L16① 工具在控制台已启用绿点② 触发器条件满足③ 工具对应用途已获同意④ 工具凭证正确GA4 为G-XXXXXXXXXXFB 仅数字⑤ 用 debug 命令复核zaraz.debug true; console.log(Tools:, zaraz.tools); console.log(Consent:, zaraz.consent.getAll());同意弹窗不出现清除同意 Cookie 后刷新页面document.cookie zaraz-consent; expiresThu, 01 Jan 1970 00:00:00 UTC; path/;工具过早触发则把工具映射到用途并设置未获同意前不加载。SPA 跟踪漏事件hash 路由#/path需手动监听hashchange补发 pageviewReact 中useEffect依赖数组必须包含location否则路由变化不触发。性能与限制工具数量超过 50 个会拖慢页面事件 payload 控制在 100KB 以内限制表完整记录为请求大小 100KB、同意用途 20 个、API 速率 1000 req/s。工具特有怪癖表gotchas.md#L56-L61工具问题方案GA4实时报告看不到事件等待 5-10 分钟用 DebugViewFacebookInvalid Pixel ID仅使用纯数字 ID去掉fbpx_前缀Google Ads转化归因不到事件中携带send_to: AW-XXX/LABEL数据层注意属性仅按页面会话持久需在每次页面加载时重新 set嵌套访问用{{client.__zarazTrack.user.plan}}。何时不该用 Zarazgotchas.md#L76-L81服务端到服务端跟踪改用 Workers、实时双向通信、二进制数据传输、认证流程——这些场景超出了标签管理器的能力边界。四、关键改进清单新增了什么、保留了什么总结文档将改进分为三组是理解这次重构动作的变更日志结构层面新增 5 文件渐进式披露体系、README 导航表、需求决策树、按任务阅读顺序指南、文件间交叉引用。新增内容Zaraz Context系统/客户端属性、SPA 专用的 History Change 触发器、Context Enrichers 模式、Worker Variables 模式、同意管理深度剖析、工具特有怪癖GA4/Facebook/Google Ads、GTM 迁移指南、系统性排障、何时不该用 Zaraz章节、TypeScript 类型定义。保留内容全部原有 API 方法、电商跟踪示例、同意管理、Workers 集成已扩充、常用模式已扩充、调试工具、参考链接——重构没有丢弃任何既有价值而是在其上做增量。五、质量控制标准Quality Metrics总结文档列出 8 条可复用的文档质量标准也可作为任何参考文档的自检清单统一 Markdown 格式代码示例带语言标记结构化数据用表格限制、参数、对比gotchas 采用问题 → 原因 → 方案格式文件间交叉引用无详见文档式占位符示例真实可执行Workers API 语法经过核验。最后一条Verified API syntax for Workers尤其重要——面向 Agent 的参考文档一旦出现语法错误会直接导致代理写出不可运行的代码。六、在仓库中的使用方式与阅读路线Zaraz 参考库在技能入口 SKILL.md 中被挂在媒体与内容决策树的分支上Third-party script management → zaraz/并在产品索引的 Media Content 分类下列出references/zaraz/。也就是说当 Agent 被请求管理第三方脚本/接入分析工具时会先命中 SKILL.md 的决策树再加载 Zaraz 参考库进入参考库后再按 README 中的决策树与按任务阅读顺序表路由到具体文件。完整阅读路径建议README.md总览与路由→ 按任务进入api.md代码埋点/configuration.md控制台配置/patterns.md组合实战/gotchas.md排障。总结文档还记录称原单体 SKILL.md 已保留为_SKILL_old.md备份以供对照当前快照中未检索到该文件以实际仓库为准。本仓库为只读目录读者可按上述路径阅读、参考与在自己的项目中复刻这套分层方法而无需修改仓库本身。七、小结IMPLEMENTATION_SUMMARY.md的价值不在于 Zaraz 本身而在于它示范了一种面向 Agent 消费的参考文档工程化方法以 README 做路由、以职责切分文件、以交叉引用代替复制、以量化指标验证收益。其 13%51% 的按任务加载削减本质上是把上下文效率当作一等公民来设计文档。这套渐进式披露 元文档总结的组合拳对任何面向 LLM/AI 代理交付技术参考的组织都具备直接的可复制性。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
渐进式披露重构实战：Cloudflare Zaraz 参考文档 5 文件分层体系在 Codex Skills 目录中的设计与落地
渐进式披露重构实战Cloudflare Zaraz 参考文档 5 文件分层体系在 Codex Skills 目录中的设计与落地【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本篇围绕 skills/.curated/cloudflare-deploy/references/zaraz/IMPLEMENTATION_SUMMARY.md 展开解析该仓库如何把一份 366 行的 Cloudflare Zaraz 单体参考文档重构为 README、api、configuration、patterns、gotchas 五文件渐进式披露体系并逐文件拆解其承载的 API、配置、模式与排障内容。读完你将掌握面向 AI Agent / LLM 消费场景组织参考文档的方法论同时获得 Zaraz 从埋点、配置到调试的完整实战链路。一、文档定位一份重构总结而非使用教程在 Codex Skills 目录Skills Catalog for Codex中IMPLEMENTATION_SUMMARY.md是一份典型的元文档meta-document它不直接教你怎么用 Zaraz而是记录了一次文档重构工程的背景、动作与收益。其价值在于回答三个问题为什么要重构、拆成了什么、效果如何。该文档位于 references/zaraz/ 目录下与该目录的 5 份参考文档平级。其核心动机来自 Agent 场景的上下文经济性参考文档由 AI 代理按需加载单体文档会强制每次任务加载全部内容原文记录为 366 行浪费 token 且增加无关干扰。重构后形成的 5 文件体系按职责切分让跟踪事件调试问题配置工具SPA 埋点等任务各自只需加载必要文件。需要说明的数据口径总结文档记录的篇幅为 README 111 行、api 287 行、configuration 307 行、patterns 430 行、gotchas 317 行合计 1,452 行vs 原 366 行。但当前仓库快照中这些文件的实际行数分别为 111、112、90、75、81 行合计 469 行——除 README 外均与记录值存在差异推测是后续对参考文档做过精简。因此本文在转述文件职责与设计意图时采用总结文档口径在做行号级引用时一律以当前仓库文件为准。二、核心设计5 文件渐进式披露Progressive Disclosure体系总结文档开篇用一张文件清单表定义了整个体系的骨架文件记录的篇幅用途README.md111 行导航、决策树、快速开始api.md287 行Web API 参考、Zaraz Contextconfiguration.md307 行控制台配置、触发器、工具、同意管理patterns.md430 行SPA、电商、Worker 集成gotchas.md317 行排障、限制、工具特有坑总计1,452 行vs 366 行原文这套体系遵循先导航、后深入、按任务取用的原则README 是入口与路由表api/configuration 是两种操作面代码埋点 vs 控制台配置patterns 是跨模块的组合实战gotchas 是经验与边界。文件之间通过交叉引用cross-reference串联而非重复拷贝。2.1 渐进式披露的量化收益总结文档给出了重构前后的按任务加载量对比任务重构前单体重构后按需加载变化跟踪事件366 行README(111) api(287) 398 行内容更聚焦API 类任务调试问题366 行gotchas(317)减少约 13%配置工具366 行configuration(307)减少约 16%SPA 跟踪366 行README patterns 的 SPA 小节约 180 行减少约 51%结论是按任务加载可将无关内容削减 13%51%按总结文档口径。需要补充的是跟踪事件场景在文档记录口径下 398 行略多于原 366 行其收益体现为每一行都与手头任务强相关若按当前快照的实际行数README 111 api 112 223 行计算则连体积也一并下降。无论哪种口径按需加载、去噪提纯都是渐进式披露的核心价值。三、逐文件详解File Summary3.1 README.md —— 导航中枢111 行README.md 承担 6 项职责总体概览与核心概念、快速开始、Zaraz 与 Workers 的选型判断、导航表、按任务阅读顺序、决策树。核心概念部分明确了 Zaraz 的四条主线服务端执行脚本运行在 Cloudflare 边缘而非浏览器、单次 HTTP 请求所有工具经一个端点加载、隐私优先控制发送给第三方的数据、零客户端 JS 开销。快速开始给出可直接落地的埋点代码README.md#L23-L32// Track page view zaraz.track(page_view); // Track custom event zaraz.track(button_click, { button_id: cta }); // Set user properties zaraz.set(userId, user_123);按任务阅读顺序表README.md#L57-L67是渐进式披露最直接的落地体现任务需要阅读的文件为站点添加分析README → configuration.md跟踪自定义事件README → api.md调试跟踪问题gotchas.mdSPA 跟踪api.md → patterns.mdSPA 小节电商跟踪api.md#ecommerce → patterns.md#ecommerceWorker 集成patterns.md#worker-integrationGDPR 合规api.md#consent → configuration.md#consent同文件内置的决策树README.md#L71-L92把需求 → 文件映射固化下来浏览器埋点 → api.md配置 Zaraz → configuration.md与 Workers 集成 → patterns.md 的 Worker 小节调试 → gotchas.md。这份决策树正是 Agent 读取该技能时的路由依据。3.2 api.md —— Web API 与 Zaraz Context记录 287 行api.md 覆盖zaraz.track()、zaraz.set()、zaraz.ecommerce()、Zaraz Context系统/客户端属性、zaraz.consentAPI、zaraz.debug、Cookie 方法、TypeScript 类型定义。事件跟踪api.md#L5-L13zaraz.track(button_click); zaraz.track(purchase, { value: 99.99, currency: USD, item_id: 12345 }); zaraz.track(pageview, { page_path: /products, page_title: Products }); // SPA参数为eventNamestring与propertiesobject可选fire-and-forget。用户属性api.md#L15-L20zaraz.set()支持单键与批量对象两种入参属性在页面会话内持久用于用户识别与分群。电商事件api.md#L26-L38zaraz.ecommerce()支持Product Viewed、Product Added、Product Removed、Cart Viewed、Checkout Started、Order Completed六个标准事件工具会自动映射到 GA4、Facebook CAPI 等zaraz.ecommerce(Order Completed, { order_id: ORD-789, total: 149.98, currency: USD, products: [{ product_id: SKU123, quantity: 2, price: 49.99 }] });Zaraz Context 系统属性{{system.page.url}}、{{system.page.title}}、{{system.page.referrer}}、{{system.device.ip}}、{{system.device.userAgent}}、{{system.device.language}}、{{system.cookies.name}}、{{client.__zarazTrack.userId}}可直接用于触发器条件与工具映射。同意管理api.md#L47-L62zaraz.consent.getAll()查询、setAll()/set()设置、modal属性控制弹窗、addEventListener(consentChanged, ...)监听变更标准流程是控制台配置用途 → 工具映射用途 → 弹窗/编程授权 → 允许后工具才触发。调试与 Cookiezaraz.debug true开启实时检查并可通过zaraz.tools查看已加载工具zaraz.getCookie()读 Zaraz 命名空间 Cookie、zaraz.readCookie()读任意 Cookie。文件末尾还给出了完整的Zaraz接口 TypeScript 定义api.md#L91-L112方便类型安全的工程接入。3.3 configuration.md —— 控制台配置、触发器与工具记录 307 行configuration.md 覆盖控制台配置流程、触发器类型含 History Change、工具配置GA4、Facebook、Google Ads、动作与动作规则、选择性加载、同意管理配置、隐私特性、测试工作流。触发器类型表configuration.md#L13-L19是本文档的骨架类型触发时机典型用途Pageview页面加载页面浏览跟踪Click元素被点击按钮跟踪Form Submission表单提交线索捕获History ChangeURL 变化SPAReact/Vue 路由Variable Match自定义条件条件触发其中History Change触发器configuration.md#L21-L28监听pushState、replaceState与 hash 变化配置Type: History Change, Event: pageview即可让 SPA 路由变化自动产生 pageview无需手写埋点代码——这是 SPA 场景推荐的首选方案。Click 触发器示例CSS 选择器.buy-button触发purchase_intent事件并通过{{system.clickElement.text}}携带按钮文案。工具配置要点GA4 填Measurement ID: G-XXXXXXXXXXFacebook Pixel 只接受纯数字 Pixel ID不能带fbpx_前缀Google Ads 需同时配置Conversion ID: AW-XXXXXXXXX与Conversion Label。同意管理配置流configuration.md#L60-L69设置 → Consent → 创建用途如 analytics、marketing→ 将工具映射到用途 → 行为设为未获同意前不加载也可用zaraz.consent.setAll({ analytics: true, marketing: true })编程授权。隐私特性默认值IP 匿名化默认开启Cookie 控制经由同意用途GDPR/CCPA 通过同意弹窗满足。测试工作流三步Preview Mode不发布先验证→ Debug Modezaraz.debug true→ 浏览器 Network 面板过滤 zaraz 关键字。文末给出两份关键限制事件属性 100KB、同意用途最多 20 个。3.4 patterns.md —— SPA、电商与 Worker 集成记录 430 行patterns.md 是体积最大的实战文件覆盖 SPA 跟踪React/Vue/Next.js、用户识别流程、完整电商漏斗、A/B 测试、Worker 集成Context Enrichers、Worker Variables、HTML 注入、多工具协同、GTM 迁移、最佳实践。SPA 跟踪优先推荐控制台配置 History Change 触发器零代码需要手动埋点时在路由变化处调用patterns.md#L3-L11// On route change zaraz.track(pageview, { page_path: pathname, page_title: document.title });用户识别登录时zaraz.set({ userId, email, plan })并 tracklogin事件登出时zaraz.set(userId, null)注意属性只能置空、无法清除。完整电商漏斗patterns.md#L24-L32环节方法浏览zaraz.ecommerce(Product Viewed, { product_id, name, price })加购zaraz.ecommerce(Product Added, { product_id, quantity })结算zaraz.ecommerce(Checkout Started, { cart_id, products: [...] })购买zaraz.ecommerce(Order Completed, { order_id, total, products })A/B 测试zaraz.set(experiment_checkout, variant)记录分组experiment_viewed/experiment_conversion事件上报曝光与转化。Worker 集成是本文件的重头戏。Context Enricherpatterns.md#L42-L56在工具执行前修改上下文例如注入用户地域export default { async fetch(request, env) { const body await request.json(); body.system.userRegion request.cf?.region; return Response.json(body); } };在 Zaraz Settings Context Enrichers 中配置启用Worker Variables则在服务端计算动态值以{{worker.variable_name}}形式被引用。GTM 迁移对照表patterns.md#L58-L67dataLayer.push({event:purchase})→zaraz.ecommerce(Order Completed, {...}){{Page URL}}→{{system.page.url}}{{Page Title}}→{{system.page.title}}Page View/Click 触发器一一对应。文末的 5 条最佳实践优先控制台触发器而非内联代码、SPA 启用 History Change、用zaraz.debug true调试、尽早落地同意机制、敏感/服务端数据走 Context Enrichers。3.5 gotchas.md —— 排障、限制与工具特有陷阱记录 317 行gotchas.md 采用问题 → 原因 → 方案结构组织事件不触发、同意问题、SPA 跟踪坑、性能问题、工具特有怪癖、数据层问题、限制表、何时不该用 Zaraz、调试清单。事件不触发的 5 步排查gotchas.md#L3-L16① 工具在控制台已启用绿点② 触发器条件满足③ 工具对应用途已获同意④ 工具凭证正确GA4 为G-XXXXXXXXXXFB 仅数字⑤ 用 debug 命令复核zaraz.debug true; console.log(Tools:, zaraz.tools); console.log(Consent:, zaraz.consent.getAll());同意弹窗不出现清除同意 Cookie 后刷新页面document.cookie zaraz-consent; expiresThu, 01 Jan 1970 00:00:00 UTC; path/;工具过早触发则把工具映射到用途并设置未获同意前不加载。SPA 跟踪漏事件hash 路由#/path需手动监听hashchange补发 pageviewReact 中useEffect依赖数组必须包含location否则路由变化不触发。性能与限制工具数量超过 50 个会拖慢页面事件 payload 控制在 100KB 以内限制表完整记录为请求大小 100KB、同意用途 20 个、API 速率 1000 req/s。工具特有怪癖表gotchas.md#L56-L61工具问题方案GA4实时报告看不到事件等待 5-10 分钟用 DebugViewFacebookInvalid Pixel ID仅使用纯数字 ID去掉fbpx_前缀Google Ads转化归因不到事件中携带send_to: AW-XXX/LABEL数据层注意属性仅按页面会话持久需在每次页面加载时重新 set嵌套访问用{{client.__zarazTrack.user.plan}}。何时不该用 Zarazgotchas.md#L76-L81服务端到服务端跟踪改用 Workers、实时双向通信、二进制数据传输、认证流程——这些场景超出了标签管理器的能力边界。四、关键改进清单新增了什么、保留了什么总结文档将改进分为三组是理解这次重构动作的变更日志结构层面新增 5 文件渐进式披露体系、README 导航表、需求决策树、按任务阅读顺序指南、文件间交叉引用。新增内容Zaraz Context系统/客户端属性、SPA 专用的 History Change 触发器、Context Enrichers 模式、Worker Variables 模式、同意管理深度剖析、工具特有怪癖GA4/Facebook/Google Ads、GTM 迁移指南、系统性排障、何时不该用 Zaraz章节、TypeScript 类型定义。保留内容全部原有 API 方法、电商跟踪示例、同意管理、Workers 集成已扩充、常用模式已扩充、调试工具、参考链接——重构没有丢弃任何既有价值而是在其上做增量。五、质量控制标准Quality Metrics总结文档列出 8 条可复用的文档质量标准也可作为任何参考文档的自检清单统一 Markdown 格式代码示例带语言标记结构化数据用表格限制、参数、对比gotchas 采用问题 → 原因 → 方案格式文件间交叉引用无详见文档式占位符示例真实可执行Workers API 语法经过核验。最后一条Verified API syntax for Workers尤其重要——面向 Agent 的参考文档一旦出现语法错误会直接导致代理写出不可运行的代码。六、在仓库中的使用方式与阅读路线Zaraz 参考库在技能入口 SKILL.md 中被挂在媒体与内容决策树的分支上Third-party script management → zaraz/并在产品索引的 Media Content 分类下列出references/zaraz/。也就是说当 Agent 被请求管理第三方脚本/接入分析工具时会先命中 SKILL.md 的决策树再加载 Zaraz 参考库进入参考库后再按 README 中的决策树与按任务阅读顺序表路由到具体文件。完整阅读路径建议README.md总览与路由→ 按任务进入api.md代码埋点/configuration.md控制台配置/patterns.md组合实战/gotchas.md排障。总结文档还记录称原单体 SKILL.md 已保留为_SKILL_old.md备份以供对照当前快照中未检索到该文件以实际仓库为准。本仓库为只读目录读者可按上述路径阅读、参考与在自己的项目中复刻这套分层方法而无需修改仓库本身。七、小结IMPLEMENTATION_SUMMARY.md的价值不在于 Zaraz 本身而在于它示范了一种面向 Agent 消费的参考文档工程化方法以 README 做路由、以职责切分文件、以交叉引用代替复制、以量化指标验证收益。其 13%51% 的按任务加载削减本质上是把上下文效率当作一等公民来设计文档。这套渐进式披露 元文档总结的组合拳对任何面向 LLM/AI 代理交付技术参考的组织都具备直接的可复制性。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
