跳转至

English

架构边界

本页是 Skill Family Foundation 面向使用者的稳定架构投影。它只解释结构、职责、边界与路由,不承载动态发布状态(发布状态只由 docs/status/current.md 记录,且经 scripts/docs/fact-check.mjs 机械校验)。所有版本、命令、包数、支持状态都从机器真源复算。

Windows 架构边界

Foundation 0.28.0 的 Windows 分支适用于 Windows 11 x64、本地 NTFS 文件系统及普通用户环境,不构成真实宿主资格。foundation.harness.fixed-set-generation 机制支持固定世代发布与批量只读读取,由 publishFixedSetGeneration 与 resolveFixedSetGeneration 实现;消费者需确认旧世代已无读取者后,方可显式清理。三个固定世代 v1 对象——fixed-set-generation-pointer、fixed-set-generation-result、fixed-set-generation-resolution——登记于本地 Contracts 1.21.0,成熟度为 candidate。既有 POSIX v1 合同与双目录交换行为保持不变;Windows 不支持旧的双目录交换。官方 npm 包 skill-family-contracts@0.27.1 承载 Contracts 1.20.0、53 个对象;0.28.0 适用 Contracts 1.21.0、56 个对象,远端发布与可用性须以正式发布凭据核实。

分层

2026-08-09 架构 hand-off(FND-ADR-001~007,active,见 artifacts/decisions/)确立的分层:纵向依赖链四层,横向能力挂接,不新增纵层。

技能族业务(各产品仓:release-skill、loop-agent、skill-eval 等)
        │ 依赖
        ▼
Engineering Kit(scaffold / adopt-plan / projection / check)
        │ 依赖
        ▼
Harness Node(Contracts 机制协议实现)
        │ 依赖
        ▼
Contracts(结构、协议、错误码、协议名登记)
        ▲
        └---------------- independent Audit consumer

横向(挂接面,不新增纵层):
- profiles/       宿主与项目形态差异声明,只实现稳定 SPI
- 宿主            外部 AI 编码运行环境:拥有语义,Foundation 统一结构性差异
- release-skill   发布状态与全部远端写入,不进入 Foundation
- Artifact Graph  `artifacts/` 架构制品体系,门禁为 check:artifacts

同一 Git workspace 还包含 packages/foundation-adoption-review/。它是独立的 Plugin release unit 和公开镜像源,从 0.17.0 起与 Foundation 数值对齐,历史 0.1.0 发布保持不变。它使用 Foundation 的公开事实,但不属于 Contracts → Harness → Engineering Kit 依赖链,也不计作 Foundation 的第四个机制包。该 Plugin 的公开闭包由自己的 release unit 白名单限定;根目录的计划、制品、测试和其他私有文档不会进入 Plugin 镜像。

箭头指向被依赖方。公共核心不得反向依赖具体 Profile 或具体技能族;新能力的依赖方向落位见 artifacts/design/FND-DES-001.md,逐资产归属见 FND-ADR-002。

职责矩阵

每个分层只承担下表列出的职责,越界能力一律由外部项目或消费者拥有。

分层 拥有 不拥有(落在别处)
Contracts 结构、协议、错误码、协议名登记;当前本地合同源码为 56 类顶层对象;9 条 mandatory rule 业务字段语义、领域审计、远端写入、模型生成
Harness Contracts 的 Node 机制实现;路径收容、原子写、闭包、请求处理、报告渲染、宿主接入机制、状态底座 业务语义、workflow 编排、模型调用、git 写、网络远端
Engineering Kit 四个工程命令及其只读/受限写入边界;host 子动作注入具体 Profile 自动修复、自动迁移、远端发布、第 5 个命令
Profile 宿主与项目形态差异的声明式 SPI;只实现稳定 SPI 业务语义、可执行脚本入口、公共核心变更
release-skill 发布状态与全部远端写入 Foundation 不含任何 publish/remote-write 入口
loop-agent 任务、重试、返工、验收、自迭代 Foundation 不定义 workflow 状态机
Artifact Graph 制品关系、context、packet、version-lock Foundation 不拥有制品图
Audit 独立 fixture、预期值、裁决 领域语义结论由外部审阅拥有

能力归属算法

给一个架构需求,按下面顺序判定归属,命中即停:

  1. 含领域语义、业务状态机或审计 oracle → 留在消费者,只接业务中立机制。
  2. 是结构、协议、稳定错误码或对象 Schema → Contracts。
  3. 是跨技能族可复用的 Node 机制 → Harness。
  4. 是 scaffold/adopt-plan/projection/check 或具体 host Profile 注入 → Kit / Profile。
  5. 涉及发布远端状态 → release-skill。
  6. 涉及任务/重试/返工/验收 → loop-agent。
  7. 涉及制品关系/版本锁 → artifact-graph。
  8. 只有一个消费者或尚未证明跨两个真实消费者重复 → 留在消费者,不扩张 Foundation。

