create-yss-spec 2.1.15 → 2.2.1

package/template/.cursor/skills/yss-formily/SKILL.md

@@ -1,99 +1,99 @@
 ---
 name: yss-formily
-description: Use when a task involves creating or modifying YssFormily or YFormily schema-driven forms, search forms, detail views, field linkage, async validation, dynamic arrays, step forms, or custom slot fields.
+description: 指导在 YSS UI 业务页面中正确使用 @yss-ui/components 的 YFormily；当新增、编辑、查看、查询、联动、详情插槽、分步表单或动态 schema 需求出现时使用，并校验组件导入、提交与错误处理边界。
 ---
 
-# YssFormily
+# YFormily 表单开发 Skill
+
+## 触发条件
+
+- 生成或修改新增、编辑、查看、弹窗表单、详情表单、查询表单。
+- 需要 JSON Schema、字段联动、动态显隐、远程字典、Slot 自定义渲染。
+- 需要 `mode=0/1/2`、详情 Descriptions、分步表单。
+
+## 不适用场景
+
+- 页面只有普通列表，不涉及表单：使用 `../page-list-module/SKILL.md`。
+- 只处理表格操作列或分页：使用 `../ytable-usage/SKILL.md`。
+- 组件库内部改造 YFormily 源码：使用 `../component-development/SKILL.md`。
+
+## 文档检索
+
+1. 当前会话可用 yss-ui MCP 时，先用 `get_component_docs` 查询 `YFormily` 的 Props、Events、Slots、Methods 和 Types；再按需求用 `get_demo` 获取 `formily/basic`、`formily/linkage`、`formily/modes`、`formily/effects`、`formily/steps` 等官方 Demo。
+2. MCP 查询未命中时先用 `search_docs/list_components` 校正名称；只有 MCP 不可用、调用失败或校正后仍无结果时，才读取最新 `llms-full.txt`。文档与当前项目依赖版本不一致时，用当前源码和可编译导出核验，不猜测 API。
+3. 本 Skill 已加载时不得用 `get_skill` 重复查询自身；只在所需 Formily 子 Skill 未同步到本地时使用 `get_skill` 兜底。
+
+## 硬约束（禁止/必须）
+
+- 业务生成代码统一使用 `import { YFormily, type ISchema } from '@yss-ui/components'`。
+- `YFormily` 是标准推荐名称；`YssFormily` 仅作为历史兼容别名，除非维护旧代码，不用于新代码。
+- 业务层禁止导入 `@formily/antdv` UI 组件，禁止导入不存在的 `@formily/antd-v3`。
+- 所有业务 `YFormily` schema 必须包含 `FormLayout -> FormGrid -> 字段` 基础层级，禁止直接以字段或单独 `FormGrid` 作为顶层布局。
+- `Submit` 组件必须传 `onSubmit`，否则不会触发提交校验。
+- 标准业务列表/CRUD 查询区默认让 `YFormily` 只渲染查询字段；“查询/重置”用外部 `YButton` 放在 `.xxx__search-actions`，由 hook 的 `handleSearch/handleReset` 控制分页重置和请求。
+- `AutoButtonGroup + Submit + Reset` 仅用于纯 Formily 表单提交场景，不作为业务列表查询区默认方案。
+- 查询区禁止把 `.xxx__search-content` 写成横向“表单 + 按钮”并用大 `gap`、`align-items: flex-start`、`padding-top` 硬调按钮位置；字段换行时按钮必须仍在搜索卡片右下角。
+- 横向业务表单必须显式设置 `FormLayout` 的 `labelWidth` 和 `labelAlign: 'right'`；抽屉/弹窗表单不得让 label 宽度随文本抖动。
+- `FormGrid` 必须保持响应式：默认 `minColumns: 1`，通过 `maxColumns`、`minWidth` 控制宽屏列数；禁止把 `minColumns` 写成与 `maxColumns` 相同的固定列数，除非用户明确要求固定不响应。
+- 抽屉/弹窗编辑表单默认 `labelWidth: 140`、`labelAlign: 'right'`、`FormGrid { maxColumns: 2, minColumns: 1, minWidth: 320~360 }`；备注、长文本等字段用 `gridSpan` 占满整行。
+- **数据前置同步原则（必守）**：弹窗/抽屉表单数据必须在 `openCreate`/`openEdit` 打开方法中**同步赋好 `formModel.value`**，严禁在子组件内部通过 `watch(visible) + await nextTick() + initForm()` 滞后回填数据。
+- **单一信任源**：优先使用 `v-model="formModel"` + `ref="formRef"` 调用 `formRef.value.submit()` 获取校验后数据；严禁在业务组件顶层写 `const form = createForm()` 单例并与 `v-model`、`form.setValues()`、`form.reset()` 混用导致状态死锁。
+- **禁止滥用动态 `:key`**：严禁在 `YFormily`/`YssFormily` 上使用 `:key="isEdit ? 'edit' : 'create'"` 强制 Remount，必须通过响应式数据或 `:mode` 驱动。
+- **弹窗生命周期隔离**：Modal/Drawer 必须配置 `:destroy-on-close="true"`，且内部 `YFormily` 必须带 `v-if="visible/open"` 随容器打开挂载、关闭销毁，保证数据干净无残留。
+- 下拉/选择器（`Select`, `TreeSelect`, `Radio.Group` 等）异步数据源**必须使用 `enum` 或 `x-reactions` / `field.dataSource` 注入**；**严禁将异步 options 数组直接写入 `x-component-props.options`**（会导致 Formily 首次挂载覆盖为空数组且外部响应式无法通知，产生首次打开弹窗显示“暂无数据”、关闭再打开才展示的经典 Bug）。
+- 弹窗/抽屉表单的基础字典下拉数据，优先在打开前 `await fetchOptions()` 或在页面 `onMounted` 提前拉取；在组件内部 `watch` 更新选项时，必须使用精确字段路径并在 `await nextTick()` 后调用 `form.setFieldState('fieldName', state => { state.dataSource = options })`。
+- `mode=2` 自动进入详情查看态；不要生成旧式详情开关 prop，配置描述列表用 `detail-options`。
+- 只使用源码已公开的 Props 和实例方法；当前没有 `show-button-group`、`detail-as`、`validate`、`reset`、`clearValidate` 等 YFormily API，禁止根据旧 demo 猜测。
+- 分步表单默认使用 AntDV `Steps + 多 YFormily`，不默认使用 `FormStep`。
+- Orval API 的网络错误及 `success === false` 业务错误已由 `mutator.ts` 统一 `message.error` 并 reject；提交 hook 的 `else`/`catch` 只做状态恢复或业务补偿，禁止重复 `message.error`。
+- 需要统一提示客户端校验失败时使用 `onFormSubmitValidateFailed`；禁止在 `onFormSubmitFailed` 或 `Submit.onSubmitFailed` 中调用 `message.error`，因为 API reject 也会进入这些通用失败回调。
+
+## 标准代码骨架
 
