adclip

adclip

一个开放、独立、由模型路由的营销创意与学习引擎。

adclip 将营销活动意图转化为经过政策检查的文案、静态创意、短视频和自适应电子邮件；保留精确的创意溯源；从已投放的创意中读取效果数据；并将这些证据整理为明确的实验和下一轮测试建议。

brief
  -> copy / image / video / email
  -> exact creative artifacts + provenance
  -> deployment lineage
  -> performance observations
  -> experiment evidence
  -> next test

MCP 是接入 adclip 的一种接口，而非其架构本身。同一套应用服务也可供独立 CLI 使用，并计划用于支持未来的本地浏览器工作台。

adclip 的存在意义

大多数 AI 营销技术栈将工作流拆分到文案工具、图像／视频生成器、电子邮件平台、广告平台仪表板和创意分析工具中。adclip 的目标是让营销活动模型、创意溯源和学习闭环保持可移植性，同时让模型提供商和投放平台继续作为可替换的适配器。

核心原则：

• **模型中立：**工作流请求能力／路由，而不是将某一家模型供应商写死。
• **独立运行：**CLI 工作流不需要 MCP 主机。
• **本地优先：**配置得当时，本地命令和兼容 OpenAI 的推理可离线或在隔离网络环境中运行。
• **可移植：**营销活动产物、电子邮件 HTML／文本、清单、部署映射、观察结果和实验均保留为可检查的文件。
• **重视证据：**不会将观察性排名悄然呈现为因果增量效果。
• **安全控制支出：**付费生成需显式选择启用，且不会悄然执行路由回退。

从这里开始

• 快速入门 — 零成本 DTC 创意、电子邮件和学习流程演练。
• 示例 — 面向营销人员的营销活动案例集。
• 文档索引 — 架构与能力文档。
• LLM 指南 — 模型中立的贡献者／Agent 规范。

从 PyPI 安装：

pipx install adclip

PyPI 版本可能落后于当前代码库。若要使用本文档介绍的 main 完整功能集，请从源代码安装：

git clone https://github.com/dreliq9/adclip.git
cd adclip
python3.11 -m venv .venv
.venv/bin/pip install -e ".[dev]"

需要 Python 3.11+。

五分钟零成本演示

仅使用虚构的创意提供商，为 Meta、Reels/TikTok 和 Google 生成一场虚构的 DTC 护肤品发布活动：

adclip run examples/01-dtc-skincare/brief.json \
  --text-provider fake \
  --image-provider fake \
  --video-provider fake

无需调用模型，即可渲染与之匹配、已纳入代码库的发布邮件：

adclip email render \
  examples/01-dtc-skincare/email_brief.json \
  examples/01-dtc-skincare/email_message.json \
  --output-dir ./adclip_skincare_email_render

构建完整的合成创意测试套件：

python examples/06-creative-experiment/build_demo.py

然后检查证据：

adclip performance report ./adclip_creative_test_demo \
  --since 2026-08-01 \
  --until 2026-08-07 \
  --action-report-time conversion

构建器会输出一个实验 ID，可传给 experiment-evaluate 和 next-test。以上命令均不需要付费模型 API 或在线广告账户。

示例案例集

代码库中的示例围绕营销问题组织，而非围绕内部子系统：

示例	营销工作内容	主要渠道
01-dtc-skincare	产品发布／首次购买	Meta、Reels、TikTok、Google、电子邮件
02-b2b-saas-lead-gen	获取合格演示预约	LinkedIn、Google Search
03-local-service-lead-gen	本地直接响应式线索获取	Meta、Google Search
04-subscription-winback	生命周期留存	电子邮件
05-mobile-app-acquisition	免费试用获取	TikTok、Reels、Shorts、Meta
06-creative-experiment	受控的钩子学习	合成 Meta 观察数据

请参阅 examples/README.md，了解每个案例的业务目标、受众、假设和命令。

当前能力概览

