release-skill 0.2.2 → 0.2.3

package/src/core/plan.mjs

@@ -882,6 +882,184 @@ export function validatePlanActionCompleteness(plan, options = {}) {
           }
         }
 
+        // sourceCommit: frozen plugin source commit, binding the marketplace
+        // install action to the unit's frozen snapshot commit. Both forms
+        // require it in production plans; non-production diagnostic plans may
+        // omit it (never冒充生产计划).
+        if (production) {
+          _checkRequired(action, 'parameters.sourceCommit', action.parameters?.sourceCommit, frozen?.commit, unitId, failures);
+        }
+
+        // --- sourceDescriptor validation (marketplace source identity contract) ---
+        // Validates that marketplaceForm and sourceDescriptor.form are consistent,
+        // all form-specific fields are present and non-null, pluginRepo !== marketplaceRepo
+        // for standalone-index, and no mixed/extra fields exist.
+        // Only applies to platforms that require marketplace (claude, codex).
+        // Non-automatable platforms (kimi, codebuddy) use human-attestation
+        // and carry no marketplace form or source descriptor.
+        // Legacy plans (pre-sourceDescriptor) with legacyCompatibility are tolerated.
+        if (requiresMarketplace) {
+          const sd = action.parameters?.sourceDescriptor;
+          const mf = action.parameters?.marketplaceForm;
+          if (sd === undefined || sd === null) {
+            if (!options.legacyCompatibility) {
+              failures.push(
+                `unit "${unitId}", action "${action.id}": parameters.sourceDescriptor is missing; every marketplace install action must carry a complete source descriptor`,
+              );
+            }
+          } else if (typeof sd === 'object') {
+            // 1. marketplaceForm must be present when sourceDescriptor is present
+            if (mf === undefined || mf === null) {
+              failures.push(
+                `unit "${unitId}", action "${action.id}": parameters.marketplaceForm is missing but sourceDescriptor is present; form must be explicitly declared`,
+              );
+            }
+            // 2. sourceDescriptor.form must match marketplaceForm
+            if (sd.form !== mf) {
+              failures.push(
+                `unit "${unitId}", action "${action.id}": sourceDescriptor.form "${sd.form}" does not match parameters.marketplaceForm "${mf}"`,
+              );
+            }
+            // 3. Form-specific field completeness and non-null checks
+            // payloadDigest is allowed to be null in non-production plans
+            // (the frozen manifestDigest is only available after production freeze)
+            const BUNDLED_REQUIRED = ['form', 'repo', 'marketplaceEntry', 'pluginSubpath'];
+            const STANDALONE_REQUIRED = ['form', 'marketplaceRepo', 'marketplaceEntry', 'pluginRepo', 'sourceType'];
+            // Production-only fields that may be null in non-production plans
+            const PROD_ONLY_FIELDS = ['marketplaceCommitSha', 'ref', 'payloadDigest'];
+
+            if (sd.form === 'bundled-family') {
+              // Check bundled-family required fields are present and non-null
+              for (const field of BUNDLED_REQUIRED) {
+                if (sd[field] === undefined || sd[field] === null) {
+                  failures.push(
+                    `unit "${unitId}", action "${action.id}": sourceDescriptor.${field} is missing or null; bundled-family form requires all identity fields to be non-null`,
+                  );
+                }
+              }
+              // commit must be non-null in production plans (frozen from asset)
+              if (production && (sd.commit === undefined || sd.commit === null)) {
+                failures.push(
+                  `unit "${unitId}", action "${action.id}": sourceDescriptor.commit is missing or null; production bundled-family plans require a frozen commit`,
+                );
+              }
+              // commit must match frozenSnapshot.commit (production binding)
+              if (production && sd.commit !== undefined && sd.commit !== null &&
+                  frozen?.commit !== undefined && sd.commit !== frozen.commit) {
+                failures.push(
+                  `unit "${unitId}", action "${action.id}": sourceDescriptor.commit does not match frozenSnapshot.commit`,
+                );
+              }
+              // payloadDigest must be non-null in production plans
+              if (production && (sd.payloadDigest === undefined || sd.payloadDigest === null)) {
+                failures.push(
+                  `unit "${unitId}", action "${action.id}": sourceDescriptor.payloadDigest is missing or null; production plans require a frozen payload digest`,
+                );
+              }
+              // Prohibit standalone-index fields in bundled-family
+              const STANDALONE_ONLY = ['marketplaceRepo', 'pluginRepo', 'sourceType', 'marketplaceCommitSha', 'ref'];
+              for (const field of STANDALONE_ONLY) {
+                if (sd[field] !== undefined) {
+                  failures.push(
+                    `unit "${unitId}", action "${action.id}": sourceDescriptor.${field} is unexpected for bundled-family form; mixed fields are prohibited`,
+                  );
+                }
+              }
+              // repo must match the action's repo (publicRepo for bundled-family)
+              if (sd.repo !== undefined && sd.repo !== null && sd.repo !== publicRepo) {
+                failures.push(
+                  `unit "${unitId}", action "${action.id}": sourceDescriptor.repo "${sd.repo}" does not match unit publicRepo "${publicRepo}"`,
+                );
+              }
+              // marketplaceEntry must match action.plugin
+              if (sd.marketplaceEntry !== undefined && sd.marketplaceEntry !== null && sd.marketplaceEntry !== plugin) {
+                failures.push(
+                  `unit "${unitId}", action "${action.id}": sourceDescriptor.marketplaceEntry "${sd.marketplaceEntry}" does not match action plugin "${plugin}"`,
+                );
+              }
+              // payloadDigest must match manifestDigest (when both are present)
+              if (production && sd.payloadDigest !== undefined && sd.payloadDigest !== null &&
+                  frozen?.manifestDigest !== undefined && sd.payloadDigest !== frozen.manifestDigest) {
+                failures.push(
+                  `unit "${unitId}", action "${action.id}": sourceDescriptor.payloadDigest does not match frozen manifestDigest`,
+                );
+              }
+            } else if (sd.form === 'standalone-index') {
+              // Check standalone-index required fields are present and non-null
+              for (const field of STANDALONE_REQUIRED) {
+                if (sd[field] === undefined || sd[field] === null) {
+                  failures.push(
+                    `unit "${unitId}", action "${action.id}": sourceDescriptor.${field} is missing or null; standalone-index form requires all identity fields to be non-null`,
+                  );
+                }
+              }
+              // Production-only fields: must be non-null in production plans
+              if (production) {
+                for (const field of PROD_ONLY_FIELDS) {
+                  if (sd[field] === undefined || sd[field] === null) {
+                    failures.push(
+                      `unit "${unitId}", action "${action.id}": sourceDescriptor.${field} is missing or null; production standalone-index requires all fields to be non-null`,
+                    );
+                  }
+                }
+              }
+              // Prohibit bundled-family fields in standalone-index
+              const BUNDLED_ONLY = ['repo', 'commit', 'pluginSubpath'];
+              for (const field of BUNDLED_ONLY) {
+                if (sd[field] !== undefined) {
+                  failures.push(
+                    `unit "${unitId}", action "${action.id}": sourceDescriptor.${field} is unexpected for standalone-index form; mixed fields are prohibited`,
+                  );
+                }
+              }
+              // pluginRepo must NOT equal marketplaceRepo
+              if (sd.pluginRepo !== undefined && sd.pluginRepo !== null &&
+                  sd.marketplaceRepo !== undefined && sd.marketplaceRepo !== null &&
+                  sd.pluginRepo === sd.marketplaceRepo) {
+                failures.push(
+                  `unit "${unitId}", action "${action.id}": sourceDescriptor.pluginRepo must not equal marketplaceRepo; the plugin repo and marketplace repo are distinct repositories`,
+                );
+              }
+              // marketplaceRepo must match action.repo (for standalone-index, repo is the external marketplace)
+              if (externalMarketplace && sd.marketplaceRepo !== undefined && sd.marketplaceRepo !== null &&
+                  sd.marketplaceRepo !== dist.marketplaceRepo) {
+                failures.push(
+                  `unit "${unitId}", action "${action.id}": sourceDescriptor.marketplaceRepo "${sd.marketplaceRepo}" does not match distribution marketplaceRepo "${dist.marketplaceRepo}"`,
+                );
+              }
+              // pluginRepo must match the unit's publicRepo
+              if (sd.pluginRepo !== undefined && sd.pluginRepo !== null && sd.pluginRepo !== publicRepo) {
+                failures.push(
+                  `unit "${unitId}", action "${action.id}": sourceDescriptor.pluginRepo "${sd.pluginRepo}" does not match unit publicRepo "${publicRepo}"`,
+                );
+              }
+              // marketplaceEntry must match action.plugin
+              if (sd.marketplaceEntry !== undefined && sd.marketplaceEntry !== null && sd.marketplaceEntry !== plugin) {
+                failures.push(
+                  `unit "${unitId}", action "${action.id}": sourceDescriptor.marketplaceEntry "${sd.marketplaceEntry}" does not match action plugin "${plugin}"`,
+                );
+              }
+              // sourceType must be 'marketplace-entry'
+              if (sd.sourceType !== undefined && sd.sourceType !== null && sd.sourceType !== 'marketplace-entry') {
+                failures.push(
+                  `unit "${unitId}", action "${action.id}": sourceDescriptor.sourceType "${sd.sourceType}" is unexpected; standalone-index sourceType must be "marketplace-entry"`,
+                );
+              }
+              // payloadDigest must match manifestDigest (when both are present)
+              if (production && sd.payloadDigest !== undefined && sd.payloadDigest !== null &&
+                  frozen?.manifestDigest !== undefined && sd.payloadDigest !== frozen.manifestDigest) {
+                failures.push(
+                  `unit "${unitId}", action "${action.id}": sourceDescriptor.payloadDigest does not match frozen manifestDigest`,
+                );
+              }
+            } else {
+              failures.push(
+                `unit "${unitId}", action "${action.id}": sourceDescriptor.form "${sd.form}" is unknown; expected "bundled-family" or "standalone-index"`,
+              );
+            }
+          }
+        }
+
         // Expected checks. Marketplace identity is bound only on platforms
         // whose schema requires it (MINOR-1): a non-marketplace platform's
         // observation never binds a marketplace.