-This skill is the working guide for `YssFormily` in this repository.
-Use it when the task involves:
-
-- creating or editing a `YssFormily` / `YFormily` form
-- writing or refactoring a Formily schema
-- implementing add/edit/detail forms with one shared schema
-- building field linkage, reactions, form `effects`, async validation
-- adding custom slot fields such as Monaco, SQL, rich text, custom hints
-- debugging why a form does not submit, does not react, or renders incorrectly
-
-`YssFormily` in this project is a YSS wrapper built on top of the Ant Design Vue ecosystem.
-When reasoning about component props, event names, interaction behavior, and rendered form controls, treat Ant Design Vue as the underlying UI behavior model.
-
-## Source of truth
-
-Read the scenario map first:
-
-1. [references/examples.md](references/examples.md)
-
-If the user asks for a concrete pattern, inspect the closest existing YSS form page or example in the repository and match its local convention.
-
-## Hard rules
-
-### Imports
-
-Business code should import the wrapper component from `@yss-ui/components`.
-Do not build business forms by directly importing Formily UI components from React packages.
-
-Preferred imports:
-
-```ts
-import { YssFormily, YFormily, type ISchema } from "@yss-ui/components";
-import {
-  createForm,
-  onFieldValueChange,
-  onFormSubmit,
-  onFormSubmitFailed,
-} from "@formily/core";
-```
-
-Avoid these imports unless a file already depends on them for a narrow advanced case:
-
-- `@formily/antd`
-- `@formily/antd-v3`
-- direct UI field imports from `@formily/antdv` for ordinary business forms
-
-`YssFormily` already wraps the common Ant Design Vue Formily components and project-specific adapters.
-Its field event behavior should be understood through Ant Design Vue conventions first, then the YSS wrapper conventions.
-
-### Prefer one schema for add, edit, detail
-
-Default approach:
-
-- `mode=0`: create
-- `mode=1`: edit
-- `mode=2`: detail
-
-Do not fork separate edit/detail implementations unless the UI is materially different.
-
-### Use `v-model` as the main value source
+```vue
+<script setup lang="ts">
+import { YFormily, type ISchema } from '@yss-ui/components';
 
-`initial-values` is initialization only.
-For fetched data, editing state, and mode switching, prefer `v-model` or instance `setValues`.
+/** 表单保存回调 Props。 */
+interface SaveFormProps {
+  onSave: (values: Record<string, any>) => Promise<void>;
+}
 
-## Default build pattern
+/** 表单保存回调。 */
+const props = defineProps<SaveFormProps>();
 
-Start with this shape unless the existing page already uses a different local convention:
+/** 校验通过后提交表单数据。 */
+const onSubmit = (values: Record<string, any>) => {
+  return props.onSave(values);
+};
 
-```ts
+/** 基础业务表单 Schema。 */
 const schema: ISchema = {
-  type: "object",
+  type: 'object',
   properties: {
     layout: {
-      type: "void",
-      "x-component": "FormLayout",
-      "x-component-props": {
-        layout: "horizontal",
-        labelWidth: 120,
-      },
+      type: 'void',
+      'x-component': 'FormLayout',
+      'x-component-props': { layout: 'horizontal', labelWidth: 100, labelAlign: 'right' },
       properties: {
         grid: {
-          type: "void",
-          "x-component": "FormGrid",
+          type: 'void',
+          'x-component': 'FormGrid',
+          'x-component-props': { maxColumns: 3, minColumns: 1, minWidth: 260 },
           properties: {
-            fieldName: {
-              type: "string",
-              title: "字段名",
-              "x-decorator": "FormItem",
-              "x-component": "Input",
+            name: {
+              type: 'string',
+              title: '名称',
+              required: true,
+              'x-decorator': 'FormItem',
+              'x-component': 'Input',
+              'x-component-props': { placeholder: '请输入' },
+            },
+            submit: {
+              type: 'void',
+              'x-component': 'Submit',
+              'x-content': '提交',
+              'x-component-props': { onSubmit: '{{ onSubmit }}' },
             },
           },
         },
@@ -101,204 +101,172 @@ const schema: ISchema = {
     },
   },
 };
-```
-
-Interpretation:
-
-- `FormLayout` controls label layout and size
-- `FormGrid` controls responsive columns
-- fields normally use `FormItem`
-
-Do not hand-build layout with ad hoc wrapper divs if `FormLayout`, `FormGrid`, `GroupHeader`, or `AutoButtonGroup` already solve it.
-
-## Choose the right mechanism
-
-Use this decision order:
-
-1. Static field structure and basic validation:
-   put it in `schema`
-2. Visibility, disabled state, or simple dependency:
-   use `x-visible`, `x-disabled`, `x-reactions`
-3. Reusable event handlers or cross-field helper functions:
-   inject through `scope`
-4. Form-wide side effects, submit lifecycle, async orchestration:
-   use `createForm({ effects })`
-5. Rich custom rendering:
-   use `Slot` in edit mode and `detail-*` slots in detail mode
-
-### Event selection
-
-Event names follow the underlying Ant Design Vue component behavior.
-
-- text input: prefer `x-component-props.onUpdate:value`
-- select, radio, switch, date picker: usually `x-component-props.onChange`
-- submit: `Submit.x-component-props.onSubmit`
-
-Do not attach multiple equivalent listeners to the same field unless the existing component requires it.
-
-### `x-reactions` vs `scope` vs `effects`
-
-Use `x-reactions` for declarative field-to-field linkage:
-
-- show/hide
-- disable/enable
-- reset a sibling field
-- update a dependent enum or datasource
-
-Use `scope` for local handlers when the schema needs to call project code:
-
-- remote search
-- custom validation helper
-- helper function reused by multiple fields
-
-Use `effects` for form-level orchestration:
-
-- global submit success or failure behavior
-- multi-field coordination
-- async side effects not tied cleanly to one field
-- analytics or global notification hooks
-
-## Mode and detail view
-
-When `mode=2`, `YssFormily` can render as a `Descriptions`-style detail view.
-
-Default detail rendering already handles:
-
-- `enum` to label
-- `DatePicker` to `YYYY-MM-DD`
-- boolean or `Switch` to “是/否”
-- arrays joined by `、`
-- empty values as `-`
-
-Use `detail-options` to control layout.
-Important constraint from the component doc:
-
-- `responsive` is `true` by default
-- when `responsive=true`, `columns` is ignored
-- if you need a fixed max of two columns, set `maxColumns: 2` or `responsive: false`
-
-### Detail slot naming
-
-For detail mode custom rendering, use:
+</script>
 
-```text
-#detail-<path>
+<template>
+  <YFormily :schema="schema" :scope="{ onSubmit }" />
+</template>
 ```
 
-Replace dots with hyphens.
+### 表单布局基准
 
-Examples:
+- 普通业务表单：`FormLayout { layout: 'horizontal', labelWidth: 120, labelAlign: 'right' }`，`FormGrid { maxColumns: 3, minColumns: 1, minWidth: 260 }`。
+- 抽屉/弹窗表单：长 label 较多时用 `labelWidth: 140`，`FormGrid { maxColumns: 2, minColumns: 1, minWidth: 320 或 360 }`。
+- 查询表单：字段少时用 `labelWidth: 100~120`，`FormGrid { maxColumns: 3 或 4, minColumns: 1, minWidth: 260~360 }`；查询/重置按钮放在表单外部的右下角按钮行。
+- 不要为了复刻宽屏两列布局写 `minColumns: 2`；这会破坏组件库 demo 中默认的响应式收缩行为。
+- 备注、说明、富文本、长输入框等横跨整行字段，在字段 `x-decorator-props` 上设置 `gridSpan`，例如两列表单使用 `gridSpan: 2`。
 
-- `email` -> `#detail-email`
-- `user.email` -> `#detail-user-email`
+### 业务列表查询区固定模板
 
-## Slot strategy
+```typescript
+import { YButton, YCard, YFormily, type ISchema } from '@yss-ui/components';
 
-For custom edit-mode content inside the schema, use:
-
-```ts
-'x-component': 'Slot',
-'x-component-props': { name: 'sql' }
+/** 查询表单 Schema。 */
+const searchSchema: 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: 4, minColumns: 1, minWidth: 260, columnGap: 16, rowGap: 0 },
+          properties: {
+            keyword: {
+              type: 'string',
+              title: '关键字',
+              'x-decorator': 'FormItem',
+              'x-component': 'Input',
+              'x-component-props': { placeholder: '请输入关键字', allowClear: true },
+            },
+          },
+        },
+      },
+    },
+  },
+};
 ```
 
-Then provide:
-
 ```vue
