Cindy proto-bot 验收证据核对:输入契约、acceptance_check.py 校验规则与离线核对实践

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

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,因此在安装和导入时是作为一个整体被搬运的(下文「包内安装与完整性约束」一节会展开)。

输入契约精读:字段形状与声明纪律

契约文档的正文很短,但每一句都是一个约束。把它拆成规则清单:

  1. 字段形状见 input.json:契约本身不重复列字段,字段的唯一权威形状是示例文件。
  2. 状态、来源与许可都是显式声明:脚本不会去推断「大概通过了吧」,输入里没有写 PASS 就视为没有通过。
  3. 脚本不核实远端内容:evidence 里写的是什么就记什么,既不下载也不打开。
  4. null 表示未知:未知必须显式表达,不能靠省略字段来暗示。
  5. 不允许重复 id,不允许未声明字段:这两条由脚本硬性执行,违反即退出码 2。
  6. 具体输出与负例记录在交付根 validation 中:脚本输出只是中间结果,最终要落到交付目录的 validation 记录里。
  7. 日期按 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)

这里有两个非常实际的结论:

  1. 跨 head 的证据一律不算数。 我实测过一条 head: "old" 的 PASS 记录,在 head: "h" 的输入下仍被报为 a:LIGHT 缺失。这与 proto-bot-ops 中「旧 head 截图不通过」的要求完全一致。
  2. 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 截图不通过,脚本通过不能代替真实浏览器/设备目检。

这句话包含三个层次的责任划分,值得在评审时逐条对照:

  1. 对齐:脚本负责「有没有」——每个验收项 × 每个必需模式是否都有当前 head 的证据。
  2. 版本一致:只有与 head 相等的证据参与判定,这条在实现里就是 r["head"] == head 的严格比较。
  3. 不可替代性:脚本通过 ≠ 人看过。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。它在包内被登记为普通资源文件,导入后不带可执行位;调用方需要自己提供解释器。

一次完整核对的推荐步骤

  1. 确定 head:取本轮真实构建/提交的标识,填入 head。不要复用上一轮的值。
  2. 列验收项:每条给出可观察的描述与必需模式。深浅色都要验的,就写 ["LIGHT","DARK"];若某条只接受跨主题统一证据,写 ["ANY"] 并保证证据也是 ANY。
  3. 逐条填证据:status 只允许三态;尚未运行的写 NOT_RUN 而不是省略——省略会让该验收项整体缺记录。
  4. 本地运行:python3 scripts/acceptance_check.py < 你的输入.json。先看退出码:2 说明结构与引用有错,按 stderr 修输入;0 再看 JSON。
  5. 读结果:missingOrNotRun 是「还差什么」,failed 是「已经不行了」,status 只是聚合结论。别把 REVIEWABLE 读成「可以发布」。
  6. 落交付记录:把输出与本次遇到的负例一起写入交付根 validation,在交付表中同步「未验状态」与真实截图的操作路径。
  7. 人工目检:脚本只核对覆盖度。主题、排序、保存、连接是否真实发生,仍需在真实浏览器或设备上确认,截图必须属于最终版本。

边界声明

最后重申这个技能刻意不做的三件事,避免把它当成超出能力的凭证:

  • 不渲染页面:它不会启动应用、不会截图、不会打开 evidence 里的地址。
  • 不证明目检:note 字段每次输出都会带上这句话,status: REVIEWABLE 仅表示「证据覆盖完整,值得人看」。
  • 不是凭证或授权:输出不构成测试通过证明、连接真实性证明或发布许可,published 恒为 false。

在这三条边界之内,contract.md 定义的那套「显式声明 + 严格字段集 + 唯一 id + 当前 head」纪律,配合一个不到百行、只用标准库的脚本,足以把「验收证据有没有齐」从口头讨论变成可复现的命令行输出。

登录后查看全文
cindy