create-yss-spec 3.0.0 → 3.1.0

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

@@ -1,227 +0,0 @@
----
-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/.hermes/skills/yss-antd-design/SKILL.md

@@ -1,34 +0,0 @@
----
-name: yss-antd-design
-description: Use when 原型设计或高保真构建需要查询 Ant Design v6 设计语言、组件 API/demo/token/semantic，或落盘 AntD CLI 证据。不用于前端代码落地（改用 yss-ui）、Vue 生产 API、生命周期批准、安装官方 antd skill，或替代 yss-prototype-stage。
----
-
-# YSS Ant Design 事实
-
-只服务原型设计与高保真构建。把官方 `@ant-design/cli`、`design.md`、MCP 与 LLMs.txt 收成可追溯的事实引擎。阶段合同仍是 `yss-prototype-stage`。前端代码落地一律改用 `yss-ui`，不要继续调用本技能。
-
-## 何时使用
-
-- 已进入 `yss-prototype-stage` 的高保真产出前后，需要 Ant Design v6 组件 / token / demo / semantic / 上游 `design.md` 事实。
-- 需要写入 `prototype-evidence.yaml` 的 AntD 段。
-
-不要用本技能：前端实现、Vue / Ant Design Vue 生产代码、批准门禁、生成页面流、安装官方 `antd` skill，或运行 `antd setup`。进入实现切片后停用本技能，改走 `yss-ui`。
-
-## 步骤
-
-1. 检测 CLI：优先已安装的 `antd`，否则用 `npx -y @ant-design/cli`。记录实际 CLI 版本。不要在模板源执行 `npm install -g`。
-2. 读项目 `docs/design/design.md` 与 `docs/design/tokens/*`。
-3. 选定 `<target_antd_version>`（项目已选的 v6；未选则先查再记录，不得依赖空仓库自动检测）。此后每次知识查询都传同一版本。
-4. 设置 `ANTD_NO_AUTO_REPORT=1`。一律 `--format json`，对外说明用 `--lang zh`。
-5. 查询官方 `design.md`，再按选用组件跑 `info` / `demo` / `token` / `semantic`。命令矩阵见 `references/cli-matrix.md`。
-6. 把 JSON 路径写入证据清单。字段与 lint 适用范围见 `references/evidence.md`。
-7. 上游默认与项目 token 冲突时，以项目覆盖为准，并标记 `project_override_reviewed`。
-
-## 硬规则
-
-- 禁止凭记忆写 Ant Design v6 API。
-- 禁止 `antd setup`、`npx skills add ant-design/ant-design-cli`，以及把官方 `skills/antd` 拷进 `.agents/skills`。
-- 禁止把官方 `design.md` 的默认色、圆角、间距写回项目实现或覆盖项目 token。
-- 禁止在前端代码落地、垂直切片实现或 `yss-ui` 任务中调用本技能。
-- 禁止把 React props / demo / hook 当作 `yss-ui` 或 Ant Design Vue API。
-- MCP 与 `llms-full.txt` 不是门禁证据。边界见 `references/boundaries.md`。

package/template/.hermes/skills/yss-antd-design/references/boundaries.md

@@ -1,30 +0,0 @@
-# 边界与官方资料
-
-官方文档只提供 React `antd` 事实，不提供 YSS 阶段合同。入口对照：
-
-| 官方资料 | 本技能用法 |
-|---|---|
-| https://ant.design/docs/react/for-agents-cn | 了解 CLI / skill / MCP / LLMs 分层。不要把其中的 “安装 skill” prompt 写进 `AGENTS.md` |
-| https://ant.design/docs/react/cli-cn | 命令与参数的权威说明 |
-| https://ant.design/docs/react/design-md-cn | 上游 `design.md` 定位。项目覆盖是 `docs/design/design.md` |
-| https://ant.design/docs/react/mcp-cn | MCP 是 IDE 加速，8 个知识工具不含 `lint` |
-| https://ant.design/docs/react/llms-cn | CLI 不可用时的降级目录。不要默认注入 `llms-full.txt` |
-| https://ant.design/design.md | 与 `antd design.md` 同一份 v6 上游默认 |
-
-## 与其他技能
-
-- `yss-prototype-stage`：阶段顺序、评审、浏览器验证、用户确认。本技能只回写 AntD 事实段。
-- `yss-design-system`：项目风格与 token 规范。本技能查询上游事实，不得改项目 token。
-- `product-design:index`：Codex 视觉产出。本技能不替代它，也不使用 `antd-page-generator`。
-- `yss-ui`：前端代码落地的唯一 UI 入口。进入实现后不得再查本技能或 `@ant-design/cli` 的 React API。
-- 官方 `antd` skill：不安装、不锁定、不投影。
-
-## MCP 与 LLMs.txt
-
-开发者本机可以运行 `npx -y @ant-design/cli mcp --version <target_antd_version> --lang zh`，但：
-
-- 不把 `.cursor/mcp.json` 提交为模板默认。
-- 不把 MCP 调用记录当成 `evidence.antd-cli-validation`。
-- `antd-page-generator` 不是原型阶段入口。
-
-CLI 不可用时，可用 `https://ant.design/llms.txt` 定位单组件 `.md`，并在证据里写明降级原因。恢复 CLI 后补 JSON 落盘。

