快速开始¶
本页给普通开发者三条可执行旅程:新项目能力发现与骨架生成、存量项目采用与迁移、日常单需求查询。每条路径都给出精确命令;架构路由与 API 细节转到对应文档。
先判断需要哪种入口:
- 只有一段自然语言需求,还不确定 Foundation 是否已经覆盖时,调用唯一的
foundation-adoption-reviewSkill。向它提供明确的 Foundation 精确版本、同版本能力目录查询结果和adopt-plan结果;它只读分析,不安装、不初始化、不运行check或资格探测。 - 需要对目标根做完整静态工程审阅,或读取已有 Foundation 证明时,调用
foundation-engineering-check。它按所选范围审阅工程声明、公共能力采用和调用边界,再用check proof-create投影共同结论;读取旧证明用check proof。版本与入口两个机械分支通过不等于完整 Foundation 通过。 - 已经知道能力 ID,准备初始化空目录时,使用
scaffold。 - 已有项目需要盘点结构、冲突和迁移条件时,先使用只读
adopt-plan。得到计划后再决定是否授权projection或由项目自己修改存量文件。 - 已有声明需要与物理文件核对时,使用
check。它执行静态治理检查,不运行目标 Skill、业务脚本或 hooks。
能力目录中的 stable 表示该入口在所查发布版本中稳定;candidate 仍是候选。候选命中、迁移 complete、本地源码存在和研发自测通过,都不能单独证明能力已经发布、整个宿主已经受管或目标项目已经合规。当前发布与候选边界只从当前产品状态和所用精确版本的能力目录读取。
公共安装前提¶
本地候选验证从工作区打出三份当前版本 tarball,并把它们安装到临时 consumer。以下命令从 Foundation 工作区根目录运行;foundation_version 会读取根 package.json,作为三份 tarball 共用的版本:
foundation_version="$(node -p "require('./package.json').version")"
pack_dir="$(mktemp -d)"
(cd packages/skill-family-contracts && pnpm pack --pack-destination "$pack_dir")
(cd packages/skill-family-harness-node && pnpm pack --pack-destination "$pack_dir")
(cd packages/skill-family-engineering-kit && pnpm pack --pack-destination "$pack_dir")
mkdir "$pack_dir/consumer" && (cd "$pack_dir/consumer" && npm init -y)
(cd "$pack_dir/consumer" && npm install "$pack_dir/skill-family-contracts-${foundation_version}.tgz" "$pack_dir/skill-family-harness-node-${foundation_version}.tgz" "$pack_dir/skill-family-engineering-kit-${foundation_version}.tgz")
发布后安装状态页所列的精确坐标,再运行下文的 npm exec 命令。
新项目:发现能力并生成骨架¶
先用用途文件查看整个项目可用的能力,再显式选择稳定能力生成骨架。--list-capabilities 只读,不写项目;--uses 文件只保留问题、约束、保留保证和可选筛选词,不要写凭据或私密业务数据。
npm exec -- skill-family-kit adopt-plan --list-capabilities --all --scope all --locale zh-CN --uses ./uses.json
npm exec -- skill-family-kit scaffold --root ./my-project --project-id my-project --capability foundation.contracts.object-validation --capability foundation.harness.atomic-write
npm exec -- skill-family-kit check --root ./my-project
supportedMatches 只是候选发现,needsDecision 表示仍需由项目确认用途;它不会写 Profile 或宣称采用完成。scaffold 成功只表示骨架和契约测试接线已写入,适配器、领域保证和消费者测试仍需补齐。
存量项目:采用并完成迁移¶
先运行只读 adopt-plan,再在 migration manifest 中记录用途和四类 decision。direct-adoption 与 compatibility-layer 才能指向 Foundation 能力;keep-business 和 foundation-gap 保留在消费者侧。
npm exec -- skill-family-kit adopt-plan --root ./existing-repo
npm exec -- skill-family-kit adopt-plan --root ./existing-repo --list-capabilities --all --scope all --locale zh-CN --uses ./uses.json
npm exec -- skill-family-kit check --root ./existing-repo
adopt-plan 不写文件,也不自动迁移。迁移状态 complete 只表示 Profile、受管文件、旧实现退出、check 和四类证据都满足;它不等于契约接入完成。契约接入完成要由消费者自己的适配器测试与领域门禁声明。
参考骨架比较只报告结构差异,不把参考目录解释成所有语言、发行形式或宿主必须采用的规范。当前发布检查仍带有既有 Foundation 工程政策,例如版本源和入口形态的假设。单包、独立版本包、Python 项目或其他非 npm 版本源应先由采用诊断确认适用范围。旧政策检查产生发现时,不要直接把目标改造为本仓私有父工作区的结构。
日常工作:查询单项需求¶
不确定 capability ID 时,用当前语言做确定性子串查询。结果为空是 no-text-match,只命中 unsupported 能力是 boundary-found;这两种结果都不是 foundation-gap decision。
npm exec -- skill-family-kit adopt-plan --list-capabilities --locale zh-CN --filter "写文件失败时不能留下残缺文件"
需要证明真实宿主时,必须另行提供完整 request、bindings 和 --native,并使用能力目录声明的资格入口:
npm exec -- skill-family-kit check qualification \
--root <consumer-repo> \
--capability foundation.kit.plugin-verification \
--request <request-json> \
--bindings <private-bindings-json> \
--native
该命令的真实资格结论只来自一次显式、受约束的宿主执行;候选发现、迁移 complete 和契约接入完成都不能替代它。
旧版最短路径:生成骨架¶
若项目已确认不需要先做用途评估,仍可直接从零生成符合 Foundation 契约的骨架。
npm exec -- skill-family-kit scaffold --root ./my-project --project-id my-project
npm exec -- skill-family-kit check --root ./my-project
以上命令先生成骨架,再对生成结果做工程诊断。scaffold 只写空目标目录,非空或冲突目标会被拒绝且不被触碰;check 只诊断不修复。验证以 check 退出码 0 为通过。
存量项目:只读盘点(兼容入口)¶
目标是先看清存量仓能否采用,不改动任何字节。
npm exec -- skill-family-kit adopt-plan --root ./existing-repo
npm exec -- skill-family-kit check --root ./existing-repo
adopt-plan 输出现状、目标 Profile、精确写集、冲突与旧实现退出清单,且对输入仓字节零变化。check 只做只读诊断。确认盘点结果后再决定是否执行写入。
架构设计者:判定归属¶
目标是判断一个架构需求该落在 Foundation 哪一层,还是留在消费者。
- 读
docs/agents/architecture-routing.md的八步决策顺序。 - 在
docs/agents/capability-catalog.json按layer与intent找到能力,读它的entrypoints、sideEffects、failureSemantics、ownedByCaller。 - 需要发布、任务生命周期或制品关系时,分别转 release-skill、loop-agent、artifact-graph。
路由的硬边界:Foundation 不拥有远端写入、业务状态机、模型编排与领域审计语义。落入
keep-business或foundation-gap的能力不强行扩张 Foundation。
路径收容、用量估算或上限守卫只保证调用它们的那条路径。调用方仍负责让相关读取统一经过入口、定义事件和上限,并决定超限后的业务动作。Foundation 没有据此承诺全量跨语言治理、跨宿主权限交集或安全沙箱。
权威事实与规范¶
- 当前产品状态(版本、包集合、镜像坐标、门禁):当前产品状态(唯一状态页,本页不复制)。
- 开发与提交规范:Git 生命周期指南。
路径对照¶
| 读者 | 起点 | 下一步 |
|---|---|---|
| 新项目 | scaffold |
check → 接入 Profile |
| 存量项目 | adopt-plan |
分类(direct-adoption / compatibility-layer / keep-business / foundation-gap)→ 采用 |
| 架构设计者 | 路由决策 | 能力目录 → 真实导出与测试 |