create-yss-spec 3.3.0 → 3.3.3

package/template/.qoder/skills/domain-modeling/SKILL.md

@@ -1,58 +0,0 @@
----
-name: domain-modeling
-description: 梳理项目的业务词汇、责任范围和关键决策；讨论术语、编辑 CONTEXT.md 或记录 ADR 时使用。
----
-
-# 业务词汇与关键决策
-
-在设计过程中主动澄清业务词汇、责任范围和关键决策：质疑含糊说法，用边界与失败场景检验规则，并在结论稳定时写入词汇表或决策记录。仅仅读取 `CONTEXT.md` 不需要调用本技能；只有准备改变业务语言或关键决策时才使用。
-
-## File structure
-
-YSS repositories use exactly one root context file:
-
-```
-/
-├── CONTEXT.md
-├── docs/
-│   └── adr/
-│       ├── 0001-event-sourced-orders.md
-│       └── 0002-postgres-for-write-model.md
-└── src/
-```
-
-不要创建嵌套 `CONTEXT.md` 或 `CONTEXT-MAP.md`。多个业务责任区统一记录在根词汇表的 `适用业务责任区` 列中；内部仍使用稳定 `ContextId`。第一次确有必要记录 ADR 时再创建 `docs/adr/`。YSS 仓库缺少根 `CONTEXT.md` 属于合同错误，必须先修复再继续生命周期工作。
-
-## During the session
-
-### 对照词汇表检查冲突
-
-When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
-
-### 澄清含糊语言
-
-When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
-
-### 讨论具体业务故事
-
-讨论业务关系时，用具体故事和失败案例检验它们，促使用户明确概念边界、规则责任和例外结果。
-
-### Cross-reference with code
-
-When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
-
-### Update CONTEXT.md inline
-
-When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
-
-`CONTEXT.md` 不得包含实现细节。不要把它当作 Spec、草稿区或实现决策仓库；它只是一份稳定业务词汇表。
-
-### Offer ADRs sparingly
-
-Only offer to create an ADR when all three are true:
-
-1. **Hard to reverse** — the cost of changing your mind later is meaningful
-2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
-3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
-
-If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).

package/template/.qoder/skills/domain-modeling/agents/openai.yaml

@@ -1,3 +0,0 @@
-interface:
-  display_name: "Domain Modeling"
-  short_description: "Build and sharpen a domain model"

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

