CocoContract 是 CocoPlus 中用于 Cortex 函数开发的契约工具,其核心目标是防御“自我预言问题”:当同一个智能体既生成函数、又依据自己编写的标准来评估该函数时,无论函数在真实世界中的行为如何,评估结果都会是自证式的、同义反复的。CocoContract 通过要求行为标准(即结果契约)在生成开始之前就存在,并且独立于生成上下文来编写,从而打破这一循环。
使用前需确认 .cocoplus/ 目录存在,否则应输出“CocoPlus is not initialized. Run $pod init first.”并停止。
主要命令包括:
$contract init [function-name]:引导开发者声明新的结果契约,包含角色(Persona)、可观察结果(Observable Result)、可证伪条件(Falsifiability Condition)和验收检查(Acceptance Checks)。角色必须来自 CocoPod 的八种角色之一(Cortex Architect、Data Engineer、ML Engineer、Analytics Engineer、Security Engineer、Data Scientist、DevOps Engineer、Business Analyst),拒绝泛化角色。可观察结果必须是特定角色在函数正确工作时能观察到的、可证伪的状态变化,使用非技术、非实现语言描述。可证伪条件是一个具体的失败测试。验收检查收集 2 至 5 项,至少一项必须是 e2e 类型,即使用真实数据运行真实 Cortex 端点或外部验证的等效方式。检查命令存储为参数数组,而非 shell 字符串。每个字段在接收前进行内联验证。完成的契约写入 outcomes/<function-name>/contract.md 并提交,该提交是 contract-gate 在允许 $spec 或 $build 继续之前检查的依据。
$contract check [function-name]:报告契约是否存在并已提交、当前证据层级和过期状态(源码哈希比较)、以及 $ship 资格(阻塞/合格)。
$contract prove [function-name] --tier <tier>:按认知强度从强到弱记录证据。e2e(Tier 1)针对真实 Cortex 端点执行,使用匹配角色上下文的真实输入,由人类或与生成器无共享会话上下文的机器检查确认可观察结果,是唯一满足 $ship 的层级。reference(Tier 2)将输出与外部来源的黄金数据集比较,该数据集不由生成智能体编写且早于会话,也满足 $ship。spec(Tier 3)依据外部声明的需求或标准验证。differential(Tier 4)证明比文档化的既有基线有可测量的改进。unit(Tier 5)依据同一会话中同一或共享上下文的智能体编写的标准评估,无论多彻底都不足以满足 $ship 认证,仅可作为开发上下文记录。调用 contract-prove 时记录证据到 contract-evidence.json,以函数当前源码哈希为键。提供 --check-command 时,$contract ci 仅重新执行已批准的参数向量命令,非零退出即失败。内联评估、shell 包装器、PowerShell、Bash 和未批准的二进制文件在执行前被拒绝。
流程阶段可声明 contract_tier: "light" | "standard" | "full" 来选择验证深度。light 包括 SQL 语法验证、列类型与模式检查、结果形状验证。standard 在 light 基础上增加 SQL lint、NULL 处理验证、同一快照上的确定性检查,为默认值。full 在 standard 基础上增加变异验证、记录行数和成本的真实执行、以及针对凭据、硬编码仓库和 ACCOUNTADMIN 假设的供应链检查。具有 allow_irreversible_actions: true 或 human_gate: true 的阶段默认使用 full,除非流程定义明确覆盖。
六条诚实规则是每次 CocoContract 评估的结构性要求:绝不削弱验证检查以使其通过;未验证不等于通过,无法运行的层记录 status: "SKIPPED" 并附原因,不能贡献 PASS 判定;失败关闭,must-find-nothing 检查仅在实际未找到任何内容时通过;在信任每个自定义检查前,用阴性对照证明其能失败;变异存活者在 full 层级契约中是阻塞性发现;在清单中逐项披露新的 Snowflake 对象依赖。
PASS 判定后,在 lifecycle/contracts/<function-name>/<timestamp>/evidence.md 写入面向操作者的证据工件,必须包含预期内容、已验证内容、已知未验证模式、确切入口命令和源码状态。操作者在生成前审查 SPEC,在验证后审查 evidence.md;SQL diff 不是主要审查界面。
$contract archive [function-name]:函数发布后,将当前契约和证据移入 outcomes/<function-name>/ 作为永久存档,包括 contract.md、evidence/(按层级的时间戳记录)、history.md(修订日志),并提交存档。如果存档中已存在 contract.md 且内容与当前工作契约不同,则视为行为修订:显示 diff,要求开发者明确确认修订,并在覆盖前追加到 history.md。绝不静默覆盖先前的行为承诺。
$contract ci:调用 contract-prove --ci,重新执行每个已存档契约中机器可执行的可证伪条件,按契约报告通过/失败,任何契约重新执行失败(行为回归)则非零退出。用于部署前 CI 门禁。
$contract status:列出 CocoPod 中所有活动契约及其证据层级和 $ship 资格。
$ship 门禁由 UserPromptSubmit 钩子调用 contract-gate,两个条件控制 $ship:证据存在,部署工件中每个函数必须在 contract-evidence.json 中至少有一条 Tier 1(e2e)或 Tier 2(reference)证据记录,Tier 3–5 证据视为无证据;证据未过期,证据以证明时的函数源码哈希为键,若源码已更改则证据过期并视为缺失。任一条件失败,$ship 返回阻塞消息,指明缺少或过期证据的函数及所需层级。没有覆盖标志和绕过机制,这是架构不变量,而非可配置策略。
退出标准包括:$contract init 仅在结果字段和 2–5 项验收检查通过内联验证后提交 outcomes/<name>/contract.md;$contract prove --tier e2e 记录绑定当前源码哈希的证据;$ship 在证据缺失时阻塞、过期时阻塞,仅在新鲜 Tier 1/2 证据下继续;$contract ci 重新运行记录的可执行检查命令,任何已存档契约回归则非零退出;不存在绕过证据层级或过期检查的代码路径;阶段 contract_tier 解析为 light、standard 或 full,不可逆和人工门控阶段默认 full;PASS 判定写入 lifecycle/contracts/<function-name>/<timestamp>/evidence.md;六条诚实规则防止 SKIPPED 层和变异存活者被报告为通过证据。
反合理化部分列出了常见诱惑及其错误原因,例如接受泛化角色、让 Tier 5 证据满足 $ship、添加 --force 或 --skip-contract 标志、静默覆盖契约、将过期证据视为有效、将 SKIPPED 验证视为可接受等。