第 8 步是扩张闸门:新增组件必须说明删除它会让两个以上真实消费者重复实现,并经独立 fixture 验证;进入门 1 另要求至少一个现有真实消费者加一个结构同型的可预见消费者(第二消费者不要求已上线,但需求必须能用同一结构表达,调整记录见 FND-ADR-009)。第 9 步是有限封闭语义闸门(对应 FND-ADR-001 门 8):能力若携带少量领域语义,必须满足语义能被少数稳定封闭枚举覆盖,或为确定性估算原语——算法、适用范围与偏差方向已在契约中声明;本闸门不取消门 2「语义无关」一票否决。机器可读版见 docs/agents/architecture-routing.md。

信任与副作用边界

Foundation 的信任前提与副作用约定按层固化,调用方据此判断风险:

  • Contracts:纯函数,无文件/Git/网络/进程副作用;错误码冻结不漂移(foundation.contracts.error-codes)。
  • Harness:机制层只在受收容路径内读写;HARNESS_EXCLUSIONS 排除 release-state、remote-network-access、business-semantics、workflow-orchestration、model-calls、git-writes(foundation.harness.errors)。
  • Engineering Kit:FORBIDDEN_SIDE_EFFECTS 含 git-init/commit/push/tag、publish、remote-write;REFUSED_MUTATION_FLAGS 在 CLI 入口即拒(foundation.kit.cli)。
  • Profile:声明式差异,入口必须为 JSON 数据资源;coreOwned(packages/commands/namespacePrefixes)为禁入目标(foundation.profile.extension-spi)。
  • 状态底座:事件日志是唯一权威,snapshot 是派生缓存;confirmOwnerTerminated 是调用方提供的外部信任锚,不承诺抵御同权限恶意进程(foundation.harness.state-store)。

架构决策树

需求含领域语义/状态机/审计? ──是──▶ 留在消费者
        │否
是结构/协议/错误码/Schema? ──是──▶ Contracts
        │否
是跨技能族 Node 机制? ──是──▶ Harness
        │否
是 scaffold/adopt/projection/check 或 Profile 注入? ──是──▶ Kit / Profile
        │否
涉及发布远端状态? ──是──▶ release-skill
        │否
涉及任务/重试/返工/验收? ──是──▶ loop-agent
        │否
涉及制品关系/版本锁? ──是──▶ artifact-graph
        │否
只有一个消费者/未证明跨两个真实消费者? ──是──▶ 留在消费者,不扩张
        │否
携带少量领域语义? ──是──▶ 有限封闭语义:稳定闭枚举可覆盖,或为确定性
         │               估算原语(算法/适用范围/偏差方向已契约声明)→ 可纳入;
         │               否则留在消费者(FND-ADR-001 门 8,不取消门 2 一票否决)
         │否
        ──▶ 可纳入

与外部项目的路由关系

