create-yss-spec 2.1.15 → 2.2.1

package/README.md

@@ -44,8 +44,10 @@ npx create-yss-spec@latest --version
 - 接管 / 升级时迁移 Spec / Ticket 路径并删除 `to-prd`、`to-issues` 旧 skill
 - 旧、新资产内容冲突或清单 schema / mode 非法时 fail closed
 - 保留模板的共享 skill 投影；生成实例可在尚未 `git init` 时运行模板校验
+- init / sync 不把模板源治理笔记、wiki、审查证据、源仓 CI / Cloud 环境和公开发布清单写入项目实例；attach 会带上 `yss-public-skills.json` 供 `verify-template` 使用
+- 空 gitlink / detached HEAD / git-submodule 挂载点 fail closed，`--force` 也不能覆盖
 
-本次模板适配按 `2.1.15` 发布。`templateCommit` 会写入实例 metadata；“最新模板”指用户执行的 `npx create-yss-spec@latest` 所携带的最新已发布快照，CLI 运行时不会拉取模板仓库。
+本次模板适配按 `2.2.1` 发布，绑定 `yss-spec-project-template@2375746`。`templateCommit` 会写入实例 metadata；“最新模板”指用户执行的 `npx create-yss-spec@latest` 所携带的最新已发布快照，CLI 运行时不会拉取模板仓库。实例会带上 YSS 前端技能叠加层（如 `ytable-usage`、`formily-foundation`、`yss-page-module-development`）、`.cursorrules` 与 `.agents/rules/yss-ai-skills.md`；审查临时目录 `docs/.scratch/` 与已退役的 `high-fidelity-html-prototype` 等独立入口不进入快照。
 
 ## 接管已有项目
 
@@ -72,6 +74,7 @@ npx create-yss-spec@latest attach \
 - 根规则文件等受管冲突默认阻断；`--force` 才覆盖，并把被覆盖文件备份到目标目录外的临时目录。
 - 合法 `template-source` 身份会转换为 `project-instance`；非法身份、迁移冲突和无法判断归属的扁平 Ticket 始终阻断。
 - Git worktree 有脏改动时只提醒，不自动 stash 或提交。
+- `.gitmodules`、gitlink 和 `apps/` 挂载工作树是用户资产；空 gitlink / detached HEAD 即使 `--force` 也阻断。
 
 ## 同步已有模板实例仓库
 
@@ -96,7 +99,8 @@ npx create-yss-spec@latest sync --dry-run
 - 对模板已删除文件只报告，不自动删除
 - 对已知的 Spec / Ticket 旧路径执行一次性迁移
 - 迁移目标已存在且内容不一致时停止，不静默覆盖
