create-yss-spec 2.2.0 → 2.2.2

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

@@ -0,0 +1,167 @@
+---
+name: formily-linkage-effects
+description: 指导 YFormily 字段联动与表单级副作用；当实现动态显隐、禁用、级联选项、scope 事件、x-reactions、effects、异步联动或客户端校验失败兜底时使用。
+---
+
+# Formily Linkage Effects Skill
+
+## 触发条件
+
+- 需要字段联动（A 影响 B）、动态显隐/禁用、级联下拉。
+- 需要 `scope`、`x-reactions` 或 `createForm + effects`。
+- 需要处理异步选项竞态、旧值清理或 Formily 校验失败反馈。
+
+## 不适用场景
+
+- 纯基础字段与提交：使用 `../formily-foundation/SKILL.md`。
+- 详情态渲染和 mode 切换：使用 `../formily-mode-slot-detail/SKILL.md`。
+- 分步流程：使用 `../formily-step-flow/SKILL.md`。
+
+## 文档检索
+
+1. 当前会话可用 yss-ui MCP 时，先用 `get_component_docs` 查询 `YFormily` 的 `scope`/Schema/表单实例边界；实现字段联动、多字段反应或 effects 时，再用 `get_demo` 获取 `formily/linkage`、`formily/linkage-multi`、`formily/effects` 等官方 Demo。
+2. MCP 查询未命中时先用 `search_docs/list_components` 校正名称；MCP 不可用、调用失败或校正后仍无结果时，才读取最新 `llms-full.txt`。若文档与当前项目依赖版本不一致，用当前源码和导出核验。
+
+## 硬约束（禁止/必须）
+
+- 按复杂度选择机制：表达式 < `x-reactions` < `scope` < `effects`，避免同一联动在多处重复实现。
+- 仅显隐/禁用优先使用 `$values` 表达式；当前字段依赖其他字段时优先 `x-reactions`；跨字段事件用 `scope`；表单级监听才用 `effects`。
+- `effects` 需要首屏即生效时，同时注册 `onFieldInit` 和 `onFieldValueChange`，禁止只监听变化导致初始状态错误。
+- 修改其他字段状态时使用 `form.setFieldState`；级联选项变化后，只有旧值不在新选项中时才清空，避免初始化误删合法回填值。
+- 异步联动必须处理空依赖、loading、请求竞态与卸载；旧请求不得覆盖新选择。
+- 客户端校验提示使用 `onFormSubmitValidateFailed`。禁止在 `onFormSubmitFailed` 或 `Submit.onSubmitFailed` 中调用 `message.error`：Formily 会把 `onSubmit` 中的 API reject 也交给这些通用失败回调，导致与 `mutator.ts` 重复提示。
+- 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>
+```
+
+## 交付检查清单
+
+- [ ] 已说明为何选择表达式、`x-reactions`、`scope` 或 `effects`。
+- [ ] 首屏需要联动时同时覆盖初始化与变更事件。
+- [ ] 字段切换后旧值、选项和 loading 状态正确，异步请求有竞态保护。
+- [ ] Formily 客户端校验提示集中在 `onFormSubmitValidateFailed`，未用通用 `onFormSubmitFailed`/`Submit.onSubmitFailed` 处理 API reject。
+- [ ] API 错误只由 `mutator.ts` 提示，业务 `else`/`catch` 未重复 `message.error`。
+- [ ] 无 DOM hack、无无意义 `setTimeout`，未把分步逻辑塞入本 skill。
+
+## 失败兜底策略
+
+- `x-reactions` 失效时先校验字段路径和实际 schema 层级，再决定是否升级为 `setFieldState`。
+- 首屏状态错误时检查是否遗漏 `onFieldInit`；回填值丢失时检查是否无条件清空了级联字段。
+- 异步结果乱序时使用请求序号或 `AbortController`，只接受最后一次请求结果。
+- API 调用 reject 时只恢复 loading 或回滚局部状态，不重复弹出错误提示。

package/template/.agents/skills/formily-mode-slot-detail/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: formily-mode-slot-detail
+description: 指导 YFormily 新增、编辑、查看三态与插槽渲染；当配置 mode 0/1/2、查看态只读、详情页 Descriptions 展示、detail-options、Schema Slot 或详情字段插槽时使用。
+---
+
+# Formily Mode Slot Detail Skill
+
+## 触发条件
+
+- 需要 `mode: 0/1/2` 的新增、编辑、查看三态切换。
+- 查看态需要 Descriptions 响应式渲染或 `detail-*` 字段插槽。
+- 同一字段在编辑态使用 Schema Slot、查看态使用 detail slot。
+
+## 不适用场景
+
+- 基础表单骨架：使用 `../formily-foundation/SKILL.md`。
+- 复杂联动与副作用：使用 `../formily-linkage-effects/SKILL.md`。
+- 分步流程：使用 `../formily-step-flow/SKILL.md`。
+
+## 文档检索
+
+1. 当前会话可用 yss-ui MCP 时，先用 `get_component_docs` 查询 `YFormily` 的 `mode`、`detail-options`、Slots 和 Methods；实现三态、详情插槽或 Schema Slot 时，再用 `get_demo` 获取 `formily/modes`、`formily/group`、`formily/slot` 等官方 Demo。
+2. MCP 查询未命中时先用 `search_docs/list_components` 校正名称；MCP 不可用、调用失败或校正后仍无结果时，才读取最新 `llms-full.txt`。若文档与当前项目依赖版本不一致，用当前源码和导出核验。
+
+## 硬约束（禁止/必须）
+
+- mode 语义固定：`0=新增`、`1=编辑`、`2=查看`；默认值为 `0`。
+- `mode=2` 直接进入 Descriptions 查看态并强制 readPretty；源码没有 `detail-as` 等额外详情开关，禁止生成旧式 prop。
+- 描述列表配置使用 `:detail-options`。默认 `responsive=true`，此时 `columns` 被忽略；响应式列数使用 `maxColumns`、`minColumns`、`minWidth`，固定列数才组合 `responsive: false` 与 `columns`。
+- 查看态插槽命名固定为 `#detail-<path>`，字段路径中的 `.` 替换为 `-`；作用域为 `{ value, item, values }`。
+- 编辑态插槽使用 `x-component: 'Slot'` 与 `x-component-props.name`；`value/onChange` 默认提供，仅在需要 `field` 或整表数据时配置 `params`。
+- 运行时切换 mode 时加 `:key="mode"`，确保当前实现重新创建 form/schema 上下文并避免状态残留。
+- 查看态不会发送 `update:modelValue`；回填优先在渲染前准备好 `v-model`/`initial-values`，或通过已公开的 `setValues` 更新。
+- 只使用公开实例方法：`getValues`、`setValues`、`submit`、`setFieldState`、`toggle/expand/collapse`；禁止编造 `validate/reset/clearValidate`。
+- 加载详情的 Orval API 错误已由 `mutator.ts` 统一 `message.error` 并 reject，业务 `else`/`catch` 禁止重复提示。
+- 分步需求默认走 `formily-step-flow`，不在本 skill 中给 `FormStep` 默认方案。
+
+## 标准代码骨架
+
+```vue
+<script setup lang="ts">
+import { YMonaco, YFormily, type ISchema } from '@yss-ui/components';
+import { ref } from 'vue';
+
+/** YFormily 业务模式。 */
+type FormMode = 0 | 1 | 2;
+
+/** 当前表单模式。 */
+const mode = ref<FormMode>(0);
+
+/** 编辑和查看回填值。 */
+const initialValues = {
+  user: { email: 'user@example.com' },
+  sql: 'select * from users',
+};
+
+/** 编辑与详情共用的 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: {
+            user: {
+              type: 'object',
+              properties: {
+                email: {
+                  type: 'string',
+                  title: '邮箱',
+                  'x-decorator': 'FormItem',
+                  'x-component': 'Input',
+                },
+              },
+            },
+            sql: {
+              type: 'string',
+              title: 'SQL',
+              'x-decorator': 'FormItem',
+              'x-decorator-props': { gridSpan: 2 },
+              'x-component': 'Slot',
+              'x-component-props': { name: 'sql' },
+            },
+          },
+        },
+      },
+    },
+  },
+};
+</script>
+
+<template>
+  <YFormily
+    :key="mode"
+    :schema="schema"
+    :initial-values="initialValues"
+    :mode="mode"
+    :detail-options="{ bordered: true, maxColumns: 3, minColumns: 1, minWidth: 260 }"
+  >
+    <template #sql="{ value, onChange }">
+      <YMonaco :model-value="value" language="sql" @change="onChange" />
+    </template>
+
+    <template #detail-user-email="{ value }">
+      <a :href="`mailto:${value}`">{{ value }}</a>
+    </template>
+
+    <template #detail-sql="{ value }">
+      <YMonaco :model-value="value" language="sql" readonly />
+    </template>
+  </YFormily>
+</template>
+```
+
+## 交付检查清单
+
+- [ ] mode 语义和默认值正确，运行时切换配置了 `:key="mode"`。
+- [ ] 未生成 `detail-as`、旧式详情开关或虚构实例方法。
+- [ ] `detail-options` 已区分响应式 `maxColumns` 与固定列 `columns`。
+- [ ] 查看态插槽路径映射正确，作用域只使用 `{ value, item, values }`。
+- [ ] 编辑 Slot 名称与模板插槽一致，只在需要时声明 `params`。
+- [ ] 查看回填在进入 `mode=2` 前准备完毕，未依赖查看态 v-model 回写。
+- [ ] API 失败只由 `mutator.ts` 统一提示，业务 `else`/`catch` 未重复 `message.error`。
+- [ ] 无分步 `FormStep` 默认实现。
+
+## 失败兜底策略
+
+- 查看态插槽不生效时，先按详情收集后的数据路径核对 `detail-<path>`，不要把 `FormLayout/FormGrid` 容器名拼入路径。
+- 编辑态插槽不生效时，核对 `x-component-props.name` 与模板名；需要整表值时再加入 `params: ['$values']`。
+- 模式切换错乱时先确认 `:key="mode"`，再检查回填数据是否在新实例挂载前准备好。
+- API 调用 reject 时只恢复 loading 或保留原数据，不重复弹出错误提示。