Foundation 不是全能底座。下列职责明确在 Foundation 之外:

  • 发布与远端写入:release-skill 拥有;Foundation 不提供任何 publish/remote-write 入口(foundation.unsupported.remote-publish)。
  • 任务生命周期:loop-agent 拥有任务、重试、返工、验收;Foundation 不含 workflow 状态机(foundation.unsupported.business-state-machine)。
  • 制品治理:artifact-graph 拥有 artifacts/ 关系合同与版本锁,门禁为 check:artifacts。
  • 领域审计:独立审计消费者拥有语义与最终接受/拒绝;Foundation 只提供确定性审计表面(foundation.unsupported.domain-audit-semantics)。
  • 宿主应用与生命周期:宿主拥有自身语义与生命周期行为;Foundation 只统一结构性差异,提供有限 host identity/alias 解析、受收容本地投影、绑定读取、原子写入和固定 driver 的受约束验证。只有 Descriptor 的 support=supported 时,planHost 才可能产出 status=planned 的 install/update 计划;Qoder 等 support=manual 宿主返回空的 status=manual 计划,applyHostPlan 对该计划返回 rejected 与 publicationState=not-attempted。applyHostPlan 只执行 status=planned 的计划;install/update 仍须摘要绑定、已验证 build 和显式授权,uninstall 返回 manual-recovery-required 且不删除文件。真实宿主验证使用六个封闭内置 driver,按固定参数执行 fresh、受约束调用,并复用 existing-user-state + host-managed。技能族(调用方)根据基础设施观察和业务答案解释业务结果并作最终领域验收。Qoder 的 Descriptor 为 manual,qodercli-print-v1 是 candidate 真实验证 driver;WorkBuddy 与 CodeBuddy 各用独立 driver 和发现布局。真实用户环境中的发布后插件发现、安装、更新、marketplace 与发布状态由 release-skill 管理。
  • 同级适配器只读验证:Contracts 1.10.0 增加成熟度中立的 request/result;Harness 复用真实根绑定、路径收容、读取、闭包和 manifest,按 peer 归一化后验证共同来源与唯一 SKILL.md mapping;Kit 只提供薄入口。Foundation 不拥有 canonical source,不写目录,不产生 receipt,也不接管旧 manifest 的业务迁移。
  • 真实宿主验证:Contracts 1.11.0 增加 host-verification-request 与 host-verification-result;Harness 在既有 superviseProcess 上提供原始字节 sink,Kit 维护六个封闭内置 candidate driver:其中包含 qodercli-print-v1、WorkBuddy 与 CodeBuddy 各自独立的 driver,以及另外三个已登记 driver。调用方创建、提供并独占本次验证所需的 fresh roots,完成检查后清理其独占的外层 temporaryRoot;Foundation 只在该根下创建并保留受跟踪的 session root。Foundation 校验 canonical/fresh 路径、路径收容、根重叠隔离、摘要与 Descriptor/driver 绑定,再按固定参数执行受约束调用;这些路径检查是路径边界,不是 OS sandbox。调用方根据基础设施观察和业务答案作最终领域验收。WorkBuddy 与 CodeBuddy 的 driver、发现目录和工作目录保持独立。Foundation 返回基础设施观察结果,不拥有领域输出、发布状态或真实用户环境中的插件发布后行为,也不宣称认证状态隔离、凭证未变化、模型身份固定或宿主工具能力已关闭。

宿主验证调用准备(未发布增量)

Kit 包根新增的 prepareHostVerification 尚未发布,不属于 0.20.0 已发布 API。它只为 Cursor 的单 Skill 调用准备输入,复用现有成员闭包、绑定读取、独占写入和固定驱动。Contracts Schema、Harness 机制、原有七驱动和四态结果不变,也不增加顶层命令。

调用方提供业务字节、声明成员、独占目录及现有用户状态根。Kit 复制字节、派生摘要、准备目录并返回冻结对象,不启动进程;原 runHostVerification 入口重新校验绑定,并在首次启动前核对实际安装摘要。返回对象的私有 readInvocationStream 方法按请求、证据根和流摘要读取字节,不解释业务答案。

调用方继续拥有业务语义、候选与载荷绑定、领域验收、发布新鲜度及资源清理。公共报告只能使用经校验的四态结果;准备对象、原始流和错误细节保持私有。必要业务流不可读时验证未完成;indeterminate 须保留现场,不能无条件清理。受控夹具只证明公开 API 接线,不新增真实宿主资格。

能力身份与成熟度

