简体中文

Recipe: Host Access and Profile Injection

1. Scenario and Non-Scenario

Applicable: you need to describe a registered host (claude/codex), probe or plan host access, verify peer-adapter directories, or use the package API for digest-bound local install/update.

Not applicable: needs Kit CLI apply, generic or remote apply, or automatic deleting uninstall; needs the full Qoder driver (that host is unsupported).

2. Architecture Choice and Capability ID

Preferred capabilities: foundation.kit.host (describeHost / probeHost / buildHostAdapter / verifyHostPeers / planHost / applyHostPlan) and foundation.profile.extension-spi (verifyProfile). Host-difference declarations are in foundation.profile.hosts.

3. Preconditions and Trust Boundary

• The host Profile is registered in profiles/hosts; from 0.11.0, the Kit package carries a managed projection of that closure. The only trusted drivers are claude-version-v1 / codex-version-v1. Local install/update additionally require a verified build, a digest-consistent plan, a contained targetRoot, and an explicit authorizationRef.
• Trust boundary: the Profile entry point must be a JSON data resource, and the public core does not import profiles/; coreOwned is a forbidden target.

4. Minimal Command and Code

# Describe a registered host
npm exec -- skill-family-kit adopt-plan host-describe --host claude --hosts-root profiles/hosts

# Read-only probe (no spawn by default)
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

The commands explicitly select the workspace Profile root. The code resolves the canonical packaged root before describe/probe, in-memory build, and plan, then validates a Profile declaration through verifyProfile; none of these operations executes install/update.

5. Expected Output and Evidence

describeHost returns the host description, probeHost returns read-only probe facts, planHost returns the access plan, and verifyProfile returns result codes such as SPE0000. Evidence: packages/skill-family-engineering-kit/test/host.test.mjs and fixtures/generic-profile-extension-conformance/verify.mjs.

6. Safety / Failure Negative Case

# Negative case: CLI apply stably refused
npm exec -- skill-family-kit adopt-plan host-apply --host claude --hosts-root profiles/hosts
# exit code 2: host apply is not implemented in the read-only Phase D slice

// Negative case: qoder is unsupported
describeHost("qoder"); // throws: support = "unsupported"

7. Copy-Paste Verification Command

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

8. Business Logic the Caller Continues to Own

• The host's concrete business semantics.
• Business authorization and completion criteria for local install/update; manual recovery and file deletion for uninstall.

9. Upgrade and Rollback Notes

• The package API applyHostPlan supports registered, digest-bound local install/update. Executing an uninstall plan only returns manual-recovery-required and does not delete files. Kit CLI apply, generic apply, and remote apply remain stably refused.
• verifyHostPeers only performs read-only peer-adapter directory verification; it grants no install, release, or domain decision.
• bundledHostProfilesRoot() only exposes the managed Profile root. Host APIs still require an explicit hostsRoot, and callers may select another conforming Profile root.
• The full Qoder driver is unsupported; only its structure is referenced, and it is not claimed to have been run on Qoder; adding a supported host on upgrade requires registering a descriptor and binding a trusted driver.