yoyoboot admin contracts

需要判断权限、动作、API 客户端及 validation linkage 是否同步时，调用各正式 owner 的检查。结果保留每项状态与复核命令，严格模式要求全部一致。

基本用法

yoyoboot admin contracts status [--check] [--json]

在 YoyoBoot 源码仓库中运行

实际运行五类 owner 检查；运行前准备对应开发依赖。

pnpm --dir tools/yoyoboot-cli run cli -- admin contracts status --json

参数

参数	必填	说明
status	是	只读检查五类契约同步状态。
--json	否	以 JSON 输出完整结果信封，供机器读取。
--help	否	展示帮助；yoyoboot --help / yoyoboot <command> --help。
--repo <path>	否	显式指定仓库查找起点；缺省从当前工作目录向上查找。
--check	否	布尔选项，不接受取值。

示例

固定示例仓库中的返回结果

yoyoboot admin contracts status --json

此命令针对固定示例仓库。下面只展示公开字段投影，不是当前 checkout 的完整输出。

{
  "command": "contracts status",
  "status": "warn",
  "data": {
    "kind": "contracts-status",
    "checks": {
      "capability": {
        "status": "current"
      },
      "actionContracts": {
        "status": "current"
      },
      "apiGenerated": {
        "status": "current"
      },
      "validationLinkage": {
        "status": "current"
      },
      "liveOpenApi": {
        "status": "unavailable"
      }
    }
  }
}

返回结果

五类正式 owner 检查的同步状态。

主要字段

字段	说明
command	实际结果命令名；Admin 保留子命令名，入口捕获异常时为 cli。
status	ok / warn / error；同时检查退出码及诊断码。warn 可以退出 0。
findings[]	诊断项包含 code、status、message，可选 detail；机器使用 code 分支，不解析消息。
source	JSON 顶层命令实现来源，包含 kind / path / owner。
data	命令结果；入口捕获失败时可能缺省，部分诊断失败仍保留结果。
data.kind	固定为 contracts-status。
data.checks	包含 capability、actionContracts、apiGenerated、validationLinkage、liveOpenApi。
data.checks.<name>.status	current / stale / unavailable / error。
data.checks.<name>.owner	该检查的正式执行 owner。
data.checks.<name>.command	可单独复核的命令字符串。
data.checks.<name>.message	人类诊断说明，不作为状态判定协议。

使用说明

• 仓库根使用 pnpm --dir tools/yoyoboot-cli run cli -- <命令参数>；已完成构建时也可使用 node tools/yoyoboot-cli/dist/bin.js <命令参数>。
• JSON 示例来自固定示例仓库的公开投影，省略实现来源、规则文件位置及大段内容；<...> 是明确的环境占位符。完整字段见返回结果表，实际内容以当前工作树为准。
• 全局参数严格解析：未知、重复、缺值参数返回退出码 2；--help 输出文本，即使同时指定 --json。
• 此结果没有独立的 data.schemaVersion；不要把来源 catalog 版本或 Reference metadata 版本当成结果版本。
• 调用正式 owner checks，可能发生 .NET 构建及进程执行；不修改正式合同、不启动后端、不执行数据库迁移。
• 未设置 YOYO_ADMIN_OPENAPI_URL 时 liveOpenApi 为 unavailable。普通状态查询可 warn、退出 0；--check 要求全部 current，否则退出 2并保留 data。
• owner 退出码 0=一致、3=漂移；live 检查的 4=来源不可用，其余非零为 error。一个检查失败不会阻止其它检查。
• contracts refresh 尚未实现。

退出码

Exit code	含义
0	成功或仅有警告；警告仍需阅读。
2	预期失败：参数、仓库或领域条件不满足，或严格检查未通过。
1	未预期程序错误。

常见错误

unsupported-contracts-command

不是唯一的 status 子命令或有多余参数。

处理方式：使用 admin contracts status。

contracts-dry-run-unsupported

诊断不接受 --dry-run。

处理方式：移除 --dry-run；诊断本身不刷新合同。

contracts-not-current

--check 严格模式下并非全部 current。

处理方式：按返回的 owner 命令检查，使用正式生成入口刷新漂移合同。

相关命令

• yoyoboot admin doctor

• yoyoboot repo verify-plan

• Reference 合同版本：1.0.0

• 结果合同版本：未独立版本化（实际结果没有 data.schemaVersion）

• 源码产品版本：10.5.7（不代表 registry 发布状态）。