Cindy 投放监控伙伴交付模板详解:delivery.md 的字段契约、取值规则与离线核对实践

原创2026-10-25 14:05:231,984 阅读
文章标签:人工智能AI Agent代码智能体大模型AI 技能Agent 记忆工具调用MCP Clients多智能体浏览器控制GUI 自动化本地部署插件系统桌面应用移动开发前端跨平台语音任务调度交互助手

Cindy 投放监控伙伴交付模板详解:delivery.md 的字段契约、取值规则与离线核对实践

在 Cindy 的 Bot 包体系中,ad-spend-watch(投放监控伙伴)把"给用户看什么"固化成了一份只有八行的交付模板:delivery.md。它看起来极简,却是整套监控流程的落点——前面所有"记账、套门槛、判状态"的计算,最终都要收敛成这张表和四行结论。本文以该模板为骨架,逐列拆解它背后可验证的字段来源,结合配套脚本 spend_ledger.py 与 SKILL.md 的操作规程,说明如何把一份投放报表正确落成这份交付物,以及哪些地方一旦写错就会失真。

模板原文与它在包中的位置

先看模板的实际内容,全文如下(即 delivery.md 的完整形态):

# 投放监控伙伴

| 规则 | 对象 | 窗口 | 实际值 | 限值 | 严重度 | 状态 |
|---|---|---|---|---|---|---|

最该改的一处:
原因(观察/推断/未知):
数据截至:
待用户确认:

它由两部分组成:一张七列的空表,和四行固定前缀的结论句。标题行 # 投放监控伙伴 是伙伴名称,与 manifest.json 中 profile.name 一致。

这份模板不是孤立文件,它被登记为该技能的 resources:

这一步登记是强制性的,不是文档习惯。内置包解析器在读取技能目录时,会要求"技能子树的实际文件"与"正文 + 脚本 + 资源"的声明集合完全一致:

  • 见 nativePackage.ts:对每个技能计算 references = [bodyPath, ...scripts, ...resources],再比对 files 中以 skills/<slug>/ 开头的全部文件,长度不等或存在未声明文件即判定 INVALID_PACKAGE。

也就是说,templates/delivery.md 必须既存在于磁盘、又出现在 manifest 的 resources 里,且所有引用都必须落在 skills/ad-spend-watch-ops/ 前缀下。模板缺失或未登记,整个包都无法被读取和邀请。这条约束解释了为什么这个八行文件在仓库里位置如此严格。

交付格式为什么是契约而不是排版

在 SKILL.md 的操作顺序里,模板只出现在最后一步:

使用 templates/delivery.md,事实/推断/未知分开。具体辅助检查见配套 ad-spend-watch-evidence,不要把离线PASS当作真实Bot运行。

这句简短的话定了三条硬边界:

  1. 格式固定:交付必须按模板的形状给出,而不是自由发挥成一段话;
  2. 认知状态必须标注:事实、推断、未知三类不允许混写在同一句里;
  3. 离线结果不等于运行证明:脚本跑通只说明输入被正确处理,不代表 Bot 真实接入过广告平台。

第 3 条有明确的方法论依据。method.md 写明:门槛是用户的决定而非行业标准;花费、点击、转化、收入只能来自用户提供或明确读取的数据,缺失写未知、不估算;比率类指标样本太小时不报警;提醒与修改清单只是建议,改动由用户自己在广告平台完成。

模板的表格与四行结论,正是把这些原则变成了可核对的字段。

七列表头逐列解析

表格的列顺序并非随意排列,它和离线脚本输出的 evaluations 数组一一对应。对照 spend_ledger.py 里的评估对象结构,映射关系如下:

模板列 脚本字段 含义
规则 thresholdId 触发的门槛 id,如 t-daily-spend
对象 group 账户级为 ALL,广告系列级为系列名
窗口 window today / last3 / last7 / month
实际值 value 按窗口聚合后算出的指标值,可能为 null
限值 limit 用户设定的门槛数值
严重度 severity urgent / watch / note
状态 status OK / BREACH / NOT_COMPUTABLE / NO_DATA / SUPPRESSED_LOW_SAMPLE

