create-yss-spec 3.4.10 → 3.5.0

package/src/commands/skills.js

@@ -0,0 +1,253 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { runInTransaction } = require("../filesystem/transaction-runner");
+const { applyManagedOperation } = require("../filesystem/apply-plan");
+const { pathKind, targetPath } = require("../filesystem/path-utils");
+const { assertTargetFamily } = require("../family-runtime");
+const { assertTargetWorkingTreeWritable } = require("../validation/security");
+const { readTemplateSnapshot, loadTemplateMetadata, writeTemplateMetadata, buildDesiredManagedOperations, BUNDLED_TEMPLATE_ROOT, fileHash } = require("../template/instance-runtime");
+const { RUNTIMES, assertRuntime, readDistributionRegistry, requiredSkills, renderInstanceDesignSkillFile } = require("../template/distribution-runtime");
+const { ASSET_PROFILE, STAGES } = require("../template/asset-runtime");
+const { refreshGeneratedProjectInstance, verifyGeneratedProjectInstance } = require("../template/verification-runtime");
+
+function parseSkillArgs(argv) {
+  const options = { names: [], triggers: [], targetDir: "." };
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    if (arg === "--plan") options.plan = true;
+    else if (arg === "--apply") options.apply = true;
+    else if (arg === "--target-dir" || arg === "--when") {
+      const value = argv[++index];
+      if (!value || value.startsWith("--")) throw new Error(`${arg} 需要一个值`);
+      if (arg === "--target-dir") options.targetDir = value;
+      else options.triggers.push(value);
+    } else if (arg.startsWith("--")) throw new Error(`不支持的参数：${arg}`);
+    else options.names.push(arg);
+  }
+  if (options.plan && options.apply) throw new Error("--plan 与 --apply 互斥");
+  if (!options.plan && !options.apply) throw new Error("skills 命令必须显式选择 --plan 或 --apply");
+  return options;
+}
+
+function listFiles(directory, prefix = "") {
+  const files = [];
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) files.push(...listFiles(path.join(directory, entry.name), relative));
+    else if (entry.isFile()) files.push(relative);
+  }
+  return files;
+}
+
+function addManagedTree(metadata, targetDir, relativeDir) {
+  for (const file of listFiles(targetPath(targetDir, relativeDir))) {
+    const relative = `${relativeDir}/${file}`;
+    metadata.managedFiles[relative] = { type: "copy", contentHash: fileHash(targetPath(targetDir, relative)) };
+  }
+}
+
+function context(targetDir) {
+  assertTargetFamily(targetDir);
+  const { metadata } = loadTemplateMetadata(targetDir);
+  if (metadata.metadataSchemaVersion !== 3 || metadata.distribution?.mode !== "selected") {
+    throw new Error("按需 Skill 命令仅适用于 v3 精简实例；v2 实例继续 legacy-all 分发");
+  }
+  const snapshot = readTemplateSnapshot();
+  if (metadata.templateCommit !== snapshot.templateCommit || metadata.snapshotHash !== snapshot.snapshotHash) {
+    throw new Error("CLI 快照与实例模板提交不一致，请先运行 create-yss-spec sync");
+  }
+  const lockPath = targetPath(targetDir, "skills-lock.json");
+  const lock = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+  if (JSON.stringify(lock.projectionRoots) !== JSON.stringify(metadata.distribution.runtimes.map((name) => RUNTIMES[name]))) {
+    throw new Error("实例 Skill 锁与元数据的平台选择不一致");
+  }
+  return { metadata, lock, lockPath };
+}
+
+function runAssetSelection({ targetDir, requestedSkills = [], triggers = [], stage = null, plan = false }) {
+  const { metadata, lock, lockPath } = context(targetDir);
+  const distribution = metadata.distribution;
+  if (distribution.assetProfile !== ASSET_PROFILE) {
+    throw new Error("阶段资产命令仅适用于新建的按阶段分发实例；旧实例保持原分发范围");
+  }
+  if (stage && !Object.hasOwn(STAGES, stage)) throw new Error(`未知生命周期阶段：${stage}`);
+  const stageSkills = stage ? STAGES[stage].skills : [];
+  const registry = readDistributionRegistry(BUNDLED_TEMPLATE_ROOT);
+  const requested = [...new Set([...requestedSkills, ...stageSkills])];
+  const addStage = stage && !distribution.installedStages.includes(stage) ? stage : null;
+  const variables = { ...metadata.variables };
+  const before = buildDesiredManagedOperations(targetDir, { ...variables, distribution }, "init");
+  for (const operation of before) {
+    if (metadata.managedFiles[operation.relativePath] && pathKind(operation.targetPath) === "missing") {
+      throw new Error(`实例受管资产缺失，请先运行 create-yss-spec sync：${operation.relativePath}`);
+    }
+  }
+  let names, missingSkills, nextDistribution, after;
+  for (let attempt = 0; attempt <= 50; attempt++) {
+    names = requiredSkills(registry.text, requested, triggers, BUNDLED_TEMPLATE_ROOT);
+    missingSkills = names.filter((name) => !distribution.installedSkills.includes(name));
+    nextDistribution = {
+      ...distribution,
+      installedSkills: [...distribution.installedSkills, ...missingSkills].sort(),
+      installedStages: addStage ? [...distribution.installedStages, addStage] : [...distribution.installedStages],
+      resourceSkills: [...new Set([...distribution.resourceSkills, ...missingSkills])].sort(),
+    };
+    try {
+      after = buildDesiredManagedOperations(targetDir, { ...variables, distribution: nextDistribution }, "init");
+      break;
+    } catch (error) {
+      if (!error.requiredSkill || requested.includes(error.requiredSkill) || attempt === 50) throw error;
+      requested.push(error.requiredSkill);
+    }
+  }
+  const beforePaths = new Set(before.map((operation) => operation.relativePath));
+  const newOperations = after.filter((operation) => !beforePaths.has(operation.relativePath) && operation.relativePath !== "skills-lock.json");
+  const paths = newOperations.map((operation) => operation.relativePath);
+  for (const relative of paths) {
+    if (pathKind(targetPath(targetDir, relative)) !== "missing") throw new Error(`目标阶段资产路径已存在，拒绝覆盖：${relative}`);
+  }
+  if (plan) {
+    console.log(JSON.stringify({ operation: stage ? "assets ensure" : "skills ensure", targetDir, requested: stage || requestedSkills,
+      dependencies: names, addSkills: missingSkills, addStage, paths }, null, 2));
+    return;
+  }
+  if (!addStage && !missingSkills.length && !paths.length) {
+    verifyGeneratedProjectInstance(targetDir);
+    console.log("阶段资产已满足，无需写入");
+    return;
+  }
+  assertTargetWorkingTreeWritable(targetDir, { packageRoot: path.resolve(__dirname, "../..") });
+  const sourceLock = JSON.parse(fs.readFileSync(path.join(BUNDLED_TEMPLATE_ROOT, "skills-lock.json"), "utf8"));
+  runInTransaction({
+    targetDir, operation: stage ? "assets" : "skills", affectedPaths: [...paths, "skills-lock.json", ".yss-template.json"],
+    execute(transaction) {
+      const nextMetadata = structuredClone(metadata);
+      const nextLock = structuredClone(lock);
+      for (const operation of newOperations) {
+        applyManagedOperation(operation, transaction);
+        nextMetadata.managedFiles[operation.relativePath] = { type: operation.type, contentHash: fileHash(operation.targetPath) };
+      }
+      for (const name of missingSkills) {
+        if (!sourceLock.skills.shared[name]) throw new Error(`CLI 快照缺少 Skill 锁记录：${name}`);
+        nextLock.skills.shared[name] = { ...sourceLock.skills.shared[name], targets: [".agents/skills", ...nextLock.projectionRoots] };
+      }
+      nextMetadata.distribution = nextDistribution;
+      transaction.writeFile(lockPath, `${JSON.stringify(nextLock, null, 2)}\n`);
+      refreshGeneratedProjectInstance(targetDir);
+      nextMetadata.managedFiles["skills-lock.json"] = { type: "render", contentHash: fileHash(lockPath) };
+      verifyGeneratedProjectInstance(targetDir);
+      writeTemplateMetadata(targetDir, nextMetadata, transaction);
+    },
+  });
+  console.log(stage ? `已安装阶段资产 ${stage}` : `已补装 ${missingSkills.join(", ")}`);
+}
+
+function runAssets(argv = []) {
+  const [command, stage, ...rest] = argv;
+  if (command !== "ensure" || !stage || stage.startsWith("--")) throw new Error("用法：assets ensure <stage-id> --plan|--apply");
+  const options = parseSkillArgs(rest);
+  if (options.names.length || options.triggers.length) throw new Error("assets ensure 只接受一个阶段 ID");
+  runAssetSelection({ targetDir: path.resolve(options.targetDir), stage, plan: Boolean(options.plan) });
+}
+
+function runSkills(argv = []) {
+  const [command, maybeAction, ...rest] = argv;
+  const runtimeAdd = command === "runtime" && maybeAction === "add";
+  if (command !== "ensure" && !runtimeAdd) throw new Error("用法：skills ensure <skill-id...> --plan|--apply，或 skills runtime add <runtime> --plan|--apply");
+  const options = parseSkillArgs(runtimeAdd ? rest : [maybeAction, ...rest].filter((value) => value !== undefined));
+  if (!options.names.length) throw new Error(runtimeAdd ? "runtime add 需要平台名" : "ensure 需要至少一个 Skill ID");
+  if (runtimeAdd && options.names.length !== 1) throw new Error("runtime add 一次只接受一个平台");
+  const targetDir = path.resolve(options.targetDir);
+  const { metadata, lock, lockPath } = context(targetDir);
+  const distribution = metadata.distribution;
+  if (!runtimeAdd && distribution.assetProfile === ASSET_PROFILE) {
+    runAssetSelection({ targetDir, requestedSkills: options.names, triggers: options.triggers, plan: Boolean(options.plan) });
+    return;
+  }
+  const registry = readDistributionRegistry(BUNDLED_TEMPLATE_ROOT);
+  const names = runtimeAdd ? [] : requiredSkills(registry.text, options.names, options.triggers, BUNDLED_TEMPLATE_ROOT);
+  const runtime = runtimeAdd ? assertRuntime(options.names[0]) : null;
+  const missing = names.filter((name) => !distribution.installedSkills.includes(name));
+  const addedRuntime = runtime && !distribution.runtimes.includes(runtime) ? runtime : null;
+  const roots = distribution.runtimes.map((name) => RUNTIMES[name]);
+  const runtimeFiles = addedRuntime ? buildDesiredManagedOperations(targetDir, {
+    ...metadata.variables,
+    distribution: { mode: "selected", runtimes: [...distribution.runtimes, addedRuntime], installedSkills: distribution.installedSkills },
+  }, "init").filter((operation) => {
+    const runtimeRoot = RUNTIMES[addedRuntime].split("/")[0];
+    return (operation.relativePath.startsWith(`${runtimeRoot}/`) || (addedRuntime === "cursor" && operation.relativePath === ".cursorrules")) &&
+      !distribution.installedSkills.some((name) => operation.relativePath.startsWith(`${RUNTIMES[addedRuntime]}/${name}/`));
+  }) : [];
+  const paths = ["skills-lock.json", ".yss-template.json"];
+  for (const name of missing) {
+    paths.push(`.agents/skills/${name}`, ...roots.map((root) => `${root}/${name}`));
+  }
+  if (addedRuntime) paths.push(...Object.keys(lock.skills.shared).map((name) => `${RUNTIMES[addedRuntime]}/${name}`), ...runtimeFiles.map((operation) => operation.relativePath));
+  for (const relative of paths.slice(2)) {
+    if (pathKind(targetPath(targetDir, relative)) !== "missing") throw new Error(`目标 Skill 路径已存在，拒绝覆盖：${relative}`);
+  }
+  if (options.plan) {
+    console.log(JSON.stringify({ operation: runtimeAdd ? "runtime add" : "ensure", targetDir, requested: options.names, dependencies: names, addSkills: missing, addRuntime: addedRuntime, paths }, null, 2));
+    return;
+  }
+  if (!missing.length && !addedRuntime) {
+    verifyGeneratedProjectInstance(targetDir);
+    console.log("Skill 分发已满足，无需写入");
+    return;
+  }
+  assertTargetWorkingTreeWritable(targetDir, { packageRoot: path.resolve(__dirname, "../..") });
+  const sourceLock = JSON.parse(fs.readFileSync(path.join(BUNDLED_TEMPLATE_ROOT, "skills-lock.json"), "utf8"));
+  runInTransaction({
+    targetDir, operation: "skills", affectedPaths: paths,
+    execute(transaction) {
+      const nextMetadata = structuredClone(metadata);
+      const nextLock = structuredClone(lock);
+      if (addedRuntime) {
+        nextMetadata.distribution.runtimes.push(addedRuntime);
+        nextLock.projectionRoots.push(RUNTIMES[addedRuntime]);
+      }
+      for (const name of missing) {
+        const source = path.join(BUNDLED_TEMPLATE_ROOT, ".agents/skills", name);
+        if (pathKind(source) !== "directory" || !sourceLock.skills.shared[name]) throw new Error(`CLI 快照缺少 Skill：${name}`);
+        transaction.copyFile(source, targetPath(targetDir, `.agents/skills/${name}`));
+        for (const root of roots) transaction.copyFile(source, targetPath(targetDir, `${root}/${name}`));
+        if (name === "yss-design-system") {
+          for (const root of [".agents/skills", ...roots]) {
+            for (const file of ["SKILL.md", "references/data-quality-theme.md"]) {
+              const target = targetPath(targetDir, `${root}/${name}/${file}`);
+              transaction.writeFile(target, renderInstanceDesignSkillFile(fs.readFileSync(target, "utf8")));
+            }
+          }
+        }
+        nextMetadata.distribution.installedSkills.push(name);
+        nextLock.skills.shared[name] = { ...sourceLock.skills.shared[name], targets: [".agents/skills", ...nextLock.projectionRoots] };
+        addManagedTree(nextMetadata, targetDir, `.agents/skills/${name}`);
+        for (const root of roots) addManagedTree(nextMetadata, targetDir, `${root}/${name}`);
+      }
+      if (addedRuntime) {
+        const root = RUNTIMES[addedRuntime];
+        for (const name of Object.keys(nextLock.skills.shared)) {
+          const source = targetPath(targetDir, `.agents/skills/${name}`);
+          transaction.copyFile(source, targetPath(targetDir, `${root}/${name}`));
+          if (nextMetadata.distribution.installedSkills.includes(name)) addManagedTree(nextMetadata, targetDir, `${root}/${name}`);
+        }
+        for (const operation of runtimeFiles) {
+          transaction.copyFile(operation.sourcePath, operation.targetPath);
+          nextMetadata.managedFiles[operation.relativePath] = { type: operation.type, contentHash: fileHash(operation.targetPath) };
+        }
+      }
+      for (const record of Object.values(nextLock.skills.shared)) record.targets = [".agents/skills", ...nextLock.projectionRoots];
+      nextMetadata.distribution.installedSkills.sort();
+      transaction.writeFile(lockPath, `${JSON.stringify(nextLock, null, 2)}\n`);
+      refreshGeneratedProjectInstance(targetDir);
+      nextMetadata.managedFiles["skills-lock.json"] = { type: "render", contentHash: fileHash(lockPath) };
+      verifyGeneratedProjectInstance(targetDir);
+      writeTemplateMetadata(targetDir, nextMetadata, transaction);
+    },
+  });
+  console.log(runtimeAdd ? `已增加平台 ${runtime}` : `已补装 ${missing.join(", ")}`);
+}
+
+module.exports = { runSkills, runAssets };

