create-yss-spec 2.2.0 → 2.2.1

package/template/.claude/skills/page-skeleton/examples/StandardListPage/index.vue

@@ -0,0 +1,91 @@
+<script setup lang="ts">
+import { onMounted, ref } from 'vue';
+import { Input as AInput } from 'ant-design-vue';
+import { YButton, YCard, YTable } from '@yss-ui/components';
+import { useTableHeight } from '@yss-ui/hooks';
+import { TABLE_COLUMNS, type QualityRuleItem } from './constant';
+import { useQualityRuleList } from './hooks/useQualityRuleList';
+import { useRuleActions } from './hooks/useRuleActions';
+
+defineOptions({ name: 'StandardListPage' });
+
+const emit = defineEmits<{
+  create: [];
+  edit: [row: QualityRuleItem];
+  view: [row: QualityRuleItem];
+}>();
+
+const tableAreaRef = ref<HTMLDivElement>();
+const { tableHeight, isReady } = useTableHeight(tableAreaRef, {
+  withPagination: true,
+  withToolbar: true,
+});
+const { tableData, loading, pagination, searchForm, fetchList, handlePageChange, handleSearch, handleReset } =
+  useQualityRuleList();
+const { actionConfig, handleCreate } = useRuleActions({
+  refreshList: fetchList,
+  onCreate: () => emit('create'),
+  onEdit: row => emit('edit', row),
+  onView: row => emit('view', row),
+});
+
+/** 查看规则详情。 */
+const handleRuleNameClick = (row: QualityRuleItem): void => {
+  emit('view', row);
+};
+
+onMounted(() => {
+  void fetchList();
+});
+</script>
+
+<template>
+  <div class="quality-rule-page">
+    <YCard class="quality-rule-page__search-card">
+      <div class="quality-rule-page__search-content">
+        <AInput
+          v-model:value="searchForm.ruleName"
+          class="quality-rule-page__keyword"
+          placeholder="请输入规则名称"
+          allow-clear
+          @press-enter="handleSearch"
+        />
+        <div class="quality-rule-page__search-actions">
+          <YButton @click="handleReset">重置</YButton>
+          <YButton type="primary" :loading="loading" @click="handleSearch">查询</YButton>
+        </div>
+      </div>
+    </YCard>
+
+    <YCard class="quality-rule-page__table-card">
+      <div ref="tableAreaRef" class="quality-rule-page__table-area">
+        <YTable
+          v-if="isReady"
+          :data="tableData"
+          :columns="TABLE_COLUMNS"
+          :loading="loading"
+          :height="tableHeight"
+          :action-config="actionConfig"
+          :toolbar-config="{ custom: true }"
+          pageable
+          v-model:pagination="pagination"
+          @page-change="handlePageChange"
+        >
+          <template #toolbar-right>
+            <YButton @click="fetchList">刷新</YButton>
+            <YButton type="primary" @click="handleCreate">新增质量规则</YButton>
+          </template>
+          <template #ruleName="{ row }">
+            <button class="quality-rule-page__rule-link" type="button" @click="handleRuleNameClick(row)">
+              {{ row.ruleName ?? '-' }}
+            </button>
+          </template>
+        </YTable>
+      </div>
+    </YCard>
+  </div>
+</template>
+
+<style scoped lang="less">
+@import url('./style.less');
+</style>

package/template/.claude/skills/page-skeleton/examples/StandardListPage/style.less