规则与对象:门槛决定聚合粒度

门槛定义在输入 JSON 的 thresholds 中,字段必须恰好是 id scope metric direction limit window severity 七项,多一项少一项都会以退出码 2 结束。scope 只接受 account 或 campaign:

  • account:把窗口内所有行合并成一个组,group 固定为 ALL;
  • campaign:按 campaign 字段分组,每组单独评估。

因此同一份台账、同一条门槛,在不同 scope 下会产生不同数量的表行。脚本对分组结果按组名排序,保证输出稳定可复现。

窗口:以 asOf 为锚,而非机器时间

窗口语义在 spend_ledger.py 中实现:

窗口 判定条件 说明
today 日期 == asOf 只有当天
last3 asOf - date <= 2 当天 + 前两天,共 3 天
last7 asOf - date <= 6 当天 + 前六天,共 7 天
month 年月与 asOf 相同 自然月,不按 30 天滚动

两条容易踩错的细节:

  • 未来日期被排除:when > as_of 直接返回 false;
  • 不读机器当前时间:contract.md 明确"日期按 ISO 日历日,不读取机器当前时间;asOf 必须由本轮材料明确"。

这点在实践上很重要:用户周一来贴一份上周五导出的报表,asOf 应写 2026-10-15 这类"材料覆盖到的最后日期",而不是今天。否则 today 窗口会直接落空,产出 NO_DATA 而非"数据不足"的诚实结论。

实际值与限值:比率指标的算法

METRICS 共七项:spend、clicks、conversions、cpa、cpc、roas、ctr。其中后四项是比率,计算方式为:

指标 分子 / 分母
cpa spend / conversions
cpc spend / clicks
roas revenue / spend
ctr clicks / impressions

比率结果统一保留 4 位小数;分母为 0 时状态变为 NOT_COMPUTABLE,原因码 ZERO_DENOMINATOR;分子或分母为 null 时为 NOT_COMPUTABLE + UNKNOWN_INPUT。

聚合规则是关键:totals() 对五个基础字段求和,只要窗口内任一行该字段为 null,整组合计就是 null。这意味着"部分缺失"不会被当作"缺失行忽略",而会整体降级为未知。这正是模板里"实际值"列允许为空、并要求在结论中说明数据缺口的原因。

严重度:排序优先级

SEVERITY_RANK = {"urgent": 0, "watch": 1, "note": 2}。评估结果按 (严重度, thresholdId, group) 三元组升序排序,因此表行的天然顺序就是"紧急 → 关注 → 备注",与 SKILL.md 第 4 步"有越线时先说结论"一致。用户看到的第一行,应当就是最该处理的那条。

状态:五种取值与各自的含义

状态 触发条件 是否算越线
OK 已算出值且未越线 否
BREACH above 时 value > limit;below 时 value < limit 是
NOT_COMPUTABLE 缺输入或分母为 0 否,须说明原因
NO_DATA 窗口内无任何行(NO_ROWS_IN_WINDOW) 否,须说明缺口
SUPPRESSED_LOW_SAMPLE 比率指标样本量低于静默阈值 否,且不等于"没问题"

最后一行尤其容易误读。方法文档的原话是"比率类指标样本太小时不报警,这是为了避免噪声,不代表'没问题'"。quietFloor 默认值为 clicks: 100、conversions: 5、spend: 50,用户可改。判定逻辑只在 clicks、conversions、spend 三者中筛出"非 null 且低于阈值"的项,写进原因码,例如 BELOW_QUIET_FLOOR:clicks。注意静默只作用于比率指标,spend、clicks、conversions 这类绝对量指标照常判定。

用 spend_ledger.py 产出表行

模板里的数据不是在对话里"估"出来的。配套技能 ad-spend-watch-evidence 提供了只读的离线核算脚本,用法固定:

python3 scripts/spend_ledger.py < selected-input.json