领域	当前能力
广告活动简报	结构化的 AdBrief、格式、政策约束、成本估算
文案	与提供方无关的生成、筛选、评分、修复/评审兼容性
图片	通过 fal/直接 OpenAI/模拟适配器提供的任务路由，支持模型系列架构
视频	通过 fal/模拟适配器为短视频格式提供路由生成
模型选择	明确区分路由/提供方/模型/选项，并支持对比测试
电子邮件	序列生成、结构化内容块、响应式 HTML/文本、标头、检查、修补
来源追踪	稳定的广告活动 ID 和与素材绑定的创意 ID
成效	明确的投放映射和只读 Meta Insights 同步
报告	归因安全的精确时间窗口和描述性创意比较
实验	对照/处理素材、变更因素、阈值、比率置信区间
学习	支持/反驳/无法确定的证据，以及确定性的下一步测试操作
接口	CLI + MCP，共用应用服务
安全	运行时网络模式、付费生成门控、只读 Meta 连接器

独立 CLI

实用的发现命令：

adclip status
adclip formats
adclip routes
adclip routes --modality image
adclip route-recommend image --text-heavy
adclip estimate examples/01-dtc-skincare/brief.json
adclip email --help
adclip performance --help

路由创意生成

# Route defaults
adclip run brief.json

# Task-specific selection
adclip run brief.json \
  --image-route text-heavy \
  --video-route premium

# Explicit provider/model overrides remain authoritative
adclip run brief.json \
  --image-route general \
  --image-provider openai \
  --image-model gpt-image-2 \
  --video-route budget \
  --video-provider fal \
  --video-model wan-2.7

兼容性别名仍然可用：

--llm          -> --text-provider
--llm-model    -> --text-model
--image        -> --image-provider
--video        -> --video-provider

当前媒体路由

模态	路由	主要模型	用途
图片	general	fal / gpt-image-2 medium	通用营销创意
图片	text-heavy	fal / gpt-image-2 high	可读文本/布局处理
图片	bulk	fal / flux-2-pro	控制成本的批量处理
图片	draft	fal / nano-banana-2-lite	快速探索
图片	brand-control	fal / flux-2-flex	调控调色板/布局
图片	premium	直接 OpenAI / gpt-image-2 high	高级通用渲染
视频	general	fal / kling-o3-standard	通用社交/效果视频
视频	premium	fal / veo-3.1	电影感/原生音频内容
视频	multi-shot	fal / seedance-2-fast	有导演设计的多镜头叙事
视频	budget	fal / wan-2.7	低成本探索

参考图、矢量图、多参考图、图片动画和素材剪辑路由已列入目录，但在具备所需的输入约定/适配器之前仍不可执行。请参阅模型路由。

电子邮件广告活动和 HTML 编辑

电子邮件是原生广告活动状态，而非对某个 ESP 的封装。

# Render the canonical launch message locally
adclip email render \
  examples/01-dtc-skincare/email_brief.json \
  examples/01-dtc-skincare/email_message.json \
  --output-dir ./rendered-email

# Apply stable block-level edits to a generic fixture
adclip email patch-message \
  examples/email_message.json \
  examples/email_patches.json \
  --output ./message-edited.json

生成的广告活动包含可移植的消息 JSON、响应式 HTML、纯文本、标头、检查报告和清单。序列生成使用配置的文本提供方；通用的 fake 文本提供方是用于生成文案的测试夹具，并非电子邮件序列生成器。发送、同意、抑制名单和 ESP 账户状态仍由连接器负责。

请参阅电子邮件广告活动。

成效与创意学习

adclip 可以将确切的本地创意映射到现有的 Meta 广告，并读取 Insights，而无需添加 Meta 修改方法。

adclip performance link-meta ./campaign \
  --variant-id v01 \
  --account-id act_123456 \
  --ad-id 987654321

export ADCLIP_META_ACCESS_TOKEN=...

adclip performance sync-meta ./campaign \
  --since 2026-08-01 \
  --until 2026-08-07 \
  --action-report-time conversion

衡量窗口以 (since, until, action_report_time) 为键，因此同一日期的转化归因行和展示归因行不会被悄然合并。

描述性比较：

adclip performance compare ./campaign \
  --since 2026-08-01 \
  --until 2026-08-07 \
  --action-report-time conversion \
  --metric ctr

