Cindy 投放监控伙伴交付模板详解:delivery.md 的字段契约、取值规则与离线核对实践
Cindy 投放监控伙伴交付模板详解:delivery.md 的字段契约、取值规则与离线核对实践
在 Cindy 的 Bot 包体系中,ad-spend-watch(投放监控伙伴)把"给用户看什么"固化成了一份只有八行的交付模板:delivery.md。它看起来极简,却是整套监控流程的落点——前面所有"记账、套门槛、判状态"的计算,最终都要收敛成这张表和四行结论。本文以该模板为骨架,逐列拆解它背后可验证的字段来源,结合配套脚本 spend_ledger.py 与 SKILL.md 的操作规程,说明如何把一份投放报表正确落成这份交付物,以及哪些地方一旦写错就会失真。
模板原文与它在包中的位置
先看模板的实际内容,全文如下(即 delivery.md 的完整形态):
# 投放监控伙伴
| 规则 | 对象 | 窗口 | 实际值 | 限值 | 严重度 | 状态 |
|---|---|---|---|---|---|---|
最该改的一处:
原因(观察/推断/未知):
数据截至:
待用户确认:
它由两部分组成:一张七列的空表,和四行固定前缀的结论句。标题行 # 投放监控伙伴 是伙伴名称,与 manifest.json 中 profile.name 一致。
这份模板不是孤立文件,它被登记为该技能的 resources:
- 技能正文:skills/ad-spend-watch-ops/SKILL.md
- 模板文件:
skills/ad-spend-watch-ops/templates/delivery.md - 清单登记:manifest.json 中
skills[0].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运行。
这句简短的话定了三条硬边界:
- 格式固定:交付必须按模板的形状给出,而不是自由发挥成一段话;
- 认知状态必须标注:事实、推断、未知三类不允许混写在同一句里;
- 离线结果不等于运行证明:脚本跑通只说明输入被正确处理,不代表 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 依次为:
t-daily-spend/合成-品牌词/today/ 40 / 200 / urgent /OKt-daily-spend/合成-拉新/today/ 260 / 200 / urgent /BREACHt-cpa-week/合成-品牌词/last7/null/ 25 / watch /NOT_COMPUTABLE(UNKNOWN_INPUT)t-cpa-week/合成-拉新/last7/ 22.0 / 25 / watch /OKt-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 会直接变成"无穷大"或触发零分母,整张表的严重度排序都会失真。
相关文件索引
- 交付模板:delivery.md
- 操作规程:ad-spend-watch-ops/SKILL.md
- 离线核对技能:ad-spend-watch-evidence/SKILL.md
- 核算脚本:spend_ledger.py
- 输入契约:contract.md
- 输入示例:input.json
- 方法参考:method.md
- 开场设置:ad-spend-watch-getting-started/SKILL.md
- 包清单:manifest.json
- 内置包解析与校验:nativePackage.ts
- 包安装与邀请入口:host.ts
- 技能文件落盘与校验:botSkillStore.ts
- 包契约与设计边界说明:bot-market-native.md
模板只有八行,但它把"哪条规则越线、值是多少、为什么、数据到哪天、下一步谁来做"压缩成了机器可核对、人可读的结构。填对它,比写更多分析文字更有价值。