脚本要求 Python 3.10+、只用标准库、只走 stdin/stdout、不访问网络与 Home、不写文件、不执行子进程;安装与打包过程也不会执行它。成功退出码 0,输入结构或引用错误退出码 2,错误信息以 INVALID_INPUT: ... 打到 stderr。

完整输入示例

input.json 给出了一份可直接运行的合成数据:

{
  "asOf": "2026-10-15",
  "quietFloor": { "clicks": 100, "conversions": 5, "spend": 50 },
  "thresholds": [
    { "id": "t-daily-spend", "scope": "campaign", "metric": "spend",
      "direction": "above", "limit": 200, "window": "today", "severity": "urgent" },
    { "id": "t-cpa-week", "scope": "campaign", "metric": "cpa",
      "direction": "above", "limit": 25, "window": "last7", "severity": "watch" },
    { "id": "t-roas-month", "scope": "account", "metric": "roas",
      "direction": "below", "limit": 2, "window": "month", "severity": "note" }
  ],
  "rows": [
    { "id": "r1", "date": "2026-10-15", "campaign": "合成-拉新",
      "spend": 260, "clicks": 300, "impressions": 9000, "conversions": 8, "revenue": 400 },
    { "id": "r2", "date": "2026-10-14", "campaign": "合成-拉新",
      "spend": 180, "clicks": 250, "impressions": 8000, "conversions": 12, "revenue": 700 },
    { "id": "r3", "date": "2026-10-15", "campaign": "合成-品牌词",
      "spend": 40, "clicks": 60, "impressions": 1200, "conversions": 3, "revenue": 150 },
    { "id": "r4", "date": "2026-10-13", "campaign": "合成-品牌词",
      "spend": 35, "clicks": 55, "impressions": 1100, "conversions": null, "revenue": null }
  ]
}

rows 的字段集合是固定的八个:id、date、campaign、spend、clicks、impressions、conversions、revenue。后五项可以是数字或 null,null 表示未知;null 不能改写成 0——脚本对负值也会拒绝。

实际输出与填表对照

在包目录下执行上述命令,得到的 evaluations 依次为:

  1. t-daily-spend / 合成-品牌词 / today / 40 / 200 / urgent / OK
  2. t-daily-spend / 合成-拉新 / today / 260 / 200 / urgent / BREACH
  3. t-cpa-week / 合成-品牌词 / last7 / null / 25 / watch / NOT_COMPUTABLE(UNKNOWN_INPUT)
  4. t-cpa-week / 合成-拉新 / last7 / 22.0 / 25 / watch / OK
  5. t-roas-month / ALL / month / null / 2 / note / NOT_COMPUTABLE(UNKNOWN_INPUT)

对应的交付表可以直接落笔为:

规则 对象 窗口 实际值 限值 严重度 状态
t-daily-spend 合成-拉新 today 260 200 urgent 越线
t-cpa-week 合成-品牌词 last7 未知 25 watch 无法计算
t-roas-month ALL month 未知 2 note 无法计算

注意第 4 行 cpa = 22.0 的算法:last7 窗口把 r1(260 花费 / 8 转化)与 r2(180 花费 / 12 转化)合并,得 440 / 20 = 22.0,而不是对两次单日 CPA 求平均。这是"按窗口先聚合再算比率"的直接体现,也是最常见的算错点。

脚本额外给出的三个字段

除表行外,脚本输出还包含模板四行结论所依赖的信息:

  • latestRowDate 与 daysBehindAsOf:最新台账日期,以及它与 asOf 相差的天数;
  • warnings:目前只有一种,DUPLICATE_DATE_CAMPAIGN,当同一天同一系列出现多行时给出涉及的行 id 列表;
  • zeroConversionSpendCampaigns:自然月内有花费但转化为 0 的系列名。

此外还有三个固定回显,防止结果被误用:estimatedValues: false、platformChangesMade: false、mode: "REPORT_ONLY"。

四行结论怎么写才不失真

最该改的一处

