create-yss-spec 3.5.6 → 3.5.8

package/template/.agents/skills/file-export-download/SKILL.md

@@ -31,7 +31,7 @@ description: "在 Vue3 YSS UI 中实现或修复文件下载与导出，处理 O
 
 ## 决策流程
 
-1. 在 OpenAPI 中定位导出接口，优先把成功响应声明为二进制媒体类型和 `format: binary`。
+1. 在冻结 OpenAPI 中定位导出接口，核对成功响应的二进制媒体类型和 `format: binary`。需要修改声明时回交 `yss-openapi-governance`，完成现有 Draft / Freeze 与受控 JSON 派生链后再接入。
 2. 重新生成 API 后检查生成方法，而不是凭接口名称判断：
    - 已包含 `responseType: 'blob'`：业务调用不必重复传第二参数。
    - 未包含 `responseType: 'blob'`：业务调用必须传第二参数 `{ responseType: 'blob' }`。
@@ -57,78 +57,9 @@ description: "在 Vue3 YSS UI 中实现或修复文件下载与导出，处理 O
 - 必须用独立 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: ... }`，直接使用生成类型，删除不必要的类型断言。
+## 按需示例
+
+核对二进制响应与文件名声明时，读取 [OpenAPI 二进制响应示例](references/binary-contract-example.md)。首次接入生成方法、或需判断是否补传 Blob 选项时，读取 [下载调用示例](references/download-call-example.md)，按生成方法的真实签名选择分支。
 
 ## 响应约定
 

package/template/.agents/skills/file-export-download/references/binary-contract-example.md

@@ -0,0 +1,26 @@
+## 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` 响应头。

package/template/.agents/skills/file-export-download/references/download-call-example.md

@@ -0,0 +1,45 @@
+## 标准代码骨架
+
+### 生成方法已包含 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: ... }`，直接使用生成类型，删除不必要的类型断言。

package/template/.agents/skills/formily-foundation/SKILL.md

@@ -3,7 +3,7 @@ name: formily-foundation
 description: 指导 YFormily 基础表单开发；当创建或修复普通单页表单、字段校验、提交链路、查询表单布局、scope 表达式或导入边界时使用。
 ---
 
-# Formily Foundation Skill
+# YFormily 基础表单
 
 ## 触发条件
 
@@ -28,6 +28,7 @@ description: 指导 YFormily 基础表单开发；当创建或修复普通单页
 - 禁止业务层导入 `@formily/antdv`、`@formily/antd*` UI 组件。
 - 必须使用三层结构：`FormLayout -> FormGrid -> 字段`，禁止字段直接挂在根节点或单独以 `FormGrid` 作为顶层布局。
 - `Submit` 必须传 `onSubmit`，否则不触发表单提交。
+- 异步保存时 `onSubmit` 返回实际保存 Promise，以等待完成并传播 reject；`emit('submit')` 只发送事件，不能代表父回调的异步结果。
 - 标准业务列表/CRUD 查询区默认让 `YFormily` 只渲染字段；查询/重置按钮用外部 `YButton` 放在 `.xxx__search-actions`，由 hook 的 `handleSearch/handleReset` 控制分页重置和请求。
 - `AutoButtonGroup -> Submit/Reset` 仅用于纯 Formily 表单提交，不作为业务列表查询区默认方案。
 - 查询区禁止横向放“表单 + 按钮”后用大 `gap`、`align-items: flex-start` 或 `padding-top` 硬调位置；字段换行时按钮必须在搜索卡片右下角。
@@ -46,109 +47,9 @@ description: 指导 YFormily 基础表单开发；当创建或修复普通单页
   - 当前 YFormily 的 FormItem 适配层会在运行时归一化反馈：空值优先显示必填提示，非空值移除残留必填提示，多条相关消息只拼接一次。该兜底不替代正确的 Schema 校验职责拆分。
 - 分步需求默认走 `formily-step-flow`，不在本 skill 内给 `FormStep` 方案。
 