package/template/.hermes/skills/yss-antd-design/references/cli-matrix.md

@@ -1,38 +0,0 @@
-# CLI 命令矩阵
-
-运行时入口：已安装的 `antd`，或 `npx -y @ant-design/cli`。记录实际 CLI 版本。知识查询必须带 `--format json`、`--lang zh` 和同一 `<target_antd_version>`。
-
-官方命令说明：https://ant.design/docs/react/cli-cn
-
-## 允许（原型 / 设计事实）
-
-| 命令 | 用途 |
-|---|---|
-| `antd design.md --version <target_antd_version> --lang zh --format json` | 上游默认 Light 主题。只对 antd v6 发布 |
-| `antd list --version <target_antd_version> --format json` | 组件选型 |
-| `antd info <Component> --version <target_antd_version> --format json` | props / 类型 / 默认值 |
-| `antd demo <Component> [name] --version <target_antd_version> --format json` | 可运行 demo 源码（React/TSX） |
-| `antd token <Component> --version <target_antd_version> --format json` | 组件或全局 token |
-| `antd semantic <Component> --version <target_antd_version> --format json` | `classNames` / `styles` 结构 |
-| `antd doc <Component> --version <target_antd_version> --lang zh --format json` | 需要完整文档时 |
-| `antd changelog <v1> <v2> [Component] --format json` | 仅当版本差异影响当前决策 |
-
-`design.md` 对 v5 返回 `UNSUPPORTED_VERSION_FEATURE`。空仓库不传 `--version` 时的回退版本不要假设；必须写进证据。
-
-## 条件允许
-
-| 命令 | 条件 |
-|---|---|
-| `antd lint <tsx-or-src> --format json` | 产物是 React/TSX 源码。HTML 原型不得当作通过 |
-| `antd doctor` / `antd usage` / `antd migrate` | 仅已登记的 React + `antd` 实现仓 |
-| `antd env --format json` | 排障需要环境快照时 |
-
-## 默认禁止
-
-| 命令 | 原因 |
-|---|---|
-| `antd setup` | 会写入 `.agents/skills/antd` 和 `AGENTS.md`，绕过 `skills-lock.json` |
-| `npx skills add ant-design/ant-design-cli` | 同上，安装官方 skill |
-| `antd bug` / `antd bug-cli` | 与 YSS Ticket 无关。保持 `ANTD_NO_AUTO_REPORT=1` |
-| `antd upgrade` | 不得在模板源或未授权时改动全局 CLI |
-| `antd mcp` 作为证据采集 | MCP 调用默认不落盘，见 `boundaries.md` |

package/template/.hermes/skills/yss-antd-design/references/evidence.md