能力身份和成熟度是两个维度(FND-ADR-016)。历史 ./candidate/** 消费者迁移一次到 0.10.0 提供的规范入口;旧入口 只作为同源兼容面进入弃用窗口。0.10.0 以后新增能力从第一个 candidate 版本起就使用最终规范入口、Schema $id 和 operation。后续晋升 stable 只提高兼容承诺,不再触发消费者源码或合同身份改造。消费者要取得新发布的 stable 承诺仍需 更新三包精确 pin;Bundle 是否重建由既有 package identity、来源摘要与 provenance 绑定输入决定,而非成熟度标签决定。

物理 candidate/ 目录不是新的架构层,也不决定公开稳定性。Contracts 的机器政策和能力目录 stability 字段才是成熟度 真源;删除历史入口需要独立主版本决策和消费者退出证据,不能夹带在晋升中。

治理采用(本地未发布增量)

当前工作树把 Contracts 规格推进到 1.21.0、56 类顶层对象。既有的 professional-conclusion 已在 Contracts 1.20.0 登记,只统一专业方与消费方之间的六字段交换结构;专业 code、详情、适用范围和整改解释仍由提供方拥有。project-manifest 可选的 engineering 声明只列出要检查的发行单元版本来源与物理入口,不要求所有项目复制 Foundation 的仓库布局。

Engineering Kit 在既有 check 下增加显式 declared 分支。版本分支只读取声明的文本或 JSON 版本来源及镜像;入口分支只静态读取声明的普通文件,均不运行目标脚本、Skill、hook 或模型。 纯读取 API 与缺省命令不写文件。只有 runCommand("check") 与 checkEntriesAction 在调用方同时 给出已存在输出根和根内相对路径时,才独占创建一份公共结论;不自动建目录,也不覆盖现有文件。

本地 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 中复制检查逻辑。候选实现与局部验证不构成正式发布、业务资格或整体初始化完成的证明。

这组源码不是已发布 0.21.0 的组成部分。已发布 0.21.0 仍对应 Contracts 1.18.0 与 46 类 对象;新协议的发布、跨方正式采用,以及跨操作类别的权限交集均不在本地实现完成结论内。

下一阶段能力线(架构 hand-off)

三条能力线均经 FND-ADR-001 能力纳入门裁决纳入,全部在既有分层内落位:

  • 宿主接入线(FND-FR-001/FND-FR-002,FND-ADR-003,FND-ADR-017):Contracts 1.10.0 在既有 stable descriptor/probe/plan/receipt 合同上补足有限成熟度、手动事实与 digest 绑定的操作约束;Harness 复用 source closure、受收容本地投影、绑定读取、严格发布和原子替换;Kit 注入有限 Profile 与六个封闭内置 driver。只有 support=supported 的 Descriptor 才能让 planHost 产出 status=planned 的 install/update 计划;manual 宿主得到空的 status=manual 计划,applyHostPlan 返回 rejected / not-attempted。现有公共 API 保留 planHost / applyHostPlan,planned 计划仍须摘要绑定、已验证 build 和显式授权。真实宿主验证由调用方创建并独占 fresh roots,Foundation 校验 canonical/fresh、收容、重叠隔离、摘要与 Descriptor/driver 绑定并按固定参数调用;调用方根据基础设施观察和业务答案作最终领域验收。Qoder 的 Descriptor 为 manual,qodercli-print-v1 为 candidate 真实验证 driver;WorkBuddy 与 CodeBuddy 使用独立 driver 和发现布局。真实用户环境的发布后插件发现、安装、更新、marketplace 与发布状态由 release-skill 管理。
  • 持久状态底座线(FND-FR-003,FND-ADR-004):append-only 事件、hash chain、快照与校验恢复;只提供状态底座,状态机、任务节点、重试、终态、记忆等业务语义不纳入 Foundation。
  • 人类报告线(FND-FR-004,FND-ADR-005):双层合同——机器结果是唯一真源,人类报告由机器结果确定性渲染(Markdown + digest 绑定 + 分级检查),不自由撰写。
  • 有限封闭语义工具线(FND-ADR-009):基线物化 + contentGuard(摘要不符、物化中途变化、守卫检出均失败关闭)、通用只读 chokepoint(允许根集合 + 可选身份谓词)、策略化表面扫描(策略契约 + 注入式自测)、token 上界估算(确定性领域估算原语,无模型/网络/tokenizer 依赖)、通用上限守卫(复用 state-store 事件账与 token-lock,上限与超限策略由消费者配置)。

三包机制结构保持、不拆第四个机制包(FND-ADR-007);同一 workspace 内的独立 Plugin release unit 不改变这条依赖链。制品治理采用 artifact-graph CLI 与版本锁(FND-ADR-006)。

首版预算

  • 顶层 Contracts 对象:56 类(完整清单以 packages/skill-family-contracts/src/registry.json 为唯一真源):project-manifest、profile-descriptor、project-profile(FND-ADR-013,1.7.0 纳入)、managed-file-lock、operation-request、operation-result、migration-manifest、adapter-source、report-model、report-binding、host-descriptor、host-registry、host-capability-fact、host-probe-result、adapter-build-manifest、host-operation-plan、host-operation-receipt、state-event-envelope、state-snapshot-metadata、token-estimate-result、surface-scan-policy、declared-read-surface-result、structured-scan-policy(FND-ADR-010/011)、timeout-policy、watchdog-termination-envelope(FND-ADR-012,append-only 保持 1.5.0)、public-boundary-declaration、platform-difference-registry、observation-scope、profile-adoption-declaration、audit-baseline-pin、token-estimate-record(审计规则裁决与整改 1.6.0 纳入)、source-authority-receipt(1.8.0 纳入)、filesystem-root-binding、fixed-set-publication-manifest、fixed-set-publication-receipt(1.9.0 纳入)、adapter-peer-verification-request、adapter-peer-verification-result(FND-ADR-018,1.10.0 纳入)、host-verification-request、host-verification-result(FND-ADR-019,1.11.0 纳入)、plugin-verification-request、plugin-verification-result、filesystem-tree-observation(FND-ADR-021,1.13.0 纳入)、executable-identity-observation、skill-family-directory-verification-request、skill-family-directory-verification-result、engineering-baseline、professional-conclusion(本地 Contracts 1.19.0 候选)、file-set-apply-request、file-set-recovery-request、file-set-prune-request、file-set-result、file-set-event-payload、state-store-recovery-observation(FND-ADR-032,本地 Contracts 1.20.0 候选纳入)、fixed-set-generation-pointer、fixed-set-generation-result、fixed-set-generation-resolution(Contracts 1.21.0,candidate);
  • Kit 顶层命令:4 个(scaffold、adopt-plan、projection、check);
  • 强制机械规则:当前 9 条,预算不超过 20 条,绝对上限 30 条;CR-001 对登记表内全部 Schema 做统一编译;
  • 叶子包:3 个(skill-family-contracts、skill-family-harness-node、skill-family-engineering-kit);
  • Schema 校验器:Ajv 8.20.0(精确版本 pin),支持 draft-07 与 2020-12 双方言;
  • kernel 协议:skill-family.kernel.operation(stable),Contracts 规格版本 1.14.0;Kernel 文档仍保持 1.8.0 生命周期坐标和字节基线;
  • 默认运行时语言:Node;第二语言实现首版为 0。

任何新增组件必须说明删除它会导致的两个以上真实消费者重复实现,并通过独立 fixture 验证。

机器真源与文件分类

真源 内容
.foundation/skeleton-manifest.json 包清单、Profile、fixture、顶层命令
.foundation/version-lock.json projen、pnpm、Node 的精确版本与锁定点
.foundation/file-registry.json managed / handwritten / artifact 三类文件登记
package.json 与 packages/*/package.json 版本、命令、依赖(全部 projen 受管)
packages/skill-family-contracts/src/registry.json 协议名与 Schema $id 登记
scripts/release-artifact-contract.json 固定三包发布字节合同(成员、必需项与内容摘要规则)