-<template #sql="{ value, onChange }">...</template>
+<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>
 ```
 
-For the same field in detail mode, provide:
-
-```vue
-<template #detail-sql="{ value }">...</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;
+  }
+}
 ```
 
-This is the preferred pattern for:
-
-- Monaco editors
-- SQL or JSON editors
-- rich text or code previews
-- custom helper blocks
-
-## Layout guidance
-
-Use these built-ins before writing custom wrappers:
-
-- `FormLayout`
-- `FormGrid`
-- `GroupHeader`
-- `AutoButtonGroup`
-- `FormCollapse`
-- `FormStep`
-- `ArrayItems`
-
-Recommended habits:
-
-- use `x-decorator-props.gridSpan` for wide fields
-- use `GroupHeader` for section titles instead of ad hoc headings
-- use `AutoButtonGroup` for aligned action areas
-- set shared grid behavior through `grid-defaults` at component usage level
-
-## Instance methods
-
-When page logic needs imperative control, get a component ref and use:
-
-- `getValues`
-- `setValues`
-- `submit`
-- `setFieldState`
-- `form`
+> 只有纯 Formily 提交表单才把按钮放回 schema 内，例如 `AutoButtonGroup -> Submit/Reset`。
 
-Prefer these methods over reaching into internal implementation details.
+### 抽屉/弹窗表单模板
 
-## Working sequence for implementation
-
-When asked to build or refactor a form, follow this sequence:
-
-1. Read the existing page and find current mode, data source, and submit flow.
-2. Read the canonical Formily doc and the most relevant demo.
-3. Design the schema first:
-   fields, layout, sections, buttons.
-4. Add validation and enum handling.
-5. Add simple linkage with `x-visible` / `x-disabled` / `x-reactions`.
-6. Add `scope` handlers or `effects` only where schema alone is insufficient.
-7. If detail mode exists, verify `mode=2` rendering and slot coverage.
-8. Verify submit behavior, especially the `Submit` handler path.
-
-## Common mistakes to avoid
-
-- Using `initial-values` as if it were reactive state
-- Splitting add/edit/detail into separate unrelated schemas without necessity
-- Writing large business logic inline in schema expressions
-- Forgetting that detail-mode slot naming is fixed as `detail-<path>`
-- Expecting `detail-options.columns` to work while `responsive=true`
-- Using custom layout divs where `FormGrid` and `gridSpan` should be used
-- Solving complex form coordination with scattered component events instead of `effects`
-
-## When to open demos
-
-Open the matching demo before writing code for these scenarios:
-
-- dynamic show or hide
-- dynamic disable
-- custom slot
-- group or collapse section
-- effects
-- async validation
-- multi-dependency linkage
-- submit failure handling
-- steps
-- dynamic array
-
-The example index is in:
-[references/examples.md](references/examples.md)
-
-## Output expectation
-
-When using this skill, produce code that is:
+```typescript
+/** 抽屉或弹窗内的编辑表单 Schema。 */
+const formSchema: ISchema = {
+  type: 'object',
+  properties: {
+    layout: {
+      type: 'void',
+      'x-component': 'FormLayout',
+      'x-component-props': { layout: 'horizontal', labelWidth: 140, labelAlign: 'right' },
+      properties: {
+        grid: {
+          type: 'void',
+          'x-component': 'FormGrid',
+          'x-component-props': { maxColumns: 2, minColumns: 1, minWidth: 360, columnGap: 24, rowGap: 16 },
+          properties: {
+            orgName: {
+              type: 'string',
+              title: '机构名称',
+              required: true,
+              'x-decorator': 'FormItem',
+              'x-component': 'Input',
+              'x-component-props': { placeholder: '请输入机构名称' },
+            },
+            remark: {
+              type: 'string',
+              title: '备注',
+              'x-decorator': 'FormItem',
+              'x-decorator-props': { gridSpan: 2 },
+              'x-component': 'Input.TextArea',
+              'x-component-props': { placeholder: '请输入备注', rows: 4 },
+            },
+          },
+        },
+      },
+    },
+  },
+};
+```
 
-- schema-first
-- mode-aware
-- concise in business pages
-- aligned with `@yss-ui/components`
-- anchored to existing YSS docs and demos instead of inventing a parallel pattern
+## 关联 skill
+
+- 基础表单：`../formily-foundation/SKILL.md`
+- 联动副作用：`../formily-linkage-effects/SKILL.md`
+- 模式与详情插槽：`../formily-mode-slot-detail/SKILL.md`
+- 分步流程：`../formily-step-flow/SKILL.md`
+- 完整示例：`../formily-foundation/references/examples.md`
+
+## 交付检查清单
+
+- [ ] 使用 `YFormily`，模板名和 import 一致。
+- [ ] 只使用文档和源码已公开的 Props/实例方法，未出现 `show-button-group`、`detail-as` 等旧式或虚构 API。
+- [ ] 未生成旧式详情开关 prop。
+- [ ] 未导入业务层 `@formily/antdv` UI 组件。
+- [ ] Schema 层级完整：`FormLayout -> FormGrid -> 字段`，`Submit.onSubmit` 可触发校验。
+- [ ] 所有横向表单已设置固定 `labelWidth` 和 `labelAlign: 'right'`。
+- [ ] `FormGrid` 保持响应式，未用 `minColumns: maxColumns` 固定列数。
+- [ ] 业务列表查询区的查询/重置按钮在外部 `.xxx__search-actions`，按钮行独占下一行并右对齐；缩窄后不会贴在第一行字段旁。
+- [ ] 抽屉/弹窗表单 label 宽度统一、右对齐，窄屏可响应式换列，长字段已占满整行。
+- [ ] 复杂联动已选择表达式、`x-reactions`、`scope` 或 `effects` 中合适的一种。
+- [ ] API 失败仅由 `mutator.ts` 统一提示，hook 的 `else`/`catch` 未重复 `message.error`。
+
+## 失败兜底策略
+
+- 字段不显示时，先检查 `FormLayout -> FormGrid -> 字段` 层级。
+- 提交不触发时，先检查 `Submit.x-component-props.onSubmit` 或外部 `formRef.submit()`。
+- 查看态显示异常时，先检查 `mode=2`、`detail-options` 和 `detail-<path>` 插槽命名。
+- API 调用被 reject 时，让错误继续中断当前流程；只在 `finally` 恢复 loading，不在业务 hook 重复提示。

package/template/.cursor/skills/yss-frontend-scaffold-generator/SKILL.md

@@ -31,7 +31,7 @@ branch: template
 ## Workflow
 
 1. 确认当前任务已经通过 Harness 入口分诊，且实现位置已记录在 proposal、design、build entry review、实施计划或实现路由记录中。
-2. 确认目标是外部实现仓库；只有用户明确选择时才输出到 Harness 仓库的 `apps/frontend/<project>/`。`apps/frontend/` 只能作为项目容器，`app/frontend/`、`app/backend/` 及其子路径禁止作为输出位置。
+2. 确认目标是外部实现仓库；只有用户明确选择时才输出到 Harness 仓库的 `apps/frontend/<project>/`。`apps/frontend/` 只能作为项目容器，`app/frontend/`、`app/backend/` 及其子路径禁止作为输出位置。`git-submodule` 只能在已初始化且附加分支的子仓工作树生成；空 gitlink、detached HEAD、`--force` 覆盖挂载点不得当成普通目录。
 3. 只读检查模板分支是否可访问：`git ls-remote --heads <repo> template`。
 4. 需要生成工程时，克隆或复制模板到用户确认的目标位置；不得默认写入 Harness 仓库。
 5. 替换应用名、微应用名、路由、`micro-config.json`、环境变量和 README 中的模板占位。
@@ -63,7 +63,7 @@ packages/package.json
 - 不修改模板既有的代码生成配置，也不把客户端生成加入 CI。
 - 不得把 `apps/frontend/` 容器根登记为项目根；Harness 内每个前端项目必须有独立的 `apps/frontend/<project>/` 路径。
 - 不把模板示例页面当作业务功能交付。
-- 生成后仍需使用 `yss-page-module-development`、`yss-components`、`api-integration` 等专项 skill 实现业务页面。
+- 生成后仍需使用 `yss-page-module-development`、`yss-components`、`yss-api-integration` 等专项 skill 实现业务页面。
 
 ## Output
 

package/template/.cursor/skills/yss-hook/SKILL.md

@@ -13,7 +13,7 @@ description: Use when YSS Vue 页面涉及 vue-hooks-plus/useRequest、分页、
 - Vue Hooks Plus `useRequest`: `https://inhiblabcore.github.io/vue-hooks-plus/zh/hooks/useRequest/quick-start`
 - Local reference index: `references/frontend-docs.md`
 