package/src/commands/sync.js

@@ -56,6 +56,9 @@ function printSyncDryRun(context) {
     syncPlan.updated,
     (operation) => `update: ${operation.relativePath}`,
   );
+  if ([...syncPlan.updated, ...syncPlan.added].some((operation) => operation.relativePath === "skills-lock.json")) {
+    console.log("提示：skills-lock.json 为生成文件；最终校验后内容一致时不会重新写入。");
+  }
   printLimitedOperations(
     syncPlan.added,
     (operation) => `add: ${operation.relativePath}`,

package/src/family-identity.js

@@ -283,7 +283,7 @@ function createFamilyGuard(_packageRoot, expectedName) {
         Object.hasOwn(value, "metadataSchemaVersion") &&
         (!Number.isInteger(value.metadataSchemaVersion) ||
           value.metadataSchemaVersion < 1 ||
-          value.metadataSchemaVersion > (expectedName === "create-yss-spec" ? 2 : 1))
+          value.metadataSchemaVersion > (expectedName === "create-yss-spec" ? 3 : 1))
       ) {
         throw new Error("身份 metadata schema 版本非法或不支持");
       }

package/src/template/asset-runtime.js

@@ -0,0 +1,220 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const ASSET_PROFILE = "stage-selective";
+const INITIAL_STAGES = ["stage.entry-triage", "stage.plan"];
+const TEMPLATE_ONLY_IMPORTS = new Set(["scripts/lib/maintenance-intensity.mjs"]);
+const RENDERED_SKILL_SCRIPTS = Object.freeze({ "yss-design-system": ["scripts/design-md"] });
+const SKILL_ASSET_PREFIXES = Object.freeze({ "yss-design-system": ["docs/design/tokens/"] });
+
+// Paths here are the entry points for each stage. Relative JavaScript imports
+// are included by moduleClosure; files named by an explicitly installed Skill
+// are included by skillReferences. The CLI snapshot retains every source file.
+const COMMON = {
+  files: [
+    "docs/agents/yss-skill-registry.yaml",
+    "docs/agents/digital-human-roles.yaml",
+    "docs/agents/digital-human-roles.md",
+    "docs/agents/issue-tracker.md",
+    "docs/agents/triage-labels.md",
+    "docs/agents/domain.md",
+    "docs/process/lifecycle-registry.yaml",
+    "docs/process/lifecycle-registry-baseline.json",
+    "docs/process/lifecycle-artifact-map.md",
+    "docs/process/harness-process-tailoring.md",
+    "docs/process/document-writing.md",
+    "docs/process/contract-reading.md",
+    "docs/process/stage-tracking.md",
+    "docs/process/schemas/context-reconciliation.schema.json",
+    "docs/process/schemas/digital-human-task-package.schema.json",
+    "docs/process/schemas/lifecycle-checkpoint.schema.json",
+    "docs/process/schemas/stage-tracking.schema.json",
+    "docs/process/schemas/user-decision.schema.json",
+    "docs/process/templates/context-reconciliation-template.yaml",
+    "docs/process/templates/lifecycle-checkpoint-template.yaml",
+    "docs/process/templates/stage-checkpoint-template.md",
+    "docs/process/templates/user-decision-template.yaml",
+    "docs/templates/local-parent-ticket-template.md",
+    "docs/templates/approval-record-template.yaml",
+    "docs/templates/review-report-template.md",
+    "docs/user-guide/用户手册.md",
+  ],
+  scripts: [
+    "scripts/verify-project-instance",
+    "scripts/sync-skills",
+    "scripts/update-skill-lock",
+    "scripts/verify-context-contract",
+    "scripts/verify-context-reconciliation",
+    "scripts/verify-digital-human-roles",
+    "scripts/verify-digital-human-task-package",
+    "scripts/verify-lifecycle-checkpoint",
+    "scripts/verify-user-decision",
+    "scripts/verify-approval-record",
+    "scripts/query-lifecycle-context",
+    "scripts/contract",
+    "scripts/stage-tracking",
+    "scripts/gitworks",
+  ],
+};
+
+const STAGES = Object.freeze({
+  "stage.entry-triage": { files: [], scripts: [], skills: [] },
+  "stage.plan": {
+    prefixes: ["docs/plan/"],
+    files: ["docs/process/plan-migration.md"],
+    scripts: ["scripts/verify-plan-spec-entry"],
+    skills: [],
+  },
+  "stage.spec-architecture": {
+    files: [
+      "docs/templates/spec-template.md",
+      "docs/templates/spec-delta-template.md",
+      "docs/architecture/templates/business-architecture-template.md",
+      "docs/architecture/templates/functional-architecture-template.md",
+    ],
+    scripts: [],
+    skills: [],
+  },
+  "stage.product-design": {
+    prefixes: ["docs/design/"],
+    files: [],
+    scripts: ["scripts/design-md"],
+    skills: ["yss-prototype-stage"],
+  },
+  "stage.system-data-engineering": {
+    prefixes: ["docs/engineering/"],
+    files: [
+      "docs/process/implementation-repo-integration.md",
+      "docs/process/existing-backend-architecture.md",
+      "docs/process/existing-ui-baseline.md",
+      "docs/process/frontend-backend-delivery.md",
+      "docs/templates/implementation-repo-registry-template.md",
+    ],
+    scripts: [
+      "scripts/backend-platforms",
+      "scripts/backend-delivery",
+      "scripts/repository-scope-policy",
+      "scripts/verify-scaffold-architecture-decisions",
+    ],
+    skills: ["yss-implementation-contract-compiler"],
+  },
+  "stage.ticket-formalization": {
+    files: ["docs/templates/vertical-slice-ticket-template.md", "docs/templates/cross-repo-slice-template.md"],
+    scripts: ["scripts/dispatch-slice-task", "scripts/slice-contract"],
+    skills: [],
+  },
+  "stage.vertical-slice-implementation": {
+    files: ["docs/templates/verification-record-template.md"],
+    scripts: ["scripts/implementation-path-policy", "scripts/complete-backend-delivery"],
+    skills: [],
+  },
+  "stage.verification-release-retrospective": {
+    files: [
+      "docs/process/delivery-preflight.md",
+      "docs/templates/release-note-template.md",
+      "docs/templates/retro-report-template.md",
+      "docs/templates/review-bundle-template.yaml",
+    ],
+    scripts: ["scripts/preflight-delivery"],
+    skills: [],
+  },
+});
+
+function sourceFile(root, ref) {
+  const file = path.join(root, ref);
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile()) throw new Error(`CLI 快照缺少阶段资产：${ref}`);
+  return file;
+}
+
+function addFile(root, result, ref) {
+  sourceFile(root, ref);
+  result.add(ref);
+}
+
+function addPrefix(root, result, prefix) {
+  const directory = path.join(root, prefix);
+  if (!fs.existsSync(directory) || !fs.statSync(directory).isDirectory()) throw new Error(`CLI 快照缺少阶段目录：${prefix}`);
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    const ref = `${prefix}${entry.name}`;
+    if (entry.isDirectory()) addPrefix(root, result, `${ref}/`);
+    else if (entry.isFile()) result.add(ref);
+  }
+}
+
+function moduleClosure(root, result, ref, selectedSkills) {
+  if (result.has(ref)) return;
+  const source = fs.readFileSync(sourceFile(root, ref), "utf8");
+  result.add(ref);
+  const expressions = [
+    /\b(?:import|export)\s+(?:[^'"\n]*?\s+from\s*)?['"]([^'"]+)['"]/g,
+    /\b(?:require|import)\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+  ];
+  for (const expression of expressions) {
+    for (const match of source.matchAll(expression)) {
+      if (!match[1].startsWith(".")) continue;
+      const resolved = path.posix.normalize(path.posix.join(path.posix.dirname(ref), match[1]));
+      const candidate = [resolved, `${resolved}.mjs`, `${resolved}.js`].find((name) => fs.existsSync(path.join(root, name)));
+      if (!candidate && TEMPLATE_ONLY_IMPORTS.has(resolved)) continue;
+      if (candidate?.startsWith(".agents/skills/")) {
+        const skill = candidate.split("/")[2];
+        if (!selectedSkills.has(skill)) {
+          const error = new Error(`阶段脚本依赖未安装 Skill：${ref} -> ${skill}`);
+          error.requiredSkill = skill;
+          throw error;
+        }
+        continue;
+      }
+      if (!candidate || !candidate.startsWith("scripts/")) throw new Error(`阶段脚本依赖未分发：${ref} -> ${match[1]}`);
+      moduleClosure(root, result, candidate, selectedSkills);
+    }
+  }
+}
+
+function skillReferences(root, result, skillId, selectedSkills) {
+  const skillRoot = path.join(root, ".agents/skills", skillId);
+  if (!fs.existsSync(skillRoot)) throw new Error(`CLI 快照缺少 Skill：${skillId}`);
+  function visit(directory) {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const file = path.join(directory, entry.name);
+      if (entry.isDirectory()) visit(file);
+      else if (entry.isFile() && /\.(?:md|yaml|json)$/.test(entry.name)) {
+        const source = fs.readFileSync(file, "utf8");
+        for (const match of source.matchAll(/(?:docs|scripts)\/[\p{L}\p{N}_.\/-]+/gu)) {
+          const ref = match[0].replace(/[.,;]+$/, "");
+          if (!fs.existsSync(path.join(root, ref)) || !fs.statSync(path.join(root, ref)).isFile()) continue;
+          if (ref.startsWith("scripts/")) moduleClosure(root, result, ref, selectedSkills);
+          else addFile(root, result, ref);
+        }
+      }
+    }
+  }
+  visit(skillRoot);
+  for (const prefix of SKILL_ASSET_PREFIXES[skillId] || []) addPrefix(root, result, prefix);
+  for (const ref of RENDERED_SKILL_SCRIPTS[skillId] || []) moduleClosure(root, result, ref, selectedSkills);
+}
+
+function assetPaths(root, distribution) {
+  if (distribution.mode !== "selected" || distribution.assetProfile !== ASSET_PROFILE) return null;
+  const lifecycle = fs.readFileSync(sourceFile(root, "docs/process/lifecycle-registry.yaml"), "utf8");
+  const stageIds = [...lifecycle.matchAll(/^  - id: (stage\.[a-z0-9-]+)\s*$/gm)].map((match) => match[1]).sort();
+  if (JSON.stringify(stageIds) !== JSON.stringify(Object.keys(STAGES).sort())) {
+    throw new Error("CLI 阶段资产映射与生命周期注册表阶段 ID 不一致");
+  }
+  const result = new Set();
+  const selectedSkills = new Set(distribution.installedSkills);
+  for (const ref of COMMON.files) addFile(root, result, ref);
+  for (const ref of COMMON.scripts) moduleClosure(root, result, ref, selectedSkills);
+  for (const stage of distribution.installedStages) {
+    const bundle = STAGES[stage];
+    if (!bundle) throw new Error(`未知生命周期阶段：${stage}`);
+    for (const prefix of bundle.prefixes || []) addPrefix(root, result, prefix);
+    for (const ref of bundle.files || []) addFile(root, result, ref);
+    for (const ref of bundle.scripts || []) moduleClosure(root, result, ref, selectedSkills);
+  }
+  for (const skill of distribution.resourceSkills || []) skillReferences(root, result, skill, selectedSkills);
+  return result;
+}
+
+module.exports = { ASSET_PROFILE, INITIAL_STAGES, STAGES, assetPaths };

