ckool-model-contract

AKOOL 模型配置契约的唯一真源:media_input_schema 类型定义、模型配置三层校验器、上传输入编译器。四端(landing / akool-admin-web / agi-content / management-backend)共用同一份实现——admin 保存时拦的、后端入库时拒的、前台渲染画的、预览显示的,物理上是同一个函数。

迁移说明(2026-08-11):本包由 landing/lib/model-contract/ 迁出。契约规范正文暂在 landing docs/image-to-video-input-schema.md;治理背景见 landing docs/technical-designs/2026-08-04-model-config-governance-plan.md。

API

import { validateModelConfig, compileInputPlan } from 'ckool-model-contract';

// 1. 配置写入闸门:结构 / 交叉引用 / 准入策略 三层校验
const { ok, errors, warnings } = validateModelConfig(doc, {
  requireMediaInputSchema: true,   // 新建契约家族模型必须带 schema(create 场景开)
  rejectLegacyFields: true,        // 拒收已废弃 legacy 字段
});
// errors: [{ severity, path, code, message }]

// 2. 输入编译器:(media_input_schema, params) → 上传框计划
const plan = compileInputPlan(schema, params /*, hints — 仅 landing 过渡期传 */);
// plan.slots: [{ id, role, mediaTypes, bindings: [{ param, maxItems, required }], maxCount }]

另导出全部契约类型(MediaInputSchema / MediaInputSlot / ParamsRule / ValidationIssue …)与常量(CONTRACT_MODEL_TYPES / LEGACY_DB_FIELDS …)。

机器可读 JSON Schema(admin Monaco 补全/红线用):

import mediaInputSchema from 'ckool-model-contract/json-schema/media-input-schema.schema.json';
import paramsRulesSchema from 'ckool-model-contract/json-schema/params-rules.schema.json';

消费方

| 仓库 | 用途 | |---|---| | landing | schema-plan.ts 渲染/提交/回填的编译入口;decode fail-closed | | akool-admin-web | 保存前校验(error 阻断)、Monaco Schema、表单实时预览(compileInputPlan) | | management-backend | aiModelConfig create/update/import 写入口服务端闸门 | | agi-content | 导入/回填脚本入库校验、validate:ai-model-config 全量体检、媒体总量校验中间件(CJS 用 dist/index.cjs) |

开发

npm install
npm test          # vitest,36 用例(契约文档 8 个标准示例做用例)
npm run build     # dist/:index.cjs + index.mjs + *.d.ts(esbuild + tsc)
npm run typecheck

零运行时依赖;prepublishOnly 强制先测试后构建。

发布与消费(过渡期说明)

• 发布:publishConfig.access: public,发公共 npm registry(npm publish 即可);也可用 git 依赖:"ckool-model-contract": "git+https://gitlab.akool.io/frontend/model-contract.git#v0.1.0";
• 过渡期:四个仓当前仍使用 vendored 副本(各带 VENDOR_MANIFEST.json + 漂移校验脚本)。切换到本包依赖前,vendored 副本继续以 landing 侧 scripts/vendor-model-contract.mjs 分发;切换后删除 vendored 目录与该脚本;
• 契约变更流程:改本仓 → 升版本(语义化:校验规则收紧 = minor,破坏性结构变更 = major)→ 各消费方升级依赖。校验错误码(code 字段)是对外契约的一部分,重命名视为破坏性变更。