-- 同步结束会重新执行 `scripts/sync-skills --check`、`scripts/update-skill-lock --check` 和 `scripts/verify-template`；门禁失败会回滚文件和 metadata
+- `.gitmodules`、gitlink（mode `160000`）和 `apps/` 下已挂载实现仓是用户资产，不创建、不覆盖、不删除
+- init / sync 保持瘦实例：不复制 `scripts/`、`wiki/`、`.github/`、`.nvmrc`、`.gitignore`、`.template-source/`；attach 结束后会执行 `scripts/sync-skills --check`、`scripts/update-skill-lock --check` 和 `scripts/verify-template`，门禁失败会回滚文件和 metadata
 
 ```bash
 npx create-yss-spec@latest sync --target-dir . --dry-run

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-yss-spec",
-  "version": "2.1.15",
+  "version": "2.2.1",
   "description": "Initialize a YSS spec project template repository",
   "repository": {
     "type": "git",

package/src/cli.js

@@ -39,11 +39,21 @@ const AGENT_SKILL_ROOTS = [
   ".agents/skills",
   ".claude/skills",
   ".codex/skills",
+  ".cursor/skills",
   ".hermes/skills",
   ".pi/skills",
   ".qoder/skills",
   ".trae/skills",
 ];
+const GITLINK_MODE = "160000";
+const UNMANAGED_USER_PATHS = new Set([".gitmodules"]);
+const INSTANCE_FORBIDDEN_PATHS = [
+  ".template-source",
+  ".github",
+  ".cursor/environment.json",
+  "wiki",
+  "docs/reviews",
+];
 const LEGACY_SKILL_MAPPINGS = [
   ["to-prd", "to-spec"],
   ["to-issues", "to-tickets"],
@@ -301,6 +311,235 @@ function isInsideTemplateRoot(targetDir) {
   );
 }
 
+function posixRelative(from, to) {
+  return path.relative(from, to).split(path.sep).join("/");
+}
+
+function collectGitRoots(start) {
+  const roots = [];
+  if (!start) {
+    return roots;
+  }
+  let current = path.resolve(start);
+  while (true) {
+    if (
+      fs.existsSync(path.join(current, ".git")) ||
+      fs.existsSync(path.join(current, ".gitmodules"))
+    ) {
+      roots.push(current);
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+  return roots;
+}
+
+function parseGitmodules(content) {
+  const modules = [];
+  if (typeof content !== "string" || content.length === 0) {
+    return modules;
+  }
+  let current = null;
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    const name = line.match(/^\[submodule "(.+)"\]$/);
+    if (name) {
+      current = { name: name[1], path: "", url: "" };
+      modules.push(current);
+      continue;
+    }
+    if (!current) {
+      continue;
+    }
+    const pathMatch = line.match(/^path\s*=\s*(.+)$/);
+    if (pathMatch) {
+      current.path = pathMatch[1].trim().replace(/\\/g, "/").replace(/\/+$/, "");
+    }
+    const urlMatch = line.match(/^url\s*=\s*(.+)$/);
+    if (urlMatch) {
+      current.url = urlMatch[1].trim();
+    }
+  }
+  return modules;
+}
+
+function readGitmodules(repoRoot) {
+  const file = path.join(repoRoot, ".gitmodules");
+  if (!fs.existsSync(file) || pathKind(file) !== "file") {
+    return [];
+  }
+  return parseGitmodules(fs.readFileSync(file, "utf8"));
+}
+
+function gitLsFilesStage(repoRoot, relativePath) {
+  const result = spawnSync(
+    "git",
+    ["-C", repoRoot, "ls-files", "--stage", "--", relativePath],
+    { encoding: "utf8" },
+  );
+  if (result.status !== 0) {
+    return null;
+  }
+  const line = (result.stdout || "").trim().split(/\r?\n/).filter(Boolean)[0];
+  if (!line) {
+    return null;
+  }
+  const match = line.match(/^(\d+)\s+([0-9a-f]+)\s+(\d+)\s+(.+)$/i);
+  if (!match) {
+    return null;
+  }
+  return { mode: match[1], sha: match[2], stage: match[3], path: match[4] };
+}
+
+function gitShowSuperproject(cwd) {
+  const result = spawnSync(
+    "git",
+    ["-C", cwd, "rev-parse", "--show-superproject-working-tree"],
+    { encoding: "utf8" },
+  );
+  if (result.status !== 0) {
+    return "";
+  }
+  return (result.stdout || "").trim();
+}
+
+function gitAbbrevRef(cwd) {
+  const result = spawnSync(
+    "git",
+    ["-C", cwd, "rev-parse", "--abbrev-ref", "HEAD"],
+    { encoding: "utf8" },
+  );
+  if (result.status !== 0) {
+    return null;
+  }
+  return (result.stdout || "").trim();
+}
+
+function isEmptyDir(dir) {
+  if (!fs.existsSync(dir)) {
+    return true;
+  }
+  try {
+    return fs.readdirSync(dir).filter((name) => name !== "." && name !== "..")
+      .length === 0;
+  } catch {
+    return false;
+  }
+}
+
+function isGitSubmoduleMount(repoRoot, targetPathValue) {
+  const relative = posixRelative(repoRoot, path.resolve(targetPathValue));
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+    return false;
+  }
+  if (readGitmodules(repoRoot).some((item) => item.path === relative)) {
+    return true;
+  }
+  const staged = gitLsFilesStage(repoRoot, relative);
+  return staged?.mode === GITLINK_MODE;
+}
+
+function inspectCheckoutState(repoRoot, targetPathValue) {
+  const resolved = path.resolve(targetPathValue);
+  const relative = posixRelative(path.resolve(repoRoot), resolved);
+  const inRepo = Boolean(relative) && !relative.startsWith("..");
+  const staged = inRepo ? gitLsFilesStage(repoRoot, relative) : null;
+  const listed = inRepo
+    ? readGitmodules(repoRoot).some((item) => item.path === relative)
+    : false;
+  const superproject = fs.existsSync(path.join(resolved, ".git"))
+    ? gitShowSuperproject(resolved)
+    : "";
+  const isMount = staged?.mode === GITLINK_MODE || listed || Boolean(superproject);
+  const hasGit = fs.existsSync(path.join(resolved, ".git"));
+  if (isMount && !hasGit) {
+    return isEmptyDir(resolved) ? "empty-gitlink" : "uninitialized";
+  }
+  if (isMount && hasGit) {
+    const ref = gitAbbrevRef(resolved);
+    if (ref === "HEAD") {
+      return "detached-head";
+    }
+    return "attached-branch";
+  }
+  return null;
+}
+
+function gitlinkWriteViolation(targetDir, { force = false } = {}) {
+  const resolved = path.resolve(targetDir);
+  const roots = collectGitRoots(resolved);
+  for (const root of roots) {
+    if (path.resolve(root) === PACKAGE_ROOT) {
+      continue;
+    }
+    let current = resolved;
+    while (true) {
+      if (isGitSubmoduleMount(root, current)) {
+        const checkout = inspectCheckoutState(root, current);
+        if (checkout === "empty-gitlink" || checkout === "uninitialized") {
+          return "空 gitlink 不得当成普通目录写入；gitlink 不得由 CLI 覆盖";
+        }
+        if (checkout === "detached-head") {
+          return "detached HEAD 不得当成普通目录写入；gitlink 不得由 CLI 覆盖";
+        }
+        if (path.resolve(current) === resolved) {
+          return force
+            ? "--force 不得把 git-submodule 挂载点当成普通目录覆盖"
+            : "git-submodule gitlink 不得由 CLI 覆盖；先 git submodule update --init，在子仓附加分支的工作树内操作，或改用独立目录";
+        }
+      }
+      if (path.resolve(current) === path.resolve(root)) {
+        break;
+      }
+      const parent = path.dirname(current);
+      if (parent === current) {
+        break;
+      }
+      current = parent;
+    }
+  }
+  return null;
+}
+
+function assertTargetWorkingTreeWritable(targetDir, { force = false } = {}) {
+  const violation = gitlinkWriteViolation(targetDir, { force });
+  if (violation) {
+    throw new Error(violation);
+  }
+}
+
+function unmanagedPathReason(targetDir, relativePath) {
+  const normalized = normalizeRelativePath(relativePath);
+  if (UNMANAGED_USER_PATHS.has(normalized) || normalized.split("/")[0] === ".gitmodules") {
+    return ".gitmodules 是用户资产，不属于受管模板文件";
+  }
+  const absolutePath = path.resolve(targetDir, normalized);
+  const roots = collectGitRoots(targetDir);
+  for (const root of roots) {
+    if (path.resolve(root) === PACKAGE_ROOT) {
+      continue;
+    }
+    let current = absolutePath;
+    while (true) {
+      if (isGitSubmoduleMount(root, current)) {
+        return "gitlink / apps 挂载工作树是用户资产，不属于受管模板文件";
+      }
+      if (path.resolve(current) === path.resolve(root)) {
+        break;
+      }
+      const parent = path.dirname(current);
+      if (parent === current) {
+        break;
+      }
+      current = parent;
+    }
+  }
+  return null;
+}
+
 function normalizeRelativePath(relativePath) {
   return relativePath.split(path.sep).join("/");
 }
@@ -861,6 +1100,14 @@ function classifyAttachPlan(targetDir, variables) {
   };
 
   for (const operation of desiredOperations) {
+    const unmanagedReason = unmanagedPathReason(targetDir, operation.relativePath);
+    if (unmanagedReason) {
+      plan.unsafe.push({
+        ...operation,
+        reason: unmanagedReason,
+      });
+      continue;
+    }
     const kind = pathKind(operation.targetPath);
     if (kind === "missing") {
       plan.missing.push(operation);
@@ -904,6 +1151,14 @@ function classifySyncPlan(targetDir, metadata, identity = readTargetIdentity(tar
   const unsafe = [];
 
   for (const operation of desiredOperations) {
+    const unmanagedReason = unmanagedPathReason(targetDir, operation.relativePath);
+    if (unmanagedReason) {
+      unsafe.push({
+        ...operation,
+        reason: unmanagedReason,
+      });
+      continue;
+    }
     const existingRecord = managedFiles[operation.relativePath];
     const existingKind = pathKind(operation.targetPath);
 
@@ -1028,6 +1283,8 @@ function inspectTargetDir(targetDir, force) {
     throw new Error("目标目录不能位于模板源仓库内部");
   }
 
+  assertTargetWorkingTreeWritable(targetDir, { force });
+
   if (!fs.existsSync(targetDir)) {
     return { exists: false, clearEntries: false };
   }
@@ -1044,13 +1301,14 @@ function inspectTargetDir(targetDir, force) {
   return { exists: true, clearEntries: entries.length > 0 && force };
 }
 
-function inspectExistingTargetDir(targetDir) {
+function inspectExistingTargetDir(targetDir, { force = false } = {}) {
   if (isInsideTemplateRoot(targetDir)) {
     throw new Error("目标目录不能位于模板源仓库内部");
   }
   if (!fs.existsSync(targetDir) || pathKind(targetDir) !== "directory") {
     throw new Error("attach 目标目录必须是已经存在的项目目录");
   }
+  assertTargetWorkingTreeWritable(targetDir, { force });
 }
 
 function prepareTargetDir(targetDir, targetState) {
@@ -1130,8 +1388,8 @@ function runTemplateVerification(targetDir, scriptPath) {
 }
 
 function verifyGeneratedTemplate(targetDir, mode = "managed") {
-  if (mode === "init") {
-    verifyGeneratedInstance(targetDir);
+  if (mode === "init" || mode === "sync") {
+    verifyGeneratedInstance(targetDir, { checkForbiddenPaths: mode === "init" });
     return;
   }
 
@@ -1144,15 +1402,18 @@ function verifyGeneratedTemplate(targetDir, mode = "managed") {
   }
 }
 
-function verifyGeneratedInstance(targetDir) {
-  const forbiddenPaths = [
-    ...[...INIT_EXCLUDED_ROOT_ENTRIES],
-    ...[...INIT_EXCLUDED_ROOT_FILES],
-    ...[...INIT_EXCLUDED_RELATIVE_PATHS],
-  ];
-  for (const relativePath of forbiddenPaths) {
-    if (pathKind(targetPath(targetDir, relativePath)) !== "missing") {
-      throw new Error(`初始化结果包含禁止分发的模板源资产：${relativePath}`);
+function verifyGeneratedInstance(targetDir, { checkForbiddenPaths = true } = {}) {
+  if (checkForbiddenPaths) {
+    const forbiddenPaths = [
+      ...INSTANCE_FORBIDDEN_PATHS,
+      ...[...INIT_EXCLUDED_ROOT_ENTRIES],
+      ...[...INIT_EXCLUDED_ROOT_FILES],
+      ...[...INIT_EXCLUDED_RELATIVE_PATHS],
+    ];
+    for (const relativePath of [...new Set(forbiddenPaths)]) {
+      if (pathKind(targetPath(targetDir, relativePath)) !== "missing") {
+        throw new Error(`初始化结果包含禁止分发的模板源资产：${relativePath}`);
+      }
     }
   }
 
@@ -1614,7 +1875,7 @@ function runAttach(argv = []) {
 
   readTemplateSnapshot();
   const targetDir = normalizeTargetDir(options.targetDir);
-  inspectExistingTargetDir(targetDir);
+  inspectExistingTargetDir(targetDir, { force: Boolean(options.force) });
   if (pathKind(targetPath(targetDir, TEMPLATE_METADATA_FILENAME)) !== "missing") {
     throw new Error("当前项目已有模板元数据，请使用 sync，不要重复 attach");
   }
@@ -1710,7 +1971,7 @@ function runSync(argv = []) {
   }
   readTemplateSnapshot();
   const targetDir = normalizeTargetDir(options.targetDir || ".");
-  inspectExistingTargetDir(targetDir);
+  inspectExistingTargetDir(targetDir, { force: Boolean(options.force) });
   const { metadata } = loadTemplateMetadata(targetDir);
   const identity = readTargetIdentity(targetDir);
   const syncPlan = classifySyncPlan(targetDir, metadata, identity);
@@ -1754,7 +2015,7 @@ function runSync(argv = []) {
       applyManagedOperation(operation, transaction);
     }
     applyMigrationPlan(migrationPlan, transaction);
-    verifyGeneratedTemplate(targetDir, "init");
+    verifyGeneratedTemplate(targetDir, "sync");
     writeTemplateMetadata(
       targetDir,
       buildNextSyncMetadata(metadata, syncPlan, targetDir),

package/template/.agents/rules/yss-ai-skills.md

@@ -0,0 +1,59 @@
+---
+trigger: always_on
+---
+
+# YSS AI Skills Entry
+
+本项目使用 YSS UI 业务页面开发规范。处理 Vue3 业务页面、CRUD、列表、表单、抽屉、YTable、YEditTable、YFormily、YTree、API 对接任务时，必须先读取匹配的 SKILL.md，再写计划或代码。
+
+## Available Skills
+
+- yss-page-module-development: .agents/skills/yss-page-module-development/SKILL.md
+- theme-token-usage: .agents/skills/theme-token-usage/SKILL.md
+- component-selection-imports: .agents/skills/component-selection-imports/SKILL.md
+- page-skeleton: .agents/skills/page-skeleton/SKILL.md
+- page-list-module: .agents/skills/page-list-module/SKILL.md
+- page-form-module: .agents/skills/page-form-module/SKILL.md
+- ytable-usage: .agents/skills/ytable-usage/SKILL.md
+- yedit-table-usage: .agents/skills/yedit-table-usage/SKILL.md
+- ytree-usage: .agents/skills/ytree-usage/SKILL.md
+- prototype-page-acceptance: .agents/skills/prototype-page-acceptance/SKILL.md
+- yss-api-integration: .agents/skills/yss-api-integration/SKILL.md
+- file-export-download: .agents/skills/file-export-download/SKILL.md
+- vue3-best-practices: .agents/skills/vue3-best-practices/SKILL.md
+- frontend-commit: .agents/skills/frontend-commit/SKILL.md
+- java-backend-commit: .agents/skills/java-backend-commit/SKILL.md
+- yss-use-table-height: .agents/skills/yss-use-table-height/SKILL.md
+- yss-use-tree-height: .agents/skills/yss-use-tree-height/SKILL.md
+- yss-formily: .agents/skills/yss-formily/SKILL.md
+- formily-foundation: .agents/skills/formily-foundation/SKILL.md
+- formily-linkage-effects: .agents/skills/formily-linkage-effects/SKILL.md
+- formily-mode-slot-detail: .agents/skills/formily-mode-slot-detail/SKILL.md
+- formily-step-flow: .agents/skills/formily-step-flow/SKILL.md
+
+## Mandatory Workflow
+
+1. 页面/CRUD/列表/表单任务：先读 `.agents/skills/yss-page-module-development/SKILL.md`。
+2. 新增或修改页面、组件、Less、内联样式、TS 渲染配置、SVG 色值：必须读 `.agents/skills/theme-token-usage/SKILL.md`。
+3. 导出、报表、模板、附件、Excel、CSV、PDF、ZIP、Blob 下载任务：必须读 `.agents/skills/file-export-download/SKILL.md`。
+4. 列表或表格任务：同时读 `.agents/skills/page-list-module/SKILL.md`、`.agents/skills/ytable-usage/SKILL.md`、`.agents/skills/yss-use-table-height/SKILL.md`。
+5. 新增/编辑/查看/抽屉表单：同时读 `.agents/skills/yss-formily/SKILL.md`、`.agents/skills/page-form-module/SKILL.md`。
+6. 可编辑表格、扩展属性、添加行/删除行：必须读 `.agents/skills/yedit-table-usage/SKILL.md`。
+7. 用户给原型截图或旧项目路径：必须读 `.agents/skills/prototype-page-acceptance/SKILL.md`，先生成验收清单，再实现。
+
+## Hard Stops
+
+- 禁止使用 YTable 不存在的 `request`、`search-params` Props 和 `actionConfig.actions`；实例 `refresh()` 只刷新当前表格数据，不得当作远程重新查询。
+- 标准列表必须使用 `:data`、`:columns`、`:loading`、`pageable`、`v-model:pagination`、`@page-change`。
+- 表格主操作必须放入 `#toolbar-right`；只有确实需要列设置时才使用 `:toolbar-config="{ custom: true }"`。
+- 业务列表查询区默认将查询/重置按钮放在 YFormily 外部独占一行并右对齐；`AutoButtonGroup + Submit + Reset` 仅用于纯 Formily 提交表单。
+- 所有 YFormily 横向业务表单必须使用 `FormLayout(labelWidth, labelAlign: 'right') -> FormGrid -> 字段`，不得省略固定 label 宽度和右对齐。
+- FormGrid 必须保持响应式：默认 `minColumns: 1`，通过 `maxColumns`、`minWidth` 控制宽屏列数；禁止 `minColumns` 等于 `maxColumns` 固定列数，除非用户明确要求不响应式。
+- 抽屉/弹窗编辑表单默认 `labelWidth: 140`、`FormGrid { maxColumns: 2, minColumns: 1, minWidth: 320~360 }`；备注/长文本字段必须用 `gridSpan` 占满整行。
+- 可编辑表格必须优先使用 `YEditTable`，禁止用 `a-table` 手搓。
+- 抽屉表单必须有响应式宽度，查看态不显示保存按钮。
+- 页面和组件禁止硬编码品牌色及 hover/active/selected/focus 色阶；主色透明态必须从真实动态 Token 派生，不得依赖未同步变量的固定色 fallback。
+- 导出下载必须优先调用 `handleBlobResponse(res.data, res.headers)`；生成方法缺少 Blob 配置时，第二参数必须传 `{ responseType: 'blob' }`，禁止手改 Orval 生成文件。
+- Orval 请求失败由 `mutator.ts` 统一提示并 reject；业务 Hook 禁止 `if (res?.success)` 冗余判断，也禁止在 `else`/`catch` 重复 `message.error`，除非请求显式跳过了全局处理。
+- 调用 Orval API 前必须检查当前生成文件；存在具名导出时直接导入，只有工厂导出时在模块顶层创建一次实例，禁止猜测 `getApi()` 名称。
+- 有截图/旧项目参考时，交付前必须逐项对照查询区、表格工具栏、分页高度、抽屉、label、字段控件类型。