-## 标准代码骨架
-
-```vue
-<script setup lang="ts">
-import { YFormily, type ISchema } from '@yss-ui/components';
-
-/** 表单保存回调 Props。 */
-interface SaveFormProps {
-  onSave: (values: Record<string, any>) => Promise<void>;
-}
-
-/** 表单保存回调。 */
-const props = defineProps<SaveFormProps>();
-
-/** 校验通过后提交表单数据。 */
-const onSubmit = (values: Record<string, any>) => {
-  return props.onSave(values);
-};
-
-/** 基础表单 Schema。 */
-const schema: ISchema = {
-  type: 'object',
-  properties: {
-    layout: {
-      type: 'void',
-      'x-component': 'FormLayout',
-      'x-component-props': { layout: 'horizontal', labelWidth: 120, labelAlign: 'right' },
-      properties: {
-        grid: {
-          type: 'void',
-          'x-component': 'FormGrid',
-          'x-component-props': { maxColumns: 3, minColumns: 1, minWidth: 260 },
-          properties: {
-            name: { type: 'string', title: '名称', 'x-decorator': 'FormItem', 'x-component': 'Input', required: true, 'x-validator': [{ required: true, whitespace: true, message: '请输入名称' }] },
-            submit: {
-              type: 'void',
-              'x-component': 'Submit',
-              'x-content': '提交',
-              'x-component-props': { onSubmit: '{{ onSubmit }}' },
-            },
-          },
-        },
-      },
-    },
-  },
-};
-</script>
-
-<template>
-  <YFormily :schema="schema" :scope="{ onSubmit }" />
-</template>
-```
-
-## 业务查询区布局
-
-```vue
-<template>
-  <YCard class="demo-page__search-card" :padding="16">
-    <div class="demo-page__search-content">
-      <div class="demo-page__search-form">
-        <YFormily v-model="queryModel" :schema="searchSchema" />
-      </div>
-      <div class="demo-page__search-actions">
-        <YButton type="primary" @click="handleSearch">查询</YButton>
-        <YButton @click="handleReset">重置</YButton>
-      </div>
-    </div>
-  </YCard>
-</template>
-```
-
-```less
-.demo-page {
-  &__search-content {
-    display: flex;
-    flex-direction: column;
-    align-items: stretch;
-    gap: 16px;
-  }
-
-  &__search-form {
-    width: 100%;
-    min-width: 0;
-
-    :deep(.ant-formily-form-item) {
-      margin-bottom: 0;
-    }
-
-    :deep(.ant-formily-form-grid) {
-      width: 100%;
-    }
-  }
-
-  &__search-actions {
-    display: flex;
-    width: 100%;
-    flex: 0 0 auto;
-    align-items: center;
-    justify-content: flex-end;
-    gap: 12px;
-  }
-}
-```
+## 按需示例
+
+同步事件提交读取 [基础表单与提交](references/examples.md#1-基础表单与提交)；等待父回调完成的异步保存读取 [异步保存回调](references/async-save-example.md)。Orval 提交的 loading、reject 与错误提示读取 [错误处理](references/examples.md#8-orval-提交与错误处理)。实现业务列表查询区或排查窄屏按钮位置时，读取 [业务查询区布局](references/query-layout.md)。联动、模式和分步示例只在对应条件命中时读取，并服从实际命中的专项 Skill。
 
 ## 交付检查清单
 
@@ -173,4 +74,4 @@ const schema: ISchema = {
 
 ## 参考
 
-- 完整示例：`./references/examples.md`
+[示例库目录](references/examples.md#目录)按具体场景定位，不要求每次读取全部示例。

package/template/.agents/skills/formily-foundation/references/async-save-example.md

@@ -0,0 +1,57 @@
+# 异步保存回调
+
+等待父回调完成的保存场景读取本例。`onSubmit` 必须返回实际保存 Promise；发送 `emit` 事件只返回 void，不能等待父组件的异步请求。
+
+Orval 请求失败沿用 [错误处理](examples.md#8-orval-提交与错误处理)，由 mutator 统一提示，调用方恢复 loading 并传播 reject。
+
+```vue
+<script setup lang="ts">
+import { YFormily, type ISchema } from '@yss-ui/components';
+
+/** 表单保存回调 Props。 */
+interface SaveFormProps {
+  onSave: (values: Record<string, any>) => Promise<void>;
+}
+
+/** 表单保存回调。 */
+const props = defineProps<SaveFormProps>();
+
+/** 校验通过后提交表单数据。 */
+const onSubmit = (values: Record<string, any>) => {
+  return props.onSave(values);
+};
+
+/** 基础表单 Schema。 */
+const schema: ISchema = {
+  type: 'object',
+  properties: {
+    layout: {
+      type: 'void',
+      'x-component': 'FormLayout',
+      'x-component-props': { layout: 'horizontal', labelWidth: 120, labelAlign: 'right' },
+      properties: {
+        grid: {
+          type: 'void',
+          'x-component': 'FormGrid',
+          'x-component-props': { maxColumns: 3, minColumns: 1, minWidth: 260 },
+          properties: {
+            name: { type: 'string', title: '名称', 'x-decorator': 'FormItem', 'x-component': 'Input', required: true, 'x-validator': [{ required: true, whitespace: true, message: '请输入名称' }] },
+            submit: {
+              type: 'void',
+              'x-component': 'Submit',
+              'x-content': '提交',
+              'x-component-props': { onSubmit: '{{ onSubmit }}' },
+            },
+          },
+        },
+      },
+    },
+  },
+};
+</script>
+
+<template>
+  <YFormily :schema="schema" :scope="{ onSubmit }" />
+</template>
+```
+

package/template/.agents/skills/formily-foundation/references/query-layout.md

@@ -0,0 +1,50 @@
+## 业务查询区布局
+
+```vue
+<template>
+  <YCard class="demo-page__search-card" :padding="16">
+    <div class="demo-page__search-content">
+      <div class="demo-page__search-form">
+        <YFormily v-model="queryModel" :schema="searchSchema" />
+      </div>
+      <div class="demo-page__search-actions">
+        <YButton type="primary" @click="handleSearch">查询</YButton>
+        <YButton @click="handleReset">重置</YButton>
+      </div>
+    </div>
+  </YCard>
+</template>
+```
+
+```less
+.demo-page {
+  &__search-content {
+    display: flex;
+    flex-direction: column;
+    align-items: stretch;
+    gap: 16px;
+  }
+
+  &__search-form {
+    width: 100%;
+    min-width: 0;
+
+    :deep(.ant-formily-form-item) {
+      margin-bottom: 0;
+    }
+
+    :deep(.ant-formily-form-grid) {
+      width: 100%;
+    }
+  }
+
+  &__search-actions {
+    display: flex;
+    width: 100%;
+    flex: 0 0 auto;
+    align-items: center;
+    justify-content: flex-end;
+    gap: 12px;
+  }
+}
+```

package/template/.agents/skills/formily-linkage-effects/SKILL.md

@@ -3,7 +3,7 @@ name: formily-linkage-effects
 description: 指导 YFormily 字段联动与表单级副作用；当实现动态显隐、禁用、级联选项、scope 事件、x-reactions、effects、异步联动或客户端校验失败兜底时使用。
 ---
 
-# Formily Linkage Effects Skill
+# YFormily 联动与副作用
 
 ## 触发条件
 
@@ -33,122 +33,9 @@ description: 指导 YFormily 字段联动与表单级副作用；当实现动态
 - Orval API 的网络/业务错误已由 `mutator.ts` 提示并 reject，业务 `else`/`catch` 禁止重复 `message.error`。
 - 分步需求默认走 `formily-step-flow`，不在此 skill 中给 `FormStep` 默认方案。
 
-## 标准代码骨架
+## 按需示例
 
-```vue
-<script setup lang="ts">
-import type { DataField, Form, IFieldState } from '@formily/core';
-import { createForm, onFieldInit, onFieldValueChange, onFormSubmitValidateFailed } from '@formily/core';
-import { YFormily, type ISchema } from '@yss-ui/components';
-import { message } from 'ant-design-vue';
-
-/** 下拉选项。 */
-interface OptionItem {
-  label: string;
-  value: string;
-}
-
-/** 根据省份返回城市选项。 */
-const getCityOptions = (province?: string): OptionItem[] =>
-  province === 'zhejiang'
-    ? [{ label: '杭州', value: 'hangzhou' }]
-    : province === 'jiangsu'
-      ? [{ label: '南京', value: 'nanjing' }]
-      : [];
-
-/** 同步城市选项并清理已经失效的旧值。 */
-const syncCity = (field: DataField) => {
-  const options = getCityOptions(field.value as string | undefined);
-  field.form.setFieldState('city', (state: IFieldState) => {
-    state.dataSource = options;
-    if (!options.some(item => item.value === state.value)) state.value = undefined;
-  });
-};
-
-/** 外部 Form 实例，用于承载表单级 effects。 */
-const form: Form = createForm({
-  values: { province: 'zhejiang', city: 'hangzhou' },
-  effects() {
-    onFieldInit('province', field => syncCity(field as DataField));
-    onFieldValueChange('province', field => syncCity(field as DataField));
-    onFormSubmitValidateFailed(() => {
-      const feedbacks = form.queryFeedbacks({ type: 'error' });
-      message.error(feedbacks[0]?.messages?.[0] ?? '请检查表单');
-    });
-  },
-});
-
-/** 表单保存回调 Props。 */
-interface SaveFormProps {
-  onSave: (values: Record<string, any>) => Promise<void>;
-}
-
-/** 表单保存回调。 */
-const props = defineProps<SaveFormProps>();
-
-/** 校验通过后提交；API 错误由 mutator 统一提示。 */
-const onSubmit = (values: Record<string, any>) => {
-  return props.onSave(values);
-};
-
-/** 级联表单 Schema。 */
-const schema: ISchema = {
-  type: 'object',
-  properties: {
-    layout: {
-      type: 'void',
-      'x-component': 'FormLayout',
-      'x-component-props': { layout: 'horizontal', labelWidth: 120, labelAlign: 'right' },
-      properties: {
-        grid: {
-          type: 'void',
-          'x-component': 'FormGrid',
-          'x-component-props': { maxColumns: 2, minColumns: 1, minWidth: 320 },
-          properties: {
-            province: {
-              type: 'string',
-              title: '省份',
-              required: true,
-              enum: [
-                { label: '浙江', value: 'zhejiang' },
-                { label: '江苏', value: 'jiangsu' },
-              ],
-              'x-decorator': 'FormItem',
-              'x-component': 'Select',
-            },
-            city: {
-              type: 'string',
-              title: '城市',
-              required: true,
-              'x-decorator': 'FormItem',
-              'x-component': 'Select',
-            },
-            actions: {
-              type: 'void',
-              'x-decorator': 'FormItem',
-              'x-decorator-props': { gridSpan: 2, colon: false },
-              'x-component': 'AutoButtonGroup',
-              properties: {
-                submit: {
-                  type: 'void',
-                  'x-component': 'Submit',
-                  'x-content': '提交',
-                  'x-component-props': { onSubmit: '{{ onSubmit }}' },
-                },
-              },
-            },
-          },
-        },
-      },
-    },
-  },
-};
-</script>
-
-<template>
-  <YFormily :schema="schema" :form="form" :scope="{ onSubmit }" />
-</template>
-```
+首次组织 `createForm + effects`、排查初始化联动或校验反馈时，读取 [联动与 effects 示例](references/linkage-example.md)。基础布局和提交仍按 `formily-foundation`。
 
 ## 交付检查清单
 

package/template/.agents/skills/formily-linkage-effects/references/linkage-example.md

@@ -0,0 +1,116 @@
+## 标准代码骨架
+
+```vue
+<script setup lang="ts">
+import type { DataField, Form, IFieldState } from '@formily/core';
+import { createForm, onFieldInit, onFieldValueChange, onFormSubmitValidateFailed } from '@formily/core';
+import { YFormily, type ISchema } from '@yss-ui/components';
+import { message } from 'ant-design-vue';
+
+/** 下拉选项。 */
+interface OptionItem {
+  label: string;
+  value: string;
+}
+
+/** 根据省份返回城市选项。 */
+const getCityOptions = (province?: string): OptionItem[] =>
+  province === 'zhejiang'
+    ? [{ label: '杭州', value: 'hangzhou' }]
+    : province === 'jiangsu'
+      ? [{ label: '南京', value: 'nanjing' }]
+      : [];
+
+/** 同步城市选项并清理已经失效的旧值。 */
+const syncCity = (field: DataField) => {
+  const options = getCityOptions(field.value as string | undefined);
+  field.form.setFieldState('city', (state: IFieldState) => {
+    state.dataSource = options;
+    if (!options.some(item => item.value === state.value)) state.value = undefined;
+  });
+};
+
+/** 外部 Form 实例，用于承载表单级 effects。 */
+const form: Form = createForm({
+  values: { province: 'zhejiang', city: 'hangzhou' },
+  effects() {
+    onFieldInit('province', field => syncCity(field as DataField));
+    onFieldValueChange('province', field => syncCity(field as DataField));
+    onFormSubmitValidateFailed(() => {
+      const feedbacks = form.queryFeedbacks({ type: 'error' });
+      message.error(feedbacks[0]?.messages?.[0] ?? '请检查表单');
+    });
+  },
+});
+
+/** 表单保存回调 Props。 */
+interface SaveFormProps {
+  onSave: (values: Record<string, any>) => Promise<void>;
+}
+
+/** 表单保存回调。 */
+const props = defineProps<SaveFormProps>();
+
+/** 校验通过后提交；API 错误由 mutator 统一提示。 */
+const onSubmit = (values: Record<string, any>) => {
+  return props.onSave(values);
+};
+
+/** 级联表单 Schema。 */
+const schema: ISchema = {
+  type: 'object',
+  properties: {
+    layout: {
+      type: 'void',
+      'x-component': 'FormLayout',
+      'x-component-props': { layout: 'horizontal', labelWidth: 120, labelAlign: 'right' },
+      properties: {
+        grid: {
+          type: 'void',
+          'x-component': 'FormGrid',
+          'x-component-props': { maxColumns: 2, minColumns: 1, minWidth: 320 },
+          properties: {
+            province: {
+              type: 'string',
+              title: '省份',
+              required: true,
+              enum: [
+                { label: '浙江', value: 'zhejiang' },
+                { label: '江苏', value: 'jiangsu' },
+              ],
+              'x-decorator': 'FormItem',
+              'x-component': 'Select',
+            },
+            city: {
+              type: 'string',
+              title: '城市',
+              required: true,
+              'x-decorator': 'FormItem',
+              'x-component': 'Select',
+            },
+            actions: {
+              type: 'void',
+              'x-decorator': 'FormItem',
+              'x-decorator-props': { gridSpan: 2, colon: false },
+              'x-component': 'AutoButtonGroup',
+              properties: {
+                submit: {
+                  type: 'void',
+                  'x-component': 'Submit',
+                  'x-content': '提交',
+                  'x-component-props': { onSubmit: '{{ onSubmit }}' },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+};
+</script>
+
+<template>
+  <YFormily :schema="schema" :form="form" :scope="{ onSubmit }" />
+</template>
+```