create-yss-spec 2.2.0 → 2.2.2

package/README.md

@@ -47,7 +47,7 @@ npx create-yss-spec@latest --version
 - init / sync 不把模板源治理笔记、wiki、审查证据、源仓 CI / Cloud 环境和公开发布清单写入项目实例；attach 会带上 `yss-public-skills.json` 供 `verify-template` 使用
 - 空 gitlink / detached HEAD / git-submodule 挂载点 fail closed，`--force` 也不能覆盖
 
-本次模板适配按 `2.2.0` 发布，绑定 `yss-spec-project-template@04a6151`。`templateCommit` 会写入实例 metadata；“最新模板”指用户执行的 `npx create-yss-spec@latest` 所携带的最新已发布快照，CLI 运行时不会拉取模板仓库。
+本次模板适配按 `2.2.2` 发布，绑定 `yss-spec-project-template@51189ca`。`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` 等独立入口不进入快照。
 
 ## 接管已有项目
 
@@ -100,7 +100,7 @@ npx create-yss-spec@latest sync --dry-run
 - 对已知的 Spec / Ticket 旧路径执行一次性迁移
 - 迁移目标已存在且内容不一致时停止，不静默覆盖
 - `.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
+- init / sync 保持实例边界：不复制 `wiki/`、`.github/`、`.template-source/`、源仓库 ADR、Cursor Cloud 环境配置、`docs/reviews/` 或根 `package.json`；共享 `scripts/`、`scripts/vendor/`、`.nvmrc` 和 `.gitignore` 属于实例门禁所需资产。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.2.0",
+  "version": "2.2.2",
   "description": "Initialize a YSS spec project template repository",
   "repository": {
     "type": "git",

package/src/cli.js

@@ -18,6 +18,7 @@ const TEMPLATE_MANIFEST = JSON.parse(TEMPLATE_MANIFEST_TEXT);
 const ROOT_EXCLUDED_ENTRIES = new Set(TEMPLATE_MANIFEST.excludeRootEntries);
 const ROOT_EXCLUDED_FILES = new Set(TEMPLATE_MANIFEST.excludeRootFiles);
 const EXCLUDED_RELATIVE_PATHS = new Set(TEMPLATE_MANIFEST.excludePaths);
+const ALLOWED_RELATIVE_PATHS = new Set(TEMPLATE_MANIFEST.allowFiles || []);
 const INIT_EXCLUDED_ROOT_ENTRIES = new Set(
   TEMPLATE_MANIFEST.initExcludeRootEntries || [],
 );
@@ -47,6 +48,7 @@ const AGENT_SKILL_ROOTS = [
 ];
 const GITLINK_MODE = "160000";
 const UNMANAGED_USER_PATHS = new Set([".gitmodules"]);
+const GITLINK_PATH_CACHE = new Map();
 const INSTANCE_FORBIDDEN_PATHS = [
   ".template-source",
   ".github",
@@ -96,6 +98,9 @@ function readTemplateSnapshot() {
   if (!/^[0-9a-f]{64}$/.test(snapshot.snapshotHash || "")) {
     throw new Error("模板快照必须包含 64 位 snapshotHash");
   }
+  if (snapshot.manifestHash !== TEMPLATE_MANIFEST_VERSION) {
+    throw new Error("模板快照与当前 template.manifest.json 不一致，请重新构建 CLI 包");
+  }
 
   if (
     snapshot.encodedPaths !== undefined &&
@@ -322,8 +327,20 @@ function collectGitRoots(start) {
   }
   let current = path.resolve(start);
   while (true) {
+    const gitPath = path.join(current, ".git");
+    let validGitEntry = false;
+    try {
+      const gitStat = fs.lstatSync(gitPath);
+      validGitEntry = gitStat.isDirectory()
+        ? fs.readdirSync(gitPath).length > 0
+        : gitStat.isFile();
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+    }
     if (
-      fs.existsSync(path.join(current, ".git")) ||
+      validGitEntry ||
       fs.existsSync(path.join(current, ".gitmodules"))
     ) {
       roots.push(current);
@@ -378,7 +395,7 @@ function gitLsFilesStage(repoRoot, relativePath) {
   const result = spawnSync(
     "git",
     ["-C", repoRoot, "ls-files", "--stage", "--", relativePath],
-    { encoding: "utf8" },
+    { encoding: "utf8", timeout: 5000 },
   );
   if (result.status !== 0) {
     return null;
@@ -394,11 +411,34 @@ function gitLsFilesStage(repoRoot, relativePath) {
   return { mode: match[1], sha: match[2], stage: match[3], path: match[4] };
 }
 
+function gitlinkPaths(repoRoot) {
+  const resolvedRoot = path.resolve(repoRoot);
+  if (GITLINK_PATH_CACHE.has(resolvedRoot)) {
+    return GITLINK_PATH_CACHE.get(resolvedRoot);
+  }
+  const result = spawnSync(
+    "git",
+    ["-C", resolvedRoot, "ls-files", "--stage", "-z"],
+    { encoding: "utf8", timeout: 5000 },
+  );
+  const paths = new Set();
+  if (result.status === 0) {
+    for (const record of (result.stdout || "").split("\0")) {
+      const match = record.match(/^(160000)\s+[0-9a-f]+\s+\d+\s+(.+)$/i);
+      if (match) {
+        paths.add(match[2].replaceAll("\\", "/"));
+      }
+    }
+  }
+  GITLINK_PATH_CACHE.set(resolvedRoot, paths);
+  return paths;
+}
+
 function gitShowSuperproject(cwd) {
   const result = spawnSync(
     "git",
     ["-C", cwd, "rev-parse", "--show-superproject-working-tree"],
-    { encoding: "utf8" },
+    { encoding: "utf8", timeout: 5000 },
   );
   if (result.status !== 0) {
     return "";
@@ -410,7 +450,7 @@ function gitAbbrevRef(cwd) {
   const result = spawnSync(
     "git",
     ["-C", cwd, "rev-parse", "--abbrev-ref", "HEAD"],
-    { encoding: "utf8" },
+    { encoding: "utf8", timeout: 5000 },
   );
   if (result.status !== 0) {
     return null;
@@ -432,21 +472,22 @@ function isEmptyDir(dir) {
 
 function isGitSubmoduleMount(repoRoot, targetPathValue) {
   const relative = posixRelative(repoRoot, path.resolve(targetPathValue));
-  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+  if (!relative || 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;
+  return gitlinkPaths(repoRoot).has(relative);
 }
 
 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 staged = inRepo && gitlinkPaths(repoRoot).has(relative)
+    ? { mode: GITLINK_MODE }
+    : null;
   const listed = inRepo
     ? readGitmodules(repoRoot).some((item) => item.path === relative)
     : false;
@@ -577,6 +618,11 @@ function targetPath(targetDir, relativePath) {
 
 function shouldExcludeRelativePath(relativePath, mode = "managed") {
   const normalized = normalizeRelativePath(relativePath);
+  if ([...ALLOWED_RELATIVE_PATHS].some(
+    (allowedPath) => allowedPath === normalized || allowedPath.startsWith(`${normalized}/`),
+  )) {
+    return false;
+  }
   return EXCLUDED_RELATIVE_PATHS.has(normalized) ||
     (mode === "init" &&
       (INIT_EXCLUDED_RELATIVE_PATHS.has(normalized) ||
@@ -1505,6 +1551,7 @@ function gitDirtyWarning(targetDir) {
   const probe = spawnSync("git", ["rev-parse", "--is-inside-work-tree"], {
     cwd: targetDir,
     encoding: "utf8",
+    timeout: 5000,
   });
   if (probe.status !== 0 || probe.stdout.trim() !== "true") {
     return null;
@@ -1512,6 +1559,7 @@ function gitDirtyWarning(targetDir) {
   const status = spawnSync("git", ["status", "--porcelain"], {
     cwd: targetDir,
     encoding: "utf8",
+    timeout: 5000,
   });
   if (status.status === 0 && status.stdout.trim()) {
     return "警告：目标 Git worktree 存在未提交改动；CLI 不会自动 stash 或提交，请在结果后检查 git diff / git status";

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/file-export-download/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: file-export-download
+description: 指导 Vue3 YSS UI 微应用实现文件导出、报表下载、模板下载和附件下载，覆盖 OpenAPI binary 响应、Orval 生成方法检查、responseType blob 兜底、Blob 响应类型、Content-Disposition 文件名、handleBlobResponse、loading 与错误处理；当需求出现导出、下载、Excel、CSV、PDF、ZIP、Blob 或文件流时使用。
+---
+
+# YSS 文件导出下载 Skill
+
+## 触发条件
+
+- 页面需要导出 Excel、CSV、PDF、ZIP、报表、密钥文件或其他二进制文件。
+- 页面需要下载导入模板、附件或后端动态生成的文件。
+- Orval 生成接口的返回值是 `Blob`，或业务调用需要配置 `responseType: 'blob'`。
+- 代码正在手写 `URL.createObjectURL`、解析 `Content-Disposition`、拼接文件名或调用 `downloadFileStream`。
+
+## 不适用场景
+
+- 仅上传文件，不包含模板下载或导出流程。
+- 下载公开静态 URL 且无需鉴权、请求参数和响应头文件名时，使用 `downloadFileFromUrl(url, fileName?)`。
+- 浏览器只需要预览远程 PDF/图片，不触发文件保存。
+
+## 必读依据
+
+- 通用接口规则：`../yss-api-integration/SKILL.md`。
+- 当前项目：`openapi/openapi.json`、Orval 配置、生成后的 API 方法和 `packages/src/api/mutator.ts`。
+- YSS Utils 文件下载能力：按下方检索顺序核对 `handleBlobResponse` 和 `downloadBlob`。
+
+## 文档检索
+
+1. MCP 可用时，先用 `search_docs` 查询 `handleBlobResponse 文件下载 Content-Disposition`，并读取命中的 `downloadBlob（/utils/download）` 文档。该能力属于工具函数，不强制调用面向组件别名的 `get_component_docs`。
+2. 搜索无结果时，调整关键词再次调用 `search_docs`；仅在 MCP 不可用、调用失败或仍无结果时，回退读取最新 `llms-full.txt` 的文件下载章节。文档版本与当前依赖不一致时，再核对 `packages/utils` 源码、CodeGraph 和真实导出。
+
+## 决策流程
+
+1. 在 OpenAPI 中定位导出接口，优先把成功响应声明为二进制媒体类型和 `format: binary`。
+2. 重新生成 API 后检查生成方法，而不是凭接口名称判断：
+   - 已包含 `responseType: 'blob'`：业务调用不必重复传第二参数。
+   - 未包含 `responseType: 'blob'`：业务调用必须传第二参数 `{ responseType: 'blob' }`。
+3. 检查 mutator 和全局错误处理器：Blob 成功响应必须保留 `{ data, headers }`；HTTP 4xx/5xx 的 Blob JSON 错误应由全局错误处理器解析并 reject。
+4. 在业务 hook 中设置 loading、防重复点击，调用生成 API，再执行 `handleBlobResponse(res.data, res.headers)`。
+5. 验证文件名、文件内容、错误响应和连续点击，不只验证浏览器出现了下载任务。
+
+> OpenAPI 标准通过响应 `content` 和 `format: binary` 表达二进制，不直接使用 Axios 的 `responseType` 字段。最终以 Orval 生成方法是否含 `responseType: 'blob'` 为判断依据。
+
+## 硬约束（禁止/必须）
+
+- 必须优先导入 `import { handleBlobResponse } from '@yss-ui/utils';` 处理接口文件流。
+- 必须调用 `handleBlobResponse(res.data, res.headers)`；它会自动兼容响应头大小写，并解析 RFC 5987 `filename*` 与普通 `filename`。
+- 第三个 `hasUtf8Encoding` 参数已弃用，禁止继续传递。
+- 生成方法缺少 Blob 配置时，必须在第二参数顶层传 `{ responseType: 'blob' }`；禁止放进 `headers`、请求 body 或查询参数。
+- 生成方法已包含 Blob 配置时，禁止为“保险”重复传相同配置；先保持 OpenAPI 契约和生成产物正确。
+- 禁止修改 Orval 生成文件补写 `responseType`，因为重新生成会覆盖；应修正 OpenAPI，或在业务调用第二参数临时兜底。
+- 禁止依赖 URL 中包含 `download/export` 的请求拦截器猜测响应类型；接口可能不按该名称命名。
+- 禁止在业务层重复实现 `getFileNameFromContentDisposition`、`downloadFileStream`、`URL.createObjectURL` 和 `<a download>` 流程。
+- 必须保留响应头；只取 `res.data` 会丢失服务端文件名。
+- Blob 接口失败时遵循全局 mutator 错误处理，禁止在 catch 中重复 `message.error`；成功下载后可提示 `message.success`。
+- 当前模板 mutator 只能识别“已解析 JSON 对象”的 `success === false`，不会自动检测 HTTP 200 Blob 内的业务错误；发现该契约时必须先修正后端状态码或 mutator，禁止把解析逻辑复制到每个 Hook。
+- 必须用独立 loading 状态防止重复导出，并在 `finally` 中恢复。
+- 不得默认传 `skipBusinessError` 或 `skipErrorHandler`；只有明确需要业务自定义错误体验时才使用。
+
+## OpenAPI 标准代码骨架
+
+```json
+{
+  "responses": {
+    "200": {
+      "description": "导出成功",
+      "headers": {
+        "Content-Disposition": {
+          "schema": { "type": "string" }
+        }
+      },
+      "content": {
+        "application/octet-stream": {
+          "schema": {
+            "type": "string",
+            "format": "binary"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+根据文件类型可将媒体类型换成 `text/csv`、`application/pdf` 或 Excel 对应类型。跨域请求若读取不到文件名，后端还必须暴露 `Content-Disposition` 响应头。
+
+## 标准代码骨架
+
+### 生成方法已包含 responseType
+
+```typescript
+import { ref } from 'vue';
+import { handleBlobResponse } from '@yss-ui/utils';
+import { downloadAccessSecret } from '@/api/generated/quality';
+
+/** 微应用 mutator 返回的文件下载响应。 */
+type BlobDownloadResponse = {
+  data: Blob;
+  headers: Record<string, string>;
+};
+
+/** 文件下载进行中状态。 */
+const downloading = ref(false);
+
+/** 下载密钥文件。 */
+const downloadFile = async (key: string): Promise<void> => {
+  if (downloading.value) return;
+
+  downloading.value = true;
+  try {
+    const res = (await downloadAccessSecret(key)) as unknown as BlobDownloadResponse;
+    handleBlobResponse(res.data, res.headers);
+  } catch {
+    // mutator 已展示错误；此处只阻止 reject 继续向 UI 事件传播。
+  } finally {
+    downloading.value = false;
+  }
+};
+```
+
+### 生成方法缺少 responseType
+
+只改调用行，其他流程保持一致：
+
+```typescript
+const res = (await downloadAccessSecret(key, {
+  responseType: 'blob',
+})) as unknown as BlobDownloadResponse;
+```
+
+若 mutator 与 Orval 返回类型已经准确声明为 `{ data: Blob; headers: ... }`，直接使用生成类型，删除不必要的类型断言。
+
+## 响应约定
+
+- 后端成功响应应返回真实文件流，并设置 `Content-Disposition: attachment; filename*=UTF-8''...`。
+- mutator 对 Blob 成功响应返回 `{ data, headers }`，以便 `handleBlobResponse` 获取文件名。
+- HTTP 错误的 Blob JSON 由全局错误处理器解析并 reject，业务 Hook 不重复解析或提示。
+- HTTP 200 且 body 是 Blob 包装的业务错误时，当前模板不会自动 reject；必须修复契约或统一拦截器后再交付。
+- `handleBlobResponse` 找不到文件名时会使用 `download`；应优先补齐后端响应头，而不是在每个页面手写解析逻辑。
+
+## 交付检查清单
+
+- [ ] 已检查 OpenAPI 二进制响应声明和 Orval 生成方法。
+- [ ] 仅在生成方法缺少配置时，第二参数传入了 `{ responseType: 'blob' }`。
+- [ ] 已从 `@yss-ui/utils` 导入并调用 `handleBlobResponse(res.data, res.headers)`。
+- [ ] 未修改 Orval 生成文件，未重复实现文件名解析或浏览器下载逻辑。
+- [ ] Blob 成功响应保留了 `data` 与 `headers`，类型断言只位于 API 边界。
+- [ ] 已处理 loading、防重复点击和 `finally` 恢复。
+- [ ] 未在 catch 中重复业务错误 Toast。
+- [ ] 中文文件名、普通文件名和缺失文件名场景均已验证。
+- [ ] HTTP 错误的 Blob JSON 会 reject；如存在 HTTP 200 Blob 业务错误契约，已修正后端状态码或 mutator。
+- [ ] 下载文件可以正常打开，格式和内容与接口预期一致。
+
+## 失败兜底策略
+
+- 生成方法不支持第二参数时，先确认 Orval `options: true`；修正配置并重新生成，禁止手改生成文件。
+- `res.headers` 为空时，检查 mutator 是否错误地只返回 `data`，以及后端/CORS 是否暴露 `Content-Disposition`。
+- 下载到 JSON 错误文件时，先确认 HTTP 状态码：非 2xx 检查全局错误处理器，HTTP 200 检查后端契约并在 mutator 统一补齐；禁止把解析逻辑复制到每个业务 Hook。
+- 文件名始终为 `download` 时，优先修复后端 `Content-Disposition`；无法改后端时再评估统一扩展 YSS 下载工具。
+- 超大文件导致内存压力时，改用后端临时 URL、分片或流式下载方案，不强行把全部内容载入 Blob。

package/template/.agents/skills/file-export-download/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "YSS 文件导出下载"
+  short_description: "规范 Orval Blob 导出、responseType 配置与文件下载处理"
+  default_prompt: "使用 $file-export-download 实现类型安全的文件导出下载，并正确处理 Blob、响应头和文件名。"