5 步跑通 12 个付费广告平台的审计管线：Claude Ads 源码级完整解析

5 步跑通 12 个付费广告平台的审计管线Claude Ads 源码级完整解析【免费下载链接】claude-adsClaude-first paid-media operations skill for Claude Code across 12 ad platforms (Google, Meta, YouTube, LinkedIn, TikTok, Microsoft, Apple, Amazon, Reddit, Pinterest, Snapchat, X): source-grounded audits, deterministic findings and evidence coverage, versioned JSON reports, and capability-gated account changes.项目地址: https://gitcode.com/gh_mirrors/cl/claude-adsClaude Ads 是一个为 Claude Code 等 Agent 宿主设计的付费广告运营技能包覆盖 Google、Meta、YouTube、LinkedIn、TikTok 等 12 个广告平台把授权导出的账户数据转成带证据引用的确定性审计与版本化 JSON 报告。如果你是服务广告主的代理商、顾问或内部性能团队读完后你能独立完成三件事把 Claude Ads 装进自己的 Agent 宿主、用仓库自带的确定性核心跑通CSV 导出 → 归一化快照 → 评分 → 报告全链路、并理解它的账户变更为什么默认被锁死。核心思路速览整体技术路线可以概括为一个指挥者conductorAgent 负责范围、策略与最终产物把独立可并行的平台切片分发给有界 workerworker 只返回符合 schema 的 findings再由零运行时依赖的 Python 核心 claude_ads_core 做契约校验、确定性评分与报告渲染——所有对账户的写操作默认关闭必须逐条通过能力、审批、幂等、回滚与验证门禁。组件作用版本 / 固定方式claude-ads-coreclaude_ads_core/契约校验、评分引擎、报告渲染、编排存储v2.0.0Python ≥3.11核心零运行时依赖Agent 宿主执行/ads命令族Claude Code 为正式版Codex/Cursor/Windsurf/Gemini/Goose 标注为实验性托管 Python 环境install.sh 安装时按 lock 文件建 venvCPython 3.11/3.12hash 校验 --only-binary可选依赖落地页分析、截图、PDF、图表区间固定如urllib32.6.3,3、weasyprint69,70见 requirements.txtcontrol-plane 清单能力、来源、安全、发布状态的权威记录control-plane/manifests/schema_version 1.0.0上面这张动图展示的是 v1 的命令发现体验。⚠️ README.md 第 82–83 行明确声明v2 命令表/ads setup、/ads audit、/ads report等 13 个命令才是当前权威版本别按 GIF 里的老命令去找功能。快速跑通最小可行路径整套系统没有 GPU 或数据库门槛任何能跑 Python 3.11 的 Linux/macOS/Windows 机器都够用纯技能安装甚至不需要 Python。预期 3~5 分钟产物写入~/.claude/skills与托管 venvgit clone https://gitcode.com/gh_mirrors/cl/claude-ads # 拉取仓库 cd claude-ads bash install.sh --sourcelocal # 安装到 Claude Code默认 targetclaude含托管 Python 环境 python3.12 -m venv .venv # 另建开发环境用于自测 .venv/bin/python -m pip install --no-deps -e . # 装 claude-ads-core核心零依赖 .venv/bin/python -m claude_ads_core --version # 验证核心 CLI 可用 .venv/bin/python -m claude_ads_core ingest-export --platform google tests/fixtures/exports/google.csv # 冒烟测试归一化仓库自带 fixture .venv/bin/python -m pytest -q # 跑完整确定性测试套件最后两行就是官方推荐的冒烟路径用 tests/fixtures/exports/google.csv只有 1 行演示数据喂给 CSV 适配器能成功输出AccountSnapshotJSON 即说明数据链路通pytest覆盖契约、适配器、编排、评分与发布门禁全部确定性执行。数据层把平台导出变成可审计的快照数据入口是 claude_ads_core/adapters/csv_export.py 定义的通用 CSV 形态13 个必填列date、account_id、campaign_id、creative_id、spend、conversions、currency等每行是(date, campaign_id, creative_id)粒度的一条日度观测。适配器对输入做了三层硬约束参数默认值作用MAX_EXPORT_BYTES50 MB超过直接拒绝防止误读巨型文件MAX_EXPORT_ROWS500,000行上限超出报错而非静默截断MAX_EXPORT_COLUMNS128列上限防止表头注入异常形状重复的粒度组合会被拒绝而不是静默二次计数见第 74–82 行 docstring这是为什么这样设计的关键审计数字必须可复算任何一行歧义都会污染下游评分。归一化后的AccountSnapshot受 account-snapshot.schema.json 约束平台字段必须是 12 个平台枚举之一币种必须是三字母大写代码时间窗end不得早于startcontracts.py。评分层健康分与证据覆盖为什么必须分开评分引擎在 claude_ads_core/scoring.py 里按严重度加权参数取值作用SEVERITY_WEIGHTScritical5、high3、medium1、informational0每条健康控制的权重NORMAL_COVERAGE80%证据覆盖率达到即评为 normalPROVISIONAL_COVERAGE60%60–79% 为 provisional低于 60% 为 insufficient_evidence核心算法是先分类别、再组合计类别内健康分 通过权重和 ÷ 已知权重和 × 100unknown不进分子也不进分母只拉低证据覆盖率组合分只对有分数且类别权重非零的类别做加权平均并重新归一化score_account。整个模块只用Decimal和ROUND_HALF_UP做十进制运算避免浮点误差导致同一输入两次跑出不同分数——这就是文档反复强调never recompute scores in prompts的底气分数永远由引擎算不由模型算。 但有一个文档与源码不一致的地方必须知道README 第 170–171 行把scoring.py描述为production implementation而 capability-manifest.json 和 scoring-profiles.json 显示 12 个平台的account-health-scoring能力全部是disabled理由是没有经批准、有来源支撑的 severity 决策集。control_registry.py 的 docstring 把这叫 fail-closed 设计命名检查项不自动等于可评分控制项。所以在当前发行版里平台健康分会缺席而不是被编造——score命令可用但真实启用需要 profile 被批准。编排与安全层指挥者、worker 与写操作门禁这是 Claude Ads 区别于套壳 Prompt的核心。类比一个审计事务所field 员工worker只提交证据单签字打分scoring与出报告由主办审计师conductor独占——ads/SKILL.md 明确规定 worker 不得写最终报告失败的平台会让整个 bundle 标记为partial而不是被平均掉。以 agents/audit-google.md 为例每个 worker 的前置元数据就锁死了范围maxTurns: 24、工具白名单只有Read, Glob, Grep、输出契约固定为status/findings/contradictions/missing_inputs/recovery_hints。编排产物是 claude_ads_core/orchestration.py 的OrchestrationStorerun/task/result/gate 四类包各按 ID 落盘为 JSON目录 0700、文件 0600用O_CREAT|O_EXCL|O_NOFOLLOW保证同一 ID 只能写入一次路径含符号链接直接报错。这相当于一个只能追加、可凭 sha256 验真artifact_sha256的账本事后可以逐条核对当时的决策包长什么样。对账户的写操作则被 adapters/base.py 在基类层面拒绝draft_changes、apply_changes、verify_changes、rollback四个方法默认全部抛MutationDisabledError。SKILL.md 的 mutation gate 要求 6 项条件齐备能力已启用、显式 ID、前后 diff、Owner 审批、幂等键回滚、远端状态复验且 v2 明确拒绝永久删除。缺任一项就没有写权限——缺上限意味着没有写是文档原话。报告与隐私层JSON 为源渲染即视图报告渲染器 claude_ads_core/reporting.py 的模块 docstring 定调JSON 是唯一权威产物Markdown/HTML/PDF 只是不重算分数、不加载远程资源的视图。渲染前内置一组脱敏正则第 31–41 行Bearer 令牌、api_key/password:类赋值、邮箱一律替换为[REDACTED]Markdown 输出还会对反引号、星号等语法字符做转义让不可信文本在报告里彻底失活。CLI 侧对应关系见 cli.py命令输入输出validate contract path5 种核心契约 工作流契约{status: valid}或错误score --controls --findings --weights控制项、findings、类别权重健康分 覆盖率 分类别明细portfolio path账户得分数组支出加权或临时等权组合分render bundle.json校验后的 ReportBundle.md/.html/.pdfPDF 需 WeasyPrintingest-export --platform p通用 CSVAccountSnapshot JSON实战调优与场景适配只装技能、不装 Python 环境用bash install.sh --targetclaude --sourcelocal --no-depsinstall.sh 的--no-deps跳过托管环境。适合宿主机 Python 不在 3.11/3.12 支持矩阵内的情况此时ingest-export、score等核心命令不可用/ads技能仍可基于 LLM 完成分析型工作流。换用其他 Agent 宿主--target有严格白名单claude正式版之外的codex、cursor、windsurf、gemini、goose都标注 EXPERIMENTALinstall.sh 注释。注意 resolve_target_paths 中只有claude与codex会装 Python 依赖ALLOW_PIP1其余宿主只拷贝技能文件。若自动探测路径不对用--skill-dir/--agent-dir覆盖这两项会先经过validate_install_path拒绝路径穿越与 shell 元字符。只验证确定性核心不装技能也能单独使用核心pip install --no-deps -e .后依次跑claude-ads-core validate finding file.json、claude-ads-core score ...、claude-ads-core status --as-of 2026-11-04后者会读取 control-plane 清单评估仓库自身状态。开发自测完整命令见 README.md 的 Development 一节关键是pip checkpytest -q两条必须全绿。高频踩坑点⚠️clone 地址与安装源的坑install.sh 内REPO_URL硬编码为 GitHub 上游地址如果你从本文给出的 gitcode 镜像克隆务必加--sourcelocal否则--sourcegit或 auto 模式会绕过你的本地检出、另拉一份上游仓库。⚠️别按 demo 动图找命令GIF 是 v1 界面权威命令表是 README 第 58–71 行的 v2 表格/ads validate、/ads status、/ads next等。动图里出现的旧命名在 v2 中已被路由表取代。⚠️卸载不要手删目录ads/SKILL.md 明确禁止 glob 删除ads-*会误伤同名的无关技能如ads-weather只能用bash uninstall.sh --targetclaude按所有权清单精确删除清单缺失时脚本会停下要求人工审查。引用与延伸阅读官方引用元数据见 CITATION.cffv2.0.1MIT 许可2026-07-13 发布可将其中的 title/keywords 直接转成你所需的 BibTeX software 条目。相关生态均为本项目依赖或参照的标准/工具非竞品Agent Skills本仓库的技能文件格式skills/*/SKILL.mdads/agents/openai.yaml接口元数据遵循的各 Agent 宿主通用技能约定跨宿主可移植的前提。MCPModel Context Protocolads/references/mcp-integration.md 定义了集成与审批边界Claude Ads 的账户读取默认走授权导出而非直连 API。WeasyPrint / reportlab / matplotlibPDF 渲染与图表的三个可选渲染后端对应weasyprint69等区间固定版本。结语到这里你已经具备了独立安装、冒烟测试并读懂 Claude Ads 证据链的能力。下一步建议先用ingest-export跑通自己的一个平台导出再用/ads audit让它按同一套契约重新分析对比两边的 findings。【免费下载链接】claude-adsClaude-first paid-media operations skill for Claude Code across 12 ad platforms (Google, Meta, YouTube, LinkedIn, TikTok, Microsoft, Apple, Amazon, Reddit, Pinterest, Snapchat, X): source-grounded audits, deterministic findings and evidence coverage, versioned JSON reports, and capability-gated account changes.项目地址: https://gitcode.com/gh_mirrors/cl/claude-ads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考