English

架构边界

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

分层

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

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

职责矩阵

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

分层	拥有	不拥有（落在别处）
Contracts	结构、协议、错误码、协议名登记；39 类顶层对象；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）。
• 宿主应用与生命周期：有限 host identity/alias 解析、独立 probe facts 与本地 install/update 复用既有绑定读取和发布原语；uninstall 因缺少安全绑定删除原语而拒绝并转人工恢复。Qoder 仍为 unsupported，DeepSeek Harness 仅为 developer-preview 身份事实；远端发布、自动信任和消费者 smoke 不在 Foundation（foundation.unsupported.qoder-driver）。
• 同级适配器只读验证：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 实现 Kimi 与 WorkBuddy 两个内置 candidate driver（均绑定 existing-user-state + host-managed）的受约束执行、现有用户状态根边界与结果组合。Foundation 不拥有领域输出或发布状态，也不宣称认证状态隔离、凭证未变化、模型身份固定或宿主工具能力已关闭。

能力身份与成熟度

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

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

下一阶段能力线（架构 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。0.10.0 提供 describe/build/probe/plan 及受显式授权保护的本地 install/update；uninstall 保持人工恢复拒绝。0.11.0 追加独立的真实宿主验证候选，登记 Kimi 与 WorkBuddy 两个内置 driver，复用现有登录态。
• 持久状态底座线（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）；制品治理采用 artifact-graph CLI 与版本锁（FND-ADR-006）。

首版预算

• 顶层 Contracts 对象：42 类（完整清单以 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 纳入）；
• 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.13.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 或命令比较器。