package/template/.agents/skills/.yss-skills-manifest.json

@@ -0,0 +1,28 @@
+{
+  "source": "@yss/skills",
+  "mode": "copy",
+  "skills": [
+    "yss-page-module-development",
+    "theme-token-usage",
+    "component-selection-imports",
+    "page-skeleton",
+    "page-list-module",
+    "page-form-module",
+    "ytable-usage",
+    "yedit-table-usage",
+    "ytree-usage",
+    "prototype-page-acceptance",
+    "yss-api-integration",
+    "file-export-download",
+    "vue3-best-practices",
+    "frontend-commit",
+    "java-backend-commit",
+    "yss-use-table-height",
+    "yss-use-tree-height",
+    "yss-formily",
+    "formily-foundation",
+    "formily-linkage-effects",
+    "formily-mode-slot-detail",
+    "formily-step-flow"
+  ]
+}

package/template/.agents/skills/component-selection-imports/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: component-selection-imports
+description: 指导 YSS UI 业务页面、CRUD、列表页、表单页和组件评审在编码前判定组件、Hook 与工具函数的真实导出来源；当需要在 @yss-ui/components、@yss-ui/hooks、@yss-ui/utils 与 ant-design-vue 之间选择，或需要排查虚构 Y 前缀组件、错误导入、Formily UI 边界时使用。
+---
+
+# 组件选择与导入
+
+## 触发条件
+
+- 生成 YSS UI 业务页面前需要判定组件、Hook 或工具函数来源。
+- 出现错误 Y 前缀、导入冲突、Formily UI 跨层或者组件是否已封装不明确。
+
+## 不适用场景
+
+- 只修改与 UI 导入无关的纯数据逻辑。
+- 组件库内部组件开发；该场景应按组件开发规范处理内部依赖。
+
+## 判定流程
+
+1. 当前会话可用 yss-ui MCP 时，先用 `list_components` 确认组件、Hook 或 Utils 是否真实存在，再用 `get_component_docs` 确认名称、导出包、Props、Events 和 Slots，不只看 demo 标签名。
+2. `get_component_docs` 未命中时，先用 `search_docs` 和 `list_components` 校正别名与归属，不得立即判定为未封装。
+3. MCP 工具不可用、调用失败或校正后仍无结果时，读取当前上下文中的最新 `llms-full.txt`；上下文没有时读取 `http://192.168.164.27:3200/llms-full.txt`。
+4. 必要时读取 `../yss-page-module-development/references/component-map.md`、`hooks-map.md`、`utils-map.md` 快速缩小范围；文档与当前项目依赖版本不一致时，最终以当前源码和可编译导出为准。
+5. 已导出的 YSS 能力优先从 `@yss-ui/components`、`@yss-ui/hooks`、`@yss-ui/utils` 导入；确认未封装后才从 `ant-design-vue` 导入原组件。
+6. 若文档与导出源码不一致，记录差异并按当前仓库可编译的导出处理，不猜测 API。
+
+## 硬约束（禁止/必须）
+
+- 业务层已封装组件必须从 `@yss-ui/components` 导入；可编辑表格必须优先使用 `YEditTable`，业务主表格必须优先使用 `YTable`。
+- 当前公共导出包含 `YButton`、`YCard`、`YTable`、`YEditTable`、`YTree`、`YSplitPane`、`YFormily` 等；未导出 `YModal`、`YDrawer`、`YInput`、`YPopconfirm`，禁止臆造这些名称。
+- 当前未封装的 `Modal`、`Drawer`、`Popconfirm`、`Input` 等从 `ant-design-vue` 导入。删除操作使用按钮附近的 `Popconfirm`，不默认使用居中 `Modal.confirm`。
+- 业务层禁止导入 `@formily/antdv` 或 `@formily/antd*` UI 组件；使用 `YFormily` 提供的 Schema 与组件边界。
+- 禁止因文档暂时不可达就把猜测的 `Y*` 组件改成 Ant Design Vue “先落地”。只能复用当前仓库已证明可用的导入，或明确报告待确认项。
+- 接口错误提示由 `mutator.ts` 的响应拦截器统一处理。API Hook 不得在 `success === false` 分支或 `catch` 内重复调用 `message.error`；`message` 只用于非 API 错误的本地交互反馈或成功提示。
+
+## 标准代码骨架
+
+```typescript
+import {
+  YButton,
+  YCard,
+  YEditTable,
+  YTable,
+  YTree,
+  YFormily,
+  type YEditTableColumn,
+  type YTableColumn,
+} from '@yss-ui/components';
+import { useLoading, useTableHeight, useTreeHeight } from '@yss-ui/hooks';
+import { copyToClipboard, formatDate } from '@yss-ui/utils';
+import { Drawer, Input, Modal, Popconfirm } from 'ant-design-vue';
+```
+
+## 交付检查清单
+
+- [ ] 每个关键导入都能在最新文档或包的 `src/index.ts` 中追溯。
+- [ ] 未导出的 Y 前缀组件没有出现在业务代码中。
+- [ ] 删除、表格、编辑表格和 Formily 导入边界符合项目约束。
+- [ ] API Hook 中没有重复 `message.error`，异常仍由 `Promise.reject` 中断后续流程。
+
+## 失败兜底策略
+
+- MCP 与 `llms-full.txt` 都不可用时，用 CodeGraph/源码 `src/index.ts` 和当前项目已编译的相近页面交叉确认，不猜测导出。
+- 文档与源码不一致时，优先保证当前仓库可编译，并在交付中明确标注文档差异。

