marketing-ops-automation

多平台全链路的自动化营销运营工具：目标驱动（业务目标→plan→客群→波次→执行→复盘）、多渠道（X / Email / Reddit / LinkedIn，可扩展）、多通道（API / browser-CDP / OS 键鼠模拟 / SMTP 等四类十种，含降级储备）、零凭据优先。 统一六原语（publish / reply / message / engage / search / inbox）、统一写路径事务管道（门禁→节流→回读校验→截图→dry-run 停点→发送→确认→账本）、统一账本。 三种外壳共用本内核：CLI（mkt.py）／MCP（mcp_server.py）／Skill（skills/marketing-ops）。

定位一句话：agent 当参谋（出方案，产出可校验的数据工件）、内核当执行（守门禁，上限是内核属性）、人当闸门（未经人审的计划拒跑）。 配套的调研与设计文档（现状盘点/架构/渠道风控调研等）存于本地工作区，不随本仓库分发；仓库内 data/schemas.md 自含全部数据契约。

合规与纪律（先读这个）

• 仅用于本人拥有/运营的账号；不碰他人账号、不做代运营自动化

• CDP 通道零凭据：不保存任何密码/token/Cookie；SMTP 凭据只走环境变量

• 一切写操作默认 dry-run，--go 才实跑

• 失败即停（不重试轰炸）；回读校验不一致绝不发送（449 空正文事故的固化）

• 人类节奏：随机间隔 + 单次硬上限 + 日预算（core/throttle.py 的表）

• 不群发：千人千面内容为前提；占位符残留会被门禁直接拒绝

• 不做对抗：不绕验证码、不伪造指纹、不用代理池

Related MCP server: branchlift

安装与启动

pip install -r requirements.txt   # 仅 playwright；CDP 走系统 Chrome，无需下载浏览器
./launch.command                  # 双击亦可：首次复制登录 profile，启动 CDP 9222
python3 mkt.py check              # 确认 CDP 会话与 X/Gmail 登录态

命令矩阵与验证等级

等级含义：PROVEN=真实账号跑通；PORTED=模式已验证、本封装未整跑；UNVERIFIED=选择器未实测，首跑必须人工盯跑（首跑清单见 03 渠道文档 §5）。

规划层：计划是数据，人审是闸门（05 产品方案 §2）

# 1. agent/人 按 data/schemas.md 的 plan schema 写 data/plans/<plan_id>.json
# 2. 校验（schema/能力矩阵/size≤内核日预算/判据预注册）
python3 -c "from core.planlint import load_plan, lint_plan; print(lint_plan(load_plan('data/plans/x.json')))"
# 3. 人审通过后置 review.human_approved=true —— 否则 send_queue 与 MCP 都拒跑该 campaign
# 4. 生成 data/queues/<campaign>.json 并执行（见上表）

上限是内核属性：计划里的 size 超过 core/throttle.py 日预算会被 lint 拒收。

MCP 服务（mcp_server.py，stdio，零依赖）

{"mkt": {"command": "python3", "args": ["/绝对路径/marketing-ops-automation/mcp_server.py"]}}

6 个工具：mkt_status / mkt_channels / mkt_plan_lint / mkt_search / mkt_ledger_query（只读）+ mkt_run_queue（写，默认 dry-run；UNVERIFIED 渠道拒实跑；未经人审的 plan 拒跑）。只暴露队列粒度写操作——没有绕过留痕的路径。

Skill（skills/marketing-ops/SKILL.md）

agent 操作协议：目标→plan→客群→人审→执行→复盘七步。装入 ~/.agents/skills/ 即可在 ZCode 等宿主触发（内容协作走 warm-email-outreach / expert-review-outreach / b2b-account-mapping）。

通道层（core/transports.py）

ACTIVE×4：api（OAuth，Reddit 二期）｜browser-cdp（PROVEN）｜os-input（macOS 键鼠/AX 模拟，UNVERIFIED，transports/os_input.py）｜protocol（SMTP/IMAP，PROVEN）。 RESERVE×6（通道储备库）：webdriver｜rss-public（只读）｜esp-api（事务邮件）｜mobile-appium｜integration（平台原生）｜semi-auto-ui（人工确认兜底）。 每渠道×动作声明首选+降级链；降级用于"路不通"，不用于"绕风控"——风控信号的响应是降节奏或 mkt pause，不是换马甲。风控阈值与账号限额见项目 06 文档（官方口径亲核；代码预算一律低于官方上限，见 throttle.INTERVALS/OFFICIAL_LIMITS）。

环境变量

数据三件套（data/，gitignore）

• queues/<campaign>.json 队列；ledger.jsonl 全局账本；contacts.jsonl 线索库

• suppress.txt 抑制名单（每行一个目标）；shots/ 留证；state/ 日预算状态

• schema 详见 data/schemas.md

结构

core/      ledger 账本 · gates 门禁 · throttle 节流 · pipeline 写路径事务 · evidence 留证 · cdp 会话 · transports 通道注册表 · planlint 计划校验/人审强制
channels/  x/(vendor+adapter) · email_smtp · email_cdp · reddit · linkedin
transports/  os_input（macOS 键鼠/AX 模拟，UNVERIFIED）
skills/    marketing-ops（agent 操作协议）
tests/     离线单测（33 项，含 449 事故回归与人审门禁）：python3 -m unittest discover tests -v
mcp_server.py  MCP 外壳（stdio JSON-RPC，零依赖）

X 渠道 vendor 引入 x-ops-automation（上游 github: roy-tong/x-ops-automation）， 不改写已验证代码（见 channels/x/vendor/PROVENANCE.md）；上游修选择器时同步。

License

MIT（见 LICENSE）。channels/x/vendor/ 引入自同作者仓库 x-ops-automation（MIT）。