受管文件只能通过 .projenrc.js 修改并运行 pnpm synth 再生成;手写文件(含全部文档)不会被 synth 覆盖。分类权威见 .foundation/file-registry.json。

文档系统与事实检查

文档体系的目标是用确定性检查消除手工漂移:

  1. 冻结事实包:文档写作只消费上表所列机器真源。模型或作者不得凭记忆写入版本、命令、包数;模型名、凭据和调度信息不进入文档,也不进入 Contracts。
  2. 事实检查:node scripts/docs/fact-check.mjs 对照真源校验文档中的包名、命令、门禁事实、版本 pin 与关键数字,并交叉校验真源之间的一致性(manifest 与 package.json、version-lock 与 packageManager、规则数与预算等)。
  3. 链接检查:node scripts/docs/link-check.mjs 解析 README 与全部 docs/**/*.md 的站内相对链接和标题锚点,并校验 mkdocs.yml nav 收录完整。
  4. 无工作流边界与公开边界验证:本仓没有任何 CI/CD workflow(旧拓扑的 ci/docs/docs-deploy 三个 Actions 已整体删除),全部门禁在私有工作区内运行(pnpm check);公开边界由 check:public-snapshots 与发布字节合同机械验证。公开静态站由 scripts/render-public-site.mjs 渲染(唯一输出 docs/public/site/** 与确定性基线 docs/public/site-baseline.json)。
  5. 版本锁定:站点工具链锁定在 scripts/docs/toolchain.json 与 scripts/docs/requirements.txt,构建只使用仓库外部的 Python 虚拟环境,不做系统级 pip install。

两个检查脚本都可直接 node scripts/docs/<name>.mjs 运行:fact-check.mjs 经仓内模块消费根目录精确锁定的 semver@7.8.5,运行前必须先完成 pnpm install --frozen-lockfile;link-check.mjs 为纯 Node 实现。职责说明见 scripts/docs/README.md。

稳定产品门禁

根 pnpm check 只编排 11 个稳定产品 gate ID(check:structure~check:artifacts,逐 ID 见 当前产品状态),不再锁死原始命令清单;每个稳定 ID 在自己的 package script 内组合少量产品检查。门禁事实由 node scripts/docs/fact-check.mjs 从根 package.json 的 scripts.check 机械推导并逐字核对。文档与 setup 只调用或列出 11 个稳定 ID 或根 pnpm check,不复制底层命令列表。

仓内检查的诚实边界:结构检查只证明“字节/结构一致性(仓内可证)”;一次性迁移完整性、普通正文语义与最终接受/拒绝结论属于外部审阅职责,不在目标仓内维护第二份门禁 registry、baseline 或命令比较器。