skill-family-engineering-kit 0.8.3 → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +37 -0
- package/CHANGELOG.zh-CN.md +37 -0
- package/README.md +24 -9
- package/README.zh-CN.md +24 -9
- package/candidate/profile-bundle.mjs +104 -1
- package/docs/architecture/index.html +3 -3
- package/docs/integration/audit/index.html +2 -1
- package/docs/integration/audit/mutation-taxonomy/index.html +1 -1
- package/docs/integration/audit/version-compatibility/index.html +5 -3
- package/docs/public/status/index.html +3 -3
- package/docs/reference/api/contracts/index.html +105 -1
- package/docs/reference/api/engineering-kit/index.html +2 -0
- package/docs/reference/api/harness/index.html +140 -1
- package/docs/search/search_index.json +1 -1
- package/package.json +3 -3
- package/profile-spi/extension-spi.json +1 -1
- package/release-notes/0.8.4.yaml +19 -0
- package/release-notes/0.9.0.yaml +21 -0
|
@@ -715,6 +715,45 @@
|
|
|
715
715
|
</ul>
|
|
716
716
|
</nav>
|
|
717
717
|
|
|
718
|
+
</li>
|
|
719
|
+
|
|
720
|
+
<li class="md-nav__item">
|
|
721
|
+
<a href="#来源权威收据-foundationcontractssource-authority" class="md-nav__link">
|
|
722
|
+
<span class="md-ellipsis">
|
|
723
|
+
|
|
724
|
+
来源权威收据 (foundation.contracts.source-authority)
|
|
725
|
+
|
|
726
|
+
</span>
|
|
727
|
+
</a>
|
|
728
|
+
|
|
729
|
+
<nav class="md-nav" aria-label="来源权威收据 (foundation.contracts.source-authority)">
|
|
730
|
+
<ul class="md-nav__list">
|
|
731
|
+
|
|
732
|
+
<li class="md-nav__item">
|
|
733
|
+
<a href="#validateSourceAuthorityReceipt--parseSourceAuthorityReceipt" class="md-nav__link">
|
|
734
|
+
<span class="md-ellipsis">
|
|
735
|
+
|
|
736
|
+
validateSourceAuthorityReceipt / parseSourceAuthorityReceipt
|
|
737
|
+
|
|
738
|
+
</span>
|
|
739
|
+
</a>
|
|
740
|
+
|
|
741
|
+
</li>
|
|
742
|
+
|
|
743
|
+
</ul>
|
|
744
|
+
</nav>
|
|
745
|
+
|
|
746
|
+
</li>
|
|
747
|
+
|
|
748
|
+
<li class="md-nav__item">
|
|
749
|
+
<a href="#文件系统契约-foundationcontractsfilesystem" class="md-nav__link">
|
|
750
|
+
<span class="md-ellipsis">
|
|
751
|
+
|
|
752
|
+
文件系统契约 (foundation.contracts.filesystem)
|
|
753
|
+
|
|
754
|
+
</span>
|
|
755
|
+
</a>
|
|
756
|
+
|
|
718
757
|
</li>
|
|
719
758
|
|
|
720
759
|
<li class="md-nav__item">
|
|
@@ -1972,6 +2011,45 @@
|
|
|
1972
2011
|
</ul>
|
|
1973
2012
|
</nav>
|
|
1974
2013
|
|
|
2014
|
+
</li>
|
|
2015
|
+
|
|
2016
|
+
<li class="md-nav__item">
|
|
2017
|
+
<a href="#来源权威收据-foundationcontractssource-authority" class="md-nav__link">
|
|
2018
|
+
<span class="md-ellipsis">
|
|
2019
|
+
|
|
2020
|
+
来源权威收据 (foundation.contracts.source-authority)
|
|
2021
|
+
|
|
2022
|
+
</span>
|
|
2023
|
+
</a>
|
|
2024
|
+
|
|
2025
|
+
<nav class="md-nav" aria-label="来源权威收据 (foundation.contracts.source-authority)">
|
|
2026
|
+
<ul class="md-nav__list">
|
|
2027
|
+
|
|
2028
|
+
<li class="md-nav__item">
|
|
2029
|
+
<a href="#validateSourceAuthorityReceipt--parseSourceAuthorityReceipt" class="md-nav__link">
|
|
2030
|
+
<span class="md-ellipsis">
|
|
2031
|
+
|
|
2032
|
+
validateSourceAuthorityReceipt / parseSourceAuthorityReceipt
|
|
2033
|
+
|
|
2034
|
+
</span>
|
|
2035
|
+
</a>
|
|
2036
|
+
|
|
2037
|
+
</li>
|
|
2038
|
+
|
|
2039
|
+
</ul>
|
|
2040
|
+
</nav>
|
|
2041
|
+
|
|
2042
|
+
</li>
|
|
2043
|
+
|
|
2044
|
+
<li class="md-nav__item">
|
|
2045
|
+
<a href="#文件系统契约-foundationcontractsfilesystem" class="md-nav__link">
|
|
2046
|
+
<span class="md-ellipsis">
|
|
2047
|
+
|
|
2048
|
+
文件系统契约 (foundation.contracts.filesystem)
|
|
2049
|
+
|
|
2050
|
+
</span>
|
|
2051
|
+
</a>
|
|
2052
|
+
|
|
1975
2053
|
</li>
|
|
1976
2054
|
|
|
1977
2055
|
<li class="md-nav__item">
|
|
@@ -2197,6 +2275,8 @@
|
|
|
2197
2275
|
<p>能力分组(与 <code>docs/agents/capability-catalog.json</code> 对应):</p>
|
|
2198
2276
|
<ul>
|
|
2199
2277
|
<li><a href="#对象校验-foundationcontractsobject-validation">对象校验</a> → <code>validateDocument</code> / <code>compileSchema</code> / <code>detectDialect</code></li>
|
|
2278
|
+
<li><a href="#来源权威收据-foundationcontractssource-authority">来源权威收据</a> → <code>validateSourceAuthorityReceipt</code> / <code>parseSourceAuthorityReceipt</code></li>
|
|
2279
|
+
<li><a href="#文件系统契约-foundationcontractsfilesystem">文件系统契约</a> → 根绑定与固定集合 manifest/receipt Schema</li>
|
|
2200
2280
|
<li><a href="#登记与协议-foundationcontractsregistry-protocol">登记与协议</a> → <code>loadRegistry</code> / <code>findSchemaByObject</code> / <code>findProtocol</code> / <code>registerSchema</code> / <code>registerProtocol</code></li>
|
|
2201
2281
|
<li><a href="#内核协议-foundationcontractskernel-protocol">内核协议</a> → <code>loadKernelProtocol</code> / <code>findOperation</code> / <code>checkOperation</code></li>
|
|
2202
2282
|
<li><a href="#强制检查-foundationcontractsmandatory-checks">强制检查</a> → <code>runChecks</code> / <code>collectUnresolvedRefs</code></li>
|
|
@@ -2204,7 +2284,7 @@
|
|
|
2204
2284
|
<li><a href="#错误码-foundationcontractserror-codes">错误码</a> → <code>ContractsError</code> / <code>isRegisteredErrorCode</code> / <code>stableError</code></li>
|
|
2205
2285
|
<li><a href="#审计表面-foundationcontractsaudit-surface">审计表面</a> → <code>canonicalJson</code> / <code>digestDocument</code> / <code>digestAuditSurface</code></li>
|
|
2206
2286
|
</ul>
|
|
2207
|
-
<p>包级常量(冻结,仅作事实投影,不另立权威):<code>CONTRACT_OBJECTS</code>(
|
|
2287
|
+
<p>包级常量(冻结,仅作事实投影,不另立权威):<code>CONTRACT_OBJECTS</code>(35 类顶层对象,闭集)、<code>CONTRACT_BOUNDARY</code>、<code>CONTRACTS_VERSION = "1.9.0"</code>、<code>SUPPORTED_DIALECTS</code>、<code>VALIDATION_POLICIES</code>、<code>CHECK_TYPES</code>(9 类机械检查)、<code>MANDATORY_RULES</code>、<code>RULE_BUDGET</code>、<code>ERROR_CODES</code>。</p>
|
|
2208
2288
|
<hr />
|
|
2209
2289
|
<h2 id="对象校验-foundationcontractsobject-validation">对象校验 (foundation.contracts.object-validation)<a class="headerlink" href="#对象校验-foundationcontractsobject-validation" title="Permanent link">¶</a></h2>
|
|
2210
2290
|
<h3 id="validateDocument">validateDocument<a class="headerlink" href="#validateDocument" title="Permanent link">¶</a></h3>
|
|
@@ -2251,6 +2331,29 @@
|
|
|
2251
2331
|
<li>调用方仍拥有的业务语义:方言选择策略(何时用 tolerant)。</li>
|
|
2252
2332
|
</ul>
|
|
2253
2333
|
<hr />
|
|
2334
|
+
<h2 id="来源权威收据-foundationcontractssource-authority">来源权威收据 (foundation.contracts.source-authority)<a class="headerlink" href="#来源权威收据-foundationcontractssource-authority" title="Permanent link">¶</a></h2>
|
|
2335
|
+
<h3 id="validateSourceAuthorityReceipt--parseSourceAuthorityReceipt">validateSourceAuthorityReceipt / parseSourceAuthorityReceipt<a class="headerlink" href="#validateSourceAuthorityReceipt--parseSourceAuthorityReceipt" title="Permanent link">¶</a></h3>
|
|
2336
|
+
<ul>
|
|
2337
|
+
<li>签名:<code>validateSourceAuthorityReceipt(receipt)</code>;<code>parseSourceAuthorityReceipt(receipt, actualSubjects)</code>。</li>
|
|
2338
|
+
<li>输入:闭合的外置 receipt,以及调用方实际观测的 subjects。每个 subject 只含 <code>packageName</code>、<code>version</code>、<code>filename</code> 与 <code>sha256</code>。</li>
|
|
2339
|
+
<li>输出:两者均返回既有 <code>{ valid, errorCode, errors, data }</code> 结果形态。解析成功时,<code>data</code> 只含 <code>sourceRepository</code> 与 <code>sourceBaseCommit</code>。</li>
|
|
2340
|
+
<li>纯函数:是。输入会复制后校验,调用方对象不被修改。</li>
|
|
2341
|
+
<li>副作用:无文件、进程、Git、网络或发布状态副作用。</li>
|
|
2342
|
+
<li>稳定错误码:结构、排序、重复包名、实际 subjects 形状或逐字段核对失败均返回 <code>SFC1001</code>。</li>
|
|
2343
|
+
<li>前置条件与信任锚:receipt subjects 至少一项,按 <code>packageName</code> 唯一、升序排列;<code>sourceBaseCommit</code> 是 40 位小写十六进制,SHA-256 是 64 位小写十六进制。调用方负责取得 receipt 与实际 subjects。</li>
|
|
2344
|
+
<li><code>since</code> / <code>stability</code>:<code>0.8.4</code> / <code>stable</code>。</li>
|
|
2345
|
+
<li>源文件:<code>packages/skill-family-contracts/src/source-authority.mjs</code>、<code>src/schemas/source-authority-receipt.schema.json</code>。</li>
|
|
2346
|
+
<li>正例/负例测试:<code>packages/skill-family-contracts/test/source-authority.test.mjs</code>、<code>source-authority-public-consumer.test.mjs</code>。</li>
|
|
2347
|
+
<li>调用方仍拥有的业务语义:receipt 的签发、存储和传输;实际包发现;校验后是否采用该来源。Contracts 不执行目标,也不解释私有发布计划。</li>
|
|
2348
|
+
</ul>
|
|
2349
|
+
<hr />
|
|
2350
|
+
<h2 id="文件系统契约-foundationcontractsfilesystem">文件系统契约 (foundation.contracts.filesystem)<a class="headerlink" href="#文件系统契约-foundationcontractsfilesystem" title="Permanent link">¶</a></h2>
|
|
2351
|
+
<p>0.9.0 新增三个稳定顶层 Schema:<code>filesystem-root-binding</code>、<code>fixed-set-publication-manifest</code> 与 <code>fixed-set-publication-receipt</code>。它们只描述结构与回执,不提供删除、替换或通用恢复状态机。</p>
|
|
2352
|
+
<ul>
|
|
2353
|
+
<li>根绑定 Schema:<code>https://contracts.skill-family.example/v1/filesystem-root-binding.json</code>。值固定为 <code>kind</code>、<code>digestAlgorithm</code>、<code>basis</code>、<code>digest</code> 四个字段;绑定值可序列化且不包含公开目录句柄。</li>
|
|
2354
|
+
<li>固定集合 manifest/receipt Schema:<code>https://contracts.skill-family.example/v1/fixed-set-publication-manifest.json</code> 与 <code>https://contracts.skill-family.example/v1/fixed-set-publication-receipt.json</code>。发布回执的终态只允许 <code>succeeded</code>、<code>refused</code>、<code>failed</code>、<code>indeterminate</code>。</li>
|
|
2355
|
+
<li>这三个 Schema 的真实登记与 fixture 由 <code>packages/skill-family-contracts/src/registry.json</code>、<code>src/schemas/</code> 和 <code>test/</code> 共同核验;批量校验 Schema 保持 candidate,不进入稳定 Registry。</li>
|
|
2356
|
+
</ul>
|
|
2254
2357
|
<h2 id="登记与协议-foundationcontractsregistry-protocol">登记与协议 (foundation.contracts.registry-protocol)<a class="headerlink" href="#登记与协议-foundationcontractsregistry-protocol" title="Permanent link">¶</a></h2>
|
|
2255
2358
|
<h3 id="loadRegistry--listSchemas--listProtocols--findSchemaRegistration--findSchemaByObject--findProtocol">loadRegistry / listSchemas / listProtocols / findSchemaRegistration / findSchemaByObject / findProtocol<a class="headerlink" href="#loadRegistry--listSchemas--listProtocols--findSchemaRegistration--findSchemaByObject--findProtocol" title="Permanent link">¶</a></h3>
|
|
2256
2359
|
<ul>
|
|
@@ -2492,6 +2595,7 @@
|
|
|
2492
2595
|
<hr />
|
|
2493
2596
|
<h2 id="Quickstart-Profile-v2-candidate">Quickstart Profile v2 candidate<a class="headerlink" href="#Quickstart-Profile-v2-candidate" title="Permanent link">¶</a></h2>
|
|
2494
2597
|
<p><code>skill-family-contracts/candidate/quickstart-profile</code> 导出 v2 协议、按真实 <code>$id</code> 索引的 Resource/Task/Result Schema 集合,以及 <code>validateQuickstartProfileDocument</code>。唯一操作名是业务中立的 <code>execute-method</code>;Foundation 不登记 method 词表,也不解释 parameters、evidence 或 domainResult 的领域含义。</p>
|
|
2598
|
+
<p>0.9.0 另提供两个 candidate batch Schema:<code>schema-validation-batch-request.json</code> 与 <code>schema-validation-batch-result.json</code>。它们只供现有 Quickstart Bundle 的 <code>validate-many-by-schema-id</code> 机制使用;未知 <code>schemaId</code> 或任一结构畸形都使整批请求失败,不改变稳定 Registry。</p>
|
|
2495
2599
|
<p>该入口从 <code>0.2.1</code> 起公开,但稳定性仍为 <code>candidate</code>。0.3.0 已用 v2 替换 v1,两者不兼容:新接入需精确锁定 <code>0.3.0</code>,仍需 v1 的接入继续精确锁定 <code>0.2.1</code>。candidate Schema 不进入稳定 <code>src/registry.json</code>。</p>
|
|
2496
2600
|
<hr />
|
|
2497
2601
|
<h2 id="与机器事实层的互链">与机器事实层的互链<a class="headerlink" href="#与机器事实层的互链" title="Permanent link">¶</a></h2>
|
|
@@ -2375,6 +2375,8 @@
|
|
|
2375
2375
|
<h1 id="skill-family-engineering-kit-公共-API-参考">skill-family-engineering-kit 公共 API 参考<a class="headerlink" href="#skill-family-engineering-kit-公共-API-参考" title="Permanent link">¶</a></h1>
|
|
2376
2376
|
<p>本页从真实导出(<code>src/index.mjs</code> 与各源模块、CLI 入口)核对,不手写无法证明新鲜度的全集。每个公共入口按 hand-off §4.3 说明:签名、输入与输出、是否纯函数、文件/进程/Git/网络副作用、稳定错误码与 <code>details.kind</code>、前置条件与信任锚、<code>since</code> 与 <code>stability</code>、源文件与正例/负例测试、调用方仍拥有的业务语义。</p>
|
|
2377
2377
|
<p>Kit 消费 Contracts 与 Harness,只拥有四个顶层命令与它们的只读/受控写边界。包级常量:<code>TOP_LEVEL_COMMANDS</code>(冻结 4 个:<code>scaffold</code> / <code>adopt-plan</code> / <code>projection</code> / <code>check</code>)、<code>FORBIDDEN_SIDE_EFFECTS</code>、<code>COMMAND_SIDE_EFFECTS</code>、<code>KIT_EXIT_CODES</code>(<code>ok=0</code> / <code>findings=1</code> / <code>rejected=2</code>)。Kit 永不执行 Git 写、发布、删除用户内容或触网。</p>
|
|
2378
|
+
<p>外置 source authority 不增加 Kit API。调用方先用 Contracts <code>parseSourceAuthorityReceipt(receipt, actualSubjects)</code> 核对收据,再把成功结果中的 <code>sourceRepository</code> 与 <code>sourceBaseCommit</code> 传给既有 Quickstart builder。Kit 不读取私有发布 plan,不发现实际包,也不签发 receipt。</p>
|
|
2379
|
+
<p>provider Profile descriptor 从 Foundation 0.8.4 与 Contracts 1.8.0 升级到 Foundation 0.9.0 时,须把自身的 <code>base.contractsVersion</code> 字段机械更新为 <code>1.9.0</code>。Kit 仍只有四个顶层命令;Quickstart Bundle 继续是 candidate 精确版本,并在同一 mechanisms CLI 中提供有序 <code>validate-many-by-schema-id</code>。</p>
|
|
2378
2380
|
<p>能力分组(与 <code>docs/agents/capability-catalog.json</code> 对应):</p>
|
|
2379
2381
|
<ul>
|
|
2380
2382
|
<li><a href="#scaffold-foundationkitscaffold">scaffold</a> → <code>scaffoldTarget</code></li>
|
|
@@ -776,6 +776,62 @@
|
|
|
776
776
|
</ul>
|
|
777
777
|
</nav>
|
|
778
778
|
|
|
779
|
+
</li>
|
|
780
|
+
|
|
781
|
+
<li class="md-nav__item">
|
|
782
|
+
<a href="#身份绑定读取-foundationharnessbound-read" class="md-nav__link">
|
|
783
|
+
<span class="md-ellipsis">
|
|
784
|
+
|
|
785
|
+
身份绑定读取 (foundation.harness.bound-read)
|
|
786
|
+
|
|
787
|
+
</span>
|
|
788
|
+
</a>
|
|
789
|
+
|
|
790
|
+
<nav class="md-nav" aria-label="身份绑定读取 (foundation.harness.bound-read)">
|
|
791
|
+
<ul class="md-nav__list">
|
|
792
|
+
|
|
793
|
+
<li class="md-nav__item">
|
|
794
|
+
<a href="#createFilesystemRootBinding--readFileBound" class="md-nav__link">
|
|
795
|
+
<span class="md-ellipsis">
|
|
796
|
+
|
|
797
|
+
createFilesystemRootBinding / readFileBound
|
|
798
|
+
|
|
799
|
+
</span>
|
|
800
|
+
</a>
|
|
801
|
+
|
|
802
|
+
</li>
|
|
803
|
+
|
|
804
|
+
</ul>
|
|
805
|
+
</nav>
|
|
806
|
+
|
|
807
|
+
</li>
|
|
808
|
+
|
|
809
|
+
<li class="md-nav__item">
|
|
810
|
+
<a href="#固定集合发布-foundationharnessfixed-set-publication" class="md-nav__link">
|
|
811
|
+
<span class="md-ellipsis">
|
|
812
|
+
|
|
813
|
+
固定集合发布 (foundation.harness.fixed-set-publication)
|
|
814
|
+
|
|
815
|
+
</span>
|
|
816
|
+
</a>
|
|
817
|
+
|
|
818
|
+
<nav class="md-nav" aria-label="固定集合发布 (foundation.harness.fixed-set-publication)">
|
|
819
|
+
<ul class="md-nav__list">
|
|
820
|
+
|
|
821
|
+
<li class="md-nav__item">
|
|
822
|
+
<a href="#createFixedSetPublicationManifest--publishFixedSet" class="md-nav__link">
|
|
823
|
+
<span class="md-ellipsis">
|
|
824
|
+
|
|
825
|
+
createFixedSetPublicationManifest / publishFixedSet
|
|
826
|
+
|
|
827
|
+
</span>
|
|
828
|
+
</a>
|
|
829
|
+
|
|
830
|
+
</li>
|
|
831
|
+
|
|
832
|
+
</ul>
|
|
833
|
+
</nav>
|
|
834
|
+
|
|
779
835
|
</li>
|
|
780
836
|
|
|
781
837
|
<li class="md-nav__item">
|
|
@@ -2264,6 +2320,62 @@
|
|
|
2264
2320
|
</ul>
|
|
2265
2321
|
</nav>
|
|
2266
2322
|
|
|
2323
|
+
</li>
|
|
2324
|
+
|
|
2325
|
+
<li class="md-nav__item">
|
|
2326
|
+
<a href="#身份绑定读取-foundationharnessbound-read" class="md-nav__link">
|
|
2327
|
+
<span class="md-ellipsis">
|
|
2328
|
+
|
|
2329
|
+
身份绑定读取 (foundation.harness.bound-read)
|
|
2330
|
+
|
|
2331
|
+
</span>
|
|
2332
|
+
</a>
|
|
2333
|
+
|
|
2334
|
+
<nav class="md-nav" aria-label="身份绑定读取 (foundation.harness.bound-read)">
|
|
2335
|
+
<ul class="md-nav__list">
|
|
2336
|
+
|
|
2337
|
+
<li class="md-nav__item">
|
|
2338
|
+
<a href="#createFilesystemRootBinding--readFileBound" class="md-nav__link">
|
|
2339
|
+
<span class="md-ellipsis">
|
|
2340
|
+
|
|
2341
|
+
createFilesystemRootBinding / readFileBound
|
|
2342
|
+
|
|
2343
|
+
</span>
|
|
2344
|
+
</a>
|
|
2345
|
+
|
|
2346
|
+
</li>
|
|
2347
|
+
|
|
2348
|
+
</ul>
|
|
2349
|
+
</nav>
|
|
2350
|
+
|
|
2351
|
+
</li>
|
|
2352
|
+
|
|
2353
|
+
<li class="md-nav__item">
|
|
2354
|
+
<a href="#固定集合发布-foundationharnessfixed-set-publication" class="md-nav__link">
|
|
2355
|
+
<span class="md-ellipsis">
|
|
2356
|
+
|
|
2357
|
+
固定集合发布 (foundation.harness.fixed-set-publication)
|
|
2358
|
+
|
|
2359
|
+
</span>
|
|
2360
|
+
</a>
|
|
2361
|
+
|
|
2362
|
+
<nav class="md-nav" aria-label="固定集合发布 (foundation.harness.fixed-set-publication)">
|
|
2363
|
+
<ul class="md-nav__list">
|
|
2364
|
+
|
|
2365
|
+
<li class="md-nav__item">
|
|
2366
|
+
<a href="#createFixedSetPublicationManifest--publishFixedSet" class="md-nav__link">
|
|
2367
|
+
<span class="md-ellipsis">
|
|
2368
|
+
|
|
2369
|
+
createFixedSetPublicationManifest / publishFixedSet
|
|
2370
|
+
|
|
2371
|
+
</span>
|
|
2372
|
+
</a>
|
|
2373
|
+
|
|
2374
|
+
</li>
|
|
2375
|
+
|
|
2376
|
+
</ul>
|
|
2377
|
+
</nav>
|
|
2378
|
+
|
|
2267
2379
|
</li>
|
|
2268
2380
|
|
|
2269
2381
|
<li class="md-nav__item">
|
|
@@ -2716,6 +2828,8 @@
|
|
|
2716
2828
|
<li><a href="#契约校验-foundationharnesscontract-validation">契约校验</a> → <code>validateContractDocument</code> / <code>getValidator</code></li>
|
|
2717
2829
|
<li><a href="#路径收容-foundationharnesspath-containment">路径收容</a> → <code>classifyPathInput</code> / <code>resolveContained</code> / <code>readFileContained</code></li>
|
|
2718
2830
|
<li><a href="#严格读取-foundationharnessstrict-read">严格读取</a> → <code>readFileStrict</code></li>
|
|
2831
|
+
<li><a href="#身份绑定读取-foundationharnessbound-read">身份绑定读取</a> → <code>createFilesystemRootBinding</code> / <code>readFileBound</code></li>
|
|
2832
|
+
<li><a href="#固定集合发布-foundationharnessfixed-set-publication">固定集合发布</a> → <code>createFixedSetPublicationManifest</code> / <code>publishFixedSet</code></li>
|
|
2719
2833
|
<li><a href="#原子写-foundationharnessatomic-write">原子写</a> → <code>writeFileAtomic</code></li>
|
|
2720
2834
|
<li><a href="#临时工作区-foundationharnesstemporary-workspace">临时工作区</a> → <code>TemporaryWorkspace</code> / <code>withTemporaryWorkspace</code></li>
|
|
2721
2835
|
<li><a href="#资源闭包-foundationharnessresource-closure">资源闭包</a> → <code>computeResourceClosure</code> / <code>digestBytes</code> / <code>closureContains</code></li>
|
|
@@ -2787,6 +2901,31 @@
|
|
|
2787
2901
|
<li>调用方仍拥有的业务语义:选择哪个权威文件、摘要从何而来,以及读取失败后的处置。</li>
|
|
2788
2902
|
</ul>
|
|
2789
2903
|
<hr />
|
|
2904
|
+
<h2 id="身份绑定读取-foundationharnessbound-read">身份绑定读取 (foundation.harness.bound-read)<a class="headerlink" href="#身份绑定读取-foundationharnessbound-read" title="Permanent link">¶</a></h2>
|
|
2905
|
+
<h3 id="createFilesystemRootBinding--readFileBound">createFilesystemRootBinding / readFileBound<a class="headerlink" href="#createFilesystemRootBinding--readFileBound" title="Permanent link">¶</a></h3>
|
|
2906
|
+
<ul>
|
|
2907
|
+
<li>签名:<code>createFilesystemRootBinding(root)</code>;<code>readFileBound(root, relPath, { rootBinding, encoding?, expectedSha256? } = {})</code>(均为 async)。</li>
|
|
2908
|
+
<li>输入:已规范化的绝对真实目录、受收容的相对 POSIX 路径,以及调用方先前批准的冻结根绑定。<code>encoding</code> 仅支持 <code>utf8</code>;权威读取可带小写 sha256 预期摘要。</li>
|
|
2909
|
+
<li>输出:根绑定为冻结可序列化值;读取回执为冻结 <code>{ path, content, sha256, bytes, mode }</code>。</li>
|
|
2910
|
+
<li>语义边界:根与中间目录由固定四平台 N-API 闭包以不跟随符号链接的句柄相对方式获取;叶子必须是单链接普通文件。句柄不会逃逸,调用结束前关闭。绑定读取不提供删除或恢复状态机。</li>
|
|
2911
|
+
<li>副作用:只读文件系统访问;不写文件、不触 Git、网络或进程。</li>
|
|
2912
|
+
<li>错误:根身份不符、符号链接组件、缺失资源和摘要不符均失败关闭;不支持的 Darwin/Linux 架构不提供 JavaScript 回退。</li>
|
|
2913
|
+
<li><code>since</code> / <code>stability</code>:<code>0.9.0</code> / <code>stable</code>。</li>
|
|
2914
|
+
<li>源文件:<code>packages/skill-family-harness-node/src/bound-read.mjs</code> 与 <code>src/native/</code>。</li>
|
|
2915
|
+
<li>正例/负例测试:<code>packages/skill-family-harness-node/test/bound-read.test.mjs</code>。</li>
|
|
2916
|
+
</ul>
|
|
2917
|
+
<h2 id="固定集合发布-foundationharnessfixed-set-publication">固定集合发布 (foundation.harness.fixed-set-publication)<a class="headerlink" href="#固定集合发布-foundationharnessfixed-set-publication" title="Permanent link">¶</a></h2>
|
|
2918
|
+
<h3 id="createFixedSetPublicationManifest--publishFixedSet">createFixedSetPublicationManifest / publishFixedSet<a class="headerlink" href="#createFixedSetPublicationManifest--publishFixedSet" title="Permanent link">¶</a></h3>
|
|
2919
|
+
<ul>
|
|
2920
|
+
<li>签名:<code>createFixedSetPublicationManifest({ sourceRoot, targetParent, targetSegment })</code>;<code>publishFixedSet({ sourceRoot, targetParent, targetSegment, manifest })</code>(均为 async)。稳定入口也由 <code>skill-family-harness-node/fixed-set-publication</code> 导出。</li>
|
|
2921
|
+
<li>输入:同一规范父目录下的源目录、目标父目录、一个安全目标段和此前冻结的完整集合 manifest。</li>
|
|
2922
|
+
<li>输出:完整集合 manifest 与结构化 publication receipt。receipt 终态为 <code>succeeded</code>、<code>refused</code>、<code>failed</code> 或 <code>indeterminate</code>。</li>
|
|
2923
|
+
<li>语义边界:发布使用 Darwin <code>renameatx_np(RENAME_EXCL)</code> 或 Linux <code>renameat2(RENAME_NOREPLACE)</code> 的固定原生闭包;不使用检查后 <code>rename</code> 的 JavaScript 替代,不提供身份保护删除,不自动重试、回滚或恢复 <code>indeterminate</code>。</li>
|
|
2924
|
+
<li>副作用:仅在成功时对目标目录执行一次不替换发布;失败关闭。</li>
|
|
2925
|
+
<li><code>since</code> / <code>stability</code>:<code>0.9.0</code> / <code>stable</code>。</li>
|
|
2926
|
+
<li>源文件:<code>packages/skill-family-harness-node/src/fixed-set-publication.mjs</code> 与固定原生加载器。</li>
|
|
2927
|
+
<li>正例/负例测试:<code>packages/skill-family-harness-node/test/stable-filesystem-operations.test.mjs</code> 与既有固定集合边界测试。</li>
|
|
2928
|
+
</ul>
|
|
2790
2929
|
<h2 id="原子写-foundationharnessatomic-write">原子写 (foundation.harness.atomic-write)<a class="headerlink" href="#原子写-foundationharnessatomic-write" title="Permanent link">¶</a></h2>
|
|
2791
2930
|
<h3 id="writeFileAtomic">writeFileAtomic<a class="headerlink" href="#writeFileAtomic" title="Permanent link">¶</a></h3>
|
|
2792
2931
|
<ul>
|
|
@@ -3166,7 +3305,7 @@
|
|
|
3166
3305
|
<p><code>params</code> 是闭合对象。<code>root</code> 与 <code>path</code> 是必填非空字符串;<code>encoding</code> 只能是 <code>utf8</code> 或省略;<code>expectedSha256</code> 省略时不做预期摘要比对,提供时沿用核心严格读取合同。</p>
|
|
3167
3306
|
<p>桥接保留核心回执的 <code>path</code>、<code>sha256</code>、<code>bytes</code> 与 <code>mode</code>。UTF-8 内容仍是字符串;二进制内容投影成 Node 标准的 Buffer JSON 形态 <code>{ "type": "Buffer", "data": [...] }</code>,以便通过 JSON 传输后无损还原字节。</p>
|
|
3168
3307
|
<p>直接调用失败时沿用核心异常,包括 <code>SFC2004</code> 与 <code>details.kind</code>。候选 <code>mechanisms-cli.mjs</code> 继续使用一请求一响应 JSON:成功退出 0,拒绝或用法错误退出 2;CLI 错误 JSON 只承诺 <code>name</code> 与 <code>message</code>,不承诺跨语言保留 <code>details</code>。</p>
|
|
3169
|
-
<p>该入口不选择 method,不解释 domainResult,也不拥有重试、调度或生命周期。消费者必须把 Contracts、Harness 与 Engineering Kit 精确锁定到 0.
|
|
3308
|
+
<p>该入口不选择 method,不解释 domainResult,也不拥有重试、调度或生命周期。消费者必须把 Contracts、Harness 与 Engineering Kit 精确锁定到 0.9.0,并重建受管 Bundle;禁止从 Foundation 工作树导入候选源码。0.3.0 的 v2 与 0.2.1 的 v1 不兼容。</p>
|
|
3170
3309
|
<hr />
|
|
3171
3310
|
<h2 id="与机器事实层的互链">与机器事实层的互链<a class="headerlink" href="#与机器事实层的互链" title="Permanent link">¶</a></h2>
|
|
3172
3311
|
<ul>
|