Cindy proto-bot 验收证据核对:输入契约、acceptance_check.py 校验规则与离线核对实践
Cindy proto-bot 验收证据核对:输入契约、acceptance_check.py 校验规则与离线核对实践
Cindy 内置的「原型开发伙伴」(proto-bot 0.5.1)在交付界面原型时,要求每个验收项在当前版本、每种主题模式下都有可追溯的证据。proto-bot-evidence 技能把这件事做成了一次可复现的离线检查:你提供一个结构化的 JSON 输入,脚本只做覆盖度核对,输出哪些验收项缺证据、哪些已失败。本文以该技能的输入契约文档 contract.md 为骨架,结合它的示例输入、实现脚本和包加载代码,把字段语义、校验规则、退出码、输出判定以及它与交付流程的衔接讲清楚,读者可以据此独立完成一次证据核对并正确解读结果。
技能定位:三个文件构成的一条离线检查链
proto-bot-evidence 不是一个渲染器,也不是截图工具。它的自述非常克制:核对验收项与主题模式的证据覆盖,不渲染页面、不证明目检(见 SKILL.md)。整个技能由三个文件组成:
| 文件 | 角色 | 说明 |
|---|---|---|
| templates/contract.md | 契约说明 | 定义输入语义、显式声明原则、禁用行为与输出位置 |
| templates/input.json | 字段形状示例 | 一份合成的、可直接运行的输入样例 |
| scripts/acceptance_check.py | 校验实现 | 只用 Python 3.10+ 标准库,从 stdin 读、向 stdout 写 |
三者被 manifest.json 登记为同一个 skill 的 bodyPath、scripts 与 resources,因此在安装和导入时是作为一个整体被搬运的(下文「包内安装与完整性约束」一节会展开)。
输入契约精读:字段形状与声明纪律
契约文档的正文很短,但每一句都是一个约束。把它拆成规则清单:
- 字段形状见
input.json:契约本身不重复列字段,字段的唯一权威形状是示例文件。 - 状态、来源与许可都是显式声明:脚本不会去推断「大概通过了吧」,输入里没有写
PASS就视为没有通过。 - 脚本不核实远端内容:
evidence里写的是什么就记什么,既不下载也不打开。 null表示未知:未知必须显式表达,不能靠省略字段来暗示。- 不允许重复 id,不允许未声明字段:这两条由脚本硬性执行,违反即退出码 2。
- 具体输出与负例记录在交付根
validation中:脚本输出只是中间结果,最终要落到交付目录的validation记录里。 - 日期按 ISO 日历日,不读取机器当前时间;
asOf必须由本轮材料明确给出。
字段一览
结合示例文件,输入是一个三字段的对象:
| 字段 | 类型 | 约束(来自示例与脚本) |
|---|---|---|
head |
非空字符串 | 本轮检查对应的版本标识(通常是 commit/head);首尾空白会被去除 |
criteria[] |
数组,≤10000 项 | 验收项;每项恰好三个字段:id、description、modes |
criteria[].id |
非空字符串 | 在 criteria 内唯一;被 checks[].criterion 引用 |
criteria[].description |
非空字符串 | 可观察的验收标准描述 |
criteria[].modes |
非空数组 | 取值只能是 LIGHT / DARK / ANY,且不得重复 |
checks[] |
数组,≤10000 项 | 证据记录;每项恰好六个字段 |
checks[].id |
非空字符串 | 在 checks 内唯一 |
checks[].criterion |
字符串 | 必须指向已声明的验收项 id,否则视为输入错误 |
checks[].head |
非空字符串 | 该条证据所属版本;只有与本轮 head 相等时才参与判定 |
checks[].mode |
枚举 | LIGHT / DARK / ANY |
checks[].status |
枚举 | PASS / FAIL / NOT_RUN |
checks[].evidence |
非空字符串 | 证据引用(脚本不解析其内容) |
完整示例:一份「差一条证据」的输入
仓库自带的示例输入刻意构造了「浅色有证据、深色未运行」的局面:
{
"head": "synthetic-head-a",
"criteria": [
{
"id": "save",
"description": "合成保存状态显示",
"modes": ["LIGHT", "DARK"]
}
],
"checks": [
{
"id": "light",
"criterion": "save",
"head": "synthetic-head-a",
"mode": "LIGHT",
"status": "PASS",
"evidence": "synthetic://light-reference-only"
},
{
"id": "dark",
"criterion": "save",
"head": "synthetic-head-a",
"mode": "DARK",
"status": "NOT_RUN",
"evidence": "synthetic://not-run"
}
]
}
在技能目录下运行(README 与 SKILL.md 给出的标准调用方式):
python3 scripts/acceptance_check.py < templates/input.json
实测输出:
{"failed": [], "head": "synthetic-head-a", "missingOrNotRun": ["save:DARK"], "note": "Evidence references are not executed or visually verified.", "published": false, "status": "INCOMPLETE"}
注意 NOT_RUN 与「完全没有记录」在当前实现中归入同一个桶:missingOrNotRun。这是设计上的简化——对判定而言,它们等价于「还不能算通过」。
运行方式与硬边界
脚本头部注释已经把运行环境写死:Original offline helper; Python 3.10+ standard library, stdin/stdout only.(acceptance_check.py)。具体边界如下:
- 输入通道:只有 stdin。脚本读取
sys.stdin.buffer.read(1048577),即最多读 1 MiB + 1 字节,随后校验len(raw) <= 1048576(#L76-L77)。超限直接判为输入非法。 - 输出通道:只有 stdout,一次性打印一行 JSON;错误信息走 stderr(#L80-L83)。
- 依赖:
sys、json、math、hashlib、datetime.date、urllib.parse全部是标准库,无第三方依赖。 - 不访问网络、不读 Home、不写文件、不执行子进程:SKILL.md 明确声明,脚本实现中也确实没有任何 IO 或
subprocess调用。 - 安装与打包不会执行它:它只是一个随包分发的资源文件,导入流程只做文件级校验(见后文)。
- 规模上限:每个数组最多 10000 条(
items(),#L22-L24)。 - 退出码:
0表示结构合法(即使语义上不完整),2表示输入结构或引用错误(#L81-L83)。
这三条「静默约束」值得单独记住:结构错误是硬失败(退出码 2,只有 stderr),语义缺口是软失败(退出码 0,缺口体现在输出字段)。SKILL.md 的原话是「成功 exit 0,输入结构/引用错误 exit 2;语义缺口在输出字段中保持可见」。
校验实现逐条拆解
严格字段集:多一个字段就是非法
def record(value, fields):
require(isinstance(value, dict) and set(value) == set(fields.split()), "unexpected or missing fields")
return value
set(...) == set(...) 是全等比较,因此「未声明字段」与「缺失字段」报同一条错误。根对象必须恰好是 head criteria checks(#L50),每条 check 必须恰好是 id criterion head mode status evidence(#L55),每个 criterion 必须恰好是 id description modes(#L62)。
这条规则直接解释了契约里「不允许……未声明字段」的一句:它不是文风要求,而是可以在第一次运行时就撞上的 2 号退出码。
唯一性与文本规范化
def indexed(value):
result = {}
for row in items(value):
key = text(row.get("id"))
require(key not in result, "duplicate id: " + key)
result[key] = row
return result
indexed()(#L26-L33)同时完成三件事:限制数组长度、要求元素是对象、以 id 建索引并检测重复。text()(#L18-L20)要求非空字符串并 strip()——所以 " save " 会被当作 save,而 " " 会直接失败。注意:strip() 只作用于 id 与其余文本字段的返回值,不影响你在 evidence 里写的原始 URL 语义,脚本不解析它。
枚举与引用完整性
require(row["criterion"] in criteria, "unknown acceptance criterion")
require(row["mode"] in ("LIGHT", "DARK", "ANY"), "invalid mode")
require(row["status"] in ("PASS", "FAIL", "NOT_RUN"), "invalid check status")
(#L56-L58)这意味着:证据不能凭空指向一个不存在的验收项。只要有一条 check 引用了未声明的 criterion,整份输入就作废,退出码 2——而不是被静默忽略。这是「显式声明」原则在代码层面的落地。
验收项一侧还有一条容易踩的规则(#L65):
require(modes and len(modes) == len(set(modes)) and all(m in ("LIGHT", "DARK", "ANY") for m in modes), "invalid required modes")
modes 不能为空、不能重复(["LIGHT","LIGHT"] 非法),且只能取三个枚举值。
匹配语义:head 必须相等,ANY 不等于「随便哪个」
核心循环只有六行(#L66-L69):
for mode in modes:
current = [r for r in checks.values() if r["criterion"] == key and r["mode"] == mode and r["head"] == head]
if any(r["status"] == "FAIL" for r in current): failed.append(key + ":" + mode)
elif not any(r["status"] == "PASS" for r in current): missing.append(key + ":" + mode)
这里有两个非常实际的结论:
- 跨 head 的证据一律不算数。 我实测过一条
head: "old"的PASS记录,在head: "h"的输入下仍被报为a:LIGHT缺失。这与proto-bot-ops中「旧 head 截图不通过」的要求完全一致。 mode: "ANY"的证据不会满足LIGHT或DARK的要求。 因为过滤条件是r["mode"] == mode的严格相等,ANY只匹配ANY。实测:modes: ["LIGHT"]+ 一条mode: "ANY"的PASS,输出仍是missingOrNotRun: ["a:LIGHT"]。反过来说,如果你的验收项本身声明modes: ["ANY"],那就必须提供一条ANY证据;此时一条FAIL会进入failed。
同一模式下若同时存在 PASS 与 FAIL,FAIL 优先进入 failed 列表(if 分支先判断)。这在评审语境下是保守且正确的取向:矛盾的证据不该被「有一条通过」掩盖。
状态判定与固定字段
return {"head": head, "missingOrNotRun": missing, "failed": failed,
"status": "REVIEWABLE" if criteria and not missing and not failed else "INCOMPLETE",
"published": False, "note": "Evidence references are not executed or visually verified."}
(#L70-L72)输出恒为五个键:
| 输出字段 | 含义 |
|---|---|
head |
回显本轮检查的版本标识 |
missingOrNotRun |
形如 criterion:mode 的缺口列表,按 criterion id 排序生成(因为遍历 sorted(criteria.items())) |
failed |
明确失败的 criterion:mode 列表 |
status |
REVIEWABLE 或 INCOMPLETE |
published |
恒为 false |
note |
固定英文提示:证据引用未被实际执行或目检 |
status 的判定条件值得注意:criteria 为空时结果为 INCOMPLETE(实测 {"head":"h","criteria":[],"checks":[]} 返回 status: "INCOMPLETE",退出码仍为 0)。也就是说,空清单不能伪装成「全部通过」,但也不会报错——它只是永远不可评审。
published: false 与固定 note 是防止误读的两道锁:脚本永远不会宣称证据已被发布或已被目检,任何自动化流水线若想拿 status: REVIEWABLE 当作发布许可,就会缺少 published 这一环。
负例、错误信息与退出码
下列行为均已在本仓库的技能目录下实测确认,可直接作为排障对照表:
| 场景 | 退出码 | stderr 信息 |
|---|---|---|
输入合法但缺证据(NOT_RUN) |
0 | 无;status: INCOMPLETE |
全部验收项均有 PASS |
0 | 无;status: REVIEWABLE |
criteria 为空数组 |
0 | 无;status: INCOMPLETE |
同一数组内 id 重复 |
2 | INVALID_INPUT: duplicate id: a |
| criterion/check 多出或缺少字段 | 2 | INVALID_INPUT: unexpected or missing fields |
criterion 指向未声明的验收项 |
2 | INVALID_INPUT: unknown acceptance criterion |
非法 mode 或 status |
2 | INVALID_INPUT: invalid mode / invalid check status |
| JSON 内重复键 | 2 | INVALID_INPUT: duplicate JSON key |
非有限数值(NaN/Infinity) |
2 | INVALID_INPUT: nonfinite JSON |
| 输入超过 1 MiB | 2 | INVALID_INPUT: input exceeds 1 MiB |
重复键的检测来自 json.loads(..., object_pairs_hook=unique_object)(#L42-L47、#L78-L79):Python 默认会「后者覆盖前者」,这里改成显式拒绝,避免同一份输入在不同工具链下解析出不同结果。非有限数值同样通过 parse_constant 拦截(#L79)。
关于 asOf 与 ISO 日期:契约要求与当前脚本的差异
契约明确要求「日期按 ISO 日历日,不读取机器当前时间;asOf 必须由本轮材料明确」。但当前脚本的根对象字段集是严格全等的 head criteria checks(#L50),把 asOf 放在根对象上会直接触发 unexpected or missing fields 并退出 2(已实测)。同时脚本里确实定义了一个 ISO 日期解析器:
def day(value):
return date.fromisoformat(text(value))
(#L35-L36)但它在 compute() 中没有任何调用点;number()(#L38-L40)同样处于未使用状态。从源码结构看,这两个辅助函数是为更完整的字段集预留的,尚未接入当前校验路径。
实践结论有两条:
- 在本轮交付记录中,
asOf应由你人工写入交付材料(例如交付表头或validation记录),而不是塞进 stdin 的 JSON;脚本不会替你记录检查时间,也不会读机器时钟,这一点反而符合契约「日期不由机器决定」的意图。 - 如果你确实希望在输入中携带日期,需要修改脚本——但仓库是只读的,本文只描述现状,不建议把
asOf直接加进现有输入文件,否则templates/input.json这类示例会立刻变成非法输入。
与原型交付流程的衔接
acceptance_check.py 不是孤立工具,它在 proto-bot-ops 的操作序列中被明确规定为第 5 步(SKILL.md):
用
acceptance_check.py把当前 head 的验收标准与各模式证据对齐。旧 head 截图不通过,脚本通过不能代替真实浏览器/设备目检。
这句话包含三个层次的责任划分,值得在评审时逐条对照:
- 对齐:脚本负责「有没有」——每个验收项 × 每个必需模式是否都有当前 head 的证据。
- 版本一致:只有与
head相等的证据参与判定,这条在实现里就是r["head"] == head的严格比较。 - 不可替代性:脚本通过 ≠ 人看过。
note字段每次都会重申这一点,SKILL.md 也写明「具体输出与负例记录在交付根 validation 中」。
交付时使用的表格模板见 templates/delivery.md,其列结构与输入契约一一对应:
| 交付表列 | 对应输入字段 |
|---|---|
验收id |
criteria[].id |
可观察标准 |
criteria[].description |
模式 |
criteria[].modes[] |
当前证据 |
checks[].evidence |
结果 |
checks[].status |
模板还要求填写「当前 head/内容 hash」「实现/稿件区分」「未验状态」,以及一句默认未授权的「分享/发布授权:未获得则不执行」。这与输出里恒为 false 的 published 相互印证:核对通过不等于获得发布许可。
方法层面的原则写在 knowledge/method.md:界面交付至少区分设计稿、可运行实现和已集成产品;静态截图不能证明排序、保存和连接真实发生;主题验证用 LIGHT/DARK 独立记录,未验不能靠「复用了 token」算通过。这段话正好解释了为什么 modes 是独立枚举而不是一个笼统的「已适配主题」布尔值。
包内安装与完整性约束
这个脚本是随桌面端打包分发的内置 Bot 包资源,不是用户目录里随意摆放的脚本。相关约束可以在两处源码中确认:
- 包根定位:host.ts 中
packageRoot()在打包态取process.resourcesPath,开发态取app.getAppPath()/resources,再拼接bot-packages。 - 包读取与校验:nativePackage.ts 定义了
BOT_PACKAGE_IDS白名单、BOT_PACKAGE_VERSION = '0.5.1',以及单文件 2 MiB、总计 16 MiB、最多 200 个文件的体积约束;manifest.schemaVersion、packageId、packageVersion必须匹配,integrity.files中的 SHA-256 必须覆盖除 manifest 自身之外的每个文件。 - skill 子树一致性:
bodyPath、scripts、resources三者拼起来必须与该 skill 目录下的全部文件完全一致(同一段代码还校验 slug 形如[a-z0-9][a-z0-9-]*、bodyPath必须等于skills/<slug>/SKILL.md,且所有引用都以该前缀开头)。 - 资源以非可执行方式保存:导入时构造的资源对象固定为
executable: false(#L178),随后交给 validateBotSkillFiles 做路径穿越与入口文件校验;SKILL.md正文上限 64 KiB(BOT_SKILL_MAX_BODY_BYTES)。
这解释了一个常见疑惑:为什么脚本放在 scripts/ 下却需要显式用 python3 调用,而不是直接 ./acceptance_check.py。它在包内被登记为普通资源文件,导入后不带可执行位;调用方需要自己提供解释器。
一次完整核对的推荐步骤
- 确定 head:取本轮真实构建/提交的标识,填入
head。不要复用上一轮的值。 - 列验收项:每条给出可观察的描述与必需模式。深浅色都要验的,就写
["LIGHT","DARK"];若某条只接受跨主题统一证据,写["ANY"]并保证证据也是ANY。 - 逐条填证据:
status只允许三态;尚未运行的写NOT_RUN而不是省略——省略会让该验收项整体缺记录。 - 本地运行:
python3 scripts/acceptance_check.py < 你的输入.json。先看退出码:2说明结构与引用有错,按 stderr 修输入;0再看 JSON。 - 读结果:
missingOrNotRun是「还差什么」,failed是「已经不行了」,status只是聚合结论。别把REVIEWABLE读成「可以发布」。 - 落交付记录:把输出与本次遇到的负例一起写入交付根
validation,在交付表中同步「未验状态」与真实截图的操作路径。 - 人工目检:脚本只核对覆盖度。主题、排序、保存、连接是否真实发生,仍需在真实浏览器或设备上确认,截图必须属于最终版本。
边界声明
最后重申这个技能刻意不做的三件事,避免把它当成超出能力的凭证:
- 不渲染页面:它不会启动应用、不会截图、不会打开
evidence里的地址。 - 不证明目检:
note字段每次输出都会带上这句话,status: REVIEWABLE仅表示「证据覆盖完整,值得人看」。 - 不是凭证或授权:输出不构成测试通过证明、连接真实性证明或发布许可,
published恒为false。
在这三条边界之内,contract.md 定义的那套「显式声明 + 严格字段集 + 唯一 id + 当前 head」纪律,配合一个不到百行、只用标准库的脚本,足以把「验收证据有没有齐」从口头讨论变成可复现的命令行输出。