SKILL.md 第 4 步规定:"每条紧急项只给一处最该改的地方,写清具体怎么改,等用户点头。"模板里这一行只留了一个占位,但它的约束比表格更严:

  • 只针对紧急项,而不是把所有越线项都列一遍;
  • 一处,不是一份清单——需要多条建议时应拆成多次交互;
  • 具体可执行,并且停留在建议层:不暂停广告系列、不调预算、不登录广告平台。

结合上面的合成输出,"最该改的一处"应指向 合成-拉新 的当日花费(260 对 200),而 cpa 的"未知"不是改动建议,属于数据缺口,应放到下一行。

原因(观察/推断/未知)

这一行的三分类来自方法文档:观察来自台账,推断必须写依据,解释不了就写"原因未知"并列出需要的数据。

用合成数据说明:

原因(观察/推断/未知):观察——合成-拉新当日花费 260,超过 200;推断——该系列当天点击 300、转化 8,单次转化成本 32.5,高于近 7 日合计的 22.0(依据:r1、r2 汇总);未知——具体是出价、受众还是落地页导致,需账户内变更记录与分时段数据。

要点是三类不混写。"花费 260"是台账里的观察,"转化效率下降"是需要算术支撑的推断,"为什么下降"在没有账户侧数据时只能是未知。

数据截至

这一行不是客套话。脚本用 asOf 与 latestRowDate 做差得到 daysBehindAsOf,模板要求把差异写清楚。当数据落后于今天时,结论必须带"截至某日"的限定:

数据截至:2026-10-15(台账最新行日期;与 asOf 相差 0 天)

如果用户贴的是上周报表,正确写法是"数据截至 2026-10-10,落后 5 天",并说明因此 today 窗口无数据、结论只覆盖到该日期。绝不能用"目前花费正常"这种忽略时效的措辞。

待用户确认

模板最后一行对应的是权限与写入边界。SKILL.md 第 6 步规定:结果交付在 Cindy 对话里;用户要保存时才写到他指定的表格或本地文件,写入前先问位置;绝不暂停广告、不移动预算、不登录广告平台;提醒只在 Cindy 内送达。

因此这一行通常写成"是否把本次结果写入 XX 表格 / 是否调整某系列预算(由你在平台执行)"。三个例行任务(每日花费检查、午间花费检查、每周预算进度)默认关闭,定义里的 0 9 * * 1-5、0 12 * * 1-5、0 9 * * 1 只是 Etc/UTC 下的离线示例,必须在用户确认时区、时间、数据来源后才开启——这一点在 manifest.json 的 routines[].prompt 中逐条注明,且 enabledByDefault 均为 false,解析器会拒绝非 false 取值。

常见失真与排查

现象 根因 处理
窗口内全是 NO_DATA asOf 写成了机器当天,而台账是历史数据 按材料覆盖的最后日期重设 asOf
比率指标全变"未知" 窗口内存在含 null 的行,聚合整体降级 补齐缺失列,或缩小窗口到完整数据区间
明明样本很小却显示 OK 该指标是绝对量,静默规则只作用于比率 检查 quietFloor 与指标类型
同一天同一系列出现两条 导出文件重复或多次追加 看 warnings 的 DUPLICATE_DATE_CAMPAIGN,先合并再算
脚本退出码 2 字段多了/少了、id 重复、日期非法、超出 1 MiB 或 1 万行 按 INVALID_INPUT: 提示修正输入结构
把表格当成了平台操作记录 误读 REPORT_ONLY 回显 强调 platformChangesMade: false,改动由用户执行

其中"缺项保持未知"是最容易被 LLM 违背的一条。方法文档和输入契约都写明:缺失写未知、不估算、不补零;读不了的行要逐条点名。因为一旦用 0 填补缺失的转化数,cpa 会直接变成"无穷大"或触发零分母,整张表的严重度排序都会失真。

相关文件索引

模板只有八行,但它把"哪条规则越线、值是多少、为什么、数据到哪天、下一步谁来做"压缩成了机器可核对、人可读的结构。填对它,比写更多分析文字更有价值。

登录后查看全文
cindy