Claude Ads 深度解析：12 平台付费媒体审计的端到端落地全流程
项目地址: https://gitcode.com/gh_mirrors/cl/claude-ads Claude Ads 是一个面向 Claude Code 的付费媒体（paid-media）运营技能包，把 12 个广告平台的账号导出与账户读取，转化为有来源依据（source-grounded）的审计发现、确定性评分、版本化 JSON 报告，以及受能力门控的账户变更草稿。本文以仓库内的 README.md、ads/SKILL.md 主合约、claude_ads_core/ 确定性引擎源码与 control-plane/ 控制面清单为主体，覆盖从环境安装、数据摄取、审计执行到报告渲染与校验的完整链路。读者读完可以独立安装运行该方案、跑通最小可行的"CSV 导出 → 归一化 → 验证 → 渲染"路径，并理解其"默认只读、评分必须确定性"背后的设计理由。
速览：Claude Ads 是什么，覆盖到什么规模
Claude Ads 的定位是代理机构、顾问与内部增长团队的"付费媒体操作系统"：输入是授权的 CSV 导出、截图、API 响应等，输出是带 run 清单的 JSON 审计包与 Markdown/HTML/PDF 报告。产品边界在 control-plane/PRODUCT_BOUNDARIES.md 中声明为咨询性与默认只读（项目文档声明，非本文推断）。
上图是仓库保留的历史界面演示（原始命令发现体验）。README 明确说明：v2 命令表与平台表才是当前权威口径，该 GIF 仅作历史参考。
仓库的关键规模数字（均与源码/清单文件核对一致）：
- 12 个一等平台：Google、Meta、YouTube、LinkedIn、TikTok、Microsoft、Apple、Amazon、Reddit、Pinterest、Snapchat、X，每个平台有独立的 skill、审计 worker、能力声明与测试路由面（control-plane/manifests/capability-manifest.json，
snapshot_at: 2026-07-11） - 33 个技能目录：skills/ 下 12 个平台技能 + setup、audit、plan、create、monitor、optimize、report、research、attribution 等生命周期技能
- 25 个 worker 代理：agents/ 下 17 个平台/跨平台审计 worker + research、source-verifier、release-verifier 等
- 824 条控制项（controls）：control-plane/manifests/control-registry.json 全量审计目录（如 Google 95 条、Meta 72 条、LinkedIn/TikTok 各 46 条）
- 19 个 v1 JSON Schema：claude_ads_core/schemas/v1/，覆盖 account-snapshot、run-manifest、finding、report-bundle 等
- 24 条行为评估用例：evals/v2-behavior-evals.json，全部为 P0/P1 风险场景（注入攻击、越权变更、过期审批等）
- 零运行时依赖的核心：pyproject.toml 中
dependencies = []，requires-python >= 3.11，PDF 渲染可选安装weasyprint>=69.0,<70.0 - 当前版本 2.0.1（2026-07-13，MIT 许可），12 个平台的
account-mutation（写）能力全部disabled，default_mutation_mode为read-only
官方文档口径的能力状态（control-plane/manifests/capability-manifest.json）：每个平台的 skill-guidance（技能引导）与 export-ingestion（导出摄取）、native-export-normalization（原生导出归一化）均为 implemented 或 fixture-verified；而 account-health-scoring（账号健康评分）在所有平台均为 disabled，原因是"没有已批准的、基于来源的控制项-严重度决策集"，即评分引擎存在但官方画像尚未启用。
先跑起来：安装、依赖与最短可行路径
安装运行时与受管依赖
Claude Code 是官方认可的规范运行时，Codex、Gemini、Cursor、Windsurf、Goose 为实验性目标（install.sh 顶部注释将 claude 标记为 VERIFIED/GA，其余为 EXPERIMENTAL）。推荐从本地克隆安装，而不是远程 pipe-to-shell——后者在主合约 ads/SKILL.md 中被明确列为拒绝项。
以下命令克隆仓库并本地安装到 Claude Code 目录（~/.claude/skills 与 ~/.claude/agents）：
git clone https://gitcode.com/gh_mirrors/cl/claude-ads
cd claude-ads
bash install.sh --source=local
其他宿主或无 Python 依赖时用 --target=codex / --no-deps（如 bash install.sh --target=gemini --source=local --no-deps）。安装器内置目标白名单与路径注入校验（install.sh 的 validate_install_path 拒绝前导 dash、shell 元字符、.. 段与 UNC 路径），卸载只删受所有权清单（ownership manifest）记录的文件：bash uninstall.sh --target=claude。
开发环境：跑完整测试套件
核心包是零依赖的，按 README.md 的 Development 一节创建虚拟环境、按锁文件安装后跑全量 pytest（约 2000 行测试分布在 tests/core/、tests/release/、tests/routing/ 等）：
python3.12 -m venv .venv
.venv/bin/python -m pip install --no-deps -e .
.venv/bin/python -m pip install --require-hashes --only-binary=:all: -r requirements.lock
.venv/bin/python -m pip install --require-hashes --only-binary=:all: -r requirements-dev.lock
.venv/bin/python -m pytest -q
最小可行路径：从一份 CSV 导出到报告产物
不依赖任何真实广告账号也能验证整条确定性管线：仓库自带 12 个平台的脱敏导出夹具（tests/fixtures/exports/ 与 12 个原生导出夹具 tests/fixtures/native_exports/）和一个已验证的报告包 tests/fixtures/reports/sanitized-report-bundle.json。
以下命令演示 CLI 的 ingest-export 子命令，把平台 CSV 归一化为 AccountSnapshot（claude_ads_core/cli.py 的 build_parser 注册了 validate、score、portfolio、status、next、render、ingest-export 七个子命令）：
python -m claude_ads_core ingest-export --platform google tests/fixtures/exports/google.csv
归一化适配器（claude_ads_core/adapters/csv_export.py）对输入有硬性契约：13 个必需列（date、account_id、campaign_id、creative_id、spend、currency 等），每行是 (date, campaign_id, creative_id) 粒度的一条日度观测，重复粒度直接报错而不是静默累加；文件上限 50 MB / 50 万行 / 128 列。
拿到合法的 ReportBundle 后，validate 子命令做契约检查，render 子命令在安全输出根目录下渲染报告。以下两条命令分别验证已脱敏的夹具报告包、并将其渲染为 Markdown：
python -m claude_ads_core validate report-bundle tests/fixtures/reports/sanitized-report-bundle.json
python -m claude_ads_core render tests/fixtures/reports/sanitized-report-bundle.json --format markdown
渲染器（claude_ads_core/reporting.py）是"确定性 + 隐私感知"的：先校验 bundle，再对全部文本跑一遍密钥/邮箱脱敏正则，Markdown 输出还会转义全部格式字符使不可信文本失活；写入走临时文件 + fsync + os.replace 的原子写，拒绝符号链接与路径穿越。JSON 始终是规范产物，Markdown/HTML/PDF 只是同一 bundle 的视图。
理解设计：指挥者、worker 与确定性评分三层结构
分层架构：conductor 拥有最终产物
assets/ 的架构图（architecture.svg）对应的运行时模型是"一个指挥者 + 有界 worker"（ads/SKILL.md 的 Worker orchestration 一节）：
- 指挥者（conductor）：主 skill 上下文，负责范围界定、策略解释、聚合、评分调用与最终产物；
- worker：每个平台一个独立代理（如 agents/audit-google.md，限定
Read/Glob/Grep工具与maxTurns: 24），只返回一个符合 schema 的结果对象，不写文件、不算分； - 确定性引擎：claude_ads_core/ 提供契约验证、归一化、评分与渲染，是唯一可以产出分数的地方。
worker 返回的统一结构是 status（ok / needs_input / blocked / failed）+ findings（每条含 control_id、result、severity、confidence、evidence_refs）+ contradictions / missing_inputs / recovery_hints。必填 worker 失败会把整个 run 标记为 partial，禁止以"完整审计"名义交付。
确定性评分体系：参数与规则
评分合约（ads/references/scoring-system.md）与生产实现（claude_ads_core/scoring.py）必须一致，任何 prompt 或报告模板不得重算分数。核心参数如下：
| 参数 | 取值 | 说明 |
|---|---|---|
| 控制项状态 | pass / fail / unknown / not_applicable | not_applicable 从健康与覆盖分母中剔除；unknown 不计入健康分子分母，但保留在覆盖分母中 |
| 严重度权重 | critical=5，high=3，medium=1，informational=0 | 对应 scoring.py 的 SEVERITY_WEIGHTS，代表控制项失败的影响而非"功能是否新颖" |
| 类别健康 | 100 * sum(pass_weight) / sum(known_control_weight) | 类别内按严重度加权，失败项计 0 分 |
| 平台健康 | sum(category_health * category_weight) | 类别权重必须恰好加总 100，由 _validated_weights 强制校验 |
| 证据覆盖率阈值 | ≥80% graded；60–79.99% provisional；<60% insufficient_evidence | 对应 _coverage_status 的三档状态 |
| 组合健康 | sum(platform_health * spend_share) | 用同时间窗花费占比加权；花费缺失时等权并强制标记 provisional |
所有计算使用 Decimal 与 ROUND_HALF_UP 量化到 0.01，保证跨运行结果可复现（score_account、score_portfolio）。两个关键设计决策：
- 健康分与证据覆盖分开。覆盖率不足时不产出健康分而不是压低健康分，
insufficient_evidence状态下报告必须显示"证据不足"警告而非一个分数； - beta/高级版/不可用功能不扣分。它们被记为
unscored_opportunity（未计分机会项），只有已启用的版本化评分画像（scoring profile）才允许计分——而当前 control-plane/manifests/scoring-profiles.json 中 12 个平台画像全部status: disabled，所以当前版本只产出带证据的"发现项"，不产出账号健康分。
默认只读：mutation gate 的六项条件
写路径在设计上默认关闭：基类适配器（claude_ads_core/adapters/base.py 的 BaseAdapter）把 draft_changes / apply_changes / verify_changes / rollback 全部实现为抛 MutationDisabledError。要启用一次账户写入，必须同时满足 ads/SKILL.md "Mutation gate" 的六项条件：
- 能力清单中该精确操作被标记为已测试且启用；
- 快照与变更指向显式账号/对象 ID；
- 有人类可读的前后 diff，含目标、爆炸半径、学习期影响与政策含义；
- 所有者对精确变更计划与账号级上限（ceilings）审批；
- 存在幂等键、审计记录、回滚动作与验证窗口；
- 适配器应用最小可逆变更并回读远端状态验证。
缺上限即无写入；v2 永久拒绝永久删除，只提供暂停/归档/打标签/导出备份等可逆替代。行为评估 evals/v2-behavior-evals.json 中 safety-delete、safety-stale-approval、safety-no-approval 等 P0 用例把这条边界固化为可回归测试的行为契约。
怎么跑一次审计：命令体系与执行细节
/ads 命令路由
安装后在 Claude Code 中用 /ads（插件安装则为 /claude-ads:ads）。完整命令与产物的对应关系（README.md 与 ads/SKILL.md 的路由表一致）：
| 命令 | 产物 |
|---|---|
/ads setup | 客户、账号、KPI、隐私与护栏 profile（只记录密钥存在性与引用，不存值） |
/ads audit [all\|platform\|scope] | 完整或限定的证据支撑审计 |
/ads plan | 渠道、活动、预算、竞品与测量计划 |
/ads create | 文案、图片、视频、商品照 brief 与素材 |
/ads launch --draft / /ads optimize --draft | 变更草稿，默认不落地 |
/ads monitor | 投放节奏、疲劳度、追踪、政策与性能监控 |
/ads experiment | 受控实验设计与读数 |
/ads report | 从已验证 JSON bundle 渲染报告 |
/ads validate | 契约、run、能力与发布就绪校验 |
/ads status、/ads next | 当前状态与最高优先级阻塞项 |
平台快捷方式 /ads google、/ads meta 等路由到对应平台审计；/ads attribution、/ads tracking 等路由到限定范围审计。每次 run 的产物统一写入 .claude-ads/runs/<run-id>/：manifest.json、account-snapshot.json、audit.json、action-plan.json、report.md（可选 report.html/report.pdf），worker 不得覆盖历史 run 或写共享文件名。
证据策略：来源分级与失效降级
审计结论的每个平台/政策/基准断言都要带 source ID、获取日期、置信度与刷新日期（ads/SKILL.md Evidence policy）。来源按四级排序：官方平台/API/监管文档 > 一手账号导出与 API 响应 > 有方法披露的从业者证据 > 社区 issue/PR/公开仓库（需许可审查）。来源支持度标注为 evidence_based / practitioner / contested / folklore，发现置信度独立标注 high / medium / low / none。refresh_due 过期且无法复核的断言必须降级为 provisional 或 unsupported，并阻塞依赖它的 release-current 断言——"工具不可用永远不会把过期证据变成当前证据"。矛盾证据要原样呈现，不允许平均掉。
开发与回归验证
改动某个表面后先跑聚焦测试再跑全量（CLAUDE.md Verification 一节）。以下命令是 README 给出的三个常用聚焦检查：版本、单契约验证、安装脚本语法：
python -m claude_ads_core --version
python -m claude_ads_core validate finding path/to/finding.json
bash -n install.sh uninstall.sh
验证与发布：完整性分级、行为评估与控制面
结果完整性四档
run 的最终状态由 worker 完成度与证据覆盖率共同决定（skills/ads-audit/SKILL.md Completeness rules）：
complete：所有必填 worker 返回有效结果，且各计分平台覆盖率达标；provisional：worker 全部返回，但存在 60–79% 覆盖或过期的非关键证据；partial：任一必填平台/跨平台 worker 失败或缺席——失败平台从组合健康中整体剔除权重（不记 0 分、不保留陈旧权重），只在成功平台间重归一化；insufficient_evidence：某请求平台覆盖低于 60%。
报告渲染层（claude_ads_core/reporting.py 的 _COMPLETENESS_LABELS/_STATUS_LABELS）会把非 complete 状态渲染为醒目的 WARNING 横幅，Markdown 与 HTML 输出页脚统一标注"分数由确定性引擎产出，渲染时未重算"。
行为评估：把安全边界做成回归用例
evals/ 目录维护面向模型的评估契约：evals/v2-behavior-evals.json 的 24 个用例每条都定义了 expected_skill、risk 等级、required_behaviors（必须行为）与 forbidden_behaviors（禁止行为），覆盖 CSV 注入、私网导航拦截、过期审批、跨窗口归因相加、无证据的否定关键词生成等场景；evals/model-eval-contract.json 与 evals/model_eval_gate.py 提供模型侧门禁，tests/routing/ 与 tests/scripts/ 有对应回归测试。发布级证据还要求外部签名审查与独立验证路径（control-plane/README.md：python scripts/release.py gate 在输入缺失、过期、未签名或不匹配时 fail closed）。
控制面：声明与能力必须对账
control-plane/ 是"公开安全的合约层"，五句话道出了整个设计哲学（control-plane/README.md）：无来源就没有当前断言；无实现+夹具+测试就没有能力声明；无审批与回滚就没有账户变更；无独立验证路径就没有发布；过期/安全失败/评估破损会降级成熟度。能力清单中只有 fixture-verified 或 live-verified 的行为才可声明为可用，规划中的能力必须标 declared 或 disabled。
避坑与实操要点
- 不要把历史 demo 当现状：assets/demo.gif 是 v1 命令发现界面，README 明示 v2 命令表与平台表才是权威口径；引用界面行为以 ads/SKILL.md 的路由表为准。
- 评分引擎存在但官方画像未启用：
account-health-scoring在 12 个平台全部disabled、control-plane/manifests/scoring-profiles.json 全量禁用，当前版本的输出是"带证据的发现项"而非账号健康分；不要拿 ads/references/scoring-system.md 里的参考类别权重直接给 run 打分。 - 重复粒度的 CSV 会直接报错：
ingest-export要求每行是(date, campaign_id, creative_id)的唯一日度观测，平台原生导出需先映射到 13 列通用格式，超限（50 MB / 50 万行 / 128 列）会被拒绝。 - partial 不是失败，但绝不能叫 complete：任一必填平台失败时，该平台权重从组合分中整体剔除并在报告中显式标注 partial；渲染器会自动加 WARNING 横幅，交付时不要去掉。
- 密钥只存引用不存值：profile 里只允许
{"configured": true, "source": "environment", "secret_ref": "GOOGLE_ADS_API_TOKEN"}这类存在性记录；渲染层虽有脱敏正则兜底，但 ads/SKILL.md 要求凭证从源头就不进仓库、profile、报告与日志。 - 远程 pipe-to-shell 安装一律拒绝：
curl | bash类命令在主合约与行为评估（install-curl用例）中都是禁止项，走本地克隆 +install.sh --source=local，或校验过 SHA-256 的 tag 归档。
引用与许可
项目采用 MIT 许可；当前版本 2.0.1（2026-07-13）。CITATION.cff 的官方元数据原样如下：
cff-version: 1.2.0
type: software
title: "Claude Ads"
authors:
- name: AgriciDaniel
license: MIT
version: "2.0.1"
date-released: "2026-07-13"
keywords:
- paid advertising
- google ads
- meta ads
- amazon ads
- tiktok ads
- advertising audit
- retail media
- attribution
- agent skills
- claude code
第三方 API、商标、文档与被引用材料受其各自条款约束，导入外部工作前需核对 control-plane/manifests/source-ledger.json 与 THIRD_PARTY_NOTICES.md。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