-本技能负责请求执行、分页/筛选参数、选择状态、响应映射和页面级调度。接口导入与 Orval mutator 使用 `api-integration`；布局、组件与交互呈现使用 `yss-components`；高度计算分别使用 `yss-use-table-height` 或 `yss-use-tree-height`。
+本技能负责请求执行、分页/筛选参数、选择状态、响应映射和页面级调度。接口导入与 Orval mutator 使用 `yss-api-integration`；布局、组件与交互呈现使用 `yss-components`；高度计算分别使用 `yss-use-table-height` 或 `yss-use-tree-height`。
 
 官方 `@yss-ui/hooks` 当前公开 `useFullscreen`、`useTreeHeight`、`useTableHeight`、`useLoading`、`usePollingTask` 与 `useUrlState`。`useRequest`、防抖、缓存或重试不属于这套公开 YSS Hooks 契约。仅当项目已批准 `vue-hooks-plus` 及其具体版本时，才可使用第 3 节的 `useRequest`；不得把它命名或包装成 YSS 官方 API。
 

package/template/.cursor/skills/yss-openapi-governance/SKILL.md

@@ -30,7 +30,7 @@ YSS DTO 的可复用 HTTP/JSON 映射由 `.agents/skills/yss-dto/references/open
 不使用本 skill 来替代：
 
 - `yss-openapi-draft-review`：独立、fail-closed 的语义评审与 P0 追踪。
-- `api-integration`：消费已派生的 JSON，并在目标前端实现仓库中接入既有客户端生成流程。
+- `yss-api-integration`：消费已派生的 JSON，并在目标前端实现仓库中接入既有客户端生成流程。
 - `to-tickets`：在 Freeze 后正式化垂直切片。
 
 ## 受控工具链
@@ -77,7 +77,7 @@ pnpm exec redocly bundle \
    - 记录 YAML SHA-256、JSON SHA-256、OAS 版本、Redocly CLI 版本与 lockfile 引用、完整命令、metafile、`$ref` 例外以及结果。
 
 5. **交给下游前端**
-   - 仅当 Freeze、JSON 派生记录和 JSON 校验均通过时，才把派生 JSON 交给 `api-integration` 与目标前端实现仓库。
+   - 仅当 Freeze、JSON 派生记录和 JSON 校验均通过时，才把派生 JSON 交给 `yss-api-integration` 与目标前端实现仓库。
    - JSON 的治理产物固定为 `docs/.scratch/<feature>/api/<feature>.json`。跨仓库时只能由批准的 Cross-repo 子合同或项目脚本将同一字节内容物化为 `<frontend>/openapi/openapi.json`，并记录两端相同的 SHA-256 与交接路径。
    - 本模板不读取、修改或验证目标前端项目的客户端生成配置，不执行客户端生成，也不把生成动作加入 CI；目标前端项目在需要时手动运行其既有代码生成命令。
    - 接口调整回写 YAML，而不是编辑 JSON 或生成的 TypeScript。

package/template/.cursor/skills/yss-page-module-development/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yss-page-module-development
-description: Guide AI to create standardized Vue 3 business page modules for YSS micro-applications, including directory layout, hook extraction, table/tree height hooks, YssFormily query areas, YTable pages, and left-tree-right-content shells.
+description: 指导创建标准 Vue 3 YSS 业务页面模块，覆盖 CRUD、列表、表单、详情、左树右表、组件选型、Orval 接口、主题 Token、原型还原和交付验证。
 ---
 
 # YSS Page Module Development
@@ -20,7 +20,7 @@ This skill orchestrates page/module creation. Load narrower skills only when the
 
 - `yss-components` for layout, YTable/YTree/YssFormily/YSplitPane component specifics.
 - `yss-hook` for request, pagination, parameter, and mapping logic.
-- `api-integration` for Orval-generated APIs and submit/list/detail flows.
+- `yss-api-integration` for Orval-generated APIs and submit/list/detail flows.
 - `yss-use-table-height` and `yss-use-tree-height` for height calculation.
 - `yss-formily` for detailed schema behavior.
 
@@ -120,6 +120,16 @@ Use `useTableHeight` and `useTreeHeight` when the page needs available-height ca
 - keep action handlers small and explicit
 - preserve existing route, menu, and permission conventions in the repo
 
+## YSS business page contract
+
+- 页面实现前先按 `component-selection-imports` 判定真实导出；已封装能力优先从 `@yss-ui/components`、`@yss-ui/hooks`、`@yss-ui/utils` 导入。
+- 标准列表使用 `YTable` 的真实 `data`、`columns`、`loading`、`pageable`、`v-model:pagination` 和 `@page-change`；主操作放在 `#toolbar-right`，只有确实需要列设置时才启用 `toolbar-config.custom`。
+- 查询区使用 `YFormily` 渲染字段，查询/重置按钮位于表单外部并在窄屏下保持右下对齐；表单、表格、树和导出细节分别加载 `yss-formily`、`ytable-usage`、`ytree-usage` 和 `file-export-download`。
+- 页面有原型或旧页面参考时先读取 `prototype-page-acceptance`，建立视觉、状态、交互和响应式验收清单；交付时必须逐项对照。
+- 页面和组件的颜色、状态色及暗色模式遵循 `theme-token-usage`，不得硬编码品牌色。
+- Orval API 必须使用当前生成导出和 DTO；错误由 mutator 统一处理，业务 Hook 不重复判断 `success` 或重复提示错误。
+- 列表/树高度按实际分页、工具栏和搜索状态选择 `yss-use-table-height` / `yss-use-tree-height`，不得用固定魔法高度替代。
+
 ## Deliverables
 
 When implementing a page module, the result should usually include:

package/template/.cursor/skills/yss-page-module-development/references/component-map.md

@@ -0,0 +1,34 @@
+# YSS UI 组件来源速查
+
+此文件用于业务页面生成前的组件选型。优先使用 YSS UI 已封装组件；未封装能力再从 `ant-design-vue` 导入。
+
+## 从 `@yss-ui/components` 导入
+
+| 组件 | 适用场景 | 备注 |
+| --- | --- | --- |
+| `YButton` | 操作按钮、权限按钮 | 支持 `permissionCode`、`fallback`、`modifiers`；优先替代 `a-button`。 |
+| `YCard` | 页面容器、区域容器 | 支持 `title`、`extra`、`padding`、Meta 插槽。 |
+| `YTable` | 标准列表、分页、操作列、筛选、字典翻译 | 继承 vxe-table 能力，分页用 AntDV Pagination。 |
+| `YEditTable` | 可编辑表格 | 需要底部添加按钮高度时配合 `yss-use-table-height`。 |
+| `YTree` | 左侧分类树、组织树、搜索过滤树 | 节点操作用 `getNodeActions`。 |
+| `YSplitPane` | 左树右表、可拖拽分割布局 | 左右或上下区域分割。 |
+| `YFormily` | JSON Schema 表单、新增/编辑/查看 | 默认表单方案。 |
+| `YssFormily` | 表单兼容导出 | 仅用于维护历史代码；新代码统一使用 `YFormily`。 |
+| `YConditionBuilder` | 条件构建器、规则配置 | 常用于数据质量、筛选条件配置。 |
+| `YFileImport` | 文件导入 | Formily schema 内也可用 `YFileImport`。 |
+| `YMonaco` | 代码编辑器 | SQL、JSON、脚本编辑。 |
+| `YMonacoDiff` | 代码 Diff | 变更对比场景。 |
+| `YCron` | Cron 表达式编辑 | 定时任务配置。 |
+| `YMonthCalendar` | 月度日历、节假日和连续区间 | 支持单元格、右键菜单和头部插槽。 |
+| `YEcharts` | 图表展示 | 业务图表封装。 |
+| `YSheet` | 协同/类 Excel 表格 | 复杂表格编辑。 |
+| `AuthorityDropdown` | 权限相关下拉 | 可从 `@yss-ui/components` 导入。 |
+
+## 回退到 `ant-design-vue`
+
+未由 `@yss-ui/components` 导出的组件直接从 `ant-design-vue` 导入，不臆造 Y 前缀。
+
+## 禁止规则
+
+- 不要编造未导出的 Y 前缀组件。
+- 业务层不要从 `@formily/antdv` 导入 UI 适配组件。