package/src/template/distribution-runtime.js

@@ -0,0 +1,165 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { ASSET_PROFILE, INITIAL_STAGES } = require("./asset-runtime");
+
+const RUNTIMES = Object.freeze({ codex: ".codex/skills", cursor: ".cursor/skills", pi: ".pi/skills" });
+const OMIT_INSTANCE_PATHS = [
+  "docs/process/github-workflows.md",
+  "docs/process/harness-executive-blueprint.md",
+  "docs/process/PDCA-SCRUM.md",
+  "docs/design/preview.html", "docs/design/preview.css", "docs/design/preview.js", "docs/design/preview-dark.html",
+  "docs/design/facts/antdv-next", "docs/user-guide/设备借用贯穿案例.md",
+  "docs/design/design-system-sync.yaml",
+];
+
+function readDistributionRegistry(templateRoot) {
+  const registry = fs.readFileSync(path.join(templateRoot, "docs/agents/yss-skill-registry.yaml"), "utf8");
+  const match = registry.match(/^instance_distribution:\n([\s\S]*?)(?=^[^\s#][^\n]*:\s*$)/m);
+  if (!match) throw new Error("Skill 注册表缺少 instance_distribution");
+  const initial = match[1].match(/^  initial_skills: \[([^\]]+)\]/m);
+  if (!initial) throw new Error("Skill 注册表缺少 initial_skills");
+  return {
+    initialSkills: initial[1].split(",").map((item) => item.trim()),
+    text: registry,
+  };
+}
+
+function assertRuntime(runtime) {
+  if (!Object.hasOwn(RUNTIMES, runtime)) throw new Error(`--agent-runtime 必须是 ${Object.keys(RUNTIMES).join("| ")}`);
+  return runtime;
+}
+
+function distributionForVariables(variables, templateRoot) {
+  if (variables.distribution?.mode === "legacy-all") return { mode: "legacy-all" };
+  if (variables.distribution?.mode === "selected") return variables.distribution;
+  const runtime = assertRuntime(variables.agentRuntime);
+  return {
+    mode: "selected",
+    runtimes: [runtime],
+    installedSkills: [...readDistributionRegistry(templateRoot).initialSkills],
+    assetProfile: ASSET_PROFILE,
+    installedStages: [...INITIAL_STAGES],
+    resourceSkills: [],
+  };
+}
+
+function isIncludedInstancePath(relativePath, distribution) {
+  if (distribution.mode === "legacy-all") return true;
+  if (relativePath === ".cursorrules" && !distribution.runtimes.includes("cursor")) return false;
+  if (OMIT_INSTANCE_PATHS.some((excluded) => relativePath === excluded || relativePath.startsWith(`${excluded}/`))) return false;
+  if (distribution.assetProfile === ASSET_PROFILE &&
+      (relativePath.startsWith("docs/") || relativePath.startsWith("scripts/") || relativePath.startsWith(".vscode/"))) {
+    return distribution.assetPaths.has(relativePath) ||
+      [...distribution.assetPaths].some((ref) => ref.startsWith(`${relativePath}/`));
+  }
+  for (const [runtime, root] of Object.entries(RUNTIMES)) {
+    const runtimeRoot = root.split("/")[0];
+    if (relativePath === runtimeRoot || relativePath.startsWith(`${runtimeRoot}/`)) {
+      if (!distribution.runtimes.includes(runtime)) return false;
+      if (relativePath.startsWith(`${root}/`)) {
+        const name = relativePath.slice(root.length + 1).split("/")[0];
+        if (name && !name.startsWith(".") && !distribution.installedSkills.includes(name)) return false;
+      }
+    }
+  }
+  if (relativePath.startsWith(".agents/skills/")) {
+    const name = relativePath.slice(".agents/skills/".length).split("/")[0];
+    if (name && !name.startsWith(".") && !distribution.installedSkills.includes(name)) return false;
+  }
+  return true;
+}
+
+function selectedSkillLock(sourceText, distribution) {
+  if (distribution.mode === "legacy-all") return sourceText;
+  const source = JSON.parse(sourceText);
+  const roots = distribution.runtimes.map((runtime) => RUNTIMES[assertRuntime(runtime)]);
+  source.projectionRoots = roots;
+  source.skills.shared = Object.fromEntries(Object.entries(source.skills.shared).filter(([name]) => distribution.installedSkills.includes(name)).map(([name, record]) => [name, { ...record, targets: [".agents/skills", ...roots] }]));
+  source.skills.platform = Object.fromEntries(roots.map((root) => [root, Object.fromEntries(Object.entries(source.skills.platform?.[root] || {}).filter(([name]) => distribution.installedSkills.includes(name)))]).filter(([, entries]) => Object.keys(entries).length));
+  return `${JSON.stringify(source, null, 2)}\n`;
+}
+
+function renderInstanceSkillSupplyChain(sourceText) {
+  const additions = `\nfunction projectionRootsFor(lock) {
+  const identityPath = path.join(ROOT, "yss-project.yaml");
+  const isInstance = existsSync(identityPath) && /^repository_mode:\\s*project-instance\\s*$/m.test(readFileSync(identityPath, "utf8"));
+  if (!isInstance) return PROJECTION_ROOTS;
+  const roots = lock?.projectionRoots;
+  if (!Array.isArray(roots) || !roots.length || roots.some((root) => !PROJECTION_ROOTS.includes(root))) throw new TypeError("project-instance skills-lock.json 缺少有效 projectionRoots");
+  return [...new Set(roots)];
+}\n`;
+  const marker = 'export const PROJECTION_ROOTS = [".codex/skills", ".cursor/skills", ".pi/skills"];';
+  if (!sourceText.includes(marker)) throw new Error("Skill 投影脚本分发基线已变化");
+  return sourceText.replace(marker, marker + additions)
+    .replace("  const shared = sharedFromLock(lock);", "  const shared = sharedFromLock(lock);\n  const projectionRoots = projectionRootsFor(lock);")
+    .replace("  const oldLock = parseLock(); const previous = priorMetadata(oldLock);", "  const oldLock = parseLock(); const projectionRoots = projectionRootsFor(oldLock); const previous = priorMetadata(oldLock);")
+    .replaceAll("for (const root of PROJECTION_ROOTS) {", "for (const root of projectionRoots) {")
+    .replace("const targets = [\".agents/skills\", ...PROJECTION_ROOTS];", "const targets = [\".agents/skills\", ...projectionRoots];")
+    .replace("projectionRoots: PROJECTION_ROOTS, sources, skills", "projectionRoots, sources, skills");
+}
+
+function renderInstanceDesignSkillFile(sourceText) {
+  return sourceText
+    .replaceAll("node .template-source/tooling/node/scripts/design-md.mjs", "scripts/design-md")
+    .replace("运行前先更新 `docs/design/design-system-sync.yaml` 的规范源摘要。", "项目实例无需模板间的 design-system-sync 摘要。")
+    .replace("修改根 DESIGN.md → 更新 design-system-sync.yaml 摘要 →", "修改根 DESIGN.md →");
+}
+
+function linkedSkillDependencies(templateRoot, name) {
+  const skillRoot = path.join(templateRoot, ".agents/skills");
+  const current = path.join(skillRoot, name);
+  const result = new Set();
+  function visitDir(directory) {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const file = path.join(directory, entry.name);
+      if (entry.isDirectory()) visitDir(file);
+      else if (entry.isFile() && entry.name.endsWith(".md")) {
+        const content = fs.readFileSync(file, "utf8");
+        for (const match of content.matchAll(/\[[^\]]+\]\(([^)]+)\)/g)) {
+          const ref = match[1].split("#")[0];
+          if (!ref || ref.startsWith("/") || ref.includes("://")) continue;
+          const resolved = path.resolve(path.dirname(file), ref);
+          const relative = path.relative(skillRoot, resolved).split(path.sep);
+          if (relative.length > 1 && relative[0] !== name && !relative[0].startsWith(".") && !relative[0].includes("..") && fs.existsSync(resolved)) result.add(relative[0]);
+        }
+      }
+    }
+  }
+  visitDir(current);
+  return [...result];
+}
+
+function requiredSkills(registryText, requested, triggers = [], templateRoot = null) {
+  const skillBlock = registryText.split(/^skills:\s*$/m)[1]?.split(/^platform_skills:\s*$/m)[0] || "";
+  const available = new Set([...skillBlock.matchAll(/^  - (?:\{ )?id: ([a-z][a-z0-9-]+)/gm)].map((match) => match[1]));
+  const platformBlock = registryText.split(/^platform_skills:\s*$/m)[1]?.split(/^external_skills:\s*$/m)[0] || "";
+  const platformSkills = new Set([...platformBlock.matchAll(/^  - id: ([a-z][a-z0-9-]+)/gm)].map((match) => match[1]));
+  const block = registryText.split(/^skill_dependencies:\s*$/m)[1]?.split(/^[^\s#][^\n]*:\s*$/m)[0] || "";
+  const dependencies = new Map();
+  let current = null;
+  for (const line of block.split("\n")) {
+    const header = line.match(/^  ([a-z][a-z0-9-]+):\s*$/);
+    if (header) { current = header[1]; continue; }
+    const item = line.match(/^    - \{ skill: ([a-z][a-z0-9-]+), type: ([a-z-]+)(?:, when: ([a-z0-9-]+))? \}/);
+    if (current && item) {
+      if (!dependencies.has(current)) dependencies.set(current, []);
+      dependencies.get(current).push({ name: item[1], type: item[2], when: item[3] });
+    }
+  }
+  const result = new Set();
+  function visit(name) {
+    if (!available.has(name)) throw new Error(platformSkills.has(name) ? `平台专属 Skill 不可作为共享 Skill 补装：${name}` : `Skill 未在注册表登记：${name}`);
+    if (result.has(name)) return;
+    result.add(name);
+    for (const dep of dependencies.get(name) || []) {
+      if (dep.type === "context-required" || (dep.type === "context-conditional" && triggers.includes(dep.when))) visit(dep.name);
+    }
+    if (templateRoot) for (const linked of linkedSkillDependencies(templateRoot, name)) visit(linked);
+  }
+  requested.forEach(visit);
+  return [...result].sort();
+}
+
+module.exports = { RUNTIMES, assertRuntime, readDistributionRegistry, distributionForVariables, isIncludedInstancePath, selectedSkillLock, renderInstanceSkillSupplyChain, renderInstanceDesignSkillFile, requiredSkills };