@@ -1,30 +0,0 @@
-# AntD 事实证据
-
-目标文件：`docs/.scratch/<feature>/verification/prototype-evidence.yaml`，字段以 `docs/design/templates/prototype-evidence-template.yaml` 为准。本文件只说明如何填 AntD 段。
-
-## 必填
-
-- `antd.cli_command`：实际调用的可执行文件，`antd` 或 `npx -y @ant-design/cli`。
-- `antd.cli_version`：本轮 `antd -V` 或等价输出，禁止写死模板默认值。
-- `antd.target_antd_version`：本轮全部知识查询使用的同一 v6 版本。
-- `antd.queries.design_md`：`antd design.md ... --format json` 的落盘路径。
-- `antd.queries.components[]`：每个选用组件的 `info_ref` / `demo_ref` / `token_ref` / `semantic_ref`。
-- `design_baseline.project_design_ref`：`docs/design/design.md`。
-- `design_baseline.project_override_reviewed`：上游默认与项目 token 已对照。
-- `prototype_stack.actual_antd_version`：原型 lockfile 中的实际 React `antd@6.x`，必须与 `antd.target_antd_version` 一致。
-- `visual_semantic_mapping.components[]`：记录 v6 semantic role、项目 Token、React 原型组件、生产 YSS/Ant Design Vue 4.x 目标与 React-only API 隔离结论。
-
-JSON 输出存为相邻文件，证据清单只引用路径。不要把整份 `llms-full.txt` 或 MCP 对话贴进清单。
-
-## lint
-
-`antd lint` 只对可解析的 React/TSX 源码有规则命中。HTML 原型会出现空 issues（假绿）或 `skippedFiles` / `parse-error` / `partial: true`。
-
-CLI JSON 只能证明查询事实，不能单独证明原型消费了目标版本或完成了 Vue/YSS 映射。`gate.prototype-verified` 还必须通过 `yss-prototype-stage/scripts/prototype-contract.mjs` 的项目与 schema v2 证据校验、Design QA、浏览器和无障碍验证。
-
-| 产物 | `lint_applicable` | 做法 |
-|---|---|---|
-| `docs/.scratch/<feature>/design/prototypes/index.html` | `not-applicable` | 写 `lint_reason: html-prototype`；`lint_ref` 可空；`lint_passed` 保持 `false`，不得改成 `true` |
-| React/TSX 原型源 | `true` | 对变更文件跑 `antd lint --format json`，保存输出；无 issue 才把 `lint_passed` 设为 `true` |
-
-浏览器验证仍由 `yss-prototype-stage` 采集，不在本技能宣布 `gate.prototype-verified` 通过。

package/template/.hermes/skills/yss-antd-design/scripts/validate-frontmatter.mjs

@@ -1,46 +0,0 @@
-#!/usr/bin/env node
-import { readFile } from "node:fs/promises";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-export function validateFrontmatter(text) {
-  const match = /^---\n([\s\S]*?)\n---/.exec(text);
-  if (!match) throw new Error("Invalid SKILL.md frontmatter block");
-  const fields = new Map();
-  for (const line of match[1].split("\n")) {
-    if (!line.trim()) continue;
-    const index = line.indexOf(":");
-    if (index < 0) throw new Error(`Invalid frontmatter line: ${line}`);
-    fields.set(line.slice(0, index).trim(), line.slice(index + 1).trim());
-  }
-  const keys = [...fields.keys()].sort();
-  if (keys.join(",") !== "description,name") throw new Error(`Expected keys ['description', 'name'], got ${JSON.stringify(keys)}`);
-  const name = fields.get("name");
-  const description = fields.get("description");
-  if (name !== "yss-antd-design") throw new Error("Invalid skill name: " + name);
-  if (!description || description.length > 1024) throw new Error("Description must be present and <= 1024 chars");
-  if (!/yss-ui|官方 antd skill|yss-prototype-stage/.test(description)) {
-    throw new Error("Description must exclude frontend landing via yss-ui, official antd skill, and stage-contract takeover");
-  }
-  return name;
-}
-
-export function validateSetupBan(text) {
-  if (!/禁止 `antd setup`/.test(text)) throw new Error("SKILL.md must forbid antd setup");
-  if (!/npx skills add ant-design\/ant-design-cli/.test(text)) throw new Error("SKILL.md must forbid official skill installer");
-}
-
-async function main() {
-  const skill = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "SKILL.md");
-  try {
-    const text = await readFile(skill, "utf8");
-    const name = validateFrontmatter(text);
-    validateSetupBan(text);
-    console.log(`${name} frontmatter ok`);
-  } catch (error) {
-    console.error(error.message);
-    process.exitCode = 1;
-  }
-}
-
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main();

package/template/.hermes/skills/yss-antd-design/scripts/validate-frontmatter.test.mjs