请参阅成效学习。

明确的创意实验

仓库中附带的演示采用了一个常见的付费社交广告问题：生动的问题框定是否优于直白的产品优势钩子？

python examples/06-creative-experiment/build_demo.py

或者，在解读结果之前先声明自己的实验：

adclip performance experiment-create ./campaign \
  --name "Hook CTR test" \
  --hypothesis "Problem framing increases CTR" \
  --changed-factor hook \
  --control-variant v01 \
  --treatment-variant v02 \
  --control-value "plain benefit" \
  --treatment-value "problem framing" \
  --metric ctr

当前的推断性判定刻意仅限于具有明确汇总分子/分母的比率指标：CTR、外链 CTR 和行动率。缺少方差/事件级证据时，CPA 和 ROAS 仍为描述性指标。观察性比较按设计无法得出结论，实验输出目前均保留 causal_claim: false。

请参阅实验约定。

周期性模型对比

默认选项应由证据而非声誉决定。

# Dry-run plan only
adclip bakeoff \
  --modality image \
  --routes general,text-heavy,bulk,draft \
  --output-dir ./image-bakeoff

实时执行需要同时提供 --execute 和常规的付费提供商授权。 结果会记录路由、提供商、模型、选项、延迟、估算成本、 工件 SHA-256、失败情况、评估维度和人工审核字段。

文本提供商

提供商	用途
claude-cli	通过订阅认证的兼容性默认选项
openai-compatible	本地或托管的 /v1/chat/completions 端点
command	通过标准输入/标准输出运行的本地可执行文件
sampling	支持采样的 MCP 主机
anthropic	直接选择使用的 Anthropic API
fake	确定性的文案测试／示例

本地 HTTP 推理：

export ADCLIP_TEXT_PROVIDER=openai-compatible
export ADCLIP_TEXT_MODEL=qwen2.5:14b
export ADCLIP_OPENAI_BASE_URL=http://127.0.0.1:11434/v1
export ADCLIP_RUNTIME_MODE=offline
adclip copy examples/01-dtc-skincare/brief.json

参见模型提供商。

MCP

本地注册示例：

{
  "mcpServers": {
    "adclip": {
      "command": "adclip-mcp"
    }
  }
}

MCP 接口提供与 CLI 相同的营销活动、路由、电子邮件、效果和 实验应用服务。重要的新工具包括：

adclip_list_media_routes
adclip_recommend_media_route
adclip_email_generate_campaign
adclip_email_render
adclip_email_lint
adclip_email_patch_html
adclip_email_patch_message
adclip_performance_link_meta
adclip_performance_deployments
adclip_performance_sync_meta
adclip_performance_report
adclip_performance_compare
adclip_experiment_create
adclip_experiments
adclip_experiment_evaluate
adclip_experiment_next_test

运行时与计费安全

支持的运行时模式：

online
restricted_network
offline
air_gapped

离线／隔离网络环境下会拒绝使用外部生成提供商。本地回环文本 推理仍可用。可能产生费用的生成操作需要：

ADCLIP_ALLOW_LIVE_APIS=1

Meta 效果连接器是独立的只读网络适配器，不使用生成费用授权标志。

测试

项目测试套件无需付费 API 或实时营销账号即可运行：

python -m pytest
python -m compileall src/adclip

当前状态与下一阶段目标

当前核心功能包括内容生成、电子邮件撰写、精确的创意溯源、 只读 Meta 效果数据导入、支持归因的报告、明确的实验以及下一项测试建议。

剩余的主要产品缺口包括：

1. 以 SQLite／迁移作为权威状态存储、基于内容寻址的工件以及 可持久化且可恢复的作业；
2. BrandKit 和 SourceLibrary；
3. 内置的本地浏览器工作台；
4. 创意属性提取和支持实验的受控生成；
5. Google Ads、TikTok 和 ESP 效果适配器；
6. 疲劳／变点分析以及更丰富的 CPA／ROAS 证据；
7. 需单独授权的草稿／暂停部署工作流。

路线图请参见独立架构。