package/template/.agents/skills/formily-step-flow/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: formily-step-flow
+description: 指导 YSS UI 分步表单与流程录入；当需要 Ant Design Vue Steps、多 YFormily 独立校验、跨步数据保留、确认预览或最终聚合提交时使用。
+---
+
+# Formily Step Flow Skill
+
+## 触发条件
+
+- 需求是分步表单（Step Form）或流程化录入。
+- 每一步需要独立校验与前进/后退控制。
+- 需要跨步数据聚合、确认预览和最终提交编排。
+
+## 不适用场景
+
+- 普通单页表单：使用 `../formily-foundation/SKILL.md`。
+- 仅字段联动：使用 `../formily-linkage-effects/SKILL.md`。
+- 仅查看态插槽：使用 `../formily-mode-slot-detail/SKILL.md`。
+
+## 文档检索
+
+1. 当前会话可用 yss-ui MCP 时，先用 `get_component_docs` 查询 `YFormily` 的 `submit()`、`mode`、`v-model` 和回填边界，再用 `get_demo` 获取 `formily/steps` 官方 Demo；`Steps` 的属性以当前 `ant-design-vue` 依赖和类型为准。
+2. MCP 查询未命中时先用 `search_docs/list_components` 校正名称；MCP 不可用、调用失败或校正后仍无结果时，才读取最新 `llms-full.txt`。若文档与当前项目依赖版本不一致，用当前源码和导出核验。
+
+## 硬约束（禁止/必须）
+
+- 默认方案使用 `ant-design-vue` 的 `Steps` + 多 schema / 多 `YFormily`；组件库没有 `YSteps`，禁止编造。
+- 业务层禁止把 `@formily/antdv FormStep` 作为默认方案；只有维护旧代码或用户明确指定时才可使用。
+- 每次前进前对当前 YFormily 实例执行 `submit()`；该方法校验成功后 resolve，失败时 reject，不返回布尔值，禁止写 `ok !== false`。
+- 每步使用独立 `v-model` 数据，并以单一 `reactive` 对象聚合；`v-if` 卸载实例后仍由该数据源保留回填值。
+- 确认步骤用前面步骤的聚合数据作为 `initial-values`/`v-model`，禁止绑定一个空的第三步对象导致详情无数据。
+- 最终 API 提交只聚合业务步骤，禁止把纯确认步骤当作新数据源。
+- Orval API 的网络错误及 `success === false` 业务错误已由 `mutator.ts` 统一 `message.error` 并 reject；最终提交的 `else`/`catch` 禁止重复提示，loading 放在 `finally` 恢复。
+
+## 标准代码骨架
+
+```vue
+<script setup lang="ts">
+import { YButton, YFormily, type ISchema } from '@yss-ui/components';
+import { Steps as ASteps } from 'ant-design-vue';
+import { computed, reactive, ref } from 'vue';
+
+/** YFormily 对外提交能力。 */
+interface YssFormilyExpose {
+  submit: () => Promise<Record<string, any>>;
+}
+
+/** 分步表单数据。 */
+interface StepFormData {
+  step1: { name: string };
+  step2: { level: string };
+}
+
+/** 分步表单提交回调 Props。 */
+interface StepFlowProps {
+  onSubmit: (values: StepFormData) => Promise<void>;
+}
+
+/** 分步表单提交回调。 */
+const props = defineProps<StepFlowProps>();
+/** 当前步骤，从 0 开始。 */
+const currentStep = ref(0);
+/** 最终提交状态。 */
+const submitting = ref(false);
+/** 第一步表单实例。 */
+const step1Ref = ref<YssFormilyExpose>();
+/** 第二步表单实例。 */
+const step2Ref = ref<YssFormilyExpose>();
+/** 步骤导航配置。 */
+const stepItems = [{ title: '基础信息' }, { title: '策略配置' }, { title: '确认提交' }];
+/** 跨步唯一数据源。 */
+const formData = reactive<StepFormData>({
+  step1: { name: '' },
+  step2: { level: 'normal' },
+});
+
+/** 创建符合业务三层布局约定的步骤 Schema。 */
+const createStepSchema = (properties: Record<string, ISchema>): 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,
+        },
+      },
+    },
+  },
+});
+
+/** 第一步 Schema。 */
+const step1Schema = createStepSchema({
+  name: {
+    type: 'string',
+    title: '任务名称',
+    required: true,
+    'x-decorator': 'FormItem',
+    'x-component': 'Input',
+  },
+});
+/** 第二步 Schema。 */
+const step2Schema = createStepSchema({
+  level: {
+    type: 'string',
+    title: '策略等级',
+    required: true,
+    enum: [
+      { label: '普通', value: 'normal' },
+      { label: '严格', value: 'strict' },
+    ],
+    'x-decorator': 'FormItem',
+    'x-component': 'Select',
+  },
+});
+/** 确认步骤 Schema。 */
+const confirmSchema = createStepSchema({
+  name: { type: 'string', title: '任务名称', 'x-decorator': 'FormItem', 'x-component': 'Input' },
+  level: { type: 'string', title: '策略等级', 'x-decorator': 'FormItem', 'x-component': 'Input' },
+});
+/** 确认步骤展示数据。 */
+const confirmValues = computed(() => ({ name: formData.step1.name, level: formData.step2.level }));
+
+/** 校验当前步骤，成功后前进。 */
+const next = async () => {
+  const currentRef = currentStep.value === 0 ? step1Ref.value : step2Ref.value;
+  if (!currentRef) return;
+  try {
+    await currentRef.submit();
+    currentStep.value += 1;
+  } catch {
+    return;
+  }
+};
+
+/** 返回上一步。 */
+const back = () => {
+  currentStep.value = Math.max(0, currentStep.value - 1);
+};
+
+/** 提交全部步骤数据。 */
+const submitAll = async () => {
+  submitting.value = true;
+  try {
+    await props.onSubmit({ step1: { ...formData.step1 }, step2: { ...formData.step2 } });
+  } finally {
+    submitting.value = false;
+  }
+};
+</script>
+
+<template>
+  <ASteps :current="currentStep" :items="stepItems" />
+
+  <YFormily v-if="currentStep === 0" ref="step1Ref" v-model="formData.step1" :schema="step1Schema" />
+  <YFormily v-else-if="currentStep === 1" ref="step2Ref" v-model="formData.step2" :schema="step2Schema" />
+  <YFormily
+    v-else
+    :schema="confirmSchema"
+    :initial-values="confirmValues"
+    :mode="2"
+    :detail-options="{ bordered: true, maxColumns: 2, minColumns: 1, minWidth: 320 }"
+  />
+
+  <YButton :disabled="currentStep === 0" @click="back">上一步</YButton>
+  <YButton v-if="currentStep < 2" type="primary" @click="next">下一步</YButton>
+  <YButton v-else type="primary" :loading="submitting" @click="submitAll">提交</YButton>
+</template>
+```
+
+复杂页面把 schema、类型与步骤 hook 分别拆到 `constant.ts`、`hooks/useStepFlow.ts`，保持 `index.vue` 在 150 行以内。
+
+## 交付检查清单
+
+- [ ] 使用 `ASteps + 多 YFormily`，组件来源明确且未编造 `YSteps`。
+- [ ] 每步前进前 await 当前实例 `submit()`，校验 reject 时不会前进。
+- [ ] 未使用 `ok !== false` 判断 `submit()` 结果。
+- [ ] 步骤切换后数据可保留和回显，确认页直接读取前序聚合数据。
+- [ ] 最终提交只聚合真实业务步骤，未把确认页空对象混入 payload。
+- [ ] API 失败只由 `mutator.ts` 统一提示，业务 `else`/`catch` 未重复 `message.error`。
+- [ ] 业务层未使用 `@formily/antdv FormStep` 作为默认实现。
+
+## 失败兜底策略
+
+- 下一步无校验时确认 ref 指向当前已挂载实例，并直接观察 `submit()` 是否 reject。
+- 状态串联错误时先收敛为单一 `reactive` 数据源，再检查每步 `v-model` 路径。
+- 确认页为空时检查是否错误绑定了独立 `step3`，应改为前序数据的 `computed` 聚合。
+- API 调用 reject 时只在 `finally` 恢复 loading，不重复弹出错误提示。
+- 步骤过多或主组件超过 150 行时，按阶段拆子组件和 `useStepXxx` hook。

