skill-family-engineering-kit 公共 API 参考¶
本页从真实导出(src/index.mjs 与各源模块、CLI 入口)核对,不手写无法证明新鲜度的全集。每个公共入口按 hand-off §4.3 说明:签名、输入与输出、是否纯函数、文件/进程/Git/网络副作用、稳定错误码与 details.kind、前置条件与信任锚、since 与 stability、源文件与正例/负例测试、调用方仍拥有的业务语义。
Kit 消费 Contracts 与 Harness,只拥有四个顶层命令与它们的只读/受控写边界。包级常量:TOP_LEVEL_COMMANDS(冻结 4 个:scaffold / adopt-plan / projection / check)、FORBIDDEN_SIDE_EFFECTS、COMMAND_SIDE_EFFECTS、KIT_EXIT_CODES(ok=0 / findings=1 / rejected=2)。Kit 永不执行 Git 写、发布或删除用户内容。
本页的 declared 政策与专业结论输出描述当前工作树中的未发布实现,不属于已发布的 0.21.0 制品。0.21.0 的已发布 API 与本地候选边界以当前产品状态为准。
Foundation 本身不发起网络请求,但绑定的 executable 仍可能联网。Foundation 不提供 sandbox 或 egress 阻断;隔离责任由调用方与运行环境承担。仓内受控 fixture 按设计不发起网络请求。
外置 source authority 不增加 Kit API。调用方先用 Contracts parseSourceAuthorityReceipt(receipt, actualSubjects) 核对收据,再把成功结果中的 sourceRepository 与 sourceBaseCommit 传给既有 Quickstart builder。Kit 不读取私有发布 plan,不发现实际包,也不签发 receipt。
provider Profile descriptor 使用 Contracts 1.16.0 时,须把自身的 base.contractsVersion 字段更新为 1.16.0。
Kit 仍只有四个顶层命令;Quickstart Bundle 继续是 candidate 精确版本,并在同一 mechanisms CLI 中提供有序
validate-many-by-schema-id。
能力分组(与 docs/agents/capability-catalog.json 对应):
- scaffold →
scaffoldTarget/describeSkeletonReferenceImplementation - adopt-plan →
planAdoption/evaluateMigrationCompletion/ 按需启用的工程基线结构比较 - projection →
buildProjectionClosure/runProjection/loadProjectionManifest - check →
runChecks/runCoreCheck - report →
renderReportAction/checkReportAction - git-probe →
probeGitState/probeGitFacts - host →
describeHost/resolveHostId/probeHost/planHost/applyHostPlan… - 完整插件验证 →
runPluginVerification - 技能族目录验证 →
runSkillFamilyDirectoryVerification - 显式资格入口 →
runQualification - licensing →
loadLicensingProfile/generateLicenseContent… - identity-check →
checkIdentityDrift/validateIdentityAgainstProfile - CLI →
runCommand/cliMain
scaffold (foundation.kit.scaffold)¶
scaffoldTarget / describeSkeletonFiles / describeSkeletonReferenceImplementation / normalizeSkeletonInputs¶
- 签名:
scaffoldTarget({ root, projectId, projectName, profileId, licensingProfile, licensingVariant, licensingProfileData, profilesRoot, identityProjections, engineering, capabilities = [] } = {})(async)describeSkeletonFiles(inputs)(async)describeSkeletonReferenceImplementation({ profile })(async)normalizeSkeletonInputs({ projectId, projectName, profileId, licensingProfile, licensingVariant, rootBasename })- 输入:目标根、骨架选项(
projectId等)及可选engineering。该参数属于本地0.24.0候选,正式0.23.0不支持;省略(undefined)保持原字节、文件集合与路径不变,null、空对象{}、未知字段或非法引用均拒绝。describeSkeletonFiles(inputs)与scaffoldTarget同源消费inputs.engineering。 - 工程声明沿用 Contracts 项目清单结构:
entries每项为name、form、physicalRef,form只接受skill_md或file,前者须指向SKILL.md。releaseUnits每项为id、versionSource,可选versionMirrors;文本引用使用path与format: "text",JSON 引用另需format: "json"与非空jsonPointer。依据真实业务入口和版本源声明,不取工程示例包、SDK 或 Profile 版本,也不从package.json推导 npm 分发。 - 输出:精确集合的托管骨架文件(原子 + 路径收容)。
scaffoldTarget()的结果另含referenceImplementation,字段固定为当前foundationVersion、所选profile与由规范文件清单计算的skeletonDigest。该身份用于比较,不表示 Audit 合规,也不要求存量项目逐字节复制参考骨架。骨架含两个目标侧手写种子(handwritten类,adopt 永不覆写):SOURCE-OF-TRUTH.md(唯一声明点、真源清单与生成谱系、运行与证据目录约定)与profile.json(foundation_profile/foundation_pin采用字段加只收紧方向的 overrides 示例);.gitignore/.projenrc.js/ file-registry 三处同步携带根级唯一忽略基线/site/、/.qoder/、/.artifacts/、/.runs/、/.evidence/(嵌套同名目录不被忽略)。 - 纯函数:
normalizeSkeletonInputs是;describeSkeletonReferenceImplementation只读取包内许可证 Profile 并确定性计算身份;scaffoldTarget落盘。 - 副作用:在受收容目标创建文件(原子 + 收容);目标非空则拒绝、不覆盖。
- 稳定错误码与
details.kind:非法 kebabprojectId/ 非空目标抛KitError(KIT_ERROR_KINDS的invalid-params/rejected);非法参数+ INVALID_PARAMS(SFC2003)。 - 前置条件与信任锚:目标为可写空目录;Node >= 22.22.2;骨架集合与
scaffold-conformancefixture 一致(33 个计划文件)。 since/stability:既有骨架入口自0.2.0/stable;describeSkeletonReferenceImplementation与 scaffold 结果中的参考身份自0.17.0/stable。- 源文件:
packages/skill-family-engineering-kit/src/scaffold.mjs、skeleton.mjs。 - 正例/负例测试:
packages/skill-family-engineering-kit/test/scaffold.test.mjs、skeleton-contract.test.mjs。 - 初始生成边界:声明与清单摘要由同一骨架生成器写入项目清单与原受管锁,不增加文件集合。空目标仅检查合同与根内路径形态,允许声明业务作者稍后创建的文件;不确认引用已存在,不代写领域内容。真实源落盘后再做 declared 检查。Schema 允许仅声明
entries或releaseUnits,但缺失的另一 declared 分支仍为incomplete;省略整个对象不表示声明完成。 - 调用方仍拥有的业务语义:业务项目内容、真实入口与版本来源、事实不足的报告(存量仓改用
adopt-plan)。
adopt-plan (foundation.kit.adopt-plan)¶
planAdoption / buildProfileDraft / evaluateMigrationCompletion / validateException / assessLegacyExitList / findNestedRepositories¶
- 签名(节选):
planAdoption({ root, projectId, projectName, profileId, licensingProfile, licensingVariant, licensingProfileData, profilesRoot, identityProjections, engineering, engineeringBaseline, compareSkeleton, allowGitSpawn = true, now = Date.now() } = {})(async)buildProfileDraft({ inputs, migrationManifest, writeSet, entries })evaluateMigrationCompletion({ ... })validateException(exception, index, nowMs)assessLegacyExitList(root, legacyItems)(async)findNestedRepositories(entries)- 输入:目标根、骨架选项与可选工程声明。
engineering为可选对象,属于本地0.24.0候选,正式0.23.0不支持;省略保持旧行为,传入null、空对象{}、未知字段或非法引用均拒绝。它调用同源的describeSkeletonFiles,预测与scaffold相同的声明字节,输入合同见本页 scaffold 节。工程基线比较是独立的按需功能;库调用必须同时传入已验证的engineeringBaseline与compareSkeleton: true,CLI 必须成对使用--engineering-baseline <relative-json-path>与--compare-skeleton。 - 输出:默认仍返回采用分类(
direct-adoption/compatibility-layer/keep-business/foundation-gap)、完成判定、profile 草稿(kind=skill-family.profile-draft:预填 D-8 最小采用声明 + 空 overrides 示例,仅输出,不落盘;adoption-lock 形态已废弃)。显式启用比较时才增加engineeringBaselineComparison:它包含基线身份、Foundation 参考身份,以及参考侧独有、目标侧独有、条目类型和文件类别四类结构差异;不输出合规、等价、严重程度、finding、action、waiver 或 exemption 结论,也不返回规则正文。 - 纯函数:分类与评估函数为纯函数;
planAdoption含只读探测。 - 副作用:严格只读——不写文件(临时文件也不写)、不 Git 写、不 rename、不触网;默认可能启动一条冻结参数的只读 Git 探测,传入
allowGitSpawn: false可关闭该子进程。 - 稳定错误码与
details.kind:例外缺字段 / 未退出旧实现则完成判定false;无效或未成对的比较参数使用SFC2003,无效基线合同使用SFC1001,基线中的 Foundation 版本或参考骨架摘要与当前 Kit 不一致时使用SFC1013。 - 前置条件与信任锚:目标仓存在且可只读访问;
MIGRATION_MANIFEST_PATH/MIGRATION_MANIFEST_SCHEMA_ID指向契约。比较前由 Contracts 验证基线,Kit 只接受绑定当前 Foundation 版本与参考骨架摘要的文档。 since/stability:既有采用规划自0.2.0/stable;工程基线结构比较自0.17.0/stable,默认关闭。- 源文件:
packages/skill-family-engineering-kit/src/adopt-plan.mjs、migration.mjs。 - 正例/负例测试:
packages/skill-family-engineering-kit/test/adopt-plan.test.mjs、migration.test.mjs、engineering-baseline-adopt-plan.test.mjs、cli.test.mjs。 - 计划边界:
engineering与engineeringBaseline独立,前者不取代后者的配对前提;能力目录查询不能混用工程声明。writeSet、conflicts和complete不授权自动执行、不证明业务资格;部分声明缺失的另一 declared 分支仍为incomplete。 - 调用方仍拥有的业务语义:存量业务代码的迁移决策、真实声明来源与缺项处理(真正迁移执行由调用方负责)。
本地 0.24.0 候选中,当目标工程的 skill-family.project-manifest.json 中存在 engineering 字段时,采用检查应调用已有的 runCoreCheck 进行验证;若该字段不存在,则沿用原有的 runChecks 作为 legacy 检查路径。计划输入中包含的 engineering 参数仅用于描述拟议生成内容,不能作为目标当前已采纳状态的依据,亦不可替代真实清单声明。任何畸形的工程声明均不得回退至通过状态,必须由核心检查机制直接拒绝。migration.check.green 的值来源于实际运行的检查报告,其结果反映的是当前检查阶段的真实状态,而非迁移完成或业务资格的证明。原冲突、待执行写入、旧实现退出、绑定及 unit、integration、consumer、independentAudit 四类证明的门槛要求保持不变,检查通过不等于迁移已完成,也不代表具备业务资格。
projection (foundation.kit.projection)¶
runProjection / loadProjectionManifest¶
- 签名:
runProjection({ root, manifest: manifestInput, candidateRoot, faultInjector, preparedProjection, engineering, operationId, validationTimeoutMs, cooperativeWriters } = {})(async)loadProjectionManifest(rootAbs, manifestRelPath)(async)- 输入:原投影清单、目标根,或可选
engineering。新模式属于本地0.24.0候选,正式0.23.0不支持;省略保留原 v1/v2 与 prepared 路径。runProjection({ root: targetRoot, engineering })完整替换整个声明,不做深合并;调用方传完整已确认对象,保留仍需使用的旧entries和releaseUnits。不能与manifest、candidateRoot或preparedProjection同传;null、{}、未知字段与非法引用拒绝。字段合同见本页 scaffold 节。 - 输出:原模式的投影文件(仅在校验全部通过时写入)。工程模式只更新
skill-family.project-manifest.json和skill-family.managed-file-lock.json,保留非engineering字段、registry 与其他文件字节、其他锁条目、生成器、版本、lockVersion与 mode,清单摘要由原生成器派生,同内容幂等。沿用schemaVersion: 2的skill-family.projection-receipt;内存候选的candidate.root与manifest.location为null,不新增状态文件。 - 纯函数:
loadProjectionManifest是;runProjection两阶段(全校验后才写,失败回滚)。 - 副作用:在受收容目标写投影文件,不覆盖 handwritten 文件;首写前的预检失败零写。工程模式的修改后验证与回滚范围见下述失败边界,不把中途失败称为从未写入。
- 稳定错误码与
details.kind:未授权 / 手写冲突 / 越界 / 内容冲突抛KitError(rejected/unauthorized类kind)。 - 前置条件与信任锚:原模式要求投影清单已登记(
PROJECTION_MANIFEST_PATH)。工程模式要求现有普通根与有效普通 registry、项目清单、受管锁;清单和锁均在 registry 与managedFiles内声明受管,清单锁条目由 Engineering Kit 拥有。所有其他受管文件匹配原锁,无缺覆盖、重复或未拥有的锁条目;工程引用为根内现存普通文件。缺前提只拒绝该受管更新,不自动接管任意非空项目,不手写候选清单或锁掩盖漂移。 - 工程模式失败边界:保留原始已核引用快照,重复读取不能替换基线;每次实际修改前及完成后重验。首写前拒绝不执行恢复写,未尝试输出的外来字节保留。实际尝试写入失败沿既有错误处理、验证与尽力回滚,仅恢复本模式实际尝试的路径;不承诺整次初始化事务、恶意并发或 ABA 安全。原 v2 完整闭包回滚合同不变。
- 声明完整性:允许只传
entries或releaseUnits,缺失的另一 declared 分支仍为incomplete,生成收据不证明静态检查、真实业务、正式发现或整体资格完成。 since/stability:0.2.0/stable。- 源文件:
packages/skill-family-engineering-kit/src/projection.mjs。 - 正例/负例测试:
packages/skill-family-engineering-kit/test/projection.test.mjs。 - 调用方仍拥有的业务语义:投影内容的业务含义(远端发布转
release-skill)。
buildProjectionClosure¶
- 签名:
buildProjectionClosure(resources, options);Windows 显式传{platform: "win32"},省略保持原 POSIX 合同。 - 输入:资源数组,成员为
{path, sha256, mode}(显式type: "file"被容忍)。 - 输出:规范投影闭包
{digestAlgorithm: "sha256", digest, resourceCount, resources}(成员规范化为{path, type: "file", sha256, mode},按 path 确定性排序,digest = sha256(JSON.stringify(resources))),可原样作为compileProjectionPlan()的previousOwnedClosure或externalCandidateClosure;空数组是合法空闭包。 - 纯函数:是(无文件读写、无网络、无子进程;入参不被改写)。
- 副作用:无。
- 稳定错误码与
details.kind:非数组输入、重复路径、可移植路径碰撞、非法 path/type/sha256/mode 在既有projection plan input invalid错误域内失败关闭(SFC2004,details.kind为invalid-manifest)。 - 边界:本函数构造的是投影/计划闭包,与 Harness
computeResourceClosure()的资源闭包(成员{path, role, exists, sha256}、整体信封摘要)形状与用途不同,两者不可互换;与normalizePlanClosure()、候选枚举闭包共享同一规范化与摘要事实源。 - 前置条件与信任锚:无;结果直接满足
compileProjectionPlan()的闭包合同,不新增第二个编译入口。 since/stability:0.7.0/stable。- 源文件:
packages/skill-family-engineering-kit/src/projection.mjs。 - 正例/负例测试:
packages/skill-family-engineering-kit/test/projection-closure-builder.test.mjs。 - 调用方仍拥有的业务语义:投影内容的业务含义与资源字节的来源证明。
check (foundation.kit.check)¶
runStaticReferenceCheck¶
runStaticReferenceCheck 是从 skill-family-engineering-kit 包根导出的公共 API,用于在确定性静态检查上下文中验证固定文件引用的可读性。该接口核对指定来源行上的路径字面量及所指目标文件,不执行目标、不写文件、不联网,也不扫描其他文件。
输入要求
- root:非空字符串,表示获准目录的路径。该路径可为既有 resolveTargetRoot 接受的目录字符串,API 将其解析为词法绝对根。若不可用,沿用旧合同错误传播。
- references:非空数组,每项必须包含以下四个字段:
- sourceRef:获准根内的相对文件路径,表示实际调用所在的源码文件。
- line:从 1 开始的安全整数,表示源码中引用出现的行号。
- literal:目标文件的固定相对路径,仅支持由 / 分隔的 POSIX 路径;各段由 ASCII 字母、数字、点、下划线、连字符组成,段不能为 . 或 ..,可带一个前导 ./。不支持含空格、非 ASCII 字符、反斜杠、绝对路径、冒号、变量、引号、通配符或 Shell 语法的路径。
- baseDir:相对根目录的解析基准,用于将 literal 解析为完整目标路径。根目录用 . 表示。
重复的四字段组合(sourceRef, line, literal, baseDir)、顶层未知字段或单项未知字段均抛出 SFC2003 错误。调用方需确保选集完整、来源真实、基准正确,且为实际调用而非注释、否定句或示例。
检查过程
1. 复制输入对象,防止后续修改影响执行。
2. 重新读取 sourceRef 文件,通过严格读取获取原始字节回执,并将来源内容解码为 UTF-8 文本,按 LF 分行(允许 CRLF),并严格匹配 line 行上的 literal。
3. literal 必须在该行中恰好出现一次,且其左右必须为行边界、空白、单引号、双引号或反引号。更长的文件名不能匹配,多个出现位置即使仅一个满足边界条件也视为不足。
4. 验证非根 baseDir 是否安全(通过 resolveContained),将 baseDir 与 literal 组合为相对目标路径。
5. 使用 readFileStrict 读取目标文件,获取真实字节与摘要。若读取失败(如缺失、不可读、权限不足),该项记为 insufficient,保留原始错误 code 与 kind。
6. 将可完成项的来源与目标输入 computeResourceClosure,计算真实资源闭包。闭包中每项摘要必须与严格读取回执一致。若摘要不符,受影响项降级为 insufficient,但其他项仍可完成;仅当闭包整体计算失败时,所有参与项转为不足,details.closure 设为 null。
7. 按原顺序生成 details.references,包含:
- index:从 1 起的序号
- 原始四字段:sourceRef、line、literal、baseDir
- status:checked 或 insufficient
- reason:实际核对结果或不足原因
- source:回执对象,含 ref、sha256、bytes(未取得则为 null)
- target:回执对象,含 ref、sha256、bytes(未取得则为 null)
- cause:若有既有机制异常,保留原始错误 code 与 kind
8. source.ref 与 target.ref 由已验证的相对绑定按 POSIX 规范化生成,不基于词法根与绝对路径做 path.relative 计算。符号链接根下仍沿原相对基准,不新增拒绝符号链接根或父目录的政策。
9. 最终 outcome.completion 依据完成状态设置:
- 所有项完成 → complete,code=ENGINEERING_CLEAR
- 部分完成 → partial,code=ENGINEERING_CHECK_INCOMPLETE
- 无完成项 → not-performed,code=ENGINEERING_CHECK_INCOMPLETE
输出说明
- 返回值为 skill-family.professional-conclusion 对象,provider.entry 为 runStaticReferenceCheck,subject.ref 为 resolveTargetRoot 返回的词法绝对根。
- scope.checked 仅保留完成项,scope.limitations 明示仅覆盖所选固定引用,并列出所有不足原因。
- 不返回 ENGINEERING_FINDINGS,非既有机制错误的意外异常继续抛出。
- CLEAR 仅证明选集在观测时可读,不代表完整 Foundation 审阅、Schema 采用、参数/权限/控制流正确或目标运行效果。
- 闭包数据来自真实读取后计算,不视为原子快照,不支持跨文件一致性保证。
- 调用方若需持久化结论,应在自己获准的输出根中序列化返回值,已有 readProfessionalProof 可读取,并按新入口身份说明该局部结果。
- 本轮不为该 API 增加重复的 CLI 路由。
示例
import { runStaticReferenceCheck } from "skill-family-engineering-kit";
const conclusion = await runStaticReferenceCheck({
root: "/approved/example-family",
references: [{
sourceRef: "skills/review/SKILL.md",
line: 47,
literal: "scripts/check.mjs",
baseDir: "skills/review",
}],
});
- 来源:
packages/skill-family-engineering-kit/src/static-reference-check.mjs。 - 直接正反测试:
packages/skill-family-engineering-kit/test/static-reference-check.test.mjs。 - 发布状态:本地新增候选,精确发布版本另行冻结。
runSelectedArtifactCheck¶
此接口在 0.31.0 版本候选中新增,从 skill-family-engineering-kit 包根导出,用于对调用方明确指定的文档执行真实环境下的专业检查。其核心目标是解决两类问题:一是验证文档是否符合实际采用的 JSON Schema;二是比对文件真实 SHA256 摘要与给定的可信基准。当前是否正式分发,以当前产品状态页为准。
调用方式为 runSelectedArtifactCheck({ root, artifacts })(异步)。接口需提供两个必填字段:root 与 artifacts。root 为显式非空的目录路径字符串,表示检查范围的根目录;artifacts 为非空数组,每一项代表一个待检文档及其关联的校验条件。
每个 artifact 项必须包含 path 字段,其值为相对于 root 的普通文件路径。在此基础上,可选配置以下两种校验方式之一或同时启用:
- Schema 校验:通过
schema字段指定独立的 Schema 文件描述符,该字段为单个对象,包含path与dialect两个字段。path指向一个独立的 JSON Schema 文件(路径相对于root),dialect为非空字符串,表示 Schema 所采用的方言,当前仅支持draft-07与2020-12。 - Baseline 校验:通过
baseline字段指定可信摘要基准,该字段为单个对象,包含sha256与可选的version。sha256为 64 位小写十六进制字符串,来自可信来源的期望摘要;version为非空标签,用于标识该文件的版本信息,仅作事实绑定,不参与摘要比对,也不用于提取文档版本或认证宿主政策。
同一 path 不得在 artifacts 数组中重复出现。所有未知字段将被拒绝。调用方需自行确保 Schema 已实际采用、基准来源可信、选集完整。路径安全检查由公共 API 通过 Harness 实际执行。
Schema 文件仅支持 draft-07 与 2020-12 同步的 JSON Schema 对象,允许空对象 {}。$ref 与 $dynamicRef 仅支持 # 片段引用,具体解析由现有库处理。若 Schema 为布尔值、含外部引用、使用 $async: true 或未知方言,无法完成结构检查时将如实记录不足,不联网获取。实际文档的版本一致性应由已采用 Schema 中的 const 或 enum 显式表达。
子检查和实际来源¶
runSelectedArtifactCheck 接口返回的 professional-conclusion 中,provider.entry 固定为 runSelectedArtifactCheck,subject.ref 为解析后的根目录路径。details.artifacts 按请求顺序保留每个待检项的完整信息,包含 index(从1开始的请求序号)、selection(原请求项的完整复制)、document(实际读取回执或 null)、schemaSource(实际读取的 Schema 源或 null)、checks(检查结果对象,始终为对象,不为 null)。
selection 为原始请求中对应 artifact 的完整副本,保持原始字段与结构。document 为实际读取的文件回执,仅包含 ref(相对于根的路径)、sha256(64 位小写十六进制摘要)和 bytes(字节数),不含文件内容;若读取失败则为 null。schemaSource 为实际读取的 Schema 源回执,结构同 document;若未选择 Schema 校验或尚未读取成功则为 null。checks 为检查结果对象,始终存在,包含 schema 与 bytes 两个字段,分别对应 Schema 校验与字节比对结果。checks.schema 与 checks.bytes 仅在未选择对应检查时为 null,否则为包含 status 与 reason 的对象;status 取值为 pass、findings 或 insufficient,reason 为非空字符串,用于描述检查结果或失败原因。details.closure 为实际资源闭包信息或 null,表示检查过程中实际访问的文件集合。selection 与各来源回执(document、schemaSource)必须明确区分,前者为请求输入,后者为实际读取输出。
完成情况与发现分别判断¶
outcome.completion 表示检查完成情况:全部选定子检查完成时为 complete,至少一个完成且有不足时为 partial,全部选定子检查均不足时为 not-performed。完成的子检查可为 pass 或 findings,complete 包含两者,仅关注是否完成,不涉及发现。
outcome.code 表示检查结论:若存在已确认发现,则为 ENGINEERING_FINDINGS,即使 completion 为 partial;若无发现但存在不足,则为 ENGINEERING_CHECK_INCOMPLETE;仅当全部完成且无发现时,为 ENGINEERING_CLEAR。该字段独立于完成状态,用于表达最终结论。
scope.checked 仅列出实际完成的子检查项,如 artifact:1:schema、artifact:1:bytes。真实结构或可信摘要不符为 findings,无法读取、Schema 支持不足、同 $id 实际缓存不同 Schema 或来源漂移为 insufficient。两个子检查独立;某一项不足不会直接取消另一项已完成的结果。
缓存核对以同一进程中的已编译 Schema 对象未被调用方篡改为前提,不清除公共缓存。闭包资源失配只使依赖它的检查变为不足;多次读取不构成原子快照。
CLI 与后续处理¶
CLI 命令为 skill-family-kit check selected-artifacts --root <dir> --selection <relative-json> --json。其中 --selection 指定根内的相对 JSON 文件路径;该文件的顶层对象只能包含 artifacts 字段。details.selectionSource 记录此文件实际读取的回执。
选集文件在调用时被完整纳入资源闭包。若选集在执行期间发生漂移(如文件被修改、删除或路径变更),则整批检查将被标记为 insufficient,所有子检查均视为未完成。
专业结论输出到 stdout;用法错误和未处理异常沿现有 CLI 错误通道报告。退出码定义如下:
- 0:
outcome.completion为complete且无findings,表示检查完整通过; - 1:存在
findings或insufficient,表示发现异常或检查不完整; - 2:用法错误、参数缺失、选集文件 JSON 解析失败,或未处理的机制异常。
返回结果仅输出 stdout,调用方可将其保存在自有授权目录中,后续通过 check proof 或 readProfessionalProof 读取历史记载。读证操作仅解释已保存的结论,不重跑检查,不鉴伪,不验证当前状态。
API 用法错误对应 SFC2003 错误码;已知读取失败保留 SFC2004 及其 kind 信息,用于调试。未知程序异常直接传播,不包装为读取不足。
该入口不扫描目录树、不执行目标、不启动进程、不联网、不写入目标文件。结果仅覆盖选集内容,不替代平台语义、可信基准、版本政策、选集完整性、完整 Foundation 审阅或发布批准。
源码位于 packages/skill-family-engineering-kit/src/selected-artifact-check.mjs,测试文件为 packages/skill-family-engineering-kit/test/selected-artifact-check.test.mjs 及既有 CLI 和 professional-conclusion 测试。当前版本为 0.31.0 候选,不宣传已发布。
runSourceGeneratedCheck¶
在技能族生成配置中,sourceRoots 与 generatedRoots 分别定义来源根与生成根的坐标,可指向文件或目录。本检查仅执行一项机械比较:在同一个 mapping 内,是否存在来源根坐标与生成根坐标完全相等的情况。该比较结果用于定位潜在配置冲突,供维护者与独立审阅者复核,不涉及生成执行效果、文件实际存在性或运行时行为验证。当前投影计划、执行收据与文件摘要均未涵盖此项根坐标等价性验证,原生文件角色语义审阅仍保留其独立职责。本次增量仅提供可公开调用的机械比较能力,确保选定声明的相等性判断可被重复执行并返回明确范围,不替代原有职责。
声明和比较范围¶
检查机制读取一份真实存在的JSON文件,不接收临时构造的数组或内存对象。可选的共享读取合同位于 source-generated-declaration.schema.json,其定义了当前支持的配置结构,但不证明项目此前已采用该Schema。其他项目可继续保留旧格式,未匹配的声明将被标记为“不足”而非强制迁移。
未知字段、缺字段、空根数组或版本不匹配时,保留结构错误位置并记为不足,不进入方向判断。合同要求根对象满足以下条件:
- schemaVersion 为 1
- kind 为 skill-family.source-authority-declaration
- mappings 为非空数组
每条 mapping 必须包含:
- 非空字符串 capabilityId
- 非空字符串数组 sourceRoots 与 generatedRoots
- generator.path 为非空字符串,表示生成器路径坐标
generator.checkArgument 为可选字段,仅用于记录检查参数,不解析、不传递、不执行,也不验证生成器是否存在或是否工作正常。
路径坐标遵循以下规范:
- 使用正斜杠 / 分隔
- 每段仅允许字母、数字、下划线 _、点 . 和连字符 -
- 不接受空段、. 段、.. 段
- 可省略开头的 ./,但不支持变量、通配符、排除表达式、反斜杠或绝对路径
检查仅比较路径的词法规范化形式,不探测实际文件存在性、符号链接、磁盘大小写归一化或目录层级结构。但会识别路径之间的词法祖先/后代关系,若存在此类关系,当前版本不推断其是否合规,一律记为“不足”。
在同一条 mapping 内,若任一 sourceRoot 与任一 generatedRoot 在规范化后完全相等,则判定为方向冲突。结果将记录该冲突的两个字段的 JSON 指针及共同路径坐标。
跨 mapping 之间允许前级生成物作为后级来源,例如 mapping[0].generatedRoots 中的某个路径作为 mapping[1].sourceRoots 中的某个路径,此为允许的多阶段串联。
无关路径不因文件名相似而被误判为同一根。所有判断均基于显式声明的固定路径坐标,不依赖上下文或隐含规则。
调用与返回¶
公共入口为 runSourceGeneratedCheck({root, declaration}),其中:
- root:显式非空的本地目录路径,表示声明文件所在根目录。
- declaration:相对于 root 的 JSON 文件路径,如 config/source-generated.json。
CLI 调用形式为:
skill-family-kit check source-generated --root <dir> --declaration <relative-json> --json
--json为必选项,仅向stdout输出结构化 JSON 结果。
共享读取合同路径为:
skill-family-engineering-kit/source-generated-declaration.schema.json
合同 ID 常量为:
SOURCE_GENERATED_DECLARATION_SCHEMA_ID
检查使用该共享读取合同核对声明结构;匹配结构不证明项目此前已采用它,不匹配时记为 insufficient。
固定字段参考¶
// 下列类型说明实际字段;不是另一份运行时 Schema 或专业证明。
type Coordinate = { value: string; normalized: string | null; pointer: string };
type MappingDirection = {
index: number; // 一基序号
pointer: string; // JSON 指针,内部数组索引为零基
capabilityId: string;
sourceRoots: Coordinate[];
generatedRoots: Coordinate[];
generator: { path: string; pointer: string };
status: "pass" | "findings" | "insufficient";
reason: string;
conflicts: { source: string; generated: string; root: string }[];
unsupported: ({ pointer: string; reason: string }
| { source: string; generated: string; reason: string })[];
};
type DirectionDetails = {
selection: { declaration: string };
readingContract: string;
declaration: { ref: string; sha256: string; bytes: number } | null;
declarationCheck: {
status: "pass" | "insufficient"; reason: string;
errors?: unknown[]; cause?: { code: string; kind?: string };
};
mappings: MappingDirection[];
closure: unknown | null; // 现有 computeResourceClosure 的实际返回值
};
// 沿用 professional-conclusion,不增加外层包装。
// provider = { id, version, entry: "runSourceGeneratedCheck" }
// subject = { ref: root }
// scope.checked 的形式:"mapping:1:direction"
// outcome.completion: "complete" | "partial" | "not-performed"
// outcome.code: "ENGINEERING_CLEAR" | "ENGINEERING_FINDINGS"
// | "ENGINEERING_CHECK_INCOMPLETE"
同一映射已有相等冲突,另有不支持的根坐标时,冲突贡献可以列入 scope.checked,但 outcome.completion 保持 partial,该映射的 unsupported 逐项保留未知部分;这不表示整条映射的全部根对都已完成判断。
请求缺字段或根不可用时沿原错误传播,CLI 退出 2;声明读取、路径收容、结构或根坐标支持不足时,返回真实 insufficient,CLI 退出 1。全部完成且 ENGINEERING_CLEAR 才退出 0。存在发现或不足退出 1,未知程序异常退出 2。
如何判断检查结果¶
检查结果的完成状态分为三种:
- complete:所有选中的 mapping 均已完成比较,无论是否发现冲突;
- partial:存在已完成的比较,但同条或其他映射仍有未支持的根坐标;
- not-performed:没有有效的映射方向比较贡献。
结果中若存在冲突,必须明确列出冲突路径的JSON指针与共同坐标;若存在未覆盖的 mapping,也需说明其不足原因(如动态路径或祖先关系的语义未支持)。结果不证明生成成功、文件存在或运行合规,也不替代发布资格或运行时验证。所有判断仅限于当前配置中声明的路径坐标,不扩展至祖先关系、执行效果或跨阶段业务合法性。
runChecks / runCoreCheck / runEntryContractCheck / checkEntriesAction / isContainedDeclaration / readProfessionalProof / createProfessionalProof / publishProfessionalConclusion¶
- 签名:
runChecks({ root, allowGitSpawn = true, only, profilesRoot, policy = "legacy" } = {})(async)runCoreCheck({ root, allowGitSpawn = true, profilesRoot } = {})(async)runEntryContractCheck({ root, policy = "legacy" } = {})(async)checkEntriesAction({ root, policy, conclusionOutput } = {})(async)isContainedDeclaration(rel)readProfessionalProof({ proofRoot, proof })(async)createProfessionalProof({ reviewRoot, reviewInput, conclusionOutput })(async)publishProfessionalConclusion({ conclusionOutput, report, entry })(async)- 输入:legacy 政策沿用九类
--only。declared 版本检查须显式传入policy: "declared"与only: "version";declared 入口检查通过runEntryContractCheck或check entries --policy declared读取项目清单的engineering.entries。 - 输出:原有发现清单与
ok=0、findings=1、mechanism=2映射不变。声明缺失或不合法是不可检查的领域发现;读取普通文件时发生安全或机制中断则保留为机制失败。报告只把已经完成的发行单元或入口列入结果,不把后续未访问项写成完成。 - 纯函数:否(读取目标文件);但纯检查函数只诊断、不修复、不写。declared 分支不会运行目标脚本、Skill、hook、模型、Git 探测或其他未选择分类。
- 副作用:无文件写入;默认可能启动一条冻结参数的只读 Git 探测(至多一次冻结
status查询),传入allowGitSpawn: false可关闭该子进程。 - declared 副作用:声明分支零 spawn、零 Git、零网络。只有
runCommand("check")与checkEntriesAction包装入口收到conclusionOutput: { root, path }时,才在已存在输出根内独占创建一个结论文件;不创建父目录、不覆盖现有文件。纯检查函数和缺省 CLI 都不写。readProfessionalProof只读解释本族证明,不扫描目标、不追随details路径。createProfessionalProof把 Skill 审阅 JSON 投影为FOUNDATION_STATIC_*结论,沿用同一排他写入;全部not_applicable只能是FOUNDATION_STATIC_INCOMPLETE。publishProfessionalConclusion继续把 declared 两分支投影为局部ENGINEERING_*结论。 - 稳定错误码与
details.kind:CHECK_CLASSES为九类闭集,不扩张(审计整改 C2 依裁决 SG-13/14、SG-17、SFA-PLAT-002 增设boundary、platform两类,并为version类加装版本单源一致性事实;扩类经治理批准,此后仍不扩张);机制失败抛KitError(mechanism类)。 - 前置条件与信任锚:legacy 的 Git 探测由
GIT_READ_ONLY_ALLOWLIST限定。declared 分支要求项目根存在符合 Contracts 1.20.0 的skill-family.project-manifest.json;每个版本来源与入口都是根内相对路径,严格读取普通文件。 since/stability:0.2.0/stable。- 源文件:
packages/skill-family-engineering-kit/src/check.mjs、entry-check.mjs、engineering-declaration.mjs、professional-conclusion.mjs与core-check.mjs。 - 正例/负例测试:
packages/skill-family-engineering-kit/test/check.test.mjs、entry-check.test.mjs、core-check.test.mjs、check-equivalence.test.mjs、cli.test.mjs与professional-conclusion.test.mjs。 - 调用方仍拥有的业务语义:声明哪些单元和入口应受检、处置发现项、解释专业 code 与详情、向消费方传递结论路径,以及授权和管理结论输出根。自动修复仍由调用方负责。
本地 0.24.0 候选的 core 版本接线¶
本地 0.24.0 候选对公开 runCoreCheck 作一项窄行为修复:目标真实声明 engineering.releaseUnits 时,版本类复用已有声明式版本读取逻辑,依据 versionSource 与 versionMirrors 检查文本或 JSON 格式的版本信息;私有工程的 package.json 不自动成为该业务单元的版本源或镜像,仅当被显式声明时方可参与版本认定。对于真正未声明版本、或仅包含合法 entries 的目标,仍沿用原有 legacy 版本检查路径。非法或重复的声明不回退为通过;声明的版本源或镜像缺失、不可读时如实失败。
核心调度机制保持不变,共用原九类循环与报告流程,保留 Contracts 规格版本一致性检查及其他八类校验。声明的来源、镜像及各祖先路径均需先通过原树枚举与 lstat 安全预检,包括原不展开的工具目录;仅探查声明所涉路径,不引入新的目录遍历器。符号链接、FIFO 及其他不安全读集仍按原规则拒绝访问,禁止穿过根内符号链接目录;completed、mechanism 与 0/1/2 退出码如实传播。
本次变更仅限于公开 core 在已声明版本目标上的适用性调整:公共 runChecks 缺省行为仍等同于显式 policy: "legacy",涵盖原版本发现及 full/only 等价逻辑;显式 policy: "declared" 仍仅允许 only: "version",维持原报告形式、不执行目标代码、不调用 Git 的边界。未新增任何公共 policy 值、API、CLI 参数、Schema 定义或包根导出,亦不在目标生成 shim 中复制检查逻辑。候选实现与局部验证不构成正式发布、业务资格或整体初始化完成的证明。
report (foundation.kit.report)¶
renderReportAction / checkReportAction¶
- 签名:
renderReportAction(options = {})(async)checkReportAction(options = {})(async)- 输入:
report-model、--out/--binding选项。 - 输出:Markdown 文本;显式
--out/--binding才落盘,否则只写 stdout。 - 纯函数:否(默认只写 stdout;显式选项才写受收容文件)。
- 副作用:默认无文件写入;显式
--out/--binding才写受收容文件。 - 稳定错误码与
details.kind:硬失败计为发现;非法参数reject(invalid-params)。 - 前置条件与信任锚:已存在 Harness
report-model;报告由机器结果确定性渲染。 since/stability:0.2.0/stable。- 源文件:
packages/skill-family-engineering-kit/src/report.mjs。 - 正例/负例测试:
packages/skill-family-engineering-kit/test/report.test.mjs。 - 调用方仍拥有的业务语义:报告结论解读(机制在 Harness
report)。
git-probe (foundation.kit.git-probe)¶
probeGitState / probeGitFacts¶
- 签名:
probeGitState(root, { allowSpawn = true } = {})(async)probeGitFacts(root, candidatePaths, { allowSpawn = true } = {})(async)- 输入:目标根。
- 输出:Git 状态与事实(只读)。
- 纯函数:否(调用
git只读子命令);不含任何写操作。 - 副作用:只读调用
git status/ls-files/check-ignore;默认允许启动冻结参数的只读子进程,allowSpawn: false可关闭;参数向量冻结于GIT_STATUS_ARGS/GIT_LS_FILES_ARGS/GIT_CHECK_IGNORE_ARGS,不在白名单即拒绝。 - 稳定错误码与
details.kind:非白名单参数向量抛KitError(unauthorized-git类)。 - 前置条件与信任锚:
GIT_READ_ONLY_ALLOWLIST限定可调用子命令。 since/stability:0.2.0/stable。- 源文件:
packages/skill-family-engineering-kit/src/gitprobe.mjs。 - 正例/负例测试:
packages/skill-family-engineering-kit/test/git-probe.test.mjs。 - 调用方仍拥有的业务语义:Git 写操作授权(Git 写归 Git 生命周期指南,Foundation 不拥有)。
host (foundation.kit.host)¶
bundledHostProfilesRoot / describeHost / resolveHostId / loadHostRegistry / probeHost / buildHostAdapter / verifyHostPeers / runHostVerification / verifyHostVerificationBindings / materializeHostBuild / planHost / assertPlanConsistency / applyHostPlan / probeTrustedVersionDriver¶
- 签名(节选;
bundledHostProfilesRoot与assertPlanConsistency为同步函数,其余入口按下列 async 合同执行): bundledHostProfilesRoot():返回 Engineering Kit 安装包内宿主 Profile 闭包的规范绝对路径。describeHost({ hostId, hostsRoot, registry } = {})resolveHostId({ hostId, hostsRoot, registry } = {})(async):读取已登记的有限 Profile 集合,解析 canonicalhostId与sourceAliases;不读取或写入全局别名表。loadHostRegistry({ hostsRoot, registry } = {})probeHost({ hostId, hostsRoot, registry, executable, allowSpawn = false, timeoutMs = 5000, runner } = {})buildHostAdapter({ hostId, pathCategoryId, input, hostsRoot, registry } = {})verifyHostPeers({ request, peerRoots, hostsRoot, registry } = {})(async):hostsRoot为必需的 Profile 证明根,registry可选;npm 消费者可以显式传bundledHostProfilesRoot(),薄包装 Harness 的同级适配器只读验证,不写入目录。runHostVerification({ request, bindings, hostsRoot } = {})(async):按已登记的封闭内置 driver 表(kimi-code-print-v1、workbuddy-codebuddy-print-v1、codebuddy-print-v1、claude-code-print-v1、codex-exec-v1、qodercli-print-v1,均绑定existing-user-state + host-managed)执行一次受约束调用。请求、候选、fixture、workspace、现有用户状态根和临时根均由调用方绑定;公共结果只返回脱敏的逐宿主事实。verifyHostVerificationBindings({ results, expectedCommon, expectedRequestDigestByHost } = {}):只组合已验证的observed结果,要求共同字段和逐宿主 request digest 精确匹配;不同宿主的 driver、安装、Prompt 和可执行文件事实保持独立。materializeHostBuild(options)planHost({ hostId, pathCategoryId, buildManifest, probeFacts, operation = "install", previousMembers = [], hostsRoot, registry } = {})assertPlanConsistency(planInput)applyHostPlan({ plan, build, targetRoot, authorizationRef } = {}):复用 Harness 的身份绑定读取、严格不替换发布和原子替换;卸载始终返回manual-recovery-required,不删除文件。probeTrustedVersionDriver({ hostId, driverId, capabilities = CAPABILITIES, executable, allowSpawn = false, timeoutMs = 5000, runner } = {})- 输入:宿主标识、有限 Profile、probe/plan 选项;更新和卸载计划必须携带已拥有成员的摘要。
- 输出:宿主描述、canonical 身份、逐项独立的九类 probe fact、构建产物、plan 或本地操作结果。
runHostVerification()直接返回 Contracts 校验后的逐宿主四态 result;verifyHostVerificationBindings()成功时严格返回{ status: "bound" }。 - 纯函数:只有
assertPlanConsistency是;resolveHostId通过受收容的只读 I/O 读取 Profile,不能当作纯函数。其余入口按职责含落盘或进程调用。 - 副作用:
resolveHostId/verifyHostPeers只读;build/materialize在受收容目标写产物;probe默认allowSpawn=false,不取 PATH。真实宿主验证只在调用方提供的 fresh 私有根内写原始证据;公共 result 不落盘为 Foundation receipt。 - 稳定错误码与
details.kind:缺 probe facts 抛KitError(missing-probe-facts);写入失败按 Harness 的publicationState返回partially_applied或indeterminate。HOST_DRIVER_IDS仅两个受信版本 driver(claude-version-v1/codex-version-v1);manual宿主(含 Qoder)由probeHost生成九项driver-limited事实、由planHost返回manual计划,不授予生命周期能力。 - 前置条件与信任锚:宿主 Profile 已在
profiles/hosts登记,并由 synth 投影进 Kit 的data/hosts;别名必须来自该有限集合;受信 driver 限定;applyHostPlan要求显式authorizationRef、已验证 build 与目标根。真实宿主验证还要求显式hostsRoot、受 Descriptor 约束的六个封闭内置 driver、canonical 的existingUserStateRoot(只读根可位于其下;不得等于或位于 output、temporary、private evidence、安装目标、WorkBuddy config root 或 Qoder fresh workspace 内部),以及互不重叠的 fresh 根与最小发现布局预检。WorkBuddy 使用自身配置根下的skills目录与CODEBUDDY_CONFIG_DIR投影;CodeBuddy 使用 fresh 项目的.codebuddy/skills,进程工作目录指向该项目,现有登录态只经HOME投影,两者的 driver 和布局不可互换。Codex 使用<workspace>/.codex/skills,Qoder 使用<fresh-ws>/.qoder/skills;Codex 另要求repositoryRoot/.git存在,不使用--skip-git-repo-check,不执行任何 git 命令。宿主入口不设置默认hostsRoot。 - 可执行文件身份边界:
executableSha256只绑定启动前严格读取到的字节,是点时观察;实际进程仍按 pathname 启动,不证明进程映像。调用方必须在 probe 与正式调用期间独占可执行文件的命名空间。 - 临时目录生命周期:Foundation 保留本次调用的
session-*目录,不按路径自动删除。调用方完成检查后,统一清理其独占的外层temporaryRoot。 since/stability:既有宿主能力自0.10.0提供;bundledHostProfilesRoot与真实宿主验证自0.11.0提供;0.12.0 把封闭 driver 表扩展到五个(Kimi 与 WorkBuddy 保持回归基线,Claude Code、Codex、Qoder 为新增);0.17.0 再增加独立的 CodeBuddy driver。真实宿主验证仍为candidate;生产 driver、源码测试或受控 fixture 都不能替代消费者的真实宿主资格证据。- 源文件:
packages/skill-family-engineering-kit/src/host.mjs、host-profiles.mjs、host-drivers.mjs、host-verification.mjs、host-verification-drivers.mjs。 - 正例/负例测试:
packages/skill-family-engineering-kit/test/host.test.mjs、host-verification.test.mjs。 - 调用方仍拥有的业务语义:宿主能力是否可用、手动事实的解释与生命周期授权;Foundation 不声明消费者 smoke 或远端发布成功,也不宣称认证状态隔离、凭证未变化、模型身份固定或宿主工具能力已关闭。
licensing (foundation.kit.licensing)¶
loadLicensingProfile / listLicensingProfiles / validateLicensingProfile / generateLicenseContent / generateNoticeContent / generateIdentityRecord / bundledProfilesRoot¶
- 签名(节选):
loadLicensingProfile({ profilesRoot, profileId, variant } = {})(async)listLicensingProfiles(profilesRoot)validateLicensingProfile(profile)generateLicenseContent(profile)/generateNoticeContent(profile, { projectName })/generateIdentityRecord(profile, { projectId, projectName, projections } = {})bundledProfilesRoot()- 输入:Profile 标识、变体选择。
- 输出:许可证 / 声明 / 身份记录文本。
- 纯函数:
validateLicensingProfile与各generate*是;load*含只读读取 Profile 数据。 - 副作用:无(纯函数生成 + 只读读取)。
- 稳定错误码与
details.kind:多变体未指定 / 非法 Profile 抛KitError(invalid-licensing-profile)。 - 前置条件与信任锚:
profiles/licensing/registry.json+schema.json存在;默认取 registry 第一变体,多变体须显式选择;所有商业载荷当前关闭。 since/stability:0.2.0/stable。- 源文件:
packages/skill-family-engineering-kit/src/licensing.mjs、profiles/licensing/registry.json、profiles/licensing/schema.json。 - 正例/负例测试:
packages/skill-family-engineering-kit/test/licensing.test.mjs。 - 调用方仍拥有的业务语义:授权业务语义(授权执行决策由调用方负责)。
identity-check (foundation.kit.identity-check)¶
loadIdentityRecord / checkIdentityDrift / validateIdentityAgainstProfile¶
- 签名:
loadIdentityRecord(rootAbs)(async)checkIdentityDrift({ rootAbs, identityRecord } = {})(async)validateIdentityAgainstProfile(record, profilesRoot)(async)- 输入:目标根、Profile 标识。
- 输出:漂移发现、校验结论。
- 纯函数:
validateIdentityAgainstProfile是;load*/check*含只读读取目标文件。 - 副作用:只读读取目标文件;不修改。
- 稳定错误码与
details.kind:漂移或校验失败产出 findings(不抛错,由check退出码1表达)。 - 前置条件与信任锚:
IDENTITY_RECORD_PATH指向身份记录。 since/stability:0.2.0/stable。- 源文件:
packages/skill-family-engineering-kit/src/identity-check.mjs。 - 正例/负例测试:
packages/skill-family-engineering-kit/test/identity-check.test.mjs。 - 调用方仍拥有的业务语义:漂移业务处置(自动修复由调用方负责)。
CLI (foundation.kit.cli)¶
runCommand / cliMain / 拒绝变更旗标¶
- 签名:
runCommand(command, options = {})(async)—— 按TOP_LEVEL_COMMANDS分派,返回{ exitCode, output }cliMain(argv)(async)—— CLI 入口- 输入:
argv。本地0.24.0候选版本在原scaffold、adopt-plan、projection三个命令中接收--engineering <JSON>,正式0.23.0不支持;<JSON>为工程对象的 JSON 字符串,不是文件路径。省略该选项时保持旧行为;传入非法 JSON、null、空对象{}、未知字段、非法引用或重复选项均被拒绝。 - 参数组合:
adopt-plan的--engineering不能用于能力目录查询,也不替代必须与--compare-skeleton成对的--engineering-baseline。projection --engineering不能与--manifest同传;库调用还禁止与candidateRoot、preparedProjection同传。四个顶层命令及既有 check、host、proof 职责不变,当前 help 文本尚未列出这个新参数。 - 输出:命令结果;退出码
ok=0/findings=1/rejected=2。 - 纯函数:否(依命令产生受收容文件写入或只读探测)。
- 副作用:依子动作而定:
scaffold/projection在受收容目标写入;adopt-plan与普通check只读;check relock是显式受控写事务;check qualification预检通过后可能启动绑定的 executable。Foundation 自身不发起网络请求,但绑定的 executable 可能联网;Foundation 不提供 sandbox 或 egress 阻断,调用方与运行环境负责隔离。REFUSED_MUTATION_FLAGS(如--apply)在parseOptions入口即拒。 - declared 包装入口是普通
check的显式例外:只有结论输出根与根内相对路径同时给出时,runCommand("check")或checkEntriesAction才独占创建一份结论文件;纯检查函数不写。check proof --proof-root --proof --json只读解释本族证明;check proof-create --review-root --review-input --conclusion-root --conclusion-output --json从 Skill 审阅结果独占创建一份结论。 - 稳定错误码与
details.kind:未知命令 / 拒绝旗标退出码2(unknown-command/refused-mutation)。 - 前置条件与信任锚:Node >= 22.22.2;
TOP_LEVEL_COMMANDS固定 4 个,第 5 个命令禁止新增;REFUSED_MUTATION_FLAGS在解析入口即拒。 since/stability:0.2.0/stable。- 源文件:
packages/skill-family-engineering-kit/src/index.mjs、cli.mjs。 - 正例/负例测试:
packages/skill-family-engineering-kit/test/cli.test.mjs、boundary.test.mjs。 - 调用方仍拥有的业务语义:命令的业务目标(命令集合不扩张)。
Kit 错误类型:KitError extends ContractsError(构造未登记码立即抛 TypeError);KIT_ERROR_KINDS 为稳定 kind 枚举;kitError / invalidParamsError / unknownCommandError / mutationModeError / refusalError 为构造辅助。REFUSED_MUTATION_FLAGS 列出入口即拒的变更旗标(如 --apply)。
Profile SPI 公共投影¶
skill-family-engineering-kit/profile-spi 是 Profile SPI v3 的公共数据入口。它由 Profiles 源实现投影生成,包内同时携带三个 SPI JSON 资源与 Contracts 的 profile-descriptor.schema.json;投影脚本只替换两个公共包导入和一个本地 Schema URL,资源字节保持绑定。
公共入口¶
loadSpiDefinition():读取extension-spi.json,返回开放扩展点、核心所有权和 entrypoint 规则。loadExtendedDescriptorSchema():读取profile-descriptor.schema.json,返回扩展 Profile descriptor Schema。loadRuleBaselineCatalog():读取rule-baseline-catalog.json,返回 overrides-policy 的基线目录。verifyProfile({ profileRoot, descriptorRelPath = "profile.json" } = {})(async):只读校验 Profile descriptor、资源收容、核心反向依赖、采用 pin 与 overrides;返回SPE0000或SPE1001–SPE1007结果码,不执行 Profile entrypoint。verifyAdoptionDigests({ profileRoot, adoption })与assessOverridesPolicy(overrides):分别校验采用 pin 摘要和只收紧的 overrides。
公共投影入口没有文件写入、Git、网络或进程副作用。profileRoot 必须是可读取目录,资源 entrypoint 必须留在该目录内且为 JSON 数据文件;符号链接和路径逃逸均失败关闭。Profile 的领域语义仍由调用方拥有。
profiles/spi 是唯一手写真源;packages/skill-family-engineering-kit/profile-spi 由 projen 机械生成,不得直接编辑投影文件。
Quickstart Profile v2 candidate¶
规范入口 skill-family-engineering-kit/quickstart-profile 导出 buildQuickstartProfileProjection、
buildQuickstartProfileProjectionFromInventory 与 QUICKSTART_PROFILE_TARGET_PREFIX。builder 接收显式消费者 Schema 路径
与冻结来源身份,生成按 Schema $id 查询的 standalone validator、机械投影的 Contracts/Harness runtime、许可证和
完整 provenance。历史 skill-family-engineering-kit/candidate/quickstart-profile 在弃用窗口内解析同一模块。
Bundle 离线运行时不需要 Foundation 包、node_modules 或 Ajv。builder 只返回稳定 projection manifest,不写目标文件,
也不增加第五个 Kit 顶层命令;调用方仍需把 manifest 交给 runProjection 完成授权写入。0.3.0 的 v2 与 0.2.1 的依赖
闭包 Bundle 不兼容,必须精确锁定版本。
历史 Quickstart 命名空间还导出 adoption 机制;0.10.0 的规范入口是 skill-family-engineering-kit/adoption。
skill naming 使用 skill-family-engineering-kit/skill-naming。两个入口都不增加 Kit 顶层命令;历史消费者迁移一次后,
以后只改变成熟度标签时不再迁移合同身份。消费者采用新 Foundation 版本仍需更新精确 pin,Bundle 是否重建按既有
package identity、来源摘要与 provenance 绑定合同判断。
与机器事实层的互链¶
- 能力稳定 ID 见
docs/agents/capability-catalog.json(foundation.kit.*、foundation.unsupported.*)。 - 机械校验:
scripts/docs/capability-catalog-check.mjs解析src/index.mjs与cli.mjs,拒绝引用不存在的入口,并校验TOP_LEVEL_COMMANDS未扩张为超 4 个。
能力发现与迁移指引 (Foundation 0.14.0)¶
adopt-plan --list-capabilities 是能力发现的唯一 CLI 入口,不增加第五个顶层命令。
覆盖参考和项目评估使用 --all --scope <scope> --locale <en|zh-CN>;项目评估另加
--uses <relative-json-path>,日常单需求查询使用 --filter <text>。输出中的
supportedMatches 只是候选,needsDecision=true 表示项目仍需明确 disposition;
boundary-found 和 no-text-match 都不自动生成 foundation-gap。
planAdoption() 返回的 capabilityAssessment 和 capabilityGuidance 仍是只读投影。
direct-adoption、compatibility-layer、keep-business 与 foundation-gap 的 decision
由消费者记录。迁移 complete 只表示迁移门禁闭合,consumerVerification.claim 保持
null;契约接入完成须由消费者适配器测试与领域门禁声明。
显式资格入口¶
check qualification 是挂在 check 下的显式子动作,要求同时提供
--root、受支持的 --capability(插件生命周期或技能族目录)、--request、--bindings
与 --native。它先读取三包精确版本、能力目录、request/result Schema 和参数完整性,
再调用固定资格入口。缺少证据、跳过执行或终态不确定时,不得输出
real-host-qualified;候选发现、迁移 complete 和契约接入完成都不能替代真实资格。
公共库入口为 runQualification({ root, capability, requestPath, bindingsPath, native })。参数键集闭合;runner、catalog loader、parser、预制 observation 或其它测试接缝会在读取目标文件和创建临时根之前被拒绝。包内测试接缝不从 package root 导出,也不属于公共 API。
0.15.0 的 foundation.kit.plugin-verification 只保留 Qoder 与 WorkBuddy 的
native-lifecycle 分支,使用宿主专属生产 driver 与固定十二阶段生命周期结构;
foundation.kit.skill-family-directory-verification 是 Kimi 的固定目录分支,内置
driverVersion 为 1.0.0,CLI cliVersion 为 0.39.1。受控 fixture executable 必须走同一生产 driver、superviseProcess 和原始流路径,只证明隔离接线,不是厂商官方 grammar,也不能从公共资格入口伪造正式宿主观察。调用方负责领域接受与真实宿主资格,不得复制通用 runner、Schema、Registry 或 receipt 链。
完整插件验证 (foundation.kit.plugin-verification)¶
runPluginVerification¶
- 签名:
runPluginVerification({ request, bindings, hostsRoot })(async)。 - 输入:注册的
plugin-verification-request、私有路径绑定及显式宿主 Profile 根。请求保留install-only与install-and-invoke,并增加只允许本地 source 的native-lifecycle。原分支继续区分local-staged与有限public-channel。 - 输出:注册的
plugin-verification-result。原分支分别报告输入、安装、发现和调用事实;原生命周期分支恰好报告preflight到absent-after-uninstall的十二个有序语义阶段。完整树观察和原始输出只保存在私有证据根。 - 生产 driver:Qoder 与 WorkBuddy 各自拥有 argv 计划、command step、tree evidence 与 raw stream Oracle,阶段内最多三条命令,两个宿主计划可以不同。每次 spawn 前都重新调用
observeExecutableIdentity;身份或解释器链漂移会阻断下一次启动。Contracts 不保存跨宿主统一命令表,也不解释厂商输出。 - 副作用:原生命周期分支只运行调用方绑定的本地 executable,创建 fresh workspace、一次性宿主状态与私有证据。Foundation 自身不发起网络请求,但绑定的 executable 可能联网;Foundation 不提供 sandbox 或 egress 阻断,调用方与运行环境负责隔离。所有分支不覆盖已有安装,不自动重试、回滚或清理不确定现场。
- 失败语义:
rejected表示前提拒绝,failed表示确定失败,indeterminate表示边界终态无法证明。原生命周期的首个非observed阶段会使后续阶段保持空的not-performed;输出未知、重复、缺失、身份漂移、根越界或卸载残留均失败关闭。 - fixture 边界:受控 Qoder/WorkBuddy executable 使用 Foundation 自有的封闭测试协议,并通过真实生产 driver 与 raw-stream 路径执行。该协议不是厂商官方 grammar,不构成真实宿主资格或领域接受。
- 前提:三包精确锁步;调用方绑定冻结本地源、可执行文件、解释器、互不重叠的 fresh 根与现有用户状态边界。每个真实宿主与来源组合必须另有资格证据,入口存在不等于全部组合获准。
since/stability:0.13.0/candidate。永久入口身份不因成熟度标签变化而迁移;现有单 Skill 入口及合同保留。- 源文件与正反例:
packages/skill-family-engineering-kit/src/plugin-verification.mjs、src/host-verification-drivers.mjs、test/plugin-verification.test.mjs、test/foundation-015-kit.test.mjs、test/isolated-install.test.mjs。 - 调用方责任:源接受、领域结果、发布新鲜度和状态、消费者迁移及机制退出证明。
技能族目录验证 (foundation.kit.skill-family-directory-verification)¶
runSkillFamilyDirectoryVerification¶
- 签名:
runSkillFamilyDirectoryVerification({ request, bindings })(async)。公共键集只有request与bindings;caller observation、runner、parser 或预制 result 均被拒绝。 - 输入:注册的 skill-family-directory request,以及调用方绑定的 Kimi executable/interpreter、技能族根、工作区、现有用户状态根、临时根与私有证据根。入口固定
hostId=kimi-code、driverVersion=1.0.0、cliVersion=0.39.1。 - 启动:先以固定版本参数检查 CLI;正式调用固定为
-p <prompt> --output-format stream-json --skills-dir <family-root>。环境只投影NO_COLOR、HOME、TMPDIR与KIMI_CODE_HOME,不展开继承process.env。每次 spawn 前重新观察可执行文件及解释器身份。 - 输出:注册的四态 directory result,以及受保护技能族树、工作区和原始流摘要。私有 raw stdout/stderr、绝对路径与完整 observation 不进入公共结果。
- 当前判定边界:Foundation 自有受控 raw fixture 协议可验证生产 parser 接线,但不是 Kimi 官方 stream-json grammar。当前缺少可验证的官方 typed call/result 映射,因此即使受控事件完整配对,公共结果仍为
indeterminate,原因为official-observation-unavailable,逐技能 discovery/load 保持unknown。 - 失败语义:调用方 observation、根重叠或越界、非 fresh evidence 根、来源摘要不符、可执行文件/解释器漂移、raw evidence 变化和 protected snapshot 漂移均失败关闭。边界终态无法证明时保留现场并要求人工检查。
- 副作用:只启动本地受约束进程,并在调用方绑定的私有临时根写 raw evidence。Foundation 自身不发起网络请求,但绑定的 executable 可能联网;Foundation 不提供 sandbox 或 egress 阻断,调用方与运行环境负责隔离。Foundation 不管理认证、不写全局配置或远端状态。
since/stability:0.15.0/candidate。- 源文件与正反例:
packages/skill-family-engineering-kit/src/skill-family-directory-verification.mjs、test/foundation-015-kit.test.mjs、test/isolated-install.test.mjs。 - 调用方责任:技能族来源接受、领域结果、真实宿主资格、发布新鲜度与发布决定。
Windows 支持与使用边界¶
Foundation 0.28.0 的 Windows 分支支持 scaffold、adopt-plan、projection、check 四个顶层命令,维持原有权限边界。需要原生机制的路径使用包内预构建的 win32-x64 N-API 二进制,不依赖消费者安装编译器,运行时亦不下载任何二进制文件。
执行受控 npm/pnpm 命令时,Kit 依据实际安装包 package.json 的 name、version 与 bin 字段精确定位入口,使用 npm 的 bin/npm-cli.js 或 pnpm 的 bin/pnpm.cjs 作为实际可执行文件。启动过程通过明确的 Node 解释器与参数数组执行,不解析 .cmd 或 .bat 文件,不依赖后缀名推断执行逻辑。官方宿主 .exe 入口仍需绑定真实可执行身份,并在临近正式启动时重新观察;点时身份不构成签名信任、认证或最终内核映像的证明,仅用于启动上下文识别。
静态 check 成功、安装成功和宿主装载扫描成功均不构成 Windows 宿主业务通过。Qoder、WorkBuddy、Kimi 的真实宿主资格分别依赖相应 driver、准确 CLI 版本、认证状态与业务原始输出。缺少对应登录状态或原始业务输出时,该项保持“未验证”状态。对本次版本的验证不改变旧版本的能力;精确版本的远端发布与可用性须由正式发布凭据核实。
投影调用与结果¶
1. 纯函数构建 Windows 投影¶
buildProjectionClosure 与 compileProjectionPlan 均支持显式传入 {platform: "win32"} 以启用 Windows 投影合同。
- buildProjectionClosure(resources) 为纯函数,输入为资源数组,输出为规范投影闭包 {digestAlgorithm: "sha256", digest, resourceCount, resources}。
- 仅当第二参数为 {platform: "win32"} 时,该函数选择使用 Windows 合同下的资源元组规范,包括 mode: null 与同次原生绑定读取的 permissionObservation,但不触发文件观测;文件观测由调用方通过原生绑定读取机制获取。
- compileProjectionPlan 输入保留原七项:rootBinding、authoritySources、ownership、handwrittenPolicy、previousOwnedClosure、externalCandidateClosure、authorityBinding,仅增加可选 platform: "win32"。
- 不传 platform 时,合同与字节完全保留原样,不因平台变化而语义漂移。
- plan.rootBinding 仍是规范绝对路径字符串,不是 Harness 根绑定对象。
- preparedProjection 重建时必须带回 platform 与全部权限字段,经原完整重构与深比较,不能重建成旧版本或丢失权限。
Windows 合同明确采用 projection-plan v2、projection-manifest v3 与 projection-receipt v3,顶层 platform 固定为 win32,kind 沿用原值。
- 旧版 Windows v1/v2 清单或 v1 prepared plan 在业务修改前被拒绝,并提供明确迁移说明。
- 不得隐式转换字段,亦不得将旧输入伪装为新合同。
真实文件资源为闭对象,其形状如下:
{ path, type: "file", sha256, mode: null, permissionObservation }
permissionObservation使用 Harness Windows 权限观测 的闭结构,记录真实权限,不是 POSIX mode。- 目录闭包、
authoritySources、原目标、外部候选中的真实文件均使用同一次原生绑定读取的内容与权限,不以前后lstat拼接。 - 资源排序沿用原方法,摘要为
sha256(JSON.stringify(规范资源数组)),包含完整权限观测。 - Windows 不接受数值
mode或缺失permissionObservation的文件观测。
authorityBinding 为 caller-bytes 时,authoritySources 按原来源标识绑定确切字节与摘要,mode: null,不伪造文件权限;
- 未传 authorityBinding 时的既有本地目标来源,以及 external-root 权威来源,必须使用真实文件观测;
- target-local 仅指该既有模式,不新增绑定种类。
- 绑定种类先验证,再选择合法字段;不能因缺少 permissionObservation 就降级为 caller-bytes。
manifest v3 的两条入口仍互斥。内联 entries/content 支持文本或 Base64 字节,候选资源为 {path, type: "file", sha256, mode: null},不带权限观测,收据中的 candidate.root 为 null。外部 candidate/operations/rootOutputs 使用真实文件元组及规范候选根;工程内部字节意图也不能与外部文件闭包互换。原路径授权、受管归属、手写保护、自投影拒绝、完整候选与无额外成员检查继续执行。
内联 expect 可省略;声明时,已有文件为 {state: "sha256", value, mode: null, permissionObservation},缺失目标为 {state: "absent"}。外部操作保留原 operation/path/source/owner/expect 与类型约束,不把数值 mode 用作 Windows 目标策略。before/after 始终记录实际文件状态。
2. 一次运行的授权与验证¶
runProjection 保留原参数及 root='.' 默认值,新增三个显式必填运行参数:
- operationId:小写 UUID v4 格式,唯一标识本次投影。
- validationTimeoutMs:安全整数,范围为 1 到 2147483647,表示验证超时时间(毫秒),不得为字符串。
- cooperativeWriters:必须严格为布尔值 true,不接受字符串 false 或其他值。
CLI 增加对应参数:
- --operation-id:传入 operationId。
- --validation-timeout-ms:传入 validationTimeoutMs,值必须为十进制数字字符串,转换后须为安全整数,不接受尾随字符、空白或小数。
- --cooperative-writers:无值的显式确认开关,出现即传 true,不接受值或将字符串 false 转为真。
CLI 中三个参数均拒绝重复;报告子动作不接受这三个参数。
- Windows 缺任一运行参数在任何修改前拒绝,包括 no-op。
- POSIX 显式提供任一新增运行参数也在修改前拒绝;原 POSIX 无这些字段的调用不变。
完整输入与目标闭包验证:
- 先完成全部领域授权、候选、权威来源、锁定输入、目标路径及类型/预期检查,再做只读恢复根准入。
- no-op 须在任何目录或材料写入前决定。
- 全 unchanged 路径仍核验完整前后闭包、权威与锁定输入,返回真实 unchanged 和原 declared/execution 索引,fileSet: null 表示未执行机制;不伪造 committed/材料状态,也不将请求 operationId 写为已执行身份或消费它。
需要修改时,由 Kit 显式准备固定 .foundation-file-apply 私密根,再准备必要业务父目录。
- 私密机制根及其材料不加入业务目录清理列表。
- 未知/损坏/未终结材料或仍有参与者,在 no-op 与修改路径都拒绝;不能靠当前业务字节相同放行。
合作式独占前提覆盖目录准备、文件应用、领域验证和同次清理,file-set 内部锁不能证明整个调用独占;不再增加第二套锁。
applyFileSet v2 沿原稳定顺序,非 rootOutputs 先、rootOutputs 最后,并保留原索引映射。
- 相同字节及目标权限已经满足者省去重复 replace,但仍参与完整领域验证。
- create 继承目标父权限;replace 保留原目标权限;candidate 权限只是输入绑定。
所有实际修改结束后,必须通过原 applyFileSet options.validate,在 commit 前核验全部承诺目标、unchanged 项、权威与锁定输入,不只检查改变成员。
- 沿用原 {passed: boolean}、验证超时及失败自动恢复合同。
- 提交后的观察只报告已提交事实,不能代替这项提交前验证。
prepared 的 freshRoot 在新 Windows 版本要求根下没有业务对象,只可存在经只读准入的精确 .foundation-file-apply。
- 第一次成功留下的业务输出会拒绝再次 freshRoot;正常重复使用真实 previous closure。
- SIGKILL 残留的空业务父目录也阻止 freshRoot,不能因其空或路径相同就忽略、删除或推测归属。
Kit 固定映射 allowAdjacentStaging: true,允许原 file-set 的邻接暂存及恢复根、日志、before/after 材料副作用;业务写入仍限授权路径,但机制材料可能保留;这不是所有失败均零写入的承诺,也没有第四个暂存开关。
3. 失败后的结果解释¶
结果保留原 file-set 对象中的 outcome、errors、materials、锁释放及操作身份;commit-unconfirmed、recovery-required 或未知提交不得压成成功。
- 已经有效提交的事实不因后续报告/收尾失败而反向回滚。
- Windows receipt v3 显式包含 fileSet(真实结果或 no-op 的 null);不能把未执行机制当提交成功。
从首次目录准备开始发生的失败,原 Kit projection-write-failed 错误 details 在原 cause / completed / rollback / zeroWriteSuccess 之外保留:
- fileSet:原机制结果或未执行时的 null;
- directoryPreparation:{materialRoot, businessParents},两个固定字段分别是相应准备的原结果或尚未调用时的 null;
- directoryCleanup:原清理结果或未调用时的 null。
- null 只表示未调用,不能表示没有副作用。
准备失败在 apply 之前仍携带部分创建及不确定事实,原 file-set 结果不被目录错误覆盖,不新增独立收据或状态文件。
file-set 仅恢复实际意图路径。Kit 返回前还要核对完整原承诺闭包,包括未尝试/unchanged 项及权威、锁定输入;外来漂移报告失败,不覆盖外来数据以修出通过。
- 工程投影仍只恢复尝试过的输出,不改外来锁定输入。
准备失败或业务文件已确认恢复后,才逆深度清理本次创建且同身份的空业务目录。
- 恢复未决或提交未知时,即使为空也保留父目录,因为后续文件恢复依赖其身份。
- 目录清理失败保留原 file-set 真结果,并令投影不能声称完整恢复。
- 正常成功保留必要目录。
强制终止后原 recoverFileSet 只恢复文件,本次业务父目录可能残留;没有持久目录所有权记录时不猜测清理,也不称整体投影已恢复。
- 不增加目录日志或自动 TTL。
恢复业务字节不等于没有写入。
- zeroWriteSuccess=true 仅用于确实没有发生业务或机制文件系统修改且领域仍一致的路径;写过后恢复成功也不能标为零写入。
- 私密根/日志/材料保留要明确报告;freshRoot 失败后不能无条件声称整个根恢复为空。
- 目录创建/删除要求相应系统刷盘请求,失败保留已知与未知事实,不声称断电安全。
4. 可观察副作用与回调机制¶
applyFileSet 的 options 增加 beforeMutation 与 afterMutation 两个领域回调,上下文冻结为 {index, path, action}。
- 串行 await 执行;beforeMutation 在原最终原生根/父/目标重核之前调用,回调不能用旧检查放行竞态;
- afterMutation 只在真实修改、机制后验及 applied 事件成功后调用。
- 回调抛错/拒绝仍处于 commit 之前,并进入原自动恢复流程;不在 recover/prune 调用,不重放、不自动重试。
- 可信回调自行负责结束,validate 超时期限不覆盖它。
- file-set 沿原 apply-failed / apply 错误形状保留因果消息;Kit 在局部闭包中保留精确领域原因,不能覆盖原生失败优先级。
5. 工程检查如何识别恢复材料¶
inspectFileSetRecovery 支持两种合法 environment 形状:{filesystem: "ntfs"} 与 {filesystem: "ntfs", cooperativeWriters: true}。
- 调用方声明的 filesystem 为 ntfs 仅表示意图,不构成对实际文件系统类型的证明;只读检查不要求独占、合作确认或预先维护观察,返回前复核参与者、事件边界、全部所检目录身份与成员集合。变化、读失败或不确定即拒绝,不自动重试。
- 接口复用适用的运行时、文件系统及根绑定检查。
- 其他值或包含未知字段的 environment 均拒绝。
core-check 保留 listTargetEntries 的完整遍历、链接逻辑与特殊项检查;
- 仅对 Windows 根级精确路径 .foundation-file-apply 进行公共 inspector 核验后分类,材料由机制合同解释,无需目标 registry 自注册。
- 嵌套同名、近似名路径继续沿用原分类规则。
核验失败时生成原 core findings,保留错误原因,不可由 artifact 或 handwritten 模式放行。
- 退出码定义为:机制核验失败 → 2,普通业务分类失败 → 1,无问题 → 0。
- core-check 仅捕获一次根绑定并复用;不暗填 cooperativeWriters,顶层报告字段不变。
- 业务 managed/ownership 或显式读取声明不得占用保留机制命名空间。
旧 inspector 携带 cooperativeWriters: true 的调用继续有效,新 core-check 不传该字段,缺少确认的 mutation 仍拒绝。
- 合法空根、完成操作与合法 prune 均需通过验证;
- 未知文件或目录、损坏材料、链接或特殊项、参与者、未终结操作及观察期间变化均须失败关闭。
- 原业务字节断言保持不变,不得自动改写 registry、删除或 prune 材料以遮蔽问题。
安装文件的单链接前提¶
Windows 上的 fixed-set 候选来源要求部署文件必须为普通文件,且仅有一个硬链接(nlink=1),不能是符号链接或具有多个硬链接的文件。此前提为相关来源安全读取的必要条件,不因工具链或安装方式而放宽。
实测 pnpm 10.30.0 在同卷安装时默认 auto 导入会优先使用硬链接,导致预构建文件在 store 与安装目标间共享同一 inode,nlink=2。该行为违反单链接前提,触发原读取器拒绝,即使文件内容摘要完全一致。因此,默认 pnpm 安装方式不满足 fixed-set 候选的部署前提,不能宣称其已兼容 Windows 候选验证。
为在本次安装中满足安全前提,调用方可在该次安装命令中显式使用 --package-import-method=copy,确保安装文件与 store 文件独立,且仅保留一个硬链接。该选项仅在本次调用中生效,不修改全局 npmrc,不改写或去链接原 store,也不放宽产品读取器的权限检查。其余来源、权限、NTFS 元组与闭包校验仍需完整执行。参数 --package-import-method=copy 仅提供满足前提的调用路径,不证明最终安装文件具备 Windows 候选资格。资格判定依赖实际运行时检查与独立审阅。
固定候选的来源权限¶
Windows 平台下,fixed-set 候选来源的权限记录严格基于真实文件系统权限观测,不依赖发行模式(mode)推断或合成值。所有四平台发行二进制在已绑定 manifest 中均声明为 0644,Windows 仅按此精确发行模式核验,不比较 NTFS 合成 mode;原平台构建收据中的 Darwin 0755 不属于此处的发行值。四平台、manifest/receipt/SBOM、ABI、exports、大小与字节摘要绑定继续保留,POSIX 仍比较实际 mode,不改历史发行字节。
builder 在 Windows 上返回 projection-manifest v3,其 platform: win32、schemaVersion: 3;POSIX 仍返回原 v1 清单字节。builder 只构建,不生成或消费 operationId,运行参数由调用方明确传给 runProjection。另一个对象 foundation-projection 来源记录在 Windows 使用 schemaVersion: 2、platform: win32,POSIX 仍为原 v1 字节。
source.fixedSetCandidate.files 中的十个来源成员(六个源码/JSON/NOTICE 及四个二进制)的元组结构由 {path, type, mode, sha256} 更新为 {path, type, mode: null, permissionObservation, sha256},其中 type 仍为 regular。权限信息 permissionObservation 与内容摘要 sha256 均通过同一次原生绑定读取获得,使用公共 createFilesystemRootBinding/readFileBound 接口,不依赖前后 lstat 拼接;描述符不进入 provenance。
二进制文件的权限事实以真实 Windows 安全读取为准,不混入发行 0644;发行权限已由 manifest 及其摘要完整表达。其他 source.foundation 记录仅包含路径、摘要与角色,不进行权限字段扩展或改造。
输入 releaseReceiptPath 与其 tarball 维持原严格路径、普通单链接、身份/大小/SHA 绑定,不伪造其发行属性。直接消费仅投影 fixedSet.files 字节,目标写入策略遵循本页 Windows 投影合同,不将来源权限用作目标模板。
宿主启动与会话许可¶
WorkBuddy 的 Windows 接线保留已选定的原安装启动器;版本探测与业务调用使用同一批准身份。Kit 按 Harness 的 Windows 可执行入口合同 为无后缀 Node 启动器明确传入所选 Node 的规范路径及绑定根,调用已有 observeExecutableIdentity,直接使用其 launch.file 与 launch.argvPrefix,并在每次启动前重新核对原批准身份;发现字节、权限或根绑定变化即拒绝,不把变化后的事实重新设为批准基准。
仅该宿主的 Windows 环境增加 CODEBUDDY_FORCE_LITE_WB_BUNDLE=1,HOME 沿用真实用户状态根,隔离的 CODEBUDDY_CONFIG_DIR 作为 Skill 发现配置根。固定参数、模型策略及宿主管理认证边界保持不变。
调用方在本次 Windows WorkBuddy 隔离会话中,通过在 fixtureMembers 中显式声明固定成员 workbuddy-settings.local.json,并结合原 fixtureClosureDigest 对该文件的存在性与确切字节进行绑定,提供本次明确授权的许可规则。仅当该文件在 fixtureMembers 中被明确声明,且原 fixtureClosureDigest 对包含该成员的整组夹具校验通过时,本方案才启用;若未在 fixtureMembers 中声明,则不启用本机制,调用行为保持原状,不拒绝调用。仅当文件已声明但实际缺失或原夹具闭包校验不通过时,才沿用原验证失败行为拒绝调用。
许可策略以闭结构 {permissions:{allow:[...]}} 形式提交,allow 数组必须为有限、非空且无重复项。仅接受以下三类规则,且均不得使用通配符、shell 前缀或目录级宽授权:
- 无通配的完整
Read文件路径规则:用于授权读取调用方明确允许的输入,或对既定输出的存在性检查与结果回读。读取权限不得扩展至未声明的父目录或潜在消费者材料,即使目标文件尚未创建,也视为正常准备状态,不可据此推导出对目录的读取授权。 - 无通配的完整
Write文件路径规则:用于授权写入调用方明确允许的输出路径。写入仅限于声明的输出路径,不得包含裸工具或记忆写入。 - 无通配的完整
PowerShell命令规则:用于授权执行特定命令,且必须为完整命令字符串,不可含通配符或 shell 前缀。
不得从输入或输出路径绑定自动推导工具许可,也不新增请求或结果字段、摘要、私有选择标志或顶层 Schema。调用方必须显式提供本方案使用的许可规则,无新增开关或控制层。该 JSON 不接受模型、环境变量、hook、MCP、默认许可模式、信任目录及其他设置字段。
Kit 在 host-verification.mjs 的 Windows WorkBuddy 分支中,将调用方许可策略的原始字节写入本次受保护会话目录 sessionRoot/.codebuddy/settings.local.json。来源文件和投影文件均须通过既有安全读取、普通单链接文件、链接拒绝、根身份与权限检查。启动前及调用后均需复核字节一致性、权限状态与原绑定身份;一旦发现字节、权限或身份变化,立即按原失败合同处理,不将新事实重新捕获为批准基准。
仅建立本次会话所需的私密材料目录;不修补已有宽权限目录,不写真实用户或全局设置。CODEBUDDY_CONFIG_DIR 仅承载原隔离 Skill 发现布局,不新增 settings 成员。真实 HOME、认证状态、原安装启动器、已选模型、固定参数(含 dontAsk)及原平台宿主身份保持不变,原 PE 身份及启动分支不改变。
验证记录须明确区分三类行为:
- 显式规则命中:有原始证据支持该显式规则实际被使用;未实际使用的规则不能写成已测命中;
- 原厂内置安全放行:系统自动允许的、未在
allow中声明但被认定为安全的操作,不等同于规则命中; - 实际拒绝:因权限不足、路径未授权或命令未声明导致的拒绝。
不得将原厂安全放行推断为所有命令的通用许可,亦不得宣称本文件构成操作系统沙箱或全部有效许可的封闭集合。完整命令规则不能声明“仅运行一次”,某次执行成功或失败也不得扩大为对其他命令的保证。工程业务结果、真实写出行为、proof-create 出证,以及未声明写入或追加不同命令的拒绝,均依据实际输入与原始证据判断,不以进程成功或结构合法充作领域通过。
最终仍需在真实 Kit 环境中分别验收“采用诊断”“静态工程审阅”和“工程初始化”三个 Skill。
WorkBuddy 2.165.0 的命令许可匹配¶
在 WorkBuddy 2.165.0 中,调用方必须分别记录工具实际执行的 command 与 PowerShell 规则中的匹配文本。实际执行的 command 必须保留执行所需的引号,以确保与原生 shell 环境行为一致。WorkBuddy 原厂解析器在处理时会剥除各参数的外层单引号或双引号,再将命令名与参数以单空格连接,生成 fullCommand 用于匹配判断。
匹配逻辑采用 trim 后的完整字符串进行精确比较,因此原执行字符串中保留的引号写法不一定能直接作为匹配文本使用。匹配文本必须是剥除外层引号并以单空格拼接后的 fullCommand 形式,且不得包含通配符、shell 前缀或目录级宽授权。
允许列表中仍使用原 PowerShell(...) 规则形式,括号内填写对应的完整 fullCommand,不使用冒号语法。Kit 仅核验有限规则并投影原字节,不负责解释或转换命令匹配文本。复合命令按各 fullCommand 分别判断;实测中追加不同副作用命令被拒绝,仅证明该实际对照行为,不能推断为精确 argv 白名单或操作系统沙箱。
Windows PowerShell 5.1 与原生 Node 间 JSON 传递的等价转义表示¶
在 Windows PowerShell 5.1.22621.6133 与原生 Node 22.22.2 的组合环境下,直接将包含双引号的 JSON 字符串通过单引号包裹传递给 node -e 命令,会导致 Node 接收到的 process.argv[1] 中的双引号被丢弃,从而破坏 JSON 合法性。例如,原始 JSON 字符串 {"entries":[]} 若以 '{"entries":[]}' 形式传递,Node 将接收为 {entries:[]},不再构成合法 JSON。
为确保原 JSON 字符串在传递过程中保持结构完整,可对内部双引号使用反斜杠转义,即使用 '{\"entries\":[]}' 作为传递参数。采用该等价传递表示,可使 Node 收到原始合法 JSON 字符串。以上结论仅覆盖该实测版本组合,不能推广为 PowerShell 7 或其他 shell 的验证结果。
本节所用诊断示例中,entries 空数组仅为验证 process.argv[1] 实际内容的临时构造,不构成合法工程声明。正式调用 --engineering 时,必须传入完整、已确认且符合合同的工程对象 JSON 字符串,而非文件路径。排查问题时,应优先在无敏感数据的诊断环境中核实实际 process.argv 内容,而非修改 Kit 的 JSON 解析器或目标声明以适应错误传参。
node -e 'console.log(process.argv[1])' '{"entries":[]}'
node -e 'console.log(process.argv[1])' '{\"entries\":[]}'
{entries:[]}
{"entries":[]}
runBranchFieldCheck¶
API 定义¶
runBranchFieldCheck({ root, branches }) 接受显式非空本地目录路径 root 和非空数组 branches。每项 branches 必须包含以下六个必填字段:sourceRef、line、column、resultIdentifier、schemaRef、schemaPointer。其中,sourceRef 与 schemaRef 为根内相对路径,分别指向源文件与 Schema 定义文件;line 与 column 为从 1 开始的安全正整数,精确指向有效 AST 节点的起点;resultIdentifier 为符合 ASCII JavaScript 根标识符命名规则的字符串;schemaPointer 为空串时表示选中 Schema 根节点,非空时为 RFC6901 指针,指向对象定义。
可选字段 nodeType 仅接受 IfStatement 或 BinaryExpression,省略时默认为 IfStatement。节点起点必须精确匹配 AST 中该节点的起始位置:IfStatement 指整个 if 语句的起始位置(即 if 关键字所在行列),而非其 test 子表达式的起点;BinaryExpression 指该表达式自身在源码中的起始位置,不能以根标识符或运算符位置替代。在无括号的直接比较中,节点起点与最左端根标识符重合;若左侧成员访问带括号,节点起点可能从左括号开始。例如 export const ok = (packet.status) === 'READY'; 中,BinaryExpression 节点起点为 1:19,根标识符 packet 起始于 1:20,若选择 1:20 则无法匹配有效节点,返回 insufficient 且不执行任何比较。
若存在未知字段、未知 nodeType、必填字段缺失或重复选择(以六字段身份与有效 nodeType 为依据去重,省略 nodeType 与显式指定 IfStatement 视为同一项),均按参数错误拒绝。整个请求(含显式 nodeType)在首次 await 前完成复制。
CLI 命令¶
skill-family-kit check branch-fields --root <dir> --selection <relative-json> --json
- selection 文件仅允许 branches 字段,与 API 一致;
- 复用既有严格选择文件读取方式;
- 缺参数、缺 --json、未知或重复选项、坏请求时退出码 2;
- 产生真实发现或检查不足时退出码 1;
- 仅当结果为 complete / ENGINEERING_CLEAR 时退出码 0。
输出结构¶
结果采用 professional-conclusion 格式:
provider.entry:runBranchFieldCheck;subject.ref:实际根路径;details.branches:保留原六个选择字段及index、source/schema摘要、status、reason和comparisons。仅当调用方显式传入nodeType时才回显该字段,旧请求不额外补写;details.closure:既有闭包信息或null。
每条 comparison 包含:
- 源码字段链:属性链的数组形式,表示从
resultIdentifier开始的字段访问路径; - 运算符:
===或!==; - 字符串字面值:运算符右侧的字符串字面量;
- 字段 Schema 指针(
schemaPointer):字段对应的 Schema 指针; status:取值为checked、findings或insufficient;reason:具体原因说明;- 实际存在的
enum/const成员:列出 Schema 中实际声明的枚举或常量值。
scope.checked 仅列出已完成比较的 branch-<序号>-comparison-<序号>,其中第一个序号对应 details.branches 中的 index(从 1 开始),第二个序号对应该分支内 comparisons 数组中的位置(从 1 开始),两个序号共同标识一次比较,组合保持唯一。
当字段没有 enum 或 const 定义时,仅完成字段定位,不认定字面值有效。
算法与错误处理¶
AST 选取规则¶
仅匹配指定类型且起点唯一、精确的 AST 节点;无匹配或不唯一时返回 insufficient,且 comparisons 为空。IfStatement 仍对其 test 按原有限 &&/|| 叶子算法进行检查。BinaryExpression 仅承接同一行、以 resultIdentifier 为根的非计算、非可选 ASCII 直接属性链、=== 或 !== 运算,且右侧无转义字符串字面量。在 BinaryExpression 模式下,若选中节点但语法不支持,或位置不匹配、不唯一,均返回 insufficient 且 comparisons 为空。新模式不选择整个 LogicalExpression,需多个比较时调用方应分别选择叶子节点。注释、字符串、函数调用、可选链、计算属性、模板字面量、其他语言或位置不符的节点均不猜测。保持原 Schema 的 properties、enum、const 支持边界,所有实际读取资源摘要闭包与漂移撤销机制不变;闭包非原子快照,不执行源码,不推断运行真假或完整覆盖。
Schema 核对规则¶
- 仅从所选对象沿直接
properties链定位; - 仅核对直接
enum或const的成员关系; - 选中路径上的
$ref、组合、条件、patternProperties或未知约束原则上保留不足;本批唯一的排除形状如下,不增加通用求解器; - 即使是本地片段
$ref也不解析; - 无关兄弟属性的约束不影响已选字段;
- 缺字段仅在以下条件成立时可产生
findings: - 该层
type为object; properties为对象;additionalProperties为false;- 无其他不支持约束;
- 缺字段时,开放对象或不确定封闭性为
insufficient;已声明字段不因对象开放而失去直接定位依据; enum必须为非空数组,const使用真实 JSON 值,逐一比较实际字符串成员;enum与const同时出现时分别核对,不把它们合并成另一套值域;没有两者时只贡献字段定位;- 不判断其他 Schema 条件、完整对象有效性、业务状态或分支穷尽。
其他同级字段的条件必填边界¶
当仅检查所选对象的直接属性时,可排除一类不涉及目标属性的条件必填结构:该对象的 allOf 必须为非空数组,且每项恰好包含 if 与 then;其中 if 仅含 properties 与 required,then 仅含 required。if.properties 的键以及两处 required 数组中的成员必须均为该对象已声明的其他同级属性,且不得包含目标属性。此排除仅基于结构与名称匹配,不涉及条件求值、不解析子 Schema 内容,亦不推导整对象是否可满足。
其他组合形状、else 分支、选中路径的引用,或这三处名称位置涉及目标属性时,均视为不足。该边界不扩展至多层属性链的嵌套组合推导。必须保留限制说明:未检查其他字段的条件必填状态,不证明比较值在任意整对象中有效,亦不保证完整状态全集或 Schema 合规。沿用原有 scope.checked 与 limitations 表达,不新增请求参数或协议字段。
原 release-run Schema 的两项根条件仅依据 command 与 stateSequence 要求其他字段存在,未涉及 status。因此,可核对原源码中对 status 的引用、Schema 直接声明该字段,以及 PARTIAL 属于其直接枚举。不得删除原件 allOf 或替换为简化 Schema。
闭包与漂移处理¶
- 读取、解析失败或不支持语法均视为
insufficient,不将缺资源转化为产品字段发现; - 结果保留读入字节摘要;
- 闭包再读与原摘要不一致时,将依赖这些资源的比较(包括
findings)降为insufficient; - 同一路径多次读取有冲突也降级;
- 闭包失败使对应观察全部不足。
状态判定逻辑¶
- 有发现加未知 →
partial / ENGINEERING_FINDINGS; - 没有有效贡献 →
not-performed / ENGINEERING_CHECK_INCOMPLETE; - 全部支持且无发现 →
complete / ENGINEERING_CLEAR; - 独立未知不抹除另一项有稳定前提的
findings: - 有发现 + 未知 →
partial; - 无有效贡献 →
not-performed; - 全部支持且无发现 →
complete。
既有 reader 仅解释局部结论,不重跑、不认证作者,不将局部 CLEAR 提升为完整工程审阅或发布批准。
runPublicSurfaceBindingCheck¶
用途与调用方责任¶
本接口用于验证同一业务语义下,Skill 身份、Python 路由声明、Method 定义与四份协议 Schema 的直接声明是否一致。检查聚焦于六组显式声明的匹配关系,不涉及业务逻辑同一性、运行时分派、条件分支覆盖、Schema 内容有效性、安装加载流程或发布批准。调用方负责确认文件属于公开范围、两个入口属于同一业务且条件一致、Schema 是本次检查的权威来源,以及选集是否完整。
调用输入与结构¶
调用接口为 runPublicSurfaceBindingCheck({root, bindings}),参数要求如下:
root:显式非空本地目录路径,作为本次资源读取根。bindings:非空数组,每项包含以下字段,所有嵌套字段均必填,不接受未知字段或完全重复项。入口在首次await前复制这些嵌套字段。
绑定项字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
skill |
{ref, frontmatterKey} |
ref 为 Skill 文件路径(非空字符串);frontmatterKey 为 YAML frontmatter 中选中字段名(非空字符串)。 |
route |
{ref, startLine, endLine, constant, entryKey} |
ref 为 Python 源码路径(非空字符串);startLine、endLine 为从 1 起的安全正整数,endLine >= startLine,准确指向根级简单字典赋值语句的完整行范围;constant 为 ASCII Python 标识符;entryKey 为该字典的键名(非空字符串),非键值。 |
method |
{ref, idPointer, profilePointer, parameterRefPointer, resultRefPointer} |
ref 为 Method JSON 文件路径(非空字符串);idPointer、profilePointer、parameterRefPointer、resultRefPointer 为 RFC6901 指针,空串表示根值,支持 ~0/~1 转义,仅访问实际自有属性。 |
schemas |
{task, result, parameters, domainResult} |
四个 Schema 路径均为非空字符串,沿现有严格收容机制读取。 |
CLI 调用形式为:
skill-family-kit check public-surface-bindings --root <dir> --selection <relative-json> --json
--selection指向仅含bindings数组的 JSON 文件,格式与 API 一致。- 返回码:
0=complete/ENGINEERING_CLEAR,1=complete/ENGINEERING_FINDINGS、partial/ENGINEERING_FINDINGS、partial/ENGINEERING_CHECK_INCOMPLETE或not-performed/ENGINEERING_CHECK_INCOMPLETE,2=bad parameter或unhandled mechanism error。 - 坏参数时抛出现有
SFC2003异常,意外异常传播至调用层。
实际比较逻辑¶
每条绑定读取七份完整文件:Skill Markdown、Python 源码、Method JSON 和四份 Schema JSON。CST(具体语法树)用于定位 Python 声明与显式用法,YAML frontmatter(文件头元信息)用于读取 Skill 身份。执行六组直接声明比对,每组结果为 actual 与 expected 的字符串对比,状态为 status,原因 reason。
| 比较序号 | 比较内容 | 读取来源 | 验证规则 |
|---|---|---|---|
| 1 | skill.frontmatterKey 所选值 vs method.idPointer 指向的值 |
Skill YAML + Method JSON | 二者必须为直接非空字符串,相等即通过;不支持类型转换或 URI 路径解析。 |
| 2 | route.entryKey 对应的字典值 vs method.idPointer 指向的值 |
Python 路由字典 + Method JSON | entryKey 为键名,非值;所取字典值必须与 Method 身份值完全一致。 |
| 3 | method.profilePointer 指向对象的 taskContract 字段值 vs schemas.task 的根 $id |
Method JSON + Schema task | 二者必须为直接非空字符串,相等即通过。 |
| 4 | method.profilePointer 指向对象的 resultContract 字段值 vs schemas.result 的根 $id |
Method JSON + Schema result | 二者必须为直接非空字符串,相等即通过。 |
| 5 | method.parameterRefPointer 指向的协议 URI 字符串 vs schemas.parameters 的根 $id |
Method JSON + Schema parameters | 二者必须为直接非空字符串,相等即通过。 |
| 6 | method.resultRefPointer 指向的协议 URI 字符串 vs schemas.domainResult 的根 $id |
Method JSON + Schema domainResult | 二者必须为直接非空字符串,相等即通过。 |
- 所有比较要求
actual与expected均为非空字符串。 - 不跟随 Method 中错误 URI 转读另一份 Schema;若指针指向无效路径或类型不支持,视为读取失败。
- 所有必需值和支持前提完整时,值不等产生
findings;读取失败、缺失或不支持均为insufficient。值相等不是进入检查的前提。
支持边界与失败条件¶
支持范围
- Skill:文件开头必须为完整的 YAML 映射头区,
frontmatterKey所选值为直接非空字符串,拒绝重复键、alias、merge、未知 tag 或歧义。 - Python 源码:使用
@lezer/python构建完整 Python 具体语法树(CST),不执行、导入、编译或eval目标代码。若全树存在语法错误或恢复节点,则绑定检查视为不足。所选语句必须为唯一的根级简单赋值NAME = {纯字典},字典本身非空,键与值均为无转义双引号字符串,键唯一;未选中项的键或值允许为空字符串(如"": ""或"other": ""),但不强制非空。entryKey本身必须非空,且六组实际被选比较值(包括所选路由字典值)均须非空;缺失、类型不支持或空选值均视为不足。显式使用仅支持以该名为基对象的NAME[固定字符串或简单标识符]只读取值,函数体和赋值右侧读取可支持,无关类型注解、注释或字符串不阻断。选中名或成员的写入、元组/嵌套目标、增强赋值、删除、遮蔽绑定或未知用法均视为不足。显式直接调用exec、eval、globals、locals、vars均视为不足;同一直接名称仅加透明普通括号(如(globals)())仍属此类调用,不可漏过。普通字符串或注释中出现这些名称或调用形式不触发该限制。严格基于 CST 与显式用法,不证明任意 Python 编译、运行时不可变或不存在间接影响,也不推导别名关系或调用图。 - JSON 值:由
JSON.parse解析,拒绝重复键(含转义后同名)及无法消歧的情况。
失败条件(导致 insufficient 或 findings)
- 任何必需资源重复读取冲突或闭包漂移,撤销依赖该资源的整条绑定所有比较(含
findings)和checked。 - 指针缺失、类型不支持、读取失败均视为“不足”(
insufficient),不构成冲突。 - 共享资源失效会撤销所有依赖绑定;CLI 选集漂移影响整批。无法确定闭包失败的影响范围时,不保留未证明的完成。不受影响的独立稳定发现仍保留。
- 读取回执或闭包非原子快照,不保证安全隔离。
- 未满足上述支持边界时,视为
insufficient,不进入比较阶段。
结果解释与聚合逻辑¶
单绑定状态
每绑定输出 status 为以下之一:
- checked:六组比较全部完成,无冲突。
- findings:至少一组比较值冲突。
- insufficient:读取失败、资源冲突、闭包漂移或未满足支持边界。
比较项结构
每条完成的绑定包含六项 comparisons,每项含:
- actual:实际读取值。
- expected:预期值。
- status:checked 或 findings。
- reason:本项比较的说明。
scope.checked 仅记录 binding-<index>-comparison-<序号> 格式标识。不足绑定的 comparisons 数组为空。
整体聚合结果
| 完成状态 | 聚合结果 | CLI 退出码 |
|---|---|---|
| 所有绑定完成,无冲突 | complete/ENGINEERING_CLEAR |
0 |
| 所有绑定完成,存在稳定冲突(findings) | complete/ENGINEERING_FINDINGS |
1 |
| 完成与不足混合,且存在稳定冲突 | partial/ENGINEERING_FINDINGS |
1 |
| 完成与不足混合,无稳定冲突 | partial/ENGINEERING_CHECK_INCOMPLETE |
1 |
| 所有绑定均为不足 | not-performed/ENGINEERING_CHECK_INCOMPLETE |
1 |
complete仅当所有绑定完成(checked或findings)时成立。complete/ENGINEERING_FINDINGS仅指稳定声明冲突,不包含因漂移或读取失败导致的insufficient。- 闭包漂移导致的整绑定
insufficient,不视为冲突,仅影响聚合状态。 - 空或重复请求拒绝,不返回
CLEAR。
输出结构
返回值沿用 professional-conclusion:provider.entry 为 runPublicSurfaceBindingCheck,subject.ref 为实际读取根。details.bindings 的每项直接保留 skill、route、method、schemas 四组选项,另含从 1 起的 index、实际 resources 读取回执数组、status、reason 和 comparisons。回执记录实际读取的 ref、sha256 和 bytes,并在绑定资源中保留 role,不保存文件正文。
details.selection 为 CLI 选集读取回执,API 调用时为 null;details.closure 为实际资源闭包,未取得时为 null。解释结果时,同时阅读 outcome、scope.checked 和 scope.limitations,不要只看发现数量。
只读与边界说明¶
- 本接口为只读,不扫描未选树、不启动目标、不联网、不写目标。
- 保留真实原始结论,后续通过
readProfessionalProof或check proof读取。 - 局部
CLEAR不证明完整METHOD003、业务同一性/条件、Schema 内容有效、运行时分派、安装加载或发布批准。
runNativeEntryBindingCheck¶
用途与调用方责任¶
本接口用于验证共同源清单、平台清单与两端实际 Skill 之间四组显式声明的受收容身份关系。检查范围限于已声明的身份类型,不涵盖 Markdown 业务正文、方法契约版本、自然语言身份、URI 跟随、Registry、安装加载或发布批准。
该接口自版本 0.37.0 起引入。正式消费须基于实际安装的精确已发布版本及其公开入口进行验证;源码验证仅在获准范围内有效,不得替代正式消费。调用方需确保共同清单的权威性、业务关系的一致性以及选集的完整性。
调用输入与结构¶
接口调用形式为 runNativeEntryBindingCheck({root, bindings}),参数要求如下:
root:显式非空本地目录路径,作为本次资源读取根。bindings:非空数组,每项仅含以下四字段,不接受未知字段或完全重复项。入口在首次await前复制这些字段。
绑定项字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
commonManifestRef |
非空字符串 | 调用方选定的共同 JSON 清单,按 root 路径定位。 |
commonSkillIndex |
大于等于零的安全整数 | 精确指定共同清单 skills 数组中的索引项。 |
platformManifestRef |
非空字符串 | 平台 JSON 清单,按 root 路径定位。 |
mappingIndex |
大于等于零的安全整数 | 精确指定平台清单 logicalMappings 数组中的索引项。 |
同一 platformManifestRef 与 mappingIndex 被重复选择但指定不同共同记录时,视为请求冲突并拒绝。下标超出范围属于资源不足,不是非法参数。额外 JSON 字段保持不透明。
CLI 调用形式为:
skill-family-kit check native-entry-bindings --root <dir> --selection <relative-json> --json
--selection指向仅含bindings数组的 JSON 文件,格式与 API 一致。- 返回码:
0=complete/ENGINEERING_CLEAR,1= 发现或不足,2= 坏参数或未处理机制错误。 - 坏参数时抛出现有
SFC2003异常,意外异常传播至调用层。
路径基准与解析规则¶
所有路径解析均基于以下三个固定基准,且严格遵循收容与读取规则:
- 共同清单引用、平台清单引用与平台清单的
source:都相对root解析。 - 共同清单
sourceRoot:相对root解析,当其值严格等于.时,仅作为已解析root的目录基准标记,不提交给classifyPathInput或resolveContained;所选skills.source相对这个目录解析。 - 平台映射
path:相对平台清单所在目录解析,当该目录为.时,同样仅作基准标记。
除上述目录基准标记外,各原始路径段先分类,目录基准与最终文件沿既有收容和严格读取规则处理,不使用其他基准回退。原生声明若使用 URI、展开式、通配或 ~,记为不足。
实际比较逻辑¶
每条绑定读取平台清单、共同清单、声明来源、平台 Skill 与共同 Skill。同实际文件复用该次观察,并可同时保留多个资源角色。所有必需资源完整后,按固定顺序比较四组身份:
| 比较序号 | 比较内容 |
|---|---|
| 1 | 平台 source 解析后的实际清单根内引用 vs commonManifestRef 解析后的实际清单根内引用 |
| 2 | 平台映射 physicalName vs 实际平台 Skill 的 frontmatter.name |
| 3 | 平台映射 logicalName vs 所选共同 skills 项的 logicalName |
| 4 | 所选共同 skills 项的 logicalName vs 该共同项 source 实际指向 Skill 的 frontmatter.name |
第一组使用受收容路径解析所得的实际文件身份,其余三组对实际字符串逐字比较。路径基准与安全处理沿上节规则。
支持边界与失败条件¶
- 共同清单必须有直接非空字符串
sourceRoot与数组skills;所选项必须有直接非空字符串logicalName、source。 - 平台清单必须有直接非空字符串
source与数组logicalMappings;所选项必须有直接非空字符串logicalName、physicalName、path。 - 两份实际 Skill 仅解析文首完整 YAML 映射中的直接非空字符串
name。 - 声明来源与所选共同清单解析到同一实际文件时复用观察;若不同,声明来源也须为可读、无歧义的 JSON 对象,才能确认来源地址矛盾。其余比较仍以调用方明确选择的共同记录为准。
- 任一必需资源重复读取冲突或闭包漂移,撤销依赖该资源的整条绑定所有比较(含
findings)和checked。共享资源失效会撤销所有依赖绑定;CLI 选集漂移影响整批。不受影响的独立稳定发现仍保留。 - 读取失败、缺失、不支持、下标越界或歧义均为
insufficient,不构成冲突。完整可读的直接不等才是findings。
结果解释与聚合逻辑¶
每绑定输出 status 为 checked、findings 或 insufficient。完成的绑定包含四项 comparisons。scope.checked 仅记录 binding-<index>-comparison-<序号>。不足绑定的 comparisons 数组为空。
| 完成状态 | 聚合结果 | CLI 退出码 |
|---|---|---|
| 所有绑定完成,无冲突 | complete/ENGINEERING_CLEAR |
0 |
| 所有绑定完成,存在稳定冲突 | complete/ENGINEERING_FINDINGS |
1 |
| 完成与不足混合,且存在稳定冲突 | partial/ENGINEERING_FINDINGS |
1 |
| 完成与不足混合,无稳定冲突 | partial/ENGINEERING_CHECK_INCOMPLETE |
1 |
| 所有绑定均为不足 | not-performed/ENGINEERING_CHECK_INCOMPLETE |
1 |
返回值沿用 professional-conclusion:provider.entry 为 runNativeEntryBindingCheck,subject.ref 为实际读取根。details.bindings 的每项直接保留四个选择字段,另含从 1 起的 index、实际 resources 读取回执数组、status、reason 和 comparisons。回执记录实际读取的 ref、sha256 和 bytes,并在绑定资源中保留 role:platform-manifest、common-manifest、declared-source、platform-skill、common-skill。details.selection 为 CLI 选集读取回执,API 调用时为 null。
本接口为只读。局部 CLEAR 不证明 Markdown 正文、方法契约版本、安装加载或发布批准。旧 runPublicSurfaceBindingCheck 七来源六比较与 peer 联合检查保持不变。
同级适配器的专业结论¶
该入口在0.36.0版本引入,正式发布版本0.35.0中不包含该功能。未发布源码候选仅用于已授权的开发验证,不得据此宣称功能已正式发布;正式消费必须基于实际安装的精确已发布版本及其公开导出的API。
runPeerAdapterCheck({root, request, peerRoots})
精确签名与参数职责¶
root:检查对象目录字符串,由既有目录解析取得实际subject.ref。它不是某个 peer 的根,不对root再作树扫描,也不创建FileSystemRoot新类型。request:复用现有adapter-peer-verification-request结构,包含 2 至 16 个显式 peer 与完整逻辑映射,输入在首次await前完整复制。peerRoots:映射对象,键为peerId,值为对应适配器的规范绝对真实根路径,必须为显式提供、可读且路径合法。真实根继续满足既有根绑定合同。
调用与观察范围¶
- 固定
peerRoots中按peerId排序的第一个为锚点,对剩余每个peerId调用一次原verifyPeerAdapterDirectories接口,共 N−1 次(四 peer 为三次)。这里描述完整选集的必需 pair 数;前观察不足时,相应 pair 不调用并保留不足原因。 - 第一阶段:对每个显式
peerRoot执行一次前观察,调用createFilesystemRootBinding与observeFilesystemTree,记录绑定与成员路径、类型、SHA256、字节数、权限字段。 - 第二阶段:按
peerId排序,固定首个为锚,对其他 peer 各调用一次原verifyPeerAdapterDirectories。 - 第三阶段:对具备前观察的
peerRoot执行一次后观察,调用createFilesystemRootBinding与observeFilesystemTree。 - 仅保留路径、类型、摘要、字节数、权限等字段,不复制
contentBase64或文件全文,不创建永久 manifest、历史基准、锁、控制账或原子隔离承诺。 - 实际成功 manifest 与对应前观察的完整成员/原字节衔接;前后观察不一致、不可用或 manifest 不相符时,撤销关联 pair 的
checked状态及其发现归因。 - 真实原调用仍保留供定位,不因漂移或不一致而丢失。
来源闭包相等与逻辑映射语义相等都是等价关系,因此上述 N−1 个锚关系足以判断所选 peer 的联合一致性。原机制发现来源冲突时,可能不再比较同一 pair 的映射相等;结果不声称这些内部子比较均已运行。
输出与错误边界¶
completion为互斥条件,仅取值:complete:全部必需 pair 有效完成。partial:存在至少一个有效已完成 pair,但未全部完成。not-performed:无有效已完成 pair;可能已有失败调用,不等于未曾尝试。outcome.code独立于completion,取值:ENGINEERING_CLEAR:全部必需 pair 有效完成,无finding。ENGINEERING_FINDINGS:全部必需 pair 有效完成,且存在finding;或部分完成但存在finding。ENGINEERING_CHECK_INCOMPLETE:没有有效finding,且存在必需 pair 未完成。scope.checked仅列出实际有效完成的 pair,格式为pair:<anchor>:<peer>:equivalence,锚点固定为排序首peerId。未完成或漂移失效的 pair 不列入。- 真实
finding仅当满足: SFC2004且details.kind=closure-conflictdetails.peerId属于本次调用 pair- 输入/根/前后观察可对应
- 且未被漂移撤销
insufficient保留于:- 请求结构合法但对实际 SKILL 集合缺漏/悬空的 mapping
- 缺失 peer 目录
- 不可读/不安全/不支持的 peer 读取
- 未完成的 pair
- 非法全局请求结构(如未知字段、重复
peerId、根键集或坐标格式错误)在检查前抛出参数错误,抛出SFC2003,不返回not-performed等专业结论。 - 未知运行异常 继续抛出,不捕获,不改记为
insufficient或not-performed。 - 外部进程终止 时不保证结论存在,不承诺完整性。
原件与证明读取器¶
details含复制的selection、前后观察、实际 pair 原返回或异常的code、message、details及不足原因,不承诺保存 Error 堆栈等全部进程内部对象。- 宿主在获准证据位置独占保存真实返回,再交
readProfessionalProof解释;不重跑、不鉴伪。 - 禁止以
proof-create手填机械结果。 - 旧
verifyPeerAdapterDirectories、verifyHostPeers、成功verifiedSchema 和失败关闭行为保持不变。 - 本入口不判 Audit/SOURCE 规则,不验任意生成器,不承担独立共同资源或平台元数据检查,不证明宿主安装/加载/业务运行/发布。
- 完整源权威静态审阅等仍独立核收,不可由 peer 结论替代。
- 与语义/其他机械范围合选时分别保留原件,不汇总伪完整。