English

Recipe：宿主接入与 Profile 注入¶

1. 场景与非场景¶

适用：需要描述已登记宿主（claude/codex）、探测或规划宿主接入，验证同级 adapter 目录，或者通过包 API 执行摘要绑定的本地 install/update。

不适用：需要 Kit CLI apply、通用或远端 apply、自动删除式 uninstall；需要 Qoder 的 install/update 生命周期 driver（该宿主为 manual，只支持受约束的真实宿主验证，不授予生命周期能力）。

2. 架构选择及能力 ID¶

首选能力：foundation.kit.host（describeHost / probeHost / buildHostAdapter / verifyHostPeers / planHost / applyHostPlan）与 foundation.profile.extension-spi（verifyProfile）。宿主差异声明在 foundation.profile.hosts。

3. 前置条件与信任边界¶

宿主 Profile 已在 profiles/hosts 登记；0.11.0 起，Kit 安装包携带该闭包的受管投影。受信 driver 仅 claude-version-v1 / codex-version-v1。本地 install/update 还要求已验证 build、摘要一致的 plan、受收容 targetRoot 与显式 authorizationRef。
信任边界：Profile 入口必须是 JSON 数据资源，公共核心不导入 profiles/；coreOwned 为禁入目标。

4. 最小命令与代码¶

# 描述已登记宿主
npm exec -- skill-family-kit adopt-plan host-describe --host claude --hosts-root profiles/hosts

# 只读探测（默认不 spawn）
npm exec -- skill-family-kit adopt-plan host-probe --host claude --hosts-root profiles/hosts

import { bundledHostProfilesRoot, buildHostAdapter, describeHost, probeHost, planHost } from "skill-family-engineering-kit";
import { verifyProfile } from "profiles/spi/index.mjs";

const hostsRoot = bundledHostProfilesRoot();
const desc = await describeHost({ hostId: "claude", hostsRoot });
const facts = await probeHost({ hostId: "claude", hostsRoot, allowSpawn: false });
const build = await buildHostAdapter({
  hostId: "claude",
  pathCategoryId: "claude-project-skills",
  input: {
    schemaVersion: 1,
    kind: "skill-family.adapter-source",
    skillFamilyId: "example-family",
    skills: [{ id: "demo", files: [{ path: "SKILL.md", content: "# Demo\n" }] }],
  },
  hostsRoot,
});
const plan = await planHost({
  hostId: "claude",
  pathCategoryId: "claude-project-skills",
  buildManifest: build.manifest,
  probeFacts: facts.facts,
  hostsRoot,
});
const spi = verifyProfile({ profileRoot: "profiles/public-plugin" }); // SPE0000

以上命令展示了如何显式选择仓内 Profile 根。代码则从安装包取得规范根，再运行 describe/probe、内存构建和 plan，并用 verifyProfile 校验 Profile 声明；这些操作没有执行 install/update。

5. 预期输出与证据¶

describeHost 返回宿主描述，probeHost 返回只读探测事实，planHost 返回接入计划，verifyProfile 返回 SPE0000 等结果码。证据：packages/skill-family-engineering-kit/test/host.test.mjs 与 fixtures/generic-profile-extension-conformance/verify.mjs。

6. 安全/失败负例¶

# 负例：CLI apply 稳定拒绝
npm exec -- skill-family-kit adopt-plan host-apply --host claude --hosts-root profiles/hosts
# 退出码 2：host apply is not implemented in the read-only Phase D slice

// 负例：qoder 为 manual，不授予生命周期能力
const qoder = await describeHost({ hostId: "qoder", hostsRoot }); // support = "manual"，无 driverId
const qoderFacts = await probeHost({ hostId: "qoder", hostsRoot }); // 九项均为 unknown / driver-limited
const qoderPlan = await planHost({ hostId: "qoder", hostsRoot }); // status = "manual"，actions 为空

7. 可复制验证命令¶

node --test packages/skill-family-engineering-kit/test/host.test.mjs \
           fixtures/generic-profile-extension-conformance/verify.mjs

8. 调用方继续拥有的业务逻辑¶

宿主具体业务语义。
本地 install/update 的业务授权与完成判定；卸载时的人工恢复和文件删除。

9. 升级与回滚注意事项¶

包 API applyHostPlan 支持已登记、摘要绑定的本地 install/update；执行 uninstall 计划只返回 manual-recovery-required，不删除文件。Kit CLI apply、通用或远端 apply 仍稳定拒绝。
verifyHostPeers 只做同级 adapter 目录的只读复验，不授予安装、发布或领域裁决能力。
bundledHostProfilesRoot() 只提供受管 Profile 根。宿主入口仍要求显式传 hostsRoot，调用方也可以选择另一组符合合同的 Profile。
Qoder 为 manual 宿主：Descriptor support 与 maturity 均为 manual，真实验证能力的稳定性由能力目录的 stability=candidate 表达。只登记受约束的真实宿主验证能力，不授予 build、plan、apply、通用 install/update/uninstall 或 rollback；升级新增受支持宿主须登记 descriptor 并绑定受信 driver。