package/template/.agents/skills/frontend-commit/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: frontend-commit
+description: 分析并提交 Vue、React、TypeScript、JavaScript、Vite、微前端和前端 monorepo 项目的 Git 改动；当用户要求生成 commit message、检查提交规范、拆分原子提交、暂存并执行 git commit，或修复 commitlint 与 commit-msg hook 拒绝时使用。读取仓库实际规则和 diff，选择业务 scope，生成英文 type/scope 与中文标题和正文，并安全验证提交。
+---
+
+# 前端规范提交
+
+## 触发条件
+
+- 用户要求为前端项目生成 commit message、检查提交规范或执行 `git commit`。
+- 需要将混合改动拆分为原子提交，或评估当前暂存区是否可以安全提交。
+- commitlint、`commit-msg` 或 `pre-commit` hook 拒绝提交，需要按规则修复。
+- 适用于 Vue、React、TypeScript、JavaScript、Vite、微前端和前端 monorepo 仓库。
+
+## 不适用场景
+
+- yss-ui 组件库仓库自身的提交与发版：使用 `../commit-linting/SKILL.md`。
+- Java、Spring Boot、Maven、Gradle 后端仓库：使用 `../java-backend-commit/SKILL.md`。
+- 仅请求代码实现，不涉及提交信息或 `git commit` 操作。
+- 无代码改动，或改动内容与提交请求不匹配。
+- 合并提交、发布提交和自动依赖机器人提交：遵循仓库专用流程，不套用本技能的常规消息模板。
+
+## 硬约束（禁止/必须）
+
+- 必须把仓库规则视为最高优先级：依次遵循 `AGENTS.md`、`CONTRIBUTING.md`、Git hooks、解析后的 commitlint 配置、本地配置和近期历史；通用规则只作回退。
+- 只在用户明确要求提交时执行暂存和 `git commit`；若仅要求提交信息或审查，只输出候选消息与依据。
+- 必须保留用户和他人的既有改动。禁止默认使用 `git add -A`、`git add .`、`git commit -a`、`--no-verify`，也不要自动 amend、rebase、push 或改写已发布历史。
+- 提交必须是单一逻辑变更。不要用提交信息掩盖混杂的功能、修复、格式化或临时文件。
+- 遇到密钥、令牌、私钥、证书、`.env` 实值、账号数据或意外大文件时停止提交并报告具体路径，不要在输出中泄露内容。
+- 已有暂存内容视为用户选择，除非用户授权，不要擅自取消暂存或混入其他文件。
+- `fixup!` 只用于用户明确要求的评审或 autosquash 工作流，不能作为最终历史的默认提交。
+- revert 优先使用 Git 生成的回滚信息并保留被回滚 SHA，再根据仓库规范校验；不要把普通反向修改伪装成 revert。
+
+## 工作流
+
+### 1. 建立仓库契约
+
+1. 确认仓库根目录、当前分支和工作树状态。
+2. 搜索并读取仓库级说明、贡献指南、提交模板、commitlint 配置和 `commit-msg`、`pre-commit` hooks。
+3. 检测 `package.json`、lockfile、workspace 配置和前端应用或包边界。
+4. 如果仓库使用 commitlint，优先使用本地依赖按包管理器读取解析后的配置，例如 `pnpm exec commitlint --print-config json`；不要为了校验联网安装依赖。
+5. 查看相关路径近期的非 merge 提交，了解仓库已经形成的 scope 和语言习惯，但不要复制历史中的明显错误。
+
+### 2. 审查真实改动
+
+至少检查：
+
+```bash
+git status --short --branch
+git diff --cached --name-status
+git diff --cached
+git diff --name-status
+git diff
+git ls-files --others --exclude-standard
+```
+
+- 同时理解暂存区、未暂存区和未跟踪文件；不要只依据文件名生成消息。
+- 将改动按用户可理解的行为和因果关系分组。功能实现、配套测试和为该功能必需的最小配置可以属于同一原子提交。
+- lockfile 必须与对应 manifest 一起提交。只提交项目本来就跟踪且由本次意图产生的生成代码；排除构建产物、缓存和临时文件。
+- 若无改动、改动与请求不符、多个逻辑变更无法安全拆分，先说明并停止。需要逐行拆分同一文件时，不要靠猜测改写暂存区。
+
+### 3. 选择 type、scope 与正文
+
+先读取 `./references/scope-and-examples.md`，再按「标准代码骨架」的格式生成。
+
+- type 默认从 `feat/fix/docs/style/refactor/perf/test/chore/revert/build/ci` 中选择，但仓库枚举优先。
+- scope 优先级为：仓库枚举 → monorepo 包或应用 → 业务模块 → 共享能力。使用小写 kebab-case；不要机械地以 `views`、`hooks` 或文件名作为 scope。
+- 标题使用英文 type/scope、ASCII `:` 和中文摘要；描述行为或价值，不写“修改文件”“更新代码”或单个文件名。
+- 默认将完整 header 控制在 72 个字符内；仓库存在更严格限制时服从仓库。标题末尾不加句号，不用 emoji 或全角冒号。
+- 简单单文件变更可以没有 body；多文件、非显然修复、重要功能或行为变化使用 body 解释做了什么、为什么以及如何验证。
+- 仅对真实不兼容变更使用 `!` 和 `BREAKING CHANGE:`；仅在已知编号或仓库要求时加入工单、DCO、`Signed-off-by` 等 footer，禁止编造。
+
+### 4. 验证并提交
+
+1. 根据变更范围运行仓库已有的最小充分检查，例如相关单元测试、类型检查、lint 和构建检查；优先使用仓库脚本与当前包管理器。
+2. 通过 stdin 校验完整候选消息，而不只校验 header。使用仓库本地 commitlint 命令；退出码为 0 才继续。
+3. 仅暂存属于当前原子提交的明确路径或安全 hunks，再重新检查 `git diff --cached --check`、`--name-status` 和完整 staged diff。
+4. 执行正常 `git commit`，允许 hooks 运行。
+5. hook 若格式化或修改文件，重新检查 staged 与 working tree，确认实际提交内容没有漂移。
+6. 提交成功后检查 `git show --stat --oneline --decorate HEAD` 和 `git status --short`，向用户报告 commit hash、消息、已运行检查以及剩余未提交改动。
+
+## 标准代码骨架
+
+```text
+type(scope)!: 中文行为摘要
+
+- 说明关键行为或原因
+- 说明兼容性、测试或必要约束
+
+BREAKING CHANGE: 说明不兼容影响和迁移方式
+Refs: 已知工单号
+```
+
+示例：
+
+```text
+feat(data-push): 优化推送任务数据源与调度规则展示
+
+- 将英文星期转换为中文调度描述
+- 按数据源目录映射业务名称并补充单元测试
+```
+
+## 交付检查清单
+
+- [ ] type 与 scope 通过仓库 resolved commitlint 校验，完整消息经 stdin 校验退出码为 0。
+- [ ] scope 来自仓库枚举、包名或业务模块，未使用 `views`、`hooks`、`utils` 或文件名兜底。
+- [ ] 标题为英文 type/scope + ASCII 冒号 + 中文摘要，完整 header 不超过 72 字符。
+- [ ] 暂存区只包含当前原子提交的文件；lockfile 与对应 manifest 同提交。
+- [ ] 已运行与变更范围匹配的最小充分检查（相关测试、类型检查、lint）。
+- [ ] 提交后已核对 `git show --stat` 与 `git status --short`，并向用户报告 hash 与剩余改动。
+
+## 失败兜底策略
+
+- 无法区分 `feat`、`fix`、`refactor` 时继续检查需求和行为；仍有高影响歧义则询问用户，不自动降级为 `chore`。
+- hook 拒绝时按输出中的规则修正并重新校验，绝不使用 `--no-verify`。
+- 仓库 parser 或 hook 不支持标准破坏性标记时，不要绕过校验或静默删掉标记；报告规则冲突，并采用仓库明确批准的兼容方案。
+- 多个逻辑变更无法安全拆分时，先给出拆分方案并停止，不强行生成“大杂烩”提交。
+- 发现密钥或意外大文件时停止提交，报告具体路径并等待用户处理。

package/template/.agents/skills/frontend-commit/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "前端规范提交"
+  short_description: "分析真实改动并生成、校验前端项目的规范化 Git 提交"
+  default_prompt: "使用 $frontend-commit 检查当前前端改动并创建一条规范、原子的 Git 提交。"
+
+policy:
+  allow_implicit_invocation: true