@@ -1,27 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-import { validateFrontmatter, validateSetupBan } from "./validate-frontmatter.mjs";
-
-const valid = `---
-name: yss-antd-design
-description: Use when 原型设计。不用于前端代码落地（改用 yss-ui）、安装官方 antd skill，或替代 yss-prototype-stage。
----
-
-# body
-- 禁止 \`antd setup\`、\`npx skills add ant-design/ant-design-cli\`
-`;
-
-test("accepts the required skill frontmatter", () => {
-  assert.equal(validateFrontmatter(valid), "yss-antd-design");
-});
-
-test("rejects missing exclusion branches in description", () => {
-  assert.throws(
-    () => validateFrontmatter("---\nname: yss-antd-design\ndescription: Use when querying antd.\n---\n"),
-    /exclude frontend landing/
-  );
-});
-
-test("rejects a skill that does not forbid official setup", () => {
-  assert.throws(() => validateSetupBan("# no setup ban"), /forbid antd setup/);
-});

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

@@ -1,185 +0,0 @@
----
-name: yss-api-integration
-description: 指导在 Vue3 业务列表、表单、详情和操作 Hook 中集成 Orval API，覆盖真实生成产物选择、mutator 响应契约、错误提示、加载状态、请求选项和长整型精度；当页面对接查询、新增、编辑、删除、详情或文件流接口时使用。
----
-
-# API 集成 Skill
-
-本目录是 API 集成的 canonical 技能；历史名称 `api-integration` 仅通过注册表和 Router alias 解析，不再维护第二份内容。
-
-目录、frontmatter、注册表 ID 和 Router canonical 闭包键均为 `yss-api-integration`；历史名称 `api-integration` 只在注册表和 Router alias 表中解析为本技能。
-
-## 📋 目标
-
-帮助 AI 正确使用基于 **Orval** 生成的 API 客户端：
-
-- ✅ 正确导入 API 函数
-- ✅ 统一错误处理与 Toast 门禁
-- ✅ Loading 状态管理
-- ✅ 长整型 ID 精度保持
-- ✅ TypeScript 类型安全
-
-## 🔍 前置条件
-
-1. **契约状态已明确**：
-   - 已有生成客户端：可以直接集成。
-   - 新增或变更 API：必须先在 `docs/.scratch/<feature>/api/<feature>.yaml` 形成 OpenAPI Draft，经工程基线 / 架构 / Spec Delta 设计和设计审查后 Freeze。冻结的 OpenAPI YAML 是唯一权威，JSON 仅为它的受控派生物。
-   - 如果接口尚未冻结、JSON 派生记录缺失或生成函数不存在，先回到 `yss-product-lifecycle` / `yss-openapi-governance`，不要手写临时路径、DTO 或响应结构。
-2. **API 已生成**：在目标前端实现仓库中，按其既有的手动代码生成命令（例如 `pnpm generate:api`）刷新 API；本 Harness 不配置、不执行该命令，也不把它加入 CI。
-3. **了解 OpenAPI**：查看 Freeze 记录、JSON 派生记录和 `openapi/openapi.json` 了解接口定义；不得把 JSON 或生成 TypeScript 当成可手改的源文件。
-
-## 契约输入与生成链
-
-客户端重新生成只能走下列受控链路：
-
-```text
-冻结的 OpenAPI YAML
-  → 锁定的 redocly bundle 生成 openapi.json
-  → 原样物化到目标前端
-  → 既有前端代码生成流程（由目标项目手动执行）
-  → 类型检查与调用方验证
-```
-
-1. 读取 `yss-openapi-governance` 产出的 OpenAPI Freeze 记录和 `docs/.scratch/<feature>/api/<feature>-json-export.md`；确认 YAML SHA-256、JSON SHA-256、Redocly CLI 版本、lockfile 引用和 JSON 校验均通过。治理 JSON 的唯一产物路径是 `docs/.scratch/<feature>/api/<feature>.json`。
-2. JSON 导出由 `yss-openapi-governance` 负责。`api-integration` 只接受该 skill 留下的派生记录；记录中的锁定 `redocly bundle` 命令是治理导出证据，不是前端集成任意重跑的入口。
-3. **受控交接**：若前端实现仓库需要本地输入，批准的 Cross-repo 子合同或项目脚本只能将上述治理 JSON 原样物化为 `<frontend>/openapi/openapi.json`；物化后的 SHA-256 必须与派生记录一致。禁止从 URL、Draft YAML、后端运行时或任意本地文件临时替换输入。
-4. `api-integration` 只核对 JSON 派生记录、交接路径和 SHA-256，并把原始 JSON 交给既有前端代码生成流程；本 Harness 不读取或修改目标前端的生成器配置，不在此仓库执行生成，也不建立生成 CI 门禁。若 JSON SHA 与派生记录不一致，停止交接并回到治理流程。
-5. 目标前端项目在需要时手动运行其既有生成命令、类型检查和受影响组件 / API 测试；将实际命令、结果、生成输入 SHA 和偏离写入 `YSS Skill Execution Result`。
-
-## 真实 mutator 响应契约
-
-当前微应用模板的 `mutator.ts` 行为是：
-
-- 普通 JSON 响应直接返回 `response.data`。
-- 当 JSON 对象显式包含 `success === false` 时，拦截器调用全局业务错误提示并 `Promise.reject(error)`。
-- HTTP 4xx/5xx 和网络错误由全局 `handleErrorResponse` 提示后继续 reject。
-- Blob 成功响应返回 `{ data, headers }`；HTTP 错误中的 Blob JSON 由全局错误处理器解析。
-- 当前 mutator **不会**检测 HTTP 200 Blob 内包装的 `success === false` JSON；这种契约必须先改为合理的 HTTP 错误状态，或在 mutator 中统一补齐，不得让每个业务 Hook 各自解析。
-
-## 硬约束（禁止/必须）
-
-- 禁止对普通 Orval 请求结果使用 `if (res?.success)` 或 `if/else` 判断业务成功；`success === false` 已被 reject，`await` 继续执行即为成功。
-- 禁止在 `else` 或 `catch` 中重复调用 `message.error`、`notification.error` 或项目的错误 Toast。
-- Hook 可在 `catch` 中清理局部数据、记录错误状态或阻止继续执行，但不重复展示错误。
-- 只有显式传入 `skipBusinessError: true` 或 `skipErrorHandler: true` 时，业务代码才能在 `catch` 中实现自定义错误交互。
-- 成功 Toast 必须放在 `await` 之后，不得放在 `finally` 或无条件分支中。
-- loading 必须在 `finally` 中恢复；需要阻止未处理 reject 时，在 Hook 内捕获并仅维护状态。
-
-## Orval 生成与导入
-
-生成链路通常为：
-
-```bash
-pnpm generate:api
-# orval → schema cleanup → 可选的导出扁平化 → prettier
-```
-
-必须先打开生成文件确认导出：
-
-- 已存在模块级具名 API 函数时，优先具名导入。
-- 如果当前产物只导出 `getXxxApi()` 工厂，在**模块顶层**创建一次实例；禁止每次 Hook 初始化或每次请求都重新调用工厂。
-- 不得根据文档示例假定工厂一定名为 `getApi()`；Orval `title` 配置会影响真实名称。
-- 请求/响应 DTO 必须从当前生成的 `schemas` 导入，禁止重复声明。
-
-## 标准代码骨架
-
-以微应用的真实 `getApiApi()` 产物为例：
-
-```typescript
-import { reactive, ref } from 'vue';
-import { getApiApi } from '@/api/generated/quality';
-import type { QualityBusinessRuleVO, QualityRulePage } from '@/api/generated/quality/schemas';
-
-const { pageQualityRule } = getApiApi();
-
-/** 管理质量规则列表请求和分页状态。 */
-export const useQualityRuleList = () => {
-  const loading = ref(false);
-  const dataList = ref<QualityBusinessRuleVO[]>([]);
-  const query = reactive<QualityRulePage>({ pageIndex: 1, pageSize: 20, ruleName: '' });
-  const total = ref(0);
-
-  /** 加载规则列表。 */
-  const fetchData = async (): Promise<void> => {
-    loading.value = true;
-    try {
-      const res = await pageQualityRule(query);
-      dataList.value = res.data ?? [];
-      total.value = res.totalCount ?? 0;
-    } catch {
-      dataList.value = [];
-      total.value = 0;
-    } finally {
-      loading.value = false;
-    }
-  };
-
-  return { loading, dataList, query, total, fetchData };
-};
-```
-
-> 如果所在项目已生成 `pageQualityRule` 具名导出，直接导入该函数，删除上面的工厂实例行。
-
-## 长整型与数值类型
-
-`JSONbig({ storeAsString: true })` 会把超出 JavaScript 安全整数范围的整数保留为字符串；**不会把所有普通 number 都转成字符串**。分页页码、状态值、普通小数和安全范围整数仍可按真实类型计算。
-
-硬约束：
-
-- ID、雪花 ID、长整型业务键一旦运行时为字符串，必须原样透传和比较，禁止 `Number()`、`parseInt()`、一元 `+` 或位运算转回 number。
-- 优先修正 OpenAPI，将可能超过 `Number.MAX_SAFE_INTEGER` 的 ID 声明为 `string`；不得以 `as unknown as number` 长期掩盖错误契约。
-- 普通数值计算按生成类型执行；金额或高精度计算使用 `decimal.js`/`big.js` 并以字符串入参。
-
-```typescript
-// ❌ 长整型 ID 会丢失精度
-await detailQualityRule(Number(row.id));
-
-// ✅ 保持 ID 的字符串契约
-await detailQualityRule(row.id);
-
-// ✅ 页码等普通数值仍使用 number
-query.pageIndex = pagination.current;
-```
-
-## 自定义请求选项
-
-Orval 配置 `options: true` 后，生成方法的最后一个可选参数会透传给 `customInstance`。必须先检查当前生成函数签名。
-
-- `skipBusinessError?: boolean`：仅跳过 `success === false` 的全局业务提示，请求仍 reject。
-- `skipErrorHandler?: boolean`：跳过业务错误与 HTTP/网络错误的全局提示，请求仍 reject。
-- Axios 原生选项：`responseType`、`headers`、`timeout`、`signal`、`onUploadProgress`、`onDownloadProgress` 等均在该参数顶层传入。
-
-```typescript
-try {
-  await addQualityRule(values, { skipBusinessError: true });
-} catch (error) {
-  // 只有显式跳过全局业务提示时，才在此实现自定义错误交互。
-  showCustomError(error);
-}
-
-const controller = new AbortController();
-await pageQualityRule(query, { signal: controller.signal, timeout: 120000 });
-```
-
-## 交付检查清单
-
-- [ ] 已检查 Orval 配置、生成文件和 mutator 真实实现。
-- [ ] 使用生成 DTO，未手写重复接口类型。
-- [ ] 优先使用真实具名导出；只有工厂时仅在模块顶层创建一次。
-- [ ] 没有 `if (res?.success)` 冗余分支，没有在 `else/catch` 重复错误 Toast。
-- [ ] 成功后逻辑仅在 `await` 成功后执行，loading 在 `finally` 恢复。
-- [ ] 长整型 ID 保持字符串，普通 number 没有被错误当成字符串。
-- [ ] 特殊错误交互已显式传入 skip 选项，未默认关闭全局处理。
-- [ ] 文件流已按 `file-export-download` 核对 Blob、响应头和错误链路。
-
-## 失败兜底策略
-
-- 生成导出与 skill 示例不同时，以生成文件为准并更新生成脚本，禁止绕过类型检查猜名调用。
-- 接口字段不稳定时，在 Hook API 边界做最小映射，不把兼容逻辑散落到模板。
-- HTTP 200 Blob 业务错误时，先修复后端状态码或 mutator 统一解析，禁止在业务 Hook 重复实现。
-
-## 阶段 7 合同
-
-- 只消费冻结的 OpenAPI YAML 派生出的 JSON、生成客户端和批准后的 `Slice Implementation Contract`；实现中的半成品 backend 不得作为稳定 source of truth。
-- 客户端重新生成属于 `controlled-generation`；页面请求状态、错误处理、权限和用户交互属于 `behavior-tdd`。
-- 必须按统一 `YSS Skill Execution Result` 返回生成客户端引用、调用文件、组件/API 测试、实际 pnpm 验证结果、偏离和 `new_impacts`；发现缺失路径或 schema 变化时暂停并回生命周期。

package/template/.hermes/skills/yss-api-integration/agents/openai.yaml

@@ -1,5 +0,0 @@
-version: 1
-interface:
-  display_name: "YSS API Integration"
-  short_description: "Vue 3 接口对接、useRequest 与分页状态规范"
-  default_prompt: "Use $yss-api-integration to wire Orval-generated APIs into a Vue 3 page with typed requests, loading state, and error handling."