skill-family-harness-node 公共 API 参考¶
本页从真实导出(src/index.mjs 与各源模块)核对,不手写无法证明新鲜度的全集。每个公共入口按 hand-off §4.3 说明:签名、输入与输出、是否纯函数、文件/进程/Git/网络副作用、稳定错误码与 details.kind、前置条件与信任锚、since 与 stability、源文件与正例/负例测试、调用方仍拥有的业务语义。
Harness 是薄运行时:消费 Contracts,只实现业务中立机制;不拥有业务语义、编排、Git、网络与第二语言。包级常量:HARNESS_CAPABILITIES(22 项能力,闭集)、HARNESS_EXCLUSIONS(明确排除 business-semantics / workflow-orchestration / git-writes / model-calls / release-state / remote-network-access)。
能力分组(与 docs/agents/capability-catalog.json 对应):
- 契约校验 →
validateContractDocument/getValidator - 路径收容 →
classifyPathInput/resolveContained/readFileContained - 严格读取 →
readFileStrict - 身份绑定读取 →
createFilesystemRootBinding/readFileBound - 完整树观察 →
observeFilesystemTree - 固定集合发布 →
createFixedSetPublicationManifest/publishFixedSet/replaceFixedSetAtomic - 原子写 →
writeFileAtomic - 临时工作区 →
TemporaryWorkspace/withTemporaryWorkspace - 资源闭包 →
computeResourceClosure/digestBytes/closureContains - 进程监督 →
superviseProcess/validateTimeoutPolicy - 请求管线 →
parseRequest/processRequest - 报告 →
validateReportModel/renderReportMarkdown/buildBinding/verifyBinding/checkReport - 宿主适配机制 →
normalizeAdapterSource/buildAdapterClosure/materializeAdapterBuild/probeVersionVector - 可执行身份观察 →
observeExecutableIdentity - 机制批量 →
runMechanismCliBatch/--batch(0.19.0 candidate) - 持久状态底座 →
openStateStore/appendEvent/readSnapshot/verifyStateStore… - 多路径文件集合应用与恢复 →
applyFileSet/recoverFileSet/pruneFileSetRecovery(0.21.0 candidate) - 基线物化 →
computeDirectoryDigest/materializeBaseline(FND-ADR-009) - 只读 chokepoint →
createReadChokepoint(FND-ADR-009) - 策略化表面扫描 →
scanSurface(FND-ADR-009) - token 上界估算 →
estimateTokenUpperBound/estimateTokens(FND-ADR-009) - 通用上限守卫 →
openUsageGuard/appendUsageEvent/readUsage/closeUsageGuard(FND-ADR-009) - 机制错误 →
HarnessError/mechanismError/HARNESS_ERROR_KINDS
契约校验 (foundation.harness.contract-validation)¶
validateContractDocument / getValidator / resolveSchemaContext / validatorCacheSize¶
- 签名:
validateContractDocument(document, { schemaId, dialect, policy = "strict" } = {})getValidator({ schemaId, dialect, policy = "strict" } = {})resolveSchemaContext({ schemaId, dialect, policy = "strict" } = {})validatorCacheSize()- 输入:schema 上下文或契约文档。
- 输出:校验结果(语义同 Contracts
validateDocument,但经 Node 运行时复用缓存);缓存大小查询。 - 纯函数:否(
getValidator/validateContractDocument写入进程内以 schema 为键的校验器缓存)。 - 副作用:进程内内存缓存校验器实例;无文件/Git/网络。
- 稳定错误码与
details.kind:沿用 ContractsSFC1001/SFC1002/SFC1006;底层机制失败统一SFC2004+HARNESS_ERROR_KINDS的kind(如INVALID_PATH)。 - 前置条件与信任锚:已安装
skill-family-contracts;Ajv 8.20.0。 since/stability:0.2.0/stable。- 源文件:
packages/skill-family-harness-node/src/validation.mjs。 - 正例/负例测试:
packages/skill-family-harness-node/test/validation.test.mjs。 - 调用方仍拥有的业务语义:契约业务字段语义(语义定义仍在 Contracts)。
路径收容 (foundation.harness.path-containment)¶
classifyPathInput / resolveContained / readFileContained¶
- 签名:
classifyPathInput(input, platform = process.platform)resolveContained(root, relPath)readFileContained(root, relPath, { encoding } = {})- 输入:根目录(收容边界)与待解析的相对/绝对路径。
- 输出:受收容绝对路径或读到的文件内容。
- 纯函数:
classifyPathInput是;resolveContained/readFileContained为async,含只读文件系统访问。 - 副作用:只读文件系统访问(读取/解析);不写。
- 稳定错误码与
details.kind:机制失败抛HarnessError(SFC2004)+details.kind∈{PATH_TRAVERSAL, SYMLINK_ESCAPE, REALPATH_ESCAPE, INVALID_ROOT, ABSOLUTE_PATH, WINDOWS_DRIVE_PATH, WINDOWS_PATH, UNC_PATH, INVALID_PATH, READ_FAILED}。 - 前置条件与信任锚:调用方提供明确根目录;所有解析结果必须落在根目录内;Windows 盘符/UNC 逃逸同样拒绝。
since/stability:0.2.0/stable。- 源文件:
packages/skill-family-harness-node/src/paths.mjs。 - 正例/负例测试:
packages/skill-family-harness-node/test/containment.test.mjs、boundaries.test.mjs。 - 调用方仍拥有的业务语义:哪些路径是业务允许的选择规则(业务选择语义留在调用方)。
严格读取 (foundation.harness.strict-read)¶
readFileStrict¶
- 签名:
readFileStrict(root, relPath, { encoding?, expectedSha256? } = {})(async)。 - 输入:收容根目录、相对文件路径,可选的
utf8编码与小写 sha256 预期摘要。 - 输出:冻结回执
{ path, content, sha256, bytes, mode }。指定utf8时,content是字符串;省略编码时,content是Buffer。 - 纯函数:否,函数只读一个受收容的普通文件。
- 副作用:执行
lstat、open、read与文件身份复核;不写文件,不访问 Git 或网络。 - 稳定错误码与
details.kind:失败使用SFC2004。缺失文件返回missing-resource,摘要不符返回content-guard-rejected,目录返回read-failed,越界路径沿用路径收容的失败种类。 - 符号链接边界:叶节点符号链接始终拒绝。祖先目录可以是指向根内目录的符号链接;其规范路径仍须受
root收容。 - 前置条件与信任锚:
expectedSha256的来源与信任由调用方负责;摘要只覆盖实际读到的字节。 since/stability:0.6.0/stable。- 源文件:
packages/skill-family-harness-node/src/strict-read.mjs。 - 正例/负例测试:
packages/skill-family-harness-node/test/strict-read.test.mjs。 - 调用方仍拥有的业务语义:选择哪个权威文件、摘要从何而来,以及读取失败后的处置。
身份绑定读取 (foundation.harness.bound-read)¶
createFilesystemRootBinding / readFileBound¶
- 签名:
createFilesystemRootBinding(root);readFileBound(root, relPath, { rootBinding, encoding?, expectedSha256? } = {})(均为 async)。 - 输入:已规范化的绝对真实目录、受收容的相对 POSIX 路径,以及调用方先前批准的冻结根绑定。
encoding仅支持utf8;权威读取可带小写 sha256 预期摘要。 - 输出:根绑定为冻结可序列化值;读取回执为冻结
{ path, content, sha256, bytes, mode, statMode }。mode保持旧兼容含义(st_mode & 0o777);statMode是同次原生打开描述符fstat得到的完整 POSIXst_mode,包括文件类型与特殊权限位。 - 语义边界:以下 POSIX v1 描述保持;Windows 分支见页末。根与中间目录由固定四平台 N-API 闭包以不跟随符号链接的句柄相对方式获取;叶子必须是单链接普通文件。句柄不会逃逸,调用结束前关闭。绑定读取不提供删除或恢复状态机。
- 副作用:只读文件系统访问;不写文件、不触 Git、网络或进程。
- 错误:根身份不符、符号链接组件、缺失资源和摘要不符均失败关闭;不支持的 Darwin/Linux 架构不提供 JavaScript 回退。
since/stability:0.9.0/stable。- 源文件:
packages/skill-family-harness-node/src/bound-read.mjs与src/native/。 - 正例/负例测试:
packages/skill-family-harness-node/test/bound-read.test.mjs。
完整树观察 (foundation.harness.filesystem-tree-observation)¶
observeFilesystemTree¶
- 签名:
observeFilesystemTree({ root, rootBinding, symlinkPolicy?: { mode: "reject" | "record" } })(async)。调用方先用既有createFilesystemRootBinding批准根目录。 - 输入:已规范化的真实绝对目录及其根绑定。每次调用重新读取目录和普通文件,空树合法。
- POSIX v1 输出(Windows v2 见页末):私有
filesystem-tree-observation,含按路径排序的完整成员、根绑定和membersDigest。文件成员包含同次读取的contentBase64、sha256、bytes与完整 POSIXstatMode;目录成员只含路径、类型和模式,不伪造文件摘要。省略symlinkPolicy或使用reject时保持 0.14 的 UTF-16 关系顺序和既有原生语义;record在稳定、调用方隔离且无并发 namespace writer 的本地树上走 Node/JS 分支,使用 Unicode 码点顺序,记录 symlink 自身的targetBase64、bytes、statMode,绝不读取或递归 target。membersDigest按所选模式的成员顺序推导。 - 副作用:只读文件系统,不安装、不启动进程、不访问网络。结果含原始文件内容,调用方必须保护敏感数据。
- 失败语义:参数不合法抛
TypeError,机制失败沿SFC2004关闭,不把部分观察报告为成功。record 检测到观察期间的漂移即失败关闭,普通文件复用readFileBound,硬链接与特殊文件继续拒绝。 - 保证边界:每次检查同一根绑定,不使用旧缓存;record 是 best-effort candidate,不承诺事务快照、同 UID 恶意并发或 ABA 安全。消费者负责在宿主命令完成后调用,并保留 npm
.bin等领域接受规则;真实恶意并发威胁应交回 Foundation,不在本地复制 walker、native addon、Harness、schema、Registry、runner 或 receipt 链。 since/stability:0.13.0/candidate。观察完成不等于消费者接受载荷。- 源文件:
packages/skill-family-harness-node/src/filesystem-observation.mjs与src/native/bound_read.c。 - 正例/负例:
packages/skill-family-engineering-kit/test/plugin-verification.test.mjs的实际树观察与载荷政策组合测试。
可执行身份观察 (foundation.harness.executable-identity-observation)¶
observeExecutableIdentity¶
- 签名:
observeExecutableIdentity({ boundRoots, lookup, interpreterPolicy? })(async)。 - 输入:调用方提供的非重叠真实根绑定、绝对路径或显式
pathEntries查找,以及可选的显式解释器根策略;不读取 ambientPATH。 - 输出:逐次只读的可执行入口观察,含
canonicalEntry、symlinkChain、sha256、bytes、statMode、entryKind、解释器与launch计划。/usr/bin/envshebang 通过显式pathEntries找到解释器时,解释器观察保留候选入口的完整 symlink chain,不折叠成最终文件。 - 副作用:只读
lstat/readlink与既有readFileBound;不启动进程、不写文件、不使用跨调用缓存。 - 失败语义:路径越界、符号链接漂移或循环、非单链接可执行普通文件、解释器策略不符及字节变化均失败关闭;不返回部分身份结果。
- 保证边界:这是逐次点时观察,调用方必须在正式启动前紧邻重观察。它不证明 wrapper 控制流、ambient PATH、fd-exec、内核最终映像、签名信任、跨调用连续身份、宿主支持/生命周期或领域接受。
since/stability:0.15.0/candidate。观察完成不等于宿主资格或启动授权。- 源文件:
packages/skill-family-harness-node/src/executable-identity.mjs。 - 正例/负例:
packages/skill-family-harness-node/test/foundation-015-harness.test.mjs。 - 调用方仍拥有的业务语义:命令选择、正式启动、wrapper/argv 语义、签名与认证信任、宿主支持/生命周期资格、领域接受及重观察时机。
固定集合发布 (foundation.harness.fixed-set-publication)¶
createFixedSetPublicationManifest / publishFixedSet¶
- 签名:
createFixedSetPublicationManifest({ sourceRoot, targetParent, targetSegment });publishFixedSet({ sourceRoot, targetParent, targetSegment, manifest })(均为 async)。稳定入口也由skill-family-harness-node/fixed-set-publication导出。 - 输入:同一规范父目录下的源目录、目标父目录、一个安全目标段和此前冻结的完整集合 manifest。
- 输出:完整集合 manifest 与结构化 publication receipt。receipt 终态为
succeeded、refused、failed或indeterminate。 - 语义边界:发布使用 Darwin
renameatx_np(RENAME_EXCL)或 Linuxrenameat2(RENAME_NOREPLACE)的固定原生闭包;不使用检查后rename的 JavaScript 替代,不提供身份保护删除,不自动重试、回滚或恢复indeterminate。 - 副作用:仅在成功时对目标目录执行一次不替换发布;失败关闭。
since/stability:0.9.0/stable。- 源文件:
packages/skill-family-harness-node/src/fixed-set-publication.mjs与固定原生加载器。 - 正例/负例测试:
packages/skill-family-harness-node/test/stable-filesystem-operations.test.mjs与既有固定集合边界测试。
replaceFixedSetAtomic¶
- 签名:
replaceFixedSetAtomic({ sourceRoot, targetParent, targetSegment })(async)。包根与skill-family-harness-node/fixed-set-publication子路径均导出。 - 输入:已经完整生成的真实
sourceRoot、规范targetParent和一个安全targetSegment。源目录与既有目标必须是同一规范父目录下的兄弟目录;两棵树只允许真实目录与单链接普通文件。 - 输出:确认成功时返回目标路径、保留旧目标的
displacedTargetPath,以及publicationState=published、commitState=exchange-committed、verification=verified、durability=namespace-synced和两棵树的闭包摘要。 - 提交语义:复验父目录、源和目标身份后,在同一父目录句柄下只执行一次 Darwin
RENAME_SWAP或 LinuxRENAME_EXCHANGE。成功后,新集合完整位于目标路径,被置换的旧目标完整留在原sourceRoot;Foundation 不删除任一目录。 - 失败语义:受支持的提交前失败保持原目标路径和字节不变。机制失败抛
SFC2004+details.kind=atomic-replace-failed;details同时给出phase、publicationState、commitState、verification与durability。不支持的平台使用details.kind=unsupported-platform。 - 重试边界:该操作不是幂等操作。相同参数再次调用会交换回原状态;确认成功后,或收到提交后及不确定错误时,不得盲目重试。Foundation 不自动执行第二次交换、回滚或清理。
since/stability:0.18.0/stable。- 源文件:
packages/skill-family-harness-node/src/fixed-set-publication.mjs、稳定原生加载器与固定预构建闭包。 - 正例/负例测试:
packages/skill-family-harness-node/test/stable-filesystem-operations.test.mjs;Engineering Kit 离线投影由packages/skill-family-engineering-kit/test/candidate-profile-bundle.test.mjs覆盖。 - 调用方仍拥有的业务语义:暂存目录的生命周期、成功后的旧目标清理,以及提交后或不确定失败的取证与恢复决定。
原子写 (foundation.harness.atomic-write)¶
writeFileAtomic¶
- 签名:
writeFileAtomic(root, relPath, data, { mode = 0o644 } = {})(async) - 输入:已收容目标路径、文件内容(
string或Buffer)。 - 输出:写入完成的文件,字节与输入一致。
- 纯函数:否(落盘)。
- 副作用:在根目录内创建临时文件,先
fsync再rename覆盖目标;失败时回滚临时文件、不留残影。 - 稳定错误码与
details.kind:越界路径抛SFC2004+PATH_TRAVERSAL/越界类kind;非法数据类型 / 写失败+ ATOMIC_WRITE_FAILED。 - 前置条件与信任锚:目标路径经
path-containment验证在根目录内。 since/stability:0.2.0/stable。- 源文件:
packages/skill-family-harness-node/src/atomic.mjs。 - 正例/负例测试:
packages/skill-family-harness-node/test/atomic.test.mjs。 - 调用方仍拥有的业务语义:写入内容的业务正确性。
临时工作区 (foundation.harness.temporary-workspace)¶
TemporaryWorkspace / createTemporaryWorkspace / withTemporaryWorkspace¶
- 签名:
class TemporaryWorkspace(构造(options))createTemporaryWorkspace(options)(async)withTemporaryWorkspace(fn, options)(async,回调式生命周期)- 输入:可选前缀/标签。
- 输出:临时工作目录句柄;
with在回调结束后清理。 - 纯函数:否(创建并删除系统临时目录子目录)。
- 副作用:在宿主临时目录创建子目录,退出/异常时删除;不持久化。
- 稳定错误码与
details.kind:创建失败+ WORKSPACE_CREATE_FAILED;清理失败+ WORKSPACE_DISPOSE_FAILED;已释放后使用+ WORKSPACE_DISPOSED。 - 前置条件与信任锚:宿主提供可写临时目录(如
os.tmpdir);路径不逃逸出宿主临时根。 since/stability:0.2.0/stable。- 源文件:
packages/skill-family-harness-node/src/workspace.mjs。 - 正例/负例测试:
packages/skill-family-harness-node/test/workspace.test.mjs。 - 调用方仍拥有的业务语义:临时产物的最终去处(持久态转
state-store)。
资源闭包 (foundation.harness.resource-closure)¶
computeResourceClosure / digestBytes / closureContains¶
- 签名:
computeResourceClosure({ root, resources } = {})(async)digestBytes(bytes)closureContains(closure, relPath)- 输入:资源列表(路径 + 内容)。
- 输出:确定性闭包对象与 sha256 摘要;
closureContains判定某相对路径是否在闭包内。 - 纯函数:
digestBytes/closureContains是;computeResourceClosure含按root读取资源,属受控只读。 - 副作用:按
root只读读取资源;不写。 - 稳定错误码与
details.kind:非法/重复资源声明抛SFC2004+CLOSURE_CONFLICT/MISSING_RESOURCE。 - 前置条件与信任锚:资源为可序列化文本条目(二进制投影明确 unsupported);去重与排序固定。
since/stability:0.2.0/stable。- 源文件:
packages/skill-family-harness-node/src/closure.mjs。 - 正例/负例测试:
packages/skill-family-harness-node/test/closure.test.mjs。 - 调用方仍拥有的业务语义:资源业务含义。
进程监督 (foundation.harness.supervise-process)¶
superviseProcess / validateTimeoutPolicy¶
- 签名:
superviseProcess(options, deps = {})(async);validateTimeoutPolicy(policy)。 - 输入:受约束的 command、args、cwd、环境、超时策略与既有监督选项。0.11.0 可选
rawSink只接受{ root, stdoutFile, stderrFile, onClosed? }:根必须在打开时已是 fresh canonical 目录,两个文件名必须是不同的单段相对名。 - 可选每流上限:
outputByteLimits为{ stdout?, stderr? },至少声明一流,各值为 0 到Number.MAX_SAFE_INTEGER的整数。按原始字节独立计数,等于上限允许,首次超过上限进入既有进程组终止流程。 - 输出:一个既有的
watchdog-termination-envelope。rawSink.onClosed只接收冻结的 stdout/stderr{ sha256, bytes }摘要; 它不创建第二种公开 envelope 或 receipt。 - 副作用:启动一个受监督子进程。raw sink 在 spawn 前以 exclusive/no-follow、0600 打开两个文件,直到 child
close、两个 streamclose、全部排队写入、fsync和 handleclose都完成才结束;exit 后到达的字节仍计入摘要。 - 限额结果:仅配置上限时,
evidence增加outputByteLimits和outputLimitExceeded;超限采用output_limit_exceeded终止原因。保存的截断流摘要只覆盖已保存字节。流、进程或写入终态未知时仍优先失败关闭。未配置上限保留旧行为。 - 身份边界:调用方必须在整个调用期间独占 raw sink 的命名空间。文件句柄保护不会证明调用期间 pathname 或根目录身份始终不变; 前后检查只用于尽早失败。
- 失败语义:选项形状错误抛
TypeError;机制失败抛SFC2004,沿既有supervise-process-failed错误域失败关闭。rawStreamSink仍是明确拒绝的名称;兼容别名、绝对路径、多段文件名、相同 stdout/stderr 名称与非 fresh 根均被拒绝。 - 接线边界:不要因为单一消费者想在写正式证据前脱敏,就新增
rawStreamSink、transform sink、通用 sanitizer、第二个进程 runner 或新的公开 stdout 字段/回调。现有rawSink适合调用方接受在 fresh canonical 临时根中以 0600 保存原始 stdout/stderr 文件的场景;Foundation 不承诺 zero-plaintext-on-filesystem,也不拥有领域脱敏、跨流秘密发现或事后遮盖。 - 若消费者有硬性零明文落盘要求,应由消费者基于明确威胁模型拥有该方案并暂停相关路径。至少出现第二个独立消费者和清晰共同合同前, 不重开 Foundation 的公共能力。
since/stability:监督入口自0.5.0/stable;受约束 raw sink 自0.11.0,仅提供机制,不承诺宿主资格、认证、领域 判断或发布状态。- 源文件:
packages/skill-family-harness-node/src/supervise-process.mjs。正反例测试:packages/skill-family-harness-node/test/supervise-process-validation.test.mjs、packages/skill-family-harness-node/test/supervise-process-evidence.test.mjs。 - 调用方仍拥有的业务语义:可执行程序选择、超时策略值、输出解释、认证、重试和发布决定。
请求管线 (foundation.harness.request-processing)¶
parseRequest / processRequest¶
- 签名:
parseRequest(raw)processRequest(raw, { now = () => new Date() } = {})(async)- 输入:原始请求负载(应符合 kernel 协议结构)。
- 输出:规范化
operation-request与终态operation-result(终态集合固定为REJECTED/FAILED/SUCCESS)。 - 纯函数:
parseRequest是;processRequest为纯函数管线(无外部副作用,默认now可注入以保证确定性测试)。 - 副作用:无文件/Git/网络。
- 稳定错误码与
details.kind:解析失败进入REJECTED/FAILED终态并带SFC2002/SFC2003/SFC2004;机制失败+ EXECUTION_FAILEDkind。 - 前置条件与信任锚:请求符合 kernel 协议结构;业务语义由消费者拥有。
since/stability:0.2.0/stable。- 源文件:
packages/skill-family-harness-node/src/request.mjs。 - 正例/负例测试:
packages/skill-family-harness-node/test/request.test.mjs。 - 调用方仍拥有的业务语义:操作的具体业务语义(状态机/重试转
loop-agent)。
报告 (foundation.harness.report)¶
validateReportModel / renderReportMarkdown / computeResultDigest / computeModelDigest / digestReport / buildBinding / verifyBinding / checkReport / collectStyleWarnings¶
- 签名(节选):
validateReportModel(reportModel, { resultDocument } = {})renderReportMarkdown(model)computeResultDigest(resultDocument)/computeModelDigest(reportModel)/digestReport(reportMarkdown)buildBinding(reportModel, resultDocument, reportMarkdown)verifyBinding(binding, { reportModel, resultDocument, reportMarkdown } = {})checkReport({ reportMarkdown, reportModel, resultDocument, binding } = {})collectStyleWarnings(reportMarkdown)- 输入:
report-model、渲染选项(locale/audience/style);SUPPORTED_REPORT_LOCALES = [zh-CN, en-US]。 - 输出:Markdown 文本、绑定对象、分级检查发现;人类报告由机器结果派生,禁止自由撰写。
- 纯函数:是(无时钟、无环境、无网络、无模型调用)。
- 副作用:无文件/Git/网络。
- 稳定错误码与
details.kind:SFC3001(REPORT_DIGEST_MISMATCH,绑定摘要不符或报告非模型规范渲染)、SFC3002(REPORT_ELEMENT_MISSING,强制元素缺失)、SFC3003(REPORT_FACT_DRIFT,报告改写绑定结果事实或字节与确定性再渲染不一致)。风格告警由collectStyleWarnings产出,仅建议、不编码、不阻断。 - 前置条件与信任锚:
REPORT_RENDERER_NAME/VERSION取自各自 package(当前0.3.0);双输出成组写入并拒绝路径别名与输入覆盖。 since/stability:0.2.0/stable。- 源文件:
packages/skill-family-harness-node/src/report.mjs。 - 正例/负例测试:
packages/skill-family-harness-node/test/report.test.mjs。 - 调用方仍拥有的业务语义:报告业务结论的解读(编排由 Kit
report子动作负责)。
宿主适配机制 (foundation.harness.host-adapter)¶
normalizeAdapterSource / buildAdapterClosure / verifyAdapterBuildManifest / verifyPeerAdapterDirectories / materializeAdapterBuild / probeVersionVector¶
- 签名:
normalizeAdapterSource(input)buildAdapterClosure({ hostId, pathCategory, input } = {})verifyAdapterBuildManifest(manifestInput, { hostId, pathCategory } = {})verifyPeerAdapterDirectories({ request, peerRoots } = {})(async):从两个或更多真实 peer 根目录重算共同闭包、标准 manifest 和完整logicalMappings。materializeAdapterBuild({ targetRoot, build, writer = writeFileAtomic } = {})(async)probeVersionVector({ hostId, capabilities, executable, argv, allowSpawn = false, timeoutMs = 5000, runner = spawnSync } = {})(async)- 输入:adapter source、目标路径、probe 选项。
- 输出:构建闭包、校验后的清单、materialize 产物、版本向量。
- 纯函数:
normalizeAdapterSource/buildAdapterClosure/verifyAdapterBuildManifest是;materializeAdapterBuild/probeVersionVector含落盘或进程调用。 - 副作用:
materializeAdapterBuild在受收容目标创建 sibling staging 并单次 rename;probeVersionVector默认allowSpawn=false,不取 PATH、不自动执行宿主二进制。 - 稳定错误码与
details.kind:清单摘要不符+ MANIFEST_MISMATCH;目标已存在+ PORTABLE_PATH_COLLISION;非受信可执行文件+ UNTRUSTED_EXECUTABLE;构建/探测失败+ HOST_BUILD_FAILED/HOST_PROBE_FAILED;契约不符+ HOST_CONTRACT_INVALID;以上均包于SFC2004。 - 前置条件与信任锚:adapter source 为已声明文本闭包(
content类型固定string,仅 utf8;二进制投影 unsupported);受信可执行文件方可 materialize。 since/stability:0.2.0/stable。- 源文件:
packages/skill-family-harness-node/src/host.mjs。 - 正例/负例测试:
packages/skill-family-harness-node/test/host.test.mjs。 - 调用方仍拥有的业务语义:宿主具体业务语义与本地生命周期决策;Kit 只复用本节的绑定读取、严格不替换发布和原子写机制,不由 Harness 注册宿主别名或 driver。
verifyPeerAdapterDirectories 是只读入口。它逐级枚举和读取真实目录,拒绝符号链接、路径逃逸、非普通文件、缺失/多出或逐字节摘要不一致;mapping 必须唯一覆盖每个真实 SKILL.md。它按 peerId 归一化比较闭包,因此请求顺序不会影响结果。失败使用既有 SFC2003/SFC2004 与 details.kind,不返回部分成功,也不写入 peer 根目录。
持久状态底座 (foundation.harness.state-store)¶
openStateStore / appendEvent / readEvents / readSnapshot / writeSnapshot / verifyStateStore / rebuildSnapshot / inspectStateStoreLock / recoverStateStoreLock / closeStateStore / close¶
- 签名(节选):
openStateStore(root, { owner, payloadSchemas, clock } = {})(async)appendEvent(store, event)(async)readEvents(store, { afterSequence = 0 } = {})(async)readSnapshot(store, { reducer, initial = null } = {})(async)writeSnapshot(store, state, { hostSessionRef, reducer, initial = null } = {})(async)verifyStateStore(store, { reducer, initial = null } = {})(async)rebuildSnapshot(store, reducer, { initial = null } = {})(async)inspectStateStoreLock(root, { clock, recoveryObservation = false } = {})(async)recoverStateStoreLock(root, options = {})(async)- 两种互斥接管模式,只能取其一:旧模式
{ expectedOwner, expectedFencing, confirmOwnerTerminated: true, payloadSchemas };维护模式{ observation, confirmAllParticipantsStopped: true, confirmExclusiveMaintenance: true, payloadSchemas }。两种模式都必填payloadSchemas(与openStateStore相同的注册表,至少一个 eventType/版本对),newOwner与clock可选。
- 两种互斥接管模式,只能取其一:旧模式
closeStateStore(store)/close(store)(async)- 输入:事件负载、快照、锁令牌。
- 输出:事件、hash chain 校验结果、快照;
STATE_GENESIS_DIGEST作为链起点。 - 纯函数:否(读写事件日志与快照文件,写协作式单写者锁)。
- 副作用:在受收容路径读写事件日志与快照;写锁文件用于本地协作式单写者。
- 稳定错误码与
details.kind:hash chain 断裂+ CHAIN_BROKEN;锁 fencing 冲突+ STORE_LOCKED;锁损坏+ LOCK_CORRUPT;恢复拒绝+ LOCK_RECOVERY_REFUSED;非法事件+ UNSAFE_STATE_ENTRY/EVENT_SCHEMA_INVALID;重复序号+ DUPLICATE_SEQUENCE;幂等冲突+ IDEMPOTENCY_CONFLICT;快照不一致+ SNAPSHOT_MISMATCH;已关闭+ STORE_CLOSED;以上均包于SFC2004。 - 恢复接管模式(互斥,不得混用):旧模式
recoverStateStoreLock(root, { expectedOwner, expectedFencing, confirmOwnerTerminated: true, payloadSchemas })要求 owner 与 fencing 精确匹配当前观测值;维护模式recoverStateStoreLock(root, { observation, confirmAllParticipantsStopped: true, confirmExclusiveMaintenance: true, payloadSchemas, newOwner?, clock? })用完整观察覆盖 writer 缺失与部分写入的控制文件,不只核对 owner/fencing。显式写出但值为undefined的旧模式字段同样计入混用并被拒绝(legacy and maintenance recovery options cannot be mixed),构造维护模式 options 时必须整体省略旧模式字段。 - 完整观察获取:对同一 root 调用
inspectStateStoreLock(root, { recoveryObservation: true })返回state-store-recovery-observation对象(闭字段schemaVersion、kind、root、directories、controls;只读,不整理残留、不创建目录)。默认调用(不传该选项)返回的是诊断结果,不是有效观察,不能用于维护模式。维护模式的组织范围限于已验证的事件临时别名与writer.lock、writer-mutation.lock、writer-recovery.lock三种可处置控制残留;未知格式的控制记录或 fencing 计数器拒绝接管,未知文件不删除。 - 前置条件与信任锚:事件日志为唯一权威,snapshot 为派生缓存;fencing 不承诺抵御同权限恶意进程;
confirmOwnerTerminated信任锚由调用方提供。维护模式的两项确认同样是外部信任前提,不是布尔字段自动实现的锁:confirmAllParticipantsStopped声明旧写者、旧恢复者及其子进程均已停止,confirmExclusiveMaintenance声明排他维护区间仍成立;区间从取得观察之前开始,到本次调用取得新写者句柄或失败返回结束,期间禁止其他恢复、正常打开、状态存储写入与相关业务写入。PID、年龄或 owner/fencing 比较都不能替代该前提。 since/stability:0.2.0/stable。- 源文件:
packages/skill-family-harness-node/src/state-store.mjs。 - 正例/负例测试:
packages/skill-family-harness-node/test/state-store.test.mjs。 - 调用方仍拥有的业务语义:事件业务含义、reducer 转移、owner-terminated 信任锚(业务状态机/终态转
loop-agent)。
机制错误 (foundation.harness.errors)¶
HarnessError / mechanismError / HARNESS_ERROR_KINDS¶
- 签名:
class HarnessError extends ContractsError(构造(code, message, details),未登记码立即抛TypeError)mechanismError(kind, message, extraDetails)(返回SFC2004+ 稳定details.kind)HARNESS_ERROR_KINDS(冻结对象)- 输入:错误
kind、上下文。 - 输出:带稳定
kind的错误对象;非法kind抛TypeError。 - 纯函数:是。
- 副作用:无。
- 稳定错误码与
details.kind:本模块不发明新码——机制失败统一SFC2004(EXECUTION_FAILED),其注册含义为「机制运行时执行合规操作时失败;details 携带机制证据」;details.kind取下列冻结枚举之一。 - 前置条件与信任锚:
HARNESS_ERROR_KINDS冻结,新增 SFC 码属 Contracts 变更(不在本包写集)。 since/stability:0.2.0/stable。- 源文件:
packages/skill-family-harness-node/src/errors.mjs。 - 正例/负例测试:
packages/skill-family-harness-node/test/boundary.test.mjs、boundaries.test.mjs。 - 调用方仍拥有的业务语义:错误业务归因。
HARNESS_ERROR_KINDS 冻结枚举(v1):
| kind | 含义 |
|---|---|
invalid-path / absolute-path / windows-drive-path / windows-path / unc-path |
路径形态非法 |
path-traversal / symlink-escape / realpath-escape |
收容逃逸 |
invalid-root |
根目录非法 |
atomic-write-failed / read-failed |
文件读写失败 |
missing-resource |
资源缺失 |
workspace-create-failed / workspace-dispose-failed / workspace-disposed |
临时工作区异常 |
closure-conflict / unsupported-policy |
闭包/策略冲突 |
execution-failed / invalid-result |
执行/结果异常 |
store-closed / store-locked / lock-corrupt / lock-recovery-refused |
状态锁异常 |
unsafe-state-entry / event-schema-invalid / duplicate-sequence / idempotency-conflict / chain-broken / snapshot-mismatch |
状态事件异常 |
host-contract-invalid / host-build-failed / host-probe-failed / untrusted-executable / portable-path-collision / manifest-mismatch |
宿主适配异常 |
baseline-mismatch / content-guard-rejected |
基线物化失败关闭 |
read-chokepoint-rejected |
只读准入拒绝 |
surface-scan-violation / scan-policy-invalid |
表面扫描失败关闭 |
upper-bound-exceeded |
上限守卫越限 |
基线物化 (foundation.harness.baseline-materialization)¶
FND-ADR-009。把冻结基线物化为字节保真的临时副本:物化前校验源摘要、物化后同时校验副本摘要与源摘要(捕获物化中途的任一侧变化);副本内符号链接一律拒绝。
computeDirectoryDigest / materializeBaseline¶
- 签名:
computeDirectoryDigest(rootDir)(async,返回 64 位小写 sha256 十六进制摘要)materializeBaseline({ baselineDir, baselineDigest, prefix = "sf-baseline-" } = {})(async,返回物化根路径)- 输入:基线目录与冻结摘要。
- 输出:确定性目录摘要;物化后的临时目录根路径。
- 纯函数:否(读源树、在系统临时目录创建副本)。
- 副作用:只读源基线;写系统临时目录并在失败时清理。
- 稳定错误码与
details.kind:摘要不符(物化前或物化后)抛SFC2004+baseline-mismatch(details 含phase:pre-materialization/post-materialization);目录不可用抛invalid-root;建目录失败抛workspace-create-failed。 - 前置条件与信任锚:调用方持有冻结摘要;同一权限级进程可在物化窗口内改动源,机制以双端摘要捕获并失败关闭,不承诺抵御同权限恶意进程。
since/stability:0.3.0/stable。- 源文件:
packages/skill-family-harness-node/src/baseline.mjs。 - 正例/负例测试:
packages/skill-family-harness-node/test/baseline.test.mjs。 - 调用方仍拥有的业务语义:残留内容判定(
contentGuard谓词)与副本最终去处。
TemporaryWorkspace.fromBaseline({ baselineDir, baselineDigest, prefix, contentGuard }) 与 createTemporaryWorkspace({ baseline: { ... } }) 把物化接入工作区生命周期:contentGuard 缺省为允许(字节保真是机制契约,残留判定归消费者);守卫抛错包装为 content-guard-rejected 并 dispose 副本。
只读 chokepoint (foundation.harness.read-chokepoint)¶
FND-ADR-009。把受保护区域的读取集中到一个准入入口:允许根集合 + 可选身份谓词;越界、链接逃逸与非授权身份一律 read-chokepoint-rejected。
createReadChokepoint¶
- 签名:
createReadChokepoint({ allowRoots, allowIdentity } = {})→{ assertReadAllowed, read } - 输入:非空允许根集合;可选身份谓词
(identity) => boolean。 - 输出:准入后的
{ root, relPath, absolute }或受收容读取结果。 - 纯函数:否(
async,含只读文件系统访问)。 - 副作用:只读 realpath / 收容读取;不写。
- 稳定错误码与
details.kind:越界/逃逸/非授权抛SFC2004+read-chokepoint-rejected;资源缺失抛missing-resource;参数非法抛TypeError。 - 前置条件与信任锚:调用方声明允许根集合与身份规则;机制不解释任何私有身份或路径语义。
since/stability:0.3.0/stable。- 源文件:
packages/skill-family-harness-node/src/chokepoint.mjs。 - 正例/负例测试:
packages/skill-family-harness-node/test/chokepoint.test.mjs。 - 调用方仍拥有的业务语义:允许根集合、身份谓词、准入后读取语义。
字符串输入与 { root, relPath } 输入走同一 resolveContained 收容分类(含 macOS /var → /private/var 等符号链接前缀根的统一规范化)。
策略化表面扫描 (foundation.harness.surface-scan)¶
FND-ADR-009。按 surface-scan-policy 契约文档对声明表面做路径与内容模式扫描:首个命中即失败关闭;策略非法或模式不可编译同样失败关闭;缺失扫描文件不静默跳过。
scanSurface¶
- 签名:
scanSurface({ root, relPaths, policy, encoding = "utf8" } = {})(async) - 输入:扫描根、相对路径清单、策略契约文档。
- 输出:
{ scanned, bytes, policy }(冻结对象)。 - 纯函数:否(只读文件系统访问;进程内正则编译,无持久状态)。
- 副作用:只读;不写。
- 稳定错误码与
details.kind:命中抛SFC2004+surface-scan-violation(details 含kindOfHit:path/content);策略非法或模式不可编译抛scan-policy-invalid;缺失文件抛missing-resource;参数非法抛TypeError。 - 前置条件与信任锚:策略文档通过契约校验;
allowedUses只携带不解释,命中不被豁免(豁免由消费者层实现)。 since/stability:0.3.0/stable。- 源文件:
packages/skill-family-harness-node/src/surface-scan.mjs。 - 正例/负例测试:
packages/skill-family-harness-node/test/surface-scan.test.mjs。 - 调用方仍拥有的业务语义:策略内容、允许用途语义与命中后的处置。
注入式自测约定:扫描器无状态——注入模式并扫描后移除注入,再次扫描结果字节一致(自测见测试文件,不冒充独立复核)。
token 上界估算 (foundation.harness.token-estimation)¶
FND-ADR-009。确定性领域估算原语,两个互相独立的估算器:UTF-8 字节数上界(estimateTokenUpperBound)与按 CJK 码位/空白切分的词元数估算(estimateTokens,算法 cjk-char-whitespace-split)。两者均为无模型、无网络、无 tokenizer 依赖、无持久状态导入的纯函数;字节上界结果符合 token-estimate-result 契约(无时间戳,guarantees 为封闭枚举)。每条词元估算记录携带估算器 id 与版本(SFA-CONTEXT-028:消费方必须能回答结果出自哪个估算器),两个估算器的结果不得静默混用、不得互相替代。
estimateTokenUpperBound¶
- 签名:
estimateTokenUpperBound(text)(纯函数) - 输入:文本字符串。
- 输出:
token-estimate-result对象(upperBound === inputBytes)。 - 纯函数:是;零依赖。
- 副作用:无。
- 稳定错误码与
details.kind:非字符串输入抛TypeError(无 SFC 码)。 - 前置条件与信任锚:输入为 JavaScript 字符串;估算只承诺上界(字节数即上界),不承诺真实 token 计数。
since/stability:0.3.0/stable。- 源文件:
packages/skill-family-harness-node/src/token-estimate.mjs。 - 正例/负例测试:
packages/skill-family-harness-node/test/token-estimate.test.mjs。 - 调用方仍拥有的业务语义:估算结果的解释与消费侧换算(模型调用与真实 token 计数不在 Foundation)。
estimateTokens / isCjkCodePoint / 估算器常量¶
- 签名:
estimateTokens(text)(纯函数)isCjkCodePoint(codePoint)(纯函数)- 常量:
TOKEN_ESTIMATOR_ID(skill-family.token-estimator)、TOKEN_ESTIMATOR_VERSION(1.0.0)、TOKEN_ESTIMATION_ALGORITHM(cjk-char-whitespace-split)、CJK_CODE_POINT_RANGES(冻结码位区间表) - 输入:文本字符串;
isCjkCodePoint接收整数码位。 - 输出:冻结的词元估算记录(
kind: skill-family.token-estimate-record,schemaVersion: 1),携带estimator.id/estimator.version/algorithm、输入统计(codePoints/inputBytes)、切分统计(cjkCharacters/whitespaceSeparators/otherRuns)与tokens;unit为tokens,precision为deterministic-heuristic,scope为content-text-only。 - 算法(
cjk-char-whitespace-split,逐码位单遍扫描): - CJK 码位区间(冻结):U+3400–U+4DBF(扩展 A)、U+4E00–U+9FFF(统一表意文字)、U+F900–U+FAFF(兼容表意文字)、U+20000–U+3134F(扩展 B–G)。
- 每个 CJK 码位计 1 词元,并立即终结其前尚未闭合的 OTHER 段。
- 连续的非 CJK、非空白码位构成 OTHER 段,被空白或 CJK 码位分隔时每段计 1 词元。
- 空白(ECMAScript
\s类)只起分隔作用,不贡献词元。 - 恒等式:
tokens === cjkCharacters + otherRuns;中英混排、纯 CJK、纯 ASCII、空串(0 词元)全部适用。 - 纯函数:是;零依赖、零 import(模块纯度由测试复检)。
- 副作用:无。
- 稳定错误码与
details.kind:非字符串输入抛TypeError(无 SFC 码)。 - 前置条件与信任锚:估算是对目标 tokenizer 的确定性启发式近似,不承诺与任何具体模型 tokenizer 相等;比较阈值时同一批次必须使用同一估算器(记录内的
estimator与algorithm即裁决依据)。 since/stability:0.6.0/stable。- 源文件:
packages/skill-family-harness-node/src/token-estimate.mjs。 - 正例/负例测试:
packages/skill-family-harness-node/test/token-estimator.test.mjs(中英混排、纯 CJK、纯 ASCII、空串与空白串、扩展 B 码位、区间边界、记录封闭键集、恒等式、确定性、CLI 子进程行为)。 - 调用方仍拥有的业务语义:阈值策略与超限处置;把启发式词元数换算为目标模型的真实消耗。
CLI:skill-family-token-estimate¶
- 入口:harness 包 bin
skill-family-token-estimate(src/token-estimate-cli.mjs);与工程 Kit 的四命令互不混用。 - 用法:
skill-family-token-estimate (--text <s> | --file <p> | --stdin) [--estimator tokens|upper-bound|both];默认--estimator tokens。both输出{ tokens, upperBound }两个键,明示两个估算器并存而非混合。 - 输出:stdout 打印 JSON 估算记录(
tokens为估算记录,upper-bound为token-estimate-result),换行结尾。 - 副作用:只读取命令行参数、
--file指定文件或 stdin;只写 stdout。 - 稳定退出码:
0成功;2用法错误(输入源缺失或互斥、未知参数、--file目标不是普通文件等,stderr 给出原因);--help打印用法后退出 0。 - 前置条件与信任锚:
--file按调用方给定的路径原样读取,CLI 不做路径收容;需要收容时在库内用readFileContained。 since/stability:0.6.0/stable。- 源文件:
packages/skill-family-harness-node/src/token-estimate-cli.mjs。 - 正例/负例测试:
packages/skill-family-harness-node/test/token-estimator.test.mjs(子进程 CLI 用例:确定性、--file/--stdin/both、用法错误退出码 2、--help)。 - 调用方仍拥有的业务语义:输入文本的采集与裁剪策略、输出记录的归档位置。
通用上限守卫 (foundation.harness.upper-bound-guard)¶
FND-ADR-009。复用 state-store 事件账与 token-lock 显式占用实现通用上限守卫:越限事件失败关闭且不写入;上限值、单位类别与超限策略全部由消费者配置,模块不携带任何固定数额或定价词汇。
openUsageGuard / appendUsageEvent / readUsage / closeUsageGuard¶
- 签名:
openUsageGuard({ stateRoot, owner, payloadSchemas, reducer, initial = 0, upperBound, lockRoot, lockPath, clock } = {})(async)appendUsageEvent(guard, event, { beforeCommit } = {})(async)readUsage(guard)(async)closeUsageGuard(guard)(async)- 输入:事件负载、纯归约函数、非负上限、状态根与锁根/锁路径。
- 输出:追加结果、当前用量读数、守卫句柄。
- 纯函数:否(写事件账与锁文件)。
- 副作用:在受收容路径写事件账与锁文件;打开时显式占用锁、关闭时释放。
- 稳定错误码与
details.kind:越限抛SFC2004+upper-bound-exceeded(details 含upperBound/projected,事件不写入);锁被占用抛store-locked;事件账断链抛chain-broken;事件 schema 违规抛event-schema-invalid。 - 前置条件与信任锚:
lockRoot/lockPath由消费者指定在 state store 根之外;事件账是唯一权威;fencing 不承诺抵御同权限恶意进程。 since/stability:0.3.0/stable。- 源文件:
packages/skill-family-harness-node/src/budget-guard.mjs。 - 正例/负例测试:
packages/skill-family-harness-node/test/budget-guard.test.mjs。 - 调用方仍拥有的业务语义:事件含义、归约函数、上限数值与超限后的业务处置(定价与计费语义留在消费者)。
Quickstart Profile v2 candidate¶
规范入口 skill-family-harness-node/quickstart-profile 负责创建 observation Resource、Task 与终态 Result,并复验真实
文件字节、Resource id 全局唯一性、Task digest、operation 身份、逐字段 run/stage/attempt 以及 evidence 精确回指。
历史入口 skill-family-harness-node/candidate/quickstart-profile 在弃用窗口内解析同一模块;消费者应迁移一次。
verifyQuickstartExchange 把机制拒绝转换成结构化结果,抛出式入口继续使用已登记的 SFC2004 与稳定 details.kind。
invokeFoundationMechanism¶
invokeFoundationMechanism(request) 是固定机制桥接。调用方只能选择预先登记的 operation,不能传入模块名、导出名或任意函数。0.8.2 新增的 read-file-strict 直接调用上文的 readFileStrict:
{
"operation": "read-file-strict",
"params": {
"root": "/absolute/consumer-root",
"path": "authority/frozen.json",
"encoding": "utf8",
"expectedSha256": "<lowercase-sha256>"
}
}
params 是闭合对象。root 与 path 是必填非空字符串;encoding 只能是 utf8 或省略;expectedSha256 省略时不做预期摘要比对,提供时沿用核心严格读取合同。
桥接保留核心回执的 path、sha256、bytes 与 mode。UTF-8 内容仍是字符串;二进制内容投影成 Node 标准的 Buffer JSON 形态 { "type": "Buffer", "data": [...] },以便通过 JSON 传输后无损还原字节。
直接调用失败时沿用核心异常,包括 SFC2004 与 details.kind。候选 mechanisms-cli.mjs 继续使用一请求一响应 JSON:成功退出 0,拒绝或用法错误退出 2;CLI 错误 JSON 只承诺 name 与 message,不承诺跨语言保留 details。
该入口不选择 method,不解释 domainResult,也不拥有重试、调度或生命周期。消费者必须把 Contracts、Harness 与 Engineering Kit 精确锁定到同一版本;不能从 Foundation 工作树导入源码。0.3.0 的 v2 与 0.2.1 的 v1 不兼容。 迁移到规范入口和 Schema 身份后,后续仅晋升 stable 不再要求改合同身份;消费者仍需更新精确 pin 才能取得新发布的 stable 承诺,Bundle 是否重建由既有包字节与 provenance 绑定输入决定。
rename-directory-no-replace 的规范入口是
skill-family-harness-node/rename-directory-no-replace;历史 /candidate/rename-directory-no-replace 入口解析同一原生原语。
该原语仍不等同于稳定的高层 fixed-set-publication,消费者应根据所需合同选择,不得用别名混淆两个能力层次。
机制批量 (foundation.harness.mechanism-batch)¶
FND-DES-022。有界、同操作、顺序的跨进程批量传输:把一组相互独立的 canonical-json 请求合并为一次进程启动与传输,逐项结果与错误字节等价于同版本原单请求调用。已经位于同一 Node 进程内的调用不强制改批。本切片只实现该批量合同,不新增常驻服务、并发、缓存、重试、跨项引用、工作流、收据或注册表。
runMechanismCliBatch / mechanisms-cli.mjs --batch¶
- 签名:
runMechanismCliBatch({ input = stdin, output = stdout, error = stderr, invoke } = {})(async,返回整体退出码)- CLI 显式模式:
node <同版本官方 Bundle 内的 mechanisms-cli.mjs> --batch,从标准输入读取恰好一个 JSON 文档,写出一个批次响应后退出。带--batch且出现额外参数时在读取输入前拒绝;无--batch时仍运行旧runMechanismCli单请求入口,不对旧请求新增容量限制。 - 输入:恰好含
operation(固定canonical-json)与inputs(非空有序数组,每项恰好{ "document": <任意 JSON 值> })的一个 JSON 文档。不支持 NDJSON、会话协议、数组自动探测、每项自带操作或嵌套批次。顶层缺/多字段、项缺document、空数组与未知操作属于整批结构失败。 - 输出:
{ "results": [{ "inputIndex", "exitCode", "response" }] },长度与输入一致、序号从 0 连续递增;exitCode只取 0(成功)或 2(失败)。成功项response为原机制结果;失败项为原 CLI 的{ ok: false, error: { name, message, code?, details? } }错误对象。逐项还原规则固定为JSON.stringify(response) + "\n",退出码 0 对应原 stdout、2 对应原 stderr,另一通道为空;错误对象不重新排序或规范化。 - 纯函数:是(逐项经既有固定分派器
invokeFoundationMechanism执行,不引入第二套算法;测试可注入既有可信invoke,但输入 JSON 不得指定函数、模块、路径或覆盖分派器)。 - 副作用:无文件/网络/进程副作用,无残余状态;只写调用方提供的
output/error流(默认进程标准流)。 - 容量(固定政策,权威值由 Contracts
mechanism-batch-policy.json持有,本页与 Harness 从该权威派生,调用方不可调高):
| 限制 | 含边界的最大值 | 计量对象与检查时点 |
|---|---|---|
| 输入项数 | 256 | 解析后、逐项调用前 |
| 请求字节 | 16 MiB(16,777,216) | 原始 UTF-8 流含空白,拼接与解析前累计 |
| 响应字节 | 32 MiB(33,554,432) | 完整 JSON 响应与最后换行,发送前累计确认 |
- 失败语义:请求字节、输入项数或结构的预检拒绝在任何机制调用前发生,stdout 为空,
error流写一个批次错误对象并整体退出 2。输出容量只能在当前项已经返回后确认;超限时停止后续项,stdout 仍为空,error流写批次错误对象并退出 2。错误为TypeError投影,details.kind封闭为batch-structure-invalid、batch-item-limit、batch-input-limit、batch-output-limit,不新增 SFC 错误码。畸形 UTF-8、畸形 JSON 与输入流错误属传输失败,保留原异常投影,不伪装为机制业务失败、不伪造某个inputIndex。单项机制失败(含 unsafe integer 等留给原分派器按项判断的约束)经原 CLI 错误投影写入该项response并继续执行后续项。输出通道失败时可能已有部分字节送出;整体退出 2,消费者必须把截断 JSON、通道错误或进程无正常完成结果判为传输失败,不能从前缀认定批次成功。若连错误通道也写入失败,错误对象可能无法交付。 - 整体退出码三分支:所有机制项成功 → 0,stdout 为完整批次结果加一个换行、stderr 空;至少一个机制项失败 → 2,stdout 仍为完整批次结果、stderr 空;批次预检、输出容量或传输失败 → 2。预检与输出容量失败时 stdout 空、stderr 为一个批次错误对象与换行;输出通道失败时不承诺收回已经发送的字节。
- 前置条件与信任锚:Contracts、Harness 与 Engineering Kit 精确锁定同一版本;程序化函数与 CLI 都经调用方已安装并验证来源的官方 Bundle 消费(Bundle 由同版本三包生成,保留来源身份、摘要与完整性检查),不从 Foundation 工作树导入源码;调用方提供 input/output/error 流。已有 Schema 批量校验(
validate-many-by-schema-id)继续使用原入口,不嵌套、不重新包装。 since/stability:0.19.0/candidate。candidate不等于stable,本地候选测试通过也不改变成熟度;是否发布须查对应版本的发布后验证证据,不能从stability推断。- 源文件:Contracts 新 Schema
packages/skill-family-contracts/candidate/foundation-mechanisms/mechanism-batch-request.schema.json、mechanism-batch-result.schema.json与容量权威mechanism-batch-policy.json;Harnesspackages/skill-family-harness-node/candidate/mechanisms-cli.mjs;Kit 离线 Bundle 投影packages/skill-family-engineering-kit/candidate/profile-bundle.mjs。 - 正例/负例测试:
packages/skill-family-contracts/test/quickstart-profile.test.mjs、packages/skill-family-harness-node/test/quickstart-profile.test.mjs、packages/skill-family-engineering-kit/test/candidate-mechanisms-cli.test.mjs、packages/skill-family-engineering-kit/test/candidate-profile-bundle.test.mjs。 - 调用方仍拥有的业务语义:领域分组与容量切分、请求间依赖关系判断、精确 pin 与来源身份绑定、批次采用完成与领域回归判定。逐项迁移示例:把若干
{ "operation": "canonical-json", "params": { "document": ... } }单请求合并为{ "operation": "canonical-json", "inputs": [{ "document": ... }, ...] },再按results[i].inputIndex读回逐项response与exitCode;同一 Node 进程内的直接调用继续使用invokeFoundationMechanism,不被强制改成批量。
多路径文件集合应用与恢复 (foundation.harness.file-set-recovery)¶
applyFileSet / recoverFileSet / pruneFileSetRecovery¶
- 签名:
applyFileSet(request, { validate, beforeMutation, afterMutation })(async;validate必填,缺省不得自动通过)recoverFileSet(request)(async)pruneFileSetRecovery(request)(async)- 输入:Contracts 登记的
file-set-apply-request、file-set-recovery-request与file-set-prune-request。请求携带operationId、规范绝对真实root与已批准的rootBinding、固定recoveryRelPath(.foundation-file-apply)、allowAdjacentStaging、environment(filesystem为apfs或ext4,cooperativeWriters为 true)与validationTimeoutMs;apply 另有最多 1024 条有序操作(path/action/expected/next)。bytes只存在于 JS 调用参数,不进入机器 JSON;原字节与新字节合计上限 256 MiB。恢复必须另有maintenance观察(observation加两项确认);该观察由调用方在排他维护区间内对根内固定.foundation-file-apply/journal调用inspectStateStoreLock(journalRoot, { recoveryObservation: true })取得,observation.root必须等于该 journal 目录,默认诊断结果不是有效观察、不能用于故障接管;prune 请求只接受同一根绑定与environment,在无残留时直接取得正常 writer,只有需要故障接管时才要求显式提供同一maintenance。 - 输出:
file-set-result。outcome取committed、commit-unconfirmed、rejected、rolled-back、recovery-required、already-committed、already-rolled-back、pruned或already-pruned;paths按原请求顺序逐项给出apply、restore、current与errorKinds,分别表达历史意图、恢复动作与最近一次安全观察,不合成单一布尔值;materials给出材料相对路径、none|retained|partial|pruned、durable与adjacentStaging: none-observed|possible-unknown。 - 恢复材料布局:根内固定
.foundation-file-apply/下使用journal/(既有 state-store 事件账)与operations/<id>/{before,after}/<index>。材料默认保留,只有显式pruneFileSetRecovery清理精确的已终结操作,journal 保留;机制不按后缀删除归属不明的邻接暂存文件,只报告possible-unknown。 - 副作用:业务路径上的写入复用既有严格单文件原语(
publishFileOrReplace/replaceFileAtomic),恢复材料写在根内受收容路径。不发起网络、不启动子进程、不写 Git、不修改进程 umask。 - 失败语义:可捕获的机制失败返回
file-set-result,不只抛一个错误。外码沿用SFC2004,details携带闭枚举kind与phase(input/preflight/prepare/apply/validate/restore/finalize/prune),消息仅供人阅读、不能用于分支。整组前检失败、环境不支持与容量越限在任何业务写入前返回;领域验证返回 false、抛错、超时、非法结果或迟到完成触发自动恢复且不提交,验证状态与恢复状态分开报告;恢复遇冲突路径保留外部内容并继续其他安全项;全局独占或根身份问题停止整组;有效提交事件决定不回滚,目标复核或持久化未确认时报告commit-unconfirmed并保留材料。释放锁失败不改写已确认终态,只追加lock-release-failed。 - 保证边界:未为该路径写入持久
apply-intent事实前不触碰任何业务路径。不承诺瞬时多文件可见性,也不承诺抵御不合作或同权限恶意并发写者——写者交错只由调用方的合作式独占前提阻止。恢复要求调用方先停止旧参与者与旧恢复者、在外部建立排他维护区间并提交该区间的完整观察与确认;清理在无残留时直接取得正常 writer,只有需要故障接管时才要求同一维护前提。机制不自动偷锁、不竞争恢复、不猜测损坏材料。 since/stability:0.21.0/candidate。candidate不等于stable,本地候选测试通过也不改变成熟度;是否发布须查对应版本的发布后验证证据。消费者在评估期必须精确锁定三个 Foundation 包。- 源文件:
packages/skill-family-harness-node/src/file-set-recovery.mjs(根导出见src/index.mjs);Contracts 侧file-set-apply-request、file-set-recovery-request、file-set-prune-request、file-set-result、file-set-event-payload与state-store-recovery-observation。 - 正例/负例测试:
packages/skill-family-harness-node/test/file-set-recovery.test.mjs、packages/skill-family-harness-node/test/file-set-recovery-crash.test.mjs、packages/skill-family-contracts/test/file-set-contract.test.mjs。 - 调用方仍拥有的业务语义:业务计划与原/新字节的冻结、
validate的领域判断与异常详情、维护区间的建立与旧参与者停止确认、恢复材料的最终去处、精确 pin、采用资格与领域验收判定。
与机器事实层的互链¶
- 能力稳定 ID 见
docs/agents/capability-catalog.json(foundation.harness.*)。 - 机械校验:
scripts/docs/capability-catalog-check.mjs解析src/index.mjs,拒绝引用不存在的入口。
消费方契约测试替身(fake) (Foundation 0.14.0)¶
createAtomicWriteFake({ vector }) 是按能力具名导出的官方测试替身,入口为
skill-family-harness-node/contract-testing。它要求传入已由 Contracts 校验、身份与
精确版本匹配且尚未消费的 atomic-write 向量;调用签名保持
writeFileAtomic(root, relPath, data, options),但测试替身不访问真实文件系统。
fake.identity 固定暴露 capabilityId、vectorSetId 与 foundationVersion。
fake.observation() 返回冻结的调用参数摘要和 return、throw 或 indeterminate
结果。测试替身覆盖向量声明的成功、拒绝与不确定路径,不判定消费者领域保证;消费者须
另行运行至少一条受控真实公共调用路径。
Windows 原生支持与边界¶
Foundation 0.28.0 的 Windows 原生分支适用于 Node.js ≥22.22.2 且 <23、Windows 11 x64、本地 NTFS 路径与普通用户权限环境。该版本的 API 成熟度依据登记状态判断,新增世代 API 保持 candidate 状态;精确版本的远端发布可用性需通过正式发布凭据核实,不能替代真实宿主业务验证。
原生装载采用包内五平台 manifest、软件物料清单(SBOM)与收据构成的封闭预构建集合,消费者无需编译器,装载时不下载二进制文件,亦无 JavaScript 安全回退机制。POSIX 既有合同保持不变。
路径与文件系统语义¶
- 路径使用大写盘符与正斜杠表示,如
C:/work/project。 - 输入路径分隔符可归一化为正斜杠,目录名大小写按真实目录处理,不进行全路径转小写。
- 支持长路径、空格及中文文件名,内部使用 UTF-16 编码,但不公开内部扩展前缀。
- 拒绝以下路径形式:
- UNC 路径(如
\\server\share) - 设备路径(如
\\.\C:) - 盘符相对路径(如
C:work) - 指向 ADS(Alternate Data Streams)的路径
- 尾随点或空格的路径组件
- 保留设备名(如
CON,PRN,AUX等) - 包含 junction 或 reparse point 的路径组件
- 仅当
symlinkPolicy.mode=record时,可记录符号链接自身原始信息(UTF-16 target 与 reparseTag),不跟随目标路径。
原生身份与权限模型¶
createFilesystemRootBinding 保持 kind、digestAlgorithm、basis、digest 四字段,Windows 的 basis 为 canonical-finalpath-volume-fileid-type-security-v1,不新增版本字段。observeFilesystemTree 的 Windows 观察使用 schemaVersion=2。
Windows 权限观测是闭对象 {kind, attributes, securityDigest}:kind 固定为 windows-security-v1,attributes 为原生文件属性的无符号 32 位整数,securityDigest 为 64 位小写十六进制。摘要覆盖 owner、group、DACL 及相关控制标志,不读取需要特权的 SACL;它用于核对观测一致性,不穷尽有效访问权限。readFileBound 的 rootMode 也为 null,rootPermissionObservation 使用同一结构。
- 原生身份由
volumeSerial/fileId、安全描述符摘要与文件属性共同构成。 - 不可从 POSIX
mode伪造 Windows 权限,权限信息由 Windows 安全描述符直接提供。 readFileBound的mode与statMode字段返回null,权限信息通过permissionObservation字段记录。- 所有读取、遍历与严格发布操作均需通过原生句柄验证身份。
- 普通文件仅支持单链接;硬链接被拒绝。
- 严格发布时,
permissions.kind仅支持: windows-inherited:新文件继承父目录权限windows-preserve:保留原始目标文件的权限设置- 公共
mode在 Windows 平台被拒绝,私密机制使用当前用户 owner,DACL 仅允许当前用户与SYSTEM,首字节前已设好,普通消费者无法将windows-protected当作公共策略使用。 - 恢复操作会尝试还原原 owner、group、DACL、READONLY/HIDDEN/SYSTEM/ARCHIVE 四个属性,并在整组前进行实际测试以验证还原能力。
- 不会主动申请权限提升,恢复过程依赖当前用户权限。
readFileStrict 保留对根路径 "." 的便利支持,其行为在 Windows 上先进行词法规范化,不用 realpath(root) 洗白重解析路径;规范化后的绝对路径需经原生安全核验,确保根、祖先及最终文件均在许可范围内,盘符相对路径(如 C:foo)、UNC 路径及设备命名空间路径均被拒绝。该接口不放宽对 readFileBound 或 createFilesystemRootBinding 所要求的严格根绑定准入,既有错误分类继续传播:摘要错误、缺失、读取错误、被拒绝的链接及路径越界均按原分类传播,不回退至普通读取。 POSIX 原行为不变。
可执行入口与明确的 Node 解释器¶
explicitNode 分支要求 lookup.mode=absolute-path。脚本同样须为普通单链接文件;脚本与 Node 各自必须只匹配一个绑定根,两者可以位于不同根中。允许的脚本类型包括:
- 后缀为
.js、.mjs或.cjs的文件,可无 shebang; - 无扩展名的文件,但首行必须精确匹配以下任一声明:
#!/usr/bin/env node#!node#!node.exe
shebang 必须从同一原生句柄读取并验证的字节中判断,且仅接受完整声明,不带附加参数。无扩展名脚本不接受缺失 shebang;其他后缀的文件继续拒绝。不将未知脚本类型猜测为 Node 脚本。仅 .js、.mjs、.cjs 后缀的文件允许无 shebang,无扩展名脚本则必须有上述三种 shebang 之一。
脚本字节、摘要与权限的当次观测结果作为后续复核的基准。输出版本 v2 的 canonicalEntry.entryKind=interpreter-script,interpreter.request 为 Node 的规范路径,interpreter.canonicalEntry 为同次观测的 Node 身份,shebangArgs=[],launch.file 为 Node 路径,argvPrefix 仅包含脚本的规范路径。脚本与 Node 在返回前及启动前均需复核绑定关系与摘要一致性。
当未传入 explicitNode 时,仅观察 PE 原生入口。explicit-path-search 按调用者提供的 pathEntries 顺序执行:在 pathEntries 的每个根目录内,先匹配调用者提供的完整命令名,无扩展名时再尝试 command.exe,已有扩展名则不再追加。存在候选但非合格 PE 文件时明确拒绝,不跳转至环境 PATHEXT、当前目录或其他解释器。absolute-path 仅查询指定路径。上述通用查找入口拒绝 .cmd 和 .bat 文件。工程对已知 npm/pnpm shim,从已核实的对应安装包解析实际 npm-cli.js/pnpm.cjs 等 Node 入口,并构造上述 explicitNode 输入。用户可在 cmd/PowerShell 中运行 npm 生成的 CLI shim,内部不使用 shell:true 或拼接命令字符串。
固定世代发布与整批固定读取¶
Windows 明确不支持旧的 replaceFixedSetAtomic 双目录交换,不能以普通重命名替代。POSIX 的原交换合同保留。以下两个新增入口同时从包根与 skill-family-harness-node/fixed-set-publication 导出。
- 新增两个核心 API 用于固定世代管理:
publishFixedSetGeneration({storeRoot, sourceRoot, generation, expectedCurrent})resolveFixedSetGeneration({storeRoot})
发布世代(publishFixedSetGeneration)¶
sourceRoot必须是storeRoot内以generation命名的真实子目录。generation为安全单段名,不能为current。- 世代必须先完整生成,之后保持不可变。
expectedCurrent为前置条件,表示当前指针状态,首次调用为null。- 该操作要求单写者协作;
expectedCurrent是点时前置条件,不提供并发 CAS 保证。 - 指针内容包含:
schemaVersion=1kind=skill-family.fixed-set-generation-pointergenerationclosureDigest
解析世代(resolveFixedSetGeneration)¶
- 安全读取指针并验证整个世代闭包。
- 返回:
pointer:指针对象generationRoot:世代根目录的路径-
rootBinding:根绑定信息 -
调用者每个读取批次仅需调用一次
resolveFixedSetGeneration,并将同一generationRoot与rootBinding传给所有readFileBound调用。 - 不能对每个文件重新读取
current指针。 - 旧世代不会自动删除,静默期与清理由消费者自行决定。
- 发布结果返回字段:
status:发布状态commitState:提交状态verification:闭包验证结果durability:刷新请求及确认状态indeterminate表示提交结果尚未确定,不能按提交前失败盲目重试。
文件集合恢复与 Job Object 清理¶
文件集合恢复使用 v2 协议,请求中声明 environment.filesystem=ntfs;POSIX 系统仍沿用 v1 及 apfs/ext4 合同。恢复过程需排他维护,所有旧参与者须被终止。恢复材料默认保留,不自动清理。flush-requested 仅表示已请求刷新文件与目录内容,不提供断电事务保证。
文件集合的逻辑准入规则在整组前检时执行:路径必须是 UTF-8 文本,并符合 NFC 规范化,同一请求中若存在大小写或 Unicode 归一化别名,则整组请求被拒绝,且不产生任何业务写入。此限制仅作用于逻辑命名层面,不因 NTFS 实际支持大小写敏感而放宽。即使在真实 NTFS 目录中可共存 A 与 a,该同组 apply 仍按逻辑合同拒绝。此行为非 NTFS 本身冲突,而是为保障可移植性与命名一致性所设的前置校验。
安全访问、文件树遍历与固定集合扫描仍遵循真实 NTFS 目录的大小写规则,即实际路径匹配以文件系统语义为准,不依赖逻辑命名规则。
以下四个 async 接口仅用于 Windows/NTFS;其他平台在修改前拒绝。root 与原先批准的 rootBinding 必须对应同一根,身份变化时拒绝,不能重新捕获绑定来批准替代根。目录记录中的身份与 permissionObservation 来自同一创建或打开句柄。
inspectFileSetRecovery —— 恢复状态只读探查¶
inspectFileSetRecovery({ root, rootBinding, recoveryRelPath: ".foundation-file-apply", environment })
- async:
true - 合法环境:仅接受
{filesystem: "ntfs"}或{filesystem: "ntfs", cooperativeWriters: true},未知字段或其他值均拒绝。声明不能代替实际 NTFS 与运行时检查。 - 调用前提与副作用:只读,不要求合作写者确认、独占访问或预先取得维护观察,不创建或修改文件系统对象。
返回状态(result.status)
| 状态 | 语义说明 |
|---|---|
absent |
机制根目录实际缺失 |
admitted |
合格私密空根,或已验证完成且无参与者、未终结操作、未知或损坏材料的历史记录 |
refused |
本次只读核验拒绝,保留原失败原因 |
错误结构(result.error)
null:当状态为absent或admitted时- 否则:
{ code, message, details: { kind, phase, path? } } code:SFC2004details.kind: 既有 file-set 错误种类details.phase:input或preflightdetails.path: 仅限有效业务成员路径,绝不包含机制路径
语义约束
- 机制根缺失即
absent:若实际路径不存在,返回absent,不尝试重建 - 准入范围:合格空根可以尚无
journal/operations;未终结操作、参与者、未知或损坏材料均拒绝。 prune记录可能解释缺失:若存在已记录的prune操作,可解释材料缺失;但无证明即拒绝- 历史状态不等同当前业务字节:当前业务数据无需与旧终端状态一致;缺失/陈旧头/缓存为推导结果,非权威性损坏
- 末次复核要求:
- 返回前必须重新检查原始参与者状态、事件边界、所有已检查目录身份及完整成员集合
- 任何读取错误、变更检测、不确定性均拒绝返回,不自动重试
- 事件链未变也不能放过新增未知材料
- 非保证项:
- 不保证原子快照
- 不保证独占访问证明
- 不保证返回后稳定性
- 不保证未来变更授权
- 操作身份:不创建或消费
operationId。
prepareFileSetParents —— 准备文件集合父目录¶
prepareFileSetParents({ root, rootBinding, paths })
- async:
true - 输入
paths: - 仅限授权业务相对路径
- 自动推导所需父目录,去重,按浅层优先顺序处理
- 遵循原始文件集路径/容量契约
- 权限继承:
- 新建业务目录继承实际父目录权限
- 已存在 ACL 不变
- 安全性验证:
- 原始根及祖先的原生句柄身份已验证
- 拒绝重解析(reparse)或被替换的祖先路径
- 必要句柄保持持有
EEXIST行为:- 必须先安全复核为既存真实目录,才记入
existing;不纳入本次创建记录 - 返回结构:
text { status: "succeeded" | "failed" | "indeterminate", created: Array<{ path, volumeSerial, fileId, permissionObservation }>, existing: Array<{ path, volumeSerial, fileId, permissionObservation }>, unconfirmed: Array<string>, // 仅相对路径字符串,非伪造身份 error: null | { kind, message } // 原始 HARNESS_ERROR_KINDS } - 部分成功:
- 创建成功但刷新失败,仍保留创建状态
- 不保证目录链原子性
createPrivateMaterialDirectory —— 创建私有材料目录¶
createPrivateMaterialDirectory(root, relPath, { rootBinding })
- async:
true - 输入
relPath: - 仅允许一个直接子目录路径,禁止递归
- 私有安全策略:
- 所有者为当前用户
- DACL 为受保护的非继承型,仅允许当前用户与
SYSTEM - 创建时设置,不支持任意 ACL 或模式选项
- 已存在处理:
- 仅接受已存在的有效私有真实目录
- 绝不收紧已有宽泛 ACL
- 返回
existing而非强制抛出EEXIST - 返回结构:
- 与
prepareFileSetParents相同闭合结构 created/existing/unconfirmed三组互斥- 总数最多一个有效条目
removePreparedFileSetParents —— 移除已准备的父目录¶
removePreparedFileSetParents({ root, rootBinding, directories })
- async:
true - 输入
directories: - 仅接受来自同次
prepareFileSetParents返回的created条目 - 绝不接受
existing条目 - 操作效果:
- 按深度逆序删除
- 验证原始根、祖先和记录目录的同一身份
- 仅在持有保护的前提下删除空目录
- 无递归,无任意清理
- 返回结构:
text { status: "succeeded" | "failed" | "indeterminate", entries: Array<{ path, status: "removed" | "already-absent" | "retained" | "indeterminate", error: null | { kind, message } }>, error: null | { kind, message } } - 状态语义:
removed:已知删除,即使父目录刷新失败,仍保持删除状态already-absent:当前即不存在,非组恢复或权限覆盖替换retained:未安全删除,因权限、替换、外部内容或全局停止;不证明存在或未变indeterminate:删除状态未知,绝不作为普通retained报告- 全局不安全:
- 若全局根或祖先不再可信,立即停止不安全的后续删除
- 所有未尝试项均保留,并附带原因
目录操作结果聚合规则¶
| 优先级 | 状态 | 说明 |
|---|---|---|
| 1 | indeterminate |
任意一个条目为 indeterminate,整体结果为 indeterminate |
| 2 | failed |
没有不确定项,但有错误或未完成要求 |
| 3 | succeeded |
所有条目完成,无错误或未确认项 |
- 错误处理:
- 错误优先级:首个不确定原因 → 首个错误
- 成功时
error为null - 类型错误:
- 仅在任何变更前允许
TypeError - 变更后返回结构化已知/未知部分事实,不抛异常
applyFileSet 的可选回调¶
applyFileSet(request, { validate, beforeMutation, afterMutation })
- 可选参数:
beforeMutationafterMutation- 上下文:冻结对象
{ index, path, action } - 执行顺序:
- 串行
await执行 beforeMutation在最终原生根/父/目标重检前执行afterMutation仅在实际变更 + 后验证 + 事件应用成功后执行- 拒绝行为:
- 任一回调抛错或拒绝均发生在 commit 前,进入原自动恢复,并保留
apply-failed/apply的因果消息 - 调用边界:回调不在
recover/prune中调用,不重放,也不自动重试。 - 超时:
validate的超时期限不覆盖可信回调- 可信回调须自行负责结束
runProjection 整个调用仍要求调用方确认 cooperativeWriters: true 并提供合作式独占访问;真正的 apply、recover、prune 操作保留原确认要求。只读核验结果不授权后续修改。以上说明 Windows 分支的调用边界;API 成熟度与精确版本发布状态需分别核对。
superviseProcess 与 Job Object¶
superviseProcess 使用 schemaVersion=2。挂起创建后,先关联 kill-on-close Job Object,再恢复主线程。stdin/stdout/stderr 句柄被封闭继承,防止泄漏。环境变量 env={} 可用,按 Node/libuv Windows 规则补全系统运行必需变量;显式提供的环境变量(含空字符串)优先于默认值。不保证完全无环境,但提供最小运行时上下文。
超时、预算、输出上限与残余后代均通过 TerminateJobObject 清理。成功提交强杀请求后,forcedKill=true。windowsJob 字段包含五项布尔观测状态:
associatedBeforeResume:Job Object 是否在恢复前已关联terminationRequested:终止请求是否已发出activeProcessZeroObserved:是否观察到活动进程为零handleClosed:Job Object 句柄是否已关闭(仅指 Job Object 句柄,不涵盖进程或线程句柄)cleanupCompleted:清理完成状态
cleanupCompleted 的达成需满足以下全部条件:
- 活动进程数为零
- 双流收尾、私密原始流刷盘并关闭
- 所有句柄(含 Job、进程、线程)已关闭
- 整个过程受
killGraceSeconds限制,即从TerminateJobObject发出后开始计时,用于等待 Job 归零与输出收尾
Windows 结果不包含 processGroupId 字段;POSIX 分支保留原进程组标识逻辑。原始流从私密创建、写入、刷新到关闭,全程使用同一原生句柄,确保一致性。