@@ -1,160 +0,0 @@
----
-name: file-export-download
-description: 指导 Vue3 YSS UI 微应用实现文件导出、报表下载、模板下载和附件下载，覆盖 OpenAPI binary 响应、Orval 生成方法检查、responseType blob 兜底、Blob 响应类型、Content-Disposition 文件名、handleBlobResponse、loading 与错误处理；当需求出现导出、下载、Excel、CSV、PDF、ZIP、Blob 或文件流时使用。
----
-
-# YSS 文件导出下载 Skill
-
-## 触发条件
-
-- 页面需要导出 Excel、CSV、PDF、ZIP、报表、密钥文件或其他二进制文件。
-- 页面需要下载导入模板、附件或后端动态生成的文件。
-- Orval 生成接口的返回值是 `Blob`，或业务调用需要配置 `responseType: 'blob'`。
-- 代码正在手写 `URL.createObjectURL`、解析 `Content-Disposition`、拼接文件名或调用 `downloadFileStream`。
-
-## 不适用场景
-
-- 仅上传文件，不包含模板下载或导出流程。
-- 下载公开静态 URL 且无需鉴权、请求参数和响应头文件名时，使用 `downloadFileFromUrl(url, fileName?)`。
-- 浏览器只需要预览远程 PDF/图片，不触发文件保存。
-
-## 必读依据
-
-- 通用接口规则：`../yss-api-integration/SKILL.md`。
-- 当前项目：`openapi/openapi.json`、Orval 配置、生成后的 API 方法和 `packages/src/api/mutator.ts`。
-- YSS Utils 文件下载能力：按下方检索顺序核对 `handleBlobResponse` 和 `downloadBlob`。
-
-## 文档检索
-
-1. MCP 可用时，先用 `search_docs` 查询 `handleBlobResponse 文件下载 Content-Disposition`，并读取命中的 `downloadBlob（/utils/download）` 文档。该能力属于工具函数，不强制调用面向组件别名的 `get_component_docs`。
-2. 搜索无结果时，调整关键词再次调用 `search_docs`；仅在 MCP 不可用、调用失败或仍无结果时，回退读取最新 `llms-full.txt` 的文件下载章节。文档版本与当前依赖不一致时，再核对 `packages/utils` 源码、CodeGraph 和真实导出。
-
-## 决策流程
-
-1. 在 OpenAPI 中定位导出接口，优先把成功响应声明为二进制媒体类型和 `format: binary`。
-2. 重新生成 API 后检查生成方法，而不是凭接口名称判断：
-   - 已包含 `responseType: 'blob'`：业务调用不必重复传第二参数。
-   - 未包含 `responseType: 'blob'`：业务调用必须传第二参数 `{ responseType: 'blob' }`。
-3. 检查 mutator 和全局错误处理器：Blob 成功响应必须保留 `{ data, headers }`；HTTP 4xx/5xx 的 Blob JSON 错误应由全局错误处理器解析并 reject。
-4. 在业务 hook 中设置 loading、防重复点击，调用生成 API，再执行 `handleBlobResponse(res.data, res.headers)`。
-5. 验证文件名、文件内容、错误响应和连续点击，不只验证浏览器出现了下载任务。
-
-> OpenAPI 标准通过响应 `content` 和 `format: binary` 表达二进制，不直接使用 Axios 的 `responseType` 字段。最终以 Orval 生成方法是否含 `responseType: 'blob'` 为判断依据。
-
-## 硬约束（禁止/必须）
-
-- 必须优先导入 `import { handleBlobResponse } from '@yss-ui/utils';` 处理接口文件流。
-- 必须调用 `handleBlobResponse(res.data, res.headers)`；它会自动兼容响应头大小写，并解析 RFC 5987 `filename*` 与普通 `filename`。
-- 第三个 `hasUtf8Encoding` 参数已弃用，禁止继续传递。
-- 生成方法缺少 Blob 配置时，必须在第二参数顶层传 `{ responseType: 'blob' }`；禁止放进 `headers`、请求 body 或查询参数。
-- 生成方法已包含 Blob 配置时，禁止为“保险”重复传相同配置；先保持 OpenAPI 契约和生成产物正确。
-- 禁止修改 Orval 生成文件补写 `responseType`，因为重新生成会覆盖；应修正 OpenAPI，或在业务调用第二参数临时兜底。
-- 禁止依赖 URL 中包含 `download/export` 的请求拦截器猜测响应类型；接口可能不按该名称命名。
-- 禁止在业务层重复实现 `getFileNameFromContentDisposition`、`downloadFileStream`、`URL.createObjectURL` 和 `<a download>` 流程。
-- 必须保留响应头；只取 `res.data` 会丢失服务端文件名。
-- Blob 接口失败时遵循全局 mutator 错误处理，禁止在 catch 中重复 `message.error`；成功下载后可提示 `message.success`。
-- 当前模板 mutator 只能识别“已解析 JSON 对象”的 `success === false`，不会自动检测 HTTP 200 Blob 内的业务错误；发现该契约时必须先修正后端状态码或 mutator，禁止把解析逻辑复制到每个 Hook。
-- 必须用独立 loading 状态防止重复导出，并在 `finally` 中恢复。
-- 不得默认传 `skipBusinessError` 或 `skipErrorHandler`；只有明确需要业务自定义错误体验时才使用。
-
-## OpenAPI 标准代码骨架
-
-```json
-{
-  "responses": {
-    "200": {
-      "description": "导出成功",
-      "headers": {
-        "Content-Disposition": {
-          "schema": { "type": "string" }
-        }
-      },
-      "content": {
-        "application/octet-stream": {
-          "schema": {
-            "type": "string",
-            "format": "binary"
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-根据文件类型可将媒体类型换成 `text/csv`、`application/pdf` 或 Excel 对应类型。跨域请求若读取不到文件名，后端还必须暴露 `Content-Disposition` 响应头。
-
-## 标准代码骨架
-
-### 生成方法已包含 responseType
-
-```typescript
-import { ref } from 'vue';
-import { handleBlobResponse } from '@yss-ui/utils';
-import { downloadAccessSecret } from '@/api/generated/quality';
-
-/** 微应用 mutator 返回的文件下载响应。 */
-type BlobDownloadResponse = {
-  data: Blob;
-  headers: Record<string, string>;
-};
-
-/** 文件下载进行中状态。 */
-const downloading = ref(false);
-
-/** 下载密钥文件。 */
-const downloadFile = async (key: string): Promise<void> => {
-  if (downloading.value) return;
-
-  downloading.value = true;
-  try {
-    const res = (await downloadAccessSecret(key)) as unknown as BlobDownloadResponse;
-    handleBlobResponse(res.data, res.headers);
-  } catch {
-    // mutator 已展示错误；此处只阻止 reject 继续向 UI 事件传播。
-  } finally {
-    downloading.value = false;
-  }
-};
-```
-
-### 生成方法缺少 responseType
-
-只改调用行，其他流程保持一致：
-
-```typescript
-const res = (await downloadAccessSecret(key, {
-  responseType: 'blob',
-})) as unknown as BlobDownloadResponse;
-```
-
-若 mutator 与 Orval 返回类型已经准确声明为 `{ data: Blob; headers: ... }`，直接使用生成类型，删除不必要的类型断言。
-
-## 响应约定
-
-- 后端成功响应应返回真实文件流，并设置 `Content-Disposition: attachment; filename*=UTF-8''...`。
-- mutator 对 Blob 成功响应返回 `{ data, headers }`，以便 `handleBlobResponse` 获取文件名。
-- HTTP 错误的 Blob JSON 由全局错误处理器解析并 reject，业务 Hook 不重复解析或提示。
-- HTTP 200 且 body 是 Blob 包装的业务错误时，当前模板不会自动 reject；必须修复契约或统一拦截器后再交付。
-- `handleBlobResponse` 找不到文件名时会使用 `download`；应优先补齐后端响应头，而不是在每个页面手写解析逻辑。
-
-## 交付检查清单
-
-- [ ] 已检查 OpenAPI 二进制响应声明和 Orval 生成方法。
-- [ ] 仅在生成方法缺少配置时，第二参数传入了 `{ responseType: 'blob' }`。
-- [ ] 已从 `@yss-ui/utils` 导入并调用 `handleBlobResponse(res.data, res.headers)`。
-- [ ] 未修改 Orval 生成文件，未重复实现文件名解析或浏览器下载逻辑。
-- [ ] Blob 成功响应保留了 `data` 与 `headers`，类型断言只位于 API 边界。
-- [ ] 已处理 loading、防重复点击和 `finally` 恢复。
-- [ ] 未在 catch 中重复业务错误 Toast。
-- [ ] 中文文件名、普通文件名和缺失文件名场景均已验证。
-- [ ] HTTP 错误的 Blob JSON 会 reject；如存在 HTTP 200 Blob 业务错误契约，已修正后端状态码或 mutator。
-- [ ] 下载文件可以正常打开，格式和内容与接口预期一致。
-
-## 失败兜底策略
-
-- 生成方法不支持第二参数时，先确认 Orval `options: true`；修正配置并重新生成，禁止手改生成文件。
-- `res.headers` 为空时，检查 mutator 是否错误地只返回 `data`，以及后端/CORS 是否暴露 `Content-Disposition`。
-- 下载到 JSON 错误文件时，先确认 HTTP 状态码：非 2xx 检查全局错误处理器，HTTP 200 检查后端契约并在 mutator 统一补齐；禁止把解析逻辑复制到每个业务 Hook。
-- 文件名始终为 `download` 时，优先修复后端 `Content-Disposition`；无法改后端时再评估统一扩展 YSS 下载工具。
-- 超大文件导致内存压力时，改用后端临时 URL、分片或流式下载方案，不强行把全部内容载入 Blob。

package/template/.qoder/skills/file-export-download/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "YSS 文件导出下载"
-  short_description: "规范 Orval Blob 导出、responseType 配置与文件下载处理"
-  default_prompt: "使用 $file-export-download 实现类型安全的文件导出下载，并正确处理 Blob、响应头和文件名。"

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

@@ -1,176 +0,0 @@
----
-name: formily-foundation
-description: 指导 YFormily 基础表单开发；当创建或修复普通单页表单、字段校验、提交链路、查询表单布局、scope 表达式或导入边界时使用。
----
-
-# Formily Foundation Skill
-
-## 触发条件
-
-- 创建或改造 `YFormily` 基础表单（字段、校验、提交）。
-- 修复表单导入路径、schema 层级、提交不触发等问题。
-- 实现普通单页表单，不含复杂联动或详情插槽。
-
-## 不适用场景
-
-- 复杂联动、副作用、跨字段逻辑：使用 `../formily-linkage-effects/SKILL.md`。
-- 查看态 detail 插槽和 mode 切换：使用 `../formily-mode-slot-detail/SKILL.md`。
-- 分步表单：使用 `../formily-step-flow/SKILL.md`。
-
-## 文档检索
-
-1. 当前会话可用 yss-ui MCP 时，先用 `get_component_docs` 查询 `YFormily` 的基础 Props、Methods 与 Schema 边界；实现字段布局、提交或校验失败时，再用 `get_demo` 获取 `formily/basic`、`formily/grid`、`formily/submit-failed` 等官方 Demo。
-2. MCP 查询未命中时先用 `search_docs/list_components` 校正名称；MCP 不可用、调用失败或校正后仍无结果时，才读取最新 `llms-full.txt`。若文档与当前项目依赖版本不一致，用当前源码和导出核验。
-
-## 硬约束（禁止/必须）
-
-- 业务生成代码统一从 `@yss-ui/components` 导入 `YFormily` 与 `ISchema`；`YssFormily` 仅作为历史兼容别名说明。
-- 禁止业务层导入 `@formily/antdv`、`@formily/antd*` UI 组件。
-- 必须使用三层结构：`FormLayout -> FormGrid -> 字段`，禁止字段直接挂在根节点或单独以 `FormGrid` 作为顶层布局。
-- `Submit` 必须传 `onSubmit`，否则不触发表单提交。
-- 标准业务列表/CRUD 查询区默认让 `YFormily` 只渲染字段；查询/重置按钮用外部 `YButton` 放在 `.xxx__search-actions`，由 hook 的 `handleSearch/handleReset` 控制分页重置和请求。
-- `AutoButtonGroup -> Submit/Reset` 仅用于纯 Formily 表单提交，不作为业务列表查询区默认方案。
-- 查询区禁止横向放“表单 + 按钮”后用大 `gap`、`align-items: flex-start` 或 `padding-top` 硬调位置；字段换行时按钮必须在搜索卡片右下角。
-- 横向表单必须显式设置 `FormLayout` 的 `labelWidth` 和 `labelAlign: 'right'`，抽屉/弹窗场景尤其不能让 label 宽度自适应。
-- `FormGrid` 默认保持响应式：`minColumns: 1`，通过 `maxColumns` 和 `minWidth` 控制宽屏列数；不要写 `minColumns: maxColumns` 固定列数，除非用户明确要求不响应式。
-- 查询表单常用 `labelWidth: 100~120`、`FormGrid { maxColumns: 3 或 4, minColumns: 1, minWidth: 260~360 }`，按钮行在表单外部右下角；抽屉/弹窗编辑表单常用 `labelWidth: 140`、`FormGrid { maxColumns: 2, minColumns: 1, minWidth: 320~360 }`。
-- 备注、说明等长字段必须用 `x-decorator-props.gridSpan` 占满整行，例如两列布局用 `gridSpan: 2`。
-- 下拉选择器（`Select`, `TreeSelect`, `Radio.Group` 等）异步数据源必须通过 `enum` 或 `x-reactions` / `field.dataSource` 注入，严禁写入 `x-component-props.options`（会导致 Formily 首次挂载空数组且后续不更新，产生首次打开弹窗显示“暂无数据”的 Bug）。
-- 事件表达式必须字符串化（`'{{ ... }}'`），并按组件语义使用事件名。
-- 只使用源码已公开的 Props 和实例方法；当前没有 `show-button-group`、`detail-as`、`validate`、`reset`、`clearValidate` 等 YFormily API。
-- Orval API 的网络错误及 `success === false` 业务错误已由 `mutator.ts` 统一 `message.error` 并 reject；提交 hook 禁止在 `else` 或 `catch` 中重复提示。
-- 客户端校验提示使用 `onFormSubmitValidateFailed`；禁止在 `onFormSubmitFailed` 或 `Submit.onSubmitFailed` 中调用 `message.error`，它们也会捕获 `onSubmit` 内的 API reject。
-- **Formily 表单校验规则（x-validator）防坑规范**：
-  - 必填文本字段必须声明 `whitespace: true`，即 `{ required: true, whitespace: true, message: '请输入xxx' }`，防止输入纯空格绕过前端校验。
-  - 自定义长度、格式和跨字段校验不得重复承担必填职责；函数式校验必须在空值时返回通过（如 `validator: (val) => { const str = (val || '').trim(); if (!str) return true; return validateContentLength(val) || true; }`），空值统一交由 `required` 报错，非空时才校验具体规则。
-  - 当前 YFormily 的 FormItem 适配层会在运行时归一化反馈：空值优先显示必填提示，非空值移除残留必填提示，多条相关消息只拼接一次。该兜底不替代正确的 Schema 校验职责拆分。
-- 分步需求默认走 `formily-step-flow`，不在本 skill 内给 `FormStep` 方案。
-
-## 标准代码骨架
-
-```vue
-<script setup lang="ts">
-import { YFormily, type ISchema } from '@yss-ui/components';
-
-/** 表单保存回调 Props。 */
-interface SaveFormProps {
-  onSave: (values: Record<string, any>) => Promise<void>;
-}
-
-/** 表单保存回调。 */
-const props = defineProps<SaveFormProps>();
-
-/** 校验通过后提交表单数据。 */
-const onSubmit = (values: Record<string, any>) => {
-  return props.onSave(values);
-};
-
-/** 基础表单 Schema。 */
-const schema: ISchema = {
-  type: 'object',
-  properties: {
-    layout: {
-      type: 'void',
-      'x-component': 'FormLayout',
-      'x-component-props': { layout: 'horizontal', labelWidth: 120, labelAlign: 'right' },
-      properties: {
-        grid: {
-          type: 'void',
-          'x-component': 'FormGrid',
-          'x-component-props': { maxColumns: 3, minColumns: 1, minWidth: 260 },
-          properties: {
-            name: { type: 'string', title: '名称', 'x-decorator': 'FormItem', 'x-component': 'Input', required: true },
-            submit: {
-              type: 'void',
-              'x-component': 'Submit',
-              'x-content': '提交',
-              'x-component-props': { onSubmit: '{{ onSubmit }}' },
-            },
-          },
-        },
-      },
-    },
-  },
-};
-</script>
-
-<template>
-  <YFormily :schema="schema" :scope="{ onSubmit }" />
-</template>
-```
-
-## 业务查询区布局
-
-```vue
-<template>
-  <YCard class="demo-page__search-card" :padding="16">
-    <div class="demo-page__search-content">
-      <div class="demo-page__search-form">
-        <YFormily v-model="queryModel" :schema="searchSchema" />
-      </div>
-      <div class="demo-page__search-actions">
-        <YButton type="primary" @click="handleSearch">查询</YButton>
-        <YButton @click="handleReset">重置</YButton>
-      </div>
-    </div>
-  </YCard>
-</template>
-```
-
-```less
-.demo-page {
-  &__search-content {
-    display: flex;
-    flex-direction: column;
-    align-items: stretch;
-    gap: 16px;
-  }
-
-  &__search-form {
-    width: 100%;
-    min-width: 0;
-
-    :deep(.ant-formily-form-item) {
-      margin-bottom: 0;
-    }
-
-    :deep(.ant-formily-form-grid) {
-      width: 100%;
-    }
-  }
-
-  &__search-actions {
-    display: flex;
-    width: 100%;
-    flex: 0 0 auto;
-    align-items: center;
-    justify-content: flex-end;
-    gap: 12px;
-  }
-}
-```
-
-## 交付检查清单
-
-- [ ] 导入来源和组件边界正确。
-- [ ] schema 三层结构完整。
-- [ ] 横向表单有固定 `labelWidth` 且 label 右对齐。
-- [ ] `FormGrid` 使用响应式列配置，未把 `minColumns` 固定成宽屏列数。
-- [ ] `Submit` 提交链路可用，校验可触发。
-- [ ] 只使用公开 Props/实例方法，未出现 `show-button-group`、`detail-as` 等旧式或虚构 API。
-- [ ] 业务列表查询/重置按钮在外部 `.xxx__search-actions`，按钮行独占下一行并右对齐；缩窄后不会贴在第一行字段旁。
-- [ ] label 宽度和右对齐已显式配置。
-- [ ] 包含可运行 `initial-values` 或 `v-model` 示例。
-- [ ] 未出现 `@formily/antdv` 业务层导入。
-- [ ] API 失败仅由 `mutator.ts` 统一提示，业务 `else`/`catch` 未重复 `message.error`。
-
-## 失败兜底策略
-
-- 若提交不触发：先检查 `Submit.x-component-props.onSubmit`。
-- 若字段不显示：先核对 `FormLayout/FormGrid/properties` 层级。
-- 若 API 调用 reject：只恢复 loading 或回滚局部状态，不重复弹出错误提示。
-- 若需求升级为联动/模式/分步：立即切换对应 skill，不在本 skill 内硬扩展。
-
-## 参考
-
-- 完整示例：`./references/examples.md`