package/src/platforms/codebuddy.mjs

@@ -242,6 +242,19 @@ function codebuddyDesktopTailSegments(marketplace, plugin) {
   return [CODEBUDDY_DESKTOP_HOME_DIR, 'plugins', 'marketplaces', marketplace, 'plugins', plugin];
 }
 
+/**
+ * Segment-level tail an attested cli installPath must end with:
+ * `/.codebuddy/plugins/marketplaces/<marketplace>/plugins/<plugin>`
+ * (verified CodeBuddy CLI layout).
+ *
+ * @param {string} marketplace
+ * @param {string} plugin
+ * @returns {string[]}
+ */
+function codebuddyCliTailSegments(marketplace, plugin) {
+  return [CODEBUDDY_CLI_STATE_DIR, 'plugins', 'marketplaces', marketplace, 'plugins', plugin];
+}
+
 /**
  * Segment-level check that a desktop installPath ends with the well-known
  * WorkBuddy marketplace layout. Pure string check (no filesystem): the path's
@@ -261,6 +274,25 @@ function matchesDesktopLayout(installPath, marketplace, plugin) {
   return tail.every((segment, index) => segments[offset + index] === segment);
 }
 
+/**
+ * Segment-level check that a cli installPath ends with the well-known
+ * CodeBuddy CLI marketplace layout. Pure string check (no filesystem): the
+ * path's segments (split on `/` or `\`, dropping empty/`.` segments) must end
+ * with the cli tail. Fails closed otherwise.
+ *
+ * @param {string} installPath
+ * @param {string} marketplace
+ * @param {string} plugin
+ * @returns {boolean}
+ */
+function matchesCliLayout(installPath, marketplace, plugin) {
+  const segments = installPath.split(/[\\/]+/).filter((s) => s !== '' && s !== '.');
+  const tail = codebuddyCliTailSegments(marketplace, plugin);
+  if (segments.length < tail.length) return false;
+  const offset = segments.length - tail.length;
+  return tail.every((segment, index) => segments[offset + index] === segment);
+}
+
 /**
  * Human-facing, actionable manual-install closed-loop instructions for
  * CodeBuddy / WorkBuddy.
@@ -411,6 +443,14 @@ export function validateCodeBuddyAttestation(attestation, action, isoNow, boundP
       && !matchesDesktopLayout(attestation.installPath, attestation.marketplace, attestation.plugin)) {
     return { valid: false, error: `codebuddy attestation installPath does not match the WorkBuddy desktop marketplace layout (.workbuddy/plugins/marketplaces/${attestation.marketplace}/plugins/${attestation.plugin})` };
   }
+  // CLI installPath must end with the well-known CodeBuddy CLI marketplace
+  // layout (segment-level). This is a lexical check; the full realpath
+  // containment within the isolated home is enforced in the adapter observe
+  // branch (needs the context-derived isolated home + realpath resolution).
+  if (attestation.installChannel === 'cli'
+      && !matchesCliLayout(attestation.installPath, attestation.marketplace, attestation.plugin)) {
+    return { valid: false, error: `codebuddy attestation installPath does not match the CodeBuddy CLI marketplace layout (.codebuddy/plugins/marketplaces/${attestation.marketplace}/plugins/${attestation.plugin})` };
+  }
   return { valid: true, error: null };
 }
 

package/src/platforms/registry.mjs

@@ -137,6 +137,12 @@ const CLAUDE = Object.freeze({
   // actionType -> adapter map from it (T2.2 step 3).
   adapter: 'plugin-marketplace',
   automatable: true,
+  // --- capability contract (平台能力契约) ------------------------------------
+  installMethod: 'structured-cli',
+  refStrength: 'name-ref',
+  outputProtocol: 'text',
+  identityEvidence: 'list-record',
+  degradationPolicy: 'block',
   cli: Object.freeze({
     binary: 'claude',
     marketplaceAdd: (repo, ref) => ['plugin', 'marketplace', 'add', `${repo}@${ref}`],
@@ -190,6 +196,12 @@ const CODEX = Object.freeze({
   actionType: 'codex-marketplace-install',
   adapter: 'plugin-marketplace',
   automatable: true,
+  // --- capability contract (平台能力契约) ------------------------------------
+  installMethod: 'structured-cli',
+  refStrength: 'commit-sha',
+  outputProtocol: 'structured',
+  identityEvidence: 'install-output',
+  degradationPolicy: 'block',
   cli: Object.freeze({
     binary: 'codex',
     marketplaceAdd: (repo, ref) => ['plugin', 'marketplace', 'add', repo, '--ref', ref, '--json'],
@@ -242,6 +254,12 @@ const KIMI = Object.freeze({
   actionType: 'kimi-marketplace-install',
   adapter: 'plugin-marketplace',
   automatable: false,
+  // --- capability contract (平台能力契约) ------------------------------------
+  installMethod: 'interactive-only',
+  refStrength: 'unfixable',
+  outputProtocol: 'none',
+  identityEvidence: 'filesystem-payload',
+  degradationPolicy: 'human-attestation',
   cli: null,
   jsonProtocol: Object.freeze({
     listOutput: null,
@@ -307,6 +325,12 @@ const CODEBUDDY = Object.freeze({
   actionType: 'codebuddy-marketplace-install',
   adapter: 'plugin-marketplace',
   automatable: false,
+  // --- capability contract (平台能力契约) ------------------------------------
+  installMethod: 'human-attestation',
+  refStrength: 'unfixable',
+  outputProtocol: 'none',
+  identityEvidence: 'human-attestation',
+  degradationPolicy: 'human-attestation',
   cli: null,
   jsonProtocol: Object.freeze({
     listOutput: null,
@@ -373,6 +397,11 @@ const VALID_MARKETPLACE_REF_FORMS = new Set(['sha', 'name', null]);
 const VALID_LIST_OUTPUTS = new Set(['array', 'installed-object', null]);
 const VALID_CLI_OUTPUTS = new Set(['json', null]);
 const VALID_ENTRY_VERSION_BINDING = new Set([true, false, null]);
+const VALID_INSTALL_METHODS = new Set(['structured-cli', 'interactive-only', 'human-attestation']);
+const VALID_REF_STRENGTHS = new Set(['commit-sha', 'name-ref', 'unfixable']);
+const VALID_OUTPUT_PROTOCOLS = new Set(['structured', 'text', 'none']);
+const VALID_IDENTITY_EVIDENCE = new Set(['list-record', 'install-output', 'filesystem-payload', 'human-attestation']);
+const VALID_DEGRADATION_POLICIES = new Set(['block', 'human-attestation']);
 
 /**
  * Look up a platform descriptor by id.
@@ -453,6 +482,23 @@ export function assertRegistry(registry = PLATFORMS) {
       throw new Error(`platform registry: ${label} isolationSubdirs must be an array`);
     }
 
+    // --- capability contract validation (能力契约验证) -----------------------
+    if (!VALID_INSTALL_METHODS.has(platform.installMethod)) {
+      throw new Error(`platform registry: ${label} has illegal installMethod "${platform.installMethod}"`);
+    }
+    if (!VALID_REF_STRENGTHS.has(platform.refStrength)) {
+      throw new Error(`platform registry: ${label} has illegal refStrength "${platform.refStrength}"`);
+    }
+    if (!VALID_OUTPUT_PROTOCOLS.has(platform.outputProtocol)) {
+      throw new Error(`platform registry: ${label} has illegal outputProtocol "${platform.outputProtocol}"`);
+    }
+    if (!VALID_IDENTITY_EVIDENCE.has(platform.identityEvidence)) {
+      throw new Error(`platform registry: ${label} has illegal identityEvidence "${platform.identityEvidence}"`);
+    }
+    if (!VALID_DEGRADATION_POLICIES.has(platform.degradationPolicy)) {
+      throw new Error(`platform registry: ${label} has illegal degradationPolicy "${platform.degradationPolicy}"`);
+    }
+
     if (platform.automatable) {
       if (!platform.cli || typeof platform.cli.marketplaceAdd !== 'function'
           || typeof platform.cli.install !== 'function' || typeof platform.cli.list !== 'function') {
@@ -481,8 +527,120 @@ export function assertRegistry(registry = PLATFORMS) {
         throw new Error(`platform registry: non-automatable platform ${label} needs strategy.readManifest`);
       }
     }
+
+    // --- capability contract consistency rules (能力契约一致性规则) -----------
+    // automatable === true 必须有 installMethod === 'structured-cli'
+    if (platform.automatable === true && platform.installMethod !== 'structured-cli') {
+      throw new Error(`platform registry: ${label} is automatable but installMethod is "${platform.installMethod}" (expected "structured-cli")`);
+    }
+    // automatable === false 必须有 installMethod !== 'structured-cli'
+    if (platform.automatable === false && platform.installMethod === 'structured-cli') {
+      throw new Error(`platform registry: ${label} is not automatable but installMethod is "structured-cli"`);
+    }
+    // installMethod === 'structured-cli' 必须有 refStrength !== 'unfixable'
+    if (platform.installMethod === 'structured-cli' && platform.refStrength === 'unfixable') {
+      throw new Error(`platform registry: ${label} has structured-cli install but unfixable refStrength`);
+    }
+    // installMethod === 'human-attestation' 必须有 identityEvidence === 'human-attestation'
+    if (platform.installMethod === 'human-attestation' && platform.identityEvidence !== 'human-attestation') {
+      throw new Error(`platform registry: ${label} has human-attestation install but identityEvidence is "${platform.identityEvidence}"`);
+    }
   }
 }
 
 // Self-validate at import time: a malformed registry never reaches runtime.
 assertRegistry();
+
+// --- capability-driven routing & conflict detection (能力驱动路由与矛盾检测) --
+
+/**
+ * 根据平台描述符的 installMethod 决定执行路由。
+ *
+ * @param {object} platform - 平台描述符
+ * @returns {{ route: string, reason: string }}
+ * @throws {Error} 无法路由时抛出
+ */
+export function resolvePlatformRoute(platform) {
+  const { installMethod } = platform;
+  if (installMethod === 'structured-cli') {
+    return { route: 'structured-cli', reason: `installMethod is structured-cli` };
+  }
+  if (installMethod === 'interactive-only' || installMethod === 'human-attestation') {
+    return { route: 'human-attestation', reason: `installMethod is ${installMethod}` };
+  }
+  throw new Error(
+    `platform "${platform?.id ?? '<unknown>'}" with installMethod="${installMethod}" cannot be routed`,
+  );
+}
+
+/**
+ * 检测平台能力描述符中的矛盾。
+ *
+ * @param {object} platform - 平台描述符
+ * @returns {{ hasConflict: boolean, conflicts: string[] }}
+ * @throws {Error} 发现矛盾时抛出
+ */
+export function resolveCapabilityConflicts(platform) {
+  const conflicts = [];
+  const { id, automatable, installMethod, refStrength, identityEvidence, cli, strategy } = platform;
+
+  // automatable <-> installMethod 一致性
+  if (automatable === true && installMethod !== 'structured-cli') {
+    conflicts.push(`automatable=true but installMethod="${installMethod}"`);
+  }
+  if (automatable === false && installMethod === 'structured-cli') {
+    conflicts.push(`automatable=false but installMethod="structured-cli"`);
+  }
+
+  // installMethod <-> refStrength 一致性
+  if (installMethod === 'structured-cli' && refStrength === 'unfixable') {
+    conflicts.push(`structured-cli with unfixable refStrength`);
+  }
+
+  // installMethod <-> identityEvidence 一致性
+  if (installMethod === 'human-attestation' && identityEvidence !== 'human-attestation') {
+    conflicts.push(`human-attestation install but identityEvidence="${identityEvidence}"`);
+  }
+
+  // 自动化平台必须有 cli 和策略解析函数
+  if (automatable === true) {
+    if (!cli || typeof cli !== 'object') {
+      conflicts.push(`automatable=true but cli is missing`);
+    }
+    if (!strategy || typeof strategy.parseListOutput !== 'function') {
+      conflicts.push(`automatable=true but strategy.parseListOutput is missing`);
+    }
+    if (!strategy || typeof strategy.extractInstallPath !== 'function') {
+      conflicts.push(`automatable=true but strategy.extractInstallPath is missing`);
+    }
+  }
+
+  // 非自动化平台必须 cli === null，且有手动策略函数
+  if (automatable === false) {
+    if (cli !== null) {
+      conflicts.push(`automatable=false but cli is not null`);
+    }
+    if (!strategy || typeof strategy.buildManualRequirement !== 'function') {
+      conflicts.push(`automatable=false but strategy.buildManualRequirement is missing`);
+    }
+    if (!strategy || typeof strategy.readManifest !== 'function') {
+      conflicts.push(`automatable=false but strategy.readManifest is missing`);
+    }
+  }
+
+  if (conflicts.length > 0) {
+    throw new Error(`capability conflict in platform "${id}": ${conflicts.join('; ')}`);
+  }
+
+  return { hasConflict: false, conflicts: [] };
+}
+
+/**
+ * 从 installMethod 派生 automatable 标志。
+ *
+ * @param {object} platform - 平台描述符
+ * @returns {boolean}
+ */
+export function deriveAutomatable(platform) {
+  return platform.installMethod === 'structured-cli';
+}

package/src/producers/build-adapters.mjs

@@ -438,9 +438,16 @@ async function generateAdapterFiles(platform, skills, templateJson, root, market
   if (typeof adapted.skills === 'string') {
     adapted.skills = platform.name === 'workbuddy' ? ['./skills/'] : './skills/';
   } else if (Array.isArray(adapted.skills)) {
-    for (const skill of adapted.skills) {
+    // Handle both string array and object array forms
+    adapted.skills = adapted.skills.map((skill) => {
+      if (typeof skill === 'string') {
+        // String array: transform to relative path for the adapter
+        return platform.name === 'workbuddy' ? './skills/' : skill;
+      }
+      // Object array: preserve existing behavior
       skill.source = `../skills/${skill.name}/SKILL.md`;
-    }
+      return skill;
+    });
   }
 
   const pluginJsonContent = JSON.stringify(adapted, null, 2) + '\n';