@@ -0,0 +1,49 @@
+.quality-rule-page {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  height: 100%;
+  min-height: 0;
+  gap: 12px;
+
+  &__search-content {
+    display: flex;
+    flex-direction: column;
+    gap: 12px;
+  }
+
+  &__keyword {
+    width: min(100%, 360px);
+  }
+
+  &__search-actions {
+    display: flex;
+    justify-content: flex-end;
+    gap: 8px;
+  }
+
+  &__table-card,
+  &__table-area {
+    flex: 1;
+    min-height: 0;
+  }
+
+  &__rule-link {
+    padding: 0;
+    color: var(--primary-color, #3371ff);
+    background: transparent;
+    border: 0;
+    cursor: pointer;
+
+    &:hover,
+    &:focus-visible {
+      color: var(--primary-color-hover, #4096ff);
+      text-decoration: underline;
+    }
+
+    &:focus-visible {
+      outline: 2px solid color-mix(in srgb, var(--primary-color, #3371ff) 35%, transparent);
+      outline-offset: 2px;
+    }
+  }
+}

package/template/.claude/skills/prototype-page-acceptance/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: prototype-page-acceptance
+description: 当用户提供原型截图、老项目路径、旧页面截图或要求按既有页面复刻业务页面时，指导先提取视觉和交互验收清单，开发后用截图/运行结果逐项对照，避免只实现字段而忽略布局、按钮、表格高度和控件类型。
+---
+
+# 原型页面还原验收 Skill
+
+## 触发条件
+
+- 用户提供原型图、截图、设计稿、旧项目 view/logic/service 路径。
+- 用户要求“参考老项目、照原型、复刻页面、保持和旧系统一致”。
+- 开发结果需要人工视觉对照，而不只是接口和类型正确。
+
+## 不适用场景
+
+- 纯逻辑修复、纯 API 对接、无 UI 改动。
+- 用户明确要求自由设计，不需要贴近旧页面。
+- 组件库内部能力开发，不涉及业务页面还原。
+
+## 硬约束（禁止/必须）
+
+- 开发前必须打开用户给出的旧项目 view 文件、相关 logic/service 文件和当前项目相近页面，不得只看接口。
+- 必须把截图/旧页面拆成验收清单：查询区布局、按钮位置、表格工具栏、表格高度/分页、操作列、弹窗/抽屉尺寸、表单 label 宽度和对齐、FormGrid 响应式、字段控件类型。
+- Vue3 + YSS UI 列表查询区默认验收“字段在上、查询/重置按钮独占下一行并右对齐”；缩放或窄屏导致字段换行时，按钮必须仍在搜索卡片右下角，不得贴在第一行字段旁。
+- 若截图里出现但需求文字没写的通用交互（查询/重置、表格列设置、新增按钮位置、分页器、抽屉底部按钮），默认按截图实现。
+- 不允许用“用户没说”跳过截图里明显存在的 UI；只有业务含义不明时才询问。
+- 开发后必须运行页面或至少完成类型/构建检查；可运行时必须截图对照首屏和关键弹窗/抽屉。
+- 交付说明必须列出“已对照原型的验收项”和“未能验证的项”。
+
+## 标准代码骨架
+
+```text
+原型验收清单：
+- 查询区：字段数量、FormGrid 响应式列数、label 固定宽度和右对齐、查询/重置按钮右下角位置，缩窄后按钮不贴第一行字段。
+- 表格区：YTable、toolbar-config.custom、#toolbar-right 新增按钮、分页、无底部大空白。
+- 操作列：按钮可见条件、更多菜单、删除气泡确认文案。
+- 抽屉/弹窗：响应式宽度、底部按钮、查看态只读、label 右对齐且宽度统一、缩窄时 2 列变 1 列、备注/长文本占满行。
+- 编辑表格：使用 YEditTable，列控件类型、可输入/多选、添加行/删除行、校验。
+```
+
+```text
+验收输出：
+- 通过：查询区三列栅格，查询/重置按钮独占下一行并右对齐；缩窄到字段两行或三行时按钮仍在搜索卡片右下角。
+- 通过：表格工具栏右侧为新增和列设置按钮，分页贴底显示，无大空白。
+- 通过：抽屉宽度使用 min(90vw, 1200px)，labelWidth 固定且右对齐，FormGrid 从 2 列响应式收缩为 1 列，查看态不显示保存。
+- 未验证：后端真实数据返回为空，仅用 mock/空态验证布局。
+```
+
+## 交付检查清单
+
+- [ ] 已读取旧项目 view/logic/service 或当前相近页面。
+- [ ] 已把截图中可见 UI 转成验收清单。
+- [ ] 查询/重置按钮右下角布局、表格工具栏、新增按钮、分页和空白高度已对照。
+- [ ] 抽屉/弹窗响应式、label 宽度和右对齐、FormGrid 换列、底部按钮已对照。
+- [ ] 编辑表格控件类型、可输入/多选、添加/删除已对照。
+- [ ] 已运行类型检查、构建或浏览器截图验证，并说明未验证项。
+
+## 失败兜底策略
+
+- 旧项目代码太复杂时，先提取最终 UI 结构和字段映射，再复用当前项目组件实现。
+- 截图与文字需求冲突时，优先按文字业务规则，UI 布局仍尽量按截图；冲突点写入交付说明。
+- 无法运行项目时，至少执行静态类型检查并逐项说明哪些视觉项未验证。

package/template/.claude/skills/theme-token-usage/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: theme-token-usage
+description: 指导 Vue3 YSS UI 微应用业务页面、公共组件、原型还原和主题修复使用可动态换肤的 CSS/Ant Design Token，覆盖主色、hover/active/selected/focus、状态色、中性色、透明色派生和暗色模式；当新增或修改 .vue、style.less、内联样式、TS 渲染配置、SVG 色值，或审查硬编码 #hex/rgb/渐变时使用。
+---
+
+# YSS UI 主题 Token 使用 Skill
+
+## 触发条件
+
+- 新增、重构或按原型实现 Vue3 业务页面、公共组件、布局、卡片、树、表格、表单、抽屉和详情页。
+- 修改 `.vue`、`.less`、`.css`、`.scss`、TS/TSX 渲染配置或 SVG 中的颜色、背景、边框、阴影、渐变。
+- 页面需要跟随主应用主题、JSP 预设主题、暗色模式或运行时主色切换。
+- 评审或修复 `#1677ff`、`#3371ff`、`rgb/rgba/hsl` 等硬编码色值。
+
+## 不适用场景
+
+- 只维护主题源文件中的默认值或主题预设，例如 `variables.less`、`store/theme.ts`、`config/themes.ts`。
+- 用户明确要求不可换肤的品牌插画、数据可视化固定色板或第三方资产原色；仍需在代码中注明固定色语义。
+- 只修改与视觉无关的类型、接口或纯业务逻辑。
+
+## 开发前检查
+
+1. 读取当前微应用的 `packages/src/styles/variables.less`、主题 store/config 和相近页面，确认真实 Token 名称与运行时同步逻辑。
+2. 确认主应用传入的 `colorPrimary` 最终是否同步到 Ant Design ConfigProvider、YSS CSS 变量和 VXE 变量。
+3. 搜索本次改动涉及的硬编码色值，覆盖 SFC style、`style.less`、内联 `style`、`:style`、TS 配置、SVG `fill/stroke`。
+4. 区分“主题消费代码”和“主题定义代码”；禁止机械替换主题源文件中的合法默认色板。
+
+> 变量在 `:root` 中声明，不代表它会随运行时主题更新。必须同时检查主题同步代码是否写入该变量。
+
+## Token 选择
+
+按以下优先级选值：
+
+| 语义 | 优先使用 | 兼容选择 |
+| --- | --- | --- |
+| 主色 | `var(--primary-color, #3371ff)` | `var(--yss-color-primary-6, #3371ff)` |
+| hover | `var(--primary-color-hover, #4096ff)` | `var(--yss-color-primary-5, #4096ff)` |
+| active | `var(--primary-color-active, #0958d9)` | `var(--yss-color-primary-7, #0958d9)` |
+| 成功/警告/错误/信息 | `--success-color` / `--warning-color` / `--error-color` / `--info-color` | 对应 `--yss-color-*-6` |
+| 正文/次要文字 | `--text-color` / `--text-color-secondary` | 使用项目已有语义 Token |
+| 容器/页面背景 | `--bg-color-container` / `--bg-color` | 使用项目已有语义 Token |
+| 边框/分割线 | `--border-color` / `--border-color-split` | 使用项目已有语义 Token |
+| 反色文字 | `--text-color-inverse` | 不直接写 `#fff` |
+
+需要主色透明背景、focus ring 或阴影时，从真实主色动态派生：
+
+```less
+background: color-mix(in srgb, var(--primary-color, #3371ff) 10%, transparent);
+box-shadow: 0 0 0 3px color-mix(in srgb, var(--primary-color, #3371ff) 15%, transparent);
+```
+
+仅当主题同步逻辑明确维护 `--primary-1` 时才可使用 `var(--primary-1)`。禁止用带蓝色 fallback 的 `var(--primary-1, rgba(...))` 冒充动态主题；变量未同步时，红色等主题仍会回落为蓝色。
+
+## 硬约束（禁止/必须）
+
+- 必须优先让 `YButton`、`YTable`、`YTree`、`YFormily` 和 Ant Design Vue 组件消费 ConfigProvider 主题；非必要不覆盖其主色样式。
+- 业务消费代码禁止直接写品牌蓝、主题红及其 hover/active/selected/focus 色阶，包括十六进制、`rgb/rgba/hsl`、渐变和阴影。
+- 必须使用语义 Token；禁止仅按“颜色长得接近”替换，例如把错误态改成主色。
+- `var()` fallback 必须与项目默认 Token 一致；fallback 只负责兼容，不得成为实际换肤来源。
+- 禁止在页面局部随意发明 `--primary-light` 等新变量。确需新增时，必须在统一主题源声明，并在运行时主题同步链路中更新。
+- 禁止对 CSS 变量使用 Less 编译期颜色函数，例如 `fade(@primary-color, 10%)`；`@primary-color` 指向 `var()` 时无法可靠计算。
+- 禁止写 `rgba(var(--primary-color), 0.1)`；十六进制 CSS 变量不能直接作为 `rgba()` 通道参数。
+- 固定数据可视化色板、品牌资产原色或遮罩色允许保留，但必须与换肤语义无关，并添加中文说明。
+- 新增交互样式时必须覆盖 default、hover、active、selected、focus、disabled 中实际存在的状态。
+
+## 标准代码骨架
+
+```less
+@import url('@/styles/variables.less');
+
+.module-card {
+  color: var(--text-color, rgba(0, 0, 0, 0.88));
+  background: var(--bg-color-container, #fff);
+  border: 1px solid var(--border-color-split, #f0f0f0);
+
+  &__link {
+    color: var(--primary-color, #3371ff);
+
+    &:hover {
+      color: var(--primary-color-hover, #4096ff);
+    }
+  }
+
+  &.is-selected {
+    color: var(--primary-color, #3371ff);
+    background: color-mix(in srgb, var(--primary-color, #3371ff) 10%, transparent);
+    border-color: var(--primary-color, #3371ff);
+  }
+
+  &:focus-visible {
+    outline: none;
+    box-shadow: 0 0 0 3px color-mix(in srgb, var(--primary-color, #3371ff) 15%, transparent);
+  }
+}
+```
+
+仅在 JS、图表或 Canvas 必须读取计算后色值时，优先使用 Ant Design Vue `theme.useToken()`；若消费微应用 CSS 变量，则通过 `getComputedStyle(document.documentElement)` 读取，不复制默认色板到业务常量。
+
+## 验证流程
+
+1. 扫描本次变更中的 `#hex`、`rgb/rgba`、`hsl/hsla`、渐变和 SVG 色值，逐项说明保留理由或替换为 Token。
+2. 至少使用默认主色和一个明显不同的主色（例如红色）验证页面。
+3. 检查文字、链接、图标、边框、背景、阴影以及 hover/active/selected/focus 状态是否同步变化。
+4. 项目支持暗色模式时，再验证正文、次要文字、容器背景和边框；不得只验证主色。
+5. 有原型截图时，主题适配与视觉还原必须同时通过，不能为像素接近而写死色值。
+
+## 交付检查清单
+
+- [ ] 已检查项目真实主题入口、Token 声明与运行时同步链路。
+- [ ] 业务页面未硬编码品牌色及其交互态色阶。
+- [ ] 主色透明态来自可动态更新的 Token，不依赖未同步的 `--primary-1` fallback。
+- [ ] 状态色、中性色、容器背景和边框使用正确语义 Token。
+- [ ] 已检查 SFC、Less、内联样式、TS 配置和 SVG，不只检查 `style.less`。
+- [ ] 已用至少两种差异明显的主题色验证实际效果。
+- [ ] 项目支持暗色模式时已完成暗色验收。
+- [ ] 保留的固定色值均有明确、合理的非换肤语义。
+
+## 失败兜底策略
+
+- 找不到 Token 时，先查项目 `variables.less`、主题 store/config 和 `llms-full.txt`；禁止猜测变量名。
+- 只有颜色值但没有语义 Token 时，先在统一主题源补充语义变量和运行时同步，再在页面消费。
+- 第三方组件不跟随主题时，优先通过 ConfigProvider/component token 或其官方 CSS 变量桥接；最后才使用受控的深度样式覆盖。
+- 浏览器目标不支持 `color-mix()` 时，在主题层生成并同步明确的透明态变量；不要在各页面散落固定透明色。

package/template/.claude/skills/theme-token-usage/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "YSS UI 主题 Token 使用"
+  short_description: "约束业务页面使用可动态换肤的主题 Token，禁止硬编码品牌色"
+  default_prompt: "使用 $theme-token-usage 检查并实现页面样式，确保主题色、状态色和明暗模式可动态切换。"

package/template/.claude/skills/vue3-best-practices/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: vue3-best-practices
+description: 在 Vue3 业务页面、组件和 composable 中规范响应式状态、组件通信、异步竞态与大数精度；实现或重构 Vue3 逻辑时使用。
+---
+
+# Vue3 Best Practices Skill
+
+## 触发条件
+
+- 业务页面出现响应式、组件通信、状态管理相关问题。
+- 需要重构复杂组件逻辑到更稳的 Composition API 模式。
+- 需要防止 `v-model`、`watch`、`reactive/ref` 常见误用。
+
+## 不适用场景
+
+- 纯样式调整，无状态逻辑修改。
+- 仅写提交信息，不涉及代码实现。
+- 仅做接口层封装，不涉及 Vue 组件行为。
+
+## 硬约束（禁止/必须）
+
+- 禁止直接修改 `props`，必须使用 `emit('update:xxx')`。
+- 禁止在模板层写复杂业务逻辑，必须下沉到 `computed` 或 hook。
+- 必须避免深层 watch 滥用，优先明确依赖源。
+- 必须对异步请求做取消或竞态保护，避免旧请求覆盖新状态。
+- 必须在复杂页面中拆 composable，禁止单文件耦合所有逻辑。
+- 导出函数、composable、接口、类型与常量必须使用中文 JSDoc。
+- 接口默认错误由 mutator 统一提示并 reject；业务逻辑只做状态恢复或错误转换，禁止在 `catch` 重复 `message.error`，除非请求显式设置了 `skipErrorHandler`。
+- 在 hook/computed/watch 等业务逻辑里使用接口返回的 number 字段（id、主键、金额、数量等）时，禁止用 `Number()`/`parseInt`/`parseFloat`/`+x`/`*1`/`~~` 做任何数字转换，一律按字符串透传与比较；确需高精度数值计算时用 `decimal.js`/`big.js` 以字符串入参。底层 json-bigint 已存为字符串保精度，详见 `../yss-api-integration/SKILL.md`「大数字与精度」。
+
+## 标准代码骨架
+
+```typescript
+const props = defineProps<{ modelValue: string }>();
+const emit = defineEmits<{ 'update:modelValue': [value: string] }>();
+
+const localValue = computed({
+  get: () => props.modelValue,
+  set: value => emit('update:modelValue', value),
+});
+
+const loading = ref(false);
+
+/** 请求数据并维护加载状态。 */
+const fetchData = async () => {
+  loading.value = true;
+  try {
+    await api();
+  } finally {
+    loading.value = false;
+  }
+};
+```
+
+## 交付检查清单
+
+- [ ] `props` 单向数据流未被破坏。
+- [ ] `v-model` 实现使用标准 `update:*` 事件。
+- [ ] 异步逻辑具备 loading 与异常处理。
+- [ ] 复杂逻辑已拆分到 composable。
+- [ ] 接口返回的 number 字段在逻辑中保持字符串透传，未被 `Number()`/`parseInt`/`+x` 等转换。
+- [ ] 模板表达式简洁，便于维护和测试。
+
+## 失败兜底策略
+
+- 响应式异常时，先定位是 `ref`/`reactive` 选型问题还是解构丢响应。
+- 双向绑定异常时，先检查 `emit` 事件名和参数签名。
+- 组件过重时，先抽离状态 hook，再处理视觉拆分。

package/template/.claude/skills/yedit-table-usage/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: yedit-table-usage
+description: 指导 YSS UI 业务页面使用 @yss-ui/components 的 YEditTable 实现可编辑表格、行内编辑、添加/删除行、下拉多选与可创建 tags、行级候选联动、表头筛选、校验和查看态；当需求出现编辑表格、明细行、扩展属性、可编辑列或 YEditTableColumn 时使用。
+---
+
+# YEditTable 使用
+
+## 触发条件
+
+- 需求包含可编辑表格、行内编辑、明细行、扩展属性、行级候选联动或表格校验。
+- 需要使用 `YEditTableColumn`、`validate()`、`addable`、`filterOptions` 或表头筛选。
+
+## 不适用场景
+
+- 主列表只展示和分页：使用 `../ytable-usage/SKILL.md`。
+- 表单主体不是表格：使用 `../yss-formily/SKILL.md`。
+
+## 实施流程
+
+1. 当前会话可用 yss-ui MCP 时，先用 `get_component_docs` 查询 `YEditTable` 的 Props、Events、Methods、`YEditTableColumn` 和操作列配置；需要添加行、多选/可创建下拉、行级联动或校验时，再用 `get_demo` 获取对应官方 Demo。
+2. MCP 工具不可用、调用失败或用 `search_docs/list_components` 校正后仍无结果时，才读取最新 `llms-full.txt`；若文档与当前项目依赖版本不一致，用当前源码和导出核验。
+3. 区分列编辑器、行级候选、表头筛选三种职责，再设计行类型和校验。
+4. 把行类型、列配置、新行工厂和纯操作配置放到 `constant.ts`；把数据状态、API、联动和事件放到 Hook。
+5. 显式实现 `@add`、查看态、删除确认与 `validate()` 链路，再对照真实返回类型检查提交。
+
+## 硬约束（禁止/必须）
+
+- 业务可编辑表格必须优先使用 `YEditTable`，从 `@yss-ui/components` 导入 `YEditTable`、`YEditTableColumn`、`YTableActionConfig`；不用 `a-table` 手搭编辑态。
+- 有 `component` 的列会由组件自动补齐 `edit-render`，业务列不需要重复写 `editRender: {}`。
+- `component: 'form-item-select'` 的 `props.multiple: true` 表示从现有候选中多选；`props.allowCreate: true` 会进入 Ant Design Vue `tags` 模式，值必须按数组建模。
+- 当前实现中 `multiple` 优先于 `allowCreate`，同时配置并不会得到“多选且可新建”。该需求必须明确说明当前能力缺口，使用自定义插槽或先增强组件，禁止继续生成错误 demo。
+- 行级候选使用 `rowOptionsFieldName` 指定的行字段，或列级 `filterOptions({ field, optionsMap, row })`；不修改全局 `optionsMap` 影响其他行。
+- `filterOptions` 只过滤编辑态候选；表头筛选使用 `filterable + filters + filterMethod`，文本面板优先使用 `filterRender: { name: 'VxeInput', props: {...} }`。
+- `addable` 只渲染添加按钮并发出 `add`，不会自动创建行。必须监听 `@add` 并修改 `v-model:data`；业务插入位置要与 `addPosition` 一致。
+- `disabled` 只禁用表格编辑，不会自动隐藏添加按钮和操作列。查看态必须同时设置 `:addable="false"` 并移除操作列/按钮。
+- 删除使用 `type: 'action' + actionConfig.buttons[].isConfirm`；不默认使用 `Modal.confirm`。
+- `validate()` 真实返回 `Promise<{ valid: boolean; errorMsg: Map<string, string> }>`。组件 ref 未就绪时不得误判为校验成功。
+- 弹窗/抽屉内使用添加按钮时，高度 Hook 配置 `withAddButton: true`；如果同时分页或开启工具栏，一并开启对应偏移。
+- API 失败由 `mutator.ts` 统一提示并 reject。Hook 中不写 `success === false` 分支，不在 `else/catch` 重复 `message.error`；清理状态放在 `finally`。
+
+## 标准代码骨架
+
+```typescript
+import type { YEditTableColumn, YTableActionConfig } from '@yss-ui/components';
+
+/** 扩展属性行。 */
+export interface ExtRow {
+  id?: string;
+  _rowKey: string;
+  extName?: string;
+  extValues?: string[];
+  memo?: string;
+}
+
+/** 可编辑表格列。 */
+export const EDIT_COLUMNS: YEditTableColumn[] = [
+  {
+    field: 'extName',
+    title: '扩展属性',
+    minWidth: 220,
+    component: 'form-item-select',
+    props: { placeholder: '请选择扩展属性' },
+    customRule: (value, _row, _field, all) => {
+      if (!value) return { errMsg: '扩展属性不能为空' };
+      if (all.filter(item => item.extName === value).length > 1) return { errMsg: '扩展属性不能重复' };
+      return {};
+    },
+  },
+  {
+    field: 'extValues',
+    title: '扩展值',
+    minWidth: 240,
+    component: 'form-item-select',
+    props: { multiple: true, placeholder: '请选择扩展值' },
+    customRule: value =>
+      Array.isArray(value) && value.some(item => String(item).length > 100)
+        ? { errMsg: '单个扩展值最多 100 个字符' }
+        : {},
+  },
+  {
+    field: 'memo',
+    title: '备注',
+    minWidth: 240,
+    component: 'form-item-input',
+    props: { placeholder: '请输入备注' },
+    customRule: value => (String(value ?? '').length > 200 ? { errMsg: '最多 200 个字符' } : {}),
+  },
+  { type: 'action', title: '操作', width: 100, fixed: 'right' },
+];
+
+/** 表格字典数据；实际项目可由 Hook 响应式提供。 */
+export const EDIT_OPTIONS_MAP = {
+  extName: [
+    { label: '类型', value: 'type' },
+    { label: '级别', value: 'level' },
+  ],
+  extValues: [
+    { label: '默认', value: 'default' },
+    { label: '扩展', value: 'extended' },
+  ],
+};
+
+/** 创建前端新行。 */
+export const createEmptyRow = (): ExtRow => ({
+  _rowKey: `temp-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  extValues: [],
+});
+
+/** 创建带删除确认的操作配置。 */
+export const createActionConfig = (onDelete: (row: ExtRow) => void): YTableActionConfig => ({
+  buttons: [
+    {
+      value: 'delete',
+      label: '删除',
+      type: 'link',
+      isConfirm: true,
+      confirmProps: { title: '是否确认删除此条数据？', okText: '确定', cancelText: '取消' },
+      click: ({ row }) => onDelete(row),
+    },
+  ],
+});
+```
+
+```vue
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { YEditTable } from '@yss-ui/components';
+import { createActionConfig, createEmptyRow, EDIT_COLUMNS, EDIT_OPTIONS_MAP, type ExtRow } from './constant';
+
+/** 组件模式。0-新增，1-编辑，2-查看。 */
+interface Props {
+  mode: 0 | 1 | 2;
+}
+
+const props = defineProps<Props>();
+const rows = ref<ExtRow[]>([]);
+const tableRef = ref<InstanceType<typeof YEditTable>>();
+const readonly = computed(() => props.mode === 2);
+const columns = computed(() => (readonly.value ? EDIT_COLUMNS.filter(column => column.type !== 'action') : EDIT_COLUMNS));
+const actionConfig = createActionConfig(row => {
+  rows.value = rows.value.filter(item => item._rowKey !== row._rowKey);
+});
+
+/** 处理组件 add 事件，显式更新 v-model:data。 */
+const handleAddRow = () => {
+  rows.value = [...rows.value, createEmptyRow()];
+};
+
+/** 校验全部编辑行。 */
+const validateRows = async (): Promise<boolean> => {
+  if (!tableRef.value) return false;
+  const { valid } = await tableRef.value.validate();
+  return valid;
+};
+</script>
+
+<template>
+  <YEditTable
+    ref="tableRef"
+    v-model:data="rows"
+    :columns="columns"
+    :action-config="actionConfig"
+    :options-map="EDIT_OPTIONS_MAP"
+    :row-config="{ keyField: '_rowKey', useKey: true }"
+    :table-config="{ editConfig: { trigger: 'click', mode: 'row', autoClear: false } }"
+    :disabled="readonly"
+    :addable="!readonly"
+    add-btn-text="添加一行"
+    add-position="bottom"
+    @add="handleAddRow"
+  />
+</template>
+
+<style scoped lang="less">
+@import './style.less';
+</style>
+```
+
+## Select 值类型边界
+
+```typescript
+/** allowCreate 对应 tags 模式，字段按数组存储。 */
+interface CreatableRow {
+  tags?: string[];
+}
+
+const creatableColumn: YEditTableColumn = {
+  field: 'tags',
+  title: '标签',
+  component: 'form-item-select',
+  props: { allowCreate: true, placeholder: '请选择或输入标签' },
+};
+```
+
+## 表头筛选
+
+```typescript
+const textFilterColumn: YEditTableColumn = {
+  field: 'columnName',
+  title: '目标列名称',
+  component: 'form-item-input',
+  filterable: true,
+  filters: [{ data: '' }],
+  filterMethod: ({ option, cellValue }) =>
+    String(cellValue ?? '').toLowerCase().includes(String(option?.data ?? '').trim().toLowerCase()),
+  filterRender: { name: 'VxeInput', props: { clearable: true, placeholder: '请输入关键词' } },
+};
+```
+
+- 远程筛选监听 `@filter-change`，并设置 `filterMethod: () => true` 禁用本地二次筛选。
+- 切换数据源或新增行后，可调用 `tableRef.value?.getTableInstance()?.clearFilter()`。
+- 只在面板高度定制时使用 `#<field>-filter`；修改 `option.data` 后调用 `updateFilterOptionStatus(option, !!option.data)` 同步状态。
+
+## 交付检查清单
+
+- [ ] `addable/@add/v-model:data/addPosition` 形成真实新增闭环。
+- [ ] `allowCreate` 和 `multiple` 未被错误组合，行字段类型与 Select 模式匹配。
+- [ ] 查看态同时禁用编辑、隐藏添加按钮和移除操作列。
+- [ ] `validate()` 按 `{ valid, errorMsg }` 处理，组件 ref 未就绪时不提交。
+- [ ] API Hook 没有重复 `message.error`，前端临时 key 不传给后端。
+
+## 失败兜底策略
+
+- 添加按钮无反应时，先确认已监听 `@add` 并更新 `v-model:data`，不继续调整 `addPosition`。
+- 查看态仍能删除/添加时，移除操作列并将 `addable` 设为 `false`，不只依赖 `disabled`。
+- 可创建多选与字段类型冲突时，回到 `allowCreate => tags 数组`、`multiple => 现有候选多选` 的真实实现；当前组合能力不足时明确报告。
+- API 联动失败时在 `finally` 恢复行级 loading，不捕获后重复 `message.error` 或继续使用失败结果。

package/template/.claude/skills/yss-api-integration/SKILL.md

@@ -1,11 +1,13 @@
 ---
-name: api-integration
+name: yss-api-integration
 description: Guide AI to correctly use Orval-generated API clients in Vue 3 micro-applications. This skill must be used whenever the user needs backend API integration, including list queries, CRUD actions, detail loading, submit flows, or API refactoring. It covers type-safe API imports, request/response mapping, and especially standardized useRequest integration patterns (manual/run/runAsync, pagination parameters, unified error handling, loading state, and success callbacks).
 ---
 
 # API 集成 Skill
 
-目录与锁文件身份是 `yss-api-integration`；Agent 发现名与 Router 闭包键是 `api-integration`。二者指向同一技能，注册表以 alias 对齐。
+本目录是 API 集成的 canonical 技能；历史名称 `api-integration` 仅通过注册表和 Router alias 解析，不再维护第二份内容。
+
+目录、frontmatter、注册表 ID 和 Router canonical 闭包键均为 `yss-api-integration`；历史名称 `api-integration` 只在注册表和 Router alias 表中解析为本技能。
 
 ## 📋 目标
 
@@ -56,6 +58,14 @@ packages/src/api/
 
 ## 🚀 使用步骤
 
+## YSS canonical execution rules
+
+- 先检查当前生成文件、`mutator.ts` 和冻结的 OpenAPI JSON 派生证据，不根据示例猜测导出名或响应形状。
+- 普通 JSON 请求中，`success === false` 已由 mutator reject；业务 Hook 不得再写 `if (res?.success)` 或重复 `message.error`。
+- loading 在 `finally` 中恢复；只有显式传入 `skipBusinessError` 或 `skipErrorHandler` 时，才允许实现局部错误交互。
+- 文件流必须保留 `{ data, headers }`，交给 `file-export-download` 的 `handleBlobResponse`；不得修改生成文件。
+- 长整型 ID 按冻结契约保持字符串，不得用 `Number`、`parseInt` 或位运算恢复为 number。
+
 ### 1. 查看可用 API
 
 打开 `packages/src/api/generated/api.ts` 查看所有可用的 API 函数。

package/template/.claude/skills/yss-components/SKILL.md

@@ -12,7 +12,7 @@ description: Use when YSS Vue 页面涉及布局、YTable、YEditTable、YFormil
 - YSS UI 组件文档：`http://192.168.164.27:3200/components`（组件契约以该手册为准；本技能依据 2026-08-18 可见内容整理）
 - 本地引用索引：`references/frontend-docs.md`
 
-本技能只负责页面组件、布局和交互呈现规范。请求、分页参数、接口映射交给 `yss-hook` 或 `api-integration`；完整页面生成流程交给 `yss-page-module-development`；表格/树高度细节交给 `yss-use-table-height` 或 `yss-use-tree-height`。
+本技能只负责页面组件、布局和交互呈现规范。请求、分页参数、接口映射交给 `yss-hook` 或 `yss-api-integration`；完整页面生成流程交给 `yss-page-module-development`；表格/树高度细节交给 `yss-use-table-height` 或 `yss-use-tree-height`。
 
 组件文档与当前项目的已验证用法冲突时，先检查当前项目代码和依赖版本，再决定是否迁移；不得把上游 Ant Design Vue、vxe-table、Univer 或 Monaco 的未验证 API 当作 YSS 顶层契约。