package/template/.agents/skills/cross-repo-implementation-routing/SKILL.md

@@ -19,8 +19,8 @@ description: Use when a Harness change or vertical slice may require work across
 1. 读取 `docs/process/implementation-repo-integration.md` 和当前 change 资产。
 2. 判断影响面：Harness-only、backend-only、frontend-only、backend+frontend、contract-only、release-only。
 3. 确认每个受影响实现仓库已有登记记录；缺失则阻断并要求 onboarding。
-4. 核对项目根路径：Harness 内项目必须是 `apps/backend/<project>/` 或 `apps/frontend/<project>/`；`apps/backend/`、`apps/frontend/` 只能作为容器，`app/backend/`、`app/frontend/` 及其子路径必须阻断。外部仓库记录各自的真实项目根。
-5. 输出最小任务分配：Harness 文档 / OpenAPI / 后端 MR / 前端 MR / 验证 / 发布。
+4. 核对项目根路径：Harness 内 `harness-apps` 与 `git-submodule` 项目必须是 `apps/backend/<project>/` 或 `apps/frontend/<project>/`；`apps/backend/`、`apps/frontend/` 只能作为容器，`app/backend/`、`app/frontend/` 及其子路径必须阻断。`git-submodule` 另核 gitlink、`.gitmodules` 和独立 `git_url`。外部 `external-repository` 记录各自的真实项目根。
+5. 输出最小任务分配：Harness 文档 / OpenAPI / 后端 MR / 前端 MR / 验证 / 发布。`git-submodule` 必须追加 `superproject-gitlink-update`。
 6. 按 `docs/templates/cross-repo-slice-template.md` 生成切片记录草案。
 7. 给出 fresh verification 命令和阶段 checkpoint 回写字段。