skill-family-contracts 公共 API 参考¶
本页从真实导出(src/index.mjs 与各源模块)核对,不手写无法证明新鲜度的全集。每个公共入口按 hand-off §4.3 说明:签名、输入与输出、是否纯函数、文件/进程/Git/网络副作用、稳定错误码与 details.kind、前置条件与信任锚、since 与 stability、源文件与正例/负例测试、调用方仍拥有的业务语义。
能力分组(与 docs/agents/capability-catalog.json 对应):
- 对象校验 →
validateDocument/compileSchema/detectDialect - 公共专业结论 →
professional-conclusionSchema /validateDocument - 来源权威收据 →
validateSourceAuthorityReceipt/parseSourceAuthorityReceipt - 文件系统契约 → 根绑定与固定集合 manifest/receipt Schema
- 文件集合应用与恢复合同 → apply/recover/prune request、result、事件载荷与状态恢复观察 Schema
- 登记与协议 →
loadRegistry/findSchemaByObject/findProtocol/registerSchema/registerProtocol - 内核协议 →
loadKernelProtocol/findOperation/checkOperation - 强制检查 →
runChecks/collectUnresolvedRefs - fixture 校验 →
listFixtures/verifyFixture/verifyAllFixtures - 错误码 →
ContractsError/isRegisteredErrorCode/stableError - 审计表面 →
canonicalJson/digestDocument/digestAuditSurface - 工程基线 →
validateEngineeringBaseline/describeEngineeringBaseline - 同级适配器验证合同 → request/result Schema
- 真实宿主验证合同 → request/result Schema
- 完整插件验证合同 → request/result Schema
- 技能族目录验证合同 → request/result Schema
包级常量(冻结,仅作事实投影,不另立权威):CONTRACT_OBJECTS(当前本地合同源码为 56 类顶层对象,闭集)、CONTRACT_BOUNDARY、CONTRACTS_VERSION = "1.21.0"、SUPPORTED_DIALECTS、VALIDATION_POLICIES、CHECK_TYPES(9 类机械检查)、MANDATORY_RULES、RULE_BUDGET、ERROR_CODES。已发布 Foundation 0.21.0 仍对应 Contracts 1.18.0 与 46 类对象;本页 Windows 增量部分描述尚无发布坐标的本地实现。
对象校验 (foundation.contracts.object-validation)¶
validateDocument¶
- 签名:
validateDocument(document, { schemaId, schema, dialect, policy = "strict" } = {}) - 输入:任意 JSON 文档;目标契约对象
$id或 schema 对象;方言(draft-07/2020-12);策略(strict|tolerant)。 - 输出:始终返回
{valid, errorCode, errors, data};校验通过时valid=true,失败时valid=false并带稳定errorCode,不抛出(已实测:未知$id返回SFC1002,文档不符返回SFC1001)。data是校验使用的规范化副本。 - 纯函数:是。仅读取进程内 Ajv 编译缓存,不触外部资源。
- 副作用:无文件/Git/网络/进程副作用;首次编译写入内存编译缓存,后续同
(schemaId,dialect,policy)复用。 - 稳定错误码与
details.kind:SFC1002(未知$id)、SFC1001(文档不符 Schema)。两者均经返回值errorCode表达,调用方以valid字段判断成败,不以try/catch捕获。 - 前置条件与信任锚:待校验文档带已登记契约对象
$id;Node >= 22.22.2;校验器固定为 Ajv 8.20.0。 since/stability:0.2.0/stable。- 源文件:
packages/skill-family-contracts/src/validator.mjs。 - 正例测试:
packages/skill-family-contracts/test/validator.test.mjs、schemas.test.mjs、host-contracts.test.mjs、report-contracts.test.mjs。 - 负例测试:同上(未知
$id与不符 Schema 均返回valid:false)。 - 调用方仍拥有的业务语义:具体业务字段的语义解释、领域级校验规则。
compileSchema¶
- 签名:
compileSchema(target, { dialect, policy = "strict" } = {}) - 输入:schema 对象或
$id;方言;策略。 - 输出:编译后的 Ajv
validate函数;或抛ContractsError(SFC1012SCHEMA_COMPILE_FAILED,当 schema 自身无法在声明方言下编译)。 - 纯函数:是。
- 副作用:无外部副作用,仅写入编译缓存。
- 稳定错误码与
details.kind:SFC1012(Schema 编译失败,抛异常——与validateDocument的返回式失败不同)、SFC1006(不支持的方言;compileSchema抛出,validateDocument以返回值报告)。 - 前置条件与信任锚:Ajv 8.20.0 固定;
dialect属冻结支持集。 since/stability:0.2.0/stable。- 源文件:
packages/skill-family-contracts/src/validator.mjs。 - 正例/负例测试:同
validateDocument。 - 调用方仍拥有的业务语义:schema 的业务含义。
detectDialect¶
- 签名:
detectDialect(schema) - 输入:带
$schema字段的 schema 对象。 - 输出:方言字符串(
draft-07/2020-12);缺少或未知方言返回null。compileSchema对不支持的方言抛SFC1006,validateDocument对同一情况返回errorCode: "SFC1006"。 - 纯函数:是。
- 副作用:无。
- 稳定错误码与
details.kind:调用方直接调用detectDialect时未知方言不产生错误码;下游编译/校验分别按上述规则产生SFC1006。 - 前置条件与信任锚:方言集冻结(
SUPPORTED_DIALECTS)。 since/stability:0.2.0/stable。- 源文件:
packages/skill-family-contracts/src/validator.mjs。 - 正例/负例测试:同上。
- 调用方仍拥有的业务语义:方言选择策略(何时用 tolerant)。
公共专业结论 (professional-conclusion)¶
Contracts 1.20.0 已登记 professional-conclusion,当前本地源码继续沿用。其 Schema $id 为
https://contracts.skill-family.example/v1/professional-conclusion.json。它固定六个外层字段:
schemaVersion、kind、provider、subject、scope、outcome 与可选 details。其中
scope.checked 和 scope.limitations 说明真正完成的检查与限制;outcome.completion 只能是
complete、partial 或 not-performed。outcome.code 与 details 保持对专业方开放,
Contracts 不维护领域代码表,也不根据结构有效推断专业结果通过。
消费方应从专业入口的真实返回值取得显式路径,在自身授权的允许根内读取 JSON,再调用
findSchemaByObject("professional-conclusion") 与 validateDocument。校验是纯函数,不读取引用、
不发现结果文件,也不执行提供方或目标程序。检查范围与完成程度不相容、缺少公共字段、未知外层
字段或错误结构版本时返回 valid:false 与 SFC1001。
project-manifest 同期增加可选 engineering 声明。releaseUnits 每项声明独立的 text 或 JSON
版本来源和可选镜像;entries 每项声明名称、physicalRef 与普通文件形态。Schema 只校验结构与
安全的相对引用形状,不读取这些路径,不要求外部项目采用 Foundation 的仓库布局。
- 副作用:无文件、Git、网络或进程副作用;仅复用 Ajv 进程内编译缓存。
- 正例/负例:
packages/skill-family-contracts/test/report-contracts.test.mjs、schemas.test.mjs、fixtures.test.mjs与registry.test.mjs。 - 调用方仍拥有:提供方身份信任、领域 code 与详情解释、显式路径传递、根内读取授权,以及是否 接受或整改该专业结论。
来源权威收据 (foundation.contracts.source-authority)¶
validateSourceAuthorityReceipt / parseSourceAuthorityReceipt¶
- 签名:
validateSourceAuthorityReceipt(receipt);parseSourceAuthorityReceipt(receipt, actualSubjects)。 - 输入:闭合的外置 receipt,以及调用方实际观测的 subjects。每个 subject 只含
packageName、version、filename与sha256。 - 输出:两者均返回既有
{ valid, errorCode, errors, data }结果形态。解析成功时,data只含sourceRepository与sourceBaseCommit。 - 纯函数:是。输入会复制后校验,调用方对象不被修改。
- 副作用:无文件、进程、Git、网络或发布状态副作用。
- 稳定错误码:结构、排序、重复包名、实际 subjects 形状或逐字段核对失败均返回
SFC1001。 - 前置条件与信任锚:receipt subjects 至少一项,按
packageName唯一、升序排列;sourceBaseCommit是 40 位小写十六进制,SHA-256 是 64 位小写十六进制。调用方负责取得 receipt 与实际 subjects。 since/stability:0.8.4/stable。- 源文件:
packages/skill-family-contracts/src/source-authority.mjs、src/schemas/source-authority-receipt.schema.json。 - 正例/负例测试:
packages/skill-family-contracts/test/source-authority.test.mjs、source-authority-public-consumer.test.mjs。 - 调用方仍拥有的业务语义:receipt 的签发、存储和传输;实际包发现;校验后是否采用该来源。Contracts 不执行目标,也不解释私有发布计划。
文件系统契约 (foundation.contracts.filesystem)¶
0.9.0 新增三个稳定顶层 Schema:filesystem-root-binding、fixed-set-publication-manifest 与 fixed-set-publication-receipt。它们只描述结构与回执,不提供删除、替换或通用恢复状态机。
- 根绑定 Schema:
https://contracts.skill-family.example/v1/filesystem-root-binding.json。值固定为kind、digestAlgorithm、basis、digest四个字段;绑定值可序列化且不包含公开目录句柄。 - 固定集合 manifest/receipt Schema:
https://contracts.skill-family.example/v1/fixed-set-publication-manifest.json与https://contracts.skill-family.example/v1/fixed-set-publication-receipt.json。发布回执的终态只允许succeeded、refused、failed、indeterminate。 - 这三个 Schema 的真实登记与 fixture 由
packages/skill-family-contracts/src/registry.json、src/schemas/和test/共同核验;批量校验 Schema 保持 candidate,不进入稳定 Registry。
文件集合应用与恢复合同 (file-set apply/recovery)¶
Contracts 1.20.0 已登记六个顶层对象:file-set-apply-request、file-set-recovery-request、
file-set-prune-request、file-set-result、file-set-event-payload 与
state-store-recovery-observation。以下 POSIX v1 描述保留;Windows 分支见页末。六个 Schema 均为顶层封装,使用各自版本字段与
kind=skill-family.<对象名>,闭字段、未知字段拒绝;登记状态为 candidate,本地规格坐标
contractsVersion=1.21.0 尚无 registry 发布坐标。状态恢复观察对象由状态恢复合同单独定义,
不塞进文件业务 Schema 反向依赖。
- apply request:
operationId(调用方生成的 UUID v4 小写字符串,journal 内不复用)、root(规范绝对真实路径)、rootBinding(createFilesystemRootBinding返回的原对象)、固定recoveryRelPath=".foundation-file-apply"、 固定allowAdjacentStaging=true、environment={filesystem: "apfs"|"ext4", cooperativeWriters: true}、 1~2147483647 的validationTimeoutMs,以及 1~1024 条有序operations。每条含path、action=create|replace|delete、expected与next;替换的新模式必须等于原模式。 - 字节与摘要只在 JS 调用参数中绑定,不进机器 JSON Schema:
sha256为 64 位小写十六进制,size按原始字节计数,bytes接受 Buffer 或 Uint8Array(调用开始即复制,SharedArrayBuffer 及其视图拒绝);mode为0000~0777的 POSIX 整数,且要求目标属于执行用户、owner-read 位置位且不被进程 umask 屏蔽。 1024 条与新旧字节合计 256 MiB 是首轮容量上限,超限在任何业务写入前拒绝。 - recover / prune request 共有
schemaVersion、operationId、root、rootBinding、recoveryRelPath与environment。recover 必填maintenance={observation, confirmAllParticipantsStopped:true, confirmExclusiveMaintenance:true},并要求allowAdjacentStaging:true;prune 在无残留时不需要maintenance,只有故障接管才要求同一观察,不能自动升级成恢复。完整观察由调用方在排他维护区间内对<root>/.foundation-file-apply/journal调用inspectStateStoreLock(journalRoot, { recoveryObservation: true })取得,observation.root必须等于该 journal 目录,默认诊断结果不是有效观察;获取方式见docs/reference/api/harness.md。 - result 固定包含
schemaVersion、operationId、operation、outcome、preflight、businessWrite、validation、recovery、paths、errors与materials。outcome封闭为committed|commit-unconfirmed|rejected|rolled-back|recovery-required|already-committed|already-rolled-back|pruned|already-pruned;materials={relPath, status:none|retained|partial|pruned, durable, adjacentStaging:none-observed|possible-unknown};paths按请求顺序给出每项的apply/restore/current与errorKinds。错误复用SFC2004外码, 闭枚举details.kind与details.phase(input|preflight|prepare|apply|validate|restore|finalize|prune)。 - 事件载荷使用一个闭 union Schema,
eventType固定前缀file-set.、payloadSchemaVersion固定 1; 封装、顺序、摘要链与写者代次沿用 state-store,不另立第二套序号、摘要链或身份账本。 - 纯函数:Schema 校验与登记查询是纯函数,无文件、进程、Git 或网络副作用;Contracts 不执行应用、恢复或清理。
- 前置条件与信任锚:合同只描述结构与稳定枚举;
bytes的真实性、根绑定、维护区间、领域判定 (validate返回的{passed})与接受决定均由调用方与 Harness 机制承担。 - 源文件:
packages/skill-family-contracts/src/schemas/file-set-*.schema.json、state-store-recovery-observation.schema.json与src/registry.json。 - 正例/负例测试:
packages/skill-family-contracts/test/file-set-contract.test.mjs、schemas.test.mjs。 - 调用方仍拥有的业务语义:领域 code 与详情、显式路径传递、根内读取授权、维护区间的建立与确认, 以及接受或整改本次文件集合结果。
登记与协议 (foundation.contracts.registry-protocol)¶
loadRegistry / listSchemas / listProtocols / findSchemaRegistration / findSchemaByObject / findProtocol¶
- 签名:
loadRegistry()listSchemas(registry = REGISTRY)listProtocols(registry = REGISTRY)findSchemaRegistration(schemaId, registry = REGISTRY)findSchemaByObject(object, registry = REGISTRY)findProtocol(name, version, registry = REGISTRY)- 输入:对象名、
$id、协议名/版本(其余默认读冻结REGISTRY)。 - 输出:已登记 schema 元信息或协议定义;未命中返回
null。 - 纯函数:是。
- 副作用:无。
- 稳定错误码与
details.kind:登记类冲突经registerSchema/registerProtocol抛SFC1003(DUPLICATE_SCHEMA_ID)/SFC1004(DUPLICATE_PROTOCOL_NAME)。 - 前置条件与信任锚:当前本地
registry.json的schemaVersion=1、contractsVersion=1.21.0;登记表含 56 类 Schema 与 1 个 Kernel Protocol,新增需 ADR。正式发布前不能把本地坐标当作 registry 可用版本。 since/stability:0.2.0/stable。- 源文件:
packages/skill-family-contracts/src/registry.mjs、registry.json。 - 正例/负例测试:
packages/skill-family-contracts/test/registry.test.mjs。 - 调用方仍拥有的业务语义:对象业务含义的解释。
registerSchema / registerProtocol¶
- 签名:
registerSchema(entry, registry = REGISTRY)registerProtocol(entry, registry = REGISTRY)- 输入:schema/protocol 登记项。
- 输出:包含新登记项的 registry 新副本;输入 registry 与默认冻结
REGISTRY均不修改。重复$id/协议名抛ContractsError。 - 纯函数:是(仅返回复制后的内存对象)。
- 副作用:无文件、进程、Git、网络或持久化副作用。
- 稳定错误码与
details.kind:SFC1003(重复$id)、SFC1004(重复协议名)。 - 前置条件与信任锚:当前本地登记表含 56 类 Schema 与 1 个 Kernel Protocol,新增需 ADR。
since/stability:0.2.0/stable。- 源文件:同上。
- 正例/负例测试:同上。
- 调用方仍拥有的业务语义:登记项的业务理由。
内核协议 (foundation.contracts.kernel-protocol)¶
loadKernelProtocol / findOperation / checkOperation¶
- 签名:
loadKernelProtocol()findOperation(name, kernel = KERNEL)checkOperation(operation, params)- 输入:协议名、操作名、操作参数。
- 输出:协议定义或操作参数校验结果;失败时抛
ContractsError。 - 纯函数:是(加载为只读解析,无外部副作用)。
- 副作用:无。
- 稳定错误码与
details.kind:SFC2002(UNKNOWN_OPERATION,操作名不在冻结词汇)、SFC2003(INVALID_PARAMS,参数违反操作参数契约)。 - 前置条件与信任锚:
kernel-protocol.json随包发布;内核协议版本与 Contracts 版本绑定。 since/stability:0.2.0/stable。- 源文件:
packages/skill-family-contracts/src/kernel.mjs、kernel-protocol.json。 - 正例/负例测试:
packages/skill-family-contracts/test/kernel.test.mjs。 - 调用方仍拥有的业务语义:操作的具体业务语义(状态机/重试/终态转
loop-agent)。
强制检查 (foundation.contracts.mandatory-checks)¶
runChecks / collectUnresolvedRefs¶
- 签名:
runChecks({ schemaEntries, ... } = {})collectUnresolvedRefs(schemaEntries)- 输入:待检查契约集或合成 registry/fixtures。
- 输出:检查结论与未解析引用清单;违反规则抛
ContractsError。 - 纯函数:是。
- 副作用:无。
- 稳定错误码与
details.kind:SFC1002/1003/1004/1005/1006/1008/1009/1010对应各规则 violated;SFC1005(UNRESOLVED_REF)、SFC1008(RULE_BUDGET_EXCEEDED)、SFC1010(FIXTURE_EXPECTATION_MISMATCH)。 - 前置条件与信任锚:registry 与 rules 已加载;
CHECK_TYPES为 9 类闭集;RULE_BUDGET限制firstVersionMax与absoluteMax。 since/stability:0.2.0/stable。- 源文件:
packages/skill-family-contracts/src/checker.mjs、rules.json。 - 正例/负例测试:
packages/skill-family-contracts/test/checker.test.mjs。 - 调用方仍拥有的业务语义:规则业务理由的解释(语义接受/拒绝属外部独立审阅)。
fixture 校验 (foundation.contracts.fixture-verification)¶
listFixtures / fixtureClasses / verifyFixture / verifyAllFixtures¶
- 签名:
listFixtures()fixtureClasses()verifyFixture(fixture)verifyAllFixtures()- 输入:fixture 类或单个 fixture 标识。
- 输出:逐 fixture 的校验结果(正例须通过、负例须以声明稳定码失败)。
- 纯函数:是(只读 fixture 目录)。
- 副作用:只读访问 fixture,无写。
- 稳定错误码与
details.kind:SFC1010(FIXTURE_EXPECTATION_MISMATCH,负例未产生预期失败);SFC1009(UNKNOWN_ERROR_CODE,fixture 引用未登记码)。 - 前置条件与信任锚:fixtures 目录为公开或完全虚构数据;fixture 与审计器预期结果不共享。
since/stability:0.2.0/stable。- 源文件:
packages/skill-family-contracts/src/fixtures.mjs。 - 正例/负例测试:
packages/skill-family-contracts/test/fixtures.test.mjs。 - 调用方仍拥有的业务语义:fixture 背后的业务意图(fixture 只证结构、不证语义)。
错误码 (foundation.contracts.error-codes)¶
ContractsError / errorCodeRegistry / errorCodeInfo / isRegisteredErrorCode / assertRegisteredErrorCode / stableError¶
- 签名:
class ContractsError extends Error(构造(code, message, details))errorCodeRegistry()errorCodeInfo(code)isRegisteredErrorCode(code)assertRegisteredErrorCode(code)stableError(code, message, details)- 输入:错误码字符串、错误上下文。
- 输出:带稳定错误码与
details的错误对象;assertRegisteredErrorCode对未登记码抛TypeError。 - 纯函数:是(
ContractsError构造为纯对象,无外部副作用)。 - 副作用:无。
- 稳定错误码与
details.kind:错误码体系本身冻结(error-codes.json),新增码属 Contracts 变更;SFC1009用于未登记码断言。 - 前置条件与信任锚:
error-codes.json随包发布;冻结对象不可变。 since/stability:0.2.0/stable。- 源文件:
packages/skill-family-contracts/src/errors.mjs、error-codes.json。 - 正例/负例测试:
packages/skill-family-contracts/test/boundary.test.mjs、immutability.test.mjs、audit-surface.test.mjs。 - 调用方仍拥有的业务语义:错误码的业务归因。
Contracts 错误码一览(稳定、append-only):
| 码 | 名称 | 类别 |
|---|---|---|
| SFC1001 | SCHEMA_VALIDATION_FAILED | contract |
| SFC1002 | UNKNOWN_SCHEMA_ID | contract |
| SFC1003 | DUPLICATE_SCHEMA_ID | contract |
| SFC1004 | DUPLICATE_PROTOCOL_NAME | contract |
| SFC1005 | UNRESOLVED_REF | contract |
| SFC1006 | UNSUPPORTED_DIALECT | contract |
| SFC1007 | UNKNOWN_CHECK_TYPE | contract |
| SFC1008 | RULE_BUDGET_EXCEEDED | contract |
| SFC1009 | UNKNOWN_ERROR_CODE | contract |
| SFC1010 | FIXTURE_EXPECTATION_MISMATCH | contract |
| SFC1011 | UNKNOWN_PROTOCOL | contract |
| SFC1012 | SCHEMA_COMPILE_FAILED | contract |
| SFC1013 | CONSUMER_CONTRACT_VERSION_MISMATCH | contract |
| SFC2002 | UNKNOWN_OPERATION | kernel |
| SFC2003 | INVALID_PARAMS | kernel |
| SFC2004 | EXECUTION_FAILED | kernel(机制失败统一码,承载 details.kind) |
| SFC3001 | REPORT_DIGEST_MISMATCH | report |
| SFC3002 | REPORT_ELEMENT_MISSING | report |
| SFC3003 | REPORT_FACT_DRIFT | report |
审计表面 (foundation.contracts.audit-surface)¶
canonicalJson / digestDocument / describeAuditSurface / digestAuditSurface¶
- 签名:
canonicalJson(value)digestDocument(value, { algorithm = "sha256" } = {})describeAuditSurface()digestAuditSurface(surface = describeAuditSurface())- 输入:任意 JSON 文档。
- 输出:canonical 字符串与 sha256 摘要;审计表面结构描述与其摘要。
- 纯函数:是。
- 副作用:无。
- 稳定错误码与
details.kind:非 JSON 值、未知算法(AUDIT_DIGEST_ALGORITHMS仅sha256)、冻结违规抛ContractsError。 - 前置条件与信任锚:
AUDIT_SURFACE_VERSION=1;摘要算法仅sha256;依赖方向 Audit → Contracts,本模块不反向导入审计产物。 since/stability:0.2.0/stable。- 源文件:
packages/skill-family-contracts/src/audit-surface.mjs。 - 正例/负例测试:
packages/skill-family-contracts/test/audit-surface.test.mjs。 - 调用方仍拥有的业务语义:审计语义结论(接受/拒绝属外部独立审阅)。
工程基线 (foundation.contracts.engineering-baseline)¶
validateEngineeringBaseline / describeEngineeringBaseline¶
- 签名:
validateEngineeringBaseline(baseline);describeEngineeringBaseline({ provider, id, version, canonicalRuleRefs, referenceImplementation })。 - 输入:闭合的
skill-family.engineering-baseline文档,或构造该文档所需的提供方身份、已排序规则谱系引用和 Foundation 参考骨架身份。referenceImplementation只含foundationVersion、profile与skeletonDigest。 - 输出:校验入口返回既有
{ valid, errorCode, errors, data }结果;构造入口按规则 ID 排序、计算去掉digest字段后的规范 JSON 摘要,并返回深度冻结的文档。 - 纯函数:是。只复用 Contracts 的 Schema 校验、惰性 JSON 预检、
digestDocument()与进程内编译缓存。 - 副作用:无文件、进程、Git 或网络副作用;不读取基线提供方的包、仓库或规则文件。
- 稳定错误码与
details.kind:结构、重复规则 ID、非确定性顺序或摘要不一致返回或抛出SFC1001;未知 Schema 仍按通用校验规则返回SFC1002。 - 前置条件与信任锚:Schema
$id为https://contracts.skill-family.example/v1/engineering-baseline.json;canonicalRuleRefs至少一项,按id唯一且升序;digest必须绑定文档自身。 since/stability:0.17.0/stable。- 源文件:
packages/skill-family-contracts/src/engineering-baseline.mjs、src/schemas/engineering-baseline.schema.json。 - 正例/负例测试:
packages/skill-family-contracts/test/engineering-baseline.test.mjs、schemas.test.mjs。 - 调用方仍拥有的业务语义:基线提供方负责规则正文、规则效果、等价关系、豁免和正式基线发布。Foundation 不解释这些语义,也不宣称 Audit 已经发布正式基线;依赖方向保持为基线提供方依赖 Foundation。
同级适配器验证合同 (foundation.contracts.peer-adapter-verification)¶
Contracts 1.10.0 登记 adapter-peer-verification-request 与
adapter-peer-verification-result 两个稳定 Schema。request 至少包含两个显式 peer;每个 peer
携带闭集 hostId、路径类别和完整 logicalMappings。result 固定为 verified 与
peer-verification,并携带共同来源闭包、每个 peer 的标准 manifest 和 mapping。
这两个合同只描述业务中立的只读验证,不拥有 canonical source、目录写入、迁移、receipt、重试或生命周期状态。 peer 顺序不得改变共同闭包摘要或结论;未知字段、重复/缺失/悬空 mapping 和无法由真实目录证明的输入必须失败关闭。
since/stability:0.10.0/stable。- Schema 文件:
packages/skill-family-contracts/src/schemas/adapter-peer-verification-request.schema.json、adapter-peer-verification-result.schema.json。 - 正例/负例测试:
packages/skill-family-harness-node/test/peer-adapter.test.mjs、packages/skill-family-engineering-kit/test/host.test.mjs。 - 调用方仍拥有的业务语义:peer 的 canonical 选择、旧 manifest 迁移解释、消费者 smoke 和发布后验证。
真实宿主验证合同 (foundation.contracts.host-verification)¶
Contracts 1.11.0 登记 host-verification-request 与 host-verification-result。两个 Schema 的 $id、
operation=host-verification 和四态结果身份从首版固定,但该能力当前是 candidate,不能据此宣称宿主、领域结果或发布已通过。
- request 把共同候选绑定与每宿主 binding 分开;所有
*Sha256与*ClosureDigest均为 64 位小写十六进制。调用方必须从私有 roots 严格重算这些值,不能把自报摘要当作证明。auth固定为existing-user-state + host-managed,只说明复用用户现有 登录状态;execution.modelOverridePolicy固定为forbidden。 - result 只允许
observed、rejected、failed、indeterminate。它不含 credential、绝对路径、环境变量、Prompt、原始 stream 或 durable receipt;observed只表示基础设施观察完整,不表示消费者领域 PASS。requiredActions只允许manual-temporary-root-inspection-required。 - request auth 必须精确对应已登记 Descriptor 的单值
driverId/authStrategy/credentialMutation;Descriptor 是认证组合的 唯一事实源。Schema 分别绑定kimi-code → kimi-code-print-v1、workbuddy → workbuddy-codebuddy-print-v1、codebuddy → codebuddy-print-v1、claude → claude-code-print-v1、codex → codex-exec-v1与qoder → qodercli-print-v1,CodeBuddy 与 WorkBuddy 的路由不可互换。 Schema 不提供通用 driver Registry 或认证 SPI。 since/stability:0.11.0/candidate。Schema 文件:packages/skill-family-contracts/src/schemas/host-verification-request.schema.json、packages/skill-family-contracts/src/schemas/host-verification-result.schema.json。正反例:packages/skill-family-contracts/test/schemas.test.mjs。- 调用方仍拥有的业务语义:candidate 解引用、workload、领域输出、发布新鲜度、领域 PASS/FAIL 与发布决定。
完整插件验证合同 (foundation.contracts.plugin-verification)¶
Contracts 1.15.0 在保留 install-only 与 install-and-invoke 两个既有 goal 的同时,增加 native-lifecycle 分支。request 只描述闭合的宿主、来源、认证、载荷与工作负载摘要,不携带 runner、parser、预制 observation 或自由 hostState。
原生命周期 result 的 facts.lifecycle.stages 恰好按以下顺序包含十二项:preflight、validate-v1、marketplace-add、install-v1、discover-v1、invoke-v1、disable、enable、update-v2、invoke-v2、uninstall、absent-after-uninstall。Contracts 只检查闭字段、阶段顺序、局部结构与停止传播;首个非 observed 阶段之后,后续阶段只能为 not-performed,且 commands 与 trees 为空。
Schema 不固定跨宿主统一命令数或 argv 计划,不根据 command step、退出码、自然语言或 marker 解释厂商语义,也不拥有 Qoder/WorkBuddy Oracle。每个宿主的命令计划、tree evidence 选择与 raw stream 判定由 Engineering Kit 的专属 driver 负责。
since/stability:既有合同自0.13.0/candidate;native-lifecycle分支自0.15.0。- Schema 文件:
packages/skill-family-contracts/src/schemas/plugin-verification-request.schema.json、plugin-verification-result.schema.json。 - 正例/负例测试:
packages/skill-family-contracts/test/foundation-015-contracts.test.mjs、schemas.test.mjs。 - 调用方仍拥有的业务语义:来源接受、领域结果、发布新鲜度、真实宿主资格与发布决定。
技能族目录验证合同 (foundation.contracts.skill-family-directory-verification)¶
Contracts 1.15.0 登记 Kimi 专用的 skill-family-directory request/result。request 绑定 hostId=kimi-code、固定 driver/CLI 身份、技能族树摘要、预期技能来源摘要与工作负载摘要;它不接收 caller observation、runner、parser 结论或 plugin lifecycle 字段。
result 保持既有四态,逐技能事实只能明确写为 observed、absent 或 unknown。缺少可验证的官方 typed observation 映射时,允许 status=indeterminate、reason=official-observation-unavailable,逐技能 discovery/load 为 unknown,call/result id 为 null。Schema 不从 raw marker 猜测厂商语义。
进程启动、固定 --skills-dir argv、窄环境、原始流收集与 parser 属 Engineering Kit。Contracts 只验证闭合结构和局部一致性,不把 Foundation 自有受控 fixture 协议登记成 Kimi 官方 grammar。
since/stability:0.15.0/candidate。- Schema 文件:
packages/skill-family-contracts/src/schemas/skill-family-directory-verification-request.schema.json、skill-family-directory-verification-result.schema.json。 - 正例/负例测试:
packages/skill-family-contracts/test/foundation-015-contracts.test.mjs。 - 调用方仍拥有的业务语义:技能族来源接受、领域输出、真实宿主资格与发布决定。
能力成熟度与历史迁移政策¶
包根导出 CAPABILITY_MATURITY_LEVELS、CANDIDATE_PROMOTION_POLICY、
HISTORICAL_CANDIDATE_MIGRATION_POLICY,以及两个返回结构化副本的 describe*Policy()。它们不读取文件、不写状态,
也不替消费者执行迁移。政策固定历史入口只迁移一次;新能力采用规范身份后,candidate→stable 不再改变消费者合同。
消费者要取得新发布的 stable 承诺仍需更新三包精确 pin;受管投影是否重建沿用既有绑定输入合同。
since / stability:0.10.0 / stable。源文件:packages/skill-family-contracts/src/stability.mjs。正反例测试:
packages/skill-family-contracts/test/candidate-promotion-compatibility.test.mjs。
Quickstart Profile v2 candidate¶
规范入口 skill-family-contracts/quickstart-profile 导出 v2 协议、按规范 $id 索引的 Resource/Task/Result Schema 集合,
以及 validateQuickstartProfileDocument。历史入口 skill-family-contracts/candidate/quickstart-profile 在弃用窗口内解析到
同一模块,现有消费者应迁移一次。唯一 operation 是业务中立的 execute-method;Foundation 不登记 method 词表,
也不解释 parameters、evidence 或 domainResult 的领域含义。
0.10.0 把 Quickstart 六个历史 Schema 身份和 0.9.0 的两个 batch Schema 身份一次迁移到不含 /candidate/ 的规范
$id。HISTORICAL_CANDIDATE_SCHEMA_ID_MIGRATIONS 固定八项旧 ID→规范 ID;loader 只返回规范 Schema。Quickstart
Bundle 让旧新 ID 指向同一编译 validator,不复制 Schema,也不登记进 stable Registry。两个 batch Schema 仍只供
validate-many-by-schema-id 使用;未知 schemaId 或任一结构畸形都使整批请求失败。
该能力从 0.2.1 起公开,稳定性仍为 candidate。0.3.0 已用 v2 替换 v1,两者不兼容:仍需 v1 的接入继续精确
锁定 0.2.1;v2 新接入应使用 0.10.0 规范入口并精确锁定三包。candidate Schema 不进入稳定 src/registry.json。
主动升级候选版本仍需复验;以后仅晋升 stable 时不再切入口或 Schema 身份。取得 stable 发布承诺仍需更新三包精确 pin。
消费方契约测试向量 (Foundation 0.14.0)¶
listConsumerContractVectors({ capabilityId, foundationVersion, vectorSetId? }) 返回按
vectorId 的 Unicode 码点顺序排列且深度冻结的公开向量。capabilityId 和
foundationVersion 必填;未找到匹配向量时返回空数组。
verifyConsumerContractVector(vector, { capabilityId, foundationVersion, vectorSetId? })
只核对向量身份、精确版本和公开 request/expected 结构,返回
{ vectorId, ok, expected, observed, mismatchCode }。身份或版本不匹配时
ok=false、mismatchCode=SFC1013;校验器不会调用消费方、Harness、测试替身(fake)或宿主。
0.14.0 提供 foundation.contracts.object-validation.consumer-v1 与
foundation.harness.atomic-write.consumer-v1 两组向量。向量声明的是合同可观察结果;
原子写正例的 valueRelation 由 Harness 与消费方测试验证,Contracts 不解释该关系。
与机器事实层的互链¶
- 能力稳定 ID 见
docs/agents/capability-catalog.json(foundation.contracts.*)。 - 机械校验:
scripts/docs/capability-catalog-check.mjs解析src/index.mjs,拒绝引用不存在的入口;sourceRefs与测试引用均指向本页所列真实文件。
Windows 合同分支¶
Foundation 0.28.0 的 Windows 合同分支适用于 Windows 11 x64、本地 NTFS 文件系统及普通用户环境,采用 Contracts 规格 1.21.0,共 56 个登记对象,其中 fixed-set-generation-pointer、fixed-set-generation-result 与 fixed-set-generation-resolution 为 schemaVersion=1 的候选对象,其余对象成熟度按原登记保持不变。该版本的合同规范与注册状态不构成对真实宿主资格的证明,真实宿主业务资格仍需由 driver、版本、认证与业务证据共同确认。
filesystem-root-binding 保持四字段结构,不新增 schemaVersion,Windows 分支的 basis 为 canonical-finalpath-volume-fileid-type-security-v1,表示基于路径规范化、卷序列号、文件 ID、文件类型与安全描述符摘要的唯一身份。路径处理遵循 Windows 原生语义,包括大写盘符、正斜杠分隔、不转小写、不处理符号链接目标,权限信息由原生句柄提供,不通过 mode 或 statMode 传递。
filesystem-tree-observation 与 executable-identity-observation 在 Windows 平台使用 schemaVersion=2,启用 Windows 身份与权限分支,已有 statMode 位置显式为 null,权限信息通过 permissionObservation 字段记录。嵌套解释器观察必须符合相同平台分支,混入 POSIX 观察结构的实例无法通过 Schema 校验。
file-set-apply-request、file-set-recovery-request、file-set-prune-request、file-set-event-payload 与 state-store-recovery-observation 在 Windows 分支均使用 schemaVersion=2;其中三个请求声明 environment.filesystem=ntfs,事件载荷和恢复观察按各自 Schema 承载 Windows 事实,不新增 environment 字段。POSIX 平台的 v1 合同保留,不进行兼容性降级或伪造,file-set-result 结果合同不因平台变更而伪造版本。
watchdog-termination-envelope 在 Windows 平台使用 schemaVersion=2,证据基于 Job Object,不包含 processGroupId 字段,与 POSIX 分支保持逻辑隔离。fixed-set-generation-pointer、fixed-set-generation-result 与 fixed-set-generation-resolution 为新增 schemaVersion=1 的候选对象,共享同一 registry 登记,规范 $id 为 https://contracts.skill-family.example/v1/<对象名>.json,结构校验不证明原生执行、还原能力、普通用户资格或宿主业务通过。所有合同版本与字段定义均以注册登记为准,远端可用性须由正式发布凭据核实;源码版本、单项测试或安装成功不能替代完整平台验证、真实宿主业务核验或发布凭据。官方 npm 包 skill-family-contracts@0.27.1 对应 Contracts 1.20.0、53 个对象,其历史合同不因本次新版本改变。