AdsOps — 多平台广告投放 Agent 团队(Hermes Profiles 编排)

四个 worker profile 分工协作运营广告与店铺:google_ads / tiktok_ads / meta_ads / store_operator。可按需额外启用 orchestrator profile，通过 kanban 板(ads-ops)分解与派发任务。图片素材经 Codex CLI 订阅全自动生成 投放，所有策略、素材、表现数据落入共享库，由本地 Web 面板统一监控。

📖 协作规范(角色分工 / 任务流转 / 护栏 / 审批):docs/COLLABORATION.md 🎨 生图→投放流水线:docs/CREATIVE_PIPELINE.md

安装(npm 一键)

npx --yes @neilx2ye/adsops                     # 无需安装,直接启动部署向导

该命令会把所选 profile 的 profile.yaml、SOUL.md 和 config.yaml 直接安装到当前设备的 ~/.hermes/profiles/<profile 名>/，Hermes 无需再 手动创建。团队共享库、脚本、文档和面板统一放在 ~/.hermes/adsops/， 不会在 profiles/ 下混入非 profile 内容，也不会在用户主目录另建 ~/adsops。部署向导会依次询问需要的角色，再自动完成前置自检和相似 profile 扫描。生图工具包随 npm 包自动安装到 ~/.hermes/adsops/tools/codex_imagegen_kit/，无需事先在设备上准备。 本包公开发布，运行时不需要 npm 登录。设置了 HERMES_HOME 时，上述两个 目录分别使用 $HERMES_HOME/profiles/ 和 $HERMES_HOME/adsops/。

需要分步执行或指定目录时:

npx --yes @neilx2ye/adsops check
npx --yes @neilx2ye/adsops scan
npx --yes @neilx2ye/adsops init ~/my-adsops

离线分发可在本仓库运行 npm pack,再在目标设备运行 npm install -g ./neilx2ye-adsops-*.tgz。

部署向导首先依次询问是否启用 orchestrator / google_ads / tiktok_ads / meta_ads / store_operator，只创建或接管所选角色，orchestrator 不再 默认创建；它的提示为 [y/N]，必须明确输入 y 或 yes。非交互环境用 npx --yes @neilx2ye/adsops init ~/.hermes/adsops --roles all 或 --roles orchestrator,google_ads,meta_ads 明确选择；all 表示全部五个角色。

设备上已有类似角色的 profile(名字可能不同)时,init 还会交互式询问: 更新(覆盖其 SOUL/描述但保留记忆)、保留(由它担任该角色,只补建缺的) 或无关(照常新建)。非交互环境用 --resolve 角色=profile:动作 指定。 最终"角色 → 实际 profile"名册写在 data/roster.json,未启用角色记为 null。

再次运行同一条 npx 部署命令时，同名的已启用 profile 会自动更新 SOUL.md 和英文 description，memories/、profile 配置、共享数据库及设备上的 data/budget.yaml 均会保留；只有相似但不同名的 profile 才会再次询问。

换设备部署:把 tgz 和 docs/DEPLOY_PROMPT.md 一起发给目标设备的 agent 即可。 也可在仓库内直接 scripts/setup.sh(等价于 init 的 hermes 配置步骤)。

然后人工完成(每个平台一次):

1. 接 MCP:hermes profile use google_ads && hermes mcp add ... (仅给所选 worker 接对应平台,见协作规范第 8 节清单)
2. 真实产品图放入 data/refs/(生图保真参考)
3. Codex CLI 保持订阅登录态(生图走订阅额度)

Web 监控面板

python3 panel/server.py            # → http://localhost:8787

四个视图:表现(花费/ROAS 趋势、campaign 明细)、策略(各平台在投策略)、 素材(生成→投放全生命周期画廊)、动态(所有账户变更审计流水)。

先看效果可灌演示数据:python3 scripts/seed_demo.py

日常使用

# 若启用了 orchestrator,可由它自动分解路由；否则直接点名 worker
hermes kanban --board ads-ops create "[SYNC] 新品 X 上线推广" --triage

# 直接点名派单
hermes kanban --board ads-ops create "[GADS] 巡检:拉取昨日数据落库" --assignee google_ads

# 手动生一张素材(agent 平时自己调这个)
scripts/gen_creatives.sh --prompt "..." --ref data/refs/product.jpg \
  --platform meta --campaign "夏季新品" --name feed_01

仓库结构

profiles/<角色>/SOUL.md      npm 源模板(正常 npx 会直接写入 ~/.hermes/profiles/)
docs/COLLABORATION.md        协作规范(团队宪法)
docs/CREATIVE_PIPELINE.md    生图→投放流水线
scripts/adsctl.py            共享库 CLI(agent 记录策略/素材/表现/事件)
scripts/gen_creatives.sh     Codex 生图 + 自动登记
tools/codex_imagegen_kit/    随部署命令安装的 Codex 订阅生图工具包
panel/                       Web 监控面板(纯标准库,无依赖)
data/                        schema、素材产物、参考图(运行数据不入库 git)

发布维护

npm login --auth-type=web --registry=https://registry.npmjs.org/
npm test
npm publish --access=public --registry=https://registry.npmjs.org/

本包通过 publishConfig 固定发布到官方 registry,访问级别为 public。 发布时会自动重跑冒烟测试。 在无桌面环境中，项目的 .npmrc 会阻止 npm 调用 xdg-open；如果 npm 要求网页认证，请在交互式终端中保持命令运行，并复制终端显示的 URL 到本地 浏览器中用 Security Key 完成认证。 发布后，任何人都能查看并安装此包。

安全设计

• 所有平台写操作先经 MCP 只读接口核实现状;删除类操作全面禁止
• 高风险动作(新 campaign、预算 >30%、批量改品)必须在 kanban 卡 block 等人工 unblock
• 每次真实变更强制写审计流水(events 表),面板"动态"页可回溯